qfai 2.1.1 → 2.1.2

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,110 @@ 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. Without `structure` the screen shows no heading beyond its `title`, so a
+heading that appears on the rendered screen has a group here. 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.
+
+### 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 until a group
+heading is wanted.
+
+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 +290,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 +319,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.

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

@@ -15,33 +15,6 @@ A cli-only target has no root `DESIGN.md`; it still normalizes
 `/qfai-prototyping` records its handoff in
 `.qfai/prototype/final/handoff.json`. SDD does not author it.
 
-## Removed yaml contracts (permanent)
-
-The legacy per-aspect brand yaml contracts have been **removed**. The
-brand SSOT is now root `DESIGN.md` only, authored by `common-design-md`.
-Do not regenerate or reintroduce these files. Their content is subsumed by
-`DESIGN.md`:
-
-- brand archetype / voice / audience → `DESIGN.md` `brand` + `audience` +
-  `# Brand Philosophy` body.
-- negative references / things-to-avoid →
-  `audience.do_not_look_like` and the **Don't** subsection of
-  `# Brand Philosophy`.
-- color / typography / spacing / radius / shadow tokens →
-  `DESIGN.md` `visual.*` token tree.
-
-The following contracts MUST NOT be generated (the corresponding
-concepts do not exist in the current prototyping skill):
-
-- `evaluation-rubric.yaml` — evaluation axes are global constants; no
-  per-project rubric.
-- `evaluator-calibration.yaml` — calibration is the ordinal scale plus
-  a 200–500 word prose critique authored at review time.
-- `absorption-policy.yaml` — absorption / harvest concepts are not
-  used.
-- `selected-direction.yaml` — winner selection is not used; the latest
-  accepted iteration is always the artifact.
-
 ## Sidecar mapping
 
 The remaining UI-bearing sidecar maps to its contract as follows:
@@ -50,12 +23,14 @@ 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
-and are no longer authored as sidecar files.
+QFAI CLI applies.
 
 ## Normalization Rules
 
 - Preserve source IDs where available.
+- Normalize the sidecar's notes on displayed text into the screen's `supplements`
+  and `structure`, as the UI contract guide shapes them. Notes for the author or
+  the reviewer are not displayed text and are not copied into either key.
 - Convert prose into machine-readable arrays or objects.
 - Reject placeholder text instead of copying it into contracts.
 - Frame negative references in `audience.do_not_look_like` as

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

@@ -11,5 +11,42 @@ Record a change request as one row in `<paths.specsDir>/decisions.md`. The row h
 - 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, 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. 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.
+- After appending, change only `Status`, apart from the drift protocol's
+  explicit branch-added decision renumbering or published decision prefix
+  recovery. Keep inherited ID, Content and Approach fixed, and never delete a
+  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.
+
+## Published decision prefix recovery
+
+Use the same four-cell row only after actual approval covers this specific
+recovery. Read `.qfai/assistant/rule/drift-protocol.md#published-decision-prefix-recovery`
+for eligibility, byte boundaries, pre-write checks and stop conditions. Generic
+protocol approval and a diagnostic suggestion do not authorize a target.
+
+- Content names the target's repository-relative file and the unique target
+  DEC ID. Approach records the published source commit, fixed base and unique
+  common ancestor, with evidence the target is absent from the latter two and
+  the source commit is a current-HEAD ancestor.
+- Evidence names actual supporting files. Grounds records the recovery reason,
+  actual approval authority, old and new SHA-256 Approach digests, and the exact
+  approved `- Evidence: <actual file references> - Grounds: ` prefix, including
+  its trailing space. Use actual references in place of the placeholder.
+- The old digest matches the raw published source cell; the new digest matches
+  the prefix plus the complete original Approach. State the single-line valid
+  UTF-8 cell boundary: exclude only delimiter pipes and exactly one ASCII
+  padding space at each end. Decode no escapes and trim or normalize nothing.
+- State that original ordered, nonempty Residual risk and Rollback items are
+  valid. Preserve ID, Content, Status, the full original suffix and every other
+  row. Record the immediate pre-write uniqueness, unchanged-cell and old-digest
+  checks, and the required existing validation without an exemption.
+- Residual risk states the remaining observation and concurrency limits.
+  Rollback removes only the recorded prefix when the current new digest still
+  matches; otherwise it preserves the row and stops. Removal restores the
+  original validation failure. Do not reset, amend or force push.
+
+Inherited records, open-question rows, unavailable provenance, ambiguous byte
+boundaries, duplicate IDs, stale digests and any unapproved change stop recovery.
+Do not fill approval or execution fields with assumed answers or planned results.

package/assets/init/.qfai/assistant/skill/qfai-sdd/templates/contracts/ui-contract.sample.yaml

@@ -19,6 +19,8 @@ prototype:
       purpose: customer id field on the order create form
 screens:
   - id: order_create
+    # The one heading of the screen. A heading beyond it is a group heading
+    # under `structure`.
     title: Create Order
     route: /orders/new
     # primary_tasks: at least one entry required per screen (QFAI-AUD-001).
@@ -36,6 +38,9 @@ screens:
         label: Correct a rejected field
         acceptance: the field-level error clears and submit re-enables
       - id: t3
+        label: Keep the order for later
+        acceptance: the order appears under /orders/drafts and the form keeps what was entered
+      - id: t4
         label: Abandon the draft
         acceptance: navigating away discards the draft and returns to /orders
     elements:
@@ -51,13 +56,55 @@ screens:
         required: true
         validations:
           - must be non-empty
-      - id: submit_button
-        label: Submit
-        type: button
-        required: true
-        validations: []
     actions:
       - id: submit_order
         label: Submit order
         kind: submit
         effect: navigates to /orders and shows the created row
+      - id: save_draft
+        label: Save draft
+        kind: submit
+        effect: stores the order under /orders/drafts, stays on the form and keeps what was entered
+      - id: discard_draft
+        label: Discard draft
+        kind: navigate
+        effect: navigates to /orders without storing the order
+    # structure (optional): the groups the screen is read in, in reading order.
+    # `tasks` are primary_tasks ids, `members` are elements/actions ids, and
+    # `heading` is the displayed heading of the group; leave it out for a group
+    # that shows none. Without `structure` the screen shows no heading beyond
+    # its title. An id belongs to one group.
+    structure:
+      - id: g_customer
+        heading: Customer
+        tasks: [t1, t2]
+        members: [customer_id_input]
+      - id: g_items
+        heading: Items
+        tasks: [t1, t2]
+        members: [item_code_input]
+      - id: g_commit
+        tasks: [t1, t3, t4]
+        members: [submit_order, save_draft, discard_draft]
+    # supplements (required): every text the screen shows beyond its title,
+    # group headings and labels. Field validation messages are the exception;
+    # they belong to the element's `validations`. `[]` says the screen shows
+    # none. `near` is an elements/actions/structure id, `when` is one of
+    # default, empty, loading, error, success, and `why` says what the user
+    # could not know or do without the text, and why a label or the structure
+    # cannot carry it.
+    #
+    # There is no supplement that restates what "Save draft" does: the label
+    # says it. What the label cannot say is where the draft went and what a
+    # failed save means, so those two are declared.
+    supplements:
+      - id: sp_draft_saved
+        near: save_draft
+        when: success
+        text: Saved to Drafts
+        why: After the click the user cannot see where the order went; the label names the action, not the place its result is kept.
+      - id: sp_draft_not_saved
+        near: save_draft
+        when: error
+        text: Not saved. Your entries are still here. Try again.
+        why: A failed save leaves the user unsure whether work was lost and what to do; the label says nothing about failure.

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

@@ -13,6 +13,9 @@ 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 `\|`.
 
+Use this form for every new row. A passing validation result does not prove
+that every decision row follows it.
+
 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.

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-triage
-title: QFAI Triage (Requests that end without a change)
-description: "Use when invoked by name or handed a QFAI work order for a request that ends without a change to the project: a question to answer, a duplicate, missing information, a request to split, automated reports, a security report to take in, or an operation only a person can run."
+title: QFAI Triage (Requests that end without a tracked change)
+description: "Use when invoked by name or handed a QFAI work order for a request that ends without a tracked change: a question, a duplicate, missing information, a split, automated reports, a security report, an operation only a person can run, or authorized cleanup of current-task temporary directories."
 argument-hint: "<the request, as it was reported>"
 allowed-tools: [Read, Glob, Grep, Write, Bash, TodoWrite, Task, Agent]
 roles:
@@ -24,12 +24,13 @@ steps:
   - triage-cluster
   - triage-security-intake
   - triage-handoff
+  - triage-owned-cleanup
   - triage-close
 requires: []
 mode: execution-focused
 ---
 
