git:20260930.f27afd8 to git:20261007.70cb0c3

- > **Read this file first if you are an AI agent (Claude Code, Codex CLI, Antigravity/agy, Ollama, Gemini CLI, or generic) working in this repository.** It is the source-of-truth for cross-CLI invariants. CLI-specific runtime details live in companion files: [CLAUDE.md](CLAUDE.md), [GEMINI.md](GEMINI.md). All three reference back to this document.

- > **Operating policy (canonical):** [docs/operations/operating-policy.md](docs/operations/operating-policy.md) carries the environment-independent process rules — pipeline-integrity handling (console-first, maximum reasoning), queue/routing authority, engineering standards, failure-handling contract, release policy — each with the incident evidence behind it. A clean environment inherits the full policy from the repo alone; session memory is only an advisory mirror.

- A self-evolving development pipeline that orchestrates specialized phase agents (Intent, Scout, Triage, TDD, Builder, Auditor, plus retro/memo) through a fixed spine per cycle (Intent → Scout → Triage → [TDD] → Build → Audit → Ship → Learn). Tier-1 kernel hooks enforce phase ordering, role-scoped write paths, atomic ship semantics, ledger SHA verification, and v8.37+ tamper-evident hash-chained recording.

- > **Runtime note (Go-only):** The Go binary (`go/bin/evolve`) is the sole runtime entrypoint. The bash `legacy/scripts/` tree were removed in the Go-only consolidation — there is no bash fallback. Every operation below is a native `evolve <subcommand>` or a function in `go/internal/...`. For the history of the bash→Go port, see [docs/migration-from-bash.md](docs/migration-from-bash.md).

- These rules apply regardless of which CLI you are running under. They are STRUCTURAL — enforced by kernel hooks, not by prompt instructions.

- Phases run Scout → Builder → Auditor → Ship/Record in that exact order. Phase ORDER is enforced by the Go orchestrator state machine (`go/internal/core`); the phase-gate kernel hook (`evolve guard phase`, rewired per ADR-0075 onto the `Agent|Task` matcher) denies in-process subagent dispatch while a cycle is active. The emergency operator override is the explicit `evolve guard phase --bypass` CLI flag; use is logged loudly and considered a CRITICAL violation.

- ### 2. Subagents are spawned through the native bridge, never via in-process tool calls

- Every phase agent is spawned by the native runner (`evolve subagent run <agent> <cycle> <workspace>`, or the in-process `go/internal/bridge` launcher driven by `evolve loop` / `evolve cycle run`). This is enforced by the kernel hook. The in-process `Agent` (Claude Code) / `activate_skill` (Gemini) / equivalent (Codex) is **denied during a cycle**. Reason: in-process subagents bypass profile-scoped permissions and the tamper-evident ledger.

- The ship-gate kernel hook (`evolve guard ship`) denies bare git commit/push/gh release create. The only canonical entry point is the native `evolve ship`. It enforces audit verification, cycle binding (HEAD + tree_state_sha match), and version-aware self-SHA pinning. Operator escape: `--class manual` (interactive) or the explicit `evolve guard ship --bypass` emergency flag.

- Interactive `--class manual` commits additionally require a fresh **commit-gate review attestation** (v13.0.0+): `.commit-gate/attestation.json` whose `tree_state_sha` matches the staged tree. Produce it with `/commit` (code-simplifier + code-reviewer + language reviewer + lint + targeted tests). `evolve ship --bypass-commit-gate` skips the check — routine use is a CLAUDE.md violation, identical in spirit to the ship-guard emergency bypass.

- Each cycle gets a per-cycle git worktree (provisioned natively by the orchestrator in `go/internal/core`, recorded in `cycle-state.json:active_worktree`). Builder's profile (`.evolve/profiles/builder.json`) restricts Edit/Write to the worktree path. The role-gate kernel hook (`evolve guard role`) denies edits outside that boundary, including interpreter-execution Bash-redirect leaks.

- Auditor writes `audit-report.md`, and the ship gate is the binary `acs-verdict.json:red_count == 0` (EGPS v10.0.0+ — the scalar PASS/WARN/FAIL confidence level was removed). The verdict is computed from sandbox exit codes by the native audit phase (`go/internal/phases/audit` + `evolve acs suite`), never from a model's narrative. (Strict WARN→FAIL promotion is opt-in via `.evolve/policy.json` `workflow.strict_audit`; see [reference/env-vars](knowledge/reference/env-vars.md).)

