projectstore-claude 0.30.2 → 0.30.3

package/node_modules/projectstore/scripts/doctor.mjs

@@ -60,6 +60,7 @@ import {
   statusLineLauncherPath,
   LAUNCHER_HEADER,
   installedPluginEntries,
+  projectCopies,
   selectCopy,
   takesNoRegister,
   copyUpdateAdvice,
@@ -98,7 +99,9 @@ import {
   configPath as harnessConfigPath,
   packageCommand,
   invocation,
+  harnessForOverlay,
 } from "./harness.mjs";
+import { effortSpec } from "./models.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
@@ -891,7 +894,7 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
         "install",
         "issue",
         "overlay-forbidden-key",
-        `${where} carries \`${k}\`, which an overlay may not: only agents.default.model and agents.per_agent.<name>.model are read; the key is ignored.`,
+        `${where} carries \`${k}\`, which an overlay may not: only agents.default.model, agents.default.effort, agents.per_agent.<name>.model and agents.per_agent.<name>.effort are read; the key is ignored.`,
         where,
       ),
     );
@@ -953,19 +956,42 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
       }
     }
   }
-  // A configured name no roster agent carries runs nothing: the model never
-  // applies. A warn, not an issue — a newer package's agent is a legitimate
-  // reason for a committed overlay to name one this copy does not ship.
+  // A configured name no roster agent carries runs nothing: what it
+  // configures never applies. A warn, not an issue — a newer package's agent
+  // is a legitimate reason for a committed overlay to name one this copy does
+  // not ship.
+  // An effort the harness's levels lack fails at spawn on a harness whose
+  // spawn takes those levels only, and is the harness's to judge elsewhere:
+  // a warn names it either way (the effort ADR, decision 7). Read against the
+  // manifest's floor alone: doctor reads no model catalog.
+  const levels = effortSpec(harnessForOverlay(o.id))?.levels?.map((l) => l.id) || null;
+  if (levels) {
+    const set = [
+      ...(o.efforts.default ? [["agents.default.effort", o.efforts.default]] : []),
+      ...Object.entries(o.efforts.per_agent).map(([n, v]) => [`agents.per_agent.${n}.effort`, v]),
+    ];
+    for (const [k, v] of set)
+      if (!levels.includes(v))
+        out.push(
+          finding(
+            "install",
+            "warn",
+            "overlay-unknown-effort",
+            `${where} sets \`${k}\` to ${v}, which is not one of ${harnessForOverlay(o.id)?.display_name || o.id}'s effort levels (${levels.join(", ")}) — a spawn may refuse it.`,
+            where,
+          ),
+        );
+  }
   const roster = layoutRoster(cfg);
   if (roster) {
-    for (const n of Object.keys(o.agents.per_agent)) {
+    for (const n of new Set([...Object.keys(o.agents.per_agent), ...Object.keys(o.efforts.per_agent)])) {
       if (!roster.includes(n))
         out.push(
           finding(
             "install",
             "warn",
             "overlay-unknown-agent",
-            `${where} configures \`${n}\`, which is not in the ${cfg.layout} roster (${roster.join(", ")}) — no agent by that name runs, so the model never applies. A typo, or an agent this package does not ship yet.`,
+            `${where} configures \`${n}\`, which is not in the ${cfg.layout} roster (${roster.join(", ")}) — no agent by that name runs, so what it configures never applies. A typo, or an agent this package does not ship yet.`,
             where,
           ),
         );
@@ -1148,7 +1174,16 @@ export function checkVersionDrift(home = homedir(), states = [], proj = null, {
   const seen = [];
   // The registry read here is the source harness's own.
   const registryOf = sourceHarness()?.id || null;
-  for (const e of installedPluginEntries(home, proj)) {
+  // The copies the host loads for this project (contract 17, amended
+  // 2026-10-14): this checkout's own row or a user-scope row, never another
+  // project's — the registry keeps every project's local rows, and another
+  // checkout's old copy is not a drift here. Every row, not one per key: this
+  // project's own row against a user-scope row is the drift contract 17 names.
+  // Without a project, the user-scope rows alone.
+  const rows = proj
+    ? projectCopies(home, proj)
+    : installedPluginEntries(home).filter((e) => e.present && e.enabled !== false && !e.projectPath);
+  for (const e of rows) {
     // A disabled registration is not a copy anyone runs (contract 17, amended 2026-09-05).
     if (e.version && e.present && e.enabled !== false)
       seen.push({
@@ -1284,24 +1319,32 @@ export function checkOverrideCopies(proj, home = homedir(), harness = speakingHa
   return out;
 }
 
-// ADR-008 made `effort` unconfigurable per project, which promotes this env var
-// from a curiosity to the ONLY thing that can move our agents off `effort: max`.
-// It beats frontmatter, so a value set for cost or latency silently drops all
-// five agents below the quality floor the plugin advertises — exactly the class
-// of silent downgrade doctor exists to name.
+// The variable outranks every effort projectstore passes at spawn and the
+// bundled agents' frontmatter effort: with it set, the spawn offers no effort
+// parameter at all (the effort ADR, decision 7). So a value set for cost or
+// latency silently replaces the efforts the overlay configures — exactly the
+// class of "the value configured is not the value that runs" doctor names.
 // The variable names come from the manifest (runtime.agent_overrides); the
-// wording is projectstore's, because the claim — ADR-008's quality floor — is.
-export function checkEnvEffort() {
+// overlay is read only when one is set, so a clean startup reads nothing.
+export function checkEnvEffort(proj = null) {
   return agentOverrides()
     .filter((o) => o.kind === "effort")
-    .map((o) =>
-      finding(
+    .map((o) => {
+      const ov = proj ? readOverlayAt(proj) : null;
+      const set = ov
+        ? [
+            ...(ov.efforts.default ? ["agents.default.effort"] : []),
+            ...Object.keys(ov.efforts.per_agent).map((n) => `agents.per_agent.${n}.effort`),
+          ]
+        : [];
+      const where = set.length ? ` (${relative(proj, ov.path) || ov.path} sets ${set.join(", ")})` : "";
+      return finding(
         "install",
         "warn",
         "env-effort",
-        `${o.env}=${o.value} is set — it overrides the bundled agents' "effort: max" frontmatter, so every projectstore agent runs at "${o.value}". Effort is not configurable per project (ADR-008); unset the variable to restore the quality floor.`,
-      ),
-    );
+        `${o.env}=${o.value} is set — it outranks every effort projectstore passes at spawn${where} and the bundled agents' frontmatter, so every projectstore agent runs at "${o.value}". Unset it for the configured efforts to run.`,
+      );
+    });
 }
 
 export function checkEnvModel() {
@@ -1538,28 +1581,48 @@ export function checkGitignore(proj) {
       }
     }
   }
-  if (!existsSync(join(proj, ".git"))) return out;
+  // The host's settings file is checkHostIgnored's (the layout spec, contract 9
+  // as amended 2026-10-14): only git knows every rule that ignores it, and this
+  // function runs in the SessionStart subset, whose budget forbids a subprocess.
+  return out;
+}
+
+// The line read the host-file check used before it asked git, and still uses
+// when git cannot answer: the project's own .gitignore, exact lines only.
+function hostIgnoreLineMissing(proj, env) {
   let lines = [];
   try {
     lines = readFileSync(join(proj, ".gitignore"), "utf8")
       .split("\n")
       .map((l) => l.trim());
   } catch {}
-  const coveredAll = lines.includes(".claude/") || lines.includes(".claude");
-  if (coveredAll) return out;
-  // Our own files are self-ignored inside .projectstore/; what is left is the host's.
-  const wanted = [relative(proj, hostSettingsPath(proj))];
-  const missing = wanted.filter((w) => !lines.includes(w));
-  if (!missing.length) return out;
-  out.push(
+  if (lines.includes(".claude/") || lines.includes(".claude")) return [];
+  return [relative(proj, hostSettingsPath(proj, env))].filter((w) => !lines.includes(w));
+}
+
+// Whether git ignores the host's machine-local settings file (the layout spec,
+// contract 9 as amended 2026-10-14). Our own files are self-ignored inside
+// .projectstore/; what is left is the host's. Git's answer covers every rule
+// it applies — nested .gitignore files, .git/info/exclude, core.excludesFile
+// and its XDG default — where the line read saw only the project's exact
+// lines. --no-index keeps this about rules: a tracked file with a matching rule
+// is quiet here (tracking is checkTrackedRuntime's). Exit 0 is ignored, 1 is
+// not; anything else — no git on PATH, an error, a timeout — falls back to the
+// line read. Full report only: a subprocess, like checkTrackedRuntime.
+export function checkHostIgnored(proj, { env = process.env } = {}) {
+  if (!existsSync(join(proj, ".git"))) return [];
+  const file = relative(proj, hostSettingsPath(proj, env));
+  const r = spawnSync("git", ["check-ignore", "-q", "--no-index", "--", file], { cwd: proj, env, timeout: 5000 });
+  const missing = r.status === 0 ? [] : r.status === 1 ? [file] : hostIgnoreLineMissing(proj, env);
+  if (!missing.length) return [];
+  return [
     finding(
       "install",
       "warn",
       "gitignore",
       `Machine-specific files not gitignored: ${missing.join(", ")} (or ignore ".claude/" wholesale).`,
     ),
-  );
-  return out;
+  ];
 }
 
 // An ignore line never untracks a file already in the index, so the project
@@ -2956,8 +3019,9 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
     ...checkAgentsBlock(proj, { env: opts.env, root: opts.root }),
     ...checkOverrideCopies(proj),
     ...checkEnvModel(),
-    ...checkEnvEffort(),
+    ...checkEnvEffort(proj),
     ...checkGitignore(proj),
+    ...checkHostIgnored(proj, { env: opts.env }),
     ...checkTrackedRuntime(proj),
     ...checkVaultGit(cfg),
     ...checkAutoUpdate(),
@@ -3042,7 +3106,7 @@ export function runStartupChecks(cfg, proj, budgetMs = 150) {
         restamp: findings.some((f) => f.level === "info" && f.check === "upgrade"),
       }),
     () => checkEnvModel(),
-    () => checkEnvEffort(),
+    () => checkEnvEffort(proj),
   ];
   for (const step of steps) {
     if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings: foldIntoMove(findings) };

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

@@ -2630,11 +2630,40 @@ export function plan(
   placeBlock();
   for (const item of moved.last) out.items.push({ harness: layoutHarness.id, ...item });
   out.items.push(...marks);
+  oneAddPerFile(out.items);
   if (out.items.some((i) => i.action === "refuse")) out.ok = false;
   if (out.refusals.length) out.ok = false;
   return out;
 }
 
+// One add per file (the presentation spec, contract 7 as amended 2026-10-14):
+// within one plan, a file an earlier item creates is added once. A later
+// `create` or `add` on that path changes the file the run has just made, so it
+// reads `update`; its state, steps and detail stay. Each item is planned
+// against the tree before the run, so the binding the vault item writes was
+// "absent" to the status-line flag and the channel mark, and all three read
+// "add". A creator is an earlier `create` or `add` item that is neither a
+// registration (its host-owned files are the host CLI's) nor a binding row (it
+// never makes the binding: apply skips it on an unbound project, and the vault
+// item or the layout move makes the file), counted for the paths absent at
+// plan time: its own and each step's `path` — never a move step's `to`, so a
+// migrating project's binding rows keep `add`. An entry row on a file that was
+// there keeps `add`.
+function oneAddPerFile(items) {
+  const created = new Set();
+  const writes = (i) => i.action === "create" || i.action === "add";
+  for (const item of items) {
+    if (!writes(item) || item.kind === "registration") continue;
+    if (item.path && created.has(resolve(item.path))) {
+      item.action = "update";
+      continue;
+    }
+    if (item.kind === "binding") continue;
+    for (const p of [item.path, ...(item.steps || []).map((s) => s.path)])
+      if (p && !existsSync(p)) created.add(resolve(p));
+  }
+}
+
 // ─── the layout migration (the layout ADR; layout spec contract 6) ──────
 //
 // Two items, kind `layout`. The FIRST moves what only we read — the legacy

package/node_modules/projectstore/scripts/lib.mjs

@@ -196,9 +196,11 @@ export { adoptHookInput, resetHookInput };
 // ─── Harness overlays (the layout ADR decision 3; layout spec contracts 2–4) ──
 //
 // <project>/.projectstore/harness/<id>.json carries ONE thing: the agents block
-// for that harness — agents.default.model and agents.per_agent.<name>.model.
-// Every other key is ignored on read and named for doctor (rejected). The
-// binding never carries agents: ADR-008's two-term chain is read from here.
+// for that harness — agents.default.model, agents.default.effort,
+// agents.per_agent.<name>.model and agents.per_agent.<name>.effort (the effort
+// ADR, decision 1). Every other key is ignored on read and named for doctor
+// (rejected). The binding never carries agents: ADR-008's two-term chain is
+// read from here, once per field.
 export function readOverlayAt(projectDir, id = overlayId()) {
   // No id (no manifest at all): nothing is read, and the writer below refuses
   // the same id rather than inventing a file name for it.
@@ -209,6 +211,7 @@ export function readOverlayAt(projectDir, id = overlayId()) {
     present: Boolean(path) && existsSync(path),
     unparseable: false,
     agents: { default: null, per_agent: {} },
+    efforts: { default: null, per_agent: {} },
     rejected: [],
     raw: null,
   };
@@ -235,8 +238,10 @@ export function readOverlayAt(projectDir, id = overlayId()) {
   for (const k of Object.keys(a)) if (k !== "default" && k !== "per_agent") out.rejected.push(`agents.${k}`);
   if (a.default !== undefined) {
     if (a.default && typeof a.default === "object") {
-      for (const k of Object.keys(a.default)) if (k !== "model") out.rejected.push(`agents.default.${k}`);
+      for (const k of Object.keys(a.default))
+        if (k !== "model" && k !== "effort") out.rejected.push(`agents.default.${k}`);
       if (typeof a.default.model === "string" && a.default.model) out.agents.default = a.default.model;
+      if (typeof a.default.effort === "string" && a.default.effort) out.efforts.default = a.default.effort;
     } else out.rejected.push("agents.default");
   }
   if (a.per_agent !== undefined) {
@@ -246,8 +251,10 @@ export function readOverlayAt(projectDir, id = overlayId()) {
           out.rejected.push(`agents.per_agent.${name}`);
           continue;
         }
-        for (const k of Object.keys(v)) if (k !== "model") out.rejected.push(`agents.per_agent.${name}.${k}`);
+        for (const k of Object.keys(v))
+          if (k !== "model" && k !== "effort") out.rejected.push(`agents.per_agent.${name}.${k}`);
         if (typeof v.model === "string" && v.model) out.agents.per_agent[name] = v.model;
+        if (typeof v.effort === "string" && v.effort) out.efforts.per_agent[name] = v.effort;
       }
     } else out.rejected.push("agents.per_agent");
   }
@@ -264,9 +271,22 @@ export function resolveAgentModel(projectDir, name, { harness = overlayId() } =
   return { name, model: null, source: null, overlay: o.path, harness };
 }
 
+// The same two terms for effort, on their own (the effort ADR, decision 1): an
+// agent's own model does not stop it taking the default's effort. Null passes
+// nothing: the frontmatter's effort, or the harness's own default, runs.
+export function resolveAgentEffort(projectDir, name, { harness = overlayId() } = {}) {
+  const o = readOverlayAt(projectDir, harness);
+  const per = o.efforts.per_agent[name];
+  if (per) return { name, effort: per, source: "per_agent", overlay: o.path, harness };
+  if (o.efforts.default) return { name, effort: o.efforts.default, source: "default", overlay: o.path, harness };
+  return { name, effort: null, source: null, overlay: o.path, harness };
+}
+
 // The one writer of an overlay: rewrites its agents block, keeps any other key
 // as it found it (doctor names them; this never silently drops a user's key).
-export function writeOverlayAt(projectDir, id, agents) {
+// `efforts` left out keeps the efforts the file holds, so a caller that
+// changes models only never drops one.
+export function writeOverlayAt(projectDir, id, agents, efforts) {
   if (!id) throw new Error("writeOverlayAt: the overlay's harness id is required");
   const path = layoutPaths(projectDir).overlay(id);
   let raw = {};
@@ -274,10 +294,13 @@ export function writeOverlayAt(projectDir, id, agents) {
     raw = JSON.parse(readFileSync(path, "utf8"));
   } catch {}
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) raw = {};
+  const e = efforts === undefined ? readOverlayAt(projectDir, id).efforts : efforts;
+  const pair = (model, effort) => ({ ...(model ? { model } : {}), ...(effort ? { effort } : {}) });
   const block = {};
-  if (agents.default) block.default = { model: agents.default };
-  const names = Object.keys(agents.per_agent || {}).sort();
-  if (names.length) block.per_agent = Object.fromEntries(names.map((n) => [n, { model: agents.per_agent[n] }]));
+  if (agents.default || e.default) block.default = pair(agents.default, e.default);
+  const names = [...new Set([...Object.keys(agents.per_agent || {}), ...Object.keys(e.per_agent || {})])].sort();
+  if (names.length)
+    block.per_agent = Object.fromEntries(names.map((n) => [n, pair(agents.per_agent?.[n], e.per_agent?.[n])]));
   const next = { ...raw };
   if (Object.keys(block).length) next.agents = block;
   else delete next.agents;

package/node_modules/projectstore/scripts/menu.mjs

@@ -12,7 +12,11 @@
 //
 // A group is { title, footer, description, items }. An item is
 //   { id, label, kind: "choice" | "text" | "info", toggle, value,
-//     display(v), tag, describe(v, changed), options(), caption() }
+//     display(v), tag, describe(v, changed), options(), caption(),
+//     indent, path }
+// where `indent` draws the label that many columns in, under the row it
+// belongs to (an agent's effort under its model), and `path` names the item
+// where its label alone would not: a frame's title and the path line.
 // where options() answers the values, each
 //   { value, label, note, description, tag, section, kind: "value" | "text" | "refresh" }
 // and caption() the values frame's footer, { text, busy } or null. A value
@@ -390,13 +394,13 @@ function valueSegs(c, m, it, mode, room) {
 }
 
 function itemRows(c, m, g, cur, mode, w) {
-  const lw = Math.max(...g.items.map((it) => wlen(it.label))) + 1;
+  const lw = Math.max(...g.items.map((it) => (it.indent || 0) + wlen(it.label))) + 1;
   const room = w - 4 - 3 - lw - 1;
   return g.items.map((it, k) => [
     cursorSeg(c, k === cur, mode),
     S(m.changed(it) ? icon(c, "update") : " ", "action"),
     S(" "),
-    S(padTo(G(c, it.label), lw), labelRole(k === cur, mode)),
+    S(padTo(" ".repeat(it.indent || 0) + G(c, it.label), lw), labelRole(k === cur, mode)),
     S(" "),
     ...valueSegs(c, m, it, mode, room),
   ]);
@@ -488,7 +492,7 @@ function detailFrame(c, m, it, fr, w, h, focus) {
   }
   const cap = focus && it.caption ? it.caption() : null;
   return frame(c, {
-    title: it.label,
+    title: it.path || it.label,
     rows,
     w,
     h,
@@ -644,7 +648,7 @@ export function renderMenu(m, { caps: c, columns = 100, rows = 30, head = "proje
   const wideEnough = columns >= STAIRCASE.min;
   if (!wideEnough) {
     // One frame: the one the keys act on, under the whole path.
-    const names = ["Settings", ...(level >= 1 ? [g.title] : []), ...(level >= 2 ? [it.label] : [])];
+    const names = ["Settings", ...(level >= 1 ? [g.title] : []), ...(level >= 2 ? [it.path || it.label] : [])];
     out([
       S(`${icon(c, "ask")} `, "action"),
       S(names.slice(0, -1).join(sep) + (names.length > 1 ? sep : ""), "explanation"),

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