@drafthq/draft 3.6.0 → 3.7.1

package/skills/change/SKILL.md

@@ -7,7 +7,7 @@ description: Handle mid-track requirement changes. Analyzes impact on completed
 
 You are handling a mid-track requirement change using Draft's Context-Driven Development methodology.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Applying changes to spec.md or plan.md without showing the user what will change first
 - Invalidating `[x]` completed tasks without flagging them explicitly
@@ -38,11 +38,13 @@ Extract from `$ARGUMENTS`:
 ### Default Behavior
 
 If no `track <id>` specified:
+
 - Auto-detect the active `[~]` In Progress track from `draft/tracks.md`
 - If no `[~]` track, find the first `[ ]` Pending track
 - Display: `Auto-detected track: <id> - <name>` before proceeding
 
 If no change description provided:
+
 - Error: "Usage: `/draft:change <description>` or `/draft:change track <id> <description>`"
 
 ---
@@ -73,7 +75,8 @@ For each requirement and acceptance criterion, classify the effect:
 | **Unaffected** | No change needed |
 
 Produce a concise impact list. Example:
-```
+
+```text
 Spec impact:
 - AC #2 "User can export to CSV" → Modified (now also requires JSON format)
 - AC #5 "Export limited to 1000 rows" → Removed (no row limit)
@@ -81,6 +84,7 @@ Spec impact:
 ```
 
 **HLD impact** (only when `hld.md` exists):
+
 - §Architecture / Component Diagram — does the change introduce new modules or alter integration edges?
 - §Detailed Design — does any per-component subsection need updating, or are new components introduced?
 - §Dependencies — new/removed dependent components?
@@ -89,6 +93,7 @@ Spec impact:
 - §Deployment — does the deployment surface change?
 
 **LLD impact** (only when `lld.md` exists):
+
 - §Classes and Interfaces — signatures added/modified/removed?
 - §Data Model — schema changes? New fields? Migration required?
 - §Key Algorithms and Workflows — algorithm changes? New sequence diagrams needed?
@@ -97,7 +102,7 @@ Spec impact:
 
 **Re-approval flag:** If the HLD Approvals table has any signed rows (Date column populated) AND the change touches HLD structural sections (Architecture, Detailed Design, Dependencies, Checklist, IP, Deployment), surface this warning prominently:
 
-```
+```text
 ⚠️ HLD modified after sign-off — Approvals table requires re-circulation.
     Signed rows: [list which roles signed and when]
     Changed sections: [list of HLD sections impacted]
@@ -130,7 +135,7 @@ For each task in `plan.md`, determine if the spec change affects it:
 
 Display a clear summary before proposing any file changes:
 
-```
+```yaml
 Change: [change description]
 Track: <track_id> — <track_name>
 
@@ -178,7 +183,7 @@ Show before/after for each impacted LLD section. Preserve §Approvals verbatim.
 
 ## Step 7: CHECKPOINT
 
-```
+```text
 Apply these changes to spec.md and plan.md? [yes / no / edit]
 ```
 
@@ -208,7 +213,7 @@ Apply these changes to spec.md and plan.md? [yes / no / edit]
 
 4. Announce:
 
-```
+```text
 Changes applied: <track_id>
 
 Updated:
@@ -235,19 +240,22 @@ Next: /draft:implement to continue, or /draft:review to assess current state.
 ## Error Handling
 
 ### Track Not Found
-```
+
+```yaml
 Error: Track '<id>' not found.
 Run /draft:status to see available tracks.
 ```
 
 ### No Active Track
-```
+
+```yaml
 Error: No active track found.
 Use: /draft:change track <id> <description>
 ```
 
 ### No Spec or Plan
