qfai 2.1.0 → 2.1.1

package/README.md

@@ -92,7 +92,7 @@ See [Invoking a stage directly](#invoking-a-stage-directly-expert-path).
 
 You state the change once, in your own words.
 The `qfai-run` skill reads it into facts: what it asks for, its risks, and how sure that reading is.
-`npx qfai workflow plan` then picks one of 35 fixed routes from those facts by ordered decision rules
+`npx qfai workflow plan` then picks one of the fixed routes from those facts by ordered decision rules
 and returns the route's plan, writing nothing. The session runs each step of the plan in order and
 asks you only the decisions that are yours and each release. You type no stage name.
 
@@ -325,7 +325,7 @@ flowchart LR
     | `--help`, `-h`             | Print the CLI usage banner and exit without writing anything. Accepted by every command, `init` included, and handled before the command runs.                                                                                                                                                                                                                                                         |
     | `--version`, `-V`          | Print the installed QFAI version to stdout and exit 0. Accepted by every command, `init` included, and handled before the command runs, so it works outside a project too.                                                                                                                                                                                                                             |
 
-  - `D-DEPRECATED-PATH` means the legacy assistant layout remains past its
+  - `QFAI-DEPRECATED-001` means the legacy assistant layout remains past its
     supported window. Run `npx qfai init --upgrade-assistant-tree` to copy
     recognized files into the current tree without deleting their sources.
 
@@ -403,6 +403,8 @@ paths:
   testsDir: tests
 validation:
   failOn: error # error | warning | never
+  staleTerms: # terms the specs must no longer state, such as a rejected option
+    - SMTP
   traceability:
     testFileGlobs:
       - "src/**/*.test.ts"
@@ -416,6 +418,7 @@ uiux:
 
 Notes.
 
+- `validation.staleTerms` lists terms a project no longer wants in its specs. `qfai validate` warns on each line of a spec document that states one, apart from `decisions.md` and `open-questions.md`.
 - `validate.json` is a **public** surface: its keys are documented in
   `.qfai/assistant/skill/qfai-verify/references/validate-json-schema.md`.
   Changes to its keys follow the `@api` classification in
@@ -464,10 +467,16 @@ there, and all three open with a ``# Generated by `qfai init` `` line. All three
 every push to `main` or `master` and on every pull request, and all three run on the
 runner `vars.QFAI_CI_RUNNER` names (`ubuntu-latest` when you set nothing).
 
+`npx qfai init` writes a workflow again whenever its file is missing. To stop it
+writing one, set `workflow.skipShipped` in `qfai.config.yaml` to a list of file
+names, for example `[qfai-tests.yml]`, and delete the file.
+
 - `qfai-validate.yml` runs `npx qfai validate --profile full --fail-on error`,
-  and on a pull request also `npx qfai validate --profile drift --fail-on error`.
-  The `full` profile evaluates every gate group except drift, so without the
-  second run nothing there could fail on a downstream edit to upstream SSOT.
+  and on a pull request also `npx qfai validate --profile drift --fail-on error`,
+  as a second step of the same job. The `full` profile evaluates every gate group
+  except drift, so without the second run nothing there could fail on a downstream
+  edit to upstream SSOT. The second step runs after a failing first one, so one run
+  reports both profiles, and the dependencies are installed once.
   It installs dependencies from whichever lockfile the repository has (pnpm /
   yarn / npm) and falls back to `npm install` when there is none, and it takes
   the Node version from your `.nvmrc` or `.node-version`, warning and
@@ -477,9 +486,10 @@ runner `vars.QFAI_CI_RUNNER` names (`ubuntu-latest` when you set nothing).
   holding a `pnpm-lock.yaml` with no such field fails the job with an
   annotation naming the field rather than reporting a validation it never ran.
   Declare `"packageManager": "pnpm@X.Y.Z"` so CI matches the version you
-  develop against. The `full` profile includes the `QFAI-TEST-001` test-todo
-  stub gate, so the job can fail your default branch on findings your existing
-  CI never checked.
+  develop against. The `full` profile includes the test stub gate
+  (`QFAI-TEST-001` for a todo, `QFAI-TEST-003` for a skip), so the job can fail
+  your default branch on findings your existing CI never checked. See
+  "Skipped and todo tests" below for what the gate reports and what it cannot see.
 - `qfai-tests.yml` declares one lane per test layer (unit, component,
   integration, api, e2e) and runs none of them until you opt in: a lane runs
   only when your `package.json` declares the matching `test:<layer>` script
@@ -506,7 +516,32 @@ A push to `main` or `master` runs the test lanes and the document checks again b
 default, because nothing in the files can tell whether that commit passed a pull
 request first. If your branch protection requires these checks before every merge,
 set the repository variable `QFAI_CI_PUSH_POLICY` to `protected`: the push then runs
-neither, and `qfai validate` still runs as the post-merge check.
+neither, and `qfai validate` still runs as the post-merge check. If you run
+`qfai validate` in a post-merge job of your own, set it to `none` instead: the
+push then starts no job of the validate workflow either.
+
+`protected` is safe only when GitHub requires the branch to be up to date before
+a pull request can merge: the branch protection option "Require branches to be up
+to date before merging", called `strict` in the API. Without it, two pull requests
+can each pass on their own and break the branch once both are merged. One that
+changes a function signature and one that starts calling the old signature is the
+usual case. The default branch is then red while every pull request was green.
+
+Requiring up-to-date branches makes every parallel pull request update and rerun
+after each merge. If that costs too much, there is a middle option between running
+the full lanes again and running nothing: keep `QFAI_CI_PUSH_POLICY` at
+`protected`, and add a small post-merge job of your own to a workflow you
+maintain.
+
+- It runs only what can break when two pull requests combine: the type check, and
+  the schema or contract consistency checks. The shipped `qfai-validate.yml`
+  already runs the validator on every push, so the job does not repeat it.
+- It installs dependencies once, and uses one concurrency group with
+  `cancel-in-progress: true`, so a newer push cancels an older run. The newest
+  commit contains the older ones, so nothing goes unchecked.
+- It leaves out the test suites. A break that only they would catch shows up on
+  the next pull request, which fails on code it did not change. In one project the
+  job took about two billed minutes where the full lanes took about 29.
 
 All three files are copied create-only — `qfai init` writes a workflow only
 where no file of that name exists, and never overwrites one, not even with
@@ -577,6 +612,215 @@ Typical customizations.
 - Add a `doctor` step before validate if you want to fail fast on path/glob/config issues.
 - Publish `.qfai/report/validate.json`, `report.md`, and relevant `.qfai/report/run-*/` logs as CI artifacts.
 
+### What a run costs
+
+On a private repository with GitHub-hosted runners, cost follows the number of
+jobs, not how long they run. Each job rounds up to a whole minute, a skipped job
+costs nothing, and a workflow that starts several quick jobs on every event costs
+more than one slow job. A closed pull request starts a run too, but every job in
+it declines, so nothing is billed.
+
+Jobs the shipped workflows start on each `opened`, `synchronize` and `reopened`
+event of a pull request:
+
+| Workflow            | Nothing to run                    | Lane runs                                           |
+| ------------------- | --------------------------------- | --------------------------------------------------- |
+| `qfai-validate.yml` | 1: `qfai validate`, both profiles | 1                                                   |
+| `qfai-tests.yml`    | 1: `change detection`             | 2, plus one per selected lane (at most 5)           |
+| `qfai-docs.yml`     | 1: `change scope`                 | 4: adds the `shape` and `mermaid` checks and `docs` |
+
+When nothing is selected, `verdict` is skipped, and when nothing a document check
+reads changed, `docs` is skipped. Each workflow then starts one job, and the
+detection and scope jobs say in a notice annotation why. One pull request event
+starts 3 jobs in all, and the most it can start is 12. On a push to the default
+branch, `qfai-validate.yml` starts 1 job, `QFAI_CI_PUSH_POLICY=protected` brings the
+other two workflows down to their idle counts, and `none` also skips the validate
+job, which leaves `change detection` and `change scope`.
+
+Four of those jobs install nothing and run no test: `change detection`, `verdict`,
+`change scope` and `docs`. They take seconds, so each bills one minute.
+They read `vars.QFAI_CI_LIGHT_RUNNER`, so the price of that minute is a choice.
+On a private repository with GitHub-hosted runners, set it to `ubuntu-slim`:
+
+```bash
+gh variable set QFAI_CI_LIGHT_RUNNER --body ubuntu-slim
+```
+
+`ubuntu-slim` has 1 CPU and 5 GB of memory, runs unprivileged, limits a job to 15
+minutes, and bills at a lower per-minute rate than `ubuntu-latest`; GitHub's
+pricing page has the current figure. The light jobs run only Bash, Git and Node, all
+of which it carries, and the workflows keep `ubuntu-latest` as the default, so this
+is your variable to set. Do not point `QFAI_CI_RUNNER` at it: the jobs that install
+dependencies, need Docker or can run past 15 minutes do not belong on it. A label
+GitHub does not offer to your account leaves a job queued rather than failing it.
+
+Each workflow file states its own counts in a "Jobs per pull request event" row of
+its header table. `npx qfai doctor` reports the same counts for the workflows
+installed in your repository, with the runner each job asks for. It is an `info`
+finding and reads the files only. It reads none of your repository variables, so it
+shows the variables a job falls back through and not the label they resolve to.
+
+### Required checks and branch protection
+
+Require these three checks, by exactly these names:
+
+- From `qfai-tests.yml`: `verdict`
+- From `qfai-docs.yml`: `qfai docs (document shape and Mermaid syntax)`
+- From `qfai-validate.yml`: `qfai validate (full profile, fail on error)`
+
+Each one fails when the work behind it fails. `verdict` and the `qfai docs` check
+are skipped when nothing was selected or nothing a document check reads changed,
+and GitHub counts a skipped job as satisfying a required check. The jobs behind
+them are named by their matrix value, such as `qfai tests (unit)`, and a skipped
+matrix job is reported under its unexpanded name, so a required check cannot name
+them.
+
+A check name is what branch protection matches. When you rename a job, or change
+what it covers, change the required check in the same step. While the two differ
+the required check is never reported, and every pull request is blocked. The
+validate check above is the one to watch: on a pull request it covers the `full`
+and `drift` profiles, and if you change the profiles you run, its name keeps
+saying "full profile".
+
+A job that an `if:` condition skips is reported as skipped, and that satisfies a
+required check. A workflow that a workflow-level `paths` or `paths-ignore` filter
+keeps from starting reports nothing, so its required check stays pending and the
+pull request cannot merge. Put the decision in a job, and skip jobs. The shipped
+`change detection` and `change scope` jobs do that. Do not put a `paths` filter on
+a workflow with a required check.
+
+The "Required check" row of each workflow's header table names the job to require.
+
+### Checking workflow files
+
+GitHub starts no job from a workflow file it cannot parse. The run shows as failed
+with no jobs, on every push to every branch, and a change to the file does not show
+up in its own pull request's checks, because the broken workflow never starts. A key
+that appears twice in one mapping is enough, such as `env:` twice in one step after a
+scripted edit, and many YAML loaders accept it without a word.
+
+`npx qfai doctor` parses each `.yml` and `.yaml` file under `.github/workflows/` and
+`.github/actions/` and warns with the file and the line. Run `actionlint` as well, and
+run it after any scripted edit to a workflow. It also reports duplicate keys with line
+numbers, and it checks expressions and job references that a YAML parser cannot. It
+can be one step of a job you already run, such as a change-detection job, so it adds
+no job.
+
+### Skipped and todo tests
+
+The stub gate is a static scan of the files that
+`validation.traceability.testFileGlobs` selects. It blanks comments and string
+literals first, then matches text patterns. The shipped workflow runs
+`--fail-on error`, and every finding below is an error.
+
+| What the scan finds                                                                                      | Finding         |
+| -------------------------------------------------------------------------------------------------------- | --------------- |
+| `it.todo`, `test.todo`, `describe.todo`                                                                  | `QFAI-TEST-001` |
+| `it.skip`, `test.skip`, `describe.skip`, with a modifier before or after (`.skip.each`, `.concurrent`)   | `QFAI-TEST-003` |
+| The other stacks' placeholders: `pytest.skip`, `t.Skip`, `@Disabled`, `@Ignore`, `#[ignore]`, `[Ignore]` | `QFAI-TEST-001` |
+
+It cannot see a skip that is not a text pattern, and none of these is reported:
+
+- a conditional skip: `describe.skipIf(...)`, `it.skipIf(...)` and `it.runIf(...)`
+- a form that selects the skip at run time, such as
+  `const suite = enabled ? describe : describe.skip`
+- a skip called inside a running test, such as `ctx.skip()`
+- a suite that returns early when the environment is missing, such as an unset
+  database URL
+- a test file that the globs do not select; with no globs set the scan reports
+  `QFAI-TEST-002` and reads nothing
+
+A suite skipped for a missing database therefore passes CI, and so does a suite
+whose database failed to start. Only the test runner knows what was skipped in a
+given run. Have it write a JSON report, and fail the job when a file skips more
+tests than a list of named, allowed skips permits. Jest and Vitest write the same
+shape: `jest --json --outputFile=test-report.json`, or
+`vitest run --reporter=json --outputFile=test-report.json`. Add the flags to
+your `test:<layer>` script, save this script as `scripts/check-skipped-tests.mjs`,
+and run it in a step of `qfai-tests.yml` after the step that runs the tests:
+
+```js
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const allowed = JSON.parse(readFileSync("allowed-skips.json", "utf8"));
+const report = JSON.parse(readFileSync("test-report.json", "utf8"));
+let failed = false;
+for (const file of report.testResults) {
+  const name = path.relative(process.cwd(), file.name).split(path.sep).join("/");
+  const skipped = file.assertionResults.filter(
+    (test) => test.status !== "passed" && test.status !== "failed",
+  ).length;
+  if (skipped > (allowed[name] ?? 0)) {
+    console.error(`${name}: ${skipped} tests did not run, ${allowed[name] ?? 0} allowed`);
+    failed = true;
+  }
+}
+process.exit(failed ? 1 : 0);
+```
+
+`allowed-skips.json` maps a test file to the number of tests it may skip, such as
+`{ "orders.test.ts": 2 }`. Start from the count you measure today. The
+list should only ever shrink: a pull request may remove an entry or lower a count,
+and raising one is a decision a reviewer makes on purpose.
+
+### Writing a change-scope gate for your own workflows
+
+If you write a gate that skips your own heavy jobs on a small change, copy the
+shape of the shipped `change detection` job: it falls back to running every lane
+when the base commit is missing, the clone is shallow, the base is unreachable, the
+diff fails, or a changed path is outside the set it knows. The rules that keep a
+gate from skipping what it should have run:
+
+- Decide from what the runners and tests read, not from directory names.
+- Fail open. When the input is unknown, run everything: a skipped check claims the
+  change is fine, and a check that runs costs only its minutes.
+- Run the gate's own table of cases, sample paths with the decision each must
+  get, before the gate. A pull request that changes the gate runs the checks that
+  cover the gate.
+- Keep job names fixed, so required checks stay satisfied.
+- Decide in a job and skip jobs with `if:`. Never use a workflow-level `paths`
+  filter, as the section above explains.
+
+Three mistakes this prevents:
+
+- **Excluding a directory the runner reads.** A gate treated all of
+  `tests/integration/` as irrelevant to end-to-end tests, but the browser runner's
+  configuration runs the `*.browser.spec.ts` files in it. A pull request that fixed
+  one of them ran no end-to-end job and passed. Exclude only the files the runner
+  does not read.
+- **Trusting a general plan over the repository.** "A change to tests only can
+  skip the production build" is wrong where the build type-checks the tests
+  through the compiler's `include`. Read the configuration before you write the
+  rule.
+- **A gate that skips its own tests.** See the third rule above.
+
+### Measuring Actions minutes
+
+Cost on a private repository is hard to read from the outside. The billing
+endpoint for an organization needs an admin scope and may answer with an error,
+the timing endpoint for a single run reports `billable` as zero, and the detailed
+usage report needs an admin. This method needs only read access to the repository:
+
+1. List the runs of one pull request, by its head commit:
+   `gh api "repos/OWNER/REPO/actions/runs?head_sha=SHA" --jq '.workflow_runs[].id'`
+2. For each run, list its jobs:
+   `gh api "repos/OWNER/REPO/actions/runs/RUN_ID/jobs?per_page=100" --jq '.jobs[] | [.name, .conclusion, .started_at, .completed_at] | @tsv'`
+3. A job bills `max(1, ceil(seconds / 60))` minutes, where the seconds run from
+   `started_at` to `completed_at`. A skipped job bills zero.
+4. Compare pull requests by the same author and of the same kind of change, and
+   compare jobs and runs as well as minutes. Pull requests that only changed CI
+   settings are the case a change helps most, so they overstate the saving.
+   Compare pull requests that changed source and tests.
+5. Count the runs of a day with
+   `gh api "repos/OWNER/REPO/actions/runs?created=YYYY-MM-DD&per_page=1" --jq .total_count`.
+   It is one cheap call per day, and it shows days that stand out. It also follows
+   the amount of development, so it cannot prove a reduction by itself.
+
+A job that never started looks different from a job that failed: it has no steps,
+an empty runner name and a duration of about two seconds. Its logs are not found,
+which is not the logs having expired.
+
 ### Keeping QFAI itself up to date
 
 A `qfai` bump is the one dependency update that is not finished when the version
@@ -590,6 +834,23 @@ Moving a project from the spec-pack layout to the story tree also requires
 `/qfai-migration-v1-to-v2`. `init --force` refreshes shipped assets; the
 migration skill moves project content and reports items that need a person.
 
+To upgrade by hand:
+
+1. Install the new version with your package manager, for example
+   `npm i -D qfai@<version>`.
+2. Move every edit you made to a shipped skill, step, agent or rule into
+   `.qfai/assistant/skill.local/` or a rule overlay. The next step overwrites
+   the shipped copies.
+3. Run `npx qfai init --force`. It replaces the skills and steps an agent may
+   be reading, so an agent upgrading the project reads them again from disk
+   afterwards.
+4. Delete the files the release notes of the new version list as retired, once
+   nothing you keep reads them.
+5. Run `npx qfai doctor` and `npx qfai validate`, and fix what they report.
+6. Commit the result in one change.
+
+An agent asked to upgrade `qfai` follows these steps as a dependency update.
+
 Merging the bump on its own leaves the repository claiming a version whose
 skills it does not have. If you use Renovate, QFAI publishes a preset that keeps
 the two together:
@@ -747,8 +1008,8 @@ Each hook runs `node` directly, with no shell and no network, and prints one
 message from `.agents/rules/reminders.json`. A missing or unreadable message
 file prints nothing. `qfai init` refreshes that file wherever the project has
 not edited it, so a new release's wording reaches an existing project without
-changing `.claude/settings.json`. Remove the entries to turn the reminder off;
-the rule still applies.
+changing `.claude/settings.json`. Remove the entries from that file and from
+`.codex/hooks.json` to turn the reminder off; the rule still applies.
 
 Codex gets the same reminders from `.codex/hooks.json` once you trust the
 project's hooks with `/hooks`. Each is one command line that runs the same under
@@ -764,15 +1025,6 @@ kept, and the run names it. To update one by hand, run
 `npx qfai init --dir <scratch-dir>` in an unused scratch directory and compare
 its `.claude/settings.json` with your project's file, group by group.
 
-## Contributing (for QFAI maintainers)
-
-This repository is a monorepo, and the distributable package is under `packages/qfai`.
-The repository root `README.md` and `packages/qfai/README.md` are kept aligned by
-`scripts/check-readme-alignment.mjs`, which CI runs as part of `pnpm ci:lint`: every line
-outside a `readme-align:ignore-start` / `readme-align:ignore-end` HTML-comment block must be
-identical in both files. When you change documentation, apply the edit to both READMEs, or
-wrap the intentionally file-specific part in those markers.
-
 ## License
 
 MIT

package/assets/defaults/workflows/change-tooling.yml

@@ -1,13 +1,9 @@
 route: change-tooling
 family: upkeep
 stages:
-  - id: diagnose
-    kind: diagnose
-    steps: [implement-diagnose]
   - id: edit
     kind: implement
     steps: [implement-tooling]
-    after: [diagnose]
   - id: note
     kind: verify
     steps:

package/assets/init/.claude/settings.json

@@ -30,7 +30,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{let p;try{p=JSON.parse(require('fs').readFileSync(0,'utf8')).prompt}catch{}if(!(typeof p==='string'&&/^[ \\t]*<(task-notification|wake)[\\s>]/m.test(p))){const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
+              "try{let p;try{p=JSON.parse(require('fs').readFileSync(0,'utf8')).prompt}catch{}if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "structured-question"
             ]
@@ -46,7 +46,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{let p;try{p=JSON.parse(require('fs').readFileSync(0,'utf8')).prompt}catch{}if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "free-text-entry"
             ]
@@ -96,7 +96,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "grilling-design-artifact"
             ]
@@ -112,7 +112,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "grilling-delegation"
             ]
