@fateforge/xpedition-cli 1.0.0

package/docs/NATIVE_ADAPTER.md

@@ -0,0 +1,141 @@
+# Native Xpedition adapter
+
+The repository includes an opt-in adapter for the public Xpedition PCB
+automation interface. It uses the `MGCPCB.ExpeditionPCBApplication` and
+`MGCPCBAutomationLicensing.Application` COM classes documented by the
+installation's own automation examples. The adapter never edits Xpedition
+private databases and does not bypass licensing.
+
+## Install and configure
+
+Install the optional Windows dependency from the checkout:
+
+```powershell
+python -m pip install -e ".[native]"
+```
+
+`xpedition-native-adapter` is installed as a console entry point. The CLI
+discovers it automatically when it is on `PATH`; `XPEDITION_NATIVE_COMMAND`
+can be set to an explicit adapter executable when several installations are
+present. Set `XPEDITION_SDD_HOME` when the installation cannot be found from
+`SDD_HOME` or the `MGLS_LICENSE_FILE` location.
+
+The Xpedition automation classes must be registered by the product's official
+post-install step. If `xpedition-cli doctor` reports that COM automation is
+not registered, first try the current-user helper (no elevation required). The
+`scripts/` helpers ship in neither the wheel nor the npm package, so run them from
+a clone of this repository:
+
+```powershell
+# Substitute the SDD_HOME of the installed release, for example
+# D:\Xpedition\home\XPED2604\SDD_HOME
+$env:XPEDITION_SDD_HOME = "<install>\home\<release>\SDD_HOME"
+powershell -ExecutionPolicy Bypass -File .\scripts\register-xpedition-user.ps1
+```
+
+If the current-user registration is rejected by the local policy, run
+`scripts/register-xpedition.ps1` from the clone in an elevated PowerShell. The
+helper then invokes the installation's own `registrator.exe`:
+
+```powershell
+$env:SDD_HOME = "<install>\home\<release>\SDD_HOME"
+$env:SDD_PLATFORM = "win64"
+$env:SDD_VERSION = "<release>"
+Set-Location "$env:SDD_HOME\..\win64"
+& "$env:SDD_HOME\common\win64\_bin\registrator.exe" "-version=$env:SDD_VERSION"
+```
+
+Use the paths for the installed release. A successful registration is visible
+without opening a project:
+
+```powershell
+xpedition-cli doctor --compact
+xpedition-cli system license --compact
+```
+
+The CLI keeps the native status unavailable until both the adapter and the
+COM registration are present. It reports license failures as `E_AUTH` and
+does not claim that a license is valid merely because a license file path is
+configured.
+
+## Adapter protocol
+
+The adapter receives one JSON object on stdin and returns one CLI envelope on
+stdout. Diagnostics belong on stderr:
+
+```json
+{"method":"health","params":{}}
+```
+
+```json
+{"ok":true,"schema_version":"1.0","data":{"ready":true},"meta":{"duration_ms":0}}
+```
+
+The current bridge implements `health`, `start`, `attach`, `open`,
+`snapshot`, `save`, `close`, controlled component placement/move and
+schematic net operations used by `apply_changeset`, and the project-level
+methods behind the guarded commands: `clone_project`, `draw`, `show`,
+`verify`, `export_pdf`, `package`, `library_import`, `kicad_import` (every KiCad
+`.pretty` footprint library as a cell partition, through the stock HKP converters;
+`library kicad-import`), `pcb_create` (JobWizard's command line),
+`forward_annotate` (Layout's Project Integration), `board_outline` (rounded corners
+through the points array), `mounting_holes` (`PutMountingHoleEx`), `arrange_components`,
+`placement_batch` (`pcb placement`: the selected parts previewed, then moved one at a
+time with the placement DRC on and each read back), `show_board` (`pcb show`: the board
+window to the front under a display scheme, fitted, optionally captured to a PNG),
+`plane_pour` (`bRouteObstruct` false, so the copper flows around traces), `route_board`
+(`LayerSelect` for the inner layers; a second round after the planes regenerate),
+`net_rules` (a net class and its trace widths through the `ConstraintsAuto` server, then
+`ProjectIntegration.SynchCES`), `render_board` (the board's geometry drawn to a PNG by
+`xpedition_cli.board_render`), `board_geometry` (the same data as JSON), `hand_route`
+(`PutTrace` / `PutVia` where the person says), `unroute_nets` (by net, all, or one item
+at a point), `move_component` (with the placement DRC on), `tidy_labels` (silkscreen
+designators moved beside their parts), `batch_drc` and `manufacturing_output` (the ODB++ /
+Gerber / NC drill dialogs with their setups patched while the board is closed, gathered
+into a package folder). It
+supports the PCB `MGCPCB.ExpeditionPCBApplication` and schematic
+`Viewdraw.Application` COM classes. The bridge attaches to an already running
+Xpedition process when possible; otherwise `start` or `open` creates one
+through the launcher. Layout's own questions while a board opens (a stale lock,
+database recovery, the offer to forward-annotate) are answered from a helper
+thread through UI Automation, which needs the optional `pywinauto` package (the
+`native` extra, installed from a checkout as above or with
+`python -m pip install "xpedition-cli[native] @ git+https://github.com/fatecannotbealtered/xpedition-cli"`);
+without it those prompts wait for a person.
+
+Prefer starting through the product launcher rather than through COM. Every
+Xpedition `LocalServer32` entry points at the real binary under
+`SDD_HOME/<product>/win64/bin`, and those binaries need the release environment
+that the small launcher in `SDD_HOME/common/win64/bin` establishes. COM
+activation bypasses the launcher, so `CoCreateInstance` fails with
+`CO_E_SERVER_EXEC_FAILURE` (0x80080005); `start` therefore launches the launcher
+binary and then attaches. The adapter maps that COM status to
+`E_BACKEND_UNAVAILABLE` with a launcher hint instead of a bare server error.
+
+All document reads request an automation license token using the same
+`Validate(0)` → `GetToken` → `Validate(token)` sequence as the vendor
+examples. A failed token exchange is returned as a structured error.
+
+## Placement is not transactional
+
+`AddPartInstance` puts the symbol on the sheet before the reference designator
+is assigned, and neither the component nor the block exposes a delete entry
+point in this API. When the refdes assignment fails — a power or ground symbol
+rejects one outright — the instance cannot be rolled back. The adapter reports
+that case with `orphan_placed`, the library/device/symbol it came from and the
+coordinates, so the caller can remove it in Designer; it never reports the
+operation as applied.
+
+## End-to-end evidence
+
+Native E2E still requires a disposable project in a licensed Windows
+environment. The first smoke run places `R1` and `C1`, creates the `3V3` net,
+connects `R1.1` to `C1.1`, saves, closes, reopens and compares the reread
+snapshot; it is recorded in [`E2E.md`](E2E.md), together with the runs that took
+a project from an empty schematic to a fabrication package.
+
+Attach, snapshot, placement and coordinate read-back have each been verified
+against a running Designer session. The smoke loop itself passed on 2026-09-12
+against a hand-built library: the installation ships no component library, so the
+`R` and `C` symbols were authored into a writable copy of its empty template
+library — see [`COMPATIBILITY.md`](COMPATIBILITY.md).

