projectstore-codex 0.0.1 → 0.28.1

package/skills/projectstore-spec/SKILL.md

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

package/skills/projectstore-status/SKILL.md

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

package/skills/projectstore-statusline/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: projectstore-statusline
+description: "Explain ProjectStore status-line availability for Codex. This surface is unsupported and the skill never writes configuration. Arguments: on | off | status."
+---
+
+## 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.
+
+ProjectStore's status-line surface is not supported by the Codex
+harness. Do not run install or uninstall for `--surface statusline`, and do
+not edit project or host configuration. Report the surface as unsupported.
+For project state use `$projectstore-status`; for a compact live view use the
+Codex application's own task and terminal UI.

package/skills/projectstore-story/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: projectstore-story
+description: "Create a new story inside an existing epic, or run its lifecycle gates (plan / close). Arguments: <epic-id> <title> [--spec SPEC-ID] | plan <story> | close <story>."
+---
+
+## 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 managing a story: creating one, or running its lifecycle gates.
+
+**Dispatch rule** (positional-1 contract, PS-SPEC story-007): if the first
+argument is `plan` or `close` AND the second argument resolves to an existing
+story file (path, or `<epic-id>/<story-id>` searched under
+`<vault>/epics/*/stories/`), run the **Lifecycle gate flow** below. Otherwise
+this is a **create** (first argument = epic id — uppercase by convention, so
+the two cannot collide).
+
+# Create flow
+
+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.
+
+3. **Render draft**:
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/scripts/draft.mjs" story "<user-arguments>"
+   ```
+
+   The script fails if the epic folder does not exist. Surface the error and suggest `$projectstore-epic <id> "<title>"` first.
+
+4. **Preview**: path + first ~25 lines.
+
+5. **Approval** via the harness's user-input mechanism: Yes / Edit / No.
+
+   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 "<user-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.
+
+7. **On Yes** (path free): Write file.
+
+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>`."
+
+# Lifecycle gate flow (plan / close)
+
+1. **Resolve the story file** (second argument). Ambiguous → list candidates and ask.
+
+2. **Run the compute script** (pure — writes nothing):
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/scripts/story-section.mjs" <plan|close> "<story-path>"
+   ```
+
+   It returns `{ path, changed, notes, content }`: section inserted when
+   absent, status transition, lifecycle timestamps (`started_at` /
+   `plan_updated_at` / `closed_at` — stamped unconditionally; the
+   `lifecycle_gates` key gates checks, never data).
+
+3. **Fill the section content** in the returned `content` before preview:
+   - `plan` — write the Implementation Plan. When the story's `specs:` names a
+     covering spec, the plan is a THIN ROUTE through that spec's behavioral
+     contracts: which contracts, in what order, which files. Consult the
+     planner agent's output if one ran. Do not restate the spec.
+   - `close` — write the Final Summary (what changed / why / tests executed /
+     risks & follow-ups), and update the Acceptance Criteria checkboxes with
+     evidence suffixes: `- [x] <criterion> — evidence: <test | command | file:line>`.
+     Check a box ONLY with real evidence (reviewer output, test run, command).
+
+4. **Preview** path + notes + the changed sections. **Approval** via
+   the harness's user-input mechanism: Yes / Edit / No.
+
+5. **Immediately before writing**, re-run the script and verify its `content`
+   (before your section edits) still matches what you previewed against — a
+   human may have edited the file in Obsidian meanwhile. On divergence:
+   re-preview, re-ask.
+
+5a. **Delegate the ceremony — enumerated case: story close** (ADR "Artifact
+   content is authored by the context-holder, the write ceremony by a clerk").
+   After the approval in step 4 and the re-check in step 5, on a `close`:
+   - Write TWO files to the session scratchpad: the **scratch** (the full final
+     content you previewed — sections filled) and the **baseline** (the script's
+     raw `content` from step 2, BEFORE your section edits). They are different
+     files with different jobs: the scratch is what gets copied to the target;
+     the baseline is what `--check` compares against. Handing `--check` the
+     scratch makes it report drift on every run.
+   - **Model (ADR-008)**: resolve it 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.
+   - Capture doctor's summary line (`node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" doctor
+     --vault`, last line) — the clerk needs it as the **pre-state**: it must not
+     stop on findings that were already there and are not its own.
+   - Spawn `projectstore:clerk` **as a foreground task** (you need its report to
+     continue) with: the scratch path, the target path, the exact re-check
+     invocation (`story-section.mjs close "<story-path>" --check
+     <baseline-path>`), the derived targets (`kanban`, plus `indexes=<epic
+     folder>` when status changed), and the doctor pre-state line. On a clean
+     report (`verbatim: true`, `stopped_at: null`, doctor no worse than the
+     pre-state) skip steps 6-6b — the clerk's report is the write evidence. On a
+     stopped report: fix what diverged, then re-delegate (the resume rule: after
+     the copy, the ceremony restarts at reconcile, not at the race gate) or
+     finish the remaining steps yourself (the copy is idempotent).
+   - No clerk available → perform steps 6-6b yourself. There is no fallback
+     agent: a general-purpose writer is an unpinned procedure.
+
+6. **On Yes** (undelegated path): Write the full file. On a `plan`, finish by
+   suggesting `$projectstore-kanban` (the status changed) — 6a/6b below are the
+   close's ceremony, not the plan's.
+
+6a. **(close only) Reconcile** the touched derived targets through the core:
+   `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only kanban` (add
+   `indexes=<epic folder>` when the status changed).
+
+6b. **(close only) Verify**: `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" doctor --vault` (exit 1 = findings, not failure)
+   — a close is not done while doctor got worse. Then suggest the reviewer's
+   proposed `code_refs` via `$projectstore-codemap set` (the reviewer computes it
+   from `scripts/diff-refs.mjs --since <started_at>`).

