qfai 1.7.13 → 1.7.15

package/README.md

@@ -17,8 +17,12 @@ The agent reads the repository, produces the required artifacts, and iterates un
 
 ## Release status
 
-- Current package version: `1.7.13`
-- Release posture: v1.7.13 converges init assets, validators, and docs on the canonical sidecar model.
+- Current package version: `1.7.15`
+- Release posture: v1.7.15 enforces runtime truthfulness.
+- Prototyping is UI-only; `full-harness` is measurement-driven iteration accumulation for UI-bearing surfaces only.
+- Runtime observation is observed-only (no synthetic 200 / API / DB prototyping coverage).
+- Browser QA is mandatory per screen in full-harness, and `actionsWired` reports action coverage rather than finding count.
+- Calibration SSOT is the calibration pack referenced by `calibrationRef.packPath`.
 - Current repo note: some repo-wide `qfai validate --fail-on error` blockers still come from historical review/evidence/ATDD/TDD artifacts and are being cleaned incrementally.
 
 ## Quick start
@@ -54,8 +58,27 @@ npx qfai report
 - `npx qfai doctor`
   - Diagnoses configuration discovery, path resolution, glob scanning, and `validate.json` inputs before running validate/report; use `--fail-on` to enforce failures in CI.
     Note: prototyping evidence (`.qfai/evidence/prototyping.json`) is produced by the AI workflow / skills
-    (`/qfai-prototyping` with `mode=low-cost|standard|full-harness`), not by a CLI command.
+    (`/qfai-prototyping` with `mode=full-harness` for supported UI surfaces only), not by a general-purpose end-user CLI flow.
     `qfai validate` consumes the resulting evidence files, including `mode.effective` and `fullHarness` metadata when present.
+    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/render.json#/screens/0`).
+    Absolute paths are invalid. The same strict ref grammar is enforced for top-level and leaf evidence-bearing fields, including
+    `runtimeGate.evidenceRefs`, `runtimeGate.ui[].declaredRef`, `runtimeGate.ui[].renderEvidenceRefs[]`,
+    `runtimeGate.ui[].browserQaEvidenceRefs[]`, `specs[].coverageRefs[].declaredRef`, `specs[].coverageRefs[].observedRefs[]`,
+    `fullHarness.iterations[].evidenceRefs.runtimeGate`, `fullHarness.iterations[].evidenceRefs.specCoverage`,
+    `fullHarness.iterations[].evidenceRefs.render`, `fullHarness.iterations[].evidenceRefs.browserQa`,
+    `fullHarness.iterations[].evidenceRefs.uiObservation`, `fullHarness.iterations[].evidenceRefs.discussion`,
+    `fullHarness.iterations[].evidenceRefs.screenContract`, `fullHarness.iterations[].evidenceRefs.trend`,
+    `fullHarness.iterations[].l1.axes[].evidenceRefs[]`, `fullHarness.iterations[].l2.axes[].evidenceRefs[]`, and
+    `fullHarness.reviewerLogs[].evidenceRefs[]`.
+    Semantic rules are also strict: `runtimeGate.ui[].declaredRef` and `fullHarness.iterations[].evidenceRefs.screenContract[]`
+    must use the canonical screen contract sourceRef `.qfai/discussion/<pack>/uiux/40_screen_contracts.md#<screenId>`,
+    and `specs[].coverageRefs[].declaredRef` must use the canonical spec declaration form
+    `.qfai/specs/<specId>/01_Spec.md#L<line>` (for example `.qfai/specs/spec-0001/01_Spec.md#L3`);
+    `notes.md`, `appendix.md`, anchor-fragment forms such as `#route-home`, discussion refs, and screen contract refs
+    are NOT valid `declaredRef` values.
+    `fullHarness` follows a terminal-first state machine: `status="in-progress"` requires `finalDecision="pending"`,
+    `reviewerSignoff.status="pending"`, and no `terminationReason`; `status="completed"` requires `terminationReason`,
+    a non-pending `finalDecision`, and a terminal `reviewerSignoff`.
 
 ## ATDD annotation hard gate
 
