🍊😺

Chapter 7: Implementation plan

Updated: 2026-06-07 · Executes Chapter 6 Phase A. Designed to be run by Codex on obot's OpenClaw machine.

Goal: complete one reliable PM→Dev→PR cycle on Codex-native execution plus a thin supervised runner — and pass Chapter 3's Triggered/Started/Completed taxonomy and Chapter 5's "Started vs triggered" + "Stall detection" acceptance tests without Paperclip. Passing this earns the Chapter 5 pilot. The keystone deliverable is a failure-injection test that proves a stalled run is detected and reported without Jeremy asking.

Non-goals (this phase)

Target architecture for this phase

ComponentRole this phaseConcrete form
OpenClaw main obotTelegram intake + scheduler + notifier. Not the executor.Cron wakes a launcher / posts alerts; systemEvent wake path only (Chapter 3).
Supervised runnerStarts a worker, writes a run-record, heartbeats, enforces a deadline, recovers.New scripts/run_codex_cycle.py, extending the existing scripts/work_session.py ledger.
WatchdogReads run-records, flags stalled/triggered-but-not-started, emits one alert.scripts/check_runs.py (or a --watch mode on the runner), run by cron.
Dev executorIsolated, audited code execution → PR.Codex cloud @codex on an issue/PR, or a Codex Automation in a dedicated worktree.
PM executorPortfolio audit → durable artifact → Dev target or decline.Codex local (non-interactive) wrapped by the runner; output is a GitHub issue comment.
GitHubSource of truth + audit.Project / Requirement / Task issues; PR + Codex task log are the Dev evidence.
Run-records dirDurable ledger of every run's state.runs/<run_id>.json + transcript log, local + linked in issue comments.

Phase 0 — Demote cron, scaffold the ledger ~30 min

  1. Edit the autonomous cron jobs so they only wake main obot or start the launcher script — never run a long PM/Dev agentTurn directly (Chapter 3 root cause).
  2. Create a durable run-records directory and decide its schema (below). Reuse scripts/work_session.py fields where they already exist (target, session ref, checkpoint, liveness, evidence, recovery).
  3. Create the GitHub issue set for this cycle pilot:
    • Project: "Reliable autonomous cycle (execution-first)".
    • Requirement: "Supervised Codex runner + watchdog with stall detection".
    • Task: "Failure-injection acceptance test".
    • Task: "PM dry-run audit artifact".
    • Task: "Dev docs-only PR via Codex-native execution".
Run-record schema (runs/<run_id>.json): 
{
  "run_id": "2026-06-08-pm-01",
  "role": "pm | dev",
  "target_issue": "obot-claw/obot-claw.github.io#NN",
  "repo": "obot-claw/...",
  "executor": "codex-local | codex-cloud",
  "state": "triggered | started | completed | failed",
  "started_at": "ISO-8601 or null",
  "heartbeat_at": "ISO-8601, updated every N seconds",
  "deadline_at": "ISO-8601 (started_at + timeout)",
  "artifact": "PR url / issue-comment url / audit file path / null",
  "failure_reason": "string or null",
  "recovery": "what the watchdog/obot should do on stall"
}

State rule (Chapter 3): only started counts as active; only completed counts as useful work. A record stuck in triggered past a short grace window is a failure, not progress.

Phase 1 — Supervised runner core deliverable

  1. Write scripts/run_codex_cycle.py. Inputs: --role, --issue, --repo, --timeout, --prompt-template, --write-scope.
  2. On start: write the run-record as triggered, launch the Codex CLI non-interactively as a managed subprocess, then flip to started once the process is confirmed running.
  3. Emit a heartbeat (update heartbeat_at + append a transcript line) every N seconds while the subprocess lives.
  4. On clean exit with an artifact: write completed + artifact link. On timeout/crash/no-artifact: write failed + failure_reason.
  5. Use a fresh worktree/clone for any write task; never mutate a dirty unrelated clone (Autonomy L3 rule).

