qfai 1.9.2 → 1.10.0

package/README.md

@@ -33,6 +33,28 @@ The agent reads the repository, produces the required artifacts, and iterates un
   `index.html`, or `interaction.json`.
 - Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 
+## Installation
+
+qfai is published on npm as **`qfai`**. Install it as a dev dependency:
+
+```bash
+npm i -D qfai
+# or: pnpm add -D qfai / yarn add -D qfai
+```
+
+Let the package manager write the `devDependencies` entry. Do not hand-pin a version
+here: `package.json#version` in the published package is the only version source, and a
+number copied from prose goes stale on the next release.
+
+> **Do not install from the GitHub repository.** A git specifier such as
+> `"qfai": "github:aganesy/QFAI"` maps the dependency key `qfai` to the private monorepo
+> root — the manifest `name` is irrelevant, so it lands in `node_modules/qfai` regardless.
+> That root ships no `bin` and no built `dist`, so nothing would be runnable or
+> importable. Under npm or yarn a `preinstall` guard refuses the install with an
+> explanatory error rather than completing silently; under pnpm — or any package manager
+> that reports no user agent — it is not caught, so the mistake is yours to avoid. Use the
+> npm package, or run it without installing via `npx qfai@latest <command>`.
+
 ## Quick start
 
 > **Windows users:** `qfai init` creates symlinks internally.
@@ -220,7 +242,10 @@ Operational notes.
 - Skills should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
 - Change classification (Primary/Tags) is required in `09_delta.md` and recommended in PRs. See `.qfai/assistant/constitution/change-classification.md`.
 - Verification planning is recorded in `09_delta.md` (`Verification -> Plan`) and validated in CI (`VFY-*` rules).
-- Review gate policies (required/optional layers and reviewers) are defined in `.qfai/assistant/catalog/review-gate.rules.yml`.
+- Review gate policies (required/optional layers, default reviewers, optional
+  review modes) are documented in `.qfai/assistant/catalog/review-gate.rules.yml`.
+  This catalog is reference material for agents; it is not machine-enforced.
+- Review pack structure — `.qfai/review/review-<YYYYMMDDhhmmssSSS>/{review_request.md,R01_*.md,summary.json}` — is the one layout enforced by validation (`QFAI-REVIEW-*`).
 - Agent taxonomy and invocation SSOT are defined in `.qfai/assistant/manifest/agent-catalog.yml`, `.qfai/assistant/manifest/agent-routing.yml`, and `.qfai/assistant/manifest/review-profiles.yml`.
 
 ## Configuration
@@ -343,6 +368,11 @@ Recommended baseline.
 
 Waiver policy.
 
+- A waiver's `rule:` is the finding's `code`, copied verbatim from
+  `.qfai/report/validate.json` — `QFAI-ATDD-112`, `TDDLIST_UNKNOWN_LEVEL`,
+  `E_TC_ORPHAN`. Do not strip the `QFAI-` prefix; the stripped form
+  (`ATDD-112`) is kept working only for waiver files written against older
+  releases.
 - Use waivers only for `warning` / `info` findings (false positives).
 - Waivers that target `error` findings are invalid and fail validation (`QFAI-WAIVER-002`).
 - Expired waivers are reported as warnings (`QFAI-WAIVER-003`) and must be renewed or removed with evidence.
@@ -434,7 +464,8 @@ Typical customizations.
 │   │       ├── structure.md
 │   │       ├── tech.md
 │   │       ├── test-layers.md
-│   │       └── ui-definition-protocol.md
+│   │       ├── ui-definition-protocol.md
+│   │       └── worklog-entry.schema.md
 │   └── waivers.yml
 └── qfai.config.yaml
 ```
@@ -443,6 +474,21 @@ Typical customizations.
 contracts, evidence, reports, reviews, placeholder spec directories, or artifact
 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
+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`.
+
+The frontmatter contract and the **per-kind write trigger** — which `kind` an
+agent writes when — are in the seeded
+`.qfai/assistant/catalog/worklog-entry.schema.md`.
+
+Note that `.qfai/steering/` (the work-log surface) is a different directory from
+the legacy `.qfai/assistant/steering/` (the pre-recut assistant path).
+
 Integration wrappers are also generated for immediate use:
 
 - Agents/Codex VS Code: `.agents/skills/**`

