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.
Files changed (30) 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/README.md +5 -0
  4. package/node_modules/projectstore/agents/planner.md +4 -1
  5. package/node_modules/projectstore/agents/reviewer.md +77 -2
  6. package/node_modules/projectstore/commands/doctor.md +11 -0
  7. package/node_modules/projectstore/commands/graph.md +5 -1
  8. package/node_modules/projectstore/commands/story.md +4 -1
  9. package/node_modules/projectstore/docs/contracts-and-tests.md +94 -2
  10. package/node_modules/projectstore/docs/extending.md +10 -0
  11. package/node_modules/projectstore/package.json +1 -1
  12. package/node_modules/projectstore/scaffold/guides/spec.md +6 -2
  13. package/node_modules/projectstore/scripts/configure-menu.mjs +4 -0
  14. package/node_modules/projectstore/scripts/configure.mjs +80 -7
  15. package/node_modules/projectstore/scripts/diff-refs.mjs +15 -10
  16. package/node_modules/projectstore/scripts/doctor.mjs +181 -12
  17. package/node_modules/projectstore/scripts/flow-policy.mjs +264 -0
  18. package/node_modules/projectstore/scripts/graph.mjs +12 -0
  19. package/node_modules/projectstore/scripts/lib.mjs +131 -2
  20. package/node_modules/projectstore/scripts/mcp.mjs +2 -2
  21. package/node_modules/projectstore/scripts/query.mjs +8 -2
  22. package/node_modules/projectstore/scripts/spec-drift.mjs +513 -0
  23. package/node_modules/projectstore/scripts/verbs.mjs +1 -1
  24. package/node_modules/projectstore/templates/de/spec.md.tmpl +5 -1
  25. package/node_modules/projectstore/templates/en/spec.md.tmpl +5 -1
  26. package/node_modules/projectstore/templates/es/spec.md.tmpl +5 -1
  27. package/node_modules/projectstore/templates/fr/spec.md.tmpl +5 -1
  28. package/node_modules/projectstore/templates/ru/spec.md.tmpl +5 -1
  29. package/node_modules/projectstore/templates/zh/spec.md.tmpl +5 -1
  30. 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) cur.steps.add(contractNumberAscii(step[2]));
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
- for (const c of contracts) {
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
- const contracts = contractsOf.get(s) || parseSpecContracts(s) || [];
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")) {