@drafthq/draft 2.7.0

package/core/templates/lld.md

@@ -0,0 +1,283 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+track_id: "{TRACK_ID}"
+generated_by: "draft:decompose"
+generated_at: "{ISO_TIMESTAMP}"
+# Stable frontmatter only (WS-8). Ephemeral fields live in metadata.json
+# and render via <!-- META:<key> --> directives.
+links:
+  spec: "./spec.md"
+  plan: "./plan.md"
+  hld: "./hld.md"
+  project_architecture: "../../architecture.md"
+---
+
+# {TRACK_TITLE} — LLD
+
+**_TBD_author_** (_TBD_email_) <!-- REQUIRED -->
+
+**Status:** <!-- META:status --> <!-- REQUIRED -->
+
+> Track ID: `{TRACK_ID}` — generated by `draft:decompose`. Sibling docs: [`./hld.md`](./hld.md), [`./spec.md`](./spec.md), [`./plan.md`](./plan.md). For project-wide architecture, see [`../../architecture.md`](../../architecture.md).
+
+## Approvals
+
+> **Pre-fill:** Pulled from `spec.md` frontmatter `approvers.{team_leads, tech_leads, qa}`. Captured per row before code review begins.
+
+| Role | Approver | Date | Comments | <!-- REQUIRED for criticality ∈ {high, mission-critical} -->
+|------|----------|------|----------|
+| Team Leads | _TBD_approver_team_leads_ | _TBD_date_ | _TBD_comments_ |
+| Technical Leads | _TBD_approver_tech_leads_ | _TBD_date_ | _TBD_comments_ |
+| Quality Assurance | _TBD_approver_qa_ | _TBD_date_ | _TBD_comments_ |
+
+---
+
+## Table of Contents
+
+1. [Background](#background)
+2. [Requirements](#requirements)
+3. [Low Level Design](#low-level-design)
+4. [Observability](#observability)
+
+---
+
+## Background
+
+<Link to HLD and explain context here>
+
+> See [`./hld.md` §Background](./hld.md#background) for the high-level rationale. Use this section only for component-internal context the HLD doesn't cover.
+
+> **Citations.** Use `path/to/file.ext:LINE` (or `LINE-RANGE`); verifier:
+> `scripts/tools/verify-citations.sh`. Prefer `// DRAFT-CITE: <id>` source
+> anchors over raw line numbers for code that moves often.
+
+---
+
+## Requirements
+
+> **Source:** [`./spec.md`](./spec.md). Whitebox (per-component) requirements live there. Do not duplicate.
+
+- **Whitebox requirements scorecard:** see [`./spec.md` §Requirements](./spec.md#requirements)
+- **Acceptance criteria mapped to this LLD:** {list AC IDs covered by this LLD}
+
+---
+
+## Low Level Design
+
+> **NOTE:**
+> - HLD and Detailed Design covers components and interactions across various services that the feature touches
+> - LLD to be documented here is for each such component and internal implementation
+> - A single doc here can cover all components, or they can be split up, but the key is to ensure every component in every service the design touches has an LLD
+
+### Classes and Interfaces
+
+**Describe the class level design preferably with a diagram**
+
+- This should convey what interfaces each class provides and how it interacts with other classes
+- Describe choice of message queues vs RPCs for interactions
+
+<!-- GRAPH:track-class-table:START -->
+<!-- Rendered by draft:decompose Step 5b for each module marked New/Modified.
+     Per-module table. Columns: Symbol, Kind (class/iface/func/method),
+     Signature, Visibility, Citation, Concurrency Notes, lock_acquired,
+     reentrant. -->
+<!-- WS-7 required columns: lock_acquired (named lock or "none"),
+     reentrant (yes/no/n/a). -->
+<!-- GRAPH:track-class-table:END -->
+
+#### [Component/Service Name]
+
+**Public API:**
+
+| Function / Method | Signature | Params | Returns | Errors / Exceptions | Citation |
+|-------------------|-----------|--------|---------|---------------------|----------|
+| `{name}` | `{lang-appropriate signature}` | `{param: type — constraint}` | `{type — shape}` | `{error types / codes}` | `path:line` |
+
+**Preconditions:** {what must be true before call — caller responsibilities}
+**Postconditions:** {what is guaranteed after successful call}
+**Invariants:** {properties preserved across calls — thread safety, idempotency, ordering}
+
+{Repeat per component.}
+
+---
+
+### Data Model
+
+**Describe the schemas of persistent state - protobuf or db schemas**
+
+- Describe the schemas of messages / RPCs
+- Describe caching considerations
+
+<!-- GRAPH:track-data-models:START -->
+<!-- Rendered by draft:decompose Step 5b. One block per new/modified entity.
+     Pulls proto/struct/class declarations + field metadata from the graph. -->
+<!-- GRAPH:track-data-models:END -->
+
+#### [Component/Service Name]
+
+**`{ModelName}`** (`path:line`)
+
+```{language}
+{actual type definition — struct, class, interface, proto message, TypedDict, etc.}
+```
+
+| Field | Type | Nullable | Default | Validation / Constraint |
+|-------|------|----------|---------|-------------------------|
+| `{field}` | `{type}` | yes/no | `{default or —}` | `{rule}` |
+
+**Storage:** {where persisted — table, collection, key prefix}
+**Indexes / Keys:** {primary key, unique constraints, indexed fields}
+**Migration:** {if this is a schema change — migration path and rollback}
+
+{Repeat per model.}
+
+---
+
+### Eligibility / Cap Tables <!-- OPTIONAL -->
+
+> When the LLD specifies caps (byte limits, row limits, concurrency caps),
+> use this schema. Every cap value carries `derived_from` (a flag, threshold,
+> benchmark, or vendor limit). Pure invention without `derived_from` is
+> rejected by the deploy-checklist gate.
+
+| Cap | Value | derived_from | Notes | <!-- REQUIRED if section present -->
+|-----|-------|--------------|-------|
+| _TBD_cap_1_name_ | _TBD_cap_1_value_ | _TBD_cap_1_derived_from_ | _TBD_cap_1_notes_ |
+
+---
+
+### Key Algorithms and Workflows
+
+**Describe certain key algorithms / workflows**
+
+> **WS-7 sequence-diagram rule.** When the prose enumerates edge cases (cap
+> exceeded, OOM, flag flip mid-flow, retry exhausted), the Mermaid sequence
+> diagram **must** include an explicit `alt` / `opt` block per edge case.
+> `Note over X,Y: ... TBD policy ...` is **not** sufficient. Reviewers and
+> deploy-checklist fail on bare prose without diagram blocks.
+
+Examples:
+- List of steps to failover a multi-region database cluster
+- Analysis phase of a background data indexing service
+- Transferring session state information between authentication and profile services via a secure messaging protocol
+
+#### [Algorithm/Workflow Name]
+
+**Inputs:** `{...}`
+**Outputs:** `{...}`
+**Complexity:** `O({...})` time, `O({...})` space
+
+```mermaid
+sequenceDiagram
+    participant U as {Caller}
+    participant A as {module-1}
+    participant B as {module-2}
+    participant D as {DB / external}
+
+    U->>A: {request payload}
+    A->>B: {internal call}
+    B->>D: {query / write}
+    D-->>B: {result}
+    B-->>A: {response}
+    A-->>U: {final response}
+
+    Note over A,B: {invariant / gate}
+```
+
+**Pseudocode:**
+
+```
+1. validate inputs
+2. ...
+3. return result
+```
+
+**Edge cases handled:**
+- {case 1 — what happens}
+- {case 2 — what happens}
+
+---
+
+### Error Handling & Retry Semantics
+
+| Operation | Error Class | Classification | Retry? | Backoff | Max Attempts | Fallback | fault_injection_site | <!-- REQUIRED -->
+|-----------|-------------|----------------|--------|---------|--------------|----------|----------------------|
+| _TBD_err_1_op_ | _TBD_err_1_class_ | _TBD_err_1_classification_ | _TBD_err_1_retry_ | _TBD_err_1_backoff_ | _TBD_err_1_max_attempts_ | _TBD_err_1_fallback_ | _TBD_err_1_fault_injection_site_ |
+
+**Propagation model:** {Result type / exceptions / error codes}
+**Circuit breaker:** {thresholds, half-open policy, reset} — omit if N/A
+**Idempotency:** {which operations are idempotent and how — dedup key, tx id}
+
+---
+
+### Refactoring of Existing Code
+
+<Describe if large sections of existing code is being refactored, and why (e.g., not modular and hence can't be reused; can't write UTs well as interfaces are not defined cleanly)>
+
+---
+
+### Programming Language Choice and Unit Testing
+
+#### Programming Language Choice
+
+<Describe Programming Language choice and justification>
+
+#### Unit Testing Strategy
+
+- **Mock Interfaces:**
+  - How mock interfaces are going to be implemented and used in UTs
+  
+- **Functional Test Cases:**
+  - What are major cases to be UT'd functionally
+  
+- **Error & Fault Injection:**
+  - How errors & faults are injected
+  
+- **Race Condition Simulation:**
+  - How race conditions are simulated
+
+> See `/draft:testing-strategy` for the project's authoritative test strategy. This LLD section captures only what is specific to this track's components.
+
+---
+
+### PaaS Choices
+
+<Describe the choices made in each of the following areas with justification:>
+
+#### Data Store
+
+- Relational vs NoSQL
+- Justification
+
+#### Workflow Engine
+
+- (e.g., Temporal, etc.)
+- Justification
+
+#### Operational State Checkpointing Store
+
+- (e.g., Scribe, Mongo, etc.)
+- Justification
+
+---
+
+## Observability
+
+### Metrics
+
+List down all metrics that developers and SREs need to look at to identify issues:
+
+- 
+- 
+- 
+
+### Alerting Thresholds
+
+List down alerting thresholds on those metrics:
+
+| Metric | Threshold | Severity | Action |
+|--------|-----------|----------|--------|
+| | | | |
+
+> `/draft:deploy-checklist` validates this table is populated before deploy.

package/core/templates/metadata.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "Draft Track Metadata Schema",
+  "$description": "Tracks status, progress, review history, and blast radius for a Draft track. Created by /draft:new-track, updated by /draft:implement and /draft:review.",
+
+  "id": "<track-id>",
+  "title": "<Human-readable title>",
+  "type": "feature|bugfix|refactor",
+  "status": "planning|in_progress|completed",
+  "created": "<ISO 8601 timestamp>",
+  "updated": "<ISO 8601 timestamp>",
+
+  "phases": {
+    "total": 0,
+    "completed": 0
+  },
+
+  "tasks": {
+    "total": 0,
+    "completed": 0
+  },
+
+  "template_version": "2.0.0",
+
+  "scope_includes": [],
+  "scope_excludes": [],
+
+  "classification": {
+    "criticality": "_TBD_criticality_",
+    "data_classification": "_TBD_data_classification_",
+    "deployment_surface": "_TBD_deployment_surface_"
+  },
+
+  "git": {
+    "branch": "_TBD_branch_",
+    "remote": "_TBD_remote_",
+    "commit": "_TBD_commit_",
+    "commit_short": "_TBD_commit_short_",
+    "commit_date": "_TBD_commit_date_",
+    "commit_message": "_TBD_commit_message_",
+    "dirty": false
+  },
+  "synced_to_commit": "_TBD_synced_to_commit_",
+
+  "hygiene_budget": {
+    "draft_tbd_cap": -1,
+    "ready_for_review_tbd_cap": 3,
+    "discovery_min_hotspots": 3
+  },
+
+  "pre_deploy_status": "unrun",
+
+  "lastReviewed": "<ISO 8601 timestamp — set by /draft:review>",
+  "reviewCount": 0,
+  "lastReviewVerdict": "PASS|PASS_WITH_NOTES|FAIL",
+
+  "$impact_description": "Blast-radius memory — written by /draft:implement on phase complete, read by /draft:new-track to flag overlap. Sourced from `git diff --name-only <track_first_sha>^..HEAD` plus `scripts/tools/graph-impact.sh --repo . --file <path>` for each touched file. Optional — absent if graph data unavailable.",
+  "impact": {
+    "files_touched": [],
+    "modules_touched": [],
+    "downstream_files": 0,
+    "downstream_modules": [],
+    "max_depth": 0,
+    "by_category": { "code": 0, "test": 0, "doc": 0, "config": 0 },
+    "computed_at": "<ISO 8601 timestamp>"
+  }
+}

package/core/templates/plan.md

@@ -0,0 +1,130 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+track_id: "{TRACK_ID}"
+generated_by: "draft:new-track"
+generated_at: "{ISO_TIMESTAMP}"
+# Stable frontmatter only (WS-8). Ephemeral fields live in metadata.json
+# and render via <!-- META:<key> --> directives.
+---
+
+# Plan: {TITLE}
+
+<!-- DECOMPOSE:REGENERATE START -->
+<!-- Phase tables below are rewritten by draft:decompose. Manual notes outside
+     these markers survive every regenerate. -->
+<!-- DECOMPOSE:REGENERATE END -->
+
+| Field | Value |
+|-------|-------|
+| **Branch** | <!-- META:git.branch --> → <!-- META:git.remote --> |
+| **Commit** | <!-- META:git.commit_short --> — <!-- META:git.commit_message --> |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | <!-- META:synced_to_commit --> |
+
+**Track ID:** {TRACK_ID}
+**Spec:** ./spec.md
+**Status:** <!-- META:status --> <!-- REQUIRED -->
+
+## Scope <!-- OPTIONAL -->
+
+- **Includes:** <!-- META:scope_includes -->
+- **Excludes:** <!-- META:scope_excludes -->
+
+---
+
+## Overview
+
+{One-paragraph summary of what this plan delivers, derived from spec.md}
+
+---
+
+<!-- DECOMPOSE:REGENERATE START -->
+
+## Phase 0: Discovery (completed)
+
+**Goal:** Spike — read current code, enumerate hotspots and open questions.
+**Verification:** [`./discovery.md`](./discovery.md) exists, hotspots cited,
+open questions resolved or deferred.
+
+| Entry gate | Exit gate | Owner |
+|---|---|---|
+| `draft:new-track` initiated | `discovery.md` validator clean (`scripts/tools/verify-citations.sh`, hygiene) | _TBD_owner_phase_0_ |
+
+---
+
+## Phase 1: Foundation
+
+**Goal:** {What this phase establishes}
+**Verification:** {How to confirm phase is complete}
+
+| Entry gate | Exit gate | Owner | <!-- REQUIRED -->
+|---|---|---|
+| _TBD_phase_1_entry_gate_command_ | _TBD_phase_1_exit_gate_command_ | _TBD_owner_phase_1_ |
+
+### Tasks
+
+- [ ] **Task 1.1:** {Description} — `{file_path}`
+- [ ] **Task 1.2:** {Description} — `{file_path}`
+
+---
+
+## Phase 2: Core Implementation
+
+**Goal:** {What this phase delivers}
+**Verification:** {How to confirm phase is complete}
+
+| Entry gate | Exit gate | Owner | <!-- REQUIRED -->
+|---|---|---|
+| _TBD_phase_2_entry_gate_command_ | _TBD_phase_2_exit_gate_command_ | _TBD_owner_phase_2_ |
+
+### Tasks
+
+- [ ] **Task 2.1:** {Description} — `{file_path}`
+- [ ] **Task 2.2:** {Description} — `{file_path}`
+
+---
+
+## Phase 3: Integration & Polish
+
+**Goal:** {What this phase delivers}
+**Verification:** {How to confirm phase is complete — run full test suite, manual verification}
+
+| Entry gate | Exit gate | Owner | <!-- REQUIRED -->
+|---|---|---|
+| _TBD_phase_3_entry_gate_command_ | _TBD_phase_3_exit_gate_command_ | _TBD_owner_phase_3_ |
+
+### Tasks
+
+- [ ] **Task 3.1:** {Description} — `{file_path}`
+- [ ] **Task 3.2:** Verify — {Run tests, confirm all acceptance criteria met}
+
+<!-- DECOMPOSE:REGENERATE END -->
+
+---
+
+## Pre-Deploy Validation <!-- REQUIRED -->
+
+Before any phase advances past `[~]` in-progress to `[x]` complete, run the
+validator chain via the canonical resolver pattern (see
+[core/shared/verification-gates.md](../../core/shared/verification-gates.md)):
+
+```bash
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+"$DRAFT_TOOLS/check-track-hygiene.sh" .; "$DRAFT_TOOLS/verify-citations.sh" .
+"$DRAFT_TOOLS/verify-doc-anchors.sh" .; "$DRAFT_TOOLS/check-graph-usage-report.sh" .
+"$DRAFT_TOOLS/check-scope-conflicts.sh" ..;"$DRAFT_TOOLS/diff-templates-vs-tracks.sh" .
+```
+
+`metadata.json:pre_deploy_status` MUST be `passing` to deploy.
+
+---
+
+## Status Markers
+
+- `[ ]` Pending
+- `[~]` In Progress
+- `[x]` Completed — append commit SHA: `(abc1234)`
+- `[!]` Blocked — note reason

package/core/templates/product.md

@@ -0,0 +1,110 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# Product: [Product Name]
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+---
+
+## Vision
+
+[One paragraph describing what this product does and why it matters to users]
+
+---
+
+## Target Users
+
+### Primary Users
+- **[User Type 1]**: [What they need, their context]
+- **[User Type 2]**: [What they need, their context]
+
+### Secondary Users
+- **[Admin/Support]**: [Their interaction with the product]
+
+---
+
+## Core Features
+
+### Must Have (P0)
+1. **[Feature 1]**: [Brief description]
+2. **[Feature 2]**: [Brief description]
+3. **[Feature 3]**: [Brief description]
+
+### Should Have (P1)
+1. **[Feature 4]**: [Brief description]
+2. **[Feature 5]**: [Brief description]
+
+### Nice to Have (P2)
+1. **[Feature 6]**: [Brief description]
+
+---
+
+## Success Criteria
+
+- [ ] [Measurable goal 1, e.g., "Users can complete signup in under 2 minutes"]
+- [ ] [Measurable goal 2]
+- [ ] [Measurable goal 3]
+
+---
+
+## Constraints
+
+### Technical
+- [Constraint, e.g., "Must support IE11"]
+- [Constraint, e.g., "API response time < 200ms"]
+
+### Business
+- [Constraint, e.g., "Must comply with GDPR"]
+- [Constraint, e.g., "Budget for external APIs: $X/month"]
+
+### Timeline
+- [Milestone 1]: [Date]
+- [Milestone 2]: [Date]
+
+---
+
+## Non-Goals
+
+Things explicitly out of scope for this product:
+
+- [Non-goal 1]
+- [Non-goal 2]
+
+---
+
+## Open Questions
+
+- [ ] [Question that needs resolution]
+- [ ] [Another question]
+
+---
+
+## Guidelines (Optional)
+
+### Writing Style
+- **Tone:** [professional / casual / technical]
+- **Voice:** [first person "we" / third person "the system" / second person "you"]
+- **Terminology:** [domain-specific terms and definitions]
+
+### UX Principles
+1. [e.g., "Convention over configuration" — minimize required decisions]
+2. [e.g., "Accessible by default" — WCAG AA compliance minimum]
+3. [e.g., "Progressive disclosure" — show complexity only when needed]
+
+### Error Handling
+- **Error message tone:** [helpful / technical / minimal]
+- **User feedback patterns:** [toasts / modals / inline / status bar]
+
+### Content Standards
+- **Date format:** [ISO 8601 / localized / relative]
+- **Internationalization:** [i18n required / English-only / planned]

package/core/templates/rca.md

@@ -0,0 +1,86 @@
+---
+project: "{PROJECT_NAME}"
+track_id: "{TRACK_ID}"
+jira_ticket: "{JIRA_KEY}"
+generated_by: "draft:new-track"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# Root Cause Analysis: {TITLE}
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+## Summary
+
+[1-2 sentence root cause statement with `file:line` references]
+
+## Classification
+
+- **Type:** [logic error | race condition | data corruption | config error | dependency issue | missing validation | state management | resource exhaustion]
+- **Severity:** [SEV1 | SEV2 | SEV3 | SEV4]
+- **Detection Lag:** [when introduced vs when detected]
+- **SLO Impact:** [which SLOs affected, by how much]
+
+## Evidence Gathered
+
+| Source | URL/Path | Key Finding |
+|--------|----------|-------------|
+| Jira ticket | {JIRA_KEY} | [reproduction steps, reporter context] |
+| Logs | [ssh path or URL] | [relevant log lines] |
+| Dashboard | [URL] | [metric anomaly] |
+| Code | [file:line] | [relevant code section] |
+
+## Timeline
+
+| When | What |
+|------|------|
+| [date] | Bug introduced (commit SHA if known) |
+| [date] | Bug detected / reported |
+| [date] | Investigation started |
+| [date] | Root cause confirmed |
+| [date] | Fix deployed |
+
+## 5 Whys
+
+1. Why did [symptom]? → Because [cause 1]
+2. Why [cause 1]? → Because [cause 2]
+3. Why [cause 2]? → Because [cause 3]
+4. Why [cause 3]? → Because [cause 4]
+5. Why [cause 4]? → Because [root cause]
+
+## Blast Radius
+
+- **Affected modules:** [from .ai-context.md service map]
+- **Affected users/flows:** [from product.md user journeys]
+- **Data impact:** [any data corruption or loss]
+- **SLO budget consumed:** [percentage of error budget burned]
+
+## Prevention Items
+
+### Detection Improvement
+- [ ] [monitoring/alerting improvement to catch this sooner]
+
+### Process Improvement
+- [ ] [review/testing improvement to prevent this class of bug]
+
+### Code Improvement
+- [ ] [guard/validation to add in code]
+
+### Architecture Improvement
+- [ ] [structural change if needed to make this class of bug impossible]
+
+## Proposed Fix
+
+[Brief description of the fix approach — developer reviews before implementation]
+
+**Files to modify:**
+- `file1:line` — [change description]
+- `file2:line` — [change description]
+
+**Regression test:**
+- [Description of regression test to write — pending developer approval]