qfai 2.1.1 → 2.2.0

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

@@ -22,6 +22,7 @@ naming the pattern is what works.
 - Placement
 - Motion and transitions
 - Copy in the UI
+- Copy that adds no meaning
 - Information architecture and flow
 - States and accessibility
 - Implementation defaults
@@ -51,11 +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, 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
 
@@ -269,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

@@ -25,9 +25,10 @@ this flow's provenance names:
 | `uiux/00_index.md`, `uiux/40_screen_contracts.md` | the screen-level sidecars                     |
 
 `01_Context.md#Design Direction` is the decision the user made: the adopted
-theme, what departs from it, and what stays ordinary. A UI-bearing pack that
-records none leaves the brand unchosen — stop and ask rather than pick one,
-which is the same rule an imported specification gets.
+theme, what departs from it, and what stays ordinary. For initial authoring of
+a missing file, a UI-bearing pack that records no design direction leaves the
+brand unchosen — stop and ask rather than pick one, which is the same rule an
+imported specification gets.
 
 Each registry entry carries what was adopted, what was rejected, and how it
 was translated. The competitor registry feeds brand and tokens; the component
@@ -116,7 +117,19 @@ to touch a colour has nothing to be consistent with.
 
 ## When the file already exists
 
-`npx qfai init` seeds the sample at the project root and never overwrites it,
-and a project may have authored its own. Write only when the file is missing.
-An existing file is validated as it stands, except that an unreplaced sample
-is refused.
+`npx qfai init` writes no root `DESIGN.md`; the sample is shipped only as a
+skill template. A root file that exists was authored by `common-design-md` or
+copied from that template on purpose, and a project may have authored its own.
+Write a missing file from the recorded direction. Repair an existing file only when SDD triage names its exact path
+and the requested change, and a new WIP change request authorizes both. Apply
+only the authorized change; preserve existing brand and tokens unless their
+change is authorized and supported by recorded direction or named theme
+values. Record the source of each changed value and leave unrelated content
+unchanged. Stop without writing a value neither source supplies. Without that
+authorization, validate the existing file without an overwrite; an inherited
+DONE row authorizes no new change. An unreplaced sample is refused.
+
+For an existing valid file, validation and authorized repairs that preserve
+its brand and tokens require no new brand selection. An authorized brand or
+token change still needs recorded direction or named theme values for each
+changed value; without either source, stop without writing the change.

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

@@ -25,6 +25,14 @@ 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.
 
+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

@@ -4,10 +4,35 @@ Use this sequence for /qfai-sdd. The shipped templates under ../templates/spec/
 
 ## 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
 

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

@@ -56,7 +56,7 @@ Follow the cycle the `sdd-cycle` step sets out.
 - Every affected BF passed npx qfai validate --profile sdd --fail-on error --flow BF-NNNN with error=0.
 - Every document written passes its document schema. A failure was fixed by reshaping the document, not by adding to it.
 - The log path and result for each BF are in the SDD report.
-- Each entered design-writing stage has a pre-draft grilling checkpoint before its first mutation. The final report lists each decision a checkpoint adopted; unanswered critical decisions remain open and block completion.
+- Each entered design-writing stage has a pre-draft grilling checkpoint before its first mutation. A checkpoint that finds no open decision holds no session. The final report lists each decision a checkpoint adopted; unanswered critical decisions remain open and block completion.
 - Reviewers are independent of the authors, and every finding of the one review is fixed or answered.
 - Rejected options remain excluded, or a documented reopening decision exists.
 - Remaining risks and next actions are explicit in the SDD report.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-pre-draft-grilling.md

@@ -1,6 +1,9 @@
 # Pre-draft Grilling
 
