qfai 2.1.1 → 2.2.0

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

@@ -0,0 +1,273 @@
+# Place stories and write the documents
+
+What the bundled steps need from a person before they place stories and
+rules, and the shape of what steps 1 to 7 write: the plan, the retired
+configuration keys, the contract numbers, the business rules and the story-tree
+documents.
+
+## Contents
+
+- Place stories and rules
+- Retired configuration keys
+- Contract IDs
+- Business rules
+- Documents in their template's shape
+
+## Place stories and rules
+
+The AI writes `tmp/qfai-migration/plan.yaml` before running
+step 4. `plan.yaml` may be written before step 1, because only steps 4 and 7
+read it and a contract is named by the path it has in the contracts directory
+before step 3, which is also a key of `contract-map.json` once step 3 has run.
+
+The plan states the decisions the scripts cannot make. `flows` says which
+business flow holds each old story. `rules` says which existing contract
+enforces each old business rule, or that it enforces none. The optional
+`examples` list places an example whose criterion the test cases leave open.
+Flow order and story order determine the new IDs.
+
+- **`from`.** A `from` value identifies an old flow to continue; omit it for a
+  new flow. It is the exact title of any H2 section of the old
+  `_policies/04_Business-Flow.md`, and no other H2 of that file has the same
+  title. For the unnamed opening flow, which is the text before the first
+  `CHG-` heading or the whole file where it has none, use the reserved value
+  `_policies/04_Business-Flow.md`. Several flows may continue the same section,
+  and each takes that section's prose and diagram. If `from` is omitted, the
+  script writes a template flow and reports that its diagram needs a person.
+- **`criteria`.** An old criterion belongs to the story its `Parent:` line
+  names or, where it has none, to the story its row of the criteria catalog
+  table names in the `US Ref`, `US-Refs` or `Maps To` column. Add `criteria`
+  to a story only when the criterion has no such reference, the reference
+  names several stories, or the two disagree.
+- **`contract`.** A contract path is relative to the configured contracts
+  directory, lies under `cli/`, `api/`, `db/` or `ui/`, and names the contract
+  file as it is before step 3 renames it. A Markdown file under `api/`, `db/`
+  or `ui/` and a file under `design/` hold no contract, so a rule cannot be
+  placed in one.
+- **`binds: none` and `retire`.** A rule with no contract takes one of these
+  instead of `contract`. `binds: none` is allowed only where the rule's
+  `Contract-Refs` cell is `-`. `retire` takes a reason. Step 7 removes such a
+  rule from its `04_Business-Rules.md`, lists it under `## Operations` with
+  its old ID and, for `retire`, the reason, and gives it no new ID.
+- **`examples`.** An entry names an old example ID and a `criterion`, one of
+  the old criterion IDs that the `AC-Refs` of the test cases citing the example
+  name. Step 4 places the example under that criterion's story, and its test
+  cases enter the ID map, so that step 8 rewrites their annotations.
+
+```yaml
+flows:
+  - title: Place an order
+    stories:
+      - id: US-0001-0001
+        criteria: [AC-0001-0001]
+examples:
+  - id: EX-0001-0002
+    criterion: AC-0001-0001
+rules:
+  - id: BR-0006-0001
+    contract: api/orders.yaml
+  - id: BR-0006-0002
+    binds: none
+  - id: BR-0006-0003
+    retire: The payment provider enforces this limit.
+```
+
+Use IDs from the old files in this plan. Assign each old story, rule, example
+and criterion at most once. A `from` value that matches no old flow or matches
+several, an invalid plan, a duplicate assignment, an `examples` criterion that
+none of the citing test cases names, a rule with none or more than one of
+`contract`, `binds` and `retire`, or a contract path that is outside the four
+contract directories or names no contract stops step 4 before writing. Check
+the step-4 dry run before accepting its numbering. Step 4 writes
+`tmp/qfai-migration/id-map.json` once, and later steps use
+that map. Write the `examples` entries and the rule marks before step 4: once
+the map exists, an `examples` entry and a mark on a rule the map holds are
+refused. A mark on a rule step 4 left unplaced is still accepted while a spec
+pack is left. Place any other unplaced content in the new tree through `/qfai-sdd`. While the
+map exists and no spec pack is left, steps 4 and 7 read no plan, so a missing or
+rewritten `plan.yaml` stops nothing.
+
+## Retired configuration keys
+
+Three keys of `qfai.config.yaml` no longer exist in 2.x. Each is handled by the
+step named here:
+
+| Key                                                 | What the migration does                                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `validation.traceability.scMustHaveTest`            | Step 1 removes it and lists it under `## Operations`                                                       |
+| `validation.traceability.unknownContractIdSeverity` | Step 1 removes it and lists it under `## Operations`                                                       |
+| `prototyping.primarySpecId`                         | Step 3 replaces it with `prototyping.primaryUiContract` where exactly one UI contract is tied to that spec |
+
+Step 1 also removes a `validation.traceability` or `validation` mapping that
+the removal leaves empty. Steps 1 to 3 run although the configuration loader
+reports these keys. Steps 4 to 12 refuse with exit 2 before writing, naming the
+key, while `qfai.config.yaml` still holds one of the three. That refusal does
+not mean an earlier step has not run.
+
+A UI contract is tied to a spec when the contract IDs named by the
+`Contract-Refs` of that spec's business rules translate, through the contract
+map, to one UI contract. Step 3 lists the replacement under `## Operations`.
+Where `prototyping.primaryUiContract` is already set, step 3 removes the old key
+instead. Where no UI contract is tied, more than one is, or the spec pack is
+gone, step 3 leaves `prototyping.primarySpecId` and lists it under
+`## For a person` with its old value, and exits 3. Replace it by hand with
+`prototyping.primaryUiContract: UI-NNNN` naming the contract. Steps 4 to 12 then
+run.
+
+When a step cannot load `qfai.config.yaml` for any other reason, it exits 2
+before writing and prints on standard error the message of each configuration
+issue, one per line.
+
+## Contract IDs
+
+Step 3 gives every contract file that has no 2.x contract ID one, and renames
+the file to match:
+
+| Old contract               | Declares       | New ID   | New file                   |
+| -------------------------- | -------------- | -------- | -------------------------- |
+| `cli/orders.md`            | nothing        | CLI-0001 | `cli/cli-0001-orders.md`   |
+| `api/api-0001-orders.yaml` | `CON-API-0001` | API-0002 | `api/api-0002-orders.yaml` |
+| `db/db-0001-orders.sql`    | `CON-DB-0001`  | DB-0003  | `db/db-0003-orders.sql`    |
+
+- Numbers run across all contracts, in the order CLI, API, DB, UI, then by
+  the old number, then by path. No two contracts share a number.
+- The new ID replaces the old one in the file's declaration: the H1 of a
+  Markdown contract, as `# CLI-0001: <title>`, and the `QFAI-CONTRACT-ID` line
+  of any other. The old IDs in `-- Depends on:` and `x-qfai-depends-on` become
+  the new ones, and a YAML contract keeps its `x-qfai-depends-on` list on one
+  line.
+- `contracts.md` becomes one index table listing every contract. The old
+  index's other sections are reported for a person.
+- `tmp/qfai-migration/contract-map.json` records each old
+  path and old ID with the new ones, and step 4 copies it into the ID map.
+- Step 7 writes the new IDs into rule statements, and step 8 changes a
+  `QFAI:CON-API-0001` test annotation to `QFAI:API-0002`.
+
+Step 3 gives no ID to a file that is not a 2.x contract, and does not write it
+into the new tree:
+
+| Old file                                     | Why it is not a contract                                                                                |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| A Markdown file under `api/`, `db/` or `ui/` | Those directories hold OpenAPI YAML or JSON, SQL and UI YAML contracts                                  |
+| Any file under `design/`                     | The directory no longer exists: the brand belongs in the root `DESIGN.md`, a screen in a `ui/` contract |
+
+Step 3 deletes each one, `design/` as one directory, and lists each file under
+`## For a person`. Rewrite what the file stated, from git history, in the form
+its row names.
+
+The old `design/prototype-handoff.yaml` is now
+`.qfai/prototype/final/handoff.json`, which `/qfai-prototyping` writes when
+the user confirms the prototype. The migration does not convert
+the old file into it.
+
+Step 3 also replaces every old `CON-*` ID that the contract map translates inside
+the contract files it writes, wherever it stands in the file, and lists none of
+them. It writes nothing outside those files. An old ID the map cannot translate,
+such as an ID no contract declared or that several declared, stays as written
+and is reported for a person with its file and line, as is a UI marker in
+application code.
+
+Step 3 groups its `## For a person` items under `### Content` and
+`### Identifiers`. `### Content` comes first and holds what a person rewrites
+or decides. `### Identifiers` holds an item that only pairs an old ID with its
+new one, such as a changed constraint ID. A group with no item is not printed.
+
+Step 3 writes a `routing:` override into `qfai.config.yaml` only for an entry
+of `agent-routing.yml` that differs from the installed default. It writes none
+for an entry equal to a default or to an entry a 1.x release shipped. Step 3
+lists each routing entry it does write under `## For a person`, with its name
+and a warning that a routing entry copied from a 1.x manifest hides the roles
+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-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-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
+rule written as a heading section takes the value of its `Rule` field as its
+statement, and a SQL contract holds that statement on one line.
+
+## Documents in their template's shape
+
+Each story-tree document the steps write takes the shape of its `qfai-sdd`
+template, which is the shape the document schema checks:
+
+| Documents                                                                               | Step |
+| --------------------------------------------------------------------------------------- | ---- |
+| `decisions.md` and `open-questions.md` rows                                             | 2    |
+| `objective.md`, `initiative.md`, `principle.md`, `glossary.md` and `constraint.md`      | 3    |
+| `contracts.md` and `tech.md`                                                            | 3    |
+| Markdown contracts under `cli/`                                                         | 3    |
+| `business-flows.md`, `business-flow.md`, `user-stories.md` and each story's three files | 4    |
+| Examples turned from test cases                                                         | 5    |
+
+Content that does not fit that shape is listed under `## For a person`, and the
+step exits 3:
+
+- Step 3 leaves it out of the policy file, `tech.md` or CLI contract, and names the source
+  file and, where one fits, the template section that takes the content once a
+  person rewrites it. The source file is deleted, so the content is read from
+  git history.
+- Step 3 also leaves as it is a policy file or `tech.md` that already exists
+  and differs from what it would write.
+- A constraint row keeps only its ID, Constraint and Rationale. Step 3 lists
+  an Impact column, whose content belongs to the contract or `tech.md` that
+  owns it, and a row that names a file, a command or a rule ID, to be rewritten
+  in plain words.
+- Step 3 numbers each constraint section from 01 in table order, and lists
+  every ID that changed with the ID that replaces it.
+- Steps 4 and 5 write a story sentence or an example cell of another form as it
+  stands, for a person to rewrite.
+- Step 4 lists every business flow, so that a person writes its alternate and
+  exception paths.
+
+The steps do not write these into the new tree. Each stays in its old spec-pack
+file, which stays in the pack while any of its content is unplaced and is then
+deleted, kept in git history only:
+
+- a spec pack's scope and source provenance;
+- a story block's `Parent`, `Source` and `Flow` fields;
+- a criterion's `# Parent:` line, since its directory names the story;
+- a `Background:`, any scenario after a criterion's first named one, and a
+  `Scenario Outline:`, each listed for a person.
+
+Step 3 writes no structure document. It routes the old `catalog/structure.md`
+section by section:
+
+| Old content                                                                                                                                | New home                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| An entrypoint with a smoke or skeleton command                                                                                             | A `- Skeleton:` line in `tech.md`'s Standard commands |
+| A layer row of an `## Architecture` or `## Architecture constraints` table of Layer, Responsibility and Depends on columns, naming no path | The `## Architecture` table of `tech.md`              |
+| The `ui_paths:` globs of `## UI surface paths`                                                                                             | `uiux.surfacePaths` in `qfai.config.yaml`, if unset   |
+| Anything else                                                                                                                              | `## For a person`                                     |
+
+Step 3 writes the moved layers in the shape of the Architecture section: a
+`flowchart TD` with a node per layer and an edge per dependency, then the table
+with the rows ordered from the uppermost layer down. Where the rows cannot be
+ordered, because a layer depends on one that has no row or layers depend on each
+other, none of them moves: the section is listed under `## For a person` with
+the reason, and `tech.md` keeps the template's Architecture section.
+
+Step 3 writes each Markdown contract under `cli/` in the shape of the CLI
+contract template: its `# CLI-0001: <title>` heading, `## Ownership boundary`
+and a `## Business rules` table, and nothing else.
+
+- An old `## Ownership boundary` of one to three paragraphs that name no rule is
+  kept as it stands.
+- Where the old contract has none, the section holds the template's placeholder,
+  and the contract is listed for a person to write it.
+- The text before the first section, lines such as `Status:` or `Rule refs:`,
+  and every other section are left out. Each is listed with the old file.
+
+Step 7 then writes the contract's rules into that table. A rule whose statement
+names another rule is written and listed for a person, because a CLI contract's
+rule cites only examples.

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

@@ -95,9 +95,10 @@ decide completion.
 The invocation completes when the user confirms the prototype and
 `prototyping-handoff` has written the handoff. A blocking finding the latest
 review still lists at that point is named in the final report. Report every
-decision a session adopted, as that step says. The report ends with a question
-listing the actions under Next, as `.agents/rules/user-questions.md` § 6 sets
-out. Under a no-question mode, list them in the report instead.
+decision a session adopted, as that step says. Ask about the actions under Next
+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.
 
 ## Next
 

package/assets/init/.qfai/assistant/skill/qfai-prototyping/references/review-payload-schema.md

@@ -7,7 +7,7 @@ and the user reads what it finds before confirming the prototype.
 The schema is **closed**: any key not listed below is rejected. The
 orchestrator checks each payload against it before writing it, and asks the
 reviewer again for one that does not conform before the prototype is put to
-the user. A near-miss (extra key, misspelled field, legacy flat key) fails the
+the user. A near-miss (extra key, misspelled field) fails the
 whole file.
 
 ## Contents
@@ -99,8 +99,7 @@ These keys belong to the per-iteration summary, **not** to this payload.
 Writing any of them here breaks the closed schema:
 
 `iterIndex`, `reviewerId`, `proseCritique`, `pivotDirective`,
-`evidenceRefs`, and the retired flat `timeBudgetSoftWarning` string
-(use `softWarnings.timeBudget: boolean`).
+and `evidenceRefs`.
 
 ## `sessionStatus` and the retry policy
 

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

