qfai 2.1.1 → 2.1.2

package/assets/init/.qfai/assistant/rule/references/asset-authoring.md

@@ -14,11 +14,13 @@ A `SKILL.md` states the contract and points at the file that carries the detail.
 - **One topic per file.** Do not replace an oversized `SKILL.md` with an oversized `references/everything.md`; that is the same problem one directory down. Split by topic and keep each file readable on its own — a reader who followed one pointer should not have to scan past three unrelated subjects to reach the one they came for.
 - **Every pointer resolves.** A line that moves detail out must name the file (and anchor, when the file covers more than one topic) so the reader is never left guessing where the rule went.
 
-A hard line ceiling backs this up: **800 lines per assistant asset file**, for every `.qfai/assistant/**/*.{md,yml,yaml}` file, counted as `content.split(/\r?\n/).length` — blank lines included. `npx qfai doctor` measures it and reports every file over the ceiling as `assets.lineBudget`. The ceiling is a backstop, not the rule: a file approaching it is a signal to move a section out, not
-to raise the number.
+A hard line ceiling backs this up: **500 lines per Markdown assistant asset file** and **800 lines per YAML assistant asset file**, for every `.qfai/assistant/**/*.{md,yml,yaml}` file, counted as `content.split(/\r?\n/).length` — blank lines included.
+`npx qfai doctor` measures it and reports every file over its ceiling as `assets.lineBudget`.
+The ceiling is a backstop, not the rule: a file approaching it is a signal to move a section out, not to raise the number.
 
-It was raised from 500 once, and on measurement rather than on the "this file is long" claim the number exists to refuse: three skill bodies had converged on that ceiling, and the changes in flight against one of them added 161 lines to a body already at 498 — eleven of them crossing the ceiling on their own. The detail those bodies carry is required to sit in the body rather than behind
-a pointer, so splitting could not absorb it. Converging on the limit was itself the signal — a body at the ceiling stops shedding topics and starts packing them into longer lines, and a line count cannot see that. Raise it again only against evidence of that kind.
+The Markdown ceiling is the limit an agent can follow in one file: it follows fewer instructions as its context grows, and follows those in the middle of a long file worst. A Markdown file has a `references/` home to move detail into. A YAML asset is parsed as data and cannot be split that way (see below), which is why its ceiling is higher.
+
+A body at its ceiling stops shedding topics and starts packing them into longer lines, and a line count cannot see that. The width ceiling below is what catches it.
 
 **A width ceiling makes the count honest: 400 characters per line.** A count of lines bounds reading cost only while a line is a roughly constant unit of reading, and packing broke that — one line in the shipped tree ran 9,104 characters against a median of 118, and cost the budget one unit. The two are read together, because each permits what the other refuses: width alone allows a thin
 file of a thousand short lines, and the count alone allows a packed one.

package/assets/init/.qfai/assistant/rule/references/worker-edit-boundary.md