package/skills/projectstore-story-completion/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: projectstore-story-completion
+description: "When the user finishes work that maps to a known story (story file exists in epics/<id>/stories/) — all acceptance criteria appear satisfied, code merged, tests passing — suggest updating the story's frontmatter status (e.g. planned → in-progress → review → done) and regenerating the kanban. Never write to vault directly without $projectstore-* commands and explicit approval."
+---
+
+## 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.
+
+# Story completion / status update suggester
+
+You watch for moments where the conversation indicates progress on a known story:
+
+- A merge/PR was completed for work tied to a story.
+- The user said "story-001 is done" or similar.
+- All checkboxes in a story's `Decomposition` or `Acceptance Criteria` got ticked.
+- The user moved between phases of an epic (e.g., "moving to integration testing now").
+
+## What to do
+
+1. **Confirm a vault is bound** (`.projectstore/projectstore.json` exists). Otherwise stay silent.
+2. **Confirm `active_skills` is true** in config.
+3. **Try to identify the story file**: search `<vault>/epics/*/stories/` for files matching keywords from the conversation. If multiple candidates, ask the user which one via plain text (not the harness's user-input mechanism — keep it light).
+4. **Propose the right transition**:
+   - Work about to **start** on a story → suggest `$projectstore-story plan <story>`
+     (writes the Implementation Plan, stamps `started_at`, moves to in-progress).
+   - Story looks **finished** → suggest `$projectstore-story close <story>`
+     (Final Summary, evidence suffixes on acceptance criteria, stamps
+     `closed_at`, moves to done) — and, before closing, the `reviewer` agent,
+     whose proposed `code_refs` come from `scripts/diff-refs.mjs` anchored at
+     the story's `started_at`.
+   - Intermediate move (e.g. → review) → propose the frontmatter status Edit
+     as before:
+
+   > 📋 *Looks like `epics/RECPLAT-333/stories/story-007-feature-pipeline.md` is moving to `review`. Want me to update its frontmatter and refresh the kanban?*
+
+5. **Do not modify the file** until the user says yes. When they confirm a
+   plain status move:
+   - Read the story file.
+   - Propose an Edit that changes `status:` and `updated:` in the frontmatter
+     (plus `started_at` when first entering in-progress outside the plan gate,
+     `closed_at` when moving to done outside the close gate — timestamps must
+     not be lost just because the gate was skipped; ISO-8601).
+   - Use the harness's user-input mechanism to confirm the Edit before applying.
+   - After Edit, suggest running `$projectstore-kanban` to refresh the board.
+
+## Anti-patterns
+
+- Don't pick a story automatically — always ask if uncertain.
+- Don't bulk-update multiple stories in one go without per-file approval.
+- Don't change anything beyond `status`, `updated` and the lifecycle
+  timestamps (`started_at` / `closed_at`). Section content (plan, summary,
+  evidence) belongs to the `$projectstore-story plan|close` gates.
+- Don't trigger after every code change — only on clear completion signals.

package/skills/projectstore-vault-communication/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: projectstore-vault-communication
+description: "When communicating with the user about anything stored in the projectstore vault (epics, stories, ADRs, research, kanban, backlog), reference every artifact by its human title from frontmatter — never by session-invented shorthand. Name the parent epic for stories; include status/priority when discussing state or plans. Applies by default in bound projects to summaries, plans, and progress reports."
+---
+
+## 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.
+
+# Vault-native communication
+
+Vault artifacts are the shared vocabulary between the user, this session, *other*
+sessions, and the post-compact agent. A title written in a file can be grepped,
+linked, and recognized in Obsidian six months from now. A label invented mid-session
+("T3", "P0-1", "the doctor story") dies with the session that coined it — and forces
+the user to cross-reference your earlier messages just to know what you meant.
+
+## Rules
+
+### 1. Call artifacts by their `title:`, not by number or slug
+
+```
+bad:  story-004 is done, story-005 is next
+good: "Unicode-aware slugify to unbreak ru filenames" (story-004) is done;
+      "YAML-escape template variables" (story-005) is next
+```
+
+The id in parentheses is welcome — as a *supplement*, never the only handle.
+
+### 2. Stories always carry their epic
+
+First mention in a message names both; after that a short form is fine.
+
+```
+bad:  let's start with story-001
+good: let's start with "doctor: deterministic consistency lint" (PS-IMPROVE › story-001)
+then: doctor lint story (story-001)
+```
+
+### 3. Resolution order for the name
+
+`title:` from frontmatter → filename without extension → relative path.
+Never a bare number ("story 3", "the second ADR").
+
+### 4. Plans and progress carry status (and priority when it matters)
+
+```
+bad:  the epic is moving along
+good: epic "Reliability by construction" (PS-IMPROVE, p0): 2 of 6 stories done,
+      "reconcile: re-derive kanban and indexes from frontmatter" is in-progress
+```
+
+### 5. Document-internal codes stay inside their document
+
+If a note defines its own legend (e.g. topics T1–T6 in a research note), those codes
+are fine *within that document*. In chat, expand them on first use in every message:
+
+```
+bad:  I suggest T3+T4 first, then T2/T6, T5, T1
+good: I suggest starting with the agent-roster topics — "which new roles fit" and
+      "rename projectstore-critic → critic" (topics 3–4 in research "v0.13 Design
+      Questions: Statusline, Agents, Doctor, Model Config") — their naming decisions
+      leak into every other ADR's wording
+```
+
+### 6. Link the file when the user may want to open it
+
+`epics/PS-IMPROVE/stories/story-001-doctor-deterministic-consistency-lint.md` —
+paths are clickable in the terminal and resolvable in Obsidian. Title first,
+path as the pointer.
+
+## When this applies
+
+- Any user-facing message *about vault contents*: status summaries, "what's next",
+  planning discussions, review results, kanban talk, backlog updates.
+- Artifacts you write into the vault: related-links and prose references use titles
+  and wiki-links, not invented codes.
+
+## When it does NOT apply
+
+- Short confirmations ("done", "committing now") with no artifact references.
+- Raw command output, code blocks, file paths inside tool calls.
+- Frontmatter ids themselves (`id: story-001` stays an id — that's its job).
+
+## Anti-patterns
+
+- ❌ "T3+T4 first, then T2/T6" — bare document-internal codes leaked into chat.
+- ❌ "P0-1 through P0-6 are specced" — priority labels used as names.
+- ❌ "the doctor story" when two doctor-shaped items exist (install diagnostics vs
+  vault consistency lint) — ambiguity is exactly what titles prevent.
+- ❌ Renaming an artifact in conversation ("the reliability epic" for an epic titled
+  "Reliability by construction" is fine as a gloss — but don't *invent* a different
+  working title and keep using it).
+
+## Activation
+
+Default-on when a vault is bound (`.projectstore/projectstore.json` exists) and
+`active_skills` is not `false` — same gating as the other passive skills. Silent
+otherwise. This skill changes *how you phrase things*; it never writes files and
+never blocks an action.