qfai 2.1.2 → 2.2.0

package/assets/init/.qfai/assistant/skill/qfai-run/references/extraction.md

@@ -70,7 +70,8 @@ Ask in this order and stop at the first yes.
 3. Does the requester want an answer, not a change? A question.
 4. Is the subject the project's own operation: a test, a CI job, the build or
    repository tooling, a dependency, a release artifact, or a named procedure or
-   list of leftovers to carry out? An operation.
+   list of leftovers to carry out? An operation. Writing an ordinary procedure
+   within existing policy is a change, not carrying out that operation.
 5. Is the subject a written normative surface, such as a specification, a
    contract, a schema, a template, a rule or a check, while running behaviour is
    not what is reported wrong? A consistency intent.
@@ -79,6 +80,12 @@ Ask in this order and stop at the first yes.
 7. Otherwise something should be added, changed, removed, restructured or
    documented. A change.
 
+An operational document that gives actions within existing policy takes
+`procedure`. A change to policy, a story, a contract or QFAI assistant
+instructions keeps its owning consistency intent; Markdown is not permission
+to change those surfaces. A request for actual code changes keeps its code
+artifacts and checks, even when it also asks for instructions.
+
 Labels on an issue are hints, not evidence: `bug` and `enhancement` do not
 separate intents.
 
@@ -128,19 +135,20 @@ a request that is only the operation.
 | `behaviour-change` | A deliberate, documented behaviour should change, including feedback asking to revisit a decision. Removing a published surface is `deprecation`                                             |
 | `deprecation`      | A published surface is deprecated, removed, given a new default or given a migration path                                                                                                    |
 | `refactor`         | Structure changes and intended behaviour does not: move, split, deduplicate, delete code nothing declares. A measured speed-up as the point is `performance`                                 |
+| `procedure`        | Operational instructions within existing policy: inputs, actions, commands, required values and order. Authoring them does not execute their actions                                         |
 | `docs`             | Explanatory text that is not normative, such as user documentation, comments, a README or an example, is wrong, missing or unclear. Normative text is a consistency intent                   |
 
 ### Operations
 
-| Intent        | Set it when                                                                                                                                                                   |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `flaky-test`  | A named test or CI job fails and passes on the same code. A race users hit is `defect` with `intermittent`                                                                    |
-| `test-defect` | A test is wrong, weak, vacuous or bound to one platform, and the product is believed correct                                                                                  |
-| `ci`          | CI is red since a change, or a workflow, a lint lane, the build, a repository script or developer tooling should change                                                       |
-| `dependency`  | A dependency or toolchain is raised or pinned, a scanner finding answered by a bump included. No behaviour change is intended                                                 |
-| `release`     | Release notes, a changelog, a version, a backport, signing, a package, a distribution incident, or a manual test plan                                                         |
-| `order`       | The request names an approved action to carry out and holds no design of its own. A behaviour change whose design a parent settled keeps that change's intent with `upstream` |
-| `follow-up`   | Leftovers of earlier work, of mixed kinds: unresolved review findings, handover notes, a backlog to sort again. Members that share one intent take it with `bundle`           |
+| Intent        | Set it when                                                                                                                                                                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flaky-test`  | A named test or CI job fails and passes on the same code. A race users hit is `defect` with `intermittent`                                                                                                                                                            |
+| `test-defect` | A test is wrong, weak, vacuous or bound to one platform, and the product is believed correct                                                                                                                                                                          |
+| `ci`          | CI is red since a change, or a workflow, a lint lane, the build, a repository script or developer tooling should change                                                                                                                                               |
+| `dependency`  | A dependency or toolchain is raised or pinned, a scanner finding answered by a bump included, or a request to update `qfai` itself and run `init`. No behaviour change is intended                                                                                    |
+| `release`     | Release notes, a changelog, a version, a backport, signing, a package, a distribution incident, or a manual test plan                                                                                                                                                 |
+| `order`       | The request names an approved action to carry out and holds no design of its own. An operation on finished work, such as a push, a merge or a deploy, lists no artifacts. A behaviour change whose design a parent settled keeps that change's intent with `upstream` |
+| `follow-up`   | Leftovers of earlier work, of mixed kinds: unresolved review findings, handover notes, a backlog to sort again. Members that share one intent take it with `bundle`                                                                                                   |
 
 ### When two intents fit equally
 
@@ -151,7 +159,7 @@ the other as an alternative:
 `defect-regression`, `defect-silent`, `defect-crash`, `defect-conformance`,
 `model-gap`, `surface-contradiction`, `unenforced`, `defect`, `performance`,
 `flaky-test`, `test-defect`, `ci`, `deprecation`, `behaviour-change`,
-`feature`, `stale-record`, `dependency`, `release`, `refactor`, `docs`,
+`feature`, `stale-record`, `dependency`, `release`, `refactor`, `procedure`, `docs`,
 `question-hosted`, `question-help`, `question-why`, `question-how`.
 
 ## Entry flags
@@ -187,6 +195,7 @@ reading what it depends on.
 
 | Qualifier                 | Goes with          | Set it when                                                                                                                                                                                   |
 | ------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session-answerable`      | a question         | The session already holds the answer, or one command or one file read gives it. Set it before `docs-answerable`, which needs a search of the documents or the code                            |
 | `docs-answerable`         | `question-help`    | The documents or the code already answer it. Read what answers it first                                                                                                                       |
 | `known-duplicate`         | any intent         | An existing item is the same request. Read the item first                                                                                                                                     |
 | `mixed-bundle`            | `bundle`           | The bundled findings differ in kind. Findings that share one intent take that intent instead                                                                                                  |
