qfai 1.5.0 → 1.5.1

package/README.md

@@ -246,7 +246,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.5.0)
+## Minimal tutorial (v1.5.1)
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.

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

@@ -89,7 +89,9 @@ Every major artifact in this stage MUST include this table schema:
   - `99_delta.md`
 - Discussion completion requires `Disposition: open` count to be zero in `11_OQ-Register.md`.
 - `deferred` is allowed only when required metadata is complete in `13_Deferred.md`.
+- `02_Inception-Deck.md` MUST contain at least one Mermaid diagram in ` ```mermaid ` fences.
 - `03_Story-Workshop.md` MUST contain at least one Mermaid diagram in ` ```mermaid ` fences.
+- If UI requirements exist, include an HTML+CSS visual mock in `03_Story-Workshop.md`.
 - 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`.
 - Discussion artifacts are logs/rationale and must not duplicate spec SSOT.
@@ -133,8 +135,8 @@ Produce a unified 15-file discussion pack with explicit decisions, requirements,
 ## Required Process
 
 1. Run the core interview for product concept, scope, stakeholders, and constraints (`01_Context.md`).
-2. Run Inception Deck (10 questions) for ambiguity removal and project alignment (`02_Inception-Deck.md`).
-3. Run Story Workshop to capture user stories, user flows, and at least one Mermaid diagram (`03_Story-Workshop.md`).
+2. Run Inception Deck (10 questions) for ambiguity removal and project alignment, and include at least one Mermaid diagram (`02_Inception-Deck.md`).
+3. Run Story Workshop to capture user stories, user flows, and at least one Mermaid diagram; add HTML+CSS screen mock when UI requirements exist (`03_Story-Workshop.md`).
 4. Register source traceability in `04_Sources.md` with stable `SRC-XXXX` identifiers.
 5. Define scope boundaries and success criteria in `05_Scope.md`.
 6. Capture functional requirements in `06_REQ.md` with `REQ-0001` format.
@@ -172,7 +174,7 @@ Rules:
 
 - `OQ-ID` (`OQ-0001` format)
 - `Title`
-- `Gate` (`discuss|require|sdd`)
+- `Gate` (`discussion|sdd|atdd|tdd|ops`)
 - `Disposition` (`open|resolved|deferred|rejected`)
 - `Owner` (`user|agent|team`)
 - `Rationale` (required for deferred/rejected)
@@ -250,8 +252,10 @@ Before declaring completion, you MUST:
 - verify all 15 mandatory output files exist and are populated;
 - ensure `Disposition: open` count is zero in `11_OQ-Register.md`;
 - ensure every deferred item has full metadata in `13_Deferred.md`;
+- ensure `02_Inception-Deck.md` includes at least one Mermaid diagram;
 - ensure `Example Seeds` sections are present and perspective coverage is explicit in `03_Story-Workshop.md`;
 - ensure `03_Story-Workshop.md` includes at least one Mermaid diagram;
+- ensure UI-related stories include an HTML+CSS screen mock section in `03_Story-Workshop.md`;
 - avoid duplicating finalized spec content in discussion outputs.
 
 ## Evidence (MANDATORY)
@@ -291,7 +295,9 @@ When done, report:
 - [ ] Deferred table fields follow the mandatory data model (all 11 columns present).
 - [ ] `Disposition: open` count is zero at completion.
 - [ ] Deferred items include required metadata.
+- [ ] `02_Inception-Deck.md` includes at least one Mermaid diagram.
 - [ ] `03_Story-Workshop.md` includes at least one Mermaid diagram.
+- [ ] UI-related stories include HTML+CSS screen mock details in `03_Story-Workshop.md`.
 - [ ] Mermaid fence rules were satisfied when diagrams were used.
 - [ ] Evidence file exists and includes Work Orders Summary + Reviewer result.
 - [ ] Reviewer returned `PASS`.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/02_Inception-Deck.md

@@ -37,6 +37,12 @@
 - High-level architecture:
 - Key components:
 
+```mermaid
+flowchart LR
+    User["User"] --> App["App / Service"]
+    App --> Data["Data Store"]
+```
+
 ## 7. What Keeps Us Up at Night (Risks)
 
 | Risk | Probability | Impact | Mitigation |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/03_Story-Workshop.md

@@ -42,3 +42,26 @@ flowchart TD
   - Entry point:
   - Steps:
   - Exit point:
+
+## Screen Mock (HTML+CSS)
+
+- Use this section when UI requirements exist.
+- Visual mock only; do not include JavaScript behavior.
+
+```html
+<section class="screen-mock">
+  <h1>Screen Title</h1>
+  <p>Primary information shown to the user.</p>
+  <button type="button">Primary Action</button>
+</section>
+```
+
+```css
+.screen-mock {
+  max-width: 560px;
+  margin: 24px auto;
+  padding: 20px;
+  border: 1px solid #d0d7de;
+  border-radius: 12px;
+}
+```

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/11_OQ-Register.md

@@ -2,13 +2,13 @@
 
 ## OQ Table
 
-| OQ-ID   | Title | Gate    | Disposition | Owner | Rationale | Options                              | Recommendation | Next-Decision-Point  | Due        | Evidence         |
-| ------- | ----- | ------- | ----------- | ----- | --------- | ------------------------------------ | -------------- | -------------------- | ---------- | ---------------- |
-| OQ-0001 | TBD   | discuss | deferred    | user  | TBD       | Option A / Option B (recommended: A) | Option A       | Trigger and due date | YYYY-MM-DD | Conversation log |
+| OQ-ID   | Title | Gate       | Disposition | Owner | Rationale | Options                              | Recommendation | Next-Decision-Point  | Due        | Evidence         |
+| ------- | ----- | ---------- | ----------- | ----- | --------- | ------------------------------------ | -------------- | -------------------- | ---------- | ---------------- |
+| OQ-0001 | TBD   | discussion | deferred    | user  | TBD       | Option A / Option B (recommended: A) | Option A       | Trigger and due date | YYYY-MM-DD | Conversation log |
 
 ## Rules
 
-- Allowed `Gate`: `discuss`, `require`, `sdd`.
+- Allowed `Gate`: `discussion`, `sdd`, `atdd`, `tdd`, `ops`.
 - Allowed `Disposition`: `open`, `resolved`, `deferred`, `rejected`.
 - Before discussion completion, `Disposition: open` must be zero.
 - For `deferred` and `rejected`, `Rationale` is mandatory.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/13_Deferred.md

@@ -2,9 +2,9 @@
 
 ## Deferred Items
 
-| OQ-ID   | Title | Gate    | Deferred-Reason | Deferred-Until | Owner | Due        | Severity | Impact                                         | Mitigation           | Evidence         |
-| ------- | ----- | ------- | --------------- | -------------- | ----- | ---------- | -------- | ---------------------------------------------- | -------------------- | ---------------- |
-| OQ-0001 | TBD   | discuss | TBD             | TBD            | user  | YYYY-MM-DD | medium   | Impact on spec/tests/implementation/operations | Temporary workaround | Conversation log |
+| OQ-ID   | Title | Gate       | Deferred-Reason | Deferred-Until | Owner | Due        | Severity | Impact                                         | Mitigation           | Evidence         |
+| ------- | ----- | ---------- | --------------- | -------------- | ----- | ---------- | -------- | ---------------------------------------------- | -------------------- | ---------------- |
+| OQ-0001 | TBD   | discussion | TBD             | TBD            | user  | YYYY-MM-DD | medium   | Impact on spec/tests/implementation/operations | Temporary workaround | Conversation log |
 
 ## Validation Rules
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/14_Review-Request.md

@@ -30,7 +30,13 @@
 - Consistency with upstream/downstream artifacts
 - Testability and acceptance clarity
 - Operational and security risks
+- Mermaid diagrams are sufficient for decision-making quality (not only presence)
+  - Scope boundary (in/out) is consistent across text/diagram/table
+  - Acceptance criteria are consistent with flows/state transitions
+  - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only
+- HTML+CSS screen mock is usable for UI alignment when UI requirements exist
+  - If UI requirements exist and no screen mock is provided, request changes
 - OQ register exit condition (open count = 0)
 - Deferred items have full metadata
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/Rxx_reviewer.md

@@ -11,7 +11,9 @@
 - [ ] Traceability consistency
 - [ ] Requirement and risk coverage
 - [ ] Clarity and actionability
+- [ ] Mermaid diagrams are sufficient for decisions (scope/AC/risk consistency)
 - [ ] Mermaid diagrams use ` ```mermaid ` fences only