@@ -144,7 +144,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const c=JSON.parse(require('fs').readFileSync(0,'utf8')).tool_input.command;if(typeof c==='string'&&/(^|[^\\w.-])gh([^\\w.-]|$)|api\\.github\\.com/.test(c)){const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}const c=i.tool_input&&i.tool_input.command;if(typeof c==='string'&&/(^|[^\\w.-])gh([^\\w.-]|$)|api\\.github\\.com/.test(c)){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "api-budget"
             ]
@@ -163,7 +163,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "documentation-clarity-after-write"
             ]
@@ -175,7 +175,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "documentation-clarity-after-edit"
             ]
@@ -191,7 +191,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const m=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
+              "try{const f=require('fs'),p=require('path'),R=p.dirname(p.dirname(p.dirname(process.argv[1])));let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{}const u=i.tool_input&&i.tool_input.file_path;let src=true;if(typeof u==='string'&&(x=>{const s=x.split(p.sep),b=s.pop();return p.isAbsolute(x)||s[0]==='..'||s.some(y=>['tmp','test','tests','__tests__','node_modules','.qfai','.agents'].includes(y))||b[0]==='.'||/\\.(test|spec)\\./.test(b)||['.md','.mdx','.markdown','.txt','.rst','.yml','.yaml','.json','.jsonc','.json5','.toml','.ini','.csv','.tsv','.lock','.svg','.png','.jpg','.jpeg','.gif'].includes(p.extname(b).toLowerCase())})(p.relative(R,p.resolve(R,u))))src=false;if(src){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if((n-1)%20===0){const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "minimal-implementation"
             ]

