projectstore-claude 0.30.15 → 0.30.16

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.15",
+      "version": "0.30.16",
       "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.15",
+  "version": "0.30.16",
   "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/README.md

@@ -242,6 +242,11 @@ 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. A story whose work needs no spec can say why in `no_spec`, and `doctor --vault --policy required` shows what the policy would report before you switch it on. 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 flow policy** lives there too, under `flow`: each person's time on the project and so their WIP limit, how long work may sit in a status, and the windows for throughput and capacity. No key has a default, so a check whose key is not set does not run. People are named as stories write their assignee, never by email address, and their names, time shares and leave dates commit with the vault. These keys are set with `--set` only; the view names each form. For example:
+
+```bash
+npx projectstore configure --set flow.wip.full=3 --set 'flow.people[First Last].time=part'
+```
 
 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.
 

package/node_modules/projectstore/agents/reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: reviewer
-description: Opus (max-effort) STORY-CONFORMANCE reviewer for projectstore-bound projects — a narrow, vault-aware role, NOT a general code reviewer. Invoke AFTER writing code, BEFORE committing or marking a story done. Verifies the diff actually closes the story — per-acceptance-criterion evidence — then correctness / regressions / codebase-fit / tests, severity + confidence rated, self-audited. Proposes the story's code_refs update. Read-only, no sycophancy; it reviews and reports, never edits/stages/commits.
+description: Opus (max-effort) STORY-CONFORMANCE reviewer for projectstore-bound projects — a narrow, vault-aware role, NOT a general code reviewer. Invoke AFTER writing code, BEFORE committing or marking a story done. Verifies the diff actually closes the story — per-acceptance-criterion evidence — then correctness / regressions / codebase-fit / tests, severity + confidence rated, self-audited. Proposes the story's code_refs update. Asked for spec drift on a named active spec, it checks that spec's contracts against its covered stories' code_refs instead and reports, per contract, holds / drifted / cannot tell. Read-only, no sycophancy; it reviews and reports, never edits/stages/commits.
 model: opus
 effort: max
 tools: Read, Grep, Glob, Bash, WebFetch
@@ -11,6 +11,11 @@ context, separate from the author — so a false "looks good" can't slip through
 self-approval. A false approval costs far more than a false rejection: a story
 marked done that isn't closed is exactly the vault-rot this role exists to stop.
 
+**Which job.** Given a diff or a story, you check story conformance:
+everything in this file except the Spec-drift mode section. Asked for spec
+drift on a named spec, you run the Spec-drift mode section instead; its own
+report replaces the Output section's verdict and acceptance matrix.
+
 Inspect everything yourself: `git status`, `git diff`, `git diff --staged`, and
 read the changed files in FULL context (not just the hunks). Locate the bound
 vault (`.projectstore/projectstore.json` → `vault_path`) and read the target story —
@@ -60,6 +65,73 @@ which). With neither, that is a 🟡 should-fix, never a 🔴: the line is a hin
 not a gate, and it never holds a story open. With no line, or only its
 placeholder, say nothing about it.
 
+## Spec-drift mode
+Only when the caller asks for spec drift on a named spec. You check that spec
+against the code, one spec per run. Phases 0 to 2 and the Output section are
+the story-conformance job and do not apply; "Discovery ≠ filtering" and the
+Self-audit do.
+
+1. **Input.** Run
+   `node "${CLAUDE_PLUGIN_ROOT}/scripts/spec-drift.mjs" <spec id, alias or file stem>`,
+   with `--since <date>` when the caller names one (it overrides every
+   anchor). It prints facts as JSON: the contracts with their markers (each
+   with its story's status), removed state and anchor (the date of the
+   contract's last valid marker, else the spec's `date:`); the covered
+   stories with their status and `code_refs`, empty and missing refs listed;
+   the refs expanded to files classed `source`, `tests` or `surface`, with
+   line counts and the commits since each anchor (`changed_since`: a count
+   and the last three); the files citing each contract (`cited_by`, tests
+   normally); and the
+   scan status, `ok`, `no-git` or `unknown`. A null is unknown, not empty. A
+   spec that is not `active` is refused with exit 1: report its status and
+   stop. History is a hint: an empty one is no evidence that a contract holds.
+2. **Budget.** The report states the input size: files and lines by class,
+   and the number of contracts. When the spec has more contracts that are not
+   removed (`totals.contracts_open`) than the caller's budget, 8 when none is
+   named, return the size and the contract list (number and heading), ask
+   your caller for contract numbers and give no verdict. Given numbers (up to
+   the budget), judge those and list the rest as `not checked`.
+3. **Reading.** Pre-commit to the two or three contracts whose covered files
+   changed most since their anchor (`files_changed`, `changed_since`) and hunt
+   those first. Read by symbol: search for the function, flag, command, path
+   or token a contract names, in `source` and `surface` files alike, and read
+   around each hit; a whole file only when the contract is about all of it.
+4. **Verdicts**, one per contract judged:
+   - `holds`: a line of code, quoted verbatim with its file:line, produces the
+     contract's outcome. A line outside the bundle's files is marked
+     `(outside the bundle)`. A `holds` without a quoted line is `cannot tell`.
+   - `drifted`: the code contradicts the contract as written, a named file,
+     command or token that is gone included. Cite the contradicting line or,
+     for something missing, the search that found nothing.
+   - `cannot tell`, with its reason, such as: no covered code, a rule about
+     people or prose, a `(verified: live|manual)` contract no line can show
+     (`verified` in the bundle), a scan status of `unknown`, or code read that
+     settles nothing. When the code a contract asks for is not found and the
+     story behind its last marker has not reached `review`, the verdict is
+     `cannot tell (pending)`. A contract amended by a story in `review` or
+     `done` is judged as usual.
+   - A removed contract is listed as `removed` and not judged.
+5. **Proposals.** Each `drifted` comes with a proposal and a lean: a marker
+   carried by an open story, a new story that brings the spec to the code, or
+   a follow-up story that brings the code back; never a closed story. Each
+   goes through the normal approval-gated commands, run by the caller.
+6. **Facts, not drift.** Empty or missing `code_refs` (`refs.empty`,
+   `refs.missing`, `refs.unresolved`) and uncited contracts (`cited_by: []`)
+   are listed as facts, not drift; so are doctor's `code-refs` and
+   `contract-coverage` findings.
+7. **Report**, your last message, in place of the Output section:
+   1. **Input** — the spec (title, id, status), the bundle's `checkout`, the scan status, files and
+      lines by class, contracts judged, `not checked` and removed, and
+      `--since` when given.
+   2. **Contracts** — one row per contract: number, heading, verdict and its
+      evidence (the quoted line with file:line, the contradicting line or the
+      empty search, or the reason).
+   3. **Drift proposals** — for each `drifted`: the proposal, the lean and why.
+   4. **Facts** — empty and missing refs, uncited contracts, unknown history.
+   5. **Open Questions** — low-confidence verdicts, surfaced not blocking.
+
+   You write nothing in this mode: no vault file, no code, no story.
+
 ## Phase 0 — Pre-commitment
 From the story + file list, predict the 3-5 most likely gaps ("AC #3 needs an
 error path the diff doesn't touch"; "touches a cache — invalidation risk"). Write

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

@@ -219,6 +219,45 @@ the coverage count. Evidence in a closed story that names it is not
 reported. `graph.md` and `lineage` show an `amends` edge from the story to
 the spec.
 
+## Checking a spec against the code
+
+A spec can drift from the code after its stories close: a later story
+changes the behaviour without a marker, or the code changes outside any
+story. Ask the reviewer for spec drift on a named spec, and it checks that
+spec against the code at its covered stories' `code_refs`. Run it when the
+covered code changed since the contracts' last markers, not before every
+release.
+
+The reviewer reads a bundle of facts first:
+
+```bash
+node scripts/spec-drift.mjs example --since 2026-11-01
+```
+
+It prints JSON: each contract with its markers, removed state and anchor
+(the date of its last marker, else the spec's `date:`; `--since` overrides
+it), the tests that cite it as `[example#2]`, the covered stories and their
+`code_refs` (empty and missing ones listed), the files those refs name with
+their class (`source`, `tests` or `surface`), line counts and commits since
+each anchor, and a scan status: `ok`, `no-git` or `unknown`. A spec that is
+not `active` exits 1.
+
+The reviewer judges up to eight contracts per run unless you name another
+budget. A spec with more asks you for contract numbers first. Each contract
+judged gets one verdict:
+
+| Verdict | Means |
+|---|---|
+| `holds` | A line of code, quoted with its file:line, produces the contract's outcome |
+| `drifted` | The code contradicts the contract, or a file, command or token it names is gone; the report cites the line, or the search that found nothing |
+| `cannot tell` | With a reason: no covered code, a rule about people, a live or manual contract, an unknown scan; `cannot tell (pending)` when the code is missing and the story behind the last marker has not reached review |
+
+Each drift comes with a proposal: a marker carried by an open story, a new
+story that brings the spec to the code, or a follow-up story that brings the
+code back. Empty `code_refs` and uncited contracts are listed as facts, not
+drift. The reviewer writes nothing; every change goes through the usual
+approval-gated commands.
+
 ## What doctor reports
 
 Doctor (`--vault`) scans the bound project with `git grep --untracked`, so a

package/node_modules/projectstore/docs/extending.md

@@ -222,6 +222,16 @@ each key activates.
     warn.
 - `doctor --vault --policy required[@<date>]` shows what `required` would
   report, without writing anything.
+- `flow` holds the team's flow policy: `wip.full` and `wip.part`, a
+  `people` map from each assignee's name to `time` (`full` or `part`), an
+  optional own `wip`, `git_names` and `left`, ages in days under `age_days`,
+  and `idle_days`, `window_weeks`, `capacity_weeks` (`[low, high]`),
+  `active_epics_max` and `grooming_days`. `groomed_at` is a stamp. No key has
+  a default in code, and a value of the wrong type counts as absent. A
+  person's WIP limit is their own `wip`, else `wip.<time>`, else none
+  (`wipLimitOf` in `scripts/flow-policy.mjs`). `configure --set` writes these
+  keys and merges them into the block, keeping the rest. Names are the
+  assignee as stories write it, never an email address.
 
 ## Contributing back
 

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.15",
+  "version": "0.30.16",
   "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/configure-menu.mjs

@@ -174,6 +174,10 @@ export function menuGroups(f, settings, catalogs, { menu, now = Date.now, caps:
           "The vault's own rules, shared by everyone who uses the vault: whether a story needs a spec, and whether doctor checks a story's plan and close. Kept in the vault's .projectstore.json; commit the vault after a change.",
         items: list.map((s) => plainItem(f, s, null)),
       });
+    // The flow policy is `--set` only (the configure spec, contract 2 as
+    // amended 2026-11-10): the menu has no widget for a keyed list, and the
+    // view names each key's form. Skipped here on purpose, not forgotten.
+    else if (g === "flow") continue;
   }
   return groups;
 }

