qfai 1.0.7 → 1.1.0

package/README.md

@@ -31,13 +31,15 @@ npx qfai report
 ## What you can do (CLI commands)
 
 - `npx qfai init`
-  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with prompts, instructions, agents, and steering templates), plus a default GitHub Actions workflow and `qfai.config.yaml`.
+  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with prompts, instructions, agents, and steering templates for product/tech/structure/manifest), plus a default GitHub Actions workflow and `qfai.config.yaml`.
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and writes `.qfai/report/validate.json`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate, and `--format github` to emit GitHub-friendly annotations.
 - `npx qfai report`
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
 - `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.
+- `npx qfai guardrails`
+  - Lists, extracts, or checks Decision Guardrails in `delta.md` (`list` / `extract` / `check`); use `--path` to point at samples or custom locations.
 
 ## Operating model (prompt-driven workflow)
 
@@ -55,7 +57,7 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 
 QFAI includes a small set of custom prompts (stored under `.qfai/assistant/prompts/`) designed to keep the workflow opinionated and repeatable.
 
-- **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and update `qfai.config.yaml` with a minimal diff (especially `testFileGlobs`). Run this once right after `npx qfai init`, and re-run it when the repository structure changes. Output: updated YAML + validation checklist.
+- **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and update steering (`product.md`, `tech.md`, `structure.md`, `manifest.md`) plus `qfai.config.yaml` with a minimal diff (especially `testFileGlobs`, and optionally `validation.require.specSections` when you want strict headings). Run this once right after `npx qfai init`, and re-run it when the repository structure changes or when you want to enforce required spec headings. Output: updated steering + YAML + validation checklist.
 - **qfai-discuss**: Turn an idea into clear requirements by discussing scope, constraints, risks, and open questions.
 - **qfai-require**: Produce `.qfai/require/require.md` from your idea or discussion output.
 - **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
@@ -81,7 +83,7 @@ R-->>U: .qfai kit installed (prompts, instructions, agents)
 
 U->>AG: Run /qfai-configure
 AG->>Q: Read .qfai/assistant/prompts/qfai-configure.md
-AG->>R: Update qfai.config.yaml (testFileGlobs, etc.)
+AG->>R: Update qfai.config.yaml (testFileGlobs, optional specSections)
 AG-->>U: Config tuned to this repo
 
 opt If you only have an idea
@@ -130,20 +132,23 @@ Operational notes.
 
 ## Configuration
 
-Configuration is stored at the repository root as `qfai.config.yaml`; you can change paths, traceability policies, and CI gate thresholds.
+Configuration is stored at the repository root as `qfai.config.yaml`.
+Most projects only customize `paths` and `validation.traceability`.
+`.qfai/require` is currently a fixed location (not configurable).
 
-Example: override paths and traceability globs.
+Example: a schema-valid configuration.
 
 ```yaml
 paths:
-  qfaiDir: .qfai
-  reportDir: .qfai/report
-  requireDir: .qfai/require
   specsDir: .qfai/specs
   contractsDir: .qfai/contracts
+  outDir: .qfai/report
+  promptsDir: .qfai/assistant/prompts
+  srcDir: src
+  testsDir: tests
+
 validation:
   failOn: error # error | warning | never
-  strict: false # if true, warnings also fail (equivalent to failOn=warning)
   traceability:
     testFileGlobs:
       - "src/**/*.test.ts"
@@ -152,11 +157,51 @@ validation:
       - "**/fixtures/**"
     scMustHaveTest: true
     scNoTestSeverity: warning # error | warning
