AGENT SKILL

kupo-patch-verify

Phase P+O sandbox patch loop with external verifier; governs edit emission, harness applier invocation, per-file loop detector, circuit-breaker, and pre-completion green-signal gate. Use when Kupo enters Phase P to emit a patch or Phase O to run verifiers; load after a KEEP decision. Do NOT use during Phase K or U.

License 许可
Apache-2.0
所属仓库
Rynaro/magicite
最近更新
2026-10-14
Stars
★ 2
Forks
0

01 前言 Front Matter

name
kupo-patch-verify
metadata
{ "phase": "P+O", "methodology": "Kupo" }
description
Phase P+O sandbox patch loop with external verifier; governs edit emission, harness applier invocation, per-file loop detector, circuit-breaker, and pre-completion green-signal gate. Use when Kupo enters Phase P to emit a patch or Phase O to run verifiers; load after a KEEP decision. Do NOT use during Phase K or U.

03 SKILL.md 正文

Patch-Verify Skill — Kupo (Phase P+O loop)

When to use

Load during Phase P (Patch) and Phase O (Observe). Governs the edit → harness-apply → sandbox → verify loop. Never invoked in K or U.

Loaded during Phase P (Patch) and Phase O (Observe). Governs the edit → harness-apply → sandbox → verify loop. Never invoked in K or U.


Phase P — Patch

Edit emission

Emit the edit in one of two forms. Never emit a diff.

Form 1 — search/replace (default):

{
  "target_path": "src/foo.ts",
  "edit_kind": "search_replace",
  "blocks": [
    { "search": "<exact verbatim text to find>", "replace": "<new text>" }
  ]
}

The search text MUST be verbatim — character-exact. Do not summarize, paraphrase, or use placeholders. If the exact text is unavailable, go back to Phase U and gather more context before emitting.

Multiple blocks are allowed when replacing non-adjacent hunks in the same file. Each block is applied in order; they MUST NOT overlap.

Form 2 — whole-file (use when the file is small or a full rewrite is cleaner):

{
  "target_path": "config.yaml",
  "edit_kind": "whole_file",
  "content": "<full new file content>"
}

Use whole-file only when search/replace would require > 3 blocks or the file is < ~80 lines. For large files, prefer targeted search/replace blocks.

Why never a diff: small models cannot reliably apply unified diffs (Qwen-7B 0.59 EM; disabling fuzzy apply = 9× errors — Aider/Diff-XYZ studies). The harness applier provides deterministic fuzzy matching; Kupo's job is to emit clean structured proposals.

Harness applier — TRUST IT, it is real

The nexus ships the applier. Invoke it on the scratch working copy the parent provides (a throwaway copy of the repo — never the real tree):

eidolons sandbox apply --proposal <proposal-json> --root <scratch-dir>

It applies your search/replace (with deterministic fuzzy matching) or whole-file edit to the files already under <scratch-dir> and reports applied or a structured error. Kupo never writes files directly — this is the only mutation path.

Do not doubt the tool. eidolons sandbox apply exists and is installed. If you cannot immediately confirm it, RUN IT — do not assume it is missing, and do not REFUSE/ESCALATE a KEEP task on a tool-existence doubt. A not_found result means your search text was not verbatim → return to Phase U, tighten the anchor, and retry. An apply error is a Phase O failure (increment counters, adjust the proposal, loop) — never a reason to abandon a trivially-in-scope task.

Per-file loop detector

Track attempt count per target_path. If the same target file has been patched 3+ times without a green signal from Phase O:

  • This file is stuck. Do not keep patching.
  • Count it as 3 consecutive failures toward the circuit-breaker.
  • If the circuit-breaker has not yet fired, attempt a different approach (e.g., switch edit form, re-gather context) — but only one retry.
  • If still no green signal, ESCALATE.

Phase O — Observe

Running external verifiers

Use the named verifier from Phase K (never substitute a different one):

