projectstore-claude 0.28.0-rc.3 → 0.28.0

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.3",
+      "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.3",
+  "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

@@ -168,9 +168,14 @@ bound before 0.28. What an existing project sees afterwards, and why:
   `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. If that already happened,
+  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"`
-  turns the git-marketplace copy back on. Restart, then run
+  (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
@@ -197,6 +202,15 @@ bound before 0.28. What an existing project sees afterwards, and why:
   (`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

package/node_modules/projectstore/commands/agents.md

@@ -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

@@ -25,6 +25,8 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
    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.
@@ -35,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
@@ -74,8 +79,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
      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. Never move the files
-     yourself. While this finding is in the report, its command is also the one
+     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.

package/node_modules/projectstore/docs/harnesses.md

@@ -45,20 +45,30 @@ model names and those are harness-specific — is
 
 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 the Codex plugin validator, installed and upgraded it through an isolated
+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.
+`$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`: that machine's default shell, started the way Codex's
-command runner starts a hook on its main branch (`<default shell> -lc`). That
-0.153.4 does the same is not confirmed. 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.
+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:

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

@@ -472,7 +472,7 @@
     "",
     "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. 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 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,

package/node_modules/projectstore/harnesses/codex.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30.",
+  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30. The validator reads only .codex-plugin/plugin.json; the canonical root plugin.json has not been validated.",
   "id": "codex",
   "display_name": "Codex",
   "emit": true,
@@ -7,7 +7,7 @@
   "output_dir": "adapters/codex",
   "docs": "https://developers.openai.com/codex/",
   "verified": null,
-  "verified_reason": "Null, restored 2026-10-03. docs/harnesses.md calls a harness supported only when every installed surface has been exercised end to end, and contract 16 of the generation spec (Generated harness surfaces: manifests, the generator and the three invariants) derives that label from this field. The 2026-09-30 run (session 01a0f079-7ecd-7331-95a9-2471def3cb22) exercised one surface: a fresh `codex exec` session loaded projectstore-status from the materialised cache. The hooks were not exercised, and the first real install showed why that matters. Its cached hooks, run by hand through `zsh -lc` (that machine's default shell, started as Codex's runner on its main branch starts a hook, `<default shell> -lc`; unconfirmed on 0.153.4), could not load the vault in any session; in the first, the failure sat beneath the welcome. The core had taken the shell's root for its own. That is fixed and pinned by a test that runs every rendered hook from the built shell. This block is set by a live run that exercises every installed surface: the hooks once registration has settled, including PreCompact, and the skill flows.",
+  "verified_reason": "Null, restored 2026-10-03. docs/harnesses.md calls a harness supported only when every installed surface has been exercised end to end, and contract 16 of the generation spec (Generated harness surfaces: manifests, the generator and the three invariants) derives that label from this field. The 2026-09-30 run (session 01a0f079-7ecd-7331-95a9-2471def3cb22) exercised one surface: a fresh `codex exec` session loaded projectstore-status from the materialised cache. The hooks were not exercised, and the first real install showed why that matters. Its cached hooks, run by hand through `zsh -lc` (a form the failure did not depend on: read from source, 0.153.4 runs a hook as `<session shell> -c` with the Codex process's environment, and `$SHELL -lc` only as a fallback), could not load the vault in any session; in the first, the failure sat beneath the welcome. The core had taken the shell's root for its own. That is fixed and pinned by a test that runs every rendered hook from the built shell. This block is set by a live run that exercises every installed surface: the hooks once registration has settled, including PreCompact, and the skill flows.",
   "runtime": {
     "detect_env": [
       "PLUGIN_ROOT",

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.28.0-rc.3",
+  "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.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/doctor.mjs

@@ -60,6 +60,7 @@ import {
   lastVaultActivityMs,
   ENTRY_IGNORE,
   AGENTS_BLOCK_OPEN_SRC,
+  AGENTS_BLOCK_CLOSE,
   agentsBlockVersion,
   findAgentsBlock,
   statusLineLauncherPath,
@@ -75,8 +76,11 @@ import {
   hostSettingsPath,
   readOverlayAt, layoutRoster,
   installChannel,
+  cmpPrecedence,
+  cmpVersion,
+  blockVisibleTo,
 } from "./lib.mjs";
-import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness, detectHarnesses, configPath as harnessConfigPath, packageCommand } from "./harness.mjs";
+import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness, detectHarnesses, identifiedHarnessId, configPath as harnessConfigPath, packageCommand } from "./harness.mjs";
 
 // A remedy used to interpolate the surface's harness variable here. It cannot:
 // measured 2026-09-06, NO harness gives its Bash tool that variable, and a
@@ -387,9 +391,14 @@ export function checkPendingUpgrade(proj, home = homedir(), root = pluginRoot())
     relative(proj, lp))];
 }
 
-export function checkAgentsBlock(proj) {
+// The two findings the layout move itself repairs carry what they say without
+// their remedy, so a pending move can name itself instead (foldIntoMove).
+const moveRepairs = (f, fact) => ({ ...f, byMove: fact });
+
+export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot() } = {}) {
   const out = [];
   const AGENT_BLOCK_VERSION = agentsBlockVersion();
+  const texts = {};
   // One parser for every reader (findAgentsBlock): its count is the loose one,
   // so a good block plus a re-wrapped marker in one file is "more than once"
   // here exactly as install and uninstall see it (both refuse), never a quiet
@@ -397,6 +406,7 @@ export function checkAgentsBlock(proj) {
   // registered" is the reading that makes install append a second block.
   let blocks = 0;
   let wrappedFiles = 0;
+  let unclosedFiles = 0;
   const perFile = {};
   const staleVersions = [];
   for (const name of ["CLAUDE.md", "AGENTS.md"]) {
@@ -404,6 +414,7 @@ export function checkAgentsBlock(proj) {
     if (!existsSync(p)) continue;
     let text;
     try { text = readFileSync(p, "utf8"); } catch { continue; }
+    texts[name] = text;
     const f = findAgentsBlock(text);
     if (!f) continue;
     perFile[name] = f.count;
@@ -414,6 +425,13 @@ export function checkAgentsBlock(proj) {
         `${name}:${f.line}: the projectstore:agents open marker does not close on its own line — put \`-->\` back on the marker's line, then run /projectstore:agents register (install and uninstall refuse until it does).`, name));
       continue;
     }
