@drafthq/draft 2.7.0

package/core/templates/ai-context.md

@@ -0,0 +1,270 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# {PROJECT_NAME} Context Map
+
+> Self-contained AI context. Budget: {TIER_MIN}–{TIER_MAX} lines (tier {N}: {LABEL}).
+> Graph metrics: M={modules} F={functions} P={proto_rpcs} E={include_edges}
+> Primary value: faithful structural graph + **core operational models** (workflows, lifecycles, state machines) derived from architecture.md §3 (Primary Control & Data Flows).
+> This file must stand alone — no references to architecture.md or source files needed.
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+---
+
+## Architecture
+
+- **Type**: {type} <!-- e.g., gRPC Microservice, CLI tool, library, REST API -->
+- **Language**: {language} <!-- e.g., TypeScript 5.3, Python 3.12, Go 1.21 -->
+- **Pattern**: {pattern} <!-- e.g., Hexagonal, MVC, Pipeline, Event-driven -->
+- **Build**: `{build_command}`
+- **Test**: `{test_command}`
+- **Entry**: `{entry_file}` → `{entry_function}`
+- **Config**: {config_mechanism} <!-- e.g., .env + config.ts, gflags, Viper -->
+- **Generational**: {generational} <!-- V1/V2 split or "single generation" -->
+
+## Component Graph
+
+```
+{project_root}/
+├── {module1}/ ← {5-10 word description}
+│ ├── {submod1}/ ← {description} ({Ncc} cc, {Nh} h)
+│ │ └── ops/ ← {description} ({N} operations)
+│ ├── {submod2}/ ← {description}
+│ └── {shared}/ ← {description}
+├── {module2}/ ← {description}
+│ ├── {submod}/ ← {description}
+│ └── {submod}/ ← {description}
+└── {module3}/ ← {description}
+```
+
+> Include immediate sub-directories for all major modules (not just top-level).
+> Use graph data (`draft/graph/modules/*.jsonl`) for exhaustive sub-module enumeration.
+> Show file counts per sub-module to indicate relative size/importance.
+
+## GRAPH:MODULES
+
+{module}|{sizeKB}KB|go:{N},proto:{N} → {dep1},{dep2}
+...
+
+> One row per module ordered by sizeKB descending. Omit for tier-1 codebases (≤5 modules) where Component Graph is sufficient.
+
+## GRAPH:HOTSPOTS
+
+{file_path}|{lines}L|fanIn:{N}
+...
+
+> Top 10 files by score (lines + fanIn×50). Always include all tiers.
+
+## GRAPH:CYCLES
+
+None ✓
+
+> Or: list cycle paths e.g. "auth → storage → auth". Always include — absence is signal.
+
+## GRAPH:MODULE-HOTSPOTS
+
+{module}: {file}|{lines}L|fanIn:{N}
+           {file}|{lines}L|fanIn:{N}
+           {file}|{lines}L|fanIn:{N}
+
+> Top 3 hotspot files per module by score (lines + fanIn×50). Tier ≥ 3 only. Omit for tier 1–2.
+> Tells agents which files in a specific module carry the most change risk.
+
+## GRAPH:FAN-IN
+
+{module}|fanIn:{N}|callers:{caller1},{caller2}
+
+> Modules ordered by incoming dependency count descending. Tier ≥ 3 only.
+> High fanIn = high change risk — modifications propagate to many callers.
+
+## GRAPH:PROTO-MAP
+
+{ServiceName}: {rpc}({RequestType}) → {ResponseType} @{file}
+
+> One line per RPC, grouped by service. Present only when proto_rpcs > 0. Omit entirely for non-proto codebases.
+
+## GRAPH:OPERATIONAL (Core Behavioral Models)
+
+**Primary Operational Models** (from architecture.md §3 — highest fidelity requirement):
+
+- **{Flow/Lifecycle Name 1}** (e.g. Request Lifecycle, Init Pipeline, Job Pipeline):
+  State1 --(event/func)--> State2 --(error path)--> ErrorState --> Recovery
+  (include key decision points, alt paths, and error recovery)
+
+- **{Flow/Lifecycle Name 2}**:
+  ...
+
+> For typical apps: main request flow + background processing + startup.
+> For plugin / meta-tooling platforms: init with graph gate, skill/agent dispatch + frontmatter enforcement, condensation, parallel analysis, etc.
+> Represent complex sequence/state diagrams in compact structured text. Preserve error paths and critical transitions.
+
+## Dependency Injection / Wiring
+
+{One paragraph or bullets explaining how components find each other.}
+
+Key injection points:
+- `{token1}`: {what it provides}
+- `{token2}`: {what it provides}
+- `{token3}`: {what it provides}
+
+## Critical Invariants (DO NOT BREAK)
+
+- [Data] **{name}**: {one-sentence rule} — enforced at `{file}:{line}`
+- [Security] **{name}**: {rule} — enforced at `{file}:{line}`
+- [Concurrency] **{name}**: {rule} — enforced at `{file}:{line}`
+- [Ordering] **{name}**: {rule} — enforced at `{file}:{line}`
+- [Idempotency] **{name}**: {rule} — enforced at `{file}:{line}`
+- [Compatibility] **{name}**: {rule} — enforced at `{file}:{line}`
+
+## Interface Contracts (TypeScript-like IDL)
+
+```typescript
+// Primary extension interface
+interface {InterfaceName} {
+  {method}({param}: {Type}): {ReturnType}; // {brief description}
+  {optionalMethod}?({param}: {Type}): {ReturnType};
+}
+
+// Service contract
+interface {ServiceName} {
+  {rpcMethod}(req: {RequestType}): Promise<{ResponseType}>;
+}
+```
+
+## Dependency Graph
+
+```
+[{Component}] -> (HTTP) -> [{ExternalService}]
+[{Component}] -> (SQL) -> [{Database}]
+[{Component}] -> (gRPC) -> [{PeerService}]
+[{Component}] -> (queue) -> [{MessageBroker}]
+```
+
+## Key Data Sources
+
+| Source | Type | Readers |
+|--------|------|---------|
+| `{table/topic/endpoint}` | {DB/Queue/API} | `{component1}`, `{component2}` |
+
+## Data Flow Summary (tied to Operational Models above)
+
+**{FlowName}** (from GRAPH:OPERATIONAL): {concise description of one primary model, including main error/recovery path}.
+
+**{FlowName2}**: ...
+
+> This section should be a lightweight textual summary of the key models already detailed in GRAPH:OPERATIONAL. Do not duplicate — complement it.
+
+## Error Handling & Failure Recovery
+
+- **{Scenario}**: {Recovery mechanism} — {where handled}
+- **{Scenario}**: {Recovery mechanism} — {where handled}
+- **Retries**: {policy description}
+- **Circuit breaker**: {if applicable}
+- **Graceful degradation**: {behavior when dependencies unavailable}
+
+## Concurrency Safety Rules
+
+- **{ComponentName}**: {rule} — violating causes {consequence}
+- **{ComponentName}**: {rule} — violating causes {consequence}
+- **Lock ordering**: {if applicable}
+- **Thread affinity**: {which components are single-threaded}
+
+## Implementation Catalog
+
+### {Category1}
+
+| Name | Type | Description |
+|------|------|-------------|
+| `{impl1}` | `{Class}` | {brief description} |
+| `{impl2}` | `{Class}` | {brief description} |
+
+### {Category2}
+
+| Name | Type | Description |
+|------|------|-------------|
+| `{impl3}` | `{Class}` | {brief description} |
+
+## V1 ↔ V2 Migration Status
+
+> Skip if no generational split.
+
+| V1 | V2 | Status |
+|----|----|----|
+| `{v1_impl}` | `{v2_impl}` | {Migrated/Pending/Deprecated} |
+
+**Rule**: When adding new {X}, prefer {V1/V2} because {reason}.
+
+## Thread Pools / Execution Model
+
+| Pool | Count | Purpose |
+|------|-------|---------|
+| `{pool_name}` | {N} | {what runs on it} |
+
+> For single-threaded: "Single-threaded event loop — N/A"
+
+## Key Configuration
+
+| Flag/Param | Default | Critical? | Purpose |
+|------------|---------|-----------|---------|
+| `{FLAG_NAME}` | `{value}` | Yes | {description} |
+| `{flag_name}` | `{value}` | No | {description} |
+
+## Extension Points — Step-by-Step Cookbooks
+
+### Adding a New {ExtensionType}
+
+1. Create `{path/to/new_file.ext}` (naming: `{convention}`)
+2. Implement interface:
+   - Required: `{method1}()`, `{method2}()`
+   - Optional: `{method3}?()`
+3. Register at `{registry_file}:{line}` via `{mechanism}`
+4. Add to build: `{build_dep_instruction}`
+5. Test: create `{test_path}` covering {scenarios}
+
+### Adding a New {ExtensionType2}
+
+1. {step}
+2. {step}
+3. {step}
+
+## Testing Strategy
+
+- **Unit**: `{exact_test_command}`
+- **Integration**: `{framework}` in `{location}`
+- **E2E**: `{command}` (if applicable)
+- **Key hooks**: `{injection_point}`, `{mock_pattern}`, `{test_utility}`
+
+## File Layout Quick Reference
+
+- Entry: `{path}`
+- Config: `{path}`
+- Routes/Handlers: `{path}`
+- Services: `{path}`
+- Repositories: `{path}`
+- Models: `{path}`
+- Tests: `{path}`
+- Build: `{path}`
+
+## Glossary (Critical Terms Only)
+
+| Term | Definition |
+|------|------------|
+| {term} | {one-sentence definition} |
+| {term} | {one-sentence definition} |
+
+## Draft Integration
+
+- See `draft/tech-stack.md` for accepted patterns and technology decisions
+- See `draft/workflow.md` for TDD preferences and commit conventions
+- See `draft/guardrails.md` for hard guardrails, learned conventions, and learned anti-patterns
+- See `draft/product.md` for product context and guidelines

