@drafthq/draft 2.7.0

package/core/shared/condensation.md

@@ -0,0 +1,224 @@
+# Condensation Subroutine
+
+> Generates `.ai-context.md` from `architecture.md`. Called by multiple skills after modifying architecture.
+
+---
+
+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
+- Extension Points (§8) → EXTEND + INTERFACES
+
+Any skill that mutates `architecture.md` should execute this subroutine afterward to keep the derived context files in sync.
+
+**Called by:** `/draft:init`, `/draft:init refresh`, `/draft:implement`, `/draft:decompose`, `/draft:coverage`, `/draft:index`
+
+### 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
+
+| Output | Path | Description |
+|--------|------|-------------|
+| .ai-context.md | `draft/.ai-context.md` | Token-optimized, machine-readable AI context (tier-scaled budget) |
+| .ai-profile.md | `draft/.ai-profile.md` | Ultra-compact, always-injected project profile (20-50 lines) |
+
+**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
+
+Compute tier from `draft/graph/schema.yaml` after graph build:
+
+  M = stats.modules
+  F = stats.go_functions + stats.py_functions
+  P = stats.proto_rpcs
+
+| Tier | Label | Condition | Budget |
+|------|--------|----------------------------------------|---------------|
+| 1 | micro | M≤5 AND F≤50 AND P≤10 | 100–180 lines |
+| 2 | small | M≤15 AND F≤300 AND P≤30 | 180–280 lines |
+| 3 | medium | M≤40 AND F≤1000 AND P≤100 | 280–400 lines |
+| 4 | large | M≤100 AND F≤5000 AND P≤500 | 400–600 lines |
+| 5 | XL | M>100 OR F>5000 OR P>500 | 600–900 lines |
+
+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
+
+#### 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
+
+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
+
+Transform each `architecture.md` section into machine-optimized format using this mapping:
+
+| architecture.md Section (10-section graph-primary) | .ai-context.md Section | Transformation |
+|--------------------------------------------------|------------------------|----------------|
+| §1 Executive Summary + Graph Health Dashboard | META + GRAPH:HEALTH | Extract key-value pairs; dashboard metrics as compact rows |
+| §2 Critical Invariants & Safety Rules | INVARIANTS | One line per invariant: `[CATEGORY] name: rule @file:line` |
+| §3 Primary Control & Data Flows | GRAPH:OPERATIONAL + GRAPH:DATAFLOW | Convert Mermaid to `FLOW:{Name}` arrow notation |
+| §4 Module & Dependency Map | GRAPH:COMPONENTS + GRAPH:MODULES | Tree notation `├─` / `└─`; module fan-in/out from graph |
+| §5 Concurrency, Ownership & Isolation | THREADS + CONCURRENCY | Pipe-separated rows + isolation rules |
+| §6 Error Handling & Failure Mode Catalog | ERRORS | Key-value pairs: `scenario: recovery` |
+| §7 State & Data Truth Sources | GRAPH:DATAFLOW + STATE | Truth sources and reconciliation paths |
+| §8 Extension Points & Safe Mutation | INTERFACES + EXTEND | Condensed signatures + cookbook steps |
+| §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
+
+If `draft/graph/schema.yaml` exists, generate these sections from the snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools:
+
+**GRAPH:MODULES** (tier ≥ 2 only):
+- Read `draft/graph/architecture.json` → `.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):
+- Read `draft/graph/hotspots.jsonl` (already fan-in-ranked), take top 10
+- 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):
+- Read `draft/graph/hotspots.jsonl`; group 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
+- Order modules by their highest-fanIn symbol, descending
+- Omit modules with no hotspot entries; omit entire section for tier 1–2 (covered by global GRAPH:HOTSPOTS)
+
+**GRAPH:FAN-IN** (tier ≥ 3 only):
+- Read `architecture.json` → `.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 `architecture.json` `.routes` is non-empty):
+- Read `architecture.json` → `.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
+
+- Remove all prose paragraphs — use structured key-value pairs instead
+- Remove Mermaid syntax — use text-based graph notation (`├─`, `-->`, `-[proto]->`)
+- Remove markdown formatting (no `**bold**`, no `_italic_`, no headers beyond `##`)
+- 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
+
+If the output exceeds the tier maximum, cut sections in this order (bottom = cut first):
+
+| Priority | Section | Rule |
+|----------|---------|------|
+| 1 (never cut) | INVARIANTS | Safety critical — preserve every invariant |
+| 2 (never cut) | EXTEND | Agent productivity critical — preserve all cookbook steps |
+| 3 (keep) | GRAPH:HOTSPOTS | Always include — needed for impact awareness |
+| 3 (keep) | GRAPH:CYCLES | Always include — always 1-2 lines; absence is signal |
+| 3 (keep) | GRAPH:PROTO-MAP | Never cut when protos exist — RPC contracts are critical for AI agents |
+| 3 | GRAPH:* | Keep all component, dependency, and dataflow graphs |
+| 4 (scale) | GRAPH:MODULES | Include tier ≥ 2; omit for tier 1 |
+| 4 (scale) | GRAPH:MODULE-HOTSPOTS | Include tier ≥ 3; cut to top-5 modules if budget tight |
+| 4 (scale) | GRAPH:FAN-IN | Include tier ≥ 3; cut to top-10 rows if budget tight |
+| 4 | INTERFACES | Keep all signatures |
+| 5 | CATALOG | Can abbreviate to top 20 entries per category |
+| 6 | CONFIG | Can abbreviate to `critical:Y` entries only |
+| 7 (cut first) | VOCAB | Can abbreviate to 10 most important terms |
+
+#### Step 6: Quality Check
+
+Before writing `draft/.ai-context.md`, verify:
+
+- [ ] No prose paragraphs remain (all content is structured data)
+- [ ] No Mermaid syntax (all diagrams converted to text graphs)
+- [ ] No references to `architecture.md` (file must be self-contained)
+- [ ] All invariants from architecture.md are preserved
+- [ ] Extension cookbooks are complete (an agent can follow them without other files)
+- [ ] Output is within tier budget bounds (compute from schema.yaml or default tier 2)
+- [ ] GRAPH:HOTSPOTS present (or note "No hotspot data available" if graph absent)
+- [ ] GRAPH:CYCLES present ("None ✓" or cycle list; or note if graph absent)
+- [ ] GRAPH:MODULE-HOTSPOTS present for tier ≥ 3 (or note if no hotspot data)
+- [ ] GRAPH:FAN-IN present for tier ≥ 3
+- [ ] GRAPH:PROTO-MAP present when `stats.proto_rpcs > 0` (omit entirely if no protos)
+- [ ] YAML frontmatter metadata is present at the top
+
+#### Step 7: Write Output
+
+Write the completed content to `draft/.ai-context.md`.
+
+#### 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="${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"
+[ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" draft/architecture.md draft/.ai-context.md draft/.ai-profile.md 2>/dev/null || true
+```
+
+This is idempotent — run it unconditionally.
+
+### Example Transformation
+
+**architecture.md input:**
+````markdown
+### 4.1 High-Level Topology
+
+The AuthService is a microservice that handles user authentication...
+
+```mermaid
+flowchart TD
+    subgraph AuthService
+        API[API Layer] --> Logic[Auth Logic]
+        Logic --> Store[Token Store]
+    end
+    Logic --> UserDB[(User Database)]
+```
+````
+
+**.ai-context.md output:**
+```
+## GRAPH:COMPONENTS
+AuthService
+  ├─API: handles HTTP requests
+  ├─Logic: validates credentials, generates tokens
+  └─Store: caches active tokens
+
+## GRAPH:DEPENDENCIES
+AuthService.Logic -[PostgreSQL]-> UserDB
+```
+
+### 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`."

package/core/shared/context-verify.md

@@ -0,0 +1,44 @@
+---
+shared: context-verify
+applies_to: all skills that load Draft project context
+---
+
+# Verify Draft Context (Shared Subroutine)
+
+Single-source `Verify Draft Context` subroutine. Replaces the duplicated 3–4 line blocks that appeared in skills that load project context.
+
+Referenced by: every skill that starts with a `Verify Draft Context` step.
+
+## Procedure
+
+1. **Probe the draft directory:**
+
+   ```bash
+   ls draft/ 2>/dev/null
+   ```
+
+2. **Branch on result:**
+
+   | Result | Action |
+   |---|---|
+   | Directory exists | Proceed to step 3. |
+   | Directory missing AND skill requires context (`/draft:learn`, `/draft:deep-review`, `/draft:tech-debt`, `/draft:implement`) | **STOP** — print `No Draft context found. Run /draft:init first.` and exit. |
+   | Directory missing AND skill is context-optional (`/draft:debug`, `/draft:quick-review`, `/draft:bughunt`, `/draft:deploy-checklist`, `/draft:documentation`, `/draft:testing-strategy`) | Proceed with reduced-context mode; record `draft_context: absent` in the report header. |
+
+3. **Load context** by following [draft-context-loading.md](draft-context-loading.md). Honor the **selective guardrail matrix** in that file's Layer 0.5 — do not load all guardrails just because they are available.
+
+## Usage in SKILL.md
+
+Replace the existing 3–4 line `Verify Draft Context` block with a single reference:
+
+```md
+### Verify Draft Context
+
+See [core/shared/context-verify.md](../../core/shared/context-verify.md). This skill is <required | optional> with respect to `draft/`.
+```
+
+This keeps each skill explicit about whether draft context is required, while centralizing the probe-and-branch logic.
+
+## Why This Exists
+
+Duplicating the same `ls draft/ 2>/dev/null` snippet across skills costs tokens per duplicate after frontmatter and surrounding prose. Factoring removes the duplication without changing semantics.

package/core/shared/cross-skill-dispatch.md

@@ -0,0 +1,127 @@
+# Cross-Skill Dispatch Convention
+
+Standard convention for how Draft skills invoke, offer, or suggest other skills. All Tier 1 orchestrators and cross-referencing skills follow this pattern.
+
+Convention spec implemented by: All Tier 1 orchestrators (`init`, `new-track`, `implement`, `review`, `upload`), and Tier 2 skills that cross-reference others. Skills implement this dispatch convention independently; see `skills/GRAPH.md` for the full dependency graph.
+
+## Dispatch Tiers
+
+### Tier 1: Auto-Invoke (Silent)
+
+Execute without user confirmation. Used for passive context enrichment and established patterns.
+
+- Load `testing-strategy.md` if it exists (context enrichment)
+- Feed quality results to `/draft:learn` (established pattern)
+- Sync artifacts to Jira via `core/shared/jira-sync.md` when ticket is linked
+- Load `rca.md` into bug track implementation context
+
+**Convention:** No announcement needed. Log in track metadata if applicable.
+
+### Tier 2: Offer (Ask with Default)
+
+Present a choice with a recommended default. Used when the skill adds significant value but the user may want to skip.
+
+Format:
+```
+"Run /draft:<skill> to <benefit>? [Y/n]"
+```
+
+Examples:
+- "Run `/draft:debug` to investigate before writing the spec? [Y/n]" — bug tracks in new-track
+- "Run full three-stage review or `/draft:quick-review` for lightweight check? [full]" — phase boundaries in implement
+- "Run `/draft:tech-debt` to scope this refactor? [Y/n]" — refactor tracks in new-track
+
+**Convention:** Default answer in brackets. Enter accepts default.
+
+### Tier 3: Suggest (Announce, Don't Block)
+
+Announce availability at completion without blocking. Used for optional follow-up actions.
+
+Format:
+```
+"Consider running `/draft:<skill>` to <benefit>."
+```
+
+Examples:
+- "Consider running `/draft:tech-debt` to catalog debt found during review."
+- "Consider running `/draft:documentation api` to document new endpoints."
+- "Consider running `/draft:adr` to record this design decision."
+
+**Convention:** Grouped in a "What's Next" or "Suggestions" section at skill completion.
+
+### Tier 4: Detect + Auto-Feed (Smart Context Injection)
+
+Automatically detect when output from one skill is useful to another and inject it as context. No user interaction.
+
+| Source Skill | Output | Target Skill | How Injected |
+|---|---|---|---|
+| `/draft:debug` | Debug Report | `/draft:new-track` | Fed into spec.md "Reproduction" and "Root Cause Hypothesis" sections |
+| `/draft:incident-response` | Postmortem | `/draft:new-track` | Fed into bug track spec context |
+| `/draft:tech-debt` | Debt Report | `/draft:new-track` | Fed into refactor track spec scope |
+| `/draft:testing-strategy` | Strategy Doc | `/draft:implement` | Loaded into TDD context (coverage targets, test boundaries) |
+| `/draft:debug` + RCA agent | `rca.md` | `/draft:implement` | Loaded as investigation context for bug fix implementation |
+
+**Convention:** Check for artifact existence before injection. If not found, skip silently.
+
+## Dispatch Registry
+
+Complete registry of all cross-skill dispatch points:
+
+| Orchestrator | When | Dispatches | Tier |
+|---|---|---|---|
+| `init` | Brownfield + debt signals detected | `tech-debt` | Suggest |
+| `init` | After generating tech-stack.md | `testing-strategy` | Suggest |
+| `init` | At completion | `documentation readme` | Suggest |
+| `new-track` | Bug track detected | `debug` | Offer |
+| `new-track` | Incident/outage keywords | `incident-response postmortem` | Detect + Suggest |
+| `new-track` | Refactor track | `tech-debt` | Offer |
+| `new-track` | New technology / arch shift | `adr` | Detect + Suggest |
+| `new-track` | Plan generation (feature) | `testing-strategy` task, `deploy-checklist` task, `documentation` task | Auto-embed |
+| `implement` | Blocked task | `debug` | Offer (replaces inline debugger) |
+| `implement` | Before TDD (first task) | `testing-strategy` load | Auto-Invoke |
+| `implement` | Bug track before tests | Ask developer | Offer (test guardrail) |
+| `implement` | Phase boundary | `quick-review` | Offer |
+| `implement` | Track completion | `deploy-checklist`, `documentation`, `tech-debt`, `adr` | Suggest |
+| `review` | After Stage 3 | `coverage` | Auto-Invoke |
+| `review` | At completion (quality findings) | `tech-debt`, `documentation` | Suggest |
+| `upload` | Pre-upload | `deploy-checklist` | Auto-Invoke |
+| `upload` | New APIs detected | `documentation api` | Detect + Suggest |
+| `upload` | Post-upload success | Jira comment | Auto-Invoke |
+| `decompose` | After module decomposition | `testing-strategy`, `documentation api` | Suggest |
+| `decompose` | Dependency cycles detected | `tech-debt` | Detect + Suggest |
+| `decompose` | Module boundary decisions | `adr` | Auto-Invoke |
+| `bughunt` | Critical bugs found | `debug` | Suggest |
+| `deep-review` | Architecture debt found | `tech-debt`, `adr` | Suggest |
+
+## Implementation Pattern
+
+Skills implementing dispatch should follow this pattern:
+
+```markdown
+## Cross-Skill Dispatch
+
+At this point, check for dispatch opportunities:
+
+### Auto-Invoke
+- [list auto-invoke actions relevant to this skill]
+
+### Offer
+- [list offer actions relevant to this skill]
+
+### Suggest (at completion)
+- [list suggest actions relevant to this skill]
+```
+
+## Test Writing Guardrail
+
+**In bug/debug/RCA workflows:** Never auto-write unit tests. Always ask the developer first.
+
+Applies to: `/draft:debug`, `/draft:implement` (bug tracks), auto-triage pipeline, `/draft:bughunt`
+Does NOT apply to: Feature tracks with TDD enabled, `/draft:coverage`
+
+```
+If track type is "bugfix" OR current context is debug/RCA:
+  BEFORE writing any test file:
+    ASK: "Want me to write [regression/unit] tests for [description]? [Y/n]"
+    If declined: skip test writing, note in plan.md: "Tests: developer-handled"
+```

package/core/shared/discovery-schema.md

@@ -0,0 +1,75 @@
+# Discovery Artifact Schema
+
+> Schema for the `discovery.md` artifact produced by discovery flows (as part of
+> new-track). The artifact captures the AI's pre-spec code-spike
+> findings as a first-class output.
+
+## Why this is first-class
+
+Pre-2.0, code-spike findings were buried in "Conversation Log" sections of
+`spec.md` or scattered across context-references rows. Reviewers could not
+tell whether the AI had actually read the code or had inferred structure
+from titles. `discovery.md` makes the spike output auditable, machine-
+verifiable (via citation verifiers), and load-bearing for downstream specs.
+
+## Required sections (each carries `<!-- REQUIRED -->`)
+
+1. **Hotspots** — code locations the spec must address.
+2. **Mode selection** — flags / feature gates / env switches governing the
+   current code path.
+3. **Open Questions** — load-bearing unknowns that must close before spec
+   freeze.
+4. **References** — flat list of files and functions touched in the spike.
+
+## Hotspots table — required columns
+
+| Column | Notes |
+|---|---|
+| Step | Short label for the operation observed |
+| Location | `path/to/file.ext:LINE` (verifier-resolvable) |
+| Behavior | What the spec must explain or improve (1 line) |
+
+Minimum row count: 3 (configurable via `metadata.json:hygiene_budget.discovery_min_hotspots`).
+If the spike genuinely found nothing, the row count may be 0 but the
+**Open Questions** section must contain a `_NONE_FOUND_ — <one-line
+justification>` line. The validator rejects an empty discovery without
+that justification.
+
+## Mode selection table — required columns
+
+| Column | Notes |
+|---|---|
+| Switch | flag, gate, env var, or build option |
+| Location | `path/to/file.ext:LINE` |
+| Notes | what behavior the switch toggles |
+
+## Open Questions
+
+Each question begins with `Q<N>:` and is a single line. Each MUST close
+into one of:
+
+- a decision merged into `spec.md` (preferred),
+- an explicit deferral with a follow-up track ID, or
+- a `_NONE_FOUND_` annotation explaining why the question is moot.
+
+A `discovery.md` whose Open Questions list is left dangling fails the
+hygiene validator.
+
+## References
+
+A flat bullet list of files and functions:
+
+- `path/to/file.ext` — `Function` / `Class::Method` — one-line role
+- `path/to/other.ext` — `Function2` — …
+
+Functions named here are exempt from citation drift unless they also
+appear with line numbers elsewhere.
+
+## Renaming / archiving
+
+Discovery is created once per track at spec time. Subsequent
+decompose runs DO NOT regenerate `discovery.md` — its job is to
+capture the moment in time when the spec was written, anchored to
+`metadata.json:synced_to_commit`. Re-running discovery is a deliberate
+re-spike; the previous file should be renamed `discovery-<isodate>.md`
+and the new one inherits the slot.