qfai 1.7.8 → 1.7.13

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

@@ -2,90 +2,172 @@
 
 ## Purpose
 
-Evidence files record **what was actually executed** for each custom prompt run:
+Evidence files record what was actually executed, observed, skipped, or deferred.
 
-- commands executed
-- relevant logs (summary)
-- gaps / exceptions
-- reviewer approval
+## Prototyping stage required artifacts
 
-## Version control policy
+`/qfai-prototyping` uses these canonical files:
 
-Evidence is **not versioned by default**.
-Recommended approach:
+- `.qfai/evidence/prototyping.md`
+- `.qfai/evidence/prototyping.json`
+- `.qfai/evidence/render.json` (when render evidence is emitted)
+- `.qfai/evidence/browser-qa.json` (when browser QA is emitted)
 
-- Add `.qfai/evidence/` to `.gitignore` (project-level), OR
-- Add it to `.git/info/exclude` (local only), OR
-- Store evidence outside the repository (artifact store, issue attachments).
+## prototyping.json minimum schema
 
-## Naming
+Always required:
 
-- Summary file: `.qfai/evidence/<prompt>-<run-id>.md`
-- Optional artifacts: `.qfai/evidence/<prompt>/<YYYY-MM-DD>/<run-id>/...`
-- `<run-id>`: prefer `spec-XXXX` when applicable.
+- `specs[]`
+- `meta.generatedAt`
+- `meta.toolVersion`
+- `meta.commands[]`
+- `mode.effective`
+- `mode.source`
+- `mode.rationale`
 
-### Prototyping stage required evidence
+Optional:
 
-`/qfai-prototyping` requires two evidence artifacts in the evidence directory:
+- `surface`
+- `mode.requested`
+- `mode.discussionRecommendation`
+- `runtimeGate`
+- `uiFidelity`
+- `renderEvidence`
+- `browserQa`
+- `fullHarness`
 
-- one markdown evidence file for human-readable coverage/runtime logs
-- one json evidence file for machine validation
+## Obligation matrix
 
-### Prototyping JSON minimum + uiFidelity mode rule
+| surface / mode            | specs    | runtimeGate | uiFidelity                    | render evidence | browser QA | fullHarness |
+| ------------------------- | -------- | ----------- | ----------------------------- | --------------- | ---------- | ----------- |
+| non-ui / low-cost         | required | optional    | n/a                           | n/a             | n/a        | absent      |
+| non-ui / standard         | required | optional    | n/a                           | n/a             | n/a        | absent      |
+| non-ui / full-harness     | required | optional    | n/a                           | n/a             | n/a        | required    |
+| ui-bearing / low-cost     | required | optional    | optional (`skeleton` allowed) | optional        | optional   | absent      |
+| ui-bearing / standard     | required | optional    | required                      | optional        | optional   | absent      |
+| ui-bearing / full-harness | required | required    | required                      | required        | required   | required    |
 
-`prototyping.json` keeps the existing minimum schema for validation:
+Interpretation:
 
-- `specs[]`
-- `runtimeGate.ui[]`
-- `runtimeGate.api[]`
-- `meta.generatedAt`
-- `meta.toolVersion`
-- `meta.commands[]`
+- `required`: schema and completeness are enforced
+- `optional`: if present, schema must be valid
+- `n/a`: absent is normal success
+
+## non-ui canonical semantics
+
+For `surface: non-ui`, the following are normal success when absent:
 
-`uiFidelity` handling depends on `mode`:
+- `uiFidelity`
+- render evidence bundle
+- browser QA bundle
+- `runtimeGate.ui`
 
-- `mode: interactive` (default): `uiFidelity` is required.
-- `mode: skeleton`: keep `uiFidelity` with `screens: []` for L1 evidence.
+Contradictory UI-only payloads on `non-ui` are validation errors.
 
-When `uiFidelity` is present, keep all minimum fields above.
+## uiFidelity notes
 
