projectstore-claude 0.30.14 → 0.30.16
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/README.md +5 -0
- package/node_modules/projectstore/agents/planner.md +4 -1
- package/node_modules/projectstore/agents/reviewer.md +77 -2
- package/node_modules/projectstore/commands/doctor.md +11 -0
- package/node_modules/projectstore/commands/graph.md +5 -1
- package/node_modules/projectstore/commands/story.md +4 -1
- package/node_modules/projectstore/docs/contracts-and-tests.md +94 -2
- package/node_modules/projectstore/docs/extending.md +10 -0
- package/node_modules/projectstore/package.json +1 -1
- package/node_modules/projectstore/scaffold/guides/spec.md +6 -2
- package/node_modules/projectstore/scripts/configure-menu.mjs +4 -0
- package/node_modules/projectstore/scripts/configure.mjs +80 -7
- package/node_modules/projectstore/scripts/diff-refs.mjs +15 -10
- package/node_modules/projectstore/scripts/doctor.mjs +181 -12
- package/node_modules/projectstore/scripts/flow-policy.mjs +264 -0
- package/node_modules/projectstore/scripts/graph.mjs +12 -0
- package/node_modules/projectstore/scripts/lib.mjs +131 -2
- package/node_modules/projectstore/scripts/mcp.mjs +2 -2
- package/node_modules/projectstore/scripts/query.mjs +8 -2
- package/node_modules/projectstore/scripts/spec-drift.mjs +513 -0
- package/node_modules/projectstore/scripts/verbs.mjs +1 -1
- package/node_modules/projectstore/templates/de/spec.md.tmpl +5 -1
- package/node_modules/projectstore/templates/en/spec.md.tmpl +5 -1
- package/node_modules/projectstore/templates/es/spec.md.tmpl +5 -1
- package/node_modules/projectstore/templates/fr/spec.md.tmpl +5 -1
- package/node_modules/projectstore/templates/ru/spec.md.tmpl +5 -1
- package/node_modules/projectstore/templates/zh/spec.md.tmpl +5 -1
- package/package.json +2 -2
|
@@ -52,6 +52,9 @@ import {
|
|
|
52
52
|
storiesAttributionRe,
|
|
53
53
|
citationTokenRe,
|
|
54
54
|
contractNumberAscii,
|
|
55
|
+
parseAmendmentMarkers,
|
|
56
|
+
isCalendarDate,
|
|
57
|
+
TOMBSTONE_BODY,
|
|
55
58
|
CITATION_EXAMPLE_KEY,
|
|
56
59
|
CITATION_PREFILTER,
|
|
57
60
|
slugIdentity,
|
|
@@ -2298,7 +2301,7 @@ function storyStemOf(storyRel) {
|
|
|
2298
2301
|
// exact filename stem, legacy story-NNN prefix fallback — the strongest tier
|
|
2299
2302
|
// wins across the epic's stories, and a tie within it is a reported
|
|
2300
2303
|
// ambiguity, never a silent first match.
|
|
2301
|
-
function resolveSpecStory(entry, artifacts, epicFolderPath) {
|
|
2304
|
+
export function resolveSpecStory(entry, artifacts, epicFolderPath) {
|
|
2302
2305
|
const m = String(entry).match(/^([^/]+)\/(.+)$/);
|
|
2303
2306
|
if (!m) return { error: `not in <epic-id>/<story-id> form: "${entry}"` };
|
|
2304
2307
|
const [, epicId, storyId] = m;
|
|
@@ -2460,6 +2463,116 @@ export function checkSpecLinks(cfg, layout, artifacts) {
|
|
|
2460
2463
|
return out;
|
|
2461
2464
|
}
|
|
2462
2465
|
|
|
2466
|
+
// Amendment markers (the ADR "An active spec is amended by a marked block
|
|
2467
|
+
// under the contract…", decisions 1, 4 and 5; SPEC-001 contracts 5 and 6),
|
|
2468
|
+
// in every spec whatever its status, under every policy:
|
|
2469
|
+
// amendment-form (warn) a candidate that is not the grammar, a marker
|
|
2470
|
+
// before the first contract or after REMOVED;
|
|
2471
|
+
// such a marker counts for nothing;
|
|
2472
|
+
// amendment-story (issue) the ref resolves to no story, or to several;
|
|
2473
|
+
// amendment-link (warn) neither the story nor the spec lists the other
|
|
2474
|
+
// (one side only is checkSpecLinks' warn);
|
|
2475
|
+
// amendment-date (warn) not a calendar date, before the spec's `date:`,
|
|
2476
|
+
// after tomorrow, or before the previous marker
|
|
2477
|
+
// under the same contract.
|
|
2478
|
+
// One finding per spec and fact: two markers of one unlinked story warn once.
|
|
2479
|
+
export function checkAmendments(layout, artifacts, now = new Date().toISOString()) {
|
|
2480
|
+
const out = [];
|
|
2481
|
+
const epicFolder = folderByKind(layout, "epic");
|
|
2482
|
+
const resolveSpec = buildSpecResolver(artifacts, layout);
|
|
2483
|
+
const t = Date.parse(now);
|
|
2484
|
+
const tomorrow = new Date((Number.isFinite(t) ? t : Date.now()) + 86400000).toISOString().slice(0, 10);
|
|
2485
|
+
for (const spec of artifacts.filter((a) => a.kind === "spec")) {
|
|
2486
|
+
const markers = parseAmendmentMarkers(spec.body);
|
|
2487
|
+
if (!markers.length) continue;
|
|
2488
|
+
const seen = new Set();
|
|
2489
|
+
const once = (key, f) => {
|
|
2490
|
+
if (seen.has(key)) return;
|
|
2491
|
+
seen.add(key);
|
|
2492
|
+
out.push(f);
|
|
2493
|
+
};
|
|
2494
|
+
const specDate = String(spec.fm.date || "").slice(0, 10);
|
|
2495
|
+
const prevDate = new Map();
|
|
2496
|
+
for (const m of markers) {
|
|
2497
|
+
const where = m.contract === null ? `line ${m.line}` : `contract ${m.contract} (line ${m.line})`;
|
|
2498
|
+
if (!m.valid) {
|
|
2499
|
+
out.push(
|
|
2500
|
+
finding(
|
|
2501
|
+
"vault",
|
|
2502
|
+
"warn",
|
|
2503
|
+
"amendment-form",
|
|
2504
|
+
`Amendment marker at ${where} counts for nothing: ${m.form}.`,
|
|
2505
|
+
spec.rel,
|
|
2506
|
+
),
|
|
2507
|
+
);
|
|
2508
|
+
continue;
|
|
2509
|
+
}
|
|
2510
|
+
if (!isCalendarDate(m.date)) {
|
|
2511
|
+
out.push(
|
|
2512
|
+
finding(
|
|
2513
|
+
"vault",
|
|
2514
|
+
"warn",
|
|
2515
|
+
"amendment-date",
|
|
2516
|
+
`Amendment marker at ${where}: ${m.date} is not a date.`,
|
|
2517
|
+
spec.rel,
|
|
2518
|
+
),
|
|
2519
|
+
);
|
|
2520
|
+
} else {
|
|
2521
|
+
const prev = prevDate.get(m.index);
|
|
2522
|
+
let why = null;
|
|
2523
|
+
if (isCalendarDate(specDate) && m.date < specDate) why = `before the spec's date ${specDate}`;
|
|
2524
|
+
else if (m.date > tomorrow) why = `after tomorrow (${tomorrow})`;
|
|
2525
|
+
else if (prev && m.date < prev) why = `before the previous marker under the same contract (${prev})`;
|
|
2526
|
+
if (why) {
|
|
2527
|
+
out.push(
|
|
2528
|
+
finding(
|
|
2529
|
+
"vault",
|
|
2530
|
+
"warn",
|
|
2531
|
+
"amendment-date",
|
|
2532
|
+
`Amendment marker at ${where} is dated ${m.date}, ${why}.`,
|
|
2533
|
+
spec.rel,
|
|
2534
|
+
),
|
|
2535
|
+
);
|
|
2536
|
+
}
|
|
2537
|
+
prevDate.set(m.index, m.date);
|
|
2538
|
+
}
|
|
2539
|
+
const r = epicFolder
|
|
2540
|
+
? resolveSpecStory(m.ref, artifacts, epicFolder.path)
|
|
2541
|
+
: { error: "the layout has no epic folder" };
|
|
2542
|
+
if (r.error) {
|
|
2543
|
+
once(
|
|
2544
|
+
`story ${m.ref}`,
|
|
2545
|
+
finding(
|
|
2546
|
+
"vault",
|
|
2547
|
+
"issue",
|
|
2548
|
+
"amendment-story",
|
|
2549
|
+
`Amendment marker at ${where} names "${m.ref}", which resolves to no single story: ${r.error}.`,
|
|
2550
|
+
spec.rel,
|
|
2551
|
+
),
|
|
2552
|
+
);
|
|
2553
|
+
continue;
|
|
2554
|
+
}
|
|
2555
|
+
const storyListsSpec = listOf(r.story.fm, "specs").some((ref) => resolveSpec(ref) === spec);
|
|
2556
|
+
const specListsStory = listOf(spec.fm, "stories").some(
|
|
2557
|
+
(e) => resolveSpecStory(e, artifacts, epicFolder.path).story === r.story,
|
|
2558
|
+
);
|
|
2559
|
+
if (!storyListsSpec && !specListsStory) {
|
|
2560
|
+
once(
|
|
2561
|
+
`link ${r.story.rel}`,
|
|
2562
|
+
finding(
|
|
2563
|
+
"vault",
|
|
2564
|
+
"warn",
|
|
2565
|
+
"amendment-link",
|
|
2566
|
+
`Amendment marker at ${where} names ${r.story.rel}, but neither lists the other: add the spec to the story's \`specs:\` and the story to the spec's \`stories:\`.`,
|
|
2567
|
+
spec.rel,
|
|
2568
|
+
),
|
|
2569
|
+
);
|
|
2570
|
+
}
|
|
2571
|
+
}
|
|
2572
|
+
}
|
|
2573
|
+
return out;
|
|
2574
|
+
}
|
|
2575
|
+
|
|
2463
2576
|
// In-scope story = status beyond planned, not legacy-exempt.
|
|
2464
2577
|
function specScopeStatus(fm) {
|
|
2465
2578
|
const s = String(fm.status || "").toLowerCase();
|
|
@@ -2691,6 +2804,11 @@ export function checkLifecycleGates(artifacts, vaultCfg) {
|
|
|
2691
2804
|
// is not a contract. Scenario items are `- WHEN|GIVEN|AND|THEN …` list items
|
|
2692
2805
|
// under a contract; the `(verified: live|manual)` marker is looked for in the
|
|
2693
2806
|
// contract's first paragraph, which a wrapped bold heading may span.
|
|
2807
|
+
//
|
|
2808
|
+
// Amendment markers (SPEC-001 contract 5) set `removed` on a contract whose
|
|
2809
|
+
// last valid marker is REMOVED (a tombstone, with that marker's `why`), and a
|
|
2810
|
+
// step is removed when its body, trimmed, is exactly `Removed, see below.`
|
|
2811
|
+
// (`removedSteps`). `why` is the latest valid marker's, whatever its kind.
|
|
2694
2812
|
export function parseSpecContracts(spec) {
|
|
2695
2813
|
const sec = sectionOf(spec.body || "", "spec_contracts");
|
|
2696
2814
|
if (sec === null) return null;
|
|
@@ -2701,6 +2819,8 @@ export function parseSpecContracts(spec) {
|
|
|
2701
2819
|
// The scenario item a continuation line belongs to (SPEC-001 contract 13):
|
|
2702
2820
|
// a line indented deeper than its dash, not a bullet, before a blank line.
|
|
2703
2821
|
let open = null;
|
|
2822
|
+
// The step a wrapped line belongs to, for the tombstone test.
|
|
2823
|
+
let stepOpen = null;
|
|
2704
2824
|
for (const line of lines) {
|
|
2705
2825
|
const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
|
|
2706
2826
|
if (top) {
|
|
@@ -2708,6 +2828,7 @@ export function parseSpecContracts(spec) {
|
|
|
2708
2828
|
n: contractNumberAscii(top[1]),
|
|
2709
2829
|
steps: new Set(),
|
|
2710
2830
|
stepIndent: null,
|
|
2831
|
+
stepText: new Map(),
|
|
2711
2832
|
scenarios: [],
|
|
2712
2833
|
marker: null,
|
|
2713
2834
|
marks: [],
|
|
@@ -2716,22 +2837,34 @@ export function parseSpecContracts(spec) {
|
|
|
2716
2837
|
contracts.push(cur);
|
|
2717
2838
|
inFirstPara = true;
|
|
2718
2839
|
open = null;
|
|
2840
|
+
stepOpen = null;
|
|
2719
2841
|
continue;
|
|
2720
2842
|
}
|
|
2721
2843
|
if (!cur) continue;
|
|
2722
2844
|
if (/^\s*$/.test(line)) {
|
|
2723
2845
|
inFirstPara = false;
|
|
2724
2846
|
open = null;
|
|
2847
|
+
stepOpen = null;
|
|
2725
2848
|
continue;
|
|
2726
2849
|
}
|
|
2727
2850
|
if (inFirstPara) cur.first += " " + line.trim();
|
|
2728
2851
|
const step = line.match(/^(\s+)(\d+[′″']*)\.(\s|$)/);
|
|
2729
2852
|
if (step) {
|
|
2730
2853
|
if (cur.stepIndent === null) cur.stepIndent = step[1].length;
|
|
2731
|
-
if (step[1].length === cur.stepIndent)
|
|
2854
|
+
if (step[1].length === cur.stepIndent) {
|
|
2855
|
+
const n = contractNumberAscii(step[2]);
|
|
2856
|
+
cur.steps.add(n);
|
|
2857
|
+
cur.stepText.set(n, line.slice(step[0].length));
|
|
2858
|
+
stepOpen = n;
|
|
2859
|
+
} else stepOpen = null;
|
|
2732
2860
|
open = null;
|
|
2733
2861
|
continue;
|
|
2734
2862
|
}
|
|
2863
|
+
if (stepOpen !== null) {
|
|
2864
|
+
if (line.match(/^\s*/)[0].length > cur.stepIndent && !/^\s*([-*+>]|\d+[′″']*\.)(\s|$)/.test(line))
|
|
2865
|
+
cur.stepText.set(stepOpen, cur.stepText.get(stepOpen) + " " + line.trim());
|
|
2866
|
+
else stepOpen = null;
|
|
2867
|
+
}
|
|
2735
2868
|
const sc = line.match(/^(\s*)-\s+(WHEN|GIVEN|AND|THEN)\b/);
|
|
2736
2869
|
if (sc) {
|
|
2737
2870
|
cur.scenarios.push(line.trim());
|
|
@@ -2742,21 +2875,27 @@ export function parseSpecContracts(spec) {
|
|
|
2742
2875
|
cur.scenarios[open.i] += " " + line.trim();
|
|
2743
2876
|
else open = null;
|
|
2744
2877
|
}
|
|
2745
|
-
|
|
2878
|
+
const markers = parseAmendmentMarkers(spec.body || "").filter((m) => m.valid);
|
|
2879
|
+
contracts.forEach((c, i) => {
|
|
2746
2880
|
const mk = c.first.match(/\(verified\s*[::]\s*(live|manual)\)/);
|
|
2747
2881
|
c.marker = mk ? mk[1] : null;
|
|
2748
2882
|
// An (edge) or (failure) mark closes a WHEN or GIVEN item; nowhere else counts.
|
|
2749
2883
|
c.marks = c.scenarios.map((l) => /^-\s+(WHEN|GIVEN)\b.*\((edge|failure)\)\s*$/.exec(l)?.[2]).filter(Boolean);
|
|
2884
|
+
const last = markers.filter((m) => m.index === i).at(-1) ?? null;
|
|
2885
|
+
c.removed = last?.kind === "REMOVED";
|
|
2886
|
+
c.why = last?.why ?? null;
|
|
2887
|
+
c.removedSteps = new Set([...c.stepText].filter(([, t]) => t.trim() === TOMBSTONE_BODY).map(([n]) => n));
|
|
2750
2888
|
delete c.first;
|
|
2751
2889
|
delete c.stepIndent;
|
|
2752
|
-
|
|
2890
|
+
delete c.stepText;
|
|
2891
|
+
});
|
|
2753
2892
|
return contracts;
|
|
2754
2893
|
}
|
|
2755
2894
|
|
|
2756
2895
|
// Key → spec, by frontmatter id and alias, exact and case-sensitive. Not
|
|
2757
2896
|
// buildSpecResolver: its filename fallback is lower-cased, and a citation
|
|
2758
2897
|
// token resolves only to what a spec declares.
|
|
2759
|
-
function citationKeys(artifacts) {
|
|
2898
|
+
export function citationKeys(artifacts) {
|
|
2760
2899
|
const keys = new Map();
|
|
2761
2900
|
for (const s of artifacts.filter((a) => a.kind === "spec")) {
|
|
2762
2901
|
for (const k of [String(s.fm.id || ""), String(s.fm.alias || "")]) {
|
|
@@ -2826,11 +2965,12 @@ export function checkSpecAliases(artifacts) {
|
|
|
2826
2965
|
|
|
2827
2966
|
// Happy path only (SPEC-001 contract 13; the authoring-guides ADR, decision
|
|
2828
2967
|
// 7): the contracts of an active spec that carry scenarios and have none
|
|
2829
|
-
// marked (edge) or (failure). Counted, not judged; no git.
|
|
2968
|
+
// marked (edge) or (failure). Counted, not judged; no git. A removed
|
|
2969
|
+
// contract (contract 5) is not reported, whatever its body still holds.
|
|
2830
2970
|
export function checkHappyPathOnly(artifacts) {
|
|
2831
2971
|
const out = [];
|
|
2832
2972
|
for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
|
|
2833
|
-
const withScenarios = (parseSpecContracts(s) || []).filter((c) => c.scenarios.length);
|
|
2973
|
+
const withScenarios = (parseSpecContracts(s) || []).filter((c) => !c.removed && c.scenarios.length);
|
|
2834
2974
|
const bare = withScenarios.filter((c) => !c.marks.length).map((c) => c.n);
|
|
2835
2975
|
if (!bare.length) continue;
|
|
2836
2976
|
out.push(
|
|
@@ -2847,12 +2987,12 @@ export function checkHappyPathOnly(artifacts) {
|
|
|
2847
2987
|
}
|
|
2848
2988
|
|
|
2849
2989
|
// Scenario shape (Decision 3): a contract's scenario items need a WHEN (or
|
|
2850
|
-
// GIVEN) and a THEN.
|
|
2990
|
+
// GIVEN) and a THEN. Removed contracts are skipped.
|
|
2851
2991
|
export function checkScenarioShape(artifacts) {
|
|
2852
2992
|
const out = [];
|
|
2853
2993
|
for (const s of artifacts.filter((a) => a.kind === "spec")) {
|
|
2854
2994
|
for (const c of parseSpecContracts(s) || []) {
|
|
2855
|
-
if (!c.scenarios.length) continue;
|
|
2995
|
+
if (c.removed || !c.scenarios.length) continue;
|
|
2856
2996
|
const when = c.scenarios.some((l) => /^-\s+(WHEN|GIVEN)\b/.test(l));
|
|
2857
2997
|
const then = c.scenarios.some((l) => /^-\s+THEN\b/.test(l));
|
|
2858
2998
|
if (!when || !then) {
|
|
@@ -2961,6 +3101,21 @@ export function checkContractCitations(artifacts, scan) {
|
|
|
2961
3101
|
if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
|
|
2962
3102
|
const [top, step] = t.n.split("/");
|
|
2963
3103
|
const c = contractsOf.get(spec).find((x) => x.n === top);
|
|
3104
|
+
if (c && (c.removed || (step && c.removedSteps.has(step)))) {
|
|
3105
|
+
// A tombstone (SPEC-001 contract 8): reported instead of unknown, with
|
|
3106
|
+
// the why of the contract's latest valid marker, and no coverage.
|
|
3107
|
+
const what = c.removed ? `contract ${top}` : `step ${t.n}`;
|
|
3108
|
+
out.push(
|
|
3109
|
+
finding(
|
|
3110
|
+
"vault",
|
|
3111
|
+
"warn",
|
|
3112
|
+
"citation-removed",
|
|
3113
|
+
`[${t.key}#${t.n}] cites ${what} of ${spec.rel}, which is removed${c.why ? `: "${c.why}"` : ""} — move the test to the rule that replaced it, or drop the token.`,
|
|
3114
|
+
where,
|
|
3115
|
+
),
|
|
3116
|
+
);
|
|
3117
|
+
continue;
|
|
3118
|
+
}
|
|
2964
3119
|
if (!c || (step && !c.steps.has(step))) {
|
|
2965
3120
|
out.push(
|
|
2966
3121
|
finding("vault", "warn", "citation-unknown", `[${t.key}#${t.n}] — ${spec.rel} has no contract ${t.n}.`, where),
|
|
@@ -2992,7 +3147,8 @@ export function checkContractCitations(artifacts, scan) {
|
|
|
2992
3147
|
return f;
|
|
2993
3148
|
};
|
|
2994
3149
|
for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
|
|
2995
|
-
|
|
3150
|
+
// Tombstones are not counted (SPEC-001 contract 8).
|
|
3151
|
+
const contracts = (contractsOf.get(s) || parseSpecContracts(s) || []).filter((c) => !c.removed);
|
|
2996
3152
|
if (!contracts.length) continue;
|
|
2997
3153
|
const got = cited.get(s) || new Set();
|
|
2998
3154
|
if (!got.size && String(s.fm.coverage || "") !== "report") {
|
|
@@ -3029,11 +3185,23 @@ export function checkContractCitations(artifacts, scan) {
|
|
|
3029
3185
|
// Evidence that cites a contract (Decision 10), behind lifecycle_gates: on.
|
|
3030
3186
|
// A token not found in the project is a warn for a story in progress or in
|
|
3031
3187
|
// review, and for a done story that is not legacy. Free-text evidence is
|
|
3032
|
-
// never checked, and doctor never runs a test.
|
|
3188
|
+
// never checked, and doctor never runs a test. Evidence naming a removed
|
|
3189
|
+
// contract or step is skipped (SPEC-001 contract 8): a closed story's record
|
|
3190
|
+
// does not warn when a later story removes what it cited.
|
|
3033
3191
|
export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
|
|
3034
3192
|
if (!lifecycleGatesOn(vaultCfg) || !scan || scan.status !== "ok") return [];
|
|
3035
3193
|
const since = legacySince(vaultCfg);
|
|
3036
3194
|
const present = new Set(scan.tokens.map((t) => `${t.key}#${t.n}`));
|
|
3195
|
+
const keys = citationKeys(artifacts);
|
|
3196
|
+
const contractsOf = new Map();
|
|
3197
|
+
const tombstone = (key, n) => {
|
|
3198
|
+
const spec = keys.get(key);
|
|
3199
|
+
if (!spec) return false;
|
|
3200
|
+
if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
|
|
3201
|
+
const [top, step] = n.split("/");
|
|
3202
|
+
const c = contractsOf.get(spec).find((x) => x.n === top);
|
|
3203
|
+
return Boolean(c && (c.removed || (step && c.removedSteps.has(step))));
|
|
3204
|
+
};
|
|
3037
3205
|
const evidenceRe = evidenceSuffixRe();
|
|
3038
3206
|
const out = [];
|
|
3039
3207
|
for (const story of artifacts.filter((a) => a.kind === "story")) {
|
|
@@ -3047,7 +3215,7 @@ export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
|
|
|
3047
3215
|
const at = item.text.search(evidenceRe);
|
|
3048
3216
|
if (at === -1) continue;
|
|
3049
3217
|
for (const t of item.text.slice(at).matchAll(citationTokenRe())) {
|
|
3050
|
-
if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`)) continue;
|
|
3218
|
+
if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`) || tombstone(t[1], t[2])) continue;
|
|
3051
3219
|
out.push(
|
|
3052
3220
|
finding(
|
|
3053
3221
|
"vault",
|
|
@@ -3883,6 +4051,7 @@ export function runVaultChecks(
|
|
|
3883
4051
|
() => checkIndexHeaders(cfg, layout),
|
|
3884
4052
|
() => checkStoriesAndEpics(artifacts),
|
|
3885
4053
|
() => checkSpecLinks(cfg, layout, artifacts),
|
|
4054
|
+
() => checkAmendments(layout, artifacts, now),
|
|
3886
4055
|
() => checkSpecCoverage(artifacts, vaultCfg, layout),
|
|
3887
4056
|
() => checkSpecAcceptance(layout, artifacts, vaultCfg),
|
|
3888
4057
|
() => checkLifecycleGates(artifacts, vaultCfg),
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
// projectstore — flow-policy.mjs: the vault's flow policy, as data.
|
|
2
|
+
//
|
|
3
|
+
// The `flow` block of <vault>/.projectstore.json holds a team's flow
|
|
4
|
+
// thresholds: WIP limits by a person's time on the project, ages in status,
|
|
5
|
+
// windows for throughput and capacity. This module is its grammar: the keys
|
|
6
|
+
// and their value forms, the `--set` parse `configure` uses, the view's rows,
|
|
7
|
+
// and the WIP limit rule doctor, `next` and the band read. Pure: no I/O.
|
|
8
|
+
//
|
|
9
|
+
// Spec: "Changing a project's settings after setup…" (alias `configure`),
|
|
10
|
+
// contracts 2, 3, 7 and 11 as amended 2026-11-10, and SPEC-001 contract 4
|
|
11
|
+
// as amended the same day, by PS-FLOW/story-the-vault-declares-its-flow-
|
|
12
|
+
// policy-and-configure-writes-it. No key has a default in code: a check whose
|
|
13
|
+
// key is absent does not run, and a value of the wrong type counts as absent.
|
|
14
|
+
|
|
15
|
+
import { isCalendarDate } from "./lib.mjs";
|
|
16
|
+
|
|
17
|
+
export const CLEAR = "-";
|
|
18
|
+
|
|
19
|
+
// The fixed keys, in the view's order. `kind` picks the value form.
|
|
20
|
+
export const FLOW_FIXED = Object.freeze([
|
|
21
|
+
{ key: "flow.wip.full", path: ["wip", "full"], kind: "count" },
|
|
22
|
+
{ key: "flow.wip.part", path: ["wip", "part"], kind: "count" },
|
|
23
|
+
{ key: "flow.age_days.review", path: ["age_days", "review"], kind: "days" },
|
|
24
|
+
{ key: "flow.age_days.in_progress_idle", path: ["age_days", "in_progress_idle"], kind: "days" },
|
|
25
|
+
{ key: "flow.age_days.todo", path: ["age_days", "todo"], kind: "days" },
|
|
26
|
+
{ key: "flow.idle_days", path: ["idle_days"], kind: "days" },
|
|
27
|
+
{ key: "flow.window_weeks", path: ["window_weeks"], kind: "weeks" },
|
|
28
|
+
{ key: "flow.capacity_weeks", path: ["capacity_weeks"], kind: "range" },
|
|
29
|
+
{ key: "flow.active_epics_max", path: ["active_epics_max"], kind: "count" },
|
|
30
|
+
{ key: "flow.grooming_days", path: ["grooming_days"], kind: "days" },
|
|
31
|
+
]);
|
|
32
|
+
|
|
33
|
+
// A person's fields, in the view's order.
|
|
34
|
+
export const PERSON_FIELDS = Object.freeze(["time", "wip", "git_names", "left"]);
|
|
35
|
+
const PERSON_KIND = Object.freeze({ time: "time", wip: "count", git_names: "names", left: "date" });
|
|
36
|
+
|
|
37
|
+
// Stamps under `flow`: never set by hand (contract 2's "Not settings").
|
|
38
|
+
export const FLOW_STAMPS = Object.freeze(["flow.groomed_at"]);
|
|
39
|
+
|
|
40
|
+
const SET_OF = Object.freeze({
|
|
41
|
+
count: "a positive whole number",
|
|
42
|
+
days: "a whole number of days, 1 or more",
|
|
43
|
+
weeks: "a whole number of weeks, 1 or more",
|
|
44
|
+
range: "two positive numbers, low then high, like 2,3",
|
|
45
|
+
time: "full or part",
|
|
46
|
+
names: "a comma list of git author names",
|
|
47
|
+
date: "a date as YYYY-MM-DD",
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
const FORM_OF = Object.freeze({
|
|
51
|
+
count: "<n>",
|
|
52
|
+
days: "<days>",
|
|
53
|
+
weeks: "<weeks>",
|
|
54
|
+
range: "<low,high>",
|
|
55
|
+
time: "<full|part>",
|
|
56
|
+
names: "<a,b>",
|
|
57
|
+
date: "<YYYY-MM-DD>",
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
const CONTROL = /[\u0000-\u001f\u007f\u0085\u2028\u2029]/;
|
|
61
|
+
const PERSON_KEY = /^flow\.people\[([\s\S]*?)\]\.([A-Za-z_]+)=([\s\S]*)$/;
|
|
62
|
+
const BARE_PERSON = /^flow\.people\[([\s\S]*?)\]\s*(=|$)/;
|
|
63
|
+
|
|
64
|
+
const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
65
|
+
|
|
66
|
+
// A positive safe integer written in plain decimal: no sign, no leading zero,
|
|
67
|
+
// no exponent, no fraction.
|
|
68
|
+
function positiveInt(raw) {
|
|
69
|
+
if (!/^[1-9]\d*$/.test(raw)) return null;
|
|
70
|
+
const n = Number(raw);
|
|
71
|
+
return Number.isSafeInteger(n) ? n : null;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function positiveNumber(raw) {
|
|
75
|
+
if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(raw)) return null;
|
|
76
|
+
const n = Number(raw);
|
|
77
|
+
return Number.isFinite(n) && n > 0 ? n : null;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// A value as typed → the value stored, or null when it is outside the set.
|
|
81
|
+
function parseValue(kind, raw) {
|
|
82
|
+
switch (kind) {
|
|
83
|
+
case "count":
|
|
84
|
+
case "days":
|
|
85
|
+
case "weeks":
|
|
86
|
+
return positiveInt(raw);
|
|
87
|
+
case "range": {
|
|
88
|
+
const parts = raw.split(",").map((p) => p.trim());
|
|
89
|
+
if (parts.length !== 2) return null;
|
|
90
|
+
const [lo, hi] = parts.map(positiveNumber);
|
|
91
|
+
return lo !== null && hi !== null && lo <= hi ? [lo, hi] : null;
|
|
92
|
+
}
|
|
93
|
+
case "time":
|
|
94
|
+
return raw === "full" || raw === "part" ? raw : null;
|
|
95
|
+
case "names": {
|
|
96
|
+
const names = raw
|
|
97
|
+
.split(",")
|
|
98
|
+
.map((n) => n.trim())
|
|
99
|
+
.filter(Boolean);
|
|
100
|
+
return names.length && !names.some((n) => CONTROL.test(n)) ? names : null;
|
|
101
|
+
}
|
|
102
|
+
case "date":
|
|
103
|
+
return isCalendarDate(raw) ? raw : null;
|
|
104
|
+
default:
|
|
105
|
+
return null;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const shownName = (name) => (CONTROL.test(name) ? JSON.stringify(name) : name);
|
|
110
|
+
|
|
111
|
+
// A person's name as `flow.people[<name>]` takes it: the assignee as stories
|
|
112
|
+
// write it, never an email address.
|
|
113
|
+
function badName(name) {
|
|
114
|
+
return !name || /[@\]=]/.test(name) || CONTROL.test(name) || name === "__proto__";
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// Whether a raw `--set` argument is a flow key: these are parsed here, before
|
|
118
|
+
// configure splits at the first `=` (a person's name may hold a dot).
|
|
119
|
+
export const isFlowSet = (raw) => /^\s*flow(?:[.[=]|$)/.test(String(raw));
|
|
120
|
+
|
|
121
|
+
// The every-key list a typo is measured against.
|
|
122
|
+
export function flowKnownKeys(flow) {
|
|
123
|
+
const keys = FLOW_FIXED.map((k) => k.key);
|
|
124
|
+
if (isPlainObject(flow) && isPlainObject(flow.people))
|
|
125
|
+
for (const name of Object.keys(flow.people)) for (const f of PERSON_FIELDS) keys.push(personKey(name, f));
|
|
126
|
+
return keys;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
export const personKey = (name, field) => `flow.people[${name}].${field}`;
|
|
130
|
+
|
|
131
|
+
// One `--set` argument → `{ change: { key, path, value } }`, `value: null`
|
|
132
|
+
// meaning "remove that key", or `{ usage }` (exit 2).
|
|
133
|
+
export function parseFlowSet(raw, { nearest = null, flow = null } = {}) {
|
|
134
|
+
const text = String(raw).trim();
|
|
135
|
+
const unknown = (key) => {
|
|
136
|
+
if (FLOW_STAMPS.includes(key))
|
|
137
|
+
return { usage: `unknown setting ${key} — a stamp that groom writes, never set by hand` };
|
|
138
|
+
const hint = nearest ? nearest(key, flowKnownKeys(flow)) : null;
|
|
139
|
+
return { usage: `unknown setting ${key}${hint ? ` — did you mean ${hint}?` : ""}` };
|
|
140
|
+
};
|
|
141
|
+
const p = PERSON_KEY.exec(text);
|
|
142
|
+
if (p) {
|
|
143
|
+
const name = p[1].trim();
|
|
144
|
+
const field = p[2];
|
|
145
|
+
const value = p[3].trim();
|
|
146
|
+
if (badName(name))
|
|
147
|
+
return {
|
|
148
|
+
usage: `flow.people[${shownName(name)}] takes a name with no @, ] or =, and no line break (the assignee as stories write it, never an email address), got ${JSON.stringify(name)}`,
|
|
149
|
+
};
|
|
150
|
+
const key = personKey(name, field);
|
|
151
|
+
if (!PERSON_FIELDS.includes(field)) return unknown(key);
|
|
152
|
+
return change(key, ["people", name, field], PERSON_KIND[field], value);
|
|
153
|
+
}
|
|
154
|
+
const bare = BARE_PERSON.exec(text);
|
|
155
|
+
if (bare) {
|
|
156
|
+
const name = bare[1].trim();
|
|
157
|
+
return {
|
|
158
|
+
usage: `flow.people[${shownName(name)}] takes ${PERSON_FIELDS.map((f) => `.${f}`)
|
|
159
|
+
.join(", ")
|
|
160
|
+
.replace(/, ([^,]*)$/, " or $1")}`,
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
const at = text.indexOf("=");
|
|
164
|
+
if (at < 1) return { usage: `--set takes <key>=<value>, got ${raw}` };
|
|
165
|
+
const key = text.slice(0, at).trim();
|
|
166
|
+
const value = text.slice(at + 1).trim();
|
|
167
|
+
const fixed = FLOW_FIXED.find((k) => k.key === key);
|
|
168
|
+
if (!fixed) return unknown(key);
|
|
169
|
+
return change(key, fixed.path, fixed.kind, value);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
function change(key, path, kind, value) {
|
|
173
|
+
if (value === CLEAR) return { change: { key, path, value: null } };
|
|
174
|
+
const parsed = value ? parseValue(kind, value) : null;
|
|
175
|
+
if (parsed === null)
|
|
176
|
+
return { usage: `${key} takes ${SET_OF[kind]}, or ${CLEAR} to clear it, got ${value || "nothing"}` };
|
|
177
|
+
return { change: { key, path, value: parsed } };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// The `--set` form a flow key is changed with; a person's form is quoted by
|
|
181
|
+
// the caller for the shell.
|
|
182
|
+
export function flowForm(key) {
|
|
183
|
+
const fixed = FLOW_FIXED.find((k) => k.key === key);
|
|
184
|
+
if (fixed) return `--set ${key}=${FORM_OF[fixed.kind]}`;
|
|
185
|
+
const m = /^flow\.people\[([\s\S]*)\]\.([a-z_]+)$/.exec(key);
|
|
186
|
+
return m ? `--set ${key}=${FORM_OF[PERSON_KIND[m[2]]]}` : null;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
// The value at a path of the flow block, own keys only; undefined when absent.
|
|
190
|
+
export function flowAt(flow, path) {
|
|
191
|
+
let node = flow;
|
|
192
|
+
for (const step of path) {
|
|
193
|
+
if (!isPlainObject(node) || !Object.hasOwn(node, step)) return undefined;
|
|
194
|
+
node = node[step];
|
|
195
|
+
}
|
|
196
|
+
return node;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
// The first node on a path that exists and is not an object, as a dotted
|
|
200
|
+
// key; null when the path can be written.
|
|
201
|
+
export function blockedAt(vaultCfg, path) {
|
|
202
|
+
if (!isPlainObject(vaultCfg) || !Object.hasOwn(vaultCfg, "flow")) return null;
|
|
203
|
+
let node = vaultCfg.flow;
|
|
204
|
+
let label = "flow";
|
|
205
|
+
for (let i = 0; i < path.length; i++) {
|
|
206
|
+
if (!isPlainObject(node)) return label;
|
|
207
|
+
if (i === path.length - 1 || !Object.hasOwn(node, path[i])) return null;
|
|
208
|
+
label += path[0] === "people" && i === 1 ? `[${path[i]}]` : `.${path[i]}`;
|
|
209
|
+
node = node[path[i]];
|
|
210
|
+
}
|
|
211
|
+
return null;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// The rows the view lists: every set key, fixed keys in table order, then
|
|
215
|
+
// people in file order, each person's fields in table order. A value of the
|
|
216
|
+
// wrong type is listed as it is: the view shows the file.
|
|
217
|
+
export function flowRows(flow) {
|
|
218
|
+
if (!isPlainObject(flow)) return [];
|
|
219
|
+
const rows = [];
|
|
220
|
+
for (const k of FLOW_FIXED) {
|
|
221
|
+
const v = flowAt(flow, k.path);
|
|
222
|
+
if (v !== undefined) rows.push({ key: k.key, value: v, person: null });
|
|
223
|
+
}
|
|
224
|
+
if (isPlainObject(flow.people))
|
|
225
|
+
for (const [name, fields] of Object.entries(flow.people)) {
|
|
226
|
+
if (!isPlainObject(fields)) continue;
|
|
227
|
+
for (const f of PERSON_FIELDS)
|
|
228
|
+
if (Object.hasOwn(fields, f)) rows.push({ key: personKey(name, f), value: fields[f], person: name });
|
|
229
|
+
}
|
|
230
|
+
return rows;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
const goodCount = (v) => Number.isSafeInteger(v) && v > 0;
|
|
234
|
+
|
|
235
|
+
// A fixed key's value when it is of its key's type, else null: how every
|
|
236
|
+
// reader of the policy takes it (SPEC-001 contract 4, as amended).
|
|
237
|
+
export function flowValue(vaultCfg, key) {
|
|
238
|
+
const fixed = FLOW_FIXED.find((k) => k.key === key || k.key === `flow.${key}`);
|
|
239
|
+
if (!fixed || !isPlainObject(vaultCfg)) return null;
|
|
240
|
+
const v = flowAt(vaultCfg.flow, fixed.path);
|
|
241
|
+
if (fixed.kind === "range")
|
|
242
|
+
return Array.isArray(v) &&
|
|
243
|
+
v.length === 2 &&
|
|
244
|
+
v.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0) &&
|
|
245
|
+
v[0] <= v[1]
|
|
246
|
+
? [v[0], v[1]]
|
|
247
|
+
: null;
|
|
248
|
+
return goodCount(v) ? v : null;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
// The WIP limit rule (SPEC-001 contract 4, as amended): a person's own `wip`,
|
|
252
|
+
// else `flow.wip.<time>` for their `time`, else no limit. A person not listed
|
|
253
|
+
// has none. The name matches exactly, as an own key.
|
|
254
|
+
export function wipLimitOf(vaultCfg, name) {
|
|
255
|
+
if (!isPlainObject(vaultCfg)) return null;
|
|
256
|
+
const people = flowAt(vaultCfg.flow, ["people"]);
|
|
257
|
+
if (!isPlainObject(people) || typeof name !== "string" || !Object.hasOwn(people, name)) return null;
|
|
258
|
+
const person = people[name];
|
|
259
|
+
if (!isPlainObject(person)) return null;
|
|
260
|
+
if (goodCount(person.wip)) return person.wip;
|
|
261
|
+
if (person.time !== "full" && person.time !== "part") return null;
|
|
262
|
+
const byTime = flowAt(vaultCfg.flow, ["wip", person.time]);
|
|
263
|
+
return goodCount(byTime) ? byTime : null;
|
|
264
|
+
}
|
|
@@ -24,6 +24,7 @@ import {
|
|
|
24
24
|
extractLinks,
|
|
25
25
|
resolveLinkTarget,
|
|
26
26
|
storyMatchesEntry,
|
|
27
|
+
parseAmendmentMarkers,
|
|
27
28
|
isMain,
|
|
28
29
|
commandForm,
|
|
29
30
|
} from "./lib.mjs";
|
|
@@ -115,6 +116,17 @@ export function buildGraph(cfg, layout, { files = null } = {}) {
|
|
|
115
116
|
if (r.outcome === "node") addEdge(n.path, "spec-implements-adr", r.node.path);
|
|
116
117
|
else addResolved(n.path, r, entry);
|
|
117
118
|
}
|
|
119
|
+
// Amendment markers in the contracts section (spec contract 3, the
|
|
120
|
+
// third edge source; SPEC-001 contract 5), whatever the spec's status:
|
|
121
|
+
// a valid marker's ref resolves as a `stories:` entry does, and gives
|
|
122
|
+
// one `amends` edge story → spec per pair (dedup on the triple), or
|
|
123
|
+
// the dead or ambiguous edge its ref resolves to.
|
|
124
|
+
for (const m of parseAmendmentMarkers(n.body)) {
|
|
125
|
+
if (!m.valid) continue;
|
|
126
|
+
const r = epicsPath ? resolveStoryEntry(m.ref, index, epicsPath) : { outcome: "dead" };
|
|
127
|
+
if (r.outcome === "node") addEdge(r.node.path, "amends", n.path);
|
|
128
|
+
else addResolved(n.path, r, m.ref);
|
|
129
|
+
}
|
|
118
130
|
}
|
|
119
131
|
if (n.type === "story") {
|
|
120
132
|
for (const entry of refsOf(n.fm, "specs")) {
|