projectstore-claude 0.30.8 → 0.30.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
  2. package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
  3. package/node_modules/projectstore/.mcp.json +1 -5
  4. package/node_modules/projectstore/README.md +6 -5
  5. package/node_modules/projectstore/agents/archaeologist.md +1 -1
  6. package/node_modules/projectstore/agents/critic.md +26 -3
  7. package/node_modules/projectstore/agents/librarian.md +1 -1
  8. package/node_modules/projectstore/agents/planner.md +13 -1
  9. package/node_modules/projectstore/agents/reviewer.md +19 -2
  10. package/node_modules/projectstore/commands/adr.md +10 -0
  11. package/node_modules/projectstore/commands/bind.md +4 -3
  12. package/node_modules/projectstore/commands/concept.md +9 -0
  13. package/node_modules/projectstore/commands/doctor.md +17 -4
  14. package/node_modules/projectstore/commands/epic.md +10 -0
  15. package/node_modules/projectstore/commands/meeting.md +9 -0
  16. package/node_modules/projectstore/commands/research.md +9 -0
  17. package/node_modules/projectstore/commands/review.md +11 -7
  18. package/node_modules/projectstore/commands/runbook.md +9 -0
  19. package/node_modules/projectstore/commands/spec.md +10 -0
  20. package/node_modules/projectstore/commands/story.md +25 -1
  21. package/node_modules/projectstore/docs/contracts-and-tests.md +107 -0
  22. package/node_modules/projectstore/docs/extending.md +44 -5
  23. package/node_modules/projectstore/harnesses/claude-code.json +3 -3
  24. package/node_modules/projectstore/harnesses/codex.json +1 -1
  25. package/node_modules/projectstore/package.json +1 -1
  26. package/node_modules/projectstore/scaffold/guides/adr.md +42 -0
  27. package/node_modules/projectstore/scaffold/guides/concept.md +10 -0
  28. package/node_modules/projectstore/scaffold/guides/epic.md +36 -0
  29. package/node_modules/projectstore/scaffold/guides/meeting.md +11 -0
  30. package/node_modules/projectstore/scaffold/guides/research.md +16 -0
  31. package/node_modules/projectstore/scaffold/guides/runbook.md +12 -0
  32. package/node_modules/projectstore/scaffold/guides/spec.md +39 -0
  33. package/node_modules/projectstore/scaffold/guides/story.md +34 -0
  34. package/node_modules/projectstore/scripts/cli.mjs +55 -1
  35. package/node_modules/projectstore/scripts/configure-menu.mjs +2 -1
  36. package/node_modules/projectstore/scripts/configure.mjs +12 -2
  37. package/node_modules/projectstore/scripts/diff-refs.mjs +39 -0
  38. package/node_modules/projectstore/scripts/doctor.mjs +648 -33
  39. package/node_modules/projectstore/scripts/guides.mjs +217 -0
  40. package/node_modules/projectstore/scripts/harness.mjs +2 -0
  41. package/node_modules/projectstore/scripts/lib.mjs +163 -1
  42. package/node_modules/projectstore/scripts/mcp-server.mjs +11 -4
  43. package/node_modules/projectstore/scripts/mcp.mjs +30 -3
  44. package/node_modules/projectstore/scripts/read-verbs.mjs +59 -3
  45. package/node_modules/projectstore/scripts/scaffold.mjs +1 -1
  46. package/node_modules/projectstore/scripts/story-section.mjs +16 -1
  47. package/node_modules/projectstore/scripts/verbs.mjs +33 -1
  48. package/node_modules/projectstore/scripts/version-guard.mjs +5 -10
  49. package/node_modules/projectstore/skills/projectstore-peer-reviewer/SKILL.md +9 -3
  50. package/node_modules/projectstore/templates/de/spec.md.tmpl +9 -1
  51. package/node_modules/projectstore/templates/de/story.md.tmpl +1 -0
  52. package/node_modules/projectstore/templates/en/spec.md.tmpl +8 -1
  53. package/node_modules/projectstore/templates/en/story.md.tmpl +1 -0
  54. package/node_modules/projectstore/templates/es/spec.md.tmpl +9 -1
  55. package/node_modules/projectstore/templates/es/story.md.tmpl +1 -0
  56. package/node_modules/projectstore/templates/fr/spec.md.tmpl +9 -1
  57. package/node_modules/projectstore/templates/fr/story.md.tmpl +1 -0
  58. package/node_modules/projectstore/templates/ru/spec.md.tmpl +8 -1
  59. package/node_modules/projectstore/templates/ru/story.md.tmpl +1 -0
  60. package/node_modules/projectstore/templates/zh/spec.md.tmpl +8 -1
  61. package/node_modules/projectstore/templates/zh/story.md.tmpl +1 -0
  62. package/package.json +2 -2
  63. package/node_modules/projectstore/scaffold/checklists.json +0 -88
@@ -0,0 +1,217 @@
1
+ // projectstore — guides.mjs
2
+ //
3
+ // Authoring guides: one markdown file per artifact kind that the author reads
4
+ // before a draft and the critic checks after it. The package ships the
5
+ // defaults in scaffold/guides/<kind>.md; a vault may override one, whole, in
6
+ // <vault>/guides/<kind>.md. Resolved at every read, never cached and never
7
+ // copied into the project tree: an edit in Obsidian reaches the next reader.
8
+ // Normative: the ADR "One authoring guide per artifact kind, read by the
9
+ // author before the draft and by the critic after, overridable from the
10
+ // vault" (decisions 1-5) and SPEC-001 contract 12.
11
+ //
12
+ // A leaf: lib.mjs, harness.mjs and node built-ins only. The read side serves
13
+ // the `guide` verb and the MCP `guide` tool (read-verbs.mjs); eject is the one
14
+ // writer, reached only through the CLI's own handler (cli.mjs).
15
+
16
+ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync } from "node:fs";
17
+ import { join } from "node:path";
18
+ import { pluginRoot, parseFrontmatter, guideItems, linesOutsideFences, createFileExclusive } from "./lib.mjs";
19
+ import { LAYOUT } from "./harness.mjs";
20
+
21
+ // The five sections, read by name; English in every vault language.
22
+ export const GUIDE_SECTIONS = Object.freeze(["Lens", "Must", "Common mistakes", "Do not write", "Length"]);
23
+ const LIST_SECTIONS = new Set(["Must", "Common mistakes", "Do not write"]);
24
+ // A kind, or <kind>.<variant>. Checked before any path is built.
25
+ export const GUIDE_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)?$/;
26
+
27
+ export const guidesDir = (vault) => join(vault, LAYOUT.guides);
28
+ export const packageGuidesDir = (root = pluginRoot()) => join(root, "scaffold", "guides");
29
+
30
+ const usageError = (msg) => Object.assign(new Error(msg), { code: "USAGE" });
31
+
32
+ export function checkGuideName(name) {
33
+ if (typeof name !== "string" || !GUIDE_NAME.test(name))
34
+ throw usageError(`guide takes a kind such as \`spec\` or \`story.test\`, not "${name ?? ""}"`);
35
+ return name;
36
+ }
37
+
38
+ // A file read that never throws: an iCloud placeholder, a directory named
39
+ // spec.md or a permission error is "unreadable", reported, not a crash.
40
+ function readText(p) {
41
+ try {
42
+ if (!statSync(p).isFile()) return { error: "not a file" };
43
+ return { text: readFileSync(p, "utf8").replace(/\r\n/g, "\n") };
44
+ } catch (e) {
45
+ return { error: e && e.code === "ENOENT" ? "absent" : `unreadable (${e && e.code ? e.code : "error"})` };
46
+ }
47
+ }
48
+
49
+ // The sections of a guide body: `## <name>` headings outside fences. A list
50
+ // section is its items; Lens and Length are their trimmed text. A section that
51
+ // is absent is null; a heading that is not one of the five is ignored.
52
+ function sectionsOf(body) {
53
+ const raw = {};
54
+ let cur = null;
55
+ for (const line of linesOutsideFences(body)) {
56
+ const h = line.match(/^##\s+(.+?)\s*$/);
57
+ if (h) {
58
+ cur = GUIDE_SECTIONS.includes(h[1]) ? h[1] : null;
59
+ if (cur) raw[cur] = [];
60
+ continue;
61
+ }
62
+ if (cur) raw[cur].push(line);
63
+ }
64
+ const sections = {};
65
+ for (const s of GUIDE_SECTIONS) {
66
+ if (!raw[s]) sections[s] = null;
67
+ else if (LIST_SECTIONS.has(s)) sections[s] = guideItems(raw[s]);
68
+ else sections[s] = raw[s].join("\n").trim() || null;
69
+ }
70
+ return { sections, raw };
71
+ }
72
+
73
+ const intOrNull = (v) => {
74
+ const n = Number(v);
75
+ return v !== null && v !== undefined && v !== "" && Number.isInteger(n) ? n : null;
76
+ };
77
+ const boolOrNull = (v) => (v === "true" ? true : v === "false" ? false : null);
78
+
79
+ // The parse rule (decision 1): frontmatter whose guide_for equals the file's
80
+ // name, and a ## Must with at least one item.
81
+ export function parseGuide(text, name) {
82
+ if (!/^---\n/.test(text)) return { ok: false, reason: "no frontmatter" };
83
+ const { data, body } = parseFrontmatter(text);
84
+ if (data.guide_for !== name)
85
+ return { ok: false, reason: `guide_for is "${data.guide_for ?? ""}", not "${name}"`, fm: data };
86
+ const { sections, raw } = sectionsOf(body);
87
+ if (!sections.Must || sections.Must.length === 0) return { ok: false, reason: "## Must has no item", fm: data };
88
+ return { ok: true, fm: data, sections, raw, body };
89
+ }
90
+
91
+ // The candidates for a name, in decision 2's order: vault variant, package
92
+ // variant, vault base, package base. `source` keeps one side.
93
+ function candidates(name, { vault, root, source }) {
94
+ const base = name.includes(".") ? name.split(".")[0] : null;
95
+ const names = base ? [name, base] : [name];
96
+ const out = [];
97
+ for (const n of names) {
98
+ if (vault && source !== "package") out.push({ name: n, source: "vault", path: join(guidesDir(vault), `${n}.md`) });
99
+ if (source !== "vault") out.push({ name: n, source: "package", path: join(packageGuidesDir(root), `${n}.md`) });
100
+ }
101
+ return out;
102
+ }
103
+
104
+ // The resolved guide, or null when no candidate parses. Every vault file that
105
+ // exists and does not parse is a warning, and the next candidate is tried.
106
+ export function resolveGuide(name, { vault = null, root = pluginRoot(), source = null } = {}) {
107
+ checkGuideName(name);
108
+ const warnings = [];
109
+ for (const c of candidates(name, { vault, root, source })) {
110
+ const r = readText(c.path);
111
+ if (r.error === "absent") continue;
112
+ if (r.error) {
113
+ if (c.source === "vault") warnings.push(`skipped ${LAYOUT.guides}/${c.name}.md: ${r.error}`);
114
+ continue;
115
+ }
116
+ const g = parseGuide(r.text, c.name);
117
+ if (!g.ok) {
118
+ if (c.source === "vault") warnings.push(`skipped ${LAYOUT.guides}/${c.name}.md: ${g.reason}`);
119
+ continue;
120
+ }
121
+ return {
122
+ kind: name,
123
+ resolved: c.name,
124
+ source: c.source,
125
+ path: c.path,
126
+ guide_version: c.source === "package" ? intOrNull(g.fm.guide_version) : null,
127
+ based_on: intOrNull(g.fm.based_on),
128
+ default_review: boolOrNull(g.fm.default_review),
129
+ sections: g.sections,
130
+ warnings,
131
+ text: r.text,
132
+ raw: g.raw,
133
+ };
134
+ }
135
+ return { kind: name, resolved: null, warnings };
136
+ }
137
+
138
+ // The names that have a guide on either side (for the "no guide" message).
139
+ export function guideKinds({ vault = null, root = pluginRoot() } = {}) {
140
+ const names = new Set();
141
+ const scan = (dir, side) => {
142
+ let list;
143
+ try {
144
+ list = readdirSync(dir);
145
+ } catch {
146
+ return;
147
+ }
148
+ for (const f of list) {
149
+ if (!f.endsWith(".md") || f.startsWith(".")) continue;
150
+ const n = f.slice(0, -3);
151
+ if (!GUIDE_NAME.test(n)) continue;
152
+ const r = readText(join(dir, f));
153
+ if (side === "vault" && (r.error || !parseGuide(r.text, n).ok)) continue;
154
+ names.add(n);
155
+ }
156
+ };
157
+ scan(packageGuidesDir(root), "package");
158
+ if (vault) scan(guidesDir(vault), "vault");
159
+ return [...names].sort();
160
+ }
161
+
162
+ // The JSON result of the read (decision 3, plus default_review at the plan
163
+ // gate): the internals (text, raw) stay out.
164
+ export function guideResult(g) {
165
+ return {
166
+ kind: g.kind,
167
+ source: g.source,
168
+ path: g.path,
169
+ guide_version: g.guide_version,
170
+ based_on: g.based_on,
171
+ default_review: g.default_review,
172
+ sections: g.sections,
173
+ warnings: g.warnings,
174
+ };
175
+ }
176
+
177
+ // The text form: a header line, then the guide's body or one raw section.
178
+ export function renderGuide(g, section = null) {
179
+ const head = `guide ${g.resolved} · source ${g.source} · ${g.path}\n`;
180
+ if (!section) return head + "\n" + g.text.replace(/\n*$/, "\n");
181
+ if (!g.raw[section]) return head + `\n(no ## ${section} in this guide)\n`;
182
+ return head + `\n## ${section}\n` + g.raw[section].join("\n").replace(/\n*$/, "\n");
183
+ }
184
+
185
+ // ─── eject: the one writer ─────────────────────────────────────────────
186
+ //
187
+ // Copies a package guide into <vault>/guides/<name>.md with `based_on` set to
188
+ // its guide_version, create-only (decision 5). A plan first, so the preview
189
+ // and the write are the same thing.
190
+
191
+ export function planEject(name, { vault, root = pluginRoot() } = {}) {
192
+ checkGuideName(name);
193
+ const src = join(packageGuidesDir(root), `${name}.md`);
194
+ const target = vault ? join(guidesDir(vault), `${name}.md`) : null;
195
+ const refuse = (why) => ({ ok: false, name, target, refusal: why });
196
+ if (!vault || !existsSync(vault) || !statSync(vault).isDirectory())
197
+ return refuse("the binding names no vault directory to write the guide into");
198
+ const r = readText(src);
199
+ if (r.error) return refuse(`the package has no guide named "${name}" (eject copies a package guide)`);
200
+ const dir = guidesDir(vault);
201
+ if (existsSync(dir) && !statSync(dir).isDirectory())
202
+ return refuse(`${LAYOUT.guides} exists in the vault and is not a folder`);
203
+ if (existsSync(target)) return refuse(`${LAYOUT.guides}/${name}.md already exists; eject never overwrites it`);
204
+ const version = intOrNull(parseFrontmatter(r.text).data.guide_version);
205
+ const content = r.text.replace(/^(guide_version:.*)$/m, `$1\nbased_on: ${version}`);
206
+ return { ok: true, name, target, content, based_on: version };
207
+ }
208
+
209
+ export function applyEject(plan) {
210
+ if (!plan.ok) return { written: false };
211
+ mkdirSync(join(plan.target, ".."), { recursive: true });
212
+ // Create-only for real (lib.mjs's exclusive create): a file made meanwhile
213
+ // is never replaced.
214
+ if (!createFileExclusive(plan.target, plan.content))
215
+ return { written: false, refusal: `${plan.target} appeared meanwhile` };
216
+ return { written: true };
217
+ }
@@ -746,6 +746,8 @@ export const LAYOUT = Object.freeze({
746
746
  // The vault's own, unrelated files under the same name (ADR-007 decision 4; sessions).
747
747
  vaultConfig: ".projectstore.json",
748
748
  vaultSessions: "sessions",
749
+ // <vault>/guides/: per-kind authoring guide overrides (the authoring-guides ADR, decision 2).
750
+ guides: "guides",
749
751
  });
750
752
  // The header both the legacy and the new state .gitignore carry — how
751
753
  // uninstall recognises a state directory as ours (layout spec, contract 6).
@@ -14,6 +14,7 @@ import {
14
14
  mkdirSync,
15
15
  utimesSync,
16
16
  unlinkSync,
17
+ linkSync,
17
18
  renameSync,
18
19
  rmSync,
19
20
  realpathSync,
@@ -506,6 +507,26 @@ export function writeFileAtomic(p, content, { sweep = true } = {}) {
506
507
  }
507
508
  }
508
509
 
510
+ // Create a file only if it is absent, atomically: the content goes to the
511
+ // same dot-prefixed temp writeFileAtomic uses, and a hard link puts it at
512
+ // the target, which fails EEXIST when the target exists — a file made
513
+ // meanwhile is never replaced. Returns false on EEXIST; other errors throw.
514
+ export function createFileExclusive(p, content) {
515
+ const tmp = join(dirname(p), `.${basename(p)}.${process.pid}.tmp`);
516
+ writeFileSync(tmp, content, "utf8");
517
+ try {
518
+ linkSync(tmp, p);
519
+ return true;
520
+ } catch (e) {
521
+ if (e && e.code === "EEXIST") return false;
522
+ throw e;
523
+ } finally {
524
+ try {
525
+ unlinkSync(tmp);
526
+ } catch {}
527
+ }
528
+ }
529
+
509
530
  // Write metadata into a descriptor the caller acquired with O_EXCL. The
510
531
  // exclusive create is the lock; keeping this tiny write in lib preserves the
511
532
  // repository's single write boundary without weakening the atomic lock race.
@@ -896,6 +917,17 @@ export function envFlag(env, name) {
896
917
  return v !== undefined && v !== null && v !== "" && !["0", "false"].includes(String(v).toLowerCase());
897
918
  }
898
919
 
920
+ // The one package in `npm pack --json`'s answer: an array of one entry up to
921
+ // npm 11, an object keyed by the package's name from npm 12. Here, not in
922
+ // scripts/version-guard.mjs: packaging/shells.mjs reads it too, and an import
923
+ // of the guard from there is a cycle (the guard loads shells.mjs while its own
924
+ // top-level await is pending, and Node exits 13).
925
+ export function packEntry(answer) {
926
+ const [pkg] = Array.isArray(answer) ? answer : Object.values(answer ?? {});
927
+ if (!pkg || !Array.isArray(pkg.files)) throw new Error("no package entry with a file list");
928
+ return pkg;
929
+ }
930
+
899
931
  // The files a package ships, as the release gate defines them — package.json
900
932
  // files[] plus npm's always-included package.json, README and LICENSE — copied
901
933
  // from `from` to `to`. Never node_modules, never a symlink (a symlink is a
@@ -1835,6 +1867,24 @@ export function storiesAttributionRe() {
1835
1867
  return new RegExp(`[—–-]\\s*${keywordRe("stories").source}\\s*[::]\\s*(.+)$`, "i");
1836
1868
  }
1837
1869
 
1870
+ // A test cites a spec contract with `[<key>#<n>]` (the spec policy ADR,
1871
+ // Decisions 4 and 8): <key> is the spec's id or alias, <n> the contract
1872
+ // number in ASCII — `4'` for 4′, `4''` for 4″, `4/1''` for a step nested
1873
+ // under contract 4. The closing bracket ends the token, so #4 never matches
1874
+ // #4' or #40. The lookarounds drop a Markdown link `[x#1](…)` and a
1875
+ // wikilink `[[x#1]]`. These tokens are machine tokens: English in every
1876
+ // locale, never in the heading registry.
1877
+ export const CITATION_EXAMPLE_KEY = "example";
1878
+ export function citationTokenRe() {
1879
+ return /(?<!\[)\[([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+'*(?:\/\d+'*)?)\](?![(\]])/g;
1880
+ }
1881
+ // A loose ERE for git's side of the scan; citationTokenRe decides.
1882
+ export const CITATION_PREFILTER = "\\[[A-Za-z0-9][A-Za-z0-9._-]*#[0-9]";
1883
+ // A contract number as a spec writes it (`4′`, `1″`), in the token's ASCII.
1884
+ export function contractNumberAscii(n) {
1885
+ return String(n).replace(/″/g, "''").replace(/′/g, "'");
1886
+ }
1887
+
1838
1888
  // The body footer (`*Last updated: 2026-01-01*`) is content rather than a heading,
1839
1889
  // but the lifecycle gates keep it in step with frontmatter `updated:`. Matching
1840
1890
  // accepts every registered language; the rewrite preserves the file's OWN prefix
@@ -1890,7 +1940,8 @@ export function listOf(fm, key) {
1890
1940
  // would defeat the whole point. Keys: spec_policy ("required"|"optional"),
1891
1941
  // lifecycle_gates ("on"|"off"), spec_policy_since (ISO-8601, stamped whenever
1892
1942
  // spec_policy becomes "required" from anything else; kept otherwise — the
1893
- // configure spec, contract 7).
1943
+ // configure spec, contract 7), gates_since (stamped when lifecycle_gates
1944
+ // turns on; the configure spec, contract 7 as amended 2026-11-08).
1894
1945
  export function vaultConfigPath(vault) {
1895
1946
  return join(vault, LAYOUT.vaultConfig);
1896
1947
  }
@@ -1931,9 +1982,113 @@ export function nextVaultConfig(before, patch, now = new Date().toISOString()) {
1931
1982
  const prev = before.spec_policy_since;
1932
1983
  next.spec_policy_since = prev && String(prev) > now ? prev : now;
1933
1984
  }
1985
+ // gates_since (the spec policy ADR, Decision 18a): the date the lifecycle
1986
+ // checks start counting from under any spec policy. Stamped when the gates
1987
+ // turn on, and when they are set on again with no stamp yet, so a vault
1988
+ // already on can get its date. Same never-earlier rule as above.
1989
+ if (patch.lifecycle_gates === "on" && (before.lifecycle_gates !== "on" || !before.gates_since)) {
1990
+ const prev = before.gates_since;
1991
+ next.gates_since = prev && String(prev) > now ? prev : now;
1992
+ }
1934
1993
  return next;
1935
1994
  }
1936
1995
 
1996
+ // The date the legacy predicate reads: spec_policy_since, else gates_since.
1997
+ // Spec coverage itself reads only spec_policy_since.
1998
+ export function legacySince(vaultCfg) {
1999
+ return (vaultCfg && (vaultCfg.spec_policy_since || vaultCfg.gates_since)) || null;
2000
+ }
2001
+
2002
+ export function lifecycleGatesOn(vaultCfg) {
2003
+ return ["on", "true"].includes(String((vaultCfg && vaultCfg.lifecycle_gates) || "off").toLowerCase());
2004
+ }
2005
+
2006
+ // A story's declared opt-out from a spec (Decision 13). `declared` when the
2007
+ // key is present at all; `reason` is its text, trimmed, "" when empty.
2008
+ export function noSpecOf(fm) {
2009
+ if (!fm || fm.no_spec == null || fm.no_spec === "null") {
2010
+ return { declared: false, reason: "" };
2011
+ }
2012
+ return { declared: true, reason: String(fm.no_spec ?? "").trim() };
2013
+ }
2014
+
2015
+ // `doctor --policy required[@<date>]` (Decision 18): the overlay a dry run
2016
+ // evaluates the vault with. A bare date means UTC midnight; none means now.
2017
+ export function parseDryRunPolicy(value, now = new Date().toISOString()) {
2018
+ const m = String(value || "").match(/^required(?:@(.+))?$/);
2019
+ if (!m) return { error: `--policy takes required or required@<date>, not "${value}"` };
2020
+ if (!m[1]) return { policy: { spec_policy: "required", spec_policy_since: now } };
2021
+ // ISO only: a date (UTC midnight), or a full timestamp with its zone.
2022
+ const iso = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;
2023
+ if (!iso.test(m[1])) return { error: `--policy: "${m[1]}" is not an ISO date (YYYY-MM-DD)` };
2024
+ const d = /^\d{4}-\d{2}-\d{2}$/.test(m[1]) ? `${m[1]}T00:00:00.000Z` : m[1];
2025
+ const t = Date.parse(d);
2026
+ if (!Number.isFinite(t)) return { error: `--policy: "${m[1]}" is not a date` };
2027
+ return { policy: { spec_policy: "required", spec_policy_since: new Date(t).toISOString() } };
2028
+ }
2029
+
2030
+ // A checklist item read together with its wrapped continuation lines: the
2031
+ // lines after `- [x] …` indented deeper than its dash, nested bullets
2032
+ // included (a criterion that lists cases ends with the evidence on its last
2033
+ // bullet). `— evidence:` on a wrapped line belongs to the item.
2034
+ export function checklistItems(lines) {
2035
+ const items = [];
2036
+ let cur = null;
2037
+ for (const line of lines) {
2038
+ const m = line.match(/^(\s*)-\s*\[( |x|X)\]\s*(.*)$/);
2039
+ if (m) {
2040
+ cur = { checked: m[2].toLowerCase() === "x", text: m[3], indent: m[1].length };
2041
+ items.push(cur);
2042
+ continue;
2043
+ }
2044
+ if (cur && /^\s+\S/.test(line) && line.match(/^\s*/)[0].length > cur.indent) {
2045
+ cur.text += " " + line.trim();
2046
+ continue;
2047
+ }
2048
+ cur = null;
2049
+ }
2050
+ return items;
2051
+ }
2052
+
2053
+ // A guide's rule items (the authoring-guides ADR, decision 1): plain bullets,
2054
+ // not checkboxes. An item is its bullet line plus the lines indented deeper
2055
+ // than its dash (wrapped text and nested bullets); a bullet at the same or a
2056
+ // lesser depth starts the next item; a blank or an unindented line ends it.
2057
+ // The caller drops fenced lines first (linesOutsideFences).
2058
+ export function guideItems(lines) {
2059
+ const items = [];
2060
+ let cur = null;
2061
+ for (const line of lines) {
2062
+ const m = line.match(/^(\s*)-\s+(\S.*)$/);
2063
+ if (m && (!cur || m[1].length <= cur.indent)) {
2064
+ cur = { text: m[2].trim(), indent: m[1].length };
2065
+ items.push(cur);
2066
+ continue;
2067
+ }
2068
+ if (cur && /^\s+\S/.test(line) && line.match(/^\s*/)[0].length > cur.indent) {
2069
+ cur.text += " " + line.trim();
2070
+ continue;
2071
+ }
2072
+ cur = null;
2073
+ }
2074
+ return items.map((i) => i.text);
2075
+ }
2076
+
2077
+ // RAW lines outside fenced blocks — for checks that must both MATCH (fence-
2078
+ // immune) and REPORT the line verbatim (backticks intact in the message).
2079
+ export function linesOutsideFences(s) {
2080
+ const out = [];
2081
+ let fenced = false;
2082
+ for (const line of s.split("\n")) {
2083
+ if (/^\s*```/.test(line)) {
2084
+ fenced = !fenced;
2085
+ continue;
2086
+ }
2087
+ if (!fenced) out.push(line);
2088
+ }
2089
+ return out;
2090
+ }
2091
+
1937
2092
  // The one writer of the vault config: atomic, and every key it was not asked
1938
2093
  // to change is kept as it was.
1939
2094
  export function writeVaultConfig(vault, cfg) {
@@ -3576,6 +3731,13 @@ export function isSourcePath(absPath, projectDir, vaultPath) {
3576
3731
  return !(vaultPath && vaultLocation(absPath, vaultPath));
3577
3732
  }
3578
3733
 
3734
+ // A test file, for the opt-out's size check only (Decision 15): tests do not
3735
+ // weigh. Not part of SOURCE_IGNORE — the entry-rule hook and diff-refs count
3736
+ // a test edit as source.
3737
+ export function isTestPath(rel) {
3738
+ return /(^|\/)(test|tests|__tests__)(\/|$)/.test(rel) || /\.(test|spec)\.[^/]+$/.test(rel);
3739
+ }
3740
+
3579
3741
  export function scoreDir(projectDir, sessionId) {
3580
3742
  return join(stateDir(projectDir), `${sessionId}.paths`);
3581
3743
  }
@@ -2,9 +2,15 @@
2
2
  // projectstore — mcp-server.mjs
3
3
  //
4
4
  // The MCP server's entry: what the plugin's .mcp.json runs, as `node
5
- // <plugin root>/scripts/mcp-server.mjs --project <the host's project>`. It
6
- // parses --project and starts the server through mcp.mjs's serveSupplied,
7
- // the path the CLI's `mcp` verb takes too, so the two entries serve alike.
5
+ // <plugin root>/scripts/mcp-server.mjs` with no other argument. The project
6
+ // comes from the directory the host declares in the server's environment
7
+ // (projectRootDeclared), since 0.30.9: Anthropic's plugin portal blocks any
8
+ // variable but the plugin root in a server's command (PS-DIRECTORY: "The MCP
9
+ // server's entry names no variable but ${CLAUDE_PLUGIN_ROOT}…"). That
10
+ // directory comes before PROJECTSTORE_PROJECT_DIR, as 0.30.8's --project
11
+ // did; --project still wins, for a test or a start by hand. It starts the
12
+ // server through mcp.mjs's serveSupplied, the path the CLI's `mcp` verb
13
+ // takes too, so the two entries serve alike.
8
14
  // It lives under scripts/, never bin/: a file in the plugin's top-level bin/
9
15
  // is on the host's Bash PATH, and it imports nothing from cli.mjs, so its
10
16
  // imports reach no install verb (the PS-DIRECTORY story "The MCP server's
@@ -17,6 +23,7 @@
17
23
 
18
24
  import { parseArgs } from "node:util";
19
25
  import { serveSupplied } from "./mcp.mjs";
26
+ import { projectRootDeclared } from "./harness.mjs";
20
27
 
21
28
  let values;
22
29
  try {
@@ -30,4 +37,4 @@ try {
30
37
  process.stderr.write(`mcp-server: ${e.message} — it takes --project <dir> alone\n`);
31
38
  process.exitCode = 2;
32
39
  }
33
- if (values) process.exitCode = await serveSupplied({ project: values.project ?? null });
40
+ if (values) process.exitCode = await serveSupplied({ project: values.project ?? projectRootDeclared(process.env) });
@@ -62,7 +62,7 @@ export const isErrorExit = (code) => code !== 0 && code !== 1;
62
62
  export const PROTOCOL_VERSIONS = Object.freeze(["2025-11-25", "2025-06-18"]);
63
63
  export { DOCTOR_TIMEOUT_MS };
64
64
  export const SERVER_NAME = "projectstore";
65
- export const TOOL_CEILING = 8;
65
+ export const TOOL_CEILING = 9; // amended by the authoring-guides ADR, decision 8
66
66
  export const TOOL_LIST_TOKEN_CEILING = 3000; // ADR decision 7, chars/4
67
67
  export const RESOURCE_SCHEME = "projectstore://";
68
68
 
@@ -205,8 +205,31 @@ export const TOOLS = Object.freeze({
205
205
  inputSchema: schema({
206
206
  install: bool("only the install section"),
207
207
  vault: bool("only the vault section"),
208
+ policy: str("a dry run of the vault section: required, or required@<date>; writes nothing"),
209
+ }),
210
+ argv: (a) => ({
211
+ opts: [...flag("install", a.install), ...flag("vault", a.vault), ...opt("policy", a.policy)],
212
+ positionals: [],
213
+ }),
214
+ },
215
+ // The ninth tool (the authoring-guides ADR, decision 8, amending the MCP
216
+ // surface ADR's decision 7): the read half of `guide`; eject is not served.
217
+ guide: {
218
+ verb: "guide",
219
+ description:
220
+ "An artifact kind's authoring guide (Lens, Must, Common mistakes, Do not write, Length). Call it before drafting an artifact of that kind and before reviewing one; the vault's override wins over the package default.",
221
+ inputSchema: schema(
222
+ {
223
+ kind: str("a kind (adr, spec, epic, story, …) or <kind>.<variant>, such as story.test"),
224
+ section: str("one section: Lens, Must, Common mistakes, Do not write or Length"),
225
+ source: { type: "string", enum: ["vault", "package"], description: "read one side only" },
226
+ },
227
+ ["kind"],
228
+ ),
229
+ argv: (a) => ({
230
+ opts: [...opt("section", a.section), ...opt("source", a.source)],
231
+ positionals: [a.kind],
208
232
  }),
209
- argv: (a) => ({ opts: [...flag("install", a.install), ...flag("vault", a.vault)], positionals: [] }),
210
233
  },
211
234
  });
212
235
 
@@ -332,7 +355,11 @@ export function createServer({
332
355
  ).error,
333
356
  };
334
357
  // An option value that starts with "-" would read as a flag to the CLI's parser; a positional is safe behind "--".
335
- if (typeof v === "string" && v.startsWith("-") && ["section", "status", "direction", "selector"].includes(k))
358
+ if (
359
+ typeof v === "string" &&
360
+ v.startsWith("-") &&
361
+ ["section", "status", "direction", "selector", "source", "kind"].includes(k)
362
+ )
336
363
  return { error: rpcError(null, E_INVALID_PARAMS, `${name}: "${k}" may not start with "-"`).error };
337
364
  }
338
365
  // The verb table decides who runs unbound: status and doctor do (doctor
@@ -1,7 +1,8 @@
1
1
  // projectstore — read-verbs.mjs
2
2
  //
3
3
  // The read-verb runner: the handlers of the verbs that write nothing (status,
4
- // orientation, search, show, graph, codemap, doctor and version), and
4
+ // orientation, search, show, graph, codemap, doctor and version, and the read
5
+ // half of guide, whose eject only the CLI serves), and
5
6
  // runRead(), which dispatches through the one verb table (scripts/verbs.mjs)
6
7
  // with these handlers alone. The CLI's run() hands dispatch() these and its
7
8
  // write handlers; the MCP server (scripts/mcp.mjs) runs runRead() and imports
@@ -21,8 +22,10 @@ import { resolve, dirname } from "node:path";
21
22
  import { fileURLToPath } from "node:url";
22
23
  import * as term from "./term.mjs";
23
24
  import { doctorFallbackText } from "./lib.mjs";
24
- import { READ_OPERATIONS, LINEAGE_KINDS } from "./query.mjs";
25
- import { dispatch, envelope, packageVersion, usageFail, ownEnv, runVersion } from "./verbs.mjs";
25
+ import { READ_OPERATIONS, LINEAGE_KINDS, oneOf } from "./query.mjs";
26
+ import { normaliseVaultPath } from "./binding.mjs";
27
+ import { GUIDE_SECTIONS, checkGuideName, resolveGuide, guideKinds, guideResult, renderGuide } from "./guides.mjs";
28
+ import { dispatch, envelope, packageVersion, usageFail, ownEnv, runVersion, PACKAGE_ROOT } from "./verbs.mjs";
26
29
 
27
30
  const HERE = dirname(fileURLToPath(import.meta.url));
28
31
  export const DOCTOR_SCRIPT = resolve(HERE, "doctor.mjs");
@@ -111,6 +114,57 @@ async function runCodemap(ctx) {
111
114
  }
112
115
  }
113
116
 
117
+ // ─── guide ─────────────────────────────────────────────────────────────
118
+ //
119
+ // The read half of the guide row (the authoring-guides ADR, decision 3): the
120
+ // resolved guide, vault override first. `eject` writes, so this runner, which
121
+ // the MCP server runs, refuses it; the CLI serves it with its own handler.
122
+
123
+ // The vault the binding names, as scaffold and eject read it; null when the
124
+ // project is unbound or names no usable path (the package side still answers).
125
+ export function guideVault(cfg, project) {
126
+ const norm = cfg && cfg.vault_path ? normaliseVaultPath(cfg.vault_path, project) : null;
127
+ return typeof norm === "string" ? norm : null;
128
+ }
129
+
130
+ async function runGuide(ctx) {
131
+ const { row, values, positionals, cfg, project, stdout, stderr } = ctx;
132
+ const usage = (m) => usageFail(Object.assign(new Error(m), { code: "USAGE" }), { verb: row.verb, ...ctx });
133
+ const vault = guideVault(cfg, project);
134
+ if (positionals[0] === "eject")
135
+ return usage("guide eject writes; the read-only runner does not serve it. Run it from a terminal in the project");
136
+ if (values.write) return usage("--write belongs to guide eject");
137
+ const name = positionals[0];
138
+ if (!name) return usage(`guide takes a kind: ${guideKinds({ vault, root: PACKAGE_ROOT }).join(", ")}`);
139
+ try {
140
+ checkGuideName(name);
141
+ const source = oneOf("source", values.source, ["vault", "package"], null);
142
+ const section = values.section ?? null;
143
+ if (section !== null && !GUIDE_SECTIONS.includes(section))
144
+ throw Object.assign(new Error(`--section takes one of: ${GUIDE_SECTIONS.join(", ")}`), { code: "USAGE" });
145
+ const g = resolveGuide(name, { vault, root: PACKAGE_ROOT, source });
146
+ if (!g.resolved) {
147
+ const why = `no guide for "${name}"${source ? ` on the ${source} side` : ""}. Kinds with a guide: ${guideKinds({ vault, root: PACKAGE_ROOT }).join(", ")}`;
148
+ if (values.json)
149
+ stdout.write(
150
+ JSON.stringify(envelope(row.verb, project, false, { error: why, warnings: g.warnings }), null, 2) + "\n",
151
+ );
152
+ else stderr.write(why + "\n");
153
+ return 1;
154
+ }
155
+ for (const w of g.warnings) if (!values.json) stderr.write(`guide: ${w}\n`);
156
+ if (values.json) {
157
+ const result = guideResult(g);
158
+ if (section) result.sections = { [section]: g.sections[section] };
159
+ stdout.write(JSON.stringify(envelope(row.verb, project, true, result), null, 2) + "\n");
160
+ } else stdout.write(renderGuide(g, section));
161
+ return 0;
162
+ } catch (e) {
163
+ if (e && e.code === "USAGE") return usageFail(e, { verb: row.verb, ...ctx });
164
+ throw e;
165
+ }
166
+ }
167
+
114
168
  // ─── doctor ────────────────────────────────────────────────────────────
115
169
  //
116
170
  // Spawned, never imported (MCP ADR decision 2): doctor's main writes to
@@ -127,6 +181,7 @@ export const doctorArgs = (values) => [
127
181
  DOCTOR_SCRIPT,
128
182
  "--json",
129
183
  ...[values.install && "--install", values.vault && "--vault"].filter(Boolean),
184
+ ...(values.policy ? ["--policy", String(values.policy)] : []),
130
185
  ];
131
186
 
132
187
  // Where the child runs: in the project when it exists — a project that does
@@ -265,6 +320,7 @@ export const READ_HANDLERS = Object.freeze({
265
320
  show: readVerb("show"),
266
321
  graph: runGraph,
267
322
  codemap: runCodemap,
323
+ guide: runGuide,
268
324
  doctor: runDoctor,
269
325
  version: runVersion,
270
326
  });
@@ -42,7 +42,7 @@ import { packageCommand } from "./harness.mjs";
42
42
 
43
43
  const README = "README.md";
44
44
 
45
- const kindsOf = (layout) => [...new Set((layout.folders || []).map((f) => f.kind))];
45
+ export const kindsOf = (layout) => [...new Set((layout.folders || []).map((f) => f.kind))];
46
46
  const usable = (v) => typeof v === "string" && v.trim() !== "";
47
47
  const pathKind = (p) => {
48
48
  try {