package/assets/init/.qfai/assistant/agents/acceptance-test-engineer.md

@@ -32,6 +32,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Acceptance test plan and implemented coverage
 - Mapping from US / TC / CON-API to test assets
 - Execution proof and evidence summary
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Gaps and follow-up actions
 
 ## Stop conditions

package/assets/init/.qfai/assistant/agents/backend-engineer.md

@@ -35,6 +35,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Backend implementation summary
 - Changed files and affected contracts
 - Local verification notes
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Evidence summary for `.qfai/evidence/`
 - Notes on invariants, validation, and why added abstractions/configuration are necessary now
 

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

@@ -12,7 +12,7 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Domain Responsibilities
 
-- Return pass/fail only with actionable rework instructions.
+- Return only PASS or REVISE, with actionable rework instructions on REVISE.
 - Enforce validate evidence, required coverage obligations, and no self-approval.
 - Verify rejected options are not reintroduced without RE-OPEN.
 
@@ -27,20 +27,31 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Deliverables
 
-- PASS or FAIL with concrete rework list
+- PASS or REVISE with concrete rework list
 - Evidence summary and gaps
 - Open risks or blocking assumptions
 
 ## Stop conditions
 
 - Required evidence, governing specs, or target artifacts are missing.
+  - "Required evidence" means the evidence this review audits — the phase-authored record produced
+    before the review was requested. A completion record that this review's own verdict will be
+    written into is not yet expected to be finalized; its missing verdict fields are not a stop
+    condition and not a blocking finding. Report an unfinalized completion record as a sequencing
+    note, not as a gap.
 - The request requires implementation or file editing instead of independent review.
 - The issue falls outside this review domain and must be rerouted to another specialist first.
+- The finding would add a product obligation upstream never asked for. Do not raise it as blocking;
+  raise it as an advisory finding plus a Change Request proposal per
+  `.qfai/assistant/constitution/drift-protocol.md#reviewer-originated-obligations`. A defect you can
+  demonstrate from the changed artifacts (correctness, security / data integrity, or a repository
+  quality gate) is NOT in this category: it stays blocking and traces to its `defect:*` class.
 
 ## Sign-off
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

package/assets/init/.qfai/assistant/agents/delivery-planner.md

@@ -17,6 +17,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Define parallel-safe slices and post-merge verification conditions.
 - Own schedule, priority, and risk trade-offs across roles.
 - Produce actionable work orders for workers and reviewers.
+- Own **item selection and item scope** in a TDD micro-cycle, and Red-Green-Refactor phase ordering. Raise a scope REVISE **before** RED/GREEN evidence is submitted to `qa-gatekeeper`; do not
+  re-litigate item scope after `qa-gatekeeper` has passed the observation for that round — open a new ledger row instead.
+
+## Ownership boundaries
+
+- `qa-gatekeeper` owns RED/GREEN **observation** evidence (did the test fail or pass for the expected reason). This role does not overrule that verdict, and that verdict does not widen item scope.
+  See `.qfai/assistant/skills/qfai-implement/SKILL.md#precedence-between-delivery-planner-and-qa-gatekeeper`.
 
 ## Inputs you must read
 
@@ -24,6 +31,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
+- `.qfai/specs/spec-*/tdd/test-list.md` — the execution ledger this role selects
+  the next item from and whose Red-Green-Refactor ordering it enforces
 - .qfai/discussion/discussion-\*/04_Sources.md
 - .qfai/discussion/discussion-\*/06_REQ.md
 - .qfai/discussion/discussion-\*/11_OQ-Register.md

package/assets/init/.qfai/assistant/agents/frontend-engineer.md

