Evolve

Evolve

Use this skill when current work exposes a lesson that is likely to prevent a future mistake. Fix and verify the current task first. Do not invoke it for a one-off detail that has no recurring value.

Agent Context Patch is agent-first:

• The agent understands the project, judges evidence, chooses wording, and prepares semantic changes.
• The deterministic commit kernel validates the plan envelope, paths, policy, hashes, conflicts, and application. The Lifecycle Coordinator owns deterministic proposal reconciliation and audit continuation. The Outcome Interface validates and formats the ephemeral delivery result; the agent owns detection, proposal meaning, and semantic lifecycle decisions. Neither deterministic module judges project meaning or edits proposal prose.
• auto is the default write policy for new workspaces. It requires the Node kernel; if the kernel is unavailable, preserve the exact proposal, report the reason, and use the approval path instead of pretending the patch was applied.

Read references/protocol-v1.md for the normative v1 contract.

Context loading

For normal project work, load only:

1. .agent-context/PROJECT_CONTEXT_INDEX.md
2. .agent-context/PROJECT_PROFILE.md
3. the relevant checklist for a domain enabled in config.yml

Do not load proposals, reports, or archive by default. Read config.yml and the relevant reference only when evolving context.

Lifecycle reconciliation

For $evolve after-failure, $evolve approve, $evolve review-context, and $evolve weekly, invoke the installed runtime's dedicated coordinator before creating, approving, or reporting more proposal work. Invoke it again after a new eligible auto proposal or an exact approval is persisted so the coordinator owns the apply-and-audit continuation:

import { reconcileWorkspaceProposalLifecycles } from "./runtime/lifecycle.mjs";

const reconciliation = await reconcileWorkspaceProposalLifecycles({
  workspaceRoot,
});

Resolve the module path from the installed Skill; the example path is relative to this file, not the user's current directory. This is not a new public command. Do not run it from init, update, installation, Agent startup, a daemon, or a background scan.

Handle its content-safe outcomes as follows:

• resume_exact_auto or resume_exact_authorized: report the resulting state; do not append another Decision for an already-approved plan.
• regenerate_required: re-read current sources and semantically rebuild the history-free proposal; deterministic code must not choose new wording.
• superseding_proposal_required: create a replacement proposal, write that exact proposal ID in the old Supersession section, then reconcile again. The coordinator alone verifies the cross-proposal edge before changing the old status to superseded.
• audit_recovery_required: stop. Matching after hashes do not prove that this proposal applied; never invent the missing Attempt or silently reapply.
• manual_recovery_required: stop automatic work and report the one machine-readable reason.
• approval_required: continue only through the existing informed approval path.
• settled: no additional lifecycle action is needed for that proposal.

If the lifecycle lock remains after a crash, verify that no coordinator is active before manually removing only .agent-context/.lifecycle-coordinator.lock. Never delete it based on age.

Delivery checkpoint

After the current fix is verified, run one delivery checkpoint only when at least one high-signal event occurred:

• failed_verification_later_passed
• explicit_user_correction
• independent_qa_defect
• stale_context
• first_fix_failed_then_passed

The Agent decides the semantic detect and propose stages. If a proposal was created or an existing proposal was reconciled, pass the exact content-safe Lifecycle Coordinator result as mechanical evidence; never synthesize the apply stage. Finalize the task-level result through the installed Skill's separate Outcome Interface:

import { finalizeEvolutionOutcome } from "./runtime/outcome.mjs";

const outcome = finalizeEvolutionOutcome({
  detect,
  propose,
  proposalId,
  reconciliation,
});

Omit proposalId and reconciliation for no_candidate or a semantic blocker. Resolve the module path from the installed Skill. Print only outcome.receipt.text: it covers detect, propose, and apply; every non-success stage includes one stable machine-readable reason. Applied results may also include only a content-safe proposal ID and sorted workspace-relative targets. Do not add lesson prose, PatchPlan content, target content, secrets, conversation data, or absolute paths to the receipt.

The valid state families are:

• no_candidate / not_needed / not_attempted
• skipped / blocked / not_attempted
• candidate / blocked / not_attempted
• candidate / created / applied | approval_required | blocked
• skipped(existing_proposal) / not_needed(existing_proposal) / applied | approval_required | blocked

Any other combination is invalid and must fail closed. In particular, the Outcome Interface cannot report applied without the exact proposal ID and a verified applied audit from settled reconciliation. If finalization itself rejects the inputs, report only invalid_evolution_outcome; do not hand-format a success receipt.

