Skip to content

ccoalm/ccl-skills / skills/skill-extraction-workflow

skill-extraction-workflow

Flagged

复盘 / 沉淀 / 总结经验 / 补进技能 / 技能缺陷 / 流程优化 / would other teammates hit this / will we forget next time / teamwide recurrence / extract skill / post-mortem / 深度 review·审计技能仓库 / 对标外部技能包找 gap(benchmark superpowers·gstack 等) / 核查全局安装点(~/.config/opencode 等)旧快照是否遮蔽本仓技能 / 本仓(ccl-skills 等共享技能仓)OpenCode 项目配置·命令治理 → turn reusable lessons into durable CCL skills.

FileKindSize
SKILL.mdskill md111.0 KB
agents/openai.yamlconfig257 B
references/analysis-parse-fix-test-challenge-replay.mdmarkdown1.5 KB
references/attention-budget-ratchet.mdmarkdown13.7 KB
references/attribution-verification.mdmarkdown4.4 KB
references/bootstrap-slim-c3-obligation-table.mdmarkdown8.0 KB
references/correction-routing-map.mdmarkdown3.7 KB
references/coverage-exhaustion-traps.mdmarkdown19.6 KB
references/description-authoring.mdmarkdown21.1 KB
references/dual-track-review-gate.mdmarkdown110.6 KB
references/eval-routing.mdmarkdown22.2 KB
references/evidence-card-template.mdmarkdown3.2 KB
references/example-domain-preselect.mdmarkdown4.6 KB
references/external-practice-controls.mdmarkdown45.5 KB
references/extraction-lifecycle-handoff.mdmarkdown6.9 KB
references/extraction-quickstart.mdmarkdown20.2 KB
references/firing-point-placement.mdmarkdown21.3 KB
references/harness-patterns-and-eval.mdmarkdown42.6 KB
references/incident-postmortem-extraction.mdmarkdown28.8 KB
references/l0-l1-l2-routing.mdmarkdown10.3 KB
references/online-skill-review.mdmarkdown6.7 KB
references/parallel-stack-references-pattern.mdmarkdown35.9 KB
references/r0-leakage-audit.mdmarkdown19.9 KB
references/recurring-anti-patterns-checklist.mdmarkdown34.4 KB
references/resume-paused-delivery.mdmarkdown3.0 KB
references/review-feedback-mining.mdmarkdown5.7 KB
references/review-finding-standards.mdmarkdown7.3 KB
references/review-rubric.mdmarkdown3.1 KB
references/rule-consolidation.mdmarkdown38.2 KB
references/skill-listing-budget.mdmarkdown1.7 KB
references/source-register.mdmarkdown1.0 MB
references/source-to-skill-extraction.mdmarkdown109.3 KB
references/two-source-extraction-pattern.mdmarkdown19.4 KB
references/uiux-judgment-extraction.mdmarkdown19.1 KB
references/uiux-routing-map.mdmarkdown5.8 KB
references/validation-and-landing.mdmarkdown46.9 KB
scripts/AGENTS.mdmarkdown635 B
scripts/check-ccl-skills.shexecutablescript100.7 KB
scripts/check-contract-anchors.shexecutablescript5.6 KB
scripts/check-evidence-card-leak.shexecutablescript26.1 KB
scripts/check-mr-target-freshness.shexecutablescript9.4 KB
scripts/check-size-budget.shexecutablescript36.0 KB
scripts/check-sync-pointers.shexecutablescript22.6 KB
scripts/check_review_evidence_present.pyexecutablescript4.6 KB
scripts/contract-anchors.tsvother3.8 KB
scripts/entrypoint_form_census.pyexecutablescript7.1 KB
scripts/eval-golden-trace.rbexecutablescript10.0 KB
scripts/eval-health.rbexecutablescript14.6 KB
scripts/eval-routing-bank.rbexecutablescript30.4 KB
scripts/eval-routing.rbexecutablescript9.2 KB
scripts/extraction_review_gate.shexecutablescript1.8 KB
scripts/gate_receipt.pyexecutablescript24.7 KB
scripts/generic-r0-leak-scan.shexecutablescript12.4 KB
scripts/governing-chain-diff.pyexecutablescript12.8 KB
scripts/impact-chain-gate.rbexecutablescript124.4 KB
scripts/obligation-ledger.pyscript107.0 KB
scripts/reference-access-census.shexecutablescript8.3 KB
scripts/register-firing-path-resolution.rbexecutablescript48.4 KB
scripts/shared_git_surface_gate.pyexecutablescript38.0 KB
scripts/skill-behavior-eval.pyexecutablescript39.3 KB
scripts/skill-paired-eval.pyexecutablescript76.9 KB
scripts/source-register-lifecycle.rbscript1.5 KB
scripts/source-register-pending-status.rbscript2.0 KB
scripts/test_ai_coding_implementation_gates.shexecutablescript85.2 KB
scripts/test_antipattern_grep_panel.shexecutablescript3.2 KB
scripts/test_body_compliance_grading.shexecutablescript21.0 KB
scripts/test_check_ccl_impact_chain_refscripts.shexecutablescript145.1 KB
scripts/test_check_ccl_r0_status.shexecutablescript4.2 KB
scripts/test_check_ccl_register_pending_exclusion.shexecutablescript7.4 KB
scripts/test_check_ccl_regressions.shexecutablescript14.3 KB
scripts/test_check_ccl_route_drift.shexecutablescript22.6 KB
scripts/test_check_ccl_size_budget.shexecutablescript59.5 KB
scripts/test_check_ccl_skill_catalog.shexecutablescript23.3 KB
scripts/test_check_ccl_source_register_lifecycle.shexecutablescript6.1 KB
scripts/test_check_contract_anchors.shexecutablescript7.4 KB
scripts/test_check_mr_target_freshness.shexecutablescript12.8 KB
scripts/test_check_review_evidence_present.shexecutablescript4.3 KB
scripts/test_check_sync_pointers.shexecutablescript32.5 KB
scripts/test_ci_checkout_ref_binding.shexecutablescript8.2 KB
scripts/test_controlled_escalation_pins.shexecutablescript7.7 KB
scripts/test_entrypoint_domain_scan_terms.shexecutablescript8.8 KB
scripts/test_entrypoint_form_census.shexecutablescript6.3 KB
scripts/test_eval_routing_bank_grader_diagnostics.shexecutablescript20.6 KB
scripts/test_eval_routing_bank_resolution.shexecutablescript15.3 KB
scripts/test_eval_routing_bank_surface_binding.shexecutablescript6.9 KB
scripts/test_eval_routing_prose_target.shexecutablescript3.7 KB
scripts/test_eval_runtime.pyexecutablescript43.3 KB
scripts/test_extraction_review_gate.shexecutablescript15.2 KB
scripts/test_frozen_case_sanctity.shexecutablescript6.9 KB
scripts/test_frozen_case_sanctity_selfproof.shexecutablescript4.6 KB
scripts/test_gate_receipt.shexecutablescript17.7 KB
scripts/test_generic_r0_leak_scan.shexecutablescript6.4 KB
scripts/test_git_identity_predicate_gate.shscript13.8 KB
scripts/test_governing_chain_diff.shexecutablescript15.1 KB
scripts/test_impact_chain_gate_dateless_host.shexecutablescript6.8 KB
scripts/test_impact_chain_gate_verdict_differential.shexecutablescript20.8 KB
scripts/test_impact_chain_round_attribution.shexecutablescript32.5 KB
scripts/test_impact_chain_self_adjudication.shexecutablescript31.4 KB
scripts/test_impact_chain_source_refuted.shexecutablescript14.7 KB
scripts/test_liveness_predicate_gate.shexecutablescript14.5 KB
scripts/test_locale_independent_gates.shexecutablescript13.0 KB
scripts/test_obligation_ledger.shexecutablescript94.9 KB
scripts/test_obligation_ledger_repo_audit.shexecutablescript2.7 KB
scripts/test_pinned_phrase_mutation_walk.shexecutablescript6.5 KB
scripts/test_reference_access_census.shexecutablescript17.3 KB
scripts/test_register_firing_path_resolution.shexecutablescript41.0 KB
scripts/test_register_firing_path_wiring.shexecutablescript29.9 KB
scripts/test_regression_runner_lanes.shexecutablescript4.5 KB
scripts/test_regression_runner_registration.shexecutablescript1.5 KB
scripts/test_routing_bank_integrity.shexecutablescript15.5 KB
scripts/test_routing_pointer_integrity.shexecutablescript18.9 KB
scripts/test_shared_git_surface_gate.shexecutablescript76.8 KB
scripts/test_skill_paired_eval.pyscript60.0 KB
scripts/test_teardown_guard_pins.shexecutablescript17.0 KB
scripts/test_uiux_delivery_contract.shexecutablescript118.6 KB
scripts/test_uiux_loading_budget.shexecutablescript15.4 KB
scripts/test_validate_skill_credential_cwd.shexecutablescript2.6 KB
scripts/test_validate_skill_cross_refs.shexecutablescript4.8 KB
scripts/test_validate_skill_root_depth.shexecutablescript2.5 KB
scripts/validate-skill.shexecutablescript10.5 KB