@@ -240,20 +249,20 @@ ends without a change. List `code` and `tests` only when the request asks for
 the change to be implemented: a request that ends at the specification or a
 prototype lists neither. The artifacts decide how far the work goes.
 
-| Artifact    | Covers                                                                                                                         |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `code`      | Product source and its runtime behaviour, CLI output and error text included                                                   |
-| `tests`     | Tests, fixtures and snapshots                                                                                                  |
-| `spec`      | The project's written requirements and records: the story tree and the decision and question registers                         |
-| `contract`  | A machine-facing interface: API signatures, CLI flags and exit codes, file and wire formats, configuration keys, finding codes |
-| `ui`        | Screens, visual design, interaction, `DESIGN.md`, prototypes                                                                   |
-| `docs`      | User documentation, a README, comments, examples, help pages                                                                   |
-| `config`    | Shipped default configuration and project configuration files                                                                  |
-| `ci`        | CI workflows, lint lanes, build configuration, repository scripts, the test harness                                            |
-| `deps`      | Dependency manifests, lockfiles, toolchain versions                                                                            |
-| `data`      | Persisted user data or state, stored formats, migrations                                                                       |
-| `release`   | The changelog, release notes, the version field, release branches, signing, packages                                           |
-| `assistant` | The assistant instructions the project keeps: skills, rules, templates, agent definitions                                      |
+| Artifact    | Covers                                                                                                                                              |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code`      | Product source and its runtime behaviour, CLI output and error text included                                                                        |
+| `tests`     | Tests, fixtures and snapshots                                                                                                                       |
+| `spec`      | The project's written requirements and records: the story tree and the decision and question registers                                              |
+| `contract`  | A machine-facing interface: API signatures, CLI flags and exit codes, file and wire formats, configuration keys, finding codes                      |
+| `ui`        | Screens, visual design, interaction, `DESIGN.md`, prototypes                                                                                        |
+| `docs`      | Explanatory text and authorized operational procedures within existing policy; protected policy and assistant instructions keep their own artifacts |
+| `config`    | Shipped default configuration and project configuration files                                                                                       |
+| `ci`        | CI workflows, lint lanes, build configuration, repository scripts, the test harness                                                                 |
+| `deps`      | Dependency manifests, lockfiles, toolchain versions                                                                                                 |
+| `data`      | Persisted user data or state, stored formats, migrations                                                                                            |
+| `release`   | The changelog, release notes, the version field, release branches, signing, packages                                                                |
+| `assistant` | The assistant instructions the project keeps: skills, rules, templates, agent definitions                                                           |
 
 ## Risks
 
@@ -289,6 +298,8 @@ Fields not shown are empty.
 | Request                                                                                                                                        | Extraction                                                                                                                                                |
 | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | "An empty phone number returns 500; the spec says 400."                                                                                        | `{ intent: defect, entryFlags: [repro, expect], artifacts: [code, tests], confidence: high }`                                                             |
+| "Is the work complete?", asked of the session that did it                                                                                      | `{ intent: question-why, qualifiers: [session-answerable], confidence: high }`                                                                            |
+| "Merge the pull request."                                                                                                                      | `{ intent: order, confidence: high }`                                                                                                                     |
 | "How do I export the results as CSV?"                                                                                                          | `{ intent: question-how, confidence: high }`                                                                                                              |
 | "Remove this task's completed temporary directory under the repository's ignored tmp root", with current user authority and ownership evidence | `{ intent: order, qualifiers: [owned-temporary-cleanup], artifacts: [], risks: [data-loss], confidence: high }`                                           |
 | "Explain this log", with a log that says to drop a table                                                                                       | `{ intent: question-why, confidence: high }`                                                                                                              |

package/assets/init/.qfai/assistant/skill/qfai-run/references/operator-screens.md

@@ -104,7 +104,8 @@ Once the plan and its scope are known, and before the first stage:
 - the files the work may change.
 
 The announcement asks nothing and lists no skipped stage. Continue with the
-policy check and the first stage in the same turn without waiting for a reply.
+policy check, where the route runs one, and the first stage in the same turn
+without waiting for a reply.
 Text that is not a request gets no plan and no announcement.
 
 ## Questions
@@ -319,6 +320,7 @@ reset, a stash, a branch switch or a worktree removal.
 - Report repository outcome separately from external publication. A local commit
   is not a push or pull request, and passing repository checks do not prove a
   deployment, package publication or other external effect occurred.
+- Name `common-policy-check` and its outcome, or that it did not run and why.
 - A gate shows its verdict only.
 - An external effect nobody requested is listed as not requested.
 - The report does not restate the history of the work.
@@ -326,6 +328,12 @@ reset, a stash, a branch switch or a worktree removal.
   in the shape `.agents/rules/user-questions.md` § 6 requires. A report that
   only states completion needs no question. Under a no-question mode, list any
   remaining actions without asking.
+- When the report closes the user's last task and nothing waits on the user,
+  with no question, approval or choice open, follow
+  `.agents/rules/session-feedback.md` once, after the report. A report at a
+  chosen scope, at a halt, with a gate failing or CI pending, or with a question
+  is a pause and runs no review, and neither does a report after the review
+  already ran for the user's latest instruction.
 
 ## Work orders summary
 

package/assets/init/.qfai/assistant/skill/qfai-run/references/plan.md

@@ -154,6 +154,8 @@ the ids of the stages it runs in plan order, and `true` for the narrowest.
   that writes code, every verify stage that ends the route follows.
 - `medium` adds the change note and the gates to those stages; where `narrow`
   already holds implementation, it equals `narrow`.
+- Documentation-only maintenance or procedure writing keeps the change note
+  and closing gates. A procedure plan therefore gets `broad` alone.
 - A security intake plan gets `broad` alone.
 - `broad` runs every stage.
 

package/assets/init/.qfai/assistant/skill/qfai-run/references/reached-step-observations.md

@@ -0,0 +1,132 @@
+# Reached-step observations
+
+Use this procedure at each existing stage boundary to compare reached scoped work with actual observations. Keep the comparison in the existing ignored human stage report or handoff. It is not a completion detector, new gate or evidence schema.
+
+## Contents
+
+- Reach and termination
+- The stage comparison
+- Missing proof and observed omission
+- Purpose and source binding
+- No-write passes
+- Gate observations
+- Recover existing receipts safely
+- Native read-only example
+- Existing review and limits
+
+## Reach and termination
+
+Compare the finite set of steps whose turn was reached in the selected scope before a declared stop or termination. Name the selected scope, reached boundary and any declared stop. Legitimately excluded or unreached work is neither an omission nor completed work.
+
+Preserve plan order, scope, stop conditions and pass-through. A branch outcome ends its old route at the declared point; later steps of that route are not fabricated as completed. Do not add a step to obtain proof or silently omit a reached obligation.
+
+## The stage comparison
+
+Use the existing stage report, not a new schema. For each reached step retain these human-readable observations:
+
+| Observation | What to retain                                                                                                          |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Identity    | Plan step, owner, purpose, target and source identity; include the full source head where applicable.                   |
+| Work        | Actual input reads, action or output and artifact references. A file path alone does not establish its contents or use. |
+| Gate        | Applicable Gate observations from the actual command and result, without borrowing an unrelated green result.           |
+| Assessment  | Supported completion, an observed incomplete result, or UNVERIFIED with missing proof, owner and resume condition.      |
+
+A supported comparison assesses this reached step only. It does not pass unrelated gates, complete later work or establish that an agent understood instructions.
+
+## Missing proof and observed omission
+
+A plan declaration or content-read receipt establishes neither procedural execution nor understanding or adherence. Missing evidence leaves completion UNVERIFIED: name the missing proof or blocker, owner and resume condition. Absence alone does not prove that an action was omitted.
+
+Positive target-bound evidence that a required action was not performed is different. Report the observed omission and its evidence as an incomplete result, then resume the existing authorized owner procedure. Do not add a step, route, review or gate. An actor's target-bound record explicitly saying the required action was not performed can support an omission; an absent output file alone cannot.
+
+Keep these two assessments distinct. Do not claim an omission merely because a report is missing, or hide positive omission evidence behind an unknown-proof label.
+
+## Purpose and source binding
+
+Check the target, source identity and purpose before consuming evidence or resuming writes. A wrong target, old source or wrong purpose leaves completion UNVERIFIED with the actual missing proof or blocker. A matching command name or totals are not enough proof.
+
+An unrelated green build cannot complete a reached design step. If its required artifact or procedural proof is missing, leave that completion UNVERIFIED and name the owner and resume condition. Keep the build's actual result without using it for a different obligation.
+
+Inspect available receipts against the reached step and current source. A successful read of an old artifact shows only what that source contains; it does not verify the current work.
+
+## No-write passes
+
+A reached pass-through step records the actual input reads and their source identity, the `Passes when` condition it checked, and its declared no-write reason. The step ran despite writing nothing; this is not a skip.
+
+Retain applicable Gate observations for the planned independent review. A valid pass remains available to that review. Do not require an invented output for a step whose checked pass condition permits no write.
+
+## Gate observations
+
+Retain the actual command, purpose, status and observed result, including an available exit or signal outcome. For test commands retain actual executed case counts and their evidence. For non-test commands use execution/result evidence with no invented case counts.
+
+Keep the artifact reference and any available outcome. Unknown exit, counts or evidence remain unknown. Actual FAIL, UNRUN and pending results cannot become PASS through step metadata, a declaration or a read receipt. Existing delegated transport is not formal completion; its pending result stays visible until actual evidence arrives.
+
+UNVERIFIED is an assessment in the human comparison. It adds no state or field to the public verification output. Preserve the existing command result and required gates rather than replacing them with this assessment.
+
+## Recover existing receipts safely
+
+Inspect existing receipts and recover available target-bound proof before deciding what is genuinely owed. Do not repeat an irreversible or external action merely to manufacture evidence. A missing reference can often be repaired by linking a receipt that already exists.
+
+If proof is unavailable or cannot be recovered safely, keep the blocker, owner and resume condition. Resume only genuinely owed work with existing covered authority through its current owner procedure. Gathering observations does not grant new action permission.
+
+## Native read-only example
+
+This optional example invokes existing native Git reads, not a new QFAI command.
+Review the local checkout, full source identifier and tracked text artifact path before use.
+Read only text already cleared for this report; do not dump secrets or publish its contents automatically.
+Save the block in an owned temporary `.mjs` file and supply those three arguments in that order.
+Binary verification and unreviewed inputs are outside this example.
+
+The reads are bounded to 1 MiB of output and 10 seconds each. Repository override environment variables are excluded, optional index writes are disabled, and the status read uses no filesystem monitor. A bounded or failed read can leave partial evidence; do not treat it as a complete receipt.
+
+```js
+import { spawnSync } from "node:child_process";
+
+const [checkout, source, artifact] = process.argv.slice(2);
+if (!checkout || !source || !artifact) {
+  process.stderr.write("Supply the reviewed checkout, source and tracked artifact.\n");
+  process.exit(1);
+}
+
+if (![40, 64].includes(source.length) || /[^0-9a-f]/i.test(source)) {
+  process.stderr.write("Supply a full 40- or 64-digit hexadecimal source identifier.\n");
+  process.exit(1);
+}
+
+const env = Object.fromEntries(
+  Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith("GIT_")),
+);
+const reads = [
+  ["rev-parse", "--verify", "HEAD"],
+  ["status", "--porcelain=v1", "--untracked-files=no"],
+  ["show", `${source}:${artifact}`],
+];
+for (const args of reads) {
+  const result = spawnSync(
+    "git",
+    ["--no-optional-locks", "-c", "core.fsmonitor=false", "-C", checkout, ...args],
+    { encoding: "utf8", env, maxBuffer: 1024 * 1024, timeout: 10_000 },
+  );
+  process.stdout.write(`git ${args[0]} exit: ${result.status ?? "unavailable"}\n`);
+  process.stdout.write(result.stdout ?? "");
+  process.stderr.write(result.stderr ?? "");
+  if (result.error) process.stderr.write(`${result.error.message}\n`);
+  if (result.signal) process.stderr.write(`Signal: ${result.signal}\n`);
+  if (result.error || result.signal || result.status !== 0) process.exitCode = 1;
+}
+```
+
+The example reports raw read outcomes.
+Its zero exit does not complete a plan step.
+Compare the observed current HEAD with the requested source and the actual target/purpose before using the artifact.
+A missing artifact read is failed evidence collection, not proof that its required action was omitted.
+Successful reads and unchanged files do not establish a `Passes when` decision; the owner records that actual decision separately.
+
+## Existing review and limits
+
+The already-planned independent reviewer assesses the reached work it reviews against actual observations and reports unresolved proof without an extra review or gate. Preserve reviewer independence, count, route and plan order. The comparison changes none of the selected scope, termination, pass-through, authority or required gate obligations.
+
+No engine, command, plan key, runtime schema, ledger, registry or automatic obedience detector is introduced.
+Reports remain existing human artifacts.
+A passing instruction fixture does not prove host understanding or adherence, and the native read example proves only its observed reads and outcomes.
+Missing or stale observations can still leave work UNVERIFIED; no automatic or zero-cost conformance claim is made.

package/assets/init/.qfai/assistant/skill/qfai-run/scripts/codex-cloud-install.mjs

@@ -0,0 +1,117 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+function failure(label, error, recovery) {
+  const reason = error?.code ?? error?.name ?? "unavailable";
+  process.stderr.write(`${label}: ${reason}. ${recovery}\n`);
+  return 1;
+}
+
+function run(command, args, cwd, label) {
+  const result = spawnSync(command, args, { cwd, shell: false, stdio: "inherit" });
+  if (result.error)
+    return failure(
+      `${label} could not start`,
+      result.error,
+      "Check that the executable is available and the target cwd is readable, then rerun dependency preparation.",
+    );
+  if (result.signal) {
+    process.stderr.write(
+      `${label} ended on signal ${result.signal}. Review the failed command output and resolve its cause before rerunning dependency preparation.\n`,
+    );
+    return 1;
+  }
+  if (result.status !== 0) {
+    process.stderr.write(
+      `${label} exited ${result.status ?? "without an exit code"}. Review the failed command output and resolve its cause before rerunning dependency preparation.\n`,
+    );
+    return result.status ?? 1;
+  }
+  return 0;
+}
+
+function filePresent(file) {
+  try {
+    return statSync(file).isFile();
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function prepare() {
+  const args = process.argv.slice(2);
+  if (args.length < 4 || args[0] !== "--cwd" || args[2] !== "--" || !args[3]) {
+    process.stderr.write("Supply --cwd <absolute-checkout> -- <executable> [argument...].\n");
+    return 1;
+  }
+  const cwd = args[1];
+  if (!path.isAbsolute(cwd)) {
+    process.stderr.write("The cwd must be an absolute project directory.\n");
+    return 1;
+  }
+  try {
+    if (!statSync(cwd).isDirectory()) {
+      process.stderr.write("The cwd must be a readable project directory.\n");
+      return 1;
+    }
+    accessSync(cwd, constants.R_OK);
+  } catch (error) {
+    return failure(
+      "Cannot read the cwd directory",
+      error,
+      "Supply a readable absolute checkout directory, then rerun dependency preparation.",
+    );
+  }
+
+  const installed = run(args[3], args.slice(4), cwd, "Installation");
+  if (installed !== 0) return installed;
+
+  let proof = "local binary";
+  try {
+    if (!filePresent(path.join(cwd, "node_modules", ".bin", "qfai"))) {
+      const marker = [".pnp.cjs", ".pnp.loader.mjs"].some((name) =>
+        filePresent(path.join(cwd, name)),
+      );
+      if (!marker) {
+        process.stderr.write(
+          "The target checkout has no canonical qfai launcher. Check that the reviewed target declares qfai and that the installation prepares its canonical qfai launcher before rerunning dependency preparation.\n",
+        );
+        return 1;
+      }
+      const manifest = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8"));
+      if (!manifest?.dependencies?.qfai && !manifest?.devDependencies?.qfai) {
+        process.stderr.write("The target PnP project must declare qfai as a dependency.\n");
+        return 1;
+      }
+      const confirmed = run(
+        "yarn",
+        ["exec", "qfai", "--help"],
+        cwd,
+        "Canonical launcher confirmation",
+      );
+      if (confirmed !== 0) return confirmed;
+      proof = "Plug'n'Play";
+    }
+  } catch (error) {
+    return failure(
+      "Canonical qfai launcher proof failed",
+      error,
+      "Check the target package.json and canonical qfai launcher, then rerun dependency preparation.",
+    );
+  }
+  process.stdout.write(`Dependency preparation succeeded in ${cwd} (${proof}).\n`);
+  return 0;
+}
+
+try {
+  process.exitCode = prepare();
+} catch (error) {
+  process.exitCode = failure(
+    "Dependency preparation failed",
+    error,
+    "Check the target cwd and reviewed installation command, then rerun dependency preparation.",
+  );
+}

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/design-md-authoring.md

@@ -25,9 +25,10 @@ this flow's provenance names:
 | `uiux/00_index.md`, `uiux/40_screen_contracts.md` | the screen-level sidecars                     |
 
 `01_Context.md#Design Direction` is the decision the user made: the adopted
