qfai 1.8.10 → 1.9.1

package/README.md

@@ -54,7 +54,7 @@ npx qfai report
 
 - `npx qfai init`
   - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit
-    (`assistant/` with skills, instructions, agents, and steering templates), plus `qfai.config.yaml`.
+    (`assistant/` with the 4-layer tree — `constitution/`, `manifest/`, `catalog/`, `process/` — plus `agents/` and `skills/`), plus `qfai.config.yaml`.
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and review artifacts
     (`.qfai/review/review-*/summary.json` + minimum schema), writes `.qfai/report/validate.json`,
@@ -170,7 +170,7 @@ participant R as Repo (codebase)
 
 U->>R: Create a repo (or open an existing one)
 U->>R: Run npx qfai init
-R-->>U: .qfai kit installed (skills, instructions, agents)
+R-->>U: .qfai kit installed (4-layer assistant tree + skills + agents)
 
 U->>AG: Run /qfai-configure
 AG->>Q: Read .qfai/assistant/skills/qfai-configure/SKILL.md
@@ -218,10 +218,10 @@ Operational notes.
 - Each custom skill must end with a completion message that enumerates all available next actions and clearly states what to do for each option.
 - Except `qfai-discussion`, each skill must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
 - 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/instructions/change-classification.md`.
+- 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/steering/review-gate.rules.yml`.
-- Agent taxonomy and invocation SSOT are defined in `.qfai/assistant/steering/agent-catalog.yml`, `.qfai/assistant/steering/agent-routing.yml`, and `.qfai/assistant/steering/review-profiles.yml`.
+- Review gate policies (required/optional layers and reviewers) are defined in `.qfai/assistant/catalog/review-gate.rules.yml`.
+- 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
 
@@ -367,7 +367,6 @@ Typical customizations.
 ├── .qfai
 │   ├── assistant
 │   │   ├── agents
-│   │   │   ├── README.md
 │   │   │   ├── acceptance-test-engineer.md
 │   │   │   ├── architecture-reviewer.md
 │   │   │   ├── backend-engineer.md
@@ -375,6 +374,7 @@ Typical customizations.
 │   │   │   ├── delivery-planner.md
 │   │   │   ├── devops-ci-engineer.md
 │   │   │   ├── discovery-analyst.md
+│   │   │   ├── doc-steward.md
 │   │   │   ├── frontend-engineer.md
 │   │   │   ├── implementation-reviewer.md
 │   │   │   ├── orchestrator.md
@@ -386,14 +386,26 @@ Typical customizations.
 │   │   │   ├── requirements-reviewer.md
 │   │   │   ├── solution-architect.md
 │   │   │   └── test-design-analyst.md
-│   │   ├── instructions
-│   │   │   ├── README.md
+│   │   ├── constitution
 │   │   │   ├── agent-selection.md
+│   │   │   ├── change-classification.md
 │   │   │   ├── communication.md
 │   │   │   ├── constitution.md
+│   │   │   ├── drift-protocol.md
 │   │   │   ├── quality.md
+│   │   │   ├── requirements-decomposition.md
+│   │   │   ├── research-first-protocol.md
+│   │   │   ├── shared-skill-delegation-baseline.md
+│   │   │   ├── shared-skill-operating-baseline.md
 │   │   │   ├── thinking.md
 │   │   │   └── workflow.md
+│   │   ├── manifest
+│   │   │   ├── agent-catalog.yml
+│   │   │   ├── agent-routing.yml
+│   │   │   └── review-profiles.yml
+│   │   ├── process
+│   │   │   └── migrations
+│   │   │       └── v<X.Y.Z>-<topic>.md
 │   │   ├── skills
 │   │   │   ├── qfai-configure
 │   │   │   │   └── SKILL.md
@@ -413,14 +425,16 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   └── qfai-verify
 │   │   │       └── SKILL.md
