@aidemd-mcp/server 0.2.0

package/.aide/intent.aide

@@ -0,0 +1,256 @@
+---
+scope: .
+intent: >
+  This repository is the canonical home of the AIDE methodology — Autonomous
+  Intent-Driven Engineering, with a deliberate second reading as AI Domain
+  Expert — and the MCP server that delivers it to agents in host projects.
+  Intent is the primary driver: a `.aide` intent doc governs the code, and a
+  research agent plays the role of the human domain expert an engineering
+  team would otherwise need to hire. The repo has two jobs: author the
+  canonical docs, and ship them through the MCP handshake and aide_init.
+  Success is an agent in a brand-new host project receiving the full
+  methodology via tooling alone, then working intent-first — describing what
+  it wants in cascading layers of abstraction and letting the agent turn
+  those layers into code. Full autonomy through intent-driven development,
+  with AI domain experts filling the expertise gap, is the north star every
+  other decision in this repo must serve.
+outcomes:
+  desired:
+    - >-
+      The canonical AIDE methodology — spec, template, progressive disclosure,
+      agent-readable code, automated QA — lives in this repo as editable doc
+      files and is the single source of truth. Editing those files is the
+      only way to change what downstream host projects receive.
+    - >-
+      Two delivery channels, each with one clear job: MCP tool descriptions
+      teach AIDE at handshake time; aide_init installs a short pointer stub
+      into the host's config file, lands the progressively-disclosed
+      methodology doc hub onto the host's disk, scaffolds pipeline slash
+      commands, wires the MCP server into the host project, and configures
+      IDE preview. Together they cover the full lifecycle from handshake
+      to steady-state work. The stub-plus-hub shape of the methodology
+      delivery is load-bearing: every session in the host pays the stub
+      cost on every read of the config file, but pays the full doctrine
+      cost only when the task actually touches `.aide` files. Progressive
+      disclosure applies at the delivery layer, not just inside the docs.
+    - >-
+      Every downstream artifact the server ships — tool descriptions,
+      host-installed pointer stubs, host-installed methodology docs,
+      slash command templates — is composed from the canonical doc
+      files at build or init time, never duplicated as an inline string
+      or hardcoded template.
+    - >-
+      A host project that runs aide_init once is AIDE-ready: the installing
+      agent did not have to paraphrase, remember, or quote any AIDE rules to
+      get there, because the tooling carried the full methodology into the
+      project.
+    - >-
+      The repo itself exemplifies AIDE because the server is written using
+      it: progressive disclosure in the folder tree, agent-readable names,
+      `.aide` specs next to orchestrators, decisions-not-descriptions in
+      every spec. Cascading intent at every level, so a contributor can
+      write a new submodule spec by inheritance without re-deriving the
+      rules.
+  undesired:
+    - >-
+      A rule, convention, or doctrine that lives anywhere other than the
+      canonical doc files — a commit message, a README, a code comment, a
+      per-project CLAUDE.md edit. If the change is not in the canonical
+      docs, it is not shipped, and it will drift away from whatever the
+      server actually delivers.
+    - >-
+      Dual sources of truth: the same doctrine appearing in both this repo
+      and the original brain notes without one being marked authoritative
+      and the other deleted. Migration from the brain is a one-way move on
+      the same commit.
+    - >-
+      A delivery channel other than MCP tool descriptions and aide_init —
+      a sixth tool that "also explains things," a server-side prompt, a
+      standalone CLI that teaches. Every additional channel fragments the
+      teaching surface and forces agents to guess where to look.
+    - >-
+      A canonical doc that describes behavior the server does not actually
+      deliver. Aspirational docs are worse than missing docs, because
+      missing docs do not lie.
+    - >-
+      A change that makes the cascading-intent model less faithful, less
+      complete, or less teachable — a child spec restating its parent, a
+      parent so narrow that its children have nothing to inherit, a helper
+      with a `.aide` file, an orchestrator without one. These are
+      regressions even when they add features.
+---
+
+## Context
+
+Before this repo existed, the AIDE methodology lived in a personal Obsidian
+vault. That worked for one maintainer but could not ship: every new project,
+every new contributor, every new agent framework had to rediscover the rules
+from a vault they did not have access to, and any CLAUDE.md snippet that
+tried to carry the rules forward went stale the moment the canonical vault
+notes changed.
+
+The MCP handshake is the only documentation surface a compliant MCP client
+is required to present to the model verbatim, in every session, in every
+project, without user action. aide_init is the only command needed to turn
+a cold host project into one that knows AIDE. Together those two channels
+give the methodology a delivery path that does not depend on the agent
+remembering anything across sessions or the user editing any file by hand.
+
+This repo's job is to author the methodology once, hold it as the single
+source of truth, and ship it through those two channels. Nothing else.
+
+## Strategy
+
+**Canonical docs are editable files, not compiled output.** The doc set
+lives in this repo as plain Markdown the maintainer can read, diff, and
+edit. Every downstream artifact — tool descriptions, methodology blocks,
+slash command templates — is composed from those files at build or init
+time. A doctrine change is one edit in one file; propagation to every
+downstream host project is automatic on their next init. If a maintainer
+ever has to edit two places to ship one change, the source-of-truth
+invariant has been broken and must be repaired, not worked around.
+
+**Two delivery channels, no third.** MCP tool descriptions teach AIDE at
+handshake time: what `.aide` files are, where they live, the naming rules,
+the read-before-code workflow. aide_init installs the rest: a short
+pointer stub into the host's config file, the full canonical methodology
+doc set into a dedicated host-side doc hub the stub points at, the slash
+commands that run the pipeline, the MCP wiring, and the IDE preview. The
+two channels are cleanly partitioned — handshake teaches concepts, init
+installs artifacts — and between them they cover the lifecycle an agent
+in a host project actually walks. Any proposal to add a third channel
+should be rejected and redirected into improving one of the existing two.
+
+**Methodology delivery honors progressive disclosure at the delivery
+layer.** The agent reads the host's config file on every session, so
+that surface carries only a short stub that names the installed doc hub
+and teaches the crawl trigger. The full canonical methodology lands as
+files on the host's disk, read on demand by sessions that actually touch
+`.aide` material. This mirrors what the user's global `study-playbook`
+skill does against the brain — a shallow pointer surface naming a deep
+content surface, with the agent crawling only when the task requires it.
+Shipping the full methodology body inside the stub region violates the
+pattern the methodology itself teaches, which is exactly the regression
+this architecture exists to prevent.
+
+**The repo eats its own dog food.** The MCP server is written using AIDE.
+Progressive disclosure in the folder tree, folders named after their
+default exports, JSDoc on every function, inline narration only on
+orchestrators, `.aide` specs next to orchestrators and nowhere else,
+decisions-not-descriptions in every spec. This is not stylistic — it is
+the forcing function. A rule that is wrong or unworkable shows up as
+pain in this repo before it ships to a host project. If a rule can't
+survive being lived under here, it doesn't belong in the canonical docs.
+
+**Migration from the brain is one-way.** Every doc that lands in this
+repo is deleted or archived from the brain on the same commit. Drift
+between two copies of a canonical doc is the worst kind of drift,
+because it silently propagates to every host project on its next init
+and no one notices which copy is authoritative.
+
+**Intent-driven development is the measurement.** Every change to this
+repo — a new doc, a new tool, a revised description, a refactored helper
+— is evaluated against one question: does this make "describe what you
+want in cascading layers of abstraction, let the agent build the code"
+more real or less real? A feature that adds surface but doesn't move that
+needle is a regression in disguise. A change that tightens the cascading
+intent model is load-bearing even when it looks like cleanup.
+
+## Good examples
+
+A maintainer edits `docs/aide-spec.md` to clarify how outcomes cascade
+from parent to child specs. They commit. On the next release, every
+host project that runs `aide_init` sees the updated text land inside
+its own `.aide/aide-spec.md` — the host-side doc hub contains a
+byte-faithful copy of the canonical doc, so the edit reaches every
+host project on its next init with no duplication anywhere in between.
+Every agent that connects to the MCP server also sees the updated tool
+descriptions (in whichever tools the rule touched), because those
+descriptions were composed from the same doc file at build time. One
+edit in one file, full propagation, zero paraphrasing, and the stub
+inside each host's config file keeps pointing at the same hub path it
+always did.
+
+An agent in a cold host project is told only "run aide_init." It does,
+reads back a summary naming the pointer stub in the config file, the
+installed host-side doc hub with every canonical methodology doc by
+name, the pipeline slash commands, the MCP registration, and the
+IDE configuration, and then starts the pipeline with `/aide:research`.
+At no point in that sequence did a human tell the agent what AIDE is,
+what a `.aide` file is, or how the phases fit together — every piece
+came through the tooling.
+
+An agent opens a host project to implement a new feature unrelated to
+AIDE. Its first read is the host's config file, which contains a short
+pointer stub saying AIDE exists, naming the doc-hub path, and telling
+the agent to crawl the hub before writing or acting on any `.aide`
+file. The agent notes this, skips the hub for now because the task
+touches no specs, and proceeds with the feature work carrying only a
+handful of lines of AIDE context. An hour later, the same agent picks
+up a task that does touch a `.aide` file; it follows the stub's
+pointer into the hub, reads the hub index, drills into `aide-spec.md`
+and `aide-template.md`, and leaves the three canonical docs its task
+does not need unread. The delivery layer practiced the same
+progressive disclosure the methodology teaches — exactly the way the
+user's global `study-playbook` skill crawls the brain on demand
+instead of hoisting it into every session.
+
+A contributor adds a new tool to the MCP server. They read `/.aide`,
+narrow to `src/.aide`, narrow to their new submodule spec, and know
+exactly which invariants their addition must honor: five-tool cap, client
+parity, idempotency, progressive disclosure in the code, cascading intent
+in the spec. Three reads, full contract, no source files opened.
+
+## Bad examples
+
+A doctrine change that lands as a one-liner in a host project's CLAUDE.md
+after a maintainer "noticed something while using AIDE in production."
+The host project is correct for a week. The canonical docs in this repo
+still reflect the old rule. The next host project that runs aide_init
+receives the old rule because aide_init reads from the canonical docs,
+and the two projects now diverge invisibly. The fix is to land the
+change in this repo first and let it flow outward, not to patch the edge
+and forget to come back.
+
+A `writeMethodology/` helper that builds its output by concatenating
+hardcoded string literals instead of reading `docs/aide-spec.md`. The
+canonical doc and the shipped methodology drift apart on the first edit
+to either one, and a maintainer updating the doc has no way to know
+their change did not ship. The repo has two sources of truth and
+neither is marked authoritative.
+
+An `aide_init` that skips the doc-hub step and dumps the full
+concatenated methodology body inside the host's config file, the way
+it used to before this architecture was locked in. The agent pays the
+full doctrine cost on every read of the config file, the doctrine
+crowds out the host's own content, and the methodology's own
+progressive-disclosure rule is violated by the very tool whose job
+is to install it. The refactor passed its tests and broke the
+invariant it was supposed to enforce.
+
+A pointer stub that names a host-side doc-hub path at `.aide/` while
+the installer writes the hub into `aide/` (or any other mismatch of
+the same shape). The agent reads the stub, follows the pointer, and
+lands on a missing directory. The two sides were coincident string
+literals instead of a single shared path source, and the refactor
+shipped with its most load-bearing invariant broken at compile time.
+
+A proposal for `aide_explain`, a sixth tool that "walks an agent through
+the methodology interactively." The teaching surface now has three
+channels — handshake, init, explain — and an agent calling explain is an
+agent the tool descriptions failed to teach. The correct response is to
+fix the tool descriptions, not to add a channel that papers over their
+weakness.
+
+A canonical doc that introduces a new pipeline phase — say, "review" —
+without aide_init scaffolding an `/aide:review` slash command to match.
+Agents read the methodology, look for the command, can't find it, and
+conclude the system is incomplete. The doc was aspirational; the tooling
+was real; they disagreed; the agent trusted the tooling and lost trust
+in the doc.
+
+A child `.aide` that opens with "this repo is the canonical home of
+AIDE…" — a verbatim restatement of this spec's intent paragraph. The
+child has earned nothing by copying; every token spent restating is a
+token the child could have used to say what only it can say. Cascading
+intent failed because the child didn't cascade.

