qfai 2.1.0 → 2.1.2

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,22 @@ 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`.
+- **Every screen states the text it shows.** A screen declares `supplements` (`[]` when it shows none) and may declare `structure`. `QFAI-CONTRACT-043` names a key that is absent or malformed, `QFAI-CONTRACT-044` an id the screen does not declare, and `QFAI-CONTRACT-045` a text shown twice.
+- **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 +133,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,25 @@ 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
+- Copy that adds no meaning
+- 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
@@ -33,12 +52,13 @@ naming the pattern is what works.
   flow_ and _States and accessibility_ do, `interface-clarity.md` and the spec
   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
-  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.
+- The reviewer inside the prototyping loop does not apply the sections about
+  identity. Root `DESIGN.md` locks the brand values that reviewer sees, so a
+  pattern there is caught where the design direction is reviewed and where
+  `DESIGN.md` is written. That reviewer does apply _Copy that adds no meaning_,
+  through the criterion on explanatory text, because those patterns are about
+  what the text tells the user, not about a brand. No entry here is a `lap-*`
+  detection.
 
 ## Color and background
 
@@ -252,6 +272,21 @@ naming the pattern is what works.
 - The screen shows technical detail nobody asked for, such as GPU status or
   average generation time.
 
+## Copy that adds no meaning
+
+These patterns are judged against the screen's tasks and the `supplements` its UI
+contract declares, in SDD, in implementation and in every surface review. A chosen
+visual direction does not exempt them. A disclosure about demo data, cost, storage
+or transmission that is true and shown where the user decides is not one of them:
+judge where it sits and what it lets the user do, not the word.
+
+- A second heading or a sentence repeats the main heading, an action label, a
+  state, or the content beside it.
+- A condition the user already knows is explained again where it adds nothing to
+  the decision being made.
+- Production copy carries a development instruction, implementation commentary,
+  or a demo note repeated on screen after screen.
+
 ## Information architecture and flow
 
 - Sections follow the stock order: hero, logos, three features, stats or

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,15 @@ 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`.
+A capacity-only sibling may represent the same actual actor goal within the
+same BF when requested AC or EX additions exceed the source story's remaining
+capacity. Prefer preserving published cases and IDs, and place only new,
+cohesive incoming cases under their own covering change request. Confirm
+retired-inclusive capacity and the owning approval before writing; this
+exception invents no new product outcome and grants no future creation or move
+permission.
+
+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
 

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

@@ -1,17 +1,42 @@
 # SDD Execution Playbook
 
-Use this sequence for /qfai-sdd. The shipped templates under ../templates/spec/ define each file's shape, and spec-traceability-rules.md#document-shapes states what a template cannot show.
+Use this sequence for /qfai-sdd. The shipped templates under ../templates/spec/ define each file's shape, and the `Document shapes` section of the spec traceability rules states what a template cannot show.
 
 ## Stage 0: source inventory
 
-1. Run npx qfai sdd preflight and read its selectedInputPath and source. Respect an explicitly selected discussion pack, including one older than the newest pack.
-2. Read the selected pack, completed reviews that target it, explicit user requirements, and the existing story tree. A pack is reference and provenance material. Disposition its applicable review advice in the SDD report, a decision row, or an open question. A pack discrepancy does not itself block SDD.
-3. Stop if there is no usable input source. Stop on an unresolved product decision that cannot safely be inferred; record the question in open-questions.md.
-4. If no discussion pack exists and an imported specification does, run npx qfai sdd preflight --import <path> with that file, which selects it as the source. An explicit user requirement is used as it is and named in the SDD report. Do not manufacture a discussion pack.
+1. Use the launcher established by
+   `.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory`.
+   Record its resolved package path and version in the SDD report. Check that
+   the installed Stage 0 instructions support the procedure being used.
+2. Run `npx qfai sdd preflight` and read its `selectedInputPath` and `source`.
+   Respect an explicitly selected discussion pack, including one older than the
+   newest pack.
+3. Read the selected pack, completed reviews that target it, explicit user
+   requirements, and the existing story tree. A pack is reference and provenance
+   material. Disposition its applicable review advice in the SDD report, a decision
+   row, or an open question. A pack discrepancy does not itself block SDD. For
+   the current request, read the existing purpose in
+   `<paths.specsDir>/01_policy/objective.md` and inspect related flows and stories.
+4. A missing discussion pack does not mean that specifications are missing. If
+   an existing readable specification is authoritative for this request, run
+   `npx qfai sdd preflight --import <path>` with that file. The fallback does
+   not replace a selected pack or bypass unsafe pack names, unreadable files,
+   invalid active pointers, config errors, or a mismatched tool.
+5. Use an explicit user requirement as supplied and name it in the SDD report.
+   Do not invent an import file from conversation. Without a file, CLI preflight
+   can remain blocked while SDD assesses that explicit requirement.
+6. Use `/qfai-discussion` only when no usable source exists; stop SDD until one
+   is available. Stop on an unresolved product decision that cannot safely be
+   inferred; record the question in `open-questions.md`. Do not manufacture or
+   regenerate a past discussion pack, or regenerate the existing purpose,
+   merely to clear preflight.
+7. Import-lite readiness identifies the input source. It does not establish
+   complete requirements or a validation PASS. Keep the existing purpose and
+   current request while updating only affected flow and story content.
 
 ## Stage 1: triage and decisions
 
-Follow sdd-triage.md. Classify each requirement against existing policy, flow, story, example, and contract content.
+Follow the triage reference. Classify each requirement against existing policy, flow, story, example, and contract content.
 Identify every affected flow. Put each approval-required operation to the user through the shared user-question
 protocol before a dependent write, and append its change request row to decisions.md once approved; record unresolved
 questions in open-questions.md. In --auto, ask nothing and stop dependent work. A declined change request is appended at REJECTED.
@@ -22,7 +47,7 @@ questions in open-questions.md. In --auto, ask nothing and stop dependent work.
    A constraint is a limit in plain words; its ID is its place in its section, so removing a row renumbers the rows after it.
    A layer boundary is a row of tech.md `## Architecture`, written from the technical decisions the pack records and, in an existing codebase, its module layout and import directions: what each layer does and the layers below it that it may import from.
    A layer is a group of modules whose dependencies point one way: down. The section draws the layers as one `flowchart TD`, then lists them in the table from the uppermost down, and the two name the same layers and edges.
-   Implementation places new code by that table and reviewers judge a change against it, as spec-traceability-rules.md#architecture states.
+   Implementation places new code by that table and reviewers judge a change against it, as the `Architecture` section of the spec traceability rules states.
 2. Write 02_business-flow/business-flows.md and the affected business-flow-NNNN/business-flow.md files. Each flow's `## Flow` section is exactly one Mermaid flowchart or sequenceDiagram.
 3. Allocate BF and US IDs from the highest existing ID in their scopes, counting retired IDs named in decisions rows. Add rows to the flow and story indexes.
 
@@ -37,12 +62,12 @@ questions in open-questions.md. In --auto, ask nothing and stop dependent work.
 
 1. Write the 03_contract/ view and each contract file from its paired template or contract-specific template. tech.md holds the stack, the runtime dependencies and, in its Standard commands section, the only quality-gate command definitions. It holds no BR.
 2. Put each BR inside the contract that enforces it, numbered `BR-<contract number>-NNNN`. Cite at least one EX already written. Every EX is cited by at least one BR. A shared rule has one authoritative definition, and no other contract cites it.