package/core/templates/ai-profile.md

@@ -0,0 +1,41 @@
+---
+project: "{PROJECT_NAME}"
+module: "{MODULE_NAME or 'root'}"
+generated_by: "draft:{COMMAND_NAME}"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# {PROJECT_NAME} Profile
+
+## Project
+- Name: {PROJECT_NAME}
+- One-liner: {ONE_LINE_PRODUCT_DESCRIPTION}
+- Primary users: {USER_TYPES}
+- Repository layout: {monorepo|polyrepo|single-service}
+
+## Stack
+- Language: {LANGUAGE}
+- Framework: {FRAMEWORK}
+- Database: {DATABASE}
+- Auth: {AUTH_METHOD}
+- API: {API_STYLE}
+- Testing: {TEST_FRAMEWORK}
+- Deploy: {DEPLOY_TARGET}
+- Build: {BUILD_COMMAND}
+- Entry: {ENTRY_POINT}
+
+## INVARIANTS
+{Top 3-5 critical invariants from .ai-context.md, one per line, with file:line refs}
+
+## NEVER
+{2-3 safety rules — things that must never happen}
+
+## Key Operational Models (from §6 / GRAPH:OPERATIONAL)
+- {Most critical flow 1 — one line}
+- {Most critical flow 2 (if space allows)}
+
+## Active Tracks
+{List of active track IDs and one-line descriptions, or "none"}
+
+## Recent Changes
+{Last 3-5 significant commits or changes, one per line}

