qfai 1.9.2 → 1.10.0

package/assets/init/.qfai/assistant/catalog/test-layers.md

@@ -2,8 +2,87 @@
 
 This document is the SSOT for ATDD test-layer semantics and completion gates.
 
+## Layer vocabulary crosswalk (normative)
+
+qfai spells the same layer four ways across shipped artifacts. This table is
+the crosswalk; every artifact MUST use the spelling in its column.
+
+| Code | Word        | Tag                 | Test directory              | `06_Test-Cases.md#Level` | `tdd/test-list.md#Layer` |
+| ---- | ----------- | ------------------- | --------------------------- | ------------------------ | ------------------------ |
+| L1   | Unit        | `layer-unit`        | project convention          | `L1`                     | `Unit`                   |
+| L2   | Component   | `layer-component`   | project convention          | `L2`                     | `Component`              |
+| L3   | Integration | `layer-integration` | `<testsDir>/integration/**` | `L3`                     | `Integration`            |
+| L4   | API         | `layer-api`         | `<testsDir>/api/**`         | —                        | `API`                    |
+| L5   | E2E         | `layer-e2e`         | `<testsDir>/e2e/**`         | —                        | `E2E`                    |
+
+Rules:
+
+- **One value per cell.** A `Level` cell and a `Layer` cell each hold exactly
+  one layer. An obligation spanning two layers is two rows, not one row with
+  two values.
+- `06_Test-Cases.md` uses the **code** (`L1`…`L3`) in its `Level` column.
+- `tdd/test-list.md` uses the **word** in its `Layer` column.
+- Test-strategy tags in prompts and policy files use the **tag** form.
+- **`<testsDir>` is `paths.testsDir` from `qfai.config.yaml`**, whose default
+  is `tests` — hence the shipped `tests/integration/**`, `tests/api/**` and
+  `tests/e2e/**`. A project that repoints `paths.testsDir` moves all three at
+  once; the ATDD traceability scan follows the configured value, so never
+  hard-code the literal `tests/` prefix in a project's own artifacts.
+- L1 and L2 have no mandated directory: unit and component tests live wherever
+  the project's own convention puts them. Only L3-L5 are directory-pinned, and
+  only those directories are scanned by the ATDD traceability rules.
+- **A `TC-*` row's `Level` is L1-L3.** The ATDD annotation hard gate routes an
+  obligation by its ID, not by its `Level`: `US-*` is answered from
+  `<testsDir>/e2e/**` (`QFAI-ATDD-111`), `TC-*` from
+  `<testsDir>/integration/**` (`QFAI-ATDD-112`) and `CON-API-*` from
+  `<testsDir>/api/**` (`QFAI-ATDD-113`) and `CON-DB-*` from
+  `<testsDir>/integration/**` (`QFAI-ATDD-115`), while a `TC-*` reference inside
+  `<testsDir>/api/**` or `<testsDir>/e2e/**` is rejected outright
+  (`QFAI-ATDD-121` / `QFAI-ATDD-122`). L4's goal is `CON-API-*` and L5's is
+  `US-*` (see the layer definitions below), so an oracle that lands at L4 or L5
+  means the obligation is misfiled: record it as `CON-API-*` or `US-*` rather
+  than as a `TC-*` row no test directory can carry.
+- The two code-side word lists (`tddHelpers.ts#UNIT_COMPONENT_LAYERS` /
+  `#NON_COVERAGE_LAYERS`) accept both the code and the word form for the same
+  layer; they MUST stay in step with this table.
+
+## How this file is consumed
+
+The layer set below is read by `core/layerPolicy.ts` and is the SSOT for two
+checks: `QFAI-EX-005` on the legacy spec-pack layout, and `QFAI-EX-105` on the
+layered layout `npx qfai init` produces. Until both consumed it, the file was
+read, reported on, and then ignored on every modern project.
+
+- A file that yields no layers raises `QFAI-SPACK-090` (error) rather than
+  silently widening to the built-in set.
+- A declared set that disagrees with the built-in set raises `QFAI-SPACK-091`
+  (warning). Without it the two could drift in either direction and this file
+  would not be an SSOT.
+
+## Scaffolded tests
+
+`npx qfai atdd scaffold` writes skeletons to `<testsDir>/integration/<spec-id>/`.
+There is deliberately no `<testsDir>/atdd/**` row below: a fourth root would
+need a rule for which layer such a file belongs to, and qfai has none. The
+writer targets a declared layer instead.
+
 ## Layer definitions
 
