Manufacturing operating system plan

Status: approved — Phases 1–3 complete; Phase 4 candidate merged, physical acceptance pending, 2026-09-21
Decision owner: Angel
Owners after approval: Engineering, Manufacturing, Quality, Purchasing
Systems: product repositories, GitHub, Universal Tester, tester API, InvenTree ERP, fixtures, printers, engineering notebook

Purpose

Create one scalable and traceable operating system for taking an electronic product from prototype through purchasing, assembly, test, quarantine, repair, production release, finished inventory, service, and retirement. A person or AI should be able to determine the current state, the permitted next actions, the evidence required, and the applicable instructions without relying on memory.

This is a plan, not an active procedure. It does not change production behavior. Approved repeatable procedures become SOPs under SOP-000 Document Control, and implementation must preserve the working behavior in robot-board-quarantine-rework-plan.

Outcome

The completed system will provide:

1. One source of truth for every kind of record.
2. Permanent identifiers for products, parts, revisions, physical units, fixtures, firmware, workflows, tests, and transactions.
3. Versioned state machines that define allowed lifecycle transitions.
4. A single Universal Tester application that identifies the fixture and board, obtains the required stage, validates compatibility, and executes the approved workflow.
5. Product repositories created from a standard GitHub template with hardware, firmware, manufacturing definitions, AI instructions, and validation already present.
6. ERP product definitions covering parts, manufacturer parts, approved alternatives, BOM revisions, assemblies, routings, inventory, purchasing, costs, quarantine, and scrap.
7. Immutable event history connecting every physical unit to its design, material lots, firmware, workflow, fixture, measurements, failures, repairs, and final disposition.
8. Guided screens that show people only valid next actions.
9. Controlled APIs that give AI the same rules and permissions as people, rather than allowing direct database changes.
10. Reconciliation, alerts, backups, recovery, and periodic audits that expose missing or conflicting records.

Operating principles

The system must carry the process

People and AI should not have to remember the workflow. The ERP and workflow service expose the current state, missing evidence, permitted actions, required role, and resulting inventory effect. The Universal Tester renders those actions consistently.

Instructions guide; software enforces

AGENTS.md, SOPs, and work instructions explain the rules. Schemas, validators, permissions, state machines, CI, protected reviews, and server APIs enforce consequential behavior.

One fact has one authoritative home

Record	Authority
Product design and hardware revision	Product GitHub repository
Firmware source	Product GitHub repository
Released firmware binary and checksum	Immutable GitHub release/artifact store
Test-step implementations and UI contract	Universal Tester repository
Board workflow definition	Product repository, released with an exact hash
Fixture design, pin map, firmware, and self-test	Fixture repository
Approved production combination	ERP release registry
Parts, manufacturer parts, suppliers, prices, stock, builds, serials, and work orders	ERP
Measurements and test attempts	Tester results service, linked to ERP
Quarantine, repair, scrap, and disposition	ERP
Procedures	SOP site and its versioned Notes source
Plans and engineering decisions	Engineering notebook

Other systems may hold verified caches or links. They do not independently redefine the record.

Every physical and digital object has an identity

The identifier standard must cover products, internal parts, hardware revisions, prototypes, production serials, fixtures, test stations, firmware artifacts, workflow releases, test attempts, work orders, quarantine cases, repairs, deviations, engineering changes, qualifications, and inventory transactions. Identifiers are never reused.

History is appended, not rewritten

Measurements, failures, repairs, releases, and corrections remain visible. A correction creates a new event that references the original. A passing retry never deletes the failure that preceded it.

System model

Product repository ── design, BOM intent, workflow and firmware source
        │
        ├── GitHub CI ── schemas, ERC/DRC, builds, simulation and release package
        │
        ▼
Approved release registry ── exact compatible combination and activation state
        │
        ├── ERP ── parts, builds, inventory, serials, lifecycle and cost
        │
        └── Universal Tester ── deterministic execution and local durable queue
                      │
                      ▼
               Test-results service ── attempts, measurements and attachments
                      │
                      ▼
               ERP state transition and reconciliation

Product repository standard

The existing decision in project-template remains the foundation: one repository per product, with a manifest that may link external repositories where necessary.

