Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

review/scripts/deep_review_gate.py

View on GitHub
#!/usr/bin/env python3
"""Evidence gate for Deep Review findings.

One command, zero ceremony:

    python3 skills/kicad/review/scripts/deep_review_gate.py \
        analysis/deep_review.json --analysis-dir analysis/

1. Validates each finding against deep_review.schema.json
   (_mini_jsonschema; per-finding — invalid findings are quarantined,
   not fatal) plus the cross-field rule the mini validator can't
   express: >=1 design anchor AND >=1 evidence source.
2. Checks citations: components/nets/pins exist in the analyzer JSON
   (a pin REF.PIN names a pin number or name that component has in the
   analyzer JSON, a floating pin included; a PCB-only part with a pad on
   no net has its pins unchecked); the cited datasheet page
   contains the quote (pdftotext when available; missing tool or PDF
   -> evidence_checked=partial, never quarantine); a computation's
   script path resolves against --project-dir. The gate never runs a
   computation, so a finding that cites one is evidence_checked=partial.
3. Stamps finding_ids (assign_deep_review_ids), mirrors evidence
   anchors to top-level components/nets/pins, canonical-sorts, writes
   back. Re-evaluates quarantined[] so corrected findings promote.
4. Failures land in quarantined[] with quarantine_reason — visible,
   never silently dropped.

Exit codes: 0 all verified; 1 >=1 quarantined; 2 I/O or top-level
shape error. Stdlib-only; pdftotext (poppler) optional.
"""
import argparse
import json
import os
import re
import secrets
import shutil
import subprocess
import sys
import unicodedata
from difflib import SequenceMatcher
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "scripts"))   # skills/kicad/scripts

from _mini_jsonschema import iter_errors            # noqa: E402
from analysis_cache import get_run                  # noqa: E402
from finding_schema import assign_deep_review_ids   # noqa: E402
from kicad_core.executables import find_executable  # noqa: E402

SCHEMA_PATH = (Path(__file__).resolve().parents[1] / "schemas"
               / "deep_review.schema.json")

ANCHOR_KEYS = ("components", "nets", "pins")


def resolve_run_dir(analysis_dir, run_id=None):
    """The run folder analysis/manifest.json names ('current' unless
    `run_id` is given), confined to a folder directly inside
    `analysis_dir`; `analysis_dir` itself for a flat layout or an
    unreadable manifest."""
    analysis_dir = Path(analysis_dir)
    manifest = analysis_dir / "manifest.json"
    if manifest.is_file():
        try:
            m = json.loads(manifest.read_text(encoding="utf-8"))
        except (OSError, ValueError, RecursionError):
            m = None
        if isinstance(m, dict) and isinstance(m.get("runs"), dict):
            run = get_run(str(analysis_dir), run_id or m.get("current"), m)
            if run and Path(run[0]).is_dir():
                return Path(run[0])
    return analysis_dir


def _strip_overbar(name):
    """KiCad's active-low markup: ~{RESET} is RESET."""
    return re.sub(r"~\{([^{}]*)\}", r"\1", name)


class _PinIds(set):
    """Pin numbers and names of one component. has_names is False when the
    analyzer JSON lists numbers only; names_complete is True only when every
    pin with a number on record also has a name."""
    has_names = False

    def __init__(self, *args):
        super().__init__(*args)
        self._named, self._unnamed = set(), set()

    def add_name(self, name):
        self.add(name)
        stripped = _strip_overbar(name)
        if stripped != name:
            self.add(stripped)
        self.has_names = True

    def add_pin(self, number, name):
        number = str(number).upper()
        self.add(number)
        if str(name or "").strip():
            self.add_name(str(name).strip().upper())
            self._named.add(number)
        else:
            self._unnamed.add(number)

    @property
    def names_complete(self):
        return self.has_names and not (self._unnamed - self._named)


