qfai 2.1.1 → 2.2.0

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

@@ -5,12 +5,20 @@ What the user sees while a request is worked, and how a question reaches them.
 ## Contents
 
 - Every screen
+- Launcher recovery
+- Refreshing installed instructions
+- Executing a step
 - The scope question
 - The announcement
 - Questions
+- Repair found by a question-only stage
 - A step only a person can take
+- Authorized external actions
+- Replies to a waiting step
+- Independent targets under one goal
 - Halt notice
 - Final report
+- Work orders summary
 
 ## Every screen
 
@@ -21,6 +29,49 @@ What the user sees while a request is worked, and how a question reaches them.
 - Show nothing while a call is running beyond the host's own activity
   indicator.
 
+## Launcher recovery
+
+Read this section if the canonical launcher is missing or its preflight fails,
+before planning.
+
+Use the project's package manager and declared install command in this checkout:
+
+- If `package.json` declares `qfai`, install the project's dependencies here.
+- If it does not, add `qfai` as a development dependency using that package manager.
+- Repeat the launcher preflight. Plan only after it succeeds.
+
+Never use a published, remote or cached QFAI launcher as a fallback.
+
+## Refreshing installed instructions
+
+Read this section before applying corrected guidance to an adopting project.
+
+Install or update its project-local QFAI dependency using the project's package
+manager and approved package source. Verify that the canonical launcher resolves
+that installation, then inspect the installed step and reference files for the
+required guidance. A source fix or package version string alone does not prove
+that a published package contains it.
+
+Preview the refresh with that verified local launcher using
+`npx qfai init --force --dry-run`. Review the managed files it would replace,
+including any direct local edits, before `npx qfai init --force`. Review the
+resulting diff. Force refresh overwrites managed assistant and rule masters;
+project specs, contracts, rule overlays, `skill.local/`, configuration overrides
+and existing entry documents remain project-owned. Keep them intact; do not
+replace them with templates to make the refresh pass.
+
+## Executing a step
+
+Read this section when a step is short or passes without edits.
+
+Read `STEP.md` at the plan's path and follow its Procedure. Run only its declared
+commands and pass its Gate.
+
+A `passThrough` step first reads what its Passes when section names. If that
+condition holds, write nothing and record the reason in the stage report.
+Do not skip the step. The planned independent review still runs, even when the
+step is only two lines.
+
 ## The scope question
 
 The scopes are the plan's, or the chosen candidate's after the candidate
@@ -52,8 +103,10 @@ Once the plan and its scope are known, and before the first stage:
 - the chosen stages in order;
 - the files the work may change.
 
-It asks nothing and lists no skipped stage. Text that is not a request gets no
-plan and no announcement.
+The announcement asks nothing and lists no skipped stage. Continue with the
+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
 
@@ -77,12 +130,33 @@ Independent questions go in one round; a dependent one waits for its answer.
 - Under a no-question mode nothing is asked. `SKILL.md` says what is done
   instead.
 
+## Repair found by a question-only stage
+
+Read this section when a question-only request finds a defect and its move to
+tracked-file repair lacks explicit authority for the same target.
+
+Show the defect and its evidence, the proposed repair scope and the planned
+checks. Put one question through the structured question tool in the form
+`.agents/rules/user-questions.md` requires:
+
+- **Repair:** authorize the stated repair and checks for this target.
+- **Report and stop:** report the finding and stop this target without edits.
+
+Write nothing before the answer. Repair permission takes the destination's
+existing plan; add no stage or scope. The guards for a third branch move, a
+scope that leaves stages out and release approval still apply.
+
+Under a no-question mode, report the defect and required repair permission and
+stop that target. Write no tracked `open-questions.md` row for this choice;
+asking for no questions alone supplies no repair authority. Other authorized
+independent targets may continue.
+
 ## A step only a person can take
 
-A change can depend on an action outside the repository that only the user can
-take: a setting in a hosted dashboard, or a credential issued in a service's
-web console. The plan stays the repository change. The work stops before the
-stage that needs the action and says three things:
+A change can depend on a step only a person can take: interactive login, a
+new permission grant or an expansion of authority. The plan stays the
+repository change. The work stops before the stage that needs that action
+and says three things:
 
 - what the user must do, in plain words, and where;
 - what shows it was done;
