AGENTS.md@infrastructure/autoresearch git:20260708.fadfd64A

Immutable. This exact content is served forever at /api/v1/blob/8b241ff61ba45de8.

# AutoResearch Module - Agent Notes

## Purpose

`infrastructure/autoresearch` provides opt-in deterministic readiness checks.
Use it when a project wants AutoResearchClaw-inspired planning and validation
without autonomous research execution.

## Boundaries

- No network calls.
- No LLM calls.
- No generated-code execution.
- No autonomous self-approval loops.
- No AutoResearch CLI-style lifecycle hooks or git commit/revert ownership.
- Scripts remain thin; use `python -m infrastructure.autoresearch.cli` instead
  of adding root entry points.

## Public Interfaces

- `AutoResearchConfig`
- `BudgetPolicy`
- `ReviewGate`
- `BenchmarkTask`
- `EvidenceLink`
- `ResearchIdea`
- `ExperimentCandidate`
- `ResearchProgram`
- `RunLedger`
- `SecurityProfile`
- `AutoResearchStage`
- `ValidationPhase`
- `AutoResearchPlan`
- `AutoResearchIssue`
- `AutoResearchReport`
- `INTRINSIC_QUALITY_CHECKS` / `EXTRINSIC_QUALITY_CHECKS`
- `load_autoresearch_config(project_root)`
- `parse_metric_lines(output)`
- `metric_unit_from_name(name)`
- `mad_confidence(values, baseline, best)`
- `parse_string_sequence(value, *, default)`
- `build_autoresearch_plan(repo_root, project_name, projects_dir="projects")`
- `validate_autoresearch_plan(plan, project_root, *, phase="all")`
- `write_autoresearch_report(project_root, report)`

Implementation split: [`validation.py`](validation.py) orchestrates;
[`validation_checks.py`](validation_checks.py) holds per-check validators.
The frozen dataclasses (`AutoResearchConfig`, `BudgetPolicy`, `ReviewGate`,
`BenchmarkTask`, `EvidenceLink`, `ResearchIdea`, `ExperimentCandidate`,
`ResearchProgram`, `RunLedger`, `SecurityProfile`, `AutoResearchStage`,
`AutoResearchPlan`, `AutoResearchIssue`, `AutoResearchReport`) plus the
`DEFAULT_QUALITY_CHECKS` / `METHOD_QUALITY_CHECKS` / `KNOWN_QUALITY_CHECKS`
tuples live in [`models.py`](models.py); `build_autoresearch_plan(repo_root,
project_name, projects_dir="projects")` — which assembles a deterministic plan
from domain profile, experiment plan, and `pipeline.yaml` DAG — lives in
[`planner.py`](planner.py).

## Validation phases

`validate_autoresearch_plan(..., phase=...)`:

| Phase | Checks |
| --- | --- |
| `intrinsic` | `domain_profile`, `experiment_plan`, `pipeline_contracts`, `thin_orchestrators`, `ai_disclosure` |
| `extrinsic` | `evidence_registry`, `artifact_manifest`, `method_contracts`, `review_gates`, `benchmark_tasks`, `security_profile` |
| `all` | every configured check (default) |

Stage-gate and unknown quality-check validation always runs regardless of
phase.

## Validation Inputs

The module validates only file-backed deterministic surfaces:

- `autoresearch.yaml`
- `domain_profile.yaml`
- `experiment_plan.yaml`
- `pipeline.yaml`
- `output/reports/artifact_manifest.json`
- project evidence registry facts
- root and project script thin-orchestrator drift
- `output/data/idea_ledger.json`
- `output/data/run_ledger.json`
- `output/data/review_decisions.json`
- `output/data/benchmark_scores.json`
- configured disclosure text or `{{DISCLOSURE_TEXT}}` token in manuscript Markdown
- exact `METRIC name=value` command output only when a caller explicitly parses
  it with `parse_metric_lines`

## Configuration Rules

`stage_gates` are exact `pipeline.yaml` stage names, not gate labels.
Valid `quality_checks` are:

- `domain_profile`
- `experiment_plan`
- `pipeline_contracts`
- `evidence_registry`
- `artifact_manifest`
- `thin_orchestrators`
- `method_contracts`
- `review_gates`
- `benchmark_tasks`
- `ai_disclosure`
- `security_profile`

Strict mode promotes advisory readiness defects to errors. Configuration
defects such as unknown stage names or unknown checks are always errors.