Skip to content
sdlc

T-2QXZ-start-task-handles-frontmatter-rebase-cleanly

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”

plugin/skills/task-work/start_task.py deterministically resolves the frontmatter conflict that arises when its chore(tasks): start commit on main meets the feat branch’s earlier docs(tasks): verify implementation-ready commit during rebase. Right now the rebase bails to a REBASE state, the operator manually merges three lines of YAML, and continues. Every conflict is the same shape (same file, same two fields). Cited by T-KG6Y-task-ensure-ready-flags-spec-placeholders.

Today

Section titled “Today”

When /sdlc:task-work Step 5b runs against a feat branch that already has the docs(tasks): verify <basename> implementation-ready commit (the normal case, since 5a always runs first), start_task.py applies its frontmatter edit on main (sets status: in-progress and today’s last_reviewed:), commits, then git rebase main inside the worktree. The feat branch’s verify commit and the new start commit both touch the same YAML frontmatter block, so the rebase surfaces a CONFLICT (content) and exits 3.

The operator (or a sub-agent driving task-work) then opens the file, sees the conflict markers, picks the union (today’s last_reviewed: from HEAD plus the newer readiness_verified_at: stamp from the feat commit), and continues the rebase. The merge is mechanical: HEAD wins for status: and last_reviewed:, the feat side wins for readiness_verified_at:.

Proposed

Section titled “Proposed”

start_task.py detects the expected conflict shape and resolves it in-script before exiting. Specifically:

  • If git rebase main fails with a conflict whose only conflicted file is the task .md file AND whose conflicting hunks are confined to the YAML frontmatter block AND the conflicting fields are a subset of {status, last_reviewed, readiness_verified_at, definition_gap}, the script applies the documented resolution (HEAD wins for status/last_reviewed, feat side wins for readiness_verified_at/definition_gap) and runs git rebase --continue.
  • Any other conflict shape (different file, different fields, non-frontmatter hunks) is still a hard error — the script exits 3 with the worktree in REBASE state for human inspection.

This keeps the auto-resolution narrow: it only handles the one conflict shape that’s structurally guaranteed by Step 5a then Step 5b touching the same lines.

Approach

Section titled “Approach”
  1. After git rebase main returns non-zero, parse git status --porcelain=v2 to extract the conflicted files. If it’s exactly the task file, proceed; otherwise bail with the current exit-3 behaviour.
  2. Read the conflicted file, parse the conflict markers, confirm they’re inside the YAML frontmatter block (between the two --- fences). If not, bail.
  3. Parse both sides as YAML, merge per the rule above (HEAD wins for status/last_reviewed; feat wins for readiness_verified_at/definition_gap), write the merged file.
  4. git add <task-file> then git -c core.editor=true rebase --continue. Verify the rebase completed; if not, bail.
  5. Add an eval case under plugin/skills/task-work/tests/ (or the existing test_start_task.py if present) covering the auto-resolve path.

Files to touch