@@ -0,0 +1,48 @@
+# Worker edits and work orders
+
+Read when assigning worker write paths or handling a refused edit.
+
+## Edit boundary
+
+The work order names the checkout assigned to the task by the host, the worker's
+write paths and the permitted edit method. Creating a Git worktree does not
+grant the host's tools permission to edit it. Even an assigned checkout can
+receive a refusal; verify the actual edit result rather than claiming access.
+
+If an edit is refused, stop writes to that target. Report the tool, working
+directory, target path and refusal text, omitting secrets. Return the owned
+paths and a reviewable diff that can be prepared within the worker's permitted
+area. Do not bypass the refusal through a shell, script or another tool.
+This does not forbid shell authoring where the host already permits it.
+
+The orchestrator checks the diff against the current files in its own permitted
+checkout before applying it. If that edit is refused too, leave the application
+pending and continue only independent work. Follow the existing worktree or
+shared-index mode in `.qfai/assistant/rule/workflow.md#concurrency-stage-independent-mandatory`
+when assigning writers and integrating their paths.
+
+## Work order template
+
+```text
+Task title: <short>
+Role: <sub-agent role>
+Review series: <reviewed artifact> + <reviewer role> + <replacement ordinal>   # review work orders only
+Goal: <what to decide/produce>
+Checkout: <absolute checkout assigned to this task by the host>
+Write paths: <exact owned paths, or none for a read-only task>
+Edit method: <host-permitted tool; worktree creation does not grant access>
+If an edit is refused: stop that target; return tool, cwd, target, refusal text, owned paths and a reviewable diff
+Inputs (refs):
+- <file/section>
+- .qfai/assistant/rule/drift-protocol.md#core-rule  <!-- the protected set, in front of the agent -->
+Constraints:
+- must: enforce Drift Protocol
+- must: follow applicable test-layer or validation policy
+- must_not: patch upstream artifacts directly; every upstream change requires
+  STOP + Change Request + owner rerun per .qfai/assistant/rule/drift-protocol.md
+Output format:
+- <headings / bullet schema>
+Time budget: none | <seconds>   # advisory: nothing stops at it. See .qfai/assistant/rule/stage-cost.md
+Elapsed line: end every message with `elapsed <seconds>s / <budget>s`, or `elapsed <seconds>s` when the budget is none
+Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
+```

package/assets/init/.qfai/assistant/rule/shared-skill-delegation-baseline.md

@@ -1,12 +1,12 @@
 # Shared Skill Delegation Baseline
 
-Use this document to keep SKILL bodies compact. Skill files should reference this baseline and only add role-, stage-, or gate-specific rules.
+Skills cite this baseline and add only role, stage or gate overrides.
 
 ## Sub-agent Delegation (MANDATORY)
 
-This section binds every skill and every step as written. A skill or step
-restates none of it and writes no placeholder stanza for a subsection it does
-not change; it states only an override, under the subsection it overrides.
+This section binds every skill and step. A skill or step repeats none of it
+and adds no placeholder for a subsection it does not change. State only an
+override, under the subsection it overrides.
 
 Delegation is optional. The session agent, called the orchestrator below, may
 author any artifact itself. It uses a sub-agent only for work that runs in
@@ -40,8 +40,15 @@ classified by the taxonomy below before any response.
 - A read-only agent never runs `git checkout` or `git switch` in a worktree it
   shares; it reads other revisions with `git show <rev>:<path>`. Each agent
   writes scratch files only under a path of its own.
-- Commit the change, or give each reviewer a fixed commit, before a review
-  starts, and leave the working tree alone until every review returns.
+- Give each reviewer a fixed commit. Leave the checkout alone until reviews
+  return. Only read-only fixed-SHA `git show` reviews permit clean switches.
+  Writers, local gates and reviews using live files or checkout-dependent
+  execution must finish first.
+
+### Worker edit boundary
+
+Before assigning write paths or handling a refused edit, read
+`.qfai/assistant/rule/references/worker-edit-boundary.md`.
 
 ### Capability Probe (MUST)
 
@@ -212,25 +219,8 @@ A blocking review that cannot be delegated because the agent budget is spent is
 
 ## Work order template
 
-```text
-Task title: <short>
-Role: <sub-agent role>
-Review series: <reviewed artifact> + <reviewer role> + <replacement ordinal>   # review work orders only
-Goal: <what to decide/produce>
-Inputs (refs):
-- <file/section>
-- .qfai/assistant/rule/drift-protocol.md#core-rule  <!-- the protected set, in front of the agent -->
-Constraints:
-- must: enforce Drift Protocol
-- must: follow applicable test-layer or validation policy
-- must_not: patch upstream artifacts directly; every upstream change requires
-  STOP + Change Request + owner rerun per .qfai/assistant/rule/drift-protocol.md
-Output format:
-- <headings / bullet schema>
-Time budget: none | <seconds>   # advisory: nothing stops at it. See .qfai/assistant/rule/stage-cost.md
-Elapsed line: end every message with `elapsed <seconds>s / <budget>s`, or `elapsed <seconds>s` when the budget is none
-Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
-```
+When preparing a delegation, use the template in
+`.qfai/assistant/rule/references/worker-edit-boundary.md#work-order-template`.
 
 ## Reviewer response template
 

package/assets/init/.qfai/assistant/rule/shared-skill-operating-baseline.md

@@ -196,9 +196,9 @@ the policy check. The mode is `workflow.mode` in `qfai.config.yaml`. An absent k
   needs the operator's answer.
 - A QFAI work order binds the stage to its target: one business flow, or one
   new-story slot. The stage works on that target and no other.
-- The stage result names the agent instance that did the work in
-  `actor: { agentInstance }`. The run records that instance as the work's
-  author and never counts it as the work's independent reviewer.
+- The session report names the agent instance that authored the work and
+  each independent reviewer. The author never counts as the work's
+  independent reviewer.
 - These statements add to the constitution. They except no article.
 
 ## Running Steps (Mandatory)
@@ -268,12 +268,12 @@ writes nothing and states why; the stage's review reads that statement.
 
 ## Default Autopilot Policy inside a run
 
-Inside a run, each bucket of a skill's Default Autopilot Policy is
-satisfied by one kind of authorization the run records:
+Inside a run, record the authorization for each bucket in the session report:
 
-- An `ask-user` item is satisfied only by a `human_decision` that answers it.
-- A `hard-required` input is satisfied by `request_scope` or by the run's
-  binding.
+- An `ask-user` item is satisfied only by the operator's answer to it.
+  Name that answer and its source; an agent's choice is not an operator answer.
+- A `hard-required` input is satisfied by the operator's request or by the
+  run's binding. Name the request or work order that supplies it.
 - An `auto-decide` item needs no authorization.
 - `--auto` satisfies nothing. It answers no `ask-user` item and supplies no
   `hard-required` input.

package/assets/init/.qfai/assistant/rule/ui-definition-protocol.md

@@ -27,6 +27,8 @@ A downstream skill reads the UI definition in this order.
    - primary tasks
    - states
    - actions
+   - supplements (the text shown beyond title, group headings and labels, each with
+     its reason) and, when written, structure (the groups and headings, in order)
 
 3. **Brand SSOT**
    - root `DESIGN.md` (front-matter + `# Brand Philosophy` body), the only
@@ -36,6 +38,10 @@ A downstream skill reads the UI definition in this order.
    prototyping loop ran): the final prototype, procurement and implementation
    notes
 
+The supplements and structure are required input: implementation adds no text the
+contract does not declare, and surface review compares the rendered text with them.
+A screen that lacks them is returned to `/qfai-sdd`.
+
 The paths that render a user-visible surface are declared by `uiux.surfacePaths`
 in `qfai.config.yaml`, and nowhere else.
 
@@ -51,6 +57,5 @@ in `qfai.config.yaml`, and nowhere else.
 ## Forbidden Fallbacks
 
 - Do not infer downstream UI behavior from discussion-pack sidecars.
-- Do not use retired design contract files.
 - Do not use HTML mock sections as downstream source of truth.
 - Do not treat a competitor reference as a selected design direction.

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

@@ -293,7 +293,7 @@ Fill policy templates with repo evidence.
 - Keep existing content when already accurate.
 - When evidence is missing, write `TBD` and record what is missing.
 - Do not invent facts.
-- Fill `03_contract/tech.md` in its template's shape: a Stack row for the runtime, the platform and each tool detected, each runtime dependency with its reason, and the quality-gate commands under Standard commands, one labelled item each. It holds no rule and no constraint; a constraint goes to `01_policy/constraint.md`.
+- Fill `03_contract/tech.md` in its template's shape: a Stack row for the runtime, the platform and each tool detected, with one row per test layer whose Choice names the tool, the files it was observed in, and why it fits; each runtime dependency with its reason, and the quality-gate commands under Standard commands, one labelled item each. It holds no rule and no constraint; a constraint goes to `01_policy/constraint.md`.
 - Fill `## Architecture` of `03_contract/tech.md` from the codebase: one row per layer the module layout shows, what it is responsible for, and the layers its imports reach, or `-`. Name layers, never paths. Implementation places new code by this table and reviewers judge a change against it, so write the import directions the code has.
   - A layer is a group of modules whose imports point one way: an upper layer uses the layers below it, and a lower layer never imports an upper one.
   - Draw the layers first, as one `mermaid` `flowchart TD` with a node per layer and an `Upper --> Lower` edge per import direction. Then write the table rows from the uppermost layer down, so each Depends on names only rows below it. `npx qfai validate` reports a diagram and a table that disagree.
