projectstore-codex 0.0.1 → 0.28.2

package/node_modules/projectstore/commands/agents.md

@@ -0,0 +1,180 @@
+---
+description: Manage bundled-agent integration in this project — register/unregister the routing block in CLAUDE.md/AGENTS.md, inspect state, or configure which model its agents run on.
+argument-hint: "<register | unregister | status | configure>"
+---
+
+You are managing projectstore's agent integration (ADR-002 block lifecycle,
+ADR-003 presets as revised by ADR-008 — model per invocation, no copies). Require a bound project for every
+subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind`).
+
+## `register` — write the managed routing block
+
+1. **Ask** via AskUserQuestion: "Register projectstore's agents in
+   CLAUDE.md/AGENTS.md so every session routes to them (critic after
+   authoring artifacts, planner before implementing, reviewer before commit)?
+   [Yes / No]". On No, stop.
+2. **Run the verb** and print its output verbatim:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"
+   ```
+   It renders the block from the installed plugin's template ∩ the layout's
+   roster (`scaffold/layouts/<layout>.json` — only routable agents get lines;
+   the entry-rule line, the instruction-conflict line, the
+   model-resolution line and the vault-native communication line always stay), places it (`AGENTS.md` when it
+   exists, else `CLAUDE.md`; a block in the other file is migrated, never
+   duplicated; `CLAUDE.md` gets an `@AGENTS.md` import), previews every
+   write, and applies because the harness is named. A current block is
+   reported and left alone; a stale one is replaced in place with the user's
+   prose byte-identical.
+3. A non-zero exit is a refusal — a duplicated or unclosed block, a missing
+   template — relay it and stop. Never write the block with the Write or Edit
+   tool: the verb is the only writer (install spec, contract 6). One exception,
+   read from the output, not assumed: when it shows the block applied and the
+   `layout` item skipped as deferred to a terminal outside the session, the
+   exit 1 is that deferral. The block is registered — say so, and for the move
+   relay the command the startup line or `/projectstore:doctor`'s
+   `layout-legacy` finding names; never compose one. Any other non-zero exit
+   is a refusal.
+
+## `unregister` — remove what register added
+
+1. Ask via AskUserQuestion ("Remove projectstore's agents block? [Yes / No]"),
+   then run and print verbatim:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" uninstall --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"
+   ```
+   It removes the marked block; deletes a `CLAUDE.md` that held nothing else,
+   or nothing but the `@AGENTS.md` import registration added; and leaves every
+   user-authored line in place. A non-zero exit is a refusal (a block whose
+   open marker was re-wrapped, or that appears twice in one file) — relay it
+   and stop; never report success over it, and never remove the block by hand.
+
+## `status` — read-only report
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" plan --json --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
+and report each item's `state` from `result.items[]` — the bin wraps the plan in its envelope (`ours-current`, `ours-stale` with its reason,
+`ours-absent`, or a refusal). Then:
+
+- Block: present in which file, marker version vs the installed template, agent
+  names vs the layout roster.
+- Model: run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents show --json --project "${CLAUDE_PROJECT_DIR}"`
+  and report `result.resolved` — per roster agent, the model the verb would
+  pass and its `source` (`per_agent`, `default`, or `null`: the agent's own
+  frontmatter), resolved by the verb over the active harness's overlay
+  (`result.path`) so nothing here re-derives it; `result.unknown` (configured
+  names no roster agent carries — nothing runs under them), `result.rejected`
+  (keys the overlay may not carry) and `result.agents_in_binding` (a pre-0.28
+  leftover; point at `upgrade`), and
+  whether `CLAUDE_CODE_SUBAGENT_MODEL` is set (it overrides everything) and
+  whether `CLAUDE_CODE_EFFORT_LEVEL` is set (ADR-008 makes it the only thing that
+  can move the agents off `effort: max`, and it beats frontmatter). **Warn when
+  `result.resolved.clerk.model` is anything but `sonnet` or `haiku`** (that
+  literal pair is the rule, so it is never re-derived; an unknown custom id also
+  warns, with "verify it is cheap"): the clerk transcribes approved
+  content and runs a pinned procedure — paying reasoning-model prices there is
+  the misallocation its ADR exists to end; point at `configure` to pin
+  `per_agent.clerk`.
+- Leftover copies: anything in `.claude/agents/` or `~/.claude/agents/` carrying
+  `# source: projectstore v…`. Report these as **overriding nothing** (ADR-008)
+  and point at `configure` to clean them up — do not present them as the active
+  configuration, because they are not.
+
+## `configure` — model per invocation, recorded in config (ADR-008)
+
+> **Why there are no override copies here.** ADR-003 wrote
+> `<project>/.claude/agents/<name>.md` believing an equal `name:` shadows the
+> bundled agent. It does not: plugin agents register as `projectstore:<name>`,
+> project agents bare, so the names never collide, the scope-priority rule never
+> fires, and the copy becomes a **sibling** — the registration block keeps
+> invoking the bundled agent and the model pinned in the copy never runs.
+> Verified by invoking both ids (ADR-003's field note). ADR-008 replaces the
+> mechanism: the choice lives in config and rides the **per-invocation `model`
+> parameter**, which sits above the agent file's frontmatter.
+
+1. **Preset question** (one choice for ALL roster agents), with this education
+   line in the question text: *"These agents don't write code — they are
+   critics, planners, and reviewers; they perform best on strong models at high
+   effort. The one exception is the clerk, which only transcribes approved
+   content — it stays cheap regardless of the preset."* Options: keep bundled default (`opus`) / `fable` / `sonnet` /
+   custom model ID (free-form). Offer the current session's model as a hint
+   option — you know what you are running on. **Do not ask about effort** — see
+   step 5. **`inherit` is no longer offered**: it meant "follow the session's
+   model", and that cannot be expressed per invocation — passing nothing falls
+   through to the bundled `model: opus`, not to the session. A user who wants
+   session-follow behaviour should pick their session's model explicitly, or set
+   `CLAUDE_CODE_SUBAGENT_MODEL=inherit`, which does mean exactly that.
+2. **Optional follow-up**: "configure individually?" → per-agent model for each
+   roster agent. Skippable.
+3. **Apply**: after the AskUserQuestion, run the verb and print its output —
+   `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents configure --harness claude-code --default <model> [--agent <name>=<model> …] --project "${CLAUDE_PROJECT_DIR}"`
+   (naming the harness is the confirmation; the verb writes
+   `.projectstore/harness/claude-code.json → agents` and nothing else — never
+   Edit or Write the file yourself). **Whenever `--default` is set and no
+   `--agent clerk=…` is, the verb pins `per_agent.clerk.model: "sonnet"`** and
+   says so — a strong roster preset must not silently lift the clerk with it;
+   an explicit clerk choice in step 2 (`--agent clerk=<model>`) wins. The same
+   applies as a **migration**: an overlay carrying a default with no clerk pin
+   gets the pin on any `configure` run. `--agent <name>=` (empty) removes a
+   per-agent key; `--reset` empties the block ("leave every agent to its own
+   frontmatter"), and a `--default`/`--agent` given with it applies on top of
+   the emptied block. A name outside the layout's roster is a usage error
+   naming the roster — a model written under a name no agent carries would
+   never run. That file is the whole output of this command — **never write
+   an agent copy into `.claude/agents/`**. The verb never writes an `effort`
+   key; one already inside the agents block is dropped by the next `configure`
+   write and named in its preview, and until then doctor reports it as a key the
+   overlay may not carry — it has no effect (the effort you configured is not
+   the effort that runs).
+4. **Migrate away from copies**: if `.claude/agents/` holds copies carrying
+   `# source: projectstore v…`, they are pre-ADR-008 leftovers that override
+   nothing. Offer to delete them **one approval per file** (matching `/projectstore:doctor --fix`), project scope only — a copy in `~/.claude/agents/` needs a manual removal, and you should say so rather than implying this command will handle it.
+   Copies WITHOUT the provenance marker are user-authored — never touch them,
+   never mention deleting them.
+5. **Effort is not configurable per project.** The bundled agents ship
+   `effort: max`, which is the recommended value, and there is no
+   per-invocation effort parameter — only frontmatter, settings, or
+   `CLAUDE_CODE_EFFORT_LEVEL`. If the user asks for a different effort, say
+   that plainly and point at the env var; do not write a copy to achieve it.
+6. **Honesty notes to print**: an org `availableModels` allowlist silently
+   downgrades excluded models; the `CLAUDE_CODE_SUBAGENT_MODEL` env var
+   overrides everything configured here, per-invocation parameter included.
+   `/projectstore:doctor` validates config shape and reports leftover copies —
+   not entitlement, and not whether a given spawn actually passed the model.
+7. **No restart is needed** — nothing about the agent list changed. The model
+   takes effect on the next invocation that reads the config (step "Model
+   resolution" below).
+
+## Model resolution — how the configured model is actually used
+
+Any surface that spawns a roster agent (this plugin's own commands, and the
+registration block's instructions) resolves the model with one read:
+
+```
+node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents model <name> --json --project "${CLAUDE_PROJECT_DIR}"
+```
+
+and passes `result.model` as the spawn's model parameter — `null` means pass
+nothing, the agent's own frontmatter decides. The verb applies
+`agents.per_agent.<name>.model ?? agents.default.model ?? null` over
+`<project>/.projectstore/harness/<harness>.json` (the active harness's
+overlay); besides the agents block itself (harness-neutral prose with no bin
+to call — it states the rule as a file read, deliberately), nothing else
+restates that rule. Never guess a model.
+
+`agents.default` is optional and often absent (a per-agent-only config is normal);
+the resolution must tolerate that. An `effort` key, if present, is a pre-ADR-008
+leftover: ignore it.
+
+**Coverage, stated honestly.** This reaches spawns made by this plugin's commands
+and spawns a session makes while following the registration block. It does *not*
+reach description-based auto-delegation, where the platform picks the agent and
+there is no invocation site to attach a model to — those always run the bundled
+frontmatter. `CLAUDE_CODE_SUBAGENT_MODEL` is the only mechanism that covers every
+path, at the cost of applying to every subagent on the machine.
+
+## Notes
+
+- Uninstalling the plugin removes these commands but NOT the block — run
+  `unregister` first, or delete everything between the
+  `<!-- projectstore:agents -->` markers by hand.
+- Never write any file without AskUserQuestion approval.

package/node_modules/projectstore/commands/bind.md

@@ -0,0 +1,128 @@
+---
+description: Bind this project to an Obsidian vault (or any markdown directory) where projectstore will record artifacts.
+argument-hint: <vault-path> | --inherit [--layout engineering] [--lang en|ru|es|de|fr|zh]
+---
+
+You are binding the current project to a markdown vault for projectstore. The config is written by the core's `bind` / `init` verbs (roadmap A8); this interview decides the values, previews them, and asks — it never writes `projectstore.json` itself, except on the inherit path (step 0a), which copies the parent's file verbatim, and the two later stamps in steps 11–12 (`autoupdate_asked`, `statusline`), which `Edit` the file the verb wrote. The interview's `--lang` is the verb's `--language`.
+
+Parse `$ARGUMENTS`:
+- First positional arg: vault path. Expand `~` if present.
+- Optional `--inherit`: adopt the binding of the checkout this worktree was forked from (step 0a). Mutually exclusive with a positional vault path.
+- Optional `--layout <name>`: layout to use. Default: `engineering`.
+- Optional `--lang <en|ru|es|de|fr|zh>`: template language. Default: `en`. (`zh` is Simplified Chinese.)
+
+Steps:
+
+0. **Check for an existing bind** (safer rebind, v0.4.1):
+   - Read `<project>/.projectstore/projectstore.json` if it exists.
+   - `--inherit` and a positional vault path together are a contradiction: say so and stop, rather than silently picking one.
+   - If absent **and** no positional vault path was given (or `--inherit` was passed): run step **0a** first.
+   - If absent otherwise: proceed to step 1 (fresh bind).
+   - If present **and** `--inherit` was passed: print "Already bound to `<path>`." and stop. Do not fall through to the rebind comparison below — with `--inherit` there is no new path to compare, and the comparison would render an empty "proposed" side and offer to replace the binding. A no-op command must not reach a destructive option.
+   - If present, let the verb compare — run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" bind "<vault-path>" [--layout <name>] [--language <code>] --json` **without** `--rebind` (pass the user's flags, so the proposed side of the diff is what a rebind would write) (the vault is normalised on both sides: `~`, relative, trailing slash, symlinks):
+     - `result.state` is `"same"` (exit 0, nothing written): print "Already bound to `<path>`. Re-run `/projectstore:scaffold` if you need to (re)create the layout, or `/projectstore:status` to inspect it." and stop. If `result.ignored` names `layout` or `language`, say the flag was ignored — a change of layout or language is not a rebind.
+     - a refusal with code `UNREADABLE` (the config exists but is not valid JSON): relay it and stop — nothing is overwritten; the user fixes or removes the file first.
+     - `result.state` is `"different"` (exit 1, a `REBIND` refusal, nothing written — **the refusal is the diff**, and `result.kept_keys` lists what a rebind keeps): show the user a one-block diff built from the existing config and the refusal:
+       ```
+       Existing bind:
+         vault_path: <old>
+         layout:     <old layout>
+         language:   <old lang>
+       Proposed bind:
+         vault_path: <new>
+         layout:     <new layout>
+         language:   <new lang>
+       ```
+       Then ask via AskUserQuestion: "An existing projectstore bind was found. How to proceed?" with options:
+       - **Replace bind** (Recommended) — re-run the verb with `--rebind` in step 5 (every other key of the config is kept), leaving the old vault's `.projectstore/sessions/` to expire on its own 24h TTL.
+       - **Keep old bind** — make no changes, print "Kept binding to `<old>`." and stop.
+       - **Cancel** — make no changes, print "Cancelled." and stop.
+
+       Only on **Replace bind**, continue with the remaining steps below.
+
+0a. **Inherit from the checkout this worktree was forked from** (ADR "A vault worktree is an additional write path…", decision 12). `.gitignore` ignores `.claude/`, so a worktree of a bound checkout starts unbound and every `/projectstore:*` command is dead in it — including this one's usual path.
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree.mjs"
+   ```
+
+   It prints `{state, worktree, mainCheckout, vaultPath}` and writes nothing.
+   - `state` is **not** `inheritable` → say why in one line (not a worktree, its parent is unbound too, or git could not answer) and fall through to step 1, which needs a vault path; if none was given, ask for one.
+   - `state` is `inheritable` → read the parent's `<mainCheckout>/.projectstore/projectstore.json` (or, in a checkout not yet migrated, the legacy `<mainCheckout>/.claude/projectstore.json`), show it **verbatim as a code block**, and ask via AskUserQuestion: "Adopt the binding of `<mainCheckout>` (vault `<vaultPath>`)?" — Yes / No.
+   - On **Yes**: Write that JSON verbatim to `<project>/.projectstore/projectstore.json`, **and write `<project>/.projectstore/.gitignore` beside it** with the two lines `projectstore.json` and `state/` under a comment saying they are machine-local (the verb writes them itself on every other path; this one bypasses the verb, and without them the worktree commits an absolute vault path into the index it shares with its parent). If that file already exists, add any missing line and leave the rest — it is line-merged. Then **jump straight to step 10** (the summary). Steps 1–9 and 11–12 are decisions the parent already made and the copied config already carries — layout, language, statusline, agent models, auto-update. Do not re-ask them, and do not scaffold: the vault exists and is shared.
+   - Copy the **binding only** (`projectstore.json`). Never copy `.projectstore/state/` — per-session state belonging to the other checkout — and never `harness/`: the overlays are committed and arrive from git.
+   - Do not add a provenance key to the config. The parent is resolvable from git at any time; a key would be a second source of truth for the same fact.
+
+1. **Validate the vault path** read-only first: `ls -d "<path>"` (the verb has no dry run — running it on a fresh project would write the config before step 4's approval). If it does not exist, ask the user (via AskUserQuestion) whether to create it; on Yes, step 5 runs `init` instead of `bind` (it creates the directory and binds; the layout's folders remain `/projectstore:scaffold`'s). Never `mkdir` it yourself.
+2. **Detect existing layout**: list immediate subdirectories. If you see `adr/`, `epics/`, `concepts/`, `research/` — the vault already uses an engineering-like layout; suggest `engineering`. Otherwise use the user's choice or `engineering` default.
+3. **Build the config** as JSON:
+
+   ```jsonc
+   {
+     "vault_path": "<absolute-path>",
+     "layout": "engineering",
+     "auto_inject": true,
+     "language": "en",
+     "tags": [],
+     "default_author": "<git user.name or $USER>",
+     "active_skills": true,
+     "approval_mode": "always"
+   }
+   ```
+
+   `default_author` comes from `git config --get user.name` in the project (fallback to the login name) — the verb reads it; the block above is the preview of what the verb writes on a fresh bind (a rebind rewrites `vault_path`, `layout`, `language` and keeps every other key).
+
+4. **Show the user the proposed config** as a code block. Use AskUserQuestion to confirm: "Write `.projectstore/projectstore.json` with this config? [Yes / Edit a field / No]".
+
+5. On approval, write through the core — never with the Write tool:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" bind "<vault-path>" [--layout <name>] [--language <code>] [--rebind]
+   ```
+
+   `init "<vault-path>" …` instead when step 1 chose to create the vault; `--rebind` only when step 0 ended on **Replace bind**. Naming the vault is the verb's confirmation (there is no `--yes`); the interview's AskUserQuestion in step 4 is the in-session gate. Print the verb's output. A non-zero exit is a refusal or a usage error — relay it and stop. Steps 11 and 12 below `Edit` the file this step wrote; keep them after it.
+
+6. **Check `.gitignore`**: read `<project>/.gitignore` if it exists. Our own files are self-ignored inside `.projectstore/` — the verb writes that `.gitignore` itself, carrying `projectstore.json` and `state/`, with `harness/` committed on purpose (the layout ADR); on the inherit path of step 0a, which bypasses the verb, you wrote both by hand. Unless `.claude/` is ignored wholesale, the one machine-specific entry left is the host's `.claude/settings.local.json`. If it is missing, offer (AskUserQuestion) to append it. If the user declines, skip silently.
+
+7. **Offer scaffold**: if the vault is empty or missing layout folders, ask: "Vault is empty/incomplete. Run `/projectstore:scaffold` to create the layout? [Yes / No]". If yes, invoke `/projectstore:scaffold` immediately (just describe; do not assume execution).
+
+7.5. **Vault policy** (v0.14, ADR-007 — vault-side, survives clones): check `<vault>/.projectstore.json`.
+   - If it already exists with a `spec_policy` key — respect it, print the current policy, do not re-ask.
+   - **New bind into an empty/fresh vault**: ask via AskUserQuestion — "Enable spec-first policy for this vault (every story must be covered by a spec; doctor enforces it)?" with options **Yes, `spec_policy: required` (Recommended)** / **Not yet, `optional`**. Second question: "Enable lifecycle gates (plan/close sections + evidence checks on stories)?" — **Yes, `lifecycle_gates: on` (Recommended)** / **Off for now**.
+   - **Bind to an existing vault with artifacts**: default to `spec_policy: optional`, `lifecycle_gates: off` and say doctor will suggest enabling once specs appear. Do not impose the gate on an existing backlog.
+   - On any choice, write `<vault>/.projectstore.json` (vault ROOT — deliberately not inside `<vault>/.projectstore/`, whose .gitignore would keep the policy out of git):
+
+   ```json
+   {
+     "spec_policy": "required",
+     "lifecycle_gates": "on",
+     "spec_policy_since": "<current ISO-8601 timestamp>"
+   }
+   ```
+
+   `spec_policy_since` is stamped ONLY when spec_policy is set to `required` — it anchors the legacy exemption (stories done before it stay exempt; stories in progress/review at enable time are in scope).
+
+8. **Agent registration** (v0.13, ADR-002): ask via AskUserQuestion — "Register projectstore's agents in CLAUDE.md/AGENTS.md so every session routes to them (critic after authoring artifacts, planner before implementing, reviewer before commit)? [Yes (Recommended) / No]". On Yes, run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"` and print its output (it renders from the layout's roster, migrates rather than duplicates, previews every write, and applies because the harness is named). On a rebind where a block already exists the verb reports it current or replaces it in place — do not re-ask blindly.
+
+9. **Agent model preset** (v0.13, ADR-003; mechanism per ADR-008): ask via AskUserQuestion — include this line in the question text: *"These agents don't write code — they are critics, planners, and reviewers; they perform best on strong models at high effort."* Options: **Keep bundled default — opus** (Recommended) / **fable** / **sonnet**. Do not offer `inherit` — it cannot be expressed per invocation (see `commands/agents.md`). Do not offer effort — it is not configurable per project (the bundled agents already run at `max`). Free-form model IDs and per-agent tuning live in `/projectstore:agents configure` — mention it. A non-default choice runs the `configure` apply flow from `commands/agents.md`, which writes the config only — **never an agent copy**. Skippable.
+
+10. **Print summary**: confirm the bind, list the layout's folders, suggest next commands (`/projectstore:status`, `/projectstore:adr "<first decision>"`, `/projectstore:epic <ID> "<title>"`).
+
+11. **Auto-update reminder** (v0.7+, only on first successful bind in this project): After Step 5 (config write), check whether the newly-written config has `autoupdate_asked: true`. If not, ask the user via AskUserQuestion:
+
+   > "Claude Code does not auto-update third-party marketplaces by default. Want to enable auto-update for the SmartAndPoint marketplace so you'll be notified about future projectstore releases?"
+
+   Options:
+   - **Yes, show me how** (Recommended) — respond with: "Open `/plugin` → **Marketplaces** tab → **SmartAndPoint** → toggle **auto-update** on. New releases (v0.7+) will be detected at Claude Code startup; you'll need to run `/reload-plugins` after the notification to activate them."
+   - **No, I'll handle it manually** — respond with: "OK. To pull the latest version at any time, run `/plugin marketplace update SmartAndPoint`, then `/reload-plugins`."
+   - **Already enabled** — respond with: "Great. New releases will be detected at the next Claude Code startup."
+
+   After the question is answered (regardless of choice), Edit `<project>/.projectstore/projectstore.json` to add `"autoupdate_asked": true` to the JSON object. This guarantees we ask only once per project.
+
+12. **Status line offer** (v0.13, ADR-006 — the final step, language is known by now): read `${CLAUDE_PLUGIN_ROOT}/templates/<lang>/strings.json` (fall back to `en`) and the plugin version, then show the fully rendered example:
+
+    > `[PS#<version>] 📚 <statusline_example_epic> › <statusline_example_story> (in-progress)`
+
+    (for `ru`: `[PS#<version>] 📚 Супер-фича в супер-продукте › Ручка для туалетной бумаги (in-progress)`; every bundled language ships its own example pair)
+
+    Ask via AskUserQuestion: "Show your current epic/story in the status line, composed above any existing HUD? [Yes / No]". On Yes: Edit `projectstore.json` → `"statusline": { "enabled": true }` (approval-gated), then run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface statusline --project "${CLAUDE_PROJECT_DIR}"` and print its output (it writes the `settings.local.json` entry and the launcher, previewed), and report: "Enabled — restart Claude Code in this project to apply. A fresh session shows: `[PS#<version>] 📚 <statusline_no_work>`."

package/node_modules/projectstore/commands/codemap.md

@@ -0,0 +1,50 @@
+---
+description: Regenerate code-map.md (epic ↔ code overview) from frontmatter code_refs, or set an artifact's code_refs. The command is the write path — planner/reviewer only propose refs.
+argument-hint: "[set <epic-id | story-path> <ref> [ref…]]"
+---
+
+You are managing the epic↔code mapping (ADR-004).
+
+## Bare `codemap` — regenerate the view
+
+1. **Check config**; stop if missing.
+2. Compute (read-only, the unified reconcile path):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --only codemap
+   ```
+
+   The `codemap` entry carries `{ path, changed, content?, stats }`.
+3. Show `stats` (epics, epics_with_refs, story_rows) + first ~15 lines of
+   `content` when changed.
+4. **Approval** via AskUserQuestion: Yes / No (disclose: content is recomputed
+   from frontmatter at write time; the preview is advisory). On Yes → apply
+   through the core, never the Write tool:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only codemap
+   ```
+
+   Explicit selection writes the map even on a vault with no `code_refs` yet.
+   Render the report's `codemap` entry; nonzero exit — surface the `error`.
+5. Suggest: "Refs are set via `codemap set`; reviewer proposes updates at story completion."
+
+## `codemap set <target> <ref…>` — update frontmatter (the write path)
+
+1. **Resolve target**: an epic id (`PS-AGENTS` → `epics/PS-AGENTS/epic.md`) or a
+   story path relative to the vault. Stop with a clear error if not found.
+2. **Read the file**, show current `code_refs` vs proposed (`["src/auth/", …]`).
+   Validate: repo-relative paths/globs; warn (don't block) on paths that don't
+   exist yet — planning-time refs are legitimate (doctor is status-aware).
+3. **Approval** via AskUserQuestion (diff preview). On Yes → Edit the frontmatter
+   `code_refs` line only; also bump `updated:` if the artifact has it.
+4. **Offer regen**: "Refresh the view? (runs bare `codemap`)" — on Yes, run the
+   bare flow above.
+
+## Notes
+
+- Story `code_refs` = files that story touched; epic `code_refs` = the epic's
+  overall footprint. Doctor checks story ⊆ epic and path existence
+  (status-aware). `reconcile` also regenerates the view.
+- Never write refs without approval; never let an agent edit them directly —
+  planner/reviewer *propose*, this command *writes*.

package/node_modules/projectstore/commands/concept.md

@@ -0,0 +1,17 @@
+---
+description: Create a new concept note (definition, mental model, glossary entry).
+argument-hint: <title>
+---
+
+You are creating a concept note.
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" concept "$ARGUMENTS"`.
+3. Preview path + first ~15 lines. When `index` is non-null, print `index.line` too — the exact row that will appear in the folder index, unless the index step reports a failure and no row lands at all.
+4. AskUserQuestion: Yes / Edit / No. This is the only gate: **Yes** covers the artifact and its index row. Disclose in the question that the folder's whole managed index table is regenerated from vault state at write time, so the update may also repair a stale row for another artifact.
+5. Pre-write race check (Layer 1): `test -e "<path>"`. If exists, ask: **Overwrite**, **Use new slug** (`-2`), or **Cancel**.
+6. On Yes (path free or overwrite confirmed): Write file.
+7. Index row, if `index` is non-null — apply through the core, never Write/Edit, no second gate (step 4 covers it): `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>`. The row is derived state: canonical order, atomic write, manual prose preserved. The file is already on disk, so a nonzero exit is a warning naming the folder (stderr with no JSON = rejected before any write, fix the header or restore the README; `error` in JSON = I/O failure, suggest `/projectstore:reconcile`), never a failed creation.
+8. Suggest: "Define `What is it` first, then `How it works`. Link from ADRs/research that reference this concept."

package/node_modules/projectstore/commands/doctor.md

@@ -0,0 +1,166 @@
+---
+description: Diagnose the projectstore installation (config, vault, hooks, statusline, agents wiring) and the vault's consistency (status ↔ kanban ↔ indexes, acceptance, links). Read-only by default; --fix offers approval-gated install-side repairs.
+argument-hint: "[--install | --vault] [--fix]"
+---
+
+You are running projectstore diagnostics (ADR-005: umbrella doctor).
+
+## Steps
+
+1. **Run the engine** (read-only; pass through section flags, never `--fix`):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor $ARGUMENTS_WITHOUT_FIX
+   ```
+
+   Forward only `--install` / `--vault` from the arguments: the bin's parser is strict, and any other flag is a usage error (exit 2) rather than the shrug the bare script gave. Exit 1 means findings were reported, not that the check failed (exit 2 is usage, 3 not bound) — read the report, never the exit code, as the verdict. (The bare script always exited 0; through the bin the exit code carries the verdict, so a Bash tool that colours non-zero red is colouring findings, not a crash.)
+
+   Default (no flags) runs both sections: `--install` (wiring/config) and
+   `--vault` (consistency). Print the report **verbatim**.
+
+2. **No findings** → done. One line: "Doctor is clean — N info note(s) above."
+
+3. **`--fix` requested** → walk the *install-side* findings only, one
+   AskUserQuestion per repair, never batched silently. **When `layout-legacy`
+   is in the report, it goes first and its command is the one repair** for a
+   stale-launcher `surface`, a v3 `agents-block` and `agents-in-binding` as
+   well: relay it and run nothing in-session for those (see its bullet below).
+   The report already shows the v3 block, and a block Claude Code cannot see,
+   as info that points at the move.
+   - `worktree-unbound` → this checkout is a git worktree of a bound one. Offer
+     `/projectstore:bind --inherit`, and say what it does: copies the parent's
+     binding, leaves the vault shared and unchanged, carries no session state.
+     Do not offer a fresh `bind <vault-path>` here — binding a second vault by
+     hand is exactly what this finding exists to prevent.
+   - `vault-git` → offer `git init` (+ optional first commit) inside the vault.
+   - `gitignore` → offer appending the missing entries via Edit.
+   - `agents-block` duplicate or stale → show the finding, then (after approval)
+     run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
+     and print its output: it removes the copy in the non-preferred file and
+     keeps the preferred one current. A block Claude Code cannot see — in
+     `AGENTS.md`, with no `@AGENTS.md` line in `CLAUDE.md` — is the same repair:
+     the verb adds the import. For another harness the finding names its own
+     `--harness`; relay that command. Never Edit or Write the block yourself —
+     the verb is its only writer (install spec, contract 6).
+   - `statusline` issues → offer running `/projectstore:statusline on|off`,
+     which installs or removes the entry and the launcher behind a preview
+     (the SessionStart hook only refreshes an entry that already exists), and
+     remind that a restart applies it.
+   - `surface` (a stale installed file or a stale shared entry) → offer running
+     the verb for that surface and print its output:
+     `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface <key> --project "${CLAUDE_PROJECT_DIR}"`
+     (`statusline` for the launcher, `agents_block` for the block). When more
+     than one surface is stale — the shape of a plugin update — offer the one
+     command that covers them all:
+     `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" upgrade --harness claude-code --project "${CLAUDE_PROJECT_DIR}"`.
+     Repairs invoke core verbs only — never Edit, Write or delete the file yourself.
+   - `upgrade` (an info the SessionStart line carries, not a row of this
+     report: a launcher written before file stamps existed) → in this report
+     the same file is the `surface` issue above; the `upgrade` command re-stamps
+     it in one run. While `layout-legacy` is pending the startup line does not
+     carry it: the move re-stamps the launcher at its new path.
+   - `surface-foreign` → **never repairable.** A file under our prefix with no
+     provenance line is not ours: no `--fix` flow may edit, delete, move or
+     overwrite it. Print the finding verbatim and relay its resolution — rename
+     it if it is yours, or delete it yourself to let `install` take the name.
+     The verbs refuse it in code; this clause is the belt.
+   - `version-drift` → report only: name both versions and where each was
+     read; the fix is the host's update path (`/plugin update` for a git-marketplace
+     copy; for the npm registration, the `projectstore-claude` shell's `upgrade`
+     from a terminal — the `plugin-registration` finding spells the command),
+     not ours.
+   - `layout-legacy` (warn; the startup line carries it as an offer) → the project
+     still holds the pre-0.28 layout (`.claude/projectstore.json`,
+     `.claude/.projectstore/` — legacy, read through 0.29). The migration is one
+     previewed `layout` item of `upgrade`, run **from a terminal outside this
+     session** (it moves files this session reads and writes; the verb defers
+     inside one). The finding names the form for the channel this plugin was
+     installed through: the installed copy's own `bin/projectstore.mjs` for a
+     git-marketplace install or a checkout, the `projectstore-claude` shell for
+     the npm registration. Relay the finding's command verbatim and never
+     substitute the other form — the shell, run for a git-marketplace install,
+     would also move this checkout to the npm channel. When the finding carries
+     advice instead of a command — the installed copy predates the move, or
+     predates `--no-register` — relay the advice and never compose a command
+     yourself. Never move the files yourself. While this finding is in the report, its command is also the one
+     repair for a stale-launcher `surface`, a v3 `agents-block` and
+     `agents-in-binding`: do not run the in-session `install` or `upgrade` for
+     those — the deferred move makes that run stop part-way.
+   - `layout-two-configs` (issue) → both `.claude/projectstore.json` (legacy) and
+     `.projectstore/projectstore.json` exist: `install` and `upgrade` refuse until
+     one is deleted. Show both, ask the user which is the binding they mean, and
+     let them delete the other; `uninstall` and this report are not blocked.
+   - `gitignore-tracked` (warn) → **report only.** git already tracks a file
+     that is machine-local — a binding with an absolute vault path, or
+     `state/`. An ignore line cannot untrack what is in the index. Show the
+     finding's `git rm --cached` line and let the user run it: untracking is a
+     commit they own, and `--fix` never runs git on their behalf.
+   - `agents-in-binding` (warn) → the binding still carries a pre-0.28 `agents`
+     block that nothing reads; the `layout` item of `upgrade` moves it into the
+     harness overlay. Same rule as `layout-legacy`: relay the finding's command
+     verbatim, run from a terminal outside this session.
+   - `overlay-forbidden-key` / `overlay-unparseable` (issue) →
+     `.projectstore/harness/<id>.json` carries a key an overlay may not (only
+     `agents.default.model` and `agents.per_agent.<name>.model` are read) or is
+     not JSON. Print the finding. A key inside the agents block goes away on the
+     next `/projectstore:agents configure` write; a key outside it, and a parse
+     error, are the user's to edit — never rewrite the file yourself.
+   - `overlay-unknown-agent` (warn) → the overlay configures a name no roster
+     agent carries (a typo, or a newer package's agent): nothing runs under it.
+     Point at `/projectstore:agents configure` with the roster's names.
+   - `plugin-registration` (info) → nothing to repair; it names where the npm
+     registration loads from. As an **issue** — stale, or two enabled copies —
+     print the finding and relay its command verbatim (the package runner's
+     `upgrade` or `install` with `--surface plugin`): it is run **from a
+     terminal outside this session**. Never run `claude plugin …` from a Bash
+     tool here: the host CLI and this live session both rewrite the same
+     settings files, and the registration verb refuses inside a session for
+     that reason.
+   - `plugin-registration-foreign` → **never repairable**, like `surface-foreign`:
+     a marketplace directory under our name without our provenance field, or a
+     host registry naming our marketplace elsewhere. Print the finding verbatim;
+     the user moves or removes it.
+   - `harness` (info) → nothing to repair; it names what `install` can target.
+   - `mcp` → the plugin-bundled `.mcp.json` is missing or does not launch
+     `bin/projectstore.mjs mcp`: the install is incomplete — the fix is the
+     host's update path (`/plugin update`), never a hand-written file.
+   - `override-copies` → a copy carrying the provenance marker overrides nothing
+     (ADR-008): offer to **delete** it (approval-gated, one prompt per file), and
+     say that `/projectstore:agents configure` now records the model in
+     `.projectstore/harness/<harness>.json` (the active harness's overlay) instead. Never offer to delete — or edit — a
+     copy reported at `info`: no provenance marker means we cannot prove it is
+     ours, and it may be the user's own agent.
+   - `auto-update` off → offer adding `extraKnownMarketplaces.<marketplace>.autoUpdate: true`
+     to `~/.claude/settings.json` (Edit with diff preview + approval — this is the
+     user's global settings file), or point at `/plugin` → Marketplaces → toggle.
+     For "newer version available" → tell the user to run
+     `/plugin marketplace update <marketplace>` and `/reload-plugins` themselves.
+
+   **Boundary (ADR-005)**: `--fix` never repairs vault-side findings. For those,
+   point at `/projectstore:kanban` (board regen) and `/projectstore:reconcile`
+   (indexes + code-map + graph). Never offer a hand-written Edit of an index
+   row: derived views are only ever written by the core's regeneration.
+
+   `work-without-story` is not repairable by any command and must not be
+   presented as if it were: it reports that the project tree has uncommitted
+   source work while no story is `in-progress`. The response is a judgement —
+   open a story (`/projectstore:story <EPIC> "<title>"`), or decide the work is
+   a one-off and leave it. Relay the finding's own note about whether an entry
+   reminder fired: "fired and the work still went untracked" and "never fired"
+   are different problems, and the count is for this machine only.
+
+4. **Suggest next**: if issues remain, list the one-line repair per finding; if
+   only warnings remain, say they are advisory.
+
+## Notes
+
+- Detection is read-only by contract — the engine never writes; only `--fix`
+  flows (each behind AskUserQuestion) touch files.
+- The SessionStart hook runs a cheap install-only subset of this engine and
+  prints one line when it finds issues; the full vault lint runs only here.
+- Spec gates (`spec-coverage`, `spec-status`, `spec-acceptance`) and lifecycle
+  gates (`evidence`, `plan-gate`, `final-summary`) key off the VAULT-side
+  policy file `<vault>/.projectstore.json` (`spec_policy` / `lifecycle_gates`,
+  ADR-007), never the machine-local config. `spec-links` integrity runs
+  whenever specs exist. Legacy stories (done before `spec_policy_since`, or
+  done with no `closed_at`) are exempt by design.

package/node_modules/projectstore/commands/epic.md

@@ -0,0 +1,40 @@
+---
+description: Create a new epic (with stories subfolder) in the bound vault.
+argument-hint: <epic-id> <title>
+---
+
+You are creating a new epic.
+
+Steps:
+
+1. **Check config**: if `.projectstore/projectstore.json` is missing — instruct user to `/projectstore:bind` and stop.
+
+2. **Validate args**: `$ARGUMENTS` must contain at least an ID and a title. ID is a short uppercase token (e.g. `AUTH-001`, `RECPLAT-269`). If only one word was given, ask user for the title via AskUserQuestion.
+
+3. **Render draft**:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" epic "$ARGUMENTS"
+   ```
+
+   Capture the JSON output.
+
+4. **Check collision**: if `<vault>/epics/<id>/epic.md` already exists, ask user via AskUserQuestion: "Epic `<id>` exists. [Open existing / Overwrite / Cancel]".
+
+5. **Preview**: show path + content excerpt. When `index` is non-null, print `index.line` too — the exact row that will appear in `epics/README.md`, unless the index step reports a failure and no row lands at all.
+
+6. **Approval** via AskUserQuestion: Yes / Edit / No. This is the only gate: **Yes** covers the epic and its index row. Disclose in the question that the folder's whole managed index table is regenerated from vault state at write time, so the update may also repair a stale row for another epic.
+
+7. **Pre-write race check** (Layer 1): run `test -e "<path>"`. The earlier collision check (step 4) covers most cases, but another session could have created this epic during the approval delay. If exists now → ask the user via AskUserQuestion whether to **Overwrite** or **Cancel**. Do not silently overwrite.
+
+8. **On Yes** (path free or overwrite confirmed): Write the file (parent directories are created by the Write tool), then create the stories directory: `mkdir -p "<vault>/epics/<id>/stories"`. The draft script itself never touches the disk — declining at step 6 leaves the vault unchanged.
+
+9. **Index update**: if `index` is non-null in the draft JSON, apply the row through the core — never the Write/Edit tools, no second gate (the step-6 approval covers it). Must run **after** step 8: the regeneration scans the disk, so an epic written later would be missing from the table.
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>
+   ```
+
+   The row is derived state — regenerated in canonical order, written atomically, manual prose preserved. The epic is already on disk, so a nonzero exit is a warning naming the folder (stderr with no JSON = rejected before any write, fix the header or restore the README; per-target `error` in JSON = I/O failure, suggest `/projectstore:reconcile`), never a failed creation.
+
+10. **Suggest next**: print "Add the first story: `/projectstore:story <epic-id> \"<first story title>\"`".