planr 1.10.0-alpha.9 → 2.0.0

package/skills/planr/scripts/lib/runs.mjs

@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+import { posix } from 'node:path';
+import { compare, taskFile, taskStatus } from './graph.mjs';
+
+export function git(root, args, input) {
+  try {
+    const value = execFileSync('git', args, {
+      cwd: root,
+      encoding: input === undefined ? 'utf8' : undefined,
+      input,
+      maxBuffer: 64 << 20,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    return typeof value === 'string' ? value.trimEnd() : value;
+  } catch {
+    return input === undefined ? '' : Buffer.alloc(0);
+  }
+}
+
+export function runs(root, index, c, now = new Date().toISOString()) {
+  const mode = git(root, ['rev-parse', '--is-shallow-repository']);
+  const warnings = mode === 'false' ? [] : [
+    mode ? 'history: shallow clone, runs incomplete'
+      : 'history: not a git repository, runs unavailable',
+  ];
+  const prefix = git(root, ['rev-parse', '--show-prefix']) +
+    posix.normalize(c.tasksDir).replace(/\/$/, '') + '/';
+  const log = mode ? git(root, [
+    'log', '--first-parent', '--reverse', '--format=%x00PLANR%x09%H%x09%cI%x09%s',
+    '--raw', '-z', '--no-abbrev', '--no-renames', '--root', '--diff-merges=first-parent', '--', c.tasksDir,
+  ]) : '';
+  const records = [];
+  const parts = log.split('\0');
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i].replace(/^\n/, '');
+    if (part.startsWith('PLANR\t')) {
+      const [, full, date, ...subject] = part.split('\t');
+      records.push({ commit: full.slice(0, 7), date, subject: subject.join('\t'), files: [] });
+    } else if (part.startsWith(':')) {
+      const [, , , blob, status] = part.split(' ');
+      const file = parts[++i];
+      if (file?.startsWith(prefix) && taskFile(file.slice(prefix.length))) {
+        records.at(-1).files.push({ file, blob, removed: status === 'D' });
+      }
+    }
+  }
+  const hashes = [...new Set(records.flatMap(r =>
+    r.files.filter(f => !f.removed).map(f => f.blob)
+  ))];
+  const batch = hashes.length
+    ? git(root, ['cat-file', '--batch'], hashes.join('\n') + '\n')
+    : Buffer.alloc(0);
+  const blobs = new Map();
+  let cursor = 0;
+  while (cursor < batch.length) {
+    const end = batch.indexOf('\n', cursor);
+    if (end < 0) {
+      break;
+    }
+    const [hash, type, bytes] = batch.subarray(cursor, end).toString().split(' ');
+    cursor = end + 1;
+    if (type === 'blob') {
+      const size = Number(bytes);
+      blobs.set(hash, batch.subarray(cursor, cursor + size).toString('utf8'));
+      cursor += size + 1;
+    }
+  }
+  const result = [];
+  const history = new Map(index.tasks.map(t => [t.id, []]));
+  let previous = new Map();
+  const changesBetween = current => [...new Set([...previous.keys(), ...current.keys()])]
+    .sort(compare)
+    .filter(id => current.get(id) !== previous.get(id))
+    .map(id => ({ id, from: previous.get(id) ?? null, to: current.get(id) ?? 'removed' }));
+  const append = (s, current) => {
+    const changes = changesBetween(current);
+    if (changes.length) {
+      const initial = !result.length;
+      result.push({
+        commit: s.commit,
+        date: s.date,
+        subject: s.subject,
+        counts: [...current.values()].reduce((out, status) => {
+          out[status] = (out[status] ?? 0) + 1;
+          return out;
+        }, {}),
+        total: current.size,
+        initial,
+        changes: initial ? [] : changes,
+      });
+      for (const change of (initial ? [] : changes)) {
+        history.get(change.id)?.push({ run: result.length - 1, from: change.from, to: change.to });
+      }
+    }
+    previous = current;
+  };
+  for (const record of records) {
+    const current = new Map(previous);
+    for (const f of record.files) {
+      const id = f.file.slice(prefix.length, -3);
+      if (f.removed) {
+        current.delete(id);
+      } else {
+        try {
+          current.set(id, taskStatus(blobs.get(f.blob) ?? ''));
+        } catch {
+          warnings.push(`history: ${record.commit} ${f.file} unreadable, skipped`);
+        }
+      }
+    }
+    append(record, current);
+  }
+  if (mode) {
+    append({ commit: null, date: now, subject: 'Uncommitted changes' },
+      new Map(index.tasks.map(t => [t.id, t.status])));
+  }
+  const tasks = index.tasks.map(t => {
+    const h = history.get(t.id);
+    return {
+      ...t,
+      goal: index.goals.filter(g => g.state !== 'done' && g.scope.includes(t.id)).map(g => g.name),
+      history: h,
+      lastRun: h.at(-1)?.run ?? null,
+    };
+  });
+  return { runs: result, tasks, warnings };
+}