@@ -168,7 +168,7 @@ count can support a finding, but cannot replace the live assessment.
 | 5   | No catalogued anti-pattern is present                                 | `lap-*`, below                           |
 | 6   | Conformant, procured, restrained and consistent                       | below                                    |
 | 7   | Every declared `primary_task` walks                                   | below                                    |
-| 8   | No text on the screen explains the interface                          | `.agents/rules/interface-clarity.md`     |
+| 8   | No text explains the interface, and the text shown is the contract's  | `.agents/rules/interface-clarity.md`     |
 
 Criteria 1 to 4 are the procurement ladder read as questions, so a screen
 cannot pass by a standard it was not built to.
@@ -214,6 +214,22 @@ Hint text survives only where a need was demonstrated, the control was
 improved first and the need remained, and it is one sentence at most. Longer
 means the question needs clarifying or splitting.
 
+Compare the rendered text with the screen's UI contract in both directions. The
+screen shows its `title`, the group headings of its `structure`, its labels and
+the `supplements` it declares. A text shown that none of them declares is excess,
+and a declared supplement that is not shown is an unmet need. The finding names
+the screen, the task or state, the meaning that is duplicated or the need that is
+unmet, and the text to remove or the control or structure to repair. Apply the
+patterns of the section on copy that adds no meaning, which the loop step names; the
+rest of the design anti-patterns list stays with the direction review.
+
+A repair keeps what the task needs: a condition, cost, storage or transmission
+destination, result, recovery step, the consequence of an action that cannot be
+undone, and every label, accessible name, role and state. Moving that into a
+tooltip or a placeholder is not a repair. After a repair, walk the task again at
+the declared narrow and desktop widths, in the normal, empty, error, loading and
+success states the screen has.
+
 The counts are contract-relative. A screen declaring one primary task and
 carrying forty controls is wrong; the same forty elsewhere may be right. The
 denominator is in the contract, so no global threshold has to be invented.

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-run
 title: QFAI Run (Change request entry)
-description: "Use when the user asks for a change, a fix, an investigation of the codebase or a question about the project in plain words and names no stage skill. A question that one command or one file read answers needs no plan. Plans the request with `npx qfai workflow plan` and runs the plan's steps in order to its end."
+description: "Use when the user asks for a change, a fix, an investigation of the codebase, a question about the project or an operation on finished work in plain words and names no stage skill. Plans every such request, the lightest included, with `npx qfai workflow plan` and runs the plan's steps in order to its end."
 argument-hint: "<the change, in your own words>"
 allowed-tools: [Read, Glob, Grep, Write, Edit, Bash, TodoWrite, Task, Agent]
 roles: [orchestrator]
@@ -14,14 +14,15 @@ mode: execution-focused
 
 [DRIFT-PROTOCOL:REQUIRED]
 
-The user states a change once. This skill reads the request into facts, asks
-`npx qfai workflow plan` for the plan they give, and runs its steps in order.
+Follow the CLI plan's steps in order. Read no reference up front; each line says when.
 
-- The facts a request is read into: `references/extraction.md`.
-- The command, its input and its output: `references/plan.md`.
-- What the user sees, and how questions are put: `references/operator-screens.md`.
-- What is done at a release, decision or branch point: `references/stage-points.md`.
-- Invoke the CLI through the launcher of `.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory`.
+- `references/extraction.md`: for an extraction step 1 does not give.
+- `references/plan.md`: for a plan field this file does not name, or a refused plan.
+- `references/operator-screens.md`: when a line below or a step names it, such as to ask or report.
+- `references/stage-points.md`: at a step the plan marks with a point.
+- Run preflight before planning, as `.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory` says.
+  If the launcher is missing or preflight fails, read `references/operator-screens.md` for recovery.
+- Read `references/codex-cloud-install.md` before configuring an environment-owned Install script or Start skill, or preparing dependencies for a fresh checkout. Use the reviewed target's successful preparation and canonical proof before planning.
 
 ## What this skill never does
 
