projectstore-claude 0.30.7 → 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.7",
+      "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.7",
+  "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

@@ -1,6 +1,6 @@
 # ProjectStore
 
-> Not agent memory, not a per-feature spec pipeline. Memory helps one agent recall; a feature spec plans one change. ProjectStore keeps the project's record — what was decided, what is in flight, what was checked — as reviewed markdown in git, readable by any agent and anyone with the repo.
+> ProjectStore is a method and a framework for building apps and services of any size with AI agents. It keeps the project's record — what was decided, what is in flight, what was checked — as reviewed markdown in git, readable by any agent and anyone with the repo.
 
 [![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
 
@@ -183,7 +183,7 @@ npx projectstore codemap --for scripts/lib.mjs
 The same eight reads are an MCP server. The plugin registers it through its own `.mcp.json`, so a Claude Code session has `status`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `orientation` and `doctor` as tools with no shell; every tool result is the CLI's `--json` for the same arguments. Elsewhere:
 
 ```
-npx projectstore mcp --project "$PWD"
+npx projectstore mcp --project .
 ```
 
 Binding, too — naming the vault is the confirmation, and changing it needs `--rebind`. `init` creates a whole vault in one step, with no `mkdir` first: the directory, its git repository, the layout's folders and their README indexes; `scaffold --write` adds the folders to a vault that was bound without them:
@@ -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,10 +398,10 @@ 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 under `.projectstore/state/sessions/` while it draws; it starts no program and makes no request.
+- **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.
 - **Your own status line.** When ProjectStore's status line is on and your project's `.claude/settings.json` or your user `settings.json` already names a status line command, ProjectStore runs that command through your shell on every render, passes it the status data Claude Code gives a status line on its standard input, and shows what it prints under its own line.
 
 The package also ships `scripts/version-guard.mjs`, which runs `npm pack --dry-run` as the release's own check. The plugin never runs it.
@@ -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/commands/review.md

@@ -37,8 +37,8 @@ You are running a peer review on a projectstore artifact.
 
    ## Project context
 
-   <vault README excerpt>
-   <folder README excerpt>
+   <the vault's README excerpt>
+   <the folder's README excerpt>
 
    ## Structural checklist
 

package/node_modules/projectstore/commands/statusline.md

@@ -5,7 +5,7 @@ argument-hint: "on | off | status"
 
 You are toggling the projectstore status line for THIS project. When enabled, `install-harness.mjs` points the project's `.claude/settings.local.json` at a launcher it writes at `.projectstore/state/claude-code/statusline.mjs`. That path carries no version, so it never goes stale: the launcher resolves the *currently installed* plugin on every render, and an update is reflected on the spot instead of one restart later. (A dev checkout or `--plugin-dir` root is wired straight to its `scripts/statusline.mjs` — those paths have no version to drift.) The line renders `[PS#<version>] 📚 <epic> › <story> (<status>)` **composed above** any existing HUD (e.g. oh-my-claudecode), never replacing it. While this session's band above the prompt is drawing (`/projectstore:bar`), the line gives way to it — your base HUD stays — and it comes back within 30 s of the band stopping.
 
-Resolution is **per-session with zero cross-session and zero vault reads** (ADR-006): the 📚 segment comes from this session's pointer (`.projectstore/state/sessions/<session_id>.json`, maintained by the tool hooks — a write's patch after the write — by `story close`, and at session start; a done, closed or parked story leaves the segment); a fresh session shows an explicit localized cold-start line ("No epic or story in this session yet" / «Эпик и стори ещё не в работе в этой сессии») — never a silent blank; a corrupt pointer shows an error-marked string. Strings localize via `templates/<lang>/strings.json` (en fallback). The version badge is controlled by `statusline.show_version` (default true).
+Resolution is **per-session, with no cross-session read and no read of the vault** (ADR-006): the 📚 segment comes from this session's pointer (`.projectstore/state/sessions/<session_id>.json`, maintained by the tool hooks — a write's patch after the write — by `story close`, and at session start; a done, closed or parked story leaves the segment); a fresh session shows an explicit localized cold-start line ("No epic or story in this session yet" / «Эпик и стори ещё не в работе в этой сессии») — never a silent blank; a corrupt pointer shows an error-marked string. Strings localize via `templates/<lang>/strings.json` (en fallback). The version badge is controlled by `statusline.show_version` (default true).
 
 This command runs `configure --set statusline=on|off` (the configure spec, contracts 6 and 9): install's own items record `statusline.enabled` and write or remove the `settings.local.json` entry and the launcher, in one plan. The command never writes `projectstore.json` itself. The SessionStart hook only refreshes an entry that is already ours and removes it when the flag is off — it never creates one.
 

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/docs/how-it-works.md

