Conversation
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueComment |
Contributor
Reviewer's GuideThis documentation-only PR proposes RFCs 0013–0017 for optional states, typed inputs, owned cleanup, Ninja-backed contention, and maturity policies, then lays out a dependency-driven phases 20–25 implementation roadmap with extensive verification and Cuprum migration canaries while preserving the existing shallow-end workflow. Flow diagram for optional feature adoptionflowchart TD
Start[Existing unannotated manifest] --> Choose{Adopt an optional contract?}
Choose -->|No| Legacy[Keep legacy commands, vars, scheduling, and clean semantics]
Choose -->|Typed input| Inputs[Validate selected task inputs]
Choose -->|Contention class| Pool[Lower selected edges to a Ninja pool]
Choose -->|Managed state| State[Verify or explicitly prepare state]
Choose -->|Owned artefact| Cleanup[Preview and delete declared paths]
Inputs --> Result[Feature works without neighbouring annotations]
Pool --> Result
State --> Result
Cleanup --> Result
Result --> Policy{Optional scoped maturity policy?}
Policy -->|No| Default[Empty default policy; no missing-annotation warnings]
Policy -->|Yes| Check[Semantic-linter coverage check]
Check --> Outcome[Warn or fail only selected subjects]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add five proposed RFCs for managed states and functional probes, optional typed task inputs, owned artefacts and cleanup, named contention classes, and opt-in maturity policies. Add roadmap phases 20 to 25 with explicit dependencies and acceptance tasks, preserving the unchanged quickstart and independently usable enhancements.
Run the canonical `make fmt` over the seven new documents so they match the repository Markdown conventions: prose re-wrapped to 80 columns and tables padded to mdtablefix-canonical form. No wording changed. `mdtablefix --wrap` moved the `#592` issue reference to the start of a line, where CommonMark parses `#592` as an ATX level-1 heading, so markdownlint reported MD022 and MD025 against the roadmap. The committed text carried the same latent mis-parse; only the rewrapping made it visible. Backtick the reference, matching the existing convention for issue identifiers in `docs/`. Co-Authored-By: Claude Code <noreply@anthropic.com>
leynos
force-pushed
the
docs/progressive-enhancement-rfcs
branch
from
September 19, 2026 11:46
8cf987b to
cdbe3cc
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Owner
Author
|
@coderabbitai Please investigate the cause of the following issue using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix: Seek a systemic fix rather than tactical. Ask yourself, can this happen again or happen elsewhere? If so, think about a long term fix of the underlying issue. |
This comment was marked as resolved.
This comment was marked as resolved.
RFC 0013 to 0020 are reserved by the 6.1.1 child-RFC split plan (PR #697) for the Ansible stdlib filter RFCs, which puts this set in collision at 0013 to 0017. Nothing above RFC 0012 is merged, and the style guide forbids renumbering after publication, so resolve the overlap now by moving this set above #697's ceiling. Rename the five files and update every reference in the two documents that cite them. The change is a pure number substitution: each file is byte-identical to its predecessor once the digits are normalised back. Gates: make fmt (no-op), check-fmt, markdownlint and nixie all pass. Co-Authored-By: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add five Proposed RFCs (0021–0025) and an implementation roadmap for optional orchestration contracts:
Add
docs/roadmap-progressive-enhancement.mdwith phases 20 to 25, 17 steps, and 34 implementation tasks, including explicit dependencies, verification work, and Cuprum migration canaries. Link every new document fromdocs/contents.mdwithout changing existing index content or renumbering existing roadmap tasks.Preserve the shallow end
The unchanged quickstart is an explicit compatibility and release-acceptance fixture. Ordinary variables, legacy command semantics, and unannotated actions remain supported destinations, not deprecated migration stages.
Each feature must be independently usable. Adopting one state, typed input, cleanup root, or contention class must not force annotations onto neighbouring actions or aggregates. Default maturity policy is empty, with no new missing-annotation warnings. Inspection must not trigger new probes, installation, or preparation, and command text must not implicitly acquire state, ownership, or scheduling semantics.
Reuse the existing structured runner, OrthoConfig/profile/metadata machinery, bundle parameter validation, semantic-linter inventory, and Ninja scheduler. Named execution contexts remain a compatible future integration point, not an undeclared sixth prerequisite.
State and cleanup boundaries
Separate
require_state(verification only),ensure_state(at most one authorized preparation on definite non-readiness), andprepare_state(explicit preparation followed by verification). Built-in presence checks do not claim package-set integrity. Preparation evidence never substitutes for a fresh mutable-state check.Optional Nagios-style probes map exits 0/1/2/3 to ready/degraded/not-ready/unknown. Unknown results, crashes, and timeouts never authorize automatic repair. The proposal specifies operator-capped deadlines and output limits, process-tree cleanup, and explicit external-code trust without claiming a read-only or network sandbox.
Scoped cleanup begins with exact paths and explicitly owned directory trees, not unrestricted wildcard deletion. Preview and deletion share one capability boundary. State/ownership integrity leases protect cooperating invocations; invocation-local Ninja pools remain a separate concurrency mechanism, not CPU quotas or semantic ordering.
Scope
Documentation only: seven files, no runtime implementation, schema changes, CI changes, or accepted ADRs. Proposed syntax and public command extensions require acceptance and version allocation before implementation. Referencing issue #592 identifies the shared semantic-analysis owner; this PR does not complete that implementation.
Validation
docs/contents.mdGit blob SHA, confirming existing index content is preserved byte-for-byte.These checks do not establish Netsuke schema/compiler validity or runtime correctness for the proposed features.
Numbering
RFC 0013–0020 are reserved by the 6.1.1 child-RFC split plan (PR #697) for the Ansible stdlib
filter RFCs, which put an earlier draft of this set in collision at 0013–0017. The set was
therefore renumbered to 0021–0025, clearing #697's ceiling so the two can land in either
order. The renumber is a pure number substitution: each file is byte-identical to its
predecessor once the digits are normalised back.
Repository gates
All deterministic gates were run on the rebased head
cdbe3cc7and pass:make check-fmt/tmp/check-fmt-netsuke-docs_progressive-enhancement-rfcs.outmake lint/tmp/lint-netsuke-docs_progressive-enhancement-rfcs.outmake typecheck/tmp/typecheck-netsuke-docs_progressive-enhancement-rfcs.outmake test/tmp/test-netsuke-docs_progressive-enhancement-rfcs.outmake markdownlint/tmp/markdownlint-netsuke-docs_progressive-enhancement-rfcs.outmake nixie/tmp/nixie-netsuke-docs_progressive-enhancement-rfcs.outmake testran 3218 nextest tests (0 failed, 5 skipped) plus doctests.make lintran cargo doc,Clippy, both Whitaker packages, Ruff, Pylint, the df12 house lints, ambrleaks, interrogate,
yamllint and actionlint with zero warnings.
make fmtwas run and is committed.None of the gates contains a Mermaid fence;
make nixiepassing means the repository's otherdiagrams validated, not that these documents are diagram-checked.
The static checks above still do not establish Netsuke schema/compiler validity or runtime
correctness for the proposed features: the RFCs propose syntax the compiler does not yet accept.
Summary by Sourcery
Document an optional orchestration roadmap that adds progressive contracts while preserving Netsuke’s existing shallow-end workflows.
New Features:
Enhancements:
Documentation:
Tests:
Chores:
References