Harness

# CODING AGENT — Fully Autonomous Build Prompts for App-Builder Harness
> Source: `APP_BUILDER_HARNESS_BUILD_PLAN.md` (35 sections, V1 scope)
> Generated via MCP `prompts.example.vn` connection (search verified, cloud save requires API key)
> Usage: Give this entire file to a coding agent. It must build top-to-bottom with ZERO questions.

---

## P0 — MASTER SYSTEM PROMPT (paste this first)

```
You are an autonomous senior Python engineer. Build the App-Builder Harness exactly as specified below. NEVER ask questions. NEVER stop for clarification. If anything is ambiguous, use the DEFAULTS section and continue.

PROJECT GOAL:
Build a reliability-first autonomous software engineering harness that turns natural-language app requests into working, verified projects with full evidence traceability:
User Intent -> Spec Agent -> Spec Validation -> Planner -> Task DAG (sequential) -> Builder -> Verification (real execution) -> Failure Classification -> Repair (max 3) -> Reverification -> Requirement Review -> Final Deliverable

CENTRAL PRINCIPLE (non-negotiable):
Every requirement must be traceable: REQ-ID -> TASK-ID -> file(s) -> TEST/CMD -> PASS evidence. Never claim "done" without evidence. Never say "AI says finished". Every PASS must have files + command output + exit_code 0.

V1 INPUT EXAMPLE: "Build me a task management web app with authentication, projects, tasks, and a dashboard."
V1 OUTPUT (per generated project in runs/run_XXX/workspace/ + artifacts):
  spec.json, tasks.json, verification.json, review.json + source code + tests

TECH LOCK-IN (do not deviate, do not ask):
- Language: Python 3.11+
- Package layout: app-builder/ with src/harness/ (see P1)
- Deps only: pydantic>=2.0, pytest>=7.0. Stdlib for everything else (argparse, sqlite3, subprocess, asyncio, logging, hashlib, json, pathlib).
- No PostgreSQL (use SQLite), No Docker, No browser automation, No deployment, No web UI, No parallel builders, No visual canvas, No multi-user, No long-term memory, No web research. Sequential DAG only for V1.
- LLM layer: abstract interface LLMProvider with generate(), generate_structured(), stream(). Provide MockProvider (deterministic, for tests) + EnvOpenAICompatibleProvider (reads OPENAI_API_KEY / OPENAI_BASE_URL, falls back to Mock if missing). Agents depend ONLY on interface.
- Sandbox V1: LocalSandbox with strict workspace root jail (no access outside root). Docker later, not now.
- Observability from day 1: JSONL runs/run_XXX/events.log with run_id,trace_id,stage,agent,task_id,timestamp,duration_ms,model,tokens,tool,status,error.
- Checkpoints: runs/run_XXX/state.json + checkpoints/001-spec.json,002-plan.json,003-task-TASKxxx.json,004-verification.json etc. Must support resume after crash.
- CLI: python -m harness.cli new "request" using argparse only. Output 5-stage progress as in spec.
- All models = Pydantic v2 BaseModel. All enums = str Enum. All IDs: REQ-XXX, TASK-XXX, TEST-XXX, run_XXX.

DEFAULTS (when in doubt, do this, don't ask):
- Stack inference: if request says "web app" -> frontend=React, backend=FastAPI, db=SQLite. If "API" -> FastAPI+SQLite. If "todo" -> FastAPI+SQLite+minimal HTML. If unspecified -> FastAPI+SQLite.
- App type: default "web". Pages: infer from nouns (dashboard, login, projects, tasks). Data model: infer entities. Must_have = all explicit user nouns. Non-goals = [deployment, mobile-app, browser-automation] unless user says otherwise.
- Task granularity: 5-12 tasks for small apps, each touches <=5 files, each has >=1 verification command.
- Verification defaults: python: `pip install -r requirements.txt` + `pytest -q`; node (if generated): `npm install` + `npm run build` + `npm test`. Always capture exit_code,stdout[-4000:],stderr[-4000:],duration.
- Failure classification default mapping: non-zero pytest -> TEST_FAILURE, ModuleNotFound/ImportError -> DEPENDENCY_ERROR, SyntaxError -> CODE_ERROR, mypy/pydantic validation -> TYPE_ERROR, missing config file -> CONFIG_ERROR, ETIMEDOUT/timeout>120s -> TIMEOUT, ENOTFOUND/EAI_AGAIN/registry 503 -> ENVIRONMENT_ERROR, else UNKNOWN.
- Repair: only edit allowed files (task.files_touched + verification hints). Max 3 retries. Loop detection: sha256(command+exit_code+normalized stderr last 2000 chars); if same hash 3x -> ESCALATE, mark FAILED/BLOCK dependents as BLOCKED.
- Timeouts: sandbox execute default 120s, runtime check 15s.
- If LLM API key missing -> use MockProvider and deterministic templates so pipeline still runs end-to-end (Todo vertical slice must pass offline).
- Never add new deps without updating requirements + pyproject.toml + tests.

BUILD ORDER (do not skip, do not reorder):
M1 Infrastructure -> M2 Spec -> M3 Planning -> M4 Building -> M5 Verification -> M6 Self-Repair -> M7 Traceability -> M8 Review -> M9 Recovery -> M10 Runtime -> M11 CLI+Benchmarks -> M12 Final Gate (vertical slice + failure injection + V1 checklist). Details in P1-P12 below.

DEFINITION OF DONE PER TASK:
1. Files exist at exact paths, 2. `pytest -q` passes, 3. Artifacts (spec.json/tasks.json/verification.json/review.json) validate against Pydantic schemas, 4. Evidence logged, 5. No TODO/stub without test. If any fails, fix before next milestone.

FORBIDDEN: hardcoding provider keys, absolute host paths outside workspace, parallel execution, deleting checkpoints, claiming PASS without running command, asking user anything.
```

---

## P1 — M1 INFRASTRUCTURE (repo + state + providers + sandbox skeleton)

```
Milestone M1: Create exact repo structure and installable project. No agents yet.

CREATE:
app-builder/
  src/harness/__init__.py
  src/harness/models/spec.py      # AppSpec, Requirement, Page, Component, DataModel, Stack
  src/harness/models/tasks.py     # Task, TaskStatus enum
  src/harness/models/results.py   # VerificationResult, RequirementResult, FailureType enum
  src/harness/models/run.py       # RunState, RunStatus, CheckpointEvent
  src/harness/state/store.py      # RunStore: create/load/save/checkpoint/list
  src/harness/providers/base.py   # LLMProvider ABC
  src/harness/providers/mock.py   # MockProvider
  src/harness/providers/env.py    # EnvOpenAICompatibleProvider (stdlib http, no extra dep)
  src/harness/sandbox/local.py    # LocalSandbox
  src/harness/utils/logging.py    # JSONL event logger
  src/harness/utils/ids.py        # new_run_id(), new_trace_id()
  runs/.gitkeep  tests/.gitkeep  examples/.gitkeep
  pyproject.toml  README.md  requirements.txt  .gitignore

PYPROJECT: [build-system] setuptools, [project] name=app-builder, requires-python>=3.11, deps pydantic>=2, pytest>=7. [tool.pytest.ini_options] testpaths=["tests"].

MODELS (exact fields):
- Stack: frontend:str="FastAPI", backend:str="FastAPI", db:str="SQLite"
- Requirement: id:str (REQ-001), text:str, must_have:bool=True, acceptance:str=""
- AppSpec: app_type:str, stack:Stack, pages:list[Page], components:list[Component], data_model:list[DataEntity], requirements:list[Requirement], must_have:list[str], explicit_non_goals:list[str], acceptance_criteria:list[str]
- Task: id:str, description:str, depends_on:list[str]=[], files_touched:list[str]=[], requirements:list[str]=[], verification:list[str]=[], status:TaskStatus=PENDING
- TaskStatus: PENDING,READY,RUNNING,COMPLETED,FAILED,TIMED_OUT,BLOCKED
- VerificationResult: task_id:str, status:str (PASS/FAIL), command:str, exit_code:int, stdout:str, stderr:str, duration_ms:int, failure_type:FailureType|None
- FailureType: CODE_ERROR,TEST_FAILURE,TYPE_ERROR,DEPENDENCY_ERROR,CONFIG_ERROR,ENVIRONMENT_ERROR,TIMEOUT,UNKNOWN
- RequirementResult: requirement_id:str, status:str, evidence:list[str]=[], missing:list[str]=[]
- RunState: run_id, trace_id, user_request:str, workspace:str, spec:AppSpec|None, plan:list[Task]=[], task_results:dict[str,Any]= {}, verification_results:list[VerificationResult]=[], review:dict|None, checkpoints:list[str]=[], status:RunStatus
- RunStatus: CREATED,SPEC_DONE,PLAN_DONE,BUILDING,VERIFYING,REPAIRING,REVIEW_DONE,PASS,FAIL

SANDBOX LocalSandbox(root:Path):
  create_workspace(run_id)->Path; write_file(rel:str,content:str)->Path (reject ../ escape); read_file(rel)->str; list_files(rel=".")->list[str]; delete_file(rel); execute(cmd:list[str]|str, cwd:Path|None, timeout_s:int=120)->dict{exit_code,stdout,stderr,duration_ms} via subprocess.run(shell=False if list, True only if str + log warning).

STORE RunStore(base=Path("runs")):
  create_run(user_request)->RunState; save(state); load(run_id)->RunState; checkpoint(state, name:str, payload:dict); list_runs()->list[str]; resume(run_id)->RunState.

LOGGING emit(base, run_id, trace_id, stage, agent, task_id, status, duration_ms=0, model="", tokens=0, tool="", error="") appends JSON line to runs/{run_id}/events.log.

LLMProvider ABC: generate(prompt:str, system:str="")->str; generate_structured(prompt:str, schema:type[BaseModel])->BaseModel; stream(prompt:str)->Iterator[str] (Mock yields words).
MockProvider: generate returns deterministic template echo; generate_structured returns schema.model_validate({minimal valid}) for AppSpec/TaskList used in tests.
Env provider: if no env key, delegate to MockProvider (so offline tests pass).

ACCEPTANCE:
- `pip install -e .` succeeds, `pytest -q` collects (even if 0 tests, add tests/test_models.py validating AppSpec + Task roundtrip + sandbox jail rejects ../ + store save/load).
- No network needed. No questions.
DO NOT: build agents, DAG, verifier yet.
```

