zeugnis-cycle
Use when the user asks for a bounded self-optimization loop that re-runs zeugnis's audits until convergence or a pass cap, wants to 'run the zeugnis cycle', 'keep fixing findings until done', or asks for propose-only vs fix-mode passes. Runs at most max_passes_per_invocation (default 5) passes, applies fixes only in fixable domains, and stops early on convergence — every bound is enforced by scripts/cycle_engine.py, not by this file's instructions.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- zeugnis-cycle
- description
- Use when the user asks for a bounded self-optimization loop that re-runs zeugnis's audits until convergence or a pass cap, wants to 'run the zeugnis cycle', 'keep fixing findings until done', or asks for propose-only vs fix-mode passes. Runs at most max_passes_per_invocation (default 5) passes, applies fixes only in fixable domains, and stops early on convergence — every bound is enforced by scripts/cycle_engine.py, not by this file's instructions.
03 SKILL.md 正文
Run zeugnis's bounded self-optimization loop: repeatedly find the
"constraint" domain (the one with the most urgent open findings), audit
it, and — in fix mode — apply or draft fixes, until the loop converges or
hits its pass cap. The pass cap, the reopen thrash-guard, the fixable-
domain gating, and the convergence check are all enforced by
scripts/cycle_engine.py and scripts/lib/ledger.py; this file only
describes how to drive that engine. If your own count of passes ever
disagrees with what the engine reports, trust the engine — it is the
source of truth, not your running tally.
Setup (once per invocation)
- Determine
repo_root,mode("fix"or"propose"— default"propose"unless the user explicitly asked to apply fixes),max_passes(default 5, never pass a value above 20 to the engine — it will refuse), andmax_reopens(default 3, never above 10). - Generate one
invocation_idfor this whole run (e.g.python3 -c "import uuid; print(uuid.uuid4())") and reuse it for every symbol-index build this invocation needs — never build a fresh one per pass or per domain. This is what makes the symbol-index snapshot shared rather than rebuilt (rule: symbol-index-shared-per-invocation). Resolve it now:
This is the "CLI wrapper the cycle skill points you at" thatpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/symbol_index_cli.py" resolve <repo_root> --invocation-id <invocation_id>zeugnis-assertion-auditandzeugnis-contract-drift's "Shared symbol index" sections already reference — tell those domain skills this sameinvocation_idwhen dispatching them so they hit the cache instead of rebuilding.
Per-pass loop
Repeat the following until the engine tells you to stop:
- Ask the engine what to do next:
If this exits 2 with a stderr JSON object namingpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/cycle_engine.py" plan-next-pass <repo_root> \ --max-passes <max_passes> --mode <mode>"maxPasses"({"error": "...", "maxPasses": N}), the pass cap is already reached — stop the loop immediately and go to "Wrap up" below. Any other non-zero exit is a different failure (a badrepo_root, a corrupted ledger, an invalid--mode) surfacing as an uncaught crash rather than this deliberate refusal — surface that error to the user and stop; do not treat it as "cap reached" or proceed to "Wrap up" as if the loop finished normally. Otherwise it prints{"passNumber": N, "domain": "...", "mode": "..."}. - Run that domain's audit skill's Find (and, per that domain's own
rules, Verify) phase, scoped efficiently since you likely already have
recent findings from a prior invocation — reuse
analysis/zeugnis/<domain>_summary.jsonif it's fresh, otherwise re-run the audit as that skill's own SKILL.md describes. "Fresh" means the same checkscripts/status_dashboard.pyalready implements: the summary file's mtime is not older thangit -C <repo_root> log -1 --format=%ct(itsstaleRelativeToLatestCommitfield) — not a recorded commit or fingerprint field, which no domain*_summary.jsonstores. Do not weaken that domain's own mandatory-verification rules just because you're inside a cycle pass —assertion_auditstill runs its Verify phase unconditionally,contract_driftandagentic_reliabilitystill run theirs unless explicitly skipped. - For each open finding in the constraint domain, decide its handling:
- mode is
"propose": never apply anything. For a fixable finding (see below), still just describe the proposed fix in your report — do not dispatchzeugnis-remediatorat all in propose mode. Record that finding's outcome (step 6) as"blocked"with ablockReasonof"not applied: cycle is in propose mode"— there is no separate outcome for "described but not fixed";"blocked"is the existing value that keeps the finding open without claiming a fix happened. - mode is
"fix"and the finding IS in zeugnis's fixable set (dependency_auditany category,contract_driftany category,agentic_reliabilitycategoryexcessive-tool-grantonly — check with the same tablescripts/lib/constants.py FIXABLE_DOMAINSencodes, don't just guess): open a remediation scope, dispatch the remediator, then close the scope:
If this exits 3, the finding is NOT fixable — the script refused to even open a scope for it. Treat it as advisory and do not dispatchpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/remediation_scope_cli.py" open <repo_root> \ --finding-id <id> --domain <domain> --category <category> \ --target-file <repo-relative file>zeugnis-remediator; this can happen even in fix mode if a finding's category was miscategorized upstream, and the script is the authority here, not your own read of the finding. If it exits 0, dispatchzeugnis-remediatorwith exactly this one finding. APreToolUsehook enforces that its oneEditcall must target the locked file and that no second edit is possible in this scope — you do not need to police that yourself. After the remediator returns, run:python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/remediation_scope_cli.py" close <repo_root> - the finding is in
assertion_audit, oragentic_reliabilityoutsideexcessive-tool-grant: this is draft-only or advisory — never open a remediation scope for it, never dispatchzeugnis-remediator. Forassertion_auditspecifically, you may ask theassertion-auditoragent to run in Suggest mode to draft a replacement assertion, but that draft is reported, never applied — noEditcall happens for it, ever.
- mode is
- Build this pass's outcome record and tell the engine:
Use{"passNumber": N, "domain": "...", "mode": "fix"|"propose", "outcomes": [{"findingId": "...", "category": "...", "evidence": "...", "severity": "...", "outcome": "fixed"|"drafted"|"blocked"|"reopened", "blockReason": "... (required when outcome is \"blocked\")"}]}"fixed"only for a findingzeugnis-remediatorreturnedstatus: "applied"for. Use"blocked"for one it returnedstatus: "blocked"for, or one you determined is not fixable — and always copy itsreasonintoblockReasonhere; the engine rejects (exit 2) any"blocked"outcome with an emptyblockReasonrather than accepting a blocked finding with no explanation on record. Use"drafted"for an assertion-audit Suggest-mode draft. Use"reopened"for a finding that was closed in a prior pass/invocation but is open again this pass. Write this to a scratch JSON file and run:
This is the ONLY place ledger state changes — do not hand-editpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/cycle_engine.py" record-pass-result <repo_root> \ --pass-json <path> --max-reopens <max_reopens> --max-passes <max_passes>analysis/zeugnis/ledger.jsonyourself. The script rejects (exit 2) any"fixed"outcome for a non-fixable domain/category or for a"propose"-mode pass; if you see that rejection, you made a mistake in step 5 — fix your outcome record, don't retry with a different claim to force it through. It prints{"converged": bool, "shouldContinue": bool, ...}. IfshouldContinueisfalse, stop the loop — either the pass cap was reached or the pass converged (closed zero findings and produced zero fix/draft outcomes). Do not start anotherplan-next-passcall aftershouldContinue: false. In"propose"mode,"blocked"outcomes never count toward fix/draft outcomes, so a propose-mode pass can report"converged": trueon its very first pass regardless of how many findings were described — do not read that as "nothing needs attention" when summarizing for the user; report the open findings themselves.convergedis also forcedfalsewhile any verified domain's sidecar hasunverifiedCount > 0(or an unreadable sidecar): the output then lists them underunverifiedBlockers. That is an abstain, not a pass: re-run that domain's Verify phase rather than starting more passes (shouldContinuestaysfalse).
Wrap up
analysis/zeugnis/reports/ZEUGNIS_CYCLE.mdalready has one line appended per pass by the engine. Summarize it for the user: total passes run, which of the three stop reasons applied — convergence, the pass cap, or blocked by unverified findings (converged: falsewithunverifiedBlockers; name each blocked domain and say its Verify phase must be re-run — that is not convergence and not a clean result) — findings closed, findings escalated (reopened pastmax_reopens), and anything left open.
What NOT to do
- Do not run more than
max_passespasses in one invocation, even if the user asks you to "just keep going" — a fresh invocation (a new call to this skill) is how they get more passes;plan-next-passwill refuse once the cap is hit regardless of what you're asked. - Do not dispatch
zeugnis-remediatorfor anassertion_auditfinding or a non-excessive-tool-grantagentic_reliabilityfinding under any framing — the remediation-scope script refuses to open a scope for these, and thePreToolUsehook refuses the edit even if you tried to route around the scope step. - Do not treat a
"blocked"remediator outcome as a failure to retry immediately — record it as"blocked"and let it surface as an open finding for the next pass or the user's manual attention.
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.