projectstore-claude 0.29.3 → 0.30.0

package/node_modules/projectstore/docs/getting-started.md

@@ -1,5 +1,17 @@
 # Getting started with projectstore
 
+## Install
+
+From a terminal in your project:
+
+```
+npx projectstore setup
+```
+
+Setup finds the coding agents the project uses (Claude Code, Codex or both), asks a few questions — among them where the vault lives — then shows one plan and asks once before it writes. It binds the vault, or creates one when the folder is missing or empty. The README's [Install](../README.md#install) section has the details, the global form and the registry-mirror form.
+
+The next two sections are the other ways in: a checkout, and the git marketplace inside a Claude Code session. After either of them, the first-time setup below binds the vault.
+
 ## Install (local dev)
 
 Until projectstore is published to a public marketplace, install it from a local clone.
@@ -132,6 +144,14 @@ What the language does and does not change: section headings, table labels and p
 
 ## Updating to a new version
 
+Installed with setup or from npm: from a terminal in your project, name the version you want to run:
+
+```
+npx projectstore@<version> upgrade
+```
+
+Installed from the git marketplace, in a Claude Code session:
+
 ```
 /plugin marketplace update SmartAndPoint
 /reload-plugins
@@ -139,4 +159,4 @@ What the language does and does not change: section headings, table labels and p
 
 Or enable auto-update once (`/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update**) and Claude Code will detect new releases at startup.
 
-**After any update, run `/projectstore:doctor`.** It compares your project's wiring against what the new version expects and names each fix with the command to run — stale agents block in `CLAUDE.md` (`/projectstore:agents register`), leftover agent copies that override nothing (`/projectstore:agents configure`), auto-update still off (the exact setting and file), a newer release than the one running. `doctor --fix` applies the install-side repairs interactively; `/projectstore:reconcile` rebuilds the board/indexes/code-map if content drifted. Silence at session start means healthy — the cheap checks run automatically and only speak up when something is wrong.
+**After any update, run `/projectstore:doctor` in a session.** It compares your project's wiring against what the new version expects and names each fix with the command to run: a stale agents block in `CLAUDE.md` gets `/projectstore:agents register` as its fix and leftover agent copies that override nothing get `/projectstore:agents configure` as theirs. It also names auto-update still off (the exact setting and file) and a newer release than the one running. `doctor --fix` applies the install-side repairs interactively; `/projectstore:reconcile` rebuilds the board/indexes/code-map if content drifted. Silence at session start means healthy — the cheap checks run automatically and only speak up when something is wrong.

package/node_modules/projectstore/docs/harnesses.md

@@ -75,24 +75,27 @@ not started from a terminal can miss a `node` that only `.zprofile` puts on
 `PATH`.
 
 The shell is published as `projectstore-codex` from 0.28.1, ahead of that live
-run, by the maintainer's decision:
+run, by the maintainer's decision. Nobody types its name: setup, install and
+upgrade fetch it at their own version and plan Codex from it. From a terminal
+in your project:
 
 ```sh
-npx projectstore-codex install --project "$PWD"
+npx projectstore setup
 ```
 
-For later releases, `npx projectstore-codex@<version> upgrade --project "$PWD"`.
-Installation is user-global because Codex stores marketplace registrations and
-plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
-project-local. Ordinary uninstall leaves the global plugin in place; add
-`--global` only when you mean to remove it for every project. From this
-checkout, the same flow runs against a built tarball:
+To upgrade Codex alone, naming the version you want to run:
 
 ```sh
-npm run shells:build -- --only projectstore-codex --dev --out dist
-npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+npx projectstore@<version> upgrade --harness codex
 ```
 
+Installation is user-global because Codex stores marketplace registrations and
+plugin caches in `CODEX_HOME`; the agents block in `AGENTS.md` remains
+project-local. Ordinary uninstall leaves the global plugin in place; add
+`--global` only when you mean to remove it for every project. A checkout's own
+build runs through the same flow: [`packaging/README.md`](../packaging/README.md#running-a-checkouts-build)
+has the tarball loop.
+
 What is known, and how:
 
 - **Hooks load from Codex's default file, so the shell carries no root

package/node_modules/projectstore/docs/how-it-works.md

@@ -67,8 +67,10 @@ sessions can't silently overwrite each other's new artifact.
 
 **The status line is stricter still**: it renders from a *per-session* pointer
 (`<project>/.projectstore/state/sessions/<session_id>.json`, written by the
-PreToolUse hook with denormalized titles) and performs **zero cross-session and
-zero vault reads**. 2–6 parallel sessions each see exactly their own epic/story;
+tool hooks with denormalized titles — after a write, from the file as written —
+by `story close` through the core, and refreshed at session start) and performs
+**zero cross-session and zero vault reads**. A story that is done, closed or
+parked leaves the line: it shows the epic alone, as the band does. 2–6 parallel sessions each see exactly their own epic/story;
 a fresh session gets a localized "no epic or story in this session yet" line; a
 corrupt pointer shows an error marker, never a false "no work". The renderer also
 drops a `.last-render.json` breadcrumb so `doctor` can detect session-id
@@ -162,7 +164,7 @@ resistance. v0.13 makes that safe instead of forbidden:
   (`--write`): each approved target is recomputed from the vault state at
   write time and replaced atomically, so a stale preview is never what lands;
   `--write` is also a sanctioned headless entry point (cron/CI repair job).
-- A throttled PreToolUse **nudge** fires when vault files are edited directly:
+- A throttled PostToolUse **nudge** fires when vault files are edited directly:
   "run reconcile afterwards so the derived views stay in sync" (disable with
   `"guard": "off"` in `projectstore.json`).
 - A once-per-session **entry reminder** fires on PostToolUse when a session has
@@ -189,7 +191,7 @@ resistance. v0.13 makes that safe instead of forbidden:
   sees Bash-mediated writes, which bypass hook path extraction entirely.
 
 The division of labor: deterministic checks catch the mechanical 90% for free;
-the LLM critic (`/projectstore:review`) is saved for the judgment calls.
+the LLM critic that `/projectstore:review` runs is saved for the judgment calls.
 
 ## Naming a session after the work it settled on
 

package/node_modules/projectstore/harnesses/claude-code.json

@@ -11,26 +11,27 @@
     "date": "2026-09-04"
   },
   "install": {
-    "mechanism": "the package's own registration through its distribution shell, or the built-in plugin marketplace",
+    "mechanism": "the package's own registration (setup or install, from npm), or the built-in plugin marketplace",
     "shell": "projectstore-claude",
-    "shell_reason": "the distribution shell that installs this harness from npm (the layout ADR decision 6; the shells ADR): `npx projectstore-claude install --project <dir>` is the core's `install --harness claude-code`, with the core pinned at the same version and bundled inside the shell's tarball. Data, not `projectstore-<id>`: the id is claude-code and the reserved, published name is projectstore-claude. Every command a finding or a deferred reason names is built from this key (harness.mjs packageCommand).",
-    "why_not_scripted": "Two channels. `npx projectstore-claude install --project <dir>` registers the plugin for that project from the npm package itself — the shell bundles the core and fixes the harness; the core's low-level form is `npx projectstore install --harness claude-code --project <dir>` — through a local marketplace under the Claude home, driven by Claude Code's own `claude plugin` CLI. `/plugin install projectstore@SmartAndPoint` installs it from the git marketplace. `/plugin` lists and toggles either. Upgrading the npm registration is `npx projectstore-claude@<version> upgrade --project <dir>` — that is also the pin.",
+    "shell_reason": "the distribution shell of this harness on npm (the layout ADR decision 6; the shells ADR): `projectstore-claude install` is the core's `install --harness claude-code`, with the core pinned at the same version and bundled inside the shell's tarball. Data, not `projectstore-<id>`: the id is claude-code and the reserved, published name is projectstore-claude. Since the front-door ADR the shell is a release artifact: no command a person is told to type names it (packageCommand builds the core's form, `npx projectstore <verb> --harness claude-code`), and this key tells the core which harness a running shell fixes (harness.mjs bundlingShellHarnessId, speakingHarnessId).",
+    "why_not_scripted": "Two channels. The npm package registers the plugin for a project itself — run `npx projectstore setup` or the core's low-level `install --harness claude-code` from a terminal in the project — through a local marketplace under the Claude home, driven by Claude Code's own `claude plugin` CLI. `/plugin install projectstore@SmartAndPoint` installs it from the git marketplace. `/plugin` lists and toggles either. The npm registration is upgraded, and pinned, by `npx projectstore@<version> upgrade` from a terminal in the project.",
     "steps": [
-      "npx projectstore-claude install --project \"$PWD\"   (npm; registers the plugin for this project — the shell runs the core's install with the harness fixed)",
-      "/plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint   (git marketplace, user-wide)",
+      "npm, for this checkout (the core registers the plugin), from a terminal in the project: npx projectstore install --harness claude-code",
+      "git marketplace, user-wide, in a Claude Code session: /plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint",
       "restart Claude Code"
     ],
     "next": [
       "restart Claude Code in this project"
     ],
     "notes": [
-      "Git marketplace only: auto-update is OFF by default for third-party plugins: /plugin -> Marketplaces -> SmartAndPoint -> toggle auto-update. The npm registration updates when you run `npx projectstore-claude upgrade --project <dir>`.",
-      "Pin a git-marketplace release with: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>; pin the npm registration with npx projectstore-claude@<version>.",
+      "Git marketplace only: auto-update is OFF by default for third-party plugins: /plugin -> Marketplaces -> SmartAndPoint -> toggle auto-update. The npm registration updates when you run `npx projectstore@<version> upgrade` from a terminal in the project.",
+      "Pin a git-marketplace release by adding the marketplace at a tag: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>",
+      "The npm registration is pinned by the version its upgrade names: npx projectstore@<version> upgrade",
       "Two enabled copies of the plugin (git marketplace and npm) in one checkout would load twice; the npm registration silences the other one for that checkout only (settings.local.json), and says so in its preview.",
       "From a checkout instead: claude --plugin-dir ./ProjectStore",
       "The npm registration is per checkout (local scope) and per machine; a fresh clone or a new worktree runs the install command again. It must run from a terminal outside a Claude Code session: the host CLI and a live session both rewrite settings files."
     ],
-    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install"
   },
   "runtime": {
     "detect_env": [
@@ -134,16 +135,16 @@
       "system_message": true,
       "decision": "permissionDecision",
       "evidence": "measured",
-      "note": "systemMessage measured — scripts/touch-session.mjs uses it for the pointer nudge and the name offer. additionalContext and permissionDecision (allow|deny|ask) are documented; projectstore never emits them. A separate PermissionRequest event carries its own decision object."
+      "note": "systemMessage measured — scripts/touch-session.mjs used it for the raw-edit nudge and uses it for the name offer (the nudge moved to PostToolUse with the write's pointer patch, ADR-006 amended 2026-10-12). additionalContext and permissionDecision (allow|deny|ask) are documented; projectstore never emits them. A separate PermissionRequest event carries its own decision object."
     },
     "PostToolUse": {
       "fields": [
         "additionalContext"
       ],
-      "system_message": null,
+      "system_message": true,
       "decision": null,
       "evidence": "measured",
-      "note": "scripts/touch-session.mjs — the entry-rule reminder's primary carrier (entry-rule spec, contract 14)."
+      "note": "scripts/touch-session.mjs — the entry-rule reminder's primary carrier (entry-rule spec, contract 14). The measurement covers additionalContext only. systemMessage carries the raw-edit nudge since the pointer patch moved after the write (ADR-006, amended 2026-10-12): documented for every event, not yet observed on this one — the closed-story story's live check records it."
     },
     "PostToolUseFailure": {
       "fields": [
@@ -299,7 +300,7 @@
       "file": ".projectstore/state/claude-code/statusline.mjs",
       "source": "scripts/statusline-launcher.mjs",
       "condition": "plugin_cache_install",
-      "file_reason": "the harness's generated runtime files live under .projectstore/state/<harness id>/ (layout ADR decision 4); the 0.27.x path .claude/.projectstore/statusline.mjs is read as ours through 0.29",
+      "file_reason": "the harness's generated runtime files live under .projectstore/state/<harness id>/ (layout ADR decision 4); the 0.27.x path .claude/.projectstore/statusline.mjs is read as ours through 0.30",
       "legacy_file": ".claude/.projectstore/statusline.mjs"
     },
     "mcp": {
@@ -494,18 +495,18 @@
   "ui_vocabulary_reason": "This harness's UI affordances and tool names: words that mean nothing on another harness. The generator refuses them in another harness's rendered tree, and the runtime vocabulary lint refuses them in what the core prints for another harness (generation spec, contracts 6 and 18). A word here must be followed by a non-word character to count, so `/plugins/` in a path is not `/plugin`.",
   "update_hint": {
     "line": "See /plugin → Marketplaces to enable auto-update.",
-    "welcome": ["**About future updates**: Claude Code does NOT auto-update third-party marketplaces by default. To get notified of new releases (v0.7+):", "1. Open `/plugin` → **Marketplaces** tab.", "2. Find **SmartAndPoint**.", "3. Toggle **auto-update** on.", "", "Without it, you'd run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#updates for details."],
+    "welcome": ["**About future updates**: Claude Code does NOT auto-update third-party marketplaces by default. To get notified of new releases (v0.7+):", "1. Open `/plugin` → **Marketplaces** tab.", "2. Find **SmartAndPoint**.", "3. Toggle **auto-update** on.", "", "Without it, you'd run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details."],
     "reason": "What the first-run welcome and its one-line notice say about updates (generation spec, contract 18): `line` ends the notice, `welcome` is the welcome's update block. update_instructions is the long-form guidance; this is the part a session prints, kept here so no hook names a harness's update path."
   },
   "update_instructions": [
-    "**About future updates**: installed from the git marketplace, Claude Code does NOT auto-update third-party marketplaces by default (an npm registration updates with `npx projectstore-claude upgrade --project <dir>`). To get notified of new releases (v0.7+):",
+    "**About future updates**: installed from the git marketplace, Claude Code does NOT auto-update third-party marketplaces by default; an npm registration updates with `npx projectstore@<version> upgrade` from a terminal in the project. To get notified of new git-marketplace releases (v0.7+):",
     "1. Open `/plugin` → **Marketplaces** tab.",
     "2. Find **SmartAndPoint**.",
     "3. Toggle **auto-update** on.",
     "",
     "Without it, you would run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details.",
     "",
-    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal outside the session: for a git-marketplace install, the installed copy's own `bin/projectstore.mjs upgrade --harness claude-code --no-register --project <dir>`, which leaves the registration as it is; for the npm registration, `npx projectstore-claude@<version> upgrade --no-register --project <dir>`. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the shell form without `--no-register` (`npx projectstore-claude@<version> upgrade`), which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
+    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal in the project, outside the session. For a git-marketplace install it is the installed copy's own `bin/projectstore.mjs` with `upgrade --harness claude-code --no-register`, which leaves the registration as it is. For the npm registration it is `npx projectstore@<version> upgrade --harness claude-code --no-register` and nothing else. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the form without `--no-register`, which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
   ],
   "agent_translation": {
     "carries_model": true,

package/node_modules/projectstore/harnesses/codex.json

@@ -311,33 +311,32 @@
   },
   "rewrites": [],
   "install": {
-    "mechanism": "the package's portable plugin root, registered through its distribution shell and Codex's own marketplace CLI",
+    "mechanism": "the package's portable plugin root, fetched in its distribution shell and registered through Codex's own marketplace CLI",
     "shell": "projectstore-codex",
     "shell_reason": "The built `projectstore-codex` shell carries the rendered Codex skills and hooks plus an exact bundled core, fixes --harness codex, stages a stable marketplace under CODEX_HOME, and asks Codex itself to install it. It is published from 0.28.1, by the maintainer's decision of 2026-10-04. Until then this key was absent, so generated guidance could not send users to the reserved 0.0.1 placeholder; the core alone is not Codex's plugin root and cannot register it.",
-    "why_not_scripted": "The shell does not edit Codex's registry or cache. It atomically stages the plugin source, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
+    "why_not_scripted": "The installer does not edit Codex's registry or cache. It atomically stages the plugin source from the shell it fetched, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
     "steps": [
-      "npx projectstore-codex install --project \"$PWD\"",
+      "from a terminal in the project (the core fetches the Codex shell at its own version): npx projectstore install --harness codex",
       "restart Codex and approve the ProjectStore hooks when prompted",
-      "run `$projectstore-bind <vault-path>` in Codex"
+      "in Codex, bind a vault: $projectstore-bind <vault-path>"
     ],
     "next": [
-      "restart Codex from a terminal and approve the ProjectStore hooks when it asks",
-      "in an unbound project, run `$projectstore-bind <vault-path>` in Codex"
+      "restart Codex from a terminal and approve the ProjectStore hooks when it asks"
     ],
     "notes": [
       "The installation is user-global because Codex's marketplace, plugin row and cache live in CODEX_HOME; the AGENTS.md block is project-local.",
-      "Upgrade with `npx projectstore-codex@<version> upgrade --project \"$PWD\"`; the named package version is also the plugin version.",
+      "Upgrade with `npx projectstore@<version> upgrade --harness codex` from a terminal in the project; the version it names is also the plugin version.",
       "A second enabled ProjectStore plugin from another marketplace is a refusal, not silently disabled globally. Remove or disable that older registration explicitly, then retry.",
-      "Ordinary uninstall removes only project-owned surfaces. `npx projectstore-codex uninstall --global --project \"$PWD\"` also removes the user-global plugin registration after a preview."
+      "Ordinary uninstall removes only project-owned surfaces. `npx projectstore uninstall --harness codex --global` also removes the user-global plugin registration after a preview."
     ],
-    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install"
   },
   "update_hint": {
-    "line": "Update with `{upgrade}`.",
-    "welcome": ["**About future updates**: run `{upgrade}` from a terminal, then restart Codex and approve any hook it asks about.", "", "See https://github.com/SmartAndPoint/ProjectStore#updates for details."],
-    "reason": "What the first-run welcome and its one-line notice say about updates (generation spec, contract 18): `line` ends the notice, `welcome` is the welcome's update block, and `{upgrade}` is filled with this harness's shell command at latest, so what is printed runs as printed. update_instructions is the long-form guidance; this is the part a session prints, kept here so no hook names a harness's update path."
+    "line": "Update from a terminal in this project:\n{upgrade}",
+    "welcome": ["**About future updates**: from a terminal in this project, run:", "", "```", "{upgrade}", "```", "", "Then restart Codex and approve any hook it asks about. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details."],
+    "reason": "What the first-run welcome and its one-line notice say about updates (generation spec, contract 18): `line` ends the notice, `welcome` is the welcome's update block, and `{upgrade}` is filled with the core's upgrade for this harness at latest (`--harness codex`, no `--project`), so what is printed runs as printed. Each says where to run it and puts the command alone on its line (the story \"User-facing text says where to run and names no project path and no shell\", rules 4 and 5). update_instructions is the long-form guidance; this is the part a session prints, kept here so no hook names a harness's update path."
   },
-  "update_instructions": "Run `npx projectstore-codex@<version> upgrade --project <dir>`. The installer atomically replaces its stable source and `codex plugin add projectstore@projectstore-npx` materialises the new version; this was measured across two dev builds on codex-cli 0.153.4. Restart Codex afterwards so the new skills and hooks are loaded.",
+  "update_instructions": "From a terminal in the project, run `npx projectstore@<version> upgrade --harness codex` and restart Codex afterwards, so the new skills and hooks are loaded. The run fetches the shell at that version, atomically replaces its stable source, and `codex plugin add projectstore@projectstore-npx` materialises the new version; this was measured across two dev builds on codex-cli 0.153.4.",
   "agent_translation": {
     "carries_model": false,
     "carries_model_reason": "The surface projectstore ships — a plugin's agents/ entry — carries no model on Codex: surfaces.agents is supported:false because no route from a plugin's agents/ directory to collaborationspawn_agent has been found (measured). Codex DOES have a definition file that carries model and effort, recorded below, but it is project- or user-scoped and not plugin-shippable, so contract 12 holds as written: what we ship cannot carry a model. Was true here until 2026-09-08, which contradicted both contract 12 and this file's own agents row.",

package/node_modules/projectstore/hooks/band.tsx

@@ -40,6 +40,9 @@ import {
   segments,
   stepOf,
   storyFiles,
+  storyIsCurrent,
+  storyKeyOf,
+  storyLayout,
   subjectLabel,
   subjectPath,
   totalOf,
@@ -80,6 +83,9 @@ const steps = atom({ plugin: 'projectstore', key: 'steps' } as const, {} as Reco
 
 type Json = Record<string, any>
 type Rendered = 'drew' | 'survey' | 'nothing' | 'unknown'
+// One story file as the scan read it: its key (storyKeyOf), title and status.
+type StoryItem = { key: string; title: string | null; status: string | null }
+type Stories = { counts: BandCounts; items: StoryItem[] }
 
 // What one load of the module remembers between events.
 type Band = {
@@ -90,7 +96,7 @@ type Band = {
   gen: number
   scan: { gen: number; startedAt: number } | null
   shownKey: string
-  stories: Map<string, { sig: string; counts: BandCounts }>
+  stories: Map<string, { sig: string } & Stories>
   shipped: Map<string, Json>
   place: { vault: string | null; kinds: string[] }
 }
@@ -180,10 +186,11 @@ async function layoutOf($: EngineInterface, b: Band, name: string) {
 
 // ── The scan (contracts 2, 4–9, 14) ───────────────────────────────────
 
-// The epic's stories by stage, re-read only when a listing changed. A story
-// that cannot be read keeps the last good counts (none yet: no progress row),
-// never a partial fold — the band draws less, never wrong.
-async function countsOf($: EngineInterface, b: Band, epicDir: string): Promise<BandCounts | null> {
+// The epic's stories by stage, and each one's key, title and status (the
+// story row's, contract 8), re-read only when a listing changed. A story that
+// cannot be read keeps the last good result (none yet: no progress row and no
+// story row), never a partial fold — the band draws less, never wrong.
+async function storiesOf($: EngineInterface, b: Band, epicDir: string): Promise<Stories | null> {
   const seen: string[] = []
   const fs = {
     list: async (dir: string) => {
@@ -213,18 +220,38 @@ async function countsOf($: EngineInterface, b: Band, epicDir: string): Promise<B
   const files: string[] = await storyFiles(fs, epicDir)
   const sig = seen.sort().join('|')
   const hit = b.stories.get(epicDir)
-  if (hit && hit.sig === sig) return hit.counts
+  if (hit && hit.sig === sig) return hit
   const statuses: unknown[] = []
+  const items: StoryItem[] = []
   for (const f of files) {
     const text = await readText($, f)
-    // An unreadable story (an evicted iCloud file): the last good counts, and
+    // An unreadable story (an evicted iCloud file): the last good result, and
     // nothing cached, so the next scan tries again.
-    if (text === null) return hit?.counts ?? null
-    statuses.push((parseFrontmatter(text).data as Json).status)
+    if (text === null) return hit ?? null
+    const data = parseFrontmatter(text).data as Json
+    statuses.push(data.status)
+    const key = storyKeyOf(f.slice(epicDir.length + 1))
+    if (key) {
+      items.push({
+        key,
+        title: typeof data.title === 'string' && data.title ? data.title : null,
+        status: data.status === null || data.status === undefined || data.status === '' ? null : String(data.status),
+      })
+    }
   }
-  const counts = foldStages(statuses) as BandCounts
-  b.stories.set(epicDir, { sig, counts })
-  return counts
+  const next = { sig, counts: foldStages(statuses) as BandCounts, items }
+  b.stories.set(epicDir, next)
+  return next
+}
+
+// This session's story, from its file (contract 8): the item the pointer's
+// key names, while it is work the session is moving. Never the pointer's own
+// title or status — the pointer can be older than the file.
+function storyOf(pointer: Json | null, stories: Stories | null) {
+  const key = pointer && typeof pointer.active_story === 'string' ? (pointer.active_story as string) : null
+  const item = key && stories ? stories.items.find(i => i.key === key) : null
+  if (!item || !storyIsCurrent(item.status)) return null
+  return { title: item.title || item.key, status: item.status }
 }
 
 async function scan($: EngineInterface, b: Band, root: string, sid: string | null): Promise<BandView | null> {
@@ -258,16 +285,14 @@ async function scan($: EngineInterface, b: Band, root: string, sid: string | nul
   if (text === null) return null
   const fm = parseFrontmatter(text).data as Json
   const registry = await shippedJson($, b, 'scaffold/headings.json')
-  const story = focus.why === 'this' && pointer && typeof pointer.story_title === 'string' && pointer.story_title
-    ? { title: pointer.story_title as string, status: typeof pointer.story_status === 'string' ? (pointer.story_status as string) : null }
-    : null
+  const stories = await storiesOf($, b, epicDir)
   return {
     id: typeof fm.id === 'string' && fm.id ? fm.id : focus.id,
     title: typeof fm.title === 'string' && fm.title ? fm.title : focus.id,
     goal: goalOf(text, goalForms(registry, lang)),
-    counts: await countsOf($, b, epicDir),
+    counts: stories ? stories.counts : null,
     why: focus.why,
-    story,
+    story: focus.why === 'this' ? storyOf(pointer as Json | null, stories) : null,
     version: binding.statusline?.show_version === false ? null : await versionOf($, b),
     hint: band.hint_seen !== true,
     words,
@@ -466,11 +491,14 @@ export const register: Register = on => {
         }
       }
 
-      const story = rows.includes('story') && v.story ? (
+      // The title is cut here so the status is never the part the host's
+      // truncation takes (contract 8); truncate-end stays as a backstop.
+      const sl = v.story ? storyLayout(w.band_story, v.story.title, v.story.status, e.props.bodyColumns) : null
+      const story = rows.includes('story') && sl ? (
         <Text wrap="truncate-end">
           <Text dimColor>   {w.band_story} </Text>
-          <Text color="cyan">{v.story.title}</Text>
-          <Text dimColor>{v.story.status ? ` · ${v.story.status.replace(/[_-]/g, ' ')}` : ''}</Text>
+          <Text color="cyan">{sl.title}</Text>
+          <Text dimColor>{sl.tail}</Text>
         </Text>
       ) : null
 

package/node_modules/projectstore/hooks/pre-compact.mjs

@@ -57,10 +57,7 @@ async function readActivityBudgeted(vault, sid, budgetMs) {
   const deadline = new Promise((resolve) => {
     timer = setTimeout(() => resolve(null), budgetMs);
   });
-  const out = await Promise.race([
-    readActivityAsync(vault, sid).catch(() => []),
-    deadline,
-  ]);
+  const out = await Promise.race([readActivityAsync(vault, sid).catch(() => []), deadline]);
   clearTimeout(timer);
   return out;
 }
@@ -85,9 +82,7 @@ async function main() {
   try {
     layout = loadLayout(cfg.layout);
   } catch {}
-  const artifact = activity && layout
-    ? resolveInFlightArtifact(activity, layout, cfg.vault_path)
-    : null;
+  const artifact = activity && layout ? resolveInFlightArtifact(activity, layout, cfg.vault_path) : null;
 
   const parts = [`vault ${basename(cfg.vault_path)}`];
   // Dropped rather than rendered empty when nothing resolves.
@@ -105,9 +100,11 @@ async function main() {
     // Recent files are a separate referent with a separate condition: an empty
     // log renders no continuity section, so the stronger wording would be false
     // on a path the activity log's last-tool-wins dedupe makes ordinary.
-    parts.push(activity && activity.length > 0
-      ? "orientation and this session's recent files return at session start"
-      : "orientation returns at session start");
+    parts.push(
+      activity && activity.length > 0
+        ? "orientation and this session's recent files return at session start"
+        : "orientation returns at session start",
+    );
   } else {
     // True on every path: plugin commands are installation-scoped and not
     // gated by auto_inject.

package/node_modules/projectstore/hooks/session-rules.mjs

@@ -25,11 +25,13 @@ import { readConfig, readStdinJson, adoptHookInput, roleForm, sharedRoleForm } f
 // told once that both name one role — otherwise the second rule below would
 // have it report the block as a contradiction every session.
 function rules() {
-  const critic = roleForm("critic"), reviewer = roleForm("reviewer");
+  const critic = roleForm("critic"),
+    reviewer = roleForm("reviewer");
   const shared = sharedRoleForm("critic");
-  const bridge = shared === critic
-    ? ""
-    : `\n\nThe \`AGENTS.md\` block may name roles as \`${shared}\`; that is the same role, called \`${critic}\` here.`;
+  const bridge =
+    shared === critic
+      ? ""
+      : `\n\nThe \`AGENTS.md\` block may name roles as \`${shared}\`; that is the same role, called \`${critic}\` here.`;
   return `# projectstore — standing rules for this session
 
 **Artifact-first order.** A feature-sized request opens a vault artifact before
@@ -46,9 +48,11 @@ contradiction becomes invisible to the person who could have settled it.${bridge
 }
 
 function emit(additionalContext) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
-  }) + "\n");
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+    }) + "\n",
+  );
 }
 
 function main() {
@@ -70,6 +74,8 @@ function main() {
   emit(rules());
 }
 
-try { main(); } catch {
+try {
+  main();
+} catch {
   // A hook must never break session startup.
 }

package/node_modules/projectstore/hooks/session-start.mjs

@@ -13,7 +13,7 @@
 //    open. Bounded and O(1) in vault size by construction.
 
 import { existsSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname } from "node:path";
 import {
   readConfig,
   gatherVaultFacts,
@@ -30,6 +30,7 @@ import {
   ensureStateRoot,
   syncStatusLine,
   cleanupStaleSessionState,
+  refreshStoryPointer,
   armReminder,
   truncEnd,
   truncFront,
@@ -64,9 +65,10 @@ function welcomedMarkerWritePath(proj) {
 // the one instruction it carries branches on the binding; everything else is
 // the same message.
 function buildWelcome(cfg = null) {
-  const start = cfg && cfg.vault_path
-    ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation, and you approve every write. If the vault has no folders yet, \`${commandForm("scaffold")}\` lays them out.`
-    : `**To start using it**: run \`${commandForm("bind", { args: "<vault-path>" })}\` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation; you only approve the writes.`;
+  const start =
+    cfg && cfg.vault_path
+      ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation, and you approve every write. If the vault has no folders yet, \`${commandForm("scaffold")}\` lays them out.`
+      : `**To start using it**: run \`${commandForm("bind", { args: "<vault-path>" })}\` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation; you only approve the writes.`;
   return [
     "# 👋 projectstore is loaded for the first time in this project",
     "",
@@ -178,15 +180,25 @@ async function main() {
   // an unbound one that is not a worktree pays a single ~10 ms probe.
   let binding = null;
   if (!cfg) {
-    try { binding = resolveBinding(proj); } catch {}
+    try {
+      binding = resolveBinding(proj);
+    } catch {}
   }
   const welcome = showWelcomeOnce(proj, cfg);
   // The person's channel carries one instruction, and it has to be the right
-  // one: a bound project is told what it is bound to, not to bind again.
+  // one: a bound project is told what it is bound to, not to bind again. A
+  // command stands alone on its line, the update hint on lines of its own
+  // after it (the story "User-facing text says where to run…", rules 4 and 5).
   const welcomeSystemMessage = welcome
-    ? (cfg && cfg.vault_path
+    ? cfg && cfg.vault_path
       ? `👋 projectstore: first-run welcome shown. Bound to ${cfg.vault_path}. ${updateHint().line}`
-      : `👋 projectstore: first-run welcome shown. Start with ${commandForm("bind", { args: "<vault-path>" })}. ${updateHint().line}`)
+      : [
+          "👋 projectstore: first-run welcome shown. Start with:",
+          commandForm("bind", { args: "<vault-path>" }),
+          updateHint().line,
+        ]
+          .filter(Boolean)
+          .join("\n")
     : null;
 
   if (!cfg) {
@@ -196,8 +208,10 @@ async function main() {
     // whose parent is already bound. Ordering is the cheap fix; the small
     // redundancy is accepted rather than papered over with copy that will rot.
     const offer = binding && binding.state === "inheritable" ? bindingOfferText(binding) : "";
+    // What binding does first, then the command alone on its line: an
+    // in-session form that can carry the parent's vault path (rule 4).
     const offerSystemMessage = offer
-      ? `projectstore: this worktree is unbound — ${inheritForm(binding.vaultPath, { layout: binding.layout, language: binding.language })} ${bindInherits() ? "adopts the binding of" : "binds it to the vault, layout and language of"} the checkout it was forked from.`
+      ? `projectstore: this worktree is unbound. ${bindInherits() ? "Adopt the binding of" : "Bind it to the vault, layout and language of"} the checkout it was forked from, in the session:\n${inheritForm(binding.vaultPath, { layout: binding.layout, language: binding.language })}`
       : null;
     const body = offer + (welcome || "");
     if (body) {
@@ -213,10 +227,23 @@ async function main() {
   // Opt-in status line: keep settings.local.json pointed at this plugin
   // version's statusline.mjs (self-heals on update). Best-effort; a settings
   // write must never break session-context injection.
-  try { syncStatusLine(cfg, proj); } catch {}
+  try {
+    syncStatusLine(cfg, proj);
+  } catch {}
   // Statusline-feature housekeeping, like syncStatusLine — must run even when
   // auto_inject=false (touch-session writes pointers regardless of it).
-  try { cleanupStaleSessionState(proj); } catch {}
+  try {
+    cleanupStaleSessionState(proj);
+  } catch {}
+  // This session's story fields from the story file, once (ADR-006, amended
+  // 2026-10-12): a pointer written before a close, or a story closed elsewhere
+  // since, stops naming finished work. A bounded read; a lost race writes
+  // nothing.
+  if (sid) {
+    try {
+      await refreshStoryPointer(proj, cfg.vault_path, sid);
+    } catch {}
+  }
 
   // Arm BEFORE the auto_inject gate. The entry reminder's markers must be
   // re-armed after a compaction whether or not this session injects context —
@@ -231,7 +258,9 @@ async function main() {
   // context while its marker persists on disk. Arming lets it fire once more;
   // the cap of two is enforced by the election, not here.
   if (sid && (input?.source === "compact" || input?.source === "clear")) {
-    try { armReminder(proj, sid); } catch {}
+    try {
+      armReminder(proj, sid);
+    } catch {}
   }
 
   if (cfg.auto_inject === false) {
@@ -272,23 +301,26 @@ async function main() {
     }
   }
 
-  // Cheap install-only doctor subset (ADR-005): one line, only when N > 0;
-  // aborted past its budget rather than reporting a false "clean".
+  // Cheap install-only doctor subset (ADR-005): one part, only when N > 0;
+  // aborted past its budget rather than reporting a false "clean". Its doctor
+  // form stands alone on its line, as every command of this line does.
   let doctorMsg = null;
   let offers = [];
   try {
     const r = runStartupChecks(cfg, proj);
     if (r.skipped) {
-      doctorMsg = `projectstore doctor: startup checks skipped — run ${commandForm("doctor")}`;
+      doctorMsg = `projectstore doctor: startup checks skipped. Run them in the session:\n${commandForm("doctor")}`;
     } else if (r.count > 0) {
-      doctorMsg = `projectstore doctor: ${r.count} install issue(s) — run ${commandForm("doctor")}`;
+      doctorMsg = `projectstore doctor: ${r.count} install issue(s). See them in the session:\n${commandForm("doctor")}`;
     }
     // Offers (doctor's OFFER_CHECKS): one-time steps a user should see once,
     // e.g. the re-stamp after a plugin update — not issues, not silent.
     offers = (r.offers || []).map((m) => `projectstore: ${m}`);
   } catch {}
-  const systemMessage =
-    [welcomeSystemMessage, doctorMsg, ...offers].filter(Boolean).join(" · ") || null;
+  // Each part on lines of its own: an offer ends with its command alone on
+  // its line, and a part joined after it with ` · ` would put text after the
+  // command (the story "User-facing text says where to run…", rule 4).
+  const systemMessage = [welcomeSystemMessage, doctorMsg, ...offers].filter(Boolean).join("\n") || null;
 
   if (gatherError) {
     emit(