agent-bober 0.12.0 → 0.15.0

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

@@ -10,7 +10,10 @@
 // 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.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";

package/skills/bober.code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: bober-code-review
+description: Use when completing a sprint, after evaluator pass — spawns bober-code-reviewer subagent to audit the sprint diff against the contract and anti-pattern catalog, producing an advisory ReviewResult written to .bober/reviews/<contractId>-review.md.
+argument-hint: "[contract-id]"
+---
+
+> Adapted from [obra/superpowers](https://github.com/obra/superpowers) — MIT License.
+> Original: skills/requesting-code-review/.
+> Adaptations: agent name (bober-code-reviewer), advisory-only contract, ReviewResult JSON schema, anti-pattern citations from .bober/anti-patterns/.
+
+# bober.code-review — Advisory Code Review Orchestrator
+
+You are the **orchestrator** for a standalone code review run. You do NOT review the code yourself. You spawn the code reviewer as a subagent using the **Agent tool**, then process and save its results to `.bober/reviews/<contractId>-review.md`.
+
+The code reviewer subagent runs in its own isolated context window. It receives ONLY the information you explicitly pass in its prompt.
+
+**Integration with bober pipeline:** In the automated pipeline, bober-code-reviewer is spawned automatically after `runEvaluatorAgent` returns `passed: true` in `src/orchestrator/pipeline.ts`. This skill is for standalone runs — when you want to trigger a review manually outside the normal pipeline flow.
+
+## When to Request Review
+
+**Mandatory in pipeline:** The orchestrator triggers code review automatically after each sprint evaluator pass. You do not need to invoke this skill for normal pipeline runs.
+
+**Use this skill manually when:**
+- You completed a sprint manually (outside the pipeline) and want advisory feedback
+- You want to re-review a sprint with a different anti-pattern focus
+- You want to review a specific file range that the pipeline did not cover
+
+## What the Reviewer Checks
+
+**What to check — findings the reviewer WILL surface:**
+
+- **DRY violations**: New code that duplicates an existing utility verbatim. Cite the duplicate location with file:line evidence.
+- **YAGNI violations**: Abstractions added for future use cases not in the contract. Config options wired but never read.
+- **Dead code**: Functions defined but never called; exports with zero import sites in the diff.
+- **Missing tests**: Changed behavior with no new test coverage; tests that only check the happy path.
+- **Anti-pattern matches** from `.bober/anti-patterns/`:
+  - Testing Mock Behavior, Test-Only Methods in Production → `.bober/anti-patterns/testing-anti-patterns.md`
+  - Arbitrary-delay waiting (`setTimeout`/`sleep`) → `.bober/anti-patterns/condition-based-waiting.md`
+  - Symptom-fix instead of root-cause → `.bober/anti-patterns/root-cause-tracing.md`
+  - Single-layer validation (missing defense-in-depth) → `.bober/anti-patterns/defense-in-depth.md`
+- **Silent error swallowing**: `catch {}` with no log or rethrow; errors absorbed without surfacing
+- **TypeScript `any` types** without a comment explaining why
+
+**What NOT to flag — the reviewer MUST drop these:**
+
+- Style preferences (indentation, line length, trailing commas when file is internally consistent)
+- Naming opinions when the name is consistent with the surrounding file
+- Theoretical risks without an observed trigger (speculation without evidence)
+- Decisions the planner already resolved — re-litigating settled choices is scope creep
+- Pre-existing code that was NOT changed in this sprint
+
+## Acting on Feedback
+
+Because the review is advisory (it never blocks sprint completion), severity signals what to do NEXT:
+
+- **Critical**: Warrants a dedicated fix sprint. The finding has file:line evidence and an observed trigger. Prioritize addressing this before the next feature sprint.
+- **Important**: Address before shipping this feature broadly. Worth tracking in the backlog.
+- **Minor**: Note for future housekeeping. Do not delay other work for these.
+
+Even Critical findings do NOT trigger a generator retry. The sprint is complete. The review surfaces information for planning the next sprint.
+
+## Process Flow
+
+### Step 1: Identify the Target Contract
+
+**If a contract ID was provided as an argument:**
+- Load the contract from `.bober/contracts/<contractId>.json`
+- Verify the contract status is `passed` — review runs after evaluator pass
+
+**If no contract ID was provided:**
+- Find the most recently passed contract from `.bober/contracts/`
+- If no passed contracts exist, tell the user there is nothing to review
+
+Read the contract and its parent PlanSpec.
+
+### Step 2: Gather Context
+
+Read `bober.config.json` for commands and evaluator config.
+Read `.bober/principles.md` if it exists.
+
+Check the git status:
+```bash
+git log --oneline -5
+git diff HEAD~1 --stat
+```
+
+### Step 3: Spawn the Code Reviewer Subagent
+
+Use the **Agent tool** to spawn a code reviewer subagent.
+
+```
+Agent tool call:
+  description: "Code Review: <sprint title>"
+  subagent_type: bober-code-reviewer
+  mode: auto
+  prompt: <the full prompt below>
+```
+
+**Build the reviewer prompt with ALL of these sections:**
+
+```
+You are the Bober Code Reviewer subagent. You have been spawned to advisory-review a sprint that already passed evaluation.
+
+## Sprint Contract
+<paste the full SprintContract JSON from .bober/contracts/<contractId>.json>
+
+## Evaluation Result (Already Passed)
+<paste the EvaluationRunResult JSON — key fields: passed: true, summary, score>
+
+## Project Configuration
+Commands:
+<paste the commands section from bober.config.json>
+
+## Project Root
+<absolute path to the project root>
+
+## Context
+- Contract ID: <contractId>
+- Spec ID: <specId>
+- Review is ADVISORY ONLY — findings do not block completion or trigger retries
+
+## Anti-Pattern Catalog
+The catalog index is at .bober/anti-patterns/README.md. Consult it BEFORE classifying severity.
+Catalogued anti-patterns:
+- Testing anti-patterns → .bober/anti-patterns/testing-anti-patterns.md
+- Condition-based waiting → .bober/anti-patterns/condition-based-waiting.md
+- Root-cause tracing → .bober/anti-patterns/root-cause-tracing.md
+- Defense in depth → .bober/anti-patterns/defense-in-depth.md
+
+## Your Task
+Review the sprint diff. Produce a ReviewResult JSON. Output ONLY the JSON — no text outside it.
+```
+
+### Step 4: Process and Save the Result
+
+When the subagent returns:
+
+1. Parse the ReviewResult JSON from its response
+2. Render the markdown review document (6 required sections):
+
+```markdown
+# Code Review: <contractId>
+
+## Summary
+
+<paste summary field>
+
+## Critical
+
+<for each finding in critical array: description + evidence>
+<if empty: "No critical findings.">
+
+## Important
+
+<for each finding in important array>
+<if empty: "No important findings.">
+
+## Minor
+
+<for each finding in minor array>
+<if empty: "No minor findings.">
+
+## Approved Areas
+
+<for each item in approvedAreas: bullet>
+<if empty: "No areas specifically called out.">
+```
+
+3. Save to `.bober/reviews/<contractId>-review.md`
+4. Report a summary to the user: counts of critical/important/minor findings
+
+## Red Flags - STOP
+
+- About to spawn the reviewer before checking that the sprint status is `passed`
+- About to save a review for a contract that never passed evaluation
+- About to treat Critical findings as blocking (they are advisory — the sprint is done)
+- About to skip reading `.bober/anti-patterns/README.md` before the reviewer prompt
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "The sprint passed, so there is nothing to review" | Passing evaluation is a correctness bar, not a quality bar. Code review adds a separate signal. |
+| "Critical findings mean I should trigger a rework" | No. Advisory means advisory. The sprint is complete. Plan a fix sprint if needed. |
+| "The reviewer ran out of context — I will skip saving the file" | Save what you have. An empty review with just a Summary is better than no record. |
+| "Different words so rule doesn't apply" | Spirit over letter. |