# Day Shift HAC Entrypoint

This is the workspace-level entrypoint for agents working with Day Shift artifacts in this initialized repository.

Read this file before creating plans, changing code, writing implementation summaries, or reconciling completed work.

## What This Workspace Covers

This workspace has an initialized Day Shift layout under `.day-shift/`.

Prefer the installed CLI command `day-shift` for command-supported planning work after verifying it in the current environment. Use repository-development entrypoints only when you are intentionally working on Day Shift CLI internals.

The source of truth for planning lineage is the registered source-spec reference recorded in `.day-shift/specs/index.json`. For source intent, follow each spec registration's `source.ref` entry.

## What Day Shift Is For

Day Shift HAC (Human Agent Contract) is a planning system for human-agent software work. It turns broad intent into explicit repository artifacts so implementation and review decisions stay traceable.

## Repository Contract

- Keep Day Shift-owned state under `.day-shift/`.
- Treat `.day-shift/` references as relative to the effective workspace root selected for the current invocation.
- Supported workspaces may live at repository root or under a supported repository subdirectory when a valid `.day-shift/config.toml` marker defines that workspace.
- Treat external specifications as references by default. Do not assume specs must live under `.day-shift/`.
- Prefer repository-relative paths in generated artifacts and metadata.
- Do not write absolute local paths into committed planning documents.
- Preserve user-authored planning content when updating generated files.
- Keep planning depth proportional to risk and scope.
- Treat emergent work as distinct from planning depth, discovered work, backlog work, and scope creep.
- When automation is missing, update the relevant files manually and make the manual step obvious in summaries.

## Planning Model

Standard planning flow:

```text
specification -> slice -> phase -> milestone -> task -> implementation -> reconciliation
```

Lightweight planning is allowed for low-risk, narrow work when the user explicitly chooses it. Lightweight planning skips phase and milestone artifacts but still requires task evidence, implementation summary, and reconciliation.

Emergent work is a separate intake lane for priority-interrupting reports such as user-testing failures, environment failures, regressions, or operator-reported blockers.

## Initialized Workspace Layout

```text
.day-shift/
├── config.toml
├── local.toml
├── agents.md
├── planning/
│   ├── basic/
│   ├── structured/
│   └── governed/
├── prompts/
│   ├── latest/
│   └── user/
├── specs/
│   ├── 00-emergent/
│   └── index.json
└── templates/
```

`.day-shift/planning/` is local by default. `.day-shift/config.toml`, `.day-shift/agents.md`, templates, references, and workflows may be committed when the team wants shared planning behavior.

## Collaboration Workflows

Use `.day-shift/workflows/01-start-here.md` before beginning a planning or implementation session.

When a request references `.day-shift/workflows/*`, read that workflow and obey its operational rules as mandatory unless the workflow explicitly marks a step optional.

## Agent Lifecycle Routing

This file is the entrypoint, not the full lifecycle manual. After reading it, choose the layer-specific lifecycle guide that matches the artifact you are operating on:

- Task execution: `.day-shift/workflows/task.agent-lifecycle-guide.md`
- Milestone coordination: `.day-shift/workflows/milestone.agent-lifecycle-guide.md`
- Phase coordination: `.day-shift/workflows/phase.agent-lifecycle-guide.md`
- Slice coordination: `.day-shift/workflows/slice.agent-lifecycle-guide.md`

## Planning And Lifecycle Guardrails

- Apply durable-contract verb discipline before saving planning artifacts: use `define` only for a named contract, boundary, schema, vocabulary, policy, rule, interface, or decision that downstream work consumes; use implementation verbs for executable outcomes.
- Before child scaffolding, require the parent to state `Target <child> count: N` and an authored `Decomposition rationale:` that names a concrete implementation, dependency, validation, rollback, or ownership boundary. Reject absent, contradictory, or pattern-derived rationale; never infer a familiar child count from nearby plans. One child remains valid when one real boundary is sufficient.
- Preserve mode balance for runtime-sensitive work. Put a runtime or hybrid breakout early, evaluate remaining runtime acceptance after every task closeout, and do not continue contract-only progression after the configured streak threshold.
- For runtime or hybrid tasks that require attribution, capture the task-cycle baseline after readiness and authorization but before the first write. Close out only with current-cycle fresh runtime paths, executable validation, and the exact inherited acceptance IDs; pre-existing dirty state or file presence is not fresh evidence.
- When mode-balance review reports pending runtime acceptance, follow the deterministic Documentation Loop Recovery Protocol in `.day-shift/references/validation-and-review.md`: detect, execute the authorized breakout, verify freshness, rebuild reconciliation, rerun milestone review, then rerun phase review. Do not invent or reorder work.
- Run the canonical pre-save authoring audit before any single-child or full-set scaffold write. Treat rejection as atomic and no-write; do not create partial child, summary, or reconciliation artifacts.
- Keep planning writes CLI-first. Record CLI provenance, or exactly one named manual exception when required: `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification`.
- Before acting on a rendered prompt, verify its generated-context evidence: requested prompt path, resolved layer and repository-relative path, source family, fallback trace, and user-layer destination. The resolved body and provenance are authoritative; source-file presence elsewhere is not delivery evidence.

## Agent Workflow

Before changing implementation code:

- Read the selected spec and its registered `source.ref`.
- Check `.day-shift/specs/index.json` for registered specs.
- Resolve the effective workspace root before assuming where `.day-shift/` lives.
- For command-supported planning artifact creation, use the Day Shift CLI first.
- Do not advance from spec to slice, slice to phase, phase to milestone, or milestone to task unless the user explicitly requested that lifecycle step or an existing workflow command selected it as the active write.
- Treat review, navigation, hardening, and improvement requests as read-only or selected-artifact edit work by default. Do not create downstream planning artifacts from those requests unless explicitly requested.

While changing implementation code:

- Keep changes inside declared scope unless there is explicit discovered-work evidence.
- Update planning artifacts when implementation reveals a meaningful scope change.
- Prefer small, traceable changes that can be tied back to a task definition.

After changing implementation code:

- Write or update an implementation summary when there is a task artifact to reconcile.
- Record changed paths, validation performed, and deviations from the task definition.
- Record completed work, discovered work, follow-up work, and review concerns.
- Do not claim reconciliation is complete automatically; leave explicit review fields for the user or agent.

## Intended CLI Defaults

- Runtime: Node.js LTS and TypeScript.
- Argument parser: `commander`.
- Package manager: `pnpm`.
- Config file: `.day-shift/config.toml`.
- Agent entrypoint: `.day-shift/agents.md`.
- Spec registry: `.day-shift/specs/index.json`.
- Planning root: `.day-shift/planning`.
- Prompt root: `.day-shift/prompts`.
