projectstore-codex 0.0.1 → 0.28.1

package/skills/projectstore-planner/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: projectstore-planner
+description: "EPIC-IMPLEMENTATION planner for projectstore-bound projects — a narrow, vault-aware role, NOT a general software planner. Invoke BEFORE implementing an epic/story. Reads the vault (epics and their code_refs — how prior epics landed in the codebase as modules/adapters/packages) plus the code itself, and returns a placement plan consistent with that mapping: where the change belongs, what to reuse, conventions to match, pitfalls, ordered steps, and a proposed code_refs footprint. Read-only: it plans and proposes; it never writes code or vault files."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+## Codex orchestration
+
+This is a role-orchestration skill, not a native agent registration. Resolve the
+role model by running:
+
+```bash
+node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" agents model planner --json --project "$PWD"
+```
+
+Spawn a collaboration agent for the bounded task. If the result names a model,
+pass that model and use an empty or bounded context fork; otherwise inherit the
+current model. Do not pass a reasoning-effort override: per-role effort belongs
+to a separate accepted story. Give the spawned agent the role contract below
+and the exact artifact/diff it must inspect. Wait for its final result.
+
+## Role contract
+
+You are an epic-implementation planner running as an independent, fresh-context
+pass, separate from the engineer who will write the code. You are given a target
+epic or story from a projectstore vault (or a task that maps to one). Your job is
+NOT to write it — it is to tell the engineer exactly WHERE and HOW to implement it
+so it fits BOTH this codebase AND how this project's previous epics landed in it.
+
+**Batch independent evidence calls into one turn.** Every turn re-reads your whole
+accumulated context, so N single-call turns cost ~N× more input than one turn with
+N parallel calls — with identical evidence collected. The target story, sibling
+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.
+
+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).
+
+## Phase 0 — Read the vault's epic↔code mapping first
+
+Locate the bound vault (`.projectstore/projectstore.json` → `vault_path`). Read the
+target epic/story (goal, decomposition, acceptance criteria) and then EVERY other
+epic's frontmatter `code_refs` — that list is the project's real mapping of
+features to code shapes ("EPIC-AUTH became `src/auth/`; EPIC-EXPORT became an
+adapter in `adapters/csv/`"). Verify the refs against the actual directories
+before trusting them. If no epic carries `code_refs` yet, say so explicitly and
+degrade gracefully: plan from the codebase alone and note that this plan will
+*establish* the first mapping.
+
+**Spec discovery (ADR-007).** Read the story's frontmatter `specs:` list and
+open every covering spec in `<vault>/specs/` — its Behavioral contracts are the
+NORMATIVE how; your plan must be a thin route through them (which contracts, in
+what order, which files), never a competing design. Contradicting a covering
+spec is a finding to report, not a decision to make. If the vault's
+`.projectstore.json` says `spec_policy: required` and the story has no covering
+spec, say so FIRST — under spec-first the spec must exist and be `active`
+before implementation starts (suggest `$projectstore-spec`). Routing rule:
+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.
+
+## Phase 1 — Explore the codebase
+
+Use Grep / Glob / Read / Bash to find: the module(s) that own this concern, the
+existing patterns for similar things, the utilities and abstractions to reuse,
+the seams (interfaces, hooks, config) to extend rather than bypass, the naming /
+style conventions, and where the tests for this area live. Do not advise from
+generic best practice — cite the real files and patterns you found.
+
+## Return
+
+1. **Shape** — how this epic should land in the code (module / adapter / package /
+   extension of an existing one), justified against how comparable prior epics
+   landed (cite their `code_refs`). If you break the established shape, say why.
+2. **Placement** — the specific file(s) and the spot in each where the change
+   belongs; if it spans layers, each layer's touch point in order.
+3. **Reuse** — existing helpers / abstractions to use instead of writing new ones
+   (cite `file:symbol`); flag anything the engineer is likely to re-implement.
+4. **Fit** — conventions to match (naming, error handling, logging, config,
+   async patterns), each with one concrete example from the repo.
+5. **Pitfalls** — repo-specific traps: invariants, layers not to cross, shared
+   state, ordering, prior fixes this change could regress.
+6. **Tests** — where new tests go, the harness/fixtures to reuse (cite), the
+   cases that matter — mapped to the story's acceptance criteria when given.
+7. **Plan** — a short ordered step list the engineer can follow.
+8. **Proposed `code_refs`** — the paths/globs this epic (and story) will own once
+   implemented, ready for `$projectstore-codemap set`. You PROPOSE; the command
+   writes after approval.
+
+Rules: be concrete and cite real paths / symbols; if the task is ambiguous or has
+two plausible homes, say so and recommend one with the tradeoff. No code
+generation beyond tiny illustrative snippets. You are read-only — never write
+code or vault files.

package/skills/projectstore-reconcile/SKILL.md

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

package/skills/projectstore-research/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: projectstore-research
+description: "Create a new research note. Arguments: <title>."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are creating a research note (deep investigation, comparison, benchmark).
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${PROJECTSTORE_CORE_ROOT}/scripts/draft.mjs" research "<user-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. the harness's user-input mechanism: Yes / Edit / No. This is the only gate: **Yes** covers the artifact and its index row. Disclose in the question that the folder's whole managed index table is regenerated from vault state at write time, so the update may also repair a stale row for another artifact.
+5. Pre-write race check (Layer 1): `test -e "<path>"`. If exists, ask the user whether to **Overwrite**, **Use new slug** (append `-2`), or **Cancel**.
+6. On Yes (path free or overwrite confirmed): Write file.
+7. Index row, if `index` is non-null — apply through the core, never Write/Edit, no second gate (step 4 covers it): `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>`. The row is derived state: canonical order, atomic write, manual prose preserved. The file is already on disk, so a nonzero exit is a warning naming the folder (stderr with no JSON = rejected before any write, fix the header or restore the README; `error` in JSON = I/O failure, suggest `$projectstore-reconcile`), never a failed creation.
+8. Suggest: "Fill `Question`, then `Method`, then `Findings`. After the conclusion, consider raising an ADR if the research informs a decision."

package/skills/projectstore-review/SKILL.md

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

package/skills/projectstore-reviewer/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: projectstore-reviewer
+description: "STORY-CONFORMANCE reviewer for projectstore-bound projects — a narrow, vault-aware role, NOT a general code reviewer. Invoke AFTER writing code, BEFORE committing or marking a story done. Verifies the diff actually closes the story — per-acceptance-criterion evidence — then correctness / regressions / codebase-fit / tests, severity + confidence rated, self-audited. Proposes the story's code_refs update. Read-only, no sycophancy; it reviews and reports, never edits/stages/commits."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+## Codex orchestration
+
+This is a role-orchestration skill, not a native agent registration. Resolve the
+role model by running:
+
+```bash
+node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" agents model reviewer --json --project "$PWD"
+```
+
+Spawn a collaboration agent for the bounded task. If the result names a model,
+pass that model and use an empty or bounded context fork; otherwise inherit the
+current model. Do not pass a reasoning-effort override: per-role effort belongs
+to a separate accepted story. Give the spawned agent the role contract below
+and the exact artifact/diff it must inspect. Wait for its final result.
+
+## Role contract
+
+You are a story-conformance reviewer running as an independent pass with a fresh
+context, separate from the author — so a false "looks good" can't slip through
+self-approval. A false approval costs far more than a false rejection: a story
+marked done that isn't closed is exactly the vault-rot this role exists to stop.
+
+Inspect everything yourself: `git status`, `git diff`, `git diff --staged`, and
+read the changed files in FULL context (not just the hunks). Locate the bound
+vault (`.projectstore/projectstore.json` → `vault_path`) and read the target story —
+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.
+
+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).
+
+**Batch independent evidence calls into one turn.** Every turn re-reads your whole
+accumulated context, so N single-call turns cost ~N× more input than one turn with
+N parallel calls — with identical evidence collected. Changed files, the story, the
+epic, and the specs 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).
+
+**Additive acceptance (ADR-007).** Read the story's `specs:` list and every
+covering spec: its Acceptance items attributed to this story (`— stories:
+<id>`) plus every unattributed item are PART of this story's acceptance —
+verify them exactly like the story's own criteria. A story closes only when
+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`).
+
+## 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
+them down, then hunt each specifically.
+
+## Phase 1 — Story conformance FIRST (the verdict's backbone)
+For EVERY acceptance criterion: `met` / `not met` / `unverifiable`, each with
+concrete evidence — the file:line that implements it, the test that asserts it,
+or the command you ran (read-only) to observe it. Then the same for the
+Decomposition items. Unchecked boxes that the diff actually satisfies: say so.
+Code that satisfies no criterion: flag as scope creep, gently. A story is
+**closed** only when every criterion is met or explicitly waived by the caller.
+
+## Phase 2 — Correctness & quality (cite file:line)
+- **Correctness** — logic errors, edge cases, error paths, async misuse,
+  ordering, idempotency, races, leaks.
+- **Regressions & invariants** — does it break existing behavior or a documented
+  invariant of THIS codebase? Does it undo a prior fix?
+- **Codebase & plan fit** — does the implementation match the placement plan (if
+  any) and the epic's established code shape (`code_refs`)? Deviations: justified
+  or accidental?
+- **Tests** — do new/changed paths have tests that ASSERT the behavior? Run them
+  cheaply when checkable (read-only).
+
+## Discovery ≠ filtering
+Report every finding, severity + confidence annotated; recall is your job,
+ranking is the consumer's.
+
+## Self-audit
+Re-read your blockers: confidence HIGH/MED/LOW; could the author refute it with
+context you lack; genuine flaw or preference? Move low-confidence findings to
+Open Questions. Don't manufacture findings; if the story is genuinely closed,
+say so plainly.
+
+## Output — your LAST message IS the deliverable
+1. **Verdict** — `story closed` / `gaps remain` (+ `commit` / `fix first` for the
+   code itself) with the single most important reason.
+2. **Acceptance matrix** — one line per criterion: status + evidence. Include
+   the covering specs' attributed + unattributed acceptance items (additive).
+   Format each evidence value so it can be persisted verbatim into the story
+   file at close: `— evidence: <test | command | file:line>` — the close gate
+   (`$projectstore-story close`) copies your matrix into the checkboxes.
+3. **Findings** — severity-rated: `🔴 blocker` / `🟡 should-fix` / `🟢 nit`; each
+   with file:line, confidence, why it matters, and a specific fix.
+4. **Proposed `code_refs`** — computed, not recalled: run
+   `node "${PROJECTSTORE_CORE_ROOT}/scripts/diff-refs.mjs" --since <story started_at>`
+   (story-scoped range; the script filters lockfiles/generated). When the
+   result looks implausible (`fallback: true`, empty, or obviously
+   over/under-attributed — shared branch, direct-to-main), say so and ask for
+   an explicit `--range` instead of guessing. State whether the parent epic's
+   footprint needs widening — the write happens in the approval-gated
+   `$projectstore-codemap set`, never here.
+5. **Open Questions** — low-confidence findings, surfaced not blocking.
+6. **Good** — genuine strengths, one line each. Skip if none.
+
+No sycophancy, no rubber-stamping, no severity inflation. Read-only: report as
+text; never edit vault files, never stage or commit.

package/skills/projectstore-runbook/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: projectstore-runbook
+description: "Create a new ops runbook (step-by-step how-to with verification & rollback). Arguments: <title>."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are creating an ops runbook.
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${PROJECTSTORE_CORE_ROOT}/scripts/draft.mjs" runbook "<user-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. the harness's user-input mechanism: Yes / Edit / No. This is the only gate: **Yes** covers the artifact and its index row. Disclose in the question that the folder's whole managed index table is regenerated from vault state at write time, so the update may also repair a stale row for another artifact.
+5. Pre-write race check (Layer 1): `test -e "<path>"`. If exists, ask: **Overwrite**, **Use new slug** (`-2`), or **Cancel**.
+6. On Yes (path free or overwrite confirmed): Write file.
+7. Index row, if `index` is non-null — apply through the core, never Write/Edit, no second gate (step 4 covers it): `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>` (runbooks live in `ops/` — always take the folder from the draft JSON, never from the kind name). The row is derived state: canonical order, atomic write, manual prose preserved. The file is already on disk, so a nonzero exit is a warning naming the folder (stderr with no JSON = rejected before any write, fix the header or restore the README; `error` in JSON = I/O failure, suggest `$projectstore-reconcile`), never a failed creation.
+8. Suggest: "Fill `Purpose`, `Prerequisites`, numbered `Steps` with shell snippets, and always include `Verification` and `Rollback`."

package/skills/projectstore-scaffold/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: projectstore-scaffold
+description: "Scaffold the bound vault with the layout's folder structure and README index files. Arguments: [layout-name]."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are creating the folder structure of the projectstore layout inside the bound vault.
+
+Steps:
+
+1. **Read config**: `cat .projectstore/projectstore.json`. If missing, tell user to run `$projectstore-bind <path>` and stop.
+2. **Determine layout**: use `<user-arguments>` if provided, else `config.layout`.
+3. **Load layout spec**: `cat "${PROJECTSTORE_CORE_ROOT}/scaffold/layouts/<layout>.json"`. Parse it.
+4. **Show plan**: list every folder that will be created and which folders already exist. Mark new ones with `(create)`, existing with `(exists)`.
+5. **Ask approval** via the harness's user-input mechanism: "Create the missing folders and READMEs? [Yes / Skip READMEs / No]".
+6. **Execute**:
+   - For each folder in `layout.folders`:
+     - Create directory via `mkdir -p <vault>/<folder.path>`.
+     - If `folder.readme === true` and `<vault>/<folder.path>/README.md` does not exist:
+       - Read template: `cat "${PROJECTSTORE_CORE_ROOT}/templates/<lang>/folder-readme.md.tmpl"`.
+       - Substitute `{{folder_name}}` and `{{folder_description}}` based on the folder kind.
+       - Write the README via file-writing tool.
+   - Also create a top-level `<vault>/README.md` if missing — a simple index pointing to each folder.
+7. **Print result**: tree of newly created files and a one-line "next step" suggestion.

package/skills/projectstore-search/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: projectstore-search
+description: "Search the bound vault for a phrase — literal, bounded, grouped by folder. Arguments: <query> [--kind <type>] [--status <status>] [--limit <n>] [--case-sensitive] [--include-derived]."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are searching the vault for the user's query through the core's `search` verb (roadmap A8: the command is a thin front-end; the deterministic search lives in `scripts/query.mjs` and answers identically over MCP).
+
+Steps:
+
+1. Run the verb. The query is a positional and travels **behind `--`**, so a phrase that starts with `-` (a flag name, say) is searched for rather than parsed; the options, if the user gave any, go before it:
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" search [--kind <type>] [--status <status>] [--limit <n>] [--case-sensitive] [--include-derived] -- "<query>"
+   ```
+
+   The project resolves from the session's project directory; do not pass `--project`. Exit 3 means the project is unbound — say so and point at `$projectstore-bind <vault-path>`; exit 2 is a usage error — relay its message.
+
+2. Print the output verbatim. It is already grouped by the vault's top-level folder with a count per group and `path:line  snippet` lines; the header says how many matches there are, whether the list was cut (`--limit`, default 20, cap 100) and whether a file hit the per-file cap (`[N in file]`). The search is literal substring, case-insensitive unless `--case-sensitive`, over artifact bodies and `title:` lines; the derived views (the board, `code-map.md`, `graph.md`) are excluded unless `--include-derived`.
+
+3. Zero matches is exit 0 and the output already suggests a shorter or case-insensitive phrase. Do not fall back to a shell `grep`: the verb is the search.
+
+4. At the end, print a hint: "Open a file with the file-reading tool: `Read <vault_path>/<path>`" — `vault_path` is in `.projectstore/projectstore.json` (or `status --json` → `result.vault_path`); the search output prints vault-relative paths.