projectstore-claude 0.30.2 → 0.30.4

package/node_modules/projectstore/scripts/models.mjs

@@ -18,6 +18,18 @@
 //   modelsProblem(manifest)              → what is wrong with the block, or null:
 //                                          the manifest schema test's check
 //
+// Effort (the ADR "Agent effort is passed at spawn beside the model, from the
+// overlay, in each harness's own levels") reads the same entries: the
+// manifest's agent_translation.effort names the levels its spawn takes, and,
+// where a catalog lists a model's own levels, their field paths.
+//
+//   effortSpec(manifest)                 → the effort block, or null
+//   effortLevels(manifest, model, known) → the levels a model takes, from its
+//                                          catalog entry or the manifest's floor
+//   offLevelNote(manifest, level, model, known) → the PLAN's note for a level
+//                                          that list lacks, or null (decision 5)
+//   effortProblem(manifest)              → what is wrong with the block, or null
+//
 // Local reads are synchronous and cheap: the manifest, a `file` catalog, and
 // projectstore's own cache. A `command` or `http` catalog is read only by
 // readLive, which a menu starts in the background. env, home, now, fetch,
@@ -41,6 +53,15 @@ export function modelSpec(manifest) {
   return m && typeof m === "object" ? m : null;
 }
 
+export function effortSpec(manifest) {
+  const e = manifest?.agent_translation?.effort;
+  return e && typeof e === "object" ? e : null;
+}
+
+// A level is a lowercase token: the shape --set accepts and a catalog's
+// level must have to be kept.
+export const LEVEL = /^[a-z][a-z0-9-]*$/;
+
 // One field path, dotted: "data", "models", "fetched_at".
 const at = (obj, path) =>
   String(path || "")
@@ -67,9 +88,10 @@ const clean = (s) =>
     .replace(/[\x00-\x1f\x7f-\x9f]/g, "");
 
 // A catalog's answer as rows: { id, label, description, family, hidden },
-// in the catalog's order. Entries without an id, and entries `keep_when`
-// rejects, are dropped; `shown_when` only hides.
-export function entriesOf(body, fields) {
+// in the catalog's order, and `levels` and `default_level` when `levelFields`
+// (the effort block's catalog paths) finds them in an entry. Entries without
+// an id, and entries `keep_when` rejects, are dropped; `shown_when` only hides.
+export function entriesOf(body, fields, levelFields = null) {
   const list = at(body, fields.list);
   if (!Array.isArray(list)) return null;
   const rows = [];
@@ -89,6 +111,7 @@ export function entriesOf(body, fields) {
       description: text(fields.description),
       family: text(fields.family),
       hidden: fields.shown_when ? !matches(e, fields.shown_when) : false,
+      ...levelsOf(e, levelFields),
       order: fields.order ? at(e, fields.order) : k,
       k,
     });
@@ -100,7 +123,37 @@ export function entriesOf(body, fields) {
     if (x === y || x === undefined || y === undefined) return a.k - b.k;
     return (x < y ? -1 : 1) * (desc ? -1 : 1);
   });
-  return rows.map(({ id, label, description, family, hidden }) => ({ id, label, description, family, hidden }));
+  return rows.map(({ order: _order, k: _k, ...row }) => row);
+}
+
+// One entry's own levels, by the effort block's catalog paths: { levels:
+// [{ id, description }], default_level } or nothing at all, so an entry
+// without them reads exactly as it did before levels were read.
+function levelsOf(e, lf) {
+  if (!lf || !lf.list) return {};
+  const list = at(e, lf.list);
+  if (!Array.isArray(list)) return {};
+  const levels = [];
+  for (const x of list) {
+    const raw = x && typeof x === "object" ? at(x, lf.id || "id") : x;
+    const id = typeof raw === "string" ? clean(raw) : "";
+    if (!LEVEL.test(id) || levels.some((l) => l.id === id)) continue;
+    const d = x && typeof x === "object" && lf.description ? at(x, lf.description) : undefined;
+    levels.push({ id, description: typeof d === "string" ? clean(d) : "" });
+  }
+  if (!levels.length) return {};
+  const dRaw = lf.default ? at(e, lf.default) : undefined;
+  const d = typeof dRaw === "string" ? clean(dRaw) : "";
+  return { levels, ...(levels.some((l) => l.id === d) ? { default_level: d } : {}) };
+}
+
+// A cached row's levels, cleaned again: the cache is a file anyone can edit.
+function cachedLevels(x) {
+  if (!Array.isArray(x.levels)) return {};
+  return levelsOf(
+    { l: x.levels, d: x.default_level },
+    { list: "l", id: "id", description: "description", default: "d" },
+  );
 }
 
 const timeOf = (v) => {
@@ -129,6 +182,7 @@ function readCache(manifest, opts) {
         description: clean(x.description ?? ""),
         family: clean(x.family ?? ""),
         hidden: Boolean(x.hidden),
+        ...cachedLevels(x),
       }));
     const source = typeof c.source === "string" ? c.source : "";
     const from = (modelSpec(manifest)?.catalogs || []).find((x) => x.source === source);