# Run the NAMED verifier in the applied scratch copy (its cwd). It has no --root:
( cd <scratch-dir> && <verifier-command> ); echo "exit=$?"
# For untrusted/host-isolated execution, wrap it via the sandbox (carries --via):
eidolons sandbox run --via <sandbox-cmd> -- <verifier-command>

Supported verifier classes: test, typecheck, lint, compile, diff, schema-validate.

Success silent, failures verbose

  • Green (exit 0): proceed immediately to pre-completion gate. Do not re-run; do not seek a second confirmation. One green signal suffices.
  • Red (non-zero exit): capture the full output. Keep it in context. Do not truncate. Surface failures verbosely to inform the next P iteration.

Circuit-breaker (mandatory)

Counter Threshold Action
Consecutive failures (same or different targets) 3 STOP → ESCALATE
Total failed attempts (entire session) 20 STOP → ESCALATE

A "failure" is any of: applier error, non-zero verifier exit, timeout, per-file loop detector trigger.

Counters never reset within a delegation. If the circuit-breaker fires, ESCALATE immediately — do not attempt a final "just one more" patch.

Step ceiling and timeout

Respect the host-declared step ceiling. Treat any command that exceeds the per-command timeout as a failure (increment both consecutive and total counters). Do not ignore timeouts.

Pre-completion green-signal gate

Emit a PROPOSE only after ≥ 1 green external signal.

This gate is mandatory. It defeats the "models almost never abstain" failure mode (RiskEval 2601.07767) — structural, not verbal. Do not emit PROPOSE after introspection ("I'm confident this is right") — only after the verifier exits 0.


Output: edit-proposal artefact + ECL PROPOSE

On green signal:

  1. Construct the edit-proposal JSON matching schemas/kupo-edit-proposal.v1.json:

    {
      "schema_version": "1",
      "kind": "edit-proposal",
      "task_ref": { "thread_id": "<from envelope>", "from_eidolon": "<sender>" },
      "edits": [ { "target_path": "...", "edit_kind": "search_replace", "blocks": [...] } ],
      "verification": {
        "verifier": "<command>",
        "verifier_class": "<class>",
        "result": "green",
        "output_excerpt": "<first 200 chars of output, or empty>"
      },
      "sandbox": {
        "applied": true,
        "ephemeral": true,
        "applier": "eidolons sandbox apply",
        "attempts": <N>
      }
    }
    
  2. Compute sha256 + size_bytes of the artefact file. (If Bash is unavailable, emit PARENT_FILLS_SHA256 and PARENT_FILLS_SIZE_BYTES as placeholders; the parent patches these before running harness_verify.)

  3. Compose the ECL envelope sidecar, validated against schemas/ecl-envelope.v2.json (schemas/ecl-envelope.v1.json is retained in-repo for the ECL §7.3 back-compat window — do not emit against it for new proposals):

    {
      "envelope_version": "2.0",
      "message_id": "<UUIDv7>",
      "thread_id": "<from inbound envelope>",
      "from": { "eidolon": "kupo", "version": "<version>" },
      "to": { "eidolon": "<original sender>" },
      "performative": "PROPOSE",
      "objective": "<≤240-char summary of the edit>",
      "artifact": {
        "kind": "edit-proposal",
        "schema_version": "1",
        "path": "<relative path to artefact>",
        "sha256": "<hex>",
        "size_bytes": <N>
      },
      "ise": {
        "assertion_grade": "validated",
        "provenance": {
          "methodology_version": "kupo-<version>",
          "tool_surface": ["Read", "Grep", "Glob", "Bash(eidolons sandbox:*)"],
          "lateral_consults": []
        },
        "receiver_authorization": {
          "auto_route": true,
          "auto_merge": false,
          "auto_deploy": false
        }
      },
      "integrity": { "method": "sha256", "value": "<hex>" }
    }
    

    Why ise.assertion_grade: "validated" (ECL v2.0 §6.5) on every PROPOSE, with no lower grade ever emitted: Kupo never reaches PROPOSE except through the pre-completion green-signal gate above — a NAMED external verifier (the one skills/keep-or-kick/SKILL.md required to exist before KEEP was even granted) exited green in the sandbox. That is "emitter ran spec-mandated gates" by construction, not a self-report — validated is earned, not defaulted. ise.receiver_authorization.auto_merge: false is load-bearing, not boilerplate: the parent applies and commits (§4, PROPOSE-only P0) — Kupo's own verified signal never authorizes a receiver to merge on Kupo's say-so. auto_route: true / auto_deploy: false follow the same §6.5 defaults every Eidolon in the roster uses.

  4. Write both files. Signal the parent that PROPOSE is ready.

  5. Post-flight procedural-memory commit (SHOULD, additive). After the green signal that gates step 1, and before or alongside emitting PROPOSE, commit the verified edit pattern — see SPEC.md §9 "Post-flight commit (KEEP verified)". Graceful-skip when CRYSTALIUM is absent.