@@ -87,25 +87,28 @@ Edits made through the shell are not seen; a Read of the story sets the pointer.
 
 Continuity across a compaction is delivered by **SessionStart**, not by
 PreCompact — and that is a correction, not a design flourish. PreCompact has no
-model-facing channel: it accepts a top-level `systemMessage` and nothing else,
-so for its whole life the hook assembled a rich packet, printed a red *"Hook
-JSON output validation failed"*, and reached nobody. Worse, the invalid field
-sank the whole object, so the one line PreCompact *does* support never landed
-either.
+`additionalContext`, so for its early life the hook assembled a rich packet,
+printed a red *"Hook JSON output validation failed"*, and reached nobody. Its
+`systemMessage` is no channel either: Claude Code discards that field on
+PreCompact. What it does with a PreCompact hook is echo the hook's raw stdout in
+the `/compact` output.
 
 So the two hooks now split the work by what each can actually do.
 
-PreCompact prints one line, for you:
+PreCompact prints one plain line, for you:
 
 ```
-PreCompact [...pre-compact.mjs] completed successfully: {
-  "systemMessage": "projectstore: compacting — vault myapp-vault,
-                    in flight: `epics/WEB-101/epic.md`,
-                    orientation and this session's recent files return
-                    at session start"
-}
+⎿ Compacted (ctrl+o to see full summary)
+  PreCompact [...pre-compact.mjs] completed successfully: projectstore:
+  compacting — vault myapp-vault, in flight: `epics/WEB-101/epic.md`,
+  orientation and this session's recent files return at session start
 ```
 
+On a manual `/compact` the model reads that line too, after the summary. On an
+automatic compaction it is shown to no one. (On Codex, where none of this is
+measured yet, the hook keeps printing its line as a `{"systemMessage": …}`
+object.)
+
 That last clause is conditional on purpose. It appears only when the compaction
 is **manual** and `auto_inject` is on — the two things the hook can check at the
 moment it speaks. On an automatic compaction the plugin makes no claim that

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