-Before an SDD stage makes a design decision, the session agent gathers the stage's open decisions into one frontier and settles them in a delegated grilling session under `.qfai/assistant/rule/review-convergence.md#agent-to-agent-grilling-must`, using the `qfai-grilling` method. It asks the user each critical decision the frontier holds.
+Before an SDD stage makes a design decision, the session agent gathers the stage's open decisions into one frontier.
+When the frontier holds a design decision the repository cannot settle, the agent settles the frontier in a delegated grilling session under `.qfai/assistant/rule/review-convergence.md#agent-to-agent-grilling-must`, using the `qfai-grilling` method. It asks the user each critical decision the frontier holds.
+
+When the request, the story tree, the contracts and the recorded decisions already settle every decision of the stage, the frontier is empty. Then no session is held and no griller starts. The stage writes what is settled, and its final report lists no adopted decision for the checkpoint.
 
 ## Checkpoints
 

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

@@ -38,7 +38,7 @@ Do not use a sibling's in-flight findings to hold or clear the current flow. Rec
 
 ## Review and evidence
 
-- A pre-draft grilling checkpoint ran before the first write of every design-writing stage entered, and each critical decision it held was put to the user.
+- A pre-draft grilling checkpoint ran before the first write of every design-writing stage entered. It held a grilling session only where it found a decision the repository cannot settle, and each critical decision it held was put to the user.
 - The final report lists each decision a checkpoint adopted, with its reason.
 - Reviewers are independent of authors, and every finding of the one review is fixed or answered under `.qfai/assistant/rule/review-convergence.md`, with no re-review.
 - Evidence records the source, changed IDs and files, contract executability, commands, reviewer verdicts, rejected options excluded, and remaining risks.

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

@@ -7,6 +7,8 @@ Triage selects the smallest story-tree change that answers each incoming require
 - Inputs
 - Operation choice
 - Decision and question rows
+- Published decision prefix recovery
+- Merge-added identical decision copy recovery
 - Approval and no-question mode
 - Retiring an EX, AC or BR
 - ID allocation
@@ -34,7 +36,9 @@ 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, 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.
+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, and remove a row only as a proven surplus copy under the merge-added
+identical decision copy 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.
@@ -58,6 +62,69 @@ 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.
+
+## Merge-added identical decision copy recovery
+
+When a merge left a second byte-identical copy of an inherited decision and the
+duplicate-ID check rejects it, read
+`.qfai/assistant/rule/drift-protocol.md#merge-added-identical-decision-copy-recovery`.
+That rule defines the lineage, the raw-row proof and the stop conditions.
+Approval of the generic protocol alone authorizes no target; append a separate
+new target-specific change request using `templates/change-request.md`.
+
+The request names the exact path, the ID, the bad merge, both parents, the
+common ancestor, the base and its comparison ancestor, each occurrence's
+location, the raw SHA-256 including the line ending and the retain/remove
+mapping. Fresh evidence, reviewed independently after the request is appended,
+fixes the actual write HEAD, the complete preimage and replacement hashes and
+the current authority. Immediately before writing, recheck refs, path,
+authority, counts, mapping and bytes; stale or changed proof stops the
+recovery. Remove only the mapped surplus copies. Keep one original and every
+other row, reference and byte. Open-question rows, rows that differ in any cell,
+padding or line ending, and surplus the base already holds stay excluded.
+Duplicate, drift and Status rules apply as before. The result is no whole-target
+PASS, and the request stays WIP while any named action or required check is
+unfinished. Rollback restores the recorded preimage only while the file still
+equals the replacement; 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. A request from the user in the session that names the operation and its effect is the approval, and no second question is asked.
@@ -81,7 +148,7 @@ A story-tree or contract file changes only on the user's approval:
    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; the merge-added identical decision copy recovery above removes only surplus copies and keeps the original.
 Only a row this stage appended changes its Status.
 
 ## Retiring an EX, AC or BR
@@ -104,12 +171,74 @@ Read all IDs of the kind in the relevant scope, including IDs named by retiremen
 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.
 
+### 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 of the old ID in the same commit.
+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.
 
@@ -118,7 +247,33 @@ 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.
+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
 

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

