@drafthq/draft 2.7.0

package/core/shared/pattern-learning.md

@@ -0,0 +1,146 @@
+# Pattern Learning — Post-Analysis Phase
+
+Shared procedure for auto-discovering coding patterns after quality analysis. Run as the final phase of `/draft:bughunt`, `/draft:deep-review`, and `/draft:review`.
+
+Referenced by: `/draft:bughunt`, `/draft:deep-review`, `/draft:review`, `/draft:learn`
+
+---
+
+## When to Run
+
+Execute this phase **after** the main analysis and report generation are complete. This phase updates `draft/guardrails.md` with newly discovered patterns.
+
+**Skip this phase if:**
+- `draft/` directory does not exist (no Draft context)
+- Analysis found zero findings to learn from
+- Running in a read-only or preview mode
+
+---
+
+## Step 1: Identify Pattern Candidates
+
+Review the findings from the just-completed analysis and identify:
+
+### Convention Candidates (patterns to NOT flag in future)
+
+Look for patterns that were **considered during analysis but determined to be intentional**:
+
+- Patterns checked during the Pattern Prevalence Check that were found >3x and all instances were correct
+- Patterns that matched a framework idiom confirmed by documentation
+- Patterns flagged as MEDIUM confidence but verified as intentional after investigation
+- Recurring code structures that follow a consistent project convention
+
+### Anti-Pattern Candidates (patterns to ALWAYS flag in future)
+
+Look for patterns that were **confirmed as bugs across multiple locations**:
+
+- Bug patterns found in 3+ locations with the same root cause
+- Patterns that violate documented invariants consistently
+- Security or reliability patterns that appeared as confirmed bugs
+
+---
+
+## Step 2: Apply Confidence Threshold
+
+| Evidence | Confidence | Action |
+|----------|------------|--------|
+| Pattern found 1-2x | — | Do not learn (insufficient data) |
+| Pattern found 3-5x, all consistent | `medium` | Add to guardrails.md |
+| Pattern found >5x, all consistent, verified across multiple files | `high` | Add to guardrails.md, suggest promotion |
+| Pattern found >5x but some instances are buggy | — | Do NOT learn (inconsistent — real problem exists) |
+
+---
+
+## Step 3: Check for Duplicates
+
+Before adding a new entry to `draft/guardrails.md`:
+
+1. Read current `draft/guardrails.md`
+2. Check if the pattern already exists under Learned Conventions or Learned Anti-Patterns
+3. If it exists:
+   - Update `last_verified` and `last_active` dates
+   - Increase evidence count if new instances were found
+   - Upgrade confidence from `medium` → `high` if threshold met
+   - Preserve original `discovered_at` and `established_at` dates (never overwrite these)
+4. If it does NOT exist: append as new entry with all four timestamps populated
+
+---
+
+## Step 4: Write to guardrails.md
+
+### 4.0: Update Project Metadata
+
+Before writing entries, update `draft/metadata.json` with the current git state — this is the single source of truth for `synced_to_commit` and all `git.*` fields for project-level artifacts including `guardrails.md`. Use `git-metadata.sh --project-metadata --generated-by "draft:learn"` or update `git.commit`, `git.commit_short`, `git.commit_date`, `git.commit_message`, and `synced_to_commit` manually. Do NOT write these fields to `guardrails.md` frontmatter (WS-8).
+
+### Convention Entry Format
+
+Append under `## Learned Conventions`:
+
+```markdown
+### [Pattern Name]
+- **Category:** error-handling | naming | architecture | concurrency | state-management | data-flow | testing | configuration
+- **Confidence:** high | medium
+- **Evidence:** Found in N files — `path/file1.ext:line`, `path/file2.ext:line`, `path/file3.ext:line`
+- **Discovered at:** YYYY-MM-DD (when Draft first observed this pattern)
+- **Established at:** YYYY-MM-DD (when the pattern entered the codebase, via git blame)
+- **Last verified:** YYYY-MM-DD
+- **Last active:** YYYY-MM-DD (when source files containing this pattern were last modified)
+- **Discovered by:** draft:[command] on YYYY-MM-DD
+- **Description:** [What the pattern is and why it's intentional]
+```
+
+### Anti-Pattern Entry Format
+
+Append under `## Learned Anti-Patterns`:
+
+```markdown
+### [Anti-Pattern Name]
+- **Category:** security | reliability | performance | correctness | concurrency
+- **Severity:** critical | high | medium
+- **graph_severity:** critical | high | medium | low | unresolved (derived from fanIn of evidence files; "unresolved" if no graph data available)
+- **high_fanin_files:** `path/file.go` (fanIn:12), `path/other.go` (fanIn:7) (omit line if none meet fanIn ≥ 5)
+- **Evidence:** Found in N files — `path/file1.ext:line`, `path/file2.ext:line`
+- **Discovered at:** YYYY-MM-DD (when Draft first observed this pattern)
+- **Established at:** YYYY-MM-DD (when the pattern entered the codebase, via git blame)
+- **Last verified:** YYYY-MM-DD
+- **Last active:** YYYY-MM-DD (when source files containing this pattern were last modified)
+- **Discovered by:** draft:[command] on YYYY-MM-DD
+- **Description:** [What the pattern is and why it's problematic]
+- **Suggested fix:** [Brief description of the correct approach]
+```
+
+`graph_severity` derivation rules (from `draft/graph/hotspots.jsonl` fanIn values):
+- fanIn ≥ 10 in any evidence file → `critical`
+- fanIn 5–9 → `high`
+- fanIn 1–4 → `medium`
+- fanIn 0 or file not in hotspots.jsonl → `low`
+- Graph data absent → `unresolved`
+
+When `graph_severity` differs from `severity`, use `graph_severity` as the enforcement priority — it is objective and graph-derived.
+
+---
+
+## Step 5: Report Learning Summary
+
+After updating guardrails.md, append a brief learning summary to the end of the quality report:
+
+```markdown
+## Pattern Learning
+
+| Action | Count | Details |
+|--------|-------|---------|
+| New conventions learned | N | [names] |
+| New anti-patterns learned | N | [names] |
+| Existing patterns re-verified | N | [names] |
+| Promotion candidates (high confidence) | N | [names] |
+```
+
+---
+
+## Constraints
+
+- **Never auto-promote** learned patterns to Hard Guardrails — that requires human decision via `/draft:learn promote`
+- **Never remove** existing entries — only update evidence/confidence/dates
+- **Cap at 50 learned entries** per section — if at capacity, replace the oldest `medium` confidence entry that hasn't been re-verified in 90+ days
+- **Human-curated always wins** — Hard Guardrails and `tech-stack.md ## Accepted Patterns` take precedence over learned patterns if there's a conflict
+- **Preserve project metadata** — update `draft/metadata.json:synced_to_commit` when modifying `guardrails.md`; do NOT write `synced_to_commit` to `guardrails.md` frontmatter (WS-8)

package/core/shared/red-flags.md

@@ -0,0 +1,58 @@
+---
+shared: red-flags
+applies_to: all code-touching skills
+---
+
+# Shared Red Flags
+
+Cross-skill red flags that any code-touching skill must enforce. Skills include their own skill-specific red flags **in addition to** the universal block below. The graph-first red flags are non-negotiable — they protect correctness against premature `grep`/`find` fallbacks that miss structural truth.
+
+Referenced by: `/draft:decompose`, `/draft:implement`, `/draft:review`, `/draft:deep-review`, `/draft:quick-review`, `/draft:bughunt`, `/draft:debug`, `/draft:learn`, `/draft:tech-debt`, `/draft:deploy-checklist`, `/draft:new-track`.
+
+## Universal Red Flags (STOP if any apply)
+
+- **Ran `grep`/`find`/`rg` for symbol or file discovery before consulting the graph** (when `draft/graph/schema.yaml` exists).
+- **Read more than 50 lines of source before consulting `draft/graph/hotspots.jsonl`** to know whether the file is a hotspot.
+- **Omitted the Graph Usage Report footer** from the final output (see [graph-query.md](graph-query.md) §Mandatory Lookup Contract).
+- **Used a `grep` fallback without an explicit graph-miss statement** in the form: `Graph returned no match for <X>; falling back to grep.`
+- **Loaded full Layer 0.5 guardrails when the command type does not require them** (see selective-loading matrix in [draft-context-loading.md](draft-context-loading.md) §Layer 0.5).
+- **Marked a task complete without verification evidence** (test run, build output, lint output — pasted, not summarized).
+- **Made up file paths or line numbers** instead of reading the file (`file_path:line_number` references must resolve).
+
+## Ground-Truth Red Flags (STOP if any apply)
+
+These enforce [graph-query.md](graph-query.md) §Ground-Truth Discipline. Graph identifies candidates; Read confirms them. Shipping unread claims is the dominant correctness failure mode observed in Draft output.
+
+- **Wrote a `path:line` / `func()` / `symbol` reference into a deliverable without opening the file in this run.** Graph hit ≠ Read. (G1)
+- **Declared something in-scope or out-of-scope without Reading at least one file in that path.** Module names from `architecture.json` are a candidate set, not proof that the candidate contains the named cost. (G2)
+- **Shipped `Citation: TBD` / `Path: TBD` / `Symbol: TBD` on a row whose Status is `Modified` or `Existing`.** TBD is reserved for `Status: New` rows with a planned path filled in. (G3)
+- **Claimed code behavior (writes / blocks / loops / fails / is the only path) from graph metadata alone.** Fan-in / fan-out / complexity scores are necessary signal, not sufficient evidence. (G4)
+- **Promoted a spec / generated an HLD or LLD / closed a review without checking that the in-scope file set covers every cost term in the problem statement.** Silent scope narrowing that excludes the named cost is the highest-impact failure class. (G5)
+- **Treated a graph query result as the terminal answer.** Graph is the index; the source files are the territory. Every claim that survives to a deliverable needs at least one Read behind it.
+
+When in doubt, prefer "not yet validated against source" over an unbacked assertion. A flagged uncertainty is reviewable; a confident wrong claim is not.
+
+## Graph-First Lookup Order (non-negotiable)
+
+1. **Graph first** — the committed snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`).
+2. **Generated context second** — `draft/.ai-context.md`, relevant `draft/architecture.md` slices, track-level `hld.md`/`lld.md`.
+3. **Source file reads third** — only narrowed targets identified via graph or generated context.
+4. **Filesystem `grep`/`find` last** — only after a graph miss, with the explicit fallback sentence above.
+
+Using a lower tier before a higher tier is a **Red Flag** and must be reported in the skill's Graph Usage Report (justification required).
+
+## How to Extend
+
+Skill-specific red flags live in the skill's `SKILL.md` under `## Red Flags - STOP if you're:`. Skills should not duplicate the universal block above — instead they reference this file:
+
+```markdown
+## Red Flags - STOP if you're:
+
+See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
+
+Skill-specific:
+- <skill-specific red flag>
+- <skill-specific red flag>
+```
+
+This keeps boilerplate centralized while leaving room for skill-specific guardrails.

