dw-kit 1.6.0-rc.1 → 1.7.0-rc.1

package/.dw/core/schemas/goal-frontmatter.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/goal-frontmatter.schema.json",
+  "title": "goal@v1",
+  "description": "Frontmatter schema for .dw/goals/{goal-id}/goal.md (ADR-0010 Goals Management Layer, v1.7).",
+  "type": "object",
+  "required": [
+    "goal_id",
+    "schema_version",
+    "created",
+    "last_updated",
+    "status",
+    "owner",
+    "goal_version"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "goal_id": {
+      "type": "string",
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$",
+      "description": "Goal identifier. Format G-{slug}; uniqueness enforced via goals-index.json (W-1)."
+    },
+    "schema_version": {
+      "type": "string",
+      "const": "goal@v1",
+      "description": "Schema version. Upgrade path via `dw goal migrate --to goal@v2` (S-1)."
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD"
+    },
+    "last_updated": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Active", "Achieved", "Abandoned", "Pivoted"],
+      "description": "Q3 OKR-style lifecycle. Status transitions auto-bump goal_version (Q4/C-1)."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Person responsible for shipping this goal."
+    },
+    "target_date": {
+      "type": ["string", "null"],
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$|^TBD$",
+      "description": "ISO date YYYY-MM-DD or 'TBD' or null."
+    },
+    "goal_version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Q4/C-1: Bumped only on manual `dw goal bump --reason` or status transition (goal_status_changed event). Field edits (KR progress, summary) emit goal_field_updated event without counter increment."
+    },
+    "archived_at": {
+      "type": ["string", "null"],
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "C-2: Soft-delete timestamp ISO UTC. null = active. Set automatically when status transitions to Abandoned or via `dw goal delete`."
+    },
+    "parent_goal_id": {
+      "type": ["string", "null"],
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$|^none$",
+      "description": "Optional parent goal (for sub-goals). 'none' or null = top-level goal."
+    },
+    "summary": {
+      "type": ["string", "null"],
+      "maxLength": 1000,
+      "description": "≤1000-char short-form (agentchattr borrow). Mirrored to goals-index.json for O(1) portfolio reads + Tier 1 agent reaction."
+    },
+    "icon": {
+      "type": ["string", "null"],
+      "maxLength": 8,
+      "description": "Optional emoji/icon for visual differentiation in portfolio cards (bigokr borrow)."
+    },
+    "cycle": {
+      "type": ["string", "null"],
+      "maxLength": 32,
+      "description": "Optional temporal grouping label e.g. 'Q1 2026', 'v1.7-cycle', '2026 H1' (bigokr borrow). Portfolio groups goals by cycle."
+    }
+  }
+}

package/.dw/core/schemas/task-frontmatter.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/task-frontmatter.schema.json",
   "title": "task-frontmatter",
-  "description": "Frontmatter schema for .dw/tasks/{name}/task.md (v3 task format per ADR-0008)",
+  "description": "Frontmatter schema for .dw/tasks/{name}/task.md (v3 task format per ADR-0008; v3.1 adds optional goal linkage + summary per ADR-0010)",
   "type": "object",
   "required": [
     "task_id",
@@ -67,12 +67,31 @@
     },
     "schema_version": {
       "type": "string",
-      "const": "v3.0",
-      "description": "Frontmatter schema version. Bumped only on breaking schema change."
+      "enum": ["v3.0", "v3.1"],
+      "description": "Frontmatter schema version. v3.1 adds optional parent_goal_id, contributing_goal_ids, summary per ADR-0010."
     },
     "blockers": {
       "type": "string",
       "description": "Current blockers in free-form text; use 'none' if unblocked"
+    },
+    "parent_goal_id": {
+      "type": ["string", "null"],
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$|^none$",
+      "description": "v3.1 (ADR-0010 Q1): Primary goal this task contributes to. Single goal; ownership semantics. Format G-{slug} or 'none' or null."
+    },
+    "contributing_goal_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$"
+      },
+      "uniqueItems": true,
+      "description": "v3.1 (ADR-0010 Q1): Optional secondary goals task contributes to. Informational only; no ownership/portfolio-placement effect."
+    },
+    "summary": {
+      "type": ["string", "null"],
+      "maxLength": 1000,
+      "description": "v3.1 (ADR-0010 + agentchattr borrow): ≤1000-char short-form for portfolio cards + Tier 1 agent reaction. Mirrored to goals-index.json/active-index when applicable."
     }
   }
 }

