@anselmdk/feature-spec-md 0.1.1 → 0.2.1

package/dist/testImplementationReport.js

@@ -0,0 +1,160 @@
+export function buildSpecImplementationReport(specs, coverage, models = []) {
+    const modelCoverage = new Map(coverage.modelCoverage?.map((item) => [item.id, item]) ?? []);
+    const scenarioCoverage = new Map(coverage.scenarioCoverage.map((item) => [item.id, item]));
+    const ruleCoverage = new Map(coverage.ruleCoverage.map((item) => [item.id, item]));
+    const modelItems = models.map((model) => {
+        const coverageItems = model.modelItems.map((modelItem) => modelCoverage.get(modelItem.id) ?? {
+            id: modelItem.id,
+            title: modelItem.title,
+            filePath: model.filePath,
+            line: modelItem.line,
+            covered: false,
+            references: [],
+        });
+        const coveredModelItems = coverageItems.filter((item) => item.covered);
+        const missingModelItems = coverageItems.filter((item) => !item.covered);
+        const rules = model.rules.map((rule) => ruleCoverage.get(rule.id) ?? {
+            id: rule.id,
+            title: rule.text,
+            filePath: model.filePath,
+            line: rule.line,
+            covered: false,
+            references: [],
+        });
+        const coveredRuleItems = rules.filter((rule) => rule.covered);
+        const missingRules = rules.filter((rule) => !rule.covered);
+        return {
+            id: model.frontmatter.id,
+            title: model.title,
+            filePath: model.filePath,
+            totalItems: coverageItems.length,
+            coveredItems: coveredModelItems.length,
+            totalRules: rules.length,
+            coveredRules: coveredRuleItems.length,
+            coveredModelItems,
+            missingModelItems,
+            coveredRuleItems,
+            missingRules,
+        };
+    });
+    const items = specs.map((spec) => {
+        const scenarios = spec.scenarios.map((scenario) => scenarioCoverage.get(scenario.id) ?? {
+            id: scenario.id,
+            title: scenario.title,
+            filePath: spec.filePath,
+            line: scenario.line,
+            covered: false,
+            references: [],
+        });
+        const rules = spec.rules.map((rule) => ruleCoverage.get(rule.id) ?? {
+            id: rule.id,
+            title: rule.text,
+            filePath: spec.filePath,
+            line: rule.line,
+            covered: false,
+            references: [],
+        });
+        const missingScenarios = scenarios.filter((scenario) => !scenario.covered);
+        const coveredScenarios = scenarios.length - missingScenarios.length;
+        const coveredRuleItems = rules.filter((rule) => rule.covered);
+        const missingRules = rules.filter((rule) => !rule.covered);
+        const status = statusForCoverage(coveredScenarios, scenarios.length);
+        return {
+            id: spec.frontmatter.id,
+            title: spec.title,
+            filePath: spec.filePath,
+            totalScenarios: scenarios.length,
+            coveredScenarios,
+            totalRules: rules.length,
+            coveredRules: coveredRuleItems.length,
+            missingScenarios,
+            coveredRuleItems,
+            missingRules,
+            status,
+        };
+    });
+    return {
+        models: modelItems,
+        specs: items,
+        implemented: items.filter((item) => item.status === "implemented"),
+        partial: items.filter((item) => item.status === "partial"),
+        missing: items.filter((item) => item.status === "missing"),
+        totalModels: modelItems.length,
+        totalModelItems: modelItems.reduce((sum, item) => sum + item.totalItems, 0),
+        coveredModelItems: modelItems.reduce((sum, item) => sum + item.coveredItems, 0),
+        missingModelItems: modelItems.reduce((sum, item) => sum + item.missingModelItems.length, 0),
+        totalSpecs: items.length,
+        totalScenarios: items.reduce((sum, item) => sum + item.totalScenarios, 0),
+        coveredScenarios: items.reduce((sum, item) => sum + item.coveredScenarios, 0),
+        missingScenarios: items.reduce((sum, item) => sum + item.missingScenarios.length, 0),
+        totalRules: coverage.ruleCoverage.length,
+        coveredRules: coverage.ruleCoverage.filter((item) => item.covered).length,
+        missingRules: coverage.ruleCoverage.filter((item) => !item.covered).length,
+    };
+}
+export function formatSpecImplementationReport(report) {
+    const modelSummary = report.totalModelItems > 0
+        ? `, ${report.coveredModelItems}/${report.totalModelItems} model item(s) covered`
+        : "";
+    const missingModelSummary = report.totalModelItems > 0
+        ? `. Missing model items: ${report.missingModelItems}`
+        : "";
+    return [
+        "Spec test implementation report",
+        "",
+        `Summary: ${report.implemented.length}/${report.totalSpecs} spec(s) implemented, ${report.coveredScenarios}/${report.totalScenarios} scenario(s) covered, ${report.coveredRules}/${report.totalRules} rule(s) covered${modelSummary}.`,
+        `Partial: ${report.partial.length}. Not implemented: ${report.missing.length}. Missing scenarios: ${report.missingScenarios}. Missing rules: ${report.missingRules}${missingModelSummary}.`,
+        ...(report.totalModels > 0 ? ["", formatModelSection(report.models)] : []),
+        "",
+        formatSection("Implemented", report.implemented),
+        "",
+        formatSection("Partial", report.partial),
+        "",
+        formatSection("Not implemented", report.missing),
+    ].join("\n");
+}
+function statusForCoverage(coveredScenarios, totalScenarios) {
+    if (totalScenarios > 0 && coveredScenarios === totalScenarios)
+        return "implemented";
+    if (coveredScenarios > 0)
+        return "partial";
+    return "missing";
+}
+function formatSection(title, specs) {
+    if (!specs.length)
+        return `${title}:\n  (none)`;
+    return [
+        `${title}:`,
+        ...specs.flatMap((spec) => [
+            `  - ${spec.id}: ${spec.title} (${spec.coveredScenarios}/${spec.totalScenarios} scenarios, ${spec.coveredRules}/${spec.totalRules} rules) ${spec.filePath}`,
+            ...spec.missingScenarios.map((scenario) => `    missing ${scenario.id}: ${scenario.title ?? "Untitled scenario"}`),
+            ...spec.coveredRuleItems.map((rule) => `    covered rule ${rule.id}: ${rule.title ?? "Untitled rule"}${formatCoverageReferenceSuffix(rule)}`),
+            ...spec.missingRules.map((rule) => `    missing rule ${rule.id}: ${rule.title ?? "Untitled rule"}`),
+        ]),
+    ].join("\n");
+}
+function formatModelSection(models) {
+    if (!models.length)
+        return "Models:\n  (none)";
+    return [
+        "Models:",
+        ...models.flatMap((model) => [
+            `  - ${model.id}: ${model.title} (${model.coveredItems}/${model.totalItems} model items, ${model.coveredRules}/${model.totalRules} rules) ${model.filePath}`,
+            ...model.coveredModelItems.map((item) => `    covered model ${item.id}: ${item.title ?? "Untitled model item"}${formatCoverageReferenceSuffix(item)}`),
+            ...model.missingModelItems.map((item) => `    missing model ${item.id}: ${item.title ?? "Untitled model item"}`),
+            ...model.coveredRuleItems.map((rule) => `    covered rule ${rule.id}: ${rule.title ?? "Untitled rule"}${formatCoverageReferenceSuffix(rule)}`),
+            ...model.missingRules.map((rule) => `    missing rule ${rule.id}: ${rule.title ?? "Untitled rule"}`),
+        ]),
+    ].join("\n");
+}
+function formatCoverageReferenceSuffix(item) {
+    const references = coverageReferenceLabels(item);
+    return references.length ? ` (${references.join(", ")})` : "";
+}
+function coverageReferenceLabels(item) {
+    return Array.from(new Set(item.references.map((reference) => {
+        const line = reference.line ? `:${reference.line}` : "";
+        return `${reference.filePath}${line}`;
+    })));
+}
+//# sourceMappingURL=testImplementationReport.js.map