package/skills/planr/scripts/lib/version.mjs

@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs';
+
+export function version() {
+  const skill = readFileSync(new URL('../../SKILL.md', import.meta.url), 'utf8');
+  const frontmatter = skill.split(/^---\r?$/m)[1] ?? '';
+  const match = frontmatter.match(/^metadata:\r?\n  version: "([^"]+)"\r?$/m);
+  if (!match) {
+    throw Error('SKILL.md is missing metadata.version');
+  }
+  return match[1];
+}

package/skills/planr/scripts/planr.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, chmodSync, rmSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:http';
+import {
+  config, findRoot, buildIndex, json, compare, statuses, states, rewrite, nextWork,
+} from './lib/graph.mjs';
+import { boardData, render, writeBoard } from './lib/board.mjs';
+import { git, runs } from './lib/runs.mjs';
+import { version } from './lib/version.mjs';
+
+const argv = process.argv.slice(2);
+const options = {};
+const positional = [];
+const flags = ['json', 'strict', 'ready', 'serve', 'in-repo'];
+const allowed = {
+  check: ['strict'],
+  index: ['strict'],
+  list: ['status', 'track', 'owner', 'goal', 'ready'],
+  next: ['goal', 'stream'],
+  set: ['owner'],
+  goal: ['thread'],
+  board: ['out', 'serve', 'port'],
+  init: ['in-repo'],
+};
+const message = text => console.error(`planr: ${String(text).replace(/[\r\n]+/g, ' ')}`);
+const usage = text => {
+  const e = Error(text);
+  e.code = 2;
+  throw e;
+};
+const output = (value, lines = []) => options.json
+  ? console.log(json(value).trimEnd())
+  : lines.forEach(line => console.log(`planr: ${String(line).replace(/[\r\n]+/g, ' ')}`));
+
+function checked(root, c) {
+  const result = buildIndex(root, c);
+  if (result.errors.length) {
+    const e = Error(result.errors.join('; '));
+    e.code = 1;
+    e.errors = result.errors;
+    throw e;
+  }
+  return result.index;
+}
+
+function check(root, c, target) {
+  const result = buildIndex(root, c);
+  const warnings = [...result.index.warnings];
+  if (!result.errors.length) {
+    warnings.push(...runs(root, result.index, c).warnings);
+  }
+  const errors = options.strict ? [...result.errors, ...warnings] : result.errors;
+  process.exitCode = errors.length ? 1 : 0;
+  if (target) {
+    const scope = target.id ? [target.id]
+      : result.index.goals.find(g => g.name === target.name)?.scope ?? target.scope;
+    const files = [target.file, ...result.index.tasks.filter(t => scope.includes(t.id)).map(t => t.file)];
+    const relevant = warnings.filter(w =>
+      scope.some(id => w.startsWith(`${id}:`) || w.includes(`: dependency ${id} is dropped;`)) ||
+      files.some(file => w.startsWith(`${file}:`) ||
+        w.endsWith(` ${file} unreadable, skipped`) || w.endsWith(`/${file} unreadable, skipped`)
+      )
+    );
+    return {
+      index: result.index,
+      ok: !errors.length,
+      errors,
+      warnings: relevant,
+      otherWarnings: warnings.length - relevant.length,
+    };
+  }
+  output(
+    { ok: !errors.length, errors, warnings },
+    [...warnings, ...result.errors, errors.length ? 'check failed' : 'check passed']
+  );
+}
+
+function mutationOutput(value, line, validation) {
+  const { index, ...diagnostics } = validation;
+  output({ ...value, ...diagnostics }, [
+    line,
+    ...diagnostics.errors,
+    ...diagnostics.warnings,
+    ...(diagnostics.otherWarnings ? [`${diagnostics.otherWarnings} other warnings (run check)`] : []),
+  ]);
+}
+
+function init(root) {
+  const planning = options['in-repo'] ? join(root, '.planr') : root;
+  const source = fileURLToPath(new URL('../assets/templates/', import.meta.url));
+  const create = (file, content, mode) => {
+    if (existsSync(file)) {
+      return;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+    if (mode) {
+      chmodSync(file, mode);
+    }
+    message(`created ${file}`);
+  };
+  for (const [from, to] of [
+    ['tasks-README.md', 'tasks/README.md'],
+    ['goal.md', 'plans/example-goal.md'],
+  ]) {
+    create(join(planning, to), readFileSync(join(source, from)));
+  }
+  const configTemplate = options['in-repo'] ? 'in-repo.config.json' : 'planr.config.json';
+  create(join(root, 'planr.config.json'), readFileSync(join(source, configTemplate)));
+  const ignore = join(root, '.gitignore');
+  const previous = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  const entry = '.planr/board.html';
+  const lines = (previous.match(/[^\n]*\n|[^\n]+$/g) ?? []).filter(s =>
+    !['.planr/', '/.planr/', '.planr'].includes(s.trim())
+  );
+  let content = lines.join('');
+  if (!lines.some(s => [entry, '/' + entry, entry.replace(/\/$/, '')].includes(s.trim()))) {
+    content += (content && !content.endsWith('\n') ? '\n' : '') + entry + '\n';
+  }
+  if (content !== previous) {
+    writeFileSync(ignore, content);
+  }
+  const hooks = git(root, ['rev-parse', '--git-path', 'hooks']);
+  if (hooks) {
+    for (const hook of ['post-commit', 'post-merge']) {
+      const file = resolve(root, hooks, hook);
+      const old = existsSync(file) ? readFileSync(file, 'utf8') : '';
+      const generated = old.startsWith('#!/bin/sh\nentry="') && old.split('\n').length === 5 &&
+        old.endsWith('node "$entry" board >/dev/null 2>&1 || true\n');
+      if (old === '#!/bin/sh\nplanr board\n' || generated) {
+        rmSync(file);
+        message(`removed ${file}`);
+      }
+    }
+    create(
+      resolve(root, hooks, 'pre-commit'),
+      readFileSync(join(source, 'hook.sh'), 'utf8').replace('/*ENTRY*/', () =>
+        fileURLToPath(import.meta.url).replace(/["\\$`]/g, ch => '\\' + ch)
+      ),
+      0o755
+    );
+  }
+  message('initialized');
+}
+
+function serve(root, c, port) {
+  let html;
+  let version = 0;
+  let signature;
+  const scan = () => {
+    const data = [git(root, ['rev-parse', 'HEAD']), git(root, ['rev-parse', '--git-path', 'HEAD'])];
+    for (const dir of [c.tasksDir, c.goalsDir]) {
+      if (existsSync(join(root, dir))) {
+        for (const f of readdirSync(join(root, dir), { recursive: true }).sort()) {
+          try {
+            data.push(f, readFileSync(join(root, dir, f), 'utf8'));
+          } catch {
+            /* directories */
+          }
+        }
+      }
+    }
+    const head = data[1];
+    if (head && existsSync(resolve(root, head))) {
+      data.push(readFileSync(resolve(root, head), 'utf8'));
+    }
+    const next = JSON.stringify(data);
+    if (next === signature) {
+      return;
+    }
+    signature = next;
+    const page = render(boardData(root, checked(root, c), c));
+    version++;
+    html = page.replace('</body>', () => `<script>
+setInterval(async()=>{
+  try {
+    if ((await (await fetch('/version',{cache:'no-store'})).text()) !== '${version}') {
+      location.reload();
+    }
+  } catch {}
+},700);
+</script></body>`);
+  };
+  scan();
+  const timer = setInterval(() => {
+    try {
+      scan();
+    } catch (e) {
+      message(e.message);
+    }
+  }, 500);
+  const server = createServer((req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Content-Type', req.url === '/version' ? 'text/plain' : 'text/html; charset=utf-8');
+    if (!['/', '/version'].includes(req.url)) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    res.end(req.url === '/version' ? String(version) : html);
+  });
+  server.on('error', e => {
+    clearInterval(timer);
+    message(e.message);
+    process.exitCode = 1;
+  });
+  server.listen(port, '127.0.0.1', () => message(`serving http://127.0.0.1:${server.address().port}`));
+  const stop = () => {
+    clearInterval(timer);
+    server.close();
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+try {
+  if (argv.length === 1 && argv[0] === '--version') {
+    console.log(`planr ${version()}`);
+    process.exit(0);
+  }
+  if (!argv.length || (argv.length === 1 && argv[0] === '--help')) {
+    console.log(`Usage: planr <command> [options]
+
+Commands:
+  check [--strict]             Validate tasks and goals (index is a deprecated alias)
+  list [--ready]               List tasks; filter by --status, --track, --owner or --goal
+  next --goal <name>           Show ready and waiting tasks (--stream <S> also works)
+  set <id> <status>            Change task status [--owner <stream>]
+  goal <name> [<state>]        Show or change a goal [--thread <id>]
+  board [--out <file>]         Render the board [--serve] [--port <n>]
+  init [--in-repo]             Scaffold a planning repository
+
+Options: --root <dir>, --json, --help, --version`);
+    process.exit(0);
+  }
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) {
+      positional.push(argv[i]);
+      continue;
+    }
+    const key = argv[i].slice(2);
+    if (key in options) {
+      usage(`duplicate --${key}`);
+    }
+    if (flags.includes(key)) {
+      options[key] = true;
+    } else {
+      if (!argv[i + 1] || argv[i + 1].startsWith('--')) {
+        usage(`--${key} requires a value`);
+      }
+      options[key] = argv[++i];
+    }
+  }
+  const [command, id, value, ...extra] = positional;
+  if (!allowed[command]) {
+    usage('usage: planr check | list | next | set | goal | board | init');
+  }
+  for (const key of Object.keys(options)) {
+    if (!['root', 'json', ...allowed[command]].includes(key)) {
+      usage(`unknown option --${key}`);
+    }
+  }
+  const limit = ['set', 'goal'].includes(command) ? 3 : 1;
+  if (positional.length > limit || extra.length) {
+    usage('too many arguments');
+  }
+  if (command === 'set' && (!id || !statuses.includes(value))) {
+    usage('set requires a task ID and a known status');
+  }
+  if (command === 'goal' && (!id || (value && !states.includes(value)))) {
+    usage('goal requires a name and an optional known state');
+  }
+  if (command === 'next' && !!options.goal === !!options.stream) {
+    usage('next requires exactly one of --goal or --stream');
+  }
+  const root = options.root
+    ? resolve(options.root)
+    : command === 'init'
+      ? process.cwd()
+      : findRoot(process.cwd());
+  if (command === 'init') {
+    init(root);
+  } else {
+    const c = config(root);
+    if (['check', 'index'].includes(command)) {
+      if (command === 'index') {
+        message('index is deprecated, use check');
+      }
+      check(root, c);
+    } else {
+      const data = checked(root, c);
+      const goal = name => {
+        const g = data.goals.find(g => g.name === name);
+        if (!g) {
+          usage(`unknown goal ${name}`);
+        }
+        return g;
+      };
+      const lines = tasks => tasks.map(t =>
+        `${t.id} ${t.status} ${t.track} ${t.title} (unlocks ${t.unlocks})`
+      );
+      if (command === 'list') {
+        const order = ['blocked', 'decision', 'in-progress', 'review', 'open', 'done', 'dropped'];
+        const scope = options.goal ? goal(options.goal).scope : null;
+        const tasks = data.tasks
+          .filter(t =>
+            (!options.status || options.status.split(',').includes(t.status)) &&
+            (!options.track || t.track === options.track) &&
+            (!options.owner || t.owner === options.owner) &&
+            (!scope || scope.includes(t.id)) &&
+            (!options.ready || t.ready)
+          )
+          .sort((a, b) =>
+            order.indexOf(a.status) - order.indexOf(b.status) ||
+            b.waitingOn.length - a.waitingOn.length ||
+            compare(a.id, b.id)
+          );
+        output(tasks, lines(tasks));
+      } else if (command === 'next') {
+        const goals = options.goal
+          ? [goal(options.goal)]
+          : data.goals.filter(g =>
+              g.stream === options.stream && ['approved', 'running'].includes(g.state)
+            );
+        const stream = options.stream || goals[0].stream;
+        const { ready, waiting } = nextWork(data, goals, stream);
+        output(
+          { [options.goal ? 'goal' : 'stream']: options.goal || options.stream, ready, waiting },
+          ['ready', ...lines(ready), 'waiting', ...lines(waiting)]
+        );
+      } else if (command === 'set') {
+        const task = data.tasks.find(t => t.id === id);
+        if (!task) {
+          usage(`unknown task ${id}`);
+        }
+        rewrite(join(root, task.file), {
+          status: value,
+          ...(options.owner ? { owner: options.owner } : {}),
+        });
+        const validation = check(root, c, task);
+        mutationOutput(
+          { id, from: task.status, to: value }, `${id}: ${task.status} -> ${value}`, validation
+        );
+      } else if (command === 'goal') {
+        const g = goal(id);
+        let validation;
+        if (value || options.thread) {
+          rewrite(join(root, g.file), {
+            ...(value ? { state: value } : {}),
+            ...(options.thread ? { thread: options.thread } : {}),
+          });
+          validation = check(root, c, g);
+        }
+        const updated = (validation?.index ?? data).goals.find(g => g.name === id) ?? g;
+        const line = `${updated.name} ${updated.state} ${updated.done}/${updated.total}` +
+          ` thread=${updated.thread ?? '-'}`;
+        if (validation) {
+          mutationOutput(updated, line, validation);
+        } else {
+          output(updated, [line]);
+        }
+      } else if (command === 'board') {
+        if (options.port && (!/^\d+$/.test(options.port) || +options.port > 65535)) {
+          usage('port must be 0..65535');
+        }
+        message(`wrote ${writeBoard(root, data, c, options.out).file}`);
+        if (options.serve) {
+          serve(root, c, +(options.port ?? 4173));
+        }
+      }
+    }
+  }
+} catch (e) {
+  if (options.json) {
+    console.log(json({
+      ok: false,
+      errors: e.errors ?? [e.message],
+      warnings: [],
+    }).trimEnd());
+  } else {
+    message(e.message);
+  }
+  process.exitCode = typeof e.code === 'number' ? e.code : 1;
+}

package/docs/ARCHITECTURE.md

@@ -1,136 +0,0 @@
-# Planr Architecture
-
-Planr V1 is a single Rust binary with explicit module ownership. The crate stays small enough that a Cargo workspace would add more process overhead than value today, and there is only one deployable: the `planr` CLI. The source tree is split by ownership boundary inside that crate instead of using a premature workspace. Shared mutations that must behave identically across CLI, MCP, and HTTP live in one place (`src/app/application.rs`) so the three surfaces cannot drift.
-
-## Repository Layout
-
-- `src/`: the Rust CLI (module ownership below).
-- `tests/e2e.rs`: real CLI, MCP, HTTP, import, review-gate, run-log, and concurrent-pick tests.
-- `plugins/planr/`: the installable plugin payload — all ten skills, independent Claude/Cursor worker and reviewer role assets, and the per-host plugin manifests. Planr does not ship model-pinned Codex roles.
-- `.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`: marketplace manifests pointing Codex and Claude Code at `plugins/planr`.
-- `docs/`: user and contributor guides; `docs/contracts/` holds the frozen product contracts that gate CI.
-- `.planr/plans/product/planr/`: the production specification package for Planr V1, stored as a normal Planr product plan package. It is the only committed `.planr` path; all other runtime state stays local.
-- `examples/real-world-flow.md`: executable real-world operator flow.
-- `scripts/`: installer and release packaging scripts.
-- `npm/`: the npm wrapper package.
-
-## Module Ownership
-
-- `src/main.rs`: process composition root. Owns top-level module wiring, process startup, database opening, error printing, and dispatch into `App`.
-- `src/cli.rs`: CLI contract boundary. Owns `clap` command definitions, option parsing types, value enums, and command DTOs used by app dispatch.
-- `src/app/mod.rs`: application composition boundary. Owns the `App` runtime state, top-level dispatch, shared app-local row helpers, and app submodule wiring.
-- `src/app/commands.rs`: general CLI use-case orchestration. Owns project, plan, map, item, link, pick, approval, log, close, review, context, search, doctor, and shared install command handlers.
-- `src/app/grok.rs`: Grok-specific install orchestration. Owns safe project TOML reconciliation, repository workflow writes, and the explicit no-hooks result.
-- `src/app/prompts.rs`: CLI, MCP, and HTTP prompt output. Host routing prompt composition remains in `src/app/agents.rs`.
-- `src/app/flow.rs`: compound workflow boundary. Owns evidence log writing (with heartbeat folding), canonical FeatureRun settlement input normalization, the close transition core, the pick work packet, and the `done` command shared by CLI, HTTP, and MCP surfaces.
-- `src/app/git_review.rs`: Git and PR review evidence boundary. Owns worktree detection, scoped changed-file provenance, PR URL context, and dirty-worktree safety projections.
-- `src/app/mcp.rs`: MCP stdio boundary. Owns MCP protocol request routing, tool calls, resource reads, and prompt responses.
-- `src/app/packages.rs`: package import/export boundary. Owns reusable JSON templates, preview-before-import, durable ReviewGate package projections, and local-first encrypted bundle metadata.
-- `src/app/http.rs`: localhost HTTP/SSE boundary. Owns HTTP request parsing, routes, SSE stream output, and HTTP response mapping.
-- `src/app/repository.rs`: application data access helpers. Owns Planr query/update helpers over projects, plans, graph items, links, runs, logs, artifacts, events, approvals, search, and map projections.
-- `src/app/lease.rs`: worker lease ownership. Owns the single pick query (`PickFilter`: exclude, work type, plan scope), worker ownership checks, runtime heartbeat/progress/pause state, and stale-pick detection.
-- `src/app/review.rs`: ReviewGate application logic. Owns review annotations, feedback ingestion, scoped evidence, durable attempt completion, finding resolution, and gate lookup.
-- `src/app/recovery.rs`: recovery automation logic. Owns item retry policy configuration, task conditions, stale/timed-out sweeps, retry scheduling, and recovery result projections.
-- `src/app/execution_run.rs`: canonical FeatureRun and ReviewGate application boundary. Owns run phases, outcome batching and settlement, typed escalation, role leases, durable findings/re-review, and final product review projections.
-- `src/app/execution_state.rs`: canonical `planr.execution_state.v2` read boundary. It projects one run-scoped FeatureRun, active batch, role owner, persisted budget amounts/provenance/digest/deadline, ReviewGate, attempts, findings, stable reason code, and next action for CLI, MCP, HTTP, pick, trace, status, recovery, package, and audit consumers.
-- `src/app/surfaces.rs`: non-CLI runtime surfaces. Owns trace, scrub, artifact, event, debug, export, and import command handlers.
-- `src/app/inspection.rs`: local inspection helpers. Owns debug bundles, context/link snapshots, pick context, secret scans, export value assembly, run recording, search results, and Planr-directory import parsing.
-- `src/app/audit.rs`: goal contract audit boundary. Owns the clause-by-clause `plan audit` verdict (items settled, required independent material reviews, exactly one current independent final product review, approvals clear, canonical Evidence coverage) and its human rendering. Claim-only verification logs remain isolated to frozen pre-Evidence compatibility.
-- `src/app/application.rs`: shared surface-mutation boundary. Owns the approval request/approve/deny, context, log, artifact, and close mutations reused verbatim by CLI, MCP, and HTTP handlers so the three surfaces cannot drift.
-- `src/app/repository/`: focused data-access submodules (`item.rs`, `plan.rs`, `project.rs`, `link.rs`, `context.rs`, `evidence.rs`, `execution_run.rs`, `search.rs`) split out of `src/app/repository.rs` by entity ownership. Execution-state reads select ReviewGates strictly by run id; project/plan-wide history is never projected as the current run.
-- `src/model.rs`: JSON-facing data transfer types and typed vocabulary. Owns serializable Planr DTOs plus the `ItemStatus`, `WorkType`, `LinkKind`, and `ApprovalStatus` enums with their parsing and display behavior, used by CLI JSON, MCP, HTTP, storage rows, and tests.
-- `src/storage/mod.rs`: SQLite connection boundary. Owns default database path, connection setup, pragma configuration, and storage submodule exports.
-- `src/storage/schema.rs`: SQLite schema boundary. Owns DDL, additive schema upgrade helpers, and schema version recording.
-- `src/storage/execution_run_schema.rs`: the sole persisted compatibility boundary for FeatureRun rollout. It upgrades already-stored review/fix history into durable terminal history, but no application, packet, agent asset, or documentation path produces the superseded live shape.
-- `src/storage/rows.rs`: SQLite row mapping boundary. Owns row-to-DTO and row-to-JSON mapping functions.
-- `src/planpack.rs`: Markdown package generation and parsing. Owns project context templates, product/build plan templates, plan metadata parsing, hashes, search body extraction, and task extraction.
-- `src/agents.rs`: agent profile registry core. Owns `.planr/agents.toml` parsing, registry validation warnings, and the pure advisory `resolve_route` precedence logic (override > work_type > plan > default); no storage or host concerns.
-- `src/usage_policy.rs`: provider-neutral Usage Policy v1 core. Owns strict `.planr/policy.toml` parsing, policy and task-contract vocabulary, materiality classification, budget/concurrency validation, and the pure five-way transition resolver; it contains no provider ids, host dispatch, or execution-permission behavior.
-- `src/execution_policy.rs`: execution admission core. Owns per-role filesystem, network, tool/MCP, structured command, environment, hook, secret, and approval grants; permission-diff previews; bounded task-contract admission; fail-closed command grammar; and isolated write-scope concurrency. It never selects models or mutates graph state. `src/app/policy.rs` binds that pure decision to the current SQLite lease owner and pick token, and only treats an admission from that exact lease generation as authoritative.
-- `src/route_audit.rs`: provider-neutral run-observation contract. Owns strict requested/resolved/effective route stages, model/effort/fork enforcement confidence, transition provenance, policy/binding versions, and per-dimension metering confidence. It rejects requested-only values in the effective stage rather than inferring host execution.
-- `src/app/agents.rs`: routing application boundary. Owns the `agents` and `item route` command handlers, the shared `*_value` JSON shapes reused by MCP, per-item route facts assembly, and registry-aware role content selection for installs.
-- `src/app/agents_init.rs`: registry bootstrap boundary. Owns `planr agents init` — the static cost-tiering scaffold and, per the agent-pool plan, the flag-spec builder and interactive wizard.
-- `src/integrations.rs`: shared agent-client descriptor boundary. Owns MCP install metadata, tool schemas, resources, and text response wrapping.
-- `src/integrations/grok.rs`: document-preserving Grok project MCP configuration and conflict policy.
-- `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
-- `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
-
-## FeatureRun Execution Boundary
-
-Every live worker decision is a typed work packet:
-
-- `kind: "outcome"` is ordinary maker work; `mode: "finding_repair"` returns named findings to the same responsible maker and ReviewGate without creating a fix item.
-- `kind: "review_gate"` is independently leased checker work. Attempts and findings remain children of that gate, never graph items.
-- `kind: "verification"` is a coordinator-owned verifier lease over a frozen canonical source digest. Product source is read-only; trusted Evidence can commit only through the source-checked Evidence transaction. The coordinator calls `evidence verify` without another model.
-- Releasing verification is an application-owned transition: the item lease, FeatureRun verifier role, and verification budget reconcile atomically back to `source_frozen`. `pick release --repair <reference>` additionally invalidates the frozen candidate and routes a fresh repair batch to the recorded maker; the failed verifier lease is never resumed.
-- An accepted material checkpoint is source-bound after any product or admission repair. Repair settlement preserves the prior attempt, reopens the same gate with the active freeze revision/digest and repair-obligation lineage, and leaves verification unleaseable until a fresh independent acceptance of that exact binding.
-- `kind: "hold"` is an admission or capability stop. A driver must report its classification and next action; it cannot reinterpret the hold as permission to replace the maker, weaken verification, or open an ad hoc review.
-
-All four packets embed the same run-scoped `planr.execution_state.v2` projection. Host skills, generated roles, installed copies, and Stop hooks render that state but own no lifecycle or budget policy. Ordinary maker settlement uses plain `planr done`; only an allowed protected-risk interrupt uses structured escalation. Review findings are logged and resolved on the existing gate. Evidence runs once after stable source freeze and selectively reruns only invalidated obligations after a product repair.
-
-The one exception is persisted database input in `src/storage/execution_run_schema.rs`. Existing user databases may contain historical review/fix graph rows, so the schema upgrade consumes them once into terminal history. That read boundary does not justify aliases, fallback commands, dual DTOs, or live legacy producers elsewhere.
-
-## Planr 2.0 Immutable Budget Boundary
-
-The Planr 2.0 budget authority is one immutable `planr.feature_run_budget_contract.v2` created atomically with each FeatureRun. Bounded contracts contain a persisted UTC run-start anchor, complete wall-seconds/tool-call/token totals, exact maker/verification/review/repair/release allocations, per-dimension metering requirements, and a canonical digest. Unbounded mode is an explicit contract with no numeric limits or reserves. Every admitted bounded task carries positive maxima for all three dimensions and an overflow-checked absolute UTC deadline.
-
-Ownership is singular and dependencies are one-way:
-
-- `src/usage_policy.rs` owns the provider-neutral contract types, validation, provenance, phase protection, snapshots, and pure checked arithmetic.
-- `src/execution_policy.rs` owns pure admission over typed concurrency plus persisted budget snapshots.
-- `src/app/execution_run.rs` resolves authored policy once and binds the immutable contract to run creation.
-- `src/app/feature_run_evidence.rs` owns transactional reservation, append-only observation, reconciliation, phase release, and hold sequencing.
-- `src/app/execution_state.rs` owns the sole `planr.execution_state.v2` projection reused by CLI, MCP, HTTP, work packets, trace, status, generated roles, and skills.
-- Storage owns insert-only persistence and integrity mechanics; host adapters only enforce supplied maxima/deadlines and report observations with provenance.
-
-Runtime decisions never reload `.planr/policy.toml`, fabricate allowances, infer trusted usage from projections, synthesize missing active-run state, or expose a compatibility budget DTO. Missing, invalid, corrupt, or unenforceable budget state is a typed hold before dispatch.
-
-An incompatible active FeatureRun is retired only through the plan-scoped application lifecycle in `src/app/execution_run.rs`. Pure eligibility and policy-cancel state changes live in `src/execution_run.rs`; `src/app/repository/execution_run.rs` ends the batch and leases, updates the run with optimistic concurrency, and records provenance in one transaction. CLI, MCP, and HTTP only transport the closed `incompatible-budget` reason and reuse the canonical result. Restart never writes a budget contract or successor run; a later ordinary pick remains the sole atomic run-plus-contract creation path.
-
-A compatible budget-held FeatureRun resumes only through `planr run resolve-budget-hold --plan <id>`, owned by `src/app/feature_run_evidence.rs`. The application transaction revalidates the immutable contract, persisted snapshot, active reservation deadlines, exact held phase, canonical role owner, and lease generation before restoring that phase. Incompatible contracts require restart; capability holds, corrupt state, expired deadlines, missing reservations, unrepaired ceilings, and owner mismatches remain held. MCP and HTTP transport the same typed application result without policy or arithmetic.
-
-## Eval Contract V1/V1.1 Ownership
-
-The frozen product contract lives in `docs/contracts/EVAL_CONTRACT_V1.md` until implementation promotes it into code. Its V1.1 efficiency-evidence amendment is additive and keeps the same owner split:
-
-- repository EvalSuite manifests and fixtures are authored inputs;
-- the suite loader owns validation, safe path resolution, normalization, canonical ordering, and digests;
-- SQLite owns immutable suite snapshots, runs, case results, samples, attempt lineage, metering-basis provenance, comparisons, invalidations, rescoring provenance, and eval evidence references;
-- the comparison engine owns verdicts, reason codes, matched effective-treatment compatibility, and derived failure-inclusive efficiency metrics;
-- existing map/log/review/approval state remains authoritative for work closure, so eval evidence may support a review but must never close or reopen items by itself.
-
-## Boundary Rules
-
-- Command parsing belongs in `src/cli.rs`; process startup belongs in `src/main.rs`; command execution belongs under `src/app/`.
-- `src/main.rs` must stay small enough to be only a composition root. It must not own product use cases.
-- `src/app/mod.rs` must stay small enough to wire runtime state and dispatch. It must not absorb app submodule behavior.
-- SQLite schema belongs in `src/storage/schema.rs`; row mapping belongs in `src/storage/rows.rs`; app data access helpers belong in `src/app/repository.rs` and its submodules.
-- Mutations shared by more than one surface (CLI, MCP, HTTP) belong in `src/app/application.rs`; surface handlers must call the shared helper instead of repeating SQL.
-- Markdown templates belong in `planpack.rs`; command handlers should request generated file sets instead of embedding large template bodies.
-- Agent install metadata and MCP schema descriptors belong in `src/integrations.rs`; client-specific strings should not drift across command handlers and docs.
-- General graph DTO and vocabulary-enum changes belong in `src/model.rs`; FeatureRun/ExecutionBatch/ReviewGate status projection changes belong in `src/app/execution_state.rs`. JSON response shapes reuse those owners before adding ad hoc maps.
-- Item status, work type, link kind, and approval status values are typed enums; new states must be added to the enum, not smuggled in as strings.
-- Utility code must stay narrow. If a helper starts owning product behavior, move it to the owning module instead of growing `util.rs`.
-- Do not add catch-all `common`, `shared`, or broad utility modules. New modules must name a durable ownership boundary.
-
-## Single-Crate Decision
-
-Planr remains a single crate for V1 because:
-
-- one crate owns the CLI and its optional companion executables;
-- the current behavior contract is tighter when CLI, MCP, HTTP, storage, and docs ship together;
-- module-level ownership gives the needed architecture separation without duplicating Cargo settings or release packaging;
-- npm, release, and external consumer tests treat `planr` as the product entry point. They also package provider-specific companion executables when Planr ships them.
-
-A Cargo workspace was tried and reverted: it produced anemic crates whose only job was being a layer, plus re-export shims in the binary. A workspace should be introduced only after a concrete deployable, reuse, compilation, or team ownership boundary exists and package/release scripts are updated in the same change.
-
-## Future Extract Points
-
-If Planr grows past the V1 binary shape, the first clean extraction path is:
-
-- `planr-core`: `model.rs`, graph invariants, plan package contracts, and pure use-case types.
-- `planr-storage`: `src/storage/*`, storage repositories, schema upgrades, and import/export packages.
-- `planr-cli`: `src/cli.rs`, human output, and install helpers.
-- `planr-server`: `src/app/http.rs`, `src/app/mcp.rs`, and runtime server adapters.
-
-Do not extract those crates until a real reuse, compile-time, or ownership boundary exists. Every extraction must leave a real owner with runtime code, tests, and one-way dependencies.