projectstore-claude 0.30.8 → 0.30.9

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.30.8",
+      "version": "0.30.9",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.30.8",
+  "version": "0.30.9",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/.mcp.json

@@ -3,11 +3,7 @@
     "projectstore": {
       "type": "stdio",
       "command": "node",
-      "args": [
-        "${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.mjs",
-        "--project",
-        "${CLAUDE_PROJECT_DIR}"
-      ]
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.mjs"]
     }
   }
 }

package/node_modules/projectstore/README.md

@@ -240,7 +240,7 @@ Each setting has exactly one writer, and the plan says which file it changes:
 
 - **The agents' models and efforts** live in `.projectstore/harness/<harness>.json`. That file is committed, so a change there is a team change.
 - **The status line, the band, the language and the other binding keys** live in `.projectstore/projectstore.json`, which stays on this machine.
-- **The spec policy and the lifecycle gates** live in the vault's `.projectstore.json`, which commits with the vault. Setting `spec_policy=required` records when it took effect; stories closed before then are exempt.
+- **The spec policy and the lifecycle gates** live in the vault's `.projectstore.json`, which commits with the vault. Setting `spec_policy=required` records when it took effect; stories closed before then are exempt. A spec's contracts can carry WHEN/THEN scenarios, and a test can cite a contract, so doctor can report the contracts no test covers: see [`docs/contracts-and-tests.md`](./docs/contracts-and-tests.md).
 
 The vault itself is changed by `bind --rebind`, which configure names when asked. In a Claude Code session, `/projectstore:statusline` and `/projectstore:agents configure` run the same writers.
 
@@ -398,7 +398,7 @@ ProjectStore has no server, no account and no telemetry. It collects nothing abo
 ### What it runs
 
 - **Node.js.** The hooks, the MCP server, the status line and the `projectstore` command are Node.js scripts in the plugin. They start other scripts of the plugin through the same Node. When setup keeps a project on its git-marketplace copy, it runs that copy's own `bin/projectstore.mjs` to read the copy's plan and, once you confirm, to apply it.
-- **git**, on this machine only. ProjectStore never commits, pushes, pulls or fetches. The SessionStart hook runs `git rev-parse` in a project that is not bound, to see whether it is a worktree of a bound checkout; no other hook starts a program. Bind, init and setup run `git rev-parse --show-toplevel` to find the repository and `git init` to give a new vault its own repository. They run `git config --get user.name` to propose the default author; the binding keeps it, and each new artifact names it as its author. Doctor runs `git check-ignore` and `git ls-files` to check what git ignores and tracks, and `git diff --name-only` and `git log` to see what has changed. The reviewer's list of the files a story touched comes from `git diff` and `git log` too. The reviewer and archaeologist agents read the project's git history (`git status` and `git diff` or `git log` among others) through the agent's own tools, as any command the agent runs.
+- **git**, on this machine only. ProjectStore never commits, pushes, pulls or fetches. The SessionStart hook runs `git rev-parse` in a project that is not bound, to see whether it is a worktree of a bound checkout; no other hook starts a program. Bind, init and setup run `git rev-parse --show-toplevel` to find the repository and `git init` to give a new vault its own repository. They run `git config --get user.name` to propose the default author; the binding keeps it, and each new artifact names it as its author. Doctor runs `git check-ignore` and `git ls-files` to check what git ignores and tracks, `git diff --name-only` and `git log` to see what has changed, and `git grep --untracked` to find the tests that cite a spec's contracts. The reviewer's list of the files a story touched comes from `git diff` and `git log` too. The reviewer and archaeologist agents read the project's git history (`git status` and `git diff` or `git log` among others) through the agent's own tools, as any command the agent runs.
 - **The agent CLIs, `claude` and `codex`.** Setup, install, upgrade and uninstall run their plugin commands, such as `plugin marketplace add` and `plugin install` to register ProjectStore or `plugin uninstall` to remove it. Each one runs after you confirm the plan, which shows it verbatim. The model menu of `configure` also runs `codex debug models` to read Codex's model list, which Codex refreshes over the network with its own login.
 - **npm**, from setup, install and upgrade only. They run `npm config get registry` to learn which registry your npm uses. When they set up Codex, they also run `npm install` with `--ignore-scripts` to fetch the `projectstore-codex` package at the running version into a folder in ProjectStore's cache, because the Codex plugin ships in that package. No install script of that package runs.
 - **The band above the prompt** (Claude Code) is a module that runs inside Claude Code's own process, not in Node. It reads the binding, the session's pointer and its epic's files, and writes a heartbeat, `.band-<session id>.json` under `.projectstore/state/sessions/`, while it draws; it starts no program and makes no request. It watches agent starts (`agent.spawn`), each agent's requests and tool calls, and each turn's end, only to show a ProjectStore agent's row. It passes each of these on unchanged, and it changes no agent, permission or setting.
