qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/contract-artifact-rules.md

@@ -20,11 +20,159 @@ Discussion UI/UX files are upstream discovery artifacts. `/qfai-sdd` normalizes
 - `api/`, `db/`, and `ui/` contracts must declare `QFAI-CONTRACT-ID` at the top.
 - Use prefixes `CON-API-*`, `CON-DB-*`, and `CON-UI-*`.
 - `design/` files do not require `QFAI-CONTRACT-ID`, but they are execution-time SSOT for UI-bearing work.
+- **Declare apply-order dependencies.** `QFAI-CONTRACT-011` makes a second
+  `QFAI-CONTRACT-ID` in one file a hard `error`, so any schema larger than one
+  table necessarily becomes N cross-referencing files. State the resulting
+  composition rather than leaving every consumer to reconstruct it from the DDL:
+  - `db/`: a comment line `-- Depends on: CON-DB-0002, CON-DB-0003` (or `-`)
+  - `api/` / `ui/`: `x-qfai-depends-on: [CON-API-0002]`, flow or block form
+  - Mirror the same list in `_policies/05_Contracts.md`'s `Depends On` column.
+  - **Apply order only.** A reference resolved at run time — a deferred foreign
+    key, an endpoint another calls during a request — is not an apply-order
+    dependency and must not be listed. The apply graph is acyclic by
+    construction; the runtime graph legitimately is not, and conflating them
+    makes the declaration unusable for ordering.
+  - `QFAI-CONTRACT-014` (error) reports a declared dependency naming a contract
+    that does not exist. Getting the set wrong is otherwise silent: the wrong
+    subset still applies cleanly and the tests still pass, against a schema
+    missing the tables under test.
+- **Target schema is the applier's, not the contract's.** A `db/` contract
+  declares unqualified object names and is applied into whatever schema the
+  runner selects (`SET search_path`, `USE`, the connection's default). Do not
+  hard-code a schema qualifier: a contract that names one cannot be applied into
+  a per-test or per-tenant schema, which is what the integration layer needs.
 - Breaking changes require delta notes.
 - `_policies/05_Contracts.md` is the contract index; it must align with `.qfai/contracts/**` and must not become behavior SSOT.
 
+## What validation checks in a `.sql` contract
+
+Scope is **apply-ability, not semantic correctness**. `.sql` used to be the only
+contract kind the validator never parsed — the "this contract does not parse" check
+guarding UI and API files was unreachable for it — so a DB contract that cannot
+run passed `npx qfai validate --profile sdd --fail-on error`. It now has a structural lane:
+
+| Finding             | Fires when                                                                    | Severity |
+| ------------------- | ----------------------------------------------------------------------------- | -------- |
+| `QFAI-CONTRACT-021` | an unterminated string, comment or dollar-quoted body, or unbalanced `(`      | error    |
+| `QFAI-DB-002`       | one file creates the same object twice — only the last definition is in force | error    |
+
+`QFAI-DB-002` covers tables, views, indexes, functions, procedures, types and
+domains. **Triggers are excluded**: a trigger name is unique per table, not per
+schema, so two same-named triggers on different tables are correct SQL and
+reporting them would be a false positive on valid input.
+| `QFAI-DB-001` | a dangerous statement (`DROP TABLE`, `TRUNCATE`, …) | warning |
+
+The statement splitter honours SQL quoting, so a `;` inside a literal, a
+comment, a `$$ … $$` body or parentheses does not end a statement.
+
+**Not checked**: nothing here type-checks a query, resolves a column, or
+verifies the schema against the API contract. A green run means the file could
+be handed to a database and does not contradict itself about what it defines —
+it does not mean the schema is right. Cross-contract agreement remains the
+authoring obligation below.
+
+## Cross-contract Reconciliation (MUST)
+
+Contracts are validated per file; agreement _between_ contracts is an authoring obligation.
+
+- Every terminal state, status enum value, and error code an API contract mandates MUST have a
+  representable counterpart in the paired DB contract. An outcome the API requires but the DB
+  domain (`CHECK (... IN (...))`, `CREATE TYPE ... AS ENUM`, inline `ENUM(...)`) cannot store is a
+  contradiction, not an implementation detail.
+- Failure and rejection paths count. If the API consumes a transaction on a validation failure,
+  the DB must have an honest terminal value for that failure — do not reuse a success state whose
+  own preconditions cannot hold on failure, and do not relabel a rejection as an expiry.
+- Resolve the contradiction in the contracts, in Phase 0. Never resolve it downstream by
+  fabricating values that satisfy both.
+- Record the pairing you reconciled in `_policies/05_Contracts.md` so the scope is declared rather
+  than guessed.
+
+`QFAI-CONTRACT-040` mechanizes the state/status-domain part of this rule at `warning` severity. It
+is a partial check: error codes, response-status sets, and non-enum domains are still reconciled by
+the author and the reviewer gate.
+
+## Executability (MUST)
+
+A contract this file calls "downstream execution truth" has to have been
+executed. Everything else qfai asserts about a `db/` contract — one
+correctly-prefixed unique ID, four dangerous-SQL patterns at `warning` — is
+satisfied by a file that cannot run.
+
+- **Apply every `db/` contract to a scratch database.** Applying cleanly is the
+  floor, not the gate: contracts that apply without a single error still fail at
+  runtime, because the failure is a resolution error inside a PL/pgSQL body,
+  not a syntax error.
+- **Drive every declared write path at least twice.** The second traversal is
+  what exercises head-advance and expected-version guards; a single pass proves
+  the first insert and nothing after it. Defects that appear only on traversal
+  two are a normal share of the total, not an exotic case.
+- **Record it** in `.qfai/evidence/sdd-<spec-id>.md` as a line of the form:
+
+  ```
+  - Executability: CON-DB-NNNN — applied to scratch DB; every declared write path driven twice; <command> / <result>
+  ```
+
+  `QFAI-CONTRACT-031` (`warning`) reports a `db/` contract with no such line. It
+  is a **presence check**: it does not execute SQL and makes no claim about
+  correctness. Neither a syntax-level parse nor a structural comparison would
+  have caught the observed defects, so a cheap record of "this was actually
+  driven" is what the omission needs.
+
+The cost of skipping this is not paid in Phase 0. It is paid inside a TDD
+micro-cycle, by an implementer who is forbidden from fixing the contract and has
+to stop the batch.
+
+## Obligation Reconciliation (MUST) — Phase 2c
+
+Cross-contract reconciliation above compares contracts to each other. This
+compares contracts to the **obligations written after them**.
+
+Phase 0 authors contracts. `BR` / `AC` / `TC` are written in Phase 2. The
+contract is therefore frozen before the obligations that must ride on it exist,
+and "Contracts-first" is only defensible if something later checks that the
+obligations are realizable. That check is this one, and it runs in **Phase 2c**,
+after Phase 2b and before Phase 3 Plan finalize — early enough that a contract
+change still flows into the plan and the delta.
+
+For every `BR` / `AC` produced in Phase 2:
+
+- **Name the contract that realizes it.** An obligation whose realizing
+  contract cannot be named is not reconciled; it is unowned.
+- **Resolve every persisted attribute the obligation names to a concrete column,
+  field or enum member in that contract.** "Attribute" means anything the
+  obligation requires the system to store, distinguish or report on — an axis of
+  attribution, a status the obligation branches on, a value it aggregates by.
+- **Reachability counts, not adjacency.** When the attribute lives in a
+  different relation, state the join that reaches it. If no join reaches it, the
+  obligation is unrealizable however valid both contracts are.
+- **Vocabulary mixing is the usual cause, and it does not look like a typo.**
+  An obligation that mixes the vocabulary of two contracts designed for
+  different purposes — an operational ledger and an evidentiary one — reads
+  perfectly and cannot be satisfied by either. Two internally valid, mutually
+  consistent contracts is exactly the state in which this defect survives.
+- Record the outcome per obligation, not per spec: which contract, which
+  columns/fields, and the join when one is needed.
+
+**A failure here is resolved in the contract or in the obligation, in this
+phase.** Both are owned by `/qfai-sdd`, so amending either is not drift — but
+carrying the mismatch downstream is, because the implementer who eventually
+meets it cannot fix either side.
+
+Execution-based checking does not substitute for this. An obligation whose
+attributes are missing produces a declared path that **succeeds** when driven:
+the query returns rows, the endpoint answers, the suite is green. Failure
+surfaces defects; this class is concealed by success, and only a reading of the
+obligation against the contract finds it.
+
 ## Checklist
 
 - Contract IDs exist and are unique.
 - Specs reference only existing contract IDs.
 - Design contracts are sufficient for prototyping, ATDD, and implementation without discussion-pack fallback.
+- Every `db/` contract has been applied to a scratch database and every declared write path driven
+  **at least twice**, with the command and result recorded in `.qfai/evidence/sdd-<spec-id>.md`
+  (`QFAI-CONTRACT-031`).
+- Every API-mandated terminal state / status value / error code is representable in the paired DB contract.
+- Every `BR` / `AC` names a realizing contract, and every persisted attribute it names resolves to a
+  column, field or enum member there — reachable directly or by a stated join (Phase 2c).
+- `QFAI-CONTRACT-040` findings are resolved or explicitly triaged, not carried forward.

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/rcp_footer.md

@@ -24,15 +24,21 @@
   - `architecture-reviewer`
   - `product-surface-reviewer`
   - `qa-gatekeeper`
-- 各レビューは `PASS` / `FAIL` を返す
-- `FAIL` が出たら、失敗 reviewer と修正影響を受ける reviewer のみ再実行する
+- 各レビューは `PASS` / `REVISE` を返す（in-flight のレビュアー応答の語彙。SSOT は
+  `.qfai/assistant/constitution/shared-skill-delegation-baseline.md` の `## Reviewer response template`）
+- `REVISE` は review pack の `summary.json` を書き出す際に `status: "FAIL"` へ対応付けられる（同ファイルの
+  `### Verdict vocabulary` を参照）。第3の判定値を作らないこと
+- `REVISE` が出たら、失敗 reviewer と修正影響を受ける reviewer のみ再実行する
 
 ---
 
 ## Validate Hard Gate（必須）
 
-- 各 review cycle で `qfai validate --profile sdd --fail-on error --format github` を実行していること
-- `.qfai/report/validate.log` が存在し、最新の成果物に対応していること
+- 各 review cycle で `npx qfai validate --profile sdd --fail-on error --format github` を実行していること
+- `<paths.outDir>/validate.log`（既定 `.qfai/report/validate.log`）が存在し、最新の成果物に対応していること
+  - このファイルは `npx qfai validate` が実行のたびに自動で書き出す。`| tee` などのシェルリダイレクトは不要（PowerShell では動作しないため使用しない）
+  - `<paths.outDir>` は `qfai.config.yaml` の `paths.outDir`。既定以外に変更したプロジェクトでは `<paths.outDir>/validate.log` と `<paths.outDir>/run-*/` を見ること
+  - 最新性は `validate.log` の `run_log:` 行が最新の `run-*/` を指しているかで確認する
 
 ---
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/review-cycle-playbook.md

@@ -14,7 +14,7 @@ Use this file when you need the detailed review-cycle mechanics for `/qfai-sdd`.
 2. Build one review pack for the current cycle only.
 3. Apply the footer SSOT without rewriting it locally.
 4. Collect verdicts.
-5. If any blocking reviewer returns `FAIL`, fix only the affected scope and rerun the failed reviewer plus any reviewer whose scope changed.
+5. If any blocking reviewer returns `REVISE`, fix only the affected scope and rerun that reviewer plus any reviewer whose scope changed. `REVISE` is the in-flight verdict (`.qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-response-template`); it becomes `status: "FAIL"` only when the pack's `summary.json` is written.
 6. Mark the cycle fixed only when all routed blocking reviewers return `PASS`.
 
 ## Required Outputs

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/sdd-execution-playbook.md

@@ -9,8 +9,10 @@ Use this file for the detailed sequencing rules behind `/qfai-sdd`.
 3. **Phase 0 - Contracts-first**
 4. **Phase 1 - Outline**
 5. **Phase 2 - Slice** (per spec)
-6. **Phase 3 - Plan finalize** (per spec)
-7. **Phase 4 - Delta update** (per spec)
+6. **Phase 2b - Seed `tdd/test-list.md`** (per spec)
+7. **Phase 2c - Obligation reconciliation** (per spec)
+8. **Phase 3 - Plan finalize** (per spec)
+9. **Phase 4 - Delta update** (per spec)
 
 ## Stage 0: Preflight
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/sdd-phase-checklists.md

@@ -40,6 +40,24 @@ Use these checklists as the detailed operational guide for `/qfai-sdd`.
 - Ensure `01_Spec.md` remains the execution Primary SSOT.
 - Stop if slice gate fails.
 
+## Phase 2b: Seed `tdd/test-list.md`
+
+- Copy `templates/specs/spec/tdd/test-list.md` when `<spec-id>/tdd/test-list.md` does not exist.
+- Add one row per coverage-target TC from `06_Test-Cases.md`, `Status = todo`.
+- Delta only: an unchanged TC's row keeps its `TDD-ID`, `Status`, `Test file`, `Selector`, `DR-ID` and `Evidence`.
+- Reconcile changed and removed TCs: return a changed TC's row to `todo` under the upstream-reset rule (driving `CR-*` / `DR-*` in `DR-ID`), and retire the row of a TC deleted upstream or no longer a coverage target. Never leave a stale `done` row nor a selectable row for a TC that no longer exists.
+- Keep the ledger table the first markdown table in the file.
+- An empty table is a valid outcome when the spec declares no coverage-target TC.
+
+## Phase 2c: Obligation reconciliation
+
+- For every `BR` / `AC` this run produced, name the contract under `.qfai/contracts/**` that realizes it.
+- Resolve every persisted attribute the obligation names to a column, field or enum member in that contract.
+- When the attribute lives in another relation, state the join that reaches it. No join reaching it means the obligation is unrealizable, however valid both contracts are.
+- Fix the contract or the obligation in this phase — both are owned by `/qfai-sdd`, and a mismatch carried downstream reaches an implementer who can fix neither.
+- Record the outcome per obligation, not per spec.
+- Full rule: `contract-artifact-rules.md#obligation-reconciliation-must--phase-2c`.
+
 ## Phase 3: Plan finalize
 
 - Create or update `<spec-id>/10_Plan.md`.

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/sdd-quality-gate.md

@@ -22,17 +22,58 @@ Use this file for the full quality gate checklist behind `/qfai-sdd`.
 - UPDATE rows carry a Sub-op of APPEND / MODIFY / REMOVE.
 - CREATE / DELETE / SPLIT / MERGE / SUPERSEDE and UPDATE:REMOVE rows record an `Approved By` value.
 
+## Contract Checks
+
+Phase 0 is a mandatory output of this skill, so its own artifacts belong on this page.
+
+- Every `api/`, `db/` and `ui/` contract declares a unique, correctly-prefixed `QFAI-CONTRACT-ID`.
+- Every `db/` contract has been **applied to a scratch database**, and every declared write path
+  **driven at least twice** — the second traversal is what exercises head-advance and
+  expected-version guards. Applying cleanly is the floor, not the gate: a contract that applies
+  without error still fails at runtime, because the failure is a resolution error inside a PL/pgSQL
+  body rather than a syntax error.
+- The command and result are recorded in `.qfai/evidence/sdd-<spec-id>.md`; `QFAI-CONTRACT-031`
+  (`warning`) reports a `db/` contract with no such record.
+- `QFAI-DB-001` dangerous-SQL warnings are resolved or explicitly triaged.
+- Full rule: `references/contract-artifact-rules.md#executability-must`.
+
+## Cross-contract Checks
+
+- Every terminal state, status enum value, and error code an API contract mandates has a
+  representable counterpart in the paired DB contract (`references/contract-artifact-rules.md#cross-contract-reconciliation-must`).
+- Failure / rejection paths in particular: the DB has an honest terminal value for each API-mandated
+  failure outcome, rather than a success state whose preconditions cannot hold on failure.
+- The reconciled API↔DB pairing is recorded in `_policies/05_Contracts.md`.
+- `QFAI-CONTRACT-040` warnings are resolved or explicitly triaged before sign-off.
+
 ## Traceability Checks
 
-- `US -> AC -> BR -> EX -> TC` edges exist.
+- `US -> AC -> BR -> EX -> TC` edges exist. Check this against `.qfai/report/run-*/traceability.json`,
+  which is built from the parsed spec pack on every run, clean or failing. Table-layout specs
+  (`05_Examples.md` + `06_Test-Cases.md`) carry `BR_TO_AC`, `EX_TO_BR`, `TC_TO_AC` and `TC_TO_EX`
+  edges; the older `Examples.feature` layouts carry `AC_TO_US`, `BR_TO_AC` and either
+  `EX_TO_BR` / `TC_TO_EX` or `SC_TO_AC` / `CASE_TO_SC`. `EX_TO_AC` also appears: in v1417 an
+  `EX` may hang off an `AC` directly rather than off a `BR`, and the graph builder emits both
+  edge kinds — it is a normal edge type, not an unknown one. An empty `edges` array on a spec
+  pack that has specs is a finding, not a tool limitation.
 - `05_Examples.md` includes `EX-ID` and `BR-Ref`.
-- `06_Test-Cases.md` includes `TC-ID`, `EX-Ref`, `AC-Refs`, and `Type`.
+- `06_Test-Cases.md` includes `TC-ID`, `Level`, `EX-Ref`, `AC-Refs`, and `Type`. `Level` holds exactly one code from `.qfai/assistant/catalog/test-layers.md#layer-definitions`, which defines all five (`L1`-`L5`); the template's list is a reading aid pointing back at it.
 - Error or boundary coverage is present, not only normal-path coverage.
+- **The chain does not terminate at `TC`.** Every `BR` / `AC` names the contract that realizes it,
+  and every persisted attribute it names resolves to a column, field or enum member in that
+  contract — directly or by a stated join. Phase 0 authors contracts before these obligations
+  exist, so an obligation the contract cannot express passes every other check on this page: the
+  SQL is valid, the `US -> AC -> BR -> EX -> TC` edges are complete, `npx qfai validate` is clean.
+  Driving the declared path succeeds, so execution-based checking does not find it either. See
+  `references/contract-artifact-rules.md#obligation-reconciliation-must--phase-2c`.
 
 ## Validation Checks
 
-- `qfai validate --profile sdd --fail-on error --format github | tee .qfai/report/validate.log`
+- `npx qfai validate --profile sdd --fail-on error --format github`
 - `error=0`
+- `<paths.outDir>/validate.log` (`.qfai/report/validate.log` by default) — written automatically by the
+  command above (no `tee` redirect); its `run_log:` line points at the `run-*/` directory of that run.
+  A project that changed `paths.outDir` in `qfai.config.yaml` finds both under its configured directory
 - `.qfai/report/specs-coverage/spec-*.md` reviewed
 - Density-smell warnings triaged
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/sdd-triage.md

@@ -18,8 +18,16 @@ Concretely, before persisting any Triage row:
    and `04_Business-Rules.md`. The classifier output is a _proposal_; the
    final decision must be informed by reading the candidate spec body.
 2. Pick the spec whose scope most closely absorbs the new requirement.
-3. Append a new BR/AC/EX/TC there. If the spec is over the size threshold,
-   propose **SPLIT**, never CREATE-as-shortcut.
+3. Append a new BR/AC/EX/TC there. Never CREATE-as-shortcut. A spec over the
+   size threshold is a **signal, not an operation**: record the breach in the
+   row's `Rationale` — for a MERGE row, every breaching target — and start a
+   capability-ownership review. Propose **SPLIT** only if that review shows the
+   spec genuinely owns more than one `CAP-NNNN`; if it owns exactly one, the
+   operation already selected is unchanged (MERGE stays MERGE, APPEND stays
+   APPEND) and the reasoned non-split is recorded. A count-driven SPLIT of a
+   single-capability spec is illegal — `validateSpecSplitByCapability` raises
+   `QFAI-SPLIT-102` / `QFAI-SPLIT-104` at `error`, so it has no legal end
+   state. See `_policies/11_Slice-Policy.md` step 4.
 4. Only when no active spec's scope can absorb the requirement, AND the
    underlying capability is itself new, propose **CREATE**. Add the new
    `CAP-NNNN` to `_policies/03_Capabilities.md` _first_, then cite it in
@@ -37,14 +45,53 @@ shares the most subject tokens. CREATE is emitted only when there is
 | Operation | Sub-op | When to choose                                                                                                                                                                                                                                                                                                                                          | Approval |
 | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
 | CREATE    | -      | New subject; no active spec owns the capability                                                                                                                                                                                                                                                                                                         | Required |
-| UPDATE    | APPEND | Add new US/AC/BR/EX/TC to an active spec (no semantic change)                                                                                                                                                                                                                                                                                           | -        |
-| UPDATE    | MODIFY | Change the meaning of an existing US/AC/BR/EX/TC                                                                                                                                                                                                                                                                                                        | -        |
+| UPDATE    | APPEND | Add new US/AC/BR/EX/TC to an active spec (no semantic change). Item-level only. With UPDATE:MODIFY this is also how an item is decomposed into N siblings — see Operation scope below                                                                                                                                                                   | -        |
+| UPDATE    | MODIFY | Change the meaning of an existing US/AC/BR/EX/TC. Item-level only                                                                                                                                                                                                                                                                                       | -        |
 | UPDATE    | REMOVE | Delete an existing US/AC/BR/EX/TC (cuts downstream refs)                                                                                                                                                                                                                                                                                                | Required |
-| DELETE    | -      | Subject was removed from the product; the spec itself goes away                                                                                                                                                                                                                                                                                         | Required |
-| SPLIT     | -      | One spec carries >1 capability; split into N specs                                                                                                                                                                                                                                                                                                      | Required |
-| MERGE     | -      | Multiple specs converge on one capability; collapse them                                                                                                                                                                                                                                                                                                | Required |
+| DELETE    | -      | Subject was removed from the product; the spec itself goes away. **Spec-scoped only** — deleting one item is UPDATE:REMOVE (QFAI-TRIAGE-007)                                                                                                                                                                                                            | Required |
+| SPLIT     | -      | One spec carries >1 capability; split into N specs. **Spec-scoped only** — never use it to split an item (QFAI-TRIAGE-007)                                                                                                                                                                                                                              | Required |
+| MERGE     | -      | Multiple specs converge on one capability; collapse them. **Spec-scoped only** (QFAI-TRIAGE-007)                                                                                                                                                                                                                                                        | Required |
 | SUPERSEDE | -      | Responsibilities move to a new spec; flip status, keep history. Also covers single-spec **RENAME** (subject change at the same ID is normally UPDATE:MODIFY; if the spec ID itself must change while scope stays the same — i.e. **RENUMBER** — emit SUPERSEDE: create the new ID, mark the old as superseded). MERGE handles multi-spec consolidation. | Required |
 
+### Operation scope (spec-level vs item-level)
+
+`SPLIT`, `MERGE`, `SUPERSEDE` and `DELETE` operate on a **whole spec
+directory**. `UPDATE:APPEND / MODIFY / REMOVE` operate on **items inside one
+spec**. There is no operation for decomposing one `US/AC/BR/EX/TC` into N
+siblings within the same spec — that is encoded as `UPDATE:MODIFY` (narrow the
+original) plus one `UPDATE:APPEND` row per new sibling.
+
+Do not reach for `SPLIT` to mean "split this business rule": `SPLIT` asserts
+that the spec itself must become N specs, which
+`validateSpecSplitByCapability` then enforces as one `CAP-NNNN` per spec.
+Likewise do not reach for `DELETE` to remove one item — that is
+`UPDATE:REMOVE`.
+
+`QFAI-TRIAGE-007` (error) rejects a `SPLIT` / `MERGE` / `SUPERSEDE` / `DELETE`
+row whose `Subject` names an item ID **as the operation's object**. The object
+is decided structurally, by **brackets, not by word order**: an item ID inside
+`(...)` / `（...）` / `[...]` / `【...】` is a citation, and any item ID outside
+brackets is what the operation acts on.
+
+- `delete BR-0006-0004 from spec-0006` -> bare item: rejected. Co-occurring
+  with a spec name is not an exemption.
+- `in spec-0006, delete BR-0006-0004` -> bare item: rejected. Naming the spec
+  first does not help — there it is only the item's location, which is why word
+  order cannot decide the object.
+- `split spec-0006 (motivated by BR-0006-0004)` -> item bracketed: accepted.
+- `separate CAP-0003 (driven by BR-0006-0004)` -> item bracketed: accepted.
+
+So a genuinely spec-level row names only its `spec-NNNN` / `CAP-NNNN` target
+outside brackets and puts the motivating item inside them. Item IDs are matched
+with the shared digit semantics of `specPackIds.ts`, so `BR-1` and `TC-12345`
+are caught alongside the canonical 4-digit form.
+
+Because `UPDATE:MODIFY` and `UPDATE:APPEND` are approval-free by operation
+type, an item decomposition carries no approval-required row. Record the
+conservation statement — which obligations existed before, which exist after,
+and that none were added or dropped — in the `Rationale` column of the
+`UPDATE:MODIFY` row so a reviewer can check it.
+
 ## Inputs
 
 1. Latest discussion-pack `06_REQ.md` / `07_NFR.md` / `99_delta.md`.
@@ -122,6 +169,12 @@ ops), `Rationale` (recommended for every row).
   (APPEND / MODIFY / REMOVE).
 - `QFAI-TRIAGE-005` (error): approval-required Operation has no
   `Approved By` value.
