# Commands Reference

This reference is the compact responsibility map for Day Shift command families used by onboarding, planning, implementation, and reconciliation workflows. It is documentation-only and does not change command behavior, output shape, validation semantics, or mutation permissions.

## Command Family Boundary

Choose commands by operator intent. Write-capable commands mutate explicit artifact families. Review, validation, inventory, and navigation commands report evidence only.

Use command help as the local truth for exact flags in a checkout:

```sh
<day-shift-cli> --help
<day-shift-cli> <family> --help
<day-shift-cli> <family> <command> --help
```

The workflows use `<day-shift-cli>` as an invocation placeholder. In installed/user mode, resolve it to the verified installed command, usually `day-shift`. In repository development mode, resolve it to `node dist/cli/index.js` when compiled `dist` output is current. Treat `node dist/cli/index.js` as a development/session invocation only; installed user-facing documentation, help, and examples should continue to show the installed command name.

Use the narrowest descriptor-backed discovery surface that answers the question:

- `commands search <query> --format json` finds a bounded, ranked subset by command identity, intent, capability, artifact family, authorization, or posture. Multiword queries are tokenized.
- `commands describe <command...> --format json` returns one authoritative descriptor with inputs, defaults, validation notes, exact argv examples, effects, authorization, and transition metadata.
- `commands inventory --format json` remains the surface-wide audit source for callable versus registry-only state, mixed-posture families, and coverage across the complete Commander tree.
- `commands manifest [command...] --format json` projects one or all descriptors into native tool bindings.
- `commands validate --format json` checks callable descriptor coverage, migrated input alignment, and generated manifest drift. Read `inputCoverage.coverageVerdict` separately from `verdict`: migrated drift can be valid while repository-wide descriptor-input migration remains partial.

All five commands are read-only evidence. They do not authorize writes, repair registry gaps, or replace command help for a command whose descriptor input coverage is still absent.

For command-family help and regression coverage, prefer positive assertions for command presence, option surfaces, posture wording, and explicit no-write/write-capable boundaries. Keep absence assertions only when absence is the product behavior under test, such as a command intentionally not exposing a write mode, private issuer surface, external publication path, or unsupported alias.

When a lifecycle audit needs one command, use `commands search` and then `commands describe`. Use inventory only for whole-surface audits, and fall back to current command help when `commands validate` reports that the command is still listed in `inputCoverage.missingDescriptorInputCommands`. Record unsupported, registry-only, or ambiguous behavior as discovered work instead of inferring support from adjacent command names.

Manual artifact edits are allowed only when the active workflow records one of these exceptions: `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification`. Review, validation, inventory, next-action, explain, preview, report, list, show, status, doctor, and check outputs remain evidence only; a later mutation still needs a separately selected scaffold, build, update, sync, apply, materialize, install, checkpoint, migration-apply, or release-output command.

## Write-Capable Surfaces

Write-capable surfaces include commands that create, update, install, materialize, build, promote, sync, or migrate explicit targets. A write command owns only the artifact family and destination named by its command contract.

Planning scaffold writers:

- `work create --level basic|structured|governed` creates the selected canonical entry shape. Basic accepts one complete direct task contract; Structured and Governed require canonical planning-ready specifications.
- `work task create` creates ordered direct tasks beneath one Structured overview.
- `slice new`, `phase new`, `milestone new`, and `task new` remain the Governed layer-specific scaffold writers and create only declared children.
- `task promote` previews/applies Basic-to-Structured or Basic-to-Governed promotion.
- `work promote` previews/applies Structured-to-Governed promotion.

Workflow level controls organization only. `--agent-mode` and `--evidence-profile` are independent inputs, and no level grants write authority or weakens review, validation, confirmation, or recovery boundaries. Specification creation/review/readiness also remains separate: `spec create` requires `--implementation-order <number|next>` for the canonical numbered spec prefix, but it does not choose a level or create planning directories.

