qfai 1.7.9 → 1.7.13

package/assets/init/.qfai/assistant/steering/review-gate.rules.yml

@@ -27,34 +27,16 @@ optional:
     - OpenQuestions
     - Delta
 
+agent_routing:
+  catalog_ssot: .qfai/assistant/steering/agent-catalog.yml
+  routing_ssot: .qfai/assistant/steering/agent-routing.yml
+  review_profiles_ssot: .qfai/assistant/steering/review-profiles.yml
+
 reviewers:
-  minimum: 12
-  roster_ssot: .qfai/assistant/steering/review-roster.yml
+  minimum: 1
   required:
-    - id: qa-lead
-      role: Quality Lead
-    - id: qa-gatekeeper
-      role: QA Gatekeeper
-    - id: reviewer
-      role: Independent Reviewer
-    - id: code-reviewer
-      role: Code Reviewer
-    - id: architect-reviewer
-      role: Architect Reviewer
-    - id: qa-reviewer
-      role: QA Reviewer
-    - id: frontend-reviewer
-      role: Frontend Reviewer
-    - id: backend-reviewer
-      role: Backend Reviewer
-    - id: design-review-lead
-      role: Design Review Lead
-    - id: runtime-gatekeeper
-      role: Runtime Gatekeeper
-    - id: devils-advocate
-      role: Devil's Advocate
-    - id: pattern-doubler
-      role: Pattern Doubler
+    - id: completion-reviewer
+      role: Completion Reviewer
 
 quality_gates:
   validate:
@@ -70,46 +52,15 @@ quality_gates:
     warning_signal:
       - QFAI-COV-207
   defaults:
-    - id: qa-lead
-      role: Quality Lead
+    - id: completion-reviewer
+      role: Completion Reviewer
     - id: qa-gatekeeper
       role: QA Gatekeeper
-    - id: code-reviewer
-      role: Code Reviewer
-    - id: architect-reviewer
-      role: Architect Reviewer
-    - id: qa-reviewer
-      role: QA Reviewer
-    - id: frontend-reviewer
-      role: Frontend Reviewer
-    - id: backend-reviewer
-      role: Backend Reviewer
-    - id: design-review-lead
-      role: Design Review Lead
-    - id: runtime-gatekeeper
-      role: Runtime Gatekeeper
-    - id: devils-advocate
-      role: Devil's Advocate
-    - id: pattern-doubler
-      role: Pattern Doubler
+    - id: implementation-reviewer
+      role: Implementation Reviewer
 
-extended_reviewers:
-  devils-advocate:
-    execution_order: 11
-    can_be_na: false
-    fail_rules:
-      - alternative_required: true
-      - bare_negation_invalid: true
-    escalation:
-      consecutive_fail_limit: 3
-      action: advisory_demotion
-      scope: current_review_cycle
-      effect: non_blocking_feedback_only
-  pattern-doubler:
-    execution_order: 12
-    can_be_na: true
-    na_rule: "Allowed only if target artifact has no ID-bearing spec items (US/AC/BR/EX/TC)."
-    fail_rules:
-      - rationale_required: true
-      - count_target: "2x current ID-bearing items"
-      - count_scope: "US, AC, BR, EX, TC prefixed sequential IDs only"
+optional_review_modes:
+  review_profiles_ssot: .qfai/assistant/steering/review-profiles.yml
+  supported:
+    - devils-advocate
+    - pattern-doubler

package/assets/init/.qfai/assistant/steering/review-profiles.yml