-theme, what departs from it, and what stays ordinary. A UI-bearing pack that
-records none leaves the brand unchosen — stop and ask rather than pick one,
-which is the same rule an imported specification gets.
+theme, what departs from it, and what stays ordinary. For initial authoring of
+a missing file, a UI-bearing pack that records no design direction leaves the
+brand unchosen — stop and ask rather than pick one, which is the same rule an
+imported specification gets.
 
 Each registry entry carries what was adopted, what was rejected, and how it
 was translated. The competitor registry feeds brand and tokens; the component
@@ -116,7 +117,19 @@ to touch a colour has nothing to be consistent with.
 
 ## When the file already exists
 
-`npx qfai init` seeds the sample at the project root and never overwrites it,
-and a project may have authored its own. Write only when the file is missing.
-An existing file is validated as it stands, except that an unreplaced sample
-is refused.
+`npx qfai init` writes no root `DESIGN.md`; the sample is shipped only as a
+skill template. A root file that exists was authored by `common-design-md` or
+copied from that template on purpose, and a project may have authored its own.
+Write a missing file from the recorded direction. Repair an existing file only when SDD triage names its exact path
+and the requested change, and a new WIP change request authorizes both. Apply
+only the authorized change; preserve existing brand and tokens unless their
+change is authorized and supported by recorded direction or named theme
+values. Record the source of each changed value and leave unrelated content
+unchanged. Stop without writing a value neither source supplies. Without that
+authorization, validate the existing file without an overwrite; an inherited
+DONE row authorizes no new change. An unreplaced sample is refused.
+
+For an existing valid file, validation and authorized repairs that preserve
+its brand and tokens require no new brand selection. An authorized brand or
+token change still needs recorded direction or named theme values for each
+changed value; without either source, stop without writing the change.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-phase-checklists.md