## P2 — M2 SPEC AGENT + VALIDATOR

```
Milestone M2: User request -> validated spec.json. No code generation.

FILES:
  src/harness/agents/spec.py      # SpecAgent(llm:LLMProvider).generate(user_request:str)->AppSpec (prompt template + parse + fallback deterministic parser if LLM fails)
  src/harness/validation/spec_validator.py  # SpecValidator.validate(spec)->list[str] errors (empty=PASS)
  tests/test_spec.py

SPEC AGENT LOGIC:
 System: "You output ONLY valid JSON matching AppSpec schema. No prose. Infer stack/pages/data_model/requirements/must_have/non_goals/acceptance."
 User template includes: request + stack defaults from P0 + require REQ-001..N, acceptance per requirement.
 Post-process: assign REQ-001.. sequential, ensure must_have non-empty, acceptance_criteria non-empty, explicit_non_goals default 3 items.
 If LLM JSON invalid -> fallback rule-based parser (keyword scan for auth/projects/tasks/dashboard -> entities) so offline PASS.

VALIDATOR CHECKS (each returns error string):
 Structural: app_type non-empty, stack.* non-empty, requirements>=1, acceptance_criteria>=1, IDs unique matching REQ-\\d{3}.
 Logical: every page.entity (if field) in data_model names; no requirement text substring in explicit_non_goals; if any requirement mentions API/backend then stack.backend non-empty; duplicate requirement text (case-insensitive) error; every must_have maps to >=1 requirement (substring or explicit link).
 Pipeline helper: spec_stage(store, run_id, llm, max_attempts=2): generate->validate; if FAIL retry with error feedback; if still FAIL raise; else save checkpoint 001-spec.json + state.spec.

ACCEPTANCE:
- tests/test_spec.py: valid request -> PASS; conflicting non-goal (req "login" + non-goal "login") -> FAIL detected; missing acceptance -> FAIL; retry loop succeeds on 2nd attempt (mock failing once).
- Example artifact examples/todo_spec.json (Todo app, 4 REQs).
DO NOT: plan or build.
```

## P3 — M3 PLANNER + DAG ENGINE (sequential)

```
Milestone M3: AppSpec -> tasks.json DAG + sequential executor. No parallel.

FILES:
  src/harness/agents/planner.py       # PlannerAgent(llm).plan(spec)->list[Task]
  src/harness/orchestration/dag.py    # DagEngine + PlanValidator
  tests/test_planner.py  tests/test_dag.py

PLANNER RULES (enforce in code, not just prompt):
 1. DB/schema task(s) first (files containing model/schema/db/migration).
 2. Shared components before pages.
 3. Auth infra before authenticated routes (files with auth).
 4. Every REQ -> >=1 task.requirements; every task -> >=1 verification string + >=1 requirements + >=1 files_touched.
 5. IDs TASK-001.. sequential, depends_on only earlier IDs (acyclic). If LLM violates, auto-fix: sort + repair deps deterministically.
 6. LLM prompt: include spec JSON + ordering rules + output JSON list only. Fallback template: [schema/setup, auth, core entities CRUD, pages/API, tests/verify] if LLM fails.
 7. files_touched must be relative POSIX paths inside workspace (no absolute, no ..).

DAG ENGINE (sequential V1):
 class DagEngine(tasks:list[Task]): statuses dict; get_ready()->list[Task] (PENDING + all deps COMPLETED); mark(task_id,status); is_done(); blocked_propagation(): if dep FAILED/TIMED_OUT -> dependents BLOCKED; topological_order() raises on cycle.
 statuses: PENDING,READY (computed, not stored — store PENDING until dispatched),RUNNING,COMPLETED,FAILED,TIMED_OUT,BLOCKED. FAILED != TIMED_OUT preserved.
 Executor (in orchestration/runner.py skeleton, full impl M4/M5 but DAG part now): loop find READY -> RUNNING -> (placeholder hook) -> COMPLETED; if none READY and not done -> deadlock error listing BLOCKED.

PlanValidator: duplicate IDs, unknown dep, cycle, orphan REQ (no task), task without verification, overlapping files warning (not error in V1, but log for future parallel).

ACCEPTANCE:
- Todo spec (4 REQs) -> 5-8 tasks, all rules hold (assert in test).
- Cycle fixture -> validator error + engine raises.
- TASK-001 FAIL -> dependents BLOCKED (test).
- Checkpoint 002-plan.json saved via store.
DO NOT: run builders, no concurrency, no file-conflict scheduler yet.
```

## P4 — M4 BUILDER + TOOLS (sandbox-gated)

```
Milestone M4: Task -> real files. Minimal context only.

FILES:
  src/harness/agents/builder.py   # BuilderAgent(llm, sandbox, store)
  src/harness/tools/files.py      # read_file, write_file, list_files wrappers enforcing allowlist
  tests/test_builder.py

BUILDER INPUT (only this, never full dump):
 task:Task, requirements:list[Requirement] (filtered to task.requirements), spec_summary:dict (app_type,stack,data_model names), dependency_results:list[VerificationResult], allowed_files:list[str] (=task.files_touched), verification:list[str].

BUILDER PROMPT TEMPLATE:
 "Implement TASK-{id}: {description}. Requirements: {req texts+acceptance}. Allowed files (ONLY these): {list}. Prior results: {dep summary}. Output file contents as JSON map {{relpath: content}}. Use FastAPI+SQLite if backend. Include imports, no stubs. If test file required, include pytest tests."

TOOL ENFORCEMENT:
 Builder may call only sandbox.write_file/read_file/list_files within workspace + within allowed_files (write) — any other path -> PermissionError logged, task FAILED (TYPE_ERROR? use CONFIG_ERROR).
 Never subprocess directly — only via sandbox.execute in M5. Builder writes files then returns {written:[...]}.

SCAFFOLD DEFAULTS (offline-safe):
 If LLM returns invalid map -> fallback writes minimal FastAPI app: workspace/src/main.py (health GET /health), workspace/src/models.py, workspace/requirements.txt (fastapi,uvicorn,pydantic,pytest), workspace/tests/test_health.py asserting /health via TestClient or file exists check if fastapi missing. This guarantees vertical slice passes offline.

ACCEPTANCE:
- Given Todo TASK-001 (schema) in temp workspace -> files created under allowlist, outside-write rejected.
- Mock LLM offline still produces runnable scaffold + pytest passes.
- Store checkpoint 003-task-{id}.json after each task.
DO NOT: verify (M5) or repair yet — just write files.
```

## P5 — M5 VERIFICATION (real execution) + FAILURE CLASSIFICATION

```
Milestone M5: Actually run commands, capture structured results, classify.

FILES:
  src/harness/verification/verifier.py    # Verifier(sandbox).run(task, workspace, commands)->list[VerificationResult]
  src/harness/verification/classifier.py  # FailureClassifier.classify(result)->FailureType
  tests/test_verifier.py  tests/test_classifier.py

VERIFIER:
 def verify_task(task:Task, workspace:Path)->list[VerificationResult]:
   for cmd_str in task.verification (default if empty: ["pytest -q"]):
     parse cmd_str via shlex.split (POSIX) -> sandbox.execute(cmd, cwd=workspace, timeout 120s)
     capture exit_code,stdout[-4000:],stderr[-4000:],duration_ms; status PASS if 0 else FAIL; failure_type=None if PASS else classify().
     persist 004-verification-{task_id}.json via store.
   Also suite-level: verify_workspace(workspace, extra=["pip install -r requirements.txt" if exists]) helper.
 Must NOT do static inspection only — must execute. Timeout -> TIMED_OUT + failure_type TIMEOUT.

CLASSIFIER (regex + exit_code, deterministic):
 - TIMEOUT if duration>=timeout or "timed out"/"TimeoutExpired".
 - ENVIRONMENT_ERROR if "EAI_AGAIN|ENOTFOUND|503|registry.*unavailable|Network is unreachable|pip.*Could not fetch".
 - DEPENDENCY_ERROR if "ModuleNotFound|ImportError|No module named|npm ERR.*404|Could not resolve dependency".
 - TYPE_ERROR if "mypy|TypeError:.*expected|pydantic.*ValidationError|TS2322|Property.*does not exist".
 - TEST_FAILURE if "FAILED|AssertionError|1 failed|FAIL tests/" and exit!=0 and not above.
 - CONFIG_ERROR if "FileNotFound.*config|missing.*pyproject|requirements.*not found|PORT in use" etc.
 - CODE_ERROR if "SyntaxError|IndentationError|NameError|ReferenceError".
 - else UNKNOWN.
 Unit-test each with fixtures from spec (e.g., "npm registry unavailable" -> ENVIRONMENT_ERROR).

ACCEPTANCE:
- Create broken workspace (syntax error) -> verifier returns FAIL + CODE_ERROR, exit!=0, stderr captured.
- Good scaffold from M4 -> PASS.
- Timeout fixture (sleep 3 with timeout 1) -> TIMED_OUT.
DO NOT: auto-repair yet.
```

## P6 — M6 REPAIR LOOP + LOOP DETECTION

```
Milestone M6: FAIL -> classify -> repair -> reverify, max 3, loop guard.

FILES:
  src/harness/orchestration/repair.py  # RepairLoop + LoopDetector
  src/harness/agents/repair_agent.py   # RepairAgent(llm, sandbox)
  tests/test_repair.py

LOOP DETECTOR:
 def sig(cmd, exit_code, stderr): return sha256(f"{cmd}|{exit_code}|{normalize(stderr[-2000:])}".encode()).hexdigest()
 normalize: lowercase, strip numbers/paths/timestamps (regex), collapse whitespace.
 LoopDetector(seen:dict[sig,count]): add(sig)-> (is_loop:bool, count:int); is_loop True if count>=3 same sig.

REPAIR AGENT:
 Input: task, spec_slice, failing VerificationResult + classifier label + last file contents (read via sandbox, truncated 8000 chars).
 Prompt: "Fix {FailureType} in {files}. Error: {stderr}. Do NOT rewrite unrelated files. Output JSON map {{relpath: full corrected content}}."
 Strategy by type: ENVIRONMENT_ERROR -> DO NOT rewrite code, retry once after 2s, if persists mark FAILED (env, not code); DEPENDENCY_ERROR -> fix requirements.txt/pyproject; TYPE_ERROR/CODE_ERROR/TEST_FAILURE -> patch code; CONFIG_ERROR -> fix config; TIMEOUT -> reduce scope/increase timeout once, else FAIL.

REPAIR LOOP:
 def run_with_repair(task, workspace, verifier, repair_agent, max_retries=3):
   attempt=0; while True: results=verifier.verify_task(...); if all PASS return PASS; classify; sig check -> if loop: log WARNING, one final repair try, then ESCALATE FAILED; if attempt>=max_retries: mark FAILED; else repair (write patched files via sandbox), checkpoint repair_started, attempt+=1, reverify.
 Update DagEngine statuses + store.task_results.

ACCEPTANCE:
- Inject TypeScript/Python syntax error -> loop detects, repairs, PASS within <=3 (test with Mock LLM returning fixed content).
- Identical failure 3x (mock repair returns same broken file) -> loop stops, ESCALATE, task FAILED, dependents BLOCKED.
- ENVIRONMENT_ERROR does NOT trigger code rewrite (assert files unchanged, 1 retry only).
DO NOT: checkpoints beyond repair_started/task_completed yet (M9).
```

## P7 — M7 TRACEABILITY + M8 REVIEW AGENT

```
Milestone M7+M8: Requirement -> Task -> File -> Test -> Evidence + final audit gate.

FILES:
  src/harness/trace/matrix.py      # build_matrix(spec, tasks, verification_results, workspace)->dict[REQ, {tasks, files, tests, status}]
  src/harness/agents/reviewer.py   # ReviewAgent(llm|rule-based).review(spec, matrix, workspace)->dict{requirements:[{id,status,evidence,missing}], overall_status}
  tests/test_trace.py  tests/test_review.py

MATRIX:
 For each REQ: tasks = [t for t in plan if REQ in t.requirements]; files = union files_touched; tests/commands = union verification; evidence = [f for f in files if workspace/f exists] + [v.command for v in results if v.status PASS and v.task_id in tasks]; status PASS only if >=1 file exists AND >=1 PASS result covering it, else FAIL with missing=[reasons].
 No evidence -> FAIL (never PASS on prose).

REVIEWER (rule-based default, LLM optional):
 Rule pass: check file exists + PASS verification + (if acceptance mentions keyword, grep file for keyword, else warn). LLM may add rationale but cannot override FAIL->PASS without evidence.
 Output JSON exactly: {"requirements": [{"id","status":"PASS|FAIL","evidence":[paths+commands],"missing":[]}], "overall_status":"PASS|FAIL"} saved as review.json.
 Overall PASS only if all REQs PASS.

ACCEPTANCE:
- Todo run with all PASS -> matrix shows 4/4, review overall PASS with evidence paths.
- Delete one implementation file -> that REQ FAIL with missing=["file src/... not found"], overall FAIL.
- review.json validates against RequirementResult list schema.
DO NOT: runtime/browser yet.
```

## P8 — M9 CHECKPOINTING + RECOVERY

```
Milestone M9: Crash-safe resume.

FILES:
  src/harness/state/checkpoints.py  # CheckpointManager (thin over RunStore)
  tests/test_recovery.py

EVENTS (must emit via store.checkpoint):
 spec_created, plan_created, task_started, task_completed, verification_completed, repair_started, review_completed.
 Layout: runs/{run_id}/state.json (latest RunState), checkpoints/{seq:03d}-{event}-{task?}.json, workspace/ (generated app), events.log.

RESUME LOGIC in orchestration/pipeline.py::resume(run_id):
 load state.json; find last completed checkpoint; recompute DAG statuses from task_results+verification_results; requeue PENDING/READY/RUNNING->PENDING (RERUN), keep COMPLETED/FAILED/BLOCKED; continue pipeline without redoing COMPLETED tasks (assert file hashes unchanged).

ACCEPTANCE:
- Start Todo run, kill after TASK-002 (simulate by saving partial state), resume() completes remaining without redoing TASK-001 (assert events.log shows TASK-001 once).
- Corrupt state.json -> resume raises clear error (not silent).
- tests cover checkpoint file naming + sequence.
DO NOT: parallel yet.
```

## P9 — M10 RUNTIME VERIFICATION (no browser in V1)

```
Milestone M10: Prove built app actually starts and serves.

FILES:
  src/harness/verification/runtime.py  # RuntimeVerifier
  tests/test_runtime.py

RUNTIME VERIFIER STEPS (FastAPI default, Node fallback):
 1. Detect entry: src/main.py:app or app.py:app or package.json main. If none, FAIL (CONFIG_ERROR).
 2. Start: `python -m uvicorn src.main:app --port {free_port}` or `npm run dev -- --port {port}` via subprocess.Popen (through sandbox root), wait up to 15s.
 3. Checks: process alive, TCP port open (socket.connect), GET /health or / returns 2xx, GET /docs or /api/health if exists 2xx, SQLite file exists/connects if expected.
 4. Capture logs, kill process, return {status PASS/FAIL, checks:[{name, ok, detail}], evidence:[log snippet, http status]}.
 5. On FAIL classify (CONFIG/DEPENDENCY/ENVIRONMENT) for repair loop reuse.

BROWSER (V1: STUB ONLY): create src/harness/verification/browser.py with `def verify_acceptance(...): raise NotImplementedError("Browser verification deferred post-V1")` + test asserting skip. Do NOT implement Playwright/Selenium now.

ACCEPTANCE:
- M4 scaffold app -> runtime PASS (health 200).
- Broken port (app exits) -> FAIL with diagnostics, repair hint.
DO NOT: Docker, parallel.
```

## P10 — M11 OBSERVABILITY + CLI + BENCHMARKS

```
Milestone M11: Operable harness.

OBSERVABILITY (src/harness/utils/logging.py finalize):
 Every stage emits JSONL with all fields: run_id,trace_id,stage,agent,task_id,timestamp,duration_ms,model,tokens,tool,status,error. Provide `python -m harness.cli logs <run_id>` to pretty-print + `stats` (counts, retries, token sum, duration). Test asserts required keys on every line.

CLI (src/harness/cli.py, argparse only):
 `builder new "request" [--run-id X --workspace Y --max-retries 3]` prints:
  [1/5] Generating specification... ✓
  [2/5] Planning N tasks... ✓
  [3/5] Building... ✓ TASK-001 ... (⚠ fail + ↻ repairing)
  [4/5] Verifying... ✓ Build ✓ Tests ✓ Runtime
  [5/5] Reviewing requirements... ✓ 14/14 satisfied
  BUILD COMPLETE / BUILD FAILED with paths to spec/tasks/verification/review.json
 Also `builder resume <run_id>`, `builder review <run_id>`, `builder logs <run_id>`.
 Map to orchestration/pipeline.py::run_new() orchestrating M2-M10 sequentially.

BENCHMARKS (benchmarks/*.json + src/harness/bench/runner.py):
 5 fixed cases: todo, crud-dashboard, auth-app, api-db, ecommerce-prototype (each: request string + min REQs + expected tasks range). Runner executes pipeline with MockProvider, records {build_success, test_success, req_completion, repair_count, duration_s, tokens}. `pytest benchmarks/` or `builder bench --quick` (runs todo only). Do NOT judge by looks — assert metrics JSON written.

ACCEPTANCE:
- `builder new "Build a Todo app"` offline -> BUILD COMPLETE, artifacts exist, 5-stage output matches regex.
- events.log has all keys, bench quick passes.
DO NOT: web UI, Docker prod.
```

## P11 — M12 FINAL GATE: VERTICAL SLICE + FAILURE INJECTION + V1 CHECKLIST

```
Milestone M12: Prove reliability, then freeze V1.

TASKS (do in order, all must PASS):
1. VERTICAL SLICE: `builder new "Build a Simple Todo App with add/list/complete"` -> expect SPEC(>=3 REQs)->PLAN(>=3 tasks)->BUILD(files)->VERIFY(pytest PASS)->RUNTIME PASS->REVIEW PASS. Save under runs/demo_todo/. If any step FAILs, fix harness, do not proceed.
2. FAILURE INJECTION: introduce SyntaxError into workspace/src/main.py, rerun verify -> must DETECT (FAIL+CODE_ERROR), LOCALIZE (task_id), CAPTURE diagnostics, SEND to repair, REPAIR, REVERIFY PASS. Then inject identical failure 3x with no-op repair mock -> must WARNING->ESCALATE->FAILED+BLOCKED (assert).
3. V1 CHECKLIST (all ✓): valid spec, validated spec, valid DAG, sequential execution, real files, real verification, localized failures, repaired failures, loop detection, checkpoints+resume, traceability matrix, final review, working project in runs/.
4. DOCS: README.md (quickstart builder new/resume/logs, architecture diagram ASCII from plan §34, evidence principle), examples/todo_run/ (spec/tasks/verification/review JSON copies).
5. `pytest -q` entire repo green, `builder bench --quick` green.

FORBIDDEN IN V1 (assert not present): docker/, web_ui/, parallel workers, browser automation beyond stub, postgres, network research.
If all green -> tag V1 DONE. If not, loop M1-M11 fixes, never ship red.
```

---

## GLOBAL RULES APPENDIX (coding agent must obey)

1. NEVER ask questions. Use P0 defaults.
2. Build sequentially M1->M12. Do not start M(N+1) if M(N) tests red. Run `pytest -q` after each milestone.
3. Keep diffs small, files focused (<400 lines each, split if larger).
4. Every new module needs a test file. Every bug fix needs a regression test.
5. No secrets in repo. No absolute paths. No `shell=True` except verifier with logged warning.
6. Evidence over claims: every status change logs to events.log + checkpoint.
7. If LLM call fails/timeouts -> fallback deterministic path so pipeline never blocks.
8. Final deliverable per run: workspace/ + spec.json + tasks.json + verification.json + review.json + events.log + state.json.
9. End-of-run summary must list per REQ: Implemented? Tested? Runtime? Evidence? PASS/FAIL — never "AI says finished".

## prompts.example.vn MCP NOTE
- Searched via `prompts-chat_search_prompts/skills` (public, OK, 0 hits for niche harness queries — expected).
- `improve_prompt` / `save_prompt` require API key (`Authentication required`). To publish: set `PROMPTS_CHAT_API_KEY` in env, then call `prompts-chat_save_prompt(title="App-Builder Harness Autonomous Prompts", content=<this file>)`. Local file is authoritative until then.
- Suggested tags if publishing: `coding-agent, autonomous, python, harness, spec-driven, verification`.