Skip to content

v1.58.0 ·

Undoing a task no longer means guessing its commits

The problem

Nothing ties a commit to the task it implements. Undoing one task means reading git log and guessing which commits were its. aidlc amend reopens a phase's documents; nothing rolls back its code.

How it could be solved

Three choices, each about undoing exactly what was asked and nothing more. The first was how a commit says which task it belongs to. A few older commits already named their task in the subject line, but matching words in a subject would also catch a commit that mentions the task for some other reason. So each commit now ends with a labelled line naming the piece of work and the task, a form git already knows how to read. That gives something up. Older commits carry no such line and stay out of reach, and an agent that forgets the line leaves commits the command cannot find. When that happens, it finds nothing and says which line it looked for.

The second was how to undo. Every selected commit is undone together in one new commit, not one undo per commit, so the task goes as a unit and a wrong undo is one thing to take back. If any part clashes with later work, the whole attempt is dropped and the branch is left as it was. So a task whose lines a later task rewrote cannot be undone alone; the developer undoes the later task first, or does it by hand. A commit that names two tasks is not refused. The plan marks it as shared and both tasks are reopened, so no checkbox claims work that is gone.

The third was what the undo may touch besides code. A task's commit often ticks its own box and updates the framework's records of the work as well. Letting git rewind those would roll back the lifecycle by accident, so they are put back as they were and only the named boxes are unticked. For the same reason the command works only while the code is still being written. Once testing has passed over it, undoing code would leave a finished test phase describing code that is no longer there, and reopening a closed phase is a different command's job.

How AIDLC solves it

aidlc revert <instance> --task T<n>. Finds the commits on the current branch since it left main whose Task: <instance>/T<n> trailer names the task, prints them newest first with the tasks each names, marks any commit shared with another task, and asks before changing anything. On a yes it adds one commit that undoes them, with git's This reverts commit <sha>. line for each, and flips each affected task's [x] in tasks.md back to [ ]. Nothing else under .aidlc/state/ changes.

--phase implementation selects every commit tagged with any of the instance's tasks. Other phases are refused with a pointer to aidlc amend. --dry-run only prints the plan; without a terminal the command needs --yes; --override stands in for a missing claim.

It refuses, changing nothing, on main, without a main, with uncommitted tracked changes, outside the implementation phase, without a live claim, for an unknown task id or an unsafe name, on a selected merge commit, and when the undo conflicts with later work. A clash only inside .aidlc/state/ (the next task's checkbox) is not a conflict — the fix testing found.

Commits name their task. The implementation skill's step 7 now tells the agent to end each task commit with a Task: <instance>/T<n> trailer and names aidlc revert as the way to undo a task. Nothing enforces the trailer.

Changes

  • packages/cli/src/revert/ (new): trailers.ts, commits.ts, plan.ts, apply.ts; packages/cli/src/tasks/reset.ts (new); packages/cli/src/commands/revert.ts (new).
  • packages/cli/src/cli.ts (registration), packages/cli/src/menu/roster.ts (menu exclusion with a reason).
  • packages/content/skills/40-implementation.md step 7, and its emitted copies .aidlc/skills/aidlc-implementation.md, .agents/skills/aidlc-implementation/SKILL.md.
  • packages/content/docs/lifecycle.md (the revert section), packages/content/docs/index.yaml (revert mapped to lifecycle).
  • packages/website/src/data/cli-reference.json (generated), and the command-count pins in packages/cli/test/cli-entrypoint.test.ts and packages/website/src/test/cli-reference.test.ts.
  • Tests: six new revert-*.test.ts files and test/helpers/git-repo.ts under packages/cli/.
  • .aidlc/knowledge/: module revert-module, decisions revert-task-trailer, revert-restores-state.
  • Spec delta in requirements.md: ADDED revert: Undo a task's commits by task id, ADDED revert: Commits name their task in a trailer. aidlc spec fold revert-by-task --dry-run is clean; it folds at completion.

No deferred tasks (tasks.md: T1–T7 done).