package/docs/OPEN_SOURCE_CHECKLIST.md

@@ -0,0 +1,61 @@
+# Open-Source Checklist
+
+[English](OPEN_SOURCE_CHECKLIST.md) | [中文](OPEN_SOURCE_CHECKLIST_zh.md)
+
+Run through this gate **before every release** of `xpedition-cli` (before its `vX.Y.Z` tag is pushed). It is a security and quality checkpoint, not documentation — every box must be ticked (or consciously waived with a note) for the commit being released; the boxes in this file stay blank as the template for the next release. The repository is already public, so a secret pushed to it cannot be un-leaked: the Secrets checks apply to every push, not only to a release.
+
+## Secrets
+
+- [ ] No credentials, tokens, API keys, or passwords anywhere in the working tree.
+- [ ] No secrets in **git history** — checked with a scanner (e.g. `gitleaks detect`, `git log -p | grep`); if found, the history is rewritten or the repo re-created, not just deleted from `HEAD`.
+- [ ] No internal hostnames, private IPs, internal URLs, or employer-internal identifiers in code, config, or comments.
+- [ ] Test fixtures and recorded responses contain only synthetic / redacted data — no real account data, no real tokens.
+- [ ] `.env`, `*.local`, credential files, and `~/.xpedition-cli/` artifacts are listed in `.gitignore` and confirmed untracked (`git status --ignored`).
+- [ ] Credentials are stored encrypted at rest (OS keyring or encrypted envelope, `0600`), never plaintext in the config file.
+
+## Docs
+
+- [ ] `README.md` follows the REPO-SPEC §2 skeleton (Title/badges → Agent Install → What It Does → Capabilities → Agent Workflow → Machine Contract → Configuration → Project Structure → Development → Links).
+- [ ] `README.md` and `README_zh.md` are **content-synced** — same sections, same commands, same placeholders resolved to the same real values.
+- [ ] `CHANGELOG.md` exists, uses Keep a Changelog format, and has an `## [Unreleased]` section on top.
+- [ ] `LICENSE` is present, the license is chosen deliberately (default MIT), and the year and copyright holder are filled in (`2026`, `Sean Guo <guosong6886@gmail.com>`).
+- [ ] Install blocks are copy-paste-runnable and use the real published `@fateforge/xpedition-cli` / `fatecannotbealtered/xpedition-cli`.
+
+## Governance
+
+- [ ] `SECURITY.md` is present with a working disclosure channel (`guosong6886@gmail.com`) and a supported-versions table.
+- [ ] `CONTRIBUTING.md` is present (env setup, branch/commit, test, PR flow).
+- [ ] `CODE_OF_CONDUCT.md` is present (Contributor Covenant) if the project accepts external contributions.
+- [ ] If `xpedition-cli` wraps a third-party product (Siemens Xpedition), `NOTICE.md` carries the trademark / non-affiliation notice and `docs/COMPATIBILITY.md` lists the verified backend version matrix.
+
+## Build / CI
+
+- [ ] CI (`.github/workflows/ci.yml`) is **green** on the commit being pushed.
+- [ ] CI **enforces** lint and tests — a red lint or failing test blocks merge (not advisory-only).
+- [ ] Functional Contract Coverage is 100%: every public behavior documented in README, Skill, `reference`, `--help`, `context`, `doctor`, or `changelog` has automated command-level tests. (`update` is not shipped in this phase.)
+- [ ] `reference.release_readiness.level` is accurate: `stable` has FCC 100%, mock upstream/contract tests, and recorded live smoke/E2E evidence; missing live evidence is `beta`; missing command-level coverage is `unpublishable`.
+- [ ] `doctor` includes a `release_readiness` check whose status matches the declared release level.
+- [ ] The formatter config is committed (ruff / golangci-lint / prettier, by language) and CI runs the format check.
+- [ ] No build artifacts, caches, venvs, or IDE config are committed (covered by `.gitignore`).
+
+## Distribution
+
+- [ ] `package.json` `version` matches the git tag being released (`vX.Y.Z` ↔ `X.Y.Z`); `release.yml` guards this and fails on mismatch.
+- [ ] The binary itself (`bin/`, `*.exe`, `dist/`) is **not committed** — it is produced by CI and gitignored.
+- [ ] GitHub Release artifacts ship a `checksums.txt`; any future standalone binary install/update path must verify the checksum and **fail closed** on mismatch or missing entries.
+- [ ] Release pipeline signs `checksums.txt` with Sigstore/Cosign keyless signing, publishes the bundle, and any future standalone install/update path reports signature verification separately from checksum verification.
+- [ ] npm distribution publishes the main wrapper package plus every supported OS/CPU platform package from CI-built artifacts, with `npm publish --provenance`.
+- [ ] The version number has a single source of truth; the runtime `changelog` command and the GitHub Release body are derived from `CHANGELOG.md`, not hand-copied.
+
+## AI-native
+
+- [ ] Root `AGENTS.md` is present and points to `.agent/AGENT.md`.
+- [ ] `.agent/{AGENT,CLI-SPEC,SKILL-SPEC,SEC-SPEC}.md` specs are present; the shared repo skeleton standard is referenced from `ai-native-cli-spec/REPO-SPEC.md`.
+- [ ] `skills/xpedition-cli/SKILL.md` (the entry Skill), `skills/xpedition-schematic/SKILL.md` and `skills/xpedition-pcb/SKILL.md` are present; each frontmatter includes `version`, `license: MIT`, `user-invocable: true`, and `metadata.requires.min_version` matching the CLI version; both domain Skills also declare `metadata.requires.skills: ["xpedition-cli"]` and open by reading `../xpedition-cli/SKILL.md`, stopping at a `STOP CHECKPOINT` when that file is missing.
+- [ ] Each Skill's `description` says what it does not cover and which Skill does, and the entry Skill names the file of each domain Skill it hands work to.
+- [ ] The entry `SKILL.md` includes `When to use`, `Do not use`, `First Step`, agent defaults, JSON contract, write recipe or explicit read-only boundary, `STOP CHECKPOINT`, error decision tree, security boundary, an honest update boundary, and eval scenarios. Each domain Skill carries its own triggers, `STOP CHECKPOINT`s, playbooks and eval scenarios, and points at the entry Skill for the rest.
+- [ ] Each Skill's `test-prompts.json` is present and valid JSON; together they cover fresh-agent read, write safety or read-only boundary, permission boundary, `_untrusted` handling, and the package-update boundary.
+- [ ] Self-update is explicitly N/A for this phase. If a future release adds a bare `update`, it must sync every Skill directory under `skills/` or return `skill_sync_command` and report `stage` + `current_version` + `binary_replaced` + `skill_sync_status` on failure or interruption.
+- [ ] `xpedition-cli reference`, `xpedition-cli context`, and `xpedition-cli doctor` run and emit valid JSON envelopes — an agent can self-onboard from a clean checkout.
+- [ ] `xpedition-cli reference` exposes `release_readiness`, and `xpedition-cli doctor` reports the matching check.
+- [ ] The risk tier in `SECURITY.md` matches `reference.risk_tier` (`T2`), classified under `.agent/SEC-SPEC.md`.

