docs(agents): describe the real tree; errata for unshipped artifacts; doc-path CI gate (#65)#82
Merged
Merged
Conversation
… doc-path CI gate (#65) The agent contract referenced artifacts that do not exist — for an agent-first repo this is load-bearing documentation: an agent told to load a persona from .eamos-core/agent/*.md will fail or improvise one. - AGENTS.md §1: the specialized personas are marked planned (ROADMAP backlog), not shipped; this file is the only persona until they land. - AGENTS.md §4: the layout tree now matches the tree — agent/, orchestrator/commands/, templates/ and GEMINI.md removed; functions/, setup/, docs/i18n added; os/ children named for what ships. - AGENTS.md §3: the Templates bullet becomes Emitters — the real render path (IR -> emit_*.py, themed by os/themes tokens); no templates dir. - RFC-0001: errata notes (the RFC is frozen for M1) in §8 (agent/*.md not shipped) and §10 (gates are code in tools/eamos_lint.py; their vocabularies are data; 'gates as data' tracked in the backlog). - ROADMAP backlog: personas + phase commands, and gates-as-data, are now explicit items instead of phantom references. - CLAUDE.md: the factory list says emitters, not templates. Guard against recurrence: new tools/check_docs.py extracts every path-looking reference from AGENTS.md / README.md / CLAUDE.md (markdown links, inline-code paths, and the §4 layout tree, with glob and brace expansion) and fails listing each broken one; wired as a CI step on both legs. Verified red against main's AGENTS.md (the 4 phantom paths) and green after this change; 97/97 tests pass. Closes #65 Co-Authored-By: Claude Fable 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.
Problem (#65)
The agent contract referenced artifacts that do not exist in the tree — load-bearing documentation for an agent-first repo: an agent told to load a persona from
.eamos-core/agent/*.mdwill fail or, worse, improvise one. Phantom references:agent/personas,orchestrator/commands/,templates/,GEMINI.md, and RFC-0001 §10'sorchestrator/os/gate/.Fix (doc-only + one guard)
AGENTS.mdis the only persona.agent/,commands/,templates/,GEMINI.mdremoved;functions/,setup/,docs/i18nadded;os/children named for what actually ships.emit_*.py, themed byos/themes/tokens); there is no templates directory.agent/*.mdnot shipped; §10 — the gates are code intools/eamos_lint.py, their vocabularies are data underorchestrator/os/, and "gates as data" is now an explicit backlog item.Guard against recurrence
New
tools/check_docs.py: extracts every path-looking reference fromAGENTS.md/README.md/CLAUDE.md— markdown link targets, inline-code paths (glob-aware, placeholder-safe), and the §4 layout tree (with brace expansion and nesting) — and fails listing each broken reference. Wired as a CI step on both OS legs.Verified red against
main's AGENTS.md (catches the 4 phantom paths) and green after this change; every path referenced by the three docs now resolves. 97/97 tests pass.Closes #65
🤖 Generated with Claude Code