fix: state the minted record-dir shape in the onboarding template (#1009) - #1131
Conversation
github-actions
Bot
added
the
documentation
c21fd0f to
b794302
Compare
…slabs#1009) The onboarding template rendered `aidlc/spaces/<space>/intents/<slug>-<id8>/` into every harness's CLAUDE.md / AGENTS.md while intent-create mints `<YYMMDD>-<label>` and every other instruction surface already says so. Correct the line, fix the same wording in the t174 fixture comment, and add a fifth t174 lane so a `<slug>-<id8>` occurrence in docs/**, core/templates/*.md, or a harness orchestrator SKILL.md fails the gate. Closes awslabs#1009
b794302 to
69522b4
Compare
|
Rebased onto |
…dir wording change The onboarding template fix changes the shipped AGENTS.md bytes for the six harnesses that project it as a managed-block root integration (codex, kiro, kiro-ide, copilot, cursor, opencode). The packager appends only the current rendered hash to `legacySignatures.wholeFileHashes`, so the previously shipped variant must move into each manifest or a copy-channel install still carrying the v2.9.0 unmarked AGENTS.md stops being adoptable on refresh. Add the 2.9.0 hash to each manifest and pin the new current hash in t243's inventory, which is the test that caught this on CI.
apackeer
left a comment
apackeer
left a comment
There was a problem hiding this comment.
Thank you, @vnlebaoduy — for the precise fix, the t174 lane that makes the next occurrence unshippable, and the clean rebase that kept main's tightened learnings-log regex.
I reviewed the current head 69e90e549 against main (c66c42223; trial merge is clean).
Alignment. #1009 is precise and verified on current main: aidlc-utility.ts intent-create mints <YYMMDD>-<label>, aidlc-lib.ts recordDirMatches() keeps <slug>-<id8> only as the pre-spike fallback, and every other authored surface already states the minted shape. The onboarding template was the sole outlier and renders into all seven CLAUDE.md/AGENTS.md files. Fixing it plus adding the fifth t174 lane the issue proposed is the right scope.
One follow-up I pushed (69e90e549). CI's unit shard 4 failed on t243 › legacy signature inventory covers every shipped unmarked root variant. Changing the template changes the shipped AGENTS.md bytes for codex, kiro, kiro-ide, copilot, cursor and opencode; the packager appends only the current hash to each manifest's legacySignatures.wholeFileHashes, so the previously shipped (v2.9.0) hash has to be added to the manifests or a copy-channel install still carrying that unmarked AGENTS.md is no longer recognized on refresh. I added the six v2.9.0 hashes (verified byte-identical against a fresh v2.9.0 build) and pinned the new current hashes in t243, following the rotation #1151 did. This is a repo-internal contract that isn't documented near the template, so it's an easy one to miss — nothing about your change was wrong.
Verified locally on the new head: t243 85/85, t174 3/3 (and it fails naming core/templates/onboarding.md:47 when the template fix is reverted), t68 7/7; bun scripts/package.ts --check deterministic across all seven harnesses; lint and typecheck clean; each rendered CLAUDE.md/AGENTS.md carries one <YYMMDD>-<label> and zero <slug>-<id8>; zero <slug>-<id8> survivors across docs/, core/templates/, the harness orchestrator skills and core/aidlc-common/. The literal <slug>-<id8> predicate is the right tightness — the live claim/<intent-id8>/<unit> ref shape in 12-cli-commands.md and workshop-mode.md would false-positive under anything looser.
Approving; merging now that CI is green on 69e90e549. #1037 targets the same issue but is conflicting and predates the dist/ removal; I'll leave a note there pointing here.
…ess-v3 Base moved to 59105b3 (three commits past 2167de8: fa3c805, awslabs#1199 c66c422, awslabs#1131 59105b3). Five conflicts, plus one upstream test that this branch has to retarget - called out separately below because it is a judgment, not a mechanical resolution. - harness/kiro/manifest.ts - add/add inside the known-unmarked-root-hash list. Both additions are kept: this branch's retired-`kiro-ide` render block and awslabs#1131's 2.9.0 kiro variant (9ad7daa0). awslabs#1199's `shared: "union"` merged cleanly and is present. - harness/kiro-ide/manifest.ts (modify/delete) - stays deleted. Upstream added exactly two things to it, and neither is lost: `shared: "union"`, added identically to harness/kiro/manifest.ts which this branch keeps, and the 2.9.0 render hash 94f27a88, which this branch already lists among the retired renders in the unified manifest. - harness/kiro/hooks/aidlc-kiro-adapter.ts - the same shape as 503cc28: upstream added a name to the `../tools/aidlc-lib.ts` import list inside the block this branch had already replaced. The duplicate is dropped and `stripOrchestratorLauncherOptions` is added to the surviving list in alphabetical position; upstream's call site merged cleanly and now resolves. - tests/fixtures/docs-legacy-refs.json - both sides edited the `_comment`, so both are composed: upstream's FIVE-lane text with its new `<slug>-<id8>` lane, and this branch's `\u2014` -> literal em-dash normalization applied to all five lanes including upstream's new one. - tests/unit/t243-install-mechanism.test.ts, legacy-signature fixture (three hunks) - this fixture is compared with `toEqual` against the BUILT dist projection, whose list is the manifest's declared hashes plus the current render appended by the packager. The merged render is a new file, so neither side's value was correct and the hunks could not be composed by hand. Resolved to this branch's single-`kiro` shape (no `kiro-ide` key, matching `harnessDirs`) and then set from the built descriptor: codex 20 entries ending 87563548 + 12cb3589, kiro 28 ending 94f27a88 + 9ad7daa0 + 60e6f7a8, claude unchanged at 6. RETARGETED UPSTREAM TEST. awslabs#1199's new case "a harness that shares an engine directory cannot coexist" merged cleanly but referenced `KIRO_IDE_RELEASE`, whose declaration this branch removed - the merged tree did not typecheck. The guard it covers is unchanged and worth keeping, and the feature names a second colliding pair, so the case now exercises opencode + copilot, which both claim `.aidlc`, instead of the kiro/kiro-ide pair this branch retires. `kiro-ide` is no longer a harness id the engine knows (zero occurrences in aidlc-init.ts and aidlc-distribution.ts), and the retired stamp's own migration path keeps its separate case. Verified locally: `bun run typecheck` 0 errors across all three projects; `bun tests/gen-coverage-registry.ts --check` OK (fresh, guards green, ratchet held); and, because the retarget is a behavioural change rather than a transcription, three targeted runs after `bun scripts/package.ts` - the retargeted coexistence case (1 pass, 3 expect calls), the t243 signature group (4 pass), and the t174 docs legacy-ref gate (3 pass). The full battery is deliberately not run here - CI is the gate for this PR.
2 participants
Summary
core/templates/onboarding.md:47told every session at startup that the active intent's record dir isaidlc/spaces/<active-space>/intents/<slug>-<id8>/. The engine mints<YYMMDD>-<label>(aidlc-utility.tsintent-create;aidlc-lib.tskeeps<slug>-<id8>only asrecordDirMatches()'s back-compat fallback), and every other instruction surface already states the minted shape. The template was the one outlier, and the t174 docs legacy-ref gate could not catch it because its own fixture comment described<slug>-<id8>as the current shape.Closes #1009.
Changes
core/templates/onboarding.md— the record-dir line now reads<YYMMDD>-<label>; renders into all sevenCLAUDE.md/AGENTS.mdonboarding files.tests/unit/t174-docs-legacy-refs-gate.test.ts— fifth retired-token lane: any<slug>-<id8>occurrence indocs/**/*.md,core/templates/*.md, or a harness orchestratorSKILL.mdmust be pinned in the allowlist. Nothing is pinned, so the lane has zero survivors.tests/fixtures/docs-legacy-refs.json—_commentstates the correct shape and documents lane (5).No version bump, badge, or CHANGELOG entry, per the Release Metadata Policy in
AGENTS.md.User experience
Before: a fresh session reads
<slug>-<id8>fromCLAUDE.md/AGENTS.md, then<YYMMDD>-<label>fromstage-definition.md— two instruction files disagreeing about the same path.After: every onboarding file states the shape the engine actually writes.
Checklist
Test plan
On
355903d6(2.8.2):The new lane fails without the template fix:
git stash push -- core/templates/onboarding.md && bun test tests/unit/t174-docs-legacy-refs-gate.test.tsreportscore/templates/onboarding.md:47as an unpinned occurrence.Rendered check: each of the seven
dist/<harness>/.../{CLAUDE,AGENTS}.mdcontains one<YYMMDD>-<label>and zero<slug>-<id8>.Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.