+- `QFAI-TRIAGE-007` (error): `SPLIT` / `MERGE` / `SUPERSEDE` / `DELETE` row
+  whose `Subject` names a `US/AC/BR/EX/TC` ID as the operation's object. All
+  four are spec-scoped: item decomposition is `UPDATE:MODIFY` +
+  `UPDATE:APPEND`, and deleting one item is `UPDATE:REMOVE`.
+  `QFAI-TRIAGE-003` is a membership check on the Operation label and provably
+  cannot catch this.
 - `QFAI-TRIAGE-006` (error): CREATE row without a `CAP-NNNN` reference
   in the Rationale column, or referencing a CAP that is not registered
   in `_policies/03_Capabilities.md`. This is the structural gate that

package/assets/init/.qfai/assistant/skills/qfai-sdd/references/spec-traceability-rules.md

@@ -4,7 +4,7 @@ Use this file when working on traceability-heavy parts of `/qfai-sdd`.
 
 ## Required Layered Layout
 
-`qfai validate` treats specs as a layered package:
+`npx qfai validate` treats specs as a layered package:
 
 - Shared policies: `.qfai/specs/_policies/**`
 - Capability specs: `.qfai/specs/spec-*/**`
@@ -72,21 +72,173 @@ ID reference direction (the value of `Refs:` columns) must be lower-to-upper onl
   - `US-0001` -> Parent: `CAP-0001`
   - `AC-0001` -> defined in `03_Acceptance-Criteria.md`
   - `BR-0001` -> `AC-Refs` in `04_Business-Rules.md`