package/core/templates/architecture.md

@@ -0,0 +1,203 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+
+# Ownership — enterprise accountability.
+ownership:
+  codeowners_file: "{path-to-CODEOWNERS or 'none'}"
+  primary_owners: ["{team-or-person}"]
+  security_contact: "{email-or-channel-or-'N/A'}"
+  oncall: "{pagerduty/opsgenie URL or 'none'}"
+
+# Verification — stamped by draft:init at render time.
+verification:
+  citations_verified: "{true | false | unchecked}"
+  staleness_hash: "{sha256 of tracked source set at synced_to_commit}"
+  graph_schema_version: "{semver or 'absent'}"
+
+# Graph fidelity (mandatory, forward-looking)
+graph:
+  build_status: "{success | failed | absent}"
+  overall_fidelity: "{high | mixed | low | stub}"
+  language_fidelity:
+    python: "{stub (directory-level only) | approximate | high}"
+    typescript: "{stub | approximate | high}"
+    rust: "{approximate | high}"
+    cpp: "{high}"
+    go: "{approximate | high}"
+  stats:
+    modules: "{N from schema.yaml}"
+    edges: "{total_edges from architecture.json}"
+    hotspots: "{N}"
+  notes: "{explicit fidelity summary from architecture.json languages/packages}"
+generation_notes: "{High existing context detected via audit — see §10 Relationship for deference | Standard graph-primary generation}"
+---
+
+# Architecture: {PROJECT_NAME}
+
+> Graph-primary, high-signal engineering reference for AI coding assistants and humans.
+> For the token-optimized machine version, see `draft/.ai-context.md`.
+> The knowledge graph is the deterministic structural spine. LLM synthesis exists only to interpret dynamic behavior, state machines, and rationale not visible in the static graph. Fidelity is declared explicitly. Provenance is mandatory on all claims.
+
+**Graph Health & Fidelity Dashboard** (populated at generation time from the `graph:` block; future agents must read this first):
+
+| Language/Area | Fidelity | Modules | Edges | Hotspots | Notes |
+|---------------|----------|---------|-------|----------|-------|
+| Python        | {stub}   | {N}     | {N}   | {N}      | {e.g. directory-level only} |
+| Rust          | {high}   | {N}     | {N}   | {N}      | {graph-derived} |
+| ...           | ...      | ...     | ...   | ...      | ... |
+
+> Low-fidelity areas are explicitly called out in §9. This document never pretends richer graph data than actually exists.
+
+## Generation Contract (read first — binding)
+
+1. **Graph is structural truth.** Module boundaries, dependencies, public surfaces, hotspots, and call relationships come from `draft/graph/`. LLM never invents them.
+2. **Fidelity declaration is non-negotiable.** Every major claim carries an explicit tag: `[Graph:High]`, `[Graph:Stub]`, `[Existing:CLAUDE.md §3]`, `[Human:Synthesis]`, or `[Test-backed:INV-042]`.
+3. **Provenance on all claims.** Invariants, failure modes, lock ordering, and data truth sources must name their source and enforcement.
+4. **Diagrams > prose.** One accurate Mermaid workflow/state/sequence diagram grounded in the graph is worth more than paragraphs of generic description.
+5. **No duplication of excellent existing agent docs.** When the Context Audit detects CLAUDE.md / INVARIANTS.md / ADRs, this document defers and cross-references. It supplies the graph spine and synthesis, not a parallel prose copy.
+6. **Honest gaps.** §9 is mandatory and high-value. Future agents must be able to read the fidelity table + gaps section and know exactly where to distrust the model.
+7. **Accuracy over volume.** Short, precise, graph-anchored sections are correct. Historical line-count or diagram-count targets are retired.
+
+Absence is signal. If a section does not apply, state the precise reason referencing graph data or classification.
+
+---
+
+## 1. Executive Summary + Graph Health Dashboard
+
+One tight paragraph: what the system is, what it does, its role in the larger environment.
+
+The Graph Health & Fidelity Dashboard (above) is the first artifact any reader or agent must internalize.
+
+---
+
+## 2. Critical Invariants & Safety Rules (Highest Priority)
+
+The longest and most precise section.
+
+Every invariant must include:
+- Precise statement
+- Why violation is dangerous
+- Enforcement mechanism (test, runtime, type system, review, graph constraint, or none)
+- Provenance / Fidelity tag + source (e.g. `docs/INVARIANTS.md:INV-003`, `Graph:High`, `Human Judgment`)
+
+Example format:
+
+```
+### INV-003: Sentinel Lock Ordering
+**Rule**: `_strategies_lock < _strategy_process_locks < _global_capacity_lock < entry_lock`
+**Fidelity**: High (enforced in code + tests)
+**Graph Evidence**: Not expressible in static graph (dynamic ordering)
+**Source**: docs/INVARIANTS.md + src/.../sentinel/...
+**Enforcement**: test + code review
+```
+
+---
+
+## 3. Primary Control & Data Flows (Graph + Synthesis)
+
+Focus on the highest-value dynamic behavior:
+
+- Dominant request / data / control flows (end-to-end)
+- State machines with financial or safety impact
+- Lifecycle sequences (bootstrap, shutdown, reconciliation, failover)
+
+Each backed by:
+- Graph-derived paths where available
+- High-quality Mermaid (stateDiagram-v2, sequenceDiagram, or detailed flowchart)
+- Explicit note when the flow is only partially visible in the graph
+
+---
+
+## 4. Module & Dependency Map (Primarily Graph-Derived)
+
+- Module dependency graph rendered from `draft/graph/architecture.json` (`.packages`) + `module-deps.mermaid`
+- High fan-in / fan-out modules highlighted
+- Cyclic dependencies called out
+- Cross-language boundaries (FFI, RPC, shared memory) explicitly surfaced with coverage notes
+
+Include a short "graph coverage for this view" paragraph.
+
+---
+
+## 5. Concurrency, Ownership & Isolation Model
+
+- Single-writer patterns and ownership boundaries
+- Lock ordering (explicitly tagged when not graph-expressible)
+- Async / thread-pool / actor boundaries
+- Failure isolation regions
+
+---
+
+## 6. Error Handling & Failure Mode Catalog
+
+For every major component or flow:
+- What can go wrong
+- How it is detected
+- The defined safe response
+- Whether enforcement is graph, test, runtime, or process
+
+---
+
+## 7. State & Data Truth Sources + Reconciliation
+
+For each major domain:
+- Authoritative source
+- Derived / cached views
+- Reconciliation mechanisms and lag tolerance
+- Staleness policy
+
+---
+
+## 8. Extension Points & Safe Mutation Patterns
+
+How to add new behavior without violating invariants. Include registration sites, required vs optional contracts, and test patterns. Graph-derived where possible.
+
+---
+
+## 9. Graph Coverage Gaps & Known Limitations (MANDATORY)
+
+Explicit, honest list of where the document and underlying graph are weak or absent.
+
+- Per-language fidelity shortfalls (copy from Dashboard)
+- Areas where synthesis or existing high-quality docs were the real ground truth
+- Remaining hallucination risk for future agents
+- "Future agents should re-verify X against source before acting here"
+
+This section is one of the most valuable outputs for safety-critical or low-graph-fidelity systems.
+
+---
+
+## 10. Relationship to Other Authoritative Documentation (MANDATORY when Context Audit high/medium)
+
+When the Pre-Check Context Audit detects strong agent-optimized sources (CLAUDE.md, INVARIANTS.md, ADRs, etc.):
+
+- List the detected files with one-line characterization
+- State exactly what this architecture.md supplies (graph spine, deterministic maps, visual synthesis, provenance on claims)
+- State what it defers to, with concrete cross-references
+- Explicit confirmation that no large-scale prose duplication of the existing authoritative material occurred
+
+When no high context was detected: short note that this document is the primary self-contained reference.
+
+---
+
+## Fidelity & Provenance Rules (Strict — apply everywhere)
+
+Every claim or section must be tagged with one of:
+
+- `Graph-Derived (High)` — direct from rich graph data
+- `Graph-Derived (Approximate)` — tree-sitter / static analysis
+- `Graph-Derived (Stub)` — directory/file counts only
+- `Human + Graph` — graph shows structure; synthesis added rationale or dynamic behavior
+- `Human Judgment` — not (yet) expressible in the graph (lock ordering, certain safety rules) — always call out
+- `Existing Authoritative Doc` — defers to CLAUDE.md / INVARIANTS.md etc.
+
+AI agents are trained by the document itself to treat Stub and Human Judgment claims with calibrated caution.
+
+---
+
+**End of clean graph-primary architecture template.**
+
+This is the single forward-looking source of truth. Legacy 28-section volume-oriented material has been retired.