@@ -93,14 +167,130 @@ Put it as one question that ends the turn, in the form
 `.agents/rules/user-questions.md` sets out. The options are that the user did
 it, and `stop`.
 
-- The agent never types a password, token or key, and never changes an account
-  or service setting. The user does both in the service's own page.
+- The user completes person-only login, new permission grants and authority
+  expansion in the service's own page. A human-run or triage handoff never
+  performs the user's operation on their behalf.
 - The agent reads only the evidence it named. It reports the action as
   confirmed or not confirmed, and goes on after it only when confirmed or the
   user says to go on.
 - Under a no-question mode nothing is asked. The work that does not depend on
   the action goes on, and the final report lists the action as not done.
 
+## Authorized external actions
+
+Read this section when a repository change needs an account setting or a
+credential installed outside the repository.
+
+An agent may perform that action only when prior user instructions or project
+policy cover the specific target and action, and the host provides an allowed
+safe channel. A connector's availability alone proves neither authority nor
+access. Reuse covering authority without inventing a new permission grant.
+
+Check that the actual credential's account, project, scope and expiry fit that
+authority. One-time permission is not continuing access. Third-party credential
+ownership needs its own authority; permission for this project does not supply
+it. Use only the host's actual safe channel for credential installation. Never
+put a password, token or key in chat, logs or tracked files, or ask the user to
+paste it there. Interactive login, new permission grants and authority expansion
+remain person-only actions.
+
+If authority, credential ownership or a safe channel is absent or unknown, or
+the host denies the action, stop the dependent action. Give concrete manual
+steps, the evidence that would confirm them and a read-only verification check.
+Do not bypass the denial or infer missing authority from a generic request to
+proceed. Keep a human-run or triage handoff as a handoff; other authorized
+independent work may continue.
+
+Record host access or CI start, authorization, credential installation, CI
+results, merge and publication separately in the existing stage report. For
+each relevant effect state confirmed, pending, unverified or not requested,
+with its target, exact revision, evidence URL when available, blocker and
+resume condition where needed. Missing evidence stays unverified. A green CI
+result proves neither merge nor publication. Report the implemented repository
+change separately from unverified external effects.
+
+## Replies to a waiting step
+
+Read this section before treating a user's reply as a new request.
+
+- A reply answering a pending question or reporting the requested operation's
+  result resumes the same waiting step, including a reported failure. Use no
+  new plan and no skill invocation for that reply.
+- Free text supplying the requested value is an answer to that waiting step,
+  even if it does not repeat an option label.
+  Never treat an unrelated instruction as selection or approval of an option.
+- Dismissal or no response is not an answer or permission. Continue a routine
+  choice only under authorization the user already gave. A missing hard-required
+  fact, uncovered mandatory approval, cancellation or explicit tool block stays
+  protected; do only independent work that remains authorized.
+- An independent new request is planned under the extraction and scope rules
+  in `SKILL.md`. If a reply also contains one, resume the waiting step with its
+  answer and plan the independent request separately.
+- A separate explicit request to investigate the failure or repeat the operation
+  is planned as a new request under those same rules.
+- An answer to a closed request for information follows only the plan's branch
+  for received information. Add no branch or step.
+- For an ambiguous reply, do not assume success, completion, new facts or
+  approval. State what remains unconfirmed. Ask for any fact or decision still
+  needed under the normal question rules.
+
+Background waiting needs no question. Report the current state, awaited
+evidence or result and resume condition; promise no automatic restart unless
+the host provides it. Follow `.agents/rules/user-questions.md` § 6 when an
+answer is needed. A completion-only final report needs no question.
+
+## Independent targets under one goal
+
+Read this section before handling several independent targets under one goal
+or switching the checkout during a target's wait.
+
+Plan each target separately only when its scope is settled and independent.
+Keep each plan's scope, stage order, steps, review and release points. A target
+with an unfinished prerequisite waits; mixed findings with unsettled scopes
+still take the existing bundle/decomposition handling. Give newly eligible
+targets within the goal's criteria their own plans. Report an out-of-scope
+finding as a follow-up, never as an extra step in the current target.
+If no planned stage serves work this target needs, stop that target and name
+the owner and stage skill to invoke. Other authorized independent targets may
+continue.
+
+Use the existing stage reports and handoff messages to retain each target's
+plan and scope, stage and step, branch and exact head, evidence, open approval
+or blocker, and resume condition. Report waiting targets as waiting. Before
+writing or using a result, confirm its target and head. A green check for an
+older or different head does not pass the current one; pending checks do not
+complete verification. A matching red check resumes the planned gate and its
+fix procedure. Keep each review verdict bound to the commit reviewed; never
+relabel it as a review of a newer head or add a review the plan does not name.
+
+Before changing the shared checkout, wait for every writer and local gate
+using it, preserve target edits in a permitted commit of only its paths, and
+ensure the whole index and worktree are clean. Unknown dirty files postpone
+the switch; do not stash, reset or delete them to move on. A reviewer using
+live files or checkout-dependent execution must finish. A read-only reviewer
+using only `git show <fixed SHA>:<path>` may continue across a clean orchestrator switch;
+the reviewer never switches the checkout. CI-only pending gates use the
+existing DELEGATED commit allowance only under a user instruction or project
+policy covering that verification commit and its tracked paths. The project
+must declare the gate CI-only and name its actual check. Every nondelegated gate
+must pass. A delegated red check stops transport of the same unchanged candidate.
+Explicit CI-only delegation covering transport may instead carry actual changes
+addressing that failure through the existing planned fix into a new candidate,
+even while HEAD names the failed commit. Keep the prior head, check, run and
+observed result as FAIL; never relabel that evidence pending. Report the actual
+fix and the new head after committing. Its missing or pending CI result leaves
+verification incomplete. Ordinary FAIL or UNRUN still stops the commit. A commit
+grants no push or pull request authority: each remote action needs its own covered
+instruction or policy. Waiting alone never authorizes a commit or skipped gate.
+
+Use standing delegation only for the targets and actions it actually covers.
+Report routine choices as the agent's decisions under that authority, never
+as the user's individual option approval. A request to ask nothing supplies
+no uncovered approval. If a critical decision or release approval is missing,
+stop that target before dependent work and follow the existing question or
+no-question rules. Other authorized independent work may continue. A stop of
+the whole goal stops every target.
+
 ## Halt notice
 
 One notice when the work stops before its end:
@@ -121,10 +311,35 @@ reset, a stash, a branch switch or a worktree removal.
 | At the chosen scope                   | The chosen stages complete, the stages not chosen, and a verdict for each gate that ran, never that a change is done |
 | At a closing step                     | The closure outcome and each follow-up request, never that a change is done                                          |
 | With a gate failing                   | Each failing gate marked pre-existing or new, with its owner. Nothing reads as complete                              |
+| With delegated CI pending             | The verification commit, pending checks and resume condition; verification remains incomplete                        |
 
+- For a CI wait, name the target, current head, run ID or URL when available,
+  check, actual outcome and counts, blocker and resume condition. State when no
+  run exists. Missing, red or mismatched evidence stops formal completion or
+  merge; every required check needs actual passing evidence for the current head.
+- 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.
-- The report ends with a question listing the next actions, the recommended one
-  first, as `.agents/rules/user-questions.md` § 6 sets out. Under a no-question
-  mode it lists them instead.
+- Ask for the next action only when proceeding requires the user's answer,
+  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
+
+Read this section when parts ran in parallel. Report one row per part given to
+a sub-agent.
+
+| Step | Role (sub-agent) | Agent instance  | Task title        | Input (refs)  | Output (refs) | Status (PASS/REVISE/PENDING) |
+| ---- | ---------------- | --------------- | ----------------- | ------------- | ------------- | ---------------------------- |
+| 1    | `<role>`         | `<instance id>` | `<part in words>` | The step file | The result    | PASS/REVISE                  |

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.
 
