harness-update

Skill: harness-update

WHAT

Purpose and context

• Purpose: One command call and it's done for an OLD project: install/update the harness stack (L0–L4) and automatically pay off the legacy wiki debt for the user.
• Trigger (when to use): "tự bảo trì framework", "self-maintain", "migrate harness", "update harness", "update overstack", "nâng cấp harness", "cài harness vào dự án cũ", "/harness-update" — the project has an old llmwiki that needs migrating (case B) or already has a harness that needs updating (case C).
• Non-goals: NOT for a project that has nothing yet + needs to populate the wiki from code — that is /new-project-setup (case A). Does not fix infrastructure errors (network, python3, broken validator).

< 30s: use the flag --self-heal — the installer automatically backfills the debt (Origin + index + OKF) right within the process and then re-audits once. The agent only calls 1 command, reads 1 result, reports. There is NO more re-run loop on the agent side (that is what slowed down the old version — see [[230626-harness-update-sub30s]]).

Mental model

installer --self-heal (1 process: cài L0–L4 → audit → backfill → re-audit → activate + smoke) → rc (0 sạch · 3 nợ còn lại · khác = hạ tầng) → nghiệm thu + refresh CAPABILITIES + log → báo cáo 4 ý.

Input and output contract

	Field	Required?	Meaning
In	target project (current directory)	yes	has an old llmwiki (case B) or an old harness (case C)
In	harness/scripts/install-harness.sh	no	if missing, clone the template rheinmir/setup branch orca
Out	harness L0–L4 installed + wiki debt backfilled	yes	rc=0 is clean
Out	CAPABILITIES.md regenerated	when build-capabilities is present	old version does not have it → skip
Out	log line llmwiki/wiki/log.md + a 4-point report	yes	the backfill count is taken from the line [audit] backfill xong

Rules and capabilities

• RULE-01 (MUST): Backfill is ADDING, never modify/delete existing wiki content (self-heal in the installer adheres to this rule).
• RULE-02 (MUST): Do not touch raw/ in any form.
• RULE-03 (MUST): rc=3 (remaining debt) needs the user/skill to handle once; other rc (infrastructure) is the user's job — distinguish clearly, do not try to fix infrastructure errors.
• RULE-04 (MUST): Without the flag --self-heal → the installer runs exactly the old behavior (audit then exit 3 if there is debt) — backward-compatible.
• RULE-05 (MUST): Case A (no llmwiki yet, needs to read code to populate the wiki) → redirect to /new-project-setup.
• Capabilities: run the installer locally (may clone the template over the network); write harness + wiki (add-only) + log; do not write raw/.

Failure boundaries

• rc=3 → partial: the debt list is in the output, fix it manually once and re-run W01.
• rc other (1/4) → blocked (infrastructure): STOP, report to user verbatim, do not guess.
• Project does not have llmwiki yet (case A) → cancelled in this skill, switch /new-project-setup.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	target project	Run installer once with --self-heal (if source is missing, clone template)	output + rc	—
W02	deterministic	rc	Read exit code, NO re-run loop	rc=0 → W03	rc=3 → B01; other rc → blocked
W03	effect	output W01	Acceptance ⛔×3 + refresh CAPABILITIES + optional health-check + log	log + CAPABILITIES	no build-capabilities → skip
W04	deterministic	result	Report to user with all 4 points	report	—

Details for each step (source of truth for W01–W04):

1. Choose the path by LAYOUT then run the installer exactly once:

• Downstream project layout dot (has .llmwiki/.harness-stamp — every machine installs from v4): the engine lives in GLOBAL, so updating = re-running bootstrap. It refreshes ~/.claude/harness when the version differs, pulls/updates the engine orca-graph in the same trip as the shim, closes the stamp, and does NOT copy the engine into the project:

curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/harness/poc-vendor-neutral/bootstrap.sh | bash