-## /qfai-triage - Requests that end without a change
+## /qfai-triage - Requests that end without a tracked change
 
 [DRIFT-PROTOCOL:REQUIRED]
 
@@ -39,7 +40,10 @@ first.
 
 This skill answers, closes, splits or hands over a request, and changes no
 file git tracks. Work the request needs is recorded as a follow-up request,
-never done here.
+never done here except the exact current-task temporary cleanup that
+`triage-owned-cleanup` permits. That step rechecks existing user authority and
+repository-local scope before any deletion. No other triage step executes an
+operation, and `triage-handoff` still waits for the person's reported result.
 
 ## Inputs
 
@@ -59,17 +63,18 @@ Invoked by name, run the steps in this order, as
 states: read `.qfai/assistant/step/<name>/STEP.md` for the current step only,
 run it, then move to the next.
 
-| Step                     | What it does                                                   | Skipped when                                                                     |
-| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `triage-dedupe`          | Finds the same or a successor item, and links it               | The request neither may repeat an existing item nor rests on a premise that aged |
-| `triage-request-info`    | Asks for the facts the request is missing                      | The request states every fact its handling needs                                 |
-| `triage-investigate`     | Reads internals, history and outside facts to find the answer  | The documents and code as they stand answer the question                         |
-| `triage-answer`          | Answers, citing what shows the answer                          | The request asks no question                                                     |
-| `triage-decompose`       | Splits the request into child requests with their dependencies | The request is one piece of work                                                 |
-| `triage-cluster`         | Groups automated reports by signature                          | The request is not a set of automated reports                                    |
-| `triage-security-intake` | Takes a vulnerability report in privately                      | The request reports no exploitable weakness                                      |
-| `triage-handoff`         | Gives a person the steps of an operation only they can run     | The request needs no operation that only a person can run                        |
-| `triage-close`           | Records the outcome and each follow-up, and closes             | Only `triage-security-intake` ran: the fix follows it, so the request stays open |
+| Step                     | What it does                                                               | Skipped when                                                                     |
+| ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `triage-dedupe`          | Finds the same or a successor item, and links it                           | The request neither may repeat an existing item nor rests on a premise that aged |
+| `triage-request-info`    | Asks for the facts the request is missing                                  | The request states every fact its handling needs                                 |
+| `triage-investigate`     | Reads internals, history and outside facts to find the answer              | The documents and code as they stand answer the question                         |
+| `triage-answer`          | Answers, citing what shows the answer                                      | The request asks no question                                                     |
+| `triage-decompose`       | Splits the request into child requests with their dependencies             | The request is one piece of work                                                 |
+| `triage-cluster`         | Groups automated reports by signature                                      | The request is not a set of automated reports                                    |
+| `triage-security-intake` | Takes a vulnerability report in privately                                  | The request reports no exploitable weakness                                      |
+| `triage-handoff`         | Gives a person the steps of an operation only they can run                 | The request needs no operation that only a person can run                        |
+| `triage-owned-cleanup`   | Removes authorized current-task temporary directories and verifies absence | The request is not the specific repository-local cleanup the step permits        |
+| `triage-close`           | Records the outcome and each follow-up, and closes                         | Only `triage-security-intake` ran: the fix follows it, so the request stays open |
 
 Invoked by name, the skill ends at this stage. It starts no other stage and
 routes no follow-up: a request to carry a follow-up out goes to `qfai-run`.
@@ -94,9 +99,13 @@ Follow `.qfai/assistant/rule/shared-skill-operating-baseline.md#completion-contr
 find changed when it started.
 
 The report states the outcome `triage-close` recorded and lists each follow-up
-request. It never says a change is done. It ends with a question listing the
-next actions, as `.agents/rules/user-questions.md` § 6 sets out; under a
-no-question mode, list them in the report instead.
+request. It never says a tracked change is done. `cleaned` says only that the
+named temporary targets were removed and their absence and unchanged tracked
+contents and index were verified; unfinished cleanup cannot use it.
+Ask for the next action only when
+proceeding requires the user's answer, as `.agents/rules/user-questions.md`
+§ 6 sets out. A closure-only report needs no question. Under a no-question mode,
+list any remaining actions instead.
 
 ## Default Autopilot Policy
 
@@ -105,6 +114,7 @@ no-question mode, list them in the report instead.
 
 project_memory:
 
-- Triage changes no tracked file; work it finds is a follow-up request.
+- Triage changes no tracked file; only `triage-owned-cleanup` executes its bounded cleanup.
+- Other work it finds is a follow-up request.
 - A follow-up is recorded, never routed inside the run that found it.
 - A security report stays private until the fix is ready to disclose.

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

@@ -106,10 +106,11 @@ Questions about this skill's own inputs or settings stay in its own output for
 the user to answer. This skill does not write `open-questions.md`.
 
 The completion message lists each decision the agents adopted, with its
-reason and any disagreeing position. None of them is put as a question. The
-message then ends with a question listing every next action, as
-`.agents/rules/user-questions.md` § 6 sets out; under a no-question mode it lists
-them in the report instead:
+reason and any disagreeing position. None of them is put as a question. Ask for
+the next action only when proceeding requires the user's answer, as
+`.agents/rules/user-questions.md` § 6 sets out. A completion-only report needs
+no question. Under a no-question mode, list any remaining actions instead.
+The applicable next actions are:
 
 - Proceed (recommended): create a PR on your hosting platform, with the
   verification report as its description.

package/assets/init/.qfai/assistant/skill/qfai-verify/references/context-load.md

@@ -1,9 +1,12 @@
 # Step 0 — Load context
 
+`<paths.specsDir>` and `<paths.contractsDir>` are the directories `qfai.config.yaml` sets.
+
 1. Read relevant **project policy** (if present):
-   - `.qfai/spec/01_policy/objective.md`
-   - `.qfai/spec/01_policy/initiative.md`
-   - `.qfai/spec/03_contract/tech.md`
+   - `<paths.specsDir>/01_policy/objective.md`
+   - `<paths.specsDir>/01_policy/initiative.md`
+   - `<paths.specsDir>/01_policy/principle.md`
+   - `<paths.contractsDir>/tech.md`
    - `.qfai/assistant/rule/agent-selection.md`. From
      `.qfai/assistant/rule/agent-selection.md` read the acting role's entry
      when a role needs one, not the whole file
@@ -14,9 +17,9 @@
    - `.qfai/assistant/rule/workflow.md` (or equivalent)
 
 3. Read existing artifacts for the current work item (if present):
-   - `.qfai/spec/02_business-flow/`
-   - `.qfai/spec/03_contract/`
-   - `.qfai/spec/decisions.md`
+   - `<paths.specsDir>/02_business-flow/`
+   - `<paths.contractsDir>/`
+   - `<paths.specsDir>/decisions.md`
 
    Do not use discussion-pack artifacts as verification inputs. Verify reads normalized specs, contracts, tests and code only.
 

package/assets/init/.qfai/assistant/skill/qfai-verify/references/verify-output-contract.md

@@ -1,10 +1,18 @@
 # Verify Output Contract — `.qfai/report/verify.json`
 
-`/qfai-verify` MUST write `.qfai/report/verify.json` at the end of the run. This file is the machine-readable verdict; the stage report is the human-readable account. No `qfai` command reads it, so an absent `verify.json` does not fail `npx qfai validate`.
+## Contents
+
+- Verdict file
+- Per-gate results
+- CI-only checks
+- Scope
+- Example and rules
 
-Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.qfai/report/` directory if absent — it is the same directory `validate.json` is written to.
+## Verdict file
 
-`.qfai/output/verify.json` is the legacy location, history for projects created before the move. Never write there.
+`/qfai-verify` MUST write `.qfai/report/verify.json` at the end of the run. This file is the machine-readable verdict; the stage report is the human-readable account. No `qfai` command reads it, so an absent `verify.json` does not fail `npx qfai validate`.
+
+Canonical path: `.qfai/report/verify.json`. Create the `.qfai/report/` directory if absent — it is the same directory `validate.json` is written to.
 
 | Field        | Type             | Required | Meaning                                                                                                                                                 |
 | ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -15,8 +23,17 @@ Canonical path: `.qfai/report/verify.json` (NOT `.qfai/output/`). Create the `.q
 | `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.                                                                              |
 
+When the scope includes acceptance scaffolds or unfinished BF/AC acceptance
+bodies, an optional `summary` stays one or two short sentences naming remaining
+work, its owner or UNASSIGNED, and the detailed human-report reference. The
+five-field detail belongs in `verify-repo-gate`'s `## Report` section, not a
+new JSON field or table inside `summary`. Empty-body exemptions, verdicts and
+completion rules stay unchanged.
+
 `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"`.
 