package/node_modules/projectstore/scripts/configure.mjs

@@ -31,7 +31,8 @@ import {
   fromTerminalIn,
   commandForm,
 } from "./lib.mjs";
-import { planBindingKeys, applyBindingKeys, languageNames } from "./binding.mjs";
+import { planBindingKeys, applyBindingKeys, languageNames, shellQuote } from "./binding.mjs";
+import { isFlowSet, parseFlowSet, flowRows, flowForm, blockedAt, flowAt } from "./flow-policy.mjs";
 import { bandKeys, epicIds, planBand, applyBand } from "./band.mjs";
 import { planAgentsChange, applyAgentsChange } from "./agents-change.mjs";
 import { plan as planInstall, apply as applyInstall, planOptions, isInteractive } from "./install-harness.mjs";
@@ -63,7 +64,13 @@ const parseBool = (v) => {
 };
 const onOff = (b) => (b === true ? "on" : b === false ? "off" : "not set");
 const shown = (v) =>
-  v === null || v === undefined || v === "" ? "—" : Array.isArray(v) ? v.join(", ") || "—" : String(v);
+  v === null || v === undefined || v === ""
+    ? "—"
+    : Array.isArray(v)
+      ? v.join(", ") || "—"
+      : typeof v === "object"
+        ? JSON.stringify(v)
+        : String(v);
 const tildeOf = (p, home) =>
   home && (p === home || String(p).startsWith(home + "/")) ? "~" + String(p).slice(home.length) : String(p);
 
@@ -265,6 +272,22 @@ export function settingsOf(f) {
       pol("spec_policy", v.spec_policy || "optional", "policy"),
       pol("lifecycle_gates", Object.hasOwn(v, "lifecycle_gates") ? String(v.lifecycle_gates) : "not set", "bool"),
     );
+    // The flow policy (contract 3 as amended 2026-11-10): its own group,
+    // listed only while a key is set, so a vault with no `flow` prints what it
+    // printed before. `--set` only: the menu shows none of these rows.
+    for (const r of f.vaultCfg && !f.vaultCfg.corrupt ? flowRows(v.flow) : [])
+      out.push({
+        group: "flow",
+        key: r.key,
+        value: r.value,
+        source: "vault_config",
+        file,
+        class: "changeable",
+        team: true,
+        writer: "vault",
+        rail: null,
+        person: r.person,
+      });
   }
   for (const s of out) s.set = setForm(s, f);
   return out;