- `.evolve/ledger.jsonl` records every subagent invocation with cycle binding, challenge token, artifact SHA, **prev_hash**, and **entry_seq**. Each new entry's prev_hash is the SHA256 of the previous entry's full JSON line. `.evolve/ledger.tip` records the latest entry's SHA atomically — truncation detection. Run `evolve ledger verify` (or `evolve guard chain`) to confirm history integrity. Modifying any historical entry breaks the chain at the next entry.

- Prior failures are recorded in `state.json:failedApproaches[]` with structured classifications (infrastructure-transient, code-audit-fail, code-audit-warn, etc.). The native failure-adapter (`go/internal/core`) returns deterministic decisions; the orchestrator follows them verbatim. Default mode is fluent (would-have-blocked rules emit awareness, not BLOCK). Strict mode (`.evolve/policy.json` → `workflow.strict_audit: true`) restores legacy block-on-recurring behavior.

- The auditor profile defaults to Opus, but the native diff-complexity check (`go/internal/subagent`, modeltier) auto-downgrades to Sonnet for trivial diffs (≤3 files, ≤100 lines, no security paths). Saves ~$1.89/cycle on routine cycles. Operator override: `MODEL_TIER_HINT=opus` forces Opus regardless.

- > **Knowledge Stewardship Rule (Day-One):** Every research finding, discovery, cycle learning, or tried-and-failed approach MUST be documented before the cycle ships. All documentation lives under `docs/`, never in code comments ([code-comments convention](docs/conventions/code-comments.md)) — research notes in `docs/research/` (the former `knowledge-base/research/` tree moved there 2026-08-05; see [docs/MOVED.md](docs/MOVED.md)). `knowledge-base/` is a runtime write surface only (`cycles/` dossiers), not documentation. **Never delete; always archive.** When superseding a doc, MOVE it to `docs/private/research/archived-YYYY-MM-DD/` with a one-line note in the replacement pointing to the archive. Failing to document is a HIGH-severity audit defect.

- Enforced by the doc-deletion guard (`evolve guard docdelete`, `go/internal/guards/docdelete.go`; PreToolUse kernel hook): blocks `rm`/`mv` that would remove committed content from `docs/**` or `knowledge-base/**` unless the destination lands under `docs/` (archive with `git mv` into `docs/private/research/archived-YYYY-MM-DD/`, so the archived copy stays staged; `knowledge-base/` is deliberately NOT a valid destination). The one exception: a Build may `git rm` the active cycle's own explanation document (`docs/explain/builds/cycle-<N>-<run>.md`) when it was never committed. Operator escape: set `workflow.allow_doc_delete=true` in `.evolve/policy.json` (logged; emergency only).

- > Every agent, phase and person writes code with no comments. Names, types, small functions and test names say what the code does; a design reason goes to the package's notes under `docs/architecture/packages/`. Only the comments a tool reads survive; [the code-comments convention](docs/conventions/code-comments.md) is the one list of them. When a comment is removed, the code must say what it said.

- The commit gate (`evolve commit-gate run`) refuses a commit that adds a comment. Loop lanes: the build handoff floor counts the comments a build adds (`comment_floor`); its rollout stage is kept in [the code-comments convention](docs/conventions/code-comments.md).

- Behavioral rules every agent must follow regardless of CLI. Where the kernel hooks above catch *structural* breaches, these catch *judgment* breaches. In bypass-permissions / autonomous mode, rule 4 ("stop and ask") is overridden — make the reasonable call and continue. All other rules apply unconditionally.

- 1. **Think before coding.** Do not assume or over-engineer. State assumptions explicitly. Push back when a requested approach is wrong — propose the alternative.

- 2. **Push for simplicity.** If a simpler approach exists, propose it. Three similar lines beat a premature abstraction. Don't design for hypothetical future requirements.

- 3. **No silent changes.** When instructions admit multiple interpretations or the codebase offers multiple patterns, surface both and pick one explicitly with a one-line reason. Never guess silently.

- 4. **Surface ambiguity.** If something is unclear or context is missing, stop and ask. (Overridden in bypass-permissions mode: make the reasonable call and continue — the user will redirect.)