package/dist/testImplementationReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testImplementationReport.js","sourceRoot":"","sources":["../src/testImplementationReport.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,5 +1,37 @@
+/**
+ * Shared TypeScript types for parsed spec documents, validation issues,
+ * coverage summaries, test references, and screenshot evidence.
+ */
+/** Shared frontmatter fields supported by all spec documents. */
+export type SpecFrontmatter = {
+    id: string;
+    title: string;
+    status?: "draft" | "active" | "deprecated";
+    owner?: string;
+};
+/** Frontmatter fields supported by documents that may reference models. */
+export type ModelReferenceFrontmatter = SpecFrontmatter & {
+    model?: string;
+    models?: string[] | string;
+};
+/** Frontmatter fields supported by `*.feature.md` files. */
+export type FeatureFrontmatter = ModelReferenceFrontmatter;
+/** Frontmatter fields supported by `*.design.md` files. */
+export type DesignFrontmatter = ModelReferenceFrontmatter;
+/** Parsed contents of one `*.model.md` file. */
+export type ModelSpec = {
+    kind: "model";
+    filePath: string;
+    frontmatter: SpecFrontmatter;
+    title: string;
+    purpose: string;
+    modelItems: ModelItem[];
+    rules: FeatureRule[];
+    source: string;
+};
 /** Parsed contents of one `*.feature.md` file. */
 export type FeatureSpec = {
+    kind?: "feature";
     filePath: string;
     frontmatter: FeatureFrontmatter;
     title: string;
@@ -8,14 +40,45 @@ export type FeatureSpec = {
     scenarios: FeatureScenario[];
     source: string;
 };
-/** Frontmatter fields supported by the feature spec format. */
-export type FeatureFrontmatter = {
+/** Parsed contents of one `*.stack.md` file. */
+export type StackSpec = {
+    kind: "stack";
+    filePath: string;
+    frontmatter: SpecFrontmatter;
+    title: string;
+    purpose: string;
+    stack: string;
+    context: string;
+    rationale: string;
+    consequences: string;
+    rules: FeatureRule[];
+    source: string;
+};
+/** Parsed contents of one `*.design.md` file. */
+export type DesignSpec = {
+    kind: "design";
+    filePath: string;
+    frontmatter: DesignFrontmatter;
+    title: string;
+    purpose: string;
+    design: string;
+    principles: string;
+    layout: string;
+    interaction: string;
+    visualStyle: string;
+    rules: FeatureRule[];
+    source: string;
+};
+/** Any parsed spec document. */
+export type SpecDocument = ModelSpec | FeatureSpec | StackSpec | DesignSpec;
+/** A model concept declared in the `## Model` section. */
+export type ModelItem = {
     id: string;
     title: string;
-    status?: "draft" | "active" | "deprecated";
-    owner?: string;
+    body: string;
+    line: number;
 };
-/** A business rule declared in the `## Rules` section. */
+/** A rule declared in the `## Rules` section. */
 export type FeatureRule = {
     id: string;
     text: string;
@@ -46,15 +109,15 @@ export type ValidationIssue = {
     filePath?: string;
     line?: number;
 };
-/** A rule or scenario ID found in executable tests. */
+/** A model item, rule, or scenario ID found in executable tests. */
 export type TestReference = {
     id: string;
     filePath: string;
     line: number;
-    kind: "scenario" | "rule";
+    kind: "model" | "rule" | "scenario";
     source: "title" | "tag" | "covers" | "annotation" | "free-text";
 };
-/** Coverage state for one expected rule or scenario. */
+/** Coverage state for one expected model item, rule, or scenario. */
 export type CoverageItem = {
     id: string;
     title?: string;
@@ -63,12 +126,14 @@ export type CoverageItem = {
     covered: boolean;
     references: TestReference[];
 };
-/** Complete test coverage mapping for a set of feature specs. */
+/** Complete test coverage mapping for a set of spec documents. */
 export type CoverageSummary = {
-    scenarioCoverage: CoverageItem[];
+    modelCoverage?: CoverageItem[];
     ruleCoverage: CoverageItem[];
-    orphanScenarioReferences: TestReference[];
+    scenarioCoverage: CoverageItem[];
+    orphanModelReferences?: TestReference[];
     orphanRuleReferences: TestReference[];
+    orphanScenarioReferences: TestReference[];
 };
 /** Screenshot evidence associated with an exact spec line. */
 export type SpecScreenshot = {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG;IACxB,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,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,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,0DAA0D;AAC1D,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,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC;CACjE,CAAC;AAEF,wDAAwD;AACxD,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,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG;IAC5B,gBAAgB,EAAE,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,wBAAwB,EAAE,aAAa,EAAE,CAAC;IAC1C,oBAAoB,EAAE,aAAa,EAAE,CAAC;CACvC,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/releasing.md

@@ -0,0 +1,107 @@
+# Releasing
+
+This package uses npm semver versions and bare git tags. Use `0.2.0`, not `v0.2.0`.
+
+Bare semver tags are valid git tags and match the package version exactly. The `v` prefix is common in many projects because it makes tag names visually distinct from branch names, but npm does not require it. For this repository, exact package-version tags are simpler because the tag, `package.json`, `package-lock.json`, and npm version all use the same string.
+
+## Release Candidate
+
+Use an RC when you want a testable npm package for the next release without updating the `latest` npm dist-tag.
+
+1. Make sure `main` contains the intended final version in `package.json` and `package-lock.json`.
+   - For the next minor release from `0.1.1`, the base version should be `0.2.0`.
+   - For the next major release from `0.2.0`, the base version should be `1.0.0`.
+2. Open GitHub Actions.
+3. Run the `Publish to npm` workflow from `main`.
+4. Choose `rc` for the release type.
+5. The workflow runs verification, changes the package version only inside the workflow to `<base>-rc.<run>.<attempt>`, and publishes it with the npm `rc` dist-tag.
+
+Install the latest RC with:
+
+```bash
+npm install @anselmdk/feature-spec-md@rc
+```
+
+Install a specific RC with:
+
+```bash
+npm install @anselmdk/feature-spec-md@0.2.0-rc.123.1
+```
+
+Repeat the workflow as needed. Each run publishes a new RC and moves the `rc` dist-tag to that version.
+
+## Stable Minor Release
+
+Use this for backward-compatible features.
+
+1. Start from a clean branch based on `main`.
+2. Bump the package version:
+
+   ```bash
+   npm version minor --no-git-tag-version
+   ```
+
+3. Run verification locally:
+
+   ```bash
+   npm run verify
+   npm run format
+   ```
+
+4. Open and merge a pull request containing the version bump and any release notes.
+5. After the PR is merged, update local `main` and create a bare semver tag that exactly matches `package.json`:
+
+   ```bash
+   git checkout main
+   git pull --ff-only
+   git tag 0.2.0
+   git push origin 0.2.0
+   ```
+
+6. Confirm the `Publish to npm` workflow succeeds.
+
+The workflow validates that the tag is a stable semver version and exactly matches `package.json` before publishing to npm with the `latest` dist-tag.
+
+## Stable Major Release
+
+Use this for breaking changes.
+
+1. Document the breaking changes in the release PR.
+2. Bump the package version:
+
+   ```bash
+   npm version major --no-git-tag-version
+   ```
+
+3. Run verification locally:
+
+   ```bash
+   npm run verify
+   npm run format
+   ```
+
+4. Open and merge the release PR.
+5. Tag the merged commit with the exact version, for example:
+
+   ```bash
+   git checkout main
+   git pull --ff-only
+   git tag 1.0.0
+   git push origin 1.0.0
+   ```
+
+6. Confirm the `Publish to npm` workflow succeeds.
+
+## npm Publishing Setup
+
+The publish workflows are ready for npm provenance. The best setup is npm trusted publishing with GitHub Actions OIDC, which avoids long-lived npm publish tokens.
+
+On npmjs.com, configure this package with trusted publishing:
+
+- Publisher: GitHub Actions
+- Repository owner: `anselmdk`
+- Repository name: `feature-spec-md`
+- Workflow filename: `publish.yml`
+- Allowed action: `npm publish`
+
+If trusted publishing is not configured yet, the workflow can still use the `NPM_TOKEN` repository secret. Keep RC and stable publishing in the same workflow because npm trusted publishing allows only one trusted publisher workflow per package.

package/docs/spec-driven-flow.md

@@ -0,0 +1,175 @@
+# AI Spec Driven Development Flow
+
+`feature-spec-md` is built for a loop where specs and tests are both AI-assisted, but the contract between them is explicit and testable.
+
+```txt
+AI drafts specs
+-> humans review intent
+-> AI writes tests from stable IDs
+-> tooling checks coverage
+-> implementation follows failing tests
+-> reports show what is implemented
+```
+
+## Install
+
+Install the package in the project that owns the specs and tests:
+
+```bash
+npm install -D @anselmdk/feature-spec-md
+```
+
+Add scripts if you want short project commands:
+
+```json
+{
+  "scripts": {
+    "spec": "feature-spec-md check",
+    "spec:coverage": "feature-spec-md coverage --fail-on-missing",
+    "spec:report": "feature-spec-md report"
+  }
+}
+```
+
+Create starter documents:
+
+```bash
+npx feature-spec-md init --kind model --dir specs
+npx feature-spec-md init --kind feature --dir specs
+npx feature-spec-md init --kind stack --dir specs
+npx feature-spec-md init --kind design --dir specs
+```
+
+## 1. Ask AI To Draft The Spec Set
+
+Give the AI product intent and ask it to create or update:
+
+- `*.model.md` for domain vocabulary and global invariants
+- `*.feature.md` for capabilities, rules, and scenarios
+- `*.stack.md` for implementation platform choices
+- `*.design.md` for product, UI, and interaction direction
+
+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.
+```
+
+Run:
+
+```bash
+npx feature-spec-md check --tests ""
+```
+
+Use `--tests ""` while the spec set is still being drafted so validation focuses on document structure and graph references.
+
+## 2. Review The Specs Before Implementation
+
+Review the Markdown as product intent, not as generated test code.
+
+Check that:
+
+- model terms are clear enough for test authors
+- feature rules are durable product truths
+- scenarios are concrete enough to become executable tests
+- stack choices are specific enough to guide implementation
+- design direction covers the visible behavior users will judge
+
+Then run:
+
+```bash
+npx feature-spec-md check --require-scenario-coverage=false
+```
+
+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.
+
+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.
+```
+
+Example:
+
+```ts
+test("ACCOUNT-ACCESS-S001 registered person signs in", async ({ page }) => {
+  // Covers ACCOUNT-ACCESS-R001 and ACCOUNT-M001.
+});
+```
+
+The test can reference IDs in titles, tags, annotations, comments, or metadata. The important part is that the ID text is present in the test source.
+
+## 4. Check Coverage
+
+Run:
+
+```bash
+npx feature-spec-md coverage
+```
+
+The coverage command groups specs by implementation state and shows missing scenario, rule, and model item references.
+
+Use this in CI when missing scenario tests should block a change:
+
+```bash
+npx feature-spec-md coverage --fail-on-missing
+```
+
+Use stricter checks when you also want rule coverage to fail CI:
+
+```bash
+npx feature-spec-md check --require-rule-coverage=true
+```
+
+## 5. Generate A Report
+
+Run:
+
+```bash
+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.
+
+If your tests produce screenshot manifests, include them:
+
+```bash
+npx feature-spec-md report \
+  --screenshots "test-results/spec-report/screenshots-*.json" \
+  --out test-results/feature-spec-report/index.html
+```
+
+Screenshot manifest shape:
+
+```json
+{
+  "screenshots": [
+    {
+      "specPath": "specs/account-access.feature.md",
+      "line": 24,
+      "path": "screenshots/account-access-s001-line-24.png",
+      "title": "ACCOUNT-ACCESS-S001:24 Given a registered person is on the sign-in page"
+    }
+  ]
+}
+```
+
+## 6. 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
+```
+
+That keeps the AI-generated work anchored to a small, reviewable contract instead of a loose conversation history.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@anselmdk/feature-spec-md",
-  "version": "0.1.1",
-  "description": "Markdown feature specs with rule/scenario IDs, validation, coverage checks, and generated reports.",
+  "version": "0.2.1",
+  "description": "Markdown specs for AI-assisted, testable spec driven development across model, feature, stack, and design documents.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anselmdk/feature-spec-md.git"
+  },
   "bin": {
     "feature-spec-md": "./dist/cli.js"
   },
@@ -11,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./specDocuments": {
+      "types": "./dist/specDocuments.d.ts",
+      "import": "./dist/specDocuments.js"
+    },
     "./playwright": {
       "types": "./dist/playwright.d.ts",
       "import": "./dist/playwright.js"
@@ -20,6 +28,7 @@
     "dist",
     "README.md",
     "SPEC_FORMAT.md",
+    "docs",
     "templates",
     "examples",
     "LICENSE"
@@ -49,6 +58,7 @@
     "gherkin",
     "playwright",
     "specification",
+    "spec-driven-development",
     "testing"
   ],
   "license": "MIT",