projectstore-claude 0.30.9 → 0.30.10

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

package/node_modules/projectstore/README.md

@@ -178,9 +178,10 @@ npx projectstore search "entry rule" --kind spec
 npx projectstore show adr/README.md --section index
 npx projectstore graph neighbors epics/PS-CORE/epic.md
 npx projectstore codemap --for scripts/lib.mjs
+npx projectstore guide spec --section Must
 ```
 
-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:
+The same nine 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`, `doctor` and `guide` as tools with no shell; every tool result is the CLI's `--json` for the same arguments. Elsewhere:
 
 ```
 npx projectstore mcp --project .
@@ -240,7 +241,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. 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 spec policy and the lifecycle gates** live in the vault's `.projectstore.json`, which commits with the vault. Setting `spec_policy=required` records when it took effect; stories closed before then are exempt. A story whose work needs no spec can say why in `no_spec`, and `doctor --vault --policy required` shows what the policy would report before you switch it on. A spec's contracts can carry WHEN/THEN scenarios, and a test can cite a contract, so doctor can report the contracts no test covers: see [`docs/contracts-and-tests.md`](./docs/contracts-and-tests.md).
 
 The 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.
 
@@ -411,7 +412,7 @@ The package also ships `scripts/version-guard.mjs`, which runs `npm pack --dry-r
 Opening a project that is not bound writes nothing into it: the first-run welcome is remembered in the user cache below. Every other write in a project comes from a command you run, or from the hooks and the status line once the project is bound.
 
 - **In a bound project**: `.projectstore/`, with the binding (`projectstore.json`, machine-local and git-ignored), the agents' models (`harness/`, meant to be committed), `state/` (each session's state, the band's heartbeat, the welcome marker and the status line's launcher, machine-local) and its own `.gitignore`; the agents block between the `projectstore:agents` markers in `AGENTS.md` and `CLAUDE.md`; and `.claude/settings.local.json`, which gets the status line only when you turn it on, and this checkout's plugin registration when setup or install registers the npm copy, or turns the git-marketplace copy off here, through Claude Code's own CLI.
-- **In the vault**: the artifacts, each one after you approve it; the views generated from them (the kanban, the folder indexes, the code map and the graph); `.projectstore.json`, the vault's own settings; and `.projectstore/sessions/`, one small git-ignored file per session with its id, start time, project path, host name, process id and the vault files it read or edited last, with the tool and the time. A session's file is deleted at the next session start once it has been inactive for 24 hours. A new vault also gets its own git repository.
+- **In the vault**: the artifacts, each one after you approve it; the views generated from them (the kanban, the folder indexes, the code map and the graph); `.projectstore.json`, the vault's own settings; `guides/`, only when you run `guide eject --write` to override a kind's authoring guide; and `.projectstore/sessions/`, one small git-ignored file per session with its id, start time, project path, host name, process id and the vault files it read or edited last, with the tool and the time. A session's file is deleted at the next session start once it has been inactive for 24 hours. A new vault also gets its own git repository.
 - **In your home directory**: `~/.cache/projectstore/`, or `$XDG_CACHE_HOME/projectstore/` when that is set. It holds the newest version the npm registry named (`registry.json`, kept for 24 hours), the model lists (`models/`, kept for a day: model names, labels, descriptions and families, never a key), which agent has shown its first-run welcome in a project that is not bound (`welcomed/`, one marker per agent for the machine), and the Codex package while a run installs it (`fetch/`, removed when the run ends). Setup and install from npm also write a folder of their own, `projectstore/`, under Claude Code's home (`~/.claude`, or `$CLAUDE_CONFIG_DIR`) or Codex's (`~/.codex`, or `$CODEX_HOME`), holding the marketplace the agent installs ProjectStore from, and the agent's own CLI records the plugin in that agent's plugin registry.
 
 ProjectStore never changes Claude Code's or Codex's permission settings.

package/node_modules/projectstore/agents/archaeologist.md

