qfai 2.1.0 → 2.1.1

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

@@ -1,6 +1,6 @@
 # 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
 
@@ -11,7 +11,7 @@ Use this sequence for /qfai-sdd. The shipped templates under ../templates/spec/
 
 ## 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 +22,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 +37,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,16 @@
 
 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
+- 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 +24,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 +33,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. 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.
@@ -49,7 +60,7 @@ in Approach. It takes effect only at DONE; it never exempts descendant items.
 
 ## 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,7 +71,10 @@ 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
@@ -70,12 +84,40 @@ A story-tree or contract file changes only on the user's approval:
 A row present before the stage started keeps its ID, Content and Approach.
 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.
 
+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 of the old ID in the same commit.
+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.
+
 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.
 
 ## Completion of triage

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

@@ -2,6 +2,18 @@
 
 The story tree makes business intent concrete before a rule is attached to an enforcing contract. The required chain is BF → US → AC → EX ← BR. A policy, index, or decision row cites an ID; it does not declare a second copy of the item.
 
+## Contents
+
+- Layout and ownership
+- Document shapes
+- Architecture
+- Identifier scopes
+- Edge rules
+- Contract forms and index
+- Test-layer handoff
+- Decision provenance and drift
+- Gate
+
 ## Layout and ownership
 
 - <paths.specsDir>/01_policy/ owns objective, initiative, principles, constraints, and glossary.
@@ -48,7 +60,7 @@ A layer is a group of modules with a dependency direction. An upper layer may us
 
 The section holds two things, in this order:
 
-1. One `mermaid` block, `flowchart TD`, with one node per layer and one `Upper --> Lower` edge per dependency, and nothing else. A node is an ID, or an ID with its label in square brackets when the layer's name is not an ID.
+1. One `mermaid` block, `flowchart TD`, with one node per layer and one `Upper --> Lower` edge per dependency, and nothing else. A node is an ID, or an ID with its label in square brackets and double quotes, as in `Upper["Domain (core)"]`, when the layer's name is not an ID.
 2. One table of Layer, Responsibility and Depends on, one row per layer, from the uppermost layer to the lowermost. Depends on names only layers in rows below its own, comma-separated, or `-` for none. Peers at the same height may come in any order.
 
 `npx qfai validate` reports a Depends on that names a layer not below its row, and any node or edge the diagram and the table do not share.
@@ -95,7 +107,7 @@ Do not substitute an AC for an EX in a BR citation. The examples are concrete ev
 
 ## Contract forms and index
 
-YAML and JSON contracts put rules under x-qfai-rules. SQL contracts use -- Rule and -- Examples: lines. Markdown contracts use a ## Business rules table. Each rule includes ID, statement, and full example IDs. Follow contract-artifact-rules.md and the contract's paired template for syntax.
+YAML and JSON contracts put rules under x-qfai-rules. SQL contracts use -- Rule and -- Examples: lines. Markdown contracts use a ## Business rules table. Each rule includes ID, statement, and full example IDs. Follow the contract artifact rules and the contract's paired template for syntax.
 
 Each contract file written has a contracts.md row in the same change. The index cites the file and its ID; it is not another rule definition. Confirm that a contract can realize each persisted attribute in its cited AC and EX directly or through a stated join. Reconcile paired contracts' state and error vocabularies.
 
@@ -116,7 +128,7 @@ a later decision explicitly reopens it.
 
 A decisions.md row's Approach takes the form stated at the top of templates/spec/decisions.md.
 
-Use .qfai/assistant/rule/change-classification.md for Primary and Tags and references/requirements-decomposition.md for turning source requirements into concrete outcomes. Apply .qfai/assistant/rule/drift-protocol.md before accepting a direction that conflicts with a previous decision. Do not silently promote discussion material into a governing spec.
+Use .qfai/assistant/rule/change-classification.md for Primary and Tags and the requirements decomposition procedure for turning source requirements into concrete outcomes. Apply .qfai/assistant/rule/drift-protocol.md before accepting a direction that conflicts with a previous decision. Do not silently promote discussion material into a governing spec.
 
 ## Gate
 

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/ui-contract-guide.md

