diptrace-evidence-capture

Read runtime access before choosing between explicit-path MCP, a live bridge session, and native/headless CLI. Their availability is separate.

DipTrace evidence capture

RAG: engineering memory by default — shared workflow. Use DipTrace course knowledge as working context for editor, verification and export procedures; translate it to verified native profiles and actual MCP/CLI capabilities.

Prefer the most deterministic available evidence path without promoting runtime or operator claims to trusted provenance. For supported opening/saving, PCB validation, or recording, use the native headless helper first. Windows, WSL-to-Windows, and installed Linux/macOS Wine backends are described in runtime access, including their different path/desktop handling. For a formal operator-supplied format-evidence candidate or an unsupported native action, use the legacy operator workflow in references/operator-workflow.md.

Use public tools/list for exact callable names and get_capabilities for session, document, and feature availability. Native host orchestration is a local helper and does not expand the MCP tool contract.

Open/save/close and capture

The base headless roundtrip opens and saves pcb, schematic, component, and pattern documents in the actual editor. It is a local CLI, so it need not appear in MCP tools/list. Check the installed helper/module and backend before reporting that native opening is unavailable. The command saves its input: use an isolated copy for a read-only review, and retain original/copy hashes and process evidence.

Base roundtrip does not re-export XML or run native ERC/DRC. Use the separate bounded schematic helper below when present in the installed/source package; use the PCB profile for PCB XML re-export, refill and DRC. Preserve supported evidence and report the exact remaining unsupported action. Do not invent an export command.

For requested real-window MP4/GIF capture, use the cinematic headless command in runtime access; it requires ffmpeg and a valid replay/profile. Ordinary native verification does not require the legacy quarantine/attestation pipeline. Use that pipeline only when a formal evidence candidate is requested.

Bounded schematic evidence

The source module diptrace_mcp.schematic_native_acceptance supports .dchxml on non-elevated Windows, with an owned hidden desktop and a binary/menu-pinned English Schematic 5.3.0.3 profile. It is a local CLI, not a public MCP tool; check module availability, --help, the selected executable and source version first.

py -B -m diptrace_mcp.schematic_native_acceptance `
  --diptrace-root "C:\Program Files\DipTrace" `
  --project "C:\work\design.dchxml" --expected-sha256 <actual-source-sha256> `
  --output-dir "C:\work\new-evidence-directory" --erc --capture

The output directory must not exist. The helper copies the guarded input, uses Save As to a separate XML, reopens/exports in another process, then independently reopens the final export. --inspect only opens/captures/closes its isolated input. Optional --erc captures a known native ERC result; a complete positive-error-list profile is not yet verified. ffmpeg is required for capture, ERC images and startup-dialog images.

Unknown startup dialogs are not dismissed. First inspect their lossless client PNG; --startup-dialog-sha256 authorizes only that reviewed exact image with a unique visible/enabled OK button. Never guess the hash or use a blanket nag dismissor. Focus/locale/rendering differences may require another review, not a weaker match.

completed: true / exit 0 reports native execution only, NOT schematic acceptance. Keep erc_status: review_required when the exact success image does not match; record image review separately without rewriting the native report or inventing an operator attestation. Independently compare pin/net/NC/pad mappings, shared units, symbol geometry and wire contacts. Native imports may renumber ports, recenter symbols or embedded patterns, add pin length and reroute wires, even over successive exports. Do not classify these geometric changes as harmless rounding or replace the source until the differences are resolved. No helper result grants trusted provenance.

Native PCB acceptance first

Run the bounded native PCB rail when the task is refill/DRC/save/reopen/XML round-trip evidence:

py -m diptrace_mcp.pcb_native_acceptance run `
  --diptrace-root "C:\Program Files\DipTrace" `
  --project "C:\work\board.dipxml" `
  --output-xml "C:\work\evidence\board.native.dipxml"

