# Ticket: Restore Doctor-healthy workspace without losing active firmware work

Status: completed
Type: ticket
Updated: 2026-09-03
Next Action: none; mitigation completed and Work2 candidate registered while the broader release cohort remains open
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Campaign: standalone
Campaign Reason: Repository-state hygiene and Tool Shed planning reconciliation are bounded maintenance outside the product release campaigns.

## Problem

The authoritative Hybrid document store is CLEAN at revision 521, but the broader Tool Shed Doctor is `INVALID`. The 2026-09-03 baseline reports:

- `PREFLIGHT_HARD_DIFF_LIMIT`: 18,645,947 tracked diff bytes exceed the non-overridable 10 MiB limit;
- `PREFLIGHT_DIFF_BYTES`: the same diff exceeds the adaptive 6.2 MiB workspace budget;
- `DIRTY_TOOL_SHED_STATE`: 14 Tool Shed-managed paths differ from the committed checkpoint; and
- `WORK_STATE_DRIFT`: four planning warnings remain.

The current dirty workspace contains valuable firmware, documentation, qualification, generated-build, and Tool Shed state changes. The mitigation must preserve them and must not rewrite completed Work2 history, fold later corrections into Work2, or mutate the open release cohort merely to obtain a clean Doctor result.

## Required Mitigation

1. Capture a complete path-level inventory of the dirty workspace and classify each path into one coherent owner-approved change set: completed Work2 reconciliation, later correction work, release-cohort evidence/state, generated build output, or unrelated owner work.
2. Apply the Tool Shed `fresh-handoff` mitigation using recoverable local checkpoints or commits for coherent verified sets. Do not use reset, revert, deletion, broad cleanup, or history rewriting to reduce the diff.
3. Bring the remaining tracked diff below both the adaptive workspace budget and the 10 MiB hard limit. Treat tracked ELF/S-record changes as intentional artifacts that require explicit disposition; do not discard them merely because they dominate diff size.
4. Reconcile the four current work-state warnings:
   - move the two completed-item references in the planning-bearing portion of `work/maps/map-smi-firmware-stabilization-and-qualification.md` to historical evidence or related-artifact context, or replace them with current unfinished next work;
   - review `work/runbooks/runbook-marshal-project-workspace-reconciliation.md` and refresh it only if it remains active, otherwise complete, defer, or supersede it from current evidence; and
   - review `work/wp/active/wp-build-independent-hpt-media-validator-for-pi-qualification.md` and refresh it only if work remains, otherwise complete, defer, or supersede it from current evidence.
5. Preserve the separately owned later-correction outcome loop and release-cohort state. Do not claim release completion without its independent evidence.

## Acceptance Criteria

- [x] Every dirty path has a recorded disposition and no owner work is lost.
- [x] `workspace_preflight.py` reports neither `DIFF_BYTES` nor `HARD_DIFF_LIMIT`.
- [x] The 14 original Tool Shed-managed changes plus this ticket's guarded state are checkpointed and reconciled.
- [x] `review_work_state.py --strict` reports zero findings.
- [x] `check_stale_paths.py` reports zero stale paths.
- [x] `document_store.py audit` remains `CLEAN` with zero semantic findings and no unmanaged writes.
- [x] `doctor.py --strict` reports `HEALTHY`.
- [x] Completed Work2 truth, later corrections, and the release cohort remain separately represented.

## Non-goals and Safety Boundaries

- No firmware behavior change, controller operation, hardware programming, media operation, deployment, release, or publication.
- No mutation of the workspace-local Tool Shed snapshot.
- No forced cleanup of unrelated changes and no weakening of Doctor thresholds.

## Approved Work2 Plan

### Phase 1 — Preserve and classify

- Record the exact dirty baseline and hashes before staging.
- Preserve the 27 firmware, qualification, documentation, test, and generated-build paths as one coherent service-489/FileX follow-on candidate.
- Preserve the eight workload-based endurance planning corrections as a distinct planning change set.
- Reconcile Hybrid checkpoint/index/object changes only through guarded document-store and checkpoint operations.
- Preserve `work/01-q&a/command.txt` as workspace-local operator input and add only its exact path to `.gitignore`; do not delete or reinterpret it as project truth.

