qfai 2.1.0 → 2.1.2

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-grill/SKILL.md

@@ -10,7 +10,7 @@ mode: interactive-by-default
 
 ## qfai-grill - the session a user asks for
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run a grilling session on whatever the argument names. This skill holds no
 method of its own: it directs the run to `qfai-grilling`, which is the one

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

@@ -1,14 +1,14 @@
 ---
 name: qfai-grilling
 title: QFAI Grilling (Design interrogation)
-description: "Interrogate an unfixed design in rounds: a tree of open decisions, a frontier of the ones answerable now, facts read rather than asked, and an end condition the user holds."
+description: "Interrogate an unfixed design in rounds: a tree of open decisions, a frontier of the ones answerable now, facts read rather than asked, and an end condition the user holds. Use when a stage calls for a grilling session, or when asked to grill or stress-test a design."
 allowed-tools: [Read, Glob, Grep, Bash, TodoWrite, Task, Agent]
 mode: interactive-by-default
 ---
 
 ## qfai-grilling - interrogate a design before it is fixed
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 The one implementation of the interview method. A skill that needs a design
 interrogated invokes this rather than writing rounds of its own, so there is one
@@ -296,57 +296,13 @@ orchestrator holds both. That is a different answerer, not a delegated question:
 nothing hands the asking to a third agent, and the orchestrator still answers
 nothing itself.
 
-A round between agents may have several authors, because one frontier can hold
-decisions belonging to different drafting roles.
-
-- The round goes to **every author whose decisions it contains**, each seeing
-  the whole round. A decision reads differently beside the ones next to it, and
-  an author shown only its own share cannot say so.
-- **Every answer is collected before the frontier is recomputed.** Recomputing
-  on the first reply settles the rest against a tree that moved under them.
-- **Two authors answering one question differently is itself a decision**, and
-  it joins the frontier rather than being averaged. If the budget ends with it
-  open, it takes the griller's recommendation like any other non-critical
-  decision, with both positions recorded.
-- **An addition an author proposes is asked what part of the request needs
-  it.** One nobody can point to is dropped, not adopted.
-- **A fact only the user holds goes to the user, not to an author.** No author
-  can answer an unpublished constraint or an intention nobody wrote down, and
-  the convergence rules escalate decisions rather than facts — so without this
-  the fact sits on the frontier until the budget ends, taking every decision
-  waiting on it with it. It escalates immediately, as a request for the value
-  rather than a choice. Under a no-question mode it reaches nobody, and what
-  follows depends on the fact rather than on its kind: where the consuming
-  document declares the value undefaultable the run stops and names it
-  (`.qfai/assistant/rule/constitution.md` Article X, rule 4), and where
-  the document has a default that default is recorded as a labelled assumption
-  beside the open question, which is the ordinary no-question path. Stopping on
-  every user-held fact would block a run over a defaultable date.
-
-### Orchestrator Protocol
-
-- The orchestrator computes the frontier and reads the answers. It does not
-  decide a frontier question on anyone's behalf.
-- **Who puts the round depends on the mode, and exactly one role does.** With a
-  user, the orchestrator puts it. Between agents, the griller puts it and the
-  orchestrator does not — a session where both do is one where an author is
-  asked twice and the two answers have no tie-break.
-- It must not record an answer **as the user's** that the user did not give, and
-  must not self-approve the session's end condition. An author's answer in an
-  agent-to-agent round is recorded as that author's position, with whose it is:
-  the round cannot be recomputed, a disagreement cannot be kept, and an
-  escalation cannot carry the positions to the user unless the answers are
-  held.
-- **In a delegated session the griller's recommendation settles a decision that
-  is not critical.** Where the authors and the griller land on one answer, or
-  the budget ends first, the recommendation is taken and the stage records it as
-  `agents`, with the reason and every disagreeing position. The stage's final
-  report lists it; nothing waits for the user to read it.
-
-  A critical decision is the exception: agreement closes its node for the
-  round, and only the user's answer settles it. Recording an agreed critical
-  decision as settled is how a choice nobody with the standing made reaches a
-  draft.
+### Rounds between agents
+
+Read `references/delegated-session.md` when a griller puts the round to authors
+instead of a user. It holds how a round with several authors is held, which
+role puts the round, why a fact only the user holds goes to the user, and when
+the griller's recommendation settles a decision. A session with a user does not
+need it.
 
 ### Capability Probe
 