+
+output:
+  validateJsonPath: .qfai/report/validate.json
+```
+
+### Spec validation (BR lines and required sections)
+
+BR lines are required and must use the format `- [BR-0001][P1] ...` (priority P0-P3). Headings can be in any language.
+`validation.require.specSections` controls required H2 section titles in `spec.md`. The default is an empty list to support multi-language specs.
+If you want strict required headings, run `/qfai-configure` and specify your desired spec template headings.
+
+Example (Japanese):
+
+```yaml
+validation:
+  require:
+    specSections:
+      - 背景
+      - スコープ
+      - 非ゴール
+      - 用語
+      - 前提
+      - 決定事項
+      - 業務ルール
+```
+
+Example (English):
+
+```yaml
+validation:
+  require:
+    specSections:
+      - Background
+      - Scope
+      - Non-goals
+      - Glossary
+      - Assumptions
+      - Decisions
+      - Business Rules
 ```
 
 Notes.
 
 - `validate.json`, `report.json`, and `doctor.json` are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
+- `--strict` is a CLI option for `qfai validate` (treat warnings as failures); it is not a YAML setting.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 
 ## Specifications and contracts (SDD)
@@ -181,9 +226,21 @@ Traceability is validated across these artifacts, so code changes remain grounde
 
 What works out-of-the-box.
 
-- The generated workflow is npm-oriented (`npm ci`); if your repository uses pnpm/yarn/bun, replace the install/cache steps accordingly.
+- The generated workflow runs without installing repository dependencies; it only executes `npx qfai validate --fail-on error`, so it works even if your repo is not a Node project.
+- The default workflow does not enable `actions/setup-node` caching, so it does not require a lockfile.
+- If you want to pin the QFAI version, install your repo dependencies (e.g., to run tests), or enable dependency caching, customize the workflow accordingly.
 - The default validate gate fails only on `error`; use `--fail-on warning` or `--strict` if you want a stricter gate.
 
+Optional cache example (requires a lockfile):
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: npm
+    # cache-dependency-path: package-lock.json
+```
+
 Typical customizations.
 
 - Add a second job to generate `report.md` from the uploaded `validate.json`.
@@ -277,6 +334,7 @@ Typical customizations.
 │   │   │   ├── README.md
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
+│   │   │   ├── manifest.md
 │   │   │   └── tech.md
 │   │   └── README.md
 │   ├── contracts
@@ -294,6 +352,9 @@ Typical customizations.
 │   │   └── require.md
 │   ├── specs
 │   │   └── README.md
+│   ├── samples
+│   │   ├── guardrails
+│   │   │   └── delta_with_guardrails.md
 │   └── README.md
 └── qfai.config.yaml
 ```

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

@@ -1,7 +1,8 @@
 # .qfai (QFAI Workspace)
 
 Generated by: `qfai init`
-Template version: 1.0.6
+Template version: 1.1.0
+This kit is generated by the installed QFAI version. See the QFAI changelog for release details.
 
 This directory is the workspace for **QFAI (Quality‑First AI)**.  
 QFAI standardizes engineering work around a fixed workflow:

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

@@ -6,4 +6,4 @@ This folder contains AI assistance assets.
 - `prompts.local/` : optional per-project overrides (not required)
 - `agents/` : subagent definitions (general job roles)
 - `instructions/` : constitutions/workflow policies for the AI
-- `steering/` : project context (product/tech/structure) used before work begins
+- `steering/` : project context (product/tech/structure/manifest) used before work begins

package/assets/init/.qfai/assistant/prompts/README.md

@@ -10,7 +10,7 @@ Rule:
 Files:
 
 - qfai-discuss.md (optional)
-- qfai-configure.md (run after init; updates qfai.config.yaml testFileGlobs; outputs updated YAML + validation checklist)
+- qfai-configure.md (run after init; updates steering + qfai.config.yaml testFileGlobs; outputs updated YAML + validation checklist)
 - qfai-require.md
 - qfai-spec.md
 - qfai-scenario-test.md

package/assets/init/.qfai/assistant/prompts/qfai-configure.md

@@ -8,7 +8,7 @@ QFAI Prompt Body (SSOT)
 
 id: qfai-configure
 title: QFAI Configure (Tune qfai.config.yaml)
-description: "Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs)."
+description: "Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs, optional specSections)."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, TodoWrite, Task]
 roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
@@ -20,14 +20,16 @@ mode: evidence-focused
 
 ## Purpose
 
-Analyze the repository and update `qfai.config.yaml` so QFAI traceability checks (especially SC->Test) are actionable without manual tuning.
+Analyze the repository and update `qfai.config.yaml` so QFAI traceability checks (especially SC->Test) are actionable without manual tuning, and optionally tune required spec sections if requested.
 
 ## Success Criteria (Definition of Done)
 
 - `qfai.config.yaml` is updated with a **minimal diff** focused on traceability globs.
 - `validation.traceability.testFileGlobs` reflects the real test layout.
 - `validation.traceability.testFileExcludeGlobs` is added only when needed.
+- If strict spec sections are explicitly requested, `validation.require.specSections` is updated with a minimal, evidence-based list.
 - A validation checklist with evidence (sample matched files) is produced.
+- Steering files (`product.md`, `tech.md`, `structure.md`, `manifest.md`) are filled or refreshed with evidence, or marked `TBD` when evidence is missing.
 
 ## Non-Negotiable Principles (QFAI Articles)
 
@@ -91,10 +93,11 @@ Simulate roles by running the same sequence yourself:
 
 ## Constraints
 
-- Only update `qfai.config.yaml` unless explicitly asked.
+- Only update `qfai.config.yaml` and `.qfai/assistant/steering/*` unless explicitly asked.
 - Do **not** modify tests or source code.
 - Avoid overly broad globs (e.g., `**/*`).
 - Exclude generated/output directories (`node_modules`, `.git`, `.qfai`, `dist`, `build`, `coverage`, `.next`, `out`, etc.).
+- Keep `validation.require.specSections` unchanged unless the user explicitly requests strict required headings.
 
 ## Step 0 - Load Context (always)
 
@@ -112,6 +115,12 @@ Simulate roles by running the same sequence yourself:
    - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
    - existing test patterns (unit/integration/e2e)
 
+4. Inspect steering templates and placeholders:
+   - `.qfai/assistant/steering/product.md`
+   - `.qfai/assistant/steering/tech.md`
+   - `.qfai/assistant/steering/structure.md`
+   - `.qfai/assistant/steering/manifest.md`
+
 ## Step 0 - Project Analysis (mandatory)
 
 Before editing config, **thoroughly analyze the current project**:
@@ -129,6 +138,7 @@ If analysis cannot be performed (missing access), clearly state what could not b
 1. Inspect `package.json` and config files (e.g., `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `pytest.ini`, `go.mod`).
 2. Enumerate directories that contain tests (e.g., `tests/`, `src/`, `e2e/`, `integration/`).
 3. Note naming rules and extensions that indicate test files.
