projectstore-claude 0.30.7 → 0.30.9

package/node_modules/projectstore/scripts/doctor.mjs

@@ -40,6 +40,10 @@ import {
   indexHeaderRe,
   evidenceSuffixRe,
   storiesAttributionRe,
+  citationTokenRe,
+  contractNumberAscii,
+  CITATION_EXAMPLE_KEY,
+  CITATION_PREFILTER,
   slugIdentity,
   isLegacyNumberedId,
   storyMatchesEntry,
@@ -124,7 +128,7 @@ import { effortSpec } from "./model-spec.mjs";
 // story "The prompt surface asks the shell for a variable the host would have
 // substituted"; harness neutrality is unaffected, an absolute path carries no
 // brand, and --harness still carries the target.
-import { uncommittedProjectFiles, lastCommitMs } from "./diff-refs.mjs";
+import { uncommittedProjectFiles, lastCommitMs, grepProjectLines } from "./diff-refs.mjs";
 import { resolveBinding } from "./worktree.mjs";
 import { missingScaffoldRequirements } from "./scaffold.mjs";
 
@@ -2675,6 +2679,351 @@ export function checkLifecycleGates(artifacts, vaultCfg) {
   return out;
 }
 
+// ─── Contract scenarios and citations (the spec policy ADR, Part A) ───
+
+// A spec's Behavioral contracts as data. A contract is a top-level numbered
+// item (`4.`, `4′.`, `0.`) in the contracts section; its first nested
+// numbered level is its steps; deeper levels belong to their parent. HTML
+// comments are stripped first, so a template's example `1.` inside a comment
+// is not a contract. Scenario items are `- WHEN|GIVEN|AND|THEN …` list items
+// under a contract; the `(verified: live|manual)` marker is looked for in the
+// contract's first paragraph, which a wrapped bold heading may span.
+export function parseSpecContracts(spec) {
+  const sec = sectionOf(spec.body || "", "spec_contracts");
+  if (sec === null) return null;
+  const lines = linesOutsideFences(sec.replace(/<!--[\s\S]*?-->/g, ""));
+  const contracts = [];
+  let cur = null;
+  let inFirstPara = false;
+  for (const line of lines) {
+    const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
+    if (top) {
+      cur = {
+        n: contractNumberAscii(top[1]),
+        steps: new Set(),
+        stepIndent: null,
+        scenarios: [],
+        marker: null,
+        first: line,
+      };
+      contracts.push(cur);
+      inFirstPara = true;
+      continue;
+    }
+    if (!cur) continue;
+    if (/^\s*$/.test(line)) {
+      inFirstPara = false;
+      continue;
+    }
+    if (inFirstPara) cur.first += " " + line.trim();
+    const step = line.match(/^(\s+)(\d+[′″']*)\.(\s|$)/);
+    if (step) {
+      if (cur.stepIndent === null) cur.stepIndent = step[1].length;
+      if (step[1].length === cur.stepIndent) cur.steps.add(contractNumberAscii(step[2]));
+      continue;
+    }
+    const sc = line.match(/^\s*-\s+(WHEN|GIVEN|AND|THEN)\b/);
+    if (sc) cur.scenarios.push(line.trim());
+  }
+  for (const c of contracts) {
+    const mk = c.first.match(/\(verified\s*[:：]\s*(live|manual)\)/);
+    c.marker = mk ? mk[1] : null;
+    delete c.first;
+    delete c.stepIndent;
+  }
+  return contracts;
+}
+
+// Key → spec, by frontmatter id and alias, exact and case-sensitive. Not
+// buildSpecResolver: its filename fallback is lower-cased, and a citation
+// token resolves only to what a spec declares.
+function citationKeys(artifacts) {
+  const keys = new Map();
+  for (const s of artifacts.filter((a) => a.kind === "spec")) {
+    for (const k of [String(s.fm.id || ""), String(s.fm.alias || "")]) {
+      if (k && k !== "null" && !keys.has(k)) keys.set(k, s);
+    }
+  }
+  return keys;
+}
+
+// Alias rules (Decision 5): unique across specs, never another spec's id,
+// never the reserved example key. An alias is frozen like a slug.
+export function checkSpecAliases(artifacts) {
+  const out = [];
+  const specs = artifacts.filter((a) => a.kind === "spec");
+  const ids = new Map(specs.map((s) => [String(s.fm.id || ""), s]));
+  const seen = new Map();
+  for (const s of specs) {
+    const id = String(s.fm.id || "");
+    if (id === CITATION_EXAMPLE_KEY) {
+      out.push(
+        finding(
+          "vault",
+          "issue",
+          "spec-alias",
+          `Spec id "${id}" is the reserved citation key — docs use it for tokens that never resolve.`,
+          s.rel,
+        ),
+      );
+    }
+    const alias = s.fm.alias && s.fm.alias !== "null" ? String(s.fm.alias) : null;
+    if (!alias) continue;
+    if (alias === CITATION_EXAMPLE_KEY) {
+      out.push(
+        finding(
+          "vault",
+          "issue",
+          "spec-alias",
+          `Spec alias "${alias}" is the reserved citation key — pick another.`,
+          s.rel,
+        ),
+      );
+    } else if (ids.has(alias) && ids.get(alias) !== s) {
+      out.push(
+        finding(
+          "vault",
+          "issue",
+          "spec-alias",
+          `Spec alias "${alias}" is another spec's id (${ids.get(alias).rel}) — a citation would be ambiguous.`,
+          s.rel,
+        ),
+      );
+    } else if (seen.has(alias)) {
+      out.push(
+        finding(
+          "vault",
+          "issue",
+          "spec-alias",
+          `Spec alias "${alias}" is also the alias of ${seen.get(alias).rel} — a citation would be ambiguous.`,
+          s.rel,
+        ),
+      );
+    }
+    if (!seen.has(alias)) seen.set(alias, s);
+  }
+  return out;
+}
+
+// Scenario shape (Decision 3): a contract's scenario items need a WHEN (or
+// GIVEN) and a THEN. That is the only reading of scenarios.
+export function checkScenarioShape(artifacts) {
+  const out = [];
+  for (const s of artifacts.filter((a) => a.kind === "spec")) {
+    for (const c of parseSpecContracts(s) || []) {
+      if (!c.scenarios.length) continue;
+      const when = c.scenarios.some((l) => /^-\s+(WHEN|GIVEN)\b/.test(l));
+      const then = c.scenarios.some((l) => /^-\s+THEN\b/.test(l));
+      if (!when || !then) {
+        out.push(
+          finding(
+            "vault",
+            "info",
+            "scenario-shape",
+            `Contract ${c.n}'s scenario has no ${!when ? "WHEN (or GIVEN)" : "THEN"} step.`,
+            s.rel,
+          ),
+        );
+      }
+    }
+  }
+  return out;
+}
+
+// The one scan per doctor run: every citation-shaped line in the bound
+// project, skipping the vault when it sits inside it. null = no active spec
+// with contracts, so nothing was scanned (and git never ran).
+export function scanCitations(cfg, artifacts, proj, grep = grepProjectLines) {
+  const active = artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active");
+  if (!active.some((s) => (parseSpecContracts(s) || []).length)) return null;
+  const exclude = [];
+  try {
+    const p = realpathSync.native(proj);
+    const v = realpathSync.native(cfg.vault_path);
+    const rel = relative(p, v);
+    if (rel && !rel.startsWith("..") && !rel.startsWith("/")) exclude.push(rel);
+  } catch {}
+  const r = grep(proj, CITATION_PREFILTER, { exclude });
+  const tokens = [];
+  // A token written with the spec's own primes (`#4′`) is not a citation; it
+  // is kept, flagged, so the check can say "write it in ASCII" instead of
+  // dropping it silently.
+  const typographic = /(?<!\[)\[([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+[′″']*(?:\/\d+[′″']*)?)\](?![(\]])/g;
+  for (const { file, line, text } of r.lines) {
+    for (const m of text.matchAll(citationTokenRe())) tokens.push({ key: m[1], n: m[2], file, line });
+    for (const m of text.matchAll(typographic)) {
+      if (/[′″]/.test(m[2])) tokens.push({ key: m[1], n: m[2], file, line, typographic: true });
+    }
+  }
+  return { status: r.status, reason: r.reason || null, tokens, checkout: basename(proj) };
+}
+
+// Unknown tokens and coverage (Decisions 8 and 9). Coverage is quiet: a spec
+// nothing cites gets one line; the uncited list appears only once a spec has
+// a citation, or sets `coverage: report`. A marked contract is not counted,
+// and a cited step does not cover its parent.
+export function checkContractCitations(artifacts, scan) {
+  if (!scan) return [];
+  if (scan.status === "no-git") {
+    return [
+      finding(
+        "vault",
+        "info",
+        "contract-coverage",
+        "Contract coverage not checked — the bound project is not a git repository.",
+      ),
+    ];
+  }
+  if (scan.status === "unknown") {
+    return [
+      finding(
+        "vault",
+        "info",
+        "contract-coverage",
+        `Contract coverage not checked — ${scan.reason || "the citation scan did not finish"}.`,
+      ),
+    ];
+  }
+  const out = [];
+  const keys = citationKeys(artifacts);
+  const contractsOf = new Map();
+  const cited = new Map();
+  const citedIn = new Map();
+  for (const t of scan.tokens) {
+    if (t.key === CITATION_EXAMPLE_KEY) continue;
+    const where = `${t.file}:${t.line}`;
+    if (t.typographic) {
+      out.push(
+        finding(
+          "vault",
+          "warn",
+          "citation-unknown",
+          `[${t.key}#${t.n}] uses typographic primes — write the number in ASCII: [${t.key}#${contractNumberAscii(t.n)}].`,
+          where,
+        ),
+      );
+      continue;
+    }
+    const spec = keys.get(t.key);
+    if (!spec) {
+      out.push(
+        finding(
+          "vault",
+          "warn",
+          "citation-unknown",
+          `[${t.key}#${t.n}] names no spec id or alias (a typo, or a renamed alias?).`,
+          where,
+        ),
+      );
+      continue;
+    }
+    if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
+    const [top, step] = t.n.split("/");
+    const c = contractsOf.get(spec).find((x) => x.n === top);
+    if (!c || (step && !c.steps.has(step))) {
+      out.push(
+        finding("vault", "warn", "citation-unknown", `[${t.key}#${t.n}] — ${spec.rel} has no contract ${t.n}.`, where),
+      );
+      continue;
+    }
+    if (String(spec.fm.status || "") === "superseded") {
+      out.push(
+        finding(
+          "vault",
+          "info",
+          "citation-superseded",
+          `[${t.key}#${t.n}] cites a superseded spec (${spec.rel}) — move it to the successor.`,
+          where,
+        ),
+      );
+    }
+    if (!step) {
+      if (!cited.has(spec)) cited.set(spec, new Set());
+      cited.get(spec).add(top);
+    }
+    if (!citedIn.has(spec)) citedIn.set(spec, new Set());
+    citedIn.get(spec).add(t.file);
+  }
+  // `--json` carries the files that cite each spec, so a valid token in a doc
+  // (which counts as coverage) is easy to find (Decision 8).
+  const withCites = (f, s) => {
+    if (citedIn.has(s)) f.cites = [...citedIn.get(s)].sort();
+    return f;
+  };
+  for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
+    const contracts = contractsOf.get(s) || parseSpecContracts(s) || [];
+    if (!contracts.length) continue;
+    const got = cited.get(s) || new Set();
+    if (!got.size && String(s.fm.coverage || "") !== "report") {
+      out.push(
+        finding(
+          "vault",
+          "info",
+          "contract-coverage",
+          `${contracts.length} contracts, 0 cited (checkout ${scan.checkout}).`,
+          s.rel,
+        ),
+      );
+      continue;
+    }
+    const open = contracts.filter((c) => !c.marker && !got.has(c.n)).map((c) => c.n);
+    if (open.length) {
+      out.push(
+        withCites(
+          finding(
+            "vault",
+            "info",
+            "contract-coverage",
+            `${open.length} of ${contracts.length} contracts uncited (checkout ${scan.checkout}): ${open.join(", ")}.`,
+            s.rel,
+          ),
+          s,
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+// Evidence that cites a contract (Decision 10), behind lifecycle_gates: on.
+// A token not found in the project is a warn for a story in progress or in
+// review, and for a done story that is not legacy. Free-text evidence is
+// never checked, and doctor never runs a test.
+export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
+  const gates = String(vaultCfg.lifecycle_gates || "off").toLowerCase();
+  if (!["on", "true"].includes(gates) || !scan || scan.status !== "ok") return [];
+  const since = vaultCfg.spec_policy_since || null;
+  const present = new Set(scan.tokens.map((t) => `${t.key}#${t.n}`));
+  const evidenceRe = evidenceSuffixRe();
+  const out = [];
+  for (const story of artifacts.filter((a) => a.kind === "story")) {
+    const st = String(story.fm.status || "").toLowerCase();
+    if (!["in-progress", "in_progress", "review", "done"].includes(st)) continue;
+    if (st === "done" && isLegacyStory(story.fm, since)) continue;
+    const acc = sectionOf(story.body, "acceptance");
+    if (acc === null) continue;
+    for (const line of linesOutsideFences(acc)) {
+      const m = line.match(/^\s*-\s*\[(x|X)\]\s*(.*)$/);
+      if (!m) continue;
+      const at = m[2].search(evidenceRe);
+      if (at === -1) continue;
+      for (const t of m[2].slice(at).matchAll(citationTokenRe())) {
+        if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`)) continue;
+        out.push(
+          finding(
+            "vault",
+            "warn",
+            "evidence-citation",
+            `Evidence cites [${t[1]}#${t[2]}], which no file in checkout ${scan.checkout} carries (a renamed or removed test, or an older branch?).`,
+            story.rel,
+          ),
+        );
+      }
+    }
+  }
+  return out;
+}
+
 // Suggestion for existing binds: specs exist but no vault policy declared.
 export function checkVaultPolicy(cfg, layout, artifacts, vaultCfg) {
   const out = [];
@@ -3237,7 +3586,7 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
   return foldIntoMove(out);
 }
 
-export function runVaultChecks(cfg) {
+export function runVaultChecks(cfg, { proj = projectRoot(), grep = grepProjectLines } = {}) {
   let layout;
   try {
     layout = loadLayout(cfg.layout);
@@ -3258,6 +3607,12 @@ export function runVaultChecks(cfg) {
     () => checkSpecCoverage(artifacts, vaultCfg, layout),
     () => checkSpecAcceptance(layout, artifacts, vaultCfg),
     () => checkLifecycleGates(artifacts, vaultCfg),
+    () => checkSpecAliases(artifacts),
+    () => checkScenarioShape(artifacts),
+    () => {
+      const scan = scanCitations(cfg, artifacts, proj, grep);
+      return [...checkContractCitations(artifacts, scan), ...checkEvidenceCitations(artifacts, vaultCfg, scan)];
+    },
   ];
   for (const step of guarded) {
     try {
@@ -3274,8 +3629,8 @@ export function runVaultChecks(cfg) {
     ...checkArtifactIdentity(layout, vaultFiles, artifacts),
     ...checkArtifactNames(vaultFiles),
     ...checkExternalRefsForm(artifacts),
-    ...checkCodeRefs(artifacts, projectRoot()),
-    ...checkWorkWithoutStory(cfg, projectRoot()),
+    ...checkCodeRefs(artifacts, proj),
+    ...checkWorkWithoutStory(cfg, proj),
     ...checkCodeMap(cfg),
     ...checkGraph(cfg),
   );
@@ -3363,7 +3718,7 @@ async function main() {
   }
   if (vault && cfg && cfg.vault_path && existsSync(cfg.vault_path)) {
     groups.push("vault");
-    findings.push(...runVaultChecks(cfg));
+    findings.push(...runVaultChecks(cfg, { proj }));
   } else if (vault) {
     groups.push("vault");
     findings.push(finding("vault", "info", "vault", "Vault checks skipped — no usable vault (see install issues)."));

package/node_modules/projectstore/scripts/fetch-shell.mjs

@@ -214,8 +214,12 @@ export function npmError(stdout, stderr) {
 
 const seconds = (ms) => `${Number((ms / 1000).toFixed(ms % 1000 ? 1 : 0))} s`;
 
-// npm's own registry: the one README's registry-mirror advice names.
+// npm's own registry: the one README's registry-mirror advice names, and the
+// plugin's one spelling of it.
 export const PUBLIC_REGISTRY = "https://registry.npmjs.org";
+// npm's default: what the installer's registry read (readLatest) and its
+// registry comparison use when the user's own registry cannot be resolved.
+export const DEFAULT_REGISTRY = `${PUBLIC_REGISTRY}/`;
 
 // A registry that has no such shell may be a mirror that has not synced it:
 // the run once more, from npm's public registry, in README's form — the

package/node_modules/projectstore/scripts/harness.mjs

@@ -473,6 +473,38 @@ export function stopCarrierProblem(manifest) {
   return null;
 }
 
+// ─── The PreCompact carrier (generation spec, contract 17; skeleton spec,
+// contract 22, both as amended 2026-10-28) ─────────────────────────────
+//
+// How hooks/pre-compact.mjs prints its one line. Claude Code discards a
+// PreCompact systemMessage and echoes the hook's raw stdout in the /compact
+// output instead (measured 2026-10-28), so there the line goes out as plain
+// text. Null — nothing identified, or no carrier measured — keeps the
+// {"systemMessage"} object the hook has always printed: a plain line on a host
+// whose schema refuses it would be a failed hook, and an unchanged object is
+// not. The same identified-only rule as stopCarrier, for the same reason.
+export const PRECOMPACT_CARRIERS = Object.freeze(["stdout"]);
+export function preCompactCarrier(env = process.env, dir = MANIFEST_DIR) {
+  const id = identifiedHarnessId(env, dir);
+  const carrier = id ? loadHarness(id, dir)?.output_channels?.PreCompact?.carrier : null;
+  return PRECOMPACT_CARRIERS.includes(carrier) ? carrier : null;
+}
+
+// What is wrong with a manifest's PreCompact row, or null. The key is present
+// on every row (null when nothing is measured), and a carrier is only ever
+// chosen from a measured row.
+export function preCompactCarrierProblem(manifest) {
+  const row = manifest?.output_channels?.PreCompact;
+  if (row === null || row === undefined) return null;
+  if (typeof row !== "object") return "output_channels.PreCompact is not an object";
+  if (!("carrier" in row)) return "output_channels.PreCompact has no carrier (null when none is measured)";
+  if (![...PRECOMPACT_CARRIERS, null].includes(row.carrier))
+    return `output_channels.PreCompact.carrier ${JSON.stringify(row.carrier)} is not one of ${PRECOMPACT_CARRIERS.join(", ")} or null`;
+  if (row.carrier !== null && row.evidence !== "measured")
+    return "output_channels.PreCompact.carrier is set on a row that is not measured";
+  return null;
+}
+
 // ─── Who a message is for (generation spec, contract 18) ───────────────
 //
 // The core prints for ONE harness at a time, and a command it names must be

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -159,6 +159,7 @@ import {
   fetchRefusal,
   fetchRunId,
   sweepFetchRuns,
+  DEFAULT_REGISTRY,
 } from "./fetch-shell.mjs";
 import { HOST_BUDGET_MS, startFailure, runHost } from "./run-host.mjs";
 import {
@@ -191,7 +192,6 @@ import {
   terminalRun,
   copyBehind,
   behindAdvice,
-  DEFAULT_REGISTRY,
   NOTICE_BUDGET_MS,
   READ_TIMEOUT_MS,
   MIN_READ_MS,

package/node_modules/projectstore/scripts/lib.mjs

@@ -54,6 +54,7 @@ import {
   whichOnPath,
   hostSessionId,
   stopCarrier,
+  preCompactCarrier,
   hostRegistry,
   autoUpdateDefault,
 } from "./harness.mjs";
@@ -194,6 +195,7 @@ export {
   speakingHarness,
   whichOnPath,
   stopCarrier,
+  preCompactCarrier,
 };
 
 // A hook's payload carries the `cwd` of the session that fired it, and on a
@@ -894,6 +896,17 @@ export function envFlag(env, name) {
   return v !== undefined && v !== null && v !== "" && !["0", "false"].includes(String(v).toLowerCase());
 }
 
+// The one package in `npm pack --json`'s answer: an array of one entry up to
+// npm 11, an object keyed by the package's name from npm 12. Here, not in
+// scripts/version-guard.mjs: packaging/shells.mjs reads it too, and an import
+// of the guard from there is a cycle (the guard loads shells.mjs while its own
+// top-level await is pending, and Node exits 13).
+export function packEntry(answer) {
+  const [pkg] = Array.isArray(answer) ? answer : Object.values(answer ?? {});
+  if (!pkg || !Array.isArray(pkg.files)) throw new Error("no package entry with a file list");
+  return pkg;
+}
+
 // The files a package ships, as the release gate defines them — package.json
 // files[] plus npm's always-included package.json, README and LICENSE — copied
 // from `from` to `to`. Never node_modules, never a symlink (a symlink is a
@@ -1833,6 +1846,24 @@ export function storiesAttributionRe() {
   return new RegExp(`[—–-]\\s*${keywordRe("stories").source}\\s*[:：]\\s*(.+)$`, "i");
 }
 
+// A test cites a spec contract with `[<key>#<n>]` (the spec policy ADR,
+// Decisions 4 and 8): <key> is the spec's id or alias, <n> the contract
+// number in ASCII — `4'` for 4′, `4''` for 4″, `4/1''` for a step nested
+// under contract 4. The closing bracket ends the token, so #4 never matches
+// #4' or #40. The lookarounds drop a Markdown link `[x#1](…)` and a
+// wikilink `[[x#1]]`. These tokens are machine tokens: English in every
+// locale, never in the heading registry.
+export const CITATION_EXAMPLE_KEY = "example";
+export function citationTokenRe() {
+  return /(?<!\[)\[([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+'*(?:\/\d+'*)?)\](?![(\]])/g;
+}
+// A loose ERE for git's side of the scan; citationTokenRe decides.
+export const CITATION_PREFILTER = "\\[[A-Za-z0-9][A-Za-z0-9._-]*#[0-9]";
+// A contract number as a spec writes it (`4′`, `1″`), in the token's ASCII.
+export function contractNumberAscii(n) {
+  return String(n).replace(/″/g, "''").replace(/′/g, "'");
+}
+
 // The body footer (`*Last updated: 2026-01-01*`) is content rather than a heading,
 // but the lifecycle gates keep it in step with frontmatter `updated:`. Matching
 // accepts every registered language; the rewrite preserves the file's OWN prefix

package/node_modules/projectstore/scripts/mcp-server.mjs

@@ -2,9 +2,15 @@
 // projectstore — mcp-server.mjs
 //
 // The MCP server's entry: what the plugin's .mcp.json runs, as `node
-// <plugin root>/scripts/mcp-server.mjs --project <the host's project>`. It
-// parses --project and starts the server through mcp.mjs's serveSupplied,
-// the path the CLI's `mcp` verb takes too, so the two entries serve alike.
+// <plugin root>/scripts/mcp-server.mjs` with no other argument. The project
+// comes from the directory the host declares in the server's environment
+// (projectRootDeclared), since 0.30.9: Anthropic's plugin portal blocks any
+// variable but the plugin root in a server's command (PS-DIRECTORY: "The MCP
+// server's entry names no variable but ${CLAUDE_PLUGIN_ROOT}…"). That
+// directory comes before PROJECTSTORE_PROJECT_DIR, as 0.30.8's --project
+// did; --project still wins, for a test or a start by hand. It starts the
+// server through mcp.mjs's serveSupplied, the path the CLI's `mcp` verb
+// takes too, so the two entries serve alike.
 // It lives under scripts/, never bin/: a file in the plugin's top-level bin/
 // is on the host's Bash PATH, and it imports nothing from cli.mjs, so its
 // imports reach no install verb (the PS-DIRECTORY story "The MCP server's
@@ -17,6 +23,7 @@
 
 import { parseArgs } from "node:util";
 import { serveSupplied } from "./mcp.mjs";
+import { projectRootDeclared } from "./harness.mjs";
 
 let values;
 try {
@@ -30,4 +37,4 @@ try {
   process.stderr.write(`mcp-server: ${e.message} — it takes --project <dir> alone\n`);
   process.exitCode = 2;
 }
-if (values) process.exitCode = await serveSupplied({ project: values.project ?? null });
+if (values) process.exitCode = await serveSupplied({ project: values.project ?? projectRootDeclared(process.env) });

package/node_modules/projectstore/scripts/term.mjs

@@ -37,9 +37,9 @@ import { createInterface, emitKeypressEvents } from "node:readline";
 
 // FORCE_COLOR decides when it is set, as Node's own tty reads it: "", "1",
 // "2", "3" or "true" turn colour on even without a terminal, anything else
-// ("0", "false") turns it off. Otherwise NO_COLOR (https://no-color.org) turns
-// colour off when set to anything non-empty, and TERM=dumb means a terminal
-// that understands no escapes.
+// ("0", "false") turns it off. Otherwise NO_COLOR turns colour off when set
+// to anything non-empty, as the NO_COLOR convention has it, and TERM=dumb means
+// a terminal that understands no escapes.
 //
 // Glyphs are a switch of their own (presentation spec contract 2): ASCII
 // under TERM=dumb or PROJECTSTORE_ASCII set non-empty, Unicode otherwise, in

package/node_modules/projectstore/scripts/touch-session.mjs

@@ -80,7 +80,7 @@ import {
 const NUDGE_INTERVAL_MS = 10 * 60 * 1000;
 
 // Per-session active pointer (ADR-006) — denormalized titles/status captured
-// after the write so the statusline renders with zero vault reads — plus the
+// after the write so the statusline renders with no read of the vault — plus the
 // raw-edit nudge (PS-IMPROVE story-003): throttled, never blocking. Both in
 // patchPointer below.
 // The session-name offer (ADR: the settled-anchor offer). Returns a line or

package/node_modules/projectstore/scripts/version-guard.mjs

@@ -33,7 +33,7 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 // Contract 2 of the atomic-regeneration work: nothing under scripts/ writes
 // directly, and tests/scripts.test.mjs enforces it by globbing this directory.
-import { writeFileAtomic } from "./lib.mjs";
+import { writeFileAtomic, packEntry } from "./lib.mjs";
 import { LAYOUT } from "./harness.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -298,14 +298,6 @@ export function unshippedTopLevel(entries, packlist) {
 // The packlist is the second release-time invariant: what npm would actually
 // ship. Stored as sorted paths only — sizes churn on every content edit and
 // would make the fixture unreviewable.
-// The one package in `npm pack --json`'s answer: an array of one entry up to
-// npm 11, an object keyed by the package's name from npm 12.
-export function packEntry(answer) {
-  const [pkg] = Array.isArray(answer) ? answer : Object.values(answer ?? {});
-  if (!pkg || !Array.isArray(pkg.files)) throw new Error("no package entry with a file list");
-  return pkg;
-}
-
 export function currentPacklist(root = ROOT) {
   const r = spawnSync("npm", ["pack", "--dry-run", "--json"], {
     cwd: root,
@@ -339,7 +331,10 @@ async function main(argv) {
     // The shells' fixtures, from the core's CURRENT pack — after the core's
     // fixture, since each lists the core's files under node_modules/. A lazy
     // import: scripts/ ships and packaging/ does not, so a static specifier
-    // here would ship a module that cannot load.
+    // here would ship a module that cannot load. Nothing shells.mjs imports
+    // may import this file back: this module is still evaluating (the
+    // top-level await below), so the import would wait on it forever and Node
+    // would exit 13. tests/shells.test.mjs walks shells.mjs's imports for it.
     const shellsModule = resolve(ROOT, "packaging", "shells.mjs");
     const shells = [];
     if (existsSync(shellsModule)) {

package/node_modules/projectstore/templates/de/spec.md.tmpl

@@ -34,7 +34,15 @@ Stories — eine Story ist erst fertig, wenn beides grün ist (ADR-007).
 ## Verhaltensverträge
 
 <!-- Nummeriert, einzeln testbar. Jeder beschreibt ein beobachtbares Ergebnis, keinen Implementierungsschritt.
-     Für einen Research-Spike: zu beantwortende Fragen + Ausstiegskriterien. -->
+     Für einen Research-Spike: zu beantwortende Fragen + Ausstiegskriterien.
+     Optional, unter einem Vertrag: Szenarien, denen ein Test folgen kann, und
+     eine Markierung für einen Vertrag, den kein Test abdeckt. Die Schlüsselwörter
+     bleiben englisch:
+       - WHEN … THEN …
+       (verified: live)   oder   (verified: manual)
+     Ein Test zitiert einen Vertrag als [example#1]: id oder alias der Spec, dann
+     die Vertragsnummer. Das Frontmatter kann `alias: <kurzer-schlüssel>` und
+     `coverage: report` ergänzen. Siehe docs/contracts-and-tests.md. -->
 
 1.
 2.

package/node_modules/projectstore/templates/en/spec.md.tmpl

@@ -34,7 +34,14 @@ Spec acceptance is **additive** to the covered stories' own acceptance criteria
 ## Behavioral contracts
 
 <!-- Numbered, individually testable. Each states an observable outcome, not an implementation step.
-     For a research spike: questions to answer + exit criteria. -->
+     For a research spike: questions to answer + exit criteria.
+     Optional, under a contract: scenario items a test can follow, and a marker
+     for a contract no test can cover. The keywords stay in English:
+       - WHEN … THEN …
+       (verified: live)   or   (verified: manual)
+     A test cites a contract as [example#1]: the spec's id or alias, then the
+     contract number. Frontmatter may add `alias: <short-key>` and
+     `coverage: report`. See docs/contracts-and-tests.md. -->
 
 1.
 2.