Running the CLI migrates .taskless/ as a side effect, which lands in unrelated commits

[thecodedrift]

What happens

Running any command that loads the rule layout (taskless check is the one that caught this) migrates .taskless/ on disk as a side effect, rewriting tracked files. Observed while running pnpm cli check to verify an unrelated change:

M  .taskless/.gitignore
A  .taskless/rules/runtime/.gitkeep
A  .taskless/rules/sg/no-eval/.tests/.gitkeep
R  .taskless/rules/no-eval.yml -> .taskless/rules/sg/no-eval/no-eval.yml
A  .taskless/rules/vale/.gitkeep
D  .taskless/sgconfig.yml
M  .taskless/taskless.json

The migration itself is correct and intended. The surprise is that a read-shaped verb performs it, and that it lands in git status as a tracked-file change the caller did not ask for.

Why it matters here specifically

This repository dogfoods its own CLI, so pnpm cli check is now a step in validate.yml and is run by hand constantly while developing. Two concrete ways it bites:

1. It silently joins whatever commit you are making. A git add -A after a verification run stages a layout migration alongside an unrelated change. I caught this on a branch for A GitHub remote should not be a precondition for Taskless #179; without the check it would have shipped a .taskless/ migration inside an error-code commit.
2. Two branches that both run it produce the same migration independently, so the identical generated layout arrives twice and conflicts on merge. The migration is already carried by feat: enforce the house-style rules on main, including the agent recipes #187; any branch that runs check before that lands reproduces it.

Neither is a bug in the migration. Both come from a verb that reads producing a diff that writes.

Ask

A note in CLAUDE.md so an agent working in this repository expects it, roughly:

Running the CLI can modify tracked files. pnpm cli check (and anything else that loads the rule layout) runs the .taskless/ layout migration as a side effect. Check git status after running it, and do not git add -A a verification run without looking. The migration is legitimate; it just should not ride along in an unrelated commit.

Worth considering separately, and not proposed here: whether a read-shaped verb should migrate at all, or whether the migration belongs behind an explicit command with the read paths reporting "this layout is out of date, run X" instead. That is a larger behavioural question than the documentation note.

Notes

Found while implementing #179. Not a blocker for it; the migration was reverted before committing.

[thecodedrift]

Worse than a dirty git status: it can fail the test suite.

While verifying review fixes on #190, a pnpm test run failed 6 tests with no relation to the change:

FAIL  test/anonymous-flag.test.ts > local authoring needs no GitHub remote > an origin that is not GitHub > verify runs to completion
FAIL  test/check.test.ts > check > positional path arguments > zero paths keeps full-project scan behavior

The cause was this issue. An earlier pnpm cli check had migrated .taskless/ and the suite ran against the half-migrated rule layout. Two subsequent runs with the tree reverted were green at 929/929.

So the failure mode is not only "a migration rides along in an unrelated commit". It is also a suite that fails for reasons unconnected to the change under test, which is the expensive kind of confusing: the natural response is to go looking in the diff, and the diff is innocent.

This has now happened three times in one session, twice as a stray diff and once as a red suite.

It also strengthens the case for the second half of the original ask. A note in CLAUDE.md tells an agent to expect the stray diff; it does not help someone staring at six unrelated failures. Making the read paths report "this layout is out of date, run X" rather than migrating in place would remove the failure mode instead of documenting it.

[thecodedrift]

Consolidated into #178, which frames the same problem from the machine-interface side and already argues correctly that the migration must stay. The evidence from here — unrelated commits, a red test suite, cross-branch duplication — is carried over there, and the chosen fix is a migrated field on the --json envelope rather than a documentation note.

Closing as a duplicate rather than as won't-fix: the problem is real and is being solved on #178.