@@ -0,0 +1,30 @@
+schema_version: "1.0"
+
+profiles:
+  default:
+    always_required: [completion-reviewer]
+    conditional_required: []
+  requirements-heavy:
+    always_required: [completion-reviewer, requirements-reviewer]
+    conditional_required: []
+  architecture-heavy:
+    always_required: [completion-reviewer, architecture-reviewer]
+    conditional_required: []
+  ui-bearing:
+    always_required: [completion-reviewer, product-surface-reviewer]
+    conditional_required: []
+  runtime-heavy:
+    always_required: [completion-reviewer, qa-gatekeeper]
+    conditional_required: [implementation-reviewer]
+
+optional_modes:
+  devils-advocate:
+    kind: advisory
+    description: Challenge assumptions aggressively, but do not block completion by default.
+    alternative_required: true
+    bare_negation_invalid: true
+  pattern-doubler:
+    kind: advisory
+    description: Demand additional ID-bearing patterns with rationale when pattern coverage is thin.
+    rationale_required: true
+    default_target: "2x current ID-bearing items"

package/assets/init/.qfai/assistant/steering/structure.md

@@ -2,33 +2,47 @@
 
 ## Repo layout (high level)
 
-- Top-level directories:
-- Evidence:
+- Top-level directories: packages/, .qfai/, docs/, scripts/, tmp/, .github/, .claude/, .codex/, .agents/
+- Evidence: Repository root listing
 
 ## Key packages / entrypoints
 
-- Package(s) of interest:
-- CLI entry:
-- Core modules:
-- Evidence:
+- Package(s) of interest: packages/qfai/ (monorepo single package)
+- CLI entry: packages/qfai/src/cli/index.ts -> main.ts (run() with switch on command)
+- Core modules: packages/qfai/src/core/ (40+ files: config, discovery, specLayout, discussionPack, traceability, contracts, waivers, validate, etc.)
+- Evidence: packages/qfai/package.json, packages/qfai/src/
 
 ## Architecture constraints
 
 - Boundaries (what must not depend on what):
+  - Validators are pure async functions returning Issue[] (no side effects)
+  - CLI layer -> Core layer -> Validators -> Artifacts (one-way dependency)
+  - specs/ is definition-only (no operational status)
 - Conventions (naming, file layout):
-- Evidence:
+  - Layered spec: `_policies/` + `spec-XXXX/` (1 CAP = 1 spec dir)
+  - Contract IDs: CON-DB-XXXX, CON-API-XXXX, CON-UI-XXXX
+  - Validator files: packages/qfai/src/core/validators/ (45+ files)
+- Evidence: 02_Inception-Deck.md (Architecture), 09_Constraints.md (TC-09)
 
 ## Quality gates (SSOT)
 
-- format:
-- lint:
-- typecheck:
-- test:
-- verify-pack / pack:
-- Evidence:
+- format: prettier (.prettierrc.json)
+- lint: eslint (eslint.config.js)
+- typecheck: pnpm check-types (tsc --noEmit)
+- test: pnpm test (vitest run)
+- verify-pack / pack: scripts/verify-pack.mjs
+- Evidence: packages/qfai/package.json (scripts), .prettierrc.json, eslint.config.js
 
 ## How to run locally
 
-Provide copy-paste commands and expected outputs.
-
-- Evidence:
+```bash
+pnpm install
+pnpm build          # tsup build
+pnpm test           # vitest run
+pnpm check-types    # tsc --noEmit
+pnpm lint           # eslint src
+npx qfai validate   # run validation
+npx qfai doctor     # diagnose setup
+```
+
+- Evidence: packages/qfai/package.json (scripts)

package/assets/init/.qfai/assistant/steering/tech.md

@@ -2,36 +2,52 @@
 
 ## Runtime / platform
 
-- Node:
-- Evidence:
-- OS assumptions:
-- Evidence:
-- CI environment:
-- Evidence:
+- Node: >= 18.0.0 (package.json engines)
+- Evidence: packages/qfai/package.json
+- OS assumptions: cross-platform (Windows, macOS, Linux)
+- Evidence: fast-glob abstraction, path normalization in core/paths.ts
+- CI environment: GitHub Actions
+- Evidence: .github/ directory
 
 ## Package manager
 