@@ -367,45 +323,17 @@ decisions belonging to different drafting roles.
 
 ## Work Orders Summary
 
-A session that dispatched any lookup must record a `## Work Orders Summary`
-table in the artifact its invoking stage writes. Use the shared schema from
-`.qfai/assistant/rule/shared-skill-delegation-baseline.md`, including
-the `Agent instance` column.
-
-| Step | Role (sub-agent) | Agent instance  | Task title                      | Input (refs)                    | Output (refs)                   | Status (PASS/REVISE/PENDING) |
-| ---- | ---------------- | --------------- | ------------------------------- | ------------------------------- | ------------------------------- | ---------------------------- |
-| 1    | Reviewer         | `<instance id>` | Read the facts a round waits on | Decision and what it depends on | The fact, and where it was read | PASS/REVISE                  |
+A session that dispatched any lookup records a `## Work Orders Summary` table
+in the artifact its invoking stage writes. Read `references/session-record.md`
+for the table. It also lists what the invoking stage's reviewer confirms about
+the session, so read it when reviewing one.
 
 ### Reviewer Gate
 
 This skill produces no artifact, so the gate that covers a session is the
-invoking stage's. What it confirms about the session is:
-
-- no decision was recorded as the user's that the user did not answer, no
-  critical decision was adopted without them, and none was assumed that the
-  assumption path excludes;
-- every adopted decision has its `agents` row, and none of them adds what the
-  request did not need;
-- a fact taken as settled names where it was read;
-- the session ended on its own condition or on the user's word, in one of the
-  five endings `.agents/rules/grilling.md` names. Between agents a round budget
-  bounds the rounds (`.qfai/assistant/rule/review-convergence.md`), and
-  a session recorded as ended while a critical decision it escalated is still
-  unanswered is the finding.
-
-- Reviewer independence is defined normatively in
-  `.qfai/assistant/rule/shared-skill-delegation-baseline.md#definition-independent-reviewer-normative`.
-  An agent that answered a lookup in this session is disqualified from reviewing
-  the facts it supplied.
-- Reviewer checks the Drift Protocol, verifies alignment with `test-layers.md`,
-  and treats ratios as signals, not gates.
-- Reviewer returns only `PASS` or `REVISE`, with a concrete fix proposal on
-  `REVISE`. A gate that could not be run at all is recorded as `PENDING`, which
-  never counts as `PASS`.
-
-A session run from the user-invoked entry point has no invoking stage. There the
-gate is the user reading the record, which is why that entry point writes no
-files.
+invoking stage's. A session run from the user-invoked entry point has no
+invoking stage. There the gate is the user reading the record, which is why that
+entry point writes no files.
 
 ## Default Autopilot Policy
 

package/assets/init/.qfai/assistant/skill/qfai-grilling/references/delegated-session.md

@@ -0,0 +1,58 @@
+# Delegated session
+
+How the session agent runs a round between agents: who is asked, how the
+answers are held, and which role puts the round.
+
+## Several authors
+
+A round between agents may have several authors, because one frontier can hold
+decisions belonging to different drafting roles.
+
+- The round goes to **every author whose decisions it contains**, each seeing
+  the whole round. A decision reads differently beside the ones next to it, and
+  an author shown only its own share cannot say so.
+- **Every answer is collected before the frontier is recomputed.** Recomputing
+  on the first reply settles the rest against a tree that moved under them.
+- **Two authors answering one question differently is itself a decision**, and
+  it joins the frontier rather than being averaged. If the budget ends with it
+  open, it takes the griller's recommendation like any other non-critical
+  decision, with both positions recorded.
+- **An addition an author proposes is asked what part of the request needs
+  it.** One nobody can point to is dropped, not adopted.
+- **A fact only the user holds goes to the user, not to an author.** No author
+  can answer an unpublished constraint or an intention nobody wrote down, and
+  the convergence rules escalate decisions rather than facts — so without this
+  the fact sits on the frontier until the budget ends, taking every decision
+  waiting on it with it. It escalates immediately, as a request for the value
+  rather than a choice. Under a no-question mode it reaches nobody, and what
+  follows depends on the fact rather than on its kind: where the consuming
+  document declares the value undefaultable the run stops and names it
+  (`.qfai/assistant/rule/constitution.md` Article X, rule 4), and where
+  the document has a default that default is recorded as a labelled assumption
+  beside the open question, which is the ordinary no-question path. Stopping on
+  every user-held fact would block a run over a defaultable date.
+
+## Orchestrator protocol
+
+- The orchestrator computes the frontier and reads the answers. It does not
+  decide a frontier question on anyone's behalf.
+- **Who puts the round depends on the mode, and exactly one role does.** With a
+  user, the orchestrator puts it. Between agents, the griller puts it and the
+  orchestrator does not — a session where both do is one where an author is
+  asked twice and the two answers have no tie-break.
+- It must not record an answer **as the user's** that the user did not give, and
+  must not self-approve the session's end condition. An author's answer in an
+  agent-to-agent round is recorded as that author's position, with whose it is:
+  the round cannot be recomputed, a disagreement cannot be kept, and an
+  escalation cannot carry the positions to the user unless the answers are
+  held.
+- **In a delegated session the griller's recommendation settles a decision that
+  is not critical.** Where the authors and the griller land on one answer, or
+  the budget ends first, the recommendation is taken and the stage records it as
+  `agents`, with the reason and every disagreeing position. The stage's final
+  report lists it; nothing waits for the user to read it.
+
+  A critical decision is the exception: agreement closes its node for the
+  round, and only the user's answer settles it. Recording an agreed critical
+  decision as settled is how a choice nobody with the standing made reaches a
+  draft.

package/assets/init/.qfai/assistant/skill/qfai-grilling/references/session-record.md

@@ -0,0 +1,42 @@
+# Recording a session
+
+The work-orders table a session writes when it dispatched a lookup, and what
+the reviewer of the invoking stage confirms about the session.
+
+## Work Orders Summary
+
+Use the shared schema from
+`.qfai/assistant/rule/shared-skill-delegation-baseline.md`, including the
+`Agent instance` column.
+
+| Step | Role (sub-agent) | Agent instance  | Task title                      | Input (refs)                    | Output (refs)                   | Status (PASS/REVISE/PENDING) |
+| ---- | ---------------- | --------------- | ------------------------------- | ------------------------------- | ------------------------------- | ---------------------------- |
+| 1    | Reviewer         | `<instance id>` | Read the facts a round waits on | Decision and what it depends on | The fact, and where it was read | PASS/REVISE                  |
+
+## What the reviewer confirms
+
+The invoking stage's reviewer confirms this about the session:
+
+- no decision was recorded as the user's that the user did not answer, no
+  critical decision was adopted without them, and none was assumed that the
+  assumption path excludes;
+- every adopted decision has its `agents` row, and none of them adds what the
+  request did not need;
+- a fact taken as settled names where it was read;
+- the session ended on its own condition or on the user's word, in one of the
+  five endings `.agents/rules/grilling.md` names. Between agents a round budget
+  bounds the rounds (`.qfai/assistant/rule/review-convergence.md`), and
+  a session recorded as ended while a critical decision it escalated is still
+  unanswered is the finding.
+
+The reviewer works under these rules:
+
+- Reviewer independence is defined normatively in
+  `.qfai/assistant/rule/shared-skill-delegation-baseline.md#definition-independent-reviewer-normative`.
+  An agent that answered a lookup in this session is disqualified from reviewing
+  the facts it supplied.
+- Reviewer checks the Drift Protocol, verifies alignment with `test-layers.md`,
+  and treats ratios as signals, not gates.
+- Reviewer returns only `PASS` or `REVISE`, with a concrete fix proposal on
+  `REVISE`. A gate that could not be run at all is recorded as `PENDING`, which
+  never counts as `PASS`.

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

@@ -46,7 +46,7 @@ mode: approval-gated
 
 ## /qfai-implement — Implement a business flow
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`
@@ -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:
 
@@ -124,6 +129,13 @@ review, by `implementation-reviewer`. The review also checks for code
 written only to pass a test: no value hard-coded to the test's inputs and no branch written only for the test, and a wrong test or infeasible task raised as a Change Request, not worked around
 (`.qfai/assistant/rule/test-layers.md#a-passing-test-is-not-the-solution`).
 
+The review also checks that the
+change adds test files sized like their neighbours, commits no scratch checks,
+follows § 4 on unrequested fixes, including its exception for a necessary fix
+and reporting requirement, and states any assumption it built on
+(`.qfai/assistant/rule/test-layers.md#test-suite-sizing`,
+`.agents/rules/minimal-implementation.md` § 4).
+
 ## Completion
 
 The invocation completes on the gate of its last step once
@@ -132,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/credential-reuse.md

@@ -4,6 +4,15 @@ Acceptance tests that need an authenticated actor pay for the sign-in once per w
 per test. This file is the rule set. It is prose guidance — it adds no validator, no finding code,
 no test layer and no annotation token, and nothing here is checked by a tool.
 
+## Contents
+
+- Scope
+- Not dogfooded here
+- The seven session-reuse rules
+- The companion rule: a caller-injected environment is not the harness's to manage
+- Script naming: adopter guidance
+- A worked example, as one illustration among possible backends
+
 ## Scope
 
 These rules oblige the **E2E, API and Integration** layers only: the acceptance tests

package/assets/init/.qfai/assistant/skill/qfai-implement/references/cross-spec-ownership.md

@@ -6,6 +6,47 @@ Before changing a shared production module, test helper, fixture, contract, or p
 
 Do not use filename similarity as the only ownership signal. Follow imports, contract references, test fixtures, and call sites. A flow that merely happens to contain the same word is not a dependent flow.
 
+## Finding the dependents
+
+Search from the changed files outward, not from the flows inward:
+
+1. Start from the files the step plans to edit. After the edit, reconcile that
+   list with the files changed since the branch diverged from the configured
+   base branch (the three-dot comparison, so a file changed only on the base
+   branch is not counted). List a renamed file under both its old and new path.
+   If the comparison cannot be computed (a shallow clone, a missing base ref,
+   an exported tree), the changed set is unknown: say so and treat the search
+   as unresolved. Never read that failure as an empty list.
+2. For a changed contract, read the `Examples` citations of its rules. Each
+   cited EX ID names a flow.
+3. For every other changed file, find its readers: static imports and
+   re-exports, followed importer by importer, and literal paths that a
+   production module, test or fixture loader reads. Continue through a runtime
+   entrypoint (a command line, an HTTP route, a spawned process) that a test
+   invokes by a literal name. Follow each chain until a test file is reached.
+4. Read the `QFAI:BF-`, `QFAI:AC-` and `QFAI:EX-` annotations in those test
+   files. A BF annotation names the flow. An AC or EX annotation names it
+   through its first four-digit segment: `AC-0007-0002-01` and
+   `EX-0007-0002-03` both give `BF-0007`. Deduplicate the flows.
+
+Record each changed file, the readers or tests that reach it and the flows they
+name.
+
+## When the search cannot finish
+
+Some edges cannot be followed by reading: an import whose path is computed,
+fixtures loaded by a glob, an asset read by a path built at run time, an
+entrypoint reached by a computed name. Where one is left:
+the dependent set is unknown, not empty.
+
+Record each such edge with its file and the reason it could not be followed, as
+an unresolved cross-flow obligation. The flows it may touch keep their evidence
+until the consumers are identified and each one is revalidated below. Run the
+full test suite once on the integrated tree as an additional check, and record
+its command and result. A passing suite does not replace the per-flow
+revalidation and does not make a stale proof current. Do not report the search
+as complete while an edge is unresolved.
+
 ## Revalidation
 
 Run the changed example selector and the relevant tests of each dependent flow against the integrated tree. Run the scoped validation gate for each affected BF ID. Ask implementation-reviewer to judge any changed obligation and shared-code risk. A flow whose assertions or contract moved needs its own new evidence and review.

package/assets/init/.qfai/assistant/skill/qfai-implement/references/oracle-strength.md

@@ -16,7 +16,12 @@ The path is relative to the project root, and the original text is copied exactl
 
 A missing import, syntax error, fixture failure, or deliberate unimplemented throw does not prove the oracle. The failure must name the example's observable behavior. A mutation in an unrelated helper only proves that helper is used.
 
-The falsifiability run in red-not-observable.md already supplies this proof when it tests the same predicate and selector. Reuse that run instead of mutating twice.
+A proof belongs to one example.
+When a mutation fails tests annotated with different examples, record each failing assertion and check which boundary it proves.
+Narrow an assertion that proves another example's boundary, or have `/qfai-sdd` settle an unclear boundary in the examples.
+A shared predicate may fail several tests whose assertions independently prove their own examples.
+
+The falsifiability run recorded for an example that production already satisfies already supplies this proof when it tests the same predicate and selector. Reuse that run instead of mutating twice.
 
 ## Weak oracles
 

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,8 +6,54 @@ 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.
 
-If a seam is needed to reach the assertion, add only that seam and record its limit. A seam cannot implement the behavior that the example is intended to test. Where production already satisfies the example, use red-not-observable.md and its falsifiability proof.
+If a seam is needed to reach the assertion, add only that seam and record its limit. A seam cannot implement the behavior that the example is intended to test. Where production already satisfies the example, use the falsifiability route for existing behavior and its falsifiability proof.

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
 
@@ -13,9 +14,7 @@ production or test change implements behavior described by a UI contract, or a c
 surface path. Follow imports, component use, and contract references to check a changed path. A change to a shared
 component is UI affecting when a rendered surface consumes it.
 
-Match declared paths after normalizing separators to forward slashes. A pattern with two stars spans zero or more path
-segments; one star stays in one segment; a question mark matches one character. Matching is case-sensitive, including
-dot-prefixed segments. If `uiux.surfacePaths` is absent or the path relationship is uncertain, use the observed
+If `uiux.surfacePaths` is absent or the path relationship is uncertain, use the observed
 behavior and UI contracts; route an unresolved case as UI affecting and record the uncertainty for
 product-surface-reviewer. Do not infer that a change has no UI effect from its directory name alone.
 
@@ -24,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

@@ -12,7 +12,7 @@ mode: execution-focused
 
 ## /qfai-maintain - Non-normative edits
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`
@@ -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

@@ -1,7 +1,7 @@
 ---
 name: qfai-migration-v1-to-v2
 title: QFAI 1.x to 2.x Migration
-description: "Move an existing QFAI 1.x spec-pack project to the 2.x story-based spec tree using the bundled steps, then install and check the free-text entry."
+description: "Move an existing QFAI 1.x spec-pack project to the 2.x story-based spec tree using the bundled steps, then install and check the free-text entry. Use when asked to migrate a project that still holds QFAI 1.x spec packs."
 allowed-tools: [Read, Glob, Write, Edit, Bash]
 roles:
   [
@@ -16,7 +16,7 @@ routing-profile: architecture-heavy
 
 ## /qfai-migration-v1-to-v2
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -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:
@@ -60,7 +66,7 @@ names the directory and leaves the check to the person.
 
 Complete the launcher preflight in `.qfai/assistant/rule/shared-skill-operating-baseline.md`
 before running a CLI command.
-Use `rule/shared-skill-delegation-baseline.md` to route the declared roles and
+Use `.qfai/assistant/rule/shared-skill-delegation-baseline.md` to route the declared roles and
 keep authors separate from reviewers.
 
 ### Procedure
@@ -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.
@@ -175,7 +181,7 @@ saying it is already done. The complete write boundary is in
 The architecture reviewer checks the old-to-new mapping and preservation of
 unplaced content. The reviewer checks the twelve reports, rerun
 behavior, and validation result. Enforce the Drift Protocol and
-`rule/test-layers.md` when reviewing test obligations. Counts and effort
+`.qfai/assistant/rule/test-layers.md` when reviewing test obligations. Counts and effort
 estimates are signals, not gates. Record PASS or REVISE on the final tree.
 
 ## Default Autopilot Policy