For a binary .dip project, provide --baseline-xml expected.dipxml. The helper snapshots the baseline before GUI mutation, runs the real PCB editor on the isolated Win32 desktop by default, invokes the bounded diptrace-5.3-en-v1 menu profile, saves/closes/reopens, exports distinct XML, and writes a *.native-evidence.json sidecar.

Interpret the result exactly:

• PASS / exit 0: DRC matched a verified success token, structural invariants stayed equal, and the full XML semantic fingerprint equals the immutable baseline.
• FAIL / exit 1: the native pipeline failed, DRC exposed a positive error count, structural invariants changed, or desktop/window-station/session safety evidence changed.
• HUMAN_REVIEW_REQUIRED / exit 2: native transport completed but a locale/dialog is unknown, no immutable baseline exists, or a full semantic delta remains after stable structural checks.

Do not reinterpret HUMAN_REVIEW_REQUIRED as PASS. Do not recover from an unknown menu/dialog by coordinate clicks, SendInput, physical cursor movement, or synthesized keyboard shortcuts. A new DipTrace build/locale must first establish a reviewed native profile or fall back to operator capture.

The native summary binds components, nets/endpoints, traces/points, vias, copper and plane layers, via styles, copper pours, ratlines, unresolved multi-pad nets, duplicate IDs, hashes, PIDs and Win32 desktop/session identity. It does not prove electrical correctness or grant fixture trust.

Legacy mandatory stage order

1. Candidate capture: choose a committed question recipe and initialize an operator-owned allowed root. Record three distinct roles in order: source, open_save, reexport. Each role gets its own path, SHA-256, XML inventory, and stage-specific attestations. If a private binary input matters, bind its metadata only on the source record with repeatable --input-artifact ROLE=PATH; its bytes remain outside quarantine and Git.
2. Candidate finalization: answer every required recipe check from actual GUI observation, then finalize. The result is operator_supplied_unverified, candidate_only=true, and grants no validation level.
3. Dry-run ingest: run the shipped ingest_fixtures.py --dry-run. It re-reads every role, validates candidate and detached hashes, reports conflicts, and has no apply implementation.
4. MCP validation: bind source and saved, plus reexport when available, to the selected document and call validate_roundtrip_evidence. Require exact role paths and hashes. This call is read-only and still grants no trusted authority.
5. Explicit confirmation: show the operator the candidate ID, document SHA, role hashes, semantic comparison summary, conflicts, and metadata files that would be written. Silence, script success, or prior capture consent is not confirmation.
6. Metadata record: only after that confirmation call record_roundtrip_evidence. It may write <document>.roundtrip-evidence.json and <document>.provenance.json; it never changes design bytes and never grants high trust.

Do not make fixture-tree changes. A separate reviewed source change is required to add trusted registry entries.

Quantitative and provenance boundaries

• Native XML and legacy XML inputs are bounded at 128 MiB; DTD and entity declarations are refused.
• Legacy capture requires exactly 3 distinct role paths: source, open_save, and reexport.
• Supported XML source types are PCB, Schematic, Component Library, and Pattern Library.
• Supported document units are recorded literally as mm, inch, and mil.
• Optional private inputs are bounded to 32 files of 128 MiB each and must remain under the allowed root, outside .diptrace-capture, with no symlink, junction, or hard-link alias.
• A SHA-256 is exactly 64 lowercase hexadecimal characters and is rechecked at each evidence handoff.
• Native PASS is an execution/round-trip verdict only. Trust promotion remains a separate reviewed registry/fixture action.

The packaged legacy scripts are byte-identical mirrors of ../../scripts/capture_diptrace_evidence.py and ../../scripts/ingest_fixtures.py; their hashes are pinned in ../SOURCES.sha256.

Result

Return ../shared/result.schema.json. Label native GUI execution facts and exact hashes as document evidence, deterministic XML comparison as analytical, human visual judgements as operator, and planning advice as heuristic. Missing artifacts, hash mismatches, unknown native UI state, unresolved checklist items, changed private inputs, path aliases, failed comparisons, or absent required confirmation prevent a trusted completion claim.