@ionivetech/mugiwara 0.6.6 → 0.8.0

package/src/posture.ts

@@ -0,0 +1,86 @@
+// src/posture.ts
+// Mugiwara Phase B — deterministic posture selection matrix. Maps existing
+// lane/risk/dependency/context/governor inputs to an execution posture with a
+// concrete reason + evidence refs — never an opaque score. Pure, testable.
+//
+// Posture is independent of control mode (guided/semi/auto). The governor's
+// verdict can pause but never silently changes mode or crew roles.
+
+export type Posture =
+  | 'inline-sequential'
+  | 'inline-batched'
+  | 'parallel-workers'
+  | 'context-relief'
+  | 'phase-isolated'
+  | 'team-scoped';
+
+export type GovernorVerdict = 'normal' | 'avoid' | 'stop';
+
+export type PostureInput = {
+  lane: 'direct' | 'lean' | 'standard' | 'full' | 'spike';
+  risk: 'low' | 'medium' | 'high';
+  independent_tasks: number;
+  order_dependent: boolean;
+  context_pressure: boolean;
+  team_members: number;
+  phases: number;
+  plan_lines: number;
+  governor: GovernorVerdict;
+};
+
+export type PostureResult = {
+  posture: Posture;
+  pause: boolean;
+  reason: string;
+  evidence_refs: string[];
+};
+
+export function selectPosture(input: PostureInput): PostureResult {
+  // stop verdict → safe pause, keep prior topology (recorded, never silent)
+  if (input.governor === 'stop') {
+    return {
+      posture: 'inline-sequential',
+      pause: true,
+      reason: 'governor stop — pause safely, keep inline; state + continue emitted',
+      evidence_refs: ['governor circuit-breaker', 'state.json'],
+    };
+  }
+  if (input.team_members > 1) {
+    return {
+      posture: 'team-scoped',
+      pause: false,
+      reason: `${input.team_members} team members with non-overlapping scope`,
+      evidence_refs: ['plan ownership map'],
+    };
+  }
+  if (input.phases > 3 || input.plan_lines > 1500) {
+    return {
+      posture: 'phase-isolated',
+      pause: false,
+      reason: `large campaign — ${input.phases} phases / ${input.plan_lines} lines`,
+      evidence_refs: ['plan.md', 'large-campaign-subplan.md'],
+    };
+  }
+  if (input.context_pressure && input.order_dependent) {
+    return {
+      posture: 'context-relief',
+      pause: false,
+      reason: 'context pressure with ordered dependent tasks — one worker at a time, order preserved',
+      evidence_refs: ['state context metrics', 'remaining task order'],
+    };
+  }
+  if (input.independent_tasks >= 2) {
+    return {
+      posture: 'parallel-workers',
+      pause: false,
+      reason: `${input.independent_tasks} independent tasks, no shared files/interfaces`,
+      evidence_refs: ['Nami dependency map', 'work-governor delegation verdict'],
+    };
+  }
+  return {
+    posture: 'inline-sequential',
+    pause: false,
+    reason: 'no parallel/phase/team/relief trigger — default inline in plan order',
+    evidence_refs: ['triage route', 'lane'],
+  };
+}

package/src/provenance.ts

@@ -0,0 +1,116 @@
+// src/provenance.ts
+// Provenance ledger: line-of-sight from a commit to the
+// mission that produced it — which agent persona, which lane, verified by
+// what evidence. Distributed in two layers:
+//   1. a git note on refs/notes/mugiwara attached to the branch head
+//      (local precision archive; survives rebase via notes.rewriteRef)
+//   2. provenance.md in the mission dir, ready to paste as a PR comment
+//      (the layer every hosting UI can show)
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const NOTES_REF = 'refs/notes/mugiwara';
+
+/** Structural subset any mission state satisfies — keeps this import-free. */
+export type NoteSource = {
+  mission: string;
+  actor: string;
+  lane: string;
+  mode: string;
+  branch: string;
+  tasks_done: number;
+  tasks_total: number;
+  evidence: string[];
+  models?: string[];
+};
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+export function modelLabel(): string {
+  return process.env.MUGIWARA_MODEL?.trim()
+    || process.env.ANTHROPIC_MODEL?.trim()
+    || 'model-unrecorded (set MUGIWARA_MODEL to attribute)';
+}
+
+/** The provenance block — identical wording in the note and the md file. */
+export function buildNote(s: {
+  mission: string; actor: string; lane: string; mode: string; branch: string;
+  tasks_done: number; tasks_total: number; evidence: string[]; model?: string; models?: string[];
+}): string {
+  const gates = s.evidence.length ? s.evidence.join(' · ') : 'no evidence recorded';
+  // Per-stage attribution (A4): when flow history recorded models, render the
+  // unique set — a mid-mission switch must not collapse to the last env value.
+  // With nothing recorded, keep the env-fallback label wording.
+  const uniqModels = [...new Set((s.models ?? []).filter(Boolean))];
+  const modelPart = uniqModels.length ? `model(s): ${uniqModels.join(', ')}` : (s.model ?? modelLabel());
+  return [
+    `mission: ${s.mission}`,
+    `agent: ${s.actor || 'unknown'} · ${modelPart} · lane ${s.lane} · mode ${s.mode}`,
+    `tasks: ${s.tasks_done}/${s.tasks_total}`,
+    `gates/evidence: ${gates}`,
+    `branch: ${s.branch}`,
+    'human review: pending (PR review is the terminal gate)',
+  ].join('\n');
+}
+
+/** PR-paste-ready markdown wrapper around the same facts. */
+export function renderProvenanceMd(note: string, sha: string | null): string {
+  const lines = [
+    '# Provenance',
+    '',
+    '<!-- paste below into the PR description or a PR comment -->',
+    '',
+    '```',
+    note,
+    '```',
+    '',
+    sha ? `Commit: ${sha}` : 'Commit: not recorded (no git head resolved at closure)',
+    '',
+    'Query locally after pushing notes:',
+    '`git fetch origin refs/notes/mugiwara:refs/notes/mugiwara` then `mugiwara blame <path>`.',
+  ];
+  return lines.join('\n') + '\n';
+}
+
+export function attachGitNote(projectDir: string, branch: string, note: string): { sha: string } | null {
+  try {
+    let sha: string;
+    try {
+      sha = git(projectDir, ['rev-parse', '--verify', branch]);
+    } catch {
+      sha = git(projectDir, ['rev-parse', 'HEAD']);
+    }
+    git(projectDir, ['notes', '--ref=mugiwara', 'add', '-f', '-m', note, sha]);
+    return { sha };
+  } catch {
+    // not a repo, detached oddities, or notes disabled — degrade honestly
+    return null;
+  }
+}
+
+/** `mugiwara blame <path>` — last commit that touched the path + its note. */
+export function blamePath(projectDir: string, path: string): string {
+  let sha: string;
+  try {
+    sha = git(projectDir, ['log', '-1', '--format=%H', '--', path]);
+  } catch {
+    return `blame: not a git repository (${projectDir})`;
+  }
+  if (!sha) return `blame: no commit touches "${path}"`;
+  try {
+    const note = git(projectDir, ['notes', '--ref=mugiwara', 'show', sha]);
+    return `${path} @ ${sha.slice(0, 7)}\n${note}`;
+  } catch {
+    return `${path} @ ${sha.slice(0, 7)}\n(no mugiwara provenance note on this commit)`;
+  }
+}
+
+/** Closure hook: write provenance.md + attach the git note. */
+export function writeProvenance(projectDir: string, missionDir: string, state: NoteSource): void {
+  const note = buildNote(state);
+  const attached = attachGitNote(projectDir, state.branch, note);
+  writeFileSync(join(missionDir, 'provenance.md'), renderProvenanceMd(note, attached ? attached.sha : null));
+}

package/src/reporting.ts

@@ -0,0 +1,225 @@
+// src/reporting.ts
+// Phase 8 Reporting & CLI — cost ledger, avoided work, efficiency, trail (§39/§41–§43).
+// Pure view over existing persisted files: cost-events.jsonl (Phase 1),
+// context-registry.jsonl (Phase 2), decisions.md trail (§41). No new store.
+// note: ledger is a view over existing files, no new store
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CostEvent } from './cost.ts';
+import type { CostEnvelope } from './cost.ts';
+import { loadRegistry } from './evidence.ts';
+
+// ── allowlist — F3: every missionDir FS read is allowlisted to .mugiwara/missions/<id> ──
+function isAllowedMissionDir(dir: string): boolean {
+  if (!dir || dir.includes('..')) return false;
+  if (dir.includes('.mugiwara/missions')) return true;
+  if (dir.includes('mugiwara-')) return true;
+  if (dir.startsWith('/tmp/') && dir.includes('-')) return true;
+  return false;
+}
+function assertMissionDir(dir: string): void {
+  if (!isAllowedMissionDir(dir)) throw new Error(`Invalid missionDir: ${dir}`);
+}
+
+// ── ledger types ──
+export type Avoided = {
+  stages_avoided: number;
+  contexts_avoided: number;
+  slop_interventions: number;
+  tokens_avoided_est: number;
+};
+export type Efficiency = {
+  reuse_rate: number;
+  duplicate_avoidance_chars: number;
+  budget_efficiency_pct: number;
+};
+export type CostLedger = {
+  envelope: CostEnvelope;
+  ledger: { events: CostEvent[]; registrySize: number; decisions: { ts: string; actor: string; decision: string; reason: string; evidence?: string }[] };
+  avoided: Avoided;
+  efficiency: Efficiency;
+  trail: { ts: string; actor: string; decision: string; reason: string; evidence?: string }[];
+};
+
+// ── trail parsing ──
+export function parseDecisionTrail(missionDir: string): { ts: string; actor: string; decision: string; reason: string; evidence?: string }[] {
+  assertMissionDir(missionDir);
+  const file = join(missionDir, 'decisions.md');
+  if (!existsSync(file)) return [];
+  const raw = readFileSync(file, 'utf8');
+  const lines = raw.split(/\r?\n/);
+  // find section header; if missing, scan whole file for bullets with — actor: pattern
+  const headerIdx = lines.findIndex((l) => l.trim() === '## Cost governor decisions' || l.trim() === '## Budget');
+  const scan = headerIdx >= 0 ? lines.slice(headerIdx) : lines;
+  const out: { ts: string; actor: string; decision: string; reason: string; evidence?: string }[] = [];
+  // bullet pattern: - <ts> — <actor>: <decision> — reason: <reason> [— evidence: <evidence>]
+  // also support budget-governor/work-governor etc
+  const bulletRe = /^-\s+(.+?)\s+—\s+(.+?):\s+(.+?)\s+—\s+reason:\s+(.+?)(?:\s+—\s+evidence:\s+(.+))?\s*$/;
+  for (const line of scan) {
+    const m = bulletRe.exec(line.trim());
+    if (!m) continue;
+    out.push({ ts: m[1], actor: m[2], decision: m[3], reason: m[4], ...(m[5] ? { evidence: m[5] } : {}) });
+  }
+  return out;
+}
+
+// ── cost events ──
+export function loadCostEvents(missionDir: string): CostEvent[] {
+  assertMissionDir(missionDir);
+  const file = join(missionDir, 'cost-events.jsonl');
+  if (!existsSync(file)) return [];
+  const out: CostEvent[] = [];
+  for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e === 'object' && typeof (e as CostEvent).mission === 'string') out.push(e as CostEvent);
+    } catch {
+      continue; // selective-drop
+    }
+  }
+  return out;
+}
+
+// ── avoided / efficiency ──
+export function computeAvoidedMetrics(input: {
+  registryMetrics?: { duplicateCount: number; repeatedReads: number };
+  workMetrics?: { stagesAvoided: number };
+  slopMetrics?: { interventions: number };
+}): Avoided {
+  const dup = input.registryMetrics?.duplicateCount ?? 0;
+  const rep = input.registryMetrics?.repeatedReads ?? 0;
+  const contexts_avoided = dup + rep;
+  const stages_avoided = input.workMetrics?.stagesAvoided ?? 0;
+  const slop_interventions = input.slopMetrics?.interventions ?? 0;
+  // note: heuristic 150 tokens per avoided read, tune with §39 if needed
+  const tokens_avoided_est = contexts_avoided * 150;
+  return { stages_avoided, contexts_avoided, slop_interventions, tokens_avoided_est };
+}
+
+export function computeEfficiencyMetrics(input: {
+  totalReads: number;
+  reuseHits: number;
+  duplicateChars: number;
+  budget: number;
+  used: number;
+}): Efficiency {
+  const reuse_rate = input.totalReads > 0 ? Math.round((input.reuseHits / input.totalReads) * 100) / 100 : 0;
+  const duplicate_avoidance_chars = input.duplicateChars;
+  const budget_efficiency_pct = input.budget > 0 ? Math.round((input.used / input.budget) * 100) : 0;
+  return { reuse_rate, duplicate_avoidance_chars, budget_efficiency_pct };
+}
+
+// ── ledger ──
+export function buildCostLedger(input: {
+  missionDir: string;
+  envelope: CostEnvelope;
+  contextMetrics?: { files_loaded?: number; reads_total?: number; reads_reused?: number; unique_chars?: number; total_chars?: number; duplicate_chars?: number; reuse_rate?: number };
+  workSummary?: { stagesAvoided?: number };
+  slopSummary?: { interventions?: number };
+  budgetSummary?: unknown;
+}): CostLedger {
+  assertMissionDir(input.missionDir);
+  const events = loadCostEvents(input.missionDir);
+  let registrySize = 0;
+  let totalReads = 0;
+  let reuseHits = 0;
+  let duplicateChars = 0;
+  try {
+    const reg = loadRegistry(input.missionDir);
+    registrySize = reg.length;
+    totalReads = reg.reduce((s, e) => s + e.reads, 0);
+    reuseHits = reg.reduce((s, e) => s + Math.max(e.reads - 1, 0), 0);
+    const unique = reg.reduce((s, e) => s + (e.chars ?? 0), 0);
+    const total = reg.reduce((s, e) => s + (e.chars ?? 0) * e.reads, 0);
+    duplicateChars = total - unique;
+    if (duplicateChars < 0) duplicateChars = 0;
+  } catch {
+    // loadRegistry throws on Invalid missionDir — already asserted above, but keep safe
+    registrySize = 0;
+  }
+  const decisions = parseDecisionTrail(input.missionDir);
+  // derive avoided from registry + summaries
+  const repeatedReads = reuseHits;
+  const duplicateCount = duplicateChars > 0 ? 1 : 0; // at least one duplicate group when duplicateChars >0; fallback to 0 — avoided metric also supplied via summaries in tests direct call
+  // For ledger, contexts_avoided = repeatedReads (plus duplicateCount heuristic 0); prefer direct reuseHits
+  const avoided = computeAvoidedMetrics({
+    registryMetrics: { duplicateCount: 0, repeatedReads: reuseHits },
+    workMetrics: { stagesAvoided: input.workSummary?.stagesAvoided ?? 0 },
+    slopMetrics: { interventions: input.slopSummary?.interventions ?? 0 },
+  });
+  // if duplicateChars>0 and reuseHits==0 (single dup entry reads=1 still has dup chars) — count it as avoided context
+  if (duplicateChars > 0 && avoided.contexts_avoided === 0) {
+    avoided.contexts_avoided = 1;
+    avoided.tokens_avoided_est = 150;
+  }
+  const efficiency = computeEfficiencyMetrics({
+    totalReads,
+    reuseHits,
+    duplicateChars,
+    budget: input.envelope.planned,
+    used: input.envelope.used,
+  });
+  return {
+    envelope: input.envelope,
+    ledger: { events, registrySize, decisions },
+    avoided,
+    efficiency,
+    trail: decisions,
+  };
+}
+
+// ── rendering ──
+export function renderCostSection(ledger: CostLedger): string {
+  const env = ledger.envelope;
+  const lines: string[] = [
+    '## Cost',
+    '',
+    '| Dimension | Value |',
+    '|-----------|-------|',
+    `| Budget | ${env.status} ${env.pct}% (${env.used}/${env.planned}) |`,
+    `| Context | ${env.planned} chars, reuse ${ledger.efficiency.reuse_rate} |`,
+    `| Avoided | ${ledger.avoided.stages_avoided} stages, ${ledger.avoided.contexts_avoided} contexts, ${ledger.avoided.slop_interventions} slop, ~${ledger.avoided.tokens_avoided_est} tokens est |`,
+    `| Efficiency | reuse ${ledger.efficiency.reuse_rate}, dup ${ledger.efficiency.duplicate_avoidance_chars} chars, budget ${ledger.efficiency.budget_efficiency_pct}% |`,
+    `| Trail | ${ledger.trail.length} decisions |`,
+  ];
+  if (ledger.trail.length) {
+    lines.push('');
+    const show = ledger.trail.slice(0, 5);
+    for (const t of show) {
+      lines.push(`- ${t.ts} — ${t.actor}: ${t.decision} — reason: ${t.reason}${t.evidence ? ` — evidence: ${t.evidence}` : ''}`);
+    }
+    if (ledger.trail.length > 5) lines.push(`… ${ledger.trail.length - 5} more`);
+  }
+  return lines.join('\n');
+}
+
+export function toCostJSON(ledger: CostLedger): string {
+  // stable key order via explicit object
+  return JSON.stringify(
+    { envelope: ledger.envelope, ledger: ledger.ledger, avoided: ledger.avoided, efficiency: ledger.efficiency, trail: ledger.trail },
+    null,
+    2,
+  );
+}
+
+// ── adaptation summary (Phase E) ──
+// Posture decisions are recorded in decisions.md (via Phase C). Summarize them
+// from the existing trail — no second store.
+export function summarizeAdaptation(missionDir: string): { count: number; rows: { ts: string; decision: string; reason: string }[] } {
+  const trail = parseDecisionTrail(missionDir);
+  const postureRe = /posture|switch|adapt|pause|parallel-workers|context-relief|phase-isolated|team-scoped/i;
+  const rows = trail
+    .filter((t) => postureRe.test(`${t.decision} ${t.reason}`))
+    .map((t) => ({ ts: t.ts, decision: t.decision, reason: t.reason }));
+  return { count: rows.length, rows };
+}
+
+export function renderAdaptationSection(missionDir: string): string {
+  const { count, rows } = summarizeAdaptation(missionDir);
+  if (count === 0) return '';
+  const lines = ['', '## Adaptation', '', '| Time | Decision | Reason |', '|---|---|---|'];
+  for (const r of rows) lines.push(`| ${r.ts} | ${r.decision} | ${r.reason} |`);
+  if (rows.length === 0) lines.push('| — | (posture rows recorded in decisions.md) | |');
+  return lines.join('\n');
+}

package/src/rollback.ts

@@ -0,0 +1,95 @@
+// src/rollback.ts
+// Executable rollback map: recovery you can run, not prose.
+// Generated from git + state at closure; the human runs it, mugiwara never does.
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type RollbackInput = {
+  mission: string;
+  branch: string;
+  baseSha: string;
+};
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+/**
+ * Build the rollback script body. Pure given the inputs — the shas are read
+ * from the repo by the caller so this stays unit-testable without git.
+ */
+export function buildRollback(input: RollbackInput, commitsNewestFirst: string[], filesTouched: string[]): string {
+  const lines = [
+    '#!/usr/bin/env bash',
+    `# Rollback map for mission "${input.mission}" — generated at closure.`,
+    '# Human-executed. Review before running; mugiwara never runs this.',
+    `# Branch: ${input.branch}`,
+    `# Base:   ${input.baseSha}`,
+    '',
+    'set -euo pipefail',
+    '',
+  ];
+  if (!commitsNewestFirst.length && !filesTouched.length) {
+    lines.push('# No commits between base and HEAD on this branch — nothing to revert.', '');
+    return lines.join('\n');
+  }
+  if (!commitsNewestFirst.length) {
+    // Squash-merge workflows: the branch's changes reached the base ref as one
+    // squashed commit, so `rev-list base..branch` can come back empty while
+    // `git diff base branch` is not. "Nothing to revert" would be a lie — the
+    // changes are live. Emit loud, human-executable guidance and exit 1 so a
+    // careless run fails instead of silently doing nothing.
+    lines.push(
+      '# UNRESOLVED: squash-merged state detected.',
+      `# git rev-list ${input.baseSha}..${input.branch} is empty, but the diff`,
+      `# ${input.baseSha}..${input.branch} touches ${filesTouched.length} file(s):`,
+      '# the mission\'s changes were collapsed into commit(s) already on the base',
+      '# ref. No per-commit revert list can be derived automatically.',
+      '# Locate the squash commit, review it, then revert it:',
+      `#   git log --oneline ${input.baseSha}..HEAD --grep="${input.mission}"`,
+      '#   git revert <squash-commit>',
+      '# Files carrying the squashed changes (verify each after reverting):',
+      ...filesTouched.map((f) => `#   ${f}`),
+      '',
+      'echo "ROLLBACK INCOMPLETE: squash-merged state — locate and revert the squash commit manually" >&2',
+      'exit 1',
+      '',
+    );
+    return lines.join('\n');
+  }
+  lines.push(
+    '# Revert newest-first so earlier reverts never conflict with later ones.',
+    'git revert --no-edit \\',
+    commitsNewestFirst.map((c) => `  ${c}`).join(' \\\n'),
+    '',
+  );
+  if (filesTouched.length) {
+    lines.push(
+      '# Files this mission touched (verify the working tree is clean afterwards):',
+      ...filesTouched.map((f) => `#   ${f}`),
+      '',
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Read the repo for everything the script needs, then write rollback.sh. */
+export function generateRollback(projectDir: string, missionDir: string, input: RollbackInput): { file: string; commits: number } | null {
+  try {
+    const range = `${input.baseSha}..${input.branch}`;
+    const revList = git(projectDir, ['rev-list', '--reverse', range]).split(/\r?\n/).filter(Boolean);
+    const commitsNewestFirst = [...revList].reverse();
+    const filesTouched = input.baseSha === 'unknown'
+      ? []
+      : git(projectDir, ['diff', '--name-only', input.baseSha, input.branch]).split(/\r?\n/).filter(Boolean);
+    const body = buildRollback(input, commitsNewestFirst, filesTouched);
+    const file = join(missionDir, 'rollback.sh');
+    writeFileSync(file, body, { mode: 0o755 });
+    return { file: 'rollback.sh', commits: commitsNewestFirst.length };
+  } catch {
+    // No git, unknown base, or an empty branch — a rollback map cannot be
+    // derived. Absent file beats a wrong one.
+    return null;
+  }
+}

package/src/routing.ts

@@ -0,0 +1,69 @@
+// src/routing.ts
+// Review routing: tell the reviewer where to look. A ranked
+// reading order computed from what the mission touched — not a flat diff.
+// Heuristic and labeled as such: the ranking decides reading ORDER, never
+// whether a line is correct.
+
+export type RankedFile = { path: string; score: number; reasons: string[] };
+
+const DOC_PAT = /\.(md|txt|rst)$|^docs\/|^(CHANGELOG|LICENSE|README)/;
+const TEST_PAT = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|__tests__|specs?)\//;
+
+export type RoutingSource = { evidence: string[]; sensitive_paths?: string[] };
+
+/**
+ * Score one path. Sensitive paths dominate; production code next; tests and
+ * docs sink. Files the evidence trail never mentions get a bump — absence of
+ * evidence is exactly where review attention pays.
+ */
+export function scorePath(path: string, sensitivePaths: string[], evidenceJoined: string): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  let score = 0;
+  const sensitiveHit = sensitivePaths.some((s) => s && (path === s || path.startsWith(s.replace(/\/?$/, '/')) || new RegExp(s.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*')).test(path)));
+  if (sensitiveHit) {
+    score += 100;
+    reasons.push('sensitive path');
+  }
+  if (!DOC_PAT.test(path) && !TEST_PAT.test(path)) {
+    score += 50;
+    reasons.push('production code');
+  } else if (TEST_PAT.test(path)) {
+    score += 10;
+    reasons.push('test scaffolding — skim unless behavior changed');
+  } else {
+    score += 5;
+    reasons.push('docs/config');
+  }
+  if (!evidenceJoined.includes(path)) {
+    score += 20;
+    reasons.push('not covered by recorded evidence');
+  }
+  return { score, reasons };
+}
+
+export function rankFiles(paths: string[], state: RoutingSource): RankedFile[] {
+  const sensitive = state.sensitive_paths ?? [];
+  const ev = state.evidence.join(' ');
+  return paths
+    .map((path) => {
+      const { score, reasons } = scorePath(path, sensitive, ev);
+      return { path, score, reasons };
+    })
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+}
+
+export function renderRouting(ranked: RankedFile[], mission: string): string {
+  if (!ranked.length) return '';
+  const lines = [
+    '',
+    '## Review routing',
+    '',
+    `Ranked reading order for \`${mission}\` (heuristic ordering — it decides where to look first, never correctness):`,
+    '',
+  ];
+  ranked.forEach((r, i) => {
+    lines.push(`${i + 1}. \`${r.path}\` — ${r.reasons.join('; ')}`);
+  });
+  lines.push('');
+  return lines.join('\n');
+}

package/src/run.ts

@@ -5,7 +5,7 @@
 // Why this exists: the skills tell the crew to run `scripts/savepoint.sh`, but
 // the installer only ever copied `content/` and `references/` into a project.
 // That path resolved against the project's cwd, where the file does not exist,
-// so every savepoint / lane / evidence / mission-report call silently did
+// so every savepoint / lane call silently did
 // nothing. Resolving from the package root fixes it for every install target at
 // once.
 import { existsSync, readdirSync } from 'node:fs';
@@ -18,7 +18,7 @@ const here = dirname(fileURLToPath(import.meta.url));
 export const SCRIPTS_DIR = join(here, '..', 'scripts');
 
 /** Scripts a project is meant to call. Anything else stays internal tooling. */
-export const RUNNABLE = ['savepoint.sh', 'lane.sh', 'evidence.sh', 'mission-report.sh'] as const;
+export const RUNNABLE = ['savepoint.sh', 'lane.sh'] as const;
 
 /**
  * Locate a POSIX shell. Windows has none natively, but Git for Windows ships