projectstore-codex 0.0.1 → 0.28.2

package/node_modules/projectstore/commands/graph.md

@@ -0,0 +1,56 @@
+---
+description: Regenerate graph.md — the vault link graph (nodes + typed edges) derived from body links and frontmatter relations. Compute → preview → approval → apply through the core.
+argument-hint: ""
+---
+
+You are managing the vault link graph — the third root-level derived view
+beside kanban.md and code-map.md (spec:
+vault-link-graph-derived-view-and-shared-link-resolver).
+
+## Steps
+
+1. **Check config**; stop if missing.
+
+2. **Compute** (read-only, the unified reconcile path):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --only graph
+   ```
+
+   The `graph` entry carries `{ path, changed, content?, stats }` — stats:
+   node count, edge count, edges by kind.
+
+3. **Nothing changed** (`changed: false`) → report "graph.md already matches
+   the vault — nothing to regenerate." and stop.
+
+4. **Preview**: show `stats` and the first ~15 lines of `content`. Surface
+   `dead` and `ambiguous` edge counts FIRST — they are the actionable part
+   (the same facts doctor reports as wikilink findings, from the same
+   resolver).
+
+5. **Approval** via AskUserQuestion: Yes / No. Disclose that content is
+   recomputed from vault state at write time — the preview is advisory, the
+   approval covers the regeneration action. On Yes → apply through the core,
+   never the Write tool:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only graph
+   ```
+
+   Explicit selection creates graph.md when absent — bare reconcile
+   deliberately never mints it (first creation and re-minting after deletion
+   are this command's job). Render the report's `graph` entry; nonzero exit —
+   surface the `error`.
+
+6. **Verify**: run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor --vault` (exit 1 = findings, not failure)
+   and show the summary line.
+
+## Notes
+
+- The grep contract: `grep '<vault-relative-path>' graph.md` returns an
+  artifact's full typed neighborhood — outgoing AND incoming edges — in one
+  call. Node keys are full vault-relative paths, never short names.
+- Edge kinds: wikilink, mdlink, supersedes, spec-covers, spec-implements-adr,
+  epic-contains, dead, ambiguous, out-of-scope. Nothing resolves silently.
+- Hand-edits to graph.md never stick: doctor flags staleness, reconcile
+  repairs. Fix the source artifact, then regenerate.

package/node_modules/projectstore/commands/kanban.md

@@ -0,0 +1,40 @@
+---
+description: Regenerate the kanban board from story frontmatter (status, priority, title).
+---
+
+You are regenerating the kanban board.
+
+Steps:
+
+1. **Check config**. Stop if missing.
+
+2. **Compute** (read-only, the unified reconcile path):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --only kanban
+   ```
+
+   The `kanban` entry carries `{ path, changed, content?, stats }`.
+
+3. **Show stats**: print `stats.total` (total stories) and `stats.by_column`
+   (how many in each column). If `changed` is false, report "board already
+   matches frontmatter" and stop.
+
+4. **Diff preview**: if `<vault>/kanban.md` already exists, read it and show a brief textual diff vs the generated content (count of added/removed lines per column is enough). If it doesn't exist, just preview the first column.
+
+5. **Approval** via AskUserQuestion:
+   - **Yes** — regenerate the board (content is recomputed from story
+     frontmatter at write time; the preview is advisory)
+   - **No** — abort, keep current file
+
+6. **On Yes**: apply through the core — never the Write tool:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only kanban
+   ```
+
+   The write is atomic (temp + rename) and recomputed at write time. Render
+   the report's `kanban` entry; its `stats` mirror step 3. Nonzero exit —
+   surface the `error`.
+
+7. **Final**: confirm and suggest opening the file in Obsidian (the `kanban-plugin: board` frontmatter triggers the Kanban view automatically).

package/node_modules/projectstore/commands/meeting.md

@@ -0,0 +1,17 @@
+---
+description: Create a new meeting note (date-prefixed filename).
+argument-hint: <title>
+---
+
+You are creating a meeting note. Today's date is auto-prefixed.
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" meeting "$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. (In the step-5 **Append to existing** branch no new row appears: the existing note already has one, rendered from its own frontmatter.)
+4. AskUserQuestion: Yes / Edit / No. When proposing "Edit", offer to seed `Attendees` and `Agenda` from the conversation context if relevant. 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 a meeting note with this date+slug already exists, ask: **Append to existing** (open it and add a section), **Use new slug** (`-2`), or **Cancel**.
+6. On Yes (path free): 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: "Add attendees and agenda before the meeting; record decisions and action items during/after."

package/node_modules/projectstore/commands/reconcile.md

@@ -0,0 +1,73 @@
+---
+description: Re-derive every derived view (kanban, folder-index READMEs, code-map, graph) from the vault's source of truth — the repair half of doctor's vault checks. Hand-edits can never permanently desync the board.
+argument-hint: ""
+---
+
+You are reconciling the vault's derived views with their source of truth (frontmatter).
+
+## Steps
+
+1. **Check config**; stop if missing.
+
+2. **Compute** (read-only):
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile
+   ```
+
+   Output JSON: `kanban` / `codemap` / `graph` / `indexes[]`, each
+   `{path, changed, content?}`, plus `summary.changed`. A graph.md that does
+   not exist yet reports `skipped` — bare reconcile never mints the file;
+   first creation goes through `/projectstore:graph` (or `--only graph`).
+
+3. **Nothing changed** (`summary.changed == 0` and `summary.failed == 0`) →
+   report "Derived views already match frontmatter — nothing to reconcile."
+   and stop.
+
+4. **Preview**: list each changed target (path + a one-line what: "kanban board",
+   "adr/ index", "code map", "link graph"). Show a short diff excerpt for indexes.
+   **Surface any target carrying `error` first** — an errored target has no
+   `changed` flag, so it never appears in the changed list; a broken board
+   must not hide behind a clean-looking preview.
+
+5. **Approval** via AskUserQuestion: **Apply all** / **Select targets** / **Cancel**.
+   Disclose in the question that content is recomputed from the vault at write
+   time — the preview is advisory, the approval covers the regeneration action.
+
+5a. **Delegate the apply — enumerated case: two or more targets** (ADR "Artifact
+   content is authored by the context-holder, the write ceremony by a clerk").
+   When the approved set contains two or more targets, hand steps 6-7 to
+   `projectstore:clerk`: pass the exact selector list from step 4's preview and
+   the expectation that doctor ends clean. **Model (ADR-008)**: resolve
+   the model with `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents model clerk --json --project "${CLAUDE_PROJECT_DIR}"` and pass `result.model` as the spawn's model parameter (`null` → pass nothing);
+   missing key, `inherit`, or unreadable config → pass nothing and let the
+   agent's own frontmatter decide; never guess a model. The clerk applies
+   through the core exactly as step 6 specifies and reports per target. A single
+   approved target stays in the main thread — the spawn costs more than it
+   saves. No clerk available → steps 6-7 yourself; never a general-purpose
+   substitute.
+
+6. **On approval**: apply through the core — never the Write/Edit tools:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write --only <approved,targets>
+   ```
+
+   Selectors: `kanban`, `codemap`, `graph`, `indexes` (all), `indexes=<folder>` (one).
+   "Apply all" means the targets previewed in step 4, passed explicitly — not a
+   bare `--write`. The script recomputes each target immediately before its own
+   atomic replace; manual prose outside the managed Index tables is preserved by
+   construction (check-and-retry re-reads the README before writing). Render the
+   report: per target `{path, changed, written, error?}` + `summary`. A nonzero
+   exit means at least one target failed — surface its `error`.
+
+
+7. **Verify**: run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor --vault` (exit 1 = findings, not failure) and show
+   the summary line — reconcile's whole point is a clean doctor afterwards.
+
+## Notes
+
+- Reconcile owns **vault-side** repair (ADR-005 boundary); install-side repair
+  lives in `/projectstore:doctor --fix`.
+- Frontmatter is never modified here — if the *frontmatter* is what's wrong, fix
+  the artifact, then reconcile.

package/node_modules/projectstore/commands/research.md

@@ -0,0 +1,17 @@
+---
+description: Create a new research note.
+argument-hint: <title>
+---
+
+You are creating a research note (deep investigation, comparison, benchmark).
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" research "$ARGUMENTS"`.
+3. Preview path + first ~20 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 the user whether to **Overwrite**, **Use new slug** (append `-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: "Fill `Question`, then `Method`, then `Findings`. After the conclusion, consider raising an ADR if the research informs a decision."

package/node_modules/projectstore/commands/review.md

@@ -0,0 +1,89 @@
+---
+description: Peer-review an existing artifact (ADR / research / epic / etc.) using a fresh critic-mode agent with a structural checklist. Returns concrete improvements, no sycophancy.
+argument-hint: <path-to-artifact>
+---
+
+You are running a peer review on a projectstore artifact.
+
+## Steps
+
+1. **Resolve path**: `$ARGUMENTS` is the target file. If it is relative, resolve against the bound vault (read `.projectstore/projectstore.json` → `vault_path`). If config missing, stop with: "Run `/projectstore:bind <path>` first."
+
+2. **Read the artifact**: use the Read tool on the resolved path. Stop if file does not exist.
+
+3. **Identify the kind**: parse the YAML frontmatter for `type:`. If missing, try to infer from the file path (`adr/` → adr, `epics/<id>/epic.md` → epic, `epics/<id>/stories/*` → story, `research/` → research, etc.). If still unknown, ask the user via AskUserQuestion which kind to apply.
+
+4. **Load the checklist**:
+
+   ```bash
+   cat "${CLAUDE_PLUGIN_ROOT}/scaffold/checklists.json"
+   ```
+
+   Parse JSON, pick the entry by kind. If the kind has no entry, use the `adr` checklist as a generic fallback and note this to the user.
+
+5. **Gather domain context**: read the vault's top-level `README.md` and the folder README of the artifact's parent (e.g. `adr/README.md`). Keep both short — they're context for the critic, not the focus.
+
+6. **Spawn the critic agent**. Prefer this plugin's own `projectstore:critic` (purpose-built fresh-context critic, no sycophancy; named `projectstore:projectstore-critic` before v0.13). If unavailable, fall back to `oh-my-claudecode:critic`, then `general-purpose`. Use this exact prompt template:
+
+   ```
+   You are a critic-mode reviewer. You have ONLY the artifact and the
+   project context below. You did NOT participate in producing this
+   artifact. Your job is to find concrete, actionable problems — not
+   to praise.
+
+   ## Artifact ({{kind}} at {{path}})
+
+   <full file content>
+
+   ## Project context
+
+   <vault README excerpt>
+   <folder README excerpt>
+
+   ## Structural checklist
+
+   <bullet list of checklist.items>
+
+   ## Report format (strict)
+
+   Return a numbered list of findings, max 7 items. For each:
+     1. **What's wrong** — one sentence, specific (cite section / line).
+     2. **Why it matters** — one sentence.
+     3. **Suggested fix** — concrete edit, ideally a phrase to add or
+        replace.
+
+   Forbidden:
+     - Sycophancy ("Overall this is a strong ADR, but...").
+     - Generic advice without a citation.
+     - Restating what the artifact says.
+     - "Consider" without a concrete alternative.
+
+   If the artifact passes all checklist items with no concrete issues,
+   say so in one line — do not pad.
+   ```
+
+   Set the agent description to: `Peer-review of {{kind}} artifact at {{path}}`. Pass it as a foreground task (you need the result to continue).
+
+   **Model (ADR-008)**: resolve it with `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" agents model critic --json --project "${CLAUDE_PROJECT_DIR}"` and pass `result.model` as the spawn's model parameter (`null` → pass nothing). Missing key, `inherit`, or unreadable config → pass nothing and let the agent's own frontmatter decide; never guess a model. This is the only way the configured model reaches the agent — there are no override copies (`/projectstore:agents configure`). When falling back to `oh-my-claudecode:critic` or `general-purpose`, pass the same model.
+
+7. **Show findings**: print the agent's report verbatim. Number is its number.
+
+8. **Ask the user via AskUserQuestion** what to do:
+   - **Apply all** — propose Edits for each suggested fix, one at a time with diff preview + approval.
+   - **Apply selected** — ask which finding numbers to apply, then walk through them.
+   - **Note for later** — leave artifact untouched, but append a `## Review notes` section at the bottom of the file (after user approval) summarizing findings.
+   - **Skip** — do nothing, just close.
+
+9. **On any apply path**, after each Edit (approved by AskUserQuestion), update the frontmatter:
+   - `review_status: reviewed`
+   - `reviewed_at: <today's date YYYY-MM-DD>`
+
+   Do this with one final Edit after all content changes are applied.
+
+10. **Final print**: file path, what was applied / noted / skipped, and a one-line hint to commit the review if the vault is git-tracked.
+
+## Notes for the implementer (you, Claude)
+
+- Critic agent MUST NOT see the conversation that produced the artifact. Only the artifact + minimal context. That fresh framing is the whole point.
+- If the critic returns suspiciously sycophantic findings ("good overall, minor nit:"), retry once with an explicit `NO PRAISE, NO HEDGING.` injected into the prompt.
+- Selective default: if user invoked `/projectstore:review` on a kind whose `default_review` is `false` in checklists.json (e.g. meeting), still run — they asked explicitly. Just don't auto-trigger via skill.

package/node_modules/projectstore/commands/runbook.md

@@ -0,0 +1,17 @@
+---
+description: Create a new ops runbook (step-by-step how-to with verification & rollback).
+argument-hint: <title>
+---
+
+You are creating an ops runbook.
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" runbook "$ARGUMENTS"`.
+3. Preview path + first ~20 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>` (runbooks live in `ops/` — always take the folder from the draft JSON, never from the kind name). 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: "Fill `Purpose`, `Prerequisites`, numbered `Steps` with shell snippets, and always include `Verification` and `Rollback`."

package/node_modules/projectstore/commands/scaffold.md

@@ -0,0 +1,23 @@
+---
+description: Scaffold the bound vault with the layout's folder structure and README index files.
+argument-hint: [layout-name]
+---
+
+You are creating the folder structure of the projectstore layout inside the bound vault.
+
+Steps:
+
+1. **Read config**: `cat .projectstore/projectstore.json`. If missing, tell user to run `/projectstore:bind <path>` and stop.
+2. **Determine layout**: use `$ARGUMENTS` if provided, else `config.layout`.
+3. **Load layout spec**: `cat "${CLAUDE_PLUGIN_ROOT}/scaffold/layouts/<layout>.json"`. Parse it.
+4. **Show plan**: list every folder that will be created and which folders already exist. Mark new ones with `(create)`, existing with `(exists)`.
+5. **Ask approval** via AskUserQuestion: "Create the missing folders and READMEs? [Yes / Skip READMEs / No]".
+6. **Execute**:
+   - For each folder in `layout.folders`:
+     - Create directory via `mkdir -p <vault>/<folder.path>`.
+     - If `folder.readme === true` and `<vault>/<folder.path>/README.md` does not exist:
+       - Read template: `cat "${CLAUDE_PLUGIN_ROOT}/templates/<lang>/folder-readme.md.tmpl"`.
+       - Substitute `{{folder_name}}` and `{{folder_description}}` based on the folder kind.
+       - Write the README via Write tool.
+   - Also create a top-level `<vault>/README.md` if missing — a simple index pointing to each folder.
+7. **Print result**: tree of newly created files and a one-line "next step" suggestion.

package/node_modules/projectstore/commands/search.md

@@ -0,0 +1,22 @@
+---
+description: Search the bound vault for a phrase — literal, bounded, grouped by folder.
+argument-hint: <query> [--kind <type>] [--status <status>] [--limit <n>] [--case-sensitive] [--include-derived]
+---
+
+You are searching the vault for the user's query through the core's `search` verb (roadmap A8: the command is a thin front-end; the deterministic search lives in `scripts/query.mjs` and answers identically over MCP).
+
+Steps:
+
+1. Run the verb. The query is a positional and travels **behind `--`**, so a phrase that starts with `-` (a flag name, say) is searched for rather than parsed; the options, if the user gave any, go before it:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" search [--kind <type>] [--status <status>] [--limit <n>] [--case-sensitive] [--include-derived] -- "<query>"
+   ```
+
+   The project resolves from the session's project directory; do not pass `--project`. Exit 3 means the project is unbound — say so and point at `/projectstore:bind <vault-path>`; exit 2 is a usage error — relay its message.
+
+2. Print the output verbatim. It is already grouped by the vault's top-level folder with a count per group and `path:line  snippet` lines; the header says how many matches there are, whether the list was cut (`--limit`, default 20, cap 100) and whether a file hit the per-file cap (`[N in file]`). The search is literal substring, case-insensitive unless `--case-sensitive`, over artifact bodies and `title:` lines; the derived views (the board, `code-map.md`, `graph.md`) are excluded unless `--include-derived`.
+
+3. Zero matches is exit 0 and the output already suggests a shorter or case-insensitive phrase. Do not fall back to a shell `grep`: the verb is the search.
+
+4. At the end, print a hint: "Open a file with the Read tool: `Read <vault_path>/<path>`" — `vault_path` is in `.projectstore/projectstore.json` (or `status --json` → `result.vault_path`); the search output prints vault-relative paths.

package/node_modules/projectstore/commands/spec.md

@@ -0,0 +1,91 @@
+---
+description: Create a spec (normative "how" covering one or more stories), or transition its status (draft → active → superseded).
+argument-hint: <title> | activate <SPEC-ID> | supersede <SPEC-ID>
+---
+
+You are managing a **spec** — the durable, normative "how" of a subsystem
+(ADR-007): it references the ADR(s) that decided the approach, carries numbered
+behavioral contracts, and its Acceptance is **additive** to the covered
+stories' own criteria. One spec covers one or more stories and outlives them.
+
+Dispatch on the first argument:
+
+- `activate <SPEC-ID>` / `supersede <SPEC-ID>` → **Status transition flow**.
+- Anything else → **Creation flow** (the whole argument string is the title).
+
+## Creation flow
+
+1. **Check config**: stop if `.projectstore/projectstore.json` missing.
+
+2. **Render draft**:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" spec "$ARGUMENTS"
+   ```
+
+   Capture the JSON `{ kind, path, content, index, vars }`.
+
+3. **Fill before preview**: populate `adr: []` and `stories: []` (path form:
+   `"EPIC-ID/story-002"`, inline flow) from the conversation context when
+   known; write the mandatory sections (How we solve with ADR wiki-links,
+   numbered Behavioral contracts, Acceptance checkboxes with `— stories:`
+   attribution where items are story-specific). Optional sections (Modules &
+   files on disk, Testing) may be omitted for research spikes.
+
+4. **Preview**: path + full content, plus every `warnings` entry as a `⚠️`
+   line. If the draft's `collision` field is non-null, surface it as a
+   **topic collision** (`"<identity>" already exists as <with>`) and ask:
+   extend the existing spec, pick a different slug (`-2` is a deliberate
+   distinct identity), or cancel. When `index` is non-null, print `index.line`
+   too — the exact row that will appear in `specs/README.md`, unless the index
+   step reports a failure and no row lands at all. **Approval** via
+   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. **Post-approval race re-check**: re-run draft.mjs and re-read `collision`
+   — an exact-name `test -e` cannot see normalized cross-era collisions. If
+   it is now non-null, re-preview and re-ask.
+
+6. **On Yes**: Write the file. Then, if `index` is non-null, apply its index
+   row through the core — never the Write/Edit tools, no second gate (the
+   step-4 approval covers it):
+
+   ```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 artifact 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.
+
+7. **Reciprocal links**: for every entry in `stories:`, propose an Edit to that
+   story's frontmatter adding the spec id to its `specs:` list (inline flow —
+   `specs: ["SPEC-001"]`). One AskUserQuestion per file.
+
+8. **Remind**: "The spec is `draft`. Run `/projectstore:spec activate <ID>`
+   after review — a covered story must not enter implementation while its spec
+   is draft (doctor enforces this under `spec_policy: required`)."
+
+## Status transition flow
+
+1. **Resolve** the spec file in `<vault>/specs/` by id (case-insensitive
+   prefix match on the filename). If not found, list existing specs and stop.
+
+2. **Validate the transition**: `draft → active` (activate), `active →
+   superseded` (supersede). Reject anything else with the current status
+   shown. `superseded` requires the user to name what supersedes it — record
+   it in the body under References.
+
+3. **Preview the change**: current vs proposed frontmatter `status:` (+
+   `updated:` bump to today). For `activate`, remind that review is expected
+   first (`/projectstore:review <path>`) if `review_status` is still pending —
+   ask whether to proceed anyway.
+
+4. **Approval** via AskUserQuestion, then apply the Edit (frontmatter lines
+   only). Suggest `/projectstore:reconcile` if the specs index shows a stale
+   status.

package/node_modules/projectstore/commands/status.md

@@ -0,0 +1,27 @@
+---
+description: Show what's bound, the active layout, what is in progress, and whether the derived views are fresh.
+---
+
+You are summarizing the projectstore binding and the vault's state through the core's `status` verb (roadmap A8: the command renders the verb's facts; nothing here counts, lists or greps the vault by hand).
+
+Steps:
+
+1. Run:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" status --json
+   ```
+
+   The project resolves from the session's project directory; do not pass `--project`. `status` runs unbound: if `result.bound` is `false`, output "No vault bound. Run `/projectstore:bind <vault-path>` first." and stop.
+
+2. Print from `result`: `vault_path` (mark `vault_exists: false` as **missing**), `layout`, `language`, `auto_inject`, `approval_mode`, `spec_policy`, `lifecycle_gates`. If `vault_exists` is `false`, the remaining fields are `null` — stop here with "The bound vault directory is missing — restore it, or rebind with `/projectstore:bind <vault-path>`."
+
+3. **Stories** from `result.stories`: `total` on the board with the `by_status` breakdown on one line ("Stories: 72 — done 44, in_progress 3, planned 25"); if `off_board_total` is non-zero, add how many stories the board leaves off and why (`off_board`, e.g. `not_actionable 2`). Then the in-progress list — `in_progress[]` carries `epic`, `title`, `path`, `started_at`; `in_progress_total` says whether the list (capped at 5) is complete. If `stories.status` is `"error"`, print its `error` instead.
+
+4. **Views** from `result.views`: one line, `kanban`, `code_map`, `graph` each as fresh / stale / missing / unknown (`stale` is `true`, `false`, or `null` when the view's mtime could not be read; it compares the view's mtime with the newest artifact's). A stale or missing view is the cue for step 6.
+
+5. **Active sessions** from `result.sessions`: `active` is the count within the last 30 minutes; `entries[]` (capped at 5) carry `id`, `project_root`, `started_at`, `last_active` — print them as a compact table. From inside a slash command you cannot tell which entry is the current session (Claude's `session_id` reaches hooks, not commands); the user can match by `project_root` and timestamps. If `active` is greater than 1: warn "⚠️ Coordinate via /projectstore:search before creating new artifacts to avoid topic collisions (identity is the slug — ADR-010; the draft's `collision` field catches clashes at creation time)."
+
+6. Suggest the next command from what you saw: `stories.total` is 0 → "Vault looks empty — try `/projectstore:scaffold`"; any view stale or missing → "Stale views — try `/projectstore:reconcile`"; something in progress → name it and suggest `/projectstore:story` to continue.
+
+What this command no longer does, and why: the former `ls`/`find -mtime -7` walk of recently touched files is gone — its failure mode is a false "nothing changed" (an iCloud download or a git checkout resets mtimes), the opposite of the views' `stale` flag, whose false positive only costs a reconcile. The in-progress list and the views' freshness answer the same question from artifact facts. The former layout-folder check (`ls` the vault, mark missing folders) is `doctor --vault`'s job and `orientation`'s skeleton shows the folders that exist; it is not repeated here.

package/node_modules/projectstore/commands/statusline.md

@@ -0,0 +1,46 @@
+---
+description: Enable/disable the projectstore status line (current epic & story in the HUD). Flips a flag and runs the install verb, which wires it behind a preview; the SessionStart hook keeps an existing entry current across plugin updates.
+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.
+
+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 PreToolUse hook); 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 flips the flag in `.projectstore/projectstore.json` and then runs the install verb, which writes `settings.local.json` and the launcher behind a preview. The SessionStart hook only refreshes an entry that is already ours and removes it when the flag is off — it never creates one.
+
+## 1. Require a bound project
+
+Read `.projectstore/projectstore.json`. If missing → "No vault bound. Run `/projectstore:bind <vault-path>` first." and stop. (The epic/story segment needs a vault.)
+
+## 2. Parse `$ARGUMENTS`
+
+- `on` (or empty) — enable.
+- `off` — disable.
+- `status` — report only; modify nothing.
+
+## 3. `on`
+
+1. **Foreign status line check** (read-only): read `.claude/settings.local.json` if present. If it has a `statusLine` whose `command` is **not** ours (ours contains either `.projectstore/state/<harness>/statusline.mjs` — the launcher; a not-yet-migrated project's legacy launcher is `.claude/.projectstore/statusline.mjs`, also ours — or `scripts/statusline.mjs` — an older or dev wiring), warn — the hook will **not** clobber a foreign local status line, so enabling would silently do nothing (and `statusline.mjs` composes only over a base in `.claude/settings.json` or `~/.claude/settings.json`, never one in `settings.local.json`). AskUserQuestion: **Proceed anyway / Help me clear it / Cancel**. If a base HUD lives in `~/.claude/settings.json` (e.g. oh-my-claudecode), that's fine — we compose over it; no warning needed.
+2. **AskUserQuestion** (Yes / No): "Wire the status line for this project?" On Yes, run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface statusline --project "${CLAUDE_PROJECT_DIR}"` and print its output verbatim — it previews and writes the `statusLine` entry and the launcher (`.projectstore/state/claude-code/statusline.mjs`, provenance-stamped). A non-zero exit is a refusal (a foreign status line, an unparseable settings file) — relay it and stop, leaving the flag as it was.
+3. On success, read `.projectstore/projectstore.json`, set `statusline.enabled = true`. **Preserve `statusline.position`** if present (don't drop it); keep all other keys. Preview the change, then Write.
+4. Report: "Enabled. `📚 <epic> › <story>` renders above your existing HUD. **Restart Claude Code in this project** to apply now (statusLine loads at session start). If `.claude/settings.local.json` is tracked in git, add it to `.gitignore` — the entry carries a machine-specific absolute path."
+
+## 4. `off`
+
+1. **AskUserQuestion** (Yes / No): "Remove the projectstore status line from this project?" On Yes, read `.projectstore/projectstore.json` and set `statusline.enabled = false` (keep `statusline.position` + other keys) — write it **even if the flag was absent**, so the hook removes any managed `statusLine` entry it previously wrote. Preview, then Write.
+2. Run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" uninstall --harness claude-code --surface statusline --project "${CLAUDE_PROJECT_DIR}"` and print its output — it removes our `statusLine` entry and the launcher, previewed, and leaves a foreign entry alone.
+3. Report: "Disabled; restart to apply."
+
+## 5. `status`
+
+Report, read-only:
+- `.projectstore/projectstore.json` → `statusline.enabled` and `statusline.position` (default `above`).
+- `.claude/settings.local.json` → whether `statusLine` is present and ours (`command` contains `.projectstore/state/<harness>/statusline.mjs`, the legacy `.claude/.projectstore/statusline.mjs` of a not-yet-migrated project, or `scripts/statusline.mjs`), foreign, or absent. A `scripts/…` command inside the plugin cache is the pre-v0.16 pinned wiring — the hook replaces it with the launcher on the next session start.
+- `.claude/settings.json`, else `~/.claude/settings.json` → `statusLine.command` = the base HUD we compose over (or "none — standalone line").
+
+## Notes
+
+- Every write goes through AskUserQuestion. Never write without approval.
+- The command writes `.projectstore/projectstore.json` and runs the install verb for the `statusline` surface; the SessionStart hook only refreshes an entry that is already ours (and removes it when the flag is off) — it never creates one, and never touches a foreign status line.
+- Config shape: `.projectstore/projectstore.json` → `"statusline": { "enabled": true, "position": "above", "show_version": true }`. `position` is `above` (default) or `below` — the side our 📚 line sits relative to the base HUD; `show_version` toggles the `[PS#…]` badge.