+### L1 Unit
+
+- Scope: pure decision logic — a single module's inputs and return values, with
+  no port collaboration and no real infrastructure.
+- Goal: verify `TC-*` obligations whose oracle observes inputs and outputs only.
+- Location rule: `tests/unit/**`.
+
+### L2 Component
+
+- Scope: collaboration with a port through a fixture adapter (fake / in-memory),
+  with no real infrastructure.
+- Goal: verify `TC-*` obligations whose oracle observes the interaction with a
+  port rather than infrastructure state.
+- Location rule: `tests/component/**`.
+
 ### L3 Integration
 
 - Scope: real infrastructure integration (for example DB/queue/filesystem) within service boundaries.
@@ -22,8 +101,103 @@ This document is the SSOT for ATDD test-layer semantics and completion gates.
 - Goal: verify `US-*` obligations from specs.
 - Location rule: `tests/e2e/**`.
 
+## Layer derivation procedure (normative)
+
+Deciding a `TC-*`'s layer is a per-TC judgement, not a constant. Use the
+falsifying-oracle rule:
+
+1. **Find the oracle.** Identify the single assertion whose removal would let a
+   wrong implementation pass. That assertion, not the test's setup, is what the
+   TC verifies.
+2. **Restrict it to the parent BR's obligations.** Anything the oracle observes
+   that the parent business rule does not own is incidental and does not raise
+   the layer.
+3. **Read the layer off what the oracle observes:**
+   - inputs and return values only → **L1 Unit**
+   - collaboration with a port through a fixture adapter (no real
+     infrastructure) → **L2 Component**
+   - real infrastructure state — DB rows, queue messages, files → **L3 Integration**
+   - values at the service boundary — status codes, response bodies, auth and
+     error contracts → **L4 API**
+   - a full-system journey across UI/API/data → **L5 E2E**
+
+### Worked examples
+
+| Oracle asserts                                                                | Layer          |
+| ----------------------------------------------------------------------------- | -------------- |
+| `price(order) === 1250` for a given input                                     | L1 Unit        |
+| the repository port was called with the normalized key, via a fixture adapter | L2 Component   |
+| the row is present in the database after commit                               | L3 Integration |
+| `POST /orders` returns `422` with `code: "OUT_OF_AREA"`                       | L4 API         |
+| a user can register, order, and see the order in their history                | L5 E2E         |
+
+### Obligation spanning more than one layer
+
+**Split the row.** One TC = one oracle = one layer. If an obligation is
+observable at two layers, it is two obligations: write one TC per oracle and
+give each its own `Level`.
+
+- A multi-valued `Level` cell (`L3/L5`) is **illegal**. Nothing consumes it and
+  no validator can route it.
+- If splitting is genuinely impossible, escalate through the Drift Protocol
+  rather than inventing a combined value.
+
+### Direction of authority (anti-pattern)
+
+The test driver follows the declared layer. **The layer is never inferred from
+how a test happens to be driven.** A unit-level obligation — one whose oracle,
+after step 2, observes only inputs and return values — exercised through an
+HTTP client is still L1 badly implemented; it is not an L4 test.
+
+**Step 2 outranks step 3.** Restriction to the parent BR's obligations runs
+first, so a transport the parent BR does not own is incidental and never
+raises the layer. A BR that owns only the price calculation, asserted as
+`response.body.price` over HTTP, reads as L1: the price is the BR-owned value,
+the response envelope is the incidental transport. Step 3's "response bodies →
+L4" applies only when the service-boundary values are themselves what the
+parent BR owns. Inverting this is what collapses a designed pyramid into an
+all-integration suite.
+
+### Annotation routing is by ID type, not by `Level`
+
+The derived `Level` records which oracle owns the obligation. It does **not**
+move the traceability annotation. The [ATDD annotation hard gate](#atdd-annotation-hard-gate)
+routes by obligation ID: `US-*` is answered from `tests/e2e/**`
+(`QFAI-ATDD-111`), `TC-*` from `tests/integration/**` (`QFAI-ATDD-112`), and
+`CON-API-*` from `tests/api/**` (`QFAI-ATDD-113`); a `TC-*` reference inside
+`tests/api/**` or `tests/e2e/**` is rejected outright (`QFAI-ATDD-121` /
+`QFAI-ATDD-122`). Two consequences bind every `TC-*` row:
+
+- **A `TC-*` row's `Level` stays within L1–L3.** L4's goal is `CON-API-*` and
+  L5's goal is `US-*` (see the layer definitions above), so an oracle that
+  derives to L4 or L5 means the obligation is misfiled, not that the TC is an
+  L4/L5 test. Re-file it as `CON-API-*` or `US-*`.
+  **Re-filing is an upstream change, never a bare row deletion.** By step 2 the
+  derivation reaches L4/L5 only when the parent `BR-*` itself owns the
+  service-boundary contract or the journey, so the `TC-*` row is removed only
+  together with the `EX-*` it verifies and the `BR-*`/`AC-*` that EX
+  concretizes. Dropping the row alone leaves the parent EX with no `EX-Ref`
+  and `npx qfai validate --profile sdd --fail-on error` reports `QFAI-COV-203`
+  (and `QFAI-COV-201` when that TC was the AC's only cover); dropping the EX
+  but keeping its BR reports `QFAI-COV-202`. Move the whole chain in one
+  change through the Drift Protocol so `04_Business-Rules.md`,
+  `05_Examples.md`, `06_Test-Cases.md` and the contract stay consistent. If the
+  parent BR keeps a spec-side obligation, split the row instead: keep a `TC-*`
+  for the part the BR owns — by step 2 that part derives to L1–L3 — and re-file
+  only the boundary assertion as `CON-API-*` / `US-*`.
+- **An L1/L2 `Level` does not relax `QFAI-ATDD-112`, and the gate does not
+  change the `Level`.** The two are independent: the `Level` records what the
+  oracle observes and is derived before any test exists, while the
+  `QFAI:SPEC-XXXX:TC-YYYY` annotation is still owed to `tests/integration/**`.
+  Never rewrite a derived L1/L2 to L3 because no integration trace exists yet —
+  that would make the recorded oracle depend on implementation order and hide
+  the unit/component work `/qfai-implement` selects. The missing annotation is
+  an open ATDD obligation to satisfy, not evidence that the `Level` was wrong.
+
 ## TestKind resolution (single source)
 
+- `tests/unit/**` -> Unit
+- `tests/component/**` -> Component
 - `tests/e2e/**` -> E2E
 - `tests/api/**` -> API
 - `tests/integration/**` -> Integration
@@ -31,46 +205,213 @@ This document is the SSOT for ATDD test-layer semantics and completion gates.
 ## Annotation schema (code-side)
 
 - Smallest trace unit is ID.
-- Multiple IDs per test file are allowed.
+- Multiple IDs per test file are allowed — but this is a trace rule, not
+  licence to aggregate a whole spec into one module. See Test-file granularity
+  below.
 - AC annotations are optional (indirect coverage through TC is acceptable).
 - Allowed forms:
   - `QFAI:SPEC-0001:US-0001`
   - `QFAI:SPEC-0001:TC-0001`
   - `QFAI:CON-API-0001`
+  - `QFAI:CON-DB-0001`
 
 ## ATDD annotation hard gate
 
 - E2E obligations:
-  - Every `US-*` in specs must be referenced at least once from `tests/e2e/**` (no exception).
+  - Every `US-*` in a **user-facing** spec must be referenced at least once from
+    `tests/e2e/**`. "User-facing" is the same surface **union**
+    `/qfai-prototyping` enforces. Any one of these signals puts a spec in it:
+    - frontmatter `surface_type: ui-bearing` in `01_Spec.md`;
+    - a matching UI contract `.qfai/contracts/ui/<spec-id>*.yaml` — a project
+      that declares its surfaces only through contracts is still in scope;
+    - a legacy `# … prototyping …` heading in `01_Spec.md`;
+    - the spec pinned by `qfai.config.yaml#prototyping.primarySpecId`.
+
+    A spec that declares no user-facing surface by **any** of those signals
+    owes no E2E reference, and `QFAI-ATDD-111` does not fire for it.
+
+  - Scoping applies only when the project declares at least one UI-bearing
+    spec. A project that has never declared a surface has not opted into
+    surface typing, so the obligation stays project-wide for it.
+  - Do not create an E2E tree whose only purpose is to receive annotations.
+    That is the "convert all obligations into E2E" anti-pattern below.
   - Use `QFAI:SPEC-XXXX:US-YYYY` annotations.
-- Integration obligations:
-  - Every `TC-*` in specs must be referenced at least once from `tests/integration/**`.
-  - Use `QFAI:SPEC-XXXX:TC-YYYY` annotations.
+
+- Integration obligations (enforced today):
+  - Every `TC-*` in specs must be referenced at least once from the directory
+    its declared `Level` routes to: L3/Integration -> `tests/integration/**`,
+    L4/API -> `tests/api/**`, L5/E2E -> `tests/e2e/**`. A TC with no declared
+    `Level` defaults to `tests/integration/**`. This is what `QFAI-ATDD-112`
+    checks. - Use `QFAI:SPEC-XXXX:TC-YYYY` annotations.
+  - `tests/api/**` and `tests/e2e/**` must not carry `TC-*` annotations
+    (`QFAI-ATDD-121` / `QFAI-ATDD-122`), so an L4 obligation is discharged as a
+    `CON-API-*` reference, never as a `TC-*` one.
+  - Every declared `CON-DB-*` must be referenced at least once from
+    `tests/integration/**` (`QFAI-ATDD-115`). Use `QFAI:CON-DB-XXXX`
+    annotations. L3 owns this because a DB contract is only exercised against
+    real infrastructure, which is L3's declared scope; a `CON-DB` reference
+    from `tests/e2e/**` is not counted, or an end-to-end assertion that never
+    touches the schema could close the obligation. A contract outside the
+    current slice defers with a `-- x-qfai-status: planned` comment line,
+    reported at `info` by `QFAI-ATDD-116` so the deferral stays visible.
+
+- Per-level routing (target state — **not enforced, do not follow yet**):
+  - The intended end state is one required location per declared `Level`:
+    L1 -> `tests/unit/**`, L2 -> `tests/component/**`,
+    L3 -> `tests/integration/**`. L4 stays `CON-API-*` in `tests/api/**` and
+    L5 stays `US-*` in `tests/e2e/**`.
+  - **This is not live.** `buildAtddTestGlobs` scans only
+    `tests/{e2e,api,integration}`, so an annotation placed in `tests/unit/**`
+    or `tests/component/**` is invisible to the scanner and `QFAI-ATDD-112`
+    still reports the TC as uncovered. Until the scanner and `QFAI-ATDD-112`
+    resolve per-TC, keep discharging every `TC-*` in `tests/integration/**`.
 - API obligations:
   - Every declared `CON-API-*` must be referenced at least once from `tests/api/**`.
   - Use `QFAI:CON-API-XXXX` annotations.
+  - **Deferral.** `/qfai-sdd` authors contracts in Phase 0 (Contracts-first) and
+    slices them in Phase 2, so a contract legitimately exists before its slice
+    ships. A contract that declares `x-qfai-status: planned` is excluded from
+    the `QFAI-ATDD-113` obligation and reported as `QFAI-ATDD-114` (`info`)
+    instead. Remove the marker when the slice is implemented — leaving it in
+    place on a shipped slice is a review finding, not a tool finding.
+    - The marker counts only at the **document root**. The same key nested under
+      an operation defers nothing: one path must not be able to drop the
+      API-test obligation for every other `CON-API-*` the file declares.
+    - Deferral removes the test obligation, not the declaration. A deferred
+      `CON-API-*` stays a known ID, so writing its API test ahead of the slice
+      is fine and never raises `QFAI-ATDD-103`.
+    - Deferred IDs are recorded in `report/atdd-traceability/summary.{json,md}`
+      under `deferred.conApi`, so an empty `missing.conApi` can be told apart
+      from a project where every contract is still planned.
 - Forbidden references:
-  - `tests/api/**` must not include `QFAI:SPEC-XXXX:TC-YYYY`.
-  - `tests/e2e/**` must not include `QFAI:SPEC-XXXX:TC-YYYY`.
+  - `tests/api/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
+    declared `Level` is not L4/API**. A TC that declares an API-level
+    obligation belongs in `tests/api/**`, and its annotation there counts as
+    coverage. The rule exists to stop obligations drifting into the wrong
+    layer, not to make the correct layer unusable.
+  - `tests/e2e/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC whose
+    declared `Level` is not L5/E2E**. Same reason as above: the routing rule
+    and the forbidden rule must agree, or the layer the routing selects
+    becomes unusable.
+  - `tests/integration/**` must not include `QFAI:SPEC-XXXX:TC-YYYY` **for a TC
+    whose declared `Level` is not L3/Integration** (`QFAI-ATDD-123`). The rule
+    is symmetric so "exactly one directory" holds in both directions: an
+    annotation left behind here after the TC moved to L4/L5 is as wrong as one
+    filed early into `tests/api/**`.
 - Unknown references (`US/TC/CON-API` not declared) are errors.
+- A `TC-*` annotation outside the directory its `Level` routes to is a
+  misplacement, whichever directory it lands in — including the two new
+  locations `tests/unit/**` and `tests/component/**`.
 - AC annotations are not required in code; AC coverage is treated as indirect through TC coverage.
 - `QFAI:CON-API-*` in `tests/e2e/**` is not forbidden, but contract guarantee belongs to API tests.
 
+## Test-file granularity
+
+- Default: **one test module per `TC-*`**. A TDD ledger row's `Test file`
+  names that module.
+- Grouping several `TC-*` into one module is allowed when they verify the same
+  BR and the module stays reviewable in one pass. Above that, split by BR, then
+  by AC.
+- A single `Test file` value shared by every row of a spec is an anti-pattern:
+  it makes the per-item "relevant test suite" indistinguishable from the whole
+  spec suite, and it puts the whole spec's test code in front of every
+  in-context reviewer gate.
+- `qfai-sdd` should emit a per-item `Test file` value, not a per-spec one.
+
 ## Volume policy
 
-- Floors and ratios are signals, not completion gates.
+- Floors and ratios are signals, not completion gates. This is the only
+  statement in this section: no volume observation blocks completion, and none
+  triggers a Change Request.
 - Completion gate is validation pass with no errors:
-  - `qfai validate --fail-on error`
+  - `npx qfai validate --fail-on error`
+
+If an observed layer distribution looks wrong:
+
+1. Do not auto-adjust the distribution to make it look better.
+2. Record the observed distribution and the rationale for it in the running
+   stage's evidence file under `.qfai/evidence/` — for example
+   `.qfai/evidence/atdd-<spec-id>.md` or
+   `.qfai/evidence/implement-<spec-id>.md`.
+3. Continue. The stage is not blocked.
 
-If a volume signal is unmet:
+The record goes to evidence, not into the spec, on purpose.
+`constitution/drift-protocol.md` lists `*_delta.md` and the per-spec Open
+Questions file among the upstream SSOT a downstream stage must not edit without
+explicit user approval, and whitelists `.qfai/evidence/**` append/update as an
+allowed exception. Pointing this step at the spec would send ATDD and implement
+straight back into the STOP-and-wait state the policy exists to avoid.
 
-1. STOP auto-adjustment.
-2. Raise a Change Request with 3 options and recommendation.
-3. Wait for explicit user approval.
-4. Update upstream artifacts via owner-phase rerun when required.
+The owner phase (`/qfai-sdd`) is the one that may carry the note into the
+spec's own Open Questions file on a later run: `08_Open-questions.md` in a
+layered spec, `15_Open-questions.md` in a spec pack.
+(`09_Open-questions.md` is the shared `_policies` file, not a per-spec one.)
+
+A Change Request is reserved for `constitution/drift-protocol.md`-class events
+— an actual conflict with an upstream SSOT decision. A volume observation is not
+one, and it stays non-blocking either way. What differs is how much of it is
+measurable:
+
+- **No configured guardrail.** qfai ships no default floor, ratio or threshold,
+  and no validator emits a volume rule, so "unmet" is a judgement call with no
+  tool-checkable meaning. Record the observation and the reasoning.
+- **A configured guardrail.** When a project sets
+  `validation.testStrategy.maxE2eScenarioRatio` or `maxE2eScenarioCount` to a
+  non-null value, `report.ts` measures it and reports `ratioExceeded` /
+  `countExceeded` with a warning. That is the project's own stated limit, not a
+  subjective read: record the configured value, the measured value and the
+  report warning in the evidence, so the breach is auditable rather than
+  paraphrased.
+
+  **What it counts is narrow.** These two knobs measure **Gherkin scenarios
+  parsed out of each spec's Examples file**, bucketed by their `@layer-*` tags.
+  They never inspect `<testsDir>/e2e/**` or any other code test. A project that
+  writes no Gherkin — the normal shape for a layered project whose E2E lives in
+  code — measures zero scenarios, so the guardrail stays silent however many
+  code E2E tests exist. Treat them as a guardrail over the **scenario**
+  distribution, not over the real test-layer distribution: when they are silent,
+  the observation is the judgement call above, and the evidence entry must say
+  how the distribution was counted so it is not read as a tool measurement.
+
+Either way completion is not blocked and no Change Request is raised: a
+user-blocking Change Request against a project's own tuning knob cannot conclude
+anything actionable.
 
 ## Anti-patterns
 
 - Do not treat `scenario.feature` or a coverage ledger as mandatory completion input.
 - Do not convert all obligations into E2E.
 - Do not inflate tests only to satisfy floor numbers.
+- Do not over-concentrate obligations into a single layer, module, or selector. Collapsing a matrix-shaped `TC-*` into one integration module — or into one test function behind one `test-list.md` selector — is the same failure mode as converting everything into E2E, and it additionally destroys the RED observation: a test function fails once, so only the first failing assert is ever observed. Split per independently observable boundary (see `qfai-implement/references/execution-ledger.md#selector-granularity-must`).
+- Do not re-label an existing obligation's declared layer to change how a
+  distribution reads. Re-labelling is the cheapest way to clear a signal and
+  the one that destroys the most information; the layer of an obligation is
+  determined by what it verifies, never by how the totals look.
+
+### Concentration signals (non-gating)
+
+Treat these as review signals in the same class as volume floors — worth a finding, never a hard gate:
+
+- one test module holding a disproportionate share of a spec's `assert` statements
+- a very low `test_` functions per file ratio in a module that carries many obligations
+- a single selector whose recorded runtime grows monotonically across RED rounds
+
+## Test stub detection (QFAI-TEST-001 / QFAI-TEST-002)
+
+`QFAI-TEST-001` (error) reports the silent-placeholder construct of each
+supported stack:
+
+| Extensions           | Construct                                                           |
+| -------------------- | ------------------------------------------------------------------- |
+| `.ts` / `.js` family | `it.todo(` / `test.todo(` / `describe.todo(`                        |
+| `.py`                | `pytest.skip(`, `@pytest.mark.skip/skipif/xfail`, `@unittest.skip*` |
+| `.go`                | `t.Skip*(`                                                          |
+| `.java` / `.kt`      | `@Disabled` / `@Ignore`                                             |
+| `.rs`                | `#[ignore]`                                                         |
+| `.rb`                | a line starting `skip` / `pending`                                  |
+| `.cs`                | `[Ignore` / `Skip = "`                                              |
+
+`QFAI-TEST-002` (info) names any extension the scan opened that has no dialect.
+Without it a clean run on an unsupported stack is indistinguishable from a
+checked one — the detector used to be JS-only while file selection was
+stack-agnostic, so every other stack got a clean result that meant nothing.

package/assets/init/.qfai/assistant/catalog/worklog-entry.schema.md

@@ -0,0 +1,165 @@
+# Work-log Entry Schema Contract
+
+- Contract scope: frontmatter and body schema for `.qfai/steering/*.md` entries
+- Owners: the validate stage (schema enforcement), the implement stage (primary writer) and the Reviewer-Gate stage (consumer)
+- Used-by: All implementation/review-phase skills, `npx qfai validate`, Reviewer subagents
+- SSOT modules:
+  - `packages/qfai/src/core/worklog/parseEntry.ts` (pure parser: `string → Result<Entry, SchemaError>`)
+  - `packages/qfai/src/core/worklog/validateLinks.ts` (link-integrity check)
+
+## Storage model
+
+- Per-project, project-root location: `.qfai/steering/`.
+- The **surface** lives at `.qfai/steering/`, not under `.qfai/assistant/`. This
+  **schema** ships with the package and `npx qfai init` seeds it at
+  `.qfai/assistant/catalog/worklog-entry.schema.md` — the seeded README and entry
+  template used to point at an unpublished path, so the contract was
+  unresolvable on every consuming project.
+- By default `.gitignore` excludes the directory; projects MAY opt in via override.
+- Filename: `.qfai/steering/<id>.md` where `<id>` is kebab-case ASCII; the frontmatter `id` MUST match the filename stem.
+- Templates live at `.qfai/steering/_templates/`; templates MUST NOT contain entry-shaped frontmatter (validator ignores `_templates/`).
+
+## Frontmatter schema
+
+```yaml
+---
+id: 2026-05-22-recut-design-call # required; string; kebab-case; matches filename stem
+status: active # required; enum: active | handoff | archived
+kind: decision # required; enum: see below
+created: 2026-05-22 # required; ISO-8601 date (YYYY-MM-DD)
+updated: 2026-05-22 # required; ISO-8601 date; >= created
+scope: spec-0003 # required; "global" or "spec-NNNN"
+blocking: false # required; boolean
+promote-to: spec-0003/07_Decisions.md # required; string (path) OR null
+links: # required; array (may be empty)
+  - spec-0003
+  - discussion-20260522081618995
+closure-rationale: null # required when status=archived AND no promote-to satisfied; else null/omitted
+promoted-to: null # required when status=archived AND promote-to was satisfied; value is the DR-ID (Decision Row identifier, e.g. `DR-3`) of the appended row in the target `07_Decisions.md`
+---
+```
+
+### `kind` enum (REQ-0004)
+
+The `kind` field MUST be exactly one of:
+
+| `kind`                | Write trigger                                                                |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `milestone`           | Task milestone reached                                                       |
+| `decision`            | A decision was made during work that needs durable capture                   |
+| `risk`                | A risk was identified                                                        |
+| `consultation-needed` | The skill needs user input to proceed                                        |
+| `unexpected`          | An unexpected event occurred during work                                     |
+| `unscoped-discovery`  | Out-of-scope concern discovered; current task continues unblocked (REQ-0016) |
+| `handoff`             | Work needs to pause; another session/operator will resume                    |
+| `blocker`             | The skill is stuck (e.g. root-cause hunt stalled)                            |
+| `scope-up`            | Work volume larger than expected                                             |
+| `scope-down`          | Planned work is no longer required                                           |
+| `spike`               | Exploratory investigation logged                                             |
+
+### `status` enum
+
+| `status`   | Meaning                                                                                       |
+| ---------- | --------------------------------------------------------------------------------------------- |
+| `active`   | Open; participates in drift/promote/stale checks                                              |
+| `handoff`  | Open and awaiting resumption; body MUST satisfy the handoff-brief schema (REQ-0017)           |
+| `archived` | Closed; either promoted (`promoted-to` set) or closed-without-promotion (`closure-rationale`) |
+
+### `scope` semantics
+
+- `global` — applies project-wide; visible to every skill invocation.
+- `spec-NNNN` — applies only to the named spec. Implementation-phase skills filter on `scope ∈ {global, current-spec}` before reading.
+
+### `promote-to` semantics
+
+- `null` — entry will not promote.
+- non-`null` — string of the form `spec-NNNN/07_Decisions.md` (target Decisions row to append). The promote-gate surfaces `W-PENDING-PROMOTION` until satisfied (REQ-0007).
+
+### `links` array
+
+Each element MUST resolve to one of:
+
+- `spec-NNNN` — an existing spec directory under `.qfai/specs/`
+- `discussion-*` — an existing discussion pack under `.qfai/discussion/`
+- `<entry-id>` — another `.qfai/steering/<id>.md` entry
+
+Broken links surface `W-WORKLOG-BROKEN-LINK` (REQ-0015).
+
+## Body schema
+
+The body (everything after the closing `---`) is free-form Markdown except for two `kind`-specific schemas below.
+
+### `kind: handoff` body — required sections (REQ-0017)
+
+```markdown
+## State of the task
+
+<one paragraph: where am I, what is done, what remains>
+
+## Next single action
+
+<one bullet: the very next thing to do on resume>
+
+## Constraints to preserve
+
+- <bulleted list of invariants that the next operator MUST preserve>
+
+## Open questions
+
+- <bulleted list; may be empty>
+
+## References to consult first
+
+- <bulleted list of entry IDs / spec IDs / discussion IDs>
+```
+
+Reviewer Gate emits `R-HANDOFF-INCOMPLETE` if any of the five sections is missing or empty.
+
+### `kind: decision` body — recommended sections
+
+```markdown
+## Context
+
+<what triggered the decision>
+
+## Decision
+
+<what was decided>
+
+## Alternatives considered
+
+<bulleted; mark each as accepted | rejected | deferred>
+
+## Rationale
+
+<why this option>
+
+## Consequences
+
+<what changes downstream>
+```
+
+The body is consulted by Reviewer Gate when emitting `R-WORKLOG-DRIFT`; the structured shape improves the false-positive rate.
+
+## Unit-test obligations (NFR-0010)
+
+`parseEntry.ts` MUST have ≥ 12 unit tests covering:
+
+1. Well-formed entry
+2. Missing required field (e.g. omitted `kind`)
+3. Invalid enum value
+4. Broken YAML (parse error)
+5. UTF-8 BOM tolerated
+6. CRLF line endings tolerated
+7. `scope: spec-NNNN`
+8. `scope: global`
+9. `promote-to: null`
+10. `promote-to: spec-NNNN/07_Decisions.md`
+11. `links: []`
+12. `links` array with broken reference (parser returns ok; validator emits `W-WORKLOG-BROKEN-LINK`)
+
+≥ 90 % line coverage of `parseEntry.ts` in CI.
+
+## Distributed-surface obligations
+
+The seeded `_templates/entry.md`, and any sample entry shipped via `assets/init/`, MUST carry no internal spec ids, version markers or trace ids. The authoritative list of forbidden shapes is the scanner itself; entries use placeholder ids and dates only.

package/assets/init/.qfai/assistant/constitution/communication.md

@@ -36,7 +36,7 @@ When an agent needs to ask the user a question, the following rules apply (see a
 All SKILL.md files MUST include a
 `## User Questions (AskUserQuestion Protocol)` section with MUST-level wording.
 SSOT: `packages/qfai/assets/init/.qfai/assistant/skills/*/SKILL.md`.
-Deployed copy (updated by `qfai init`): `.qfai/assistant/skills/*/SKILL.md`.
+Deployed copy (updated by `npx qfai init`): `.qfai/assistant/skills/*/SKILL.md`.
 
 ## Error handling