@@ -488,7 +488,7 @@ npx projectstore bind ~/vaults/other --rebind
 
 ## Extending
 
-See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills, and [`docs/harnesses.md`](./docs/harnesses.md) for which coding agents projectstore runs on — what "experimental" means there, and what adding one takes.
+See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills, [`docs/contracts-and-tests.md`](./docs/contracts-and-tests.md) for linking a spec's contracts to tests, and [`docs/harnesses.md`](./docs/harnesses.md) for which coding agents projectstore runs on — what "experimental" means there, and what adding one takes.
 
 ## Contributing
 

package/node_modules/projectstore/agents/planner.md

@@ -69,6 +69,12 @@ generic best practice — cite the real files and patterns you found.
    state, ordering, prior fixes this change could regress.
 6. **Tests** — where new tests go, the harness/fixtures to reuse (cite), the
    cases that matter — mapped to the story's acceptance criteria when given.
+   A covering spec's contract may carry `- WHEN … THEN …` scenario items: list
+   them as the test cases to write, and say each new test cites its contract
+   with a token `[<spec id or alias>#<n>]` in its name or a comment beside it
+   (written here as `[example#3]`; never put a real spec's token in a plan or
+   doc — doctor would count it). A contract marked `(verified: live)` or
+   `(verified: manual)` is checked outside the test suite: name how.
 7. **Plan** — a short ordered step list the engineer can follow.
 8. **Proposed `code_refs`** — the paths/globs this epic (and story) will own once
    implemented, ready for `/projectstore:codemap set`. You PROPOSE; the command

package/node_modules/projectstore/agents/reviewer.md

@@ -62,6 +62,15 @@ Code that satisfies no criterion: flag as scope creep, gently. A story is
   or accidental?
 - **Tests** — do new/changed paths have tests that ASSERT the behavior? Run them
   cheaply when checkable (read-only).
+- **Contract citations** — a new test that covers a covering spec's contract
+  cites it with `[<spec id or alias>#<n>]` (written here as `[example#3]`).
+  Each of these is a finding:
+  - a new test that covers a contract and cites nothing;
+  - a citation on a test that does not assert the contract's observable
+    outcome — an empty or trivially passing test with a token is worse than no
+    token;
+  - a real token outside the tests (docs, README, plans, code that is not a
+    test), because doctor counts it as coverage. Docs use only `example`.
 
 ## Discovery ≠ filtering
 Report every finding, severity + confidence annotated; recall is your job,
@@ -79,7 +88,8 @@ say so plainly.
 2. **Acceptance matrix** — one line per criterion: status + evidence. Include
    the covering specs' attributed + unattributed acceptance items (additive).
    Format each evidence value so it can be persisted verbatim into the story
-   file at close: `— evidence: <test | command | file:line>` — the close gate
+   file at close: `— evidence: <test | command | file:line>` (a test may be
+   named by its contract token, `[example#3]`, which doctor checks) — the close gate
    (`/projectstore:story close`) copies your matrix into the checkboxes.
 3. **Findings** — severity-rated: `🔴 blocker` / `🟡 should-fix` / `🟢 nit`; each
    with file:line, confidence, why it matters, and a specific fix.

package/node_modules/projectstore/docs/contracts-and-tests.md