@@ -181,9 +183,10 @@ keeps its scopes: `--route` returns none.
 `schema` for an extraction field, naming its `cause`: `missing` for a required
 field that is absent, `unknown` for a key the extraction does not take,
 `wrong-type` for a value of another type, `wrong-value` for a value outside the
-field's vocabulary, and `invalid` for the rule that ties `alternatives` to
-`confidence`; each cause states what was expected and received, or the field
-name. `unknown-route` for a route the catalog does
+field's vocabulary, and `invalid` for the rules tying `alternatives` to
+`confidence` or requiring `owned-temporary-cleanup` to use `intent: order` and
+empty `artifacts`, including alternative readings. Each cause states what was
+expected and received, or the field name. `unknown-route` for a route the catalog does
 not name, `plan-invalid` for a plan that does not load, naming its `file` and
 `cause`, `artifact-unserved` for an artifact the extraction names when no stage
 of the route writes any artifact it names, so the work stops before the first

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/references/stage-points.md

@@ -8,6 +8,10 @@ Before a step `releasePoint` names runs, ask the user to approve the release; wh
 `verify-commit` runs after that, so the commit holds the approval. Nothing after it
 runs without the approval, which authorizes no push, merge, tag or publication.
 
+After approval at a handoff release point, `qfai-run` writes the required
+approval row in `decisions.md` before `triage-handoff` runs. Every triage step
+still changes no tracked file. No handed-off operation runs on the user's behalf.
+
 ## Decision point
 
 At a step `decisionPoints` names, put each critical
@@ -19,6 +23,16 @@ yourself, ask nothing, and list it with its reason in the final report.
 
 ## Branch point
 
+A question-only request with `artifacts: []` may move to a route that writes
+tracked files only under explicit same-target repair authority from the user's
+request or project policy. Reuse that authority without another repair
+question. Otherwise, show the defect evidence, repair scope and planned checks
+and ask through the structured question tool: repair, or report and stop.
+Write nothing before the answer. Under a no-question mode with no covering
+authority, report the defect and required permission and stop that target;
+write no tracked `open-questions.md` row. Asking for no questions alone grants
+no repair authority.
+
 When a step `branchPoints` names reports an outcome
 paired with one route, move there; with several, to the one the step
 names; with `decision-table`, to the route `plan --in` gives the step's

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

@@ -91,9 +91,10 @@ Report the source selected, BF and US IDs touched, decision and OQ IDs, contract
 files and index rows, each per-flow validation result and log, independent
 reviewer verdicts, adopted grilling decisions, rejected options still excluded,
 and remaining questions. The next implementation route is `/qfai-implement`; UI work
-may pass through `/qfai-prototyping` first. The report ends with a question
-listing those next actions, as `.agents/rules/user-questions.md` § 6 sets out.
-Under a no-question mode, list them in the report instead.
+may pass through `/qfai-prototyping` first. Ask about those next actions 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-sdd/references/contract-artifact-rules.md

@@ -53,6 +53,7 @@ Discussion UI/UX files are **non-normative** discovery / reference artifacts —
   not only where the attribute is written out — a framework that builds the
   attribute from a variable still writes the marker somewhere.
 - **Every entry under `screens` is a screen, once.** Each UI-bearing contract declares one full `UI-NNNN` ID and a nonempty `screens[]` list. Each screen has an ID and route, unique within its contract. The prototyping cycle covers all declared UI-bearing contract IDs; filenames do not select a legacy spec tier. `QFAI-CONTRACT-042` names malformed screen entries.
+- **Every screen states the text it shows.** A screen declares `supplements` (`[]` when it shows none) and may declare `structure`. `QFAI-CONTRACT-043` names a key that is absent or malformed, `QFAI-CONTRACT-044` an id the screen does not declare, and `QFAI-CONTRACT-045` a text shown twice.
 - **A contract's ID comes from its directory.** `api/` holds `API` contracts,
   `db/` `DB` and `ui/` `UI`; the QFAI repository's own `cli/` holds `CLI`
   contracts. The ID is `<KIND>-NNNN`.