def load_anchor_sets(analysis_dir, run_id=None):
    """Component refs + net identities from the analyzer JSON.

    Resolves the run dir via analysis/manifest.json ('current' unless
    --run given); falls back to a flat analysis dir (schematic.json /
    pcb.json directly inside it) for ad-hoc layouts.
    A physical net carries up to three identities: schematic
    internal name, annotated display_name, PCB net name. All three are
    accepted as citations.
    Returns (components, nets, pins): sets of upper-case strings plus a
    map of upper-case ref -> upper-case pin numbers and names the gate can
    check. A ref with no checkable pins is absent: no source lists any, or
    it is a PCB-only footprint with a pad on no net (pad_nets omits those).
    Raises ValueError naming the file when one cannot be read as a JSON
    object.
    """
    run_dir = resolve_run_dir(analysis_dir, run_id)
    comps, nets, pins, open_refs = set(), set(), {}, set()
    sch = run_dir / "schematic.json"
    if sch.is_file():
        data = _load_object(sch)
        for c in _as_list(data.get("components")):
            if isinstance(c, dict) and c.get("reference"):
                ref = str(c["reference"]).upper()
                comps.add(ref)
                for key in ("pin_nets", "pin_uuids"):
                    if isinstance(c.get(key), dict):
                        pins.setdefault(ref, _PinIds()).update(str(n).upper() for n in c[key])
        sch_nets = data.get("nets")
        for name, info in (sch_nets.items() if isinstance(sch_nets, dict) else ()):
            nets.add(str(name).upper())
            if not isinstance(info, dict):
                continue
            if info.get("display_name"):
                nets.add(str(info["display_name"]).upper())
            for p in _as_list(info.get("pins")):
                if isinstance(p, dict) and p.get("component"):
                    ids = pins.setdefault(str(p["component"]).upper(), _PinIds())
                    if p.get("pin_number"):
                        ids.add_pin(p["pin_number"], p.get("pin_name"))
                    elif str(p.get("pin_name") or "").strip():
                        ids.add_name(str(p["pin_name"]).strip().upper())
    sch_pinned = {ref for ref, ids in pins.items() if ids}
    pcb = run_dir / "pcb.json"
    if pcb.is_file():
        data = _load_object(pcb)
        for fp in _as_list(data.get("footprints")):
            if isinstance(fp, dict) and fp.get("reference"):
                ref = str(fp["reference"]).upper()
                comps.add(ref)
                pad_nets = fp.get("pad_nets") if isinstance(fp.get("pad_nets"), dict) else {}
                ids = pins.setdefault(ref, _PinIds())
                for num, entry in pad_nets.items():
                    ids.add_pin(num, entry.get("pin") if isinstance(entry, dict) else None)
                # pad_nets omits a pad on no net, so a PCB-only part with one is unchecked
                if ref not in sch_pinned and not (
                        isinstance(fp.get("pad_count"), int) and fp["pad_count"] <= len(pad_nets)):
                    open_refs.add(ref)
        net_map = data.get("nets")
        if isinstance(net_map, dict):
            nets.update(str(v).upper() for v in net_map.values() if v)
        name_map = data.get("net_name_to_id")
        if isinstance(name_map, dict):
            nets.update(str(k).upper() for k in name_map if k)
    for ref in open_refs:
        pins.pop(ref, None)
    return comps, nets, {ref: ids for ref, ids in pins.items() if ids}


def write_text_atomic(path, text):
    """Write UTF-8 text through a temp file beside `path` and os.replace.
    An existing file keeps its mode, a new one gets the umask mode; a
    symlink at `path` is replaced by a regular file, never followed."""
    path = Path(path)
    exists = path.is_file() and not path.is_symlink()
    flags = (os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
             | getattr(os, "O_BINARY", 0))
    while True:
        tmp = path.parent / f".{path.name}.{secrets.token_hex(6)}.tmp"
        try:
            # 0o666 lets the kernel apply the umask to a new file
            fd = os.open(tmp, flags, 0o600 if exists else 0o666)
            break
        except FileExistsError:
            continue
    try:
        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
            f.write(text)
        if exists:
            shutil.copymode(path, tmp)
        os.replace(tmp, path)
    except BaseException:
        try:
            os.unlink(tmp)
        except OSError:
            pass
        raise


