T-U1GD-schema-bump-tasks-handle-missing-version

Status: closed/done · Impact: medium · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to ready before picking up.

Goal

Future schema-bump tasks must specify upfront how files that lack a schema_version field entirely (because they predate the field) get routed — through the transform chain, not the stamp path. The v1→v2 task in T-T5RB-consolidate-task-status-enum missed this case in its spec and the implementer caught it only mid-flight (commit c050d0b). Codifying the case in a checklist or template prevents the same gap on every future bump.

Today

“The task spec implicitly assumed every pre-v2 file had schema_version: 1 set. In practice, two pre-existing tasks in this repo had no schema_version field at all (they predated that field), and the original migrate flow’s stamp path would have stamped schema_version: \"2\" onto a v1-shaped file, leaving it invalid against the v2 schema. The sub-agent had to add a generalization (commit c050d0b): if a file is missing schema_version and a transform chain exists from v1, route it through the chain rather than the stamp path. Future schema bumps should specify this case upfront in the task spec rather than relying on implementer judgment.”

There is no schema-bump task template or checklist; the consolidate-status-enum task was hand-written and missed the “missing schema_version” branch.

Proposed

A cross-entity schema-bump checklist at plugin/conventions/schema-bump-checklist.md (per plugin/skills/CLAUDE.md’s “factor shared procedural prose into plugin/conventions/.md” rule). It enumerates the canonical questions every schema-bump task spec must answer. The /sdlc:entities-migrate skill cross-references the checklist; /sdlc:task-new optionally prompts when the task headline matches a schema-bump shape.

Rejected alternatives:

Per-entity plugin/entities/<type>/migrations/README.md — forces duplication across four entity types for the same checklist content.
Inline in plugin/skills/entities-migrate/SKILL.md — buries the checklist inside the runtime skill prose; harder to cross-reference from /sdlc:task-new.

Approach

Author plugin/conventions/schema-bump-checklist.md enumerating the five canonical questions:
- Missing schema_version: what does the migrate flow do for files that predate the field entirely?
- Current schema_version: files already at the target version — pass-through, no-op?
- Unknown legacy values: what error / route applies when schema_version is set but not in the known transform chain?
- Error path: how does the migrate flow surface failures (exit code, stdout shape)?
- Stamp behavior post-migrate: after the transform chain runs, is schema_version re-stamped at the top of the frontmatter, at the bottom, or by canonical-order helper?
Cross-reference the checklist from plugin/skills/entities-migrate/SKILL.md’s Notes section, per the convention-reference shape in plugin/skills/CLAUDE.md.
Optionally add a /sdlc:task-new prompt hint that fires when a new task’s headline matches /schema bump|schema-bump|migrate v\d+ to v\d+/i, surfacing the checklist’s five questions for the author to answer.

Files to touch

plugin/conventions/schema-bump-checklist.md (new) — canonical cross-entity schema-bump checklist.
plugin/skills/entities-migrate/SKILL.md — Notes section reference to the checklist (per CLAUDE.md convention shape).
plugin/skills/task-new/SKILL.md — optional prompt hint when the task headline matches the schema-bump shape.

Acceptance criteria

AC-1: plugin/conventions/schema-bump-checklist.md exists and lists exactly five canonical questions (missing field, current field, unknown field, error path, stamp behavior).
AC-2: plugin/skills/entities-migrate/SKILL.md Notes section contains a one-line reference to the checklist matching the shape documented in plugin/skills/CLAUDE.md (”- Schema bump checklist. See …” form).
AC-3: /sdlc:task-new (optionally — gated on this AC if the prompt-hint path is included) surfaces the five-question checklist when the headline matches the schema-bump pattern.

Out of scope

Authoring the next concrete schema bump. This task is purely about the spec template / checklist.

Dependencies

none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-T5RB-consolidate-task-status-enum on 2026-05-19.

Post-mortem

Captured by /sdlc:task-work on 2026-05-21. PR: pending.

Acceptance criteria coverage

AC-1: agent-manual — verified plugin/conventions/schema-bump-checklist.md exists with exactly five numbered canonical questions (missing field, current field, unknown legacy value, error path, post-migrate stamp behavior).
AC-2: agent-manual — verified the one-line bullet in plugin/skills/entities-migrate/SKILL.md Notes matches the "- **Schema bump checklist.** See ..." shape from plugin/skills/CLAUDE.md.
AC-3: agent-manual — added a parallel one-line bullet in plugin/skills/task-new/SKILL.md Notes referencing the same checklist with a headline-pattern trigger note. AC-3 was gated on the prompt-hint path being included; chose Notes-section reference (consistent with branch-naming bullet already there) rather than inline Step-6 logic, to avoid duplicating prose across SKILL.md files per plugin/skills/CLAUDE.md.

What worked

The cross-skill convention-reference shape ("- **<Topic>.** See ..." bullet) was already established in two prior conventions docs (branch-naming.md, commit-messages.md), so the new bullet slotted in mechanically.
Quality checks (6/6) passed first try with no fixups.

Friction and automation gaps

Step 5b’s rebase surfaced a frontmatter conflict because the readiness gate stamped a fresh readiness_verified_at: on the feat branch while the main-side start-commit kept the older stamp and updated last_reviewed:. Resolution was a one-line manual merge (take newer stamp + newer last_reviewed) but the conflict is structural — every task-work run that lands a Step 5a stamp refresh will hit it. The start-commit on main should either (a) preserve the existing readiness_verified_at: value verbatim (no refresh on main, only on the feat branch), or (b) the rebase resolution should be automated in Step 5b.6 since the merge is deterministic (always prefer the feat-branch stamp, always prefer the main-branch last_reviewed). → T-H0W9-task-work-rebase-frontmatter-conflict

Spawned follow-up tasks

T-H0W9-task-work-rebase-frontmatter-conflict — linked existing task that already proposes restructuring the verify-commit frontmatter layout to eliminate the structural conflict.

← Back to Tasks