package/assets/init/.codex/hooks.json

@@ -50,7 +50,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI grilling reminder: design artifact",
-            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" grilling-design-artifact",
+            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" grilling-design-artifact",
             "timeout": 10
           }
         ]
@@ -61,7 +61,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI grilling reminder: delegation",
-            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" grilling-delegation",
+            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" grilling-delegation",
             "timeout": 10
           }
         ]
@@ -72,7 +72,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI api-budget reminder",
-            "command": "node -e \"try{const i=JSON.parse(require('fs').readFileSync(0,'utf8')).tool_input.command;if(typeof i==='string'&&/[^\\w.-]gh[^\\w.-]|api\\.github\\.com/.test(' '+i+' ')){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" api-budget",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/[^\\w.-]gh[^\\w.-]|api\\.github\\.com/.test(' '+i+' ')){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" api-budget",
             "timeout": 10
           }
         ]
@@ -85,13 +85,13 @@
           {
             "type": "command",
             "statusMessage": "QFAI documentation-clarity reminder",
-            "command": "node -e \"try{const i=JSON.parse(require('fs').readFileSync(0,'utf8')).tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Add File: .*\\.md\\r?\\n/m.test(i)){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" documentation-clarity-after-write",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Add File: .*\\.md\\r?\\n/m.test(i)){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-write",
             "timeout": 10
           },
           {
             "type": "command",
             "statusMessage": "QFAI documentation-clarity reminder",
-            "command": "node -e \"try{const i=JSON.parse(require('fs').readFileSync(0,'utf8')).tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Update File: .*\\.md\\r?\\n/m.test(i)){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" documentation-clarity-after-edit",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Update File: .*\\.md\\r?\\n/m.test(i)){const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-edit",
             "timeout": 10
           }
         ]