+4. If strict spec sections are requested, sample existing `spec.md` files and list H2 headings used.
 
 ## Step 2 - Propose glob patterns
 
@@ -139,16 +149,25 @@ Provide 3-10 **include globs** that cover all known test locations:
 
 Provide **exclude globs** only when necessary (beyond the default exclusions).
 
-## Step 3 - Update `qfai.config.yaml` (minimal diff)
+## Step 3 - Update steering (evidence-first)
+
+Fill steering templates with repo evidence.
+
+- Keep existing content when already accurate.
+- When evidence is missing, write `TBD` and record what is missing.
+- Do not invent facts.
+
+## Step 4 - Update `qfai.config.yaml` (minimal diff)
 
 Edit:
 
 - `validation.traceability.testFileGlobs`
 - `validation.traceability.testFileExcludeGlobs` (only if needed)
+- `validation.require.specSections` (only if explicitly requested)
 
 Keep all other config keys unchanged.
 
-## Step 4 - Evidence sampling
+## Step 5 - Evidence sampling
 
 Sample 5-15 actual test files that match the proposed globs.
 
@@ -158,8 +177,10 @@ Sample 5-15 actual test files that match the proposed globs.
 ## Checkpoints
 
 - [ ] Repository analysis completed (frameworks, test layout, naming rules).
+- [ ] Steering files updated with evidence or `TBD`.
 - [ ] Proposed include/exclude globs with rationale.
 - [ ] `qfai.config.yaml` updated (minimal diff).
+- [ ] Optional: specSections tuned when requested (or kept empty).
 - [ ] Evidence: sample matched files listed.
 
 ## Output
@@ -167,8 +188,10 @@ Sample 5-15 actual test files that match the proposed globs.
 Provide:
 
 1. Updated `qfai.config.yaml` (diff or full file, as appropriate).
-2. A short summary of changes and rationale.
-3. Validation checklist with sampled files.
-4. Open questions (blocking vs non-blocking).
+2. Updated steering files (diff or summary).
+3. A short summary of changes and rationale.
+4. Validation checklist with sampled files.
+5. If specSections updated, list the chosen headings and evidence source.
+6. Open questions (blocking vs non-blocking).
 
 Suggest next step: `/qfai-require` (or `/qfai-discuss` if requirements are not ready).

package/assets/init/.qfai/assistant/prompts/qfai-verify.md

@@ -219,4 +219,4 @@ Output this format:
 ## Output
 
 - Evidence summary
