docs: refresh agent context, drop volatile counts, restore mirror - #47
Merged
Conversation
CLAUDE.md and AGENTS.md declare each other mirrors but had drifted: AGENTS.md was missing the entire Site deploy section. AGENTS.md is now regenerated from CLAUDE.md, differing only in the header block. - Remove volatile counts (test total, registry size). The file already said "issues are the source of truth, not this file" while stating a test count that had gone stale. Give the command instead. - Add CONTRIBUTING.md and .github/workflows to the structure tree - Document the JD_INTEL_REGISTRY_URL local-testing gotcha - Note that the gate retries transient failures, and that a 429 is not a dead board - Three anti-patterns from today: status-by-message-regex, merging parallel agent output without reconciliation, stating volatile counts
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.
The mirror was broken
Both files declare AGENTS.md canonical and CLAUDE.md its mirror. They had drifted: CLAUDE.md carried the entire Site deploy (GitHub Pages) section and AGENTS.md did not. An agent reading AGENTS.md got no warning about
?v=cache-busting or the required gtag and theme snippets, then breaks the site.AGENTS.md is now generated from CLAUDE.md and differs only in the header comment. Verified identical below the headers.
Volatile counts do not belong in these files
The file already had the right principle, in a section titled "Where to find current state (live, not snapshot)":
No number. Then 70 lines earlier, the same command with
# 124 tests, all should pass. The actual count is 142 and had been wrong for a while. Line 49 had the same problem with700+ company verified registry, a number the weekly expansion changes by design.Fixing the numbers just resets a clock. Removed them instead, and stated the rule explicitly so it does not come back.
Kept: the seven adapters and their names. That changes only when someone deliberately ships an adapter. User-facing counts in
README.mdanddocs/index.htmlare a separate category with their own hundreds-boundary process, untouched.Added
CONTRIBUTING.mdand.github/workflows/in the structure tree, both missingJD_INTEL_REGISTRY_URLgotcha: the library reads the registry from the published Pages URL, so a locally-added company returns 0 jobs until it merges. This currently burns anyone following CONTRIBUTING.md.Three anti-patterns from today
/5\d\d/reads"(ufp/wd503/Careers): 404"as a retryable 5xx.Docs only. No code, no registry changes.