@anselmdk/feature-spec-md 0.7.0 → 0.8.1

package/README.md

@@ -7,9 +7,19 @@ Markdown specs for AI-assisted, testable spec-driven development.
 ```txt
 model + features + stack + design
 -> AI-written executable tests that reference stable spec IDs
--> validation, coverage, screenshots, and reports
+-> validation, coverage, screenshots, reports, and PR diffs
 ```
 
+## See the workflow in action
+
+The clearest example of what this library can deliver is the demo feature PR workflow:
+
+- **Feature PR:** <https://github.com/anselmdk/feature-spec-md-demo/pull/16>
+- **Feature spec report:** <https://feature-spec-md.anselm.dk/demo/build/269/>
+- **Feature spec diff:** <https://feature-spec-md.anselm.dk/demo/pr/16/269/>
+
+PRs like this are the essence of `feature-spec-md`: a feature branch can carry the product/spec/code change, a published feature spec report can show the full implementation state, and a PR diff report can show exactly what changed in the specs, rendered report, and screenshot evidence.
+
 ## What the tool does
 
 The shortest version is: `feature-spec-md` turns Markdown specifications into a testable contract.
@@ -21,21 +31,23 @@ It gives you:
 - **Validation** that checks frontmatter, headings, IDs, cross-document references, and test coverage expectations.
 - **Coverage reporting** that shows which model items, rules, and scenarios are implemented by tests.
 - **Scenario evidence policy** so specs can declare whether behavior should be tested by unit, integration, Playwright, manual, or no executable tests.
-- **HTML reports** that are useful for reviews, CI artifacts, or published build reports.
+- **HTML reports** that combine specs, coverage, validation status, source links, GitHub/build metadata, and screenshot evidence.
+- **PR diff reports** that compare a current published build with a base or previous build and highlight changed report files, changed spec sections, and screenshot evidence.
 - **Screenshot evidence** for scenarios when using the Playwright helper.
-- **A library API** for projects that want to parse specs, check coverage, collect screenshots, or render reports from their own tooling.
+- **GitHub Actions publishing helpers** for job summaries, FTP-published build reports, FTP-published PR diff reports, and PR comments.
+- **A library API** for projects that want to parse specs, check coverage, collect screenshots, render reports, or render diff reports from their own tooling.
 
 The specs are meant to be written with an AI before implementation. The tests are meant to be written with an AI from those specs. `feature-spec-md` then checks that the Markdown stays structured and that executable tests still cover the model items, rules, and scenarios the specs define.
 
 ## Demo project
 
