diff --git a/docs/ai-discoverability/AI-discoverability-plan.md b/docs/ai-discoverability/AI-discoverability-plan.md index 9f1a957..8e5b141 100644 --- a/docs/ai-discoverability/AI-discoverability-plan.md +++ b/docs/ai-discoverability/AI-discoverability-plan.md @@ -117,7 +117,7 @@ For each repo, in order: | `tree-sitter-m-vscode` | exists | `package.json` already declares it; wrap | needs add | tier 3 | | `m-stdlib-vscode` | needs check | `package.json` + manifest discovery config | needs add | tier 3 | | `m-cli-extras` | unknown | dump plugin entry points to JSON | needs add | tier 3 | -| `m-tools` | archived (upstream) | **rehosted** under [`.github/docs/history/`](history/); dropped from `tools.json` | n/a | resolved | +| `m-tools` | moved out of the org (now [`rafael5/m-tools`](https://github.com/rafael5/m-tools)) | **rehosted** under [`.github/docs/history/`](history/); dropped from `tools.json` | n/a | resolved | Until tier 1 emits machine-readable artifacts, the org catalog is fiction. @@ -489,7 +489,8 @@ the live registry record. 3. **No org-level CONTRIBUTING.md duplication of repo content.** The org `CONTRIBUTING.md` is ~30 lines pointing at each repo's own contribution guide. -4. **No history/archive routing in the catalog.** `m-tools` is archived; +4. **No history/archive routing in the catalog.** `m-tools` has been moved + out of the org (it now lives at [`rafael5/m-tools`](https://github.com/rafael5/m-tools)); its three design docs are rehosted under [`.github/docs/history/`](history/) and routed via `task_index.json`'s `history` category as `doc:m-dev-tools#` typed IDs. The diff --git a/docs/ai-discoverability/README.md b/docs/ai-discoverability/README.md index 255567a..3c2371a 100644 --- a/docs/ai-discoverability/README.md +++ b/docs/ai-discoverability/README.md @@ -55,5 +55,6 @@ each done-criterion green. `profile/build/`. - Recipes. Those are mechanically-runnable Markdown files under [`../recipes/`](../recipes/), gated by `make recipes-check`. -- Org history / archived projects. That's [`../history/`](../history/) — - e.g. the m-tools archive. +- Org history / retired or moved-out projects. That's + [`../history/`](../history/) — e.g. the m-tools rehost (the source repo + now lives at [`rafael5/m-tools`](https://github.com/rafael5/m-tools)). diff --git a/docs/ai-discoverability/phases/phase3-plan.md b/docs/ai-discoverability/phases/phase3-plan.md index a35b1eb..b9ed2a7 100644 --- a/docs/ai-discoverability/phases/phase3-plan.md +++ b/docs/ai-discoverability/phases/phase3-plan.md @@ -29,7 +29,7 @@ hardening on a weekly schedule (Phase 5 — Phase 3 link-checks at PR time only) | Upstream phase | What Phase 3 needs from it | Status as of 2026-05-11 | |---|---|---| | **Phase 1** (org routing layer) | Generated `profile/tools.json` with `*_url` pointers, `profile/task_index.json` as the intent map, strict `llms.txt` | ✅ **CLOSED 2026-05-10** — A/B/C/D all merged (PRs #10/#11/#12/#16). `make catalog && make validate-catalog` green in CI on every push. `make catalog` byte-idempotent against `origin/main`. | -| **Phase 2** (tier-2 repos `repo.meta.json`) | Recipes #6 (`investigate-failure`) and #7 (`add-editor-support`) reach into `tree-sitter-m`; their manifests must be in the catalog | ✅ **CLOSED 2026-05-10** — all 3 tier-2 + all 3 tier-3 repos onboarded the same day. `tools.json` carries **9 manifest-bearing entries** (m-tools the only archived holdout, rehosted under `docs/history/` per PR #17). | +| **Phase 2** (tier-2 repos `repo.meta.json`) | Recipes #6 (`investigate-failure`) and #7 (`add-editor-support`) reach into `tree-sitter-m`; their manifests must be in the catalog | ✅ **CLOSED 2026-05-10** — all 3 tier-2 + all 3 tier-3 repos onboarded the same day. `tools.json` carries **9 manifest-bearing entries** (m-tools the only out-of-org holdout, rehosted under `docs/history/` per PR #17). | **Phase 3 launch state — both blockers resolved as of 2026-05-11.** All five tracks (A → B+C+D → E) are unblocked. Recipes 6 and 7 (originally Phase-2- diff --git a/docs/history/README.md b/docs/history/README.md index 3fe36da..3b3b143 100644 --- a/docs/history/README.md +++ b/docs/history/README.md @@ -1,55 +1,119 @@ # Historical documents -Frozen, in-org copies of design documents from now-archived repositories in -the `m-dev-tools` org. The original repos remain read-only on GitHub; these -copies exist so the *why* behind the current org shape stays discoverable -inside `.github` itself, immune to upstream pruning or renames. - -These documents are **not maintained**. They reflect the state of the world -at the moment they were imported. For the *current* shape of the org, start -at [`profile/README.md`](../../profile/README.md) and -[`profile/tools.json`](../../profile/tools.json). - -## Contents - -| Document | Source | Imported from commit | Why it's preserved | -|---|---|---|---| -| [`m-tool-gap-analysis.md`](m-tool-gap-analysis.md) | `m-dev-tools/m-tools/docs/m-tool-gap-analysis.md` | [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27) | The Go/Rust/Python toolchain comparison that produced the `m ` design and `m-cli`'s CLI ergonomics. | -| [`m-tooling-tier1.md`](m-tooling-tier1.md) | `m-dev-tools/m-tools/docs/m-tooling-tier1.md` | [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27) | The scoped Tier-1 strategy that defined what `m-cli` shipped first (fmt / lint / test / coverage / watch / LSP). | -| [`gap-analysis-and-remediation-strategy.md`](gap-analysis-and-remediation-strategy.md) | `m-dev-tools/m-tools/docs/gap-analysis-and-remediation-strategy.md` | [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27) | The phased remediation roadmap that produced both `m-cli` and `m-stdlib`. | - -## Provenance policy - -- **Imported verbatim**, with a single `> Archived snapshot.` banner added - after each H1 to make the rehosting fact visible inline. -- **No rewrites, no link-rot patching**, except where a *sibling-doc* link - pointed at a file we did not rehost — those links were retargeted at the - archived upstream repo (read-only) so they still resolve. -- **Typed IDs** for these documents live under - [`profile/task_index.json`](../../profile/task_index.json) (category - `history`). The grammar is `doc:m-dev-tools#`. - -## Adding a new historical doc - -Trigger: another repo in the org is archived and contains design rationale -that future agents/contributors will benefit from reading. - -1. Copy the file(s) verbatim into this directory. -2. Add the `> Archived snapshot.` banner immediately after the H1, citing - the source repo, source commit hash, and date. -3. Append a row to the table above. -4. Add a `doc:m-dev-tools#` typed ID to `task_index.json` under - the `history` category, with an `intent` line that names the - plain-English question the doc answers. -5. Run `make validate-catalog` to confirm the typed IDs validate. -6. Open a PR titled `chore(history): rehost /`. - -## Not on this list - -- **`m-tools/docs/implementation.md`** — implementation log; superseded by - `m-cli/docs/evolution.md` and `m-cli/docs/plans/m-cli-history-and-evolution.md`. -- **`m-tools/docs/ydb-dev-tools-gap-analysis.md`** — 10-line stub; no - preserved content worth rehosting. - -Both remain reachable in the archived `m-tools` repo on GitHub for anyone -who wants the deeper context. +--- + +## How the m-dev-tools ecosystem evolved + +`m-tools` began as a single hub project: a `bin/` of 25 `y*` shell +scripts (`ycheck`, `ytest`, `ycover`, `ydiff`, …) that wrapped +YottaDB's command-line surface, plus a `routines/` tree of tutorial +M code, plus the strategic planning documents that drove everything +else. As the strategy materialised, each capability moved into a +dedicated repository: + +1. **Strategy was codified first.** The four planning documents under + [`docs/`](docs/) framed the problem: M had a real ISO standard and + two production engines (IRIS, YottaDB), but no formatter, no + linter, no test runner, no LSP, no package ecosystem — none of the + "developer inner-loop" infrastructure mainstream languages take + for granted. The + [gap analysis](docs/gap-analysis-and-remediation-strategy.md) + ranked the missing capabilities; + [m-tool-gap-analysis.md](docs/m-tool-gap-analysis.md) §8 fixed + the Tier 1 set; [m-tooling-tier1.md](docs/m-tooling-tier1.md) + produced the focused execution plan; and + [implementation.md](docs/implementation.md) defined the canonical + `m ` command map. + +2. **The language reference came next.** Building tooling against an + under-specified language doesn't work; every linter and formatter + would re-invent its own keyword list and re-litigate which features + were portable. The strategy called for a single citable reference, + and that became + [`m-standard`](https://github.com/m-dev-tools/m-standard) — + the ANSI standard, YottaDB docs, IRIS docs, and VA SAC reconciled + into one machine-readable artefact. + +3. **The parser was generated mechanically from the reference.** + With `m-standard` providing the grammar surface as JSON, + [`tree-sitter-m`](https://github.com/m-dev-tools/tree-sitter-m) + could be built without re-deriving the language by hand. It + shipped clean enough on VistA (99.06%) to back every downstream + tool. + +4. **The CLI replaced the `y*` scripts.** + [`m-cli`](https://github.com/m-dev-tools/m-cli) implemented the + canonical `m ` surface from + [`docs/implementation.md`](docs/implementation.md): + `m fmt` and `m lint` (engine-neutral, source-level), + `m test` and `m coverage` (YottaDB-targeted, runtime-bound), + `m watch` (the TDD inner loop), and the `m lsp` server that + editors plug into. The Tier 1 set from + [`docs/m-tooling-tier1.md`](docs/m-tooling-tier1.md) is fully + shipped; Tier 2 quality gates and project-scaffolding subcommands + layered on top. + +5. **The runtime standard library landed once the toolchain + supported it.** With `m fmt`, `m lint`, and `m test` in place, + it became feasible to ship a versioned, conformance-tested, + discoverable library — + [`m-stdlib`](https://github.com/m-dev-tools/m-stdlib) — covering + the gaps every M shop has historically filled with private + `^XB*` / `^DI*` / `^%Z*` routines: assertions, JSON, regex, + datetime, HTTP, crypto, and the rest. m-stdlib has architectural + priority over m-cli: when both projects need a utility, it lands + in m-stdlib first and m-cli imports. + +6. **The test engine was extracted.** Originally `m-tools`' `Makefile` + staged routines into the heavyweight + [`vista-meta`](https://github.com/rafael5/vista-meta) container + over SSH. For non-VistA M development that was overkill, so the + minimal YottaDB container moved into + [`m-test-engine`](https://github.com/m-dev-tools/m-test-engine) — + `docker exec` replaces SSH staging, and consumer projects + bind-mount their source at `/work`. + +7. **Editor integration shipped last, on top of everything else.** + [`tree-sitter-m-vscode`](https://github.com/m-dev-tools/tree-sitter-m-vscode) + provides syntax highlighting via the WASM-compiled grammar and + spawns `m lsp` for live tooling. Its companion + [`m-stdlib-vscode`](https://github.com/m-dev-tools/m-stdlib-vscode) + reads the m-stdlib manifest for hover, goto-def, and completion + on STD\* symbols. + +8. **A modern validation corpus was assembled.** + [`m-modern-corpus`](https://github.com/m-dev-tools/m-modern-corpus) + collects modern (post-2010, non-VistA) M source from active + open-source projects, calibrating the `M-MOD-NN` rule track + against contemporary idioms rather than legacy VA conventions. + +--- + +## What's preserved here + +- [`docs/gap-analysis-and-remediation-strategy.md`](docs/gap-analysis-and-remediation-strategy.md) + — the original cross-engine gap analysis, the four-tier + prioritisation, the technology-optimal remediation addenda, and + the language-toolchain reference appendices. +- [`docs/m-tool-gap-analysis.md`](docs/m-tool-gap-analysis.md) — + the §8 rank-ordered developer-impact analysis that fixed the + Tier 1 set. +- [`docs/m-tooling-tier1.md`](docs/m-tooling-tier1.md) — the focused + Tier 1 execution plan; still cited from the + [m-cli README](https://github.com/m-dev-tools/m-cli). +- [`docs/implementation.md`](docs/implementation.md) — the original + `m help` command map and as-built specs that `m-cli` realises. + +These are kept verbatim so the ecosystem's design rationale stays +auditable: every choice the sibling repos make ultimately traces back +to a paragraph in one of these four documents. + +--- + +## License + +The historical documents under `docs/` are released under the same +terms as the rest of the `m-dev-tools` family — **AGPL-3.0** — to +match `m-cli`, `m-stdlib`, `m-standard`, `tree-sitter-m`, and +`m-test-engine`. The two VS Code extensions are independently MIT to +align with the broader extension ecosystem. diff --git a/docs/history/gap-analysis-and-remediation-strategy.md b/docs/history/gap-analysis-and-remediation-strategy.md index 85cdbc7..f9d6de5 100644 --- a/docs/history/gap-analysis-and-remediation-strategy.md +++ b/docs/history/gap-analysis-and-remediation-strategy.md @@ -1,11 +1,11 @@ # M Tools — Gap Analysis and Remediation Strategy -> **Archived snapshot.** Imported verbatim from [`m-dev-tools/m-tools`](https://github.com/m-dev-tools/m-tools) — source commit [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), before that repo was archived. Preserved as the original phased remediation roadmap that scoped what became `m-cli` and `m-stdlib`. **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). +> **Archived snapshot.** Imported verbatim from [`m-tools`](https://github.com/rafael5/m-tools) — source commit [`16fe3f7`](https://github.com/rafael5/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), at the point that repo seeded the rest of the m-dev-tools org (it has since been moved out of the org back to its original author's account). Preserved as the original phased remediation roadmap that scoped what became `m-cli` and `m-stdlib`. **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). **Document type:** Strategic planning **Scope:** Developer toolchain for the M (MUMPS) language **Audience:** Developers building productivity tools for the M ecosystem -**Sibling document:** [`implementation.md`](https://github.com/m-dev-tools/m-tools/blob/main/docs/implementation.md) — what's actually shipped *(not rehosted; resolves to the archived m-tools repo, which remains read-only on GitHub)* +**Sibling document:** [`implementation.md`](https://github.com/rafael5/m-tools/blob/main/docs/implementation.md) — what's actually shipped *(not rehosted; resolves to the `rafael5/m-tools` repo on GitHub, where the m-tools content now lives after being moved out of the org)* --- diff --git a/docs/history/m-tool-gap-analysis.md b/docs/history/m-tool-gap-analysis.md index c0063ac..61dc33f 100644 --- a/docs/history/m-tool-gap-analysis.md +++ b/docs/history/m-tool-gap-analysis.md @@ -1,6 +1,6 @@ # M Tools — Gap Analysis (Vendor-Neutral) -> **Archived snapshot.** Imported verbatim from [`m-dev-tools/m-tools`](https://github.com/m-dev-tools/m-tools) — source commit [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), before that repo was archived. Preserved for the design rationale behind the m-dev-tools ecosystem (Go/Rust/Python toolchain analogy that drove `m-cli`'s CLI ergonomics). **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). +> **Archived snapshot.** Imported verbatim from [`m-tools`](https://github.com/rafael5/m-tools) — source commit [`16fe3f7`](https://github.com/rafael5/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), at the point that repo seeded the rest of the m-dev-tools org (it has since been moved out of the org back to its original author's account). Preserved for the design rationale behind the m-dev-tools ecosystem (Go/Rust/Python toolchain analogy that drove `m-cli`'s CLI ergonomics). **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). **Document type:** Reference / strategic planning **Scope:** Developer toolchain for the M (MUMPS) programming language across all current implementations diff --git a/docs/history/m-tooling-tier1.md b/docs/history/m-tooling-tier1.md index 17d99b0..614b9e4 100644 --- a/docs/history/m-tooling-tier1.md +++ b/docs/history/m-tooling-tier1.md @@ -1,6 +1,6 @@ # M Tooling — Tier 1 Strategy: Closing the Inner-Loop Gaps -> **Archived snapshot.** Imported verbatim from [`m-dev-tools/m-tools`](https://github.com/m-dev-tools/m-tools) — source commit [`16fe3f7`](https://github.com/m-dev-tools/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), before that repo was archived. Preserved as the original Tier 1 strategy that scoped what became `m-cli`'s first deliverables. **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). +> **Archived snapshot.** Imported verbatim from [`m-tools`](https://github.com/rafael5/m-tools) — source commit [`16fe3f7`](https://github.com/rafael5/m-tools/commit/16fe3f7dc6982070809cd1d8290d01fedc5905ac) (2026-04-27), at the point that repo seeded the rest of the m-dev-tools org (it has since been moved out of the org back to its original author's account). Preserved as the original Tier 1 strategy that scoped what became `m-cli`'s first deliverables. **Not maintained.** For the *current* shape of the org, start at [`profile/README.md`](../../profile/README.md). **Document type:** Strategic plan, scoped **Scope:** The five Tier 1 developer-toolchain gaps in the M (MUMPS) ecosystem diff --git a/profile/README.md b/profile/README.md index 3288ef6..bbc0cb8 100644 --- a/profile/README.md +++ b/profile/README.md @@ -60,7 +60,7 @@ m-dev-tools ships an MCP server ([`m-dev-tools-mcp`](https://pypi.org/project/m- | Where | What it is | |---|---| -| [`.github/docs/history/`](../docs/history/) | Frozen in-org snapshots of the design documents that seeded the entire org — the original 2026 gap analysis, the Tier 1–4 strategy, and the `m ` command map that produced everything above. Imported verbatim from the (now archived) [`m-tools`](https://github.com/m-dev-tools/m-tools) repo. Start here for the *why*. | +| [`.github/docs/history/`](../docs/history/) | Frozen in-org snapshots of the design documents that seeded the entire org — the original 2026 gap analysis, the Tier 1–4 strategy, and the `m ` command map that produced everything above. Imported verbatim from the [`m-tools`](https://github.com/rafael5/m-tools) seed repo (since moved out of the org back to its original author's account). Start here for the *why*. | ## How the pieces connect @@ -68,7 +68,7 @@ m-dev-tools ships an MCP server ([`m-dev-tools-mcp`](https://pypi.org/project/m- ┌────────────────────────────────────┐ │ .github/docs/history/ │ │ (frozen snapshots from the │ - │ archived m-tools seed repo) │ + │ former m-tools seed repo) │ │ • original gap analysis │ │ • Tier 1–4 strategy docs │ └─────────────────┬──────────────────┘