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.
- package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
- package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
- package/node_modules/projectstore/.mcp.json +1 -5
- package/node_modules/projectstore/README.md +6 -5
- package/node_modules/projectstore/agents/archaeologist.md +1 -1
- package/node_modules/projectstore/agents/critic.md +26 -3
- package/node_modules/projectstore/agents/librarian.md +1 -1
- package/node_modules/projectstore/agents/planner.md +13 -1
- package/node_modules/projectstore/agents/reviewer.md +19 -2
- package/node_modules/projectstore/commands/adr.md +10 -0
- package/node_modules/projectstore/commands/bind.md +4 -3
- package/node_modules/projectstore/commands/concept.md +9 -0
- package/node_modules/projectstore/commands/doctor.md +17 -4
- package/node_modules/projectstore/commands/epic.md +10 -0
- package/node_modules/projectstore/commands/meeting.md +9 -0
- package/node_modules/projectstore/commands/research.md +9 -0
- package/node_modules/projectstore/commands/review.md +11 -7
- package/node_modules/projectstore/commands/runbook.md +9 -0
- package/node_modules/projectstore/commands/spec.md +10 -0
- package/node_modules/projectstore/commands/story.md +25 -1
- package/node_modules/projectstore/docs/contracts-and-tests.md +107 -0
- package/node_modules/projectstore/docs/extending.md +44 -5
- package/node_modules/projectstore/harnesses/claude-code.json +3 -3
- package/node_modules/projectstore/harnesses/codex.json +1 -1
- package/node_modules/projectstore/package.json +1 -1
- package/node_modules/projectstore/scaffold/guides/adr.md +42 -0
- package/node_modules/projectstore/scaffold/guides/concept.md +10 -0
- package/node_modules/projectstore/scaffold/guides/epic.md +36 -0
- package/node_modules/projectstore/scaffold/guides/meeting.md +11 -0
- package/node_modules/projectstore/scaffold/guides/research.md +16 -0
- package/node_modules/projectstore/scaffold/guides/runbook.md +12 -0
- package/node_modules/projectstore/scaffold/guides/spec.md +39 -0
- package/node_modules/projectstore/scaffold/guides/story.md +34 -0
- package/node_modules/projectstore/scripts/cli.mjs +55 -1
- package/node_modules/projectstore/scripts/configure-menu.mjs +2 -1
- package/node_modules/projectstore/scripts/configure.mjs +12 -2
- package/node_modules/projectstore/scripts/diff-refs.mjs +39 -0
- package/node_modules/projectstore/scripts/doctor.mjs +648 -33
- package/node_modules/projectstore/scripts/guides.mjs +217 -0
- package/node_modules/projectstore/scripts/harness.mjs +2 -0
- package/node_modules/projectstore/scripts/lib.mjs +163 -1
- package/node_modules/projectstore/scripts/mcp-server.mjs +11 -4
- package/node_modules/projectstore/scripts/mcp.mjs +30 -3
- package/node_modules/projectstore/scripts/read-verbs.mjs +59 -3
- package/node_modules/projectstore/scripts/scaffold.mjs +1 -1
- package/node_modules/projectstore/scripts/story-section.mjs +16 -1
- package/node_modules/projectstore/scripts/verbs.mjs +33 -1
- package/node_modules/projectstore/scripts/version-guard.mjs +5 -10
- package/node_modules/projectstore/skills/projectstore-peer-reviewer/SKILL.md +9 -3
- package/node_modules/projectstore/templates/de/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/de/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/en/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/en/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/es/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/es/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/fr/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/fr/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/ru/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/ru/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/zh/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/zh/story.md.tmpl +1 -0
- package/package.json +2 -2
- 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
|
-
//
|
|
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
|
|
2181
|
-
//
|
|
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 —
|
|
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
|
-
|
|
2611
|
-
if (!["on", "true"].includes(gates)) return [];
|
|
2616
|
+
if (!lifecycleGatesOn(vaultCfg)) return [];
|
|
2612
2617
|
const out = [];
|
|
2613
|
-
|
|
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
|
|
2623
|
-
|
|
2624
|
-
|
|
2625
|
-
|
|
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>"): "${
|
|
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
|
-
|
|
2722
|
-
|
|
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(
|
|
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
|
-
|
|
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,
|
|
3278
|
-
...
|
|
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)."));
|