-A complete demo app is available in [`anselmdk/feature-spec-md-demo`](https://github.com/anselmdk/feature-spec-md-demo). It shows a small support-ticket desk built from model, feature, stack, and design specs, with unit tests, Playwright tests, generated coverage, and a published report.
+A complete demo app is available in [`anselmdk/feature-spec-md-demo`](https://github.com/anselmdk/feature-spec-md-demo). It shows a small support-ticket desk built from model, feature, stack, and design specs, with unit tests, Playwright tests, generated coverage, screenshot evidence, a published feature spec report, and a published PR diff report.
 
 Demo reports, including scenario screenshots, are available here:
 
 <https://feature-spec-md.anselm.dk/demo/>
 
-Use the demo repository when you want to see the expected project shape, script names, screenshot manifest flow, and report output in a real app.
+Use the demo repository when you want to see the expected project shape, script names, screenshot manifest flow, CI publishing setup, PR comments, and report output in a real app.
 
 ## What you write
 
@@ -62,9 +74,9 @@ A person who has completed registration and can request sign-in links.
 
 ### Feature specs
 
-Feature specs describe user-facing behavior with rules and scenarios. Rules and scenarios get stable IDs that tests can reference.
+Feature specs describe user-facing behavior with rules and scenarios. Rules and scenarios get stable IDs that tests can reference. Scenario steps are fenced so Markdown previews preserve line breaks without relying on trailing spaces.
 
-```md
+````md
 ---
 id: ACCOUNT-ACCESS
 title: Account access
@@ -86,10 +98,12 @@ Allow registered people to access their account securely.
 
 ### ACCOUNT-ACCESS-S001: Registered person signs in
 
+```
 Given a registered person is on the sign-in page
 When they request and open a valid sign-in link
 Then they are signed in
 ```
+````
 
 Feature specs can declare the expected test and evidence policy:
 
@@ -98,17 +112,19 @@ test: unit | integration | playwright | manual | skip
 screenshots: required | optional | skip
 ```
 
-If `screenshots` is omitted, Playwright scenarios default to `required`; non-Playwright scenarios default to `skip`. Scenario-level overrides can be written directly below a scenario heading:
+If `screenshots` is omitted, Playwright scenarios default to `required`; non-Playwright scenarios default to `skip`. Scenario-level overrides can be written directly below a scenario heading, before the fenced scenario block:
 
-```md
+````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
 ```
+````
 
 See [SPEC_FORMAT.md](SPEC_FORMAT.md) and [docs/evidence-policy.md](docs/evidence-policy.md) for the exact format.
 
@@ -155,7 +171,8 @@ npx feature-spec-md init --kind design --dir specs
 4. Ask an AI to write executable tests from the specs, preserving the relevant `-M001`, `-R001`, and `-S001` IDs in the test source.
 5. Run `npx feature-spec-md coverage` to see which scenarios, rules, and model items have tests.
 6. Run `npx feature-spec-md report` to generate an HTML implementation report for review or CI artifacts.
-7. Use `npx feature-spec-md github-report` in GitHub Actions when the report should be linked from the job summary or published.
+7. Use `npx feature-spec-md github-report` in GitHub Actions when the report should be linked from the job summary, uploaded as an artifact, or published by FTP.
+8. Use `npx feature-spec-md github-diff-report` in PR builds when a published diff should compare the current report output and screenshots with a base build and provide a PR comment body.
 
 The longer flow, including AI prompts and CI setup, is in [docs/spec-driven-flow.md](docs/spec-driven-flow.md). The demo repository also shows the flow in practice: <https://github.com/anselmdk/feature-spec-md-demo>.
 
@@ -164,8 +181,9 @@ The longer flow, including AI prompts and CI setup, is in [docs/spec-driven-flow
 ```bash
 npx feature-spec-md check
 npx feature-spec-md coverage --fail-on-missing
-npx feature-spec-md report --out test-results/feature-spec-report/index.html
-npx feature-spec-md github-report --report-dir test-results/spec-report
+npx feature-spec-md report --out test-results/spec-report/index.html
+npx feature-spec-md github-report --report-dir test-results/spec-report --publish ftp
+npx feature-spec-md github-diff-report --publish ftp --pr-number 123
 ```
 
 By default the CLI scans:
@@ -175,7 +193,7 @@ specs/**/*.model.md
 specs/**/*.feature.md
 specs/**/*.stack.md
 specs/**/*.design.md
-tests/**/*.spec.ts
+tests/**/*.ts
 ```
 
 Use explicit patterns when your project uses different paths:
@@ -188,13 +206,13 @@ npx feature-spec-md check \
 
 ### `check`
 
-Validates the spec set and, by default, requires scenario coverage when tests are scanned.
+Validates the spec set and, by default, requires model, rule, and scenario coverage when tests are scanned.
 
 ```bash
 npx feature-spec-md check
 ```
 
-`check` validates spec structure, references between documents, and test coverage. Use `--require-scenario-coverage=false` while drafting. Use `--require-rule-coverage` and `--require-model-coverage` when rules and model items must also fail validation if they have no test references.
+`check` validates spec structure, references between documents, and test coverage. Use `--require-scenario-coverage=false`, `--require-rule-coverage=false`, or `--require-model-coverage=false` while drafting.
 
 ### `coverage`
 
@@ -204,7 +222,7 @@ Prints a terminal implementation report showing covered and missing model items,
 npx feature-spec-md coverage --fail-on-missing
 ```
 
-Use `--fail-on-missing` when missing model item, rule, or scenario coverage should fail CI.
+Use `--fail-on-missing=false` when missing model item, rule, or scenario coverage should not fail CI.
 
 ### `report`
 
@@ -223,7 +241,7 @@ npx feature-spec-md report \
   --screenshots "test-results/spec-report/screenshots-*.json"
 ```
 
-When CI should fail for missing declared screenshot evidence, add `--enforce-evidence`:
+When CI should fail for missing declared screenshot evidence, use `--enforce-evidence`:
 
 ```bash
 npx feature-spec-md report \
@@ -232,7 +250,7 @@ npx feature-spec-md report \
   --out test-results/spec-report/index.html
 ```
 
-This gate only fails for scenarios whose resolved screenshot policy is `required`.
+This gate only fails for scenarios whose resolved screenshot policy is `required`. In GitHub Actions, the report also includes source links and report metadata derived from the repository, ref, SHA, run, build number, and pull request context when available.
 
 ### `github-report`
 
@@ -244,6 +262,20 @@ npx feature-spec-md github-report \
   --publish ftp
 ```
 
+With FTP publishing, build reports are published below a `build/<build-number>/` directory. This keeps immutable build outputs available for later PR diff comparisons.
+
+### `github-diff-report`
+
+Builds and publishes a PR diff report from already-published feature spec report outputs.
+
+```bash
+npx feature-spec-md github-diff-report \
+  --publish ftp \
+  --pr-number 123
+```
+
+The diff report lists changed report assets, extracts changed spec sections, groups screenshot changes by spec/scenario, writes a GitHub Actions summary, and exposes a `diff-comment-body` output that a workflow can add to the PR. PR diff reports are published below `pr/<pr-number>/<build-number>/`.
+
 ## Playwright screenshot evidence
 
 The package exports a Playwright helper from `@anselmdk/feature-spec-md/playwright`. It maps scenario step text back to the spec line, wraps the implementation in a Playwright `test.step`, captures a screenshot after the step, attaches it to the test, and writes a screenshot manifest such as `test-results/spec-report/screenshots-0.json`.
@@ -252,7 +284,7 @@ That manifest can then be passed to `feature-spec-md report` with `--screenshots
 
 ## GitHub Actions report publishing
 
-`feature-spec-md github-report` writes the GitHub Actions job summary and can either prepare outputs for a GitHub artifact upload or publish the generated report to FTP.
+`feature-spec-md github-report` writes the GitHub Actions job summary and can either prepare outputs for a GitHub artifact upload or publish the generated report to FTP. `feature-spec-md github-diff-report` compares published build reports and publishes a PR-specific diff report.
 
 For FTP publishing, configure repository secrets in GitHub under **Settings → Secrets and variables → Actions → Repository secrets**.
 
@@ -271,9 +303,12 @@ Optional values:
 FEATURE_SPEC_FTP_REMOTE_DIR=/public_html/feature-spec-md
 FEATURE_SPEC_FTP_PORT=21
 FEATURE_SPEC_FTP_SECURE=false
+FEATURE_SPEC_BUILD_NUMBER=<build number, defaults to GITHUB_RUN_NUMBER>
+FEATURE_SPEC_PR_NUMBER=<pull request number>
+FEATURE_SPEC_BASE_BUILD_NUMBER=<main/base build number for PR diffs>
 ```
 
-Example GitHub Actions step:
+Example GitHub Actions step for publishing the current report:
 
 ```yaml
 - name: Publish feature spec report
@@ -286,6 +321,19 @@ Example GitHub Actions step:
     FEATURE_SPEC_REPORT_BASE_URL: ${{ secrets.FEATURE_SPEC_REPORT_BASE_URL }}
 ```
 
+Example step for publishing a PR diff after the current report has been published:
+
+```yaml
+- name: Publish feature spec PR diff
+  if: always() && github.event_name == 'pull_request'
+  run: npx feature-spec-md github-diff-report --publish ftp --pr-number "${{ github.event.pull_request.number }}"
+  env:
+    FEATURE_SPEC_FTP_HOST: ${{ secrets.FEATURE_SPEC_FTP_HOST }}
+    FEATURE_SPEC_FTP_USER: ${{ secrets.FEATURE_SPEC_FTP_USER }}
+    FEATURE_SPEC_FTP_PASSWORD: ${{ secrets.FEATURE_SPEC_FTP_PASSWORD }}
+    FEATURE_SPEC_REPORT_BASE_URL: ${{ secrets.FEATURE_SPEC_REPORT_BASE_URL }}
+```
+
 ## Library API
 
 Most integrations can use the top-level document API:
@@ -296,6 +344,7 @@ import {
   collectSpecScreenshots,
   parseSpecDocument,
   renderHtmlReport,
+  renderLocalDiffReport,
   validateScenarioScreenshots,
   validateSpecDocument,
 } from "@anselmdk/feature-spec-md";
@@ -309,6 +358,8 @@ Useful exports include:
 - `buildSpecCoverageSummary` and `collectSpecTestReferences` for custom coverage workflows.
 - `collectSpecScreenshots` and `validateScenarioScreenshots` for loading and enforcing screenshot evidence.
 - `renderHtmlReport` for generating the same report UI from your own integration.
+- `renderLocalDiffReport` for generating the same diff-report UI from local report directories.
+- `insertReportMetadata` and `githubReportMetadata` for adding source/build/PR metadata to reports.
 - `writeTextFile` for small report-writing integrations.
 
 Feature-only helpers such as `parseFeatureSpec` and `checkFeatureSpecs` remain available for compatibility.

package/SPEC_FORMAT.md

@@ -20,6 +20,8 @@ A spec set can contain four document types:
 - `*.stack.md` defines technical platform choices and their rationale.
 - `*.design.md` defines product, UI, layout, visual, and interaction direction.
 
+For larger products, each document type can also use the optional extension sections described below. These sections are designed for API-first products, SaaS authorization models, stateful domain objects, and e2e test environments without adding new required document suffixes.
+
 ## Frontmatter
 
 Every file starts with YAML-like frontmatter:
@@ -73,6 +75,7 @@ Optional sections:
 
 ```md
 ## Rules
+## Model Diagram
 ```
 
 Model items use stable `-M001` IDs:
@@ -89,6 +92,22 @@ Model rules use stable `-R001` IDs and describe global invariants for the domain
 - KANBAN-R001: A card MUST have one current workflow state.
 ```
 
+### Model Diagram
+
+Use `## Model Diagram` for one or more Mermaid diagrams that give a visual overview of model relationships. Diagrams supplement the stable model-item catalogue; they do not replace `## Model` items or affect coverage.
+
+````md
+## Model Diagram
+
+```mermaid
+erDiagram
+    BOARD ||--o{ CARD : contains
+    CARD }o--|| COLUMN : belongs_to
+```
+````
+
+Generated reports render `mermaid` fenced code blocks as diagrams. If Mermaid cannot load or a diagram is invalid, the escaped diagram source remains visible in the report. Model nodes SHOULD use recognizable names corresponding to the stable model items.
+
 ## Feature Files
 
 Feature files use the `.feature.md` suffix.
@@ -111,15 +130,17 @@ Rules use stable `-R001` IDs:
 - KANBAN-CARD-AUTHORING-R001: A new card MUST start in the To do column.
 ```
 
-Scenarios use stable `-S001` IDs and Given / When / Then steps:
+Scenarios use stable `-S001` IDs and Given / When / Then steps. The scenario body MUST be written inside a fenced code block so Markdown previews preserve line breaks without relying on trailing spaces:
 
-```md
+````md
 ### KANBAN-CARD-AUTHORING-S001: User creates a card
 
+```
 Given the user is on the board
 When they create a card with the title "Write release notes"
 Then the card "Write release notes" is visible in the To do column
 ```
+````
 
 Allowed step keywords are `Given`, `When`, `Then`, `And`, and `But`.
 
@@ -140,17 +161,19 @@ screenshots: required
 ---
 ```
 
-Scenario-level overrides go directly below a scenario heading:
+Scenario-level overrides go directly below a scenario heading. The Given / When / Then steps remain inside the fenced scenario block:
 
-```md
+````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
 ```
+````
 
 Supported `test` values are `unit`, `integration`, `playwright`, `manual`, and `skip`.
 
@@ -196,6 +219,102 @@ Required sections:
 
 Optional sections are `## Principles`, `## Layout`, `## Interaction`, and `## Visual style`.
 
+## Extension Sections
+
+The following optional sections are valid in model, feature, stack, and design files. They are intentionally plain Markdown so teams can adopt them gradually without changing the core scenario coverage model.
+
+Mermaid fenced code blocks are supported inside extension sections. Prefer `## Model Diagram` for domain relationship overviews and `## Lifecycle` for state diagrams.
+
+### Open Questions
+
+Use `## Open Questions` for unresolved product, technical, or testing choices that block confident implementation.
+
+```md
+## Open Questions
+
+- BOOKING-Q001: Confirm whether attendees can buy individual drop-in classes.
+- BOOKING-Q002: Confirm whether "user" includes public attendees or only staff members.
+```
+
+Open question IDs SHOULD use the document id plus `-Q001`. They are not treated as executable behavior and do not require test coverage.
+
+### Assumptions
+
+Use `## Assumptions` for temporary truths the spec relies on until they are confirmed, replaced, or promoted into rules.
+
+```md
+## Assumptions
+
+- BOOKING-A001: MobilePay is the first live payment provider.
+- BOOKING-A002: All initial recurring events repeat weekly.
+```
+
+Assumption IDs SHOULD use the document id plus `-A001`. When an assumption becomes durable product behavior, rewrite it as a rule with a `-R001` id.
+
+### API Contract
+
+Use `## API Contract` for API-first features and services. This section SHOULD describe endpoints, auth requirements, request/response shapes, status codes, idempotency expectations, pagination, webhooks, and links to generated OpenAPI or Swagger output.
+
+```md
+## API Contract
+
+| Method | Path | Purpose | Auth |
+| --- | --- | --- | --- |
+| POST | /api/events | Create an event | administrator |
+| GET | /api/events | List visible events | account member |
+```
+
+API contract details can be covered by integration tests that reference the relevant scenario and rule IDs.
+
+### Permissions
+
+Use `## Permissions` for role, group, and tenant capability matrices.
+
+```md
+## Permissions
+
+| Capability | Owner | Administrator | Teacher | Attendee |
+| --- | --- | --- | --- | --- |
+| Manage payment connection | yes | no | no | no |
+| Move own class instance | yes | yes | yes | no |
+```
+
+Permissions that must be enforced by the implementation SHOULD also be written as rules so coverage can track them.
+
+### Lifecycle
+
+Use `## Lifecycle` for state machines and transition rules for entities such as bookings, payments, subscriptions, passes, and recurring event instances.
+
+```md
+## Lifecycle
+
+Payment states:
+
+```txt
+pending -> paid
+pending -> failed
+paid -> refunded
+```
+
+Invalid transitions MUST be rejected by the API.
+```
+
+Lifecycle behavior that must be executable SHOULD be represented by rules and scenarios in the same feature file.
+
+### Test Environment
+
+Use `## Test Environment` for mocks, seed data, fixed-time behavior, provider adapters, and CI/e2e setup.
+
+```md
+## Test Environment
+
+- Email delivery is mocked and exposes the latest magic link to tests.
+- MobilePay runs through a deterministic mock in CI.
+- Time is frozen during recurring-event generation tests.
+```
+
+This section is especially useful for SaaS apps with external dependencies such as payment providers, email, calendars, or third-party APIs.
+
 ## Splitting Guidance
 
 Split model files by coherent domain vocabulary, ownership, or lifecycle.
@@ -206,6 +325,8 @@ Use stack files for broad technical choices such as framework, language, testing
 
 Use design files for product/UI direction such as layout, interaction, visual style, and design principles.
 
+Use extension sections when the information belongs with a spec but is not itself a model item, durable rule, or executable scenario. If an extension section becomes large enough to hide the core behavior, split the surrounding model or feature document instead of creating a new document type.
+
 Keep each document small enough for an AI to read, revise, and use as test-writing context without extra explanation.
 
 ## Test Coverage Convention

package/dist/githubActionDiffReport.js

@@ -31,7 +31,7 @@ export async function publishGithubActionDiffReport(options) {
     await writeGithubSummary([
         "## Feature Spec PR Diff",
         "",
-        `<p><strong>Diff report:</strong> <a href=\"${html(reportUrl)}\">PR #${html(prNumber)} build ${html(currentBuild)}</a></p>`,
+        `<p><strong>Diff report:</strong> <a href="${html(reportUrl)}">PR #${html(prNumber)} build ${html(currentBuild)}</a></p>`,
         summaryComparisonSentence(report),
         "",
     ].join("\n"));
@@ -140,12 +140,11 @@ async function compareLocalFiles(previousDir, currentDir) {
     const previousSet = new Set(previousFiles);
     const currentSet = new Set(currentFiles);
     const allPaths = Array.from(new Set([...previousSet, ...currentSet])).sort();
-    const files = [];
-    for (const filePath of allPaths) {
+    return Promise.all(allPaths.map(async (filePath) => {
         const previousInfo = previousSet.has(filePath) ? await fileInfo(join(previousDir, filePath)) : undefined;
         const currentInfo = currentSet.has(filePath) ? await fileInfo(join(currentDir, filePath)) : undefined;
         const status = !previousInfo ? "added" : !currentInfo ? "removed" : previousInfo.hash === currentInfo.hash ? "unchanged" : "changed";
-        files.push({
+        return {
             path: filePath,
             kind: fileKind(filePath),
             status,
@@ -153,9 +152,8 @@ async function compareLocalFiles(previousDir, currentDir) {
             currentHash: currentInfo?.hash,
             previousSize: previousInfo?.size,
             currentSize: currentInfo?.size,
-        });
-    }
-    return files;
+        };
+    }));
 }
 async function listLocalFilesRecursive(root) {
     const files = [];
@@ -172,12 +170,10 @@ async function listLocalFilesRecursive(root) {
         }
         for (const entry of entries) {
             const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
-            if (entry.isDirectory()) {
+            if (entry.isDirectory())
                 await visit(relativePath);
-            }
-            else if (entry.isFile()) {
+            else if (entry.isFile())
                 files.push(relativePath);
-            }
         }
     }
 }
@@ -190,7 +186,7 @@ async function loadSpecSections(root) {
 }
 async function loadPublishedSpecSections(root) {
     const specRoot = join(root, publishedSpecRoot);
-    const files = (await listLocalFilesRecursive(specRoot)).filter((file) => file.endsWith(".feature.md"));
+    const files = (await listLocalFilesRecursive(specRoot)).filter(isSpecMarkdownFile);
     const sections = [];
     for (const file of files) {
         const source = await readFile(join(specRoot, file), "utf8");
@@ -201,6 +197,9 @@ async function loadPublishedSpecSections(root) {
     }
     return sections.sort((a, b) => a.key.localeCompare(b.key));
 }
+function isSpecMarkdownFile(filePath) {
+    return filePath.endsWith(".md");
+}
 function previousBuildNumber(builds, currentBuild) {
     const current = Number(currentBuild);
     return builds.map(Number).filter((build) => Number.isFinite(build) && build < current).sort((a, b) => b - a).at(0)?.toString();
@@ -253,13 +252,7 @@ function extractSpecSections(source) {
         const scenarioIds = Array.from(fragment.matchAll(/<summary><code>([^<]+)<\/code>/g), (item) => textContent(item[1] ?? ""));
         const text = specText(fragment);
         const filePath = filePaths[0];
-        sections.push({
-            key: filePath ?? title,
-            title,
-            filePath,
-            scenarioIds,
-            text,
-        });
+        sections.push({ key: filePath ?? title, title, filePath, scenarioIds, text });
     }
     return sections;
 }
@@ -350,9 +343,8 @@ function compactContext(lines) {
 function scenarioSpecMap(specs) {
     const map = new Map();
     for (const spec of specs) {
-        for (const scenarioId of spec.scenarioIds) {
+        for (const scenarioId of spec.scenarioIds)
             map.set(scenarioId, spec);
-        }
     }
     return map;
 }
@@ -384,9 +376,7 @@ function screenshotTitle(filePath, scenarioId) {
     return scenarioId ? name.replace(`${scenarioId}-`, `${scenarioId} `) : name;
 }
 function relativeAssetUrl(prefix, filePath) {
-    return [prefix.replace(/\/+$/, ""), ...filePath.split("/").filter(Boolean)]
-        .filter(Boolean)
-        .join("/");
+    return [prefix.replace(/\/+$/, ""), ...filePath.split("/").filter(Boolean)].filter(Boolean).join("/");
 }
 function renderDiffReport(report) {
     const changed = report.files.filter((file) => file.status !== "unchanged" && file.kind !== "report");
@@ -425,8 +415,8 @@ th{background:#f6f8fa}a{color:#0969da}
 }
 function renderSpecDiffs(specDiffs) {
     if (!specDiffs.length)
-        return `<section class="panel"><h2>Spec changes</h2><p class="muted">No feature spec source changes detected.</p></section>`;
-    return `<section class="panel"><h2>Spec changes</h2><p class="muted">Diffed from published feature spec source files, not from rendered report HTML.</p>${specDiffs.map(renderSpecDiff).join("\n")}</section>`;
+        return `<section class="panel"><h2>Spec changes</h2><p class="muted">No spec source changes detected.</p></section>`;
+    return `<section class="panel"><h2>Spec changes</h2><p class="muted">Diffed from published Markdown files under the specs directory, not from rendered report HTML.</p>${specDiffs.map(renderSpecDiff).join("\n")}</section>`;
 }
 function renderSpecDiff(diff) {
     return `<details open><summary><strong>${html(diff.filePath ?? diff.title)}</strong> <span class="badge ${diff.status}">${html(diff.status)}</span></summary><table class="diff"><tbody>${diff.lines.map(renderDiffLine).join("")}</tbody></table></details>`;