def _load_object(path):
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError, RecursionError) as e:
        raise ValueError(f"{path}: {e}") from None
    if not isinstance(data, dict):
        raise ValueError(f"{path}: not a JSON object")
    return data


def _as_list(value):
    return value if isinstance(value, list) else []


def check_anchors(ev, comps, nets, pins):
    """Returns (failures, partial); a cited pin that cannot be checked is partial."""
    fails, partial = [], False
    for ref in ev.get("components") or []:
        if str(ref).upper() not in comps:
            fails.append(f"component {ref} not found in analyzer JSON")
    for net in ev.get("nets") or []:
        if str(net).upper() not in nets:
            fails.append(f"net {net} not found in analyzer JSON")
    for pin in ev.get("pins") or []:
        ref, _, num = str(pin).rpartition(".")
        if ref.upper() not in comps and "." in str(pin):
            # a dotted pin name such as P0.12: split at the first dot instead
            first, _, rest = str(pin).partition(".")
            if first.upper() in comps:
                ref, num = first, rest
        if not ref or not num:
            fails.append(f"pin {pin}: not a REF.PIN citation")
        elif ref.upper() not in comps:
            fails.append(f"pin {pin}: component {ref} not found in analyzer JSON")
        elif ref.upper() not in pins:
            partial = True
        elif num.upper() not in pins[ref.upper()]:
            ids = pins[ref.upper()]
            # a name may belong to a pin the analyzer JSON lists without one
            if ids.names_complete or num.isdigit():
                fails.append(f"pin {pin}: {ref} has no pin {num} in analyzer JSON")
            else:
                partial = True
    return fails, partial


def _datasheets_pkg():
    pkg = str(Path(__file__).resolve().parents[3] / "datasheets")
    if pkg not in sys.path:
        sys.path.insert(0, pkg)


def _manifest_pdf(d, mpn):
    """(path, stop, others): the PDF datasheets/manifest.json (or legacy index.json) lists
    for `mpn`; True when the entry marks the download as the wrong part, so no other file
    may stand in for it; and the lower-cased file names the manifest lists for other parts."""
    _datasheets_pkg()
    from datasheet_types.cache_reader import read_json_object
    from distributor_core.manifest import manifest_file_path
    for name in ("manifest.json", "index.json"):
        data = read_json_object(d / name)
        if data is None:
            continue
        parts = data.get("parts")
        if not isinstance(parts, dict):
            return None, False, set()
        want = mpn.strip().lower()
        entry = parts.get(mpn)
        if entry is None:
            entry = next((v for k, v in parts.items()
                          if isinstance(k, str) and k.strip().lower() == want), None)
        others = {v["file"].lower() for k, v in parts.items()
                  if isinstance(k, str) and k.strip().lower() != want
                  and isinstance(v, dict) and isinstance(v.get("file"), str)}
        if isinstance(entry, dict) and entry.get("status") == "ok":
            if entry.get("verification") == "wrong":
                return None, True, others
            path = manifest_file_path(d, entry.get("file"))
            if path is not None and path.is_file():
                return path, False, others
        return None, False, others
    return None, False, set()