product-repository/
├── AGENTS.md
├── product.yml
├── hardware/
│   └── <board>/
├── firmware/
│   ├── application/
│   ├── manufacturing_test/
│   └── shared/
├── mechanical/
├── artwork/
├── manufacturing/
│   ├── board.toml
│   ├── bom.toml
│   ├── assemblies.toml
│   ├── routing.toml
│   ├── inventory.toml
│   └── approved-parts.toml
├── test/
│   ├── workflow.toml
│   ├── fixture-requirements.toml
│   └── images/
├── docs/
├── tests/
└── .github/workflows/

The template provides structure, schemas, examples, CI, AI rules, and release packaging. Each product owns its actual design, limits, compatible revisions, instructions, and artifacts.

Universal Tester standard

The station uses one application and a shared runner. TOML describes the approved order, limits, operator text, artifact references, and inventory stage. Reviewed Python implements hardware protocols, safe power sequencing, cleanup, parsing, and instrument drivers. TOML cannot execute arbitrary Python or shell commands.

The standard runtime sequence is:

Discover station and instruments
→ Read fixture identity before powering the unit
→ Load the approved local board plugin
→ Identify or scan the unit
→ Ask the server for its required stage
→ Validate board + fixture + workflow + firmware + calibration
→ Execute the workflow
→ Save the complete result locally
→ Submit once using an idempotency key
→ Receive server acknowledgement
→ Present the next allowed action

Standard screen states are Startup, Identification, Ready, Running, Passed, Failed, Quarantine, Rework Return, and Blocked. Screen positions, colors, buttons, status language, duplicate protection, and accessibility are shared. Product TOML supplies only the product-specific title, instruction, diagram, units, limits, approved choices, and troubleshooting text.

Production failure behavior remains the approved simple flow:

PASS → Test next board
FAIL → Retest or Quarantine
Quarantine → print bag label and repair traveler → Test next board
Repair complete → return to the server-selected required test stage

Firmware and fixture control

Manufacturing-test firmware may expose fast deterministic hardware commands. After those tests pass, the workflow installs and verifies the exact production firmware. A unit cannot be released with manufacturing-test firmware installed.

Every artifact is immutable and selected by name, version, target, and SHA-256. Production never selects latest or an arbitrary local file. Test records retain both test and production firmware identities.

Each physical fixture has a permanent serial, hardware and firmware revision, pin-map version, calibration state, self-test result, maintenance history, and supported combinations. Unknown fixtures or incompatible revisions are blocked before product power is applied.

Prototype and production separation

Products move through Concept, Engineering Prototype, EVT, DVT, PVT, Production, and Retired maturity states.

Engineering mode permits versioned draft workflows, experimental firmware, incomplete coverage, individual-step execution, explicit optional skips, and additional evidence capture. It still records the exact commits and checksums. Engineering mode cannot create sellable finished inventory or approve a production release.

Production mode accepts only released combinations, fixed limits, calibrated equipment, complete stage execution, and ERP-controlled inventory transitions.

Every prototype receives a permanent engineering unit ID. Hand modifications are recorded as deviations against the unit's real PCB revision; they do not silently rename the board revision. Prototype failures use Engineering Hold and issue/deviation records rather than the production quarantine process.

ERP product definition

The repository declares engineering intent and references ERP internal part numbers. ERP owns purchasing, suppliers, stock, prices, actual material consumption, average cost, standard cost, and build cost.

The controlled structure includes:

• Internal parts and units of measure.
• Manufacturer part numbers and approved suppliers.
• Approved, conditional, prototype-only, rejected, NRND, last-time-buy, obsolete, and quality-hold states.
• Versioned BOMs and assembly hierarchy.
• Manufacturing routing and required test stages.
• Alternate qualification scope by product and hardware revision.
• Engineering deviations and effective serial/work-order boundaries.
• Purchased prices, labor/resource rates, material roll-up, and actual build cost.

KiCad references stable internal ERP part numbers and functional roles. Distributor SKUs, volatile prices, and supplier availability remain in ERP.

