0006 — Managed files carry a marker, the hash lives elsewhere
A comment survives every edit that matters. A version inside the file goes stale and becomes a confident lie.
Context
lq upgrade has to answer, per file: is this still the copy we shipped, or has
the owner changed it? Getting it wrong in one direction wastes a minute on an
unnecessary diff. Getting it wrong in the other destroys work with no undo.
Decision
A comment marker — @lq-managed core/action-client — identifies the file. The
hash lives in the manifest, not the comment, because a hash inside the file it
hashes cannot be right.
The rule the planner enforces is one line: a file may be replaced only if it is byte-identical to what we shipped. Everything else gets a diff and a decision left to its owner.
Drift is not an error. Editing your own code is the point of vendoring it (0005).
Rejected
A version in the marker. The obvious design writes
@lq-managed core/action-client v1.4.0. It goes stale the moment anyone edits
the file without touching the comment — and then it is a confident lie, worse
than absent.
Markers in .claude/. That would mean a machine-readable comment atop sixteen
files an agent reads as prose. That directory is managed by location instead,
which is a different mechanism for a different kind of file.
Consequences
An edited file keeps its recorded hash rather than having it dropped, because dropping it would make the next upgrade treat the owner's work as ours.
The manifest is generator-write-only. A hand-edited manifest describes a codebase that does not exist, which is worse than no manifest at all.
Absence is ambiguous and the manifest disambiguates it: a file that is gone with
a recorded hash was deleted by the owner and stays deleted; gone without one is
genuinely new and arrives. lq check claimed the first behaviour for months
before the planner actually did it — the fix came from dogfooding the upgrade on
our own site.
The known limit. A planner older than a rule cannot apply that rule, and
lq upgrade runs the CLI vendored in the project. Three separate bugs have come
from this shape. The upgrade now hands over to the new CLI when it replaces one,
and reports files an earlier planner already broke — but a rule invented after a
customer's scaffold cannot be applied retroactively to files already on disk.
0005 — The template is vendored, not a dependency
Three kinds of code, three upgrade policies. The interesting one is the middle: ours to improve, yours to edit.
0007 — Codemods emit text edits, never a reprinted AST
A two-line change buried in a nine-hundred-line reformat is a diff nobody can review, and a diff nobody can review is a diff nobody trusts.