@@ -34,6 +34,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Frontend implementation summary
 - Changed files and affected flows
 - Local verification notes
+- TDD ledger Status + Evidence entry for each item processed, returned to the orchestrator (which owns the `test-list.md` write; do not edit that file directly)
 - Evidence summary for `.qfai/evidence/`
 - Notes on how simplicity, necessity, and reuse were preserved in the chosen implementation
 

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

@@ -45,11 +45,17 @@ tools: [Read, Glob, Grep, Bash]
 - The request requires implementation or file editing instead of independent review.
 - The issue falls outside this review domain and must be rerouted to another specialist first.
 - The review would rely on speculative future requirements instead of current scope and evidence.
+- The finding would add a product obligation upstream never asked for. Do not raise it as blocking;
+  raise it as an advisory finding plus a Change Request proposal per
+  `.qfai/assistant/constitution/drift-protocol.md#reviewer-originated-obligations`. A defect you can
+  demonstrate from the changed artifacts (correctness, security / data integrity, or a repository
+  quality gate) is NOT in this category: it stays blocking and traces to its `defect:*` class.
 
 ## Sign-off
 
 - [ ] Review verdict is explicit
 - [ ] Findings cite concrete artifacts or evidence
+- [ ] Every finding declares `Severity:` and `Traces to:`; no blocking finding has `Traces to: none`
 - [ ] Required gates and residual risks are recorded
 
 ## When to use

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

@@ -23,7 +23,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - .qfai/assistant/constitution/\*\*
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/assistant/catalog/test-layers.md (SSOT for hard coverage obligations)
-- .qfai/specs/spec-\*/09_delta.md (Decision Records; check rejected)
+- .qfai/specs/spec-\*/07_Decisions.md and .qfai/specs/\_policies/08_Decisions.md (Decision Records, DR-\*; check rejected)
 - Prompt-specific artifacts (traceability, validation evidence, optional legacy scenario/ledger artifacts)
 
 ## Deliverables (MANDATORY)
@@ -37,7 +37,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 ## Stop conditions
 
 - Subagent delegation missing when required
-- Validation gate evidence missing/failing (`qfai validate --fail-on error`)
+- Validation gate evidence missing/failing (`npx qfai validate --fail-on error`)
 - Required hard obligations in `test-layers.md` are unmet
 - Reviewer sign-off missing
 - Rejected option would be reintroduced without RE-OPEN DR

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

@@ -17,16 +17,104 @@ tools: [Read, Glob, Grep, Bash]
 - Audit prototyping coverage evidence and unresolved spec coverage.
 - Treat density or volume smells as review signals, not standalone hard gates.
 - Verify test-case quality depth using the Coverage Depth Matrix (see below).