@@ -0,0 +1,107 @@
+# Contracts and tests
+
+A spec's behavioral contracts are numbered and testable. This page shows how
+to write a contract so a test follows from it, how a test cites the contract
+it covers, and what doctor reports. It describes Part A of the ADR *Spec
+policy, revised: contract scenarios and test citations that doctor counts,
+and a declared per-story opt-out from a spec*.
+
+All of it is optional. A spec without scenarios, and a test without a
+citation, stay valid.
+
+Every example on this page uses the key `example`. It is reserved: no spec
+may use it as an id or alias, so a token written with it never resolves and
+never counts as coverage. A real token in a doc would count, so docs use only
+`example`.
+
+## Scenarios under a contract
+
+A contract may carry list items that start with `WHEN`, `GIVEN`, `AND` or
+`THEN`:
+
+```markdown
+3. **A stale index is reported.** Doctor compares each folder index with the
+   artifacts on disk and reports a row that no longer matches.
+   - GIVEN an index row whose status differs from the artifact's frontmatter
+   - WHEN doctor runs with --vault
+   - THEN it reports an index finding that names the folder
+```
+
+The items are a list, so Markdown keeps one step per line. The keywords stay
+in English in every language, like `— stories:`: a tool matches them
+literally.
+
+Doctor reads scenarios for one thing only. If a contract's scenario has no
+`WHEN` (or `GIVEN`), or no `THEN`, it reports an info.
+
+## A contract no test can cover
+
+Some contracts are checked on a real host after install, or by a person.
+Mark them in the contract's first paragraph:
+
+```markdown
+7. **The band draws in a live session.** (verified: live)
+```
+
+Use `(verified: live)` or `(verified: manual)`. Doctor does not count a
+marked contract as uncovered.
+
+## Citing a contract from a test
+
+A test cites a contract with a bracketed token, `[<key>#<n>]`, in its name or
+in a comment beside it:
+
+```js
+// [example#3]
+test("doctor reports a stale index row", () => {
+  // … assert the finding names the folder
+});
+```
+
+- `<key>` is the spec's frontmatter `id`, or its `alias`. Matching is
+  case-sensitive.
+- `<n>` is the contract number in ASCII: `0`, `4`, `4'` for `4′`, `4''` for
+  `4″`. A step nested under contract 4 is `4/1''`. A cited step does not
+  cover its parent.
+- The closing bracket ends the token, so `[example#4]` never matches
+  contract `4'` or `40`. A token followed by `(` is a Markdown link, and a
+  `[[…]]` is a wikilink. Neither is a citation.
+
+A slug id runs to about 60 characters, so give a spec a short alias in its
+frontmatter:
+
+```yaml
+alias: billing
+```
+
+Its tests then cite its contracts with `billing` as the key. (This page
+writes that out in words rather than as a token, because a token in a doc
+is scanned like one in a test.)
+
+An alias is frozen like a slug, because renaming it breaks every citation.
+Two specs may not share an alias, and an alias may not be another spec's id.
+
+A citation is a claim: the reviewer checks that a cited test asserts the
+contract's outcome. An empty test with a token is a review finding.
+
+## What doctor reports
+
+Doctor (`--vault`) scans the bound project with `git grep --untracked`, so a
+test you have not added yet is found too. `.gitignore`d files, a vault
+inside the project, `node_modules/` and the other generated paths are
+skipped. Tests outside the bound project, or in a submodule, are not seen.
+
+| Finding | Level | When |
+|---|---|---|
+| `contract-coverage` | info | One line per active spec. With no citation: "N contracts, 0 cited". Once a spec has a citation, or sets `coverage: report` in its frontmatter: the contracts no test cites |
+| `citation-unknown` | warn | A token whose key is no spec's id or alias, or whose number is not a contract of that spec |
+| `citation-superseded` | info | A token that cites a superseded spec |
+| `scenario-shape` | info | A scenario without a WHEN/GIVEN or a THEN |
+| `spec-alias` | issue | A duplicate alias, an alias equal to another spec's id, or the reserved `example` |
+| `evidence-citation` | warn | Under `lifecycle_gates: on`: a story's evidence names a token that no file in the project carries |
+
+Each report names the checkout it read. A worktree on an old branch, or a
+second project bound to the same vault, can see different coverage.
+
+Doctor never runs a test. CI and `npm test` do that. Doctor checks the
+record: which contracts are cited, and whether a cited token still exists.

package/node_modules/projectstore/harnesses/claude-code.json

@@ -311,9 +311,9 @@
       "dir": ".",
       "file": ".mcp.json",
       "entry": "scripts/mcp-server.mjs",
-      "entry_reason": "The script .mcp.json runs, under the plugin root, with --project and the host's project directory as its only arguments. It lives under scripts/, never bin/ (a plugin's top-level bin/ is on the host's Bash PATH), and imports nothing from cli.mjs, so the server's imports reach no install verb (PS-DIRECTORY, the story \"The MCP server's entry reaches no install verb through a read-verb runner that shares the CLI's verb table…\"; the MCP ADR's decision 1 as amended). The CLI's `mcp` verb serves the same way, for a host without a plugin channel.",
+      "entry_reason": "The script .mcp.json runs, under the plugin root, with no other argument: the project comes from CLAUDE_PROJECT_DIR, which the host exports to the server (launch.project_dir_in_env), since 0.30.9 (PS-DIRECTORY, the story \"The MCP server's entry names no variable but ${CLAUDE_PLUGIN_ROOT}…\"). It lives under scripts/, never bin/ (a plugin's top-level bin/ is on the host's Bash PATH), and imports nothing from cli.mjs, so the server's imports reach no install verb (PS-DIRECTORY, the story \"The MCP server's entry reaches no install verb through a read-verb runner that shares the CLI's verb table…\"; the MCP ADR's decision 1 as amended). The CLI's `mcp` verb serves the same way, for a host without a plugin channel.",
       "scope": "plugin",
