evolve — Skillopedia

/evolve — Goal-Driven Compounding Loop Cross-vendor analog: Anthropic Managed Agents Outcomes (May 2026). Both close the loop "agent runs → grader scores against a rubric → agent retries"; AgentOps does it locally against any model. Measure what's wrong. Fix the worst thing. Measure again. Compound. V2 command surface: keep the name . Use for the terminal-native loop. It is the top-level operator entrypoint for , preserving the old concept while reusing the v2 RPI loop engine. Operator cadence: post-mortem finished work, analyze the current repo state, select or create the next highest-value…

&& (cd cli && make build && go install ./cmd/ao)\necho \"$changed\" | grep -qE '^(skills/|hooks/)' && (cd cli && make sync-hooks)\necho \"$changed\" | grep -q '^skills-codex/' && bash scripts/regen-codex-hashes.sh\n```\n\nWithout these pre-gate steps, the gate may fail with stale-binary or embedded-drift errors that look like real regressions but are just plumbing. Each false failure costs a turn of recovery work.\n\n## Gate output parsing\n\nThe pre-push gate (and similar two-pass scripts) emits both blocking and advisory results. Trusting only the trailing status line conflates them. Use a structured grep:\n\n```bash\n# Capture full output, then parse explicit failure markers\nbash scripts/pre-push-gate.sh --fast 2>&1 | tee /tmp/gate.log\n\n# Authoritative blocking failures (case-sensitive Pass N: FAILED|BLOCKED)\nif grep -E '^.*Pass [0-9]+: (FAILED|BLOCKED)' /tmp/gate.log >/dev/null; then\n echo \"BLOCKING failure detected\"\n exit 1\nfi\n\n# Advisory issues — record but don't block\ngrep -E 'advisory|warning|WARN' /tmp/gate.log || true\n```\n\nAnti-pattern: reading `tail -1 /tmp/gate.log` and treating \"passed (N skipped)\" as authoritative. A run can show \"Pass 1: FAILED\" mid-output and \"passed (X skipped)\" at the end if Pass 2 ran in advisory-only mode against the worktree. The structural markers (`Pass N: FAILED|BLOCKED`) are the truth.\n\n## When to use `PRE_PUSH_SKIP_EVAL=1`\n\nDocumented release valve for the eval canary lane only, when:\n- The canary is flaking on pre-existing infra (filed as a tracked bead)\n- The current diff is unrelated to evals/, schemas/eval-, or cli/cmd/ao/eval\n- A recorded recent run has confirmed the canary is currently 50/50\n\nNever use `--no-verify`. The pre-commit hook is a no-op for most diffs but the principle violation is durable in `git log` and surfaces in post-mortem.\n\n## Pre-push diff-scope check (mandatory before every commit)\n\nTwo cheap pre-commit reads catch the failure modes that cost a full fix-and-repush round each (the 2026-05-29 `/burndown` + codex-budget reds):\n\n1. **`git status --short` must show ALL intended files staged.** A half-staged commit — the feature gate-script left out while only its test was committed — let CI run the *old* code so the new assertion could not pass (the #612 red). A feature and its test are one commit, not the test alone.\n2. **`git diff origin/main --stat` must be SCOPE-ONLY.** Confirm: no collateral deletions (a `git checkout --theirs` conflict take silently dropped two *unrelated* skill rows in the #600 rebase), and no lossy whole-file reformats (a 252-line `catalog.json` round-trip — discard those and use the idempotent appender). For generated/narrative files, restore `origin/main`'s version and **re-run the generator** rather than hand-merging.\n\n## Triage red precisely — pre-existing-main vs your-change\n\nNot every red is yours. The `agentops` main branch carries known pre-existing failures a local gate or a broad generator will surface:\n\n- **Local `mkdocs --strict`** fails on tracked docs because the system `mkdocs` (≤1.1.2) can't parse the modern `mkdocs.yml` (needs material plugins). CI uses the venv and passes. Confirm a flagged file is `git ls-tree origin/main`-tracked AND absent from your diff → pre-existing, proceed.\n- **~7 codex `.agentops-generated.json` drifts** (deps, provenance, red-team, release, scenario, trace, using-agentops): `regen-codex-hashes.sh` \"updates\" them because they're drifted on main. **REVERT them** (`git checkout origin/main -- \u003cthose>`) and keep only your skill's hash; surgically rebuild the manifest from `origin/main` + your delta. The CI artifact gate is changed-files-scoped (`--scope head`) so it ignores the pre-existing drift; sweeping them in adds unrelated churn and risks a manifest↔marker mismatch.\n\n**Rule:** only fix red your own diff introduced. When a generator touches files outside your bead's scope, revert those files. \"The generator changed it\" never justifies shipping unrelated drift.\n\n## See also\n\n- [new-skill-landing.md](new-skill-landing.md) — the six derived surfaces a new/modified skill must regenerate in one shot (the companion to this diff-scope discipline).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5340,"content_sha256":"e5af09cca5e78a4a382c0ddf8fe1be0a929a114d88c155428c03a3b089cbd650"},{"filename":"references/goals-schema.md","content":"# GOALS.yaml Schema\n\n```yaml\nversion: 1\nmission: \"What this repo does\"\n\ngoals:\n - id: unique-identifier\n description: \"Human-readable description\"\n check: \"shell command — exit 0 = pass, non-zero = fail\"\n weight: 1-10 # Higher = fix first\n```\n\nGoals are checked in weight order (highest first). The first failing goal with the highest weight is selected for improvement.\n\n## Fitness Snapshot Format\n\nEach cycle writes a fitness snapshot with **continuous values** (not just pass/fail):\n\n```json\n{\n \"cycle\": 1,\n \"timestamp\": \"2026-02-12T15:45:00-05:00\",\n \"cycle_start_sha\": \"abc1234\",\n \"goals\": [\n {\n \"id\": \"go-coverage-floor\",\n \"result\": \"pass\",\n \"weight\": 2,\n \"value\": 86.1,\n \"threshold\": 80\n },\n {\n \"id\": \"doc-coverage\",\n \"result\": \"pass\",\n \"weight\": 2,\n \"value\": 20,\n \"threshold\": 16\n },\n {\n \"id\": \"go-cli-builds\",\n \"result\": \"pass\",\n \"weight\": 5,\n \"value\": null,\n \"threshold\": null\n }\n ]\n}\n```\n\n- **value**: The continuous metric extracted from the check command (null for binary-only goals)\n- **threshold**: The pass/fail threshold (null for binary-only goals)\n- **cycle_start_sha**: Git SHA at cycle start, used for multi-commit revert on regression\n\nPre-cycle snapshot: `fitness-latest.json` (rolling, overwritten each cycle)\nPost-cycle snapshot: `fitness-latest-post.json` (rolling, for regression comparison)\n\n## Era Baselines\n\nBefore the first improvement cycle of a new goal era runs, evolve captures an\nimmutable baseline snapshot under\n`.agents/evolve/fitness-baselines/goals-\u003chash>/`, where `\u003chash>` is the first\n12 hex characters of the SHA-256 digest of the active GOALS.md or GOALS.yaml\nfile. A new goal era gets a new directory automatically; an existing era is\nnot recaptured once that directory contains a JSON snapshot.\n\nEach era baseline includes:\n- **All goals** from GOALS.yaml or GOALS.md, measured in their initial state for that era\n- **Baseline metadata** embedded in the snapshot JSON written by `ao goals measure`\n- **No regression comparisons** — this is the starting point for that era\n\nWhen the session ends (at Teardown), the system computes the **session fitness trajectory** by comparing the current era baseline against the final cycle snapshot. This produces `session-fitness-delta.md`, which shows which goals improved, regressed, or stayed unchanged over the entire /evolve session.\n\n## Meta-Goals\n\nMeta-goals validate the validation system itself. Use them to prevent exception lists (allowlists, skip lists) from accumulating stale entries unnoticed.\n\n```yaml\n# Meta-goals validate the validation system itself\ngoals:\n - id: allowlist-hygiene\n description: \"Every dead-code allowlist entry should have 0 non-test callers\"\n check: \"bash scripts/check-allowlist-hygiene.sh\"\n weight: 7\n\n - id: skip-list-hygiene\n description: \"Every skip-list entry should still reference an existing test\"\n check: \"bash scripts/check-skip-list-hygiene.sh\"\n weight: 5\n```\n\n**When to add a meta-goal:** After pruning any allowlist or exception list, always add a corresponding meta-goal that fails if entries have callers/references. Allowlists without meta-goals are technical debt magnets — they grow silently across epics.\n\n## Maintaining GOALS.yaml\n\nUse `/goals` to maintain the fitness specification:\n- `/goals` — run all checks, report pass/fail by pillar\n- `/goals generate` — scan repo for uncovered areas, propose new goals\n- `/goals prune` — find stale/broken goals, propose removals or updates\n\n## GOALS.md Format (Version 4)\n\nGOALS.md extends the YAML format with strategic intent:\n\n```markdown\n# Goals\n\n\u003cMission statement>\n\n## North Stars\n- \u003cAspiration>\n\n## Anti Stars\n- \u003cWhat to avoid>\n\n## Directives\n\n### 1. \u003cTitle>\n\u003cDescription>\n**Steer:** increase | decrease | hold | explore\n\n## Gates\n| ID | Check | Weight | Description |\n|----|-------|--------|-------------|\n| id | `command` | N | Description |\n```\n\n### Evolve Integration\n\nWhen GOALS.md is detected, evolve uses the directive-based cascade (Step 3.1):\n1. `ao goals measure --directives` returns the directive list as JSON\n2. Top-priority directive (lowest number) is assessed for gaps\n3. If gap found → generates work item from directive description + steer\n4. Directive becomes the work source for the cycle\n\nWhen `--beads-only` is passed, directive assessment is skipped entirely.\n\n### Format Detection\n\n`ao goals measure` auto-detects format. When both GOALS.yaml and GOALS.md exist, GOALS.md takes precedence.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4550,"content_sha256":"207464bbde3290c65a03089d3e438889d520dc69a5ba2c720e5a07022ea9d71e"},{"filename":"references/knowledge-loop-integration.md","content":"# Knowledge Loop Integration\n\n## Compile Warmup (--compile only)\n\nSkip if `--compile` was not passed or if `--dry-run`.\n\nRun the mechanical half of the Compile cycle to surface fresh signal before the first evolve cycle:\n\n```bash\nmkdir -p .agents/mine .agents/defrag\necho \"Compile warmup: mining signal...\"\nao mine --since 26h --quiet 2>/dev/null || echo \"(ao mine unavailable — skipping)\"\n\necho \"Compile warmup: defrag sweep...\"\nao defrag --prune --dedup --quiet 2>/dev/null || echo \"(ao defrag unavailable — skipping)\"\n```\n\nThen read `.agents/mine/latest.json` and `.agents/defrag/latest.json` and note (in 1-2 sentences each):\n- Any **orphaned research** files that look relevant to current goals\n- Any **code hotspots** (high-CC functions with recent edits) that may be the root cause of failing goals\n- Any **duplicate learnings** merged by defrag — context on what's been cleaned up\n\nThese notes inform work selection throughout the evolve session. Store them in a session variable (in-memory), not a file.\n\n## Harvested Work Selection (Step 3.1)\n\nRead `.agents/rpi/next-work.jsonl` and pick the highest-value unconsumed item for this repo. Prefer:\n- exact repo match before `*`, then legacy unscoped entries\n- already-harvested concrete implementation work before process work\n- higher severity before lower severity\n\nWhen evolve picks a queue item, **claim it first**:\n- set `claim_status: \"in_progress\"`\n- set `claimed_by: \"evolve:cycle-N\"`\n- set `claimed_at: \"\u003ctimestamp>\"`\n- keep `consumed: false` until the `/rpi` cycle and regression gate both succeed\n\nIf the cycle fails, regresses, or is interrupted before success, release the claim and leave the item available for the next cycle.\n\n## Queue Finalization After Regression Gate\n\n- **success:** finalize any claimed queue item with `consumed: true`, `consumed_by`, and `consumed_at`; clear transient claim fields\n- **failure/regression:** clear `claim_status`, `claimed_by`, and `claimed_at`; keep `consumed: false`; record the release in `session-state.json`\n\nAfter the cycle's `/post-mortem` finishes, immediately re-read `.agents/rpi/next-work.jsonl` before selecting the next item. Never assume the queue state from before the cycle.\n\n## Teardown Learning Extraction\n\n1. Commit any staged but uncommitted `cycle-history.jsonl`:\n```bash\nif git diff --cached --name-only | grep -q cycle-history.jsonl; then\n git commit -m \"evolve: session teardown -- artifact-only cycles logged\"\nfi\n```\n\n2. Run `/post-mortem \"evolve session: ${CYCLE} cycles\"` to harvest learnings.\n\n3. Push only if unpushed commits exist:\n```bash\nUNPUSHED=$(git log origin/main..HEAD --oneline 2>/dev/null | wc -l)\n[ \"$UNPUSHED\" -gt 0 ] && git push\n```\n\n4. Report summary: cycles, productive/regressed/idle counts, stop reason. Quality mode adds quality score + remaining findings.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2823,"content_sha256":"1945d1c7332d096fd02c1f8cb2b27d583e2c3c9d9d1c04961277aeb32f746a7c"},{"filename":"references/long-loop-discipline.md","content":"# Long-Loop Discipline — Disk Is Truth, Conversation Is Decorative\n\nThe cross-cutting axiom that every other `/evolve` reference implements.\nWhen a loop runs past ~50 cycles (`/evolve`, `/loop`, `ScheduleWakeup`-driven\ncron), **every load-bearing state must live on disk, not in conversation\ncontext.** The conversation accumulates: skill prompts re-inject, hook\nreminders pile up, tool-result history grows. Auto-compact handles it well\nenough that correctness survives — *if and only if* the work-state was on\ndisk to begin with.\n\nThis doc is the principle; the implementing references are listed below.\n\n## The Axiom\n\n| State | Truth surface |\n|---|---|\n| Cycle outcome | `.agents/evolve/cycle-history.jsonl` (append-only, read at every cycle start) |\n| Hypothesis tracker | `.agents/evolve/hypotheses.jsonl` |\n| Queueable work | `bd ready` (Dolt-backed, out-of-band) |\n| Skill rules | `skills/\u003cn>/SKILL.md` + `references/` (read fresh per cycle) |\n| Conversation context | **Decorative** — re-derives state from disk; never trusted alone |\n\nIf you remove the conversation context entirely between cycles and the work\nkeeps moving, the loop is healthy. If removing it breaks the loop, you are\nstoring load-bearing state in the wrong place.\n\n## Evidence (anchored)\n\n> \"Every cycle starts by recovering state from `.agents/evolve/cycle-history.jsonl`\n> — not from the conversation. Context drift in the conversation doesn't lose\n> the work-state … The conversation context that accumulates is mostly\n> decorative; the load-bearing state is on disk.\"\n— `docs/learnings/2026-05-13-loop-context-drift-87-cycle-observation.md`\n(87-cycle empirical observation)\n\n> \"text in SKILL.md is aspirational until paired with harness automation.\"\n— `docs/learnings/2026-05-11-evolve-skill-friction-from-13-cycle-session.md`\n(H45.2 + H45.3 falsified within 4-6 cycles because the rule lived only in\nprose, not in a gate)\n\n> \"Cycle 12's deep-scout … was the most productive move of cycles 11-13 even\n> though it shipped zero code. … A scout cycle is neither productive (ships\n> code) nor idle (finds nothing): it ships durable knowledge about pending\n> work, narrowing future cycles' search and discovery cost.\"\n— `.agents/learnings/2026-05-11-evolve-scout-mode-pattern.md`\n(durable knowledge IS the disk-truth surface)\n\n> \"in a shared tree, commit by explicit path (`git add \u003cfiles>`), never\n> `git add -A`; treat full-repo gate runs as unreliable when other agents\n> are active and lean on targeted proof commands instead.\"\n— `.agents/learnings/2026-05-16-evolve-trace-shared-tree.md`\n(disk-truth survives only if peer agents don't clobber it)\n\n## How To Apply\n\n1. **Read the ledger first.** Every cycle's first action is\n `tail -n 50 .agents/evolve/cycle-history.jsonl` (or the\n `productionLoopReader` adapter). Recover state from there, not from prior\n turns' messages.\n2. **Append, don't overwrite.** Each cycle appends one JSONL line. Never\n rewrite earlier cycles. The ledger is the audit trail.\n3. **Bead-driven work selection.** `bd ready` is the queue. Beads live in\n Dolt; the conversation never owns work scheduling.\n4. **Falsify aspirational rules.** Any rule in `SKILL.md` that depends on\n the agent following it (vs. a harness gate enforcing it) will be\n violated within 4-6 cycles. Wire automation or accept the rule is\n guidance only.\n5. **Treat \"complete\" claims with suspicion.** When a cycle says \"all\n surfaces wired,\" the next CI run often finds one more. Add a per-cycle\n drift sweep instead of trusting prior claims.\n6. **Protect disk-truth in shared trees.** See\n [../../swarm/references/shared-checkout-discipline.md](../../swarm/references/shared-checkout-discipline.md)\n — disk-truth only survives if peer agents don't clobber it via\n `git add -A` or destructive recovery.\n\n## Implementing References (Already In `/evolve`)\n\nThe axiom is the principle. Each reference below is one mechanism that\nkeeps disk-truth working:\n\n| Reference | Role |\n|---|---|\n| [cycle-history.md](cycle-history.md) | JSONL format, recovery protocol, kill switch |\n| [autonomous-execution.md](autonomous-execution.md) | ScheduleWakeup self-perpetuation pattern |\n| [context-budget.md](context-budget.md) | `CONTEXT_BUDGET_EXHAUSTED` as a third stop reason |\n| [convergence-mechanics.md](convergence-mechanics.md) | Read-path mechanisms (prior-failure injection, healing-first classifier) |\n| [scout-mode.md](scout-mode.md) | Scout-cycle as a first-class disk-truth-only result type |\n| [gate-hygiene.md](gate-hygiene.md) | Pre-gate source-surface detection + structural gate-output parsing |\n| [metronome-gate.md](metronome-gate.md) | Cross-cycle detector blocking same-mode-repeated failure |\n| [pre-flight-schema-check.md](pre-flight-schema-check.md) | Cheap field-fit check before architectural migration |\n\n## See Also\n\n- `skills/rpi/references/orchestrator-compression-anti-pattern.md` — when\n the orchestrator skips phases by inlining sub-skill work, no flywheel\n artifact lands (same disk-truth principle, applied to /rpi).\n- `skills/swarm/references/shared-checkout-discipline.md` — disk-truth only\n survives if peer agents don't clobber it.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5196,"content_sha256":"d9eb31d071c49e5664656c0f5a4694e8ec65f88610513cd06f20b9ccf073b3ae"},{"filename":"references/loop-mode.md","content":"# /evolve Loop Mode\n\n`--mode=loop` flips /evolve from agent-self-regulated to operator-driven.\n\n## Invariants under --mode=loop\n\n1. `ao evolve write-stop-marker` exits 1 unconditionally\n2. DORMANT/STOP/KILL markers are operator-only (operator writes by hand or via `ao evolve operator-stop`)\n3. Scope-filter (Step 3) splits too-big work into smaller beads via `bd create --deps discovered-from:\u003cparent>`, never halts\n4. Step 7 stop reasons are stripped of CONTEXT_BUDGET_EXHAUSTED; that becomes a non-sticky HANDOFF signal cleared by next cron-fire\n\n## CLI primitives that enforce\n\n- `ao evolve --mode=loop` — flag itself\n- `ao evolve write-stop-marker` — refuses under loop\n- `ao evolve operator-stop` — explicit operator override (separate code path)\n- `ao evolve blocked` (Wave 2) — typed blocked event instead of STOP\n\nSee: docs/plans/2026-05-21-evolve-loop-epic-design.md §A1 + §A7\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":897,"content_sha256":"802d6aa812636127220a5d6a31d7e3e1bb446004cf9e1d43feaa62a35f47dc0e"},{"filename":"references/mechanical-batches.md","content":"# Mechanical Batch Work — Script vs Per-File Edit\n\nA \"mechanical batch\" is work where the same edit is applied to N files mechanically, with no per-file judgement after the pattern is established. Examples from prior sessions: declaring `practices: [slug]` across 533 cli/ Go files, regenerating COMMANDS.md from a Cobra tree, bumping a version literal in N manifests.\n\nThe default per-file `Edit` tool path scales linearly with N and burns context. Switch to a script when ANY of these apply:\n\n- N > ~20 files\n- The transformation is **uniform** (same regex / same sed / same template field)\n- A failure on file K does not change the strategy for files K+1..N\n- Per-file output verification is cheap (`git diff --stat`, a single grep)\n\n## Script-first pattern\n\n```bash\n# 1. Inventory candidates with the predicate the task implies\ncandidates=$(git ls-files 'skills/**/SKILL.md' | xargs -I{} bash -c '\n grep -L \"^practices:\" \"{}\" >/dev/null && echo \"{}\"\n' | head -50)\n\n# 2. Apply the mechanical edit\nfor f in $candidates; do\n awk '\n /^description:/ && !done { print; print \"practices: [\u003cslug>]\"; done=1; next }\n { print }\n ' \"$f\" > \"$f.tmp\" && mv \"$f.tmp\" \"$f\"\ndone\n\n# 3. Verify in one shot\ngit diff --stat\ngrep -c \"^practices:\" $candidates | sort\n```\n\n## Per-file Edit pattern (when the above does NOT apply)\n\nUse `Edit` per file only when:\n\n- The transformation requires per-file decisions (which slug? which carrier?)\n- N is small (\u003c 10)\n- Verification benefits from reading each diff in context\n\n## Decision in Step 4\n\nWhen `/rpi` discovery surfaces a per-file pattern with N > 20 uniform candidates, the implementation phase should generate a script under `scripts/` or use an inline awk/sed pass rather than queuing N `Edit` operations. The post-edit gate then verifies the batch atomically.\n\nIf the script needs different parameters per file, that is a signal the work isn't actually mechanical — fall back to per-file Edit and reduce N (split the cycle).\n\n## Why this matters\n\nA 533-file `practices:` backfill done via per-file Edit takes ~50× more context than the same backfill done via a script with `git diff --stat` verification. The context-budget exhausts well before the work completes, and the loop drops into a forced scout or idle state with most of the work still pending.\n\n## Anti-patterns\n\n- Running a script that mutates files but ignoring the result of `git diff` (silent partial application).\n- Using `sed -i` on a tree-traversed find without `--null` handling (filename-with-spaces breakage).\n- Mixing mechanical and per-file edits in the same commit (auditor cannot tell what was bulk-applied vs per-judged).\n- Treating a 200-file batch as a single \"atomic\" change — split into review-sized waves (~30-100 files) with one commit per wave.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2782,"content_sha256":"28199aed831bf4af14ffa909452f07f243841d315fe43a5c90f67915da0b9d3c"},{"filename":"references/metronome-gate.md","content":"# Metronome Gate — Detecting Productive-Looking Repetition\n\nThe work-selection ladder treats \"tests passed + commit landed\" as productive. That signal is necessary but not sufficient: it cannot tell apart a cycle that *applied an existing template again* from one that *closed a new lane of work*. Cycles 144-154 in this repo were 7 consecutive CLI-wiring template applications — every cycle green, every commit clean, every gate happy. Only operator override at cycle 154 stopped the run.\n\nThe metronome gate adds a structural detector: when the same `mode` value repeats N times, the next rung of the ladder is forced.\n\n## State\n\n`mode_repeat_streak` is computed by `scripts/evolve-update-session-state.sh` from the trailing run of identical `mode` values in `cycle-history.jsonl`. It is derived, not authored — running the script after every cycle keeps it coherent.\n\n## Thresholds\n\n| `mode_repeat_streak` | Action |\n|---|---|\n| 0–2 | No gate. The selection ladder runs normally. |\n| 3–4 | **Soft block.** If the selected work would produce the same `mode` value, skip to the next rung of the selection ladder. Do not abort — try the rung below. |\n| 5+ | **Hard block.** File `bd remember \"metronome-N: \u003cmode>\"` and require operator override (write `.agents/evolve/RESCOPE` with a new directive). The cycle is logged as `unchanged` with `selected_source: \"metronome-gate-blocked\"`. |\n\n## Why the threshold is 3, not 2\n\nA 2-cycle streak is normal: harvested work often comes in pairs (port + adapter, R + W, parent + child). A 3-cycle streak is the earliest signal that the *template* has become the work, not the *problem*. Stopping at 3 catches the failure mode early without blocking legitimate harvested-pair cycles.\n\n## Naming discipline (operator instruction)\n\nFor the gate to work, cycle entries must use *distinguishable* `mode` values. Anti-patterns observed before this gate existed:\n\n- `template-applied-cli-wiring-5th`, `template-applied-cli-wiring-6th`, `template-applied-cli-wiring-7th` — the suffix `-Nth` made these technically unique strings but obviously the same mode. The gate canonicalizes by stripping trailing `-Nth` / `-N` patterns before comparison.\n- `wire-up-BC1`, `wire-up-BC2`, `wire-up-BC3` — the BC suffix changes but the work shape is identical. This is a *legitimate harvested-pair sequence* — three separate BCs, three real ports — and the gate correctly does NOT block here because the streak counts identical strings only. Operator distinguishes \"BC-pair work\" from \"template metronome\" by intent.\n\nWhen in doubt, the operator override at threshold 5+ is the safety net.\n\n## Worked example — cycles 144-154\n\n```\ncycle 144: wire-up-BC1 (streak: 1)\ncycle 145: wire-up-BC1-pair (streak: 1, different)\ncycle 146: wire-up-complete (streak: 1)\ncycle 147: template-applied-cli-wiring-4th (streak: 1)\ncycle 148: template-applied-cli-wiring-5th (streak: 2 after canonicalization)\ncycle 149: template-applied-cli-wiring-6th (streak: 3 — SOFT BLOCK fires)\ncycle 150: template-applied-cli-wiring-7th (streak: 4 — still blocked, next rung)\ncycle 151..154: ... (operator override at 154)\n```\n\nWith the gate active at threshold 3, cycle 149 would have skipped to the next rung of the selection ladder, probably surfacing the latent narrowness problem 5 cycles sooner.\n\n## Interaction with idle_streak\n\nThe metronome gate fires on *productive* cycles; the dormancy gate fires on *idle* cycles. They are orthogonal:\n\n- `idle_streak >= 2 AND generator_empty_streak >= 2` → dormancy (see Step 3 hard-gate)\n- `mode_repeat_streak >= 3 AND candidate.mode == last_mode` → metronome block (skip rung)\n- Both can never fire on the same cycle: idle cycles produce no work, so they cannot extend the metronome.\n\n## Why this lives in /evolve, not /rpi\n\n`/rpi` runs one cycle's worth of work. It has no visibility into prior cycles. The metronome is a *cross-cycle* pattern, only visible from the loop driver. `/evolve` is the only place that has both the ledger and the next-cycle decision.\n\n## See also\n\n- `docs/rescope/2026-05-13-ddd-hex-architecture-rescope.md` — the original operator override that prompted this gate.\n- `references/cycle-history.md` — the ledger this gate reads.\n- `references/scout-mode.md` — what to do with work that hits the soft-block (read + annotate, no execution).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4393,"content_sha256":"0533fe8c30817a8c754f80d8b5083e6b84bf9b4401e6d9528d61b9a2daaae44c"},{"filename":"references/new-skill-landing.md","content":"# New-Skill Landing — the six derived surfaces\n\nAdding or modifying a skill regenerates **six derived surfaces**, each gated by CI. Regenerating them piecemeal is the dominant fix-and-repush cause (the 2026-05-29 `/burndown` re-land needed 3 rounds; the codex-desc-budget fix needed 1). Regenerate them in **one shot** before opening the PR.\n\n## The shortcut\n\n`scripts/regen-all.sh` covers surfaces 1–3 + the CLI reference in one pass — prefer it over running the generators individually. Then run the codex + count steps below.\n\n## The six surfaces\n\n1. **registry.json (SKU catalog)** — `scripts/generate-registry.sh` (verify with `--check`). **The most-missed surface**: a stale `registry.json` trips `contracts-sync` (\"registry.json is stale\") AND `correctness(ubuntu)` (\"SKU_CATALOG: DRIFT\") *together*. As of ag-ekyq, `skills/skill-builder/scripts/init.sh` regenerates it automatically during scaffold; regenerate by hand for any out-of-band skill edit.\n2. **skill-domain-map** — `scripts/generate-skill-domain-map.sh` (narrative `N skills` count + per-skill row; verify `--check`).\n3. **context-map** — `scripts/generate-context-map.sh` (hex roles from frontmatter; CI gate `validate-context-map-drift`).\n4. **skill counts** — `scripts/sync-skill-counts.sh`. **The `SKILL-TIERS.md` row must be added by hand** — `sync-skill-counts` only syncs the *counts* across PRODUCT/ARCHITECTURE/SKILLS/using-agentops; it never adds the row.\n5. **codex twin** — `scripts/register-new-codex-skill.sh \u003cname> --treatment parity_only|bespoke --reason \"…\"` (manifest entry + override-catalog + `.agentops-generated.json` marker, atomic + idempotent). Then **hand-author `skills-codex/\u003cname>/prompt.md`** — codex twins are MANUAL; `regen-all.sh` does NOT generate them. Re-run `scripts/regen-codex-hashes.sh` afterward (adding `prompt.md` changes the tree hash). Parity_only minimal `prompt.md` = title + description + an `## Instructions` block (\"Load and follow the sibling `SKILL.md`\").\n6. **narrative skill counts** — `scripts/check-registry-drift.sh --fix-counts` (the `N skills` lines in `agentops-skill-domain-map.md` + `agentops-domain-evolution-bdd.md`).\n\n## Embedded sync\n\nIf the edit touches `skills/**` content that is embedded (e.g. `using-agentops`), run `cd cli && make sync-hooks` so `cli/embedded/skills/...` stays in sync — else the `codex artifact metadata`/embedded-drift gate fails.\n\n## See also\n\n- [gate-hygiene.md](gate-hygiene.md) — pre-push diff-scope check + pre-existing-vs-mine red triage (the companion discipline that keeps a new-skill PR one-shot-green).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2602,"content_sha256":"6806a90157d876396677a23816609bdf7e595d382f50bd4ab877e6ad4c24f42e"},{"filename":"references/oscillation.md","content":"# Oscillation Detection\n\n## What Is Oscillation?\n\nA goal **oscillates** when it alternates between passing and failing across\nevolve cycles. Typically this means the fix for the goal causes a side-effect\nthat breaks something else, which gets reverted, which re-exposes the original\nfailure — creating a loop.\n\nExample from cycle-history.jsonl:\n```\ncycle 5: goal-X → improved\ncycle 8: goal-X → fail\ncycle 12: goal-X → improved\ncycle 15: goal-X → fail\n```\n\n## Detection\n\nCount **improved→fail transitions** for the same `target` in\n`.agents/evolve/cycle-history.jsonl`:\n\n```bash\n# Count oscillations for a given goal — reads via BC3 LoopReaderPort\n# (soc-y5vh.4 wrapper) instead of inline JSONL slurp.\nscripts/evolve-read-cycle-history.sh recent 0 \\\n | jq -r \"select(.target==\\\"$GOAL_ID\\\") | .result\" \\\n | awk 'prev==\"improved\" && $0==\"fail\" {count++} {prev=$0} END {print count+0}'\n```\n\n## Threshold\n\n**3 oscillations** (improved→fail transitions) within a single session\ntriggers quarantine. The goal is skipped in Step 3 selection.\n\n## Effect\n\n- Quarantined goals are skipped during work selection (Step 3)\n- Skipping a quarantined goal counts as idle (no actionable work found)\n- The quarantine is session-scoped — a new session resets the count\n- Quarantine events are logged in cycle-history.jsonl with `\"result\": \"quarantined\"`\n\n## Recovery\n\n1. Human identifies the root cause (usually a conflict between two goals)\n2. Fix the underlying issue manually\n3. Start a new evolve session (quarantine resets)\n4. Or: remove the quarantine by deleting the goal from the skip list\n\n## Why Not Just Increase the Skip Threshold?\n\nThe 3-consecutive-regression skip in Step 3 only catches monotonic failure.\nOscillation is worse — it burns cycles alternating between \"fixed\" and \"broken\"\nwithout the stagnation detector ever triggering (because the goal intermittently\npasses). The oscillation detector catches this pattern explicitly.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1953,"content_sha256":"62cac764158b0fc2e98cfdac0828b13bbc2f91d1f7eb301fa42f3137641960cf"},{"filename":"references/parallel-execution.md","content":"# Parallel Goal Execution\n\n## Architecture\n\nWhen `--parallel` is enabled, `/evolve` uses `/swarm` to execute multiple independent\ngoal improvements concurrently instead of fixing one goal per cycle.\n\n```\n/evolve --parallel (Fitness Loop)\n │\n ├─ Step 2: Measure ALL goals\n │\n ├─ Step 3: Select top N independent failing goals (max_parallel, default 3)\n │ └─ select_parallel_goals: heuristic independence via check-script overlap\n │\n ├─ Step 4: Parallel execution via /swarm\n │ ├─ TaskCreate for each selected goal\n │ ├─ Artifact isolation: .agents/evolve/parallel-rpi/{goal.id}/\n │ ├─ Git isolation: /swarm --worktrees (each worker in /tmp/evolve-{goal.id})\n │ └─ /swarm spawns N fresh-context workers, each runs full /rpi cycle:\n │ └─ research → plan → pre-mortem → crank → vibe → post-mortem\n │\n ├─ Step 5: Single regression gate (re-measure ALL goals after wave)\n │ ├─ If ANY goal regressed → revert ENTIRE parallel wave\n │ └─ If clean → log cycle with goal_ids array\n │\n └─ Step 6-7: Log, loop (same as sequential)\n```\n\n## The Fractal Pattern\n\nSwarm is the universal coordination primitive at every level:\n\n```\nLEVEL 0: /evolve --parallel\n └─ /swarm (parallel goal improvements) ← NEW: swarm at evolve level\n └─ LEVEL 1: /rpi (per-goal lifecycle)\n └─ research → plan → crank → vibe → post-mortem\n └─ LEVEL 2: /crank (epic execution)\n └─ /swarm (parallel issue implementation) ← existing: swarm at crank level\n └─ LEVEL 3: workers (atomic tasks)\n```\n\nEach level creates fresh context for the next (Ralph Wiggum pattern).\nThe pattern is always: **one leader + N fresh-context workers + validation + cleanup**.\n\n## Goal Independence Detection\n\n`select_parallel_goals` uses a heuristic check:\n\n1. Start with highest-weight failing goal\n2. For each remaining eligible goal (weight-sorted):\n - Compare check commands for shared scripts/paths\n - If independent: add to selection (up to max_parallel)\n - If overlapping: skip (handled in next cycle)\n\n**This is a heuristic, not a guarantee.** Goals don't declare which files their\nimprovements will modify — only which scripts verify them. Two goals with different\ncheck scripts may still modify overlapping files.\n\n**The regression gate (Step 5) is the real safety net.** If parallel goals conflict,\nthe regression check detects it and reverts the entire wave. This makes false\nnegatives in independence detection safe (they just cost one wasted cycle).\n\n## Artifact Isolation\n\nEach parallel /rpi worker needs isolated artifact directories to prevent collision:\n\n| Directory | Purpose | Isolation |\n|-----------|---------|-----------|\n| `.agents/evolve/parallel-rpi/{goal.id}/` | /rpi phase summaries, next-work | Per-goal subdirectory |\n| `.agents/evolve/parallel-results/{goal.id}.md` | Worker result summary | Per-goal file |\n| `/tmp/evolve-{goal.id}` | Git worktree | Per-goal worktree via /swarm |\n\nWithout isolation, N concurrent /rpi cycles would collide on `.agents/rpi/`\n(phase summaries, next-work.jsonl) and git index locks.\n\n## Git Isolation\n\nParallel workers MUST use worktree isolation (via `/swarm --worktrees`):\n\n- Each worker operates in `/tmp/evolve-{goal.id}` worktree\n- No git lock conflicts (each worktree has its own index)\n- Lead merges worktrees after all complete, before regression gate\n- On regression: revert all merged commits using `cycle_start_sha`\n\n## Regression Handling\n\n**Sequential mode:** Revert commits from one goal's /rpi cycle.\n\n**Parallel mode:** Revert ALL commits from the entire parallel wave.\nThe `cycle_start_sha` (captured before the wave) anchors the revert point.\nAll N goal improvements are rolled back together — even goals that individually\nsucceeded. This is by design: if goals interfere, we can't know which one\ncaused the regression without testing each in isolation.\n\n## Cycle History Schema\n\nSequential cycles use `target` (string). Parallel cycles use `goal_ids` (array) with `parallel: true`:\n\n```jsonl\n{\"cycle\": 1, \"target\": \"test-pass-rate\", \"result\": \"improved\", \"sha\": \"abc1234\", ...}\n{\"cycle\": 2, \"goal_ids\": [\"doc-coverage\", \"lint-clean\"], \"result\": \"improved\", \"sha\": \"def5678\", \"parallel\": true, ...}\n```\n\nLegacy entries may use `goal_id` instead of `target` and `commit_sha` instead of `sha`. Tools should handle both.\n\n## Compounding\n\nEach parallel /rpi worker runs its own /post-mortem, which feeds the knowledge\nflywheel independently. Learnings from all N parallel cycles compound into the\nflywheel, feeding the next /evolve cycle.\n\n## When to Use\n\n| Scenario | Mode |\n|----------|------|\n| 1-2 failing goals | Sequential (default) — parallelism overhead not worth it |\n| 3+ independent failing goals | `--parallel` — significant speedup |\n| Goals with overlapping files | Sequential — parallel would cause conflicts |\n| First run on new repo | Sequential — learn the codebase before parallelizing |\n\n## Constraints\n\n- Max 5 parallel goals per wave (`--max-parallel` cap)\n- Default 3 parallel goals (balance between speedup and resource usage)\n- Each /rpi worker needs a full context window — budget accordingly\n- Worktree isolation required (no shared-worktree parallel /rpi)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5329,"content_sha256":"0e9eaac66e506d2d39b0d7243bd379482a96a033d38c1c921b1edc5d0f0e0e38"},{"filename":"references/postmortem-checkpoint.md","content":"# Mandatory checkpoint: session-PR threshold (soc-n75z)\n\n> Stop reason #6 of `/evolve`. NOT terminal — gates the next cycle, not the loop's existence. Derivation: the 2026-05-19 and 2026-05-20 sessions both shipped 5-6 PRs while the agent self-graded \"HEALTHY\" without running a real council; STOP got written as if it were post-mortem completion. This procedure closes that gap.\n\n## When this fires\n\nAt Step 7 boundary, after a cycle whose result is `improved` or `regressed`:\n\n```bash\nif [ \"$session_pr_count\" -ge \"${SESSION_PR_THRESHOLD:-5}\" ] \\\n && [ \"$session_pr_count_at_last_checkpoint\" -lt \"${SESSION_PR_THRESHOLD:-5}\" ]; then\n # checkpoint fires once per crossing — not repeatedly at every cycle past 5\n run_postmortem_checkpoint\nfi\n```\n\nThe check is **edge-triggered** (fires when the counter first crosses the threshold), not level-triggered. After PASS/WARN, the loop continues until either another stop reason fires OR another threshold crossing — e.g., at `2 × SESSION_PR_THRESHOLD = 10`, the checkpoint re-fires for a second post-mortem.\n\n## What it MUST do\n\n1. **Invoke `/post-mortem --deep`** on the cycles since the last checkpoint (or session start). `--deep` runs 3 same-vendor judges in adversarial posture.\n\n - Do NOT use `--mixed`. Cross-vendor (Codex availability) is an infrastructure dependency that should not block the loop gate. Reserve `--mixed` for strategic architecture decisions (e.g., the DUEL.md precedent), not per-session health checks.\n - Do NOT use single-judge mode. Single-judge sweeps are too weak for a gate that enables continued autonomous work — the whole point of the checkpoint is adversarial counter-balance against the author who just wrote the cycles.\n\n2. **Wait for the verdict file** at `.agents/council/\u003cdate>-\u003cscope>-postmortem/verdict.md`. The verdict file's first non-blank line must start with `## Council Verdict: \u003cPASS|WARN|FAIL>`.\n\n3. **Branch on verdict:**\n\n | Verdict | Action |\n |---|---|\n | `PASS` | Continue the ladder. Next cycle's `notes` field MUST record the verdict path. |\n | `WARN` | Continue the ladder. Next cycle's `notes` field MUST emit the council's caveats verbatim — they need to trace through `cycle-history.jsonl` so the loop's recorded behavior reflects what was acknowledged. |\n | `FAIL` | Write `.agents/evolve/STOP` with the verdict path embedded. Do NOT clear. Surface the council's required-follow-up list to the operator. |\n\n4. **Treat non-convergence as FAIL.** If after 600 seconds the verdict file is missing, malformed, or the council's judges disagreed irreconcilably after a second pass, default to FAIL. **Absence of evidence is NOT evidence of pass.** The 2026-05-20 failure mode was an empty 2-minute cron pass treated as council completion; this rule is the corrective.\n\n## What it MUST NOT do\n\n- **Never self-grade.** The agent who ran the cycles is the same agent doing the post-mortem. Self-attestation is definitionally invalid for the gate; council enforcement is the structural requirement.\n- **Never write `.agents/evolve/STOP` without a council verdict file.** STOP without a verdict is the 2026-05-20 anti-pattern — the file becomes a self-imposed pause that the same agent (or operator) clears without rigor. Every STOP written by this checkpoint must cite a verdict path that resolves to a FAIL verdict.\n- **Never run `/post-mortem` without `--deep` from this checkpoint.** A light-touch cron-fire pass that writes learnings but skips Phase 1 council does not satisfy the gate. The 2026-05-20 cron `/post-mortem` was insufficient by design.\n\n## Relationship to soc-1aou hook\n\n`hooks/session-pr-counter.sh` (PR #362, soc-1aou) is the *pre-creation* signal — it fires on `gh pr create` at `count >= threshold - 1` and emits post-mortem prompts via `additionalContext`. Default advisory; opt-in hard-block via `AGENTOPS_SESSION_PR_BLOCK=1`.\n\nThis checkpoint is the *post-merge* gate — it fires after PR #N+1 has merged, before cycle N+1 enters Step 1. The two are **complementary**, not redundant:\n\n| Layer | Trigger | Default | Purpose |\n|---|---|---|---|\n| `hooks/session-pr-counter.sh` | `gh pr create` at `count >= threshold-1` | Advisory | Warn the agent before committing to the PR that tips the session over |\n| `evolve` checkpoint #6 | Cycle boundary after `count >= threshold` | Mandatory | Structural enforcement of council before the next cycle starts |\n\nThe hook can be bypassed (advisory by default); the skill checkpoint cannot (the loop genuinely waits on the verdict file).\n\n## Configuration\n\n| Variable | Default | Effect |\n|---|---|---|\n| `SESSION_PR_THRESHOLD` | `5` | Matches soc-waxr documentation default. The 2026-05-19 session (6 PRs, 3 self-corrections) and 2026-05-20 session (5 PRs, 1 self-correction + 1 confirmation-bias verdict) are the two derivation points. Do not change without a third data point. |\n| `EVOLVE_POSTMORTEM_TIMEOUT_SEC` | `600` | Max wait for verdict file. Past this, treat as FAIL. |\n| `EVOLVE_POSTMORTEM_COUNCIL_FLAG` | `--deep` | Override only with operator sign-off in a follow-up PR; reverting to single-judge or `--mixed` requires a council justifying the change. |\n\n## Failure modes this closes\n\nThe 2026-05-20 post-mortem (`.agents/council/2026-05-20-evolve-204-208-postmortem/verdict.md`) found WARN with Q4 FAIL:\n\n> The \"post-mortem\" that \"cleared\" cycle 208 was a cron-fire that wrote 5 learning files and appended a harvest entry. No Phase 1 (council) ran. No Phase 2 extraction with adversarial review. No Phase 3 backlog processing. No verdict file was produced.\n>\n> Cycle 208's notes contain the string \"HEALTHY verdict from /post-mortem cron\" — a verdict that does not exist in any file the council directory contains.\n\nThat cycle-history entry transformed an absence (no council ran) into a positive claim (clearance exists) in an append-only ledger. Stop reason #6 prevents that pattern by requiring a real verdict file path before continuing.\n\n## Cross-references\n\n- `skills/post-mortem/SKILL.md` — the post-mortem skill this checkpoint invokes\n- `skills/council/SKILL.md` — the council skill `--deep` runs against\n- `skills/ship-loop/SKILL.md` — the soc-waxr session-scope doctrine source\n- `hooks/session-pr-counter.sh` — complementary pre-creation hook\n- `CLAUDE.md` § \"Autonomous-session scope\" — top-level doctrine reference\n- `.agents/council/2026-05-20-evolve-204-208-postmortem/verdict.md` — the derivation council (local; gitignored)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6469,"content_sha256":"61b464a9de46eb4f5918d56eabf64f57a3e866a68c6d3c479dd808619978bf46"},{"filename":"references/pre-flight-schema-check.md","content":"# Pre-Flight Schema Check — Stop Migration Cycles That Can't Succeed\n\nThree phase-2 port migrations attempted in cycles 156-157 of this repo all failed for the same structural reason: the port surface projected ~5 fields, the consumer read ~13 fields. The migration would have silently dropped 8+ fields the consumer relied on. The lesson is captured in `docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md`. This document encodes that lesson as a pre-cycle check.\n\n## When this gate runs\n\nBefore invoking `/rpi` on a cycle whose selected work matches any of:\n\n- title contains `migrate`, `rewire`, `route through`, `port-ify`, `adapt to \u003cPort>`\n- title contains `\u003cModule> → \u003cPort>Port` or similar arrow syntax\n- bd issue has label `migration` or `bc-port-adoption`\n- selected_source is `harvested` and the queue entry has `kind: \"migration\"`\n\n## Procedure\n\n1. **Identify the port surface.** From the work title, locate the port type definition (typically `cli/internal/ports/\u003cport>.go`). Extract the projected struct fields.\n\n2. **Sample two consumer call sites.** From the work description, find the function or file being migrated. Grep for *its* current consumers — the call sites that depend on the data the migration will route through the port. Pick two representative ones (different files, different formatting/decision shapes).\n\n3. **Field-fit comparison.**\n ```bash\n PORT_FIELDS=$(grep -E '^\\s+[A-Z][a-zA-Z0-9_]+\\s+' cli/internal/ports/\u003cport>.go | awk '{print $1}' | sort -u)\n CONSUMER_FIELDS=$(grep -oE '\\.[A-Z][a-zA-Z0-9_]+\\b' \u003cconsumer-files> | sed 's/^\\.//' | sort -u)\n comm -23 \u003c(echo \"$CONSUMER_FIELDS\") \u003c(echo \"$PORT_FIELDS\")\n ```\n The output is the set of fields the consumer reads that the port does NOT project.\n\n4. **Decision.**\n\n | Missing fields | Action |\n |---|---|\n | 0 | Migration is safe. Proceed with `/rpi`. |\n | 1–2 | Migration with widening. Add the missing fields to the port + writer + tests in the same cycle. Mark mode `port-widen-and-migrate`. |\n | 3+ | **Abort the migration cycle.** File a port-widening bd issue with the field list, log this cycle as `unchanged` with `selected_source: \"pre-flight-schema-fail\"`, return to Step 3 selection. |\n\n5. **Special case — zero-data target.** If the consumer reads a field (e.g. `Target`) that exists in the type definition but *no actual entries in the production data store have that field set*, the consumer is dead-code-in-disguise. Don't widen — investigate whether the consumer was ever wired. Log as `selected_source: \"pre-flight-dead-target\"`.\n\n## Why this check is cheap\n\nA migration cycle costs ~15-30 minutes of /rpi (discovery + crank + validation). The pre-flight check is two `grep` calls and one `comm` — under 30 seconds. Catching even one bad migration pays for ~50 pre-flight runs. In this repo, three cycles spent on bad migrations (156, 157, plus the soc-0pku bead) would have been caught by 90 seconds of pre-flight.\n\n## What this does NOT replace\n\nThis is a *cycle-selection* gate, not a code-quality gate. Validating the actual migration code still belongs to `/rpi` → `/validation`. The pre-flight only answers \"is this migration even shaped right for the current port?\"\n\n## Worked example — cycle 157 (soc-0pku)\n\nSelected work: `context_assemble.go → LoopReaderPort`\n\n```\nPORT_FIELDS=Number,Mode,Result,Commit,Milestone # 5\nCONSUMER_FIELDS=Timestamp,Cycle,Target,GoalIDs,Result,Status,Sha,CanonicalSha,LogSha,GoalsPassing,GoalsTotal,Summary,Error # 13\nMissing: Timestamp,Target,GoalIDs,Status,Sha,CanonicalSha,LogSha,GoalsPassing,GoalsTotal,Summary,Error # 11\n```\n\nMissing fields = 11. Threshold 3+. **Abort.** File port-widening issue: \"Widen CycleEntry: +Timestamp,+Summary at minimum; full set deferred.\" Cycle is logged as `unchanged`, ladder advances.\n\nThis is exactly what cycle 161 ended up doing reactively — adding `StartedAt` and `Title` after the migrations bounced. With pre-flight, the widening would have happened *before* burning three cycles on doomed migrations.\n\n## See also\n\n- `docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md` — the source observation\n- `references/scout-mode.md` — first-class result for cycles that intentionally don't execute\n- `references/metronome-gate.md` — sibling cross-cycle gate\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4308,"content_sha256":"8081d3e8dc2290ee8542c3800b64939c4f2c836d12bad0e0d78ea91466ceb8ba"},{"filename":"references/quality-mode.md","content":"# Quality Mode\n\n## When to Use\n\nUse `--quality` when:\n- Post-mortem findings are accumulating faster than they're consumed\n- All GOALS pass but `next-work.jsonl` has unconsumed high-severity items\n- You want to resolve context-hot findings from a just-completed epic\n- Running immediately after `/post-mortem` to action its findings\n\nDo NOT use `--quality` when:\n- GOALS have critical failures (build broken, tests failing)\n- No `next-work.jsonl` exists or is empty\n- You want standard fitness-driven improvement\n\n## Quality Score\n\nSimple severity-weighted score:\n\n```\nscore = 100 - (high_count * 10) - (medium_count * 3)\n```\n\nWhere counts are unconsumed findings remaining in next-work.jsonl.\n\n| Score | Meaning |\n|-------|---------|\n| 90-100 | Excellent — few or no findings remaining |\n| 70-89 | Good — medium-severity items remain |\n| 50-69 | Attention needed — high-severity items remain |\n| \u003c50 | Quality debt — many high-severity findings |\n\n## Priority Cascade (Quality Mode)\n\n1. High-severity unconsumed findings → /rpi\n2. Medium-severity unconsumed findings → /rpi\n3. Open ready beads → prefer /rpi with bead context\n4. Failing GOALS.yaml goals and directive gaps → /rpi\n5. Testing improvements → /rpi\n6. Validation tightening / bug-hunt / drift mining → /rpi\n7. Feature suggestions → durable work + /rpi\n8. Nothing after repeated generator passes → dormancy fallback\n\n## Marking Findings Consumed\n\nWhen evolve picks a finding from next-work.jsonl, claim it first:\n- Set `claim_status: \"in_progress\"`\n- Set `claimed_by: \"evolve-quality:cycle-N\"`\n- Set `claimed_at: \"\u003ctimestamp>\"`\n- Keep `consumed: false` until the /rpi cycle and regression gate both succeed\n\nIf the /rpi cycle fails (regression), clear the claim and leave the finding available.\n\n## Artifacts\n\n| File | Purpose |\n|------|---------|\n| `cycle-history.jsonl` | Same as standard mode + `quality_score` field |\n| `fitness-latest.json` | Same as standard mode (goals measurement) |\n| `quality-trajectory.md` | Quality score over time (written at teardown) |\n\n## Interaction with Standard Mode\n\nQuality mode and standard mode share:\n- The same cycle-history.jsonl\n- The same fitness measurement (goals are still checked)\n- The same dormancy guard (repeated empty queue + generator passes)\n- The same circuit breaker (60 minutes)\n\nThey differ in work selection priority at the top of the ladder: quality mode picks findings first, then still falls through to the same producer layers before dormancy is allowed.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2506,"content_sha256":"af705277d4b26e7b01dfa5e3407d38eb42d2761b5f39e102181138c65b108966"},{"filename":"references/scout-mode.md","content":"# Scout Mode — First-Class Cycle Result\n\nScout mode is a result type alongside `improved`, `regressed`, `harvested`, and `idle`. A scout cycle reads a candidate work item, validates its scope and shape, and either annotates the queue entry with a deeper plan or splits it into smaller beads — without executing the underlying work.\n\n## When to scout\n\nUse scout-mode whenever a Step 3 selection meets any of these criteria:\n\n- The work touches **> 5 files** and is **not** a mechanical batch (a single script-driven rewrite across N similar files).\n- The work introduces a **new shape**: schema field, frontmatter carrier, JSON top-level key, validator rule, contract surface, or struct field that downstream consumers will read.\n- The work is **operator-level epic work**: multiple cooperating sub-systems must change together (e.g. emitter + consumer + validator + tests + docs in one cycle).\n- The **current cycle is > 5 productive cycles into the session** and the work would extend the implementation arc rather than close it.\n\nThe scope-filter step (Step 3.0 in `SKILL.md`) consults these heuristics before any work is claimed.\n\n## What a scout cycle does (soc-5qit: split-or-defer, never bail)\n\nA scout cycle is **work**, not a stop. It MUST produce exactly one of:\n\n### Path A: Split (preferred when the queue is light and the work is decomposable)\n\n1. Read the target file(s) named in the work item (no edits).\n2. Map the **current shape** at the relevant boundary (what fields exist, what callers read it, what validators enforce).\n3. Run `bd create` to decompose the candidate into 2-N child beads, each ≤5 files and single-shape:\n ```bash\n bd create \"Slice 1 of \u003cparent-title>: \u003csmaller-scope>\" \\\n --description=\"Carved from \u003cparent-id> by scout-mode. Scope: \u003cfiles/contract>\" \\\n --deps discovered-from:\u003cparent-id> -t task -p \u003cinherit> --json\n ```\n4. Update the parent bead with `bd update \u003cparent-id> --notes \"scout-split into: \u003cchild-ids>\"`.\n5. **Re-enter Step 3** so the smallest new child OR another ready bead gets claimed THIS cycle.\n\n### Path B: Defer (preferred when the queue has other ready beads)\n\n1. Read the target file(s) briefly to confirm the scope assessment.\n2. Append a `disposition: defer:\u003creason>` block to the work item.\n3. **Re-enter Step 3** so the next-priority ready bead gets claimed THIS cycle. The big candidate stays available for a future session with lighter context.\n\n### Path C: Park (operator-level epic, no obvious split)\n\n1. `bd update \u003cid> --status blocked --notes \"scope-too-big: \u003cwhy>; needs operator triage\"`.\n2. **Re-enter Step 3** for the next ready bead.\n\nA scout cycle does NOT:\n\n- Run `/rpi` against the original too-big candidate.\n- Edit any source file outside `.agents/rpi/next-work.jsonl` and bd metadata.\n- Commit code (bd updates land in Dolt automatically).\n- **Exit the loop** — if `bd ready` returns ≥1 unblocked bead, the cycle MUST claim and work one of them after the scout decision. (soc-5qit invariant.)\n\n## Logging a scout cycle\n\nAppend to `cycle-history.jsonl` with:\n\n```json\n{\"cycle\": N, \"result\": \"scout\", \"selected_source\": \"\u003csource>\", \"work_ref\": \"\u003cid>\",\n \"net_change\": 0, \"commit\": null,\n \"milestone\": \"Scouted \u003cwork>; recommendation: \u003csplit|park|smaller-slice>\"}\n```\n\nThe `result: scout` value is canonical alongside `improved | regressed | harvested | idle | unchanged`.\n\n## Daily learning capture\n\nScout cycles still get a micro-capture line. Use the form:\n\n```\n- cycle N [scout] \u003cwork-ref>: \u003cwhat was learned about the shape> INSIGHT: \u003ctag>\n```\n\n## Promotion path\n\nWhen a scouted item later becomes single-cycle-doable (because earlier prerequisites landed), drop the `disposition` block and let normal Step 3.1 selection pick it up.\n\n## Why scout is not \"idle\"\n\n`idle` means \"no actionable work in any layer\". Scout means \"actionable work found but the shape is wrong for this cycle's budget\". These are structurally different stop reasons. Conflating them masks the real failure mode: the loop has work but can't safely run it.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4037,"content_sha256":"e5b136aaa37baf9b78427fc6ab6f1222332ef29edf17d01909d4cffd7ed3b2d6"},{"filename":"references/snapshot-pattern-for-long-cycle-gates.md","content":"# Snapshot Pattern For Long-Cycle Gates\n\nGates that depend on **multi-session corpus state** (flywheel\ncompounding, corpus freshness, knowledge-registry health, AOP-claim\ncoverage) cannot be evaluated by a single CI run on a greenfield\ncheckout — the corpus isn't there. The 4-step **snapshot pattern**\nconverts these into single-commit-validatable artifacts: the live gate\ncomputes the metric on demand, the operator snapshots it to a\ngit-tracked JSON file with a staleness window, and the CI gate\nvalidates the snapshot file rather than re-running the live metric.\n\nThis is how disk-is-truth (see long-loop-discipline (disk-is-truth axiom))\nextends into CI: the **disk file is the gate's truth surface**, and\nthe live metric only refreshes it.\n\n## The 4-Step Pattern\n\n### 1. Live Gate (Operator-Local)\n\nA script that computes the multi-session metric on demand. Runs in\nthe operator's full corpus, not in CI.\n\n```bash\n# Example: live gate for flywheel compounding\nbash scripts/check-flywheel-compounding.sh\n# Internally: ao flywheel status → exits 0 if compounding, 1 if not\n```\n\n### 2. Snapshot Command (Operator Cadence)\n\nWraps the live result in a JSON envelope with `recorded_at`,\n`git_sha`, and the metric payload. Writes to a git-tracked path.\n\n```bash\n# Example: snapshot the live result\nbash scripts/snapshot-flywheel-compounding.sh\n# Writes docs/releases/flywheel-compounding-snapshot.json\n```\n\nThe snapshot file is **the durable proof**. Operator runs the\nsnapshot script on cadence (e.g., before each release, or weekly).\n\n### 3. CI Gate (Snapshot Validation)\n\nCI does **not** re-run the live metric (it can't — no corpus). It\nvalidates the snapshot file:\n\n- Structural shape (required keys present)\n- Staleness threshold (e.g., \u003c 14 days old)\n- Asserted value (`compounding == true`, `freshness_score >= N`)\n\n```bash\n# Example: CI gate validates the snapshot\nbash scripts/check-flywheel-compounding-snapshot.sh\n# Fails if snapshot missing | > 14 days old | shows metric flipped\n```\n\n### 4. Wire As A Regular Gate\n\n- `GOALS.md` row naming the metric\n- `.github/workflows/validate.yml` CI job\n- `scripts/pre-push-gate.sh` lane invocation\n- `AGENTS.md` \"CI Jobs and What They Check\" row\n- (per the parity-surface inventory — see\n `docs/learnings/2026-05-12-parity-surface-inventory-grew-from-4-to-7-across-cycles-64-70.md`)\n\nOnce wired, the snapshot pattern looks like a regular gate; the\noperator-cadence-refresh is the only non-standard piece.\n\n## Why This Matters\n\nWithout this pattern, long-cycle gates stay in the Roadmap column\nforever because **CI can't run them green** — a clean CI runner has\nno corpus, no flywheel history, no AOP-claim accumulation. Three\nGOALS.md gates closed in one /evolve session because of this pattern\n(G1 flywheel-snapshot, D11 corpus-freshness, D10 workbench-delta).\n\nThe pattern is the implementation of long-loop-discipline (disk-is-truth axiom)\nat the CI layer: the disk file is the load-bearing state, the live\nmetric is the refresh path, and CI consumes the disk.\n\n## Evidence (anchored)\n\n> \"Gates that depend on multi-session corpus state (e.g., flywheel\n> compounding, corpus freshness, knowledge registry health) cannot be\n> evaluated by a single CI run on a greenfield checkout — the corpus\n> isn't there. … The snapshot file is the durable proof. The CI gate\n> ensures the operator refreshes it on cadence. Each surface is\n> testable on a clean CI runner without N sessions of warmup.\"\n— `.agents/learnings/2026-05-11-quick-snapshot-pattern-for-long-cycle-gates.md`\n(retro-quick, validate phase)\n\n> \"Applications validated this session: corpus snapshot (D11, cycle\n> 22), flywheel compounding (G1, cycle 24), workbench delta (D10,\n> cycle 26), README claim manifest (PG4, cycle 30), AOP-CLAIM\n> all-claims map (cycle 35). The structural-floor contract gate\n> (cycle 41) is the generalization — same pattern at the corpus level.\"\n— same source\n\n## How To Apply (When Adding A New Long-Cycle Gate)\n\n1. **Identify the metric.** Does it need a corpus, history, or\n multi-session state to compute? If yes, snapshot pattern. If no, a\n regular CI gate suffices.\n\n2. **Write the live gate** under `scripts/check-\u003cmetric>.sh`. Exit 0\n on success, non-zero on regression. This runs in the operator's\n environment.\n\n3. **Write the snapshot command** under `scripts/snapshot-\u003cmetric>.sh`.\n Output JSON to a git-tracked path:\n ```json\n {\n \"recorded_at\": \"2026-05-18T19:42:00Z\",\n \"git_sha\": \"abc1234\",\n \"metric_name\": \"flywheel_compounding\",\n \"value\": true,\n \"details\": { /* metric-specific payload */ }\n }\n ```\n\n4. **Write the snapshot validator** under\n `scripts/check-\u003cmetric>-snapshot.sh`. Read the JSON, assert shape +\n staleness + value.\n\n5. **Wire all 7 parity surfaces** per the parity-surface inventory:\n pre-push lane, validate.yml job, summary.needs[], summary echo,\n AGENTS.md row, registry.json (if a new hook), bats stub (if pre-push).\n\n6. **Set a refresh cadence.** Document in `AGENTS.md` or `GOALS.md`\n when the operator runs the snapshot script (before release,\n weekly, before-each-evolve-session).\n\n## Failure Modes\n\n- **Skipping step 4 (snapshot validator).** Without the validator,\n the snapshot file drifts undetected — operators stop refreshing it,\n and CI claims green forever. The validator forces the cadence.\n- **Snapshot in chat / ephemeral state.** The snapshot MUST be\n git-tracked. A snapshot in a session JSONL is invisible to CI.\n- **Staleness window too long.** > 30 days means the gate\n effectively never fails. Tighten to 7-14 days.\n- **Live gate and snapshot validator disagree on shape.** Schema\n drift between the two scripts; CI passes but the metric is wrong.\n Lock the JSON shape in the snapshot command's documentation.\n\n## Applications (Empirical Reference)\n\nThe pattern shipped 6 times across cycles 22-41 of the 2026-05-11\nevolution-roadmap drain:\n\n| Cycle | Metric | Snapshot path |\n|---|---|---|\n| 22 (D11) | corpus freshness | `docs/releases/corpus-snapshot.json` |\n| 24 (G1) | flywheel compounding | `docs/releases/flywheel-compounding-snapshot.json` |\n| 26 (D10) | workbench delta | `docs/releases/workbench-delta-snapshot.json` |\n| 30 (PG4) | README claim manifest | `docs/releases/readme-claim-manifest.json` |\n| 35 | AOP-CLAIM all-claims map | `docs/releases/aop-claims-all-snapshot.json` |\n| 41 | structural-floor contract gate (the generalization) | per-contract snapshot |\n\nReuse-rate after first ship: 5 reuses in 19 cycles. The pattern is\ndurable.\n\n## See Also\n\n- long-loop-discipline (disk-is-truth axiom) — the principle this\n pattern implements at the CI layer (sibling reference in this dir,\n landing concurrently)\n- [cycle-history.md](cycle-history.md) — the JSONL ledger pattern\n (same disk-truth principle, different consumer)\n- [gate-hygiene.md](gate-hygiene.md) — gate-output parsing; complements\n snapshot validation\n- `docs/learnings/2026-05-12-parity-surface-inventory-grew-from-4-to-7-across-cycles-64-70.md`\n — the 9-surface checklist for wiring any new gate, including\n snapshot gates\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7096,"content_sha256":"4389f42d175a3b8cc01ede21bd117e23861d282a25a4ab3200d1a5aa52cbd3cb"},{"filename":"references/teardown.md","content":"# Teardown Procedure\n\n**Auto-run /post-mortem on the full evolution session:**\n\n```\n/post-mortem \"evolve session: $CYCLE cycles, goals improved: X, harvested: Y\"\n```\n\nThis captures learnings from the ENTIRE evolution run (all cycles, all /rpi invocations) in one council review. The post-mortem harvests follow-up items into `next-work.jsonl`, feeding the next `/evolve` session.\n\n**Compute session fitness trajectory:**\n\n```bash\n# Check if both current-era baseline and final snapshot exist\nGOALS_FILE=\"\"\nif [ -f GOALS.md ]; then\n GOALS_FILE=\"GOALS.md\"\nelif [ -f GOALS.yaml ]; then\n GOALS_FILE=\"GOALS.yaml\"\nfi\n\nACTIVE_BASELINE_PATH=\"\"\nif [ -n \"$GOALS_FILE\" ]; then\n ERA_ID=\"goals-$(shasum -a 256 \"$GOALS_FILE\" | awk '{print substr($1, 1, 12)}')\"\n ACTIVE_BASELINE_PATH=\"$(ls -t \".agents/evolve/fitness-baselines/$ERA_ID\"/*.json 2>/dev/null | head -1 || true)\"\nfi\n\nif [ -n \"$ACTIVE_BASELINE_PATH\" ] && [ -f \"$ACTIVE_BASELINE_PATH\" ] && [ -f .agents/evolve/fitness-latest.json ]; then\n baseline = load(\"$ACTIVE_BASELINE_PATH\")\n final = load(\".agents/evolve/fitness-latest.json\")\n\n # Compute delta — goals that flipped between baseline and final\n improved_count = 0\n regressed_count = 0\n unchanged_count = 0\n delta_rows = []\n\n for final_goal in final.goals:\n baseline_goal = baseline.goals.find(g => g.id == final_goal.id)\n baseline_result = baseline_goal ? baseline_goal.result : \"unknown\"\n final_result = final_goal.result\n\n if baseline_result == \"fail\" and final_result == \"pass\":\n delta = \"improved\"\n improved_count += 1\n elif baseline_result == \"pass\" and final_result == \"fail\":\n delta = \"regressed\"\n regressed_count += 1\n else:\n delta = \"unchanged\"\n unchanged_count += 1\n\n delta_rows.append({goal_id: final_goal.id, baseline_result, final_result, delta})\n\n # Write session-fitness-delta.md with trajectory table\n cat > .agents/evolve/session-fitness-delta.md \u003c\u003c EOF\n # Session Fitness Trajectory\n\n | goal_id | baseline_result | final_result | delta |\n |---------|-----------------|--------------|-------|\n $(for row in delta_rows: \"| ${row.goal_id} | ${row.baseline_result} | ${row.final_result} | ${row.delta} |\")\n\n **Summary:** ${improved_count} improved, ${regressed_count} regressed, ${unchanged_count} unchanged\n EOF\n\n # Include delta summary in user-facing teardown report\n log \"Fitness trajectory: ${improved_count} improved, ${regressed_count} regressed, ${unchanged_count} unchanged\"\nfi\n```\n\n**Then write session summary:**\n\n```bash\ncat > .agents/evolve/session-summary.md \u003c\u003c EOF\n# /evolve Session Summary\n\n**Date:** $(date -Iseconds)\n**Cycles:** $CYCLE of $MAX_CYCLES\n**Goals measured:** $(wc -l \u003c GOALS.yaml goals)\n\n## Cycle History\n$(cat .agents/evolve/cycle-history.jsonl)\n\n## Final Fitness\n$(cat .agents/evolve/fitness-latest.json)\n\n## Post-Mortem\n\u003cpath to post-mortem report from above>\n\n## Next Steps\n- Run \\`/evolve\\` again to continue improving\n- Run \\`/evolve --dry-run\\` to check current fitness without executing\n- Create \\`~/.config/evolve/KILL\\` to prevent future runs\n- Create \\`.agents/evolve/STOP\\` for a one-time local stop\nEOF\n```\n\nReport to user:\n```\n## /evolve Complete\n\nCycles: N of M\nGoals improved: X\nGoals regressed: Y (reverted)\nGoals unchanged: Z\nPost-mortem: \u003cverdict> (see \u003creport-path>)\n\nRun `/evolve` again to continue improving.\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3353,"content_sha256":"1bd3a293cacd488f5ca3e781f2dac05b65813dc8ac4aa89ffa8a4865d4259f72"},{"filename":"references/work-selection-ladder.md","content":"# /evolve — Work-Selection Ladder (Step 3, full procedure)\n\n> Extracted from `skills/evolve/SKILL.md` Step 3 to keep the skill under the 10000-token ceiling (soc-opq5). SKILL.md keeps the summary + this pointer; this file owns the full per-rung procedure, code blocks, quality cascade, and dormancy hard-gate.\n\nSelection is a ladder, not a one-shot check. After every productive cycle, return to the TOP of this step and re-read the queue before considering dormancy.\n\n**Programmatic recommendation (soc-g2qd wire):** when present, consult the ladder primitive first and prefer its `.recommended_bead`; the rungs below are the cross-check + fallback.\n\n```bash\nao evolve next-work --help >/dev/null 2>&1 && RECO_BEAD=$(ao evolve next-work --json 2>/dev/null | jq -r '.recommended_bead // empty')\n```\n\nWhen a repo-local program contract exists, apply a scope filter before Step 4:\n- candidate work that clearly requires immutable-scope edits is not eligible for direct execution\n- prefer harvested, beads, goals, and generated work that can plausibly land within mutable scope\n- if the selected item is inherently out of scope, escalate it or convert it into durable follow-up work instead of invoking `/rpi` and hoping discovery widens scope\n\n**Step 3.0: Scope filter — split-or-defer, never bail (soc-5qit)**\n\nBefore claiming a candidate, gate scope vs session budget. If the work touches > 5 non-uniform files, introduces a new shape (schema field, validator, contract surface), is operator-level epic work, OR `PRODUCTIVE_THIS_SESSION > 5` and would extend an arc rather than close one — route to **scout-mode**, which MUST produce one of:\n\n1. **Split** — `bd create` 2-N child beads (each ≤5 files, single-shape) with `--deps discovered-from:\u003cparent-id>`, annotate parent, then **re-enter Step 3** so the smallest child (or another ready bead) gets claimed THIS cycle.\n2. **Defer** — annotate the candidate with `defer:\u003creason>` and re-enter Step 3 so the next-priority ready bead gets claimed.\n3. **Park** (rare) — `bd update \u003cid> --status blocked --notes \"scope-too-big\"` and re-enter Step 3.\n\nScout NEVER returns \"no work done.\" If `bd ready` ≥1, the loop MUST claim one this cycle. See `references/scout-mode.md` and `references/mechanical-batches.md`.\n\n**Metronome gate:** read `mode_repeat_streak` from `session-state.json`. If `>= 3` AND the candidate would repeat the trailing run's `mode`, BLOCK this rung and jump to the next. If `>= 5`, `bd remember \"metronome-N: \u003cmode>\"` and require operator override. See `references/metronome-gate.md`.\n\n**Step 3.1: Harvested work first**\n\nRead `.agents/rpi/next-work.jsonl` and pick the highest-value unconsumed item. Prefer exact repo match, then concrete implementation work, then higher severity. Read `references/knowledge-loop-integration.md` for the claim/release protocol.\n\n**Step 3.2: Open ready beads**\n\nIf no harvested item is ready, check `bd ready`. Pick the highest-priority unblocked issue.\n\n**Step 3.3: Failing goals and directive gaps** (skip if `--beads-only`)\n\nFirst assess directives, then goals:\n- top-priority directive gap from `ao goals measure --directives`\n- highest-weight failing goals (skip quarantined oscillators)\n- lower-weight failing goals\n\nThis step exists even when all queued work is empty. Goals are the third source, not the stop condition.\n\n```bash\nDIRECTIVES=$(ao goals measure --directives 2>/dev/null)\nFAILING=$(jq -r '.goals[] | select(.result==\"fail\") | .id' .agents/evolve/fitness-latest.json | head -1)\n```\n\n**Oscillation check:** Before working a failing goal, check if it has oscillated (improved-to-fail transitions >= 3 times). If so, quarantine it and try the next goal. See `references/oscillation.md` and `references/fitness-scoring.md` for the detection procedure.\n\n**Duplicate-work guard (mandatory before every generator `bd create`).** The\ngenerators below (3.4–3.7) and the Step-4 Split rung all create beads. A stale\nphase-1 handoff repeatedly re-seeded beads for work already covered by an\nexisting bead or merged PR (ag-b8m≈ag-jov, ag-6kw≈ag-c2i — ag-6jt). Before\n`bd create`, run the guard; skip creation when it reports a duplicate:\n\n```bash\nskills/evolve/scripts/duplicate-work-guard.sh \"\u003ccandidate title>\" || {\n echo \"skip: existing work already covers this surface\"; }\n# exit 1 + \"DUPLICATE: \u003cid> [\u003cstatus>] \u003ctitle>\" → an open/closed bead already\n# covers it (exact title OR significant-token overlap). exit 0 → safe to create.\n```\n\nThis complements the loop's origin/main fast-forward (the cron syncs local\n`main` to `origin/main` before discovery so already-merged work is not re-seen).\n\n**Step 3.4: Testing improvements**\n\nWhen queues and goals are empty, generate concrete testing work via `/test`:\n\n```\nif --no-lifecycle is NOT set:\n Skill(skill=\"test\", args=\"coverage\")\n Only files with \u003c 40% coverage become queue items (severity threshold).\n```\n\nIf `/test` is unavailable or `--no-lifecycle` is set, fall back to manual scanning:\n- find packages/files with thin or missing tests\n- look for missing regression tests around recent bug-fix paths\n- identify flaky or absent headless/runtime smokes\n\nConvert any real finding into durable work:\n- add a bead when the work needs tracked backlog ownership, or\n- append a queue item under the shared next-work contract when it should flow directly back into `/rpi`\n\n**Step 3.5: Validation tightening and bug-hunt passes**\n\nIf testing improvement generation returns nothing, run lifecycle generators then bug-hunt sweeps:\n\n```\nif --no-lifecycle is NOT set:\n a) Skill(skill=\"deps\", args=\"audit\")\n Only deps with CVSS >= 7.0 or 2+ major versions behind become queue items.\n\n b) if perf-sensitive code detected (benchmarks exist, hot path patterns):\n Skill(skill=\"perf\", args=\"profile --quick\")\n Convert significant perf findings to queue items.\n```\n\nIf lifecycle generators return nothing or are skipped, fall back to manual sweeps:\n- missing validation gates\n- weak lint/contract coverage\n- bug-hunt style audits for risky areas\n- stale assumptions between docs, contracts, and runtime truth\n\nAgain: convert findings into beads or queue items, then immediately select the highest-priority result and continue.\n\n**Step 3.6: Drift / hotspot / dead-code mining**\n\nIf the prior generators are empty, mine for complexity debt via `/refactor`:\n\n```\nif --no-lifecycle is NOT set:\n Skill(skill=\"refactor\", args=\"--sweep all --dry-run\")\n Only functions with CC > 20 become queue items (severity threshold).\n```\n\nIf `/refactor` is unavailable or `--no-lifecycle` is set, fall back to manual mining:\n- complexity hotspots\n- stale TODO/FIXME markers\n- dead code\n- stale docs\n- stale research\n- drift between generated artifacts and source-of-truth files\n\nDo not stop here. Normalize findings into tracked work and continue.\n\n**Step 3.7: Feature suggestions**\n\nIf all concrete remediation layers are empty, propose one or more specific feature ideas grounded in the repo purpose, write them as durable work, and continue:\n- create a bead when the feature needs review/backlog treatment\n- or append a queue item with `source: \"feature-suggestion\"` when it is ready for the next `/rpi` cycle\n\n**Quality mode (`--quality`)** — inverted cascade (findings before directives):\n\nStep 3.0q: Unconsumed high-severity post-mortem findings:\n```bash\nHIGH=$(jq -r 'select(.consumed==false) | .items[] | select(.severity==\"high\") | .title' \\\n .agents/rpi/next-work.jsonl 2>/dev/null | head -1)\n```\n\nStep 3.1q: Unconsumed medium-severity findings.\n\nStep 3.2q: Open ready beads.\n\nStep 3.3q: Emergency gates (weight >= 5) and top directive gaps.\n\nStep 3.4q: Testing improvements.\n\nStep 3.5q: Validation tightening / bug-hunt / drift mining.\n\nStep 3.6q: Feature suggestions.\n\nThis inverts the standard cascade only at the top of the ladder: findings BEFORE goals and directives. It does NOT skip the generator layers.\n\nWhen evolve picks a finding, claim it first in next-work.jsonl:\n- Set `claim_status: \"in_progress\"`, `claimed_by: \"evolve-quality:cycle-N\"`, `claimed_at: \"\u003ctimestamp>\"`\n- Set `consumed: true` only after the /rpi cycle and regression gate succeed\n- If the /rpi cycle fails (regression), clear the claim and leave `consumed: false`\n\nSee `references/quality-mode.md` for scoring and full details.\n\n**Nothing found?** HARD GATE — dormancy only when ALL sources empty (soc-5qit):\n\n```bash\nREADY_BEADS=$(bd ready --json 2>/dev/null | jq -r 'length // 0' 2>/dev/null || echo 0)\nHARVESTED=$(jq -r 'select(.consumed==false) | .severity' .agents/rpi/next-work.jsonl 2>/dev/null | wc -l | tr -d ' ')\nFAILING_GOALS=$(jq -r '.goals[] | select(.result==\"fail\") | .id' .agents/evolve/fitness-latest.json 2>/dev/null | wc -l | tr -d ' ')\nIDLE_STREAK=$(jq -r '.idle_streak // 0' .agents/evolve/session-state.json 2>/dev/null)\n\nif [ \"$READY_BEADS\" -gt 0 ] || [ \"$HARVESTED\" -gt 0 ] || [ \"$FAILING_GOALS\" -gt 0 ]; then\n continue # work exists — loop back to Step 3 (agile invariant)\nfi\nif [ \"${GENERATOR_EMPTY_STREAK:-0}\" -ge 2 ] && [ \"${IDLE_STREAK:-0}\" -ge 2 ]; then\n REASON=\"stagnation: all sources empty x3\"\n # soc-g2qd wire: under loop, write-stop-marker refuses → log blocked + operator-wait, never self-halt (ADR-0007).\n if ao evolve write-stop-marker --help >/dev/null 2>&1; then\n ao evolve write-stop-marker --marker dormant --reason \"$REASON\" --mode loop 2>/dev/null \\\n || ao evolve blocked --reason \"$REASON\" --needed-context \"queue empty; operator adds work or marker\" 2>/dev/null || true\n else\n printf '%s\\n%s\\n%s\\n' \"cycle $CYCLE\" \"$(date -u +%FT%TZ)\" \"$REASON\" > .agents/evolve/DORMANT # fallback\n fi\nfi\n```\n\n**Agile invariant (soc-5qit):** `bd ready ≥ 1` ⇒ loop NEVER writes DORMANT, NEVER exits. The only path to DORMANT is fully empty backlog + dry generators. Context exhaustion → HANDOFF, not DORMANT.\n\nIf work layers were empty but generators haven't exhausted 3 passes yet, persist `GENERATOR_EMPTY_STREAK` and loop back to Step 1.\n\nA cycle is idle only if NO work source returned actionable work and every generator layer also came up empty. A cycle that targeted an oscillating goal and skipped it counts as idle only after the remaining ladder was exhausted.\n\nIf `--dry-run`: report what would be worked on and go to Teardown.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10271,"content_sha256":"c1853163e0bff1a7dc8bc79ff5507660028a4e16c68c5e90805570b81fc8e708"},{"filename":"scripts/duplicate-work-guard.sh","content":"#!/usr/bin/env bash\n# duplicate-work-guard.sh — before the evolve-cron-rpi discovery loop creates a\n# tracking bead, check whether an existing OPEN or CLOSED bead already covers the\n# same work. Exits 1 (with the matching bead) when a duplicate is found, 0 when\n# the candidate is genuinely new.\n#\n# Why this exists (ag-6jt/ag-2je): a stale phase-1 handoff kept re-seeding beads\n# for work already merged or already tracked. The prior guard only matched EXACT\n# OPEN-bead titles, so same-surface, different-wording dups slipped through\n# (ag-b8m≈ag-jov, ag-6kw≈ag-c2i — 4th recurrence). This guard matches on:\n# 1. exact normalized title (lowercased, punctuation-stripped), OR\n# 2. significant-token overlap (Jaccard-style: shared / candidate tokens),\n# across both open and closed beads.\n#\n# Usage: duplicate-work-guard.sh \"\u003ccandidate bead title>\"\n# Exit: 0 no match · 1 duplicate found · 2 usage error\n# Env: DUP_GUARD_THRESHOLD (default 0.6) overlap ratio to call it a dup\n# DUP_GUARD_MIN_SHARED (default 3) min shared significant tokens\n# BD_BIN (default \"bd\") bd binary (override for tests)\nset -euo pipefail\n\nTHRESHOLD=\"${DUP_GUARD_THRESHOLD:-0.6}\"\nMIN_SHARED=\"${DUP_GUARD_MIN_SHARED:-3}\"\nBD_BIN=\"${BD_BIN:-bd}\"\n\nusage() {\n echo \"usage: duplicate-work-guard.sh \\\"\u003ccandidate bead title>\\\"\" >&2\n exit 2\n}\n\n[ \"$#\" -ge 1 ] || usage\ncandidate=\"$1\"\n# Reject empty / whitespace-only titles.\n[ -n \"${candidate//[[:space:]]/}\" ] || usage\n\n# All issues including closed (the dup-seeding failure spans merged/closed work).\nbeads_json=\"$(\"$BD_BIN\" list --all --limit 0 --json 2>/dev/null || true)\"\n[ -n \"$beads_json\" ] || beads_json='[]'\n\nmatch=\"$(\n printf '%s' \"$beads_json\" | jq -r \\\n --arg cand \"$candidate\" \\\n --argjson threshold \"$THRESHOLD\" \\\n --argjson min \"$MIN_SHARED\" '\n # Normalize a title to a set of significant (>=3 char) tokens.\n def norm: (. // \"\")\n | ascii_downcase\n | gsub(\"[^a-z0-9]+\"; \" \")\n | split(\" \")\n | map(select(length >= 3))\n | unique;\n ($cand | norm) as $c\n | ($c | length) as $cn\n | [ .[]\n | . as $b\n | ($b.title | norm) as $t\n | ([ $t[] | select(. as $x | $c | index($x) != null) ] | length) as $shared\n | { id: $b.id, status: $b.status, title: $b.title,\n exact: ($cn > 0 and $t == $c),\n shared: $shared,\n ratio: (if $cn > 0 then ($shared / $cn) else 0 end) } ]\n | map(select(.exact or (.shared >= $min and .ratio >= $threshold)))\n | if length == 0 then empty\n else (max_by(.ratio)) | \"DUPLICATE: \\(.id) [\\(.status)] \\(.title)\"\n end\n'\n)\"\n\nif [ -n \"$match\" ]; then\n echo \"$match\"\n exit 1\nfi\n\necho \"OK: no existing work matches \\\"$candidate\\\"\"\nexit 0\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":2753,"content_sha256":"9381324103de90f8b99ae1d921587171df1a65695a9baf2f6c456a677111086d"},{"filename":"scripts/validate.sh","content":"#!/usr/bin/env bash\nset -euo pipefail\nSKILL_DIR=\"$(cd \"$(dirname \"$0\")/..\" && pwd)\"\nPASS=0; FAIL=0\n\ncheck() { if bash -c \"$2\"; then echo \"PASS: $1\"; PASS=$((PASS + 1)); else echo \"FAIL: $1\"; FAIL=$((FAIL + 1)); fi; }\n\ncheck \"SKILL.md exists\" \"[ -f '$SKILL_DIR/SKILL.md' ]\"\ncheck \"SKILL.md has YAML frontmatter\" \"head -1 '$SKILL_DIR/SKILL.md' | grep -q '^---

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\"\ncheck \"SKILL.md has name: evolve\" \"grep -q '^name: evolve' '$SKILL_DIR/SKILL.md'\"\ncheck \"references/ directory exists\" \"[ -d '$SKILL_DIR/references' ]\"\ncheck \"references/ has at least 1 file\" \"[ \\$(ls '$SKILL_DIR/references/' | wc -l) -ge 1 ]\"\ncheck \"SKILL.md mentions kill switch\" \"grep -qi 'kill switch' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions fitness\" \"grep -qi 'fitness' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions GOALS.yaml\" \"grep -q 'GOALS.yaml' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions cycle\" \"grep -qi 'cycle' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions /rpi\" \"grep -q '/rpi' '$SKILL_DIR/SKILL.md'\"\n# Behavioral contracts from retro learnings (2026-02-12)\ncheck \"SKILL.md has KILL file path\" \"grep -q 'KILL' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents regression detection\" \"grep -qi 'regression' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents snapshot enforcement\" \"grep -qi 'snapshot' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents session_start_sha\" \"grep -qi 'session.start.sha\\|cycle_start_sha' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents continuous values\" \"grep -qi 'continuous\\|value.*threshold' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents regression gate\" \"grep -qi 'regression gate' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents post-cycle snapshot\" \"grep -q 'fitness-.*-post' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents oscillation detection\" \"grep -qi 'oscillat' '$SKILL_DIR/SKILL.md'\"\n# Design-level checks (2026-03-01)\ncheck \"Step 0 has oscillation sweep (always-on)\" \"grep -q 'Pre-populate quarantine list' '$SKILL_DIR/SKILL.md'\"\ncheck \"Step 5 has wiring script pre-flight check\" \"grep -q 'if.*check-wiring-closure.sh' '$SKILL_DIR/SKILL.md'\"\ncheck \"No ambiguous YAML fallback in Step 2\" \"! grep -q 'run each goal.*check command manually' '$SKILL_DIR/SKILL.md'\"\ncheck \"CLI required for fitness measurement\" \"grep -q 'CLI is required for fitness measurement' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents harvested-first selection order\" \"grep -Fq 'Harvested \\`.agents/rpi/next-work.jsonl\\` work' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents generator ladder\" \"grep -q 'Testing improvements' '$SKILL_DIR/SKILL.md' && grep -q 'Validation tightening and bug-hunt passes' '$SKILL_DIR/SKILL.md' && grep -q 'Concrete feature suggestions' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents dormancy as last resort\" \"grep -q 'Dormancy is last resort' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents queue claim before consume\" \"grep -q 'claim it first' '$SKILL_DIR/SKILL.md' && grep -Fq 'keep \\`consumed: false\\`' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents session-state persistence\" \"grep -q 'session-state.json' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md documents immediate queue reread after /rpi\" \"grep -Fq 'immediately re-read \\`.agents/rpi/next-work.jsonl\\`' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions repo execution profile\" \"grep -qi 'repo execution profile' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions startup_reads\" \"grep -q 'startup_reads' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions validation_commands\" \"grep -q 'validation_commands' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions definition_of_done\" \"grep -q 'definition_of_done' '$SKILL_DIR/SKILL.md'\"\n\necho \"\"; echo \"Results: $PASS passed, $FAIL failed\"\n[ $FAIL -eq 0 ] && exit 0 || exit 1\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":3705,"content_sha256":"0472feb724f73a14b3da5cb06c086c6a4a28a33ac880e13e624abd61414dafc7"},{"filename":"templates/cron-loop-mode.md","content":"---\ntemplate_version: 1\nverbatim_markers:\n 3-adr-cite: 5bfa1c52a93edff9316b65025a0cc75a97169c61266470cc58037f9a168cf9ba\n unblock-ladder: 745c8de8f69085fc2b5050192de8179ac203e4402a4b78071ef109a015c00bc1\n layer-3-authority: 8a4478939885980823d49ac156d27553c4a42258af5399b6e04f6d7f96016f1b\n no-self-stop: 0d46faf33d696a78fc276b8757e786a3ae72a9e5e894e1038b26757f3eb95f0a\n---\n\n# /evolve loop-mode cron prompt (cycle {{.CronSelfAdjustCounter}})\n\nYou are in /evolve --mode=loop. This is cycle {{.CronSelfAdjustCounter}}.\n\n## Last cycle outcome\n\nShipped: {{range .ShippedCommits}}{{.Sha}} ({{.Bead}}{{if .Scenario}} #{{.Scenario}}{{end}}); {{end}}\nTests delta: {{.TestsDelta}}\n\n## Sub-beads filed this cycle\n\n{{range .SubBeadsFiledThisCycle}}- {{.}}\n{{else}}(none){{end}}\n\n## Recommended next work\n\n{{.NextRecommendedBead}} (advisory; Layer-3 authority may override)\n\n\u003c!-- VERBATIM-PRESERVE:start name=\"3-adr-cite\" -->\nLoad-bearing context: docs/plans/2026-05-21-evolve-loop-epic-design.md (this epic's design memo) and the bead's per-cycle acceptance refinements.\n\u003c!-- VERBATIM-PRESERVE:end -->\n\n\u003c!-- VERBATIM-PRESERVE:start name=\"unblock-ladder\" -->\n## 7-step unblock ladder\n\nIf `bd ready` returns ≥1 unblocked bead, claim and work one.\nIf you feel \"blocked\": log via `ao evolve blocked --reason '\u003ctext>'` (Wave 2). NEVER write a STOP marker.\nThe ladder (programmatic enforcement: soc-mlbm Wave 2):\n1. Shape-compatible ready bead exists → pick it\n2. Sibling pattern in another bead's description → surface match\n3. Decomposable epic → recommend smaller child\n4. Cross-Hop pickup → traverse discovered-from chain\n5. Bug-fix fallback → smallest-surface bug\n6. Still nothing? Log blocked event, pick smallest available P1 anyway\n7. NEVER write STOP. Operator owns stop signals.\n\u003c!-- VERBATIM-PRESERVE:end -->\n\n\u003c!-- VERBATIM-PRESERVE:start name=\"layer-3-authority\" -->\n## Layer-3 shaping authority\n\nThe agent can:\n- File new beads as discoveries land (`bd create` + `discovered-from`)\n- Restructure the DAG\n- Update the cron's recommended-next pointer\n- Write ADRs for emergent precedents in `docs/decisions/`\n\nBounded by: bead-graph coherence, operator-set scope (preferences.yaml), no-self-stop principle.\n\u003c!-- VERBATIM-PRESERVE:end -->\n\n\u003c!-- VERBATIM-PRESERVE:start name=\"no-self-stop\" -->\n## The no-self-stop principle\n\nIn `--mode=loop`, the agent NEVER writes a STOP/DORMANT/KILL marker. `ao evolve write-stop-marker` mechanically refuses (exit 1). When stuck: log via `ao evolve blocked`, pick smallest-available P1 anyway. Stop signals come from the operator, never the agent.\n\u003c!-- VERBATIM-PRESERVE:end -->\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2621,"content_sha256":"a56e192e2b961286a108941219140f42afd5f04bb659e826e575f258fa96fd22"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"/evolve — Goal-Driven Compounding Loop","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Cross-vendor analog:","type":"text","marks":[{"type":"strong"}]},{"text":" Anthropic Managed Agents Outcomes (May 2026). Both close the loop \"agent runs → grader scores against a rubric → agent retries\"; AgentOps does it locally against any model.","type":"text"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Measure what's wrong. Fix the worst thing. Measure again. Compound.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"V2 command surface:","type":"text","marks":[{"type":"strong"}]},{"text":" keep the name ","type":"text"},{"text":"evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":". Use ","type":"text"},{"text":"ao evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the terminal-native loop. It is the top-level operator entrypoint for ","type":"text"},{"text":"ao rpi loop --supervisor","type":"text","marks":[{"type":"code_inline"}]},{"text":", preserving the old ","type":"text"},{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" concept while reusing the v2 RPI loop engine.","type":"text"}]},{"type":"paragraph","content":[{"text":"Operator cadence:","type":"text","marks":[{"type":"strong"}]},{"text":" post-mortem finished work, analyze the current repo state, select or create the next highest-value work item, let ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" handle research, planning, pre-mortem, implementation, and validation, then harvest follow-ups and repeat until a kill switch, max-cycle cap, regression breaker, or real dormancy stops the run.","type":"text"}]},{"type":"paragraph","content":[{"text":"Always-on autonomous loop over ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":". Work selection order:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Harvested ","type":"text","marks":[{"type":"strong"}]},{"text":".agents/rpi/next-work.jsonl","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" work","type":"text","marks":[{"type":"strong"}]},{"text":" (freshest concrete follow-up)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Open ready beads work","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Failing goals and directive gaps","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"ao goals measure","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Testing improvements","type":"text","marks":[{"type":"strong"}]},{"text":" (missing/thin coverage, missing regression tests)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validation tightening and bug-hunt passes","type":"text","marks":[{"type":"strong"}]},{"text":" (gates, audits, bug sweeps)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Complexity / TODO / FIXME / drift / dead code / stale docs / stale research mining","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Concrete feature suggestions","type":"text","marks":[{"type":"strong"}]},{"text":" derived from repo purpose when no sharper work exists","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Work generators","type":"text","marks":[{"type":"strong"}]},{"text":" that feed the selection ladder (auto-invoked, skip with ","type":"text"},{"text":"--no-lifecycle","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skill(skill=\"test\", args=\"coverage\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" → files with \u003c40% coverage become queue items (Step 3.4)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skill(skill=\"refactor\", args=\"--sweep all --dry-run\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" → functions with CC > 20 become queue items (Step 3.6)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skill(skill=\"deps\", args=\"audit\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" → deps with CVSS >= 7.0 or 2+ major versions behind become queue items (Step 3.5)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skill(skill=\"perf\", args=\"profile --quick\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" → perf findings become queue items when hot paths detected (Step 3.5)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Dormancy is last resort.","type":"text","marks":[{"type":"strong"}]},{"text":" Empty current queues mean \"run the generator layers\", not \"stop\". Only go dormant after the queue layers and generator layers come up empty across multiple consecutive passes.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"/evolve # Run until kill switch, max-cycles, or real dormancy\n/evolve --max-cycles=5 # Cap at 5 cycles\n/evolve --dry-run # Show what would be worked on, don't execute\n/evolve --beads-only # Skip goals measurement, work beads backlog only\n/evolve --quality # Quality-first mode: prioritize post-mortem findings\n/evolve --quality --max-cycles=10 # Quality mode with cycle cap\n/evolve --compile # Mine → Defrag warmup before first cycle\n/evolve --compile --max-cycles=5 # Warm knowledge base then run 5 cycles\n/evolve --test-first # Default strict-quality /rpi execution path\n/evolve --no-test-first # Explicit opt-out from test-first mode","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Delineation vs /dream","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Lane","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Runs","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mutates code?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mutates corpus?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Outer loop?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Budget","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/dream","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"nightly, private local","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (heavy)","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (convergence)","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"wall-clock + plateau","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"daytime, operator-driven","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (via ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (light)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"cycle cap","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Dream owns the knowledge compounding layer; ","type":"text"},{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" owns the code compounding layer. Both share fitness-measurement substrate via ","type":"text"},{"text":"corpus.Compute","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"ao goals measure","type":"text","marks":[{"type":"code_inline"}]},{"text":". Run Dream overnight, then start each day with ","type":"text"},{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the freshly-compounded corpus with a clean fitness baseline.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Flags","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Flag","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Default","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--max-cycles=N","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"unlimited","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Stop after ","type":"text"},{"text":"N","type":"text","marks":[{"type":"code_inline"}]},{"text":" completed cycles","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Show planned cycle actions without executing","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip goal measurement and run backlog-only selection","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--skip-baseline","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip first-run baseline snapshot","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--quality","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Prioritize harvested post-mortem findings","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--compile","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"ao mine","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"ao defrag","type":"text","marks":[{"type":"code_inline"}]},{"text":" warmup before cycle 1","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--test-first","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"on","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pass strict-quality defaults through to ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--no-test-first","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Explicitly disable test-first passthrough to ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--no-lifecycle","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"off","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip lifecycle work generators in Steps 3.4-3.6 (/test, /deps, /perf, /refactor). Falls back to manual scanning.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"--mode=burst|loop","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"burst","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Operator-loop; STOP refused. ","type":"text"},{"text":"loop-mode.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/loop-mode.md","title":null}}]},{"text":".","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Steps","type":"text"}]},{"type":"paragraph","content":[{"text":"YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"FULLY AUTONOMOUS.","type":"text","marks":[{"type":"strong"}]},{"text":" Read ","type":"text"},{"text":"references/autonomous-execution.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Every ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" uses ","type":"text"},{"text":"--auto","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do NOT ask the user anything. Each cycle = complete 3-phase ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" run.","type":"text"}]},{"type":"paragraph","content":[{"text":"For broad AgentOps 3.0 domain evolution across skills, CLI, hooks, docs, tests, beads, and knowledge, first read ","type":"text"},{"text":"references/domain-evolution-bootstrap.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/domain-evolution-bootstrap.md","title":null}}]},{"text":". It supplies the BDD/DDD/Hexagonal/TDD/XP control surface and the clean-room skill-factory guardrails.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0: Setup","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"mkdir -p .agents/evolve\nao corpus inject --query \"autonomous improvement cycle\" --limit 5 2>/dev/null || true\nbash scripts/evolve-update-session-state.sh 2>/dev/null || true # refresh derived idle_streak + mode_repeat_streak","type":"text"}]},{"type":"paragraph","content":[{"text":"ao corpus inject","type":"text","marks":[{"type":"code_inline"}]},{"text":" routes through the typed BC1 ","type":"text"},{"text":"CorpusReaderPort","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"cli/cmd/ao/corpus_reader_adapter.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", cycle 112 productionCorpusReader), emitting one ranked ","type":"text"},{"text":"ports.CorpusItem","type":"text","marks":[{"type":"code_inline"}]},{"text":" JSON record per line from ","type":"text"},{"text":".agents/learnings/","type":"text","marks":[{"type":"code_inline"}]},{"text":" by default. This closes soc-y5vh.1 — Step 0 prior-knowledge retrieval is now load-bearing on the typed port, not an untyped ","type":"text"},{"text":"ao lookup","type":"text","marks":[{"type":"code_inline"}]},{"text":" shell-out.","type":"text"}]},{"type":"paragraph","content":[{"text":"Apply retrieved knowledge:","type":"text","marks":[{"type":"strong"}]},{"text":" If learnings are returned, check each for applicability to the current improvement cycle. For applicable learnings, cite by filename and record: ","type":"text"},{"text":"ao metrics cite \"\u003cpath>\" --type applied 2>/dev/null || true","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Prior-failure injection (mandatory):","type":"text","marks":[{"type":"strong"}]},{"text":" read the last 3 entries of ","type":"text"},{"text":".agents/evolve/cycle-history.jsonl","type":"text","marks":[{"type":"code_inline"}]},{"text":". For any with ","type":"text"},{"text":"gate","type":"text","marks":[{"type":"code_inline"}]},{"text":" containing ","type":"text"},{"text":"FAIL|FAILED|BLOCKED","type":"text","marks":[{"type":"code_inline"}]},{"text":", extract failure-surface keywords (","type":"text"},{"text":"registry|bats|markdown|supergate|canary|coverage|toolchain","type":"text","marks":[{"type":"code_inline"}]},{"text":") and search ","type":"text"},{"text":".agents/learnings/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for matching learnings. Print the top matches before work selection. Without this read path, the loop accumulates write-only ledgers and re-derives lessons each cycle. See ","type":"text"},{"text":"references/convergence-mechanics.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full recipe.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before cycle recovery, load the repo execution profile contract when it exists. The repo execution profile is the source for repo policy; the user prompt should mostly supply mission/objective, not restate startup reads, validation bundle, tracker wrapper rules, or ","type":"text"},{"text":"definition_of_done","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Locate ","type":"text"},{"text":"docs/contracts/repo-execution-profile.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"docs/contracts/repo-execution-profile.schema.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the ordered ","type":"text"},{"text":"startup_reads","type":"text","marks":[{"type":"code_inline"}]},{"text":" and bootstrap from those repo paths before selecting work.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cache repo ","type":"text"},{"text":"validation_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tracker_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"definition_of_done","type":"text","marks":[{"type":"code_inline"}]},{"text":" into session state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the repo execution profile is present but missing required fields, stop or downgrade with an explicit warning before cycle 1. Do not silently invent repo policy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read operating-doctrine ADRs (","type":"text"},{"text":"docs/adr/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"docs/decisions/","type":"text","marks":[{"type":"code_inline"}]},{"text":") when present — intent the loop re-reads each cycle: only operator markers stop the loop; the bead queue is a hypothesis re-confirmed against the goal, not spec; file-a-bead when a candidate is architecture disguised as bounded work.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Then load the repo-local autodev program contract when it exists. The execution profile remains the repo bootstrap and landing-policy layer; ","type":"text"},{"text":"PROGRAM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"AUTODEV.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the repo-local execution layer for the current improvement loop.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Locate ","type":"text"},{"text":"PROGRAM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"AUTODEV.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"PROGRAM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" takes precedence.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the resolved program before cycle recovery and cache ","type":"text"},{"text":"program_path","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"mutable_scope","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"immutable_scope","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"validation_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"decision_policy","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"stop_conditions","type":"text","marks":[{"type":"code_inline"}]},{"text":" into session state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the program file exists but is structurally invalid, stop or downgrade with an explicit warning before cycle 1. Do not silently ignore a broken operator contract.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When a program contract exists, prefer work that can land wholly inside mutable scope. Do not silently widen scope around immutable files.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Recover cycle number, generator streaks, and the last claimed work item from disk (survives context compaction). Initialize ","type":"text"},{"text":"CYCLE","type":"text","marks":[{"type":"code_inline"}]},{"text":" from ","type":"text"},{"text":"cycle-history.jsonl","type":"text","marks":[{"type":"code_inline"}]},{"text":", recover ","type":"text"},{"text":"IDLE_STREAK","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"GENERATOR_EMPTY_STREAK","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"LAST_SELECTED_SOURCE","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"CLAIMED_WORK_REF","type":"text","marks":[{"type":"code_inline"}]},{"text":" from ","type":"text"},{"text":"session-state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Circuit breakers:","type":"text","marks":[{"type":"strong"}]},{"text":" Time-based (60 min no productive work).","type":"text"}]},{"type":"paragraph","content":[{"text":"Oscillation quarantine:","type":"text","marks":[{"type":"strong"}]},{"text":" Pre-populate quarantine list from cycle history (scan for goals with 3+ improved-to-fail transitions). See ","type":"text"},{"text":"references/oscillation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Parse flags: ","type":"text"},{"text":"--max-cycles=N","type":"text","marks":[{"type":"code_inline"}]},{"text":" (default unlimited), ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--skip-baseline","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--quality","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--compile","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Track cycle-level execution state:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"evolve_state = {\n cycle: \u003ccurrent cycle number>,\n mode: \u003cstandard|quality|beads-only>,\n test_first: \u003ctrue by default; false only when --no-test-first>,\n repo_profile_path: \u003cdocs/contracts/repo-execution-profile.md or null>,\n startup_reads: \u003cordered repo bootstrap paths>,\n validation_commands: \u003cordered repo validation bundle>,\n tracker_commands: \u003crepo tracker shell wrappers>,\n definition_of_done: \u003crepo stop predicates>,\n program_path: \u003cPROGRAM.md|AUTODEV.md or null>,\n program_mutable_scope: \u003cdeclared mutable paths/globs>,\n program_immutable_scope: \u003cdeclared immutable paths/globs>,\n program_validation_commands: \u003cordered program validation bundle>,\n program_decision_policy: \u003cordered keep/revert rules>,\n program_stop_conditions: \u003cordered cycle done criteria>,\n generator_empty_streak: \u003cconsecutive passes where all generator layers returned nothing>,\n last_selected_source: \u003charvested|beads|goal|directive|testing|validation|bug-hunt|drift|feature>,\n claimed_work: \u003cnull or work reference being worked>,\n queue_refresh_count: \u003cincremented after every /rpi cycle>\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Persist ","type":"text"},{"text":"evolve_state","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":".agents/evolve/session-state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" at each cycle boundary, after work claims, after release/finalize, and during teardown. ","type":"text"},{"text":"cycle-history.jsonl","type":"text","marks":[{"type":"code_inline"}]},{"text":" remains the canonical cycle ledger; ","type":"text"},{"text":"session-state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" carries resume-only state that has not yet earned a committed cycle entry. Both files are ","type":"text"},{"text":"local-only","type":"text","marks":[{"type":"strong"}]},{"text":" (the nested ","type":"text"},{"text":".agents/.gitignore","type":"text","marks":[{"type":"code_inline"}]},{"text":" denies all paths) — record durable milestones in commit messages too. See ","type":"text"},{"text":"references/cycle-history.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for full local-only semantics.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0.2: Compile Warmup (--compile only)","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip if ","type":"text"},{"text":"--compile","type":"text","marks":[{"type":"code_inline"}]},{"text":" was not passed or if ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":". Read ","type":"text"},{"text":"references/knowledge-loop-integration.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full warmup procedure (mine + defrag + signal notes).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0.5: Baseline (first run only)","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip if ","type":"text"},{"text":"--skip-baseline","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" or baseline already exists. Read ","type":"text"},{"text":"references/fitness-scoring.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the baseline capture procedure.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Kill Switch Check","type":"text"}]},{"type":"paragraph","content":[{"text":"Run at the TOP of every cycle:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"CYCLE_START_SHA=$(git rev-parse HEAD)\n# Mechanical pre-cycle gate (soc-sfjx): markers (KILL/STOP/DORMANT/HANDOFF with\n# TTL + soc-5qit non-sticky semantics), goal-regression, and prior-cycle-FAIL.\n# This is a SCRIPT the loop MUST run, not prose it can skip — externalized from\n# the old inline block so the kill-switch + revert-on-red are enforced, not\n# advisory. Adapted from the mt-olympus unbounded-evolve substrate.\nif [ -x scripts/evolve/halt-check.sh ]; then\n if ! HALT_OUT=$(bash scripts/evolve/halt-check.sh --json); then\n REASON=$(printf '%s' \"$HALT_OUT\" | jq -r '.halt_reason // \"unknown\"')\n if [ \"$REASON\" = \"prior_cycle_fail\" ]; then\n export EVOLVE_RESTORATIVE=1 # not terminal: Step 1.5 restricts scope to CI-red reduction\n else\n echo \"halt: $REASON\"; exit 0 # kill/user_halt/dormant/goal_regression -> stop this cycle\n fi\n fi\nelse\n # Fallback for repos without the substrate: minimal inline marker check.\n for m in \"$HOME/.config/evolve/KILL\" .agents/evolve/STOP; do [ -f \"$m\" ] && { echo \"halt: $m\"; exit 0; }; done\n [ -f .agents/evolve/DORMANT ] && { [ \"$(bd ready --json 2>/dev/null | jq -r 'length // 0')\" -gt 0 ] && rm -f .agents/evolve/DORMANT || { echo dormant; exit 0; }; }\n [ -f .agents/evolve/HANDOFF ] && rm -f .agents/evolve/HANDOFF\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Agile-first dormancy (soc-5qit):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"DORMANT","type":"text","marks":[{"type":"code_inline"}]},{"text":" is NEVER sticky while ready beads exist — ","type":"text"},{"text":"halt-check.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" auto-clears it when ","type":"text"},{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]},{"text":"/harvested work exists. KILL/STOP honor ","type":"text"},{"text":"EVOLVE_KILL_TTL_DAYS","type":"text","marks":[{"type":"code_inline"}]},{"text":" (default 7); stale markers are surfaced and bypassed. ","type":"text"},{"text":"goal_regression","type":"text","marks":[{"type":"code_inline"}]},{"text":" (latest cycle report ","type":"text"},{"text":"goals_passing_after \u003c before","type":"text","marks":[{"type":"code_inline"}]},{"text":") halts the loop for operator attention. Heavy-context sessions write non-sticky HANDOFF; the next fire clears it and resumes. The gate is mechanical: see ","type":"text"},{"text":"scripts/evolve/halt-check.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5: Healing-first classifier","type":"text"}]},{"type":"paragraph","content":[{"text":"Before fitness or work selection, classify the cycle: ","type":"text"},{"text":"ao ci recent --limit 1 2>/dev/null | jq -r '.Conclusion // empty'","type":"text","marks":[{"type":"code_inline"}]},{"text":" (typed BC2 ","type":"text"},{"text":"CIStatusPort","type":"text","marks":[{"type":"code_inline"}]},{"text":", soc-y5vh.2). If the last push CI was ","type":"text"},{"text":"failure","type":"text","marks":[{"type":"code_inline"}]},{"text":", this cycle is ","type":"text"},{"text":"restorative-only","type":"text","marks":[{"type":"strong"}]},{"text":" — Step 3 takes only CI-red-reducing work (bug-type harvested items, gate-failure-fix beads, generator bug output); no promotions, features, or new-shape work until green. A ","type":"text"},{"text":"gate=FAIL","type":"text","marks":[{"type":"code_inline"}]},{"text":" in cycle-history.jsonl auto-triggers this for cycle N+1 (and ","type":"text"},{"text":"halt-check.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" surfaces it as ","type":"text"},{"text":"prior_cycle_fail","type":"text","marks":[{"type":"code_inline"}]},{"text":"). See ","type":"text"},{"text":"references/convergence-mechanics.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Convergence check:","type":"text","marks":[{"type":"strong"}]},{"text":" evaluate the STOP predicate via the typed BC3 ","type":"text"},{"text":"ConvergenceCheckPort","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"ao loop converged --green-streak \u003cn> --unconsumed-high-medium \u003cn> [--fitness-baseline]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (soc-y5vh.8). Branch on ","type":"text"},{"text":".converged","type":"text","marks":[{"type":"code_inline"}]},{"text":" (default: CI green streak ≥ 3, HIGH+MEDIUM next-work ≤ 1, fitness baseline captured); if true, emit teardown and do NOT re-arm wakeup.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Measure Fitness","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip if ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":". Run ","type":"text"},{"text":"scripts/evolve-measure-fitness.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" to produce a rolling fitness snapshot at ","type":"text"},{"text":".agents/evolve/fitness-latest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":". Read ","type":"text"},{"text":"references/fitness-scoring.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full measurement procedure, baseline capture, and post-cycle regression detection.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Select Work","type":"text"}]},{"type":"paragraph","content":[{"text":"Selection is a ladder, not a one-shot check — after every productive cycle, return to the TOP and re-read the queue before considering dormancy. ","type":"text"},{"text":"Read ","type":"text","marks":[{"type":"strong"}]},{"text":"references/work-selection-ladder.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/work-selection-ladder.md","title":null}},{"type":"strong"}]},{"text":" for the full per-rung procedure","type":"text","marks":[{"type":"strong"}]},{"text":" (programmatic ","type":"text"},{"text":"ao evolve next-work","type":"text","marks":[{"type":"code_inline"}]},{"text":" recommendation, scope filter, metronome gate, the generator rungs with their code blocks, the ","type":"text"},{"text":"--quality","type":"text","marks":[{"type":"code_inline"}]},{"text":" inverted cascade, and the dormancy hard-gate).","type":"text"}]},{"type":"paragraph","content":[{"text":"Ladder order (standard mode):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.0 Scope filter","type":"text","marks":[{"type":"strong"}]},{"text":" (soc-5qit) — split-or-defer oversized candidates via scout-mode; never bail.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.1 Harvested","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":".agents/rpi/next-work.jsonl","type":"text","marks":[{"type":"code_inline"}]},{"text":", highest-value unconsumed.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.2 Open ready beads","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]},{"text":", highest priority.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.3 Failing goals + directive gaps","type":"text","marks":[{"type":"strong"}]},{"text":" — skip if ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":"; skip quarantined oscillators.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.4–3.6 Generators","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"/test","type":"text","marks":[{"type":"code_inline"}]},{"text":" coverage, ","type":"text"},{"text":"/deps","type":"text","marks":[{"type":"code_inline"}]},{"text":"+","type":"text"},{"text":"/perf","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"/refactor","type":"text","marks":[{"type":"code_inline"}]},{"text":"; findings → beads/queue items.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3.7 Feature suggestions","type":"text","marks":[{"type":"strong"}]},{"text":" grounded in repo purpose.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"--quality","type":"text","marks":[{"type":"code_inline"}]},{"text":" inverts the top (findings before goals/directives). The metronome gate blocks a rung that would repeat the trailing run's ","type":"text"},{"text":"mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" (streak ≥3).","type":"text"}]},{"type":"paragraph","content":[{"text":"Agile invariant (soc-5qit):","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"bd ready ≥ 1","type":"text","marks":[{"type":"code_inline"}]},{"text":" ⇒ the loop NEVER writes DORMANT and NEVER exits. The only path to DORMANT is a fully empty backlog + dry generators (3 passes). Context exhaustion → HANDOFF, not DORMANT. Under loop mode, ","type":"text"},{"text":"write-stop-marker","type":"text","marks":[{"type":"code_inline"}]},{"text":" refuses → log blocked + operator-wait (ADR-0007).","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":": report what would be worked on and go to Teardown.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Execute","type":"text"}]},{"type":"paragraph","content":[{"text":"Primary engine: ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" for implementation-quality work (all 3 phases mandatory). ","type":"text"},{"text":"/implement","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"/crank","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when a bead has execution-ready scope.","type":"text"}]},{"type":"paragraph","content":[{"text":"If a repo-local ","type":"text"},{"text":"PROGRAM.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" contract is active, ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" will load it automatically. ","type":"text"},{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" must compose with that behavior, not bypass it:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not select work that is obviously outside mutable scope.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a bead or goal would require edits under immutable scope, escalate it or convert it into durable follow-up work instead of launching ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When work is plausibly in scope but still uncertain, let ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" discovery validate the fit and surface a scope escape explicitly.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For a ","type":"text"},{"text":"harvested item, failing goal, directive gap, testing improvement, validation tightening task, bug-hunt result, drift finding, or feature suggestion","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Invoke /rpi \"{normalized work title}\" --auto --max-cycles=1","type":"text"}]},{"type":"paragraph","content":[{"text":"For a ","type":"text"},{"text":"beads issue","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Prefer: /rpi \"Land {issue_id}: {title}\" --auto --max-cycles=1\nFallback: /implement {issue_id}","type":"text"}]},{"type":"paragraph","content":[{"text":"Or for an epic with children: ","type":"text"},{"text":"Invoke /crank {epic_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If Step 3 created durable work instead of executing it immediately, re-enter Step 3 and let the newly-created bead item win through the normal selection order.","type":"text"}]},{"type":"paragraph","content":[{"text":"Mechanical-batch hint:","type":"text","marks":[{"type":"strong"}]},{"text":" when the implementation phase identifies > 20 uniform per-file edits, prefer a script (","type":"text"},{"text":"awk","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"sed","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"for f in $candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":") over N tool-level Edit calls. See ","type":"text"},{"text":"references/mechanical-batches.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the decision rule and the script-first pattern.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pre-flight schema check (architectural migrations):","type":"text","marks":[{"type":"strong"}]},{"text":" if the selected work is a port/adapter migration that rewires an existing consumer, BEFORE invoking ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":", sample two representative consumer call sites and compare field-use against the target port surface. If the consumer reads > 20% more fields than the port projects, abort the migration cycle and convert the work into a port-widening cycle instead. The phase-2 narrowness post-mortem (","type":"text"},{"text":"docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md","type":"text","marks":[{"type":"code_inline"}]},{"text":") is the encoded lesson; see ","type":"text"},{"text":"references/pre-flight-schema-check.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the procedure.","type":"text"}]},{"type":"paragraph","content":[{"text":"Operator-shape carve-out:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" is permitted ONLY for shape decisions affecting > 50 files OR a schema/contract surface (carrier choice, struct-field shape, frontmatter-key shape). See ","type":"text"},{"text":"references/autonomous-execution.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the bound on this exception.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4.5: Source-surface detection (pre-gate sync)","type":"text"}]},{"type":"paragraph","content":[{"text":"Before invoking the regression gate, sync downstream artifacts when the staged diff touches binary or embedded surfaces:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cli/**/*.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" changed → ","type":"text"},{"text":"cd cli && make build && go install ./cmd/ao","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills/**","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"hooks/**","type":"text","marks":[{"type":"code_inline"}]},{"text":" changed → ","type":"text"},{"text":"cd cli && make sync-hooks","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills-codex/**","type":"text","marks":[{"type":"code_inline"}]},{"text":" changed → ","type":"text"},{"text":"bash scripts/regen-codex-hashes.sh","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Without these, the gate fails on stale-binary or embedded-drift errors that look like real regressions. See ","type":"text"},{"text":"references/gate-hygiene.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the detection recipe.","type":"text"}]},{"type":"paragraph","content":[{"text":"Adding or modifying a skill?","type":"text","marks":[{"type":"strong"}]},{"text":" A skill touches ","type":"text"},{"text":"six derived surfaces","type":"text","marks":[{"type":"strong"}]},{"text":" (registry.json SKU catalog, skill-domain-map, context-map, skill counts + the hand-added ","type":"text"},{"text":"SKILL-TIERS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" row, codex twin, narrative counts) — regenerate them in one shot via ","type":"text"},{"text":"scripts/regen-all.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" + the codex/count steps, never piecemeal. The most-missed is ","type":"text"},{"text":"registry.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (stale → ","type":"text"},{"text":"contracts-sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"correctness(ubuntu)","type":"text","marks":[{"type":"code_inline"}]},{"text":" fail together). See ","type":"text"},{"text":"references/new-skill-landing.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/new-skill-landing.md","title":null}}]},{"text":" for the full procedure, then ","type":"text"},{"text":"references/gate-hygiene.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/gate-hygiene.md","title":null}}]},{"text":" for the pre-push diff-scope check + pre-existing-vs-mine red triage.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Regression Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After execution, run the project build+test bundle. If the repo execution profile declared ","type":"text"},{"text":"validation_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":", run them. If a repo-local program contract exists, run its ","type":"text"},{"text":"validation_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":" too, de-duplicated and in declared order after the repo bootstrap checks. Also check ","type":"text"},{"text":"if [ -f scripts/check-wiring-closure.sh ]; then bash scripts/check-wiring-closure.sh; fi","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the program contract's ","type":"text"},{"text":"decision_policy","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the first keep/revert rule set for the cycle:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if the cycle breached immutable scope, treat it as regressed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if program validation commands fail, treat it as regressed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if the decision policy declares a revert rule that fired, revert before consuming claimed work or advancing the queue","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Treat program ","type":"text"},{"text":"stop_conditions","type":"text","marks":[{"type":"code_inline"}]},{"text":" as per-cycle done criteria. Do not mark claimed work consumed, completed, or productive until both the stop conditions and the regression gate pass.","type":"text"}]},{"type":"paragraph","content":[{"text":"If not ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":", re-measure fitness to ","type":"text"},{"text":"fitness-latest-post.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" and detect regressions. The AgentOps CLI is required for fitness measurement. Read ","type":"text"},{"text":"references/fitness-scoring.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full measurement, regression detection, and revert procedure.","type":"text"}]},{"type":"paragraph","content":[{"text":"Gate output parsing:","type":"text","marks":[{"type":"strong"}]},{"text":" trust the structural marker ","type":"text"},{"text":"^.*Pass [0-9]+: (FAILED|BLOCKED)","type":"text","marks":[{"type":"code_inline"}]},{"text":" over the trailing status line — the trailing line conflates blocking and advisory results. See ","type":"text"},{"text":"references/gate-hygiene.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Work finalization after the regression gate: claim it first, then keep ","type":"text"},{"text":"consumed: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" until the /rpi cycle succeeds. After the cycle's ","type":"text"},{"text":"/post-mortem","type":"text","marks":[{"type":"code_inline"}]},{"text":" finishes, immediately re-read ","type":"text"},{"text":".agents/rpi/next-work.jsonl","type":"text","marks":[{"type":"code_inline"}]},{"text":" before selecting the next item. Read ","type":"text"},{"text":"references/knowledge-loop-integration.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for full claim/release semantics.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 6: Log Cycle + Commit","type":"text"}]},{"type":"paragraph","content":[{"text":"Two paths: productive cycles get committed, idle cycles are local-only.","type":"text"}]},{"type":"paragraph","content":[{"text":"PRODUCTIVE cycles","type":"text","marks":[{"type":"strong"}]},{"text":" (result is improved, regressed, or harvested): compute quality score (if ","type":"text"},{"text":"--quality","type":"text","marks":[{"type":"code_inline"}]},{"text":"), log via ","type":"text"},{"text":"scripts/evolve-log-cycle.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":", commit if real changes exist. See ","type":"text"},{"text":"references/quality-mode.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for scoring.","type":"text"}]},{"type":"paragraph","content":[{"text":"IDLE cycles","type":"text","marks":[{"type":"strong"}]},{"text":" (nothing found even after generator layers): log via ","type":"text"},{"text":"evolve-log-cycle.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"--result \"unchanged\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". No git add, no commit.","type":"text"}]},{"type":"paragraph","content":[{"text":"Record the XP/BDD/TDD trace.","type":"text","marks":[{"type":"strong"}]},{"text":" When a cycle worked a product or goal-backed gap, pass ","type":"text"},{"text":"--trace-json","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"evolve-log-cycle.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"ao loop append","type":"text","marks":[{"type":"code_inline"}]},{"text":") so the cycle records the continuous-evolution kernel — goal hypothesis → selected gap → Gherkin scenario → first failing proof → red/green evidence → refactor note → validation evidence → ratchet action → goal reshape — and a reviewer can reconstruct the cycle without the transcript. A trivial one-shot cycle records a ","type":"text"},{"text":"trace.exemption_reason","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead of carrying false BDD/TDD ceremony. Trace completeness is advisory, never a gate. See ","type":"text"},{"text":"references/cycle-history.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (\"XP/BDD/TDD Evidence Trace\").","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7: Loop or Stop","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"while true; do\n # Step 1 .. Step 6\n # Stop ONLY if: operator override (KILL/STOP), max-cycles, regression-breaker,\n # or genuine stagnation (bd ready=0 AND harvested=0 AND failing-goals=0 AND\n # generators dry across 3 passes). Context exhaustion is NOT a stop — it's a\n # session-handoff signal (HANDOFF marker) that the next cron-fire clears.\n CYCLE=$((CYCLE + 1))\ndone","type":"text"}]},{"type":"paragraph","content":[{"text":"Stop reasons (soc-5qit, ALL require genuine reason — never just context size):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"KILL/STOP file present","type":"text","marks":[{"type":"strong"}]},{"text":" — operator override.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--max-cycles=N","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" cap reached","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Genuine stagnation","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"bd ready=0 AND harvested-unconsumed=0 AND failing-goals=0 AND GENERATOR_EMPTY_STREAK>=2 AND IDLE_STREAK>=2","type":"text","marks":[{"type":"code_inline"}]},{"text":". Writes DORMANT, which auto-clears in Step 1 the moment ","type":"text"},{"text":"bd create","type":"text","marks":[{"type":"code_inline"}]},{"text":" adds a new ready bead.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Regression breaker after a revert","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Context exhaustion is NOT a stop (soc-5qit).","type":"text","marks":[{"type":"strong"}]},{"text":" Heavy-context sessions write ","type":"text"},{"text":".agents/evolve/HANDOFF","type":"text","marks":[{"type":"code_inline"}]},{"text":" (non-sticky), log ","type":"text"},{"text":"result: \"context-handoff\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" to cycle-history, and exit the turn cleanly. The next cron-fire (compacted/fresh context) clears HANDOFF in Step 1 and resumes. The loop is continuous across compactions; never write DORMANT for context size. See ","type":"text"},{"text":"references/context-budget.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Mandatory checkpoint #6 — session-PR threshold (NOT terminal, gates next cycle):","type":"text","marks":[{"type":"strong"}]},{"text":" at ","type":"text"},{"text":"session_pr_count >= 5","type":"text","marks":[{"type":"code_inline"}]},{"text":" (soc-waxr default), invoke ","type":"text"},{"text":"/post-mortem --deep","type":"text","marks":[{"type":"code_inline"}]},{"text":", wait for verdict file. PASS → continue. WARN → continue with caveat in next cycle's ","type":"text"},{"text":"notes","type":"text","marks":[{"type":"code_inline"}]},{"text":". FAIL or non-convergence → write STOP. Agent MUST NOT self-grade or self-write STOP. Full procedure in ","type":"text"},{"text":"references/postmortem-checkpoint.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (soc-n75z).","type":"text"}]},{"type":"paragraph","content":[{"text":"Self-perpetuation modes:","type":"text","marks":[{"type":"strong"}]},{"text":" the terminal-native ","type":"text"},{"text":"ao evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" loop and the Claude-Code-harness ","type":"text"},{"text":"ScheduleWakeup","type":"text","marks":[{"type":"code_inline"}]},{"text":" end-of-turn pattern are duals — both drive Step 1..Step 7 repeatedly against the same persisted state. See ","type":"text"},{"text":"references/autonomous-execution.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the ScheduleWakeup cadence and the rule that hard stops must NOT re-arm.","type":"text"}]},{"type":"paragraph","content":[{"text":"Push only when productive work has accumulated:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"if [ $((PRODUCTIVE_THIS_SESSION % 5)) -eq 0 ] && [ \"$PRODUCTIVE_THIS_SESSION\" -gt 0 ]; then\n git push\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Drive to completion (orchestrator-merge model, soc-2drk).","type":"text","marks":[{"type":"strong"}]},{"text":" Where the repo requires PRs (branch protection rejects direct ","type":"text"},{"text":"main","type":"text","marks":[{"type":"code_inline"}]},{"text":" pushes), a productive cycle does not stop at \"PR opened\" — the loop is the orchestrator that drives each bead to ","type":"text"},{"text":"merged","type":"text","marks":[{"type":"em"}]},{"text":". Ship the bead from its per-bead worktree as a PR (trailers ","type":"text"},{"text":"Closes-scenario","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"Bounded-context","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"Evidence","type":"text","marks":[{"type":"code_inline"}]},{"text":"), wait for CI, and ","type":"text"},{"text":"squash-merge to main yourself once CI is green","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"gh pr merge \u003cN> --squash --admin","type":"text","marks":[{"type":"code_inline"}]},{"text":"), then ","type":"text"},{"text":"bd close","type":"text","marks":[{"type":"code_inline"}]},{"text":" the bead and remove the worktree. ","type":"text"},{"text":"Green CI is the only merge gate","type":"text","marks":[{"type":"strong"}]},{"text":" — on a quality/test red, fix-and-repush or revert; never merge red. The loop may dispatch sub-agents to implement and drives their PRs to merge too. The operator stays ","type":"text"},{"text":"on","type":"text","marks":[{"type":"em"}]},{"text":" the loop (intent + STOP marker), not ","type":"text"},{"text":"in","type":"text","marks":[{"type":"em"}]},{"text":" it (per-PR approval). This ","type":"text"},{"text":"supersedes \"operator is the merge gate\"","type":"text","marks":[{"type":"strong"}]},{"text":" for the autonomous loop — see ","type":"text"},{"text":"ADR-0008","type":"text","marks":[{"type":"link","attrs":{"href":"../../docs/adr/ADR-0008-evolve-intelligent-agile-operating-model.md","title":null}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Teardown","type":"text"}]},{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"references/knowledge-loop-integration.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full teardown learning extraction procedure (commit staged artifacts, run ","type":"text"},{"text":"/post-mortem","type":"text","marks":[{"type":"code_inline"}]},{"text":", push, report summary).","type":"text"}]},{"type":"paragraph","content":[{"text":"A teardown ","type":"text"},{"text":"/post-mortem","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a light-touch retrospective on session-end. It does NOT substitute for the mandatory threshold checkpoint (","type":"text"},{"text":"references/postmortem-checkpoint.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"); that one is council-gated and edge-triggered at ","type":"text"},{"text":"session_pr_count >= 5","type":"text","marks":[{"type":"code_inline"}]},{"text":". Never write ","type":"text"},{"text":".agents/evolve/STOP","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a substitute for the checkpoint's verdict file — STOP without a verdict is the 2026-05-20 anti-pattern (soc-n75z).","type":"text"}]},{"type":"paragraph","content":[{"text":"Release-context teardown (MANDATORY when the loop ran on a release-shaped branch):","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"When the current branch matches ","type":"text"},{"text":"release/*","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"v*-prep","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"v*-evolve-run","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"v\\d+\\.\\d+*","type":"text","marks":[{"type":"code_inline"}]},{"text":", the teardown report MUST NOT recommend ","type":"text"},{"text":"/release","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the next step. Instead, emit the explicit pre-release checklist below — the operator must run these AND confirm green before tagging:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"## Pre-release checklist — REQUIRED before /release\n\nThe autonomous loop has stopped, but release-readiness gates have NOT been run\nduring cycles. The operator MUST run the following sequence and confirm green\nbefore invoking /release. Do NOT skip any of these on the basis of \"cycles\nwere green\" — fast pre-push gate ≠ full pre-push gate; goals-measure ≠\nrelease readiness.\n\n [ ] 1. Regenerate CLI reference docs if any cobra command/flag changed:\n bash scripts/generate-cli-reference.sh\n git diff cli/docs/COMMANDS.md # commit if non-empty\n\n [ ] 2. Run the FULL pre-push gate (NOT --fast):\n bash scripts/pre-push-gate.sh\n\n [ ] 3. Run the release-readiness gate:\n bash scripts/ci-local-release.sh\n\n [ ] 4. (Recommended) Smoke /evolve with the new typed read paths if BC port\n wire-ups changed:\n /evolve --quick --max-cycles=1 --dry-run\n\nOnly after [1]–[3] pass: /release \u003cversion>\n\nIf any check fails, fix the issue, re-run all four, then ship.","type":"text"}]},{"type":"paragraph","content":[{"text":"The handoff artifact (e.g., ","type":"text"},{"text":".agents/runs/\u003crelease>/READY-TO-TAG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":") MUST contain this checklist verbatim, unchecked, when written by the loop. The operator checks the boxes as they complete each gate; \"ready to tag\" means the boxes are checked, not that the loop ran cleanly.","type":"text"}]},{"type":"paragraph","content":[{"text":"Rationale:","type":"text","marks":[{"type":"strong"}]},{"text":" cycles 170-183 of the v2.41-evolve-run shipped clean code, all unit/integration tests green, ","type":"text"},{"text":"ao goals measure","type":"text","marks":[{"type":"code_inline"}]},{"text":" 0/30 failing for three consecutive cycles — but the loop never ran the full pre-push gate, ","type":"text"},{"text":"ci-local-release.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"generate-cli-reference.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":". The latter was load-bearing (the branch removed a CLI flag). Per-cycle ","type":"text"},{"text":"--fast","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a smoke test, not release readiness. Operator caught the gap; this checklist makes it mechanical.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/evolve --max-cycles=5","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"What happens:","type":"text","marks":[{"type":"strong"}]},{"text":" Evolve re-enters the full selection ladder after every ","type":"text"},{"text":"/rpi","type":"text","marks":[{"type":"code_inline"}]},{"text":" cycle and runs producer layers instead of idling on empty queues.","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/evolve --beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"What happens:","type":"text","marks":[{"type":"strong"}]},{"text":" Evolve skips goals measurement and works through ","type":"text"},{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]},{"text":" backlog.","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/evolve --dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"What happens:","type":"text","marks":[{"type":"strong"}]},{"text":" Evolve shows what would be worked on without executing.","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/evolve --compile","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"What happens:","type":"text","marks":[{"type":"strong"}]},{"text":" Evolve runs ","type":"text"},{"text":"ao mine","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"ao defrag","type":"text","marks":[{"type":"code_inline"}]},{"text":" at session start to surface fresh signal (orphaned research, code hotspots, oscillating goals) before the first evolve cycle. Use before a long autonomous run or after a burst of development activity.","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/evolve","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"What happens:","type":"text","marks":[{"type":"strong"}]},{"text":" See ","type":"text"},{"text":"references/examples.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a worked overnight flow that moves through beads -> harvested work -> goals -> testing -> bug hunt -> feature suggestion before dormancy is considered.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/examples.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for detailed walkthroughs.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Solution","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Loop exits immediately","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Remove ","type":"text"},{"text":"~/.config/evolve/KILL","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":".agents/evolve/STOP","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Stagnation after repeated empty passes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Queue layers and producer layers were empty across multiple passes — dormancy is the fallback outcome","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ao goals measure","type":"text","marks":[{"type":"code_inline"}]},{"text":" hangs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"--timeout 30 --total-timeout 75","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"--beads-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" to skip","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Regression gate reverts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Review reverted changes, narrow scope, re-run; claimed work items must be released back to available state","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/cycle-history.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for advanced troubleshooting.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/evolve.feature","type":"text","marks":[{"type":"link","attrs":{"href":"references/evolve.feature","title":null}}]},{"text":" — Executable spec: gated cycles, ladder, bounded slice, never-self-halt","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/long-loop-discipline.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/long-loop-discipline.md","title":null}}]},{"text":" — Disk-is-truth axiom","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/artifacts.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/artifacts.md","title":null}}]},{"text":" — Generated files registry","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/autonomous-execution.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/autonomous-execution.md","title":null}}]},{"text":" — Autonomous-loop rules + operator-shape carve-out","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/snapshot-pattern-for-long-cycle-gates.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/snapshot-pattern-for-long-cycle-gates.md","title":null}}]},{"text":" — Snapshot pattern for long-cycle gates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/compounding.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/compounding.md","title":null}}]},{"text":" — Knowledge flywheel and work harvesting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/context-budget.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-budget.md","title":null}}]},{"text":" — ","type":"text"},{"text":"CONTEXT_BUDGET_EXHAUSTED","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a third stop reason and handoff protocol","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/convergence-mechanics.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/convergence-mechanics.md","title":null}}]},{"text":" — Read-path mechanisms for compounding","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/domain-evolution-bootstrap.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/domain-evolution-bootstrap.md","title":null}}]},{"text":" — BDD/DDD/Hexagonal/TDD/XP control surface for skill/domain evolution","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/cycle-history.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/cycle-history.md","title":null}}]},{"text":" — JSONL format, recovery protocol, kill switch","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/examples.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/examples.md","title":null}}]},{"text":" — Detailed usage examples","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/fitness-scoring.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fitness-scoring.md","title":null}}]},{"text":" — Baseline capture, regression detection, revert procedure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/gate-hygiene.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/gate-hygiene.md","title":null}}]},{"text":" — Pre-gate source-surface detection, structural gate-output parsing, pre-push diff-scope check, pre-existing-vs-mine red triage","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/new-skill-landing.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/new-skill-landing.md","title":null}}]},{"text":" — The six derived surfaces a new/modified skill must regenerate in one shot to stay one-shot-green","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/goals-schema.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/goals-schema.md","title":null}}]},{"text":" — GOALS.yaml format and continuous metrics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/knowledge-loop-integration.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/knowledge-loop-integration.md","title":null}}]},{"text":" — Claim/release semantics and harvest re-read","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/mechanical-batches.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/mechanical-batches.md","title":null}}]},{"text":" — Script-first vs per-file Edit for > 20-file uniform batches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/metronome-gate.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/metronome-gate.md","title":null}}]},{"text":" — Cross-cycle same-mode-repeat blocker","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/oscillation.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/oscillation.md","title":null}}]},{"text":" — Oscillation detection and quarantine","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/pre-flight-schema-check.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/pre-flight-schema-check.md","title":null}}]},{"text":" — Cheap field-fit check before architectural migration cycles","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/postmortem-checkpoint.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/postmortem-checkpoint.md","title":null}}]},{"text":" — Stop reason #6: session-PR post-mortem checkpoint (soc-n75z)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/parallel-execution.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/parallel-execution.md","title":null}}]},{"text":" — Parallel /swarm architecture","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/quality-mode.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/quality-mode.md","title":null}}]},{"text":" — Quality-first mode: scoring, priority cascade, artifacts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/scout-mode.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/scout-mode.md","title":null}}]},{"text":" — Scout-mode as a first-class cycle result; scope filter procedure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/teardown.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/teardown.md","title":null}}]},{"text":" — Trajectory computation and session summary","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"See Also","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills/dream/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the nightly knowledge compounder; absorbs /harvest and runs the compounding loop overnight","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills/rpi/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — Full lifecycle orchestrator (called per cycle)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skills/crank/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — Epic execution (called for beads epics)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs/contracts/autodev-program.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — Repo-local operational contract for bounded autonomous development","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GOALS.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" — Fitness goals for this repo","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"test","type":"text","marks":[{"type":"link","attrs":{"href":"../test/SKILL.md","title":null}}]},{"text":" — Test generation and coverage analysis","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"refactor","type":"text","marks":[{"type":"link","attrs":{"href":"../refactor/SKILL.md","title":null}}]},{"text":" — Safe, verified refactoring","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"deps","type":"text","marks":[{"type":"link","attrs":{"href":"../deps/SKILL.md","title":null}}]},{"text":" — Dependency audit and vulnerability scanning","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"perf","type":"text","marks":[{"type":"link","attrs":{"href":"../perf/SKILL.md","title":null}}]},{"text":" — Performance profiling and benchmarking","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"evolve","author":"@skillopedia","source":{"stars":375,"repo_name":"agentops","origin_url":"https://github.com/boshu2/agentops/blob/HEAD/skills/evolve/SKILL.md","repo_owner":"boshu2","body_sha256":"b5f9a05baf8bb1102167bc3e79494c60c4f467f89a340751816d05dce565c65b","cluster_key":"272b0903542130d6fc29944b2455f42b59b558ceecf1ad12dedb6cca38ed8001","clean_bundle":{"format":"clean-skill-bundle-v1","source":"boshu2/agentops/skills/evolve/SKILL.md","attachments":[{"id":"7b7f0bb2-8654-5a07-b2e0-cc310a25f74e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7b7f0bb2-8654-5a07-b2e0-cc310a25f74e/attachment.md","path":"references/artifacts.md","size":1959,"sha256":"11fe2617ad1c4e248188afe2b0b8db34b9f835205ef750d2bac1f84a8b327250","contentType":"text/markdown; charset=utf-8"},{"id":"e525d080-f579-5909-b9f8-db187633dad6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e525d080-f579-5909-b9f8-db187633dad6/attachment.md","path":"references/autonomous-execution.md","size":4818,"sha256":"76c0205d47163db61fc6ef582e47ec2b79094978634c17e9c616b16a038d0695","contentType":"text/markdown; charset=utf-8"},{"id":"1a85a9dd-ae0e-5ece-be01-a42ddd4c57b6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1a85a9dd-ae0e-5ece-be01-a42ddd4c57b6/attachment.md","path":"references/compounding.md","size":2603,"sha256":"75094556f3846d3d70aba7657e85111d7c81d1cfadb5872db06813078f08a2f1","contentType":"text/markdown; charset=utf-8"},{"id":"21c89462-d8e0-582c-ab95-1a31ae0b1db9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/21c89462-d8e0-582c-ab95-1a31ae0b1db9/attachment.md","path":"references/context-budget.md","size":4906,"sha256":"32501c1a951b195e37cf7c13e137dd9ee07b6e6f5ca6f25d6ee7362ad5fbdad1","contentType":"text/markdown; charset=utf-8"},{"id":"7b8f7ce7-85fc-51c6-987c-c08720788fc1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7b8f7ce7-85fc-51c6-987c-c08720788fc1/attachment.md","path":"references/convergence-mechanics.md","size":5491,"sha256":"73b4f3f224a76f754d3866c5695460b136a83cc087e53a5fa42837cb437f3dbc","contentType":"text/markdown; charset=utf-8"},{"id":"48bf9bb1-a9cb-5bd3-b385-616ef7bcee85","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/48bf9bb1-a9cb-5bd3-b385-616ef7bcee85/attachment.md","path":"references/cycle-history.md","size":14715,"sha256":"ded24b70ff40f1e1f8e400c40b75bb6d3db2c7365ca5fe43f4c4eb1fe3653d48","contentType":"text/markdown; charset=utf-8"},{"id":"cfa1bac0-328e-53a0-8532-d1b4fdc68f8f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cfa1bac0-328e-53a0-8532-d1b4fdc68f8f/attachment.md","path":"references/domain-evolution-bootstrap.md","size":1972,"sha256":"5f5f75a17adb074c951358c7d6e6340fa1f3626243afbe25699d84d6dff49b15","contentType":"text/markdown; charset=utf-8"},{"id":"7b337ce4-6324-5af5-a497-96e34ba9e6d0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7b337ce4-6324-5af5-a497-96e34ba9e6d0/attachment.feature","path":"references/evolve.feature","size":1796,"sha256":"d13ed60c7a1540568461f781781fe4c5be239e446336f9b16463a075605a3625","contentType":"text/plain; charset=utf-8"},{"id":"83ea6ab6-69de-55a1-ad9f-6616b8aed115","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/83ea6ab6-69de-55a1-ad9f-6616b8aed115/attachment.md","path":"references/examples.md","size":3878,"sha256":"4d98b99c6f75c71bfc595f90189e391d994a5b2d5ca08705b7122d92220f2d55","contentType":"text/markdown; charset=utf-8"},{"id":"ddabdc9f-ba87-59a1-bbf0-9bd24582b00e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ddabdc9f-ba87-59a1-bbf0-9bd24582b00e/attachment.md","path":"references/fitness-scoring.md","size":3241,"sha256":"6826426f73b07a7fd19179fdd61d177973f6304b016df0d60573a1399783e494","contentType":"text/markdown; charset=utf-8"},{"id":"569b9b44-14c4-5dbe-bcaf-2763d6bf68a8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/569b9b44-14c4-5dbe-bcaf-2763d6bf68a8/attachment.md","path":"references/gate-hygiene.md","size":5340,"sha256":"e5af09cca5e78a4a382c0ddf8fe1be0a929a114d88c155428c03a3b089cbd650","contentType":"text/markdown; charset=utf-8"},{"id":"a52c5515-4920-5bc5-895e-2df4ad0a4a57","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a52c5515-4920-5bc5-895e-2df4ad0a4a57/attachment.md","path":"references/goals-schema.md","size":4550,"sha256":"207464bbde3290c65a03089d3e438889d520dc69a5ba2c720e5a07022ea9d71e","contentType":"text/markdown; charset=utf-8"},{"id":"a12025d6-0f45-54eb-baa9-ec3e87978894","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a12025d6-0f45-54eb-baa9-ec3e87978894/attachment.md","path":"references/knowledge-loop-integration.md","size":2823,"sha256":"1945d1c7332d096fd02c1f8cb2b27d583e2c3c9d9d1c04961277aeb32f746a7c","contentType":"text/markdown; charset=utf-8"},{"id":"abb8a0fd-e7c0-5b49-a104-4e206fd945ea","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/abb8a0fd-e7c0-5b49-a104-4e206fd945ea/attachment.md","path":"references/long-loop-discipline.md","size":5196,"sha256":"d9eb31d071c49e5664656c0f5a4694e8ec65f88610513cd06f20b9ccf073b3ae","contentType":"text/markdown; charset=utf-8"},{"id":"24b3ce19-a53c-5727-87f5-683775f1bfe4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/24b3ce19-a53c-5727-87f5-683775f1bfe4/attachment.md","path":"references/loop-mode.md","size":897,"sha256":"802d6aa812636127220a5d6a31d7e3e1bb446004cf9e1d43feaa62a35f47dc0e","contentType":"text/markdown; charset=utf-8"},{"id":"028c677c-521c-5eac-82cf-1492932e4720","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/028c677c-521c-5eac-82cf-1492932e4720/attachment.md","path":"references/mechanical-batches.md","size":2782,"sha256":"28199aed831bf4af14ffa909452f07f243841d315fe43a5c90f67915da0b9d3c","contentType":"text/markdown; charset=utf-8"},{"id":"60c4f625-2e44-5b5a-adb0-908f801e944a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/60c4f625-2e44-5b5a-adb0-908f801e944a/attachment.md","path":"references/metronome-gate.md","size":4393,"sha256":"0533fe8c30817a8c754f80d8b5083e6b84bf9b4401e6d9528d61b9a2daaae44c","contentType":"text/markdown; charset=utf-8"},{"id":"55a8f590-69ca-50e8-80f7-03d4dfc0173a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/55a8f590-69ca-50e8-80f7-03d4dfc0173a/attachment.md","path":"references/new-skill-landing.md","size":2602,"sha256":"6806a90157d876396677a23816609bdf7e595d382f50bd4ab877e6ad4c24f42e","contentType":"text/markdown; charset=utf-8"},{"id":"6c2bf8f9-cc98-52b6-8140-6e866773d390","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6c2bf8f9-cc98-52b6-8140-6e866773d390/attachment.md","path":"references/oscillation.md","size":1953,"sha256":"62cac764158b0fc2e98cfdac0828b13bbc2f91d1f7eb301fa42f3137641960cf","contentType":"text/markdown; charset=utf-8"},{"id":"40929f6c-a2b6-58c7-b776-c49945af689e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/40929f6c-a2b6-58c7-b776-c49945af689e/attachment.md","path":"references/parallel-execution.md","size":5329,"sha256":"0e9eaac66e506d2d39b0d7243bd379482a96a033d38c1c921b1edc5d0f0e0e38","contentType":"text/markdown; charset=utf-8"},{"id":"71bb4e32-5d7f-51db-95eb-1b078ea87070","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/71bb4e32-5d7f-51db-95eb-1b078ea87070/attachment.md","path":"references/postmortem-checkpoint.md","size":6469,"sha256":"61b464a9de46eb4f5918d56eabf64f57a3e866a68c6d3c479dd808619978bf46","contentType":"text/markdown; charset=utf-8"},{"id":"37bce8f9-7a2d-590b-a2ff-5687c5c1004e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/37bce8f9-7a2d-590b-a2ff-5687c5c1004e/attachment.md","path":"references/pre-flight-schema-check.md","size":4308,"sha256":"8081d3e8dc2290ee8542c3800b64939c4f2c836d12bad0e0d78ea91466ceb8ba","contentType":"text/markdown; charset=utf-8"},{"id":"fed97ae7-21db-55b2-ac5b-0a61fec72df3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/fed97ae7-21db-55b2-ac5b-0a61fec72df3/attachment.md","path":"references/quality-mode.md","size":2506,"sha256":"af705277d4b26e7b01dfa5e3407d38eb42d2761b5f39e102181138c65b108966","contentType":"text/markdown; charset=utf-8"},{"id":"039d490d-5cdf-5f30-ae11-584bb97de961","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/039d490d-5cdf-5f30-ae11-584bb97de961/attachment.md","path":"references/scout-mode.md","size":4037,"sha256":"e5b136aaa37baf9b78427fc6ab6f1222332ef29edf17d01909d4cffd7ed3b2d6","contentType":"text/markdown; charset=utf-8"},{"id":"6196a462-06d2-59f7-9cb0-df0560d60cce","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6196a462-06d2-59f7-9cb0-df0560d60cce/attachment.md","path":"references/snapshot-pattern-for-long-cycle-gates.md","size":7096,"sha256":"4389f42d175a3b8cc01ede21bd117e23861d282a25a4ab3200d1a5aa52cbd3cb","contentType":"text/markdown; charset=utf-8"},{"id":"82a1536e-7cf6-5fdf-9a17-4e12581110b5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/82a1536e-7cf6-5fdf-9a17-4e12581110b5/attachment.md","path":"references/teardown.md","size":3353,"sha256":"1bd3a293cacd488f5ca3e781f2dac05b65813dc8ac4aa89ffa8a4865d4259f72","contentType":"text/markdown; charset=utf-8"},{"id":"1773b963-f57a-5311-9522-1880e5f9fe55","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1773b963-f57a-5311-9522-1880e5f9fe55/attachment.md","path":"references/work-selection-ladder.md","size":10271,"sha256":"c1853163e0bff1a7dc8bc79ff5507660028a4e16c68c5e90805570b81fc8e708","contentType":"text/markdown; charset=utf-8"},{"id":"59d3eb52-c3cd-59a8-887d-dee772fa8207","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/59d3eb52-c3cd-59a8-887d-dee772fa8207/attachment.sh","path":"scripts/duplicate-work-guard.sh","size":2753,"sha256":"9381324103de90f8b99ae1d921587171df1a65695a9baf2f6c456a677111086d","contentType":"application/x-sh; charset=utf-8"},{"id":"a1651245-bbb9-55ba-8d91-0b83f7da4abf","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a1651245-bbb9-55ba-8d91-0b83f7da4abf/attachment.sh","path":"scripts/validate.sh","size":3705,"sha256":"0472feb724f73a14b3da5cb06c086c6a4a28a33ac880e13e624abd61414dafc7","contentType":"application/x-sh; charset=utf-8"},{"id":"61cbfad9-1213-5f9f-acff-1b42d04bd10b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/61cbfad9-1213-5f9f-acff-1b42d04bd10b/attachment.md","path":"templates/cron-loop-mode.md","size":2621,"sha256":"a56e192e2b961286a108941219140f42afd5f04bb659e826e575f258fa96fd22","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"b9e8adc25a94375648b02c3b04947d4f8e0ddd0cf0fcf5945d61f472e0482982","attachment_count":30,"text_attachments":29,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":1,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/evolve/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"context":{"intent":{"mode":"task"},"window":"fork","sections":{"exclude":["HISTORY"]},"intel_scope":"full"},"version":"v1","category":"software-engineering","consumes":["rpi","goals","post-mortem","compile"],"metadata":{"tier":"execution","triggers":["evolve","improve everything","autonomous improvement","run until done","postmortem and continue","analyze repo and keep going"],"dependencies":["rpi","post-mortem","compile"]},"produces":["git-changes","goals-fitness-delta"],"practices":["lean-startup","dora-metrics","agile-manifesto"],"import_tag":"clean-skills-v1","context_rel":[{"kind":"customer-of","with":"rpi"}],"description":"Run autonomous improvement loops.","hexagonal_role":"supporting","user-invocable":true,"output_contract":"code changes, GOALS.md fitness deltas","skill_api_version":1}},"renderedAt":1782979394554}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.