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..283ec7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,65 +1,96 @@ # 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, human + completion and existing-behavior acceptance. +- [`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. +- `skills/rdd-reverse-engineer-verify/SKILL.md` verifies PROPOSED requirements + against existing behavior and actual test evidence; it does not change their + lifecycle. +- `skills/rdd-reverse-engineer-accept/SKILL.md` obtains explicit human + acceptance and uses the supported atomic PROPOSED-to-DONE operation for + verified existing behavior. + +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` for +recording requirements and their traces to source files. +Use `skills/rdd-reverse-engineer-verify/SKILL.md` and +`skills/rdd-reverse-engineer-accept/SKILL.md` to verify and explicitly accept +existing behavior without an implementation Epic when no behavior or test +change is requested. Route any required code or test change through the normal +Epic delivery path. +`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 + +For changed behavior or tests, 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. +For an explicit existing-behavior acceptance pass, the human accepts the exact +PROPOSED requirements and complete passing evidence through the supported +atomic operation; active Epic-owned requirements stay on the Epic path. 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 or +existing-behavior acceptance; +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..ed18dd0 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -1,1171 +1,411 @@ # 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: PROPOSED -[HUMAN]-> TODO -> IN_PROGRESS -> IN_REVIEW -[HUMAN]-> DONE - -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 +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 -> IN_PROGRESS -> IN_REVIEW -> DONE +UR/SR: PROPOSED -> IN_PROGRESS -> IN_REVIEW -> DONE + PROPOSED -> DONE (verified existing behavior, explicit acceptance) + BLOCKED | DEFERRED | OBSOLETE when applicable + +Human decisions: implementation approval -> completion approval + or explicit acceptance of verified existing behavior ``` -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 - -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). - -| 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 +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. Reverse engineering records +requirements and source traces directly. An explicit request to verify and +accept behavior already present may use the separate PROPOSED-to-DONE path +below; any requested implementation or test change uses the normal Epic path. + +## Authority and sources + +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. + +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. + +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. + +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. + +## Items and traces | 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. - -## Trace completeness - -The graph contains relationships, not execution order. Epic membership and -UR-to-SR links are optional. Never invent a parent to complete a trace. - -| 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` | - -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. - -## Lifecycle states - -UR and SR use the same status vocabulary. - -| Status | Meaning | -|---|---| -| `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. - -### Derived requirement hold - -While a requirement is `DERIVED`: - -- record its candidate statement, inference sources, proposed relations, - conflicts, consequences, and confirmation brief; -- label every proposed relation `CANDIDATE`; -- exclude it from authoritative trace, release, readiness, coverage, progress, - and completion; -- candidate statements may include proposed UR scenarios, related candidates, - source links and references to existing tests so they are reviewable together; - all such content and artifacts remain candidate-only, excluded from ordinary - test lists, coverage, release snapshots and execution assignment; -- do not use a candidate to authorize implementation, test execution, - verification, entry, release commitments or delivery. - -```text -DERIVED -> confirmed/corrected ----------> PROPOSED - -> confirmed accurate as-built --> PENDING_VERIFICATION - -> rejected ---------------------> OBSOLETE -``` - -Confirmation proves the requirement exists. Requirement decisions and link -decisions are separate: one attributable action may cover an exact typed set -of URs/SRs and explicitly named proposed relationships at a checked packet and -graph fingerprint. Unselected links remain candidate-only and may be approved -later in a relationship-only decision. No Epic is required. Changed inputs -require a refreshed preview. Rejection publishes no links; deferral leaves the -candidate unchanged. Approval is additive and never overwrites a referenced -existing requirement or its compliance approval. - -Accepting as-built scope places it in Base/PENDING_VERIFICATION; accepting new -desired intent makes it PROPOSED and eligible for normal delivery planning. -Base is the store's destination for established as-built requirements, separate -from a delivery release; the project's store interface identifies that destination. -Neither action approves entry, verifies behavior, records a passing test result -or marks anything DONE. Candidate confirmation is not delivery release selection. - -### Source-scoped baseline onboarding - -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. - -A baseline authorization names the authenticated actor, system/store, immutable -repository/file and document revision inventory, current corpus fingerprint, -Base destination, permitted relationship publication and process revision. -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 -or conflicting existing content cannot silently expand the authorization. -Unchanged existing requirements may be reused only by exact identity/fingerprint. -Essential unresolved evidence remains an explicit DERIVED exception, never an -authoritative guess. Report partial publication and the exact remainder. - -Baseline requirements are PENDING_VERIFICATION, not compliance-approved or -verified. They and their grounded confirmed graph appear in authoritative -requirement views; DERIVED additions appear only in candidate review. A test -reference or stub is not an execution result. Optional Epics need real intended -members; do not manufacture discovery-container Epics or membership. - -Source capture preserves immutable repository/revision/path/digest identity, -including local changes. A historical read never substitutes latest code. -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: