@ionivetech/mugiwara 0.6.6 → 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 = {
@@ -161,10 +162,10 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     result.notes.push(...post.notes);
   }
 
-  // TASK 8: a fresh install must be immediately usable — write a default
-  // .mugiwara/config (the same defaults `mugiwara onboard` would write) so no
-  // key silently falls back. Only for project scope; global installs don't own
-  // a project config. Never overwrite an existing config.
+  // A fresh install must be immediately usable — write a default
+  // .mugiwara/config so no key silently falls back. Only for project scope;
+  // global installs don't own a project config. Never overwrite an existing
+  // config.
   if (scope === 'project') {
     const configPath = join(projectDir, '.mugiwara', 'config');
     // lstat, not existsSync: a pre-created symlinked config must not be
@@ -172,22 +173,9 @@ 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',
-        'delegate_threshold=60',
-        'heal_max_cycles=3',
-        'verbosity=normal',
-      ].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} (run \`mugiwara onboard\` to customise)`);
+      result.notes.push(`default config written: ${configPath} (edit it to customise)`);
     }
   }
   return result;
@@ -223,13 +211,14 @@ function assertNotSymlink(file: string): void {
 
 const GITIGNORE_BLOCK_START = '# >>> mugiwara >>>';
 const GITIGNORE_BLOCK_END = '# <<< mugiwara <<<';
-// legacy marker from v0.6.2 — block was undelimited, single '# mugiwara'
-// header. Kept for detection so an old install is not double-appended.
-const GITIGNORE_MARKER = '# mugiwara';
-const GITIGNORE_BLOCK = `# >>> mugiwara >>> — audit trail is the product: commit reports/, results/, logs/, spec/, plans/.
-# Ignore session state and regenerated files.
-.mugiwara/state/
-.mugiwara/continue/
+// legacy markers — pre-0.7 blocks ignored per-type dirs (.mugiwara/state/,
+// .mugiwara/continue/) instead of the mission-first layout. Kept for
+// detection so an old install is upgraded, not double-appended.
+const GITIGNORE_LEGACY = ['.mugiwara/state/', '# mugiwara'];
+const GITIGNORE_BLOCK = `# >>> mugiwara >>> — audit trail is the product: commit plan.md, flows/, review.md,
+# decisions.md, blockers.md, report.md under .mugiwara/missions/. Ignore session state.
+.mugiwara/missions/**/*.json
+.mugiwara/index.md
 .mugiwara/config
 .mugiwara/refs/
 # <<< mugiwara <<<
@@ -242,14 +231,14 @@ export function ensureProjectGitignore(projectDir: string, opts: { dryRun?: bool
   let existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
   if (existing) {
     // Delimited block present with the current entries → nothing to do.
-    if (existing.includes(GITIGNORE_BLOCK_START) && existing.includes('.mugiwara/state/')) {
+    if (existing.includes(GITIGNORE_BLOCK_START) && existing.includes('.mugiwara/missions/**/*.json')) {
       return { appended: false, notes: [] };
     }
-    // Legacy (v0.6.2) or outdated delimited block → upgrade in place:
-    // strip the old mugiwara entries (both forms), then append the new block.
+    // Legacy (pre-0.7) or outdated delimited block → upgrade in place:
+    // strip the old mugiwara entries, then append the new block.
     // Without this, upgraded projects keep committing per-wave state/continue
     // JSON to git — session state must stay ignored (Robin MAJOR, Jinbe Low).
-    const hadOld = existing.includes(GITIGNORE_MARKER) || existing.includes(GITIGNORE_BLOCK_START);
+    const hadOld = GITIGNORE_LEGACY.some((m) => existing.includes(m)) || existing.includes(GITIGNORE_BLOCK_START);
     if (hadOld) {
       const clean = removeProjectGitignore(projectDir, { dryRun });
       existing = clean.removed ? (existsSync(path) ? readFileSync(path, 'utf8') : '') : existing;
@@ -281,20 +270,22 @@ export function removeProjectGitignore(projectDir: string, { dryRun = false }: {
     const end = current.indexOf(GITIGNORE_BLOCK_END);
     if (end < start) return { removed: false, notes: ['delimiter mismatch — .gitignore left untouched'] };
     cleaned = current.slice(0, start) + current.slice(end + GITIGNORE_BLOCK_END.length);
-  } else if (current.includes(GITIGNORE_MARKER)) {
-    // legacy (v0.6.2): strip the exact undelimited block — the header, the
-    // explanatory comment, and the five known lines. Prefix-matching would
+  } else if (current.includes('# mugiwara')) {
+    // legacy (pre-0.7): strip the exact undelimited block — the header, the
+    // explanatory comment, and the known lines. Prefix-matching would
     // delete user-owned lines that merely start with a mugiwara path.
     const LEGACY_LINES = new Set([
       '.mugiwara/state.json',
       '.mugiwara/state-*.json',
       '.mugiwara/config',
+      '.mugiwara/state/',
+      '.mugiwara/continue/',
       '.mugiwara/continue.md',
       '.mugiwara/refs/',
     ]);
     const lines = current.split('\n').filter(l => {
       const t = l.trim();
-      if (t.startsWith(GITIGNORE_MARKER)) return false; // header + comment
+      if (t.startsWith('# mugiwara')) return false; // header + comment
       return !LEGACY_LINES.has(t);
     });
     cleaned = lines.join('\n');

package/src/integrity.ts

@@ -0,0 +1,158 @@
+// src/integrity.ts
+// Closure integrity gate: the audit trail validates itself
+// at archive time. Deterministic checks only — a violation fails the archive
+// with an actionable message instead of shipping a broken or leaking artifact.
+//
+// Three checks:
+//   1. Paths — every relative markdown link in the trail resolves to a file
+//      (mission-relative or repo-root).
+//   2. Secrets — no trail file matches known secret shapes.
+//   3. Evidence — cited wave/evidence paths exist.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+
+export type IntegrityIssue = { kind: 'dangling-path' | 'secret' | 'evidence' | 'evidence-thin'; detail: string };
+
+const SECRET_PATTERNS: Array<[RegExp, string]> = [
+  [/AKIA[0-9A-Z]{16}/, 'AWS access key id'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'private key block'],
+  [/gh[pousr]_[A-Za-z0-9]{20,}/, 'GitHub token'],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/, 'Slack token'],
+  [/sk-[A-Za-z0-9]{32,}/, 'API key (sk-…)'],
+  [/eyJhbGciOi[A-Za-z0-9_.-]{20,}/, 'JWT pasted verbatim'],
+  [/(api[_-]?key|secret|passwd|password)\s*[=:]\s*["'][^"'\s]{8,}["']/i, 'credential assignment'],
+];
+
+const ALLOW_SECRET = 'mugiwara:allow-secret';
+
+/** Secret shapes per line; a line carrying the allow marker is skipped — deliberate examples stay possible. */
+function findSecrets(body: string): Array<{ label: string; hit: string }> {
+  const out: Array<{ label: string; hit: string }> = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (line.includes(ALLOW_SECRET)) continue;
+    for (const [re, label] of SECRET_PATTERNS) {
+      const hit = line.match(re);
+      if (hit) out.push({ label, hit: hit[0] });
+    }
+  }
+  return out;
+}
+
+const TRAIL_EXTS = new Set(['.md', '.json', '.sh', '.jsonl']);
+
+function trailFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (TRAIL_EXTS.has(e.name.slice(e.name.lastIndexOf('.')) || '')) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** Relative markdown-link targets like `](../src/x.ts)` — skip URLs and anchors. */
+function linkedPaths(md: string): string[] {
+  const out: string[] = [];
+  for (const m of md.matchAll(/\]\(([^)\s]+)\)/g)) {
+    const t = m[1];
+    if (/^(https?:|mailto:|#|\/\/)/.test(t)) continue;
+    out.push(t.split('#')[0]);
+  }
+  return out.filter(Boolean);
+}
+
+function hasCommandOutputShape(body: string): boolean {
+  return /`[^`]+`/.test(body) || /\b(exit\s+[01]|✓|✗|\bPASS\b|\bFAIL\b|passed|failed|\d+\s+(passed|failed))\b/i.test(body);
+}
+
+function collectPassCitedPaths(missionDir: string): string[] {
+  const out: string[] = [];
+  for (const f of trailFiles(missionDir)) {
+    let body: string;
+    try { body = readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of body.split(/\r?\n/)) {
+      if (!/\bPASS\b/.test(line)) continue;
+      for (const p of linkedPaths(line)) out.push(p);
+      // also catch bare repo-path mentions like flows/04-gates.md or evidence/foo.md
+      for (const m of line.matchAll(/(?:^|[\s"'(])([a-zA-Z0-9._\/-]+\.(?:md|txt|log|json))\b/g)) {
+        const cand = m[1];
+        if (cand.includes('/')) out.push(cand);
+      }
+    }
+  }
+  return [...new Set(out)];
+}
+
+export function checkTrail(missionDir: string, projectRoot: string): IntegrityIssue[] {
+  const issues: IntegrityIssue[] = [];
+  const files = trailFiles(missionDir);
+
+  // 1 + 2: per-file link resolution and secret scan
+  for (const f of files) {
+    let body: string;
+    try { body = readFileSync(f, 'utf8'); } catch { continue; }
+    for (const target of linkedPaths(body)) {
+      if (isAbsolute(target)) continue;
+      const fromMission = join(missionDir, target);
+      const fromRoot = join(projectRoot, target);
+      if (!existsSync(fromMission) && !existsSync(fromRoot)) {
+        issues.push({
+          kind: 'dangling-path',
+          detail: `${relative(projectRoot, f)} links "${target}" — no such file (mission dir or repo root)`,
+        });
+      }
+    }
+    for (const { label, hit } of findSecrets(body)) {
+      issues.push({
+        kind: 'secret',
+        detail: `${relative(projectRoot, f)} matches ${label}: ${hit.slice(0, 12)}…`,
+      });
+    }
+  }
+
+  // 3: evidence entries recorded as repo paths must exist
+  const evidencePaths: string[] = [];
+  const evidenceFile = join(missionDir, 'state.json');
+  if (existsSync(evidenceFile)) {
+    try {
+      const s = JSON.parse(readFileSync(evidenceFile, 'utf8')) as { evidence?: unknown };
+      if (Array.isArray(s.evidence)) {
+        for (const e of s.evidence) {
+          if (typeof e !== 'string' || !e.trim()) continue;
+          evidencePaths.push(e);
+          const cand = join(projectRoot, e);
+          if (!isAbsolute(e) && !existsSync(cand) && !existsSync(join(missionDir, e))) {
+            issues.push({ kind: 'evidence', detail: `state.json evidence "${e}" does not exist` });
+          }
+        }
+      }
+    } catch { /* corrupt state — the state reader owns that error */ }
+  }
+
+  // 4: evidence-content spot check (T7): a PASS verdict that cites an evidence
+  // path must point at a file that exists AND contains command-output shape
+  // (backticked command or exit-status token). Fake-but-consistent trails
+  // defeat existence-only checks — this raises the bar cheaply.
+  const passCited = collectPassCitedPaths(missionDir);
+  for (const e of passCited) {
+    if (!e.trim() || isAbsolute(e)) continue;
+    const candMission = join(missionDir, e);
+    const candRoot = join(projectRoot, e);
+    const resolved = existsSync(candMission) ? candMission : existsSync(candRoot) ? candRoot : null;
+    if (!resolved) continue; // already reported as evidence/dangling elsewhere
+    let body: string;
+    try { body = readFileSync(resolved, 'utf8'); } catch { continue; }
+    if (!hasCommandOutputShape(body)) {
+      issues.push({ kind: 'evidence-thin', detail: `evidence "${e}" exists but lacks command output (no backticked command or exit-status token)` });
+    }
+  }
+
+  return issues;
+}
+
+export function formatIssues(issues: IntegrityIssue[]): string {
+  return issues.map((i) => `  ✗ [${i.kind}] ${i.detail}`).join('\n');
+}

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 } : {}),
+  });
+}