@drafthq/draft 2.7.0

package/skills/bughunt/references/regression-tests.md

@@ -0,0 +1,399 @@
+## Regression Test Generation
+
+For each verified bug, generate a regression test in the **project's native test framework** that would expose the bug as a failing test. **Before writing any new test**, first discover the project's language/framework and whether existing tests already cover (or partially cover) the bug scenario.
+
+### Step 1: Detect Language & Test Framework
+
+Identify the project's language(s) and test framework by examining the codebase:
+
+| Signal | Language | Test Framework | Build/Run Command |
+|--------|----------|---------------|-------------------|
+| `BUILD`/`WORKSPACE`/`MODULE.bazel` + `.cpp`/`.cc`/`.h` | C/C++ | GTest | `bazel build` / `bazel test` |
+| `CMakeLists.txt` + `.cpp`/`.cc` | C/C++ | GTest | `cmake --build` / `ctest` |
+| `go.mod` or `go.sum` | Go | `testing` (stdlib) | `go test` |
+| `pytest.ini`/`pyproject.toml`/`setup.py`/`conftest.py` | Python | pytest | `pytest` |
+| `requirements.txt` + `unittest` imports | Python | unittest | `python -m pytest` |
+| `package.json` + Jest config | JavaScript/TypeScript | Jest | `npx jest` / `npm test` |
+| `package.json` + Vitest config | JavaScript/TypeScript | Vitest | `npx vitest` |
+| `package.json` + Mocha config | JavaScript/TypeScript | Mocha | `npx mocha` |
+| `Cargo.toml` | Rust | built-in `#[test]` | `cargo test` |
+| `pom.xml` | Java | JUnit | `mvn test` |
+| `build.gradle`/`build.gradle.kts` | Java/Kotlin | JUnit | `gradle test` |
+
+**Resolution order:**
+1. Check `draft/tech-stack.md` first — it may explicitly state the test framework
+2. Look for existing test files and match their import/framework patterns
+3. Fall back to build system signals above
+
+If the project is **polyglot** (multiple languages), detect per-component and generate tests in the matching language for each bug.
+
+**If no test framework is detected:** Mark all bugs with `Regression Test Status: N/A — no test framework detected` and proceed with bug reporting. **Do not skip bugs because tests cannot be written.** The regression test section is supplementary — the primary deliverable is the bug report.
+
+Record the detected configuration:
+```
+Language: [detected | none]
+Test Framework: [detected | none]
+Build System: [detected | none]
+Test Command: [detected | N/A]
+```
+
+### Step 2: Existing Test Discovery (REQUIRED per bug, skip if no test framework)
+
+For each verified bug, search the codebase for existing tests before generating new ones:
+
+1. **Locate test files for the buggy module** using language-appropriate patterns:
+
+   | Language | Search Patterns |
+   |----------|----------------|
+   | C/C++ | `*_test.cpp`, `*_test.cc`, `test_*.cpp`; patterns: `TEST(`, `TEST_F(`, `TEST_P(` |
+   | Go | `*_test.go` in same package; patterns: `func Test`, `func Benchmark` |
+   | Python | `test_*.py`, `*_test.py` in `tests/`; patterns: `def test_`, `class Test` |
+   | JS/TS | `*.test.ts`, `*.spec.ts`, `__tests__/*.ts`; patterns: `describe(`, `it(`, `test(` |
+   | Rust | `#[cfg(test)]` in same file, or `tests/*.rs`; patterns: `#[test]`, `fn test_` |
+   | Java | `*Test.java`, `*Tests.java` in `src/test/`; patterns: `@Test`, `@ParameterizedTest` |
+
+2. **Analyze existing test coverage**
+   - Read each related test file found
+   - Check if any test exercises the **exact code path** that triggers the bug
+   - Check if any test covers the **same function/method** but misses the specific edge case
+   - Check if a test exists but has a **wrong assertion** (asserts buggy behavior as correct)
+
+3. **Classify the coverage status** — one of:
+
+   | Status | Meaning | Action |
+   |--------|---------|--------|
+   | **COVERED** | Existing test already catches this bug (test fails on buggy code) | Report the existing test — no new test needed |
+   | **PARTIAL** | Test exists for the function but misses this specific scenario | Add the missing case to the existing test file |
+   | **WRONG_ASSERTION** | Test exists but asserts the buggy behavior as correct | Fix the assertion in the existing test |
+   | **NO_COVERAGE** | No test exists for this code path | Generate a new test |
+   | **N/A** | Bug is in non-testable code (config, markdown, LLM workflow) | Write `N/A — [reason]` |
+
+4. **Document discovery results** in the bug report's Regression Test field
+
+**Example Existing Test Discovery:**
+```
+1. Bug location: src/parser.cpp:145 — off-by-one in tokenize()
+2. Grep: `rg 'tokenize' tests/` → found tests/parser_test.cpp
+3. Read tests/parser_test.cpp:
+   - TEST(Parser, TokenizeSimpleInput) — tests basic input ✓
+   - TEST(Parser, TokenizeEmptyString) — tests empty string ✓
+   - No test for boundary input length (the bug trigger)
+4. Status: PARTIAL — parser_test.cpp covers tokenize() but misses boundary case
+5. Action: Add new TEST case to existing tests/parser_test.cpp
+```
+
+### Step 3: Generate or Modify Test Cases
+
+Based on discovery results, generate tests in the project's native framework:
+
+#### When status is COVERED
+```
+**Regression Test:**
+**Status:** COVERED — existing test already catches this bug
+**Existing Test:** `tests/parser_test.cpp:45` — `TEST(Parser, TokenizeBoundary)`
+No new test needed.
+```
+
+#### When status is PARTIAL — add to existing test file
+#### When status is WRONG_ASSERTION — fix assertion in existing test
+#### When status is NO_COVERAGE — generate new test
+
+### Test Case Requirements (all languages)
+
+Each new test MUST:
+
+1. **Target exactly one bug** — One test per finding, named after the bug
+2. **Use descriptive test names** — Language-idiomatic naming (see templates below)
+3. **Include the bug setup** — Reproduce the preconditions that trigger the bug
+4. **Assert the expected (correct) behavior** — The test should FAIL against the current buggy code
+5. **Comment the expected vs actual** — Explain what the test expects and what currently happens
+6. **Be self-contained** — Include necessary imports, minimal fixtures, no external dependencies beyond the test framework and project modules
+7. **Specify target file** — State whether this goes in an existing test file or a new one
+
+### Language-Specific Test Templates
+
+#### C/C++ (GTest)
+
+```cpp
+#include <gtest/gtest.h>
+// #include "relevant/project/header.h"
+
+// Bug: [SEVERITY] Category: Brief Title
+// Location: path/to/file.cpp:line
+// This test FAILS against current code, PASSES after fix
+
+TEST(BugCategory, BriefBugTitle) {
+    // Setup
+    // Act
+    // Assert
+    EXPECT_EQ(actual, expected) << "Description of what should happen";
+}
+```
+
+#### Python (pytest)
+
+```python
+# Bug: [SEVERITY] Category: Brief Title
+# Location: path/to/file.py:line
+# This test FAILS against current code, PASSES after fix
+
+import pytest
+from module.under.test import function_under_test
+
+
+def test_brief_bug_title():
+    """[Category] Brief description of the bug scenario."""
+    # Setup
+    # Act
+    result = function_under_test(input)
+    # Assert
+    assert result == expected, "Description of what should happen"
+```
+
+#### Go (testing)
+
+```go
+package package_name
+
+import (
+    "testing"
+    // project imports
+)
+
+// Bug: [SEVERITY] Category: Brief Title
+// Location: path/to/file.go:line
+// This test FAILS against current code, PASSES after fix
+
+func TestBriefBugTitle(t *testing.T) {
+    // Setup
+    // Act
+    got := FunctionUnderTest(input)
+    // Assert
+    if got != expected {
+        t.Errorf("FunctionUnderTest() = %v, want %v", got, expected)
+    }
+}
+```
+
+#### JavaScript/TypeScript (Jest/Vitest)
+
+```typescript
+// Bug: [SEVERITY] Category: Brief Title
+// Location: path/to/file.ts:line
+// This test FAILS against current code, PASSES after fix
+
+import { functionUnderTest } from './module-under-test';
+
+describe('BugCategory', () => {
+  it('should brief bug title', () => {
+    // Setup
+    // Act
+    const result = functionUnderTest(input);
+    // Assert
+    expect(result).toBe(expected);
+  });
+});
+```
+
+#### Rust (#[test])
+
+```rust
+// Bug: [SEVERITY] Category: Brief Title
+// Location: path/to/file.rs:line
+// This test FAILS against current code, PASSES after fix
+
+#[cfg(test)]
+mod bug_regression_tests {
+    use super::*;
+
+    #[test]
+    fn test_brief_bug_title() {
+        // Setup
+        // Act
+        let result = function_under_test(input);
+        // Assert
+        assert_eq!(result, expected, "Description of what should happen");
+    }
+}
+```
+
+#### Java (JUnit 5)
+
+```java
+// Bug: [SEVERITY] Category: Brief Title
+// Location: path/to/File.java:line
+// This test FAILS against current code, PASSES after fix
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+class BugCategoryTest {
+    @Test
+    void briefBugTitle() {
+        // Setup
+        // Act
+        var result = classUnderTest.methodUnderTest(input);
+        // Assert
+        assertEquals(expected, result, "Description of what should happen");
+    }
+}
+```
+
+### Consolidated Test File
+
+After all bugs are documented, collect all test cases into a single consolidated section in the report (see Report Generation). Group by discovery status so the reader knows which tests are new vs modifications to existing tests.
+
+### Step 4: Test Infrastructure Discovery
+
+Before writing any test files, discover the project's test infrastructure and conventions:
+
+1. **Detect Build System & Test Runner**
+
+   | Language | Build System Signals | Test Runner |
+   |----------|---------------------|-------------|
+   | C/C++ | `WORKSPACE`/`MODULE.bazel` → Bazel; `CMakeLists.txt` → CMake | `bazel test` / `ctest` |
+   | Go | `go.mod` (always present) | `go test ./...` |
+   | Python | `pyproject.toml` / `setup.cfg` / `tox.ini` / bare | `pytest` (prefer) / `python -m unittest` |
+   | JS/TS | `package.json` → check `scripts.test` and devDeps | `npx jest` / `npx vitest` / `npm test` |
+   | Rust | `Cargo.toml` (always present) | `cargo test` |
+   | Java | `pom.xml` → Maven; `build.gradle` → Gradle | `mvn test` / `gradle test` |
+
+   If no recognized build system is found, inform user and keep report-only test output:
+   `"No recognized build/test system detected. Regression tests are included in the report only."`
+
+2. **Map Source Files to Test Locations**
+   For each buggy source file, determine where its tests live (or should live):
+
+   | Language | Common Conventions |
+   |----------|--------------------|
+   | C/C++ (Bazel) | Co-located `foo_test.cpp` or separate `tests/` tree; check `cc_test` in BUILD |
+   | Go | Same directory: `foo.go` → `foo_test.go` (always co-located) |
+   | Python | `src/auth/handler.py` → `tests/auth/test_handler.py` or `tests/test_auth_handler.py` |
+   | JS/TS | `src/auth/handler.ts` → `src/auth/handler.test.ts` or `__tests__/handler.test.ts` |
+   | Rust | In-file `#[cfg(test)]` module, or `tests/` directory for integration tests |
+   | Java | `src/main/java/com/...` → `src/test/java/com/...` (Maven convention) |
+
+   - If tests exist: record the directory, naming convention, and any build config
+   - If no tests exist: adopt the project's dominant convention
+   - If no convention exists: default to a `tests/` directory mirroring the source tree
+
+3. **Identify Test Dependencies** (language-specific)
+
+   | Language | What to Find |
+   |----------|-------------|
+   | C/C++ (Bazel) | GTest dep label: `@com_google_googletest//:gtest_main`; source `cc_library` targets |
+   | Go | No extra deps needed (`testing` is stdlib) |
+   | Python | Check if `pytest` is in `requirements*.txt` / `pyproject.toml`; add if missing |
+   | JS/TS | Check if test framework is in `devDependencies`; identify import style |
+   | Rust | No extra deps for unit tests; `dev-dependencies` for integration test crates |
+   | Java | JUnit version in `pom.xml` / `build.gradle` dependencies |
+
+### Step 5: Write Test Files (only for testable bugs)
+
+**Skip this step entirely if no test framework was detected in Step 1.**
+
+For bugs with status NO_COVERAGE, PARTIAL, or WRONG_ASSERTION, write the actual test files. Bugs with COVERED or N/A status do not need action here — they are still included in the final report:
+
+#### NO_COVERAGE — Create new test file
+
+1. **Create directory** if it doesn't exist:
+   ```bash
+   mkdir -p <test_directory>/
+   ```
+
+2. **Write the test file** using the language-appropriate template:
+
+   | Language | Example Target File |
+   |----------|-------------------|
+   | C/C++ | `tests/auth/login_handler_test.cpp` |
+   | Go | `auth/login_handler_test.go` (same package) |
+   | Python | `tests/auth/test_login_handler.py` |
+   | JS/TS | `src/auth/login_handler.test.ts` or `__tests__/auth/login_handler.test.ts` |
+   | Rust | `tests/login_handler_test.rs` or `#[cfg(test)]` in source |
+   | Java | `src/test/java/com/example/auth/LoginHandlerTest.java` |
+
+3. **Create or update build config** (if required by the build system):
+
+   **C/C++ (Bazel)** — add `cc_test` to BUILD:
+   ```python
+   cc_test(
+       name = "<source_filename>_test",
+       srcs = ["<source_filename>_test.cpp"],
+       deps = [
+           "//src/<component>:<library_target>",
+           "@com_google_googletest//:gtest_main",
+       ],
+   )
+   ```
+
+   **Java (Maven)** — no build config change needed (convention-based discovery)
+   **Java (Gradle)** — no build config change needed
+   **Go** — no build config change needed (`go test` discovers `_test.go` automatically)
+   **Python** — no build config change needed (`pytest` discovers `test_*.py` automatically)
+   **JS/TS** — no build config change needed (Jest/Vitest discover `*.test.*` automatically)
+   **Rust** — no build config change needed (`cargo test` discovers `#[test]` automatically)
+
+4. If multiple bugs affect different files in the same component, create one test file per source file (not one per bug). Group related bug tests into the same file.
+
+#### PARTIAL — Add test case to existing file
+
+1. Read the existing test file
+2. Append the new test at the idiomatic location:
+   - **C/C++:** Before closing namespace brace
+   - **Go:** End of file (same package)
+   - **Python:** End of file or within existing test class
+   - **JS/TS:** Inside the relevant `describe()` block, or at end of file
+   - **Rust:** Inside existing `#[cfg(test)]` module
+   - **Java:** Inside existing test class, before closing brace
+3. No build config changes needed
+
+#### WRONG_ASSERTION — Fix assertion in existing file
+
+1. Read the existing test file
+2. Locate the wrong assertion
+3. Replace with the corrected assertion
+4. No build config changes needed
+
+**Constraints:**
+- **Never modify production source code** — only test files and their build configs
+- Each test file must be valid for the project's test runner
+- Use the project's actual import paths, module names, and namespace conventions
+- Match existing test style (fixtures, helpers, naming conventions)
+
+### Step 6: Build & Syntax Validation
+
+After writing all test files, validate them using the project's native toolchain.
+
+1. **Validate each new/modified test** using the language-appropriate command:
+
+   | Language | Validation Command | What It Checks |
+   |----------|-------------------|----------------|
+   | C/C++ (Bazel) | `bazel build //tests/<component>:<target>_test` | Compilation + linking |
+   | C/C++ (CMake) | `cmake --build <build_dir> --target <target>_test` | Compilation + linking |
+   | Go | `go vet ./path/to/package/...` | Syntax + type checking (no execution) |
+   | Python | `python -m py_compile tests/path/test_file.py` | Syntax validation |
+   | JS/TS | `npx tsc --noEmit tests/path/file.test.ts` (TS) or `node --check tests/path/file.test.js` (JS) | Type check / syntax |
+   | Rust | `cargo check --tests` | Type check + borrow check (no execution) |
+   | Java (Maven) | `mvn test-compile` | Compilation only |
+   | Java (Gradle) | `gradle testClasses` | Compilation only |
+
+2. **Handle validation results:**
+
+   | Result | Action |
+   |--------|--------|
+   | **Succeeds** | Mark as `BUILD_OK` in report |
+   | **Fails — import/include error** | Fix the import path, retry (up to 2 retries) |
+   | **Fails — missing dep** | Add the dependency, retry (up to 2 retries) |
+   | **Fails — type/API mismatch** | Fix the test to match actual API signatures, retry (up to 2 retries) |
+   | **Persistent failure (3 attempts)** | Mark as `BUILD_FAILED` with the error message in report. Delete the broken test file and note in the report: "Test file removed due to persistent build failure." |
+
+3. **Do NOT run the tests.** The tests are designed to **FAIL** against the current buggy code — that's the point. Validation checks only syntax, types, and linking. Running them would produce expected failures that aren't useful here.
+
+   **Exception for Go:** `go vet` is preferred over `go build` for test files because Go compiles tests as part of `go test` only. `go vet` catches type errors and common issues without executing.
+
+4. **Validation summary** — Record results for the report:
+   ```
+   BUILD_OK:     3 targets
+   BUILD_FAILED: 1 target (tests/config/test_loader.py — ImportError: no module named 'config.loader')
+   SKIPPED:      1 target (N/A — race condition not reliably testable)
+   ```