+## Per-gate results
+
 Each entry of `gates` is `{ name, status, command }`, plus these optional fields:
 
 | Field      | Type   | Meaning                                                                                                                           |
@@ -27,11 +44,51 @@ Each entry of `gates` is `{ name, status, command }`, plus these optional fields
 | `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.
+## CI-only checks
+
+A gate the project's Standard commands declare `CI only: <check name>` is
+recorded `"DELEGATED"` with its `check` and `ci` for the candidate being evaluated.
+`check` names the actual CI check and `ci` its observed state.
+A `"red"` check makes the top-level `status` `"FAIL"` for that candidate.
+A `"pending"` one does not, and `summary` names it. A runnable local gate is
+never delegated to avoid running it. Retain an observed FAIL or
+UNRUN; neither becomes PASS or DELEGATED because a verification commit is wanted.
+
+A `"PASS"` verdict with pending delegated checks supports only the existing
+verification-commit allowance under a user instruction or project policy
+covering that commit and its paths. It does not establish formal completion or
+permission to push, create a pull request or merge. Every nondelegated gate
+must pass. A delegated red check stops transport of the same unchanged candidate.
+Explicit CI-only delegation covering a transport commit may instead carry actual
+changes addressing that failure through the existing planned fix into a new
+candidate, while HEAD still names the failed commit. Preserve the prior head,
+check, run and observed result as FAIL; never relabel that evidence pending.
+Report the actual fix and, after committing, the new head and resume condition.
+The new candidate remains unverified until its own CI results are observed.
+
+The stage report records the target, current head, run ID or URL when available,
+check, actual outcome and counts, blocker and resume condition. No run yet means
+no result; invent neither. `ci: "green"` needs actual passing evidence for that
+same target and head. Missing or mismatched evidence remains pending. Formal
+completion or merge waits for every required check to pass on the current head.
+Keep this evidence in the stage report and `summary`; add no verdict fields or states.
 
 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:
+Keep the full CI receipt in the stage report, as
+`.qfai/assistant/step/common-gate-run/STEP.md#ci-evidence` requires. A branch
+overview or a confirmed closed cleanup SKIP does not replace actual verification
+or turn it into a behavioral PASS. Preserve failures for the current head;
+unknown identity or purpose remains unverified. The receipt adds no fields or
+states to this contract.
+
+## Scope
+
+`scope` is a closed enum. Write the gate set this invocation covers through
+execution or an explicitly declared matching CI-only check. Delegation never
+claims that the profile already ran; its check must perform the required scan
+and profile. A whole-repository scope still requires full validation. Write the
+one that matches the stage you were invoked for:
 
 | `scope`       | Written by                                                          | validate profile                                |
 | ------------- | ------------------------------------------------------------------- | ----------------------------------------------- |
@@ -42,6 +99,8 @@ A gate that fails identically on the base, or did not run and is not delegated,
 There is no `implement` value: the enum is closed at these three, and a run after
 `/qfai-implement` is recorded as `full`.
 
+## Example and rules
+
 Minimal conforming example for the prototyping gate:
 
 ```json
@@ -56,6 +115,12 @@ Minimal conforming example for the prototyping gate:
 
 Rules:
 
-- Never write `"status": "PASS"` without the command outputs that justify it. A `FAIL` verdict is a legitimate output — the gate downstream is supposed to stop.
-- Never write a `scope` you did not actually run. Writing `"prototyping"` after a `full` run is a false verdict, not a workaround — and the reverse is just as wrong: a `--profile verify` run is `scope: "full"`, not `scope: "atdd"`, because `atdd` means the ATDD gate set only.
+- A PASS gate needs actual command output or matching CI evidence. The existing
+  top-level pending-DELEGATED allowance supports only the covered verification
+  commit described above. A `FAIL` verdict is a legitimate output; downstream
+  work stops as its gate requires.
+- Never write a `scope` this invocation does not cover by execution or its
+  declared matching CI-only check. Writing `"prototyping"` for a `full` gate set
+  is a false verdict, not a workaround. A `--profile verify` gate is
+  `scope: "full"`, not `scope: "atdd"`; `atdd` covers the ATDD gate set only.
 - Do not add a `version` / `schemaVersion` field. No reader validates one, and a second version series in a distributed artifact is exactly what the distributed-surface rule forbids: the npm package version is the only version this surface has.