If there is no high-signal trigger, stay silent: do not create a proposal or durable context write merely to emit an outcome. detect: skipped is available only when an explicit diagnostic result is required. The outcome and receipt are ephemeral task results; proposal aggregates remain the durable audit source.

Hard invariants

• Never let evolution delay repair of the current task.
• Never apply a proposal until current_fix_status is verified.
• Workspace is the only active context scope in v1.
• User-global is valid only for a manually approved promotion proposal; the workspace kernel cannot apply it.
• Supported write policies are propose and auto. New workspaces default to auto; an existing workspace's explicit config remains authoritative.
• Deletion, cleanup, migration, domain activation, instruction-file changes, and user-global promotion always require human approval.
• Approval covers one immutable PatchPlan and its plan_hash. Changed targets require a new plan and new approval.
• The proposal aggregate itself is never a PatchPlan target. Decision and Apply Attempt writes stay outside the kernel transaction.
• Never infer applied from target content. Exact before hashes permit resume; after hashes without an applied Attempt require audit recovery.
• Never hand-format a detect-to-apply success. The Outcome Interface requires settled Lifecycle Coordinator evidence and strips unsafe detail.
• Every non-migration kernel call requires a complete current v1 config. Future schemas remain read-only; legacy migration requires exact backups for every changed existing file in the same approved transaction.
• Archive targets are create-only history. Approval can add a new snapshot but cannot rewrite an existing archive file.
• A workspace proposal persists the complete JSON PatchPlan. Its target_files, frontmatter plan_hash, Decision Log hashes, and Apply Attempt hashes must agree with that plan.
• PatchPlan semanticOperation must equal proposal frontmatter operation. Auto is possible only for semanticOperation add.
• Approval and application are separate internal states. Eligible auto plans do not require a user decision; $evolve approve handles only the exception path that requires one.
• Active context changes use replace-before-add. Never append a rule before checking for duplication, overlap, conflict, or a better replacement.
• Evidence is pointer-first and summary-first. Never persist secrets, raw conversations, complete logs, customer data, or unnecessary absolute paths.
• Kit updates run only when the user invokes $evolve update. They never poll in the background, emit telemetry, silently replace the installed skill, edit a workspace, or authorize a workspace-schema migration.

Commands

$evolve init

Initialize or refresh the current workspace:

1. Resolve the workspace root; a Git repository is one possible workspace, not a separate scope.
2. If config.yml has no schema_version, read references/legacy-migration.md and remain read-only until a migration proposal is approved. If it claims v1 but fails the complete config envelope, stop as invalid rather than materializing missing templates.
3. Inspect source-of-truth files and mark uncertainties rather than guessing.
4. Detect candidate domains with evidence, confidence, and uncertainties.
5. Build one InitPlan containing candidate domains, active files, exact patches, and context impact. Split safe Active Context additions from approval-only config or domain changes.
6. Apply every eligible auto addition immediately. Request one concise decision only when the plan also changes config or enabled domains; the user never needs to copy a plan hash.
7. Store only approved enabled_domains in config.yml. Materialize checklists only for enabled domains; detected candidates remain temporary plan data.
8. Give one compact receipt for applied changes and list only unresolved safety exceptions. Do not dump the full InitPlan unless the user asks.

Auto cannot enable or disable domains.

$evolve after-failure

Run autonomously after a correction, failed verification, repeated mistake, missed context read, or stale-context discovery. The user does not need to invoke this command manually:

1. Repair the current issue and verify it when possible.
2. Reconcile unfinished proposal lifecycles before creating another aggregate; handle every blocking outcome using the rules above.
3. After verification, run the delivery checkpoint. Decide whether the lesson is reusable. If not, finalize no_candidate / not_needed / not_attempted and print only its compact receipt.
4. Compare it with active context using replace-before-add. Compare the responsibility, trigger, reachable execution path, intended effect, and observable verification rather than relying on shared nouns. Only when related active rules suggest the same responsibility or failure shape, read pointer-first summaries for those applied proposals and shortlist the few aggregates needed to test subsumption. Do not scan full proposal history after every failure.
5. Create one evidence-backed proposal aggregate in proposals/.
6. Use pending_current_fix while repair is not verified; otherwise use proposed.
7. Keep evidence as workspace-relative pointers and short result summaries.
8. Evaluate authority, retention value, privacy, and the net active-context change.
9. When the patch adds an Active Context rule, give each new rule a stable ID using the source proposal ID plus a one-based ordinal. Place a compact acp-rule Markdown comment immediately above it with its source proposal and subsumes: none. A replacement uses a new ID and names the replaced IDs; never retrofit IDs through an unapproved bulk migration.
10. For a workspace proposal, persist the full JSON PatchPlan under Proposed Patch and compute plan_hash from its canonical JSON.
11. Evaluate policy and all auto gates. When eligible, invoke Lifecycle Reconciliation again. It persists the policy_auto Decision, enters approved, calls the Commit Kernel with the exact runtime plan, appends the Apply Attempt, and enters applied only after success.
12. Finalize the Agent-owned detect and propose stages with the exact reconciliation result through finalizeEvolutionOutcome. Print only outcome.receipt.text; do not request approval, wait for a reply, or print the full PatchPlan or plan hash on an applied path.
13. If an auto gate fails, keep the exact proposal and let the Outcome Interface report approval_required or blocked with one machine-readable reason and a safe next action when known. Ask for a decision only when the operation is an allowed approval-only exception.

$evolve approve

This is the public exception path for a proposal that cannot use auto:

1. Reconcile unfinished lifecycles. If the requested proposal was resumed to applied or superseded, report that result and stop. If it needs regeneration, supersession, audit recovery, or manual recovery, resolve that exact outcome before requesting approval.
2. Parse the four-tilde JSON block under Proposed Patch / PatchPlan JSON. Reject prose-only or partial patch descriptions.
3. Recompute canonical JSON SHA-256 and require it to equal frontmatter plan_hash. Require target_files to equal the operation targets and every existing Decision/Apply hash to equal the same value. Require semanticOperation to equal frontmatter operation.
4. Show a concise semantic summary followed by the complete immutable plan: target contents, operations, before hashes, policy result, context delta, and plan_hash. High-risk approval must be informed even though it is rare.
5. Obtain explicit approval for the exact current plan. The user may simply reply with approval; never require them to copy or repeat the hash.
6. Persist a Decision Log entry and status approved. If this write fails, stop before calling the kernel.
7. Invoke Lifecycle Reconciliation again. It rechecks the exact plan, current config, paths, mechanical privacy, and before hashes, adds runtime-only absolute workspaceRoot and planHash, then calls applyPatchPlan(plan, {approvedPlanHash}). Approval stays outside the hashed plan and must match plan_hash exactly.
8. Let the kernel transaction update only the context targets and return its raw status, reason, and per-target hash operations.
9. Let the coordinator map that result to an Apply Attempt, add the attempt timestamp and a content-free error summary, then append it immediately. On success it sets status to applied; on conflict, failure, or rollback it keeps status approved.
10. If audit writeback fails, report audit_write_pending and retry it. Do not create a separate receipt or claim lifecycle completion.

If a target changes before any decision or attempt, replace the plan and recompute its hash. After audit history exists, create a superseding proposal instead, write the replacement ID in the old Supersession section, and rerun Lifecycle Reconciliation; one aggregate never mixes hashes from multiple plans. Without the kernel, propose mode may apply the exact human-approved patch, but must still record hashes and the result.

A user-global promotion has no workspace PatchPlan before an adapter resolves its real target. Store only a sanitized candidate hash, keep status proposed, and defer exact approval to the adapter plan. Never send it to the workspace kernel.

$evolve review-context

Review active context against current sources. Use references/cleanup-policy.md and references/context-budget.md.

• Reconcile unfinished proposal lifecycles before calculating proposal health.
• Rank authority separately from retention value.
• Detect stale, duplicated, conflicting, vague, or over-specific rules.
• Use a summary-first two-stage read: scan Active Context plus proposal IDs and short summaries, then deeply inspect only the shortlist that may share the same responsibility and behavior failure shape.
• Generalize across different implementation nouns only when one testable invariant preserves the included verification guarantees. Record subsumed rules and proposal IDs, preserved domain details, exclusions or counterexamples, behavior lost, and net active-context change.
• Prefer tighten, merge, rewrite, supersede, or archive over another append.
• When bounded, content-safe task evidence is available for a stable rule ID, distinguish material_use, loaded_only, relevant_but_missed, not_applicable, and unknown. Reading a context file alone is loaded_only; absent task coverage is unknown, not evidence of disuse.
• Recommend only retain, observe, narrow_route, rewrite_candidate, or cleanup_candidate. Low use schedules review and never authorizes removal.
• Produce an exact cleanup proposal with what behavior would be lost and the net context change.
• Require human approval for every semantic removal or replacement.