-- pnpm / npm / yarn:
-- Evidence:
+- pnpm >= 9.12.3 (monorepo workspace)
+- Evidence: pnpm-workspace.yaml, pnpm-lock.yaml
 
 ## Language / framework
 
-- TypeScript:
-- Build tool:
-- Test runner:
-- Lint / format:
-- Evidence:
+- TypeScript: 5.6.3 (strict mode)
+- Build tool: tsup 8.3.5 (ESM/CJS dual build)
+- Test runner: vitest 2.1.8
+- Lint / format: eslint + prettier + markdownlint-cli2
+- Evidence: packages/qfai/package.json (devDependencies), tsconfig.base.json
+
+## Dependencies (runtime)
+
+- @cucumber/gherkin ^37.0.1 (Gherkin parse)
+- @cucumber/messages ^31.1.0 (Gherkin AST)
+- fast-glob ^3.3.2 (file discovery, 10k limit)
+- jsdom ^26.1.0 (DOM crawling for UI fidelity)
+- yaml ^2.5.1 (YAML 1.2 parse)
+- Evidence: packages/qfai/package.json (dependencies)
 
 ## Constraints
 
--
-- Evidence:
+- Validators are pure async functions (no side effects, return Issue[])
+- File search limit: 10,000 files (fast-glob)
+- CI/CD: 2 minutes timeout target
+- validate.json: internal contract (not stable API, per OQ-0003)
+- Optional browser tooling for render evidence must remain lazy and must not become a new runtime dependency in v1.7.1.
+- v1.7.5 backend provider abstraction uses optional registration; no new universal runtime dependencies. Browser/visual-review backends are registered optionally; future capability-based loading is deferred.
+- Evidence: 09_Constraints.md (TC-09, TC-10, OC-01, OC-02)
 
 ## Standard commands (copy-paste)
 
-- Install:
-- Test:
-- Lint:
-- Typecheck:
-- Pack/verify:
-- Evidence:
+- Install: `pnpm install`
+- Test: `pnpm test`
+- Lint: `pnpm lint`
+- Typecheck: `pnpm check-types`
+- Pack/verify: `node scripts/verify-pack.mjs`
+- Build: `pnpm build`
+- Validate: `npx qfai validate --fail-on error --format github`
+- Evidence: packages/qfai/package.json

package/assets/init/.qfai/assistant/steering/ui-definition-protocol.md

