@ionivetech/mugiwara 0.7.0 → 0.8.0

package/src/evidence.ts

@@ -0,0 +1,160 @@
+// src/evidence.ts
+// Phase 2 Context Governor — content-fingerprint evidence registry
+// (Native Cost Governor initiative, plan §51 Phase 2, spec §11/§12).
+//
+// One registry enables both stable E### references (§11 reuse) and duplicate
+// detection (§12 dedup): "reuse if already available, else register E###".
+// Persisted as context-registry.jsonl — append-only JSONL beside the mission
+// state, same contract as cost-events.jsonl (append-one-line-per-entry, no
+// read-modify-write, so concurrent writers never clobber each other).
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Stable sha256 hex fingerprint of content — the dedup identity. */
+export function fingerprint(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export type RegistryKind =
+  | 'file'
+  | 'symbol'
+  | 'command'
+  | 'test'
+  | 'diff'
+  | 'evidence'
+  | 'agent_response';
+
+export type RegistryEntry = {
+  fingerprint: string;
+  kind: RegistryKind;
+  file: string;
+  range?: string;
+  id: string; // stable `E<zero-padded seq>`, monotonic, never reused (§11)
+  reads: number;
+  chars?: number; // content length held by this entry — real char payload basis
+                  // for duplicate_chars/read_avoidance_chars (§12 efficiency)
+  ref: string; // full stable reference, e.g. `E013 src/auth/middleware.ts:42-91`
+};
+
+const REGISTRY_FILE = 'context-registry.jsonl';
+
+function isAllowedMissionDir(dir: string): boolean {
+  if (!dir || dir.includes('..')) return false;
+  if (dir.includes('.mugiwara/missions')) return true;
+  // test harness tmp dirs (mkdtemp creates /tmp/<prefix>-<rand> with a dash) — allow so existing unit tests keep passing;
+  // the security test uses /tmp/evil (no dash) which stays blocked
+  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}`);
+}
+
+/** Highest numeric seq among existing ids (0 when empty). */
+function maxSeq(registry: RegistryEntry[]): number {
+  let max = 0;
+  for (const e of registry) {
+    const m = /^E(\d+)$/.exec(e.id);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return max;
+}
+
+function buildRef(id: string, file: string, range?: string): string {
+  return range ? `${id} ${file}:${range}` : `${id} ${file}`;
+}
+
+/**
+ * Register a read (reuse-or-create, §11). If fingerprint(content) already
+ * exists for the same kind → repeated: true, reads++, return the existing ref.
+ * Else append a new entry with the next monotonic `E<seq>` id (never reused
+ * across a mission) and return it with repeated: false.
+ */
+export function registerRead(
+  registry: RegistryEntry[],
+  e: { kind: RegistryKind; file: string; range?: string; content: string },
+): { ref: string; repeated: boolean } {
+  const fp = fingerprint(e.content);
+  const existing = registry.find((x) => x.fingerprint === fp && x.kind === e.kind);
+  if (existing) {
+    existing.reads += 1;
+    return { ref: existing.ref, repeated: true };
+  }
+  const seq = maxSeq(registry) + 1;
+  const id = `E${String(seq).padStart(3, '0')}`;
+  const ref = buildRef(id, e.file, e.range);
+  registry.push({
+    fingerprint: fp,
+    kind: e.kind,
+    file: e.file,
+    ...(e.range ? { range: e.range } : {}),
+    id,
+    reads: 1,
+    chars: e.content.length,
+    ref,
+  });
+  return { ref, repeated: false };
+}
+
+/** Entries with reads >= 2 — the dedup signal (§12). Optionally kind-scoped. */
+export function findRepeats(registry: RegistryEntry[], kind?: RegistryKind): RegistryEntry[] {
+  return registry.filter((e) => e.reads >= 2 && (!kind || e.kind === kind));
+}
+
+/**
+ * Append one JSON line per entry to context-registry.jsonl. Append-only: an
+ * entry already persisted is never rewritten in place; callers append the new
+ * (or re-saved) batch. mkdir-on-write like appendCostEvent.
+ */
+export function persistRegistry(missionDir: string, registry: RegistryEntry[]): void {
+  assertMissionDir(missionDir);
+  mkdirSync(missionDir, { recursive: true });
+  const file = join(missionDir, REGISTRY_FILE);
+  for (const entry of registry) {
+    appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+  }
+}
+
+/** Read the full registry from context-registry.jsonl (empty when absent). */
+export function loadRegistry(missionDir: string): RegistryEntry[] {
+  assertMissionDir(missionDir);
+  const file = join(missionDir, REGISTRY_FILE);
+  try {
+    const out: RegistryEntry[] = [];
+    // F1 — validate entry shape on load: drop malformed lines, never crash the
+    // reader, and coerce `reads` to a bounded integer. A malformed or `string
+    // reads` line (string-concat risk) can no longer reach consumers.
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      let e: unknown;
+      try {
+        e = JSON.parse(line);
+      } catch {
+        continue; // W1 — unparseable line drops only itself, never the rest
+      }
+      // W1 — a JSON literal like `null` parses but is not a registry entry.
+      if (e === null || typeof e !== 'object') continue;
+      const entry = e as RegistryEntry;
+      const ok =
+        typeof entry.fingerprint === 'string' &&
+        typeof entry.kind === 'string' &&
+        typeof entry.file === 'string' &&
+        typeof entry.id === 'string' &&
+        typeof entry.ref === 'string' &&
+        typeof entry.reads === 'number' &&
+        Number.isFinite(entry.reads) &&
+        entry.reads >= 0;
+      if (!ok) continue;
+      entry.reads = Math.floor(entry.reads);
+      out.push(entry);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}

package/src/installer.ts

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parseFrontmatter, type FrontmatterData } from './frontmatter.ts';
+import { DEFAULT_CONFIG } from './config.ts';
 import type { Scope } from './manifest.ts';
 
 export type ContentItem = {
@@ -172,22 +173,7 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     let configExists = false;
     try { configExists = lstatSync(configPath).isFile() || lstatSync(configPath).isSymbolicLink(); } catch { configExists = false; }
     if (!configExists) {
-      const body = [
-        'mode=guided',
-        'branch=feature/{type}-{issue}-{slug}',
-        'commit=conventional',
-        'auto_commit=on',
-        'coverage_new=90',
-        'coverage_modified=80',
-        'review_depth=full',
-        'quality_depth=full',
-        'verify_merged=off',
-        'delegate_threshold=60',
-        'heal_max_cycles=3',
-        'verbosity=normal',
-        '# context_budget_chars=150000  # optional: fail archive if trail exceeds this (measured in report Cost section)',
-      ].join('\n') + '\n';
-      if (!dryRun) { mkdirSync(dirname(configPath), { recursive: true }); writeFileSync(configPath, body); }
+      if (!dryRun) { mkdirSync(dirname(configPath), { recursive: true }); writeFileSync(configPath, DEFAULT_CONFIG); }
       result.written.push(configPath);
       result.notes.push(`default config written: ${configPath} (edit it to customise)`);
     }

package/src/integrity.ts

@@ -38,7 +38,7 @@ function findSecrets(body: string): Array<{ label: string; hit: string }> {
   return out;
 }
 
-const TRAIL_EXTS = new Set(['.md', '.json', '.sh']);
+const TRAIL_EXTS = new Set(['.md', '.json', '.sh', '.jsonl']);
 
 function trailFiles(dir: string): string[] {
   const out: string[] = [];

package/src/investigation.ts

@@ -0,0 +1,72 @@
+// src/investigation.ts
+// Phase 2 Context Governor — bounded investigation state machine
+// (Native Cost Governor initiative, plan §51 Phase 2, spec §13).
+//
+// Honest boundary: Phase 2 produces the verdict + the audit record; the
+// Phase-3+ consumer (Work Governor) supplies the inputs (pass state,
+// acceptance/surface/path signals, unrelated files opened, repeated reads
+// from the evidence registry) and acts on the verdict. Limits come from
+// readInvestigationConfig (T3). Stop verdicts are emitted as optimization
+// decision records via the sanitized recordOptDecision (T4's S2 fix).
+import { recordOptDecision } from './cost.ts';
+
+export type InvestigationStatus = {
+  pass: number;
+  stop: boolean;
+  reason: '' | 'max passes' | 'max unrelated files' | 'repeated read' | 'objective met';
+};
+
+export type InvestigationInput = {
+  pass: number;
+  acceptance_mapped: boolean;
+  surface_understood: boolean;
+  path_established: boolean;
+  unrelated_files_opened: number;
+  repeated_reads: number;
+  max_passes: number;
+  max_unrelated_files: number;
+  repeated_read_threshold: number;
+};
+
+/**
+ * Evaluate the investigation against the three limits (spec §13) plus the
+ * objective-met stop. Objective-met wins (stop condition first): when the
+ * acceptance is mapped, the surface understood, and the path established,
+ * the investigation stops regardless of the counters. Otherwise stop at the
+ * first limit that fires — max passes (>=), max unrelated files (>), or
+ * repeated reads (>= threshold). Else continue.
+ */
+export function evaluateInvestigation(input: InvestigationInput): InvestigationStatus {
+  const { pass } = input;
+  if (input.acceptance_mapped && input.surface_understood && input.path_established) {
+    return { pass, stop: true, reason: 'objective met' };
+  }
+  if (pass >= input.max_passes) {
+    return { pass, stop: true, reason: 'max passes' };
+  }
+  if (input.unrelated_files_opened > input.max_unrelated_files) {
+    return { pass, stop: true, reason: 'max unrelated files' };
+  }
+  if (input.repeated_reads >= input.repeated_read_threshold) {
+    return { pass, stop: true, reason: 'repeated read' };
+  }
+  return { pass, stop: false, reason: '' };
+}
+
+/**
+ * Record a stop verdict as an optimization decision when status.stop.
+ * Reuses recordOptDecision (sanitized, S2). Records nothing when not stopped.
+ */
+export function recordInvestigationStop(
+  missionDir: string,
+  status: InvestigationStatus,
+  evidence?: string,
+): void {
+  if (!status.stop) return;
+  recordOptDecision(missionDir, {
+    actor: 'cost-governor',
+    decision: 'stop investigation',
+    reason: status.reason,
+    ...(evidence ? { evidence } : {}),
+  });
+}

package/src/mission.ts

@@ -4,10 +4,15 @@ import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, writeFileSync
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { checkTrail, formatIssues } from './integrity.ts';
+import { checkMissionArtifacts } from './check-artifacts.ts';
 import { generateRollback } from './rollback.ts';
 import { writeProvenance } from './provenance.ts';
 import { rankFiles, renderRouting } from './routing.ts';
 import { formatFootprint, measureContextChars, readBudgetConfig } from './budget.ts';
+import { budgetForLane, costEnvelope, appendCostEvent } from './cost.ts';
+import { loadRegistry } from './evidence.ts';
+import { computeContextMetrics, contextStatus } from './context.ts';
+import { buildCostLedger, renderAdaptationSection } from './reporting.ts';
 
 function isStateFile(f: string): boolean {
   // state.json (solo) or <member>.json (team) — never continue*.json
@@ -122,6 +127,12 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
     if (issues.length) {
       throw new Error(`closure integrity gate failed — fix these before archiving:\n${formatIssues(issues)}`);
     }
+    // Artifact gate (roadmap v0.8 item 4): Lane 2+ missions must carry
+    // plan.md + flows/* evidence — a mission without its trail does not fold.
+    const artifacts = checkMissionArtifacts(dir);
+    if (!artifacts.ok) {
+      throw new Error(`archive artifact gate failed — missing: ${artifacts.missing.join(', ')} (lane ${artifacts.lane}). Write the evidence trail before archiving.`);
+    }
   }
 
   const files = readdirSync(dir);
@@ -142,18 +153,51 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
     const chars = measureContextChars(dir);
     const budget = readBudgetConfig(projectDir);
     const footprintLine = formatFootprint(chars, budget);
-    if (budget && chars > budget) {
-      throw new Error(`closure context budget failed — ${footprintLine}. Trim the trail or raise context_budget_chars.`);
-    }
     const est = typeof state.tokens_est === 'number' ? state.tokens_est : 0;
     const src = typeof state.tokens_source === 'string' ? state.tokens_source : 'computed';
     const lane = typeof state.lane === 'string' ? state.lane : 'unknown';
-    // lane budgets for readable delta (from lane-base.sh, mirrored here for display only)
-    const laneBudget = lane === 'lean' ? 12000 : lane === 'standard' ? 25000 : lane === 'full' ? 50000 : lane === 'spike' ? 3000 : 0;
-    const effBudget = budget || laneBudget;
-    const pct = effBudget ? Math.round((est / effBudget) * 100) : 0;
+    // C2: `status` gates on the LANE token budget (what savepoint.sh enforces),
+    // never on the context char budget. `contextStatus` below is its own gate.
+    const laneBudget = budgetForLane(lane);
+    // Q1/Q2: the normalized envelope computes planned/used/remaining/pct/status
+    // on the lane token budget — ONE computation (Q2), reused at render and for
+    // the closure event. `effBudget` stays only for the readable delta display.
+    const env = costEnvelope({ lane, budget: laneBudget, tokens_est: est });
+    const effBudget = budget || laneBudget; // display-only delta basis — never for status (C2)
     const delta = effBudget ? (est <= effBudget ? `${(effBudget - est).toLocaleString()} under` : `${(est - effBudget).toLocaleString()} over`) : 'no budget configured';
     const srcLabel = src === 'reported' ? 'provider-reported' : 'estimator';
+    const statusLabel = env.status.toUpperCase(); // derived from the single computation, not recomputed
+    // context status on context_budget_chars — separate gate, never token `est` (C2)
+    const ctxStatus = contextStatus(budget, chars);
+    // context-efficiency metrics from the evidence registry (reads), else all-zero
+    // with a note — a zero row must not be misread as "efficient" (risk row).
+    const registry = loadRegistry(dir);
+    const reads_total = registry.reduce((s, e) => s + e.reads, 0);
+    const repeated_reads = registry.reduce((s, e) => s + Math.max(e.reads - 1, 0), 0);
+    // M1: honest char accounting — each registered entry carries the content
+    // length it holds (chars). total_chars = chars actually loaded (each entry
+    // × its reads); unique_chars = distinct payload bytes. computeContextMetrics
+    // derives duplicate_chars = total − unique (bytes re-read) and
+    // read_avoidance_chars = same (bytes not reloaded by reuse). When a
+    // registry exists but carries no char payloads (legacy/absent field), the
+    // char fields render as n/a — never fabricated 0 — so reuse_rate > 0 never
+    // sits beside a false "read_avoidance_chars: 0".
+    const unique_chars = registry.reduce((s, e) => s + (e.chars ?? 0), 0);
+    const total_chars = registry.reduce((s, e) => s + (e.chars ?? 0) * e.reads, 0);
+    const charTracked = registry.length > 0 && total_chars > 0;
+    const metrics = registry.length
+      ? computeContextMetrics({
+          files_loaded: registry.length,
+          reads_total,
+          reads_reused: repeated_reads,
+          unique_chars,
+          total_chars,
+          repeated_reads,
+        })
+      : { files_loaded: 0, repeated_reads: 0, duplicate_chars: 0, reuse_rate: 0, read_avoidance_chars: 0 };
+    const ctxNote = registry.length
+      ? (charTracked ? '' : ' (char data not tracked)')
+      : ' (no registry — reads not tracked)';
     // provider-reported rollup when any stage reported
     let reportedTotal = 0;
     let hasReported = false;
@@ -176,14 +220,54 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
       '| Metric | Value |',
       '|--------|-------|',
       `| **Tokens used** | ${est.toLocaleString()} (${srcLabel}) |`,
-      `| **Lane** | ${lane} (budget ${effBudget ? effBudget.toLocaleString() : '—'} · warn ${effBudget ? Math.round(effBudget * 1.5).toLocaleString() : '—'} · stop ${effBudget ? (effBudget * 3).toLocaleString() : '—'}) |`,
-      `| **Budget status** | ${effBudget ? `${pct}% of budget · ${delta} · ${est >= effBudget * 3 ? 'STOP' : est >= effBudget * 1.5 ? 'WARN' : 'OK'}` : 'no lane budget'} |`,
+      `| **Lane** | ${lane} (budget ${effBudget ? effBudget.toLocaleString() : '—'} · warn ${effBudget ? env.warn_at.toLocaleString() : '—'} · stop ${effBudget ? env.stop_at.toLocaleString() : '—'}) |`,
+      `| **Budget status** | ${effBudget ? `${env.pct}% of budget · ${delta} · ${statusLabel}` : 'no lane budget'} |`,
       `| **Context footprint** | ${chars.toLocaleString()} chars${budget ? ` (budget ${budget.toLocaleString()})` : ' (no context budget configured)'} |`,
+      `| **Context budget status** | ${ctxStatus.toUpperCase()}${budget ? ` (budget ${budget.toLocaleString()})` : ' (no context budget configured)'} |`,
+      `| **Context efficiency** | files_loaded: ${metrics.files_loaded} · repeated_reads: ${metrics.repeated_reads} · duplicate_chars: ${charTracked ? metrics.duplicate_chars : 'n/a'} · reuse_rate: ${metrics.reuse_rate} · read_avoidance_chars: ${charTracked ? metrics.read_avoidance_chars : 'n/a'}${ctxNote} |`,
     ].join('\n');
     if (hasReported) {
       costSection += `\n| **Provider total** | ${reportedTotal.toLocaleString()} (provider-reported — sum of reported stages) |`;
     }
+    // Phase 8 Reporting — ledger/avoided/efficiency/trail rows (§39/§43)
+    try {
+      const ledger = buildCostLedger({ missionDir: dir, envelope: env });
+      costSection += `\n| Budget | ${ledger.envelope.status} ${ledger.envelope.pct}% (${ledger.envelope.used}/${ledger.envelope.planned}) |`;
+      costSection += `\n| Context | ${chars.toLocaleString()} chars, reuse ${ledger.efficiency.reuse_rate} |`;
+      costSection += `\n| Avoided | ${ledger.avoided.stages_avoided} stages, ${ledger.avoided.contexts_avoided} contexts, ${ledger.avoided.tokens_avoided_est} tokens est |`;
+      costSection += `\n| Efficiency | reuse ${ledger.efficiency.reuse_rate}, dup ${ledger.efficiency.duplicate_avoidance_chars} chars, budget ${ledger.efficiency.budget_efficiency_pct}% |`;
+      costSection += `\n| Trail | ${ledger.trail.length} decisions |`;
+      if (ledger.trail.length) {
+        const show = ledger.trail.slice(0, 5);
+        for (const t of show) costSection += `\n- ${t.ts} — ${t.actor}: ${t.decision} — reason: ${t.reason}${t.evidence ? ` — evidence: ${t.evidence}` : ''}`;
+        if (ledger.trail.length > 5) costSection += `\n… ${ledger.trail.length - 5} more`;
+      }
+    } catch { /* ledger best-effort — trail parse failure never blocks archive */ }
     costSection += '\n';
+    // Phase E — adaptation summary from the posture decision trail
+    try {
+      costSection += renderAdaptationSection(dir);
+    } catch { /* best-effort */ }
+
+    // Cost Governor: record the closure cost event — the mission's final
+    // cost snapshot, folded into report.md with the rest of the trail.
+    // (Phase 1 — native cost governor; pure append, never rewrites state.)
+    appendCostEvent(dir, {
+      kind: 'closure',
+      mission,
+      tokens_est: est,
+      budget: laneBudget,
+      status: env.status, // Q2: the single lane-token-budget computation
+      context_chars: chars,
+      context_status: ctxStatus,
+      context_metrics: metrics,
+    });
+    // M2: the closure event (with context_status possibly 'over') is recorded
+    // BEFORE the hard gate throws — an over-budget closure still leaves a
+    // ledger row so the over-budget condition is observable, never erased.
+    if (budget && chars > budget) {
+      throw new Error(`closure context budget failed — ${footprintLine}. Trim the trail or raise context_budget_chars.`);
+    }
   }
 
   // Fold order: narrative artifacts first, wave evidence last (chronological).
@@ -194,13 +278,30 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
   }
   // Flow artifacts: flows/ is the current layout; a legacy mission that still
   // keeps waves/ folds from there so an upgrade never strands a trail.
+  // 07-pr-verdict.md SURVIVES archive as a standalone `pr-verdict.md` at the
+  // mission root — it is the PR material handed to the user, so it must not
+  // fold away into report.md.
+  const PR_VERDICT = 'pr-verdict.md';
+  const PR_VERDICT_SRC = join('flows', '07-pr-verdict.md');
   const flowsDir = join(dir, 'flows');
   const legacyWavesDir = join(dir, 'waves');
   const artDir = existsSync(flowsDir) ? flowsDir : existsSync(legacyWavesDir) ? legacyWavesDir : flowsDir;
   const artRel = artDir === legacyWavesDir ? 'waves' : 'flows';
   if (existsSync(artDir)) {
-    for (const f of readdirSync(artDir).sort()) fold.push(join(artRel, f));
+    for (const f of readdirSync(artDir).sort()) {
+      if (artRel === 'flows' && f === '07-pr-verdict.md') continue; // survives as pr-verdict.md
+      fold.push(join(artRel, f));
+    }
   }
+  // Cost events ledger — appended by the closure event above (or a prior
+  // savepoint in a later phase); folds like any other trail artifact so
+  // nothing survives loose after archive.
+  if (existsSync(join(dir, 'cost-events.jsonl'))) fold.push('cost-events.jsonl');
+  // H1: the context registry is the same class of artifact as cost-events.jsonl
+  // (append-only JSONL ledger) — fold it into report.md and remove it so it does
+  // NOT survive loose after archive (survival parity; the fold loop below also
+  // removes every folded file).
+  if (existsSync(join(dir, 'context-registry.jsonl'))) fold.push('context-registry.jsonl');
 
   // The report survives: an existing report.md wins; otherwise the closure
   // wave seeds it; otherwise it starts empty.
@@ -211,6 +312,14 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
 
   if (!dryRun) {
     mkdirSync(dir, { recursive: true });
+    // PR verdict survives archive as a standalone file at the mission root —
+    // it is the PR material handed to the user and must not fold away.
+    const prVerdictSrc = join(dir, PR_VERDICT_SRC);
+    if (existsSync(prVerdictSrc)) {
+      const prVerdictPath = join(dir, PR_VERDICT);
+      writeFileSync(prVerdictPath, readFileSync(prVerdictSrc, 'utf8'));
+      kept.push(join('missions', mission, PR_VERDICT));
+    }
     if (fold.length) {
       const sections = fold.map((f) => {
         const body = readFileSync(join(dir, f), 'utf8').trim();
@@ -235,6 +344,11 @@ export function archiveMission(projectDir: string, mission: string, opts: { dryR
       rmSync(join(dir, f), { force: true, recursive: true });
       removed.push(join('missions', mission, f));
     }
+    // the pr-verdict source was copied to the root — remove the flows/ copy
+    if (existsSync(prVerdictSrc)) {
+      rmSync(join(dir, PR_VERDICT_SRC), { force: true });
+      removed.push(join('missions', mission, PR_VERDICT_SRC));
+    }
     // session state dies with the mission
     for (const f of files.filter((f) => f.endsWith('.json'))) rmSync(join(dir, f), { force: true });
     // flows/ may now be empty — remove the folder

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'],
+  };
+}