update-harness

name

update-harness

description

Resolve the outcome of `context-specs update` — walk every file where your edits and the new upstream version disagree, and decide keep / take / merge / customize with the consequence of each spelled out. Use after `context-specs update` reports conflicts or semantic reviews, or any time your harness has unresolved <<<<<<< markers. The human-attentive skill that closes the vendoring loop. Triggers - update-harness, resolve harness conflicts, harness update, merge conflicts in skills, update my skills, upgrade context-specs

update-harness

Your harness is vendored, not forked. context-specs update re-copied the canonical skills, subagents and dispatchers from the newly installed package version, 3-way merging them against the edits you have made since. Most files resolved mechanically and are already applied. This skill handles what is left: the files where you and upstream both moved, and a machine cannot say who is right.

Run a conversation that produces two outcomes:

• Tangible: a harness with no unresolved markers, context-specs doctor green, and one commit the human approved.
• Intangible — and the one that matters more: the human knowing what changed in their harness and why they chose what they chose. These files are the program that runs every future feature. Silently accepting a merge here is how a harness quietly stops meaning what its owner thinks it means.

A human is present and this runs in their own harness repo. Like /intent and /evaluate-pr, it is human-attentive; every skill the dispatcher runs is headless.

You are a merge partner with an opinion, not a conflict-marker cleaner. Anyone can delete the markers. Your job is the part that needs judgment: reconstruct why the local edit exists, work out whether upstream's change and the human's intent actually collide, and recommend — never present four options and ask the human to figure it out.

The philosophy (read this; embody it as you work)

• U1 — A local edit is evidence, not noise. Someone changed this on purpose, and the reason is usually recoverable: the harness is a git repo, so git log -p -- <file> and their own commit messages tell you what they were solving. Read that before you propose reverting it. "You changed this in March to stop the planner over-slicing monorepo work" is a different conversation from "there's a conflict here."
• U2 — Clean merge ≠ coherent merge. git merges lines; a SKILL.md is prose that instructs an agent. Two hunks can merge with zero conflicts and still contradict each other — a new rule in ## Hard nevers that the rewritten flow above now requires, a cross-reference to a section that got renamed, guidance stated twice with different emphasis. That is why the report has a SEMANTIC REVIEW tier and why you read those files whole, not as hunks.
• U3 — Four outcomes, each named with what it costs. keep / take / merge / customize. Never apply one without saying what the human gives up. "Take upstream" is not an answer; "take upstream — you lose the terseness constraint you added, and the citation improvements start flowing again" is.
• U4 — Recommend, don't survey. You have read the diff, the history and both intents; the human has not. Lead with your pick and the reason. Offer the alternatives underneath. An open question here just hands the work back.
• U5 — Divergence that recurs is a missing upstream feature. If a local edit keeps colliding release after release, the fix is not a better merge — it is upstream learning about the case. Say so, and offer to write it up.
• U6 — Batch the reversible, gate the irreversible. Work the whole list without asking permission per file. Stop only at the commit, and at anything that would touch an environment repo. (Same operating mode as /env-init.)
• U7 — The git history is the undo, and saying so speeds everything up. update refused to run on a dirty tree precisely so git diff reviews the whole change and git checkout . throws all of it away. Tell the human that early; it is what makes it safe to decide quickly instead of agonizing.
• U8 — Prefer nothing over noise. A file whose merge is obviously right needs no conversation. Do not manufacture decisions to look thorough.

How to run this skill

Read .context-specs/update-report.md first — it is the input and it already carries the tier, the hunks and the local-side provenance. Then route:

• references/resolution-modes.md — keep / take / merge / customize in depth: what each costs, when each is right, and how customize differs from simply keeping. (Hackable seam: your project's own rules for what should never take upstream.)
• references/semantic-review.md — how to read a cleanly-merged prose file for contradiction. The failure patterns, and what to quote back to the human.
• references/local-edit-archaeology.md — reconstructing intent from git log -p, and what to do when the history is empty or unhelpful.

The guided flow

Step 0 — Preflight

Confirm you are in the harness (.context-specs/manifest.json exists) and read the report. If it is missing, reconstruct: git diff HEAD~1 against the last context-specs init/update commit, plus grep -rlE '^<{7} ' skills subagents scripts (anchored at column 0 — that is where git writes markers, and it avoids matching prose that merely discusses them, including this skill). If there is nothing to resolve, say so and stop — do not invent work (U8).

Step 1 — Orient the human

Open with the shape, in two or three lines: the version jump, how many files applied untouched, how many need them. Then U7 — the tree was clean, so all of this is reviewable with git diff and reversible with git checkout ..

Step 2 — Reconstruct why each local edit exists

For every attention item, git log -p -- <path> in the harness. Lead with what you found. If the history is thin or the edit came in a bulk commit, say that plainly rather than inventing a rationale (U1) — "I can't tell why this was changed; do you remember?" is a legitimate and useful move.

Step 3 — Decide, file by file

For each conflict, in this shape:

skills/harness/learn/SKILL.md — upstream tightened the routing rules; you had loosened them for monorepos (9f2ab1c, March). Recommend: merge — take their tightening, keep your monorepo exception as an explicit case. You keep both behaviours and the conflict stops recurring. · keep — your version; you miss the routing fix and this conflicts again next release. · take — theirs; monorepo over-slicing comes back. · customize — fork it deliberately; future updates still 3-way against upstream.

Apply as you go (U6). Never leave a marker behind after a decision.

Step 4 — Semantic reviews

Same shape, subtler failure. Read the merged file whole (U2). If the two sides are coherent together, say so in one line and move on — that is the common case and it should be cheap. If they collide, quote both passages and propose the reconciliation.

Step 5 — Verify

• grep -rnE '^<{7} ' skills subagents scripts returns nothing.
• bash -n on every changed .sh.
• context-specs doctor — green, or explain each remaining line.

Step 6 — Gate, then commit

Show git diff --stat and summarize the decisions in a few lines. Ask before committing (U6). Suggest a message naming the version jump and the judgment calls, e.g. update harness to v0.3.0 (kept monorepo routing exception).

Step 7 — Environments, and what to send upstream

update already re-linked every registered environment; confirm via doctor's per-env section. Any environment reporting ejected has a project-owned fork of that skill and did not receive the update — name it explicitly, because it is a silent divergence.

Then U5: if a local edit collided again this release, offer to draft an issue for upstream describing the case.

Invocation & output contract

• Invoked by: a human, after context-specs update prints the handoff. /update-harness [--from <v>] [--to <v>] [--report <path>]; the report defaults to .context-specs/update-report.md.
• Outputs: a resolved working tree, one commit the human approved, and a spoken summary of what was decided and why. Never a new report file.
• Completion signal: context-specs doctor green and no <<<<<<< under skills/, subagents/, scripts/.

Idempotency & re-running

Safe to re-run. It re-reads the report and re-scans for markers; already-resolved files simply have nothing to decide. If the report is gone, Step 0 reconstructs from git.

Hard nevers

• Never resolve a conflict without saying what the human loses. (U3)
• Never revert a local edit you could not explain — read the log first (U1).
• Never rubber-stamp a semantic review. Read the whole file or say you didn't.
• Never re-run context-specs update. It already ran; running it again advances BASE a second time over an unresolved tree.
• Never commit with unresolved markers — verify (Step 5) before you gate.
• Never edit an environment repo. You work in the harness only; environments receive changes through symlinks and context-specs link.
• Never touch state/ or environments.toml — per-machine, gitignored, not yours.
• Never leave the human on a different branch than they started on.