qfai 1.4.23 → 1.4.24

package/README.md

@@ -210,7 +210,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.23)
+## Minimal tutorial (v1.4.24)
 
 1. `npx qfai init`
 2. Run `/qfai-discuss` to structure scope and open questions.
@@ -237,8 +237,8 @@ Release gate behavior:
 
 ## Continuous integration
 
-QFAI v1.4.23 generates `.github/**` only for Copilot integration wrappers
-(`.github/prompts`, `.github/agents`).
+QFAI v1.4.24 generates integration wrappers under `.agents/**`, `.claude/**`,
+`.github/**`, and `.codex/**`.
 It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:
 
@@ -272,6 +272,11 @@ Typical customizations.
 
 ```text
 .
+├── .agents
+│   ├── README.md
+│   └── skills
+│       └── qfai-configure
+│           └── SKILL.md
 ├── .qfai
 │   ├── assistant
 │   │   ├── agents
@@ -374,6 +379,7 @@ Typical customizations.
 
 Integration wrappers are also generated for immediate use:
 
+- Agents/Codex VS Code: `.agents/skills/**`
 - Claude Code: `.claude/commands/**`, `.claude/agents/**`
 - GitHub Copilot: `.github/prompts/**`, `.github/agents/**`
 - Codex: `.codex/skills/**`
@@ -381,7 +387,7 @@ Integration wrappers are also generated for immediate use:
 ## Agent integrations
 
 `npx qfai init` installs canonical skills under `.qfai/assistant/skills/**` (SSOT)
-and generates thin wrapper assets for Copilot / Claude Code / Codex.
+and generates thin wrapper assets for Agents/Codex VS Code / Copilot / Claude Code / Codex.
 If wrapper assets drift from canonical skills, rerun `npx qfai init --force` to resync.
 
 ## Contributing (for QFAI maintainers)

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

@@ -161,6 +161,8 @@ Rules:
 - If `plan.md` exists, you MUST follow it as implementation constraints.
 - `implementation-brief.md` is deprecated and must not be used as How SSOT.
 - If `plan.md` is missing, STOP and run `/qfai-sdd` before proceeding.
+- If `_shared/05_Contracts.md` (or equivalent contracts index) references any contract ID whose declared file does not exist under `.qfai/contracts/**`, STOP and rerun `/qfai-sdd`.
+- `/qfai-prototyping` MUST NOT create new contract files; contracts are strict inputs in this stage.
 - You MUST produce the required evidence file: `.qfai/evidence/prototyping-<spec-id>.md`.
   - `.qfai/evidence/` is intentionally NOT tracked by Git (it ships with a local `.gitignore`).
   - Do NOT commit evidence files; summarize key outcomes in the PR description instead.
@@ -225,6 +227,7 @@ Build a minimal runnable vertical slice from contracts so the app boots and user
 - ✅ You MAY add minimal “smoke scripts” (e.g., `scripts/smoke.ts`) if they help manual verification.
 - ❌ Do NOT implement acceptance tests here (that is `/qfai-atdd`).
 - ❌ Do NOT implement unit/component tests here (that is TDD phases).
+- ❌ Do NOT create new files under `.qfai/contracts/**` in this stage.
 - ❌ Do NOT change `.qfai/**/README.md` content. They are templates and remain SSOT.
 
 ## Mission (what “prototype” means)

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

@@ -171,7 +171,7 @@ Rules:
 
 ## Workflow Convention (Mandatory)
 
-- **This skill proceeds in this exact order: Outline -> Slice -> Plan finalize -> Delta update.**
+- **This skill proceeds in this exact order: Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update.**
 - **Upper-to-lower references are forbidden. Lower-to-upper references are allowed.**
 - **Connections between layers MUST be represented by IDs and required edges (`US->AC->BR->EX->TC`).**
 - **Plan finalize MUST happen after at least one user-story slice is grounded.**
@@ -184,6 +184,17 @@ Rules:
   - `.qfai/assistant/skills/qfai-sdd/templates/specs/`
   - `.qfai/assistant/skills/qfai-sdd/templates/contracts/`
 - Always write `.qfai/report/preflight_summary.md` before generating shared/spec artifacts.
+- Contracts are contract-first mandatory outputs in this skill:
+  - create/update `.qfai/contracts/(api|db|ui)/**` before shared/spec slices
+  - `_shared/05_Contracts.md` must include a Contract Index with short IDs (`DB-001`, `API-001`, `UI-001`)
+  - every indexed short ID must map to a declared file with `QFAI-CONTRACT-ID`:
+    - `DB-001 -> CON-DB-0001 -> db-0001-<slug>.sql`
+    - `API-001 -> CON-API-0001 -> api-0001-<slug>.yaml`
+    - `UI-001 -> CON-UI-0001 -> ui-0001-<slug>.yaml`
+  - `<slug>` comes from entity/router/screen and must be sanitized to kebab-case
+  - allocate new contract IDs by scanning existing declarations and using next sequential NNNN per kind
+  - never duplicate existing declared IDs; update in-place when the contract already exists
+  - contract stubs must be syntactically valid (OpenAPI YAML / UI YAML / executable SQL skeleton)
 - `/qfai-sdd` must stop when require-pack is missing/incomplete or has blocking OQ (guide to `/qfai-require` or `/qfai-discuss` first).
 - Review roster is fixed by `.qfai/assistant/steering/review-roster.yml` and must be executed in full.
 - RCP wording must be sourced from `.qfai/assistant/templates/rcp_footer.md`.
@@ -205,6 +216,22 @@ Rules:
   - ask the user when certainty is below threshold
   - unresolved decisions become explicit Open Questions
 
+### Phase 0 - Contracts-first (mandatory)
+
+Create/update:
+
+- `.qfai/contracts/api/**`
+- `.qfai/contracts/db/**`
+- `.qfai/contracts/ui/**`
+- `_shared/05_Contracts.md` Contract Index table (DB/API/UI short IDs)
+
+Rules:
+
+- This phase MUST complete before Outline/Slice.
+- If `_shared/05_Contracts.md` lists an ID, the corresponding declared contract file MUST exist.
+- If a contract is empty, create a valid minimal stub and include `QFAI-CONTRACT-ID`.
+- `none` is allowed only when there is no contract impact and rationale is written.
+
 ### Phase 1 - Outline (layer-first)
 
 Create/update:
@@ -216,11 +243,15 @@ Create/update:
 - `_shared/05_Contracts.md`
 - `_shared/06_Glossary.md`
 - `_shared/07_Constraints.md`
+- `_shared/08_Decisions.md`
+- `_shared/09_Open-questions.md`
+- `_shared/10_delta.md`
 
 Rules:
 
 - Temporary `TBD` is allowed, but each `TBD` must be mirrored into `_shared/09_Open-questions.md`.
 - `_shared/04_Business-Flow.md` must include Mermaid and keep diagram syntax inside ` ```mermaid ` fences.
+- `_shared/08_Decisions.md` and `_shared/10_delta.md` must exist even when empty, and must explicitly state `0 items`.
 
 ### Phase 2 - Slice (slice-first)
 
@@ -232,6 +263,8 @@ Create/update:
 - `spec-XXXX/04_Business-Rules.md`
 - `spec-XXXX/05_Examples.md`
 - `spec-XXXX/06_Test-Cases.md`
+- `spec-XXXX/07_Decisions.md`
+- `spec-XXXX/08_Open-questions.md`
 
 Slice gate (must pass before Phase 3):
 
@@ -239,6 +272,7 @@ Slice gate (must pass before Phase 3):
 - For each AC, BR and SC must exist.
 - For each TC, EX reference must exist.
 - `SC` tags must align with the target `spec-XXXX` namespace.
+- `07_Decisions.md` and `08_Open-questions.md` must exist even when empty and include explicit `0 items` statements.
 
 ### Phase 3 - Plan finalize
 
@@ -291,15 +325,20 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 - `.qfai/specs/_shared/05_Contracts.md`
 - `.qfai/specs/_shared/06_Glossary.md`
 - `.qfai/specs/_shared/07_Constraints.md`
+- `.qfai/specs/_shared/08_Decisions.md`
+- `.qfai/specs/_shared/09_Open-questions.md`
+- `.qfai/specs/_shared/10_delta.md`
 - `.qfai/specs/spec-XXXX/01_Spec.md`
 - `.qfai/specs/spec-XXXX/02_User-stories.md`
 - `.qfai/specs/spec-XXXX/03_Acceptance-Criteria.md`
 - `.qfai/specs/spec-XXXX/04_Business-Rules.md`
 - `.qfai/specs/spec-XXXX/05_Examples.md`
 - `.qfai/specs/spec-XXXX/06_Test-Cases.md`
+- `.qfai/specs/spec-XXXX/07_Decisions.md`
+- `.qfai/specs/spec-XXXX/08_Open-questions.md`
 - `.qfai/specs/spec-XXXX/10_Plan.md`
 - `.qfai/specs/spec-XXXX/09_delta.md` (or `*_delta.md`)
-- Updated contracts under `.qfai/contracts/**` when required
+- Updated contracts under `.qfai/contracts/**` (mandatory in this workflow)
 - `.qfai/report/preflight_summary.md`
 - Evidence file: `.qfai/evidence/sdd-<spec-id>.md`
 
@@ -309,11 +348,12 @@ Create or update layered SDD artifacts in one run so downstream execution phases
 2. If readiness checks fail, stop and show blockers with `/qfai-require` and `/qfai-discuss`.
 3. Analyze repository context, existing artifacts, constraints, and open decisions.
 4. Write `.qfai/report/preflight_summary.md` from `templates/report/preflight_summary.md`.
-5. Execute Phase 1 (Outline) in layer-first order.
-6. Execute Phase 2 (Slice) for at least one user-story slice and pass slice gate.
-7. Execute Phase 3 (Plan finalize) and make `10_Plan.md` actionable as How-only.
-8. Execute Phase 4 (Delta update) and record adoption/rejection rationale.
-9. Run static checks and record outcomes in evidence.
+5. Execute Phase 0 (Contracts-first) and ensure `_shared/05_Contracts.md` index and `.qfai/contracts/**` are aligned.
+6. Execute Phase 1 (Outline) in layer-first order.
+7. Execute Phase 2 (Slice) for at least one user-story slice and pass slice gate.
+8. Execute Phase 3 (Plan finalize) and make `10_Plan.md` actionable as How-only.
+9. Execute Phase 4 (Delta update) and record adoption/rejection rationale.
+10. Run static checks and record outcomes in evidence.
 
 ## Unified SDD Quality Gate
 
@@ -352,7 +392,7 @@ Required sections:
 When declaring DONE, include:
 
 - Referenced inputs and spec-id
-- Confirmation of phase order: Outline -> Slice -> Plan finalize -> Delta update
+- Confirmation of phase order: Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update
 - Decision record IDs touched in `09_delta.md` (or `*_delta.md`)
 - Confirmation that no rejected option was reintroduced (or list RE-OPEN IDs)
 - Unified SDD quality gate result
@@ -361,7 +401,8 @@ When declaring DONE, include:
 
 - [ ] CRITICAL CONSTRAINTS were followed.
 - [ ] `.qfai/report/preflight_summary.md` was generated before spec authoring.
-- [ ] Outline -> Slice -> Plan finalize -> Delta update order was preserved.
+- [ ] Contracts-first -> Outline -> Slice -> Plan finalize -> Delta update order was preserved.
+- [ ] `_shared/05_Contracts.md` index and `.qfai/contracts/**` declared files are aligned.
 - [ ] Upper-to-lower references were not introduced.
 - [ ] At least one user-story slice passed gate before plan finalization.
 - [ ] Required `_shared` + `spec-XXXX` outputs exist and are internally consistent.
@@ -392,7 +433,7 @@ When this skill is complete, provide a final user-facing completion message and
   Action: build contract-aligned skeleton implementation before deeper coding.
 - Test-first path: `/qfai-atdd`.
   Action: implement acceptance tests from the finalized spec pack.
-- Want to add contracts:
-  Action: create files under `.qfai/contracts/(api|db|ui)/` from `templates/contracts/*` and declare `QFAI-CONTRACT-ID`.
+- Contracts status:
+  Action: confirm contracts were created/updated under `.qfai/contracts/**` and referenced by `_shared/05_Contracts.md`.
 - Spec pack needs correction: rerun `/qfai-sdd`.
   Action: fix layered `_shared + spec-XXXX` consistency and decision records, then regenerate evidence.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_shared/05_Contracts.md

@@ -2,25 +2,49 @@
 
 ## Purpose
 
-- Describe API/UI/DB contract boundaries in shared language.
-- Model relationships with Mermaid when expressing entities or ownership.
+- Keep contracts as SSOT under `.qfai/contracts/**` with deterministic IDs.
+- Use this file as a readable index with short IDs for planning and review.
+
+## Contract Index
+
+### DB Contracts
+
+| Short ID | Entity       | Declared ID | File                                    | Purpose           |
+| -------- | ------------ | ----------- | --------------------------------------- | ----------------- |
+| DB-001   | order_drafts | CON-DB-0001 | `.qfai/contracts/db/db-0001-<slug>.sql` | draft persistence |
+
+### API Contracts
+
+| Short ID | Router      | Declared ID  | File                                       | Purpose      |
+| -------- | ----------- | ------------ | ------------------------------------------ | ------------ |
+| API-001  | /api/orders | CON-API-0001 | `.qfai/contracts/api/api-0001-<slug>.yaml` | create draft |
+
+### UI Contracts
+
+| Short ID | Screen       | Declared ID | File                                     | Purpose          |
+| -------- | ------------ | ----------- | ---------------------------------------- | ---------------- |
+| UI-001   | order-create | CON-UI-0001 | `.qfai/contracts/ui/ui-0001-<slug>.yaml` | draft input form |
+
+## Mapping Rules
+
+- `DB-001` maps to `CON-DB-0001`, file `db-0001-<slug>.sql`.
+- `API-001` maps to `CON-API-0001`, file `api-0001-<slug>.yaml`.
+- `UI-001` maps to `CON-UI-0001`, file `ui-0001-<slug>.yaml`.
+- `<slug>` must be kebab-case from entity/router/screen.
+- If no contracts are needed, keep each table and state `0 items` explicitly.
 
 ## Diagram (Mermaid required for ER/relationship)
 
 ```mermaid
 erDiagram
-  USER ||--o{ ORDER : places
+  USER ||--o{ ORDER_DRAFT : creates
   USER {
     string id
     string email
   }
-  ORDER {
+  ORDER_DRAFT {
     string id
     string user_id
+    string status
   }
 ```
-
-## Notes
-
-- Keep detailed SSOT in `.qfai/contracts/**`.
-- Use this file as the shared contract index and relationship map.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_shared/08_Decisions.md

@@ -0,0 +1,9 @@
+# 08 Decisions
+
+## Decisions
+
+- 0 items in shared decisions.
+
+## Empty State
+
+- Add ADR entries only when a cross-spec shared decision is required.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_shared/09_Open-questions.md

@@ -0,0 +1,11 @@
+# 09 Open Questions
+
+## Open Questions
+
+| OQ-ID   | Question         | Owner | Due | Status | Notes                         |
+| ------- | ---------------- | ----- | --- | ------ | ----------------------------- |
+| 0 items | 0 open questions | -     | -   | -      | Add rows only when unresolved |
+
+## Empty State
+
+- 0 open questions in shared scope.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/_shared/10_delta.md

@@ -0,0 +1,9 @@
+# 10 Delta
+
+## Change Summary
+
+- 0 items in shared delta.
+
+## Empty State
+
+- Add shared-scope decisions only when a cross-spec change requires tracking.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/07_Decisions.md

@@ -1,7 +1,9 @@
 # 07 Decisions
 
-## ADR-0001: <title>
+## Decisions
 
-- Context:
-- Decision:
-- Consequences:
+- 0 decisions in this spec.
+
+## Empty State
+
+- Add ADR entries when a local spec decision is finalized.

package/assets/init/.qfai/assistant/skills/qfai-sdd/templates/specs/spec/08_Open-questions.md

@@ -1,9 +1,11 @@
 # 08 Open Questions
 
-## OQ-0001: <title>
+## Open Questions
 
-- Status: open
-- Question:
-- Why missing:
-- Owner:
-- Due:
+| OQ-ID   | Question         | Owner | Due | Status | Notes                         |
+| ------- | ---------------- | ----- | --- | ------ | ----------------------------- |
+| 0 items | 0 open questions | -     | -   | -      | Add rows only when unresolved |
+
+## Empty State
+
+- 0 open questions in this spec.

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

@@ -21,9 +21,9 @@ specs/
 │   ├── 05_Contracts.md
 │   ├── 06_Glossary.md
 │   ├── 07_Constraints.md
-│   ├── 08_Decisions.md        (recommended)
-│   ├── 09_Open-questions.md   (recommended)
-│   └── 10_delta.md            (recommended)
+│   ├── 08_Decisions.md
+│   ├── 09_Open-questions.md
+│   └── 10_delta.md
 └── spec-XXXX/
     ├── 01_Spec.md
     ├── 02_User-stories.md
@@ -31,8 +31,8 @@ specs/
     ├── 04_Business-Rules.md
     ├── 05_Examples.md
     ├── 06_Test-Cases.md
-    ├── 07_Decisions.md        (recommended)
-    ├── 08_Open-questions.md   (recommended)
+    ├── 07_Decisions.md
+    ├── 08_Open-questions.md
     ├── 09_delta.md or *_delta.md
     └── 10_Plan.md             (optional, How-only)
 ```
@@ -71,5 +71,7 @@ Each `spec-XXXX/` must satisfy:
 - Gherkin is documented in `spec-XXXX/03_Acceptance-Criteria.md`.
 - If diagrams are written in discuss/require/spec/evidence artifacts, use ` ```mermaid ` fences only (do not use ` ```text ` or language-less fences).
 - Delta file accepts `09_delta.md` or any `*_delta.md`.
+- `07_Decisions.md` / `08_Open-questions.md` and `_shared/08_Decisions.md` / `_shared/09_Open-questions.md` / `_shared/10_delta.md` are required even when empty.
+- When empty, explicitly write `0 items` (or equivalent wording) in each file.
 - Contracts SSOT remains `.qfai/contracts/**`.
 - Report artifacts under `.qfai/report/**` are derived outputs (non-SSOT).