T-6SNW-entities-migrate-reshapes-bulleted-sections

Status: closed/obsoleted · Impact: medium · Complexity: medium

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

Goal

The v3 task schema requires ## Today and ## Files to touch to be typed tables, but tasks authored under earlier schema versions carry these sections as prose bullet lists. When /sdlc:task-work picks up such a task, the table-only gate fails mid-flight and forces a /sdlc:task-define round-trip to reshape the sections by hand. This task teaches the mechanical-migration path (/sdlc:entities-migrate / audit_entities.py) to recognize and auto-convert bulleted Today / Files to touch into v3 tables, so pickup of a legacy-shaped task doesn’t hit the gate. Surfaced by T-75LX-establish-plugin-lib-convention.

Today

Location	Role today
`plugin/scripts/audit_entities.py`	Detects prose-section drift (e.g. a task missing the v3 table shape) but reports it as a drift finding; does not reshape bulleted sections into tables
`plugin/skills/entities-migrate/SKILL.md`	Applies mechanical, auto-fixable schema drift (today: stamping a missing `schema_version`); has no handler for reshaping bulleted Today/Files-to-touch into v3 tables
`plugin/skills/task-ensure-ready/`	Runs the table-only readiness gate at `/sdlc:task-work` pickup; fails when Today/Files-to-touch are still bulleted, sending the operator to `/sdlc:task-define`
`plugin/entities/task/schema.json`	Defines the v3 table requirement for `## Today` and `## Files to touch`

The reshape from bullets to a table is mechanical for the common case (a flat list of path — description bullets maps to | Location | … | rows), so it’s a candidate for the auto-fix path rather than a manual define round-trip. The originating post-mortem records the friction verbatim:

Task shipped in the legacy bulleted shape for ## Today / ## Files to touch, failing the v3 table-only gate and forcing a /sdlc:task-define round-trip mid-task-work — entity authoring/migration should convert bulleted Today/Files-to-touch to v3 tables (e.g. /sdlc:entities-migrate handling the reshape) so pickup doesn’t hit the gate.

Proposed

/sdlc:entities-migrate (via audit_entities.py’s auto_fixable classification) recognizes a bulleted ## Today or ## Files to touch section in a task that declares (or is being bumped to) schema v3 and rewrites it into the typed table shape. The reshape is conservative: it only fires when the bullet list maps unambiguously to table rows; anything it can’t reshape cleanly stays a drift finding for human handling, not a silent lossy conversion.

Approach

Define the recognizer: a ## Today / ## Files to touch section whose body is a bullet list (no Markdown table) under a v3 task. Decide the bullet → row mapping grammar — e.g. - \path` — descriptionbecomes| `path` | description |; for Files to touch, infer the Kind column (new/modify/delete`) from keywords or leave it for human fill if unparseable.
Implement the reshape as an auto_fixable transform in audit_entities.py (or a helper it calls), so /sdlc:entities-migrate picks it up alongside the existing schema_version stamping.
Guard the lossy cases: if a bullet doesn’t map cleanly to a row, emit the section as a non-auto-fixable drift finding and leave it untouched.
Add regression tests: a fixture task with bulleted Today/Files-to-touch migrates to clean v3 tables; a fixture with an unparseable bullet stays flagged-not-fixed.
Confirm /sdlc:task-work pickup of a reshaped task clears the table-only readiness gate without a /sdlc:task-define round-trip.

Files to touch

Location	Kind	Change
`plugin/scripts/audit_entities.py`	modify	Add a recognizer + reshape transform for bulleted Today/Files-to-touch under v3; classify the clean case as `auto_fixable`
`plugin/skills/entities-migrate/SKILL.md`	modify	Document that the migrate sweep now reshapes bulleted Today/Files-to-touch into v3 tables
`plugin/scripts/tests/test_audit_entities.py`	new	Regression fixtures: clean reshape migrates; unparseable bullet stays flagged

(Exact test path is a best guess; if audit_entities.py already has a co-located test suite, extend it rather than adding a new file.)

Acceptance criteria

AC-1: Running /sdlc:entities-migrate against a task whose ## Today is a flat - \path` — descriptionbullet list rewrites it into a valid v3| Location | Role today |` table.
AC-2: The same applies to a bulleted ## Files to touch, producing a | Location | Kind | Change | table.
AC-3: A bullet that cannot be mapped cleanly to a row is left untouched and reported as a non-auto-fixable drift finding (no lossy conversion).
AC-4: After the migrate sweep, /sdlc:task-work pickup of the reshaped task clears the table-only readiness gate without a /sdlc:task-define round-trip.
AC-5: Regression tests cover the clean-reshape and unparseable-bullet paths.

Out of scope

Reshaping any section other than ## Today and ## Files to touch. Those are the two the v3 schema requires as tables.
Inferring rich content the bullets never carried (e.g. fabricating a Kind value when no signal exists) — leave such cells for human fill or flag as non-auto-fixable.
Changing the v3 table grammar itself; this task migrates existing content into the established grammar.

Dependencies

none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-75LX-establish-plugin-lib-convention on 2026-05-23.

Dedup search (spawn-from-post-mortem)

Bullet: Task shipped in the legacy bulleted shape for ## Today / ## Files to touch, failing the v3 table-only gate and forcing a /sdlc:task-define round-trip mid-task-work — entity authoring/migration should convert bulleted Today/Files-to-touch to v3 tables (e.g. /sdlc:entities-migrate handling the reshape) so pickup doesn’t hit the gate. Keywords searched: entities-migrate, files-to-touch, mid-task-work, task-define, table-only, round-trip, authoring, migration Excluded: 2026-05-23-establish-plugin-lib-convention Top candidates (score / status / headline):

38 / 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
32 / closed/done / 2026-05-19-implement-entities-migrate — Implement /sdlc:entities-migrate to apply mechanical schema-drift fixes
29 / closed/done / 2026-05-19-consolidate-task-status-enum — Consolidate task status enum and migrate existing instances
26 / planning/needs-definition / 2026-05-23-archive-closed-tasks-in-subdirectory — Move closed tasks to docs/planning/tasks/archive/; default scans to active-only
18 / closed/done / 2026-05-19-co-locate-skill-specific-scripts — Co-locate skill-specific scripts under their skill dir; promote when shared Decision: SPAWNED

← Back to Tasks