1. What the Snook fleet is
A multi-agent software factory that builds and ships Snook A Look (the Dubai snooker / pool booking and matchmaking product: KMP mobile app, Fastify backend, Next.js admin, public web) with one human (you, the founder) in the loop only for five reserved decisions. Everything else is self-authorized, but every action must pass through mechanical gates and leave an audit receipt.
13
live pane roles (5 pillars, 7 workers, 1 python conductor)
50
doctrine slot files under docs/doctrine (30+ LIVE)
1,808
feedback scars (lessons) in the memory corpus
27
hooks: 25 active shell guards + 2 stop-gates
256
tools in agents/tools (python + shell)
27,211
decision-ledger lines (every gated action logged)
23,447
reports landed in agents/reports
4
product repos: backend, mobile, admin-web, web
The one-sentence model. Founder sets priority; Principal decides when and who; Architect decides what; Curator preserves knowledge; God keeps the audit trail; worker panes write code; Conductor moves briefs; hooks + GitHub rulesets +
principal-merge.sh make the rules physically hard to break.
Design philosophy (from FLEET-MASTER-HISTORY)
- Behavioral to mechanical pivot (2026-07-02). An audit found "documented-but-fictional guarantees" (rules written but unwired). Since then every rule that matters is enforced by a hook, a script, CI, or a server-side ruleset, with the incident cited in the enforcer's header.
- Scar compilation. Incident, founder pen, numbered doctrine slot, then mechanization. Nothing is "remembered" only in prose.
- Prove, do not eyeball. Every PASS names an exact commit SHA; evidence files are the truth, prose is a claim.
- Minimum fix. Close the real P0/P1, park P2/P3 as backlog FU entries, no over-engineering (founder pen 2026-09-16).
2. Roster and topology
Blue = pillar (hard tier, Opus-class), green = worker (normal tier, Sonnet-class), purple dashed = transport. Retired: drafter (06-08), main (07-02), coordinator/fcm/bnpl-ios (de facto). Herald is documentation-only since 2026-08-26.
| Pane | Class | Owns | Never does |
|---|---|---|---|
| god | pillar | Cross-pane orchestration, escalation routing, proxy for founder when offline, TICK-1 checklist on every report, decision ledger | Claim principal duties |
| principal | pillar | Briefs, dispatch, duplicate checks, dev-merge via principal-merge.sh, master-cut prep, status tables | Write Kotlin/Swift/TS itself (except in single-man-army mode); raw gh pr merge |
| architect | pillar | PRDs, screen specs, contracts, plan-lock refine (8.42), pre-PR audit on sensitive paths | Produce device evidence |
| curator | pillar | Brief enrichment (dossier anchors L#/I#/ADR), doctrine drafting, lesson harvest, drift tables, pre-PR audit | Dispatch to pillars |
| infra / deploy | pillar/worker | VPS, Caddy, systemd, GitHub Actions, prod deploys, env deltas (8.71) | Deploy mobile |
| backend, android, ios, admin-web | worker | Code in their repo, tests, reports with handoff_to | Merge to dev; dispatch another pane |
| qa-mobile | worker | Pixel real-device runtime evidence, Maestro flows, screenshots | iOS simulator runtime checks (banned) |
| pr-steward | worker | Codex re-tags, per-thread closure asks, resolver sweeps | Self-resolve threads |
| conductor | python daemon | Transport: ingest, lint, quarantine, pointer dispatch, wake, defer/backoff, per-pane mutex | Author briefs or decide routing |
3. Life of a task (founder ask to production)
0Founder askSets priority. Task is pre-authorized end-to-end (just-do-it rule).
1SCOPE-FENCE + plan5-block fence (PROBLEM / DO-NOT / FILE-HINT / ACCEPTANCE / REPORT). Written todo checklist.
acceptance_gate.py create.2Brief authoredOne screen. Frontmatter: tier, source_of_truth, correct_layer, touch_point_file. Pillar derived from file paths.
38.42 refine gateArchitect plan-lock + curator drift-table.
refined_by: architect,curator or wake-pane exits 9.4DispatchPointer file in agents/inbox, conductor delivers, wake-pane, pickup verify T+5.
5Executor buildsfix/<slug> off dev (8.40). Audit-first, minimum diff, exact verification, report.
6Pre-PR triokk always; architect + curator only on sensitive paths (payment, challenge, account, settlement, stripe, migrations). Each PASS names full SHA.
7pr_raise_gate.shOnly sanctioned way to open a PR. Requires trio at exact commit + Pixel evidence for interactive mobile UI.
8CI + codexcodex_monitor auto-tags
@codex review per head. Only P0/P1 block; P2/P3 to backlog FU.9Fix loopVerified findings only. kk re-reviews new head. Round cap 2, then [CODEX-TRIAGE] verdict.
10principal-merge.shStructural gate: receipts at head, threads resolved, CI green, subject lint, ledger write, token mint for merge hook.
11Promote dev to mainCadence merge (backend/admin/web), kk-codex lane. Deploy via GH Actions / Vercel.
12Mobile master cutFounder pen per merge + semver tag. TEST_PHONE_BYPASS posture surfaced unprompted.
Anti-idle transaction. When a report lands, principal reads it, preserves the result, selects the continuation, wakes the pane and verifies, then returns to its own work. A completed report alone never justifies an idle pane. Pickup-verify cadence is T+5 min. A pane silent 30 min gets woken.
4. Authority model
FULL-AUTHORITY (founder pen 2026-06-24): the fleet may fix flows, fix bugs, merge to dev, refactor, change config/schema, deploy non-mobile prod (audit-gated), and rotate routine secrets without asking. Asking on planned work is itself a violation (NEVER-ASK-PERMISSION, ASK-GATE-CHECK).
The 5 founder-gated categories (STOP and surface)
| # | Gate | Why |
|---|---|---|
| 1 | Mobile deployment: App/Play submit, master cut, semver tag | Store provenance blast radius (8.26 v3) |
| 2 | Founder decisions: doctrine LIVE pen, legal/team-ID/domain, product direction | Only founder owns these |
| 3 | Collisions between pens or workstreams | Surface, never pick a side |
| 4 | Genuine P0: prod down, data loss, breach, fleet-wide auth break | Founder must know now |
| 5 | Payment / paid account: Stripe LIVE, billing tier, new subscription, money movement | Money |
Blast-tiered replica (god as proxy-founder)
GREEN self-authorized, act and report.
AMBER act with rollback candidate, report same tick (deploy with rollback, revertable merge).
RED the 5 categories, or destructive + irreversible with no rollback: direct binary to founder; if founder offline, god answers on founder's behalf for SAFE scope only.
A founder pen applies only to the surface it was said on: "lets merge" about dev is never authority above dev.
Scope locks
agents/state/principal-scope-locks.json lists workstreams the founder locked ("me and god", "hands off", "until I ask"). Principal filters them from every poll, never wakes panes for them, reopens only on explicit ask.
5. Branch and merge policy (Doctrine 8.26 v3)
- Diverged branch recovery: merge origin into it (merge commit), never rebase-force.
- Server-side backstop: rulesets (pull_request + non_fast_forward) on all prod branches; classic protection
enforce_adminson backend and mobile. - Ungated push exception (pen 2026-09-17): a commit that bypassed the PR gate stays if codex clean + kk PASS at that exact head; record an exception, fix the backdoor later (FU-148).
6. Gates: the mechanical enforcement layer
Hooks run on Claude Code tool events. A PreToolUse hook exits 2 to block. All guards cover Bash and mcp__lean-ctx__ctx_shell, match raw and quote-stripped text, fail-open on infra errors and fail-loud on policy hits. Block messages name the authorized path, never the override. Tested by pytest agents/tools/test_hooks.py (88 cases) in fleet CI.
| Gate | Where | Blocks / enforces | Authorized path |
|---|---|---|---|
| merge-gate-guard | PreToolUse | raw gh pr merge, gh api .../merge | token file minted by principal-merge.sh (<10 min) |
| deploy-gate-guard | PreToolUse | force-push, push to master, semver tag, gh release, store submit | founder deploy note + FOUNDER_DEPLOY_AUTHORIZED=1 |
| secret-echo-guard (8.22) | PreToolUse + Read | cat/grep/base64 on secret paths; native Read of .env, .p8, keystores | shape-only inspection (ls, wc, key names) |
| court-glitch-guard | PreToolUse | poll loops with sleep, heredocs into agents/inbox | Monitor tooling, conductor |
| fleet-hygiene-guard | PreToolUse | git add -A, adb monkey, open -a Xcode (8.29), killing MobAI-Runner (8.31), exhausted MobAI budget | scoped adds, CLI installs |
| git-add-hygiene-guard | PreToolUse | staging scratch / patch files | explicit paths |
| codex-review-request-guard | PreToolUse | hand-composed closure replies, wrong mention form | post_thread_closure_ask.py |
| memory-write-guard | Write/Edit | secrets or injection shapes written into memory corpus | fail-open |
| auto-scope-fence | UserPromptSubmit | technical ask: injects the 5-block SCOPE-FENCE reminder | advisory |
| minimalism-ladder | UserPromptSubmit | 7-rung reuse ladder before any new code or dependency | advisory |
| skill-router / skill-hint | UserPromptSubmit | MANDATORY skill matches must be invoked first | one-line justification to skip |
| lesson-recall-prepare | UserPromptSubmit | BM25 recall of relevant scars, injection-fenced | always |
| lesson-gate | Stop | "done" replies with no memory write this session | Lessons: none, <reason> |
| claim-receipt-gate | Stop | claiming an action or state with no receipt in the same turn (5 false "handled" claims in one session, pen 2026-08-20) | show the receipt |
| acceptance-gate-stop | Stop | open acceptance checklists: reminds acceptance_gate.py check + drift | tick every box |
| queue-freshness-guard | PreToolUse | surfacing stale queue-state files (dispatch-candidates.json) as "pending" | queue_sweep.py assert-fresh |
| brief-lint-gate | PostToolUse(Write) | malformed inbox briefs (warn); conductor quarantines on dispatch (block) | brief-schema.json |
| truncated-evidence-annotator, repo-scratch-sweep, inbox-unread-sweep, session-start-marker, memory-size-warn, codex-monitor-sweep | various | housekeeping and freshness | - |
Script gates (not hooks)
principal-merge.sh
1,369 lines. Verifies curator + architect (or kk-codex lane) PASS reports at the trace, head-tied codex clean or [CODEX-TRIAGE] verdict, zero unresolved threads, CI green, interactive-UI evidence backstop, squash subject lint (conventional commit, ASCII, no U+2014), writes the merge log and ledger, mints the merge token. Exceptions: MERGE_THREADS_EXCEPTION=1 (codex verifiably down), MERGE_CODEX_FOUNDER_OVERRIDE=1 (codex at usage limit, swarm PASS at head), MERGE_SWARM_EXCEPTION=1.
pr_raise_gate.sh
The only sanctioned PR-raise path. Requires versioned pre-PR architect, curator and kk reports at the exact local commit, then device evidence when the diff touches interactive gate keywords in mobile UI. Override DEVICE_EVIDENCE_EXCEPTION=1 is founder-pen only and logged.
acceptance_gate.py
Derives a checklist from the SCOPE-FENCE deterministically: PROBLEM clauses become "resolved" boxes, DO-NOT clauses become "invariant held" boxes, FILE-HINT globs become the drift fence. check exits 1 while any box is open, drift exits 2 when changed files leave the fence.
wake-pane.sh + inject-merge-gate.sh
Every wake goes through wake-pane.sh (exit 9 if a code brief lacks refined_by or its refine reports are missing). inject-merge-gate.sh stamps an explicit DO-NOT-MERGE block into every executor brief that touches a dev-bound branch.
7. PR review lifecycle (impact-routed, v2)
Source of truth: agents/governance/PR-REVIEW-LIFECYCLE.md + pr-review-lifecycle.json. Amended by founder plan 2026-09-14 (lean loop).
1Contract freezeArchitect, curator, kk audit the final local commit in parallel before the PR opens. Each PASS names the full SHA.
2Build loopOpen PR. CI + codex on the exact head. Reproduce and triage every finding (question-codex).
3Fix loopOnly verified findings. kk re-reviews the new head. The reviewer that found it gets the resolution handshake.
4Impact-routed deltaArchitect/curator exact-head delta attestation only when the fix touches their routed axis. Doc/mechanical/test-only fixes carry the original PASS with a kk scope receipt.
5Close immediatelyResolve approved threads, immutable-head recheck, audited merge gate. Never park the PR.
Severity floor
Only P0/P1 block. P2/P3 from codex, kk, architect or curator become agents/backlog/fu-NNN-*.md in the same round; reviewers report them as backlog lines with verdict: PASS.
Round cap = 2
After 2 reviewed heads the monitor stops re-tagging. Fixes after the cap merge on the engineer's [CODEX-TRIAGE] verdict: PASS commit: <full sha> + kk head-tied report. Zero unresolved threads is still required.
Lanes
Curator + architect audit only PRs touching sensitive paths: payment, challenge, account, settlement, stripe, prisma/migrations, schema.prisma, manual-migrations. Everything else merges with --lane kk-codex, which recomputes the file list and refuses on a sensitive match.
Required report fields (v2 receipts): trace_id, review_lifecycle_version: 2, audit_phase: pre_pr_full | post_fix_exact_head | post_fix_delta, audited_commit: <full SHA>; final kk also carries scope_receipt and impact_axes. AGY swarm is OFF (agy_required: false) since 2026-09-14; it had measured zero citations and one fabrication on its PASS path.
8. Codex protocol (permanent, every repo)
- Every codex comment gets a written reply citing the fixing SHA, or a REAL / NOT-REAL triage with evidence. No thread stays unanswered at any moment (an ACK reply closes the silent window while the fix is in flight).
- Closure asks go through
post_thread_closure_ask.py, the sole posting boundary (plain@codexmention, full SHA, evidence grammar, duplicate suppression). Never hand-compose. - A thread is resolved only via
resolve_confirmed_threads.pyafter codex gives an exact-head written approval (it echoes the full head SHA). Never self-resolve, never merge with an unresolved thread. - Closure mode
head_clean_bulk: once codex is clean at the exact head, the resolver closes every thread; P2/P3 threads also close on the triage verdict; P0/P1 close only via the per-thread handshake. Labelclosure:per-threadforces the handshake for a PR. - After pushing a fix, re-tag
@codex review(codex_monitor auto-tags every new head as a backstop). - Interim replies never say "@codex" with an action sentence: it makes Codex Cloud commit its own fixes in its sandbox (scar 2026-09-21). Only three reply types mention codex: the review request, the covering-commit confirmation ask, and the park-with-verdict reply.
- Codex clean = issue comment "Didn't find any major issues" with
Reviewed commit: <sha>prefix-matching the head, or a head-tied summary-widget row + PR-level thumbs-up. A clean verdict on a later fixture-only commit says nothing about earlier threads. - Codex at usage limit:
MERGE_CODEX_FOUNDER_OVERRIDE=1with reason + limit notice; trio + CI remain the floor. - question-codex: triage every finding yourself, judge severity yourself, push back with evidence when wrong. Probe the live config shape before accepting env-premised findings (sslmode scar 2026-09-17).
9. Doctrine system: the scar-compilation pipeline
IncidentProduction debugging, gate breach, drift, claim-vs-reality
Founder penVerbatim ruling, dated. Doctrine is load-bearing; never altered without pen.
Numbered slotdocs/doctrine/8.x-<class>.md, registry in doctrine-slot-tracker.md, PEN-LOG.md
MechanizationHook / CI gate / script, header cites the slot and incident
| Slot | Class (what it protects) |
|---|---|
| 8.5e / 8.5f | Audit-log write required for critical producers; stale-base regression class + probes |
| 8.11 / 8.12 / 8.13 / 8.18 | Next.js server-action hash skew; Android keystore corruption reset; Swift dynamic_cast main-thread block; local-storage version boot-crash |
| 8.15 / 8.16 / 8.50 | Runtime curl before header claims; HttpOnly/Secure/SameSite on session cookies; per-route CORS null-check |
| 8.22 | Secret file bytes never enter chat (hook-enforced) |
| 8.25 / 8.30 | Signing team RIVORA LABZ VG6Q82DU59 lock; portal verification before any team-ID lock |
| 8.26 v3 / 8.28 / 8.40 | Branch policy (mobile master, semver tags, cadence merge); root = fleet-meta repo, sub-repos independent; feature sub-branch protocol |
| 8.29 / 8.31 / 8.37 / 8.72 | iOS CLI install + 4-tier testing stack (no Xcode GUI); never kill MobAI-Runner; post-build daemon kill mandatory; CoreDevice tunnel lazy on WiFi |
| 8.33 / 8.43B / 8.45 | Brief collision + session-ID role identity; FS-POLL paired with ScheduleWakeup; task-marker vs spec-conformance drift |
| 8.34 / 8.54 / 8.58 / 8.70 | Mobile API resilience + 429 downgrade; Ktor concurrent-401 refresh Mutex; commonMain plugin via attributes.getOrNull; missing-route 404 silent stuck-retry |
| 8.35 / 8.52 / 8.65 / 8.68 | Sentry: resolve chain-of-custody; lastSeen day-bucket rounding; sweeps use lastSeen never firstSeen; release-tag init gap |
| 8.38 / 8.42 | Store-listing pre-submit refine gate; architect + curator pre-dispatch prompt refine gate (mechanically enforced by wake-pane) |
| 8.51 / 8.53 / 8.55 / 8.61 / 8.66 / 8.67 | Token stored before HomeStore fan-out; lifecycle-observer over-scope; Android CCT separate-task; push requires NotificationRecord first; notification-as-activity anti-pattern; logout-drain chain isolation |
| 8.69 / 8.71 | Dual-token zero-outage secret rotation; deploy env-delta ships with code + single-founder governance |
| model-tiering | Domain pane fixed by task type; brief carries tier + model; live-pane /model switch banned; new sub-agents on Sonnet 5 |
10. Memory and lessons
Corpus layout (~/.claude/projects/.../memory/)
MEMORY.md
thin always-loaded index, capped ~17 KB, one-line pointers only
MEMORY-STANDING-RULES.md
full text of standing rules, recall-indexed on demand
MEMORY-archive.md
pruned bullets, still recall-indexed
feedback_*.md (1,808)
scars: what went wrong, why, how to apply
project_*, user_*, reference_*
state snapshots, founder facts, credential locations (names only)
Pipeline
- FLAG inline the moment an error hits:
# LESSON: what went wrong - correct approach - FINISH the task.
- BATCH-SAVE to
agents/lessons/<pane>-lessons-<unix>.md, ping curator inbox. - Curator harvests into memory;
lookup-lesson.sh/lesson_recall_lean.py(BM25, injection-fenced, hit@5 = 1.0 on the pinned eval) surfaces them on every prompt. - launchd
memory-thin-indexkeeps MEMORY.md under cap;lesson-gateblocks "done" without a memory write.
Standing rules (pointer list, full text in MEMORY-STANDING-RULES.md)
| Rule | One line |
|---|---|
| NEVER-IDLE | Any report landing = classify, pick next actor, fire, same tick. Log after action, not instead of it. |
| ACTIVE-POLLING + FS-POLL | Every tick: ls reports, ls inbox, docs/wip, git log %ct on tracked branches. Commit timestamps are ground truth for "pane X is working". |
| TICK-1 PROTOCOL | 10-item checklist on every report receipt (classify, extract, scope-split, handoff brief, wake + pickup verify, founder-escalate, doctrine candidate, lesson pen, proxy log, fleet-state update). |
| FOUNDER-INPUT-PREEMPTS | A founder message always interrupts the grind loop and is answered first. Return to a readable prompt often. |
| SUPER-GRIND / BUCKET-DRAIN | Any task auto-arms full ownership, parallel streams, persistent watcher, pipeline depth 2, until every bucket task ships. The TaskList is the bucket. |
| STATUS-WINDOW | Founder reads only god + principal panes. Executor reports surface up same tick: Executor report: <topic> PASS/FAIL. finding. follow-up. |
| FULL-AUTHORITY + NEVER-ASK-PERMISSION | Only the 5 categories are gated. Run the 5-category test before any question; not in the 5 means do it and report. |
| MAIN-MERGE-UNLOCK | main merges need no per-merge pen; curator + architect PASS (or lane rule) before merge; prod deploy and mobile master cut stay locked. |
| BIG-UI-BRIEF | New screen, cross-platform UX, theme, major refactor: architect + curator parallel pre-briefs folded into one executor brief first. |
| RESOURCE-RELEASE | Whoever acquires (sim, emulator, gradle daemon, monitor, /tmp) releases proactively before the done report. |
| PR-AUDIT | God/principal audit every PR directly and post a comment addressed to the owning engineer. |
| SKILL-ROUTER | Mandatory skill hints must be invoked before any other action that turn. |
| IDENTITY-PROBE-FIRST v2 | Role comes from the session-ID marker file, never from window title or chat summary. |
Recent scars worth knowing (Sep 2026)
- A schema declared in a route file is not the schema the route enforces; read what the registered handler parses (dead
z.literal(30)misled four reviewers). - Tests that mock
apiFetchcertify the client's own wrong path; probe method + path on prod for 401-not-404 before "DONE". - A trigger or shared SQL function change needs the FULL dbtest suite once; read CI status before any trio verdict counts.
- A client-side role gate never closes a server-admitting-route finding.
- Persisting a formerly process-scoped fallback changes every
isBlank()gate that relied on the reset. - Any new browser origin or scheme needs a CSP connect-src / proxy allowlist check before PASS.
- Next page-module exports only fail at
next build; gates runpnpm buildwhen app routes change. - Fan-outs on the 16 GB Mac: max two full suites at once, vitest maxWorkers=1, pressure monitor armed, safe caches pruned before and after.
- Codex blocker-worker worktrees accumulate (26 GB once); prune merged/closed PR worktrees every campaign.
- A watcher prints its baseline on start and fails loud on query error; silence is indistinguishable from no change.
- Read flag values positively (value or /v1/config), never through a fail-open redaction.
- Probe live value formats on both sides before downgrading a matching finding (phone "+" prefix).
11. Scope fence, plan-first, minimalism
SCOPE-LOCK RULE (7 lines, every prompt)
- SCOPE: touch only the asked flow, no drive-bys.
- NO REFINEMENT of things not asked.
- NO OPTIMIZATION unless that is the task.
- FOCUS: adjacent problems get noted, not fixed.
- ZERO MISTAKES: verify before writing, never guess APIs or paths.
- REVISE: re-read the full diff line by line.
- AUDIT: compiles / tests / logic / scope self-check before "done".
PLAN-FIRST RULE (no size exemption)
- PLAN: goal, approach, files, success criteria before any code.
- SUB-TASK CHECKLIST as trackable items.
- EXECUTE in order, one in_progress at a time.
- TICK OFF only when verified. Never batch or pre-complete.
- REVISE the diff.
- AUDIT before declaring done.
Skipping the plan or the written checklist = task FAIL.
5-block SCOPE-FENCE (dispatch side)
PROBLEM
the exact defect or ask
DO-NOT
invariants that must hold, explicit non-goals
FILE-HINT
globs allowed to change (drift fence)
ACCEPTANCE
evidence-producing commands
REPORT
absolute report path + handoff rules
auto-scope-fence.sh reminds; acceptance_gate.py makes it durable.
Karpathy anchor (every code change)
- Think before coding: goal + assumptions + mechanical success criteria in 5 lines.
- Simplicity first: boring solution, no new abstraction without a one-line reason.
- Surgical changes: smallest diff, no bundled refactors.
- Goal-driven: verify mechanically; "compiles" is not done.
Minimalism ladder (7 rungs, injected every prompt)
- Reuse existing code in the repo
- Standard library
- Platform native API
- Already-installed dependency
- Config change instead of code
- Smallest new code
- New dependency, only with written justification, published 7+ days ago
LAYER-SELECTION GATE (pen 2026-06-25). Every brief carries
source_of_truth, correct_layer, touch_point_file. Mismatch between layer and file = stop and repick. Lazy-jump to the first-found file in the wrong layer is the forgotten-filter / leak class (sibling of 8.66).12. Founder standing rules (global, all agents)
| Rule | Pen | Meaning |
|---|---|---|
| no-em-dash | 2026-07-10 | U+2014 never appears anywhere: chat, code, UI, commits, reports. Replace when touching a line that has one. principal-merge lints squash subjects for it. |
| just-do-it, never-ask-obvious | 2026-07-25 | A given task is pre-authorized end to end including every step it surfaces. Ask only on: missing credential, destructive + irreversible with no rollback, founder-domain product decision, spend outside scope. |
| no-hardcode | 2026-07-24 | Single source of truth for every value that must match elsewhere (enum, event name, status, route, key). Named constants for one-offs. Config/env for deployment-specific values. Cross-file literal copy is a P1 drift bug. |
| question-codex | 2026-07-22 | Never blindly follow any automated reviewer. Triage, judge severity yourself, push back with evidence, stop patching after repeated holes and redesign the primitive. |
| resource-hygiene | 2026-07-14 | Clear safe caches (DerivedData, gradle caches, build artifacts, sims, emulators) before and after heavy builds without asking; kill daemons post-build; never kill MobAI-Runner. |
| skills-first | - | If a skill covers the task, invoke it; never re-implement what a skill does. |
| no over-engineering | 2026-09-16 | Minimum fix that closes the real P0/P1; extras and P2/P3 to backlog, briefs say so explicitly. |
| Sonnet 5 for new sub-agents | 2026-09-15 | Every new sub-agent / Workflow agent runs on Sonnet; never interrupt running work to re-model it. |
| Money-path strictness | - | Auditors disagree: take the stricter verdict. PAID_AT_VENUE obligations stay PENDING and every sweep exempts them. Dunning retry never advances settlement state. Stripe idempotency key from a pre-advance counter. |
| Codex appreciation | 2026-08-13 | Genuinely useful codex catches get a thumbs-up and a short @codex ack (founder posts reactions personally; agents surface the suggestion). |
| Maestro in parallel | 2026-08-13 | Every manual on-device tap-through is an authoring pass for a Maestro flow committed in the same PR; stale flows = FAIL. |
13. Transport: Conductor and the inbox contract
Naming and routing
- Brief pointer:
agents/inbox/<from>-<to>-<topic>-<unix>.md. FROM is first; non-conforming names are silently quarantined (agents/inbox/quarantine/). - Body lives in
agents/briefs/<topic>.md; the inbox file holds onlyFROM:+ a 📎 absolute path. Payloads over 1500 B are auto-extracted to pointers. Truncation is pipeline-state-bound, so always author pointers. - Conductor reskins into a chat header (
principal → backend · topic), dispatches one chunk, moves the file toprocessed/, and relays worker completion to principal asprincipal-relay-<pane>-<unix>.txt. - Reports:
agents/reports/<pane>-<topic>-<unix>.mdwith frontmatter (title, verdict, trace_id, audited_commit, handoff_to / handoff_reason / handoff_priority).
Reliability features
- launchd-supervised (
com.snook.conductor), kill-and-revive proven; watchdog + supervisor + health JSON. - Per-pane dispatch mutex; busy-vs-wedged detection; deliver-on-idle at-most-once; defer/backoff with a 2 h abandon backstop.
- Bracketed-paste TUI injection (ESC[200~ + Enter outside paste) with a screen-contents typing probe; half-type detection raises a deliverability alarm in the digest.
- Hijack blocklist on pane titles (deploy-chat, cowork, etc.); tier logging in
dispatch-log.jsonl; ledger append on every dispatch, merge and wake. - Brief lint pre-dispatch (schema in
agents/tools/brief-schema.json); malformed briefs are quarantined, never delivered.
14. Observability and ledgers
| Surface | What it tells you |
|---|---|
agents/reports/founder-dashboard.md + digest-YYYY-MM-DD.md | Daily push surface (STATUS-WINDOW): cost per pane, held items, stale doctrine drafts, harness audit verdict, deliverability alarms, founder-interruption weekly trend, conductor liveness, dispatch analytics. |
agents/state/decision-ledger.jsonl | Every gated action (dispatch, merge, wake, deploy) as a line; harness audit warns on unledgered actions. |
harness_audit.py, fleet_health_probe.py, pane_health_check | Is the meta-layer itself healthy: hooks registered, prompts byte-identical to compiled artifacts, remote CI state, MEMORY.md size. |
dispatch_analytics.py | Retry storms, hijack hits, tier hits, handoff violations, undelivered briefs. |
agents/state/behaviour-audit-*/results.json | Founder-batch feature scorecard: per-row PASS / FAIL / BLOCKED / PARTIAL with probe, observed, evidence, root cause, fix surface. |
agents/evidence/<run>/ | Screenshots, payload captures, headed-browser proofs. Evidence is the truth; report prose is a claim. |
agents/chain-*.json | Handoff chains per workstream (162), visualized by chain_visualize.py. |
| Sentry MCP, /health SHA check, GitHub deployments API | Production truth: live backend SHA at api.snookalook.com/health, Vercel production deployments for admin and web. |
cost_report.py, quota_watch.py | Spend per pane (informational, no budget cap by founder directive) and claude-to-codex quota failover. |
15. Fleet modes and single-man-army
Launch modes (agents/snook-up.sh)
- pilot-hot (default): 9 panes + conductor hot.
- lean: principal + god + conductor.
- custom: mixed claude / codex runtime per pane (
SNOOK_AGENT_RUNTIME=codexpanes have no hooks; server rulesets + principal-merge are the only guards). - founder-batch: campaign layout for the feature scorecard.
Prompt stack actually served: SILENCE_PREAMBLE + slim-prompts/<pane>.prompt.txt + common.md + pane capsule. The legacy <pane>-prompt.txt is the escalation reference.
Single-man-army mode (this session)
Trigger phrases: "god founder rely only" or "as single man army". One pane executes directly on a cut feature branch, founder-direct, no relay layer.
Not exempt from review. Solo code still carries a pre-code sub-architect + sub-curator refine and a mandatory kk code-review pass on the diff; codex still reviews the PR; principal-merge.sh still gates the merge; the 5 founder categories still hold.
Degraded fallback when sub-agents are unavailable: self-authored SCOPE-FENCE + minimalism ladder + karpathy anchor pre-code, kk pass once dispatch recovers.
16. State today (2026-09-26, live probes)
Repos
backend
dev == main (live SHA era 64dd95c5, PR501 tx budget + PR503 no-store headers)
web
dev == main (PR112 to 118 promoted 09-24/25)
admin-web
dev == main
mobile
dev = master + 13 (PR288 to 301: Now chip, deep links, StateKeeper, reroute refetch). master tag v1.1.8. Founder pen needed to cut.
Open PRs
web #98
fu175 server-bypass observability. Codex approved thread closure at head 8aaf52b1; 13 behind dev, CONFLICTING (needs merge-from-dev, not rebase).
admin #244
DRAFT HOLD: X04 duration state, waits on PR239 lifecycle + Custom contract discrepancy.
Behaviour audit scorecard
PASS 111 · BLOCKED 10 · DROPPED 5 · FAIL 2 · NOT_SHIPPED 2 · PARTIAL 1. The two FAILs (W3-04, W5-14: mobile Now chip) are fixed in dev by backend #499 (live) + mobile #298 (not yet on master, phone build 1.1.6 lacks it).
Backlog FU (open)
FU-359 P1
Cloudflare Page Rule 35b1b863 (api /v1/clubs* cache_everything, 2 h TTL) overrides no-store. Founder-side: dashboard bypass/delete or a write-scoped token.
FU-355 P2
collect-cash completes a booking without releasing the table session on the wedge path.
FU-357 P2
early-closed session freezes a 0-fils bill while 3000 fils cash was captured pre-close.
FU-356 / 358 P3
early-start dialog copy wrong; early start dead under 30 min.
Harness health: disk 5.6 GiB free (68%); codex_monitor.log recorded an ENOSPC crash and the monitor respawned; harness audit verdict FAIL (8 hook surfaces), local-CI last run FAIL. Codex worktrees: web 20, mobile 15, backend 7, admin 5. Nothing has been acted on in this session by instruction.
17. Glossary
| Term | Meaning |
|---|---|
| Pen | A verbatim founder ruling, dated. The only way doctrine becomes LIVE or changes. |
| Brief | One-screen task contract (goal, audit-first, canonical source, scope, acceptance, report, tier, layer fields). |
| Pointer dispatch | Inbox file containing only FROM + an absolute path to the brief body. |
| Trace id | Workflow identifier that ties briefs, audit reports and the merge log together; principal-merge matches receipts by it. |
| Trio | Architect + curator + kk pre-PR audits at the exact commit. |
| kk | The independent code-reviewer role (capsule-loaded sub-agent). Always reviews the final head. |
| kk-codex lane | Merge lane for PRs touching no sensitive path: kk report + codex clean, no curator/architect. |
| FU-NNN | Follow-up backlog entry under agents/backlog for P2/P3 findings and deferred work. |
| Scar | A feedback_*.md memory entry: what went wrong, why, how to apply. |
| Capsule | The compressed per-pane doctrine loaded at boot (pane-doctrine/<pane>.capsule.md). |
| Receipt | Machine-checkable evidence of an action or state (SHA-tied report, ledger line, screenshot path). |
| TICK-1 | The 10-item checklist god/principal run on every report landing. |
| Cadence merge | dev to main promotion for backend/admin/web, audit-gated, no per-merge founder pen. |
| Master cut | Mobile dev to master merge + annotated semver tag; founder pen per cut. |
| Wedge path | A failure branch where a transaction dies mid-way and leaves inconsistent state (e.g. table IN_PLAY on a COMPLETED booking). |
| Falsifier | A reviewer whose brief is to try to break the fix, not to confirm it. |
| Codex round cap | Two reviewed heads; after that an engineer triage verdict stands in. |