---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: task-agent-lifecycle-guide
---

# Task Agent Lifecycle Guide

Use this guide when the user wants an agent to execute one task as a full cycle: start cleanly, work inside task scope, close the task with evidence, and hand off clearly.

Agent entrypoint route: read `.day-shift/agents.md` first, then use this guide for one-task execution. Human workflow files may orient the session, but this guide owns the full agent task lifecycle.

This guide is task-oriented orchestration. It complements `.day-shift/workflows/03-implement-from-task.md` by adding the full before, during, and after operating loop for agents. The selected `task-definition.md` remains the source of truth for allowed work, target paths, acceptance criteria, validation, and closeout expectations.

Use the Day Shift stack deliberately during this lifecycle:

- CLI commands are the first choice for command-supported discovery, readiness checks, review, and paired-artifact build/update behavior.
- Workflow files specify the operating rules, sequencing, and guardrails around the task.
- Prompts specify the canonical layer/action handoffs when the work requires prompt-driven authoring or review language.

## Agent Orientation Command

`<day-shift-cli> agent` is the read-only agent orientation command. Use it at the start of an automation-agent session to show the repository contract, entrypoint guidance, and command envelope before the agent chooses workflow-specific commands.

`agent orient` is the full-orientation alias, and `agent remind` is the shorter correction-focused reminder for sessions that have drifted from the repository contract.

## Purpose

Point the agent at one task definition and have it drive:

- startup and repository-state checks
- task readiness confirmation
- upstream context gathering
- scoped implementation
- validation and evidence capture
- task closeout
- topology-aware Basic terminal, Structured sibling/project-review, or Governed milestone handoff readiness
- final reporting of completed, blocked, deferred, and discovered work

## Inputs

Require these inputs before starting:

- task definition path
- run mode: `readiness-only` or `implement`
- whether the agent may update only paired task artifacts or also perform approved task-scope code/doc edits

Prefer repository-relative paths in all artifact references and outputs.

## Canonical Surfaces

Use these surfaces intentionally rather than mixing ad hoc alternatives.

### CLI

- `<day-shift-cli> workflow explain`
- `<day-shift-cli> planning next-action`
- `<day-shift-cli> planning inventory`
- `<day-shift-cli> planning gap-report`
- `<day-shift-cli> link materialize --dry-run --artifact <path>` for the primary revision-bound lifecycle link gate and body-link candidate preview
- `<day-shift-cli> link materialize --write --artifact <path> --validation-evidence-id <evidence-id>` only after a safe matching dry-run and only when planning-artifact writes are authorized
- `<day-shift-cli> validation links-check --scope planning --artifact <path>` only when independent diagnostic detail or an exact materialization-required recheck is needed
- `<day-shift-cli> task readiness-review --task-definition <path> --reviewed-by <actor> --reviewed-at <ISO-8601 timestamp>`
- `<day-shift-cli> task review --task-definition <path>` when read-only task evidence review is needed
- `<day-shift-cli> implementation-summary build --task-definition <path>`
- `<day-shift-cli> implementation-summary review --task-definition <path>`
- `<day-shift-cli> reconciliation build --milestone-overview <path>` when the next handoff is milestone rollup
- `<day-shift-cli> reconciliation review --milestone-overview <path>` when milestone closeout evidence needs a read-only check
- `<day-shift-cli> validation smoke --scope planning --artifact <path>` when the current task needs focused planning-validation evidence for the selected artifact
- `<day-shift-cli> validation smoke` only when the current task intentionally needs repository-wide validation-smoke context
- `<day-shift-cli> validation checkpoint --scope planning` only when the user explicitly chooses to preserve existing repo-wide planning smoke findings as a forward-only baseline
- `<day-shift-cli> metadata update ...` and `<day-shift-cli> metadata validate-update ...` only when the task explicitly includes metadata-family mutation or review work

### Workflow Files

- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- the matching human prompt guide for the task's canonical root: `.day-shift/workflows/basic-workflow-guide.md`, `.day-shift/workflows/structured-workflow-guide.md`, or Governed `.day-shift/workflows/workflow-guide.md`
- `.day-shift/workflows/02-plan-from-spec.md` only when execution reveals missing planning artifacts or the task must route back into planning

### Prompts

- `.day-shift/prompts/user/task.next.md`: canonical task-to-implementation handoff prompt
- `.day-shift/prompts/user/task.review.md`: canonical task-layer review prompt
- `.day-shift/prompts/user/task.recertify.md`: canonical task-layer lifecycle hygiene prompt
- `.day-shift/prompts/user/implementation.build.md`: canonical implementation-summary build prompt when prompt-driven authoring is required
- `.day-shift/prompts/user/implementation.next.md`: canonical implementation-to-reconciliation handoff prompt
- `.day-shift/prompts/user/implementation.review.md`: canonical implementation-summary review prompt
- `.day-shift/prompts/user/implementation.recertify.md`: canonical implementation-summary lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.build.md`: canonical reconciliation build prompt for downstream milestone rollup work
- `.day-shift/prompts/user/reconciliation.review.md`: canonical reconciliation review prompt
- `.day-shift/prompts/user/reconciliation.recertify.md`: canonical reconciliation lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.next.md`: canonical reconciliation-to-follow-up prompt

The task lifecycle should use task-layer prompts first, then implementation-layer prompts as evidence accumulates, and only then reconciliation-layer prompts for downstream handoff. Use recertify prompts when an existing task, summary, or reconciliation artifact may be stale before implementation, review, closeout, or follow-up planning; recertification remains read-only unless a separate explicit write request follows.

Mode-aware runtime evidence gate: preserve the originating `execution_mode` through task execution and implementation-summary closeout. New task scaffolds default to `execution_mode: runtime`. Switch a task to `contract` only when completion is contract-only evidence or planning work with no runtime behavior change. Switch a task to `hybrid` only when completion requires both runtime implementation evidence and contract or handoff evidence. Contract tasks can close on frozen contract evidence without runtime file changes, but must not claim runtime implementation. Runtime and hybrid tasks must keep Runtime Delta targets visible, list runtime changed paths, record executable validation evidence, and use a structured validation exception only for a blocked validation command; validation exceptions cannot substitute for missing runtime code changes.

## Run-Scoped Lifecycle Evidence

Reuse the `.day-shift/runs/run-<run-id>/run-context.json` manifest inherited from the phase or milestone lifecycle. For a directly invoked Basic or Structured task with no parent phase, resolve or create one repository-local run directory and open the selected task definition as the explicit direct phase-less `resume run open --phase <task-definition>` anchor. This run anchor is evidence context only: it does not create a planning parent, change the direct task-pair topology, or authorize any command. Establish the manifest before the link checks and revision-bound readiness review emit their first transient result, then reuse it through attempt opening, validation recording, summary review, disposition, and close preview.

Invoke each selected ordinary task gate with global `--format json --run-directory .day-shift/runs/run-<run-id> --run-gate <gate>` and add `--run-artifact <path>` whenever attribution moves between the task definition and paired summary. The shared output boundary writes the exact final success or error envelope once to a deterministic manifest-owned path such as `.day-shift/runs/run-<run-id>/evidence/0001-task-readiness-task-readiness-review-ok.json`. Do not add `--output-file`, redirect the envelope, or follow an ordinary bound command with `resume run record`.

If automatic capture returns `data.lifecycleRunCapture` with `writeOutcome: partial-evidence`, the underlying command outcome is already final. Preserve that envelope, keep its original status, identity, and exit classification, do not rerun the command, inspect `resume run status`, and use `resume run record` only as a compatibility recovery import.

Do not write evidence files directly under `.day-shift/runs/`, and do not create unexpected sibling directories there; its direct children must remain canonical `run-<run-id>/` directories.

The run directory is disposable command evidence only. Canonical task and implementation-summary artifacts remain in `.day-shift/planning/` within their task directory, and separately owned durable local evidence stores remain at their declared repository-local paths. Do not move either durable artifact class into `.day-shift/runs/`.

When a direct invocation inherits `sandbox/run-<run-id>/`, use the preview-bound `resume run migrate` transition and continue only from the emitted `.day-shift/runs/run-<run-id>/` destination. Legacy reads exist for compatibility; do not create another root run.

### Command Continuation And Evidence Inspection

Under strict lifecycle execution, an execution-surface response that includes a live process or continuation handle is `running`, not successful, failed, or timed out. Retain that handle and poll the same invocation until it reaches a terminal result; do not launch a duplicate command solely because the initial call yielded. A poll or caller wait budget ending while the handle remains live leaves the command in `running` state.

Use command states consistently:

- `running`: the original invocation has a live handle and no terminal result
- `timed out`: the command itself reached a terminal deadline outcome and is no longer running
- `interrupted`: the process or session ended without a command-owned terminal result; inspect possible side effects and freshness before an intentional retry
- `failed`: the invocation returned a terminal unsuccessful result
- `completed`: the invocation returned a terminal successful result with complete required output

While an invocation is `running`, poll its existing handle and provide user-visible progress at least once every 60 seconds without changing command identity. A retry is a new execution and is eligible only after the earlier invocation is known to be terminal and the lifecycle permits retrying it.

Inspect authored evidence with bounded, structure-aware reads. For Markdown, separate front matter from the authored body and select the named body section before searching; exclude serialized attempts, validation records, review receipts, and disposition payloads from body searches by default. For JSON or YAML, select exact structured fields. Bound the file set, match count, surrounding context, and output size before broadening scope, and do not begin with an unbounded repository-wide recursive text search over planning artifacts.

When serialized lifecycle metadata is the selected evidence source, parse it explicitly and inspect only the relevant attempt, validation, receipt, or disposition fields with bounded output. The default body-search exclusion keeps serialized payloads from flooding authored evidence; it does not discard them.

## Starting

Start with the minimum context required to execute the selected task safely:

- the selected `task-definition.md`
- the paired `implementation-summary.md` if it already exists
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/prompts/user/task.next.md`
- upstream specs, workflows, manifests, prompts, templates, and dependency artifacts named by the task when they specify contract truth, validation semantics, or scope boundaries for the work

Read these broader surfaces only when they materially affect the current task or when startup evidence is unclear:

- `.day-shift/agents.md`
- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- the matching Basic, Structured, or Governed prompt guide when level-specific topology or handoff wording matters
- the applicable canonical parent when one exists: a Structured `overview.md` for direct tasks or a Governed `milestone-overview.md`; Basic tasks have no planning parent
- `.day-shift/prompts/user/task.review.md` when the request is review-heavy or readiness-first
- `.day-shift/prompts/user/task.recertify.md` when the selected task may be stale, already satisfied, duplicated by sibling work, or superseded before implementation starts
- `<day-shift-cli> workflow explain`, `planning next-action`, `planning inventory`, `planning gap-report`, or `validation links-check --scope planning --artifact <path>` when task context, trace links, or the directory shape is suspect

Use the selected task definition to establish:

- objective
- target paths
- current behavior
- desired behavior
- acceptance criteria
- validation commands
- dependencies
- constraints
- closure expectations

Before implementation, confirm the task path is the active source of truth.

- Infer the task directory from the selected `task-definition.md`.
- Use the existing paired `implementation-summary.md` in that same directory if present.
- If chat context or prior summaries disagree with the repository tree, trust the repository tree and re-resolve from the task path before editing anything.
- If the task depends on a later declared sibling or on a producer artifact that does not yet exist, stop and report the sequencing blocker instead of silently reordering the Structured work or Governed milestone.
- If the correct workflow or prompt pairing is unclear, use `<day-shift-cli> workflow explain` and `<day-shift-cli> planning next-action` as read-only guidance before proceeding. Use `<day-shift-cli> validation links-check --scope planning --artifact <path>` when the uncertainty is about local parent or trace links.

## Full-Cycle Algorithm

Run this loop for the selected task.

For normal `implement` runs, use this strict command spine unless the task definition gives a stronger task-specific sequence. Bind every complete JSON gate result to the active manifest with the gate and artifact identities named above. A preview, review, or suggested next action is never authority for a later write; run only the separately authorized command named at that step.

1. Resolve or create the inherited or direct-invocation run directory. Run `<day-shift-cli> link materialize --dry-run --artifact <path>` before readiness and save its complete revision-bound validation evidence. A clean zero-candidate preview with `reusableAsLifecycleLinkGate: true` satisfies the link gate without a preceding standalone links-check. Reuse the evidence only while repository, artifact, planning scope, selected revision digest, candidate state, and finding state match exactly. When candidates exist and writes are authorized, verify `previewChangedPaths` is limited to the selected artifact and apply `<day-shift-cli> link materialize --write --artifact <path> --validation-evidence-id <evidence-id>`; use its `postWriteValidationEvidence` as the new gate, or run only the exact `requiredRecheck` it reports. A missing ID, advisory or blocking finding state, stale revision, different artifact or scope, partial output, or non-callable result is a no-write stop.
2. Run `<day-shift-cli> task readiness-review --task-definition <path> --reviewed-by <actor> --reviewed-at <timestamp> --format json --detail full` and save the complete result as `<readiness-review.json>`. Keep the canonical task's own `task-definition.md` and paired `implementation-summary.md` out of `Implementation Target Paths`; lifecycle commands own those artifacts independently, and readiness rejects them as implementation scope. When `.day-shift/contract-impact.json` is present, treat its writable, generated-output, read-only, frozen, validation, enforcer, advisory, and unknown lanes as the mandatory cycle-safe transitive-impact preflight. Stop on every missing writable/generated obligation, immutable declared target, missing immutable dependency or enforcer, invalid contract, or `unknownPolicy: blocking` unknown-producer finding; revise the planning contract before authorization and never turn read-only or frozen evidence into implementation scope. Under `unknownPolicy: advisory`, unknown producers remain visible warnings and fingerprint evidence but do not block otherwise-complete readiness. They never prove coverage, and every obligation from a known relationship remains strict in both modes. Stop unless readiness reports `ready to implement`, no blockers, the current task revision, a current `contractImpact.fingerprint`, and a complete no-write result. Use `reviewedReadiness` to select the authorization branch; a fresh review of an already-ready task does not replace its stored authorization identity.
3. When `reviewedReadiness` is `needs_more_evidence`, preview `<day-shift-cli> task readiness-authorize --task-definition <path> --review-result <readiness-review.json> --dry-run`. Confirm the exact task-pair revisions, intended paths, and zero conflicts, then apply the identical command without `--dry-run`. When `reviewedReadiness` is `ready_to_implement`, do not pass the different fresh review to `task readiness-authorize`; route directly to the `task attempt-open --dry-run` verifier in the next step, which must prove that the stored authorization is complete, valid, and revision-applicable. Exact original readiness-review replay remains available only for idempotent receipt recovery. Stop on every other readiness state, on an incomplete or non-applicable stored authorization, or when either branch returns stale, blocked, partial, conflicting, or non-callable evidence.
4. Choose one stable attempt identity and timestamp. Preview `<day-shift-cli> task attempt-open --task-definition <path> --attempt-id <attempt-id> --opened-at <timestamp> --dry-run`, confirm it binds the authorized readiness review and exact pair revisions, then apply the identical command without `--dry-run`. For an already-ready task, this preview is the command-owned proof that its existing authorization can be reused; a different fresh review remains fail-closed and is not routine replay input. Preserve the returned `readinessReviewId` as the attempt's actual authorization identity. Do not infer or hand-author attempt evidence.
5. When `runtime_attribution_required` is true, preview `<day-shift-cli> task baseline --task-definition <path> --task-cycle-id <attempt-id> --checkpoint-id <attempt-readiness-review-id> --contract-impact-fingerprint <readiness-contract-impact-fingerprint> --captured-by <actor> --captured-at <timestamp> --dry-run` before the first task-scope write, using the `readinessReviewId` returned by `attempt-open` rather than assuming the fresh review supplied it. Omit only the fingerprint option when the readiness result reports the repository contract absent. Require baseline planning to recompute the same fingerprint and refuse stale or incomplete required impact before capture. Resolve every dirty declared target through the command's explicit adoption contract, then apply the identical command without `--dry-run`. When attribution is not required, record that profile-derived skip and do not fabricate a baseline.
6. Implement only the scoped changes declared by the task. Do not silently append a mirror, generated output, ledger, or test-partition consumer discovered after baseline. When current schema-v2 contract-impact evidence identifies a complete exact set of missing required writable/generated paths or validations, pause edits but do not classify that deterministic additive closure as a material scope change. Preview the manifest-bound `<day-shift-cli> task scope-recover` command with the same fresh run directory, exact task path, open attempt, current task revision, immutable baseline ID, current impact fingerprint, actor/time/reason, and `--dry-run`; omit `--add-path` and `--add-validation` to derive the closure, or supply every exact addition and require equality with the derived closure. Apply the identical command without `--dry-run` only when every addition is eligible and the pair preconditions are current. Untouched additions amend the open attempt and record a supplemental baseline; already-changed additions preserve the predecessor as `contract_gap`, open the named successor, invalidate predecessor validation identities only for current-attempt advancement, and return the exact successor-baseline action. Execute that action and continue the ordinary validation spine in the same run. Read-only, frozen, unknown, arbitrary, incomplete, objective, acceptance, ownership, external-authority, and destructive-boundary changes remain explicit no-write material blockers. Stop only when recovery is non-callable, stale, conflicting, partial, or materially ineligible. Run `pnpm build` first when later validation imports compiled `dist/**` or TypeScript changed.
7. Run the complete current task-declared validation set through `<day-shift-cli> task validation-set --task-definition <path> --attempt-id <attempt-id> --task-revision <current-task-revision> --dry-run`. Require deterministic names, shell-free ordered argv, required flags, declared scope, evidence paths, exact unrecorded/retry selectors, and current pair preconditions, with no child execution or write. Apply the identical command without `--dry-run`; it executes and appends each declared command at most once in order, records exit, timing, termination, bounded output, provenance, and lifecycle sub-result evidence independently, and stops before every later command on the first required failure, timeout, spawn restriction, stale revision, or unrecordable outcome. A failed result must be retried only through its returned exact `--retry-validation-id` selector; after a successful selected retry, use the returned continuation selector to execute only still-unrecorded work. Never add caller argv, reconstruct a retry from task metadata, rerun a passed identity, or let a later pass mask an earlier failure. Use `task validation-record --task-definition <path>` for one explicitly selected command with semantic JSON assertions, imported evidence, or evidence-only recording. Its `--dry-run` validates identity, exact argv, every explicit semantic assertion, and pair preconditions without launching the child process; apply launches that exact argv once without a shell. Do not run the declared command separately before or after `validation-record`. Imported and evidence-only modes retain their read-only preview behavior. Use repeatable `--expect-json <json-pointer>=<JSON-literal>` assertions when JSON stdout values are acceptance evidence; invalid or truncated JSON, a missing pointer, or unequal JSON values derives failed validation evidence even when the process exits zero.
8. Run `<day-shift-cli> implementation-summary build --task-definition <path>` against the current pair. For a manifest-bound run, keep `--run-artifact <task-definition-path>` on this pre-authoring build so the run remains fresh while the paired summary body changes. Treat the selected task path, canonical paired destination, and complete write outcome as the build freshness boundary; stop on a pairing mismatch or incomplete write. Use only the returned current-attempt `candidatePaths` and `candidateMarkdown` when authoring Changed Paths, and inspect every returned excluded-path reason instead of attributing unrelated or unadopted dirty paths.
9. Manually complete the paired `implementation-summary.md` body with changed paths, acceptance results, validation evidence, exceptions, scope classification, runtime boundary, deviations, risks, and discovered work. Write Changed Paths as one exact top-level `- \`repository/relative/path\`` bullet per entry with no description or second path. This body-only authoring is not a lifecycle transition, must preserve command-owned attempt metadata, and must not move run attribution to the summary before authoring finishes. A Changed Paths parser rejection with `writeOutcome: no-writes` remains immutable error evidence and never promotes the rejected summary revision. When the pre-authoring build is bound to the unchanged task definition as required above, its capture re-anchors the run there even if the preceding gate left the summary active; correct the summary and retry without restoring bytes or running an extra link gate. A build incorrectly bound to the summary instead preserves the run's last accepted active-artifact path and revision.
10. Run `<day-shift-cli> implementation-summary build --task-definition <path>` a second time after manual body authoring. For a manifest-bound run, move `--run-artifact` to the paired `implementation-summary.md` on this post-authoring build for the paired summary. This rebuild is required to derive runtime attribution and task-scoped change metadata from the authored evidence; do not review or complete implementation from the pre-authoring build result.
11. Obtain the exact current task revision, then preview `<day-shift-cli> task implementation-complete --task-definition <path> --attempt-id <attempt-id> --task-revision <task-revision> --completed-by <actor> --completed-at <timestamp> --dry-run`. Apply the identical command without `--dry-run` only when the preview reports `applicable: true`, current pair revisions, and no blocking findings. When `applicable: false`, do not apply: continue only if the typed result identifies a profile-valid no-op and the canonical pair already satisfies the profile's implementation-state requirement; otherwise stop and resolve the reported evidence or freshness blocker.
12. Run the manifest-bound `<day-shift-cli> implementation-summary review --task-definition <path> --format json --detail full` without shell redirection or `--review-result-path`. Require `data.lifecycleRunCapture.status: captured`, `callerConsumable: true`, and one indexed `evidencePath`; use that exact manifest-owned raw envelope as the pending-disposition review result. Stop unless it returns a current zero-blocker receipt that authorizes `disposition`; review does not authorize or perform disposition or close.
13. Preview `<day-shift-cli> task disposition --task-definition <path> --disposition accepted --review-result <pending-disposition-review-evidence-path> --recorded-by <actor> --recorded-at <timestamp> --dry-run`. Apply the identical command without `--dry-run` only when the pending receipt, attempt, pair revisions, and intended paths are current and conflict-free. Use `changes_requested` or `accepted_with_follow_up` only when the actual review result and required reason support that explicit outcome.
14. After accepted disposition changes the paired summary revision, run a second manifest-bound `<day-shift-cli> implementation-summary review --task-definition <path> --format json --detail full`. Require a different exact indexed `evidencePath` whose fresh receipt records the accepted disposition and authorizes `close`. The pre-disposition receipt is stale for close and remains fail-closed.
15. Preview `<day-shift-cli> task close --task-definition <path> --review-result <accepted-close-review-evidence-path> --dry-run`. Inspect revision, attempt, implementation, effective required validations, accepted disposition, receipt, and pair preconditions. Apply the identical command without `--dry-run` only when the preview is complete and clean; any stale, blocked, partial, conflicting, or non-callable result is a no-write stop.
16. Re-open `task-definition.md` and `implementation-summary.md` and verify the canonical terminal pair: completed task readiness/status, completed and closed current attempt, accepted disposition, current required validation evidence, and preserved runtime attribution when required. For a direct phase-less Basic run, `resume run status` and `resume run resume` must verify the exact indexed task-close gate and return terminal state `task_close_complete` with `nextPermittedGate: null`; do not create or recommend phase, reconciliation, or project-review artifacts. Structured and Governed continue only under their separate topology rules.

If `pnpm build` is required for TypeScript or `dist` validation but fails during `check:metadata` because of unrelated historical planning findings, record the build blocker, run `pnpm exec tsc -p tsconfig.json` to refresh compiled runtime artifacts, and then run the focused validation commands that exercise the task scope.

Link materialization preview is the task lifecycle's revision-bound link-validation evidence when task artifacts are created or updated. Validation remains read-only evidence; `link materialize --write` is the explicit selected-artifact body-link writer and must receive the exact matching preview `evidenceId`. Treat a clean zero-candidate preview as reusable gate evidence and `candidateCount > 0` as the signal to consider the matching write when authorized; use `previewChangedPaths` to verify scope because dry-run `changedPaths` remains empty by design. After a write, rely only on current `postWriteValidationEvidence`; when it is absent, run the emitted exact `requiredRecheck`. Never reuse evidence across repository, artifact, scope, revision, candidate, or finding-state changes, and do not use links-check output alone to rewrite metadata, repair hierarchy, create artifacts, or infer migrated targets.

### Deterministic Additive Scope Recovery

`task scope-recover` is the default continuation after baseline when the current authoritative contract-impact fingerprint exposes only required additive writable/generated paths or validation commands. Keep the selected task active in its existing fresh `full-cycle-strict` run. Preview with global lifecycle capture and the command-owned run directory:

`<day-shift-cli> --format json --run-gate task-scope-recover-preview --run-artifact <task-definition> task scope-recover --run-directory <run-directory> --task-definition <task-definition> --attempt-id <attempt-id> --successor-attempt-id <fresh-successor-id-if-needed> --task-revision <current-task-revision> --baseline-id <current-baseline-id> --contract-impact-fingerprint <current-fingerprint> --recorded-by <actor> --recorded-at <timestamp> --reason <reason> --dry-run`

The command owns classification and pair mutation. Do not edit target lists, validation commands, readiness fields, attempt state, baselines, or history by hand. For `amendment`, require an unchanged predecessor attempt identity, preserved original baseline, supplemental observations for the new untouched paths, and one callable resume action. For `successor`, require an immutable `contract_gap` predecessor, matching `scope_recovery_id`, preserved evidence, and one callable `task baseline --plan` action containing explicit adoption for every dirty successor target. Apply that exact baseline plan/capture before further writes. A replay of the same recovery identity must return `no-write`; stale or conflicting identities require a fresh preview.

### Authorized Material Contract Revision Recovery

User authorization to revise planning scope and command eligibility to mutate lifecycle state are separate decisions. Use this branch only when `task scope-recover` reports a material authority boundary rather than a complete deterministic additive closure. When a material scope correction is discovered after attempt baseline capture, stop implementation, preserve the one existing `.day-shift/runs/run-<run-id>/` directory and every manifest entry, and obtain explicit authorization for the bounded phase/task contract edits. Never hand-edit readiness or attempt metadata, discard the predecessor baseline, or open a sibling run to escape stale evidence.

After the authorized body edits, select review authority from the canonical run anchor. A Governed phase anchor requires a current clean phase authoring receipt from `phase review --review-mode readiness`. A direct task run whose phase and active artifact are the same task definition requires that exact current `task readiness-review`; the task must resolve either to parentless Basic topology or to direct Structured topology with exactly one `work_overview` parent. The review must have no unrelated blocker and may carry only the canonical stale-attempt blocker directing a baseline-only attempt to supersession or an evidence-bearing attempt to contract-revision recovery. Direct Basic never infers an organization parent, while direct Structured verifies its declared work overview through normal readiness topology evidence. Preview `resume run revise-contract --run-directory <run-directory> --review-result <current-authoritative-review.json> --active-artifact <task-definition> --recorded-by <actor> --recorded-at <timestamp> --reason <reason> --rollback-gate task-readiness --dry-run`; require stale reasons bounded to the selected phase/task anchor and active planning artifact, exact old/new digests, complete immutable history, explicit invalidated entry identities, and zero unrelated run files. Apply the identical command without `--dry-run`, then require `resume run status` to be fresh and `resume run resume` to return a callable continuation before touching task-attempt state.

If the open attempt is baseline-only and has no target delta, validation, implementation completion, deviation, waiver, blocker, disposition, cancellation, review, or closeout evidence, preview `task attempt-supersede --task-definition <path> --attempt-id <attempt-id> --task-revision <current-revision> --recorded-by <actor> --recorded-at <timestamp> --reason <reason> --dry-run`. Apply the identical command without `--dry-run` only when it preserves the predecessor baseline, archives that attempt as `superseded`, clears the stale authorization, and resets readiness. `task attempt-supersede` remains the only supported baseline-only branch and must continue to reject every evidence-bearing attempt.

If the same exact accepted contract-revision checkpoint instead invalidates an open evidence-bearing attempt, require readiness, resume, or terminal navigation to expose one callable `task attempt-contract-revise` action. Preview it with lifecycle capture as `<day-shift-cli> --format json --run-directory <run-directory> --run-gate task-contract-revision-recovery --run-artifact <task-definition> task attempt-contract-revise --revision-run-directory <run-directory> --task-definition <task-definition> --attempt-id <attempt-id> --task-revision <current-revision> --checkpoint-id <latest-checkpoint-id> --recorded-by <actor> --recorded-at <timestamp> --reason <reason> --dry-run`. The command-owned `--revision-run-directory` is intentionally distinct from the global `--run-directory` capture binding. Require the fresh `full-cycle-strict` run, latest accepted task-readiness contract-revision checkpoint, exact old/new task revisions, exact open attempt, complete predecessor baseline, and concrete post-baseline target or lifecycle evidence. Missing, stale, ambiguous, conflicting, baseline-only, or partial evidence is a no-write blocker. Apply the same bound command without `--dry-run` only while those exact preconditions remain current.

Successful evidence-bearing recovery preserves predecessor validation, deviation, waiver, blocker, baseline, and audit evidence byte-for-byte; closes only that attempt as `contract_gap` with actor, timestamp, reason, run, checkpoint, and old/new revision metadata; clears `current_attempt_id`; and resets readiness authorization to `needs_more_evidence`. It does not fabricate readiness, a successor, or a baseline. Resume the ordinary fresh readiness review and authorization path, open a separately authorized successor linked with `successor_kind: contract_revision`, and capture a new baseline for the revised target set before further writes.

Resume the ordinary command spine from link materialization: obtain fresh task readiness, preview/apply `task readiness-authorize`, open a new attempt identity, and capture a new baseline containing the expanded declared target set. Historical attempts, baselines, run entries, review receipts, and invalidation identities remain immutable audit evidence throughout this sequence.

### 1. Startup Preflight

Confirm the local session is safe to begin.

- inspect current repository state before editing, using scoped changed-path accounting rather than broad unrelated-dirty-state narration
- preserve unrelated user changes
- Treat changed paths as the task-scope accounting surface. Do not add a separate final-report note about unrelated pre-existing dirty worktree files unless they affect task scope, block validation, or create a concrete review risk.
- verify the task's implementation target paths exist or are intentionally creatable within task scope
- if a task names a generated, built, renamed, or stale implementation path but the repository has an obvious editable source equivalent for the same component, use the editable source, keep the change inside the intended implementation seam, and record the path substitution as a deviation in `implementation-summary.md`
- verify the task does not require missing planning artifacts before implementation can proceed
- verify `Dependencies` contains only concrete repository-relative paths; prose wrappers such as "Existing behavior in `path`" belong in `Upstream Context`, `Risks`, or `Assumptions` because readiness review treats dependency bullets as artifact references
- if the request is command-supported and the CLI provides a read-only readiness check, prefer that first
- use `<day-shift-cli> planning inventory`, `planning gap-report`, or `validation links-check --scope planning --artifact <path>` when task context, trace links, or the directory shape is suspect
- if missing planning structure is the real blocker, route back to `.day-shift/workflows/02-plan-from-spec.md` instead of improvising task-local replacements
- when metadata or planning validation is in scope, use the CLI validation surfaces with the narrowest meaningful target: `<day-shift-cli> validation smoke --scope planning --artifact <path>`, `<day-shift-cli> validation links-check --scope planning --artifact <path>`, and `<day-shift-cli> validation rollup --scope planning --artifact <path>` for selected artifacts; use `.day-shift/references/validation-and-review.md` for broader no-write and findings semantics.
- when no suitable command owns a needed task-scope edit, record the manual exception as `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification` before relying on direct artifact edits.

If startup evidence is contradictory or incomplete, stop before editing.

### 2. Check Readiness

Confirm the task definition includes or establishes:

- objective
- upstream references
- implementation target paths
- current behavior
- desired behavior
- acceptance criteria
- validation commands
- rollback or recovery notes
- risks
- dependencies
- constraints
- assumptions
- no implementation-blocking open questions

Before treating the task as ready, also confirm:

- the upstream artifacts named by the task are present and readable when they specify behavior that implementation or validation must preserve
- the task's validation commands are concrete enough to run as written or with only path-local substitution
- the task does not rely on inferred contract rules that exist only in prior agent summaries instead of source artifacts
- the task is not blocked by later declared sibling work, missing producer artifacts, or unresolved planning drift
- the task's `Dependencies` section uses concrete repository-relative artifact paths only; dependency explanation, contract context, and behavioral notes belong in `Upstream Context`, `Risks`, or `Assumptions`
- prefer `<day-shift-cli> task readiness-review --task-definition <path> --reviewed-by <actor> --reviewed-at <ISO-8601 timestamp>` as the canonical low-token readiness check before doing a longer manual audit

If the task is not ready:

- in `readiness-only` mode, stop and report `blocked` with the missing evidence
- in `implement` mode, stop before changing repository code or summaries and report the blocker

Do not update `implementation-summary.md` for readiness-only runs.
Use `.day-shift/prompts/user/task.review.md` when the readiness result needs to be expressed through the canonical task review lens rather than only as CLI findings.

### 3. Work During Execution

Enter implementation only when:

- run mode is `implement`
- the task is ready
- no unresolved blocker prevents safe execution

Implementation rules:

- keep changes within declared implementation target paths unless the task definition is updated to reflect a justified deviation
- preserve unrelated user changes
- prefer small, traceable edits
- do not invent new acceptance criteria or broaden task scope silently
- record discovered work when implementation reveals it
- preserve validation/reporting boundaries declared by the task, including separate evidence lanes or artifact-family distinctions when those boundaries are part of the contract
- treat review and validation commands as read-only unless the task explicitly authorizes a mutating command or artifact-creation step
- do not let advisory findings, adjacent evidence, or partial drift reports collapse one artifact family or reporting lane into another
- preserve execution-mode closeout semantics: contract work records frozen contract evidence, while runtime and hybrid work must preserve Runtime Delta evidence, runtime changed paths, executable validation, or a structured validation exception for the blocked validation command only

While work is in progress:

- keep the task definition open as the active contract
- use `.day-shift/prompts/user/task.next.md` as the canonical prompt surface when the implementation handoff needs reusable prompt wording
- re-check governing upstream artifacts before making alignment or closeout claims on contract-oriented tasks
- prefer task-declared validation commands over ad hoc substitute checks
- if a substitute check is necessary, record why the declared command was not the authoritative closeout command
- when a task-declared command is repo-wide and returns unrelated existing findings, record whether the command executed successfully, summarize only findings relevant to the current task, and treat unrelated findings as non-blocking unless they affect this task's validation or review risk
- when `pnpm build` is blocked by unrelated historical `check:metadata` findings but the task still needs compiled `dist` artifacts, use `pnpm exec tsc -p tsconfig.json` as the narrow compile fallback, then run focused task validation and record the substitution plus the original build blocker
- when validation smoke is needed for the current task, prefer `<day-shift-cli> validation smoke --scope planning --artifact <task-or-milestone-path>` so inventory and gap evidence stay scoped to the selected artifact; use repository-wide smoke only when broad context is intentionally in scope
- when a bound command emits a large JSON payload, read the exact manifest entry's deterministic `evidencePath` before parsing or summarizing it; do not create a second loose result or rely on shell pipes when parse correctness matters. Put a truly incidental structured diagnostic under the explicit `auxiliary/` subtree instead of presenting it as gate evidence
- if a declared combined `node --test` command is inconclusive because individual test files mutate process cwd, environment variables, or other process-global state, rerun the affected files separately; record the combined command as inconclusive and the separated runs as the validation evidence
- when updating command-family help or regression coverage, prefer assertions for command presence, option surfaces, posture wording, and explicit no-write/write-capable boundaries; keep absence assertions only when the missing command, option, or output is the product behavior being tested
- update planning artifacts that own scope truth if implementation reveals a real scope, dependency, or contract change
- use `<day-shift-cli> metadata update ...` only when the task explicitly authorizes metadata-family writes, and use `.day-shift/references/metadata.md` for the write versus validate-update boundary
- when applying a metadata or artifact-specific update from a task handoff that names the selected artifact, include `--active-artifact <same-repository-relative-path>` so mismatched handoff context and selected command target fail before writing; omit it only when no explicit active-artifact handoff is being checked
- when a lifecycle metadata transition is CLI-supported, use the relevant update or sync command instead of hand-editing front matter; manual metadata edits require an explicit recorded exception naming the command that was unavailable, failed, or did not own the transition
- keep `<day-shift-cli> task review --task-definition <path>` available as a read-only spot check when implementation drift is suspected but closeout is premature

### 4. Capture Task Execution Evidence

For each implemented task, update the paired `implementation-summary.md` in the same task directory.

Prefer `<day-shift-cli> implementation-summary build --task-definition <path>` for standard and lightweight task paired-summary refreshes. The command preserves the standard implementation-summary template shape for standard tasks and the lightweight implementation-summary template shape for lightweight tasks. Use `.day-shift/prompts/user/implementation.build.md` when the summary needs prompt-driven drafting or recovery language that the CLI does not supply directly.

Treat `implementation-summary build` as both a write helper and a pairing/handoff check. If it reports that no write was needed because the paired summary already exists, continue with manual closeout updates unless the existing summary already contains complete changed-path, validation, acceptance, deviation, and follow-up evidence.

Changed Paths authoring uses one exact top-level `- \`repository/relative/path\`` bullet per path. Prefer the build result's deterministic `candidatePaths` and rendered `candidateMarkdown`; preserve its excluded-path reasons as recovery evidence, and never copy excluded unrelated, pre-existing-unadopted, uncertain, or protected paths into the summary.

Record:

- summary of work performed
- changed paths
- validation performed
- validation commands not run and why they were skipped, substituted, blocked, or inconclusive
- acceptance criteria status
- deviations
- discovered work
- follow-up work

Changed paths should communicate what this task touched. If the worktree contains unrelated pre-existing changes, leave them out of the final report unless they affected this task's scope, validation, or risk; preserving them is still required.

When findings are part of the task contract, record them using the task's declared taxonomy and blocking-versus-advisory semantics instead of inventing workflow-local labels.

When a task depends on read-only validation or review behavior, record whether the closeout checks remained no-write and whether any mutating command was intentionally excluded from validation evidence.

Use `<day-shift-cli> implementation-summary review --task-definition <path>` or `.day-shift/prompts/user/implementation.review.md` when a read-only evidence pass is needed over the summary before closing the task.

When the task changes validation smoke, validation links-check, planning inventory, gap reporting, or paired-artifact status behavior, rerun the relevant artifact-scoped validation after task closeout so task-local pending-state findings are not mistaken for residual repository drift.

When capturing diff sanity evidence, prefer targeted `git diff --stat -- <paths>`, `git diff --numstat -- <paths>`, and `wc -l <paths>` over broad repository output. If any task-scoped path is untracked, record scoped `git status --short -- <paths>` and line counts for those files because ordinary `git diff` does not show untracked file contents. Use `git diff --no-index /dev/null <file>` only when content-level diff evidence for a new untracked file is needed; otherwise line counts plus scoped status are sufficient.

### 5. Close The Task

When implementation and evidence capture are complete:

- use the supported CLI sync/update command to set completed task-definition metadata to `readiness: completed` and `status: completed`; do not leave a completed task in `readiness: ready to implement`
- edit the source `task-definition.md` directly only for body evidence, closeout notes, or unsupported metadata transitions with an explicit manual exception
- make sure task-definition status and implementation-summary evidence do not disagree
- leave discovered work and follow-up work explicit rather than burying them in prose
- preserve the topology-aware handoff by keeping the task summary review-ready for Basic terminal inspection, Structured project review, or Governed milestone reconciliation
- use `.day-shift/prompts/user/implementation.next.md` only when a completed Governed task is being passed into milestone reconciliation
- prefer `<day-shift-cli> reconciliation build --milestone-overview <path>` only for Governed milestone rollup and only after the task evidence is genuinely ready

Do not mark the task complete unless the acceptance criteria are either met or clearly deferred with an explicit reason the user can evaluate.

If a direct metadata edit appears necessary where a CLI update or sync command exists, stop before editing and report the exact command considered, why it cannot be used, the manual exception, and the artifact fields that would change.

### 6. Hand Off After The Task

After the task is complete or blocked, report what the next workflow step should be.

- if the task completed cleanly, identify the topology-aware next step: Basic terminal handoff, the next Structured sibling or project review, or Governed next task or milestone reconciliation
- if the task stopped early, identify the first blocking condition and the exact artifact or decision needed to resume
- if the task surfaced discovered work outside current scope, separate it from the completed task outcome
- if the next step is Governed milestone rollup, use `.day-shift/workflows/04-summarize-and-reconcile.md` plus `.day-shift/prompts/user/reconciliation.build.md` or `.day-shift/prompts/user/reconciliation.review.md` as appropriate
- if the next step is follow-up extraction from reconciliation evidence, use `.day-shift/prompts/user/reconciliation.next.md`

## Stop Conditions

Stop and report instead of improvising when any of these are true:

- the task is not ready
- the task depends on a later declared sibling task
- the implementation target paths are missing, contradictory, or too vague to execute safely
- required upstream artifacts or dependencies are absent
- the authoritative validation commands cannot be run or cannot meaningfully confirm the task's acceptance criteria
- the task definition conflicts with the observed repository structure in a way that affects scope
- implementation would require broad opportunistic cleanup outside declared task boundaries
- a requested result would require inventing missing planning structure rather than executing approved planning

When stopping, report the exact task, the blocking condition, and the next explicit artifact or decision needed to resume.

## Artifact Contract

This workflow may update only these artifact classes by default:

- repository code or docs within the task's declared implementation target paths
- the paired task `implementation-summary.md`
- the source `task-definition.md`

Derived state files under `.day-shift/state/` may be written only by explicit state, checkpoint, or sync commands named by the task or explicitly requested by the user. Do not hand-edit derived state as part of ordinary task closeout.

This workflow must not automatically:

- reorder Structured or Governed declared tasks silently
- mark blocked tasks as completed
- invent or rewrite acceptance criteria without updating the task definition
- absorb unrelated cleanup outside task scope
- treat advisory review output as authorization to write
- create alternate task-summary or closeout artifact destinations

When CLI, workflow, and prompt surfaces disagree, prefer them in this order:

1. the selected `task-definition.md` and its upstream contract artifacts
2. the command-specific CLI contract for the exact operation being used
3. the workflow file governing the current stage
4. the matching layer/action prompt
5. prior summaries or conversational assumptions

## Output Contract

For successful full-cycle task completion, keep the final response concise and include:

- completed status or blocked status for the selected task
- changed paths
- validations run and results
- validation commands skipped, substituted, blocked, or inconclusive
- discovered work
- follow-up work

Detailed acceptance-criteria mapping may live in the paired `implementation-summary.md`; summarize only material deviations or unmet criteria in the final response.

Do not include unrelated dirty worktree state as its own final-report note when the changed-path list already communicates the task scope. Mention unrelated dirty state only when it materially affected the task outcome, validation, or review risk.

When relevant to the task contract, also include:

- whether findings were blocking or advisory
- whether artifact-family or evidence-lane boundaries were preserved
- whether validation and review steps remained no-write
- whether the task is ready for Basic terminal handoff, Structured project review or the next sibling, or Governed milestone reconciliation

If the run stopped early, say so explicitly and identify the first blocker.

Name the CLI commands, workflow files, and prompts actually used whenever they materially shaped the lifecycle outcome.

## Promptable Invocation

Use this invocation shape when you want the agent to run the workflow directly:

```md
Use `.day-shift/workflows/task.agent-lifecycle-guide.md`.
Also use:
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/prompts/user/task.next.md`
- `.day-shift/prompts/user/implementation.next.md` when the task completes

Task: <path-to-task-definition.md>
Mode: implement
Constraints:
- stop on readiness blockers
- keep edits within declared target paths
- update the paired implementation summary and task definition closeout metadata
- report blocked or discovered work explicitly
- state the next handoff after the task
```

For review-only passes, change `Mode: implement` to `Mode: readiness-only` and keep the workflow read-only.