package/.aide/plan.aide

@@ -0,0 +1,169 @@
+---
+intent: >
+  Bring the aidemd-mcp codebase into alignment with the canonical docs updated
+  in c32e887: five file types (adding plan), seven phase commands (adding
+  synthesize) plus the /aide orchestrator, seven canonical docs plus index
+  (adding plan-aide.md and todo-aide.md), todo.aide redefined as a QA
+  re-alignment document, and discover tags including [plan].
+---
+
+## Plan
+
+- [x] **Step 1 — src/types/index.ts line 2: expand AideFileType union.**
+      Change `"intent" | "research" | "todo"` to `"intent" | "research" | "todo" | "plan"`.
+      Update the JSDoc comment on line 1 from "The three spec types plus QA checklist"
+      to "The four spec types plus QA re-alignment document" (or equivalent wording
+      that reflects five file types total with plan included). No other changes in
+      this file.
+
+- [x] **Step 2 — src/util/classify/index.ts line 12-17: add plan.aide classification branch.**
+      Add a branch `if (base === "plan.aide") return "plan";` before the final
+      `return "intent"` fallback. Update the JSDoc on the function (lines 7-11) to
+      list all five patterns: `.aide` or `intent.aide` -> "intent", `research.aide` ->
+      "research", `todo.aide` -> "todo", `plan.aide` -> "plan". Order the branches
+      so the specific named files are checked before the catch-all intent return:
+      research, todo, plan, then fallback to intent.
+
+- [x] **Step 3 — src/tools/discover/buildTree/index.ts line 5: add plan to TYPE_ORDER.**
+      Change `{ intent: 0, research: 1, todo: 2 }` to
+      `{ intent: 0, research: 1, plan: 2, todo: 3 }`. Plan sorts after research
+      (it is the architect's artifact derived from the intent) and before todo
+      (which is the QA artifact). Update the JSDoc on line 4 to read:
+      "Sort priority for file types: intent first, then research, plan, then todo."
+      Also update the tree-rendering JSDoc on buildTree (line 34) to include `[plan]`
+      in the tag list: `[intent]`, `[research]`, `[plan]`, `[todo]`.
+
+- [x] **Step 4 — src/tools/scaffold/index.ts: add plan type and template.**
+      4a. Line 8: change the Zod enum from `["intent", "research", "both", "todo"]` to
+      `["intent", "research", "both", "todo", "plan"]`. Update the `.describe()` text
+      to mention plan.
+      4b. Add a `PLAN_TEMPLATE` constant after the existing `TODO_TEMPLATE` (after
+      line 43). Content should match the plan.aide spec format from
+      `.aide/docs/plan-aide.md` — a minimal scaffold with frontmatter `intent` field
+      and `## Plan` / `## Decisions` body sections:
+      ```
+      ---
+      intent: >
+
+      ---
+
+      ## Plan
+
+      - [ ]
+
+      ## Decisions
+
+      ```
+      4c. Line 67: change the `type` parameter signature from
+      `"intent" | "research" | "both" | "todo"` to
+      `"intent" | "research" | "both" | "todo" | "plan"`.
+      4d. Add a `plan` branch in the `if/else` chain (after the `todo` branch,
+      before `intent`). It should mirror the todo branch exactly in structure:
+      create `plan.aide` in the target directory using `PLAN_TEMPLATE`, push
+      action "Created plan.aide". Plan is orthogonal to intent/research naming
+      — no rename logic needed.
+      4e. Update the function-level JSDoc (lines 56-63) to document the new
+      `type=plan` branch: "type=plan -> creates plan.aide".
+
+- [x] **Step 5 — src/tools/init/initContent/index.ts: add plan-aide, todo-aide docs
+      and synthesize + aide orchestrator command entries.**
+      5a. DOC_PATHS (lines 34-47): add two methodology doc entries:
+      `"plan-aide": ".aide/docs/plan-aide.md"` and
+      `"todo-aide": ".aide/docs/todo-aide.md"`.
+      Add two command entries:
+      `"commands/aide/synthesize": ".claude/commands/aide/synthesize.md"` and
+      `"commands/aide/aide": ".claude/commands/aide.md"` (the orchestrator lives
+      at the commands root as `aide.md`, not inside the `aide/` subfolder — check
+      that the path `.claude/commands/aide.md` resolves correctly relative to
+      REPO_ROOT).
+      Note: the orchestrator canonical template is at `.claude/commands/aide.md`
+      which is a peer of the `aide/` folder, not inside it.
+      5b. METHODOLOGY_DOCS (lines 71-78): append two entries to the array:
+      `{ canonical: "plan-aide", hostFilename: "plan-aide.md" }` and
+      `{ canonical: "todo-aide", hostFilename: "todo-aide.md" }`.
+      These go after the existing `automated-qa` entry and before the closing
+      bracket. Keep insertion order matching the hub index reading order.
+
+- [x] **Step 6 — src/tools/init/scaffoldCommands/index.ts: add synthesize command
+      and /aide orchestrator.**
+      6a. COMMANDS array (lines 30-37): add the synthesize phase command entry:
+      `{ canonical: "commands/aide/synthesize", hostPath: "aide/synthesize.md", displayName: "aide:synthesize" }`.
+      Insert it between the `spec` entry and the `plan` entry to match pipeline
+      order: research, spec, synthesize, plan, build, qa, fix.
+      6b. Add the `/aide` orchestrator command entry:
+      `{ canonical: "commands/aide/aide", hostPath: "aide.md", displayName: "aide" }`.
+      **Important**: the orchestrator's `hostPath` is `"aide.md"` (at the command
+      directory root), NOT `"aide/aide.md"` (inside the subfolder). It is a peer
+      of the `aide/` subfolder. Place it as the first entry in the COMMANDS array
+      so it is installed and reported before the seven phase commands.
+      6c. Update the JSDoc comment on lines 9-25: change "six AIDE pipeline slash
+      commands" to "seven AIDE pipeline phase commands plus the /aide orchestrator
+      entry point". Explain that the orchestrator is installed as `aide.md` at
+      the command directory root (a peer of `aide/`), while phase commands go
+      inside `aide/`. Update any references to "six" or "six-phase cap" to
+      reflect the new count.
+
+- [x] **Step 7 — src/index.ts: update stale tool description strings.**
+      7a. `aide_discover` description (lines 34-35): where it lists file types,
+      add the plan.aide type. The current text lists four types (.aide, intent.aide,
+      research.aide, todo.aide). Add between research.aide and todo.aide:
+      `- plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.`
+      Also update the count text from "File types:" (which implies four) to
+      explicitly name all five. Update the description of todo.aide from
+      "QA checklist. Issues found by audit agents." to
+      "QA re-alignment document. Captures where implementation drifted from intent."
+      7b. `aide_read` description (line 50): change the parenthetical
+      `(intent/research/todo)` to `(intent/research/plan/todo)`.
+      7c. `aide_scaffold` description (lines 64-65): add `plan` to the Types list.
+      Add a line: `- plan -- Architect's implementation plan (no naming interaction
+      with intent/research)`. Also update the todo description from
+      "QA checklist for audit agents" to
+      "QA re-alignment document for QA agents".
+      Update the Zod enum in the inputSchema (line 75) from
+      `["intent", "research", "both", "todo"]` to
+      `["intent", "research", "both", "todo", "plan"]`.
+      7d. `aide_init` description (lines 98-99): update the text that says
+      "scaffolds slash commands for every pipeline phase (research, spec, plan,
+      build, QA, fix)" to include synthesize:
+      "scaffolds slash commands for every pipeline phase (research, spec,
+      synthesize, plan, build, QA, fix) plus the /aide orchestrator entry point".
+      Also ensure the methodology doc hub description mentions "seven canonical
+      methodology docs" (not five or six). Update "six pipeline slash commands"
+      references to "seven pipeline phase commands plus the /aide orchestrator".
+
+## Decisions
+
+**plan sorts between research and todo in TYPE_ORDER.** Plan is the architect's
+artifact that follows research synthesis and precedes implementation + QA. This
+matches the pipeline ordering: research -> synthesize -> plan -> build -> qa.
+Todo is the QA output that comes last in the lifecycle.
+
+**The orchestrator /aide is a COMMANDS entry, not a separate mechanism.** The
+scaffoldCommands helper already handles idempotent command installation. The
+orchestrator is just another command file with a different hostPath (command
+directory root instead of aide/ subfolder). Adding it to the same COMMANDS array
+avoids a second installation path and keeps reporting consistent.
+
+**The orchestrator entry goes first in the COMMANDS array.** Pipeline reporting
+order should show the entry point before the phases it routes to. This matches
+the init spec's good-example output where `aide:` appears before `aide/research:`.
+
+**PLAN_TEMPLATE follows the plan.aide spec format, not the intent template format.**
+The plan.aide canonical spec defines frontmatter with `intent` only, plus
+`## Plan` and `## Decisions` body sections. The scaffold template mirrors this
+structure with empty placeholders, same as the TODO_TEMPLATE mirrors the todo
+format.
+
+**No changes to aide_validate or aide_read.** Both tools work off the
+AideFileType union and classifyFile, which are being updated in steps 1-2.
+They will automatically handle plan.aide files once the type system includes
+"plan". No tool-specific changes needed.
+
+**The "commands/aide/aide" canonical name uses `aide` as both namespace and
+basename.** This looks redundant but is mechanically correct: the canonical
+name prefix `commands/aide/` means "lives under .claude/commands/aide/" in
+the repo, and `aide` is the bare filename. The hostPath `aide.md` (without
+the `aide/` prefix) is what places it at the command directory root on the
+host side. The asymmetry between canonical path and host path is intentional
+— the canonical source lives inside the aide/ folder in the repo, but the
+host install places it as a peer of that folder.

