qfai 2.1.0 → 2.1.2

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.
@@ -77,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.
@@ -95,7 +119,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 +140,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,22 @@
 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
+- Purposeful copy: `supplements` and `structure`
+- 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
@@ -128,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:
@@ -170,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`.
@@ -185,11 +312,13 @@ 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
 
 - [ ] 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,13 +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 (restated in
-`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`)
-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

@@ -9,7 +9,44 @@ 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`, 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/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/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/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,13 @@ 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.
+
 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

@@ -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,14 +24,15 @@ 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:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`
@@ -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

@@ -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`
@@ -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.