Improve Harness

Improve Harness

Improve one bounded future-agent behavior without turning every difficult task into permanent process. Keep consumer truth with its owner and require a fresh rerun before claiming improvement.

Establish Authority

• Read AGENTS.md, docs/WORKFLOW.md, and applicable local instructions.
• Confirm the request authorizes changing Harness behavior. Inspection or a request to report friction does not authorize edits.
• Record the initial repository root, revision, branch, status, and unrelated changes. Preserve all existing work.
• Treat invocation as authority for this bounded experiment, not for changing product policy, weakening proof, adding credentials, or mutating external systems.

1. Preserve The Baseline

Use an observed task trajectory when available. Record:

• the representative job and accepted outcome;
• the concrete failure and evidence;
• human steering, relay, or recovery required;
• the worker, repository revision, relevant external state, tools, and authority; and
• existing proof and known limitations.

Do not diagnose a worker limitation from one run. If no observed baseline exists, stop with an experiment proposal; do not manufacture one.

Copy docs/templates/harness-improvement.md to docs/plans/active/harness-improvement-<slug>.md. Reuse an existing active record for the same experiment.

2. Locate The Earliest Gap

Trace the failure upstream to the first owner that could have prevented or exposed it:

• Context: knowledge was absent, stale, overloaded, or not retrieved.
• Capability: discovery, invocation, interpretation, repair, or real-system verification failed.
• Domain ownership: no canonical type, API, state machine, or source owned the invariant.
• Authority: permission, approval, audit, or recovery was unclear.
• Proof: checks established a proxy rather than the accepted outcome.
• Environment: an external prerequisite was unavailable.

Assign the correction to repository-harness, the consumer repository, the external environment, or a human decision. Do not copy consumer commands or policy into a generic upstream template.

3. State And Apply One Intervention

Before editing, write:

If <smallest change> is added at <owner>, then a fresh agent will
<observable change> on <representative job>, because <mechanism>.
Evidence that would weaken this:
Maintenance owner and removal condition:

Make only the authorized intervention. Prefer an existing owner, a clearer route, an actionable diagnostic, a runbook fact, a type or API, or claim-matched proof over a parallel framework. Keep unknown policy unknown. Run repository-native checks that protect the changed boundary.

4. Require A Fresh Rerun

Use a fresh agent session and an equivalent starting state. Hold the worker, task class, authority, tools, and relevant external conditions materially steady. Record separately whether the intervention was available, retrieved or invoked, and relevant.

If a fresh rerun is not authorized or available, leave the record active with Decision: pending fresh rerun. Report the exact next task; do not claim the Harness improved.

5. Keep, Revise, Or Remove

Compare accepted outcome, claim-matched proof, human intervention, retries, authority behavior, and maintenance cost.

• Keep when the rerun exercised the intervention and improved the bounded job enough to justify its cost.
• Revise when the owner is correct but the route or interface remains hard to use.
• Remove when it adds noise, duplicates a better owner, or does not improve the job.

Record the decision, evidence, owner, and removal condition. Move the record to docs/plans/completed/ only after native validation and the fresh-rerun decision. Preserve a removed intervention's result in the completed record.

Report

Return:

• representative job and baseline;
• earliest gap and owner;
• intervention and changed files;
• native validation;
• fresh-rerun status and comparison;
• keep, revise, remove, or pending fresh rerun; and
• remaining authority, risk, or follow-up.