`spec create --implementation-order next` selects the lowest unused order from `01` through `99` using registered order metadata, registered numbered canonical paths, and existing numbered canonical spec directories. An explicit value in the same range selects that two-digit prefix directly; `00` remains reserved for emergent intake. Creation writes `.day-shift/specs/<implementation-order>-<spec-id>/<spec-id>.md` and records the same string-valued `implementation_order` in specification front matter and the registry.

Canonical creation destinations are:

```text
.day-shift/planning/basic/tasks/<task-id>/
.day-shift/planning/structured/<work-id>/
.day-shift/planning/governed/<NN>-<slice-slug>/
```

Former nested Governed containers and older top-level numbered roots are readable compatibility history, not new-write destinations. A Structured `work_id` remains source provenance after Structured-to-Governed promotion; Governed identity is the ordered `slice_id`. Optional `initiative_id` groups slices without adding a lifecycle directory.

Metadata and lifecycle writers:

- `metadata update` applies direct intended metadata field values to one metadata-bearing artifact.
- Artifact-specific update commands such as `spec update`, `slice update`, `phase update`, `milestone update`, `task update`, `implementation-summary update`, and `reconciliation update` apply the narrower field set owned by that artifact family.
- `metadata sync-status-from-review` writes only when completed review evidence makes the status transition deterministic.

Workspace migration has two modes under the same command family:

- Schema mode uses `workspace migrate --target-schema-version <version> --dry-run`, then the exact `--confirm apply-workspace-migration` apply form.
- Structural mode uses `workspace migrate --check`, `--plan`, then `--apply --expected-plan-digest <digest> --confirm apply-workspace-migration` with any required `--mapping <work-unit-id=level>` selections.

Check, dry-run, and plan are read-only. Structural apply may create canonical work parents, move planning artifacts, retire legacy sources, record old-to-new mappings, and write transaction evidence. Ambiguous classification, stale plan digest, collision, invalid path, or incomplete transaction fails without claiming success; inspect typed recovery evidence before retrying or restoring.

CLI-supported metadata transitions are command-owned. When a supported update or sync command can apply a lifecycle metadata transition, use that command instead of hand-editing front matter fields such as `status`, `readiness`, `implementation_status`, or `reconciliation_status`. Manual metadata edits are allowed only for an explicit exception: the CLI surface is unsupported in the current checkout, the command fails, or the workflow step is completing non-metadata artifact body evidence and no metadata command owns the transition. Record the exception and the command that was considered.

Explicit active-artifact handoff:

- Metadata update and artifact-specific planning update commands accept `--active-artifact <path>` as an optional stateless handoff guard.
- Use `--active-artifact` when conversational context, a workflow handoff, or a resume step names the artifact that should still be active and the write command also selects an artifact path.
- The active artifact path must normalize to the same repository-relative path as the command's selected artifact argument, such as `--task-definition`, `--summary`, `--reconciliation`, `--slice-overview`, `--phase-overview`, `--milestone-overview`, or generic `--artifact`.
- A mismatch is a blocking no-write active-artifact conflict. It is evidence that the handoff context and write target disagree; rerun with matching paths, correct the selected artifact, or omit `--active-artifact` when no explicit handoff is being checked.
- `--active-artifact` is not persistent session state, does not select an artifact by itself, and does not authorize writes that the command contract would otherwise reject.

Build, materialize, and install writers:

- `implementation-summary build` and `reconciliation build` refresh paired execution or review artifacts at their canonical destinations.
- `link materialize --dry-run --artifact <path>` performs selected-scope link validation and candidate inspection together without writing files. A clean zero-candidate preview can be reused as the lifecycle link gate while its exact evidence boundary remains current; candidate writes use `link materialize --write --artifact <path> --validation-evidence-id <evidence-id>` and report post-write validation evidence, changed paths, and rollback guidance.
- `prompt init`, `prompt edit`, `prompt update`, `template update`, and `manifest update` are explicit prompt, template, or manifest mutation surfaces.
- `ignore install`, `init`, completion install/uninstall commands, and workspace migration apply flows write only when the operator invokes the relevant write surface.
- `structural-pressure sync` mirrors completed reconciliation evidence into derived JSON state after reconciliation is eligible.

