# Validation And Review Reference

This reference is the compact responsibility map for validation, review, and structural-pressure policy. It is documentation-only and does not change validation semantics, review commands, findings taxonomy, or structural-pressure sync behavior.

## Review Command Posture

Planning review commands are read-only findings surfaces. `task readiness-review`, `task review`, `milestone review`, `phase review`, `implementation-summary review`, and `reconciliation review` evaluate evidence and report blockers, warnings, or metadata hygiene follow-ups without writing artifacts.

Review commands do not:

- create missing artifacts
- repair task, milestone, phase, or reconciliation content
- advance lifecycle metadata
- mark implementation or reconciliation complete
- authorize unrelated cleanup

When a review command recommends a deterministic next step, treat that recommendation as evidence. A later write still needs an explicit write-capable command, scoped artifact edit, or lifecycle step.

Command adoption guidance should preserve that boundary even when review output names a likely command. A review recommendation may identify a scaffold, build, update, sync, or reconciliation step, but the operator or agent must still select that write surface explicitly and keep the write scoped to the active artifact.

## Documentation Loop Recovery Protocol

Structured mode-balance review activates only when explicit runtime-acceptance metadata opts an artifact into the contract. The parent criterion IDs, declared task order, configured contract streak, complete exception evidence, task execution modes, lifecycle completion, and current-cycle attribution are authoritative. Filename verbs, changed-path prose, ordinary dirty state, and completion status cannot satisfy or override that structured evidence. Artifacts that predate the structured task-attribution opt-in retain their existing runtime changed-path and executable-validation review semantics.

Task closeout review, milestone review, and phase review project this exact ordered protocol when runtime acceptance remains pending:

1. `detect`: confirm the structured mode-balance blocker for the selected task or milestone with a read-only review.
2. `execute-authorized-breakout`: implement the already declared runtime or hybrid breakout through `.day-shift/workflows/03-implement-from-task.md`; do not scaffold or reorder tasks.
3. `verify-freshness`: run `implementation-summary review` for the breakout and require matching task-cycle identity, fresh runtime paths, executable validation, empty ineligible paths, and exact inherited acceptance IDs.
4. `rebuild-reconciliation`: explicitly run `reconciliation build` for the selected milestone only after freshness review succeeds.
5. `rerun-milestone-review`: run the read-only milestone review after reconciliation is rebuilt.
6. `rerun-phase-review`: run the read-only phase review only after milestone review clears.

Detection and every review step are read-only. Step 2 is authorized task execution and step 4 is an explicit reconciliation write; review output never performs either write implicitly. The protocol never creates a replacement breakout, reorders declared work, edits source or planning content, updates status metadata, or recommends repeating unchanged review as the primary recovery action. If the declared breakout path is missing or under-specified, stop with a typed contract blocker and repair the contract separately instead of inventing a task.

## Validation Command Posture

`validation links-check`, `validation smoke`, `validation rollup`, and related validation commands provide evidence. They do not repair links, mutate metadata, create missing artifacts, update derived state, or authorize cross-family writes.

Validation output may identify missing links, stale hierarchy relationships, unsupported artifacts, malformed artifacts, current next-action guidance, or repository-wide historical warnings. Those findings remain no-write evidence unless the operator separately invokes the appropriate planning, metadata, or implementation workflow that owns the write.

When validation reports a command gap, unsupported artifact, or outside-coverage evidence, record it as validation evidence or discovered work. Do not rewrite links, invent replacement targets, create planning artifacts, update status metadata, or normalize unsupported evidence into another artifact family from validation output alone.

Validation commands should preserve selected-artifact, directory, and root semantics. Do not replace file-scoped evidence with broad recursive cleanup unless the active task explicitly asks for directory or repository-wide evidence.

## Findings Taxonomy

Blocking evidence should remain distinct from warnings and informational follow-ups.

- Blocking findings identify conditions that prevent the current lifecycle gate from safely advancing.
- Warnings identify review or validation concerns that should be recorded, accepted, or handled in a later scoped task.
- Informational or metadata-hygiene findings identify cleanup or consistency work that does not block the current gate by itself.

Findings are not mutation instructions. Do not narrow, guess, or partially apply a write based only on a finding. Wrong-family, ambiguous, inconsistent, under-specified, and lossy update requests should remain blocking no-write outcomes on write-attempt surfaces.

## Scoped Validation

Prefer artifact-scoped validation for current-step evidence:

- Use `validation links-check --scope planning --artifact <path>` when the input is one selected planning artifact and the needed output is local trace-link, parent-link, hierarchy, or paired-artifact relationship evidence.
- Use `validation smoke --scope planning --artifact <path>` when the input is one selected planning artifact and the needed output is focused planning readiness, declared-child, inventory, gap, or likely-next-action evidence for that artifact.
- Use repository-wide `validation smoke` only when broad repository context is intentionally in scope.

Artifact-scoped validation keeps evidence tied to the selected planning artifact, task definition, reference page, or milestone under review. Repository-wide validation may report unrelated historical findings; record those findings only when they affect the active task, milestone, or review gate.

## Long-Running Command And Evidence Inspection

An execution-surface yield is a transport state, not a command result. When it includes a live process or continuation handle, retain that handle and poll the same invocation to a terminal result. Do not rerun the command solely because the first call yielded, and do not classify a caller-side wait budget as a command timeout while the handle remains live.

Keep `running`, `timed out`, `interrupted`, `failed`, and `completed` distinct. A running command still has a live handle. A timed-out command has reached a terminal command-owned deadline outcome. An interrupted command ended without a command-owned terminal result and may require side-effect inspection before retry. A failed command returned a terminal unsuccessful result. A completed command returned a terminal successful result with all required output. Long validations should produce user-visible progress at least every 60 seconds by polling the existing invocation, not by changing command identity.

Evidence inspection should prefer authored, decision-relevant content over serialized lifecycle payloads. Separate Markdown front matter from its body, select named body sections, and exclude serialized attempts, validation records, review receipts, and disposition payloads from body searches by default. For JSON or YAML, select exact structured fields. Bound file count, match count, context, and output size before broadening scope; do not start with an unbounded repository-wide recursive search over planning artifacts.

Serialized lifecycle evidence remains available when it is the selected source. Parse it explicitly, choose the relevant attempt, validation, receipt, or disposition fields, and keep the rendered result bounded instead of discarding the payload or mixing it into authored-body search results.

### Safe Link Materialization Gate

After a planning scaffold or overview body change, run selected-artifact `validation links-check`, then matching `link materialize --dry-run`. Run `link materialize --write` only when `candidateCount > 0`, every `previewChangedPaths` entry remains inside the selected artifact scope, and the current request authorizes planning-body writes. Dry-run `changedPaths` is empty by design. This named gate is the shared rule for task, milestone, and phase workflows; layer guides should reference it rather than redefining its write boundary.

When validating reference pages that are not planning artifacts, a validation command may report the page as outside planning-artifact parser coverage. That is useful coverage evidence, not an instruction to relocate or reclassify the reference page.

## Implementation Summary Gate

Task implementation summaries become milestone review evidence only after they are completed, non-placeholder, and include:

- `implementation_status: completed`
- `status: completed`
- changed paths
- validation evidence or an explicit validation exception
- acceptance-criteria review
- scope classification
- deviations or a clear none-state
- risks, discovered work, or follow-up work

When a CLI update or sync command owns these lifecycle metadata fields, use that command instead of inferring and hand-editing front matter. Treat status fields as command-supported lifecycle outputs backed by body evidence, not as evidence by themselves.

Implementation-summary build commands refresh paired artifacts at canonical destinations. Implementation-summary review commands evaluate evidence without writing or advancing metadata.

## Milestone Reconciliation Gate

Milestone reconciliation is eligible only after every declared task under the milestone has a completed, non-placeholder implementation summary. A pending reconciliation placeholder is expected before that gate.

Milestone reconciliation uses the milestone overview plus completed task implementation summaries as review inputs. It should not be used to compensate for missing task evidence, unresolved task blockers, or placeholder-heavy summaries.

Reconciliation build commands refresh the milestone-level reconciliation artifact at its canonical destination. Reconciliation review commands evaluate milestone closure evidence without writing or auto-accepting the review.

## Structural Pressure Policy

Structural-pressure evidence records the current state of structurally large, coupled, awkward, or intentionally deferred surfaces after implementation work.

Use these classifications:

- `resolved`: the hotspot pressure is materially improved or intentionally unchanged and no longer needs first-pass follow-up.
- `acceptable-for-now`: pressure remains, but the current boundary is coherent enough to defer without opening immediate work.
- `follow-up-candidate`: enough pressure remains that later planning should revisit it explicitly.

Markdown task summaries and milestone reconciliation are the source of truth. `.day-shift/state/structural-pressure.json`, when present, is derived current-state lookup data.

Task summaries should record task-local structural deltas when a task touches a hotspot or deliberately defers part of a refactor seam. Milestone reconciliation should dedupe repeated mentions and record the current-state verdict once.

## Structural Pressure Sync

`structural-pressure report` is read-only evidence. `structural-pressure sync` is the write surface for derived state.

`structural-pressure sync` belongs after completed milestone reconciliation and should update derived state only when the milestone evidence establishes a current-state transition. Do not update derived structural-pressure state during ordinary task execution, task summary authoring, planning artifact creation, or validation/review reporting.

Write derived state only when a file or family receives a first classification, materially changes classification, materially changes severity or summary, clears an active concern, or needs a family-level current-state update. Do not write derived state for every task touch or for duplicated rationale already preserved in Markdown artifacts.

When Markdown and derived JSON disagree, treat Markdown planning and review artifacts as the canonical evidence.

## Explicit Write Surfaces

The no-write boundary for validation and review does not mean the repository can never be updated. It means updates must happen through separately named write-capable surfaces or scoped artifact edits owned by the active lifecycle step.

Examples include:

- task, implementation-summary, reconciliation, milestone, phase, or metadata update commands when the command contract explicitly supports the requested field
- task execution edits inside declared implementation target paths
- implementation-summary closeout after task execution
- milestone reconciliation after every task summary is complete
- structural-pressure sync after completed milestone reconciliation

Keep these write surfaces separate from read-only review, validation, planning-navigation, and evidence-reporting surfaces.

## Related References

- Use `.day-shift/references/prompts-and-templates.md` for prompt-family, template-family, manifest, template-reference, and scaffold-destination boundaries.
- Use `.day-shift/references/commands.md` for command-family behavior once that reference home is completed.
- Use `.day-shift/references/metadata.md` for artifact-family metadata mutation boundaries once that reference home is completed.

## Canonical Sources

- `.day-shift/workflows/task.agent-lifecycle-guide.md`
- `.day-shift/workflows/milestone.agent-lifecycle-guide.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/prompts/user/implementation.next.md`
- `.day-shift/workflows/01-start-here.md`
