Recover project state and produce a defensible engineering handoff

“Done” is not a recoverable state

You inherit a feature branch for a coupon-audit change. The branch name looks right and the README says the work is complete. The checkout tells a less convenient story: one tracked path is staged, another tracked path is modified but unstaged, and a third path is untracked. A verification report says PASS, but it was produced before the latest working-tree change.

A handoff such as “use this branch, tests are green, merge next” cannot tell a successor exactly what was inherited, which changes belong to the task, what the earlier PASS actually covers, or what action is safe first. This lesson turns that ambiguity into an inspectable artifact.

Your deliverable is Project State Handoff Record v1. It records a reproducible resume anchor, the current delta, intended versus incidental scope, verification evidence with its freshness boundary, unresolved assumptions, and one bounded next action. A second engineer should be able to resume from the record and repository without relying on the author's memory or chat history.

This is not a general Git workflow lesson. It does not choose branch, merge, rebase, or release policy, and it does not design a portfolio-wide test strategy. Git is used here as evidence about project state. The success condition is independent recovery, not command count.

Different support, identical evidence bar

Use the Foundation route when you still merge history, working state, and verification into one idea. It gives explicit vocabulary and one guided pass through the record, then removes prompts before transfer.

Use Repair when only one distinction is fragile. If you can record the commit but misread staged versus unstaged changes, repair that boundary with a discriminating probe instead of repeating unrelated material.

Use the Experienced / Fast Path when the syntax is routine. You may compress explanation, but you still owe the same artifact, limitation disclosure, changed-context transfer, and human decision.

Diagnostic: with only a branch name and the latest commit message, can you rule out an unstaged fix or an untracked file? If a verification report predates a working-tree change, can it still support the statement “the current state is verified”? If either answer is uncertain, keep the Foundation route.

Mental model: five independent evidence layers

A defensible handoff separates five layers that prose often collapses:

1. Resume anchor — repository identity, current ref/branch, and commit context that another person can locate.
2. Working-state boundary — the staged, unstaged, and untracked deltas visible relative to the recorded anchor.
3. Intent boundary — which deltas belong to the task and which are incidental or still unknown.
4. Evidence ledger — checks already run, their observed result, locator, covered state, and freshness or limitation.
5. Human next action — the first bounded action justified by current evidence, plus blockers and non-claims.

History and current state are related but not interchangeable. Commit history describes recorded snapshots. The index and working tree can contain additional changes. The last commit is therefore part of the anchor, not a complete description of the handoff.

The lab uses git status --porcelain=v1 as a machine-readable state observation. Within the official Git status semantics used by this lesson, its status positions distinguish index and working-tree differences and represent untracked paths separately. That fact does not make a clean status proof of correctness or completion.

First checkpoint

State one conclusion the opening scenario does not yet justify, then name the missing evidence. A useful answer might say that the previous PASS cannot establish the current working state until the report is connected to the files it covered. The wording is flexible; the evidence boundary is not.

Building Project State Handoff Record v1

Do not begin with a long narrative. Close the inspectable fields first.

1. Make the resume anchor reproducible

Record repository identity, the current ref or branch, and the HEAD object id. Some projects need more context, but every extra field should answer a recovery question. In the synthetic lab, a local probe emits the relevant anchor values; the lesson does not expand those commands into a daily Git tutorial.

A branch name alone is not durable enough because the name can later point elsewhere. A commit id alone is also incomplete when current changes live outside that commit. The anchor identifies the recorded snapshot; the delta ledger identifies what is currently different from it.

2. Classify state before you infer intent

For every visible path, record its state class, its relationship to the task, the evidence for that relationship, and the proposed handling. Do not infer “intended” from “staged.” Staging is a state property. Intent comes from the issue brief, content, owner context, or comparable scope evidence.

3. Bind verification to the state it covered

A PASS with no state locator is easy to over-promote. Record what check ran, what state or file fingerprint it covered, the observed result, and what changed afterward. A report created before a later delta remains valid historical evidence about the earlier state; it is not automatically evidence for the current state.

4. Preserve unknowns and non-claims

A useful handoff says what is unresolved. An untracked file might be personal scratch, task input, or an artifact worth preserving. If the evidence does not establish which, record that uncertainty instead of silently deleting or including it. Likewise, a local PASS does not prove a deployment path that was never exercised.

5. End with a bounded first action

“Continue the work” is not operational. The successor should know the first action that can be taken without destroying evidence or promoting an unsupported claim. The final decision belongs to a human and uses one of four bounded outcomes: ACCEPT, MODIFY, REJECT, or BOUNDED_DEFER.

Deep explanation: state, scope, and verification are different axes

Weak handoffs often compress three questions into one sentence:

• Where is the change? This is a state question.
• Does the change belong to this task? This is an intent/scope question.
• Has the change been verified well enough for the next decision? This is an evidence question.

A staged file can be incidental. An unstaged file can be essential. A clean working tree can still lack valid verification. A PASS report can be stale because a relevant file changed after the report. Keeping these axes separate is what makes the handoff auditable.

The lesson's recovery chain is:

exact anchor → current delta → intended/incidental boundary → evidence ledger → unresolved boundary → next safe action → independent recovery check

Asset FND007-A01 depicts the same chain. It contains no confidence score or decorative percentage. Each arrow means that the next claim depends on evidence from the previous boundary.

Why a chat summary cannot be authority

Narrative is useful for intent, but it is mutable and difficult to reproduce. If a summary says “everything is staged and verified” while the checkout shows an unstaged change and a stale report, the inspectable state wins. Good narrative sits on top of evidence locators rather than replacing them.

What exactly is wrong with stale evidence?

The earlier report need not be false. Its claim is simply narrower: the recorded check passed for the state it covered. The invalid move is extending that result across a later relevant delta without new evidence. The repair is a discriminating check that reconnects verification to current state, not a larger command dump.

Why independent recovery is the oracle

The author carries private context. A successor does not. If another learner can reconstruct the anchor, classify the same deltas, recognize stale evidence, preserve the same unknowns, and reach the same bounded first-action decision, the artifact is doing its job. The shell commands and prose do not have to be identical.

Worked case: handing off coupon-audit without guessing

The lab checkout exposes three paths with different state classes, a README that claims completion, and a prior PASS report.

Step 1 — capture the anchor. Record the current ref/branch and HEAD. This establishes the recorded history point; it does not describe all current changes.

Step 2 — build the delta ledger. Turn the status observation into path-level rows and keep state separate from intent. For each path, inspect the issue brief, diff/content, and any available owner evidence. If the evidence does not establish intended or incidental scope, preserve UNKNOWN; the state class alone never authorizes inclusion or deletion.

Step 3 — test evidence freshness. The prior report records a fingerprint for the coupon file. Compare it with the current file fingerprint. If they differ, the precise conclusion is not “the tests fail”; it is “the previous PASS does not cover the current file state.”

Step 4 — choose a bounded decision. The README does not authorize ACCEPT. If current verification has not been re-established after the observed working-tree change, MODIFY or BOUNDED_DEFER may be more defensible than acceptance, depending on the evidence and task policy. The learner makes and defends that choice.

Step 5 — perform the recovery check. Give the record and checkout to a second learner. They should be able to identify the anchor, avoid silently absorbing incidental state, detect the stale report, and state the first safe action. If they must ask the author which file “really mattered,” the handoff is incomplete.

Counterexample: the last commit message is the current state

The shortcut sounds reasonable because commit messages summarize intent. In this fixture, however, staged and unstaged changes exist beyond HEAD. The commit message can describe history but cannot exhaust current state. The appropriate repair is a state ledger, not a more confident summary.

Seductive failure modes

“The branch is correct, so resume from there.” Branch name is only part of the anchor. Preserve the commit identity and current delta as separate evidence.

“A clean working tree means done and verified.” Cleanliness and verification answer different questions. Keep the evidence ledger even when no delta is visible.

“The report says PASS, therefore the current state passes.” Check what state the report covered. A later relevant change restricts the report's applicability until verification is re-established.

“Every untracked file should be committed or deleted.” That jumps from a state class to an intent decision. Use task evidence; if intent remains unclear, keep the path and record an unknown.

“A detailed handoff paragraph is enough.” Without locators and path-level evidence, a reviewer cannot falsify or reproduce the claims. Attach the narrative to the anchor, ledger, evidence locator, and explicit next action.

For each shortcut, ask one discriminator: What observable evidence could make this conclusion wrong? If you cannot name one, the claim is probably too broad or too narrative-dependent.

Mapping professional workflows to the same invariants

Real teams may use pull requests, tickets, CI runs, patch queues, worktrees, or internal state collectors. This lesson does not prescribe one container. Preserve the invariants instead:

• the anchor is reproducible;
• current delta is not hidden inside history;
• intent has evidence;
• verification is bound to its actual state and scope;
• unknowns and residual risk remain visible;
• the successor can derive a bounded next action without the author's memory.

If your existing tool captures these better than a CSV, use it in practice. Project State Handoff Record v1 is the lesson's inspectable baseline, not a claim that every organization needs the same file format.

AI may help format supplied evidence, suggest candidate probes, or summarize after you establish the initial state. Material use must be disclosed. It may not invent verification, declare intended scope from filenames, or make the final accept/modify/reject/defer decision for you.

Trade-offs: how much state should a handoff capture?

Sometimes branch + HEAD + status is enough. Sometimes recovery also depends on generated artifacts, configuration, dependency state, submodules, or another workspace dimension. Add a field when omitting it would prevent a successor from reproducing the bounded state relevant to the task.

A minimal record is fast and readable but can miss a critical dependency. A giant state dump may preserve everything while burying the evidence that drives the decision and making freshness difficult. The target is not maximum data; it is sufficient, traceable evidence for blocking claims.

Incidental changes create a second trade-off. Deleting them immediately may destroy useful owner data. Automatically including them expands scope without authority. When intent evidence is missing, BOUNDED_DEFER can be the disciplined outcome: preserve the path, record the ambiguity, and name the clarification needed.

No Git success signal selects the decision enum automatically. ACCEPT means the evidence is sufficient for the bounded claim. MODIFY means a specific repair is needed before that claim. REJECT means the proposed path is not defensible from current evidence. BOUNDED_DEFER means the missing evidence or authority is explicit and the deferred scope is contained.

Guided practice, then changed-context transfer

Guided pass

In FND007-LAB1, run only the non-destructive fixture setup and probe first. Create one row per visible delta. Keep state class and intent in different fields. Compare the prior verification fingerprint with the current file fingerprint. If coverage has become stale, record the limitation; do not call it a new test failure unless a current check actually fails.

Complete the handoff record with repository/ref/HEAD, path, state class, intended/incidental/unknown status, evidence locator, verification result and freshness, unresolved assumption, next safe action, human decision, and one non-claim. The prompts are scaffolding for the first pass, not the final artifact.

Independent transfer

In the transfer case, you only know that the state/history cues differ from the first case. Re-observe the current anchor and delta from evidence and do not carry forward any earlier classification. A strategy that depends on remembered labels rather than current observations can silently produce the wrong record.

Transfer means keeping the invariants while adapting the strategy. The exact command sequence is not part of the oracle.

Minimum reviewable evidence package

A defensible submission contains:

• a reproducible resume anchor;
• a path-level ledger separating staged, unstaged, and untracked state;
• intent evidence or an explicit unknown for material deltas;
• a verification ledger naming the check, observed result, evidence locator, covered state, and freshness or limitation;
• at least one unresolved assumption, or an evidence-based statement that none was observed;
• a bounded next safe action that preserves evidence;
• a human ACCEPT / MODIFY / REJECT / BOUNDED_DEFER decision with rationale;
• at least one non-claim;
• disclosure of material AI/support use;
• an independent recovery check.

Evidence should be capable of falsifying the claim. “README says complete” merely repeats a project assertion. A status observation, file fingerprint, prior-report locator, and task brief can be inspected independently of that sentence.

The lab baseline only confirms that the synthetic fixture can be inspected consistently; it does not supply the handoff answer. A defensible submission must show correct state/history boundaries, traceable evidence, explicit human limitations, and successful recovery in the changed-context case rather than matching a particular wording.

Assessment: retrieval through transfer

S1 — retrieval, non-blocking: separate resume anchor, current delta, and verification evidence in a compact scenario; explain at least two concepts without overclaiming.

S2 — application, blocking: build the central portion of Project State Handoff Record v1 from the realistic case. Narrative-only or command-only output is insufficient; conclusions need inspectable evidence fields.

S3 — diagnosis, blocking: find the first unsupported promotion in a plausible handoff, such as extending an older PASS across a later change. Propose one discriminating repair probe.

S4 — decision, blocking: choose ACCEPT, MODIFY, REJECT, or BOUNDED_DEFER. Cite evidence, limits, residual uncertainty, and at least one non-claim. The final choice cannot be delegated to Git or AI.

S5 — transfer, blocking: recover a second interrupted repository in which the staged/unstaged split and resume commit differ despite similar contents. Adapt the evidence strategy instead of copying the earlier record.

Four critical dimensions are non-compensatory: state/history correctness, evidence traceability, human judgment with limitation disclosure, and changed-context transfer. A strong score in one cannot cancel a critical failure in another.

References and freshness boundary

The lesson makes one current tool-semantics claim from an official source. Git's git status documentation describes status information for differences among HEAD, the index, and the working tree, represents untracked files separately, and provides a porcelain format intended for stable machine-readable use. This authority is bounded to status semantics; it does not prove correctness, intended scope, or release readiness.

• SRC-GIT-STATUS — FACT / PRIMARY_OFFICIAL

https://git-scm.com/docs/git-status Retrieved: 2026-09-02 Review due: 2026-10-17 Boundary: Git status semantics only.

Two additional claims are explicitly curriculum DESIGN, not Git documentation claims: a MAKNOW handoff combines exact anchor, change ledger, evidence ledger, unresolved boundary, and next action; and independent recovery is the acceptance oracle for the handoff artifact.

As of this authoring date, the locked source has not reached review_due. Re-verify when that date expires, when the cited source materially changes, or when authoring introduces a new current technical claim outside the locked research map. Project conventions remain a declared uncertainty: branch, release, and workspace policy vary by team, so this synthetic example is not universal workflow policy.