qfai 2.1.0 → 2.1.1

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

@@ -2,6 +2,17 @@
 
 Use this file only when the current discussion needs platform-specific detail.
 
+## Contents
+
+- Cross-Platform Baseline
+- Web
+- Mobile
+- Desktop
+- CLI
+- States
+- Dark Mode
+- Motion
+
 ## Cross-Platform Baseline
 
 - Keep the same conceptual model across surfaces.

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

@@ -2,6 +2,17 @@
 
 Use this file when the core checklist is not enough.
 
+## Contents
+
+- Heuristic Review Pass
+- Layout And Information Architecture
+- Forms And Actions
+- Screen States
+- Accessibility Audit
+- Anti-Pattern Red Flags
+- Documentation Expectations For QFAI
+- Recommended Audit Order
+
 ## Heuristic Review Pass
 
 Review the design direction against these durable heuristics:

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

@@ -5,6 +5,15 @@ This file is the compact, durable core for `qfai-discussion`.
 It is intentionally not an encyclopedia. Keep this file short, decision-oriented, and stable.
 Move volatile or bulky detail into the `ui_ux/` sidecar references and research current material at run time.
 
+## Contents
+
+- Why This File Is Compact
+- How To Use This Reference
+- Core Decision Rules
+- QFAI-Specific Authoring Guidance
+- Compact Review Checklist
+- Anti-Bloat Rules For Future Edits
+
 ## Why This File Is Compact
 
 - OpenAI recommends versioned prompts, variables, concise examples, and eval-backed iteration rather than piling all guidance into one prompt.
@@ -18,10 +27,7 @@ Move volatile or bulky detail into the `ui_ux/` sidecar references and research
 ## How To Use This Reference
 
 1. Read this file first for durable decision rules.
-2. Open only the appendix you need:
-   - `ui_ux/platform_baselines.md`
-   - `ui_ux/review_audit_playbook.md`
-   - `ui_ux/trend_scan_playbook.md`
+2. Open only the appendix the `discussion-uiux` step names for the current task.
 3. For trends, platform release details, or fast-moving conventions, do web research during the current discussion run and cite sources in `04_Sources.md`.
 
 ## Core Decision Rules
@@ -107,9 +113,8 @@ resolves through:
 
 Those three are the entire canonical sidecar family. Evaluation axes are global constants
 (4-step ordinal: weak / acceptable / strong / exceptional) fixed by the review validation the
-QFAI CLI applies — not by any file in this tree. The shipped
-`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md` restates that axis set
-for the reviewer prompt; editing it does not change the set the CLI accepts. Axes are not
+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
@@ -175,29 +180,6 @@ Use this as the first-pass gate before deeper review.
 - Are comparisons and rejections traceable?
 - Can prototyping and SDD proceed without guessing the intended UX?
 
-## When To Open The Appendices
-
-Open `ui_ux/platform_baselines.md` when you need:
-
-- touch target sizes
-- breakpoint heuristics
-- platform navigation baselines
-- dark mode and cross-platform adaptation notes
-
-Open `ui_ux/review_audit_playbook.md` when you need:
-
-- heuristic review structure
-- anti-pattern checklists
-- screen-spec documentation rules
-- audit/testing guidance
-
-Open `ui_ux/trend_scan_playbook.md` when you need:
-
-- trend-scan category coverage
-- freshness and citation rules
-- how to translate references into local decisions
-- how to keep trends from overwhelming product-specific needs
-
 ## Anti-Bloat Rules For Future Edits
 
 - Do not add long font-scale tables, full platform encyclopedias, or year-stamped trend lists to this file.
@@ -205,9 +187,3 @@ Open `ui_ux/trend_scan_playbook.md` when you need:
 - Do not repeat the same concept across multiple theoretical frameworks unless the duplication changes an actual QFAI decision.
 - Prefer one sharp rule plus a short verification cue over paragraph-heavy explanation.
 - If a section is mostly lookup material, move it to an appendix.
-
-## Appendix Index
-
-- [Platform Baselines](ui_ux/platform_baselines.md)
-- [Review Audit Playbook](ui_ux/review_audit_playbook.md)
-- [Trend Scan Playbook](ui_ux/trend_scan_playbook.md)

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`
@@ -124,6 +124,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

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/red-admissibility.md

@@ -10,4 +10,4 @@ A collection error, import error, syntax error, missing fixture, timeout before
 
 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

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

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`

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)
 
