projectstore-claude 0.30.8 → 0.30.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
  2. package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
  3. package/node_modules/projectstore/.mcp.json +1 -5
  4. package/node_modules/projectstore/README.md +6 -5
  5. package/node_modules/projectstore/agents/archaeologist.md +1 -1
  6. package/node_modules/projectstore/agents/critic.md +26 -3
  7. package/node_modules/projectstore/agents/librarian.md +1 -1
  8. package/node_modules/projectstore/agents/planner.md +13 -1
  9. package/node_modules/projectstore/agents/reviewer.md +19 -2
  10. package/node_modules/projectstore/commands/adr.md +10 -0
  11. package/node_modules/projectstore/commands/bind.md +4 -3
  12. package/node_modules/projectstore/commands/concept.md +9 -0
  13. package/node_modules/projectstore/commands/doctor.md +17 -4
  14. package/node_modules/projectstore/commands/epic.md +10 -0
  15. package/node_modules/projectstore/commands/meeting.md +9 -0
  16. package/node_modules/projectstore/commands/research.md +9 -0
  17. package/node_modules/projectstore/commands/review.md +11 -7
  18. package/node_modules/projectstore/commands/runbook.md +9 -0
  19. package/node_modules/projectstore/commands/spec.md +10 -0
  20. package/node_modules/projectstore/commands/story.md +25 -1
  21. package/node_modules/projectstore/docs/contracts-and-tests.md +107 -0
  22. package/node_modules/projectstore/docs/extending.md +44 -5
  23. package/node_modules/projectstore/harnesses/claude-code.json +3 -3
  24. package/node_modules/projectstore/harnesses/codex.json +1 -1
  25. package/node_modules/projectstore/package.json +1 -1
  26. package/node_modules/projectstore/scaffold/guides/adr.md +42 -0
  27. package/node_modules/projectstore/scaffold/guides/concept.md +10 -0
  28. package/node_modules/projectstore/scaffold/guides/epic.md +36 -0
  29. package/node_modules/projectstore/scaffold/guides/meeting.md +11 -0
  30. package/node_modules/projectstore/scaffold/guides/research.md +16 -0
  31. package/node_modules/projectstore/scaffold/guides/runbook.md +12 -0
  32. package/node_modules/projectstore/scaffold/guides/spec.md +39 -0
  33. package/node_modules/projectstore/scaffold/guides/story.md +34 -0
  34. package/node_modules/projectstore/scripts/cli.mjs +55 -1
  35. package/node_modules/projectstore/scripts/configure-menu.mjs +2 -1
  36. package/node_modules/projectstore/scripts/configure.mjs +12 -2
  37. package/node_modules/projectstore/scripts/diff-refs.mjs +39 -0
  38. package/node_modules/projectstore/scripts/doctor.mjs +648 -33
  39. package/node_modules/projectstore/scripts/guides.mjs +217 -0
  40. package/node_modules/projectstore/scripts/harness.mjs +2 -0
  41. package/node_modules/projectstore/scripts/lib.mjs +163 -1
  42. package/node_modules/projectstore/scripts/mcp-server.mjs +11 -4
  43. package/node_modules/projectstore/scripts/mcp.mjs +30 -3
  44. package/node_modules/projectstore/scripts/read-verbs.mjs +59 -3
  45. package/node_modules/projectstore/scripts/scaffold.mjs +1 -1
  46. package/node_modules/projectstore/scripts/story-section.mjs +16 -1
  47. package/node_modules/projectstore/scripts/verbs.mjs +33 -1
  48. package/node_modules/projectstore/scripts/version-guard.mjs +5 -10
  49. package/node_modules/projectstore/skills/projectstore-peer-reviewer/SKILL.md +9 -3
  50. package/node_modules/projectstore/templates/de/spec.md.tmpl +9 -1
  51. package/node_modules/projectstore/templates/de/story.md.tmpl +1 -0
  52. package/node_modules/projectstore/templates/en/spec.md.tmpl +8 -1
  53. package/node_modules/projectstore/templates/en/story.md.tmpl +1 -0
  54. package/node_modules/projectstore/templates/es/spec.md.tmpl +9 -1
  55. package/node_modules/projectstore/templates/es/story.md.tmpl +1 -0
  56. package/node_modules/projectstore/templates/fr/spec.md.tmpl +9 -1
  57. package/node_modules/projectstore/templates/fr/story.md.tmpl +1 -0
  58. package/node_modules/projectstore/templates/ru/spec.md.tmpl +8 -1
  59. package/node_modules/projectstore/templates/ru/story.md.tmpl +1 -0
  60. package/node_modules/projectstore/templates/zh/spec.md.tmpl +8 -1
  61. package/node_modules/projectstore/templates/zh/story.md.tmpl +1 -0
  62. package/package.json +2 -2
  63. package/node_modules/projectstore/scaffold/checklists.json +0 -88
@@ -13,7 +13,9 @@
13
13
  // The SessionStart line counts level==="issue" only.
14
14
  //
15
15
  // CLI: node doctor.mjs [--install] [--vault] [--startup] [--json]
16
- // default = --install --vault. Exit code is always 0 (reporting tool).
16
+ // [--policy required[@<date>]]
17
+ // default = --install --vault. Exit code is always 0 (reporting tool),
18
+ // except 2 for a bad --policy, which writes nothing to stdout.
17
19
  // Without --json the findings are drawn by doctor-report.mjs, the
18
20
  // renderer the bin uses, in its plain layout.
19
21
 
