projectstore-claude 0.30.9 → 0.30.11

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.11",
       "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.11",
   "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

@@ -1,6 +1,6 @@
 ---
 description: Create a new story inside an existing epic, or run its lifecycle gates (plan / close).
-argument-hint: <epic-id> <title> [--spec SPEC-ID] | plan <story> | close <story>
+argument-hint: <epic-id> <title> [--spec SPEC-ID] [--variant test] | plan <story> | close <story>
 ---
 
 You are managing a story: creating one, or running its lifecycle gates.
@@ -16,15 +16,39 @@ 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.
+
+   An optional `--variant test` makes a **test story**: one that plans the
+   tests for a spec's contracts, written to the `story.test` guide. Only
+   `test` is defined: refuse another value and name `test`. Remove `--variant test` and `--spec SPEC-ID` with its
+   value from the arguments before any `draft.mjs` call, in step 3 and in the
+   re-run of step 6: the script reads every remaining word as the title, so a
+   flag left in would end up in the title and the slug.
+
+2a. **Read the guide** for this kind before writing anything:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide story --project "${CLAUDE_PROJECT_DIR}"
+   ```
+
+   For a test story read `guide story.test` instead, in the same form.
+
+   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
-   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" story "$ARGUMENTS"
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" story <epic-id> "<title>"
    ```
 
-   The script fails if the epic folder does not exist. Surface the error and suggest `/projectstore:epic <id> "<title>"` first.
+   The epic id and the title only, with the flags of step 2 removed. The
+   script fails if the epic folder does not exist. Surface the error and suggest `/projectstore:epic <id> "<title>"` first.
+
+3a. **For a test story**, replace the draft's commented `# variant: test …`
+   line with `variant: test` before the preview, the way `--spec` fills
+   `specs:`. The critic then reviews the story against `story.test`.
 
 4. **Preview**: path + first ~25 lines.
 
@@ -32,9 +56,10 @@ the two cannot collide).
 
    When prompting "Edit", note that the story template has a `Decomposition` checklist — if the user wants to seed it with concrete tasks from the current conversation, regenerate with those tasks pre-filled in place of the empty checkboxes.
 
-6. **Post-approval race re-check** (Layer 1): re-run `draft.mjs story "$ARGUMENTS"` and re-read its `collision` field — an exact-name `test -e` cannot see normalized cross-era collisions (`story-006-foo.md` vs `story-foo.md`). If `collision` is non-null, surface it as a topic collision (`"<identity>" already exists as <with>`), and ask: extend the existing story, pick a different slug (`-2` is a deliberate distinct identity), or cancel. Render `warnings` entries as `⚠️` lines in the preview too.
+6. **Post-approval race re-check** (Layer 1): re-run `draft.mjs story <epic-id> "<title>"` (the same stripped arguments as step 3) and re-read its `collision` field — an exact-name `test -e` cannot see normalized cross-era collisions (`story-006-foo.md` vs `story-foo.md`). If `collision` is non-null, surface it as a topic collision (`"<identity>" already exists as <with>`), and ask: extend the existing story, pick a different slug (`-2` is a deliberate distinct identity), or cancel. Render `warnings` entries as `⚠️` lines in the preview too.
 
-7. **On Yes** (path free): Write file.
+7. **On Yes** (path free): Write the file you previewed, with the step-2 and
+   step-3a edits (`specs:`, `variant: test`), not the re-run's raw draft.
 
 8. **Suggest next**: "Now decompose the work in the `Decomposition` section, or run `/projectstore:kanban` to refresh the board. Before implementation: `/projectstore:story plan <story>`."
 
@@ -42,12 +67,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/contracts-and-tests.md

@@ -4,7 +4,10 @@ A spec's behavioral contracts are numbered and testable. This page shows how
 to write a contract so a test follows from it, how a test cites the contract
 it covers, and what doctor reports. It describes Part A of the ADR *Spec
 policy, revised: contract scenarios and test citations that doctor counts,
