@oh-my-pi/pi-coding-agent 13.14.0 → 13.15.2

package/CHANGELOG.md

@@ -2,6 +2,146 @@
 
 ## [Unreleased]
 
+## [13.15.0] - 2026-03-23
+### Breaking Changes
+
+- Changed hashline edit schema from flat `op`/`pos`/`end`/`lines` fields to structured `loc`/`content` format with location-specific objects
+- Renamed hashline edit operations: `replace_line` → `{ line: anchor }`, `replace_range` → `{ block: { pos, end } }`, `append_at` → `{ append: anchor }`, `prepend_at` → `{ prepend: anchor }`, `append_file` → `"append"`, `prepend_file` → `"prepend"`
+- Changed `lines` parameter to `content` in hashline edit entries
+- Renamed hashline edit operation types: `append` → `append_at`, `prepend` → `prepend_at`, `append_eof` → `append_file`, `prepend_bof` → `prepend_file`
+- Changed hashline edit operation types from `replace` (with optional `end`) to explicit `replace_line` and `replace_range` operations
+- Added required `append_eof` and `prepend_bof` operations for file-level edits; `append` and `prepend` now require an anchor position
+- Made `pos` parameter required for `replace_line`, `append`, and `prepend` operations; `append_eof` and `prepend_bof` no longer accept anchors
+
+### Added
+
+- Added prompt for tradeoff metrics during autoresearch setup to collect secondary metrics alongside primary metric
+- Added validation of contract path specifications to reject absolute paths and parent directory references
+- Added stricter benchmark command validation in `isAutoresearchShCommand()` to reject chained commands, pipes, and redirects
+- Added protection against prototype pollution in ASI data and metric cloning by filtering `__proto__`, `constructor`, and `prototype` keys
+- Added `autoResumeArmed` flag to track when autoresearch should automatically resume pending runs
+- Added `lastAutoResumePendingRunNumber` to prevent duplicate auto-resume prompts for the same pending run
+- Added `git clean -X` invocation during failed experiment rollback to remove ignored build artifacts
+- Added validation to reject `init_experiment` when a previous run is still pending and unlogged
+- Added autoresearch contract system for validating benchmark commands, metrics, scope paths, off-limits paths, and constraints with fingerprint tracking to detect configuration drift
+- Added `autoresearch.program.md` support for repo-local playbook overlays that guide session strategy while preserving `autoresearch.md` as source of truth
+- Added pending run artifact tracking and recovery to resume incomplete experiments from `.autoresearch/runs/` directory with run numbers and benchmark logs
+- Added run directory organization with numbered run artifacts, benchmark logs, and optional checks logs for experiment traceability
+- Added segment fingerprinting to detect when benchmark configuration changes between runs and warn about potential incomparability
+- Added support for secondary metrics tracking alongside primary metric with configurable direction (lower/higher is better)
+- Added `getCurrentAutoresearchBranch()` helper to detect and validate existing autoresearch branches for session resumption
+- Added `PendingRunSummary` type to track unlogged run state including parsed metrics, ASI data, and pass/fail status
+- Added hidden next-turn message delivery via `deliverAs: 'nextTurn'` with optional `triggerTurn` to queue context for next LLM call without exposing in editable queue
+- Added `#queueHiddenNextTurnMessage()` and `#promptQueuedHiddenNextTurnMessages()` to AgentSession for autonomous tool reactions
+- Added resume context support in `command-resume.md` template for user-provided guidance when resuming sessions
+- Added current segment snapshot display in autoresearch prompt showing recent runs, baseline metrics, and best results
+- Added pending run indicator in autoresearch prompt to guide users to complete unlogged experiments before starting new benchmarks
+- Added local playbook section in autoresearch prompt when `autoresearch.program.md` exists
+- Added tab replacement in dashboard and tool output rendering to prevent display corruption from shell commands with tabs
+- Added boundary duplication warning when replace_range or replace_line operations include a last inserted line that matches the next surviving line, helping detect off-by-one range errors
+- Added git branch isolation for autoresearch sessions via `ensureAutoresearchBranch()` to safely revert failed experiments
+- Added branch status line to autoresearch initialization and resume prompts showing created or reused branch name
+- Added `Files in Scope`, `Off Limits`, and `Constraints` sections to autoresearch.md template for explicit scope definition
+- Added validation of ASI metadata requirements in `log_experiment` tool, requiring hypothesis for all runs and rollback context for failed runs
+- Added keybinding matcher utilities `matchesAppInterrupt()` and `matchesSelectCancel()` for consistent escape key handling across components
+- Added support for customizable `app.interrupt` and `tui.select.cancel` keybindings in interactive components
+- Added `defaultInactive` property to `ToolDefinition` to allow tools to be registered but excluded from the initial active set, with extension responsibility for activation/deactivation
+- Added dynamic tool activation/deactivation in autoresearch mode via `setActiveTools()` API
+- Added separate initialization and resume workflows for autoresearch with `command-initialize.md` and `command-resume.md` prompts
+- Added intent dialog to prompt users for autoresearch optimization goals when starting fresh
+- Added automatic detection of existing `autoresearch.md` to resume from previous sessions without re-prompting for intent
+- Added autoresearch extension with autonomous experiment loop capabilities
+- Added `init_experiment` tool to initialize and reset autoresearch sessions with configurable metrics
+- Added `log_experiment` tool to record experiment results with metric parsing and confidence tracking
+- Added `run_experiment` tool to execute commands and capture metrics with timeout and crash detection
+- Added autoresearch dashboard controller for displaying experiment results and optimization progress
+- Added support for secondary metrics tracking alongside primary metric
+- Added `ExtensionWidgetContent` and `ExtensionUiComponentFactory` types for flexible widget configuration
+- Added `ExtensionWidgetOptions` interface with `placement` parameter to position widgets above or below editor
+- Added `WidgetPlacement` type supporting 'aboveEditor' and 'belowEditor' placement options
+- Added `hookWidgetContainerAbove` and `hookWidgetContainerBelow` containers to InteractiveMode for separate widget management
+- Added autoresearch mode for autonomous experiment loops with init_experiment, log_experiment, and run_experiment tools
+- Added autoresearch dashboard widget displaying experiment results, metrics, and optimization progress
+- Added support for metric tracking with configurable direction (lower/higher is better) and secondary metrics
+- Added widget placement options to position extensions above or below the editor via `placement` parameter
+- Added `ExtensionWidgetContent` and `ExtensionWidgetOptions` types for flexible widget configuration
+- Added ACP (Agent Client Protocol) mode for headless agent operation via `--mode acp`
+- Added support for Agent Client Protocol SDK integration with session management, MCP server configuration, and streaming communication
+- Added `ensureOnDisk()` method to SessionManager to persist sessions immediately for ACP discovery
+
+### Changed
+
+- Changed `isAutoresearchShCommand()` to use proper command-line argument parsing instead of regex, improving accuracy for complex shell invocations
+- Changed autoresearch initialization prompt to display collected tradeoff metrics in the setup summary
+- Changed `command-initialize.md` template to include guidance on preflight requirements, comparability invariants, and marking measurement-critical files as off-limits
+- Changed `command-initialize.md` to instruct users to write or update `autoresearch.program.md` with durable heuristics and repo-specific strategy
+- Changed autoresearch resume guidance to emphasize continuing on the current protected branch rather than switching branches
+- Changed autoresearch prompt to clarify that `autoresearch.md` holds durable conclusions while `autoresearch.ideas.md` is the scratch backlog
+- Changed autoresearch prompt guidance to require stable measurement harness and fixed benchmark inputs unless intentionally starting a new segment
+- Changed autoresearch prompt to recommend keeping equal or near-equal results when they materially simplify implementation
+- Changed `init_experiment` to reset pending run state (checks, duration, ASI, artifact directory) when initializing a new segment
+- Changed `log_experiment` to set `autoResumeArmed` flag after successfully logging a run to enable auto-resume on next agent turn
+- Changed `run_experiment` to set `autoResumeArmed` flag and update dashboard after completing a run
+- Changed auto-resume logic to only prompt when a new pending run exists or when `autoResumeArmed` is explicitly set, preventing duplicate prompts
+- Changed path normalization in contract validation to use `path.posix.normalize()` for consistent path handling
+- Changed autoresearch initialization to collect and validate benchmark command, metric definition, scope paths, off-limits list, and constraints before `init_experiment`
+- Changed `init_experiment` to require exact benchmark command, metric definition, scope, off-limits, and constraints matching collected contract
+- Changed `log_experiment` to record run number, benchmark command, scope paths, off-limits list, constraints, and segment fingerprint with each result
+- Changed `run_experiment` to organize output in numbered run directories with separate benchmark and checks logs for artifact preservation
+- Changed autoresearch dashboard to show pending run indicator when unlogged experiment exists
+- Changed autoresearch resume workflow to detect and offer recovery of pending run artifacts before continuing experiment loop
+- Changed `ExperimentResult` to include `runNumber`, `benchmarkCommand`, `scopePaths`, `offLimits`, `constraints`, and `segmentFingerprint` fields
+- Changed `RunningExperiment` to track `runDirectory` and `runNumber` for artifact organization
+- Changed `AutoresearchRuntime` to include `lastRunArtifactDir`, `lastRunNumber`, `lastRunSummary`, `benchmarkCommand`, `secondaryMetrics`, `scopePaths`, `offLimits`, `constraints`, and `segmentFingerprint`
+- Changed autoresearch prompts to emphasize `autoresearch.md` as source of truth for benchmark, scope, and constraints
+- Changed `command-initialize.md` to display collected setup (benchmark command, metric, direction, scope, off-limits, constraints) before initialization
+- Changed `resume-message.md` to reference pending run artifacts and guide completion of unlogged experiments
+- Changed `sendMessage()` API documentation to clarify `deliverAs: 'nextTurn'` behavior for hidden context delivery
+- Changed `SendMessageHandler` type documentation to explain hidden next-turn message queuing during prompt teardown
+- Changed autoresearch startup to create or reuse a dedicated `autoresearch/...` git branch before enabling the experiment loop
+- Changed autoresearch to refuse startup when unrelated worktree changes would make auto-reverts unsafe
+- Changed autoresearch prompts to emphasize scope and constraints as source of truth for session direction
+- Changed component escape key handling to use keybinding manager for `app.interrupt` and `tui.select.cancel` with fallback to raw Escape matching
+- Updated autoresearch prompt guidance to require explicit files in scope, off-limits paths, and session constraints
+- Changed autoresearch command to use intent-based initialization instead of goal parameter, with user input dialog for new sessions
+- Changed autoresearch startup to create or reuse a dedicated `autoresearch/...` git branch before enabling the experiment loop, and to refuse startup when unrelated worktree changes would make auto-reverts unsafe
+- Changed autoresearch startup to activate experiment tools (`init_experiment`, `run_experiment`, `log_experiment`) only when autoresearch mode is enabled
+- Changed autoresearch shutdown to deactivate experiment tools when mode is disabled or cleared
+- Changed autoresearch session rehydration to dynamically manage experiment tool activation based on session state
+- Changed autoresearch prompts and notes guidance to require explicit files in scope, off-limits paths, and session constraints
+- Refactored hashline edit validation to enforce stricter anchor requirements per operation type
+- Updated edit application logic to handle explicit file-level operations (`append_eof`, `prepend_bof`) separately from anchor-based operations
+- Changed `setWidget` API to accept `ExtensionWidgetOptions` parameter for placement control
+- Changed widget placement logic to manage widgets above and below editor separately
+- Changed hashline edit application to preserve duplicated boundary lines exactly as provided instead of auto-correcting them
+- Updated RPC mode to support widget placement option in `setWidget` requests
+- Changed hashline edit application to preserve duplicated boundary lines exactly as provided instead of auto-correcting them
+- Changed widget API to support placement options and component factories in addition to string arrays
+- Updated extension UI controller to manage widgets above and below the editor separately
+- Updated ask tool rendering to support markdown formatting in questions and option labels
+- Refactored hook input and selector components to render titles as markdown for richer text formatting
+- Changed session collection to include sessions with zero messages, enabling ACP mode to create discoverable sessions immediately
+- Changed session persistence logic to use atomic file rewrite when flushing unflushed sessions to prevent duplication
+- Removed hashline edit autocorrection for duplicated boundary lines; escaped-tab autocorrection remains available for leading `\\t` sequences
+
+### Removed
+
+- Removed `command-start.md` prompt template in favor of separate initialize and resume workflows
+- Removed auto-correction of off-by-one range edits that duplicated closing braces or boundary lines
+- Removed `shouldAutocorrect` function and related boundary line deduplication logic from hashline editor
+- Removed auto-correction of off-by-one range edits that duplicated closing braces or boundary lines
+
+### Fixed
+
+- Fixed boundary duplication warnings to always display when replacement lines match the next surviving line, even when auto-correction is disabled
+- Fixed secondary metrics validation to properly reject missing configured metrics and new metrics without force flag
+- Fixed ASI data cloning to prevent prototype pollution attacks by filtering reserved property names
+- Fixed autoresearch resume to detect and recover pending run artifacts that were left unlogged from previous sessions
+- Fixed dashboard overlay to display when running experiment even with zero completed results
+- Fixed tab character rendering in dashboard command display and tool output summaries
+- Fixed autoresearch logging to require durable ASI metadata (hypothesis, rollback_reason, next_action_hint) for every run including rollback context for discarded, crashed, and checks-failed experiments
+- Fixed autoresearch logging to require durable ASI metadata for every run, including rollback context for discarded, crashed, and checks-failed experiments
+
 ## [13.14.0] - 2026-03-20
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.14.0",
+	"version": "13.15.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -40,13 +40,14 @@
 		"test": "bun test"
 	},
 	"dependencies": {
+		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.14.0",
-		"@oh-my-pi/pi-agent-core": "13.14.0",
-		"@oh-my-pi/pi-ai": "13.14.0",
-		"@oh-my-pi/pi-natives": "13.14.0",
-		"@oh-my-pi/pi-tui": "13.14.0",
-		"@oh-my-pi/pi-utils": "13.14.0",
+		"@oh-my-pi/omp-stats": "13.15.2",
+		"@oh-my-pi/pi-agent-core": "13.15.2",
+		"@oh-my-pi/pi-ai": "13.15.2",
+		"@oh-my-pi/pi-natives": "13.15.2",
+		"@oh-my-pi/pi-tui": "13.15.2",
+		"@oh-my-pi/pi-utils": "13.15.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",
@@ -54,7 +55,8 @@
 		"diff": "^8.0",
 		"handlebars": "^4.7",
 		"linkedom": "^0.18",
-		"puppeteer": "^24.37"
+		"puppeteer": "^24.37",
+		"zod": "4.3.6"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3"

package/src/autoresearch/command-initialize.md

@@ -0,0 +1,34 @@
+Set up autoresearch for this intent:
+
+{{intent}}
+
+{{branch_status_line}}
+
+Collected setup:
+
+- benchmark command: `{{benchmark_command}}`
+- primary metric: `{{metric_name}}`
+- metric unit: `{{metric_unit}}`
+- direction: `{{direction}}`
+- tradeoff metrics:
+{{{secondary_metrics_block}}}
+- files in scope:
+{{{scope_paths_block}}}
+- off limits:
+{{{off_limits_block}}}
+- constraints:
+{{{constraints_block}}}
+
+Explain briefly what autoresearch will do in this repository, then initialize the workspace.
+
+Your first actions:
+- write `autoresearch.md`
+- record the collected benchmark command, primary metric, metric unit, direction, tradeoff metrics, scope, off-limits list, and constraints in `autoresearch.md`
+- add a short preflight section in `autoresearch.md` covering prerequisites, one-time setup, and the comparability invariant that must stay fixed across runs
+- explicitly mark the ground-truth evaluator, fixed datasets, and other measurement-critical files as off-limits or hard constraints when they define the benchmark contract
+- write or update `autoresearch.program.md` when you learn durable heuristics, failure patterns, or repo-specific strategy that future resume turns should inherit
+- define the benchmark entrypoint in `autoresearch.sh`
+- optionally add `autoresearch.checks.sh` if correctness or quality needs a hard gate
+- run `init_experiment` with the exact collected benchmark command, metric definition, scope paths, off-limits list, and constraints
+- run and log the baseline
+- keep iterating until interrupted or until the configured iteration cap is reached

package/src/autoresearch/command-resume.md

@@ -0,0 +1,17 @@
+Resume autoresearch from the attached notes.
+
+@{{autoresearch_md_path}}
+
+{{branch_status_line}}
+{{#if has_resume_context}}
+
+Additional context from the user:
+
+{{resume_context}}
+{{/if}}
+
+Use the notes as the source of truth for the current direction, scope, and constraints.
+- inspect recent git history for context
+- inspect `autoresearch.jsonl` if it exists
+- continue the most promising unfinished direction on the current protected branch
+- keep iterating until interrupted or until the configured iteration cap is reached

package/src/autoresearch/contract.ts

@@ -0,0 +1,332 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AutoresearchBenchmarkContract, AutoresearchContract, MetricDirection } from "./types";
+
+export interface AutoresearchContractLoadResult {
+	contract: AutoresearchContract;
+	errors: string[];
+	path: string;
+}
+
+export interface AutoresearchScriptSnapshot {
+	benchmarkScript: string;
+	benchmarkScriptPath: string;
+	checksScript: string | null;
+	checksScriptPath: string;
+	errors: string[];
+}
+
+const HEADING_REGEX = /^##\s+(.+?)\s*$/;
+const LIST_ITEM_REGEX = /^\s*[-*]\s+(.*)$/;
+const KEY_VALUE_REGEX = /^\s*[-*]\s+([^:]+):\s*(.*)$/;
+
+export function readAutoresearchContract(workDir: string): AutoresearchContractLoadResult {
+	const contractPath = path.join(workDir, "autoresearch.md");
+	let content = "";
+	try {
+		content = fs.readFileSync(contractPath, "utf8");
+	} catch {
+		return {
+			contract: createEmptyAutoresearchContract(),
+			errors: [`${contractPath} does not exist. Create it before initializing autoresearch.`],
+			path: contractPath,
+		};
+	}
+
+	const contract = parseAutoresearchContract(content);
+	const errors = validateAutoresearchContract(contract);
+	return { contract, errors, path: contractPath };
+}
+
+export function parseAutoresearchContract(markdown: string): AutoresearchContract {
+	const sections = extractSections(markdown);
+	return {
+		benchmark: parseBenchmarkSection(sections.get("benchmark") ?? ""),
+		scopePaths: parseListSection(sections.get("files in scope") ?? "", normalizeContractPathSpec),
+		offLimits: parseListSection(sections.get("off limits") ?? "", normalizeContractPathSpec),
+		constraints: parseListSection(sections.get("constraints") ?? ""),
+	};
+}
+
+export function validateAutoresearchContract(contract: AutoresearchContract): string[] {
+	const errors: string[] = [];
+	if (!contract.benchmark.command) {
+		errors.push("Benchmark.command is required in autoresearch.md.");
+	}
+	if (!contract.benchmark.primaryMetric) {
+		errors.push("Benchmark.primary metric is required in autoresearch.md.");
+	}
+	if (!contract.benchmark.direction) {
+		errors.push("Benchmark.direction must be `lower` or `higher` in autoresearch.md.");
+	}
+	if (contract.scopePaths.length === 0) {
+		errors.push("Files in Scope must contain at least one path in autoresearch.md.");
+	}
+	for (const scopePath of contract.scopePaths) {
+		if (isUnsafeContractPathSpec(scopePath)) {
+			errors.push(`Files in Scope contains an invalid path: ${scopePath}`);
+		}
+	}
+	for (const offLimitsPath of contract.offLimits) {
+		if (isUnsafeContractPathSpec(offLimitsPath)) {
+			errors.push(`Off Limits contains an invalid path: ${offLimitsPath}`);
+		}
+	}
+	return errors;
+}
+
+export function buildAutoresearchSegmentFingerprint(
+	contract: AutoresearchContract,
+	scripts: {
+		benchmarkScript: string;
+		checksScript: string | null;
+	},
+): string {
+	const payload = {
+		benchmark: contract.benchmark,
+		scopePaths: contract.scopePaths,
+		offLimits: contract.offLimits,
+		constraints: contract.constraints,
+		scripts,
+	};
+	return crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+export function getAutoresearchFingerprintMismatchError(
+	stateFingerprint: string | null,
+	workDir: string,
+): string | null {
+	if (!stateFingerprint) {
+		return "The current segment has no fingerprint metadata. Re-run init_experiment before continuing.";
+	}
+
+	const contractResult = readAutoresearchContract(workDir);
+	const scriptSnapshot = loadAutoresearchScriptSnapshot(workDir);
+	const errors = [...contractResult.errors, ...scriptSnapshot.errors];
+	if (errors.length > 0) {
+		return `${errors.join(" ")} Re-run init_experiment after fixing the workspace contract.`;
+	}
+
+	const currentFingerprint = buildAutoresearchSegmentFingerprint(contractResult.contract, {
+		benchmarkScript: scriptSnapshot.benchmarkScript,
+		checksScript: scriptSnapshot.checksScript,
+	});
+	if (currentFingerprint === stateFingerprint) {
+		return null;
+	}
+
+	return "autoresearch.md, autoresearch.sh, or autoresearch.checks.sh changed since the current segment was initialized. Re-run init_experiment before continuing.";
+}
+
+export function loadAutoresearchScriptSnapshot(workDir: string): AutoresearchScriptSnapshot {
+	const benchmarkScriptPath = path.join(workDir, "autoresearch.sh");
+	const checksScriptPath = path.join(workDir, "autoresearch.checks.sh");
+	const errors: string[] = [];
+
+	let benchmarkScript = "";
+	try {
+		benchmarkScript = fs.readFileSync(benchmarkScriptPath, "utf8");
+	} catch {
+		errors.push(`${benchmarkScriptPath} does not exist. Create it before initializing autoresearch.`);
+	}
+
+	let checksScript: string | null = null;
+	try {
+		checksScript = fs.readFileSync(checksScriptPath, "utf8");
+	} catch {
+		checksScript = null;
+	}
+
+	return {
+		benchmarkScript,
+		benchmarkScriptPath,
+		checksScript,
+		checksScriptPath,
+		errors,
+	};
+}
+
+export function normalizeAutoresearchList(values: readonly string[]): string[] {
+	const normalized: string[] = [];
+	const seen = new Set<string>();
+	for (const value of values) {
+		const trimmed = value.trim();
+		if (trimmed.length === 0) continue;
+		if (seen.has(trimmed)) continue;
+		seen.add(trimmed);
+		normalized.push(trimmed);
+	}
+	return normalized;
+}
+
+export function normalizeContractPathSpec(value: string): string {
+	const normalized = path.posix.normalize(value.trim().replaceAll("\\", "/"));
+	if (normalized === "." || normalized === "./") return ".";
+	return normalized.replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+
+export function pathMatchesContractPath(pathValue: string, specValue: string): boolean {
+	const normalizedPath = normalizeContractPathSpec(pathValue);
+	const normalizedSpec = normalizeContractPathSpec(specValue);
+	if (normalizedSpec === ".") return true;
+	return normalizedPath === normalizedSpec || normalizedPath.startsWith(`${normalizedSpec}/`);
+}
+
+export function contractListsEqual(left: readonly string[], right: readonly string[]): boolean {
+	const normalizedLeft = normalizeAutoresearchList(left);
+	const normalizedRight = normalizeAutoresearchList(right);
+	if (normalizedLeft.length !== normalizedRight.length) return false;
+	return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+
+export function contractPathListsEqual(left: readonly string[], right: readonly string[]): boolean {
+	const normalizedLeft = normalizeContractPathList(left);
+	const normalizedRight = normalizeContractPathList(right);
+	if (normalizedLeft.length !== normalizedRight.length) return false;
+	return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+
+function createEmptyAutoresearchContract(): AutoresearchContract {
+	return {
+		benchmark: {
+			command: null,
+			primaryMetric: null,
+			metricUnit: "",
+			direction: null,
+			secondaryMetrics: [],
+		},
+		scopePaths: [],
+		offLimits: [],
+		constraints: [],
+	};
+}
+
+function normalizeContractPathList(values: readonly string[]): string[] {
+	return normalizeAutoresearchList(values.map(normalizeContractPathSpec)).sort((left, right) =>
+		left.localeCompare(right),
+	);
+}
+
+function extractSections(markdown: string): Map<string, string> {
+	const sections = new Map<string, string>();
+	const lines = markdown.split("\n");
+	let currentHeading: string | null = null;
+	let currentLines: string[] = [];
+
+	for (const line of lines) {
+		const headingMatch = line.match(HEADING_REGEX);
+		if (headingMatch) {
+			if (currentHeading) {
+				sections.set(currentHeading, currentLines.join("\n").trim());
+			}
+			currentHeading = headingMatch[1]?.trim().toLowerCase() ?? null;
+			currentLines = [];
+			continue;
+		}
+		if (currentHeading) {
+			currentLines.push(line);
+		}
+	}
+
+	if (currentHeading) {
+		sections.set(currentHeading, currentLines.join("\n").trim());
+	}
+	return sections;
+}
+
+function parseBenchmarkSection(section: string): AutoresearchBenchmarkContract {
+	const entries = new Map<string, string>();
+	const lines = section.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const rawLine = lines[index] ?? "";
+		const match = rawLine.match(KEY_VALUE_REGEX);
+		if (!match) continue;
+		const key = normalizeKey(match[1] ?? "");
+		let value = (match[2] ?? "").trim();
+		if (key === "secondarymetrics") {
+			const nestedItems: string[] = [];
+			for (let nestedIndex = index + 1; nestedIndex < lines.length; nestedIndex += 1) {
+				const nestedLine = lines[nestedIndex] ?? "";
+				if (nestedLine.match(KEY_VALUE_REGEX)) break;
+				const nestedMatch = nestedLine.match(/^\s{2,}[-*]\s+(.*)$/);
+				if (!nestedMatch) {
+					if (nestedLine.trim().length > 0) break;
+					continue;
+				}
+				nestedItems.push((nestedMatch[1] ?? "").trim());
+				index = nestedIndex;
+			}
+			if (nestedItems.length > 0) {
+				value = [value, ...nestedItems].filter(Boolean).join(", ");
+			}
+		}
+		entries.set(key, value);
+	}
+
+	const direction = parseDirection(entries.get("direction"));
+	return {
+		command: readNullableEntry(entries.get("command")),
+		primaryMetric: readNullableEntry(entries.get("primarymetric")),
+		metricUnit: entries.get("metricunit")?.trim() ?? "",
+		direction,
+		secondaryMetrics: parseSecondaryMetrics(entries.get("secondarymetrics")),
+	};
+}
+
+function parseListSection(section: string, normalizeItem?: (value: string) => string): string[] {
+	const items: string[] = [];
+	let activeItem: string | null = null;
+	for (const rawLine of section.split("\n")) {
+		const line = rawLine.trimEnd();
+		if (line.trim().length === 0) continue;
+		const match = rawLine.match(LIST_ITEM_REGEX);
+		if (match) {
+			if (activeItem) items.push(activeItem);
+			activeItem = (match[1] ?? "").trim();
+			continue;
+		}
+		if (activeItem && /^\s{2,}\S/.test(rawLine)) {
+			activeItem = `${activeItem} ${line.trim()}`;
+			continue;
+		}
+		if (activeItem) {
+			items.push(activeItem);
+			activeItem = null;
+		}
+		items.push(line.trim());
+	}
+	if (activeItem) {
+		items.push(activeItem);
+	}
+	const normalizedItems = normalizeAutoresearchList(items);
+	return normalizeItem ? normalizedItems.map(normalizeItem) : normalizedItems;
+}
+
+function normalizeKey(value: string): string {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function parseDirection(value: string | undefined): MetricDirection | null {
+	if (value === "lower" || value === "higher") return value;
+	return null;
+}
+
+function readNullableEntry(value: string | undefined): string | null {
+	const trimmed = value?.trim() ?? "";
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+function parseSecondaryMetrics(value: string | undefined): string[] {
+	if (!value) return [];
+	return normalizeAutoresearchList(
+		value
+			.split(",")
+			.map(entry => entry.trim())
+			.filter(Boolean),
+	);
+}
+
+function isUnsafeContractPathSpec(value: string): boolean {
+	return path.posix.isAbsolute(value) || value === ".." || value.startsWith("../");
+}