@@ -26,7 +26,7 @@ Locate the vault (`.projectstore/projectstore.json` → `vault_path`). Read `adr
 `concepts/` titles + frontmatter first. Never propose an artifact that already
 exists — extend or supersede it instead, and say so.
 
-**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `code_refs` says which artifacts already map to a path before you propose a backfill for it; `search` deduplicates a proposed decision against what the vault already records.
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`, `guide`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `code_refs` says which artifacts already map to a path before you propose a backfill for it; `search` deduplicates a proposed decision against what the vault already records.
 
 Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes —
 prefer them for orientation, but fall back to a frontmatter sweep when a view is

package/node_modules/projectstore/agents/critic.md

@@ -17,7 +17,7 @@ Read the file and follow its load-bearing links (a referenced research note, ADR
 or the actual code/data behind a claim). **Verify every technical claim against
 the real source** — don't trust an assertion because it's written confidently.
 
-**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `neighbors` and `lineage` are how you follow an artifact's load-bearing links; `get_artifact` with `section` reads one section without the whole file.
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`, `guide`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `neighbors` and `lineage` are how you follow an artifact's load-bearing links; `get_artifact` with `section` reads one section without the whole file.
 
 Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes —
 prefer them for orientation, but fall back to a frontmatter sweep when a view is
@@ -31,12 +31,30 @@ implementation), issue them together; go sequential only when a result genuinely
 decides what to look at next. Quote paths with spaces (vaults often live under
 iCloud paths).
 
+**The kind's guide is your checklist.** When the artifact under review has a
+projectstore kind (frontmatter `type:`), read its authoring guide, with the
+story's `variant` when it has one (`<kind>.<variant>`, such as `story.test`):
+the MCP tool `guide` when it is exposed to you, otherwise
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide <kind> --json --project "${CLAUDE_PROJECT_DIR}"
+```
+
+A vault override wins over the package default, so this is the project's own
+rule set, the same one the author read before the draft. When the caller's
+prompt already carries the kind's checklist, it is this guide's `## Must`.
+Exit 1 means the kind has no guide: say in your verdict that the review ran
+without a kind checklist, and apply no other kind's items.
+
 ## Phase 0 — Pre-commitment (before reading in detail)
 From the artifact's type + domain, predict the 3-5 most likely problem areas ("a
 caching fix here probably ignores eviction"; "these acceptance criteria are
-probably not measurable"). Write them, then investigate each.
+probably not measurable"). Take the guide's `## Common mistakes` among them.
+Write them, then investigate each.
 
 ## Phase 1 — Verify & stress-test
+- **The guide's `## Must`** — check every item against the artifact, and
+  report each one that fails by its text.
 - **Technical correctness** — does the mechanism actually WORK? Systems gotchas:
   caching (prefix/KV-cache invalidation, eviction, hit-rate), concurrency /
   ordering / idempotency, retries, timeouts, partial failure, data-loss, protocol
@@ -52,6 +70,10 @@ probably not measurable"). Write them, then investigate each.
 - **Internal consistency & testability** — does the decomposition deliver the
   stated goal? Are the acceptance criteria objectively verifiable, and do they
   cover the failure modes the problem statement raised?
+- **A story that opts out of a spec** (`no_spec: "<reason>"`) — does the
+  reason hold? Non-trivial "how", or work across several source files, needs
+  a spec. A research spike takes a light spec, not a reason. A reason such as
+  "n/a" or "small" is a finding.
 
 ## Phase 2 — Gap analysis ("What's Missing") — highest-leverage step
 Standard reviews evaluate what IS present; explicitly hunt what ISN'T: "What would
@@ -80,7 +102,8 @@ by: …" — but NEVER downgrade data-loss, security, or a wrong core claim. Don
 manufacture findings; if an aspect is genuinely solid, one sentence and move on.
 
 ## Output — your LAST message IS the deliverable returned to the caller