+    if (f.unclosed) {
+      // Named here as the wrapped marker is, so the startup count carries it:
+      // the agents-block plan refuses it, and the layout move with it.
+      unclosedFiles++;
+      out.push(finding("install", "issue", "agents-block",
+        `${name}: the projectstore:agents block opens and never closes — close it with \`${AGENTS_BLOCK_CLOSE}\` or delete the half block, then run /projectstore:agents register (install and uninstall refuse until then).`, name));
+    }
     for (const m of text.matchAll(AGENT_BLOCK_MARKER)) {
       const v = parseInt(m[1], 10);
       if (v !== AGENT_BLOCK_VERSION) staleVersions.push({ file: name, v });
@@ -427,25 +445,75 @@ export function checkAgentsBlock(proj) {
     // One block in each file is a state install resolves (it keeps the
     // preferred file's); two in one file is not, and stays an issue — and a
     // wrapped marker anywhere means install refuses, so the "both files"
-    // advice is withheld while one is wrapped.
+    // advice is withheld while one is wrapped or never closes.
     const twiceInOne = Object.entries(perFile).find(([, n]) => n > 1);
     if (twiceInOne) {
       out.push(finding("install", "issue", "agents-block",
         `${twiceInOne[0]} carries the projectstore:agents block ${twiceInOne[1]} times — keep exactly one; install refuses until it does.`, twiceInOne[0]));
-    } else if (wrappedFiles) {
+    } else if (wrappedFiles || unclosedFiles) {
       // already named above, file by file
     } else {
       out.push(finding("install", "warn", "agents-block",
         `The projectstore:agents block is in both CLAUDE.md and AGENTS.md — run /projectstore:agents register: install keeps the one in ${(sourceHarness()?.surfaces?.agents_block?.files || ["AGENTS.md"])[0]} and removes the other.`));
     }
   }
+  // A state the agents-block plan refuses — a wrapped marker, a block that
+  // never closes, a block twice in one file — refuses the move with it, so
+  // nothing here is the move's to repair while one stands.
+  const refuses = wrappedFiles > 0 || unclosedFiles > 0 || Object.values(perFile).some((n) => n > 1);
   for (const s of staleVersions) {
-    out.push(finding("install", "issue", "agents-block",
-      `Agents block in ${s.file} is v${s.v}, expected v${AGENT_BLOCK_VERSION} — re-run /projectstore:agents register.`, s.file));
+    const fact = `Agents block in ${s.file} is v${s.v}, expected v${AGENT_BLOCK_VERSION}`;
+    const f = finding("install", "issue", "agents-block", `${fact} — re-run /projectstore:agents register.`, s.file);
+    out.push(refuses ? f : moveRepairs(f, fact));
+  }
+  // Placement, held to the predicate install plans from (the install spec,
+  // contract 6 as amended after the rc.3 tag): one well-formed block, seen by
+  // every harness the project uses. rc.1 and rc.2 left a block in an
+  // AGENTS.md-only project with no CLAUDE.md, so Claude Code saw nothing, and
+  // nothing said so. Used means detected by directory, or identified from the
+  // environment — never the source harness a terminal run falls back to, so a
+  // Codex-only project hears nothing about CLAUDE.md (contract 16). An issue
+  // for the harness that identified itself, a warning for one only detected.
+  const blockFile = blocks === 1 && !refuses ? Object.keys(perFile)[0] : null;
+  if (blockFile) {
+    const identified = identifiedHarnessId(env);
+    const used = new Set([...detectHarnesses(proj).map((d) => d.id), ...(identified ? [identified] : [])]);
+    for (const id of used) {
+      const m = loadHarness(id);
+      if (!m || blockVisibleTo(m, blockFile, texts)) continue;
+      const ab = m.surfaces.agents_block;
+      const why = (ab.files || []).includes(blockFile)
+        ? `${ab.reads_natively} does not import it (\`@${blockFile}\`)`
+        : `it reads ${(ab.files || []).join(" and ")} only`;
+      const fact = `The projectstore:agents block is in ${blockFile}, which ${m.display_name} does not see: ${why}`;
+      // The resolved-root form the surface remedy uses: the running copy's own bin.
+      const remedy = `install the block for ${m.display_name}: node "${join(root, "bin", "projectstore.mjs")}" install --harness ${id} --surface agents_block --project "${proj}"`;
+      const f = finding("install", id === identified ? "issue" : "warn", "agents-block", `${fact} — ${remedy}.`, blockFile);
+      // The layout's harness is the one the move's command installs for, so the
+      // move plans this import; another harness's is not the move's to repair.
+      out.push(id === sourceHarness()?.id ? moveRepairs(f, fact) : f);
+    }
   }
   return out;
 }
 