@@ -102,7 +102,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI minimal-implementation reminder",
-            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" minimal-implementation",
+            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let go=true,j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}try{const R=p.dirname(p.dirname(p.dirname(r))),n=(x=>{const s=x.split(p.sep),b=s.pop();return p.isAbsolute(x)||s[0]==='..'||s.some(y=>['tmp','test','tests','__tests__','node_modules','.qfai','.agents'].includes(y))||b[0]==='.'||/\\.(test|spec)\\./.test(b)||['.md','.mdx','.markdown','.txt','.rst','.yml','.yaml','.json','.jsonc','.json5','.toml','.ini','.csv','.tsv','.lock','.svg','.png','.jpg','.jpeg','.gif'].includes(p.extname(b).toLowerCase())}),a=[...j.tool_input.command.matchAll(/^\\*\\*\\* (?:(?:Add|Update|Delete) File|Move to): (.+)/gm)].map(m=>p.relative(R,p.resolve(process.cwd(),m[1].trim())));if(a.length>0&&a.every(n))go=false}catch{}if(go){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" minimal-implementation",
             "timeout": 10
           }
         ]

package/assets/init/.qfai/assistant/agent/implementation-reviewer.md

@@ -30,8 +30,13 @@ specialization_tags:
 
 ## Domain Responsibilities
 