-```
+
+```yaml
 Error: Missing spec.md or plan.md for track <id>.
 Cannot perform change analysis without both files.
 ```
@@ -257,11 +265,13 @@ Cannot perform change analysis without both files.
 ## Examples
 
 ### Change description for active track
+
 ```bash
 /draft:change the export format should support JSON in addition to CSV
 ```
 
 ### Targeting a specific track
+
 ```bash
 /draft:change track add-export-feature also require a progress indicator for exports over 500 rows
 ```

package/skills/coverage/SKILL.md

@@ -7,7 +7,7 @@ description: Compute code coverage for active track or module. Targets 95%+ cove
 
 You are computing and reporting code coverage for the active track or a specific module. This complements the TDD workflow — TDD is the process (write test, implement, refactor), coverage is the measurement (how much code do those tests exercise).
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Reporting coverage without actually running the coverage tool
 - Making up coverage percentages
@@ -26,6 +26,7 @@ You are computing and reporting code coverage for the active track or a specific
 5. Check if `draft/tracks/<id>/bughunt-report-latest.md` (track scope) or `draft/bughunt-report-latest.md` (project scope) exists for cross-referencing (see Coverage-Bughunt Cross-Reference below)
 
 If no active track and no argument provided:
+
 - Tell user: "No active track. Provide a path or track ID, or run `/draft:new-track` first."
 
 ## Step 2: Detect Coverage Tool
@@ -54,6 +55,7 @@ If the script is unavailable or returns `framework: unknown`, fall back to the h
 | Ruby | `simplecov` |
 
 **Detection order (fallback path):**
+
 1. Check `tech-stack.md` for explicit testing section
 2. Check config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `setup.cfg`, `pyproject.toml`, `.nycrc`)
 3. Check `package.json` scripts for coverage commands
@@ -62,6 +64,7 @@ If the script is unavailable or returns `framework: unknown`, fall back to the h
 ## Step 3: Determine Scope
 
 **Priority order:**
+
 1. If argument provided (path or module name): use as scope filter
 2. If track has `architecture.md` (or project has `.ai-context.md`) with an in-progress module: scope to that module's files
 3. If active track exists: scope to files changed in the track (use `git diff` against base branch)
@@ -84,6 +87,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 ```
 
 If the script is unavailable or returns `tool: unsupported`:
+
 1. Execute the coverage command. Request machine-readable output when possible: `--json` for Jest, `--cov-report=json` for pytest, `-coverprofile` for Go, `--coverage-output-format json` for dotnet.
 2. Capture full output
 3. If command fails:
@@ -95,7 +99,7 @@ If the script is unavailable or returns `tool: unsupported`:
 
 Parse coverage output and present in a standardized format:
 
-```
+```yaml
 ---
                      COVERAGE REPORT
 ---
