# Spec Registry Reference

This reference is the compact responsibility map for the spec registry. It is documentation-only and does not change spec registry schema, source resolution, planning behavior, or validation semantics.

## Registry Responsibility

`.day-shift/specs/index.json` records registered specifications and their source references. The registry helps select implementation order and preserve traceability from planning artifacts back to source intent.

Treat the registry as source-spec metadata. Planning artifacts copy traceability from it, but registry entries are not themselves slice, phase, milestone, task, implementation-summary, or reconciliation metadata.

## Registry Fields

Each entry in `specs` uses stable fields to identify the source and its planned destination:

- `id`: stable registry identity for command selection, search, and traceability.
- `title`: human-readable label for listings and search results.
- `depth`: intended planning depth, usually `standard` or `lightweight`.
- `status`: registry lifecycle state such as `active` or `archived`.
- `implementation_order`: ordered planning lane used when creating planning roots, for example `16`.
- `destination`: stable destination slug used with `implementation_order` to derive the planning directory.
- `spec_path`: repository-relative path to a repo-local specification when the spec is stored in this workspace.
- `source`: original source reference metadata. `source.type` identifies the source kind, and `source.ref` preserves the operator-supplied or external source reference.
- `linked_slice`: optional metadata added after a planning slice exists. It records the slice identity and the repository-relative slice overview path.

Registry update commands may support mutable fields, but identity-bearing fields and coordinated linked-slice updates must follow the metadata update contract. Do not infer registry rewrites from downstream planning paths or validation findings.

`spec create` requires `--implementation-order <number|next>`. It stores a normalized two-digit order from `01` through `99` as a string and creates the canonical source beneath `.day-shift/specs/<implementation-order>-<spec-id>/`; `00` remains reserved for emergent intake. `next` fills the lowest unused order using registered order metadata, registered numbered canonical paths, and existing numbered canonical spec directories; an explicit number permits intentional reuse or reserved sequencing within the same range.

## Source References

Specification sources may live inside or outside `.day-shift/`. Treat the registered `source.ref` as the source-spec reference for CLI behavior and planning traceability. Do not assume every source specification must be copied into `.day-shift/specs/`.

When `spec_path` and `source.ref` both exist, they answer different questions. `spec_path` points to the workspace copy used by local planning. `source.ref` preserves where the source intent came from, which may be a message, external document, repository file, or other reference.

## Linked Slice Metadata

`linked_slice` connects a registered source spec to the planning slice created from it. The field should remain repository-relative and should not replace downstream parent links.

For the current onboarding redesign spec, the registry entry records:

```json
{
  "id": "onboarding-experience-redesign",
  "depth": "standard",
  "status": "active",
  "implementation_order": "16",
  "destination": "onboarding-experience-redesign",
  "spec_path": ".day-shift/specs/16-onboarding-experience-redesign/onboarding-experience-redesign.md",
  "source": {
    "type": "message",
    "ref": "User-provided onboarding experience redesign document"
  },
  "linked_slice": {
    "slice": "16-onboarding-experience-redesign",
    "path": ".day-shift/planning/governed/16-onboarding-experience-redesign/slice-overview.md"
  }
}
```

The planning slice, phase, milestone, and task artifacts still carry their own `upstream` parent links. `linked_slice.path` is registry context, not a replacement for `upstream.slice_overview`, `upstream.phase_overview`, `upstream.milestone_overview`, or `upstream.task_definition`.

## Planning Traceability

Planning artifacts should preserve `upstream.specs` as the default traceability shape and keep parent planning links explicit by layer: `slice_overview`, `phase_overview`, `milestone_overview`, and `task_definition` when applicable.

Use one `upstream.specs` entry per contributing registered spec. Preserve the registry `id`, `depth`, source reference, and source type when carrying traceability into planning artifacts. For single-spec artifacts, prefer the one-entry list shape unless compatibility with an older artifact requires `upstream.spec`.

## Shared Slice Inputs

When several registered specs share one planning slice, preserve each contributing source entry under `upstream.specs`. Do not collapse multi-spec traceability into a single inferred source.

## Emergent Intake

Emergent work belongs in a distinct intake lane. Repo-local emergent specs should use `.day-shift/specs/00-emergent/` and planning slices should normally use a `00-emergent-<slug>` directory.

Emergent registry entries should preserve intake context such as `origin`, `emergent_source`, `reported_at`, and `implementation_order: "00"` when present. That context remains registry/source metadata and should not be flattened into downstream planning status fields.

## Canonical Sources

- `.day-shift/specs/index.json`
- `.day-shift/specs/16-onboarding-experience-redesign/onboarding-experience-redesign.md`
- `.day-shift/planning/governed/16-onboarding-experience-redesign/slice-overview.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/agents.md`