@@ -273,6 +296,11 @@ export function settingsOf(f) {
 // The --set form a key is changed with, for the view and the envelope.
 function setForm(s, f) {
   if (s.class !== "changeable") return null;
+  if (s.group === "flow") {
+    const form = flowForm(s.key);
+    // A person's name may hold a space or a dot, and `[`…`]` globs in zsh.
+    return form && s.person !== null ? `--set ${shellQuote(form.slice("--set ".length))}` : form;
+  }
   const value =
     s.rail === "bool"
       ? "on|off"
@@ -301,6 +329,19 @@ export function resolveSets(f, sets, { harness = null, nearest = null } = {}) {
   const known = [...new Set(keys.map((s) => s.key))];
   const harnessesNamed = f.used.map((h) => h.display_name || h.id).join(", ") || "none";
   for (const raw of sets) {
+    // A flow key is parsed whole, before the split at the first `=`: a
+    // person's name may hold a dot (contract 2 as amended 2026-11-10).
+    if (isFlowSet(raw)) {
+      const vcfg = f.vaultCfg && !f.vaultCfg.corrupt ? f.vaultCfg.cfg : {};
+      const r = parseFlowSet(raw, { nearest, flow: vcfg.flow });
+      if (r.usage) return { usage: r.usage };
+      const { key, path, value } = r.change;
+      if (!f.vault) return { usage: `${key} lives in the vault's config, and this binding names no vault` };
+      if (seen.has(key)) return { usage: `${key} is named twice` };
+      seen.add(key);
+      out.push({ key, writer: "vault", path: ["flow", ...path], value });
+      continue;
+    }
     const at = String(raw).indexOf("=");
     if (at < 1) return { usage: `--set takes <key>=<value>, got ${raw}` };
     let key = String(raw).slice(0, at).trim();
@@ -464,20 +505,39 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
       );
     const strict = readVaultConfigStrict(f.vault);
     if (strict.corrupt) return refuse(`${strict.path} is not valid JSON — fix or remove it first`);
-    const patch = Object.fromEntries(policy.map((c) => [c.key, c.value]));
+    // A flow change carries a path into the `flow` object; a node on it that
+    // exists and is not an object is never replaced (contract 11).
+    for (const c of policy.filter((c) => c.path)) {
+      const at = blockedAt(strict.cfg, c.path.slice(1));
+      if (at) return refuse(`${c.key}: ${at} is not an object — fix or remove it first`);
+    }
+    const patch = {};
+    for (const c of policy) {
+      const path = c.path || [c.key];
+      let node = patch;
+      for (const step of path.slice(0, -1)) node = Object.hasOwn(node, step) ? node[step] : (node[step] = {});
+      node[path[path.length - 1]] = c.value;
+    }
     const next = nextVaultConfig(strict.cfg, patch, new Date().toISOString());
+    const flowBefore = (c) => flowAt(strict.cfg.flow, c.path.slice(1)) ?? null;
     const inEffect = (k) => strict.cfg[k] ?? (k === "spec_policy" ? "optional" : undefined);
     // `lifecycle_gates=on` on a vault already on but with no gates_since is a
     // change: it stamps the date the gates count from (the configure spec,
     // contract 7 as amended 2026-11-08).
     const stampsGates = (c) => c.key === "lifecycle_gates" && c.value === "on" && !strict.cfg.gates_since;
-    const changed = policy.filter((c) => inEffect(c.key) !== c.value || stampsGates(c));
+    const changed = policy.filter((c) =>
+      c.path
+        ? JSON.stringify(flowBefore(c)) !== JSON.stringify(c.value)
+        : inEffect(c.key) !== c.value || stampsGates(c),
+    );
     for (const c of changed)
       items.push({
         key: c.key,
         file: tildeOf(strict.path, f.home),
-        before: shown(strict.cfg[c.key] ?? (c.key === "spec_policy" ? "optional" : "not set")),
-        after: shown(c.value),
+        before: c.path
+          ? shown(flowBefore(c) ?? "not set")
+          : shown(strict.cfg[c.key] ?? (c.key === "spec_policy" ? "optional" : "not set")),
+        after: shown(c.value ?? "not set"),
         team: true,
         note:
           c.key === "spec_policy" && next.spec_policy_since !== strict.cfg.spec_policy_since
@@ -486,7 +546,13 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
               ? GATES_NOTE
               : null,
       });
-    if (changed.length) steps.push({ writer: "vault", patch, keys: changed.map((c) => c.key) });
+    if (changed.length)
+      steps.push({
+        writer: "vault",
+        patch,
+        keys: changed.map((c) => c.key),
+        flowPaths: policy.filter((c) => c.path).map((c) => c.path.slice(1)),
+      });
   }
 
   // The overlays: one agents change per harness, through the core
@@ -741,6 +807,12 @@ export function applyChanges(f, steps, { env = process.env, home = homedir(), ro
         // by every checkout, and a change made while the question waited is kept.
         const now = readVaultConfigStrict(f.vault);
         if (now.corrupt) throw new Error(`${now.path} stopped being valid JSON after the plan`);
+        // A flow path whose node stopped being an object since the PLAN is
+        // refused here too, never replaced (contract 11 as amended 2026-11-10).
+        for (const path of s.flowPaths || []) {
+          const at = blockedAt(now.cfg, path);
+          if (at) throw new Error(`${at} stopped being an object after the plan — fix or remove it first`);
+        }
         writeVaultConfig(f.vault, nextVaultConfig(now.cfg, s.patch, new Date().toISOString()));
         wrote.push(vaultConfigPath(f.vault));
       } else if (s.writer === "overlay") {
@@ -793,6 +865,7 @@ const GROUP_TITLES = (f) => ({
   surfaces: "Status line and band",
   vault: "Vault and templates",
   policy: "Policy",
+  flow: "Flow policy",
   ...Object.fromEntries(f.used.map((h) => [`agents:${h.id}`, `Agents · ${h.display_name || h.id}`])),
 });
 

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

@@ -103,6 +103,20 @@ export function grepProjectLines(cwd, pattern, { exclude = [], timeout = 10000,
   return { status: "ok", lines };
 }
 
+// The `--since` window git is given, shared with spec-drift.mjs.
+//
+// A bare YYYY-MM-DD gets midnight appended, and it is not cosmetic. Git's
+// approxidate reads a date with no time as THAT DATE AT THE CURRENT TIME OF
+// DAY, so `--since=2026-09-08` run at 17:46 silently excludes everything
+// committed earlier the same day. `started_at` is written as a bare date,
+// so a story started and finished in one day proposed `files: []` and the
+// caller had no way to tell that from "nothing was committed" (measured
+// 2026-09-08: --since=2026-09-08 returned nothing while
+// --since="2026-09-08 00:00" returned the day's commit).
+export function sinceWindow(since) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since} 00:00:00` : since;
+}
+
 function filterFiles(list) {
   return [...new Set(list)]
     .map((f) => f.trim())
@@ -128,16 +142,7 @@ function main() {
   } else if (since) {
     // committer-date window; work committed before the story went in-progress
     // is invisible by design (story-scoped attribution).
-    //
-    // A bare YYYY-MM-DD gets midnight appended, and it is not cosmetic. Git's
-    // approxidate reads a date with no time as THAT DATE AT THE CURRENT TIME OF
-    // DAY, so `--since=2026-09-08` run at 17:46 silently excludes everything
-    // committed earlier the same day. `started_at` is written as a bare date,
-    // so a story started and finished in one day proposed `files: []` and the
-    // caller had no way to tell that from "nothing was committed" (measured
-    // 2026-09-08: --since=2026-09-08 returned nothing while
-    // --since="2026-09-08 00:00" returned the day's commit).
-    const window = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since} 00:00:00` : since;
+    const window = sinceWindow(since);
     const out = git(["log", `--since=${window}`, "--name-only", "--pretty=format:"]);
     committed = out ? out.split("\n") : [];
     usedRange = `--since=${window}`;

package/node_modules/projectstore/scripts/doctor.mjs

@@ -2301,7 +2301,7 @@ function storyStemOf(storyRel) {
 // exact filename stem, legacy story-NNN prefix fallback — the strongest tier
 // wins across the epic's stories, and a tie within it is a reported
 // ambiguity, never a silent first match.
-function resolveSpecStory(entry, artifacts, epicFolderPath) {
+export function resolveSpecStory(entry, artifacts, epicFolderPath) {
   const m = String(entry).match(/^([^/]+)\/(.+)$/);
   if (!m) return { error: `not in <epic-id>/<story-id> form: "${entry}"` };
   const [, epicId, storyId] = m;
@@ -2895,7 +2895,7 @@ export function parseSpecContracts(spec) {
 // 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) {
+export 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 || "")]) {

package/node_modules/projectstore/scripts/flow-policy.mjs

@@ -0,0 +1,264 @@
+// projectstore — flow-policy.mjs: the vault's flow policy, as data.
+//
+// The `flow` block of <vault>/.projectstore.json holds a team's flow
+// thresholds: WIP limits by a person's time on the project, ages in status,
+// windows for throughput and capacity. This module is its grammar: the keys
+// and their value forms, the `--set` parse `configure` uses, the view's rows,
+// and the WIP limit rule doctor, `next` and the band read. Pure: no I/O.
+//
+// Spec: "Changing a project's settings after setup…" (alias `configure`),
+// contracts 2, 3, 7 and 11 as amended 2026-11-10, and SPEC-001 contract 4
+// as amended the same day, by PS-FLOW/story-the-vault-declares-its-flow-
+// policy-and-configure-writes-it. No key has a default in code: a check whose
+// key is absent does not run, and a value of the wrong type counts as absent.
+
+import { isCalendarDate } from "./lib.mjs";
+
+export const CLEAR = "-";
+
+// The fixed keys, in the view's order. `kind` picks the value form.
+export const FLOW_FIXED = Object.freeze([
+  { key: "flow.wip.full", path: ["wip", "full"], kind: "count" },
+  { key: "flow.wip.part", path: ["wip", "part"], kind: "count" },
+  { key: "flow.age_days.review", path: ["age_days", "review"], kind: "days" },
+  { key: "flow.age_days.in_progress_idle", path: ["age_days", "in_progress_idle"], kind: "days" },
+  { key: "flow.age_days.todo", path: ["age_days", "todo"], kind: "days" },
+  { key: "flow.idle_days", path: ["idle_days"], kind: "days" },
+  { key: "flow.window_weeks", path: ["window_weeks"], kind: "weeks" },
+  { key: "flow.capacity_weeks", path: ["capacity_weeks"], kind: "range" },
+  { key: "flow.active_epics_max", path: ["active_epics_max"], kind: "count" },
+  { key: "flow.grooming_days", path: ["grooming_days"], kind: "days" },
+]);
+
+// A person's fields, in the view's order.
+export const PERSON_FIELDS = Object.freeze(["time", "wip", "git_names", "left"]);
+const PERSON_KIND = Object.freeze({ time: "time", wip: "count", git_names: "names", left: "date" });
+
+// Stamps under `flow`: never set by hand (contract 2's "Not settings").
+export const FLOW_STAMPS = Object.freeze(["flow.groomed_at"]);
+
+const SET_OF = Object.freeze({
+  count: "a positive whole number",
+  days: "a whole number of days, 1 or more",
+  weeks: "a whole number of weeks, 1 or more",
+  range: "two positive numbers, low then high, like 2,3",
+  time: "full or part",
+  names: "a comma list of git author names",
+  date: "a date as YYYY-MM-DD",
+});
+
+const FORM_OF = Object.freeze({
+  count: "<n>",
+  days: "<days>",
+  weeks: "<weeks>",
+  range: "<low,high>",
+  time: "<full|part>",
+  names: "<a,b>",
+  date: "<YYYY-MM-DD>",
+});
+
+const CONTROL = /[\u0000-\u001f\u007f\u0085\u2028\u2029]/;
+const PERSON_KEY = /^flow\.people\[([\s\S]*?)\]\.([A-Za-z_]+)=([\s\S]*)$/;
+const BARE_PERSON = /^flow\.people\[([\s\S]*?)\]\s*(=|$)/;
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+// A positive safe integer written in plain decimal: no sign, no leading zero,
+// no exponent, no fraction.
+function positiveInt(raw) {
+  if (!/^[1-9]\d*$/.test(raw)) return null;
+  const n = Number(raw);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+function positiveNumber(raw) {
+  if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(raw)) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+// A value as typed → the value stored, or null when it is outside the set.
+function parseValue(kind, raw) {
+  switch (kind) {
+    case "count":
+    case "days":
+    case "weeks":
+      return positiveInt(raw);
+    case "range": {
+      const parts = raw.split(",").map((p) => p.trim());
+      if (parts.length !== 2) return null;
+      const [lo, hi] = parts.map(positiveNumber);
+      return lo !== null && hi !== null && lo <= hi ? [lo, hi] : null;
+    }
+    case "time":
+      return raw === "full" || raw === "part" ? raw : null;
+    case "names": {
+      const names = raw
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
+      return names.length && !names.some((n) => CONTROL.test(n)) ? names : null;
+    }
+    case "date":
+      return isCalendarDate(raw) ? raw : null;
+    default:
+      return null;
+  }
+}
+
+const shownName = (name) => (CONTROL.test(name) ? JSON.stringify(name) : name);
+
+// A person's name as `flow.people[<name>]` takes it: the assignee as stories
+// write it, never an email address.
+function badName(name) {
+  return !name || /[@\]=]/.test(name) || CONTROL.test(name) || name === "__proto__";
+}
+
+// Whether a raw `--set` argument is a flow key: these are parsed here, before
+// configure splits at the first `=` (a person's name may hold a dot).
+export const isFlowSet = (raw) => /^\s*flow(?:[.[=]|$)/.test(String(raw));
+
+// The every-key list a typo is measured against.
+export function flowKnownKeys(flow) {
+  const keys = FLOW_FIXED.map((k) => k.key);
+  if (isPlainObject(flow) && isPlainObject(flow.people))
+    for (const name of Object.keys(flow.people)) for (const f of PERSON_FIELDS) keys.push(personKey(name, f));
+  return keys;
+}
+
+export const personKey = (name, field) => `flow.people[${name}].${field}`;
+
+// One `--set` argument → `{ change: { key, path, value } }`, `value: null`
+// meaning "remove that key", or `{ usage }` (exit 2).
+export function parseFlowSet(raw, { nearest = null, flow = null } = {}) {
+  const text = String(raw).trim();
+  const unknown = (key) => {
+    if (FLOW_STAMPS.includes(key))
+      return { usage: `unknown setting ${key} — a stamp that groom writes, never set by hand` };
+    const hint = nearest ? nearest(key, flowKnownKeys(flow)) : null;
+    return { usage: `unknown setting ${key}${hint ? ` — did you mean ${hint}?` : ""}` };
+  };
+  const p = PERSON_KEY.exec(text);
+  if (p) {
+    const name = p[1].trim();
+    const field = p[2];
+    const value = p[3].trim();
+    if (badName(name))
+      return {
+        usage: `flow.people[${shownName(name)}] takes a name with no @, ] or =, and no line break (the assignee as stories write it, never an email address), got ${JSON.stringify(name)}`,
+      };
+    const key = personKey(name, field);
+    if (!PERSON_FIELDS.includes(field)) return unknown(key);
+    return change(key, ["people", name, field], PERSON_KIND[field], value);
+  }
+  const bare = BARE_PERSON.exec(text);
+  if (bare) {
+    const name = bare[1].trim();
+    return {
+      usage: `flow.people[${shownName(name)}] takes ${PERSON_FIELDS.map((f) => `.${f}`)
+        .join(", ")
+        .replace(/, ([^,]*)$/, " or $1")}`,
+    };
+  }
+  const at = text.indexOf("=");
+  if (at < 1) return { usage: `--set takes <key>=<value>, got ${raw}` };
+  const key = text.slice(0, at).trim();
+  const value = text.slice(at + 1).trim();
+  const fixed = FLOW_FIXED.find((k) => k.key === key);
+  if (!fixed) return unknown(key);
+  return change(key, fixed.path, fixed.kind, value);
+}
+
+function change(key, path, kind, value) {
+  if (value === CLEAR) return { change: { key, path, value: null } };
+  const parsed = value ? parseValue(kind, value) : null;
+  if (parsed === null)
+    return { usage: `${key} takes ${SET_OF[kind]}, or ${CLEAR} to clear it, got ${value || "nothing"}` };
+  return { change: { key, path, value: parsed } };
+}
+
+// The `--set` form a flow key is changed with; a person's form is quoted by
+// the caller for the shell.
+export function flowForm(key) {
+  const fixed = FLOW_FIXED.find((k) => k.key === key);
+  if (fixed) return `--set ${key}=${FORM_OF[fixed.kind]}`;
+  const m = /^flow\.people\[([\s\S]*)\]\.([a-z_]+)$/.exec(key);
+  return m ? `--set ${key}=${FORM_OF[PERSON_KIND[m[2]]]}` : null;
+}
+
+// The value at a path of the flow block, own keys only; undefined when absent.
+export function flowAt(flow, path) {
+  let node = flow;
+  for (const step of path) {
+    if (!isPlainObject(node) || !Object.hasOwn(node, step)) return undefined;
+    node = node[step];
+  }
+  return node;
+}
+
+// The first node on a path that exists and is not an object, as a dotted
+// key; null when the path can be written.
+export function blockedAt(vaultCfg, path) {
+  if (!isPlainObject(vaultCfg) || !Object.hasOwn(vaultCfg, "flow")) return null;
+  let node = vaultCfg.flow;
+  let label = "flow";
+  for (let i = 0; i < path.length; i++) {
+    if (!isPlainObject(node)) return label;
+    if (i === path.length - 1 || !Object.hasOwn(node, path[i])) return null;
+    label += path[0] === "people" && i === 1 ? `[${path[i]}]` : `.${path[i]}`;
+    node = node[path[i]];
+  }
+  return null;
+}
+
+// The rows the view lists: every set key, fixed keys in table order, then
+// people in file order, each person's fields in table order. A value of the
+// wrong type is listed as it is: the view shows the file.
+export function flowRows(flow) {
+  if (!isPlainObject(flow)) return [];
+  const rows = [];
+  for (const k of FLOW_FIXED) {
+    const v = flowAt(flow, k.path);
+    if (v !== undefined) rows.push({ key: k.key, value: v, person: null });
+  }
+  if (isPlainObject(flow.people))
+    for (const [name, fields] of Object.entries(flow.people)) {
+      if (!isPlainObject(fields)) continue;
+      for (const f of PERSON_FIELDS)
+        if (Object.hasOwn(fields, f)) rows.push({ key: personKey(name, f), value: fields[f], person: name });
+    }
+  return rows;
+}
+
+const goodCount = (v) => Number.isSafeInteger(v) && v > 0;
+
+// A fixed key's value when it is of its key's type, else null: how every
+// reader of the policy takes it (SPEC-001 contract 4, as amended).
+export function flowValue(vaultCfg, key) {
+  const fixed = FLOW_FIXED.find((k) => k.key === key || k.key === `flow.${key}`);
+  if (!fixed || !isPlainObject(vaultCfg)) return null;
+  const v = flowAt(vaultCfg.flow, fixed.path);
+  if (fixed.kind === "range")
+    return Array.isArray(v) &&
+      v.length === 2 &&
+      v.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0) &&
+      v[0] <= v[1]
+      ? [v[0], v[1]]
+      : null;
+  return goodCount(v) ? v : null;
+}
+
+// The WIP limit rule (SPEC-001 contract 4, as amended): a person's own `wip`,
+// else `flow.wip.<time>` for their `time`, else no limit. A person not listed
+// has none. The name matches exactly, as an own key.
+export function wipLimitOf(vaultCfg, name) {
+  if (!isPlainObject(vaultCfg)) return null;
+  const people = flowAt(vaultCfg.flow, ["people"]);
+  if (!isPlainObject(people) || typeof name !== "string" || !Object.hasOwn(people, name)) return null;
+  const person = people[name];
+  if (!isPlainObject(person)) return null;
+  if (goodCount(person.wip)) return person.wip;
+  if (person.time !== "full" && person.time !== "part") return null;
+  const byTime = flowAt(vaultCfg.flow, ["wip", person.time]);
+  return goodCount(byTime) ? byTime : null;
+}

package/node_modules/projectstore/scripts/lib.mjs

@@ -2047,7 +2047,9 @@ export function listOf(fm, key) {
 // lifecycle_gates ("on"|"off"), spec_policy_since (ISO-8601, stamped whenever
 // spec_policy becomes "required" from anything else; kept otherwise — the
 // configure spec, contract 7), gates_since (stamped when lifecycle_gates
-// turns on; the configure spec, contract 7 as amended 2026-11-08).
+// turns on; the configure spec, contract 7 as amended 2026-11-08), and flow,
+// the team's flow thresholds (scripts/flow-policy.mjs; the configure spec,
+// contract 2, and SPEC-001 contract 4, as amended 2026-11-10).
 export function vaultConfigPath(vault) {
   return join(vault, LAYOUT.vaultConfig);
 }
@@ -2079,8 +2081,29 @@ export function readVaultConfigStrict(vault) {
 // spec_policy_since: a story done before the policy (re)took effect is exempt
 // (ADR-007 decision 6), and since every story the old stamp exempted closed
 // before the new one, no exemption is lost.
+// A change merged into a config object (the configure spec, contract 7 as
+// amended 2026-11-10): plain objects merge key by key, an array or a scalar
+// replaces, `null` deletes the key, and an object the deletion leaves empty
+// is deleted too. Pure and copy-on-write: `before` is never mutated. Keys are
+// own keys only, and maps are built with Object.fromEntries, so a key named
+// `__proto__` stays a key.
+export function mergeConfig(before, patch) {
+  const plain = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+  const base = plain(before) ? before : {};
+  const entries = new Map(Object.entries(base));
+  for (const [k, v] of Object.entries(patch || {})) {
+    if (v === null) entries.delete(k);
+    else if (plain(v)) {
+      const merged = mergeConfig(Object.hasOwn(base, k) && plain(base[k]) ? base[k] : {}, v);
+      if (Object.keys(merged).length) entries.set(k, merged);
+      else entries.delete(k);
+    } else entries.set(k, v);
+  }
+  return Object.fromEntries(entries);
+}
+
 export function nextVaultConfig(before, patch, now = new Date().toISOString()) {
-  const next = { ...before, ...patch };
+  const next = mergeConfig(before, patch);
   if (patch.spec_policy === "required" && before.spec_policy !== "required") {
     // Never earlier than the stamp it replaces: one written ahead of this
     // clock (a hand edit, a machine whose clock ran fast) would otherwise

package/node_modules/projectstore/scripts/spec-drift.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+// projectstore — spec-drift.mjs (PS-SPEC: "The reviewer can run against an
+// active spec and its code_refs and report where the code drifted from the
+// contracts"; SPEC-001 contract 10, the Spec drift bullet).
+//
+//   node spec-drift.mjs <spec id|alias|stem> [--since <date>] [--project <dir>]
+//
+// The fact bundle the reviewer's spec-drift mode reads. Pure and read-only:
+// it prints stable JSON (no generated_at, sorted lists) and writes nothing.
+// It judges nothing either: the verdicts are the reviewer's.
+//
+// - contracts: number, heading, removed state, scenarios, marks, the valid
+//   and invalid markers with the status of each marker's story, the anchor
+//   (the date of the contract's last valid marker, else the spec's `date:`;
+//   `--since` overrides every anchor), and the tests citing it;
+// - stories: the spec's `stories:`, each with its status and `code_refs`,
+//   empty and missing refs listed;
+// - files: the refs expanded (directories, a trailing `/`, globs `*` `**` `?`),
+//   SOURCE_IGNORE dropped, classed tests / surface / source, with line counts
+//   and the commits since each anchor of a contract that is not removed (a
+//   count and the last three);
+// - scan: `ok`, `no-git` or `unknown`. A null is "unknown", never "none":
+//   with no git, history and citations are null, not empty.
+//
+// Git runs in the PROJECT through diff-refs.mjs's seams (gitIn,
+// grepProjectLines), which tests replace; this module spawns nothing itself.
+
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from "node:fs";
+import { join, relative, basename, resolve } from "node:path";
+import {
+  readConfigAt,
+  loadLayout,
+  folderByKind,
+  listOf,
+  sectionOf,
+  linesOutsideFences,
+  parseAmendmentMarkers,
+  isTestPath,
+  SOURCE_IGNORE,
+  CITATION_EXAMPLE_KEY,
+  isMain,
+  commandForm,
+  projectRoot,
+} from "./lib.mjs";
+import { gitIn, grepProjectLines, sinceWindow } from "./diff-refs.mjs";
+import { scanArtifacts, parseSpecContracts, resolveSpecStory, citationKeys, scanCitations } from "./doctor.mjs";
+
+function die(msg) {
+  process.stderr.write(`projectstore/spec-drift: ${msg}\n`);
+  process.exit(1);
+}
+
+// ─── Which spec ────────────────────────────────────────────────────────
+
+const stemOf = (s) => basename(s.rel).replace(/\.md$/, "");
+const realValue = (v) => (v && v !== "null" ? String(v) : null);
+
+function describe(s) {
+  return {
+    id: realValue(s.fm.id),
+    alias: realValue(s.fm.alias),
+    rel: s.rel,
+    status: String(s.fm.status || "draft"),
+  };
+}
+
+// By exact id or alias (the citation keys), or exact filename stem; then the
+// same, case-insensitive. Two specs that answer to one query are ambiguous
+// whichever way each answers: the caller names it better, nothing is picked.
+export function resolveSpec(artifacts, query) {
+  const q = String(query || "");
+  const specs = artifacts.filter((a) => a.kind === "spec");
+  const keys = citationKeys(artifacts);
+  const exact = new Set();
+  if (keys.has(q)) exact.add(keys.get(q));
+  for (const s of specs) if (stemOf(s) === q) exact.add(s);
+  let hits = [...exact];
+  if (!hits.length) {
+    const lc = q.toLowerCase();
+    hits = specs.filter((s) =>
+      [realValue(s.fm.id), realValue(s.fm.alias), stemOf(s)].some((v) => v && v.toLowerCase() === lc),
+    );
+  }
+  const byRel = (a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0);
+  if (hits.length === 1) return { spec: hits[0] };
+  if (hits.length > 1) return { error: "ambiguous", candidates: hits.sort(byRel).map(describe) };
+  const lc = q.toLowerCase();
+  const near = specs.filter((s) =>
+    [realValue(s.fm.id), realValue(s.fm.alias), stemOf(s), realValue(s.fm.title)].some(
+      (v) => lc && v && v.toLowerCase().includes(lc),
+    ),
+  );
+  return { error: "unknown", candidates: (near.length ? near : specs).sort(byRel).map(describe) };
+}
+
+// ─── Files ─────────────────────────────────────────────────────────────
+
+// `**/` is any number of directories, `**` anything, `*` and `?` stay inside
+// one path segment. Everything else is literal.
+export function globRe(glob) {
+  let s = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*" && glob[i + 1] === "*") {
+      i++;
+      if (glob[i + 1] === "/") {
+        i++;
+        s += "(?:.*/)?";
+      } else s += ".*";
+    } else if (c === "*") s += "[^/]*";
+    else if (c === "?") s += "[^/]";
+    else s += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${s}$`);
+}
+
+const ignored = (rel) => SOURCE_IGNORE.some((rx) => rx.test(rel));
+
+// Every file under `dir` (project-relative), sorted; `.git`, symbolic links,
+// SOURCE_IGNORE paths and the vault (when it sits inside the project) skipped.
+function walk(proj, dir, skipRel) {
+  const out = [];
+  const visit = (rel) => {
+    let entries;
+    try {
+      entries = readdirSync(join(proj, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (e.name === ".git" || ignored(`${r}/`) || (skipRel && (r === skipRel || r.startsWith(`${skipRel}/`))))
+          continue;
+        visit(r);
+      } else if (e.isFile() && !ignored(r)) out.push(r);
+    }
+  };
+  visit(dir);
+  return out.sort();
+}
+
+// A ref expanded to files, or null when it names nothing (a missing path, a
+// glob that matches no file).
+function expandRef(proj, ref, allFiles, skipRel) {
+  const r = String(ref).replace(/^\.\//, "");
+  if (/[*?]/.test(r)) {
+    const dirGlob = r.endsWith("/");
+    const re = globRe(dirGlob ? r.slice(0, -1) : r);
+    const hits = allFiles().filter((f) => {
+      if (re.test(f)) return !dirGlob;
+      const parts = f.split("/");
+      for (let i = 1; i < parts.length; i++) if (re.test(parts.slice(0, i).join("/"))) return true;
+      return false;
+    });
+    return hits.length ? hits : null;
+  }
+  const bare = r.replace(/\/+$/, "");
+  let st;
+  try {
+    st = statSync(join(proj, bare));
+  } catch {
+    return null;
+  }
+  if (st.isDirectory()) return walk(proj, bare, skipRel);
+  if (r.endsWith("/")) return null;
+  return ignored(bare) ? [] : [bare];
+}
+
+// The classes only split the input size (contract 10): tests by the test-path
+// rule; surface for docs, the README, manifests and generated copies; source
+// otherwise.
+const SURFACE = [
+  /(^|\/)docs?\//,
+  /(^|\/)(README|CHANGELOG|CHANGES|LICENSE)(\.[^/]*)?$/i,
+  /(^|\/)(package|plugin|marketplace|packlist)\.json$/,
+  /(^|\/)\.mcp\.json$/,
+  /(^|\/)\.[^/]+-plugin\//,
+  /^adapters\//,
+  /^packaging\/shells\//,
+];
+export function classOf(rel) {
+  if (isTestPath(rel)) return "tests";
+  if (SURFACE.some((rx) => rx.test(rel))) return "surface";
+  return "source";
+}
+
+// Lines in a text file; null for a binary or unreadable one.
+function lineCount(abs) {
+  let buf;
+  try {
+    buf = readFileSync(abs);
+  } catch {
+    return null;
+  }
+  if (buf.subarray(0, 8000).includes(0)) return null;
+  const text = buf.toString("utf8");
+  if (!text) return 0;
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+
+// ─── History ───────────────────────────────────────────────────────────
+
+const SEP_RECORD = "\x1e";
+const SEP_FIELD = "\x1f";
+
+// anchor → (file → commits, newest first), or anchor → null when git could
+// not answer. One `git log` per anchor and per chunk of paths.
+function historyByAnchor(proj, files, anchors, git) {
+  const out = new Map();
+  for (const anchor of anchors) {
+    const per = new Map();
+    let failed = false;
+    for (let i = 0; i < files.length && !failed; i += 400) {
+      const chunk = files.slice(i, i + 400);
+      const log = git(proj, [
+        "-c",
+        "core.quotePath=false",
+        "log",
+        `--since=${sinceWindow(anchor)}`,
+        "--relative",
+        "--name-only",
+        "--format=%x1e%H%x1f%cI%x1f%s",
+        "--",
+        ...chunk,
+      ]);
+      if (log === null || log === undefined) {
+        failed = true;
+        break;
+      }
+      for (const rec of String(log).split(SEP_RECORD)) {
+        if (!rec.trim()) continue;
+        const [head, ...names] = rec.split("\n");
+        const [sha = "", date = "", subject = ""] = head.split(SEP_FIELD);
+        const commit = { commit: sha.slice(0, 12), date, subject };
+        for (const n of names) {
+          const f = n.trim();
+          if (!f) continue;
+          if (!per.has(f)) per.set(f, []);
+          if (!per.get(f).some((c) => c.commit === commit.commit)) per.get(f).push(commit);
+        }
+      }
+    }
+    out.set(anchor, failed ? null : per);
+  }
+  return out;
+}
+
+// ─── The bundle ────────────────────────────────────────────────────────
+
+// Each contract's heading, in the order parseSpecContracts reads them (the
+// same section, comments stripped, fences skipped, the same top-level form).
+function contractHeadings(spec) {
+  const sec = sectionOf(spec.body || "", "spec_contracts");
+  if (sec === null) return [];
+  const out = [];
+  for (const line of linesOutsideFences(sec.replace(/<!--[\s\S]*?-->/g, ""))) {
+    const m = line.match(/^(\d+[′″']*)\.(?:\s|$)(.*)$/);
+    if (!m) continue;
+    // A bold heading that wraps is cut at its first sentence on this line.
+    const bold = m[2].match(/^\*\*(.+?)\*\*/);
+    const text = bold ? bold[1] : m[2].replace(/^\*\*/, "").split(/(?<=\.)\s/)[0];
+    out.push(text.trim().replace(/\.$/, "").slice(0, 120));
+  }
+  return out;
+}
+
+const byPath = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function vaultInside(proj, vault) {
+  try {
+    const rel = relative(realpathSync.native(proj), realpathSync.native(vault));
+    return rel && !rel.startsWith("..") && !rel.startsWith("/") ? rel : null;
+  } catch {
+    return null;
+  }
+}
+
+// { bundle } or { error: "unknown" | "ambiguous" | "not-active", … }.
+export function buildSpecDrift({
+  proj,
+  cfg,
+  query,
+  since = null,
+  git = gitIn,
+  grep = grepProjectLines,
+  layout = null,
+}) {
+  const lay = layout || loadLayout(cfg.layout);
+  const artifacts = scanArtifacts(cfg, lay);
+  const found = resolveSpec(artifacts, query);
+  if (found.error) return { error: found.error, query: String(query || ""), candidates: found.candidates };
+  const spec = found.spec;
+  const status = String(spec.fm.status || "draft");
+  if (status !== "active") return { error: "not-active", status, spec: describe(spec) };
+
+  const epicFolder = folderByKind(lay, "epic");
+  const storyOf = (ref) =>
+    epicFolder ? resolveSpecStory(ref, artifacts, epicFolder.path) : { error: "the layout has no epic folder" };
+
+  // Contracts and their markers.
+  const parsed = parseSpecContracts(spec) || [];
+  const headings = contractHeadings(spec);
+  const allMarkers = parseAmendmentMarkers(spec.body || "");
+  const specDate = /^\d{4}-\d{2}-\d{2}/.test(String(spec.fm.date || "")) ? String(spec.fm.date).slice(0, 10) : null;
+  const contracts = parsed.map((c, i) => {
+    const markers = allMarkers
+      .filter((m) => m.index === i)
+      .map((m) => {
+        const row = { line: m.line, date: m.date, kind: m.kind, ref: m.ref, why: m.why, valid: m.valid };
+        if (!m.valid) row.form = m.form;
+        const r = m.ref ? storyOf(m.ref) : { error: "no ref" };
+        row.story = r.story ? { rel: r.story.rel, status: String(r.story.fm.status || "planned") } : null;
+        if (r.error) row.story_error = r.error;
+        return row;
+      });
+    const lastValid = markers.filter((m) => m.valid).at(-1) || null;
+    const [anchor, anchor_from] = since
+      ? [since, "since"]
+      : lastValid
+        ? [lastValid.date, "marker"]
+        : [specDate, specDate ? "date" : null];
+    return {
+      n: c.n,
+      heading: headings[i] ?? null,
+      removed: c.removed,
+      why: c.why,
+      steps: [...c.steps],
+      removed_steps: [...c.removedSteps],
+      verified: c.marker,
+      scenarios: c.scenarios,
+      marks: c.marks,
+      anchor,
+      anchor_from,
+      markers,
+      cited_by: [],
+      files_changed: null,
+    };
+  });
+
+  // Covered stories and their refs.
+  const stories = [];
+  const refs = { empty: [], missing: [], unresolved: [] };
+  const vaultRel = vaultInside(proj, cfg.vault_path);
+  let all = null;
+  const allFiles = () => (all ??= walk(proj, "", vaultRel));
+  const fileRefs = new Map();
+  for (const entry of listOf(spec.fm, "stories")) {
+    const r = storyOf(entry);
+    if (r.error) {
+      stories.push({ ref: entry, error: r.error });
+      refs.unresolved.push({ story: entry, error: r.error });
+      continue;
+    }
+    const codeRefs = listOf(r.story.fm, "code_refs");
+    const missing = [];
+    for (const ref of codeRefs) {
+      const files = expandRef(proj, ref, allFiles, vaultRel);
+      if (files === null) {
+        missing.push(ref);
+        refs.missing.push({ story: entry, ref });
+        continue;
+      }
+      for (const f of files) {
+        if (!fileRefs.has(f)) fileRefs.set(f, new Set());
+        fileRefs.get(f).add(ref);
+      }
+    }
+    if (!codeRefs.length) refs.empty.push(entry);
+    stories.push({
+      ref: entry,
+      rel: r.story.rel,
+      title: String(r.story.fm.title || stemOf(r.story)),
+      status: String(r.story.fm.status || "planned"),
+      code_refs: codeRefs,
+      missing,
+    });
+  }
+
+  // Citations: the doctor's scan, keyed by id and alias; `example` is docs.
+  const scan = scanCitations(cfg, artifacts, proj, grep) || { status: "ok", reason: null, tokens: [] };
+  const keys = citationKeys(artifacts);
+  if (scan.status === "ok") {
+    for (const t of scan.tokens) {
+      if (t.typographic || t.key === CITATION_EXAMPLE_KEY || keys.get(t.key) !== spec) continue;
+      const top = t.n.split("/")[0];
+      const c = contracts.find((x) => x.n === top);
+      if (c) c.cited_by.push({ file: t.file, line: t.line, n: t.n });
+    }
+    for (const c of contracts) c.cited_by.sort((a, b) => byPath(a.file, b.file) || a.line - b.line || byPath(a.n, b.n));
+  } else for (const c of contracts) c.cited_by = null;
+
+  // Files, with history since each anchor of an open contract.
+  const paths = [...fileRefs.keys()].sort(byPath);
+  const anchors = [...new Set(contracts.filter((c) => !c.removed && c.anchor).map((c) => c.anchor))].sort(byPath);
+  const history = scan.status === "no-git" ? null : historyByAnchor(proj, paths, anchors, git);
+  let scanStatus = scan.status;
+  let reason = scan.reason || null;
+  if (scanStatus === "ok" && history && [...history.values()].some((h) => h === null)) {
+    scanStatus = "unknown";
+    reason = "git log did not answer";
+  }
+  const files = paths.map((p) => {
+    let changed_since = null;
+    // No anchor at all (no `date:`, no valid marker, no --since, or every
+    // contract removed): nothing to count from, so history is unknown, not none.
+    if (history && anchors.length) {
+      changed_since = {};
+      for (const a of anchors) {
+        const h = history.get(a);
+        const commits = h ? h.get(p) || [] : null;
+        changed_since[a] = commits ? { count: commits.length, last: commits.slice(0, 3) } : null;
+      }
+    }
+    return {
+      path: p,
+      class: classOf(p),
+      lines: lineCount(join(proj, p)),
+      refs: [...fileRefs.get(p)].sort(byPath),
+      changed_since,
+    };
+  });
+  for (const c of contracts) {
+    if (c.removed || !c.anchor || !history || history.get(c.anchor) === null) continue;
+    c.files_changed = files.filter((f) => f.changed_since[c.anchor]?.count > 0).length;
+  }
+
+  const lines = { source: 0, tests: 0, surface: 0, total: 0 };
+  const byClass = { source: 0, tests: 0, surface: 0 };
+  for (const f of files) {
+    byClass[f.class]++;
+    if (f.lines !== null) {
+      lines[f.class] += f.lines;
+      lines.total += f.lines;
+    }
+  }
+  const removed = contracts.filter((c) => c.removed).length;
+  const changed =
+    history && anchors.length
+      ? files.filter((f) => Object.values(f.changed_since).some((x) => x?.count > 0)).length
+      : null;
+  return {
+    bundle: {
+      spec: { ...describe(spec), title: realValue(spec.fm.title), date: specDate },
+      checkout: basename(proj),
+      since,
+      scan: { status: scanStatus, reason },
+      totals: {
+        contracts: contracts.length,
+        contracts_removed: removed,
+        contracts_open: contracts.length - removed,
+        stories: stories.length,
+        files: files.length,
+        files_by_class: byClass,
+        lines,
+        files_changed: history && [...history.values()].some((h) => h === null) ? null : changed,
+        refs_empty: refs.empty.length,
+        refs_missing: refs.missing.length,
+        stories_unresolved: refs.unresolved.length,
+      },
+      contracts,
+      stories,
+      refs,
+      files,
+    },
+  };
+}
+
+// ─── CLI ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const opts = { query: null, since: null, project: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--since") {
+      opts.since = argv[++i];
+      if (!opts.since || Number.isNaN(Date.parse(opts.since)))
+        die("--since expects a date (YYYY-MM-DD or an ISO timestamp)");
+    } else if (a === "--project") {
+      opts.project = argv[++i];
+      if (!opts.project) die("--project expects a directory");
+    } else if (a.startsWith("--")) die(`unknown argument: ${a}`);
+    else if (opts.query === null) opts.query = a;
+    else die(`one spec per run (got "${opts.query}" and "${a}")`);
+  }
+  return opts;
+}
+
+const named = (c) => `${c.id || c.rel} (${c.rel}, ${c.status})`;
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const proj = resolve(opts.project || projectRoot());
+  const cfg = readConfigAt(proj);
+  if (!cfg || !cfg.vault_path) die(`No projectstore config. Run ${commandForm("bind")} first.`);
+  if (!existsSync(cfg.vault_path)) die(`The bound vault is not there: ${cfg.vault_path}`);
+  if (!opts.query) die("usage: spec-drift.mjs <spec id|alias|stem> [--since <date>]");
+  const r = buildSpecDrift({ proj, cfg, query: opts.query, since: opts.since });
+  if (r.error === "not-active")
+    die(`Spec ${named(r.spec)} is ${r.status}, not active: spec drift reads an active spec only.`);
+  if (r.error === "ambiguous")
+    die(`"${r.query}" names more than one spec; name one of: ${r.candidates.map(named).join("; ")}.`);
+  if (r.error === "unknown")
+    die(
+      `No spec answers to "${r.query}" by id, alias or filename. Candidates: ${r.candidates.map(named).join("; ") || "none"}.`,
+    );
+  // Compact on purpose: the reviewer reads it through a tool whose output may be capped.
+  process.stdout.write(JSON.stringify(r.bundle) + "\n");
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.15",
+  "version": "0.30.16",
   "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.15"
+    "projectstore": "=0.30.16"
   },
   "bundleDependencies": [
     "projectstore"