PCB Learning Lab

An isolated, reproducible training repository for reviewing schematics and PCB layouts, extracting traceable engineering knowledge, and guiding simple KiCad designs.

The repository is rooted at D:\PCB-Learning-Lab. Runtime tools, fetched GitHub repositories, caches, temporary files, and editable work copies remain inside this directory and are not committed.

Read PROJECT_STATUS.md first for the latest verified capabilities, corpus counts, acceptance gaps, and commands for continuing the project in a new Codex task.

Capabilities

• Catalog pinned open-hardware PCB projects and promote verified projects to a Gold corpus.
• Ingest KiCad, Altium, and Cadence source packages without modifying the originals.
• Run deterministic KiCad ERC/DRC plus structured schematic and layout review.
• Extract evidence-backed knowledge cards from designs and review outcomes.
• Guide simple 2-4 layer low- and medium-speed KiCad training projects.

Catalog state

The catalog starts from commit-pinned design candidates and records seed and backfill audits separately. A seed is not a Gold case merely because it is a well-known open-source design or receives a high numeric score. The generated seed scorecard is the authoritative snapshot of attempted cases, Gold promotions, rejections, and remaining category gaps.

Quick start

Open D:\PCB-Learning-Lab as the Codex workspace and trust this repository so Codex can load the repository-level .codex/config.toml. Do not register the KiCad MCP globally; the checked-in review/build templates deliberately confine it to work\active.

. .\scripts\Enter-Lab.ps1
.\scripts\lab.ps1 bootstrap
.\scripts\lab.ps1 status
.\scripts\lab.ps1 catalog stats

Formal seed scoring and automatic backfill

Run the formal seed scorer from the project root to score the 13 ready seeds and automatically try up to 83 remaining candidates until the 20-case Gold target is filled or the eligible queue is exhausted:

.\scripts\lab.ps1 catalog seed-score --target-gold 20 --max-backfill 83

The command writes the human-readable scorecard to reports\baselines\seed-scorecard.md and the machine-readable record to reports\baselines\seed-scorecard.json. Per-case evidence is retained under reports\baselines\seed-evidence, with catalog case records in catalog\cases.yaml and backfill audit decisions in catalog\backfill-audit.yaml.

Gold promotion uses strict gates in addition to the 12-point score. A case must have a fixed commit and auditable license scope, parseable native schematic and PCB sources, reproducible baseline outputs, and no unresolved blocker from ERC, DRC, import warnings, missing dependencies, or evidence review. A score of 8/12 or even 12/12 never overrides an ERC/DRC blocker; the blocker must be resolved or explicitly dispositioned with evidence before promotion.

Use review mode by default. Stage a project before review or drawing:

.\scripts\lab.ps1 stage <case-id>
.\scripts\lab.ps1 mode review
.\scripts\lab.ps1 review <case-id> --profile full

The build mode is limited to work\active:

.\scripts\lab.ps1 mode build

The pinned kicad-mcp-pro 3.30.1 package requires Python 3.13 or newer, so the bootstrap uses a project-local managed Python 3.13 runtime even though the core catalog and CI remain compatible with Python 3.12. The KiCad Windows package is signature/hash verified and extracted into .runtime; its NSIS installer is not executed.

Evidence model

Knowledge advances from E0 raw evidence, through E1 deterministic facts and E2 supported candidates, to E3 internally reproduced rules and E4 engineer-approved rules. Only E4 rules are loaded automatically by review and drawing workflows.

Licensing

Original software and skills are MIT licensed, original hardware is CERN-OHL-P-2.0 licensed, and original documentation and knowledge cards are CC BY 4.0 licensed. Upstream projects retain their own licenses; this repository stores source metadata and commit pins rather than vendoring their contents.