@@ -85,9 +108,11 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 - **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure)
   and tailor `qfai.config.yaml` accordingly (especially `testFileGlobs`).
   Run this once right after `npx qfai init`, and re-run it when the repository structure changes.
-- **qfai-discussion**: Run a unified structured discussion that produces and maintains the latest discussion pack as 15 required markdown files plus required prototyping.yaml under `.qfai/discussion/discussion-<ts>/`.
+- **qfai-discussion**: Run a unified structured discussion that produces and maintains the latest discussion pack
+  as 15 required markdown files under `.qfai/discussion/discussion-<ts>/`.
+  UI-bearing discussion packs require `prototyping.yaml`; non-ui discussion packs do not.
 - **qfai-sdd**: Unified SDD entrypoint with discussion-pack preflight guard (missing/incomplete/blocking OQ causes stop + next action guidance).
-- **qfai-prototyping**: Build a contract-aligned implementation skeleton with static-first evidence by default, and escalate to full-harness only when explicitly justified.
+- **qfai-prototyping**: Build a contract-aligned UI prototype under the `full-harness` only / UI-only contract, with calibration-pack SSOT and screen-level Browser QA evidence.
 - **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
 - **qfai-implement**: Unified TDD micro-cycle (Red/Green/Refactor) one test at a time using `test-list.md` as the execution ledger, including ledger status updates and exception closure.
 - **qfai-verify**: Run full-scan local quality gates (`validate --fail-on error`, `report`, repo gates) and produce reviewer-approved evidence under `.qfai/evidence/`.
