projectstore-claude 0.29.1 → 0.29.3

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

@@ -134,6 +134,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 —

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)"
   },
@@ -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",
@@ -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": {

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

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> }
+  }
+}