## Summary
- Analyzes 7 specific PMF blockers with evidence from the repo's own
artifacts (PRODUCT.md Δ=+0.0000, 9-branch quickstart, 73-skill flat
catalog, jargon-heavy README)
- Produces a 3-wave execution plan ranked by leverage: prove lift (P0),
shrink time-to-aha (P0), narrow ICP (P1), reduce surface area (P1),
deliver compounding payoff, simplify vocabulary, expand distribution
- Companion to issue #556 which tracks the full breakdown
## Test plan
- [ ] Plan file renders correctly in GitHub markdown
- [ ] No CI regressions (doc-only addition to `docs/plans/`)
https://claude.ai/code/session_011cygz2T9XnQzK7TmS9JxHH
---
_Generated by [Claude
Code](https://claude.ai/code/session_011cygz2T9XnQzK7TmS9JxHH)_
Co-authored-by: Claude <noreply@anthropic.com>
## Why
/evolve self-stops in operator-driven cron sessions because its defaults
assume agent-as-operator. `--mode=loop` flips the contract: operator
owns stop signals; CLI mechanically refuses self-written STOPs.
## What changed
| Surface | Change |
|---|---|
| `cli/cmd/ao/evolve.go` | New `--mode string` flag (burst\|loop,
default burst) + `validateEvolveMode` helper called from `runEvolve` |
| `cli/cmd/ao/evolve_write_stop_marker.go` | New subcommand; refuses
with exit 1 under `--mode=loop`, writes `.agents/evolve/<MARKER>` under
burst |
| `cli/cmd/ao/evolve_test.go` | L1: `--mode=invalid` rejected; mode flag
registered with burst default |
| `cli/cmd/ao/evolve_write_stop_marker_test.go` | L2 table tests: burst
writes (DORMANT body assertion), loop refuses {dormant,stop,kill}, no
file written under refusal |
| `skills/evolve/SKILL.md` | Mode-aware HTML comments in Steps 1/3/7 +
Flag table row (only edited Steps 1/3/7 + Flag table; verified via grep
`^### Step`) |
| `skills/evolve/references/loop-mode.md` | New reference doc with
invariants + CLI primitives |
| `docs/plans/2026-05-21-evolve-loop-epic-design.md` | Epic design memo
(consumed by all 6 sub-beads of soc-g2qd) |
| `cli/docs/COMMANDS.md` | Regenerated via
`scripts/generate-cli-reference.sh` |
|
`skills-codex/{.agentops-manifest.json,evolve/.agentops-generated.json}`
| Post-edit hook source-hash refresh; `check-codex-parity-drift.sh` PASS
|
## How tested
- `go test -count=1 ./cmd/ao/` — 10175 pass, 1 skip (full suite green
after CLI-docs regen; pre-regen `TestCobraConformance` correctly flagged
the doc drift)
- `go build ./... && go vet ./...` — green
- `grep '^### Step' skills/evolve/SKILL.md` confirms only Steps 1/3/7
edited (12 Step markers preserved at same positions)
- `bash scripts/check-codex-parity-drift.sh` — PASS
- Table tests assert exact marker filename (DORMANT/STOP/KILL) + body
content for burst; for loop they assert error substring AND that no
marker file was created.
## §A7 fallback decision
**Chose in-file HTML comments** (not two-file split). Each Step comment
is one line; no conditional sections needed. Two-file split would have
ballooned the surface for a single-line contract reminder. CLI
mechanical enforcement (`write-stop-marker` refusal) is the real
invariant; SKILL.md comments only document intent for human readers.
See: docs/plans/2026-05-21-evolve-loop-epic-design.md §A1 + §A7
## TODOs the worker leaves for the epic
- Wire `cli/internal/evolve.preferences.Load()` into
`detectEvolveWriteStopMarkerMode` once soc-6svt lands (currently
flag-only).
- `ao evolve operator-stop` (Wave 2) — separate code path explicit
operator override.
- `ao evolve blocked` (Wave 2) — typed blocked event instead of STOP.
Closes-scenario: soc-hwax#mode-loop-flag
Bounded-context: BC5-Runtime
Evidence: cli/cmd/ao/evolve_write_stop_marker.go
Plan to migrate the skill catalog toward CDLC first-principles skill
definitions without a big-bang rewrite. Wraps the live SKILL.md runtime
with an advisory V2 SkillDefinition contract; skill-builder and
skill-auditor become the factory pair. Follows the dated-plan shape from
docs/plans/2026-05-11-evolution-roadmap.md.
Plan document only; no implementation artifacts introduced.
Rescope PRACTICE.md into PRACTICE-REGISTRY.md: it now owns only the
practice-slug lineage registry, not product positioning or CDLC doctrine.
Update all references (schema, validate-practice-citations.sh, bats test,
architecture-terms.md, documentation-index.md, aggregate.go comment).
Introduce the Context Density Rule as a canonical domain concept: every
high-value context token carries intent, boundary, evidence, decision,
constraint, or next action. New domain entry context-density-rule.md (+
codex mirror). Thread the BDD/Gherkin + DDD + Hexagonal + TDD narrow waist
through cdlc.md, README.md, PRODUCT.md, GOALS.md, and the rpi/domain/
post-mortem skills. Sync codex artifacts.
Fourth soc-5yuy child closed. Drift #1 (Gate/Check/Validation/
Validator) resolved as audit-only — catalog overstated drift size.
Audit findings:
- Zero scripts/check-*.sh headers use the noun "Validator".
- 38 of ~90 scripts already use "Gate" in their headers; rest
don't repeat the noun.
- cli/internal/ratchet.Validator is the only Go Validator type
(legitimate ratchet-specific concept; not a check-script
validator). KEEP.
- "validate"/"validates" as English verbs in header descriptions
is fine — not a noun-confusion drift.
The "90 scripts inconsistent" claim in the catalog was wrong. The
codebase organically drifted toward "Gate" already. No renames
needed.
Changes:
- ubiquitous-language.md drift #1 resolution block rewritten to
document the actual state.
- ubiquitous-language.md drift-baseline table row #1 marked
AUDITED.
- ubiquitous-language.md cycle log entry for cycle 130.
- docs/plans/2026-05-12-rescope-evolve-and-architecture.md .1 row
marked AUDITED.
This is doc-only. No code changes. soc-5yuy.1 bd closed.
soc-5yuy progress: 4 of 5 children closed. Three via audit-only
(.1 cycle 130, .2 cycle 129, .4 cycle 128) and one via rename
(.3 cycle 126). Only .5 (Session → TranscriptSession, 97 refs)
remains as the actual code-rename work.
Pattern crystallizes: when a drift catalog comes from one-shot
research mode rather than incremental observation, the actual
codebase is often more disciplined than the catalog implied.
3 of 5 cycle-128/129/130 audits resolved without renames. The
audit-first discipline (cycle 125 / 127 learnings) is now
demonstrably better than execute-first for borderline drifts.
Cycle 130 / soc-5yuy.1 audit-only-resolution mode.
Third soc-5yuy child closed via audit-only. Drift #2 (Cycle/Loop/
Iteration/Run consistency) resolved without renames — the catalog
over-flagged this.
Audit findings:
- ~150 RPIRun* identifiers + 132 Iteration* identifiers enumerated.
- Most usage falls into one of 5 categories that are NOT drift:
1. Serialized-contract enums (JobTypeRPIRun) — renaming breaks
on-disk JSON job spec format and cross-process compatibility.
2. Filesystem path constants (RPIRunRegistryDir) — renaming
breaks registry layout.
3. Legitimate Runner/Executor naming (RPIRunner, RPIRunExecutor)
— these are role types, not Run-instance synonyms.
4. Substring coincidence — RPIRuntimeCommand and RPIRuntimeMode
contain "Run" as part of "Runtime". Not a Run concept.
5. Scoped Dream-internal counters (overnight.IterationSummary,
dream_subcycle.MaxIterations) — Dream's convergence-loop term,
scoped to Dream surface only.
- rpi.RPIRun (the artifact struct) IS the canonical name for an
RPI execution; analogous to GitHub Actions' "CI Run". Keep.
Conclusion: the codebase's Run/Iteration usage is mostly
semantically correct. Drift #2 was a contract-side mistake. The
audit IS the resolution.
Changes:
- ubiquitous-language.md drift #2 resolution block: REWRITTEN to
document the 5 categories of correct-but-look-like-drift usage,
with explicit "KEEP" annotations.
- ubiquitous-language.md drift-baseline table row #2: AUDITED.
- ubiquitous-language.md cycle log entry for cycle 129.
- docs/plans/2026-05-12-rescope-evolve-and-architecture.md .2 row
marked AUDITED.
This is doc-only. No code changes. soc-5yuy.2 bd closed with
reason linking to this commit.
soc-5yuy progress: 3 of 5 children closed (.3 cycle 126 via
rename, .4 cycle 128 via audit, .2 cycle 129 via audit). Two
remaining: .1 (Gate/Validator) + .5 (Session/TranscriptSession) —
both still rename-required but with substring-overreach warnings
baked in from cycle 127.
Pattern note: the same cycle-126 substring-audit applied to a
catalog flag and revealed the catalog was wrong, not that the code
needed renaming. The audit-first discipline (cycles 125, 128, 129)
is now demonstrably better than execute-first for borderline
drifts.
Cycle 129 / soc-5yuy.2 audit-only-resolution mode.
Second soc-5yuy child closed. Drift #4 (Skill/Pattern/Practice/
Primitive cross-reference consistency) resolved as audit-only — no
code renames needed.
Audit findings:
- Skill is consistently "invokable harness module" across all SKILL.md
files. No drift.
- Pattern is consistently "reusable promoted knowledge". No drift.
- Practice is consistently "citation annotation in primitive
frontmatter". No drift.
- Primitive IS overloaded — three distinct concepts share the word:
1. BC1 Corpus Primitive (the annotated unit; canonical sense for
the cross-cutting `practices: [slug]` annotation)
2. Domain Primitive (skills/domain/ — 6 structural primitives:
Entry, Index, Citation, Primitive, Slice, Anti-Pattern)
3. Runtime primitive (skills/converter/ + skills/standards/ —
atomic tool/feature exposed by a runtime, e.g., a Claude-only
hook event)
The 3 senses do NOT conflict because each is scoped to its own
surface (BC1 cross-cutting vs the domain skill only vs converter
+ standards). No renames are needed — the audit IS the resolution.
Changes:
- ubiquitous-language.md drift #4 section: added a sub-overload
table enumerating all 3 `primitive` senses with their scope
+ distinguishing context.
- ubiquitous-language.md drift-baseline table row #4: marked
AUDITED cycle 128.
- ubiquitous-language.md cycle log entry for cycle 128.
- docs/plans/2026-05-12-rescope-evolve-and-architecture.md:
marked .4 done.
This is doc-only. No code changes. soc-5yuy.4 bd closed with
reason linking to this commit.
soc-5yuy progress: 2 of 5 children closed (.3 cycle 126 via
rename, .4 cycle 128 via audit). Three rename-required children
(.1, .2, .5) still open with the cycle-127 substring-overreach
warning baked into their descriptions.
Cycle-shape note: "audit-only" is a legitimate cycle-sized
deliverable when the catalog turns out to NOT reflect real
drift. Cycle 125 also did contract-refinement after audit
(drift #5). Cycle 128 takes the simpler path — surveyed and
documented the overload as scoped, no follow-up code work
needed.
Cycle 128 / soc-5yuy.4 audit-only-resolution mode.
First soc-5yuy child to close. Mechanical rename of `daemon.QueueClaim`
to `daemon.QueueLease` across 108 Go references in 28 files —
cli/internal/daemon (76 refs), cli/cmd/ao (22), cli/internal/rpi
(7), cli/internal/llmwiki (3). Resolves drift #3 from
docs/contracts/ubiquitous-language.md.
Why QueueLease, not QueueClaim:
- `Claim` is the BC2 noun for what the project says publicly
(e.g., AOP-CLAIM-*, factory-claim-ledger.json).
- The daemon's QueueClaim was semantically a LEASE on a job slot
with a token + expiration, not a public assertion. The struct
has fields `ClaimToken`, `LeaseEpoch`, `LeaseExpiresAt` — three
out of four already named "Lease".
- The name collision tax was real: a fresh contributor reading
factory-claim-ledger could not tell whether daemon.QueueClaim
was the same concept.
Audit-then-execute (cycle-125 pattern):
1. Pre-rename audit: counted refs by package (76+22+7+3+5+0).
2. Checked for split-concept surprise (cycle-125 lesson): all 111
baseline refs are the same concept (no Session-like split).
3. Checked for serialization keys: no `"queue_claim"` JSON tags;
no string literals containing "QueueClaim".
4. Then bulk sed across 4 Go packages; build clean; vet clean;
tests pass (daemon 11s, rpi 4s, llmwiki 0.1s, cmd/ao 53s).
Docs updated:
- docs/contracts/ubiquitous-language.md drift #3 resolution
block, schedule table row, baseline table row, and cycle log
entry — all reflect "DONE cycle 126" + "0 refs (from 111)".
- docs/plans/2026-05-12-rescope-evolve-and-architecture.md soc-5yuy
.3 row marked DONE.
soc-5yuy.3 bd closed with reason linking to this commit.
Net delta: 113 insertions, 112 deletions across 28 files. Zero
QueueClaim refs remain in tracked code/docs (testdata excluded —
those are immutable transcript fixtures).
Cycle 126 / soc-5yuy.3 audit-then-execute mode (first real rename
following the audit-then-execute discipline from cycle 125).
Cycle 45 commit cc21ec2d landed 6 patches to skills/evolve/SKILL.md
sourced from .agents/learnings/2026-05-11-evolve-skill-friction-from-
13-cycle-session.md — a learning file that lived only in operator-
local .agents/ runtime state. docs/plans/2026-05-11-evolution-roadmap.md
referenced that path, but the file is gitignored and missing from
this worktree (and from every checkout that isn't the original
authoring session). Future value audits depending on the rationale
couldn't find it.
Per soc-w6vh.5 acceptance: export to durable surface
(docs/learnings/) and update referrers. Content reconstructed from
cycle 45's commit body, cycle 51's hypotheses.jsonl (verdicts on the
6 patches as of cycle 51), and the cycle-45-49 retro post-mortem.
The exported version goes beyond the original: it includes the
hypothesis verdicts from cycle 51 (H45.2 + H45.3 FALSIFIED; H45.6
VERIFIED) so future readers see not just the original rationale but
the durability of each patch.
Matches the cycle-46/47 PG4 evidence-file shape (docs/releases/
v2.39.0-claims/*.md) — durable export of local-only rationale to a
public, version-controlled surface.
Code-driven fitness: durable learning evidence files 0 → 1;
references in docs/plans/ pointing at local-only .agents/ paths: 2 → 0.
Cycle 61 / bd-driven mode. Bead soc-w6vh.5 acceptance partially met
(export done + references updated). Second clause — validation check
catches docs references to absent .agents/learnings files — deferred
to a follow-up bead.
Tracks the rescope plan that reorganizes evolve-improvement work under
5 bounded-context epics + 1 cross-cutting epic, sourced from the
operator's exemplar commit shape (1b9d139c → f62295f7).
Companion artifacts (gitignored research / post-mortems, local-only):
- .agents/research/2026-05-12-repo-direction-map.md
- .agents/research/2026-05-12-bounded-contexts-and-ports.md
- .agents/post-mortems/2026-05-12-evolve-session-improvement-postmortem.md
BD state filed in same cycle (durable in dolt, not in this commit):
- 6 NEW epics: soc-2c1p (BC1), soc-wxh5 (BC2), soc-y5vh (BC3),
soc-2klg (BC4), soc-zd7c (BC5), soc-5yuy (cross-cutting)
- CLOSED soc-z8rt + 8 children (catch-all retired; children migrated
to BC homes with traceable close reasons)
Matches the docs/plans/2026-05-11-evolution-roadmap.md sibling
pattern: plan tracked alongside bd state for operator visibility and
durable rationale. The plan IS the structural drift-block — reader
verifies bd state by listing BC labels and matching to plan sections.
Code-driven fitness: open evolve-improvement parent epics 1 (soc-z8rt
catch-all) → 6 (5 BC-aligned + 1 cross-cutting); orphan z8rt children
8 → 0 (all migrated or closed).
Cycle 53 / wave 1.2 of the 2026-05-12 rescope.
Three-layer protocol so each /evolve day improves the next:
1. Per-cycle micro-capture: 1 line to .agents/evolve/daily-learning-log-YYYY-MM-DD.md
2. Every-5th-productive reflect: pattern annotation inline in cycle-history note;
3+-occurrence frictions matching prior days auto-file an evolve-improvement bead
3. End-of-day consolidate via scripts/evolve-capture-daily-learning.sh:
- Reads daily log + cycle-history (filtered to today)
- Writes .agents/learnings/YYYY-MM-DD-evolve-loop-learnings.md with counts,
ledger, frictions, recurring patterns
- Auto-files LC-followup beads (label: evolution-roadmap,evolve-improvement)
for any FRICTION tag that recurred on 2+ days
- Idempotent (re-run overwrites today's consolidated file; daily log untouched)
- Supports --dry-run
Seeder updates:
- LC epic + LC1 leaf bead added (closes loop on the loop's own behavior)
- Pagination bug fixed: bd list --status=open --json (default 50 cap) caused
duplicate beads on re-run when total open > 50. Changed all idempotency
checks to bd list --status=open --limit 0 --json. Re-run is now safely
idempotent — verified with dry-run reporting 41 skips, 0 would-create.
- 13 duplicate beads from the prior re-run already closed manually with
reason="duplicate from seeder idempotency bug"; their close is the
evidence the bug existed and is now fixed.
Road-map plan extended with LC section + table entry. 41 evolution-roadmap
labeled beads now open (39 original + LC epic + LC1).
Local-only artifacts (in .agents/, gitignored by policy):
- .agents/evolve/all-day-starter-prompt.md (revised with mandatory steps 9-10
+ end-of-day consolidator invocation)
- .agents/evolve/daily-learning-log.template.md (tag taxonomy + examples)
- .agents/evolve/daily-learning-log-2026-05-11.md (seeded for smoke test)
docs/plans/2026-05-11-evolution-roadmap.md is the durable plan: 8 epics, 39 beads,
explicit drain order. Closes the structural friction the 13-cycle 2026-05-11 /evolve
session surfaced — the loop was picking from bd ready / next-work.jsonl but the
LARGEST work source in this repo is the gap between aspirational docs
(PRODUCT.md / GOALS.md / PRACTICE.md / docs/contracts/ / docs/code-map/) and what
the code actually does. The road map enumerates that gap.
Epics filed (12 parents + 27 leaves = 39 beads, all labeled evolution-roadmap):
- E1 soc-ymph: Close 11 GOALS.md directive gaps (D1-D11)
- E2 soc-45sg: Promote 5 Roadmap gates to CI-blocking (G1-G5)
- E3 soc-dec2: Close 8 PRODUCT.md Known Product Gaps (PG1-PG11, some merged)
- E4 soc-3q1l: Polish 4 product layers (L1-L4)
- E5 soc-m47k: Three-gap contract super-gates (TG1-TG3)
- A1 soc-waod: AOP-CLAIM evidence map audit (83 markers → N follow-ups)
- A2 soc-nzji: Contract enforcement matrix audit (38 contracts → N follow-ups)
- A3 soc-cd32: Code-map drift report (2 maps → N follow-ups)
scripts/seed-evolution-roadmap-beads.sh is idempotent (--dry-run preview supported)
and safe to re-run; uses bd list title-match for idempotency.
Drain priority order documented in the plan; the all-day starter prompt
(.agents/evolve/all-day-starter-prompt.md, local only since .agents/ is gitignored)
references it. First-cycle target: soc-ymph.7 (D7: Codex parity drift to zero).
docs/INDEX.md (contract catalog) and docs/index.md (MkDocs landing) shared the
same case-folded name on case-insensitive filesystems, leaving the working tree
in a phantom-modified state and breaking contract-compatibility-gate when the
script read whichever file the OS resolved at run time.
Resolves TASK-1 + TASK-2 of .agents/plans/2026-04-26-resolve-docs-index-case-collision.md:
- Move catalog content from HEAD:docs/INDEX.md into docs/documentation-index.md
- Repoint contract validators (scripts/check-contract-compatibility.sh,
scripts/contract-orphans-allowlist.txt) and their tests at the new path
- Update navigation references across README.md, AGENTS.md, CLAUDE.md, and the
docs/ tree (newcomer-guide, CONTRIBUTING, CI-CD, plans/, positioning/,
templates/, contract examples)
- Replace stale docs/README.md mentions in CLAUDE.md / AGENTS.md / repo-execution
profile example with docs/index.md (the actual MkDocs landing)
Verification:
- bash scripts/check-contract-compatibility.sh -> 0 failures, 24 contracts catalogued
- bash tests/scripts/test-contract-compatibility-gate.sh -> 7/7 PASS (verified pre-rebase)
- bash tests/skills/test-repo-native-orchestration.sh -> 28/28 PASS (verified pre-rebase)
- git ls-files | awk casefold-dup scan -> empty
TASK-3 (casefold-collision guard script) and TASK-4 (worktree disposition) from
the plan remain to be done in a follow-up.
Rename the athena skill to compile — a descriptive name that communicates
what it actually does. Extend with Karpathy's LLM Knowledge Bases architecture:
- New compile phase: LLM reads raw .agents/ artifacts and produces interlinked
markdown wiki at .agents/compiled/ with index.md, log.md, backlinks
- New lint phase: detects contradictions, orphan pages, stale claims, coverage gaps
- Pluggable compute backend via AGENTOPS_COMPILE_RUNTIME (ollama|claude|openai)
- Hash-based incremental compilation (only recompile changed sources)
- compile.sh engine with security fixes (no shell injection, path traversal guard)
- Full rename across 93 files: skills, docs, CLI, tests, hooks, scripts, codex
Existing Mine → Grow → Defrag cycle preserved as phases within the larger
compile workflow. No vector DB — compiled wiki IS the retrieval layer.
Bo