T-52SQ-task-work-cleanup-on-fail-prose

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

AUTO-DEFINED: this spec was best-effort machine-authored by /sdlc:task-auto-define on 2026-08-03 because /sdlc:spawn-task-pr requested a readiness drive. Review the Goal, Approach, Today, Files-to-touch, and Acceptance-criteria carefully before trusting it.

Goal

Originating from T-HTN8-lease-gate-memo-fields in git@github.com:sksizer/dev.git: /sdlc:task-work Step 5a’s prose describes the readiness gate as being invoked “passing both --commit-on main and --cleanup-on-fail”, which reads as though both flags travel together on whichever invocation the gate makes. The underlying script rejects that pairing: ensure_ready_mutate.ts returns exit 2 with --cleanup-on-fail is only meaningful with --mode fail, so the flag rides the FAIL invocation only. The skill prose should say so, rather than leave an operator or agent reading Step 5a to construct an invocation the script refuses.

/sdlc:task-work Step 5a states the readiness gate is shelled with —commit-on main —cleanup-on-fail, but ensure_ready_mutate.ts exits 2 on —cleanup-on-fail when —mode pass — the flag is fail-path-only. The skill prose should say so rather than imply both flags travel together.

— T-HTN8-lease-gate-memo-fields

Today

Location	Role today
`apps/sdlc/skills/task-work/SKILL.md`	Step 5a instructs the operator to invoke `/sdlc:task-ensure-ready` “passing both `--commit-on main` and `--cleanup-on-fail`”, and repeats the joined form (“shells the mutator with `--commit-on main --cleanup-on-fail`”) without noting that the second flag applies only when the verdict is a fail.
`apps/sdlc/skills/task-ensure-ready/SKILL.md`	The `--cleanup-on-fail` contract section opens with “The two flags are paired”, while the same file’s Step 4 PASS example correctly shells `--mode pass --commit-on main` with no cleanup flag — the prose contradicts its own example.
`apps/sdlc/skills/task-ensure-ready/ensure_ready_mutate.ts#cleanupOnFail`	Argument validation returns exit 2 when `--cleanup-on-fail` is supplied with any mode other than `fail`, and again when it is supplied without `--commit` or `--commit-on`. This is the behavior the prose has to match.
`apps/sdlc/skills/task-ensure-ready/tests/ensure_ready.test.ts`	Pins the guard with the `cleanup-on-fail-rejects-on-pass` and `cleanup-on-fail-rejects-without-commit` cases, so the exit-2 behavior is settled and only the prose is wrong.

Proposed

/sdlc:task-work Step 5a describes the readiness gate the way the script actually behaves: --commit-on main is on both the pass and fail invocations, and --cleanup-on-fail is added only when the gate is writing a downshift. A reader of Step 5a can tell, without opening ensure_ready_mutate.ts, that combining --cleanup-on-fail with a passing verdict is an error and not a supported shape. /sdlc:task-ensure-ready’s matching contract section carries the same framing so the two skills no longer disagree.

Approach

Re-read the two guard clauses in apps/sdlc/skills/task-ensure-ready/ensure_ready_mutate.ts that return exit 2, to pin the exact scope in the rewritten prose: --cleanup-on-fail requires --mode fail, and it also requires one of --commit / --commit-on.
Rewrite the Step 5a paragraphs in apps/sdlc/skills/task-work/SKILL.md that currently say “passing both” and “shells the mutator with --commit-on main --cleanup-on-fail”. The replacement states that /sdlc:task-ensure-ready shells --commit-on main on whichever path it takes, and adds --cleanup-on-fail to the fail-mode shell only; keep the existing explanation of what the teardown does and the existing wikilink citations intact.
Reword the opening of the “When called by /sdlc:task-work — the --cleanup-on-fail contract” section in apps/sdlc/skills/task-ensure-ready/SKILL.md so “paired” becomes an explicit fail-path statement that agrees with Step 4’s PASS invocation example. Leave the numbered teardown list and the cleaned-up: marker description untouched.
Run the skill-prose gate (bun apps/sdlc/cli/sdlc.ts gate skill-prose) and the suite at apps/sdlc/skills/task-ensure-ready/tests/ensure_ready.test.ts under bun test, confirming no pinned prose invariant and no script behavior moved.

Files to touch

Location	Kind	Change
`apps/sdlc/skills/task-work/SKILL.md`	modify	Step 5a prose describes `--cleanup-on-fail` as fail-path-only and names the exit-2 rejection when it is combined with a passing verdict.
`apps/sdlc/skills/task-ensure-ready/SKILL.md`	modify	The `--cleanup-on-fail` contract section drops the “two flags are paired” framing in favor of a fail-path-only statement that matches Step 4’s PASS example.

Acceptance criteria

AC-1: apps/sdlc/skills/task-work/SKILL.md Step 5a states that --cleanup-on-fail rides the fail invocation only and that supplying it with --mode pass exits 2.
AC-2: grep -n "passing both" apps/sdlc/skills/task-work/SKILL.md returns no match.
AC-3: grep -n "The two flags are paired" apps/sdlc/skills/task-ensure-ready/SKILL.md returns no match.
AC-4: bun apps/sdlc/cli/sdlc.ts gate skill-prose exits 0.
AC-5: The suite at apps/sdlc/skills/task-ensure-ready/tests/ensure_ready.test.ts still passes under bun test, confirming the prose fix moved no script behavior.

Out of scope

Changing ensure_ready_mutate.ts behavior. The exit-2 guard is correct; this task moves prose to match it.
The --commit-on main ephemeral-worktree write path and its D-WK7T-agent-git-writes-worktree-isolated rationale.
The shape of the cleaned-up: worktree=... branch=... lease=... marker line and the teardown steps behind it.

Dependencies

none

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-08-03 UTC from T-HTN8-lease-gate-memo-fields in git@github.com:sksizer/dev.git.

← Back to Tasks