Core workflow commands

Core workflow commands move work from intent to reviewed evidence. Use the generated command inventory or day-shift commands describe "<command path>" --format json for the exact current arguments, options, aliases, preconditions, and effects of any command below.

Behavioral compliance depends on the connected agent or integration. The verified command examples use CLI automation protocol version 2; example availability does not make an unsupported integration conforming.

Contract shared by every family

Before calling a command, resolve its descriptor and check prerequisites, selection requirements, authorization, confirmation, mutation posture, and effects. Text output is for operators; --format json returns the protocol envelope. Protocol v2 is the default and approved bounded read surfaces use their compact projection when detail is omitted. Use --detail full for complete audit output, or pin --protocol-version 1 during the compatibility window to retain the former full-detail default. Explicit --detail compact, summary, and full always override the version default. Supported structured controls can also include --fields, finding filters, lane-specific --limit, --page-lane, --page-size, opaque --cursor, and --output-budget. Support is command-specific.

Success exits with 0. Usage, validation, conflict, environment, and unexpected failures use typed non-zero exit classifications in JSON. Inspect writeOutcome before retrying. Recovery guidance is evidence, not authorization for a different write.

Workspace and specification intake

Exact roots: init, spec, workspace, work, and Governed layer-specific slice.

• init creates workspace-owned Day Shift state; preview or compatibility evidence should precede replacement of existing state.
• spec create --implementation-order <number|next> creates a numbered canonical draft specification and registry entry without selecting a workflow level or creating planning roots. Canonical flag authoring uses --purpose, --problem-statement, repeatable --desired-outcome, --non-goal, --scope, --constraint, --success-criterion, and --open-question; structured JSON or YAML accepts their camel-case or snake-case field equivalents. The body contains exactly Purpose, Problem Statement, Desired Outcome, Non-Goals, Scope, Constraints, Success Criteria, and Open Questions in order. The deprecated Day Shift 0.2.0 --summary, --problem, --goal, and --risk aliases preserve content under those canonical headings. next selects the lowest unused positive order without a 99 ceiling; explicit positive whole numbers such as 100 and 1000 are valid. Orders below 10 are zero-padded to two digits, larger orders retain their full width, and 00 remains reserved for emergent intake. spec review is read-only; spec disposition is the separate revision-bound planning-readiness write. Creation, review, and disposition never create planning roots.
• work create --level basic|structured --implementation-order <NN|next> --dry-run previews a numbered Basic or Structured root. Basic accepts a complete direct task; Structured requires canonical planning-ready specifications. Results include implementationOrder, implementationOrderSource, orderedRootName, and rootInventoryFingerprint. Governed creation retains its registered-spec/slice ordering contract.
• Use spec source add --id <id> --ref <new-source> --reason <reason> when a registered source reference changes. It appends the previous source to history before atomically installing the new reference. Generic spec update must not be used to mutate source.ref.
• Inputs are repository-relative spec ids, registered sources, or selected overview paths. Outputs include created paths and traceability evidence.

Start with workspace initialization and continue through intake to implementation.

Planning organization and hierarchy

Exact roots: work, phase, milestone, task, and planning.

Basic writes .day-shift/planning/basic/tasks/<NN>-<task-id>/. Structured writes .day-shift/planning/structured/<NN>-<work-id>/overview.md with direct tasks at tasks/<NN>-<task-id>/ through work task create. Root prefixes come from implementation_order; direct Structured task prefixes come from parent-local sequence. Semantic work/task/dependency/lifecycle identities remain unprefixed. Task and follow-up creation results include sequence, sequencePrefix, orderedTaskRootName, and taskInventoryFingerprint. Governed writes .day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md and uses phase new, milestone new, and task new for declared children. slice new is the layer-specific alternative that creates the same numbered root from registered spec context. Former nested Governed containers and unnumbered Basic/Structured paths are legacy read/migration inputs only, never canonical new-write destinations.