def find_pdf(datasheets_dir, mpn):
    """The datasheet PDF for `mpn`: the manifest's file, else `<MPN>.pdf`, else the one
    `<MPN>_*.pdf` the datasheet sync writes that the manifest does not list for another
    part (`LM317_NOPB_….pdf` is LM317/NOPB's, not LM317's)."""
    d = Path(datasheets_dir)
    if not d.is_dir():
        return None
    listed, stop, others = _manifest_pdf(d, mpn)
    if stop:
        return None
    if listed is not None:
        return listed
    sanitized = re.sub(r"[^A-Za-z0-9_.-]", "_", mpn.strip())
    direct = d / f"{sanitized}.pdf"
    if direct.is_file():
        return direct
    lowered = sanitized.lower()
    pdfs = sorted(d.glob("*.pdf"))
    for p in pdfs:
        if p.stem.lower() == lowered:
            return p
    _datasheets_pkg()
    from distributor_core.manifest import sanitize_filename
    bases = {lowered + "_", sanitize_filename(mpn.strip()).lower() + "_"} - {"_"}
    hits = {p for p in pdfs if any(p.stem.lower().startswith(b) for b in bases)
            and p.name.lower() not in others}
    return hits.pop() if len(hits) == 1 else None


_DASH_RE = re.compile("[\u2212\u2013\u2010\u2011]")
# +/- (spaces allowed around the slash) and +- with any dash
_PLUSMINUS_RE = re.compile(r"\+(?:\s*/\s*)?[-\u2014]")
# One token per comparison operator or per run of letters/digits. A run
# keeps a decimal point or comma between digits ("5.5", "1,000") or before
# the first digit (".5", but not a dot leader "....37" or "100Ω.5"); a
# leading minus that starts a number outside a word ("-40", "(−40"; not
# "SOT-23" or "3.3-5.5"); and a ± written against its number ("±15",
# "+/-15"); and the minus of an exponent such as "1e-3". So "15" is neither
# "-15" nor "±15", and "5" is not ".5". Unit letters such as µ and ω are
# letters.
_TOKEN_RE = re.compile(
    r"<=|>=|±(?!\.?[0-9])|<|>|="
    r"|(?:(?<![^\W_]|\.)-(?=\.?[0-9])|±(?=\.?[0-9]))?"
    r"(?:(?<![^\W_]|\.)\.(?=[0-9]))?"
    r"(?:[^\W_]|(?<=[0-9])[.,](?=[0-9])|(?<=[0-9]e)-(?=[0-9]))+")
# a ± set apart from the number it precedes (a space or a wrapped line)
_PLUSMINUS_GAP_RE = re.compile(r"±\s+(?=\.?[0-9])")
_LEADING_POINT_RE = re.compile(r"(?<![^\s±-])\.(?=[0-9])")
# An exponent the PDF text splits ("1e- 3", "1 e-3"). The digits before the e
# must be a number of their own: "MAX3232E -40" is a part number and a value.
# A single digit glued to a letter ("A1e-3", "IC1e-3") stays an exponent. A
# token heuristic cannot separate every glued label from a part number; this
# one calls two or more digits a part number.
_EXP_BASE = r"(?:(?<![^\W_])[0-9]*\.?[0-9]+|(?<=[^\W\d_])[0-9](?![0-9]))"
_EXP_GAP_RE = re.compile(rf"({_EXP_BASE})[ \t]*e[ \t]*-\s*(?=[0-9])")
# a part-number token such as "max3232e-40" is not an exponent
_PARTNO_EXP_RE = re.compile(r"([^\W\d_][^\W_]*[0-9]{2}e)-(?=[0-9])")


def _norm_text(s):
    # NFKC folds ligatures/fullwidth forms and µ into μ; other symbols and
    # punctuation (degree signs, dashes, curly quotes) are word breaks.
    s = unicodedata.normalize("NFKC", s).lower()
    s = _DASH_RE.sub("-", s)
    s = _PLUSMINUS_RE.sub("±", s).replace("≤", "<=").replace("≥", ">=")
    s = _PLUSMINUS_GAP_RE.sub("±", s)
    s = _EXP_GAP_RE.sub(r"\1e-", s)
    # ".5" is written "0.5" so both spellings compare equal
    s = _LEADING_POINT_RE.sub("0.", " ".join(_TOKEN_RE.findall(s)))
    return _PARTNO_EXP_RE.sub(r"\1 -", s)