references/external-practice-controls.md

View on GitHub
# External Practice Controls

This note records the public evidence boundary for three shared controls. It is a design comparison, not a claim that these skills implement PRISMA, NIST, in-toto, SLSA, or any vendor runtime specification.

## Research coverage

Primary and official sources:

- [OpenAI Deep research guide](https://developers.openai.com/api/docs/guides/deep-research): research prompts should be sufficiently specified; source priorities should be explicit; scientific work should prefer original papers or official publications; citations and source metadata make results reviewable; private inputs and public-web retrieval are separate source surfaces.
- [PRISMA 2020 checklist](https://www.prisma-statement.org/s/PRISMA_2020_checklist-ab3g.pdf): a systematic review reports its question, eligibility criteria, information sources, search strategy, selection method, data items, and risk-of-bias method.
- [Cochrane Handbook, Chapter 4](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-04): high-certainty reviews plan broad, documented searches across multiple source types; it also records the counterpoint that abbreviated searches can be acceptable when decision-makers explicitly accept lower certainty.
- [UK government institutional-analysis guidance](https://www.gov.uk/government/publications/understanding-institutional-analysis/understanding-institutional-analysis): triangulation should use different sources and perspectives, not repeated claims derived from one powerful informant or document.
- [CIA Tradecraft Primer](https://www.cia.gov/resources/csi/static/955180a45afe3f5013772c313b16face/Tradecraft-Primer-apr09.pdf): information-quality checks, competing hypotheses, and contrarian techniques make disconfirming evidence an explicit analysis surface.

Disposition:

- Supported: define the question and source classes before retrieval; do not let supplied material silently become the whole boundary; prefer primary/official evidence for load-bearing claims; triangulate independently; search for contradictory evidence; record unresolved cells and lower confidence/coverage claims.
- repository control, not an external mandate: the four visible rows (`user leads`, `primary/official`, `independent external`, `counter/negative`) are this skill's minimum for a result labelled complete/deep. PRISMA and Cochrane do not prescribe those exact four rows for every research domain.
- Boundary: PRISMA/Cochrane are systematic-review methods, so this skill borrows their question/source/search/closure discipline without claiming formal systematic-review compliance. Simple facts and explicitly scoped rapid/partial research stay outside the complete/deep label; a nonexistent user-lead class is closed as `not-applicable`, not fabricated.

## Leaf delegation

Primary and official sources:

- [NIST SP 800-53 Rev. 5, AC-6](https://doi.org/10.6028/NIST.SP.800-53r5): users and processes receive only the authorized access needed for their assigned task; privileged-function use is logged.
- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html): enforce least privilege, deny by default, and prefer explicit configuration over framework defaults that can change.
- [OpenAI Agents SDK tool controls](https://openai.github.io/openai-agents-python/tools/#conditional-tool-enabling): `is_enabled` can hide a disabled tool from the model at runtime.
- [Anthropic subagent documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents): tool allow/deny lists restrict a worker's effective capabilities. The same page is important counterevidence to stale assumptions: current versions allow nested subagents, with a fixed host depth limit, whereas older versions did not.

Disposition:

- Supported: enforce a leaf role by removing the delegation capability when the host permits it, verify the effective tool set, log/observe privileged attempts, and fail safely when neither denial nor observation is available.
- repository control, not a vendor requirement: `can_delegate=false`, promotion to orchestrator, and whole-return invalidation after a prohibited nested attempt are local containment rules. They deliberately remain stricter than a host's built-in nesting support.
- Boundary: host behavior is versioned. Resolve the live host capability instead of writing a timeless claim that a named host can or cannot nest; a host depth limit does not replace the controller's role-specific admission decision.

## Behavioral evidence and attestation

Primary and official sources:

- [in-toto Statement v1](https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md): an attestation statement binds a predicate to immutable subjects identified by digest.
- [SLSA v1.2 provenance](https://slsa.dev/spec/v1.2/provenance): provenance describes where, when, and how an artifact was produced so a verifier can trace it through a supply chain.
- [Open Policy Agent policy testing](https://www.openpolicyagent.org/docs/policy-testing): policy tests exercise decisions, while coverage reports identify rules whose bodies were never true or expressions never evaluated.

Disposition:

- Supported: a rule's existence is not proof it executed; use behavioral assertions and coverage/firing evidence. The digest-binding practices these sources describe (complete subject sets, provenance, raw-result digests) are sound for supply-chain trust boundaries where authors and verifiers are distinct parties; the local policy below explains why this repository adopts the firing/coverage principle but not the digest binding.
- Local evidence policy: the impact-chain gate machine-verifies what is cheap and deterministic — an owner-scoped firing path that resolves to its round's added lines (a unique anchor on a changed normative numbered/list rule or table data cell, or a changed owner executable), the letters/digits-free wording-only classification computed from that round's owner diff, and the owner-level floor that a non-wording package carries at least one `RED-baseline` row (a `semantic-control` label may supplement but never close a package alone, because an author-selected stable label cannot vouch for a different hidden delta). The `behavioral-evidence` and `observed-failure` fields themselves are required author declarations. A digest-bound attestation apparatus for these rows (in-toto-style subject digests, same-prompt model result pairs, command-result envelopes) was built, evaluated against real iteration, and deliberately removed: under the unsigned-repository-local trust model the author can regenerate every hash, so the apparatus only detected stale records — while costing a full-suite rerun and whole-evidence regeneration whenever any owner script changed by a single byte. That cost defeated normal multi-commit iteration (it broke its own author's branch twice), so behavior claims rest on the firing-path gate, honest authorship, and the mandatory independent review/challenge instead of hashes.
- Local trust model: register rows remain honest-but-fallible workflow evidence, not a hostile-author security boundary. The gate proves that a changed owner-scoped rule or table data line (or changed owner executable) exists for every claimed firing path; it does not prove a model run occurred, that a named executable implements the claimed enforcement (a shebang stub passes the static check), that a mangled or ambiguous ledger row was honest (those are warned, not blocked, to avoid false positives on other table shapes), author identity, or non-tampering by an authorized contributor. Independent review/challenge and the fixed checker remain the assurance case.
- Machine format (relocated from the `SKILL.md` firing-mechanism rule; the local evidence policy above carries the rationale): every added source-register row must carry `behavioral-evidence: RED-baseline` (any observed delta — `observed-failure: yes` requires it) or `semantic-control` (only with `observed-failure: no`), an `observed-failure: yes/no` state, and an owner-scoped `firing-path` — each declaration in its own semicolon-delimited fragment of the cell (`…prose; behavioral-evidence: …; observed-failure: …; firing-path: …`), so a key embedded mid-prose never parses as a declaration. The firing-path anchor is at least 16 characters, occurs once in the file and once in its round's added lines, and lands on a numbered/list Markdown rule with a normative action or a data cell in an explicit Markdown table with a header and delimiter. A table anchor must also be absent from the round's base file; changing only a source link cannot reuse the old definition as evidence. Table headers, delimiters, comments, code examples, and HTML blocks are not definition anchors. The source register itself cannot be a file firing path: evidence does not certify itself. The table check establishes the changed location, not the definition's factual accuracy. A row that survives at HEAD must also resolve to an owner this range actually changes — an owner reverted to its base bytes by a rebase or a base-side conflict resolution leaves the changed set while its row stays behind, and the row then vouches for a change the delivered diff does not contain. There is no author-declared escape from this: a corrective rewrite that back-fills a row for a round which merged red produces the same shape, and it is a deliberate, person-adjudicated repair that can adjudicate this refusal too.

- **Round scoping — a row is judged against the round it landed in, never the accumulating range.** A row is authored against one round's diff, so reading the whole `base..HEAD` range to classify it judges the row against work it never described. That mismatch produced both directions of the same defect: an already-gated row turned red once a LATER round touched the same owner (which is what the ledger's superseded-row notes were absorbing), and a description-only round lost its routing-surface locator because an EARLIER round had edited that owner's body. The gate cuts rounds at the commits that touch the ledger along a first-parent line, and each round spans from the previous boundary so work commits sit in the round whose ledger append describes them. A merge that git rebuilds from its two parents is expanded into its branch's own rounds, so a merged worktree round is judged exactly as its pull request was — the same history must not partition differently after it lands; a merge git cannot rebuild (a hand resolution, a conflict) keeps a single boundary at the merge, so content that came from neither parent is never left in no round. The partition is derived from git alone — an author cannot nominate, widen, or move their own scope.
  - Both obligations move together, in opposite directions. **Classification** narrows to the round: whether a diff is wording-only, an identifier retarget, or description-only is asked of that round's bytes, which is what makes a verdict stable once it lands. **Presence** narrows to the round too: the round that changed an owner is the round that owes the row, so owner work committed after a ledger append can no longer ride on an earlier round's row. Narrowing classification without narrowing presence would have opened exactly that laundering route.
  - **Known exception, inherited not introduced: a renamed-away owner escapes round presence.** The round's subject set is intersected with the cumulative one, and the cumulative pass drops an owner whose package was renamed away (a row citing it would be refused for naming a SKILL.md that no longer exists). So an owner changed substantively in an earlier round, with an intervening ledger boundary that closed that round without its row, and renamed away in a later round, is demanded by neither round. Differential check on the same fixture: the pre-round-scoping gate passes it too, so this is not a regression of the narrowing — but the per-round presence contract above does not hold in this shape, and saying so is the point of this bullet. Closing it needs the evidence-file existence check to resolve at the row's round head instead of the worktree, which is its own change.
  - The owner-level `RED-baseline` floor deliberately stays **cumulative**: it asks whether anything in the owner's whole change is left unvouched-for, and per-round would let a package self-clear on the one round that happened to be punctuation-only. Cumulative is the stricter of the two readings, so the round scoping cannot loosen it.
- Machine-verified no-behavior classes (each drops the firing-path requirement, each requires `observed-failure: no`, and neither is an author waiver — the gate recomputes the predicate from the owner's diff for that row's round and refuses on any mismatch): `not-required wording-only` when no changed line differs by a letter or digit and every changed owner file is Markdown prose; `not-required identifier-rename` when rewriting the base bytes with git-derived rename pairs reproduces the head bytes exactly. Both exist because the anchor uses the SHAPE of a changed line as a proxy for "an obligation changed", and both are diff shapes that carry no obligation at all.
- Retiring an owner into a successor. A merge removes an upstream owner without renaming it: its content moves into another package, git reports a deletion with no rename pair, and a row may not cite a `SKILL.md` its round head no longer has. The successor's row must declare it with a `retires: <slug>[, <slug>]` fragment in the declaration cell; without that fragment the deleted owner stays a demanded subject and the round fails closed, exactly as an undeclared deletion does. The gate honours the fragment only on a declaring row bound to a successor that survives at the round head, for a selectable owner whose `SKILL.md` existed at the round base and is gone at the round head, and only when the successor package gained this round at least one non-empty blob the retired package carried (a blob both packages already shared at the round base does not count); a fragment that fails any condition blocks rather than being ignored. A third owner whose whole change replaces a retired slug with its successor may then declare `not-required identifier-rename`: the gate rewrites whole retired identifiers in the base bytes with the verified pairs and requires the head bytes to equal that rewrite, or the rewrite of a base in which each run of whole mentions joined only by a prose list separator (comma, spaced slash, "or", "and") and containing at least one retired slug was first collapsed to one successor mention, because several retired slugs map onto one. The head is never normalised, so writing the successor twice in a path or value still fails, a slug that continues into a longer name is not a mention, and the owner's package must keep the same files and modes. The fragment proves that a deletion was declared and that content moved; it does not prove that every obligation of the retired owner survived — that is the zero-loss map and the independent review. An owner deleted with no successor has no declaration and keeps failing closed.
- Canonical field locator for a routing-surface-only owner — NOT a third no-behavior class. When an owner's entire change is the `SKILL.md` frontmatter `description` entry (same body, same other top-level keys, the value still a YAML string, all checked byte-exact), its firing path is the constant `file:skills/<owner>/SKILL.md#description`. The row still declares `RED-baseline`, still owes its behavioural evidence — for a routing change that is the measured routing delta — and only the free-text anchor is replaced. It is deliberately not an exemption: a description edit decides which requests reach the skill, so exempting it would drop evidence from the class carrying the most behaviour. The locator is canonical rather than a substring because three successive substring designs were refuted — a numbered/list rule shape, then the `description:` line, then any line of the entry — the last because a substring that merely SURVIVES the edit identifies nothing. Same class three times is the signal to drop the proxy, not to patch it again; the predicate is what carries the proof, and the locator only names the field it proved. The predicate matters more here than in the two classes above because a wrong judgement is LOOSER rather than stricter, so it accounts for every changed byte and refuses whatever it cannot account for. A further shape that cannot be located is a signal to replace the proxy, not to widen again. The precondition judges BEHAVIOUR, not file count: the rest of the package — and the entrypoint's own body and other frontmatter keys — may differ by a rename retarget, because that is already a machine-proven no-behaviour class, and the two compose under one normalizer (apply git's rename pairs to the base bytes, then require the head bytes exactly, mode included). Without the composition an owner on an integration branch that accumulates rounds gets refused for retargets it already declared no-behaviour, while having no other rule to anchor on. The description entry is the one part exempt from the normalizer, because it is the change being evidenced; anything the normalizer cannot account for — one real byte — takes the locator away. Siblings are further restricted to regular-file Markdown: a script's bytes reproducing under a substitution says nothing about whether rewriting that identifier was safe there, and a `.md` SYMLINK's blob is its target, so a retargeted target reproduces while what the path resolves to changes. **Disclosed residual, unchanged from the rename class it composes with**: a Markdown sibling can still carry a fenced command or a persisted key whose old identifier is deliberately preserved — an installed artifact name that must not follow a source rename is the observed instance — and rewriting one of those IS a behaviour change the normalizer clears. The exposure is identical to the identifier-rename class, which already reproduces whole packages under the same pairs; this composition inherits that residual rather than widening it, and the pairs still come only from git's own tree state, so a slug is rewritten only when that skill was actually renamed in the same diff. Closing it means distinguishing prose mentions from executable/persisted ones inside Markdown, which needs its own evidence round. Two shapes are knowingly left refused, and refusal here costs nothing that was not already lost: before this locator existed no routing-surface owner could satisfy an anchor at all, so a refused shape simply keeps that prior behaviour rather than regressing from it. (1) A sibling frontmatter value whose YAML tag or class `safe_load` will not construct makes the parse fail, and a failed parse refuses rather than guesses. (2) The owner that ships `references/source-register.md` cannot use the class at all, because its own evidence row lands inside its package and so its diff is never the description alone — a consequence of not special-casing that file, which is what would otherwise let arbitrary ledger content ride along. Both are usability limits on a strictly additive path, not bypasses; closing either one means loosening a predicate whose wrong answers are LOOSER than the bar, so neither is worth doing without its own evidence.
- Boundary: OPA coverage supports the general distinction between policy presence and policy execution; the repository does not run OPA. in-toto/SLSA supply-chain formats were consulted for the evaluated-and-removed digest apparatus; the shipped gate deliberately does not bind digests and does not reuse or claim their security levels.

### `source-refuted` — withdrawing a claim a primary source refutes

A rule can fire perfectly and still be false. Removing such a claim usually produces **no measurable behavioural delta** — there is nothing for a `RED-baseline` to capture — while `semantic-control` is refused by the owner-level RED floor. Before this class existed the cheapest path was therefore to *leave the false claim in place*, which is the wrong incentive.

The class is not a waiver; it swaps one kind of evidence for another. All four bars are machine-checked and a row fails without any of them:

1. `observed-failure: no` — this gate asks whether the owning rule failed to *fire*; a withdrawn claim fired fine, it was simply wrong. Self-declaring `yes` cannot use this class.
2. The evidence cell cites a **primary source that refutes the claim** (a URL).
3. The evidence cell carries a pointer to a **zero-loss obligation map** that is a git-tracked regular `.md` inside the repository (no absolute path, no `..`, mode `100644`), whose **anchor resolves to an actual heading** — not merely to a substring, or `#a` would pass on any file containing the letter — and the map **quotes verbatim every substantive line the round deleted**. That last bar is what binds the pointer to the withdrawal itself: to remove a real obligation you must first copy it into the map, where a reviewer sees it.
4. The owner's round diff is a **pure deletion**, classified structurally rather than by line text: every changed path is a regular `.md` under that owner, every path's status is a modification, **both tree modes are `100644` and identical**, and the diff adds **zero** lines while deleting at least one. Read the modes from `--raw`, not `--name-status`: a `chmod` shows up as a plain modification there and contributes `0/0` to `--numstat`, so a mode change would otherwise ride along with a genuine deletion. Two earlier drafts used proxies — a net-byte floor, then "adds no normative rule line" — and adversarial review broke both: the first by offsetting a smuggled rule with unrelated deletions, the second because a script edit or an `Always`-phrased rule matches no prose predicate. A proxy for the invariant gets bypassed; the invariant itself does not.
5. **Every** row for that owner in the round is in this class. A lone compliant withdrawal must not lift the floor for a sibling row carrying a real change.

Because a withdrawal is a pure deletion it has no added line to anchor on, so this class drops the firing-path requirement exactly as the two `not-required` classes do. Write the explanation of *why* the claim was withdrawn into a reference, not beside the line being removed — an inline note is an added normative line and bar 4 refuses it.

These bars are **mechanical floors, not proof**: they cannot bind the cited source to the specific obligation withdrawn. The zero-loss review in the dual-track gate remains what catches that, and this gate does not pretend to replace it.

**This class does not lift the per-owner RED floor.** Seven independent review rounds broke every successive bar built to make an automatic lift safe — a net-byte floor, a normative-line heuristic, a status-letter check, a file-exists check, a substring anchor, and finally a well-formed-but-unbound pointer — and two lanes twice recommended not granting the lift until the pointer can be bound to the obligation actually withdrawn. The residual gap is not machine-checkable in principle: a pointer can resolve to a real heading and quote the deleted text verbatim while the cited source has nothing to do with the claim. So the class does what a machine can do — force an honest label, a real obligation map, and a genuinely pure deletion — and leaves the judgement where it belongs: a withdrawal still needs a `RED-baseline` row, or a named risk owner's waiver through the existing human channel.

## Designing a behavioral-evidence measurement

A `RED-baseline` row is only as good as the measurement behind it. The failure modes below were each observed while measuring one small skill change; **all of them biased the same way — toward "the change worked" and "the measurement is sound".** That is the tell: when the person designing the measurement is the author of the change being measured, design errors are not random.

**The one rule that matters: the grading standard must precede the change.** Not "write the rubric carefully afterwards" — afterwards you already know what the new text says, and the rubric grows into its shape. Either freeze the rubric before editing, or have a party that has not seen the candidate produce it. This repo already applies preregistration to *dispositions* (a preregistered reading rule committed before any run); apply it to the *instrument* too.

**Its companion: the baseline must be one the thing under test cannot have moved.** A rubric frozen before the change still grades against *something*, and rubric discipline says nothing about whether that something held still. A baseline the candidate can write, a baseline read while another writer is mid-flight, a baseline ref that has drifted, and a baseline that was never established all produce a well-formed comparison with no anchor — and none of them announces itself. The first four rows below are that failure; the rest is hygiene. Every row was observed failing:

| Failure | What it looked like | Rule |
| --- | --- | --- |
| Candidate-writable baseline | The reference the gate compared against was committed inside the same change-set the gate then judged, so the change could move its own reference point | The baseline must resolve to an immutable commit or frozen artifact **that the change did not author** — immutability is not independence. A candidate can commit a tuned fixture and cite that commit's SHA: perfectly immutable, still its own reference point. Require provenance older than the change (an ancestor of the merge-base with the target, or an artifact under separate control), and never a bare ref name (a ref is as movable as a file, so creating or re-pointing one satisfies "an explicit target ref" while moving the reference point). What is barred is the candidate's **working-tree** version of a file its diff touches; the **pre-change blob of that same file, read at an independent commit**, is the correct control arm — that is what `Transcribed arms` below means by extracting both arms from version control. A fixture authored alongside the change is self-authored evidence, and the **weaker ancestry check some harnesses run — verifying that the artifact *declares* an ancestor commit, rather than that the artifact itself predates the change — does not detect one tuned in that same change** (`validation-and-landing.md` records this for the golden-trace form). Requiring the artifact's own provenance to predate the change is what closes that hole; the declared-ancestor check alone does not |
| Baseline read under a concurrent writer | A suite total was recorded while a mutation harness was still rewriting the tree, then reused as the stable prior; a size reading taken in a worktree holding a staged revert produced the opposite conclusion from the truth | Prefer a baseline that **cannot** move while you read it — but **naming an immutable source is not reading from one**: a suite or size command run in the live worktree consumes staged edits, generated files, and a sibling agent's writes while the record says the baseline was commit X. Read the baseline *out of* the immutable source — check it out into a clean location, or read the blob at that commit — and only then is a dirty candidate worktree irrelevant to it. For a genuinely *mutable* source the requirement is that nothing writes it **for the duration of the read** — quiesce the writers (stop the harness, watcher, or sibling agent; settle staged state) rather than sampling cleanliness, because a point-in-time `git status` says nothing about the next second — or label the reading `unstable` and do not let it serve as a baseline |
| Base ref drift | The comparison resolved against a stale local ref, so the packet carried the upstream's newer fixes *reversed* and the reviewer raised findings against code that was already correct | Resolve the base at read time and prove it is current before comparing. A finding pointing at a file outside your own diff should trigger a base check **before you act on it either way** — do not rank the two: it is equally often a real completeness defect (an untouched consumer the changed contract broke), so verify the base rather than dismissing the finding |
| Attribution with no base run | A red was reported as this change's regression; the identical failure reproduced on the unmodified base and was a pre-existing environment condition | Reproduce a failure on the unmodified base before attributing it to the change — "also red on base" is a result to record, not a step to skip (`product-rd-workflow/references/refactoring-discipline.md` owns the green-baseline-first form) |
| Ceiling | The unchanged arm already passed 9/10, so no improvement was detectable | The arm you expect to fail must be *able* to fail; verify before comparing |
| Vocabulary inheritance | Regex written after the new text; the old arm said the same thing in other words and scored 0 (`剥离` vs a regex for `剥掉`) | Grade the **obligation**, paraphrase-tolerant, by a grader blind to which arm produced the answer |
| Tautology by construction | A "marker must be uniquely carried by this line" rule forced markers that only that line's vocabulary could satisfy — removing the line trivially removed the word | A validity constraint built for one polarity becomes a bias generator in the other: uniqueness is required of the **control**, never of the candidate (other carriers are the redundancy evidence, not an artifact) |
| Underpowered null | n=3 nulls recorded as findings; one flipped to a large effect at n=10 | Nulls need power and replication; large separations survive small n, nulls do not |
| Cross-run drift | Identical inputs, same n, unchanged arm scored 2/10 and 6/10 in two runs | Replicate; report the spread, never a point estimate |
| Transcribed arms | The "old" arm was hand-copied and did not match the real prior text; it inflated the effect | Extract both arms from version control |
| Slice inflation | Removing one line from a 22-line excerpt overstates its weight versus the 338-line artifact | Use the whole artifact, or report both readings |
| Post-hoc analysis change | Verdict logic was changed after an unwelcome result | Freeze thresholds and decision order with the rubric; if changed later, publish the full sensitivity grid, never the favourable cell |

**Proving a removal is harmless is not the mirror of proving an addition helps.** An addition is evidenced by a difference; a removal is evidenced by an *absence* of difference, which is indistinguishable from an instrument that detects nothing. So a deletion claim needs a **positive control** — remove something known to carry an obligation and show that obligation's satisfaction actually drops. Better still, remove two candidates in the same run so each is the other's control: a double dissociation (removing A drops only A's obligations, removing B only B's) validates the instrument and both verdicts at once.

## Instruction-following mechanisms

Referenced from `SKILL.md`'s "The mechanism underneath" rule. This section holds the withdrawn predecessor, the sources, and their evidence grade; the entrypoint holds only the operative rules.

**Withdrawn (do not cite).** An earlier version said: *prose rules do not reliably co-fire — at any single decision point the agent tends to actively apply roughly the ONE most-salient rule*, with the corollary that *appending a bullet does not ADD compliance — it competes for, and can displace, the same salience slot*. Neither vendor's guidance nor any public benchmark supports a winner-take-all salience slot, and the corollary is contradicted outright: OpenAI's guidance is that a single unequivocal sentence is usually enough to steer the model. The claim rested on one session's self-observation.

**Sources and what each actually supports.**

| Source | What it gives | Evidence grade |
| --- | --- | --- |
| [Anthropic, *Effective context engineering for AI agents*](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | finite attention budget; "context rot" reported as gentler in some models but emerging across those tested; smallest-set-of-high-signal-tokens; the right-altitude failure modes | vendor engineering post — no dataset, n, or error bars; version-bound; commercially aligned with context-management tooling |
| [OpenAI, *GPT-4.1 Prompting Guide*](https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide) | conflicting instructions tend to resolve to the one nearer the end; instructions at both ends of long context beat either alone; check-conflicts-first; a single clear sentence usually steers | same class; explicitly model-generation-bound ("GPT-4.1 tends to…") |
| [OpenAI, *GPT-5.1 Prompting Guide*](https://cookbook.openai.com/examples/gpt-5/gpt-5-1_prompting_guide) | check-conflicts-first; a published metaprompt recipe for finding contradictions in your own system prompt | same class |
| [RECAST](https://arxiv.org/html/2505.19030) | joint satisfaction degrades sharply as constraint count grows — and it is already low at small counts. The metric for "all of them at once" is the paper's **OSR** (§4.1: "the HSR of all constraints, both rule-based and model-based, that are successfully satisfied simultaneously"). Across all 29 model rows of Table 1 the **ceiling** on OSR is **25.0** at Level 1, falling to **19.0 / 13.0 / 13.5** at Levels 2–4, whose constraint counts are **5 / 10 / 15 / all** (§B.4). So at five constraints no model held the whole set more than about a quarter of the time, and by fifteen none exceeded ~13% | benchmark paper proposing its own dataset and method — a low baseline flatters the contribution; these are one hard benchmark's order of magnitude, not a usage failure rate, and its constraints are generation-task instruction constraints rather than preconditions of a procedure, so transfer is by analogy. **Citation corrected 2026-08 against Table 1:** the widely quoted 39.75% is the **Average column of the single best-by-average row** (Gemini-2.5-Pro) — the arithmetic mean of that row's twelve MSR/RSR/OSR cells (sum 477; 477/12 = 39.75, confirmed) — **not** an all-constraints-satisfied rate, and it must not be cited as one. The two orderings differ: Gemini leads on Average while Qwen3-235B-A22B holds the highest Level-1 OSR, so do not carry "best model" across from one column to the other. Cite the OSR ceilings above |
| [IFScale](https://arxiv.org/abs/2507.11538) | instruction-following accuracy degrades as instruction density rises (500 keyword-inclusion instructions; best frontier model 68% at max density across 20 models / 7 providers); three degradation shapes correlated with model size and reasoning; a **bias toward earlier instructions** (primacy), and omission as a distinct error category | benchmark paper on a synthetic keyword-inclusion task — density and primacy transfer by analogy only; it measures a list of independent constraints, not a procedure's preconditions; note it reports primacy where the vendor guides report recency, so position is a bias with no single direction |
| [AgentIF](https://arxiv.org/abs/2505.16944) | real agent system prompts (707 instructions from 50 applications) average 1,723 words and 11.9 constraints; the best model followed fewer than 30% of them perfectly, adherence fell as instructions grew longer, and condition and tool constraints were the hardest | benchmark paper on production-shaped prompts — the closest public analog to a loaded skill body, but it scores one response per instruction, not a multi-step procedure |
| [Context Length Alone Hurts LLM Performance Despite Perfect Retrieval](https://arxiv.org/abs/2510.05381) | with every relevant token retrievable, accuracy still fell 13.9–85% as input grew within the advertised window, even when the added tokens were whitespace or masked; reciting the relevant evidence before answering recovered part of it | 5 models on math, QA and code — supports "length itself costs attention", not any particular budget figure |
| [SkillsBench](https://arxiv.org/abs/2602.12670) (§6, App. F, Tables 8–9) | curated Skills raised an 87-task pass rate from 33.9% to 50.5% across 18 model–harness configurations; by SKILL.md size bucket the lift was compact +19.0, standard +21.5, detailed +14.5 and comprehensive +0.7 points, and by Skills per task 1 / 2–3 / ≥4 gave +18.0 / +19.0 / +10.1; where Skills hurt, the paired-trajectory audit found a heavyweight pipeline crowding out a simpler path, a generic recipe displacing a stronger native strategy, or a brittle framework the agent could not debug; in the three configurations that tested self-generated Skills, they fell below the no-Skills baseline | observational on size and count (task and Skill are confounded, the comprehensive bucket has five tasks) on terminal-based tasks whose authors flag long-horizon workflows as possibly not transferring — a direction to test here, not a budget |
| [SkillJuror](https://arxiv.org/abs/2606.11543) | holding the knowledge fixed, a concise root that points to on-demand resources versus one flat file raised distinct resources touched per trajectory from 1.18 to 3.85 and added 17 verifier-passing trials of 410 (+4.1%); it helped where resources guide implementation, checking or repair and was weaker where success hinges on exact output conventions, numerical thresholds or long artifact pipelines | controlled variants on 82 tasks — organization changes how the agent searches before it changes outcomes, and the outcome gain is small and task-dependent |
| [Skill availability and presentation granularity](https://arxiv.org/abs/2605.31408) | having the Skill raised task-mean pass rates by 18–36 points, while moving the same guidance between abstraction levels or adding one worked example changed them by −6.7 to +1.3 points (both abstraction contrasts' bootstrap intervals cross zero) | controlled, 30 tasks × 2 models × 5 trials — do not expect a rewording of the same knowledge to move outcomes measurably |
| [Anthropic, *Prompting best practices*](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) | newer Claude models follow the system prompt more closely, so prompts written to stop tools or skills under-triggering may now over-trigger; the fix is to dial back aggressive emphasis ("CRITICAL: You MUST use this tool when…" → "Use this tool when…") | vendor guidance bound to named model generations; not yet measured against this repository's process-heavy skills |

**Why recency is a hazard, not a rule.** Vendor guidance reports that models *tend to follow* whichever instruction sits later — an observation about behaviour, not a licence to resolve conflicts by position. Two ways position becomes dangerous if read as a rule: a later permissive line beats an earlier stricter one (directly contradicting `Conflict Resolution`, which keeps the stricter data-loss/security/contract guard); and text embedded in **untrusted data** — a diff under review, a retrieved document, tool output — sits later within the same authority level and would win by placement alone, which is prompt injection with extra steps. Treat recency as a bias to design against: put the load-bearing rule where the decision happens, and never let placement confer authority.

**How to use them.** Vendor guidance and benchmarks are **hypotheses with good provenance** — they tell you what to test on your own corpus, they do not substitute for testing it. Citing them as settled is the same error as landing an unverified claim; so is overruling one with an underpowered probe.

## 继承的约定读法:失败形态

一道建立在**继承来的错误读法**之上的闸——把 `AGENTS.md` 读成存在「根索引」要求(实际并不存在)——在多轮 dual-track 里以不断打补丁的方式存活,直到用户问「参考网上优秀实践了么」,一手源(nearest-file-wins)才证伪了整个前提。

教训:前一个 agent 或前一次提交对某个具名约定的读法是 **hypothesis-grade**;在其之上 fix-forward 会把原始错误一并传播。

### 同类的最高频实例:CLI flag 靠记忆不靠读

上面那条讲的是**继承自别人**的读法;本节讲**继承自自己记忆**的读法,两者同根——载体都是一个本仓不拥有的外部契约。

`SKILL.md` 已有的规则要求用 live tool(`--help` 或等价物)核验 flag 的存在与语义,但只写在**把 CLI 命令写进 reference 时**这一个作用域。真正复发的地方是**调用**时:一份跨上百个会话的失败记录语料里,「flag 靠猜不靠读」是最重复的机械失败类之一——同一个 `glab mr list --state` 在**八个互相独立的会话**里各失败一次,横跨数月;每次修法都相同(读 help、换 flag),每次都只修好了当次那一条实例,所以类原样返回。同族还有 `--jq`(3 次)、`--output`、`--pipeline-id`、`--branch`、`--old-text`、`--allow-scripts`。

八次复发说明 prose 不收敛,所以落点是机械的:`hooks/remind-unverified-cli-flag.sh`(PreToolUse,仅提示不阻断),对 flag 词表跨版本发散的工具,按 (会话, 工具) 各提示一次;它**刻意不解析命令串**——合法 shell 写法的集合是开放的,早期的解析版本几乎每轮独立评审都被找出一种误处理的合法写法。

**谓词选择是这条里唯一承重的设计决定**:hook 认的是**工具身份**,不是「已知坏 flag」的清单。flag 清单是上游项目拥有的词表,上游每发一版就把控制打回原形——这正是本文件上一节所述「控制建立在自己不拥有的东西上」的形态,也是这个类跨多次落地反复回来的原因。工具名集合缓慢、有限、可由本仓拥有;flag 集合不是。代价是明写的:未列入的工具是**不触发**,这是刻意接受的残留,扩列表的判据是该工具已积累出记录在案的 flag 失败。

### Cross-landing recurrence: the reviewer-isolation instance and the decision record (relocated from `SKILL.md`)

The same predicate-ownership rule has an English-side worked instance and a required record. When a failure class returns in production after a previous landing already "fixed" it, and each prior fix registered the newly-seen value, name, or version on the same predicate rather than changing what the check is predicated on, the second occurrence is already the design signal: re-express the predicate over an **invariant the control owns** (shape, arity, type, or the verified property the check really needs), or accept the maintenance and say so. Either way the landing records a `keep / delete / narrow / replace` decision, **the invariant that took the vocabulary's place**, and **the residual risk accepted by the looser predicate**. Failure shape: a reviewer-isolation gate pinned to an upstream CLI's init field names and enum values took every reviewer lane down on three separate upstream releases; the first two landings each registered the new vocabulary — which guaranteed the third — until the predicate moved to shape.

可执行形态:

- 给列表内的外部 CLI 传长 flag 之前,**必须先在本机读过该 CLI 的 help 输出**;未读过就用,属于把记忆当一手源。
- 一条命令因无法识别的 flag 失败时,**不得**先改用法之外的东西——先怀疑该 flag 在本机这个版本不受支持。语料里多次出现「以为是用法错、其实是这版没这个 flag」。

### 记录半边:把外部契约钉进控制时,同时钉住它的时效

上两节讲**读法**(读一手源、把谓词挂在自己拥有的东西上);这一节讲**记录**。一旦本仓的某个控制**编码了**对外部契约的一次读取——闸强制它、脚本依赖它、recipe 假设它——控制自身必须带三样东西,且写在控制旁边,不是写在 commit message 或某轮私档里:

- **出处到条款级**:读的是哪一份一手源的哪一节,不是「按官方文档」。
- **核验时点与被核对象的版本**:哪天核的、对着工具/宿主的哪个版本或哪个 pin 核的。
- **失效条件**:必须写明什么变化会使这条结论不再成立(pin 的大版本被抬、宿主换了解析链、上游把该字段改成会读的)。

缺这三样,下一个读到该控制的 agent 分不清它是**经过判断的决定**还是**没人敢动的化石**,唯一的复核方式是把整轮外部调研重做一遍——这正是「继承来的读法」能一路存活的原因:不是没人想核,是核一次的代价被隐藏了。三样都在时,复核退化成一次针对性的对照。

- A control whose annotation lacks any of the three must be treated as carrying an unverified reading: the next change to it re-reads the primary source instead of inheriting the claim, and a reviewer must not accept the inherited reading as established merely because the control has shipped for a long time.

判据窄,别泛用:只对**控制依赖的外部契约**成立(宿主/工具/格式/协议的行为)。纯内部不变量不适用;「谁提出的」那一档归 `attribution-verification.md` 的源质量与 pending 语义,与本条不同 facet。

本轮两个活体实例(都是读代码时先撞上「这为什么在这」才发现的):`verify-packed.mjs` 用机械闸禁止 `plugin.json` 带 `version`——这是一条关于宿主版本解析链的主张,落地时正确、但当时没留出处与时点;以及 `check-release-version.py` 依赖 `actions/checkout` 的 `fetch-depth: 0` 会取到 tag。两处已按上述三样补齐。

## 只据内部语料的「深度提炼」:失败形态

一次仅以内部 launch-SOP 为源的「深度提炼」会落出**看起来完整**的规则集,却从未核过这套技能声称代表的**公开实践**;下一个用户于是问「参考网上优秀实践了么 / did you check industry practice」。

判据:凡规则带 state-of-the-art 主张,charter 的 evidence plan 必须含权威外部源类;只编码内部运行约束、且明标内部范围不作行业主张的规则,不受此限。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall