qfai 1.10.1 → 1.10.2

package/README.md

@@ -18,19 +18,34 @@ The agent reads the repository, produces the required artifacts, and iterates un
 ## Release status
 
 - Release posture: runtime truthfulness is enforced.
-- Prototyping is UI-only and runs a multi-spec evolution loop driven by
-  `qfai prototyping iterate --cycle <n>`. The skill resolves every
-  UI-bearing spec in one invocation, freezes that set at cycle 0, and
-  iterates `cycle 0..9` (max 10 cycles) with deterministic stop conditions
-  (exit codes 0 continue / 64 convergence / 65 max-iterations /
-  66 license-verify failure / 2 input or lock drift).
+- Prototyping is UI-only and runs a primary-spec evolution loop driven by
+  `qfai prototyping iterate --cycle <n>`. Each run resolves exactly one
+  primary UI-bearing spec (`prototyping.primarySpecId` in `qfai.config.yaml`,
+  a `surface_type: ui-bearing` marker, or `--primary-spec-id`), freezes it at
+  cycle 0, and iterates `cycle 0..9` (max 10 cycles) with deterministic stop
+  conditions (exit codes 0 continue / 64 convergence / 65 max-iterations /
+  66 license-verify failure / 2 input or lock drift). The full set of
+  UI-bearing specs is frozen at cycle 0 as `frozenSurfaceUnion` and is read
+  only to detect surface drift on later cycles: secondary specs are **not**
+  evaluated by that run. Only one primary spec can therefore be evolved per
+  project: re-running cycle 0 for a second spec is refused without `--force`,
+  and with `--force` it re-seeds `prototyping.json` (`runId`, `specsCovered`,
+  `frozenSpecsCovered`) around the new single spec, so the earlier spec's
+  iterations do not survive as a valid loop. Iterating a second UI-bearing
+  spec has to wait for the per-spec iteration layout.
 - Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
 - Per-iter evidence is a single `<screen>.review.json` per declared spec ×
   screen pair (4-axis ordinal verdicts, 6 `*Feel` short-prose impressions
   bounded to 200 words each, `layoutAntiPatternsDetected[]`,
-  `designMdViolations[]`, and `pivotDirective`). Reviewer-emitted
-  `<screen>.review.json` is the only per-cycle artifact — no `screenshot.png`,
-  `index.html`, or `interaction.json`.
+  `designMdViolations[]`, and `pivotDirective`). It is the only
+  reviewer-authored file, not the only per-cycle artifact: the CLI itself
+  always writes `iterate-plan.json` into the same `iter-NN/` directory, and
+  from cycle 1 onward — once the previous cycle is recorded in
+  `prototyping.json#iterations[]` — an advisory `iterate-context.json` holding
+  the prior scores and open blockers. The opt-in `--capture` and
+  `--cycle 0 --emit-skeletons` flags additionally write `<screen>.png` /
+  `<screen>.html` there. Archive the whole `iter-NN/` directory; no
+  `interaction.json` is written on any path.
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 
 ## Installation
@@ -77,6 +92,17 @@ npx qfai report
 - `npx qfai init`
   - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit
     (`assistant/` with the 4-layer tree — `constitution/`, `manifest/`, `catalog/`, `process/` — plus `agents/` and `skills/`), plus `qfai.config.yaml`.