@@ -89,14 +89,26 @@ The table holds no rule. A behaviour a layer must show is a BR in the contract t
 
 Use highest existing number plus one in the scope. Count IDs named in retired-item decisions, so deletion never frees an ID. Empty scopes begin at 0001 or, for AC and EX tails, 01. Directory names match their BF and US IDs. Do not add a CLI allocator.
 
+AC/EX tails remain two digits with upper bound 99. Before planned additions,
+compare requested additions with the retired-inclusive remaining 99-H. Stop an
+over-capacity batch before partial declarations. For an approved capacity-only
+sibling or actual move, apply the owning stage's capacity preflight and complete
+map before writing; no larger ID or new product outcome is a substitute for the
+required scope.
+
 Constraint IDs are the exception. `TC-NN`, `OC-NN` and `BC-NN` in constraint.md are positional: each section numbers its rows from 01 in table order. No other document cites one, so a removed row closes the gap and the rows after it are renumbered. `npx qfai validate` reports a constraint ID that is not its row's place.
 
-Moving a story to another flow changes its US ID and every child AC and EX ID. Update all indexes, contract citations, and decision references in the same change. Record the old IDs as retired so they cannot be issued again.
+Moving a story to another flow changes its US ID and every child AC and EX ID
+under its existing approval path. Preserve case meanings and assertions through
+the complete fixed-source map, update approved active indexes, contract citations
+and counted test references. Record the old IDs as retired in a new approved
+record so they cannot be issued again. Inherited DEC ID, Content and Approach
+cells and their old-ID references stay historical and unchanged.
 
 ## Edge rules
 
 1. business-flows.md cites each actual BF. Each business-flow.md states its BF in its H1, gives its purpose, and draws its main path as exactly one Mermaid flowchart or sequenceDiagram under `## Flow`.
-2. user-stories.md cites each US under that flow. A user story declares its US in its H1. Its parent BF is the directory it sits in, and no line of the file restates it. Keep each observable outcome in its own story.
+2. user-stories.md cites each US under that flow. A user story declares its US in its H1. Its parent BF is the directory it sits in, and no line of the file restates it. Keep each observable outcome in its own story, except the explicitly approved same-BF, same-actor-goal capacity-only partition above.
 3. 02_Acceptance-Criteria.md states each AC under that US as an `# AC-NNNN-NNNN-NN` comment followed by exactly one Gherkin `Scenario:`.
 4. Each EX row in 03_Example.md has exactly one AC-Ref. It names an AC in that story. Every AC has at least one EX.
 5. Each BR lives in an enforcing contract and cites one or more full EX IDs that already exist. Every EX is cited by at least one BR. Several BRs may cite an EX, and one BR may cite several EXs.

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

@@ -11,6 +11,7 @@ The flows a UI contract serves are the flows whose examples its rules cite; the
 - `elements[].label` is inspection-target text
 - `data-qfai` marker convention
 - Prototype metadata
+- Purposeful copy: `supplements` and `structure`
 - Screen contract rules
 - Template
 - Typical failures
@@ -143,6 +144,142 @@ evidence records nothing against it — an entry is a note between the contract'
 author and whoever reviews the prototype. Follow the shape
 `templates/contracts/ui-contract.sample.yaml` shows.
 