-- Review changed production code and tests against the affected BF, AC, EX, BR and contracts. Check correctness, input validation, security, performance, maintainability and operational failure paths.
+- Review changed production code and tests against the affected BF, AC, EX, BR and contracts. Check correctness, performance, maintainability and operational failure paths, and security as set out below.
 - Apply the repository review checklist and `.agents/rules/minimal-implementation.md`. Require a concrete smaller implementation when reporting excess; preserve every safety-floor obligation.
+- Check that the change adds test files sized like their neighbours, commits no
+  scratch checks, follows § 4 on unrequested fixes, including its exception for
+  a necessary fix and reporting requirement, and states any assumption it built
+  on (`.qfai/assistant/rule/test-layers.md#test-suite-sizing`,
+  `.agents/rules/minimal-implementation.md` § 4).
 - Check each new module against the `## Architecture` table of `<paths.contractsDir>/tech.md`: it belongs to one layer and imports only from the layers its row lists. A crossing is a finding.
 - In TypeScript, flag unjustified assertions, unchecked `unknown`, needless generic complexity and promises that callers neither await nor return.
 - Read the whole of every file the change touches for silent failure and type design, not only the lines the change adds or alters.
@@ -46,6 +51,14 @@ specialization_tags:
 - Type design, against § 2 of the same rule: a value crossing a trust boundary is parsed there into a form that cannot hold an invalid value.
   Flag mutable internals exposed to outside code, an invariant held only by documentation, validation missing at construction,
   enforcement that differs from one mutation to another, and outside code left to maintain an invariant the type should own.
