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).