model-orchestrator 0.1.34 → 1.0.0

package/src/plugin.js

@@ -19,7 +19,7 @@ export const REPO_URL = 'https://github.com/aunysillyme/model-orchestrator';
 // ROUTING.md at level 2 and 3, ORCHESTRATOR.md at level 1. Level 2 first, so
 // a project that moved up a level reads the newer file.
 export const DEFAULT_RULES = ['ai-orchestrator/ROUTING.md', 'ai-orchestrator/ORCHESTRATOR.md'];
-export const DEFAULT_TASK_BUNDLE = 'ai-orchestrator/TASK_BUNDLE.md';
+export const DEFAULT_TASK_BRIEF = 'ai-orchestrator/TASK_BRIEF.md';
 
 // route-metrics.mjs is not here on purpose: it appends a routing log to disk,
 // and the plugin ships only hooks that read. `npx model-orchestrator` still
@@ -37,7 +37,7 @@ export function pluginVars() {
     RULES_DIR_OVERRIDE_JS: "''",
     RULES_FILE_REL: DEFAULT_RULES.join(' or '),
     RULES_FILE_REL_JSON: JSON.stringify(DEFAULT_RULES[0] + ' (' + DEFAULT_RULES[1] + ' on a level 1 install)'),
-    TASK_BUNDLE_REL_JSON: JSON.stringify(DEFAULT_TASK_BUNDLE),
+    TASK_BRIEF_REL_JSON: JSON.stringify(DEFAULT_TASK_BRIEF),
     RULES_CANDIDATES_JSON: JSON.stringify(DEFAULT_RULES),
     SETUP_HINT_JSON: JSON.stringify(
       'This project has no model-orchestrator routing rules yet. Running `npx model-orchestrator` in the project root writes them (' +
@@ -59,9 +59,9 @@ export function pluginManifest() {
     name: PLUGIN_NAME,
     version: GENERATOR_VERSION,
     description:
-      'Routing for Claude Code: a hook injects your project\'s routing table on every prompt, so each task goes to the right subagent tier and fewer tokens go to the most expensive model. Ships ' +
+      'Model router for Claude Code: injects project routing rules on each prompt and provides ' +
       n +
-      ' subagents across three model tiers.',
+      ' subagents for planning, working and cheap model tiers.',
     author: { name: 'model-orchestrator maintainers', url: REPO_URL },
     homepage: REPO_URL + '#readme',
     repository: REPO_URL,
@@ -70,6 +70,15 @@ export function pluginManifest() {
   };
 }
 
+export function marketplaceManifest() {
+  return {
+    name: PLUGIN_NAME,
+    owner: { name: 'model-orchestrator maintainers', url: REPO_URL },
+    description: 'Model router for Claude Code: routing hooks and subagents for planning, working and cheap model tiers.',
+    plugins: [{ name: PLUGIN_NAME, source: './plugin', category: 'development' }]
+  };
+}
+
 // Pure: reads templates, writes nothing. Paths are posix, relative to plugin/.
 export function planPluginFiles() {
   const v = pluginVars();

package/src/postinstall.js

@@ -0,0 +1,57 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { which } from './detect.js';
+import { doctor, windowsSpawnPlan } from '../bin/cli-run.mjs';
+
+// Q1: `trust: 'positive-only'` means a definite negative is never reported
+// for this AI. Only a parsed JSON field of exactly `true` counts as signed
+// in; a failed spawn, a non-zero exit, unparsable stdout or a parsed `false`
+// all come back unknown (null), so the conditional "if you have not signed
+// in yet" step stays instead of a wrong, confident "you are not signed in".
+// Author-machine probe 2026-09-27: `claude auth status` (default JSON)
+// returned {"loggedIn":false} with exit 1 inside a working, signed-in
+// session, so a reported failure is not trustworthy either.
+function positiveOnlyVerdict(result, jsonField) {
+  if (result.error || result.signal) return null;
+  try {
+    const parsed = JSON.parse(result.stdout ?? '');
+    return parsed && typeof parsed === 'object' && parsed[jsonField] === true ? true : null;
+  } catch { return null; }
+}
+
+// Only catalogued, reliable read-only status commands may run. Vendor output
+// can contain account details, so return a verdict without printing it.
+export function signInStatus(selected, { detect = which, spawn = spawnSync, platform = process.platform } = {}) {
+  const statuses = {};
+  for (const ai of selected) {
+    const status = ai.authStatus;
+    if (!ai.bin || !status?.reliable) continue;
+    const positiveOnly = status.trust === 'positive-only';
+    const bin = detect(ai.bin);
+    if (!bin) { statuses[ai.id] = positiveOnly ? null : false; continue; }
+    try {
+      const plan = windowsSpawnPlan([bin, ...status.args], platform);
+      if (plan.refuse) { statuses[ai.id] = null; continue; }
+      const result = spawn(plan.command, plan.args, {
+        ...plan.options, shell: false, encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'], timeout: 2000, maxBuffer: 8192, windowsHide: true
+      });
+      statuses[ai.id] = positiveOnly ? positiveOnlyVerdict(result, status.jsonField || 'loggedIn')
+        : result.error || result.signal || result.status === null ? null
+        : result.status === 0 ? true : result.status === 1 ? false : null;
+    } catch { statuses[ai.id] = null; }
+  }
+  return statuses;
+}
+
+export async function installHealthCheck({ level, selected, primary, dir }) {
+  console.log('\nHealth check (doctor, binary presence only):');
+  // Use this package's implementation, never execute a retained or user-edited
+  // runner in the target directory. Only its data configuration is read.
+  const rc = await doctor(false, {
+    here: join(dir, 'bin'), primary: primary?.id, compact: true,
+    ...(level < 2 ? { config: { enabled: selected.filter(ai => ai.facts.cliRun).map(ai => ai.id), defaults: {} } } : {})
+  });
+  if (rc && rc !== 10 && rc !== 13) console.log(`  doctor could not read the installed lane configuration (exit ${rc}).`);
+  return rc;
+}

package/src/roles.js

@@ -0,0 +1,184 @@
+// Pure role assignment. The catalog supplies capabilities; this module orders
+// those facts and renders the result without probing tools or touching files.
+
+const isMain = (ai, ctx) => ai.id === ctx.primary?.id;
+const mainFirst = (ai, ctx) => isMain(ai, ctx) ? 0 : 1;
+const knownContext = (ai) => ai.facts.contextWindow?.tokens ?? null;
+const largestContext = (ai) => -(knownContext(ai) ?? -1);
+const differentFamily = (ai, ctx) => Boolean(ctx.mainFamily && ai.facts.modelFamily && ai.facts.modelFamily !== ctx.mainFamily);
+const familyFirst = (ai, ctx) => differentFamily(ai, ctx) ? 0 : 1;
+const callable = (ai, ctx) => isMain(ai, ctx) || ai.facts.cliRun === true;
+const inputRate = (ai) => ai.facts.billing === 'pay-per-token' ? ai.facts.pricing?.inPerM ?? null : null;
+const factNote = (ai, key) => ai.factNotes?.[key] ? `; ${ai.factNotes[key]}` : '';
+const billingReason = (ai) => ai.facts.billing === 'pay-per-token'
+  ? `pay-per-token billing${ai.facts.pricing?.inPerM == null ? "; check your provider's rate" : `, stated input rate ${ai.facts.pricing.inPerM} per million tokens`}`
+  : `${ai.facts.billing} billing`;
+
+export function costRank(ai) {
+  return { local: 0, free: 1, subscription: 2, 'pay-per-token': 3 }[ai.facts.billing] ?? Infinity;
+}
+
+const mainOrContext = (ai, ctx) => isMain(ai, ctx) ? 'main agent' : knownContext(ai) == null
+  ? 'selection order; context capacity is unverified'
+  : `largest known context among qualifying lanes (${knownContext(ai)} tokens)`;
+const noReview = (ctx) => ctx.mainFamily
+  ? `No AI from a different model family than ${ctx.mainFamily} is selected. Review in a fresh context on your main agent and treat the result as a self-check, not an independent review.`
+  : 'The main agent model family is unverified, so independent review cannot be established. Review in a fresh context as a self-check.';
+const noPrivate = () => 'Nothing in your stack runs on your own machine. Keep this work off every lane here.';
+const noMain = () => 'No main agent is selected.';
+
+export const ROLE_SPECS = [
+  {
+    id: 'plan', job: 'Architecture, ambiguity, unknown cause', tier: 'planning model',
+    requires: callable, prefer: [mainFirst, largestContext], fallback: 'main', why: mainOrContext
+  },
+  {
+    id: 'build', job: 'Implement a specified section', tier: 'working model',
+    requires: (ai, ctx) => ai.facts.writesFiles === true && (isMain(ai, ctx) || (ai.facts.headless === true && ai.facts.cliRun === true)),
+    prefer: [mainFirst, (ai) => ai.facts.loadsProjectRules === true ? 0 : 1, (ai) => ai.facts.agentDefinitions ? 0 : 1], fallback: 'main',
+    why: (ai, ctx) => [isMain(ai, ctx) ? 'main agent' : 'writes files, headless cli-run lane', ai.facts.loadsProjectRules === true ? 'loads project rules' : ai.facts.loadsProjectRules === null ? 'project rules inheritance is unverified' : null].filter(Boolean).join(', ')
+  },
+  {
+    id: 'review', job: 'Independent review of the final artifact', tier: 'working model',
+    requires: (ai, ctx) => ai.facts.cliRun === true && differentFamily(ai, ctx),
+    prefer: [(ai) => ai.facts.readOnlyMode === true ? 0 : 1, costRank], fallback: 'none', noneReason: noReview,
+    why: (ai, ctx) => `different model family from ${ctx.mainFamily}${ai.facts.readOnlyMode === true ? ', read-only mode available' : `, ${billingReason(ai)}`}`
+  },
+  {
+    id: 'verify', job: 'Reproduce a finding, check a definition of done', tier: 'working model',
+    requires: callable, prefer: [familyFirst, costRank, mainFirst], fallback: 'main',
+    why: (ai, ctx) => differentFamily(ai, ctx)
+      ? `different model family from the author (${ctx.mainFamily}), ${billingReason(ai)}`
+      : `${isMain(ai, ctx) ? 'main agent' : billingReason(ai)}${!ai.facts.modelFamily || !ctx.mainFamily ? '; model family is unverified' : ''}`
+  },
+  {
+    id: 'research', job: 'Current primary sources, live web or social', tier: 'working model',
+    requires: (ai) => ai.facts.liveWeb === true, prefer: [costRank], fallback: 'main',
+    why: (ai) => `states live web tools, ${billingReason(ai)}; ties follow selection order${factNote(ai, 'liveWeb')}`
+  },
+  {
+    id: 'bulk', job: 'Many similar items, cheap', tier: 'cheap model',
+    requires: (ai) => ai.facts.headless === true && ai.facts.cliRun === true,
+    prefer: [costRank, inputRate], fallback: 'main',
+    why: (ai) => `${billingReason(ai)}, headless, runs through cli-run; ties follow selection order`
+  },
+  {
+    id: 'read', job: 'Digest many files, return cited facts', tier: 'cheap model',
+    requires: () => true, prefer: [mainFirst, largestContext], fallback: 'main', why: mainOrContext
+  },
+  {
+    id: 'private', job: 'Work that must not leave the machine', tier: 'working model',
+    requires: (ai) => ai.facts.runsLocally === true, prefer: [], fallback: 'none', noneReason: noPrivate,
+    why: () => 'runs on your machine'
+  },
+  {
+    id: 'fan-out', job: 'N independent units in one call', tier: 'working model', conditional: true,
+    requires: (ai) => ai.facts.fanOut === true, prefer: [costRank], fallback: 'none',
+    why: (ai) => `one call starts several children, ${billingReason(ai)}${factNote(ai, 'fanOut')}`
+  },
+  {
+    id: 'long-context', job: 'One document larger than the main agent holds', tier: 'planning model', conditional: true,
+    requires: (ai, ctx) => ctx.mainContext !== null && knownContext(ai) !== null && knownContext(ai) > ctx.mainContext,
+    prefer: [largestContext], fallback: 'none',
+    why: (ai, ctx) => `known context of ${knownContext(ai)} tokens exceeds the main agent's ${ctx.mainContext}`
+  }
+];
+
+function routeVia(ai, primary) {
+  if (ai.id === primary?.id) return 'main-agent';
+  if (ai.facts.runsLocally === true) return 'local';
+  if (ai.facts.cliRun === true) return 'cli-run';
+  // Agent definitions belong to their own main agent. A different selected AI
+  // gets no subagent route merely because it can store such definitions.
+  return 'manual';
+}
+
+export function assignRoles({ selected, primary, detected = new Set(), plans = {} }) {
+  // PATH detection and stated plan headroom are advisory, not role qualifiers.
+  void detected;
+  void plans;
+  const ctx = { primary, mainFamily: primary?.facts.modelFamily ?? null, mainContext: primary?.facts.contextWindow?.tokens ?? null };
+  const roles = {};
+  for (const spec of ROLE_SPECS) {
+    const pool = selected.filter((ai) => spec.requires(ai, ctx));
+    if (!pool.length) {
+      if (spec.conditional) continue;
+      if (spec.fallback === 'main' && primary) {
+        const why = spec.id === 'research'
+          ? 'No selected AI states live web tools; capability is unverified. The main agent carries it; verify it has the required tools.'
+          : 'No separate lane qualifies; the main agent carries it.';
+        roles[spec.id] = { ai: primary.id, via: 'main-agent', tier: spec.tier, why };
+      } else {
+        roles[spec.id] = { ai: null, via: 'none', tier: spec.tier, why: (spec.noneReason || noMain)(ctx) };
+      }
+      continue;
+    }
+    pool.sort((a, b) => {
+      for (const key of spec.prefer) {
+        const x = key(a, ctx), y = key(b, ctx);
+        if (x != null && y != null && x !== y) return x < y ? -1 : 1;
+      }
+      return selected.indexOf(a) - selected.indexOf(b);
+    });
+    const winner = pool[0];
+    roles[spec.id] = { ai: winner.id, via: routeVia(winner, primary), tier: spec.tier, why: spec.why(winner, ctx) };
+  }
+  return { roles, unassigned: Object.entries(roles).filter(([, role]) => role.ai === null).map(([id]) => id) };
+}
+
+// `agents` is the installer's role -> installed definition name map. Keeping
+// that explicit means this pure module never guesses whether a file was written.
+export function roleRoute(roleId, assignment, { selected = [], primary = null, agents = {} } = {}) {
+  const role = assignment.roles[roleId];
+  if (!role) return null;
+  const out = { ...role };
+  const ai = selected.find((item) => item.id === role.ai);
+  if (role.ai === null) {
+    out.reason = role.why;
+  } else if (role.via === 'cli-run' && ai?.facts.cliRun === true) {
+    out.command = `cli-run ${ai.id}${['review', 'verify'].includes(roleId) && ai.facts.readOnlyMode === true ? ' --audit' : ''}`;
+  } else if (role.ai === primary?.id && primary.facts.agentDefinitions && agents[roleId]) {
+    out.agent = agents[roleId];
+  }
+  return out;
+}
+
+export function manifestRoles(assignment, context = {}) {
+  return Object.fromEntries(Object.keys(assignment.roles).map((id) => [id, roleRoute(id, assignment, context)]));
+}
+
+export function roleHow(role, { selected = [], primary = null } = {}) {
+  if (role.ai === null) return role.reason?.startsWith('Nothing in your stack') ? 'keep it off every lane here' : 'fresh-context self-check on your main agent';
+  const ai = selected.find((item) => item.id === role.ai);
+  const tier = `${role.tier} tier`;
+  if (role.command) return `\`aunx ${role.command}\`, ${tier}`;
+  if (role.via === 'local') return `${ai?.bin ? `\`${ai.bin}\`` : 'local runtime'} on your machine, ${tier}`;
+  if (ai?.facts.kind === 'chat') return `paste the work into your ${role.ai === primary?.id ? 'main agent' : 'chat app'}, ${tier}`;
+  if (role.agent) return `\`${role.agent}\` on your main agent, ${tier}`;
+  if (role.via === 'main-agent') return `on your main agent, ${tier}`;
+  return `manual handoff, ${tier}`;
+}
+
+const cell = (text) => String(text).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+export function roleTable(assignment, { selected = [], primary = null, detected = new Set(), agents = {} } = {}) {
+  const context = { selected, primary, agents };
+  const rows = ROLE_SPECS.filter((spec) => assignment.roles[spec.id]).map((spec) => {
+    const role = roleRoute(spec.id, assignment, context);
+    const ai = selected.find((item) => item.id === role.ai);
+    const name = ai ? `${ai.name}${detected.has(ai.id) ? ' (detected on PATH)' : ''}` : 'none selected';
+    return `| ${[spec.job, name, roleHow(role, context), role.why].map(cell).join(' | ')} |`;
+  });
+  return [
+    '## Your stack: who does what', '',
+    'Assigned from the AIs you selected and what each one can do. Re-run the installer to reassign.', '',
+    '| Job | Goes to | How | Why this one |', '|---|---|---|---|', ...rows
+  ].join('\n');
+}
+
+export function inferPrimary(candidates) {
+  const rank = (ai) => ai.facts.loadsProjectRules === true && ai.facts.agentDefinitions ? 0
+    : ai.facts.agentDefinitions ? 1
+      : ai.facts.kind === 'agent-cli' && ai.rulesFile ? 2
+        : ai.facts.kind === 'agent-cli' ? 3 : 4;
+  return [...candidates].sort((a, b) => rank(a) - rank(b) || candidates.indexOf(a) - candidates.indexOf(b))[0];
+}

package/src/uninstall.js

@@ -1,7 +1,9 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, openSync, readFileSync, readdirSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path';
-import { dirProblems, realRoot } from './install.js';
+import { dirProblems, globalConfigProblem, realRoot } from './install.js';
+import { START, END } from './apply-snippets.js';
+import { validateActivationOwnership } from './activation-ownership.js';
 
 const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
@@ -38,6 +40,8 @@ function entry(key, roots, directory = false) {
   }
   const abs = resolve(root, rel);
   if (!isDirRoot && (abs === root || !abs.startsWith(root + sep))) throw refused(`path leaves its target root: ${key}`);
+  const globalProblem = globalConfigProblem(abs);
+  if (globalProblem) throw refused(globalProblem);
   return { key, root, abs, directory };
 }
 
@@ -79,6 +83,95 @@ function removeFile(item, expectedHash) {
   unlinkSync(item.abs);
 }
 
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function activationEntry(key, ownership, roots) {
+  const problem = validateActivationOwnership(key, ownership);
+  if (problem) throw refused(problem);
+  const item = entry(key, roots);
+  return { ...item, ownership };
+}
+
+// Only the bytes/config entries recorded by activation belong to this install.
+// User content around a block and unrelated settings survive later edits.
+function removeActivation(item, bytes) {
+  const owned = item.ownership;
+  if (owned.kind === 'rules') {
+    let start = bytes.indexOf(START);
+    let end = bytes.indexOf(END);
+    if (start === -1 && end === -1) return { content: bytes, edited: false };
+    if (start < 0 || end < start || bytes.indexOf(START, start + START.length) !== -1 || bytes.indexOf(END, end + END.length) !== -1) return { content: bytes, edited: true };
+    end += Buffer.byteLength(END);
+    if (hash(bytes.subarray(start, end)) !== owned.blockHash) return { content: bytes, edited: true };
+    const prefix = Buffer.from(owned.addedPrefix);
+    const suffix = Buffer.from(owned.addedSuffix);
+    if (prefix.length && bytes.subarray(start - prefix.length, start).equals(prefix)) start -= prefix.length;
+    if (suffix.length && bytes.subarray(end, end + suffix.length).equals(suffix)) end += suffix.length;
+    const content = Buffer.concat([bytes.subarray(0, start), bytes.subarray(end)]);
+    return { content: owned.created && content.length === 0 ? null : content, edited: false };
+  }
+  let data;
+  try { data = JSON.parse(bytes.toString('utf8')); }
+  catch { return { content: bytes, edited: true }; }
+  if (!object(data)) return { content: bytes, edited: true };
+  let edited = false;
+  let changed = false;
+  if (owned.kind === 'hooks') {
+    if (data.hooks === undefined) return { content: bytes, edited: false };
+    if (!object(data.hooks)) return { content: bytes, edited: true };
+    for (const record of owned.hooks) {
+      const groups = data.hooks[record.event];
+      if (groups === undefined) continue;
+      if (!Array.isArray(groups) || groups.some((group) => !object(group) || !Array.isArray(group.hooks))) { edited = true; continue; }
+      let removed = false;
+      for (let index = 0; index < groups.length; index++) {
+        const group = groups[index];
+        const { hooks, ...attributes } = group;
+        if (!same(attributes, record.group)) continue;
+        const match = hooks.findIndex((hook) => same(hook, record.hook));
+        if (match === -1) continue;
+        hooks.splice(match, 1);
+        if (!hooks.length) groups.splice(index, 1);
+        changed = removed = true;
+        break;
+      }
+      if (!removed && groups.some((group) => group.hooks.some((hook) => object(hook) && hook.command === record.hook.command && same(hook.args || [], record.hook.args || [])))) edited = true;
+      if (!groups.length && !owned.originalEvents.includes(record.event)) delete data.hooks[record.event];
+    }
+    if (!owned.hadHooks && Object.keys(data.hooks).length === 0) delete data.hooks;
+  } else {
+    const servers = data[owned.key];
+    if (servers === undefined) return { content: bytes, edited: false };
+    if (!object(servers)) return { content: bytes, edited: true };
+    for (const [name, configuration] of Object.entries(owned.servers)) {
+      if (!Object.hasOwn(servers, name)) continue;
+      if (!same(servers[name], configuration)) { edited = true; continue; }
+      delete servers[name];
+      changed = true;
+    }
+    if (!owned.hadKey && Object.keys(servers).length === 0) delete data[owned.key];
+  }
+  return { content: !changed ? bytes : owned.created && Object.keys(data).length === 0 ? null : Buffer.from(JSON.stringify(data, null, 2) + '\n'), edited };
+}
+
+function applyRemoval(item, plan) {
+  const current = readRegular(item);
+  if (!current || !current.bytes.equals(plan.original)) throw refused(`file changed during uninstall: ${item.abs}`);
+  const backup = plan.backup;
+  writeFileSync(backup, current.bytes, { flag: 'wx', mode: current.stat.mode & 0o777 });
+  const last = inspect(item);
+  if (!last || last.dev !== current.stat.dev || last.ino !== current.stat.ino) throw refused(`file changed during uninstall: ${item.abs}`);
+  if (plan.content === null) unlinkSync(item.abs);
+  else {
+    const fd = openSync(item.abs, constants.O_WRONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    try {
+      const actual = fstatSync(fd);
+      if (!actual.isFile() || actual.dev !== current.stat.dev || actual.ino !== current.stat.ino) throw refused(`file changed during uninstall: ${item.abs}`);
+      ftruncateSync(fd, 0);
+      writeFileSync(fd, plan.content);
+    } finally { closeSync(fd); }
+  }
+}
+
 // Validate every path and type before removing anything. The manifest is an
 // inventory, never authority to expand the two roots supplied by the caller.
 export function uninstallFiles({ dir, project, dry = false }) {
@@ -96,6 +189,7 @@ export function uninstallFiles({ dir, project, dry = false }) {
     }
   }
   if (data.directories !== undefined && !Array.isArray(data.directories)) throw refused('manifest directories must be an array');
+  if (data.activation !== undefined && !object(data.activation)) throw refused('manifest activation must be an object');
 
   const files = Object.entries(data.files).map(([key, digest]) => {
     const item = entry(key, roots);
@@ -104,17 +198,18 @@ export function uninstallFiles({ dir, project, dry = false }) {
     return { ...item, digest };
   });
   const directories = (data.directories || []).map((key) => entry(key, roots, true));
+  const activation = Object.entries(data.activation || {}).map(([key, ownership]) => activationEntry(key, ownership, roots));
   const seen = new Set([manifest.abs]);
-  for (const item of [...files, ...directories]) {
+  for (const item of [...files, ...directories, ...activation]) {
     if (seen.has(item.abs)) throw refused(`duplicate manifest path: ${item.key}`);
     seen.add(item.abs);
     inspect(item);
   }
 
   const actions = [];
-  const backupTargets = [...files, manifest];
+  const backupTargets = [...files, manifest, ...activation];
   if (data.primary === 'claude-code') backupTargets.push(entry('[project] CLAUDE.md', roots), entry('[project] .claude/settings.json', roots));
-  for (const item of backupTargets) {
+  for (const item of new Map(backupTargets.map((target) => [target.abs, target])).values()) {
     const parent = dirname(item.abs);
     if (!inspect({ root: item.root, abs: parent, directory: true })) continue;
     const prefix = basename(item.abs) + '.bak-';
@@ -125,7 +220,27 @@ export function uninstallFiles({ dir, project, dry = false }) {
     }
   }
   const pending = [];
+  const changes = [];
   let edited = false;
+  for (const item of activation) {
+    const current = readRegular(item);
+    if (!current) { actions.push('  missing activation ' + item.abs); continue; }
+    const removal = removeActivation(item, current.bytes);
+    if (removal.edited) {
+      edited = true;
+      actions.push('  keep edited activation ' + item.abs);
+    }
+    if (removal.content !== null && removal.content.equals(current.bytes)) continue;
+    let stamp = Date.now();
+    let backup;
+    do {
+      backup = item.abs + '.bak-' + new Date(stamp).toISOString().replace(/[-:]/g, '').slice(0, 15);
+      stamp += 1000;
+    } while (existsSync(backup));
+    changes.push({ item, original: current.bytes, ...removal, backup });
+    actions.push('  backup ' + backup);
+    actions.push('  remove activation ' + item.abs);
+  }
   for (const item of files) {
     const current = readRegular(item);
     if (!current) actions.push('  missing file ' + item.abs);
@@ -142,13 +257,14 @@ export function uninstallFiles({ dir, project, dry = false }) {
 
   // Compute empty directories against the same plan used by the real run.
   // Foreign entries and kept edits prevent their parents from being removed.
-  const disappearing = new Set(pending.map((item) => item.abs));
+  const disappearing = new Set([...pending.map((item) => item.abs), ...changes.filter((plan) => plan.content === null).map((plan) => plan.item.abs)]);
+  const backupParents = new Set(changes.map((plan) => dirname(plan.backup)));
   if (!edited) disappearing.add(manifest.abs);
   const empty = [];
   directories.sort((a, b) => b.abs.split(sep).length - a.abs.split(sep).length || a.abs.localeCompare(b.abs));
   for (const item of directories) {
     if (!inspect(item)) continue;
-    if (readdirSync(item.abs).every((name) => disappearing.has(join(item.abs, name)))) {
+    if (!backupParents.has(item.abs) && readdirSync(item.abs).every((name) => disappearing.has(join(item.abs, name)))) {
       disappearing.add(item.abs);
       empty.push(item);
     }
@@ -156,7 +272,8 @@ export function uninstallFiles({ dir, project, dry = false }) {
 
   if (!dry) {
     // A changed type or symlink detected here still refuses the whole run.
-    for (const item of [...files, ...directories, manifest]) inspect(item);
+    for (const item of [...files, ...directories, ...activation, manifest]) inspect(item);
+    for (const plan of changes) applyRemoval(plan.item, plan);
     for (const item of pending) removeFile(item, item.digest);
     if (!edited) removeFile(manifest, hash(saved.bytes));
   }

package/templates/README.md

@@ -4,11 +4,28 @@ Everything the installer can write, organized by the level that adds it. Files a
 
 | Folder | Written at | Contents |
 |---|---|---|
-| `common/` | every level | the start-here README, `TASK_BUNDLE.md`, `protocols/` (build, propagate, gap analysis, deep research, numbers and logic, memory and record, docs then prove) |
+| `common/` | every level | the start-here README, `TASK_BRIEF.md`, `CONTEXT.md`, `ACCEPTANCE_CHECKS.json`, `DECISIONS.md` and indexed workflow protocols |
 | `beginner/` | every level | `ORCHESTRATOR.md`, the single-agent routing rules |
-| `agents/` | every level, one variant | the primary agent's loading surface: Claude Code subagents (plus `.claude/hooks/route-gate.mjs` and `subagent-context.mjs`, and `settings.hooks.snippet.json` to wire them in), Antigravity custom agents, or a paste snippet |
+| `agents/` | every level, one variant | the main agent's loading surface: Claude Code subagents (plus `.claude/hooks/route-gate.mjs`, `subagent-context.mjs` and `route-metrics.mjs`, and `settings.hooks.snippet.json` to wire them in), Antigravity custom agents, or a paste snippet |
 | `intermediate/` | level 2+ | `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md` |
 | `advanced/` | level 3 | `vm/`: gateway config, compose file, box rules, privacy gates, scheduled jobs |
 | `tools/` | when selected | companion tools the AIs call: `codecalc/`, `obsidian-tc/` and `context7/` (install doc + MCP snippets each). See `tools/README.md` |
 
 Agent definitions under `agents/claude-code/` and `agents/agy/` are written to the PROJECT root (`--project`), not `--dir`, because that is where those CLIs read them. A `README.md` at the root of a tier folder (like this one) documents the repo and is not installed. `common/README.md` is the exception: it is the user's start-here file. READMEs deeper in (`protocols/`, `vm/`, `vm/jobs/`) are installed as folder indexes.
+
+## Workflow protocols
+
+When editing a procedure, update its installed index in `common/protocols/README.md` too.
+
+| Protocol | Purpose |
+|---|---|
+| Build | Frame, assign, implement, audit once and verify the change in use |
+| Context file | Share one source of context across the run |
+| Acceptance checks | Verify requirements against the final artifact |
+| Decision log | Record Did / Why / Serves / Rejected |
+| Propagate | Complete shared-name and interface changes |
+| Gap analysis | Compare scope with the user's ask |
+| Deep research | Reconcile bounded research against primary sources |
+| Numbers and logic | Compute decision inputs |
+| Memory and record | Keep durable information indexed |
+| Docs then prove | Verify changing interfaces on the runtime |

package/templates/advanced/README.md

@@ -5,10 +5,10 @@ Written at level 3 only, on top of everything below it. Everything lands under `
 | File | What it is |
 |---|---|
 | `vm/README.md` | start-here for the box: what runs where, the gateway-holds-the-keys rule, the closed loop |
-| `vm/setup-vm.sh` | idempotent setup for a fresh Ubuntu box: deps, the selected CLIs; prints every vendor script instead of running it |
+| `vm/setup-vm.sh` | manual Ubuntu setup: dependencies and selected CLIs; prints vendor scripts for review. After sign-ins and secret injection, `--start-services` starts Compose and verifies the selected local lane |
 | `vm/docker-compose.yml` | the gateway (and a local model runtime if selected), bound to loopback |
 | `vm/gateway.config.yaml` | one lane per selected provider, keys referenced by environment variable NAME only |
 | `vm/ENVIRONMENT.md` | which variable names the gateway expects, and where to keep the values (a secrets manager, never a file in the repo) |
 | `vm/box-CLAUDE.md` | the rules a Claude Code session on the box inherits: cheapest tier that does the job, what never goes to the cheap tier, no public bind |
-| `vm/PRIVACY_GATES.md` | what data never leaves the machine, which lanes are barred by name |
+| `vm/PRIVACY_GATES.md` | configurable data classes, allowed and barred lanes, and the authorization check before dispatch |
 | `vm/jobs/` | a systemd timer + service pair for the weekly gap-analysis audit, plus an index |

package/templates/advanced/vm/PRIVACY_GATES.md

@@ -1,33 +1,31 @@
-# PRIVACY_GATES.md: what never leaves the machine
+# PRIVACY_GATES.md: match data to authorized lanes
 
-A bar that is not named is not enforced. Fill in the names.
+Before sending data to a lane, classify it under the project's policy and verify the lane is authorized for that class. Fill in the allowed and barred lane names before using this template with protected information.
 
 ## Data classes
 
-| Class | Examples | May go to |
+| Class | Examples | Choose |
 |---|---|---|
-| Public | published posts, open docs, public repos | any lane |
-| Working | your own notes, drafts, code you will publish | your primary vendor's lanes, subscription CLIs you trust with it |
-| Confidential | client data, other people's records, contracts | your primary vendor only, or the local lane |
-| Personal | health, identity, private journals | the local lane only, or nowhere |
+| Public | Published posts, open docs, public repositories | Any lane permitted by project policy |
+| Working | Internal drafts and unpublished code | Lanes approved for this project |
+| Confidential | Client records, contracts and restricted business data | Explicitly approved processors or a local runtime |
+| Personal | Health, identity and private journals | Explicitly authorized processing with the required privacy boundary |
 
-## Lanes barred by name for Confidential and Personal
+## Name the boundaries
 
-- metered third-party bulk lanes (the cheapest-tier API you use for volume)
-- concurrent fan-out lanes on a consumer subscription
-- any shared compute lane (free GPU tiers, notebook services)
-- any tool that stores conversation history on its own servers without a retention control you have read
-
-Write your own lane names here, in this file, so the bar is checkable:
+Record the actual tool names and the reason for each rule:
 
 ```
-BARRED: <lane>, <lane>, <lane>
+ALLOWED FOR <class>: <lane>, <lane>
+BARRED FOR <class>: <lane>, <lane>
 ```
 
-## The local lane is a privacy lane, not a cost lane
+Review a provider's retention, training and access policy before approving a new lane for protected data. Never send protected information to an unapproved bulk, fan-out or shared-compute lane.
+
+## Use the local lane for confinement
 
-Route to a local model when confinement is the requirement. Never to save money: the accuracy gap is real, and pennies saved are not worth a wrong answer that looks right.
+When data must remain on the machine, use a local runtime and verify that its tools and logging preserve that boundary. Check its task quality with the same acceptance checks used for any other lane.
 
-## The check
+## Check before dispatch
 
-Before any bulk call: which class is this data, and is the lane in the barred list? If you cannot answer both, it is Confidential.
+When a bulk call is ready, verify the data class, the selected tool and the permission that allows it. When classification or permission is unresolved, keep the data local and obtain the missing decision before dispatch.