T-NF26-setup-runs-entities-migrate-after-schema-bump
Status: closed/done · Impact: medium · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
When a plugin upgrade bumps an entity’s schema_version, every
pre-existing instance under docs/planning/<plural>/ becomes drift —
but a consumer project only learns about it the next time
/sdlc:task-work picks up one of the affected tasks and stamps it
through entities-audit. By then a developer is mid-context-switch
into a different problem. /sdlc:setup already runs at plugin-install
/ upgrade time; it should call /sdlc:entities-audit (or invoke
/sdlc:entities-migrate directly when the auto-fixable bit is set) so
drift surfaces immediately after the upgrade, in the right cognitive
context. Cite T-S0PK-add-lease-protocol-library-and-schemas
for the live example: three slice-1 task files were stuck at v2 when
the task schema bumped to v3; the operator only found out at task-pickup time.
| Location | Role today |
|---|---|
plugin/skills/setup/SKILL.md | Sets up docs/planning/<plural>/ and sdlc.yaml; does NOT run an audit afterward. |
plugin/skills/entities-audit/SKILL.md | Surfaces drift but is invoked manually. |
plugin/skills/entities-migrate/SKILL.md | Applies auto-fixable drift but is invoked manually. |
plugin/skills/task-work/SKILL.md | The current first place drift surfaces — via the quality-check gate at Step 7, mid-task. |
Proposed
Section titled “Proposed”/sdlc:setup ends with an audit-and-offer-to-migrate step that runs
on every invocation (including re-runs after a plugin upgrade). On a
fresh project this is a no-op; on an upgraded project it surfaces drift
immediately and offers /sdlc:entities-migrate for auto-fixable cases.
Approach
Section titled “Approach”- Add a final step to the
/sdlc:setupskill that runs/sdlc:entities-auditnon-interactively. - If the audit reports auto-fixable drift, prompt the operator
(
AskUserQuestion) whether to run/sdlc:entities-migrateinline. - Document the new flow in
plugin/skills/setup/SKILL.md.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/skills/setup/SKILL.md | modify | Add the audit-and-offer-migrate step at the end of the procedure. |
docs/skills/setup.md | modify | Regen / refresh to reflect the new step in the Mermaid flow. |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: A fresh
/sdlc:setuprun on a project with at least one entity file at an outdatedschema_versionreports the drift before exiting. - AC-2: When the drift is auto-fixable,
/sdlc:setupoffers to run/sdlc:entities-migrateand, if accepted, the migrate skill handles the fix without a second manual invocation. - AC-3: A fresh
/sdlc:setuprun on a clean project (no drift) exits silently with no extra prompts beyond the audit’s clean signal.
Out of scope
Section titled “Out of scope”- Wiring drift into a CI gate. That’s a separate concern; this task is about catching drift at upgrade time in the developer’s local loop.
- Making
entities-migratenon-interactive when invoked fromsetup. Status-quo prompt behavior is fine for v1.
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-S0PK-add-lease-protocol-library-and-schemas on 2026-05-23.
Dedup search (spawn-from-post-mortem)
Section titled “Dedup search (spawn-from-post-mortem)”Bullet: Pre-existing schema_version drift on slice-1 task files. When a schema_version bumps, /sdlc:entities-migrate could be wired into /sdlc:setup or CI so drift surfaces sooner than at task-pickup time. Keywords searched: entities-migrate, schema_version, pre-existing, task-pickup, surfaces, slice-1, sooner, drift Excluded: 2026-05-23-add-lease-protocol-library-and-schemas Top candidates (score / status / headline):
- 77 / closed/done / 2026-05-21-run-quality-checks-isolates-pre-existing-drift — run_quality_checks.py only fails on drift the current branch introduced
- 72 / closed/done / 2026-05-19-implement-entities-migrate — Implement /sdlc:entities-migrate to apply mechanical schema-drift fixes
- 57 / planning/draft / 2026-05-21-audit-entities-baseline-allow — audit_entities.py: distinguish pre-existing drift from PR-introduced drift
- 44 / closed/done / 2026-05-19-consolidate-task-status-enum — Consolidate task status enum and migrate existing instances
- 43 / closed/done / 2026-05-22-restructure-task-touchpoints-as-a-table-with-symbol-dir-glob — Restructure task touchpoints as a table with symbol/dir/glob citation grammar Decision: SPAWNED