Calling the wrong install-harness.sh . --self-heal in this layout → the script automatically STOPS rc 5 and prints exactly the command above (measured 09/20/2026: the old path did not update global and even copied 77 scripts into the project). Agent runs in a terminal with a pty: add -s -- --with-graph to avoid waiting for the 60-second checklist.

• Framework repo (repo_role: framework): do NOT run the installer here — the installer automatically refuses rc 3. Updating the framework = git pull.
• Old bare layout (llmwiki/ + harness/ is in the project, no stamp yet) — the path --self-heal (auto-detects migrate/update; if source is missing, clone template):

test -f harness/scripts/install-harness.sh \
  && bash harness/scripts/install-harness.sh . --self-heal \
  || { git clone -q --depth 1 -b orca git@github.com:rheinmir/setup.git /tmp/llmwiki-tpl \
       && bash /tmp/llmwiki-tpl/harness/scripts/install-harness.sh . --self-heal ; rm -rf /tmp/llmwiki-tpl; }

The installer does the whole package itself: install L0–L4 → audit (Origin/index/OKF merged into 1 process via audit.py) → if there is debt then AUTO backfill (Origin gets the hash in 1 pass git log for the whole batch; index adds missing rows; OKF migrates bold **Type:** → YAML) → re-audit once → activate + smoke.

2. Read exit code (NO re-run loop — self-heal already ran inside):

• rc=0 → clean (auto backfill finished). Go to step 3.
• rc=3 → remaining self-heal debt that could NOT be auto-fixed (e.g. file conflict, undeducible OKF type): the list is right in the output. Fix manually once then re-run step 1.
• rc khác (1/4) → infrastructure error (network, python3, broken validator) — STOP, report to user verbatim, do not guess.

3. Acceptance + log:

• Confirm the "Harness self-check" table has ⛔×3 BLOCKED ✓ in the output of step 1 (the installer has run pre-commit install if pre-commit exists; if not, remind the user pipx install pre-commit).
• Refresh the capability map (so the agent sees the right toolset after update — ADR-005): python3 ~/.claude/harness/hooks/build-capabilities.py --root . (the deployed copy next to hooks) OR python3 fdk/tools/build-capabilities.py (if inside the framework repo) → regenerate CAPABILITIES.md. If there is no build-capabilities file (old version) → skip, no error.
• Health-check (optional, confirm the guard still bites after update): /health-check or python3 ~/.claude/harness/hooks/health-check.py.
• Append to llmwiki/wiki/log.md: ## YYYY-MM-DD — harness-update — migrate/update xong (--self-heal), nợ đã backfill: <n> file. Figures taken from the line [audit] backfill xong — Origin:<a> index:<b> OKF:<c> in the output.

4. Report to user (mandatory, all 4 points):

• Mode that ran (migrate or update) + number of self-heal debts backfilled (Origin/index/OKF from the line [audit] backfill xong)
• Settings root: backup file .bak.* if there was a merge
• Reminder: open a new session for the new hooks to load
• Invite: /harness-tour to see the guard bite visually

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	recovery	rc=3	manually fix once the self-heal debts that cannot be fixed automatically (list in the output)	still rc=3 → report to user	W01
B02	capability_optional	there is build-capabilities.py (deployed copy or framework repo)	regenerate CAPABILITIES.md	old version does not have it → skip, no error	W03
B03	user_optional	want to confirm the guard still bites	/health-check	skip	W03

Validation and stopping

Verdict by the installer's rc (deterministic) + the "Harness self-check" table has ⛔×3. At most one round of B01 → W01; rc other than 0/3 stops immediately.

Examples

• Positive: a project has an old llmwiki missing ## Origin on 12 pages → install-harness.sh . --self-heal → [audit] backfill xong — Origin:12 index:0 OKF:0, rc=0 → log + report "migrate, backfill 12 files, open a new session for hooks to load".
• Boundary/failure: the machine does not have python3 → rc=1 → STOP, report the error to the user verbatim, do not install or rerun on your own.