@@ -34,8 +35,8 @@ The user states a change once. This skill reads the request into facts, asks
 
 ## Mode
 
-Read `workflow.mode` in `qfai.config.yaml` first. No key means `active`; any
-value but the three below plans nothing.
+Read `workflow.mode` in `qfai.config.yaml` first. No key means `active`; unlisted
+values plan nothing.
 
 | Mode     | What this skill does                                                                 |
 | -------- | ------------------------------------------------------------------------------------ |
@@ -45,48 +46,60 @@ value but the three below plans nothing.
 
 ## Request kinds
 
-- A change, a question, a proposal to decide or a report to close is planned.
-  A question plans a route that answers it and changes nothing. Text that is
-  not a request is not planned.
+- For independent targets under one goal, read `references/operator-screens.md`
+  before planning or switching during a wait.
+- Plan changes, questions, proposals to decide and reports to close.
+  Questions plan answers without changes; nonrequests get no plan.
+- Replies with a requested answer or result, including failure, resume the same step without
+  a new invocation. An independent new request is planned; read `references/operator-screens.md`
+  for replies.
 - `stop`: end the work at once and list every open decision as open.
 - A request naming a stage skill: invoke that skill by name.
 
 ## The work
 
-1. **Extract.** Read the request into an extraction as
-   `references/extraction.md` sets out, and pass it to
-   `npx qfai workflow plan --in <file>`, or `--in -` on standard input.
+1. **Extract.** A question one read answers is `{ intent: question-why, qualifiers: [session-answerable] }`
+   (or `question-how`, `question-help`); an operation on finished work that the session runs itself and
+   that deletes nothing is `{ intent: order, artifacts: [] }`. Every other field is empty, with
+   `confidence: high`; neither needs a reference. Read any other request as `references/extraction.md`
+   sets out, and pass the extraction to `npx qfai workflow plan --in <file>`, or `--in -`.
 2. **Candidates.** When `plan` returns `candidates`, put one single-select
    question, each option saying in the user's words what that route will do,
    then run `npx qfai workflow plan --route <route>` for the chosen one.