@@ -147,7 +201,7 @@ function readFileCatalog(manifest, spec, catalog, opts) {
     const raw = readFileSync(p, "utf8");
     const fields = fieldsOf(spec, catalog);
     const body = JSON.parse(raw);
-    const entries = entriesOf(body, fields);
+    const entries = entriesOf(body, fields, effortSpec(manifest)?.catalog);
     if (!entries) return null;
     const t = timeOf(fields.at ? at(body, fields.at) : undefined) ?? statSync(p).mtimeMs;
     return { at: t, source: catalog.source || "", caption: catalog.caption || catalog.source || "", entries };
@@ -239,6 +293,14 @@ export function knownModels(manifest, { env = process.env, home = homedir(), now
       if (!offered.some((o) => o.id === s.id))
         offered.push({ id: s.id, label: s.label || "", description: s.description || "" });
   }
+  // A model's own levels, from the newest list whose entry for it names
+  // them: a cache written before levels were kept falls through to the
+  // harness's own file, so a refresh never loses what that file says.
+  const levels = new Map();
+  for (const c of [...(past.length ? past : candidates)].sort((a, b) => b.at - a.at))
+    for (const e of c.entries)
+      if (e.levels && !levels.has(e.id))
+        levels.set(e.id, { levels: e.levels, default: e.default_level || null, source: c.source, at: c.at });
   const t = t0;
   const live = liveCatalog(spec, env);
   return {
@@ -247,6 +309,7 @@ export function knownModels(manifest, { env = process.env, home = homedir(), now
     offered,
     known,
     hidden: new Set(entries.filter((e) => e.hidden).map((e) => e.id)),
+    levels,
     source: newest ? newest.source : "",
     caption: newest ? newest.caption || newest.source : "",
     at: newest ? newest.at : null,
@@ -288,6 +351,53 @@ const localDate = (t) => {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 };
 
+// The levels a model takes (the effort ADR, decisions 3 and 4): its own, when
+// a list names them, else the manifest's floor. `known` is knownModels'
+// answer, or null. Null when the manifest declares no effort block.
+//   { levels: [{ id, description }], default, from: "catalog" | "floor",
+//     model, source, at }
+export function effortLevels(manifest, model, known) {
+  const spec = effortSpec(manifest);
+  if (!spec) return null;
+  const own = model ? known?.levels?.get(model) : null;
+  if (own) return { levels: own.levels, default: own.default, from: "catalog", model, source: own.source, at: own.at };
+  const levels = (spec.levels || []).filter((l) => l && typeof l.id === "string" && l.id);
+  return { levels, default: null, from: "floor", model: model || null, source: "", at: null };
+}
+
+// The PLAN's note for a level the list lacks (the effort ADR, decision 5), or
+// null when it is listed, or when the harness declares no levels at all.
+//   the model's own list: "<model> does not list <level> in <source>'s list
+//                          as of <date>; written as typed"
+//   the floor:            "<level> is not one of <harness>'s effort levels
+//                          (<levels>); written as typed", and, where the
+//                          spawn takes those levels only, that it refuses it
+export function offLevelNote(manifest, level, model, known) {
+  if (!level) return null;
+  const l = effortLevels(manifest, model, known);
+  if (!l || l.levels.some((x) => x.id === level)) return null;
+  const display = manifest?.display_name || manifest?.id || "this harness";
+  if (l.from === "catalog")
+    return `${l.model} does not list ${level} in ${l.source || display}'s list${l.at ? ` as of ${localDate(l.at)}` : ""}; written as typed`;
+  const list = l.levels.map((x) => x.id).join(", ");
+  return effortSpec(manifest).strict
+    ? `${level} is not one of ${display}'s effort levels (${list}); written as typed, and ${display} refuses it at spawn`
+    : `${level} is not one of ${display}'s effort levels (${list}); written as typed`;
+}
+
+// The note for a level an agent keeps when the run moves it to a model that
+// does not take it (the effort ADR, decision 5), or null: "<agent> runs at
+// <level>, which <model> does not list in <source>'s list as of <date>".
+export function standingLevelNote(manifest, agent, level, model, known) {
+  if (!level) return null;
+  const l = effortLevels(manifest, model, known);
+  if (!l || l.levels.some((x) => x.id === level)) return null;
+  const display = manifest?.display_name || manifest?.id || "this harness";
+  return l.from === "catalog"
+    ? `${agent} runs at ${level}, which ${l.model} does not list in ${l.source || display}'s list${l.at ? ` as of ${localDate(l.at)}` : ""}`
+    : `${agent} runs at ${level}, which is not one of ${display}'s effort levels`;
+}
+
 // What is wrong with a manifest's models block, or null (the manifest schema
 // test, generation contract 1). A manifest without the block is fine: its
 // agents' models are typed by name.
@@ -321,6 +431,40 @@ export function modelsProblem(manifest) {
   return null;
 }
 
+// What is wrong with a manifest's effort block, or null (the manifest schema
+// test). A manifest without the block passes no effort, and is fine.
+export function effortProblem(manifest) {
+  const spec = effortSpec(manifest);
+  if (!spec) return manifest?.agent_translation?.effort === undefined ? null : "effort is not an object";
+  const str = (v) => typeof v === "string" && v.length > 0;
+  const EVIDENCE = ["measured", "documented", "chosen"];
+  if (!str(spec.spawn_param) || !str(spec.spawn_param_reason)) return "spawn_param carries no name or no reason";
+  if (!EVIDENCE.includes(spec.spawn_param_evidence))
+    return `spawn_param_evidence is ${spec.spawn_param_evidence}, not ${EVIDENCE.join(", ")}`;
+  if (!Array.isArray(spec.levels) || !spec.levels.length) return "levels is not a non-empty list";
+  for (const l of spec.levels)
+    if (!l || !LEVEL.test(String(l.id)) || !str(l.description))
+      return `a level is not { id, description }: ${JSON.stringify(l)}`;
+  if (!str(spec.levels_reason)) return "levels carries no levels_reason";
+  if (spec.strict !== undefined && (typeof spec.strict !== "boolean" || !str(spec.strict_reason)))
+    return "strict is not a boolean with a strict_reason";
+  if (spec.catalog !== undefined) {
+    const c = spec.catalog;
+    if (!c || !str(c.list) || !str(c.id) || !str(c.reason)) return "the effort catalog names no list, id or reason";
+    if (!modelSpec(manifest)) return "an effort catalog without a models block has no entries to read";
+  }
+  const u = spec.unset;
+  if (!u || !str(u.value) || !str(u.row) || typeof u.model_default !== "boolean" || !str(u.reason))
+    return "unset is not { value, row, model_default, reason }";
+  if (spec.cheap !== undefined) {
+    if (!spec.levels.some((l) => l.id === spec.cheap)) return `cheap is ${spec.cheap}, not one of the levels`;
+    if (!str(spec.cheap_reason)) return "cheap carries no cheap_reason";
+    if (!EVIDENCE.includes(spec.cheap_evidence))
+      return `cheap_evidence is ${spec.cheap_evidence}, not ${EVIDENCE.join(", ")}`;
+  }
+  return null;
+}
+
 // One bounded fetch, settled by a timer whatever the request does after: the
 // pattern of convergence.mjs's request(). The key goes in its header and
 // nowhere else; nothing of the request is kept.
@@ -487,7 +631,7 @@ export async function readLive(
   }
   if (r.error) return { error: r.error, source: catalog.source || "" };
   if (signal?.aborted) return { error: "stopped", source: catalog.source || "" };
-  const entries = entriesOf(r.body, fieldsOf(spec, catalog));
+  const entries = entriesOf(r.body, fieldsOf(spec, catalog), effortSpec(manifest)?.catalog);
   if (!entries) return { error: "the answer holds no list", source: catalog.source || "" };
   const t = now();
   const p = modelCachePath(manifest, { env, home });

package/node_modules/projectstore/scripts/setup.mjs

@@ -64,7 +64,7 @@ import {
   languageNames,
 } from "./binding.mjs";
 import { analyseRegistration, analyseJsonEntry } from "./surfaces.mjs";
-import { runningCopies, coreCommand, channelChoices, pinFor } from "./convergence.mjs";
+import { runningCopies, coreCommand, channelChoices, pinFor, terminalRun } from "./convergence.mjs";
 import { runVerb, isInteractive, gateText, channelText, publicItem, planOptions } from "./install-harness.mjs";
 import { resolveBinding } from "./worktree.mjs";
 import * as term from "./term.mjs";
@@ -328,7 +328,9 @@ function factsOf(project, { env, home, root, version, interactive }) {
     sessionCopy = selectCopy(home, project, { harness: channelHarness });
   }
   const slotHarness = manifests.find((m) => statuslineOf(m)) || null;
-  const slot = slotHarness ? analyseJsonEntry(project, statuslineOf(slotHarness), { root, home }).state : null;
+  const slot = slotHarness
+    ? analyseJsonEntry(project, statuslineOf(slotHarness), { root, home, harness: slotHarness }).state
+    : null;
   // A worktree's main checkout (worktree.mjs): only where it can be offered —
   // at a terminal, unbound, in a linked worktree. Read for the project
   // answered, never from the git top, which --project leaves unread.
@@ -692,12 +694,12 @@ function doneLines(r, { project, runEnv, home, version, channel, vaultPlan, unde
     // Rule 13: `--channel npm` when that was the answer, and only for the
     // harness whose channel it is — setup refuses --channel in a run without
     // that harness (exit 2). A keep is not repeated: once recorded, it is the
-    // default already (rule 6).
-    const again = channel === "npm" && hostRegistrationOf(m) ? "--channel npm" : "";
+    // default already (rule 6). The deferred row's reason names the same
+    // command, from the same builder.
     if (left.length)
       blocks.push({
         lead: `Left for a terminal outside this ${m.display_name} session: ${left.join(", ")}. From a terminal in this project, run:`,
-        commands: [coreCommand("setup", { version, args: [`--harness ${id}`, again].filter(Boolean).join(" ") })],
+        commands: [terminalRun({ verb: "setup", harness: m, version, channel })],
         after: `then restart ${m.display_name}.`,
       });
   }

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -19,7 +19,8 @@
 //
 // Normative: the install spec — contract 0 (exclusive vs shared), 3–4 (the
 // four states and the ladder, rungs 1′ and 1″ included), 6 (per-entry states
-// for shared files: ours-current, ours-stale, ours-absent, unparseable),
+// for shared files: ours-current, ours-stale, ours-newer — 2026-10-14 —, ours-absent,
+// unparseable),
 // 12 (current, last written by), 14 (host-managed surfaces have no state to
 // derive), 16 (a harness is in use when detected or when it has files of
 // ours). Pure node, no external deps.
@@ -37,6 +38,8 @@ import {
   desiredStatusLineCommand,
   findAgentsBlock,
   agentsBlockVersion,
+  newerBlockWords,
+  isNewerBlock,
   agentsBlockTemplatePath,
   renderAgentsBlock,
   loadLayout,
@@ -185,6 +188,15 @@ export function analyseBlock(
   a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
   a.duplicates = withBlock.filter((e) => e !== a.current);
   if (!a.current) return { ...a, state: "ours-absent" };
+  // A marker above this copy's template is never rendered down (the install
+  // spec, contracts 4 and 6, as amended 2026-10-14). Placement still decides
+  // first (rungs B4–B6), and a block that moves, migrates or is deduplicated
+  // carries the newest block's own text; one that stays is `ours-newer`
+  // (B7), before the render is compared, so its roster is never re-rendered.
+  const newest = withBlock.reduce((n, e) => (e.block.v > n.block.v ? e : n), a.current);
+  a.newer = isNewerBlock(newest.block.v, a.version) ? newest : null;
+  const words = a.newer ? newerBlockWords(a.newer.block.v, a.version) : null;
+  const carried = a.newer ? ` with its own text (${words})` : "";
   // A block this harness CANNOT READ moves, and its target is created if it has
   // to be: that is the whole difference between a second harness arriving and a
   // preference. A block it can read moves only when the preferred file already
@@ -197,17 +209,25 @@ export function analyseBlock(
     return {
       ...a,
       state: "ours-stale",
-      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}`,
+      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}${carried}`,
     };
   }
   if (a.current.file !== preferred.file && preferred.present)
-    return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
+    return {
+      ...a,
+      state: "ours-stale",
+      reason: `in ${a.current.file}; install migrates it to ${preferred.file}${carried}`,
+    };
   if (a.duplicates.length)
     return {
       ...a,
       state: "ours-stale",
-      reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}`,
+      reason:
+        a.newer && a.newer !== a.current
+          ? `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}, and ${a.newer.file}'s carries v${a.newer.block.v}, newer than this copy's v${a.version}: its text replaces the block in ${a.current.file}`
+          : `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}${carried}`,
     };
+  if (a.newer) return { ...a, state: "ours-newer", reason: `${words}: left as it is` };
   if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
   return {
     ...a,
@@ -223,8 +243,15 @@ export function analyseBlock(
 
 // `renderRoot` (contract 4′, two phases): the root the surface is planned
 // AGAINST — the host's install path a registration produces — when it differs
-// from the root the templates are read from. Defaults to `root`.
-export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = homedir(), renderRoot = root } = {}) {
+// from the root the templates are read from. Defaults to `root`. `harness` is
+// the one the entry is FOR: its launcher lives under its own state directory,
+// whichever harness launched this process (the install spec, contract 6, as
+// amended 2026-10-14).
+export function analyseJsonEntry(
+  projectDir,
+  s,
+  { root = pluginRoot(), home = homedir(), renderRoot = root, harness = null } = {},
+) {
   const path = join(projectDir, s.file);
   const pointer = s.marker?.pointer || "statusLine.command";
   const entryKey = pointer.split(".")[0];
@@ -263,7 +290,7 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
   a.ours =
     statusLineIsOurWiring(a.curCmd, projectDir, home, root) ||
     statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
-  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home).command;
+  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home, harness?.id).command;
   if (!a.curEntry) return { ...a, state: "ours-absent" };
   if (!a.ours) return { ...a, state: "theirs", reason: "a status line we did not write owns the slot" };
   if (a.curCmd === a.desired) return { ...a, state: "ours-current" };
@@ -317,7 +344,7 @@ export function analyseStampedFile(
   const tpl = readText(src);
   if (!tpl.present || tpl.text === null)
     return { ...a, state: "unparseable", refusal: `the source ${s.source} is missing from the plugin at ${root}` };
-  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir);
+  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir, process.env, harness);
   if (rendered === null)
     return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
   const pkg = pluginVersionAt(root, harness) || "0.0.0";
@@ -791,7 +818,7 @@ export function surfaceStates(
     const hasOurs = states.some(
       (x) =>
         (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) ||
-        (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)),
+        (x.kind === "shared" && ["ours-current", "ours-stale", "ours-newer"].includes(x.state)),
     );
     if (detected.includes(m.id) || hasOurs) {
       out.used.push(m.id);

package/node_modules/projectstore/templates/claude-md-block.md.tmpl

@@ -1,4 +1,4 @@
-<!-- projectstore:agents v4 (managed by projectstore — edit outside markers) -->
+<!-- projectstore:agents v5 (managed by projectstore — edit outside markers) -->
 ## projectstore agents
 
 - **A feature-sized request opens a vault artifact before it opens an editor.**
@@ -11,10 +11,12 @@
   harness-level instruction contradicts this block, say so and ask which wins.
   Resolving it silently is how the contradiction becomes invisible to the person
   who could have settled it.
-- When spawning any agent below, resolve its model from
-  `.projectstore/harness/<harness>.json` → `agents.per_agent.<name>.model ?? agents.default.model`,
-  where `<name>` is the **bare** agent name (`critic` for `projectstore:critic`),
-  and pass it as the spawn's model parameter. No key — pass nothing.
+- When spawning any agent below, resolve its model and its effort from
+  `.projectstore/harness/<harness>.json` → `agents.per_agent.<name>.model ?? agents.default.model`
+  and `agents.per_agent.<name>.effort ?? agents.default.effort`, where `<name>` is
+  the **bare** agent name (`critic` for `projectstore:critic`), and pass them as
+  the spawn's model and effort parameters, the effort only when the spawn offers
+  one. No key — pass nothing.
 - After authoring or revising any vault artifact (ADR/research/epic/story) or
   design proposal: run the `projectstore:critic` agent on it before treating it final.
 - Before implementing an epic/story: consult `projectstore:planner` — it plans

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.2",
+  "version": "0.30.4",
   "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.30.2"
+    "projectstore": "=0.30.4"
   },
   "bundleDependencies": [
     "projectstore"