-### Render evidence bundle conventions
+- `uiFidelity` is the canonical UI evidence block.
+- `mode: interactive` is the default when a working UI flow is exercised.
+- `mode: skeleton` is allowed for low-cost UI proof where structure exists but wiring is intentionally partial.
+- Keep `"version": "0.1"` in the `uiFidelity` payload until the schema version changes.
 
-When render capture is enabled, keep render metadata path-only and store artifacts on disk:
+## fullHarness minimum completeness
 
-- default bundle path: `.qfai/evidence/render.json`
-- default viewports: `desktop`, `mobile`
-- `uiFidelity.screens[].renders[]` is the normalized in-band source for validator/report use
-- captured entries require `imagePath` and `htmlPath`
-- skipped entries require `skippedReason`
-- failed entries require `error`
+When `mode.effective = "full-harness"`:
 
-Degraded mode is allowed:
+- `fullHarness.enabled = true`
+- `fullHarness.available`
+- `fullHarness.runId`
+- `fullHarness.iterationCount >= 1`
+- `fullHarness.bestIteration >= 1`
+- `fullHarness.terminationReason`
+- `fullHarness.reviewerSignoff`
+- `fullHarness.scoringTrace.length >= 1`
 
-- if renderer setup is unavailable, record `status: "skipped"` with a concrete reason
-- do not inline screenshot bytes or HTML bodies into JSON
-- keep `prototyping.json` and `render.json` aligned by file path only
+## Render evidence bundle conventions
+
+Canonical path: `.qfai/evidence/render.json`
 
 ```json
 {
   "renderEvidence": {
-    "status": "skipped",
+    "status": "captured",
     "requested": true,
-    "autogenEnabled": false,
     "viewports": ["desktop", "mobile"],
-    "outputPath": ".qfai/evidence/render.json",
-    "reason": "render requested without autogen-ui-fidelity"
-  }
+    "outputPath": ".qfai/evidence/render.json"
+  },
+  "screens": [
+    {
+      "route": "/orders",
+      "viewport": "desktop",
+      "status": "captured",
+      "width": 1440,
+      "height": 900,
+      "imagePath": ".qfai/evidence/render/orders.desktop.png",
+      "htmlPath": ".qfai/evidence/render/orders.desktop.html"
+    },
+    {
+      "route": "/orders",
+      "viewport": "mobile",
+      "status": "skipped",
+      "skippedReason": "path-only review for non-blocking mobile check"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `status`: `captured | skipped | failed`
+- `captured`: `imagePath` and `htmlPath` required (QFAI-PROT-252)
+- `skipped`: `skippedReason` required (QFAI-PROT-252)
+- `failed`: `error` required (QFAI-PROT-252)
+- external bundle is the source of truth
+- in-band `uiFidelity.screens[].renders[]` is summary/projection only
+- render evidence must remain `path-only`; `data:` URIs, `base64,` payloads, and inline HTML are invalid (QFAI-PROT-251)
+- extremely long single-line payloads (>500 chars) are treated as inline payload violations
+- top-level `renderEvidence.status` and individual `screens[].status` must not contradict (QFAI-PROT-253)
+
+## browser-qa.json canonical contract
+
+```json
+{
+  "browserQa": {
+    "executed": true,
+    "status": "completed",
+    "mode": "full-harness",
+    "summary": {
+      "smoke": { "passed": 3, "failed": 0 },
+      "interaction": { "passed": 4, "failed": 1 }
+    }
+  },
+  "findings": [
+    {
+      "category": "interaction",
+      "severity": "error",
+      "route": "/orders",
+      "message": "Save button submits duplicate request"
+    }
+  ]
 }
 ```
 
-Good example references:
+Rules:
 
-- Repository docs sample: `docs/examples/prototyping-ui-fidelity.good.json`
-- UI contract pair sample: `docs/examples/ui-contract.good.yaml`
+- required only for `ui-bearing / full-harness` (QFAI-PROT-263)
+- optional for `ui-bearing / low-cost|standard`
+- n/a for `non-ui`
+- `executed=true` requires `status=completed`; `executed=false` permits `status=skipped|failed` only
+- `status=completed` without `summary` or `findings` produces a warning (QFAI-PROT-262)
+- `browserQa.mode` must match `prototyping.json.mode.effective` (QFAI-PROT-261)
+- `summary.*.passed/failed` must be non-negative integers
+- each finding requires `category`, `severity`, and `message`
+
+## Example prototyping.json
 
 ```json
 {
+  "surface": "web-ui",
   "specs": [
     {
       "specId": "spec-0001",
@@ -94,75 +176,20 @@ Good example references:
       "missing": { "uiRoutes": [], "apiEndpoints": [], "dbObjects": [] }
     }
   ],
-  "runtimeGate": {
-    "ui": [{ "route": "/orders", "status": 200 }],
-    "api": [{ "method": "GET", "path": "/api/orders", "status": 200 }]
-  },
-  "uiFidelity": {
-    "version": "0.1",
-    "mode": "interactive",
-    "screens": [
-      {
-        "route": "/orders",
-        "uiContractId": "CON-UI-0001",
-        "expected": { "elements": 6, "actions": 2 },
-        "observed": {
-          "elementsPlaced": 6,
-          "actionsWired": 2,
-          "markersEmitted": 5
-        },
-        "mockPaths": [
-          {
-            "id": "mp_create_to_list",
-            "status": "pass",
-            "notes": "create -> list reflects (client mock)"
-          }
-        ],
-        "placeholders": { "hasPlaceholderText": false, "notes": "" }
-      }
-    ]
+  "mode": {
+    "effective": "standard",
+    "source": "default",
+    "rationale": "No explicit request or discussion recommendation was provided."
   },
   "meta": {
-    "generatedAt": "2026-02-27T00:00:00.000Z",
+    "generatedAt": "2026-04-04T00:00:00.000Z",
     "toolVersion": "<current-tool-version>",
     "commands": ["qfai validate --fail-on error"]
+  },
+  "uiFidelity": {
+    "version": "0.1",
+    "mode": "interactive",
+    "screens": []
   }
 }
 ```
-
-## Minimal content template
-
-```md
-# Evidence: <prompt> (<run-id>)
-
-## Scope
-
-- Spec: <SPEC-XXXX or none>
-- Branch: <name>
-- Commit: <hash>
-
-## Commands executed
-
-- <cmd1>
-- <cmd2>
-
-## Results summary
-
-- <what passed / what failed>
-
-## Exceptions / gaps
-
-- <explicit gaps>
-
-## Reviewer approval
-
-- Reviewer: <name/role>
-- Approved at: <YYYY-MM-DD>
-```
-
-## Checklist
-
-- [ ] Contains executed commands and outcomes.
-- [ ] Notes any intentional gaps.
-- [ ] Has non-author approval (when required by prompt).
-- [ ] Prototyping stage includes both markdown and json evidence files.

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

@@ -23,4 +23,4 @@ These artifacts are reporting outputs, not SSOT.
 - Keep this directory as report-only output.
 - Do not move requirement/spec SSOT into this directory.
 - If `preflight_summary.md` exists, treat it as review-exempt context for the next SDD step.
-- Keep `.gitignore` as a baseline and append generated logs/artifacts over time.
+- Keep `.gitignore` entries in the project root (managed by `qfai init`) to exclude generated artifacts.

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

@@ -10,15 +10,16 @@ Each review pack must include:
 - `Rxx_<reviewer>.md` (1 file or more)
 - `summary.json`
 
-Roster SSOT:
+Routing SSOT:
 
-- `.qfai/assistant/steering/review-roster.yml`
+- `.qfai/assistant/steering/agent-routing.yml`
+- `.qfai/assistant/steering/review-profiles.yml`
 
 ## Path format
 
 ```text
 .qfai/review/
-├── .gitignore
+├── README.md
 └── review-YYYYMMDDhhmmssSSS/
     ├── review_request.md
     ├── R01_<reviewer>.md
@@ -30,20 +31,34 @@ Roster SSOT:
 
 ```json
 {
-  "version": "1.0",
+  "version": "2.0",
   "created_at": "2026-02-18T12:34:56+09:00",
   "target": { "kind": "spec|require|discussion", "path": "..." },
-  "roster": [{ "reviewer": "name-or-id", "status": "PASS|FAIL|N/A", "feedback_count": 0 }],
+  "routing_profile": "default",
+  "reviewers": [{ "reviewer": "name-or-id", "status": "PASS|FAIL", "feedback_count": 0 }],
+  "conditional_reviewers": [],
   "overall_status": "PASS|FAIL"
 }
 ```
 
 Rules:
 
-- Execute all reviewers from roster in order for each review cycle.
-- `N/A` is allowed only with an explicit reason following roster `na_rule`.
-- If any reviewer returns `FAIL`, return/fix and rerun full roster review.
-- Validate evidence must include latest `.qfai/report/validate.log` and ATDD traceability report (`.qfai/report/atdd-traceability/summary.{json,md}`).
+- Execute only the reviewers routed for the current skill/phase.
+- If any reviewer returns `FAIL`, return/fix and rerun only failed reviewers and reviewers **affected by the changed scope**.
+  - "changed scope" is defined as the set of file paths affected by the latest fix and the scope tags (component, domain, layer, etc.) associated with those files.
+  - An "affected reviewer" is any reviewer matching either of the following:
+    - Its assigned scope (path prefix or scope tag) in `.qfai/assistant/steering/agent-routing.yml` or `review-profiles.yml` intersects the changed scope.
+    - Its routing definition (scope, weight, enabled/disabled) was modified in the diff of the above two files.
+  - Procedure for determining rerun targets:
+    1. List all added/modified/deleted file paths from the latest change diff.
+    2. Resolve the corresponding scope tags, components, and domains via `agent-routing.yml` / `review-profiles.yml` to enumerate the changed scope.
+    3. For each reviewer, check whether its assigned scope intersects the changed scope or whether its routing definition was modified; mark matching reviewers as "affected".
+    4. Rerun only "previously FAIL reviewers" + "affected reviewers"; carry forward previous results for all others.
+- Validation evidence for each review pack must archive the latest
+  `.qfai/report/validate.log` and ATDD traceability report
+  (`.qfai/report/atdd-traceability/summary.{json,md}`) by copying them from
+  `.qfai/report` into the corresponding `review-*/evidence/` directory
+  (since `.qfai/report` may be git-ignored).
 - Reviewers must confirm no unresolved ATDD hard gates (`QFAI-ATDD-101/102/103/111/112/113/121/122`).
 
 ## Prototyping review quick checklist

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

@@ -7,7 +7,8 @@
 - upper-layer policies and decision bases: `.qfai/specs/_policies/**`
 - capability-specific details: `.qfai/specs/spec-XXXX/**`
 
-The split policy is fixed: **1 CAP = 1 spec directory**.
+The slice policy SSOT lives in `_policies/11_Slice-Policy.md`.
+The current approved model is **1 CAP = 1 spec directory**, but `/qfai-sdd` must refresh that policy file before making create/update/delete slice decisions.
 
 ## Required layout
 
@@ -23,7 +24,8 @@ specs/
 │   ├── 07_Constraints.md
 │   ├── 08_Decisions.md
 │   ├── 09_Open-questions.md
-│   └── 10_delta.md
+│   ├── 10_delta.md
+│   └── 11_Slice-Policy.md
 └── spec-XXXX/
     ├── 01_Spec.md
     ├── 02_User-stories.md
@@ -84,6 +86,7 @@ Each `spec-XXXX/tdd/test-list.md` is the execution ledger for the TDD micro-cycl
 - `specs/` is definition-only. Keep operational status as run logs under `.qfai/report/run-*/`.
 - Do not keep state markers like `release_candidate`, `Status`, `Progress`, or runtime `Risk` sections in spec files.
 - `/qfai-sdd` requires a complete `discussion/discussion-*/` pack and stops if it is missing or incomplete.
+- `/qfai-sdd` must create or refresh `_policies/11_Slice-Policy.md` before deciding whether repository changes require spec CREATE / UPDATE / DELETE.
 - Blocking OQ in `discussion-*/11_OQ-Register.md` (`Disposition: open`) must be resolved before SDD proceeds.
 - Preflight writes `.qfai/report/preflight_summary.md` before spec generation to record selected inputs and open gaps.
 - `_policies/04_Business-Flow.md` must include at least one ` ```mermaid ` block and at least one `flowchart` or `sequenceDiagram`.

package/assets/init/root/qfai.config.yaml

@@ -30,3 +30,16 @@ validation:
     unknownContractIdSeverity: error
 output:
   validateJsonPath: .qfai/report/validate.json
+prototyping:
+  calibration:
+    packPath: .qfai/evidence/calibration.yaml
+    thresholds:
+      accept: 0.8
+      refine: 0.5
+    maxIterations: 15
+    plateauDelta: 0.02
+    plateauLookback: 3
+  execution:
+    targetUrl: null
+    browserProvider: playwright
+    renderProvider: playwright

package/assets/uix-rev/comparison-review.md

@@ -1,13 +1,30 @@
 # UIX-REV: Comparison Review
 
-Review option comparison and anchor selection.
+Review option comparison and selected anchor screen as independent artifacts.
 
-## Comparison (30_comparison.md)
+## Comparison Quality (30_option_comparison.md)
 
-- Must contain at least 2 options
-- Each option should have structured evaluation
+- Must contain at least 2 options with structured evaluation
+- Each option should have pros/cons/trade-off analysis
+- Evaluation criteria must reference the 3-layer evaluation family
+- Rejected/deferred options must have explicit rationale
+- Reconsideration conditions must be documented for deferred options
 
-## Anchor (31_anchor.md)
+### Trend-derived conversion check
 
-- Must declare selected_anchor or chosen field
-- Anchor must reference one of the compared options
+- Trend scan results are converted to comparison axes
+- Stale / overused AI slop avoidance is reflected in comparison criteria
+
+## Selected Direction Quality (31_selected_anchor_screen.md)
+
+- `selected_option` must reference one of the compared options in `30_option_comparison.md`
+- `why_selected` must provide rationale aligned with 3-layer evaluation family
+- Anchor screen must represent the canonical visual direction
+- Downstream strategy (`10_implementation_strategy.md`) must align with selected direction
+- Downstream contracts (`40_screen_contracts.md`) must be consistent with selected direction
+- Deferred options must document reconsideration conditions
+
+### Trend-derived conversion check
+
+- Trend scan results are reflected in selected direction rationale
+- Stale / overused AI slop avoidance is reflected in selection

package/assets/uix-rev/contracts-review.md

@@ -1,18 +1,25 @@
-# UIX-REV: Screen Contracts Review
+# UIX-REV: Screen Contracts Review (40_screen_contracts.md)
 
-Review screen contracts for completeness.
+Review screen contracts for canonical 11-field schema completeness.
 
-## Required Fields per Screen
+## Required Fields per Screen (canonical 11-field schema)
 
-- route
-- actor
-- purpose
-- primary_tasks
-- required_states
-- transitions
-- observable_outcomes
+1. `screen_id` — unique identifier
+2. `route` — URL path or navigation target
+3. `purpose` — what the screen accomplishes
+4. `actor` — who uses this screen
+5. `primary_tasks` — main user tasks on this screen
+6. `secondary_tasks` — additional tasks
+7. `required_states` — must include `default`, `loading`, `empty`, and `error`
+8. `transitions` — navigation to/from this screen
+9. `observable_outcomes` — what success looks like
+10. `notes_for_verify` — verification guidance
+11. `notes_for_reviewer` — reviewer-specific notes
 
 ## Quality Criteria
 
 - Each screen contract must be independently verifiable
 - Routes must be unique across all contracts
+- Required states must include `default`, `loading`, `empty`, and `error`
+- All 11 fields must be present and non-empty for each screen
+- Screen contracts must be consistent with 50_review_input_bundle.md

package/assets/uix-rev/scoring-review.md

@@ -1,14 +1,50 @@
 # UIX-REV: Scoring Review
 
-Review evaluation axes and aggregate scoring rules.
+Review scoring-ready schema for canonical completeness.
 
-## Evaluation Axes
+## Per-Axis Required Fields
+
+Each evaluation axis must include:
+
+1. `axis_id` — unique identifier
+2. `axis_name` — human-readable name
+3. `layer` — invariant / trend-derived / product-specific
+4. `origin` — derivation source (taste interview, trend scan, domain)
+5. `intent` — what this axis measures
+6. `why_it_matters` — rationale for inclusion
+7. `score_anchors` — concrete definitions for `low`, `mid`, `high`
+8. `positive_signals` — evidence that supports a high score
+9. `negative_signals` — evidence that supports a low score
+10. `anti_patterns` — patterns that should be flagged
+11. `evidence_required` — what evidence is needed to score
+12. `weight` — relative weight in aggregate scoring
+13. `minimum_floor` — minimum acceptable score (optional)
+14. `source_refs` — references to taste/trend sources
+15. `goal_refs` — references to project goals
+16. `review_questions` — questions the reviewer should ask
+
+## Evaluation Axes Quality
 
 - Each trend-derived row must include source_translation
 - Axes must be measurable and verifiable
+- No generic/boilerplate axes without taste/trend derivation
+
+## Aggregate Scoring Rules
+
+Canonical field names (must match `23_design_eval_aggregate.md`):
+
+- `total_score_formula`: weighted composite formula
+- `layer_weights`: per-layer weight allocation (must sum to 1.0)
+- `accept_threshold`: minimum score for accept verdict (≥ 3.5)
+- `refine_band`: score range for refine verdict (2.5–3.4)
+- `pivot_band`: score range for pivot verdict (< 2.5)
+- `max_iterations`: maximum scoring iterations
+- `plateau_rule`: stagnation detection rule documented
+- `missing_score_policy`: how to handle missing axis scores
+- `disagreement_rule`: calibration disagreement handling documented
 
-## Aggregate Scoring
+### Trend-derived conversion check
 
-- weights: defined for all axes
-- normalization: method specified
-- threshold: pass/fail boundary defined
+- Trend scan results are converted to scoring axes
+- Trend scan results are reflected in selected direction
+- Stale / overused AI slop avoidance is reflected in comparison and selection

package/assets/uix-rev/strategy-review.md

@@ -1,19 +1,23 @@
 # UIX-REV: Strategy Review
 
-Review the UI/UX strategy document for completeness and quality.
+Review the UI/UX strategy document (`10_implementation_strategy.md`) for completeness and quality.
+
+This review is scoped to strategy completeness only. Selected direction evaluation belongs to `comparison-review.md`.
 
 ## Required Fields
 
-- selection_required
-- candidate_options
-- chosen_option
-- verification_expectations
-- none_as_legitimate_outcome
+- `surface`
+- `decision`
+- `why_this_strategy`
+- `expected_strengths`
+- `known_risks`
+- `fit_for_this_product`
+- enum validity for `surface` and `decision`
 
-## Depth Check
+## Alignment Check
 
-- rationale: minimum 20 characters
-- approach: minimum 20 characters
+- Strategy `decision` must be consistent with the selected direction in `31_selected_anchor_screen.md` (cross-reference only; SSOT judgment is in comparison-review)
+- Strategy must not contradict screen contracts in `40_screen_contracts.md`
 
 ## Verdict