@@ -0,0 +1,54 @@
+# UI Definition Consumption Protocol
+
+spec-0013 (CAP-0013) で定義された、下流 skill（prototyping / ATDD / TDD）が UI 定義を読み取る際の手順。
+
+## Reading Order
+
+下流 skill は以下の順序で UI 定義を読み取る。
+**Primary truth** は step 1 の discussion sidecar artifacts にある。step 2 以降は **存在する場合のみ読む supporting input / fallback** であり、init 直後に未作成でも正常である。
+
+1. **Discussion-side UI/UX Sidecar Artifacts** (`discussion-*/uiux/`) — **primary source of truth**
+   - `30_option_comparison.md` — オプション比較（比較 artifact）
+   - `31_selected_anchor_screen.md` — 選定結果 + selected direction の SSOT
+   - `10_implementation_strategy.md` — 実装戦略（strict canonical schema）
+   - `11_design_taste_interview.md` — デザインテイストインタビュー
+   - `20-24` — 3-layer 評価ファミリー（invariant / trend-derived / product-specific / aggregate / dynamic overrides）
+   - `40_screen_contracts.md` — スクリーンコントラクト（strong schema）
+   - `50_review_input_bundle.md` — レビュー入力バンドル
+
+2. **UI Contracts / Route-level Obligations** (`.qfai/contracts/ui/*.yaml`) — **supporting input; read only if present**
+   - 画面定義、インタラクション仕様
+   - Design Token ID への参照を含む
+   - init 直後にファイルが存在しなくても異常ではない
+
+3. **Design Token** (`.qfai/contracts/design/design-tokens*.yaml`) — **supporting input; read only if present**
+   - カラー、スペーシング、タイポグラフィ等の基盤値
+   - primitive → semantic → component の 3 層参照解決
+   - init 直後にファイルが存在しなくても異常ではない
+
+4. **Optional Fallback Visual Mock** (spec/discussion 内の Screen Mock セクション) — **fallback; read only if present**
+   - HTML+CSS mock は補助的な視覚的フォールバックとしてのみ使用
+   - sidecar artifacts と contracts が主要な UI 定義ソース
+   - mock が存在する場合のみ参照し、欠落していても問題なし
+
+5. **Mermaid Screen Flow** (spec/discussion 内の mermaid フェンス) — **supporting; read only if present**
+   - 画面遷移図（stateDiagram-v2）
+   - ナビゲーション構造図（flowchart）
+
+## Fallback Rules
+
+| Missing Definition     | Behavior                                       |
+| ---------------------- | ---------------------------------------------- |
+| Design Token のみ欠落  | warning 発行、CSS fallback 値を使用して継続    |
+| UI Contract のみ欠落   | warning 発行、sidecar artifacts から構造を推論 |
+| Sidecar artifacts 欠落 | warning 発行、UI Contract からの推論で継続     |
+| Fallback mock 欠落     | no-op — mock は必須ではない                    |
+| 全定義が欠落           | 現実装では no-op（issues なし）で終了          |
+
+## Priority and Override Semantics
+
+- sidecar artifacts（selected direction / strategy / contracts）が **primary truth**
+- UI Contracts と Design Token は **存在する場合のみ読む supporting input**（primary truth ではない）
+- Optional fallback mock はさらに後順位の **fallback**
+- Design Token の値と HTML Mock の fallback 値が矛盾する場合は warning を発行
+- UI Contract の screen ID と sidecar contracts の対応がない場合は warning を発行

package/assets/init/.qfai/contracts/README.md

@@ -5,15 +5,18 @@
 Contracts define the **stable surface** that specs and tests may reference.
 They are the boundary between "what we promise" and "how we implement".
 
-QFAI organizes contracts into three types:
+QFAI organizes contracts into four directories:
 
 ```text
 contracts/
-├── api/   # OpenAPI YAML (endpoints, request/response)
-├── db/    # SQL schema contracts (tables, columns, constraints)
-└── ui/    # UI contract YAML (screens, elements, user actions)
+├── api/      # OpenAPI YAML (endpoints, request/response)
+├── db/       # SQL schema contracts (tables, columns, constraints)
+├── design/   # Design token YAML — optional supporting input
+└── ui/       # UI contract YAML (screens, elements, user actions)
 ```
 
+> **Note:** `ui/` and `design/` are **supporting input** that supplements the discussion sidecar artifacts (`discussion-*/uiux/*`), which remain the primary truth. After `qfai init`, these directories may contain only placeholder READMEs — this is the normal initial state.
+
 ## Directory rules
 
 - Contract files are **minimal**: only what specs actually need.
@@ -29,6 +32,9 @@ contracts/
 ├── db/
 │   ├── README.md
 │   └── db-0001-<slug>.sql
+├── design/
+│   ├── README.md
+│   └── design-tokens.yaml          (created when needed)
 └── ui/
     ├── README.md
     └── ui-0001-<slug>.yaml

package/assets/init/.qfai/contracts/design/README.md