-3. **Scope.** Ask which scope to run, as `references/operator-screens.md` says; run only its stages.
-4. **Announce.** Before the first stage, give the goal, the chosen stages in
-   order in plain words, and the files the work may change. Ask nothing. Then run
-   `common-policy-check` once. On a route that changes no file, one that
+3. **Scope.** With two or more scopes, ask which to run as `references/operator-screens.md` says,
+   and run only its stages. With one scope, no scopes, or a branch destination's plan, ask
+   nothing and run every stage.
+4. **Announce.** Before the first stage, give the goal, the chosen stages in order in plain words,
+   and the files the work may change. Ask nothing. Then run `common-policy-check` once, unless the
+   plan's one step is `triage-answer` or `triage-operate`. On a route that changes no file, one that
    closes, answers or asks, it reads and reports and writes nothing.
 5. **Run the stages.** Run each stage in plan order, and each of its steps in
-   order. Write any artifact yourself. Give a part to a sub-agent only to run
-   independent parts in parallel, or for a review. At each step, handle the
-   points the plan names for it, as `references/stage-points.md` sets out:
+   order, as `.qfai/assistant/rule/shared-skill-operating-baseline.md#running-steps-mandatory` says.
+   When a step is short or passes without edits, read `references/operator-screens.md`.
+   Write artifacts yourself or delegate independent parallel work or review.
+   At a step the plan marks with a point, follow `references/stage-points.md`:
    - **Release point.** Ask the user to approve the release before the step `releasePoint` names.
    - **Decision point.** Put each critical decision at a step `decisionPoints` names to the user.
    - **Branch point.** Move to the destination a step `branchPoints` names, and plan it at once.
-6. **Review.** After a stage whose `review` is `spec`, `requirements-reviewer`
-   reviews, with `architecture-reviewer` when a contract changed; after one
-   whose `review` is `code`, `implementation-reviewer`.
-   `product-surface-reviewer` joins both where a UI contract with screens
-   serves the flow. No agent reviews its own work, and no step adds a review.
-   Each review returns PASS or REVISE, and each finding is fixed or answered
-   once, with no re-review. A step that would go beyond the request stops.
+6. **Review.** After a stage whose `review` is `spec`, `requirements-reviewer` reviews; for `code`,
+   `implementation-reviewer`. Only a contract or screen change no earlier review read adds
+   `architecture-reviewer` or `product-surface-reviewer`, as `common-review-cycle` lists; no one else
+   joins. A review whose target's only edits resolve the conflicts of a merge or branch update between
+   reviewed sides gets no reviewer.
+   No agent reviews its own work; no step adds a review. Each returns PASS or REVISE.
+   Fix or answer each finding once, with no re-review. Stop a step that exceeds the request.
 7. **Approvals.** Each approval of a specification change, a critical decision
    or a release is one `decisions.md` row: what was approved, who approved it,
-   when, and the chosen option's label. A decision you took appends no row.
+   when, and the chosen option's label, in the `qfai-sdd` decisions template's form. A decision you took appends no row.
 8. **A finding no stage serves.** Stop, and name the finding, its owner and the stage skill to invoke by name.
 9. **Commit.** `verify-commit` runs last, after any release point; never pushes.
+10. **Session feedback.** When the final report closes the user's last task and nothing waits on them, follow `.agents/rules/session-feedback.md` once.
 
 ## Under a no-question mode
 
 Nothing is asked. The plan's narrowest scope, or the first candidate and its narrowest scope, is taken and reported as an assumption.
+An uncovered question-only move to tracked-file repair instead stops that target
+with a report and no tracked open question, as `references/stage-points.md` says.
 A critical decision or a release point becomes one `open-questions.md` row,
 the step stops before the change that depends on it, and the report lists the
 decision as open. A third branch move, or one from a scope that leaves stages out, stops the work.
@@ -108,11 +121,7 @@ Follow `.qfai/assistant/rule/shared-skill-delegation-baseline.md`.
 
 ## Work Orders Summary
 
-Where 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                  |
+When parts ran in parallel, use the summary in `references/operator-screens.md`.
 
 ## Default Autopilot Policy
 
@@ -127,7 +136,13 @@ Where parts ran in parallel, report one row per part given to a sub-agent.
 
 ## Completion Contract (Shared)
 
