qfai 2.1.0 → 2.1.2

package/README.md

@@ -79,11 +79,21 @@ Then open your AI coding agent in the repository and describe the change in your
 
 > Let each customer register up to five notification addresses, with no duplicates.
 
+If you only have an idea, say so: the run starts with a discussion that structures scope and open questions.
+
 The agent announces the goal, the stages it will run and the files it may change, then runs them.
 It asks you only what it cannot decide for you, such as whether to create a new story.
+Answer its questions, or say `stop` to end the run.
 The stages fill the seeded story tree and follow the project's Standard commands in
 `<paths.contractsDir>/tech.md` (by default `.qfai/spec/03_contract/tech.md`) for its quality gates.
 
+When the run ends, check the result:
+
+```bash
+npx qfai validate
+npx qfai report
+```
+
 To drive the stages yourself instead:
 Run `/qfai-discussion` and `/qfai-sdd` to fill the seeded story tree.
 See [Invoking a stage directly](#invoking-a-stage-directly-expert-path).
@@ -92,7 +102,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.
 
@@ -313,27 +323,22 @@ flowchart LR
     (`assistant/rule/`, `skill/`, `agent/` and `prompt/`), plus `qfai.config.yaml`.
   - Options:
 
-    | Flag                       | Effect                                                                                                                                                                                                                                                                                                                                                                                                 |
-    | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-    | `--dir <path>`             | Output directory (default: the current directory). Wins over `--root` when both are given.                                                                                                                                                                                                                                                                                                             |
-    | `--root <path>`            | Every other command reads this as the target directory; `init` reads it as the output directory too, but only when `--dir` is omitted.                                                                                                                                                                                                                                                                 |
-    | `--force`                  | Overwrite the shipped skills, steps, agents and rules, the rule masters under `.agents/rules/`, their host wrappers, and generated Copilot instructions, whether or not you edited them. Project content, `qfai.config.yaml`, `DESIGN.md`, `AGENTS.md`, `CLAUDE.md` and routing overrides are preserved. The managed `.gitignore` block and `core.symlinks` setting are repaired on every non-dry-run. |
-    | `--dry-run`                | Report what would change and write nothing. Use it to rehearse `--upgrade-assistant-tree`.                                                                                                                                                                                                                                                                                                             |
-    | `--upgrade-assistant-tree` | Copy recognized legacy assistant files into the singular tree without deleting a source or overwriting a destination. Migrate old spec packs with `/qfai-migration-v1-to-v2`. Unrecognized assistant files stay in place.                                                                                                                                                                              |
-    | `--yes`                    | Reserved for a future interactive mode; no behavioural difference today.                                                                                                                                                                                                                                                                                                                               |
-    | `--verbose`                | Expand the run report's `skipped` list to the full path listing. Off by default, so a no-op re-run prints the skip count and a pointer to this flag instead of every shipped asset path. It does not gate the written or removed listings: those are printed whenever they have entries, with or without this flag.                                                                                    |
-    | `--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
-    supported window. Run `npx qfai init --upgrade-assistant-tree` to copy
-    recognized files into the current tree without deleting their sources.
+    | Flag              | Effect                                                                                                                                                                                                                                                                                                                                                                                    |
+    | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `--dir <path>`    | Output directory (default: the current directory). Wins over `--root` when both are given.                                                                                                                                                                                                                                                                                                |
+    | `--root <path>`   | Every other command reads this as the target directory; `init` reads it as the output directory too, but only when `--dir` is omitted.                                                                                                                                                                                                                                                    |
+    | `--force`         | Overwrite the shipped skills, steps, agents and rules, the rule masters under `.agents/rules/`, their host wrappers, and generated Copilot instructions, whether or not you edited them. Project content, `qfai.config.yaml`, `DESIGN.md`, `AGENTS.md` and routing overrides are preserved. The managed `.gitignore` block and `core.symlinks` setting are repaired on every non-dry-run. |
+    | `--dry-run`       | Report what would change and write nothing.                                                                                                                                                                                                                                                                                                                                               |
+    | `--yes`           | Reserved for a future interactive mode; no behavioural difference today.                                                                                                                                                                                                                                                                                                                  |
+    | `--verbose`       | Expand the run report's `skipped` list to the full path listing. Off by default, so a no-op re-run prints the skip count and a pointer to this flag instead of every shipped asset path. It does not gate the written or removed listings: those are printed whenever they have entries, with or without this flag.                                                                       |
+    | `--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.                                                                                                                                                                                                                |
 
 - `npx qfai validate`
   - Validates the story tree, contracts and test obligations, writes `.qfai/report/validate.json`,
     and appends run logs to `.qfai/report/run-*/`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate,
     and `--format github` to emit GitHub-friendly annotations.
-    Use `--flow BF-0001` to scope a run to one business flow. `--spec` is retired.
+    Use `--flow BF-0001` to scope a run to one business flow.
     Use `--profile discussion|sdd|prototyping|atdd|tdd|verify` for local skill-owned checks; CI should use default/full validation (or `verify` / `tdd` for the dedicated CI gates).
 - `npx qfai report`
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
@@ -403,6 +408,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 +423,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
@@ -423,15 +431,29 @@ Notes.
   issue order are not stable; match on `issues[].code`.
 - `report.json`, `doctor.json`, and `run-*` JSON logs are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
 
-## Minimal tutorial
+## Dependency security
+
+The glob-matching dependency `braces` has an unresolved
+[stack-exhaustion denial-of-service advisory](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm).
+QFAI accepts this residual risk only for reviewed project patterns and paths,
+trusted configuration and trusted SDK callers. This is risk acceptance, not a
+clean audit or proof that QFAI is unaffected. Reproduction and exploitation in
+QFAI remain unverified.
+
+Review include, ignore and negative patterns, constructed paths and SDK inputs.
+`validateProject` accepts a caller-supplied `ConfigLoadResult` without invoking
+the configuration loader; the caller must review those values too. Catching
+errors and limiting results after glob expansion do not defend against stack
+exhaustion during expansion.
 
-1. `npx qfai init`
-2. Open your AI coding agent in the repository and describe the change in your own words.
-   If you only have an idea, say so: the run starts with a discussion that structures scope and open questions.
-3. Answer the questions the work puts to you, or say `stop` to end it.
-4. Run `npx qfai validate` then `npx qfai report`.
+Untrusted pull requests, externally supplied configuration and service request
+inputs are outside this acceptance. Review those inputs and restrict access;
+do not expose glob processing to them until your mitigation and security review
+cover them.
 
-To choose each stage yourself, see [Invoking a stage directly](#invoking-a-stage-directly-expert-path).
+Reassess the risk when a compatible patch becomes available or untrusted input
+is needed. A forced downgrade to `qfai@0.4.0` is not a compatible fix for the
+current major API; do not apply it through `npm audit fix --force`.
 
 ## FAQ
 
@@ -464,10 +486,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 +505,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 +535,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
@@ -572,11 +626,231 @@ Waiver policy.
 - Expired waivers are reported as warnings (`QFAI-WAIVER-003`) and must be renewed or removed with evidence.
 - Suppressed findings remain visible in reports as `suppressed=true`; waivers do not erase findings.
 
+When upgrading a project with `.qfai/waivers.yml`, back up that file. Check the
+current public finding codes and the release notes for confirmed removals or
+renames. Update a `rule:` value only when the documented rename preserves the
+finding's meaning and scope. Remove confirmed retired or inapplicable waivers,
+keeping the backup and recording each removal's reason for the operator. Do not
+rename whole code prefixes or automatically delete an unknown rule.
+
+Rerun full validation and require zero errors. An unknown waiver rule produces
+`QFAI-WAIVER-004` at `warning` and is not applied in that run; investigate it
+against the current diagnostics and release notes.
+
 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 +864,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:
@@ -668,7 +959,6 @@ commit that bumps the package, and to keep the two from being merged separately.
 │   │   └── open-questions.md
 │   └── waivers.yml
 ├── AGENTS.md
-├── CLAUDE.md
 └── qfai.config.yaml
 ```
 
@@ -705,17 +995,6 @@ provide those defaults to the agent.
 The `.claude` / `.github` agent wrappers are symlinks and follow the canonical document
 automatically; the Codex profiles are generated files, so rerun `npx qfai init --force`
 to refresh them (and any other wrapper asset that has drifted).
-`--force` deletes as well as overwrites: it removes the command and prompt wrappers
-under `.claude/commands/` and `.github/prompts/`, and the skill wrappers under
-`.claude/skills/`, `.agents/skills/`, `.codex/skills/` and `.github/skills/` for skills that are
-not in the current release, whether those wrappers are directories or symlinks.
-Files it did not write — a project's own slash command, prompt file or skill,
-including one published from a project-authored `.qfai/assistant/skill/` entry — are left in place,
-whatever they are named. Ownership is read from the file, not the name: a wrapper is removed only when
-it carries the delegation line to the canonical document of the same name, or is a symlink into
-`.qfai/assistant/skill/`. One consequence of that: a symlink has no content to prove who wrote it, so
-if you publish a canonical skill of your own under a name QFAI itself once shipped, `--force` removes
-that link. Your `.qfai/assistant/skill/` entry is untouched; re-create the link to publish it again.
 
 ### Supported hosts
 
@@ -725,7 +1004,9 @@ No host is declared supported in this release.
 ### Cross-AI rules and the writing reminder
 
 `npx qfai init` seeds `.agents/rules/**`, the rule set every AI coding agent in
-the project shares, and points `AGENTS.md` and `CLAUDE.md` at it. One of those
+the project shares, and points `AGENTS.md` at it, with a line for each rule that says when
+to read it. Claude Code reads `AGENTS.md` when the project has no `CLAUDE.md` (Claude Code
+2.1.277 or later). One of those
 rules, `documentation-clarity.md`, sets the writing standard for pull requests,
 issues, code comments and Markdown: no project-local identifiers, no account of
 how the work went, cut to what a reader outside the team can follow.
@@ -747,8 +1028,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 +1045,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/agent-routing/qfai-triage.yml

@@ -4,6 +4,15 @@
 routing:
   # The triage steps change no tracked file, so each has one author and no
   # build or test phase.
+  - step: triage-owned-cleanup
+    phases:
+      - id: cleanup
+        mandatory_agents: [devops-ci-engineer]
+        conditional_agents: []
+        parallel_groups: []
+        rerun_policy: changed-scope-dependents
+    review_profile: default
+
   - step: triage-close
     phases:
       - id: record

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/defaults/workflows/run-owned-cleanup.yml

@@ -0,0 +1,12 @@
+route: run-owned-cleanup
+family: upkeep
+stages:
+  - id: cleanup
+    kind: triage
+    steps: [triage-owned-cleanup]
+  - id: close
+    kind: triage
+    steps: [triage-close]
+    after: [cleanup]
+decisionPoints: []
+branchPoints: []