opencode-skills-collection 4.0.56 → 4.0.57

package/bundled-skills/.antigravity-install-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-09-08T01:47:16.781Z",
+  "updatedAt": "2026-09-09T01:53:48.864Z",
   "entries": [
     "00-andruia-consultant",
     "007",
@@ -368,6 +368,7 @@
     "brand-guidelines-community",
     "brand-perception-psychologist",
     "brave-man",
+    "break-ai-fix-loops",
     "brendangregg-use-tsa",
     "brevo-automation",
     "broken-authentication",
@@ -1750,6 +1751,7 @@
     "skill-installer",
     "skill-issue",
     "skill-optimizer",
+    "skill-porter",
     "skill-rails-upgrade",
     "skill-router",
     "skill-scanner",

package/bundled-skills/antigravity-maintainer-batch-release/SKILL.md

@@ -78,6 +78,26 @@ Before changing anything:
    - Verify its managed-only diff, required checks, merge result, and the resulting `origin/main`.
    - If an unmanaged repair remains, use a topic PR; never patch `main` directly.
 
+
+### Reviewed fork bundle exceptions
+
+`tools/config/reviewed-fork-skills.json` is a protected-base ledger for the two
+explicitly reviewed fork contributions #1337 and #1413. Each entry binds the
+base repository, fork repository, PR number, original full reviewed head and
+complete Git skill-tree object. It permits only Python files under that skill's
+`scripts/` subtree and its root `LICENSE`, with a read-only Git copy origin when
+needed. It does not allow workflows, arbitrary script types, generated-file
+mutations, unsafe modes, links, invalid paths/objects or oversized content.
+
+Both CI intake and `merge:batch` load the ledger from their trusted evaluator
+checkout, never the PR's repository directory. Any change anywhere in the skill
+subtree invalidates the exception. A base-only merge may reuse identical content,
+but the maintainer must inspect the new complete PR diff and attest its exact
+current head with `--reviewed-head`. Evidence, source-only checks, truthful skill
+review, immutable PR/workflow binding and strict branch protection all remain
+mandatory. Missing or malformed ledger data fails closed. Further exceptions or
+policy expansions need explicit maintainer authorization and protected review.
+
 ## Workflow Contract Change Gate
 
 When changing maintainer scripts, workflows, or policy, update the canonical skill, maintainer documentation, and regression tests in the same source PR. Add a negative test for every failure mode being fixed, run the relevant dry-run path, and reject any implementation/documentation mismatch. Source PRs must exclude generated registries and plugin mirrors; the protected canonical-sync PR owns that derived state, except for files intentionally staged by the scripted protected-release flow.

package/bundled-skills/break-ai-fix-loops/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-skills/break-ai-fix-loops/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: break-ai-fix-loops
+description: "Stop ineffective AI coding repair loops with stable failure fingerprints, a three-attempt budget, real-path proof, negative controls, and tested rollback."
+category: code-quality
+risk: critical
+source: community
+source_repo: twoicewoo/awesome-copilot
+source_type: community
+date_added: "2026-09-04"
+author: twoicewoo
+tags: [ai-agents, debugging, verification, negative-control, rollback]
+tools: [claude-code, codex-cli, copilot, cursor, gemini-cli]
+license: "MIT"
+license_source: "https://github.com/twoicewoo/awesome-copilot/blob/886bf799bb05501bfd1afa7aae9cc5a77dedb03e/LICENSE"
+---
+
+# Break AI Fix Loops
+
+Replace patch-and-retry behavior with a bounded, evidence-producing repair. Treat a changed patch as progress only when an observable state changes.
+
+## When to Use This Skill
+
+- Use when an AI coding agent cycles through similar patches without changing the observed failure.
+- Use when a focused test passes but the installed, deployed, UI, API, persistence, or other real execution path still fails.
+- Use when a repair claim needs a verifier that can reject a known-bad state and a rollback that has actually restored the baseline on a disposable copy.
+- Do not use for a one-shot, already-understood edit whose acceptance check directly exercises the complete claimed behavior.
+
+## Establish the repair contract
+
+Before the first edit, record:
+
+- the exact defect and the behavior that would disprove it;
+- the revision, configuration, input, and execution path under test;
+- the baseline command, literal result, and exit status;
+- the strongest check that directly observes the claimed behavior;
+- the rollback command and the state it must restore.
+
+Save raw evidence before normalizing it. Redact credentials, tokens, cookies, personal data, and private URLs. Never put secrets into a fingerprint record or committed ledger.
+
+If the defect cannot be reproduced, stop editing. Report `INCONCLUSIVE` with the missing observation instead of guessing at a fix.
+
+## Use a three-attempt budget
+
+Allow at most **three repair attempts for one acceptance claim**. An attempt begins when code, configuration, dependencies, generated artifacts, or test expectations change. Inspections and read-only probes do not consume an attempt.
+
+Do not reset the budget because the agent restarts, opens a new session, rewrites the same patch, changes models, clears a cache, or renames the hypothesis. A newly exposed downstream failure still belongs to the same three-attempt budget unless it is a separately accepted task.
+
+For every attempt, write these fields before the next edit:
+
+| Field | Required evidence |
+| --- | --- |
+| Hypothesis | One causal mechanism, not a restatement of the symptom |
+| Prediction | An observation that would distinguish this hypothesis from the previous one |
+| Change | Exact changed paths and a patch or before/after hash |
+| Focused check | Exact command, input, literal output, and exit status |
+| Real-path check | Direct observation, or `NOT_RUN` with a reason |
+| Symptom fingerprint | Stable fingerprint described below |
+| Decision | `ADVANCE`, `SHIFT_CAUSE`, `PROVEN`, or `STOP` |
+
+Use [the evidence ledger](references/evidence-ledger.md) as a copyable record.
+
+## Fingerprint the observable failure
+
+Fingerprint what the system did, not the agent's explanation. Build a canonical record from:
+
+```json
+{
+  "schema_version": 1,
+  "command": "the exact verification command",
+  "input_digest": "digest or stable identifier of the tested input",
+  "exit_code": 1,
+  "failure_class": "stable-machine-readable-class",
+  "stable_excerpt": "the smallest decisive output with volatile values removed",
+  "real_path_state": "the directly observed state, or NOT_OBSERVED"
+}
+```
+
+Keep the unedited output beside this sanitized record. Remove timestamps, run IDs, ANSI codes, random ports, and temporary paths from `stable_excerpt` only when they do not affect the defect. Do not normalize away values that could distinguish two causes.
+
+Optionally compute the canonical SHA-256 fingerprint from this skill directory:
+
+```bash
+python3 scripts/fingerprint.py evidence/attempt-1.json
+```
+
+The helper validates the record, rejects unknown fields, and prints the fingerprint. It does not execute commands or redact evidence.
+
+The helper uses only the Python 3.9+ standard library. When changing it, run its bundled regression tests:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/test_fingerprint.py -v
+```
+
+The same fingerprint after a different patch means the observable failure did not move. A cosmetically different message with the same failure class, input, command, and real-path state also counts as a repeated failure when the changed text is only volatile data. Do not use a patch hash in the symptom fingerprint; record it separately so different edits cannot masquerade as different outcomes.
+
+## Shift the root-cause strategy
+
+Set the decision to `SHIFT_CAUSE` immediately when any of these occurs:
+
+- a symptom fingerprint repeats;
+- the patch changes but the decisive state does not;
+- a focused test passes while the real path still fails;
+- a retry produces no new discriminating evidence.
+
+Then stop editing and perform this sequence:
+
+1. List the attempted mechanisms and the observation that falsified or failed to distinguish each one.
+2. Identify the next unobserved owner boundary along the live path: input, dispatch, configuration, dependency, generated artifact, process, persistence, network, or presentation.
+3. Collect one new observation at that boundary with tracing, logging, inspection, or a minimal probe.
+4. Form a replacement hypothesis that predicts a different observation and targets a different causal mechanism.
+5. Resume only if the new evidence can discriminate the replacement hypothesis. Otherwise return `BLOCKED`.
+
+Do not spend an attempt on the same mechanism with broader edits. Do not weaken the assertion, skip the failing path, add a silent fallback, or update expected output merely to obtain green tests.
+
+## Prove the real execution path
+
+Match proof to the claim. Bind every result to the exact revision, configuration, and input.
+
+| Claim | Required direct observation |
+| --- | --- |
+| CLI behavior | Invoke the installed or built entry point as a user would |
+| API or integration | Send a real request and observe response plus the responsible service boundary |
+| UI behavior | Perform the real interaction and observe UI state plus relevant network or console evidence |
+| Persistence | Write, reload in a new read path or process, and observe the stored value |
+| Deployment | Exercise the deployed revision and prove which revision served the result |
+| Agent or tool action | Observe the actual tool call and its external state change, not the agent's narration |
+
+A unit test, mock, type check, build, open port, process liveness check, or model-written summary is supporting evidence only when the claim crosses a boundary it does not exercise.
+
+## Make the verifier prove it can fail
+
+After the modified path passes, run a negative control on a disposable copy:
+
+1. Copy the verified modified state to a separate worktree or directory.
+2. Reintroduce the original defect or substitute a known-bad input that violates the same acceptance claim.
+3. Run the **same primary verification command** with the same relevant configuration.
+4. Require a non-zero exit status caused by the intended assertion.
+5. Record the exact command, input, literal output, exit status, and failure classification.
+
+An unrelated crash, missing dependency, timeout, syntax error, or test-discovery failure is not a valid negative control. If the known-bad state exits zero, the verifier is false-green: return `INCONCLUSIVE`, repair the verifier, and do not claim the product fix is proven.
+
+Return to the untouched modified tree and rerun the primary verification after the negative control.
+
+## Test rollback on another copy
+
+Never test rollback only by undoing the working repair. Instead:
+
+1. Copy the verified modified state to another disposable worktree or directory.
+2. Run the documented rollback command there.
+3. Verify changed paths and hashes match the recorded baseline.
+4. Run the baseline command and confirm the prior behavior or status is restored.
+5. Leave the primary modified tree unchanged.
+
+A rollback script that parses, prints help, or exits zero without restoring behavior has not been tested.
+
+## Finish with an evidence status
+
+Use exactly one status:
+
+- `PROVEN`: baseline defect observed; responsible change identified; focused and real-path checks pass; the known-bad negative control exits non-zero for the intended reason; rollback succeeds on another copy; the primary tree remains modified and passing.
+- `INCONCLUSIVE`: some useful evidence exists, but a decisive gate is missing, false-green, or ambiguous.
+- `BLOCKED`: the three-attempt budget is exhausted, a repeated fingerprint has no new discriminator, or a named external condition prevents the next observation.
+
+Report exact commands, inputs, literal results, exit statuses, fingerprints, changed paths, revision, and remaining gaps. A passing proxy check or the phrase "tests pass" is never a substitute for those fields.
+
+## Examples
+
+### Repeated patch with no state change
+
+```text
+Attempt 1: patch hash changed; focused test passed; real path still shows disabled.
+Fingerprint: 08b4...; decision: SHIFT_CAUSE.
+Next action: stop editing and observe the configuration-to-process boundary.
+```
+
+### Valid negative control
+
+```text
+Modified copy: primary verifier exits 0 and observes the expected UI state.
+Known-bad disposable copy: the same verifier exits 1 on the intended assertion.
+Rollback copy: baseline hashes match and the baseline command restores its prior result.
+Decision: PROVEN.
+```
+
+## Limitations
+
+- This workflow cannot prove a repair when the defect is not reproducible, the real execution path is inaccessible, or the primary verifier cannot observe the acceptance claim.
+- A three-attempt budget exposes stagnation; it does not identify the correct architecture or replace domain expertise.
+- A known-bad control demonstrates that one verifier catches one defect class. It does not prove complete test coverage.
+- Rollback verification covers the recorded paths and baseline behavior only; external systems need their own provider-side readback.
+
+## Security & Safety Notes
+
+- This skill can guide changes to code, configuration, dependencies, generated artifacts, and files, so its risk is `critical`.
+- Confirm the repository, target environment, accepted paths, and approval boundary before modifying state. Ask before destructive, irreversible, production, financial, credential, or external-message actions.
+- Keep negative controls and rollback trials on disposable copies. Never inject a known defect into the primary working tree or a live environment.
+- Keep raw evidence private when it may contain credentials, personal data, internal URLs, or customer content. Commit only sanitized records.
+- `scripts/fingerprint.py` is a Python standard-library helper that reads one local JSON record and prints a digest; it does not run commands, access the network, redact data, or modify the record.
+
+## Related Skills
+
+- `systematic-debugging` focuses on root-cause investigation before a fix; use this skill when attempts must also be fingerprinted, bounded, falsified with a negative control, and made reversible.
+- `verification-before-completion` gates success claims on fresh evidence; this skill adds repair-attempt accounting and rollback proof.
+- `closed-loop-delivery` spans acceptance through delivery; this skill is the narrower anti-stagnation and verifier-falsification protocol for repair loops.
+- `audit-agent-run-evidence` performs a read-only post-run audit; this skill governs the repair while it is happening.
+
+
+## Source and license
+
+The upstream MIT copyright and permission notice is preserved in
+[LICENSE](LICENSE), alongside the commit-pinned provenance above.

package/bundled-skills/break-ai-fix-loops/references/evidence-ledger.md

@@ -0,0 +1,90 @@
+# Repair evidence ledger
+
+Copy this template to a task-owned path. Do not commit runtime evidence unless the project requires it. Preserve full raw output separately and keep this ledger free of secrets and personal data.
+
+```markdown
+# Repair ledger
+
+## Contract
+- Acceptance claim:
+- Defect-disproving behavior:
+- Baseline revision:
+- Baseline configuration:
+- Baseline input and digest:
+- Baseline command:
+- Baseline literal output/result:
+- Baseline exit status:
+- Real execution path:
+- Primary verification command:
+- Rollback command:
+- Expected restored behavior/status:
+
+## Attempts
+| # | Hypothesis | Discriminating prediction | Changed paths / patch hash | Focused result + exit | Real-path result + exit | Symptom fingerprint | Decision |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | | | | | | | |
+| 2 | | | | | | | |
+| 3 | | | | | | | |
+
+## Root-cause shifts
+### Shift after attempt <n>
+- Repeated fingerprint or unchanged state:
+- Mechanisms already attempted:
+- Evidence against each mechanism:
+- Next unobserved owner boundary:
+- New observation:
+- Replacement hypothesis:
+- Different predicted observation:
+
+## Modified proof
+- Revision:
+- Exact command:
+- Input/configuration:
+- Literal output/result:
+- Exit status:
+- Real-path observation:
+
+## Negative control on disposable copy
+- Copy path or worktree:
+- Known-bad mutation/input:
+- Exact primary verification command:
+- Literal output/result:
+- Exit status (must be non-zero):
+- Intended failure classification:
+- Untouched modified tree rerun result:
+- Untouched modified tree rerun exit status:
+
+## Rollback on another copy
+- Copy path or worktree:
+- Exact rollback command:
+- Literal rollback output/result:
+- Rollback exit status:
+- Baseline hash comparison:
+- Restored behavior/status:
+- Baseline command rerun exit status:
+- Primary modified tree status:
+
+## Decision
+- Status: PROVEN | INCONCLUSIVE | BLOCKED
+- Attempts consumed: <0-3>
+- Decisive evidence:
+- Remaining gap or next discriminating observation:
+```
+
+## Fingerprint record
+
+Create one sanitized JSON record for every observed symptom:
+
+```json
+{
+  "schema_version": 1,
+  "command": "npm test -- --runInBand path/to/regression.test.js",
+  "input_digest": "sha256:replace-with-real-input-digest",
+  "exit_code": 1,
+  "failure_class": "assertion-mismatch",
+  "stable_excerpt": "expected enabled; observed disabled",
+  "real_path_state": "settings page still shows disabled after reload"
+}
+```
+
+Keep the primary verification command unchanged across attempts unless the contract was wrong. If it changes, record why and preserve results from both commands; otherwise a changed verifier can hide an unchanged defect.

package/bundled-skills/break-ai-fix-loops/scripts/fingerprint.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Create a stable symptom fingerprint from a validated JSON record."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Mapping
+
+
+REQUIRED_FIELDS = (
+    "schema_version",
+    "command",
+    "input_digest",
+    "exit_code",
+    "failure_class",
+    "stable_excerpt",
+    "real_path_state",
+)
+FAILURE_CLASS_PATTERN = re.compile(r"^[a-z0-9][a-z0-9._:-]*$")
+
+
+class RecordError(ValueError):
+    """Raised when a record cannot produce a trustworthy fingerprint."""
+
+
+def _reject_duplicate_fields(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """Build a JSON object while rejecting ambiguous duplicate field names."""
+    value: dict[str, Any] = {}
+    for field, field_value in pairs:
+        if field in value:
+            raise RecordError(f"duplicate field: {field}")
+        value[field] = field_value
+    return value
+
+
+def _normalize_text(value: str) -> str:
+    """Normalize transport-only differences without deleting meaningful values."""
+    return value.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def canonicalize(record: Mapping[str, Any]) -> dict[str, Any]:
+    unknown = sorted(set(record) - set(REQUIRED_FIELDS))
+    missing = sorted(set(REQUIRED_FIELDS) - set(record))
+    if missing:
+        raise RecordError(f"missing field(s): {', '.join(missing)}")
+    if unknown:
+        raise RecordError(f"unknown field(s): {', '.join(unknown)}")
+
+    if (
+        isinstance(record["schema_version"], bool)
+        or not isinstance(record["schema_version"], int)
+        or record["schema_version"] != 1
+    ):
+        raise RecordError("schema_version must be 1")
+    if isinstance(record["exit_code"], bool) or not isinstance(record["exit_code"], int):
+        raise RecordError("exit_code must be an integer")
+
+    canonical: dict[str, Any] = {
+        "schema_version": 1,
+        "exit_code": record["exit_code"],
+    }
+    for field in REQUIRED_FIELDS:
+        if field in ("schema_version", "exit_code"):
+            continue
+        value = record[field]
+        if not isinstance(value, str):
+            raise RecordError(f"{field} must be a string")
+        value = _normalize_text(value)
+        if not value:
+            raise RecordError(f"{field} must not be empty")
+        canonical[field] = value
+
+    if not FAILURE_CLASS_PATTERN.fullmatch(canonical["failure_class"]):
+        raise RecordError(
+            "failure_class must use lowercase letters, numbers, dot, underscore, colon, or hyphen"
+        )
+    return canonical
+
+
+def fingerprint(record: Mapping[str, Any]) -> str:
+    payload = json.dumps(
+        canonicalize(record), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(payload).hexdigest()}"
+
+
+def load_record(path: str) -> Mapping[str, Any]:
+    try:
+        if path == "-":
+            value = json.load(sys.stdin, object_pairs_hook=_reject_duplicate_fields)
+        else:
+            with Path(path).open("r", encoding="utf-8") as handle:
+                value = json.load(handle, object_pairs_hook=_reject_duplicate_fields)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise RecordError(str(error)) from error
+    if not isinstance(value, dict):
+        raise RecordError("record must be a JSON object")
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate a symptom record and print its canonical SHA-256 fingerprint."
+    )
+    parser.add_argument("record", help="JSON record path, or - to read standard input")
+    args = parser.parse_args(argv)
+
+    try:
+        print(fingerprint(load_record(args.record)))
+    except RecordError as error:
+        print(f"fingerprint: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-skills/break-ai-fix-loops/scripts/test_fingerprint.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Regression tests for fingerprint.py."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).with_name("fingerprint.py")
+SPEC = importlib.util.spec_from_file_location("fix_loop_fingerprint", SCRIPT)
+assert SPEC and SPEC.loader
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+def record() -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "command": "python -m pytest tests/test_regression.py",
+        "input_digest": "sha256:0123456789abcdef",
+        "exit_code": 1,
+        "failure_class": "assertion-mismatch",
+        "stable_excerpt": "expected enabled\nobserved disabled",
+        "real_path_state": "settings remain disabled after reload",
+    }
+
+
+class FingerprintTests(unittest.TestCase):
+    def test_key_order_and_transport_newlines_do_not_change_fingerprint(self) -> None:
+        first = record()
+        second = dict(reversed(list(first.items())))
+        second["stable_excerpt"] = "expected enabled\r\nobserved disabled"
+        self.assertEqual(MODULE.fingerprint(first), MODULE.fingerprint(second))
+
+    def test_meaningful_boundary_blank_lines_change_fingerprint(self) -> None:
+        first = record()
+        second = record()
+        second["stable_excerpt"] = "\nexpected enabled\nobserved disabled\n"
+        self.assertNotEqual(MODULE.fingerprint(first), MODULE.fingerprint(second))
+
+    def test_meaningful_trailing_whitespace_changes_fingerprint(self) -> None:
+        first = record()
+        second = record()
+        second["stable_excerpt"] = "expected enabled  \nobserved disabled"
+        self.assertNotEqual(MODULE.fingerprint(first), MODULE.fingerprint(second))
+
+    def test_observable_state_change_changes_fingerprint(self) -> None:
+        first = record()
+        second = record()
+        second["real_path_state"] = "settings are enabled after reload"
+        self.assertNotEqual(MODULE.fingerprint(first), MODULE.fingerprint(second))
+
+    def test_unknown_field_fails_closed(self) -> None:
+        value = record()
+        value["patch_hash"] = "must-be-recorded-outside-the-symptom-fingerprint"
+        with self.assertRaisesRegex(MODULE.RecordError, "unknown field"):
+            MODULE.fingerprint(value)
+
+    def test_missing_field_fails_closed(self) -> None:
+        value = record()
+        del value["input_digest"]
+        with self.assertRaisesRegex(MODULE.RecordError, "missing field"):
+            MODULE.fingerprint(value)
+
+    def test_boolean_schema_version_fails_closed(self) -> None:
+        value = record()
+        value["schema_version"] = True
+        with self.assertRaisesRegex(MODULE.RecordError, "schema_version must be 1"):
+            MODULE.fingerprint(value)
+
+    def test_cli_rejects_duplicate_fields_with_exit_two(self) -> None:
+        duplicate_record = (
+            '{"schema_version":1,"command":"pytest","input_digest":"sha256:abc",'
+            '"exit_code":1,"failure_class":"assertion-mismatch",'
+            '"stable_excerpt":"first","stable_excerpt":"second",'
+            '"real_path_state":"disabled"}'
+        )
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory, "duplicate.json")
+            path.write_text(duplicate_record, encoding="utf-8")
+            result = subprocess.run(
+                [sys.executable, str(SCRIPT), str(path)],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        self.assertEqual(result.returncode, 2)
+        self.assertIn("duplicate field: stable_excerpt", result.stderr)
+        self.assertNotIn("Traceback", result.stderr)
+
+    def test_cli_rejects_invalid_utf8_with_exit_two(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory, "invalid-utf8.json")
+            path.write_bytes(b"\xff")
+            result = subprocess.run(
+                [sys.executable, str(SCRIPT), str(path)],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        self.assertEqual(result.returncode, 2)
+        self.assertIn("invalid start byte", result.stderr)
+        self.assertNotIn("Traceback", result.stderr)
+
+    def test_cli_rejects_invalid_record_with_exit_two(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory, "invalid.json")
+            path.write_text(json.dumps({"schema_version": 1}), encoding="utf-8")
+            result = subprocess.run(
+                [sys.executable, str(SCRIPT), str(path)],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        self.assertEqual(result.returncode, 2)
+        self.assertIn("missing field", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()