qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/change-request.md

@@ -0,0 +1,125 @@
+# Change Request
+
+<!--
+Canonical path: `.qfai/decisions/CR-YYYYMMDD-NNNN-<slug>.md`
+ID pattern:     `CR-\d{8}-\d{4}`
+A Change Request is the mandatory precondition for any upstream SSOT edit
+(`constitution/drift-protocol.md`). `qfai-implement` blocks spec completion
+while an unresolved CR exists, so `Status` must be a real, checkable field.
+-->
+
+- ID: `CR-YYYYMMDD-NNNN`
+- Title: `<one-line summary>`
+- Raised by: `<skill or agent>`
+- Raised at: `YYYY-MM-DDThh:mm:ssZ`
+- Class: `intent` <!-- intent | defect; see constitution/drift-protocol.md#drift-classes -->
+- Status: `open` <!-- open | approved | rejected | superseded -->
+- Approved by: `-` <!-- required whenever Status leaves `open` (approved / rejected / superseded) -->
+- Approved at: `-` <!-- YYYY-MM-DDThh:mm:ssZ -->
+- Approved option: `-` <!-- the option number below that was chosen; stays `-` when Class is defect -->
+- Applied at: `-` <!-- YYYY-MM-DDThh:mm:ssZ; set only after the owner-skill rerun below completed and upstream artifacts are updated -->
+- Superseded by: `-` <!-- CR-ID, required when Status is superseded -->
+
+<!--
+`Status: approved` records the operator's decision; `Applied at` records that
+the approved actions were carried out. `qfai-implement` treats an approved CR
+as unresolved until `Applied at` and `Resolution` are both filled, because
+`constitution/drift-protocol.md` resumes downstream work only after the
+upstream artifacts have been updated.
+-->
+
+## Context
+
+<!--
+Class `intent`: the upstream SSOT statement and the downstream fact that
+contradicts it. Cite both by path and ID.
+Class `defect`: what the artifact declares, and how it breaks that declaration
+on its own terms. A defect conflicts with nothing external — say what it
+contradicts in itself.
+-->
+
+## Reproduction
+
+<!--
+REQUIRED when Class is `defect`; delete this section when Class is `intent`.
+The command and its verbatim output, or the two artifact excerpts that
+contradict each other, with paths and line numbers. A defect claim without a
+reproduction is an intent-drift CR that skipped its options
+(`constitution/drift-protocol.md#drift-classes`).
+-->
+
+## Proposed change
+
+<!--
+What must change in the upstream artifact. When Class is `defect` this is the
+single correct fix, and it is what the operator approves.
+-->
+
+## Options (at least 3) and recommendation
+
+<!--
+Class `intent` only — delete this section when Class is `defect`. A change with
+exactly one correct answer has no option set; manufacturing a second and third
+so the table is full asks the operator to ratify a comparison its author knew
+was fabricated.
+-->
+
+| #   | Option     | Cost     | Risk     | Recommended |
+| --- | ---------- | -------- | -------- | ----------- |
+| 1   | `<option>` | `<cost>` | `<risk>` |             |
+| 2   | `<option>` | `<cost>` | `<risk>` | ✅          |
+| 3   | `<option>` | `<cost>` | `<risk>` |             |
+
+## Blocked downstream items
+
+<!--
+The set STOP covers for THIS Change Request
+(`constitution/drift-protocol.md#when-drift-is-detected`, step 1). Enumerate it
+— an item not listed here is not blocked by this CR and continues. The halt is
+not repository-wide, and this section is what makes that checkable.
+
+Also state what this CR does NOT block when it would otherwise be assumed, and
+name any other open CR whose blocked set overlaps: the effective halt is the
+union of the open CRs' blocked sets.
+-->
+
+| Item                       | Kind                               | Why it depends on the artifact |
+| -------------------------- | ---------------------------------- | ------------------------------ |
+| `<spec-NNNN / TDD-NNNN />` | `spec` / `ledger-row` / `contract` | `<TC-Refs names …>`            |
+
+- Not blocked by this CR: `<items a reader would expect to be blocked, and why they are not>`
+- Overlapping open CRs: `<CR-ID, …>` or `none`
+
+## Impact scope
+
+- Specs: `<spec-NNNN, ...>`
+- Plans: `<paths>`
+- Tests: `<paths / TDD-IDs>`
+- Contracts: `<CON-*>`
+- Schema: `<paths>`
+
+## Decision needed from user
+
+<!-- The exact question to put to the user. -->
+
+## Approved actions (owner skill rerun plan)
+
+1. `<owner skill>` rerun scope: `<what>`
+2. Downstream ledger sweep: reset these `tdd/test-list.md` rows, recording this
+   CR's ID in their `DR-ID` column. **Enumerate them here, before approval** —
+   list the `TDD-ID`s (or a verifiable selection rule such as "every row whose
+   `TC-Refs` names TC-0007"), because what the operator approves is this list.
+   A reset of any row not covered by it is not operator-approved, and
+   `Resolution` must match this list.
+   - `<TDD-NNNN>`, `<TDD-NNNN>`, …
+     This is the only sanctioned backward status transition — see
+     `.qfai/assistant/skills/qfai-implement/SKILL.md`, "Approved Change Request
+     reset".
+
+## Resolution
+
+<!--
+Filled in when Status leaves `open`. Record what was actually done: the owner
+skill that was rerun and the upstream artifacts it updated, and the ledger rows
+reset (by TDD-ID). Set `Applied at` in the header once this section is true.
+-->

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/contracts/db-contract.sample.sql

@@ -1,5 +1,11 @@
 -- QFAI-CONTRACT-ID: CON-DB-0001
 -- Purpose: Sample order draft persistence contract
+-- Depends on: -
+--   Apply-order dependencies as a comma-separated list of CON-DB-* ids, or `-`
+--   when there are none. List only what must be applied BEFORE this file.
+--   A reference resolved at run time (a deferred FK, a view a later query
+--   reads) is NOT an apply-order dependency: the apply graph is acyclic by
+--   construction, the runtime graph need not be.
 
 CREATE TABLE order_drafts (
   id TEXT PRIMARY KEY,

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/evidence/sdd-spec.md

@@ -0,0 +1,92 @@
+# Evidence: /qfai-sdd (<spec-id>)
+
+> Canonical layout for `.qfai/evidence/sdd-<spec-id>.md`, a Mandatory Output of
+> `/qfai-sdd`. Keep every `##` heading below, in this order, even when a section
+> is empty — write `- none` rather than deleting the heading. The completion
+> reviewer grades this file's shape against this template.
+
+## Objective
+
+- Spec target: <spec-id>
+- Objective: <what this SDD cycle set out to change for this spec>
+
+## Inputs reviewed
+
+- <path or pack id>
+- <path or pack id>
+
+## Preflight summary path
+
+- `.qfai/report/preflight_summary.md`
+
+## Triage decisions
+
+> One row per incoming REQ/NFR handled for this spec, mirroring the Triage table
+> persisted in `09_delta.md` (per-spec) or `_policies/10_delta.md` (cross-spec).
+> Operation: `CREATE` | `UPDATE` | `DELETE` | `SPLIT` | `MERGE` | `SUPERSEDE`.
+> Sub-op (UPDATE only): `APPEND` | `MODIFY` | `REMOVE`.
+> Approved By is required for CREATE / DELETE / SPLIT / MERGE / SUPERSEDE /
+> UPDATE:REMOVE; use `-` when approval is not required.
+
+| Source   | Subject     | Operation | Sub-op | Approved By | Rationale |
+| -------- | ----------- | --------- | ------ | ----------- | --------- |
+| REQ-XXXX | <one-liner> | UPDATE    | APPEND | -           | <why>     |
+
+## Open questions
+
+- OQ-XXXX: <question> — Disposition: open | resolved | deferred
+- <or> none
+
+## Decisions made
+
+- DEC-XXXX / DELTA-XXXX: <decision> — <rationale>
+- <or> none
+
+## Work performed
+
+- <artifact created or updated, with path>
+- <artifact created or updated, with path>
+
+## Commands executed
+
+```
+npx qfai validate --profile sdd --fail-on error --format github
+```
+
+> No redirect. `npx qfai validate` writes `<paths.outDir>/validate.log` itself on
+> every run, always pointing at that run's `run-*/` directory, so a `| tee` is
+> both unnecessary and not portable to PowerShell. Same command as `SKILL.md`
+> step 8 and `references/sdd-quality-gate.md`.
+
+## Validate evidence paths
+
+- `.qfai/report/validate.log`
+- `.qfai/report/run-<timestamp>/` (run id: <run-id>, status: pass | fail)
+- `.qfai/report/specs-coverage/<spec-id>.md`
+
+## Work Orders Summary
+
+> Fixed 6-column schema from
+> `.qfai/assistant/constitution/shared-skill-delegation-baseline.md#work-orders-summary`.
+> Do not add, remove or rename columns.
+> `Status` accepts exactly `PASS` or `REVISE` — no other value (no `PENDING`,
+> no `N/A`, no `FAIL`). A work order that has not been reviewed yet is `REVISE`.
+
+| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
+| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
+| 1    | <role>           | <task>     | <refs>       | <refs>        | PASS                 |
+
+## Gaps / Open risks
+
+- <residual risk, or the OQ that carries it>
+- <or> none
+
+## Final status
+
+- Final status: PASS | REVISE
+- Rationale: <one line>
+
+> `Final status` accepts exactly `PASS` or `REVISE`, matching the reviewer
+> vocabulary in `shared-skill-delegation-baseline.md#verdict-vocabulary`. A
+> `REVISE` here maps to `status: "FAIL"` when a review pack's `summary.json` is
+> written; they are the same outcome. Do not invent a third verdict.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/01_Objective.md

@@ -0,0 +1,27 @@
+# 01 Objective
+
+The product-level "why" the whole spec pack serves. One objective per project;
+every `CAP-*` in `03_Capabilities.md` traces up to it.
+
+## Objective
+
+- <one sentence: the outcome this product exists to produce>
+
+## Success criteria
+
+| ID     | Criterion              | How it is measured        |
+| ------ | ---------------------- | ------------------------- |
+| OBJ-01 | `<observable outcome>` | `<metric or observation>` |
+
+## Out of scope
+
+- `<what this objective explicitly does not cover>`
+
+## Authoring rules
+
+- Outcome only. No solution, no architecture, no delivery sequencing — those
+  live in `02_Initiative.md` and `10_Plan.md` respectively.
+- Do not name `US` / `AC` / `BR` / `EX` / `TC` IDs here: `_policies/**` must not
+  define or own lower-layer items (`references/spec-traceability-rules.md`).
+- An empty success-criteria table is a finding, not a default. An objective no
+  one can measure cannot adjudicate a capability.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/02_Initiative.md

@@ -0,0 +1,30 @@
+# 02 Initiative
+
+The initiative is the bounded effort undertaken to reach `01_Objective.md`. It
+answers "what are we doing about it", one layer above capabilities.
+
+## Initiative
+
+- <one sentence: the bounded effort, not the product>
+
+## Scope
+
+| In scope | Out of scope               | Why                       |
+| -------- | -------------------------- | ------------------------- |
+| `<area>` | `<adjacent area excluded>` | `<reason for the border>` |
+
+## Assumptions
+
+- `<assumption this initiative rests on, and what falsifies it>`
+
+## Dependencies
+
+- `<external system, team, or decision this initiative waits on>`
+
+## Authoring rules
+
+- The scope table's `Out of scope` column is load-bearing: a border with no
+  stated reason is a border no one can defend when it is challenged.
+- Record a stated assumption here rather than an open question when the work
+  proceeds on it. Genuine questions belong in `09_Open-questions.md`.
+- No lower-layer IDs (`references/spec-traceability-rules.md`).

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/05_Contracts.md

@@ -15,8 +15,8 @@
 | DB-001   | order_drafts | CON-DB-0001 | `.qfai/contracts/db/db-0001-<slug>.sql` | draft persistence |
 -->
 
-| Short ID | Entity | Declared ID | File | Purpose |
-| -------- | ------ | ----------- | ---- | ------- |
+| Short ID | Entity | Declared ID | File | Depends On | Purpose |
+| -------- | ------ | ----------- | ---- | ---------- | ------- |
 
 ### API Contracts
 
@@ -26,8 +26,8 @@
 | API-001  | /api/orders | CON-API-0001 | `.qfai/contracts/api/api-0001-<slug>.yaml` | create draft |
 -->
 
-| Short ID | Router | Declared ID | File | Purpose |
-| -------- | ------ | ----------- | ---- | ------- |
+| Short ID | Router | Declared ID | File | Depends On | Purpose |
+| -------- | ------ | ----------- | ---- | ---------- | ------- |
 
 ### UI Contracts
 
@@ -37,11 +37,21 @@
 | UI-001   | order-create | CON-UI-0001 | `.qfai/contracts/ui/ui-0001-<slug>.yaml` | draft input form |
 -->
 
-| Short ID | Screen | Declared ID | File | Purpose |
-| -------- | ------ | ----------- | ---- | ------- |
+| Short ID | Screen | Declared ID | File | Depends On | Purpose |
+| -------- | ------ | ----------- | ---- | ---------- | ------- |
 
 ## Mapping Rules
 
+- `Depends On` lists the contracts that must be applied **before** this one, as
+  `CON-*` ids, or `-` when none. It mirrors the `-- Depends on:` line in a
+  `.sql` contract and the `x-qfai-depends-on` key in a `.yaml` one.
+- A runtime reference is not an apply-order dependency. `QFAI-CONTRACT-011`
+  forces a multi-table schema into N files, so this column is the only place the
+  resulting composition is stated; without it every consumer reconstructs the
+  apply graph by reading the DDL, and getting it wrong is silent.
+- `QFAI-CONTRACT-014` errors on a declared dependency that names no existing
+  contract.
+
 - If no contracts are needed, keep each table and state `0 items` explicitly.
 - `<slug>` must be kebab-case from entity/router/screen.
 

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/06_Glossary.md

@@ -0,0 +1,19 @@
+# 06 Glossary
+
+Cross-spec vocabulary. One definition per term, defined once, here.
+
+## Terms
+
+| Term     | Definition                           | Not to be confused with     |
+| -------- | ------------------------------------ | --------------------------- |
+| `<Term>` | `<precise definition, one sentence>` | `<the near-miss it is not>` |
+
+## Authoring rules
+
+- A term earns an entry when two specs would otherwise define it differently,
+  or when a reader outside the team would guess wrong.
+- `Not to be confused with` is where the value is. A definition that no one
+  would have misread did not need this file.
+- Use the term consistently in every spec once it is defined here. Introducing a
+  synonym is a glossary change, not a wording choice.
+- Domain vocabulary only — do not restate framework or language terms.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/07_Constraints.md

@@ -0,0 +1,25 @@
+# 07 Constraints
+
+Cross-spec constraints every spec inherits: what the solution may not do,
+regardless of which capability is being built.
+
+## Constraints
+
+| ID     | Constraint                | Kind                                                       | Source                     |
+| ------ | ------------------------- | ---------------------------------------------------------- | -------------------------- |
+| CST-01 | `<what is not permitted>` | `regulatory` / `contractual` / `technical` / `operational` | `<who or what imposes it>` |
+
+## Non-functional floors
+
+| ID     | Dimension                                     | Floor              | How it is verified |
+| ------ | --------------------------------------------- | ------------------ | ------------------ |
+| NFR-01 | `availability` / `latency` / `security` / ... | `<measurable bar>` | `<gate or probe>`  |
+
+## Authoring rules
+
+- A constraint without a `Source` is a preference. Name who imposes it, so a
+  future change knows whom to ask.
+- A floor without a verification method is unenforceable — state the gate or the
+  probe that would catch a breach.
+- Constraints bind every spec. Something true of one capability only belongs in
+  that spec's `01_Spec.md`, not here.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/08_Decisions.md

@@ -1,9 +1,29 @@
 # 08 Decisions
 
+Cross-spec Decision Records. A `DR-*` cited from any spec's `tdd/test-list.md`
+`DR-ID` column resolves against this file as well as the spec's own
+`07_Decisions.md`, so a policy-level decision is cited, never re-declared.
+
+## ID scheme
+
+- **Policy-level**: `DR-NNNN` — declared here, cited from any spec.
+- A spec-only decision uses `DR-NNNN-MMMM` and belongs in that spec's
+  `07_Decisions.md`. Declaring the same ID in both files gives it two owners.
+
 ## Decisions
 
-- 0 items in shared decisions.
+<!-- One `### DR-NNNN` block per decision. Copy the sample below. -->
+
+### DR-NNNN: one-line title
+
+- Status: proposed | accepted | superseded | rejected
+- Context: what forced the decision — the constraint, conflict or anomaly
+- Decision: what was decided, in the imperative
+- Consequences: what this costs and what it forecloses
+- Related: the specs, capabilities or contracts this decision binds, or `-`
 
 ## Empty State
 
-- Add ADR entries only when a cross-spec shared decision is required.
+- 0 items in shared decisions. Add an entry only when a decision genuinely
+  crosses specs; a spec-local one belongs in that spec's `07_Decisions.md`.
+  Delete the sample block above once the first real decision is recorded.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_policies/11_Slice-Policy.md

@@ -67,22 +67,49 @@ approval before any spec edits begin.
 
 ## APPEND vs CREATE algorithm
 
-For each incoming REQ/NFR, apply in order (append-first):
+Steps 1-3, 5 and 6 select the operation; the **first** one that matches wins.
+Step 4 is **not** an alternative branch — it is a recording obligation that
+always runs afterwards, on whichever spec the selected operation targets. Do not
+stop at step 2.
 
 1. Resolve the REQ's capability from `_policies/03_Capabilities.md`.
-2. If a single active spec already owns that capability and its
-   `acCount <= 30 && tcCount <= 50` → **UPDATE:APPEND**.
+2. If a single active spec already owns that capability → **UPDATE:APPEND**.
+   Item counts do not change this answer. Continue to step 4: an oversized
+   owner still needs its `Rationale` entry and its capability-ownership review.
 3. If multiple active specs share the capability → **MERGE**.
-4. If a single active spec owns the capability but exceeds the AC/TC
-   thresholds → **SPLIT**.
+4. **Always evaluate, whatever step 2/3/5 decided.** If any spec the selected
+   operation targets exceeds the AC/TC thresholds (`acCount > 30` or
+   `tcCount > 50`), that is a **size signal, not an operation**. A MERGE row
+   targets several specs, so check them all. Record every breach in the Triage
+   row's `Rationale` and start a **capability-ownership review**:
+   - the spec genuinely owns more than one `CAP-NNNN` → **SPLIT** (approval
+     required, see below);
+   - the spec owns exactly one capability → **the operation selected in steps
+     1-3/5 is unchanged** — MERGE stays MERGE with its approval, APPEND stays
+     APPEND. This step never rewrites the operation; it only records the
+     reasoned non-split, because there is nothing to split into.
+
+   > A count-driven SPLIT of a single-capability spec is **illegal**.
+   > `validateSpecSplitByCapability` hard-enforces one `CAP-NNNN` per spec
+   > with sequential directory names, so it raises `QFAI-SPLIT-102` and
+   > `QFAI-SPLIT-104` at `error` severity. The SPLIT trigger is capability
+   > ownership (line 64 of this file, and `sdd-triage.md`), never a count.
+
+   > An **obligation-conserving re-granulation** — the same obligations
+   > expressed as finer cells, zero added and zero removed — never triggers
+   > SPLIT, whatever it does to `acCount` / `tcCount`. To claim it, state in
+   > the `Rationale` which obligations existed before, which exist after, and
+   > that the sets are equal.
+
 5. If no active spec owns the capability **but at least one active
    spec's title / scope / capability shares any subject token with the
    REQ** → **UPDATE:APPEND on the closest spec** (subject-overlap
-   fallback). Upgrade to **SPLIT** if that spec exceeds the AC/TC
-   thresholds. Subject tokens follow `src/core/sddTriage.ts::tokenize`
-   normalization (STOP_TOKEN drop, length ≥ 2, Unicode `\p{L}\p{N}`),
-   so "the new flag"-style subjects collapse to zero tokens and skip to
-   step 6 — author REQ subjects with meaningful nouns.
+   fallback). A threshold breach on that spec is again a size signal
+   recorded in `Rationale`, not an upgrade to SPLIT. Subject tokens follow
+   `src/core/sddTriage.ts::tokenize` normalization (STOP_TOKEN drop,
+   length ≥ 2, Unicode `\p{L}\p{N}`), so "the new flag"-style subjects
+   collapse to zero tokens and skip to step 6 — author REQ subjects with
+   meaningful nouns.
 6. Only when **no active spec shares any token** with the REQ AND the
    underlying capability is genuinely new → **CREATE**. Add the new
    `CAP-NNNN` to `_policies/03_Capabilities.md` _first_, then cite it

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/02_User-stories.md

@@ -7,6 +7,26 @@
 ## US-0001: <title>
 
 - Parent: CAP-XXXX
+- Source: discussion-YYYYMMDDhhmmssSSS#DUS-XXX <!-- originating pack + story ID, or `-` if none -->
 - Goal: <goal>
 - Non-goals: <non-goal>
 - Notes: <notes>
+
+> `Source` carries provenance back to the discussion pack. Write it as
+> `<pack-id>#<discussion-id>`: the pack directory name under `.qfai/discussion/`, then the
+> discussion-layer ID inside that pack, joined by `#`. Both halves are required. Every pack
+> numbers its stories from `DUS-001`, so a bare `DUS-001` cannot say which pack it came from
+> — and a spec that a second pack later `UPDATE:APPEND`s would carry two different stories
+> under the same `Source` value. The pair resolves to exactly one entry:
+> `.qfai/discussion/<pack-id>/03_Story-Workshop.md`, story `<discussion-id>`.
+>
+> Use the discussion-layer ID verbatim (`DUS-001`, `DAC-001-01`, ...) — never rewrite it into
+> prose, and never renumber it into the spec-local `US-0001` form. Discussion IDs are
+> `D`-prefixed precisely so they cannot be mistaken for spec IDs, and the `_policies`
+> lower-layer-ID rule does not apply to them (it covers spec-local 4-digit IDs only).
+>
+> **Packs written before the `D` prefix** carry unprefixed IDs (`US-001`, `AC-001-01`).
+> Copy those verbatim too: `discussion-YYYYMMDDhhmmssSSS#US-001`. Do NOT invent a `DUS-`
+> form for them — that ID does not exist in the pack, so the `Source` would resolve to
+> nothing. The pack half already disambiguates it from the spec-local `US-0001`, and the
+> pack is immutable: rewriting its IDs to match this template is not a migration.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/03_Acceptance-Criteria.md

@@ -9,14 +9,33 @@
 
 ```gherkin
 # AC-0001
+# Source: discussion-YYYYMMDDhhmmssSSS#DAC-001-01
 Scenario: <scenario title>
   Given <precondition>
   When <action>
   Then <expected outcome>
 ```
 
+> The `# Source:` comment is required on every AC and lives in this block, not in the optional
+> catalog below — a spec that skips the catalog would otherwise have nowhere to record
+> provenance, losing the only machine-checkable trace back to the discussion pack.
+>
+> Write it as `<pack-id>#<discussion-id>`: the pack directory name under `.qfai/discussion/`,
+> then the discussion criterion ID inside it, joined by `#`. Both halves are required —
+> every pack numbers its criteria from `DAC-001-01`, so a bare `DAC-001-01` cannot say which
+> pack it came from, and two packs updating the same spec would collide. Use `-` when the AC
+> has no discussion ancestor. Keep the discussion ID verbatim; do not paraphrase it into prose.
+>
+> Packs written before the `D` prefix carry unprefixed IDs (`AC-001-01`). Copy those verbatim
+> as well — `discussion-YYYYMMDDhhmmssSSS#AC-001-01` — rather than inventing a `DAC-` form
+> the pack does not contain.
+
 ## AC Catalog (optional)
 
 | AC-ID   | Title   | Notes   | Priority |
 | ------- | ------- | ------- | -------- |
 | AC-0001 | <title> | <notes> | P1       |
+
+> This catalog is a human-facing index. It deliberately carries no `Source` column: provenance
+> has exactly one home, the `# Source:` comment in the required Gherkin block above, so the two
+> can never disagree.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/04_Business-Rules.md

@@ -5,8 +5,37 @@
 - Decompose AC into explicit business rules.
 - Every BR must reference one or more AC IDs.
 
+## Granularity (required)
+
+- **One BR expresses one independently falsifiable rule.** If you can delete
+  half of the `Rule` cell and what remains is still a complete, testable rule,
+  it is two BRs.
+- A BR that needs the words "and also", "additionally", or an enumerated list
+  of unrelated conditions to be stated is almost always several BRs.
+- Splitting late is expensive: `05_Examples.md` pins `EX` to `BR` 1:1, so a
+  coarse BR propagates downward by construction and is usually discovered only
+  after it has been projected into one oversized test module.
+- `QFAI-DENSITY-005` (`warning`) flags a `Rule` cell that is a size outlier
+  against the other rules in the same file. It is a signal, not a gate.
+- See `.qfai/assistant/constitution/requirements-decomposition.md#item-granularity-acbrextc`.
+
+## Reference Column Conventions
+
+- `AC-Refs`, `NFR-Refs` and `Contract-Refs` are typed reference columns. Each
+  holds a comma-separated list of IDs and nothing else — no prose, no
+  parentheses, no trailing commentary.
+- `Contract-Refs` holds the contract IDs this rule is bound by. The supported
+  kinds are exactly `CON-API-*`, `CON-DB-*` and `CON-UI-*` — for example
+  `CON-API-0001`, `CON-DB-0002`, `CON-UI-0003`. Any other kind is silently
+  untracked: `specPackIds.ts` and `contractReferences.ts` only recognise these
+  three, so an invented kind such as `CON-EVT-*` is neither declarable nor
+  traceable. Use `-` when the rule binds no contract. Do not put contract IDs
+  in `Notes`.
+- `Notes` is free prose. IDs written there are **not** traced by any tool and
+  must not be the only place an obligation is recorded.
+
 ## Rule Table (required)
 
-| BR-ID   | Title   | AC-Refs | Rule   | Notes   | NFR-Refs |
-| ------- | ------- | ------- | ------ | ------- | -------- |
-| BR-0001 | <title> | AC-0001 | <rule> | <notes> | <nfr>    |
+| BR-ID   | Title   | AC-Refs | Rule   | Contract-Refs | Notes   | NFR-Refs |
+| ------- | ------- | ------- | ------ | ------------- | ------- | -------- |
+| BR-0001 | <title> | AC-0001 | <rule> | CON-API-0001  | <notes> | <nfr>    |

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/06_Test-Cases.md

@@ -6,6 +6,39 @@
 - Include both `AC-Refs` and `EX-Ref` whenever possible.
 - Ensure test cases cover not only normal paths but also error paths, boundary values, and edge cases.
 
+Derive each row's `Level` with
+`.qfai/assistant/catalog/test-layers.md#layer-derivation-procedure-normative`.
+One oracle per TC; a multi-valued `Level` is illegal.
+
+## Level vocabulary
+
+`Level` holds exactly **one** layer code from the crosswalk in
+`.qfai/assistant/catalog/test-layers.md#layer-vocabulary-crosswalk-normative`:
+
+- `L1` — Unit
+- `L2` — Component
+- `L3` — Integration
+
+(Deliberately a list, not a table: `collectTestCaseIds` and the TDD coverage
+report both read `parseFirstMarkdownTable`, so the **Test Case Table below must
+be the first markdown table in this file**. A table here would be parsed as the
+TC table, find no `TC-ID` column, and silently disable `TDDLIST_TC_NOT_COVERED`
+for the whole spec.)
+
+`L1` and `L2` are TDD coverage targets — each needs a `tdd/test-list.md` row.
+`L3` is not. An obligation that spans two layers is two TC rows.
+
+**`L4` and `L5` are not `TC-*` values.** An oracle that lands at the service
+boundary (L4) or on a full-system journey (L5) is a misfiled obligation —
+record it as `CON-API-*` or `US-*`, not as a `TC-*` row. If one is declared
+anyway, the ATDD gate routes it to `<testsDir>/api/**` or `<testsDir>/e2e/**`
+by its declared `Level`; that routing is a safety net, not a licence to file
+L4/L5 as `TC-*`.
+
+`<testsDir>` is `paths.testsDir` from `qfai.config.yaml` (default `tests`); the
+traceability scan follows the configured value, so write the paths relative to
+it rather than hard-coding a literal `tests/` prefix.
+
 ## Test Case Table (required)
 
 | TC-ID   | Level | AC-Refs | EX-Ref  | Type     | Steps   | Expected   | Notes   |
@@ -14,6 +47,29 @@
 | TC-0002 | L2    | AC-0001 | —       | error    | <steps> | <expected> | <notes> |
 | TC-0003 | L2    | AC-0001 | —       | boundary | <steps> | <expected> | <notes> |
 
+### Level column values
+
+The layer this test case verifies; exactly one code per cell. All five codes are
+defined in `.qfai/assistant/catalog/test-layers.md`, which is the single source;
+the summaries below are a reading aid, not a second definition.
+
+- `L1` — Unit. The oracle observes inputs and return values only.
+- `L2` — Component. The oracle observes collaboration with a port through a
+  fixture adapter, with no real infrastructure.
+- `L3` — Integration. The oracle observes real infrastructure state
+  (DB / queue / filesystem). Tests live in `<testsDir>/integration/**`.
+- `L4` — API. The oracle observes service-boundary values (status, body, auth,
+  error contracts). Tests live in `<testsDir>/api/**`.
+- `L5` — E2E. The oracle observes a full-system journey. Tests live in
+  `<testsDir>/e2e/**`.
+
+Which codes require a `tdd/test-list.md` row is decided by
+`isCoverageTargetLevel`. It recognises both spellings of every layer — the code
+form (`L1`-`L5`) and the word form (`unit`, `integration`, `e2e`, …) — so `L1`
+and `L2` are coverage targets that need a ledger row and `L3`-`L5` are not. A
+value it recognises in neither spelling is conservatively treated as a target,
+and `TDDLIST_UNKNOWN_LEVEL` reports it rather than letting it pass silently.
+
 ### Type column values
 
 - `normal` — Happy path / expected successful behavior.