docs(CONTRIBUTING): add org-level Layout conventions section#4
Merged
Conversation
States the cross-repo rule: docs/ holds only human-readable prose (.md, .markdown, images, .gitkeep); technical artifacts live under dist/ (Phase 0 contract), examples/, templates/, scripts/, tools/, or a domain-specific top-level dir. Provides a single table of which standardized directories are relevant where. Enforced per-repo by make check-docs-prose (CI gate; landed in each tier-1 repo + meta-repo in PRs #5/#8/#11/#3 today). Each tier-1 AGENTS.md will carry a "Layout conventions" section that specializes this table for its own layout and links back here.
This was referenced May 11, 2026
rafael5
added a commit
that referenced
this pull request
May 11, 2026
Adds Phase-0 pointer URLs to the tree-sitter-m entry, mirroring the m-modern-corpus follow-up (.github PR #6) after PR #4 in tree-sitter-m landed: - agent_instructions: AGENTS.md - repo_meta_url: dist/repo.meta.json - node_types_url: src/node-types.json - grammar_url: src/grammar.json - grammar_metadata_url: src/grammar-metadata.json Hand-curated lines (role, consumes, consumed_by, bindings, validation) stay until Phase 1 ships build-catalog.py — those will fall away in favour of generator-derived summaries. Tier-2 onboarding per AI-discoverability-plan.md §3.4 / phase1-plan.md §9. Phase 2 progress: 2 of 3 tier-2 repos onboarded (m-modern-corpus + tree-sitter-m); m-test-engine remains.
rafael5
added a commit
that referenced
this pull request
May 11, 2026
Supplements AI-discoverability-plan.md §3.4. §3.4 was authored when no repo shipped the Phase-0 contract; with tier-1 + tier-2 onboarded (6 of 9 repos as of 2026-05-10), that table is stale as a priority guide. This doc reframes priority around the actual remaining work and ranks it by *downstream dependents* — not by ease of shipping. Structure: - §2 Current-state inventory (per-repo Phase-0 contract status) - §3 Outstanding work catalogued from parent plan §7 + phase1-plan.md - §4 Dependency graph (ASCII; shows what blocks what) - §5 Priority ranking by downstream-leverage (P1-A ranks #1 with 6 downstream items; tier-3 onboarding ranks #4 despite being "easy" because it doesn't unblock anything) - §6 Recommended execution order — single-threaded sequence + which items to parallelize when bandwidth allows - §6.4 explicit "easy first" trap: ships three quick PRs, leaves nothing unblocked - §7 Concrete recommended next move: ship P1-A as a single coherent PR (cuts the longest dependency chain in front of the entire Phase 1 + 3 + 4 stack) - §8 How to keep the doc in sync (read-then-act discipline) Source files referenced (all on main): - AI-discoverability-plan.md §3.4 — original tier-based framing - phase0-plan.md — completed - phase1-plan.md — to-do, Track A-D layout matches §3-5 here Prose-only gate (make check-docs-prose) green: doc is .md under docs/.
This was referenced May 11, 2026
rafael5
added a commit
that referenced
this pull request
May 11, 2026
…s/history/ (#17) The m-tools repo on GitHub is archived. Three design documents in it are still load-bearing — they're the *why* behind the m-dev-tools ecosystem's shape (Go/Rust/Python toolchain analogy that drove m-cli's CLI ergonomics, Tier-1 strategy that scoped the first m-cli release, phased remediation roadmap that produced both m-cli and m-stdlib). Routing agents at a repo we no longer maintain — and one GitHub could prune at any time — is brittle. Resolution per AI-discoverability-plan.md §8 non-goal #4 ("rehost its docs in .github/docs/history/ or drop them from tools.json"): rehost, not drop. Changes: - docs/history/ — verbatim copies of three preserved docs: - gap-analysis-and-remediation-strategy.md - m-tool-gap-analysis.md - m-tooling-tier1.md Plus a README.md documenting the provenance policy and the explicit exclusion of implementation.md + ydb-dev-tools-gap-analysis.md. Each preserved doc carries a single `> Archived snapshot.` banner after the H1 citing upstream commit 16fe3f7 (2026-04-27). - profile/tools.json: dropped the `m-tools` entry (was `status: archived`, no manifest by design); build-catalog's archived-carryover no longer triggers for it since the prior tools.json doesn't list it. - profile/task_index.json: retargeted the three `history` category intents from `tool:m-tools` to typed-ID `doc:m-dev-tools#<filename>` and the new in-org doc URLs. - profile/README.md, docs/AI-discoverability-plan.md, docs/AI-discoverability-guide.md: cross-references retargeted at the in-org paths. Equivalent to the original chore/rehost-archived-m-tools-docs work (PR #14), rebuilt on top of post-P1-A/P1-D state. PR #14 conflicted heavily on profile/tools.json because it was authored against pre-P1-A baseline. Verification: - make check-docs-prose ✓ (docs/history/ holds only .md prose) - make validate-catalog ✓ (tools.json + task_index.json strict-validate) - make catalog ✓ (regen is byte-idempotent; m-tools stays gone) - 26/26 pytest in profile/build/ - make phase0-smoke PASS
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
States the cross-repo rule: `docs/` holds only human-readable prose; technical artifacts live under `dist/` (Phase 0 contract), `examples/`, `templates/`, `scripts/`, `tools/`, or a domain-specific top-level dir.
Sits in CONTRIBUTING.md alongside the existing Code style section — both are org-level rules enforced at PR time. Enforced per-repo by `make check-docs-prose` (CI gate; landed in m-stdlib #5, m-standard #8, m-cli #11, .github #3 earlier today).
Follow-up
Each tier-1 AGENTS.md gets a "Layout conventions" section that specializes this table for its own top-level layout — three small follow-on PRs.