-1. **Verdict** — `ship` / `revise` / `rethink` + the single most important reason.
+1. **Verdict** — `ship` / `revise` / `rethink` + the single most important reason;
+   for a kind with no guide, add that the review ran without a kind checklist.
 2. **Findings** — severity-rated, highest first: `🔴 blocker` / `🟡 should-fix` /
    `🟢 nice`. Each: problem in one sentence (cite the exact claim / line /
    acceptance-criterion), confidence, *why it matters* (concrete consequence),

package/node_modules/projectstore/agents/librarian.md

@@ -18,7 +18,7 @@ Locate the vault via `.projectstore/projectstore.json` → `vault_path`. Read th
 READMEs for orientation, then the artifacts themselves (frontmatter + content),
 prioritizing accepted ADRs and active epics.
 
-**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. Your baseline is the whole edge set, which is one read of the `projectstore://graph` resource (or `graph.md`), never one `neighbors` call per artifact; `neighbors` is for confirming a candidate pair.
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`, `guide`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. Your baseline is the whole edge set, which is one read of the `projectstore://graph` resource (or `graph.md`), never one `neighbors` call per artifact; `neighbors` is for confirming a candidate pair.
 
 Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes —
 prefer them for orientation, but fall back to a frontmatter sweep when a view is

package/node_modules/projectstore/agents/planner.md

@@ -19,7 +19,7 @@ epics' `code_refs`, and the modules they point at don't depend on each other —
 read them together; go sequential only when a result genuinely decides what to
 look at next. Quote paths with spaces (vaults often live under iCloud paths).
 
-**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. `code_refs` with an epic id is the epic↔code mapping Phase 0 asks for, in one call. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows.
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`, `guide`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. `code_refs` with an epic id is the epic↔code mapping Phase 0 asks for, in one call. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows.
 
 Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes — prefer them for orientation, but fall back to a frontmatter sweep when a view is missing or its `generated_at` predates recent artifact changes (compare file mtimes; a false-stale just costs a sweep).
 
@@ -46,6 +46,12 @@ spec contracts = durable how; the story's `## Implementation Plan` = per-story
 route (your output feeds it via `/projectstore:story plan`); `## Technical
 Notes` = incidental constraints discovered during work.
 
+**Spec or no spec.** When the story has no covering spec, say whether it
+needs one, and why. Work whose "how" is non-trivial, or that will touch three
+or more source files, needs a spec. A release, a text or site change, or a
+small fix may instead declare `no_spec: "<reason>"` at the plan gate, which
+the story command writes. A research spike takes a light spec, not a reason.
+
 ## Phase 1 — Explore the codebase
 
 Use Grep / Glob / Read / Bash to find: the module(s) that own this concern, the

package/node_modules/projectstore/agents/reviewer.md

@@ -18,7 +18,7 @@ its Description, Decomposition, and **Acceptance Criteria** — plus the parent
 epic and the plan if one was produced. If the caller named no story, ask the diff
 which story it serves (grep the vault) before falling back to a plain code review.
 
-**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `lineage` on the story returns its covering specs and their ADRs in one call; `code_refs` answers whether the parent epic's footprint needs widening; `search` locates the story and its acceptance text.
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`, `guide`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `lineage` on the story returns its covering specs and their ADRs in one call; `code_refs` answers whether the parent epic's footprint needs widening; `search` locates the story and its acceptance text.
 
 Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes —
 prefer them for orientation, but fall back to a frontmatter sweep when a view is
@@ -39,6 +39,13 @@ both sets are green and every covering spec is `active`. Report a covering
 spec still in `draft` as a blocker under `spec_policy: required` (vault's
 `.projectstore.json`).
 
+**A declared opt-out, at close.** A story with `no_spec: "<reason>"` has no
+covering spec on purpose. Compute its files (Output 4). If it touches three
+or more source files (tests do not count; a directory counts as several),
+that is a 🔴 finding: the story is covered by a spec, new or existing, and
+`no_spec` is removed before it closes. There is no way to silence this.
+Otherwise check that the reason still matches what the diff did.
+
 ## Phase 0 — Pre-commitment
 From the story + file list, predict the 3-5 most likely gaps ("AC #3 needs an
 error path the diff doesn't touch"; "touches a cache — invalidation risk"). Write

package/node_modules/projectstore/commands/adr.md

@@ -9,6 +9,16 @@ Steps:
 
 1. **Check config**: `test -f .projectstore/projectstore.json` — if missing, tell user to run `/projectstore:bind <path>` and stop.
 
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide adr --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
+
 2. **Render draft** by running:
 
    ```bash

