From b5f2300b2c96e75220aa785e96128e79fb35420c Mon Sep 17 00:00:00 2001 From: mattias-modernpath Date: Sun, 18 Oct 2026 02:39:21 +0300 Subject: [PATCH 1/3] refactor: govern delivery with Epic plans and human approvals --- .pre-commit-config.yaml | 9 + AGENTS.md | 131 +-- PROCESS.md | 1279 ++++++------------------- README.md | 82 +- file-state/BACKLOG.md | 50 - file-state/EPICS.md | 27 - file-state/GATES.md | 48 - file-state/REQUIREMENTS.md | 48 - file-state/WORK-SELECTION.md | 49 - skills/rdd-autopilot/SKILL.md | 180 +--- skills/rdd-build/SKILL.md | 96 +- skills/rdd-cold-review/SKILL.md | 120 +-- skills/rdd-completion-review/SKILL.md | 84 +- skills/rdd-deliver/SKILL.md | 120 +-- skills/rdd-discover/SKILL.md | 53 +- skills/rdd-entry-review/SKILL.md | 69 +- skills/rdd-plan/SKILL.md | 118 +-- skills/rdd-start/SKILL.md | 168 +--- skills/rdd-triage/SKILL.md | 62 +- skills/rdd-verify/SKILL.md | 210 +--- 20 files changed, 670 insertions(+), 2333 deletions(-) create mode 100644 .pre-commit-config.yaml delete mode 100644 file-state/BACKLOG.md delete mode 100644 file-state/EPICS.md delete mode 100644 file-state/GATES.md delete mode 100644 file-state/REQUIREMENTS.md delete mode 100644 file-state/WORK-SELECTION.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a7d7e14 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,9 @@ +repos: + - repo: local + hooks: + - id: source-audit-tests + name: Shared source audit tests + entry: env -u GIT_INDEX_FILE -u GIT_DIR -u GIT_WORK_TREE node --test skills/rdd-audit/audit-citations.test.mjs + language: system + pass_filenames: false + always_run: true diff --git a/AGENTS.md b/AGENTS.md index 997373d..ab677f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,65 +1,82 @@ # Requirement-driven delivery — agent instructions -This repository defines a reusable requirement-driven delivery process. It -contains canonical process instructions, procedural skills, and flat-file -serialization shapes; it does not contain a project's live delivery state. +This repository defines a reusable product-delivery process and its focused +agent procedures. The server-backed process interface in a consuming project +is the sole authority for Epics, requirements, saved plans and exact proposed content and +human approvals. This repository defines no local delivery ledger. ## Instruction ownership -- [`PROCESS.md`](PROCESS.md) defines the canonical process, including authority, - items, traces, lifecycles, gates, planning, development, evidence, - 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. -- 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 - for the process store and its channel for surfacing tooling gaps; the rule - that binds both is `PROCESS.md` "State records and reconciliation". - -If project instructions conflict with a process rule, stop the affected -transition and report the conflict rather than creating a silent local variant. +- [`PROCESS.md`](PROCESS.md) defines product authority, native item identity, + traces, Epic scope, implementation approval, engineering, evidence and human + completion. +- [`skills/`](skills/) contains focused procedures that apply that process. + They use the consuming project's sanctioned process interface and do not + prescribe or invent its CLI verbs. +- Project instructions own project-specific architecture, repository layout, + commands, environments and test gates. They name the sanctioned process + interface and the channel for reporting a tooling gap. + +If the process interface lacks a required read or write, report that gap. Do +not create a local ledger, direct transport, or another authority as a +workaround. ## Required reading -Before planning, changing, reviewing, or delivering product work — and -before answering what to work on next, where the loop stands, what is waiting -on a decision, or what is blocked: - -1. read the project's root `AGENTS.md` for project-specific rules; -2. read this file and `PROCESS.md`; -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 - 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 - requiring new tests, and `skills/rdd-reverse-engineer/SKILL.md` to - establish an authorized as-built baseline or propose DERIVED additions to - an existing requirement corpus; - 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-audit/SKILL.md` is a shared utility other passes invoke, not a - phase; -4. read the relevant product sources, requirement records, optional epic, and - active work-selection record. - -Find and read relevant documents available locally. Checking when documents -were last updated does not refresh the local copies. When a refresh is needed, -follow the project's documented procedure. Consult the authoritative source -when local documents lack the information or you need an up-to-date answer. - -Being asked what to do next is session entry, not a shortcut past it. The -answer is the store's pending human decisions and routed work, read through -`skills/rdd-start/SKILL.md`. Version control, change lists, and the working -tree describe the repository rather than the loop, and never answer that -question. A project's root `AGENTS.md` names the concrete read for its own -store; if it names none, that omission is the report. - -## Binding process - -Follow `PROCESS.md`. Skills apply it and `file-state/` serializes its records; -neither redefines its rules. +Before planning, changing, reviewing or delivering product work — and before +answering what to work on next — read the project's root `AGENTS.md`, this +file and `PROCESS.md`. Enter with `skills/rdd-start/SKILL.md`; use +`skills/rdd-deliver/SKILL.md` for end-to-end work or the focused skill when the +request ends at one pass. Use `skills/rdd-autopilot/SKILL.md` only under an +explicit human grant. Use `skills/rdd-reverse-engineer/SKILL.md`, +`skills/rdd-reverse-engineer-verify/SKILL.md` and +`skills/rdd-reverse-engineer-accept/SKILL.md` only for their source-scoped +baseline and existing-proof work. `skills/rdd-audit/SKILL.md` is a shared +utility invoked by other passes, not a phase. + +Read relevant product documents and inspect their cited code and tests. A +citation or file audit establishes that a source can be opened; it does not +show that the source supports the claim. Keep source text, code/test links and +process identity distinct. + +## Product work and meta-work + +The loop covers changes to what a customer can do or observe. Repository +layout, build and review tooling, CI, deployment identity and agent +instructions are meta-work unless their purpose changes customer-visible +behavior. Do that work as a regular repository change and explain why the +product loop does not apply. Do not create process records for meta-work. + +## Authority and tooling gaps + +The human selects an Epic and approves its exact saved plan and proposed content for +implementation, atomically locking its requirements to one user and that Epic, and separately approves completion. Agents establish facts, +plan, review, implement approved work and report results. A human retains +merge, deployment and release authority. Never infer approval from silence, +code, test results, commits, a passing review or a repository status. + +Use only the project's sanctioned process interface for process reads and +writes. If it lacks a needed read or transition, report the gap through the +project's named channel. Never read credentials or private configuration, +call its transport directly, or write process state by hand. Ordinary product +documents remain in their project repository and use its documented +documentation workflow. + +## Communication and code style + +Be terse and factual. Ground technical claims in sources, code, tests or +observed runs. Prefer simple, robust changes. Preserve red-first test evidence, +run the focused and proportional regression checks, and report commands and +results. Read back accepted requirement versions after completion approval; +verify Git, PR and deployment state separately before making those claims. + +## Repository checks + +This source repository's pre-commit configuration runs the existing shared +audit test suite with `node --test skills/rdd-audit/audit-citations.test.mjs`. +Install it with `prek install --prepare-hooks`. The hook clears Git +repository/index variables before tests create their own temporary repositories; +otherwise an outer commit can redirect fixture Git operations. It supplies the missing +configuration needed by the required hook installation, without changing the +consuming project's checks or adding a delivery protocol. Process edits also +require review of internal links and competing instruction statements. diff --git a/PROCESS.md b/PROCESS.md index d7c35d4..5d6318b 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -1,209 +1,100 @@ # Requirement-driven delivery process -This document is the sole process authority. Skills execute it; `file-state/` -is its flat-file serialization. Neither may redefine it. - -Runtime sessions, user interfaces, queues, and tool transports are outside the -process model. +This document defines the delivery process. Skills apply it. The project's sanctioned process interface is the only way to read or change delivery state; its server is authoritative. This process does not define local ledger formats or add a second record system. ## Canonical model ```text -EPIC -- optionally groups --> UR and/or SR - -UPPER (UR): UR -- contains --> acceptance scenario -> TEST_CASE -> TEST_RESULT - | - +-- may require --> SR - -LOWER (SR): SR -> CODE -> TEST_CASE -> TEST_RESULT +EPIC -> optional UR/SR requirements -> native code and test references +UR -> acceptance scenario -> TEST_CASE -> TEST_RESULT +UR acceptance scenario -- may require --> SR +SR -> CODE -> TEST_CASE -> TEST_RESULT -EPIC: PROPOSED -[HUMAN]-> TODO -> IN_PROGRESS -> IN_REVIEW -[HUMAN]-> DONE +EPIC: PROPOSED -> IN_PROGRESS -> IN_REVIEW -> DONE +UR/SR: PROPOSED -> IN_PROGRESS -> IN_REVIEW -> DONE + BLOCKED | DEFERRED | OBSOLETE when applicable -UR/SR: DERIVED -[HUMAN]-> PROPOSED -[HUMAN]-> TODO -> IN_PROGRESS -> IN_REVIEW -[HUMAN]-> DONE -UR/SR: DERIVED -[HUMAN]-> PENDING_VERIFICATION -[HUMAN]-> TODO -> IN_PROGRESS -> IN_REVIEW -[HUMAN]-> DONE -UR/SR: source-scoped baseline authorization -[publish as-built]-> PENDING_VERIFICATION -UR/SR with source-scoped baseline authority: PENDING_VERIFICATION -[complete current verified/delivered proof + one HUMAN acceptance]-> DONE - -TRACE: PENDING -> PASS | FAIL; PASS | FAIL -> STALE -> PASS | FAIL - -HUMAN: DRAFT -> OPEN -> ANSWERED -> CLOSED - DRAFT | OPEN | ANSWERED -> SUPERSEDED +Human decisions: implementation approval -> completion approval ``` -UR evidence is upper evidence, normally exercised through an acceptance/E2E -path. SR evidence is lower evidence, exercised at the appropriate unit, API, -component, contract, or integration boundary. Upper and lower evidence belong -to different requirement types. Normal development is red-first; the -existing-baseline path uses the proof specified under As-built verification -and acceptance. - -## Authority +The Epic is the normal unit of authorized delivery. Requirements express +behavior and link to implementation and evidence; they do not replace the +Epic's saved plan or human approvals. Upper evidence exercises a user outcome; +lower evidence exercises a system behavior. Existing-baseline work follows +its dedicated source-scoped process below. -Humans decide product intent, scope, architecture, acceptance, priority, -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). +## Authority and sources -| Tag | Source | -|---|---| -| `USER::` | Attributable human fact, decision, or approval | -| `DOC:` | Product, domain, architecture, or contract source | -| `CODE:` | Implementation source file | -| `TEST:` | Verification source file | -| `RUN:` | Observed test or runtime result | -| `EPIC:#
` | Existing Epic record | - -File citations name the source file. The cited file carries the requirement or -other item ID it supports. Optional line, symbol, test-name or section suffixes -are navigation hints; the citation auditor checks only that the file resolves. -Execution evidence separately identifies the tests that ran and their results. - -Missing support is an open question. Conflicting support remains a conflict -until a human resolves it. Code proves existing behavior, not intended -behavior. Repository state — branches, diffs, change lists, and version -control's own review queues — proves what the repository contains, not what -the loop holds; it is never a source for selection, status, or priority. -Here, **material** means capable of changing correctness, security, data -integrity, a public contract, trace completeness, acceptance, or testability. - -Session working notes — review write-ups, test plans, scratch alignment -records — are not authoritative sources and may be discarded at any time. A -durable record restates their content rather than pointing at them, and -identifiers internal to one (finding numbers, plan step ids, review round -labels) are never citable from records, code, or instructions. Provenance -for an applied change belongs to the change itself and its gate records. - -## Item ownership - -| Item | Owns | -|---|---| -| `EPIC` | Optional requirement grouping, human-readable outcome, shared scope and decisions, lifecycle, gates, aggregate views, completion record | -| `UR` | Actor, context, user outcome, source, inline acceptance scenarios, lifecycle, upper evidence, optional Epic membership | -| `SR` | Smallest independently implementable system behavior, source, boundary, scope, technical context, lifecycle, lower evidence, code/test links, optional UR and Epic relations | -| `CODE` | Implementing files, symbols, revisions, branches, and changes | -| `TEST_CASE` | Stable identity, targeted UR scenario or SR clause, expected observation | -| `TEST_RESULT` | Outcome, RED/passing role, validity, command/report, environment, and tested fingerprint | - -Acceptance scenarios are UR content, not separate lifecycle records. Split an -SR that contains independently implementable behaviors. Projects may retain -`REQ-*` IDs if each record declares its canonical kind. +Humans decide product intent, scope, architecture, acceptance, priority, and +workflow. Agents establish facts, write and review plans, implement approved +work, and report evidence. They do not infer human approval from silence, +prior work, a passing test, a commit, or a repository state. -## Trace completeness +Use the project's sanctioned process interface to read the Epic and its +requirements, save a plan, obtain recorded approvals, and read back results. +If it lacks a needed read or write, report the tooling gap through the +project's named channel. Do not read or edit process state through a local +ledger, private database connection, or direct API call. -The graph contains relationships, not execution order. Epic membership and -UR-to-SR links are optional. Never invent a parent to complete a trace. +Ground product claims in product documents, code, tests, or observed runs. +When a document supplies a claim, read the relevant passage and quote or +faithfully summarize it with the file and location. Code proves existing +behavior, not intended behavior. Repository status and a change list describe +the repository; they do not establish process approval or completion. -| Selected item | Complete trace | -|---|---| -| Epic | Every in-scope member requirement satisfies its applicable trace; every declared Epic gate passes | -| UR | Sourced outcome, scenarios, current upper evidence, and every SR explicitly required by those scenarios | -| SR | Lower trace: `SR -> CODE -> TEST_CASE -> TEST_RESULT` | +The process interface attributes human decisions and approvals to the person +who made them. In the saved plan, cite product sources in ordinary prose with +links or file locations and enough quoted or summarized context for another +reviewer to inspect the claim. A link audit checks whether a reference +resolves; it does not prove that the source supports the claim. -Every declared relation must be authoritative, reciprocal where stored twice, -and covered by the gates that depend on it. A missing optional relation is not -a gap. A code link identifies implementation; it does not prove correctness. -A test covering multiple clauses must identify every target and assertion. A -UR-to-SR relation makes the SR part of the UR trace; it does not make UR upper -evidence part of the SR lower trace. +## Items and traces -## Lifecycle states - -UR and SR use the same status vocabulary. - -| Status | Meaning | +| Item | Owns | |---|---| -| `DERIVED` | Inferred requirement awaiting human confirmation; all relations are candidate-only | -| `PENDING_VERIFICATION` | As-built behavior established by exact confirmation or source-scoped baseline authorization; awaiting current direct proof and acceptance; normal development entry applies when tests or behavior need development | -| `PROPOSED` | Confirmed or directly sourced requirement being prepared for entry | -| `TODO` | Entry trace passed and human entry approval was applied | -| `IN_PROGRESS` | Applicable red-first evidence work is underway | -| `IN_REVIEW` | Required evidence is complete; delivery, reconciliation, or completion acceptance remains | -| `DONE` | Delivered trace passed the applicable normal completion or existing-baseline acceptance gate, and human acceptance was applied | -| `BLOCKED` | Work cannot proceed; blocker and suspended status are recorded | -| `DEFERRED` | Work is postponed with reason, owner, target, and suspended status; excluded from ongoing delivery obligations | -| `OBSOLETE` | Soft-deleted requirement, retained as terminal rejection or supersession with decision/replacement linked; excluded from ongoing delivery obligations | - -A directly sourced requirement may start `PROPOSED`. An Epic uses -`PROPOSED -> TODO -> IN_PROGRESS -> IN_REVIEW -> DONE` and the same side states; -it has no `DERIVED` state. - -On release from `BLOCKED` or `DEFERRED`, restore only the strongest state -supported by current gates and evidence. - -### Applicable requirements - -Current requirement obligations exclude `OBSOLETE` and `DEFERRED` URs and SRs. -They impose no outstanding work, missing-proof, entry-origin, readiness, -routing, reconciliation, or completion obligation on ongoing delivery. This -applies to declared Epic members and confirmed required-SR dependencies, -including required SRs outside the selected Epic. Retain the stored identities, -relations, postponement metadata, decisions, evidence, and approval history. -Completing other work never turns a deferred requirement into `DONE`. - -`DONE` remains applicable accepted work. Active `BLOCKED` requirements, live -holds, suspended work selections, and unresolved material findings retain their -guards. A finding with disposition `DEFERRED` is not a deferred requirement. -Missing, physically deleted, unknown, or unconfirmed dependencies are not an -intentional exclusion and cannot be treated as satisfied proof. - -An entirely empty applicable delivery scope is an explicit no-op: it creates -no new acceptance or lifecycle promotion. A live UR whose required SRs are all -explicitly excluded has zero applicable lower obligations, but still needs its -own genuine current upper proof, delivery, and applicable human acceptance. - -Apply the rule per obligation and input. A gate or trace covering both excluded -and active work retains all obligations for its live inputs; an excluded member -does not waive changed live acceptance, failing live evidence, or unknown live -authority. Equivalent batch and individual completion use the same applicable -obligations, with any difference in scope or authority explained. - -Approval aggregates and section context stamps use the authoritative subject's -applicable members and content. Excluding or restoring a member changes the -applicable scope and its aggregate; ordinary progression within the applicable -set does not. Edits confined to excluded requirements do not change the live -aggregate or invalidate unrelated live proof through retained historical links. -Changing a genuine live input retains the declared invalidation consequences. -No old pin, section stamp, or `STALE` trace becomes current approval or `PASS` -merely because the denominator changed. Revalidate purpose-specific proof and -use the applicable existing restamp, review, re-entry, or immaterial reapply -path; preserve settled acceptance as history without accepting reopened work. - -### Resuming deferred requirements - -Resumption restores the requirement's current obligations. If doing so changes -a completed owner's approved scope, reopen that owner through its attributable -reversed-decision gate before restoring the member. Reopen affected accepted -URs explicitly when their acceptance changes; reopening an Epic alone does not -establish a UR's changed authority. Refuse a premature restoration under a -completed owner with this recovery step. A standalone requirement needs no -invented parent. - -For fresh planning, restore the deferred requirement conservatively to -`PROPOSED`. Retire only that requirement's old applied entry, if any, atomically -with its status change and attributed resumption event. Retain the actual -decision source and old approval history; do not invent a demotion decision, -entry origin, or passing proof. If retirement fails, none of that command's -status, event, or retirement effects commit. A shared legacy entry without -per-member application rows keeps its existing semantics for each untouched -covered member; one member's retirement cannot retire a sibling or grant entry -to an unrelated member. Retirement alone supplies no missing historical origin. - -Replan the resumed member under its original authority, obtain fresh applicable -entry, establish proof for new or changed obligations, then obtain successor -completion over the current live scope. Unchanged siblings retain their states -and approvals; revalidate their accepted proof at delivery. Other restoration -destinations require current retained authority and cannot revive a retired -entry or restore `DONE` from historical acceptance. Each command is atomic; -an interrupted multi-command sequence resumes from its recorded state and -receipts, rather than pretending the entire sequence committed together. - -Acceptance scenarios, code, test cases, and planning artifacts have no work -lifecycle. Evidence conclusions are not completion states: - -- `LOWER_VERIFIED`: current lower evidence for an SR. -- `UPPER_VALIDATED`: current upper evidence for UR acceptance content. +| `EPIC` | Human-readable outcome, explicit scope, saved plan and exact proposed content, decisions, lifecycle, implementation and completion approvals | +| `UR` | Actor, context, user outcome, sources, acceptance scenarios, optional Epic relation | +| `SR` | One independently implementable system behavior, source, boundary, technical context, code and test links | +| `CODE` | Implementing files, symbols, revision, branch and changes | +| `TEST_CASE` | Stable test identity, target clause and expected observation | +| `TEST_RESULT` | Outcome, command/report, environment when relevant, tested revision and validity | + +Requirement and Epic identifiers come from the authoritative process store. +Use those native IDs in plans, code/test links, review notes and evidence. +Never invent, derive, or substitute a path, slug, code, or external key for an +identity the store owns. + +A trace records relationships, not execution order. An Epic plan names the +selected requirements and their expected code/test evidence. An UR trace is +its sourced outcome, scenarios, current upper evidence and each SR the +scenario requires. An SR trace is `SR -> CODE -> TEST_CASE -> TEST_RESULT`. +Do not invent parent relations or code links to make a trace look complete. +A code link identifies implementation; it does not prove behavior. A test +that covers several clauses identifies each clause and assertion it checks. + +## Lifecycle + +`PROPOSED` is a draft. Human implementation approval moves the Epic and its +named requirements directly to `IN_PROGRESS`, retaining the exact approved plan +and proposed requirement content separately from published content. It atomically +locks the whole requirement set to that Epic and one user. A conflicting owner +must leave the whole approval unchanged. + +`IN_REVIEW` means implementation is complete and awaits human completion +approval. The ownership lock, approved proposal and prior published requirement +content remain unchanged. `DONE` follows human completion approval: atomically +publish the approved content, increment each requirement revision once, retain +an immutable accepted version with criteria and trace meaning, record the +actor, time, reason and originating Epic, and release ownership. A failed write +must roll back all effects; repeating completion must not publish twice. + +There is no READY/TODO entry step, requirement stage, evidence-conclusion status, +plan-revision token, fingerprint, generic gate or separate ownership framework. +Requirements keep their own native UUIDs and types; Epic membership and criterion +ownership are direct containment, while links among requirements, code, +documents and tests are traces. Requirement-to-document traces use `relates`. +`BLOCKED`, `DEFERRED` and `OBSOLETE` retain their actual reason and history when +applicable; none authorizes publication or erases an accepted version. ### Derived requirement hold @@ -287,577 +178,133 @@ Unavailability or explicit source revocation is shown honestly while retaining audit identity. Source/store read-backs and explicit coverage denominators are part of onboarding completion, not evidence of product verification. -## Gates - -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`. - -An approval-scope fingerprint identifies the requirement content, declared -relations, scope, and decisions being approved. An evidence fingerprint identifies -the tested code/content, tests, inputs, and revision. Each gate names its inputs. -Implementation within approved scope updates evidence; it does not by itself -invalidate entry approval. Changed approved scope or material review assumptions -require the affected gates to be re-evaluated. - -```text -authoritative trace -> TRACE PASS -> HUMAN OPEN -> attributable answer --> answer applied -> records reconciled -> HUMAN CLOSED - -application: NOT_APPLICABLE -> PENDING -> APPLIED | FAILED -``` - -`PASS` and `FAIL` become `STALE` when inputs change. `STALE` never counts as -pass. The first answer to an exact `OPEN` gate is immutable; changed scope or -decision creates a successor and marks the old gate `SUPERSEDED`. An application -failure leaves the gate `ANSWERED` and preserves its holds. - -Feedback not attached to an exact `OPEN` gate is a source or proposed decision, -not a gate answer. - -### Strict human transitions - -| Transition | Required trace `PASS` before human input | -|---|---| -| 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 | -| Source-scoped baseline requirement `PENDING_VERIFICATION -> DONE` | Complete exact current as-built verification and separate repository integration proof; one dedicated reviewed human acceptance | -| 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 applicable member is already `DONE` or named and completion-eligible in the same gate; the Epic completion predicate is satisfied | - -One human answer may cover an exact Epic and named requirements. Apply member -requirement transitions before the Epic and record a `USER:` source for each. - -Every human gate carries: - -```markdown -**Brief:** -- What: -- Why now: -- Changes if approved: -- Risk if wrong: -- Recommendation: