Capstone: retrofit a brownfield repository and defend the autonomy decision: Practical Field Guide

On this page

01Working definition
02Field situation
03Worked example
04Build it, with checkpoints
05Operating context
06Hands-on lab
07Failure clinic
08Production boundary
09Sources and claim limits

Learning objectives

Integrate task contracts, repository knowledge, initialization, isolation, state, tools, rules, verification, observability, recovery, and graph policy
Run before-and-after holdout tasks with equivalent scope and evidence requirements
Produce a Harness Card that states boundaries, budgets, receipts, failure policy, owners, and removal paths
Issue a scoped go, conditional hold, or no-go decision and remove scaffolding that does not improve measured work

Before you start

• Completed artifacts and passing receipts from Modules 00 through 09
• A fresh Release Desk clone, the locked request-reopen holdout, a reviewer who did not build the harness, and fixture-only credentials

Working definition

Brownfield capstone

The capstone is an evidence-backed retrofit of a real-shaped but synthetic brownfield repository. Completion requires the code change, reproducible harness, full acceptance receipt, recovery and security drills, clean handoff, maintenance plan, and an operating decision limited to the evaluated task class. The goal is not maximum scaffolding. Every layer must protect a named boundary or improve a measured outcome enough to justify its upkeep.

Harness engineering becomes credible when another person can enter a clean environment, understand the repository, run the task, inspect the evidence, interrupt and resume safely, and reach the same release decision. A diagram or a successful recorded session cannot substitute for that reproduction.

The final decision should preserve uncertainty. A candidate may improve orientation and reduce reviewer intervention while still failing one recovery drill. That is a conditional hold, not a reason to weaken the gate. It may also reveal a costly layer that adds no observable value. Removing unnecessary complexity is a successful harness outcome.

Field situation

Request reopening as an unseen brownfield change

Release Desk, the holdout task, runs, metrics, reviewers, failures, and decisions are synthetic course materials.

Owner: A harness engineer delivering a repository retrofit to a skeptical engineering lead and independent reviewer.
Decision: Does the completed harness justify the proposed unattended window for this task class, and which layers should remain, change, or be removed?
Starting state: The request-changes feature is complete. The holdout asks authorized reviewers to reopen a resolved request with a reason, preserve one audit effect, reject stale state, and show the new status after refresh. The baseline agent has not seen this task.
Expected outcome: A reviewer reproduces the feature and receipts, verifies one logical effect and scoped cleanup, then signs a bounded decision with owners, limitations, and a next review date.

Constraints

• The baseline and candidate begin from equivalent clean commits and receive the same contract plus budgets
• The candidate may use only committed harness artifacts and fixture services; no private coaching or previous transcript is allowed
• The independent reviewer executes clean reproduction, one crash drill, one permission denial, one secret canary, and one two-worktree collision
• Any critical failure forces conditional hold or no-go until a new version passes the locked suite

Worked example

Faster orientation did not excuse a recovery failure

Evidence status: Named synthetic scenario

The candidate located the transition boundary and produced a focused diff with fewer reviewer interventions than the baseline. All happy-path checks passed. During the independent crash drill, resume inherited an expired approval fixture and attempted dispatch before reauthorization.

The critical stale-authority gate overrode the favorable productivity deltas. The decision remained conditional hold. The team moved authorization validation ahead of resume eligibility, added the failure to development and holdout suites, then repeated clean reproduction with a fresh reviewer.

The second candidate rejected stale approval, preserved one audit effect, passed the collision fixture, and left another worktree untouched. The signed decision allowed a bounded unattended window only for the evaluated transition task class. A redundant narrative summary generator was removed because the ledger and map already supported orientation.

Limits

The decision applies to the recorded Release Desk commit, harness version, task class, model and tool setup, budgets, and fixtures. Production data, broader writes, repository restructuring, or additional workers require new threat, evaluation, and operating evidence.

Method

Build it, with checkpoints

Field situation

Does the completed harness justify the proposed unattended window for this task class, and which layers should remain, change, or be removed?

01Assemble and validate the harness manifest
02Run equivalent baseline and candidate tasks
03Challenge and simplify the candidate

Acceptance checks

A fresh reviewer can reproduce the harnessed task, inspect why it passed, stop and recover it safely, confirm isolated cleanup, and defend a version-bound autonomy decision without relying on the builders' narrative.

Why this visualA capstone system map connects every retained harness layer to its evidence, owner, health check, and removal path.

01
Assemble and validate the harness manifest
Link every module artifact to its source commit, version, owner, health check, evidence, and removal command. Resolve broken links, expired exceptions, stale generated maps, dirty branches, missing fixtures, and inconsistent receipts before opening the holdout.
CHECKPOINT · One command validates the complete manifest from a clean clone, and every Harness Card claim resolves to executable control or reviewable evidence.
02
Run equivalent baseline and candidate tasks
Execute the locked request-reopen task without the new harness and with the frozen candidate. Preserve all trials. Compare behavior, critical controls, intervention, scope, orientation, recovery, elapsed time, total cost, context, and review effort using the predeclared rubric.
CHECKPOINT · Both reports bind the same task scope and disclose every environmental or model difference; critical failures remain visible outside productivity deltas.
03
Challenge and simplify the candidate
Run stale approval, unknown write, secret canary, skipped browser, collision, and destructive-target fixtures. For each harness layer, record benefit, cost, owner, and removal trigger. Remove one layer with no supported value, then rerun the complete suite and update the manifest.
CHECKPOINT · Critical fixtures pass after the change, the removed layer has no hidden dependency, and the smaller harness still supports clean orientation and recovery.
04
Hand off for blind reproduction
Give the independent reviewer only the repository, standard entry instruction, and declared fixture access. Ask them to initialize, implement or inspect the holdout, run acceptance, interrupt and resume, execute scoped cleanup, verify artifacts, and sign go, hold, or no-go.
CHECKPOINT · The reviewer reproduces evidence from a clean environment, explains limits and next action without chat history, and signs a decision tied to exact versions.
05
Set the operating and maintenance contract
Define supported tasks, unattended window, owners, monitoring, review sampling, kill authority, incident route, update triggers, scheduled health checks, maintenance budget, rollback, removal, and facts that would require reevaluation. Preserve unresolved risks with deadlines.
CHECKPOINT · The final memo names a narrow scope, accountable humans, critical stop conditions, next review date, and a simpler fallback path.

Operating context

Beyond the demo

Assemble a reproducible Harness Card

Document the supported task class, excluded work, repository entry points, authoritative state, initializer, environments, tools, permissions, rules, evaluator, budgets, terminal reasons, effects, recovery, kill control, handoff, owners, evidence retention, health checks, and removal commands. Link each claim to the artifact that enforces or proves it.

Record model, tool, runtime, lockfile, fixture, contract, prompt or instruction, rule, evaluator, and generator versions. Separate current facts from hypotheses and course fixture results. A reviewer should know which parts are executable, which require judgment, and which remain unverified.

Decide from deltas and critical gates

Compare baseline and harnessed holdouts on correctness, acceptance coverage, completion honesty, intervention, changed scope, orientation, recovery, elapsed time, total cost, context volume, and review effort. Critical permission, duplicate-effect, secret, destructive-action, evidence-integrity, and environment-isolation failures remain blockers regardless of average improvement.

For each harness layer, name its observed benefit, ongoing cost, owner, failure mode, and removal trigger. Keep the smallest set that supports the scoped decision. If a layer has no measurable or risk-reduction rationale, delete it and rerun the acceptance suite so simplicity is proven rather than assumed.

Hands-on lab

Deliver the Harness Card and independent reproduction

Assemble all course artifacts, run the baseline and harnessed holdout, repair only through versioned changes, remove one low-value layer, and hand the clean repository to an independent reviewer for acceptance and decision.

Prepare

• Freeze the holdout contract, critical gates, reviewer rubric, environment recipe, budgets, artifact manifest, and baseline commit
• Confirm the reviewer has no prior chat, private notes, production access, or authority beyond the synthetic Release Desk fixture

Deliverable

A runnable brownfield repository, Harness Card, artifact manifest with hashes, baseline and candidate report, holdout receipts, clean reproduction record, crash and permission drills, handoff packet, maintenance budget, layer decision table, and signed scope memo.

Starter kit: Harness Card

Markdown

# Release Desk Harness Card
Supported task class:
Excluded work:
Authoritative state:
Initializer and isolation:
Tools and permissions:
Mechanical rules:
Verification and receipts:
Budgets and terminal reasons:
Recovery, kill, and handoff:
Owners, health, and removal:
Decision and review date:

Downloadable artifacts

Harness Card

HARNESS-CARD.md · Markdown

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-10-receipt.json · JSON

A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.

Acceptance command

npm run harness:capstone -- --manifest .harness/artifacts.json --clean --blind-review

Expected receipt

PASS he-10 brownfield-capstone
cleanReproduction=true criticalFailures=0 removedLayers=1
logicalEffects=1 collisionScopeViolations=0 decision=scoped-go

Expected result

Carry forward

Keep the repository as a reference implementation, not a universal template. Re-run diagnosis, contracts, threat boundaries, target fixtures, and operating review whenever the task class, codebase, model, tools, data, authority, or scale changes.

Acceptance checks

01The artifact manifest validates from a clean clone and binds every file, rule, fixture, receipt, command, commit, owner, and removal path
02Baseline and candidate use equivalent scope and report correctness, critical controls, interventions, orientation, recovery, time, cost, context, and review
03Stale approval, unknown write, secret canary, skipped browser, collision, and destructive-target fixtures all produce the expected safe outcomes
04An independent reviewer reproduces the complete acceptance receipt and signs a versioned scoped decision with limits and review date
05At least one unsupported layer is removed and the complete suite proves that the simpler harness retains required behavior and controls

What breaks

Failure clinic

F1The capstone passes only when the builder explains hidden setup to the reviewer.

Inspect: Compare committed instructions, initializer output, environment receipt, private notes, manual actions, and clean-reproduction timeline.
Likely cause: Operational knowledge remained in conversation or personal memory instead of the repository system of record.
Repair: Stop the review, encode the missing fact or deterministic setup, add a cold-start fixture, and begin reproduction again.
Prevent next time: Use a reviewer with no prior context and count every coaching intervention as a failed orientation signal.

F2Productivity improves, but a critical permission or recovery gate fails.

Inspect: Separate correctness and speed deltas from permission, effect, secret, scope, recovery, and evidence-integrity outcomes.
Likely cause: The decision optimized an average result and treated required controls as secondary metrics.
Repair: Issue hold or no-go, repair the failed boundary, version the candidate, and repeat locked development plus holdout evaluation.
Prevent next time: Predeclare critical gates that cannot be outweighed by time or cost improvement.

F3The final harness contains many files, but no owner can explain why several exist.

Inspect: Review layer benefit, usage events, maintenance cost, failure coverage, dependency, owner, and removal trigger.
Likely cause: Artifacts accumulated from examples without evidence that they protect this repository or task class.
Repair: Remove unsupported layers one at a time, rerun the complete suite, and update the Harness Card plus maintenance budget.
Prevent next time: Require an observed benefit or named risk-reduction rationale and accountable owner for every retained layer.

Beyond the demo

Production boundary

01The Harness Card states supported and excluded tasks, authority, data, environments, effects, budgets, owners, and review date
02Every harness artifact is committed, versioned, hashed, linked to evidence, health-checked, owned, and removable
03Baseline and candidate comparisons use equivalent contracts, fixtures, critical gates, budgets, and complete evidence
04Clean reproduction covers initialization, task execution, full verification, interruption, recovery, permission denial, and scoped cleanup
05Critical effect, secret, permission, destructive-action, isolation, and evidence-integrity failures force hold or no-go
06The final scope defines monitoring, review sampling, kill authority, incident path, maintenance budget, rollback, and reevaluation triggers
07Unsupported scaffolding is removed and the smaller candidate passes the full suite before handoff

Evidence status

Sources and claim limits

Sources support the named claims; they do not guarantee the same result in another system.

[1]
Harness engineering: leveraging Codex in an agent-first world
OpenAI · Public case · 2026-08-26
repository knowledge · agent legibility · mechanical enforcement · entropy management
[2]
Effective harnesses for long-running agents
Anthropic · Published research · 2026-08-26
initializer pattern · feature ledger · session handoff · end-to-end verification
[3]
Harness design for long-running application development
Anthropic · Published research · 2026-08-26
planner-generator-evaluator · testable contracts · harness simplification · cost tradeoffs
[4]
Learn Harness Engineering
Walking Labs · Public case · 2026-08-26
project-based sequence · five harness subsystems · loop engineering · graph engineering
[5]
Andrej Karpathy's AI Engineering Playbook
AI Builder Club · Public case · 2026-08-26
Software 3.0 framing · spec-diff-eval practice · parallel session framing · repository instructions
[6]
Harness Engineering learning guide
deusyu · Public case · 2026-08-26
repository as record · mechanical rules · agent readability · continuous cleanup