Each writer must not infer adjacent-family writes from findings, suggestions, paths, command output, or prompt/template references. If a write needs coordinated metadata changes, the command contract must name that coordination explicitly.

Before any direct front matter metadata edit, check the matching command family first: `task update`, `implementation-summary update`, `reconciliation update`, `milestone update`, `phase update`, or `metadata sync-status-from-review`. If a command exists but cannot be used, stop and report the command considered, why it is insufficient or unsafe, the manual exception, and the exact artifact fields that would be changed.

## Read-Only Review And Validation

Review and validation commands are no-write evidence surfaces. They may report blockers, warnings, missing evidence, trace-link findings, or likely next steps, but their output does not authorize a later write by itself.

Read-only review examples:

- `task readiness-review`
- `task review`
- `milestone review`
- `phase review`
- `implementation-summary review`
- `reconciliation review`

Read-only validation examples:

- `validation links-check --scope planning --artifact <path>` takes one selected artifact or directory and reports local trace-link, hierarchy, and paired-artifact evidence.
- `validation smoke --scope planning --artifact <path>` takes one selected planning artifact and reports focused metadata, declared-child, inventory, gap, alignment, and likely-next-action evidence for that artifact.
- repository-wide `validation smoke` reports broad planning-validation context and may include unrelated historical findings.
- `validation rollup`
- `metadata validate-update`

Use these commands to decide whether an artifact is ready, complete, internally consistent, or safe to advance. Use a separate explicit writer to act on the findings.

For Markdown body-link materialization, use `link materialize --dry-run --artifact <path>` as the combined selected-scope link-validation and candidate-inspection gate; a preceding standalone `validation links-check` is not required. Reuse clean zero-candidate evidence only while the repository, artifact, planning scope, selected revision digest, candidate state, and finding state remain exact. When candidates exist, use `link materialize --write --artifact <path> --validation-evidence-id <evidence-id>` with the current preview identity, then continue from current `postWriteValidationEvidence` or run only the exact `requiredRecheck` when post-write proof is unavailable. `validation links-check --scope planning --artifact <path>` remains an independent read-only diagnostic surface and does not authorize materialization writes.

When a planning scaffold writer creates a child layer from an existing parent planning artifact, apply that same combined gate to the parent before closeout: preview `link materialize --dry-run --artifact <parent-artifact-path>`, and when safe body-link candidates are reported write with `link materialize --write --artifact <parent-artifact-path> --validation-evidence-id <evidence-id>`. Use the returned `postWriteValidationEvidence`, or only its exact `requiredRecheck` when needed, as the current gate. This materializes newly resolvable child references in the previous layer; it does not authorize metadata rewrites, hierarchy repair, or additional scaffolding.

## Read-Only Navigation

Navigation and inventory helpers orient the operator without mutating artifacts:

- `commands inventory --format json` reports callable command evidence merged with command capability metadata, including write posture, artifact family, selected-artifact requirements, registry-only entries, and mixed-posture families.
- `commands search`, `commands describe`, and `commands manifest` provide bounded descriptor-backed command and tool discovery without loading the full inventory.
- `commands validate` reports descriptor/runtime/tool drift plus separate repository-wide descriptor-input coverage.
- `spec list` and `spec search` select registered source specifications.
- `planning inventory` takes a workspace, planning root, or selected scope and reports observed hierarchy plus paired evidence artifacts.
- `planning gap-report` takes a workspace, planning scope, or selected artifact and reports expected-but-missing, placeholder-heavy, or incomplete downstream artifacts.
- `planning next-action` takes the selected artifact or scope and reports the most likely valid next planning or review step from current evidence.
- `workflow explain` takes a selected artifact or workflow question and reports the workflow file, prompt handoff, and contract boundary that match that evidence state.
- `metadata inventory` reports metadata state, helper coverage, and update opportunities.
- `templates list` reports template-family inventory and adjacent manifest evidence.
- `structural-pressure report` summarizes current structural-pressure state without syncing derived JSON.
- `agent`, `agent orient`, `agent remind`, `about`, `doctor`, `config`, `license`, `release`, `workspace` inspection, and similar discovery commands provide orientation or environment evidence unless their specific subcommand help identifies an explicit write mode.

Read-only does not always mean exit code zero in every fixture. Diagnostic read-only commands may return a nonzero health or findings exit code while still satisfying the no-write boundary when they leave the selected workspace unchanged and report evidence only. For grouped command surfaces, posture tests may use an executable read-only subcommand such as `config get` to represent the registered group surface when the bare group command is help or dispatch-only.

When navigation output suggests a next action, treat it as advisory evidence. The operator or agent must still invoke the appropriate scaffold, update, build, sync, materialize, migration, metadata, implementation, review, or reconciliation workflow explicitly. Navigation output does not replace the source spec, planning artifact, implementation summary, reconciliation artifact, or review evidence it points to.

For agent work, start with compact orientation and one explicit selection. `work candidates`, `work select`, `work current`, `work next`, and `work clear` keep selection lifecycle explicit; `agent context` returns bounded selected-artifact evidence; `resume` manages interruption capsules. These local state surfaces do not grant authorization and must yield to explicit arguments and current canonical-file freshness.

Use scoped doctor modes for the current decision: `--runtime-only`, `--artifact`, or `--planning-directory`, optionally paired with one exact `--action`. Reserve `--repository-audit` for an intentionally broad gate. See `.day-shift/references/small-model-agent-operations.md` for the complete compact-output and recovery loop.

Every callable runtime command that accepts arguments or options is represented by descriptor inputs and a generated native tool schema. `commands validate` compares all such commands, not a migration allowlist; any missing or mismatched input makes coverage partial and the drift verdict invalid.

## Workflow Usage Notes

Use the narrowest command surface that matches the workflow step:

- Planning from specs starts with `spec list` or `spec search`, then explicit scaffold writers such as `slice new`, `phase new`, `milestone new`, or `task new`.
- After a scaffold writer creates a child planning layer from a parent overview, run the parent overview's combined `link materialize --dry-run` gate and evidence-bound safe `--write` when candidates exist so declared child references in the previous layer are materialized as clickable Markdown links when possible.
- Command-surface adoption or guidance work starts with `commands search`, narrows with `commands describe`, uses `commands validate` for drift and input-coverage evidence, and reserves full inventory for audits that genuinely need the complete surface.
- Task execution starts with `task readiness-review`, performs scoped implementation, then uses `implementation-summary build` plus manual closeout when needed and `implementation-summary review` for no-write evidence.
- Task closeout should use `implementation-summary build` and manual body evidence updates for summary content, `implementation-summary review` for read-only sufficiency evidence, and `metadata sync-status-from-review` or `task update --active-artifact <same-task-definition-path>` for task-definition `readiness` and `status` transitions when supported.
- Milestone reconciliation waits for completed task summaries, then uses `reconciliation build` and `reconciliation review`.
- Planning validation should prefer artifact-scoped commands such as `validation links-check --scope planning --artifact <path>` and `validation smoke --scope planning --artifact <path>` when the current decision is local to one artifact.
- When a workflow handoff already names the intended active artifact, pass the same repository-relative path through `--active-artifact` on a write-capable update command to make context drift a no-write failure.

Do not substitute repository-wide warning cleanup for the selected artifact's task, implementation-summary, or reconciliation validation unless the active task explicitly declares that broader scope.

## Canonical Sources

- `node dist/cli/index.js --help`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/workflow-guide.md`
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/milestone.agent-lifecycle-guide.md`