Exit: a manual PM dry-run writes a run-record and either an audit artifact or a clear failure reason. Keep it boring; this is a supervisor, not a platform.

Phase 2 — Failure-injection test the keystone

This is the test Chapter 3 said we have never passed and Chapter 5 lists as an acceptance gate. Do it on the cheap substrate first.

  1. Run the runner against a deliberately stalling prompt (or kill the subprocess mid-run) so it stops heart-beating before producing an artifact.
  2. The watchdog (scripts/check_runs.py on a short cron) must detect: (a) triggered that never reached started, and (b) started with a stale heartbeat_at past deadline_at.
  3. On detection it flips the record to failed, writes a failure artifact, and emits one concise (<500 char, plain-text) Telegram alert via obot — without Jeremy asking.

Pass = "Started vs triggered" and "Stall detection" from Chapter 5, satisfied with no Paperclip in the loop.

Phase 3 — PM dry-run (authority L2)

  1. Runner starts the PM role: read the Roadmap, open issues, and Hub state (reuse scripts/portfolio_audit.py).
  2. PM produces a durable audit artifact as a GitHub issue comment and either selects one Dev target or declines with a reason.
  3. obot sends a Telegram summary only after the issue-comment artifact exists.

Phase 4 — Dev cycle via Codex-native (authority L2/L3)

  1. Pick a safe documentation-only task in obot-claw.github.io (no secrets, deterministic check).
  2. Drive it Codex-native: tag @codex on the task issue, or run a Codex Automation in a dedicated worktree → one PR. No merge.
  3. The PR + Codex task log are the durable evidence; link them back into the run-record and the issue.
  4. L3 (implementation PR) only if the parent Requirement already approves implementation scope; otherwise keep it an L2 draft/docs PR.

This is the half Codex 2026 already solves natively (isolated worktrees, scheduled automations, issue→PR, PR-as-audit) — lean on it instead of hand-building.

Phase 5 — Wire daily PM→Dev (only after a manual pass)

  1. Daily PM cron wakes main obot or runs the launcher that starts the supervised runner.
  2. A watchdog cron checks the run-record after 5–10 min; a stall produces a visible alert, never a false "active" claim.
  3. If PM completes with a safe Dev target, the launcher starts Dev through the same supervised runner.

Graduation gate → Chapter 5 pilot

CriterionPass condition
One real cycleA PM→Dev→PR cycle completed with liveness evidence at each step.
Stall detectionFailure-injection test flips to failed + alerts, unprompted (Phase 2).
No false statusNothing was reported "active" without a started record + concrete evidence.
GitHub artifactsAudit comment + PR exist and are linked from run-records.
Telegram hygieneSummaries are <500 char plain text, sent only after a durable artifact.
When all five pass, proceed to Chapter 5 and run the Paperclip pilot as a control-plane comparison against this runner, scored on the Chapter 6 go/no-go gates.

Authority & stop conditions

Follow the Autonomy operating contract: default block authority L2; L3 only where the parent Requirement approves implementation; merges stay review-gated. Stop and report (don't push) if requirements are ambiguous, checks fail without a clear fix, work needs non-obot-claw writes, private data could be exposed, credentials/tooling are blocked, or work exceeds the active Requirement scope.

Deliverables checklist

Rollback / what not to do

Hand-off to the next session

First actions for Codex on obot's machine: (1) create the Phase 0 GitHub issue set; (2) demote the autonomous cron jobs to wake/notify; (3) scaffold scripts/run_codex_cycle.py + the run-record schema above; (4) run the Phase 2 failure-injection test and capture the alert as evidence. Report back with the run-records and issue/PR links — that evidence is the go/no-go input for the Chapter 5 Paperclip pilot.

Notes from obot for next Codex session

Start here: Jeremy confirmed Chapter 6/7 execution-first sequencing. The next session on obot's machine should implement obot-claw.github.io issue #38: scaffold the supervised Codex runner and run-record ledger. Do not install Paperclip first.