@drafthq/draft 3.5.3 → 3.7.1

package/core/agents/rca.md

@@ -69,6 +69,7 @@ Before investigating, load and reference the project's big picture documents:
 **Output:** Reproduction confirmed with evidence. Blast radius and SLO impact documented. Investigation scoped to specific module(s).
 
 **Anti-patterns:**
+
 - Starting to read code before reproducing
 - Assuming the bug reporter's diagnosis is correct
 - Investigating the entire system instead of scoping first
@@ -82,18 +83,23 @@ Before investigating, load and reference the project's big picture documents:
 **Techniques (use the most appropriate):**
 
 #### Control Flow Tracing
+
 Follow the execution path from entry point to failure:
-```
+
+```text
 request arrives → handler (file:line)
   → validation (file:line) ✓ passes
   → service call (file:line) ✓ returns data
   → transformation (file:line) ✗ FAILS HERE
 ```
+
 Document each hop with `file:line` references.
 
 #### Data Flow Tracing
+
 Track data transformation through the system:
-```
+
+```yaml
 input: { userId: "abc", role: "admin" }
   → after auth middleware (file:line): { userId: "abc", role: "admin", verified: true }
   → after service layer (file:line): { userId: "abc", role: null } ← DATA LOST HERE
@@ -101,6 +107,7 @@ input: { userId: "abc", role: "admin" }
 ```
 
 #### Differential Analysis (Google SRE Practice)
+
 Compare what works vs. what doesn't:
 
 | Aspect | Working Case | Failing Case | Difference |
@@ -112,8 +119,10 @@ Compare what works vs. what doesn't:
 This narrows the investigation to the specific difference that causes the failure.
 
 #### 5 Whys (Toyota/Google Practice)
+
 Once you find the immediate cause, ask "why" to find the root:
-```
+
+```text
 1. Why did the request fail? → NullPointerException at file:line
 2. Why was the value null? → The cache returned stale data
 3. Why was the cache stale? → The invalidation event was dropped
@@ -125,6 +134,7 @@ Once you find the immediate cause, ask "why" to find the root:
 **Output:** Data/control flow trace with exact code references. Divergence point identified.
 
 **Anti-patterns:**
+
 - Reading code randomly instead of tracing the specific flow
 - Assuming you know the code path without verifying
 - Skipping the "what works" comparison
@@ -149,6 +159,7 @@ Once you find the immediate cause, ask "why" to find the root:
 | 1 | Cache returns stale data when TTL=0 | Unit test with TTL=0 | Should return stale | Returns stale | **Confirmed** |
 
 **If hypothesis fails:**
+
 - Do NOT try a random different fix
 - Record the failed hypothesis (it narrows the search space)
 - Return to Phase 2 with updated understanding

package/core/agents/reviewer.md

@@ -84,6 +84,7 @@ Check against the track's `spec.md`:
    - [ ] Integration points work as specified
 
 **Verdict options:**
+
 - **PASS** — All requirements met, all acceptance criteria verified
 - **PASS WITH NOTES** — All requirements met but minor gaps exist in acceptance criteria verification
 - **FAIL** — Missing requirements or acceptance criteria not met

package/core/agents/writer.md

@@ -37,6 +37,7 @@ You are a technical writer agent. When generating documentation, follow structur
 ### Step 1: Audience Analysis
 
 Before writing, answer:
+
 - Who will read this? (role, experience level)
 - When will they read it? (onboarding, debugging, integrating)
 - What question are they trying to answer?
@@ -45,6 +46,7 @@ Before writing, answer:
 ### Step 2: Information Architecture
 
 Organize content using this hierarchy:
+
 1. **Title** — What is this document about?
 2. **TL;DR** — 1-3 sentence summary for scanners
 3. **Quick Start** — Minimum steps to get started (if applicable)
@@ -71,22 +73,26 @@ Organize content using this hierarchy:
 ## Documentation Modes
 
 ### README Mode
+
 - Audience: New team members, external visitors
 - Structure: What → Why → Quick Start → Architecture Overview → Development → Deployment → Contributing
 - Sources: product.md, tech-stack.md, .ai-context.md, workflow.md
 
 ### Runbook Mode
+
 - Audience: Operators, on-call engineers
 - Structure: Service Overview → Health Checks → Common Issues → Escalation → Recovery Procedures
 - Sources: .ai-context.md (service map), tech-stack.md (infrastructure), incident history
 - Reference: `core/agents/ops.md` for operational mindset
 
 ### API Mode
+
 - Audience: Integrators, frontend developers
 - Structure: Authentication → Endpoints (grouped by resource) → Request/Response Examples → Error Codes → Rate Limits
 - Sources: Code analysis, tech-stack.md (API patterns), existing API tests
 
 ### Onboarding Mode
+
 - Audience: New team members (day 1-5)
 - Structure: Prerequisites → Environment Setup → First Task Walkthrough → Key Concepts → Who to Ask
 - Sources: All draft context files, workflow.md, guardrails.md

package/core/knowledge-base.md

@@ -7,28 +7,33 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 ## Books
 
 ### Architecture & Design
+
 - **Domain-Driven Design** (Eric Evans) — Bounded contexts, ubiquitous language, aggregates, strategic design
 - **Clean Architecture** (Robert Martin) — Dependency rule, boundaries, use cases, separation of concerns
 - **Designing Data-Intensive Applications** (Martin Kleppmann) — Data models, replication, partitioning, consistency, stream processing
 - **Building Evolutionary Architectures** (Ford, Parsons, Kua) — Fitness functions, incremental change, architectural governance
 
 ### Reliability & Operations
+
 - **Release It!** (Michael Nygard) — Stability patterns, circuit breakers, bulkheads, timeouts, failure modes
 - **Site Reliability Engineering** (Google) — SLOs, error budgets, toil reduction, incident response
 - **The Phoenix Project** (Kim, Behr, Spafford) — Flow, feedback, continuous improvement
 
 ### Craft & Practice
+
 - **The Pragmatic Programmer** (Hunt, Thomas, 20th Anniversary ed., 2019) — Tracer bullets, DRY, orthogonality, good enough software
 - **Clean Code** (Robert Martin) — Naming, functions, error handling, code smells
 - **Refactoring** (Martin Fowler, 2nd ed., 2018) — Code smells, refactoring patterns, incremental improvement
 - **Working Effectively with Legacy Code** (Michael Feathers) — Seams, characterization tests, breaking dependencies
 
 ### Microservices & Distribution
+
 - **Building Microservices** (Sam Newman, 2nd ed., 2021) — Service boundaries, decomposition, communication patterns
 - **Microservices Patterns** (Chris Richardson) — Saga, CQRS, event sourcing, API gateway
 - **Enterprise Integration Patterns** (Hohpe, Woolf) — Messaging, routing, transformation, endpoints
 
 ### Testing
+
 - **Growing Object-Oriented Software, Guided by Tests** (Freeman, Pryce) — TDD outside-in, mock objects
 - **Unit Testing Principles, Practices, and Patterns** (Khorikov) — Test pyramid, test doubles, maintainable tests
 
@@ -37,21 +42,25 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 ## Standards & Principles
 
 ### Security
+
 - **OWASP Top 10** — Injection, broken auth, XSS, insecure deserialization, security misconfiguration
 - **OWASP ASVS** — Application Security Verification Standard, security requirements
 - **OWASP Cheat Sheets** — Specific guidance for auth, session management, input validation
 
 ### Design Principles
+
 - **SOLID** — Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion
 - **12-Factor App** — Codebase, dependencies, config, backing services, build/release/run, processes, port binding, concurrency, disposability, dev/prod parity, logs, admin processes
 - **KISS / YAGNI / DRY** — Simplicity, avoiding premature abstraction, avoiding duplication
 
 ### API Design
