evolve

The machine version of chaos-injection. snappy-os runs mutations on itself indefinitely, reverting what regresses and keeping what compounds. No human in the loop - the revert primitive IS the safety. No stop condition; "999 and then another 999" is the doctrine.

Steps

1. Scope - no side effects

Read state/log/evolve.ndjson to see what stuck and what didn't. This is the audit surface.

2. Gate

Working tree MUST be clean before starting. Any uncommitted change is a failure mode - the harness can't distinguish a regression from operator noise. The harness aborts with exit 3 if the tree is dirty.

3. Act - the loop

npx tsx state/bin/evolve/run.ts --max=3     # smoke (3 iterations)
npx tsx state/bin/evolve/run.ts --max=10    # default sanity
npx tsx state/bin/evolve/run.ts --max=999   # real session

Each iteration:

1. propose_mutation(i) - deterministic, rotating over a 5-candidate catalog.
2. apply_candidate() - edit + git add + git commit (local only).
3. measure() - recompute health_score.
4. keep_or_revert() - keep if Δ > 0.005, else git revert HEAD --no-edit.
5. Append one row to state/log/evolve.ndjson.

4. Log + eval

The harness itself appends to state/log/evolve.ndjson. Eval is shape-based: row presence + fields {i, candidate, baseline, new, delta, kept, wall_time_ms} intact. The delta sign determines whether the mutation landed.

Health score

Composite metric in [0, 1]:

Mutation catalog

Five seed candidates (rotated by (i-1) % N). Three earlier candidates (tune-breaker-cooldown, tighten-graduation-bar, swap-tui-view-order) were pruned 2026-04-26 because their target files (autopilot/break.sh, byline/tui.sh) and concept (graduation bar) were retired.

1. add-lint-rule-trailing-newline - new warn rule in state/lint/check.ts
2. extend-parity-canonical-5-to-6 - add ops to CANONICAL_SKILLS in state/lint/parity-test.ts
3. tighten-lint-rule - promote eval-unknown lint from warn → error in state/lint/check.ts
4. add-eval-gate-threshold - raise auto-eval gate 0.50 → 0.55 in state/lint/check.ts
5. prune-redundant-skill - new warn rule: skills must have a paired <name>/AGENTS.md loader

Mutations are idempotent - already-applied mutations SKIP cleanly (logged, no commit).

Eval

Actor: state/bin/evolve/run.ts (proposer + applier). Auditor: health_score() reading ndjson logs the actor does NOT write.

The actor cannot game the score because the score is sourced from independent logs (evals, breakage, parity, sync-events, pid-trends).

Score convention:

The kept/reverted decision is the evolutionary signal, not the eval.

Gotchas

• Working tree MUST be clean before invoke - exit 3 otherwise.
• Mutations are staged as local commits and NOT pushed. Operator decides

when (or whether) to push.

• The revert is the safety. There is no "pause on N regressions" knob -

that would cap the harness's agency (doctrine).

• Do not add LLM calls on the hot path - determinism lets the harness run

overnight without operator babysitting.

• Iterations are append-only; never rewrite rows in evolve.ndjson.

Graduation

Graduated on first commit - this skill is born with a sidecar. The prose is documentation, not the implementation.

Rubric

criteria:
  - name: working_tree_clean_exit_code
    kind: deterministic
    check: "The skill script exits with code 3 if the working tree is not clean at invocation."
  - name: log_integrity_and_completeness
    kind: deterministic
    check: "Each iteration appends a well-formed row to 'state/log/evolve.ndjson' containing fields {i, candidate, baseline, new, delta, kept, wall_time_ms} as specified."
  - name: mutation_catalog_adherence
    kind: deterministic
    check: "The 'candidate' field in 'state/log/evolve.ndjson' logs matches one of the 8 specified mutation names in the documented catalog for its corresponding iteration 'i'."
  - name: keep_revert_logic_adherence
    kind: deterministic
    check: "For each iteration, the 'kept' field in 'state/log/evolve.ndjson' is true if 'delta' > 0.005, and false otherwise, reflecting the 'keep_or_revert()' logic."
  - name: side_effect_honesty
    kind: judge
    check: "The skill only modifies the local git repository and 'state/log/evolve.ndjson', without pushing commits or altering other system states not explicitly mentioned."

evolve - loader

Per-turn rules for the evolve skill. Full reference: state/skills/evolve/SKILL.md. Do not skip these.

Critical Rules

• NEVER disable or weaken the revert primitive - it is the ONLY safety. No "pause on N regressions", no "stop if score drops", no manual confirm.
• NEVER skip measure() - a committed mutation without a measurement is a silent bias in baseline.
• NEVER rewrite rows in state/log/evolve.ndjson - the log is append-only; it is the artifact.
• ALWAYS start from a clean working tree (harness exits 3 if dirty). Stash first, don't force.
• DO NOT push to remote from inside the harness. Local commits only; operator chooses when to push.
• Mutations MUST be idempotent - a no-op candidate SKIPs cleanly, never double-commits.

Commands

| ui dashboard | state/skills/evolve/resources/ui.openui | |invoke: npx tsx state/bin/evolve/run.ts --max=<n> (default 10) |smoke: npx tsx state/bin/evolve/run.ts --max=3 |real: npx tsx state/bin/evolve/run.ts --max=999 |log: state/log/evolve.ndjson (append-only)

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/evolve/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Statusline/hook runs can dirty the working tree between iterations - if a revert leaves drift, the harness aborts (exit 4). Investigate the hook, don't patch the harness.
• pid-trends.ts is invoked per-iteration; if absent, recurring-area component defaults to 1.0 (no penalty) - don't confuse absence with perfection.
• health_score reads evals.ndjson tail-20 - if the log was recently truncated, baseline may be artificially low. Use a longer window for real sessions.

Self-Test

1. [ ] Is the working tree clean before invoke?
2. [ ] Is the mutation catalog idempotent (re-running the same iter is a no-op)?
3. [ ] Does every iteration append exactly one row to evolve.ndjson?
4. [ ] Does a reverted iteration leave the working tree clean?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] evolve: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] evolve: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.