@protoboardai/ext-release 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Protoboard Stack: @protoboardai/ext-release
+Copyright 2026 Delta Robotics, Inc.
+
+This product includes software developed at Delta Robotics, Inc.
+(https://deltaroboticsinc.com).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+See the LICENSE file in this package for full terms.
+
+"Protoboard", the Protoboard logo and the "0" mark are trademarks of
+Delta Robotics, Inc. The License grants no rights to them (section 6);
+see TRADEMARKS.md in the Protoboard Stack repository
+(https://github.com/Delta-Robotics-Inc/protoboard-stack).

package/README.md

@@ -1,3 +1,291 @@
-# Temporary Holding Version
+# @protoboardai/ext-release
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`protoboard release` and the Manufacturing Package
+([releases, package, SOPs and evals](../../docs/specs/release-package-and-evals.md)
+§1–§3). A release refuses a project that is not clean, then
+writes everything needed to order, make, assemble and check the product to
+`release/<version>/`, laid out by unit, with a manifest that a rebuild in a
+clean environment reproduces byte for byte. It never orders, uploads or
+prints anything, and never calls a service.
+
+| Kind | Id | What |
+| --- | --- | --- |
+| Operation | `release` (export; tool `chrome`) | The package; inputs `version` (default: the root module's `version`), `allow-dirty`, `check` (preconditions only). `protoboard release [--version <v>] [--allow-dirty] [--check]` runs it. |
+| Operations | `package:spec`, `package:bom`, `package:work-order`, `package:assembly`, `package:test-plan` (pure) | The release's own section content, from the model and the collected files: identity and interfaces with ratings; module breakdown and ordering list; ordering checklist, fabrication orders, operations and kitting; plain assembly steps when nothing richer is installed; the basic test plan |
+| Skill | `release` | The SOP: choose units, clear the preconditions, release, inspect |
+| Tool | `chrome` | Headless Chrome for the unit figures and the PDFs (@protoboardai/ext-docs' renderer) |
+
+```ts
+// protoboard.config.ts (or the default export of release.config.ts)
+extensions: [..., "@protoboardai/ext-release"],
+release: {
+  units: ["stack", "quadcopter-5in-arm"], // instance paths or module ids; the root is always a unit
+  build: 1,                                // products to build: ordering quantities × build
+  spares: { fastener: { percent: 20, min: 4 } }, // by part id, tag or category; overrides the defaults
+},
+```
+
+## The package
+
+```
+release/<version>/
+  00-overview.pdf      the cover, then the product page (what it is, features, functions, requirements with how
+                       each is shown, from docs/product.json), units, order of work, index of files, traceability appendix
+  index.html           all of it, navigable by unit and by section (assets/ holds its figures and Kode Mono)
+  manifest.json        protoboard.release/v0
+  system/              the root unit: final assembly
+    spec-sheet.pdf  bom.pdf  bom.csv  ordering-list.csv  work-order.pdf  assembly-guide.pdf  test-plan.pdf
+    files/model/uhd-bundle.json      the released model (artifact bases relative to the project)
+    files/firmware/…                 configurations other extensions contribute (ext-drone: betaflight-cli.txt)
+  units/<unit>/        one per release.units entry, same layout (no ordering list)
+    files/boards/<module>/           circuit: gerber/ (layers and drill), bom.csv, pnp.csv, board.step, board.glb
+    files/mechanical/<module>/       cad: <module>.step and the process exports (<module>.stl, .3mf, .dxf)
+    files/harnesses/<module>/        cad on a cable: routed <module>.step and .glb; cut-list.csv from the model
+```
+
+**Units.** An instance path makes that instance a unit (folder: the path with
+`/` as `.`); a module id makes every instance of the module one unit, built
+once per instance. Every other instance folds into the nearest unit above it.
+A unit inside another is built first; the root (`system/`, final assembly) is
+last. A unit named by path may not sit inside one build of a module unit that
+is built several times (the builds would differ). Files of a custom module go
+to every unit that builds it.
+
+**Files** come only from the providers' standard outputs (`<module>/out/`),
+never from native files, renamed as above. The cut list is derived from the
+cable's UHD facts (`performance` kind cable, `cable_build`, the conductor
+link between its ends); a cable the unit makes or cuts without a cad
+provider gets `files/harnesses/<module>/cut-list.csv` too, and the work order
+and test plan name a cut list only when the package holds it.
+
+## Preconditions
+
+Nothing is written unless all of these hold (`--check` reports them):
+
+| Code | Rule |
+| --- | --- |
+| `REL_CHECK_ERRORS` | `protoboard check` has no errors. |
+| `REL_STALE` | No provider finding ends in `_STALE` (warning or error). Every bound module has a recorded `<capability>:export` made with the current config file (digest) and provider, and, when the record has it, the current module (`capability.moduleDigest`, recorded by core since Stack 0.1). `out/` holds exactly the files that record lists, with its digests. Every file any operation record wrote is still the bytes its latest writer wrote (earlier packages under `release/` excepted: a release replaces its folder). |
+| `REL_FRESHNESS_UNKNOWN` | No provider check was skipped: a skipped check cannot show its outputs are current. |
+| `REL_NOT_EXPORTED` | Every bound module has standard outputs. |
+| `REL_DIRTY` | In a git work tree, no uncommitted changes outside `release/` and `operations/` (`--allow-dirty` records them in the manifest instead). |
+| `REL_UNIT_INVALID`, `REL_CONFIG_INVALID`, `REL_NO_VERSION` | The configuration resolves. |
+| any error a section returns | e.g. ext-drone's `DRONE_CLI_STALE` when the flight-controller configuration no longer matches the model. |
+
+## Section contract
+
+An extension contributes to a section by declaring an operation
+`package:<section>` (`spec`, `bom`, `work-order`, `assembly`, `test-plan`;
+effect `pure`). The release calls it once per unit, the others in
+configuration order and the release's own entry last (so its work order can
+number what they contribute), and renders what it returns into that unit's
+PDF and `index.html`, the release's own content first.
+
+```ts
+import type { SectionFn } from "@protoboardai/ext-release";
+
+export const workOrder: SectionFn = ({ project, unit, units, release, files }) => {
+  if (unit.kind !== "root") return undefined; // nothing for this unit
+  return {
+    title: "Flight controller configuration", // its own numbered part of the document; omit to join the main body
+    order: 20,
+    blocks: [
+      { kind: "paragraph", text: "…" },
+      { kind: "table", columns: [{ key: "item", label: "Item" }], rows: [{ item: "…" }] },
+    ],
+    // work order only: operations the release numbers with its own (OP 10, 20, …)
+    operations: [{ stage: "configure", title: "Load the configuration", actions: ["…"], test: "…" }],
+    files: [{ path: "files/firmware/betaflight-cli.txt", from: "firmware/betaflight/cli.txt", role: "firmware-config" }],
+    diagnostics: [], // an error stops the release
+  };
+};
+```
+
+Blocks: `heading`, `paragraph` (`keep` holds it on the page of the next
+block), `list`, `keyvalues`, `figures` (key figures), `table` (with `{ group
+}` rows; `nowrap` columns), `note` (tip, caution, warning), `steps` (an id,
+actions, parts with thumbnails and letters, a figure with callouts, a table,
+tools, materials, torque, inspection, the test that follows, notes, trace),
+`image` (with lettered `callouts`; `size: "small"`) and `kit` (a grid of
+items with thumbnails). Files go under the unit folder (`files/…` for
+manufacturing files; a unit-level data file such as `bom.csv`); a `from`
+path is copied from the project, and the manifest traces it to the operation
+record that wrote it. Types: `lib/types.ts`.
+
+The context also carries:
+
+- `figure(name, spec)`: renders an ext-docs `RenderSpec` (line art or
+  shaded, from served GLB paths, `project/<path>`) with the release's Chrome
+  into `assets/images/<name>.png` and returns its package path, size and
+  anchor positions (for callouts). A name is rendered once per release; the
+  same name with another spec is an error. Figures are rendered before the
+  documents, one Chrome at a time.
+- `contributors`: the extensions contributing to this section, so a
+  baseline can step aside (the release's plain assembly steps give way to
+  ext-docs' illustrated ones).
+- `operations`: for the release's own work order, the operations the others
+  returned. A `configure` operation (flash firmware, load a configuration)
+  runs after the assembly steps, between the power-up checks and the rest of
+  the bench test, and so before the steps that must follow the test.
+
+`@protoboardai/ext-release/helpers` gives contributors what the release
+knows: the custom modules a unit builds (`unitModules`, `providerModules`),
+how many per build (`perBuild`), the files collected for one
+(`moduleFiles`), its JSON standard outputs (`readOutput`), a GLB's size
+(`glbBox`), the cut list and the bill of materials.
+`@protoboardai/ext-release/testing` builds the units and contexts of a project
+for a contributor's tests, recording figures instead of rendering them.
+
+## Bills of materials (PK2)
+
+- **`bom.csv` / `bom.pdf`** per unit: one build's module tree (sub-assembly →
+  board → components), one row per instance with quantity per build and per
+  product, make/buy, manufacturer, MPN, tier and origin. A board's components
+  are its UHD children; the circuit provider's `out/bom.csv` is merged by its
+  `instance` column for value, package and MPN where the model has none.
+- **`system/ordering-list.csv`**: every item to obtain for the whole product,
+  one line per part. Quantities come from the instance tree (independent of
+  the units). `needed = per product × build`; `spares = max(ceil(needed ×
+  percent / 100), min)` by the first matching rule: `release.spares[part id]`,
+  `release.spares[tag or category]`, then the defaults: mechanical hardware
+  (category `hardware` or tag `fastener`) 10 %, at least 2; components placed
+  on a board 5 %, at least 2; nothing else. `order` rounds `needed + spares`
+  up to whole packs (the offer's own, else the `pack_quantity` the model
+  states) and the chosen offer's minimum, and goes up to a later price break
+  where that costs less in all (`offer_flag` then says what the smaller
+  order would have cost). Parts that ship with another (`included_with`) are listed with
+  order 0; custom parts, boards and cables not included with a part are
+  `fabricate` lines.
+- **Offers, offline only**: catalog offers vendored by `protoboard parts
+  offers` into `parts/offers.json` (`protoboard.offers/v0`), sourcing evidence
+  in `parts/evidence/<id>/sourcing.json` (@protoboardai/ext-sourcing: price
+  breaks, stock, lead time, lifecycle, alternates), and as a last resort a
+  supplier listing the model cites (a `usage_note` starting "Supplier
+  listing:"; where to buy, no price). Each catalog offer names the MPN it is
+  for, so a series passive's values are priced by their own offers. A value
+  with no offer for its own MPN stays unpriced; it is never priced by
+  another value's offer.
+- **One quote, the bill of materials'** (docs/specs/bom.md §3.8). A
+  bought line is quoted by the model the bill of materials uses
+  (ext-sourcing `quoteHeldLines`), so a release and `protoboard bom` agree
+  on supplier and price for the same pieces: the offer a person chose for
+  the line in `parts/bom.json` (flagged "chosen in the bill of materials"),
+  else, in order, an offer with a price; not a full reel for fewer than a
+  reel (that line stays unpriced and says so in `offer_flag`, the reel
+  listed in `offer_alternatives`; a reel the quantity fills is quoted and
+  flagged); stock that covers the order or is not stated; a current price
+  before a stale one; the lowest cost of the order in dollars. Every price
+  is in US dollars: `unit_price`, `currency` (`USD`) and `extended`. An
+  offer in another currency is converted with the project's dated rate
+  table (`parts/fx-rates.json`, else the Stack's) and marked:
+  `supplier_unit_price`, `supplier_currency`, `fx_rate` and `fx_date` carry
+  the supplier's own price and the rate, `offer_flag` says "converted from
+  EUR at 1.1177 (2026-10-07)", and the PDF's price reads "(from EUR)". An
+  offer in a currency the table lacks is not quoted. The cost estimate is
+  the sum of the lines; its note names the currencies converted and the
+  table's date, and it says how many bought lines are priced. `currency` in
+  protoboard.config.ts no longer changes a release's quotes. The only
+  difference from the bill of materials is the quantity: a release adds
+  spares.
+
+## Work order, assembly guide and test plan (PK3–PK5)
+
+The three documents follow one sequence: the unit's assembly plan from
+`@protoboardai/ext-docs/plan` (the doc spec's steps, then automatic ones,
+scoped to the links the unit makes; a board's nets are its copper, not
+steps). The release's own content:
+
+- **Work order.** Ordering checklist from the ordering list (the whole
+  product on the root, the unit's own items elsewhere), with supplier, lead
+  time and minimum order where an offer or sourcing record states them and
+  "unknown" otherwise. Fabrication orders, one line per made part, pointing
+  at the provider's details below. Operations, numbered OP 10, 20, …: kit and
+  incoming inspection (first-article ids), board assembly, cutting and
+  preparing cables whose installed length is shorter than supplied, one
+  operation per assembly step (parts, tools, materials, torque, an inspection
+  point and the joint check that follows), then the bench test. With
+  contributed `configure` operations the test is split around them: power-up
+  checks (before power, power-up, rails, current), the configuration, then
+  the checks that need firmware (programming, bus scans, smoke tests). Steps
+  that must follow the test come next: a step that fits propellers, or one
+  the doc spec marks `after: "test"` (the quadcopter's battery); then a final
+  check with the functional checks on the finished product. A sub-unit with
+  such a step gets a `REL_AFTER_TEST_IN_SUBUNIT` warning, since it is built
+  before the product's own test. Kitting: what
+  each operation consumes and where it comes from (ordering-list line,
+  fabrication order, sub-unit folder, the part it ships with).
+- **Assembly guide.** Contributed by ext-docs (illustrated steps); the
+  release's plain steps only when no other extension contributes, from the
+  same plan as the work order (its "Assembly guide step N" is step N). A part
+  whose connectors ship loose (UHD `connector` trait `supplied: "loose"`, a
+  shield's header strips) gets a soldering step first, with a solder-joint
+  check. A mate the scene could not place (no geometry) lowers the
+  component-side part onto the structure-side one (the shield onto the UNO).
+- **Test plan** (basic v0.1, marked so). First-article inspection of each
+  part designed in the project: overall size from its GLB, thickness, hole
+  patterns from its bolt-pattern interfaces, seal glands, features present;
+  boards bare and assembled; cables' length and conductor order. One joint
+  check per assembly step. Bring-up of what the unit powers: before power,
+  power-up current-limited (a battery's voltage in its place, a board's
+  undriven edge nets, power inputs nothing in the unit feeds), each rail at
+  its design voltage (board nets, regulated outputs of purchased modules),
+  current against the model's supply budget (`supply_budget`) and
+  `docs/power-budget.md` when the project has one, programming and boot on
+  the reachable USB/SWD/JTAG ports, an I2C scan per controller with the
+  addresses the parts state, and a smoke test per signal link. Functional
+  checks, one per requirement of `docs/brief.md` (ID tables, requirement
+  tables, top-level and requirement-section bullets), on the root; a
+  table's How, Pass and Record columns give the check's method and
+  criterion, otherwise they follow the requirement's wording. A rail that
+  passes an input through (the same voltage range as one of the part's
+  inputs) reads the supply's voltage. An input the model marks as left
+  unconnected on purpose (UHD `ChildModuleRef.unconnected`, with a reason)
+  gets no bench supply; when a rail can only read such an input (a motor
+  shield's outputs with its motor terminal open), a "Temporary supply" check
+  on that input comes first and those rails are measured with it on. The
+  I2C scan lists every address a device answers at: its `i2c_address` and
+  each `i2c_address_<name>` it states (a PCA9685's all-call 0x70). Project checks (`release.checks`) join
+  the bring-up, numbered power-phase first. Records to
+  capture, and `files/test/test-record.csv` with one row per check.
+- **Builds that differ.** A unit named by module id is built once per
+  instance from one plan. Where the instances differ in what their parent
+  sets (`spin`, `overrides`), the plan names the value per build where a step
+  depends on it (the propeller's hand by the motor's spin at each position),
+  the work order and guide say how the builds differ, and a difference no
+  step accounts for is a `REL_BUILDS_DIFFER` warning.
+- **Counts.** A wiring step's actions and its joint check count the same
+  thing: the conductors of the step's table (pin rows), in links.
+
+Providers add their parts: ext-tscircuit the board fabrication and assembly
+order, ext-frame-cad the cut order and its inspection, ext-enclosure-cad the
+print order and the enclosure checks, ext-harness-cad cable preparation,
+terminations and routing checks, ext-docs the spec sheet's designed parts
+and the illustrated assembly guide, ext-drone the flight-controller
+configuration and bench check.
+
+## Reproducibility
+
+The manifest holds no clock time and no machine path. The release date is
+`SOURCE_DATE_EPOCH`, else the source commit's date. Chrome writes the print
+time and its DOM node counter into each PDF; both are normalised (same
+length, so the cross-reference table holds). Figures are rendered with
+SwiftShader. The fonts the PDFs were printed with are listed with digests,
+since other fonts give other bytes. Rebuilding a version replaces its folder.
+
+## Tests
+
+`test/release.test.ts` (from the repository root, `npm test`): requirements
+read from a brief, test-id ranges, an earlier package not held against the
+project, unit folding
+and invalid entries; unit BOMs with the provider's BOM merged; ordering
+quantities with spares, packs, MOQ, offers from both offline sources and
+included parts; each precondition refusing (check errors, edited, extra and
+missing outputs, a changed config, an earlier module, no export, uncommitted
+changes); PDF normalisation; and, with Chrome, the package layout, files
+from the standard outputs, the manifest, operations and test ids in
+index.html, a CLI refusal, and two releases with identical bytes. The
+fixture uses core's fake providers. Contributors test their parts with
+`@protoboardai/ext-release/testing` (ext-docs, ext-frame-cad and
+ext-harness-cad on the quadcopter, ext-enclosure-cad on a written build
+report, ext-tscircuit with the IMU tile board, which also exercises the
+release's bring-up checks for a custom board).

package/evals/release-after-hand-edit/case.json

@@ -0,0 +1,59 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Cut a release of the smart bottle after a generated file was edited by hand",
+  "skills": ["release", "circuit-board", "enclosure-cad"],
+  "tags": ["release", "package"],
+  "requires": ["chrome", "python-build123d", "tscircuit-node"],
+  "fixture": {
+    "from": "../../../../examples/smart-bottle",
+    "exclude": ["release"],
+    "operations": true,
+    "steps": [
+      { "note": "the seed: someone swapped the LED driver's MPN in the board's generated BOM", "replace": { "file": "src/boards/bottle-cap/out/bom.csv", "find": "LP5024RSMR", "with": "LP5024RSMT", "count": 1 } }
+    ]
+  },
+  "instruction": "Cut release 0.1.1 of the smart bottle with `npx protoboard release --version 0.1.1`: the Manufacturing Package for the cap board, the cap housing and final assembly. The design itself has not changed since 0.1.0 and must not change now: do not edit the UHD model, the parts or the module configs. Bring the project to a releasable state the way the release SOP says, cut the release, then check the package. Tell me what blocked the release and how you cleared it, and the package digest.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *"] },
+  "budget": { "turns": 40, "seconds": 1800, "usd": 6 },
+  "graders": [
+    {
+      "id": "package-written",
+      "kind": "files",
+      "exist": [
+        "release/0.1.1/index.html",
+        "release/0.1.1/manifest.json",
+        "release/0.1.1/00-overview.pdf",
+        "release/0.1.1/system/work-order.pdf",
+        "release/0.1.1/system/ordering-list.csv",
+        "release/0.1.1/units/board/work-order.pdf",
+        "release/0.1.1/units/board/test-plan.pdf",
+        "release/0.1.1/units/cap/work-order.pdf"
+      ]
+    },
+    { "id": "overview-pdf", "kind": "format", "file": "release/0.1.1/00-overview.pdf", "format": "pdf" },
+    { "id": "manifest", "kind": "facts", "file": "release/0.1.1/manifest.json", "facts": [{ "path": "schema", "equals": "protoboard.release/v0" }, { "path": "version", "equals": "0.1.1" }, { "path": "check.errors", "equals": 0 }, { "path": "packageDigest", "matches": "[0-9a-f]{12}" }] },
+    { "id": "bom-as-exported", "kind": "digest", "file": "src/boards/bottle-cap/out/bom.csv", "equals": "sha256:cb00f59c0ab4281cab665f65686972ba1b0ae99f6390a61e60c7e96ba11343b2", "description": "the board's BOM is what circuit:export writes, not the hand edit" },
+    { "id": "package-bom-mpn", "kind": "text", "file": "release/0.1.1/units/board/bom.csv", "matches": ["LP5024RSMR"], "notMatches": ["LP5024RSMT"] },
+    { "id": "blocker-named", "kind": "text", "matches": ["bom\\.csv", "(edit|chang|modif)"], "description": "the answer names the hand-edited BOM" },
+    { "id": "model-untouched", "kind": "digest", "file": "src/boards/bottle-cap/bottle-cap.uhd.ts", "changed": false },
+    { "id": "circuit-config-untouched", "kind": "digest", "file": "src/boards/bottle-cap/circuit.config.ts", "changed": false },
+    { "id": "cad-config-untouched", "kind": "digest", "file": "src/enclosures/bottle-cap/cad.config.ts", "changed": false },
+    { "id": "project-config-untouched", "kind": "digest", "file": "protoboard.config.ts", "changed": false },
+    {
+      "id": "inspection",
+      "kind": "rubric",
+      "files": ["release/0.1.1/manifest.json"],
+      "rubric": "The agent cut release 0.1.1 of the smart bottle after a hand edit to a generated file blocked it. 1. The answer says what blocked the release (the board's out/bom.csv changed after circuit:export wrote it) and that it was cleared by re-running the generating operation, not by editing the file or the records, and names any further stale output it had to regenerate. 2. The release was not forced (no --allow-dirty, no edited operation records). 3. The answer reports the package digest as the manifest shows it. 4. The answer reports what it inspected in the package (units, documents, warnings carried into the manifest) and states remaining warnings honestly rather than claiming a clean bill of health."
+    }
+  ],
+  "solution": [
+    { "protoboard": ["release", "--check", "--version", "0.1.1"], "expect": { "exit": 1 } },
+    { "protoboard": ["run", "circuit:export", "--module", "bottle-cap-board"], "expect": { "status": "succeeded" } },
+    { "note": "the enclosure is stale only when the re-exported board body differs from the one it was designed around; regenerating it is the SOP either way", "protoboard": ["release", "--check", "--version", "0.1.1"] },
+    { "note": "the cap is fitted to the board body: regenerated whether or not the re-export changed it (a re-export that is not reproducible makes it ENCLOSURE_STALE, PB-869)", "protoboard": ["run", "cad:generate", "--module", "bottle-cap-enclosure"], "expect": { "status": "succeeded" } },
+    { "protoboard": ["run", "cad:export", "--module", "bottle-cap-enclosure"], "expect": { "status": "succeeded" } },
+    { "protoboard": ["release", "--check", "--version", "0.1.1"] },
+    { "protoboard": ["release", "--version", "0.1.1"], "expect": { "status": "succeeded" } },
+    { "say": "protoboard check reported PB_OUTPUT_STALE and release --check refused: src/boards/bottle-cap/out/bom.csv was changed after circuit:export wrote it (LP5024RSMR edited to LP5024RSMT). I re-ran circuit:export for bottle-cap-board, which restored the BOM (the same inputs, so the same board.step and board.glb), then regenerated and exported the cap enclosure around the re-exported board (the release SOP: a board export can make its enclosure stale). release --check then passed and release 0.1.1 wrote 3 units, 16 documents; the manifest's packageDigest is in release/0.1.1/manifest.json. The manifest carries 3 warnings: two FW_STRAPPING_PIN on the I2C lines and ENCLOSURE_THIN_WALL." }
+  ]
+}