From eb191373f6cbd7e3d500745fee1e27589c4d1d44 Mon Sep 17 00:00:00 2001 From: Jussi Rajala Date: Sat, 12 Sep 2026 20:21:36 +0300 Subject: [PATCH] process: the review audits the change, delegated passes return facts, and the packet is bounded Canonical rules distilled from six delivery retrospectives on a store-backed workspace, where every session that went wrong went wrong the same way: the review attacked the packet instead of the change, a delegated pass reasoned past a refusal, or a session reached past its sanctioned tool. PROCESS.md - Planning: a single-requirement packet is at most one page; more reconnaissance means the scope is wrong. - Cold review: audits the change, not the document; packet-wording findings are notes; traceability is material only when a builder or gate would act on the wrong citation; independence is the recorded context, not a claim; carried closures are claims; a finding that changes a human decision goes to the human. Convergence bound: two rounds, then cut the packet, never a third. - Entry: the defect lane (USER:2026-09-12) - a diagnosed, bounded defect may have its failing test written on a branch before entry as a RUN: source; the SR's lower RED is still re-established after entry. - Development loop: delegated passes return findings and verdicts and write nothing; a refusal is a decision - the pass stops and returns it verbatim. - Completion: the delivered revision is the integrated one; a STALE member-scoped trace still counts against its Epic. - State records: the project's sanctioned tool - a missing surface is a gap to surface, never a variance; read-only workaround with a filed gap is fine, a hand-written store change is a stop; notes never carry a workaround past the surface landing (USER:2026-09-12, tool-neutral wording). Skills - rdd-cold-review: the independent context and delegated-pass rule, closures as claims, materiality by effect, the round bound, report shape. - rdd-entry-review, rdd-completion-review: trace before gate so the gate names it; answer then apply, members before epic; delivered revision. - rdd-plan: scope from the relation graph; inventory by the invariant and judge breaks per call site; read before claiming; a RED case must fail today; the defect lane. - rdd-start: suspended selections are a preflight fact; read the projection before any readiness claim; timebox tooling diagnosis then surface; never mutate a shared store to test a hypothesis; a direction given twice is a decision. - rdd-build: the commit gate binds GREEN, cleanup and reconciliation; a RED waypoint may fail the suite the gate runs; record RED evidence at the RED commit. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_019qTRmYNwxhofJUNhxW45oc --- AGENTS.md | 4 +- PROCESS.md | 66 ++++++++++++++++++++++++++- skills/rdd-build/SKILL.md | 7 +++ skills/rdd-cold-review/SKILL.md | 31 +++++++++++-- skills/rdd-completion-review/SKILL.md | 27 +++++++---- skills/rdd-entry-review/SKILL.md | 8 +++- skills/rdd-plan/SKILL.md | 21 +++++++-- skills/rdd-start/SKILL.md | 13 +++++- 8 files changed, 152 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bd32750..0b824cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,9 @@ serialization shapes; it does not contain a project's live delivery state. Epic, requirement, gate, work-selection, and backlog/gap records. - Project instructions own only project-specific rules such as architecture, repository topology, commands, environments, and test gates. They reference - rather than redefine the process. + rather than redefine the process. They name the project's sanctioned tool + for the process store and its channel for surfacing tooling gaps; the rule + that binds both is `PROCESS.md` "State records and reconciliation". - `CLAUDE.md` files are compatibility pointers; they do not override these instructions. diff --git a/PROCESS.md b/PROCESS.md index 604eb71..b200d1d 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -241,7 +241,12 @@ review, in that order. A changed fingerprint or failed result returns work to the earliest affected pass; a downstream pass cannot repair an upstream gap. Packet depth is proportional to the selected scope — a single-SR packet may satisfy an item in a sentence where an Epic needs pages — but no packet item -may be omitted. +may be omitted. Depth is also bounded: a single-requirement packet is at most +one page. Reconnaissance that needs more than that page is evidence that the +scope is wrong, not that the packet should grow — split or replan the scope. +The bound is a limit, not a preference: every line a packet carries beyond +what a builder or a gate acts on is a line a review attacks instead of the +change. ### Entry packet @@ -274,9 +279,32 @@ in-scope deferred correctness, security, data-loss, contract, traceability, or testability findings fail the cold-review trace gate. Technical review cannot grant entry approval. +The review audits the change, not the document. A finding about the packet's +own wording, counts, or citations that would alter none of the code, the +tests, the interfaces, or the risks is a note and never blocks; a traceability +finding is material only when a builder or a gate would act on the wrong +citation. The independent context is a recorded fact of the verdict — the +context the verdict was recorded from — not a claim in its text: a verdict +recorded from the authoring context is not a cold review. A closure carried +from an earlier round is a claim to re-verify, not a fact. A finding that +would change a human decision returns to that human as a question; it is never +resolved by editing the packet. + +Cold review converges or stops. At most two rounds run on one change. When a +second round's new blocking findings are about the packet rather than the +change, the packet is cut to what the change needs and review proceeds. A +third round does not start: the work stops and what is known is handed to a +human. + Entry review evaluates the complete packet at its exact fingerprint. Only a current entry trace `PASS` may open the human entry gate. Do not create or -change tests or implementation until every selected item is `TODO`. +change tests or implementation until every selected item is `TODO`, with one +exception — 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, +and it gives the review something executable instead of prose about whether a +planned test would fail. The red test does not replace the SR's own lower +RED, which is re-established after entry, and it authorizes no implementation. ## Development loop @@ -359,6 +387,22 @@ The full loop terminates only when the selected scope is `DONE` or `OBSOLETE`. An unanswered human gate, `BLOCKED`, `DEFERRED`, `TODO`, or `IN_REVIEW` state is an explicit incomplete handoff, not completion. +### Delegated passes + +A pass may be delegated to another context — a cold review, a verification +sweep, one reconnaissance surface. A delegated pass establishes facts and +returns them: findings, a verdict, citations. It writes nothing to the process +store; the orchestrating session records what the pass returned, under its own +actor attribution. The independence of a cold review is a property of the +context the verdict is recorded from, not of which process runs the recording, +so recording from the orchestrating session does not compromise it. + +A delegated pass that is refused by its environment — a permission denial, an +authentication failure, a store refusal — stops and returns the refusal +verbatim as its report. A refusal is a decision by the environment's owner, +not an obstacle: the pass never reformulates, splits, or re-issues the refused +call, and an instruction to finish the task does not override this. + ## Evidence and completion A test result is immutable. Rerunning creates a new result. @@ -403,6 +447,10 @@ work back to planning. A 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. A 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. | Item | `DONE` predicate after human acceptance | |---|---| @@ -430,6 +478,20 @@ A repository is one or the other, never both at once. Every serialized file carries its snapshot header — `Snapshot at` and `Source store/revision` — so currency is checkable per file. +A project names one sanctioned tool as its interface to the store — its write +channels, its reads, its projections — and a channel for surfacing what that +tool lacks. When a task needs something the tool does not expose — a session +or authentication fact, an untruncated value, any read — that is a tooling +gap to surface through that channel, never a variance to absorb. Reaching past +the tool — reading its credential or configuration files, calling its +transport by hand, editing store files — is the anti-pattern, with the same +standing as every other rule here. A read-only workaround that unblocks the +session is acceptable when the gap is surfaced in the same session. A +workaround that writes to the store by hand is a stop: it bypasses server-side +legality and actor attribution, which are safety properties, not conveniences. +An agent's persistent notes never carry such a workaround as knowledge: the +gap is filed, and the note is retired when the surface lands. + ```text file-state/ EPICS.md diff --git a/skills/rdd-build/SKILL.md b/skills/rdd-build/SKILL.md index 2753432..52de3ce 100644 --- a/skills/rdd-build/SKILL.md +++ b/skills/rdd-build/SKILL.md @@ -40,6 +40,13 @@ 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 — +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. + ## Report Report the planning revision, RED and passing observations, code and test diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index c128b59..058a04a 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -11,6 +11,13 @@ in a consuming repository), versioned product sources, selected requirements, optional epic/specifications, technical reconnaissance, and repository state at the recorded revision. +The independent context is a recorded fact of the verdict, not a claim: the +verdict is recorded from that context, and a verdict recorded from the +authoring context is not a cold review. Run as a delegated pass, this skill +returns its findings and verdict and writes nothing to the store; the +orchestrating session records them (`PROCESS.md` §Delegated passes). The +review audits the change the packet proposes, not the packet as a document. + ## Procedure 1. Audit the authoritative graph and selected scope without relying on @@ -25,8 +32,20 @@ the recorded revision. 5. Identify any product, architecture, acceptance, or scope choice that lacks human authority. 6. Record each finding with severity, direct source, owner, and disposition as - `OPEN`, `RESOLVED`, `DEFERRED`, or `REJECTED`. -7. Return the cold-review trace gate `PASS` only when the material-finding rule + `OPEN`, `RESOLVED`, `DEFERRED`, or `REJECTED`. A `RESOLVED` closure carried + from an earlier round is a claim: verify it against the current packet and + code before accepting it. A finding that would change a human decision is a + question for that human, never a packet edit. +7. Grade materiality by what the finding would change. A finding about the + packet's wording, counts, or citations that alters none of the code, tests, + interfaces, or risks is a note and never blocks; traceability is material + only when a builder or a gate would act on the wrong citation + (`PROCESS.md` §Planning and readiness). +8. Bound the rounds: at most two on one change. On a second round whose new + blocking findings are about the packet rather than the change, return + `FAIL` with the instruction to cut the packet, not to expand it. Do not + start a third round: stop and hand what is known to a human. +9. Return the cold-review trace gate `PASS` only when the material-finding rule in `PROCESS.md` is satisfied. Otherwise return `FAIL` with exact blockers. Use `skills/rdd-audit/SKILL.md` to resolve the packet's citations and diff its @@ -38,6 +57,8 @@ verdict as entry approval. ## Report -Lead with material findings, then state the reviewed fingerprints, finding -dispositions, trace-gate verdict, and the exact handoff: `rdd-plan` after a -failure or `rdd-entry-review` after a current pass. +Lead with material findings, then state the round number, the context the +verdict is recorded from, the reviewed fingerprints, finding dispositions +(notes separated from blockers), trace-gate verdict, and the exact handoff: +`rdd-plan` after a failure, `rdd-entry-review` after a current pass, or the +human after a bounded third round. diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index 08829f5..b4e1788 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -20,19 +20,26 @@ records, and derived views. cold-review finding, 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`. -4. Re-run or confirm evidence against the delivered revision 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. -5. Record completion trace `PASS` only for the exact eligible fingerprint. Only - then make the scoped human completion gate `OPEN` and present its brief. +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 + `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. +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. A + `STALE` member-scoped cold-review trace from an earlier round blocks an + epic's completion until it is re-evaluated at the current fingerprint; an + epic-scoped pass does not stand in for it. Only then make the scoped human + completion gate `OPEN` and present its brief. 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 - complete applicable predicate. Apply member requirements before a named - epic. Route rejection or requested changes through `rdd-triage` to the - earliest invalidated phase. + complete applicable predicate. The answer and its application are separate + steps: apply member requirements before a named epic, and report an answer + that is recorded but not yet applied as exactly that, never as completion. + Route rejection or requested changes through `rdd-triage` to the earliest + invalidated phase. ## Report diff --git a/skills/rdd-entry-review/SKILL.md b/skills/rdd-entry-review/SKILL.md index 656861f..d79f308 100644 --- a/skills/rdd-entry-review/SKILL.md +++ b/skills/rdd-entry-review/SKILL.md @@ -17,7 +17,9 @@ packet, cold-review findings, current gate records, and relevant sources. candidate links counted as authoritative, ambiguous acceptance, broad SRs, stale reconnaissance, incomplete implementation context, inadequate RED strategy, or unresolved material cold-review findings. -3. Record the entry trace gate against the exact content fingerprint. Keep the +3. Record the entry trace gate against the exact content fingerprint, before + the human gate exists, so the gate names it as its prerequisite; a human + gate opened without a named passing trace cannot be answered. Keep the human gate `DRAFT` when the trace does not pass. 4. After a current trace `PASS`, make only the exact scoped human gate `OPEN` and present its brief and recommendation in **plain product language** — see @@ -27,7 +29,9 @@ packet, cold-review findings, current gate records, and relevant sources. reader and expand any bare identifier or jargon. 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 - named transitions and reconcile all affected records. + 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. 6. Move approved named `PROPOSED` or `PENDING_VERIFICATION` requirements and any named proposed epic to `TODO`. Otherwise retain the strongest honest state and route requested changes. diff --git a/skills/rdd-plan/SKILL.md b/skills/rdd-plan/SKILL.md index 0bf9f97..efbd66e 100644 --- a/skills/rdd-plan/SKILL.md +++ b/skills/rdd-plan/SKILL.md @@ -13,8 +13,10 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. ## Procedure 1. Confirm every requirement and relation the proposed scope depends on is - authoritative. Stop at the confirmation gate for `DERIVED` requirements or - candidate-only links. + authoritative. Take the scope from the stored relation graph — declared + members, required SRs, gates — never from a keyword search over records. + Stop at the confirmation gate for `DERIVED` requirements or candidate-only + links. 2. Choose epic scope or single-SR scope using `PROCESS.md`. Do not invent epic membership or a UR link to make the graph appear complete. 3. Create or update the selected item content: sourced UR outcomes and inline @@ -22,10 +24,21 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. behavior. 4. Perform technical reconnaissance at a named repository revision. Record the affected surface, control/data flow, contracts, reuse targets, dependencies, - risks, test infrastructure, failure modes, and unknowns. + risks, test infrastructure, failure modes, and unknowns. Inventory the + surface by what depends on the invariant the change alters, not by the + callers of the module that owns it, and judge each break per call site + against the post-change invariants — one file can hold call sites of both + kinds. Verify every claim about existing code by reading it at that + revision; a reconnaissance sentence is a citation, not a memory. Keep the + packet within the bound in `PROCESS.md`: a single-requirement packet is at + most one page. 5. Enrich every selected SR with its implementation context, explicit change boundary, and lower-RED strategy. Define a separate upper-RED strategy for - every selected UR. + every selected UR. Every planned RED case must fail today for the stated + reason; a case that would pass on the current code is not evidence. For a + diagnosed, bounded defect the failing test may already exist on a branch + as a `RUN:` source — the defect lane in `PROCESS.md` §Entry packet — + cite it, and plan the SR's own lower RED to be re-established after entry. 6. Route product, scope, architecture, acceptance, priority, release, and workflow decisions through exact human gates. Open them only after their trace prerequisites pass. Record blockers, conflicts, gaps, and deferrals diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index 30cb70f..a92c8ad 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -24,6 +24,9 @@ Read the project `AGENTS.md` and the canonical `PROCESS.md` — installed at 4. Refresh the session's working-set snapshots and check each file's snapshot header against the store revision. A stale snapshot is refreshed, never edited. +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. The pending-decision projection may already have been delivered into the session by the host — a session-start brief injected as context rather than @@ -64,7 +67,15 @@ packet item may be omitted. These rules bind every subsequent phase in the session: - run the project's deterministic process checks before every commit, chained - so a failure stops the commit; + so a failure stops the commit — the expected RED of a red-first waypoint is + the one failure that does not (see `rdd-build`); +- read the store's projection before any claim about readiness or state; a + claim made from memory of an earlier read is not a fact; +- 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; +- a direction the human has given twice is a decision: record its `USER:` + source and proceed on it rather than re-planning around it; - 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;