diff --git a/AGENTS.md b/AGENTS.md index c89477b..6cd87cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,10 +11,12 @@ serialization shapes; it does not contain a project's live delivery state. completion, records, and reconciliation. - [`skills/`](skills/) contains focused procedures that apply the process. - [`file-state/`](file-state/) contains the canonical serialization shapes for - Epic, requirement, gate, work-selection, and backlog/gap records. -- Project instructions own only project-specific rules such as architecture, - repository topology, commands, environments, and test gates. They reference - rather than redefine the process. + Epic, requirement, engineering-constraint, gate, work-selection, and + backlog/gap records. +- Project instructions own project-specific sources such as architecture, + repository topology, commands, environments, and test gates. EC records cite + those sources and bind their rules into delivery; neither may redefine the + process. - `CLAUDE.md` files are compatibility pointers; they do not override these instructions. @@ -34,10 +36,12 @@ Before planning, changing, reviewing, or delivering product work: process pass; use `skills/rdd-verify/SKILL.md` for reverse-engineered `PENDING_VERIFICATION` rows, and `skills/rdd-reverse-engineer/SKILL.md` to adopt a codebase that has no requirement corpus yet; + `skills/rdd-engineering-check/SKILL.md` is the focused EC evaluator invoked + by cold and completion review, not a phase; `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. + active work-selection and engineering-constraint records. ## Binding process diff --git a/PROCESS.md b/PROCESS.md index 6a825e8..f04dced 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -17,11 +17,15 @@ UPPER (UR): UR -- contains --> acceptance scenario -> TEST_CASE -> TEST_RESULT LOWER (SR): SR -> CODE -> TEST_CASE -> TEST_RESULT +ENGINEERING: selected scope -> applicable ACTIVE EC -> engineering trace gate + 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 +EC: PROPOSED -[HUMAN]-> ACTIVE -[HUMAN]-> SUPERSEDED | RETIRED + TRACE: PENDING -> PASS | FAIL; PASS | FAIL -> STALE -> PASS | FAIL HUMAN: DRAFT -> OPEN -> ANSWERED -> CLOSED @@ -34,6 +38,11 @@ component, contract, or integration boundary. Both are red-first. They are evidence classes owned by different requirement types, not two arms of one requirement. +An engineering constraint (`EC`) is a persistent architectural, quality, or +engineering rule. It is not product behavior and does not use the UR/SR work +lifecycle. Applicable active ECs are evaluated independently by an engineering +trace gate during cold review and again against the delivered revision. + ## Authority Humans decide product intent, scope, architecture, acceptance, priority, @@ -49,6 +58,7 @@ be established from authoritative records, code, tests, or runtime evidence. | `TEST::` | Stable test-case identity | | `RUN:` | Observed test or runtime result | | `EPIC:#
` | Existing Epic record | +| `EC:` | Active engineering constraint in the authoritative process store | Missing support is an open question. Conflicting support remains a conflict until a human resolves it. Code proves existing behavior, not intended behavior. @@ -72,6 +82,7 @@ for an applied change belongs to the change itself and its gate records. | `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 | +| `EC` | Persistent architecture, quality, or engineering constraint; proposal evidence, authority, explicit scope, rationale, lifecycle, and verification method | Acceptance scenarios are UR content, not separate lifecycle records. Split an SR that contains independently implementable behaviors. Projects may retain @@ -95,6 +106,20 @@ 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. +Engineering conformance is a separate trace. For every selected scope, resolve +the complete flat set of `ACTIVE` ECs whose declared scope matches the affected +repository, language, service, domain, or path. ECs are not inherited through +profiles and are never copied onto URs or SRs. Resolve and fingerprint this set +after reconnaissance establishes the affected surface; initial resolution is +planning progress, not a change to the frozen work-selection fingerprint. + +Engineering checks produce separate trace-gate results for the planning packet, +the pre-delivery candidate, and the delivered revision. Each result records the +exact applicable EC set and target fingerprint, and every member must pass its +declared verification. Ambiguous applicability, a missing verification method, +or an unmet active EC fails the trace. A proposed, superseded, or retired EC does +not apply. + ## Lifecycle states UR and SR use the same status vocabulary. @@ -125,6 +150,26 @@ lifecycle. Evidence conclusions are not completion states: - `LOWER_VERIFIED`: current lower evidence for an SR. - `UPPER_VALIDATED`: current upper evidence for UR acceptance content. +### Engineering-constraint states + +| Status | Meaning | +|---|---| +| `PROPOSED` | Constraint statement, proposal evidence, scope, rationale, and verification method are being prepared for human activation | +| `ACTIVE` | Human-approved constraint included whenever its declared scope applies | +| `SUPERSEDED` | Terminal constraint version replaced by a named successor | +| `RETIRED` | Terminal constraint removed by an attributable human decision | + +Activating, superseding, or retiring an EC is a human decision. Code can prove +an observed convention but cannot make it normative. Changing an active EC's +statement, scope, or verification method creates a successor rather than +silently changing the approved constraint. EC activation is prospective from +the effective release or store revision recorded by its activation gate. After +the initial post-reconnaissance resolution, a changed affected surface or +applicable set makes a nonterminal selection's engineering, cold-review, and +entry gates stale and returns it to planning. It does not reopen a `DONE` scope +delivered before that effective point unless the activation decision explicitly +names it for remediation. + ### Derived requirement hold While a requirement is `DERIVED`: @@ -172,6 +217,8 @@ not a gate answer. | Transition | Required trace `PASS` before human input | |---|---| | Requirement `DERIVED -> PROPOSED/PENDING_VERIFICATION/OBSOLETE` | Candidate packet and exact confirmation scope complete | +| EC `PROPOSED -> ACTIVE` | Statement, proposal evidence, exact scope, effective point, rationale, verification method, and impact are complete | +| EC `ACTIVE -> SUPERSEDED/RETIRED` | Successor or retirement effect and affected scope are complete | | Requirement `PROPOSED/PENDING_VERIFICATION -> TODO` | Its Entry packet is complete at the exact fingerprint | | 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 | @@ -260,7 +307,11 @@ The fingerprinted packet must contain: Reconnaissance cites `DOC:`, `CODE:`, and `TEST:` sources. Generated context is navigation only. Material revision drift makes the packet and its dependent -reviews stale. +reviews stale. Once reconnaissance establishes the affected repository, +language, service, domain, and path surface, record the exact applicable active +EC ids and their set fingerprint in the work selection. This first resolution +does not alter the frozen selection fingerprint; changing the resolved surface +or EC set afterwards returns the packet to planning. Cold review runs from a context independent of packet authoring and audits the trace, scope, technical surface, changed flow, contracts, data, compatibility, @@ -271,6 +322,12 @@ in-scope deferred correctness, security, data-loss, contract, traceability, or testability findings fail the cold-review trace gate. Technical review cannot grant entry approval. +Cold review invokes `rdd-engineering-check` rather than embedding EC evaluation. +A current engineering trace `PASS` at the planning fingerprint is a prerequisite +for cold-review `PASS`. Engineering findings join the cold-review finding list, +but the broader technical review remains responsible for risks not expressed as +ECs; the flat EC set is not presumed complete. + 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`. @@ -302,6 +359,15 @@ Before each phase, reconcile answered gates and state, then select the earliest unmet prerequisite. A focused skill's exit is a handoff, not completion of the full loop. +`rdd-engineering-check` is a shared utility, not a phase. Cold review invokes it +against the planning fingerprint. Completion review invokes it first against +the candidate code before integration, then records a separate result against +the delivered fingerprint. It evaluates EC conformance and records engineering +trace gates; it does not perform the rest of either review or change lifecycle +state. Approved implementation changes do not stale the planning result because +code is not an input to that result; they require the separate candidate and +delivered results. + ### AI TDD inner loop After human entry places the selected scope in `TODO`, the AI owns the automatic @@ -397,15 +463,18 @@ Supplemental evidence causes no demotion. Re-verification may restore completion gate. Material approved-scope changes stale entry approval and send 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. +Delivery may proceed only after the pre-delivery candidate has a current passing +engineering trace. 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, the separate delivered +engineering trace is current and passing, and gaps/deferrals/decisions are +disclosed. | Item | `DONE` predicate after human acceptance | |---|---| -| SR | Its lower trace is delivered, current, and reconciled | -| UR | All scenarios have current upper evidence; every required SR has a complete lower trace; result is delivered and reconciled | -| Epic | Every member is `DONE`; applicable member and declared Epic gates pass; Epic scope is delivered and reconciled | +| SR | Its lower trace is delivered, current, and reconciled; the delivered engineering trace passes | +| UR | All scenarios have current upper evidence; every required SR has a complete lower trace; result is delivered and reconciled; the delivered engineering trace passes | +| Epic | Every member is `DONE`; applicable member, Epic, and delivered engineering gates pass; Epic scope is delivered and reconciled | Completing one item never advances an optional related item unless that item independently satisfies its predicate and is named in the human gate. @@ -431,22 +500,24 @@ currency is checkable per file. file-state/ EPICS.md REQUIREMENTS.md + ENGINEERING-CONSTRAINTS.md GATES.md WORK-SELECTION.md BACKLOG.md ``` `EPICS.md` stores optional grouping records. `REQUIREMENTS.md` stores URs, SRs, -declared relations, and trace references. `GATES.md` stores every trace and -human gate record. `WORK-SELECTION.md` stores the frozen scope, suspended -selections, and selection history. `BACKLOG.md` stores unrouted triage items -and gap records. Derived queues and progress views — including the pending -human-decision projection — are regenerated, not backed up separately. +declared relations, and trace references. `ENGINEERING-CONSTRAINTS.md` stores +the flat EC set and its lifecycle. `GATES.md` stores every trace and human gate +record. `WORK-SELECTION.md` stores the frozen scope, suspended selections, and +selection history. `BACKLOG.md` stores unrouted triage items and gap records. +Derived queues and progress views — including the pending human-decision +projection — are regenerated, not backed up separately. | Concern | Authority | |---|---| | Product/domain/architecture/contracts | Product documents and schemas | -| Epic, requirement, relation, gate, decision, release, and work-selection state | Authoritative process store | +| Epic, requirement, relation, EC, gate, decision, release, and work-selection state | Authoritative process store | | Code, test cases, and results | Implementation repository plus exact evidence references | | Aggregate progress and human queues | Generated projections; never lifecycle authority | @@ -470,6 +541,7 @@ After every transition, update the complete affected graph and run checks for: - valid identities/statuses and reciprocal declared relations; - stable test identities, revision-pinned validity, and invalidation cascades; - exact gate fingerprints and legal gate/state transitions; +- exact applicable active EC sets and current engineering-trace results; - no `TODO` without applied entry approval; - no `DONE` without delivered evidence, reconciliation, and applied completion; - isolation of `DERIVED` items and candidate links from authoritative scope; @@ -484,6 +556,7 @@ human decisions. |---|---| | Inferred possible requirement | `DERIVED` plus confirmation gate; links remain candidate-only | | Directly sourced requirement | `PROPOSED` UR or SR | +| Observed or requested architecture, quality, or engineering rule | `PROPOSED` EC; inactive until its human activation gate closes | | Missing human decision or ambiguity | Decision gate; `BLOCKED` only when work cannot proceed | | Known future work | `DEFERRED` with reason, owner, and target | | Capability/specification gap | Gap linked to affected traces | diff --git a/README.md b/README.md index da7f989..670fdac 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,13 @@ EPIC -- optionally groups --> UR and/or SR UR -> acceptance scenario -> TEST_CASE -> TEST_RESULT UR acceptance scenario -- may require --> SR SR -> CODE -> TEST_CASE -> TEST_RESULT +selected scope -> applicable ACTIVE EC -> engineering trace gate -Each selected trace passes planning, technical review, human entry, red-first -evidence, implementation, cleanup, verification, delivery, reconciliation, -and human completion. +Each selected product trace passes planning, technical review, human entry, +red-first evidence, implementation, cleanup, verification, delivery, +reconciliation, and human completion. Its separate engineering trace evaluates +the applicable flat EC set during cold review, before integration, and at the +delivered revision. ``` Product repositories hold authoritative process records in one selected store, @@ -43,8 +46,8 @@ apply that model; `file-state/` serializes its records without redefining it. | `AGENTS.md` | shared agent policy and canonical entry point | | `PROCESS.md` | complete canonical process | | `CLAUDE.md` | root compatibility entry required for Claude discovery | -| `skills/` | full-loop orchestration plus focused procedures for discovery, planning, review, building, triage, completion, and as-built verification; corpus adoption for codebases without requirement records (`rdd-reverse-engineer`); a shared document/citation auditing utility (`rdd-audit`) | -| `file-state/` | canonical serialization shapes for Epic, requirement, gate, work-selection, and backlog/gap records | +| `skills/` | full-loop orchestration plus focused procedures for discovery, planning, review, building, triage, completion, and as-built verification; a focused flat-EC evaluator (`rdd-engineering-check`); corpus adoption for codebases without requirement records (`rdd-reverse-engineer`); a shared document/citation auditing utility (`rdd-audit`) | +| `file-state/` | canonical serialization shapes for Epic, requirement, engineering-constraint, gate, work-selection, and backlog/gap records | ## Distribution @@ -68,8 +71,8 @@ human gates with current passing prerequisites. Neither is an authority; see ## Process maintenance Changes to lifecycle, status meanings, trace relationships, gate requirements, -evidence rules, or record ownership belong in `PROCESS.md`. Validate internal -links and search the skills and flat-file shapes for competing authority -statements whenever it changes. +evidence rules, engineering-constraint semantics, or record ownership belong in +`PROCESS.md`. Validate internal links and search the skills and flat-file shapes +for competing authority statements whenever it changes. License: MIT. diff --git a/file-state/BACKLOG.md b/file-state/BACKLOG.md index 8ee03f0..65e71f2 100644 --- a/file-state/BACKLOG.md +++ b/file-state/BACKLOG.md @@ -24,8 +24,8 @@ requirement and does not belong here. - **Raised by / at:** «USER:/CODE:/RUN:/TEST: source» / «timestamp» - **Observed:** «what was seen, not what it implies» - **Why unrouted:** «unclear owner, cross-cutting, or awaiting a decision» -- **Candidate route:** «PROPOSED UR/SR, DERIVED, gap, conflict, or decision gate» -- **Affected items:** «EPIC/UR/SR ids, or none known» +- **Candidate route:** «PROPOSED UR/SR, PROPOSED EC, DERIVED, gap, conflict, or decision gate» +- **Affected items:** «EPIC/UR/SR/EC ids, or none known» - **Disposition:** OPEN / ROUTED to «id» / REJECTED with «source» ## Gap records diff --git a/file-state/ENGINEERING-CONSTRAINTS.md b/file-state/ENGINEERING-CONSTRAINTS.md new file mode 100644 index 0000000..257aead --- /dev/null +++ b/file-state/ENGINEERING-CONSTRAINTS.md @@ -0,0 +1,33 @@ +# Engineering-constraint flat-file state + +> Canonical EC serialization for the authoritative process store. `PROCESS.md` +> defines EC ownership, lifecycle, applicability, and engineering trace rules. +> A store-backed repository materializes this file from the store; a file-backed +> repository versions it as the store. Never both. + +- **Snapshot at:** «timestamp» +- **Source store/revision:** «database revision or repository SHA» +- **Context / release:** «scope» + +This is one flat set. There are no profiles, inheritance rules, or implicit +service defaults. Every constraint declares its own applicability. + +## EC-«AREA»-«NNN» — «Title» + +- **Kind:** ARCHITECTURE / QUALITY / ENGINEERING +- **Status:** PROPOSED / ACTIVE / SUPERSEDED / RETIRED +- **Statement:** «one normative rule» +- **Proposal evidence:** «USER:/DOC:/CODE:/TEST:/RUN: observations supporting the proposal» +- **Authority:** «applied human activation gate and optional normative DOC: source; none while unapproved» +- **Rationale:** «why the constraint exists and the consequence it prevents» +- **Scope:** «global, or explicit repository/language/service/domain/path targets» +- **Effective from:** «release or store revision established by the activation gate» +- **Owner:** «person or team responsible for the rule» +- **Verification:** «deterministic command/check, architecture test, static analysis, or exact review observation» +- **Activation/retirement gates:** «GATES.md gate ids» +- **Supersedes / superseded by:** «EC id or none» +- **Notes:** «ambiguities or none» + +Code may support a proposal as evidence of an observed convention, but only an +attributable human source and applied activation gate make an EC `ACTIVE`. +Changing an active statement, scope, or verification method creates a successor. diff --git a/file-state/EPICS.md b/file-state/EPICS.md index 481133e..f1b4d88 100644 --- a/file-state/EPICS.md +++ b/file-state/EPICS.md @@ -14,7 +14,7 @@ - **Scope / non-goals:** «included and excluded change» - **Owner / release:** «owner and release» - **Members:** «UR/SR ids with CONFIRMED membership; candidate ids labelled CANDIDATE» -- **Shared context:** «cross-cutting decision, specification, reconnaissance, and cold-review refs» +- **Shared context:** «cross-cutting decision, specification, applicable EC refs, reconnaissance, and cold-review refs» - **Entry gates:** «GATES.md gate ids» - **Completion gates:** «GATES.md gate ids» - **Delivered revision:** «repository + revision or not delivered» diff --git a/file-state/GATES.md b/file-state/GATES.md index 55853d1..d771c54 100644 --- a/file-state/GATES.md +++ b/file-state/GATES.md @@ -15,15 +15,15 @@ recorded prerequisite trace gate is unreadable, not implicitly open. ## GATE-«AREA»-«NNN» — «Transition or decision purpose» -- **Kind:** trace or human / «confirmation, entry, decision, cold-review, start-review, completion» +- **Kind:** trace or human / «confirmation, EC activation/retirement, engineering-check (planning/candidate/delivered), entry, decision, cold-review, start-review, completion» - **Transition / purpose:** «exact state transition, or the decision being asked» -- **Exact scope:** «named EPIC/UR/SR ids this gate covers; one answer may cover an Epic and named members» +- **Exact scope:** «named EPIC/UR/SR/EC ids this gate covers; one answer may cover an Epic and named members» - **Prerequisites:** «gate ids that must be PASS before this one may leave DRAFT, or none» - **Fingerprint:** «content/code fingerprint the gate was evaluated at» - **State:** «trace: PENDING / PASS / FAIL / STALE — human: DRAFT / OPEN / ANSWERED / CLOSED / SUPERSEDED» - **Verdict / answer:** «trace verdict with exact blockers, or the human answer as given» - **Actor / evaluator:** «real human actor and role for a human gate; evaluating agent or check for a trace gate» -- **Sources:** «USER:/DOC:/CODE:/TEST:/RUN:/EPIC: support for the verdict or answer» +- **Sources:** «USER:/DOC:/CODE:/TEST:/RUN:/EPIC:/EC: support for the verdict or answer» - **Timestamps:** «evaluated/opened at; answered at; closed at» - **Application:** «NOT_APPLICABLE / PENDING / APPLIED / FAILED» at «revision» - **Predecessor / successor:** «superseded gate id and successor gate id, or none» @@ -44,5 +44,5 @@ Human gates only. Omit for trace gates. ### Holds -- **Held items:** «EPIC/UR/SR ids blocked until this gate closes, or none» +- **Held items:** «EPIC/UR/SR/EC ids blocked until this gate closes, or none» - **Applied transitions:** «item id -> from -> to, one per line; empty until APPLIED» diff --git a/file-state/REQUIREMENTS.md b/file-state/REQUIREMENTS.md index 5438449..a85ca14 100644 --- a/file-state/REQUIREMENTS.md +++ b/file-state/REQUIREMENTS.md @@ -35,6 +35,7 @@ and `Fingerprint` carry the remaining mandated evidence-record fields. - **Confirmation gates:** «GATES.md gate ids, or N/A» - **Entry gates:** «GATES.md gate ids» - **Start/review gates:** «GATES.md gate ids» +- **Engineering-check gates:** «GATES.md gate ids» - **Completion gates:** «GATES.md gate ids» - **Delivered revision:** «repository + revision or not delivered» - **Gaps / deferrals / blockers / notes:** «refs or none» diff --git a/file-state/WORK-SELECTION.md b/file-state/WORK-SELECTION.md index d819fa2..2a21270 100644 --- a/file-state/WORK-SELECTION.md +++ b/file-state/WORK-SELECTION.md @@ -19,8 +19,9 @@ authoritative store and are not recorded here. - **Selected scope:** «EPIC id, or the single SR id» - **Members:** «UR/SR ids in the frozen scope; empty for single-SR scope» - **Scope kind:** Epic or single SR -- **Frozen at fingerprint:** «content/code fingerprint the selection was frozen at» +- **Frozen at fingerprint:** «selected content/scope fingerprint; EC applicability is unresolved here» - **Reconnaissance revision:** «named revision the packet was authored against» +- **Applicable EC set / fingerprint:** «unresolved before reconnaissance; then exact active EC ids and set fingerprint» - **Current phase:** «source / plan / cold review / entry / build / verify / completion / triage» - **Waiting on:** «gate id, blocker, external prerequisite, or nothing» - **Owner:** «who holds the selection» diff --git a/skills/rdd-cold-review/SKILL.md b/skills/rdd-cold-review/SKILL.md index c128b59..c416749 100644 --- a/skills/rdd-cold-review/SKILL.md +++ b/skills/rdd-cold-review/SKILL.md @@ -8,26 +8,31 @@ description: Independently audit a requirement planning packet before implementa Start from a context independent of the planning-authoring conversation. Read the project `AGENTS.md`, canonical `PROCESS.md` (`.modernpath/rdd/PROCESS.md` in a consuming repository), versioned product sources, selected requirements, -optional epic/specifications, technical reconnaissance, and repository state at -the recorded revision. +optional epic/specifications, active engineering constraints, technical +reconnaissance, and repository state at the recorded revision. ## Procedure 1. Audit the authoritative graph and selected scope without relying on unstated author reasoning. -2. Verify the affected repositories, files, symbols, entry points, callers, +2. Invoke `skills/rdd-engineering-check/SKILL.md` with target `PLANNING` + against the exact planning fingerprint and post-reconnaissance EC set. Import + its findings and require its current trace gate to pass; do not reproduce its + EC-by-EC procedure here. +3. Verify the affected repositories, files, symbols, entry points, callers, writers, readers, and every changed control/data-flow hop. -3. Examine contracts, schemas, compatibility, persistence, integrations, +4. Examine contracts, schemas, compatibility, persistence, integrations, failure propagation, retries, concurrency, security, and operational risks where applicable. -4. Assess feasibility, dependency order, SR boundaries, reuse of established +5. Assess feasibility, dependency order, SR boundaries, reuse of established patterns, testability, expected RED reasons, and proportional gates. -5. Identify any product, architecture, acceptance, or scope choice that lacks +6. Identify any product, architecture, acceptance, or scope choice that lacks human authority. -6. Record each finding with severity, direct source, owner, and disposition as +7. 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 - in `PROCESS.md` is satisfied. Otherwise return `FAIL` with exact blockers. +8. Return the cold-review trace gate `PASS` only when the engineering trace is + current and passing and 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 inventories against the code — scoped to the packet's affected surface. Its @@ -39,5 +44,5 @@ 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. +dispositions, engineering and cold-review trace-gate verdicts, and the exact +handoff: `rdd-plan` after a failure or `rdd-entry-review` after a current pass. diff --git a/skills/rdd-completion-review/SKILL.md b/skills/rdd-completion-review/SKILL.md index 08829f5..dd02551 100644 --- a/skills/rdd-completion-review/SKILL.md +++ b/skills/rdd-completion-review/SKILL.md @@ -18,18 +18,26 @@ records, and derived views. 2. Stop for any `DERIVED` dependency, candidate link counted as authoritative, stale or inherited-unverified evidence, missing RED observation, material 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 +3. Invoke `skills/rdd-engineering-check/SKILL.md` with target `CANDIDATE` + against the completed pre-delivery code. Do not integrate unless the complete + applicable active EC set has a current engineering trace `PASS`. +4. If the pre-delivery audit and candidate engineering check pass, deliver + through the project's authorized integration path while keeping awaiting + entities `IN_REVIEW`. +5. 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 +6. Invoke `skills/rdd-engineering-check/SKILL.md` with target `DELIVERED` and + rerun or confirm the candidate checks against the delivered fingerprint. + Record a separate delivered engineering result and stop unless it is current + and `PASS`. +7. Record completion trace `PASS` only for the exact eligible fingerprint. 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, +8. 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 +9. 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. @@ -38,4 +46,5 @@ records, and derived views. Report proven, contradicted, incomplete, indirect, and missing completion facts; delivered revision; reconciliation result; gate states; applied -transitions; and remaining work. +transitions; applicable ECs and planning/candidate/delivered engineering +verdicts; and remaining work. diff --git a/skills/rdd-deliver/SKILL.md b/skills/rdd-deliver/SKILL.md index 6902d59..b195c05 100644 --- a/skills/rdd-deliver/SKILL.md +++ b/skills/rdd-deliver/SKILL.md @@ -18,8 +18,9 @@ all semantics; this skill owns phase order and continuation. prerequisite. Never start from the most convenient phase. 3. If input is not authoritative or is `DERIVED`, apply `rdd-discover` and its confirmation gate. Continue only with confirmed requirements and relations. -4. Apply `rdd-plan`, then `rdd-cold-review`, then `rdd-entry-review`. Repeat from - the earliest stale or failed pass until the exact selected scope is `TODO`. +4. Apply `rdd-plan`, then `rdd-cold-review` with its separate engineering check, + then `rdd-entry-review`. Repeat from the earliest stale or failed pass until + the exact selected scope is `TODO`. 5. Run the AI TDD inner loop below. Apply `rdd-build` to changed SRs and `rdd-verify` to human-confirmed as-built URs or SRs. Continue until every selected requirement satisfies its applicable trace and is `IN_REVIEW`. @@ -69,5 +70,6 @@ external blocker when progress cannot continue. ## Report Report the selected scope and fingerprint, completed phases, current lifecycle -states, trace and human gates, evidence and delivered revision, discoveries, -and either the terminal result or the exact next phase and prerequisite. +states, product/engineering/human gates, evidence and delivered revision, +discoveries, and either the terminal result or the exact next phase and +prerequisite. diff --git a/skills/rdd-engineering-check/SKILL.md b/skills/rdd-engineering-check/SKILL.md new file mode 100644 index 0000000..1b2c2da --- /dev/null +++ b/skills/rdd-engineering-check/SKILL.md @@ -0,0 +1,62 @@ +--- +name: rdd-engineering-check +description: Evaluate the complete flat set of active engineering constraints applicable to an exact planning, pre-delivery candidate, or delivered fingerprint. Use from RDD cold review and completion review. Produces a distinct engineering trace verdict and findings for each target; it does not replace technical review, change constraint authority, or advance lifecycle state. +--- + +# Check engineering constraints + +Read the project `AGENTS.md`, canonical `PROCESS.md` +(`.modernpath/rdd/PROCESS.md` in a consuming repository), the authoritative +engineering-constraint records, selected scope, affected-surface +reconnaissance, relevant code and configuration, and current gate records. + +## Procedure + +1. Fix the evaluation target as `PLANNING`, `CANDIDATE`, or `DELIVERED`, with + the selected Epic or SR scope, affected repository, revision, and exact + packet or code fingerprint. Never reuse one target kind's result as another. +2. Resolve the complete flat set of `ACTIVE` ECs whose explicit scope matches + the affected repository, language, service, domain, or path. Do not use + profiles, inheritance, naming conventions, or presumed defaults. Record how + each EC was included or excluded, honor its recorded effective point, and + compare the result with the post-reconnaissance EC set in work selection. + Ambiguous applicability or a set mismatch is a failure. +3. Evaluate every applicable EC using its declared verification method and + direct `DOC:`, `CODE:`, `TEST:`, or `RUN:` evidence. Run deterministic + commands when available. For `PLANNING`, assess the planned approach and its + declared enforcement path at the reconnaissance revision. For `CANDIDATE`, + evaluate the completed implementation before integration. For `DELIVERED`, + rerun or confirm the check against the delivered revision. +4. Record each unmet or unevaluable EC as a finding with severity, direct + source, owner, and `OPEN`, `RESOLVED`, `DEFERRED`, or `REJECTED` + disposition. An EC is normative while active; a deferred or rejected + finding does not make nonconformance pass. +5. Record a distinct engineering trace gate for the target kind, exact target + fingerprint, and exact applicable EC-id set. Return `PASS` only when the set + is complete, every applicable EC is proven conformant, and no applicability + conflict is unresolved. If no EC applies, record `0 applicable`, the + resolution basis, and `PASS`; silence is not an evaluated result. +6. Apply staleness only from the inputs owned by that result: + - `PLANNING` becomes `STALE` when the selected scope, packet, + reconnaissance revision or affected surface, applicable EC set, or an + applicable EC changes. Approved implementation changes alone do not stale + it. + - `CANDIDATE` becomes `STALE` when its candidate code fingerprint or + applicable EC set changes. + - `DELIVERED` becomes `STALE` when its delivered fingerprint or applicable + EC set changes. +7. Feed the findings and gate verdict to the invoking review. Candidate code + that expands the approved affected surface invalidates planning rather than + being treated as an ordinary code-fingerprint change. + +Do not create, activate, edit, retire, or waive an EC during this check. Do not +make an architecture or engineering-policy decision, modify implementation to +clear a finding, grant cold-review or completion approval, or treat a proposed, +superseded, or retired EC as active. + +## Report + +Report the evaluated fingerprint and revision; applicable EC ids with the +scope match that selected each one; evidence and result per EC; exclusions, +ambiguities, and findings; the engineering trace-gate verdict; and the exact +handoff to the invoking cold or completion review. diff --git a/skills/rdd-engineering-check/agents/openai.yaml b/skills/rdd-engineering-check/agents/openai.yaml new file mode 100644 index 0000000..4b1bff1 --- /dev/null +++ b/skills/rdd-engineering-check/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "RDD Engineering Check" + short_description: "Check applicable engineering constraints" + default_prompt: "Use $rdd-engineering-check to evaluate the active engineering constraints for this requirement scope." diff --git a/skills/rdd-entry-review/SKILL.md b/skills/rdd-entry-review/SKILL.md index 656861f..bdd3a03 100644 --- a/skills/rdd-entry-review/SKILL.md +++ b/skills/rdd-entry-review/SKILL.md @@ -16,7 +16,8 @@ packet, cold-review findings, current gate records, and relevant sources. 2. Fail the entry trace for missing or conflicting sources, `DERIVED` items, candidate links counted as authoritative, ambiguous acceptance, broad SRs, stale reconnaissance, incomplete implementation context, inadequate RED - strategy, or unresolved material cold-review findings. + strategy, a missing/failed/stale engineering trace, or unresolved material + cold-review findings. 3. Record the entry trace gate against the exact content fingerprint. 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` diff --git a/skills/rdd-plan/SKILL.md b/skills/rdd-plan/SKILL.md index 0bf9f97..c31a6ba 100644 --- a/skills/rdd-plan/SKILL.md +++ b/skills/rdd-plan/SKILL.md @@ -7,8 +7,9 @@ description: Prepare an epic-scoped or single-SR planning packet for controlled Read the project `AGENTS.md`, canonical `PROCESS.md` (`.modernpath/rdd/PROCESS.md` in a consuming repository), relevant product -sources, requirement records, code, tests, and optional epic. Apply the Work -scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. +sources, requirement records, active engineering constraints, code, tests, and +optional epic. Apply the Work scope, Item ownership, and Planning and readiness +sections of `PROCESS.md`. ## Procedure @@ -22,7 +23,12 @@ 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, project gates, and unknowns. Make + the affected repository, language, service, domain, and path explicit enough + for `rdd-engineering-check` to resolve EC applicability independently. Once + that surface is known, resolve and record the exact active EC ids and set + fingerprint in work selection; this initial post-reconnaissance update does + not change the frozen selection fingerprint. 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. @@ -36,4 +42,5 @@ scope, Item ownership, and Planning and readiness sections of `PROCESS.md`. ## Report Report the selected scope, authoritative graph, reconnaissance revision, -planned evidence, unresolved decisions, blockers, and cold-review input. +applicable EC set and fingerprint, planned evidence, unresolved decisions, +blockers, and cold-review input. diff --git a/skills/rdd-triage/SKILL.md b/skills/rdd-triage/SKILL.md index fb43cfc..320b6c1 100644 --- a/skills/rdd-triage/SKILL.md +++ b/skills/rdd-triage/SKILL.md @@ -24,10 +24,13 @@ order. the postponement, capability/specification gaps to gap records, unclear ownership to backlog, and contradicted or removed behavior to an explicit conflict or `OBSOLETE` decision. -5. For feedback, determine whether one standalone or UR-linked SR can address +5. Route a proposed architecture, quality, language, service, domain, or code + rule to a flat `PROPOSED` EC and its activation gate. It remains inactive + until an attributable human answer is applied. +6. For feedback, determine whether one standalone or UR-linked SR can address it without changing user outcome, acceptance, or a cross-cutting decision. Otherwise route it to epic-scoped planning. -6. Re-evaluate stale gates and evidence, then reconcile authoritative records, +7. Re-evaluate stale gates and evidence, then reconcile authoritative records, release scope, work selection, and derived views. Never promote to `TODO` without the strict entry gate.