package/docs/OPEN_SOURCE_CHECKLIST_zh.md

@@ -0,0 +1,61 @@
+# 开源检查清单
+
+[English](OPEN_SOURCE_CHECKLIST.md) | [中文](OPEN_SOURCE_CHECKLIST_zh.md)
+
+`xpedition-cli` **每次发布之前**（推送 `vX.Y.Z` tag 之前）逐项走查。这是一道安全与质量关卡，不是文档 —— 待发布的提交必须勾选每一项（或明确写明理由后豁免）；本文件中的复选框保持空白，作为下一次发布的模板。仓库已经公开，推送上去的密钥无法收回：“密钥”一节的检查适用于每一次推送，而不只是发布。
+
+## 密钥
+
+- [ ] 工作区任何位置都没有凭据、token、API key 或密码。
+- [ ] **git 历史**中没有密钥 —— 已用扫描工具检查（如 `gitleaks detect`、`git log -p | grep`）；若发现，需重写历史或重建仓库，而不是只从 `HEAD` 删除。
+- [ ] 代码、配置、注释中没有内部主机名、内网 IP、内部 URL 或公司内部标识符。
+- [ ] 测试夹具和录制的响应只含合成 / 脱敏数据 —— 没有真实账户数据，没有真实 token。
+- [ ] `.env`、`*.local`、凭据文件以及 `~/.xpedition-cli/` 产物已列入 `.gitignore` 并确认未被跟踪（`git status --ignored`）。
+- [ ] 凭据静态加密存储（操作系统钥匙串或加密信封，`0600`），绝不以明文写入配置文件。
+
+## 文档
+
+- [ ] `README.md` 遵循 REPO-SPEC §2 骨架（标题/徽章 → Agent 安装 → 它做什么 → 能力 → Agent 工作流 → 机器契约 → 配置 → 项目结构 → 开发 → 链接）。
+- [ ] `README.md` 与 `README_zh.md` **内容同步** —— 章节一致、命令一致、占位符解析为相同的真实值。
+- [ ] `CHANGELOG.md` 存在，使用 Keep a Changelog 格式，顶部有 `## [Unreleased]` 小节。
+- [ ] `LICENSE` 存在，许可证经过有意选择（默认 MIT），年份和版权方已填写（`2026`、`Sean Guo <guosong6886@gmail.com>`）。
+- [ ] 安装块可直接复制运行，使用真实已发布的 `@fateforge/xpedition-cli` / `fatecannotbealtered/xpedition-cli`。
+
+## 治理
+
+- [ ] `SECURITY.md` 存在，含可用的披露渠道（`guosong6886@gmail.com`）和受支持版本表。
+- [ ] `CONTRIBUTING.md` 存在（环境搭建、分支/提交、测试、PR 流程）。
+- [ ] 若项目接受外部贡献，`CODE_OF_CONDUCT.md` 存在（Contributor Covenant）。
+- [ ] 若 `xpedition-cli` 包装第三方产品（Siemens Xpedition），`NOTICE.md` 载明商标 / 非隶属声明，且 `docs/COMPATIBILITY.md` 列出已验证的后端版本矩阵。
+
+## 构建 / CI
+
+- [ ] 待推送的提交上 CI（`.github/workflows/ci.yml`）为**绿色**。
+- [ ] CI **强制**执行 lint 和测试 —— lint 失败或测试失败会阻断合并（不仅仅是提示性的）。
+- [ ] 功能契约覆盖率为 100%：README、Skill、`reference`、`--help`、`context`、`doctor` 或 `changelog` 中记录的每个公开行为，都有自动化命令级测试。（本阶段不提供 `update`。）
+- [ ] `reference.release_readiness.level` 准确：`stable` 具备 FCC 100%、mock upstream / contract tests 和真实环境 smoke/E2E 记录；缺真实证据为 `beta`；缺命令级覆盖为 `unpublishable`。
+- [ ] `doctor` 包含 `release_readiness` 检查，且状态与声明的发布等级一致。
+- [ ] 格式化工具配置已提交（按语言：ruff / golangci-lint / prettier），且 CI 运行格式校验。
+- [ ] 没有提交构建产物、缓存、虚拟环境或 IDE 配置（已由 `.gitignore` 覆盖）。
+
+## 分发
+
+- [ ] `package.json` 的 `version` 与待发布的 git tag 一致（`vX.Y.Z` ↔ `X.Y.Z`）；`release.yml` 对此做守卫，不一致即失败。
+- [ ] 二进制本身（`bin/`、`*.exe`、`dist/`）**不提交** —— 由 CI 产出并被 gitignore。
+- [ ] GitHub Release 发布产物附带 `checksums.txt`；未来的 standalone 二进制安装/更新路径必须校验 checksum，且在不匹配或缺少条目时**失败关闭**。
+- [ ] release pipeline 使用 Sigstore/Cosign keyless 签署 `checksums.txt`，发布 bundle；未来的 standalone 安装/更新路径必须把签名验证状态与 checksum 校验分开报告。
+- [ ] npm 分发从 CI 构建产物发布主 wrapper 包和每个受支持 OS/CPU 的平台包，并使用 `npm publish --provenance`。
+- [ ] 版本号有唯一真相来源；运行时 `changelog` 命令和 GitHub Release 正文均派生自 `CHANGELOG.md`，而非手工复制。
+
+## AI 原生
+
+- [ ] 根目录 `AGENTS.md` 存在并指向 `.agent/AGENT.md`。
+- [ ] `.agent/{AGENT,CLI-SPEC,SKILL-SPEC,SEC-SPEC}.md` 规格文件齐全；共享仓库骨架标准引用 `ai-native-cli-spec/REPO-SPEC.md`。
+- [ ] `skills/xpedition-cli/SKILL.md`（入口 Skill）、`skills/xpedition-schematic/SKILL.md` 与 `skills/xpedition-pcb/SKILL.md` 存在；各自的 frontmatter 包含 `version`、`license: MIT`、`user-invocable: true`，且 `metadata.requires.min_version` 匹配 CLI 版本；两个领域 Skill 另外都声明 `metadata.requires.skills: ["xpedition-cli"]`，正文开头先读 `../xpedition-cli/SKILL.md`，该文件不存在时停在 `STOP CHECKPOINT`。
+- [ ] 每个 Skill 的 `description` 写清不负责什么、该找哪个 Skill；入口 Skill 写明它把工作交给的每个领域 Skill 的文件。
+- [ ] 入口 `SKILL.md` 包含 `When to use`、`Do not use`、`First Step`、Agent 默认规则、JSON contract、写操作配方或明确只读边界、`STOP CHECKPOINT`、错误决策树、安全边界、诚实的更新边界和评估场景。每个领域 Skill 带自己的触发条件、`STOP CHECKPOINT`、剧本和评估场景，其余部分指向入口 Skill。
+- [ ] 每个 Skill 的 `test-prompts.json` 存在、JSON 合法，合起来覆盖 fresh-agent read、写操作安全或只读边界、权限边界、`_untrusted` 处理和包管理器更新边界。
+- [ ] 本阶段自更新明确标记为 N/A。未来若增加裸 `update`，必须同步 `skills/` 下的每个 Skill 目录或返回 `skill_sync_command`，并在失败/中断时报告 `stage` + `current_version` + `binary_replaced` + `skill_sync_status`。
+- [ ] `xpedition-cli reference`、`xpedition-cli context`、`xpedition-cli doctor` 可运行并输出合法的 JSON 信封 —— 代理能从干净的检出自助上手。
+- [ ] `xpedition-cli reference` 暴露 `release_readiness`，`xpedition-cli doctor` 报告匹配的检查项。
+- [ ] `SECURITY.md` 中的风险等级与 `reference.risk_tier` 一致（`T2`），分级依据 `.agent/SEC-SPEC.md`。

