@ionivetech/mugiwara 0.7.0 → 0.8.1

package/src/cognition.ts

@@ -0,0 +1,234 @@
+// src/cognition.ts
+// Phase 5 Cognitive & Output Governor — focused reasoning, investigation
+// termination, alternative limitation, output compression, duplicate detection,
+// mission-focused output structure (Native Cost Governor, plan §51 Phase 5, §17/§18).
+//
+// Boundary: pure verdict functions over explicit inputs (unit-testable), plus a
+// record helper that persists via the sanitized recordOptDecision (§41). No new
+// config keys; savepoint.sh/lane-base.sh untouched. The crew acts — this module
+// records.
+import { fingerprint } from './evidence.ts';
+import { recordOptDecision } from './cost.ts';
+
+// ── Focused reasoning policy (§17) ──
+
+export type ReasoningInput = {
+  question: string;
+  evidence_available: boolean;
+  speculative_paths: number;
+  reconsiderations: number;
+  hypothetical_requirements: boolean;
+  unrelated_implementations: number;
+};
+
+/**
+ * Focused reasoning policy — Question→Evidence→Decision→Action.
+ * Lists every §17 slop type present; focused only when none.
+ */
+export function isFocusedReasoning(input: ReasoningInput): {
+  focused: boolean;
+  reason: string;
+  slop_types: string[];
+} {
+  const slop_types: string[] = [];
+  if (input.speculative_paths > 0) slop_types.push('speculative_architecture');
+  if (input.reconsiderations >= 2) slop_types.push('repeated_reconsideration');
+  if (input.hypothetical_requirements) slop_types.push('hypothetical_requirements');
+  if (input.unrelated_implementations > 0) slop_types.push('unrelated_implementations');
+  const focused = slop_types.length === 0;
+  const reason = focused
+    ? 'Question→Evidence→Decision→Action — reasoning is focused'
+    : `unfocused — ${slop_types.join(', ')}`;
+  return { focused, reason, slop_types };
+}
+
+// ── Investigation termination (§13 re-consumed at cognition layer, §17) ──
+
+export type CognitiveTerminationInput = {
+  acceptance_mapped: boolean;
+  surface_understood: boolean;
+  path_established: boolean;
+  passes: number;
+  max_passes: number;
+  unrelated_files_opened: number;
+  repeated_reads: number;
+  has_concrete_reason: boolean;
+};
+
+/**
+ * Cognitive investigation termination — re-consumes the §13 triad at the
+ * reasoning layer with a has_concrete_reason override. Triad-complete wins.
+ */
+export function shouldTerminateInvestigation(input: CognitiveTerminationInput): {
+  terminate: boolean;
+  reason: string;
+} {
+  if (input.acceptance_mapped && input.surface_understood && input.path_established) {
+    return { terminate: true, reason: 'triad complete — terminate' };
+  }
+  if (input.passes >= input.max_passes) {
+    if (input.has_concrete_reason) return { terminate: false, reason: 'continue — concrete reason present' };
+    return { terminate: true, reason: 'max passes — terminate' };
+  }
+  if (input.unrelated_files_opened > 5) {
+    if (input.has_concrete_reason) return { terminate: false, reason: 'continue — concrete reason present' };
+    return { terminate: true, reason: 'max unrelated files — terminate' };
+  }
+  if (input.repeated_reads >= 2) {
+    if (input.has_concrete_reason) return { terminate: false, reason: 'continue — concrete reason present' };
+    return { terminate: true, reason: 'repeated read — terminate' };
+  }
+  if (input.has_concrete_reason) return { terminate: false, reason: 'continue — concrete reason present' };
+  return { terminate: false, reason: 'continue — triad incomplete' };
+}
+
+// ── Alternative limitation (§17) ──
+
+export type AlternativeInput = {
+  alternatives: string[];
+  evidence_backed: boolean[];
+  max_alternatives: number;
+};
+
+/**
+ * Bound alternatives to evidence-backed options within max_alternatives.
+ * Dropped = beyond max OR without evidence backing when at least one backed exists.
+ */
+export function limitAlternatives(input: AlternativeInput): {
+  alternatives: string[];
+  limited: boolean;
+  reason: string;
+  dropped: string[];
+} {
+  const max = input.max_alternatives ?? 3;
+  const hasBacked = input.evidence_backed.some(Boolean);
+  const kept: string[] = [];
+  const dropped: string[] = [];
+  for (let i = 0; i < input.alternatives.length; i++) {
+    const alt = input.alternatives[i];
+    const backed = input.evidence_backed[i] ?? false;
+    if (i >= max) {
+      dropped.push(alt);
+    } else if (hasBacked && !backed) {
+      dropped.push(alt);
+    } else {
+      kept.push(alt);
+    }
+  }
+  const limited = dropped.length > 0;
+  const reason = limited
+    ? `bounded to ${kept.length} evidence-backed alternatives`
+    : 'all alternatives within bound';
+  return { alternatives: kept, limited, reason, dropped };
+}
+
+// ── Output compression (§18) ──
+
+export type CompressionInput = {
+  output: string;
+  essential_sections: string[];
+};
+
+export function compressOutput(input: CompressionInput): {
+  compressed: string;
+  saved_chars: number;
+  reason: string;
+  well_structured: boolean;
+} {
+  const well_structured = input.essential_sections.length >= 2;
+  const lines = input.output.split('\n');
+  const headingIndices: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (input.essential_sections.some((h) => lines[i].includes(h))) headingIndices.push(i);
+  }
+  let compressed: string;
+  if (headingIndices.length === 0) {
+    compressed = '';
+  } else {
+    const kept: string[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      const near = headingIndices.some((hi) => Math.abs(i - hi) <= 2);
+      if (near) kept.push(lines[i]);
+    }
+    compressed = kept.join('\n');
+  }
+  const saved_chars = input.output.length - compressed.length;
+  const reason =
+    saved_chars > 0
+      ? `compressed — saved ${saved_chars} chars`
+      : well_structured
+        ? 'compressed — well structured'
+        : 'no compression — not well structured';
+  return { compressed, saved_chars, reason, well_structured };
+}
+
+// ── Duplicate explanation detection (§17/§18, reuses fingerprint) ──
+
+export type DuplicateInput = {
+  explanations: string[];
+};
+
+export function detectDuplicateExplanation(input: DuplicateInput): {
+  duplicate: boolean;
+  reason: string;
+  duplicate_groups: string[][];
+} {
+  const groups = new Map<string, string[]>();
+  for (const exp of input.explanations) {
+    const fp = fingerprint(exp);
+    const arr = groups.get(fp);
+    if (arr) arr.push(exp);
+    else groups.set(fp, [exp]);
+  }
+  const duplicate_groups: string[][] = [];
+  for (const arr of groups.values()) {
+    if (arr.length >= 2) duplicate_groups.push(arr);
+  }
+  const duplicate = duplicate_groups.length > 0;
+  const reason = duplicate
+    ? `${duplicate_groups.length} duplicate group(s) — ${duplicate_groups.length} duplicate explanation(s) found`
+    : 'no duplicate explanations';
+  return { duplicate, reason, duplicate_groups };
+}
+
+// ── Mission-focused output structure (§18) ──
+
+export type StructureInput = {
+  output: string;
+  has_decision: boolean;
+  has_action: boolean;
+  has_result: boolean;
+  has_evidence: boolean;
+  has_blocker: boolean;
+};
+
+export function structureOutput(input: StructureInput): {
+  well_structured: boolean;
+  missing: string[];
+  reason: string;
+} {
+  const missing: string[] = [];
+  if (!input.has_decision) missing.push('Decision');
+  if (!input.has_evidence) missing.push('Evidence');
+  // Action/Result/Blocker are optional — only Decision+Evidence are required
+  // for well_structured (matches acceptance: Decision+Evidence present → true).
+  const well_structured = missing.length === 0;
+  const reason = well_structured
+    ? 'Decision/Action/Result/Evidence/Blocker — mission-focused'
+    : `missing: ${missing.join(', ')}`;
+  return { well_structured, missing, reason };
+}
+
+// ── Decision trail (§41) ──
+
+export function recordCognitiveDecision(
+  missionDir: string,
+  d: { decision: string; reason: string; evidence?: string },
+): void {
+  recordOptDecision(missionDir, {
+    actor: 'cognitive-governor',
+    decision: d.decision,
+    reason: d.reason,
+    ...(d.evidence ? { evidence: d.evidence } : {}),
+  });
+}

package/src/config.ts

@@ -0,0 +1,113 @@
+// src/config.ts
+// Shared .mugiwara/config handling — single source of truth for the default
+// body and key lookup, consumed by the installer, the CLI bootstrap, and
+// script readers. Shell tools (savepoint.sh, lane.sh) read the file directly;
+// this module serves TypeScript consumers (src/ and scripts/*.ts).
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The default config body, identical to what the installer has always written. */
+export const DEFAULT_CONFIG = [
+  'mode=guided',
+  'branch=feature/{type}-{issue}-{slug}',
+  'commit=conventional',
+  'auto_commit=on',
+  'coverage_new=85',
+  'coverage_modified=90',
+  '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)',
+  '# investigation_max_passes=2  # optional: cap investigation passes (spec §13)',
+  '# investigation_max_unrelated_files=5',
+  '# investigation_repeated_read_threshold=2',
+  '# sign=auto            # optional: auto | minisign | pure | off — report attestation',
+  '# enforce=block                # optional: off | warn | block — pipeline-guard policy',
+].join('\n') + '\n';
+
+/** Config file path candidates: project first, then user home. */
+function configPaths(projectDir: string): string[] {
+  return [join(projectDir, '.mugiwara', 'config'), join(homedir(), '.mugiwara', 'config')];
+}
+
+/**
+ * Parse the config as a flat key=value map. Project config wins over the
+ * user-level one (per-key, first-wins across the two files). Comments and
+ * blank lines are skipped; values are trimmed.
+ */
+export function readConfig(projectDir: string): Record<string, string> {
+  try {
+    const file = join(projectDir, '.mugiwara', 'config');
+    let exists = false;
+    try { exists = lstatSync(file).isFile() || lstatSync(file).isSymbolicLink(); } catch { exists = false; }
+    if (!exists) ensureConfig(projectDir);
+  } catch { /* best-effort: auto-create must not break reads */ }
+  const out: Record<string, string> = {};
+  for (const file of configPaths(projectDir)) {
+    if (!existsSync(file)) continue;
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) continue;
+      const eq = t.indexOf('=');
+      if (eq === -1) continue;
+      const key = t.slice(0, eq).trim();
+      if (!key) continue;
+      if (key in out) continue; // project value already set — keep it
+      out[key] = t.slice(eq + 1).trim();
+    }
+  }
+  return out;
+}
+
+/**
+ * Write the default config into <project>/.mugiwara/config when it is missing.
+ * Never overwrites an existing file, never follows a symlink (defense-in-depth
+ * against pre-created symlinked configs — same guard as the installer).
+ * Returns true when a config was written.
+ */
+export function ensureConfig(projectDir: string): boolean {
+  const file = join(projectDir, '.mugiwara', 'config');
+  let exists = false;
+  try { exists = lstatSync(file).isFile() || lstatSync(file).isSymbolicLink(); } catch { exists = false; }
+  if (exists) return false;
+  mkdirSync(join(projectDir, '.mugiwara'), { recursive: true });
+  writeFileSync(file, DEFAULT_CONFIG);
+  return true;
+}
+
+// ── Investigation limits (§13) ──────────────────────────────────────────────
+// Three flat policy keys, all optional (commented in DEFAULT_CONFIG per §52).
+// Defaults: max_passes 2, max_unrelated_files 5, repeated_read_threshold 2.
+
+export type InvestigationConfig = {
+  max_passes: number;
+  max_unrelated_files: number;
+  repeated_read_threshold: number;
+};
+
+const INVESTIGATION_DEFAULTS: InvestigationConfig = {
+  max_passes: 2,
+  max_unrelated_files: 5,
+  repeated_read_threshold: 2,
+};
+
+/** Parse a flat config value as a positive integer; invalid/absent → default. */
+function positiveInt(raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+/** Read the three investigation limit keys via readConfig; non-numeric/zero → default. */
+export function readInvestigationConfig(projectDir: string): InvestigationConfig {
+  const cfg = readConfig(projectDir);
+  return {
+    max_passes: positiveInt(cfg.investigation_max_passes, INVESTIGATION_DEFAULTS.max_passes),
+    max_unrelated_files: positiveInt(cfg.investigation_max_unrelated_files, INVESTIGATION_DEFAULTS.max_unrelated_files),
+    repeated_read_threshold: positiveInt(cfg.investigation_repeated_read_threshold, INVESTIGATION_DEFAULTS.repeated_read_threshold),
+  };
+}

package/src/context.ts

@@ -0,0 +1,72 @@
+// src/context.ts
+// Phase 2 Context Governor — context accounting, budget gate, and efficiency
+// metrics (Native Cost Governor initiative, plan §51 Phase 2, spec §10/§52).
+//
+// Boundary: savepoint.sh measures TOKENS (and gates the lane token budget); it
+// does NOT measure context. There is no shell-side context measurement to
+// mirror, so this TS module is the single definition of context accounting.
+// The chars→tokens estimate here is deliberately separate from the lane token
+// budget: `contextStatus` gates on `context_budget_chars`, never on tokens
+// (C2 — never conflate the two budgets).
+import { measureContextChars as budgetMeasureContextChars } from './budget.ts';
+
+/**
+ * Trail character count — REUSED from src/budget.ts, never re-implemented
+ * (single implementation; test locks the equality). Sum of bytes across the
+ * trail's markdown artifacts, i.e. the context a future reader must load.
+ */
+export const measureContextChars = budgetMeasureContextChars;
+
+/**
+ * Estimate chars→tokens at a documented 4 chars / token ratio.
+ * note: coarse fixed ratio; refine when the harness exposes provider
+ * token telemetry for the actual loaded context.
+ */
+export function estContextTokens(chars: number): number {
+  return Math.round(chars / 4);
+}
+
+/**
+ * Context budget gate on `context_budget_chars`. Mirrors the archive-time
+ * closure throw (chars > budget) as a pure, tested gate. Budget 0 (not
+ * configured) → 'ok'. This is a CHAR threshold — never compare token `est`
+ * against it (C2).
+ */
+export function contextStatus(budgetChars: number, chars: number): 'ok' | 'over' {
+  return budgetChars > 0 && chars > budgetChars ? 'over' : 'ok';
+}
+
+export type ContextMetrics = {
+  files_loaded: number;
+  repeated_reads: number;
+  duplicate_chars: number;
+  reuse_rate: number;
+  read_avoidance_chars: number;
+};
+
+export type ContextMetricStats = {
+  files_loaded: number;
+  reads_total: number;
+  reads_reused: number;
+  unique_chars: number;
+  total_chars: number;
+  repeated_reads: number;
+};
+
+/**
+ * Context-efficiency metrics from the evidence registry + accounting stats.
+ * reuse_rate = reads_reused / reads_total (0 when total 0 — never NaN/Infinity).
+ * duplicate_chars = total − unique (bytes re-read); read_avoidance = duplicate
+ * (bytes not reloaded by reuse). Pure.
+ */
+export function computeContextMetrics(stats: ContextMetricStats): ContextMetrics {
+  const reuse_rate = stats.reads_total > 0 ? stats.reads_reused / stats.reads_total : 0;
+  const duplicate_chars = stats.total_chars - stats.unique_chars;
+  return {
+    files_loaded: stats.files_loaded,
+    repeated_reads: stats.repeated_reads,
+    duplicate_chars,
+    reuse_rate,
+    read_avoidance_chars: duplicate_chars,
+  };
+}

package/src/continue.ts

@@ -14,6 +14,32 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 
+export const CURRENT_SCHEMA_VERSION = 2;
+
+/**
+ * v0.6 legacy layout: `.mugiwara/state/<mission>/<member>.json`
+ * (and `.mugiwara/continue/<mission>/...`) is invisible to v0.8
+ * `missions/` readers. Detect it so status/continue can warn.
+ */
+export function hasLegacyLayout(projectDir: string): boolean {
+  for (const legacy of [join(projectDir, '.mugiwara', 'state'), join(projectDir, '.mugiwara', 'continue')]) {
+    if (!existsSync(legacy)) continue;
+    try {
+      const walk = (dir: string): boolean => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          if (e.isFile() && e.name.endsWith('.json')) return true;
+          if (e.isDirectory() && walk(join(dir, e.name))) return true;
+        }
+        return false;
+      };
+      if (walk(legacy)) return true;
+    } catch { /* ignore */ }
+  }
+  // also legacy flat files at .mugiwara/state.json style already handled by missions scan,
+  // but treat top-level .mugiwara/state/*.json absence as no legacy
+  return false;
+}
+
 /** Mission/member allowlist — identical to savepoint.sh and mission.ts. */
 const SAFE = /^[A-Za-z0-9._-]+$/;
 const isSafeKey = (s: string): boolean => SAFE.test(s) && !/^\.+$/.test(s);
@@ -51,6 +77,7 @@ export type StateEntry = ContinueEntry & {
   budget_status: string;
   files_touched: number;
   evidence: string[];
+  schema_version: number | string | null;
 };
 
 const num = (v: unknown): number => {
@@ -148,6 +175,7 @@ export function readContinue(projectDir: string): ContinueEntry[] {
 export function readState(projectDir: string): StateEntry[] {
   return scan(projectDir, 'state', (r, member) => {
     const tasks = (r.tasks ?? {}) as Record<string, unknown>;
+    const sv = r.schema_version;
     return {
       mission: text(r.mission),
       member,
@@ -178,6 +206,7 @@ export function readState(projectDir: string): StateEntry[] {
       budget_status: text(r.budget_status) || 'ok',
       files_touched: num(r.files_touched),
       evidence: Array.isArray(r.evidence) ? r.evidence.map(text).filter(Boolean) : [],
+      schema_version: typeof sv === 'number' || typeof sv === 'string' ? sv : null,
     };
   });
 }

package/src/cost.ts

@@ -0,0 +1,189 @@
+// src/cost.ts
+// Cost Governor — Phase 1 foundation (Native Cost Governor initiative, plan §51).
+//
+// Centralizes the budget/threshold math that was duplicated across the repo:
+// scripts/lib/lane-base.sh owns the constants for the SHELL runtime
+// (savepoint.sh reads it and cannot import TS), and this module is the single
+// TS-side mirror — consumed by src/mission.ts (archive cost section) and the
+// record helpers below. A drift between the two is a CI failure, not a
+// display nit: test/cost.test.ts asserts every constant against lane-base.sh
+// (D5, same pattern as scripts/lane-base.ts).
+//
+// Also introduces the two record primitives later phases build on:
+//   - cost events        → append-only JSONL per mission (cost-events.jsonl)
+//   - optimization decisions → structured rows in decisions.md
+//     (## Cost governor decisions section — the trail plan §41 asks for)
+//
+// Pure functions first; I/O helpers at the bottom. Nothing here estimates
+// tokens — token telemetry stays in savepoint.sh (estimator or reported).
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ContextMetrics } from './context.ts';
+
+// ── Lane constants (MUST equal scripts/lib/lane-base.sh — enforced by test) ──
+
+export const LANE_BASE: Record<string, number> = {
+  lean: 8421,
+  standard: 13325,
+  full: 22016,
+  spike: 5411,
+};
+
+export const LANE_BUDGET: Record<string, number> = {
+  lean: 12000,
+  standard: 25000,
+  full: 50000,
+  spike: 3000,
+};
+
+/** Token estimate for skills/agents loaded in this lane (0 for unknown/direct). */
+export function laneBaseForLane(lane: string): number {
+  return LANE_BASE[lane] ?? 0;
+}
+
+/** Budget for this lane (0 for unknown/direct — matches savepoint.sh). */
+export function budgetForLane(lane: string): number {
+  return LANE_BUDGET[lane] ?? 0;
+}
+
+// ── Thresholds — savepoint.sh exact integer math (`BUDGET * 3 / 2`, `BUDGET * 3`) ──
+
+/** Warn threshold: integer division `budget * 3 / 2` — same as `$(( BUDGET * 3 / 2 ))`. */
+export function warnAt(budget: number): number {
+  return Math.floor((budget * 3) / 2);
+}
+
+/** Stop threshold: `budget * 3` — same as `$(( BUDGET * 3 ))`. */
+export function stopAt(budget: number): number {
+  return budget * 3;
+}
+
+/** Token budget gate — replicating savepoint.sh: stop at 3×, warn at 1.5×, else ok. Budget 0 → ok. */
+export function budgetStatus(budget: number, tokens: number): 'ok' | 'warn' | 'stop' {
+  if (budget > 0 && tokens >= stopAt(budget)) return 'stop';
+  if (budget > 0 && tokens >= warnAt(budget)) return 'warn';
+  return 'ok';
+}
+
+/** Delegation threshold — same as `$(( BUDGET * DELEGATE_THRESHOLD / 100 ))`. */
+export function delegateAt(budget: number, thresholdPct: number): number {
+  // clamp threshold to [1,100] before the integer division — matches
+  // savepoint.sh's clamp (DELEGATE_THRESHOLD clamped 1..100, scripts/savepoint.sh)
+  const t = Math.min(100, Math.max(1, thresholdPct));
+  return Math.floor((budget * t) / 100);
+}
+
+// ── Normalized cost envelope (computed, never stored — state.json convention) ──
+
+export type CostEnvelopeInput = { lane?: string; budget?: number; tokens_est?: number };
+
+export type CostEnvelope = {
+  planned: number;
+  used: number;
+  remaining: number;
+  pct: number;
+  warn_at: number;
+  stop_at: number;
+  status: 'ok' | 'warn' | 'stop';
+};
+
+/** Normalize stored primitives (tokens_est, budget, lane) into one read model. */
+export function costEnvelope(state: CostEnvelopeInput): CostEnvelope {
+  const planned = typeof state.budget === 'number' && state.budget > 0
+    ? state.budget
+    : budgetForLane(state.lane ?? '');
+  const used = typeof state.tokens_est === 'number' ? state.tokens_est : 0;
+  const remaining = Math.max(planned - used, 0);
+  const pct = planned > 0 ? Math.round((used / planned) * 100) : 0;
+  return {
+    planned,
+    used,
+    remaining,
+    pct,
+    warn_at: warnAt(planned),
+    stop_at: stopAt(planned),
+    status: budgetStatus(planned, used),
+  };
+}
+
+// ── Cost events — append-only JSONL per mission ──
+
+export type CostEvent = {
+  ts: string;
+  kind: string; // 'closure' | 'savepoint' | … future kinds
+  mission: string;
+  tokens_est: number;
+  budget: number;
+  status: string;
+  context_chars?: number;
+  // Phase 2 (T6): context budget status (chars gate) + efficiency metrics,
+  // kept apart from the token `status` — C2 never conflates the two budgets.
+  context_status?: 'ok' | 'over';
+  context_metrics?: ContextMetrics;
+};
+
+const COST_EVENTS_FILE = 'cost-events.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}`);
+}
+
+/**
+ * Append one cost event as a single JSON line. Append-only: no
+ * read-modify-write, so concurrent writers never clobber each other. The
+ * file lives next to the mission state and folds into report.md at archive.
+ */
+export function appendCostEvent(missionDir: string, event: Omit<CostEvent, 'ts'>): void {
+  assertMissionDir(missionDir);
+  mkdirSync(missionDir, { recursive: true });
+  const line: CostEvent = Object.assign({ ts: new Date().toISOString() }, event);
+  appendFileSync(join(missionDir, COST_EVENTS_FILE), JSON.stringify(line) + '\n', 'utf8');
+}
+
+// ── Auto-compress (T4) — compressed event kind ───────────────────────────────
+export const COMPRESSED_KIND = 'compressed';
+
+// ── Optimization decision records — structured rows in decisions.md ──
+
+export type OptDecision = {
+  ts: string;
+  actor: string;
+  decision: string;
+  reason: string;
+  evidence?: string;
+};
+
+const DECISIONS_FILE = 'decisions.md';
+const OPT_SECTION = '## Cost governor decisions';
+
+/**
+ * Append one optimization decision as a bullet under the
+ * `## Cost governor decisions` section of decisions.md. Existing content is
+ * never modified — only appended to. Creates the section header on first use.
+ */
+export function recordOptDecision(missionDir: string, d: Omit<OptDecision, 'ts'>): void {
+  assertMissionDir(missionDir);
+  mkdirSync(missionDir, { recursive: true });
+  const file = join(missionDir, DECISIONS_FILE);
+  let hasSection = false;
+  try {
+    hasSection = readFileSync(file, 'utf8').split(/\r?\n/).some((l) => l.trim() === OPT_SECTION);
+  } catch { /* first write */ }
+  const ts = new Date().toISOString();
+  // flat fields by contract — strip newlines so no markdown/line injection
+  // into decisions.md → report.md (S2). CR/LF become spaces.
+  const flat = (s: string): string => s.replace(/[\r\n]+/g, ' ');
+  const ev = d.evidence ? ` — evidence: ${flat(d.evidence)}` : '';
+  const bullet = `- ${ts} — ${flat(d.actor)}: ${flat(d.decision)} — reason: ${flat(d.reason)}${ev}`;
+  const body = hasSection ? `\n${bullet}\n` : `\n${OPT_SECTION}\n\n${bullet}\n`;
+  appendFileSync(file, body, 'utf8');
+}