-│   │   ├── steering
-│   │   │   ├── agent-catalog.yml
-│   │   │   ├── agent-routing.yml
-│   │   │   ├── review-gate.rules.yml
-│   │   │   ├── review-profiles.yml
-│   │   │   ├── product.md
-│   │   │   ├── structure.md
-│   │   │   └── tech.md
+│   │   └── catalog
+│   │       ├── cli-ux-guidelines.md
+│   │       ├── manifest.md
+│   │       ├── product.md
+│   │       ├── review-gate.rules.yml
+│   │       ├── spec_required_files.json
+│   │       ├── structure.md
+│   │       ├── tech.md
+│   │       ├── test-layers.md
+│   │       └── ui-definition-protocol.md
 │   └── waivers.yml
 └── qfai.config.yaml
 ```

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

@@ -19,9 +19,9 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/02_User-stories.md
 - .qfai/specs/spec-\*/06_Test-Cases.md

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

@@ -21,10 +21,10 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md

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

@@ -21,9 +21,9 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md

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

@@ -18,10 +18,10 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - Validation evidence and gate results
 

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

@@ -20,8 +20,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .qfai/discussion/discussion-\*/04_Sources.md

package/assets/init/.qfai/assistant/agents/devops-ci-engineer.md

@@ -18,8 +18,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - package.json scripts, CI config, and runbooks
 - Evidence summaries under `.qfai/evidence/`

package/assets/init/.qfai/assistant/agents/discovery-analyst.md

@@ -19,8 +19,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - Existing discussion records under `.qfai/discussion/`
 - .qfai/discussion/discussion-\*/04_Sources.md

package/assets/init/.qfai/assistant/agents/doc-steward.md

@@ -18,8 +18,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - CHANGELOG.md
 - README.md
 - docs/\*\*

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

@@ -21,8 +21,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md

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

@@ -22,10 +22,10 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md

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

@@ -20,9 +20,9 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md (SSOT for hard coverage obligations)
+- .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)
 - Prompt-specific artifacts (traceability, validation evidence, optional legacy scenario/ledger artifacts)
 

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

@@ -23,8 +23,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .github/instructions/principles.instructions.md

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

@@ -27,10 +27,10 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .github/instructions/code-review.instructions.md
 - .github/instructions/principles.instructions.md

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

@@ -30,10 +30,10 @@ In addition to traceability-based coverage (US/TC/CON-API existence), verify the
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - `.qfai/report/validate.log`
 - `.qfai/report/specs-coverage/spec-*.md`

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

@@ -18,9 +18,9 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - QA evidence, coverage tooling outputs, and test plans

package/assets/init/.qfai/assistant/agents/requirements-analyst.md

@@ -19,8 +19,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/discussion/discussion-\*/04_Sources.md
 - .qfai/discussion/discussion-\*/06_REQ.md
@@ -33,6 +33,12 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 - Option set with recommendation and rejected rationale
 - Open questions with owner, decision point, and safe deferral notes
 - Mapping from requirements to impacted artifacts
+- For UI-bearing surfaces: every entry in the UI contract `screens[]` must
+  carry at least one `primary_task` (≥ 1 primary_task per screen). The
+  shipped `ui-contract.sample.yaml` template exposes a `primary_tasks: []`
+  placeholder slot; populate it before handing the contract to the
+  prototyping phase. Empty `primary_tasks` arrays cause the
+  QFAI-AUD-001 aligned validate lane to block `/qfai-prototyping`.
 
 ## Stop conditions
 

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

@@ -18,10 +18,10 @@ tools: [Read, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/instructions/drift-protocol.md
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/constitution/drift-protocol.md
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - Requirement drafts, option tables, and OQ ledgers
 

package/assets/init/.qfai/assistant/agents/solution-architect.md

@@ -22,8 +22,8 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/01_Spec.md
 - .qfai/discussion/discussion-\*/04_Sources.md

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

@@ -30,9 +30,9 @@ When reviewing or producing test cases, apply the checklist in `.qfai/assistant/
 
 ## Inputs you must read
 
-- .qfai/assistant/instructions/\*
-- .qfai/assistant/steering/\*
-- .qfai/assistant/steering/test-layers.md
+- .qfai/assistant/constitution/\*\*
+- .qfai/assistant/{manifest,catalog}/\*\*
+- .qfai/assistant/catalog/test-layers.md
 - .qfai/specs/spec-\*/09_delta.md
 - .qfai/specs/spec-\*/03_Acceptance-Criteria.md
 - .qfai/specs/spec-\*/04_Business-Rules.md

package/assets/init/.qfai/assistant/{steering → catalog}/manifest.md

@@ -31,9 +31,9 @@
 - Review / approval: <who approves what, gating policy>
 - Evidence requirements: <what artifacts are required for closure>
 - Update cadence: <how often this manifest is revisited>