@@ -36,10 +38,22 @@ import {
36
38
  statusLineIsOurs,
37
39
  statusLineIsOurWiring,
38
40
  isLegacyStory,
41
+ legacySince,
42
+ lifecycleGatesOn,
43
+ noSpecOf,
44
+ parseDryRunPolicy,
45
+ checklistItems,
46
+ linesOutsideFences,
47
+ isTestPath,
48
+ isSourcePath,
39
49
  sectionOf,
40
50
  indexHeaderRe,
41
51
  evidenceSuffixRe,
42
52
  storiesAttributionRe,
53
+ citationTokenRe,
54
+ contractNumberAscii,
55
+ CITATION_EXAMPLE_KEY,
56
+ CITATION_PREFILTER,
43
57
  slugIdentity,
44
58
  isLegacyNumberedId,
45
59
  storyMatchesEntry,
@@ -124,9 +138,10 @@ import { effortSpec } from "./model-spec.mjs";
124
138
  // story "The prompt surface asks the shell for a variable the host would have
125
139
  // substituted"; harness neutrality is unaffected, an absolute path carries no
126
140
  // brand, and --harness still carries the target.
127
- import { uncommittedProjectFiles, lastCommitMs } from "./diff-refs.mjs";
141
+ import { uncommittedProjectFiles, lastCommitMs, grepProjectLines } from "./diff-refs.mjs";
128
142
  import { resolveBinding } from "./worktree.mjs";
129
- import { missingScaffoldRequirements } from "./scaffold.mjs";
143
+ import { missingScaffoldRequirements, kindsOf } from "./scaffold.mjs";
144
+ import { GUIDE_NAME, guidesDir, parseGuide, resolveGuide } from "./guides.mjs";
130
145
 
131
146
  const AGENT_BLOCK_MARKER = new RegExp(AGENTS_BLOCK_OPEN_SRC, "g");
132
147
  // The provenance grammar's prefix, duplicated here on purpose: the startup
@@ -2177,20 +2192,8 @@ export function checkIndexes(cfg, layout, artifacts) {
2177
2192
  // definition shared with the link-graph extractor, so "not a link/checkbox
2178
2193
  // when inside code" means the same thing everywhere.
2179
2194
 
2180
- // RAW lines outside fenced blocks — for checks that must both MATCH (fence-
2181
- // immune) and REPORT the line verbatim (backticks intact in the message).
2182
- function linesOutsideFences(s) {
2183
- const out = [];
2184
- let fenced = false;
2185
- for (const line of s.split("\n")) {
2186
- if (/^\s*```/.test(line)) {
2187
- fenced = !fenced;
2188
- continue;
2189
- }
2190
- if (!fenced) out.push(line);
2191
- }
2192
- return out;
2193
- }
2195
+ // linesOutsideFences (RAW lines outside fenced blocks) lives in lib.mjs too,
2196
+ // shared with the guide reader.
2194
2197
 
2195
2198
  // Epic id of a story artifact, derived from the layout's epic folder path —
2196
2199
  // never from a hardcoded segment index (custom layouts may nest the folder).
@@ -2475,12 +2478,15 @@ export function checkSpecCoverage(artifacts, vaultCfg, layout = null) {
2475
2478
  if (isLegacyStory(story.fm, since)) continue;
2476
2479
  const ids = listOf(story.fm, "specs");
2477
2480
  if (!ids.length) {
2481
+ // A declared opt-out passes coverage (the spec policy ADR, Decision 12);
2482
+ // checkNoSpec judges the declaration itself.
2483
+ if (noSpecOf(story.fm).declared) continue;
2478
2484
  out.push(
2479
2485
  finding(
2480
2486
  "vault",
2481
2487
  "issue",
2482
2488
  "spec-coverage",
2483
- `Story is ${status} with no covering spec (spec_policy: required — every story needs a spec; ADR-007).`,
2489
+ `Story is ${status} with no covering spec and no no_spec reason (spec_policy: required — a story needs a spec, or a no_spec reason written at the plan gate).`,
2484
2490
  story.rel,
2485
2491
  ),
2486
2492
  );
@@ -2607,10 +2613,10 @@ export function checkSpecAcceptance(layout, artifacts, vaultCfg) {
2607
2613
  // ─── Lifecycle gates (PS-SPEC story-008) — behind lifecycle_gates=on ───
2608
2614
 
2609
2615
  export function checkLifecycleGates(artifacts, vaultCfg) {
2610
- const gates = String(vaultCfg.lifecycle_gates || "off").toLowerCase();
2611
- if (!["on", "true"].includes(gates)) return [];
2616
+ if (!lifecycleGatesOn(vaultCfg)) return [];
2612
2617
  const out = [];
2613
- const since = vaultCfg.spec_policy_since || null;
2618
+ // spec_policy_since, else gates_since (the spec policy ADR, Decision 18a).
2619
+ const since = legacySince(vaultCfg);
2614
2620
  const evidenceRe = evidenceSuffixRe();
2615
2621
 
2616
2622
  for (const story of artifacts.filter((a) => a.kind === "story")) {
@@ -2619,16 +2625,17 @@ export function checkLifecycleGates(artifacts, vaultCfg) {
2619
2625
 
2620
2626
  const acc = sectionOf(story.body, "acceptance");
2621
2627
  if (acc !== null) {
2622
- // Raw lines (fence-immune matching, verbatim reporting — backticks kept).
2623
- for (const line of linesOutsideFences(acc)) {
2624
- const m = line.match(/^\s*-\s*\[(x|X)\]\s*(.*)$/);
2625
- if (m && !evidenceRe.test(m[2])) {
2628
+ // Raw lines (fence-immune matching, verbatim reporting — backticks
2629
+ // kept), each item read with its wrapped continuation lines, so an
2630
+ // evidence suffix on the item's second line counts.
2631
+ for (const item of checklistItems(linesOutsideFences(acc))) {
2632
+ if (item.checked && !evidenceRe.test(item.text)) {
2626
2633
  out.push(
2627
2634
  finding(
2628
2635
  "vault",
2629
2636
  "warn",
2630
2637
  "evidence",
2631
- `Checked acceptance criterion carries no evidence suffix ("— evidence: <test | command | file:line>"): "${m[2].slice(0, 70)}".`,
2638
+ `Checked acceptance criterion carries no evidence suffix ("— evidence: <test | command | file:line>"): "${item.text.slice(0, 70)}".`,
2632
2639
  story.rel,
2633
2640
  ),
2634
2641
  );
@@ -2675,6 +2682,487 @@ export function checkLifecycleGates(artifacts, vaultCfg) {
2675
2682
  return out;
2676
2683
  }
2677
2684
 
2685
+ // ─── Contract scenarios and citations (the spec policy ADR, Part A) ───
2686
+
2687
+ // A spec's Behavioral contracts as data. A contract is a top-level numbered
2688
+ // item (`4.`, `4′.`, `0.`) in the contracts section; its first nested
2689
+ // numbered level is its steps; deeper levels belong to their parent. HTML
2690
+ // comments are stripped first, so a template's example `1.` inside a comment
2691
+ // is not a contract. Scenario items are `- WHEN|GIVEN|AND|THEN …` list items
2692
+ // under a contract; the `(verified: live|manual)` marker is looked for in the
2693
+ // contract's first paragraph, which a wrapped bold heading may span.
2694
+ export function parseSpecContracts(spec) {
2695
+ const sec = sectionOf(spec.body || "", "spec_contracts");
2696
+ if (sec === null) return null;
2697
+ const lines = linesOutsideFences(sec.replace(/<!--[\s\S]*?-->/g, ""));
2698
+ const contracts = [];
2699
+ let cur = null;
2700
+ let inFirstPara = false;
2701
+ for (const line of lines) {
2702
+ const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
2703
+ if (top) {
2704
+ cur = {
2705
+ n: contractNumberAscii(top[1]),
2706
+ steps: new Set(),
2707
+ stepIndent: null,
2708
+ scenarios: [],
2709
+ marker: null,
2710
+ first: line,
2711
+ };
2712
+ contracts.push(cur);
2713
+ inFirstPara = true;
2714
+ continue;
2715
+ }
2716
+ if (!cur) continue;
2717
+ if (/^\s*$/.test(line)) {
2718
+ inFirstPara = false;
2719
+ continue;
2720
+ }
2721
+ if (inFirstPara) cur.first += " " + line.trim();
2722
+ const step = line.match(/^(\s+)(\d+[′″']*)\.(\s|$)/);
2723
+ if (step) {
2724
+ if (cur.stepIndent === null) cur.stepIndent = step[1].length;
2725
+ if (step[1].length === cur.stepIndent) cur.steps.add(contractNumberAscii(step[2]));
2726
+ continue;
2727
+ }
2728
+ const sc = line.match(/^\s*-\s+(WHEN|GIVEN|AND|THEN)\b/);
2729
+ if (sc) cur.scenarios.push(line.trim());
2730
+ }
2731
+ for (const c of contracts) {
2732
+ const mk = c.first.match(/\(verified\s*[::]\s*(live|manual)\)/);
2733
+ c.marker = mk ? mk[1] : null;
2734
+ delete c.first;
2735
+ delete c.stepIndent;
2736
+ }
2737
+ return contracts;
2738
+ }
2739
+
2740
+ // Key → spec, by frontmatter id and alias, exact and case-sensitive. Not
2741
+ // buildSpecResolver: its filename fallback is lower-cased, and a citation
2742
+ // token resolves only to what a spec declares.
2743
+ function citationKeys(artifacts) {
2744
+ const keys = new Map();
2745
+ for (const s of artifacts.filter((a) => a.kind === "spec")) {
2746
+ for (const k of [String(s.fm.id || ""), String(s.fm.alias || "")]) {
2747
+ if (k && k !== "null" && !keys.has(k)) keys.set(k, s);
2748
+ }
2749
+ }
2750
+ return keys;
2751
+ }
2752
+
2753
+ // Alias rules (Decision 5): unique across specs, never another spec's id,
2754
+ // never the reserved example key. An alias is frozen like a slug.
2755
+ export function checkSpecAliases(artifacts) {
2756
+ const out = [];
2757
+ const specs = artifacts.filter((a) => a.kind === "spec");
2758
+ const ids = new Map(specs.map((s) => [String(s.fm.id || ""), s]));
2759
+ const seen = new Map();
2760
+ for (const s of specs) {
2761
+ const id = String(s.fm.id || "");
2762
+ if (id === CITATION_EXAMPLE_KEY) {
2763
+ out.push(
2764
+ finding(
2765
+ "vault",
2766
+ "issue",
2767
+ "spec-alias",
2768
+ `Spec id "${id}" is the reserved citation key — docs use it for tokens that never resolve.`,
2769
+ s.rel,
2770
+ ),
2771
+ );
2772
+ }
2773
+ const alias = s.fm.alias && s.fm.alias !== "null" ? String(s.fm.alias) : null;
2774
+ if (!alias) continue;
2775
+ if (alias === CITATION_EXAMPLE_KEY) {
2776
+ out.push(
2777
+ finding(
2778
+ "vault",
2779
+ "issue",
2780
+ "spec-alias",
2781
+ `Spec alias "${alias}" is the reserved citation key — pick another.`,
2782
+ s.rel,
2783
+ ),
2784
+ );
2785
+ } else if (ids.has(alias) && ids.get(alias) !== s) {
2786
+ out.push(
2787
+ finding(
2788
+ "vault",
2789
+ "issue",
2790
+ "spec-alias",
2791
+ `Spec alias "${alias}" is another spec's id (${ids.get(alias).rel}) — a citation would be ambiguous.`,
2792
+ s.rel,
2793
+ ),
2794
+ );
2795
+ } else if (seen.has(alias)) {
2796
+ out.push(
2797
+ finding(
2798
+ "vault",
2799
+ "issue",
2800
+ "spec-alias",
2801
+ `Spec alias "${alias}" is also the alias of ${seen.get(alias).rel} — a citation would be ambiguous.`,
2802
+ s.rel,
2803
+ ),
2804
+ );
2805
+ }
2806
+ if (!seen.has(alias)) seen.set(alias, s);
2807
+ }
2808
+ return out;
2809
+ }
2810
+
2811
+ // Scenario shape (Decision 3): a contract's scenario items need a WHEN (or
2812
+ // GIVEN) and a THEN. That is the only reading of scenarios.
2813
+ export function checkScenarioShape(artifacts) {
2814
+ const out = [];
2815
+ for (const s of artifacts.filter((a) => a.kind === "spec")) {
2816
+ for (const c of parseSpecContracts(s) || []) {
2817
+ if (!c.scenarios.length) continue;
2818
+ const when = c.scenarios.some((l) => /^-\s+(WHEN|GIVEN)\b/.test(l));
2819
+ const then = c.scenarios.some((l) => /^-\s+THEN\b/.test(l));
2820
+ if (!when || !then) {
2821
+ out.push(
2822
+ finding(
2823
+ "vault",
2824
+ "info",
2825
+ "scenario-shape",
2826
+ `Contract ${c.n}'s scenario has no ${!when ? "WHEN (or GIVEN)" : "THEN"} step.`,
2827
+ s.rel,
2828
+ ),
2829
+ );
2830
+ }
2831
+ }
2832
+ }
2833
+ return out;
2834
+ }
2835
+
2836
+ // The one scan per doctor run: every citation-shaped line in the bound
2837
+ // project, skipping the vault when it sits inside it. null = no active spec
2838
+ // with contracts, so nothing was scanned (and git never ran).
2839
+ export function scanCitations(cfg, artifacts, proj, grep = grepProjectLines) {
2840
+ const active = artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active");
2841
+ if (!active.some((s) => (parseSpecContracts(s) || []).length)) return null;
2842
+ const exclude = [];
2843
+ try {
2844
+ const p = realpathSync.native(proj);
2845
+ const v = realpathSync.native(cfg.vault_path);
2846
+ const rel = relative(p, v);
2847
+ if (rel && !rel.startsWith("..") && !rel.startsWith("/")) exclude.push(rel);
2848
+ } catch {}
2849
+ const r = grep(proj, CITATION_PREFILTER, { exclude });
2850
+ const tokens = [];
2851
+ // A token written with the spec's own primes (`#4′`) is not a citation; it
2852
+ // is kept, flagged, so the check can say "write it in ASCII" instead of
2853
+ // dropping it silently.
2854
+ const typographic = /(?<!\[)\[([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+[′″']*(?:\/\d+[′″']*)?)\](?![(\]])/g;
2855
+ for (const { file, line, text } of r.lines) {
2856
+ for (const m of text.matchAll(citationTokenRe())) tokens.push({ key: m[1], n: m[2], file, line });
2857
+ for (const m of text.matchAll(typographic)) {
2858
+ if (/[′″]/.test(m[2])) tokens.push({ key: m[1], n: m[2], file, line, typographic: true });
2859
+ }
2860
+ }
2861
+ return { status: r.status, reason: r.reason || null, tokens, checkout: basename(proj) };
2862
+ }
2863
+
2864
+ // Unknown tokens and coverage (Decisions 8 and 9). Coverage is quiet: a spec
2865
+ // nothing cites gets one line; the uncited list appears only once a spec has
2866
+ // a citation, or sets `coverage: report`. A marked contract is not counted,
2867
+ // and a cited step does not cover its parent.
2868
+ export function checkContractCitations(artifacts, scan) {
2869
+ if (!scan) return [];
2870
+ if (scan.status === "no-git") {
2871
+ return [
2872
+ finding(
2873
+ "vault",
2874
+ "info",
2875
+ "contract-coverage",
2876
+ "Contract coverage not checked — the bound project is not a git repository.",
2877
+ ),
2878
+ ];
2879
+ }
2880
+ if (scan.status === "unknown") {
2881
+ return [
2882
+ finding(
2883
+ "vault",
2884
+ "info",
2885
+ "contract-coverage",
2886
+ `Contract coverage not checked — ${scan.reason || "the citation scan did not finish"}.`,
2887
+ ),
2888
+ ];
2889
+ }
2890
+ const out = [];
2891
+ const keys = citationKeys(artifacts);
2892
+ const contractsOf = new Map();
2893
+ const cited = new Map();
2894
+ const citedIn = new Map();
2895
+ for (const t of scan.tokens) {
2896
+ if (t.key === CITATION_EXAMPLE_KEY) continue;
2897
+ const where = `${t.file}:${t.line}`;
2898
+ if (t.typographic) {
2899
+ out.push(
2900
+ finding(
2901
+ "vault",
2902
+ "warn",
2903
+ "citation-unknown",
2904
+ `[${t.key}#${t.n}] uses typographic primes — write the number in ASCII: [${t.key}#${contractNumberAscii(t.n)}].`,
2905
+ where,
2906
+ ),
2907
+ );
2908
+ continue;
2909
+ }
2910
+ const spec = keys.get(t.key);
2911
+ if (!spec) {
2912
+ out.push(
2913
+ finding(
2914
+ "vault",
2915
+ "warn",
2916
+ "citation-unknown",
2917
+ `[${t.key}#${t.n}] names no spec id or alias (a typo, or a renamed alias?).`,
2918
+ where,
2919
+ ),
2920
+ );
2921
+ continue;
2922
+ }
2923
+ if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
2924
+ const [top, step] = t.n.split("/");
2925
+ const c = contractsOf.get(spec).find((x) => x.n === top);
2926
+ if (!c || (step && !c.steps.has(step))) {
2927
+ out.push(
2928
+ finding("vault", "warn", "citation-unknown", `[${t.key}#${t.n}] — ${spec.rel} has no contract ${t.n}.`, where),
2929
+ );
2930
+ continue;
2931
+ }
2932
+ if (String(spec.fm.status || "") === "superseded") {
2933
+ out.push(
2934
+ finding(
2935
+ "vault",
2936
+ "info",
2937
+ "citation-superseded",
2938
+ `[${t.key}#${t.n}] cites a superseded spec (${spec.rel}) — move it to the successor.`,
2939
+ where,
2940
+ ),
2941
+ );
2942
+ }
2943
+ if (!step) {
2944
+ if (!cited.has(spec)) cited.set(spec, new Set());
2945
+ cited.get(spec).add(top);
2946
+ }
2947
+ if (!citedIn.has(spec)) citedIn.set(spec, new Set());
2948
+ citedIn.get(spec).add(t.file);
2949
+ }
2950
+ // `--json` carries the files that cite each spec, so a valid token in a doc
2951
+ // (which counts as coverage) is easy to find (Decision 8).
2952
+ const withCites = (f, s) => {
2953
+ if (citedIn.has(s)) f.cites = [...citedIn.get(s)].sort();
2954
+ return f;
2955
+ };
2956
+ for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
2957
+ const contracts = contractsOf.get(s) || parseSpecContracts(s) || [];
2958
+ if (!contracts.length) continue;
2959
+ const got = cited.get(s) || new Set();
2960
+ if (!got.size && String(s.fm.coverage || "") !== "report") {
2961
+ out.push(
2962
+ finding(
2963
+ "vault",
2964
+ "info",
2965
+ "contract-coverage",
2966
+ `${contracts.length} contracts, 0 cited (checkout ${scan.checkout}).`,
2967
+ s.rel,
2968
+ ),
2969
+ );
2970
+ continue;
2971
+ }
2972
+ const open = contracts.filter((c) => !c.marker && !got.has(c.n)).map((c) => c.n);
2973
+ if (open.length) {
2974
+ out.push(
2975
+ withCites(
2976
+ finding(
2977
+ "vault",
2978
+ "info",
2979
+ "contract-coverage",
2980
+ `${open.length} of ${contracts.length} contracts uncited (checkout ${scan.checkout}): ${open.join(", ")}.`,
2981
+ s.rel,
2982
+ ),
2983
+ s,
2984
+ ),
2985
+ );
2986
+ }
2987
+ }
2988
+ return out;
2989
+ }
2990
+
2991
+ // Evidence that cites a contract (Decision 10), behind lifecycle_gates: on.
2992
+ // A token not found in the project is a warn for a story in progress or in
2993
+ // review, and for a done story that is not legacy. Free-text evidence is
2994
+ // never checked, and doctor never runs a test.
2995
+ export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
2996
+ if (!lifecycleGatesOn(vaultCfg) || !scan || scan.status !== "ok") return [];
2997
+ const since = legacySince(vaultCfg);
2998
+ const present = new Set(scan.tokens.map((t) => `${t.key}#${t.n}`));
2999
+ const evidenceRe = evidenceSuffixRe();
3000
+ const out = [];
3001
+ for (const story of artifacts.filter((a) => a.kind === "story")) {
3002
+ const st = String(story.fm.status || "").toLowerCase();
3003
+ if (!["in-progress", "in_progress", "review", "done"].includes(st)) continue;
3004
+ if (st === "done" && isLegacyStory(story.fm, since)) continue;
3005
+ const acc = sectionOf(story.body, "acceptance");
3006
+ if (acc === null) continue;
3007
+ for (const item of checklistItems(linesOutsideFences(acc))) {
3008
+ if (!item.checked) continue;
3009
+ const at = item.text.search(evidenceRe);
3010
+ if (at === -1) continue;
3011
+ for (const t of item.text.slice(at).matchAll(citationTokenRe())) {
3012
+ if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`)) continue;
3013
+ out.push(
3014
+ finding(
3015
+ "vault",
3016
+ "warn",
3017
+ "evidence-citation",
3018
+ `Evidence cites [${t[1]}#${t[2]}], which no file in checkout ${scan.checkout} carries (a renamed or removed test, or an older branch?).`,
3019
+ story.rel,
3020
+ ),
3021
+ );
3022
+ }
3023
+ }
3024
+ }
3025
+ return out;
3026
+ }
3027
+
3028
+ // ─── The declared opt-out from a spec (the spec policy ADR, Part B) ───
3029
+
3030
+ // How much source a story's code_refs name, for the size and ratio checks
3031
+ // (Decision 15): a directory or a glob weighs three; a file weighs one; a
3032
+ // test, or a path isSourcePath ignores, weighs nothing.
3033
+ export function sourceWeight(fm, proj, vaultPath) {
3034
+ let w = 0;
3035
+ for (const ref of listOf(fm, "code_refs")) {
3036
+ const r = String(ref).replace(/^\.\//, "");
3037
+ if (!r || isTestPath(r)) continue;
3038
+ const base = r.replace(/[*?[{].*$/, "").replace(/\/$/, "");
3039
+ if (!isSourcePath(join(proj, base || r), proj, vaultPath)) continue;
3040
+ let dir = /\/$/.test(r) || /[*?[{]/.test(r);
3041
+ if (!dir) {
3042
+ try {
3043
+ dir = statSync(join(proj, r)).isDirectory();
3044
+ } catch {}
3045
+ }
3046
+ w += dir ? 3 : 1;
3047
+ }
3048
+ return w;
3049
+ }
3050
+
3051
+ // The opt-out's own checks, under every spec policy, on stories in scope that
3052
+ // are not legacy (Decisions 13 and 15): an empty reason or no_spec beside
3053
+ // specs: is an issue; a story whose code_refs weigh three or more is a warn.
3054
+ export function checkNoSpec(artifacts, vaultCfg, proj, vaultPath) {
3055
+ const out = [];
3056
+ const since = legacySince(vaultCfg);
3057
+ for (const story of artifacts.filter((a) => a.kind === "story")) {
3058
+ const ns = noSpecOf(story.fm);
3059
+ if (!ns.declared || !specScopeStatus(story.fm) || isLegacyStory(story.fm, since)) continue;
3060
+ if (!ns.reason) {
3061
+ out.push(
3062
+ finding("vault", "issue", "no-spec", "no_spec has no reason — say why this story needs no spec.", story.rel),
3063
+ );
3064
+ }
3065
+ if (listOf(story.fm, "specs").length) {
3066
+ out.push(
3067
+ finding(
3068
+ "vault",
3069
+ "issue",
3070
+ "no-spec",
3071
+ "The story lists specs and also declares no_spec — keep one: the spec, or the reason.",
3072
+ story.rel,
3073
+ ),
3074
+ );
3075
+ }
3076
+ if (sourceWeight(story.fm, proj, vaultPath) >= 3) {
3077
+ out.push(
3078
+ finding(
3079
+ "vault",
3080
+ "warn",
3081
+ "no-spec",
3082
+ "A no_spec story whose code_refs name three or more source files — AGENTS.md wants a spec for work across several files. Cover it with a spec and remove no_spec.",
3083
+ story.rel,
3084
+ ),
3085
+ );
3086
+ }
3087
+ }
3088
+ return out;
3089
+ }
3090
+
3091
+ // Opt-outs against covered stories, among code stories only (Decision 16).
3092
+ // One info when any opt-out exists; a warn once the window holds five stories
3093
+ // and the opt-outs outnumber the covered ones. The window is every in-scope
3094
+ // code story that is not legacy, stories with neither field included; with
3095
+ // no date, done stories are legacy and only open ones are in it.
3096
+ export function checkNoSpecShare(artifacts, vaultCfg, proj, vaultPath) {
3097
+ const since = legacySince(vaultCfg);
3098
+ let window = 0;
3099
+ let optedOut = 0;
3100
+ let covered = 0;
3101
+ const perEpic = {};
3102
+ for (const story of artifacts.filter((a) => a.kind === "story")) {
3103
+ if (!specScopeStatus(story.fm) || isLegacyStory(story.fm, since)) continue;
3104
+ if (sourceWeight(story.fm, proj, vaultPath) < 1) continue;
3105
+ window++;
3106
+ const epic = String(story.fm.epic || "");
3107
+ perEpic[epic] = perEpic[epic] || { no_spec: 0, specs: 0 };
3108
+ if (noSpecOf(story.fm).declared) {
3109
+ optedOut++;
3110
+ perEpic[epic].no_spec++;
3111
+ } else if (listOf(story.fm, "specs").length) {
3112
+ covered++;
3113
+ perEpic[epic].specs++;
3114
+ }
3115
+ }
3116
+ if (!optedOut) return [];
3117
+ const warn = window >= 5 && optedOut > covered;
3118
+ const f = finding(
3119
+ "vault",
3120
+ warn ? "warn" : "info",
3121
+ "no-spec-share",
3122
+ `${optedOut} code ${optedOut === 1 ? "story opts" : "stories opt"} out of a spec, against ${covered} covered by one${warn ? " — opting out has become the norm for code work" : ""}.`,
3123
+ );
3124
+ f.per_epic = perEpic;
3125
+ return [f];
3126
+ }
3127
+
3128
+ // An accepted ADR past its review_by (Decision 17), until it is reviewed on
3129
+ // or after that date.
3130
+ export function checkReviewBy(artifacts, now = new Date().toISOString()) {
3131
+ const out = [];
3132
+ const today = String(now).slice(0, 10);
3133
+ for (const a of artifacts.filter((x) => x.kind === "adr")) {
3134
+ const by = a.fm.review_by && a.fm.review_by !== "null" ? String(a.fm.review_by).slice(0, 10) : null;
3135
+ if (!by || String(a.fm.status || "") !== "accepted" || by >= today) continue;
3136
+ const at = a.fm.reviewed_at && a.fm.reviewed_at !== "null" ? String(a.fm.reviewed_at).slice(0, 10) : "";
3137
+ if (String(a.fm.review_status || "") === "reviewed" && at >= by) continue;
3138
+ out.push(
3139
+ finding(
3140
+ "vault",
3141
+ "info",
3142
+ "review-by",
3143
+ `This decision was due for review on ${by}. Review it, then set review_status: reviewed and reviewed_at, or move review_by.`,
3144
+ a.rel,
3145
+ ),
3146
+ );
3147
+ }
3148
+ return out;
3149
+ }
3150
+
3151
+ // A vault whose gates are on but that has no date to count from: every done
3152
+ // story is legacy, so the lifecycle checks never reach one (Decision 18a).
3153
+ export function checkGatesStamp(vaultCfg, proj) {
3154
+ if (!lifecycleGatesOn(vaultCfg)) return [];
3155
+ if (vaultCfg.spec_policy_since || vaultCfg.gates_since) return [];
3156
+ return [
3157
+ finding(
3158
+ "vault",
3159
+ "info",
3160
+ "gates-since",
3161
+ `The lifecycle gates are on, but the vault has no date to count from, so no done story is checked. Stamp it ${fromTerminalIn(proj)} (stories closed after now are checked from then on):\n${packageCommand([], "configure", { args: "--set lifecycle_gates=on" })}`,
3162
+ ),
3163
+ ];
3164
+ }
3165
+
2678
3166
  // Suggestion for existing binds: specs exist but no vault policy declared.
2679
3167
  export function checkVaultPolicy(cfg, layout, artifacts, vaultCfg) {
2680
3168
  const out = [];
@@ -2718,14 +3206,102 @@ export function walkVaultFiles(vault) {
2718
3206
  } catch {
2719
3207
  continue;
2720
3208
  }
2721
- if (st.isDirectory()) walk(p, relDir ? `${relDir}/${n}` : n);
2722
- else if (n.endsWith(".md")) files.push({ rel: relDir ? `${relDir}/${n}` : n, name: n });
3209
+ // The vault-root guides/ holds authoring guides, not artifacts (SPEC-001
3210
+ // contract 12): no name collision, no link target, no stale view, no
3211
+ // search hit. A deeper folder of that name is an ordinary folder.
3212
+ if (st.isDirectory()) {
3213
+ if (relDir === "" && n === LAYOUT.guides) continue;
3214
+ walk(p, relDir ? `${relDir}/${n}` : n);
3215
+ } else if (n.endsWith(".md")) files.push({ rel: relDir ? `${relDir}/${n}` : n, name: n });
2723
3216
  }
2724
3217
  };
2725
3218
  walk(vault, "");
2726
3219
  return files;
2727
3220
  }
2728
3221
 
3222
+ // The vault's guide overrides (SPEC-001 contract 12; the authoring-guides
3223
+ // ADR, decision 5): guide-shape when one does not parse, guide-unknown when
3224
+ // its base kind is not the layout's (or story), guide-stale when the package
3225
+ // default moved past its based_on. Never throws; nothing when guides/ is absent.
3226
+ export function checkGuides(vault, layout, { proj = null, root = pluginRoot() } = {}) {
3227
+ const dir = guidesDir(vault);
3228
+ let names;
3229
+ try {
3230
+ if (!statSync(dir).isDirectory()) return [];
3231
+ names = readdirSync(dir);
3232
+ } catch {
3233
+ return [];
3234
+ }
3235
+ const kinds = new Set([...kindsOf(layout || {}), "story"]);
3236
+ const out = [];
3237
+ for (const f of names.sort()) {
3238
+ if (f.startsWith(".") || !f.endsWith(".md") || f === "README.md") continue;
3239
+ const p = join(dir, f);
3240
+ try {
3241
+ if (!statSync(p).isFile()) continue;
3242
+ } catch {
3243
+ continue;
3244
+ }
3245
+ const name = f.slice(0, -3);
3246
+ const rel = `${LAYOUT.guides}/${f}`;
3247
+ const base = name.split(".")[0];
3248
+ if (!kinds.has(base))
3249
+ out.push(
3250
+ finding(
3251
+ "vault",
3252
+ "warn",
3253
+ "guide-unknown",
3254
+ `A guide for "${name}", but "${base}" is not a kind of this vault's layout; no command or critic reads it.`,
3255
+ rel,
3256
+ ),
3257
+ );
3258
+ let text;
3259
+ try {
3260
+ text = readFileSync(p, "utf8").replace(/\r\n/g, "\n");
3261
+ } catch (e) {
3262
+ out.push(
3263
+ finding(
3264
+ "vault",
3265
+ "warn",
3266
+ "guide-shape",
3267
+ `The guide cannot be read (${e.code || "error"}); the package default is used.`,
3268
+ rel,
3269
+ ),
3270
+ );
3271
+ continue;
3272
+ }
3273
+ const g = GUIDE_NAME.test(name)
3274
+ ? parseGuide(text, name)
3275
+ : { ok: false, reason: "the file name is not a guide name" };
3276
+ if (!g.ok) {
3277
+ out.push(
3278
+ finding(
3279
+ "vault",
3280
+ "warn",
3281
+ "guide-shape",
3282
+ `The guide does not parse (${g.reason}), so readers fall back to the package default. A guide needs frontmatter whose guide_for is its file name, and a ## Must with at least one item.`,
3283
+ rel,
3284
+ ),
3285
+ );
3286
+ continue;
3287
+ }
3288
+ const basedOn = Number(g.fm.based_on);
3289
+ if (g.fm.based_on == null || !Number.isInteger(basedOn)) continue;
3290
+ const pkg = resolveGuide(name, { root, source: "package" });
3291
+ if (pkg.resolved !== name || !Number.isInteger(pkg.guide_version) || pkg.guide_version <= basedOn) continue;
3292
+ out.push(
3293
+ finding(
3294
+ "vault",
3295
+ "info",
3296
+ "guide-stale",
3297
+ `This guide was made from the package's version ${basedOn}; the package's guide is now version ${pkg.guide_version}. Read the new default ${fromTerminalIn(proj)}, and merge what you want by hand:\n${packageCommand([], "guide", { args: `${name} --source package` })}`,
3298
+ rel,
3299
+ ),
3300
+ );
3301
+ }
3302
+ return out;
3303
+ }
3304
+
2729
3305
  // Body links resolved through the ONE shared resolver (spec:
2730
3306
  // vault-link-graph-derived-view-and-shared-link-resolver): dead stays an
2731
3307
  // issue, ambiguous (multiple node candidates — invisible to the old
@@ -3237,7 +3813,10 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
3237
3813
  return foldIntoMove(out);
3238
3814
  }
3239
3815
 
3240
- export function runVaultChecks(cfg) {
3816
+ export function runVaultChecks(
3817
+ cfg,
3818
+ { proj = projectRoot(), grep = grepProjectLines, policy = null, now = new Date().toISOString() } = {},
3819
+ ) {
3241
3820
  let layout;
3242
3821
  try {
3243
3822
  layout = loadLayout(cfg.layout);
@@ -3247,8 +3826,19 @@ export function runVaultChecks(cfg) {
3247
3826
  const artifacts = scanArtifacts(cfg, layout);
3248
3827
  // Vault-side policy read ONCE (ADR-007 Decision 4): spec gates and lifecycle
3249
3828
  // gates key off <vault>/.projectstore.json, never the machine-local config.
3250
- const vaultCfg = readVaultConfig(cfg.vault_path);
3829
+ // A dry run (`--policy`) overlays it in memory and writes nothing.
3830
+ const vaultCfg = { ...readVaultConfig(cfg.vault_path), ...(policy || {}) };
3251
3831
  const findings = [...checkKanbanSync(cfg), ...checkIndexes(cfg, layout, artifacts)];
3832
+ if (policy) {
3833
+ findings.push(
3834
+ finding(
3835
+ "vault",
3836
+ "info",
3837
+ "dry-run",
3838
+ `Dry run: the vault is evaluated as spec_policy: required since ${policy.spec_policy_since}. Nothing was written; the vault's own policy is unchanged.`,
3839
+ ),
3840
+ );
3841
+ }
3252
3842
  // Registry-dependent checks: a missing/corrupt scaffold/headings.json must
3253
3843
  // become a finding, never a crash that swallows the whole report.
3254
3844
  const guarded = [
@@ -3258,6 +3848,12 @@ export function runVaultChecks(cfg) {
3258
3848
  () => checkSpecCoverage(artifacts, vaultCfg, layout),
3259
3849
  () => checkSpecAcceptance(layout, artifacts, vaultCfg),
3260
3850
  () => checkLifecycleGates(artifacts, vaultCfg),
3851
+ () => checkSpecAliases(artifacts),
3852
+ () => checkScenarioShape(artifacts),
3853
+ () => {
3854
+ const scan = scanCitations(cfg, artifacts, proj, grep);
3855
+ return [...checkContractCitations(artifacts, scan), ...checkEvidenceCitations(artifacts, vaultCfg, scan)];
3856
+ },
3261
3857
  ];
3262
3858
  for (const step of guarded) {
3263
3859
  try {
@@ -3274,8 +3870,13 @@ export function runVaultChecks(cfg) {
3274
3870
  ...checkArtifactIdentity(layout, vaultFiles, artifacts),
3275
3871
  ...checkArtifactNames(vaultFiles),
3276
3872
  ...checkExternalRefsForm(artifacts),
3277
- ...checkCodeRefs(artifacts, projectRoot()),
3278
- ...checkWorkWithoutStory(cfg, projectRoot()),
3873
+ ...checkCodeRefs(artifacts, proj),
3874
+ ...checkNoSpec(artifacts, vaultCfg, proj, cfg.vault_path),
3875
+ ...checkNoSpecShare(artifacts, vaultCfg, proj, cfg.vault_path),
3876
+ ...checkReviewBy(artifacts, now),
3877
+ ...checkGatesStamp(vaultCfg, proj),
3878
+ ...checkGuides(cfg.vault_path, layout, { proj }),
3879
+ ...checkWorkWithoutStory(cfg, proj),
3279
3880
  ...checkCodeMap(cfg),
3280
3881
  ...checkGraph(cfg),
3281
3882
  );
@@ -3345,6 +3946,20 @@ async function main() {
3345
3946
  install = true;
3346
3947
  vault = true;
3347
3948
  }
3949
+ // `--policy required[@<date>]`: a dry run of the vault section as if the
3950
+ // spec policy were required (the spec policy ADR, Decision 18). Read-only.
3951
+ let policy = null;
3952
+ const pi = args.indexOf("--policy");
3953
+ if (pi !== -1) {
3954
+ const parsed = parseDryRunPolicy(args[pi + 1]);
3955
+ const why = parsed.error || (!vault ? "--policy applies to the vault section only" : null);
3956
+ if (why) {
3957
+ process.stderr.write(`doctor: ${why}\n`);
3958
+ process.exitCode = 2;
3959
+ return;
3960
+ }
3961
+ policy = parsed.policy;
3962
+ }
3348
3963
 
3349
3964
  const cfg = readConfig();
3350
3965
  const proj = projectRoot();
@@ -3363,7 +3978,7 @@ async function main() {
3363
3978
  }
3364
3979
  if (vault && cfg && cfg.vault_path && existsSync(cfg.vault_path)) {
3365
3980
  groups.push("vault");
3366
- findings.push(...runVaultChecks(cfg));
3981
+ findings.push(...runVaultChecks(cfg, { proj, policy }));
3367
3982
  } else if (vault) {
3368
3983
  groups.push("vault");
3369
3984
  findings.push(finding("vault", "info", "vault", "Vault checks skipped — no usable vault (see install issues)."));