From d027476135854e5ce43ba606c8a38ba2cdcbf2c4 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Sun, 27 Sep 2026 23:09:30 +0300 Subject: [PATCH 1/2] feat(process): a small-change lane that scales review and gates to the change One SR, at most five non-test source files, no security, migrations, public contracts, model calls, background jobs or billing, and a class a standing lane authorization covers (defect with a failing test, wording, presentation-only, patch dependency). Its packet is the SR record; one narrow independent review pass, no rounds; entry applies the authorization; small changes may be completed in one batched human gate. Every loop invariant is kept: red-first evidence, independent review, attributable human decisions. Decided by the process owner on 2026-09-27 from measurements of the loop's cost (USER:2026-09-27:small-change-lane-approved). Co-Authored-By: Claude Opus 5.5 --- PROCESS.md | 47 +++++++++++++++++++++++++-- skills/rdd-cold-review/SKILL.md | 8 +++-- skills/rdd-completion-review/SKILL.md | 3 ++ skills/rdd-entry-review/SKILL.md | 5 +++ skills/rdd-plan/SKILL.md | 8 +++-- skills/rdd-start/SKILL.md | 3 +- 6 files changed, 67 insertions(+), 7 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index 490c72a..f9c3409 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -227,6 +227,8 @@ not a gate answer. | Requirement `DERIVED -> PROPOSED/PENDING_VERIFICATION/OBSOLETE` | Candidate packet and exact confirmation scope complete | | Source-scoped baseline authorization | Bound system/store, current corpus and exact source/document inventory reviewed; allowed baseline publication made explicit | | Requirement `PROPOSED/PENDING_VERIFICATION -> TODO` | Its Entry packet is complete at the exact fingerprint | +| Lane authorization for a system | The classes, excluded areas, who may apply it, expiry and daily cap are explicit | +| Small change `PROPOSED -> TODO` | Its narrow independent pass is `PASS`, it is eligible, and a current lane authorization covers its class and cap; the entry is recorded as an application of that authorization, attributed to the human who answered it | | Epic `PROPOSED -> TODO` | Its Entry packet and every selected member's entry trace are complete | | Requirement `IN_REVIEW -> DONE` | Its completion predicate is satisfied at the delivered fingerprint | | Epic `IN_REVIEW -> DONE` | Every member is already `DONE` or named and completion-eligible in the same gate; the Epic completion predicate is satisfied | @@ -343,11 +345,42 @@ failure. |---|---|---| | Epic | Multiple requirements form one human-readable change, or shared product/architecture/contract/data decisions are required | Exact member UR/SR set; membership is grouping, not ancestry | | Single SR | Exactly one independently verifiable system behavior changes | Authoritative SR source; Epic and UR relations optional | +| Small change | One SR changes one bounded behavior, the change meets the lane's eligibility, and a current lane authorization covers its class | Authoritative SR source; the lane authorization it applies; UR relation optional | Expand single-SR work to Epic scope when it changes user outcome or acceptance, requires another SR, or introduces a cross-cutting decision. Related approved items repeat entry approval only when their approved scope changes. +### Small-change lane + +The small-change lane scales review and gates to the size of the change; it +keeps every invariant of the loop. A change is eligible only when all of these +hold, checked by the store and the CLI rather than asserted by an agent: + +- exactly one SR changes and no other requirement changes status; +- its change boundary names at most five non-test source files in one + repository (tests are not counted — red-first adds them); +- it touches none of: security, authentication, authorization, or the + process's own guards and permissions; migrations, persisted schema or tenant + data access; public API routes, response shapes, or CLI verbs and flags; + model prompts or anything that calls a model or runs a background job; + billing; and any area the lane authorization excludes; +- its class is one the current lane authorization covers. The classes are: a + defect with a diagnosed failing test; wording or copy; a presentation-only + change inside one view or one library component; a patch-version dependency + update with the suite passing. New features are never small changes. + +A lane authorization is a strict human gate answered once for a system by a +workspace admin or the process owner. It names the classes it covers, any +further excluded areas, who may apply it, its expiry (at most 90 days; renewed +by a successor gate), and a daily cap. It can be withdrawn at any time; work +already entered finishes, nothing new enters. Every application of it is +visible in the authorizing human's feed. + +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. + ## Planning and readiness Planning consists of packet authoring, independent cold review, and entry @@ -355,7 +388,10 @@ 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. Depth is also bounded: a single-requirement packet is at most +may be omitted. A small change's packet is its SR record: statement and source, +change boundary (files, and what must not change), RED plan (the failing test and +why it fails today), and lane class; together they satisfy the eight items, and +they fit in about ten lines. 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 @@ -404,7 +440,10 @@ 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 +Cold review converges or stops. At most two rounds run on one change. A small +change gets one narrow pass from an independent context — the boundary against +the code, the RED plan, and the eligibility — and no second round: a blocking +finding sends it out of the lane. 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 @@ -558,6 +597,10 @@ Supplemental evidence causes no demotion. Re-verification may restore completion gate. Material approved-scope changes stale entry approval and send work back to planning. +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 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. diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index 058a04a..d4774e6 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -41,11 +41,15 @@ review audits the change the packet proposes, not the packet as a document. 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 +8. For a small change, run one narrow pass: the boundary against the code, the + RED plan, and the lane's eligibility. There is no second round — a blocking + finding returns `FAIL` with the instruction that the change leaves the lane + for single-SR scope. +9. 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 +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. Use `skills/rdd-audit/SKILL.md` to resolve the packet's citations and diff its diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index 3d33179..e3d39c0 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -33,6 +33,9 @@ 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. + 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`. 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-entry-review/SKILL.md b/skills/rdd-entry-review/SKILL.md index 1c32f25..e5fdf32 100644 --- a/skills/rdd-entry-review/SKILL.md +++ b/skills/rdd-entry-review/SKILL.md @@ -28,6 +28,11 @@ packet, cold-review findings, current gate records, and relevant sources. with every referenced decision, correction, or finding stated by its substance and not its code. Before presenting, reread the brief as that reader and expand any bare identifier or jargon. + For a small change there is no per-change human gate: after its narrow pass + is `PASS` and its eligibility holds, record its entry as an application of + 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 named transitions and reconcile all affected records. The answer and its diff --git a/skills/rdd-plan/SKILL.md b/skills/rdd-plan/SKILL.md index efbd66e..d5d738c 100644 --- a/skills/rdd-plan/SKILL.md +++ b/skills/rdd-plan/SKILL.md @@ -17,8 +17,12 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. 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. +2. Choose epic scope, single-SR scope, or the small-change lane using + `PROCESS.md`. Do not invent epic membership or a UR link to make the graph + appear complete. Take the small-change lane only when the change meets the + lane's eligibility and a current lane authorization covers its class; its + packet is the SR record's statement, boundary, RED plan and lane class, and + nothing more. 3. Create or update the selected item content: sourced UR outcomes and inline scenarios when user behavior is in scope, and thin testable SRs for system behavior. diff --git a/skills/rdd-start/SKILL.md b/skills/rdd-start/SKILL.md index 1a25edd..804ba14 100644 --- a/skills/rdd-start/SKILL.md +++ b/skills/rdd-start/SKILL.md @@ -105,7 +105,8 @@ These rules bind every subsequent phase in the session: ## Route Select the earliest unmet prerequisite for the frozen scope and hand off to -its skill: `rdd-discover`, `rdd-plan`, `rdd-cold-review`, `rdd-entry-review`, +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. From 6f633c7e0f8c67634f261350873a6172fb60aae5 Mon Sep 17 00:00:00 2001 From: Pasi Vuorio Date: Mon, 28 Sep 2026 18:20:18 +0300 Subject: [PATCH 2/2] fix(process): the lane authorization matches the product: admin or superuser, at most 30 days PROCESS.md said "workspace admin or the process owner" and "at most 90 days"; the product enforces a workspace admin or platform superuser and at most 30 days (PR #694 review, confirmed in code). Co-Authored-By: Claude Opus 5.5 --- PROCESS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PROCESS.md b/PROCESS.md index eb1a7a1..04f200d 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -377,8 +377,8 @@ hold, checked by the store and the CLI rather than asserted by an agent: update with the suite passing. New features are never small changes. A lane authorization is a strict human gate answered once for a system by a -workspace admin or the process owner. It names the classes it covers, any -further excluded areas, who may apply it, its expiry (at most 90 days; renewed +workspace admin or a platform superuser. It names the classes it covers, any +further excluded areas, who may apply it, its expiry (at most 30 days; renewed by a successor gate), and a daily cap. It can be withdrawn at any time; work already entered finishes, nothing new enters. Every application of it is visible in the authorizing human's feed.