Restructure: relocate docs/integrated/ → integrated/ (reverts 3bfb947)#6
Merged
Conversation
Revisited the 3bfb947 move once Phase 0 made the layout a public contract. Three reasons stack for reverting: 1. The code's mental model already lives at repo-root integrated/. Every emit_*.py defaults to Path("integrated"); reconcile.py writes there; validate.py carried a docs/-first preference codepath as a layout-shift workaround. The rename was a filesystem move that the rest of the codebase never internalized. 2. ADR-005 frames the layer as a machine-readable interface, not a reference document. docs/ connotes prose for humans — spec.md, ADRs, the user guide. commands.tsv and grammar-surface.json are wire-format the downstream consumers (tree-sitter-m, m-cli, AI agents) read at their build time. They belong alongside their semantic sibling per-source/, also at the root. 3. The layout shift was leaking into other repos as a compatibility shim — see m-cli/src/m_cli/lint/_keywords.py walking ("", "docs") to find m-standard's integrated/. Phase 0's dist/repo.meta.json just made the current path public; ossifying docs/integrated/ now would force every future consumer to either replicate the shim or break when this gets fixed later. Cost paid by this commit: - git-mv of 25 files docs/integrated/* → integrated/ - dist/repo.meta.json: 9 exposes paths reverted - validate.py: canonical layout flipped (integrated/ preferred, docs/integrated/ kept as fallback for one cycle) - AGENTS.md Build/Verify/Guardrails references updated Phase 0 smoke test continues to pass — pointers move with files atomically. m-cli's _find_m_standard() shim can be simplified in a follow-up commit once this lands on main.
This was referenced May 11, 2026
rafael5
added a commit
that referenced
this pull request
May 11, 2026
Two cleanups bundled: 1. make check-docs-prose — cross-repo guardrail enforcing that docs/ holds only human-readable prose (.md, .markdown, images, .gitkeep). Non-prose artifacts belong under dist/, examples/, templates/, or a top-level domain dir. Wired into CI alongside the existing manifest drift gate. Engine-free, fast, find-based. 2. validate.py _integrated_dir — drop the docs/integrated/ legacy fallback. The relocation back to top-level integrated/ (PR #6) is committed; the fallback's job was to support stale checkouts during the migration window, which is now closed. Three-line simplification — single canonical path.
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
Reverts the
3bfb947move of pipeline outputs intodocs/integrated/.The committed reference data (TSV + JSON, 25 files) returns to
integrated/at the repo root, alongside its semantic siblingper-source/.Triggered by a cross-repo cleanup directive:
docs/should holdonly human-readable prose; technical artifacts, output, data, and
metadata belong elsewhere.
Why revert now (rather than later)
integrated/. Everyemit_*.pydefaults toPath("integrated");reconcile.pywrites there;validate.pycarried adocs/-first preference codepath as a layout-shift workaround. The rename was a filesystem move that the rest of the codebase never internalized.docs/connotes prose for humans —spec.md, ADRs, the user guide.commands.tsvandgrammar-surface.jsonare wire-format the downstream consumers (tree-sitter-m, m-cli, AI agents) read at their build time. They belong alongside their semantic siblingper-source/, also at the root.m-cli/src/m_cli/lint/_keywords.py:25walking("", "docs")to find m-standard's integrated/. Phase 0'sdist/repo.meta.jsonjust made the current path public; ossifyingdocs/integrated/now would force every future consumer to either replicate the shim or break when this gets fixed later.What changes
docs/integrated/*integrated/*(puregit mv, no content edits)dist/repo.meta.jsonexposes.*paths prefixeddocs/integrated/integrated/src/m_standard/tools/validate.pydocs/integrated/preferred,integrated/fallbackintegrated/canonical,docs/integrated/kept as fallback one cycleAGENTS.mddocs/integrated/integrated/Phase 0 contract continuity
The
dist/repo.meta.jsonpointers move atomically with the files. The org-levelphase0-smokerun in.githubwill pick up the new paths on the next run.Verified locally:
make check-manifest✓make test164 passed ✓.github/profile/build/validate-repo-meta.py) green against the new manifest ✓Follow-up
m-cli/src/m_cli/lint/_keywords.py_find_m_standard()shim can drop the("", "docs")walk once this lands on main — separate small PR.