docs: tighten spec ↔ persona ↔ docs layering (audit-driven)#685
Merged
Conversation
…ase-security Extracts the seven inline review-agent specs from `.agents/lib/pr-review-base.md` into one-file-per-persona under `.agents/personas/`, then collapses Step 5 to a short loop over those files. Pure refactor for the baseline seven: their bodies are copied verbatim (modulo frontmatter), and `pr-review-base.md` shrinks from 271 lines to 196. Adds one new conditional persona, `ci-release-security`, which fires when `<HAS_CI_RELEASE>` is true (diff touches `.github/workflows/**`, `.changeset/**`, `pnpm-lock.yaml`, `.npmrc`, or publish-flow scripts). Covers GitHub Actions workflow injection, action pinning, permissions scopes, secret exposure, publish-flow integrity, lockfile drift. Step 4 grows flag detection for `<HAS_CI_RELEASE>`. The output contract adds `<TOTAL_AGENTS_LAUNCHED>` so the caller's failed-agent report phrases correctly when conditional personas do not fire. Root `AGENTS.md` gets a short pointer to `.agents/personas/` as the canonical inventory of review personas. No new engineering rules. No published package source touched — no changeset needed per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tightens the spec↔persona relationship four ways: 1. Documentation persona now covers Markdown docs and pointer integrity in addition to JSDoc on exports. Validates: stale prose, out-of-sync inventories, cross-doc consistency, internal Markdown link resolution, path references in prose, frontmatter pointers, rename cascade (old paths surviving in other docs), AGENTS.md ↔ persona backlink consistency. 2. AGENTS.md gains §10 "Review automation & CI/release security": the canonical persona inventory plus the source-of-truth rules that ci-release-security enforces (workflow injection, action pinning, permissions scopes, secret exposure, publish-flow integrity, lockfile drift, dependency hygiene, .npmrc hardening). The persona referenced these rules but they were not codified anywhere — now they live in one place and the persona points at the section. 3. Each AGENTS.md §3–8 ends with a `> Applied by personas: …` callout so a rule-author can navigate from rule to enforcer. Pairs with the personas' new `applies:` frontmatter (next item). 4. Persona frontmatter adds `applies:` (AGENTS.md section anchor) and `out-of-scope:` (boundary against neighbor personas) to all eight personas. Documents the scope contract and reduces overlap drift between code-quality / silent-failure-hunter / module-api-architecture / style-conventions. The temporary "Review personas" callout from #682 is replaced by a one-line pointer to §10. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audit-driven cleanup of the documentation architecture surfaced by the last review. Five fixes: 1. test-coverage persona now enforces AGENTS.md §5 colocation (src/Foo.ts ↔ src/Foo.test.ts) instead of describing the obsolete `packages/<pkg>/test/` layout. Captures the dual-layout coexistence rule (colocation wired only in morpho-sdk + evm-simulation today; moving tests in non-wired packages silently skips them) and the *.integration.test.ts naming for fork-bound tests that stay. The incoming TIB-2026-04-27 (PR #596) extends the migration; the rule stays anchored in AGENTS.md §5. 2. module-api-architecture persona: replaced verbatim restatements of AGENTS.md §1/§3/§4/§8 rules (8 bullets) with section pointers and crisp application points. Out-of-scope boundary tightened. 3. style-conventions persona: same fix — replaced verbatim §3/§8 restatements with pointers. Scope sharpened to "mechanical-style enforcement + changeset relevance". 4. code-quality persona: narrowed `applies:` from §1/§3 to §2/§3 so the "Error handling and edge cases" bullet (which overlapped silent-failure-hunter) is replaced by §2's typed-error rule. silent-failure-hunter updated in lock-step: it owns the *depth* of error handling; code-quality owns the *existence* of the typed class. 5. CONTRIBUTING.md: trimmed the duplicated "Code Style" and "Changesets" sections to brief pointers at AGENTS.md §7/§8. The detailed rules live in one place now. Plus housekeeping: - AGENTS.md §10 gains an "Orchestration" sub-table for the three command skills + the shared base, so .agents/lib/pr-review-base.md is discoverable from the inventory. - docs/tibs/TEMPLATE.md footer: removed dangling reference to a non-existent TIB-2026-04-08; added explicit notes that TIBs are proposals feeding into AGENTS.md (not authoritative themselves) and that the repo uses two ID formats (sequential for older TIBs, CalVer for new). No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The test-coverage persona referenced `@morpho-org/test/mock` as if it already shipped on main, but the sub-export lands with the still-open TIB-2026-04-27 (PR #596). Caught by self-applying the documentation persona's pointer-integrity rule. Softened to "lands with TIB-2026-04-27" / "once TIB-2026-04-27 lands" so the persona is accurate against current main and self-corrects when the TIB merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two follow-ups to the architecture refactor. 1. **web3-security persona** rewritten to the new structure (matching what code-quality / silent-failure-hunter / module-api-architecture / style-conventions / test-coverage already use). Was the last persona still in the old "Prompt must include:" bullet-list format. New shape: anchored to AGENTS.md §1 (Action-layer purity) and §2 (chainId validation as a security invariant). Tightened `out-of-scope` boundary against code-quality (which owns generic security primitives per §2) and silent-failure-hunter (which owns generic error swallowing; this persona owns Web3-specific failed-tx surfacing). Structured What-to-flag sections (contract interaction shape, transaction parameter integrity, wallet + chain handling, permit / typed-data, token approvals, race conditions, Action-layer purity) with calibrated severity guidance for this domain. 2. **AGENTS.md §10 + ci-release-security persona** gain a new "Release-commit signing & write-token hardening" rule reflecting the patterns landing in PR #673 (release-bot signing hardening): GitHub- signed identity via `createCommitOnBranch` GraphQL mutation (not local `git commit`); checksum and `$PATH` verification of trusted helpers before minting write-scoped tokens; truncation of `$GITHUB_ENV` / `$GITHUB_PATH` immediately before the privileged step; `.git/hooks/` validated as containing only `*.sample` files; forced trusted `$PATH` and explicit `RELEASE_BRANCH` guard on the write-token step. The rule lives in §10 as source of truth; the persona references it as an anchor. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
0xbulma
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: de2075cef7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Ran the persona-powered /pr-review-local on this branch (8 personas, all
baseline + ci-release-security since HAS_CI_RELEASE=true). The expanded
documentation persona caught 7 cross-doc consistency drifts on its own
author's PR — exactly the kind of finding the persona is designed for.
Aggregated to 6 after dedup (two web3-security findings on adjacent
lines merged — same root cause).
Applied:
1. AGENTS.md §1 (Architecture) — added missing `> Applied by personas:`
backlink. Three personas had `applies: §1` in frontmatter but the
section had no callout linking back.
2. AGENTS.md §2 (Forbidden patterns) — same fix; added missing backlink
for code-quality, web3-security, silent-failure-hunter with per-rule
attributions.
3. AGENTS.md §10 inventory: `code-quality` row had Anchors `§1, §3`, but
the persona's frontmatter and body cite `§2, §3`. Fixed to `§2, §3`.
4. web3-security persona was citing AGENTS.md §2 for the chainId-
validation rule, but that invariant is enumerated in §5 (security
invariants list). Re-attributed:
- frontmatter `applies:` now also names §5
- intro paragraph updated
- "Missing chainId validation" body bullet cites §5
AGENTS.md §5 backlink updated to list web3-security alongside
test-coverage. AGENTS.md §10 table row also updated to add §5.
5. .agents/lib/pr-review-base.md persona inventory was describing the
documentation persona too narrowly ("JSDoc on public exports per
docs/jsdoc-style.md") relative to AGENTS.md §10's expanded
description. Updated to match.
6. AGENTS.md §10 conditional persona table: <HAS_CI_RELEASE> trigger
description was missing the `package.json` `scripts.*publish*` clause.
Added, plus a pointer to pr-review-base.md as canonical detector.
All 6 are mechanical cross-doc consistency fixes; no rules changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Triaged 7 unresolved threads from Codex + Devin with the 'only if
relevant' lens. Applied 5 fixes targeting real drift introduced by
this PR; skipped 1 out-of-scope behavior change; 1 was already
addressed.
Applied:
1. Caller files hardcoded 'of 7 agents' (9 occurrences across
pr-review-{ci,gh,local}.md) — broken now that <TOTAL_AGENTS_LAUNCHED>
is dynamic (8+ when conditional personas fire). Replaced with
'<TOTAL_AGENTS_LAUNCHED>'.
2. module-api-architecture persona's `applies:` was missing §3 even
though the body extensively enforces §3 type-discipline rules at
the boundary. Added §3 to the frontmatter and to the AGENTS.md
§10 inventory row.
3. AGENTS.md §4 backlink listed style-conventions, but that persona
covers Biome mechanics + changesets (§7, §8) — not §4 public-API
packaging. Dropped it from the §4 callout.
4. test-coverage persona recommended mocked transport-level tests as
'preferred', contradicting AGENTS.md §5 ('No mocked viem clients
on RPC paths') because TIB-2026-04-27 has not landed yet. Reworded
to defer to §5 forks today, and clearly mark mock support as
gated on TIB acceptance.
Skipped:
- Codex P2 'Trigger CI persona for dependency edits': would broaden
<HAS_CI_RELEASE> to fire on any package.json dep edit. Legitimate
scenario but a substantive behavior change beyond this PR's
doc-architecture scope, and would flood with no-op runs on every
dep bump. Better as a follow-up that also reviews the trigger
surface holistically.
Already addressed:
- Devin '§1 and §2 have no Applied by personas callouts': fixed in
commit d734a65 (the self-applied /pr-review-local --fix pass).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two targeted additions to /pr-fix's Step 6a project-context reading, catching the gaps that the audit surfaced: 1. CI / release files — when the fix touches .github/workflows/**, .github/actions/**, .changeset/**, lockfiles, .npmrc, or a package.json publish/release script, AGENTS.md §10 is the source-of-truth rule set. The ci-release-security persona enforces these at review time; the same rules govern a fix's correctness. 2. Persona / spec-layering files — when the fix touches AGENTS.md or any file under .agents/personas/, the bidirectional-backlink invariant from the documentation persona applies: every persona's `applies:` frontmatter must match the corresponding `> Applied by personas:` callout in AGENTS.md, and vice versa. A fix to one side must atomically update the other. Both rules were already inherited implicitly via Step 6a's "read root AGENTS.md" line, but making them explicit prevents drift and signals to the fix-applier when a one-side change is incomplete. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Internal contradictions: §2 backlink contradicts the personas it cites. §2 credits silent-failure-hunter for “2 — typed errors”, but that persona’s own body + out-of-scope: explicitly defer the typed-class existence rule to code-quality. Also missing: module-api-architecture for #5 (deep cross-package imports) and test-coverage/web3-security for #6 (mocked viem clients) — “1–4, 7–10” leaves both orphaned. §1 backlink ↔ code-quality.md disagree on early returns. code-quality.md labels “Prefer early returns over nested conditionals” as “not codified in AGENTS.md”, but it’s the last bullet of §1 “Stateless, immutable, composable”. Either add code-quality to §1’s backlink, or drop the “not codified” claim. The dedupe the PR claims wasn’t done for CI/release. Motivation §4 (“personas restate AGENTS.md rules verbatim — sync burden + drift”) is violated twice: <HAS_CI_RELEASE> trigger is restated verbatim in 3 places (pr-review-base.md Step 4, ci-release-security.md Trigger, AGENTS.md §10 table). Pick one canonical (probably Step 4 since it computes the flag) and point at it. |
4 tasks
5 tasks
Rubilmax
pushed a commit
that referenced
this pull request
Jun 1, 2026
docs: resolve PR #686 review comments on current main Rebase the PR #686 documentation changes onto current main and fix the unresolved Devin review comment. - Preserve main's morpho-protocol persona additions while removing the stale silent-failure-hunter §1 backlink. - Add §2 rule 5 to module-api-architecture's body intro and heading, matching its updated frontmatter. - Keep §10 CI/release security pointer wording deduplicated. Co-authored-by: prd-carapulse[bot] <264278285+prd-carapulse[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
After #682 (which extracted personas + added
ci-release-security), four audit rounds surfaced gaps in the documentation architecture:ci-release-securityhad noAGENTS.mdanchor. The persona enforced CI/release rules — workflow injection, action pinning, publish-flow integrity, lockfile drift — but those rules weren't codified anywhere in the spec. The persona was effectively source-of-truth, inverting the layering.documentationpersona only covered JSDoc on exports. Markdown docs (README,AGENTS.md,docs/**,.agents/**) could drift from the code; cross-references could break on file moves; AGENTS.md ↔ persona backlinks could fall out of sync — none of it caught by review.AGENTS.md§3 had no way to find which personas needed updating.code-quality/silent-failure-hunter,module-api-architecture/style-conventions,code-quality/web3-security.test-coveragepersona was out of date — described the obsoletepackages/<pkg>/test/layout while AGENTS.md §5 mandates colocation (src/Foo.ts↔src/Foo.test.ts). Doesn't reflect the incoming TIB-2026-04-27 (PR test: maximize unit-test coverage of SDK packages #596) on transport-level mocking.docs/tibs/TEMPLATE.mdhad a dangling reference to a non-existentTIB-2026-04-08.web3-securitypersona was the last one still in the old "Prompt must include:" bullet-list format — never got the structural refactor the others received.createCommitOnBranch, write-token guards) weren't in §10 — would land without spec backing.Solution
A. Expanded
documentationpersonaOld scope: JSDoc on exported symbols per
docs/jsdoc-style.md.New scope adds:
README.md,AGENTS.md,MISSION.md,CONTRIBUTING.md,SECURITY.md,docs/**,.agents/**, package*.mdfiles. Flags stale prose, out-of-sync inventories, cross-doc consistency drift, code blocks that no longer match the code they describe.applies:,trigger:,canonical-rules:). Rename cascade detection viagit diff --name-status --find-renames.applies:must match the corresponding> Applied by personas: …callout inAGENTS.md. Dangling anchors and one-way pointers are findings.B. New
AGENTS.md§10 — Review automation & CI/release securityapplies:columns linking each persona back to spec..agents/commands/pr-review-{ci,gh,local}.md) + the shared base (.agents/lib/pr-review-base.md) — the full review-automation stack is now discoverable.pull_request_target+ checkout restriction, ACL-gated comment triggers, action pinning,permissions:block, secret exposure, publish-flow integrity, Changesets/release-bot wiring, lockfile drift, dependency hygiene,.npmrchardening, and (commitde2075ce) release-commit signing & write-token hardening (informed by PR ci(release): sign and harden release automation #673).ci-release-securityreferences §10 instead of being authoritative on its own.C. Backlinks in
AGENTS.md§3–8Each existing section ends with a
> Applied by personas: …callout. Pairs with the newapplies:frontmatter for bidirectional navigation.D. Persona frontmatter
applies:+out-of-scope:All 8 personas declare
applies:(spec anchor) andout-of-scope:(boundary against neighbors).E. Persona dedupe (audit-driven)
module-api-architecture— 8 verbatim restatements of AGENTS.md §1/§3/§4/§8 replaced with section pointers + crisp application points.style-conventions— verbatim §3/§8 restatements replaced with pointers. Scope sharpened to "mechanical-style enforcement + changeset relevance".code-quality+silent-failure-hunterboundary sharpened:code-qualityowns existence of typed error classes (§2);silent-failure-hunterowns depth of error handling.code-quality.applies:shifted from §1/§3 to §2/§3.web3-security(last persona in the old format) — rewritten with structured What-to-flag sections (contract interaction shape, transaction parameter integrity, wallet/chain handling, permit/typed-data, token approvals, race conditions, Action-layer purity), severity guidance calibrated for the domain, sharpenedout-of-scopeboundary againstcode-quality(which owns generic security primitives).F.
test-coveragerewrite — colocation enforcerReflects AGENTS.md §5: new unit tests live next to source (
src/Foo.ts↔src/Foo.test.ts). Two layouts coexist (colocation wired inmorpho-sdk+evm-simulationtoday; olderpackages/<pkg>/test/layout elsewhere). Fork-bound tests use*.integration.test.tsnaming. Refactor-driven migration path documented. Forward-reference to@morpho-org/test/mockmarked as "lands with TIB-2026-04-27" (PR #596).G. CONTRIBUTING.md trim
"Code Style" + "Changesets" sections collapsed to brief operational quick-reference + pointers to
AGENTS.md§7/§8.H. Housekeeping
docs/tibs/TEMPLATE.mdfooter: removed danglingTIB-2026-04-08reference; added explicit notes that TIBs are proposals feeding into AGENTS.md (not authoritative themselves) and that the repo uses two ID formats (sequential for older TIBs, CalVer for new).Audit verdict on the rest of the repo
Spawned an Explore agent to survey docs not covered by the rounds above:
AGENTS.md(16 packages), nestedAGENTS.mdundermorpho-sdk/src/, package READMEs,ARCHITECTURE.md,BUNDLER3.md, remaining.agents/commands/*(pr-create,pr-describe,pr-fix,extract-plan,verify-dependency-vulnerability).Scope discipline
CLAUDE.md§7.Status: Proposed(live decisions, not stale).test/→ colocation migration for non-wired packages,extract-plan.mdTeam-IDs table (gated on Linear integration).Test plan
> Applied by personas: …callout inAGENTS.mdlinks to a real file (verified — 8/8 resolve).applies:line cites a realAGENTS.mdsection (verified — 8/8 frontmatter + 7 backlinks consistent).../../AGENTS.md,../../MISSION.md) resolve from.agents/personas/(verified).documentationpersona body references files that exist (docs/jsdoc-style.md,.agents/lib/pr-review-base.md— verified). Forward-references to@morpho-org/test/mockcorrectly marked as incoming./pr-review-localon this branch — eat our own dogfood; the expandeddocumentationpersona should find no pointer drift, and the newweb3-security/ci-release-securityrule structures should produce findings cleanly. (Done — see follow-up commit if fixes applied.)Commit history
8a6b8ff2300cfbe621f6ae12@morpho-org/test/mocksoftenedde2075ce/pr-review-local --fixon this branch)🤖 Generated with Claude Code
View Slack thread