docs: add repo health — the question a code reviewer actually has (#13)

The README already answered "are the contracts live" well: dated receipts, real
token IDs, basescan links, honest gaps noted inline. It did not answer "is this
codebase healthy", which is what a reviewer opens a repo to find out.

Adds one table of things a reviewer can run locally, and one of what is known
broken. Every row re-verified today before committing:

  npm ci                    exit 0
  CI                        4 jobs (install / contracts / coverage-map)
  HAL parity                11/11
  contract suite            61 tests execute

And the part that matters most, stated where it cannot be missed rather than
buried: 26 of 61 ReputationRegistry tests fail, and it is ONE defect, not 26.
`NewFeedback` in the Solidity source carries a 12th parameter (bytes
x402PaymentProof) that appears in neither ERC8004SPEC.md:224 nor the checked-in
abis/ReputationRegistry.json — both specify 11. That changes the event
signature, so an ERC-8004-compliant indexer filtering the canonical topic0 sees
ZERO feedback events from this contract. Diagnosed and left alone: the spec's
owner decides the fix.

A reviewer who hits that suite cold concludes the contracts are broken. A
reviewer who reads this concludes there is one conformance decision outstanding.
Those are very different impressions of the same repository.

Also states plainly, with the 404s that prove it, that @hyperdag/protocol and
all six named default packages are unpublished, and that the kernel source is
branch-only — then points at @hyperdag/trustshell, which IS published and
reaches the same contracts. A reviewer should leave with something they can
actually install.

No new claims. Every line is a command someone can run or a link they can open.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: DealAppSeo

README.md

@@ -24,6 +24,37 @@ Both canonical registries are live on-chain, holding real minted identities and
 
 ---
 
+## Repo health — what a reviewer can run today
+
+The section above answers "are the contracts live". This one answers "is the
+codebase healthy", which is the question a code reviewer actually has. Both
+columns are current as of **2026-08-06** and every row is checkable locally.
+
+| Works today | Command | Result |
+|---|---|---|
+| Clean install from the lockfile | `npm ci` | exits 0 |
+| CI | `.github/workflows/ci.yml` | 4 jobs: install · contracts · coverage-map |
+| HAL parity against production | `cd packages/defaults/hallucination-hal-local && npm test` | **11/11** — golden vectors captured from the upstream extractor |
+| Contract test suite runs | `cd packages/contracts && npm test` | 61 tests execute (see the known failure below) |
+
+| Known broken / not live | Actual state |
+|---|---|
+| **`ReputationRegistry` tests: 26 of 61 fail** | **One defect, not 26.** `NewFeedback` in the Solidity source carries a 12th parameter (`bytes x402PaymentProof`) that appears in neither `ERC8004SPEC.md:224` nor the checked-in `abis/ReputationRegistry.json`, both of which specify 11. That changes the event signature, so an ERC-8004-compliant indexer filtering the canonical `topic0` sees **zero** feedback events from this contract. Diagnosed, not patched — the spec's owner decides. |
+| `@hyperdag/protocol` on npm | **not published** — `npm view` returns 404 |
+| The six default packages (`@hyperdag/identity-erc8004`, `reputation-zkp`, `validation-trinity`, `payment-x402`, `linkage-registry`, `hallucination-hal`) | **not published** — 404 for all six |
+| Six-interface kernel source | on `feat/modular-kernel-interfaces-2026-05-04`, **not on `main`** |
+| `packages/protocol`, `packages/interfaces` | untracked `dist` output only; no rebuildable source |
+
+**To use the trust layer today, install [`@hyperdag/trustshell`](https://www.npmjs.com/package/@hyperdag/trustshell)** — it is published, keyless for HAL scoring, RepID reads and ZK proofs, and it reaches the same contracts listed above.
+
+> `hallucination-hal-local` and `identity-erc8004-viem` are the two packages that
+> actually exist in this repo. Neither is one of the six names above. Until
+> 2026-08-05 the HAL copy asserted byte-equivalence with production while being
+> blind to prompt injection for three months; that is fixed and now held by the
+> parity test in the table.
+
+---
+
 ## Receipts
 
 Real on-chain ERC-8004 activity from a production agent fleet. Every number is verifiable on basescan; honest gaps are noted inline.