projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/docs/alongside.md

@@ -0,0 +1,167 @@
+# ProjectStore beside agent memory and spec-driven tools
+
+People who meet ProjectStore compare it with what they already run next to a coding agent: a
+memory plugin, an instruction file, a spec-driven tool. This page says what each of those keeps,
+what ProjectStore keeps instead, and which parts of ProjectStore exist elsewhere. The README and
+the site name three kinds of tools; the first table here has four kinds, because agent memory kept
+in the repository gets its own column.
+
+The claims about other tools come from their own documentation, repositories and release notes,
+**read on 2026-10-09**. Tools move fast; if a cell below is wrong or out of date,
+[open an issue](https://github.com/SmartAndPoint/ProjectStore/issues/new?title=docs%2Falongside.md%3A+a+wrong+cell)
+and name the cell and your source.
+
+## The question each kind of tool answers
+
+| | Agent memory | Instruction files | Agent notes in the repository | Spec-driven tools | ProjectStore |
+|---|---|---|---|---|---|
+| **Examples** | Mem0, Zep, claude-mem, Codex memories, Claude Code auto memory | `CLAUDE.md`, `AGENTS.md`, rules, Kiro steering | Cline Memory Bank, Serena memories, Basic Memory, Letta | Spec Kit, Kiro specs, OpenSpec, BMAD | |
+| **One entry is** | a fact or an observation | a rule | a note the agent keeps | a change: spec, plan, tasks | a decision, a spec or a work item, with a status, a date and links |
+| **Written by** | the model, automatically | a person, or the agent on request | the agent, sometimes reviewed in pull requests | the agent; phase approval in Kiro and Tessl, a clear yes in OpenSpec's Explore, write previews in one BMAD skill | the agent drafts; a person approves the full text; a fresh-context critic reviews it by rule |
+| **Lives in** | a hosted or local index (vector, graph, SQLite), or machine-local files | the code repository | the code repository, or a memory repository | the code repository; OpenSpec Stores (beta) in a planning repository | a folder kept in git, usually its own repository |
+| **Read by** | the model, by retrieval | the model, at session start or when a file pattern or request matches | the model, on demand | the model and the team, during the feature | Claude Code sessions from the start (Codex: experimental); any agent through the CLI and MCP; people in pull requests and Obsidian |
+| **Scope** | an agent, a user or a machine | the project | the project | a feature, plus a constitution or steering | the project, across features and harnesses |
+| **Changes by** | expiry, invalidation, pruning | rewriting | rewriting, git history | per feature: discarded, or merged into living specs | supersede with reasons; status changes with evidence; `doctor` and `reconcile` |
+| **Answers** | "What does this agent recall?" | "How should an agent behave here?" | "What has this agent learned about the project?" | "How do we build this change?" | "What has the project decided, what is in flight, and was it checked?" |
+
+## Why ProjectStore is not agent memory
+
+1. **Nothing is written because it was said.** A memory system writes when the model notices
+   something. A vault artifact is written through a ProjectStore command, after a person approved
+   its path and full text. The skill that watches the conversation only suggests a command.
+2. **Nothing is read by similarity.** Agents navigate: folder indexes, the link graph grepped by
+   path, the kanban, then the artifact. `search` is a literal substring search. What an agent read
+   is a file a person can open.
+
+   The price: an agent must know a word, a title or a path. Nothing finds a note that says the
+   same thing in other words.
+3. **Nothing belongs to an agent, a user or a machine.** The vault travels through git to whoever
+   has the repository. Claude Code and Codex read it through ProjectStore's commands; any other
+   agent can read it through the CLI or the MCP read surface. Codex memories and Claude Code auto
+   memory are per machine; Mem0's are per user or agent.
+4. **It can be wrong in a way that is reviewed.** A memory that turned false is expired, pruned or
+   invalidated. A decision that turned false is superseded by a newer ADR that says why, and the
+   chain stays.
+5. **What survives `/compact` is paths into the record, not knowledge from the session.** In
+   Claude Code, the SessionStart hook runs after compaction too. It hands back a navigation
+   skeleton of the vault plus the vault paths the session touched: the session's own activity log,
+   machine-local and git-ignored, resolved against the vault. Nothing the conversation said is
+   stored. Codex runs the same hook in its experimental shell, but what it reports after
+   compaction has not been measured.
+
+**The overlap.** ProjectStore keeps a little session state on the machine — a per-session pointer
+and the last 50 activity entries — for orientation, never committed. It is not knowledge, and
+deleting it changes nothing in the vault.
+
+**Where the data goes.** A memory tool stores what it derives from conversations, and some ship it
+off the machine (Mem0's platform, claude-mem's optional cloud sync). The vault holds only text a
+person approved. What reaches the model provider still depends on your harness and its
+permissions.
+
+## Memory and the vault, side by side
+
+They are not rivals. Use both, each for its own thing:
+
+- **Memory for the person and the machine:** how you like to work, your environment's quirks,
+  corrections you gave the agent.
+- **The vault for the project:** what was decided and why, what is in flight, what was checked.
+
+The vendors say the same about their own memory. Codex: "Keep required team guidance in AGENTS.md
+or checked-in documentation. Treat memories as a helpful recall layer, not as the only source for
+rules that must always apply." Claude Code's auto memory skips what your `CLAUDE.md` already says.
+
+The rule needs upkeep, because memory fills up on its own. When a memory states a project decision
+or an idea the team should see, move it into the vault as an artifact, and let the memory keep only
+a pointer to it.
+
+## The ingredients, tool by tool
+
+Every ingredient of ProjectStore's loop exists somewhere else. This matrix shows where. "Core"
+means without extensions; "?" means the documentation we read says nothing either way.
+
+| Tool | Decision record with status and supersede | Person approves the full text before a write | Fresh-context review of planning artifacts | Fresh-context review of the diff against acceptance criteria | Orientation from the record at session start | Consistency checks with no model | Read surface for any agent |
+|---|---|---|---|---|---|---|---|
+| Spec Kit 1.1, core | no | no (a convention between phases) | no (in-context `/speckit.analyze` and `/speckit.checklist` only) | no | no | ? | commands for about forty agents |
+| Spec Kit with community extensions | `adrkit`: MADR records with `status`, `adr accept`, superseded retrieval (pinned below 1.1.0) | no, before a write. `plan-review-gate` requires spec and plan merged by PR before tasks; `spec-validate` adds approval state as "a hard gate before /speckit.implement" | `red-team`, `critique`, `multi-model-review` | `maqa`, a QA workflow (fresh context unstated) | the official `agent-context` extension keeps a static block in `CLAUDE.md`/`AGENTS.md`; `memory`, `dubsar` (resume) | ? (`speckit-utils` "validate project health", `sync`; model use unverified) | same |
+| Kiro | no | yes, per phase (Quick Spec skips the gates) | ? | ? | steering, always included | ? | Kiro only |
+| OpenSpec 1.14 | a section per change; the archive keeps history | Explore only: waits for "a clear yes" | ? | ? | marker blocks in `CLAUDE.md`/`AGENTS.md`; no session hook | **yes**: `openspec validate` | many tools |
+| BMAD 6.12.1 | spine `AD-n`: IDs can be retired, never reused; append-only rationale; no supersede chain documented | the project-context skill shows every write first | **yes**: reviewer gates on PRD, spine, UX | fresh subagent lenses (edge cases, verification gaps); the edge-case lens reads the spec's acceptance as claims, not per criterion | its `AGENTS.md` block (project-context skill); no SessionStart hook found | **yes**: `sprint_plan.py validate` | installer for several agents |
+| Beads 1.3.1 | no: issues, not decisions (`bd supersede` marks an issue superseded by a newer one) | no | no | no | **yes**: `bd prime` through SessionStart hooks (Claude Code, Gemini CLI, Codex) | **yes**: `bd doctor`, `bd lint` (missing sections), `bd orphans` (referenced in commits, still open) | CLI with JSON; Dolt in git, JSONL export |
+| Letta, Serena | no | no | no | no | Letta loads memory-root files into the system prompt every turn | no | Serena: any MCP client |
+| Mem0, claude-mem | no | no | no | no | claude-mem injects memory at session start | no | many harnesses |
+| ProjectStore 0.29.2 | **yes**: ADR status, `superseded_by` | **yes**, through its commands | a standing rule for every kind (critic) | a standing rule (reviewer), per criterion with evidence | **yes** in Claude Code; Codex experimental | **yes**: `doctor`, `reconcile`, regenerated views | CLI and MCP; Claude Code and Codex shells |
+
+**What it shows.** No single column is ProjectStore's alone:
+- `adrkit` keeps decision status and supersession;
+- OpenSpec, BMAD and Beads validate artifacts without a model;
+- Beads injects ready work at session start;
+- BMAD reviews plans and diffs in fresh contexts.
+
+What none of the tools above documents is all of them over one record: decisions, specs and work
+items in one linked graph with a lifecycle, where the same `doctor` checks the links between them
+and down to code, the same views regenerate from them, one critic rule covers every kind, and each
+session's starting map is computed from that record.
+
+**The nearest composition is Spec Kit with extensions.** Read cell by cell, it covers three of the
+four ingredients listed above — decision status (`adrkit`), fresh-context review (`red-team`,
+`critique`, `multi-model-review`), session-start orientation (`agent-context`, `memory`, `dubsar`) —
+and has a "?" on the fourth, checks with no model. But it spreads across three stores — `adrkit`'s
+ADRs, `specs/`, and an issue tracker through `maqa` — and documents no links between them and no
+check that reads across them. `adrkit`'s catalog entry also pins Spec Kit below 1.1.0, the current
+core.
+
+**Review is a rule, not a lock**, in ProjectStore and in BMAD alike. Both are only as good as their
+being followed. In ProjectStore, ADRs, specs, epics and research notes carry `review_status:
+pending` until a critic pass is applied, so "not yet reviewed" is a state the tools can read;
+stories are checked instead by the reviewer, against their diff. Nothing stops a person from
+accepting an ADR before the critic pass.
+
+**When this table is re-read:** when BMAD ships its next release, when OpenSpec Stores leave beta,
+or when a Spec Kit extension joins decision records to review — each of those could change a cell.
+
+**Sources, read on 2026-10-09:**
+- Spec Kit: [repository](https://github.com/github/spec-kit) — releases 1.0.0 (2026-08-21) and
+  1.1.0 (2026-10-02), `docs/concepts/spec-persistence.md`, `docs/reference/integrations.md`,
+  `extensions/catalog.community.json`; [adrkit](https://github.com/mbeacom/adrkit).
+- Kiro: [specs](https://kiro.dev/docs/specs/), [best practices](https://kiro.dev/docs/specs/best-practices/),
+  [steering](https://kiro.dev/docs/steering/).
+- OpenSpec: [repository](https://github.com/Fission-AI/OpenSpec) — releases, `docs/concepts.md`,
+  `docs/cli.md`, `docs/installation.md`, `docs/stores-beta/user-guide.md`.
+- BMAD-METHOD: [repository](https://github.com/bmad-code-org/BMAD-METHOD) — release 6.12.1
+  (2026-10-04), `src/bmm-skills/plan/bmad-architecture/references/reviewer-gate.md`,
+  `src/bmm-skills/plan/bmad-sprint-planning/references/validate.md`.
+- Beads: [repository](https://github.com/gastownhall/beads) — release 1.3.1 (2026-09-30),
+  `docs/cli-reference/`.
+- Letta: [context repositories](https://www.letta.com/blog/context-repositories),
+  [MemFS](https://docs.letta.com/concepts/memfs). Serena:
+  [memories](https://oraios.github.io/serena/02-usage/045_memories.html).
+- Zep / Graphiti: [concepts](https://help.getzep.com/concepts),
+  [Graphiti](https://github.com/getzep/graphiti). Cline: [Memory Bank](https://docs.cline.bot/best-practices/memory-bank).
+  Basic Memory: [repository](https://github.com/basicmachines-co/basic-memory). Tessl:
+  [overview](https://docs.tessl.io/overview/readme.md),
+  [spec-driven development tile](https://github.com/tesslio/spec-driven-development-tile).
+- Mem0: [how it works](https://docs.mem0.ai/core-concepts/how-it-works),
+  [memory expiration](https://docs.mem0.ai/platform/features/memory-expiration),
+  [OpenMemory's removal](https://github.com/mem0ai/mem0/pull/6530). claude-mem:
+  [repository](https://github.com/thedotmack/claude-mem).
+- Claude Code: [memory](https://code.claude.com/docs/en/memory). Codex:
+  [memories](https://learn.chatgpt.com/docs/customization/memories),
+  [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
+- ProjectStore: this repository.
+
+## What the checks cost
+
+The critic and reviewer runs are model calls, and they are not free. On this repository, where
+every change goes through the full loop, vault work measures 22.5% of total spend; on a typical
+project, budget 10–15% of a weekly limit. The number is the price of the critic and reviewer
+runs, not of storing files. See
+[What it costs — measured, not promised](../README.md#what-it-costs--measured-not-promised).
+
+## Spec-driven tools
+
+Running ProjectStore beside a spec-driven tool such as Spec Kit, Kiro or OpenSpec is a design that
+has not been tried. The idea is that the spec-driven tool would own one feature's spec, plan and
+tasks, while ProjectStore keeps the decisions, the backlog and the checks around them. Whether the
+two tools' agent instructions, entry points and acceptance criteria stay out of each other's way is
+an open question, and so is how ProjectStore's spec-first policy should be set beside them. A trial
+and a decision on that policy are proposed; until they land, this page recommends no setting.

package/node_modules/projectstore/docs/extending.md

@@ -4,8 +4,8 @@
 
 Since v0.14 the kind machinery is layout-driven: `draft.mjs` builds ANY kind
 declared in the layout, and doctor's template check follows the layout instead
-of a hardcoded list. A new kind needs **five touch points** — note that **all
-five live inside the plugin installation**, not in your vault (there is no
+of a hardcoded list. A new kind needs **six touch points** — note that **all
+six live inside the plugin installation**, not in your vault (there is no
 vault-side layout or template override):
 
 1. **Layout folder entry** — `scaffold/layouts/<name>.json` → `folders`:
@@ -56,6 +56,16 @@ vault-side layout or template override):
    `collision`/`warnings` fields and updates an index, `commands/spec.md`
    for one with status transitions.
 
+6. **Folder strings** — `templates/<lang>/strings.json` → `folders.<kind>`,
+   a `name` and a one-line `description`, in **every** bundled language's
+   file. `scaffold` (and `init`) render the folder's README and its row in
+   the vault's top-level README from them, and refuse a layout whose folder
+   kind has no string in the bound language, naming the kind and the
+   language; doctor warns about the same gap. Every folder kind needs one,
+   with or without a command (`diagram` too). Keep the description to 160
+   characters with no `|`: the SessionStart skeleton shows it as the
+   folder's Purpose cell. Machine tokens such as `stories/` stay as they are.
+
 If the kind introduces **new section headings or inline keywords** that
 deterministic checks must recognize (doctor, reconcile, story-section),
 register a form per bundled language (en, ru, es, de, fr, zh) in
@@ -108,7 +118,11 @@ Frontmatter keys **and their values** stay English (`status: planned` is
 machine-read; only prose and table labels get translated). Then register the
 language's heading/keyword/index-column forms in `scaffold/headings.json`, and
 add the locale to `LOCALES` in `tests/locales.test.mjs` so the suite actually
-runs over it. `templates/<lang>/strings.json` localizes the statusline only.
+runs over it. `templates/<lang>/strings.json` localizes the statusline and the
+folder names and descriptions `scaffold` writes into the READMEs
+(`folders.<kind>`, one per kind the layout declares — touch point 6 above),
+and `vault-readme.md.tmpl` is the vault's top-level README. There is no English
+fallback for either: a language that lacks one is refused by `scaffold`.
 
 Skipping the registry does not produce one clean error — it degrades *unevenly*,
 which is why the spec exists: an unregistered index header raises a doctor

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

@@ -37,11 +37,7 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
 
 ## First-time setup
 
-1. **Pick a vault directory** — any folder where you want your project artifacts to live. Obsidian opens it natively. Git tracks it cleanly.
-
-   ```bash
-   mkdir -p ~/Documents/projects/my-project-vault
-   ```
+1. **Pick a vault directory** — any folder where you want your project artifacts to live. Obsidian opens it natively. Git tracks it cleanly. There is nothing to create by hand: step 2 creates the vault when the folder does not exist yet or is empty.
 
 2. **Bind your current project to that vault**:
 
@@ -49,7 +45,15 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
    /projectstore:bind ~/Documents/projects/my-project-vault
    ```
 
-   This creates `.projectstore/projectstore.json` in your project root (machine-local, gitignored) — and then walks you through a short interview: gitignore entries → scaffold offer → agent registration in `CLAUDE.md` (recommended: Yes) → model preset for the review agents (the default `opus` is fine) → status line offer (you'll see a preview of the exact line). Every step shows what it wants to write and waits for your approval.
+   This creates `.projectstore/projectstore.json` in your project root (machine-local, gitignored) — and then walks you through a short interview: gitignore entries → scaffold offer → vault policy → agent registration in `CLAUDE.md` (recommended: Yes) → model preset for the review agents (the default `opus` is fine) → status line offer (you'll see a preview of the exact line). Every step shows what it wants to write and waits for your approval. When the folder is missing or empty, the interview offers to create the whole vault there through `init` — the directory, its own git repository, the layout's folders and their README indexes — and then has no scaffold to offer.
+
+   **From a terminal instead**, outside a session, one command creates the same vault and binds this project to it:
+
+   ```bash
+   npx projectstore init ~/Documents/projects/my-project-vault
+   ```
+
+   It skips the rest of the interview: no agents block, no status line, no vault policy, no model preset. A later `/projectstore:bind` on that project only reports "Already bound" — it does not run those steps either. Choose this path when you want the vault and the binding alone.
 
    **Working in a git worktree?** That config is gitignored, so a worktree of a bound checkout starts unbound and `/projectstore:*` will not run there. Session start says so and names the fix:
 
@@ -59,13 +63,17 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
 
    It copies the binding of the checkout the worktree was forked from — same vault, shared and unchanged, no session state carried over — and skips the interview, since the parent already answered it.
 
-3. **Scaffold the layout** if the vault is empty (bind offers this automatically):
+3. **Scaffold the layout** of a vault that was bound without its folders (bind offers this automatically; a vault `init` made already has them):
 
    ```
-   /projectstore:scaffold engineering
+   /projectstore:scaffold
    ```
 
-   Creates `adr/`, `specs/`, `epics/`, `research/`, `concepts/`, `meetings/`, `ops/`, `diagrams/` and a top-level `README.md`.
+   Creates whichever of `adr/`, `specs/`, `epics/`, `research/`, `concepts/`, `meetings/`, `ops/`, `diagrams/`, their `README.md` indexes and the top-level `README.md` are missing, in the vault's language, and never rewrites a file that is there. The layout is the binding's. From a terminal:
+
+   ```bash
+   npx projectstore scaffold --write
+   ```
 
 ## Daily flow
 
@@ -81,6 +89,7 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
 /projectstore:codemap                                     # epic ↔ code mapping view
 /projectstore:graph                                       # vault link graph: nodes + typed edges
 /projectstore:agents status                               # routing block + model config state
+/projectstore:bar status                                  # the band above the prompt: on/off, a pinned epic, why it is not drawing
 ```
 
 ## How approval works

package/node_modules/projectstore/docs/harnesses.md

@@ -13,7 +13,7 @@ This page says which harnesses exist, how far each one is trusted, and what
 
 | Harness | id | Status | Verified | Surfaces installed |
 |---|---|---|---|---|
-| Claude Code | `claude-code` | **supported** | 2026-08-30 | hooks, commands, agents, skills, MCP, status line, agents block |
+| Claude Code | `claude-code` | **supported** | 2026-08-30 | hooks, commands, agents, skills, MCP, status line, agents block; the band above the prompt (experimental until its own live run) |
 | Codex | `codex` | **experimental** | — | portable plugin, hooks, rendered workflow skills, agents block |
 
 **supported** means the manifest carries a `verified` block: a session id and a

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
@@ -134,6 +136,13 @@ has one, else `~/.claude/settings.json`), prints its output
 verbatim, and adds one `[PS#version] 📚 …` line above it (`statusline.position`:
 `above`/`below`). With no base command it renders a standalone line.
 
+While this session's band above the prompt is drawing, the line gives way to
+it: the band keeps a heartbeat file fresh in the session-state directory, and
+the renderer leaves its own line out while that file is younger than 30 s —
+the base HUD prints as it always does. A band that stops, or never starts
+(an older Claude Code, modules switched off), lets the heartbeat go stale, and
+the line is back on its own.
+
 ## Doctor and reconcile: the trust layer
 
 The vault's guarantees used to depend on everyone using the gated commands —
@@ -155,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

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

@@ -57,9 +57,14 @@
       }
     ],
     "session_env": [
-      "CLAUDECODE"
+      "CLAUDECODE",
+      "CLAUDE_CODE_SESSION_ID"
     ],
-    "session_env_reason": "set to 1 in every Bash tool of a live session (measured 2026-09-05, 2.1.261); detect_env names the variables a hook or plugin process receives, which a Bash tool does not — the two questions differ.",
+    "session_env_reason": "set to 1 in every Bash tool of a live session (measured 2026-09-05, 2.1.261); detect_env names the variables a hook or plugin process receives, which a Bash tool does not — the two questions differ. CLAUDE_CODE_SESSION_ID is set there too (measured 2026-10-10, 2.1.296).",
+    "session_id_env": "CLAUDE_CODE_SESSION_ID",
+    "session_id_env_reason": "the session's id in every Bash tool of a live session (measured 2026-10-10 and 2026-10-11, 2.1.296): the id the session-state files are keyed by, which `band status` needs to find this session's pointer and heartbeat (the band spec, contract 13). Read only through hostSessionId(), since scripts/ names no branded variable.",
+    "registration_defer_env": [],
+    "registration_defer_env_reason": "Empty: session_env already defers this harness's registration inside its own session (measured: the host's CLI and the session's exit rewrite the same settings files), and registrationDeferred reads both lists. Present on every manifest, an array, so an absent key is never a forgotten one (story: projectstore setup asks, shows one plan and installs every harness it finds, with the vault, rule 15).",
     "overlay": "claude-code",
     "overlay_reason": "the file under <project>/.projectstore/harness/ that carries this harness's agents block — the models, per agent, that plugin surfaces pass per invocation (ADR-008; the layout ADR decision 3)"
   },
@@ -129,16 +134,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": [
@@ -246,6 +251,15 @@
       "scope_reason": "Claude Code loads the plugin's hooks.json from the plugin installation itself; per-project hooks live in settings, which projectstore does not write.",
       "registered_by": "plugin"
     },
+    "band": {
+      "supported": true,
+      "kind": "host",
+      "registered_by": "plugin",
+      "scope": "user",
+      "scope_reason": "Claude Code loads the band as a hooks module named under `modules` in the plugin's own hooks.json, from the plugin installation itself; nothing is written into a project to draw it.",
+      "verified": null,
+      "verified_reason": "null until a recorded live session (terminal and Desktop) observes it drawing, hiding during a question, and the status line yielding and coming back (the band spec, contract 15). The harness's own `verified` block predates the surface and does not cover it."
+    },
     "agents_block": {
       "supported": true,
       "kind": "shared",
@@ -285,7 +299,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": {
@@ -385,7 +399,8 @@
             "-y accepts a marketplace-declared command; this marketplace declares none",
             "the project of a --scope local command is the process cwd; there is no --project flag",
             "a live session marks its Bash environment with CLAUDECODE=1 (not the plugin-root or project-dir variables, which reach hooks only); the registration defers on that marker",
-            "`plugin update` at an unchanged version answers \"already at the latest version\" and copies nothing, even after `marketplace update`: a same-version content refresh is uninstall + install"
+            "`plugin update` at an unchanged version answers \"already at the latest version\" and copies nothing, even after `marketplace update`: a same-version content refresh is uninstall + install",
+            "2.1.296, 2026-10-10: the plugin of this directory marketplace loads in place from <dir>/<plugin_subdir> — the MCP server's argv, the slash commands' plugin root and the SessionStart hook all name it — while the registry row's installPath stays the cache copy the launcher renders; the SessionStart refresh therefore never demotes a launcher entry (install spec, contract 0 as amended 2026-10-10)"
           ]
         },
         "commands": {
@@ -479,7 +494,7 @@
   "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": [

package/node_modules/projectstore/harnesses/codex.json

@@ -29,7 +29,11 @@
     ],
     "shared_env_reason": "Codex sets Claude Code's plugin-root names too, for compatibility — measured in every one of the 759 captured hook payloads. Without declaring them, a Codex session scores a strong detection hit for claude-code, ties with codex, and loses the tie to manifest filename order. A variable two harnesses both set identifies neither, so these are demoted to weak for every manifest (generation spec, contract 1, amended 2026-09-08).",
     "session_env": [],
-    "session_env_reason": "Deliberately empty, though measured. Codex's exec tool sets CODEX_THREAD_ID and CODEX_SESSION_ID in every command (measured 2026-10-05, codex-cli 0.160.0; CODEX_SANDBOX* depend on the sandbox mode), and CODEX_HOME never appeared in a hook environment. Declaring them would identify a session, but session_env also defers the registration and the layout move inside a session (insideHostSession), which would stop the doctor skill's upgrade --json fix from running there. Splitting identity from deferral is the question of *Codex hook contract measured in a live session* (PS-HARNESS); until then a core run from a rendered skill is identified by the shell that bundles it (generation spec, contract 18)."
+    "session_env_reason": "Deliberately empty, though measured. Codex's exec tool sets CODEX_THREAD_ID and CODEX_SESSION_ID in every command (measured 2026-10-05, codex-cli 0.160.0; CODEX_SANDBOX* depend on the sandbox mode), and CODEX_HOME never appeared in a hook environment. Declaring them would identify a session, but session_env also defers the registration and the layout move inside a session (insideHostSession), which would stop the doctor skill's upgrade --json fix from running there. Splitting identity from deferral is the question of *Codex hook contract measured in a live session* (PS-HARNESS); until then a core run from a rendered skill is identified by the shell that bundles it (generation spec, contract 18). The deferral half of that split is registration_defer_env below (the maintainer's decision of 2026-10-08).",
+    "registration_defer_env": [
+      "CODEX_THREAD_ID"
+    ],
+    "registration_defer_env_reason": "Defers this harness's registration, and the shell fetch that would feed it, and nothing else (harness.mjs registrationDeferred): install, upgrade and setup leave the registration for a terminal outside the session, and so does uninstall --global's removal, which runs the same host CLI against the same CODEX_HOME. Codex's exec tool sets CODEX_THREAD_ID in every command (measured 2026-10-05, codex-cli 0.160.0; session_env_reason above). Whether a Codex session rewrites config.toml at exit is not measured; the maintainer chose deferral on 2026-10-08, answering the front-door ADR's first open question (story: projectstore setup asks, shows one plan and installs every harness it finds, with the vault, rule 15). isInteractive, the layout move and session identity do not read this key, so the doctor skill's upgrade --json still moves the layout inside a session. Lifting the deferral needs a measurement of its own."
   },
   "tools": {
     "write_tools": [
@@ -242,6 +246,13 @@
       "scope_reason": "There is no per-project status-line slot to occupy: Codex has no status-line surface at all, so nothing of ours is written anywhere and the scope is the host's, not a file's.",
       "why_unsupported": "No status-line mechanism was found in the harness — no settings slot, no plugin field, no handler contract. Recorded as a row rather than an absence so the generator's coverage invariant sees a stated omission (contract 9) instead of a surface that quietly does not exist here."
     },
+    "band": {
+      "supported": false,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "There is no surface above the prompt to draw into: nothing of ours is written anywhere, so the scope is the host's, not a file's.",
+      "why_unsupported": "Codex has no plugin surface that draws above the prompt and no hooks module runtime. The generator drops the module from this tree's hooks.json and renders the bar command as a skill that says so (the band spec, contract 1)."
+    },
     "plugin": {
       "supported": true,
       "kind": "registration",
@@ -310,8 +321,7 @@
       "run `$projectstore-bind <vault-path>` in Codex"
     ],
     "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.",
@@ -322,9 +332,9 @@
     "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
   },
   "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.",
   "agent_translation": {

package/node_modules/projectstore/hooks/band-state.d.ts

@@ -0,0 +1,44 @@
+// projectstore — the band's values in the host's session state ($.state):
+// what hooks/band.tsx draws from. Named in .claude-plugin/plugin.json under
+// "types", so `claude plugin validate` holds every key the module names to it.
+
+export type BandCounts = { done: number; active: number; backlog: number }
+
+// The epic the band shows and everything its rows need, written by the
+// module's clock only when it changed (a write redraws the band).
+export type BandView = {
+  id: string
+  title: string
+  goal: string
+  // null until the stories have been read whole once: no progress row.
+  counts: BandCounts | null
+  why: 'this' | 'pinned'
+  story: { title: string; status: string | null } | null
+  version: string | null
+  hint: boolean
+  words: Record<string, string>
+}
+
+export type BandAgentStatus = 'running' | 'done' | 'error'
+
+// A ProjectStore agent this session spawned: its role, the model and effort
+// its own requests name, and the vault document its prompt names.
+export type BandAgent = {
+  id: string
+  role: string
+  model: string
+  effort: string | null
+  subject: string | null
+  description: string
+  status: BandAgentStatus
+  startedAt: number
+  endedAt?: number
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    // `steps` is apart from `crew` on purpose: only the terminal's band reads
+    // it, so an agent's every step never redraws Desktop's drawing.
+    projectstore: { band: BandView | null; crew: BandAgent[]; steps: Record<string, string> }
+  }
+}