APP-BUILDER HARNESS

Autonomous Coding Agent Build Specification — V1

Purpose: Give this entire specification to a coding agent.

The agent must implement the project sequentially from M1 through M12.

ZERO clarification questions. ZERO unverified completion claims.

0. OPERATING CONTRACT

You are an autonomous senior Python engineer.

Build the App-Builder Harness exactly according to this specification.

You MUST:

Work sequentially from M1 → M12.
Never ask the user for clarification.
Resolve ambiguity using the defaults defined here.
Run real tests and commands before declaring PASS.
Stop milestone progression whenever its acceptance tests are red.
Repair failures before proceeding.
Record evidence for every completed requirement.
Keep the implementation inside the V1 scope.
Never claim success based solely on LLM output.
Finish only when the complete V1 Final Gate passes.

1. PROJECT GOAL

Build a reliability-first autonomous software-engineering harness that transforms a natural-language application request into a working, tested, reviewed project.

Canonical pipeline:

User Request
    ↓
Spec Agent
    ↓
Spec Validation
    ↓
Planner
    ↓
Task DAG
    ↓
Sequential Builder
    ↓
Real Verification
    ↓
Failure Classification
    ↓
Repair Loop
    ↓
Reverification
    ↓
Traceability Matrix
    ↓
Requirement Review
    ↓
Runtime Verification
    ↓
Final Deliverable

Example input:

Build me a task management web app with authentication,
projects, tasks, and a dashboard.

2. CENTRAL INVARIANT — EVIDENCE OVER CLAIMS

Every requirement MUST be traceable through:

REQ-ID
  ↓
TASK-ID
  ↓
FILE(S)
  ↓
TEST / COMMAND
  ↓
EXECUTION RESULT
  ↓
PASS EVIDENCE

A requirement is not complete merely because:

an LLM generated code;
a file exists;
an agent says it is finished;
static inspection looks correct.

A PASS requires real evidence.

Minimum PASS evidence:

implementation file exists
+
verification command executed
+
exit_code == 0
+
result persisted

Never output:

AI says finished

as completion evidence.

3. V1 SCOPE LOCK

Harness runtime

Python 3.11+
Pydantic >= 2.0
pytest >= 7.0
Python standard library for infrastructure whenever possible

Allowed stdlib examples:

argparse
asyncio
hashlib
json
logging
pathlib
shlex
socket
sqlite3
subprocess
time
urllib
uuid

Harness architecture

Repository:

app-builder/
└── src/harness/

State storage:

SQLite / JSON files

Sandbox:

LocalSandbox

Execution model:

Sequential DAG only

LLM abstraction:

LLMProvider
├── MockProvider
└── EnvOpenAICompatibleProvider

4. STRICT V1 NON-GOALS

DO NOT implement:

PostgreSQL
Docker sandbox
production deployment
browser automation
Playwright
Selenium
visual canvas
web management UI
parallel builders
parallel DAG execution
file-conflict scheduler
multi-user support
long-term agent memory
internet research
distributed workers

A browser verification module may exist only as an explicit post-V1 stub.

5. DEPENDENCY BOUNDARY

The dependency restriction:

pydantic>=2
pytest>=7

applies to the App-Builder Harness itself.

Generated applications may contain their own:

requirements.txt
package.json

according to their inferred stack.

Do not silently add dependencies to the harness.

Whenever a new harness dependency is intentionally introduced, all of the following MUST be updated together:

pyproject.toml
requirements.txt
tests
documentation

6. OFFLINE BEHAVIOR

"No API key" MUST never block the pipeline.

If:

OPENAI_API_KEY

is unavailable:

EnvOpenAICompatibleProvider
        ↓
MockProvider
        ↓
deterministic fallback implementation

The harness must therefore remain testable without an LLM connection.

"Offline" in this specification means:

No external LLM/web call is required for harness correctness.

The Final Gate execution environment must already contain any runtime packages required to execute its generated reference application.

Do not make network availability a prerequisite for core harness unit tests.

7. DEFAULTS

When ambiguity exists, DO NOT ask.

Use these defaults.

Stack inference

"web app"
→ frontend=React
→ backend=FastAPI
→ db=SQLite

"API"
→ backend=FastAPI
→ db=SQLite

"todo"
→ FastAPI + SQLite + minimal HTML

unspecified
→ FastAPI + SQLite

App defaults

app_type = "web"

Infer pages from explicit nouns such as:

dashboard
login
projects
tasks
settings

Infer data entities from domain nouns.

Every explicit feature noun becomes a must_have candidate.

Default non-goals:

deployment
mobile-app
browser-automation

unless explicitly requested.

Planning defaults

Small applications:

5–12 tasks

Each task SHOULD:

touch <= 5 files
have >= 1 requirement
have >= 1 verification command

Timeouts

sandbox command: 120 seconds
runtime startup: 15 seconds
repair attempts: maximum 3

8. IDENTIFIER CONTRACT

Use deterministic ID formats.

REQ-001
REQ-002

TASK-001
TASK-002

TEST-001
TEST-002

run_XXXXXXXX

Requirement IDs and Task IDs must be sequential within a run.

Never reuse an ID for a different object.

9. RUN ARTIFACT CONTRACT

Each generated run lives under:

runs/<run_id>/

Required final layout:

runs/<run_id>/
├── state.json
├── spec.json
├── tasks.json
├── verification.json
├── review.json
├── events.log
├── checkpoints/
│   ├── 001-spec_created.json
│   ├── 002-plan_created.json
│   └── ...
└── workspace/
    ├── source code
    └── tests

The canonical final deliverable for every run is:

workspace/
spec.json
tasks.json
verification.json
review.json
events.log
state.json

10. EVENT CONTRACT

All meaningful state transitions append one JSON object to:

runs/<run_id>/events.log

Required fields:

run_id
trace_id
stage
agent
task_id
timestamp
duration_ms
model
tokens
tool
status
error

Optional values may be empty, but keys must exist.

11. STATUS CONTRACT

TaskStatus

PENDING
READY
RUNNING
COMPLETED
FAILED
TIMED_OUT
BLOCKED

READY may be computed by the DAG engine rather than persisted.

A persisted ready-but-not-started task may remain:

PENDING

RunStatus

CREATED
SPEC_DONE
PLAN_DONE
BUILDING
VERIFYING
REPAIRING
REVIEW_DONE
PASS
FAIL

Preserve the distinction:

FAILED != TIMED_OUT

12. BUILD ORDER

The exact milestone order is:

M1  Infrastructure
M2  Specification
M3  Planning + DAG
M4  Building
M5  Verification
M6  Self-Repair
M7  Traceability
M8  Requirement Review
M9  Recovery
M10 Runtime Verification
M11 CLI + Benchmarks
M12 Final Gate

Do not reorder.

Do not start milestone M(N+1) while M(N) has failing acceptance tests.

Run:

pytest -q

after every milestone.

M1 — INFRASTRUCTURE

Goal

Create an installable repository containing:

data models;
run state;
providers;
local sandbox;
event logging;
deterministic IDs.

No agents yet.

Required structure

app-builder/
├── src/harness/__init__.py
├── src/harness/models/spec.py
├── src/harness/models/tasks.py
├── src/harness/models/results.py
├── src/harness/models/run.py
├── src/harness/state/store.py
├── src/harness/providers/base.py
├── src/harness/providers/mock.py
├── src/harness/providers/env.py
├── src/harness/sandbox/local.py
├── src/harness/utils/logging.py
├── src/harness/utils/ids.py
├── tests/
├── runs/
├── examples/
├── pyproject.toml
├── requirements.txt
├── README.md
└── .gitignore

Core models

Stack

frontend: str = "FastAPI"
backend: str = "FastAPI"
db: str = "SQLite"

Requirement

id: str
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]

The source specification does not fully define the fields of Page, Component, and DataEntity.