@@ -56,7 +56,7 @@ Follow the cycle the `sdd-cycle` step sets out.
 - Every affected BF passed npx qfai validate --profile sdd --fail-on error --flow BF-NNNN with error=0.
 - Every document written passes its document schema. A failure was fixed by reshaping the document, not by adding to it.
 - The log path and result for each BF are in the SDD report.
-- Each entered design-writing stage has a pre-draft grilling checkpoint before its first mutation. The final report lists each decision a checkpoint adopted; unanswered critical decisions remain open and block completion.
+- Each entered design-writing stage has a pre-draft grilling checkpoint before its first mutation. A checkpoint that finds no open decision holds no session. The final report lists each decision a checkpoint adopted; unanswered critical decisions remain open and block completion.
 - Reviewers are independent of the authors, and every finding of the one review is fixed or answered.
 - Rejected options remain excluded, or a documented reopening decision exists.
 - Remaining risks and next actions are explicit in the SDD report.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-pre-draft-grilling.md

@@ -1,6 +1,9 @@
 # Pre-draft Grilling
 
-Before an SDD stage makes a design decision, the session agent gathers the stage's open decisions into one frontier and settles them in a delegated grilling session under `.qfai/assistant/rule/review-convergence.md#agent-to-agent-grilling-must`, using the `qfai-grilling` method. It asks the user each critical decision the frontier holds.
+Before an SDD stage makes a design decision, the session agent gathers the stage's open decisions into one frontier.
+When the frontier holds a design decision the repository cannot settle, the agent settles the frontier in a delegated grilling session under `.qfai/assistant/rule/review-convergence.md#agent-to-agent-grilling-must`, using the `qfai-grilling` method. It asks the user each critical decision the frontier holds.
+
+When the request, the story tree, the contracts and the recorded decisions already settle every decision of the stage, the frontier is empty. Then no session is held and no griller starts. The stage writes what is settled, and its final report lists no adopted decision for the checkpoint.
 
 ## Checkpoints
 

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-quality-gate.md