package/core/shared/template-contract.md

@@ -0,0 +1,22 @@
+---
+shared: template-contract
+applies_to: quality + init + graph skills
+---
+
+# Template Contract
+
+Tracks under `draft/tracks/<id>/` must conform to the artifact set and section headers in `core/templates/`. Enforcement tools:
+
+| Tool | Purpose |
+|------|---------|
+| `scripts/tools/diff-templates-vs-tracks.sh` | Missing files, section headers, removed 2.0 fields |
+| `scripts/tools/check-track-hygiene.sh` | Status parity, author placeholders, TBD budget, plan staleness |
+| `scripts/tools/check-scope-conflicts.sh` | Overlapping `scope_includes` without mutual exclusion |
+| `scripts/tools/verify-citations.sh` | `path:line` citations vs `synced_to_commit` |
+| `scripts/tools/verify-doc-anchors.sh` | Internal `§` / `#anchor` references |
+
+See [verification-gates.md](verification-gates.md) for the canonical WS-9 gate chain and [template-hygiene.md](template-hygiene.md) for hygiene rules.
+
+**Required track artifacts (2.0):** `spec.md`, `plan.md`, `hld.md`, `lld.md`, `metadata.json`, `discovery.md`.
+
+**Scope fields:** `metadata.json:scope_includes` / `scope_excludes` (or spec frontmatter fallback) define track footprint; conflicts block parallel work without explicit exclusion.

package/core/shared/template-hygiene.md

@@ -0,0 +1,10 @@
+---
+shared: template-hygiene
+applies_to: quality + init + graph skills
+---
+
+# template-hygiene (Foundations Stub)
+
+Portable generalized stub per manifest §2.1. Full content will be expanded in later agent tranche or manual follow-up.
+
+See verification-gates.md and template-hygiene.md for usage contracts.

package/core/shared/tool-resolver.md

@@ -0,0 +1,10 @@
+---
+shared: tool-resolver
+applies_to: quality + init + graph skills
+---
+
+# tool-resolver (Foundations Stub)
+
+Portable generalized stub per manifest §2.1. Full content will be expanded in later agent tranche or manual follow-up.
+
+See verification-gates.md and template-hygiene.md for usage contracts.

package/core/shared/vcs-commands.md

@@ -0,0 +1,97 @@
+# VCS Command Abstraction
+
+Shared procedure for VCS write operations across all Draft skills. Draft is GitHub-first and uses the standard `git` CLI throughout.
+
+Referenced by: All skills that execute VCS write operations (`/draft:implement`, `/draft:revert`, `/draft:new-track`).
+
+## Standard Operations
+
+| Operation         | Command                                  |
+|-------------------|------------------------------------------|
+| Stage files       | `git add <files>`                        |
+| Remove files      | `git rm <files>`                         |
+| Commit            | `git commit -m "<message>"`              |
+| Reset             | `git reset --soft <ref>`                 |
+| Revert            | `git revert --no-commit <sha>`           |
+| Checkout branch   | `git checkout -b <branch>`               |
+| Pull              | `git pull`                               |
+| Push (new branch) | `git push -u origin <branch>`            |
+| Push (existing)   | `git push`                               |
+| Rebase            | `git rebase <ref>`                       |
+
+### Read Operations
+
+```bash
+git diff [options]               # Diff (staged, unstaged, ranges)
+git log [options]                # History
+git rev-parse [options]          # SHA resolution
+git branch --show-current        # Current branch name
+git status --porcelain           # Machine-readable status
+git ls-files [pattern]           # File listing
+git diff --cached --quiet        # Check if anything staged
+git rev-list [range]             # Commit listing
+```
+
+---
+
+## Commit Message Convention
+
+Draft uses [Conventional Commits](https://www.conventionalcommits.org/) for traceability:
+
+```
+<type>(<track_id>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Common `<type>` values: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`.
+
+Footer fields (when applicable):
+- `Refs: <issue or PR number>` — link to issue tracker
+- `Co-Authored-By: <name> <email>` — for AI-assisted commits
+
+If a Jira ticket is linked in `spec.md`, include it in the body or footer:
+```
+feat(add-auth): implement OAuth2 callback
+
+Refs: ENG-1234
+```
+
+---
+
+## Branch Creation
+
+```bash
+git checkout -b <track_id>
+```
+
+Track IDs are kebab-case (e.g., `add-user-auth`, `fix-login-bug`). They become the branch name directly.
+
+---
+
+## Push for Review
+
+```bash
+git push -u origin <branch>
+```
+
+Then open a PR via the `gh` CLI or the GitHub web UI:
+```bash
+gh pr create --title "<title>" --body "<description>"
+```
+
+The PR title should match the track title from `spec.md`. The body should reference the track and include the standard test plan.
+
+---
+
+## Verification Gates
+
+Before any push or PR creation, skills run the project's test/lint commands as defined in `draft/workflow.md` → `## Verification`. Common gates:
+
+- `make test` or `npm test` / `pytest` / `cargo test` — unit tests
+- `make lint` or `npm run lint` / `ruff` / `cargo clippy` — static analysis
+- `make build` or framework-specific build — type-check / compile
+
+If `workflow.md` does not specify gates, skills detect the test framework via `scripts/tools/detect-test-framework.sh` and use sensible defaults.

package/core/shared/verification-gates.md

@@ -0,0 +1,47 @@
+# Verification Gates
+
+> Shared block defining the validator chain every track passes through
+> before promoting status. Imported by quality and implementation flows
+> that gate on artifact correctness.
+
+## The chain
+
+Run in this order. Single non-zero exit aborts the chain.
+
+| Step | Tool | What it checks |
+|------|------|----------------|
+| 1 | `scripts/tools/check-track-hygiene.sh` | status parity, author resolution, approver placeholders, TBD budget vs `metadata.json:status`, plan staleness vs HLD/LLD |
+| 2 | `scripts/tools/verify-citations.sh` | every `path:line` resolves against `metadata.json:synced_to_commit` (±tolerance) |
+| 3 | `scripts/tools/verify-doc-anchors.sh` | `§X.Y` references and `<doc>.md#anchor` links resolve |
+| 4 | `scripts/tools/check-graph-usage-report.sh` | Graph Usage Report footer present and well-formed |
+| 5 | `scripts/tools/check-scope-conflicts.sh` | no overlap with adjacent tracks under same scope tags |
+| 6 | `scripts/tools/diff-templates-vs-tracks.sh` | no drift between track and current template schema |
+
+## Output convention
+
+Each tool emits:
+
+- exit code 0/1 (clean / violations)
+- text mode by default; `--json` for machine-readable
+- one line per violation: `[<kind>] <track>/<file>:<line> — <detail>`
+
+## Result persistence
+
+After the chain runs, persist the outcome to `metadata.json:pre_deploy_status`:
+
+- `unrun` — chain has never executed against this track
+- `passing` — last run exited 0
+- `failing` — last run exited 1; details in CI log
+- `bypassed` — explicit override; requires `bypass_reason` in metadata
+
+`/draft:deploy-checklist` reads this field and refuses to deploy a track
+whose `pre_deploy_status != passing`.
+
+## When to invoke
+
+- `/draft:deploy-checklist` — mandatory before any production deploy.
+- `/draft:implement` — at the end of each phase before flipping
+  `phases.completed`.
+- `/draft:decompose` — after rewriting `plan.md`, to catch plan-staleness
+  immediately.
+- CI hook — gate every merge that touches `tracks/**`.

package/core/templates/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Template Schema Changelog
+
+Semver-style change log for the schema defined by files under `core/templates/`.
+Tracks are generated from these templates by `skills/new-track`, `skills/decompose`,
+and downstream skills. Any change here is a contract change consumed by every
+downstream repo. Major bumps require a `scripts/tools/migrate-track-frontmatter.sh`
+migration path.
+
+## How template versions are referenced
+
+- `metadata.json` carries the optional field `template_version` (semver string).
+- Validators in `scripts/tools/` (hygiene, citations, anchors, scope-conflicts,
+  graph-usage-report) read this field and refuse to lint tracks whose
+  `template_version` major-bumps past the validator's known schema.
+
+## Shared blocks each template depends on
+
+| Template | Depends on (under `core/shared/`) |
+|---|---|
+| `spec.md` | `template-contract.md`, `template-hygiene.md`, `discovery-schema.md` (back-link), `verification-gates.md` |
+| `hld.md` | `template-contract.md`, `template-hygiene.md`, `graph-query.md`, `verification-gates.md` |
+| `lld.md` | `template-contract.md`, `template-hygiene.md`, `graph-query.md`, `verification-gates.md` |
+| `plan.md` | `template-contract.md`, `template-hygiene.md`, `verification-gates.md` |
+| `metadata.json` | `template-contract.md` (canonical schema for ephemeral fields) |
+| `discovery.md` | `discovery-schema.md` |
+
+Templates are markdown-only (and JSON for `metadata.json`). Viewer artifacts
+(HTML/PDF) are rendered on demand by `scripts/tools/render-track.sh` and are
+git-ignored at the track level. No HTML or PDF templates ship here.
+
+## Versions
+
+### 2.0.0 — Templates-as-contract baseline
+
+- **Breaking:** Introduces parseable sentinel placeholders (`_TBD_<field>_`,
+  `_PLACEHOLDER_<kind>_`). Silent placeholders such as `Author1`,
+  `xxx@example.com`, pre-checked `Status: [x] Complete` are forbidden.
+- **Breaking:** Introduces `<!-- REQUIRED -->` and `<!-- OPTIONAL -->` markers
+  next to authorable fields. Hygiene validator gates `ready-for-review` on the
+  required set being populated; optional fields may carry sentinels indefinitely.
+- **New:** `core/templates/discovery.md` becomes a first-class artifact.
+- **New:** `core/templates/CHANGELOG.md` (this file) and
+  `core/shared/template-contract.md` (narrative + field index).
+- **New:** Scope frontmatter — `scope_includes: []`, `scope_excludes: []`.
+  Lives on `spec.md` and mirrored into `metadata.json`.
+- **New:** Table columns required by WS-7 — `concurrency_model`,
+  `aggregate_resource_cap`, `derived_from`, `mitigation_test_id`, `test_id`,
+  `entry_gate_command`, `exit_gate_command`, `owner`, `flag_name`,
+  `cluster_feature_gate`, `kill_switch_test_id`, `runbook_link`,
+  `sunset_criteria`, `promote_to_adr`, `lock_acquired`, `reentrant`,
+  `fault_injection_site`.
+- **New:** `<!-- DECOMPOSE:REGENERATE START -->` / `<!-- ... END -->` markers
+  in `plan.md` so `draft:decompose` can rewrite phase tables without clobbering
+  manual notes outside the markers.
+- **New:** `<!-- META:<key> -->` directives in `spec.md`, `hld.md`, `lld.md`,
+  `plan.md` that pull ephemeral fields from `metadata.json` at render time.
+- **Breaking:** Ephemeral fields stripped from per-file YAML frontmatter —
+  `git.*`, `synced_to_commit`, `classification.*`, `status`. They live solely
+  in `metadata.json` from this version forward.
+- **Migration:** `scripts/tools/migrate-track-frontmatter.sh` rewrites pre-2.0
+  tracks in place (idempotent; emits `.bak`).
+- **Validators:** any commit touching `skills/**` or `scripts/tools/**` that
+  affects artifact schema must also touch `core/templates/**`, or carry
+  `[template-noop]` in the commit message.
+
+### 1.x.y — pre-baseline (historical)
+
+- See `git log -- core/templates/` for changes before 2.0.0. No formal version
+  tagging; downstream consumers relied on `generated_by` and `generated_at`
+  frontmatter only.

package/core/templates/ai-context-export.md

@@ -0,0 +1,8 @@
+---
+name: ai-context-export
+description: Foundations stub — will be expanded with export / summary logic
+---
+
+# ai-context-export (Draft Foundations)
+
+Portable stub. Content generalized from proven internal patterns.