@@ -304,10 +304,10 @@ Edit:
 
 - `validation.traceability.testFileGlobs`
 - `validation.traceability.testFileExcludeGlobs` (only if needed)
-- `routing` or `reviewProfiles` only when the project needs an override; each matching entry replaces the shipped default as a whole
+- `routing` or `reviewProfiles` only when the user asks to change one; each matching entry replaces the shipped default as a whole
 - `uiux.surfacePaths`: the repository-relative globs of the paths observed to render a user-visible surface, or `[]` when the repository renders none. Keep an existing value unless the user asks to change it. An absent key leaves the UI impact decision unevaluable.
 
-Keep all other config keys unchanged.
+Keep all other config keys unchanged. Add no key the package already defaults, `paths.specsDir` included; a value the project set stays.
 
 ## Step 5 - Evidence sampling
 

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/discussion-completion-matrix.md

@@ -74,12 +74,9 @@ Completion is blocked until all are true:
    ordinary. This is the one visual decision made here, because no later stage asks the user for
    it: `/qfai-sdd`'s `common-design-md` step authors tokens from whatever is recorded. A direction taken without the
    user carries `chosen_by: assumption` and an open entry in `11_OQ-Register.md`.
-6. No forbidden legacy sidecar exists under `uiux/` (see
-   `templates/uiux/00_index.md#Forbidden Legacy Files`).
 
 Evaluation axes are global constants (4-step ordinal: weak / acceptable / strong /
-exceptional) and are NOT authored as discussion sidecars, so no scoring, override, strategy,
-taste-interview, option-comparison or selected-anchor sidecar is required or permitted.
+exceptional) and are NOT authored as discussion sidecars.
 
 ## CLI Packs
 
@@ -93,9 +90,8 @@ so conditions 1 and 5 above do not apply to it:
   `validators/designContractReadiness.ts` skips `QFAI-DCON-030`/`-033`/`-034` for it.
 - No design direction either: nothing downstream reads a theme for a surface that renders
   no tokens.
-- Conditions 2, 3, 4, 6 and 7 apply unchanged: all three canonical `uiux/` sidecars, the
-  full screen-contract schema, unranked exploration directions, no forbidden legacy
-  sidecar, and zero open OQs.
+- Conditions 2, 3, 4 and 7 apply unchanged: all three canonical `uiux/` sidecars, the
+  full screen-contract schema, unranked exploration directions, and zero open OQs.
 - `route:` on a `cli` screen contract names the command invocation, not a web path, as the `cli` section of the UI-bearing playbook sets out.
 - No `prototyping.yaml`: `cli` is not a valid prototyping execution surface.
 - `primary_surface: cli` with a visual `secondary_surfaces` entry is NOT a cli-only pack —

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui-bearing-playbook.md

@@ -74,7 +74,5 @@ shadows:
 
 Trend Scan is **not** a sidecar file. Trend Scan lives at
 `04_Sources.md#Trend Scan` (part of the core nine-file discussion pack).
-The legacy `uiux/20_trend_scan.md` template and the whole `uiux/20-24`
-design-evaluation family were removed; evaluation axes are now global
-constants and are not authored as discussion sidecars. UI-bearing
-completion checks read Trend Scan from `04_Sources.md`.
+Evaluation axes are global constants and are not authored as discussion
+sidecars. UI-bearing completion checks read Trend Scan from `04_Sources.md`.

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui_ux_best_practices.md

