Skip to content
sdlc

T-780G-task-ensure-ready-checks-shipped-claims

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

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

Goal

Section titled “Goal”

Task specs often contain factual claims about what’s “not yet shipped” / “still reserved” / “will land in a later PR” — claims that are accurate when the spec is authored but go stale by the time the task is picked up. The implementer catches the contradiction manually (or, worse, doesn’t, and the implementation drifts from reality). Surfaced during T-J1M3-sdlc-yaml-json-schema-and-validator: the spec said to document worktree_init: as x-reserved: true “until that consumer ships,” but the convention doc and a ready-and-deployed --key worktree_init executor invocation in /sdlc:task-work Step 4 made it clear the consumer had in fact shipped. The implementer caught it; ensure-ready did not.

Today

Section titled “Today”

/sdlc:task-ensure-ready’s contract (plugin/entities/task/implementation-ready.md) checks for missing/thin sections, frontmatter shortfalls, and the short list of disqualifiers (cited paths don’t exist, cited symbols absent, subjective ACs, placeholder text). It does NOT cross-check factual claims like “not yet shipped,” “reserved for a later PR,” or “this consumer doesn’t exist yet.” Those claims sit in the spec body and survive into implementation untouched.

Sibling work in the same neighbourhood:

This task is the same family, applied to a different shape of stale claim: “X has not yet shipped” (i.e. asserts an absence) where the absence is no longer true.

Proposed

Section titled “Proposed”

Extend ensure-ready’s disqualifier set with a heuristic check for common “not-yet-shipped” phrasings (“not yet implemented”, “still reserved”, “will land in”, “consumer hasn’t shipped”, “TBD until X ships”), and for each occurrence, grep the codebase for the referenced thing. If the thing now exists, flag it as a definition_gap (“spec claims X is not yet shipped but Y exists in plugin/foo.py”). False positives are acceptable — the goal is to nudge the human/agent to re-read the claim, not to auto-resolve.

Approach

Section titled “Approach”
  1. Catalogue the phrasings worth catching from the existing task corpus (likely a handful of patterns).
  2. Add a heuristic scanner to /sdlc:task-ensure-ready (or its co-located ensure_ready_mutate.py-style helper) that pulls the surrounding sentence for each match, attempts to extract the referenced symbol/path, and greps for it.
  3. On any hit, append a definition_gap: bullet to the failure report. Decide whether this is a hard fail or a soft warning — start with a soft warning (don’t downshift status) since false positives are likely.

Files to touch

Section titled “Files to touch”
LocationKindChange
plugin/skills/task-ensure-ready/SKILL.mdnewdescribe the new
plugin/entities/task/implementation-ready.mdmodifyextend the
plugin/skills/task-ensure-ready/ensure_ready_mutate.pymodify(or
plugin/skills/task-ensure-ready/tests/modifyfixtures covering a

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: ensure-ready run against a fixture spec containing “the --foo flag is not yet shipped” — when --foo exists in a cited CLI — surfaces a definition_gap: mentioning the contradiction.
  • AC-2: ensure-ready run against the same fixture with the contradicting code removed surfaces no gap.
  • AC-3: the check is documented in plugin/entities/task/implementation-ready.md under disqualifiers.

Out of scope

Section titled “Out of scope”
  • Auto-rewriting the spec. The check raises a flag; the human (or /sdlc:task-define) edits the body.
  • More general NLP. A short list of phrasings is sufficient; this is a nudge, not a contract.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”

Spawned by /sdlc:task-work post-mortem of T-J1M3-sdlc-yaml-json-schema-and-validator on 2026-05-21. The originating task’s “Approach Step 2” said to document worktree_init: as x-reserved: true “until that consumer ships,” but the executor’s --key worktree_init invocation already shipped in plugin/scripts/run_quality_checks.py (verified in the same run’s pre-flight) — the implementer caught the contradiction, but ensure-ready did not.

← Back to Tasks