package/.dw/core/templates/v3/goal.md

@@ -0,0 +1,146 @@
+---
+goal_id: G-{slug}
+schema_version: goal@v1
+created: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+status: Draft
+owner: {name}
+target_date: {YYYY-MM-DD or TBD}
+goal_version: 1
+archived_at: null
+parent_goal_id: none
+icon: "🎯"
+cycle: "{Q1 2026 | v1.7-cycle | 2026 H1 | null}"
+summary: "{≤1000-char short-form for portfolio cards + agent reaction; mirrored to goals-index.json}"
+---
+
+# Goal: {Title}
+
+<!--
+Goals Management Layer (ADR-0010 Accepted Round 2, 2026-05-22).
+
+This template mirrors task.md v3 structure (dual-projection per ADR-0008) so
+agents and humans navigate goal.md and task.md with the same mental model.
+
+Status lives ONLY in Section 3 (Subtask/KR Tracker) — never in Section 2.
+Status transitions auto-bump goal_version per Q4/C-1; non-status field edits
+emit goal_field_updated event without counter increment.
+
+Sidecar SVG (timeline-goal.svg) auto-rendered by `dw goal render` once
+dw-kit-render `renderGoal()` ships (R-G6 telemetry-gated, post-P1).
+-->
+
+<!-- ![Goal Timeline](./goal.svg) -->
+
+## 1. Snapshot
+
+**Status:** {Draft | Active | Achieved | Abandoned | Pivoted}
+**Owner:** {name}
+**Target date:** {YYYY-MM-DD or TBD}
+**Goal version:** {1}
+**Last updated:** {YYYY-MM-DD}
+**Linked tasks:** {auto-populated from `dw goal lint` or `dw goal portfolio`}
+
+## 2. Statement
+
+<!--
+Section 2 is the stable intent contract. Per lint convention, status markers
+(✅, 🟡, dates) MUST NOT appear in Section 2 — those live exclusively in
+Section 3 (Tracker). Section 2 changes only when intent or scope genuinely
+changes (auto-bumps goal_version via `dw goal bump --reason`).
+-->
+
+### What
+
+{1-2 paragraphs — what outcome this goal is chasing. No background padding.}
+
+### Why Now
+
+{Forcing function: deadline, market signal, dependency, strategic bet.}
+
+### Out of Scope
+
+- {Explicit exclusions — prevents goal scope creep into Jira-lite territory (R-G1)}
+
+## 3. Key Results & Linked Tasks Tracker
+
+<!--
+SINGLE SOURCE OF TRUTH for KR status. This is the only section where status
+markers (⬜🟡✅🔴⏸) are allowed. KR progress is percentage 0-100% per Q2.
+Linked tasks auto-populated from frontmatter parent_goal_id / contributing_goal_ids
+in task.md v3.1.
+-->
+
+### Key Results
+
+| # | Key Result | Target | Current | Status | Notes |
+|---|-----------|--------|---------|--------|-------|
+| KR-001 | {measurable outcome} | {100%} | {0%} | ⬜ Pending | |
+| KR-002 | ... | ... | ... | ⬜ Pending | |
+
+Status legend: ⬜ Pending · 🟡 In Progress · ✅ Achieved · 🔴 Blocked · ⏸ Paused
+
+### Linked Tasks
+
+| Task | Role | KR | Status |
+|------|------|----|--------|
+| {auto-populated by `dw goal lint`} | primary/contributing | KR-N | ... |
+
+## 4. Timeline / Changelog
+
+<!--
+Reverse-chronological. Each pivot or material change = one heading. Section
+auto-rotates per goal_version bump (manual `dw goal bump --reason` or status
+transition). Field edits emit events to events-global.jsonl WITHOUT bumping
+this section (Q4/C-1 separation).
+-->
+
+```mermaid
+timeline
+    title Goal Lifecycle
+    {YYYY-MM-DD} : Drafted (v1)
+```
+
+### {YYYY-MM-DD} — Goal drafted (version 1)
+
+**Statement:**
+{snapshot of Section 2 at creation time for diff history}
+
+**Key Results defined:**
+- KR-001: ...
+- KR-002: ...
+
+**Initial target date:** {YYYY-MM-DD or TBD}
+
+## 5. Handoff & Annotations
+
+<!--
+Cross-session context for agents picking up work on this goal. Annotations
+(canvas-style sticky notes) live in peer file goal-annotations.md per Q6
+(ADR-0010 P6 scope).
+-->
+
+**For next session (or next agent):**
+
+- **Read first:** {related ADRs, parent goal if any, linked task.md files}
+- **Current state:** {phase, blocked-on, last decision}
+- **Don't do:** {anti-patterns specific to this goal}
+- **Watch out:** {strategic risks, dependencies, stakeholder commitments}
+
+### Friction Journal
+
+| Date | Friction | Component | Proposed fix |
+|------|----------|-----------|-------------|
+| {YYYY-MM-DD} | ... | ... | ... |
+
+## 6. Annexes
+
+<!--
+Free-form supplements. Recommended names:
+- baseline.md — initial metrics
+- pivot-r{N}.md — pivot rationale
+- goal-annotations.md — canvas annotations (P6+)
+- timeline-history.md — auto-rotated overflow
+-->
+
+- (none)

