@anselmdk/feature-spec-md 0.4.0 → 0.5.0-rc.2

package/dist/types.d.ts

@@ -14,8 +14,17 @@ export type ModelReferenceFrontmatter = SpecFrontmatter & {
     model?: string;
     models?: string[] | string;
 };
+export type ScenarioTestType = "unit" | "integration" | "playwright" | "manual" | "skip";
+export type ScreenshotPolicy = "required" | "optional" | "skip";
+export type ScenarioEvidencePolicy = {
+    test: ScenarioTestType;
+    screenshots: ScreenshotPolicy;
+};
 /** Frontmatter fields supported by `*.feature.md` files. */
-export type FeatureFrontmatter = ModelReferenceFrontmatter;
+export type FeatureFrontmatter = ModelReferenceFrontmatter & {
+    test?: ScenarioTestType;
+    screenshots?: ScreenshotPolicy;
+};
 /** Frontmatter fields supported by `*.design.md` files. */
 export type DesignFrontmatter = ModelReferenceFrontmatter;
 /** Parsed contents of one `*.model.md` file. */
@@ -91,6 +100,7 @@ export type FeatureScenario = {
     id: string;
     title: string;
     line: number;
+    evidence: ScenarioEvidencePolicy;
     steps: FeatureStep[];
 };
 /** A single Given / When / Then style step inside a scenario. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG,eAAe,GAAG;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CAC5B,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE3D,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AAE1D,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,kBAAkB,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5E,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,aAAa,CAAC;IAClE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,KAAK,GACL,UAAU,CAAC;AAEf,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;IACpC,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC;CACjE,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,gBAAgB,EAAE,YAAY,EAAE,CAAC;IACjC,qBAAqB,CAAC,EAAE,aAAa,EAAE,CAAC;IACxC,oBAAoB,EAAE,aAAa,EAAE,CAAC;IACtC,wBAAwB,EAAE,aAAa,EAAE,CAAC;CAC3C,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/evidence-policy.md

@@ -0,0 +1,63 @@
+# Scenario Test And Evidence Policy
+
+Feature specs can declare how scenarios are expected to be tested and whether screenshot evidence is required.
+
+Use feature frontmatter to set defaults for all scenarios in a feature:
+
+```md
+---
+id: KANBAN-CARD-AUTHORING
+title: Card authoring
+test: playwright
+screenshots: required
+---
+```
+
+Use scenario-level overrides directly below a scenario heading when one scenario needs different evidence:
+
+```md
+### KANBAN-CARD-AUTHORING-S002: Card title is normalized
+Test: unit
+Screenshots: skip
+
+Given the raw card title contains leading whitespace
+When the title is normalized
+Then the stored title has no leading whitespace
+```
+
+## `test` values
+
+- `unit`: behavior is expected to be covered by unit tests.
+- `integration`: behavior is expected to be covered by integration tests.
+- `playwright`: behavior is expected to be covered by Playwright or another UI/browser test.
+- `manual`: behavior is intentionally verified manually.
+- `skip`: no executable test is expected for this scenario.
+
+## `screenshots` values
+
+- `required`: every scenario step should have screenshot evidence in the report manifest.
+- `optional`: screenshot evidence may be included when useful, but missing screenshots do not fail validation.
+- `skip`: screenshots are not expected and should not be treated as missing evidence.
+
+`screenshots: none` is accepted as an alias for `screenshots: skip`.
+
+## Defaults
+
+- If `test` is omitted, scenarios default to `unit`.
+- If `screenshots` is omitted and `test` resolves to `playwright`, screenshots default to `required`.
+- If `screenshots` is omitted and `test` resolves to `unit`, `integration`, `manual`, or `skip`, screenshots default to `skip`.
+
+This lets UI scenarios fail CI when screenshot evidence is missing, while unit-only domain behavior does not need screenshots.
+
+## CI enforcement
+
+Use report evidence enforcement in CI when declared screenshot evidence should block a build:
+
+```bash
+npx feature-spec-md report \
+  --screenshots "test-results/spec-report/screenshots-*.json" \
+  --enforce-evidence \
+  --out test-results/spec-report/index.html
+```
+
+The gate only fails for scenarios whose resolved screenshot policy is `required`.

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.4.0",
+  "version": "0.5.0-rc.2",
   "description": "Markdown specs for AI-assisted, testable spec driven development across model, feature, stack, and design documents.",
   "type": "module",
   "repository": {