fix: unreliable CLAUDE.md → AGENTS.md prose pointer; issue title standard - #260
Merged
Merged
Conversation
…standard CLAUDE.md's "Read [AGENTS.md](AGENTS.md) for..." sentence only loads if Claude decides to open the file — not guaranteed every session, per Claude Code's own docs. Replaced with the sentineled @AGENTS.md import ak setup --project already generates for fresh projects, so this repo's own dogfooding matches what the tool produces. ak setup --project's reconciliation only fills in the @AGENTS.md reference when CLAUDE.md is empty; a non-empty hand-authored CLAUDE.md (like this repo had) is left untouched forever, even with the same stale prose pattern. Added detection for that known-unreliable pointer (project-guidance.mjs) and an additive, idempotent migration that adds the reliable import alongside the existing prose without deleting it — wired into both ak setup --project and ak sync, since setup only runs once per project and sync is how an already-set-up project would ever see this fix. Also documents a Conventional-Commits-style issue title standard in AGENTS.md (feat/fix/chore/... plus tracking/research) and retitles the 13 currently-open GitHub issues to conform. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The CI failure on PR #260 (ubuntu-latest, node 26) was unrelated to that PR's diff: tests/kit/upstream-watch-ledger-branch.test.mjs crashed with an uncaught "Error: write EPIPE", reported as async activity after the test had already ended. Root cause: runWithInput spawns git with stdio: ['pipe', 'pipe', 'pipe'] and writes to child.stdin, but never attached an 'error' listener to that stream. A command that exits before draining stdin (e.g. `git hash-object -w --stdin` on an empty blob) closes the pipe's read end; the next write then fails with EPIPE, which Node raises as an unhandled stream error rather than a promise rejection — an uncaughtException that can surface asynchronously, attributed to whatever test happens to be running at that moment. The real outcome was already available via the 'close' event, so the write failure itself is safe to ignore. Added a regression test that reliably reproduces this without CI-only timing: a payload larger than the OS pipe buffer forces the write to block on drain long enough for a child that exits immediately to land mid-write, every run. Verified failing before the fix (3/3 runs) and passing after (3/3 runs). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.md(feat/fix/docs/style/refactor/perf/test/chore, plustracking/researchextensions used only for issues) and retitled the 13 currently-open issues to conform.CLAUDE.mdused a prose sentence ("Read AGENTS.md for...") to point atAGENTS.md. Per Claude Code's own docs, that only loads if Claude decides to open the file — not guaranteed every session, unlike an@AGENTS.mdimport. Replaced it with the sentineled@AGENTS.mdblockak setup --projectalready generates for fresh projects, so this repo now dogfoods what the tool itself produces.ak setup --project/ak syncfix: found that the reconciliation inproject-guidance.mjsonly ever fills in the@AGENTS.mdreference whenCLAUDE.mdis completely empty — any non-empty hand-authoredCLAUDE.md(exactly this repo's prior state) is left untouched forever, even carrying the same known-unreliable prose pattern. AddedhasStaleAgentsPointer/migrateStaleAgentsPointer: an additive, idempotent migration that inserts the reliable@AGENTS.mdimport alongside existing prose without ever deleting user content. Wired into bothak setup --project(existingreconcileProjectGuidancecall) andak sync(new call in theblocksstep), since setup only runs once per project and sync is the only path an already-set-up project would see this fix through.Test plan
node --test tests/kit/project-guidance.test.mjs tests/kit/guidance-targets.test.mjs tests/kit/blocks-drift-parity.test.mjs— 40/40 passing, including new idempotency tests for both the setup and sync migration pathsnpx tsc -p tsconfig.json— cleannpx eslinton all changed files — 0 errors (2 pre-existing complexity warnings insetup.mjs, unrelated to this change, confirmed present onmainbefore this branch)🤖 Generated with Claude Code