package/docs/PIN_WORKFLOW_VALIDATION.json

@@ -0,0 +1,28 @@
+{
+  "baseline": "d42b226a5b1812b2937ded096bf618b8692c4f9a",
+  "run_id": "35296848583",
+  "platform": "Linux-6.17.0-1022-azure-x86_64-with-glibc2.39",
+  "before": {
+    "tests": 2,
+    "failures": 2,
+    "errors": 0,
+    "skipped": 0
+  },
+  "full_suite": {
+    "tests": 261,
+    "failures": 0,
+    "errors": 0,
+    "skipped": 0
+  },
+  "ruff": "passed",
+  "version_sync": "passed",
+  "contract_local_only": "passed",
+  "native_xpedition_executed": false,
+  "scope": "offline comparison of supplied observations; not native execution",
+  "source_sha256": {
+    "xpedition_cli/pin_assignment.py": "39dc1c337897a1c9dc7fc07dc3b9d94c7d2e6b8b12eff16199d319fb790cf7cb",
+    "xpedition_cli/pin_assignment_contract.py": "baacde879cd5b69f2a2802309c67084d87fbd5066d9a372c40556460c8cd0348",
+    "xpedition_cli/main.py": "a799454b993578d0088600fa03f2fedddcc5c925cb9e72fa75608b502f30a1dc",
+    "xpedition_cli/reference_data.py": "0c62f966691c00c8ae79b31e80901bf91353c38bef78e8558bc5243db0465a8e"
+  }
+}

package/docs/PLACEMENT_TASKS.md

@@ -0,0 +1,99 @@
+# Selected-origin placement tasks (native smoke partial)
+
+## Scope and public references
+
+This change turns familiar selection/translate/rotate/align/distribute workflows
+into one deterministic task, not a new auto-placer or a UI click macro. Its baseline
+included confirmation concurrency PR #7 (`8e40dc910b09e5f0ca58b975739bc4bba7cef031`)
+but not PRs #4–#6; all of them, and this change (PR #10), were merged on 2026-09-18.
+
+The native binding cross-checks the published API surface in
+[SiemensEDA_Python_Interface](https://github.com/EdgarMerger/SiemensEDA_Python_Interface/blob/main/xpedition_layout/layout_ifc.py),
+blob `8d70329e7a838328affac2d62a53a3f46a34eb39`: `IMGCPCBComponent`,
+`GetPositionX/Y`, `GetOrientation`, `Anchor`, `FixLock`, `UniqueId`, `Side`,
+`UnPlace`, and `Place(x,y,orientation,bTop,eFixType,eUnit,eAngleUnit)`.
+The repository's Layout directory declares MIT. No generated interface, external
+implementation, dependency, or bundled proprietary manual was copied here.
+The community type hints are not authoritative types; notably an integer COM
+Anchor is annotated as a string. We validate the actual observations instead.
+
+[XACT](https://github.com/RedHeadIvan/XpeditionAdvancedCapabilityToolkit)
+(tree `a1945aac520cc3c7983c54a49bd6013950533ff5`, LabelAligner and AddCluster)
+informed the task-level emphasis on explicit selections and local edits. Its
+implementation was not copied. We did not adopt DRC-disabling batch patterns,
+unqualified transactions, global selection, or automatic pop-up acceptance.
+These references are evidence for API/task design, not proof of compatibility
+with XPED2604 or any licensed installation.
+
+## Two entry points
+
+`pcb placement-plan --file TASK --input OBSERVATIONS` computes targets offline.
+`pcb placement --file TASK --backend native_xpedition --project BOARD --dry-run`
+reads selected native placements and previews; repeat with the returned `--confirm`
+token to execute. The new native path requires an already-running Layout session.
+Use the installed binary's `reference` to discover exact input JSON Schemas,
+required fields, bounds, preconditions and examples. The two example files in
+`examples/placement-{task,observations}.json` exercise only offline planning.
+
+Each task selects explicit unique reference designators. Coordinates are component
+CELL ORIGINS in board millimetres, on either board side, not bounding-box centres.
+Rotation is counter-clockwise in board coordinates around an explicit origin;
+orientation changes with it. Alignment fixes one coordinate to a selected anchor;
+distribution uses explicit selection order and evenly spaced origins, not equal
+body clearances. Steps calculate a final target; only one final move per changed
+part is executed. A protected part may be an unchanged anchor, never a moved target.
+
+`Anchor` values 1/2/3 and ANY nonzero `FixLock` are conservatively protected.
+Unknown identity, side, units, placement or protection state fails closed. We do
+not interpret every FixLock bit, override a lock, support embedded/flex-specific
+placement layers, flip sides or place previously unplaced components.
+
+## Execution and failure semantics
+
+Preview never calls UnPlace, Place or Save. Confirm re-reads the preview and binds
+the selected identities, positions, angles, sides, protection and semantic task
+into the token. The adapter checks that digest again under a bounded sidecar lock
+shared by this batch entry point in the same configuration directory. Other CLI
+commands, other config directories, old versions, humans and external tools do
+not cooperate. This is NOT a global engineering lock or a full-board revision.
+
+The batch explicitly enables native placement DRC and requires read-back of that
+setting before moving anything. Parts execute serially in selection order; after
+each move and at the end, positions and identities are compared. The previous DRC
+setting is restored and checked. Save is requested once only after all selected
+targets verify. The CLI also checks the returned observed targets, not only a
+`verification.valid` boolean. Numeric tolerance is 1e-6 mm/degrees, not a clearance.
+Native quantization outside that tolerance correctly reports a mismatch.
+
+On refusal or uncertainty, stop. Earlier moves can remain; the current part can
+be unplaced. No blind rollback, all-or-none guarantee, or save of partial batches
+is attempted. Results account for every selected item as unchanged, verified,
+not_attempted, outcome_unknown or verification_failed. Execution/save failures
+are non-retryable; transport failure after submit is explicitly outcome unknown.
+Inspect the live board before another preview. There is not yet a durable operation
+journal or restart recovery. Save/close/reopen durability has one licensed record, the
+2026-09-19 smoke in [`E2E.md`](E2E.md).
+
+No routing deletion/repair or unselected placement is requested. This is not proof
+that Xpedition made no incidental changes; routing topology and whole-board DRC
+remain unchecked. Component swaps may fail because sequential placement sees the
+other part still in the target position; DRC is not disabled to make them pass.
+
+## Evidence and remaining native gate
+
+Pure planning and fake COM-object tests cover transforms, strict input bounds,
+protection, bottom-side placement, no preview mutation, one collection pass,
+per-item verification, refusals, silent failure, DRC cleanup and save uncertainty.
+CLI tests exercise preview/confirm, stale state, response mismatch, partial results,
+request counts and machine discovery. CI executes no licensed Xpedition.
+
+A licensed smoke on a disposable board (2026-09-19, [`E2E.md`](E2E.md)) covered
+top-side parts, a `FixLock` part refused as a moved target, unknown components,
+a stale preview, save/close/reopen read-back and a full DRC with no placement hazard.
+Still not run on a licensed board: bottom-side parts (`Side` is read-only and this
+tool does not flip sides), the `Anchor` states and other `FixLock` values, a
+deliberate refused move after a prior success, DRC-setting restoration, a save
+failure, and a check of unselected parts and routing afterwards (that board was
+unrouted). The first confirmed run applied part of a task and then reported it
+incomplete; its per-item report was lost, later runs did not reproduce it, and the
+cause is unknown. Runtime readiness stays beta until that native evidence exists.

package/docs/PLACEMENT_TASKS_VALIDATION.json

@@ -0,0 +1,36 @@
+{
+  "baseline": "8e40dc910b09e5f0ca58b975739bc4bba7cef031",
+  "dependency_pr": 7,
+  "run_id": "35298684673",
+  "python": "3.12.14 (main, Aug 13 2026, 02:47:42) [GCC 13.3.0]",
+  "platform": "Linux-6.17.0-1022-azure-x86_64-with-glibc2.39",
+  "baseline_selected": {
+    "tests": 3,
+    "failures": 3,
+    "errors": 0,
+    "skipped": 0
+  },
+  "full_suite": {
+    "tests": 323,
+    "failures": 0,
+    "errors": 0,
+    "skipped": 0
+  },
+  "ruff": "passed",
+  "version_sync": "passed",
+  "contract_local_only": "passed",
+  "linux_pyinstaller_offline_smoke": "passed",
+  "native_xpedition_executed": false,
+  "source_sha256": {
+    "xpedition_cli/native_placement.py": "17e4755448f5b84ace3178d467a80c344712afba76103ba73ca672200348b2ab",
+    "xpedition_cli/placement_contract.py": "9f3e683f4b999813df178d05562632279cadff4a888bf37c632b533dca6ab221",
+    "xpedition_cli/placement_command.py": "8b88867aa2af7ae00e70ab9b88f29430d506ac95ddfb0fa10cc50b052506a8fe",
+    "xpedition_cli/placement.py": "666f319f68c62d59209301f5432ad8db4eb3a46e7cbafae5418bb203151fb6d3",
+    "tests/test_native_placement.py": "6412c5f6e051fdf906585631a6229153f97f90ab5a1bfa75afe9107e1efabbfd",
+    "tests/test_placement.py": "7c682a59d8fe000a650d0c9654e21096e1d4bbbd4d06dd79da8a8aa65d0a4f65",
+    "tests/test_placement_cli.py": "cbbf719774c14fb85df21b142facba88590aace7e5b4925cc4d3bf263e2b75ef",
+    "xpedition_cli/main.py": "a0ed65de3a20c77a547316ce1b472ebdceba98ad982b5a500e559ca20efe9ef0",
+    "xpedition_cli/native_com_adapter.py": "5e5d0694ebc653f2d4da8575aa52a8500014a20b7559760a5f3f7014596a5cf9",
+    "xpedition_cli/reference_data.py": "abe1aed0bb52b875f2050eef33767f2d38cb528cb2dd9fa0c6094594680504af"
+  }
+}

package/docs/REFERENCE_ADOPTION.md

@@ -0,0 +1,67 @@
+# Public-reference adoption and evidence boundaries
+
+*Historical record: written for pull request #8 before it was merged on 2026-09-18;
+kept as the design and evidence record. The current contract is
+`xpedition-cli reference`.*
+
+This work advances engineer-level task coverage without claiming an untested
+Xpedition version behaves like someone else's installation. No third-party source
+code, manuals, binaries or library assets are included by this change. New code
+and fixtures are independently authored; links document task/API investigation,
+not a blanket license to copy upstream code. Review date: 2026-09-18.
+
+## Evidence vocabulary
+
+`public_example`: an upstream source demonstrates a task or API name.
+`offline_tested`: our deterministic code is tested against saved/synthetic data.
+`adapter_tested`: our adapter path is exercised with a simulated native object.
+`licensed_run`: an identified target installation and disposable project were
+actually used. These labels must never be silently promoted into each other.
+Historical licensed evidence elsewhere in this repo does not validate new paths.
+
+## Adoption register
+
+| Engineer task | Public reference | Our implementation / next gate |
+|---|---|---|
+| Assign pin nets from a table | XACT NetAssigner [1] | Offline plan and check implemented here; native mutation deliberately unavailable. |
+| Select the right component and pin | XACT uses active selection and integer pin comparison [1] | Explicit refdes + exact string pin IDs; ambiguous/missing observations block. |
+| Review effects on shared nets | XACT changes labels near pins [1] | Reassign is distinguished from connect/noop; bounded peer sample and total require isolation review. No promise of safe global rename. |
+| Inspect available Designer APIs | SiemensEDA interface generator [2] | Candidate for local read-only type-library inventory; no new COM execution claimed here. |
+| Batch native changes / transactions | EETB_2412 Constraint/SetPadEntry.vbs [3] | Investigate transaction and LockServer semantics on target installation; not an engineering write lock or proven rollback. |
+| React to forward-annotation completion | XACT faReporter.js [4] | Candidate event/report source. Complete warnings and result provenance required; not a substitute for fresh state validation. |
+
+[1] [XACT NetAssigner at a1945aa](https://github.com/RedHeadIvan/XpeditionAdvancedCapabilityToolkit/blob/a1945aac520cc3c7983c54a49bd6013950533ff5/NetAssigner/net_assigner.js)
+([blob 674e32f](https://api.github.com/repos/RedHeadIvan/XpeditionAdvancedCapabilityToolkit/git/blobs/674e32f4fb51c688ed66259a0cdc7cd51088a879)).
+Its workflow motivates table-based assignment; no JavaScript, CSV library or UI code
+was copied. Its active-selection, skipped-row, integer pin and success-reporting
+behavior is not our safety contract. License clearance is required before any code
+reuse; this change does not rely on such reuse.
+
+[2] [SiemensEDA interface project at 54b3c3f](https://github.com/EdgarMerger/SiemensEDA_Python_Interface/tree/54b3c3f85d9fbcf10259705e5a3a11399794c12f).
+The generator is a discovery reference, not authoritative typing for our installed
+version. A type-library member does not establish a safe or supported CLI operation.
+
+[3] [EETB batch/constraint example](https://github.com/Aragornian/EETB_2412/blob/main/Constraint/SetPadEntry.vbs).
+Prior investigation only; this mutable link is NOT a pinned implementation input.
+No transaction calls, DRC disabling or error suppression from it were adopted.
+
+[4] [XACT report workflow at a1945aa](https://github.com/RedHeadIvan/XpeditionAdvancedCapabilityToolkit/blob/a1945aac520cc3c7983c54a49bd6013950533ff5/faReporter.js).
+A future event implementation needs its own installation-specific tests.
+
+## Native integration gate
+
+Before implementing/exposing pin mutations: verify actual typed pin identity,
+component hierarchy, wire/label ownership and disconnection semantics; bind plans
+to a freshly read target; serialize engineering writes; record partial/unknown
+outcomes; compare requested postconditions and unaffected peers; save/close/reopen.
+Do not map `reassign` to existing additive `connect` and assume the old net vanished.
+
+## Tests and review
+
+Helper tests cover exact IDs, unknown and contradictory observations, duplicate
+targets, stale preconditions, post-edit checks, paging and bounded peers, malformed
+CSV/JSON and immutability. CLI tests reject native/write/output arguments before
+file/backend access, preserve JSON/trust controls and exercise both new leaves.
+The generated validation record records actual CI results. No native design is
+opened by this work. PRs #4--#7 remain independent; combined-tree behavior must be
+validated before release. Preserve all Unreleased notes when combining branches.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@fateforge/xpedition-cli",
+  "version": "1.0.0",
+  "description": "read, validate, preview, and apply controlled Xpedition design changes with mock-first verification",
+  "license": "MIT",
+  "author": "Sean Guo <guosong6886@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fatecannotbealtered/xpedition-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "xpedition-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "version": "node scripts/sync-version.js",
+    "check-version": "node scripts/check-version.js"
+  },
+  "optionalDependencies": {
+    "@fateforge/xpedition-cli-darwin-arm64": "1.0.0",
+    "@fateforge/xpedition-cli-darwin-x64": "1.0.0",
+    "@fateforge/xpedition-cli-linux-arm64": "1.0.0",
+    "@fateforge/xpedition-cli-linux-x64": "1.0.0",
+    "@fateforge/xpedition-cli-win32-arm64": "1.0.0",
+    "@fateforge/xpedition-cli-win32-x64": "1.0.0"
+  },
+  "files": [
+    "scripts/run.js",
+    "skills/",
+    "README.md",
+    "README_zh.md",
+    "*_zh.md",
+    "LICENSE",
+    "NOTICE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "AGENTS.md",
+    ".agent/",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/run.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin forwarder: exec the binary shipped by the npm platform package.
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const rootPackage = require("../package.json");
+const toolName = Object.keys(rootPackage.bin || {})[0] || "xpedition-cli";
+const ext = process.platform === "win32" ? ".exe" : "";
+const platformKey = `${process.platform}-${process.arch}`;
+const platformPackage = `${rootPackage.name}-${platformKey}`;
+const optionalDependencies = rootPackage.optionalDependencies || {};
+
+if (!Object.prototype.hasOwnProperty.call(optionalDependencies, platformPackage)) {
+  console.error(
+    `${toolName} does not ship an npm platform package for ${platformKey}.\n` +
+    "Install a supported platform package or use the GitHub standalone binary."
+  );
+  process.exit(1);
+}
+
+let bin;
+try {
+  const platformPackageJson = require.resolve(`${platformPackage}/package.json`);
+  bin = path.join(path.dirname(platformPackageJson), "bin", toolName + ext);
+} catch {
+  console.error(
+    `${toolName} platform package ${platformPackage} is not installed.\n` +
+    "This usually means npm optional dependencies were omitted.\n" +
+    `Reinstall with:  npm install -g ${rootPackage.name} --include=optional`
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  if (e.code === "ENOENT") {
+    console.error(
+      `${toolName} binary not found inside ${platformPackage}.\n` +
+      `Reinstall with:  npm install -g ${rootPackage.name} --include=optional`
+    );
+  }
+  process.exit(e.status || 1);
+}