-- Next action suggestion: /qfai-pr (optional) or proceed to PR creation
+- Next action suggestion: proceed to PR creation (use your platform workflow)

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

@@ -7,9 +7,15 @@ These are intentionally short and practical:
 - `product.md` : what we are building and why
 - `tech.md` : stack, versions, constraints
 - `structure.md` : repo structure, key directories, how to run gates
+- `manifest.md` : product-level decision spine and governance rubric
 
 QFAI prompts are expected to read these before producing deliverables.
 
+Rule:
+
+- Keep steering flat (no subdirectories).
+- Markdown only.
+
 ## AI-managed policy (recommended)
 
 These steering files are intended to be **filled and refreshed by the AI** (via QFAI custom prompts).

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

@@ -0,0 +1,43 @@
+# Manifest (Decision Spine)
+
+## Product / Mission
+
+- Summary:
+- Value:
+- Evidence:
+
+## Drive / Lens / Axioms
+
+- Axioms / principles:
+- Decision lens (what we optimize for):
+- Evidence:
+
+## Compatibility vs Change (Rubric)
+
+- Compatibility:
+- Change:
+- Examples:
+- Evidence:
+
+## Ownership / Governance
+
+- Owner:
+- Review / approval:
+- Update cadence:
+- Evidence:
+
+## Evidence
+
+- Rule (e.g., link to repo evidence for every claim):
+- Evidence:
+
+## Non-goals / Not-now (Optional)
+
+-
+- Evidence:
+
+## References (Optional)
+
+- product.md
+- tech.md
+- structure.md

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

@@ -20,6 +20,13 @@ Include the contract ID in the SQL header comments so QFAI can discover/index it
 
 - Keep DB contracts minimal and spec-driven (only what scenarios/tests need).
 - This directory is for the **contract/schema snapshot**, not migrations history.
-- If your project uses an ORM schema (Prisma, etc.), decide one:
-  - (Recommended for v1.0.6) Keep a minimal `.sql` contract snapshot here, and link to the real schema in the spec.
-  - (Future) Add support for other schema formats via config (out of scope for v1.0.6).
+
+If your project uses an ORM schema (Prisma, etc.), decide one:
+
+### Recommended
+
+- Keep a minimal `.sql` contract snapshot here, and link to the real schema in the spec.
+
+### Out of scope
+
+- Add support for other schema formats via config.

package/assets/init/.qfai/samples/guardrails/delta_with_guardrails.md

@@ -0,0 +1,19 @@
+# SPEC-0001: Delta (Decision Guardrails Sample)
+
+## Decision Guardrails
+
+- ID: DG-0001
+  Type: non-goal
+  Guardrail: Do not introduce per-language parsing rules into validators.
+  Rationale: Multi-language output is a core contract.
+  Reconsider: never
+  Related: SPEC-0001
+  Keywords: parsing, validators, multi-language
+
+- ID: DG-0002
+  Type: not-now
+  Guardrail: Do not add automatic template upgrades for existing repositories.
+  Rationale: Update safety needs a dedicated upgrade design.
+  Reconsider: after upgrade design is approved
+  Related: V11-OQ-007
+  Keywords: upgrade, templates

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

@@ -8,4 +8,8 @@ A **spec pack** lives under `specs/spec-XXXX/` and contains:
 
 Create/update spec packs with `/qfai-spec`.
 
+Decision Guardrails can be stored under `delta.md` as `## Decision Guardrails`. See `.qfai/samples/guardrails/delta_with_guardrails.md` for an opt-in example.
+
+Manifest is maintained under `.qfai/assistant/steering/manifest.md` (product-level decision spine). Do not duplicate a manifest under specs.
+
 Note: After `qfai init`, this folder contains only this README. Spec packs (`spec-XXXX/`) are created by running `/qfai-spec`.

package/assets/init/root/.github/workflows/qfai.yml

@@ -13,8 +13,6 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: npm
-      - run: npm ci
       - run: npx qfai validate --fail-on error --format github
       - uses: actions/upload-artifact@v4
         with:

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

@@ -8,14 +8,7 @@ paths:
 validation:
   failOn: error
   require:
-    specSections:
-      - 背景
-      - スコープ
-      - 非ゴール
-      - 用語
-      - 前提
-      - 決定事項
-      - 業務ルール
+    specSections: []
   traceability:
     brMustHaveSc: true
     scMustHaveTest: true