T-JZ07-task-new-commits-task-file

Status: planning/backlog · Impact: medium · Complexity: small

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

Goal

/sdlc:task-new delegates file creation to sdlc task create, which writes docs/planning/tasks/<basename>.md but does not stage or commit it. /sdlc:task-work treats origin/main’s copy of the task file as the source of truth: start_task.ts reads it via git show origin/main:<taskRel> and lands the start-commit through an ephemeral worktree off origin/main. A freshly scaffolded, uncommitted file is therefore absent where task-work looks for it, and the user must detour through a manual git add + git commit (landed on origin/main) before retrying. Close the gap so the canonical task-new → task-work flow works end to end.

Today

Location	Role today
`apps/sdlc/lib/model/entities/task/ops/create.ts`	`sdlc task create` op — writes the task file; does not stage or commit it
`apps/sdlc/skills/task-new/SKILL.md`	Delegates creation to `sdlc task create`; never tells the user to commit the file
`apps/sdlc/skills/task-work/start_task.ts`	Sources the task file from origin/main; when absent, fails fast with `task file not found on origin/main: <taskRel>` — but the error does not name the remediation command

The fail-fast already removes the worst failure mode (a silently broken worktree state); what remains is that nothing in the flow commits the file and the error leaves the user to work out the git add + git commit detour themselves — the detour the originating post-mortem session hit.

Proposed

Two complementary fixes (probably both, layered):

sdlc task create optionally commits the file it writes with a deterministic message like docs(tasks): scaffold <basename>. The behavior lands as a flag/option on the op (or a task-work step), so every caller — the task-new skill included — gets it.
The start_task.ts fail-fast error names the exact remediation: the commands that land the file on origin/main, rather than only stating the file is missing.

The named-remediation fail-fast is the floor: it adds no hidden commits and surfaces the contract break immediately. The optional commit on task create is what makes task-new → task-work a fully canonical handoff.

Approach

Decide whether sdlc task create commits by default, on a flag (--commit), or never. Default-on is friendliest; default-off preserves scaffold-without-committing as a useful mode for in-progress drafting. Note: task-work reads origin/main, so a local commit alone doesn’t satisfy it — decide whether the op also pushes or the remaining gap stays with the user.
If committing: extend apps/sdlc/lib/model/entities/task/ops/create.ts to git add the new file and commit on the current branch with the deterministic message.
In apps/sdlc/skills/task-work/start_task.ts, extend the existing task file not found on origin/main error to name the exact remediation, e.g. git add docs/planning/tasks/<basename>.md followed by git commit -m "docs(tasks): scaffold <basename>" and a push to main.
Extend apps/sdlc/skills/task-work/tests/start_task.test.ts with a fixture where the task file is absent from origin/main, asserting the error text carries the remediation.
Update /sdlc:task-new’s SKILL.md and /sdlc:task-work’s SKILL.md to reflect whichever resolution ships.

Files to touch

Location	Kind	Change
`apps/sdlc/lib/model/entities/task/ops/create.ts`	modify	optional `git add` + commit of the file it writes
`apps/sdlc/skills/task-new/SKILL.md`	modify	document the commit option and when to use it
`apps/sdlc/skills/task-work/start_task.ts`	modify	fail-fast error names the exact remediation commands
`apps/sdlc/skills/task-work/SKILL.md`	modify	prose reflects whichever resolution ships
`apps/sdlc/skills/task-work/tests/start_task.test.ts`	modify	fixture: task file absent from origin/main; assert error text

Acceptance criteria

AC-1: /sdlc:task-new <slug> followed immediately by /sdlc:task-work <basename> runs end-to-end with no manual git add or git commit of the task file.
AC-2: If the scaffold commit is deferred (default-off, or flag not passed), task-work either commits the file as a precondition with a deterministic message OR fails fast with an error that names the exact commands to land the file on origin/main.
AC-3: apps/sdlc/skills/task-work/tests/start_task.test.ts carries a fixture covering a task file absent from origin/main at start, and the suite passes.

Out of scope

Changing how task create chooses the id or slug shape.
Changing how task-work handles task files that exist on origin/main but have uncommitted edits in the checkout (different failure mode).

Dependencies

none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-G834-move-plugin-runtime-state-to-sdlc-dir on 2026-05-22.

Dedup search (spawn-from-post-mortem)

Bullet (condensed): task-new creates the task file but does not commit it; task-work assumes it is already tracked, so a fresh file forces an out-of-band git add + git commit detour. Keywords searched: freshly-created, ensure-ready, precondition, out-of-band, start_task, optionally, task-work, untracked Excluded: 2026-05-22-move-plugin-runtime-state-to-sdlc-dir Top candidates (score / status / headline):

56 / closed/done / 2026-05-20-task-work-sub-agent-verdict-contract-clarity — Tighten task-work sub-agent verdict contract so ensure-ready’s READY marker isn’t mistaken for task-work’s final verdict
47 / closed/done / 2026-05-19-task-ensure-ready-accepts-in-progress — task-ensure-ready accepts in-progress when readiness_verified_at is set
46 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into a standalone script
42 / closed/done / 2026-05-19-resolve-ensure-ready-in-progress-contract — Resolve task-ensure-ready contract conflict with task-work in-progress flip
35 / closed/done / 2026-05-19-task-work-uses-per-project-quality-checks — Make /sdlc:task-work quality-check commands per-project configurable Decision: SPAWNED

← Back to Tasks