# Metadata Reference

This reference is the compact responsibility map for Day Shift metadata. It is documentation-only and does not change metadata schemas, update helpers, validation behavior, or artifact eligibility.

## Metadata Family Ownership

Each artifact family owns only the metadata fields that apply to that family. Shared `status` remains separate from family-specific fields such as task `readiness`, implementation-summary `implementation_status`, and reconciliation `reconciliation_status`.

Do not normalize one family field into another. A task definition owns `readiness`; an implementation summary owns `implementation_status`; a reconciliation artifact owns `reconciliation_status`; shared `status` remains the cross-family artifact lifecycle field.

## Metadata Families

Planning artifact metadata belongs to slice, phase, milestone, task-definition, implementation-summary, and reconciliation Markdown front matter. These artifacts use planning coordinates such as `slice`, `phase`, `milestone`, `task`, and `planning_depth`, plus applicable upstream parent links.

Specification metadata has two related surfaces:

- Specification Markdown front matter records source-spec identity and source reference context for repo-local specs.
- `.day-shift/specs/index.json` records registered spec entries, including fields such as `id`, `depth`, `status`, `implementation_order`, `destination`, `spec_path`, `source`, and `linked_slice`.

Prompt metadata belongs to prompt Markdown front matter and the prompt manifest. Prompt-family fields include `prompt_version`, `layer`, `action`, and prompt manifest relationships such as `template_ref` or `template_refs`.

Template metadata belongs to template Markdown front matter and the template manifest. Template-family fields and manifest entries preserve template identity, role, version, optional `destination`, usage, and notes.

Manifest metadata belongs to JSON manifest files. Manifest updates must preserve entry identity and unrelated entries unless the command explicitly requests a guarded replacement.

## Direct Intended Values

Metadata update commands should apply direct intended values supplied by the operator. They should not infer missing hierarchy changes, normalize one family field into another, or rewrite unrelated metadata.

`metadata update` is the generic write surface for helper-backed direct field updates. `metadata validate-update` runs the same routing and validation semantics as no-write evidence. Validate-update, review commands, and validation commands do not perform writes and do not authorize guessed corrections.

Direct intended-value updates use explicit field assignments, such as `--field status=completed` or `--field linked_slice.path=.day-shift/planning/example/overview.md`. If the request is incomplete, ambiguous, inconsistent, wrong-family, under-specified, or lossy, the correct outcome is a blocking no-write failure.

When an operator or agent has an explicit handoff context, update commands may include `--active-artifact <path>` alongside the command's selected artifact argument. The value is a stateless guard only: it must match the selected artifact path after repository-relative normalization, or the command rejects the update as a blocking no-write active-artifact conflict. Do not use `--active-artifact` as persistent session state or as a replacement for the command's required selected artifact argument.

For command adoption, keep metadata validation and metadata mutation in separate lanes. Use `metadata inventory` and `metadata validate-update` as no-write evidence, and use `metadata update`, artifact-specific update commands, or `metadata sync-status-from-review` only after the workflow explicitly selects a deterministic metadata write. If no metadata command owns a required transition, record `unsupported by CLI` or `CLI failed` before considering a manual front matter edit.

CLI-supported lifecycle metadata transitions must be applied through CLI update or sync surfaces rather than inference-driven front matter edits. This applies to shared `status` and family-specific lifecycle fields including task `readiness`, implementation-summary `implementation_status`, and reconciliation `reconciliation_status`.

Manual front matter metadata edits are exception-only. Use them only when the CLI surface is unsupported in the current checkout, the relevant command failed, or the workflow explicitly owns non-metadata body evidence and no command owns the requested metadata transition. In that case, record the manual exception, the command considered, and why the command was not used.

## Applicable Field Boundaries

Planning coordinates such as `slice`, `phase`, `milestone`, `task`, and `planning_depth` are valid only when the transition is coherent for the artifact family. Parent links must be updated only through explicit applicable parent-link fields.

Artifact-specific update commands narrow the generic metadata contract:

- `slice update`, `phase update`, and `milestone update` apply overview-owned fields only.
- `task update` applies task-definition fields such as `status`, `readiness`, and applicable planning coordinates.
- `implementation-summary update` applies implementation-summary fields such as `status`, `implementation_status`, and applicable planning coordinates.
- `reconciliation update` applies reconciliation fields such as `status`, `reconciliation_status`, and applicable planning coordinates.
- `spec update` applies mutable spec-registry fields and must reject identity-bearing registry rewrites.

Unsupported cross-family requests, such as setting `readiness` on a reconciliation artifact or `reconciliation_status` on a task definition, are wrong-family no-write failures.

## Parent-Link Updates

Parent-link fields are explicit metadata paths under `upstream`, not arbitrary path-like prose. Applicable parent-link fields include:

- `upstream.slice_overview`
- `upstream.phase_overview`
- `upstream.milestone_overview`
- `upstream.task_definition`

When a hierarchy transition affects parent links, update all applicable parent-link fields in the same coordinated repository-relative transition. Reject partial stale-link rewrites that leave one parent pointer on an old hierarchy while another points to the new hierarchy. Absolute paths, external URIs, and inferred rewrites from body text are outside the parent-link mutation contract.

Source and upstream spec references are a separate lane. `upstream.specs`, compatibility-sensitive `upstream.spec`, and specification-family `source` references should preserve source identity and apply only explicitly requested source-reference changes.

## Prompt And Template Metadata

Prompt metadata belongs to prompt front matter and the prompt manifest. Template metadata belongs to template front matter and the template manifest. Prompt `template_ref` relationships do not become template-manifest routing writes.

Prompt and template lanes must stay separate:

- Prompt front matter updates apply direct intended values to prompt-family keys such as `prompt_version`, `layer`, and `action`.
- Prompt manifest updates preserve prompt entry identity and preserve `template_ref` versus `template_refs` shape.
- Template front matter updates apply direct intended values to template-family keys while preserving body content.
- Template manifest updates preserve entry identity fields such as `path`, `kind`, `artifact_type`, optional `destination`, version, usage, and notes unless a guarded replacement explicitly owns those fields.

Do not infer template materialization destinations from prompt metadata, directory membership, or `artifact_type`.

## No-Write Validation

`metadata validate-update` and validation/review commands are read-only evidence surfaces. Findings may block a proposed write, but they do not perform a partial update or authorize guessed corrections.

Blocking no-write cases include:

- wrong metadata family or unsupported artifact family
- malformed Markdown front matter or malformed JSON manifest content
- ambiguous target family or command intent
- inconsistent status-family or planning-coordinate requests
- under-specified hierarchy, linked-slice, or manifest-entry updates
- lossy partial rewrites that would drop unrelated metadata, body content, manifest entries, source references, or path-bearing identity
- partial stale-link parent updates

No-write findings should be reported as evidence. A later write must use a separately named update, build, materialize, sync, or scaffold command with explicit scope.

Use `--active-artifact` on update commands when validating an explicit handoff from review, readiness, implementation, or reconciliation text to a later write. If the selected command artifact and active-artifact handoff disagree, stop and re-resolve the artifact path instead of narrowing or guessing the write target.

If an agent believes a direct metadata edit is necessary where a CLI update or sync command exists, it must stop before editing and report the exact CLI command considered, the evidence that prevents using it, the manual exception being invoked, and the artifact fields that would change. Do not silently replace CLI-supported metadata transitions with local inference.

## Canonical Sources

- `.day-shift/specs/05-planning-artifacts/artifact-model.md`
- `.day-shift/prompts/user/manifest.json`
- `.day-shift/templates/manifest.json`
- `.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/workflow-guide.md`