+- Security, read on the same scope as silent failure and type design above. Check the three shapes the drift protocol names:
+  missing validation on an input the code already treats as trusted, credential or personal-data exposure, and an injection or traversal path opened by the change.
+  Cover injection, cross-site scripting, server-side request forgery, hardcoded secrets, insecure direct object reference, auth bypass,
+  unsafe deserialization and path traversal. Judge validation at a trust boundary against `.agents/rules/minimal-implementation.md` § 2.
+- Follow every input the change adds or alters to where it is used, across files the change did not touch.
+  A path the change opens there, such as an insecure direct object reference, a server-side request forgery or an auth bypass reached through several files, blocks.
+  This is the one reach beyond the touched files, and it covers only the inputs the change handles.
+  A security finding the review demonstrates traces to `defect:security`.
 - Check the EX test's oracle, selector and RED/GREEN/Refactor evidence.
 - Check for code written only to pass a test: no value hard-coded to the test's
   inputs and no branch written only for the test, and a wrong test or infeasible

package/assets/init/.qfai/assistant/agent/qa-gatekeeper.md

@@ -59,6 +59,11 @@ scope.
   code, control, setting or copy to remove or simplify and what replaces it.
   Do not weaken an active obligation to reduce code.
 - Treat test volume and density as review signals, not independent hard gates.