Workflow organization is independent from --agent-mode, --evidence-profile, and action authority. Review and readiness-review remain read-only at every level.

day-shift work create --spec .day-shift/specs/example.md --level structured --implementation-order next --dry-run --format json
day-shift --protocol-version 2 --format json --detail full planning inventory --root .day-shift/planning
day-shift milestone new --phase-overview .day-shift/planning/governed/01-delivery/phases/01-runtime/phase-overview.md --full-set

The first two examples are read-only. The final command is an explicit write for Governed work and must follow the declared-child and active-artifact gates in plan from spec.

Governed lifecycle map

Governed is available as a complete advanced workflow only when the numbered root, full hierarchy, task evidence, milestone reconciliation, read-only project review, explicit project-review.md persistence, and separate work close gate are all preserved. The canonical root is .day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md; new writes never add a sibling overview.md or a nested slices/ layer.

Use the Governed workflow for the ordered journey and Governed hierarchy for the exact artifact-owner matrix. Those technical pages keep the advanced lifecycle reachable without adding it to Basic or ordinary Structured onboarding.

Promotion and migration

task promote supports Basic-to-Structured and Basic-to-Governed preview/apply. Structured promotion accepts --implementation-order <NN|next> and reports the numbered root, root inventory fingerprint, and direct-task sequence fields. work promote supports Structured-to-Governed preview/apply. Promotion preserves semantic task identity, dependencies, evidence, source-spec links, and independent agent/evidence settings; it changes organization only and requires an exact plan identity plus actor/reason on apply.

workspace migrate preserves the existing schema-version mode and adds a distinct structural mode:

day-shift workspace migrate --target-schema-version <version> --dry-run
day-shift workspace migrate --check
day-shift workspace migrate --plan --mapping <work-unit-id=level> --root-order <work-unit-id=NN> --task-sequence <work-unit-id:task-id=sequence>
day-shift workspace migrate --apply --expected-plan-digest <digest> --confirm apply-workspace-migration

Schema dry-run, structural check, and structural plan do not write. The structural result exposes root/task ordering, moves, rewrites, metadataInsertions, revisionRebindings, recoveryActions, conflicts, retirements, and planDigest. Structural apply may create canonical parents, move planning artifacts, retire legacy paths, record path mappings, and stage a repository transaction. Ambiguous mapping, stale digest, root or sequence collision, invalid path, conflict, or incomplete transaction fails with a typed classification and recovery guidance; do not retry blindly or move files manually. Discovery never applies migration implicitly.

Work selection and task execution

Exact roots: work, run, and agent context.

Candidate, current, context, and inspection commands are read-only derived evidence. Selection/checkpoint commands write coordination state but do not implement a task. run executes only the resolved command contract and preserves its filesystem, network, host-state, confirmation, and idempotency boundaries.

Routine lifecycle inspection starts with the resume run status command using the selected run directory and JSON output. Omitting --detail under protocol v2 selects the compact byte budget and returns a context-loss resumeCapsule: active artifact, last accepted gate, bounded completed-action identities and total, one next action, and targeted entries, validations, and evidence paging commands. Do not repeat counted current successful entries. Use resume run resume to re-resolve the next action from canonical artifacts; reserve unpaged --detail full for an explicit audit.

For a ready runtime or hybrid task, capture task baseline after readiness succeeds and before implementation writes. The baseline records the task-cycle and checkpoint identities, declared-target hashes, dirty-state classifications, and any explicitly adopted pre-staged target. A later summary must prove fresh runtime paths and executable validation against that same identity; an unrelated dirty path or a changed file without current-cycle attribution does not satisfy the breakout.

When the current schema-v2 contract-impact fingerprint later exposes only required additive writable/generated paths or validations, use task scope-recover in the existing fresh full-cycle-strict run. Its preview/apply contract binds the task revision, open attempt, baseline ID, and impact fingerprint and refuses arbitrary additions. Untouched additions amend the attempt with a supplemental baseline; already-changed additions preserve a contract_gap predecessor and open one attribution successor whose exact next action captures the expanded baseline. Material authority-boundary changes remain explicit no-write stops.

day-shift --format json --run-gate task-scope-recover --run-artifact "$TASK" task scope-recover \
  --run-directory .day-shift/runs/run-current --task-definition "$TASK" --attempt-id "$ATTEMPT" \
  --task-revision <revision> --baseline-id <sha256> --contract-impact-fingerprint <sha256> \
  --recorded-by operator --recorded-at <timestamp> --reason "Recover exact additive impact." --dry-run

Use implement from task for readiness, target-path, validation, rollback, and closeout gates.

Verified machine-readable handoff commands

apps/docs/content-agent/agent-reference-examples.json freezes the current compiled descriptors and bounded success envelopes for agent, work candidates, work select, work current, agent context, work next, resume run status, and resume run resume. The first discovery and inspection surfaces are read-only; work select is the one explicit user-local coordination write; neither posture implies task implementation or closeout authority.

The bundle’s disposable fixture reaches current readiness through the shipped readiness review/authorization, attempt, and baseline commands before capture. This makes its effective policy, required evidence, implementation_incomplete resolution, run profile, metadata posture, active gate, and callable next action current command evidence rather than hand-authored sample fields. The focused capture test fails closed if a command becomes unavailable, changes write posture, loses protocol or completeness fields, changes its reference owner, or drifts from the frozen envelope.

Implementation evidence and reconciliation

Exact roots: implementation-summary and reconciliation.

build refreshes the canonical paired artifact; update applies explicit supported metadata changes; review is read-only. Reconciliation is eligible only after all declared task summaries are completed and non-placeholder.

day-shift implementation-summary review --task-definition .day-shift/planning/example/task-definition.md --format json
day-shift reconciliation build --milestone-overview .day-shift/planning/example/milestone-overview.md

Review does not repair or complete evidence. Build is an explicit planning-artifact write. See evidence review and reconciliation.

Governed reconciliation and closeout contract

Governed task closeout preserves a receipt chain: implementation-summary review is read-only, task implementation-complete records implementation completion, task disposition records the accepted disposition, and task close performs the separate terminal task write only with current review evidence. A validation exception or waiver remains explicit evidence and cannot turn incomplete Runtime proof into a pass.

At the milestone boundary, reconciliation build writes the draft rollup, reconciliation review is read-only, and reconciliation accept is the dedicated receipt-bound acceptance write. metadata sync-status-from-review is a separate administrative write when overview state legitimately lags accepted evidence. At the slice boundary, work review is read-only, work project-review create explicitly persists project-review.md, and work close is the later terminal overview write. Generic recommendation apply, follow-up creation, and repair are separate receipt-bound mutations; no review command performs them.

Stale receipts, changed artifacts, or mismatched attempt identities fail closed and require a fresh matching review. Incomplete tasks return to task evidence; they are not repaired by forcing reconciliation to pass. The CLI does not automatically mutate review findings, silently synchronize status, demote Governed work, or migrate its hierarchy. See Governed reconciliation and closeout for the full evidence-owner and recovery sequence.

Metadata and lifecycle status

Exact root: metadata, plus the layer-specific slice update, phase update, milestone update, task update, implementation-summary update, and reconciliation update commands.

Inventory and validation are read-only. Update and sync commands require exact fields, compatible artifact families, and active-artifact preconditions where declared. Status changes record administrative state; they cannot replace body evidence.

Validation and trace links

Exact roots: validation and link.

validation smoke, links-check, rollups, scope guards, and diff checks report evidence only. Link materialization and disposition previews are read-only previews; their write/apply variants mutate only the explicitly selected scope after candidate-path review.

day-shift validation links-check --scope planning --artifact .day-shift/planning/example/phase-overview.md --format json
day-shift link materialize --dry-run --artifact .day-shift/planning/example/phase-overview.md --format json

Do not infer replacement targets or repair links from validation output. Use the safe materialization gate described in resume, trace, archive, and release handoff.

Structural pressure

Exact root: structural-pressure.

Reports are read-only. Sync is an explicit derived-state write allowed only after completed reconciliation establishes a current classification. Markdown task and reconciliation evidence remains canonical.

Common failures

• Unknown command or option: run commands search, then commands describe; do not guess syntax.
• Missing selection or precondition: refresh current/context evidence and retry only the same authorized action.
• Stale cursor or derived context: discard it and request a fresh bounded page or context pack.
• Validation finding: classify blockers separately from warnings; validation never grants repair authority.
• Partial write or conflict: stop and follow the typed rollback, inspection, or retry action.

For environment and recovery diagnosis, use troubleshooting.

Structured lifecycle command contract

Structured uses one canonical specification plus a numbered overview and numbered direct tasks. The semantic identities are spec_id, work_id, and task_id; implementation_order numbers the work root and parent-local sequence numbers each direct task root. Planning stores the canonical specification path and exact revision instead of copying requirements out of .day-shift/specs/.

The specification gate is deliberately split. spec review --spec <path> --reviewed-by <actor> --reviewed-at <timestamp> is read-only. spec disposition --spec <path> --planning-readiness ready --review-result <spec-review.json> --recorded-by <actor> --recorded-at <timestamp> is the separate revision-bound write. Neither action creates or relocates planning work. work create --spec <path> --work-id <id> --implementation-order <NN|next> is the later explicit Structured overview write when no level override changes the default.

work task create --overview <overview.md> --task <json> creates direct task pairs in dependency order. Every task JSON supplies taskId, objective, targetPaths, currentBehavior, desiredBehavior, acceptanceCriteria, validationCommands, rollbackRecovery, dependencies, and constraints. The CLI assigns the next sequence-derived prefix, keeps dependencies on stable task ids, and carries overview defaults for agent mode and evidence profile. Each pair’s implementation-summary.md is the canonical task implementation evidence.

Follow-up, review persistence, and closure are separate contracts:

CLI=day-shift
OVERVIEW=.day-shift/planning/structured/31-structured-evaluation/overview.md
PROJECT_REVIEW=.day-shift/planning/structured/31-structured-evaluation/project-review.md

$CLI work review --overview "$OVERVIEW" --format json

$CLI work project-review create \
  --overview "$OVERVIEW" \
  --disposition accepted \
  --reviewer feature-reviewer \
  --summary "The specification-bound Structured work is accepted."

$CLI work follow-up create \
  --project-review "$PROJECT_REVIEW" \
  --task-id harden-client \
  --dry-run

$CLI work close \
  --overview "$OVERVIEW" \
  --project-review "$PROJECT_REVIEW" \
  --dry-run

$CLI work close \
  --overview "$OVERVIEW" \
  --project-review "$PROJECT_REVIEW"

work review never writes project-review.md. work project-review create is the explicit canonical evidence write. A follow-up can materialize only a complete task contract already declared by canonical project review, and receives a later sequence without renaming prior tasks. work close changes only the selected overview and requires current accepted project-review evidence.

When the canonical specification revision changes, review reports stale binding without rewriting it. Recertify the canonical source through a fresh spec review and disposition, then create a fresh revision-bound Structured overview; the earlier overview remains evidence for its recorded revision. When direct-task coordination genuinely outgrows Structured, preview work promote --overview <overview.md> --to governed --implementation-order <NN> --slice <slug> --phase <ordered-phase> --task-mapping <task-id=milestone-id> --dry-run, then apply only the exact plan-id with --apply --plan-id <id> --actor <identity> --reason <reason>. Promotion preserves semantic task identity, dependencies, source links, and evidence; it does not authorize hand-created hierarchy or run phase, milestone, or reconciliation commands implicitly.