-Follow `.qfai/assistant/rule/shared-skill-operating-baseline.md#completion-contract-shared`. **Smallest applicable smoke check** (this skill's override): the gates of the `verify-qfai-gate` and `verify-repo-gate` steps the chosen scope holds; a scope holding none runs no gate, and the report says so. A gate that cannot run is UNRUN, not a pass.
+Follow `.qfai/assistant/rule/shared-skill-operating-baseline.md#completion-contract-shared`. **Smallest applicable smoke check**: the chosen scope's `verify-qfai-gate` and `verify-repo-gate` gates. With none, run no gate and report it. Unavailable gates are UNRUN, never PASS.
+
+At stage boundaries, follow `references/reached-step-observations.md` in the existing report.
+
+If requested evidence handover must precede archive, read `references/evidence-delivery.md`
+and complete receiving proof first. Missing access leaves handover pending and originals
+retained; ordinary completion requires no unsolicited upload.
 
 project_memory:
 

package/assets/init/.qfai/assistant/skill/qfai-run/references/codex-cloud-install.md

@@ -0,0 +1,80 @@
+# Codex Cloud dependency preparation
+
+Read before configuring an environment-owned Install script or Start skill, or
+when a fresh checkout cannot pass the canonical launcher preflight. Init writes
+the preparation entry and this guide; it performs no installation or host setup.
+
+## Before execution
+
+Review the project-declared executable, separate argv and absolute checkout cwd.
+Read the declared Install command from the project's Standard commands; translate
+it into a reviewed native executable and arguments before configuration. The entry
+does not parse Markdown, shell text or choose a package manager.
+
+Covered authority for the command and its lifecycle scripts must already exist.
+Preserve network, secret, trust and publication permissions. A generated file,
+invocation or flag grants no authority. Missing authority blocks execution.
+Review argument and output contents before retaining or sharing them.
+
+## Install script
+
+Use the generated entry with the reviewed tuple:
+
+```text
+node .qfai/assistant/skill/qfai-run/scripts/codex-cloud-install.mjs --cwd <absolute-checkout> -- <executable> [argument...]
+```
+
+Replace the placeholders with the reviewed values and configure the host's
+supported Install script. The executable and arguments are passed with no shell
+parsing at the explicit cwd. Do not supply an entire shell command as one argument.
+Do not use a parent, remote or cached command as a substitute.
+
+Missing inputs, an unknown option, a relative cwd or an unreadable target directory
+fail before installation. Unavailable tools, spawn errors, signals, nonzero exit
+and observed timeout remain failed preparation. Retain the actual reason; there
+is no automatic retry, extra timeout option or new deadline.
+
+After successful installation the entry checks the same cwd for its local
+`node_modules/.bin/qfai`, or a root `.pnp.cjs` / `.pnp.loader.mjs` marker with a
+declared qfai dependency and native `yarn exec qfai --help` exiting 0. A failed
+installation stays failed even if a launcher already exists. A Windows wrapper
+that cannot start natively remains a tool failure; no shell fallback is added.
+
+## Start skill
+
+Check successful preparation and the canonical proof at the same reviewed cwd
+before dependent planning. Failure or missing covered authority blocks planning;
+report the actual blocker and owner required to resume. The entry starts no plan.
+Use the launcher that the existing canonical preflight established for that target.
+Preparation is neither global validation nor formal workflow completion.
+
+## Environment setup
+
+Confirm current environment support for the Install script and Start skill before
+real configuration. The operator performs authorized setup and publication;
+init and the generated entry do not register an account or configure the host.
+
+Saving configuration, preparing and publishing a filesystem for new tasks are
+distinct operations. A refresh does not rerun installation or startup. Existing
+tasks retain their own state. Confirm the actual host behavior before claiming
+that preparation or a Start skill ran for a task; changing a local file is not
+evidence of a published environment or a new task using it.
+
+## Reminders and trust
+
+Existing reminder-only exit-0 behavior stays unchanged. Project-edited hook groups
+keep their existing merge behavior. Keep linked-path refusals, unreadable-file warnings and hook
+review. Preparation does not grant hook trust. No universal SessionStart installer
+is added, and reminder hooks do not perform this installation.
+
+## Evidence limits
+
+Distinguish generated assets, controlled native CI and actual Cloud configuration,
+publication or task execution. Retain reviewed command and argv, cwd, actual exit
+or signal, and canonical result without exposing secrets. A failed or interrupted
+run is not ready; missing outcomes remain unknown.
+
+Controlled native fixtures cannot prove host lifecycle or startup execution.
+Actual Cloud setup and execution remain unobserved without their own receipts.
+Keep existing workflow gates, trust and independent review; preparation replaces
+none of them.