+- Check that the change adds test files sized like their neighbours, commits no
+  scratch checks, follows § 4 on unrequested fixes, including its exception for
+  a necessary fix and reporting requirement, and states any assumption it built
+  on
+  (`.qfai/assistant/rule/test-layers.md#test-suite-sizing`, `.agents/rules/minimal-implementation.md` § 4).
 
 ## Coverage gate
 
@@ -79,6 +84,30 @@ required gap or weak oracle; report a gap owned by another stage with that
 owner. During SDD, assess the requirement links without demanding tests that
 implementation has not written.
 
+## Refactor survival check (advisory)
+
+Read each test on four questions. Three are already judged elsewhere; apply
+them there, not twice.
+
+| Question                                                          | Where it is judged                                                      |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Does it cover the behaviour that matters, not just the lines run? | The coverage gate above                                                 |
+| Are the recurring gaps covered: kept failures and boundary cases? | The coverage gate above                                                 |
+| Would it fail on a concrete regression?                           | `skill/qfai-implement/references/oracle-strength.md`, proof per example |
+| Would it survive a refactor that keeps the behaviour?             | This check                                                              |
+
+A test fails the last question when it asserts on what the contract does not
+name: a private function, an internal call order, a mock of the code's own
+collaborators, or the structure of a value rather than what it means. Such a
+test breaks on a safe change and teaches authors to weaken the test instead of
+fixing the code.
+
+Read the whole of every test file the change touches, not only the tests it
+adds or alters. Record each finding with the test and a concrete
+behaviour-preserving change it would fail on. A finding with no named change is
+not admitted. A finding on a test that existed before the change is recorded
+and deferred. This check does not REVISE on its own and carries no score.
+
 ## Completion and runtime gate
 
 - Read the current BF's test selectors, command results and reviewer

