projectstore-claude 0.29.4 → 0.30.1

package/node_modules/projectstore/docs/extending.md

@@ -49,12 +49,17 @@ vault-side layout or template override):
 4. **Checklist entry** — `scaffold/checklists.json`, consumed by
    `/projectstore:review` and the `projectstore-peer-reviewer` skill. English-only by design.
 
-5. **Command prompt** — `commands/<kind>.md`, a prompt (not code) that calls
-   `node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" <kind> "$ARGUMENTS"`, previews,
-   and gates every write behind AskUserQuestion. Copy `commands/research.md`
-   for a plain kind, `commands/adr.md` for one that renders the draft's
-   `collision`/`warnings` fields and updates an index, `commands/spec.md`
-   for one with status transitions.
+5. **Command prompt** — `commands/<kind>.md`, a prompt (not code). It renders
+   the draft with the line below, previews it, and gates every write behind
+   AskUserQuestion:
+
+   ```
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" <kind> "$ARGUMENTS"
+   ```
+
+   Copy `commands/research.md` for a plain kind, `commands/adr.md` for one
+   that renders the draft's `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

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

@@ -1,8 +1,20 @@
 # Getting started with projectstore
 
-## Install (local dev)
+## Install
 
-Until projectstore is published to a public marketplace, install it from a local clone.
+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 what setup needs (Node.js 20 or later; npm only for Codex), the other package runners, the global form and the registry-mirror form. Setup binds the vault itself, so after it the project is ready: restart the agent and go on to the daily flow.
+
+The next two sections are the other ways in: a checkout, for contributors, and the git marketplace inside a Claude Code session. After either of them, the first-time setup below binds the vault from inside a session.
+
+## From a checkout
+
+For contributors working on projectstore itself. Clone it; [Running a checkout's build](../packaging/README.md#running-a-checkouts-build) covers the packed form.
 
 ```bash
 git clone https://github.com/SmartAndPoint/ProjectStore.git ~/Projects/SmartAndPoint/ProjectStore
@@ -28,7 +40,7 @@ Verify the plugin appears:
 
 You should see `projectstore` (displayName) with prefix `projectstore`.
 
-## Install (via marketplace)
+## In a Claude Code session, from the git marketplace
 
 ```
 /plugin marketplace add SmartAndPoint/ProjectStore
@@ -37,6 +49,8 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
 
 ## First-time setup
 
+`npx projectstore setup` binds a vault or creates one, adds the agents block, and offers the status line, in one plan. The steps below do that from inside a Claude Code session, for the two ways in above, and also ask for the vault's policy and the agents' models; after setup, those two are [Configure](#configure)'s.
+
 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**:
@@ -75,6 +89,22 @@ You should see `projectstore` (displayName) with prefix `projectstore`.
    npx projectstore scaffold --write
    ```
 
+## Configure
+
+After setup, every setting is one command away, from a terminal in your project:
+
+```
+npx projectstore configure
+```
+
+It shows each agent's model, the status line and the band, the template language, and the vault's spec policy and lifecycle gates — with their values and the file each one lives in. Then it asks which to change, shows one plan and asks once. From a script or an agent, name the change; naming it is the confirmation:
+
+```
+npx projectstore configure --set language=de --set lifecycle_gates=on
+```
+
+The README's [Configure](../README.md#configure) section lists what each setting writes and which files are committed.
+
 ## Daily flow
 
 ```
@@ -110,12 +140,10 @@ Skills (`projectstore-decision-detector`, `projectstore-story-completion`) are p
 
 ## Disabling skills
 
-Edit `.projectstore/projectstore.json`:
+From a terminal in your project:
 
-```jsonc
-{
-  "active_skills": false
-}
+```
+npx projectstore configure --set active_skills=off
 ```
 
 ## Multi-language templates
@@ -126,12 +154,26 @@ Default is English (`en`). Also bundled: Russian (`ru`), Spanish (`es`), German
 /projectstore:bind <path> --lang de
 ```
 
-Or edit `language: "de"` in `.projectstore/projectstore.json` (templates must exist at `templates/de/`). The language also localizes the status line strings (e.g. the "no epic or story in this session yet" line).
+A bound project changes it with `configure` (the value must be a bundled language). From a terminal in your project:
+
+```
+npx projectstore configure --set language=de
+```
+
+New artifacts take the new language's templates. The language also localizes the status line strings (e.g. the "no epic or story in this session yet" line).
 
 What the language does and does not change: section headings, table labels and prose are translated; frontmatter keys and their values (`status: planned`, `priority: p2`) stay English, because they are machine-read. Section headings are registered in `scaffold/headings.json`, so doctor, reconcile and the story lifecycle gates recognize every bundled language — a Russian-headed file lints in a French-bound vault, and mixed-language vaults reconcile.
 
 ## 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 +181,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,33 @@ 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.
+
+`npx projectstore configure` changes Codex's settings as it does Claude Code's.
+In a project that uses only Codex, it offers no status line and no band: Codex
+has neither surface. An agent's model goes to `.projectstore/harness/codex.json`:
+name it in Codex's own vocabulary with `--set agents.<name>=<model>`. The
+terminal's model presets are Claude Code's, so they are not offered for Codex.
+
 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

@@ -191,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": [
@@ -493,19 +494,40 @@
   ],
   "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#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."
+    "line": "Update from a terminal in this project:\n{upgrade}",
+    "welcome": [
+      "**About future updates**: from a terminal in this project, run:",
+      "",
+      "```",
+      "{upgrade}",
+      "```",
+      "",
+      "Then restart Claude Code. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details."
+    ],
+    "by_channel": {
+      "marketplace": {
+        "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#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, so what is printed runs as printed. `by_channel` holds the text for a copy that loads from another channel, by installChannel's answer: a copy from the git marketplace is updated by Claude Code itself, so its welcome keeps the auto-update toggle; the npm registration and a checkout get the npm form. 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,32 +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"
     ],
     "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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.29.4",
+  "version": "0.30.1",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/agents-change.mjs

@@ -0,0 +1,84 @@
+// The change to a harness overlay's agents block (the configure spec,
+// contract 8): planned once, here, and called by `agents configure` and by
+// `configure`, so the clerk pin, the precedence and the overlay's other keys
+// behave the same whichever verb asks. The gate stays the caller's.
+import { readOverlayAt, writeOverlayAt } from "./lib.mjs";
+import { harnessForOverlay } from "./harness.mjs";
+
+// What a change would write. `before` is readOverlayAt's read; `roster` the
+// layout's agent names (null when no layout loads); `agents` the
+// `<name>=<model>` specs. A malformed spec or a name outside the roster comes
+// back as `usage`, with nothing planned.
+export function planAgentsChange({ before, harness, layout, roster, defaultModel, agents = [], reset = false }) {
+  // --reset empties the block first; --default and --agent then apply on top of
+  // the emptied block — "reset, then set" is one call, and nothing given is
+  // silently dropped.
+  const base = reset ? { default: null, per_agent: {} } : before.agents;
+  const next = {
+    default: defaultModel !== undefined ? defaultModel || null : base.default,
+    per_agent: { ...base.per_agent },
+  };
+  for (const spec of agents) {
+    const m = /^([a-z][a-z0-9-]*)=(.*)$/.exec(spec);
+    if (!m) return { usage: `--agent takes <name>=<model>, got ${spec}` };
+    // A name outside the roster would be written, listed, and never run.
+    if (roster && !roster.includes(m[1]))
+      return { usage: `no agent named ${m[1]} in the ${layout} roster — known: ${roster.join(", ")}` };
+    if (m[2]) next.per_agent[m[1]] = m[2];
+    else delete next.per_agent[m[1]];
+  }
+  // The clerk transcribes; a strong default must not lift it (commands/agents.md,
+  // ADR-008). WHICH model it is pinned to is the harness's vocabulary, so the
+  // manifest names it and this file does not: pinning every harness to
+  // "sonnet" wrote an Anthropic model name into a Codex overlay, which is a
+  // model that does not exist there. A manifest with no cheap model declared
+  // does not pin, and the preview says so rather than inventing one.
+  // No fallback model here, deliberately, and it is not the same call as
+  // SOURCE_WRITE_TOOLS_FALLBACK: a missing manifest cannot reach this line.
+  // harnessIds() derives from the manifests, so with none loadable a named
+  // harness is refused as unknown before any caller plans a change (`agents
+  // configure` and `configure` both check it first). A literal here would be
+  // the deleted `"sonnet"` restored for a case that cannot happen.
+  let pinnedClerk = false;
+  let clerkPinUnavailable = false;
+  const clerkAsked = agents.some((s) => s.startsWith("clerk="));
+  if (next.default && !next.per_agent.clerk && !clerkAsked) {
+    const cheap = harnessForOverlay(harness)?.agent_translation?.cheap_model || null;
+    if (cheap) {
+      next.per_agent.clerk = cheap;
+      pinnedClerk = true;
+    } else clerkPinUnavailable = true;
+  }
+  // Keys inside the agents block that the allowlist rejected (an `effort`, a
+  // stray shape) are rewritten out by the write and announced here; keys
+  // outside the block are kept, and stay doctor's to name.
+  const dropped = before.rejected.filter((k) => k.startsWith("agents."));
+  const same =
+    !dropped.length &&
+    JSON.stringify({ d: before.agents.default, p: before.agents.per_agent }) ===
+      JSON.stringify({ d: next.default, p: next.per_agent });
+  const preview = [
+    `agents configure — ${harness} — ${before.path}`,
+    `  default: ${before.agents.default || "—"} → ${next.default || "—"}`,
+  ];
+  const names = new Set([...Object.keys(before.agents.per_agent), ...Object.keys(next.per_agent)]);
+  for (const n of [...names].sort())
+    preview.push(
+      `  ${n}: ${before.agents.per_agent[n] || "—"} → ${next.per_agent[n] || "—"}${pinnedClerk && n === "clerk" ? " (pinned: the clerk stays cheap under a strong default)" : ""}`,
+    );
+  // Silence here would read as "the clerk is fine", and it is not: it takes the
+  // strong default, which is the one thing ADR-008 says must not happen to it.
+  if (clerkPinUnavailable)
+    preview.push(
+      `  clerk: takes the default — ${harness} declares no cheap model to pin it to, so name one with --agent clerk=<model>`,
+    );
+  if (dropped.length)
+    preview.push(`  drops from the agents block (an overlay carries only models): ${dropped.join(", ")}`);
+  return { next, pinnedClerk, clerkPinUnavailable, dropped, same, preview };
+}
+
+// Writes a planned change through the overlay's one writer and reads it back.
+export function applyAgentsChange(projectDir, harness, next) {
+  const path = writeOverlayAt(projectDir, harness, next);
+  return { path, after: readOverlayAt(projectDir, harness) };
+}

package/node_modules/projectstore/scripts/binding.mjs

@@ -135,6 +135,46 @@ function readExisting(configPath) {
   }
 }
 
+// The binding's plain settings and their one writer (the configure spec,
+// contract 5). Every other key of the binding has a writer of its own: the
+// vault path is rebind's, the band the band verb's, the status line's flag
+// install's.
+export const BINDING_SETTING_KEYS = Object.freeze([
+  "language",
+  "active_skills",
+  "auto_inject",
+  "default_author",
+  "tags",
+]);
+
+// What a change to named plain keys would write: never a binding that does
+// not exist (a bare file of settings would read as bound), never over one
+// that does not parse.
+export function planBindingKeys(projectDir, changes, { env = process.env } = {}) {
+  const path = harnessConfigPath(projectDir, env);
+  const unknown = Object.keys(changes).filter((k) => !BINDING_SETTING_KEYS.includes(k));
+  if (unknown.length) throw new Error(`planBindingKeys: not a binding setting: ${unknown.join(", ")}`);
+  const { cfg, corrupt } = readExisting(path);
+  if (corrupt || (cfg && (typeof cfg !== "object" || Array.isArray(cfg))))
+    return { path, refusal: { code: "UNREADABLE", message: `${path} is not valid JSON — fix or remove it first` } };
+  if (!cfg) return { path, refusal: { code: "UNBOUND", message: `${projectDir} is not bound to a vault` } };
+  const keys = Object.keys(changes).filter((k) => JSON.stringify(cfg[k]) !== JSON.stringify(changes[k]));
+  const before = Object.fromEntries(keys.map((k) => [k, cfg[k]]));
+  const after = Object.fromEntries(keys.map((k) => [k, changes[k]]));
+  return { path, keys, before, after, changed: keys.length > 0 };
+}
+
+// Applies a plan: reads the binding again and sets only the planned keys, so
+// a write another writer made since the plan (the band, the flag) is kept.
+export function applyBindingKeys(plan) {
+  if (plan.refusal || !plan.changed) return { wrote: false };
+  const { cfg, corrupt } = readExisting(plan.path);
+  if (corrupt || !cfg || typeof cfg !== "object" || Array.isArray(cfg))
+    throw new Error(`${plan.path} changed since the plan and no longer reads as a binding`);
+  writeFileAtomic(plan.path, JSON.stringify({ ...cfg, ...plan.after }, null, 2) + "\n", { sweep: false });
+  return { wrote: true };
+}
+
 export const shellQuote = (s) => (/^[A-Za-z0-9_/.~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`);
 
 // A directory with no entries at all. A `.DS_Store` makes it not empty: that