package/core/templates/dependency-graph.md

@@ -0,0 +1,103 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:index"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# Service Dependency Graph
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+> Auto-generated. Do not edit directly.
+> Re-run `/draft:index` to update.
+
+---
+
+## System Topology
+
+```mermaid
+graph LR
+    subgraph "Core Services"
+        auth[auth-service]
+        users[user-service]
+    end
+
+    subgraph "Business Services"
+        billing[billing-service]
+        orders[order-service]
+    end
+
+    subgraph "Edge"
+        gateway[api-gateway]
+    end
+
+    subgraph "Background"
+        notifications[notification-service]
+        reports[report-service]
+    end
+
+    gateway --> auth
+    gateway --> users
+    gateway --> billing
+    gateway --> orders
+    billing --> auth
+    orders --> auth
+    orders --> billing
+    notifications --> users
+    reports --> billing
+    reports --> orders
+```
+
+> Services without `draft/` are shown with dashed borders when detected.
+
+## Dependency Matrix
+
+| Service | Depends On | Depended By | Circular? |
+|---------|-----------|-------------|-----------|
+| auth-service | - | billing, orders, gateway | No |
+| user-service | auth | gateway, notifications | No |
+| billing-service | auth | orders, gateway, reports | No |
+| order-service | auth, billing | gateway, reports | No |
+| api-gateway | auth, users, billing, orders | - | No |
+| notification-service | users | - | No |
+| report-service | billing, orders | - | No |
+
+## Dependency Order (Topological)
+
+Build/deploy order for cross-service changes:
+
+1. **auth-service** — foundational, no internal dependencies
+2. **user-service** — depends on: auth
+3. **billing-service** — depends on: auth
+4. **order-service** — depends on: auth, billing
+5. **notification-service** — depends on: users
+6. **report-service** — depends on: billing, orders
+7. **api-gateway** — depends on: auth, users, billing, orders (deploy last)
+
+> This ordering helps when planning cross-service changes, understanding blast radius, or sequencing deployments.
+
+## Impact Analysis
+
+When modifying a service, these services may be affected:
+
+| If You Change... | Check These Services |
+|------------------|---------------------|
+| auth-service | billing, orders, gateway, users |
+| billing-service | orders, gateway, reports |
+| user-service | gateway, notifications |
+
+## External Dependencies
+
+Services depending on external systems:
+
+| External System | Used By | Purpose |
+|----------------|---------|---------|
+| [Stripe] | billing-service | Payment processing |
+| [SendGrid] | notification-service | Email delivery |
+| [AWS S3] | report-service | Report storage |