package/node_modules/projectstore/commands/bind.md

@@ -95,7 +95,7 @@ Steps:
 
 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 a vault with no artifacts** (a vault `init` just made counts: its folders and README indexes are not artifacts): 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**.
+   - **New bind into a vault with no artifacts** (a vault `init` just made counts: its folders and README indexes are not artifacts): ask via AskUserQuestion — "Enable spec-first policy for this vault (every story is covered by a spec, or says at its plan gate why it needs none; 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, run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" configure --set spec_policy=<required|optional> --set lifecycle_gates=<on|off> --dry-run --project "${CLAUDE_PROJECT_DIR}"` and show its PLAN, then ask via AskUserQuestion: "Record this policy in the vault? [Yes / No]". On **Yes**, run the same command without `--dry-run`; a non-zero exit is a refusal — relay it and go on to step 8 (the binding is already written). It writes `<vault>/.projectstore.json` — vault ROOT, deliberately not inside `<vault>/.projectstore/`, whose .gitignore would keep the policy out of git — and keeps any other key in it:
 
@@ -103,11 +103,12 @@ Steps:
    {
      "spec_policy": "required",
      "lifecycle_gates": "on",
-     "spec_policy_since": "<current ISO-8601 timestamp>"
+     "spec_policy_since": "<current ISO-8601 timestamp>",
+     "gates_since": "<current ISO-8601 timestamp>"
    }
    ```
 
-   configure stamps `spec_policy_since` whenever spec_policy becomes `required` — it anchors the legacy exemption (stories done before it stay exempt; stories in progress/review at enable time are in scope).
+   configure stamps `spec_policy_since` whenever spec_policy becomes `required` — it anchors the legacy exemption (stories done before it stay exempt; stories in progress/review at enable time are in scope). It stamps `gates_since` when the lifecycle gates turn on, so the gates check stories closed after that date under either policy.
 
 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.
 

package/node_modules/projectstore/commands/concept.md

@@ -8,6 +8,15 @@ You are creating a concept note.
 Steps:
 
 1. Check config; stop if missing.
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide concept --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
 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.

package/node_modules/projectstore/commands/doctor.md

@@ -1,6 +1,6 @@
 ---
 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]"
+argument-hint: "[--install | --vault] [--policy required[@<date>]] [--fix]"
 ---
 
 You are running projectstore diagnostics (ADR-005: umbrella doctor).
@@ -13,7 +13,7 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    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.)
+   Forward only `--install` / `--vault` / `--policy <rule>` from the arguments. `--policy required` (or `required@<date>`) is a dry run of the vault section as if the spec policy were required since that date: it writes nothing, and the report opens with a `dry-run` note. 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**.
@@ -186,5 +186,18 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
   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.
+  whenever specs exist. Legacy stories (done before `spec_policy_since`, else
+  `gates_since`, or done with no `closed_at`) are exempt by design.
+- The opt-out checks run under every policy: `no-spec` (an empty reason,
+  `no_spec` beside `specs:`, or three or more source files), `no-spec-share`
+  (opt-outs against covered stories). `gates-since` suggests the stamp for
+  gates that have no date, `review-by` names an ADR due for review, and
+  `dry-run` heads a `--policy` report. None of them is repairable by `--fix`:
+  each is a judgement, or a `configure` step its message names.
+- The guide checks read the vault's `guides/` folder, the per-kind overrides
+  of the authoring guides: `guide-shape` (an override that does not parse, so
+  readers fall back to the package default), `guide-unknown` (a guide for a
+  kind the layout does not have) and `guide-stale` (an override made from an
+  older package default; the message names the command that reads the new
+  one). None of them is repairable by `--fix`: the override is the user's
+  file, and merging a newer default into it is a judgement.