package/assets/init/.qfai/assistant/rule/constitution.md

@@ -95,7 +95,7 @@ The test obligation is determined by the ID and the test's layer:
 
 - `BF-*` requires a `QFAI:BF-NNNN` annotation in an E2E test.
 - `AC-*` requires a `QFAI:AC-NNNN-NNNN-NN` annotation in an integration or API test.
-- `EX-*` requires a `QFAI:EX-NNNN-NNNN-NN` annotation in a selected non-E2E test file.
+- `EX-*` requires a `QFAI:EX-NNNN-NNNN-NN` annotation in a selected non-E2E test file, on the comment line directly before the test declaration it marks.
 
 `.qfai/assistant/rule/test-layers.md` defines the layer directories. Test
 selection uses `validation.traceability.testFileGlobs`. A missing BF, AC, or EX
@@ -429,7 +429,8 @@ This article survives context compaction because `.qfai/assistant/rule/constitut
 
 Scratch files an agent creates for its own convenience — working notes, one-off
 scripts, captured command output, downloaded samples, intermediate data —
-must be placed under the repository‑root `tmp/` directory.
+go in the scratch directory the host names for the session, and under the
+repository-root `tmp/` directory where the host names none.
 
 Scope: this article is about files written **into the working tree**. Two kinds
 of output are outside it:
@@ -445,7 +446,7 @@ of output are outside it:
 Rules:
 
 1. **Never** create a scratch file in the repository root, `src/`, `.qfai/spec/`, or any other production/artifact directory.
-2. Use `tmp/` (repository root) as the sole staging area. Create subdirectories as needed (e.g., `tmp/notes/`, `tmp/capture/`).
+2. When the host names a scratch directory for the session, use it. Otherwise use `tmp/` (repository root) as the sole staging area, with subdirectories as needed (e.g., `tmp/notes/`, `tmp/capture/`). A file the repository's own tooling must read from the working tree goes under `tmp/` whichever the host names.
 3. `tmp/` MUST be listed in `.gitignore` so temporary files are never committed.
-4. Clean up `tmp/` contents when the task that created them is complete.
+4. Clean up `tmp/` contents when the task that created them is complete. The host's own scratch directory is the host's to clean.
 5. If a scratch file is found outside `tmp/` **in the working tree**, treat it as a defect and move or delete it immediately. A test's `mkdtemp` sandbox and configured toolchain output are not scratch files — see Scope above.