T-G39V-validate-task-body-shape-at-commit-time

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

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

Goal

A planning-session author writing a task file directly via the Write tool — without going through /sdlc:task-new — does not see the canonical body shapes that template.md and implementation-ready.md enforce. They reasonably guess - **AC-N:** bullets and a bulleted ## Files to touch, then learn three iterations later (at /sdlc:task-ensure-ready pickup time) that the contract requires - [ ] AC-N: checkboxes and a typed | Location | Kind | Change | table. The validator should surface these requirements at commit time so the author fixes them once, immediately, in the right context. Cite T-S0PK-add-lease-protocol-library-and-schemas for the three-iteration example.

Today

Location	Role today
plugin/validators/validate_frontmatter.py	Validates frontmatter only. Body shape is unchecked.
plugin/entities/task/implementation-ready.md	Documents the canonical AC-checklist + Files-to-touch table shape — but is read only at /sdlc:task-ensure-ready time.
plugin/entities/task/template.md	Shows the canonical shape — but only consulted by /sdlc:task-new. Authors using Write directly never see it.
plugin/skills/task-ensure-ready/SKILL.md	The current first place drift surfaces — late, after the task has been written and committed.

Proposed

A plugin/validators/validate_task.py (or an extension to validate_frontmatter.py that gains a --body-shape flag) that rejects two specific drift patterns on tasks:

• ## Acceptance criteria containing - **AC- or any non-- [ ] AC bullet.
• ## Files to touch rendered as a bulleted list rather than a markdown table with the Location | Kind | Change columns.

Error messages cite plugin/entities/task/implementation-ready.md and show the canonical shape inline so the author can fix without context-switching. The validator runs as part of the per-project quality-check gate so drift surfaces on the same git commit that introduces it.

Approach

1. Add the body-shape checks as functions in a new plugin/validators/validate_task.py (or as helpers inside the existing validator if it’s already a natural fit).
2. Wire the new validator into the default quality_checks list seeded by /sdlc:setup so it runs at every Step 7 quality-check gate.
3. Write a small fixture set: a passing task, a bulleted-AC task, a bulleted-Files-to-touch task; assert the validator’s exit code on each.
4. Update plugin/skills/task-define/SKILL.md and plugin/skills/task-new/SKILL.md to note that the validator catches body-shape drift, so authors know what to expect.

Files to touch

Location	Kind	Change
plugin/validators/validate_task.py	new	Add body-shape checks (AC checklist, Files-to-touch table).
plugin/validators/tests/test_validate_task.py	new	Fixture-based pass/fail assertions for the new checks.
plugin/skills/setup/SKILL.md	modify	Seed validate_task.py into the default quality_checks list.
plugin/skills/task-define/SKILL.md	modify	Note that the validator catches body-shape drift at commit time.

Acceptance criteria

• AC-1: validate_task.py rejects a task whose ## Acceptance criteria section uses - **AC-1:** bullets and prints an error citing implementation-ready.md and the canonical - [ ] AC-1: shape.
• AC-2: validate_task.py rejects a task whose ## Files to touch section is a bulleted list and prints an error showing the canonical | Location | Kind | Change | table shape.
• AC-3: validate_task.py passes on every task file in docs/planning/tasks/ that currently has readiness_verified_at set (i.e. the validator’s error budget against the existing canonical corpus is zero).
• AC-4: Running /sdlc:setup on a fresh project seeds the new validator into sdlc.yaml’s quality_checks list so it runs at Step 7 of every /sdlc:task-work invocation.

Out of scope

• Auto-fixing the drift. The validator only reports; the author edits.
• Validating sections beyond ## Acceptance criteria and ## Files to touch. Other section shapes (Goal, Today, Proposed) are prose by design.

Dependencies

• none

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)

Bullet: AC checklist format and Files-to-touch table format weren’t surfaced at task-authoring time. Planning-session author writing task files directly via Write tool doesn’t see canonical formats in template.md and implementation-ready.md. Steer authoring through /sdlc:task-new or add stricter validate_task.py catching body-shape drift at commit-time. Keywords searched: implementation-ready, planning-session, files-to-touch, task-authoring, validate_task, commit-time, body-shape, checklist Excluded: 2026-05-23-add-lease-protocol-library-and-schemas Top candidates (score / status / headline):

• 21 / closed/done / 2026-05-19-schema-bump-tasks-handle-missing-version — Schema-bump task template enumerates the missing-schema_version case explicitly
• 14 / 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
• 10 / planning/draft / 2026-05-23-entities-migrate-reshapes-bulleted-sections — entities-migrate reshapes bulleted Today/Files-to-touch into v3 tables
• 9 / closed/done / 2026-05-19-clarify-out-of-scope-requirement — implementation-ready contract disambiguates whether Out of scope is required or conditional
• 7 / closed/superseded / 2026-05-19-task-work-defers-status-flip-until-ensure-ready — Defer task-work status flip until /sdlc:task-ensure-ready passes Decision: SPAWNED

---

← Back to Tasks