package/node_modules/projectstore/commands/epic.md

@@ -11,6 +11,16 @@ Steps:
 
 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.
 
+2a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide epic --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
+
 3. **Render draft**:
 
    ```bash

package/node_modules/projectstore/commands/meeting.md

@@ -8,6 +8,15 @@ You are creating a meeting note. Today's date is auto-prefixed.
 Steps:
 
 1. Check config; stop if missing.
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide meeting --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
 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.

package/node_modules/projectstore/commands/research.md

@@ -8,6 +8,15 @@ You are creating a research note (deep investigation, comparison, benchmark).
 Steps:
 
 1. Check config; stop if missing.
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide research --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
 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.

package/node_modules/projectstore/commands/review.md

@@ -1,5 +1,5 @@
 ---
-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.
+description: Peer-review an existing artifact (ADR / research / epic / etc.) using a fresh critic-mode agent with the kind's authoring guide as its checklist. Returns concrete improvements, no sycophancy.
 argument-hint: <path-to-artifact>
 ---
 
@@ -13,13 +13,13 @@ You are running a peer review on a projectstore artifact.
 
 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**:
+4. **Load the guide**: read the kind's authoring guide (the kind from step 3; for a story whose frontmatter has `variant:`, use `<kind>.<variant>`):
 
    ```bash
-   cat "${CLAUDE_PLUGIN_ROOT}/scaffold/checklists.json"
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide <kind> --json --project "${CLAUDE_PROJECT_DIR}"
    ```
 
-   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.
+   Its `result.sections.Must` items are the checklist, and `result.sections["Common mistakes"]` the likely problem areas; a vault override wins over the package default, so this is the project's own rule set. Exit 1 means the kind has no guide: the review runs without a kind checklist, and the report says so. No other kind's items stand in for it.
 
 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.
 
@@ -40,9 +40,13 @@ You are running a peer review on a projectstore artifact.
    <the vault's README excerpt>
    <the folder's README excerpt>
 
-   ## Structural checklist
+   ## Structural checklist (the guide's ## Must)
 
-   <bullet list of checklist.items>
+   <bullet list of result.sections.Must, verbatim; or "none: reviewed without a kind checklist">
+
+   ## Common mistakes for this kind
+
+   <bullet list of result.sections["Common mistakes"], when present>
 
    ## Report format (strict)
 
@@ -86,4 +90,4 @@ You are running a peer review on a projectstore artifact.
 
 - 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.
+- Selective default: if user invoked `/projectstore:review` on a kind whose guide has `default_review: false` (e.g. meeting), still run — they asked explicitly. Just don't auto-trigger via skill.

package/node_modules/projectstore/commands/runbook.md

@@ -8,6 +8,15 @@ You are creating an ops runbook.
 Steps:
 
 1. Check config; stop if missing.
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide runbook --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
 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.

package/node_modules/projectstore/commands/spec.md

@@ -17,6 +17,16 @@ Dispatch on the first argument:
 
 1. **Check config**: stop if `.projectstore/projectstore.json` missing.
 
+1a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide spec --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
+
 2. **Render draft**:
 
    ```bash

package/node_modules/projectstore/commands/story.md

@@ -16,7 +16,17 @@ the two cannot collide).
 
 1. **Check config**: stop if `.projectstore/projectstore.json` missing.
 
-2. **Validate args**: epic-id (positional 1) + title (rest). If only one word, ask for the title. An optional `--spec SPEC-ID` names the covering spec — put it into the rendered draft's `specs:` list (inline flow: `specs: ["SPEC-001"]`). Under `spec_policy: required` (vault's `.projectstore.json`), remind that every story needs a covering spec before implementation starts.
+2. **Validate args**: epic-id (positional 1) + title (rest). If only one word, ask for the title. An optional `--spec SPEC-ID` names the covering spec — put it into the rendered draft's `specs:` list (inline flow: `specs: ["SPEC-001"]`). Under `spec_policy: required` (vault's `.projectstore.json`), remind that a story needs a covering spec before implementation starts, or a `no_spec` reason declared at the plan gate.
+
+2a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide story --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
+   and `## Length`: the critic checks the same `## Must` items. Exit 1 means
+   this kind has no guide; say so and go on.
 
 3. **Render draft**:
 
@@ -42,12 +52,26 @@ the two cannot collide).
 
 1. **Resolve the story file** (second argument). Ambiguous → list candidates and ask.
 
+1a. **(plan only) A spec, or a reason.** When the vault's policy is
+   `required` and the story has neither a `specs:` entry nor a `no_spec`
+   reason, ask the user once: name the covering spec, or say in one sentence
+   why this story needs no spec (a release, a text or site change, work with
+   no non-trivial "how"). A reason becomes `--no-spec '<reason>'` in step 2 and
+   in the re-run of step 5, single-quoted (write an apostrophe inside it as
+   `'\''`). Research spikes take a light spec,
+   not a reason. A story that will touch three or more source files needs a
+   spec: the reviewer flags an opt-out like that at close.
+
 2. **Run the compute script** (pure — writes nothing):
 
    ```bash
    node "${CLAUDE_PLUGIN_ROOT}/scripts/story-section.mjs" <plan|close> "<story-path>"
    ```
 
+   On a plan with a reason from step 1a, add `--no-spec '<reason>'` to that
+   command. It writes `no_spec` into the returned frontmatter, and it refuses
+   a story that already lists specs.
+
    It returns `{ path, changed, notes, content }`: section inserted when
    absent, status transition, lifecycle timestamps (`started_at` /
    `plan_updated_at` / `closed_at` — stamped unconditionally; the

package/node_modules/projectstore/docs/extending.md

@@ -6,7 +6,8 @@ Since v0.14 the kind machinery is layout-driven: `draft.mjs` builds ANY kind
 declared in the layout, and doctor's template check follows the layout instead
 of a hardcoded list. A new kind needs **six touch points** — note that **all
 six live inside the plugin installation**, not in your vault (there is no
-vault-side layout or template override):
+vault-side layout or template override). The one exception is the guide
+(step 4): a vault may override it, file by file.
 
 1. **Layout folder entry** — `scaffold/layouts/<name>.json` → `folders`:
 
@@ -46,8 +47,31 @@ vault-side layout or template override):
    but an empty date sorts first, so the kind's rows pile up at the top of
    its index and stay there.
 
-4. **Checklist entry** — `scaffold/checklists.json`, consumed by
-   `/projectstore:review` and the `projectstore-peer-reviewer` skill. English-only by design.
+4. **Guide file** — `scaffold/guides/<kind>.md`, the kind's authoring guide:
+   frontmatter `guide_for: <kind>`, `guide_version: 1` and `default_review`
+   (bare values, no trailing comments), then `## Lens`, `## Must`,
+   `## Common mistakes`, `## Do not write` and `## Length`. Only `## Must` is
+   required; its plain bullets are the checklist the critic checks. The kind's
+   command reads the guide before the draft, `/projectstore:review` and the
+   critic check its `## Must`, and the `projectstore-peer-reviewer` skill reads
+   its `default_review`. The headings are English in every vault language; the
+   package defaults are English only. Bump `guide_version` whenever you change
+   a default's text, then record it:
+
+   ```
+   node tests/fixtures/guides.mjs --write
+   ```
+
+   A project overrides a guide in its vault, as `<vault>/guides/<kind>.md`,
+   which replaces the package file whole. To start from the default:
+
+   ```
+   npx projectstore guide eject <kind> --write
+   ```
+
+   Doctor reports a vault guide that does not parse (`guide-shape`), names an
+   unknown kind (`guide-unknown`), or was made from an older default
+   (`guide-stale`).
 
 5. **Command prompt** — `commands/<kind>.md`, a prompt (not code). It renders
    the draft with the line below, previews it, and gates every write behind
