| name | harness-review |
| description | Adversarially review one tsforge harness subsystem (or all) against its invariants. Use when asked to "review the harness", "audit a subsystem", "check the gate/tools/loop/process layer", or before a release. Reads source + tests, checks each invariant, repros suspected breaks, and returns a structured findings list. |
Harness review
Review the tsforge harness one subsystem at a time against its contracts, the way
the codex pass that found the scaffold_web and process-group bugs did. The goal is
verified findings, not vibes: a finding is real only once you've reproduced it or
traced it to a concrete file:line.
Inputs
- A subsystem name from
docs/harness-subsystems.md (e.g. tools, lib/fs, loop,
gate, oracles, browser, inference, rules, cli, mcp, web-scaffold), or
all — review every subsystem (fan out; see below).
Procedure (one subsystem)
-
Load the contract. Read that subsystem's entry in docs/harness-subsystems.md —
its source globs, invariants, risk areas, checklist. If the entry looks stale versus
the code, note it as a finding (the manifest is part of the contract).
-
Read the source AND its tests. Don't skim. For each invariant, find the lines
that are supposed to uphold it. Absence of a test for an invariant is itself a P2.
-
Be adversarial. For each invariant assume it's violated until the code proves
otherwise. Walk the failure modes in "Risk areas". Ask: what input, ordering, env,
or platform makes this break? Mutation that doesn't re-gate? A kill that leaks a
child? Text that lies about state? A guard a forced/salvaged call routes around?
-
Reproduce. For any suspected break, write the smallest repro — a throwaway
bun script or a focused test in a temp dir. A repro that fires is a P1/P2; one that
doesn't clears the hunch (say so). Never report an unreproduced "could be".
-
Report. Return a findings list using the output template below.
If the subsystem is clean, say so explicitly and list which invariants you verified
and how — "clean" with no evidence is not an acceptable result.
Procedure (all)
Fan out: one focused review per subsystem (use the Agent tool — or a Workflow if the
user opted into multi-agent orchestration), each running the single-subsystem
procedure on its own slice, then collate into one severity-sorted list with a short
per-subsystem "verified / findings" summary. This is opt-in per run (it spawns many
agents); don't trigger it automatically.
Output template
Return findings in this shape (highest severity first):
## Harness review: <subsystem>
### Findings
#### P1 — <title>
- **location:** `path/to/file.ts:42`
- **evidence:** <repro steps or quoted code path>
- **fix:** <concrete sketch + regression test name>
#### P2 — …
### Verified (if clean)
- <invariant>: checked via <how>
Output discipline
- Quote real emission strings/identifiers before matching on them — grep the source,
don't guess keywords (a wrong keyword reads as "clean" when it isn't).
- Distinguish "I verified X holds" (with how) from "X looks fine" (didn't check).
- Tie every fix to a regression test; an un-tested fix is half a fix.
- Respect the house rules when sketching fixes: no
as casts, no eslint-disable,
cyclomatic complexity ≤ 20, reuse the shared AST walkers / serveEphemeral /
runArgvCommand rather than re-rolling them.
Verify the skill itself
After a review, the user should be able to run bun run validate and see any fix you
landed reflected as a green regression test. If a "finding" can't be turned into a
failing-then-passing test, treat it as unproven.
