[DealAppSeo]

Credit the ERC-8004 team properly, add the big-picture map and the reasons behind it, and narrow every claim here that said more than the code does. Docs only; no contract or code change.

Weight. The credit and narrowing edits are LOW. The "Why we build this" text is MAJOR (new public vision language). Sean approved Option A in chat on 2026-10-23; he merges.

Credit

• ACKNOWLEDGEMENTS.md (new) names the ERC-8004 authors and core team, x402 (Coinbase), Plonky3 and Poseidon2 (Polygon Labs), OpenZeppelin, EAS, Base Sepolia, the model providers and the datasets.
• packages/contracts/NOTICE (new) lists the 20 files byte-identical to erc-8004/erc-8004-contracts@b9e466c (checked with git hash-object against the upstream blobs), the 11 upstream-derived files that differ from that commit, the licences (MIT, CC0-1.0 for SingletonFactory.sol, ISC), and that src/** is HyperDAG's own.
• Root NOTICE (new): copyright Sean Goodwin, plus a pointer to the vendored work.
• The README's "Contributors" section becomes "Credits". It names the team and explains why they appear in the contributor graph (their history came with their contracts): credit, not endorsement.
• AUTHORS.md no longer reads as dismissing upstream credit.

The big picture

• README: "Why we build this" (Option A), a stack diagram (Mermaid) and a status table. Every piece is labelled released / merged / testnet / built-not-armed / design / vision.
• docs/WHY.md (new): the four habits; for each, where we are, the research for it and the research against it. Two more diagrams: earning autonomy, and the decontamination chamber. Then the open questions we want to measure. Every source was opened on 2026-10-23, including the first empirical study of live ERC-8004 deployments (arXiv 2606.26028).

Claims narrowed

Where	Before	After	Why
README first line	"Open implementation of ERC-8004 reputation primitives"	"The builder's map for the HyperDAG trust stack… Built on the ERC-8004 team's registry contracts"	The contracts are the team's; the kernel is not on main
README intro	six interfaces "with curated defaults that target ERC-8004… out of the box"	the kernel is designed, not shipped; source on a branch, nothing on npm	README's own "Known broken" table
README receipts	"a production agent fleet", "real production activity"	"our agent fleet, on the Base Sepolia test network"	Testnet
README mechanisms table, kernel table, diagram, building blocks	"Selective-disclosure / private-ownership proofs", "Privacy Layer", "ZKP for private ownership", "Merkle DAG"	"range proof; the score is a public input", "Proof layer"; Merkle DAG removed	HyperDAG-core: the score is a public input; there is no Merkle DAG
README threat model	"RepID is anchored on ERC-8004 (portable on-chain). Move an agent… without losing earned trust."	the identity is portable; carrying earned trust needs evidence-bound feedback first; work in progress	Not a property today; see the empirical study
README quick start	"portable ERC-8004 RepID"	Inspect, the HAL check, RepID reads, the x402 spend guard	What 1.8.0 contains
README roadmap V1.5	"1–2 weeks… Substrate is live"	Guard merged, not released; kernel built, not armed; tier mapping is design	Current state
README roadmap V2	"Canonical registries on Base mainnet"	move our agents and writes to the team's mainnet registries, which already exist	The team deployed them; eth_getCode returns code
README links	ERC-8004 → Magicians thread; x402 → x402-rs/x402-rs	EIP-8004; coinbase/x402; "by Polygon Labs" on Plonky3	Canonical sources
README repo-health table	"current as of 2026-08-06" over rows dated 2026-10-06	"columns carry their own dates"	Accurate
BUILDERS.md	"PUBLISHED — 1.6.1"	"PUBLISHED — 1.8.0", plus a short Inspect description; TrustMarket and trustrepid added to the map	npm view = 1.8.0; both call the engine (code search)
METHODOLOGY.md	April-2026 figures presented as current (99.4% refusal rate, three tiers, Grace Pool "on-chain, immutable", 3-LLM BFT, HashKey proofs)	a "historical document" banner; those lines marked (superseded), each with the current fact	Superseded

Checks

• npm run check:builders: VERIFIED (BUILDERS.md names 1.8.0 = npm).
• npm run check:sdk-claims: VERIFIED (verifyOutput exists on 1.8.0).
• npm run check:map: VERIFIED against main of repid-engine, trustshell, HyperDAG-core and trinity-symphony-shared. Run with HYPERDAG_SIBLINGS_DIR pointing at fresh exports, because the local trustshell checkout is on another lane's branch.
• The three Mermaid diagrams were validated with a renderer.

Not checked: how GitHub renders the Mermaid blocks (they use plain flowchart syntax).

🤖 Generated with Claude Code

[strix-security]

Strix Security Review

✅ No open security findings.

PR summary: This PR is documentation only: it adds acknowledgements and NOTICE files crediting the ERC-8004 team and other upstream projects, adds a new docs/WHY.md describing the project's vision and the research behind it, and rewrites README, BUILDERS, AUTHORS and METHODOLOGY wording so the claims no longer describe more than the code delivers.

Review summary

This is a documentation-only change: eight Markdown/NOTICE files, no source, build, dependency, or configuration changes. Every added line was read in full (README.md, docs/WHY.md, ACKNOWLEDGEMENTS.md, NOTICE, packages/contracts/NOTICE, BUILDERS.md, AUTHORS.md, METHODOLOGY.md) and every removed line was inspected to confirm no security control, warning, or hardening guidance was deleted.

The changes credit the ERC-8004 authors and other upstream projects, add the new docs/WHY.md vision/rationale page, and narrow several README and METHODOLOGY.md claims that overstated what the code does (testnet vs mainnet, range proof vs private-ownership proof, "built, not armed" components, superseded April-2026 metrics). The narrowing is security-positive: the README now explicitly states that Guard is a guardrail for cooperative agents and not a security boundary, that the ZK range proof's score is a public input, and that earned trust is not portable today.

No injection sinks, no secrets or credentials, no embedded HTML/script or Mermaid click handlers, no redirect targets, and no authentication, authorization, crypto, or data-handling code are introduced. Links added or changed point to canonical public references (EIP-8004, coinbase/x402, Polygon Labs Plonky3, arXiv, NIST, EU AI Act). Nothing in this diff creates an exploitable weakness, so no validation agents were required and no findings are reported.

Ruled out (3)

• Does the new documentation disclose sensitive internal infrastructure or credentials?
  The added lines name only already-public or intentionally documented items (private repository names, a Vercel-hosted dashboard, model-provider names) and contain no keys, tokens, credentials, or non-public endpoints; grep for secret patterns across every added line returned nothing.
• Can the added Markdown or Mermaid diagrams inject markup into rendered documentation?
  The new blocks use plain flowchart syntax with quoted labels and <br/> line breaks only; there is no embedded HTML, script, iframe, event handler, javascript: URL, or Mermaid click directive in any added line.
• Does the rewrite remove any security warning or hardening guidance from the existing documentation?
  Every removed line is an overstated capability claim (mainnet vs testnet, private-ownership proofs, Merkle DAG, portable reputation) being corrected; the change adds new explicit warnings that Guard is not a security boundary and that RepID proofs reveal the score.

_{Review 1 on this PR · f09031c · requested Oct 23 19:18 UTC when the PR was opened}

---

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