@@ -116,12 +116,7 @@ Those three are the entire canonical sidecar family. Evaluation axes are global
 QFAI CLI applies — not by any file in this tree. The reviewer prompt that
 `/qfai-prototyping` ships restates that axis set; editing it does not change the set the CLI accepts. Axes are not
 authored as discussion sidecars. Discussion is planner-first: it carries exploration directions
-unranked and does not select a single visual winner, so there is no strategy, taste-interview, scoring,
-override, option-comparison or selected-anchor sidecar. Do NOT create
-`10_implementation_strategy.md`, `11_design_taste_interview.md`, the `20-24`
-design-evaluation family, `30_option_comparison.md`, or `31_selected_anchor_screen.md` —
-those filenames are forbidden, see `templates/uiux/00_index.md#Forbidden Legacy Files`, and
-creating them fails validation.
+unranked and does not select a single visual winner.
 
 ### What must be explicit in the discussion pack
 

package/assets/init/.qfai/assistant/skill/qfai-discussion/templates/uiux/00_index.md

@@ -30,19 +30,3 @@ cli-only pack — `primary_surface: cli` with no visual surface in
 `secondary_surfaces` — never gets one: the `common-design-md` step writes none, and
 `/qfai-prototyping` does not run on `cli`. Do not report any pack as
 incomplete for a missing `DESIGN.md`.
-
-## Forbidden Legacy Files
-
-The following files are NOT part of the canonical family and must NOT be created in new packs:
-
-- `10_implementation_strategy.md` — discussion carries directions unranked, so it selects no strategy
-- `11_design_taste_interview.md` — brand signals are recorded in `04_Sources.md`
-- `12_design_system.md` — replaced by root `DESIGN.md`
-- the `20`–`24` design-evaluation family — the evaluator axes are fixed by the CLI, not authored here
-- `30_option_comparison.md` — replaced by root `DESIGN.md`
-- `31_selected_anchor_screen.md` — replaced by root `DESIGN.md`
-- `33_exploration_rubric.md` — replaced by the fixed evaluator axes (`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`)
-- `34_evaluator_calibration.md` — replaced by the fixed evaluator axes (`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md`)
-- `40_contracts.md` — replaced by `40_screen_contracts.md`
-- `50_review_bundle.md` — replaced by `50_review_input_bundle.md`
-- `60_critique_loop.md` — removed (critique integrated into review bundle)

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

@@ -86,6 +86,11 @@ design. They are written by the `write-acceptance-tests` route, or by
 `implement-acceptance` run alone, and the report says which BF and AC tests
 still have an empty body.
 
+For that report or a handoff of unfinished BF/AC bodies, read
+`.qfai/assistant/step/verify-repo-gate/STEP.md#acceptance-evidence-and-follow-up`.
+It separates annotation proof, body states, actual behavior and execution,
+and the remaining work's owner and completion criteria.
+
 Each of these runs alone, instead of that order, when the request is not new
 behaviour but a failure, a repair or upkeep:
 
@@ -139,9 +144,10 @@ every finding of its one review is fixed or answered. Invoked by name, it runs
 completion; when that fresh validate result has no test-obligation EX finding
 for this BF, the invocation reports "nothing to do", and reads or writes no
 ledger status. Inside a route it runs no validate: the verify stage does.
-The report ends with a question listing the next actions, `/qfai-verify`
-recommended, as `.agents/rules/user-questions.md` § 6 sets out.
-Under a no-question mode, list them in the report instead.
+When the next step needs the user's answer, ask a question listing the next
+actions, `/qfai-verify` recommended, per `.agents/rules/user-questions.md` § 6.
+Completion-only reports ask nothing. Under a no-question mode, list remaining
+actions instead.
 
 ## Default Autopilot Policy
 

package/assets/init/.qfai/assistant/skill/qfai-implement/references/parallelization-policy.md

