docs(neckbeard): require requester-outcome traceability at gate 3

Implements issue #378 (Finding F4 of the journey SDLC validation brief):
separate validation from verification in the change-request journey.

Gate 3 now requires that at least one SPEC.md acceptance criterion traces
to the requester's stated outcome/problem restated from primary evidence
in phase 2 - verification proves the build matches the spec; this
criterion proves it solves the requester's actual problem (15288/12207
validation vs. verification discipline).

- references/stages.md: authoritative new Gate 3 bullet (single source
  of truth for gate definitions)
- references/journey.md: phase 4 Output and Gate rows aligned, deferring
  to stages.md; phase-continuity and gate summary unchanged
- templates/change-contract.md: acceptance-criteria guidance requires a
  criterion tracing to the Problem section
- templates/delivery-packet.md: acceptance-criteria mapping field asks
  for the requester-outcome trace for the gate-3 verdict
- evals/evals.json: gate-3 assertions updated in four full-path cases;
  all 13 case IDs stable

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
2026-08-23 00:48:12 -04:00
co-authored by factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent b0f3a954de
commit 1cd5e19620
5 changed files with 13 additions and 5 deletions
File diff suppressed because one or more lines are too long
+2 -2
View File
@@ -76,8 +76,8 @@ assessed position under this journey's rules.
|---|---|
| **Owner** | `spec-driven-development` (see [routing-table.md](routing-table.md)) |
| **Input** | Phase 3 output: approved architecture delta, decisions, and risk assessment (gate 1 passed). |
| **Output** | Packet group (g) partially: `SPEC.md` with acceptance criteria mapped to the change contract; `TASK-PLAN.md` covering every spec item and acceptance criterion. No task is unbounded or ownerless. |
| **Gate** | **Gate 3** — specification and task-plan completeness (see [stages.md](stages.md)). `SPEC.md` and `TASK-PLAN.md` must be complete and approved before the planning phase exits. |
| **Output** | Packet group (g) partially: `SPEC.md` with acceptance criteria mapped to the change contract, including **at least one criterion traced to the requester's stated outcome/problem restated in phase 2** (packet group (d)); `TASK-PLAN.md` covering every spec item and acceptance criterion. No task is unbounded or ownerless. |
| **Gate** | **Gate 3** — specification and task-plan completeness (see [stages.md](stages.md)). `SPEC.md` and `TASK-PLAN.md` must be complete — including the requester-outcome traceability criterion — and approved before the planning phase exits. |
| **Escalation** | Requirements are irreconcilably ambiguous after product-discovery engagement; or scope exceeds granted authority and requires re-negotiation. |
| **Platform mapping** | **GitHub mode:** spec artifacts committed to the working branch; acceptance criteria may reference issue comments. **Enterprise mode:** spec artifacts stored per project conventions; requirements traced to the ticket tracker. |
+5
View File
@@ -218,6 +218,11 @@ the packet (group (f)). The gate is never silently skipped.
Chronologically the second gate. Planning may not complete until:
- `SPEC.md` exists with acceptance criteria **mapped to the change contract**;
- at least one acceptance criterion traces to the requester's stated
outcome/problem restated from primary evidence in phase 2 — verification
proves the build matches the spec; this criterion proves it solves the
requester's actual problem (15288/12207 validation vs. verification
discipline);
- `TASK-PLAN.md` covers **every** spec item and acceptance criterion;
- no task is unbounded (missing effort/scope estimate) or ownerless (no
assigned phase or specialist).
+4 -1
View File
@@ -35,7 +35,10 @@
## Acceptance criteria
<!-- Observable conditions that mean "satisfied." Each should be checkable at a
named boundary (unit / integration / end-to-end / production). -->
named boundary (unit / integration / end-to-end / production).
At least one criterion must trace back to the Problem section above —
it proves the change solves the requester's actual problem, not just
that the build matches the spec. -->
## Declared verification target
<!-- The boundary the contract actually cares about. This is what "done" must be
+1 -1
View File
@@ -100,7 +100,7 @@ continuing.
their content here. -->
- **SPEC.md path:** _[fill: e.g. `SPEC.md`]_
- **Acceptance criteria mapping:** _[fill: AC identifiers mapped to change-contract acceptance criteria]_
- **Acceptance criteria mapping:** _[fill: AC identifiers mapped to change-contract acceptance criteria; identify which criterion traces to the requester's stated outcome (contract Problem section, restated in phase 2) — required for the gate-3 verdict]_
- **Test strategy:** _[fill: test levels (unit / integration / end-to-end), regression coverage strategy]_
- **TASK-PLAN.md path:** _[fill: e.g. `TASK-PLAN.md`]_
- **QA verification plan path:** _[fill: e.g. `VERIFICATION-PLAN.md`]_