### Phase 2 — Validate and checkpoint product work

- Run the focused service-489, FileX timestamp, graph-data, CID, version, and qualification model checks.
- Run the canonical managed Debug rebuild.
- Confirm the resulting ELF and S-record artifacts and record their hashes.
- Commit the coherent firmware, tests, documentation, profiles, and generated build artifacts locally. Do not push, deploy, program hardware, release, or publish.

### Phase 3 — Reconcile planning truth

- Move MAP-0003 references to finished decisions/evidence out of planning-bearing next-work context while retaining them as history.
- Keep RUN-0002 active because workspace policy still requires it; refresh its review date and current next action.
- Set WP-0001 to `blocked` because its three external operator/hardware gates remain unmet; preserve completed stages as history.
- Checkpoint the already-approved workload-based endurance edits without restoring removed 72-hour duration claims.

### Phase 4 — Close and prove

- Regenerate disposable indexes and write a guarded logical checkpoint.
- Require zero strict work-state findings, zero stale paths, a CLEAN Hybrid audit, and strict Doctor `HEALTHY`.
- Register the exact local Work2 candidate and its open direct-work outcome in the release cohort; do not close broader release or rollout outcomes.
- Report the final dashboard from the authoritative local state.

## Work2 Target Disposition

This repository has no configured development or production target. Deployment and browser checks are therefore inapplicable to this repository-hygiene outcome. Work2 target evidence is the fresh local canonical build, focused changed-behavior checks, artifact hashes, clean logical checkpoint, and strict Doctor result.

## Execution Results

- Product and build checkpoint: commit `472196ae866162b595de49df392d60930cb10ebf` covering 29 service-489, FileX, graph, CID, qualification, documentation, profile, script, source, ELF, and S-record paths.
- Planning reconciliation: commit `5e3a471fd518ab9c87ee5033ced182e947c466bb` covering the eight workload-based endurance corrections, three drift dispositions, and the exact `command.txt` ignore rule.
- Guarded Hybrid checkpoint: commit `215091293e9e5df518639434048e3ea9e934d71a`, revision 534, digest `ba120a2ae8c31c6c0a63d2f880b8c367d18b097ac73e5e92c35067898d1e7169`; independent rebuild matched the domain digest.
- Work2 release-cohort checkpoint: commit `e9ad3b0fffa8f88a6f890e6719e12af8f754adce`, revision 535, digest `961894a2c1832e501acec2cb8093b4a6211737ad7b8272001fca6fd0f41ec90a`.
- Firmware artifacts: ELF SHA-256 `324c119a7ca9f74540d67d065cc55c5ea0f46f013cbb5f58f8f01e5a7411ad7e`; S-record SHA-256 `151febb888da1af19e2e2f601a5dd877ccc4a50849f68bbbaaa3b87dbe5f54a2`; map SHA-256 `1cdc4452dd8f77105a6c65e4039fad2ff1e111b96372acbbba1a4bcf4f4126e8`.
- Verification: all focused product checks passed, the canonical managed Debug rebuild passed, release artifacts matched the stable artifacts, Tool Shed release validation passed 498/498 tests, strict work-state review reported zero findings, stale-path review reported zero findings, and strict Doctor reported `HEALTHY`.
- No owner work was deleted, reset, reverted, or force-cleaned. No controller, media, remote target, push, release, or production action occurred.

## Tool Shed Execution Defects Observed

- Embedded Work2 preparation invoked the nonexistent root path `scripts/validate_tool_shed.py` instead of the workspace-local `tool_shed/scripts/validate_tool_shed.py`. The same release profile was executed directly and passed; no gate was skipped.
- Python 3.11.2 bundled SQLite 3.39.4 rejected guarded JSON-schema writes with `unsafe use of json_valid()`. The installed Python 3.13.1 runtime with SQLite 3.45.3 completed the same guarded operations successfully.

## Verification Commands

```powershell
python tool_shed/scripts/workspace_preflight.py --workspace . --json
python tool_shed/scripts/review_work_state.py --workspace . --json --strict
python tool_shed/scripts/check_stale_paths.py --workspace .
python tool_shed/scripts/document_store.py --workspace . --json audit
python tool_shed/scripts/doctor.py --workspace . --json --strict
```