@@ -60,7 +60,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
@@ -175,7 +175,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

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

@@ -5,6 +5,20 @@ QFAI 2.x does not read the old spec-pack layout. A project that keeps spec packs
 must stay on a pinned 1.x release. To upgrade, migrate the project before using
 the 2.x validation and authoring workflow.
 
+## Contents
+
+- Prepare
+- Place stories and rules
+- Retired configuration keys
+- Contract IDs
+- Business rules
+- Documents in their template's shape
+- Run the bundled steps
+- Write boundary
+- Resolve the reports
+- Install and check the free-text entry
+- Former migration memos
+
 ## Prepare
 
 1. Commit the current project state. The migration deletes every 1.x file
@@ -82,11 +96,11 @@ examples:
   - id: EX-0001-0002
     criterion: AC-0001-0001
 rules:
-  - id: BR-0001-0001
+  - id: BR-0006-0001
     contract: api/orders.yaml
-  - id: BR-0001-0002
+  - id: BR-0006-0002
     binds: none
-  - id: BR-0001-0003
+  - id: BR-0006-0003
     retire: The payment provider enforces this limit.
 ```
 
@@ -200,14 +214,14 @@ the 2.x skills declare.
 ## Business rules
 
 Rules are numbered per contract, `BR-<contract number>-NNNN` from `0001` in plan
-order: the first rule step 4 places in API-0002 is BR-0002-0001. Step 7 writes
+order: the first rule step 4 places in API-0006 is BR-0006-0001. Step 7 writes
 each rule into its contract in the form the contract's format takes:
 
 | Contract format | Where the rule goes                                                     |
 | --------------- | ----------------------------------------------------------------------- |
 | Markdown        | A row of the `## Business rules` table: BR-ID, Statement and Examples   |
 | YAML or JSON    | An entry `{ id, statement, examples }` of the top-level `x-qfai-rules:` |
-| SQL             | A `-- Rule BR-0002-0001: <statement>` line, then an `-- Examples:` line |
+| SQL             | A `-- Rule BR-0006-0001: <statement>` line, then an `-- Examples:` line |
 
 A Markdown contract without a `## Business rules` section gets one as its last
 section. A rule's examples are the new IDs of the examples that cited it. A

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

@@ -19,7 +19,7 @@ mode: execution-focused
 
 ## /qfai-prototyping
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/design-md-spec.md

@@ -10,6 +10,16 @@ every color, font, radius or shadow an iteration uses outside this file.
 A reference copy is shipped in this skill at
 `templates/DESIGN.md.sample`.
 
+## Contents
+
+- File shape
+- Front-matter schema
+- `brand.archetype` allowed values
+- `brand.theme`
+- `accessibility` allowed keys
+- Validation rules
+- Issue shape
+
 ## File shape
 
 ```markdown
@@ -72,11 +82,10 @@ accessibility:
 
 ## `brand.archetype` allowed values
 
-The 8-archetype catalog is the SSOT in
-`.qfai/assistant/skill/qfai-sdd/references/design-md-brand-catalog.md`:
-`minimal | bold | corporate | playful | organic | tech | elegant |
-casual`. Read that reference for archetype semantics, do not duplicate
-here.
+The 8-archetype catalog is the SSOT in the brand catalog that
+`/qfai-sdd`'s `common-design-md` step names: `minimal | bold | corporate |
+playful | organic | tech | elegant | casual`. Read the catalog for
+archetype semantics, do not duplicate here.
 
 ## `brand.theme`
 

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/generator-prompt.md

@@ -5,6 +5,16 @@ Brand identity is locked by root `DESIGN.md`. Iterate on **information
 architecture**, **navigation flow**, and **usability** — not visual
 identity.
 
+## Contents
+
+- Read order
+- HTML envelope (mandatory on every iter)
+- Hard constraints
+- Output layout
+- The first iteration (seed)
+- Later iterations
+- Pivot guidance (what changes vs what does not)
+
 ## Read order
 
 1. Root `DESIGN.md` (front-matter tokens + `# Brand Philosophy` body).