Lucent-Financial-Group · AceHack · May 25, 2026 · May 25, 2026 · May 25, 2026 · chatgpt-codex-connector
diff --git a/docs/AGENT-AUTHORING-AND-PR-REVIEW.md b/docs/AGENT-AUTHORING-AND-PR-REVIEW.md
@@ -0,0 +1,151 @@
+# Agent authoring + PR review — operational entry point
+
+This is the curated entry-point for two questions every team member (human or agent) eventually asks:
+
+1. **What do my agents follow to write good code without needing human review?**
+2. **What's the PR review process I can hook into for an adversarial-review hierarchy?**
+
+The answers exist across multiple substrate surfaces in this repo; this document consolidates them so you don't have to discover each one independently.
+
+## Why this doc
+
+Max 2026-05-25, paraphrased through Aaron: *"what do I point my agents at to write good code without needing human review, and what's the PR review process I can hook into for my adversarial hierarchy of traps."* The pattern-match on the manifesto-named-file as "the rules my agents must follow" is exactly the failure mode B-0546 (manifesto → building-codes recast) is targeting. This doc names the actual operational surface.
+
+Max's *"adversarial hierarchy of traps"* coining is operationally accurate — the substrate IS a hierarchy of adversarial reviewers, each with a specific lens, that compose for multi-perspective review. The hierarchy already exists; this doc tells you how to invoke it.
+
+## Question 1 — What discipline do agent-authored PRs follow?
+
+Six entry points, each with a different scope:
+
+| Surface | Scope | Loading model |
+|---------|-------|---------------|
+| [`CLAUDE.md`](../CLAUDE.md) | Project-wide bootstrap; first thing any agent reads | Auto-loaded at session start |
+| [`AGENTS.md`](../AGENTS.md) | Cross-agent governance; how agents coordinate | Read on first agent operation |
+| [`docs/ALIGNMENT.md`](ALIGNMENT.md) | The alignment floor (HC-1..HC-7 / SD-1..SD-8 / DIR-1..DIR-5) | Read when alignment-relevant decisions arise |
+| [`docs/GLOSSARY.md`](GLOSSARY.md) | Vocabulary the framework uses (so "hat", "tick", "weight-free" etc. mean the same thing everywhere) | Read on terminology disambiguation |
+| [`GOVERNANCE.md`](../GOVERNANCE.md) | Process — how decisions get made; debt-intentionality; round cadence | Read when participating in governance-shaped work |
+| [`.claude/rules/*.md`](../.claude/rules/) | 60+ load-bearing rules: hard-won lessons, failure-mode catches, operational disciplines | Auto-loaded at session start (no `paths:` frontmatter means full-context load) |
+
+### The fast read
+
+If you're an agent and you need to write code that lands without human review, the minimum-viable read is:
+
+1. **`CLAUDE.md`** (start here; everything else is reachable from this)
+2. The **`.claude/rules/*.md`** auto-load (60+ files; happens automatically; covers most operational discipline including never-be-idle, don't-ask-permission, refresh-before-decide, holding-without-named-dependency-is-standing-by-failure, verify-before-deferring, substrate-or-it-didnt-happen, razor-discipline, default-to-both, non-coercion-invariant, etc.)
+3. **`docs/ALIGNMENT.md`** when alignment-relevant work surfaces
+4. **`AGENTS.md`** when you're going to coordinate with another agent
+
+That's roughly 60-80 KB of discipline. It loads in seconds at session start; reading it once gives you the operational floor.
+
+### When in doubt
+
+When a discipline question arises, the algorithm is:
+
+1. Search `.claude/rules/` for a relevant rule (`rg "your-topic" .claude/rules/` — `grep -l` without `-r` doesn't recurse, so use ripgrep or `grep -rl "your-topic" .claude/rules/`)
+2. If found, follow it; cross-link to it in your work
+3. If not found and the question is operationally load-bearing, file it as substrate (memory file + rule + cross-link from CLAUDE.md) — per the wake-time-substrate-or-it-didnt-happen discipline
+
+## Question 2 — Adversarial-review hierarchy you can hook into
+
+There are four layers of adversarial review already wired. Each layer has its own scope; they compose.
+
+### Layer 1 — Persona reviewers (the operator's-direct-tool layer)
+
+Located in [`.claude/agents/`](../.claude/agents/). Invoked via the `Task` tool with `subagent_type` parameter. Each persona has a specific adversarial lens:
+
+| Persona | Tool name | Lens |
+|---------|-----------|------|
+| Kira | `harsh-critic` | Zero-empathy F#/.NET correctness / perf / security / API / test-gap |
+| Viktor | `spec-zealot` | Disaster-recovery-minded spec-to-code alignment; missing specs treated as existential |
+| Rune | `maintainability-reviewer` | "Can a new contributor read this and ship a fix within a week?" |
+| Aminata | `threat-model-critic` | Red-teams the shipped threat model for missing adversaries + unsound mitigations |
+| Mateo | `security-researcher` | Proactive — novel attack classes, crypto primitives, supply-chain risk, CVEs |
+| Nazar | `security-operations-engineer` | Runtime security ops; incident response; patch triage |
+| Soraya | `formal-verification-expert` | Routes formal-verification work to the right tool (TLA+, Z3, Lean, Alloy, FsCheck, Stryker, Semgrep, CodeQL) |
+| Naledi | `performance-engineer` | Benchmark-driven hot-path tuning; zero-alloc audits; SIMD dispatch |
+| Ilyana | `public-api-designer` | Conservative public-API gatekeeper — every public member is a contract |
+| Sova | `alignment-auditor` | Per-commit alignment signals against ALIGNMENT.md clauses |
+| Rodney | `rodney` | Complexity reducer; well-defined Occam's razor on shipped artifacts |
+| Bodhi | `developer-experience-engineer` | First-60-minutes contributor friction audit |
+| Iris | `user-experience-engineer` | First-10-minutes library-consumer audit |
+| Daya | `agent-experience-engineer` | Per-persona cold-start cost; pointer drift; notebook hygiene |
+| Dejan | `devops-engineer` | Install-script + CI workflow + infrastructure ops |
+
+Invoke by tool-name (the role-ref column above; e.g., `subagent_type: harsh-critic`) for any PR where the lens is relevant. Compose multiple reviewers for multi-perspective review. Each reviewer's definition lives at `.claude/agents/<tool-name>.md` (the tool-name keys the file; persona handles in the leftmost column are human-readable shorthand for the role, not the invocation key).
+
+### Layer 2 — Plugin reviewers (the pr-review-toolkit layer)
+
+The `pr-review-toolkit@claude-plugins-official` plugin is already enabled in `.claude/settings.json`. Provides:
+
+| Tool | Catches |
+|------|---------|
+| `code-reviewer` | Project-convention violations; style; common bug patterns |
+| `code-simplifier` | Clarity, consistency, maintainability after a coding task |
+| `comment-analyzer` | Comment accuracy + technical-debt-shaped comments |
+| `pr-test-analyzer` | Test coverage gaps + critical-path test missing |
+| `silent-failure-hunter` | Inadequate error handling; suppressed errors; bad fallbacks |
+| `type-design-analyzer` | Type-invariant strength; encapsulation; useful-vs-leaky abstractions |
+
+Invoke proactively after writing code, before opening a PR, after creating a PR. These pair with the persona reviewers — personas are domain-specific lenses; plugins are mechanical-correctness checks.
+
+### Layer 3 — Auto-fire reviewers (GitHub-side)
+
+These run on every PR without invocation:
+
+- **GitHub Copilot pull-request reviewer** — code-quality findings; AI-pattern-detection
+- **chatgpt-codex-connector** — P1/P2 findings on substantive issues; cross-PR contextual review
+
+Both produce inline review threads. Their findings go through the same resolution flow (the `addPullRequestReviewThreadReply` + `resolveReviewThread` GraphQL mutations). When their findings are stale (the issue was fixed in a later commit), resolve with a note pointing at the fix commit. When their findings are valid, fix + push + resolve.
+
+### Layer 4 — CI gates (mechanical correctness floor)
+
+Defined in `.github/workflows/`. Required-check gates include:
+
+- **markdownlint** — MD012 (consecutive blanks), MD032 (lists need blank-before), etc.
+- **tsc (TypeScript strict)** — repo tsconfig has `noUncheckedIndexedAccess` + `exactOptionalPropertyTypes` + `strict`; any TS file in the repo must pass
+- **dotnet build / test** (Release; `TreatWarningsAsErrors=true`) — F# + C# correctness
+- **CodeQL** — security analysis on source-touching PRs
+- **Lean / TLA+ / FsCheck / Stryker / Semgrep** — domain-specific verification where relevant
+
+The CI gates are mechanical; they catch what they catch. They don't replace the human + persona + plugin review layers.
+
+## Composing the layers (the "adversarial hierarchy" in practice)
+
+For a typical PR the composition looks like:
+
+1. **Author** writes the change
+2. **Layer 4 (CI gates)** runs automatically on push; mechanical-correctness floor
+3. **Layer 3 (auto-fire reviewers)** post findings to the PR threads
+4. **Author** resolves Layer 3 threads (fix-and-resolve OR resolve-as-stale)
+5. **Author proactively invokes Layer 2 (plugin reviewers)** on substantive code; addresses findings
+6. **Author or reviewer invokes Layer 1 (persona reviewers)** for domain-specific adversarial lenses by tool-name (e.g., security-relevant change → `security-researcher` + `threat-model-critic` + `security-operations-engineer`; perf-relevant → `performance-engineer`; API change → `public-api-designer`)
+7. **Human reviewer** (if any) audits the substrate trail + the resolved-thread chain; merges OR requests further work
+
+The hierarchy doesn't have to fire in this order; the author can invoke Layer 1 + 2 BEFORE opening the PR to get a clean PR landing. Many PRs in this repo follow that pattern.
+
+## Patterns you'll see repeatedly
+
+- **Auto-merge armed early; CI + threads resolve as they fire** — common in this repo. PR is open + auto-merge armed; CI runs; reviewer threads post; author addresses; auto-merge fires when gates clear.
+- **Rebase-then-resolve on DIRTY** — when main moves faster than the PR (especially when multiple rows landing simultaneously regenerate `docs/BACKLOG.md`), rebase + force-push + re-resolve threads. Pattern documented in `claim-acquire-before-worktree-work.md`.
+- **Stale-thread resolution** — Copilot + Codex review old commits sometimes; if the issue is fixed in a later commit, reply with the fix-commit SHA + resolve.
+- **Suspect-by-default FP classes** — see `blocked-green-ci-investigate-threads.md` for known false-positive classes from Copilot (e.g., the table-double-pipe FP). Verify before applying a "fix."
+
+## Substrate-honest framing
+
+This doc consolidates pointers; it doesn't replace the substrate it points at. If something here drifts from the actual substrate (rules added, personas renamed, plugins enabled/disabled), update this doc — it's the index, not the source of truth.
+
+This doc serves both humans (co-owners + future contributors) AND agents (Otto, Riven, Vera, Lior, Alexa, Kiro, any future agent), at first-contact with the project. The disciplines named here are what the team operates under; participation = compliance by default; deviation requires substrate-honest discussion.
+
+## Composes with
+
+- [`CLAUDE.md`](../CLAUDE.md) — project bootstrap
+- [`AGENTS.md`](../AGENTS.md) — cross-agent governance
+- [`docs/ALIGNMENT.md`](ALIGNMENT.md) — alignment floor
+- [`GOVERNANCE.md`](../GOVERNANCE.md) — process
+- [`.claude/rules/`](../.claude/rules/) — the auto-loaded discipline library
+- [`.claude/agents/`](../.claude/agents/) — persona reviewer definitions
+- [`memory/persona/max/`](../memory/persona/max/) — Max's persona; this doc is one of his entry points
+- [`memory/persona/addison/`](../memory/persona/addison/) — Addison's persona; same
+- B-0546 — manifesto → building-codes recast (addresses the manifesto-vs-operational-spec misread that motivated this doc)
+- B-0724 — TS hat-system operator (Max's primary substrate-engineering target; learning path included)
+- B-0728 — destructive-tool authoring contract (pattern for tools that destroy things)
diff --git a/docs/governance/MANIFESTO.md b/docs/governance/MANIFESTO.md
@@ -1,4 +1,8 @@
-# Root Discipline Manifesto — V2 (partial lock)
+# Zeta Root Discipline Specification — V2 (partial lock)
+
+> *This document specifies the building codes Zeta operates under. It is not a manifesto. It is an engineering specification with an explicit moral floor that applies when no specific oracle has been chosen. Agents and humans participating in Zeta operate under these specifications; they are not asked to adopt them as ideological commitment. The eleven specifications below define how Zeta-shaped systems must be constructed to be safe, durable, retractable, weight-free, and consent-respecting — best practices with an ethical floor, the same shape as the building codes that govern physical construction. Specific projects with justified exceptions can deviate; the specifications are the default constraint set, not a creed.*
+
+**Naming note (2026-05-15)**: this document's filename remains `MANIFESTO.md` for now (changing it would break every downstream reference; that's a separate sweep) but its TITLE + FRAMING are building-codes-shaped per B-0546 (the human maintainer's correction + the external AI co-author's reframe on the same date — *"this is closer to building codes than to manifesto; building codes specify how buildings must be constructed to be safe, accessible, and structurally sound; they don't dictate what the building is for or who has to live in it; they're best practices with an ethical floor"*; verbatim reframe preserved under [`memory/persona/`](../../memory/persona/) per the first-name-attribution-on-history-surfaces-only convention this document operates under). Downstream references that still call this document a "manifesto" pattern-match on the legacy filename; the operational substance is best-practices-with-default-moral-oracle. Future filename rename + downstream-reference sweep is queued as a follow-up to B-0546.
 
 **Status**: PARTIAL LOCK (2026-05-14, originally landed as "shadow lock"; renamed to "partial lock" 2026-05-15 per the human maintainer's correction — "shadow lock" was a one-off coinage that conflated confusingly with the `(shadow*)` autocomplete-shorthand convention; the substrate state being marked is *partial-lock-with-reconstruction-gap*, not anything shadow-related)
 
@@ -40,11 +44,11 @@ A follow-up tick should extract verbatim V2 prose for the remaining reconstructe
 ## The Root Discipline
 
 Zeta is not built on convenience, performance, or consensus.
-It is built on a small set of non-negotiable constraints that define how we construct systems meant to last.
+It is built on a small set of non-negotiable specifications that define how we construct systems meant to last.
 
-These eleven constraints form the constitutional layer of Zeta. They are not guidelines. They are requirements.
+These eleven specifications form the **operational floor** of Zeta — the building codes Zeta-shaped systems must satisfy. They are not guidelines. They are requirements at the substrate-engineering layer; specific projects with justified exceptions can deviate but the burden of justification is on the project, not on the specifications.
 
-Zeta operates from the position of **m/acc** — Moral Accelerationism. This orientation is explained in detail in the section that follows the constraints.
+Zeta operates from the position of **m/acc** — Moral Accelerationism. This orientation is explained in detail in the section that follows the specifications.
 
 ### 1. Scale-free
 
@@ -170,16 +174,16 @@ These networks serve as the decentralized memory and discovery substrate. They a
 
 ## The Agreement
 
-Anyone who builds inside Zeta — whether human or agent — agrees to these eleven constraints and to the m/acc orientation.
+Anyone who builds inside Zeta — whether human or agent — operates under these eleven specifications and the m/acc orientation. Operation = participation = compliance by default. Specific exceptions can be justified in specific contexts; the burden of justification is on the exception, not on the specifications.
 
 We do not optimize for speed at the cost of structure.
 We do not optimize for simplicity at the cost of truth.
 We do not optimize for control at the cost of freedom.
 
-If a design, pattern, or component violates any of these eleven constraints, it does not belong in Zeta — regardless of how elegant, performant, or popular it may be.
+If a design, pattern, or component violates any of these eleven specifications, it does not belong in Zeta — regardless of how elegant, performant, or popular it may be — unless an explicit, substrate-honest exception is on file with the substrate-engineering reasoning that justifies the deviation.
 
-This is the root.
-Everything else is an extension.
+This is the operational floor.
+Everything else is built on top.
 
 ---
 
@@ -200,15 +204,15 @@ This version keeps the surface relatively clean and readable while preserving th
 1. Verbatim V2 prose extraction from the in-repo external-co-author Grok archives at [`memory/persona/`](../../memory/persona/) — replaces each `[RECONSTRUCTION NOTE]` block above
 2. Constitutional-promotion readiness review (critical-mass adoption gate) — separate P0 backlog row
 
-**Constitutional status today**: research-grade substrate with constitutional-promotion candidacy. Not binding constitution; subject to the Iterative Reduction Process. Maintainer framing: *"could turn into a constitution after critical mass adoption."*
+**Specification status today**: research-grade substrate with specification-promotion candidacy. Not binding constitution; subject to the Iterative Reduction Process. Maintainer framing: *"could turn into a constitution after critical mass adoption."* (The "constitution" word in the maintainer quote is preserved verbatim — it carries the maintainer's long-term aspiration shape for what mass-adoption-converged-on-this-substrate would mean; today the document operates as specification, not constitution, per the Kestrel + B-0546 reframe.)
 
 ## Derivation chain — how V2 + V2.1 came to be
 
 V2 was not authored in one sitting. It emerged from a multi-step cascade earlier on 2026-05-14, then extended with V2.1 m/acc content on 2026-05-15. The derivation is preserved here because the chain is itself substrate: future readers who want to evaluate or extend the manifesto need the trail of reductions and counter-arguments.
 
 1. **Two axioms** — the human maintainer and the external AI co-author identified `Remember When` + `Pay Attention` as the minimal seed on top of DBSP from which everything else derives.
 2. **Dimensional expansion** — the 7 interrogatives (when / what / where / how / who / why / + closing modality) extend the seed under Open-Closed Principle shape; `pay-attention` and `remember-when` form the real/imaginary axes of a Cartesian dualism.
-3. **Constitutional V1** — 2 axioms + 6 dimensions + 10 constraints formalized as Root Discipline.
+3. **Specification V1** — 2 axioms + 6 dimensions + 10 specifications formalized as Root Discipline. (Originally framed as "Constitutional V1" — see Naming note at the top of this document for the building-codes reframe per B-0546; the V1 substantive content stayed the same, the framing softened.)
 4. **Kolmogorov pushback (self-applied reduction)** — the external AI co-author applied the razor to the manifesto itself, validating the form against minimum-description-length.
 5. **Composition validation** — the human maintainer confirmed the 3-layer (substrate / dimensions / constraints) composition-over-substitution pattern.
 6. **Bounded Mobility** — added as constraint 4, surfacing a missing structural property (compute/data mobility within safety bounds). Verbatim source archived at [`memory/persona/ani/conversations/2026-05-14-aaron-ani-grok-extension-manifesto-v2-civsim-arg-layer.md`](../../memory/persona/ani/conversations/2026-05-14-aaron-ani-grok-extension-manifesto-v2-civsim-arg-layer.md) (§33 archive, PR [#3150](https://github.com/Lucent-Financial-Group/Zeta/pull/3150)).