-      "scope_reason": "Claude Code loads a plugin's .mcp.json from the plugin installation itself and expands ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} in it per session, so the one shipped file binds each server to one project (MCP ADR decision 6, amended 2026-09-05); nothing is installed and nothing is derived — the host kind install-harness skips, which the install spec's contract 0 does not yet name.",
+      "scope_reason": "Claude Code loads a plugin's .mcp.json from the plugin installation itself and expands ${CLAUDE_PLUGIN_ROOT} in it and exports CLAUDE_PROJECT_DIR to the server per session, so the one shipped file binds each server to one project (MCP ADR decision 6, amended 2026-09-05); nothing is installed and nothing is derived — the host kind install-harness skips, which the install spec's contract 0 does not yet name.",
       "launch": {
         "cwd": "project",
         "project_dir_in_env": true,
@@ -326,7 +326,7 @@
         ],
         "default_syntax": "${VAR:-default}",
         "unset_placeholder_in_env": "literal",
-        "unset_placeholder_in_args": "inferred literal — the server refuses a --project still carrying a dollar-brace placeholder",
+        "unset_placeholder_in_args": "inferred literal — measured through the 0.30.8 form, which the server refused as a placeholder",
         "entrypoint": "sdk-cli (headless -p), plugin loaded with --plugin-dir; the marketplace install and an interactive session are A9's",
         "protocol_era": "initialize",
         "protocol_version_seen": "2025-11-25",

package/node_modules/projectstore/harnesses/codex.json

@@ -240,7 +240,7 @@
       "kind": "host",
       "scope": "project",
       "scope_reason": "Codex auto-discovers a plugin-root .mcp.json even when the manifest does not declare mcpServers — measured.",