package/CLAUDE.md

@@ -3,7 +3,7 @@
 Workflow toolkit codebase. Rules live in `.claude/rules/` (auto-loaded).
 
 **v2.0 direction:** Context-First SDLC Governance Layer (5 pillars — see `.dw/core/PILLARS.md`)
-**Current:** v1.3.6 (released 2026-05-14) · ADR-0001 active · ADR-0005 + ADR-0006 Accepted (Supply-Chain Guard 3-pillar AI-Native; sunset review 2026-08-12 per pillar) · v1.4 cuts pending telemetry · **ADR-0008 Accepted (task docs v3 = 1-file `task.md` + 3-tier auto-sync sidecar)** shipped v1.5 (commit 2030dd2) · **ADR-0009 Accepted Round 2 (Agent OS multi-agent orchestration)** — execution task `agent-os-orchestration` shipping v1.6 (rc.1 candidate)
+**Current:** v1.6.0-rc.1 on npm `rc` tag (2026-05-20) + **v1.7.0-rc.1 candidate** on `feat/goals-okr-v1.7` shipping ADR-0010 Goals Management Layer (Accepted Round 2 — all 4 Critical + 7 Warnings + 4 Suggestions resolved; `bcurts/agentchattr` summary primitive + bigokr icon/cycle/progress/constellation visualization borrowed; 150/150 smoke tests). Active ADRs: ADR-0001 (Pragmatic Lean), ADR-0005/0006 (Supply-Chain Guard; sunset review 2026-08-12), ADR-0008 (Task Docs v3, v1.5), ADR-0009 (Agent OS, v1.6), ADR-0010 (Goals Layer, v1.7). v1.4 cuts pending telemetry.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.6.0-rc.1",
+  "version": "1.7.0-rc.1",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -121,13 +121,14 @@ export function run(argv) {
 
   taskCmd
     .command('migrate [task-name]')
-    .description('Migrate v2 spec.md + tracking.md → v3 task.md')
+    .description('Migrate v2 spec.md + tracking.md → v3 task.md, OR bump v3.0 → v3.1 schema (--to-v3.1)')
     .option('-n, --dry-run', 'Preview without writing')
     .option('--diff', 'Show diff against existing task.md')
-    .option('--all', 'Scan and migrate all v2 tasks')
+    .option('--all', 'Scan and migrate all v2 tasks (or all v3.0 tasks when --to-v3.1)')
     .option('--force', 'Overwrite existing task.md')
     .option('--remove-v2', 'Delete spec.md/tracking.md after backup (default keeps them)')
     .option('--rollback', 'Restore v2 files from .v2bak backups (requires task name)')
+    .option('--to-v3-1', 'Bump v3.0 → v3.1 schema (adds optional parent_goal_id, contributing_goal_ids, summary fields per ADR-0010)')
     .action(async (taskName, opts) => {
       const { taskMigrateCommand } = await import('./commands/task-migrate.mjs');
       await taskMigrateCommand(taskName, opts);
@@ -178,11 +179,21 @@ export function run(argv) {
     .command('watch [task-name]')
     .description('Watch task.md for changes and live-reload the HTML preview in browser (local server, debounced)')
     .option('-p, --port <port>', 'Local server port (auto-finds next available if busy)', parseInt)
+    .option('--rotate-token', 'Regenerate .dw/cache/watch.token at startup (invalidates old browser sessions; C-3)')
     .action(async (taskName, opts) => {
       const { taskWatchCommand } = await import('./commands/task-watch.mjs');
       await taskWatchCommand(taskName, opts);
     });
 
+  taskCmd
+    .command('summary <task-name>')
+    .description('Read or update task summary frontmatter field (≤1000 chars; agentchattr borrow)')
+    .option('--write <text>', 'Update summary (auto-bumps schema_version v3.0→v3.1 if needed)')
+    .action(async (taskName, opts) => {
+      const { taskSummaryCommand } = await import('./commands/task-summary.mjs');
+      await taskSummaryCommand(taskName, opts);
+    });
+
   const agentCmd = program
     .command('agent')
     .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · claims · reports · conflicts');
@@ -254,6 +265,146 @@ export function run(argv) {
       await agentConflictsCommand(opts);
     });
 
+  const goalCmd = program
+    .command('goal')
+    .description('Goals Management Layer (ADR-0010): strategic layer above tasks. new · show · link · summary · portfolio · lint · bump · delete · view');
+
+  goalCmd
+    .command('new <goal-id>')
+    .description('Create a new goal from template (ID format G-{slug})')
+    .option('--title <text>', 'Goal title (default: "New Goal")')
+    .option('--owner <name>', 'Owner (default: current user)')
+    .option('--target-date <YYYY-MM-DD>', 'Target date (default: TBD)')
+    .option('--icon <emoji>', 'Icon/emoji for portfolio cards (default: 🎯)')
+    .option('--cycle <label>', 'Cycle label e.g. "Q2 2026", "v1.7-cycle"')
+    .option('--summary <text>', 'Initial ≤1000-char summary')
+    .option('--parent-goal-id <id>', 'Parent goal ID for sub-goals')
+    .action(async (goalId, opts) => {
+      const { goalNewCommand } = await import('./commands/goal-new.mjs');
+      await goalNewCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('set <goal-id>')
+    .description('Update goal metadata fields (icon, cycle, owner, target_date, parent_goal_id)')
+    .option('--icon <emoji>', 'Icon/emoji (empty string removes)')
+    .option('--cycle <label>', 'Cycle label (empty string removes)')
+    .option('--owner <name>', 'New owner')
+    .option('--target-date <YYYY-MM-DD>', 'New target date or "TBD"')
+    .option('--parent-goal-id <id>', 'Parent goal ID or "none"')
+    .action(async (goalId, opts) => {
+      const { goalSetCommand } = await import('./commands/goal-set.mjs');
+      await goalSetCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('show [goal-id]')
+    .description('ANSI snapshot of a goal (no arg = list all)')
+    .action(async (goalId, opts) => {
+      const { goalShowCommand } = await import('./commands/goal-show.mjs');
+      await goalShowCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('link <goal-id> <task-id>')
+    .description('Link a task → goal (primary parent_goal_id; --contributing for secondary)')
+    .option('--contributing', 'Add to contributing_goal_ids instead of parent_goal_id (Q1)')
+    .option('-f, --force', 'Override existing parent_goal_id')
+    .action(async (goalId, taskId, opts) => {
+      const { goalLinkCommand } = await import('./commands/goal-link.mjs');
+      await goalLinkCommand(goalId, taskId, opts);
+    });
+
+  goalCmd
+    .command('unlink <goal-id> <task-id>')
+    .description('Remove task→goal mapping (clears both parent_goal_id and contributing_goal_ids)')
+    .action(async (goalId, taskId) => {
+      const { goalUnlinkCommand } = await import('./commands/goal-link.mjs');
+      await goalUnlinkCommand(goalId, taskId);
+    });
+
+  goalCmd
+    .command('summary <goal-id>')
+    .description('Read or update goal summary (≤1000 chars; agentchattr borrow)')
+    .option('--write <text>', 'Update summary (≤1000 chars); auto-syncs to goals-index.json')
+    .action(async (goalId, opts) => {
+      const { goalSummaryCommand } = await import('./commands/goal-summary.mjs');
+      await goalSummaryCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('bump <goal-id>')
+    .description('Manually bump goal_version (Q4 material change; requires --reason)')
+    .option('--reason <text>', 'Reason for the version bump (required)')
+    .action(async (goalId, opts) => {
+      const { goalBumpCommand } = await import('./commands/goal-bump.mjs');
+      await goalBumpCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('delete <goal-id>')
+    .description('Delete a goal (C-2: soft by default, --hard removes folder)')
+    .option('--cascade', 'Clear parent_goal_id / contributing_goal_ids on linked tasks')
+    .option('--hard', 'Hard-delete: remove .dw/goals/{id}/ folder (vs soft = status→Abandoned)')
+    .option('-n, --dry-run', 'Preview without writing')
+    .action(async (goalId, opts) => {
+      const { goalDeleteCommand } = await import('./commands/goal-delete.mjs');
+      await goalDeleteCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('lint [goal-id]')
+    .description('Lint goal.md: frontmatter schema + summary length + index drift + orphan cross-refs')
+    .action(async (goalId, opts) => {
+      const { goalLintCommand } = await import('./commands/goal-lint.mjs');
+      await goalLintCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('portfolio')
+    .description('Show all goals at-a-glance (O(1) read via goals-index.json; W-1)')
+    .option('--status <status>', 'Filter by status (Draft | Active | Achieved | Abandoned | Pivoted)')
+    .action(async (opts) => {
+      const { goalPortfolioCommand } = await import('./commands/goal-portfolio.mjs');
+      await goalPortfolioCommand(opts);
+    });
+
+  goalCmd
+    .command('view [goal-id]')
+    .description('Generate HTML portfolio (P1+P2 joint MVP per W-7)')
+    .option('--no-open', 'Do not auto-open browser')
+    .action(async (goalId, opts) => {
+      const { goalViewCommand } = await import('./commands/goal-view.mjs');
+      await goalViewCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('migrate [goal-id]')
+    .description('Stub for future schema bump (S-1; goal@v1 → goal@v2)')
+    .option('--to <schema>', 'Target schema (default: goal@v2)')
+    .action(async (goalId, opts) => {
+      const { goalMigrateCommand } = await import('./commands/goal-stubs.mjs');
+      await goalMigrateCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('suggest-krs <goal-id>')
+    .description('Build SMART-formatted prompt to paste into AI agent chat for KR brainstorming (W-5)')
+    .option('--count <n>', 'Requested number of KRs (default: 3)', '3')
+    .option('--json', 'Output structured JSON (for agent piping)')
+    .action(async (goalId, opts) => {
+      const { goalSuggestKrsCommand } = await import('./commands/goal-suggest-krs.mjs');
+      await goalSuggestKrsCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('render [goal-id]')
+    .description('Render constellation SVG for goal(s) — goal center + KR satellites + task leaves (R-G6 shipped)')
+    .action(async (goalId, opts) => {
+      const { goalRenderCommand } = await import('./commands/goal-render.mjs');
+      await goalRenderCommand(goalId, opts);
+    });
+
   program
     .command('dashboard')
     .description('Show team dashboard — active tasks, ADRs, telemetry summary, health')

package/src/commands/goal-bump.mjs

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { readGoal, updateGoalFrontmatter, syncIndexEntry, todayIso } from '../lib/goal-store.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+export async function goalBumpCommand(goalId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!goalId) {
+    console.error(chalk.red('✗ Usage: dw goal bump <goal-id> --reason "..."'));
+    process.exit(1);
+  }
+  if (!opts.reason) {
+    console.error(chalk.red('✗ --reason "..." required (Q4: explicit reason for material change)'));
+    process.exit(1);
+  }
+
+  const goal = readGoal(goalId, rootDir);
+  if (!goal) {
+    console.error(chalk.red(`✗ Goal ${goalId} not found`));
+    process.exit(1);
+  }
+
+  const oldVersion = goal.fm.goal_version || 1;
+  const newVersion = oldVersion + 1;
+
+  updateGoalFrontmatter(goalId, (fm) => {
+    fm.goal_version = newVersion;
+    fm.last_updated = todayIso();
+    return fm;
+  }, rootDir);
+  syncIndexEntry(goalId, rootDir);
+
+  logGoalEvent({
+    event: 'goal_pivoted',
+    goal_id: goalId,
+    from_version: oldVersion,
+    to_version: newVersion,
+    summary: opts.reason,
+    changed_by: process.env.USER || process.env.USERNAME || 'unknown',
+  }, rootDir);
+
+  logEvent({ event: 'goal', action: 'bump', name: goalId, from_version: oldVersion, to_version: newVersion }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  ${chalk.bold(goalId)} version ${oldVersion} → ${newVersion}`));
+  console.log(chalk.dim(`     Reason: ${opts.reason}`));
+  console.log(chalk.dim(`     Logged to .dw/events-global.jsonl as goal_pivoted`));
+  console.log();
+}

package/src/commands/goal-delete.mjs

@@ -0,0 +1,120 @@
+import { readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
+import { readGoal, removeIndexEntry, findLinkedTaskIds, goalDir, todayIso, nowUtc } from '../lib/goal-store.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+function clearParentGoalOnTask(taskId, goalId, rootDir = process.cwd()) {
+  const file = join(rootDir, TASKS_DIR, taskId, 'task.md');
+  if (!existsSync(file)) return false;
+  const content = readFileSync(file, 'utf8');
+  const fm = parseFrontmatter(content);
+  let changed = false;
+  if (fm.parent_goal_id === goalId) { fm.parent_goal_id = 'none'; changed = true; }
+  if (Array.isArray(fm.contributing_goal_ids) && fm.contributing_goal_ids.includes(goalId)) {
+    fm.contributing_goal_ids = fm.contributing_goal_ids.filter((id) => id !== goalId);
+    changed = true;
+  }
+  if (!changed) return false;
+  fm.last_updated = todayIso();
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  writeFileSync(file, stringifyFrontmatter(fm) + body, 'utf8');
+  return true;
+}
+
+export async function goalDeleteCommand(goalId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!goalId) {
+    console.error(chalk.red('✗ Usage: dw goal delete <goal-id> [--cascade] [--dry-run] [--hard]'));
+    process.exit(1);
+  }
+
+  const goal = readGoal(goalId, rootDir);
+  if (!goal) {
+    console.error(chalk.red(`✗ Goal ${goalId} not found`));
+    process.exit(1);
+  }
+
+  const linked = findLinkedTaskIds(goalId, rootDir);
+
+  if (opts.dryRun) {
+    console.log();
+    console.log(chalk.cyan(`  Dry-run: delete ${chalk.bold(goalId)}`));
+    console.log(chalk.dim(`     Mode: ${opts.hard ? 'HARD (remove .dw/goals/' + goalId + '/)' : 'SOFT (status → Abandoned, archived_at set)'}`));
+    console.log(chalk.dim(`     Linked tasks (${linked.length}): ${linked.join(', ') || '(none)'}`));
+    if (opts.cascade && linked.length > 0) {
+      console.log(chalk.dim(`     Would clear parent_goal_id/contributing_goal_ids on ${linked.length} task(s)`));
+    } else if (!opts.cascade && linked.length > 0) {
+      console.log(chalk.yellow(`     ⚠  ${linked.length} tasks reference this goal — add --cascade or unlink manually first`));
+    }
+    console.log();
+    return;
+  }
+
+  if (linked.length > 0 && !opts.cascade) {
+    console.error(chalk.red(`✗ ${linked.length} task(s) link to ${goalId} — re-run with --cascade or unlink manually`));
+    console.error(chalk.dim(`  Linked: ${linked.join(', ')}`));
+    process.exit(1);
+  }
+
+  if (opts.cascade) {
+    for (const t of linked) clearParentGoalOnTask(t, goalId, rootDir);
+  }
+
+  if (opts.hard) {
+    rmSync(goalDir(goalId, rootDir), { recursive: true, force: true });
+    removeIndexEntry(goalId, rootDir);
+    logGoalEvent({
+      event: 'goal_archived',
+      goal_id: goalId,
+      archived_at: nowUtc(),
+      mode: 'hard',
+      cascade_task_count: linked.length,
+    }, rootDir);
+    logEvent({ event: 'goal', action: 'delete.hard', name: goalId, cascade_count: linked.length }, rootDir);
+    console.log();
+    console.log(chalk.green(`  ✓  Hard-deleted ${chalk.bold(goalId)} (folder removed)`));
+    console.log(chalk.dim(`     Cleared parent_goal_id on ${linked.length} linked task(s)`));
+    console.log();
+    return;
+  }
+
+  // Soft delete: status → Abandoned, archived_at set, bump version
+  const content = readFileSync(goal.file, 'utf8');
+  const fm = parseFrontmatter(content);
+  const oldVersion = fm.goal_version || 1;
+  fm.status = 'Abandoned';
+  fm.archived_at = nowUtc();
+  fm.goal_version = oldVersion + 1;
+  fm.last_updated = todayIso();
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  writeFileSync(goal.file, stringifyFrontmatter(fm) + body, 'utf8');
+
+  logGoalEvent({
+    event: 'goal_status_changed',
+    goal_id: goalId,
+    from_status: goal.fm.status,
+    to_status: 'Abandoned',
+    changed_by: process.env.USER || process.env.USERNAME || 'unknown',
+  }, rootDir);
+  logGoalEvent({
+    event: 'goal_archived',
+    goal_id: goalId,
+    archived_at: fm.archived_at,
+    mode: 'soft',
+    cascade_task_count: linked.length,
+  }, rootDir);
+
+  logEvent({ event: 'goal', action: 'delete.soft', name: goalId, cascade_count: linked.length }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  Soft-deleted ${chalk.bold(goalId)} (status=Abandoned, archived_at=${fm.archived_at})`));
+  console.log(chalk.dim(`     Cleared parent_goal_id on ${linked.length} linked task(s)`));
+  console.log(chalk.dim(`     To hard-delete folder: dw goal delete ${goalId} --hard`));
+  console.log();
+}