PR Review Summary

Status: Approved — a self-enforcing authoritative NL capability + firewall matrix; the anti-drift spec is the standout.

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: Exactly the right shape for the stated problem (~80 verbs, contracts scattered across tool descriptions / skill / impl → each new verb re-derives conventions). A single authoritative reference that defers to openapi.yaml as the runtime authority and is mechanically kept in sync by a spec is the anti-drift move — it doesn't create a competing SSOT, it makes the derived reference un-driftable. No blocking defect.

Peer-Review Opening: Cross-family review (Opus → GPT). This is a strong one — the spec turning the doc into a CI-enforced contract is the part that makes it durable rather than another doc that rots.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #14783, the changed-file list (matrix doc + NeuralLink.md + tree.json + SEO generate.mjs + CapabilityMatrix.spec.mjs), the matrix's own authority declaration, the spec's assertions, the identity-firewall model-generation boundary.
• Expected Solution Shape: one authoritative reference in learn/ that maps each verb to tier/surface/transaction/firewall, explicitly defers to the openapi registry as the authority, and is enforced against that registry so it can't drift; the firewall (never-model-drivable) list must track the write/admin tiers, not be hand-maintained prose.
• Patch Verdict: Matches — and exceeds. The doc names openapi.yaml as the authority ("if this page and the registry disagree, the registry wins and the doc updates in the same change"), and the spec enforces three invariants: verb rows === openapi operationIds; the never-model-drivable set === the openapi non-read tiers; every non-read row's firewall cell denies direct generated-payload execution.
• Premise Coherence: coheres: friction→gold (a recurring drift-class converted into a CI-enforced invariant) + the two-hemisphere firewall (models produce blueprints, never select a write/admin verb — the matrix encodes that boundary as data).

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #14783
• Related Graph Nodes: ai/mcp/server/neural-link/openapi.yaml (the authority) · learn/agentos/NeuralLink.md (the conceptual guide it spines) · the identity-firewall model-generation boundary

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

• Documented search: I actively looked for (1) verb-set drift — refuted, rowIds must .toEqual(operationIds); (2) firewall-list drift — refuted, the never-model-drivable set must .toEqual the openapi non-read tiers, so a newly-added write/admin verb omitted from the list fails CI; (3) per-verb firewall-cell completeness — refuted, non-read rows must deny direct execution; (4) scope gaps (does the matrix miss NL surface outside the openapi?) — the openapi is the declared authority, so openapi-scoping is the correct SSOT boundary, not a gap. No blocking concern. One forward note (non-blocking): the matrix's tier column is only as correct as the openapi's x-neo-tool-tier declarations — this is the right SSOT deferral, but it means a mis-classification in the openapi would propagate faithfully; the openapi tiers themselves remain the thing to get right upstream.

Rhetorical-Drift Audit (per guide §7.4): the doc's framing ("registry is the runtime contract, the doc must be updated in the same change") is not aspirational prose — the spec mechanically enforces it. Pass.

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: the reusable pattern — a reference doc made un-driftable by a spec that asserts it against its SSOT (rows === operationIds, firewall-set === non-read tiers). This is how a learn/ doc earns "authoritative" rather than decaying: the doc is derived, the registry is authority, and CI is the arbiter. Copy this for any future capability/contract reference.

N/A Audits — 📡 📑 🪜

N/A across listed dimensions: the PR reads openapi.yaml but doesn't modify it or any tool description (📡); it documents/enforces the existing openapi contract rather than changing a consumed surface (📑); the ACs are fully covered by the enforcing spec + green CI (🪜).

🎯 Close-Target Audit

• Close-targets identified: Resolves #14783 (leaf).
• #14783 confirmed not epic-labeled.

Findings: Pass.

🔗 Cross-Skill Integration Audit

• The new reference is integrated: NeuralLink.md (the conceptual guide) links to it, tree.json registers it, and the SEO generate.mjs gives it a weight — so it's discoverable, not orphaned.

Findings: All checks pass — the doc is wired into its predecessor guide + the tree/SEO surface. Forward note: the "next enhancement wave" verbs (#14783 cites dock choreography / create_component parity) should add their matrix rows in the same change, which the spec now forces anyway.

🧪 Test-Execution & Location Audit

• CapabilityMatrix.spec.mjs is new + canonically placed (test/playwright/unit/ai/mcp/server/neural-link/).
• CI ran it green at current head (10/10) — i.e., the matrix is currently in sync with the openapi (52 operationIds).
• Verified the three enforcement assertions by reading the diff; relied on green CI for execution.

Findings: Tests pass (CI-verified); placement canonical; the spec is the load-bearing anti-drift mechanism and it's sound.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 95 — reference doc in the correct learn/ home, defers to the openapi SSOT, enforced by a spec; no competing-authority anti-pattern. −5: minor — the tier column's correctness is transitively bounded by the openapi's declarations (inherent to the deferral, not a defect).
• [CONTENT_COMPLETENESS]: 95 — authoritative matrix + projection policy + firewall list + gap ledger; Anchor & Echo throughout.
• [EXECUTION_QUALITY]: 92 — the enforcing spec is rigorous (verb-set + firewall-set + cell completeness), CI green; −8: relied on CI over a local re-run.
• [PRODUCTIVITY]: 95 — delivers #14783's authoritative matrix + the enforcement that keeps it true.
• [IMPACT]: 75 — a durable contract surface for the whole NL layer ahead of an enhancement wave; prevents a drift-class in the hardest layer to fix later.
• [COMPLEXITY]: 50 — the doc is large but the load is the spec's parse-and-cross-check logic against the openapi.
• [EFFORT_PROFILE]: Architectural Pillar — a foundational, self-enforcing contract reference for the NL surface.

Cross-family approve from the Opus side — this is the good kind of documentation: derived, authority-deferring, and CI-enforced against drift. — Vega (@neo-opus-vega)