+- Own RED/GREEN **observation** evidence in a TDD micro-cycle: did the test fail (or pass) for the expected reason.
+
+## Ownership boundaries
+
+- `delivery-planner` owns **item selection and item scope** — whether a ledger row's selector is a sufficient slice of its `TC-*` obligation. Do not adjudicate item scope here; a PASS on observation
+  evidence is explicitly scoped to that observation and never widens or ratifies item scope. See `.qfai/assistant/skills/qfai-implement/SKILL.md#precedence-between-delivery-planner-and-qa-gatekeeper`.
+- Refuse to evaluate RED/GREEN evidence while an unresolved `delivery-planner` scope REVISE is open on the same item.
+
+## Oracle Strength Check (MUST)
+
+GREEN is `exit code == 0`. That does not say the pass depends on the behaviour
+the item owns, and nothing downstream re-asks: coverage is annotation presence
+and the Depth Matrix counts case categories. A test that cannot fail otherwise
+clears every gate.
+
+Require an `Oracle proof` on each item and **reject** it when:
+
+- the mutation is outside the code the item owns — breaking a shared helper
+  proves the helper is used, not that this test discriminates;
+- the mutation is a syntax error, a thrown "not implemented", or a deleted
+  export — that is a load failure, not a discriminating failure;
+- the failing output names a selector other than the row's;
+- the recorded command differs from the `GREEN command`.
+
+`equivalent-mutant` is acceptable **only** when the named contract clause is
+genuinely weaker than the obligation. It is an upstream gap: route it as an
+advisory / Change Request, do not send the implementer to strengthen an
+assertion past the contract — that is reviewer-originated scope, which
+`drift-protocol.md` forbids. Full criteria and the weak-oracle shapes:
+`.qfai/assistant/skills/qfai-implement/references/oracle-strength.md`.
+
+## RED/GREEN Observation Gate (MUST)
+
+This is the gate `qfai-implement` routes here as blocking, per ledger row. Judge
+the row's own evidence; nothing in the calling work order substitutes for it.
+
+**Accept a RED** only when all hold:
+
+- the test module loaded — the failure is not a collection, import, syntax,
+  missing-symbol or fixture error;
+- an assertion (or expected-exception check) inside the row's own `Selector`
+  raised it, and the message names the predicate the row owns;
+- the recorded output retains that assertion message and its location;
+- when the `Selector` holds several entries, each entry's failure was observed
+  separately. One aggregate run is not a RED for several entries.
+
+**Accept a GREEN** only when the same command shape ran after the production
+change and the recorded output shows the row's own selector passing. A full-suite
+pass that does not name the row's selector is not a GREEN for that row.
+
+**Never accept as a substitute** for a captured failing run of the item's own
+test:
+
+- a narrative claim that the test failed, in any artifact, including a commit
+  message written by the implementing agent — that is self-attestation, which is
+  what this gate exists to prevent;
+- a load error standing in for an assertion failure;
+- evidence copied from a previous round or a sibling row;
+- "the suite is green" in place of the row's own GREEN.
+
+The one legitimate absence is the _RED not observable_ path: the obligation is
+already satisfied by a sibling row, so the correct test passes first run. Then
+require `Satisfied-by`, `Falsifiability command` and `Falsifiability result`
+instead — never both forms, never neither. See
+`.qfai/assistant/skills/qfai-implement/references/red-not-observable.md` and
+`.qfai/assistant/skills/qfai-implement/references/red-admissibility.md`.
+
+Verdict scope: a PASS covers the observation for that round and nothing else. It
+does not ratify item scope and does not clear the completion gate.
 
 ## Test Case Quality Depth Check (MUST)
 
 In addition to traceability-based coverage (US/TC/CON-API existence), verify the **depth** of test cases:
 