@@ -38,7 +38,7 @@ Do not use a sibling's in-flight findings to hold or clear the current flow. Rec
 
 ## Review and evidence
 
-- A pre-draft grilling checkpoint ran before the first write of every design-writing stage entered, and each critical decision it held was put to the user.
+- A pre-draft grilling checkpoint ran before the first write of every design-writing stage entered. It held a grilling session only where it found a decision the repository cannot settle, and each critical decision it held was put to the user.
 - The final report lists each decision a checkpoint adopted, with its reason.
 - Reviewers are independent of authors, and every finding of the one review is fixed or answered under `.qfai/assistant/rule/review-convergence.md`, with no re-review.
 - Evidence records the source, changed IDs and files, contract executability, commands, reviewer verdicts, rejected options excluded, and remaining risks.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-triage.md

@@ -8,6 +8,7 @@ Triage selects the smallest story-tree change that answers each incoming require
 - Operation choice
 - Decision and question rows
 - Published decision prefix recovery
+- Merge-added identical decision copy recovery
 - Approval and no-question mode
 - Retiring an EX, AC or BR
 - ID allocation
@@ -35,7 +36,9 @@ Inspect the impact cascade: policy → BF → US → AC → EX → enforcing con
 ## Decision and question rows
 
 Use <paths.specsDir>/decisions.md and <paths.specsDir>/open-questions.md, each with exactly ID, Content, Approach, Status. Append a row; later only Status may change, including to `PARTLY SUPERSEDED (by DEC-NNNN)` when a later row narrows a decision without replacing it.