package/skills/change/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: change
+description: Handle mid-track requirement changes. Analyzes impact on completed and pending tasks, proposes amendments to spec.md and plan.md before applying.
+---
+
+# Course Correction
+
+You are handling a mid-track requirement change using Draft's Context-Driven Development methodology.
+
+## 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
+- Proceeding past the CHECKPOINT without user confirmation
+- Editing files when the user said "no" or "edit"
+
+**Show impact before applying. Always confirm.**
+
+---
+
+## Step 0: Verify Draft Context
+
+```bash
+ls draft/tracks.md 2>/dev/null
+```
+
+If `draft/` does not exist: **STOP** — "No Draft context found. Run `/draft:init` first."
+
+---
+
+## Step 1: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+
+- **Change description** — free text describing what needs to change (required)
+- **Track specifier** — optional `track <id>` prefix to target a specific track
+
+### 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>`"
+
+---
+
+## Step 2: Load Context
+
+1. Read `draft/tracks/<id>/spec.md` — extract requirements and acceptance criteria
+2. Read `draft/tracks/<id>/plan.md` — extract all tasks with their current status (`[ ]`, `[~]`, `[x]`, `[!]`)
+3. Read `draft/tracks/<id>/metadata.json` — for track type and status
+4. Read `draft/tracks/<id>/hld.md` if present — extract Architecture, Detailed Design components, Dependencies, Checklist sections, and Approvals table (signed/unsigned)
+5. Read `draft/tracks/<id>/lld.md` if present — extract Classes/Interfaces, Data Model, Algorithms, Error Handling sections
+
+---
+
+## Step 3: Analyze Spec / HLD / LLD Impact
+
+Analyze the change description against the loaded spec, HLD, and LLD.
+
+**Code-grounded impact (Ground-Truth Discipline G1, G2, G4):** Classification ("Modified", "Unaffected", etc.) must be informed by the current code, not just the prior spec text. For each requirement / AC you're about to mark **Unaffected**, confirm the code path it depends on still behaves as the spec claims — Read the cited file or a representative file in the affected module before stamping Unaffected. Specs and implementations drift; "spec text unchanged" ≠ "behavior unchanged."
+
+For each requirement and acceptance criterion, classify the effect:
+
+| Classification | Meaning |
+|---|---|
+| **Added** | New requirement or AC introduced by this change |
+| **Modified** | Existing requirement or AC needs updating |
+| **Removed** | Existing requirement or AC is no longer needed |
+| **Unaffected** | No change needed |
+
+Produce a concise impact list. Example:
+```
+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)
+- NEW: AC #6 "Export progress indicator for large datasets"
+```
+
+**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?
+- §Checklist (Performance, Scale, Security, Resiliency, Multi-tenancy, Upgrade, Cost) — do any answers need re-evaluation?
+- §IP / TPT — does the change introduce new third-party technology or invention disclosure?
+- §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?
+- §Error Handling — new error classes or retry policy changes?
+- §Observability — new metrics or alert thresholds?
+
+**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:
+
+```
+⚠️ 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]
+```
+
+Same logic applies to LLD Approvals when LLD §Classes/Interfaces, §Data Model, or §Key Algorithms change.
+
+---
+
+## Step 4: Map Impact to Plan Tasks
+
+For each task in `plan.md`, determine if the spec change affects it:
+
+- **`[x]` completed tasks** that are now invalidated by the change → flag as:
+  `⚠️ [task description] — may need rework`
+
+- **`[ ]` pending tasks** that need updating → show the proposed new task text
+
+- **`[~]` in-progress tasks** that are affected → flag as:
+  `⚠️ IN PROGRESS: [task description] — review before continuing`
+
+- **`[!]` blocked tasks** that are affected → flag as:
+  `⚠️ BLOCKED: [task description] — re-evaluate; requirement change may alter blocking condition or resolution path`
+
+- **Unaffected tasks** — skip, do not mention
+
+---
+
+## Step 5: Present Impact Summary
+
+Display a clear summary before proposing any file changes:
+
+```
+Change: [change description]
+Track: <track_id> — <track_name>
+
+Spec impact:
+  - [classification] [requirement/AC]
+  - [classification] [requirement/AC]
+
+Plan impact:
+  - ⚠️ [N] completed task(s) may need rework
+  - [M] pending task(s) need updating
+  - [K] in-progress task(s) need review
+  - [B] blocked task(s) need re-evaluation
+
+Completed tasks that may need rework:
+  - [x] [task description] (commit: abc1234)
+
+Pending tasks with proposed changes:
+  Before: - [ ] [original task text]
+  After: - [ ] [proposed new task text]
+```
+
+---
+
+## Step 6: Show Proposed Amendments
+
+Display only the changed sections of each file (not full rewrites):
+
+### Proposed spec.md changes
+
+Show the diff as before/after for each modified section. Do not rewrite unchanged sections.
+
+### Proposed plan.md changes
+
+Show each task that would be modified as before/after. Do not rewrite the full plan.
+
+### Proposed hld.md changes (when HLD exists and is impacted)
+
+Show before/after for each impacted HLD section. Preserve §Approvals table verbatim — do not modify Approvals as part of the spec amendment; re-circulation is the author's manual step. Surface a "Sections changed" list at the top of the diff so reviewers can see scope at a glance.
+
+### Proposed lld.md changes (when LLD exists and is impacted)
+
+Show before/after for each impacted LLD section. Preserve §Approvals verbatim. Flag schema changes (Data Model) for migration consideration.
+
+---
+
+## Step 7: CHECKPOINT
+
+```
+Apply these changes to spec.md and plan.md? [yes / no / edit]
+```
+
+- **`yes`** — proceed to Step 8
+- **`no`** — discard all proposed changes, announce "No changes applied." and stop
+- **`edit`** — let the user describe adjustments to the proposed amendments, then revise and re-present the CHECKPOINT again. The loop continues until the user selects `yes` or `no`.
+
+---
+
+## Step 8: Apply Changes and Log
+
+1. Apply the agreed amendments to `spec.md`, `plan.md`, and (when impacted) `hld.md` / `lld.md`. Preserve §Approvals tables in HLD/LLD verbatim — re-approval is a manual author step, not an automated edit.
+
+2. Update `draft/tracks/<id>/metadata.json`:
+   - Set `updated` to current ISO timestamp
+   - Recalculate `tasks.total` by counting all `- [ ]`, `- [~]`, `- [x]`, and `- [!]` lines in the updated `plan.md`. Update `tasks.completed` by counting only `- [x]` lines.
+
+3. Append a Change Log entry (with current git SHA (obtain via `git rev-parse --short HEAD`) and timestamp) to `plan.md`. If a `## Change Log` section does not exist, add it at the bottom:
+
+```markdown
+## Change Log
+
+| Date | Description | Impact |
+|------|-------------|--------|
+| [ISO date] | [change description] | [N completed may need rework, M pending updated] |
+```
+
+4. Announce:
+
+```
+Changes applied: <track_id>
+
+Updated:
+- draft/tracks/<id>/spec.md
+- draft/tracks/<id>/plan.md
+[when HLD impacted:]
+- draft/tracks/<id>/hld.md
+[when LLD impacted:]
+- draft/tracks/<id>/lld.md
+
+[If completed tasks flagged:]
+⚠️ Review N completed task(s) — they may not align with the updated spec.
+    Re-run /draft:implement to address rework, or /draft:review to assess.
+
+[If HLD/LLD modified after sign-off:]
+⚠️ HLD/LLD modified after sign-off — re-circulate to approvers listed in §Approvals.
+    /draft:upload will block git upload for high-criticality tracks until re-signed.
+
+Next: /draft:implement to continue, or /draft:review to assess current state.
+```
+
+---
+
+## Error Handling
+
+### Track Not Found
+```
+Error: Track '<id>' not found.
+Run /draft:status to see available tracks.
+```
+
+### No Active Track
+```
+Error: No active track found.
+Use: /draft:change track <id> <description>
+```
+
+### No Spec or Plan
+```
+Error: Missing spec.md or plan.md for track <id>.
+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
+```