Before ERP publication, every proposed change receives a machine-generated preview showing added, removed, and changed BOM lines; lifecycle conflicts; assembly/routing changes; estimated cost effect; open work orders; and affected inventory. Publication creates a new immutable BOM or release revision. Existing build snapshots are not rewritten.

Shared manufacturing contract

A central versioned contract will contain:

manufacturing-system/
├── AGENTS.md
├── governance/
├── schemas/
├── state-machines/
├── policies/
├── templates/
├── procedures/
├── examples/
└── validators/

Each product, fixture, Universal Tester, and ERP integration release declares the contract version it implements. Updates arrive as reviewed pull requests and explicit migrations, never silent upgrades.

Core state machines cover product maturity, part lifecycle, engineering changes, board production, test attempts, quarantine/rework, fixture lifecycle, and release promotion. Each transition declares authorized roles, required evidence, inventory effect, idempotency behavior, and audit event.

People and AI

Root and nested AGENTS.md files are included by the templates. AI launchers or hooks discover the repository root, load applicable instructions, record their hashes, and run repository preflight checks. Critical behavior is still enforced by code and CI.

People use guided ERP and tester screens. AI uses the same controlled workflow API and may explain, review, prepare, reconcile, and notify. AI does not directly edit production databases, invent measurements, override failed tests, select arbitrary firmware, release quarantine, scrap inventory, or approve production combinations.

Initial monitoring roles are test reconciliation, quarantine coordination, production reconciliation, firmware/release compliance, inventory variance, fixture health, and quality trends. Deterministic services perform transactions.

Traceability record

For any unit, the system must reconstruct:

• Product, board, and hardware revision.
• Prototype or production identity.
• Work order and immutable BOM snapshot.
• Installed part and supplier lots where required.
• Deviations and engineering changes.
• Test workflow and UI-contract versions.
• Test and production firmware artifacts and hashes.
• Fixture, station, instrument, calibration, and operator.
• Every attempt, measurement, abort, failure, and attachment.
• Quarantine, repair, rework, scrap, or release history.
• Inventory transactions and finished-goods disposition.
• Applicable approvals and manufacturing-contract version.

Resilience and controls

The station saves results locally before submission and retains them until the server acknowledges the idempotent transaction. Defined recovery behavior is required for network loss, ERP outage, printer failure, station crash, interrupted flashing, power loss, duplicate submission, partial quarantine creation, and clock error.

Individual identities and least-privilege service accounts replace shared production authority. Released artifacts, audit events, BOM snapshots, and records required to explain a shipped unit are retained and backed up. Recovery is tested periodically.

Metrics have owners and thresholds: first-pass yield, final yield, retest rate, recurring failure by fixture or part lot, unsynchronized events, aging quarantine, calibration expiry, inventory variance, and release adoption.

Implementation phases

Moved out: Phases 1-3 (all complete) are in manufacturing-operating-system-phases-1-3.

Phase 4 — Robot Board end-to-end reference implementation

Move Robot configuration into its product package, add its released TOML workflow, fixture definition, artifact manifests, ERP routing, and complete screen flow. Validate in simulation and sandbox, then perform known-good, known-failure, printer, fixture, offline, quarantine, repair, scrap, and inventory reconciliation bench acceptance. Activate only after review.

Candidate implementation evidence:

• Cow Robot Board PR #11 merged as 88de848. The product repository now owns the pinned contract, Robot Cow 004B candidate compatibility release, declarative pre- and post-coating workflow, fixture definition, production firmware 4.5.0 manifest, manufacturing-test firmware 4.0.0 manifest, ERP routing, nested AI rules, CI validator, and physical bench matrix.
• Universal Tester PR #4 merged as a3cf096. Host API 1.4.0 includes the bundled Robot product package, exact release/workflow/fixture checks, hardware-driver boundary, server-authoritative routing adapter, unlimited retest or explicit quarantine session, next-stage client, and hardware-free simulation. Existing Robot launchers and Cow Tester 2.7.0 remain unchanged.
• Assistant/tester API PR #1 merged as 32f9cbd. The authenticated read-only /tester/v1/next-stage endpoint selects pre-coating or post-coating from accepted history, never advances on failure, blocks active quarantine and completed units, and rejects mixed identities. The running production service was not restarted or configured with the candidate release.
• The authoritative product release and bundled tester copy match byte for byte. Contract and cross-artifact validation report zero errors and warnings. Universal Tester passed 501 tests, 1 intentional skip, and 70 subtests; tester API passed 118 tests; firmware CI passed; the hardware-free application simulation and isolated cross-repository API sandbox passed.
• Cow Robot Board PR #13, merged as aedd64c, makes the ordered and built 004B design the sole production PCB on main, preserves retired and unreleased projects on archive/pre-production-hardware-cleanup-2026-09-21, retains the three commented manufacturer-proven DRC exclusions, and passes dedicated KiCad CI. Universal Tester PR #6, merged as 5fa3e14, syncs the resolved compatibility record.
• Candidate.2 completes the approved laptop-side Phase 4 work: Cow Robot Board PR #14 (3072045), Universal Tester PR #9 (c04b38c), and tester API PR #2 (9cd4326). Workflow 1.1.0 keeps test firmware through both stages, flashes production firmware and requires its smoke test before the final label, routes repairs according to retained evidence, and supplies an exact nonproduction API config. Eleven rehearsal scenarios passed with a dated report; 49 focused tester tests, 119 API tests, package validation, wheel build, cross-repository equality, and CI passed.

Remaining activation gate:

• Verify and permanently mark the physical fixture serial independently from its model ID.
• Run every row in manufacturing/acceptance/phase4-bench.md at the Robot station: known-good pre-coating and final boards, known board failure, fixture failure, offline replay, quarantine, repair return, scrap, printer failure, and inventory reconciliation.
• Record dated evidence and Quality/Engineering review, then make a separate change from candidate to active, install the tester API release configuration, restart the service, and deliberately switch the station launcher. Phase 5 does not start until this gate is complete.

Phase 5 — ERP product-definition and change workflow

Implement preview-and-publish for parts, manufacturer parts, lifecycle, alternatives, BOM revisions, assemblies, routings, effective boundaries, and cost impact. Add engineering build orders and prototype deviations. Preserve immutable snapshots for existing builds.

Phase 6 — Firmware and fixture release system

Build manufacturing-test and production firmware through clean CI, publish immutable manifests and checksums, support candidate promotion, and add fixture identity, firmware, calibration, self-test, cycle, maintenance, and compatibility management.

Every new Universal Tester fixture must start from one controlled fixture template and complete the same lifecycle:

1. Assign a stable fixture model ID, hardware revision, pin-map version, EEPROM magic/schema, supported product/stages, and safe-state definition. The model ID identifies the design; it must never be reused as the physical serial.
2. Create the fixture as an ERP-controlled assembly/equipment item and assign each built fixture a unique physical serial. Print the serial on a durable label and program the same value into the fixture EEPROM.
3. Use the shared EEPROM identity record with model ID, physical serial, hardware revision, pin-map version, fixture-firmware version, schema version, checksum, and provisioned state. Blank EEPROM may be provisioned only through an explicit fixture-build operation; production testing is read-only and blocks missing, corrupt, or conflicting identity.
4. Declare whether the fixture itself requires calibration. Use not_required only for passive interconnect fixtures; record separate calibration/verification for measurement instruments, camera alignment, programmable supplies, and other measurement resources.
5. Provide a versioned fixture package containing the manifest, pin map, hardware artifact hash, fixture firmware manifest, capabilities, self-test, safe shutdown behavior, maintenance interval, and acceptance matrix.
6. Pass ERC/DRC, manifest validation, unpowered identity, safe-state, continuity/routing, self-test, known-good, known-failure, and disconnect/recovery acceptance before candidate promotion.
7. Register the accepted physical serial with the tester service. At startup, the Universal Tester reads identity without UUT power, selects the compatible product workflow, and blocks any unregistered serial or incompatible model/revision/pin map/firmware combination.
8. Record fixture serial, fixture release, firmware, pin-map version, station instruments, and verification state on every test attempt. Service, repair, retirement, and replacement create append-only equipment history.

Phase 6 must migrate the two existing Cow Robot and Cow Remote fixtures as the reference examples, replace the current template behavior that defaults fixture_serial to fixture_id, and add CI rules rejecting placeholder identities, reused model IDs as serials, unknown calibration status, missing artifact hashes, and absent acceptance evidence.

Phase 7 — Prototype-to-production lifecycle

Add engineering-mode screens, prototype identities, draft workflow/artifact handling, EVT/DVT/PVT evidence, deviations, engineering holds, qualification records, and controlled production promotion. Prove the lifecycle on a real development revision.

Phase 8 — Remaining products and stations

Migrate the Remote and subsequent boards one at a time. Each migration requires representation of existing behavior, simulation, sandbox validation, physical acceptance, data reconciliation, and a reversible activation plan.

Phase 9 — Monitoring, agents, and notifications

After structured data and deterministic transitions are reliable, add reconciliation and monitoring agents. Start read-only, measure accuracy, then permit only low-risk idempotent actions such as retrying an acknowledged-safe upload. Add owned notifications and end-of-shift reconciliation.

Phase 10 — Operational maturity

Add supplier/receiving quality, calibration guard bands, golden units, controlled failure samples, training records, retention enforcement, backup recovery exercises, periodic end-to-end trace audits, KPI thresholds, and scheduled governance review.

Approved Phase 1 decisions

Angel approved all recommended defaults on 2026-09-20.

1. Reference product and revision. Use the Robot Board and its currently active production hardware revision as the Phase 1 reference. Confirm the exact hardware revision designation found in the repository/ERP before freezing the example.
2. Central contract home. Create a private EmbeddedEra/Manufacturing_System GitHub repository and link its released contract version from product, fixture, Universal Tester, and ERP integration repositories.
3. Manifest format. Preserve the already-approved product.yml decision for the top-level product manifest. Use TOML for tester, fixture, firmware, routing, and manufacturing definitions where the current Universal Tester plan engine already supports it. Do not create two representations of the same fact.
4. Identifier authority. ERP assigns internal part numbers, production serials, work orders, quarantine IDs, and inventory transaction IDs. GitHub releases assign immutable design/workflow/firmware versions. The tester service assigns test-attempt and event IDs. Prototype unit IDs should also come from ERP engineering records so physical labels and later production history stay connected.
5. Prototype inventory policy. Use engineering build orders and non-sellable engineering locations for prototypes; track actual installed material and deviations without creating finished production inventory.
6. Promotion approval. Engineering approves hardware, firmware, limits, and compatibility; Manufacturing approves workability and fixture acceptance; Quality approves production activation and disposition rules. During the current small-team stage, one person may hold multiple authenticated roles, but each approval event records the role being exercised.
7. Result storage boundary. Keep detailed append-only measurements and attachments in the tester results service, with ERP holding the board state, required summary, and links. Avoid placing large raw logs directly in ERP.
8. Retention default. Retain released designs, workflows, firmware artifacts, BOM snapshots, approvals, audit events, and shipped-unit traceability indefinitely. Define a later storage policy for bulky raw diagnostic captures that are not referenced by a shipped unit or investigation.
9. Phase 1 scope boundary. Phase 1 is documentation, inventory, schemas, representative fixtures, and scenario validation only. It does not deploy a new tester runner, change ERP production behavior, alter inventory, or activate a release.

Phase 1 is proceeding without further policy questions. Discovery resolved the shipping Robot PCB as 004B, ERP product EE-A-0002-A, ERP PCB EE-P-0002-A, current fixture identity COW-ROBOT-001, Cow Tester 2.7.0, and approved production firmware Robot_4.5.0.bin. The remaining fixture-serial and release-package gaps are recorded rather than guessed.

The private contract repository is EmbeddedEra/Manufacturing_System. Phase 1 completion is recorded at commit aa2dd53. It contains the sources-of-truth table, identifier and approval rules, retention baseline, draft state machines, version-one schemas, Robot compatibility and live-event mapping, acceptance scenarios, system inventory, gap report, and completion evidence. It makes no production changes.

Phase 1 validation passed: every JSON Schema is structurally valid; representative Robot compatibility and result records validate; all TOML parses; every state transition references declared states and declares roles, evidence, idempotency, and inventory effect; the current product manifest validates; and the observed production firmware matches its pinned SHA-256. The tester event store was inspected read-only and mapped without altering records.

Risks to control

• Building a second product template instead of extending the approved one.
• Letting ERP, TOML, and product manifests each own the same fact.
• Treating an AI instruction as enforcement.
• Migrating every product before one complete reference implementation passes.
• Rewriting current Robot history during schema adoption.
• Allowing draft prototype artifacts to become production-approved implicitly.
• Activating combinations that passed CI but were never physically accepted.
• Losing results or duplicating inventory transactions during outages.
• Treating supplier availability, obsolescence, and approved equivalence as the same state.
• Using a successful retest to hide first-pass failures.

Open

• Delete the archived temporary proof repository EmbeddedEra/Phase2_Template_Proof_20260920 when an authenticated GitHub session has delete_repo scope. It contains only the untouched template plus two empty/proof commits and no production data.

Related records

• project-template — approved one-repository-per-product and GitHub template plan.
• robot-board-quarantine-rework-plan — implemented Robot quarantine and rework behavior.
• universal-tester — current tester architecture and station operation.
• mrp — ERP model, parts, builds, inventory, traceability, and costing.
• SOP-001 Part Numbering.
• SOP-006 Assembly Builds.
• SOP-021 New PCB Design.
• SOP-022 Product Records.

Decision record

Date	Decision	By
2026-09-21	Phase 4 candidate.2 laptop work completed: workflow 1.1.0, evidence-aware repair routing, exact tester/API synchronization, and 11-scenario software rehearsal are merged. Production remains inactive until physical fixture serialization and the complete bench matrix pass.	Codex, on behalf of Engineering
2026-09-21	Approved the Robot candidate workflow direction: manufacturing-test firmware 4.0.0 is used for pre- and post-coating testing; production firmware 4.5.0 is flashed only after post-coating tests and must pass a short production-firmware smoke test before the finished-goods label. A repaired post-coating failure returns to post-coating unless the recorded repair invalidates pre-coating evidence.	Angel Diaz and Codex, on behalf of Engineering
2026-09-21	Standardize every Universal Tester fixture through one controlled template and lifecycle: model identity is separate from the serialized physical unit, EEPROM and physical labels must agree, calibration applicability is explicit, CI validates the fixture package, and unpowered startup blocks unregistered or incompatible fixtures. Robot and Remote are the first migration examples.	Angel Diaz and Codex, on behalf of Engineering
2026-09-21	Confirmed hardware/Robot Cow was the ordered and built Robot Cow 004B design. Production main now keeps that design alone at hardware/Robot-Cow-004B; retired and unreleased PCB projects are preserved on a dated archive branch. Commented manufacturer-proven DRC exclusions are accepted as the design-review evidence and KiCad CI passes.	Angel Diaz and Codex, on behalf of Engineering
2026-09-21	Phase 4 software candidate merged across Cow_Robot_Board, Universal_Tester, and the tester API. Simulation, isolated API sandbox, contract, package, firmware, and automated tests pass. Physical fixture verification and the complete bench matrix remain required; no launcher, production service, or ERP data was activated.	Codex, on behalf of Engineering
2026-09-21	Phase 3 completed in Universal Tester PR #3. The shared application, compatibility gate, attempt journal, server publication adapter, standard UI, and legacy adapter are merged; Phase 4 is ready. No physical station was activated.	Codex, on behalf of Engineering
2026-09-20	Approved all recommended Phase 2 defaults. Phase 2 completed with the tagged shared validator, updated Project Template, and disposable-repository proof; Phase 3 is ready.	Angel Diaz and Codex, on behalf of Engineering
2026-09-20	Phase 1 definition baseline completed at Manufacturing_System aa2dd53; Phase 2 is ready. No live production behavior changed.	Codex, on behalf of Engineering
2026-09-20	Approved all nine recommended Phase 1 defaults and authorized Phase 1 to proceed.	Angel Diaz
2026-09-20	Initial consolidated proposal created from the hardware, firmware, tester, ERP, prototype, alternatives, AI, traceability, and governance planning discussion.	Codex, on behalf of Engineering