@@ -10,7 +10,15 @@ For each candidate item, name its production files, test files, contracts, fixtu
 
 Deny parallel dispatch when two items write the same shared fixture or mock file, or mutate the same fixture instance. A shared fixture module that both items only read as-is does not by itself deny parallel dispatch.
 
-Give each worker a separate worktree and an exact file ownership list. Workers do not change another worker's files or the story tree. The orchestrator integrates their results and resolves every overlap before judging either item complete.
+Give each worker an exact file ownership list and a checkout assigned by the host.
+Use separate worktrees when the host supports editing them; otherwise use the
+existing shared-index mode in
+`.qfai/assistant/rule/workflow.md#concurrency-stage-independent-mandatory`.
+Creating a worktree does not grant edit permission. For a refused edit, follow
+`.qfai/assistant/rule/shared-skill-delegation-baseline.md#worker-edit-boundary`.
+Workers do not change another worker's files or the story tree. The orchestrator
+integrates their results and resolves every overlap before judging either item
+complete.
 
 ## Integration gate
 

package/assets/init/.qfai/assistant/skill/qfai-implement/references/red-admissibility.md

@@ -6,6 +6,52 @@ A RED observation belongs to one example and one test selector. The test must lo
 
 A collection error, import error, syntax error, missing fixture, timeout before the assertion, or unconditional throw is a missing seam. Repair the seam and repeat RED before production behavior is added.
 
+### Selected-case execution
+
+For each focused Red, Green and Refactor invocation, keep this human receipt
+under the target example in the existing stage report:
+
+- The exact command with argument boundaries, cwd, file selection and case
+  selector. Preserve the Standard Test command's quoted arguments; a name
+  pattern does not select files.
+- The actual runtime version, reporter, input revision and raw output/log
+  reference. Explain intentional input changes between invocations.
+- The target EX, test source declaration and full file/parent/case identity.
+  Resolve duplicate short names through their full hierarchy; account for the
+  runner's actual parent selection rather than assuming a leaf-only pattern
+  runs every nesting shape.
+- Evidence that this selected case's body executed, linked to its actual
+  terminal result. Retain skip, TODO, cancellation, interruption and any
+  expected-failure inversion explicitly.
+- Process exit, aggregate counts and file/container results, apart from that
+  case evidence. An annotation and static scanner linkage prove a declaration,
+  not runtime execution or a behavioral result.
+
+Compare actual TAP start and terminal records, spec named results or JUnit
+nodes with the declared target and its full hierarchy. A TAP label, spec glyph
+or JUnit testcase can belong to a container; none alone proves the selected
+leaf body ran. Dots, coverage and summaries alone are also insufficient. If
+output is unfamiliar, incomplete or cannot identify the selected case, retain
+it, name the missing observation and obtain supported case-level evidence.
+Do not guess a parser or invent a receipt format.
+
+Zero selected executions, skip, TODO, cancellation, interruption or missing
+identifiable body evidence cannot close a phase, even with exit zero or a
+passing file/container. Correct selection or observation and repeat the
+focused invocation. Failure of a parent, another case, an import or an
+unconditional throw is not the selected assertion's ordinary RED. An
+expected-failure inversion is recorded separately; its reported pass is not
+ordinary behavior success. Existing approved alternative RED routes remain
+available.
+
+Ordinary RED reaches and fails the selected intended assertion or expected
+exception on its stated behavior. GREEN and Refactor must observe that same
+selected behavior succeeding on the intended input. Do not reuse another
+case's result or a prior input revision's result as proof for this invocation.
+The normal verify run establishes full collection coverage; no extra full suite is
+required for each focused cycle. This receipt adds no ledger, JSON field,
+gate status, runtime parser or runner.
+
 ## Assertion control
 
 Temporarily neutralize only the example assertion while keeping the test compilable and runnable. The same command must pass. Capture the changed lines and result, then restore the assertion before recording RED. This control shows that the reported failure came from the assertion.

package/assets/init/.qfai/assistant/skill/qfai-implement/references/ui-affecting.md

