# Idea Brief: Unambiguous Firmware Candidate Identity and Exact Work5 Promotion

Status: completed
Type: idea-brief
Updated: 2026-09-08
Next Action: none; MAP-0008 and PRM-0009 completed in firmware v00.05.00
Readiness Review: run explicitly with `ts: bs review <idea-id-or-path>`; ordinary brainstorming does not review
Produces: MAP-0008

## Current Synthesis

### Idea

Establish one unambiguous, machine-verifiable identity and promotion model for SMI firmware images.
Separate overwriteable build output, verified development candidates, and published production
releases. Integrate repository-owned manifest and hash enforcement with Tool Shed Work2-Work5 so
ordinary development can continue for weeks without losing the exact image intended for the later
combined Work5 release.

### Why It Matters

The repository currently presents several plausible "latest" images. The September 8 Work3 build
produced current generic `Debug/7520553_SMI_FW.*` and `Release/7520553_SMI_FW.*` artifacts, while
the more authoritative-looking `*_00_05_00.*` copies are older. `README.md` says each managed
build creates versioned copies, but the canonical `script/vscode-e2-build.ps1` wrapper invokes
managed make and verifies only generic outputs; it does not run
`script/package-release-artifacts.ps1`. The active source also sets `BUILD_IS_PRODUCTION` to `1`
even though the accumulated image is a Work3 candidate rather than a Work5 release.

Filename, directory, timestamp, compiler configuration, embedded build mode, candidate readiness,
and production-release state can therefore disagree. That ambiguity risks programming or
qualifying stale bytes and encourages premature Work4/Work5 activity merely to obtain confidence
about which image is current.

### Desired Outcome

At any time, one read-only command identifies the current verified development candidate by source
commit/tree, embedded version and build type, Debug and Release artifact hashes, build toolchain,
release-cohort state, and promotion status. Work2 or Work3 creates an immutable candidate identity;
programming and qualification consume that identity and fail on a hash mismatch; Work5 promotes
the exact qualified bytes without an identity-changing rebuild. Generic build outputs remain
clearly disposable, and production release evidence is impossible to confuse with development
candidate evidence.

## Constraints And Non-Goals

- The repository's managed-make wrapper remains the canonical ordinary firmware builder.
- e2 `Debug` and `Release` are compiler configurations, not development/production lifecycle
  states; both may belong to one development candidate.
- Hybrid SQLite and the existing release cohort remain authoritative for pending Work5 ownership;
  do not add a second release queue.
- Tool Shed `before` and `after` actions wrap only the selected endpoint. Lower-level customization
  does not run again for Work4 or Work5, and the current hooks cannot insert a check between the
  standard Work5 freeze, qualification, and publication stages.
- Repository scripts must own artifact creation, provenance, validation, programming admission,
  and exact-byte promotion. `work/tool-shed.yaml` may require those scripts but must not become an
  artifact store or replacement release engine.
- Preserve existing firmware safety, controller identity, qualification evidence, protected
  production, and dirty-worktree boundaries.
- Do not require Direct work to create an Idea, Map, PRM, Campaign, or other document merely to
  receive release-candidate identity.
- Do not program hardware, deploy, push, publish, tag, increment a version, delete historical
  artifacts, or perform Work5 as part of discovery or planning.

## Possibilities And Tradeoffs

| Possibility | Benefits | Costs / Risks | Evidence / Status |
| --- | --- | --- | --- |
| Repository-owned build manifest plus immutable candidate bundle and atomic current-candidate pointer | Makes source and bytes explicit; reusable by programming, qualification, Tool Shed, and Work5; does not add another work queue | Requires retention/location policy and careful clean/dirty source identity | Leading direction |
| Use Work2/Work3 `after` actions to create or validate candidate identity | Automatically closes the common operator gap at the correct development endpoints | Hooks run after the standard checkpoint and are not inherited by Work4/Work5; tracked output could leave a dirty tree | Useful orchestration layer, insufficient alone |
| Use Work4/Work5 `before` and `after` validation actions | Adds endpoint-specific preflight and final verification without changing portable Tool Shed defaults | `before` is too early to prove a later frozen/published image and `after` is too late to prevent a bad publication | Defense in depth only |
| Replace Work5 with `run_default: false` and one project release script | Allows exact stage ordering inside one project-owned command | Risks duplicating Tool Shed cohort, qualification, publication, reconciliation, and safety behavior | Avoid unless planning proves no smaller safe integration |
| Put commit/hash identity directly in artifact filenames | Immediately distinguishes many candidate files | Filenames remain forgeable and cannot express full provenance or lifecycle; long names do not replace a manifest | Optional convenience, not authority |
| Treat every successful compile as a candidate | Simple and automatic | Creates noise, preserves unverified builds, and weakens the Work2/Work3 meaning | Reject |

## Open Questions

- Where should immutable candidate bundles and the atomic current-candidate pointer live, and which
  pieces are tracked versus ignored or externally retained?
- Does Work2 create a partial/focused candidate bundle while Work3 creates the combined Debug and
  Release freeze, or should both use one manifest schema with different lifecycle states?
- How will a build record its exact source tree when it runs before the final candidate commit or
  against explicitly reviewed dirty inputs?
- Which existing programming and qualification commands should accept a manifest path instead of
  a loose artifact stem, and what compatibility period is needed?
- How will Work5 bind the final cohort content commit, qualified artifact hashes, release package,
  and production verification without rebuilding different bytes?
- Are finer Tool Shed insertion points such as `after-freeze-before-push` and
  `after-qualification-before-publish` needed, or can the repository's release command safely own
  those invariants within the existing endpoint?
- Because lower-level customizations are not inherited, which shared project script should be
  explicitly invoked by Work2, Work3, Work4, and Work5 without duplicating policy?
- How should existing stale versioned artifacts be classified, archived, or rejected without
  destructive cleanup or rewriting historical evidence?
- Should ordinary development set `BUILD_IS_PRODUCTION=0`, or should production-form candidate
  builds remain allowed but carry an external `NOT PRODUCTION RELEASED` manifest state?
- Can controller read-only state expose enough build identity to verify the running image against
  the candidate manifest, or must programming/readback evidence remain the binding mechanism?
- How should the candidate manifest summarize release-cohort inclusion without duplicating cohort
  authority or inheriting the dashboard's direct-outcome visibility defect?

## Decisions

- Retire the ambiguous phrase "latest dev release." Use `build output`, `development candidate`,
  and `production release` as distinct states.
- Never select a firmware image by filename or modification time alone; require source identity and
  SHA-256.
- Generic e2 outputs are overwriteable build products, not durable handoff artifacts.
- A verified development candidate must be immutable and visibly marked `NOT PRODUCTION RELEASED`
  until Work5 evidence exists.
- Work5 must promote the exact qualified candidate bytes rather than rebuilding under the same
  version.
- Before/after work-level actions should invoke shared repository scripts and enforce results, not
  contain the identity model themselves.
- Do not create a second manual release ledger; relate candidate identity to the authoritative
  release cohort.

## Don't Forget

- Current September 8 Work3 source commit: `dc4acb608b9902f8a5a7b33e677ab4c9799bc862`.
- Current Debug S-record: `Debug/7520553_SMI_FW.srec`, SHA-256
  `255BB3B3230CCE6651E263CC3EAC0DAE5A71F1000568630BACA95D5866097EB8`.
- Current Release-configuration S-record: `Release/7520553_SMI_FW.srec`, SHA-256
  `C33CDA33C79A760BFE839503C18F5CFD4C614ADF0A00F41AF92360CF90EDB024`.
- The current `Debug/Release/7520553_SMI_FW_00_05_00.*` copies predate that Work3 build and must not
  be treated as the current candidate.
- The active release cohort contains seven awaiting-release registrations representing six unique
  candidate commits; every one is an ancestor of the Work3 candidate.
- The separate Tool Shed maintainer idea about dashboard cohort visibility may improve presentation,
  but it cannot substitute for firmware artifact provenance and programming enforcement.

## Exploration Log

### 2026-09-08

- Idea Brief created.
- Confirmed that all seven registered Work5 obligations are present in the September 8 Work3 source
  candidate, but the generic and versioned output names point at different artifact generations.
- Found that `README.md` describes automatic packaging for managed builds while the canonical
  managed-make wrapper does not invoke the packaging script.
- Explored Tool Shed work-level customization. Endpoint `before`/`after` actions can require shared
  project scripts and improve visibility, but their outer-only ordering and non-inheritance cannot
  alone prove exact Work5 binary promotion.
- Leading direction is a repository-owned immutable candidate manifest/bundle, an atomic local
  current-candidate pointer, manifest-bound programming and qualification, explicit per-endpoint
  Tool Shed actions, and exact-byte Work5 promotion.
- Semantic readiness review `38d2e6092502f5f59502fad336624d19ec15db40cc53534d80c08f9e3d4514b8`
  passed as READY-WITH-PRM-GATES. MAP-0008 captured the settled direction and transferred all six
  readiness gates without loss; PRM-0009 is the approved delivery roadmap.
- MAP-0008 and PRM-0009 completed all gates. The full seven-registration cohort shipped as
  `v00.05.00`; final content commit `fa6f1a99099c02d8359ca6723e982ce48e4529f7` and Release
  S-record SHA-256 `C33CDA33C79A760BFE839503C18F5CFD4C614ADF0A00F41AF92360CF90EDB024`
  are the unambiguous production identity. Controller A and B run those Release bytes, and the
  GitHub Release assets were independently downloaded and hash-verified.

Keep the synthesis current and append only useful dated exploration notes. Use `Status: ready-for-prm`
when the owner chooses to promote it, `promoted` after approved project-map direction captures it,
or `parked` when it is intentionally set aside. A promoted brief names its output in `Produces:`.
