@anselmdk/feature-spec-md 0.5.0 → 0.6.1

package/docs/spec-driven-flow.md

@@ -4,9 +4,9 @@
 
 ```txt
 AI drafts specs
--> humans review intent
+-> humans review intent and evidence policy
 -> AI writes tests from stable IDs
--> tooling checks coverage
+-> tooling checks coverage and declared evidence
 -> implementation follows failing tests
 -> reports show what is implemented
 ```
@@ -54,7 +54,9 @@ Useful instruction:
 ```txt
 Create feature-spec-md documents for this change. Keep the documents small.
 Use stable uppercase IDs. Put durable behavior in rules. Put testable examples
-in scenarios. Do not include test mappings inside the specs.
+in scenarios. For each feature or scenario, declare whether the expected test
+is unit, integration, playwright, manual, or skip. Require screenshots only for
+UI flows where visual evidence should be part of the review.
 ```
 
 Run:
@@ -74,9 +76,34 @@ Check that:
 - model terms are clear enough for test authors
 - feature rules are durable product truths
 - scenarios are concrete enough to become executable tests
+- each scenario has the right test policy
+- screenshots are required only for UI/browser behavior where visual evidence is valuable
 - stack choices are specific enough to guide implementation
 - design direction covers the visible behavior users will judge
 
+Example feature-level policy for UI behavior:
+
+```md
+---
+id: ACCOUNT-ACCESS
+title: Account access
+test: playwright
+screenshots: required
+---
+```
+
+Example scenario-level override for unit-only behavior:
+
+```md
+### ACCOUNT-ACCESS-S002: Link expiry is calculated
+Test: unit
+Screenshots: skip
+
+Given a sign-in link was created 31 minutes ago
+When expiry is calculated
+Then the link is expired
+```
+
 Then run:
 
 ```bash
@@ -87,14 +114,17 @@ This keeps the spec set valid while allowing missing tests.
 
 ## 3. Ask AI To Write Tests From The Specs
 
-Give the AI the relevant spec files and tell it to write executable tests that preserve spec IDs in the test source.
+Give the AI the relevant spec files and tell it to write executable tests that preserve spec IDs in the test source and match the declared test policy.
 
 Useful instruction:
 
 ```txt
 Write tests from these feature-spec-md specs. Each scenario test must include
 the scenario ID in the test title. Add comments or annotations for covered
-rule IDs and model item IDs. Do not invent IDs that are not in the specs.
+rule IDs and model item IDs. Use Playwright and the screenshot evidence helper
+for scenarios declared as test: playwright with screenshots: required. Use unit
+or integration tests for scenarios declared that way. Do not invent IDs that are
+not in the specs.
 ```
 
 Example:
@@ -137,7 +167,7 @@ Run:
 npx feature-spec-md report --out test-results/feature-spec-report/index.html
 ```
 
-The report is useful as a PR artifact because it shows specs, coverage state, validation issues, and optional screenshot evidence.
+The report is useful as a PR artifact because it shows specs, coverage state, validation issues, declared evidence policy, and optional screenshot evidence.
 
 If your tests produce screenshot manifests, include them:
 
@@ -147,6 +177,17 @@ npx feature-spec-md report \
   --out test-results/feature-spec-report/index.html
 ```
 
+When missing declared screenshot evidence should block the build, enforce evidence policy:
+
+```bash
+npx feature-spec-md report \
+  --screenshots "test-results/spec-report/screenshots-*.json" \
+  --enforce-evidence \
+  --out test-results/feature-spec-report/index.html
+```
+
+The gate only fails for scenarios whose resolved screenshot policy is `required`.
+
 Screenshot manifest shape:
 
 ```json
@@ -162,14 +203,32 @@ Screenshot manifest shape:
 }
 ```
 
-## 6. Keep The Loop Honest
+## 6. Publish The Report From CI
+
+A typical CI sequence is:
+
+```bash
+npm run build
+npx feature-spec-md check --require-rule-coverage --require-model-coverage
+npx feature-spec-md coverage --fail-on-missing
+npm test
+npx feature-spec-md report \
+  --screenshots "test-results/spec-report/screenshots-*.json" \
+  --enforce-evidence \
+  --out test-results/spec-report/index.html
+npx feature-spec-md github-report --publish ftp --report-dir test-results/spec-report
+```
+
+Use `--enforce-evidence` when the project wants missing required screenshots to fail the build. Leave it out when the report should show screenshot state without blocking.
+
+## 7. Keep The Loop Honest
 
 When behavior changes, update specs first, then regenerate or update tests from the changed specs.
 
 The expected loop is:
 
 ```txt
-spec change -> validation -> AI test update -> coverage -> implementation -> report
+spec change -> validation -> AI test update -> coverage -> implementation -> evidence report
 ```
 
 That keeps the AI-generated work anchored to a small, reviewable contract instead of a loose conversation history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anselmdk/feature-spec-md",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Markdown specs for AI-assisted, testable spec driven development across model, feature, stack, and design documents.",
   "type": "module",
   "repository": {
@@ -26,6 +26,7 @@
   },
   "files": [
     "dist",
+    "src/mocks",
     "README.md",
     "SPEC_FORMAT.md",
     "docs",
@@ -43,6 +44,7 @@
     "spec": "tsx src/cli.ts check",
     "spec:init": "tsx src/cli.ts init",
     "spec:report": "tsx src/cli.ts report",
+    "report:mock": "tsx src/mockReports.ts",
     "format": "prettier --write .",
     "check:example": "tsx src/cli.ts check --specs examples/**/*.feature.md --require-scenario-coverage=false",
     "report:example": "tsx src/cli.ts report --specs examples/**/*.feature.md --tests tests/**/*.test.ts --out test-results/feature-spec-report/index.html",

package/src/mocks/current/app/supportDesk.ts

@@ -0,0 +1,27 @@
+export type Ticket = {
+  id: string;
+  title: string;
+  status: "open" | "closed";
+  priority: "low" | "normal" | "high";
+  createdAt: string;
+};
+
+export function visibleTickets(tickets: Ticket[]) {
+  return tickets
+    .filter((ticket) => ticket.status === "open")
+    .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+}
+
+export function priorityBadge(ticket: Ticket) {
+  if (ticket.priority === "high") return "High priority";
+  if (ticket.priority === "low") return "Low priority";
+  return "Normal priority";
+}
+
+export function draftReply(existingDraft: string, nextText: string) {
+  return nextText.trim() ? nextText : existingDraft;
+}
+
+export function applySavedReply(template: string) {
+  return template.trim();
+}

package/src/mocks/current/screenshots/SUPPORT-INBOX-S001-line-27-current.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-label="Inbox with priority badges">
+  <rect width="960" height="540" fill="#f6f8fa"/>
+  <rect x="72" y="64" width="816" height="412" rx="24" fill="white" stroke="#d0d7de"/>
+  <rect x="112" y="112" width="736" height="72" rx="14" fill="#ddf4ff" stroke="#54aeff"/>
+  <text x="144" y="158" font-family="system-ui, sans-serif" font-size="28" font-weight="700" fill="#1f2328">Inbox with priority badges</text>
+  <rect x="112" y="224" width="520" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="292" width="660" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="360" width="420" height="44" rx="10" fill="#f6f8fa"/>
+  <circle cx="812" cy="384" r="34" fill="#ddf4ff" stroke="#54aeff"/>
+</svg>

package/src/mocks/current/screenshots/SUPPORT-REPLY-S001-line-27-current.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-label="Reply composer with suggested answer">
+  <rect width="960" height="540" fill="#f6f8fa"/>
+  <rect x="72" y="64" width="816" height="412" rx="24" fill="white" stroke="#d0d7de"/>
+  <rect x="112" y="112" width="736" height="72" rx="14" fill="#ddf4ff" stroke="#54aeff"/>
+  <text x="144" y="158" font-family="system-ui, sans-serif" font-size="28" font-weight="700" fill="#1f2328">Reply composer with suggested answer</text>
+  <rect x="112" y="224" width="680" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="292" width="620" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="360" width="300" height="44" rx="10" fill="#ddf4ff" stroke="#54aeff"/>
+  <circle cx="812" cy="384" r="34" fill="#ddf4ff" stroke="#54aeff"/>
+</svg>

package/src/mocks/current/screenshots/screenshots.json

@@ -0,0 +1,18 @@
+{
+  "screenshots": [
+    {
+      "specPath": "src/mocks/current/specs/ticket-inbox.feature.md",
+      "line": 27,
+      "path": "screenshots/SUPPORT-INBOX-S001-line-27-current.svg",
+      "title": "Inbox with priority badges",
+      "testPath": "src/mocks/current/tests/supportDesk.spec.ts"
+    },
+    {
+      "specPath": "src/mocks/current/specs/ticket-reply.feature.md",
+      "line": 27,
+      "path": "screenshots/SUPPORT-REPLY-S001-line-27-current.svg",
+      "title": "Reply composer with suggested answer",
+      "testPath": "src/mocks/current/tests/supportDesk.spec.ts"
+    }
+  ]
+}

package/src/mocks/current/specs/support-desk.model.md

@@ -0,0 +1,29 @@
+---
+id: SUPPORT
+title: Support desk
+status: active
+---
+
+# Support desk
+
+## Purpose
+
+Define the shared vocabulary for a small customer support workflow.
+
+## Model
+
+### SUPPORT-M001: Ticket
+
+A customer request that needs a response from an agent.
+
+### SUPPORT-M002: Agent
+
+A team member who reviews tickets and sends replies.
+
+### SUPPORT-M003: Priority
+
+A visible urgency label used to sort the queue.
+
+## Rules
+
+- SUPPORT-M-R001: Tickets MUST keep a stable public reference.

package/src/mocks/current/specs/ticket-inbox.feature.md

@@ -0,0 +1,27 @@
+---
+id: SUPPORT-INBOX
+title: Ticket inbox
+status: active
+model: SUPPORT
+test: playwright
+screenshots: optional
+---
+
+# Ticket inbox
+
+## Purpose
+
+Let agents find the next ticket to work on without losing context.
+
+## Rules
+
+- SUPPORT-INBOX-R001: The inbox MUST show open tickets first.
+- SUPPORT-INBOX-R002: The inbox SHOULD highlight high priority tickets.
+
+## Scenarios
+
+### SUPPORT-INBOX-S001: Agent reviews the queue
+
+Given an agent has open tickets
+When they open the inbox
+Then open tickets are listed by age with priority badges

package/src/mocks/current/specs/ticket-reply.feature.md

@@ -0,0 +1,33 @@
+---
+id: SUPPORT-REPLY
+title: Ticket replies
+status: active
+model: SUPPORT
+test: playwright
+screenshots: optional
+---
+
+# Ticket replies
+
+## Purpose
+
+Help agents answer a customer without leaving the ticket.
+
+## Rules
+
+- SUPPORT-REPLY-R001: The reply composer MUST preserve unsent text.
+- SUPPORT-REPLY-R002: Saved replies SHOULD be reusable across tickets.
+
+## Scenarios
+
+### SUPPORT-REPLY-S001: Agent drafts a reply
+
+Given an agent has selected a ticket
+When they write a reply
+Then the draft remains visible
+
+### SUPPORT-REPLY-S002: Agent sends a saved reply
+
+Given an agent has selected a ticket
+When they choose a saved reply
+Then the composer is filled with reusable text

package/src/mocks/current/tests/supportDesk.spec.ts

@@ -0,0 +1,17 @@
+import { draftReply, priorityBadge, visibleTickets } from "../app/supportDesk.js";
+
+const tickets = [
+  { id: "T-2", title: "Newer", status: "open" as const, priority: "high" as const, createdAt: "2026-01-02T10:00:00Z" },
+  { id: "T-1", title: "Older", status: "open" as const, priority: "normal" as const, createdAt: "2026-01-01T10:00:00Z" },
+];
+
+export function verifiesTicketInboxMock() {
+  // Covers SUPPORT-M001, SUPPORT-M002, SUPPORT-M003 and SUPPORT-M-R001.
+  // Covers SUPPORT-INBOX-R001, SUPPORT-INBOX-R002 and SUPPORT-INBOX-S001.
+  return visibleTickets(tickets).map((ticket) => priorityBadge(ticket));
+}
+
+export function verifiesReplyDraftMock() {
+  // Covers SUPPORT-REPLY-R001 and SUPPORT-REPLY-S001.
+  return draftReply("Existing draft", "Updated draft");
+}

package/src/mocks/previous/app/supportDesk.ts

@@ -0,0 +1,17 @@
+export type Ticket = {
+  id: string;
+  title: string;
+  status: "open" | "closed";
+  priority: "low" | "normal" | "high";
+  createdAt: string;
+};
+
+export function visibleTickets(tickets: Ticket[]) {
+  return tickets
+    .filter((ticket) => ticket.status === "open")
+    .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+}
+
+export function draftReply(existingDraft: string, nextText: string) {
+  return nextText.trim() ? nextText : existingDraft;
+}

package/src/mocks/previous/screenshots/SUPPORT-INBOX-S001-line-27-previous.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-label="Inbox before priority badges">
+  <rect width="960" height="540" fill="#f6f8fa"/>
+  <rect x="72" y="64" width="816" height="412" rx="24" fill="white" stroke="#d0d7de"/>
+  <rect x="112" y="112" width="736" height="72" rx="14" fill="#fff8c5" stroke="#d4a72c"/>
+  <text x="144" y="158" font-family="system-ui, sans-serif" font-size="28" font-weight="700" fill="#1f2328">Inbox before priority badges</text>
+  <rect x="112" y="224" width="520" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="292" width="660" height="44" rx="10" fill="#f6f8fa"/>
+  <rect x="112" y="360" width="420" height="44" rx="10" fill="#f6f8fa"/>
+  <circle cx="812" cy="384" r="34" fill="#fff8c5" stroke="#d4a72c"/>
+</svg>

package/src/mocks/previous/screenshots/screenshots.json

@@ -0,0 +1,11 @@
+{
+  "screenshots": [
+    {
+      "specPath": "src/mocks/previous/specs/ticket-inbox.feature.md",
+      "line": 27,
+      "path": "screenshots/SUPPORT-INBOX-S001-line-27-previous.svg",
+      "title": "Inbox before priority badges",
+      "testPath": "src/mocks/previous/tests/supportDesk.spec.ts"
+    }
+  ]
+}

package/src/mocks/previous/specs/support-desk.model.md

@@ -0,0 +1,29 @@
+---
+id: SUPPORT
+title: Support desk
+status: active
+---
+
+# Support desk
+
+## Purpose
+
+Define the shared vocabulary for a small customer support workflow.
+
+## Model
+
+### SUPPORT-M001: Ticket
+
+A customer request that needs a response from an agent.
+
+### SUPPORT-M002: Agent
+
+A team member who reviews tickets and sends replies.
+
+### SUPPORT-M003: Priority
+
+An internal urgency label.
+
+## Rules
+
+- SUPPORT-M-R001: Tickets MUST keep a stable public reference.

package/src/mocks/previous/specs/ticket-inbox.feature.md

@@ -0,0 +1,26 @@
+---
+id: SUPPORT-INBOX
+title: Ticket inbox
+status: active
+model: SUPPORT
+test: playwright
+screenshots: optional
+---
+
+# Ticket inbox
+
+## Purpose
+
+Let agents find the next ticket to work on without losing context.
+
+## Rules
+
+- SUPPORT-INBOX-R001: The inbox MUST show open tickets first.
+
+## Scenarios
+
+### SUPPORT-INBOX-S001: Agent reviews the queue
+
+Given an agent has open tickets
+When they open the inbox
+Then open tickets are listed by age

package/src/mocks/previous/specs/ticket-reply.feature.md

@@ -0,0 +1,26 @@
+---
+id: SUPPORT-REPLY
+title: Ticket replies
+status: draft
+model: SUPPORT
+test: playwright
+screenshots: optional
+---
+
+# Ticket replies
+
+## Purpose
+
+Help agents answer a customer without leaving the ticket.
+
+## Rules
+
+- SUPPORT-REPLY-R001: The reply composer MUST preserve unsent text.
+
+## Scenarios
+
+### SUPPORT-REPLY-S001: Agent drafts a reply
+
+Given an agent has selected a ticket
+When they write a reply
+Then the draft remains visible

package/src/mocks/previous/tests/supportDesk.spec.ts

@@ -0,0 +1,17 @@
+import { draftReply, visibleTickets } from "../app/supportDesk.js";
+
+const tickets = [
+  { id: "T-2", title: "Newer", status: "open" as const, priority: "high" as const, createdAt: "2026-01-02T10:00:00Z" },
+  { id: "T-1", title: "Older", status: "open" as const, priority: "normal" as const, createdAt: "2026-01-01T10:00:00Z" },
+];
+
+export function verifiesTicketInboxMock() {
+  // Covers SUPPORT-M001, SUPPORT-M002, SUPPORT-M003 and SUPPORT-M-R001.
+  // Covers SUPPORT-INBOX-R001 and SUPPORT-INBOX-S001.
+  return visibleTickets(tickets);
+}
+
+export function verifiesReplyDraftMock() {
+  // Covers SUPPORT-REPLY-R001 and SUPPORT-REPLY-S001.
+  return draftReply("Existing draft", "Updated draft");
+}