@@ -3,6 +3,21 @@
 Write UI contracts under `<paths.contractsDir>/ui/**/*.{yaml,yml}`, each named `ui-NNNN-<slug>.yaml` after its ID. A UI-bearing contract declares exactly one full `# QFAI-CONTRACT-ID: UI-NNNN` and a nonempty `screens[]` list. Add its row to `<paths.contractsDir>/contracts.md` in the same change.
 The flows a UI contract serves are the flows whose examples its rules cite; the file name does not select them.
 
+## Contents
+
+- `screens[].primary_tasks` shape
+- Recommended ceiling: at most 7
+- `elements[].id` naming policy
+- `elements[].label` is inspection-target text
+- `data-qfai` marker convention
+- Prototype metadata
+- Screen contract rules
+- Template
+- Typical failures
+- Prototyping coverage
+- Root DESIGN.md
+- Review checklist
+
 ## `screens[].primary_tasks` shape
 
 Each entry in `screens[]` must carry a `primary_tasks:` slot. Each
@@ -185,7 +200,7 @@ A malformed UI contract or an empty screen list is an authoring failure. Fix the
 
 ## Root DESIGN.md
 
-For a UI-bearing visual flow, the root `DESIGN.md` is authored and validated by `.qfai/assistant/step/common-design-md/STEP.md`. Normalize approved screen decisions with `ui-design-contract-normalization.md`. A CLI-only flow without a visual secondary surface does not need one.
+For a UI-bearing visual flow, the root `DESIGN.md` is authored and validated by `.qfai/assistant/step/common-design-md/STEP.md`. Normalize approved screen decisions with the UI design contract normalization reference. A CLI-only flow without a visual secondary surface does not need one.
 
 ## Review checklist
 

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/ui-design-contract-normalization.md

@@ -50,8 +50,7 @@ The remaining UI-bearing sidecar maps to its contract as follows:
 
 Project-specific anti-pattern notes live in `audience.do_not_look_like`
 of `DESIGN.md`. Evaluator axes are fixed by the review validation the
-QFAI CLI applies (restated in
-`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`)
+QFAI CLI applies
 and are no longer authored as sidecar files.
 
 ## Normalization Rules

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

@@ -9,7 +9,7 @@ Record a change request as one row in `<paths.specsDir>/decisions.md`. The row h
 - Allocate `DEC-NNNN` as the highest decision ID in this tree plus one. Never reuse an ID, including a retired one.
 - Begin `Content` with `Change request:` and name every repository-relative path the decision can change; an ID there authorizes nothing. A path mentioned only in a discussion or an alternative does not authorize an edit.
 - Describe the actual contradiction and its source in `Content`. In `Approach`, state the proposed correction, affected work, and the gate that proves it is applied, inside the form stated at the top of `templates/spec/decisions.md`. Keep both cells concise enough to review as a table row.
-- Append the row only once the user approves the change, at `WIP`, and record in `Approach` who approved it, when, and the option chosen. Move it to `DONE` only after the owner rerun, affected artifacts, and validation evidence are complete. Use `SUPERSEDED (by DEC-NNNN)` when a later decision replaces the row.
+- Append the row only once the user approves the change, at `WIP`, and record in `Approach` who approved it, when, and the option chosen. Move it to `DONE` only after the owner rerun, affected artifacts, and validation evidence are complete. Use `SUPERSEDED (by DEC-NNNN)` when a later decision replaces the row, and `PARTLY SUPERSEDED (by DEC-NNNN)` when it replaces only part of it.
 - Append a declined change at `REJECTED`, recording in `Approach` who declined it and when. It authorizes no edit.
-- After appending, change only `Status`. Never rewrite `ID`, `Content`, or `Approach`, and never delete the row. If its scope or proposed correction changes, append a new decision row and supersede the old one.
+- After appending, change only `Status`. Never rewrite `ID`, `Content`, or `Approach`, and never delete the row. A row the base holds at DONE authorizes nothing at any Status, so a later change needs a new row. If its scope or proposed correction changes, append a new decision row and supersede the old one.
 - Keep open questions in `<paths.specsDir>/open-questions.md`. Use the same four columns there, with `OQ-NNNN` IDs and the statuses permitted by that template.

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