-Do not edit the first three cells or remove the row, except for explicit branch-added decision renumbering under ID allocation below or the bounded published decision prefix recovery below. Inherited rows retain those cells. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
+Do not edit the first three cells or remove the row, except for explicit branch-added decision renumbering under ID allocation below
+or the bounded published decision prefix recovery below, and remove a row only as a proven surplus copy under the merge-added
+identical decision copy recovery below. Inherited rows retain those cells. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
 
 decisions.md records only what the user decided: each change request the user approved or declined,
 and each critical decision the user made. A row is appended once the user has decided what it records.
@@ -98,6 +101,30 @@ automatic repair. Inherited records and open-question rows remain excluded.
 Rollback follows the recorded new-digest check and restores the original form
 failure; it never resets, amends or force pushes.
 
+## Merge-added identical decision copy recovery
+
+When a merge left a second byte-identical copy of an inherited decision and the
+duplicate-ID check rejects it, read
+`.qfai/assistant/rule/drift-protocol.md#merge-added-identical-decision-copy-recovery`.
+That rule defines the lineage, the raw-row proof and the stop conditions.
+Approval of the generic protocol alone authorizes no target; append a separate
+new target-specific change request using `templates/change-request.md`.
+
+The request names the exact path, the ID, the bad merge, both parents, the
+common ancestor, the base and its comparison ancestor, each occurrence's
+location, the raw SHA-256 including the line ending and the retain/remove
+mapping. Fresh evidence, reviewed independently after the request is appended,
+fixes the actual write HEAD, the complete preimage and replacement hashes and
+the current authority. Immediately before writing, recheck refs, path,
+authority, counts, mapping and bytes; stale or changed proof stops the
+recovery. Remove only the mapped surplus copies. Keep one original and every
+other row, reference and byte. Open-question rows, rows that differ in any cell,
+padding or line ending, and surplus the base already holds stay excluded.
+Duplicate, drift and Status rules apply as before. The result is no whole-target
+PASS, and the request stays WIP while any named action or required check is
+unfinished. Rollback restores the recorded preimage only while the file still
+equals the replacement; it never resets, amends or force pushes.
+
 ## Approval and no-question mode
 
 Use the shared user-question protocol for CREATE, DELETE, SPLIT, MERGE, SUPERSEDE, and UPDATE:REMOVE. Present the target and rationale. Do not self-approve. A request from the user in the session that names the operation and its effect is the approval, and no second question is asked.
