chore(history): rehost archived m-tools design docs under .github/docs/history/#14
Closed
rafael5 wants to merge 1 commit into
Closed
chore(history): rehost archived m-tools design docs under .github/docs/history/#14rafael5 wants to merge 1 commit into
rafael5 wants to merge 1 commit into
Conversation
…s/history/ 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 (the Go/Rust/Python toolchain analogy that drove m-cli's CLI ergonomics, the Tier-1 strategy that scoped the first m-cli release, and the phased remediation roadmap that produced both m-cli and m-stdlib). Routing agents at a repo we no longer maintain — and one that 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: - New: docs/history/ — verbatim copies of the three preserved docs, each with a single `> Archived snapshot.` banner after the H1 citing the upstream commit (16fe3f7, 2026-04-27). README.md in the directory documents the provenance policy and the explicit exclusion of implementation.md + ydb-dev-tools-gap-analysis.md. - profile/tools.json: dropped the tool:m-tools entry; updated the first-principles bullet to point at the in-org rehost path. - profile/task_index.json: retargeted the three history-category intents to doc:m-dev-tools#<filename> typed IDs and the new in-org doc URLs. - profile/README.md: replaced the "Historical root" repo row and the architecture-diagram caption to point at .github/docs/history/ instead of the archived repo. - docs/AI-discoverability-plan.md: marked the m-tools row in §3.4 resolved; expanded non-goal #4 to record the resolution. - docs/AI-discoverability-guide.md: updated the example typed ID in §11 from doc:m-tools#gap-analysis to doc:m-dev-tools#m-tool-gap-analysis to match the new scheme. Validation: - make check-docs-prose: green (only .md files under docs/history/). - make validate-catalog: green. - Typed-ID grammar regex (tools.schema.json $defs/typedID) applied to every primary + see_also in task_index.json: all pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Superseded by #17 (rebuilt against post-P1-A/P1-D baseline; this PR's profile/tools.json was on the pre-P1-A shape and would have produced unresolvable merge conflicts). Same content; same intent. |
2 tasks
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
m-dev-tools/m-toolsrepo as verbatim, frozen snapshots under.github/docs/history/.tool:m-toolsentry fromprofile/tools.jsonand retarget the threetask_index.jsonhistoryintents at newdoc:m-dev-tools#<filename>typed IDs pointing at the in-org rehosts.profile/README.mdtable row + architecture diagram caption and reconcile the two AI-discoverability docs (table row in §3.4 marked resolved; non-goal docs(CONTRIBUTING): add org-level Layout conventions section #4 expanded to record the resolution; one illustrative typed ID corrected).Resolves
AI-discoverability-plan.md§8 non-goal #4: "m-toolsis archived; either rehost its docs in.github/docs/history/or drop them fromtools.json. Agents care about the current shape." Chose rehost because the three preserved docs (gap analysis + Tier 1 strategy + remediation roadmap) are the design rationale behindm-cli's whole CLI shape; losing them to upstream pruning would erase the why. Cost: ~262 KB of frozen Markdown in.github.Files
docs/history/{README.md, m-tool-gap-analysis.md, m-tooling-tier1.md, gap-analysis-and-remediation-strategy.md}. Each rehost carries a single> Archived snapshot.banner after its H1 citing upstream commit16fe3f7(2026-04-27). One dangling sibling-link toimplementation.mdingap-analysis-and-remediation-strategy.mdwas retargeted at the archived upstream URL (read-only on GitHub) rather than rehosting a fourth file — provenance noted inhistory/README.md.profile/tools.json(droptool:m-toolsblock + update first-principles bullet),profile/task_index.json(retarget 3 history intents todoc:m-dev-tools#<slug>typed IDs + new in-org URLs),profile/README.md(Historical-root row + diagram caption),docs/AI-discoverability-plan.md(§3.4 row + §8 non-goal docs(CONTRIBUTING): add org-level Layout conventions section #4),docs/AI-discoverability-guide.md(one example typed ID).Test plan
python3 -m json.tool profile/tools.json— parsespython3 -m json.tool profile/task_index.json— parsesmake check-docs-prose— green (.github/docs/history/is.md-only)make validate-catalog— greentools.schema.json#/\$defs/typedIDapplied to everyprimary+see_alsointask_index.json— all pass; three new IDs validated:doc:m-dev-tools#gap-analysis-and-remediation-strategydoc:m-dev-tools#m-tool-gap-analysisdoc:m-dev-tools#m-tooling-tier1m-tools/blob/main/docs/...URLs in the catalog or routing files; remainingm-toolsmentions are intentional provenance citations only.Not in scope
m-tools/docs/implementation.mdandydb-dev-tools-gap-analysis.mdare deliberately not rehosted (history/README.mdexplains why). Both remain reachable in the archivedm-toolsrepo for anyone who wants the deeper context.🤖 Generated with Claude Code