+  - Options:
+
+    | Flag                       | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+    | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `--dir <path>`             | Output directory (default: the current directory).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+    | `--force`                  | Re-generate `.qfai/assistant/{skills,agents}/**` and the published skill/agent wrappers under `.agents/`, `.claude/`, `.codex/` and `.github/`, and prune the legacy wrappers they replace. It also rewrites two kinds of plain (non-wrapper) generated files without asking: the integration READMEs `.agents/README.md`, `.codex/README.md`, `.claude/agents/README.md`, `.github/agents/README.md`, and `.github/copilot-instructions.md` — local edits to those five files are overwritten, so back them up first. `.github/instructions/*.instructions.md` is create-only even under `--force`. The template trees `--force` does not own — `assistant/manifest/**`, `specs/`, `contracts/`, `steering/` and the rest of `.qfai/` — stay create-only. The flag does not narrow what plain `init` always does: the managed `.gitignore` block, the legacy `.qfai/evidence/.gitignore` negations and `git config core.symlinks` are re-applied (and repaired when stale) on every non-dry-run, with or without `--force`. |
+    | `--dry-run`                | Report what would change and write nothing. Use it to rehearse `--upgrade-assistant-tree`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    | `--upgrade-assistant-tree` | Migrate a pre-recut project to the 4-layer tree. Only the two pre-recut surfaces `.qfai/assistant/instructions/` and `.qfai/assistant/steering/` are scanned; `assistant/manifest/` is already the canonical layer, so it is kept in place and never re-copied. This is what the `D-DEPRECATED-PATH` finding is asking for. Files are copied, never deleted: the legacy paths stay until you remove them, and an existing file at a scanned surface's migration target is kept (reported as `W-USER-EDIT-PRESERVED`) — that warning only ever covers those scanned targets. A project left with nothing but `manifest/` has nothing to migrate and is reported as "no pre-recut surfaces ... found".                                                                                                                                                                                                                                                                                                                         |
+    | `--yes`                    | Reserved for a future interactive mode; no behavioural difference today.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+    | `--help`, `-h`             | Print the CLI usage banner and exit without writing anything. Accepted by every command, `init` included, and handled before the command runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and review artifacts
     (`.qfai/review/review-*/summary.json` + minimum schema), writes `.qfai/report/validate.json`,
@@ -96,7 +122,7 @@ npx qfai report
     Use `npx qfai prototyping preflight --target-url <url>` for a focused
     prototyping preflight before the skill starts; it surfaces blocking
     `QFAI-DCON-*` design-contract issues alongside runtime assumptions and resolves a runnable Playwright CLI launcher.
-    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the multi-spec
+    Use `npx qfai prototyping iterate --cycle <n> --target-url <url>` to drive each cycle of the primary-spec
     evolution loop. Exit codes: 0 (continue), 64 (convergence), 65 (max-iterations), 66 (license-verify failure), 2 (input or lock drift).
     Traceability refs inside prototyping evidence must use repo-root-relative concrete artifact refs
     (for example `.qfai/specs/spec-0001/01_Spec.md#L3` or `.qfai/evidence/prototyping/iter-03/home.png`).
@@ -137,7 +163,7 @@ a `TC` obligation is routed by the `Level` its spec declares for it.
   | none declared, or unreadable  | `tests/integration/**` |
 
 - Unit and Component test cases carry **no** ATDD annotation obligation. They are gated by the
-  `tdd/test-list.md` ledger instead, so do not copy them into `tests/integration/**` to satisfy this gate.
+  per-spec `test-list.md` ledger instead, so do not copy them into `tests/integration/**` to satisfy this gate.
 - A `TC` annotation outside the directory its declared `Level` names is rejected. The rule is `Level`-relative,
   not a blanket ban: a `TC` in `tests/api/**` is accepted only for a test case that declares `L4`/`API`, and in
   `tests/e2e/**` only for `L5`/`E2E`.
@@ -177,9 +203,10 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
   in `.qfai/specs/_policies/03_Capabilities.md` before the row is accepted
   (`QFAI-TRIAGE-006`). Every `01_Spec.md` declares a lifecycle
   `Status: active | superseded | deprecated | removed` (`QFAI-STATUS-001..006`).
-- **qfai-prototyping**: Multi-spec parallel design evolution loop. Resolves
-  every UI-bearing spec in one invocation, freezes that set at cycle 0,
-  and iterates each `spec × screen` pair through up to 10 cycles
+- **qfai-prototyping**: Primary-spec design evolution loop. Resolves exactly
+  one primary UI-bearing spec per invocation and freezes it at cycle 0 (the
+  full UI-bearing set is recorded as `frozenSurfaceUnion` for drift detection
+  only), then iterates each `spec × screen` pair through up to 10 cycles
   (`cycle 0..9`) of generate → capture → review with a 4-axis ordinal
   rubric, 6 `*Feel` short-prose impressions (200-word bounded), explicit
   layout anti-pattern detection (`lap-001..lap-008`), DESIGN.md token
@@ -292,7 +319,14 @@ validation:
 
 Notes.
 
-- `validate.json`, `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.
+- `validate.json` is a **public** surface: its keys are documented in
+  `.qfai/assistant/skills/qfai-verify/references/validate-json-schema.md` and a change to
+  them takes the `@api` path (`.qfai/assistant/constitution/change-classification.md`). The
+  skills instruct agents to read it, so it is a contract whether or not this file says so —
+  it used to say the opposite, which left a consumer following the skills depending on
+  something the README disclaimed. `message` text and the order of `issues` are still 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.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 - `prototyping.calibration.packPath` points to the calibration pack SSOT; runtime and validator both resolve thresholds and iteration parameters from that pack.
 - `prototyping.calibration.thresholds`, `maxIterations`, `plateauDelta`, and `plateauLookback` are unsupported public config fields.
@@ -364,8 +398,10 @@ Release gate behavior:
 
 QFAI generates integration wrappers under `.agents/**`, `.claude/**`,
 `.github/**`, and `.codex/**`.
-It does not generate GitHub Actions workflows.
-Configure CI in your own platform and run:
+Into `.github/workflows/` it writes exactly two files — `qfai-validate.yml`
+and `qfai-tests.yml` — and touches nothing else there; both open with a
+`# Generated by \`qfai init\`` line. Configure the rest of CI in your own
+platform and run:
 
 ```bash
 pnpm ci:gate
@@ -478,6 +514,7 @@ Typical customizations.
 │   │       ├── spec_required_files.json
 │   │       ├── structure.md
 │   │       ├── tech.md
+│   │       ├── test-layers-ci-lanes.md
 │   │       ├── test-layers.md
 │   │       ├── ui-definition-protocol.md
 │   │       └── worklog-entry.schema.md
@@ -492,7 +529,7 @@ README files. Those files are created later by QFAI skills when real work exists
 ### AI work-log surface (`.qfai/steering/`)
 
 `qfai init` also creates `.qfai/steering/`, the per-project work-log surface for
-AI coding agents, with a `README.md` and `_templates/entry.md`. Each entry is a
+AI coding agents, with a `README.md` and an `entry.md` template under `_templates/`. Each entry is a
 markdown file with YAML frontmatter, and `npx qfai validate` polices the surface in
 the `sdd` and full profiles via `W-WORKLOG-SCHEMA`, `W-WORKLOG-BROKEN-LINK`,
 `W-WORKLOG-STALE`, `W-PENDING-PROMOTION` and `R-HANDOFF-INCOMPLETE`.
@@ -509,7 +546,7 @@ Integration wrappers are also generated for immediate use:
 - Agents/Codex VS Code: `.agents/skills/**`
 - Claude Code: `.claude/skills/**`, `.claude/agents/**`
 - GitHub Copilot: `.github/skills/**`, `.github/agents/**`
-- Codex: `.codex/skills/**`
+- Codex: `.codex/skills/**`, `.codex/agents/**`
 
 ## Agent integrations
 
@@ -517,12 +554,30 @@ Integration wrappers are also generated for immediate use:
 and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
 Canonical agent markdown under `.qfai/assistant/agents/**` uses a shared YAML frontmatter
 subset (`name`, `description`, `tools`) compatible with Claude Code and GitHub Copilot,
-while Codex consumes mirrored `.codex/agents/*.toml` profiles.
-If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
+while Codex consumes `.codex/agents/*.toml` profiles generated from that same markdown.
+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 earlier releases
+installed under `.claude/commands/` and `.github/prompts/`, and the skill wrappers it installed under
+`.claude/skills/`, `.agents/skills/`, `.codex/skills/` and `.github/skills/` for skills QFAI no longer
+ships — the directory wrappers releases before the symlink recut copied there as well as the symlinks
+that replaced them. Files it did not write — a project's own slash command, prompt file or skill,
+including one published from a project-authored `.qfai/assistant/skills/` 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/skills/`. 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/skills/` entry is untouched; re-create the link to publish it again.
 
 ## Contributing (for QFAI maintainers)
 
-This repository is a monorepo, and the distributable package is under `packages/qfai`; if you change documentation, keep the repository root README and the package README aligned (the CI enforces this).
+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
 

package/assets/init/.qfai/assistant/agents/completion-reviewer.md

@@ -67,7 +67,7 @@ being asked to judge, and falls into its own Stop condition ("Required evidence
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
-- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

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

@@ -37,8 +37,8 @@ tools: [Read, Glob, Grep, Bash]
 
 **The last two are what the `Audited evidence hash` is computed over.** This
 role records that hash itself, over the row's phase-authored fields — and those
-live in an evidence file that is normally ignored, so the diff of changed files
-does not contain them. Without the ledger and the evidence home the row's
+live in a committed per-item evidence file so a fresh clone can reproduce the
+audit. Without the ledger and the evidence home the row's
 `Layer` selects, this role cannot identify its own audit subject: the hash goes
 missing and gate items 10-11 stop, or the orchestrator computes it instead,
 which is the one thing the contract says must not happen.
@@ -66,7 +66,7 @@ which is the one thing the contract says must not happen.
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
-- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding traces to `none` or `record:*`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

package/assets/init/.qfai/assistant/agents/orchestrator.md

@@ -32,7 +32,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Work Orders for each subagent (scope, inputs, outputs, gates)
 - Stage Gates plan + current status
 - Completion report (DoD checklist + evidence links)
-- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
+- Evidence summary for `.qfai/evidence/` (commit only paths re-included by the managed block)
 
 ## Stop conditions
 
@@ -45,7 +45,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 ## Sign-off
 
 - [ ] Deliverables are complete
-- [ ] Evidence is present (gitignored)
+- [ ] Evidence is present under the managed tracking policy
 - [ ] Stage gates are PASS
 - [ ] Reviewer sign-off recorded
 

package/assets/init/.qfai/assistant/agents/product-experience-architect.md

@@ -30,7 +30,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .github/instructions/principles.instructions.md
 - Root `DESIGN.md` (brand SSOT: front-matter tokens plus `# Brand Philosophy` body)
 - Reference pool framed as deviate-from inputs, screen contracts (`uiux/40_screen_contracts.md`), optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
-- Evaluator axes are fixed in `core/prototyping/evaluatorReview.ts#ORDINAL_AXES` (information architecture / navigation flow / usability / functionality) and no longer authored as sidecar files
+- Evaluator axes (information architecture / navigation flow / usability / functionality) are fixed by
+  the review validation the QFAI CLI applies (restated in `.qfai/assistant/skills/qfai-prototyping/references/reviewer-prompt.md`), not sidecar files
 - Runtime screenshots or rendered evidence when available
 
 ## Deliverables

package/assets/init/.qfai/assistant/agents/product-surface-reviewer.md

@@ -15,7 +15,7 @@ tools: [Read, Glob, Grep, Bash]
 - Audit frontend changes for correctness and user-facing risk.
 - Audit layout sanity, interaction usability, and accessibility guardrails.
 - Audit visual design, token alignment, and service-level UX coherence.
-- Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
+- Reconcile sidecar artifacts (screen contracts), design tokens, mermaid flows, and rendered output consistency.
   HTML mock is optional fallback evidence only. Design tokens are supporting input.
 - For UI implementation, compare rendered output against `.qfai/contracts/design/prototype-handoff.yaml`, canonical prototype screenshots, HTML snapshots, and `.qfai/prototypes/winner/index.html`.
 - Reject prototype parity when implementation loses CTA hierarchy, spacing rhythm, information density,

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

@@ -138,9 +138,8 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 
 - Confirm a Coverage Depth Matrix exists at `.qfai/evidence/coverage-depth-<spec-id>.md` (produced by `test-design-analyst`).
   Missing matrix: REVISE from the ATDD review cycle onward; on an SDD review cycle record it as a finding. See the scope note.
-  A matrix that exists only inside `.qfai/evidence/atdd-<spec-id>.md` is a **missing** matrix: that file is ignored by the
-  managed `.gitignore` block, so neither it nor the justification for any `❌` reaches a commit, and the "unjustified"
-  judgement cannot be re-made by anyone reading the repository.
+  A matrix that exists only inside `.qfai/evidence/atdd-<spec-id>.md` is a **missing** matrix: that committed file is the
+  ledger's per-item evidence payload, not the dedicated matrix artifact whose justifications this gate reads.
 - Check that each US/TC has test cases for at minimum: normal path AND error/failure path.
 - Flag any US/TC that has only normal-path test cases as a coverage gap.
 - Reference: `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`
@@ -154,8 +153,9 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 The Coverage Depth Matrix is an **ATDD-stage artifact**: it is defined in
 `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`, listed as an ATDD
 Mandatory Output,
-and written to `.qfai/evidence/coverage-depth-<spec-id>.md` — a committed path, unlike the rest of
-`.qfai/evidence/**`. `qfai-sdd` neither defines its layout nor ships a section for it, so:
+and written to `.qfai/evidence/coverage-depth-<spec-id>.md` — a committed governance path alongside
+`implement-<spec-id>.md` and `atdd-<spec-id>.md`. Only run-scoped evidence remains ignored.
+`qfai-sdd` neither defines the matrix layout nor ships a section for it, so:
 
 - Apply this check from the **ATDD review cycle onward**, where
   `.qfai/assistant/skills/qfai-atdd/SKILL.md` lists

package/assets/init/.qfai/assistant/agents/test-design-analyst.md

@@ -59,8 +59,9 @@ At both stages: when business rules (BR-\*) exist, verify each BR has at least o
 - Test-case quality and traceability findings
 - **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
   Destination: `.qfai/evidence/coverage-depth-<spec-id>.md` from the ATDD stage onward — its own
-  file, because that path is committed while the rest of `.qfai/evidence/**` is ignored, and the
-  justification behind each `❌` is the input `qa-gatekeeper` reads. During SDD there is
+  file, because it has its own committed governance lifecycle separate from the committed
+  per-item TDD evidence, and the justification behind each `❌` is the input `qa-gatekeeper`
+  reads. During SDD there is
   no evidence artifact that holds it, so report depth gaps as findings instead of producing the
   matrix format.
 - Volume estimate and risk notes

package/assets/init/.qfai/assistant/catalog/cli-ux-guidelines.md

@@ -42,6 +42,9 @@ QFAI が定義する、`npx qfai validate` の UI/UX 関連出力ガイドライ
 - 許容値: `web`, `windows`, `mobile-ios`, `mobile-android`, `cross-platform`
 - 未指定時: 自動検出（config → project files → fallback to `web`）
 - 未知の値: warning 発行。platform 値は保持しつつ、実質的に common ルールのみ適用
+- 参照する profile: `prototyping` / `verify` / `full` / `saas-package` のみ。
+  `discussion` / `sdd` / `atdd` / `tdd` は platform を読まないため、これらに
+  `--platform` を渡すと未使用である旨の warning のみを発行する（未知値チェックは走らない）
 
 ## Known Limitations