@@ -0,0 +1,32 @@
+# contracts/design (Design Token YAML) — Optional Supporting Input
+
+## Purpose
+
+Provide a designated location for design token files (`design-tokens*.yaml`) that serve as **optional supporting input** for UI review, validation, and implementation.
+
+**Primary truth** for UI/UX definitions resides in the discussion sidecar artifacts (`discussion-*/uiux/*`). Design token files in this directory supplement — but never override — those primary artifacts.
+
+## Status After Init
+
+After `qfai init`, this directory contains only this README. This is the normal initial state. Design token files are created later when the project needs explicit token definitions.
+
+The absence of design token files is **not** a defect and does not affect the canonical discussion or contracts flow.
+
+## When Design Tokens Are Used
+
+Design token files are consumed **only when they exist**:
+
+- `qfai validate` runs token-level checks (schema, circular references, platform coverage) if token files are present
+- `ui-definition-protocol.md` read-order includes this path as a conditional step
+- Prototyping and review skills reference tokens as supplementary color/spacing/typography values
+
+## Expected File Names
+
+- `design-tokens.yaml` — primary token definitions (primitive → semantic → component)
+- `design-tokens.mobile.yaml` — mobile-specific overrides (optional)
+
+## What This Directory Is NOT
+
+- **Not** the primary truth for screen layout or component hierarchy
+- **Not** a required baseline for discussion or spec authoring
+- **Not** a substitute for sidecar artifacts or UI contracts

package/assets/init/.qfai/contracts/ui/README.md

@@ -2,9 +2,11 @@
 
 ## Purpose
 
-Define UI surface contracts as SSOT for prototyping and E2E selection.
+Define UI surface contracts for prototyping and E2E selection.
 The contract must describe both screen structure and minimum mockable behavior.
 
+> **Note:** UI contracts are **supporting input** that supplements the discussion sidecar artifacts (`discussion-*/uiux/*`), which remain the primary truth for UI/UX definitions. Screen contract YAML files are read **only when present**; after `qfai init`, this directory may contain only this README — that is the normal initial state.
+
 ## File rules
 
 - File name: `ui-XXXX-<slug>.yaml`
@@ -130,7 +132,7 @@ screens:
 
 ### Q1. "The page is just a static string." Which rule fails?
 
-- Typical fail: `QFAI-PROT-232` (`prototypingEvidence.uiFidelityContractCoverage`).
+- Typical fail: `QFAI-PROT-238` (`prototypingEvidence.uiFidelityContractCoverage`).
 - Reason: Contract expects `elements/actions`, but runtime evidence does not satisfy expected placement/wiring.
 - Fix:
   - Add concrete UI elements for contract labels, or
@@ -142,7 +144,7 @@ screens:
   1. Contract label (`contracts/ui/*.yaml`)
   2. UI rendered text (or marker mapping)
   3. Prototyping evidence (`.qfai/evidence/prototyping.json`)
-- If only one side is updated, `QFAI-PROT-232` can remain unresolved in review.
+- If only one side is updated, `QFAI-PROT-238` can remain unresolved in review.
 
 ### Q3. "Can I treat this as a static screen?"
 

package/assets/init/.qfai/discussion/README.md

@@ -2,10 +2,12 @@
 
 ## Purpose
 
-`discussion/` stores the unified discussion pack that merges interview outputs (discuss) and requirement intake (require) into a single fixed 15-file structure.
+`discussion/` stores the unified discussion pack that merges interview outputs (discuss) and requirement intake (require). Discussion packs use 15 required markdown files plus required prototyping.yaml.
 
 This directory does not directly update `specs/`; it prepares decisions, requirements, open questions, and rationale as inputs for `/qfai-sdd`.
 
+Generated discussion packs (`discussion-YYYYMMDDhhmmssSSS/`) are not version-controlled by default. Only `README.md` is tracked in Git. Ignore rules are managed in the project root `.gitignore` by `qfai init`. Historic discussion packs that were previously committed should be referenced via Git history only.
+
 ## Required structure
 
 ```text
@@ -26,7 +28,8 @@ discussion/
     ├── 12_OQ-Resolution-Log.md
     ├── 13_Deferred.md
     ├── 14_Review-Request.md
-    └── 99_delta.md
+    ├── 99_delta.md
+    └── prototyping.yaml
 ```
 
 ## File responsibilities