+  - `BR-0001` -> `Contract-Refs` in `04_Business-Rules.md` (comma-separated
+    `CON-*` IDs; `-` when the rule binds no contract). Contract IDs recorded
+    only in `Notes` are untraced.
   - `EX-0001` -> `BR-Ref` in `05_Examples.md`
   - `TC-0001` -> `EX-Ref` and `AC-Refs` in `06_Test-Cases.md`
-- `_policies/**` must not contain lower-layer IDs (`US/AC/BR/EX/TC`) or per-spec references.
+- `_policies/**` must not **define or own** lower-layer items. Concretely: no
+  traceability edge in `_policies/**` may name a lower-layer ID — no `Parent:`,
+  `Refs:`, `AC-Refs`, `BR-Ref` or `EX-Ref` value, and no heading that declares a
+  `US/AC/BR/EX/TC` item.
+- **How this is enforced today is broader than that intent.** `QFAI-LAYER-100`
+  and `TRACE_SHARED_SCOPE_VIOLATION` are a token scan: they match any
+  `US/AC/BR/EX/TC-NNNN` anywhere in a `_policies/**` file, not only in an
+  ownership or definition position. Outside the Triage carve-out below, a plain
+  prose citation is therefore reported too. Treat the ownership/definition rule
+  as the _intent_ and the token scan as the _current mechanism_; when you need
+  to name a lower-layer item in `_policies/**`, put it in the Triage table rows,
+  which is the one place the scan skips.
+- _Citing_ a lower-layer ID or a `spec-NNNN` inside the **Triage table rows** of
+  `_policies/10_delta.md` is explicitly allowed. `sdd-triage.md` requires
+  cross-spec and policy-only Triage rows to be persisted there, and
+  `QFAI-TRIAGE-002` makes `Existing Spec` (a `spec-NNNN` value) a required
+  column — so the `Existing Spec`, `Approved By` and `Rationale` cells must be
+  able to name what actually changed, verbatim. `QFAI-LAYER-100` and
+  `TRACE_SHARED_SCOPE_VIOLATION` skip those rows for this reason.
+- The carve-out is exactly that narrow, so it cannot be used as an escape
+  hatch:
+  - **file** — `_policies/10_delta.md` only. A `## Triage` heading anywhere
+    else under `_policies/**` (`11_Slice-Policy.md`, `01_Objective.md`, ...)
+    gets no exemption.
+  - **heading** — the canonical `## Triage` H2 only, matching what
+    `QFAI-TRIAGE-001..007` validate. `# Triage`, `### Triage` and
+    `## Triage notes` are not exempt.
+  - **line shape** — markdown table rows only. A heading that declares an item
+    (`### AC-0001-0001`) or a traceability edge (`- Parent: US-0001-0001`)
+    inside the Triage section is still a violation, because it defines or owns
+    rather than cites.
+  - **table identity** — the mandated Triage table only. A second table under
+    `## Triage` is exempt only when its header carries the full canonical
+    column set (`Source`, `Subject`, `Existing Spec`, `Operation`, `Sub-op`,
+    `Approved By`, `Rationale`); order may differ, since the Triage validators
+    resolve columns by name. A table reusing only one or two of those names
+    earns no exemption.
+  - **column** — within an exempt table, only cells under a canonical column
+    are skipped. An author-added column (`Parent`, `Refs`, ...) keeps its cells
+    visible to the scan.
+- Discussion-layer IDs (`DUS-001`, `DAC-001-01`, `DTC-1`, `DSC-001`) are a different
+  namespace and are explicitly allowed in `_policies/**` and in `Source` fields. They are
+  how provenance back to the discussion pack stays machine-checkable; do not rewrite them
+  into prose to satisfy the rule above.
+- A `Source` value is always the pair `<pack-id>#<discussion-id>`, e.g.
+  `discussion-20260415101112123#DUS-001`. The pack half is not optional: pack IDs are the
+  only thing that makes a discussion ID unique, because every pack restarts its numbering at
+  `DUS-001` / `DAC-001-01`. A spec that two packs have updated therefore carries two `Source`
+  values that differ only in the pack half.
+- `Source` is recorded once per item, in the required artifact: the `- Source:` line of each
+  `## US-NNNN` block in `02_User-stories.md`, and the `# Source:` comment inside each AC's
+  Gherkin block in `03_Acceptance-Criteria.md`. The optional `AC Catalog` table carries no
+  `Source` column, so there is no second copy to drift.
+
+### Item granularity
+
+Depth expectations answer how many layers; item granularity answers how big one
+item may be. It is defined in
+`.qfai/assistant/constitution/requirements-decomposition.md#item-granularity-acbrextc`
+and signalled by `QFAI-DENSITY-005`.
 
 ## TDD Execution Ledger
 
 Each `.qfai/specs/<spec-id>/tdd/test-list.md` is the execution ledger for the TDD micro-cycle.
 
 - Required columns: TDD-ID, TC-Refs, Layer, Test file, Selector, Status, DR-ID, Evidence
-- Coverage is measured as unit/component TC references from `06_Test-Cases.md` appearing in TC-Refs.
+- Optional columns: `US-Refs`, `CON-API-Refs`, `Blocked-By`. `Blocked-By` names what a
+  `blocked` row is waiting on and is required on those rows.
+- Legal `Status` values: `todo`, `blocked`, `red`, `green`, `refactor`, `review-fix`,
+  `done`, `exception`. `blocked` is completion-prohibiting and is never selected by
+  Phase Red.
+- **Ownership split.** `/qfai-sdd` owns the rows — which obligations exist and what each
+  covers. `/qfai-implement` owns the `Status`, `DR-ID` and `Evidence` cells and nothing else.
+  This is the one carve-out in `constitution/drift-protocol.md#allowed-exceptions-minimal-whitelist`; adding,
+  removing or re-scoping a row is an upstream change and takes the Change Request path.
+- `Evidence` is a **pointer**: the one-word RED/GREEN outcome plus an anchor into
+  `.qfai/evidence/implement-<spec-id>.md`. A GFM cell is one physical line and ends at
+  every unescaped `|`, so it cannot hold command output. Encoding rules and the cell
+  contract: `qfai-implement/references/execution-ledger.md#evidence-cell-contract`.
+- Optional columns detail: `US-Refs`, `CON-API-Refs` — the E2E and API obligations a
+  row implements. Required when the row carries one, since `TC-*` annotations
+  are forbidden in `tests/e2e/**` and `tests/api/**`.
+- TC coverage reads **`TC-*` tokens only**. `US-*` and `CON-API-*` IDs are
+  explicitly inert to it — recording one does not raise or lower TC coverage.
+- Legal `Layer` values: `Unit`, `Component`, `Integration`, `API`, `E2E`.
+  Legal obligation kinds per layer: `TC-*` on Unit / Component / Integration,
+  `US-*` on E2E, `CON-API-*` on API.
+- `Selector` may hold one entry, a comma-separated list, or a glob pattern. It is not limited to a single test function.
+- `TC-Refs` is many-to-many with `TDD-ID`: one `TC-*` may be decomposed across several TDD rows, and each of those rows carries that `TC-*`.
+- A matrix-shaped `TC-*` (many rejection reasons, a status-code matrix, several independent state transitions) MUST be split across multiple TDD rows before RED begins — one falsifying oracle per row, one row per independently observable boundary. Do not accumulate unrelated boundaries behind a single selector; doing so invalidates the RED observation, because only the first failing assert is ever observed.
+- Coverage is measured as unit/component TC references from `06_Test-Cases.md`
+  appearing in TC-Refs. That measures which TCs need a `tdd/test-list.md` row;
+  it says nothing about where the test file lives. Every `TC-*` — including
+  unit/component ones — is still discharged in `tests/integration/**` for
+  `QFAI-ATDD-112` until the scanner supports the per-level routing described as
+  a target state in `catalog/test-layers.md`.
 - If `06_Test-Cases.md` has no test-case classification column, every TC is treated as a coverage target.
-- `Status=exception` requires a non-empty DR-ID.
-- `Status` in `green`, `refactor`, or `done` requires an existing Test file resolved from project root.
+- `Status=exception` requires a non-empty DR-ID. An `exception` row is not a
+  dead end: a Drift Protocol sweep may reset it to `todo` like any other status
+  when the rerun changed the obligation it was raised against.
+- `Status` in `green`, `refactor`, or `done` requires an existing Test file
+  resolved from project root. The upstream reset does not relax this: a swept
+  row returns to `todo`, where no file is required, and writes its test in the
+  following `red` phase.
+- **The converse also holds.** A `todo` row whose Test file exists _and_ whose
+  `Selector` resolves inside it is a stale ledger row, not a not-started one
+  (`TDDLIST_STALE_STATUS`, `warning`). Stated in one direction only, the rule
+  could catch the ledger over-reporting and never under-reporting — and
+  under-reporting is what actually happens, because work lands from parallel
+  worktrees and the ledger is reconciled by hand afterwards. A stale `todo` and
+  a genuinely not-started row are indistinguishable to every downstream
+  consumer, including the completion gate that reads the ledger. A project that
+  declares test paths and selectors up front waives `TDDLIST-005`.
+- `Selector` is read, not merely required: on a row claiming completion it must
+  resolve inside the named Test file (`TDDLIST_SELECTOR_UNRESOLVED`, `warning`).
+  Resolution is a containment check over the selector text and its last
+  identifier token, not a runner-specific parse; waive `TDDLIST-006` for a
+  selector form it cannot resolve.
+- `DR-ID` carries Decision Record (`DR-*`) **and** Change Request (`CR-*`)
+  references, so it carries the approval that authorised an upstream reset, not
+  only `Status = exception`. A row reset by a Drift Protocol sweep records the
+  approved `CR-*` / `DR-*` ID there and **retains it through `red`, `green`,
+  `refactor` and `done`** — the ledger is the audit trail for why a completed
+  row was reopened. Change Requests live at
+  `.qfai/decisions/CR-YYYYMMDD-NNNN-<slug>.md` (`CR-\d{8}-\d{4}`).
+- `Layer` must be consistent with `Test file`: an `Integration` row may not
+  point into `tests/e2e/**` or `tests/api/**`, and vice versa.
+- More than one `TDD-*` row MAY reference the same `TC-*` — a TC split across
+  several test modules is legitimate. `TDD-ID` uniqueness is the only
+  identity constraint.
 - `TDD-ID` must match `TDD-NNNN` and be unique within the spec.
 - Missing `tdd/test-list.md` is a warning; missing DR-ID/Evidence columns is an error.