Use minimal Pydantic models sufficient for the specified validation rules; do not add unrelated domain complexity.

Task

id: str
description: str
depends_on: list[str] = []
files_touched: list[str] = []
requirements: list[str] = []
verification: list[str] = []
status: TaskStatus = PENDING

VerificationResult

task_id: str
status: str
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: str
trace_id: str
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

All models MUST use Pydantic v2 BaseModel.

All enums MUST derive from:

str, Enum

LocalSandbox

LocalSandbox(root: Path)

Required methods:

create_workspace(run_id) -> Path
write_file(rel, content) -> Path
read_file(rel) -> str
list_files(rel=".") -> list[str]
delete_file(rel)
execute(cmd, cwd=None, timeout_s=120) -> dict

Every path MUST be resolved against the configured sandbox root.

Reject:

../
absolute paths
symlink escape
resolved paths outside root

Prefer command execution as:

subprocess.run(list_args, shell=False)

Verification commands must be parsed with shlex.split().

Do not use shell=True in V1.

Return:

{
  "exit_code": 0,
  "stdout": "",
  "stderr": "",
  "duration_ms": 0
}

RunStore

RunStore(base=Path("runs"))

Methods:

create_run(user_request) -> RunState
save(state)
load(run_id) -> RunState
checkpoint(state, event_name, payload)
list_runs() -> list[str]
resume(run_id) -> RunState

LLMProvider

Abstract interface:

generate(prompt: str, system: str = "") -> str

generate_structured(
    prompt: str,
    schema: type[BaseModel]
) -> BaseModel

stream(prompt: str) -> Iterator[str]

Agents depend ONLY on this abstraction.

MockProvider

Must be:

deterministic
offline-safe
test-friendly

EnvOpenAICompatibleProvider

Read:

OPENAI_API_KEY
OPENAI_BASE_URL

If API key is absent:

delegate to MockProvider

Acceptance

Must pass:

pip install -e .
pytest -q

Tests must include:

AppSpec roundtrip
Task roundtrip
sandbox ../ rejection
sandbox absolute-path rejection
RunStore save/load
MockProvider deterministic behavior

No network required.

Forbidden

Do not implement:

SpecAgent
Planner
Builder
Verifier
DAG execution

M2 — SPECIFICATION AGENT + VALIDATOR

Goal

Transform:

user request

into:

validated spec.json

No application code generation yet.

Files

src/harness/agents/spec.py
src/harness/validation/spec_validator.py
tests/test_spec.py
examples/todo_spec.json

SpecAgent

Interface:

SpecAgent(llm: LLMProvider)

generate(user_request: str) -> AppSpec

System instruction:

Output ONLY JSON matching AppSpec.
No prose.
Infer stack, pages, data model, requirements,
must-have features, explicit non-goals and acceptance criteria.

Post-processing MUST:

assign REQ-001..N
ensure must_have is non-empty
ensure acceptance_criteria is non-empty
populate default explicit_non_goals when absent

If LLM output is invalid:

use deterministic rule-based fallback

Fallback must understand at minimum:

auth
projects
tasks
dashboard
todo

SpecValidator

Return:

list[str]

Empty list means PASS.

Structural checks

Verify:

app_type non-empty
stack fields non-empty
requirements >= 1
acceptance_criteria >= 1
REQ IDs unique
REQ IDs match ^REQ-\d{3}$

Logical checks

Verify:

page.entity references known data entity when entity is present
requirement does not conflict with explicit non-goal
backend is defined when requirement mentions API/backend
requirement text is unique case-insensitively
every must_have maps to >=1 requirement

Pipeline stage

Implement:

spec_stage(
    store,
    run_id,
    llm,
    max_attempts=2
)

Flow:

generate
→ validate
→ if invalid: regenerate with validation feedback
→ maximum 2 generation attempts
→ persist spec
→ checkpoint spec_created

Persist:

runs/<run_id>/spec.json

Acceptance

Test:

valid Todo request → PASS
conflicting login non-goal → FAIL
missing acceptance → FAIL
duplicate requirement → FAIL
first generation invalid + second valid → PASS

Create:

examples/todo_spec.json

with four requirements.

Forbidden

No planning.

No code generation.

M3 — PLANNER + DAG ENGINE

Goal

Transform:

AppSpec

into:

validated sequential Task DAG

Persist:

tasks.json

Files

src/harness/agents/planner.py
src/harness/orchestration/dag.py
src/harness/orchestration/runner.py
tests/test_planner.py
tests/test_dag.py

Planner rules

Enforce these in code.

Do NOT rely only on the LLM prompt.

Ordering

DB/schema before dependent application logic.
Shared components before pages.
Auth infrastructure before authenticated routes.

Coverage

Every:

REQ

must map to at least one Task.

Every Task must contain:

>=1 requirement
>=1 file
>=1 verification command

IDs

Generate:

TASK-001
TASK-002
...

Dependencies may reference only earlier tasks.

If LLM output violates ordering:

repair deterministically

Paths

Every files_touched path must be:

relative
POSIX-style
inside workspace
without ..

Fallback planner

If LLM planning fails, generate deterministic tasks roughly covering:

project/schema setup
auth if required
core entity CRUD
API/pages
tests/verification

For small apps:

5–12 tasks

DagEngine

Required behavior:

get_ready()
mark(task_id, status)
is_done()
blocked_propagation()
topological_order()

A task is READY iff:

status == PENDING
AND
all dependencies == COMPLETED

If dependency becomes:

FAILED
TIMED_OUT

dependent tasks become:

BLOCKED

Cycles must raise an explicit error.

PlanValidator

Detect:

duplicate task IDs
unknown dependency
cycle
orphan requirement
task without verification
task without files
task without requirements
invalid paths

Overlapping files:

WARNING only in V1

Acceptance

Todo spec with four requirements:

→ 5–8 tasks

Tests:

all requirements covered
dependency ordering valid
cycle rejected
TASK-001 failure blocks dependent task
tasks.json persisted
plan_created checkpoint persisted

Forbidden

No Builder execution.

No concurrency.

M4 — BUILDER + SANDBOX-GATED FILE TOOLS

Goal

Transform one Task into real files.

Files

src/harness/agents/builder.py
src/harness/tools/files.py
tests/test_builder.py

Builder context

Provide ONLY:

current Task
requirements referenced by Task
small spec summary
dependency verification results
allowed files
verification commands

Do NOT dump the full run history.

Example input:

task
requirements
spec_summary = {
    "app_type": ...,
    "stack": ...,
    "data_model": ...
}
dependency_results
allowed_files
verification

Builder output

LLM must produce:

{
  "relative/path.py": "full file contents"
}

No prose.

No markdown fences.

Write restrictions

Builder may write ONLY:

task.files_touched

Any attempted write outside the allowlist:

PermissionError
+
event log
+
task failure
+
CONFIG_ERROR

Builder may use only sandboxed:

read_file
write_file
list_files

Builder may NOT execute subprocesses.

Deterministic fallback

If LLM output cannot be parsed, use a deterministic implementation for the current task.

The fallback MUST obey the same files_touched allowlist.

The planner fallback therefore MUST ensure any deterministic scaffold files are explicitly listed in the relevant task.

Reference generated application may include:

src/main.py
src/models.py
requirements.txt
tests/test_health.py

Do not create files outside the current Task's declared set.

Acceptance

Test:

allowed file write succeeds
outside-allowlist write fails
../ escape fails
MockProvider creates deterministic output
checkpoint created after task

After milestone:

pytest -q

must pass.

Forbidden

No verification execution inside Builder.

No repair.

M5 — REAL VERIFICATION + FAILURE CLASSIFICATION

Goal

Execute real verification commands and persist structured evidence.

Files

src/harness/verification/verifier.py
src/harness/verification/classifier.py
tests/test_verifier.py
tests/test_classifier.py