Thresholds trigger review and block auto; they never authorize truncation.

$evolve weekly

Reconcile unfinished proposal lifecycles first, then write a compact derived report in reports/ covering:

1. recurring signals and verification status
2. applied improvements
3. proposal triage
4. stale, redundant, or conflicting active context
5. a bounded effectiveness view for reviewed stable rule IDs: relevant-task opportunities, material uses, recurrence after activation, last material-use pointer, irrelevant-load observations, and explicit unknown coverage
6. review signals independent of line count, including repeated failure after activation, repeated loaded-only or irrelevant default loading, rapid active additions, long auto-add sequences without cleanup, and undifferentiated high-retention declarations with little known coverage
7. recommended patches, cleanup, and possible cross-noun generalization candidates for $evolve review-context; the report never merges them
8. next review priorities

Reports are rebuildable views, not sources of truth, and are not part of the default context read. Inspect only explicitly available, content-safe task evidence. Do not add a background scan, per-task receipt, raw usage ledger, or mechanical hit-rate score.

Personal multi-repository dogfooding

When the user explicitly wants to establish or review their own long-running use of this kit across repositories, read the experimental owner-dogfood guide references/personal-dogfooding.zh-CN.md. Keep each repository workspace-first, promote only evidence-backed patterns, and do not turn the review cadence into mandatory ceremony when no real signal exists.

$evolve update

This is the only public Kit update entry point. Run it only when the user asks:

1. Resolve the installed evolve skill path and read its manifest without scanning workspaces.
2. Query https://github.com/Cherwayway/agent-context-patch/releases/latest, resolve the latest stable Release to one GitHub-enforced immutable tag and source commit, and compare its Kit Version with the installed version. Stop if the Release is not marked immutable. If the check is unavailable, report that and leave the current install usable. If the installed version is current or newer, report that and stop; this command never downgrades an installation.
3. Download that exact Release and its published integrity metadata to a local temporary directory. Verify the published archive checksum, the GitHub Release tag and target commit, and the unpacked skill manifest version. Require those identities to agree. Stop on missing metadata or any mismatch.
4. Execute the Bootstrap from the unpacked candidate Release in UpdateDryRun mode against the resolved installed skill path. The candidate Release is the update source; never run the installed Bootstrap as its own source.
5. Show the complete UpdatePlan: installed and target versions, immutable tag and commit, artifact checksum, exact installed and candidate managed-tree hashes, whole-skill replacement scope, recovery copy, workspace-schema impact, rollback behavior, and exact plan hash.
6. Obtain explicit approval of that exact hash. A changed candidate, target, or plan requires a new dry-run and new approval.
7. Invoke the same candidate Release Bootstrap in UpdateApply mode with the approved hash. Do not merge locally modified skill files or include an instruction-file patch or workspace migration in this mechanical update.
8. Report verification and recovery results. On failure, restore the prior working skill when possible. If automatic restore fails, retain and report the recovery copy; never claim success from an incomplete replacement.
9. On success, report the installed version and tell the user to start a new Agent task so the updated skill is loaded.

Version discovery sends no workspace path, context, source code, conversation, or usage event. GitHub Release notifications are external; this skill provides no daemon, scheduled check, telemetry, or silent upgrade.

Policy evaluation

Read context_write_policy from config.yml. auto is the default write policy for newly initialized workspaces:

• auto: complete the same audited lifecycle immediately without a human decision when every low-risk gate in references/protocol-v1.md passes.
• propose: an explicit cautious mode, or a preserved setting in an existing workspace; create the exact record and wait for approval.

If an auto gate fails, keep the proposal and its machine-readable policy result, but show the user only one concise exception by default:

requested_policy: auto
effective_policy: propose
reason: <machine-readable-reason>

The agent or kernel must not weaken a failed gate. A successful auto path must end with one non-blocking receipt and no request for user action.

References

• references/protocol-v1.md
• references/config-schema.md
• references/proposal-schema.md
• references/legacy-migration.md
• references/domain-packs.md
• references/context-budget.md
• references/cleanup-policy.md
• references/privacy.md
• references/personal-dogfooding.zh-CN.md
• references/domain-coding.md
• references/domain-prd.md
• references/domain-seo.md