Skip to content

Skip non-scaffold files in tool config sync - #125

Open
olddognewflex wants to merge 4 commits into
mex-memory:mainfrom
olddognewflex:main
Open

Skip non-scaffold files in tool config sync#125
olddognewflex wants to merge 4 commits into
mex-memory:mainfrom
olddognewflex:main

Conversation

@olddognewflex

Copy link
Copy Markdown

Problem

checkToolConfigSync treats any co-existing CLAUDE.md / AGENTS.md / .cursorrules / .windsurfrules / .github/copilot-instructions.md as byte-identical copies installed from .tool-configs/, and raises TOOL_CONFIG_DRIFT whenever two differ.

That assumption fails in repos where those files have independent owners. Real case: a repo with a hand-written CLAUDE.md (project context) and an AGENTS.md generated by tkt sync-pack (managed skill pack, "do not edit by hand"). Neither file ever came from .tool-configs/, and the warning is unfixable — making them match would either clobber the managed block or duplicate machine-regenerated content that re-drifts on the next sync.

Fix

Every .tool-configs/ template carries a ROUTER.md scaffold pointer. A file now participates in the mirror comparison only when its content includes that marker:

  • Non-copies (no marker) are skipped entirely — no comparison, no warning.
  • Genuine drift between real scaffold copies is still flagged, including when non-copies sit alongside them.

Trade-off: a copy edited so heavily that the ROUTER.md pointer is removed drops out of the check — at that point it is no longer a scaffold anchor, so silence is the correct behaviour.

Testing

  • Existing drift fixtures updated to carry the marker.
  • Two new tests: hand-written + generated coexistence produces no issue; comparison still runs among the remaining real copies when non-copies are present.
  • npx vitest run test/checkers.test.ts — 54/54 pass.
  • Verified against the originating repo: TOOL_CONFIG_DRIFT false positive gone, drift score 88 → 91, real checks unaffected.

checkToolConfigSync assumed any co-existing CLAUDE.md / AGENTS.md /
.cursorrules were byte-identical copies installed from .tool-configs/,
and flagged TOOL_CONFIG_DRIFT whenever two differed. Repos commonly
have a hand-written CLAUDE.md or a generated AGENTS.md (e.g. a managed
skill pack) that never came from the templates; comparing those is a
false positive the user cannot fix without breaking one of the files.

Every .tool-configs/ template carries a ROUTER.md scaffold pointer, so
a file now participates in the mirror comparison only when its content
includes that marker. Genuine drift between real scaffold copies is
still flagged; non-copies are ignored.
…ositive

fix: skip non-scaffold files in tool config sync
@olddognewflex olddognewflex changed the title fix: skip non-scaffold files in tool config sync Skip non-scaffold files in tool config sync Aug 10, 2026

@theDakshJaitly theDakshJaitly left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scaffold-copy detection remains too broad. ROUTER.md is not unique to mex-generated tool configs: independently owned CLAUDE.md and AGENTS.md files can legitimately tell agents to read ROUTER.md, causing this code to compare them and still report TOOL_CONFIG_DRIFT. I reproduced this with two unrelated files containing ordinary See ROUTER.md guidance. Please add a dedicated scaffold sentinel, such as an HTML mex-tool-config comment, to the generated templates and match that instead, with a regression test where non-scaffold files mention ROUTER.md. The focused tests, full suite (371 tests), and typecheck otherwise pass.

Matching on "ROUTER.md" was still too broad: independently owned
CLAUDE.md/AGENTS.md files legitimately tell agents to read ROUTER.md,
so unrelated files were compared and flagged as TOOL_CONFIG_DRIFT.

Generated .tool-configs/ templates now carry an HTML sentinel comment
(<!-- mex-tool-config ... -->) and the checker matches only that.
Regression test covers non-scaffold files that mention ROUTER.md.
@olddognewflex

Copy link
Copy Markdown
Author

Addressed in 5f37ac4 (landing on this branch via the fork's main).

  • Generated .tool-configs/ templates now carry a dedicated sentinel comment (<!-- mex-tool-config: managed copy from .tool-configs/ ... -->), added to all four markdown templates and the repo's own .mex/.tool-configs/ copies.
  • checkToolConfigSync matches only that sentinel instead of the ROUTER.md substring, so independently owned CLAUDE.md/AGENTS.md files that merely mention ROUTER.md are no longer compared.
  • Regression test added: two non-scaffold files each containing ordinary "See ROUTER.md" guidance produce no TOOL_CONFIG_DRIFT.

372 tests pass, typecheck clean.

One trade-off to note: copies installed from pre-sentinel templates won't carry the marker, so the checker skips them until they're re-copied — a false negative rather than a false positive, which seems the right direction, but happy to add migration handling if you'd prefer.

…ositive

fix: use dedicated sentinel for tool config sync
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants