--- title: "feat: Activate native self-driving AINA Paperclip factory" type: feat status: active created: 2026-06-30 origin: docs/aina-factory-archive-2026-06-30/aina-factory-native-selfdriving-design-2026-06-30.md target_repo: aina-paperclip-agent-context (+ Paperclip control plane, company 7d58fc13-7c9a-4c87-b9f8-a7cfae8564a9) depth: deep --- # feat: Activate native self-driving AINA Paperclip factory **Target systems:** the Paperclip control plane (via `paperclipai` CLI) + the `aina-paperclip-agent-context` repo on the VDS (`aina-vds-tf`). This is infrastructure/configuration work, not application code — "tests" are **self-drive verification** (does a lane run end-to-end with no external nudge?), not unit test files. --- ## Problem frame The native, ANMS-spec-driven, handoff-wake factory **worked on 06-29** (agents coordinating through Paperclip handoffs + wake, gated by canon-locked Gherkin specs). It broke on **06-30** when a per-task GitHub apparatus (commit+push+PR per task → CI → bot-review-watcher → a jam then stacked with Mergify/merge-train/release-marshal) replaced the native model — verified via the botfix churn metric (3 → 61) and Ali's own words. The external scaffolding is already **torn down and paused**; the 70-item in-review backlog is already **cleared** by parallel verifiers. This plan **activates the native design** (origin doc) so the factory self-drives on Paperclip's own primitives with zero external scaffolding — **restore, don't rebuild**. ## Scope boundaries **In scope:** activate the `agent-context-map` per **dev lane** (content-curriculum, data-personalization, product-platform, agentops-tools, qa-release); un-pause + re-point the 7 native routines off the Hermes bridge to native assignment/wake; wire the flow (CEO → heads → members → QA → Frodo release at milestone); always-on for Jessica + heads + one keeper (Atlas); remove the Hermes bridge + all remaining external scaffolding; GitOps (incl. Mergify) relocated into Frodo's milestone runbook. ### Deferred to Follow-Up Work - **growth-media (marketing) + security/legal lanes** — remain draft/parked until Ali approves public/legal lanes; they need **no git/PR/CI**. - **Docker** containerization of lanes — validated capability, parked; not part of this activation. - **PKM-nightly-to-VDS** — separate adjacent decision. - **Canon reconciliation** of the scratch-flagged doctrines into CANON-INDEX — a canon-steward (Finch) task, not this plan. ### Outside this plan's identity - Any per-task GitHub PR/CI, any external cron/watchdog/bridge, any script-based orchestration. If a job needs doing, a Paperclip **agent** does it on a native **routine**. --- ## Key technical decisions 1. **Native primitives replace every external script** — `routines`/`triggers` (was COO cron), `agent wake`/heartbeat (on assignment/@mention), `issue comment`+`interaction:create`+`successfulRunHandoff` (inter-agent handoff), `child:create`+issue-tree (decomposition), `recovery-actions` (was watchdog), `approval` (founder gates), `org` chart (leads). 2. **Hybrid, team-head-driven** — a minimal keeper routine (Atlas) only surfaces ready/stalled work + fires recovery; **heads route** (assign N members per task, first-verify in-team). 3. **Always-on ≈ 9** — Jessica + department heads + Atlas keeper. Everyone else wakes on assignment/@mention (not heartbeat). 4. **Option (b) release** — dev inner loop internal (no per-task git); branches/PRs only as *evidence* where a lane needs them; **Frodo's team owns all GitOps (incl. Mergify) at milestone granularity**; `dev→main` batch promotion via release runbook; preview URLs via wrangler; marketing/media git-free. 5. **Producer ≠ verifier**, enforced by the map's default-verifier pairing + `aina-runsafe-gate` before every wake/assign/handoff. 6. **Lane-by-lane, reversible** — each activation is a config apply with Paperclip receipts; content-curriculum is already applied+verified and is the reference lane. 7. **Workspace/git mechanic (verified 06-30) — the drift cause + the gate on U4.** Paperclip runs each issue in an isolated per-issue workspace **derived from the issue's assigned PROJECT (a git repo; 57 projects exist)**. If an issue has **no `projectId`**, its workspace defaults to **home/codex-home → plugin re-discovery → bloat/drift** (this is the "fall back to codex-home" failure). Current state: 216/263 issues project-bound; **47 have no project**. The watchdog's `git-init` self-heal was a band-aid for the project-less ones. **Therefore every active dev-lane issue must be project-bound (native git-backing) BEFORE the watchdog is removed (U4).** Keep isolated-workspaces **on** (per-issue isolation is correct); the fix is project-binding, not toggling it off. Docker is verified **parked/non-interfering** (0 containers, not in the execution path) — keep parked. --- ## High-level design (directional, not implementation spec) ``` Native routine (keeper: Atlas) surfaces ready work ─┐ ▼ CEO Jessica ── org-chart ── Dept Head ── issue:update --assignee (+ child:create) ── Member │ first-verify (comment/interaction) │ wakes, builds └──────────────── handoff (successfulRunHandoff) ─────────┘ ▼ QA gate: Gimli (adversarial) → Éowyn (visual/E2E) → Calibrator (2nd-verifier vs canon+PKM) ▼ Frodo Release/GitOps team ── AT MILESTONE ── branches/PR/CI/Mergify · runbook · dev→main · deploy · preview URL ▼ recovery-actions self-heal any stalled issue (no watchdog) ``` *This illustrates the intended approach and is directional guidance for review, not implementation specification.* --- ## Implementation units ### U1. Reconcile activation prerequisites (read-only) **Goal:** pin the exact facts the activation needs, so no unit guesses at runtime. **Requirements:** advances all downstream units. **Dependencies:** none. **Files:** (control-plane reads only) `paperclipai routine get ` for all 7 routines; `paperclipai org get`; `aina-paperclip-agent-context/mappings/agent-context-map.md`. **Approach:** capture (a) each routine's current **trigger** structure + `assigneeAgentId` (to know what "re-point off Hermes" changes), (b) the **qa-release head** name (Root/Gimli/Frodo split — confirm from the map/org), (c) which lanes are `applied-live-verified` vs `mapped-not-applied`, (d) the exact `aina-runsafe-gate` + scope-precheck invocation from `AGENTS.md`, (e) **the 47 project-less issues — which lanes they belong to** (dev = must-fix before U4; marketing/parked = out of scope), and the project→lane binding map (57 projects). **Verification:** a short reconciliation note listing each routine's trigger, the confirmed heads per dev lane (content=Monica), the runsafe-gate command, and **the list of project-less dev issues needing binding** — no unknowns remain for U2–U7. **Test scenarios:** `Test expectation: none — read-only reconciliation.` ### U2. Content-curriculum lane — prove native self-drive end-to-end **Goal:** make the *already-applied* content-curriculum lane run a real task fully self-driven, as the reference implementation every other lane copies. **Requirements:** KTD 1,2,5; the "restore what worked" thesis. **Dependencies:** U1. **Files:** Paperclip control plane (issue assign/comment/interaction on a content-curriculum goal); `aina-paperclip-agent-context/lanes/content-curriculum/`. **Approach:** place/pick one ready content-curriculum issue → **head Monica** assigns a member (`issue update --assignee`) → member **wakes** (native), builds in scoped workspace → Monica **first-verifies** in-team (comment/interaction) → **handoff** to QA → mark done. No external nudge, no git. Confirm each hop fires natively. **Patterns to follow:** the map's content-curriculum default-verifiers (Monica); the assignment-envelope template. **Test scenarios (self-drive verification):** - Happy path: a ready issue flows assign → wake → build → verify → handoff → done with **zero** operator action after the head assigns. - Wake: the assigned member's heartbeat/inbox fires from the assignment alone (no `agent wake` script). - @mention: a comment tagging a second agent wakes it and it responds. - Producer≠verifier: the member and Monica are different agents; runsafe-gate passes. - Negative: an issue with no assignee does **not** auto-run (heads route, not the keeper). **Verification:** one content-curriculum issue reaches `done` via native handoff-wake only, with Paperclip activity-log evidence for each hop. ### U3. Re-point the 7 routines off Hermes + set always-on **Goal:** the native scheduler runs without the Hermes bridge; the right agents are always-on. **Requirements:** KTD 1,2,3. **Dependencies:** U1, U2. **Files:** Paperclip routines (7) via `paperclipai routine update` / `trigger:update`; agent heartbeat config for Jessica + heads + Atlas. **Approach:** for each routine, replace the **Hermes-bridge dispatch** with a native action (assignment/wake/`child:create`) and **un-pause** only those that serve dev lanes now (Atlas keeper, Gimli verify, Éowyn E2E, Frodo release; Donna digest/cost = monitor-only; Finch canon; hold marketing-adjacent). Set **always-on heartbeat** for Jessica + department heads + the Atlas keeper; keep everyone else on-demand. **Patterns to follow:** the existing routine descriptions (owner/cadence intent) — preserve intent, swap the dispatch mechanism. **Test scenarios (self-drive verification):** - Keeper (Atlas) surfaces a ready/stalled item to the correct head **without** touching the Hermes bridge. - A stalled issue triggers native `recovery-actions` (no watchdog). - Always-on set = Jessica + heads + Atlas only; a non-lead member is **not** heartbeating. - No routine references or calls the Hermes bridge after update. **Verification:** `routine list` shows the dev routines `active` with native triggers; Hermes bridge receives zero calls over one keeper cycle; always-on roster is exactly the intended ~9. ### U4. Remove the Hermes bridge + all remaining external scaffolding **Goal:** delete every external orchestration surface so nothing outside Paperclip can nudge the factory. **Requirements:** "zero external scaffolding" scope. **Dependencies:** U3 (native path proven first) **AND U8 (project-binding done — the watchdog's git-init safety net can only be removed once workspaces are natively git-backed).** **Files (VDS):** `/srv/aina/ops/` (coo-ops-loop.sh, watchdog.sh, release-marshal.sh, pr-bot-watcher.sh, merge-train lanes), crontab, the Hermes↔Paperclip bridge / kanban_decomposer, hermes dispatch loop. **Approach:** confirm crons already paused → **retire** (archive + remove) the external scripts; disable the Hermes bridge dispatch path (kanban_decomposer); ensure hermes stays only as Donna's monitor/assist surface (systemd, no dispatch). Leave the GitHub bots disabled (already `disabled_manually`). **Test scenarios (verification):** - After removal, a placed issue still flows end-to-end (native path carries it) — proves nothing depended on the scaffolding. - No cron, no watchdog, no bridge process participates in dispatch. - hermes gateway still up (monitor-only) via systemd `Restart=always`. **Verification:** crontab has no factory dispatch/merge/watch entries; no external process appears in a dispatch trace; a full lane cycle completes with scaffolding gone. ### U5. QA gate wiring (Gimli · Éowyn · Calibrator) **Goal:** the cross-lane QA gate runs as native verifier assignments after a head's first-verify. **Requirements:** KTD 5; producer≠verifier. **Dependencies:** U2. **Files:** Paperclip control plane (verifier assignment/interaction); the qa-release lane bundle. **Approach:** on head handoff, the issue routes to **Gimli** (adversarial) → **Éowyn** (visual/E2E, may run staging preview per milestone) → **Calibrator** (2nd-verifier vs canon+PKM) before `done`/promotion-eligible. Each is a **separate** agent from the producer; `aina-runsafe-gate` blocks producer=verifier. **Test scenarios (self-drive verification):** - A handed-off issue is picked up by Gimli via native assignment/wake (no script). - A verifier rejection sends the issue **back** to the lane (native), not to a merge. - Producer=verifier is blocked by the runsafe-gate. - Éowyn's E2E can target a wrangler staging preview when the issue is release-bound. **Verification:** an issue traverses head-verify → Gimli → Éowyn → Calibrator → eligible, with a rejection round-trip demonstrated once. ### U6. Frodo Release/GitOps team + milestone runbook **Goal:** all git operations (incl. Mergify) live in Frodo's team and fire **per milestone**, promoting `dev→main` in batches with a preview URL. **Requirements:** KTD 4; option (b). **Dependencies:** U5. **Files:** the qa-release/Frodo lane bundle; a release runbook doc in `aina-paperclip-agent-context/lanes/qa-release/`; the (relocated) `.mergify.yml` scoped to release branches; wrangler preview/deploy invocation. **Approach:** define Frodo's runbook: at milestone/epic close, gather the verified work → run CI/Mergify **once** on the release branch → promote `dev→main` (deploy source) → post the Cloudflare **preview URL** to Ali along the way. Mergify is a **release** tool here, not a per-task gate. Marketing/media never enter this path. **Technical design (directional):** milestone-gate = all lane issues for the milestone `done` + QA-passed → Frodo assembles release branch → CI/Mergify → promote → deploy → notify Ali (preview + prod). *Directional only.* **Test scenarios (verification):** - No git operation fires at the task level; the first git action is Frodo's milestone assembly. - A milestone with all issues verified triggers exactly one release cycle → preview URL delivered. - Mergify runs only on the release branch, not per-task PRs. - A marketing issue completes with **no** branch/PR/CI. **Verification:** one simulated milestone promotes `dev→main` via Frodo's runbook with a single CI/Mergify pass + preview URL; zero per-task git in the trace. ### U7. Replicate lane-by-lane to remaining dev lanes **Goal:** apply the proven pattern to data-personalization, product-platform, agentops-tools. **Requirements:** full dev-lane coverage. **Dependencies:** U2–U6 proven on content-curriculum. **Files:** `agent-context-map` apply per lane; per-lane heads (Laurie/data, Richard/platform, Jared/agentops). **Approach:** for each lane in order, apply the map (role/verifier/scoped context), confirm the head, and run the U2 self-drive verification. Prove each lane self-drives before the next. Preserve the ~20 rejected + never-built tasks — they re-enter the restored native flow, not the old GitHub path. **Test scenarios (self-drive verification):** per lane, repeat U2's happy-path + producer≠verifier + no-per-task-git checks. **Verification:** each dev lane completes one real issue end-to-end natively; growth-media/legal remain parked. --- ### U8. Guarantee new dev issues inherit a project (git-backed workspaces) **Goal:** every *new* dev-lane issue inherits its lane **project** so its isolated workspace is git-derived — closing the home/codex-home fallback (the drift) natively, so the watchdog's git-init band-aid can be removed. **Requirements:** KTD 7; safe removal of U4. **Dependencies:** U1. **Note (U1 finding):** the 47 project-less issues are **all done/cancelled — zero active**. All active/future work is already project-bound. So this unit is *lighter than first scoped*: no backfill needed; the job is **default inheritance for new issues** only. **Files:** Paperclip control plane (lane/goal → default project binding); the 57 projects ↔ lane map. **Approach:** for each dev lane, set the goal/lane default so a newly-created issue inherits the correct lane project (Curriculum→content, Data Engine Room→data, Platform Engineering→platform, AgentOps→agentops, qa-release→Frodo). Verify a fresh test issue lands git-backed with no git-init. (Historical project-less issues are done — left as-is.) **Test scenarios (verification):** - A newly-created dev issue in an activated lane inherits a project → its workspace is git-backed with no git-init step. - A previously project-less dev issue, once bound, passes `codex_local` workspace validation. - With the watchdog OFF (simulated), a project-bound issue's agent does **not** fall back to home/codex-home. **Verification:** zero project-less **dev** issues remain; a sample agent run produces a git-backed workspace and no codex-home fallback, with the watchdog inactive. --- ## System-wide impact - **Agents/heads:** Jessica + heads become always-on; members become wake-on-assignment — a behavioral shift from the 06-30 push model. - **Cost:** always-on ≈ 9 (not 62); GitHub minutes → ~0 between milestones; no per-task CI churn. - **Founder surface:** Jessica/Donna produce founder-readable digests (no `/srv` paths); preview URLs at milestones. - **Reversibility:** every lane activation is a receipted config apply; the removed scripts are archived, not destroyed. ## Risks & mitigations - **Native wake doesn't fire as expected** → U2 proves one lane end-to-end *before* removing scaffolding (U4 depends on U3/U2). If wake is unreliable, stop at U2 and diagnose — do not remove the safety nets. - **Re-pointing a routine breaks its intent** → U1 captures each routine's current trigger; changes preserve owner/cadence intent, swap only the dispatch mechanism; reversible via `routine revision:restore`. - **A lane self-approves** → runsafe-gate + producer≠verifier enforced; U5 demonstrates a rejection round-trip. - **Removing scaffolding strands in-flight work** → U4 verifies a full cycle completes *after* removal; backlog already cleared. ## Deferred to implementation - Exact `routine update` payloads / trigger JSON (captured in U1, applied in U3). - The qa-release head name (confirmed in U1). - Whether Éowyn's E2E routine deploys its own wrangler preview or reuses Frodo's (decide when wiring U5/U6). - Keeper (Atlas) cadence — start conservative, tune after U2. ## Verification (overall) Success = a goal placed in a dev lane flows head → member → QA → (at milestone) Frodo release + preview URL, **with no external nudge, no cron, and no per-task GitHub roundtrip**; stalls self-heal via `recovery-actions`; an @mentioned agent wakes; zero `.botfix` churn; zero GitHub-minutes burn between milestones. --- **Origin:** `docs/aina-factory-archive-2026-06-30/aina-factory-native-selfdriving-design-2026-06-30.md` (LOCKED design) · reconciled + verified across the full session + prior-session history.