@@ -151,7 +155,8 @@ For files below target (using per-module targets when configured — see Per-Mod
    - **Infrastructure** - Framework boilerplate, main entry points. Usually acceptable.
    - **Legacy/Brownfield** - Modules with 0% or very low coverage that need refactoring. Apply Characterization Testing (see below).
 3. **Suggest tests** for testable gaps:
-   ```
+
+   ```text
    SUGGESTED TESTS
    ─────────────────────────────────────────────────────────
    1. Test malformed JWT token handling (jwt.ts:45-52)
@@ -174,7 +179,8 @@ When encountering modules with 0% or very low coverage that need refactoring, do
 5. **Remove approval tests** — Once proper unit test coverage meets the target, retire the Golden Master tests.
 
 **Tool references:**
-- ApprovalTests (https://approvaltests.com/) — available for Java, C#, Python, JS, and more
+
+- ApprovalTests (<https://approvaltests.com/>) — available for Java, C#, Python, JS, and more
 - Verify (.NET) — snapshot testing library
 
 Present characterization testing recommendations in the gap analysis when applicable.
@@ -191,11 +197,11 @@ After measuring line coverage (and branch coverage if applicable), prompt the en
 
 | Language | Tool | Reference |
 |----------|------|-----------|
-| Java | PIT | https://pitest.org/ |
-| JavaScript/TypeScript | Stryker | https://stryker-mutator.io/ |
+| Java | PIT | <https://pitest.org/> |
+| JavaScript/TypeScript | Stryker | <https://stryker-mutator.io/> |
 | Python | mutmut | (Mutation testing tool) |
 | Rust | cargo-mutants | (Mutation testing tool) |
-| C# | Stryker.NET | https://stryker-mutator.io/ |
+| C# | Stryker.NET | <https://stryker-mutator.io/> |
 | Go | go-mutesting | (Mutation testing tool) |
 
 **Reference:** Google's mutation testing program is used by 6,000+ engineers and processes approximately 30% of all code diffs, validating that mutation testing scales to large codebases.
@@ -209,7 +215,8 @@ If a bughunt report exists (`draft/tracks/<id>/bughunt-report-latest.md` or `dra
 1. **Parse bughunt findings** — Extract file paths and line ranges of confirmed or suspected bugs.
 2. **Cross-reference with uncovered code paths** — Identify bughunt findings that fall in uncovered lines.
 3. **Flag as highest-priority test gaps** — Confirmed bugs in uncovered code are the most dangerous gaps. Present them prominently:
-   ```
+
+   ```text
    BUGHUNT CROSS-REFERENCE
    ─────────────────────────────────────────────────────────
    ⚠ CRITICAL: Bug "Race condition in session refresh" (bughunt #3)
@@ -220,6 +227,7 @@ If a bughunt report exists (`draft/tracks/<id>/bughunt-report-latest.md` or `dra
      at src/users/repository.ts:45 — IN UNCOVERED CODE
      → Write a regression test targeting this path
    ```
+
 4. **Prioritize suggested tests** — Tests that cover bughunt-flagged code should appear first in the SUGGESTED TESTS section.
 
 ## Per-Module Coverage Enforcement
@@ -255,7 +263,8 @@ coverage_targets:
 **Classification heuristic:** Infer module risk from directory names and file content when explicit configuration is absent. Flag the inferred classification in the report so the developer can correct it.
 
 In the coverage report, show per-module targets alongside actual coverage:
-```
+
+```text
 PER-FILE BREAKDOWN (module-level targets)
 ---
 src/auth/middleware.ts 96.2% [high_risk: 95%] PASS
@@ -271,6 +280,7 @@ src/generated/api.ts — [generated: excluded]
 **STOP.** Present the full coverage report and gap analysis.
 
 Ask developer:
+
 - Accept current coverage? (if at or above target)
 - Write additional tests for testable gaps?
 - Justify and document acceptable uncovered lines?
@@ -283,17 +293,20 @@ Ask developer:
 After developer approves:
 
 1. **Update plan.md** - Add coverage note to the relevant phase:
+
    ```markdown
    **Coverage:** 96.2% (target: 95%) - PASS
    - Uncovered: defensive null checks in jwt.ts (justified)
    ```
 
 2. **Update architecture context** — update the project-level `draft/architecture.md` with coverage data (not a track-level architecture file), then run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`. The Condensation Subroutine only applies to the project-level `draft/architecture.md` → `draft/.ai-context.md` pipeline:
+
    ```markdown
    - **Status:** [x] Complete (Coverage: 96.2%)
    ```
 
 3. **Update metadata.json** - Add coverage field if not present:
+
    ```json
    {
      "coverage": {
@@ -307,6 +320,7 @@ After developer approves:
 4. **Write detailed coverage report** to `draft/tracks/<id>/coverage-report-<timestamp>.md` (where `<timestamp>` is generated via `date +%Y-%m-%dT%H%M`, e.g., `2026-03-15T1430`) with YAML frontmatter (include `project`, `track_id`, `generated_by: "draft:coverage"`, `generated_at`, `git` metadata matching other skills) and timestamped entries for historical tracking.
 
    After writing the timestamped report, create a symlink pointing to it:
+
    ```bash
    ln -sf coverage-report-<timestamp>.md draft/tracks/<id>/coverage-report-latest.md
    ```
@@ -316,7 +330,8 @@ After developer approves:
 ## Completion
 
 Announce:
-```
+
+```text
 Coverage report complete.
 
 Overall: [percentage]% (target: [target]%)
@@ -335,6 +350,7 @@ Results recorded in:
 ## Re-running Coverage
 
 When coverage is run again on the same track/module:
+
 1. Compare with previous results from metadata.json. If no previous coverage data found in metadata.json, skip delta comparison and report current values only.
 2. Show delta: "Coverage improved from 87.3% to 96.2% (+8.9%)"
 3. Highlight newly covered lines

package/skills/debug/SKILL.md

@@ -29,11 +29,12 @@ When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-firs
 
 Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
 
 Skill-specific:
+
 - Making code changes before reproducing the bug
 - Guessing at the cause instead of tracing data/control flow
 - Trying multiple fixes simultaneously ("shotgun debugging")
@@ -70,6 +71,7 @@ Debug can run standalone (without draft context) or within a draft track. If `dr
 Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 
 Key context for debugging:
+
 - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
 - `tech-stack.md` — Language-specific debugging tools and techniques
 - `guardrails.md` — Known anti-patterns that may be causing the issue
@@ -78,12 +80,14 @@ Key context for debugging:
 ## Step 1: Parse Arguments
 
 Check for arguments:
+
 - `/draft:debug` — Interactive: ask what's broken
 - `/draft:debug <description>` — Start with the described problem
 - `/draft:debug track <id>` — Debug within a specific track context (load spec.md, plan.md)
 - `/draft:debug <JIRA-KEY>` — Pull context from Jira ticket via MCP
 
 If a Jira ticket is provided:
+
 1. Pull ticket via Jira MCP: `get_issue()`, `get_issue_description()`, `get_issue_comments()`
 2. Extract: URLs, log paths, stack traces, reproduction steps, affected services
 3. Use `curl`/`wget` to fetch any URLs mentioned (dashboards, error pages, API responses)
@@ -111,8 +115,10 @@ Reference `core/agents/debugger.md` Phase 1 for detailed investigation technique
 1. **Trace data flow** — Follow data from input to failure point, documenting each hop with `file:line` references
 2. **Trace control flow** — Map the execution path, identify where it diverges from expected behavior
 3. **Differential analysis** — Compare working vs failing cases:
+
    | Aspect | Working Case | Failing Case | Difference |
    |--------|-------------|-------------|------------|
+
 4. **Check boundaries** — Reference `.ai-context.md` module boundaries to scope the investigation
 
 Reference `core/agents/debugger.md` Phase 2 for language-specific debugging techniques.
@@ -143,9 +149,11 @@ Reference `core/agents/debugger.md` Phase 3 and `core/agents/rca.md` for 5 Whys
 ### Test Writing Guardrail
 
 **STOP.** Before writing any test:
-```
+
+```yaml
 ASK: "Root cause confirmed: [summary]. Want me to write a regression test for this fix? [Y/n]"
 ```
+
 - If accepted: write regression test first (fails before fix, passes after)
 - If declined: note "Tests: developer-handled" and proceed to fix
 
@@ -172,6 +180,7 @@ Include the report header table immediately after frontmatter:
 ```
 
 Save to:
+
 - Track-scoped: `draft/tracks/<id>/debug-report.md`
 - Standalone: `draft/debug-report-<timestamp>.md` with symlink `debug-report-latest.md`
 
@@ -194,6 +203,7 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to debug report)
 
 Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md) §Canonical footer. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
 ## Cross-Skill Dispatch
 
 - **Auto-invoked by:** `/draft:new-track` (bug tracks — Offer tier), `/draft:implement` (blocked tasks — Offer tier)

package/skills/decompose/SKILL.md

@@ -29,7 +29,7 @@ When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-firs
 
 Filesystem `grep`/`find` for module discovery is only permitted **after** a documented graph miss, using the fallback sentence `Graph returned no match for <X>; falling back to grep.` and recorded in the Graph Usage Report.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills. In particular, the **Ground-Truth Red Flags** are load-bearing for decompose: HLD/LLD are design-mandated artifacts and TBD citations on Modified modules fail review.
 
@@ -44,6 +44,7 @@ must pass clean on the regenerated set. Plan.md must back-link to
 [core/shared/discovery-schema.md](../../core/shared/discovery-schema.md).
 
 Skill-specific:
+
 - Defining modules without understanding the codebase
 - Creating modules with circular dependencies
 - Making modules too large (>3 files, excluding test files) or too small (single function)
@@ -67,6 +68,7 @@ For track-scoped decomposition, also derive the human-readable track title used
 - `{TRACK_TITLE}` — first-level heading text from the active track's `spec.md` (the `# ...` line). If `spec.md` has no H1, fall back to the `{TRACK_ID}`.
 
 Also extract from `spec.md` frontmatter:
+
 - `classification.criticality`, `classification.data_classification`, `classification.deployment_surface` — copy verbatim into hld.md frontmatter.
 - `approvers.*` — pre-fill the HLD Approvals table (tech_leads, arb_leads, cloudops_leads, qa_leads, pm_leads) and LLD Approvals table (team_leads, tech_leads, qa). If a field is empty in spec.md, leave the table cell empty — do not invent names.
 
@@ -100,6 +102,7 @@ Parse `$ARGUMENTS` for flags first, then strip them before interpreting the rema
 - `--lld` → **LLD mode** — generate Section 6 (Low-Level Design) in addition to HLD. Strip from arguments before scope detection.
 
 Scope detection (on stripped arguments):
+
 - `project` or no argument with no active track → **Project-wide** decomposition → `draft/architecture.md` + `draft/.ai-context.md`
 - Track ID or active track exists → **Track-scoped** decomposition → `draft/tracks/<id>/hld.md` (always) + `draft/tracks/<id>/lld.md` (when triggered)
 
@@ -135,25 +138,30 @@ For brownfield projects, scan the existing codebase using these concrete steps:
 ### Codebase Scanning Patterns
 
 **Directory structure** — Map top-level organization:
+
 ```bash
 ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
 ```
 
 **Entry points** — Find main files and exports:
+
 - Look for: `index.ts`, `main.ts`, `app.ts`, `mod.rs`, `__init__.py`, `main.go`
 - Check `package.json` `main`/`exports` fields, `pyproject.toml` entry points, `go.mod` module path
 
 **Existing module boundaries** — Identify by:
+
 - Directory-per-feature patterns (e.g., `src/auth/`, `src/users/`)
 - Package files (`package.json` in subdirs, `__init__.py`, `go` package declarations)
 - Barrel exports (`index.ts` re-exporting from a directory)
 
 **Dependency patterns** — Trace imports:
+
 - Search for `import` / `require` / `from` statements across source files
 - Identify which directories import from which other directories
 - Flag cross-cutting imports (e.g., `utils/` imported everywhere)
 
 **File type filters by language:**
+
 | Language | Source Extensions | Config Files |
 |----------|-------------------|--------------|
 | TypeScript/JS | `*.ts`, `*.tsx`, `*.js`, `*.jsx` | `tsconfig.json`, `package.json` |
@@ -180,6 +188,7 @@ This data is deterministic and exhaustive. The manual scanning recipes above onl
 Propose a module breakdown through dialogue:
 
 For each module, define:
+
 - **Name** - Short, descriptive identifier
 - **Responsibility** - One sentence: what this module owns
 - **Files** - Expected source files (existing or to be created)
@@ -193,6 +202,7 @@ For each module, define:
 2. Target 1-3 files per module
 3. Every module needs a clear API boundary
 4. **Minimal Coupling** — communicate through interfaces, not internals
+
 - Modules should be testable in isolation
 - Each module typically contains: API, control flow, execution state, functions
 
@@ -200,7 +210,7 @@ For each module, define:
 
 **STOP.** Present the module breakdown to the developer.
 
-```
+```yaml
 ---
                    MODULE BREAKDOWN
 ---
@@ -235,7 +245,7 @@ After modules are approved:
 
 **STOP.** Present the dependency diagram and implementation order.
 
-```
+```yaml
 ---
                  DEPENDENCY ANALYSIS
 ---
@@ -277,6 +287,7 @@ Template selection depends on scope:
 - **Track-scoped** → `core/templates/hld.md` (always) and `core/templates/lld.md` (when triggered)
 
 **Output location:**
+
 - Project-wide: Update `draft/architecture.md` with the module changes, then run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`.
 - Track-scoped: write to `draft/tracks/<id>/hld.md` and (when triggered) `draft/tracks/<id>/lld.md`.
 
@@ -287,6 +298,7 @@ Template selection depends on scope:
 Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every section that has a directive — do not ship placeholders.
 
 **Frontmatter:**
+
 - Copy git metadata from current repo state.
 - Copy `classification.*` from `spec.md` frontmatter (criticality, data_classification, deployment_surface). The HLD's `links.*` block is statically correct in `core/templates/hld.md` — do not copy it from spec.md.
 
@@ -297,6 +309,7 @@ Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every
 **§Requirements:** Do not duplicate `spec.md`. Verify the link references resolve to actual sections in spec.md; if a section is missing, flag it.
 
 **§High Level Design / Architecture:**
+
 - **`<!-- GRAPH:track-component-diagram -->` slot:** Render Mermaid `flowchart TD` with three subgraphs — `Track` (modules in scope from Step 3), `Existing` (existing modules this track touches per integration edges), `External` (DB, queue, 3P APIs). Label edges with transport (HTTP / RPC / queue / direct call) when non-obvious.
 - **Architecture narrative** (≤300 words). Explain how blackbox requirements map to the architecture. Name the architectural style. Justify from observable evidence.
 
@@ -307,11 +320,13 @@ Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every
 **§High Level Design / Alternatives Considered:** Table format. Promote any non-trivial rejected alternative to a standalone ADR via `/draft:adr` and link both ways.
 
 **§Detailed Design:**
+
 - **`<!-- GRAPH:track-component-table -->` slot:** Render one row per module from Step 3. Columns: Module, Status (`New`/`Modified`/`Existing`), Files (count + comma list), Public API count, Fan-In, Fan-Out, Complexity (`Low`/`Medium`/`High`), Primary Deps, Citation (`path:line` of entry symbol).
 - **Mandatory Citation Gate:** For every row whose Status is `Modified` or `Existing`, the Citation cell **MUST** resolve to a real `path:line` from a file you Read in this run. `TBD` is only legal for `Status: New` rows, and only when the planned file path is filled (e.g. `Citation: newscribe/server/ops/shuffle_memory_eligibility.h (planned)`). If a Modified-row Citation is unresolved, **halt** — Read the file, locate the entry symbol, and fill the cell before emitting the table. See [graph-query.md](../../core/shared/graph-query.md) §Ground-Truth Discipline rules G1 and G3.
 - **Per-component subsection:** One `#### {Component Name}` block per module. Fill Responsibility, Status, Entry point (resolved `path:line` for Modified/Existing modules), Public API link to LLD, Whitebox requirements addressed (AC IDs from spec.md), Design notes (≤200 words).
 
 **§Dependencies:**
+
 - **`<!-- GRAPH:track-dependencies -->` slot:** Render rows per cross-module integration edge of kind `call`/`import`/`event`/`shared-schema`. Columns: Dependent Component, Edge Kind, Impact Assessment (Small/Medium/Large — graph fan-in heuristic: 1–2 = Small, 3–5 = Medium, 6+ = Large), Description, Citation. The Citation column is bound by the same Mandatory Citation Gate as the component table.
 
 **§Intellectual Property, §Checklist, §Deployment, §Observability:** These are author-driven sections that the design author completes before the HLD is presented for approval. Decompose's job is to **scaffold structured TBD bullets**, not to invent claims and not to leave bare `-` placeholders.
@@ -388,11 +403,13 @@ When triggered, generate `draft/tracks/<id>/lld.md` from `core/templates/lld.md`
 **§Requirements:** Link-only to `spec.md`; list AC IDs covered by this LLD.
 
 **§Low Level Design / Classes and Interfaces:**
+
 - **`<!-- GRAPH:track-class-table -->` slot:** Render per-module table from graph public-API index. One row per public symbol. Columns: Symbol, Kind (class/iface/func/method), Signature, Visibility, Citation (`path:line`), Concurrency Notes.
 - **Mandatory Citation Gate (LLD):** Same rule as HLD §Detailed Design. For every symbol whose owning module has Status `Modified` or `Existing`, Citation must resolve to a real `path:line` from a file Read in this run. For `Status: New` symbols, Citation may be `<planned path>:<planned line or TBD>` provided the file path is concrete. A bare `TBD` cell is a halt — fix before emitting.
 - **Per-component subsection:** Public API table with full signatures, params, returns, errors, citation. Document Preconditions, Postconditions, Invariants (thread safety, idempotency, ordering).
 
 **§Low Level Design / Data Model:**
+
 - **`<!-- GRAPH:track-data-models -->` slot:** Render one block per new/modified entity. Pull proto/struct/class declarations and field metadata from the graph data-model index.
 - **Per-model subsection:** Field table (type, nullable, default, validation), Storage, Indexes/Keys, Migration path.
 
@@ -432,6 +449,7 @@ Run unconditionally — idempotent if files are already clean.
 ### CHECKPOINT (MANDATORY)
 
 **STOP.** Present the generated `hld.md` (and `lld.md` if generated) to the developer. Call out:
+
 - Which graph slots were populated vs. unpopulated (and why — e.g., "no proto definitions found, GRAPH:track-data-models slot empty").
 - Whether LLD was generated, and the trigger (`--lld` flag or auto-triggered by High-complexity module X).
 - Author-driven sections that still need manual content: §IP, §Checklist (HLD), §PaaS/§UT (LLD), §Observability metrics/thresholds.
@@ -452,7 +470,7 @@ If this is a track-scoped decomposition and a `plan.md` exists:
 `core/templates/plan.md` (and tracks generated from it at template_version
 ≥ 2.0.0) wraps phase tables in:
 
-```
+```text
 <!-- DECOMPOSE:REGENERATE START -->
 ... phase tables ...
 <!-- DECOMPOSE:REGENERATE END -->
@@ -479,6 +497,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 **Completed tasks `[x]`:** Preserve exactly as-is. Map them to the appropriate module phase. Do not rename, reorder, or modify. Add a note: `(preserved from original plan)`.
 
 **In-progress tasks `[~]`:** Map to the appropriate module phase. Flag for developer review if the task spans multiple modules:
+
 ```markdown
 - [~] **Task 2.1:** Original task description
   - ⚠ REVIEW: This task may need splitting across modules [auth] and [database]
@@ -489,6 +508,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 **Blocked tasks `[!]`:** Preserve the blocked status and reason. Map to appropriate module. If the blocker is in a different module, add a cross-module dependency note.
 
 **Conflict handling:** If a task doesn't map cleanly to any module:
+
 1. List it under a `### Unmapped Tasks` section at the end
 2. Flag it for developer decision
 3. Never silently drop tasks
@@ -497,7 +517,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 
 **STOP.** Present the updated plan structure.
 
-```
+```text
 PROPOSED PLAN RESTRUCTURE
 ---
 Phase 1: [Module A] (Foundation)
@@ -521,7 +541,8 @@ After applying the approved plan changes:
 ## Completion
 
 **Track-scoped announcement:**
-```
+
+```text
 Track decomposition complete.
 
 Created: draft/tracks/<id>/hld.md
@@ -547,7 +568,8 @@ Next steps:
 ```
 
 **Project-wide announcement** (when scope = project):
-```
+
+```text
 Project architecture refresh complete.
 
 Updated: draft/architecture.md
@@ -570,6 +592,7 @@ When adding new modules to the project-wide architecture:
 4. Run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`
 
 **Safe write pattern for architecture.md:**
+
 1. Backup `architecture.md` → `architecture.md.backup`
 2. Write changes to `architecture.md.new`
 3. Present diff for review
@@ -579,12 +602,14 @@ When adding new modules to the project-wide architecture:
 ## Updating design context
 
 **Project-wide rerun** (running `/draft:decompose` on existing `.ai-context.md` / `architecture.md`):
+
 1. Read the existing context file
 2. Ask developer what changed (new modules, removed modules, restructured boundaries)
 3. Follow the same checkpoint process for changes
 4. Update `draft/architecture.md`, preserving completed module statuses and stories, then regenerate `.ai-context.md`
 
 **Track-scoped rerun** (running `/draft:decompose <track>` on existing `hld.md` / `lld.md`):
+
 1. Read the existing HLD (and LLD if present)
 2. If the track's `spec.md` has materially changed, prefer `/draft:change` first to amend spec/plan and flag HLD/LLD impact
 3. Otherwise, regenerate the graph-fenced slots only (component diagram, component table, dependencies table, class table, data models). Author-driven sections (§IP, §Checklist, §PaaS, §UT, §Observability) and the §Approvals table are preserved verbatim
@@ -598,7 +623,7 @@ When adding new modules to the project-wide architecture:
 
 After defining module boundaries and interfaces:
 
-```
+```text
 "Decomposition complete. Consider:
 
 Testing:
@@ -614,7 +639,8 @@ Architecture:
 ### Dependency Cycle Detection
 
 If dependency analysis (Step 4) detects cycles or high coupling:
-```
+
+```text
 "Detected dependency cycles / high coupling. Consider:
   → /draft:tech-debt — Catalog architecture debt and prioritize remediation"
 ```
@@ -622,6 +648,7 @@ If dependency analysis (Step 4) detects cycles or high coupling:
 ### ADR Auto-Invocation
 
 When decomposition involves breaking a monolith, choosing module boundaries, or extracting services:
+
 - Auto-invoke: "This decomposition is a significant architectural decision. Creating ADR to document rationale."
 - Invoke `/draft:adr "Module boundary decisions for {project}"`
 
@@ -644,11 +671,13 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to output)
 
 Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md) §Canonical footer. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
 ## Skill Telemetry
 
 As the last step after the completion announcement, emit a metrics record. Best-effort — never block.
 
 **Payload fields:**
+
 ```json
 {
   "skill": "decompose",
@@ -661,6 +690,7 @@ As the last step after the completion announcement, emit a metrics record. Best-
 ```
 
 **Emit call:**
+
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.