projectstore-claude 0.28.0-rc.2 → 0.28.0

package/bin/projectstore-claude.mjs

@@ -76,7 +76,10 @@ if (!core) {
     // without one, so the child must see the real stdin and stdout. No
     // timeout — the child waits on a human at the preview. exitCode, not
     // exit(): the core's own bin says why (a pending write on a pipe).
-    const r = spawnSync(process.execPath, [core, ...fixed.argv], { stdio: "inherit" });
+    const r = spawnSync(process.execPath, [core, ...fixed.argv], {
+      stdio: "inherit",
+      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root },
+    });
     if (r.error) process.stderr.write(`${SHELL}: ${r.error.message}\n`);
     // A signal is relayed the shell way (128 + its number): Ctrl-C at the
     // preview is 130 here as it would be on the core itself.

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "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 an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.28.0-rc.2",
+      "version": "0.28.0",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.28.0-rc.2",
+  "version": "0.28.0",
   "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.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/README.md

@@ -4,7 +4,7 @@
 
 [![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
 
-A [Claude Code](https://claude.com/claude-code) plugin.
+A project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental).
 
 ---
 
@@ -88,6 +88,28 @@ npx projectstore-claude install --project "$PWD"
 
 The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
 
+**Codex uses its own rendered plugin root and the same one-command shape.**
+Codex support is **experimental** (see [`docs/harnesses.md`](./docs/harnesses.md)
+for what has been measured and what has not), and its shell is not published
+yet. From this checkout, exercise the exact npx path against the built tarball:
+
+```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"
+```
+
+The Codex shell carries a canonical portable manifest, namespaced workflow and
+role skills, lifecycle hooks, and the exact bundled core. It stages a stable
+marketplace under `CODEX_HOME`, drives `codex plugin marketplace add` and
+`codex plugin add`, then reads the installation back and verifies its version
+and payload digest. Restart Codex, approve the hooks, and run
+`$projectstore-bind <vault-path>`. After the first explicit npm publication,
+the shorter command is
+`npx projectstore-codex@<version> install --project "$PWD"`; use its `upgrade`
+verb for later releases. Because Codex's
+plugin registry is user-global, ordinary uninstall removes only the project's
+agents block; `uninstall --global` is the explicit machine-wide removal.
+
 The package also carries a `bin`. Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
 
 ```
@@ -119,20 +141,48 @@ npx projectstore bind ~/vaults/my-project
 npx projectstore init ~/vaults/new-project --language ru
 ```
 
-`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` on npm are this package's per-harness shells — the core pinned and bundled, the harness fixed; the Codex and opencode shells publish once their plugin roots are rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N published tarballs.
+`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` are this package's per-harness shells — the core pinned and bundled, the harness fixed. Codex's shell is experimental and stays private until a live run has exercised every surface it installs, from an installed release ([`docs/harnesses.md`](./docs/harnesses.md)). The opencode shell publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs.
 </details>
 
 ## Upgrading
 
-`/plugin update` (or auto-update) and a restart is the whole procedure. What
-an existing project sees afterwards, and why:
-
-- **The status line keeps rendering.** A launcher written by an earlier
-  version still works, but it now carries no file stamp and its embedded
-  fallback root is frozen at the old version; the startup line says so at
-  every session start until you run the fix — `/projectstore:doctor --fix` — which
-  re-stamps it. Nothing rewrites that file behind your back any more: first
-  wiring and refresh are `install`'s, behind a preview.
+`/plugin update` (or auto-update) and a restart, then one command per project
+bound before 0.28. What an existing project sees afterwards, and why:
+
+- **The project's files move to `.projectstore/`.** `.claude/projectstore.json`
+  and `.claude/.projectstore/` become `.projectstore/projectstore.json`,
+  `.projectstore/harness/claude-code.json` and `.projectstore/state/`. Nothing
+  breaks before you move them: every reader falls back to the old paths through
+  0.29, and the startup line names the command until the move is done. Close
+  every Claude Code session in the project, run that command from a terminal,
+  then restart. The command depends on how you installed:
+  - **From the git marketplace** (every 0.27.x install): the installed copy's
+    own `bin/projectstore.mjs`, with its path spelled out in the startup line —
+    `node "<plugin cache>/bin/projectstore.mjs" upgrade --harness claude-code --no-register --project "$PWD"`.
+    `--no-register` leaves your plugin registration as it is.
+  - **From npm**: `npx projectstore-claude@<version> upgrade --no-register --project "$PWD"`.
+
+  Both forms move only the project's files, so neither touches your plugin
+  registration. The same run re-stamps the status-line launcher at its new path
+  and re-registers the agents block, whose template is now v4. A plain
+  `npx projectstore-claude upgrade` on a git-marketplace install does more: it
+  also registers the plugin from npm for this checkout and turns the
+  git-marketplace copy off here, so `/plugin update` stops reaching the
+  checkout. The 0.28.0-rc.1 and rc.2 startup lines named that shell form
+  (`npx projectstore-claude@<version> upgrade`, without `--no-register`), so on
+  those, update first and run what the new startup line names. If it already
+  happened,
+  `npx projectstore-claude@<version> uninstall --surface plugin --project "$PWD"`
+  (0.28.0 or later) turns the git-marketplace copy back on. That copy must be 0.28 or later — an
+  older one reads a moved project as unbound — so update it first if it is not.
+  Restart, then run
+  `/projectstore:doctor --fix` in the new session, which re-stamps the status
+  line against that copy.
+- **The status line keeps rendering.** A launcher written by an earlier version
+  still works, but it carries no file stamp and its embedded fallback root is
+  frozen at the old version; the move above re-stamps it. Nothing rewrites that
+  file behind your back any more: first wiring and refresh are `install`'s,
+  behind a preview.
 - **`/projectstore:status` and `/projectstore:search` answer differently:**
   facts from artifact frontmatter and the derived views' freshness instead
   of an `mtime` walk; a literal, bounded, grouped search instead of a shell
@@ -144,9 +194,29 @@ an existing project sees afterwards, and why:
   a crash.
 - **The plugin registers an MCP server** (eight read-only tools over the
   vault). Claude Code may ask you to approve it once.
-- **Rolling back** to an earlier version works; that version's first session
-  overwrites the stamped launcher, and coming forward again costs the same
-  one `--fix`.
+- **The agents block stays where Claude Code reads it.** In a project with an
+  `AGENTS.md`, the block goes there and `CLAUDE.md` carries a one-line
+  `@AGENTS.md` import; otherwise the block goes into `CLAUDE.md`. A project with
+  an `AGENTS.md` and no `CLAUDE.md` now gains that one-line `CLAUDE.md`.
+- **The passive skills are published under the `projectstore-` prefix**
+  (`projectstore-decision-detector`, `projectstore-peer-reviewer`,
+  `projectstore-story-completion`, `projectstore-vault-communication`). Nothing
+  in a project names them; only a skill listing shows the new names.
+- **Rolling back** to 0.27.x before the move: everything keeps working, since
+  0.27.x still reads the old layout. It rewrites the status-line launcher in its
+  own form, as it always did; coming forward again, the startup line names the
+  move once more, and the move re-stamps the launcher. If a session already
+  re-stamped the status line or re-registered the agents block before the move
+  (rc.2's `/projectstore:doctor --fix` did both), 0.27.x reports a foreign
+  status line and a v4 block and leaves both alone — unless you run its
+  `/projectstore:agents register`, which rewrites the block; the status line
+  still renders, and the move settles both.
+- **Rolling back** to 0.27.x after the move: 0.27.x looks for its binding under
+  `.claude/`, finds none and offers `bind`. Do not accept. A re-bind writes
+  `.claude/projectstore.json` again, and 0.28's `install` and `upgrade` refuse
+  while two bindings exist. To come forward again, delete
+  `.claude/projectstore.json`, then run the command the startup line names
+  once more: a 0.27.x session writes its welcome marker back under `.claude/`.
 - **Installed from npm?** Then `/plugin update` has nothing to fetch: the
   registration is refreshed by the package itself — from a terminal outside
   the session, `npx projectstore-claude@<version> upgrade --project "$PWD"`
@@ -193,11 +263,11 @@ The deep dive — real session files, measured payloads, how every mechanism wor
 
 ## Uninstalling
 
-`/plugin uninstall projectstore@SmartAndPoint` for a git-marketplace install; `npx projectstore-claude uninstall --project "$PWD"` (from a terminal) for an npm one — it forgets the registration for this checkout, turns a silenced git copy back on, and removes the local marketplace directory only when no other checkout uses it. Your vault is yours — plain markdown, untouched. One leftover of the `/plugin` path: the agents block in `CLAUDE.md`/`AGENTS.md`. Before uninstalling, run `/projectstore:agents unregister` (which runs the core's `uninstall --surface agents_block` for this harness), or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand.
+`/plugin uninstall projectstore@SmartAndPoint` for a Claude git-marketplace install; `npx projectstore-claude uninstall --project "$PWD"` for its npm registration. For Codex, `npx projectstore-codex uninstall --project "$PWD"` removes only project-owned wiring; add `--global` only to remove the user-global Codex plugin and marketplace. Your vault is yours — plain markdown, untouched. One leftover of a host-managed plugin path can be the agents block in `CLAUDE.md`/`AGENTS.md`; remove it with the harness's agents unregister skill, or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand. `uninstall` leaves a block that lives in `AGENTS.md`, because that file is read by other coding agents too, and removes the `CLAUDE.md` import when that file holds nothing else; `uninstall --surface agents_block` removes the block as well.
 
 ## Extending
 
-See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills.
+See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills, and [`docs/harnesses.md`](./docs/harnesses.md) for which coding agents projectstore runs on — what "experimental" means there, and what adding one takes.
 
 ## Contributing
 

package/node_modules/projectstore/commands/agents.md

@@ -20,7 +20,7 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
    It renders the block from the installed plugin's template ∩ the layout's
    roster (`scaffold/layouts/<layout>.json` — only routable agents get lines;
    the entry-rule line, the instruction-conflict line, the
-   model-resolution line and the vault-communication line always stay), places it (`AGENTS.md` when it
+   model-resolution line and the vault-native communication line always stay), places it (`AGENTS.md` when it
    exists, else `CLAUDE.md`; a block in the other file is migrated, never
    duplicated; `CLAUDE.md` gets an `@AGENTS.md` import), previews every
    write, and applies because the harness is named. A current block is
@@ -28,7 +28,13 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
    prose byte-identical.
 3. A non-zero exit is a refusal — a duplicated or unclosed block, a missing
    template — relay it and stop. Never write the block with the Write or Edit
-   tool: the verb is the only writer (install spec, contract 6).
+   tool: the verb is the only writer (install spec, contract 6). One exception,
+   read from the output, not assumed: when it shows the block applied and the
+   `layout` item skipped as deferred to a terminal outside the session, the
+   exit 1 is that deferral. The block is registered — say so, and for the move
+   relay the command the startup line or `/projectstore:doctor`'s
+   `layout-legacy` finding names; never compose one. Any other non-zero exit
+   is a refusal.
 
 ## `unregister` — remove what register added
 

package/node_modules/projectstore/commands/doctor.md

@@ -21,7 +21,12 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
 2. **No findings** → done. One line: "Doctor is clean — N info note(s) above."
 
 3. **`--fix` requested** → walk the *install-side* findings only, one
-   AskUserQuestion per repair, never batched silently:
+   AskUserQuestion per repair, never batched silently. **When `layout-legacy`
+   is in the report, it goes first and its command is the one repair** for a
+   stale-launcher `surface`, a v3 `agents-block` and `agents-in-binding` as
+   well: relay it and run nothing in-session for those (see its bullet below).
+   The report already shows the v3 block, and a block Claude Code cannot see,
+   as info that points at the move.
    - `worktree-unbound` → this checkout is a git worktree of a bound one. Offer
      `/projectstore:bind --inherit`, and say what it does: copies the parent's
      binding, leaves the vault shared and unchanged, carries no session state.
@@ -32,7 +37,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    - `agents-block` duplicate or stale → show the finding, then (after approval)
      run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
      and print its output: it removes the copy in the non-preferred file and
-     keeps the preferred one current. Never Edit or Write the block yourself —
+     keeps the preferred one current. A block Claude Code cannot see — in
+     `AGENTS.md`, with no `@AGENTS.md` line in `CLAUDE.md` — is the same repair:
+     the verb adds the import. For another harness the finding names its own
+     `--harness`; relay that command. Never Edit or Write the block yourself —
      the verb is its only writer (install spec, contract 6).
    - `statusline` issues → offer running `/projectstore:statusline on|off`,
      which installs or removes the entry and the launcher behind a preview
@@ -49,7 +57,8 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    - `upgrade` (an info the SessionStart line carries, not a row of this
      report: a launcher written before file stamps existed) → in this report
      the same file is the `surface` issue above; the `upgrade` command re-stamps
-     it in one run.
+     it in one run. While `layout-legacy` is pending the startup line does not
+     carry it: the move re-stamps the launcher at its new path.
    - `surface-foreign` → **never repairable.** A file under our prefix with no
      provenance line is not ours: no `--fix` flow may edit, delete, move or
      overwrite it. Print the finding verbatim and relay its resolution — rename
@@ -63,10 +72,20 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    - `layout-legacy` (warn; the startup line carries it as an offer) → the project
      still holds the pre-0.28 layout (`.claude/projectstore.json`,
      `.claude/.projectstore/` — legacy, read through 0.29). The migration is one
-     previewed `layout` item of the `projectstore-claude` shell's `upgrade`, run
-     **from a terminal outside this session** (it moves files this session reads and writes; the verb defers
-     inside one). Relay the finding's command verbatim; never move the files
-     yourself.
+     previewed `layout` item of `upgrade`, run **from a terminal outside this
+     session** (it moves files this session reads and writes; the verb defers
+     inside one). The finding names the form for the channel this plugin was
+     installed through: the installed copy's own `bin/projectstore.mjs` for a
+     git-marketplace install or a checkout, the `projectstore-claude` shell for
+     the npm registration. Relay the finding's command verbatim and never
+     substitute the other form — the shell, run for a git-marketplace install,
+     would also move this checkout to the npm channel. When the finding carries
+     advice instead of a command — the installed copy predates the move, or
+     predates `--no-register` — relay the advice and never compose a command
+     yourself. Never move the files yourself. While this finding is in the report, its command is also the one
+     repair for a stale-launcher `surface`, a v3 `agents-block` and
+     `agents-in-binding`: do not run the in-session `install` or `upgrade` for
+     those — the deferred move makes that run stop part-way.
    - `layout-two-configs` (issue) → both `.claude/projectstore.json` (legacy) and
      `.projectstore/projectstore.json` exist: `install` and `upgrade` refuse until
      one is deleted. Show both, ask the user which is the binding they mean, and

package/node_modules/projectstore/docs/extending.md

@@ -47,7 +47,7 @@ vault-side layout or template override):
    its index and stay there.
 
 4. **Checklist entry** — `scaffold/checklists.json`, consumed by
-   `/projectstore:review` and the peer-reviewer skill. English-only by design.
+   `/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,

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

@@ -97,7 +97,7 @@ Every command that writes or edits a file goes through `AskUserQuestion`:
    One consequence the prompt tells you about: the regeneration rewrites the
    whole table, so a creation can also repair a stale row for another artifact.
 
-Skills (decision-detector, story-completion) are passive — they suggest commands; they never write directly.
+Skills (`projectstore-decision-detector`, `projectstore-story-completion`) are passive — they suggest commands; they never write directly.
 
 ## Disabling skills
 

package/node_modules/projectstore/docs/harnesses.md

@@ -0,0 +1,159 @@
+# Harnesses
+
+projectstore's engine is one package. What differs between coding agents —
+where a hook is declared, whether a subagent can be shipped, which environment
+variable names the project — lives in `harnesses/<id>.json`, one **capability
+manifest** per harness, and nowhere else. No script branches on a harness name;
+the portability suite greps for it.
+
+This page says which harnesses exist, how far each one is trusted, and what
+"experimental" means when you read it below.
+
+## Status
+
+| Harness | id | Status | Verified | Surfaces installed |
+|---|---|---|---|---|
+| Claude Code | `claude-code` | **supported** | 2026-08-30 | hooks, commands, agents, skills, MCP, status line, agents block |
+| Codex | `codex` | **experimental** | — | portable plugin, hooks, rendered workflow skills, agents block |
+
+**supported** means the manifest carries a `verified` block: a session id and a
+date on which this harness's surfaces were installed and exercised end to end,
+and the measurements in the manifest came from that run.
+
+**experimental** means `verified` is `null`. Every field that was not measured
+is absent or `null` rather than guessed. It is enough to run on; it is not enough
+to promise. An experimental harness is never the source layout. A generated
+adapter may exist while it is experimental, but its distribution shell stays
+private until the complete built artifact passes the live gate.
+
+The label is not prose. It is derived from the manifest, and
+`tests/portability.test.mjs` fails if this table and `verified` disagree.
+
+## Claude Code
+
+The **source layout**: the repository's own `hooks/`, `commands/`, `agents/`,
+`skills/` and `.mcp.json` are Claude Code's, written by hand and read directly.
+Every other harness is generated from them. Exactly one manifest may say
+`source_layout: true`, which is what keeps "the original" a single place.
+
+Config lives in `<project>/.projectstore/`, harness-neutral, shared by every
+harness in the project. The per-harness half — the agents block, which carries
+model names and those are harness-specific — is
+`<project>/.projectstore/harness/claude-code.json`.
+
+## Codex
+
+Experimental, measured on `codex-cli 0.153.4`. The initial spike captured 759
+hook firings. The 2026-09-30 gate then built the npm shell from a packed core,
+passed Codex's plugin validator, installed and upgraded it through an isolated
+`CODEX_HOME`, verified the materialised cache by version and digest, and loaded
+`$projectstore-status` in a fresh Codex session. The validator (the
+plugin-creator skill's `validate_plugin.py`) reads only
+`.codex-plugin/plugin.json`, so the canonical root `plugin.json` has not been
+validated.
+
+That run exercised one skill, not every installed surface, so `verified` stays
+`null`. The hooks are the reason it matters. On 2026-10-03 the first real
+install's cached hooks could not load the vault in any session. They were run
+by hand through `zsh -lc`; the failure did not depend on the shell form. In the
+first session the failure sat in the model's context under the welcome, which
+was all the user saw. The core had taken the shell's root for its own. That is
+fixed, and the suite now runs every rendered hook from the built shell. A live
+Codex session firing them from an installed release is still owed.
+
+How 0.153.4 starts a hook was read from its source, not measured: under the
+session's shell as `<shell> -c`, with the environment the Codex process had when
+it built the session's hooks. `$SHELL -lc` (or `/bin/sh -lc`) is the fallback
+when the hooks are built without exactly one ready local environment. So a hook
+finds `node` on the Codex process's own `PATH`, plus whatever `.zshenv` adds:
+zsh reads `.zshenv` for a `-c` command, not `.zprofile` or `.zshrc`, so a Codex
+not started from a terminal can miss a `node` that only `.zprofile` puts on
+`PATH`.
+
+The shell is not published. Build it and install the tarball through npx from
+this checkout:
+
+```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"
+```
+
+The shell package is release-gated until its first npm publication. From this
+repository, the same flow is exercised against the packed tarball. Installation
+is user-global because Codex stores marketplace registrations and plugin caches
+in `CODEX_HOME`; the agents block in `AGENTS.md` remains project-local. After
+the first explicit npm publication, the shorter registry form is
+`npx projectstore-codex@<version> install --project "$PWD"` (or `upgrade`). Ordinary
+uninstall leaves the global plugin in place; add `--global` only when you mean
+to remove it for every project.
+
+What is known, and how:
+
+- **Hooks are rendered; their live firing from an installed release is not
+  yet observed.** The canonical portable `plugin.json` selects
+  `./hooks/hooks.json` through `extensions.com.openai`; the compatibility
+  `.codex-plugin/plugin.json` stays inside the current ingestion schema. Five
+  events: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`.
+  Of the 759 captured firings, 757 came from the earlier inline form, across
+  `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop`,
+  and 2 from a file-site `hooks/hooks.json` with an absolute `node` path.
+  `PreCompact` has never been observed firing on Codex, and neither has the
+  `${PLUGIN_ROOT}` form selected through `extensions.com.openai`. The hook process
+  receives `PLUGIN_ROOT` in its environment, naming the shell's root with the
+  core beneath it in `node_modules/projectstore/`, and **no project-directory
+  variable at all**. The project comes from the payload's `cwd`, which every
+  projectstore hook adopts before it resolves anything.
+- **Trust is granted per hook, machine-wide**, and it lags: a release that
+  changes hooks may not take effect until the session after next.
+- **Source commands are not shipped.** Codex has no registrable root slash command, and
+  shipping `commands/` is actively harmful — it rewrites them into skills itself
+  and leaves `${CLAUDE_PLUGIN_ROOT}` in the body, producing entry points that
+  exit 1. They are rendered as skills instead.
+- **Roles are rendered as orchestration skills.** Codex spawns subagents through
+  its collaboration tool, not by loading a plugin's `agents/` directory. The
+  six ProjectStore roles therefore ship as namespaced skills that resolve their
+  configured model through the core and ask Codex to spawn the role. No effort
+  is forced: it inherits unless the user has configured a model policy.
+- **Multi-file edits reach the activity log and entry rule when their paths
+  are absolute.** Codex's `apply_patch` carries paths inside
+  `tool_input.command`; the shared extractor reads every `Add`, `Update`,
+  `Delete` and `Move to` path from that measured envelope field. A relative
+  path is not yet resolved against the payload's `cwd`, so it is not recorded.
+  The field name remains manifest data, not a Codex branch.
+- **MCP does not ship.** Our `.mcp.json` is in Claude Code's dialect.
+
+Codex also sets Claude Code's `CLAUDE_PLUGIN_ROOT` for compatibility. A variable
+two harnesses both set identifies neither, so both manifests demote it: it stops
+being evidence for *either* harness rather than being evidence for the first file
+in alphabetical order.
+
+## Running both over one project
+
+Nothing is shared that could collide. The binding
+(`<project>/.projectstore/projectstore.json`) is harness-neutral and one file;
+the agents block is per harness; the session state is keyed by harness id. Two
+harnesses in one project write two overlays and neither disturbs the other.
+
+Within one machine, run them in separate **git worktrees** over the same
+checkout, as parallel Claude Code sessions already do. The vault itself is a git
+repository with its own remote — that is how it syncs between people and their
+agents.
+
+## Adding a harness
+
+A harness is a manifest plus measurements, not code:
+
+1. Write `harnesses/<id>.json`. Copy the field list from an existing one; leave
+   `verified: null` and omit or null every value you have not observed. A field
+   that is `null` with a reason is a decision on the record; an absent field is
+   one someone forgot.
+2. Measure. Install it, run a real task, capture the hook payloads. The values
+   that matter first: which environment variables the hook process receives,
+   where hooks are declared, which tool writes files and where that tool puts the
+   path.
+3. Declare any variable the harness sets that belongs to another harness under
+   `runtime.shared_env`, or detection will answer with someone else's id.
+4. Add a row to the table above. It stays **experimental** until the manifest
+   carries a `verified` block — the test enforces the pairing in both directions.
+
+See [`docs/extending.md`](./extending.md) for the surfaces themselves.

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

@@ -222,7 +222,16 @@
       "format": "skill-md",
       "scope": "user",
       "scope_reason": "Claude Code loads skills from the plugin installation itself, not from a per-project directory.",
-      "registered_by": "plugin"
+      "registered_by": "plugin",
+      "frontmatter_required": [
+        "name",
+        "description"
+      ],
+      "frontmatter_reason": "`description` is what Claude Code matches a skill on; `name` was added 2026-09-08 because Codex's documentation requires it and this is the tree both harnesses load until the generator renders one per harness. Harmless here, required there.",
+      "invocation": null,
+      "invocation_reason": "UNMEASURED. Claude Code activates a skill from its description rather than from a form the user types; there is no explicit call syntax to record, and null says that rather than leaving the key out and reading as forgotten.",
+      "unrendered_source": false,
+      "unrendered_source_reason": "This IS the source tree (source_layout: true), so there is nothing to render and no foreign vocabulary to leak into it."
     },
     "hooks": {
       "supported": true,
@@ -244,6 +253,8 @@
         "AGENTS.md",
         "CLAUDE.md"
       ],
+      "reads_natively": "CLAUDE.md",
+      "reads_natively_reason": "The file this harness reads BY ITSELF. `files` is the block's placement preference and conflates two things: AGENTS.md is first because it is the cross-tool convention, but Claude Code reaches it only through the @AGENTS.md import WE install — remove the bridge and the block is invisible. So installing for this harness must leave CLAUDE.md present: holding the block when it lands here, holding the import when it lands in AGENTS.md. Measured 2026-09-09: a project with an AGENTS.md and no CLAUDE.md took the block into AGENTS.md and created no bridge, so the harness that ran the install could not see it.",
       "source": "templates/claude-md-block.md.tmpl",
       "marker": {
         "open": "<!-- projectstore:agents v",
@@ -461,9 +472,12 @@
     "",
     "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. The status line keeps rendering; the first session names the one step — `/projectstore:doctor --fix` — that re-stamps the launcher written before file stamps existed. `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. Rolling back overwrites the stamp; coming forward costs the same one `--fix`."
+    "**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."
   ],
   "agent_translation": {
-    "carries_model": true
+    "carries_model": true,
+    "cheap_model": "sonnet",
+    "cheap_model_evidence": "measured",
+    "cheap_model_reason": "The model the clerk is pinned to when a strong default would otherwise lift it (ADR-008). A literal here, in the one file allowed to name a harness's vocabulary; it used to be a literal in scripts/cli.mjs, which made `agents configure --harness codex` write an Anthropic model name into a Codex overlay. MEASURED in the sense that matters: this is the model the clerk has been running on since ADR-008, in this repository, and tests/overlay.test.mjs asserts the pin end to end."
   }
 }