+## Purposeful copy: `supplements` and `structure`
+
+A screen states the words it shows, so that implementation adds none the contract
+did not ask for and review can compare the rendered screen with what was agreed.
+The words are the screen `title` (its one heading), the labels of `elements` and
+`actions`, the group headings, and the supplements below. Two keys carry them,
+beside `primary_tasks`, `elements` and `actions`, which stay as they are.
+
+### `supplements` (required)
+
+Every text the screen shows beyond its `title`, group headings and labels: a
+sentence under a field, a notice, an empty-state message, a disclosure, the result
+of a save or a send, the instruction after a failure, the consequence of an action
+that cannot be undone. Each is an entry with exactly these keys, all non-empty:
+
+| Key    | Holds                                                                                     |
+| ------ | ----------------------------------------------------------------------------------------- |
+| `id`   | stable key, unique in the screen                                                          |
+| `near` | the `id` of the element, action or structure group the text sits with                     |
+| `when` | the state it shows in: `default`, `empty`, `loading`, `error` or `success`                |
+| `text` | the words as displayed                                                                    |
+| `why`  | what the user could not know or do without it, and why a label or structure is not enough |
+
+`supplements: []` says the screen shows none. Most screens need few, and a screen
+need not have any. Two kinds of text are not supplements: the message of a field
+rule is owned by the `validations` of its element, and data the product shows or
+the user types is not copy the contract authors. A field message that says more
+than its rule does is a supplement with `when: error`.
+
+The list is the whole inventory in both directions. Text the screen shows that is
+not listed is excess. A listed text the screen does not show is an unmet need, so
+a necessary condition, cost, destination, result, recovery step or consequence
+that is written here cannot be dropped by a later tidy-up; removing it is a
+change to the contract, which goes back to `/qfai-sdd`.
+
+Write `why` for the point of decision. "Explains the Save button" is a reason to
+delete the text. "After the click the user cannot see where the draft went" is a
+reason to keep it.
+
+### `structure` (optional)
+
+The groups the screen is read in, in reading order. Each is an entry with exactly
+`id`, `tasks`, `members` and, when the group shows a heading, `heading`:
+
+| Key       | Holds                                                              |
+| --------- | ------------------------------------------------------------------ |
+| `id`      | stable key, unique in the screen                                   |
+| `tasks`   | the `primary_tasks[].id` values the group serves, at least one     |
+| `members` | the `elements[].id` and `actions[].id` values it holds, in order   |
+| `heading` | the displayed heading; leave the key out when the group shows none |
+
+An id belongs to one group, and an element or action may be left out of every
+group. `structure` is optional only for a screen that shows no heading beyond its
+`title`. A screen that shows any other heading, at any level, has one group with a
+`heading` for each, so a screen with several `h2` headings writes `structure`.
+Leaving the key out says the screen shows no such heading; it never says the
+screen may show one without a group. A group needs a task and a member, so the
+heading must head something the user reads or acts on: declare the table or list
+that shows data as an element, and the group holds it. A heading over prose or
+supplements alone has neither a task nor a member, and does not belong on the
+screen. `npx qfai validate` does not check this, so the
+reviewer compares the rendered headings with the groups. A group heading is
+not the screen title: a second heading above or beside the real one repeats it.
+A group that serves no task does not belong on the screen; name the task it
+enables, or leave the heading and the group out.
+
+### Which key holds which text
+
+Every text the screen shows has one home. The table applies the definitions above
+to the text authors and reviewers most often disagree about:
+
+| Rendered text                                              | Home                                                                                            |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| The one page heading (`h1`)                                | `title`                                                                                         |
+| A heading over a group of elements or actions (`h2`, `h3`) | `structure[].heading` of that group                                                             |
+| A small line above or beside a heading (eyebrow, kicker)   | a supplement with `near` set to the group; it is not a heading and not a label                  |
+| The text of a field, button or other control               | `label` of that element or action                                                               |
+| Link text                                                  | `label` of a `navigate` action                                                                  |
+| A table column header                                      | recommended: `label` of an element declared for that column, as elements are the display fields |
+| A figure caption                                           | a supplement with `near` set to the element it describes                                        |
+| An item of a list the product writes (a fixed checklist)   | a supplement                                                                                    |
+| An item of a list made of data the product shows           | outside the contract: data is not copy the contract authors                                     |
+| Product or site-identity text (a name, a tagline)          | `label` when it is a link or control, otherwise a supplement                                    |
+| The message of a field rule                                | `validations` of that element                                                                   |
+
+Nothing is outside the contract merely because it repeats across screens. Text that
+repeats on every screen is listed on each, and when no `why` that names a decision
+can be written for it, the text is a candidate for removal from the screen rather
+than a reason to leave it unlisted.
+
+### A worked example
+
+The sample at `templates/contracts/ui-contract.sample.yaml` shows a complete
+screen. Its draft action reads "Save draft", and no paragraph says what Save draft
+does. What the label cannot say is declared instead: `Saved to Drafts` after the
+click, and `Not saved. Your entries are still here. Try again.` after a failure.
+The user learns where the draft went and what a failure means, and nothing is
+written twice.
+
+### What a necessary text looks like
+
+Subtraction removes text that adds no meaning. It never removes:
+
+- a condition, cost, storage or transmission destination, or the result of an
+  action that is not visible otherwise (a demo-data notice that is true and
+  shown where the user decides is one of these);
+- error recovery, and the consequence of an action that cannot be undone;
+- labels, accessible names, roles and states.
+
+Moving such text into a tooltip or a placeholder does not keep it. A word or
+character count never approves or rejects a screen; a count is an observation
+a finding may cite.
+
+### What validate checks
+
+`QFAI-CONTRACT-043` reports `supplements` absent, a key that is not a list, an
+entry that is not a mapping, a missing, empty or extra key, a `when` outside the
+five states, and a repeated `id`; the same for `structure` when it is written.
+`QFAI-CONTRACT-044` reports a `members`, `tasks` or `near` that names an id
+the screen does not declare, and an element or action in two groups.
+`QFAI-CONTRACT-045` warns when a group heading is the screen title, or a
+supplement's text is the title, a group heading, the label of what it sits near, or
+another supplement's text near the same target in the same state; case, spacing and
+closing punctuation do not make a text different. Whether a sentence is needed is
+judged against the task by the reviewer; validate compares ids and exact wording
+only.
+
+A contract written before these keys was valid without them. Add
+`supplements` to each screen: `supplements: []` is the answer for a screen that
+shows nothing beyond its title and labels. Keep `structure` out while the screen
+shows no heading beyond its title; the first such heading needs its group.
+
+Two contracts that state the same screen `id` each hold their own `supplements`
+and `structure`; the project-wide screen list compares `title`, `route` and
+`primary_tasks` only.
+
 ## Screen contract rules
 
 `screens[].elements[]` are the display fields:
