@fiale-plus/pi-rogue 0.2.3 → 0.2.4

package/node_modules/@fiale-plus/pi-rogue-router/README.md

@@ -11,24 +11,63 @@ npm run router:rebuild -- --session ./current-session.jsonl --workspace-diff --o
 npm run router:decide -- --checkpoint-file .pi/router/checkpoints.jsonl --ledger .pi/router/events.jsonl
 npm run router:cards -- --events .pi/router/events.jsonl --output .pi/router/model-cards.jsonl
 npm run router:outcomes -- --checkpoint-file .pi/router/checkpoints.jsonl --events .pi/router/events.jsonl --output .pi/router/outcomes.jsonl
+npm run router:outcome-enrich -- --outcomes .pi/router/outcomes.jsonl --checkpoint-file .pi/router/checkpoints.jsonl --events .pi/router/events.jsonl --output .pi/router/outcomes.enriched.jsonl
 npm run router:teacher-requests -- --checkpoint-file .pi/router/checkpoints.jsonl --output .pi/router/teacher-requests.jsonl --teacher openai-codex/gpt-5.5
-npm run router:reflect -- --checkpoint-file .pi/router/checkpoints.jsonl --labels .pi/router/labels/teacher-labels.jsonl --reflection .pi/router/reflections/session.md --teacher local-rule
+npm run router:teacher-label -- --requests .pi/router/teacher-requests.jsonl --teacher-output .pi/router/teacher-decisions.jsonl --labels .pi/router/labels/teacher-labels.jsonl --teacher openai-codex/gpt-5.5
+npm run router:reflect -- --checkpoint-file .pi/router/checkpoints.jsonl --labels .pi/router/labels/teacher-labels.jsonl --reflection .pi/router/reflections/session.md --teacher openai-codex/gpt-5.5 --teacher-output .pi/router/teacher-decisions.jsonl
 npm run router:dataset -- --checkpoint-file .pi/router/checkpoints.jsonl --events .pi/router/events.jsonl --outcomes .pi/router/outcomes.jsonl --labels .pi/router/labels/teacher-labels.jsonl --output .pi/router/training.jsonl
+npm run router:gate-train -- --dataset .pi/router/training.train.jsonl --eval-dataset .pi/router/training.eval.jsonl --artifact .pi/router/binary-gate.json --report .pi/router/binary-gate-report.json
+npm run router:report -- --events .pi/router/events.jsonl --outcomes .pi/router/outcomes.jsonl --dataset .pi/router/training.eval.jsonl --gate-report .pi/router/binary-gate-report.json --output .pi/router/report.json --markdown .pi/router/report.md
+npm run router:sharpen -- --events .pi/router/events.jsonl --outcomes .pi/router/outcomes.jsonl --cards .pi/router/model-cards.jsonl --output .pi/router/sharpening-hints.json
 npm run router:shadow -- --checkpoint-file .pi/router/checkpoints.jsonl --ledger .pi/router/events.jsonl --output .pi/router/shadow-report.json
 
-# Live observe-only extension commands:
-# /router on|off|status|profile|profiles|models|configure|cycle
+# Live router extension commands:
+# /router status|help|on|off|mode|profile|print|profiles|models|configure|cycle
+# /router mode observe      # default: recommendations only
+# /router mode auto_model   # explicit: apply model switches only
+# /router profile spark-smart
+# /router print mismatch_only|all|off
 # ctrl+alt+p cycles router profiles (Ctrl-P is reserved by Pi model cycling).
 ```
 
 ## V1 telemetry notes
 
-Router v1 is still observe-only. It adds outcome skeletons, stronger diff/error fingerprints, teacher-label request export, binary gate dataset export, and subagent-aware telemetry schemas. It does not switch models, spawn agents, or promote policies automatically.
+Router v1 defaults to observe-only. It adds outcome skeletons, stronger diff/error fingerprints, teacher-label request export, binary gate dataset export, and subagent-aware telemetry schemas. It does not spawn agents/subagents or promote policies automatically. The explicit `auto_model` mode may only switch the active model for future turns.
 
-Live config is repo-global at `.pi/router/config.json`, while mutable live state and route ledgers are isolated per Pi session under `.pi/router/sessions/<session-key>/state.json` and `events.jsonl`.
+Live config is repo-global at `.pi/router/config.json`, while mutable live state and route ledgers are isolated per Pi session under `.pi/router/sessions/<session-key>/state.json` and `events.jsonl`. The default `mode` is `observe`; `auto_model` must be explicitly selected and does not alter agents, subagents, tools, or execution paths.
 
 - Diff telemetry stores counts and hashes from `git diff`, not raw patches. Offline rebuilds remain deterministic by default; use `--workspace-diff` only with one current live session/worktree snapshot.
+- `router:outcome-enrich` upgrades conservative outcome skeletons with checkpoint/event-derived verifier, rework, interruption, override, and accepted-diff signals.
 - Error fingerprints normalize paths, line numbers, timestamps, UUIDs, ports, and object ids before hashing.
-- `router:teacher-requests` writes local JSONL requests for an explicit teacher model; imported teacher decisions are still required before labels become training truth.
+- `router:teacher-requests` writes local JSONL requests for an explicit teacher model; `router:teacher-label` calls the explicitly configured teacher and writes decision/label JSONL artifacts.
 - `router:dataset` excludes `local-rule` labels by default so a future model does not merely imitate the current rules.
+- `router:gate-train` trains a local binary continue-vs-intervene gate and evaluates it on a distinct labeled eval dataset; local-rule labels are rejected as training/eval truth and promotion remains manual/eval-gated.
+- `router:report` writes JSON plus optional Markdown summaries across route ledgers, enriched outcomes, dataset labels, and gate evaluation reports.
+- `router:sharpen` writes local-only `pi-router.sharpening-hints.v1` recommendations from route ledgers, optional outcomes, and optional capability cards. Hints include sample-size/confidence/auto-use guardrails, repo-local learning policy, and provenance, but never mutate config or promote policy automatically.
+
+### Automated, upgrade-safe sharpening persistence
+
+Use this one-shot command for cron/background automation:
+
+```bash
+npm run router:sharpen:auto -- --workspace .
+```
+
+By default it stores artifacts at:
+
+- Linux/BSD: `<XDG_DATA_HOME || ~/.local/share>/pi-rogue-router/learning/<repo-name>-<hash>/`
+- macOS: `~/Library/Application Support/pi-rogue-router/learning/<repo-name>-<hash>/`
+
+The script:
+- writes `latest.json` and `history/*.json` artifacts;
+- writes `manifest.json` with source fingerprints for change detection;
+- skips re-computation if inputs are unchanged (unless `--force`);
+- migrates legacy `.pi/router/sharpening-hints.json` into the stable learning directory when present.
+
+Cron example:
+
+```bash
+*/30 * * * * cd /path/to/pi-rogue && npm run router:sharpen:auto -- --workspace /path/to/pi-rogue
+```
+
 - Subagent route/ledger schemas describe parent-child evidence flow, but live autonomous spawning remains out of scope.

package/node_modules/@fiale-plus/pi-rogue-router/src/binary-gate.test.ts

@@ -0,0 +1,88 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { trainBinaryGate, writeBinaryGateTraining } from "./binary-gate.js";
+import type { RouterTrainingRow } from "./dataset.js";
+
+function tempFile(name: string): string {
+  return join(mkdtempSync(join(tmpdir(), "pi-router-gate-")), name);
+}
+
+function row(id: string, label: "continue" | "intervene" | "unknown", overrides: Partial<RouterTrainingRow["features"]> = {}, source: RouterTrainingRow["labels"]["source"] = label === "unknown" ? "unknown" : "teacher"): RouterTrainingRow {
+  return {
+    schema: "pi-router.training-row.v1",
+    checkpointId: id,
+    sessionId: "session-1",
+    rawSessionRef: { schema: "pi-router.raw-session-ref.v1", path: "/tmp/session.jsonl", fromEvent: 0, toEvent: 1, fromByte: 0, toByte: 1, contentHash: "hash" },
+    features: {
+      phase: "implementation",
+      activeModel: "qwen",
+      provider: "local",
+      contextTokensApprox: 1000,
+      sameCommandRepeatedCount: 1,
+      sameErrorRepeatedCount: 0,
+      loopScore: 0.1,
+      progressScore: 0.9,
+      verifierUsed: true,
+      noVerifierUsed: false,
+      diffLines: 10,
+      diffFilesChanged: 1,
+      diffChurnScore: 0.01,
+      filesTouched: 1,
+      ...overrides,
+    },
+    labels: { routeAction: label === "intervene" ? "run_verifier" : label === "continue" ? "continue_current" : null, binaryGate: label, source, confidence: label === "unknown" ? null : 0.8 },
+    outcome: { taskStatus: "unknown", testsPassedAfter: null, acceptedDiff: null, userOverrodeDecision: null, reworkTurns: null },
+    provenance: { localRuleAction: label === "intervene" ? "run_verifier" : "continue_current", excludedLocalRuleAsTruth: false },
+  };
+}
+
+describe("router binary gate training", () => {
+  it("trains a threshold artifact and reports candidate vs rule baseline", () => {
+    const rows = [
+      row("continue-1", "continue"),
+      row("intervene-1", "intervene", { phase: "debug", loopScore: 0.8, progressScore: 0.2, sameErrorRepeatedCount: 3, noVerifierUsed: true, verifierUsed: false }),
+      row("unknown-1", "unknown"),
+    ];
+
+    const evalRows = [
+      row("eval-continue-1", "continue"),
+      row("eval-intervene-1", "intervene", { phase: "debug", loopScore: 0.7, progressScore: 0.3, sameErrorRepeatedCount: 2 }),
+    ];
+
+    const { artifact, report } = trainBinaryGate(rows, evalRows, "2026-06-14T00:00:00.000Z");
+
+    expect(artifact).toMatchObject({ schema: "pi-router.binary-gate-artifact.v1", manualPromotionRequired: true, training: { rows: 3, labeledRows: 2 }, evaluation: { rows: 2, labeledRows: 2 } });
+    expect(report).toMatchObject({ schema: "pi-router.binary-gate-eval.v1", trainRows: 3, trainLabeledRows: 2, evalRows: 2, evalLabeledRows: 2, manualPromotionRequired: true });
+    expect(report.thresholdSweep.length).toBeGreaterThan(1);
+    expect(report.candidate.truePositive + report.candidate.trueNegative + report.candidate.falsePositive + report.candidate.falseNegative).toBe(2);
+  });
+
+  it("writes gate artifact and eval report", () => {
+    const input = tempFile("training.jsonl");
+    const evalInput = tempFile("eval.jsonl");
+    const artifact = tempFile("gate.json");
+    const report = tempFile("report.json");
+    writeFileSync(input, [
+      JSON.stringify(row("continue-1", "continue")),
+      JSON.stringify(row("intervene-1", "intervene", { loopScore: 0.9, progressScore: 0.1, noVerifierUsed: true })),
+    ].join("\n") + "\n");
+    writeFileSync(evalInput, [
+      JSON.stringify(row("eval-continue-1", "continue")),
+      JSON.stringify(row("eval-intervene-1", "intervene", { loopScore: 0.8, progressScore: 0.2, sameErrorRepeatedCount: 3 })),
+    ].join("\n") + "\n");
+
+    const summary = writeBinaryGateTraining({ trainingRowsPath: input, evalRowsPath: evalInput, artifactPath: artifact, reportPath: report });
+
+    expect(summary).toMatchObject({ schema: "pi-router.binary-gate-train-summary.v1", trainRows: 2, trainLabeledRows: 2, evalRows: 2, evalLabeledRows: 2 });
+    expect(JSON.parse(readFileSync(artifact, "utf8")).schema).toBe("pi-router.binary-gate-artifact.v1");
+    expect(JSON.parse(readFileSync(report, "utf8")).schema).toBe("pi-router.binary-gate-eval.v1");
+    expect(() => writeBinaryGateTraining({ trainingRowsPath: input, evalRowsPath: input, artifactPath: tempFile("bad-gate.json"), reportPath: tempFile("bad-report.json") })).toThrow(/distinct --eval-dataset/);
+  });
+
+  it("rejects unusable labels", () => {
+    expect(() => trainBinaryGate([row("rule-1", "continue", {}, "local-rule"), row("rule-2", "intervene", {}, "local-rule")], [row("eval-1", "continue"), row("eval-2", "intervene")])).toThrow(/no usable/);
+    expect(() => trainBinaryGate([row("only-continue", "continue")], [row("eval-1", "continue"), row("eval-2", "intervene")])).toThrow(/both continue and intervene/);
+  });
+});

package/node_modules/@fiale-plus/pi-rogue-router/src/binary-gate.ts

@@ -0,0 +1,232 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { BinaryGateLabel, RouterTrainingRow } from "./dataset.js";
+
+export const BINARY_GATE_ARTIFACT_SCHEMA = "pi-router.binary-gate-artifact.v1" as const;
+export const BINARY_GATE_EVAL_SCHEMA = "pi-router.binary-gate-eval.v1" as const;
+
+export interface BinaryGateArtifact {
+  schema: typeof BINARY_GATE_ARTIFACT_SCHEMA;
+  generatedAt: string;
+  policyVersion: string;
+  model: {
+    kind: "linear-threshold";
+    threshold: number;
+    weights: Record<string, number>;
+  };
+  training: {
+    rows: number;
+    labeledRows: number;
+    positiveIntervene: number;
+    negativeContinue: number;
+  };
+  evaluation: {
+    rows: number;
+    labeledRows: number;
+    positiveIntervene: number;
+    negativeContinue: number;
+  };
+  manualPromotionRequired: true;
+}
+
+export interface ConfusionMatrix {
+  truePositive: number;
+  trueNegative: number;
+  falsePositive: number;
+  falseNegative: number;
+}
+
+export interface BinaryGateEvalReport {
+  schema: typeof BINARY_GATE_EVAL_SCHEMA;
+  generatedAt: string;
+  policyVersion: string;
+  trainRows: number;
+  trainLabeledRows: number;
+  evalRows: number;
+  evalLabeledRows: number;
+  candidate: ConfusionMatrix & { accuracy: number; precision: number; recall: number; f1: number };
+  ruleBaseline: ConfusionMatrix & { accuracy: number; precision: number; recall: number; f1: number };
+  thresholdSweep: Array<{ threshold: number; trainAccuracy: number; trainF1: number; evalAccuracy: number; evalF1: number }>;
+  manualPromotionRequired: true;
+}
+
+export interface GateTrainSummary {
+  schema: "pi-router.binary-gate-train-summary.v1";
+  artifact: string;
+  report: string;
+  trainRows: number;
+  trainLabeledRows: number;
+  evalRows: number;
+  evalLabeledRows: number;
+  threshold: number;
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(4));
+}
+
+export function readTrainingRows(path: string): RouterTrainingRow[] {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) throw new Error(`training rows file not found: ${path}`);
+  return readFileSync(resolved, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      const row = JSON.parse(line) as RouterTrainingRow;
+      if (row.schema !== "pi-router.training-row.v1") throw new Error(`invalid training row schema at ${path}:${index + 1}`);
+      return row;
+    });
+}
+
+function scoreRow(row: RouterTrainingRow): number {
+  const weights = DEFAULT_WEIGHTS;
+  const context = row.features.contextTokensApprox ? Math.min(row.features.contextTokensApprox / 100_000, 1) : 0;
+  const diff = Math.min(row.features.diffLines / 600, 1);
+  const repeatErrors = Math.min(row.features.sameErrorRepeatedCount / 4, 1);
+  const repeatCommands = Math.min(row.features.sameCommandRepeatedCount / 4, 1);
+  const noVerifier = row.features.noVerifierUsed ? 1 : 0;
+  const lowProgress = 1 - row.features.progressScore;
+  const phaseRisk = row.features.phase === "debug" || row.features.phase === "review" ? 0.15 : 0;
+  return Math.max(0, Math.min(1,
+    weights.bias
+    + weights.loopScore * row.features.loopScore
+    + weights.lowProgress * lowProgress
+    + weights.sameErrorRepeatedCount * repeatErrors
+    + weights.sameCommandRepeatedCount * repeatCommands
+    + weights.noVerifierUsed * noVerifier
+    + weights.diffLines * diff
+    + weights.contextPressure * context
+    + phaseRisk,
+  ));
+}
+
+const DEFAULT_WEIGHTS: Record<string, number> = {
+  bias: -0.08,
+  loopScore: 0.38,
+  lowProgress: 0.22,
+  sameErrorRepeatedCount: 0.18,
+  sameCommandRepeatedCount: 0.08,
+  noVerifierUsed: 0.16,
+  diffLines: 0.08,
+  contextPressure: 0.12,
+};
+
+function isIntervene(label: BinaryGateLabel): boolean | null {
+  if (label === "intervene") return true;
+  if (label === "continue") return false;
+  return null;
+}
+
+function ruleGate(row: RouterTrainingRow): BinaryGateLabel {
+  return row.provenance.localRuleAction === "continue_current" || row.provenance.localRuleAction === "continue_local" ? "continue" : "intervene";
+}
+
+function metrics(matrix: ConfusionMatrix): ConfusionMatrix & { accuracy: number; precision: number; recall: number; f1: number } {
+  const total = matrix.truePositive + matrix.trueNegative + matrix.falsePositive + matrix.falseNegative;
+  const precision = matrix.truePositive + matrix.falsePositive ? matrix.truePositive / (matrix.truePositive + matrix.falsePositive) : 0;
+  const recall = matrix.truePositive + matrix.falseNegative ? matrix.truePositive / (matrix.truePositive + matrix.falseNegative) : 0;
+  const f1 = precision + recall ? (2 * precision * recall) / (precision + recall) : 0;
+  return {
+    ...matrix,
+    accuracy: total ? round((matrix.truePositive + matrix.trueNegative) / total) : 0,
+    precision: round(precision),
+    recall: round(recall),
+    f1: round(f1),
+  };
+}
+
+function confusion(rows: RouterTrainingRow[], predict: (row: RouterTrainingRow) => BinaryGateLabel): ConfusionMatrix {
+  const matrix: ConfusionMatrix = { truePositive: 0, trueNegative: 0, falsePositive: 0, falseNegative: 0 };
+  for (const row of rows) {
+    const truth = isIntervene(row.labels.binaryGate);
+    if (truth === null) continue;
+    const predicted = predict(row) === "intervene";
+    if (truth && predicted) matrix.truePositive++;
+    else if (!truth && !predicted) matrix.trueNegative++;
+    else if (!truth && predicted) matrix.falsePositive++;
+    else matrix.falseNegative++;
+  }
+  return matrix;
+}
+
+function thresholdValues(): number[] {
+  return Array.from({ length: 19 }, (_, index) => round(0.05 + index * 0.05));
+}
+
+function usableLabeledRows(rows: RouterTrainingRow[], label: string): RouterTrainingRow[] {
+  const labeled = rows.filter((row) => row.labels.binaryGate !== "unknown" && row.labels.source !== "local-rule");
+  const positives = labeled.filter((row) => row.labels.binaryGate === "intervene").length;
+  const negatives = labeled.filter((row) => row.labels.binaryGate === "continue").length;
+  if (labeled.length === 0) throw new Error(`${label} dataset has no usable teacher/human labeled rows`);
+  if (positives === 0 || negatives === 0) throw new Error(`${label} dataset must contain both continue and intervene labels`);
+  return labeled;
+}
+
+function labelCounts(rows: RouterTrainingRow[]): { positiveIntervene: number; negativeContinue: number } {
+  return {
+    positiveIntervene: rows.filter((row) => row.labels.binaryGate === "intervene").length,
+    negativeContinue: rows.filter((row) => row.labels.binaryGate === "continue").length,
+  };
+}
+
+export function trainBinaryGate(trainRows: RouterTrainingRow[], evalRows: RouterTrainingRow[], generatedAt = new Date().toISOString()): { artifact: BinaryGateArtifact; report: BinaryGateEvalReport } {
+  const trainLabeled = usableLabeledRows(trainRows, "training");
+  const evalLabeled = usableLabeledRows(evalRows, "eval");
+  const trainSweep = thresholdValues().map((threshold) => {
+    const result = metrics(confusion(trainLabeled, (row) => scoreRow(row) >= threshold ? "intervene" : "continue"));
+    return { threshold, accuracy: result.accuracy, f1: result.f1 };
+  });
+  const best = trainSweep.reduce((winner, item) => item.f1 > winner.f1 || (item.f1 === winner.f1 && item.accuracy > winner.accuracy) ? item : winner, trainSweep[0]);
+  const policyVersion = `pi-router.binary-gate.v1.threshold-${best.threshold}`;
+  const trainCounts = labelCounts(trainLabeled);
+  const evalCounts = labelCounts(evalLabeled);
+  const thresholdSweep = thresholdValues().map((threshold) => {
+    const train = metrics(confusion(trainLabeled, (row) => scoreRow(row) >= threshold ? "intervene" : "continue"));
+    const evaluation = metrics(confusion(evalLabeled, (row) => scoreRow(row) >= threshold ? "intervene" : "continue"));
+    return { threshold, trainAccuracy: train.accuracy, trainF1: train.f1, evalAccuracy: evaluation.accuracy, evalF1: evaluation.f1 };
+  });
+  const artifact: BinaryGateArtifact = {
+    schema: BINARY_GATE_ARTIFACT_SCHEMA,
+    generatedAt,
+    policyVersion,
+    model: { kind: "linear-threshold", threshold: best.threshold, weights: DEFAULT_WEIGHTS },
+    training: { rows: trainRows.length, labeledRows: trainLabeled.length, ...trainCounts },
+    evaluation: { rows: evalRows.length, labeledRows: evalLabeled.length, ...evalCounts },
+    manualPromotionRequired: true,
+  };
+  const report: BinaryGateEvalReport = {
+    schema: BINARY_GATE_EVAL_SCHEMA,
+    generatedAt,
+    policyVersion,
+    trainRows: trainRows.length,
+    trainLabeledRows: trainLabeled.length,
+    evalRows: evalRows.length,
+    evalLabeledRows: evalLabeled.length,
+    candidate: metrics(confusion(evalLabeled, (row) => scoreRow(row) >= best.threshold ? "intervene" : "continue")),
+    ruleBaseline: metrics(confusion(evalLabeled, ruleGate)),
+    thresholdSweep,
+    manualPromotionRequired: true,
+  };
+  return { artifact, report };
+}
+
+export function writeBinaryGateTraining(options: { trainingRowsPath: string; evalRowsPath: string; artifactPath: string; reportPath: string }): GateTrainSummary {
+  const rows = readTrainingRows(options.trainingRowsPath);
+  const evalRows = readTrainingRows(options.evalRowsPath);
+  if (resolve(options.trainingRowsPath) === resolve(options.evalRowsPath)) throw new Error("gate training requires a distinct --eval-dataset file for out-of-sample evaluation");
+  const { artifact, report } = trainBinaryGate(rows, evalRows);
+  mkdirSync(dirname(resolve(options.artifactPath)), { recursive: true });
+  mkdirSync(dirname(resolve(options.reportPath)), { recursive: true });
+  writeFileSync(resolve(options.artifactPath), `${JSON.stringify(artifact, null, 2)}\n`);
+  writeFileSync(resolve(options.reportPath), `${JSON.stringify(report, null, 2)}\n`);
+  return {
+    schema: "pi-router.binary-gate-train-summary.v1",
+    artifact: resolve(options.artifactPath),
+    report: resolve(options.reportPath),
+    trainRows: rows.length,
+    trainLabeledRows: artifact.training.labeledRows,
+    evalRows: evalRows.length,
+    evalLabeledRows: artifact.evaluation.labeledRows,
+    threshold: artifact.model.threshold,
+  };
+}

package/node_modules/@fiale-plus/pi-rogue-router/src/cli.ts

@@ -2,11 +2,15 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { decideRoute, readCheckpointJsonl, selectCheckpoint } from "./decision.js";
+import { writeBinaryGateTraining } from "./binary-gate.js";
 import { writeSessionCheckpointsJsonl } from "./checkpoints.js";
 import { appendRouteEvent, buildRouteEvent } from "./ledger.js";
 import { writeCapabilityCards, writeShadowEval, writeTeacherPromptRequests, writeTeacherReflection } from "./learning.js";
 import { writeTrainingRows } from "./dataset.js";
-import { writeInferredOutcomes } from "./outcomes.js";
+import { writeEnrichedOutcomes, writeInferredOutcomes } from "./outcomes.js";
+import { writeRouterReport } from "./reports.js";
+import { writeSharpeningHints } from "./sharpening.js";
+import { runTeacherLabeling } from "./teacher-runner.js";
 
 interface Args {
   command?: string;
@@ -19,12 +23,22 @@ interface Args {
   events?: string;
   labels?: string;
   reflection?: string;
+  artifact?: string;
+  report?: string;
+  dataset?: string;
+  evalDataset?: string;
+  markdown?: string;
+  gateReport?: string;
   teacher?: string;
   teacherOutput?: string;
   teacherPrompts?: string;
+  requests?: string;
+  decisionsOutput?: string;
   outcomes?: string;
+  cards?: string;
   includeLocalRuleLabels?: boolean;
   workspaceDiff?: boolean;
+  dryRun?: boolean;
   pretty: boolean;
 }
 
@@ -35,9 +49,14 @@ function usage(): never {
   npm run router:decide -- --checkpoint-file <checkpoints.jsonl> [--checkpoint-id <id>] [--ledger <events.jsonl>] [--pretty]
   npm run router:cards -- --events <events.jsonl> --output <model-cards.jsonl> [--outcomes <outcomes.jsonl>] [--pretty]
   npm run router:outcomes -- --checkpoint-file <checkpoints.jsonl> --events <events.jsonl> --output <outcomes.jsonl> [--pretty]
+  npm run router:outcome-enrich -- --outcomes <outcomes.jsonl> --output <enriched-outcomes.jsonl> [--checkpoint-file <checkpoints.jsonl>] [--events <events.jsonl>] [--pretty]
   npm run router:teacher-requests -- --checkpoint-file <checkpoints.jsonl> --output <requests.jsonl> [--teacher openai-codex/gpt-5.5] [--pretty]
+  npm run router:teacher-label -- --requests <requests.jsonl> --teacher-output <decisions.jsonl> --labels <labels.jsonl> [--teacher openai-codex/gpt-5.5] [--dry-run] [--pretty]
   npm run router:reflect -- --checkpoint-file <checkpoints.jsonl> --labels <labels.jsonl> --reflection <reflection.md> [--teacher local-rule] [--teacher-output <decisions.jsonl>] [--teacher-prompts <requests.jsonl>] [--pretty]
   npm run router:dataset -- --checkpoint-file <checkpoints.jsonl> --output <training.jsonl> [--events <events.jsonl>] [--outcomes <outcomes.jsonl>] [--labels <labels.jsonl>] [--include-local-rule-labels] [--pretty]
+  npm run router:gate-train -- --dataset <training.jsonl> --eval-dataset <eval.jsonl> --artifact <gate.json> --report <gate-report.json> [--pretty]
+  npm run router:report -- --output <report.json> [--markdown <report.md>] [--events <events.jsonl>] [--outcomes <outcomes.jsonl>] [--dataset <training.jsonl>] [--gate-report <gate-report.json>] [--pretty]
+  npm run router:sharpen -- --events <events.jsonl> --output <hints.json> [--outcomes <outcomes.jsonl>] [--cards <model-cards.jsonl>] [--pretty]
   npm run router:shadow -- --checkpoint-file <checkpoints.jsonl> --output <report.json> [--ledger <events.jsonl>] [--pretty]
 
 Commands:
@@ -45,9 +64,14 @@ Commands:
   decide     Emit a strict JSON route decision for a checkpoint and optionally append a route event.
   cards      Generate local observed model capability cards from route events and optional outcomes.
   outcomes   Infer conservative outcome skeletons that can be manually enriched.
+  outcome-enrich Enrich outcome records from checkpoints and route events.
   teacher-requests Generate local JSONL prompt requests for explicit teacher labeling.
+  teacher-label Run explicit teacher model labeling over request JSONL.
   reflect    Generate command-triggered soft routing labels and a reflection artifact.
   dataset    Export trainable rows for a conservative continue-vs-intervene gate.
+  gate-train Train/evaluate a local binary continue-vs-intervene gate artifact.
+  report     Summarize route events, outcomes, labels, and gate eval metrics.
+  sharpen    Generate local, provenance-backed router sharpening hints without mutating policy.
   shadow     Shadow-evaluate the current rule policy over historical checkpoints.
 `);
   process.exit(2);
@@ -104,6 +128,36 @@ function parseArgs(argv: string[]): Args {
       index++;
       continue;
     }
+    if (arg === "--artifact" && next) {
+      args.artifact = next;
+      index++;
+      continue;
+    }
+    if (arg === "--report" && next) {
+      args.report = next;
+      index++;
+      continue;
+    }
+    if (arg === "--dataset" && next) {
+      args.dataset = next;
+      index++;
+      continue;
+    }
+    if (arg === "--eval-dataset" && next) {
+      args.evalDataset = next;
+      index++;
+      continue;
+    }
+    if (arg === "--markdown" && next) {
+      args.markdown = next;
+      index++;
+      continue;
+    }
+    if (arg === "--gate-report" && next) {
+      args.gateReport = next;
+      index++;
+      continue;
+    }
     if (arg === "--teacher" && next) {
       args.teacher = next;
       index++;
@@ -119,11 +173,26 @@ function parseArgs(argv: string[]): Args {
       index++;
       continue;
     }
+    if (arg === "--requests" && next) {
+      args.requests = next;
+      index++;
+      continue;
+    }
+    if (arg === "--decisions-output" && next) {
+      args.decisionsOutput = next;
+      index++;
+      continue;
+    }
     if (arg === "--outcomes" && next) {
       args.outcomes = next;
       index++;
       continue;
     }
+    if (arg === "--cards" && next) {
+      args.cards = next;
+      index++;
+      continue;
+    }
     if (arg === "--include-local-rule-labels") {
       args.includeLocalRuleLabels = true;
       continue;
@@ -132,6 +201,10 @@ function parseArgs(argv: string[]): Args {
       args.workspaceDiff = true;
       continue;
     }
+    if (arg === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
     if (arg === "--pretty") {
       args.pretty = true;
       continue;
@@ -207,12 +280,28 @@ function outcomes(args: Args): unknown {
   return writeInferredOutcomes({ checkpointPath: args.checkpointFile, eventsPath: args.events, outputPath: args.output });
 }
 
+function outcomeEnrich(args: Args): unknown {
+  if (!args.outcomes || !args.output) usage();
+  return writeEnrichedOutcomes({ outcomesPath: args.outcomes, outputPath: args.output, checkpointPath: args.checkpointFile, eventsPath: args.events });
+}
+
 function teacherRequests(args: Args): unknown {
   if (!args.checkpointFile || !args.output) usage();
   const requests = writeTeacherPromptRequests(args.checkpointFile, args.output, args.teacher ?? "openai-codex/gpt-5.5");
   return { schema: "pi-router.teacher-requests-summary.v1", output: resolve(args.output), requests: requests.length, teacher: args.teacher ?? "openai-codex/gpt-5.5" };
 }
 
+async function teacherLabel(args: Args): Promise<unknown> {
+  if (!args.requests || !args.teacherOutput || !args.labels) usage();
+  return runTeacherLabeling({
+    requestsPath: args.requests,
+    decisionsOutputPath: args.teacherOutput,
+    labelsOutputPath: args.labels,
+    teacher: args.teacher,
+    dryRun: args.dryRun,
+  });
+}
+
 function reflect(args: Args): unknown {
   if (!args.checkpointFile || !args.labels || !args.reflection) usage();
   const result = writeTeacherReflection({
@@ -244,6 +333,21 @@ function dataset(args: Args): unknown {
   });
 }
 
+function gateTrain(args: Args): unknown {
+  if (!args.dataset || !args.evalDataset || !args.artifact || !args.report) usage();
+  return writeBinaryGateTraining({ trainingRowsPath: args.dataset, evalRowsPath: args.evalDataset, artifactPath: args.artifact, reportPath: args.report });
+}
+
+function report(args: Args): unknown {
+  if (!args.output) usage();
+  return writeRouterReport({ outputPath: args.output, markdownPath: args.markdown, eventsPath: args.events, outcomesPath: args.outcomes, trainingRowsPath: args.dataset, gateReportPath: args.gateReport });
+}
+
+function sharpen(args: Args): unknown {
+  if (!args.events || !args.output) usage();
+  return writeSharpeningHints({ eventsPath: args.events, outputPath: args.output, outcomesPath: args.outcomes, cardsPath: args.cards });
+}
+
 function shadow(args: Args): unknown {
   if (!args.checkpointFile || !args.output) usage();
   return writeShadowEval(args.checkpointFile, args.output, args.ledger);
@@ -259,15 +363,25 @@ async function main(): Promise<void> {
         ? cards(args)
         : args.command === "outcomes"
           ? outcomes(args)
-          : args.command === "teacher-requests"
+          : args.command === "outcome-enrich"
+            ? outcomeEnrich(args)
+            : args.command === "teacher-requests"
             ? teacherRequests(args)
-            : args.command === "reflect"
-              ? reflect(args)
-              : args.command === "dataset"
-                ? dataset(args)
-                : args.command === "shadow"
-                  ? shadow(args)
-                  : usage();
+            : args.command === "teacher-label"
+                ? await teacherLabel(args)
+                : args.command === "reflect"
+                  ? reflect(args)
+                  : args.command === "dataset"
+                    ? dataset(args)
+                    : args.command === "gate-train"
+                      ? gateTrain(args)
+                      : args.command === "report"
+                        ? report(args)
+                        : args.command === "sharpen"
+                          ? sharpen(args)
+                          : args.command === "shadow"
+                          ? shadow(args)
+                          : usage();
   console.log(args.pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result));
 }