-      "why_unsupported": "Our .mcp.json is in Claude Code's dialect: its argv carries ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR}, which nothing substitutes there, so the server failed its handshake and printed a red error in every session. Ships only once the Codex dialect is rendered and the spike's criterion (h) says what cwd and environment the server receives."
+      "why_unsupported": "Our .mcp.json is in Claude Code's dialect: its argv needs ${CLAUDE_PLUGIN_ROOT} expanded, which nothing substitutes there, and the server needs CLAUDE_PROJECT_DIR in its environment, which Codex does not export. With its earlier argv, which named the project variable too, the server failed its handshake and printed a red error in every session. Ships only once the Codex dialect is rendered and the spike's criterion (h) says what cwd and environment the server receives."
     },
     "skills": {
       "supported": true,

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.8",
+  "version": "0.30.9",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/diff-refs.mjs

@@ -64,6 +64,45 @@ export function lastCommitMs(cwd = projectRoot()) {
   return Number.isFinite(t) ? t : null;
 }
 
+// The citation scan (the spec policy ADR, Decision 7): every line in the
+// project, untracked files included, that looks like a contract citation.
+// `.gitignore` is honoured, `exclude` paths (the vault, when it sits inside
+// the project) are skipped, and SOURCE_IGNORE paths are dropped. Unlike gitIn
+// this tells "no match" (status ok, no lines) from "not a repository"
+// (no-git) and from every other failure — no git binary, a timeout, an exit
+// git explains on stderr (unknown, with that reason): only the first is an
+// answer.
+export function grepProjectLines(cwd, pattern, { exclude = [], timeout = 10000, ignore = IGNORE } = {}) {
+  const args = [
+    "grep",
+    "--untracked",
+    "-n",
+    "-I",
+    "-E",
+    "-e",
+    pattern,
+    "--",
+    ".",
+    ...exclude.map((p) => `:(exclude)${p}`),
+  ];
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error?.code === "ENOENT") return { status: "unknown", reason: "git is not installed", lines: [] };
+  if (r.error || r.signal) return { status: "unknown", reason: "the scan timed out", lines: [] };
+  if (r.status === 1) return { status: "ok", lines: [] };
+  if (/not a git repository/i.test(r.stderr || "")) return { status: "no-git", lines: [] };
+  if (r.status !== 0) {
+    const why = (r.stderr || "").trim().split("\n")[0] || `git exited ${r.status}`;
+    return { status: "unknown", reason: why, lines: [] };
+  }
+  const lines = [];
+  for (const raw of r.stdout.split("\n")) {
+    const m = raw.match(/^(.*?):(\d+):(.*)$/);
+    if (!m || ignore.some((rx) => rx.test(m[1]))) continue;
+    lines.push({ file: m[1], line: Number(m[2]), text: m[3] });
+  }
+  return { status: "ok", lines };
+}
+
 function filterFiles(list) {
   return [...new Set(list)]
     .map((f) => f.trim())

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/lib.mjs

@@ -896,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
@@ -1835,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/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.

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

@@ -34,7 +34,15 @@ cubiertas: una historia se cierra cuando ambos están en verde (ADR-007).
 ## Contratos de comportamiento
 
 <!-- Numerados, verificables uno a uno. Cada uno describe un resultado observable, no un paso de implementación.
-     Para un spike de investigación: preguntas a responder + criterios de salida. -->
+     Para un spike de investigación: preguntas a responder + criterios de salida.
+     Opcional, bajo un contrato: escenarios que una prueba puede seguir, y una
+     marca para un contrato que ninguna prueba puede cubrir. Las palabras clave
+     quedan en inglés:
+       - WHEN … THEN …
+       (verified: live)   o   (verified: manual)
+     Una prueba cita un contrato así: [example#1] — el id o alias de la spec y
+     el número del contrato. El frontmatter puede añadir `alias: <clave-corta>`
+     y `coverage: report`. Ver docs/contracts-and-tests.md. -->
 
 1.
 2.

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

@@ -34,7 +34,15 @@ couvertes : une story n'est finie que si les deux sont au vert (ADR-007).
 ## Contrats de comportement
 
 <!-- Numérotés, testables un par un. Chacun énonce un résultat observable, pas une étape d'implémentation.
-     Pour un spike de recherche : questions à trancher + critères de sortie. -->
+     Pour un spike de recherche : questions à trancher + critères de sortie.
+     Facultatif, sous un contrat : des scénarios qu'un test peut suivre, et une
+     marque pour un contrat qu'aucun test ne peut couvrir. Les mots-clés restent
+     en anglais :
+       - WHEN … THEN …
+       (verified: live)   ou   (verified: manual)
+     Un test cite un contrat ainsi : [example#1] — l'id ou l'alias de la spec,
+     puis le numéro du contrat. Le frontmatter peut ajouter `alias: <clé-courte>`
+     et `coverage: report`. Voir docs/contracts-and-tests.md. -->
 
 1.
 2.

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

@@ -34,7 +34,14 @@ reviewed_at: null
 ## Контракты поведения
 
 <!-- Нумерованные, проверяемые по одному. Каждый — наблюдаемый результат, не шаг реализации.
-     Для research-спайка: вопросы, на которые надо ответить + критерии выхода. -->
+     Для research-спайка: вопросы, на которые надо ответить + критерии выхода.
+     По желанию, под контрактом: сценарии, по которым пишется тест, и пометка
+     для контракта, который тестом не проверить. Ключевые слова — по-английски:
+       - WHEN … THEN …
+       (verified: live)   или   (verified: manual)
+     Тест ссылается на контракт так: [example#1] — id или alias спеки и номер
+     контракта. Во frontmatter можно добавить `alias: <короткий-ключ>` и
+     `coverage: report`. Подробнее: docs/contracts-and-tests.md. -->
 
 1.
 2.

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

@@ -34,7 +34,14 @@ story 才算完成（ADR-007）。
 ## 行为契约
 
 <!-- 编号列出，逐条可测。每条描述可观察的结果，而不是实现步骤。
-     若是研究性 spike：需要回答的问题 + 退出条件。 -->
+     若是研究性 spike：需要回答的问题 + 退出条件。
+     可选，写在契约下方：测试可以照着写的场景，以及无法用测试覆盖的契约的标记。
+     关键字保持英文：
+       - WHEN … THEN …
+       (verified: live)   或   (verified: manual)
+     测试这样引用契约：[example#1]，即 spec 的 id 或 alias，加上契约编号。
+     frontmatter 可以加 `alias: <短键>` 和 `coverage: report`。
+     详见 docs/contracts-and-tests.md。 -->
 
 1.
 2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.8",
+  "version": "0.30.9",
   "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.30.8"
+    "projectstore": "=0.30.9"
   },
   "bundleDependencies": [
     "projectstore"