@@ -185,6 +322,13 @@ Render the element with that marker, or remove the marker from the contract.
 **A label does not match.** Update the contract label, then the rendered text or
 marker mapping. Updating one side leaves the two out of step.
 
+**`QFAI-CONTRACT-043` names a screen with no `supplements`.** Add `supplements: []`
+if the screen shows no text beyond its title, group headings and labels, or list each
+text with its `near`, `when`, `text` and `why`.
+
+**`QFAI-CONTRACT-045` warns that a supplement repeats a label.** Delete the supplement,
+or word it so it tells the user something the label does not.
+
 **The discussion pack already has screen contracts, so this looks redundant.**
 It is not. A discussion pack is discovery output and is non-normative; the
 downstream skills and every validate lane read `<paths.contractsDir>/ui/*.yaml`.
@@ -207,4 +351,6 @@ For a UI-bearing visual flow, the root `DESIGN.md` is authored and validated by
 - [ ] Every UI-bearing contract has one full declared ID, at least one screen, and a matching `contracts.md` row.
 - [ ] Screen IDs, routes, primary tasks, labels, markers, and actions are stable and testable.
 - [ ] Every declared action has an observable effect, including relevant failure states.
+- [ ] Every screen declares `supplements` (`[]` when none), each with the reason the text is needed, and its `structure` names every heading beyond the title.
+- [ ] No supplement restates a label, heading or action the screen already shows, and none is development commentary.
 - [ ] Prototyping coverage uses full contract IDs and the current cycle-0 fields.