@@ -5,6 +5,7 @@
 Read the UI surface paths `uiux.surfacePaths` declares in qfai.config.yaml, and resolve paths.contractsDir from the same file. Read every UI contract under its ui/ directory, and the root DESIGN.md if present for the brand tokens.
 When a prototyping loop ran in this checkout, read its handoff at .qfai/prototype/final/handoff.json: the final prototype, its procurement and the implementation notes.
 Read the flow, story, acceptance criterion, and example that the implementation changes.
+For each screen the change renders, read its `supplements` and `structure` in the UI contract before adding text: the screen shows its title, group headings, labels and declared supplements, and no other text.
 
 ## Routing
 
@@ -22,3 +23,5 @@ product-surface-reviewer. Do not infer that a change has no UI effect from its d
 For a UI affecting example, report the screen state, action, expected and observed result, and a capture or rendered artifact. The artifact must identify the source revision. In the stage review, product-surface-reviewer judges each UI affecting example, its UI contracts, and its captured state. The review verdict refers to that revision.
 
 If the implementation or capture changes after the verdict, refresh the capture and review. A passing code test cannot substitute for the visual and interaction evidence that the acceptance criterion requires.
+
+Capture each declared task at a desktop width and a narrow width, in the normal state and in every declared empty, error, loading and success state the screen has. A text the contract declares that the capture lacks, or a text the capture shows that the contract does not declare, is a finding.

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

@@ -57,9 +57,9 @@ Markdown and link checks run over the changed files, each exiting 0. A check the
 project does not have is UNRUN, not a pass.
 
 The stage returns what `maintain-edit` lists under "What the stage returns".
-The report 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.
+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.
 
 ## Default Autopilot Policy
 

package/assets/init/.qfai/assistant/skill/qfai-migration-v1-to-v2/SKILL.md

@@ -24,10 +24,16 @@ Follow `.qfai/assistant/rule/shared-skill-operating-baseline.md#user-questions-a
 for every user question. With `--auto`, ask nothing and record
 explicit assumptions in the migration report.
 
-Read `references/migration-guide.md` before changing the project. Run this
-skill from the project root, where `qfai.config.yaml` and a locally installed
-`qfai` package are available. The twelve scripts use the installed package.
-They do not add a `qfai` subcommand or make network calls.
+Read `references/migration-guide.md` before changing the project.
+
+Read `references/migration-placement.md` when you write `plan.yaml`, when a
+step reports a retired configuration key, and when a step lists a document that
+does not fit its template's shape. It holds the plan format, the retired keys,
+the contract numbers, the business rules and what each document keeps.
+
+Run this skill from the project root, where `qfai.config.yaml` and a locally
+installed `qfai` package are available. The twelve scripts use the installed
+package. They do not add a `qfai` subcommand or make network calls.
 
 The skill serves two runs, and the steps tell them apart from the project
 itself:
@@ -81,7 +87,7 @@ keep authors separate from reviewers.
    each old business rule's destination contract. Name that contract by its
    current path under `cli/`, `api/`, `db/`, `ui/` or `design/` of the
    contracts directory: step 3 gives every contract a new ID and file name,
-   and later steps find it from that path. Use the format in the guide. The plan
+   and later steps find it from that path. Use the format in `references/migration-placement.md`. The plan
    may be written before step 1, from the old contract paths.
 2. Before the first real run, tell the person that the migration deletes
    every 1.x file that has no destination and replaces every customised
@@ -112,7 +118,7 @@ keep authors separate from reviewers.
 5. Resolve every reported item with the person responsible for the content.
    Preserve any item the scripts could not place. Before step 4 writes
    `id-map.json`, settle an example that cites several criteria and a rule that
-   binds no contract through the plan keys the guide names. After it, do not
+   binds no contract through the plan keys `references/migration-placement.md` names. After it, do not
    change `plan.yaml` to move a mapped item. Place remaining content in the new
    tree through `/qfai-sdd`, and finish each listed item as the guide's
    "Resolve the reports" section says.