---
name: harness-update
description: Use after a completed or validated workflow run to separate product implementation from durable harness evolution. Produces and reviews a scoped proposal before changing AGENTS.md, docs, skills, agent specs, or run templates.
---

# Harness Update Workflow

Use this workflow after a non-trivial feature has implementation evidence, verification evidence, and validation evidence.

The goal is to improve the reusable project harness without letting one run poison durable instructions with overbroad lessons.

## When to use

Use after:

- non-trivial feature implementation and validation
- a validator finding reveals a missing or stale rule
- a human correction exposes a repeated workflow mistake
- a run shows harness activation or adherence problems
- a project should promote a lesson from chat or a run artifact into durable docs

Do not use for:

- product feature implementation
- final implementation validation
- broad architecture changes
- automatic memory/rule promotion after every correction

## Workflow

1. Create or select `.agent-runs/<feature-id>/`.
2. Confirm implementation and validation evidence exists:
   - `04_implementation_summary.md`, `04_backend_summary.md`, or `05_frontend_summary.md`
   - `06_test_report.md`
   - `07_validator_report.md`
   - `08_handoff.md` when the project uses handoff checkpoints
3. Invoke `harness-updater` with the run folder and current diff.
4. Have `harness-updater` write `09_harness_update_proposal.md`.
5. Invoke `harness-reviewer` to review the proposal and write `10_harness_review_report.md`.
6. If the reviewer verdict is `APPROVE_AUTO`, apply only the approved small, scoped patches.
7. If the reviewer verdict is `NEEDS_HUMAN`, stop for human approval before patching.
8. If the reviewer verdict is `REJECT` or `BLOCKED`, do not patch until the proposal is revised and reviewed again.
9. If a shared skill or agent definition changes, keep source and runtime copies synchronized.
10. Run lightweight validation after applied patches:
   - markdown/readability review
   - source/runtime sync check
   - any project-documented docs or lint checks

## Activation/adherence diagnostics

Every proposal should distinguish:

- Harness activation failure: the right artifact existed but was not loaded, selected, or routed.
- Harness adherence failure: the artifact was loaded but not followed.

Fix activation failures with routing, preflight, or artifact-discovery changes.
Fix adherence failures with clearer checklists, validator checks, or narrower instructions.

Do not respond to adherence failures by blindly adding more rules. First check whether the current rules are too broad, duplicated, stale, or hidden in the wrong file.

## Promotion policy

Use these statuses for lessons:

- `candidate`: supported by one run or one correction; proposal only unless the risk is severe.
- `confirmed`: repeated across runs or explicitly approved by the human.
- `deprecated`: previously useful but now contradicted by architecture, workflow, or human preference.

Prefer project-specific docs for project-specific lessons. Prefer scaffold skills or agent specs only for lessons that should transfer across future projects.

## Reviewer verdicts

`harness-reviewer` uses these verdicts:

- `APPROVE_AUTO`: evidence-backed, low-risk, narrow updates may be applied without additional human approval.
- `NEEDS_HUMAN`: the proposal may be valid but touches a human-gated area or has enough risk that a human should approve before patching.
- `REJECT`: the proposal is unsupported, overbroad, stale, redundant, or targets the wrong artifact.
- `BLOCKED`: the reviewer cannot determine safety because required evidence is missing or contradictory.

Only use `APPROVE_AUTO` for low-risk changes such as typo/readability fixes, narrow checklist additions marked `candidate`, source/runtime sync repairs for already-approved content, missing report-template fields, or documentation clarifications that preserve existing approval gates.

Human approval is still required before changing constitutional rules, shared skill behavior, agent responsibilities, workflow routing, validation policy, model tier policy, security policy, dependency policy, persistence strategy, architecture rules, or approval requirements.

## Output

Write:

```text
.agent-runs/<feature-id>/09_harness_update_proposal.md
.agent-runs/<feature-id>/10_harness_review_report.md
```

The proposal should include:

```markdown
# Harness Update Proposal

## Run outcome

## Evidence reviewed

## Activation/adherence diagnostics

## Proposed harness updates

## Rejected overgeneralizations

## Follow-up checks
```

The review report should include:

```markdown
# Harness Review Report

Verdict: APPROVE_AUTO / NEEDS_HUMAN / REJECT / BLOCKED

## Evidence check

## Item review

## Approval gates

## Follow-up validation
```

## Human approval gates

Human approval is required before:

- changing project constitution rules in `AGENTS.md`
- changing shared skills or agent definitions
- promoting a one-off lesson into a global rule
- changing workflow routing or validation policy
- weakening safety, privacy, dependency, verification, or validation rules

## Final output

- Proposal path
- Review report path and verdict
- Highest-value proposed update
- Updates intentionally rejected
- Files patched, if patching was explicitly requested
- Follow-up validation needed