harness-maintenance-audit

Harness maintenance audit

What rots, and why it rots silently

This repo has an unusual shape that produces two specific failure modes.

It is a product and its own blueprint. docs/ describes a plugin that skills/, hooks/, commands/ and oracles/ actually implement. Both are prose-heavy, both are edited by hand, and nothing mechanically ties a sentence in docs/design/03-system-design.md to the enum it describes. So the docs drift, and they drift plausibly — a doc that says "11 workers" over a 10-member enum reads perfectly.

Not everything in the repo is product. Development artifacts — benchmark numbers, internal defect IDs, migration stage names, audit codenames, paths under docs/, tests/, tools/, evals/ — belong in the repo but not in what a user reads as the product. They leak easily, because the person writing a code comment is holding all that context and it feels like useful rationale at the time.

The leak that matters most is not in a code comment. skills/*/SKILL.md and skills/tech-lead/references/*.md are loaded by the model at runtime, so a dangling docs/migration/... pointer there is a broken instruction handed to the orchestrator mid-run — the file does not exist in an installed plugin. references/forbidden-content.md ranks the severity tiers and, importantly, defines what "shipped" means: there are two delivery channels, and the files allowlist governs only one of them.

Both are invisible to the test suite and to code review, because in both cases the wrong text is locally coherent. The only way to catch them is to derive the truth from artifacts and compare.

The one rule that makes this work

Never confirm a fact by reading prose. Derive it from the thing itself.

A doc that says GATE L2 denies, a glossary that calls it "the deny hook", and a README whose screenshot shows a denial will all agree with each other and all be wrong. Reading any of them confirms the others. Executing the hook settles it in one command.