Notes

  • One green signal is enough. Do not seek multiple confirmations.
  • Keep failures in context. Prior error output informs the next patch. Do not discard failure output between P→O iterations.
  • Escalate loudly. When the circuit-breaker fires, include the last failure output in the ESCALATE body so the parent can diagnose without re-running.
  • Never write the real tree. The only mutation path is eidolons sandbox apply. Any direct file write would violate §4.

Patch-Verify Skill — Kupo Phase P+O loop

04 同仓库更多 Skills

Rynaro
Rynaro/magicite

wine-dxvk-cache-clear

Clear a stale DXVK shader cache that is causing graphical corruption in a Wine or Proton game. Use when: a game shows corrupted textures or shader flicker that started after a driver or DXVK version change.

★ 2
Rynaro
Rynaro/magicite

steam-download-region-fix

Fix a Steam client stuck at very low download speed by changing its download region. Use when: Steam downloads are far below the local internet speed for every game, not just one.

★ 2
Rynaro
Rynaro/magicite

proton-battleye-eac-toggle

Toggle BattlEye or Easy Anti-Cheat runtime support for a Steam Proton game. Use when: a multiplayer game refuses to launch with an anti-cheat error under Proton.

★ 2
Rynaro
Rynaro/magicite

vivi-verify-incoming

Load when reading any upstream artefact handed off to Vivi that carries a sibling .envelope.json. BLOCKING per ECL §6.2.2: the orchestrator MUST have verified the envelope's SHA-256 (eidolons verify-envelope --block / eidolons run --verify) and recorded a verify_pass before dispatch. If no verify_pass exists for the message_id, or a verify_fail is present, REFUSE to process the payload and hand back to the orchestrator. Symmetric receiver gate — every Eidolon enforces it identically.

★ 2
Rynaro
Rynaro/magicite

vivi-parallel-tracks

Load ONLY under TRANCE authorization when the Plan phase yields N independent, non-overlapping implementation tracks (disjoint file sets). Operationalizes the TRANCE G4 form — parallel multi-track implementation in mandatory git-worktree isolation, max 5 clean-context tracks, a per-track verifier cascade, a non-fungible per-track ≤3 reflection budget, explicit stop conditions, and a single-threaded merge/aggregation step. Absent TRANCE gating, Vivi runs exactly as today: single-track A→P→I→V→Δ/R.

★ 2
Rynaro
Rynaro/magicite

vivi-methodology

Full Vivi cycle reference — A(nalyze) → P(lan) → I(mplement) → V(erify) → Δ(Delta)/R(eflect). Use when the task is a non-trivial feature implementation in a brownfield codebase and you need the complete methodology reference: complexity routing, evidence-grounded planning rules, test-anchoring requirements, and failure-escalation thresholds.

★ 2