v1.36.1 ·
The file was there the whole time
The problem
The release blog has a guard that checks every backticked path in a post names a file that really exists. It was added after two releases went public linking to files that had been deleted, and it is worth keeping.
But it compared the whole backticked token against the list of tracked files. It stripped a
trailing slash, so a directory worked. Nothing stripped a trailing line number. So a citation like
packages/cli/src/compile/adapters/cursor.ts:86 was looked up as a file literally named
cursor.ts:86, missed, and failed the release as a dangling path. The file was there the whole
time.
Citing code by line is how this project's ideation and requirements documents point at evidence, so this was not an edge case. It blocked v1.17.0, v1.20.0 and v1.36.0. Each time the fix was the same: hand-write an override that reworded the citation so the guard would stop seeing it. Across the three sources that forced those overrides, the guard rejected six paths. All six were tracked files.
The item that recorded this was filed after the first occurrence with the recommendation "do later", because the workaround was cheap. It was cheap once. Paid on every release that cites code by line, it was not.
How it could be solved
Three decisions, each about how far to loosen a check that exists for a good reason.
The first was where to strip the line number. The guard does two things with a backticked token: it decides whether the token looks like a path into this repository at all, and if so, it checks that the path exists. Stripping the suffix before the first step would have been simpler to write and would have quietly changed which tokens count as paths. That rule was built from measured false positives, one exclusion at a time, and the item said to leave it alone. So the suffix comes off in exactly one place, the existence lookup, and nowhere else. When the guard does reject a path, it still reports the token exactly as written, line number included, so it can be found in the source.
The second was which suffixes to accept. It is tempting to accept anything after a colon. That would have made the guard pass a typo it should catch. Instead the shapes were counted across every document in the project's state and roadmap: a single line appears 329 times, a range 262, and comma lists of either a handful. Those are accepted. A colon followed by letters, a bare colon, a range with no end, and GitHub-style anchors are not, and tests assert each of them still fails. None of them occur in the corpus. When one does, it can be added with evidence.
The third was what to do with the three overrides the defect had forced. The one from v1.36.0 differed from its source only in rewording the rejected citation, so it was deleted, and that entry now builds from the original document. The two older ones were full prose rewrites. Posts here are written once and then owned, so deleting those would change nothing anyone can read and would only make a forced rebuild disagree with what was published. They stay. A test proves all three sources now pass the guard on their own, which was the point of deleting any of them.
How AIDLC solves it
A source document can now cite a real file by line number and the release blog generator
publishes it. Before this, the content guard read cursor.ts:86 as a file literally named with
the :86, failed to find it, and stopped the release as a dangling path. It did that at v1.17.0,
v1.20.0 and v1.36.0, and each time the way through was a hand-written override that reworded the
citation.
The guard now removes a trailing line reference before it checks that a path exists. It accepts a single line, a range, and comma lists of either, which are the only shapes that occur in the project's own documents. It does not accept anything else after a colon, so a typo still fails. A citation of a file that is not tracked still fails too, and the failure still names the token as written, line number included. Which tokens count as paths at all is unchanged.
The proof is on the real content. The three documents that forced overrides are guarded as extracted, with no override, in a test. Against the old guard those three produced six rejections, every one a file that was tracked. Against the new guard they produce none. The v1.36.0 override, which existed only to reword one citation, is deleted, and that entry now builds from its source.
This release's own problem act cites the guard's source by line number, and it generated without an override.
Nothing changes for a project that installs the CLI. The guard lives in the website package, which is not published.