Autofix¶

autofix -- mvp.autofix

Cluster: Uncategorised | Type: component | MCP Tools: 7

Overview¶

The Autofix Dogfood Harness is a single frozen component that hardens a codebase toward production readiness. It inspects the code, picks the highest-yield next step, applies a propose-only fix in an isolated git worktree, tests the result through the correct interface (GUI / TUI / REST / MCP / shell), records traces in workspace memory, reflects with a T3 self-improvement loop, extracts reusable algorithms, and repeats.

The harness never auto-merges. Every proposed change stops at a human-approval gate; the founder merges. It reuses the existing G6 self-improvement engine (reliability/self_improve/), patch server, autonomy governor, and reliability orchestrator rather than re-implementing them. See docs/autofix/GOAL.md for the full mission brief.

Operations¶

Operation	Description
`ops` / `help`	List supported operations
`observe`	Read-only: ingested audit backlog + release-gate status
`audit`	Ingest/refresh the Codex production audit into the backlog
`cycle`	Run one propose-only autofix cycle on a component
`loop`	Run the open-ended propose-only dogfood loop
`report`	Produce a production-readiness report
`sanity_check`	Run the 7-axis component design sanity check
`db_repair`	Produce a safe, reversible vibe-coded-DB repair plan

Completion States¶

Every result carries an honest completion state (RELIABILITY_SPEC §1):

VERIFIED_READY — verified against evidence.
QUALIFIED_DRAFT — produced but not fully verified; degraded is set and degradation_reason explains what is missing.
BLOCKED_ESCALATED — cannot proceed without a human decision.

Build Status¶

The component is built across PRs P0.1-P4.4 of the build plan. At scaffold stage only ops/help are wired; the real operations report QUALIFIED_DRAFT until their PRs land. Production maturity is asserted only at the freeze PR (P4.4) once invariant tier T3 is confirmed.

Source Files¶

File	Purpose
`components/mvp/autofix/__init__.py`	Public exports
`components/mvp/autofix/schema.py`	`AutofixInput`, `AutofixOutput`, `AutofixState`
`components/mvp/autofix/autofix_block.py`	`AutofixBlock` — operation dispatch

Public API¶

`AuditFinding(BaseModel)`¶

One actionable item derived from the Codex audit.

Field	Type	Default
`finding_id`	`str`	required
`unit`	`str`	required
`unit_category`	`str`	required
`kind`	`str`	required
`severity`	`str`	required
`verdict`	`str`	''
`summary`	`str`	''
`source`	`str`	''
`fix_plan`	`str`	''
`test_plan`	`str`	''
`status`	`str`	'needs_verification'
`detail`	`dict[str, Any]`	Field(default_factory=dict)

`AuditBacklog(BaseModel)`¶

A queryable collection of audit findings.

Field	Type	Default
`audit_root`	`str`	required
`generated_at`	`str`	required
`findings`	`list[AuditFinding]`	Field(default_factory=list)

Methods:

`open_items() -> list[AuditFinding]`¶

`by_severity(severity: str) -> list[AuditFinding]`¶

`for_unit(unit: str) -> list[AuditFinding]`¶

`top(n: int) -> list[AuditFinding]`¶

The n highest-severity findings (critical first).

`counts() -> dict[str, int]`¶

`to_markdown() -> str`¶

`AutofixBlock(AIBlock[AutofixInput, AutofixOutput, AutofixState])`¶

Single frozen entrypoint for the Autofix Dogfood Harness.

Field	Type	Default
`name`	`str`	'autofix'
`state`	`AutofixState`	field(default_factory=AutofixState)
`memory`	`AutofixWorkspaceMemory \\| None`	field(default=None, repr=False)
`engine`	`Any`	field(default=None, repr=False)
`reporter`	`Any`	field(default=None, repr=False)
`sanity_checker`	`Any`	field(default=None, repr=False)
`db_repairer`	`Any`	field(default=None, repr=False)

Methods:

`infer(data: AutofixInput) -> Result[AutofixOutput]`¶

`to_dict() -> dict[str, Any]`¶

Serialise the block's persistable state to a checkpoint dict.

`from_dict(data: dict[str, Any]) -> 'AutofixBlock'`¶

Reconstruct a block from a :meth:to_dict checkpoint.

`DbRepairPlan(BaseModel)`¶

