v1.10.6 ·
The guidance that never arrived: three mechanisms that reported success and delivered nothing
Every AIDLC phase skill ends with a Guidance section, and for seventeen days that section was a lie. Where an agent should have found the project's security rules, it found the literal text {{guidance:secure-defaults}}, a fill-in-the-blank marker nothing ever filled. The implementation skill went further and listed "guidance layer rules have been applied" as a completion criterion. No rule had been applied. None had been delivered.
The code to substitute those markers had existed since the first commit, with passing unit tests and no caller anywhere in production. Separately, nothing ever copied the guidance files from the package into a project. The framework shipped three rule files, referenced them from seven skills, and delivered them zero times.
It survived because every signal pointed the right way. Unit tests were green. The platform adapters printed a tidy list of guidance paths into CLAUDE.md. And grepping the emitted skill files for a leftover {{ found nothing, a false clean: those files are 431-byte stubs saying "read the canonical copy", and the markers sat in the canonical copy. A review note against an earlier instance had already recorded the defect and moved on.
What changed
aidlc init now creates .aidlc/guidance/ and installs the bundled layers. aidlc update and aidlc doctor install missing ones into older projects, so there is no command to remember. Layers you edited are never overwritten, and existing index.yaml entries are kept, including the lessons layer.
A rule decides how each placeholder resolves. At or under 2048 bytes the content is inlined. Above that, the skill gets one visible line: read this repo-relative path and apply it. In practice every guidance layer is referenced and every context document is inlined.
I did not inline everything. The three layers run roughly 3.5, 3.8 and 5.1 kilobytes, and the implementation skill points at all three. That would have grown a 4.5-kilobyte skill past 16 and repeated most of it across seven skills. It would also hide edits until regeneration. Pointing by path was already how the adapters worked.
Two smaller choices. The pointer is prose, not an HTML comment, because an agent reads the body as instructions and a comment is not one. And the path is relative, because this release also fixes a bug caused by absolute paths baked into generated files.
aidlc update rewrites the generated skill files in every existing project. In this repo it touched 13 files. Anything that grepped a skill for guidance text will now find a path.
Two more of the same shape
Cost-capture hooks bake in absolute paths to node and the CLI. A new machine or a runtime upgrade breaks them, and nothing says so. One real project's hooks named a home directory and node version that had been gone four days. The check already existed but had no caller outside a status command. Detection now runs on its own, and stays report-only, because repair rewrites project config and belongs behind an explicit install command.
And reports printed $0.00 for a project with no cost data, from a sum over an empty ledger and a hard-coded zero for a phase with time but no entry. A real measured zero stays zero. No entry at all is now null and prints "no data".
The first version of the hook migration found nothing, because it read a registry that only fills after an explicit registration call. Its own tests caught it on the first run.