package/.aide/todo.aide

@@ -0,0 +1,47 @@
+---
+intent: >
+  Canonical docs updated in c32e887 (orchestrator, synthesize phase, plan.aide
+  spec, todo.aide spec, expanded file-type table, seven-doc hub) but downstream
+  .aide intent specs still reference the pre-commit state: four file types
+  instead of five, six pipeline commands instead of seven-plus, five canonical
+  docs instead of seven, and todo.aide described as a "QA queue" instead of a
+  re-alignment document. The specs no longer faithfully reflect the methodology
+  they are supposed to deliver.
+misalignment:
+  - implementation-drift
+---
+
+## Issues
+
+- [x] **src/.aide:21** — Teaches "the four file types" in tool descriptions; canonical `aide-spec.md` now defines five file types (`.aide`, `intent.aide`, `research.aide`, `plan.aide`, `todo.aide`).
+      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
+
+- [x] **src/.aide:149-152** — Good example describes `todo.aide` as "a QA queue". Canonical docs redefine it as a "QA re-alignment document" with misalignment tags and a `## Retro` section.
+      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/init/.aide:33-34** — References "six pipeline slash commands (research, spec, plan, build, qa, fix)". Canonical pipeline now includes a synthesize phase (`/aide:synthesize`) and an orchestrator entry point (`/aide`).
+      Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/init/.aide:194-209** — Good examples list exactly six scaffolded commands and six "already present" lines. Missing synthesize phase; summary shape no longer matches what init actually produces after the doc update.
+      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/init/scaffoldCommands/.aide:1-4** — Intent says "six AIDE pipeline slash commands (research, spec, plan, build, qa, fix)" and enforces a six-cap throughout. The canonical pipeline now has seven phase commands (adding synthesize). The "six-cap" language on lines 20, 81, 114, 116 is all stale.
+      Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/init/installMethodologyDocs/.aide:101** — Context says "five canonical files under `docs/`". The hub index now lists seven docs (added `plan-aide.md` and `todo-aide.md`). The number "five" also appears in the bad-examples section (line 255) and good-examples section (line 198).
+      Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/discover/.aide:23** — Type tags listed as `[intent]`, `[research]`, `[todo]`. Missing `[plan]` tag for the new `plan.aide` file type.
+      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
+
+- [x] **src/tools/scaffold/.aide:1-28** — Supports types: intent, research, both, todo. Does not support `type=plan` for creating `plan.aide` files. The canonical `aide-spec.md` file-type table now includes `plan.aide` as a first-class file type that scaffold should know how to create.
+      Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
+
+## Retro
+
+Every issue traces to a single cause: the canonical docs were updated in one commit but the downstream `.aide` specs that encode the same facts were not updated in the same commit. The commit changed the source of truth; the renderers of that truth were left behind.
+
+What would have caught this earlier:
+- A pre-commit check (or a QA pass scoped to `.aide` files) that runs `aide_validate` and flags specs whose file-type counts, command counts, or doc counts disagree with the canonical docs.
+- A convention that any commit touching `.aide/docs/` also touches every downstream `.aide` that references the changed facts — enforced by review checklist, not tooling, until tooling can do it.
+- The orchestrator `/aide` could have been used to drive the doc change itself, which would have surfaced the propagation gap at the plan stage before code was written.