The .taskless/ migration is invisible to the machine interface

[thecodedrift]

Running check, verify, or test against a .taskless/ tree from an older schema migrates it: files move, taskless.json and .gitignore are rewritten. Measured on a pristine copy of this repo's own tree (schema version 2 → 5), that is six tracked files changed.

This is not a request to stop migrating. check and verify require a specific layout to function at all, so for anyone pinned to * or @latest the alternatives are an automatic migration or a hard failure on every run, and the failure is plainly worse. Migration is a precondition, not a side effect.

The problem is that nothing the caller can read says it happened.

What the caller actually gets

Surface	Migration signal
Human stderr	one line: Migrating to latest .taskless/ schema...
Human stdout	nothing
--json stdout	nothing — the envelope has no migration field
Exit code	unchanged

So the machine interface is silent. A CI script reading {"success":true,"results":[]} has no way to learn that the working tree was rewritten underneath it, and a person looking at six changed tracked files afterwards has nothing connecting them to the command they ran — the notice names no file, no source version, and no target version.

Two things that are already fine — please don't re-investigate

Both were suspected and neither reproduced on 0.10.2:

• CI=1 does not suppress the notice. It prints in both environments.
• --json stdout is valid JSON. The notice goes to stderr, correctly, so JSON.parse(stdout) is safe. (Banner noise seen through pnpm cli comes from pnpm, not from the CLI.)

The gap is not that the notice is misrouted. It is that stderr is the only place it exists.

Suggested shape

• Add a migration record to the JSON envelope — at minimum from and to schema versions, ideally the paths that moved. A consumer can then log it, fail on it, or ignore it deliberately.
• Have the human notice name what changed, or how many files, rather than announcing only that something did.

Open question: does test need this?

test migrates, but it may be inheriting rather than requiring it. The call chain is ensureTasklessDirectory → runMigrations, reached from commands/check.ts, commands/verify.ts, commands/init.ts, commands/onboard.ts, and rules/verify.ts:497 — the last of which is how test picks it up, since test runs verify first.

Unlike a whole-project check, test is handed an explicit rule directory. Whether it needs the entire tree at the current schema, or only the path it was given, is worth establishing before this is designed — it may be that test can operate on an old-layout tree for a path that is already well-formed.

Measured command-by-command, for reference:

command	migrates
info	no
detect	no
verify	yes
test	yes
check	yes

[thecodedrift]

Consolidating #188 into this issue, and recording the chosen approach.

#188 was filed from the other direction — the migration lands in unrelated commits — but it is the same underlying problem this issue already frames correctly: the migration is a precondition, not a side effect, and the fault is that nothing readable says it happened. No need for two threads.

Decision: add a migrated field to the --json envelope. Not a documentation note, and not moving migration behind an explicit command. This issue already argues why a hard failure is worse than an automatic migration, and that argument stands.

The field should carry what the current notice omits: the source and target schema versions, and the files touched. That is what turns an unexplained diff into an explained one.

Evidence carried over from #188

The silence costs more than a stray diff:

It lands in unrelated commits. A git add -A after a verification run stages a layout migration alongside whatever you were actually doing. Caught on the #179 branch before it shipped inside an error-code commit.

It can fail the test suite for unrelated reasons. During #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

An earlier pnpm cli check had migrated .taskless/ and the suite ran against the half-migrated layout. Two subsequent runs with the tree reverted were green at 929/929. That is the expensive kind of confusing: the natural response is to search the diff, and the diff is innocent.

It reproduces across branches. Two branches that both run check produce the same migration independently, so the identical generated layout arrives twice and conflicts on merge.

Three occurrences in one session: twice as a stray diff, once as a red suite.

Why the machine-readable field is the right fix for all of it

A CLAUDE.md note tells an agent to expect a stray diff. It does nothing for someone staring at six unrelated test failures, and nothing for a CI script that cannot see the tree was rewritten. The field addresses the case the note cannot reach, which is why it beats documenting the trap.

This repository is now the loudest consumer of that gap, since #187 makes pnpm cli check a blocking step in Validate and it is run constantly by hand.