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

Status: active
Type: ticket
Updated: 2026-09-03
Next Action: inventory and separate the current dirty paths into coherent owned change sets, then perform the Tool Shed `fresh-handoff` mitigation without resetting, reverting, deleting, or combining unrelated work
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

- [ ] Every dirty path has a recorded disposition and no owner work is lost.
- [ ] `workspace_preflight.py` reports neither `DIFF_BYTES` nor `HARD_DIFF_LIMIT`.
- [ ] The 14 Tool Shed-managed changes are checkpointed or otherwise reconciled to their intended state.
- [ ] `review_work_state.py --strict` reports zero findings.
- [ ] `check_stale_paths.py` reports zero stale paths.
- [ ] `document_store.py audit` remains `CLEAN` with zero semantic findings and no unmanaged writes.
- [ ] `doctor.py --strict` reports `HEALTHY`.
- [ ] 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.

## 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
```
