Execution records and diagnostic workflow

This document governs development records, not application logging. It supplements the implementation order and agent instructions. Product requirements, independent review and acceptance gates are unchanged.

Record boundaries

Record	Purpose	Contents
PLANS.md	Current execution contract and resume point	Scope, acceptance checklist, task state/owner, open findings, concise closed-finding disposition, latest applicable evidence, limitations and next action.
`docs/diagnostics/milestone-N.md`	Investigation notebook, created only when needed	Failed attempts, hypotheses, bounded diagnostics, observations, cause and repair verification.
`docs/evidence/milestone-N.md`	Reproducible evidence report, created when evidence no longer fits a concise plan table	Exact commands, source/build identity, environment, outcomes, review disposition and acceptance mapping.
`docs/history/`	Preserved superseded records	Historical snapshots with an explicit non-current notice and a link back to the plan.

The plan is a current snapshot, not an append-only diary. Do not copy worker reports or full diagnostic sequences into it. Keep the detailed report in one place and link it. Evidence and diagnostic reports never override the plan's scope or the specification. Read only the relevant investigation/report when resuming; reading all historical logs is not a prerequisite for implementation.

Updating the plan

The coordinator updates a task row in place when its result, owner, next action, review disposition or blocker changes, and before handoff. A failed command alone does not need a plan entry unless it changes current status or invalidates evidence. For an active failure keep one concise entry: affected behavior, known facts, owner, next discriminating check and acceptance impact. Replace it as facts change.

Keep the milestone register, milestone status/outcome and top-level resume point consistent in the same edit. Use the existing lifecycle states; distinguish a repairable defect (needs_changes) from an unavailable prerequisite (blocked). Task completion does not imply milestone acceptance. Closed findings retain their stable ID, effect, final resolution and review/evidence reference; intermediate repair attempts belong in diagnostics. Superseded passing runs are historical, not additional proof for the current revision.

Aim for at most one short paragraph per task/finding and one row per evidence scope. This is a readability target, not permission to omit acceptance criteria, required evidence, unresolved findings or safety constraints. If detail exceeds that target, move the detail to the appropriate linked report.

Investigating failures

Classify the failure: prerequisite, fixture/transport, application behavior, assertion, or currently unknown. Do not assume the application or fixture is correct before checking.
Record a concrete hypothesis and the smallest bounded check that distinguishes it from alternatives. Reuse the same task/finding ID across attempts.
Run that check and record the observation. Retry unchanged commands only for an evidenced transient condition or deliberate repeatability check; record why.
After two failed repair attempts for the same symptom, reassess the cause and task boundary before another expensive full run. Obtain a focused independent review or reduce to a minimal reproduction when useful. This is an escalation of investigation, not an arbitrary acceptance cutoff or a reason to ask the user to resolve routine implementation choices.
Repair the cause, run focused checks, then rerun affected integration behavior. Rebuild the container driver when its inputs changed; reuse a compatible pinned builder/cache. Do not run the full Rust gates for every diagnostic edit. Run them at the required completion gates and again if subsequent changes invalidate them, following TESTING.md.
Review the actual repair and affected behavior independently. Consolidate the plan to the final result, remaining uncertainty and next action.

A diagnostic entry contains: ISO timestamp with offset; task/finding ID; symptom; hypothesis; exact safe command or reproduction reference; observed result; cause if established; next action or closure/evidence reference. Record only useful redacted excerpts. Raw logs, secrets, configuration payloads, private keys and working backups must not be committed. An agent stall or usage limit needs a brief handoff note only when it affects ownership or the next action.

Evidence and handoff

An evidence entry identifies:

Task/criterion and run timestamp with offset.
Tested commit plus dirty-state description, or a reproducible fingerprint of relevant tracked/untracked source inputs; identify the built artifact and its source inputs when a separate container binary is used. A commit alone does not identify a dirty working tree. Never fingerprint secret-bearing data into a report or claim a source identity that was not captured.
Exact command, toolchain/target and required environment or immutable image identity, excluding secrets. Mark missing historical identity as unavailable.
Actual outcome: exit/result counts, fixture versus Alpine versus VM scope, cleanup outcome, limitations and which later edits invalidate the evidence.
Independent reviewer disposition and remaining findings where applicable.

Do not manufacture missing evidence when migrating old records. Carry forward reported results as historical evidence and state whether they were rerun. Before accepting a milestone, verify the integrated files, close actionable findings, run required gates on that revision and update the acceptance mapping.

A handoff consists of current task/state/owner, open issue, latest applicable checks, environment prerequisites and one concrete next action. Link diagnostics only if needed to avoid repeating an investigation. It must be possible to resume from the current plan without reconstructing chronology.

Migration and ownership

Preserve the old record in docs/history/ before compacting existing diagnostic history. Keep scope, acceptance criteria, stable finding IDs, final outcomes, limitations and source links. Clearly label contradictory historical statuses as superseded. Migrate older accepted milestones when they need maintenance; do not rewrite their acceptance merely for uniform formatting.

The coordinator owns PLANS.md and evidence consolidation. Assign a diagnostics file to one writer at a time, or have workers return concise entries for the coordinator to integrate. Include these record boundaries in dispatch briefs; workers still report actual checks and unresolved issues. New agent configuration may not affect an existing session: supply this document explicitly at its next authorized dispatch/handoff. Do not message other chats without user authorization.

6.9 KiB Raw Blame History