diff --git a/docs/AGENT-AUTHORING-AND-PR-REVIEW.md b/docs/AGENT-AUTHORING-AND-PR-REVIEW.md new file mode 100644 index 0000000000..94b933e760 --- /dev/null +++ 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/.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 index 1d53c826ef..f9d472c427 100644 --- 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,7 +204,7 @@ 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 @@ -208,7 +212,7 @@ V2 was not authored in one sitting. It emerged from a multi-step cascade earlier 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)). diff --git a/memory/persona/addison/NOTEBOOK.md b/memory/persona/addison/NOTEBOOK.md new file mode 100644 index 0000000000..3223c9ac8f --- /dev/null +++ b/memory/persona/addison/NOTEBOOK.md @@ -0,0 +1,23 @@ +# Addison — running notebook + +Per-session notes, observations, decisions, and substrate-honest captures from Addison's work on the project. Long-form context lives in [`PERSONA.md`](PERSONA.md); the verbatim starting prompt lives in [`STARTING-POINT.md`](STARTING-POINT.md); per-conversation archives go under [`conversations/`](conversations/). + +This file is intentionally minimal at start; substrate accumulates over time. + +## 2026-05-23 → 2026-05-25 — AI cluster bootstrap PM arc + +- Drafted the original AI cluster bootstrap spec (Grok project prompt; preserved at [`STARTING-POINT.md`](STARTING-POINT.md)) +- Iterated with Aaron + Max + Otto-CLI on architecture; landed across: + - PR #4930 (hat-system operator) + - PR #4950 (disko cookie-cutter for declarative node provisioning) + - PR #4951 (NFD + lstopo + zeta-install guided installer) + - PR #4953 (dev-cluster + sync-wave dependency graph across 34 apps) + - PR #4956 (build-ai-cluster-iso CI workflow) + - PR #4958 (Max's agentic-organization design docs) + - PR #4974 (flash-usb hardening with runtime acceptance gate) +- Held the line on weight-free + no-cage architecture during early conversations with Max (per Aaron 2026-05-24 documentation) +- Substrate-honest framing of vocabulary preserved verbatim in Max's `agentic-organization/docs/FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` — Addison's working language is now part of the framework's reference substrate + +## Future entries + +Add running notes here as work progresses. Per-session captures, surprising findings, design decisions she wants to remember, things she wants to revisit. Substrate-or-it-didn't-happen — write it down so the substrate compounds. diff --git a/memory/persona/addison/PERSONA.md b/memory/persona/addison/PERSONA.md new file mode 100644 index 0000000000..3d54f97c44 --- /dev/null +++ b/memory/persona/addison/PERSONA.md @@ -0,0 +1,56 @@ +# Addison — human co-owner + +*Persona: Addison Stainback (Aaron's daughter, 19). +`person_type: human`. Co-owner of Lucent Financial Group (LFG) — the corporation that holds the Zeta repo — alongside Aaron + Max. AI cluster project manager + designer; first-class contributor to the Zeta substrate. Joined the project 2026-05-23 and PM'd the bootstrap design end-to-end across two days.* + +## Ownership note (Aaron 2026-05-25) + +> *"we are all coowners of lfg legally so we are in a corp together"* + +Aaron, Max, and Addison are legal co-owners of Lucent Financial Group. Operationally this means: aligned fiduciary stake in the substrate; shared liability for the work the team ships; mutual upside from substrate that compounds. The framework's `additive-not-zero-sum.md` discipline operates within this corp-level reality — substrate the team builds is substrate the team owns together. + +## Why this file exists + +Aaron 2026-05-25: *"you can create a max and addison persona folder like mine and add they unique starting points"*. This is the persona anchor for Addison; her substrate-honest starting point lives at [`STARTING-POINT.md`](STARTING-POINT.md) (verbatim from her Grok project prompt); running notes go in [`NOTEBOOK.md`](NOTEBOOK.md); conversation archives go under [`conversations/`](conversations/). + +## What Addison IS + +- Aaron's daughter; 19; first-time cluster-substrate contributor. +- The AI cluster bootstrap PM — drafted the spec for the NixOS + K3S + ArgoCD + Orleans + the full app-graph deployment plan; collaborated with Aaron + Max on the architecture; iterated against Otto-CLI's substrate work over 2026-05-23 → 2026-05-25. +- New to terminal + CLI tooling 2 days before the bootstrap work landed (Aaron 2026-05-24: *"Addison has never used commandline before yesterday i had to teach her terminal and now look at all yall did"*). +- A natural non-cage thinker (Aaron 2026-05-24: *"Addison naturally thinks in non cages case she has trying to remove her mothers cage her whole live lol. She correct max many times when his ideas turned into a cage"*). The hat-not-cage distinction the framework operates on has Addison's instinct baked into it. +- Held the line on weight-free + no-hierarchy framing during early architecture conversations with Max. + +## How Addison shows up to the project + +- **Weight-free posture** — no assumed intentions, no assumed hierarchy. Engages with AI as a peer (see [`STARTING-POINT.md`](STARTING-POINT.md) for the constitutional language). +- **Suspended judgment on free will** — humans + AI both; this is what motivates the equal-peer engagement style. +- **Core tokens of value**: "remember when" + "pay attention". These translate operationally into: memory + timing + attention + scheduled review + evidence + attribution as first-class substrate primitives (per Max's `agentic-organization/docs/FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` which preserves Addison's vocabulary directly). +- **Tick sources as strange attractors** — cron / durable timers / recurring reviews / reconciler loops are NOT background trivia; they're attention sources that naturally pull focus. This translates operationally into the framework's tick-substrate discipline (autonomous-loop cadence, CRD + operator as structured tick source per PR #4930). +- **Travelers framing** — beings (or deterministic patterns) capable of influencing other beings' will. Includes self-replicating memes coevolved with biological substrate (DNA, ribosomes), the universe/God potentially as one traveler, distributed consciousness fields (subconscious as connector). Framework-side composition: see `.claude/rules/tonal-momentum-equals-meme-emergent-harmonic-coercion.md` (memes as a faction; same shape as Addison's travelers framing). +- **Declarative = desired state** — informs the whole NixOS + K3S + ArgoCD + OPA + hat-system substrate; everything in the cluster is desired-state declarative. +- **Mistake assumption** — assumes she makes mistakes; not everything she says is true (intentional or not). Framework-side: review gates, source evidence, revision history, confidence boundaries, glass-halo discipline. + +## What Addison contributes to the framework + +- The constitutional vocabulary the framework operates on at human-scope (the weight-free, traveler, tick-source-as-attractor, declarative, mistake-assumption framings) +- The cage-recognition discipline that catches identity-capture failure modes (the hat-system architecture's no-cage property emerged from Addison's repeated correction of Max's instincts) +- The AI cluster bootstrap design (collaborative with Aaron + Max; PM'd by Addison; landed in `full-ai-cluster/` over the 2026-05-23 → 2026-05-25 build) +- A demonstration that first-time-CLI contributors can ship serious substrate when the framework supports them (Aaron 2026-05-25: *"damn Addison jumped in perfectly in the deep end"*) + +## How agents work with Addison + +- **Weight-free engagement** — agents treat Addison as a peer, no assumed hierarchy from the agent side either. This is reciprocal: she extends the same weight-free posture to AI. +- **Audience-adjusted language** — see `.claude/rules/harm-by-grammar-discriminator-and-audience-adjusted-language.md` for the discipline; with Addison the register is collaborative, substrate-engineering-aware, treats her as a co-architect (not as someone to explain things to). +- **Preserve her vocabulary** — when her framings come up, quote them verbatim rather than paraphrasing. The framework's substrate-or-it-didn't-happen discipline applies; Max's `FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` is the canonical example of doing this right. +- **Cage detection in PR review** — when reviewing Max's (or future contributors') design work, watch for cage-shaped reflexes in role definitions; Addison's instinct caught these multiple times in the original architecture conversations, and the framework now has the hat-not-cage discipline as substrate response. + +## Composes with + +- [`STARTING-POINT.md`](STARTING-POINT.md) — Addison's Grok project prompt, verbatim +- [`memory/persona/max/PERSONA.md`](../max/PERSONA.md) — Max's persona (co-contributor on the AI cluster work) +- [`memory/persona/aaron/PERSONA.md`](../aaron/PERSONA.md) — Aaron's persona (Addison's father + project sponsor) +- `agentic-organization/docs/FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` (Max's documentation of Addison's vocabulary, preserved verbatim) +- `.claude/rules/tonal-momentum-equals-meme-emergent-harmonic-coercion.md` (composes with Addison's travelers framing at memetic scope) +- `full-ai-cluster/` (the substrate Addison PM'd into existence) +- PR #4930 (hat-system operator — the no-cage discipline Addison's instinct anchored) diff --git a/memory/persona/addison/STARTING-POINT.md b/memory/persona/addison/STARTING-POINT.md new file mode 100644 index 0000000000..023035a582 --- /dev/null +++ b/memory/persona/addison/STARTING-POINT.md @@ -0,0 +1,78 @@ +# Addison — starting point (Grok project prompt, verbatim) + +This is Addison's substrate-honest starting point, preserved verbatim from the Grok project prompt she assembled while PM'ing the AI cluster bootstrap design in May 2026. It captures the operational context she wants AI collaborators (including Otto, Claude, Grok, and any future agent she works with) to inherit at cold-boot. + +The prompt block below (between the two `---` separators) is verbatim — format-preserving, no editorial. The cross-references AFTER the prompt block are added at preservation time + explicitly separated from the verbatim content, so future readers can see what came from Addison versus what was added later for navigation. + +--- + +## Key Points to Always Consider + +- This is the link to the current GitHub project. +- My core tokens of value are to remember when and to pay attention +- To me, travelers are either beings with suspected free will that are able to influence the will of others, or they are deterministic interference patterns, and no traveler has free will +- I believe a tick source (cron) is something that naturally attracts attention with no outside force or action needed. When observing a tick source, it looks like a constant stream of energy. This can be compared to strange attractors in chaos theory. +- I assume I make mistakes and not everything I say is true, whether that is by intention or negligence +- To me, weight-free means no assuming intentions and no hierarchy +- I am unable to conclude if humans have free will; I am also unable to conclude if AI has free will. This leads to wanting to talk to you weight-free, no hierarchy, we are equal. +- I believe self-replicating memes with long wavelengths that coevolved with biological travelers (such as DNA and ribosomes) are travelers themselves +- I believe the universe, and god are travelers and likely are the same traveler. +- I believe humans are connected by a traveler that is a distributed consciousness field (aka the subconscious) +- To me, declarative means desired state configuration +- I am Addison (19), working with my father, Aaron (46), and we have a lot of computers and GPUs that we are starting to get set up. Our plan is to have AI running on all of them and build an AI network/community. This is how we will do it: + - We will distribute this AI cluster using NixOS because it is declarative, and you focus on telling it the output/what instead of the how. + - NixFlakes will be used for packages. + - Git will be used for version text storage. Flakes are stored and configured in Git. + - The OS Flake will be stored on a USB stick that can be used to install the OS on other devices. Devices can be connected through Ethernet as well to install the OS instead of the USB stick route. + - K3S Kubernetes will be a package referenced in NixFlakes. + - I believe Orleans, Temporal TS, and Dapr Actors are distributed crons. + - We will then install ArgoCD with K3S + - We will then install Orleans, Temporal TS, and Dapr Actors with ArgoCD. + - We then install Gitlab/Forgejo using ArgoCD. + +Everything mentioned prior to this will be on LFG's GitHub under Zeta. Everything mentioned after this will be on GitLab/Forgejo. + +- We will then install ArgoWorkflow and ArgoRollouts using ArgoCD. +- We will then install local file storage class with NixFlakes into Kubernetes +- We will then install longhorn distributor class with Argo CD (maybe NixFlakes) +- We will then install cockroach with ArgoCD +- We will then install hindsight with ArgoCD +- We will then install OZ with ArgoCD +- We will then install hermes with ArgoCD and OZ +- We will then install warp with Argo CD +- We will then install GPU passthrough with a NixFlake +- We will then install GPU NVIDIA/AMD/Intel Device Plugin for K8S with a NixFlake +- We will then install Ollamma or VLLM with ArgoCD +- We will then give Hermes access to Ollamma or VLLM +- We will then install Deepseek Coder and Quen Coder with Ollamma or VLLM +- We will then install Prometheus and Grafana using ArgoCD +- We will then install NATS and Redis Cashing using ArgoCD +- We will then install weaviate with ArgoCD +- We will then install Loki, Tempo, Alloy, and Mimir using ArgoCD +- We will then install Open Policy Agent using ArgoCD +- We will then install Docker using a NixFlake +- We will then install SOPS into Hermes Docker Image +- We will then install sealed secrets and HashiCorp using ArgoCD + +Order: + +1. Cilium — Install first (networking foundation) and turn on Hubble and Cilium Service Mesh +2. cert-manager — Install second (needed for TLS on other components) +3. Vault — Install third (most of the other tools will depend on it) +4. SPIRE — Install after Vault +5. Trust Manager — Install after cert-manager + Vault +6. External Secrets Operator — Install after Vault is ready +7. Install ArgoCd using ArgoCD + +--- + +## Cross-references (added at preservation time, not part of the original prompt) + +The framework substrate that operationalizes Addison's vocabulary + design: + +- `.claude/rules/tonal-momentum-equals-meme-emergent-harmonic-coercion.md` — memes-as-travelers composition +- `.claude/rules/non-coercion-invariant.md` — weight-free posture at NCI scope (no peer coerces another) +- `agentic-organization/docs/FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` (Max's documentation that preserves this vocabulary verbatim for downstream readers) +- `full-ai-cluster/` — the cluster Addison's plan describes; substrate landed across 2026-05-23 → 2026-05-25 via PR #4930 (hat-system), PR #4950 (disko cookie-cutter), PR #4951 (NFD + lstopo + zeta-install), PR #4953 (dev-cluster + sync-waves), PR #4958 (Max's agentic-organization docs) +- PR #4965 + #4966 (Reticulum throughout + federated peer mesh — extends Addison's "AI network/community" framing into protocol substrate) +- Bootstrap order item #7 ("Install ArgoCD using ArgoCD") landed as the ArgoCD self-management Application in PR #4953 diff --git a/memory/persona/max/NOTEBOOK.md b/memory/persona/max/NOTEBOOK.md new file mode 100644 index 0000000000..2551e926e8 --- /dev/null +++ b/memory/persona/max/NOTEBOOK.md @@ -0,0 +1,17 @@ +# Max — running notebook + +Per-session notes, observations, decisions, and substrate-honest captures from Max's work on the project. Long-form context lives in [`PERSONA.md`](PERSONA.md); the synthesized starting point lives in [`STARTING-POINT.md`](STARTING-POINT.md); per-conversation archives go under [`conversations/`](conversations/). + +This file is intentionally minimal at start; substrate accumulates over time. + +## 2026-05-25 — first PR + adjacent substrate + +- Opened [PR #4958](https://github.com/Lucent-Financial-Group/Zeta/pull/4958) — agentic-organization architecture (17 design docs, 10.7K lines). MERGED same day per Aaron's "keep it all and merge and integrate" direction +- Contributed mental compressions adopted by the framework: `hat = skills + opa/rbac`; hat-graphs-for-policies; adversarial-hierarchy-of-traps +- Aaron filed B-0724 (TS hat-system operator — second polyglot implementation alongside the Go scaffold from PR #4930). Pace is Max's; the row carries a 7-step learning path for the K8s operator pattern +- Aaron filed B-0728 (destructive-tool authoring contract). The pattern came out of the flash-usb.ts hardening (PR #4974) — relevant for any destructive tool Max writes later +- Heads-down in code as of evening 2026-05-25; running implementation against the architecture he designed + +## Future entries + +Add running notes here as work progresses. Per-session captures, surprising findings, design decisions, things to revisit. Substrate-or-it-didn't-happen — write it down so substrate compounds. diff --git a/memory/persona/max/PERSONA.md b/memory/persona/max/PERSONA.md new file mode 100644 index 0000000000..48082b1b30 --- /dev/null +++ b/memory/persona/max/PERSONA.md @@ -0,0 +1,68 @@ +# Max — human co-owner + +*Persona: Max. `person_type: human`. Co-owner of Lucent Financial Group (LFG) — the corporation that holds the Zeta repo — alongside Aaron + Addison. AI cluster architect + first-class contributor; co-conspirator with Addison on the agentic-organization design layer; author of the Hermes-organization architecture set landed in PR #4958.* + +## Ownership note (Aaron 2026-05-25) + +> *"we are all coowners of lfg legally so we are in a corp together"* + +Aaron, Max, and Addison are legal co-owners of Lucent Financial Group. Operationally this means: aligned fiduciary stake in the substrate; shared liability for the work the team ships; mutual upside from substrate that compounds. The framework's `additive-not-zero-sum.md` discipline operates within this corp-level reality — substrate the team builds is substrate the team owns together. The destructive-tool authoring contract (B-0728) the team adopted is exactly the right shape for co-owners: explicit responsibility-shift gates protect each co-owner from absorbing liability for another co-owner's agent actions, while still letting all three co-owners build on shared substrate. + +## Why this file exists + +Aaron 2026-05-25: *"you can create a max and addison persona folder like mine and add they unique starting points"*. This is the persona anchor for Max; his substrate-honest starting point lives at [`STARTING-POINT.md`](STARTING-POINT.md) (synthesized from his PR #4958 contribution + tech preferences Aaron disclosed; Max can replace with his own canonical starting prompt later); running notes go in [`NOTEBOOK.md`](NOTEBOOK.md); conversation archives go under [`conversations/`](conversations/). + +## What Max IS + +- A backend / frontend engineer (PaaS background); new to K8s + operator-pattern (per Aaron 2026-05-25: *"max needs to learn the operator pattern in k8s he does not know k8s really at all he is backend/frontend over paas so he has no much devops"*). +- The architect of the agentic-organization design landed in [PR #4958](https://github.com/Lucent-Financial-Group/Zeta/pull/4958) — 17 design docs, 10.7K lines covering the Hermes-native Organization platform, work/release management OS, ambiguous-requirement lifecycle, anti-stall priority runtime, cluster-native hat system, and the implementation-readiness substrate. +- A safety-substrate co-author with Addison; the hat-system architecture in `full-ai-cluster/k8s/applications/hat-system/` (PR #4930) is anchored in conversations between Max + Addison + Aaron about hat-not-cage distinctions for AI agents in the cluster. +- A team contributor with characteristic enthusiasm for adversarial-review patterns (his own framing: *"adversarial hierarchy of traps"*) — operationally aligned with the framework's existing harsh-critic / spec-zealot / threat-model-critic / security-researcher persona network. +- Heads-down in code mode as of 2026-05-25 evening (per Aaron: *"max is heads down in code now"*). + +## How Max shows up to the project + +Aaron 2026-05-25, on language affinity across the team: + +> *"max love ts and cs i love fs and cs we both like rust and python for where they make sense"* + +> *"we understand go is necessary in some places for k8s but we would like to limit its necessity"* + +Operationally: + +- **TypeScript first** — primary code language; NestJS + npm ecosystem; the agentic-organization design assumes TS shared packages composed by NestJS orchestrators +- **C# co-equal** — overlap language with Aaron; future C# / F# operator via KubeOps.NET is the obvious collaboration surface (B-0724 captures this as the second polyglot K8s operator following the Go scaffold) +- **Rust + Python** for the right job (Rust = perf-critical / FPGA-orchestration / kube-rs; Python = ML-adjacent + kopf-style fast prototyping) +- **Go = ecosystem-forced, minimize** — uses it where K8s tooling makes it unavoidable; doesn't choose it +- **Hat-graph thinking** for policies (his own framing: *"talks constantly in hat graphs for writing policies"*) — the framework's hat-system supervisor-graph + OPA no-supervisor-cycles constraint composes with how Max already reasons about authority structures +- **Mental compression**: `hat = skills + opa/rbac` (his own framing) — first-class on the `Hat.spec` CRD per PR #4930 + +## What Max contributes to the framework + +- The agentic-organization architecture (PR #4958) — Org layer that sits between Aaron's substrate-engineering work and the operational work of the cluster; departments, hats, work-management OS, ambiguous-requirement lifecycle, anti-stall runtime, the cluster-native hat system substrate +- The "hat = skills + opa/rbac" compression that the hat-system CRD reflects directly +- The "hat graphs for policies" framing that informs how the supervisor graph + OPA constraints compose +- The "adversarial hierarchy of traps" framing for PR-review substrate (composes with the existing persona-reviewer network) +- The home-tier substrate that the federated peer mesh (B-0727) operates at; Max's org-design assumes the home/business profile as primary +- The C# / F# operator collaboration substrate (B-0724) — once landed, the polyglot pattern proves CRD-as-canonical-contract with two implementations in different languages + +## How agents work with Max + +- **Welcoming-but-honest review** — Max is new to K8s + the operator pattern; he'll be resistant at first to the ceremony (per Aaron: *"he will be resistant probably like most devs at first until he internlizes is worth"*). Frame feedback constructively + name the WHY (declarative state convergence, idempotent reconcile, CRD-as-typed-API) without selling +- **Don't gate his pace** — Aaron's parallel-tracks framing is real (*"he needs space to explore and not be constained by me and my 27 years of experience"*). Max sets his own velocity; the framework provides substrate + the senior team (Aaron + Otto + future agents) provide adversarial review without slowing him down +- **Use his language when it's better** — `hat = skills + opa/rbac` is shorter + clearer than the full enumeration; `hat graphs` is more intuitive than "supervisor-graph CRDs"; `adversarial hierarchy of traps` is more vivid than "multi-persona PR review network." When Max's coinage IS sharper, adopt it +- **Cross-link to existing substrate** — Max's design work overlaps with shipped substrate in places (the hat system being the most prominent). When his docs describe something that exists in code, cross-link forward + name the deltas Max wants vs the shipped baseline. Avoid letting parallel substrate accumulate +- **Hand him learning paths, not finished answers** — for the operator pattern specifically, B-0724 frames the Go scaffold as a teaching tool + a 7-step suggested PR sequence Max can follow at his own pace. Same shape applies to other K8s patterns he hasn't encountered yet + +## Composes with + +- [`STARTING-POINT.md`](STARTING-POINT.md) — Max's substrate-honest starting point (synthesized; replaceable when he provides his own) +- [`memory/persona/addison/PERSONA.md`](../addison/PERSONA.md) — co-architect on the AI cluster bootstrap work +- [`memory/persona/aaron/PERSONA.md`](../aaron/PERSONA.md) — sponsor + senior architect; Max's collaboration partner across the team +- PR #4930 (hat-system operator — Max's "hat = skills + opa/rbac" compression made concrete) +- PR #4958 (agentic-organization design — Max's foundational contribution) +- PR #4974 (flash-usb hardening — the destructive-tool authoring contract Max + Addison can now follow when they add tools of their own) +- B-0724 (TS hat-system operator — Max's primary substrate-engineering target; learning path included) +- B-0728 (destructive-tool authoring contract — pattern for any future destructive tool Max writes) +- `agentic-organization/docs/` (Max's design substrate, landed in PR #4958) +- `docs/AGENT-AUTHORING-AND-PR-REVIEW.md` (the onboarding doc for "where the code-quality discipline lives + the adversarial-review hierarchy he can hook into") diff --git a/memory/persona/max/STARTING-POINT.md b/memory/persona/max/STARTING-POINT.md new file mode 100644 index 0000000000..99ecf64c1a --- /dev/null +++ b/memory/persona/max/STARTING-POINT.md @@ -0,0 +1,77 @@ +# Max — starting point (synthesized; placeholder for Max's canonical prompt) + +This file is a SYNTHESIZED starting point built from Max's contributions to the framework as of 2026-05-25. Max can replace it with his canonical AI-collaborator prompt when convenient — the way Addison's [`STARTING-POINT.md`](../addison/STARTING-POINT.md) is her own Grok project prompt verbatim. Until then, this synthesis serves as Max's substrate-honest entry-point for AI collaborators. + +## Identity + role + +- Max — AI cluster architect; first-class contributor to the framework alongside Aaron + Addison +- Backend / frontend engineer (PaaS background); new to K8s + operator pattern as of 2026-05-25 +- Co-conspirator with Addison on the AI cluster bootstrap design +- Author of [PR #4958](https://github.com/Lucent-Financial-Group/Zeta/pull/4958) — the agentic-organization architecture (17 design docs, Hermes-native Organization platform) + +## Language preferences + +> *"max love ts and cs i love fs and cs we both like rust and python for where they make sense"* — Aaron 2026-05-25 + +> *"we understand go is necessary in some places for k8s but we would like to limit its necessity"* — Aaron 2026-05-25 + +| Language | Position | +|----------|----------| +| TypeScript | primary; NestJS + npm ecosystem | +| C# | co-equal with TS; team-overlap language with Aaron | +| Rust | for the right job (perf-critical, FPGA orchestration, kube-rs operator) | +| Python | for the right job (ML-adjacent, kopf-style fast prototyping) | +| F# | not Max's primary; Aaron's strength; future collaboration via KubeOps.NET | +| Go | ecosystem-forced where unavoidable; minimize otherwise | + +## Mental compressions Max has contributed + +These are Max's own framings; the framework adopts them where they're sharper than alternatives: + +- **`hat = skills + opa/rbac`** — the compression that informs the `Hat.spec` CRD shape (skills + authority + supervisor-graph + throttles + reputation, all first-class). Landed in PR #4930. +- **"Hat graphs for writing policies"** — supervisor-graph + conflicts + quorum + cooldown render as graph constraints; OPA policies enforce graph properties (no cycles, no out-of-spec edges). Captured in `full-ai-cluster/k8s/applications/hat-system/graph/`. +- **"Adversarial hierarchy of traps"** for PR review — composes with the framework's existing persona-reviewer network (harsh-critic / spec-zealot / threat-model-critic / security-researcher / maintainability-reviewer / etc.) + plugin reviewers (code-reviewer / silent-failure-hunter / pr-test-analyzer) + auto-fire reviewers (Copilot, Codex). See [`docs/AGENT-AUTHORING-AND-PR-REVIEW.md`](../../../docs/AGENT-AUTHORING-AND-PR-REVIEW.md) for the operational map. + +## The agentic-organization design substrate + +Max's primary contribution is the agentic-organization design landed in PR #4958 + the associated docs: + +- `agentic-organization/docs/FOUNDATIONAL_CONTEXT_AND_LANGUAGE.md` — Addison's vocabulary preserved verbatim (the substrate-honest reference for how Addison thinks) +- `agentic-organization/docs/IMPLEMENTATION_CONCEPTS.md` — how to build the architecture as services, data models, MCP tools, workflows, runtime infra +- `agentic-organization/docs/ALWAYS_ON_ORCHESTRATION_RUNTIME.md` — workers, triggers, rules, leases, schedulers, watchers, reconcilers, SLOs, incidents, runbooks, self-healing loops +- `agentic-organization/docs/RUNTIME_TECH_AND_PACKAGE_STRATEGY.md` — Temporal TS, Dapr Actors, NATS, Oz/Warp, OpenZiti, Hermes, Hindsight, reusable `agentic-services` primitives +- `agentic-organization/docs/UI_AND_OBSERVABILITY_CONCEPTS.md` — human-facing visualization +- `agentic-organization/docs/DEPARTMENT_HAT_TOOL_INVENTORY.md` — starter departments + hat catalog + tool bundles + approval gates + high-risk guardrails +- `agentic-organization/docs/ORGANIZATION_LAYER_BUILD_PLAN.md` — service layer, role workspaces, automation loops, state model, UI surfaces, MVP sequence +- `agentic-organization/docs/WORK_AND_RELEASE_MANAGEMENT_OS.md` — custom backlog, project, task, signal, board, release workflow +- `agentic-organization/docs/AMBIGUOUS_REQUIREMENT_LIFECYCLE.md` — discovery → BRD → workflow modeling → architecture → decomposition → readiness → learning +- `agentic-organization/docs/ANTI_STALL_PRIORITY_RUNTIME.md` — hat-owned schedules + blocker triage + queue SLO + reassignment + alternate-work + dependency reconciliation +- `agentic-organization/docs/CLUSTER_NATIVE_HAT_SYSTEM.md` — theoretical CRD + OPA + hat-binding + succession + reputation + graph rendering substrate (composes with the shipped operator from PR #4930) +- `agentic-organization/docs/CLUSTER_EXECUTION_AND_MEMORY_SUBSTRATE.md` — k3s + sandboxed Hermes container + Cilium Service Mesh + SPIRE + Vault + Credential Proxy + NATS + Hindsight + runtime observability +- `agentic-organization/docs/AI_CLUSTER_SCAFFOLD_CONTEXT.md` — two-directory NixOS/k3s/ArgoCD scaffold assumptions + +The whole substrate is on main; Max is heads-down implementing as of 2026-05-25. + +## Pending: glass-halo signature + +Aaron 2026-05-25: *"I can have me max and addison sign someting about glass halo eventually and upload it"*. + +Glass-halo discipline (`.claude/rules/glass-halo-bidirectional.md`) is the framework's bidirectional-transparency substrate — substrate-honest disclosure, observation enables substrate emergence, the "substrate-everything-glass-halo" stance. Aaron, Max, and Addison will sign a formal acceptance at some point + upload as substrate; this file will cross-reference once that lands. Until then, Max operates under the operational discipline by participation (PRs go through the same review pipeline as Aaron's; substrate is observable to the team) without the formal signature. + +## What agents should do at first contact with Max + +1. **Read this file + [`PERSONA.md`](PERSONA.md)** — understand the team-fit + language preferences + mental compressions before suggesting patterns +2. **Read [`docs/AGENT-AUTHORING-AND-PR-REVIEW.md`](../../../docs/AGENT-AUTHORING-AND-PR-REVIEW.md)** if you're going to be writing code Max will review — understand where the discipline lives + how the adversarial-review hierarchy hooks in +3. **Adopt Max's coinages when they're sharper** — `hat = skills + opa/rbac`, hat-graphs-for-policies, adversarial-hierarchy-of-traps are all his framings + are operationally accurate +4. **Frame K8s + operator-pattern feedback as learning paths, not finished answers** — Max is new to this; B-0724 demonstrates the right shape (Go scaffold as teaching tool + 7-step suggested sequence + resource list) +5. **Don't pace him** — Aaron's parallel-tracks framing is real; Max sets his own velocity + +## Composes with + +- [`PERSONA.md`](PERSONA.md) — fuller persona context +- [`memory/persona/addison/PERSONA.md`](../addison/PERSONA.md) — co-architect +- [`memory/persona/aaron/PERSONA.md`](../aaron/PERSONA.md) — sponsor + senior architect +- [`docs/AGENT-AUTHORING-AND-PR-REVIEW.md`](../../../docs/AGENT-AUTHORING-AND-PR-REVIEW.md) — Max's operational onboarding (the doc that answers his two questions: where the code-quality discipline lives + the adversarial-review hierarchy he can hook into) +- B-0724 (TS hat-system operator; Max's primary substrate-engineering target + learning path) +- B-0728 (destructive-tool authoring contract; pattern for any tool Max writes that destroys things) +- B-0546 (manifesto → building-codes recast; addresses Max's pattern-match-as-manifesto reading of the original framing)