From 20cb4f10d35971d1a52d6cba5b6dce73cc7d2a73 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 20:05:20 -0400 Subject: [PATCH] =?UTF-8?q?Restructure:=20relocate=20docs/integrated/=20?= =?UTF-8?q?=E2=86=92=20integrated/=20(reverts=203bfb947)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AGENTS.md | 6 ++--- dist/repo.meta.json | 18 ++++++------- {docs/integrated => integrated}/commands.json | 0 {docs/integrated => integrated}/commands.tsv | 0 .../integrated => integrated}/conflicts.json | 0 {docs/integrated => integrated}/conflicts.tsv | 0 .../environment.json | 0 .../integrated => integrated}/environment.tsv | 0 {docs/integrated => integrated}/errors.json | 0 {docs/integrated => integrated}/errors.tsv | 0 .../grammar-surface.json | 0 .../intrinsic-functions.json | 0 .../intrinsic-functions.tsv | 0 .../intrinsic-special-variables.json | 0 .../intrinsic-special-variables.tsv | 0 .../multi-vendor-extensions.tsv | 0 .../operational-m-standard.json | 0 .../operational-m-standard.tsv | 0 .../integrated => integrated}/operators.json | 0 {docs/integrated => integrated}/operators.tsv | 0 .../pattern-codes.json | 0 .../pattern-codes.tsv | 0 .../pragmatic-m-standard.json | 0 .../pragmatic-m-standard.tsv | 0 .../va-sac-compliance.json | 0 .../va-sac-compliance.tsv | 0 .../va-sac-rules.tsv | 0 src/m_standard/tools/validate.py | 26 +++++++------------ 28 files changed, 22 insertions(+), 28 deletions(-) rename {docs/integrated => integrated}/commands.json (100%) rename {docs/integrated => integrated}/commands.tsv (100%) rename {docs/integrated => integrated}/conflicts.json (100%) rename {docs/integrated => integrated}/conflicts.tsv (100%) rename {docs/integrated => integrated}/environment.json (100%) rename {docs/integrated => integrated}/environment.tsv (100%) rename {docs/integrated => integrated}/errors.json (100%) rename {docs/integrated => integrated}/errors.tsv (100%) rename {docs/integrated => integrated}/grammar-surface.json (100%) rename {docs/integrated => integrated}/intrinsic-functions.json (100%) rename {docs/integrated => integrated}/intrinsic-functions.tsv (100%) rename {docs/integrated => integrated}/intrinsic-special-variables.json (100%) rename {docs/integrated => integrated}/intrinsic-special-variables.tsv (100%) rename {docs/integrated => integrated}/multi-vendor-extensions.tsv (100%) rename {docs/integrated => integrated}/operational-m-standard.json (100%) rename {docs/integrated => integrated}/operational-m-standard.tsv (100%) rename {docs/integrated => integrated}/operators.json (100%) rename {docs/integrated => integrated}/operators.tsv (100%) rename {docs/integrated => integrated}/pattern-codes.json (100%) rename {docs/integrated => integrated}/pattern-codes.tsv (100%) rename {docs/integrated => integrated}/pragmatic-m-standard.json (100%) rename {docs/integrated => integrated}/pragmatic-m-standard.tsv (100%) rename {docs/integrated => integrated}/va-sac-compliance.json (100%) rename {docs/integrated => integrated}/va-sac-compliance.tsv (100%) rename {docs/integrated => integrated}/va-sac-rules.tsv (100%) diff --git a/AGENTS.md b/AGENTS.md index 2191c4c..c97a3f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,7 +132,7 @@ make check # lint + mypy + cov (run before push) ``` ## Build / generate -The committed payloads under `docs/integrated/` are produced by the +The committed payloads under `integrated/` are produced by the pipeline. To regenerate them from `sources/`: ```bash @@ -147,7 +147,7 @@ hasn't drifted from the committed integrated payloads. These are the `verification_commands` declared in `dist/repo.meta.json`: ```bash -make integrated # regenerates docs/integrated/ deterministically +make integrated # regenerates integrated/ deterministically make test # full test suite ``` @@ -155,7 +155,7 @@ A green `make check-manifest` proves the committed integrated payloads still match what the pipeline produces. ## Guardrails -- **Do not hand-edit `docs/integrated/*` files.** They are pipeline +- **Do not hand-edit `integrated/*` files.** They are pipeline outputs; edit `sources/` + the extract/reconcile/emit stages instead. - **Do not hand-edit `dist/repo.meta.json` `verified_on` to a future date.** The Phase 0 smoke test rejects manifests older than 90 days; diff --git a/dist/repo.meta.json b/dist/repo.meta.json index caf2cdf..5d19a4c 100644 --- a/dist/repo.meta.json +++ b/dist/repo.meta.json @@ -8,15 +8,15 @@ "agent_instructions": "AGENTS.md", "verified_on": "2026-05-10", "exposes": { - "grammar_surface": "docs/integrated/grammar-surface.json", - "commands": "docs/integrated/commands.tsv", - "intrinsic_functions": "docs/integrated/intrinsic-functions.tsv", - "intrinsic_special_variables": "docs/integrated/intrinsic-special-variables.tsv", - "operators": "docs/integrated/operators.tsv", - "errors": "docs/integrated/errors.tsv", - "pragmatic_standard": "docs/integrated/pragmatic-m-standard.json", - "operational_standard": "docs/integrated/operational-m-standard.json", - "va_sac_rules": "docs/integrated/va-sac-rules.tsv" + "grammar_surface": "integrated/grammar-surface.json", + "commands": "integrated/commands.tsv", + "intrinsic_functions": "integrated/intrinsic-functions.tsv", + "intrinsic_special_variables": "integrated/intrinsic-special-variables.tsv", + "operators": "integrated/operators.tsv", + "errors": "integrated/errors.tsv", + "pragmatic_standard": "integrated/pragmatic-m-standard.json", + "operational_standard": "integrated/operational-m-standard.json", + "va_sac_rules": "integrated/va-sac-rules.tsv" }, "verification_commands": ["make integrated", "make test"] } diff --git a/docs/integrated/commands.json b/integrated/commands.json similarity index 100% rename from docs/integrated/commands.json rename to integrated/commands.json diff --git a/docs/integrated/commands.tsv b/integrated/commands.tsv similarity index 100% rename from docs/integrated/commands.tsv rename to integrated/commands.tsv diff --git a/docs/integrated/conflicts.json b/integrated/conflicts.json similarity index 100% rename from docs/integrated/conflicts.json rename to integrated/conflicts.json diff --git a/docs/integrated/conflicts.tsv b/integrated/conflicts.tsv similarity index 100% rename from docs/integrated/conflicts.tsv rename to integrated/conflicts.tsv diff --git a/docs/integrated/environment.json b/integrated/environment.json similarity index 100% rename from docs/integrated/environment.json rename to integrated/environment.json diff --git a/docs/integrated/environment.tsv b/integrated/environment.tsv similarity index 100% rename from docs/integrated/environment.tsv rename to integrated/environment.tsv diff --git a/docs/integrated/errors.json b/integrated/errors.json similarity index 100% rename from docs/integrated/errors.json rename to integrated/errors.json diff --git a/docs/integrated/errors.tsv b/integrated/errors.tsv similarity index 100% rename from docs/integrated/errors.tsv rename to integrated/errors.tsv diff --git a/docs/integrated/grammar-surface.json b/integrated/grammar-surface.json similarity index 100% rename from docs/integrated/grammar-surface.json rename to integrated/grammar-surface.json diff --git a/docs/integrated/intrinsic-functions.json b/integrated/intrinsic-functions.json similarity index 100% rename from docs/integrated/intrinsic-functions.json rename to integrated/intrinsic-functions.json diff --git a/docs/integrated/intrinsic-functions.tsv b/integrated/intrinsic-functions.tsv similarity index 100% rename from docs/integrated/intrinsic-functions.tsv rename to integrated/intrinsic-functions.tsv diff --git a/docs/integrated/intrinsic-special-variables.json b/integrated/intrinsic-special-variables.json similarity index 100% rename from docs/integrated/intrinsic-special-variables.json rename to integrated/intrinsic-special-variables.json diff --git a/docs/integrated/intrinsic-special-variables.tsv b/integrated/intrinsic-special-variables.tsv similarity index 100% rename from docs/integrated/intrinsic-special-variables.tsv rename to integrated/intrinsic-special-variables.tsv diff --git a/docs/integrated/multi-vendor-extensions.tsv b/integrated/multi-vendor-extensions.tsv similarity index 100% rename from docs/integrated/multi-vendor-extensions.tsv rename to integrated/multi-vendor-extensions.tsv diff --git a/docs/integrated/operational-m-standard.json b/integrated/operational-m-standard.json similarity index 100% rename from docs/integrated/operational-m-standard.json rename to integrated/operational-m-standard.json diff --git a/docs/integrated/operational-m-standard.tsv b/integrated/operational-m-standard.tsv similarity index 100% rename from docs/integrated/operational-m-standard.tsv rename to integrated/operational-m-standard.tsv diff --git a/docs/integrated/operators.json b/integrated/operators.json similarity index 100% rename from docs/integrated/operators.json rename to integrated/operators.json diff --git a/docs/integrated/operators.tsv b/integrated/operators.tsv similarity index 100% rename from docs/integrated/operators.tsv rename to integrated/operators.tsv diff --git a/docs/integrated/pattern-codes.json b/integrated/pattern-codes.json similarity index 100% rename from docs/integrated/pattern-codes.json rename to integrated/pattern-codes.json diff --git a/docs/integrated/pattern-codes.tsv b/integrated/pattern-codes.tsv similarity index 100% rename from docs/integrated/pattern-codes.tsv rename to integrated/pattern-codes.tsv diff --git a/docs/integrated/pragmatic-m-standard.json b/integrated/pragmatic-m-standard.json similarity index 100% rename from docs/integrated/pragmatic-m-standard.json rename to integrated/pragmatic-m-standard.json diff --git a/docs/integrated/pragmatic-m-standard.tsv b/integrated/pragmatic-m-standard.tsv similarity index 100% rename from docs/integrated/pragmatic-m-standard.tsv rename to integrated/pragmatic-m-standard.tsv diff --git a/docs/integrated/va-sac-compliance.json b/integrated/va-sac-compliance.json similarity index 100% rename from docs/integrated/va-sac-compliance.json rename to integrated/va-sac-compliance.json diff --git a/docs/integrated/va-sac-compliance.tsv b/integrated/va-sac-compliance.tsv similarity index 100% rename from docs/integrated/va-sac-compliance.tsv rename to integrated/va-sac-compliance.tsv diff --git a/docs/integrated/va-sac-rules.tsv b/integrated/va-sac-rules.tsv similarity index 100% rename from docs/integrated/va-sac-rules.tsv rename to integrated/va-sac-rules.tsv diff --git a/src/m_standard/tools/validate.py b/src/m_standard/tools/validate.py index 6b2319b..4752428 100644 --- a/src/m_standard/tools/validate.py +++ b/src/m_standard/tools/validate.py @@ -34,25 +34,19 @@ def _integrated_dir(project_root: Path) -> Path: """Resolve the integrated/ directory location. - The repo layout was restructured in commit 3bfb947 (2026-04-30) to - move `integrated/` under `docs/integrated/`. Every gate in this - module reads from there. Accept either layout so a mid-migration - or older checkout still works: - - 1. `/docs/integrated/` (current layout, preferred) - 2. `/integrated/` (pre-3bfb947 fallback) - - Returns the first that exists; falls back to the new path even if - neither exists, so callers that probe ``.exists()`` get a path - rooted in the current layout. + The canonical layout has `integrated/` at the repo root, alongside + `per-source/`, `schemas/`, `sources/`, and `src/`. The repo briefly + held it at `docs/integrated/` (3bfb947 .. its reversion); the + fallback is kept for one release cycle so a stale checkout still + validates. """ - new = project_root / "docs" / "integrated" - if new.is_dir(): - return new - legacy = project_root / "integrated" + canonical = project_root / "integrated" + if canonical.is_dir(): + return canonical + legacy = project_root / "docs" / "integrated" if legacy.is_dir(): return legacy - return new + return canonical # Names that are ALWAYS tracked under sources// regardless of