agent-bober 0.11.6 → 0.15.0

package/scripts/graph-hook.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook for Edit|Write tools.
+ *
+ * Claude Code invokes this script after every Edit/Write tool call,
+ * passing tool metadata via stdin (JSON) per the hook contract.
+ *
+ * Contract:
+ *   - Read bober.config.json sync; exit 0 if graph.enabled=false or graph.autoSync=false.
+ *   - Read JSON payload from stdin (Claude Code hook protocol).
+ *   - Extract file paths (tool_input.file_path for Edit/Write).
+ *   - Validate each path is inside the project root (sandboxPath logic mirrored
+ *     from src/orchestrator/tools/handlers.ts:31-45).
+ *   - Append one JSON line to .bober/graph/.hook-queue.jsonl: {ts, tool, paths}.
+ *   - Exit 0 in <50ms. No tokensave invocation here.
+ *
+ * Cross-platform notes:
+ *   - Shebang is present but Windows uses the hooks.json command directly:
+ *     "command": "node scripts/graph-hook.mjs" (NOT a bare path).
+ *   - All path operations use node:path, no shell quoting.
+ *   - Uses fs SYNC calls only (readFileSync, appendFileSync) so the script
+ *     can return as soon as the event loop drains. No promises.
+ */
+
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, relative, isAbsolute, dirname } from "node:path";
+
+const PROJECT_ROOT = process.cwd();
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Mirror of src/orchestrator/tools/handlers.ts:31-45 sandboxPath.
+ * Returns null instead of throwing when the path is outside the sandbox,
+ * so the hook script can silently drop + log an incident rather than crash.
+ */
+function sandboxPath(projectRoot, inputPath) {
+  if (typeof inputPath !== "string" || !inputPath) return null;
+  const abs = isAbsolute(inputPath) ? resolve(inputPath) : resolve(projectRoot, inputPath);
+  const rel = relative(projectRoot, abs);
+  if (rel.startsWith("..") || isAbsolute(rel)) return null;
+  return abs;
+}
+
+function readConfigSync() {
+  for (const candidate of ["bober.config.json", ".bober/config.json"]) {
+    const p = resolve(PROJECT_ROOT, candidate);
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+function readStdinSync() {
+  // Read up to 64KB from stdin synchronously via file descriptor 0.
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function appendSandboxDropIncident(file) {
+  // Best-effort; mirrors IncidentLog.append for the "sandbox-drop" variant.
+  try {
+    const incidentsPath = resolve(PROJECT_ROOT, ".bober/graph/incidents.jsonl");
+    mkdirSync(dirname(incidentsPath), { recursive: true });
+    appendFileSync(
+      incidentsPath,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        event: "sandbox-drop",
+        file,
+        source: "graph-hook",
+      }) + "\n",
+      "utf-8",
+    );
+  } catch {
+    // ignore — never block the tool call
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────
+
+function main() {
+  const config = readConfigSync();
+  const graph = config?.graph;
+
+  // Early exit when graph is disabled or autoSync is off.
+  // The hook entry stays registered in hooks.json (per s8-c9) but does nothing.
+  if (!graph || graph.enabled === false) return 0;
+  if (graph.autoSync === false) return 0;
+
+  const raw = readStdinSync();
+  let payload = {};
+  try {
+    payload = raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    // Malformed payload — exit cleanly with a warning; never crash.
+    process.stderr.write("[graph-hook] Warning: malformed stdin payload\n");
+    return 0;
+  }
+
+  // Claude Code hook payload shape:
+  //   { tool_name, tool_input: { file_path?, edits?[{file_path?}] }, ... }
+  const tool = payload.tool_name ?? "unknown";
+  const candidatePaths = [];
+  const ti = payload.tool_input ?? {};
+  if (typeof ti.file_path === "string") candidatePaths.push(ti.file_path);
+  if (Array.isArray(ti.edits)) {
+    for (const e of ti.edits) {
+      if (typeof e?.file_path === "string") candidatePaths.push(e.file_path);
+    }
+  }
+
+  // Sandbox-validate every path. Drop any path outside the project root
+  // with a silent incident log.
+  const validated = [];
+  for (const p of candidatePaths) {
+    const sb = sandboxPath(PROJECT_ROOT, p);
+    if (sb === null) appendSandboxDropIncident(p);
+    else validated.push(sb);
+  }
+  if (validated.length === 0) return 0;
+
+  // Append to IPC queue file. mkdir is defensive.
+  const queueFile = resolve(PROJECT_ROOT, ".bober/graph/.hook-queue.jsonl");
+  try {
+    mkdirSync(dirname(queueFile), { recursive: true });
+    appendFileSync(
+      queueFile,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        tool,
+        paths: validated,
+      }) + "\n",
+      "utf-8",
+    );
+  } catch {
+    // Best-effort; never block the tool call
+  }
+
+  return 0;
+}
+
+process.exit(main());

package/scripts/migrate-specs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// One-off migration: convert legacy PlanSpec JSON files in .bober/specs/
+// to the schema introduced in src/contracts/spec.ts.
+//
+// Idempotent: running again on already-migrated specs is a no-op.
+//
+// Usage:  node scripts/migrate-specs.mjs
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SPECS_DIR = ".bober/specs";
+
+// Legacy → new priority enum
+const PRIORITY_MAP = {
+  must: "must-have",
+  should: "should-have",
+  could: "nice-to-have",
+};
+
+// Legacy estimatedSprints → estimatedComplexity (rough heuristic)
+function complexityFromSprints(n) {
+  if (typeof n !== "number") return undefined;
+  if (n <= 1) return "low";
+  if (n <= 3) return "medium";
+  return "high";
+}
+
+function migrateFeature(f) {
+  const featureId = f.featureId ?? f.id;
+  if (!featureId) {
+    throw new Error(
+      `Feature missing both featureId and id: ${JSON.stringify(f).slice(0, 100)}`,
+    );
+  }
+
+  const priority = PRIORITY_MAP[f.priority] ?? f.priority;
+
+  const out = {
+    featureId,
+    title: f.title,
+    description: f.description,
+    priority,
+    acceptanceCriteria: f.acceptanceCriteria ?? [],
+    dependencies: f.dependencies ?? [],
+  };
+
+  if (f.estimatedComplexity) {
+    out.estimatedComplexity = f.estimatedComplexity;
+  } else if (f.estimatedSprints !== undefined) {
+    const c = complexityFromSprints(f.estimatedSprints);
+    if (c) out.estimatedComplexity = c;
+    out.estimatedSprints = f.estimatedSprints;
+  }
+
+  return out;
+}
+
+function migrateSpec(spec) {
+  const mode = spec.mode ?? spec.projectType ?? "greenfield";
+  if (mode !== "greenfield" && mode !== "brownfield") {
+    throw new Error(
+      `Spec ${spec.specId}: mode must be greenfield|brownfield (got ${mode})`,
+    );
+  }
+
+  return {
+    specId: spec.specId,
+    version: spec.version ?? 1,
+    title: spec.title,
+    description: spec.description,
+    status: spec.status ?? "completed",
+    mode,
+    features: (spec.features ?? []).map(migrateFeature),
+    assumptions: spec.assumptions ?? [],
+    outOfScope: spec.outOfScope ?? [],
+    ambiguityScore: spec.ambiguityScore,
+    clarificationQuestions: spec.clarificationQuestions ?? [],
+    resolvedClarifications: spec.resolvedClarifications ?? [],
+    techStack: spec.techStack ?? [],
+    techNotes: spec.techNotes,
+    nonFunctionalRequirements:
+      spec.nonFunctionalRequirements ??
+      // legacy: convert nonFunctional string[] to richer objects
+      (spec.nonFunctional ?? []).map((req) => ({ requirement: req })),
+    constraints: spec.constraints ?? [],
+    sprints: spec.sprints,
+    metadata: spec.metadata,
+    createdAt: spec.createdAt,
+    updatedAt: new Date().toISOString(),
+    completedAt: spec.completedAt,
+  };
+}
+
+async function main() {
+  const entries = await readdir(SPECS_DIR);
+  const jsonFiles = entries.filter((f) => f.endsWith(".json")).sort();
+
+  console.log(`Migrating ${jsonFiles.length} specs...`);
+
+  for (const file of jsonFiles) {
+    const path = join(SPECS_DIR, file);
+    const content = await readFile(path, "utf-8");
+    const parsed = JSON.parse(content);
+
+    let migrated;
+    try {
+      migrated = migrateSpec(parsed);
+    } catch (err) {
+      console.error(`✗ ${file}: ${err.message}`);
+      process.exitCode = 1;
+      continue;
+    }
+
+    // Strip undefineds before serializing for cleaner JSON
+    const cleaned = JSON.parse(JSON.stringify(migrated));
+    await writeFile(path, JSON.stringify(cleaned, null, 2) + "\n", "utf-8");
+    console.log(`✓ ${file}`);
+  }
+
+  console.log("Done.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/run-kpi-gate.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * KPI Gate (Sprint 7) — Go/No-Go for Sprints 8-10.
+ *
+ * Reads token-usage data (real or fixture), computes per-role percent
+ * reduction (baseline vs graph-enabled), writes a structured report to
+ * .bober/graph/kpi-gate-report.json, and exits:
+ *   - 0  on pass (reduction.combined >= threshold)
+ *   - 2  on fail
+ *   - 1  on script error (cannot read fixtures, invalid env, etc.)
+ *
+ * Default threshold: 40. Override with env KPI_GATE_THRESHOLD.
+ *
+ * Modes:
+ *   1. Fixture mode (auto when --use-fixtures, KPI_FIXTURE_FILE, or any
+ *      KPI_*_TOKENS_* env var is set):
+ *        - Reads token data from KPI_FIXTURE_FILE (default:
+ *          .bober/graph/token-usage.jsonl), OR
+ *        - Reads directly from env: KPI_BASELINE_TOKENS_RESEARCHER_PHASE2,
+ *          KPI_BASELINE_TOKENS_CURATOR, KPI_BASELINE_TOKENS_ARCHITECT,
+ *          KPI_GATED_TOKENS_RESEARCHER_PHASE2, KPI_GATED_TOKENS_CURATOR,
+ *          KPI_GATED_TOKENS_ARCHITECT (and the matching *_TURNS_* counts).
+ *   2. Real-pipeline mode (default when no fixture flags/env): TODO —
+ *      run the benchmark contract twice via runPipeline(). Deferred to
+ *      manual post-merge runs (per orchestrator autonomous-mode rule).
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..");
+
+const ROLES = ["researcher-phase2", "curator", "architect"];
+const DEFAULT_THRESHOLD = 40;
+const DIVERGENCE_PCT = 10; // s7-c9: turn-count vs token-count divergence flag
+
+function envInt(name, fallback) {
+  const v = process.env[name];
+  if (v === undefined) return fallback;
+  const n = Number(v);
+  if (!Number.isFinite(n)) return fallback;
+  return n;
+}
+
+function tokensEnvFor(prefix, role) {
+  // KPI_BASELINE_TOKENS_RESEARCHER_PHASE2, KPI_GATED_TOKENS_CURATOR, etc.
+  const upper = role.toUpperCase().replace(/-/g, "_");
+  return envInt(`${prefix}_${upper}`, undefined);
+}
+
+function turnsEnvFor(prefix, role) {
+  const upper = role.toUpperCase().replace(/-/g, "_");
+  return envInt(`${prefix}_TURNS_${upper}`, undefined);
+}
+
+function shouldUseFixtures(argv) {
+  if (argv.includes("--use-fixtures")) return true;
+  if (process.env.KPI_FIXTURE_FILE) return true;
+  for (const role of ROLES) {
+    if (tokensEnvFor("KPI_BASELINE_TOKENS", role) !== undefined) return true;
+    if (tokensEnvFor("KPI_GATED_TOKENS", role) !== undefined) return true;
+  }
+  return false;
+}
+
+async function loadFixtureRecords(filePath) {
+  // Read JSONL — one record per line, same shape as src/graph/token-usage.ts.
+  const raw = await readFile(filePath, "utf-8");
+  const records = [];
+  for (const line of raw.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      records.push(JSON.parse(t));
+    } catch {
+      // Skip malformed lines (incidents.jsonl style — never throw).
+    }
+  }
+  return records;
+}
+
+function aggregateRecords(records) {
+  // Returns: { baseline: {role: {tokens, turns}}, gated: {...} }
+  // tokens = inputTokens + outputTokens, turns = count of records per role.
+  const out = { baseline: {}, gated: {} };
+  for (const role of ROLES) {
+    out.baseline[role] = { tokens: 0, turns: 0 };
+    out.gated[role] = { tokens: 0, turns: 0 };
+  }
+  for (const r of records) {
+    if (!r || typeof r !== "object") continue;
+    if (!ROLES.includes(r.agent)) continue;
+    const bucket = r.graphEnabled === true ? out.gated : out.baseline;
+    const slot = bucket[r.agent];
+    slot.tokens += (r.inputTokens ?? 0) + (r.outputTokens ?? 0);
+    slot.turns += 1;
+  }
+  return out;
+}
+
+function overrideWithEnv(agg) {
+  // Env vars take precedence over JSONL fixture for explicit pass/fail cases.
+  for (const role of ROLES) {
+    const bTok = tokensEnvFor("KPI_BASELINE_TOKENS", role);
+    if (bTok !== undefined) agg.baseline[role].tokens = bTok;
+    const gTok = tokensEnvFor("KPI_GATED_TOKENS", role);
+    if (gTok !== undefined) agg.gated[role].tokens = gTok;
+    const bTurns = turnsEnvFor("KPI_BASELINE", role);
+    if (bTurns !== undefined) agg.baseline[role].turns = bTurns;
+    const gTurns = turnsEnvFor("KPI_GATED", role);
+    if (gTurns !== undefined) agg.gated[role].turns = gTurns;
+  }
+  return agg;
+}
+
+function pct(baseline, gated) {
+  if (!Number.isFinite(baseline) || baseline <= 0) return 0;
+  return Number((((baseline - gated) / baseline) * 100).toFixed(2));
+}
+
+function computeReduction(agg) {
+  const reduction = {};
+  let totalBaseline = 0;
+  let weightedSum = 0;
+  for (const role of ROLES) {
+    const b = agg.baseline[role].tokens;
+    const g = agg.gated[role].tokens;
+    reduction[role] = pct(b, g);
+    totalBaseline += b;
+    weightedSum += (b - g);
+  }
+  reduction.combined = totalBaseline > 0
+    ? Number(((weightedSum / totalBaseline) * 100).toFixed(2))
+    : 0;
+  return reduction;
+}
+
+function computeTurnDelta(agg) {
+  const delta = {};
+  for (const role of ROLES) {
+    delta[role] = pct(agg.baseline[role].turns, agg.gated[role].turns);
+  }
+  return delta;
+}
+
+function hasDivergence(reduction, turnDelta) {
+  // s7-c9: if turn-delta and token-delta differ by >10 pp for any gated role,
+  // flag for human review.
+  for (const role of ROLES) {
+    if (Math.abs(reduction[role] - turnDelta[role]) > DIVERGENCE_PCT) return true;
+  }
+  return false;
+}
+
+function buildRecommendations(report) {
+  const lines = [];
+  if (report.gatePass) return lines;
+  const arch = ".bober/architecture/arch-20260524-port-code-review-graph-architecture.md";
+  lines.push(`Combined reduction ${report.reduction.combined}% is below threshold ${report.threshold}%.`);
+  lines.push(`Review per-role deltas: researcher-phase2=${report.reduction["researcher-phase2"]}%, curator=${report.reduction.curator}%, architect=${report.reduction.architect}%.`);
+  lines.push(`Open questions on budget tuning: see ${arch} (preflight-budgets section).`);
+  lines.push(`Consider: (a) raising per-role token budgets, (b) tightening QUERY_BATCHES, (c) adding graph_review_context calls in agent prompts.`);
+  return lines;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const threshold = envInt("KPI_GATE_THRESHOLD", DEFAULT_THRESHOLD);
+
+  let agg;
+  if (shouldUseFixtures(argv)) {
+    const fixturePath = process.env.KPI_FIXTURE_FILE
+      ?? resolve(ROOT, ".bober/graph/token-usage.jsonl");
+    let records = [];
+    try {
+      records = await loadFixtureRecords(fixturePath);
+    } catch (err) {
+      // Missing fixture file is OK when env overrides will fill the values.
+      if (err && err.code !== "ENOENT") throw err;
+    }
+    agg = aggregateRecords(records);
+    agg = overrideWithEnv(agg);
+  } else {
+    console.error("Real-pipeline KPI mode not implemented in this script. Use --use-fixtures or env overrides.");
+    console.error("TODO: invoke runPipeline twice (graphEnabled=false, then graphEnabled=true) against tests/benchmarks/curator-benchmark-contract.json.");
+    process.exit(1);
+  }
+
+  const reduction = computeReduction(agg);
+  const turnDelta = computeTurnDelta(agg);
+  const divergenceFlag = hasDivergence(reduction, turnDelta);
+  const gatePass = reduction.combined >= threshold;
+
+  const report = {
+    baseline: {
+      "researcher-phase2": agg.baseline["researcher-phase2"].tokens,
+      curator: agg.baseline.curator.tokens,
+      architect: agg.baseline.architect.tokens,
+    },
+    gated: {
+      "researcher-phase2": agg.gated["researcher-phase2"].tokens,
+      curator: agg.gated.curator.tokens,
+      architect: agg.gated.architect.tokens,
+    },
+    reduction, // includes researcher-phase2, curator, architect, combined
+    turnCounts: {
+      baseline: {
+        "researcher-phase2": agg.baseline["researcher-phase2"].turns,
+        curator: agg.baseline.curator.turns,
+        architect: agg.baseline.architect.turns,
+      },
+      gated: {
+        "researcher-phase2": agg.gated["researcher-phase2"].turns,
+        curator: agg.gated.curator.turns,
+        architect: agg.gated.architect.turns,
+      },
+    },
+    turnCountDelta: turnDelta,
+    divergenceFlag,
+    gatePass,
+    threshold,
+    timestamp: new Date().toISOString(),
+    recommendations: undefined, // filled below
+  };
+  report.recommendations = buildRecommendations(report);
+
+  const outPath = resolve(ROOT, ".bober/graph/kpi-gate-report.json");
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(report, null, 2) + "\n", "utf-8");
+
+  console.log(`KPI gate: ${gatePass ? "PASS" : "FAIL"} (combined=${reduction.combined}%, threshold=${threshold}%)`);
+  console.log(`Report: ${outPath}`);
+  if (divergenceFlag) {
+    console.warn("Warning: TURNCOUNT_DIVERGENCE — turn-count and token-count reductions diverge by >10pp on at least one role.");
+  }
+
+  process.exit(gatePass ? 0 : 2);
+}
+
+main().catch((err) => {
+  console.error("KPI gate script error:", err);
+  process.exit(1);
+});

package/scripts/sync-skills.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Reverse-inline: take a `.claude/commands/<skill>.md` (which is SKILL.md +
+// inlined references concatenated by `agent-bober init`) and split it back
+// into `skills/<skill>/SKILL.md` + `skills/<skill>/references/<name>.md`.
+//
+// Idempotent and safe: writes only inside `skills/`. Strips trailing
+// `--- + blank line + <!-- Reference: ... -->` separator that init.ts adds
+// when concatenating.
+//
+// Usage:  node scripts/sync-skills.mjs <skill-key>:<command-file> ...
+//   e.g.: node scripts/sync-skills.mjs bober.plan:bober-plan.md \
+//                                     bober.run:bober-run.md \
+//                                     bober.sprint:bober-sprint.md \
+//                                     bober.graph:bober-graph.md \
+//                                     bober.onboard:bober-onboard.md \
+//                                     bober.impact:bober-impact.md
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+const REF_RE = /\n+---\n+<!-- Reference: ([^>]+?) -->\n+/g;
+
+async function syncSkill(skillKey, cmdFile) {
+  const localPath = join(".claude/commands", cmdFile);
+  const content = await readFile(localPath, "utf-8");
+
+  // Split the file at every "<!-- Reference: foo.md -->" marker, capturing
+  // the filename. The first segment is SKILL.md; subsequent segments are
+  // each named reference, in order.
+  const parts = [];
+  let lastIdx = 0;
+  let lastName = null;
+  let m;
+  REF_RE.lastIndex = 0;
+  while ((m = REF_RE.exec(content)) !== null) {
+    parts.push({ name: lastName, body: content.slice(lastIdx, m.index) });
+    lastName = m[1].trim();
+    lastIdx = m.index + m[0].length;
+  }
+  parts.push({ name: lastName, body: content.slice(lastIdx) });
+
+  const skillDir = join("skills", skillKey);
+  const refDir = join(skillDir, "references");
+
+  // Write SKILL.md (the first part, name === null)
+  const head = parts[0];
+  if (head.name !== null) {
+    throw new Error(`First segment of ${cmdFile} should be SKILL.md, got reference ${head.name}`);
+  }
+  // Trim trailing whitespace so SKILL.md doesn't grow with stray newlines
+  const headBody = head.body.replace(/\s+$/, "") + "\n";
+  await writeFile(join(skillDir, "SKILL.md"), headBody, "utf-8");
+  console.log(`  ${skillKey}/SKILL.md  (${headBody.split("\n").length} lines)`);
+
+  // Write references — dedupe by name (some files have duplicate refs from
+  // bad re-inits; the last copy wins, but we warn).
+  const seen = new Map();
+  for (const p of parts.slice(1)) {
+    if (!p.name) continue;
+    if (seen.has(p.name)) {
+      console.warn(`  ⚠ duplicate reference ${p.name} in ${cmdFile} — last copy wins`);
+    }
+    seen.set(p.name, p.body);
+  }
+
+  if (seen.size > 0) {
+    await mkdir(refDir, { recursive: true });
+    for (const [name, body] of seen) {
+      const trimmed = body.replace(/^\s+|\s+$/g, "") + "\n";
+      await writeFile(join(refDir, name), trimmed, "utf-8");
+      console.log(`  ${skillKey}/references/${name}  (${trimmed.split("\n").length} lines)`);
+    }
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.error("Usage: node scripts/sync-skills.mjs <skillKey>:<commandFile> ...");
+    process.exit(1);
+  }
+
+  for (const arg of args) {
+    const [skillKey, cmdFile] = arg.split(":");
+    if (!skillKey || !cmdFile) {
+      console.error(`Bad arg "${arg}" — expected <skillKey>:<commandFile>`);
+      process.exit(1);
+    }
+    console.log(`Syncing ${skillKey} from .claude/commands/${cmdFile}:`);
+    await syncSkill(skillKey, cmdFile);
+  }
+
+  console.log("Done.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});