-3. Give each new contract the next contract number, declare its `<KIND>-NNNN` ID, name the file `<kind>-NNNN-<slug>.<ext>`, and add its row to contracts.md in the same change. Reconcile API and DB fields, state transitions, errors, and persisted attributes. Run the executable DB contract checks required by contract-artifact-rules.md.
+3. Give each new contract the next contract number, declare its `<KIND>-NNNN` ID, name the file `<kind>-NNNN-<slug>.<ext>`, and add its row to contracts.md in the same change. Reconcile API and DB fields, state transitions, errors, and persisted attributes. Run the executable DB contract checks required by the contract artifact rules.
 4. For a visual UI surface, the root DESIGN.md is written and validated by .qfai/assistant/step/common-design-md/STEP.md. A CLI-only surface does not require one.
 
 ## Concrete-abstract cycle
 
-When Stage 4 wrote or changed a BR Statement or Examples cell, run the cycle in concrete-abstract-cycle.md before the gate: a sub-agent that wrote none of the BRs raises findings against the tree, the session agent decides them, the adopted changes are applied, and the affected BRs are rewritten. At most two cycles run.
+When Stage 4 wrote or changed a BR Statement or Examples cell, run the concrete-abstract cycle before the gate: a sub-agent that wrote none of the BRs raises findings against the tree, the session agent decides them, the adopted changes are applied, and the affected BRs are rewritten. At most two cycles run.
 
 ## Stage 5: gate, review, and completion
 

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

@@ -1,6 +1,6 @@
 # SDD Phase Checklists
 
-Use these checkpoints with the ordered stages in sdd-execution-playbook.md. A checked item requires evidence in the story tree or the SDD report.
+Use these checkpoints with the ordered stages of the SDD steps. A checked item requires evidence in the story tree or the SDD report.
 
 ## Source and triage
 
@@ -14,7 +14,7 @@ Use these checkpoints with the ordered stages in sdd-execution-playbook.md. A ch
 
 ## Policy and business flow
 
-- Files in 01_policy/ and 02_business-flow/ were copied from paired templates and hold their headings and nothing else, as spec-traceability-rules.md#document-shapes sets out. No section records history.
+- Files in 01_policy/ and 02_business-flow/ were copied from paired templates and hold their headings and nothing else, as the `Document shapes` section of the spec traceability rules sets out. No section records history.
 - Objective, initiative, principle, and tech state each fact in one place. Gate commands occur only in tech.md Standard commands.
 - Every affected business-flow.md has exactly one Mermaid flowchart or sequenceDiagram in `## Flow`, and at least one alternate or exception path.
 - business-flows.md and user-stories.md index actual flows and stories with their assigned BF and US IDs and the titles in their H1s after the ID, word for word.
@@ -37,12 +37,12 @@ The one example a diagnosed missing test needs is appended by the implement stag
 - No contract names an implementation file.
 - Every written contract file has a contracts.md index row in the same change, with the columns `ID`, `Title`, `File`, `Depends On`, `Reconciled With` and `Purpose`.
 - Contract state, errors, and persisted attributes can realize the AC and EX outcomes, including required joins.
-- Changed DB contracts were applied to a scratch database and their declared write paths exercised as contract-artifact-rules.md requires. Record the command and result under Contract executability in the SDD repdence.
+- Changed DB contracts were applied to a scratch database and their declared write paths exercised as the contract artifact rules require. Record the command and result under Contract executability in the SDD repdence.
 - UI contracts follow the product's own root `DESIGN.md`; the sample design was not adopted.
 
 ## Concrete-abstract cycle
 
-Follow concrete-abstract-cycle.md.
+Follow the cycle the `sdd-cycle` step sets out.
 
 - A cycle ran when this invocation wrote or changed a BR Statement or Examples cell, and did not run otherwise or in an append stage.
 - The finder is a sub-agent that wrote none of the BRs it read. The session agent decided each finding that is not critical.

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

@@ -8,7 +8,7 @@ The gate checks the story-tree files against their shipped templates, the docume
 - Quality-gate commands occur only in the Standard commands section of <paths.contractsDir>/tech.md. Other files point there.
 - 02_business-flow/business-flows.md indexes real BF directories. Each business-flow.md has exactly one Mermaid flowchart or sequenceDiagram, in `## Flow`.
 - Each story directory holds exactly 01_User-story.md, 02_Acceptance-Criteria.md, and 03_Example.md.