-- Evidence: `.qfai/assistant/steering/agent-catalog.yml`,
-  `.qfai/assistant/steering/agent-routing.yml`,
-  `.qfai/assistant/steering/review-profiles.yml`
+- Evidence: `.qfai/assistant/manifest/agent-catalog.yml`,
+  `.qfai/assistant/manifest/agent-routing.yml`,
+  `.qfai/assistant/manifest/review-profiles.yml`
 
 ## Evidence
 

package/assets/init/.qfai/assistant/{steering → catalog}/review-gate.rules.yml

@@ -28,9 +28,9 @@ optional:
     - 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
+  catalog_ssot: .qfai/assistant/manifest/agent-catalog.yml
+  routing_ssot: .qfai/assistant/manifest/agent-routing.yml
+  review_profiles_ssot: .qfai/assistant/manifest/review-profiles.yml
 
 reviewers:
   minimum: 1
@@ -60,7 +60,7 @@ quality_gates:
       role: Implementation Reviewer
 
 optional_review_modes:
-  review_profiles_ssot: .qfai/assistant/steering/review-profiles.yml
+  review_profiles_ssot: .qfai/assistant/manifest/review-profiles.yml
   supported:
     - devils-advocate
     - pattern-doubler

package/assets/init/.qfai/assistant/{instructions → constitution}/constitution.md

@@ -44,8 +44,8 @@ Do **not** guess file paths, existing commands, or project policies.
 
 Before producing deliverables, read **project memory**:
 
-1. `.qfai/assistant/instructions/*`
-2. `.qfai/assistant/steering/*`
+1. `.qfai/assistant/constitution/*`
+2. `.qfai/assistant/manifest/*` + `.qfai/assistant/catalog/*`
 3. discussion pack in `.qfai/discussion/` (if present)
 4. `.qfai/specs/spec-*/` (if relevant)
 5. repository config (package.json, CI, scripts)

package/assets/init/.qfai/assistant/{instructions → constitution}/shared-skill-operating-baseline.md

@@ -22,10 +22,10 @@ Skill files should reference this baseline and only restate skill-specific addit
 
 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`
+- `.qfai/assistant/catalog/manifest.md`
+- `.qfai/assistant/catalog/product.md`
+- `.qfai/assistant/catalog/structure.md`
+- `.qfai/assistant/catalog/tech.md`
 
 Rules:
 

package/assets/init/.qfai/assistant/{instructions → constitution}/workflow.md

@@ -32,13 +32,13 @@ Do not proceed without a declared Change Type.
 
 ## Drift Protocol (Mandatory)
 
-- Read and enforce `.qfai/assistant/instructions/drift-protocol.md`.
+- Read and enforce `.qfai/assistant/constitution/drift-protocol.md`.
 - Downstream phases must not edit upstream SSOT artifacts without explicit user approval.
 - If drift is required, STOP and raise a Change Request (3 options + recommendation), then wait for approval and rerun the owner skill.
 
 ## Test-layer policy (Mandatory)
 
-- Read and enforce `.qfai/assistant/steering/test-layers.md`.
+- Read and enforce `.qfai/assistant/catalog/test-layers.md`.
 - Treat floors/ratios as signals, not completion gates.
 - Completion gate is `qfai validate --fail-on error` with evidence.
 
@@ -83,10 +83,10 @@ Legacy note:
 At the beginning of each stage (`qfai-discussion`, `qfai-sdd`, `qfai-prototyping`, `qfai-atdd`, `qfai-verify`):
 
 1. Check these steering files:
-   - `.qfai/assistant/steering/manifest.md`
-   - `.qfai/assistant/steering/product.md`
-   - `.qfai/assistant/steering/structure.md`
-   - `.qfai/assistant/steering/tech.md`
+   - `.qfai/assistant/catalog/manifest.md`
+   - `.qfai/assistant/catalog/product.md`
+   - `.qfai/assistant/catalog/structure.md`
+   - `.qfai/assistant/catalog/tech.md`
 2. Detect incomplete content (empty sections, placeholder-only lines, `<...>`, `TBD`, outdated facts).
 3. If the current stage can fill missing facts from repository evidence, update the steering files immediately.
 4. If information cannot be verified, record Open Questions and ask the user.