# Runbook: Reconcile a Marshal project with workspace progress

Status: active
Type: runbook
Updated: 2026-09-03
Next Action: use this runbook only when the owner explicitly requests downstream Marshal synchronization after local Tool Shed reconciliation
Campaign Reason: Cross-campaign coordination or operating guidance; intentionally tracked outside any single owner campaign.
Campaign: standalone
Canonical Truth: README.md and docs/
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Purpose

Synchronize a named Marshal project only after Tool Shed and current workspace
truth have been reconciled. Tool Shed defines commitments, status, gates, and
next actions; Marshal is a downstream mirror. The outcome is the maximum
defensible Marshal task closeout and a project summary matching Tool Shed
without rediscovering the process.

## Expected request

A short request such as:

> Reconcile Marshal project `<project name>` with this workspace, close what the
> evidence supports, document current state, and sync Marshal.

Unless the owner narrows the request, first reconcile Tool Shed without using
Marshal as planning input. Then this authorizes the smallest matching
downstream changes in the named Marshal project: complete supported tasks,
correct task readiness/waiting state, and update that project's current state,
next action, and health. It does not authorize hardware mutation, destructive
testing, controlled-document release, commits, pushes, or changes to other
Marshal projects.

## Authority and evidence order

Do not inspect Marshal to determine what the project should do next. Establish
the Tool Shed state and current workspace truth first, then read Marshal only
to calculate the synchronization delta.

Read evidence in this order so stale planning does not override current truth:

1. `README.md` and current documents under `docs/`.
2. `work/index.md`, then the active project map and relevant active artifacts.
3. Dated evidence and incidents linked by those artifacts.
4. Source, tests, build outputs, and operator results needed to verify specific
   completion criteria.
5. Git status and recent log for recency/context only. A dirty or recent file is
   not proof of completion by itself.
6. Completed/deferred work artifacts only for history, constraints, or explicit
   handoff context.

Prefer targeted reads and searches over enumerating the entire repository.
For the SD-card ECR project, start with:

- `docs/ecr-sd-card-supply-change-resolution.md`
- `docs/sd-continuous-background-endurance-plan.md`
- `docs/sd-card-operation-and-recovery.md`
- `work/evidence/service-469-470-474-implementation-and-target-status-20260721.md`
- `work/incidents/incident-control-a-sd-card-read-failure-20260722.md`

## Marshal inspection

Use `marshal-agent`; never print, inspect, request, or alter the credential.

```powershell
marshal-agent projects --limit 100
marshal-agent tasks --limit 100
```

Find the named project exactly, record its ID, then filter the returned task
list by `project_id`. Read every task's description, dependencies, status, and
waiting reason before making changes. Do not infer project membership from
similar wording alone.

## Task decision rules

Classify each task as one of these:

| Decision | Required evidence | Marshal action |
| --- | --- | --- |
| Done | Every material completion criterion is directly supported | Complete task |
| Ready | Preconditions are complete and owner work can begin | Set Ready; clear stale waiting reason |
| Waiting | A real dependency, approval, sample, external document, or physical action is missing | Keep/set Waiting; name only the current missing condition |
| In progress | Work is actively underway and the status is supported | Preserve/update progress without claiming completion |
| Unchanged | Workspace provides no stronger current evidence | Do not churn the record |

Important separation rules:

- Implementation complete is not qualification complete.
- Firmware feature qualification is not candidate-card qualification.
- Candidate qualification is not ECO release.
- ECO release is not manufacturing/DCS rollout.
- A bounded SD working-set pass is not proof of full-address media health.
- A stale dependency text should be corrected after its dependency closes.
- Never close a downstream task solely because an upstream task closed.

## Local documentation

If the named project lacks a current workspace truth document, create the
smallest appropriate document under `docs/` and link it from `README.md` when
it is a lasting entry point. Include:

- objective and affected products/assemblies;
- approved/current requirements;
- workspace implementation and qualification evidence;
- limitations and incidents that constrain interpretation;
- controlled procedure or result template when the project requires one;
- explicit completed versus remaining gates; and
- links to canonical docs and dated evidence.

Do not copy bulky raw evidence or claim that a workspace document released an
external ECO, supplier approval, BOM, or controlled manufacturing change.

## Synchronization sequence

1. Reconcile current docs, direct evidence, and Tool Shed state without using
   Marshal as an authority.
2. Create or update the local current-truth and Tool Shed artifacts, if needed.
3. Verify local Markdown changes with `git diff --check` and validate links by
   targeted search/read.
4. Inspect the matching Marshal project and calculate its delta from Tool Shed.
5. Complete only fully supported Marshal tasks.
6. Change newly unblocked tasks to Ready and clear obsolete waiting text.
7. Update remaining Waiting tasks so they name the actual current blocker.
8. Update the Marshal project:
   - `current_state`: dated summary of evidence, closures, open gates, and risks;
   - `next_action_summary`: smallest executable next step(s);
   - `health`: evidence-based, with important release/quality risk reflected.
9. Read the project's tasks again and count statuses.
10. Report files changed, tasks closed, final status counts, and remaining gates.

## Windows Marshal JSON quoting

The installed `marshal-agent.cmd` passes arguments through another PowerShell
layer. Plain inline JSON may lose its quotes. If a normal command reports that
`--changes` is not valid JSON, preserve JSON quotes through both layers and
encode spaces as `\u0020`. A known-working shape is:

```powershell
marshal-agent update <task-id> --changes '{\\\"status\\\":\\\"Ready\\\",\\\"waiting_on\\\":\\\"\\\"}'
```

For long values, construct JSON, replace literal spaces with `\u0020`, and
escape each JSON quote for both wrapper layers. Do not work around quoting by
reading or printing Marshal credentials.

## Verification and handoff

Before finishing:

```powershell
git diff --check -- README.md docs/ work/
```

Confirm:

- each completed task has a direct evidence location;
- no candidate/release/rollout conclusion was inferred from narrower evidence;
- Ready and Waiting states reflect current dependencies;
- project health mentions material incidents or release risks;
- local changes are limited to reconciliation documentation unless broader
  edits were requested; and
- final task counts match the Marshal readback.

The concise handoff format is:

> Documented `<project>` in `<file>`. Closed N of M tasks. Marshal now shows X
> Done, Y Ready, and Z Waiting. The next actions are `<actions>`. Remaining
> gates are `<gates>`. Project health is `<health>` because `<reason>`.
