Operating model and artifact lifecycle

Day Shift is a local CLI that keeps coding-agent plans, scope, validation evidence, and handoff records in your repository.

These records give humans and coding agents a shared continuation point across sessions, tools, and contributors. Begin with the workflow level that fits the work; use the artifact and lifecycle detail on this page only when you need the technical model.

Choose the workflow level

Choose from observable coordination and review needs:

• Basic: The fastest path for one scoped task.
• Structured: The normal path for planned feature work.
• Governed: The staged path for formal review and reconciliation.

Basic appears first because it is the smallest useful path, not because it is the default. Structured remains the default when valid specification input exists and no explicit level or parent context overrides it.

Level	Best fit	Repository shape
Basic	The fastest path for one independent, low-coordination implementation task with known targets and resolved sequencing.	One direct pair under .day-shift/planning/basic/tasks/<NN>-<task-id>/.
Structured	Normal planned-feature work with a shared specification, one overview, and one or more direct tasks. It is the default when valid specification input exists and no explicit level or parent context overrides it.	.day-shift/planning/structured/<NN>-<work-id>/overview.md, direct tasks under tasks/<NN>-<task-id>/, and project review when needed.
Governed	Large, risky, long-running, cross-team, or formally reviewed work that needs staged hierarchy and reconciliation.	.day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md, phases, milestones, tasks, reconciliations, and project review.

Basic:      task definition → implementation summary
Structured: specification → work overview → direct tasks → project review and close
Governed:   specification → numbered slice overview → phase → milestone → task → implementation summary → reconciliation → project review and close

Workflow level controls organization only. It does not select evidence profile, agent mode, action authority, validation strength, or safety boundaries. Basic is not “less safe,” and Governed does not grant an agent broader permission.

Specification creation, refinement, read-only review, and planning-readiness disposition are separate from workflow selection. Specifications stay under .day-shift/specs/ when planning begins or is promoted.

Basic and Structured root prefixes come from implementation_order; values below 10 are zero-padded to two digits, while larger root orders retain their full width. A direct Structured task prefix remains the two-digit rendering of its parent-local sequence from 1 through 99. These prefixes order paths only. Work ids, task ids, dependency ids, attempts, reviews, validations, receipts, and closeout identities remain unprefixed.

Former nested Governed containers, unnumbered Basic/Structured roots and direct Structured task directories, and the lightweight/standard planning-depth model remain readable compatibility history. New writes use the numbered canonical shapes, and discovery never migrates compatibility paths implicitly. Any migration or promotion requires an explicit preview-bound write. Multiple Governed slices share specifications, dependencies, project views, or optional non-hierarchical initiative_id metadata rather than a shared lifecycle-directory parent.

Map a legacy Lightweight slice with exactly one independent task to Basic when preservation and dependency evidence allow it. Map legacy Lightweight work with coordinated direct tasks to Structured. Map legacy Lightweight work that needs staged formal hierarchy and reconciliation to Governed. These are content-aware migration decisions, not mechanical path renames.

Emergent work describes priority-interrupting intake, not a workflow level. Capture an operator report, production regression, or environment blocker as an emergent specification first, then choose Basic, Structured, or Governed from the same explicit evidence.

From work agreement to technical contract

Day Shift preserves the work agreement and implementation evidence in the repository where the work occurs. Together, the work agreement and implementation evidence form a Human-Agent-Contract.

The category describes the durable record, not automatic authority:

• Day Shift records the work agreement and implementation evidence. Review is read-only; acceptance and closure are explicit actions.
• Day Shift exposes collaboration policy to compatible agents but does not grant unlimited authority or force unsupported agents to comply.
• The current Day Shift CLI can explicitly execute and record one selected task validation command, or record or import evidence produced elsewhere. It does not automatically run every declared validation command.

Day Shift organizes and preserves agent-assisted engineering work. It does not replace the coding agent, Git, CI, issue tracking, or code review.

Artifact responsibilities

Artifact	Producer and purpose	Required relationships	Evidence and next consumer
Specification	A human or agent captures source intent, constraints, and success conditions.	Registered source identity and source reference.	Review/readiness establishes current intent; Structured or Governed planning consumes it.
Work overview	Structured planning groups one coherent delivery outcome.	Canonical specification identities, paths, and revisions.	Direct Structured tasks consume it.
Slice overview	Governed planning groups one staged delivery outcome at an ordered root.	Specification links, ordered slice_id, and optional non-hierarchical initiative_id.	Slice review and validation inform phase decomposition.
Phase overview	Planning orders a major stage of the slice.	Slice and specification traceability.	Phase review informs declared milestone creation.
Milestone overview	Planning declares an ordered, reviewable outcome and task set.	Phase, slice, and specification traceability.	Milestone review and declared-child validation govern task scaffolding.
Task definition	A planner freezes implementation scope, targets, acceptance criteria, dependencies, and validation.	Milestone ancestry in standard planning, or the lightweight parent context.	Readiness review gates the implementation handoff.
Implementation summary	The implementing agent records changed paths, validation, acceptance results, deviations, and discovered work.	Its task definition and full planning ancestry.	Summary review supplies task-closeout evidence; it does not replace the task contract.
Reconciliation	A reviewer rolls completed task summaries into acceptance, residual-work, and verdict evidence.	The applicable milestone or lightweight parent plus completed summaries.	Review and explicit status synchronization support the next parent or release handoff.