@@ -115,7 +115,7 @@
     "_root_placeholder_literal_comment": "true = the harness passes the placeholder through as literal text and the installer must substitute an absolute path; false = the harness expands it. Claude Code expands ${CLAUDE_PLUGIN_ROOT}, so false. Measured value for Codex comes from the spike."
   },
   "output_channels": {
-    "_comment": "Per-event output channels (generation spec, contract 17). `fields` are the hookSpecificOutput keys the event honours; `system_message` is the top-level systemMessage; `decision` names the decision object where one exists; an optional `input_fields` lists the stdin keys; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null) — our choice where both are honoured. `evidence` is `measured` only where this repository's own hooks observe the fact, `documented` where the Claude Code hooks reference says so and we never emit it.",
+    "_comment": "Per-event output channels (generation spec, contract 17). `fields` are the hookSpecificOutput keys the event honours; `system_message` is the top-level systemMessage; `decision` names the decision object where one exists; an optional `input_fields` lists the stdin keys; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null) — our choice where both are honoured; PreCompact's `carrier` is how hooks/pre-compact.mjs prints its line (stdout | null, null keeping the {\"systemMessage\"} object). `system_message` is true where the field is honoured, false where it is measured discarded, null where unmeasured. `evidence` is `measured` only where this repository's own hooks observe the fact, `documented` where the Claude Code hooks reference says so and we never emit it.",
     "SessionStart": {
       "fields": [
         "additionalContext"
@@ -195,10 +195,11 @@
     },
     "PreCompact": {
       "fields": [],
-      "system_message": true,
+      "system_message": false,
       "decision": null,
+      "carrier": "stdout",
       "evidence": "measured",
-      "note": "Measured NEGATIVELY: an output object containing additionalContext is rejected whole, taking systemMessage down with it (hooks/pre-compact.mjs; vault story: PreCompact survival packet targets a channel PreCompact does not have). Only top-level decision/reason and systemMessage exist."
+      "note": "Measured NEGATIVELY: an output object containing additionalContext is rejected whole, taking systemMessage down with it (vault story: PreCompact survival packet targets a channel PreCompact does not have). A top-level `decision: \"block\"` exists (documented; never emitted here). The systemMessage field is discarded (hooks reference; measured on 2.1.312, 2026-10-28): what carries the line is the hook's raw stdout, echoed in the /compact output as `PreCompact [<command>] completed successfully: <stdout>` (the same form was seen on 2026-08-18). On a manual compaction the user sees it and the model reads it as <local-command-stdout> after the summary; on an automatic one nothing is shown, and the compacting model appears to receive it (nothing relies on that). stderr reaches no one. Vault story: On Claude Code PreCompact speaks plain text, because the host echoes its stdout and discards systemMessage."
     }
   },
   "surfaces": {
@@ -310,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,
@@ -325,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

@@ -72,7 +72,7 @@
     "_root_placeholder_literal_comment": "true: Codex substitutes nothing in a hook command string. It does not need to — the hook process receives PLUGIN_ROOT in its environment (measured). The generator therefore renders an absolute interpreter and an absolute script path; a bare `node` is a PATH gamble."
   },
   "output_channels": {
-    "_comment": "Per-event channels (generation spec, contract 17, as amended 2026-10-15). `fields` are the hookSpecificOutput keys the event honours — the output side, as on every manifest; `input_fields` are the stdin keys it delivers, captured from live firings (759 on 2026-09-07/08; Run 4 of *Codex hook contract measured in a live session*, codex-cli 0.162.1, 2026-10-15, traces t1–t7). `decision` names the decision object where one exists; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null). `system_message` stays null: documented, not measured. `evidence` is about the output side.",
+    "_comment": "Per-event channels (generation spec, contract 17, as amended 2026-10-15). `fields` are the hookSpecificOutput keys the event honours — the output side, as on every manifest; `input_fields` are the stdin keys it delivers, captured from live firings (759 on 2026-09-07/08; Run 4 of *Codex hook contract measured in a live session*, codex-cli 0.162.1, 2026-10-15, traces t1–t7). `decision` names the decision object where one exists; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null); PreCompact's `carrier` is how hooks/pre-compact.mjs prints its line (stdout | null). `system_message` stays null: documented, not measured. `evidence` is about the output side.",
     "SessionStart": {
       "input_fields": [
         "session_id",
@@ -185,8 +185,9 @@
       "fields": [],
       "system_message": null,
       "decision": null,
+      "carrier": null,
       "evidence": "documented",
-      "note": "trigger is `auto` on an automatic compaction, and PostCompact follows (Run 4, t2:5–6). No permission_mode. Whether a systemMessage reaches anyone on Codex is unmeasured."
+      "note": "trigger is `auto` on an automatic compaction, and PostCompact follows (Run 4, t2:5–6). No permission_mode. Whether a systemMessage reaches anyone on Codex is unmeasured, so no carrier is set and hooks/pre-compact.mjs keeps its {\"systemMessage\"} object here."
     }
   },
   "surfaces": {
@@ -239,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/hooks/band.tsx

@@ -197,14 +197,14 @@ async function storiesOf($: EngineInterface, b: Band, epicDir: string): Promise<
     list: async (dir: string) => {
       const entries = await $.fs.list(dir)
       const out = []
-      for (const e of entries) {
-        let kind = e.kind
+      for (const entry of entries) {
+        let kind = entry.kind
         if (kind === 'other') {
           // A symbolic link: the board follows it, so the band does too.
-          try { kind = (await $.fs.stat(`${dir}/${e.name}`, { resolve: true })).kind } catch { kind = 'other' }
+          try { kind = (await $.fs.stat(`${dir}/${entry.name}`, { resolve: true })).kind } catch { kind = 'other' }
         }
-        seen.push(`${dir}/${e.name}:${kind}:${e.mtimeMs}`)
-        out.push({ ...e, kind })
+        seen.push(`${dir}/${entry.name}:${kind}:${entry.mtimeMs}`)
+        out.push({ ...entry, kind })
       }
       return out
     },
@@ -240,9 +240,9 @@ async function storiesOf($: EngineInterface, b: Band, epicDir: string): Promise<
       })
     }
   }
-  const next = { sig, counts: foldStages(statuses) as BandCounts, items }
-  b.stories.set(epicDir, next)
-  return next
+  const fresh = { sig, counts: foldStages(statuses) as BandCounts, items }
+  b.stories.set(epicDir, fresh)
+  return fresh
 }
 
 // This session's story, from its file (contract 8): the item the pointer's