Verifier

Implement:

verify_task(
    task: Task,
    workspace: Path
) -> list[VerificationResult]

For every verification command:

shlex.split(command)
→ LocalSandbox.execute(...)

Default when missing:

pytest -q

Capture:

exit_code
stdout[-4000:]
stderr[-4000:]
duration_ms

PASS:

exit_code == 0

FAIL:

exit_code != 0

Timeout:

Task status = TIMED_OUT
FailureType = TIMEOUT

Static inspection alone can never count as verification.

Workspace verification

Provide helper:

verify_workspace(workspace)

It may include project-level checks appropriate to files actually present.

Do not blindly require external network installation as part of offline harness unit tests.

Failure classifier precedence

Classification MUST be deterministic.

Use precedence:

1. TIMEOUT
2. ENVIRONMENT_ERROR
3. DEPENDENCY_ERROR
4. TYPE_ERROR
5. CODE_ERROR
6. CONFIG_ERROR
7. TEST_FAILURE
8. UNKNOWN

The precedence matters.

For example, a pytest session containing a Python SyntaxError must classify as:

CODE_ERROR

not merely TEST_FAILURE.

TIMEOUT

Patterns:

timed out
TimeoutExpired
duration >= configured timeout

ENVIRONMENT_ERROR

Patterns:

EAI_AGAIN
ENOTFOUND
registry unavailable
Network is unreachable
HTTP 503
Could not fetch

DEPENDENCY_ERROR

Patterns:

ModuleNotFoundError
ImportError
No module named
Could not resolve dependency
npm ERR 404

TYPE_ERROR

Patterns:

mypy
Pydantic ValidationError
TypeError ... expected
TS2322
Property ... does not exist

CODE_ERROR

Patterns:

SyntaxError
IndentationError
NameError
ReferenceError

CONFIG_ERROR

Patterns:

missing configuration
missing pyproject
requirements file not found
port already in use
invalid path configuration

TEST_FAILURE

Patterns:

AssertionError
FAILED
1 failed
FAIL tests/

Only after higher-priority categories have been excluded.

Acceptance

Tests:

SyntaxError → CODE_ERROR
ModuleNotFoundError → DEPENDENCY_ERROR
AssertionError → TEST_FAILURE
network unavailable → ENVIRONMENT_ERROR
timeout → TIMEOUT
working scaffold → PASS

Persist verification evidence.

Forbidden

No automatic repair yet.

M6 — REPAIR LOOP + LOOP DETECTION

Goal

Implement:

FAIL
→ classify
→ repair
→ verify

with bounded retries.

Files

src/harness/orchestration/repair.py
src/harness/agents/repair_agent.py
tests/test_repair.py

Loop signature

sha256(
    command
    + exit_code
    + normalize(stderr[-2000:])
)

Normalization:

lowercase
strip changing timestamps
strip volatile numeric values
normalize paths
collapse whitespace

Track:

seen[signature] += 1

If the same normalized failure signature occurs three times:

ESCALATE
FAILED
BLOCK dependents

Total repair attempts MUST NEVER exceed:

Repair strategy

ENVIRONMENT_ERROR

Do not rewrite application code.
Retry once.
If still failing → FAILED.

DEPENDENCY_ERROR

Repair only dependency/config files that are already allowed by the Task or explicitly listed as verification hints.

TYPE_ERROR

Patch relevant code only.

CODE_ERROR

Patch relevant code only.

TEST_FAILURE

Patch implementation or tests only when justified by requirement evidence.

Do not simply weaken tests to obtain PASS.

CONFIG_ERROR

Patch configuration files only.

TIMEOUT

Allow one bounded adjustment/retry.

Do not create an unbounded timeout.

RepairAgent context

Provide:

Task
relevant requirement slice
failing VerificationResult
FailureType
allowed files
current relevant file contents

Truncate large source context around:

8000 chars per repair context

Output:

{
  "relative/path": "full corrected contents"
}

Acceptance

Tests:

repair SyntaxError → PASS within <=3 attempts
same failure 3 times → ESCALATE
dependents become BLOCKED
ENVIRONMENT_ERROR does not modify code
files outside allowlist cannot be repaired

M7 — TRACEABILITY MATRIX

Goal

Construct mechanical evidence:

Requirement
→ Tasks
→ Files
→ Verification
→ Result

Files

src/harness/trace/matrix.py
tests/test_trace.py

Matrix structure

For every requirement:

{
  "REQ-001": {
    "tasks": [],
    "files": [],
    "tests": [],
    "evidence": [],
    "status": "PASS|FAIL",
    "missing": []
  }
}

Compute:

tasks
= tasks referencing REQ

files
= union(task.files_touched)

tests
= union(task.verification)

evidence
= existing files
  + successful verification commands

PASS only if:

>=1 expected implementation file exists
AND
>=1 relevant verification result PASS

No evidence:

FAIL

Prose can never substitute for evidence.

Acceptance

Todo reference run:

4/4 requirements traced

Delete an implementation file:

associated requirement becomes FAIL

M8 — REQUIREMENT REVIEW

Goal

Perform the final requirement-level audit.

Files

src/harness/agents/reviewer.py
tests/test_review.py

ReviewAgent

Default authority:

rule-based evidence

LLM review is optional and explanatory only.

An LLM MAY:

add rationale
summarize evidence
identify concerns

An LLM MUST NOT:

turn evidence-based FAIL into PASS

Output

Persist:

runs/<run_id>/review.json

Shape:

{
  "requirements": [
    {
      "id": "REQ-001",
      "status": "PASS",
      "evidence": [],
      "missing": []
    }
  ],
  "overall_status": "PASS"
}

Overall PASS only if:

every requirement == PASS

Acceptance

Tests:

complete evidence → PASS
missing implementation file → FAIL
missing successful verification → FAIL
LLM cannot override FAIL
review JSON validates

M9 — CHECKPOINTING + CRASH RECOVERY

Goal

Resume interrupted runs without repeating completed work.

Files

src/harness/state/checkpoints.py
src/harness/orchestration/pipeline.py
tests/test_recovery.py

Required checkpoint events

spec_created
plan_created
task_started
task_completed
verification_completed
repair_started
review_completed

Filename convention:

checkpoints/<sequence>-<event>-<optional-task>.json

Example:

001-spec_created.json
002-plan_created.json
003-task_started-TASK-001.json
004-task_completed-TASK-001.json

Resume algorithm

load state.json
↓
validate state
↓
load latest checkpoint state
↓
reconstruct task statuses
↓
keep COMPLETED
keep FAILED
keep BLOCKED
convert interrupted RUNNING → PENDING
convert READY → PENDING
↓
continue unfinished pipeline

Completed tasks MUST NOT execute again.

Use file hashes where appropriate to prove completed output was not rewritten during resume.

Corruption handling

Corrupt:

state.json
checkpoint JSON

must produce a clear explicit error.

Never silently restart the run from scratch.

Acceptance

Simulate crash after:

TASK-002

Resume must:

finish remaining tasks
not rerun TASK-001
not alter completed file hashes

Test checkpoint sequencing.

M10 — RUNTIME VERIFICATION

Goal

Prove that the generated application actually starts and responds.

Static tests alone are insufficient.

Files

src/harness/verification/runtime.py
src/harness/verification/browser.py
tests/test_runtime.py

RuntimeVerifier

Entry detection

Recognize at minimum:

src/main.py:app
app.py:app
package.json

No recognized entry:

FAIL
CONFIG_ERROR

Start

FastAPI:

python -m uvicorn src.main:app --port <free_port>

Node fallback:

npm run dev -- --port <free_port>

Use an OS-assigned/free local port.

Start process with:

subprocess.Popen

with:

cwd jailed inside workspace
shell=False

The verification layer may own process execution; application-building agents may not.

Startup timeout

15 seconds

Checks

Verify:

process remains alive
TCP port accepts connection
GET /health OR / returns 2xx
GET /docs or /api/health when available
SQLite DB can be opened when expected

Cleanup

Always terminate spawned process.

Use finally cleanup.

Never leave orphan development servers.

Result

Return structured:

{
  "status": "PASS",
  "checks": [
    {
      "name": "health",
      "ok": true,
      "detail": "HTTP 200"
    }
  ],
  "evidence": []
}

Capture useful log snippets.

Browser V1 stub

Implement only:

def verify_acceptance(...):
    raise NotImplementedError(
        "Browser verification deferred post-V1"
    )

Test that the browser verifier remains explicitly deferred.

Do NOT install Playwright or Selenium.

Acceptance

Reference application:

starts
port opens
health endpoint returns 200
runtime verifier PASS

Broken startup:

FAIL
diagnostics captured
repair hint available

M11 — CLI + BENCHMARKS

Goal

Expose the entire harness through a deterministic command-line interface and provide a quick regression benchmark.

Files

src/harness/cli.py
src/harness/orchestration/pipeline.py
src/harness/benchmarks.py
tests/test_cli.py
tests/test_benchmarks.py

Add console entrypoint:

[project.scripts]
builder = "harness.cli:main"

Use:

argparse only

No Click/Typer dependency.

CLI commands

New run

builder new "Build a Todo app"

Equivalent module form:

python -m harness.cli new "Build a Todo app"

It must execute the full pipeline.

Resume

builder resume <run_id>

Logs

builder logs <run_id>

Print or tail the run's structured event log in readable form.

Benchmark

builder bench --quick

Progress output

builder new must emit five user-facing high-level stages:

[1/5] SPEC
[2/5] PLAN
[3/5] BUILD
[4/5] VERIFY
[5/5] REVIEW

Detailed internal milestones remain M1–M12; the five-stage CLI view is only presentation.

On success:

BUILD COMPLETE

On failure:

BUILD FAILED

and return non-zero exit status.

Quick benchmark

builder bench --quick runs a deterministic small Todo scenario.

It must validate at minimum:

spec generated
plan generated
files written
verification executed
runtime checked
review produced
required artifacts exist

Return:

0 → PASS
non-zero → FAIL

Acceptance

Must pass:

builder new "Build a Todo app"
builder bench --quick

Offline LLM fallback must still function.

Verify:

all required artifacts exist
five-stage output matches expected format
events.log contains required keys
quick benchmark passes

Forbidden

No Web UI.

No production Docker environment.

M12 — FINAL GATE

Goal

Prove V1 reliability before declaring completion.

All gates are mandatory.

Gate 1 — Vertical Slice

Run:

builder new "Build a Simple Todo App with add/list/complete"

Expected pipeline:

SPEC
→ >=3 REQs
→ PLAN
→ >=3 tasks
→ BUILD
→ real files
→ VERIFY
→ pytest PASS
→ RUNTIME
→ PASS
→ REVIEW
→ PASS

Save a stable demonstration run under:

runs/demo_todo/

If any stage fails:

fix the harness
rerun
do not proceed

Gate 2 — Failure Injection

Inject:

SyntaxError

into:

workspace/src/main.py

The harness must:

DETECT
→ FAIL

CLASSIFY
→ CODE_ERROR

LOCALIZE
→ TASK-ID

CAPTURE
→ diagnostics

REPAIR
→ relevant file only

REVERIFY
→ PASS

Then simulate identical failure repeatedly using a no-op repair implementation.

Expected:

same signature x3
→ LOOP DETECTED
→ ESCALATE
→ task FAILED
→ dependents BLOCKED

Gate 3 — V1 Capability Checklist

All MUST be ✓:

[ ] valid spec generated
[ ] spec validated
[ ] valid DAG generated
[ ] sequential execution
[ ] real files created
[ ] real verification executed
[ ] failures localized
[ ] failures classified
[ ] failures repaired
[ ] repair bounded <=3
[ ] loop detection works
[ ] checkpoints written
[ ] crash resume works
[ ] completed tasks not rerun
[ ] traceability matrix generated
[ ] requirement review generated
[ ] runtime verified
[ ] final working project retained

