opencode-autoresearch 3.6.0 → 3.7.0

package/dist/cli.js

@@ -1,18 +1,25 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, readdirSync } from "fs";
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, readdirSync } from "fs";
 import { resolve } from "path";
-import { printJson, resolveRepo, parseRunState, parsePositiveInt, sanitizeForTerminal, getInstalledPackagePath, getInstalledPackageInfo, readUpdateCache, getGlobalNpmPrefix } from "./helpers.js";
+import { execSync } from "child_process";
+import { MAX_DRAFTS } from "./constants.js";
+import { printJson, resolveRepo, parseRunState, parsePositiveInt, sanitizeForTerminal, getInstalledPackagePath, getInstalledPackageInfo, readUpdateCache, getGlobalNpmPrefix, readGoalDoc, atomicWriteTextInRepo } from "./helpers.js";
 const VERSION_FLAGS = ["--version", "-v"];
 const HELP_FLAGS = ["--help", "-h", "help"];
+const BRANCH_POLICIES = ["best", "roulette", "diverse"];
 const usage = () => {
     console.error("Usage: autoresearch <command> [options]");
     console.error("");
     console.error("Commands:");
     console.error("  init       Initialize a run");
+    console.error("  goal       Manage goal definitions (subcommands: init)");
     console.error("  wizard     Generate a setup summary");
     console.error("  status     Print run status");
     console.error("  explain    Human-readable run state");
+    console.error("  goal       Show or validate the goal document");
     console.error("  history    Show recent iteration log");
+    console.error("  scores     Show score trend history");
+    console.error("  score      Run the configured scorer and show normalized output");
     console.error("  config     Show runtime configuration");
     console.error("  summary    Aggregate stats across runs");
     console.error("  suggest    Suggest next goal from memory");
@@ -27,18 +34,30 @@ const usage = () => {
     console.error("Options:");
     console.error("  --repo          Repository root (default: current directory)");
     console.error("  --goal          Desired run outcome");
-    console.error("  --metric        Metric name to track");
-    console.error("  --direction     lower or higher");
+    console.error("  --metric        Metric name to track (default outcome metric)");
+    console.error("  --direction     lower or higher (for outcome metric)");
+    console.error("  --outcome-metric    Primary metric for keep decisions");
+    console.error("  --outcome-direction Direction for outcome metric");
+    console.error("  --instrument-metric Measurement quality/risk metric (surfaced separately)");
+    console.error("  --instrument-direction Direction for instrument metric");
+    console.error("  --instrument-value  Recorded value for the instrument metric");
+    console.error("  --scorer-status     ok, ok-low-score, or scorer-broken (default: ok)");
     console.error("  --verify        Mechanical verification command");
     console.error("  --guard         Guard command for regression catch");
+    console.error("  --scorer        Scorer command (outputs JSON with score and max fields)");
     console.error("  --mode          foreground or background");
     console.error("  --scope         In-scope files or subsystem");
     console.error("  --iterations    Iteration cap");
+    console.error("  --max-no-progress  Max consecutive discards before stop");
     console.error("  --duration      Wall-clock cap (e.g., 5h or 300m)");
+    console.error(`  --num-drafts    Number of parallel drafts (default: 1, max: ${MAX_DRAFTS})`);
+    console.error("  --branch-policy Branch selection policy: best, roulette, diverse");
     console.error("  --json          Output raw JSON (default: human-readable)");
     console.error("  --results-path  Custom results TSV path");
     console.error("  --state-path    Custom state JSON path");
     console.error("  --fresh-start   Archive previous artifacts before starting");
+    console.error("  --goal-path     Output path for GOAL.md (used by goal init)");
+    console.error("  --template      Goal template: performance, quality, coverage, custom (used by goal init)");
     console.error("");
     console.error("Flags:");
     console.error("  -h, --help      Show this help");
@@ -49,9 +68,12 @@ const usage = () => {
     console.error("Examples:");
     console.error("  autoresearch wizard --goal \"optimize response time\"");
     console.error("  autoresearch init --goal \"reduce errors\" --metric errors --direction lower --verify \"npm test\"");
+    console.error("  autoresearch goal init --goal \"reduce errors\" --metric errors --direction lower --verify \"npm test\"");
+    console.error("  autoresearch goal init --template performance");
     console.error("  autoresearch status");
     console.error("  autoresearch explain");
     console.error("  autoresearch history");
+    console.error("  autoresearch score --scorer \"node score.js\"");
 };
 const parseArgs = (args) => {
     const result = {};
@@ -70,6 +92,8 @@ const parseArgs = (args) => {
                 r: "repo", g: "goal", m: "metric", d: "direction",
                 v: "verify", n: "guard", o: "mode", s: "scope",
                 i: "iterations", t: "duration",
+                f: "num-drafts", b: "branch-policy",
+                p: "max-no-progress",
             };
             const key = shortToLong[args[i][1]] ?? args[i].slice(1);
             if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
@@ -82,6 +106,12 @@ const parseArgs = (args) => {
     }
     return result;
 };
+const tsvField = (headers, cols, field, legacyIndex) => {
+    const fieldIndex = headers.indexOf(field);
+    if (fieldIndex >= 0)
+        return cols[fieldIndex] ?? "";
+    return cols[legacyIndex] ?? "";
+};
 const markdownInlineEscapes = {
     "\\": "\\\\",
     "`": "\\`",
@@ -123,6 +153,21 @@ const formatDisplayValue = (val) => {
         return "—";
     return sanitizeForTerminal(val);
 };
+const parseMemoryPatternHeading = (heading) => {
+    const raw = heading.replace(/^### Pattern: /, "");
+    const trimmed = raw.trimEnd();
+    if (trimmed.startsWith('"')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === "string")
+                return parsed;
+        }
+        catch {
+            // Fall through to the raw heading text for backward compatibility.
+        }
+    }
+    return trimmed;
+};
 const formatMetricValue = formatDisplayValue;
 const formatTimestamp = (ts) => {
     try {
@@ -133,6 +178,46 @@ const formatTimestamp = (ts) => {
         return ts;
     }
 };
+const readTailLines = (filePath, limit) => {
+    if (limit <= 0)
+        return [];
+    const fd = openSync(filePath, "r");
+    try {
+        const size = fstatSync(fd).size;
+        if (size === 0)
+            return [];
+        const chunkSize = 64 * 1024;
+        const lines = [];
+        let position = size;
+        let remainder = Buffer.alloc(0);
+        while (position > 0 && lines.length < limit) {
+            const bytesToRead = Math.min(chunkSize, position);
+            position -= bytesToRead;
+            const chunk = Buffer.alloc(bytesToRead);
+            const bytesRead = readSync(fd, chunk, 0, bytesToRead, position);
+            const data = Buffer.concat([chunk.subarray(0, bytesRead), remainder]);
+            let end = data.length;
+            for (let i = data.length - 1; i >= 0 && lines.length < limit; i -= 1) {
+                if (data[i] === 0x0a) {
+                    const line = data.subarray(i + 1, end).toString("utf-8").trim();
+                    if (line.length > 0)
+                        lines.push(line);
+                    end = i;
+                }
+            }
+            remainder = data.subarray(0, end);
+        }
+        if (lines.length < limit) {
+            const line = remainder.toString("utf-8").trim();
+            if (line.length > 0)
+                lines.push(line);
+        }
+        return lines.reverse();
+    }
+    finally {
+        closeSync(fd);
+    }
+};
 const markdownEscapePattern = /([\\`*_{}[\]()#+\-.!|>])/g;
 const terminalControlPattern = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/g;
 const controlCharacterPattern = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
@@ -148,6 +233,13 @@ const sanitizeMarkdownText = (value) => {
 const formatMarkdownField = (value) => {
     return sanitizeMarkdownText(value).replace(markdownEscapePattern, "\\$1");
 };
+const normalizeBranchPolicy = (value) => {
+    if (value == null || value === "")
+        return "best";
+    if (BRANCH_POLICIES.includes(value))
+        return value;
+    throw new Error(`Invalid branch policy: ${value}. Expected one of: ${BRANCH_POLICIES.join(", ")}`);
+};
 const main = async () => {
     const args = process.argv.slice(2);
     // Handle standalone flags
@@ -193,6 +285,7 @@ const main = async () => {
                     guard: grouped.guard,
                     mode: grouped.mode,
                     iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    max_no_progress: parsePositiveInt(grouped["max-no-progress"], "max-no-progress"),
                     duration: grouped.duration,
                     memory_path: grouped["memory-path"],
                     required_keep_labels: grouped["required-keep-labels"],
@@ -219,13 +312,15 @@ const main = async () => {
                 const { initializeRun } = await import("./run-manager.js");
                 const config = {
                     goal: grouped.goal,
-                    metric: grouped.metric,
-                    direction: grouped.direction || "lower",
+                    metric: (grouped.metric || grouped["outcome-metric"]),
+                    direction: (grouped.direction || grouped["outcome-direction"]) || "lower",
                     verify: grouped.verify,
                     mode: grouped.mode || "foreground",
                     scope: grouped.scope,
                     guard: grouped.guard,
+                    scorer: grouped.scorer,
                     iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    max_no_progress: parsePositiveInt(grouped["max-no-progress"], "max-no-progress"),
                     duration: grouped.duration,
                     memory_path: grouped["memory-path"],
                     required_keep_labels: grouped["required-keep-labels"],
@@ -233,6 +328,12 @@ const main = async () => {
                     run_tag: grouped["run-tag"],
                     stop_condition: grouped["stop-condition"],
                     baseline: grouped.baseline,
+                    num_drafts: parsePositiveInt(grouped["num-drafts"], "num_drafts", { max: MAX_DRAFTS }) ?? 1,
+                    branch_selection_policy: normalizeBranchPolicy(grouped["branch-policy"]),
+                    outcome_metric: grouped["outcome-metric"],
+                    outcome_direction: grouped["outcome-direction"],
+                    instrument_metric: grouped["instrument-metric"],
+                    instrument_direction: grouped["instrument-direction"],
                 };
                 const state = await initializeRun(grouped.repo, grouped["results-path"], grouped["state-path"], config, grouped["fresh-start"] === "true");
                 printJson(state);
@@ -250,6 +351,7 @@ const main = async () => {
                     console.log(`Run:     ${formatDisplayValue(s.run_id)}`);
                     console.log(`Status:  ${formatDisplayValue(s.status)}`);
                     console.log(`Mode:    ${formatDisplayValue(s.mode)}`);
+                    console.log(`Op Mode: ${formatDisplayValue(s.operating_mode)}`);
                     console.log(`Goal:    ${formatDisplayValue(s.goal)}`);
                     if (s.metric) {
                         const m = s.metric;
@@ -264,6 +366,13 @@ const main = async () => {
                     const lastIter = s.last_iteration;
                     if (lastIter && lastIter.iteration) {
                         console.log(`Last:    iter ${formatDisplayValue(lastIter.iteration)} — ${formatDisplayValue(lastIter.decision)} (${formatMetricValue(lastIter.metric_value)})`);
+                        if (lastIter.score_components != null && typeof lastIter.score_components === "object") {
+                            const parts = Object.entries(lastIter.score_components)
+                                .map(([k, v]) => `${formatDisplayValue(k)}:${typeof v === "number" ? v.toFixed(4) : formatDisplayValue(v)}`)
+                                .join(", ");
+                            if (parts.length > 0)
+                                console.log(`  Components: [${parts}]`);
+                        }
                     }
                     const flags = s.flags;
                     if (flags?.needs_human)
@@ -296,6 +405,7 @@ const main = async () => {
                 console.log(`   Goal:      ${formatDisplayValue(s.goal)}`);
                 console.log(`   Status:    ${formatDisplayValue(s.status)}`);
                 console.log(`   Mode:      ${formatDisplayValue(s.mode)}`);
+                console.log(`   Op Mode:   ${formatDisplayValue(s.operating_mode)}`);
                 if (s.metric) {
                     const m = s.metric;
                     console.log(`   Metric:    ${formatDisplayValue(m.name)} → ${formatMetricValue(m.latest)} (best: ${formatMetricValue(m.best)}, dir: ${formatDisplayValue(m.direction)})`);
@@ -307,6 +417,13 @@ const main = async () => {
                     console.log(`   Last iter: #${formatDisplayValue(lastIter.iteration)} — ${formatDisplayValue(lastIter.decision)}`);
                     if (lastIter.change_summary)
                         console.log(`   Change:    ${formatDisplayValue(lastIter.change_summary)}`);
+                    if (lastIter.score_components != null && typeof lastIter.score_components === "object") {
+                        const parts = Object.entries(lastIter.score_components)
+                            .map(([k, v]) => `${formatDisplayValue(k)}:${typeof v === "number" ? v.toFixed(4) : formatDisplayValue(v)}`)
+                            .join(", ");
+                        if (parts.length > 0)
+                            console.log(`   Components: [${parts}]`);
+                    }
                 }
                 if (flags?.needs_human)
                     console.log("   ⚠  Needs human review");
@@ -331,9 +448,9 @@ const main = async () => {
                     break;
                 }
                 const limit = parsePositiveInt(grouped.limit, "limit") ?? 10;
+                const headers = lines[0].split("\t");
                 const records = lines.slice(1).reverse().slice(0, limit);
                 if (useJson) {
-                    const headers = lines[0].split("\t");
                     const parsed = records.map((r) => {
                         const cols = r.split("\t");
                         const obj = {};
@@ -347,14 +464,221 @@ const main = async () => {
                 }
                 for (const r of records) {
                     const cols = r.split("\t");
-                    if (cols.length >= 8) {
-                        const emoji = cols[2] === "keep" ? "✓" : cols[2] === "discard" ? "✗" : "⚠";
-                        console.log(`${emoji}  #${formatDisplayValue(cols[1])}  ${formatDisplayValue(cols[2])}  (${formatMetricValue(cols[3])})  ${formatDisplayValue(cols[7].substring(0, 60))}`);
+                    if (cols.length >= 4) {
+                        const decision = tsvField(headers, cols, "decision", 2);
+                        const metricValue = tsvField(headers, cols, "metric_value", 3);
+                        const emoji = decision === "keep" ? "✓" : decision === "discard" ? "✗" : "⚠";
+                        const changeSummary = tsvField(headers, cols, "change_summary", 8);
+                        console.log(`${emoji}  #${formatDisplayValue(cols[1])}  ${formatDisplayValue(decision)}  (${formatMetricValue(metricValue)})  ${formatDisplayValue(changeSummary.substring(0, 60))}`);
                     }
                 }
                 console.log(`\nShowing ${Math.min(limit, records.length)} of ${lines.length - 1} records.`);
                 break;
             }
+            case "scores": {
+                const { resolvePath } = await import("./helpers.js");
+                const { SCORE_HISTORY_DEFAULT } = await import("./constants.js");
+                const scoreHistoryPath = resolvePath(grouped.repo, grouped["score-history-path"], SCORE_HISTORY_DEFAULT);
+                if (!existsSync(scoreHistoryPath)) {
+                    console.log("No score history found.");
+                    break;
+                }
+                const limit = parsePositiveInt(grouped.limit, "limit") ?? 10;
+                const showTopComponents = grouped["top-components"] === "true";
+                if (showTopComponents) {
+                    const allLines = readFileSync(scoreHistoryPath, "utf-8")
+                        .split("\n")
+                        .map((l) => l.trim())
+                        .filter(Boolean);
+                    const allParsed = allLines.map((r) => {
+                        try {
+                            return JSON.parse(r);
+                        }
+                        catch {
+                            return null;
+                        }
+                    }).filter(Boolean);
+                    if (allParsed.length === 0) {
+                        console.log("No score records yet.");
+                        break;
+                    }
+                    const { rankComponents } = await import("./score-parser.js");
+                    const ranking = rankComponents(allParsed);
+                    if (useJson) {
+                        printJson({ count: allParsed.length, scores: allParsed.slice(-limit), ranking });
+                        break;
+                    }
+                    console.log("Component Rankings:");
+                    if (ranking.top_positive.length > 0) {
+                        console.log("  Top improving components:");
+                        for (const c of ranking.top_positive) {
+                            console.log(`    + ${formatDisplayValue(c.name)}  Δ+${c.delta.toFixed(4)}`);
+                        }
+                    }
+                    if (ranking.top_negative.length > 0) {
+                        console.log("  Top declining components:");
+                        for (const c of ranking.top_negative) {
+                            console.log(`    - ${formatDisplayValue(c.name)}  Δ${c.delta.toFixed(4)}`);
+                        }
+                    }
+                    if (ranking.top_positive.length === 0 && ranking.top_negative.length === 0) {
+                        console.log("  No component data found in score history.");
+                    }
+                    console.log(`\nAnalyzed ${allParsed.length} score records.`);
+                    break;
+                }
+                const records = readTailLines(scoreHistoryPath, limit);
+                if (records.length === 0) {
+                    console.log("No score records yet.");
+                    break;
+                }
+                if (useJson) {
+                    const parsed = records.map((r) => {
+                        try {
+                            return JSON.parse(r);
+                        }
+                        catch {
+                            return null;
+                        }
+                    }).filter(Boolean);
+                    printJson({ count: parsed.length, scores: parsed });
+                    break;
+                }
+                console.log("Score History (latest " + Math.min(limit, records.length) + "):");
+                const recordsOrdered = records.slice().reverse();
+                const parseMetricNumber = (value) => {
+                    if (typeof value === "number") {
+                        return Number.isFinite(value) ? value : null;
+                    }
+                    if (typeof value === "string") {
+                        const parsed = Number(value);
+                        return Number.isFinite(parsed) ? parsed : null;
+                    }
+                    return null;
+                };
+                for (let i = 0; i < recordsOrdered.length; i += 1) {
+                    const r = recordsOrdered[i];
+                    try {
+                        const rec = JSON.parse(r);
+                        let trend = "";
+                        if (i + 1 < recordsOrdered.length) {
+                            try {
+                                const previousRec = JSON.parse(recordsOrdered[i + 1]);
+                                const currentMetricValue = parseMetricNumber(rec.metric_value);
+                                const previousMetricValue = parseMetricNumber(previousRec.metric_value);
+                                if (currentMetricValue !== null && previousMetricValue !== null) {
+                                    if (currentMetricValue === previousMetricValue) {
+                                        trend = "→";
+                                    }
+                                    else if (rec.metric_direction === "higher") {
+                                        trend = currentMetricValue > previousMetricValue ? "↑" : "↓";
+                                    }
+                                    else {
+                                        trend = currentMetricValue < previousMetricValue ? "↑" : "↓";
+                                    }
+                                }
+                            }
+                            catch {
+                                trend = "";
+                            }
+                        }
+                        let componentLine = "";
+                        if (rec.score_components != null && typeof rec.score_components === "object") {
+                            const parts = Object.entries(rec.score_components)
+                                .map(([k, v]) => `${formatDisplayValue(k)}:${typeof v === "number" ? v.toFixed(4) : formatDisplayValue(v)}`)
+                                .join(", ");
+                            if (parts.length > 0)
+                                componentLine = `  [${parts}]`;
+                        }
+                        let componentDeltaLine = "";
+                        if (componentLine && i + 1 < recordsOrdered.length) {
+                            try {
+                                const prevRec = JSON.parse(recordsOrdered[i + 1]);
+                                if (prevRec.score_components != null && typeof prevRec.score_components === "object") {
+                                    const deltas = [];
+                                    for (const [k, v] of Object.entries(rec.score_components)) {
+                                        const prev = prevRec.score_components[k];
+                                        if (typeof prev === "number" && typeof v === "number") {
+                                            const d = v - prev;
+                                            if (d !== 0) {
+                                                deltas.push(`${formatDisplayValue(k)}:${d > 0 ? "+" : ""}${d.toFixed(4)}`);
+                                            }
+                                        }
+                                    }
+                                    if (deltas.length > 0)
+                                        componentDeltaLine = `  Δ[${deltas.join(", ")}]`;
+                                }
+                            }
+                            catch {
+                                // ignore delta parse errors
+                            }
+                        }
+                        console.log(`  #${rec.iteration}  ${trend}  ${rec.metric_value ?? "—"}  (${rec.decision})  ${rec.verify_status}${componentLine}${componentDeltaLine}`);
+                    }
+                    catch {
+                        console.log(`  [parse error]`);
+                    }
+                }
+                console.log(`\nShowing ${records.length} score records.`);
+                break;
+            }
+            case "score": {
+                const { resolvePath, readJsonFile, AutoresearchError: AErr } = await import("./helpers.js");
+                const { STATE_DEFAULT } = await import("./constants.js");
+                const { parseScoreOutput } = await import("./score-parser.js");
+                // Resolve scorer: --scorer flag takes priority, else use state.scorer
+                let scorerCmd = grouped.scorer;
+                if (!scorerCmd) {
+                    const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                    if (existsSync(statePath)) {
+                        const state = parseRunState(readJsonFile(statePath));
+                        scorerCmd = state.scorer;
+                    }
+                }
+                if (!scorerCmd) {
+                    throw new AErr("No scorer configured. Provide --scorer <cmd> or configure a scorer via autoresearch init --scorer <cmd>.");
+                }
+                const repoBase = resolveRepo(grouped.repo);
+                let rawOutput;
+                try {
+                    rawOutput = execSync(scorerCmd, { encoding: "utf-8", cwd: repoBase, stdio: ["ignore", "pipe", "pipe"] });
+                }
+                catch (err) {
+                    const e = err;
+                    const stderr = typeof e.stderr === "string" ? e.stderr.trim() : (Buffer.isBuffer(e.stderr) ? e.stderr.toString("utf-8").trim() : "");
+                    const errMsg = stderr || (err instanceof Error ? err.message : String(err));
+                    throw new AErr(`Scorer command failed: ${errMsg}`);
+                }
+                const scored = parseScoreOutput(rawOutput);
+                const normalized = scored.score / scored.max;
+                const percent = (normalized * 100).toFixed(1) + "%";
+                if (useJson) {
+                    printJson({
+                        score: scored.score,
+                        max: scored.max,
+                        normalized,
+                        percent,
+                        components: scored.components ?? null,
+                        diagnostics: scored.diagnostics ?? null,
+                        details: scored.details ?? null,
+                    });
+                    break;
+                }
+                console.log(`Score: ${scored.score} / ${scored.max} (${percent})`);
+                if (scored.components && Object.keys(scored.components).length > 0) {
+                    console.log("Components:");
+                    for (const [key, val] of Object.entries(scored.components)) {
+                        console.log(`  ${formatDisplayValue(key)}: ${formatDisplayValue(val)}`);
+                    }
+                }
+                if (scored.diagnostics && Object.keys(scored.diagnostics).length > 0) {
+                    console.log("Diagnostics:");
+                    for (const [key, val] of Object.entries(scored.diagnostics)) {
+                        console.log(`  ${formatDisplayValue(key)}: ${formatDisplayValue(val)}`);
+                    }
+                }
+                break;
+            }
             case "config": {
                 const { resolvePath, readJsonFile } = await import("./helpers.js");
                 const { STATE_DEFAULT } = await import("./constants.js");
@@ -374,6 +698,7 @@ const main = async () => {
                         deadline_at: state.deadline_at,
                         verify: state.verify,
                         guard: state.guard,
+                        scorer: state.scorer ?? null,
                         subagent_pool: state.subagent_pool ? "configured" : "none",
                         label_requirements: state.label_requirements,
                     });
@@ -382,6 +707,7 @@ const main = async () => {
                 console.log("Run Configuration:");
                 console.log(`  Goal:     ${formatDisplayValue(state.goal)}`);
                 console.log(`  Mode:     ${formatDisplayValue(state.mode)}`);
+                console.log(`  Op Mode:  ${formatDisplayValue(state.operating_mode)}`);
                 if (state.metric) {
                     const m = state.metric;
                     console.log(`  Metric:   ${formatDisplayValue(m.name)} (${formatDisplayValue(m.direction)})`);
@@ -391,6 +717,7 @@ const main = async () => {
                 console.log(`  Deadline: ${formatDisplayValue(state.deadline_at ? formatTimestamp(state.deadline_at) : "—")}`);
                 console.log(`  Verify:   ${formatDisplayValue(state.verify)}`);
                 console.log(`  Guard:    ${formatDisplayValue(state.guard)}`);
+                console.log(`  Scorer:   ${formatDisplayValue(state.scorer ?? "—")}`);
                 console.log(`  Pool:     ${state.subagent_pool ? "configured" : "none"}`);
                 break;
             }
@@ -445,8 +772,8 @@ const main = async () => {
                 const errors = [];
                 if (!grouped.goal)
                     errors.push("Missing required: --goal");
-                if (!grouped.metric)
-                    errors.push("Missing required: --metric");
+                if (!grouped.metric && !grouped["outcome-metric"])
+                    errors.push("Missing required: --metric or --outcome-metric");
                 try {
                     if (grouped.direction)
                         normalizeDirection(grouped.direction);
@@ -470,7 +797,7 @@ const main = async () => {
                 if (errors.length === 0) {
                     console.log("✓ Configuration is valid");
                     console.log(`  Goal: ${grouped.goal}`);
-                    console.log(`  Metric: ${grouped.metric} (${grouped.direction || "lower"})`);
+                    console.log(`  Metric: ${grouped.metric || grouped["outcome-metric"]} (${grouped.direction || grouped["outcome-direction"] || "lower"})`);
                     console.log(`  Verify: ${grouped.verify}`);
                     console.log(`  Mode: ${grouped.mode || "foreground"}`);
                 }
@@ -494,9 +821,12 @@ const main = async () => {
                 }
                 const state = parseRunState(readJsonFile(statePath));
                 let results = [];
+                let resultHeaders = [];
                 if (existsSync(resultsPath)) {
                     const content = readFileSync(resultsPath, "utf-8");
-                    results = content.trim().split("\n").slice(1).filter(Boolean);
+                    const resultLines = content.trim().split("\n");
+                    resultHeaders = resultLines[0]?.split("\t") ?? [];
+                    results = resultLines.slice(1).filter(Boolean);
                 }
                 if (useJson) {
                     printJson({ state, results_count: results.length });
@@ -507,6 +837,7 @@ const main = async () => {
                 console.log(`**Goal:** ${formatMarkdownField(state.goal)}`);
                 console.log(`**Status:** ${formatMarkdownField(state.status)}`);
                 console.log(`**Mode:** ${formatMarkdownField(state.mode)}`);
+                console.log(`**Op Mode:** ${formatMarkdownField(state.operating_mode)}`);
                 if (state.metric) {
                     const m = state.metric;
                     console.log(`**Metric:** ${formatMarkdownField(m.name)} (${formatMarkdownField(m.direction)})`);
@@ -524,8 +855,11 @@ const main = async () => {
                     console.log(`\n## Iterations`);
                     for (const r of results) {
                         const cols = r.split("\t");
-                        if (cols.length >= 8) {
-                            console.log(`- ${formatMarkdownField(cols[1])}: ${formatMarkdownField(cols[2])} (${formatMarkdownField(cols[3])}) — ${formatMarkdownField(cols[7]).substring(0, 60)}`);
+                        if (cols.length >= 4) {
+                            const decision = tsvField(resultHeaders, cols, "decision", 2);
+                            const metricValue = tsvField(resultHeaders, cols, "metric_value", 3);
+                            const changeSummary = tsvField(resultHeaders, cols, "change_summary", 8);
+                            console.log(`- ${formatMarkdownField(cols[1])}: ${formatMarkdownField(decision)} (${formatMarkdownField(metricValue)}) — ${formatMarkdownField(changeSummary).substring(0, 60)}`);
                         }
                     }
                 }
@@ -541,15 +875,16 @@ const main = async () => {
                 }
                 const memory = readFileSync(memoryPath, "utf-8");
                 const patterns = memory.match(/### Pattern: [^\n]+/g) ?? [];
+                const suggestions = patterns.map(parseMemoryPatternHeading);
                 if (useJson) {
-                    printJson({ patterns_found: patterns.length, suggestions: patterns.map((p) => p.replace("### Pattern: ", "")) });
+                    printJson({ patterns_found: suggestions.length, suggestions });
                     break;
                 }
                 console.log("Memory Patterns — candidate next goals:");
-                for (const p of patterns) {
-                    console.log(`  → ${formatDisplayValue(p.replace("### Pattern: ", ""))}`);
+                for (const suggestion of suggestions) {
+                    console.log(`  → ${formatDisplayValue(suggestion)}`);
                 }
-                console.log(`\n${patterns.length} patterns available. Use 'autoresearch init --goal "..."' to start a new run.`);
+                console.log(`\n${suggestions.length} patterns available. Use 'autoresearch init --goal "..."' to start a new run.`);
                 break;
             }
             case "export": {
@@ -611,8 +946,8 @@ const main = async () => {
             }
             case "completion": {
                 const shell = grouped.shell || "bash";
-                const commands = ["init", "wizard", "status", "explain", "history", "config", "summary", "suggest", "launch", "complete", "stop", "resume", "record", "doctor", "export", "completion", "help"];
-                const options = ["--repo", "--goal", "--metric", "--direction", "--verify", "--guard", "--mode", "--scope", "--iterations", "--duration", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell"];
+                const commands = ["init", "goal", "wizard", "status", "explain", "history", "config", "summary", "suggest", "launch", "complete", "stop", "resume", "record", "doctor", "export", "completion", "help"];
+                const options = ["--repo", "--goal", "--metric", "--direction", "--verify", "--guard", "--mode", "--scope", "--iterations", "--duration", "--num-drafts", "--branch-policy", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell", "--goal-path", "--template"];
                 if (shell === "bash" || shell === "zsh") {
                     console.log(`# Auto Research CLI completion for ${shell}`);
                     console.log(`_autoresearch() {`);
@@ -647,13 +982,15 @@ const main = async () => {
                 const { LAUNCH_DEFAULT } = await import("./constants.js");
                 const config = {
                     goal: grouped.goal,
-                    metric: grouped.metric,
-                    direction: grouped.direction || "lower",
+                    metric: (grouped.metric || grouped["outcome-metric"]),
+                    direction: (grouped.direction || grouped["outcome-direction"]) || "lower",
                     verify: grouped.verify,
                     mode: "background",
                     scope: grouped.scope,
                     guard: grouped.guard,
+                    scorer: grouped.scorer,
                     iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    max_no_progress: parsePositiveInt(grouped["max-no-progress"], "max-no-progress"),
                     duration: grouped.duration,
                     memory_path: grouped["memory-path"],
                     required_keep_labels: grouped["required-keep-labels"],
@@ -661,6 +998,12 @@ const main = async () => {
                     run_tag: grouped["run-tag"],
                     stop_condition: grouped["stop-condition"],
                     baseline: grouped.baseline,
+                    num_drafts: parsePositiveInt(grouped["num-drafts"], "num_drafts", { max: MAX_DRAFTS }) ?? 1,
+                    branch_selection_policy: normalizeBranchPolicy(grouped["branch-policy"]),
+                    outcome_metric: grouped["outcome-metric"],
+                    outcome_direction: grouped["outcome-direction"],
+                    instrument_metric: grouped["instrument-metric"],
+                    instrument_direction: grouped["instrument-direction"],
                 };
                 const launchPath = resolvePath(grouped.repo, grouped["launch-path"], LAUNCH_DEFAULT);
                 if (dryRun) {
@@ -706,15 +1049,32 @@ const main = async () => {
                 break;
             }
             case "record": {
-                const { normalizeResultStatus } = await import("./helpers.js");
+                const { normalizeResultStatus, normalizeScorerStatus } = await import("./helpers.js");
                 const vs = grouped["verify-status"] || "pass";
                 const gs = grouped["guard-status"] || "skip";
+                const scorerStatus = normalizeScorerStatus(grouped["scorer-status"]);
                 const iteration = parsePositiveInt(grouped.iteration, "iteration");
+                let scoreComponents;
+                if (grouped["score-components"]) {
+                    try {
+                        const parsed = JSON.parse(grouped["score-components"]);
+                        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                            throw new Error('score-components must be a JSON object with string keys and numeric values, e.g., {"accuracy": 0.8, "coverage": 0.6}');
+                        }
+                        scoreComponents = parsed;
+                    }
+                    catch (e) {
+                        console.error(`Invalid --score-components: ${e.message}`);
+                        return 1;
+                    }
+                }
                 if (dryRun) {
                     console.log("[dry-run] Would record experiment result:");
                     console.log(JSON.stringify({
                         decision: grouped.decision,
                         metric_value: grouped["metric-value"],
+                        instrument_value: grouped["instrument-value"],
+                        scorer_status: scorerStatus,
                         verify_status: normalizeResultStatus(vs, "verify_status"),
                         guard_status: normalizeResultStatus(gs, "guard_status"),
                         hypothesis: grouped.hypothesis,
@@ -722,11 +1082,12 @@ const main = async () => {
                         labels: grouped.labels ? (Array.isArray(grouped.labels) ? grouped.labels : [grouped.labels]) : undefined,
                         note: grouped.note,
                         iteration,
+                        score_components: scoreComponents,
                     }, null, 2));
                     return 0;
                 }
                 const { appendIteration } = await import("./run-manager.js");
-                const state = await appendIteration(grouped.repo, grouped["results-path"], grouped["state-path"], grouped.decision, grouped["metric-value"], normalizeResultStatus(vs, "verify_status"), normalizeResultStatus(gs, "guard_status"), grouped.hypothesis, grouped["change-summary"], grouped.labels ? (Array.isArray(grouped.labels) ? grouped.labels : [grouped.labels]) : undefined, grouped.note, iteration);
+                const state = await appendIteration(grouped.repo, grouped["results-path"], grouped["state-path"], grouped.decision, grouped["metric-value"], grouped["instrument-value"], normalizeResultStatus(vs, "verify_status"), normalizeResultStatus(gs, "guard_status"), grouped.hypothesis, grouped["change-summary"], grouped.labels ? (Array.isArray(grouped.labels) ? grouped.labels : [grouped.labels]) : undefined, grouped.note, iteration, undefined, scorerStatus, scoreComponents);
                 printJson(state);
                 break;
             }
@@ -821,6 +1182,197 @@ const main = async () => {
                 console.log(`\nAll ${checks.length} checks passed.`);
                 break;
             }
+            case "goal": {
+                const rawSubCmd = cmdArgs[0];
+                const subCmd = rawSubCmd && !rawSubCmd.startsWith("-") ? rawSubCmd : undefined;
+                if ((!subCmd && cmdArgs.length === 0) || subCmd === "help" || (subCmd && HELP_FLAGS.includes(subCmd))) {
+                    console.error("Usage: autoresearch goal <subcommand> [options]");
+                    console.error("");
+                    console.error("Subcommands:");
+                    console.error("  init    Create a GOAL.md goal definition file");
+                    console.error("");
+                    console.error("Options (goal init):");
+                    console.error("  --goal          Goal description");
+                    console.error("  --metric        Metric name to track");
+                    console.error("  --direction     lower or higher (default: lower)");
+                    console.error("  --verify        Mechanical verification command");
+                    console.error("  --guard         Guard command for regression catch");
+                    console.error("  --mode          foreground or background (default: foreground)");
+                    console.error("  --scope         In-scope files or subsystem");
+                    console.error("  --iterations    Iteration cap");
+                    console.error("  --duration      Wall-clock cap (e.g., 5h or 300m)");
+                    console.error("  --template      Preset template: performance, quality, coverage, custom");
+                    console.error("  --goal-path     Output file path (default: .autoresearch/goal.md)");
+                    console.error("  --dry-run       Preview without writing the file");
+                    console.error("  --json          Output result as JSON");
+                    console.error("");
+                    console.error("Examples:");
+                    console.error("  autoresearch goal init --goal \"reduce errors\" --metric failures --direction lower --verify \"npm test\"");
+                    console.error("  autoresearch goal init --template performance");
+                    console.error("  autoresearch goal init  # interactive wizard");
+                    return 0;
+                }
+                if (!subCmd) {
+                    const { GOAL_DEFAULT } = await import("./constants.js");
+                    const { resolvePath } = await import("./helpers.js");
+                    const goalPath = resolvePath(grouped.repo, grouped["goal-path"], GOAL_DEFAULT);
+                    if (!existsSync(goalPath)) {
+                        console.log("No goal document found. Run 'autoresearch init' first.");
+                        break;
+                    }
+                    const doc = readGoalDoc(goalPath);
+                    if (useJson) {
+                        printJson(doc);
+                        break;
+                    }
+                    console.log(`Goal:             ${formatDisplayValue(doc.goal)}`);
+                    console.log(`Metric:           ${formatDisplayValue(doc.metric)} (${formatDisplayValue(doc.direction)})`);
+                    console.log(`Verify:           ${formatDisplayValue(doc.verify)}`);
+                    if (doc.guard)
+                        console.log(`Guard:            ${formatDisplayValue(doc.guard)}`);
+                    if (doc.file_map)
+                        console.log(`File map:         ${formatDisplayValue(doc.file_map)}`);
+                    if (doc.constraints)
+                        console.log(`Constraints:      ${formatDisplayValue(doc.constraints)}`);
+                    if (doc.stop_conditions)
+                        console.log(`Stop conditions:  ${formatDisplayValue(doc.stop_conditions)}`);
+                    break;
+                }
+                if (subCmd !== "init") {
+                    console.error(`Unknown goal subcommand: ${subCmd}`);
+                    console.error("Run 'autoresearch goal help' for usage.");
+                    return 1;
+                }
+                const goalArgs = cmdArgs.slice(1);
+                const goalParsed = parseArgs(goalArgs);
+                const goalGrouped = {};
+                for (const [k, v] of Object.entries(goalParsed)) {
+                    goalGrouped[k] = v;
+                }
+                const useGoalJson = goalGrouped.json === "true";
+                const isGoalDryRun = goalGrouped["dry-run"] === "true";
+                const { GOAL_TEMPLATES, getGoalTemplate, buildGoalDocument, buildGoalInitResult } = await import("./goal-init.js");
+                const { GOAL_DEFAULT } = await import("./constants.js");
+                const { resolvePath } = await import("./helpers.js");
+                const { existsSync: goalExistsSync } = await import("fs");
+                const templateId = goalGrouped.template ?? "custom";
+                if (!GOAL_TEMPLATES.find((t) => t.id === templateId)) {
+                    console.error(`Unknown template: ${templateId}. Valid templates: ${GOAL_TEMPLATES.map((t) => t.id).join(", ")}`);
+                    return 1;
+                }
+                const template = getGoalTemplate(templateId);
+                const templateDefaults = template?.defaults ?? {};
+                let config = {
+                    goal: goalGrouped.goal ?? templateDefaults.goal,
+                    metric: goalGrouped.metric ?? templateDefaults.metric,
+                    direction: goalGrouped.direction ?? templateDefaults.direction,
+                    verify: goalGrouped.verify ?? templateDefaults.verify,
+                    guard: goalGrouped.guard ?? templateDefaults.guard,
+                    mode: goalGrouped.mode ?? templateDefaults.mode,
+                    scope: goalGrouped.scope ?? templateDefaults.scope,
+                    iterations: goalGrouped.iterations ? parsePositiveInt(goalGrouped.iterations, "iterations") : templateDefaults.iterations,
+                    duration: goalGrouped.duration ?? templateDefaults.duration,
+                    stop_condition: goalGrouped["stop-condition"] ?? templateDefaults.stop_condition,
+                    rollback_strategy: goalGrouped["rollback-strategy"] ?? templateDefaults.rollback_strategy,
+                    template: templateId,
+                };
+                const isTTY = process.stdin.isTTY === true;
+                const hasRequiredFlags = Boolean(config.goal && config.metric && config.verify);
+                if (!hasRequiredFlags && !isTTY) {
+                    // Non-interactive stdin: try to read JSON from stdin
+                    let stdinData = "";
+                    try {
+                        stdinData = await new Promise((resolve, reject) => {
+                            const chunks = [];
+                            process.stdin.on("data", (chunk) => chunks.push(chunk));
+                            process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+                            process.stdin.on("error", reject);
+                            // Resolve immediately if stdin is closed / empty
+                            setTimeout(() => resolve(""), 200);
+                        });
+                        stdinData = stdinData.trim();
+                    }
+                    catch {
+                        stdinData = "";
+                    }
+                    if (stdinData) {
+                        try {
+                            const parsed = JSON.parse(stdinData);
+                            config = { ...config, ...parsed, template: templateId };
+                        }
+                        catch {
+                            console.error("Failed to parse stdin as JSON. Provide valid JSON or use --goal, --metric, --verify flags.");
+                            return 1;
+                        }
+                    }
+                }
+                if (!config.goal && isTTY) {
+                    // Interactive wizard
+                    const readline = await import("readline");
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                    const ask = (prompt, defaultVal) => new Promise((resolve) => {
+                        const suffix = defaultVal ? ` [${defaultVal}]` : "";
+                        rl.question(`${prompt}${suffix}: `, (answer) => {
+                            resolve(answer.trim() || defaultVal || "");
+                        });
+                    });
+                    process.stderr.write("\nAutoresearch Goal Init — Interactive Wizard\n");
+                    process.stderr.write("Press Enter to accept default values shown in brackets.\n\n");
+                    if (!config.goal)
+                        config.goal = await ask("Goal (what outcome should this run optimize?)", config.goal);
+                    if (!config.metric)
+                        config.metric = await ask("Metric name", config.metric ?? "primary_metric");
+                    if (!config.direction)
+                        config.direction = await ask("Direction (lower/higher)", config.direction ?? "lower");
+                    if (!config.verify)
+                        config.verify = await ask("Verify command", config.verify);
+                    if (!config.guard) {
+                        const guard = await ask("Guard command (optional, press Enter to skip)");
+                        if (guard)
+                            config.guard = guard;
+                    }
+                    if (!config.scope)
+                        config.scope = await ask("Scope (files or subsystem)", config.scope ?? "current repository");
+                    if (!config.mode)
+                        config.mode = await ask("Mode (foreground/background)", config.mode ?? "foreground");
+                    rl.close();
+                }
+                const goalPath = resolvePath(goalGrouped.repo, goalGrouped["goal-path"], GOAL_DEFAULT);
+                const document = buildGoalDocument(config);
+                const result = buildGoalInitResult(goalPath, config, !hasRequiredFlags && isTTY);
+                if (isGoalDryRun) {
+                    if (useGoalJson) {
+                        printJson({ ...result, dry_run: true });
+                    }
+                    else {
+                        console.log("[dry-run] Would write goal document to: " + goalPath);
+                        console.log("");
+                        console.log(document);
+                    }
+                    return 0;
+                }
+                if (goalExistsSync(goalPath) && !goalGrouped["force"]) {
+                    // Overwrite allowed by default (like init), but warn
+                    if (verbose)
+                        console.error(`[verbose] Overwriting existing ${goalPath}`);
+                }
+                atomicWriteTextInRepo(goalGrouped.repo, goalPath, document);
+                if (useGoalJson) {
+                    printJson(result);
+                }
+                else {
+                    console.log(`✓ Goal definition written to ${goalPath}`);
+                    console.log(`  Goal:    ${result.goal ?? "(unset)"}`);
+                    console.log(`  Metric:  ${result.metric ?? "(unset)"} (${result.direction})`);
+                    console.log(`  Verify:  ${result.verify ?? "(unset)"}`);
+                    console.log(`  Mode:    ${result.mode}`);
+                    if (result.template !== "custom")
+                        console.log(`  Template: ${result.template}`);
+                    console.log("");
+                    console.log(`Run 'autoresearch init --goal "..." --metric "..." --verify "..."' to start a run.`);
+                }
+                break;
+            }
             default: {
                 console.error(`Unknown command: ${cmd}`);
                 console.error("Run 'autoresearch --help' for usage.");