- 5. **Reserve judgment tasks for AI.** Use LLM cycles for qualitative work — summarizing, categorizing, drafting, designing. Deterministic work (retries, error codes, state transitions, hashing) goes in the Go kernel. evolve-loop already enforces this: the phase gate, ship, and failure-adapter (`go/internal/core`, `go/internal/phases/ship`) are deterministic Go; Scout/Builder/Auditor are LLM.

- 6. **Strict token budgeting.** Stay within your per-task and per-session token budget. When approaching it, summarize state to a markdown file and stop the phase rather than letting it auto-resume. (This is about your own working discipline, not a runtime cap: the product's token-budget *cost* gates were removed — the dollar-cost calculation was unreliable across LLM models — so the former dollar-cost budget flags (and `--budget-usd N`) are gone and cost is display-only telemetry.) See [docs/architecture/checkpoint-resume.md](docs/architecture/checkpoint-resume.md).

- 7. **Address conflicting patterns.** If two patterns conflict in scope (e.g., bash 3.2 vs bash 4 features; `skills/` canonical vs `.agents/skills/` canonical), do not mix them. Pick one, document the reason in the commit body, and tag the other for cleanup.

- 8. **Read first.** Before importing from or calling into a module, `Read` it and list its real exports. Do not invent function names from context. Builder agents shipping code against imagined APIs is the recurring failure mode this rule prevents.

- 9. **Write meaningful tests.** Tests verify *intent*, not surface behavior. EGPS predicates that pass with `echo PASS; exit 0` or `grep -q presence` are rejected by the eval-quality check (`evolve eval quality-check`, EGPS v10.0+). Same principle applies to Go unit tests: a passing test that doesn't probe the behavior change is a no-op.

- 10. **Use checkpoints.** For multi-phase work, summarize what was done and what remains after every phase. evolve-loop encodes this in the native cycle-state checkpoint + `phase report` artifacts. If you cannot clearly describe current status in 3 bullets, stop — you have lost the plot.

- 11. **Follow existing conventions.** Match the codebase even if you disagree. Specifics: Go is the runtime (`go/internal/...`); the few remaining shell helpers (test fixtures, the commit-gate runner) target bash 3.2 (no `declare -A`, no `mapfile`, no `${var^^}`) and use `printf > tmp && mv` for atomic writes; commits go through `evolve ship`; kernel guards are `evolve guard <name>` and split read roots (`PLUGIN_ROOT`) from write roots (`PROJECT_ROOT`).

- 12. **Fail loudly.** Do not silently skip steps, swallow errors, or report success when work was incomplete. A "migration complete" claim that secretly skipped 3 files is the failure mode this rule prevents. Format for completion claims: `cd go && go test ./internal/<pkg>/... — N/N PASS, no regression`.

- This file covers the universal contract. CLI-specific runtime details live in companion files:

- - **Claude Code**: see [CLAUDE.md](CLAUDE.md). Tier-1 production. Skills at `skills/<name>/SKILL.md` are the only invocation/slash-command surface (per ADR-0040; they carry `argument-hint`), with the plugin manifest at `.claude-plugin/plugin.json` declaring only `agents` and `skills` (no `commands[]` array). Kernel hooks fire as PreToolUse hooks per `.claude/settings.json`.

- - **Codex CLI**: skills auto-discovered at `.agents/skills/<name>/SKILL.md` (this directory exists as symlinks to `skills/<name>/`). Codex reads this AGENTS.md as its canonical config. Driven by the native codex bridge driver (`go/internal/bridge/driver_codex*.go`): NATIVE when `codex` is on PATH and supports non-interactive prompts, HYBRID (delegates to `claude`) otherwise, DEGRADED as a last resort (pipeline still completes; reduced isolation). Capability tier visible via `evolve bridge probe`.

- - **Gemini CLI**: skills auto-discovered at `.agents/skills/<name>/SKILL.md`. See [GEMINI.md](GEMINI.md) for Gemini-specific notes. `gemini` is a distinct CLI identity with its own adapter metadata (`adapters/gemini.capabilities.json`); there is **no** dedicated `driver_gemini*.go` bridge driver. A Gemini *model* is also reachable natively through the Antigravity (agy) driver (`go/internal/bridge/driver_agy*.go`, documented in-code as "Gemini-backed"), but `gemini` and `agy`/`antigravity` are separate CLI identities — only `antigravity → agy` is name-resolved (see the Antigravity bullet below).

- - **Antigravity CLI (agy)**: skills auto-discovered at `.agents/skills/<name>/SKILL.md`. Driven by the native agy bridge driver (`go/internal/bridge/driver_agy*.go`): NATIVE mode (`agy -p`) when the agy binary is on PATH; HYBRID when claude on PATH; DEGRADED otherwise. The cross-name resolver maps `antigravity → agy`. cost_blind:true in NATIVE mode (deferred billing tap). See [reference/agy-runtime.md](skills/loop/reference/agy-runtime.md). Capability tier: `evolve bridge probe`.

- - **Ollama (local models)**: driven by the native ollama tmux-REPL bridge driver (`go/internal/bridge/driver_ollamatmux.go`), which launches `ollama run <model>` in a tmux pane and reuses the shared REPL completion-detection machinery. A routing target for local models — no skill/plugin surface of its own. Research record: [docs/research/ollama-control-surface-2026.md](docs/research/ollama-control-surface-2026.md).

- - **Generic / unsupported CLI**: see [skills/loop/reference/generic-runtime.md](skills/loop/reference/generic-runtime.md). Tool name translation tables at `skills/loop/reference/<platform>-tools.md`.

- If you are an AI agent activating in this repository:

- 3. **Read this AGENTS.md** in full — the cross-CLI invariants apply to you.

- Skill files use YAML frontmatter (`name`, `description`) followed by markdown instructions. Skills include subdirectories (`scripts/`, `references/`, `assets/`) for resources used during execution.

- The pipeline's safety properties stack into three tiers:

- | Tier 2 | OS isolation (sandbox-exec on macOS, bwrap on Linux) | Compromised builder writing outside its sandbox |

- Tier 1 is non-negotiable and runs in privileged shell context. Tier 2 adapts to the environment. Tier 3 is operator-controlled per-run.

- These constraints apply to ALL agents in the pipeline to ensure cost efficiency and structural integrity.

- To prevent context saturation from accumulated tool results:

- - **Summarize Reads**: After each `Read`, summarize the content in 2-3 lines; reference the summary in subsequent turns.

- - **Discard Large Blobs**: After each `Bash` with large output, extract key lines and discard the full output.

- - **Trajectory Compression**: When reading files >3000 tokens, extract 3–5 key facts and discard the full content from working context immediately.

- - **No Speculative Loading**: Use `Glob`+`Grep` to locate points of interest before `Read`.

- - **No Self-Reversion**: Do not revert your own changes unless explicitly instructed or if they cause an immediate environment failure.

- - **No Pipeline Bypass**: Never attempt to skip a phase or ignore a kernel-gate failure.

- - **No Post-Report Turns**: Once the phase report (scout/build/audit/orchestrator) is written, STOP. Turn accumulation after report completion is a critical cost driver.

- When a cycle converts an `EVOLVE_*` env flag into a typed input parameter, the conversion is "done" ONLY when it meets the **[Flag → Parameter Conversion Standard](docs/research/flag-parameter-conversion-standard.md)**: (1) the resolution package is environment-agnostic (no `os.Getenv`/`LookupEnv`/`Environ` — enforced by `paramPackages` in `go/internal/policy/param_env_agnostic_test.go`, which the conversion MUST enroll the package in); (2) it ships an env-free, black-box, public-API test suite covering the full field × edge-case matrix; (3) every exported parameter API at 100% coverage with `apicover -enforce` exit 0. Tests drive behavior ONLY through input parameters — never `t.Setenv`. Reference template: `internal/quotareset` + `internal/policy` config accessors.

- Every coding change takes the laziest solution that actually works — the ladder (YAGNI → stdlib → native/`policy.json` config → already-present dependency → one line → minimum), no unrequested abstraction, deletion over addition, shortest working diff; mark a deliberate shortcut with a `minimal:` comment naming the ceiling + upgrade path. The cut is in scope, NEVER in safety: input validation, error handling, security, accessibility, explicit requests, and the pipeline gates (RED test / safety invariants / eval+contract gates / ship floor) are never simplified away. Full ruleset: **[skills/minimalism/SKILL.md](skills/minimalism/SKILL.md)** (adapted from ponytail, MIT).

- Code explains itself. A comment states only what the code cannot: a directive, a one-line contract on an export, or the *why* behind a non-obvious invariant. No history — cycle numbers, incidents, F-ids, dates — ever goes in code; it goes to `docs/`. Full rule: **[docs/conventions/code-comments.md](docs/conventions/code-comments.md)**.