From b2df9815654b65149e5b65d17f61efa0f693e490 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 08:59:00 -0400 Subject: [PATCH] docs: consolidate AI-discoverability docs under docs/ai-discoverability/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The eleven docs that explain why and how the AI-discoverability framework was designed now live together under one subdirectory. A future maintainer (human or agent) can replay the design decisions from one curated set before changing anything. Moves (all via git mv — git tracks as renames, history preserved): * AI-discoverability-guide.md * AI-discoverability-plan.md * current-state-inventory-priority.md * phase0-plan.md, phase0-status.md * phase1-plan.md, phase1-evidence.md * phase3-plan.md, phase3-evidence.md * phase4-plan.md, phase4-evidence.md Internal cross-refs between these docs are sibling-relative, so they survive the group move unchanged. The four external refs from docs/recipes/README.md got their paths bumped from `../.md` to `../ai-discoverability/.md`. New docs/ai-discoverability/README.md serves as the entry-point index: "read this first" pointers (guide → plan → inventory), a phase table with plan + evidence side-by-side, and an explicit "what this directory is NOT" so a future agent doesn't add a recipe or a generated artifact here. docs/ now contains three subdirs only — ai-discoverability/ (this move), recipes/ (Phase-3 mechanically-runnable artifacts), history/ (archived prose like the m-tools rehosted docs). All four meta-repo gates stay green after the move: * make check-docs-prose — clean (md-only under docs/) * make recipes-check — 4/4 clean (recipes-side cross-refs updated) * make handshake — 8/8 steps green * make validate-catalog — OK * pytest profile/build/ — 51/51 Two known external-URL ref sets need a follow-up pass (not in this PR — out-of-org change): * m-dev-tools-mcp repo (AGENTS.md, README.md, examples/) carries hard-coded URLs like https://github.com/m-dev-tools/.github/blob/main/docs/phase4-plan.md — those'll surface GitHub's "moved" hint after this lands but should be bumped in their own MCP-side PR. * ~/claude/memory/ entries reference local paths under ~/m-dev-tools/.github/docs/ — bumping those is a memory-only cleanup. --- .../AI-discoverability-guide.md | 0 .../AI-discoverability-plan.md | 0 docs/ai-discoverability/README.md | 53 +++++++++++++++++++ .../current-state-inventory-priority.md | 0 docs/{ => ai-discoverability}/phase0-plan.md | 0 .../{ => ai-discoverability}/phase0-status.md | 0 .../phase1-evidence.md | 0 docs/{ => ai-discoverability}/phase1-plan.md | 0 .../phase3-evidence.md | 0 docs/{ => ai-discoverability}/phase3-plan.md | 0 .../phase4-evidence.md | 0 docs/{ => ai-discoverability}/phase4-plan.md | 0 docs/recipes/README.md | 13 ++--- 13 files changed, 60 insertions(+), 6 deletions(-) rename docs/{ => ai-discoverability}/AI-discoverability-guide.md (100%) rename docs/{ => ai-discoverability}/AI-discoverability-plan.md (100%) create mode 100644 docs/ai-discoverability/README.md rename docs/{ => ai-discoverability}/current-state-inventory-priority.md (100%) rename docs/{ => ai-discoverability}/phase0-plan.md (100%) rename docs/{ => ai-discoverability}/phase0-status.md (100%) rename docs/{ => ai-discoverability}/phase1-evidence.md (100%) rename docs/{ => ai-discoverability}/phase1-plan.md (100%) rename docs/{ => ai-discoverability}/phase3-evidence.md (100%) rename docs/{ => ai-discoverability}/phase3-plan.md (100%) rename docs/{ => ai-discoverability}/phase4-evidence.md (100%) rename docs/{ => ai-discoverability}/phase4-plan.md (100%) diff --git a/docs/AI-discoverability-guide.md b/docs/ai-discoverability/AI-discoverability-guide.md similarity index 100% rename from docs/AI-discoverability-guide.md rename to docs/ai-discoverability/AI-discoverability-guide.md diff --git a/docs/AI-discoverability-plan.md b/docs/ai-discoverability/AI-discoverability-plan.md similarity index 100% rename from docs/AI-discoverability-plan.md rename to docs/ai-discoverability/AI-discoverability-plan.md diff --git a/docs/ai-discoverability/README.md b/docs/ai-discoverability/README.md new file mode 100644 index 0000000..14b0783 --- /dev/null +++ b/docs/ai-discoverability/README.md @@ -0,0 +1,53 @@ +# AI-discoverability — framework reference set + +Every document that explains **why** and **how** the AI-discoverability +framework exists. Curated together so a future maintainer (human or +agent) can replay the design decisions before changing anything. + +The framework itself lives at the repo root (`profile/tools.json`, +`profile/task_index.json`, the schemas, the build scripts). This +directory holds the prose that justifies it. + +## Read this first + +If you're new to the framework: + +1. **[`AI-discoverability-guide.md`](AI-discoverability-guide.md)** — + the user-facing intro. Explains what an "AI-discoverable" repo + looks like and what it costs an agent to consume. +2. **[`AI-discoverability-plan.md`](AI-discoverability-plan.md)** — + the de-novo design plan. Three layers (repo-local facts → org + routing → agent operability), success criteria, the architectural + inversion vs. the prior hand-maintained `tools.json` approach. +3. **[`current-state-inventory-priority.md`](current-state-inventory-priority.md)** — + the as-of-Phase-1 snapshot that re-ranked outstanding work by + downstream-dependent priority. Historical, but useful context for + why the phase order is what it is. + +## Phase plans + exit evidence + +Five phases, two docs each — the plan and the evidence file that +captures clean-run output for the phase's exit gate. + +| Phase | Plan | Exit evidence | State | +|---|---|---|---| +| 0 — Repo-local manifests + CI drift gates | [`phase0-plan.md`](phase0-plan.md) | [`phase0-status.md`](phase0-status.md) | Closed 2026-05-10 | +| 1 — Org routing layer (`tools.json` as build output) | [`phase1-plan.md`](phase1-plan.md) | [`phase1-evidence.md`](phase1-evidence.md) | Closed 2026-05-10 | +| 2 — Tier-2 + tier-3 onboarding | (folded into Phase 1) | — | Closed 2026-05-10 | +| 3 — Recipes + discovery handshake | [`phase3-plan.md`](phase3-plan.md) | [`phase3-evidence.md`](phase3-evidence.md) | Closed 2026-05-11 | +| 4 — MCP server (`m-dev-tools-mcp`) | [`phase4-plan.md`](phase4-plan.md) | [`phase4-evidence.md`](phase4-evidence.md) | Closed 2026-05-11 | + +Phase 0 used a different naming convention (`-status.md` instead of +`-evidence.md`). The convention stabilized starting Phase 1 — both +later phases write a single `phase-evidence.md` file that cites +each done-criterion green. + +## What this directory is NOT + +- The framework itself. That's `profile/tools.json`, + `profile/task_index.json`, `profile/*.schema.json`, and + `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. diff --git a/docs/current-state-inventory-priority.md b/docs/ai-discoverability/current-state-inventory-priority.md similarity index 100% rename from docs/current-state-inventory-priority.md rename to docs/ai-discoverability/current-state-inventory-priority.md diff --git a/docs/phase0-plan.md b/docs/ai-discoverability/phase0-plan.md similarity index 100% rename from docs/phase0-plan.md rename to docs/ai-discoverability/phase0-plan.md diff --git a/docs/phase0-status.md b/docs/ai-discoverability/phase0-status.md similarity index 100% rename from docs/phase0-status.md rename to docs/ai-discoverability/phase0-status.md diff --git a/docs/phase1-evidence.md b/docs/ai-discoverability/phase1-evidence.md similarity index 100% rename from docs/phase1-evidence.md rename to docs/ai-discoverability/phase1-evidence.md diff --git a/docs/phase1-plan.md b/docs/ai-discoverability/phase1-plan.md similarity index 100% rename from docs/phase1-plan.md rename to docs/ai-discoverability/phase1-plan.md diff --git a/docs/phase3-evidence.md b/docs/ai-discoverability/phase3-evidence.md similarity index 100% rename from docs/phase3-evidence.md rename to docs/ai-discoverability/phase3-evidence.md diff --git a/docs/phase3-plan.md b/docs/ai-discoverability/phase3-plan.md similarity index 100% rename from docs/phase3-plan.md rename to docs/ai-discoverability/phase3-plan.md diff --git a/docs/phase4-evidence.md b/docs/ai-discoverability/phase4-evidence.md similarity index 100% rename from docs/phase4-evidence.md rename to docs/ai-discoverability/phase4-evidence.md diff --git a/docs/phase4-plan.md b/docs/ai-discoverability/phase4-plan.md similarity index 100% rename from docs/phase4-plan.md rename to docs/ai-discoverability/phase4-plan.md diff --git a/docs/recipes/README.md b/docs/recipes/README.md index c72e85e..de76de1 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -56,8 +56,8 @@ Frontmatter contract: ## The seven priority recipes -Per [`AI-discoverability-plan.md` §5.1](../AI-discoverability-plan.md) and -the [Phase-3 implementation plan](../phase3-plan.md): +Per [`AI-discoverability-plan.md` §5.1](../ai-discoverability/AI-discoverability-plan.md) and +the [Phase-3 implementation plan](../ai-discoverability/phase3-plan.md): | # | Slug | Tier | Phase-3 status | What it proves | |---|---|---|---|---| @@ -69,7 +69,7 @@ the [Phase-3 implementation plan](../phase3-plan.md): | 6 | `investigate-failure` | tier-2 | **post-exit** | Standard triage path when `m test` is red | | 7 | `add-editor-support` | tier-3 | **post-exit** | Extend the VS Code extensions with a new file association / setting | -Phase-3 exit per [`phase3-plan.md`](../phase3-plan.md): at least **4 of +Phase-3 exit per [`phase3-plan.md`](../ai-discoverability/phase3-plan.md): at least **4 of the 7** are written + executable + CI-verified. Recipes 1–4 are the exit set; #5 is buffer; #6 + #7 land after Phase 3 closes. @@ -114,10 +114,11 @@ follow to recipe → run recipe → assert exit code. ## What this directory is NOT -- A general documentation tree. That's [`../`](../) — for plans, - guides, and history. +- A general documentation tree. That's [`../ai-discoverability/`](../ai-discoverability/) + (plans + evidence + the parent guide) and [`../history/`](../history/) + (archived prose). - A test corpus. That's `m-modern-corpus` (and, by reach, the VistA corpus surfaced via `tree-sitter-m`). - A tutorial. Recipes are mechanically-runnable; tutorials are prose that explains why. The user-facing guide lives in - [`../AI-discoverability-guide.md`](../AI-discoverability-guide.md). + [`../ai-discoverability/AI-discoverability-guide.md`](../ai-discoverability/AI-discoverability-guide.md).