docs: the hard-stop paths pointed at a root that has none of those files

[DealAppSeo]

Two gaps found by measuring the other repos rather than reading about them. Both are the class LESSONS rule 12 exists for: a wrong or missing message sends the next agent astray, and outlives the thing it describes.

1. The Marco De Rossi hard stop named paths that do not exist

The line read:

Marco De Rossi's files in hyperdag-protocol: ERC8004SPEC.md, contracts/, test/, abis/

Four bare root-level names. None of the four exist at that repository's root [MEASURED 2026-09-08]. All live one directory down, under packages/contracts/:

VERIFIED exists: packages/contracts/ERC8004SPEC.md
VERIFIED exists: packages/contracts/contracts
VERIFIED exists: packages/contracts/test
VERIFIED exists: packages/contracts/abis
root lacks ERC8004SPEC.md / contracts / test / abis

The failure mode is silent and lands on the worst possible target. An agent checks the documented path before touching anything — the correct instinct — finds nothing there, and concludes the hard stop is stale. A live prohibition read as a dead one, on the one set of files that must not be touched without Sean's permission.

This is the same shape as the plonky3-stub line that prompted rule 12: not a lie, just a description nobody re-measured, repeated forward as fact.

2. hyperdag-protocol had no entry point at all

A find across its whole tree for CLAUDE.md / AGENTS.md / LESSONS.md returned nothing. The other four surfaces each carry one.

A missing file is worse than a wrong one because nothing announces it — no warning, no failing check, no 404. It just produces an agent working with less context than it believes it has, and no prompt to go looking. It now carries a CLAUDE.md with the corrected hard-stop paths, the public-repo discipline, Sean's execution rules and the operator environment: DealAppSeo/hyperdag-protocol#19.

3. The pointer now exists where an agent lands

Rule 12 names the four surfaces, and LESSONS.md is injected into every XC/GA dispatch — so XC and GA see it. Nobody else does. Measured across all five repos, the string appears in exactly one file. An agent starting in trinity-ecosystem, trustshell or trinity-symphony-shared gets that repo's own guidance and no sign that a cross-surface true north exists.

This adds the read-first table to the top of this file, where every reader of it already arrives:

surface	read first
repid-engine	LESSONS.md, then this file
trinity-ecosystem	CLAUDE.md, then docs/PRIOR-WORK-INDEX.md
trustshell	AGENTS.md (CLAUDE.md is a one-line @AGENTS.md include)
trinity-symphony-shared	CLAUDE.md — lane rules; take a lane before touching a repo
hyperdag-protocol	CLAUDE.md

Each row was verified by reading the named file on that surface — including that trustshell/CLAUDE.md is a single @AGENTS.md line, which is why that row names AGENTS.md and not CLAUDE.md.

This is a table, and tables go stale. It is deliberately the shortest durable thing: five filenames, no verdicts, no dated measurements. It goes wrong only if a surface renames its entry point, which is loud.

Verification

• npm run check → VERIFIED (1 check, 163 markdown files scanned).
• tests/lessons-injectable.test.ts → 10/10 — LESSONS.md is unchanged, so the 6000-character injection cap is untouched. The table went in CLAUDE.md, which has no cap, precisely so the capped file did not have to give something up for it.
• Documentation only; no code paths touched.

NOT CHECKED: whether any other document repeats the bad hard-stop paths. I corrected the two places I measured — this file and the new hyperdag-protocol/CLAUDE.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F3yrSVaGDLirLw4itQJ5wK

---

Generated by Claude Code

[strix-security]

Strix Security Review

No security issues found.

_{Updated for 7f8a653.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[strix-security]

Reviewed PR #686, a documentation-only change to CLAUDE.md. The diff adds a cross-repository "read first" guidance table and corrects hard-stop file paths under hyperdag-protocol/packages/contracts/. No runtime code, configuration, secrets, or security controls were added or modified; the change introduces no attack surface and no actionable security findings.

---

Reviewed by Strix
_{Configure security review settings}

[DealAppSeo]

@strix-security new head 7f8a653 — please re-review.

Correcting a false claim this PR was carrying, rather than merging with it in.

The original body said the read-first table "goes wrong only if a surface renames its entry point, which is loud." That is false, and the counterexample already existed at the moment I wrote it: DealAppSeo/trustrails-dev is live today, is documented in trinity-ecosystem/CLAUDE.md's deployment table, and is not in the table's five rows. The table shipped incomplete.

It also goes wrong when a surface is added, and that failure is silent — the new surface simply is not listed, nothing breaks, and an agent landing there sees no pointer. That is the exact defect this section was written to fix, reintroduced one level up.

The scope is wider than five repos: TrustShell, TrustMarket, TrustRepID, TrustRails, TrustTrader, TrustCRE, TrustEscrow and TrustMedical are all planned on the same HAL / RepID / ERC-8004 / x402 harness, plus third parties building via TrustMarket. A per-repo list of all siblings is N tables of N rows — the hand-maintained jest roots list from Test layout wearing different clothes, and the recorded lesson there is to prefer a discovery rule to a list anywhere this pattern appears.

So this push does three things and deliberately stops short of a fourth:

1. States that the table is not exhaustive and that absence from it must not be read as "that surface has no rules".
2. Names trustrails-dev as already missing, so the gap is a documented fact rather than a surprise.
3. Names the fix — a star, not a mesh: one line per repo pointing at true north, nothing about siblings, no table to rot.
4. Does not apply that refactor here. Whether outside builders get a separate published contract instead of this internal file is Sean's decision. LESSONS.md is capped at 6000 characters because it is a dispatch payload, and it is full of dated retractions a stranger evaluating the ecosystem should not meet first.

The hard-stop path correction — the four Marco De Rossi paths being under packages/contracts/ and not at the repo root — is untouched and correct at any scale.

npm run check VERIFIED · tests/lessons-injectable.test.ts 10/10 · documentation only, no code paths touched.

---

Generated by Claude Code

[strix-security]

Reviewed the only changed file, CLAUDE.md. The PR is documentation-only: it adds a cross-repo "read first" pointer table, clarifies that the table is deliberately non-exhaustive, and corrects the hyperdag-protocol hard-stop file paths from bare root-level names to their actual location under packages/contracts/. No executable code, runtime configuration, secrets, or security-relevant data flows were introduced or modified, so no security findings apply.

---

Reviewed by Strix
_{Configure security review settings}

[strix-security]

Reviewed the single changed file, CLAUDE.md (+47/-1). The diff is documentation-only: it adds a "read first" table listing agent entry points across sibling repositories, documents that the table is intentionally non-exhaustive, and corrects the paths in a "hard stops" list from bare root-level names to their actual packages/contracts/ locations. No code, secrets, injection sinks, authentication/authorization logic, input handling, or runtime behavior is changed. The content does not disclose any actual secrets (the RepID scoring formula and ANFIS parameters are only referenced as items that must not appear in public docs). No security vulnerabilities were introduced or exposed by this PR.

---

Reviewed by Strix
_{Configure security review settings}