def _squash(s):
    # Two numbers side by side stay apart ("0.9 1.0" is not "0.91.0"), and
    # so does a ± set apart from a word ("± x" is not "±x").
    return re.sub(r"(?<=[0-9]) (?=[-±0-9])|(?<=[0-9]e) (?=-)|(?<=±) ", "|",
                  _norm_text(s)).replace(" ", "")


# a whole run of dots is one marker, so a dot leader leaves no stray point
_ELISION_RE = re.compile(r"\.{3,}|…")


def _quote_segments(quote):
    """Split a (possibly elided) quote into segments on '...' / '…'.
    Must run BEFORE normalization -- _norm_text collapses elision
    markers into a plain word break, destroying the split points."""
    return [s for s in _ELISION_RE.split(quote) if s.strip()]


def _segments_match(segments, norm_fn, text):
    """True if every segment appears in `text` (normalized via
    `norm_fn`), in order -- each search starts where the previous
    segment's match ended. Normalized segments match whole
    tokens; squashed ones may not start or end inside a number."""
    t = norm_fn(text)
    if norm_fn is _norm_text:
        t = f" {t} "
    pos = 0
    for seg in segments:
        q = norm_fn(seg)
        if not q:
            continue
        if norm_fn is _norm_text:
            q = f" {q} "
            idx = t.find(q, pos)
        else:
            idx = _find_outside_numbers(t, q, pos)
        if idx == -1:
            return False
        pos = idx + len(q)
        if norm_fn is _norm_text:
            pos -= 1    # the closing space opens the next token
    return True


def _find_outside_numbers(t, q, pos):
    idx = t.find(q, pos)
    while idx != -1:
        before = t[idx - 1] if idx else ""
        after = t[idx + len(q):idx + len(q) + 1]
        inside = ((q[0].isdigit() and before and (before.isdigit() or before in ".,-±"))
                  or (q[0] == "-" and re.search(r"[0-9]e$", t[max(0, idx - 2):idx]))
                  or (q[0] == "." and before.isdigit())
                  or (q[-1].isdigit() and after and (after.isdigit() or after in ".,")))
        if not inside:
            return idx
        idx = t.find(q, idx + 1)
    return -1


def _quote_in_text(quote, text):
    """Containment tolerant of case, whitespace, punctuation, Unicode
    variants, PDF line-wrap hyphenation, and mid-quote elision
    ("..."/"…") -- each segment between elision markers
    must appear in the text in order. The squashed fallback absorbs
    boundary shifts ("5.5V" vs "5.5 V", "over-\\nvoltage" vs
    "overvoltage"). Numbers, signs, decimal points, comparison
    operators and unit letters must match; a quote with no letter or
    digit matches nothing."""
    segments = _quote_segments(quote) or [quote]
    if not any(re.search(r"\w", _norm_text(s)) for s in segments):
        return False
    return (_segments_match(segments, _norm_text, text)
            or _segments_match(segments, _squash, text))


def _nearest_match(quote, text, window=80, stride=40):
    """Deterministic nearest-match hint for a quarantined datasheet
    quote: locates the earliest elision segment that fails to
    match (by the same in-order rule as `_quote_in_text`), then scores
    `window`-char slices of the normalized text at a fixed `stride`
    against it via difflib.SequenceMatcher.ratio(). First-best wins on
    ties (replacement requires a strictly higher ratio)."""
    segments = _quote_segments(quote) or [quote]
    t = _norm_text(text)
    pos = 0
    missing = None
    for seg in segments:
        q = _norm_text(seg)
        if not q:
            continue
        idx = t.find(q, pos)
        if idx == -1:
            missing = q
            break
        pos = idx + len(q)
    if missing is None:
        missing = _norm_text(segments[0])
    if len(t) <= window:
        return t
    best_ratio, best = -1.0, t[:window]
    for i in range(0, len(t) - window + 1, stride):
        candidate = t[i:i + window]
        ratio = SequenceMatcher(None, missing, candidate).ratio()
        if ratio > best_ratio:
            best_ratio, best = ratio, candidate
    return best


PDFTOTEXT_TIMEOUT_S = 30    # a PDF that stalls pdftotext leaves the quote unchecked


def check_datasheet(cites, datasheets_dir):
    """Returns (failures, partial). Missing tool/PDF -> partial, not failure."""
    fails, partial = [], False
    tool = find_executable("pdftotext")
    have_tool = tool is not None
    for cite in cites or []:
        quote = cite.get("quote", "")
        page = cite.get("page")
        if not re.search(r"\w", _norm_text(quote)):
            fails.append(f'quote "{quote[:80]}" has no letter or digit to check')
            continue
        if page is not None and page < 1:
            fails.append(f"page {page} is not a page number (1 or more)")
            continue
        pdf = find_pdf(datasheets_dir, cite.get("mpn", "")) if have_tool else None
        if pdf is None:
            partial = True
            continue
        # UTF-8 is poppler's default; xpdf's pdftotext (some Windows installs) writes Latin-1
        cmd = [tool, "-enc", "UTF-8"]
        if page is not None:
            cmd += ["-f", str(page), "-l", str(page)]
        cmd += [str(pdf), "-"]
        try:
            proc = subprocess.run(cmd, capture_output=True, encoding="utf-8",
                                  errors="replace", timeout=PDFTOTEXT_TIMEOUT_S)
        except (OSError, subprocess.TimeoutExpired):
            partial = True
            continue
        # Past the last page poppler's pdftotext exits 99 ("Wrong page range given"); xpdf's
        # exits 0 with no output at all, where any real page, even a blank one, gives a form feed
        if page is not None and (
                (proc.returncode == 99 and "page" in proc.stderr.lower())
                or (proc.returncode == 0 and proc.stdout == "")):
            fails.append(f"page {page} is past the end of {pdf.name}")
            continue
        if proc.returncode != 0:
            partial = True
            continue
        text = proc.stdout
        if not _quote_in_text(quote, text):
            where = f"page {page} of" if page else "anywhere in"
            reason = f'quote not found {where} {pdf.name}: "{quote[:80]}"'
            nearest = _nearest_match(quote, text)
            if nearest:
                reason += f'; nearest match: "...{nearest}..."'
            fails.append(reason)
    return fails, partial


def check_computation(comp, project_dir):
    """Returns (failures, partial). The gate never runs a computation, so
    a cited one is always partial; a cited script must still exist."""
    if not comp:
        return [], False
    script = comp.get("script")
    if script and not (Path(project_dir) / script).is_file():
        return [f"computation script not found: {script}"], True
    return [], True


def gate_finding(finding, item_schema, comps, nets, pins, datasheets_dir, project_dir):
    """Returns (kept_finding | None, quarantined_finding | None)."""
    # Strip all gate-stamped output fields so re-runs produce identical key order.
    _GATE_FIELDS = frozenset(
        ("quarantine_reason", "evidence_checked", "finding_id",
         "components", "nets", "pins"))
    f = {k: v for k, v in finding.items() if k not in _GATE_FIELDS}
    fails = [e.message for e in iter_errors(f, item_schema)]
    ev = f.get("evidence") or {}
    if not isinstance(ev, dict):
        ev = {}     # the schema error above already names it
    has_anchor = any(ev.get(k) for k in ANCHOR_KEYS)
    has_source = bool(ev.get("datasheet")) or bool(ev.get("computation"))
    if not has_anchor:
        fails.append("no design anchor: evidence must cite >=1 component/net/pin")
    if not has_source:
        fails.append("no evidence source: evidence must carry a datasheet "
                     "quote and/or a computation")
    partial = False
    if not fails:
        a_fails, a_partial = check_anchors(ev, comps, nets, pins)
        fails += a_fails
        ds_fails, ds_partial = check_datasheet(ev.get("datasheet"), datasheets_dir)
        comp_fails, comp_partial = check_computation(ev.get("computation"), project_dir)
        fails += ds_fails + comp_fails
        partial = a_partial or ds_partial or comp_partial
    if fails:
        q = dict(finding)
        q["quarantine_reason"] = "; ".join(fails)
        return None, q
    f["evidence_checked"] = "partial" if partial else "full"
    for key in ANCHOR_KEYS:
        if ev.get(key):
            f[key] = list(ev[key])
    return f, None