Workflow identity and planning coordinates identify location without changing lifecycle ownership. Legacy planning_depth remains compatibility metadata; current workflow_level records Basic, Structured, or Governed organization. Shared status is independent of family-specific lifecycle fields: task definitions own readiness, implementation summaries own implementation_status, and reconciliations own reconciliation_status. Upstream links accumulate by level so a later reader can recover both source intent and parent context.

Roles and ownership

• Humans own intent and authorization. They choose scope, risk tolerance, planning depth, acceptance tradeoffs, and any meaningful write or release decision.
• Agents own scoped execution and honest evidence. They follow the selected artifact, preserve unrelated work, validate proportionately, record deviations, and stop when evidence conflicts.
• The CLI owns deterministic mechanics. It scaffolds declared artifacts, validates structure and trace links, applies explicitly selected metadata or materialization writes, and reports findings.
• Reviewers own judgment. They assess whether evidence satisfies intent, classify residual work, and approve or reject lifecycle handoffs.

Ownership does not transfer implicitly. A recommendation from an agent or CLI is evidence for a human or workflow decision, not authorization to broaden scope.

Evidence gates and transitions

Creation and mutation commands are write-capable only when explicitly selected. By contrast, planning next-action, inventories, gap reports, readiness reviews, artifact reviews, validation links-check, and validation smoke are read-only. They can report findings or recommend a next command; they do not create children, repair links, update metadata, or advance lifecycle state.

The main gates are:

1. Recertify source intent before relying on stale or conflicting specifications.
2. Declare children at the parent layer before scaffolding them; never invent undeclared downstream work during expansion.
3. Require a task to be ready to implement before changing its runtime targets.
4. Close implementation with non-placeholder changed-path, validation, acceptance, deviation, and follow-up evidence.
5. Reconcile only after every in-scope summary is completed; review the reconciliation before any explicit parent-status synchronization.

Warnings require review or explicit acceptance. Errors block advancement. A review result may justify a later write-capable update, sync, build, or materialize command, but the write remains a separate action.

Resumability and lifecycle state

Repository artifacts make interrupted work recoverable. Re-open the selected task or parent overview, inspect scoped changes, identify the last passed gate, and rerun the current read-only review before continuing. Record structural pressure, scope growth, or newly discovered work in evidence instead of silently changing the declared contract. Archive or release only after reconciled evidence has reached the applicable parent and unresolved work has an explicit disposition.

Continue with Getting Started for workspace setup, workflow guides for procedural journeys, and reference for precise command contracts.

Structured specification, work, and task identity

Structured keeps source intent and delivery coordination separate. The canonical specification remains at .day-shift/specs/<NN>-<spec-id>/<spec-id>.md; specification creation, read-only review, and the revision-bound planning-readiness disposition do not create or relocate planning work. A later work create action consumes that ready source only after the operator explicitly selects the planning write.

A Structured overview stores the canonical repository-relative specification path and exact sha256: revision. It does not copy the specification requirements into .day-shift/planning/. This boundary keeps one spec_id authoritative while a stable work_id identifies the delivery outcome. The work root’s implementation_order supplies its minimum-two-digit directory prefix, but that ordering coordinate is not part of the semantic work identity.

Direct child tasks follow the same rule. Each stable task_id is placed under the next parent-local sequence, producing tasks/<NN>-<task-id>/. Dependencies refer to stable task ids, not numbered directory names, so adding a later task does not rename existing identities or rewrite dependency meaning. Structured direct tasks inherit the overview’s agent-mode and evidence-profile defaults—guided and runtime in the normal path—unless an individual contract explicitly overrides them.

Each direct task owns a task-definition.md work agreement and a paired implementation-summary.md as its canonical implementation evidence. A follow-up is not an informal extra task: accepted or accepted-with-follow-up project review declares its complete contract, and work follow-up create assigns the next sequence without changing earlier tasks. If direct-task coordination is no longer sufficient, work promote is a separate preview-bound Structured-to-Governed action. Neither discovery, review, follow-up reporting, nor promotion guidance silently inserts Governed hierarchy.

Project completion also remains split into observable actions. work review evaluates specification coverage and task evidence without writing. work project-review create is the explicit canonical evidence write, and work close is a separate overview-only transition that requires current accepted project-review evidence. Successful review output alone does not persist acceptance or close the work.