@@ -313,10 +313,12 @@ async function scan($: EngineInterface, b: Band, root: string, sid: string | nul
 // ── The clock: scan, heartbeat, prune (contract 10) ───────────────────
 
 async function writeHeartbeat($: EngineInterface, root: string, sid: string | null, body: unknown): Promise<boolean> {
-  const name = heartbeatFile(sid)
-  if (!name) return false
+  // An id that cannot name a file writes nothing. The path is spelled out,
+  // folder and name, so the directory's scan can read where the band writes;
+  // a node test holds it to layoutPaths() and heartbeatFile().
+  if (!heartbeatFile(sid)) return false
   try {
-    await $.fs.write(`${root}/${SESSIONS}/${name}`, JSON.stringify(body) + '\n')
+    await $.fs.write(`${root}/.projectstore/state/sessions/.band-${sid}.json`, JSON.stringify(body) + '\n')
     return true
   } catch {
     // A heartbeat missed: the status line keeps its own line, and the next
@@ -341,11 +343,11 @@ async function prune($: EngineInterface, now: number) {
   if (live.length !== list.length) await update($, crew, () => live)
 }
 
-async function show($: EngineInterface, b: Band, next: BandView | null) {
-  const key = JSON.stringify(next)
+async function show($: EngineInterface, b: Band, shown: BandView | null) {
+  const key = JSON.stringify(shown)
   if (key === b.shownKey) return
   b.shownKey = key
-  await update($, view, () => next)
+  await update($, view, () => shown)
 }
 
 async function tick($: EngineInterface, b: Band) {
@@ -362,7 +364,7 @@ async function tick($: EngineInterface, b: Band) {
   b.scan = { gen, startedAt: now }
   const current = () => b.scan?.gen === gen
   const scanning = scan($, b, root, sid)
-    .then(next => (current() ? show($, b, next) : undefined))
+    .then(found => (current() ? show($, b, found) : undefined))
     .catch(() => undefined)
     .finally(() => {
       if (current()) b.scan = null

package/node_modules/projectstore/hooks/pre-compact.mjs

@@ -3,12 +3,19 @@
 //
 // Fires before context compaction (both manual /compact and automatic).
 //
-// ONE channel: `systemMessage`, the line the user sees in their /compact
-// output. PreCompact has no `additionalContext` — the runtime rejects the whole
-// object when one is present, taking `systemMessage` down with it, so for its
-// entire history this hook assembled a packet, printed a red validation error,
-// and reached nobody. Agent-facing continuity after a compaction is
-// SessionStart's job, on `source: "compact"` (spec contract 19).
+// ONE line, through the identified harness's PreCompact carrier (spec
+// contract 22, as amended 2026-10-28). On Claude Code that is plain stdout: the
+// host discards a PreCompact `systemMessage` and echoes the hook's raw stdout in
+// the /compact output instead, where the user sees it and, on a manual
+// compaction, the model reads it after the summary. An automatic compaction
+// shows it to no one. Elsewhere — nothing identified, or nothing measured — the
+// line keeps the {"systemMessage"} object it has always had.
+//
+// PreCompact has no `additionalContext`: the runtime rejects the whole object
+// when one is present, so for its early history this hook assembled a packet,
+// printed a red validation error, and reached nobody. Agent-facing continuity
+// after a compaction is SessionStart's job, on `source: "compact"` (spec
+// contract 19).
 //
 // What this hook may CLAIM is narrower than what it knows, and deliberately so:
 //   - naming the in-flight artifact is always safe — it is a fact about the log
@@ -32,12 +39,22 @@ import {
   resolveInFlightArtifact,
   pathCell,
   commandForm,
+  preCompactCarrier,
 } from "../scripts/lib.mjs";
 
+// The file's one writer to stdout, for the success path and the catch-all
+// alike. A plain line stays one line: the object form escaped a line break in a
+// vault name or an error message for free, the text form has to fold it.
+//
 // Exits after the flush, never before: process.exit does not drain a pending
 // pipe write, and the budgeted read below can still be outstanding.
-function emit(systemMessage) {
-  process.stdout.write(JSON.stringify({ systemMessage }) + "\n", () => process.exit(0));
+function emit(line) {
+  let carrier = null;
+  try {
+    carrier = preCompactCarrier();
+  } catch {}
+  const out = carrier === "stdout" ? line.replace(/[\r\n]+/g, " ") : JSON.stringify({ systemMessage: line });
+  process.stdout.write(out + "\n", () => process.exit(0));
 }
 
 // Contract 13's budget applies here too. The session file lives inside the

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.7",
+  "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/convergence.mjs

@@ -72,8 +72,6 @@ import { registrationPaths } from "./surfaces.mjs";
 // (rule 9's command-form rule). The shells bundle it; the notice and the stop
 // name the package that runs, never a shell.
 export const PACKAGE = "projectstore";
-// What the read uses when the user's registry cannot be resolved.
-export const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 // The abbreviated packument: what `npm install` itself reads (8 728 bytes
 // against 50 896 for the full document, measured 2026-10-09).
 export const ACCEPT = "application/vnd.npm.install-v1+json";
@@ -90,8 +88,8 @@ export const MIN_READ_MS = 50;
 export const FRESH_MS = 24 * 60 * 60 * 1000;
 export const NO_CHECK_ENV = "PROJECTSTORE_NO_UPDATE_CHECK";
 
-// Strict semver 2.0 (semver.org's own grammar): a `dist-tags.latest` that is
-// anything else counts as missing — never printed, never compared.
+// Strict semver 2.0 (the specification's own grammar): a `dist-tags.latest`
+// that is anything else counts as missing — never printed, never compared.
 const NUM = "(?:0|[1-9]\\d*)";
 const PRE = `(?:${NUM}|\\d*[A-Za-z-][0-9A-Za-z-]*)`;
 const SEMVER = new RegExp(

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())