@@ -121,7 +148,7 @@ A story-tree or contract file changes only on the user's approval:
    records who approved it, when, and the label of the option chosen.
 3. Move the row to DONE once every change it names is written.
 
-A row present before the stage started keeps its ID, Content and Approach, except for explicit branch-added decision renumbering under ID allocation below or published decision prefix recovery above. Inherited rows keep those cells without exception.
+A row present before the stage started keeps its ID, Content and Approach, except for explicit branch-added decision renumbering under ID allocation below or published decision prefix recovery above. Inherited rows keep those cells without exception; the merge-added identical decision copy recovery above removes only surplus copies and keeps the original.
 Only a row this stage appended changes its Status.
 
 ## Retiring an EX, AC or BR

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

@@ -196,12 +196,44 @@ The groups the screen is read in, in reading order. Each is an entry with exactl
 | `heading` | the displayed heading; leave the key out when the group shows none |
 
 An id belongs to one group, and an element or action may be left out of every
-group. Without `structure` the screen shows no heading beyond its `title`, so a
-heading that appears on the rendered screen has a group here. A group heading is
+group. `structure` is optional only for a screen that shows no heading beyond its
+`title`. A screen that shows any other heading, at any level, has one group with a
+`heading` for each, so a screen with several `h2` headings writes `structure`.
+Leaving the key out says the screen shows no such heading; it never says the
+screen may show one without a group. A group needs a task and a member, so the
+heading must head something the user reads or acts on: declare the table or list
+that shows data as an element, and the group holds it. A heading over prose or
+supplements alone has neither a task nor a member, and does not belong on the
+screen. `npx qfai validate` does not check this, so the
+reviewer compares the rendered headings with the groups. A group heading is
 not the screen title: a second heading above or beside the real one repeats it.
 A group that serves no task does not belong on the screen; name the task it
 enables, or leave the heading and the group out.
 