package/core/templates/discovery.md

@@ -0,0 +1,79 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+track_id: "{TRACK_ID}"
+generated_by: "draft:discover"
+generated_at: "{ISO_TIMESTAMP}"
+links:
+  spec: "./spec.md"
+  plan: "./plan.md"
+  hld: "./hld.md"
+  lld: "./lld.md"
+---
+
+# {TRACK_TITLE} — Discovery
+
+> Phase 0 (code spike). Captures the current-state code reading the AI
+> performed before the spec was written, anchored to
+> `metadata.json:synced_to_commit`. See
+> [core/shared/discovery-schema.md](../../core/shared/discovery-schema.md)
+> for the schema. Hygiene validator forbids empty hotspots without an
+> adjacent `_NONE_FOUND_` justification.
+
+**Status:** <!-- META:status --> <!-- REQUIRED -->
+
+---
+
+## Hotspots <!-- REQUIRED -->
+
+Code locations the spec must address. Each row cites `path:line` that
+verify-citations.sh resolves against the pinned commit.
+
+| Step | Location | Behavior |
+|------|----------|----------|
+| _TBD_hotspot_1_step_ | _TBD_hotspot_1_location_ | _TBD_hotspot_1_behavior_ |
+| _TBD_hotspot_2_step_ | _TBD_hotspot_2_location_ | _TBD_hotspot_2_behavior_ |
+| _TBD_hotspot_3_step_ | _TBD_hotspot_3_location_ | _TBD_hotspot_3_behavior_ |
+
+> If the spike found nothing: keep this table empty and add a
+> `_NONE_FOUND_ — <justification>` line below before saving.
+
+---
+
+## Mode Selection <!-- REQUIRED -->
+
+Flags, feature gates, environment switches that govern the current code
+path. Receivers of the spec use this to scope rollout planning.
+
+| Switch | Location | Notes |
+|--------|----------|-------|
+| _TBD_switch_1_name_ | _TBD_switch_1_location_ | _TBD_switch_1_notes_ |
+
+---
+
+## Open Questions <!-- REQUIRED -->
+
+Load-bearing unknowns that must close before spec freeze. Each question
+must resolve into a decision in `spec.md`, a deferral with a follow-up
+track ID, or `_NONE_FOUND_` with justification.
+
+- Q1: _TBD_question_1_
+- Q2: _TBD_question_2_
+
+---
+
+## References <!-- REQUIRED -->
+
+Flat list of files and functions touched in the spike. Files cited here
+without line numbers are exempt from drift checks (they document
+*familiarity*, not pinned facts).
+
+- _TBD_reference_1_path_ — _TBD_reference_1_symbol_ — _TBD_reference_1_role_
+- _TBD_reference_2_path_ — _TBD_reference_2_symbol_ — _TBD_reference_2_role_
+
+---
+
+## Conversation Log <!-- OPTIONAL -->
+
+> Free-form notes captured during the spike. Reviewers can skim this for
+> context the structured sections above don't carry. Not validator-checked.