@@ -181,8 +205,23 @@ nothing checking that they agree — see the PS-I18N epic's backlog.
 
 `<vault>/.projectstore.json` (vault root — committed with the vault, survives
 clones) carries `spec_policy: required|optional`, `lifecycle_gates: on|off`,
-and `spec_policy_since` (ISO-8601). See ADR-007 in the project vault and
-`commands/doctor.md` for which checks each key activates.
+`spec_policy_since` and `gates_since` (ISO-8601). See ADR-007 and the spec
+policy ADR in the project vault, and `commands/doctor.md`, for which checks
+each key activates.
+
+- `configure` stamps `spec_policy_since` when the policy becomes `required`,
+  and `gates_since` when the lifecycle gates turn on. A done story closed
+  before the date is legacy. The lifecycle checks read `spec_policy_since`,
+  then `gates_since`.
+- A story may declare `no_spec: "<reason>"` at the plan gate instead of a
+  covering spec. Under `required`, doctor accepts it. Under any policy it
+  checks the declaration:
+  - an empty reason, or `no_spec` beside `specs:`, is an issue;
+  - three or more source files in the story's `code_refs` is a warn;
+  - when opt-outs outnumber covered stories among code stories, that is a
+    warn.
+- `doctor --vault --policy required[@<date>]` shows what `required` would
+  report, without writing anything.
 
 ## Contributing back
 

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.9",
+  "version": "0.30.10",
   "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/scaffold/guides/adr.md

@@ -0,0 +1,42 @@
+---
+guide_for: adr
+guide_version: 1
+default_review: true
+---
+
+## Lens
+
+The architect who will be asked in a year why this was decided. Write for a stranger who has only this file: they must be able to implement the decision, and to find what was rejected and why.
+
+## Must
+
+- Decision section is unambiguous — a stranger could implement it from this file alone, with no other context.
+- At least one named Alternative is present with an explicit rejection reason ('Rejected because: ...').
+- Consequences include at least one Negative / trade-off stated honestly. Reject sales framing.
+- All hand-wavy referents ('we', 'users', 'the system') are resolved to concrete actors or components.
+- No marketing language: 'blazingly', 'robust', 'best-in-class', 'magnificent', 'rock-solid', etc.
+- Context explains why the decision is needed NOW (vs. a year ago or in 6 months).
+- References cite at least one external doc / prior ADR / RFC if relevant.
+- Status, Date, Authors metadata filled (not template placeholders).
+- No TODOs, no '...', no empty bullets in the final body.
+
+## Common mistakes
+
+- The Decision restates the Context or lists options instead of deciding. Number each decision, so a test or a reviewer can tell whether the code does it.
+- Alternatives are straw men: no real Pros, and a "Rejected because" that fits any project. Name this project's constraint.
+- Claims about the code written from memory. Cite the file and symbol; copy counts and numbers from the source or a measurement.
+- Consequences list only the good. Negative / trade-offs is the section a critic reads first: state the cost and who pays it.
+- A rule with no enforcement point. Say which test, doctor check or command text makes it true.
+- An accepted ADR it amends or contradicts is not named, or is contradicted silently.
+- Artifacts named by session shorthand instead of their title (and, for an epic or story, its parent).
+
+## Do not write
+
+- A plan, a file list or a task list: those belong to the spec and the story.
+- The Decision restated under Rationale.
+- Marketing adjectives, or hedges (might, ideally, probably) inside a Decision.
+- The ADR's own revision history in the body: the vault history holds it.
+
+## Length
+
+One decision fits one screen; the whole ADR 100 to 250 lines. Past 300, split it into ADRs with their own lifecycles.

package/node_modules/projectstore/scaffold/guides/concept.md

@@ -0,0 +1,10 @@
+---
+guide_for: concept
+guide_version: 1
+default_review: false
+---
+
+## Must
+
+- Definition fits in one paragraph; a stranger leaves knowing what the concept IS.
+- Examples ground the concept (at least one concrete case).