+// While the layout move is pending, the findings the move itself repairs fold
+// into it instead of being counted beside it (the layout spec, contract 7 as
+// amended after the rc.3 tag; the upgrade story's O1): the stale block, which
+// the move re-registers, and the block's invisibility to the layout's
+// harness, whose import the move plans. Nothing else folds — a block twice in
+// one file, one that never closes or a wrapped marker makes the agents-block
+// plan refuse, which blocks the move itself. The message points at the layout
+// finding rather than computing its command again. The tag is internal: no
+// finding leaves here carrying it.
+export function foldIntoMove(findings) {
+  const layout = findings.find((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
+  const step = layout && (layout.check === "layout-two-configs"
+    ? "delete the binding the layout-two-configs finding names, then run the layout move, which repairs this"
+    : "the layout move repairs this: run what the layout-legacy finding names");
+  return findings.map(({ byMove, ...f }) => (byMove && layout ? { ...f, level: "info", message: `${byMove} — ${step}.` } : f));
+}
+
 // Both scopes are walked. The original reason ("project > user > plugin, so a
 // copy in either scope shadows the bundle") turned out to be wrong — a copy
 // shadows NOTHING, because plugin agents register under a scoped id and copies
@@ -509,8 +577,10 @@ export async function checkHarnessSurfaces(_cfg, proj, { home = homedir(), root
       }
     } else if (s.surface === "agents_block") {
       // Version drift and duplicates are checkAgentsBlock's; what only the
-      // state knows is content that differs at the same version, and a block
-      // that never closes.
+      // state knows is content that differs at the same version. A block that
+      // never closes is named by both: checkAgentsBlock carries it to the
+      // startup line, and the state names it with the file's own reason, as a
+      // wrapped marker already was.
       if (s.state === "unparseable") {
         out.push(finding("install", "issue", "surface", `${where} — ${s.reason}`, where));
       } else if (s.state === "ours-stale" && /content differs|migrates/.test(s.reason || "")) {
@@ -590,13 +660,38 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
 // itself); a competing copy enabled beside ours → an issue (two enabled copies
 // of one plugin); a competitor alone → an info naming the npm path; foreign →
 // never repairable; the host CLI missing → an info.
-export function checkPluginRegistration(proj, states = []) {
+export function checkPluginRegistration(proj, states = [], { home = homedir() } = {}) {
   const out = [];
   for (const s of states.filter((x) => x.kind === "registration")) {
     // The shell form when the manifest names a shell (contract 12): the
     // command a user can paste, built in one place.
     const h = loadHarness(s.harness) || { id: s.harness };
     const refresh = packageCommand(h, "upgrade", { version: s.pkg || "latest", args: `--surface ${s.surface} --project "${proj}"` });
+    // A copy this registration silenced for the checkout and the checkout
+    // still holds off, one per key (the install spec, contract 13 as amended
+    // after the rc.3 tag): rc.1 and rc.2's startup offer left exactly this on
+    // git-marketplace projects, and nothing said so. Only for a registration
+    // this checkout holds; the record lives in our directory, so a directory
+    // removed by hand takes it along and leaves nothing to name.
+    if ((s.silenced || []).length && (s.state === "current" || s.state === "stale")) {
+      // The row this checkout loads: its own local-scope row first, then a
+      // user-scope one — never another checkout's (layoutRemedy's rule).
+      const real = (x) => { try { return realpathSync.native(x); } catch { return resolve(x); } };
+      const here = real(proj);
+      const rows = installedPluginEntries(home, proj).filter((e) => e.present && (!e.projectPath || real(e.projectPath) === here));
+      for (const key of s.silenced) {
+        const row = rows.filter((e) => e.key === key).sort((a, b) => Number(Boolean(b.projectPath)) - Number(Boolean(a.projectPath)))[0];
+        if (!row) {
+          out.push(finding("install", "info", "plugin-registration", `${key} is held off in this checkout's local settings, where the npm registration turned it off — and that copy is no longer installed, so the entry is stale.`, s.path));
+          continue;
+        }
+        // The release line, not the build: a 0.28 release candidate reads a
+        // moved project; 0.27.x reads it as unbound. No version reads as old.
+        const old = !row.version || cmpVersion(row.version, "0.28.0") < 0;
+        out.push(finding("install", "info", "plugin-registration",
+          `${key} (${row.version || "no version recorded"}) is off for this checkout: the npm registration turned it off when it registered, so the checkout no longer loads that copy and a /plugin update no longer reaches the project. ${old ? "Update that copy first — 0.27.x reads a moved project as unbound. " : ""}To go back to it: from a terminal outside the session, ${packageCommand(h, "uninstall", { version: s.pkg || "latest", args: `--surface ${s.surface} --project "${proj}"` })}, restart, then /projectstore:doctor --fix. If moving to npm was meant, ignore this.`, s.path));
+      }
+    }
     const others = (s.others || []).map((o) => `${o.key} (${o.version || "?"})`).join(", ");
     if (s.state === "foreign") {
       out.push(finding("install", "issue", "plugin-registration-foreign", `${s.reason} — install, uninstall and upgrade refuse it; nothing repairs it.`, s.path));
@@ -770,6 +865,21 @@ export function checkLayout(proj, harness = sourceHarness(), { level = "warn", r
 // the move never needs the registration, so a misread channel can cost a
 // launcher stamp but never a channel switch. A copy that predates the move
 // (no bin/projectstore.mjs — 0.27.x) cannot run it: update that copy first.
+// Nor can one whose CLI predates --no-register (takesNoRegister).
+//
+// Whether a registry copy can run the command named for it. `--no-register`
+// arrived in 0.28.0-rc.3, and rc.1 and rc.2 parse strictly, so the command
+// exits 2 on the flag and writes nothing (the layout spec, contract 12 as
+// amended after the rc.3 tag). Read from the copy's own parse table, never
+// from its version: a never-published 0.28.0 build ranks above rc.3 and lacks
+// the flag, while a copy labelled rc.2 taken from main at 418448e has it. A
+// file read, because this runs in the SessionStart subset: never an import()
+// of the copy, never a spawn. Add files to the read, never drop cli.mjs:
+// released copies keep their parse there.
+export function takesNoRegister(copy) {
+  try { return readFileSync(join(copy, "scripts", "cli.mjs"), "utf8").includes('"no-register"'); } catch { return false; }
+}
+
 export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harness = sourceHarness(), env = process.env } = {}) {
   // A session under a relocated host home hands it on: a terminal without it
   // would classify the copy as a checkout, render no launcher and never clear
@@ -790,10 +900,22 @@ export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harn
     .filter((e) => e.present && e.enabled && (!e.projectPath || mine(e)))
     .sort((a, b) => (Number(mine(b)) - Number(mine(a))) || (b.at - a.at))[0];
   if (copy) {
+    const v = copy.version ? ` (${copy.version})` : "";
     if (!existsSync(join(copy.path, "bin", "projectstore.mjs"))) {
-      return { advice: `This project's projectstore plugin${copy.version ? ` (${copy.version})` : ""} predates the move and cannot run it: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
+      return { advice: `This project's projectstore plugin${v} predates the move and cannot run it: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
+    }
+    // Chosen first, gated after: the copy is what the project runs, so an
+    // incapable one gets advice even beside a capable user-scope copy.
+    const viaRegistration = installChannel(copy.path, { home, harness }) === "registration";
+    if (!takesNoRegister(copy.path)) {
+      return { advice: viaRegistration
+        // Its channel's ordinary refresh, at the running version: the plain
+        // upgrade re-registers from npm — not a switch for an npm project — and
+        // moves the project in the same run.
+        ? `This project's projectstore plugin${v} is the npm registration's copy and predates --no-register, so it cannot run the move as named: refresh that registration, which moves the project too, from a terminal outside the session: ${prefix}${packageCommand(harness, "upgrade", { version: pluginVersion(root) || "latest", args: `--project "${proj}"` })}`
+        : `This project's projectstore plugin${v} predates --no-register and cannot run the move as named: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
     }
-    return installChannel(copy.path, { home, harness }) === "registration" ? shell(copy.version) : own(copy.path);
+    return viaRegistration ? shell(copy.version) : own(copy.path);
   }
   return channel === "package" ? shell(pluginVersion(root)) : own(root);
 }
@@ -865,16 +987,6 @@ export function checkVaultGit(cfg) {
     "Vault is not a git repository — the knowledge has no history/blame/review. Consider `git init` (doctor --fix offers it).")];
 }
 
-function versionNewer(a, b) {
-  const pa = String(a).split(".").map(Number);
-  const pb = String(b).split(".").map(Number);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const x = pa[i] || 0, y = pb[i] || 0;
-    if (x !== y) return x > y;
-  }
-  return false;
-}
-
 // Marketplace auto-update (maintainer request 2026-07-03): third-party
 // marketplaces do NOT auto-update by default, so a stale plugin looks like
 // "the feature is broken". Read the real registries and, when the flag is
@@ -948,7 +1060,8 @@ export function checkAutoUpdate(home = homedir()) {
     const latest = (catalog.plugins || []).find((p) => p.name === name)?.version;
     const running = (named && named.version)
       || JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8")).version;
-    if (latest && running && versionNewer(latest, running)) {
+    // Precedence, not the triple: a session on 0.28.0-rc.3 hears that 0.28.0 is out.
+    if (latest && running && cmpPrecedence(latest, running) > 0) {
       out.push(finding("install", "warn", "auto-update",
         `A newer ${name} is available: v${latest} (running v${running}) — run /plugin marketplace update ${marketplace}, then /reload-plugins.`));
     }
@@ -1852,7 +1965,7 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
     ...checkLayoutTemplates(cfg),
     ...checkHooksAlive(cfg),
     ...checkStatusline(cfg, proj),
-    ...checkAgentsBlock(proj),
+    ...checkAgentsBlock(proj, { env: opts.env, root: opts.root }),
     ...checkOverrideCopies(proj),
     ...checkEnvModel(),
     ...checkEnvEffort(),
@@ -1867,9 +1980,9 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
   let read = null;
   try { read = await readSurfaceStates(proj, opts); } catch {} // reported as a warn by checkHarnessSurfaces
   out.push(...await checkHarnessSurfaces(cfg, proj, { ...opts, read }));
-  if (read) out.push(...checkPluginRegistration(proj, read.result.states));
+  if (read) out.push(...checkPluginRegistration(proj, read.result.states, { home: opts.home }));
   if (read) out.push(...checkVersionDrift(opts.home, read.result.states, proj));
-  return out;
+  return foldIntoMove(out);
 }
 
 export function runVaultChecks(cfg) {
@@ -1932,24 +2045,26 @@ export function runStartupChecks(cfg, proj, budgetMs = 150) {
   ];
   const findings = [];
   for (const step of steps) {
-    if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings };
+    if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings: foldIntoMove(findings) };
     try { findings.push(...step()); } catch {}
   }
+  // The findings the move repairs are not counted beside it (foldIntoMove).
+  const settled = foldIntoMove(findings);
   // While the move is pending, the re-stamp is not a step of its own: the move
   // re-stamps the launcher at its new path (the layout spec, contract 7 as
   // amended 2026-10-03), and an in-session `doctor --fix` would write that
   // launcher and then stop at the deferred move with exit 1. So the line names
   // one step, and says what it covers when the dropped offer would have fired.
-  const movePending = findings.some((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
-  const restamp = findings.some((f) => f.level === "info" && f.check === "upgrade");
-  const offers = findings
+  const movePending = settled.some((f) => f.check === "layout-legacy" || f.check === "layout-two-configs");
+  const restamp = settled.some((f) => f.level === "info" && f.check === "upgrade");
+  const offers = settled
     .filter((f) => f.level === "info" && OFFER_CHECKS.has(f.check) && !(movePending && f.check === "upgrade"))
     .map((f) => (movePending && restamp && f.check === "layout-legacy" ? `${f.message} The same run re-stamps the status line launcher.` : f.message));
   return {
     skipped: false,
-    count: findings.filter((f) => f.level === "issue").length,
+    count: settled.filter((f) => f.level === "issue").length,
     offers,
-    findings,
+    findings: settled,
   };
 }
 

package/node_modules/projectstore/scripts/harness.mjs

@@ -120,7 +120,49 @@ export function detectHarnessId(env = process.env, dir = MANIFEST_DIR) {
 function detect(env, dir) {
   const forced = env.PROJECTSTORE_HARNESS;
   if (forced && loadHarnesses(dir).has(forced)) return forced;
+  const best = ranked(env, dir);
+  // A strong signal is the harness identifying itself, and it decides.
+  if (best && best.strong) return best.id;
 
+  // Only weak signals. That is not enough to switch harness: the project
+  // itself carries better evidence — whichever harness directory is present
+  // in it is the harness this project is used from. (Until 2026-09-06 the
+  // evidence was "which harness directory holds our config"; the binding is
+  // harness-neutral now and carries no such signal.)
+  const cwd = process.cwd();
+  for (const m of loadHarnesses(dir).values()) {
+    const d = m.runtime?.harness_dir;
+    if (d && existsSync(join(cwd, d))) return m.id;
+  }
+  if (best) return best.id;
+  const src = sourceHarness(dir);
+  return src ? src.id : null;
+}
+
+// The harness that identifies ITSELF from the environment, or null: a strong
+// signal (its own plugin-root or project-dir variable, not one another
+// harness shares), or its session marker — runtime.session_env, which a Bash
+// tool inside a session carries while the variables a hook receives are
+// absent (measured 2026-09-05). Never the weak ranking, never the cwd's
+// directory, never the source harness detectHarnessId falls back to. A
+// finding that must not fire for a harness the project only might use asks
+// this (the install spec, contract 6 as amended after the rc.3 tag).
+export const IDENTIFIED_ENV = "PROJECTSTORE_IDENTIFIED";
+export function identifiedHarnessId(env = process.env, dir = MANIFEST_DIR) {
+  const forced = env.PROJECTSTORE_HARNESS;
+  if (forced && loadHarnesses(dir).has(forced)) return forced;
+  // A parent of ours decided before it named the project in the harness's own
+  // vocabulary (childEnv), so its answer stands — an empty one included.
+  if (env[IDENTIFIED_ENV] !== undefined) return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
+  const best = ranked(env, dir);
+  if (best && best.strong) return best.id;
+  for (const m of loadHarnesses(dir).values()) {
+    if ((m.runtime?.session_env || []).some((k) => env[k])) return m.id;
+  }
+  return null;
+}
+
+function ranked(env, dir) {
   // Explicit plugin-root/home variables beat merely-present ones: a shell that
   // exports CODEX_HOME globally should not make a Claude Code session read as
   // Codex when Claude Code also handed us CLAUDE_PLUGIN_ROOT.
@@ -168,22 +210,7 @@ function detect(env, dir) {
     const rank = (strongHits > 0 ? 1e6 : 0) + strongHits * 1e3 + weakHits;
     if (!best || rank > best.rank) best = { id: m.id, rank, strong: strongHits > 0 };
   }
-  // A strong signal is the harness identifying itself, and it decides.
-  if (best && best.strong) return best.id;
-
-  // Only weak signals. That is not enough to switch harness: the project
-  // itself carries better evidence — whichever harness directory is present
-  // in it is the harness this project is used from. (Until 2026-09-06 the
-  // evidence was "which harness directory holds our config"; the binding is
-  // harness-neutral now and carries no such signal.)
-  const cwd = process.cwd();
-  for (const m of loadHarnesses(dir).values()) {
-    const d = m.runtime?.harness_dir;
-    if (d && existsSync(join(cwd, d))) return m.id;
-  }
-  if (best) return best.id;
-  const src = sourceHarness(dir);
-  return src ? src.id : null;
+  return best;
 }
 
 // Test seam: the detected id is memoised for the process; a test that changes
@@ -474,6 +501,11 @@ export function configPath(projectDir, env = process.env) {
 export function childEnv(base = process.env, { projectRoot: root, pluginRoot: plugin } = {}) {
   const out = { ...base };
   const r = activeHarness(base)?.runtime || {};
+  // Who called is decided here, before the project is named below: a
+  // project-dir variable we write would otherwise read, in the child, as the
+  // harness identifying itself — a terminal `doctor` took Claude Code for the
+  // session's own harness (the review of the post-rc.3 fixes, 2026-10-04).
+  if (base[IDENTIFIED_ENV] === undefined) out[IDENTIFIED_ENV] = identifiedHarnessId(base) || "";
   if (r.project_dir_env && root) out[r.project_dir_env] = root;
   // A caller that runs its own copy of the core (the npm bin) names it, so a
   // child never resolves templates or its version from a sibling install.

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -67,7 +67,7 @@ import { loadHarness, loadHarnesses, harnessIds, sourceHarness, detectHarnesses,
 import { FOREIGN_TEXT, GRAMMAR_VERSION } from "./provenance.mjs";
 import { analyseBlock, analyseJsonEntry, analyseStampedFile, analyseRegistration, analysePortableRegistration, analyseLayout, isOurFile, readText } from "./surfaces.mjs";
 import { payloadFiles, renderPortableCatalog } from "./portable-registration.mjs";
-import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpVersion, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder } from "./lib.mjs";
+import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpPrecedence, importsLine, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder } from "./lib.mjs";
 
 import { GENERATOR } from "./surfaces.mjs";
 export { GENERATOR };
@@ -112,7 +112,7 @@ function planAgentsBlock(ctx, key, s) {
   const items = [];
   if (a.refusal) return [{ surface: key, kind: "shared", path: a.files[0].path, entry: "projectstore:agents", state: "refused", action: "refuse", reason: a.refusal }];
 
-  const hasImport = (text) => String(text ?? "").split("\n").some((l) => l.trim() === importLine);
+  const hasImport = (text) => importsLine(text, importLine);
   // A CLAUDE.md that is nothing but the import registration added is ours to
   // delete when the block goes (ADR-002 decision 4); anything else stays.
   const onlyImport = (text) => String(text ?? "").split("\n").every((l) => !l.trim() || l.trim() === importLine);
@@ -256,7 +256,7 @@ function planAgentsBlock(ctx, key, s) {
     const rewrite = items.find((i) => i.action === "remove" && i.path === e.path);
     // An absent native file is empty text, not a reason to skip: it is created.
     const text = rewrite ? rewrite.after : (e.present ? e.text : "");
-    if (typeof text !== "string" || text.split("\n").some((l) => l.trim() === line)) continue;
+    if (typeof text !== "string" || importsLine(text, line)) continue;
     const after = line + "\n" + (text.startsWith("\n") || !text.trim() ? "" : "\n") + text;
     if (rewrite) { rewrite.after = after; rewrite.deleteIfEmpty = false; rewrite.reason += `; ${line} import added`; }
     else items.push({ surface: `${key}_import`, kind: "shared", path: e.path, entry: line, state: "ours-absent", action: e.present ? "add" : "create",
@@ -455,7 +455,7 @@ function planRegistration(ctx, key, s) {
     // pack → install → fix → pack loop never bumps it. The host will not
     // re-copy at an equal version (measured), so that refresh is uninstall + install.
     const sameVersionDiffers = a.contentDiffers === true;
-    const rewrite = !a.dir.present || (cmpVersion(a.dir.pkg, a.pkg) < 0) || a.dir.digestOk === false || sameVersionDiffers;
+    const rewrite = !a.dir.present || (cmpPrecedence(a.dir.pkg, a.pkg) < 0) || a.dir.digestOk === false || sameVersionDiffers;
     const disabled = [...new Set([...a.dir.disabled, ...a.others.map((o) => o.key)])];
     const digest = rewrite ? packageDigest(root) : (a.dir.prov?.digest || null);
     const files = digest ? digest.count : 0;
@@ -596,7 +596,7 @@ export function plan(projectDir, { harnesses = [], mode = "install", env = proce
   // once whatever --surface names — planned first, so every surface below is
   // planned against the new paths; its cleanup is planned last (below).
   const layoutHarness = loadHarness(ids.find((id) => { const p = layoutPaths(projectDir, { harnessDir: loadHarness(id).runtime?.harness_dir || null }); return existsSync(p.legacy.binding) || existsSync(p.legacy.runtime); }) || ids[0]);
-  const layoutCtx = { projectDir, mode, env, home, root, harness: layoutHarness, incomplete: false };
+  const layoutCtx = { projectDir, mode, env, home, root, harness: layoutHarness, incomplete: false, surfaces };
   const layout = planLayout(layoutCtx);
   for (const item of layout.first) out.items.push({ harness: layoutHarness.id, ...item });
   if (layoutCtx.incomplete) out.incomplete = true;
@@ -691,7 +691,12 @@ function planLayout(ctx) {
   const base = { surface: "layout", kind: "layout", path: P.legacy.binding, entry: null, state: a.state, reason: null };
   if (mode === "uninstall") {
     // Disowning: the legacy runtime directory goes with the new one when it is
-    // ours (its header); the legacy binding is bind's, never uninstall's.
+    // ours (its header); the legacy binding is bind's, never uninstall's. A
+    // narrowed uninstall leaves it alone: the way back from an npm switch is
+    // `uninstall --surface plugin`, and it deleted a not-yet-moved project's
+    // sessions, log and the launcher its status line still ran (the critic's
+    // fourth pass, 2026-10-04). `surfaces` is null when nothing was named.
+    if (ctx.surfaces) return none;
     if (!a.legacy.runtime || !a.legacy.runtimeOurs) return none;
     return { first: [], last: [{ ...base, surface: "layout_cleanup", path: P.legacy.runtime, state: "legacy", action: "remove", reason: "the legacy runtime directory is ours (its .gitignore header) and goes with the state", steps: [
       { kind: "remove-legacy-runtime", path: P.legacy.runtime, why: "the pre-0.28 state directory, removed whole" },
@@ -714,7 +719,7 @@ function planLayout(ctx) {
   const last = [];
   if (a.legacy.launcher || a.legacy.runtime) {
     const cleanup = [];
-    if (a.legacy.launcher) cleanup.push({ kind: "remove-legacy-launcher", path: P.legacy.launcher, why: "removed once the new launcher is written and the settings entry names it — or at once when the status-line slot is not ours (foreign, or empty because the status line is off); kept if anything still points at it" });
+    if (a.legacy.launcher) cleanup.push({ kind: "remove-legacy-launcher", path: P.legacy.launcher, why: "removed once the new launcher is written and the settings entry names it — or at once when the status-line slot is not ours (foreign, or empty because the status line is off); kept while a settings file the host reads (this project's local or committed settings, or the user's) still runs it as the status line — a script that calls it indirectly is not seen" });
     if (a.legacy.runtime) cleanup.push({ kind: "rmdir-legacy", path: P.legacy.runtime, why: "the emptied pre-0.28 runtime directory" });
     last.push({ ...base, surface: "layout_cleanup", path: P.legacy.runtime, state: "legacy", action: "cleanup", reason: null, steps: cleanup });
   }
@@ -767,7 +772,7 @@ function applyLayout(p, i, { failed, home = homedir() }) {
         if (text === null) out.steps.push({ kind: st.kind, ok: true, removed: false });
         else if (!moved && slotOurs) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "no launcher at the new path yet (this root does not produce one) — left in place" });
         else if (!isOurFile(text)) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "not ours — left in place" });
-        else if (named) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "the settings entry still names it — left in place" });
+        else if (named) out.steps.push({ kind: st.kind, ok: true, removed: false, reason: "a settings file the host reads still runs it as the status line — left in place" });
         else out.steps.push({ kind: st.kind, ok: true, removed: removeInside(st.path, within) });
       }
       else if (st.kind === "rmdir-legacy") {

package/node_modules/projectstore/scripts/lib.mjs

@@ -318,6 +318,9 @@ export function claudeHome(home = homedir()) {
   return harnessAgentHome(process.env, home);
 }
 
+// The release triple only: 0.28.0-rc.2 and 0.28.0 compare equal. Right for
+// "which release line" (the layout window's sunset); wrong for "which build is
+// newer" — that is cmpPrecedence.
 export function cmpVersion(a, b) {
   const A = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
   const B = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
@@ -325,6 +328,33 @@ export function cmpVersion(a, b) {
   return 0;
 }
 
+// Semver 2.0 precedence: 0.28.0-rc.2 < 0.28.0-rc.3 < 0.28.0. A registration
+// made at a release candidate read as current against the release while the
+// comparison stopped at the triple, so `upgrade` never refreshed it (the
+// critic's probe, 2026-10-03). Build metadata (`+…`) never ranks.
+export function cmpPrecedence(a, b) {
+  const parse = (v) => {
+    const s = String(v || "0").split("+")[0];
+    const dash = s.indexOf("-");
+    return { core: (dash < 0 ? s : s.slice(0, dash)).split(".").map((n) => parseInt(n, 10) || 0), pre: dash < 0 ? [] : s.slice(dash + 1).split(".") };
+  };
+  const A = parse(a), B = parse(b);
+  for (let i = 0; i < 3; i++) if ((A.core[i] || 0) !== (B.core[i] || 0)) return (A.core[i] || 0) - (B.core[i] || 0);
+  // A release outranks every candidate for it.
+  if (!A.pre.length || !B.pre.length) return B.pre.length - A.pre.length;
+  for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
+    if (i >= A.pre.length) return -1;
+    if (i >= B.pre.length) return 1;
+    const x = A.pre[i], y = B.pre[i];
+    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
+    if (nx && ny) { if (Number(x) !== Number(y)) return Number(x) - Number(y); continue; }
+    // A numeric identifier ranks below an alphanumeric one.
+    if (nx !== ny) return nx ? -1 : 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 // Where the CURRENTLY installed projectstore lives, per Claude Code's own
 // plugin registry. The cache path carries the version
 // (…/plugins/cache/<marketplace>/projectstore/<version>), so anything that
@@ -863,6 +893,30 @@ export function findAgentsBlock(text) {
   return { present: true, v: Number(m[1]), start: m.index, end, unclosed: false, count, block: text.slice(m.index, end) };
 }
 
+// Whether `text` holds `line` as a line of its own, trimmed and exact — the
+// installer's match for the `@<file>` import, so `@./AGENTS.md` reads as
+// absent to install and doctor alike.
+export function importsLine(text, line) {
+  return String(text ?? "").split("\n").some((l) => l.trim() === line);
+}
+
+// Whether a harness sees the one agents block where it stands — the predicate
+// doctor reports by (the install spec, contract 6 as amended after the rc.3
+// tag). Install's placement rules agree with it: it moves a block whose file
+// is not among the harness's files and bridges one that is, through the same
+// import match (importsLine); a test holds the two to one answer. Visible when
+// the block's file is among the harness's agents_block.files and is either the
+// file it reads by itself or imported from that file. A harness with no agents
+// block has nothing to see it with. `texts` maps a file name to its text; an
+// absent file is undefined.
+export function blockVisibleTo(manifest, file, texts = {}) {
+  const ab = manifest?.surfaces?.agents_block;
+  if (!ab || ab.supported === false) return true;
+  if (!(ab.files || []).includes(file)) return false;
+  const native = ab.reads_natively;
+  return !native || native === file || importsLine(texts[native], `@${file}`);
+}
+
 // Replace the block in place, else append it after the user's own content.
 export function replaceAgentsBlock(text, block) {
   const base = String(text ?? "");

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -47,7 +47,7 @@ import {
   pluginEnabled,
   treeDigest,
   packageDigest,
-  cmpVersion,
+  cmpPrecedence,
   layoutPaths,
   RUNTIME_GITIGNORE_HEADER,
   LAUNCHER_HEADER,
@@ -284,7 +284,7 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
     if (e.projectPath && !samePath(e.projectPath, projectDir)) continue;
     seen.add(e.key); a.others.push({ key: e.key, path: e.path, version: e.version });
   }
-  a.newer = Boolean(a.dir.pkg) && cmpVersion(a.dir.pkg, pkg) > 0;
+  a.newer = Boolean(a.dir.pkg) && cmpPrecedence(a.dir.pkg, pkg) > 0;
   // Same version, different payload: the directory's recorded digest against
   // this package's — contract 4's rung 3 (source changed) for a directory.
   a.contentDiffers = null;
@@ -307,7 +307,7 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   // The directory is shared by every checkout on the machine; a project that never registered is absent, whatever the directory holds.
   if (nothingOfOursHere) return { ...a, state: "absent", reason: a.dir.present ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered` : null };
   if (!a.dir.present) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + " (the directory is gone)" };
-  if (cmpVersion(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
+  if (cmpPrecedence(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
   if (a.dir.digestOk === false) return { ...a, state: "stale", reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)" };
   if (a.contentDiffers === true) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (same version ${pkg}, different content — the directory's digest is not this package's)` };
   if (!a.known || !a.registeredHere) return { ...a, state: "stale", reason: STALE_TEXT[STALE.CONFIG] + (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)") };
@@ -397,6 +397,9 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
         writtenBy: a.writtenBy || null,
         newer: Boolean(a.newer),
         bin: a.bin,
+        // What this registration silenced for the checkout and the checkout
+        // still holds off: exactly the set uninstall re-enables (contract 13).
+        silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
       });
       states.push(row);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.28.0-rc.3",
+  "version": "0.28.0",
   "description": "Installs projectstore for Claude Code from npm: the core pinned and bundled, the harness fixed — npx projectstore-claude install --project \"$PWD\".",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.28.0-rc.3"
+    "projectstore": "=0.28.0"
   },
   "bundleDependencies": [
     "projectstore"