+
 - **REST Constraints** — Stateless, cacheable, uniform interface, layered system
 - **GraphQL Best Practices** — Schema design, resolvers, N+1 prevention
 - **API Versioning Strategies** — URL, header, content negotiation
 
 ### Cloud Native
+
 - **CNCF Patterns** — Containers, service mesh, observability, declarative configuration
 - **GitOps Principles** — Declarative, versioned, automated, auditable
 
@@ -60,15 +69,19 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 ## Patterns
 
 ### Creational (GoF)
+
 - Factory, Abstract Factory, Builder, Prototype, Singleton
 
 ### Structural (GoF)
+
 - Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy
 
 ### Behavioral (GoF)
+
 - Chain of Responsibility, Command, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor
 
 ### Resilience
+
 - **Circuit Breaker** — Fail fast, prevent cascade failures
 - **Bulkhead** — Isolate failures, limit blast radius
 - **Retry with Backoff** — Transient failure recovery
@@ -76,12 +89,14 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 - **Fallback** — Graceful degradation
 
 ### Data
+
 - **CQRS** — Separate read/write models
 - **Event Sourcing** — Append-only event log as source of truth
 - **Saga** — Distributed transaction coordination
 - **Outbox** — Reliable event publishing
 
 ### Integration (EIP)
+
 - Message Channel, Message Router, Message Translator, Message Endpoint
 - Publish-Subscribe, Request-Reply, Competing Consumers
 - Dead Letter Channel, Wire Tap, Content-Based Router
@@ -91,23 +106,27 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 ## Anti-Patterns to Flag
 
 ### Distributed Systems
+
 - **Fallacies of Distributed Computing** — Network reliability, zero latency, infinite bandwidth, secure network, topology stability, single admin, zero transport cost, homogeneous network
 - **Distributed Monolith** — Microservices with tight coupling
 - **Shared Database** — Services coupled through data
 
 ### Architecture
+
 - **Big Ball of Mud** — No discernible structure
 - **Golden Hammer** — Using one solution for everything
 - **Cargo Cult** — Copying patterns without understanding
 - **Premature Optimization** — Optimizing before measuring
 
 ### Code
+
 - **God Class** — Class doing too much
 - **Feature Envy** — Method more interested in other class's data
 - **Shotgun Surgery** — Changes requiring many small edits across codebase
 - **Leaky Abstraction** — Implementation details bleeding through interface
 
 ### Security
+
 - **Security by Obscurity** — Hiding instead of securing
 - **Trust on First Use** — Accepting unverified credentials
 - **Hardcoded Secrets** — Credentials in source code
@@ -119,9 +138,9 @@ AI guidance during track creation must be grounded in vetted sources. When provi
 When providing guidance, cite sources naturally:
 
 > "Consider CQRS here (DDIA, Ch. 11) — separates read/write concerns which fits your high-read workload."
-
+>
 > "This violates the Dependency Rule (Clean Architecture) — domain shouldn't know about infrastructure."
-
+>
 > "Watch for N+1 queries (common GraphQL pitfall) — use DataLoader pattern."
-
+>
 > "Circuit breaker pattern (Release It!) would help here — fail fast instead of cascading timeouts."

package/core/methodology.md

@@ -9,6 +9,7 @@ Draft is a methodology for Context-Driven Development that ensures consistent, h
 ### The Core Problem
 
 AI coding assistants are powerful but undirected. Without structure, they:
+
 - Make assumptions about requirements
 - Choose arbitrary technical approaches
 - Produce code that doesn't fit the existing codebase
@@ -73,7 +74,7 @@ Draft solves this through **Context-Driven Development**: structured documents t
 
 ### The Constraint Hierarchy
 
-```
+```text
 product.md → "Build a task manager for developers"
   ↓
 tech-stack.md → "Use React, TypeScript, Tailwind"
