@aidemd-mcp/server 0.2.0

package/.aide/docs/automated-qa.md

@@ -0,0 +1,111 @@
+# Automated QA
+
+The verification loop of [AIDE](./aide-spec.md). Spec documents define what correct output looks like — automated QA uses agents to verify that the system's actual output matches those specs, then iteratively fixes drift without human review of every line.
+
+This completes the AIDE cycle: research → spec → plan → implementation → **QA against specs → fix → re-verify**.
+
+## Why This Exists
+
+When an LLM generates prose, emails, reports, or any output governed by a strategy doc, the output drifts from the spec. Prompt changes fix one issue and introduce another. Manual review doesn't scale — you'd need to re-read the strategy and cross-check every line of output after every change.
+
+Automated QA turns the `.aide` specs into a machine-readable rubric. The same specs that drove implementation now drive verification.
+
+## The Two-Phase Pattern
+
+### Phase 1: QA Agent
+
+The QA agent reads the `.aide` specs and the latest generated output, then produces a checklist of issues — each a discrete finding with a file path, line reference, and the spec rule it violates.
+
+**Inputs:**
+
+1. **`.aide` specs** — the spec files that define what correct output looks like
+2. **Generated output** — the actual files the system produced
+3. **Judgement directive** — "use judgement; if it sounds wrong, flag it"
+
+**Output:** a `todo.aide` re-alignment document in the module. See [todo.aide spec](./todo-aide.md) for the full format. Each issue references the spec rule violated, the exact location of the problem, and the pipeline stage where intent was lost.
+
+```yaml
+---
+intent: >
+  Which outcome(s) are violated — the gap between spec and reality.
+misalignment:
+  - implementation-drift
+  - test-gap
+---
+```
+
+```markdown
+## Issues
+
+- [ ] **<output-path>:<line>** — <What's wrong in one line.>
+      Traces to: `outcomes.undesired[1]` | Misalignment: `implementation-drift`
+- [ ] **<output-path>:<line>** — <Next issue, same format.>
+      Traces to: `outcomes.desired[3]` | Misalignment: `test-gap`
+
+## Retro
+
+What would have caught this earlier? Which stage needs strengthening?
+```
+
+**Key constraint:** the QA agent does NOT propose solutions. Solutions bias the implementor toward a specific approach before it reads the spec itself. The checklist says *what's wrong and where* — the implementor, invoked to work the `todo.aide`, decides *how*.
+
+### Phase 2: Implementor in Fix Mode (One Issue Per Session)
+
+The fix loop is not a separate agent — it is the same [implementor](./aide-spec.md#the-agent-pipeline) that executes architect plans, invoked with a narrower scope and a stricter session protocol. One session per unchecked `todo.aide` item, clean context each time. Each session does exactly this:
+
+1. Read the `todo.aide`, find the next unchecked issue
+2. Read the relevant `.aide` specs — the actual strategy, not just the issue description
+3. Implement the fix
+4. Run the generation command to produce fresh output
+5. Compare the new output against the previous output for regressions
+6. Check off the item in the `todo.aide`
+
+Then a **new implementor session** repeats for the next unchecked item.
+
+### Why One-Per-Session
+
+The fix loop is an invocation discipline, not a separate agent. Each fix modifies prompts, templates, or logic that affects all generated output. A single session fixing five issues in sequence can't reliably regression-test — fix #3 might undo fix #1, and the implementor won't notice because it's holding stale assumptions from thousands of tokens ago. The same implementor that executes architect plans in build mode is perfectly capable of executing a single `todo.aide` item in fix mode; what changes is the scope and the protocol, not the agent.
+
+One-per-session means:
+- **Fresh context** — the implementor reads current state, not cached assumptions
+- **Clean diffs** — each fix is one change, one before/after comparison
+- **Regression isolation** — if output gets worse, you know exactly which fix caused it
+
+## Regression Testing
+
+The implementor must verify its change didn't make things worse.
+
+1. Output lives in timestamped folders
+2. Before fixing, the latest folder is the baseline
+3. After fixing, run the generation command — a new timestamped folder appears
+4. Compare the new folder against the baseline
+
+A **positive effect** means the output more closely matches the AIDE specs. A **regression** means the output moved *further* from what the specs require. The implementor checks both the targeted issue and surrounding output for unintended drift.
+
+## The `todo.aide` as Coordination
+
+The `todo.aide` file is the handoff contract between agent sessions:
+
+1. **Work queue** — unchecked items are pending, checked items are done
+2. **Scope boundary** — each agent works exactly one item
+3. **Re-alignment tool** — misalignment tags identify where in the pipeline intent was lost
+4. **Audit trail** — the completed checklist shows what was found and fixed
+5. **Process learning** — the `## Retro` section captures what would have caught issues earlier; the orchestrator promotes retro findings to the brain at `process/retro/` when the fix loop closes
+
+The `todo.aide` lives in the module it audits. When all items are checked off, the QA cycle is complete and retro is promoted to the brain as durable process learning.
+
+## Prerequisites
+
+The pattern requires three things:
+
+1. **`.aide` specs** alongside orchestrator code — the QA agent's source of truth
+2. **A CLI command** that generates output into timestamped folders — so agents can trigger generation and compare runs
+3. **The `todo.aide` convention** — so the checklist has a predictable location
+
+## When to Use
+
+- **LLM-generated prose** — emails, reports, summaries where tone and strategy compliance matter
+- **Prompt engineering iterations** — when tuning prompts, the QA agent catches drift you'd miss reading output manually
+- **Any output governed by AIDE specs** — if a spec defines what correct looks like, an agent can verify against it
+
+Don't use this for code correctness — that's what tests are for. Use it when the output is subjective enough that "does this match the spec?" requires reading comprehension, not assertion checks.

package/.aide/docs/cascading-alignment.md

@@ -0,0 +1,107 @@
+# Cascading Alignment
+
+The AIDE intent tree is a hierarchy of `.aide` specs: root intent at the top, module specs below, submodule specs below those. Intent flows downward — each child spec narrows the intent of its parent. Without explicit verification, a child spec could contradict a parent's undesired outcomes and the drift would go unnoticed until QA fails in a confusing way — or worse, the implementation faithfully serves a child intent that violates the root intent. This is the **cascading alignment problem**: specs multiply and drift between levels can accumulate silently.
+
+Cascading alignment is the protocol that detects and surfaces that drift. It separates **spec-vs-spec verification** from **code-vs-spec verification** (which is QA's job) and gives the spec-vs-spec job to a dedicated agent — the aligner.
+
+## The Alignment Problem
+
+Agents in the AIDE pipeline read specs and produce artifacts from them. The architect reads a spec and produces a plan. The implementor reads a plan and produces code. QA reads a spec and verifies code against it. None of these roles require that a spec be internally consistent with its ancestors — they all assume the spec is correct and work from it.
+
+This assumption holds when spec authors rigorously check their work against every ancestor. It fails in practice: specs are written iteratively, outcomes change, new child specs are added without re-reading the full ancestor chain, and no one performs a systematic check. The result is that drift enters the spec tree undetected and persists until a downstream failure makes it visible.
+
+Cascading alignment makes drift visible before code is written.
+
+## The Aligner's Role
+
+The aligner agent performs **spec-vs-spec comparison** — it checks whether a child spec's outcomes are consistent with every ancestor's outcomes. It does not check code. It does not propose fixes. It reads specs, identifies contradictions, and flags the spec that deviated.
+
+**What the aligner checks.** At each child spec, the aligner compares the child's `outcomes.desired` and `outcomes.undesired` against every ancestor's outcomes, looking for:
+
+- **Contradictions** — a child's desired outcome conflicts with an ancestor's undesired outcome, or vice versa
+- **Undermining** — a child narrows its scope in a way that makes an ancestor's outcome unreachable within this branch of the tree
+- **Omissions** — an ancestor has a critical outcome whose scope clearly covers this child, but the child doesn't acknowledge or carry it forward in any form
+
+**What the aligner does not check.** Whether the implementation satisfies the spec — that is QA. The aligner never reads code. It reads specs only.
+
+**Where the aligner flags drift.** Always at the leaf that deviated. If the root spec says "X is a failure mode" and a child spec says "X should always happen," the child is the one that drifted — the flag goes on the child, not the root. The ancestor remains the source of truth; the child carries the misalignment marker.
+
+**What the aligner produces.** At each node where drift is found, the aligner sets `status: misaligned` on the leaf spec's frontmatter and produces a `todo.aide` with concrete items naming the specific conflict — which child outcome conflicts with which ancestor outcome, at which spec path. It never rewrites the spec's intent or outcomes. Realignment items go into `todo.aide` for a human or spec-writer to resolve.
+
+## How the Aligner Walks the Tree
+
+The aligner uses `aide_discover` on the target path to receive the full ancestor chain. It then walks top-down:
+
+1. Load intent and outcomes for each spec in the chain, from root to target
+2. At each child, compare its outcomes against every ancestor's outcomes accumulated so far
+3. When drift is found: set `status: misaligned` on the leaf, produce `todo.aide` at the leaf with items referencing the specific conflict by outcome index and ancestor path
+4. When no drift is found at a node: set `status: aligned` on that spec's frontmatter
+5. Continue down the chain until the target spec is reached
+
+The aligner is invoked via `/aide:align` and reports a verdict (ALIGNED or MISALIGNED), the count of specs checked, the count of misalignments found, and the paths of any `todo.aide` files created.
+
+## The `status` Field Lifecycle
+
+The `status` field in a spec's frontmatter reflects whether alignment has been verified. It has three states:
+
+| State | Value | Set By | Meaning |
+|-------|-------|--------|---------|
+| Pending | *(no field)* | Default | Alignment has not been checked at this node |
+| Aligned | `aligned` | Aligner only | A deliberate full-tree walk found no drift at this node |
+| Misaligned | `misaligned` | Aligner, or QA incidentally | Drift detected — see `todo.aide` for specifics |
+
+**Pending is the default.** A spec with no `status` field has not been checked. This is normal for newly written specs and for specs added after a prior alignment run. The absence of `status` does not mean the spec is correct — it means it has not been verified.
+
+**Aligned requires a deliberate full-tree walk.** Only the aligner can set `status: aligned`, and only after walking the full ancestor chain from root to the target node. An agent that reads a spec and judges it "looks fine" cannot set `aligned` — that is not the same as a systematic comparison against every ancestor's outcomes. The distinction matters because `aligned` carries a specific claim: every ancestor's outcomes were checked, not just the immediate parent's.
+
+**Misaligned is set by the aligner or by QA incidentally.** QA reviews code against spec outcomes. While doing so, it may notice that the spec itself contradicts a parent spec — this is incidental to its primary job. QA can set `status: misaligned` when it observes this contradiction, but it cannot set `aligned`. QA never performs a full tree walk, so it cannot confirm that no drift exists — it can only flag drift it happens to notice.
+
+**Status does not cascade.** When the aligner verifies a parent and sets `status: aligned`, that alignment claim applies to the parent at the time of the check. If a new child spec is added later, the parent's status is not retroactively invalidated — the parent's outcomes didn't change. The new child starts as pending. The next `/aide:align` run will check the new child against its ancestors and set its status accordingly.
+
+## `todo.aide` for Alignment Issues
+
+When the aligner finds drift, it produces a `todo.aide` at the misaligned leaf. The format follows the standard `todo.aide` spec with one alignment-specific constraint: the `misalignment` value is always `spec-gap`.
+
+Alignment issues are definitionally spec-level problems — the spec itself contradicts an ancestor, not the implementation. `spec-gap` is the correct misalignment tag regardless of where in the pipeline the contradiction will eventually cause problems.
+
+Each issue in the `todo.aide` names the specific conflict:
+
+```markdown
+## Issues
+
+- [ ] **Leaf desired outcome #3 conflicts with root undesired outcome #2**
+      Leaf says X should always happen; root spec at `.aide/intent.aide` names X as a failure mode.
+      Traces to: `outcomes.desired[3]` | Misalignment: `spec-gap`
+```
+
+The issue tells a spec-writer exactly what to resolve without telling them how. The aligner never makes the revision itself — it flags and stops.
+
+## Non-Blocking Semantics
+
+`status: misaligned` is informational. It surfaces drift for human or agent judgment; it does not stop the pipeline.
+
+A team may intentionally diverge a child spec from its parent. A child submodule may serve a constrained environment where a parent's desired outcome is not achievable, or where the parent's undesired outcome is intentionally accepted as a tradeoff. The aligner flags the divergence so it is visible — but the team decides whether to resolve it or document it as intentional.
+
+If misalignment blocked the pipeline, intentional divergence would be impossible and every misalignment flag would create an emergency. The flag is a signal, not a gate.
+
+## QA Interaction
+
+QA and the aligner share the `status` field and the `todo.aide` file, but they interact with alignment differently:
+
+**QA sets `misaligned` incidentally.** During code-vs-spec review, QA may notice that a spec it is validating against contradicts a parent spec. This is outside QA's primary scope but worth flagging. QA sets `status: misaligned` and adds a `spec-gap` item to its `todo.aide`. It then continues its code-vs-spec review normally.
+
+**QA never sets `aligned`.** QA reviews code against one spec at a time. It does not walk the full ancestor chain with the intention of confirming spec consistency. Setting `aligned` requires exactly that walk — a claim that every ancestor's outcomes were compared and no drift was found. QA cannot make that claim as a byproduct of code review.
+
+**The aligner is the single source of `aligned` confirmations.** After a QA run sets `misaligned` and a spec-writer resolves the contradiction, the next `/aide:align` run performs the full tree walk and can confirm alignment. Until the aligner runs, the node remains `misaligned` even if the spec-writer believes the fix is complete.
+
+## How Misalignment Is Resolved
+
+The resolution flow is:
+
+1. The aligner runs `/aide:align`, walks the tree, finds drift
+2. The aligner sets `status: misaligned` on the leaf, produces `todo.aide` with specific conflict items
+3. A spec-writer (or the human) reads the `todo.aide`, understands which outcomes conflict, and revises the child spec to align with the ancestor — or documents the divergence as intentional in the spec's `## Context`
+4. `/aide:align` runs again on the same path, walks the tree, confirms no drift remains
+5. The aligner sets `status: aligned` on the node
+
+The aligner never drives step 3. Realignment requires intent judgment — deciding whether to change the child's outcomes, change the ancestor's outcomes (a more consequential change), or accept the divergence as deliberate. That judgment belongs to the spec author, informed by the `todo.aide` the aligner produced.

package/.aide/docs/index.md

@@ -0,0 +1,38 @@
+# AIDE Methodology Doc Hub
+
+- [aide-spec.md](./aide-spec.md)
+- [aide-template.md](./aide-template.md)
+- [plan-aide.md](./plan-aide.md)
+- [todo-aide.md](./todo-aide.md)
+- [progressive-disclosure.md](./progressive-disclosure.md)
+- [agent-readable-code.md](./agent-readable-code.md)
+- [automated-qa.md](./automated-qa.md)
+- [cascading-alignment.md](./cascading-alignment.md)
+
+## Pipeline Agents
+
+AIDE ships eight canonical agents that `aide_init` installs to `.claude/agents/aide/`. Each agent maps to one pipeline role:
+
+| Agent | Model | Phase(s) | Brain Access |
+|---|---|---|---|
+| `aide-spec-writer` | opus | spec | none |
+| `aide-domain-expert` | sonnet | research | write |
+| `aide-strategist` | opus | synthesize | read |
+| `aide-architect` | opus | plan | read (playbook + brain) |
+| `aide-implementor` | sonnet | build, fix | read (playbook) |
+| `aide-qa` | sonnet | qa | none |
+| `aide-aligner` | opus | align | none |
+| `aide-auditor` | opus | refactor | read (playbook + brain) |
+
+The orchestrator (`/aide`) delegates to these agents by name. Each agent gets fresh context per phase — handoff is via files (`.aide`, `plan.aide`, `todo.aide`), not conversation.
+
+## Skills
+
+AIDE ships two canonical skills that `aide_init` installs to `.claude/skills/`:
+
+| Skill | Purpose |
+|---|---|
+| `study-playbook` | Navigate the coding playbook hub top-down to load conventions before writing or reviewing code |
+| `brain` | General-purpose vault access — read the vault CLAUDE.md, follow its navigation rules, fulfill the user's request |
+
+The `aide-architect` and `aide-auditor` agents declare this skill in their frontmatter. Host projects build their own coding playbook in their Obsidian vault; the skill teaches the navigation pattern.

package/.aide/docs/plan-aide.md

@@ -0,0 +1,77 @@
+# plan.aide Spec
+
+The architect's implementation plan. A `plan.aide` lives next to the `.aide` intent spec it implements — same folder, progressive disclosure tells the implementor which intent it serves.
+
+## Format
+
+```yaml
+---
+intent: >
+  One-line summary of what this plan delivers. Mirrors the `.aide` intent
+  but scoped to the concrete work this plan covers — enough for the
+  implementor to know at a glance what they are building.
+---
+```
+
+```markdown
+## Plan
+
+### 1. Step title — self-contained unit
+
+Read: `coding-playbook/structure/modularization`, `coding-playbook/patterns/orchestrator-helper`
+
+- [ ] What to do, which files, what contracts
+
+### 2. Coupled step title — requires shared context
+
+Read: `coding-playbook/testing/unit-tests`
+
+- [ ] 2a. First action in the coupled group
+- [ ] 2b. Second action that depends on 2a's in-memory state
+- [ ] 2c. Third action completing the group
+
+### 3. Another independent step
+
+- [ ] What to do
+
+## Decisions
+
+Architectural choices made during planning: why X over Y, naming rationale,
+tradeoffs accepted. The implementor reads this to understand the reasoning
+without re-deriving it.
+```
+
+## Rules
+
+- **Frontmatter is minimal.** `intent` only. No `status`, no `spec` pointer — the plan lives next to the spec it implements, and progressive disclosure makes the relationship obvious.
+- **Every step gets a checkbox.** The implementor checks each box as it completes during `/aide:build`. Unchecked boxes are pending work; checked boxes are done.
+- **Steps execute top-to-bottom.** Sequencing is the architect's job. The implementor does not reorder, skip, or add steps. If a step is ambiguous, escalate back to `/aide:plan`. Each numbered step is executed by a fresh implementor agent. Lettered sub-steps within a number share a single agent session.
+- **Each numbered step is a unit of delegation.** The orchestrator spawns one fresh implementor agent per numbered step. This means each step must be self-contained: a fresh agent should be able to execute it by reading the plan, the `.aide` spec, and the current code state — without knowing what a prior agent did in-memory. Write steps at a granularity where each one produces a complete, testable change.
+- **Lettered sub-steps for coupled work.** When multiple actions are tightly coupled and cannot be executed independently (e.g., creating a helper and immediately wiring it into the caller), group them as lettered sub-steps under a single number: `1a`, `1b`, `1c`. The orchestrator keeps one agent for all sub-steps of a given number. Use this sparingly — most steps should be independent. If you find yourself lettering more than you're numbering, the steps are too granular.
+- **No implementation code.** No function bodies, no business logic, no algorithms, no worked examples, no copy-paste snippets. Steps describe decisions — file names, contracts, sequencing, reuse. The implementor writes the code and loads conventions directly from the playbook via the step's `Read:` list.
+- **Every step has a Read list.** Each numbered step must open with a `Read:` line listing 1-3 coding playbook notes from the brain that the implementor should read before coding that step. These are the **convention notes** — playbook rules that govern how the implementor writes the code for that step (decomposition, naming, file size, patterns, testing style). The architect already consulted the playbook during planning; the Read list tells the implementor exactly which notes to load so it applies the same conventions. The implementor has direct playbook access via the `study-playbook` skill and will read these notes itself — the architect does not need to encode convention details into the plan text.
+- **Every step traces to intent.** Each step must be traceable back to a line in the `.aide` spec, a rule in the coding playbook, or the [progressive disclosure](./progressive-disclosure.md) conventions (orchestrator/helper pattern, modularization, cascading structure). If a step has no source, cut it or find the rule that justifies it.
+- **Tests are steps.** Every behavior the spec's `outcomes.desired` names gets a corresponding test step in the plan.
+- **Decisions section is not optional.** The architect records *why* each structural choice was made. This prevents the implementor from second-guessing decisions mid-build and prevents future architects from re-debating settled choices.
+- **Read lists are not optional.** The architect consults the playbook during planning and encodes the relevant conventions as a `Read:` list pointing the implementor to the specific playbook notes that govern each step. The implementor has direct playbook access and will load those notes itself. The architect's job is to pick the right notes, not to transcribe their contents into the plan.
+
+## Lifecycle
+
+1. **Created** by the architect agent during `/aide:plan`.
+2. **Presented to the user** for approval before `/aide:build` begins. The orchestrator pauses here.
+3. **Consumed** by the implementor during `/aide:build` — checkboxes track progress.
+4. **Retained** after build completes — the plan is an audit trail of what was decided and why.
+
+## Placement
+
+`plan.aide` lives next to the `.aide` it implements:
+
+```
+src/service/<feature>/
+├── .aide          ← intent spec
+├── plan.aide      ← implementation plan
+├── index.ts
+└── ...
+```
+
+No cross-referencing needed. The folder is the relationship.

package/.aide/docs/plan.aide

@@ -0,0 +1,60 @@
+---
+intent: >
+  Add a References section to the AIDE methodology so the synthesis agent
+  leaves a traceable breadcrumb trail of which brain notes informed each
+  strategy decision. Three file edits: template, methodology doc, agent
+  instructions.
+---
+
+## Plan
+
+### 1. Add `## References` section to the template (`aide-template.md`)
+
+File: `.aide/docs/aide-template.md`
+
+- [x] Inside the fenced template block (lines 15-92), after the `## Bad examples` HTML comment block (which ends at line 91), add a new `## References` section before the closing ```` ```` ```` on line 92.
+- [x] The new section follows the same pattern as the four existing sections: a heading, an HTML comment with guidance for the agent, and a "Delete this entire HTML comment once..." closing instruction.
+- [x] The HTML comment guidance must cover:
+  - Each entry is a bullet: brain note path, then ` -- `, then a one-line description of what was drawn from that note for the Strategy.
+  - Only notes that actually informed a strategy decision belong here. Notes opened but not used are excluded.
+  - Descriptions are breadcrumbs (source + which finding was drawn), not summaries that restate the full finding.
+  - Paths are hints, not contracts. Brain notes move; the description is the fallback. No tooling should validate paths.
+  - This section is populated by the synthesis agent during normal synthesis flow, not added after the fact.
+- [x] Update the numbered instruction list at lines 4-11 (the "How to use this template" section). Step 4 currently names four body sections — add "## References" to the list so it reads five. The guidance for References differs from the other four: the synthesis agent populates it from its reading log rather than replacing a guidance paragraph with authored content. Make this distinction clear in step 4.
+
+### 2. Document the References section in the methodology doc (`aide-spec.md`)
+
+File: `.aide/docs/aide-spec.md`
+
+- [x] In the "Body sections (required)" subsection (line 128-137), add a fifth bullet for `## References` after the `## Bad examples` bullet (line 135). The description must state:
+  - What it contains: a flat list of brain notes the synthesis agent read during strategy writing, each with a path and a one-line description of what was drawn from it.
+  - Its purpose: human auditability — a reviewer can trace every strategy decision back to the research that informed it.
+  - Who populates it: the synthesis agent, as a side effect of normal synthesis.
+  - That paths are not required to be valid links — descriptions are the fallback by design.
+- [x] Update the heading text on line 128 to reflect that there are now five body sections instead of four. The current text reads: "Every spec has the same four body sections." Change "four" to "five" (or reword to avoid a count if that reads better).
+- [x] Update line 89 which currently reads: "Frontmatter is required, and the four body sections below are required." Change "four" to "five" to match.
+- [x] On line 137, the sentence "Additional sections (references, constraints, state machine, etc.) are allowed when the module needs them. These four are the floor." — remove "references" from the parenthetical list (it is no longer an "additional" section, it is a required one) and change "four" to "five".
+- [x] In the agent pipeline section (line 184), where the synthesis instance is described, the current text lists the four body sections it fills: "fills the `.aide` body sections: `## Context`, `## Strategy`, `## Good examples`, `## Bad examples`." Add `## References` to this list.
+
+### 3. Update the synthesis agent instructions (`aide-domain-expert.md`)
+
+File: `.claude/agents/aide/aide-domain-expert.md`
+
+- [x] In the opening role description (line 11), update the list of body sections the agent produces. Current text mentions "Context, Strategy, and examples." Add References to this list.
+- [x] In the "Synthesis Process" section (lines 26-42), add a new step between the current step 7 (Bad examples) and step 8 (Verify traceability). The new step instructs the agent to fill `## References` by logging every brain note it actually used during steps 3-5. Each entry is a bullet with the note's path and a one-line description of what finding was drawn from it for the Strategy. The agent must not list notes it opened but did not use. Descriptions are breadcrumbs, not summaries.
+- [x] Renumber the current step 8 (Verify traceability) to step 9.
+- [x] In the "Return Format" section (lines 44-51), the "Research sources used" bullet already exists. Update its description to clarify that this information now also lives in the spec's `## References` section — the return format summary and the in-spec References section are the same data, just surfaced in two places (one for the caller, one for the reviewer).
+- [x] In the "Input Expectations" section (lines 20-23), no changes needed — the References section requires no new inputs.
+- [x] In the description frontmatter field (line 3), update the parenthetical list of body sections from "(Context, Strategy, Good/Bad examples)" to include References.
+
+## Decisions
+
+**References is a required body section, not an optional additional section.** The spec at aide-spec.md line 137 currently lists "references" as an example of an allowed additional section. Promoting it to required means every spec gets it by default via the template, and the synthesis agent always populates it. This is justified by the intent: if references were optional, the auditability trail would be inconsistent across specs, defeating the purpose of having it.
+
+**Placement after Bad examples, before the closing fence.** The four existing body sections follow a logical progression: Context (why), Strategy (how), Good examples (what success looks like), Bad examples (what failure looks like). References is audit metadata — it supports the Strategy but is not itself strategy content. Placing it last keeps the decision-making sections contiguous and puts the audit trail where a reviewer looks after reading the spec, not before.
+
+**The synthesis agent logs references during synthesis, not as a post-hoc step.** The spec's strategy is explicit: making it a separate step would tempt the agent to reconstruct from memory. The agent instruction update integrates reference-logging into the existing step sequence (after Bad examples, before traceability verification) so it happens while the reading list is still live in context.
+
+**No changes to frontmatter schema.** References is a body section, not a frontmatter field. This keeps the machine-readable contract (scope, intent, outcomes) unchanged and avoids token cost for agents that only need the contract.
+
+**The "How to use this template" instructions distinguish References from the other four sections.** The other four sections require the agent to replace guidance with authored content. References requires the agent to populate from its reading log. The instruction wording must make this distinction clear so agents do not treat the References guidance paragraph as something to overwrite with freeform prose.

package/.aide/docs/progressive-disclosure.md

@@ -0,0 +1,72 @@
+# Progressive Disclosure
+
+Code structured so understanding deepens on demand, not all at once. An agent (or a human) should be able to stop at the shallowest tier that answers its question and only drill deeper when the current tier isn't enough. Every tier is a deliberate layer of documentation built into the code itself — the folder tree, the function signatures, the function bodies.
+
+Agents re-learn the codebase every session. Progressive disclosure is what keeps that re-learning cheap: the less an agent has to read to find what it needs, the more context it has left for the actual task, and the more accurate its output.
+
+## Tier 1 — Folder structure (zero files opened)
+
+The folder tree *is* the high-level architecture. This is the **orchestrator/helper pattern**: the `index.ts` at any level is the **orchestrator** — it imports helpers, coordinates the pipeline, and is the only export. Subfolders are **helpers** — focused, independently testable functions named after what they do. This pattern applies at every layer.
+
+**Aggressive modularization.** Every helper gets its own subfolder with an `index.ts` and a default export. Files are always `index.ts` — never name a file after what it does (that's what the folder name is for). The folder structure *is* the naming system.
+
+```
+src/service/orders/createOrder/
+├── validatePayload/
+│   └── index.ts      ← export default function validatePayload(...)
+├── checkInventory/
+│   └── index.ts      ← export default function checkInventory(...)
+├── reserveStock/
+│   └── index.ts      ← export default function reserveStock(...)
+├── chargePayment/
+│   └── index.ts      ← export default function chargePayment(...)
+├── emitConfirmation/
+│   └── index.ts      ← export default function emitConfirmation(...)
+└── index.ts           ← orchestrator: imports above, reads as the order flow
+```
+
+An agent navigating this tree already knows: this module handles order creation by validating the payload, checking inventory, reserving stock, charging payment, and emitting a confirmation. No files opened.
+
+**Single-helper exception.** When an orchestrator has exactly one helper, it *may* stay in the same file — but this is rare and should be the exception. When it does happen, the helper must be defined **above** the default export, never below. Humans don't hoist; code reads top-down.
+
+The folder shape mirrors the shape of the module — whatever best expresses its composition. It might be a pipeline, a set of strategy variants, a set of resource types, a set of rendering targets, or any other meaningful subdivision. Subfolder names always match the default export they contain.
+
+## Tier 2 — JSDoc on every function (file opened, bodies not read)
+
+Every function carries a JSDoc block — orchestrators *and* helpers, no exceptions. JSDoc explains *why the function exists* and what role it plays, not a restatement of the code.
+
+When folder names aren't enough, an agent opens the orchestrator's `index.ts` and sees the import list plus the JSDoc of each imported helper. That alone is enough to understand the complete data flow without stepping into any helper body. The orchestrator's own JSDoc summarizes the full flow.
+
+JSDoc is non-negotiable because the alternative is an agent reading a function body and *hoping* it inferred the purpose correctly. Signatures alone lie — they tell you the shape of the inputs and outputs but not the intent.
+
+## Tier 3 — Inline step-by-step comments (orchestrators only)
+
+Orchestrator function bodies carry inline comments that narrate the pipeline step by step, so an agent reading the orchestrator sees the sequence of decisions without chasing every helper. Each step in the orchestrator's body is introduced by a short comment describing what this step accomplishes in the larger flow.
+
+Helpers do **not** get step-by-step comments. Their JSDoc plus their focused implementation is enough — if a helper needs narration, it's doing too much and should be split. Helpers earn inline comments only for non-obvious implementation details: a subtle workaround, a cache invalidation reason, a specific ordering constraint. Those are rare.
+
+## Why This Matters
+
+The same property that makes code readable to humans makes it navigable for agents. An agent exploring a codebase can:
+
+1. Read the folder tree → understand architecture
+2. Read orchestrator imports + JSDoc → understand data flow
+3. Read orchestrator body's inline steps → understand sequencing
+4. Drill into a specific helper body only when the task requires it
+
+This eliminates the need for agents to "read the whole codebase" before making changes. The folder structure is the documentation, the function signatures are the documentation, the orchestrator narration is the documentation. Every tier earns its place by saving the agent from reading the tier below it.
+
+## The Rule
+
+Write code so an agent can stop at the shallowest tier that answers its question:
+
+- The orchestrator/helper pattern at every layer
+- Helpers in subfolders, `index.ts` always, folder name = function name
+- `export default` on every module
+- JSDoc on every function
+- Inline narration on orchestrators
+- Drill-in is a last resort, not a default
+
+If you notice a module that would be clearer with a different folder structure — a flat folder that should cascade, a helper that grew into an orchestrator, siblings that share logic begging for a `shared/` lift — flag it. Progressive disclosure only works when the structure stays honest about the shape of the code.
+
+This tier model is one half of the AIDE methodology's code-side contract — the spec ([AIDE Spec](./aide-spec.md)) carries the intent and strategy, the progressively-disclosed code carries the shape and flow.

package/.aide/docs/todo-aide.md

@@ -0,0 +1,77 @@
+# todo.aide Spec
+
+The QA re-alignment document. A `todo.aide` captures where the implementation drifted from canonical intent and provides a structured work queue to bring it back. One `todo.aide` per QA loop, living next to the `.aide` it audits.
+
+## Format
+
+```yaml
+---
+intent: >
+  One-line summary of which `.aide` outcome(s) are violated — the gap
+  between what the spec says and what the code actually produces.
+misalignment:
+  - <where in the pipeline intent was lost — one or more of the values below>
+---
+```
+
+### Misalignment values
+
+Each entry in `misalignment` names the pipeline stage where intent was lost in translation:
+
+| Value | Meaning |
+|-------|---------|
+| `spec-gap` | The intent spec didn't capture something important — a missing outcome, an ambiguous intent, an edge case the spec should have named |
+| `research-gap` | Domain knowledge was incomplete, outdated, or wrong — the brain didn't have what the strategist needed |
+| `strategy-gap` | Strategy didn't account for an edge case or made a decision that doesn't hold under real conditions |
+| `plan-gap` | The architect missed a step, made a wrong structural call, or left ambiguity the implementor had to improvise around |
+| `implementation-drift` | Code deviated from the plan — the implementor made an unauthorized architectural decision or misread a step |
+| `test-gap` | Tests passed but didn't cover the failure mode — green tests, wrong output |
+
+Multiple values are allowed. A single QA run often surfaces issues from different pipeline stages.
+
+## Body
+
+```markdown
+## Issues
+
+- [ ] **path/to/file.ts:42** — What's wrong in one line.
+      Traces to: `outcomes.undesired[1]` | Misalignment: `implementation-drift`
+- [ ] **path/to/file.ts:87** — Next issue, same format.
+      Traces to: `outcomes.desired[3]` | Misalignment: `strategy-gap`
+
+## Retro
+
+What would have caught this earlier? Which stage needs strengthening?
+Specific observations — not generic process advice.
+```
+
+## Rules
+
+- **One `todo.aide` per QA loop.** Each QA run produces a fresh `todo.aide`. If a prior one exists, the QA agent replaces it — checked items from a previous loop are history, not carry-forward.
+- **Each issue gets a checkbox.** The implementor checks it off when the fix lands and no regression is introduced.
+- **Each issue traces to intent.** Every checkbox references which `outcomes` field (desired or undesired) the issue violates. Issues that don't trace to an outcome don't belong in the file.
+- **Each issue names its misalignment.** Per-issue `Misalignment` tags complement the frontmatter-level `misalignment` array. Frontmatter is the summary; per-issue tags are the detail.
+- **No solutions.** The QA agent says *what's wrong and where*. The implementor decides *how* to fix it. Solutions in the todo bias the fixer toward an approach before they've read the spec.
+- **One checkbox per fix session.** The implementor picks the next unchecked item, fixes it in a clean session, and stops. No bundling. See [Automated QA](./automated-qa.md) for the rationale.
+- **Retro is required.** The `## Retro` section captures what would have prevented the misalignment. The orchestrator promotes retro findings to the brain at `process/retro/` when the fix loop closes — durable process learning that future sessions can draw from.
+
+## Placement
+
+`todo.aide` lives next to the `.aide` it audits:
+
+```
+src/service/<feature>/
+├── .aide          ← intent spec
+├── plan.aide      ← implementation plan
+├── todo.aide      ← QA re-alignment
+├── index.ts
+└── ...
+```
+
+## Lifecycle
+
+1. **Created** by the QA agent during `/aide:qa` using `aide_scaffold type=todo`.
+2. **Consumed** by the implementor during `/aide:fix` — one item per session.
+3. **Re-validated** by QA after fixes land — may produce a new `todo.aide` if issues remain.
+4. **Retro promoted** by the orchestrator to `process/retro/` in the brain when all items are checked.
+5. **Retained** in the module as an audit trail.