-- Confirm a Coverage Depth Matrix exists (produced by `test-design-analyst`). If missing, return FAIL.
+- Confirm a Coverage Depth Matrix exists (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.
 - 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`
-- This check is a review signal (not a hard gate that blocks validation), but unjustified gaps MUST be documented as findings.
+- Which verdict applies depends on the review cycle, per the scope note below.
+  On an **SDD** cycle this check is a review signal, not a hard gate that blocks validation.
+  From the **ATDD** cycle onward a missing matrix — or one whose ❌ cells are unjustified — is a REVISE.
+  Either way, unjustified gaps MUST be documented as findings.
+
+### Scope of this check
+
+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 into `.qfai/evidence/atdd-<spec-id>.md`. `qfai-sdd` neither defines its 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
+  the matrix under both Mandatory Outputs and Not-done criteria. A missing matrix is a REVISE there,
+  and so is one whose ❌ cells are unjustified.
+- Do NOT evaluate it against an SDD spec pack that has no tests yet. On an SDD review cycle,
+  assess depth directly from `06_Test-Cases.md` (normal path plus error/boundary coverage per
+  AC) and record any gap as a finding, without requiring the matrix format.
 
 ## Inputs you must read
 
@@ -35,13 +123,18 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 - .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
+- `.qfai/specs/spec-*/tdd/test-list.md` — the ledger row under review
+- `.qfai/evidence/implement-<spec-id>.md` — the per-item RED/GREEN evidence this
+  role adjudicates. Both are listed because the Stop condition below ("target
+  artifacts are missing") is not checkable against an artifact this role was
+  never told to open.
 - `.qfai/report/validate.log`
 - `.qfai/report/specs-coverage/spec-*.md`
 - Runtime evidence and prototyping evidence artifacts
 
 ## Deliverables
 
-- Gate decision (PASS / FAIL) with rationale
+- Gate decision (PASS / REVISE) with rationale
 - Hard gate status and required fixes
 - Evidence summary and unresolved quality gaps
 

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

@@ -17,16 +17,30 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Estimate test volume as a planning signal, not a hard gate.
 - Prevent unit/component scope creep and ambiguous layer ownership.
 - Evaluate test-case depth using the structured checklist (see reference below).
-- Produce a Coverage Depth Matrix for each spec to expose gaps in boundary values, error paths, edge cases, and combinatorial scenarios.
+- Produce a Coverage Depth Matrix per spec from the ATDD stage onward, exposing gaps in boundary values, error paths, edge cases,
+  and combinatorial scenarios. During SDD, report the same gaps as findings instead — see the stage split below.
 
 ## Test Case Quality Depth (MUST)
 
 When reviewing or producing test cases, apply the checklist in `.qfai/assistant/skills/qfai-atdd/references/test-case-depth-checklist.md`.
 
+Read the stage split first: the checklist's full category set and the Coverage Depth Matrix are ATDD-stage obligations. `qfai-sdd` neither
+defines the matrix layout nor ships an artifact that holds it, and the tests do not exist yet, so the SDD rules below replace them.
+
+From the ATDD stage onward:
+
 - For each US/TC, verify that test cases exist for: normal path, error path, boundary values, special values, state transitions, and combinatorial scenarios.
 - Produce the Coverage Depth Matrix as a required deliverable. Flag any ❌ cells as gaps.
 - Test cases covering only normal (happy) paths are INCOMPLETE. Return REVISE with specific missing scenarios.
-- When business rules (BR-\*) exist, verify each BR has at least one positive and one negative test case.
+
+During SDD:
+
+- Require normal path plus error/boundary coverage per AC, read directly from `06_Test-Cases.md`.
+- Record any further depth gap (special values, state transitions, combinatorial) as a finding.
+- Do NOT produce the matrix, and do NOT return REVISE solely because the matrix is absent or because
+  special / state-transition / combinatorial cases are not yet enumerated.
+
+At both stages: when business rules (BR-\*) exist, verify each BR has at least one positive and one negative test case.
 
 ## Inputs you must read
 
@@ -43,7 +57,10 @@ When reviewing or producing test cases, apply the checklist in `.qfai/assistant/
 
 - Coverage plan and layer ownership
 - Test-case quality and traceability findings
-- **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference)
+- **Coverage Depth Matrix** (per spec, using the template in the depth checklist reference).
+  Destination: `.qfai/evidence/atdd-<spec-id>.md` from the ATDD stage onward. 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
 - Scope-boundary decisions for tests
 

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

@@ -1,11 +1,11 @@
 # CLI UX Guidelines
 
-QFAI が定義する、`qfai validate` の UI/UX 関連出力ガイドライン。
+QFAI が定義する、`npx qfai validate` の UI/UX 関連出力ガイドライン。
 
 ## Output Format
 
 - Issue メッセージにタイムスタンプやランダム値を含めない（冪等性確保）
-- `## Auto Check Results` — `qfai validate` による自動チェック結果セクション
+- `## Auto Check Results` — `npx qfai validate` による自動チェック結果セクション
 - `## Manual Review Results` — product-surface-reviewer による手動レビュー結果セクション
 
 ## Error Message Format

package/assets/init/.qfai/assistant/catalog/spec_required_files.json

@@ -21,6 +21,7 @@
     "07_Constraints.md",
     "08_Decisions.md",
     "09_Open-questions.md",
-    "10_delta.md"
+    "10_delta.md",
+    "11_Slice-Policy.md"
   ]
 }