From 147264ec50bed7dbae92647635d35d288eba6289 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Tue, 13 Oct 2026 09:58:31 +0300 Subject: [PATCH 01/11] docs(design): slices, project gate rules and user acceptance tests (draft) Draft for the process owner's decisions (USER:2026-10-13:slices-gates-uat). Co-Authored-By: Claude Opus 5.5 --- design/2026-10-13-slices-gates-uat.md | 215 ++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 design/2026-10-13-slices-gates-uat.md diff --git a/design/2026-10-13-slices-gates-uat.md b/design/2026-10-13-slices-gates-uat.md new file mode 100644 index 0000000..437b020 --- /dev/null +++ b/design/2026-10-13-slices-gates-uat.md @@ -0,0 +1,215 @@ +# Slices, project gate rules and user acceptance tests + +Status: draft for the process owner's decisions. Nothing here is normative +until `PROCESS.md` and the skills say it. + +Source: `USER:2026-10-13:slices-gates-uat` — "we are testing too often and +deeply in RDD-process, it's wasting time … bring concept of slice of work to +regular process … abstract out the human gates to separate +rdd-human-gates.md file … introduce another step … user-acceptance-tests", +with the customer problems below kept in mind. + +## The customer problems this must solve + +| # | Problem met | Where it came from | +|---|---|---| +| P1 | Work that is live in production cannot be closed: completion accepts only a merge to the default branch. | NextPath, `REQ-COURSE-001`, 2026-10-12 | +| P2 | Bookkeeping resets reviews: adding test citations moved fingerprints, staled passing reviews and asked for new approvals (six re-approvals and two extra reviews in one sprint). | Our sprint of 2026-10-09 | +| P3 | Evidence is assembled by hand: three RED commits, their runs and the GREEN run collected per requirement. | NextPath observation 3 and 8 | +| P4 | Full verification and review run per item, so a small package of related changes pays for many reviews, many full suites and many completion gates. | Process owner, this request | +| P5 | One process for everyone: a team cannot say "this kind of decision the AI may take", short of an autopilot grant with an end date. | Process owner, this request | +| P6 | The loop ends at "DONE" in the store; nobody gets a document saying what was built and how to check it by hand. Production state and process state are not shown together. | NextPath observations 6 and 7; this request | +| P7 | Preparation refuses or blocks for reasons that do not stop work. | NextPath; BACKLOG-TOOL-481/482/493/498/500/509 | + +## What exists today (25d85d6) + +- **Sprint** exists only in §Autopilot (`PROCESS.md:496-677`) and + `skills/rdd-autopilot`: the period an autopilot grant covers, ended by a + date, the human, or the scope being done. Work inside is a "connected + journey" built in batches (one RED commit and its GREEN per batch), one + cold-review pass per journey, full verification deferred to closeout, one + independent review and one completion page at the end, answered item by + item. No code knows the word; the server has no sprint record. +- **"Slice" is already used** for "the working code a batch lands" + (`PROCESS.md:550` and nearby; `rdd-autopilot` 79, 91, 132-133). +- **The regular loop tests and reviews per item:** upper RED per UR scenario, + lower RED per SR clause, focused and proportional gates per clause cycle, + full verification at each phase exit, up to two cold-review rounds per Epic + or SR, an independent code review and a completion gate per Epic. The + server enforces the per-SR part: RED before IN_PROGRESS, a passing lower + trace before IN_REVIEW, current evidence before completion + (`core/rdd/reconcile.ex`). +- **Units of work:** Epic, single SR, small-change lane (with lane batches at + completion), named sets for baselines. A work selection holds one Epic or + one SR; nothing groups several Epics as one package. +- **Human gates** are defined in `PROCESS.md` §Gates (280-438) and the phase + skills, and enforced in server code (`Governance.class`, + `Lifecycle.gate_edges`, `require_approving_human_answer`). The only + per-workspace knobs are cascade mode and lane authorizations. Every answer + the server stores is recorded as a human's, so "the agent answers entry + under a grant" is a convention the record cannot show. +- **The end:** completion review, delivery, reconciliation, the completion + gate, DONE. No acceptance-test guide, no test plan for a tester, no + release-facing summary per change. Evidence kinds include `manual` and + `browser_verification`. + +## 1. Slices + +**Definition.** A slice is the set of Epics and requirements a developer is +delivering as one logical package. It has a name and members; it has no +dates. It starts when the developer opens it and ends when the developer +closes it. It may be one requirement. It replaces "sprint" everywhere, and +autopilot becomes a way of running a slice (section 2), not a separate +period. + +**Iterative.** Members can be added while the slice is open. Each addition is +reviewed when it is written to the store — a review of the addition and its +effect on the slice, not a re-review of the slice. + +**What happens once per slice instead of once per item** + +| Activity | Today | With slices | +|---|---|---| +| Planning cold review | up to two rounds per Epic or SR | one review of the slice plan at the start; one narrow review per addition | +| Entry approval | one gate per Epic or SR | one per slice, plus one per addition — or none, by the project's gate rules | +| Red-first | upper RED per scenario, lower RED per clause, a commit pair per clause cycle | per connected batch, as autopilot does now: one RED commit with a failing assertion for every clause in the batch, then its GREEN | +| Tests while building | focused + proportional + full at phase exits | focused tests per batch only | +| Full verification | each phase exit | once, at slice end, at the delivered revision | +| Independent code review | per Epic | once per slice, over the whole change | +| Completion | one gate per Epic or SR | one page per slice, answered item by item | +| Acceptance-test guide | none | one per slice (section 3) | + +**Fingerprints and staleness (P2).** Reviews and approvals pin the slice, not +each member. An edit that does not change intent — test citations, evidence +links, wording the reviewer marked as a note — does not reopen the slice's +review. An edit that changes intent reopens review for that member only, as +an addition does. This needs the review fingerprint to be separate from the +write fingerprint (the cold review of `EPIC-CLI-DELIVERY-PATH`, finding +F-DELIVERY-R1-01, showed that reusing one value for both loses writes). + +**Small work keeps working.** A one-requirement slice is today's single-SR +loop with one review and one completion; the small-change lane becomes a +gate rule ("a change of class X needs no human entry") rather than a separate +lane. + +**Renames.** The existing "slice" (code a batch lands) becomes **increment**. +"Sprint", "sprint end" and "the sprint's working record" become slice, slice +end and the slice record. Gap records name the slice. + +**Store.** A slice is a work selection of a new kind `slice` whose members +are Epics and requirements, with one packet aggregate over them and one +entry and completion gate subject (the lane batch's per-member approve and +reject, generalised). Per-requirement evidence and traces stay as they are, so +what the server enforces per SR still holds — only its timing moves to the +slice's batches. + +## 2. Project gate rules — `process/rdd-human-gates.md` + +**Idea.** The process names the decision points (gates) and what each must +carry — brief, evidence, prerequisites. A project file says, per gate, who +decides: a human, or the agent under a stated rule. The kit installs a +default file equal to today's rules. Autopilot is a second preset file: the +agent decides entry and recorded assumptions, completion stays with the +human. A customer edits their copy in a pull request. + +**Shape (sketch).** + +```markdown +# Human gates — + +- **Decided:** USER:: + +| Gate | Decided by | When the agent may decide | Always a human when | +|---|---|---|---| +| Candidate confirmation | human | — | — | +| Slice entry | agent | the slice's plan review passed with no open material finding | the change touches auth, payments, existing data or an external contract | +| Addition to an open slice | agent | its narrow review passed | as above | +| Slice completion | human | — | — | +| Demotion | human | — | — | +| Product decision during build | agent (recorded assumption) | reversible and inside the slice | as above | +``` + +**Honesty.** A gate the agent decides is recorded as the agent's decision, +naming the rule row that allowed it and the human whose file it is. Today the +server stamps every answer as human; it must learn an agent answerer and +check the rule. Without that, the file is advice, not enforcement. + +**Store.** The file is pushed to the store as the System's gate policy with a +`USER:` source (the shape of `cascade_mode` and lane authorizations), and the +server's gate checks read it. The CLI shows the active rules at session start. + +**Floors.** Some things stay outside any project file because they are not +gates of this process: merging, deploying and releasing are human acts in the +project's own tools. + +## 3. User acceptance tests + +**A new last step per slice.** After the slice's full verification and before +its completion page, the agent writes the **acceptance-test guide** for a +human tester: + +1. What changed, in product language, per user requirement. +2. Where to test it: environment, revision, build, test data, sign-in. +3. Step-by-step manual checks per user scenario, with the expected result. +4. What the automated tests already cover, per acceptance criterion, with the + run that proves it. +5. An acceptance-criteria table: criterion → automated / manual / not + covered → result. +6. Known gaps, assumptions taken during the slice, and what is out of scope. + +The tester's results are recorded as evidence (`manual` or a new +`acceptance` kind) against the criteria. The completion page links the guide +and shows its results next to the automated evidence, and — on a deploy path — +which revision runs where (P6). + +**Store.** The guide is a slice packet section (`acceptance_guide`), so it is +versioned with the slice, reviewable and readable through the CLI; +`process complete` refuses a slice without it unless the gate rules say the +project does not use acceptance tests. + +## How the customer problems land + +| Problem | Answered by | +|---|---| +| P1 completion only on merge | the declared integration path (`EPIC-CLI-DELIVERY-PATH`), carried into slice completion | +| P2 bookkeeping resets reviews | slice-level pins, intent changes reviewed per member, separate review fingerprint | +| P3 hand-assembled evidence | batch REDs (one run per batch); test-report evidence (planned follow-on) | +| P4 too much testing and review | section 1: full tests, code review and completion once per slice | +| P5 one process for everyone | section 2: project gate rules, autopilot as a preset | +| P6 no tester-facing end, no production view | section 3: acceptance-test guide with deployment facts | +| P7 preparation blocks | `EPIC-CLI-DELIVERY-PATH` REQ-CROSS-551/552 | + +## Order of work + +1. **Process text** (req-driven-dev): slices and the renames; §Gates split + into the process's gate definitions and the default gate rules file; the + autopilot preset; the acceptance step and `rdd-acceptance` skill; file-state + shapes for the slice record, the gate rules file and the guide. +2. **CLI**: slice selection and membership, slice enter/complete, showing the + gate rules, writing and reading the guide — first working on top of + today's per-Epic records where possible. +3. **Server**: the `slice` work-selection kind and aggregate, the gate policy + and the agent answerer, the guide packet section and the acceptance + evidence kind. + +Each of 2 and 3 is product work and goes through the loop. + +## Decisions for the process owner + +- **D1 — red-first inside a slice.** Keep red-first per connected batch + (recommended: every clause still gets a failing assertion before code, + but one RED commit and one GREEN per batch), or drop red-first evidence and + keep only the slice-end full run? +- **D2 — floors.** Is there anything a project's gate rules may not hand to + the agent (recommended: completion of a slice that touches auth, payments, + existing data or an external contract stays human in the default and + autopilot presets, but a project may still change it)? +- **D3 — acceptance tests and completion.** Is the tester's sign-off required + before the slice can complete (recommended: required when the project's + gate rules say so; the default file requires the guide but not the + sign-off), or is the guide only delivered alongside? +- **D4 — the rename.** Today's "slice" (code a batch lands) becomes + "increment" — or another word? +- **D5 — `EPIC-CLI-DELIVERY-PATH`.** Build it now on today's process (its + test-citation part split off and absorbed into section 1's separate review + fingerprint), or fold it into the first slice built under the new process? From 247c2b4dee11e96ad03e116dcd4d30554b36aec1 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Tue, 13 Oct 2026 10:07:48 +0300 Subject: [PATCH 02/11] docs(design): record the process owner's decisions on slices, gates and acceptance tests USER:2026-10-13:slices-gates-uat-as-recommended. Co-Authored-By: Claude Opus 5.5 --- design/2026-10-13-slices-gates-uat.md | 39 +++++++++++++-------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/design/2026-10-13-slices-gates-uat.md b/design/2026-10-13-slices-gates-uat.md index 437b020..8cd9ed6 100644 --- a/design/2026-10-13-slices-gates-uat.md +++ b/design/2026-10-13-slices-gates-uat.md @@ -1,7 +1,7 @@ # Slices, project gate rules and user acceptance tests -Status: draft for the process owner's decisions. Nothing here is normative -until `PROCESS.md` and the skills say it. +Status: decided (see Decisions); not yet normative — `PROCESS.md` and the +skills change in the next step. Source: `USER:2026-10-13:slices-gates-uat` — "we are testing too often and deeply in RDD-process, it's wasting time … bring concept of slice of work to @@ -194,22 +194,19 @@ project does not use acceptance tests. Each of 2 and 3 is product work and goes through the loop. -## Decisions for the process owner - -- **D1 — red-first inside a slice.** Keep red-first per connected batch - (recommended: every clause still gets a failing assertion before code, - but one RED commit and one GREEN per batch), or drop red-first evidence and - keep only the slice-end full run? -- **D2 — floors.** Is there anything a project's gate rules may not hand to - the agent (recommended: completion of a slice that touches auth, payments, - existing data or an external contract stays human in the default and - autopilot presets, but a project may still change it)? -- **D3 — acceptance tests and completion.** Is the tester's sign-off required - before the slice can complete (recommended: required when the project's - gate rules say so; the default file requires the guide but not the - sign-off), or is the guide only delivered alongside? -- **D4 — the rename.** Today's "slice" (code a batch lands) becomes - "increment" — or another word? -- **D5 — `EPIC-CLI-DELIVERY-PATH`.** Build it now on today's process (its - test-citation part split off and absorbed into section 1's separate review - fingerprint), or fold it into the first slice built under the new process? +## Decisions (`USER:2026-10-13:slices-gates-uat-as-recommended`) + +- **D1 — red-first inside a slice:** kept, per connected batch. Every clause + gets a failing assertion before its code, with one RED commit and one GREEN + commit per batch. +- **D2 — floors:** the shipped default and autopilot gate files keep slice + completion human when the slice touches sign-in, payments, existing data or + an external contract. A project may change that in its own copy. +- **D3 — acceptance tests and completion:** the default gate file requires the + acceptance-test guide before completion; whether the tester's sign-off is + also required is each project's gate-file rule (default: not required). +- **D4 — rename:** today's "slice" (the code a batch lands) becomes + **increment**. +- **D5 — `EPIC-CLI-DELIVERY-PATH`:** built now on today's process, without + `REQ-CROSS-553`, which is deferred to this work's separate review + fingerprint. From c1e0b9a5698f79adb8af1391448c51f3eae824f6 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Tue, 13 Oct 2026 10:26:29 +0300 Subject: [PATCH 03/11] docs(design): SLICE-RDD-FLOW delivers the change as one slice USER:2026-10-13:one-slice-dogfood. Co-Authored-By: Claude Opus 5.5 --- design/2026-10-13-slices-gates-uat.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/design/2026-10-13-slices-gates-uat.md b/design/2026-10-13-slices-gates-uat.md index 8cd9ed6..353b51f 100644 --- a/design/2026-10-13-slices-gates-uat.md +++ b/design/2026-10-13-slices-gates-uat.md @@ -210,3 +210,23 @@ Each of 2 and 3 is product work and goes through the loop. - **D5 — `EPIC-CLI-DELIVERY-PATH`:** built now on today's process, without `REQ-CROSS-553`, which is deferred to this work's separate review fingerprint. + +## The slice that delivers this (`USER:2026-10-13:one-slice-dogfood`) + +The whole change is planned, entered, built, verified and accepted as one +slice, run under its own rules before the tooling exists ("eat our own +dogfood"). Where the tools cannot yet hold a rule, it is followed by +convention and the gap is filed. + +- **Slice:** `SLICE-RDD-FLOW` — opened 2026-10-13 by the process owner. +- **Members:** `EPIC-CLI-DELIVERY-PATH` (planned; three cold-review rounds, + passing), `EPIC-RDD-SLICES`, `EPIC-RDD-GATE-RULES`, `EPIC-RDD-ACCEPTANCE`. +- **Plan review:** one review of the new epics and their fit with the + delivery-path epic; additions get a narrow review when recorded. +- **Entry:** one decision by the process owner for the whole slice + (convention: the per-epic entry gates are answered together on that one + word; `ENTRY-EPIC-CLI-DELIVERY-PATH` is held open until then). +- **Build:** red-first per connected batch; focused tests per batch. +- **End:** full verification, one independent code review, the + acceptance-test guide, one completion page answered item by item. +- **Gaps met:** `BACKLOG-TOOL-522` (no slice record or selection kind). From bb0d202e7607b034a803d760a9138ae737a2e184 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:01:23 +0300 Subject: [PATCH 04/11] docs(process): work in slices; the code a batch lands is an increment A slice is a named set of Epics and requirements a developer delivers as one package, recorded in a tracked process/slices/.md file with no dates. Plan review, entry brief, full verification, independent code review and completion brief run once per slice; red-first runs per connected batch with focused tests per batch. The entry packet's RED strategy names the stages. "Sprint" becomes "slice" and today's "slice" becomes "increment". Adds file-state/SLICE.md; WORK-SELECTION.md is unchanged. REQ-CROSS-562 Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 +- PROCESS.md | 133 ++++++++++++++++++-------- README.md | 4 +- file-state/SLICE.md | 64 +++++++++++++ skills/rdd-autopilot/SKILL.md | 38 ++++---- skills/rdd-build/SKILL.md | 37 +++---- skills/rdd-cold-review/SKILL.md | 6 +- skills/rdd-completion-review/SKILL.md | 10 +- skills/rdd-deliver/SKILL.md | 10 +- skills/rdd-plan/SKILL.md | 3 + skills/rdd-start/SKILL.md | 18 ++-- 11 files changed, 235 insertions(+), 93 deletions(-) create mode 100644 file-state/SLICE.md diff --git a/AGENTS.md b/AGENTS.md index 997373d..f6c599a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,8 @@ serialization shapes; it does not contain a project's live delivery state. completion, records, and reconciliation. - [`skills/`](skills/) contains focused procedures that apply the process. - [`file-state/`](file-state/) contains the canonical serialization shapes for - Epic, requirement, gate, work-selection, and backlog/gap records. + Epic, requirement, gate, work-selection, and backlog/gap records, and the + shape of the tracked slice file. - Project instructions own only project-specific rules such as architecture, repository topology, commands, environments, and test gates. They reference rather than redefine the process. They name the project's sanctioned tool @@ -32,7 +33,7 @@ on a decision, or what is blocked: 3. enter the session with `skills/rdd-start/SKILL.md` — it verifies the store binding before selection and the active release for normal delivery; then use `skills/rdd-deliver/SKILL.md` for end-to-end delivery, - `skills/rdd-autopilot/SKILL.md` for a sprint under a human's autopilot + `skills/rdd-autopilot/SKILL.md` for a slice run under a human's autopilot grant, or the applicable focused `skills/rdd-*/SKILL.md` when the request explicitly ends at one process pass; use `skills/rdd-verify/SKILL.md` for entered verification work diff --git a/PROCESS.md b/PROCESS.md index d7c35d4..f2f4945 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -476,6 +476,41 @@ Normal delivery selection requires exactly one active release with a `USER:` source. Candidate confirmation and source-scoped baseline work do not select a delivery release and do not require one to be active. +### Slices + +A slice is a named set of Epics and requirements a developer delivers as one +package. It is recorded in a tracked `process/slices/.md` file in +the shape `file-state/SLICE.md` gives, and changed the way the project +reviews any other repository change. It has no dates: the developer opens it +and closes it. It may hold one requirement. Members are added while it is +open; each addition gets its own review and entry through its normal gates — +a plan review of the addition and its effect on the slice, not a re-review of +the slice. A member leaves only by becoming `DEFERRED` or `OBSOLETE`. Each +member keeps its own records, gates, and selection; the slice file is +coordination and never states a status — where it and a record disagree, the +record holds. The work-selection record carries no slice: which slice names a +scope is read from the open slice files. + +What the loop otherwise does per Epic or per requirement happens once per +slice: + +| Activity | Once per slice | +|---|---| +| Plan review | One cold review: one independent reviewer pass over every member's review snapshot, its findings and verdict recorded per member; one narrow review per addition | +| Entry | One entry brief; each member's entry gate carries it, and the human answers each gate with its own confirmation | +| Red-first | Per connected batch: one RED commit carrying a failing assertion for every clause the batch implements, then the commit that turns it green | +| Tests while building | Focused tests per batch | +| Full verification | Once, at slice end, at the delivered revision | +| Independent code review | One review over the whole change, where the slice needs one (§Planning and readiness) | +| Completion | One completion brief; each member's completion gate carries it and is answered with its own confirmation, item by item | + +The stages in each member's plan (§Entry packet item 5) order its connected +batches; a slice file may list stages across members. A one-requirement slice +is the single-SR loop with one review and one completion. Per-requirement +evidence, traces, and the store's per-requirement checks do not change; only +their timing follows the slice's batches. Autopilot is a way of running a +slice (§Autopilot). + ### Small-change lane The small-change lane scales review and gates to the size of the change; it @@ -510,8 +545,9 @@ is never forced through. Autopilot is for building larger scopes — greenfield systems, initiatives, many Epics — when stopping at every process check costs more than the check -protects. It keeps the records and the tests. It moves the human checkpoint to -the end of a sprint, and turns process refusals into logged work instead of +protects. It is a way of running a slice (§Slices), not a separate period of +work. It keeps the records and the tests. It moves the human checkpoint to +the end of the slice, and turns process refusals into logged work instead of stops. **The unit of work is a connected journey.** A connected journey is a set of @@ -530,20 +566,20 @@ selection kind. Within the scope, a missing view or primary action outranks refining one that already works. This changes the order of work, never what a requirement means or what completion requires. -The sprint keeps a usable-coverage matrix: for each journey, whether its +The slice keeps a usable-coverage matrix: for each journey, whether its entry point is reachable, its primary action is connected to real state, the state persists, the next step works, and end-to-end evidence exists — each marked built, partial, missing, or externally held. Externally held means the -cell waits on something the sprint cannot supply — a human answer, access, or +cell waits on something the slice cannot supply — a human answer, access, or an outside party. It is a matrix mark, not a lifecycle state: when the hold stops work on a requirement, that requirement is `BLOCKED` with the blocker recorded; otherwise the requirement keeps its state and its matrix cell names the hold. A navigable prototype, a mocked response, or an isolated backend test does not make a journey built. Every unfinished requirement clause stays visible in it. The matrix is a -working view of the sprint, reported at checkpoints and on the sprint-end +working view of the slice, reported at checkpoints and on the slice-end page; it links requirement records and never stands in for them. Between -sessions it is kept in the sprint's working record with the checkpoint +sessions it is kept in the slice's working record with the checkpoint reports, not in the store unless the project says so; where it and a record disagree, the record holds. @@ -557,23 +593,23 @@ A journey is built in three stages: 3. harden the remaining acceptance clauses, edge cases, scale, and presentation. -Stages 1 and 2 run per journey during the sprint; stage 3 runs at the sprint's +Stages 1 and 2 run per journey during the slice; stage 3 runs at the slice's closeout. A stage proceeds in batches: a batch is the adjacent primary actions built together under one RED commit and the commit that turns it -green, and the working code a batch lands is a slice. +green, and the working code a batch lands is an increment. Security, authorization, tenant isolation, and atomic data integrity belong to -the first functioning slice. They are never deferred to the hardening stage. +the first functioning increment. They are never deferred to the hardening stage. **Build-time and completion-time verification are separate.** During the -sprint, focused checks are the feedback gate: a focused-green slice is a +slice, focused checks are the feedback gate: a focused-green increment is a development waypoint, not a completion event, and the next step is the next missing capability. A run of the full verifier before closeout needs a concrete cross-system risk that focused checks cannot bound, or a human's request, and the reason is stated. The full-verifier rule governs the agent's own feedback runs; the project's commit gate runs on every commit as configured, even when it runs the full suite. Full regression and hardening -run in the sprint's closeout, with time reserved for repairs. Closeout adds +run in the slice's closeout, with time reserved for repairs. Closeout adds verification and hardening, not RED for clauses already built. Missing or failing required evidence keeps an item from `IN_REVIEW`: it stops acceptance, not the building of the next authorized action. @@ -582,7 +618,7 @@ acceptance, not the building of the next authorized action. grants autopilot once. The grant names: - the scope (Epics, an initiative, or a system); -- the end of the sprint (a date); +- the end of the grant (a date) — the slice itself has no dates; - any areas that stay out of it. It is recorded with its `USER:` source where the scope's decisions are @@ -601,17 +637,17 @@ human withdraws it, or when its scope is done. | Cold review | Up to two rounds, blocking | One pass, then at most one narrow confirmation. Material findings are folded into the packet as tests or boundary lines, and the rest are logged. If the confirmation still fails, the item is built ahead of its record and the failure is logged. | | Packet completeness | Items 1–6 and the brief complete before review | Write what the builder needs; a gap the review finds is folded in or logged, never a stop | | Preflight facts (suspended selections, stale snapshots, drift, open holds) | Stop selection | Clear each with its documented verb, or log it and continue | -| A refusal at a phase boundary | Stop and report | Try the documented clearing verb once. If it still refuses, log it, move to the next item, and let the record catch up at sprint end. | +| A refusal at a phase boundary | Stop and report | Try the documented clearing verb once. If it still refuses, log it, move to the next item, and let the record catch up at slice end. | | A product question | Asked; the loop waits | Asked, but the loop does not wait: see below | | After a gate answer or a pass | Continue the requested work to the next human decision | Continue | | Work selection | An Epic or a single SR | A connected journey with the requirements it needs, existing or newly written with sources; more than one SR from an Epic is held as that Epic's selection | -| Planning and cold review | Per selected scope | Once per journey. An unchanged reviewed packet goes straight to entry, or to RED when its entry is already applied and current; any change in a blocking cold-review category — correctness, security, data integrity or data loss, contract, traceability, testability — and any changed scope or acceptance is reviewed again, and only that change | +| Planning and cold review | Once per slice, recorded per member; one narrow review per addition | Once per journey. An unchanged reviewed packet goes straight to entry, or to RED when its entry is already applied and current; any change in a blocking cold-review category — correctness, security, data integrity or data loss, contract, traceability, testability — and any changed scope or acceptance is reviewed again, and only that change | | Readiness to build | The complete packet and an applied entry | Code starts once the source, outcome, owning requirements, state and safety boundaries, and representative RED assertions are clear; remaining inventory and record updates run alongside the build. Code written before the entry is applied is reversible local build-ahead (below); the entry is applied before any RED evidence is recorded or any requirement advances | | Cold review timing | Before any code | May run alongside reversible local build-ahead. A material safety finding is repaired before the affected code is committed past its RED commit | -| AI TDD inner loop | One SR clause at a time, rerunning affected URs each iteration | Batch: representative journey and state-boundary REDs cover adjacent primary actions, which are implemented together and checked with one focused integrated GREEN run. The batch's RED commit carries a failing assertion for every clause the batch implements; representative REDs only reduce the number of commits, never the assertions | -| Commits | At each waypoint: RED, GREEN, cleanup, reconciliation | Per connected batch: one RED commit carrying the batch's failing tests, its RED evidence recorded there, then the working batch. A RED commit carries only failing tests that its next commit turns green; that commit lands the whole batch. To land a batch SR by SR, use one RED/GREEN pair per SR. A journey assertion is written in the batch that can make it pass. A test is never skipped, disabled or left failing to get a commit past the project's gate, other than the declared RED tests of a RED commit as the gate admits them; the gate runs on every commit as configured | +| AI TDD inner loop | Per connected batch: one RED commit with a failing assertion for every clause the batch implements, then its GREEN, rerunning affected URs each batch | Batch: representative journey and state-boundary REDs cover adjacent primary actions, which are implemented together and checked with one focused integrated GREEN run. The batch's RED commit carries a failing assertion for every clause the batch implements; representative REDs only reduce the number of commits, never the assertions | +| Commits | Per connected batch: RED, GREEN, cleanup, reconciliation | Per connected batch: one RED commit carrying the batch's failing tests, its RED evidence recorded there, then the working batch. A RED commit carries only failing tests that its next commit turns green; that commit lands the whole batch. To land a batch SR by SR, use one RED/GREEN pair per SR. A journey assertion is written in the batch that can make it pass. A test is never skipped, disabled or left failing to get a commit past the project's gate, other than the declared RED tests of a RED commit as the gate admits them; the gate runs on every commit as configured | | Records | Reconciled after each pass | Reconciled at each integration checkpoint; record grooming never holds the build | -| Full verification | At each phase's required exit | The agent's full-verifier feedback runs wait for sprint closeout, unless the exception above applies; the project's commit gate is unchanged | +| Full verification | Once per slice, at slice end, at the delivered revision; focused tests per batch before it | The agent's full-verifier feedback runs wait for slice closeout, unless the exception above applies; the project's commit gate is unchanged | **Reversible local build-ahead** is uncommitted work on the feature branch, written before the entry is applied. It is set aside so that the RED commit @@ -626,10 +662,10 @@ each integration checkpoint, compare usable coverage with the previous checkpoint. When the batch added no user capability and repaired no blocking defect, the next action is the next missing journey step; any exception is explained in user-outcome terms. Immediate further work on a -green slice is justified only by a safety or data-integrity defect, a +green increment is justified only by a safety or data-integrity defect, a regression, or a failure that blocks the selected journey; every other finding is queued with an owner and a next action. This restriction governs the -build during the sprint; it does not apply to the hardening stage at +build during the slice; it does not apply to the hardening stage at closeout. Report the observed split between implementation and preparation or checking; when preparation and checking dominate, stop discretionary process work and build the next missing action. @@ -659,9 +695,9 @@ It waits for an answer only when a wrong guess is hard to undo: clause a batch implements has its failing assertion in the batch's RED commit. - Security, authorization, tenant isolation, and atomic data integrity hold - from the first functioning slice. -- Every acceptance clause is met before acceptance. Focused-green slices, - partial evidence, and the sprint's end date are not acceptance. + from the first functioning increment. +- Every acceptance clause is met before acceptance. Focused-green increments, + partial evidence, and the grant's end date are not acceptance. - The store's server-side refusals are cleared through the sanctioned tool or logged. They are never bypassed with hand-made writes. - Merging, deploying, and releasing stay with humans. @@ -669,13 +705,13 @@ It waits for an answer only when a wrong guess is hard to undo: **The log.** Each skipped check, uncleared refusal, advisory finding left open, and build ahead of its record is filed as a gap record naming the -sprint. Nothing is dropped silently. +slice. Nothing is dropped silently. -**Sprint end.** Closeout runs the full required verification and the +**Slice end.** Closeout runs the full required verification and the hardening stage, and repairs what fails; it adds verification and hardening, not RED for clauses already built. An item is presented as eligible for completion only when its required evidence passes. Then one -independent review reads everything the sprint built — the change, not the +independent review reads everything the slice built — the change, not the packets — against its requirements and tests. The human then gets one page: - the journeys and primary actions a user can now complete, with evidence; @@ -685,7 +721,7 @@ packets — against its requirements and tests. The human then gets one page: - the review's findings. The human answers completion item by item, as in a lane batch. A rejected -item stays `IN_REVIEW`. A changed assumption is triaged into the next sprint. +item stays `IN_REVIEW`. A changed assumption is triaged into the next slice. Only then does normal gate discipline apply again to anything the grant did not cover. @@ -726,7 +762,9 @@ The fingerprinted packet must contain: 5. an upper-RED strategy for selected UR scenarios requiring new evidence, a lower-RED strategy for selected SR clauses requiring new evidence, and proportional regression gates; unchanged proven scenarios need revalidation, - not a new RED; + not a new RED. The strategy names the stages: the ordered connected batches + the build runs, each naming the clauses its RED commit carries and its + focused tests; 6. sourced decisions, conflicts, gaps, deferrals, blockers, and unknowns; 7. cold-review findings and verdict; and 8. the human entry brief. @@ -793,7 +831,8 @@ Changes to approved behavior, scope, architecture, acceptance, or a material technical decision return to the affected planning pass. A review finding does not itself authorize implementation. -At most two cold-review rounds run on the selected planning scope. A later +At most two cold-review rounds run on the selected planning scope. In a +slice, each round is one pass over every member (§Slices). A later round reviews what changed since the previous round's recorded trace — the records and sections whose fingerprints moved, the findings still open, and what those touch — and carries the unchanged remainder at that round's verdict; @@ -807,7 +846,7 @@ round: a blocking finding sends it out of the lane. Completion review requires an independent code review of the built change for Epic scope. For single-SR scope, obtain one when project gates or the user -require it. The review runs from a context independent of implementation; +require it. In a slice, one such review covers the whole change once. The review runs from a context independent of implementation; record the reviewer, reviewed revision, findings, and verdict separately from planning review. Missing required review or open material findings stop delivery and completion. Resolved implementation findings cite the correcting @@ -912,8 +951,8 @@ while the approved scope remains unchanged. ```text establish required selected UR upper RED - -> select an unmet approved SR clause - -> SR lower RED -> GREEN -> CLEAN -> lower verify + -> select the next connected batch of unmet approved SR clauses + -> batch lower RED -> GREEN -> CLEAN -> focused verify -> rerun affected UR upper evidence -> all applicable trace gates PASS? no -> repeat @@ -924,11 +963,16 @@ Run the loop as follows: 1. Establish the expected upper RED for every selected applicable UR requiring new evidence. A standalone SR has no upper step. -2. If an SR trace is unmet, select one approved clause, establish its focused - lower RED, implement the smallest passing behavior, and perform scoped - behavior-preserving cleanup. -3. Run the SR's focused and boundary-appropriate regression gates on the - cleaned content, then rerun each affected UR scenario. +2. If an SR trace is unmet, select the next connected batch: the approved + clauses built together, in the order the packet's stages name — one + clause, or several adjacent ones. Commit a failing assertion for every + clause in the batch and establish the batch's focused lower RED at that + commit, implement the smallest passing behavior for the whole batch, and + perform scoped behavior-preserving cleanup. A RED commit carries only + failing tests that its next commit turns green. +3. Run the batch's focused tests on the cleaned content, then rerun each + affected UR scenario. Full verification runs once per slice, at slice end, + at the delivered revision (§Evidence and completion). 4. Re-evaluate every selected applicable SR lower trace and UR upper trace independently. A trace `FAIL` caused by unmet approved behavior starts another iteration; it does not request human input. @@ -936,8 +980,9 @@ Run the loop as follows: `PASS`, and every selected applicable UR upper trace is current and `PASS` with all of its applicable required SRs in `IN_REVIEW` or `DONE`. -Under a current autopilot grant, §Autopilot's batch cadence replaces the -per-clause rhythm of steps 2–4, at closeout as during the sprint: a clause +Under a current autopilot grant, §Autopilot's batch cadence — representative +journey and state-boundary assertions over adjacent primary actions — applies +to steps 2–4, at closeout as during the slice: a clause first built at closeout gets its own RED like any other. Step 1 changes in one respect: a UR scenario's upper RED is established in the batch that can make it pass, and it still fails at that batch's RED revision. The exit in @@ -1006,7 +1051,7 @@ uses the requirements under As-built verification and acceptance instead. | Requirement/evidence | Required evidence | |---|---| -| SR lower — `LOWER_VERIFIED` | Sourced SR clause; expected focused failure; named regression-sensitive assertions; linked code; passing focused and proportional post-cleanup gates at the cited revision | +| SR lower — `LOWER_VERIFIED` | Sourced SR clause; expected focused failure in its batch's RED commit; named regression-sensitive assertions; linked code; passing focused post-cleanup gates for its batch at the cited revision; proportional and full regression run once per slice (§Slices) | | UR upper — `UPPER_VALIDATED` | Sourced UR scenario; expected user-flow failure; passing result; required runtime/browser observation; linked revision | Choose evidence by boundary: unit/property for domain rules, component plus @@ -1033,6 +1078,11 @@ One completion human gate may name many small changes — a lane batch — each meeting its own predicate below; the human may reject single items, which stay `IN_REVIEW`. +A slice completes the same way, item by item: one completion brief, carried +by each member's completion gate and answered with its own confirmation; a +rejected item stays `IN_REVIEW`. The slice's full required verification runs +once, at the delivered revision, before that brief is presented. + A normal completion human gate may open only when named items are `IN_REVIEW`, code is delivered, evidence is current at the delivered revision, state is reconciled, candidate relations are excluded, and gaps/deferrals/decisions are disclosed. @@ -1090,6 +1140,7 @@ file-state/ GATES.md WORK-SELECTION.md BACKLOG.md + SLICE.md ``` `EPICS.md` stores optional grouping records. `REQUIREMENTS.md` stores URs, SRs, @@ -1099,6 +1150,10 @@ selections, and selection history. `BACKLOG.md` stores unrouted triage items and gap records. Derived queues and progress views — including the pending human-decision projection — are regenerated, not backed up separately. +`SLICE.md` is not a store record: it gives the shape of the tracked slice +file (§Slices), which is versioned in the repository in both kinds of store +and holds coordination only. + Backlog, gap, and tooling-gap records are records of the store like every other: they are created, routed, and closed there, and their state is read from there. A plan, a handover, or an agent's notes may summarize them and is diff --git a/README.md b/README.md index b1e04c9..cf01d5b 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,8 @@ apply that model; `file-state/` serializes its records without redefining it. |---|---| | `AGENTS.md` | shared agent policy and canonical entry point | | `PROCESS.md` | complete canonical process | -| `skills/` | delivery orchestration, an autopilot sprint (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-audit` for documents and citations | -| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records | +| `skills/` | delivery orchestration, a slice run on autopilot (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-audit` for documents and citations | +| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shape of the tracked slice file | ## Distribution diff --git a/file-state/SLICE.md b/file-state/SLICE.md new file mode 100644 index 0000000..83727d1 --- /dev/null +++ b/file-state/SLICE.md @@ -0,0 +1,64 @@ +# Slice file + +> Canonical shape of a slice file. `PROCESS.md` §Slices defines the slice. +> A slice file is a tracked project file at `process/slices/.md`, +> versioned in the repository and changed the way the project reviews any +> other repository change, in a store-backed and a file-backed repository +> alike. It is coordination, not a store record: it never states a lifecycle +> status, and where it and a record disagree, the record holds. + +The work-selection record carries no slice field. Which slice names a scope is +read from the open slice files. + +```markdown +# SLICE-«id» — «title in plain product language» + +- **Status:** open | closed +- **Opened by:** «person» («USER: source») +- **Closed by:** — | «person» («USER: source») + +## Members +- «EPIC id» +- «UR or SR id» + +## Stages +1. «stage» — «the members or clauses it lands, in build order» + +## Decisions +- «USER: source» — «decision in plain words» + +## Entry brief +- What: «decision» +- Why now: «trigger and blocked work» +- Changes if approved: «visible outcome» +- Risk if wrong: «downside and reversibility» +- Recommendation: «option and rationale» + +## Completion brief +- What: «decision» +- Why now: «trigger and blocked work» +- Changes if approved: «visible outcome» +- Risk if wrong: «downside and reversibility» +- Recommendation: «option and rationale» +``` + +- The heading's id matches the file name. +- **Status** is `open` or `closed`. The developer opens and closes the slice; + it has no dates. +- **Members** lists Epic and requirement ids, one per line, at least one, + none repeated. A requirement whose Epic is also a member is not listed: it + enters and completes with its Epic. Backlog, gap and gate ids are not + members. A member is added by a change to this file while the slice is + open, and gets its own review and entry through its normal gates. A member + leaves only by becoming `DEFERRED` or `OBSOLETE`; its line stays and the + loop skips it. +- **Stages** is optional: the order in which the members' connected batches + are built, across members. Each member's own plan names its stages + (`PROCESS.md` §Entry packet item 5). +- **Decisions** is optional and records slice-wide decisions with their + `USER:` sources. A decision about one member is also recorded on that + member. +- **Entry brief** and **Completion brief** are optional until the slice + reaches entry or completion. A brief carries the five bullets of the gate + brief (`PROCESS.md` §Gates). Each member's gate carries the brief, and the + human answers each gate with its own confirmation. diff --git a/skills/rdd-autopilot/SKILL.md b/skills/rdd-autopilot/SKILL.md index 7a3ded2..2269aef 100644 --- a/skills/rdd-autopilot/SKILL.md +++ b/skills/rdd-autopilot/SKILL.md @@ -1,9 +1,9 @@ --- name: rdd-autopilot -description: Build a larger scope — Epics, an initiative, or a greenfield system — under a human's autopilot grant, keeping requirements, sources, and red-first tests while moving human approval to the end of the sprint. Use when a current autopilot grant covers the scope, or when the human asks to start one. Builds connected user journeys in batches before hardening, asks product questions without waiting on them, clears or logs process refusals instead of stopping, and ends the sprint with full verification, one independent review, and one completion page. +description: Run a slice on autopilot to build a larger scope — Epics, an initiative, or a greenfield system — under a human's autopilot grant, keeping requirements, sources, and red-first tests while moving human approval to the end of the slice. Use when a current autopilot grant covers the scope, or when the human asks to start one. Builds connected user journeys in batches before hardening, asks product questions without waiting on them, clears or logs process refusals instead of stopping, and ends the slice with full verification, one independent review, and one completion page. --- -# Run an autopilot sprint +# Run a slice on autopilot Read the project `AGENTS.md` and canonical `PROCESS.md` (`.modernpath/rdd/PROCESS.md` in a consuming repository), especially @@ -15,23 +15,23 @@ bounds differ from §Autopilot, §Autopilot applies. 1. **Find the grant.** Read the grant that covers the scope and check that it is current. Without one, ask the human for it in one message that names: - - the scope; - - the sprint end date; + - the slice, or the scope to open one for; + - the grant's end date (the slice itself has no dates); - any excluded areas; - what the human gives up: per-Epic entry approval and waiting on questions; - - what the human keeps: the completion answer at sprint end, and merges. + - what the human keeps: the completion answer at slice end, and merges. Record the answer as §Autopilot says. 2. **Run `rdd-start`'s preflight, without stopping on it.** Clear each preflight fact with its documented verb: reconcile, refresh, or release a - selection this sprint does not need. If a fact will not clear, log it and - go on. Only a missing or unreachable store stops the sprint. + selection this slice does not need. If a fact will not clear, log it and + go on. Only a missing or unreachable store stops the slice. 3. **Map usable coverage.** Turn the scope into user journeys and the views and primary actions each needs, linked to the requirements they need, existing or newly written with sources. Start the coverage matrix - §Autopilot describes as the sprint's working view, and keep it in the - sprint's working record between sessions; it links the records and is not + §Autopilot describes as the slice's working view, and keep it in the + slice's working record between sessions; it links the records and is not a second ledger. 4. **Order the journeys.** Dependencies first, then the journey that makes the most of the product usable. Show the order and the first outcome a @@ -76,7 +76,7 @@ bounds differ from §Autopilot, §Autopilot applies. batch. To land a batch SR by SR, use one RED/GREEN pair per SR. Write a journey assertion in the batch that can make it pass; - implement the adjacent primary actions together, keeping security, - authorization, tenant isolation, and data integrity in this first slice; + authorization, tenant isolation, and data integrity in this first increment; - run one focused integrated GREEN check, plus targeted regressions where the integration needs them — not the full verifier; - commit and push the working batch. The full-verifier rule governs your @@ -88,7 +88,7 @@ bounds differ from §Autopilot, §Autopilot applies. end. Stage 3, harden, runs at closeout. Record RED, GREEN, and limits as you go. Advance a requirement to `IN_REVIEW` only with its full required evidence; a requirement in a - partial slice keeps its state. + partial increment keeps its state. 5. **Checkpoint.** Reconcile the batch's records. Update the coverage matrix and compare it with the previous checkpoint, as §Autopilot's checkpoint rule says. Queue findings that do not block the journey with an owner and @@ -101,7 +101,7 @@ bounds differ from §Autopilot, §Autopilot applies. 1. Read the refusal. Run the verb it names, or the one `mp-process-cli` (or the project's store guide) lists for it, **once**. 2. If it still refuses: - - file a gap record naming the sprint, the item, the refusal text, and + - file a gap record naming the slice, the item, the refusal text, and what was tried; - if the code is ready, keep building it on the branch ahead of its record; - move to the next item. @@ -117,23 +117,23 @@ bounds differ from §Autopilot, §Autopilot applies. *assumed under autopilot, pending confirmation*, and continue. 4. When the human answers later, apply it. A changed assumption is triaged: fix it now if the item is still being built, otherwise queue it for the - next sprint. + next slice. -## Sprint end +## Slice end Run it at the grant's end date, when the scope is built, or when the human asks. -1. **Reconcile** every record the sprint touched. Try once more to clear the +1. **Reconcile** every record the slice touched. Try once more to clear the logged refusals. 2. **Close out.** Run the full required verification and harden the combined change (stage 3). Closeout adds verification and hardening, not RED for clauses already built; a clause first built at closeout gets its own RED like any other. The checkpoint limit on further work on a - green slice does not apply here. Repair what fails + green increment does not apply here. Repair what fails before presenting any item as eligible for completion. The end date is not evidence. -3. **Review.** Run one independent review of everything the sprint built, from +3. **Review.** Run one independent review of everything the slice built, from the code at the branch head, against its requirements and tests (`rdd-completion-review`'s audit). Record the findings. 4. **Present one page:** @@ -146,7 +146,7 @@ asks. Give links to the working-set files. 5. **Apply** the human's completion answers item by item. A rejected item stays `IN_REVIEW`. A changed assumption goes to `rdd-triage`. -6. **Report** whether the grant continues into another sprint, or ends. +6. **Report** whether the grant continues into another slice, or ends. ## Report @@ -154,4 +154,4 @@ At each checkpoint, lead with what a user can now do, the next missing step, and any safety or external hold, then the observed split between building and preparation or checking. Requirement ids, RED and GREEN commits, and assumptions follow as evidence; test and record counts are never reported as -product progress. At sprint end, the page above. +product progress. At slice end, the page above. diff --git a/skills/rdd-build/SKILL.md b/skills/rdd-build/SKILL.md index ef7d684..d3b2e69 100644 --- a/skills/rdd-build/SKILL.md +++ b/skills/rdd-build/SKILL.md @@ -3,7 +3,7 @@ name: rdd-build description: Implement one approved SR from TODO through current lower evidence and IN_REVIEW using RED, GREEN, cleanup and regression checks. Use after normal development entry for new or changed behavior. Use rdd-verify for entered verification work and rdd-reverse-engineer-verify for eligible source-scoped baselines with existing proof. --- -# Build one SR slice +# Build one SR increment Read the project `AGENTS.md`, canonical `PROCESS.md` (`.modernpath/rdd/PROCESS.md` in a consuming repository), selected SR, @@ -25,17 +25,22 @@ code, tests, and current records. unchanged scenarios needs no new RED. Keep upper evidence on the UR. Under an autopilot grant, a scenario's upper RED is established in the batch that can make it pass (`PROCESS.md` §AI TDD inner loop). -3. Select one unmet approved SR clause, establish its focused lower RED for the - expected reason, and link the stable test identity to the clause. -4. Implement the smallest behavior that makes the focused evidence pass. +3. Select the next connected batch of unmet approved SR clauses — one clause, + or several built together, in the order the packet's stages name. Commit a + failing assertion for every clause in the batch, establish the batch's + focused lower RED at that commit for the expected reason, and link each + stable test identity to its clause. +4. Implement the smallest behavior that makes the batch's focused evidence pass. Capture discoveries instead of silently expanding scope. 5. Perform requirement-scoped cleanup or record a no-op. Return to RED if the cleanup exposes a correctness change. -6. Run focused and proportional post-cleanup gates and record current SR lower - evidence. Separately rerun affected UR scenarios and update their upper +6. Run the batch's focused tests on the cleaned content and record current SR + lower evidence. Full verification runs once per slice, at slice end + (`rdd-completion-review`). Separately rerun affected UR scenarios and update their upper evidence, including live-browser and screenshot evidence for UI behavior. 7. Re-evaluate the selected SR clauses and affected UR scenarios. Repeat from - step 3 while an unmet result is caused by approved behavior in this SR. + step 3, with the next batch, while an unmet result is caused by approved + behavior in this SR. 8. Move the SR to `IN_REVIEW` when its lower trace passes. An affected UR moves to `IN_REVIEW` only when its upper trace passes and every applicable required SR is `IN_REVIEW` or `DONE`. @@ -48,21 +53,21 @@ Do not ask for human input inside the loop. Return to planning only when drift creates a new product, scope, architecture, acceptance, priority, release, workflow, or material technical decision. Record an external blocker exactly. -The project's commit gate binds the GREEN, cleanup, and reconciliation -commits. A RED waypoint may legitimately fail the very suite the gate runs — +A RED commit carries only failing tests that its next commit turns green; +that commit lands the whole batch. The project's commit gate binds the GREEN, +cleanup, and reconciliation commits. A RED waypoint may legitimately fail the +very suite the gate runs — its targeted failing test is its gate, and committing it before the change that satisfies it is what makes red-first auditable in history. Record the RED evidence while the repository stands at the RED commit, so the evidence is pinned to the revision that produced it. Under a current autopilot grant, `PROCESS.md` §Autopilot's batch cadence -applies: one RED commit carries a connected batch's failing tests, with a -failing assertion for every clause the batch implements; adjacent -actions are implemented together, and full-verifier feedback runs wait for -closeout. -A RED commit carries only failing tests that its next commit turns green; -that commit lands the whole batch. To land a batch SR by SR, use one RED/GREEN -pair per SR. A journey assertion is written in the batch that can make it +applies: one RED commit carries a connected batch's representative journey +and state-boundary failing tests, with a failing assertion for every clause +the batch implements; adjacent actions are implemented together, and +full-verifier feedback runs wait for closeout. +To land a batch SR by SR, use one RED/GREEN pair per SR. A journey assertion is written in the batch that can make it pass. A test is never skipped, disabled or left failing to get a commit past the project's gate, other than the declared RED tests of a RED commit as the gate admits them; the gate runs on every commit as configured, even when it diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index 30363d3..23872ea 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -78,7 +78,11 @@ review audits the change the packet proposes, not the packet as a document. failed round, report the remaining material findings to the human; do not start a third round automatically. Under an autopilot grant there is one pass and at most one narrow confirmation that its folded findings close - it; either way the sprint continues (`PROCESS.md` §Autopilot). + it; either way the slice continues (`PROCESS.md` §Autopilot). + For a slice, each round is one pass over every member's review snapshot, + with findings and the verdict recorded per member; an addition to an open + slice gets one narrow review of the addition and its effect on the slice, + not a re-review of the slice (`PROCESS.md` §Slices). 10. Return the cold-review trace gate `PASS` only when the material-finding rule in `PROCESS.md` is satisfied. Otherwise return `FAIL` with exact blockers. diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index 6a1f850..e5d57ac 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -22,7 +22,9 @@ records, and derived views. are proof dependencies; keep them DONE when their evidence is current and exclude them from new acceptance transitions. Obtain an independent code review of the built change for Epic scope. For single-SR scope, obtain one - when required by project gates or requested by the user. Use a context + when required by project gates or requested by the user. For a slice, run + this audit and one such review once, over the whole change + (`PROCESS.md` §Slices). Use a context independent of implementation; record the reviewer, reviewed revision, findings, and verdict separately from planning review. Verify fixes against their commits and test evidence. @@ -35,7 +37,7 @@ records, and derived views. integration path while keeping awaiting entities `IN_REVIEW`. 4. Re-run or confirm evidence against the delivered revision — the revision the authorized integration path produced, not the branch head that fed - it — and reconcile all authoritative records and derived views. Use + it; for a slice this is its one full verification — and reconcile all authoritative records and derived views. Use `skills/rdd-audit/SKILL.md` to verify that delivered records, citations, and documents still describe the code; a finding it surfaces is a stop condition or routes through `rdd-triage`, never a silent correction. @@ -48,7 +50,9 @@ records, and derived views. working-set files before asking for acceptance, following `PROCESS.md` §Gates. Small changes may be completed together in one lane-batch gate that lists each change with its evidence and review verdict; the human may reject - single items, which stay `IN_REVIEW`. + single items, which stay `IN_REVIEW`. A slice presents one completion + brief, carried by each member's completion gate and answered item by + item. 6. Do not answer the gate for the human. If the authorized human answers, record the real actor, role, exact scope, answer, and `USER:` source. 7. Apply `DONE` only to accepted named entities that independently satisfy the diff --git a/skills/rdd-deliver/SKILL.md b/skills/rdd-deliver/SKILL.md index cc3b41d..4439bbe 100644 --- a/skills/rdd-deliver/SKILL.md +++ b/skills/rdd-deliver/SKILL.md @@ -28,7 +28,10 @@ requirements remain normal development work. 1. Reconcile authoritative state, answered gates, evidence validity, and projections. Fix state disagreement before selecting work. 2. Freeze the selected scope under `PROCESS.md` and find its earliest unmet - prerequisite. Never start from the most convenient phase. + prerequisite. Never start from the most convenient phase. For a slice, + do this per member; the plan review, entry brief, full verification, + independent code review and completion brief run once per slice + (`PROCESS.md` §Slices). 3. If input is not authoritative or is `DERIVED`, apply `rdd-discover` and its confirmation gate. Continue only with confirmed requirements and relations. 4. For active work lacking current entry approval, apply `rdd-plan`, then @@ -60,8 +63,9 @@ human input while the approved scope remains unchanged: 1. Evaluate every selected applicable UR upper trace and SR lower trace. Establish any required initial RED observations. -2. Select the next unmet approved SR clause. Apply `rdd-build` or `rdd-verify` - until its lower trace is current and passing. +2. Select the next connected batch of unmet approved SR clauses, in the order + the packet's stages name. Apply `rdd-build` or `rdd-verify` until its lower + traces are current and passing. 3. Rerun affected UR scenarios and update their separate upper evidence. 4. Repeat for any failing or stale approved trace. Do not stop after the first GREEN result or completed SR while another selected trace remains unmet. diff --git a/skills/rdd-plan/SKILL.md b/skills/rdd-plan/SKILL.md index d54198d..e2c823e 100644 --- a/skills/rdd-plan/SKILL.md +++ b/skills/rdd-plan/SKILL.md @@ -69,6 +69,9 @@ retains its live obligations. code at the planning revision for the stated reason; a case that would already pass cannot serve as RED evidence. Check that reason against the current code during planning. + Name the stages: the ordered connected batches the build runs, each naming + the clauses its RED commit carries and its focused tests. In a slice, the + slice file may order stages across members. Planned commands and test identities are proposals; actual commands and outcomes become evidence when executed at the RED revision. A migration or schema change that satisfies the test lands with GREEN. For entered diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index cd7a72e..27b249b 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -51,9 +51,9 @@ continue (`PROCESS.md` §Autopilot, `rdd-autopilot`). ## Take the scope -Accept the work scope as the argument: an Epic id, a single SR id, an exact -UR/SR set for candidate or baseline work, a source inventory for onboarding, -or a raw request. +Accept the work scope as the argument: a slice id, an Epic id, a single SR id, +an exact UR/SR set for candidate or baseline work, a source inventory for +onboarding, or a raw request. Without one — including when the request is an orientation question rather than a scope — answer from the store: read pending human decisions, current and suspended selections, and routed work across all supported phases. @@ -74,7 +74,9 @@ the loop is stalled — report it as one rather than leaving the reader to count rows. For normal delivery, freeze the Epic or single-SR selection in the existing -work-selection record. For candidate and baseline work, retain the exact scope +work-selection record. For a slice, read its members from its slice file +(`PROCESS.md` §Slices); each member keeps its own selection, and the +slice's once-per-slice passes run over all of them. For candidate and baseline work, retain the exact scope in the applicable authorization, run and decision records. For normal planning, entry-packet depth is proportional to the frozen scope; no required item may be omitted. @@ -101,10 +103,10 @@ These rules bind every subsequent phase in the session: - timebox the diagnosis of a tooling failure; when the box closes, surface the gap through the project's channel and continue on a read-only path or stop. Never mutate a shared store to test a hypothesis; -- commit at waypoints — specification, expected RED, GREEN, cleanup, - reconciliation — with RED evidence committed before the change that - satisfies it, so red-first is auditable in history (under an autopilot - grant, per connected batch — `PROCESS.md` §Autopilot); +- commit at waypoints — specification, then per connected batch expected RED, + GREEN, cleanup, reconciliation — with RED evidence committed before the + change that satisfies it, so red-first is auditable in history + (`PROCESS.md` §Slices; under an autopilot grant, §Autopilot's batches); - work on a reviewable feature branch and preserve RED and passing fingerprints; - route a discovery through `rdd-triage` to the earliest phase it From 22a5e3bd21c6de93b58dab9852f68e62d4ccd1c6 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:02:18 +0300 Subject: [PATCH 05/11] docs(process): stop only at human decisions and speak plain language A human's answer is applied and the loop continues: the agent stops only at a human gate, a question only a human can answer, or where the user asked it to stop. An applied entry approval lets the build start. Merging, deploying and releasing still need the human's explicit instruction. The autopilot sentence for gate answers stays word for word. Everything shown to the human is plain product language with store jargon at most a trailing breadcrumb, and review findings are walked through one at a time. REQ-CROSS-586 (process-text side) Co-Authored-By: Claude Opus 5.5 --- PROCESS.md | 47 +++++++++++---------- skills/rdd-cold-review/SKILL.md | 6 ++- skills/rdd-deliver/SKILL.md | 16 ++++--- skills/rdd-entry-review/SKILL.md | 13 +++--- skills/rdd-reverse-engineer-accept/SKILL.md | 4 +- skills/rdd-start/SKILL.md | 19 ++++++--- 6 files changed, 59 insertions(+), 46 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index f2f4945..dc992cb 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -247,12 +247,8 @@ or marks anything DONE. Candidate confirmation is not delivery release selection Reverse-engineering can establish a usable requirement base or propose additions to an existing corpus. Before publication, present both modes and require an -explicit choice. Recommend baseline when the corpus is empty, is the sweep's -own earlier baseline, or the person has stated an as-built base as the purpose; -recommend DERIVED additions otherwise when it is populated. The choice is asked -once: the person's words settle it when they state the purpose or ask to -proceed on the recommendation shown, and the same question is not put again. -Existing content and approvals are preserved in both modes. +explicit choice. Recommend baseline when the corpus is empty, DERIVED additions +when it is populated. Existing content and approvals are preserved in both modes. A baseline authorization names the authenticated actor, system/store, immutable repository/file and document revision inventory, current corpus fingerprint, @@ -261,12 +257,6 @@ It authorizes derivation and publication of grounded as-built URs/SRs with inline scenarios and canonical source/UR–SR/code/test relationships. It does **not** assert the human reviewed statements that had not yet been generated. No per-row or per-context confirmation is required within this approved scope. -URs are derived one per distinct actor outcome over an enumerated inventory of -the surfaces actors reach, never one per context or subsystem; file linkage -alone never shows that a sweep is complete. Each requirement is written from -the code it cites, with its actor, outcome and the code's own rules; text -generated by filling a template from identifiers is not a requirement. Every UR -is served by the SRs that implement it. Publish coherent groups atomically with durable input fingerprints and receipts. Identical retries return the same receipt; changed input, out-of-scope sources @@ -386,17 +376,28 @@ earlier answer already implies its answer: preserving a delivered acceptance, applying a stance the human has stated, or bookkeeping that follows from a decision already given is done and reported, never asked. Each question stands alone in one plain sentence about what changes for the product, and -bookkeeping is never bundled with a decision. A human's answer — to a gate -or to a question — is a decision about that gate or question: the agent -applies it, reports in one line what moved, and carries on through the -phases of the work it was asked to do. It stops only at a human decision: an -open human gate, a question only the human can answer, or a stop the human -asked for. An answered entry gate lets the build start. Merging, deploying -and releasing wait for the human's word. A focused pass ends with its report. -Under an autopilot grant the agent also answers the entry gate itself -(§Autopilot). An authorized source-scoped +bookkeeping is never bundled with a decision. + +Everything shown to the human — briefs, questions, reports, progress lines — +is in plain product language: store jargon — record ids, fingerprints, gate +kinds, verb names, phase codes — appears at most as a trailing breadcrumb. +Review findings put to the human are walked through one at a time: what the +finding means for the product, its context, the options and what each +changes, then the next finding. + +A human's answer — to a gate or to a question — is a decision about that gate +or question: the agent applies it, reports what moved, and continues the loop +unless the user asked it to stop. An applied entry approval lets the build +start. The agent stops only at a human gate, at a question only a human can +answer, or where the user asked it to stop — a request that ends at one pass +is such a request — never merely because a phase ended. Merging, deploying +and releasing wait for the human's explicit instruction. Under an autopilot +grant the agent continues instead (§Autopilot). An authorized source-scoped reverse-engineering run, baseline or derived, continues within that -authorization (§Source-scoped baseline onboarding). +authorization (§Source-scoped baseline onboarding). Merging, deploying, and +releasing are not phases the loop continues into: they stay human acts in the +project's own tools, and the agent performs one only on a human's explicit +instruction for it. ### Automatic transitions @@ -639,7 +640,7 @@ human withdraws it, or when its scope is done. | Preflight facts (suspended selections, stale snapshots, drift, open holds) | Stop selection | Clear each with its documented verb, or log it and continue | | A refusal at a phase boundary | Stop and report | Try the documented clearing verb once. If it still refuses, log it, move to the next item, and let the record catch up at slice end. | | A product question | Asked; the loop waits | Asked, but the loop does not wait: see below | -| After a gate answer or a pass | Continue the requested work to the next human decision | Continue | +| After a gate answer or a pass | Continue, unless the user asked to stop | Continue | | Work selection | An Epic or a single SR | A connected journey with the requirements it needs, existing or newly written with sources; more than one SR from an Epic is held as that Epic's selection | | Planning and cold review | Once per slice, recorded per member; one narrow review per addition | Once per journey. An unchanged reviewed packet goes straight to entry, or to RED when its entry is already applied and current; any change in a blocking cold-review category — correctness, security, data integrity or data loss, contract, traceability, testability — and any changed scope or acceptance is reviewed again, and only that change | | Readiness to build | The complete packet and an applied entry | Code starts once the source, outcome, owning requirements, state and safety boundaries, and representative RED assertions are clear; remaining inventory and record updates run alongside the build. Code written before the entry is applied is reversible local build-ahead (below); the entry is applied before any RED evidence is recorded or any requirement advances | diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index 23872ea..8b4211b 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -75,8 +75,10 @@ review audits the change the packet proposes, not the packet as a document. finding returns `FAIL` with the instruction that the change leaves the lane for single-SR scope. 9. Run at most two rounds on the selected planning scope. After a second - failed round, report the remaining material findings to the human; - do not start a third round automatically. Under an autopilot grant there is + failed round, report the remaining material findings to the human one at + a time — what each means for the product, its context, the options and + what each changes (`PROCESS.md` §Gates); do not start a third round + automatically. Under an autopilot grant there is one pass and at most one narrow confirmation that its folded findings close it; either way the slice continues (`PROCESS.md` §Autopilot). For a slice, each round is one pass over every member's review snapshot, diff --git a/skills/rdd-deliver/SKILL.md b/skills/rdd-deliver/SKILL.md index 4439bbe..9f72ad1 100644 --- a/skills/rdd-deliver/SKILL.md +++ b/skills/rdd-deliver/SKILL.md @@ -52,14 +52,15 @@ requirements remain normal development work. invalidates. At an exact `OPEN` human gate, present its brief and linked list of relevant -working-set files before asking and wait, following `PROCESS.md` §Gates. If an -attributable answer is already available, apply it, report, and wait for the -human to resume. Never infer or supply the answer. +working-set files before asking and wait for the answer, following +`PROCESS.md` §Gates. If an attributable answer is already available, apply it, +report what moved, and continue the loop unless the user asked to stop. Never +infer or supply the answer. ## Run the AI TDD inner loop -When the human resumes after applied entry approval, iterate without further -human input while the approved scope remains unchanged: +After the entry is applied, iterate without further human input while the +approved scope remains unchanged: 1. Evaluate every selected applicable UR upper trace and SR lower trace. Establish any required initial RED observations. @@ -83,8 +84,9 @@ external blocker when progress cannot continue. - Treat a focused skill's exit as a handoff, not completion of this skill. - A human gate answer inside the loop is applied and reported, and the loop - carries on to the next human decision. Merging, deploying and releasing - wait for the human's word. + continues. It stops only at a human gate, at a question only a human can + answer, or where the user asked it to stop (`PROCESS.md` §Gates). Merging, + deploying, and releasing still need the human's explicit instruction. - Do not bypass a failed trace gate, a `DERIVED` hold, candidate relation, material finding, stale evidence, missing delivery, or failed reconciliation. - Keep unchanged approved items at their strongest supported state; re-enter diff --git a/skills/rdd-entry-review/SKILL.md b/skills/rdd-entry-review/SKILL.md index d7dad2b..953aa15 100644 --- a/skills/rdd-entry-review/SKILL.md +++ b/skills/rdd-entry-review/SKILL.md @@ -43,14 +43,15 @@ packet, cold-review findings, current gate records, and relevant sources. state and route requested changes. Report any remaining entry approvals needed for the selected delivery scope; partial approval does not permit development to start on the approved subset. -7. Report. Asked as a focused pass, the entry pass ends with the applied - transitions. In the complete loop the build follows without a new - request: an answered entry gate lets the build start (`PROCESS.md` - §Gates). +7. Report the applied transitions in plain product language. An applied + entry approval lets the build start: continue into the build unless the + user asked to stop after entry or the request ended at this pass + (`PROCESS.md` §Gates). Merging, deploying, and releasing still need the + human's explicit instruction. ## Report Report the entry-trace verdict, exact human-gate state, applied transitions, remaining blockers, and the exact handoff: `rdd-build`, `rdd-verify`, or the -earliest planning pass that must be repeated — named as the next pass for the -human to open, not entered by this one. +earliest planning pass that must be repeated — entered next, unless the user +asked to stop or the request ended at this pass. diff --git a/skills/rdd-reverse-engineer-accept/SKILL.md b/skills/rdd-reverse-engineer-accept/SKILL.md index afb313e..79c8a7d 100644 --- a/skills/rdd-reverse-engineer-accept/SKILL.md +++ b/skills/rdd-reverse-engineer-accept/SKILL.md @@ -92,7 +92,7 @@ Drift in a receipt's proof pins does not itself change lifecycle state. Route an established invalidation through `rdd-triage`, retaining the receipt as historical evidence; normal development resumes according to the item's entry approval and state. -After applying a human answer, report and wait as required by `PROCESS.md`, -including during the complete loop. Merge, publication and deployment need their +After applying a human answer, report what moved and continue as `PROCESS.md` +§Gates says, including during the complete loop. Merge, publication and deployment need their own authority. Missing operations go to the sanctioned tooling-gap channel, not raw API/store writes. diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index 27b249b..fc3ca81 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -97,9 +97,13 @@ These rules bind every subsequent phase in the session: has happened or will; - present the decision brief and linked list of relevant working-set files before asking for approval or a choice, following `PROCESS.md` §Gates; state - each option's consequences, and treat the answer as a decision, not as an - instruction to continue: - apply it, report, and wait (`PROCESS.md` §Gates); + each option's consequences, and treat the answer as a decision about that + gate or question: apply it, report what moved, and continue unless the user + asked to stop. Stop only at a human gate, at a question only a human can + answer, or where the user asked (`PROCESS.md` §Gates); +- show everything in plain product language; record ids, fingerprints, gate + kinds and verb names appear at most as a trailing breadcrumb, and review + findings are walked through with the human one at a time; - timebox the diagnosis of a tooling failure; when the box closes, surface the gap through the project's channel and continue on a read-only path or stop. Never mutate a shared store to test a hypothesis; @@ -130,9 +134,12 @@ retain precedence. Mixed scopes remain explicit; do not silently change the selection or apply normal RED requirements to this dedicated path. Provenance alone never reroutes an entered or defect-reopened item. -A focused pass ends with its report. When the request at session entry was -the complete loop, continue through its phases and stop only at a human -decision (`PROCESS.md` §Gates). +A pass ends with its report. When the request at session entry was the +complete loop, continue into the next phase, including after a human answer +applied at the boundary, unless the user asked to stop. A request that ends at +one pass, or an orientation question, ends with its report. Merging, +deploying, and releasing are never entered without the human's explicit +instruction. ## Report From f8cfd8845b5172c69e8436e650891d6b510fe5db Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:04:58 +0300 Subject: [PATCH 06/11] docs(process): project gate rules say who decides each decision point PROCESS.md names the decision points and what each carries; the project's process/rdd-human-gates.md says who decides. The kit ships a default preset (today's rules, light paths off, marked "kit default, not decided by this project") and an autopilot preset (light paths on, Scope and Expires required); the autopilot grant becomes that preset. Sign-in, payments, existing data and external contracts stay with a person in both, and the incident path keeps sign-in, payments and existing data with a person; an incident counts only when a person's words declaring it are quoted as a USER: source. An agent answer under a rules row carries a disclosure, and the ten residual risks are stated. Adds file-state/HUMAN-GATES.md and presets/. REQ-CROSS-573 Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 +- PROCESS.md | 168 +++++++++++++++++++++++--- README.md | 3 +- file-state/GATES.md | 2 +- file-state/HUMAN-GATES.md | 88 ++++++++++++++ presets/autopilot.md | 24 ++++ presets/default.md | 22 ++++ skills/rdd-autopilot/SKILL.md | 21 ++-- skills/rdd-completion-review/SKILL.md | 9 +- skills/rdd-entry-review/SKILL.md | 13 +- skills/rdd-start/SKILL.md | 10 +- skills/rdd-triage/SKILL.md | 8 +- 12 files changed, 336 insertions(+), 35 deletions(-) create mode 100644 file-state/HUMAN-GATES.md create mode 100644 presets/autopilot.md create mode 100644 presets/default.md diff --git a/AGENTS.md b/AGENTS.md index f6c599a..d0a8907 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,8 @@ serialization shapes; it does not contain a project's live delivery state. - [`skills/`](skills/) contains focused procedures that apply the process. - [`file-state/`](file-state/) contains the canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the - shape of the tracked slice file. + shapes of the tracked slice file and gate rules file; + [`presets/`](presets/) holds the default and autopilot gate rules. - Project instructions own only project-specific rules such as architecture, repository topology, commands, environments, and test gates. They reference rather than redefine the process. They name the project's sanctioned tool diff --git a/PROCESS.md b/PROCESS.md index dc992cb..33af5a9 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -44,7 +44,9 @@ release, and workflow. Agents establish facts and propose options; they do not make those decisions by assumption. Ask humans only for decisions that cannot be established from authoritative records, code, tests, or runtime evidence. Under an autopilot grant an agent may take a reversible product decision as a -recorded assumption pending confirmation (§Autopilot). +recorded assumption pending confirmation (§Autopilot). Where the project's gate +rules let the agent decide a gate, it decides only under the row's condition +and discloses it in the answer (§Project gate rules). | Tag | Source | |---|---| @@ -281,7 +283,8 @@ part of onboarding completion, not evidence of product verification. A trace gate evaluates non-human facts at an exact fingerprint. A human gate records a decision by an authorized human. A human gate may become `OPEN` only -after every prerequisite trace gate is `PASS`. +after every prerequisite trace gate is `PASS`. Who decides each decision point +is the project's gate rules (§Project gate rules). An approval-scope fingerprint identifies the requirement content, declared relations, scope, and decisions being approved. An evidence fingerprint identifies @@ -399,6 +402,123 @@ releasing are not phases the loop continues into: they stay human acts in the project's own tools, and the agent performs one only on a human's explicit instruction for it. +### Project gate rules + +This section names the decision points and what each must carry. Who decides +each one is the project's rule, kept in `process/rdd-human-gates.md` in the +shape `file-state/HUMAN-GATES.md` gives. The process ships two presets of that +file: `presets/default.md` and `presets/autopilot.md`. Installation seeds the +project's file once from the default preset and never overwrites it; a +deleted file is seeded again. + +The file has one row per decision point: `entry`, `slice_addition`, +`small_change_entry`, `pre_approved_entry`, `defect_fix`, `incident_fix`, +`product_assumption`, `completion`, `candidate_confirmation`, `demotion`, +`acceptance_guide`, `tester_signoff`, and the rows that are always a person's — +`baseline_acceptance`, `gate_rules`, and `lane_authorization`. Each row says +who decides — a person (`human`) or the agent (`agent`) — the one condition +under which the agent may decide, and the always-human areas: `sign_in`, +`payments`, `existing_data`, and `external_contract`. When a change touches an +area a row names, a person decides that row, whatever else it says; when the +agent is unsure whether a change touches one, a person decides. Candidate +confirmation, demotion, and the always-human rows are never the agent's. +`acceptance_guide` and `tester_signoff` say `required` or `not_required` +instead (§Evidence and completion). + +The rules count only when they are merged on the project's default branch +with a `Decided:` line carrying the process owner's `USER:` source. The rows +`entry`, `slice_addition`, `product_assumption`, and `completion` may be the +agent's only in a file with an `Expires` date; a file may also name the Epics +and requirements it covers (`Scope`). Expired, refused, or missing rules mean +the default preset, and the session says so at its start; nothing expires +silently. + +- **Default preset.** Today's rules with the light paths off: a person + decides entry, additions, product assumptions, completion, and the light + paths `pre_approved_entry`, `defect_fix`, and `incident_fix`; + `small_change_entry` is the small-change lane as it stands. The acceptance + test guide is required and the tester's sign-off is not. The seeded file + carries `kit-default` in place of a `USER:` source and is shown as "kit + default, not decided by this project". The marker is valid only while the + file is identical to the kit's default preset; a project that edits the + file decides it with its own `Decided:` source. +- **Autopilot preset.** The default, plus: the agent may decide entry after a + passing plan review, an addition after its passing narrow review, and a + reversible product assumption inside the scope; the light paths are on — + a recorded pre-approval is honoured, and reproduced defects and declared + incidents are fixed first. Completion stays a person's. It carries `Scope` + and `Expires` placeholders that must be filled before it counts (§Autopilot). + +In both presets every row the agent may decide names all four always-human +areas — the incident path names `sign_in`, `payments`, and `existing_data` — +and completion is a person's, so a slice that touches sign-in, payments, +existing data, or an external contract is completed by a person. A project +may change this in its own copy, except that the incident path always keeps +`sign_in`, `payments`, and `existing_data` with a person. Merging, deploying, +and releasing are not decision points of this process: they stay human acts +in the project's own tools. + +**Light paths.** On only where the project's rules turn them on — the +autopilot preset or the process owner's own copy: + +- **Pre-approved entry** (`pre_approved_entry`): a person's earlier words + naming the exact scope are cited as the entry answer's `USER:` source, + without a new decision brief. A recorded pre-approval naming the scope is + honoured; one that does not name it is not. +- **Defect fixed first** (`defect_fix`): a reproduced defect is fixed first + and recorded afterwards. The reproduction test is committed failing before + the fix; the SR, the entry answer, the evidence, and a gap record naming + the fix-first follow before other work is selected. +- **Incident fixed first** (`incident_fix`): only for an incident a person + declared. An incident counts as declared only when a person's words + declaring it are quoted as a `USER:` source in the fix-first gap record; + the agent never declares one. The fix may go first and the reproduction + test follow as verification; the SR, the entry answer, and the evidence + follow before other work is selected. The incident path keeps `sign_in`, + `payments`, and `existing_data` with a person. +- **Small change** (`small_change_entry`): the small-change lane + (§Small-change lane), under a lane authorization whose end is shown before + it comes. + +The always-human areas apply to every light path. + +**How an agent decision is recorded.** The commands that send a gate answer +or a lane approval as the person's ask the person before they run; a harness +that cannot ask refuses them, and the person runs them. When a rules row lets +the agent decide, the agent prepares the answer and writes `decided by the +agent under process/rdd-human-gates.md row `, with the condition it +relied on, in the answer text; the person confirms it at the ask. This +disclosure is a known limit: the store records the answer as the person's. + +**Residual risks.** Until the store enforces the rules, these risks are +accepted and stated: + +1. The server does not read the rules file and records every answer as the + signed-in person's. +2. The disclosure in the answer text is a convention the server does not + check. +3. The rules are not enforced: the agent assesses its own conditions, the + always-human areas, and whether a person declared an incident; when + unsure, a person decides. +4. The rules are read from the working tree, so a branch or an uncommitted + edit changes what the agent is shown; they count only once merged on the + default branch. +5. A harness running without prompts cannot ask: prompt-skipping modes are + denied rather than asked. +6. A missing CLI binary fails the hook open: the permission setting then + applies with no ask. +7. Direct API use with the developer's token bypasses the ask. +8. Other commands that record or apply a person's decision — a finding + disposition with a decision, an advance, a gate withdrawal, an entry + reapplied or re-entered, a demotion, an as-built acceptance applied — are + asked only where the workspace's permission settings place them on ask, + which not every harness honours. +9. Outage replay: an answer kept during a store outage can be replayed + without a new ask until BACKLOG-CLI-OUTAGE-09 is delivered. +10. On the store, fix-first evidence ordering is unverified: whether it + accepts RED evidence recorded at a revision before the entry answer is + not yet known. + ### Automatic transitions An agent or deterministic check may apply these only from a current trace-gate @@ -542,6 +662,10 @@ A change that stops being eligible — a finding, a wider boundary, an excluded area — leaves the lane for single-SR scope with its full packet and review. It is never forced through. +In the project's gate rules the lane is the `small_change_entry` row +(§Project gate rules). The end of the current lane authorization is shown +before it comes. + ### Autopilot Autopilot is for building larger scopes — greenfield systems, initiatives, @@ -616,25 +740,28 @@ failing required evidence keeps an item from `IN_REVIEW`: it stops acceptance, not the building of the next authorized action. **The grant.** A human who may answer entry and completion gates for the scope -grants autopilot once. The grant names: - -- the scope (Epics, an initiative, or a system); -- the end of the grant (a date) — the slice itself has no dates; -- any areas that stay out of it. - -It is recorded with its `USER:` source where the scope's decisions are -recorded: in each Epic's decisions as it is selected, in a store-backed -repository, and as `process/autopilot.md` in a file-backed one. The grant is -the human's answer, given in advance, to every entry gate in its scope. The -agent applies it by answering each such gate with the grant's `USER:` source. +grants autopilot once, by merging the autopilot preset into the project's +gate rules (§Project gate rules) with their own `Decided:` `USER:` source. The +grant names: + +- the scope (Epics, an initiative, or a system) — the rules file's `Scope`; +- the end of the grant (a date) — its `Expires`; the slice itself has no dates; +- any areas that stay out of it — the always-human areas, and any the human + adds. + +The grant is the human's answer, given in advance, to every entry gate in its +scope. The agent prepares each such entry answer under the rules file's +`entry` row, citing the grant's `USER:` source with the disclosure +§Project gate rules describes, and the person confirms it at the ask. It is never the answer to a completion gate. A grant ends at its date, when the -human withdraws it, or when its scope is done. +human withdraws it, or when its scope is done; then the default rules apply +again. **Under a current grant these rules change:** | Rule | Normal | Autopilot | |---|---|---| -| Entry gate | The human answers | The agent answers, citing the grant | +| Entry gate | The human answers | The agent prepares the answer under the `entry` row, citing the grant, and the person confirms it at the ask | | Cold review | Up to two rounds, blocking | One pass, then at most one narrow confirmation. Material findings are folded into the packet as tests or boundary lines, and the rest are logged. If the confirmation still fails, the item is built ahead of its record and the failure is logged. | | Packet completeness | Items 1–6 and the brief complete before review | Write what the builder needs; a gap the review finds is folded in or logged, never a stop | | Preflight facts (suspended selections, stale snapshots, drift, open holds) | Stop selection | Clear each with its documented verb, or log it and continue | @@ -679,7 +806,8 @@ Timings are observed, never reconstructed. answer: behavior, scope, user experience, meaning of data, priority. It asks each one when it arises, in plain words. Then it takes the most reasonable default and records it in the Epic's decisions as *assumed under autopilot, -pending confirmation*, with the grant's `USER:` source. Then it continues. +pending confirmation*, with the grant's `USER:` source, under the rules file's +`product_assumption` row. Then it continues. It waits for an answer only when a wrong guess is hard to undo: @@ -1142,6 +1270,7 @@ file-state/ WORK-SELECTION.md BACKLOG.md SLICE.md + HUMAN-GATES.md ``` `EPICS.md` stores optional grouping records. `REQUIREMENTS.md` stores URs, SRs, @@ -1151,9 +1280,10 @@ selections, and selection history. `BACKLOG.md` stores unrouted triage items and gap records. Derived queues and progress views — including the pending human-decision projection — are regenerated, not backed up separately. -`SLICE.md` is not a store record: it gives the shape of the tracked slice -file (§Slices), which is versioned in the repository in both kinds of store -and holds coordination only. +`SLICE.md` and `HUMAN-GATES.md` are not store records: they give the shapes +of the tracked slice file (§Slices) and the project's gate rules file +(§Project gate rules), which are versioned in the repository in both kinds of +store. The presets of the gate rules file are under `presets/`. Backlog, gap, and tooling-gap records are records of the store like every other: they are created, routed, and closed there, and their state is read diff --git a/README.md b/README.md index cf01d5b..5fd1944 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,8 @@ apply that model; `file-state/` serializes its records without redefining it. | `AGENTS.md` | shared agent policy and canonical entry point | | `PROCESS.md` | complete canonical process | | `skills/` | delivery orchestration, a slice run on autopilot (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-audit` for documents and citations | -| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shape of the tracked slice file | +| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shapes of the tracked slice file and gate rules file | +| `presets/` | the default and autopilot presets of a project's gate rules file, `process/rdd-human-gates.md` | ## Distribution diff --git a/file-state/GATES.md b/file-state/GATES.md index 2556dd3..c409179 100644 --- a/file-state/GATES.md +++ b/file-state/GATES.md @@ -22,7 +22,7 @@ only where `PROCESS.md` explicitly permits it, such as an attributable demotion. - **Fingerprint:** «approval-scope or evidence fingerprint and the exact inputs evaluated, per PROCESS.md» - **State:** «trace: PENDING / PASS / FAIL / STALE — human: DRAFT / OPEN / ANSWERED / CLOSED / SUPERSEDED» - **Verdict / answer:** «trace verdict with exact blockers, or the human answer as given» -- **Actor / evaluator:** «real human actor and role for a human gate; evaluating agent or check for a trace gate» +- **Actor / evaluator:** «real human actor and role for a human gate; evaluating agent or check for a trace gate». An answer the agent prepared under a gate rules row carries `decided by the agent under process/rdd-human-gates.md row ` and the condition it relied on in its answer text; the actor is still the person who confirmed it - **Sources:** «USER:/DOC:/CODE:/TEST:/RUN:/EPIC: support for the verdict or answer» - **Timestamps:** «evaluated/opened at; answered at; closed at» - **Application:** «NOT_APPLICABLE / PENDING / APPLIED / FAILED» at «revision» diff --git a/file-state/HUMAN-GATES.md b/file-state/HUMAN-GATES.md new file mode 100644 index 0000000..f957ae5 --- /dev/null +++ b/file-state/HUMAN-GATES.md @@ -0,0 +1,88 @@ +# Gate rules file + +> Canonical shape of a project's gate rules. `PROCESS.md` §Project gate rules +> defines the decision points and what each must carry; this file says who +> decides each one. It is a tracked project file at +> `process/rdd-human-gates.md`, versioned in the repository and changed the +> way the project reviews any other repository change, in a store-backed and a +> file-backed repository alike. It is not a store record. + +Installation seeds the file once from `presets/default.md` and never +overwrites it; a deleted file is seeded again. `presets/autopilot.md` is the +autopilot preset a process owner copies in to grant autopilot. + +```markdown +# Project gate rules + +- **Decided:** «USER: source of the process owner who merged this file» +- **Preset:** default | autopilot | custom +- **Scope:** «Epic or requirement ids, comma-separated; omit the line for the whole System» +- **Expires:** «YYYY-MM-DD; omit the line when no row needs it» + +| Decision | Decided by | When the agent may decide | Always a human when | +|---|---|---|---| +| «row» | «decider» | «condition, or —» | «areas separated by spaces, or —» | +``` + +## Header lines + +- **Decided** is required: the `USER:` source of the process owner who merged + the file on the project's default branch. The seeded default carries + `kit-default` instead; that marker is valid only while the file is + identical to the kit's `presets/default.md`, and the file is then shown as + "kit default, not decided by this project". A file that differs from the + kit's default by any byte needs its own `USER:` source. +- **Preset** names where the file started: `default`, `autopilot`, or + `custom`. +- **Scope** is optional. Absent, the rules cover the whole System. +- **Expires** is optional, except that a file in which `entry`, + `slice_addition`, `product_assumption`, or `completion` is the agent's must + carry it. The date is inclusive: the rules expire from the next day, UTC. + +A placeholder or malformed value is refused. Rules that are expired, refused, +or missing mean the default preset; the session says so at its start. + +## Rows + +Every row appears exactly once. A row the agent may decide accepts only its +own condition. + +| Row | Decided by | Agent condition | +|---|---|---| +| `entry` | human, agent | `plan_review_passed` | +| `slice_addition` | human, agent | `narrow_review_passed` | +| `small_change_entry` | human, agent | `lane_authorization_current` | +| `pre_approved_entry` | human, agent | `user_source_names_scope` | +| `defect_fix` | human, agent | `failing_test_reproduces` | +| `incident_fix` | human, agent | `incident_declared` | +| `product_assumption` | human, agent | `reversible_inside_scope` | +| `completion` | human, agent | `evidence_complete` | +| `candidate_confirmation` | human | — | +| `demotion` | human | — | +| `acceptance_guide` | required, not_required | — | +| `tester_signoff` | required, not_required | — | +| `baseline_acceptance` | human | — | +| `gate_rules` | human | — | +| `lane_authorization` | human | — | + +`incident_declared` holds only when a person's words declaring the incident +are quoted as a `USER:` source in the fix-first gap record; the agent never +declares one. + +## Always-human areas + +`sign_in`, `payments`, `existing_data`, `external_contract`, or `—` for none. +When a change touches an area a row names, a person decides that row. An +`incident_fix` row the agent may decide always names `sign_in`, `payments`, +and `existing_data`. + +## Refusals + +A file is refused, naming the line, for: an unknown row, condition, or area; a +condition another row owns; the agent on `candidate_confirmation`, +`demotion`, or an always-human row; an agent `incident_fix` row whose areas +omit `sign_in`, `payments`, or `existing_data`; a malformed or placeholder +`Scope` or `Expires`; an agent `entry`, `slice_addition`, +`product_assumption`, or `completion` row without `Expires`; a missing row; a +missing `Decided` source; and the `kit-default` marker on a file that differs +from the kit's default. diff --git a/presets/autopilot.md b/presets/autopilot.md new file mode 100644 index 0000000..10f270e --- /dev/null +++ b/presets/autopilot.md @@ -0,0 +1,24 @@ +# Project gate rules + +- **Decided:** USER:: +- **Preset:** autopilot +- **Scope:** +- **Expires:** + +| Decision | Decided by | When the agent may decide | Always a human when | +|---|---|---|---| +| entry | agent | plan_review_passed | sign_in payments existing_data external_contract | +| slice_addition | agent | narrow_review_passed | sign_in payments existing_data external_contract | +| small_change_entry | agent | lane_authorization_current | sign_in payments existing_data external_contract | +| pre_approved_entry | agent | user_source_names_scope | sign_in payments existing_data external_contract | +| defect_fix | agent | failing_test_reproduces | sign_in payments existing_data external_contract | +| incident_fix | agent | incident_declared | sign_in payments existing_data | +| product_assumption | agent | reversible_inside_scope | sign_in payments existing_data external_contract | +| completion | human | — | — | +| candidate_confirmation | human | — | — | +| demotion | human | — | — | +| acceptance_guide | required | — | — | +| tester_signoff | not_required | — | — | +| baseline_acceptance | human | — | — | +| gate_rules | human | — | — | +| lane_authorization | human | — | — | diff --git a/presets/default.md b/presets/default.md new file mode 100644 index 0000000..e247723 --- /dev/null +++ b/presets/default.md @@ -0,0 +1,22 @@ +# Project gate rules + +- **Decided:** kit-default +- **Preset:** default + +| Decision | Decided by | When the agent may decide | Always a human when | +|---|---|---|---| +| entry | human | — | — | +| slice_addition | human | — | — | +| small_change_entry | agent | lane_authorization_current | sign_in payments existing_data external_contract | +| pre_approved_entry | human | — | — | +| defect_fix | human | — | — | +| incident_fix | human | — | — | +| product_assumption | human | — | — | +| completion | human | — | — | +| candidate_confirmation | human | — | — | +| demotion | human | — | — | +| acceptance_guide | required | — | — | +| tester_signoff | not_required | — | — | +| baseline_acceptance | human | — | — | +| gate_rules | human | — | — | +| lane_authorization | human | — | — | diff --git a/skills/rdd-autopilot/SKILL.md b/skills/rdd-autopilot/SKILL.md index 2269aef..2e14f94 100644 --- a/skills/rdd-autopilot/SKILL.md +++ b/skills/rdd-autopilot/SKILL.md @@ -13,16 +13,20 @@ bounds differ from §Autopilot, §Autopilot applies. ## Start -1. **Find the grant.** Read the grant that covers the scope and check that it - is current. Without one, ask the human for it in one message that names: +1. **Find the grant.** The grant is the autopilot preset merged into the + project's gate rules, `process/rdd-human-gates.md`, with the human's + `Decided:` source, `Scope`, and `Expires` (`PROCESS.md` §Project gate + rules). Read it and check that it is current and covers the scope. + Without one, ask the human for it in one message that names: - the slice, or the scope to open one for; - the grant's end date (the slice itself has no dates); - any excluded areas; - - what the human gives up: per-Epic entry approval and waiting on - questions; + - what the human gives up: writing each entry decision and waiting on + questions — each entry answer the agent prepares is confirmed with one + keystroke at the ask; - what the human keeps: the completion answer at slice end, and merges. - Record the answer as §Autopilot says. + The human merges the filled preset; §Autopilot says what it grants. 2. **Run `rdd-start`'s preflight, without stopping on it.** Clear each preflight fact with its documented verb: reconcile, refresh, or release a selection this slice does not need. If a fact will not clear, log it and @@ -65,8 +69,11 @@ bounds differ from §Autopilot, §Autopilot applies. correctness, security, data integrity or data loss, contract, traceability, testability — and any changed scope or acceptance, and only that change. -3. **Enter.** Answer the entry gate with the grant's `USER:` source, and apply - it. +3. **Enter.** Prepare the entry answer under the rules file's `entry` row, + citing the grant's `USER:` source with the disclosure `decided by the + agent under process/rdd-human-gates.md row entry`; the person confirms it + at the ask. Then apply it. A change that touches an always-human area + waits for the person's own decision. 4. **Build the journey in connected batches** (`rdd-build`, with §Autopilot's batch cadence): - write the batch's representative failing tests, with a failing diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index e5d57ac..c5583fc 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -53,8 +53,13 @@ records, and derived views. single items, which stay `IN_REVIEW`. A slice presents one completion brief, carried by each member's completion gate and answered item by item. -6. Do not answer the gate for the human. If the authorized human answers, - record the real actor, role, exact scope, answer, and `USER:` source. +6. Do not answer the gate for the human. Completion is a person's in both + shipped gate rules presets; where a project's own rules give the + `completion` row to the agent, prepare the answer with the disclosure + `PROCESS.md` §Project gate rules describes, and a scope that touches an + always-human area is still completed by a person. If the authorized human + answers, record the real actor, role, exact scope, answer, and `USER:` + source. 7. Apply `DONE` only to accepted named entities that independently satisfy the complete applicable predicate. The answer and its application are separate steps: apply member requirements before a named epic, and report an answer diff --git a/skills/rdd-entry-review/SKILL.md b/skills/rdd-entry-review/SKILL.md index 953aa15..d024040 100644 --- a/skills/rdd-entry-review/SKILL.md +++ b/skills/rdd-entry-review/SKILL.md @@ -33,8 +33,17 @@ packet, cold-review findings, current gate records, and relevant sources. the current lane authorization, which names the human who answered it; a missing, expired, exhausted or non-covering authorization stops here and the change follows the single-SR entry. -5. Do not answer the gate for the human. If the authorized human answers, - record the real actor, role, scope, answer, and `USER:` source; apply only +5. Do not answer the gate for the human. Where the project's gate rules + (`PROCESS.md` §Project gate rules) give the row — `entry`, + `slice_addition`, or `pre_approved_entry` — to the agent, its condition + holds, and the change touches none of the row's always-human areas, + prepare the answer: cite the grant's or the pre-approval's `USER:` source + and write `decided by the agent under process/rdd-human-gates.md row + ` with the condition in the answer text; the person confirms it at + the ask. When unsure about an area, a person decides. In ModernPath, + `factory answer` and `process lane approve` ask the person; a harness that + cannot ask refuses them, and the person runs them. If the authorized human + answers, record the real actor, role, scope, answer, and `USER:` source; apply only named transitions and reconcile all affected records. The answer and its application are two steps: apply member requirements before a named epic, and report an answer that is recorded but not yet applied as exactly that. diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index fc3ca81..b3bcd45 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -37,6 +37,13 @@ when local documents lack the information or you need an up-to-date answer. 5. Count the suspended selections. More than one is a preflight fact: report each with its suspended status and reason, and name the mitigation — resume one, release one — before selecting new work. +6. Read the project's gate rules, `process/rdd-human-gates.md` + (`PROCESS.md` §Project gate rules), and report them in one line: the kit + default, not decided by this project, or the process owner's decision with + its source; the rows the agent may decide; and the `Scope` and `Expires` + date, with a warning when the end is within seven days. Expired, refused, + or missing rules mean the default — say so. The rules count only once + merged on the default branch. The pending-decision projection may already have been delivered into the session by the host — a session-start brief injected as context rather than @@ -123,7 +130,8 @@ its skill; a change that meets the small-change lane's eligibility under a current lane authorization is planned, reviewed and entered through that lane: `rdd-discover`, `rdd-plan`, `rdd-cold-review`, `rdd-entry-review`, `rdd-build`, `rdd-verify`, `rdd-completion-review`, or `rdd-deliver` for the complete loop. When a current autopilot grant covers the scope, or the human -asks for one, hand off to `rdd-autopilot` instead. Source-inventory +asks for one, hand off to `rdd-autopilot` instead; the grant is the +autopilot preset merged into the project's gate rules. Source-inventory onboarding uses `rdd-reverse-engineer`. For genuine source-scoped baseline requirements still in PENDING_VERIFICATION, diff --git a/skills/rdd-triage/SKILL.md b/skills/rdd-triage/SKILL.md index 5e6e0de..6f2cbfa 100644 --- a/skills/rdd-triage/SKILL.md +++ b/skills/rdd-triage/SKILL.md @@ -38,7 +38,13 @@ order. `PROPOSED`. A defect or invalidated required evidence returns affected requirements and Epics to `IN_PROGRESS`. Preserve prior acceptance receipts; reopening does not waive the entry prerequisites for changing code or tests. -6. Re-evaluate stale gates and evidence, then reconcile authoritative records, +6. Record a fix-first change — a defect or incident light path the project's + gate rules turn on (`PROCESS.md` §Project gate rules) — as a gap record + naming the fix-first. For an incident, quote the person's words declaring + it as a `USER:` source in that gap record; never declare an incident + yourself. Route its SR, entry answer, and evidence before other work is + selected. +7. Re-evaluate stale gates and evidence, then reconcile authoritative records, release scope, work selection, and derived views. Never promote to `TODO` without the strict entry gate. From 9e9f97ddb993c8295cafed17938d3c782c602c58 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:06:47 +0300 Subject: [PATCH 07/11] docs(process): acceptance test step before completion Completion gains an acceptance test step between the delivered-revision check and the completion trace: the agent drafts and completes an acceptance test guide (a tracked file beside the slice file) for a human tester, after the last record edit of the covered scopes. Tester results are acceptance test results naming the tester, environment and tested revision. The project's gate rules decide whether the guide and the tester's sign-off are required; with sign-off required, every criterion not proven by automated tests needs a current tester pass. Adds the rdd-acceptance skill and file-state/ACCEPTANCE-GUIDE.md; rdd-completion-review runs the step. REQ-CROSS-581 (process side) Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 +- PROCESS.md | 52 ++++++++++++++-- README.md | 6 +- file-state/ACCEPTANCE-GUIDE.md | 88 +++++++++++++++++++++++++++ skills/rdd-acceptance/SKILL.md | 73 ++++++++++++++++++++++ skills/rdd-autopilot/SKILL.md | 7 ++- skills/rdd-completion-review/SKILL.md | 8 +++ skills/rdd-deliver/SKILL.md | 4 +- 8 files changed, 229 insertions(+), 14 deletions(-) create mode 100644 file-state/ACCEPTANCE-GUIDE.md create mode 100644 skills/rdd-acceptance/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index d0a8907..4113460 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,8 @@ serialization shapes; it does not contain a project's live delivery state. - [`skills/`](skills/) contains focused procedures that apply the process. - [`file-state/`](file-state/) contains the canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the - shapes of the tracked slice file and gate rules file; + shapes of the tracked slice file, gate rules file, and acceptance test + guide; [`presets/`](presets/) holds the default and autopilot gate rules. - Project instructions own only project-specific rules such as architecture, repository topology, commands, environments, and test gates. They reference @@ -44,6 +45,8 @@ on a decision, or what is blocked: use `skills/rdd-reverse-engineer-verify/SKILL.md` and `skills/rdd-reverse-engineer-accept/SKILL.md` for source-scoped baselines with existing proof (one human acceptance directly to DONE); + `skills/rdd-acceptance/SKILL.md` runs the acceptance test step inside + completion review; `skills/rdd-audit/SKILL.md` is a shared utility other passes invoke, not a phase; 4. read the relevant product sources, requirement records, optional epic, and diff --git a/PROCESS.md b/PROCESS.md index 33af5a9..4e856c9 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -623,6 +623,7 @@ slice: | Tests while building | Focused tests per batch | | Full verification | Once, at slice end, at the delivered revision | | Independent code review | One review over the whole change, where the slice needs one (§Planning and readiness) | +| Acceptance test guide | One guide for a human tester, after full verification and before completion (§Evidence and completion) | | Completion | One completion brief; each member's completion gate carries it and is answered with its own confirmation, item by item | The stages in each member's plan (§Entry packet item 5) order its connected @@ -847,7 +848,8 @@ packets — against its requirements and tests. The human then gets one page: - the coverage matrix: remaining clauses and what is still unavailable; - the assumed decisions to confirm or change; - the log; -- the review's findings. +- the review's findings; +- the acceptance test guide and its results (§Evidence and completion). The human answers completion item by item, as in a lane batch. A rejected item stays `IN_REVIEW`. A changed assumption is triaged into the next slice. @@ -1020,7 +1022,7 @@ focused skill alone only when the requested scope explicitly ends at that pass. | Verify entered work requiring tests | `rdd-verify` | Current UR upper or SR lower evidence; eligible requirement in `IN_REVIEW` | | Verify existing baseline | `rdd-reverse-engineer-verify` | Complete applicable current assertion/execution proof and separate repository integration observations; exact eligibility packet | | Accept existing baseline | `rdd-reverse-engineer-accept` | One reviewed human decision atomically applied from `PENDING_VERIFICATION` to `DONE`, with durable receipt; compliance unchanged | -| Deliver/complete | `rdd-completion-review` | Delivered revision, reconciled records, completion trace, and applied human result | +| Deliver/complete | `rdd-completion-review`, with `rdd-acceptance` for the acceptance test step | Delivered revision, reconciled records, acceptance test guide and results where the project's gate rules require them, completion trace, and applied human result | | Route change | `rdd-triage` | Discovery assigned to the earliest phase it invalidates | Before each phase, reconcile answered gates and state, then select the earliest @@ -1222,6 +1224,42 @@ pass does not stand in for it — until it is re-evaluated at the current fingerprint. Excluded-only proof does not block current work; mixed-scope proof retains its live obligations. +**Acceptance test step.** After the evidence is confirmed current at the +delivered revision — for a slice, its one full verification — and before the +completion trace, the agent drafts and completes an acceptance test guide for +a human tester (`rdd-acceptance`). The guide is a tracked file: +`process/slices//acceptance-guide.md` beside the slice file, or +`process/acceptance/.md` for an Epic or requirement outside a slice. +Testers read it in the change under review. It is not a packet section and +moves no aggregate, review, or approval. Its shape is +`file-state/ACCEPTANCE-GUIDE.md`, in six sections: what changed, in product +language, per user requirement; where to test — environment, revision, +build, test data, sign-in; manual steps per user scenario with the expected +result; what the automated tests already prove, per acceptance criterion, +with the run that proves it; a criteria table; and the known gaps, +assumptions, and what is out of scope. Its header records the aggregate of +every scope it covers at drafting, so a later record edit makes it stale: it +is drafted after the last record edit of those scopes. + +A tester's result is an acceptance test result — evidence of kind +`acceptance` against a criterion or scenario, naming the tester as a `USER:` +source, the environment, and the revision the tester tested, never the +recorder's own checkout. An acceptance test result never counts as automated +evidence, and it is not the as-built acceptance of an existing baseline. + +The project's gate rules decide what the step requires (§Project gate +rules). With `acceptance_guide` required, as in both presets, a slice's +completion needs a current guide with every section filled; with +`not_required`, a missing guide is disclosed in one line. With +`tester_signoff` required — not required in both presets — every criterion +or scenario not proven by automated evidence needs a current acceptance pass: +its latest acceptance test result is a pass, at the delivered revision or an +ancestor of it, recorded at or after the guide was drafted; an automated pass +on the owning requirement counts as automated proof. Outside a slice, a +missing or stale guide is disclosed in one line and does not stop +completion. The completion brief links the guide and shows its results beside +the automated evidence and, on a deploy path, which revision runs where. + | Item | `DONE` predicate after human acceptance | |---|---| | SR | Its lower trace is delivered, current, and reconciled | @@ -1271,6 +1309,7 @@ file-state/ BACKLOG.md SLICE.md HUMAN-GATES.md + ACCEPTANCE-GUIDE.md ``` `EPICS.md` stores optional grouping records. `REQUIREMENTS.md` stores URs, SRs, @@ -1280,10 +1319,11 @@ selections, and selection history. `BACKLOG.md` stores unrouted triage items and gap records. Derived queues and progress views — including the pending human-decision projection — are regenerated, not backed up separately. -`SLICE.md` and `HUMAN-GATES.md` are not store records: they give the shapes -of the tracked slice file (§Slices) and the project's gate rules file -(§Project gate rules), which are versioned in the repository in both kinds of -store. The presets of the gate rules file are under `presets/`. +`SLICE.md`, `HUMAN-GATES.md`, and `ACCEPTANCE-GUIDE.md` are not store +records: they give the shapes of the tracked slice file (§Slices), the +project's gate rules file (§Project gate rules), and the acceptance test +guide (§Evidence and completion), which are versioned in the repository in +both kinds of store. The presets of the gate rules file are under `presets/`. Backlog, gap, and tooling-gap records are records of the store like every other: they are created, routed, and closed there, and their state is read diff --git a/README.md b/README.md index 5fd1944..459b0ee 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ SR -> CODE -> TEST_CASE -> TEST_RESULT Normal development passes planning, technical review, human entry, red-first evidence, implementation, cleanup, verification, delivery, reconciliation, -and human completion. An eligible source-scoped baseline uses existing-proof +the acceptance test step, and human completion. An eligible source-scoped baseline uses existing-proof verification and one human acceptance instead; publication alone proves neither verification nor delivery. @@ -45,8 +45,8 @@ apply that model; `file-state/` serializes its records without redefining it. |---|---| | `AGENTS.md` | shared agent policy and canonical entry point | | `PROCESS.md` | complete canonical process | -| `skills/` | delivery orchestration, a slice run on autopilot (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-audit` for documents and citations | -| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shapes of the tracked slice file and gate rules file | +| `skills/` | delivery orchestration, a slice run on autopilot (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-acceptance` for the acceptance test guide before completion; `rdd-audit` for documents and citations | +| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shapes of the tracked slice file, gate rules file, and acceptance test guide | | `presets/` | the default and autopilot presets of a project's gate rules file, `process/rdd-human-gates.md` | ## Distribution diff --git a/file-state/ACCEPTANCE-GUIDE.md b/file-state/ACCEPTANCE-GUIDE.md new file mode 100644 index 0000000..55bd289 --- /dev/null +++ b/file-state/ACCEPTANCE-GUIDE.md @@ -0,0 +1,88 @@ +# Acceptance test guide + +> Canonical shape of an acceptance test guide. `PROCESS.md` §Evidence and +> completion defines the acceptance test step; `rdd-acceptance` runs it. A +> guide is a tracked project file — `process/slices//acceptance-guide.md` +> beside the slice file, or `process/acceptance/.md` for an Epic or +> requirement outside a slice — versioned in the repository in a store-backed +> and a file-backed repository alike. It is not a store record and not a +> packet section: it moves no aggregate, review, or approval. + +The guide is written for a human tester who has not read the records, in plain +product language. Where the agent must still write, the draft carries a fill +marker, `[[fill: ]]`; a guide with an open fill marker is not +finished. + +```markdown +--- +scope: «SLICE id, Epic id, or requirement id» +drafted_at: «timestamp, UTC» +aggregates: + «covered scope id»: «its packet aggregate at drafting» +draft_body: sha256:«hash of the body as drafted» +--- + +# Acceptance test guide — «scope title in plain product language» + +## 1. What changed +«per user requirement, in product language» + +## 2. Where to test +- Environment: «name» +- Revision: «revision deployed there» +- Build: «build or version» +- Test data: «what to use, and what never to touch» +- Sign-in: «which account or role» + +## 3. Manual checks +### «UR scenario id» — «scenario in plain words» +- Given: «starting state» +- When: «what the tester does» +- Then: «what the tester observes» +- Steps: + 1. «step» +- Expected result: «what counts as a pass» + +## 4. What the automated tests prove +| Criterion | Proving run | +|---|---| +| «criterion or scenario id» | «pass or fail — revision and time», «via «requirement id»: pass or fail — revision», or not covered | + +## 5. Criteria +| Criterion | Coverage | Automated result | Acceptance test result and tester | +|---|---|---|---| +| «criterion or scenario id» | automated / via «requirement id» / manual / not covered | «result» | «pass or fail — tester (USER: source), environment, revision» | + +## 6. Known gaps, assumptions, and out of scope +- «gap, assumption taken during the work, or exclusion» +``` + +## Header + +- `scope` names the slice, Epic, or requirement the guide covers. +- `drafted_at` is when the guide was drafted. Tester passes recorded before it + are not current for this guide. +- `aggregates` records the packet aggregate of every covered scope at + drafting — for a slice, each member's. When a covered scope's aggregate + moves, the guide is stale; draft it again after the last record edit. +- `draft_body` is the hash of the body as drafted. A guide whose body no + longer matches it has been edited and is never overwritten by a new draft. + +## Sections + +1. **What changed** — per user requirement, in product language. +2. **Where to test** — environment, revision, build, test data, sign-in. On a + deploy path, the environment's latest recorded deployment names the + revision. +3. **Manual checks** — per user scenario, steps with the expected result. +4. **What the automated tests prove** — per criterion, the run that proves + it. Only automated evidence fills this section; acceptance test results, + manual notes, migrations, and deployments never do. +5. **Criteria** — every applicable SR criterion and UR scenario of the covered + scopes once, excluding `DEFERRED` and `OBSOLETE` requirements, with its + coverage, automated result, and latest acceptance test result. +6. **Known gaps, assumptions, and out of scope** — including the assumptions + taken during the work and anything not covered. + +Acceptance test results are recorded as evidence of kind `acceptance`, never +in this file; the criteria table shows them as read at drafting or refresh. diff --git a/skills/rdd-acceptance/SKILL.md b/skills/rdd-acceptance/SKILL.md new file mode 100644 index 0000000..afc4aaa --- /dev/null +++ b/skills/rdd-acceptance/SKILL.md @@ -0,0 +1,73 @@ +--- +name: rdd-acceptance +description: Draft and complete the acceptance test guide for a slice, Epic, or requirement after its full verification at the delivered revision and before the completion trace, hand it to a human tester, and record the tester's acceptance test results. Use inside completion review when the project's gate rules require the guide, or when a tester will check the change by hand. Grants no completion and is not the as-built acceptance of an existing baseline. +--- + +# Write and run the acceptance test guide + +Read the project `AGENTS.md`, canonical `PROCESS.md` +(`.modernpath/rdd/PROCESS.md` in a consuming repository) — especially +§Evidence and completion's acceptance test step and §Project gate rules — the +shape `file-state/ACCEPTANCE-GUIDE.md`, and the project's gate rules +(`process/rdd-human-gates.md`). In ModernPath, the installed `mp-process-cli` +skill names the commands that draft and show the guide and record results. + +## When + +Run this step after the full verification at the delivered revision — for a +slice, its one full verification — and before the completion trace. + +Draft the guide after the last record edit of the scopes it covers. Its +header records the aggregate of every covered scope at drafting, and any +later record or packet edit moves that aggregate and makes the guide stale. +If a record must change after drafting, draft again; earlier tester passes +recorded before the new draft are no longer current. + +## Procedure + +1. Read the `acceptance_guide` and `tester_signoff` rows of the project's + gate rules. Expired, refused, or missing rules mean the default preset: + the guide is required for a slice and the tester's sign-off is not. +2. Draft the guide at its path — `process/slices//acceptance-guide.md` + beside the slice file, or `process/acceptance/.md` outside a + slice — through the project's sanctioned tool where it offers a drafting + step, otherwise by hand in the shape. Never overwrite a guide someone has + edited: put the fresh draft beside it, uncommitted, and merge by hand. +3. Fill every fill marker in plain product language, for a tester who has + not read the records: + - what changed, per user requirement; + - where to test: environment, revision, build, test data, and sign-in; + - the manual steps per user scenario, each with its expected result; + - what the automated tests already prove, per acceptance criterion, with + the run that proves it — never more than the evidence shows; + - the criteria table: each criterion or scenario once, marked automated, + via its requirement, manual, or not covered, with its results; + - the known gaps, the assumptions taken during the work, and what is out + of scope. +4. Commit the guide with the change, so the tester reads it in the change + under review, and give the tester its path. +5. Record each tester result as an acceptance test result — evidence of kind + `acceptance` against the criterion or scenario — naming the tester as a + `USER:` source, the environment, and the revision the tester tested: the + revision the tester names, otherwise the environment's latest recorded + deployment. Never record the recorder's own checkout as the tested + revision; when neither is known, ask the tester instead of recording. +6. Check the guide's currency and results through the sanctioned tool. Where + the tester's sign-off is required, every criterion or scenario not proven + by automated evidence needs a current acceptance pass: its latest + acceptance test result is a pass, at the delivered revision or an ancestor + of it, recorded at or after the guide was drafted. A failing acceptance + test result is a finding: route it through `rdd-triage`. +7. Hand back to `rdd-completion-review` for the completion trace. The + completion brief links the guide and shows its results beside the + automated evidence. + +Outside a slice, a missing or stale guide is disclosed in one line and does +not stop completion. + +## Report + +Report the guide's path and whether it is current, any fill marker still +open, the criteria split between automated, manual, and not covered, the +acceptance test results with tester, environment, and revision, the gaps, and +the handoff. diff --git a/skills/rdd-autopilot/SKILL.md b/skills/rdd-autopilot/SKILL.md index 2e14f94..d7615bd 100644 --- a/skills/rdd-autopilot/SKILL.md +++ b/skills/rdd-autopilot/SKILL.md @@ -142,13 +142,16 @@ asks. evidence. 3. **Review.** Run one independent review of everything the slice built, from the code at the branch head, against its requirements and tests - (`rdd-completion-review`'s audit). Record the findings. + (`rdd-completion-review`'s audit). Record the findings. Then write the + acceptance test guide (`rdd-acceptance`) where `rdd-completion-review` + places it. 4. **Present one page:** - the journeys and primary actions a user can now complete, with evidence; - the coverage matrix: remaining clauses, and what is not built and why; - assumed decisions to confirm; - the log; - - review findings. + - review findings; + - the acceptance test guide and its results. Give links to the working-set files. 5. **Apply** the human's completion answers item by item. A rejected item diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index c5583fc..c2ceab7 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -41,6 +41,12 @@ records, and derived views. `skills/rdd-audit/SKILL.md` to verify that delivered records, citations, and documents still describe the code; a finding it surfaces is a stop condition or routes through `rdd-triage`, never a silent correction. + Then run `rdd-acceptance` for the acceptance test step (`PROCESS.md` + §Evidence and completion) when the project's gate rules require the guide + or a tester will check the change. For a slice, a missing, stale, or + unfinished required guide stops completion here, as does a missing + current acceptance pass where the tester's sign-off is required; outside a + slice, a missing or stale guide is disclosed in one line. 5. Record completion trace `PASS` only for the exact eligible fingerprint, and before the human gate exists, so the gate names it as its prerequisite. An applicable `STALE` member-scoped cold-review trace from an earlier round blocks an @@ -48,6 +54,8 @@ records, and derived views. epic-scoped pass does not stand in for it. Only then make the scoped human completion gate `OPEN` and present its brief and linked list of relevant working-set files before asking for acceptance, following `PROCESS.md` §Gates. + Link the acceptance test guide and show its results beside the automated + evidence. Small changes may be completed together in one lane-batch gate that lists each change with its evidence and review verdict; the human may reject single items, which stay `IN_REVIEW`. A slice presents one completion diff --git a/skills/rdd-deliver/SKILL.md b/skills/rdd-deliver/SKILL.md index 9f72ad1..07439a6 100644 --- a/skills/rdd-deliver/SKILL.md +++ b/skills/rdd-deliver/SKILL.md @@ -45,8 +45,8 @@ requirements remain normal development work. has a current passing trace and is `IN_REVIEW` or already `DONE`. Keep unchanged DONE members as proof dependencies, without reaccepting them. 6. Apply `rdd-completion-review` to audit, deliver, recheck the delivered - revision, reconcile records, run the completion trace gate, and apply the - human completion answer. + revision, reconcile records, run the acceptance test step (`rdd-acceptance`), + run the completion trace gate, and apply the human completion answer. 7. Apply `rdd-triage` whenever a discovery, contradiction, requested change, or invalidation alters the selected trace. Resume at the earliest phase it invalidates. From ca4bcb46890106fca0fac6df4e306c78f21fa036 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:25:52 +0300 Subject: [PATCH 08/11] docs(process): complete on the project's declared integration path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit EPIC-CLI-DELIVERY-PATH replaced the exact default-branch-tip rule with completion on the path a project declares in process/integration-path.md: merge (the default) or deploy. On merge the fetched default branch must contain every requirement's tested commit wherever the checkout sits; on deploy the deployed commit is named and a deployment run records the environment and smoke checks. Failing, stale, missing or uncontained evidence is refused by name before any write; squash or rebase merges re-run the tests at the merged commit. PROCESS.md §Evidence and completion and rdd-completion-review describe the paths; file-state/INTEGRATION-PATH.md gives the file shape the CLI parser reads. As-built acceptance keeps its exact-tip integration observation, and PROCESS.md and rdd-reverse-engineer now say the declared path does not change it. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 4 ++-- PROCESS.md | 33 ++++++++++++++++++++++----- README.md | 2 +- file-state/INTEGRATION-PATH.md | 32 ++++++++++++++++++++++++++ skills/rdd-completion-review/SKILL.md | 14 ++++++++++-- skills/rdd-reverse-engineer/SKILL.md | 4 +++- 6 files changed, 77 insertions(+), 12 deletions(-) create mode 100644 file-state/INTEGRATION-PATH.md diff --git a/AGENTS.md b/AGENTS.md index 4113460..e140aab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,8 +12,8 @@ serialization shapes; it does not contain a project's live delivery state. - [`skills/`](skills/) contains focused procedures that apply the process. - [`file-state/`](file-state/) contains the canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the - shapes of the tracked slice file, gate rules file, and acceptance test - guide; + shapes of the tracked slice file, gate rules file, acceptance test guide, + and integration path declaration; [`presets/`](presets/) holds the default and autopilot gate rules. - Project instructions own only project-specific rules such as architecture, repository topology, commands, environments, and test gates. They reference diff --git a/PROCESS.md b/PROCESS.md index 4e856c9..86b0694 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -1053,6 +1053,8 @@ A dedicated existing-behavior path may move exactly reviewed URs/SRs directly to Retain the observed remote identity. If the integration check does not validate it against an independently declared repository identity, disclose that limitation; a local origin setting alone does not establish repository ownership. + The project's declared integration path (§Evidence and completion) governs + completion and does not change this observation. - A current eligibility trace evaluated through the sanctioned tool supports the exact human decision. Its attributed reviewed answer and guarded application recheck the complete @@ -1218,7 +1220,24 @@ A normal completion human gate may open only when named items are `IN_REVIEW`, code is delivered, evidence is current at the delivered revision, state is reconciled, candidate relations are excluded, and gaps/deferrals/decisions are disclosed. The delivered revision is the one the authorized integration path produced, -not the branch head that fed it. An applicable member-scoped trace from an +not the branch head that fed it. + +**Integration path.** A project declares how it delivers in the tracked file +`process/integration-path.md` (shape: `file-state/INTEGRATION-PATH.md`): +`merge`, the default when the file is absent, or `deploy`. A person declares +it in a reviewed commit. On `merge`, the delivered revision is the fetched +tip of the remote default branch, and that branch must contain the tested +commit of every requirement being completed, wherever the checkout sits — on +another branch or behind the tip. On `deploy`, the deployed commit is named +as the delivered revision, and the completion records a deployment run that +names the environment and the smoke checks. On both, a requirement whose +latest evidence is failing, stale, or missing, or whose tested commit is not +contained in the delivered revision, is refused by name before anything is +written. A squash or rebase merge leaves the tested commit outside the +default branch, so containment cannot be proven; the team re-runs the tests +at the merged commit and records that run. + +An applicable member-scoped trace from an earlier round that is `STALE` still counts against its Epic — an Epic-scoped pass does not stand in for it — until it is re-evaluated at the current fingerprint. Excluded-only proof does not block current work; mixed-scope proof @@ -1310,6 +1329,7 @@ file-state/ SLICE.md HUMAN-GATES.md ACCEPTANCE-GUIDE.md + INTEGRATION-PATH.md ``` `EPICS.md` stores optional grouping records. `REQUIREMENTS.md` stores URs, SRs, @@ -1319,11 +1339,12 @@ selections, and selection history. `BACKLOG.md` stores unrouted triage items and gap records. Derived queues and progress views — including the pending human-decision projection — are regenerated, not backed up separately. -`SLICE.md`, `HUMAN-GATES.md`, and `ACCEPTANCE-GUIDE.md` are not store -records: they give the shapes of the tracked slice file (§Slices), the -project's gate rules file (§Project gate rules), and the acceptance test -guide (§Evidence and completion), which are versioned in the repository in -both kinds of store. The presets of the gate rules file are under `presets/`. +`SLICE.md`, `HUMAN-GATES.md`, `ACCEPTANCE-GUIDE.md`, and `INTEGRATION-PATH.md` +are not store records: they give the shapes of the tracked slice file +(§Slices), the project's gate rules file (§Project gate rules), the +acceptance test guide, and the project's integration path declaration +(§Evidence and completion), which are versioned in the repository in both +kinds of store. The presets of the gate rules file are under `presets/`. Backlog, gap, and tooling-gap records are records of the store like every other: they are created, routed, and closed there, and their state is read diff --git a/README.md b/README.md index 459b0ee..ce92265 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ apply that model; `file-state/` serializes its records without redefining it. | `AGENTS.md` | shared agent policy and canonical entry point | | `PROCESS.md` | complete canonical process | | `skills/` | delivery orchestration, a slice run on autopilot (`rdd-autopilot`), and focused passes; `rdd-verify` for entered verification work; `rdd-reverse-engineer` for baseline publication or DERIVED additions; `rdd-reverse-engineer-verify` and `rdd-reverse-engineer-accept` for eligible existing baselines; `rdd-acceptance` for the acceptance test guide before completion; `rdd-audit` for documents and citations | -| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shapes of the tracked slice file, gate rules file, and acceptance test guide | +| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records, and the shapes of the tracked slice file, gate rules file, acceptance test guide, and integration path declaration | | `presets/` | the default and autopilot presets of a project's gate rules file, `process/rdd-human-gates.md` | ## Distribution diff --git a/file-state/INTEGRATION-PATH.md b/file-state/INTEGRATION-PATH.md new file mode 100644 index 0000000..9d9e777 --- /dev/null +++ b/file-state/INTEGRATION-PATH.md @@ -0,0 +1,32 @@ +# Integration path file + +> Canonical shape of a project's integration path declaration. `PROCESS.md` +> §Evidence and completion defines what each path delivers and what completion +> checks on it. The declaration is a tracked project file at +> `process/integration-path.md`, versioned in the repository and changed the +> way the project reviews any other repository change, in a store-backed and a +> file-backed repository alike. It is not a store record, and no tool writes +> it: a person declares the path in a reviewed commit. + +```markdown +# Integration path + + + +- **Integration path:** merge | deploy +``` + +## Value + +- **Integration path** is `merge` or `deploy`, case-insensitive. `merge` + delivers by merging to the remote default branch; `deploy` delivers by + deploying a named commit. +- Only the first `- **Integration path:**` bullet counts; later ones and the + prose around it are ignored. +- A project without the file delivers by `merge`. + +## Refusals + +A file that exists is refused, naming the file and both accepted values, when +its first `- **Integration path:**` bullet carries any other value or none, or +when it has no such bullet. diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index c2ceab7..343adf6 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -34,10 +34,20 @@ records, and derived views. planning or implementation review, undisclosed gap, or incomplete reconciliation. 3. If the pre-delivery audit passes, deliver through the project's authorized - integration path while keeping awaiting entities `IN_REVIEW`. + integration path while keeping awaiting entities `IN_REVIEW`. The path is + the one `process/integration-path.md` declares: `merge`, the default when + the file is absent, or `deploy` (`PROCESS.md` §Evidence and completion). 4. Re-run or confirm evidence against the delivered revision — the revision the authorized integration path produced, not the branch head that fed - it; for a slice this is its one full verification — and reconcile all authoritative records and derived views. Use + it; for a slice this is its one full verification — and reconcile all authoritative records and derived views. + On `merge`, the delivered revision is the fetched remote default-branch + tip, and it must contain every requirement's tested commit; the checkout + need not sit on the tip. On `deploy`, name the deployed commit and record + a deployment run with the environment and the smoke checks. A requirement + whose latest evidence is failing, stale, or missing, or whose tested + commit the delivered revision does not contain, stops completion by name + before anything is written. After a squash or rebase merge, re-run the + tests at the merged commit and record that run. Use `skills/rdd-audit/SKILL.md` to verify that delivered records, citations, and documents still describe the code; a finding it surfaces is a stop condition or routes through `rdd-triage`, never a silent correction. diff --git a/skills/rdd-reverse-engineer/SKILL.md b/skills/rdd-reverse-engineer/SKILL.md index e2b9530..99ba78f 100644 --- a/skills/rdd-reverse-engineer/SKILL.md +++ b/skills/rdd-reverse-engineer/SKILL.md @@ -36,7 +36,9 @@ captured dirty cannot be accepted as built, whatever is committed later, without a new authorized run with its own capture. As-built acceptance also needs the tested commit to be the tip of the remote default branch — which may lie past the captured commit, when the commits between changed none of the -files the run authorized (the `mp-process-cli` verification steps). Put +files the run authorized (the `mp-process-cli` verification steps). This +as-built check is not completion: the project's declared integration path +(`PROCESS.md` §Evidence and completion) does not change it. Put untracked files that are not source into the repository's local exclude file: ignored files are left out and disclosed, and tracked files are listed whatever the ignore rules say, except From 7136b3b8a535cad78b17f820ac4be8ee4b388bfa Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 08:25:58 +0300 Subject: [PATCH 09/11] =?UTF-8?q?docs(process):=20gate=20rules=20shape=20u?= =?UTF-8?q?ses=20the=20presets'=20<=E2=80=A6>=20placeholders?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit file-state/HUMAN-GATES.md used «…» placeholders while presets/default.md and presets/autopilot.md use <…>. The shape now uses <…> like the presets; the CLI parser refuses both as placeholders. Co-Authored-By: Claude Opus 5.5 --- file-state/HUMAN-GATES.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/file-state/HUMAN-GATES.md b/file-state/HUMAN-GATES.md index f957ae5..979bcdd 100644 --- a/file-state/HUMAN-GATES.md +++ b/file-state/HUMAN-GATES.md @@ -14,14 +14,14 @@ autopilot preset a process owner copies in to grant autopilot. ```markdown # Project gate rules -- **Decided:** «USER: source of the process owner who merged this file» +- **Decided:** - **Preset:** default | autopilot | custom -- **Scope:** «Epic or requirement ids, comma-separated; omit the line for the whole System» -- **Expires:** «YYYY-MM-DD; omit the line when no row needs it» +- **Scope:** +- **Expires:** | Decision | Decided by | When the agent may decide | Always a human when | |---|---|---|---| -| «row» | «decider» | «condition, or —» | «areas separated by spaces, or —» | +| | | | | ``` ## Header lines From 97dfbf0db6a0d63c3ee96eed44d4f20887963c4d Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Wed, 14 Oct 2026 09:26:44 +0300 Subject: [PATCH 10/11] docs(process): a later cold-review round reviews only what changed The slice design (REQ-CROSS-585) has later rounds read the change list the review snapshot carries; the skill now says so, with the closures of earlier findings re-verified and findings and dispositions each recorded in one batch. Co-Authored-By: Claude Opus 5.5 --- skills/rdd-cold-review/SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index 8b4211b..a1e5958 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -85,6 +85,10 @@ review audits the change the packet proposes, not the packet as a document. with findings and the verdict recorded per member; an addition to an open slice gets one narrow review of the addition and its effect on the slice, not a re-review of the slice (`PROCESS.md` §Slices). + A later round reviews only what changed since the reviewed round, as the + review snapshot lists it, plus the closures of earlier findings, each + verified against the current packet and code as step 6 requires. Its + findings are recorded in one batch, and so are their dispositions. 10. Return the cold-review trace gate `PASS` only when the material-finding rule in `PROCESS.md` is satisfied. Otherwise return `FAIL` with exact blockers. From bf18e1e033c8b6dac254550f13d3f7ff8fd376fc Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Thu, 15 Oct 2026 07:56:16 +0300 Subject: [PATCH 11/11] docs(process): make fix-first paths and the slice's one full run consistent Review on #40: - The defect and incident light paths let the fix precede entry and RED, but the entry rule, the autopilot RED rule, rdd-build and the completion-review stop list had no matching exception. They now name fix-first as an exception, with the reproduction proof standing as its RED. For an incident the proof is the test failing at the pre-fix revision and passing at the fix, cited in the gap record. - Full verification was required both at closeout (before review) and again after delivery. The one run is now the closeout run, carried to the delivered revision by the existing containment rule; it is re-run there only when containment cannot be shown (squash or rebase). Co-Authored-By: Claude Opus 5.5 --- PROCESS.md | 36 +++++++++++++++++++-------- skills/rdd-autopilot/SKILL.md | 4 ++- skills/rdd-build/SKILL.md | 4 +++ skills/rdd-completion-review/SKILL.md | 8 ++++-- 4 files changed, 38 insertions(+), 14 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 86b0694..afb5804 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -473,8 +473,10 @@ autopilot preset or the process owner's own copy: declared. An incident counts as declared only when a person's words declaring it are quoted as a `USER:` source in the fix-first gap record; the agent never declares one. The fix may go first and the reproduction - test follow as verification; the SR, the entry answer, and the evidence - follow before other work is selected. The incident path keeps `sign_in`, + test follow as verification: the test is shown failing at the pre-fix + revision and passing at the fix, and the gap record cites both runs. The + SR, the entry answer, and the evidence follow before other work is + selected. The incident path keeps `sign_in`, `payments`, and `existing_data` with a person. - **Small change** (`small_change_entry`): the small-change lane (§Small-change lane), under a lane authorization whose end is shown before @@ -621,7 +623,7 @@ slice: | Entry | One entry brief; each member's entry gate carries it, and the human answers each gate with its own confirmation | | Red-first | Per connected batch: one RED commit carrying a failing assertion for every clause the batch implements, then the commit that turns it green | | Tests while building | Focused tests per batch | -| Full verification | Once, at slice end, at the delivered revision | +| Full verification | Once, at slice closeout, carried to the delivered revision by containment (§Evidence and completion) | | Independent code review | One review over the whole change, where the slice needs one (§Planning and readiness) | | Acceptance test guide | One guide for a human tester, after full verification and before completion (§Evidence and completion) | | Completion | One completion brief; each member's completion gate carries it and is answered with its own confirmation, item by item | @@ -776,7 +778,7 @@ again. | AI TDD inner loop | Per connected batch: one RED commit with a failing assertion for every clause the batch implements, then its GREEN, rerunning affected URs each batch | Batch: representative journey and state-boundary REDs cover adjacent primary actions, which are implemented together and checked with one focused integrated GREEN run. The batch's RED commit carries a failing assertion for every clause the batch implements; representative REDs only reduce the number of commits, never the assertions | | Commits | Per connected batch: RED, GREEN, cleanup, reconciliation | Per connected batch: one RED commit carrying the batch's failing tests, its RED evidence recorded there, then the working batch. A RED commit carries only failing tests that its next commit turns green; that commit lands the whole batch. To land a batch SR by SR, use one RED/GREEN pair per SR. A journey assertion is written in the batch that can make it pass. A test is never skipped, disabled or left failing to get a commit past the project's gate, other than the declared RED tests of a RED commit as the gate admits them; the gate runs on every commit as configured | | Records | Reconciled after each pass | Reconciled at each integration checkpoint; record grooming never holds the build | -| Full verification | Once per slice, at slice end, at the delivered revision; focused tests per batch before it | The agent's full-verifier feedback runs wait for slice closeout, unless the exception above applies; the project's commit gate is unchanged | +| Full verification | Once per slice, at slice closeout, carried to the delivered revision by containment; focused tests per batch before it | The agent's full-verifier feedback runs wait for slice closeout, unless the exception above applies; the project's commit gate is unchanged | **Reversible local build-ahead** is uncommitted work on the feature branch, written before the entry is applied. It is set aside so that the RED commit @@ -823,7 +825,10 @@ It waits for an answer only when a wrong guess is hard to undo: - Red-first tests, with evidence recorded. A RED is observed before the code that satisfies it, and no evidence is reconstructed after the fact. Every clause a batch implements has its failing assertion in the batch's RED - commit. + commit. A fix-first change on a light path the gate rules turn on + (§Project gate rules) meets this with its reproduction proof: for a defect, + the test committed failing before the fix; for an incident, the test shown + failing at the pre-fix revision and passing at the fix. - Security, authorization, tenant isolation, and atomic data integrity hold from the first functioning increment. - Every acceptance clause is met before acceptance. Focused-green increments, @@ -837,7 +842,8 @@ It waits for an answer only when a wrong guess is hard to undo: open, and build ahead of its record is filed as a gap record naming the slice. Nothing is dropped silently. -**Slice end.** Closeout runs the full required verification and the +**Slice end.** Closeout runs the full required verification — the slice's +one full verification (§Slices) — and the hardening stage, and repairs what fails; it adds verification and hardening, not RED for clauses already built. An item is presented as eligible for completion only when its required evidence passes. Then one @@ -989,7 +995,7 @@ change tests or implementation until current applied entry approval covers the whole selected delivery scope, including the Epic when selected. Newly entered items must be `TODO`; already-entered items retain their current states. Unchanged `DONE` dependencies are not re-entered. Partial entry approval does -not permit development to start on the approved subset. There are two +not permit development to start on the approved subset. There are three exceptions. The first is the defect lane: when a defect is already diagnosed and the change is bounded, the failing test may be written first, on a branch and before entry, and cited in the packet as a `RUN:` source: it is the reconnaissance, @@ -999,6 +1005,10 @@ RED, which is re-established after entry, and it authorizes no implementation. The second is reversible local build-ahead under a current autopilot grant (§Autopilot): uncommitted code, set aside before the RED commit, that authorizes no RED evidence and no status change before entry. +The third is a fix-first change on a light path the project's gate rules turn +on (`defect_fix`, `incident_fix`, §Project gate rules): the fix may precede +entry, its reproduction proof stands as its RED, and its SR, entry answer, +evidence and fix-first gap record follow before other work is selected. ## Development loop @@ -1104,8 +1114,9 @@ Run the loop as follows: perform scoped behavior-preserving cleanup. A RED commit carries only failing tests that its next commit turns green. 3. Run the batch's focused tests on the cleaned content, then rerun each - affected UR scenario. Full verification runs once per slice, at slice end, - at the delivered revision (§Evidence and completion). + affected UR scenario. Full verification runs once per slice, at slice + closeout, and carries to the delivered revision by containment + (§Evidence and completion). 4. Re-evaluate every selected applicable SR lower trace and UR upper trace independently. A trace `FAIL` caused by unmet approved behavior starts another iteration; it does not request human input. @@ -1214,7 +1225,9 @@ meeting its own predicate below; the human may reject single items, which stay A slice completes the same way, item by item: one completion brief, carried by each member's completion gate and answered with its own confirmation; a rejected item stays `IN_REVIEW`. The slice's full required verification runs -once, at the delivered revision, before that brief is presented. +once, at closeout, and counts at the delivered revision when that revision +contains its tested commit; otherwise it is re-run at the delivered revision. +Either way it passes before that brief is presented. A normal completion human gate may open only when named items are `IN_REVIEW`, code is delivered, evidence is current at the delivered revision, state is reconciled, @@ -1244,7 +1257,8 @@ fingerprint. Excluded-only proof does not block current work; mixed-scope proof retains its live obligations. **Acceptance test step.** After the evidence is confirmed current at the -delivered revision — for a slice, its one full verification — and before the +delivered revision — for a slice, its one full verification, carried by +containment or re-run there — and before the completion trace, the agent drafts and completes an acceptance test guide for a human tester (`rdd-acceptance`). The guide is a tracked file: `process/slices//acceptance-guide.md` beside the slice file, or diff --git a/skills/rdd-autopilot/SKILL.md b/skills/rdd-autopilot/SKILL.md index d7615bd..62104a1 100644 --- a/skills/rdd-autopilot/SKILL.md +++ b/skills/rdd-autopilot/SKILL.md @@ -133,7 +133,9 @@ asks. 1. **Reconcile** every record the slice touched. Try once more to clear the logged refusals. -2. **Close out.** Run the full required verification and harden the +2. **Close out.** Run the full required verification — the slice's one full + verification, carried to the delivered revision by containment + (`PROCESS.md` §Slices) — and harden the combined change (stage 3). Closeout adds verification and hardening, not RED for clauses already built; a clause first built at closeout gets its own RED like any other. The checkpoint limit on further work on a diff --git a/skills/rdd-build/SKILL.md b/skills/rdd-build/SKILL.md index d3b2e69..c0fa8f0 100644 --- a/skills/rdd-build/SKILL.md +++ b/skills/rdd-build/SKILL.md @@ -19,6 +19,10 @@ code, tests, and current records. planning and entry first. Under a current autopilot grant, reversible local build-ahead (`PROCESS.md` §Autopilot) may precede this check; it is set aside before RED and authorizes no RED evidence or status change. + A fix-first change on a light path the project's gate rules turn on + (`PROCESS.md` §Project gate rules) may be implemented before this check; + its reproduction proof stands as its RED, and its SR, entry answer and + evidence follow before other work is selected. Work on a reviewable feature branch and preserve unrelated changes. 2. Before its first implementation iteration, establish upper RED for selected UR scenarios requiring new evidence. Re-validation of previously proven diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index 343adf6..26c46f7 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -29,7 +29,9 @@ records, and derived views. findings, and verdict separately from planning review. Verify fixes against their commits and test evidence. 2. Stop for any `DERIVED` dependency, candidate link counted as authoritative, - stale or inherited-unverified evidence, missing required RED observation, + stale or inherited-unverified evidence, missing required RED observation + (for a fix-first change, the reproduction proof `PROCESS.md` §Project gate + rules names), missing required independent code review, unresolved material finding from planning or implementation review, undisclosed gap, or incomplete reconciliation. @@ -39,7 +41,9 @@ records, and derived views. the file is absent, or `deploy` (`PROCESS.md` §Evidence and completion). 4. Re-run or confirm evidence against the delivered revision — the revision the authorized integration path produced, not the branch head that fed - it; for a slice this is its one full verification — and reconcile all authoritative records and derived views. + it; for a slice, its closeout full verification counts when the delivered + revision contains its tested commit, and otherwise this re-run is the + slice's one full verification — and reconcile all authoritative records and derived views. On `merge`, the delivered revision is the fetched remote default-branch tip, and it must contain every requirement's tested commit; the checkout need not sit on the tip. On `deploy`, name the deployed commit and record