Section titled “Files to touch”
LocationKindChange
plugin/skills/task-work/start_task.pymodifyadd the auto-resolve
plugin/skills/task-work/tests/modifyadd eval case (existing harness

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: A fresh /sdlc:task-work against a task whose feat branch carries only a docs(tasks): verify-shaped commit completes Step 5b without surfacing a conflict to the caller.
  • AC-2: An eval case constructs the conflict shape and asserts the script exits 0 with the rebased feat branch containing both the start commit and the verify commit, in that order.
  • AC-3: A conflict on any other file or any non-frontmatter hunk still exits 3 with REBASE state preserved.

Out of scope

Section titled “Out of scope”

  • General-purpose conflict resolution. This task only handles the one structurally-predictable shape.

  • Re-architecting how task state is stored. The broader question of whether frontmatter is the right state store at all (raised on PR

    #69 review) is captured separately at B-HUT2-rethink-frontmatter-as-task-state-store; revisit if this narrow fix doesn’t hold up in practice.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”

Spawned by /sdlc:task-work post-mortem of T-KG6Y-task-ensure-ready-flags-spec-placeholders on 2026-05-21.

Dedup search (spawn-from-post-mortem)

Section titled “Dedup search (spawn-from-post-mortem)”

Bullet: Step 5b start_task.py rebase surfaced a frontmatter merge conflict between the verify-stamp commit and the start-commit; conflict resolution is mechanical and could be auto-resolved by start_task.py Keywords searched: auto-resolved, verify-stamp, start-commit, frontmatter, start_task, resolution, mechanical, surfaced Excluded: 2026-05-21-task-work-step-6-inline-impl-fallback Top candidates (score / status / headline):

  • 35 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into scripts/start_task.py
  • 25 / closed/done / 2026-05-20-task-work-rebase-frontmatter-conflict — Avoid structural rebase conflict in /sdlc:task-work Step 5b
  • 24 / closed/done / 2026-05-19-templates-html-comment-after-frontmatter — Move template HTML comment block after frontmatter
  • 21 / closed/done / 2026-05-19-migrate-reorders-frontmatter-keys — Shared reorder_frontmatter_keys helper produces consistent key order across migrate paths
  • 21 / planning/draft / 2026-05-21-start-task-handles-frontmatter-rebase-cleanly — start_task.py auto-merges frontmatter on stamp/start rebase conflict Decision: LINKED-EXISTING Rationale: Script’s top-ranked candidates are all closed/done; the only open task in the candidate set is this very file, which is precisely the fix the bullet describes (auto-resolve the start_task.py rebase frontmatter conflict). Override script’s SPAWNED → LINKED-EXISTING; this task already covers the bullet. Linked to: 2026-05-21-start-task-handles-frontmatter-rebase-cleanly

Dedup search (spawn-from-post-mortem)

Section titled “Dedup search (spawn-from-post-mortem)”

Bullet: The Step 5b rebase hit a frontmatter conflict on first run — start_task.py wrote the verify commit’s new readiness_verified_at value into main’s start commit, which made the verify commit on the task branch effectively empty when replayed, surfacing as a context conflict (because main’s start also added a new last_reviewed line). Resolved by git rebase —skip. There is already a tracked task for this — T-2QXZ-start-task-handles-frontmatter-rebase-cleanly — so this PR’s friction confirms that task’s premise rather than introducing a new one. Keywords searched: start-task-handles-frontmatter-rebase-cleanly, readiness_verified_at, last_reviewed, frontmatter, effectively, introducing, start_task, surfacing Excluded: 2026-05-22-restructure-task-touchpoints-as-a-table-with-symbol-dir-glob Top candidates (score / status / headline):

  • 51 / closed/done / 2026-05-21-start-task-preserves-readiness-stamp — start_task.py should preserve readiness_verified_at across rebase
  • 47 / planning/draft / 2026-05-21-start-task-handles-frontmatter-rebase-cleanly — start_task.py auto-merges frontmatter on stamp/start rebase conflict
  • 31 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into scripts/start_task.py
  • 24 / closed/done / 2026-05-19-migrate-reorders-frontmatter-keys — Shared reorder_frontmatter_keys helper produces consistent key order across migrate paths
  • 23 / closed/done / 2026-05-19-templates-html-comment-after-frontmatter — Move template HTML comment block after frontmatter Decision: LINKED-EXISTING Rationale: Bullet contains an explicit wikilink to this very task. The originating task author explicitly identified this task as the tracking item. Override script’s SPAWNED → LINKED-EXISTING per the explicit author signal. Script’s top candidate (start-task-preserves-readiness-stamp) is closed/done; this task (rank #2, planning/draft) is the open follow-up the bullet references. Linked to: 2026-05-21-start-task-handles-frontmatter-rebase-cleanly

Dedup search (spawn-from-post-mortem)

Section titled “Dedup search (spawn-from-post-mortem)”

Bullet: start_task.py rebase conflict on the task file’s frontmatter is now confirmed as a recurring failure mode — happened on both the pr-check task last turn and this task. The conflict arises when ensure-ready’s verify-stamp commit and start-commit on main both touch the frontmatter near readiness_verified_at/last_reviewed and three-way merge can’t resolve cleanly. The fix should be in start_task.py itself: detect the verify-stamp commit on the task branch, see that its only delta is readiness_verified_at, and absorb the value into the start-commit’s frontmatter edit so the verify-stamp commit’s content is already present in the rebase target. Keywords searched: readiness_verified_at, last_reviewed, ensure-ready, verify-stamp, start-commit, frontmatter, start_task, confirmed Excluded: 2026-05-21-run-quality-checks-isolates-pre-existing-drift Top candidates (score / status / headline):

  • 70 / planning/draft / 2026-05-21-start-task-handles-frontmatter-rebase-cleanly — start_task.py auto-merges frontmatter on stamp/start rebase conflict
  • 69 / closed/done / 2026-05-21-start-task-preserves-readiness-stamp — start_task.py should preserve readiness_verified_at across rebase
  • 42 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into scripts/start_task.py
  • 40 / closed/done / 2026-05-20-task-work-rebase-frontmatter-conflict — Avoid structural rebase conflict in /sdlc:task-work Step 5b
  • 38 / closed/done / 2026-05-19-task-ensure-ready-accepts-in-progress — task-ensure-ready accepts in-progress when readiness_verified_at is set Decision: LINKED-EXISTING 2026-05-21-start-task-handles-frontmatter-rebase-cleanly Originating task: 2026-05-21-run-quality-checks-isolates-pre-existing-drift

Bullet: The define round-trip’s status churn (open/ready->needs-definition->open/ready) made start_task.py’s git rebase main conflict (exit 3), leaving the worktree in REBASE state for manual resolution — the define loop should restore a pickable status without tugging the status line across commits, or start_task.py should recognize/squash the known define-churn instead of surfacing a hand-resolve. Keywords searched: needs-definition-, define-churn, hand-resolve, round-trip, start_task, resolution, recognize, surfacing Excluded: 2026-05-23-establish-plugin-lib-convention Top candidates (score / status / headline):

  • 26 / closed/done / 2026-05-21-start-task-preserves-readiness-stamp — start_task.py should preserve readiness_verified_at across rebase
  • 25 / planning/draft / 2026-05-21-start-task-handles-frontmatter-rebase-cleanly — start_task.py auto-merges frontmatter on stamp/start rebase conflict
  • 18 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into scripts/start_task.py
  • 14 / planning/draft / 2026-05-23-start-task-drops-orphan-stashes — start_task.py detects pre-existing stashes referencing files absent on the rebase target and prompts to drop them
  • 11 / closed/done / 2026-05-19-consolidate-task-status-enum — Consolidate task status enum and migrate existing instances Decision: SPAWNED Rationale: Override script’s SPAWNED → LINKED-EXISTING. The script’s top candidate (start-task-preserves-readiness-stamp) is closed/done; this task (rank #2, planning/draft) is the open follow-up that already owns this exact failure mode — start_task.py’s git rebase main surfacing a frontmatter conflict (the status line moving across the verify-stamp and start commits) and bailing to REBASE state for hand-resolution. The define-churn described here is the same structural conflict this task auto-resolves. Two prior post-mortems linked their analogous bullets here for the same reason. Linked to: 2026-05-21-start-task-handles-frontmatter-rebase-cleanly Originating task: 2026-05-23-establish-plugin-lib-convention

Dedup search (spawn-from-post-mortem)

Section titled “Dedup search (spawn-from-post-mortem)”

Bullet: start_task.py’s rebase conflicted on the frontmatter even though its stamp-lift handles readiness_verified_at: — because the start-commit also adds last_reviewed: adjacent to it and the verify-stamp commit made before last_reviewed existed collides; the stamp-lift should also align last_reviewed: or the verify-stamp commit should carry it so the rebase is conflict-free. Keywords searched: readiness_verified_at, last_reviewed, conflict-free, start-commit, verify-stamp, frontmatter, start_task, conflicted Excluded: 2026-05-27-add-backlog-capture Top candidates (score / status / headline):

  • 113 / planning/draft / 2026-05-21-start-task-handles-frontmatter-rebase-cleanly — start_task.py auto-merges frontmatter on stamp/start rebase conflict
  • 59 / closed/done / 2026-05-21-start-task-preserves-readiness-stamp — start_task.py should preserve readiness_verified_at across rebase
  • 48 / closed/superseded / 2026-05-26-start-task-fails-loud-on-cache-miss — start_task.py exits non-zero and surfaces cache-miss on lease lookup
  • 41 / planning/draft / 2026-05-25-start-task-resolves-frontmatter-conflict — start_task.py auto-resolves frontmatter-only rebase conflicts
  • 38 / closed/done / 2026-05-19-extract-start-task-script — Extract task-work Step 5b into scripts/start_task.py Decision: LINKED-EXISTING 2026-05-21-start-task-handles-frontmatter-rebase-cleanly Originating task: 2026-05-27-add-backlog-capture

← Back to Tasks