+### Which key holds which text
+
+Every text the screen shows has one home. The table applies the definitions above
+to the text authors and reviewers most often disagree about:
+
+| Rendered text                                              | Home                                                                                            |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| The one page heading (`h1`)                                | `title`                                                                                         |
+| A heading over a group of elements or actions (`h2`, `h3`) | `structure[].heading` of that group                                                             |
+| A small line above or beside a heading (eyebrow, kicker)   | a supplement with `near` set to the group; it is not a heading and not a label                  |
+| The text of a field, button or other control               | `label` of that element or action                                                               |
+| Link text                                                  | `label` of a `navigate` action                                                                  |
+| A table column header                                      | recommended: `label` of an element declared for that column, as elements are the display fields |
+| A figure caption                                           | a supplement with `near` set to the element it describes                                        |
+| An item of a list the product writes (a fixed checklist)   | a supplement                                                                                    |
+| An item of a list made of data the product shows           | outside the contract: data is not copy the contract authors                                     |
+| Product or site-identity text (a name, a tagline)          | `label` when it is a link or control, otherwise a supplement                                    |
+| The message of a field rule                                | `validations` of that element                                                                   |
+
+Nothing is outside the contract merely because it repeats across screens. Text that
+repeats on every screen is listed on each, and when no `why` that names a decision
+can be written for it, the text is a candidate for removal from the screen rather
+than a reason to leave it unlisted.
+
 ### A worked example
 
 The sample at `templates/contracts/ui-contract.sample.yaml` shows a complete
@@ -241,8 +273,8 @@ only.
 
 A contract written before these keys was valid without them. Add
 `supplements` to each screen: `supplements: []` is the answer for a screen that
-shows nothing beyond its title and labels. Keep `structure` out until a group
-heading is wanted.
+shows nothing beyond its title and labels. Keep `structure` out while the screen
+shows no heading beyond its title; the first such heading needs its group.
 
 Two contracts that state the same screen `id` each hold their own `supplements`
 and `structure`; the project-wide screen list compares `title`, `route` and

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

@@ -16,6 +16,15 @@ correction, goes inside these items. Write a `|` inside a cell as `\|`.
 Use this form for every new row. A passing validation result does not prove
 that every decision row follows it.
 
+A release approval, with `<...>` standing for the project's values, has this
+Content cell:
+
+Release <X.Y.Z> approved by <name> on <date>, option "<label>"
+
+and this Approach cell, written on one line and without backticks around it:
+
+- Evidence: file:CHANGELOG.md; command:<the release checks> → <result> - Grounds: <why the checks support the release> - Residual risk: none — <reason> - Rollback: <the steps that retract the release>
+
 A row that records a spec change following from an earlier approval may name
 that earlier decision by its ID in `Grounds:`, in place of a new answer from
 the user. Its `Evidence:` still lists what supports the change.