+- [ ] HTML+CSS screen mock exists when UI requirements are present
 - [ ] OQ register exit condition (open count = 0)
 - [ ] Deferred items have full metadata
 

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/review/review_request.md

@@ -17,7 +17,13 @@
 - Consistency with upstream/downstream artifacts
 - Testability and acceptance clarity
 - Operational and security risks
+- Mermaid diagrams are sufficient for decision-making quality (not only presence)
+  - Scope boundary (in/out) is consistent across text/diagram/table
+  - Acceptance criteria are consistent with flows/state transitions
+  - Security/operations risks are reflected in diagrams where relevant
 - Mermaid diagrams use ` ```mermaid ` fences only (no ` ```text ` or language-less fences)
+- HTML+CSS screen mock is usable for UI alignment when UI requirements exist
+  - If UI requirements exist and no screen mock is provided, request changes
 - OQ register exit condition (open count = 0)
 - Deferred items have full metadata in `13_Deferred.md`
 - Validate hard gate evidence exists (`.qfai/report/validate.log`).

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

@@ -63,13 +63,13 @@ Each `spec-XXXX/` must satisfy:
 
 - `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 `require/require-*/` pack and stops if it is missing or incomplete.
-- Blocking OQ in `require-*/08_OQ.md` (`Disposition: open` + `Gate: discuss|require|sdd`) must be resolved before SDD proceeds.
+- `/qfai-sdd` requires a complete `discussion/discussion-*/` pack and stops if it is missing or incomplete.
+- 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.
 - `_shared/04_Business-Flow.md` must include at least one ` ```mermaid ` block and at least one `flowchart` or `sequenceDiagram`.
 - Business Flow must be documented in `_shared/04_Business-Flow.md` (Markdown). Legacy `*Business-flow*.feature` is deprecated.
 - 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).
+- If diagrams are written in discussion/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.