A propose-only, human-reviewable repair plan for one SQLite database.

Field	Type	Default
`db_path`	`str`	required
`issues`	`list[dict]`	Field(default_factory=list)
`steps`	`list[dict]`	Field(default_factory=list)
`before_schema`	`dict \\| str`	''
`after_schema`	`dict \\| str`	''
`after_summary`	`str`	''
`explanation`	`str`	''
`reversible`	`bool`	True
`completion_state`	`str`	QUALIFIED_DRAFT
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None

`VibeDbRepairer`¶

Propose-only repair harness for vibe-coded SQLite databases.

Methods:

`analyze(db_path: str, expected_schema: str | None = None) -> DbRepairPlan`¶

Inspect db_path and produce a propose-only repair plan.

`EngineCycleResult(BaseModel)`¶

The record of one :meth:AutofixEngine.run_cycle invocation.

Field	Type	Default
`target`	`AutofixTarget`	required
`harness_outcome`	`str`	'incomplete'
`completion_state`	`str`	''
`recorded`	`bool`	False
`reflection`	`dict[str, Any]`	Field(default_factory=dict)
`merged`	`bool`	False
`message`	`str`	''
`steps`	`list[str]`	Field(default_factory=list)
`surface_results`	`list[dict[str, Any]]`	Field(default_factory=list)
`diff`	`str`	''
`proposed_files`	`dict[str, str]`	Field(default_factory=dict)
`safety_verdict`	`str \\| None`	None
`safety_rationale`	`str`	''
`gate_passed`	`bool \\| None`	None
`gate_status`	`str`	''
`baseline_status`	`str`	''
`monitor_status`	`str`	''
`artifact_dir`	`str`	''
`hitl_gate_id`	`str \\| None`	None
`hitl_gate_queued`	`bool`	False
`formal_verified`	`bool \\| None`	None
`formal_counterexample`	`dict[str, Any] \\| None`	None
`formal_tier`	`int \\| None`	None
`formal_method`	`str`	''
`formal_fidelity`	`float \\| None`	None
`formal_input_domain`	`str`	''
`formal_review_required`	`bool`	False
`formal_error_code`	`str`	''
`formal_representations`	`tuple[dict[str, Any], ...]`	()

`AutofixEngine`¶

The Autofix Dogfood Harness core loop — a thin, propose-only composer.

Constructor:

Parameter	Type	Default
`repo_root`	`str \\| Path \\| None`	None
`memory`	`AutofixWorkspaceMemory \\| None`	None
`harness`	`_HarnessLike \\| None`	None
`selector`	`NextStepSelector \\| None`	None
`interpreter`	`GoalInterpreter \\| None`	None
`router`	`Any`	None

Methods:

`from_repo(repo_root: str | Path | None = None) -> 'AutofixEngine'`¶

Build an engine with real defaults for repo_root.

`run_cycle(target: AutofixTarget | None = None, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, exclude_units: Collection[str] | None = None, scope_contract: dict[str, Any] | None = None) -> EngineCycleResult`¶

Run one propose-only autofix cycle.

`run_loop(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False) -> list[EngineCycleResult]`¶

Run up to max_cycles propose-only cycles, stopping early.

`run_loop_with_scorecard(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, window: str = '7d', release_report: dict[str, Any] | None = None, prior_scorecard: Any = None) -> DogfoodLoopReport`¶

Run the propose-only loop and emit the DogfoodScorecard go/no-go.

`verify_surfaces(changed_paths: list[str], component: str = '') -> list[Any]`¶

Verify a change through the correct G6 surfaces (the verify step).

`GoalInterpreter`¶

Interpret a free-text goal into a normalised :class:AutofixTarget.

Constructor:

Parameter	Type	Default
`component_names`	`set[str] \\| None`	None

Methods:

`interpret(goal_text: str, backlog: 'AuditBacklog | None' = None) -> AutofixTarget`¶

Turn goal_text into a normalised :class:AutofixTarget.

`decompose(goal_text: str)`¶

Decompose a rich multi-step goal via :class:GoalDecomposer.

`AutofixWorkspaceMemory`¶

Manages the 13-file .autofix-workspace/ workspace memory.

Constructor:

Parameter	Type	Default
`root`	`Path \\| str \\| None`	None

Methods:

`exists() -> bool`¶

`path(name: str) -> Path`¶

Resolve name to a path inside the workspace (sandbox-checked).

`ensure() -> list[str]`¶

Create the workspace dir and any missing files. Idempotent.

`read(name: str) -> str`¶

`write(name: str, content: str) -> None`¶

Overwrite a living memory file. Refused for append-only logs.

`append(name: str, entry: str) -> None`¶

Append a timestamped entry, preserving all prior content.

`NextStepSelector`¶

Ranks an audit backlog into highest-yield-first :class:AutofixTargets.

Methods:

`select(backlog: AuditBacklog, limit: int = 10, store: ReliabilityStore | None = None, exclude_units: Collection[str] | None = None) -> list[AutofixTarget]`¶

Rank backlog's open findings into :class:AutofixTarget objects.

`ReadinessReport(BaseModel)`¶

The synthesised production-readiness report.

Field	Type	Default
`overall_status`	`str`	'unknown'
`gate_summary`	`dict[str, Any]`	Field(default_factory=dict)
`audit_summary`	`dict[str, Any]`	Field(default_factory=dict)
`scorecard_summary`	`dict[str, Any]`	Field(default_factory=dict)
`top_risks`	`list[str]`	Field(default_factory=list)
`completion_state`	`str`	QUALIFIED_DRAFT
`markdown`	`str`	''

`ProductionReadinessReporter`¶

Synthesises the release gate + scorecard + audit backlog into one report.

Constructor:

Parameter	Type	Default
`gate_builder`	`GateBuilder \\| None`	None
`scorecard_generator`	`ScorecardGenerator \\| None`	None
`audit_ingester`	`AuditIngester \\| None`	None
`window`	`str`	'7d'

Methods:

`build() -> ReadinessReport`¶

Assemble the production-readiness report. Never raises.

`SanityReport(BaseModel)`¶

The 7-axis component-design sanity check result.

Field	Type	Default
`component`	`str`	required
`axes`	`dict[str, dict[str, str]]`	Field(default_factory=dict)
`overall`	`str`	'not_assessed'
`summary`	`str`	''

`ComponentSanityChecker`¶

Runs the 7-axis component design sanity check on a named component.

Constructor:

Parameter	Type	Default
`auditors`	`AuditorMap \\| None`	None

Methods:

`check(component: str) -> SanityReport`¶

Run all five structural auditors and map them onto the 7 axes.

`AutofixInput(BaseModel)`¶

A single request to the AutofixBlock.

Field	Type	Default
`op`	`AutofixOp`	required
`component`	`str`	''
`goal`	`str`	''
`dry_run`	`bool`	True
`max_cycles`	`int`	Field(default=1, ge=1)
`params`	`dict[str, Any]`	Field(default_factory=dict)

`AutofixOutput(BaseModel)`¶

The result of one AutofixBlock operation.

Field	Type	Default
`ok`	`bool`	required
`completion_state`	`str`	''
`message`	`str`	''
`data`	`dict[str, Any]`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None

`AutofixState(BaseModel)`¶

Persisted, mutable state carried across AutofixBlock calls.

Field	Type	Default
`cycles_run`	`int`	0
`last_cycle_at`	`str`	''
`history`	`list[dict[str, Any]]`	Field(default_factory=list)

`AutofixTarget(BaseModel)`¶

A normalised "thing to work on" — the unit a cycle will act upon.

Field	Type	Default
`unit`	`str`	''
`kind`	`str`	'component'
`reason`	`str`	''
`priority_score`	`float`	0.0
`severity`	`str`	''
`source`	`str`	''
`detail`	`dict[str, Any]`	Field(default_factory=dict)

`AdapterResult(BaseModel)`¶

The uniform result of testing a change through one G6 surface.

Field	Type	Default
`surface`	`str`	required
`ok`	`bool`	required
`passed`	`int`	0
`failed`	`int`	0
`checks`	`list[dict[str, Any]]`	Field(default_factory=list)
`completion_state`	`str`	''
`message`	`str`	''
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None

`TestRouter`¶

Route changed file paths to surface adapters and run them.

Constructor:

Parameter	Type	Default
`adapter_factories`	`dict[str, Callable[[], Any]] \\| None`	None

Methods:

`route(changed_paths: list[str]) -> list[str]`¶

Map changed_paths to the surface(s) that should verify them.

`run(changed_paths: list[str], component: str = '') -> list[AdapterResult]`¶

Route changed_paths and run the selected surface adapters.

Functions¶

`default_audit_root() -> Path`¶

Absolute path to the Codex audit directory.

`ingest_audit(audit_root: Path | str | None = None) -> AuditBacklog`¶

Parse the Codex audit into a structured :class:AuditBacklog.

`enrich_finding(finding: AuditFinding, audit_root: Path | str | None = None) -> AuditFinding`¶

Return a copy of finding enriched from its per-unit audit report.

`analyze_db(db_path: str, expected_schema: str | None = None) -> DbRepairPlan`¶

Convenience wrapper around :meth:VibeDbRepairer.analyze.

`interpret_goal(goal_text: str) -> AutofixTarget`¶

Convenience: interpret goal_text with a freshly built interpreter.

`select_next_steps(audit_root: Path | str | None = None, limit: int = 10) -> list[AutofixTarget]`¶

Ingest the Codex audit and return the highest-yield next steps.

`route_and_run(changed_paths: list[str], component: str = '') -> list[AdapterResult]`¶

Convenience: route changed_paths and run the real surface adapters.

MCP Tools¶

Operation	Source
`autofix_observe`	autofix_mcp
`autofix_audit`	autofix_mcp
`autofix_cycle`	autofix_mcp
`autofix_loop`	autofix_mcp
`autofix_report`	autofix_mcp
`autofix_sanity_check`	autofix_mcp
`autofix_db_repair`	autofix_mcp

Autofix¶

Overview¶

Operations¶

Completion States¶

Build Status¶

Source Files¶

Public API¶

AuditFinding(BaseModel)¶

AuditBacklog(BaseModel)¶

open_items() -> list[AuditFinding]¶

by_severity(severity: str) -> list[AuditFinding]¶

for_unit(unit: str) -> list[AuditFinding]¶

top(n: int) -> list[AuditFinding]¶

counts() -> dict[str, int]¶

to_markdown() -> str¶

AutofixBlock(AIBlock[AutofixInput, AutofixOutput, AutofixState])¶

infer(data: AutofixInput) -> Result[AutofixOutput]¶

to_dict() -> dict[str, Any]¶

from_dict(data: dict[str, Any]) -> 'AutofixBlock'¶

DbRepairPlan(BaseModel)¶

VibeDbRepairer¶

analyze(db_path: str, expected_schema: str | None = None) -> DbRepairPlan¶

EngineCycleResult(BaseModel)¶

AutofixEngine¶

from_repo(repo_root: str | Path | None = None) -> 'AutofixEngine'¶

run_cycle(target: AutofixTarget | None = None, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, exclude_units: Collection[str] | None = None, scope_contract: dict[str, Any] | None = None) -> EngineCycleResult¶

run_loop(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False) -> list[EngineCycleResult]¶

run_loop_with_scorecard(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, window: str = '7d', release_report: dict[str, Any] | None = None, prior_scorecard: Any = None) -> DogfoodLoopReport¶

verify_surfaces(changed_paths: list[str], component: str = '') -> list[Any]¶

GoalInterpreter¶

interpret(goal_text: str, backlog: 'AuditBacklog | None' = None) -> AutofixTarget¶

decompose(goal_text: str)¶

AutofixWorkspaceMemory¶

exists() -> bool¶

path(name: str) -> Path¶

ensure() -> list[str]¶

read(name: str) -> str¶

write(name: str, content: str) -> None¶

append(name: str, entry: str) -> None¶

NextStepSelector¶

select(backlog: AuditBacklog, limit: int = 10, store: ReliabilityStore | None = None, exclude_units: Collection[str] | None = None) -> list[AutofixTarget]¶

ReadinessReport(BaseModel)¶

ProductionReadinessReporter¶

build() -> ReadinessReport¶

SanityReport(BaseModel)¶

ComponentSanityChecker¶

check(component: str) -> SanityReport¶

AutofixInput(BaseModel)¶

AutofixOutput(BaseModel)¶

AutofixState(BaseModel)¶

AutofixTarget(BaseModel)¶

AdapterResult(BaseModel)¶

TestRouter¶

route(changed_paths: list[str]) -> list[str]¶

run(changed_paths: list[str], component: str = '') -> list[AdapterResult]¶

Functions¶

default_audit_root() -> Path¶

ingest_audit(audit_root: Path | str | None = None) -> AuditBacklog¶

enrich_finding(finding: AuditFinding, audit_root: Path | str | None = None) -> AuditFinding¶

analyze_db(db_path: str, expected_schema: str | None = None) -> DbRepairPlan¶

interpret_goal(goal_text: str) -> AutofixTarget¶

select_next_steps(audit_root: Path | str | None = None, limit: int = 10) -> list[AutofixTarget]¶

route_and_run(changed_paths: list[str], component: str = '') -> list[AdapterResult]¶

MCP Tools¶

`AuditFinding(BaseModel)`¶

`AuditBacklog(BaseModel)`¶

`open_items() -> list[AuditFinding]`¶

`by_severity(severity: str) -> list[AuditFinding]`¶

`for_unit(unit: str) -> list[AuditFinding]`¶

`top(n: int) -> list[AuditFinding]`¶

`counts() -> dict[str, int]`¶

`to_markdown() -> str`¶

`AutofixBlock(AIBlock[AutofixInput, AutofixOutput, AutofixState])`¶

`infer(data: AutofixInput) -> Result[AutofixOutput]`¶

`to_dict() -> dict[str, Any]`¶

`from_dict(data: dict[str, Any]) -> 'AutofixBlock'`¶

`DbRepairPlan(BaseModel)`¶

`VibeDbRepairer`¶

`analyze(db_path: str, expected_schema: str | None = None) -> DbRepairPlan`¶

`EngineCycleResult(BaseModel)`¶

`AutofixEngine`¶

`from_repo(repo_root: str | Path | None = None) -> 'AutofixEngine'`¶

`run_cycle(target: AutofixTarget | None = None, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, exclude_units: Collection[str] | None = None, scope_contract: dict[str, Any] | None = None) -> EngineCycleResult`¶

`run_loop(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False) -> list[EngineCycleResult]`¶

`run_loop_with_scorecard(max_cycles: int = 1, dry_run: bool = True, reflect: bool = True, verify_surfaces: bool = False, window: str = '7d', release_report: dict[str, Any] | None = None, prior_scorecard: Any = None) -> DogfoodLoopReport`¶

`verify_surfaces(changed_paths: list[str], component: str = '') -> list[Any]`¶

`GoalInterpreter`¶

`interpret(goal_text: str, backlog: 'AuditBacklog | None' = None) -> AutofixTarget`¶

`decompose(goal_text: str)`¶

`AutofixWorkspaceMemory`¶

`exists() -> bool`¶

`path(name: str) -> Path`¶

`ensure() -> list[str]`¶

`read(name: str) -> str`¶

`write(name: str, content: str) -> None`¶

`append(name: str, entry: str) -> None`¶

`NextStepSelector`¶

`select(backlog: AuditBacklog, limit: int = 10, store: ReliabilityStore | None = None, exclude_units: Collection[str] | None = None) -> list[AutofixTarget]`¶

`ReadinessReport(BaseModel)`¶

`ProductionReadinessReporter`¶

`build() -> ReadinessReport`¶

`SanityReport(BaseModel)`¶

`ComponentSanityChecker`¶

`check(component: str) -> SanityReport`¶

`AutofixInput(BaseModel)`¶

`AutofixOutput(BaseModel)`¶

`AutofixState(BaseModel)`¶

`AutofixTarget(BaseModel)`¶

`AdapterResult(BaseModel)`¶

`TestRouter`¶

`route(changed_paths: list[str]) -> list[str]`¶

`run(changed_paths: list[str], component: str = '') -> list[AdapterResult]`¶

`default_audit_root() -> Path`¶

`ingest_audit(audit_root: Path | str | None = None) -> AuditBacklog`¶

`enrich_finding(finding: AuditFinding, audit_root: Path | str | None = None) -> AuditFinding`¶

`analyze_db(db_path: str, expected_schema: str | None = None) -> DbRepairPlan`¶

`interpret_goal(goal_text: str) -> AutofixTarget`¶

`select_next_steps(audit_root: Path | str | None = None, limit: int = 10) -> list[AutofixTarget]`¶

`route_and_run(changed_paths: list[str], component: str = '') -> list[AdapterResult]`¶