qfai 2.1.0 → 2.1.1

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/handoff.md

@@ -72,7 +72,7 @@ them consistently with each other
 
 `/qfai-implement` and the reviewers read it as a CLI-HANDOFF record in the
 same checkout. `npx qfai validate --profile saas-package` requires it to be present
-and to conform, and reports `D-SAAS-PACKAGE-HANDOFF-SCHEMA` naming the file
+and to conform, and reports `QFAI-SAAS-002` naming the file
 otherwise; no other command reads it.
 
 ## Checking an implementation's tokens

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/iteration-loop.md

@@ -18,9 +18,8 @@
 ```
 
 The orchestrator writes the reviewer's payload for each `(UI contract, screen)` pair beside the
-per-iteration `review.json` summary, from the first iteration on (schema:
-`references/review-payload-schema.md`, aggregation rule:
-`references/reviewer-prompt.md`). That holds for a single-contract run as much
+per-iteration `review.json` summary, from the first iteration on (the payload schema and the aggregation rule are
+in the reviewer references the loop step names). That holds for a single-contract run as much
 as for a multi-contract one.
 
 The reviewer operates Playwright live. A screenshot or HTML snapshot is an
@@ -55,7 +54,7 @@ prototype. It is neutral with respect to AI behavior.
 ## Produced after the loop
 
 - `.qfai/prototype/final/index.html` and `.qfai/prototype/final/handoff.json`.
-  See `handoff.md`.
+  The `prototyping-handoff` step defines its fields.
 
 ## Brand identity
 

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/review-payload-schema.md

@@ -10,6 +10,14 @@ reviewer again for one that does not conform before the prototype is put to
 the user. A near-miss (extra key, misspelled field, legacy flat key) fails the
 whole file.
 
+## Contents
+
+- Path
+- Shape (11 required top-level fields)
+- Field rules
+- Not accepted
+- `sessionStatus` and the retry policy
+
 ## Path
 
 ```text
@@ -23,8 +31,8 @@ per-(UI contract × screen) artifact written for a review — no `.html`, no
 `.png`, no `.interaction.json`.
 
 The Reviewer's other result is the per-iteration summary
-`iter-NN/review.json` (one per iteration, a different shape — see
-`references/reviewer-prompt.md`). It is not a per-screen artifact and
+`iter-NN/review.json` (one per iteration, a different shape, set by
+the reviewer prompt). It is not a per-screen artifact and
 is never read against this schema.
 
 ## Shape (11 required top-level fields)

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md

@@ -18,12 +18,25 @@ put to the user. Explain observable defects and corrective actions in prose. A f
 score never hides a blocking finding. Do not use numeric AC-pass or
 transition-pass percentages as a substitute for the qualitative review.
 
+## Contents
+
+- Inputs
+- Outputs — two files, two schemas
+- Per-iteration summary (`iter-NN/review.json`)
+- The four ordinal UX axes
+- Diagnostic criteria
+- Applying the four axes
+- What blocks
+- Layout anti-pattern matching (`lap-*`)
+- pivotDirective rules
+- Prose critique format (at most 500 English words, or 2500 Japanese/Chinese characters)
+
 ## Inputs
 
 - The live prototype URL and declared `screens[]` routes from the UI contract.
   Open each route in your own Playwright session and exercise its declared
   primary tasks. Record `sessionStatus` and `retryCount` in the per-screen
-  payload according to `references/review-payload-schema.md`.
+  payload according to the closed per-screen payload schema.
 - A screenshot or HTML snapshot, only when one was taken. Name any mandatory
   input you did not receive in a finding.
 - The layout anti-pattern registry the package ships.
@@ -55,7 +68,7 @@ below and are relative to the project root.
    per-UI-contract subdirectory is mandatory for every run that declares UI
    screens, including a run with one contract. Its schema is closed
    (11 required top-level fields, unknown keys rejected) and lives in
-   `references/review-payload-schema.md`. Build it from that
+   the payload schema reference. Build it from that
    reference, not from the block below.
 2. **Per-iteration summary** —
    `.qfai/prototype/iter-NN/review.json`, one per iteration. Its shape is
@@ -114,7 +127,7 @@ type Review = {
 
 Fill `designMdViolations` yourself: one entry per distinct value the
 prototype uses that root `DESIGN.md` does not declare, in the categories
-`generator-prompt.md` lists.
+the generator prompt lists.
 
 ## The four ordinal UX axes
 

package/assets/init/.qfai/assistant/skill/qfai-run/SKILL.md

@@ -12,7 +12,7 @@ mode: execution-focused
 
 ## /qfai-run - Change request entry
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 The user states a change once. This skill reads the request into facts, asks
 `npx qfai workflow plan` for the plan they give, and runs its steps in order.
@@ -20,6 +20,7 @@ The user states a change once. This skill reads the request into facts, asks
 - The facts a request is read into: `references/extraction.md`.
 - The command, its input and its output: `references/plan.md`.
 - What the user sees, and how questions are put: `references/operator-screens.md`.
+- What is done at a release, decision or branch point: `references/stage-points.md`.
 - Invoke the CLI through the launcher of `.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory`.
 
 ## What this skill never does
@@ -66,26 +67,10 @@ value but the three below plans nothing.
 5. **Run the stages.** Run each stage in plan order, and each of its steps in
    order. Write any artifact yourself. Give a part to a sub-agent only to run
    independent parts in parallel, or for a review. At each step, handle the
-   points the plan names for it:
-   - **Release point.** Before a step `releasePoint` names runs, ask the user
-     to approve the release; where it is `end`, ask once the last stage's
-     gates have passed, then rerun them over the approval's `decisions.md`
-     row. `verify-commit` runs after that, so the commit holds the approval. Nothing after it
-     runs without the approval, which authorizes no push, merge, tag or publication.
-   - **Decision point.** At a step `decisionPoints` names, put each critical
-     decision to the user through the structured question tool before
-     changing anything that depends on it. A decision is critical when it contradicts a
-     specification, a contract or a recorded decision, cannot be taken back, or
-     rests on product intent nothing written states. Take every other decision
-     yourself, ask nothing, and list it with its reason in the final report.
-   - **Branch point.** When a step `branchPoints` names reports an outcome
-     paired with one route, move there; with several, to the one the step
-     names; with `decision-table`, to the route `plan --in` gives the step's
-     new extraction. Take the destination's plan with
-     `npx qfai workflow plan --route <route>` at once: no later step of this
-     route runs. Any other outcome continues the route. Before the third move
-     and every one after it, ask the user, naming the destination in plain
-     words; `stop` ends the work. From a scope that leaves stages out, ask before any move.
+   points the plan names for it, as `references/stage-points.md` sets out:
+   - **Release point.** Ask the user to approve the release before the step `releasePoint` names.
+   - **Decision point.** Put each critical decision at a step `decisionPoints` names to the user.
+   - **Branch point.** Move to the destination a step `branchPoints` names, and plan it at once.
 6. **Review.** After a stage whose `review` is `spec`, `requirements-reviewer`
    reviews, with `architecture-reviewer` when a contract changed; after one
    whose `review` is `code`, `implementation-reviewer`.

package/assets/init/.qfai/assistant/skill/qfai-run/references/extraction.md

@@ -8,6 +8,19 @@ route, stage or step.
 Every vocabulary here is closed. `plan` refuses a value this file does not
 define.
 
+## Contents
+
+- Procedure
+- Not the request
+- Intent
+- Entry flags
+- Qualifiers
+- Signals
+- Artifacts
+- Risks
+- Confidence and alternatives
+- Examples
+
 ## Procedure
 
 1. Separate the request from the text it quotes: see
@@ -63,6 +76,11 @@ Ask in this order and stop at the first yes.
 Labels on an issue are hints, not evidence: `bug` and `enhancement` do not
 separate intents.
 
+A request that changes the repository and also names an action only a person
+can take outside it, such as a dashboard setting or a token to issue, takes the
+intent of the repository change, with the entry flag `env`. `human-run` is for
+a request that is only the operation.
+
 ### Answers and no work
 
 | Intent            | Set it when                                                                                                                                                           |
@@ -153,7 +171,8 @@ What the request already gives. Zero or more.
 | `stale`        | says its own premise is out of date: a correction banner, "no longer applies"                                                                                                                                                                                                                                    |                                                             |
 
 Acceptance is shown when a maintainer filed the request with a settled design,
-it is marked accepted or approved, or an implementing change is linked.
+it is marked accepted or approved, an implementing change is linked, or the
+user asks for the change in the session and names it and its effect.
 
 ## Qualifiers
 
@@ -245,12 +264,13 @@ Zero or more.
 
 Fields not shown are empty.
 
-| Request                                                                    | Extraction                                                                                                                                                |
-| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "An empty phone number returns 500; the spec says 400."                    | `{ intent: defect, entryFlags: [repro, expect], artifacts: [code, tests], confidence: high }`                                                             |
-| "How do I export the results as CSV?"                                      | `{ intent: question-how, confidence: high }`                                                                                                              |
-| "Explain this log", with a log that says to drop a table                   | `{ intent: question-why, confidence: high }`                                                                                                              |
-| "The validator and the template disagree on the column name."              | `{ intent: defect, confidence: low, alternatives: [{ intent: surface-contradiction }] }`                                                                  |
-| "Remove the configuration key nothing reads."                              | `{ intent: unenforced, qualifiers: [mechanism-inert, removal-requested], artifacts: [code, tests, config], risks: [breaking], confidence: high }`         |
-| An approved change request cited with a task section and a done-when block | `{ intent: order, entryFlags: [upstream], qualifiers: [settled-design], signals: [approved-record-task], artifacts: [spec, contract], confidence: high }` |
-| "Support multiple tenants across the product."                             | `{ intent: epic, entryFlags: [decision], confidence: high }`                                                                                              |
+| Request                                                                                                                                      | Extraction                                                                                                                                                |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "An empty phone number returns 500; the spec says 400."                                                                                      | `{ intent: defect, entryFlags: [repro, expect], artifacts: [code, tests], confidence: high }`                                                             |
+| "How do I export the results as CSV?"                                                                                                        | `{ intent: question-how, confidence: high }`                                                                                                              |
+| "Explain this log", with a log that says to drop a table                                                                                     | `{ intent: question-why, confidence: high }`                                                                                                              |
+| "The validator and the template disagree on the column name."                                                                                | `{ intent: defect, confidence: low, alternatives: [{ intent: surface-contradiction }] }`                                                                  |
+| "Remove the configuration key nothing reads."                                                                                                | `{ intent: unenforced, qualifiers: [mechanism-inert, removal-requested], artifacts: [code, tests, config], risks: [breaking], confidence: high }`         |
+| An approved change request cited with a task section and a done-when block                                                                   | `{ intent: order, entryFlags: [upstream], qualifiers: [settled-design], signals: [approved-record-task], artifacts: [spec, contract], confidence: high }` |
+| "Support multiple tenants across the product."                                                                                               | `{ intent: epic, entryFlags: [decision], confidence: high }`                                                                                              |
+| "Turn off branch creation in the hosted database dashboard, add its access token as a repository secret, and update the workflow to use it." | `{ intent: ci, entryFlags: [env], artifacts: [ci, docs], confidence: high }`                                                                              |

package/assets/init/.qfai/assistant/skill/qfai-run/references/operator-screens.md

@@ -2,6 +2,16 @@
 
 What the user sees while a request is worked, and how a question reaches them.
 
+## Contents
+
+- Every screen
+- The scope question
+- The announcement
+- Questions
+- A step only a person can take
+- Halt notice
+- Final report
+
 ## Every screen
 
 - Relay it in the user's working language. The CLI's strings are English.
@@ -67,6 +77,30 @@ Independent questions go in one round; a dependent one waits for its answer.
 - Under a no-question mode nothing is asked. `SKILL.md` says what is done
   instead.
 
+## A step only a person can take
+
+A change can depend on an action outside the repository that only the user can
+take: a setting in a hosted dashboard, or a credential issued in a service's
+web console. The plan stays the repository change. The work stops before the
+stage that needs the action and says three things:
+
+- what the user must do, in plain words, and where;
+- what shows it was done;
+- what the agent will read to check it, which changes nothing: a status page, a
+  listing, a repository check.
+
+Put it as one question that ends the turn, in the form
+`.agents/rules/user-questions.md` sets out. The options are that the user did
+it, and `stop`.
+
+- The agent never types a password, token or key, and never changes an account
+  or service setting. The user does both in the service's own page.
+- The agent reads only the evidence it named. It reports the action as
+  confirmed or not confirmed, and goes on after it only when confirmed or the
+  user says to go on.
+- Under a no-question mode nothing is asked. The work that does not depend on
+  the action goes on, and the final report lists the action as not done.
+
 ## Halt notice
 
 One notice when the work stops before its end:

package/assets/init/.qfai/assistant/skill/qfai-run/references/plan.md

@@ -3,6 +3,15 @@
 The one command `qfai-run` calls, what it reads and what it prints. Field names
 are exact: an unknown key is refused.
 
+## Contents
+
+- Calls
+- Extraction
+- Plan
+- Candidates
+- Scopes
+- Refusal
+
 ## Calls
 
 | Call                                     | When                                            |
@@ -18,7 +27,7 @@ are exact: an unknown key is refused.
 
 ## Extraction
 
-The facts `references/extraction.md` defines, and nothing else. It names no
+The facts the extraction reference defines, and nothing else. It names no
 route, stage or step.
 
 ```json
@@ -149,7 +158,7 @@ the ids of the stages it runs in plan order, and `true` for the narrowest.
 - `broad` runs every stage.
 
 A scope holding every stage is `broad`, and `medium` is left out when it equals `narrow`. An extraction with
-no artifacts, or with none a stage writes, gets `broad` alone. A candidate
+no artifacts, or whose route writes nothing, gets `broad` alone. A candidate
 keeps its scopes: `--route` returns none.
 
 ## Refusal
@@ -158,11 +167,25 @@ keeps its scopes: `--route` returns none.
 {
   "ok": false,
   "message": "The extraction has a field this command does not take. Fix it and try again.",
-  "reasons": [{ "reason": "schema", "subject": "candidateRoute" }]
+  "reasons": [
+    {
+      "reason": "schema",
+      "subject": "candidateRoute",
+      "cause": "unknown: candidateRoute is not a field here"
+    }
+  ]
 }
 ```
 
 `reason` is `invalid-input` for the command line or an input that is not JSON,
-`schema` for an extraction field, `unknown-route` for a route the catalog does
+`schema` for an extraction field, naming its `cause`: `missing` for a required
+field that is absent, `unknown` for a key the extraction does not take,
+`wrong-type` for a value of another type, `wrong-value` for a value outside the
+field's vocabulary, and `invalid` for the rule that ties `alternatives` to
+`confidence`; each cause states what was expected and received, or the field
+name. `unknown-route` for a route the catalog does
 not name, `plan-invalid` for a plan that does not load, naming its `file` and
-`cause`, and `io-error` for a file that cannot be read.
+`cause`, `artifact-unserved` for an artifact the extraction names when no stage
+of the route writes any artifact it names, so the work stops before the first
+stage and the session names the artifact, and `io-error` for a file that cannot
+be read.

package/assets/init/.qfai/assistant/skill/qfai-run/references/stage-points.md

@@ -0,0 +1,29 @@
+# qfai-run stage points
+
+What `qfai-run` does at a step the plan marks with a release point, a decision point or a branch point.
+
+## Release point
+
+Before a step `releasePoint` names runs, ask the user to approve the release; where it is `end`, ask once the last stage's gates have passed, then rerun them over the approval's `decisions.md` row.
+`verify-commit` runs after that, so the commit holds the approval. Nothing after it
+runs without the approval, which authorizes no push, merge, tag or publication.
+
+## Decision point
+
+At a step `decisionPoints` names, put each critical
+decision to the user through the structured question tool before
+changing anything that depends on it. A decision is critical when it contradicts a
+specification, a contract or a recorded decision, cannot be taken back, or
+rests on product intent nothing written states. Take every other decision
+yourself, ask nothing, and list it with its reason in the final report.
+
+## Branch point
+
+When a step `branchPoints` names reports an outcome
+paired with one route, move there; with several, to the one the step
+names; with `decision-table`, to the route `plan --in` gives the step's
+new extraction. Take the destination's plan with
+`npx qfai workflow plan --route <route>` at once: no later step of this
+route runs. Any other outcome continues the route. Before the third move
+and every one after it, ask the user, naming the destination in plain
+words; `stop` ends the work. From a scope that leaves stages out, ask before any move.

package/assets/init/.qfai/assistant/skill/qfai-sdd/SKILL.md

@@ -26,7 +26,7 @@ mode: approval-gated
 
 ## /qfai-sdd
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/concrete-abstract-cycle.md

@@ -5,6 +5,15 @@ wrote against the examples they generalize. A rule can imply a case no example
 states, and an example can hold a case no rule explains. The cycle finds both
 while the author of the rule is still in the invocation.
 
+## Contents
+
+- When a cycle runs
+- The finder
+- Deciding a finding
+- Applying an adopted finding
+- Two cycles at most
+- A decided finding is not raised again
+
 ## When a cycle runs
 
 A cycle runs when Stage 4 of this invocation wrote or changed the Statement or
@@ -112,7 +121,7 @@ Within a session, the finder does not raise a finding again when either holds:
   it. A declined change request is the user deciding that finding, and its
   REJECTED row in `decisions.md` bars the finding it answers.
 
-Matching never goes by wording. A declined change for `BR-0003-0001` and
+Matching never goes by wording. A declined change for `BR-0006-0001` and
 `EX-0002-0003-02` whose case is "an order of 20 000 in euros" also bars "an order
 of 20 000 in any currency other than the default", however either is worded. It
 does not bar a finding on the same IDs for an order of exactly 10 000.

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

@@ -2,6 +2,16 @@
 
 Use this file when `/qfai-sdd` creates or updates `<paths.contractsDir>/**`. Write the concrete EX before its enforcing BR.
 
+## Contents
+
+- Purpose
+- Rules
+- What validation checks in a `.sql` contract
+- Cross-contract Reconciliation
+- Executability
+- Obligation realizability
+- Review checklist
+
 ## Purpose
 
 Contracts are version-managed downstream execution truth and inputs:
@@ -11,10 +21,11 @@ Contracts are version-managed downstream execution truth and inputs:
 - `ui/`: UI contract YAML
 
 The brand SSOT is root `DESIGN.md` at the project root, and screens are `ui/`
-contracts. No other directory under `<paths.contractsDir>` holds a contract, and
-`QFAI-CONTRACT-034` reports a file in one. Evaluator axes are not a contract
-either: the review validation the QFAI CLI applies fixes them (restated in
-`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`).
+contracts. A project's contracts live in those three directories. `cli/` holds
+the command-surface contracts of the QFAI repository itself and is not a kind a
+project adds. No other directory under `<paths.contractsDir>` holds a contract,
+and `QFAI-CONTRACT-034` reports a file in one. Evaluator axes are not a contract
+either: the review validation the QFAI CLI applies fixes them.
 
 Discussion UI/UX files are **non-normative** discovery / reference artifacts — not upstream SSOT (`.qfai/assistant/rule/drift-protocol.md#core-rule`). `/qfai-sdd` normalizes approved decisions into `<paths.contractsDir>/**`; downstream skills read contracts, not discussion UI/UX files. A contradiction between a pack and a contract is resolved in the contract, not by amending the pack.
 
@@ -42,20 +53,21 @@ Discussion UI/UX files are **non-normative** discovery / reference artifacts —
   not only where the attribute is written out — a framework that builds the
   attribute from a variable still writes the marker somewhere.
 - **Every entry under `screens` is a screen, once.** Each UI-bearing contract declares one full `UI-NNNN` ID and a nonempty `screens[]` list. Each screen has an ID and route, unique within its contract. The prototyping cycle covers all declared UI-bearing contract IDs; filenames do not select a legacy spec tier. `QFAI-CONTRACT-042` names malformed screen entries.
-- **A contract's ID comes from its directory.** `cli/` holds `CLI`
-  contracts, `api/` `API`, `db/` `DB` and `ui/` `UI`. The ID is `<KIND>-NNNN`.
+- **A contract's ID comes from its directory.** `api/` holds `API` contracts,
+  `db/` `DB` and `ui/` `UI`; the QFAI repository's own `cli/` holds `CLI`
+  contracts. The ID is `<KIND>-NNNN`.
   Its number is one more than the highest contract number of any kind, so
   `API-0002` and `DB-0002` cannot both exist. A number is never reused, even
   after its contract is removed.
 - **The file is named after the ID**: `<kind>-NNNN-<slug>.<ext>`, such as
-  `api/api-0002-orders.yaml` or `cli/cli-0001-checkout.md`.
+  `api/api-0002-orders.yaml` or `db/db-0003-orders.sql`.
 - **The ID is declared once, in the file.** A Markdown contract declares it in
   its H1: `# CLI-0001: <title>`. A YAML or SQL contract declares it on a
   `QFAI-CONTRACT-ID: API-0002` comment line at the top. A Markdown file under
   `api/`, `db/` or `ui/` is not a contract, whatever its H1 says:
   `QFAI-CONTRACT-034` reports it, and no other check counts it.
 - **Rules are numbered after their contract.** A business rule's ID is
-  `BR-<contract number>-NNNN`: `BR-0002-0001` is the first rule of `API-0002`.
+  `BR-<contract number>-NNNN`: `BR-0006-0001` is the first rule of `API-0006`.
   Only that contract declares it: under `x-qfai-rules` in YAML or JSON, on
   `-- Rule` and `-- Examples:` lines in SQL, and in the `## Business rules`
   table (`BR-ID`, `Statement`, `Examples`) of a Markdown contract.
@@ -120,12 +132,12 @@ The structural lane:
 | ------------------- | ----------------------------------------------------------------------------- | -------- |
 | `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-001`       | a dangerous statement (`DROP TABLE`, `TRUNCATE`, …)                           | warning  |
 
 `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.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md

@@ -9,6 +9,24 @@ default, not because the brand direction the discussion pack recorded asks for
 it. An instruction to avoid "a generic look" only swaps one default for another;
 naming the pattern is what works.
 
+## Contents
+
+- Using the list
+- Where the list stops
+- Color and background
+- Typography
+- Iconography and imagery
+- Surfaces
+- Components
+- Layout and composition
+- Placement
+- Motion and transitions
+- Copy in the UI
+- Information architecture and flow
+- States and accessibility
+- Implementation defaults
+- Displacement
+
 ## Using the list
 
 - **Writing root `DESIGN.md`.** Read the list before choosing a value. A value
@@ -34,8 +52,7 @@ naming the pattern is what works.
   are the rules. The entry is the form a breach of them takes on a generated
   screen.
 - The reviewer inside the prototyping loop does not apply this list. Root
-  `DESIGN.md` locks the brand values that reviewer sees
-  (`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`), so
+  `DESIGN.md` locks the brand values that reviewer sees, so
   a pattern is caught where the design direction is reviewed and where
   `DESIGN.md` is written. No entry here is a `lap-*` detection, and none blocks
   the loop.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/design-md-authoring.md

@@ -6,6 +6,13 @@ Applies only to a UI-bearing target — one whose classified surface set names
 `web`, `mobile`, `desktop` or `mixed`. A cli-only target has no root
 `DESIGN.md`.
 
+## Contents
+
+- Where the answers come from
+- Output mapping
+- Taking the values from the theme
+- When the file already exists
+
 ## Where the answers come from
 
 The interview is `/qfai-discussion`'s, and its record is the discussion pack
@@ -27,8 +34,7 @@ was translated. The competitor registry feeds brand and tokens; the component
 catalogue registry feeds screen structure, which is the contracts' business,
 not this file's.
 
-The questions behind those answers are in
-`../../qfai-discussion/references/design-dna-intake.md`.
+The questions behind those answers are in the design DNA intake reference.
 
 ## Output mapping
 
@@ -47,7 +53,7 @@ three intent fields, so those come first.
   identities to avoid, not conventions.
 - Adopted reference points → the **Do** subsection of `# Brand Philosophy`.
 - Brand archetype → `brand.archetype`. Allowed values are the 8-archetype
-  catalog in `design-md-brand-catalog.md`
+  catalog in the brand catalog
   (`minimal | bold | corporate | playful | organic | tech | elegant | casual`).
   Map the theme the pack records to the archetype that describes it; the
   Selection Guide's scoring is the fallback for a pack whose direction names
@@ -64,10 +70,10 @@ three intent fields, so those come first.
 - Visual decisions (color, typography, radius, shadow) → the `visual.*` token
   tree, **taken from the named theme's published values**. Schema and
   validation rules live in
-  `.qfai/assistant/skill/qfai-prototyping/references/design-md-spec.md`.
+  the DESIGN.md specification.
 
 For the schema (12 colors, 3 fonts, 4 radii, 3 shadows, 8 archetypes), read
-`qfai-prototyping/references/design-md-spec.md` and start from the sample at
+the DESIGN.md specification and start from the sample at
 `qfai-prototyping/templates/DESIGN.md.sample`.
 
 ## Taking the values from the theme

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/design-md-brand-catalog.md

@@ -3,10 +3,25 @@
 Reference catalog of 8 canonical brand archetypes. The SDD design stage picks one to fill the
 required `brand.archetype` field of the root `DESIGN.md`; each archetype supplies
 `aesthetic_properties` that become the starting tokens, and
-`design-md-authoring.md#output-mapping` defines where each value is written.
+the `Output mapping` section of the DESIGN.md authoring reference defines where
+each value is written.
 
 ---
 
+## Contents
+
+- Archetype: Minimal
+- Archetype: Bold
+- Archetype: Corporate
+- Archetype: Playful
+- Archetype: Organic
+- Archetype: Tech
+- Archetype: Elegant
+- Archetype: Casual
+- Patterns to avoid
+- Typeface candidates
+- Selection Guide
+
 ## Archetype: Minimal
 
 - representative_brand: Apple, Notion, Linear
@@ -91,7 +106,7 @@ required `brand.archetype` field of the root `DESIGN.md`; each archetype supplie
 
 ## Patterns to avoid
 
-`design-anti-patterns.md` lists the patterns that mark a design as generated,
+The design anti-patterns reference lists the patterns that mark a design as generated,
 by aspect, and the substitutes a model falls back to once one is banned. Read it
 before turning an archetype's defaults into `DESIGN.md` values. A value that
 produces a listed pattern stays only where the recorded brand direction asks for

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/requirements-decomposition.md

@@ -12,7 +12,7 @@ Use source-backed discussion requirements to write one connected, testable story
 
 1. Read the selected discussion pack's source registry, requirement index, open questions, decision record, and completed reviews. Each requirement must trace to a source ID. Record a missing source or unresolved product choice in `<paths.specsDir>/open-questions.md` and stop the dependent write.
 2. Reuse an existing policy, business flow, or story when it still expresses the requirement. Put a create, update, or retirement operation to the user, and record the approved one as a `Change request:` row of `<paths.specsDir>/decisions.md` naming the affected BF or US and `discussion-<id>#REQ-NNNN`.
-3. Write broad intent in `01_policy/` as criteria, then each observable process in `02_business-flow/business-flow-NNNN/business-flow.md`. Keep each flow's story index and three-file story directories beneath it. Every file takes its template's shape exactly, as `spec-traceability-rules.md#document-shapes` sets out.
+3. Write broad intent in `01_policy/` as criteria, then each observable process in `02_business-flow/business-flow-NNNN/business-flow.md`. Keep each flow's story index and three-file story directories beneath it. Every file takes its template's shape exactly, as the `Document shapes` section of the spec traceability rules sets out.
 4. Write one observable outcome per AC, as one named Gherkin `Scenario:` under its ID comment. Give each AC at least one concrete EX, and give each EX exactly one AC reference. Include normal, failure, boundary, and authorization paths relevant to the requirement.
 5. Once the examples exist, write independently falsifiable BRs in the contracts that enforce them. Each BR cites at least one full EX ID; every EX has a BR. A shared BR is defined once, in the contract that enforces it, and no other contract cites it.
 6. Derive test obligations from the completed BF → US → AC → EX ← BR graph. The SDD skill records those obligations; `/qfai-implement` writes the acceptance tests.
@@ -25,7 +25,7 @@ Use source-backed discussion requirements to write one connected, testable story
 - An EX is one concrete input and expected result for exactly one AC. Split examples whose paths can pass or fail independently.
 - A BR is one independently falsifiable constraint. If removing a clause leaves another complete rule, split it.
 
-Allocate each ID as the highest ID of its kind in its defined scope plus one, counting retired IDs. Never reuse an ID. The scopes and widths are in `sdd-triage.md#id-allocation`.
+Allocate each ID as the highest ID of its kind in its defined scope plus one, counting retired IDs. Never reuse an ID. The scopes and widths are in the `ID allocation` section of the triage reference.
 
 ## Ambiguity