@@ -55,7 +58,7 @@ discussion/
 | ------------------- | ---------------------------------------------------- |
 | OQ-ID               | `OQ-0001` format                                     |
 | Title               | Short descriptive title                              |
-| Gate                | `discuss`, `require`, or `sdd`                       |
+| Gate                | `discussion`, `sdd`, `atdd`, `tdd`, or `ops`         |
 | Disposition         | `open`, `resolved`, `deferred`, or `rejected`        |
 | Owner               | `user`, `agent`, or `team`                           |
 | Rationale           | Required for `deferred` and `rejected`               |
@@ -76,7 +79,7 @@ discussion/
 | --------------- | -------------------------------------------------- |
 | OQ-ID           | `OQ-0001` format                                   |
 | Title           | Short descriptive title                            |
-| Gate            | `discuss`, `require`, or `sdd`                     |
+| Gate            | `discussion`, `sdd`, `atdd`, `tdd`, or `ops`       |
 | Deferred-Reason | Why deferral is justified                          |
 | Deferred-Until  | Milestone, date, or trigger                        |
 | Owner           | `user`, `agent`, or `team`                         |
@@ -88,6 +91,7 @@ discussion/
 
 - Every deferred item must have all columns populated.
 - `Deferred-Until` must define when and by what signal re-evaluation happens.
+- If there are no deferred items, keep the table header and add a single `0 items` row instead of replacing the section with plain text.
 
 ## Rules
 
@@ -97,7 +101,50 @@ discussion/
 - `03_Story-Workshop.md` must include at least one Mermaid diagram in ` ```mermaid ` fences.
 - If diagrams are written elsewhere, use ` ```mermaid ` fences only (do not use ` ```text ` or language-less fences).
 - Use timestamp directory naming for new outputs: `discussion-YYYYMMDDhhmmssSSS`.
-- `14_Review-Request.md` must reference roster SSOT: `.qfai/assistant/steering/review-roster.yml`.
+- `14_Review-Request.md` must reference routing SSOT: `.qfai/assistant/steering/agent-routing.yml` and `.qfai/assistant/steering/review-profiles.yml`.
+
+## prototyping.yaml (Required Recommendation Artifact)
+
+Each discussion pack **must** include a `prototyping.yaml` file that recommends the prototyping mode for the project. This is a required side artifact of the 15-file discussion pack plus required prototyping.yaml completion contract.
+
+### Canonical namespaced schema (recommended)
+
+```yaml
+prototyping:
+  recommended_mode: standard
+  rationale: UI validation is recommended but full-harness is not justified by default.
+  allowed_modes:
+    - low-cost
+    - standard
+    - full-harness
+  surface: web-ui
+```
+
+### Legacy top-level schema (deprecated — read-only backward compatibility)
+
+The following top-level form is accepted by the parser for backward compatibility but produces a deprecation warning (`QFAI-PROT-231`). New artifacts MUST NOT emit this form; use the namespaced canonical schema above.
+
+```yaml
+recommended_mode: standard
+rationale: ...
+allowed_modes:
+  - low-cost
+  - standard
+surface: web-ui
+```
+
+If both forms are present in the same file, the namespaced form takes precedence and a conflict warning (`QFAI-PROT-232`) is emitted.
+
+### Field reference
+
+All 4 fields are **required**. An artifact missing any field will fail validation.
+
+| Field              | Required | Description                                                  |
+| ------------------ | -------- | ------------------------------------------------------------ |
+| `recommended_mode` | yes      | `low-cost`, `standard`, or `full-harness`                    |
+| `rationale`        | yes      | Non-empty string explaining the recommendation               |
+| `allowed_modes`    | yes      | Unique array of valid modes; must include `recommended_mode` |
+| `surface`          | yes      | `web-ui`, `mobile-ui`, `desktop-ui`, `mixed`, or `non-ui`    |
 
 ## Suggested naming