Gate 4 — Documentation

README must document:

quickstart
builder new
builder resume
builder logs
builder bench --quick
architecture
evidence principle
failure handling
checkpoint recovery

Include an ASCII architecture diagram.

Create:

examples/todo_run/
├── spec.json
├── tasks.json
├── verification.json
└── review.json

Gate 5 — Full Test Suite

Run:

pytest -q
builder bench --quick

Both must pass.

V1 Forbidden-Feature Audit

Assert the implementation does NOT contain functional implementations for:

docker/
web_ui/
parallel workers
parallel DAG scheduler
Playwright
Selenium
PostgreSQL backend
web research

The browser verification stub is allowed.

FINAL DEFINITION OF DONE

V1 is complete only when:

M1 PASS
M2 PASS
M3 PASS
M4 PASS
M5 PASS
M6 PASS
M7 PASS
M8 PASS
M9 PASS
M10 PASS
M11 PASS
M12 PASS

Every bug fix MUST include a regression test.

Every new module MUST have tests.

Keep source files focused.

Prefer:

<400 lines per file

Split larger files when practical.

Never store:

API keys
secrets
absolute host-specific paths

Never delete historical checkpoints to hide failures.

FINAL RUN SUMMARY FORMAT

At the end of every run, print a requirement-level summary.

Example:

REQ-001
Implemented: YES
Tested: YES
Runtime: YES
Evidence:
- src/main.py
- pytest -q → exit_code 0
Status: PASS

REQ-002
Implemented: YES
Tested: NO
Runtime: NO
Missing:
- successful verification result
Status: FAIL

Final status:

PASS

only when every requirement has evidence-backed PASS status.

Never use:

"AI says finished"

as evidence.

EXECUTION COMMAND

Start now.

Implement:

M1

Run its tests.

If green, continue to:

M2

Continue sequentially until M12.

Do not ask questions.

Do not stop at intermediate milestones.

Do not skip failed gates.

Do not declare V1 complete until the Final Gate is green.

提示词正文

APP-BUILDER HARNESS

Autonomous Coding Agent Build Specification — V1

0. OPERATING CONTRACT

1. PROJECT GOAL

2. CENTRAL INVARIANT — EVIDENCE OVER CLAIMS

3. V1 SCOPE LOCK

Harness runtime

Harness architecture

4. STRICT V1 NON-GOALS

5. DEPENDENCY BOUNDARY

6. OFFLINE BEHAVIOR

7. DEFAULTS

Stack inference

App defaults

Planning defaults

Timeouts

8. IDENTIFIER CONTRACT

9. RUN ARTIFACT CONTRACT

10. EVENT CONTRACT

11. STATUS CONTRACT

TaskStatus

RunStatus

12. BUILD ORDER

M1 — INFRASTRUCTURE

Goal

Required structure

Core models

Stack

Requirement

AppSpec

Task

VerificationResult

FailureType

RequirementResult

RunState

LocalSandbox

RunStore

LLMProvider

MockProvider

EnvOpenAICompatibleProvider

Acceptance

Forbidden

M2 — SPECIFICATION AGENT + VALIDATOR

Goal

Files

SpecAgent

SpecValidator

Structural checks

Logical checks

Pipeline stage

Acceptance

Forbidden

M3 — PLANNER + DAG ENGINE

Goal

Files

Planner rules

Ordering

Coverage

IDs

Paths

Fallback planner

DagEngine

PlanValidator

Acceptance

Forbidden

M4 — BUILDER + SANDBOX-GATED FILE TOOLS

Goal

Files

Builder context

Builder output

Write restrictions

Deterministic fallback

Acceptance

Forbidden

M5 — REAL VERIFICATION + FAILURE CLASSIFICATION

Goal

Files

Verifier

Workspace verification