Overview
The evolution loop has two ends:mutation endwhich produces new rule candidates,selection end, which judges which candidate is better. The number one failure mode in this repository is "add a rule whenever a problem occurs" — that is preciselymutation only, no selection(ball of mud).
This skill only does theselection end, and only the part of it that ismechanically provable: it turns "which rule needs fixing" from the model'sopinioninto the script'sexit code。
Thesis: any "improvement suggestion" that cannot be reproduced by a single command produces no finding.
When to Use
| Trigger | Description |
|---|---|
| Standalone invocation(primary path) | The user or agent explicitly runs a full audit (7 skills + root prompt);--skills the scope can be narrowed |
goal-loop P5 incremental hook |
Review at the delivery archive stagewhat this delivery touchesof skills/<n>/; no full scan |
Not applicable(structural exclusion, see references/checks-spec.md §5）：
- Evaluating "whether this skill should exist", "whether responsibilities overlap", "whether the design is too heavy" — there is no objective signal, and this is a high-incidence area for sycophancy;
- Evaluating whether the criteria thresholds themselves are reasonable (e.g., "should 1000 lines be 800 lines").
Hard Invariants
- Zero LLM, zero network: The judge must not call any model and must not access the network. The same input always yields the same output.
- Read-only: Collection and judgmentmodify no files. Modifications are initiated separately after human adjudication.
- Facts and findings separated: The collector only answers "what it is"; only the judge answers "what is wrong". The two belong to different processes, and merging them is prohibited.
- Human adjudication not outsourced: The report stops as soon as the judge writes the "Human Adjudication" heading. Any adjudication content filled in on behalf of the model is considered agate violation(GI-4 assertion guard).
Quick Start
python3 skills/spec-evolution/scripts/collect-facts.py --out /tmp/facts.json
python3 skills/spec-evolution/scripts/judge.py --facts /tmp/facts.json \
--json /tmp/findings.json --report /tmp/report.md
echo "exit=$?" # 0 = 无 BLOCKER/HIGH；1 = 存在 BLOCKER/HIGH；2 = 用法或输入错误
Narrow the scope (used during P5 incremental review to shorten runtime):
python3 skills/spec-evolution/scripts/collect-facts.py --no-gates --skills goal-loop,doc-governance --out /tmp/facts.json
⚠️
--no-gateswillskip S1 gate fact collection, and therefore C-09 is not executed in this round: the report outputs "gate facts not collected — C-09 not executed" for that item rather than "no failures", and the exit code no longer reflects the existing gate status.The final review before release must be run without--no-gates。
Criteria
The full definitions of the ten criteria, severity semantics, and known expression limits are in references/checks-spec.md。
| ID | Criterion | Severity |
|---|---|---|
| C-01 | Skill has no tests/ or has no test_*.py |
HIGH |
| C-02 | Skill has no architecture design document docs/explanation/architecture/<n>-design.md |
MID |
| C-03 | Skill delivery surface lacks references/ / scripts/ / templates/, or it exists but is empty |
MID |
| C-04 | description character count > 500 (soft recommended value, non-hard limit) |
MID |
| C-05 | description character count ≥ 1024 (Agent Skills spechard limit） |
HIGH |
| C-06 | single file line count > 1000 | MID |
| C-07 | skill missing registration in 4 registration surfaces | HIGH |
| C-08 | cross-skill relative links exist within the skill | HIGH |
| C-09 | any existing gate exits non-zero | BLOCKER |
| C-10 | root prompt net growth relative to baseline | MID |
Anchor Contract (Anchors)
Each finding carries an anchor that can be directly verified by a human.When an anchor path does not exist, the evaluator itself errors and exits with 2(to prevent anchor hallucination). The three forms and validation rules are described in references/anchor-contract.md。
Exit Codes (Exit Codes)
| Code | Meaning |
|---|---|
0 |
None BLOCKER/HIGH(may include MID advisory; when C-09 is not collected, that item does not participate in the determination) |
1 |
Exists BLOCKER/HIGH |
2 |
usage or input error (including anchor path not existing = anchor hallucination) |
The authoritative definition is in
scripts/judge.pyand references/checks-spec.md; this table is consistent with them.
Red Lines (Red Lines)
- Must notautomatically fix findings—that would reduce this skill to a "rule that automatically modifies its own rules", i.e., a mechanized version of a ball of mud.
- Must notadd clauses to
contexts/AGENTS.md; that file's admission criterion prohibits net growth. - Must notintegrate this skill into CI or introduce third-party dependencies.