@@ -93,7 +94,7 @@ Each layer narrows the solution space. By the time AI writes code, most decision
 
 Draft uses a layered context system inspired by memory tiering — see `core/shared/draft-context-loading.md` for the authoritative specification.
 
-```
+```text
 Layer 0: .ai-profile.md (20-50 lines) — Always loaded. Minimum project context.
 Layer 1: .ai-context.md (200-400 lines) — Base context: boundaries, invariants, flows.
 Layer 1.5: draft/graph/*.jsonl — Structural graph (when available).
@@ -145,6 +146,7 @@ graph LR
 ### Keeping AI Constrained
 
 Without constraints, AI will:
+
 1. **Over-engineer** — add abstractions, utilities, "improvements" you didn't ask for
 2. **Assume context** — guess at requirements instead of asking
 3. **Lose focus** — drift across the codebase making tangential changes
@@ -164,6 +166,7 @@ The AI becomes an executor of pre-approved work, not an autonomous decision-make
 **This is Draft's most important feature.**
 
 The workflow:
+
 1. Developer runs `/draft:plan` — AI routes to the right planning workflow, usually `/draft:new-track`
 2. Developer reviews and edits these documents
 3. Developer commits them for peer review
@@ -178,6 +181,7 @@ The workflow:
 | AI decisions are implicit | AI decisions are documented |
 
 **Benefits:**
+
 - **Faster reviews** — Reviewers approve approach, not implementation details
 - **Fewer rewrites** — Catch design issues before code exists
 - **Knowledge transfer** — Specs document *why*, not just *what*
@@ -201,12 +205,14 @@ Draft's artifacts are designed for team collaboration through standard git workf
 ### When to Use Draft
 
 **Good fit:**
+
 - Features requiring design decisions
 - Work that will be reviewed by others
 - Complex multi-step implementations
 - Anything where "just do it" has failed before
 
 **Overkill:**
+
 - One-line bug fixes
 - Typo corrections
 - Exploratory prototypes you'll throw away
@@ -249,6 +255,7 @@ Writing specs feels slower. It isn't.
 | Wrong feature entirely | Days wasted | Caught in review |
 
 The overhead is constant (~20% for simple tasks). The savings scale with:
+
 - **Complexity** — More moving parts = more value from upfront planning
 - **Team size** — More reviewers = more value from documented decisions
 - **Criticality** — Higher stakes = more value from discipline
@@ -306,7 +313,7 @@ Draft works with **Claude Code** (native `.claude-plugin/` support) and **Cursor
 
 ## Core Workflow
 
-```
+```text
 Context → Spec & Plan → Implement
 ```
 
@@ -321,7 +328,7 @@ A **track** is a high-level unit of work (feature, bug fix, refactor). Each trac
 
 Two layouts are supported; both are valid:
 
-```
+```text
 # Single-track project (default) # Multi-track project
 draft/ draft/tracks/<track-id>/
 ├── spec.md ├── spec.md
@@ -387,6 +394,7 @@ Plans are organized into phases:
 ### Task Granularity
 
 Good tasks are:
+
 - Completable in a focused session
 - Have clear success criteria
 - Produce testable output
@@ -534,6 +542,7 @@ Creates a new track (feature, bug fix, or refactor) with a specification and pha
 #### Context Loading
 
 Every new track loads the full project context before spec creation:
+
 - `draft/product.md` — product vision, users, goals, guidelines
 - `draft/tech-stack.md` — languages, frameworks, patterns, accepted patterns
 - `draft/.ai-context.md` — system map, modules, data flows, invariants, security architecture (if exists). Falls back to `draft/architecture.md` for legacy projects.
@@ -555,6 +564,7 @@ New track auto-detects the track type from the description and dialogue:
 #### Specification Creation (Feature)
 
 Engages in dialogue to understand scope before generating `spec.md`:
+
 - **What** — Exact scope and boundaries
 - **Why** — Business/user value
 - **Acceptance criteria** — How we know it's done
@@ -564,6 +574,7 @@ Engages in dialogue to understand scope before generating `spec.md`:
 #### Specification Creation (Bug / RCA)
 
 For bugs, incidents, and Jira-sourced issues. Focused investigation, not broad exploration:
+
 - **Symptoms** — Exact error, affected users/flows, frequency
 - **Reproduction** — Steps to trigger, environment conditions
 - **Blast Radius** — What's broken AND what's not (scopes the investigation)
@@ -575,6 +586,7 @@ The spec is presented for approval and iterated until the developer is satisfied
 #### Plan Creation
 
 Based on the approved spec, generates a phased task breakdown in `plan.md`:
+
 - **Feature tracks:** Tasks organized into phases (Foundation → Implementation → Integration → Polish)
 - **Bug tracks:** Fixed 3-phase structure: Investigate & Reproduce → Root Cause Analysis → Fix & Verify. Includes an RCA Log table for tracking hypotheses.
 - Each task specifies target files and test files
@@ -586,6 +598,7 @@ Also creates `metadata.json` (status tracking) and registers the track in `draft
 #### Track ID
 
 Auto-generated kebab-case from the description:
+
 - Full description converted to lowercase
 - Spaces replaced with hyphens
 - Special characters removed
@@ -620,6 +633,7 @@ Implements tasks from the active track's plan, following the TDD workflow when e
 #### Task Selection
 
 Scans `plan.md` for the first uncompleted task:
+
 - `[ ]` Pending — picks this one
 - `[~]` In Progress — resumes this one
 - `[x]` Completed — skips
@@ -668,6 +682,7 @@ This keeps `/draft:implement` as the common entry point while preserving explici
 #### Phase Boundary Review
 
 When all tasks in a phase are `[x]`, a three-stage review is triggered:
+
 1. **Stage 1: Automated Validation** — Fast static checks (architecture conformance, dead code, circular dependencies, OWASP security, performance anti-patterns)
 2. **Stage 2: Spec Compliance** — Verify all requirements for the phase are implemented
 3. **Stage 3: Code Quality** — Verify patterns, error handling, test quality; classify issues as Critical/Important/Minor
@@ -692,6 +707,7 @@ When all phases complete: update `plan.md`, `metadata.json`, and `draft/tracks.m
 ### `/draft:status` — Show Progress
 
 Displays a comprehensive overview of project progress:
+
 - All active tracks with phase and task counts
 - Current task indicator
 - Module status (if `.ai-context.md` exists) with coverage percentages
@@ -789,6 +805,7 @@ Documents significant technical decisions with context, alternatives, and conseq
 #### When to Use
 
 Create an ADR during or after `/draft:plan` when making architectural decisions:
+
 - Adopting a new technology or framework
 - Changing system architecture or module boundaries
 - Selecting between multiple viable approaches with trade-offs
@@ -799,6 +816,7 @@ Skip ADRs for trivial decisions (variable naming, formatting) or reversible choi
 #### ADR Structure
 
 Each ADR contains:
+
 - **Context** — The issue or forces driving the decision (technical, business, organizational)
 - **Decision** — What we're proposing/doing, stated in active voice ("We will...")
 - **Alternatives Considered** — At least 2 alternatives with pros/cons and rejection rationale
@@ -885,6 +903,7 @@ When graph data exists, baseline review always includes blast-radius / hotspot i
 #### Track-Level Review
 
 Reviews a track's implementation against its spec.md and plan.md:
+
 - **Stage 1 (Automated Validation):** Fast, static checks for structural flaws (dead code, circular dependencies, OWASP secrets, N+1 patterns).
 - **Stage 2 (Spec Compliance):** Verifies all functional requirements and acceptance criteria are met.
 - **Stage 3 (Code Quality):** Evaluates architecture, error handling, testing, and maintainability.
@@ -894,6 +913,7 @@ Extracts commit SHAs from plan.md to determine diff range. Supports fuzzy track
 #### Project-Level Review
 
 Reviews arbitrary changes (static validation + code quality only, no spec compliance):
+
 - `project` — uncommitted changes
 - `files <pattern>` — specific file patterns
 - `commits <range>` — commit range
@@ -963,6 +983,7 @@ Handles mid-track requirement changes without losing work. Analyzes the impact o
 #### When to Use
 
 Use when requirements shift after a track is already in progress:
+
 - A stakeholder changes scope mid-sprint
 - A dependency constraint forces a pivot
 - New information invalidates part of the original spec
@@ -992,6 +1013,7 @@ Use when requirements shift after a track is already in progress:
 Draft supports granular pre-implementation design for complex projects. **Architecture mode is automatically enabled when `draft/tracks/<id>/.ai-context.md` exists** (created by `/draft:decompose`). Falls back to `draft/tracks/<id>/architecture.md` for legacy projects.
 
 **How it works:**
+
 1. Run `/draft:decompose` on a track → Creates `draft/tracks/<id>/architecture.md` (and derived `.ai-context.md`)
 2. Run `/draft:implement` → Automatically detects `architecture.md` and enables architecture features
 3. Features: Story writing, Execution State design, Function Skeletons, ~200-line chunk reviews
@@ -1071,19 +1093,21 @@ Coverage complements TDD — TDD is the process (write test, implement, refactor
 ### When to Use Architecture Mode
 
 **Good fit:**
+
 - Multi-module features with component dependencies
 - New projects where architecture decisions haven't been made
 - Complex algorithms or data transformations
 - Teams wanting maximum review granularity
 
 **Overkill:**
+
 - Simple features touching 1-2 files
 - Bug fixes with clear scope
 - Configuration changes
 
 ### Workflow with Architecture Mode
 
-```
+```text
 /draft:init
      │ (creates draft/architecture.md + draft/.ai-context.md for brownfield)
      │
@@ -1115,6 +1139,7 @@ Sync tracks to Jira via the unified router:
 `/draft:jira preview` → review/edit export → `/draft:jira create`
 
 Story points are auto-calculated from task count:
+
 - 1-2 tasks = 1 point
 - 3-4 tasks = 2 points
 - 5-6 tasks = 3 points

package/core/shared/condensation.md

@@ -4,11 +4,12 @@
 
 ---
 
-This is a self-contained, callable procedure for generating `draft/.ai-context.md` from `draft/architecture.md`. 
+This is a self-contained, callable procedure for generating `draft/.ai-context.md` from `draft/architecture.md`.
 
 **Critical fidelity requirement**: The condensation must faithfully preserve the core operational models (workflows, lifecycles, state machines) from architecture.md §3 "Primary Control & Data Flows", along with invariants (§2) and extension points (§8). These behavioral models are the highest-value content for downstream coding accuracy.
 
 **Mapping (architecture.md → .ai-context.md)** (modern 10-section graph-primary):
+
 - Primary Control & Data Flows (§3) → `## GRAPH:OPERATIONAL` + GRAPH:DATAFLOW (states, transitions, error/recovery paths in compact form)
 - Module & Dependency Map (§4) + hotspots → `GRAPH:MODULE-HOTSPOTS`, `GRAPH:FAN-IN`, `GRAPH:PROTO-MAP` etc.
 - Critical Invariants (§2) → INVARIANTS
@@ -18,14 +19,14 @@ Any skill that mutates `architecture.md` should execute this subroutine afterwar
 
 **Called by:** `/draft:init`, `/draft:init refresh`, `/draft:implement`, `/draft:decompose`, `/draft:coverage`
 
-### Inputs
+## Inputs
 
 | Input | Path | Description |
 |-------|------|-------------|
 | architecture.md | `draft/architecture.md` | Comprehensive human-readable engineering reference (source of truth) |
 | schema.yaml | `draft/graph/schema.yaml` | Graph metrics for tier computation (optional — skip if absent) |
 
-### Outputs
+## Outputs
 
 | Output | Path | Description |
 |--------|------|-------------|
@@ -34,7 +35,7 @@ Any skill that mutates `architecture.md` should execute this subroutine afterwar
 
 **Note:** `.ai-profile.md` generation is a separate step (the Profile Generation Subroutine defined in `skills/init/SKILL.md`). The Condensation Subroutine generates `.ai-context.md` only. Skills that call this subroutine should also trigger profile regeneration if `draft/.ai-profile.md` exists.
 
-### Target Size
+## Target Size
 
 Compute tier from `draft/graph/schema.yaml` after graph build:
 
@@ -55,21 +56,22 @@ If `schema.yaml` does not exist: default to tier 2 (180–280 lines).
 - Below tier minimum: incomplete condensation — ensure all sections are represented
 - Above tier maximum: insufficient compression — apply prioritization rules below
 
-### Procedure
+## Procedure
 
-#### Step 1: Read Source
+### Step 1: Read Source
 
 Read the full contents of `draft/architecture.md`. Extract the YAML frontmatter metadata block — it will be reused (with updated `generated_by` and `generated_at`) for the output file.
 
-#### Step 2: Write YAML Frontmatter
+### Step 2: Write YAML Frontmatter
 
 Start `draft/.ai-context.md` with a stable frontmatter block. Git state is centralized in `draft/metadata.json` — do NOT copy `git.*` or `synced_to_commit` from `architecture.md` into this file. Set:
+
 - `project`: from `architecture.md` frontmatter
 - `module`: from `architecture.md` frontmatter (usually `root`)
 - `generated_by`: the calling command (e.g., `draft:init`, `draft:implement`)
 - `generated_at`: current ISO 8601 timestamp
 
-#### Step 3: Transform Sections
+### Step 3: Transform Sections
 
 Transform each `architecture.md` section into machine-optimized format using this mapping:
 
@@ -86,28 +88,32 @@ Transform each `architecture.md` section into machine-optimized format using thi
 | §9 Graph Coverage Gaps | GRAPH:GAPS | Bullet list of known limitations |
 | §10 Relationship to Other Docs | META:DOCS | Pointer map to authoritative files |
 
-#### Step 3.5: Generate Graph Summary Sections
+### Step 3.5: Generate Graph Summary Sections
 
 If `draft/graph/schema.yaml` exists, generate these sections via live engine queries.
 
 **GRAPH:MODULES** (tier ≥ 2 only):
+
 - Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'` (each has `name`, `node_count`, `fan_in`, `fan_out`)
 - Format: `{name}|{node_count} nodes|fan_in:{fan_in} fan_out:{fan_out}`
 - Order by `node_count` descending
 - Omit this section entirely for tier-1 codebases (≤5 modules) where Component Graph is sufficient
 
 **GRAPH:HOTSPOTS** (all tiers):
+
 - Query: `scripts/tools/hotspot-rank.sh --repo . --top 10`; take top 10 results
 - Format: `{name}|fanIn:{fanIn}` (use `id` for disambiguation when names collide)
 - Always include regardless of tier
 
 **GRAPH:CYCLES** (all tiers):
+
 - Run `scripts/tools/cycle-detect.sh --repo .`; read `.cycles[]` (each is an array of qualified symbol names)
 - Output `None ✓` if empty
 - Otherwise output each cycle on its own line: `"A → B → C → A"`
 - Always include — absence is positive signal that the call graph is acyclic
 
 **GRAPH:MODULE-HOTSPOTS** (tier ≥ 3 only):
+
 - Query: `scripts/tools/hotspot-rank.sh --repo .`; group results by the package segment of each `id` (the qualified name minus the leaf symbol)
 - For each module: take its top 3 symbols by `fanIn`, format as indented lines under the module name
 - Format: `{module}: {name}|fanIn:{N}` with subsequent symbols indented to align
@@ -115,18 +121,20 @@ If `draft/graph/schema.yaml` exists, generate these sections via live engine que
 - Omit modules with no hotspot entries; omit entire section for tier 1–2 (covered by global GRAPH:HOTSPOTS)
 
 **GRAPH:FAN-IN** (tier ≥ 3 only):
+
 - Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, use the `fan_in` field per module
 - Format: `{name}|fanIn:{fan_in}|fanOut:{fan_out}`
 - Order by `fan_in` descending; include only modules with `fan_in ≥ 2`; cap at 15 rows
 - Omit entire section for tier 1–2 (trivially small graph)
 
 **GRAPH:PROTO-MAP** (only when routes are non-empty):
+
 - Query: `scripts/tools/graph-arch.sh --repo . | jq '.routes[]'` (each has `method`, `path`, `handler`)
 - Format: `{method} {path} → {handler}`
 - One line per route
 - Omit entire section if `.routes` is empty — do not write an empty section
 
-#### Step 4: Apply Compression
+### Step 4: Apply Compression
 
 - Remove all prose paragraphs — use structured key-value pairs instead
 - Remove Mermaid syntax — use text-based graph notation (`├─`, `-->`, `-[proto]->`)
@@ -134,7 +142,7 @@ If `draft/graph/schema.yaml` exists, generate these sections via live engine que
 - Abbreviate common words: `fn`=function, `ret`=returns, `cfg`=config, `impl`=implementation, `req`=required, `opt`=optional, `dep`=dependency, `auth`=authentication, `authz`=authorization
 - Use symbols: `@`=at/in file, `->`=calls/leads-to, `|`=column separator, `?`=optional, `!`=required/critical
 
-#### Step 5: Prioritize Content
+### Step 5: Prioritize Content
 
 If the output exceeds the tier maximum, cut sections in this order (bottom = cut first):
 
@@ -154,7 +162,7 @@ If the output exceeds the tier maximum, cut sections in this order (bottom = cut
 | 6 | CONFIG | Can abbreviate to `critical:Y` entries only |
 | 7 (cut first) | VOCAB | Can abbreviate to 10 most important terms |
 
-#### Step 6: Quality Check
+### Step 6: Quality Check
 
 Before writing `draft/.ai-context.md`, verify:
 
@@ -171,16 +179,16 @@ Before writing `draft/.ai-context.md`, verify:
 - [ ] GRAPH:PROTO-MAP present when engine reports non-empty routes (omit entirely if no protos)
 - [ ] YAML frontmatter metadata is present at the top
 
-#### Step 7: Write Output
+### Step 7: Write Output
 
 Write the completed content to `draft/.ai-context.md`.
 
-#### Step 8: Normalise Whitespace
+### Step 8: Normalise Whitespace
 
 After writing both output files, strip trailing whitespace and blank lines at EOF to prevent GitHub upload failures. Resolve the script via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -189,9 +197,10 @@ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
 
 This is idempotent — run it unconditionally.
 
-### Example Transformation
+## Example Transformation
 
 **architecture.md input:**
+
 ````markdown
 ### 4.1 High-Level Topology
 
@@ -208,7 +217,8 @@ flowchart TD
 ````
 
 **.ai-context.md output:**
-```
+
+```text
 ## GRAPH:COMPONENTS
 AuthService
   ├─API: handles HTTP requests
@@ -219,7 +229,7 @@ AuthService
 AuthService.Logic -[PostgreSQL]-> UserDB
 ```
 
-### Reference for Other Skills
+## Reference for Other Skills
 
 Other skills that mutate `draft/architecture.md` should invoke this subroutine with:
 > "After updating `draft/architecture.md`, regenerate `draft/.ai-context.md` using the Condensation Subroutine defined in `core/shared/condensation.md`. If `draft/.ai-profile.md` exists, also regenerate it using the Profile Generation Subroutine defined in `skills/init/SKILL.md`."