+- The `Evidence` **cell** is checked too, not only the header: on a row at
+  `green` / `refactor` / `review-fix` / `done`, an empty-or-dash cell is
+  `TDDLIST_EVIDENCE_EMPTY` and a verdict with no command is
+  `TDDLIST_EVIDENCE_STATUS_ONLY`, both at `error`.
+
+## Traceability Ledger (`16_Traceability-ledger.md`)
+
+Optional per-spec artifact linking `BR-*` / `AC-*` to the implementation file that realizes them.
+Template: `templates/specs/spec/16_Traceability-ledger.md`.
+
+- It is **optional**. Without it `npx qfai validate` emits `QFAI-TRACE-002` (`warning`) and skips the
+  implementation-integrity check; the spec is still valid.
+- With it, `QFAI-TRACE-001` (`error`) fires when a spec's `03_Acceptance-Criteria.md` or
+  `04_Business-Rules.md` changed on the branch but a linked implementation file did not.
+- Schema for the **layered** layout — the first Markdown table is the one read; header needs ≥3
+  columns, one named `Implementation File`:
+
+  | BR/AC   | Implementation File | Test File |
+  | ------- | ------------------- | --------- |
+  | AC-0001 | src/…               | tests/…   |
+
+  First cell must be a `BR-NNNN` / `AC-NNNN` ID; second cell one repo-root-relative path (no globs,
+  no `./`). One row per BR/AC ↔ file pair. Extra trailing columns are ignored.
+
+- The legacy **spec-pack** layout uses the same filename with a different schema
+  (`trace_id, obj_id, init_id, cap_id, flow_id, us_id, ac_id, ex_ids, tc_ids`, checked by
+  `QFAI-LEDGER-001`). That check runs only on spec-pack layouts — the two schemas never apply to the
+  same file. Do not merge them.
+- Authored and refreshed by `/qfai-sdd` in the same change as the BR/AC it links. It is upstream
+  SSOT; downstream skills must not edit it.
 
 ## Depth Expectations