From 39bad7d2f3e42608dfb015248c23e5f3cb548093 Mon Sep 17 00:00:00 2001 From: Bo Date: Sun, 24 May 2026 21:15:43 -0400 Subject: [PATCH] =?UTF-8?q?docs(3.0):=20ag-p7j=20W2=20=E2=80=94=20reframe?= =?UTF-8?q?=20core=20narrative=20docs=20to=20in-session=20(ag-p7j)=20(#527?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What Worker 2 of the ag-p7j 3-way swarm reconciling stale daemon/scheduler references for AgentOps 3.0. Reframes stale `ao daemon` / `agentopsd` / `ao schedule` / `ao overnight` prose across 7 core narrative docs to the **in-session model**: the loop runs in session (the product + sovereignty floor); always-on / scheduled / unattended execution is delegated to an orchestration substrate (Gas City is the reference City), not an AgentOps surface. Those daemon/scheduler/overnight-runner surfaces were deleted in the 3.0 rearchitecture (ADR-0009). Mirrors `docs/3.0.md`. ## Files (7, prose only) - `docs/software-factory.md` — Runtime Variants daemon-submit lane → in-session `ao rpi phased`; Surface Map drops `ao daemon submit`, adds an out-of-session (substrate) row; "both paths" note now in-session + Gas City delegation. - `docs/cdlc.md` — SDLC→CDLC table: "Software factory daemon (`ao daemon`)" → in-session loop run on a substrate (Gas City reference). - `docs/how-it-works.md` — Dream split intro + "Dream — Private Overnight Operator Mode" section reframed from `ao overnight` to in-session `/dream` + CLI primitives; unattended = Gas City substrate. - `docs/philosophy.md` — `/dream and ao overnight` → `/dream` in session, out-of-session compounding on Gas City. - `docs/first-value-path.md` — intro item 6, Time-Budget row, Step 7 "Optional Scheduled Lane" (`ao daemon run` / `ao schedule`) → "Optional Out-of-Session Lane" (Gas City mayor/refinery); First-Artifacts and Friction rows updated. - `docs/workflows/session-lifecycle.md` — Option 3 "Bedtime Dream Run" (`ao overnight setup/start/report`) → "Dream Compounding Run" (`/dream` foreground); runtime-modes table row updated. - `docs/architecture/ports-and-adapters.md` — Autonomous-loops adapter bullet: `agentopsd daemon scheduler` removed; `/dream`,`/evolve` framed as in-session driving adapters with out-of-session delegated to the substrate. No links to deleted daemon contracts existed in these files (verified). No edits outside the 7. ## Gates - `grep -E "ao daemon |agentopsd|ao schedule"` across the 7 files: **CLEAN** (also clean for `ao overnight`/`ao plans`/`ao watch`/`schedule.yaml`/`--with-schedule`). - `markdownlint` on the 7 files: **PASS** (exit 0). - `mkdocs build --strict`: **PASS** (exit 0; only the generic Material upgrade banner, no link warnings/errors). - doc-release gate (`tests/docs/validate-doc-release.sh`): **PASS**. - learning-references check: **PASS**. Diff stat: 7 files, +65/-72 — balanced, no collateral data loss. Closes-scenario: ag-p7j#w2-core-docs Bounded-context: BC1-Corpus Evidence: docs/software-factory.md --- docs/architecture/ports-and-adapters.md | 2 +- docs/cdlc.md | 2 +- docs/first-value-path.md | 48 ++++++++++--------------- docs/how-it-works.md | 28 +++++++-------- docs/philosophy.md | 2 +- docs/software-factory.md | 17 +++++---- docs/workflows/session-lifecycle.md | 38 ++++++++++---------- 7 files changed, 65 insertions(+), 72 deletions(-) diff --git a/docs/architecture/ports-and-adapters.md b/docs/architecture/ports-and-adapters.md index 176223e72..980868c86 100644 --- a/docs/architecture/ports-and-adapters.md +++ b/docs/architecture/ports-and-adapters.md @@ -22,7 +22,7 @@ Primary adapters drive the domain from the outside: a human, an agent, or a work - **CLI commands** in `cli/cmd/ao/` — every `ao ` is a driving adapter. - **Slash commands** in `skills/` — invocations like `/plan`, `/discovery`, `/validation`, `/vibe`. - **MCP** — Model Context Protocol entry points exposed by `ao` and by skills. -- **Autonomous loops** — `/dream`, `/evolve`, the `agentopsd` daemon scheduler. +- **Autonomous loops** — `/dream`, `/evolve`. These are in-session driving adapters; running them out of session (always-on, scheduled) is delegated to an orchestration substrate (Gas City is the reference), not an AgentOps daemon. - **CI gates** — `scripts/*.sh` and `.github/workflows/validate.yml` jobs that drive validation against the same domain types they would in interactive runs. ## Secondary (driven) adapters diff --git a/docs/cdlc.md b/docs/cdlc.md index b09de19cc..ce8f4238c 100644 --- a/docs/cdlc.md +++ b/docs/cdlc.md @@ -18,7 +18,7 @@ The translation is direct. Each piece of the software-engineering stack has a co | CI/CD | Validation gates (`/vibe`, `/pre-mortem`) | | Postmortems | Automated postmortems (`/post-mortem` → learnings) | | Runbooks | Skills + planning rules | -| Software factories | Software factory daemon (`ao daemon`) | +| Software factories | The in-session loop (`ao rpi`, `/evolve`) run out of session on an orchestration substrate (Gas City is the reference) | | Markdown / Git / Linux (open primitives) | LLM Wiki of Markdown | | Open-source corpus | Your private corpus (`.agents/` in your repo) | diff --git a/docs/first-value-path.md b/docs/first-value-path.md index c168b89ce..fefc050fa 100644 --- a/docs/first-value-path.md +++ b/docs/first-value-path.md @@ -11,7 +11,7 @@ The first value is a council verdict over a visible engineering domain: 3. Assemble bounded context for one decision. 4. Run council across Claude and Codex, with a same-packet fallback. 5. Inspect the verdict artifact and turn it into tracked work. -6. Only then show the daemon as the optional scheduled compounding lane. +6. Only then point at the optional out-of-session compounding lane, which runs the same loop on an orchestration substrate (Gas City is the reference) — AgentOps itself ships no daemon or scheduler. ## Target Viewer @@ -32,7 +32,7 @@ need to see one agent decision become an inspectable engineering artifact. | Context assembly | 1 min | `.agents/rpi/briefing-current.md` exists. | | Council run | 5-10 min | `.agents/council//verdict.md` exists. | | Verdict to work | 2 min | `bd show ` cites the verdict path. | -| Optional daemon lane | 5 min | `ao schedule list` shows an operator-approved schedule. | +| Optional out-of-session lane | 5 min | A substrate (Gas City) Order is registered to run the loop unattended. | ## Commands And Expected Outputs @@ -158,34 +158,24 @@ Expected: The important behavior is not the issue id. The important behavior is that the decision leaves chat and becomes tracked engineering work. -### 7. Optional Scheduled Lane +### 7. Optional Out-of-Session Lane -Only show this after the first verdict has landed. +Only point at this after the first verdict has landed. -Terminal 1: +The first six steps all run **in session** — that is the AgentOps product and +the zero-dependency sovereignty floor. Running the same loop **out of session** +(always-on, scheduled, unattended) is a separate concern. AgentOps 3.0 ships no +daemon, scheduler, or overnight runner of its own — those surfaces were deleted +(see [AgentOps 3.0 north star](3.0.md)). Out-of-session orchestration is +delegated to a substrate, and AgentOps ships a reference one: a **Gas City** +City (`city.toml` + `packs/agentops/`). -```bash -ao init --with-schedule -ao daemon run --schedule-file .agents/schedule.yaml -``` - -Terminal 2: - -```bash -ao schedule list -``` - -Expected: - -```text -NAME -``` - -If there is no schedule yet, add one intentionally: - -```bash -ao schedule add --file examples/schedules/dream-nightly.yaml -``` +On the reference substrate, a long-lived **mayor** agent runs `bd ready` and +dispatches the next bead to a **refinery** worker that runs `ao rpi `; +scheduled maintenance (`ao compile`, `ao maturity --scan`) runs as cron `exec` +Orders. The agents inherit the AgentOps skills via an overlay and run the same +loop you just ran by hand. See the [AgentOps 3.0 north star](3.0.md) for the +in-session / out-of-session split and the reference City. ## First Artifacts To Inspect @@ -195,7 +185,7 @@ ao schedule add --file examples/schedules/dream-nightly.yaml | `.agents/rpi/briefing-current.md` | The bounded task context assembled for the run. | | `.agents/council//verdict.md` | The engineering verdict from the council. | | `.beads/issues.jsonl` | The tracked work created from the verdict. | -| `.agents/schedule.yaml` | The optional always-on lane, only after first trust exists. | +| `city.toml` + `packs/agentops/` | The reference Gas City substrate for the optional out-of-session lane, only after first trust exists. | ## Friction List @@ -204,7 +194,7 @@ ao schedule add --file examples/schedules/dream-nightly.yaml | Mixed council requires both Claude Code and Codex CLI to be installed and authenticated. | Use `/council --quick` for first local proof and record that the demo used fallback mode. | | Activation profiles are docs-backed, not executable config. | Use `docs/activation-profiles.md`; follow-up `soc-uyp6` evaluates `ao activate product-council` after PMF evidence. | | `.agents/` is local runtime state and should not be committed. | Copy public examples into `docs/examples/`; export or summarize private verdicts before sharing. | -| The daemon can distract from first value. | Present it as second-stage automation after a human has inspected the verdict. | +| The out-of-session substrate can distract from first value. | Present it as second-stage automation after a human has inspected the verdict; the in-session loop is the product, the substrate is optional. | | Public claims can outrun evidence. | Use the claim-safe language in the domain/practice packet and storyboard. | ## Product Gaps Found diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 94daface2..f59a1983e 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -14,13 +14,12 @@ briefings and startup context prepare the work order, RPI phases run the delivery lane, and the flywheel closes the learning loop. See [Software Factory Surface](software-factory.md). -The same split now applies to Dream: +The same split applies to Dream's in-session surface: -- skills remain the interactive operator surface -- the `ao` binary is the headless automation surface -- shared config is the control surface +- skills (`/dream`) are the interactive operator surface for a compounding session +- the `ao` CLI primitives (`ao compile`, `ao maturity`, `ao flywheel close-loop`) are the headless work the loop performs -That matters most for overnight work. GitHub nightly is the public proof harness. `ao overnight` is the private local compounding engine. +Running that compounding *out of session* — always-on, scheduled, unattended — is delegated to an orchestration substrate (Gas City is the reference City), not an AgentOps daemon or scheduler; those surfaces were deleted in 3.0. GitHub nightly remains the public CI proof harness for the report contract; the private always-on compounding engine is the Gas City substrate driving the in-session loop. ## The Proof Gaps @@ -212,22 +211,19 @@ ao rpi parallel --no-merge --manifest m.json # Leave worktrees for manual review Each phase spawns a fresh session — no context bleed. Worktree isolation means parallel epics can touch the same files without conflicts. The merge order is configurable (manifest `merge_order` or `--merge-order` flag) so dependency-heavy epics land first. -## Dream — Private Overnight Operator Mode +## Dream — Compounding Run, In Session and Out -Dream is the overnight expression of the same control-plane model: +Dream is the compounding expression of the same loop model: -- **interactive surface:** `$dream` for setup, bedtime runs, and morning reports -- **automation surface:** `ao overnight setup|start|run|report` -- **control plane:** shared `dream.*` config plus explicit output artifacts +- **interactive surface:** `/dream` for a compounding session, run in the foreground against the real `.agents` corpus +- **work the loop performs:** `ao compile`, `ao maturity --scan`, `ao flywheel close-loop` — the CLI primitives the session drives +- **report contract:** `summary.json` and `summary.md` plus DreamScape terrain rendering -The first shipped wave is intentionally bounded. `ao overnight` runs locally against the real `.agents` corpus, writes `summary.json` and `summary.md`, and keeps runtime behavior honest: +A foreground `/dream` session keeps runtime behavior honest: no tracked source-code edits by default, optional bounded Dream Council synthesis through independent runner reports, and a shared report contract. -- no fake scheduler guarantees on sleeping laptops -- no tracked source-code edits by default -- optional bounded Dream Council synthesis through independent runner reports -- DreamScape terrain rendering inside the shared report contract +Running Dream **unattended** — always-on, scheduled, queue-driven — is out-of-session orchestration, which AgentOps delegates to a substrate (Gas City is the reference City) rather than shipping its own daemon or scheduler. The Gas City pattern is a long-lived agent running `/dream`-equivalent maintenance Orders (`ao compile`, `ao maturity --scan`) on a cron `exec` schedule. There are no fake scheduler guarantees on a sleeping laptop; the substrate owns when and where. -GitHub nightly remains useful, but for a different job: it proves that Dream's report contract and flywheel primitives still work in CI. It does not replace a private local bedtime run. +GitHub nightly remains useful for a different job: it proves that Dream's report contract and flywheel primitives still work in CI. It does not replace a substrate-driven unattended run. ## See Also diff --git a/docs/philosophy.md b/docs/philosophy.md index b384e003d..0ff351096 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -64,7 +64,7 @@ Not every knowledge operation needs a frontier model. AgentOps uses three tiers: | Frontier (Claude, GPT-4o, etc.) | Quality work — council validation, pre-mortem review, pattern extraction | Accuracy matters more than throughput. | | Human | Curation and promotion decisions | Judgment calls that agents get wrong systematically. | -`/dream` and `ao overnight` use the local tier for continuous compounding. `/council` and `/pre-mortem` use the frontier tier for high-stakes validation. The human reviews promotions from learning → finding → rule. +`/dream` uses the local tier for continuous compounding; when that compounding runs out of session — always-on, scheduled, unattended — it runs on the Gas City substrate (the reference out-of-session orchestrator), not an AgentOps daemon. `/council` and `/pre-mortem` use the frontier tier for high-stakes validation. The human reviews promotions from learning → finding → rule. The ratio is intentional. Validation and curation cost 3-5x implementation time. This is not overhead — it is the ratchet. Without it, the flywheel runs backward. diff --git a/docs/software-factory.md b/docs/software-factory.md index 01695ba61..b2cc7d898 100644 --- a/docs/software-factory.md +++ b/docs/software-factory.md @@ -39,8 +39,8 @@ harness-specific hook surface. Workflow is guided by skills + the `ao` CLI, and CI is the authoritative gate. The operator lane is the same everywhere: ```bash -/rpi "fix auth startup" # interactive, any harness -ao daemon submit --kind rpi --goal "fix auth startup" # pipeline-resident +/rpi "fix auth startup" # in-session, any harness +ao rpi phased "fix auth startup" # in-session with phase-level resume control ``` What used to be hook responsibilities are now explicit, pulled surfaces: @@ -53,15 +53,20 @@ What used to be hook responsibilities are now explicit, pulled surfaces: | Flywheel closure | `ao flywheel close-loop` / `/retro` / `/forge` at session close | | Execution discipline | Execution-packet `next_action` + skill instructions | -Both interactive and daemon paths exist because people use Codex or they use -Claude Code — but neither relies on hooks. +Both lanes run **in session** because people use Codex or they use Claude +Code — neither relies on hooks. Running the same loop **out of session** +(always-on, scheduled, unattended) is a separate concern AgentOps delegates to +an orchestration substrate; Gas City is the reference City. AgentOps 3.0 ships +no daemon, scheduler, or overnight runner of its own — those surfaces were +deleted (see [AgentOps 3.0 north star](3.0.md)). ## Surface Map | Layer | Purpose | Primary surfaces | |------|---------|------------------| -| Operator | What the human or lead agent should touch first | `ao factory start`, `/rpi`, `ao rpi phased`, `ao rpi status`, `ao daemon submit` | -| Briefing + runtime | Bounded startup context and thread-time state | `ao knowledge brief`, `ao context assemble`, `ao daemon submit` | +| Operator | What the human or lead agent should touch first | `ao factory start`, `/rpi`, `ao rpi phased`, `ao rpi status` | +| Briefing + runtime | Bounded startup context and thread-time state | `ao knowledge brief`, `ao context assemble` | +| Out-of-session | Running the loop unattended (always-on, scheduled) | Delegated to an orchestration substrate (Gas City is the reference) — not an AgentOps surface | | Delivery line | Research, planning, execution, validation | `/discovery`, `/plan`, `/crank`, `/validation`, `/rpi` | | Learning loop | Convert completed work into future advantage | `ao knowledge activate`, `ao flywheel close-loop`, `/retro`, `/forge` | | Enforcement | Automatic quality gates and execution discipline | CI (`.github/workflows/validate.yml`), skill-level checks, `cd cli && make test` | diff --git a/docs/workflows/session-lifecycle.md b/docs/workflows/session-lifecycle.md index cf4edfa92..fa2565ae3 100644 --- a/docs/workflows/session-lifecycle.md +++ b/docs/workflows/session-lifecycle.md @@ -44,29 +44,31 @@ ao codex status the corpus can support it, run Codex startup, then move into RPI. The lower level lifecycle commands still exist when you want direct control. -### Option 3: Bedtime Dream Run +### Option 3: Dream Compounding Run ```bash -# One-time bootstrap / scheduler guidance -ao overnight setup --apply --runner codex --runner claude --at 01:30 - -# Start a private overnight run now -ao overnight start --goal "close the loop on today's auth work" - -# In the morning -ao overnight report --from .agents/overnight/latest +# A foreground compounding session against the real local .agents corpus +/dream "close the loop on today's auth work" ``` -Use this when you want AgentOps to work against the real local `.agents` corpus -while you are away. This is not the same as the GitHub nightly workflow: +The session drives the CLI primitives that do the work — `ao compile`, +`ao maturity --scan`, `ao flywheel close-loop` — and writes the `summary.json` / +`summary.md` report contract. -- GitHub nightly is the public CI proof harness -- `ao overnight` is the private local compounding engine +Use this when you want AgentOps to compound against the real local `.agents` +corpus in a session you can watch. This is not the same as the GitHub nightly +workflow: -Scheduling is still external, but Dream now helps you bootstrap it honestly. -Use `ao overnight setup` to detect the host, persist `dream.*` config, and -generate scheduler assistance artifacts for `launchd`, `cron`, or `systemd` -without pretending sleeping laptops have guaranteed wake behavior. +- GitHub nightly is the public CI proof harness for the report contract +- `/dream` is the private local compounding engine, run in session + +**Running Dream unattended is out-of-session orchestration**, which AgentOps +3.0 delegates to a substrate rather than shipping its own daemon, scheduler, or +overnight runner — those surfaces were deleted (see +[AgentOps 3.0 north star](../3.0.md)). On the reference substrate (Gas City), a +long-lived agent runs `/dream`-equivalent maintenance Orders on a cron `exec` +schedule. The substrate owns when and where; AgentOps owns what the loop does. +No tool pretends a sleeping laptop has guaranteed wake behavior. ### Option 4: Lower-Level Codex Lifecycle @@ -111,7 +113,7 @@ SessionEnd would normally run. | Hook-capable | Natural language, `/session-start`, or startup hooks | Natural language, `/session-end`, or session-end hooks | Best fit for Claude/OpenCode when hooks are installed; `CLAUDE.md` is the startup surface and hooks stage state silently | | Codex optional native hooks | Quiet native `SessionStart` maintenance plus explicit `ao codex start` / `ao codex ensure-start` when context retrieval is needed | Native `Stop` hook for turn-scope close-loop; explicit `ao codex stop` / `ao codex ensure-stop` for transcript-driven closeout | Opt-in with `install-codex.sh --with-hooks`; startup hooks stay quiet and no native `SessionEnd` event exists today | | Codex hookless default | `ao factory start --goal ""`, `ao rpi phased`, `ao codex start`, or skill-driven `ao codex ensure-start` | `ao codex stop` or skill-driven `ao codex ensure-stop` | No startup/session-end hook surface required; lifecycle is explicit, and closeout owns the same curation hygiene as SessionEnd | -| Dream overnight run | `ao overnight setup --apply` then `ao overnight start --goal ""` | `ao overnight report --from ` | Private local overnight mode. Dream bootstraps config and scheduler assistance, while the host OS still owns actual scheduling semantics | +| Dream compounding run | `/dream ""` (foreground, in session) | Reads `summary.json` / `summary.md` from the run dir | Private local compounding in a watchable session. Running it unattended is out-of-session orchestration, delegated to a substrate (Gas City is the reference) — AgentOps ships no daemon or scheduler | | Manual fallback | `ao inject`, `ao lookup` | `ao forge transcript`, `ao flywheel close-loop` | Lowest-level portable path | ---