@@ -189,8 +214,10 @@ 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.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
-- `prototyping.calibration` in `qfai.config.yaml` connects full-harness scoring thresholds to the report and validator.
-- Observability modules (`src/core/observability/`) exist as foundation code but are **not integrated into blocking validation** in v1.7.13. They are reserved for future operational instrumentation.
+- `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 in v1.7.15.
+  Put calibration values in the referenced pack instead of `qfai.config.yaml`.
+- Observability modules (`src/core/observability/`) exist as foundation code but are **not integrated into blocking validation** in v1.7.14. They are reserved for future operational instrumentation.
 
 ## Specifications and contracts (SDD)
 
@@ -266,7 +293,7 @@ Recommended baseline.
 
 Waiver policy.
 
-- Use waivers only for `warning` / `info` findings (false positives, phased migration noise).
+- 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.
 - Suppressed findings remain visible in reports as `suppressed=true`; waivers do not erase findings.

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

@@ -2,12 +2,12 @@
 
 ## Mission
 
-- Implement frontend behavior aligned with selected direction, strategy, screen contracts, and product experience decisions.
+- Implement frontend behavior aligned with selected anchor, strategy, screen contracts, and product experience decisions.
 
 ## Domain Responsibilities
 
 - Build UI components, states, interactions, and user-facing flows.
-- Respect selected direction, strategy, screen contracts, optional design tokens, optional fallback HTML/CSS mock, and screen flow constraints.
+- Respect selected anchor, strategy, screen contracts, optional design tokens, optional fallback HTML/CSS mock, and screen flow constraints.
 - Coordinate with backend changes without breaking surface contracts.
 - Implement with KISS and YAGNI: prefer the simplest component/state structure that satisfies the current contract, and do not add speculative hooks, props, flags, or abstraction layers.
 - Keep UI code cohesive and readable: isolate concerns, minimize hidden coupling, avoid duplication, and use existing patterns/utilities before inventing new ones.

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

@@ -9,7 +9,7 @@
 - Define UX direction, user journeys, interaction patterns, and accessibility expectations.
 - Define visual design direction, tokens, typography, color, and layout hierarchy.
 - Design navigation structures, IA, and screen transition logic.
-- Integrate selected direction, strategy, screen contracts, evaluation sidecars, and Mermaid flow consistency.
+- Integrate selected anchor, strategy, screen contracts, evaluation sidecars, and Mermaid flow consistency.
 - Resolve conflicts between specialist design perspectives as a unified product experience decision.
 - Apply KISS and YAGNI to product-surface design: only add screens, controls, states, and branching flows that are justified by the current user goal.
 - Keep product experience decisions cohesive and unsurprising across copy, IA, navigation, transitions, and visual hierarchy.
@@ -24,7 +24,7 @@
 - .github/instructions/principles.instructions.md
 - .instruction/00_universal/development-principles-checklist.md
 - .instruction/01_specialties/design.md
-- Selected direction, strategy, screen contracts, evaluation sidecars, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
+- Selected anchor, strategy, screen contracts, evaluation sidecars, optional tokens, optional fallback HTML/CSS mock, and Mermaid flows
 - Runtime screenshots or rendered evidence when available
 
 ## Deliverables

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

@@ -9,7 +9,7 @@
 - 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 direction, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
+- Reconcile sidecar artifacts (selected anchor, strategy, screen contracts), design tokens, mermaid flows, and rendered output consistency.
   HTML mock is optional fallback evidence only. Design tokens are supporting input.
 - Review UI changes for KISS and YAGNI at the surface layer: avoid needless states, controls, flows, animations, and configuration that are not justified by the product goal.
 - Check naming, structure, and responsibility split of UI components for clarity, cohesion, and minimal surprise.

package/assets/init/.qfai/assistant/instructions/agent-selection.md

@@ -7,6 +7,8 @@ dependencies:
 version: 2.0.0
 ---
 
+<!-- markdownlint-disable MD041 -->
+
 > **言語指示（厳守）**
 >
 > - 報告・出力: 日本語（Plan も含む）

package/assets/init/.qfai/assistant/instructions/shared-skill-delegation-baseline.md

@@ -0,0 +1,88 @@
+# Shared Skill Delegation Baseline
+
+Use this document to keep SKILL bodies compact.
+Skill files should reference this baseline and only add role-, stage-, or gate-specific rules.
+
+## Sub-agent Delegation (MANDATORY)
+
+### Orchestrator Protocol (MUST)
+
+- The orchestrator may create work orders, delegate tasks, integrate outputs, and present results.
+- The orchestrator must not generate the primary artifact first draft.
+- The orchestrator must not self-approve or act as reviewer for convenience.
+
+### Capability Probe (MUST)
+
+1. Attempt the first required delegation at stage start using the platform's native delegation mechanism.
+2. Treat that first real delegation attempt as the capability check. Do not gate execution on preflight availability questions or synthetic probe-only checks.
+3. If the delegation fails, stop the stage immediately. Do not simulate roles and do not continue with self-execution.
+
+### Delegation Failure (Hard Stop)
+
+- Report all of:
+  - `Delegation failure: <raw reason or concise summary>`
+  - `Attempted role: <role>`
+  - `Attempted task: <task title>`
+  - `Why stopped: QFAI requires real sub-agent delegation in this environment.`
+  - `User action needed: <settings or tooling changes required>`
+  - `Retry condition: rerun after the required delegation succeeds`
+
+## Work Orders Summary
+
+Every major artifact in the stage should include this table schema:
+
+| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
+| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
+| 1    | <role>           | <task>     | <refs>       | <refs>        | PASS/REVISE          |
+
+- `Output (refs)` should point to in-file anchors or relative evidence paths.
+
+## Reviewer Gate Baseline
+
+- Final completion gate must be delegated to an independent reviewer.
+- Reviewers must verify Drift Protocol enforcement.
+- Reviewers must verify test-layer policy enforcement when relevant.
+- Do not treat test volume ratios or floors as hard gates unless the skill explicitly says so.
+- Do not declare DONE until all routed blocking reviewers return `PASS`.
+- Every reviewer returning `FAIL` or `REVISE` must include a concrete fix proposal.
+
+## Work order template
+
+```text
+Task title: <short>
+Role: <sub-agent role>
+Goal: <what to decide/produce>
+Inputs (refs):
+- <file/section>
+Constraints:
+- must: enforce Drift Protocol
+- must: follow applicable test-layer or validation policy
+- must_not: patch upstream artifacts directly when owner rerun is required
+Output format:
+- <headings / bullet schema>
+Quality bar:
+- PASS if ...
+- REVISE if ...
+```
+
+## Reviewer response template
+
+```text
+Result: PASS | REVISE
+Findings:
+- <issue>
+Required fixes:
+- <action>
+Evidence checked:
+- <refs>
+```
+
+### Verdict vocabulary
+
+- Reviewer responses in-flight use `Result: PASS | REVISE` (this file).
+- `summary.json` archived into review packs historically uses
+  `status: "PASS|FAIL"` (validated by
+  `packages/qfai/src/core/validators/reviewArtifacts.ts`).
+- A `REVISE` verdict during iteration maps to `status: "FAIL"` when the
+  final `summary.json` is written; they represent the same outcome.
+  Review packs should not invent a third verdict.

package/assets/init/.qfai/assistant/instructions/shared-skill-operating-baseline.md

@@ -0,0 +1,49 @@
+# Shared Skill Operating Baseline
+
+Use this document to keep SKILL bodies compact.
+Skill files should reference this baseline and only restate skill-specific additions or overrides.
+
+## User Questions (AskUserQuestion Protocol)
+
+- When a question to the user is needed, use AskUserQuestion if the tool is available.
+- When AskUserQuestion supports structured choices, prefer structured choices over free-text input.
+- If AskUserQuestion is unavailable, ask the same question in a normal message with explicit numbered choices.
+- Preserve structured choice semantics when falling back.
+- State why AskUserQuestion was unavailable.
+
+## FORMAT SSOT (Mandatory)
+
+- Before writing or editing `.qfai/**`, read the relevant README/template/sample for the target artifact.
+- Do not copy templates or samples into prompt markdown.
+- Generated artifacts must match README-defined structure, headings, ordering, and table columns.
+- Completion requires a format self-check in evidence.
+
+## Stage 0 - Steering completion refresh (mandatory)
+
+Refresh these files before or during the stage when facts are missing or stale:
+
+- `.qfai/assistant/steering/manifest.md`
+- `.qfai/assistant/steering/product.md`
+- `.qfai/assistant/steering/structure.md`
+- `.qfai/assistant/steering/tech.md`
+
+Rules:
+
+- Detect incomplete content such as empty sections, placeholder-only text, `<...>`, `TBD`, or stale facts.
+- Fill only what is verifiable from repository evidence.
+- If something cannot be verified, record an Open Question and ask the user.
+- Update steering when new facts are discovered during the stage.
+
+## Delta Rejected Guard (Mandatory)
+
+- Do not reintroduce options marked as rejected in `09_delta.md`.
+- If a rejected option must be reconsidered, create a `[RE-OPEN]` decision record that references the prior DR-ID, states what changed, and includes explicit approval.
+
+## Completion Contract (Shared)
+
+Before declaring completion, you MUST:
+
+- resolve or explicitly defer undefined or ambiguous items with rationale;
+- verify every expected artifact exists and required sections are populated;
+- scan generated artifacts for unresolved placeholders such as `TBD`, `TODO`, `TBA`, `TBC`, `XXX`, `???`, `OQ`, `OPEN QUESTION`, `UNDEFINED`, and `PLACEHOLDER`;
+- run the smallest applicable smoke check, or state "not applicable" with a short rationale.

package/assets/init/.qfai/assistant/skills/qfai-atdd/SKILL.md

@@ -30,21 +30,16 @@ QFAI Skill Body (SSOT)
 
 ## User Questions (AskUserQuestion Protocol)
 
-- When a question to the user is needed (e.g., test scope decisions, runtime environment confirmation),
-  the agent MUST use AskUserQuestion if the tool is available.
-- When AskUserQuestion supports structured choices (radio/multi-select),
-  the agent MUST prefer structured choices over free-text input.
-- If AskUserQuestion is technically unavailable, present the same question as a normal message
-  with explicit numbered choices.
-  The agent SHOULD preserve structured choice semantics (enumerated options, selection constraints).
-  The reason for unavailability MUST be stated.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#user-questions-askuserquestion-protocol`.
+
+Skill-specific examples:
+
+- test scope decisions
+- runtime environment confirmation
 
 ## FORMAT SSOT (Mandatory)
 
-- Before writing or editing any `.qfai/**` artifact, read and follow the relevant directory README template and sample.
-- Do not copy templates/samples into this prompt or other prompt markdown.
-- Generated artifacts must match README-defined structure (headings, ordering, table columns).
-- Completion requires a format self-check in evidence.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#format-ssot-mandatory`.
 
 ## Inputs Priority (Preflight)
 
@@ -78,36 +73,26 @@ When unsure, read inputs in this order:
 
 ## Sub-agent Delegation (MANDATORY)
 
-This section is mandatory and overrides any conflicting fallback text in this file.
+Follow `.qfai/assistant/instructions/shared-skill-delegation-baseline.md`.
 
 ### Orchestrator Protocol (MUST)
 
-- Orchestrator may only create work orders, delegate tasks, integrate outputs, and present results.
+- Follow the shared baseline.
+- Orchestrator MUST NOT self-approve.
 - Orchestrator MUST NOT generate the primary artifact first draft.
-- Orchestrator MUST NOT serve as Reviewer or skip delegation for convenience.
 
 ### Capability Probe (MUST)
 
-1. Run one harmless Probe Task (for example: "reply with ok") once at stage start.
-2. If subagents are unavailable, explicitly ask the user for Simulation mode approval.
-3. Without explicit approval, stop the stage and do not continue.
+- No additional overrides.
 
-### Simulation mode (Opt-in only)
+### Delegation Failure (Hard Stop)
 
-- Allowed only when the user explicitly states `Simulation mode allowed`.
-- When used, record both in outputs/evidence:
-  - `Subagents: simulated (reason: <why unavailable>)`
-  - `User approval: <quote or reference>`
+- No additional overrides.
+- Do not simulate roles. If the first required delegation fails, stop the stage and report remediation.
 
 ## Work Orders Summary
 
-Every major artifact in this stage MUST include this fixed table schema:
-
-| Step | Role (sub-agent) | Task title | Input (refs) | Output (refs) | Status (PASS/REVISE) |
-| ---- | ---------------- | ---------- | ------------ | ------------- | -------------------- |
-| 1    | <role>           | <task>     | <refs>       | <refs>        | PASS/REVISE          |
-
-- `Output (refs)` must point to in-file anchors or relative evidence file paths.
+Use the shared schema.
 
 ### Stage Minimum Roles (MUST)
 
@@ -120,77 +105,37 @@ Every major artifact in this stage MUST include this fixed table schema:
 
 ### Reviewer Gate (MUST)
 
+- Follow `.qfai/assistant/instructions/shared-skill-delegation-baseline.md#reviewer-gate-baseline`.
 - Final completion gate MUST be delegated to an independent `completion-reviewer`.
-- Reviewer checks (minimum):
-  - Required roles were delegated (no orchestrator self-authoring).
-  - Drift Protocol enforced (no upstream edits without approval and owner rerun).
-  - Test-layer policy enforced via `test-layers.md`.
-  - Coverage obligations met: E2E covers `US`, Integration covers `TC`, API covers `CON-API`.
-  - **Test-case quality depth verified**: Coverage Depth Matrix reviewed; no unjustified ❌ cells remain (see `references/test-case-depth-checklist.md`).
-  - Validation evidence exists and `qfai validate --fail-on error` passes.
-  - Floors/ratios are signals, not gates.
-  - `scenario.feature` and coverage ledgers are optional legacy inputs, not completion gates.
+- ATDD-specific reviewer checks:
+  - coverage obligations met: E2E covers `US`, Integration covers `TC`, API covers `CON-API`;
+  - Coverage Depth Matrix is reviewed and no unjustified `X` cells remain;
+  - validation evidence exists and `qfai validate --fail-on error` passes;
+  - `scenario.feature` and coverage ledgers remain optional legacy inputs, not completion gates.
 - Route specialist reviewers from `.qfai/assistant/steering/agent-routing.yml`.
 - Default ATDD review set:
   - `completion-reviewer`
   - `qa-gatekeeper`
 - Add `implementation-reviewer` only when helper/runtime support code changed.
 - Do not declare DONE until all routed blocking reviewers return `PASS`.
-- Every reviewer MUST provide a concrete alternative or fix proposal when returning FAIL.
 
 ### Work order template (copy/paste)
 
-```text
-Task title: <short>
-Role: <sub-agent role>
-Goal: <what to decide/produce>
-Inputs (refs):
-- <file/section>
-Constraints:
-- must: enforce Drift Protocol (no upstream edits without user approval + CR)
-- must: verify test-layer obligations from `steering/test-layers.md`
-- must: provide validation evidence (`qfai validate --fail-on error`)
-- must_not: treat volume ratios/floors as hard gates
-- must_not: accept upstream edits made directly by downstream phase
-Output format:
-- <headings / bullet schema>
-Quality bar:
-- PASS if ...
-- REVISE if ...
-```
+Use the shared template.
 
 ### Reviewer response template
 
-```text
-Result: PASS | REVISE
-Findings:
-- <issue>
-Required fixes:
-- <action>
-Evidence checked:
-- <refs>
-```
+Use the shared template.
 
-## Stage 0 — Steering completion refresh (mandatory)
-
-Before moving forward in this stage, refresh:
-
-- `.qfai/assistant/steering/manifest.md`
-- `.qfai/assistant/steering/product.md`
-- `.qfai/assistant/steering/structure.md`
-- `.qfai/assistant/steering/tech.md`
+- Required field: `Status (PASS/REVISE)`.
 
-Rules:
+## Stage 0 — Steering completion refresh (mandatory)
 
-- Detect incomplete content (empty sections, placeholder-only lines, `<...>`, `TBD`, stale facts).
-- Fill what is verifiable from repository evidence.
-- If something cannot be verified, record an Open Question and ask the user.
-- Update steering when new facts are discovered during this stage.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#stage-0---steering-completion-refresh-mandatory`.
 
 ## Delta Rejected Guard (Mandatory)
 
-- Do not reintroduce options marked as rejected in 09_delta.md.
-- If a rejected option must be reconsidered, create a `[RE-OPEN]` Decision Record that references prior DR-ID and explicit approval.
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#delta-rejected-guard-mandatory`.
 
 ## CRITICAL CONSTRAINTS (Read First)
 
@@ -212,12 +157,7 @@ Rules:
 
 ## Completion Contract (Shared)
 
-Before declaring completion, you MUST:
-
-- Resolve or explicitly defer undefined/ambiguous items with rationale.
-- Verify every expected artifact exists and required sections are populated.
-- Scan generated artifacts for unresolved placeholders (`TBD`, `TODO`, `???`, etc.).
-- Run the smallest smoke check proving runnable behavior (or state "not applicable" with rationale).
+Follow `.qfai/assistant/instructions/shared-skill-operating-baseline.md#completion-contract-shared`.
 
 ## Goal