@@ -1,9 +1,9 @@
--- QFAI-CONTRACT-ID: DB-0002
+-- QFAI-CONTRACT-ID: DB-0006
 -- Replace the sample IDs: the contract takes the next contract number, its
 -- rules are numbered under it, and its examples come from the story tree.
 -- Purpose: Sample order draft persistence contract
 -- Depends on: -
--- Rule BR-0002-0001: An order draft stores a nonempty customer ID.
+-- Rule BR-0006-0001: An order draft stores a nonempty customer ID.
 -- Examples: EX-0001-0001-02
 --   Apply-order dependencies as a comma-separated list of DB-* ids, or `-`
 --   when there are none. List only what must be applied BEFORE this file.

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/spec/03_contract/cli/cli-NNNN-title.md

@@ -1,4 +1,4 @@
-# CLI-0001: Example command
+# CLI-0006: Example command
 
 ## Ownership boundary
 
@@ -8,4 +8,4 @@
 
 | BR-ID        | Statement    | Examples        |
 | ------------ | ------------ | --------------- |
-| BR-0001-0001 | Example rule | EX-0001-0001-01 |
+| BR-0006-0001 | Example rule | EX-0001-0001-01 |

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/spec/03_contract/tech.md

@@ -19,7 +19,7 @@
 
 ```mermaid
 flowchart TD
-  Upper[<upper layer>] --> Lower[<lower layer>]
+  Upper["<upper layer>"] --> Lower["<lower layer>"]
 ```
 
 | Layer         | Responsibility                      | Depends on    |

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/spec/decisions.md

@@ -13,6 +13,10 @@ No item is empty, and only the last two may take `none — <reason>`. What a
 kind of row must state in its Approach, such as a change request's proposed
 correction, goes inside these items. Write a `|` inside a cell as `\|`.
 
+A row that records a spec change following from an earlier approval may name
+that earlier decision by its ID in `Grounds:`, in place of a new answer from
+the user. Its `Evidence:` still lists what supports the change.
+
 A stage that does not own this file records its decisions in its own final
 report, with the same four items under the same rules.
 -->

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

@@ -31,7 +31,7 @@ mode: execution-focused
 
 ## /qfai-triage - Requests that end without a change
 
-[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-verify/SKILL.md

@@ -32,7 +32,7 @@ mode: evidence-focused
 
 ## /qfai-verify — Quality Gates and Evidence
 
-[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-verify/references/verify-output-contract.md

@@ -6,17 +6,31 @@ Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.q
 
 `.qfai/output/verify.json` is the legacy location, history for projects created before the move. Never write there.
 
-| Field        | Type             | Required | Meaning                                                                                                  |
-| ------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------- |
-| `status`     | string           | yes      | `"PASS"` when every gate in scope passed; `"FAIL"` otherwise. Only `"PASS"` satisfies a downstream gate. |
-| `scope`      | string           | yes      | Which stage's gate set this run covers. See the enum below.                                              |
-| `flowId`     | string           | no       | The business flow this run targeted, when scoped to one (e.g. `"BF-0001"`).                              |
-| `recordedAt` | ISO-8601 string  | no       | When the run completed.                                                                                  |
-| `summary`    | string           | no       | One or two sentences an operator can read without opening the stage report.                              |
-| `gates`      | array of objects | no       | Per-gate results: `{ name, status, command }`. Advisory; no reader gates on it today.                    |
+| Field        | Type             | Required | Meaning                                                                                                                                                 |
+| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`     | string           | yes      | `"PASS"` when every gate in scope passed, or is delegated to a CI check that is not red; `"FAIL"` otherwise. Only `"PASS"` satisfies a downstream gate. |
+| `scope`      | string           | yes      | Which stage's gate set this run covers. See the enum below.                                                                                             |
+| `flowId`     | string           | no       | The business flow this run targeted, when scoped to one (e.g. `"BF-0001"`).                                                                             |
+| `recordedAt` | ISO-8601 string  | no       | When the run completed.                                                                                                                                 |
+| `summary`    | string           | no       | One or two sentences an operator can read without opening the stage report.                                                                             |
+| `gates`      | array of objects | no       | Per-gate results: as set out below. Advisory; no reader gates on it today.                                                                              |
 
 `status` is a closed two-value enum: `"PASS"` / `"FAIL"`. There is no `"WARN"` — a run with only `warning` / `info` findings is `"PASS"` (waivers apply to those severities only). Any `error` finding makes it `"FAIL"`.
 
+Each entry of `gates` is `{ name, status, command }`, plus these optional fields:
+
+| Field      | Type   | Meaning                                                                                                                           |
+| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `status`   | string | `"PASS"`, `"FAIL"`, `"UNRUN"` or `"DELEGATED"`. `"UNRUN"` is a gate with no command, launcher or environment; it is never a pass. |
+| `baseline` | string | On a `"FAIL"`: `"same"` when the base commit fails identically, `"different"` when it does not, `"unrun"` when it cannot run.     |
+| `reason`   | string | On an `"UNRUN"` gate, or a `baseline` of `"unrun"`: what is missing.                                                              |
+| `check`    | string | On a `"DELEGATED"` gate: the CI check that runs it.                                                                               |
+| `ci`       | string | On a `"DELEGATED"` gate: `"green"`, `"red"` or `"pending"`, the state of that check when the file is written.                     |
+
+A gate the project runs in CI only is recorded `"DELEGATED"` with its `check` and `ci`. A `"red"` check makes the top-level `status` `"FAIL"`. A `"pending"` one does not, and `summary` names it, so a reader sees what the run left to CI. A gate that can run here is never delegated to avoid running it.
+
+A gate that fails identically on the base, or did not run and is not delegated, still makes the top-level `status` `"FAIL"`. The fields let a reader tell it from a failure the run caused.
+
 `scope` is a closed enum. Write the one that matches the stage you were invoked for:
 
 | `scope`       | Written by                                                          | validate profile                                |

package/assets/init/.qfai/assistant/skill/web-research/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: web-research
 title: "Web Research Pipeline"
-description: "8-stage web research pipeline with MCP integration, caching, and citation generation."
+description: "8-stage web research pipeline with MCP integration, caching, and citation generation. Use when asked to research a topic on the web and report the findings with cited sources."
 argument-hint: "[query] [--max-depth N] [--yolo]"
 allowed-tools: [Read, Glob, Bash, Write, Task, Agent, WebSearch, WebFetch]
 roles: [Researcher, Analyst, FactChecker]
@@ -16,7 +16,7 @@ QFAI Skill Body (SSOT)
 
 ## /web-research — Web Research Pipeline
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -38,14 +38,6 @@ baseline overlap, the baseline governs.
 - The orchestrator may write the research artifact itself, or give independent searches to sub-agents that run in parallel.
 - It never approves its own work.
 
-### Capability Probe
-
-- No additional overrides.
-
-### Delegation Failure (Hard Stop)
-
-- No additional overrides.
-
 ## Work Orders Summary
 
 Every major research artifact must include a `## Work Orders Summary` table.

package/assets/init/.qfai/assistant/step/common-design-md/STEP.md

@@ -27,12 +27,17 @@ for it.
   lists it: `01_Context.md#Design Direction`, the reference registries in
   `04_Sources.md`, and the `uiux/` sidecars. For an imported tree, the surface
   the import source names, or the user's answer.
+- The questions behind those answers:
+  `.qfai/assistant/skill/qfai-discussion/references/design-dna-intake.md`.
 - The schema and validation rules:
   `.qfai/assistant/skill/qfai-prototyping/references/design-md-spec.md`.
 - The archetype catalog:
   `.qfai/assistant/skill/qfai-sdd/references/design-md-brand-catalog.md`.
 - The starting sample:
   `.qfai/assistant/skill/qfai-prototyping/templates/DESIGN.md.sample`.
+- The patterns that mark a design as generated, and their displacement table:
+  `.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md`. Read it
+  for § Author and validate step 5.
 
 ## Author and validate
 
@@ -51,6 +56,12 @@ for it.
 4. **Parse and validate.** `parseDesignMd(text)` must succeed; pass its `data`
    to `validateDesignMd` and halt on any issue. Both are exported from the
    `qfai` package entry.
+5. **Check the finished file against the pattern list.** Review root
+   `DESIGN.md` against every aspect of
+   `.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md` and its
+   Displacement section. A token that prescribes a listed pattern fails unless
+   `01_Context.md#Design Direction` asks for it. Name the pattern in the
+   finding, replace the value, and check the file again.
 
 The retired per-aspect brand contracts are not regenerated; their content lives
 in `DESIGN.md`
@@ -77,7 +88,8 @@ it, edit it; the next iteration is built from it.
 Read first: the flow's classified surface set and root `DESIGN.md`. The step
 passes when the flow is not on a visual prototyping surface, or when root
 `DESIGN.md` exists, is not the unreplaced sample, and parses and validates with
-no issue. The pass names the surface set and the validation result.
+no issue and shows no listed pattern that the recorded direction does not ask
+for. The pass names the surface set and the validation result.
 
 ## Writes
 
@@ -87,5 +99,7 @@ no issue. The pass names the surface set and the validation result.
 
 ## Gate
 
-`DESIGN.md` parses and validates with no issue, and no value was written that
-the recorded direction or the named theme does not supply.
+`DESIGN.md` parses and validates with no issue, no value was written that
+the recorded direction or the named theme does not supply, and no token
+prescribes a pattern from `design-anti-patterns.md` that the recorded direction
+does not ask for. A reviewer fails the gate by naming the pattern.

package/assets/init/.qfai/assistant/step/common-gate-run/STEP.md

@@ -38,6 +38,9 @@ Neither is restated here.
    gate is the matching entry of the Standard commands section, used as
    written. An entry that is missing makes the gate UNRUN: record it and route
    the gap as the rule says; never substitute a command from another stack.
+   An entry written `CI only: <check name>` instead of a command is not run
+   here: record the gate DELEGATED with that check name, and read the check's
+   state from the pull request when one exists.
 3. **Run it** on the tree the stage will hand to its reviewer, in the
    environment the `Runtime` and `Platform` rows declare.
 4. **Report** in the stage report: the exact
@@ -66,12 +69,32 @@ Neither is restated here.
 
 ## Outcomes
 
-| Outcome | Means                                                              |
-| ------- | ------------------------------------------------------------------ |
-| `PASS`  | The command ran on the reviewed tree and exited 0 with zero errors |
-| `FAIL`  | The command ran and reported an error or a non-zero exit           |
-| `UNRUN` | No command, no launcher, or no environment to run it in            |
+| Outcome     | Means                                                              |
+| ----------- | ------------------------------------------------------------------ |
+| `PASS`      | The command ran on the reviewed tree and exited 0 with zero errors |
+| `FAIL`      | The command ran and reported an error or a non-zero exit           |
+| `UNRUN`     | No command, no launcher, or no environment to run it in            |
+| `DELEGATED` | The project runs the gate in CI only, by the check its entry names |
 
-Only `PASS` satisfies a gate. `FAIL` and `UNRUN` go in the stop report with the
-reason and the retry condition. Do not weaken a profile, lower `--fail-on`,
+Only `PASS` satisfies a gate here. A `DELEGATED` gate is satisfied by its CI
+check, which runs on the pull request: it is not a pass, and it is not a
+failure until that check is red. `FAIL` and `UNRUN` go in the stop report with
+the reason and the retry condition. Do not weaken a profile, lower `--fail-on`,
 waive an error or invent a result to reach `PASS`.
+
+## A failure that predates the change
+
+Before a failing gate is attributed to the change, run it again on the base
+commit: the revision the change branched from, in a clean checkout that holds
+none of the change. Build it the same way, so a failure that needs a build is
+not read from a stale one.
+
+| Base result                            | Record                                       |
+| -------------------------------------- | -------------------------------------------- |
+| The same failures                      | `FAIL`, baseline `same`: it predates the run |
+| Fewer, other or no failures            | `FAIL`, baseline `different`: the run's own  |
+| The gate cannot run on the base either | `FAIL`, baseline `unrun`, with the reason    |
+
+The comparison is between the failing tests or findings, not the exit code.
+The result stays `FAIL`; a baseline of `same` explains it and never turns it
+into a pass. The run did not cause it, so it is reported and not repaired.

package/assets/init/.qfai/assistant/step/discussion-uiux/STEP.md

@@ -26,7 +26,17 @@ The same as `discussion-pack`: this run's stage report holds the
 - `.qfai/assistant/skill/qfai-discussion/references/design-dna-intake.md`.
 - `.qfai/assistant/skill/qfai-discussion/references/ui_ux_best_practices.md`
   for the durable decision rules. Open only the `ui_ux/` appendix the current
-  task needs.
+  task needs:
+  - `.qfai/assistant/skill/qfai-discussion/references/ui_ux/platform_baselines.md`
+    for touch target sizes, breakpoint heuristics, platform navigation baselines,
+    and dark mode and cross-platform adaptation notes;
+  - `.qfai/assistant/skill/qfai-discussion/references/ui_ux/review_audit_playbook.md`
+    for heuristic review structure, anti-pattern checklists, screen-spec
+    documentation rules and audit guidance;
+  - `.qfai/assistant/skill/qfai-discussion/references/ui_ux/trend_scan_playbook.md`
+    for trend-scan category coverage, freshness and citation rules, and turning
+    references into local decisions without letting trends overwhelm
+    product-specific needs.
 - The templates under `.qfai/assistant/skill/qfai-discussion/templates/uiux/`.
 
 ## Writes

package/assets/init/.qfai/assistant/step/implement-dep-bump/STEP.md

@@ -38,6 +38,13 @@ advisory to clear.
    publishes to its own users as wide as the new version allows.
 6. Run the relevant suite.
 
+When the dependency is `qfai` itself, the package also wrote assistant files
+into the repository, so steps 5 and 6 are replaced by the upgrade procedure in
+the section "Keeping QFAI itself up to date" of `node_modules/qfai/README.md`:
+`init --force`, the retired files the release notes list, then `doctor` and
+`validate`. `init --force` replaces the skills and steps in use, so read the
+next step from disk after it runs.
+
 ## What it writes
 
 - The manifest, the lockfile and any adapted call, listed in `changedFiles`.

package/assets/init/.qfai/assistant/step/implement-scaffold/STEP.md

@@ -16,9 +16,9 @@ the system's shape has settled.
 
 ## Reads
 
-- The active flow, one `BF-NNNN`. Inside a workflow run the work order's
-  `target` names it. A flow that cannot be resolved stops this step: report
-  the missing source.
+- The active flow, one `BF-NNNN`, which the invocation's BF argument or the
+  request names. A flow that cannot be resolved stops this step: report the
+  missing source.
 - The flow's stories and acceptance criteria under `paths.specsDir`. The
   default tree is `.qfai/spec/`.
 - `.qfai/assistant/rule/test-layers.md` for the layer each ID maps to.

package/assets/init/.qfai/assistant/step/implement-seam/STEP.md

@@ -20,7 +20,9 @@ waits until the acceptance stage has taken RED.
 
 - The acceptance result's seam request and the target test it names.
 - `.qfai/assistant/skill/qfai-implement/references/walking-skeleton.md` and
-  `.qfai/assistant/skill/qfai-implement/references/red-admissibility.md`.
+  `.qfai/assistant/skill/qfai-implement/references/red-admissibility.md`, and
+  `.qfai/assistant/skill/qfai-implement/references/red-not-observable.md` where
+  production already satisfies the example.
 - The commands of `common-gate-run`.
 
 ## Procedure

package/assets/init/.qfai/assistant/step/implement-tdd/STEP.md

@@ -134,7 +134,9 @@ writes, a passing technical gate, and the required user consent.
 ## Red, Green, Refactor
 
 For the selected EX, create or strengthen a test in a non-acceptance layer and
-annotate it `QFAI:EX-NNNN-NNNN-NN`. Preserve the BF E2E and AC integration
+annotate it `QFAI:EX-NNNN-NNNN-NN` on the comment line directly before its
+`it(`, `test(` or `describe(`, or the equivalent test declaration of another
+framework. Preserve the BF E2E and AC integration
 or API tests `implement-scaffold` wrote. Put the test where the observable
 behavior belongs. Use
 `.qfai/assistant/skill/qfai-implement/references/walking-skeleton.md` and