def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("deep_review_json")
    ap.add_argument("--analysis-dir", required=True)
    ap.add_argument("--run", default=None, help="run id (default: manifest current)")
    ap.add_argument("--datasheets-dir", default=None,
                    help="folder of datasheet PDFs (default: <project-dir>/datasheets)")
    ap.add_argument("--project-dir", default=None,
                     help="project root for resolving computation script "
                          "paths (default: --analysis-dir's parent)")
    args = ap.parse_args()
    project_dir = args.project_dir
    if project_dir is None:
        # analysis/ conventionally lives directly inside the project
        # root -- anchor to it, not the invoking cwd, so the
        # gate works when run from elsewhere.
        project_dir = str(Path(args.analysis_dir).resolve().parent)
    datasheets_dir = args.datasheets_dir or str(Path(project_dir) / "datasheets")

    path = Path(args.deep_review_json)
    try:
        doc = json.loads(path.read_text(encoding="utf-8"))
        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
    except (OSError, ValueError, RecursionError) as e:
        print(f"deep_review_gate: cannot load inputs: {e}", file=sys.stderr)
        return 2
    top_required = ("schema_version", "produced_for_run_id", "produced_at",
                    "findings", "quarantined")
    if not isinstance(doc, dict) or not all(k in doc for k in top_required):
        print("deep_review_gate: top-level shape invalid "
              f"(required keys: {', '.join(top_required)})", file=sys.stderr)
        return 2
    for key in ("findings", "quarantined"):
        if doc[key] is not None and not isinstance(doc[key], list):
            print(f"deep_review_gate: top-level shape invalid ({key} must be an array)",
                  file=sys.stderr)
            return 2

    try:
        comps, nets, pins = load_anchor_sets(args.analysis_dir, args.run)
    except ValueError as e:
        print(f"deep_review_gate: cannot load inputs: {e}", file=sys.stderr)
        return 2
    item_schema = schema["properties"]["findings"]["items"]

    kept, quarantined = [], []
    candidates = list(doc.get("findings") or []) + list(doc.get("quarantined") or [])
    for finding in candidates:
        if not isinstance(finding, dict):
            quarantined.append({"quarantine_reason": "not a JSON object",
                                "value": finding})
            continue
        ok, bad = gate_finding(finding, item_schema, comps, nets, pins,
                               datasheets_dir, project_dir)
        if ok is not None:
            kept.append(ok)
        else:
            quarantined.append(bad)

    assign_deep_review_ids(kept)
    kept.sort(key=lambda f: (f.get("category", ""), f.get("finding_id", "")))
    quarantined.sort(key=lambda f: (str(f.get("category", "")),
                                    str(f.get("summary", ""))))
    doc["findings"] = kept
    doc["quarantined"] = quarantined
    write_text_atomic(path, json.dumps(doc, indent=2) + "\n")

    n_partial = sum(1 for f in kept if f.get("evidence_checked") == "partial")
    print(f"deep_review gate: {len(kept)} verified "
          f"({n_partial} partial), {len(quarantined)} quarantined")
    return 1 if quarantined else 0


if __name__ == "__main__":
    for _stream in (sys.stdout, sys.stderr):  # UTF-8 on a cp1252 pipe (Windows)
        if hasattr(_stream, "reconfigure"):
            _kw = {"newline": "\n"}
            if (getattr(_stream, "encoding", "") or "").lower().replace("-", "") != "utf8":
                _kw.update(encoding="utf-8", errors="backslashreplace")
            _stream.reconfigure(**_kw)
    sys.exit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall