# Project Map: Firmware Candidate Identity and Exact Work5 Promotion

Status: approved
Type: project-map
Updated: 2026-09-08
Source Idea: IDEA-0005
Requested Endpoint: work5
Next Action: execute PRM-0009
Campaign: standalone

## Desired outcome

Make firmware identity unambiguous from ordinary development through production release. A
developer can build freely without publishing releases, Work2 or Work3 can freeze an immutable
development candidate, every programming or qualification operation can prove which bytes it
consumed, and Work5 promotes exactly those qualified bytes while closing the complete authoritative
release cohort.

## Settled lifecycle model

1. `build output` means the overwriteable generic e2 artifacts under `Debug/` or `Release/`.
2. `development candidate` means an immutable local bundle under ignored
   `.firmware-candidates/candidates/<candidate-id>/`, containing copied ELF, map, and S-record
   artifacts plus a canonical JSON manifest. An atomically replaced ignored
   `.firmware-candidates/current.json` points to one verified bundle.
3. `production release` means the same manifest-bound bytes after exact candidate qualification,
   release-cohort freeze, publication, and production verification. A tracked provenance manifest
   and the GitHub Release refer back to the candidate manifest digest and artifact hashes.

No filename, timestamp, e2 configuration, embedded production macro, or Tool Shed lifecycle label
alone establishes release identity.

## Design decisions

- Use one schema for Work2 and Work3 candidates. A candidate records its endpoint and may contain
  one or both configurations; Work3 and Work5 require both Debug and Release.
- Bind candidates only to a clean committed source state. The manifest records full source commit,
  Git tree, firmware-affecting tree digest, firmware version/build type, toolchain identity, and
  every artifact path, size, and SHA-256. Dirty source fails closed instead of creating a candidate.
- Keep immutable bundles and the current pointer ignored because build products are local evidence;
  track their schema, commands, tests, documentation, and Work-level policy.
- Keep Hybrid SQLite and its release cohort authoritative for pending Work5 work. Candidate status
  may query that cohort but never copies it into a second editable ledger.
- Permit production-form firmware bytes to be development candidates. The manifest remains visibly
  `NOT PRODUCTION RELEASED` until Work5 attaches release evidence; `BUILD_IS_PRODUCTION` is an
  embedded behavior/version choice, not release proof.
- Make `script/firmware-candidate.ps1` the shared entry point for create, status, validate,
  release-preflight, promote, and release-verify operations. Work-level includes invoke this
  script; they do not reproduce its policy.
- Add manifest selection to the serial-confirmed programming entry point. Loose artifact mode is
  no longer the default; compatibility requires an explicit exact path and SHA-256.
- Work5 never rebuilds after candidate qualification. Publication assets are copied from the
  immutable bundle and verified against the manifest immediately before and after publication.

## Work-level contract

- Work2 `after`: create or refresh a clean committed candidate for the configurations actually
  built and print its identity.
- Work3 `after`: create the combined Debug/Release candidate and validate it against current HEAD.
- Work4 `before`: validate current candidate identity and current HEAD before push.
- Work5 `before`: require a combined current candidate, exact complete cohort coverage, clean HEAD,
  and release readiness; `after`: verify published release evidence still matches every candidate
  hash.

The current invocation began before this policy existed, so it follows the already-resolved
standard Work5 envelope and invokes the same shared checks explicitly. Future invocations resolve
the tracked includes normally.

## Production target and release scope

The production publication target is the repository's GitHub Release for firmware `00.05.00`.
Controller A and Controller B are release-qualification benches, not customer production units.
Both must pass exact-candidate program/verify, full-flash comparison, firmware identity, SD CID,
representative-sector-read, and bounded smoke checks before publication. No powered SD-card change
is allowed. Customer rollout, ECO approval, BOM/supply change, and DCS deployment are separate
controlled processes and are not implied by publishing this firmware release.

## Non-goals

- No second release queue, artifact database, cloud artifact service, signing system, or Tool Shed
  fork.
- No destructive cleanup of historical artifacts.
- No specimen-specific USB behavior or expansion of unrelated qualification scope.
- No automatic controller programming from a build or candidate-creation action.

## Readiness gates

- G1-CANDIDATE-MANIFEST: immutable, reproducible source-and-byte identity.
- G2-CURRENT-CANDIDATE: one read-only, fail-closed current-candidate command.
- G3-MANIFEST-BOUND-CONSUMERS: programming and qualification consume the manifest identity.
- G4-WORK-LEVEL-INTEGRATION: explicit project includes call shared repository policy.
- G5-EXACT-BYTE-PROMOTION: Work5 qualifies and publishes without rebuilding.
- G6-REGRESSION-AND-DOCUMENTATION: adversarial checks and clear operator terminology pass.