-- The story tree was written from its paired templates under ../templates/spec/ and holds no heading, section, content kind or history they do not show, as spec-traceability-rules.md#document-shapes sets out.
+- The story tree was written from its paired templates under ../templates/spec/ and holds no heading, section, content kind or history they do not show, as the `Document shapes` section of the spec traceability rules sets out.
 - decisions.md and open-questions.md have four cells per row: ID, Content, Approach, Status. Existing rows changed only in Status.
 - Each change the user approved, retirement included, has its `Change request:` decision row recording who approved it, when, and the option chosen. No row records a decision the agent took. Unanswered critical decisions have open-question rows and prevent completion.
 
@@ -22,7 +22,7 @@ The gate checks the story-tree files against their shipped templates, the docume
 - Every contract file written has a contracts.md row from the same change.
 - Every persisted attribute and state named by an AC, EX, or BR is realizable by its contract directly or through a stated join.
 - Paired API and DB contracts agree on terminal states and error outcomes.
-- Each changed DB contract was applied to a scratch database and its declared write paths were exercised as contract-artifact-rules.md requires. The result appears under Contract executability in the SDD repdence.
+- Each changed DB contract was applied to a scratch database and its declared write paths were exercised as the contract artifact rules require. The result appears under Contract executability in the SDD repdence.
 - UI work uses a product-owned DESIGN.md that parses and validates; a sample design is not adopted.
 
 ## Flow validation

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

@@ -2,6 +2,17 @@
 
 Triage selects the smallest story-tree change that answers each incoming requirement. The source may be the discussion pack selected by preflight, an imported specification, or the user's explicit requirement. Treat the pack as reference material and resolve a conflict in an SDD-owned artifact.
 
+## Contents
+
+- Inputs
+- Operation choice
+- Decision and question rows
+- Published decision prefix recovery
+- Approval and no-question mode
+- Retiring an EX, AC or BR
+- ID allocation
+- Completion of triage
+
 ## Inputs
 
 - The selected source and its requirement IDs, if present.
@@ -14,7 +25,7 @@ Read the flow and story indexes plus concrete files. A subject match alone is in
 ## Operation choice
 
 Choose one primary operation for each affected BF or US. UPDATE is the default when the existing item keeps its identity
-and purpose. Its sub-operation is APPEND, MODIFY, or REMOVE. CREATE is used when no existing item represents the new
+and purpose. Its sub-operation is written UPDATE:APPEND, UPDATE:MODIFY, or UPDATE:REMOVE. CREATE is used when no existing item represents the new
 outcome. DELETE, SPLIT, MERGE, and SUPERSEDE change identity or scope and require explicit approval. UPDATE:REMOVE also
 requires approval. A supporting contract update is named in the same decision's Approach or in a linked row; it is not a
 second fictional flow.
@@ -23,7 +34,8 @@ Inspect the impact cascade: policy → BF → US → AC → EX → enforcing con
 
 ## Decision and question rows
 
-Use <paths.specsDir>/decisions.md and <paths.specsDir>/open-questions.md, each with exactly ID, Content, Approach, Status. Append a row; later only Status may change. Do not edit the first three cells or remove the row. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
+Use <paths.specsDir>/decisions.md and <paths.specsDir>/open-questions.md, each with exactly ID, Content, Approach, Status. Append a row; later only Status may change, including to `PARTLY SUPERSEDED (by DEC-NNNN)` when a later row narrows a decision without replacing it.
+Do not edit the first three cells or remove the row, except for explicit branch-added decision renumbering under ID allocation below or the bounded published decision prefix recovery below. Inherited rows retain those cells. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
 
 decisions.md records only what the user decided: each change request the user approved or declined,
 and each critical decision the user made. A row is appended once the user has decided what it records.
@@ -47,9 +59,48 @@ whose Content opens Unadjudicated:, at TODO until decided. A justified test exce
 decision Content with Test exception:, names the exact BF, AC, or EX it exempts, and puts the reason
 in Approach. It takes effect only at DONE; it never exempts descendant items.
 
+A test annotation may remain pending only when authority to change the
+specification covers that state and the test deferral is approved. Record the
+specification change in its own `Change request:` row. Record the deferral as a
+`Test exception:` decision naming the exact AC at DONE. Its Approach states
+the reason, untested scope, owner, next decision date and condition for restoring
+the annotation.
+
+DONE establishes the exception decision; it does not mean test completion.
+The existing info finding names the exempted AC and its decision without
+claiming test execution or coverage. The exception never exempts descendant EX
+obligations or authorizes changes to EX or BR scope. Do not silently substitute
+an EX or prose rewrite for an approved specification change. Use the next
+decision date for manual review; there is no automatic expiry and no automatic
+warning.
+
+When specification changes are forbidden or either authority is missing, first
+append an `Unadjudicated:` OQ at TODO. Name the affected IDs, expected versus
+actual behavior, implementation-change evidence, owner and required permission.
+Stop dependent AC, EX and BR edits; independent authorized work may continue.
+
+## Published decision prefix recovery
+
+When an approved request names a published malformed decision added by the
+branch, read `.qfai/assistant/rule/drift-protocol.md#published-decision-prefix-recovery`.
+That rule defines the source, byte boundaries, exact prefix and stop conditions.
+Approval of the generic protocol alone authorizes no target; append a separate
+new target-specific recovery change request using `templates/change-request.md`.
+
+Record the fixed base and unique common ancestor, absence of the target in both,
+the published source commit's ancestry, raw Approach digests and the exact
+approved prefix. Immediately before writing, recheck the unique current row,
+its original ID, Content and Status, and its old digest. Preserve every original
+Approach byte as the suffix and leave every other row unchanged. Recheck the
+existing form and validation; status or supersession clears no malformed form.
+Record actual results, including any stopped recovery, without claiming an
+automatic repair. Inherited records and open-question rows remain excluded.
+Rollback follows the recorded new-digest check and restores the original form
+failure; it never resets, amends or force pushes.
+
 ## Approval and no-question mode
 
-Use the shared user-question protocol for CREATE, DELETE, SPLIT, MERGE, SUPERSEDE, and UPDATE:REMOVE. Present the target and rationale. Do not self-approve.
+Use the shared user-question protocol for CREATE, DELETE, SPLIT, MERGE, SUPERSEDE, and UPDATE:REMOVE. Present the target and rationale. Do not self-approve. A request from the user in the session that names the operation and its effect is the approval, and no second question is asked.
 In --auto, ask no question: append one `open-questions.md` row per pending operation naming it and its target, at TODO with its Content opening Unadjudicated:; stop before the dependent writes, and report every pending operation with its target as open.
 Approval-free changes may proceed only if they do not depend on a pending operation.
 
@@ -60,23 +111,142 @@ Clarifications follow the constitution's question budget. Approval questions are
 A story-tree or contract file changes only on the user's approval:
 
 1. Show the user the files the stage would change and the proposed change, and
-   change nothing until the user answers.
+   change nothing until the user answers. A request from the user in the
+   session that names the change and its effect is that answer: the stage lists
+   the files in its announcement, asks no second question, and records the
+   request as the option chosen.
 2. On approval, write the change and append one `decisions.md` row whose Content
    opens `Change request:` and names every story-tree and contract file it
    changed, and `decisions.md` when it appended any other row. Its Approach
    records who approved it, when, and the label of the option chosen.
 3. Move the row to DONE once every change it names is written.
 
-A row present before the stage started keeps its ID, Content and Approach.
+A row present before the stage started keeps its ID, Content and Approach, except for explicit branch-added decision renumbering under ID allocation below or published decision prefix recovery above. Inherited rows keep those cells without exception.
 Only a row this stage appended changes its Status.
 
+## Retiring an EX, AC or BR
+
+A retirement touches every place the ID is written. Do all of them in one change:
+
+1. Get the user's approval of the UPDATE:REMOVE and append its `Change request:` decision row, whose Content names every retired ID.
+2. Delete the EX row from 03_Example.md, the AC scenario from 02_Acceptance-Criteria.md, or the BR row from its contract.
+3. Remove a retired EX from the Examples cell of every BR that cites it. A BR left with no example gets another example or is retired in the same row.
+4. Remove each QFAI:EX annotation of a retired EX from the tests, or point it at the example the test now proves.
+5. An AC left with no example gets one or is retired in the same row.
+6. Retiring an AC also retires each EX whose AC-Ref names it, or moves that EX to another AC of the story by changing its AC-Ref, then applies steps 3 and 4 to each EX retired. Remove each QFAI:AC annotation of the retired AC from the tests, or point it at the AC the test now proves.
+7. Never reuse a retired ID. The decision row keeps it counted.
+
+`npx qfai validate` reports what steps 3 to 6 left behind: a BR citing an unknown example (`QFAI-STORY-005`), a test annotation naming an undeclared ID (`QFAI-STORY-008`), and an AC with no example or an EX with an invalid AC-Ref (`QFAI-STORY-004`).
+
 ## ID allocation
 
-Read all IDs of the kind in the relevant scope, including IDs named by retirement rows. The next ID is the highest plus one. BF spans the project. US is inside its BF. AC and EX are inside their US.
+Read all IDs of the kind in the relevant scope, including IDs named by retirement rows. The next ID is the highest plus one. A project that also counts the IDs its open pull requests add takes the highest across the tree and those pull requests, so a gap above the tree's own highest is allowed. BF spans the project. US is inside its BF. AC and EX are inside their US.
 A contract number spans every contract kind, and a BR is numbered inside its contract. DEC and OQ each span their table.
 Empty numeric scopes begin at 0001, and AC/EX tails begin at 01. Do not reuse an ID because its file was removed or a row was rejected.
 
-A move to another BF changes the story's US ID and all child AC and EX IDs. Record the old IDs as retired, allocate new IDs in the destination scope, and update every citation before the move is complete.
+### Capacity before writing
+
+AC and EX tails stay two digits, from 01 through 99. Before writing a planned
+batch, report each affected kind and story, its high-water number H (0 when
+empty), remaining capacity 99-H and the number of requested additions. Count
+valid IDs in the tree and decisions, including retired IDs, plus observed
+published parallel heads and known reservations under the project's existing
+method. Name the fixed observation and what it did not cover. A snapshot
+reserves nothing and cannot cover unpublished concurrent work.
+
+If requested additions exceed 99-H, stop before any partial allocation or
+invalid declaration. Never fill gaps, reuse retired IDs or emit tail 100.
+An empty scope has capacity 99. H = 98 allows one addition at tail 99, not two;
+a retired 99 still exhausts the scope. Recheck newly published claims or
+collisions before publication.
+
+### Capacity partition
+
+Only additions exceeding an actual AC or EX scope's remaining 99-H qualify for
+a capacity-only story partition. Record the source story, affected kind, H,
+remainder and requested count first. Prefer leaving every published case and ID
+in place and putting a cohesive incoming group in a capacity-checked sibling
+under the same BF and actual actor goal. An in-force owning change request must
+explicitly approve this partition and its affected paths before writing.
+
+State the sibling's truthful cohesive scope and settle each criterion's owner;
+do not invent a new product outcome, duplicate an obligation or weaken it.
+A different actor, goal, flow or intended behavior needs its existing owning
+approval path. Additions that fit the original scope do not qualify. Missing
+authority, insufficient destination capacity or no truthful partition stops
+the dependent write. This prospective split places new overflow cases; moving
+an existing case also needs the complete map below. These instructions approve
+no future specific creation, move or split.
+
+### Actual moves and incoming collisions
+
+Before an approved actual AC/EX move or incoming collision repair, make a
+complete one-to-one map of:
+
+- the fixed source commit and declaration path;
+- each original BF/US/AC/EX identity and its case meaning;
+- destination story, AC/EX IDs and paths;
+- every affected active BR citation and counted adjacent test declaration;
+- unaffected cases and the input, expected outcome and executable assertion
+  each mapped case preserves.
+
+Check both scopes' retired-inclusive capacity. Each destination EX needs one
+existing destination AC; each AC needs an EX. Preserve every moved EX's
+owning BR link and counted test obligation. An ID change alone proves no
+coverage. Retire old moved IDs in a new approved record and never refill them.
+Inherited published DEC ID, Content and Approach cells and their old-ID
+references remain historical and unchanged; update only approved active
+references.
+
+Keep unaffected published cases and IDs. Identify same-number branch cases by
+fixed provenance and meaning, and change only the provably incoming item,
+without blanket replacement. Unknown ownership, ambiguous collisions,
+uncovered declarations, missing counted test links, changed assertions or an
+incomplete map stops the move without a completion claim. This is a manual
+approval and mapping procedure, not a relocation executor or mapping schema.
+
+Two branches can take the same next ID. When a merge leaves one ID on two items:
+
+1. The merge target's item keeps the ID. Renumber the incoming item, the one the merge brings in.
+2. Give it the next ID of its scope.
+   A renumbered BF or US takes its child IDs and its directory names with it, as a move to another BF does below.
+3. Change every citation belonging to the incoming item in the same commit.
+   For a decision, leave inherited references unchanged.
+4. State the old ID, the new ID and the renamed record's subject or path in the commit message.
+   A citation of the old ID elsewhere is then told apart from the item that kept it.
+
+A `decisions.md` or `open-questions.md` row already on the target keeps its ID, Content and Approach.
+A row the incoming branch added takes the next ID of its table.
+An ID that two merged records already share is not renumbered:
+ask the user for a change request row that states which record each citation meant.
+
+For a unique decision added by the incoming branch, repair its ID before merging:
+
+```text
+qfai sdd renumber-decision --from <old-DEC-ID> --to <new-DEC-ID> --base <local-ref>
+```
+
+The explicit base and HEAD must resolve locally and have one common ancestor
+that declares no source row. The base may already use that ID; the current
+tree must declare it only once. Choose an unused destination above both story trees'
+highest decision number, retired IDs included, within the four-digit grammar.
+The command reserves no number and chooses no final number automatically.
+
+Read the preview's fixed SHAs, IDs, relative paths and replacement lines or
+counts. It writes nothing and dumps no original lines or full files. Each
+invocation builds its own plan. Run with `--apply` to recheck that invocation's
+fixed refs and original bytes before writing; changed refs after a preview can
+produce a different plan. Preflight-only
+`--format`, `--fail-on`, `--import` and `--assume` are not accepted here.
+Only provably branch-added exact references change. Inherited references stay
+fixed; ambiguous ownership, dirty or linked candidates, unsupported text or
+failed reads stop the whole plan before writing. Unrelated links and dirty
+files are not candidates. Apply rechecks original bytes before each write.
+Rollback restores a changed file only if its bytes still match this invocation's
+replacement, preserving concurrent changes and naming any unrestored path.
+These checks guarantee neither atomic concurrency nor power-loss safety.
+
+A move to another BF changes the story's US ID and all child AC and EX IDs. It follows the existing approval path, not the same-BF capacity exception. Apply the complete map above to approved active citations and retire old IDs in a new approved record; inherited DEC cells and their historical references stay unchanged.
 
 ## Completion of triage