-and a declared per-story opt-out from a spec*.
+and a declared per-story opt-out from a spec*, and decisions 6 and 7 of the
+ADR *One authoring guide per artifact kind, read by the author before the
+draft and by the critic after, overridable from the vault* (edge and failure
+marks, and test stories).
 
 All of it is optional. A spec without scenarios, and a test without a
 citation, stay valid.
@@ -31,8 +34,75 @@ The items are a list, so Markdown keeps one step per line. The keywords stay
 in English in every language, like `— stories:`: a tool matches them
 literally.
 
-Doctor reads scenarios for one thing only. If a contract's scenario has no
-`WHEN` (or `GIVEN`), or no `THEN`, it reports an info.
+Doctor reads scenarios for two things. If a contract's scenario has no
+`WHEN` (or `GIVEN`), or no `THEN`, it reports an info. And it counts the
+scenarios marked as an edge or a failure case, below.
+
+An item may wrap: a line indented deeper than its dash, before a blank line,
+belongs to the item above it.
+
+## Marking an edge or a failure case
+
+A scenario's `WHEN` or `GIVEN` item may end with `(edge)` or `(failure)`:
+
+```markdown
+3. **A stale index is reported.** Doctor compares each folder index with the
+   artifacts on disk and reports a row that no longer matches.
+   - GIVEN an index row whose status differs from the artifact's frontmatter
+   - WHEN doctor runs with --vault
+   - THEN it reports an index finding that names the folder
+   - GIVEN a folder whose README is missing (edge)
+   - WHEN doctor runs with --vault
+   - THEN it reports the missing index, and nothing else in that folder
+```
+
+`(edge)` is for a case that comes from the input or the state: boundary
+values, invalid input, a state transition, an upgrade from an older state.
+`(failure)` is for a case where something else fails: a dependency, a retry
+or a concurrent run, a partial failure, a rollback. A happy-path scenario
+has no mark.
+
+The mark is lowercase English in ASCII parentheses, at the very end of the
+item (on its last line when the item wraps). A mark on an `AND` or `THEN`
+item, in the contract's prose, inside backticks, or followed by more text
+does not count.
+
+For each active spec, doctor lists the contracts that carry scenarios and
+have none marked: their scenarios show only the happy path. It counts the
+marks and does not judge them. Whether a marked scenario is a real edge case
+is the critic's question.
+
+## Writing a test story
+
+A test story plans the tests for one or more contracts. Create it with the
+variant flag, and its draft is written to the test lead's guide, `story.test`:
+
+```
+/projectstore:story PS-X "Tests for the stale-index contract" --variant test
+```
+
+The guide asks the story to name the contracts it covers by token, to list
+the cases that apply to each (boundary values, invalid input, state
+transitions, failure of a dependency, retry and concurrency, partial failure,
+upgrade from an older state, rollback), to say which cases it leaves untested
+and why, and to require a citation on every test it adds. For example:
+
+```markdown
+## Description
+
+Covers [example#3]. The scenario shows the happy path; the cases below are
+the ones a production vault hits.
+
+## Decomposition
+
+- [ ] Boundary: an index with no rows, and one with a row per artifact.
+- [ ] Invalid input: a row whose link points at no file.
+- [ ] Partial failure: one folder's README unreadable, the others fine.
+- [ ] Not tested: concurrency. Doctor is read-only, so two runs cannot race.
+```
+
+The story has `variant: test` in its frontmatter and follows every other
+story rule: the plan and close gates, evidence, the board.
 
 ## A contract no test can cover
 
@@ -97,6 +167,7 @@ skipped. Tests outside the bound project, or in a submodule, are not seen.
 | `citation-unknown` | warn | A token whose key is no spec's id or alias, or whose number is not a contract of that spec |
 | `citation-superseded` | info | A token that cites a superseded spec |
 | `scenario-shape` | info | A scenario without a WHEN/GIVEN or a THEN |
+| `contract-happy-path-only` | info | One line per active spec: the contracts that carry scenarios and have none marked `(edge)` or `(failure)` |
 | `spec-alias` | issue | A duplicate alias, an alias equal to another spec's id, or the reserved `example` |
 | `evidence-citation` | warn | Under `lifecycle_gates: on`: a story's evidence names a token that no file in the project carries |