dw-kit 1.4.0 → 1.7.0-rc.1

package/src/commands/doctor.mjs

@@ -191,6 +191,70 @@ export async function doctorCommand() {
     }
   }
 
+  info('Task Docs v3 (ADR-0008)');
+  const templateV3 = join(projectDir, '.dw/core/templates/v3/task.md');
+  const schemaV3 = join(projectDir, '.dw/core/schemas/task-frontmatter.schema.json');
+  if (existsSync(templateV3) && existsSync(schemaV3)) {
+    ok('v3 template + JSON schema present');
+  } else {
+    warn('v3 template/schema not in project — run `dw upgrade` or run from a v1.5+ project');
+    warnings++;
+  }
+  const tasksDir = join(projectDir, '.dw/tasks');
+  if (existsSync(tasksDir)) {
+    const fs = await import('node:fs');
+    const entries = fs.readdirSync(tasksDir).filter((e) => e !== 'archive' && e !== 'ACTIVE.md');
+    let v3 = 0, v2 = 0, v1 = 0, none = 0;
+    for (const e of entries) {
+      const p = join(tasksDir, e);
+      try {
+        if (!fs.statSync(p).isDirectory()) continue;
+        if (existsSync(join(p, 'task.md'))) v3++;
+        else if (existsSync(join(p, 'tracking.md'))) v2++;
+        else if (fs.readdirSync(p).some((f) => f.endsWith('-progress.md'))) v1++;
+        else none++;
+      } catch { /* skip */ }
+    }
+    log(`  Tasks       : ${v3} v3 · ${v2} v2 · ${v1} v1 · ${none} no-tracking`);
+    if (v2 > 0) {
+      log(`  ${v2} v2 task${v2 === 1 ? '' : 's'} can be migrated: \`dw task migrate --all --dry-run\``);
+    }
+  }
+
+  info('Agent OS (ADR-0009)');
+  const claimSchema = join(projectDir, '.dw/core/schemas/agent-claim.schema.json');
+  const reportSchema = join(projectDir, '.dw/core/schemas/agent-report.schema.json');
+  if (existsSync(claimSchema) && existsSync(reportSchema)) {
+    ok('Agent OS schemas (claim + report) present');
+  } else {
+    warn('Agent OS schemas not in project — run `dw upgrade` or use v1.6+ project');
+    warnings++;
+  }
+  const claimsDir = join(projectDir, '.dw/cache/agents/claims');
+  if (existsSync(claimsDir)) {
+    const fs = await import('node:fs');
+    const claimFiles = fs.readdirSync(claimsDir).filter((f) => f.endsWith('.json'));
+    let active = 0, expired = 0, released = 0;
+    const now = Date.now();
+    for (const f of claimFiles) {
+      try {
+        const c = JSON.parse(fs.readFileSync(join(claimsDir, f), 'utf8'));
+        const wallClock = Date.parse(c.lease_expires) || 0;
+        const relative = (Date.parse(c.created_at) || 0) + (c.lease_duration_seconds || 0) * 1000;
+        const effective = Math.max(wallClock, relative);
+        if (c.status === 'released' || c.status === 'invalidated') released++;
+        else if (effective < now) expired++;
+        else active++;
+      } catch { /* skip */ }
+    }
+    log(`  Claims      : ${active} active · ${expired} expired (not reaped) · ${released} released`);
+    if (expired > 0) {
+      log(`  Run \`dw agent claims --status expired\` to inspect; \`dw agent expire <id>\` to reap.`);
+    }
+  } else {
+    log('  Claims      : (no .dw/cache/agents/claims/ yet — first `dw agent claim` will initialize)');
+  }
+
   info('Supply-Chain Guard (ADR-0005, opt-in)');
   const sc = snapshotInfo(projectDir);
   if (!sc.exists) {

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();
+}

package/src/commands/goal-link.mjs

@@ -0,0 +1,126 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
+import { readGoal, syncIndexEntry, todayIso } from '../lib/goal-store.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+
+function taskFile(taskId, rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR, taskId, 'task.md');
+}
+
+function writeTaskFrontmatter(taskId, mutator, rootDir = process.cwd()) {
+  const file = taskFile(taskId, rootDir);
+  const content = readFileSync(file, 'utf8');
+  const fm = parseFrontmatter(content);
+  const updated = mutator({ ...fm });
+  if (updated.schema_version === 'v3.0') updated.schema_version = 'v3.1';
+  updated.last_updated = todayIso();
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  writeFileSync(file, stringifyFrontmatter(updated) + body, 'utf8');
+  return updated;
+}
+
+export async function goalLinkCommand(goalId, taskId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!goalId || !taskId) {
+    console.error(chalk.red('✗ Usage: dw goal link <goal-id> <task-id> [--contributing]'));
+    process.exit(1);
+  }
+
+  if (!readGoal(goalId, rootDir)) {
+    console.error(chalk.red(`✗ Goal ${goalId} not found`));
+    process.exit(1);
+  }
+  if (!existsSync(taskFile(taskId, rootDir))) {
+    console.error(chalk.red(`✗ Task ${taskId} not found at .dw/tasks/${taskId}/task.md`));
+    process.exit(1);
+  }
+
+  const role = opts.contributing ? 'contributing' : 'primary';
+
+  const updated = writeTaskFrontmatter(taskId, (fm) => {
+    if (role === 'primary') {
+      if (fm.parent_goal_id && fm.parent_goal_id !== 'none' && fm.parent_goal_id !== goalId && !opts.force) {
+        console.error(chalk.red(`✗ Task ${taskId} already has parent_goal_id=${fm.parent_goal_id} (use --force to override)`));
+        process.exit(1);
+      }
+      fm.parent_goal_id = goalId;
+    } else {
+      const existing = Array.isArray(fm.contributing_goal_ids) ? fm.contributing_goal_ids : [];
+      if (!existing.includes(goalId)) existing.push(goalId);
+      fm.contributing_goal_ids = existing;
+    }
+    return fm;
+  }, rootDir);
+
+  syncIndexEntry(goalId, rootDir);
+
+  logGoalEvent({
+    event: 'goal_task_linked',
+    goal_id: goalId,
+    task_id: taskId,
+    role,
+  }, rootDir);
+
+  logEvent({ event: 'goal', action: 'link', name: goalId, task_id: taskId, role }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  Linked ${chalk.bold(taskId)} → ${chalk.bold(goalId)} (${role})`));
+  if (role === 'primary') {
+    console.log(chalk.dim(`     task.md frontmatter: parent_goal_id=${goalId}`));
+  } else {
+    console.log(chalk.dim(`     task.md frontmatter: contributing_goal_ids includes ${goalId}`));
+  }
+  console.log();
+}
+
+export async function goalUnlinkCommand(goalId, taskId) {
+  const rootDir = process.cwd();
+
+  if (!goalId || !taskId) {
+    console.error(chalk.red('✗ Usage: dw goal unlink <goal-id> <task-id>'));
+    process.exit(1);
+  }
+
+  if (!existsSync(taskFile(taskId, rootDir))) {
+    console.error(chalk.red(`✗ Task ${taskId} not found`));
+    process.exit(1);
+  }
+
+  let changed = false;
+  writeTaskFrontmatter(taskId, (fm) => {
+    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;
+    }
+    return fm;
+  }, rootDir);
+
+  if (!changed) {
+    console.log(chalk.dim(`  · Task ${taskId} was not linked to ${goalId}`));
+    return;
+  }
+
+  if (readGoal(goalId, rootDir)) syncIndexEntry(goalId, rootDir);
+
+  logGoalEvent({
+    event: 'goal_task_unlinked',
+    goal_id: goalId,
+    task_id: taskId,
+  }, rootDir);
+
+  logEvent({ event: 'goal', action: 'unlink', name: goalId, task_id: taskId }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  Unlinked ${chalk.bold(taskId)} from ${chalk.bold(goalId)}`));
+  console.log();
+}

package/src/commands/goal-lint.mjs

@@ -0,0 +1,152 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parseFrontmatter, loadSchema, validateFrontmatter } from '../lib/frontmatter.mjs';
+import { listGoalIds, readGoal, readGoalIndex, findLinkedTaskIds, goalFile } from '../lib/goal-store.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TASKS_DIR = '.dw/tasks';
+const MAX_SUMMARY_CHARS = 1000;
+
+function loadGoalSchema(rootDir = process.cwd()) {
+  const path = join(rootDir, '.dw', 'core', 'schemas', 'goal-frontmatter.schema.json');
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function scanTaskParentGoalRefs(rootDir = process.cwd()) {
+  const tasksRoot = join(rootDir, TASKS_DIR);
+  if (!existsSync(tasksRoot)) return [];
+  const refs = [];
+  for (const entry of readdirSync(tasksRoot)) {
+    if (entry === 'archive' || entry === 'ACTIVE.md') continue;
+    const file = join(tasksRoot, entry, 'task.md');
+    if (!existsSync(file)) continue;
+    try {
+      const fm = parseFrontmatter(readFileSync(file, 'utf8'));
+      const primary = fm.parent_goal_id && fm.parent_goal_id !== 'none' ? fm.parent_goal_id : null;
+      const contributing = Array.isArray(fm.contributing_goal_ids) ? fm.contributing_goal_ids : [];
+      if (primary || contributing.length) {
+        refs.push({ task: entry, primary, contributing });
+      }
+    } catch { /* skip */ }
+  }
+  return refs;
+}
+
+export async function goalLintCommand(goalId, opts = {}) {
+  const rootDir = process.cwd();
+  const goalSchema = loadGoalSchema(rootDir);
+
+  const ids = goalId ? [goalId] : listGoalIds(rootDir);
+  if (ids.length === 0) {
+    console.log(chalk.dim('  No goals to lint.'));
+    return;
+  }
+
+  let errorCount = 0;
+  let warnCount = 0;
+  let infoCount = 0;
+  let cleanCount = 0;
+
+  console.log();
+  console.log(chalk.bold(`  Linting ${ids.length} goal${ids.length === 1 ? '' : 's'}:`));
+
+  const index = readGoalIndex(rootDir);
+  const allTaskRefs = scanTaskParentGoalRefs(rootDir);
+
+  for (const id of ids) {
+    const goal = readGoal(id, rootDir);
+    if (!goal) {
+      console.log(chalk.red(`  ✗ ${id} — goal.md not found`));
+      errorCount++;
+      continue;
+    }
+
+    const issues = [];
+
+    if (goalSchema) {
+      const v = validateFrontmatter(goal.fm, goalSchema);
+      if (!v.ok) {
+        for (const e of v.errors) {
+          issues.push({ level: 'error', msg: `frontmatter ${e.path}: ${e.message}` });
+        }
+      }
+    }
+
+    if (goal.fm.summary && goal.fm.summary.length > MAX_SUMMARY_CHARS) {
+      issues.push({ level: 'error', msg: `summary > ${MAX_SUMMARY_CHARS} chars (got ${goal.fm.summary.length})` });
+    }
+    if (!goal.fm.summary) {
+      issues.push({ level: 'info', msg: 'no summary set — add via `dw goal summary <id> --write "..."` for agent reaction perf' });
+    }
+
+    const indexEntry = index.goals && index.goals[id];
+    if (!indexEntry) {
+      issues.push({ level: 'error', msg: 'missing from goals-index.json — re-run `dw goal show ' + id + '` to repair' });
+    } else {
+      if ((indexEntry.summary || null) !== (goal.fm.summary || null)) {
+        issues.push({ level: 'error', msg: 'summary drift: goal.md ↔ goals-index.json (write via dw goal summary syncs atomically)' });
+      }
+      if ((indexEntry.status || 'Draft') !== (goal.fm.status || 'Draft')) {
+        issues.push({ level: 'error', msg: `status drift: index=${indexEntry.status} vs file=${goal.fm.status}` });
+      }
+    }
+
+    if (goal.fm.parent_goal_id && goal.fm.parent_goal_id !== 'none') {
+      if (!existsSync(goalFile(goal.fm.parent_goal_id, rootDir))) {
+        issues.push({ level: 'error', msg: `dangling parent_goal_id=${goal.fm.parent_goal_id} (target goal does not exist)` });
+      }
+    }
+
+    for (const issue of issues) {
+      if (issue.level === 'error') errorCount++;
+      else if (issue.level === 'warn') warnCount++;
+      else infoCount++;
+    }
+
+    if (issues.length === 0) {
+      console.log(chalk.green(`  ✓  ${id} — clean`));
+      cleanCount++;
+    } else {
+      console.log(`     ${chalk.bold(id)}`);
+      for (const issue of issues) {
+        const tag = issue.level === 'error' ? chalk.red('[error]') : issue.level === 'warn' ? chalk.yellow('[warn]') : chalk.blue('[info]');
+        console.log(`       ${tag} ${issue.msg}`);
+      }
+    }
+  }
+
+  // Reverse-lookup: task references to nonexistent goals
+  const existingGoalIds = new Set(listGoalIds(rootDir));
+  for (const ref of allTaskRefs) {
+    if (ref.primary && !existingGoalIds.has(ref.primary)) {
+      console.log(`     ${chalk.bold('task:' + ref.task)}`);
+      console.log(`       ${chalk.red('[error]')} parent_goal_id=${ref.primary} but goal does not exist`);
+      errorCount++;
+    }
+    for (const c of ref.contributing) {
+      if (!existingGoalIds.has(c)) {
+        console.log(`     ${chalk.bold('task:' + ref.task)}`);
+        console.log(`       ${chalk.red('[error]')} contributing_goal_ids includes ${c} but goal does not exist`);
+        errorCount++;
+      }
+    }
+  }
+
+  console.log();
+  console.log(`  ${cleanCount} clean · ${warnCount} warnings · ${errorCount} errors · ${infoCount} info`);
+  console.log();
+
+  logEvent({
+    event: 'goal',
+    action: 'lint',
+    count: ids.length,
+    clean: cleanCount,
+    warnings: warnCount,
+    errors: errorCount,
+    info: infoCount,
+  }, rootDir);
+
+  if (errorCount > 0) process.exit(1);
+}

package/src/commands/goal-new.mjs

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { readGoal, writeGoal, syncIndexEntry, todayIso, validateGoalId } from '../lib/goal-store.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATE_PATH = join(__dirname, '..', '..', '.dw', 'core', 'templates', 'v3', 'goal.md');
+
+export async function goalNewCommand(goalId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!goalId) {
+    console.error(chalk.red('✗ Goal ID required. Example: dw goal new G-001'));
+    process.exit(1);
+  }
+
+  if (!validateGoalId(goalId)) {
+    console.error(chalk.red(`✗ Invalid goal ID format: ${goalId}`));
+    console.error(chalk.dim('  Must match: G-{alphanumeric, ≤32 chars} (e.g. G-001, G-ship-v1)'));
+    process.exit(1);
+  }
+
+  if (readGoal(goalId, rootDir)) {
+    console.error(chalk.red(`✗ Goal ${goalId} already exists at .dw/goals/${goalId}/goal.md`));
+    process.exit(1);
+  }
+
+  if (!existsSync(TEMPLATE_PATH)) {
+    console.error(chalk.red(`✗ Template not found: ${TEMPLATE_PATH}`));
+    process.exit(1);
+  }
+
+  const title = opts.title || 'New Goal';
+  const owner = opts.owner || process.env.USER || process.env.USERNAME || 'unknown';
+  const today = todayIso();
+  const summary = opts.summary || null;
+  const icon = opts.icon || '🎯';
+  const cycle = opts.cycle || null;
+
+  const template = readFileSync(TEMPLATE_PATH, 'utf8');
+  const body = template
+    .replace(/^---\n[\s\S]*?\n---\n?/, '')
+    .replace(/\{Title\}/g, title);
+
+  const frontmatter = {
+    goal_id: goalId,
+    schema_version: 'goal@v1',
+    created: today,
+    last_updated: today,
+    status: 'Draft',
+    owner,
+    target_date: opts.targetDate || 'TBD',
+    goal_version: 1,
+    archived_at: null,
+    parent_goal_id: opts.parentGoalId || 'none',
+    icon,
+    cycle,
+    summary,
+  };
+
+  writeGoal(goalId, frontmatter, body, rootDir);
+  syncIndexEntry(goalId, rootDir);
+
+  logGoalEvent({
+    event: 'goal_created',
+    goal_id: goalId,
+    created_by: owner,
+  }, rootDir);
+
+  logEvent({ event: 'goal', action: 'new', name: goalId }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  Created goal ${goalId}`));
+  console.log(chalk.dim(`     .dw/goals/${goalId}/goal.md`));
+  console.log(chalk.dim(`     status: Draft  ·  owner: ${owner}  ·  version: 1`));
+  console.log();
+  console.log(chalk.cyan('  Next:'));
+  console.log(chalk.dim(`     dw goal show ${goalId}         # ANSI snapshot`));
+  console.log(chalk.dim(`     dw goal link ${goalId} <task>  # cross-link tasks`));
+  console.log(chalk.dim(`     dw goal summary ${goalId} --write "..."  # add 1000-char summary`));
+  console.log();
+}

package/src/commands/goal-portfolio.mjs

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { readGoalIndex, listGoalIds, syncIndexEntry } from '../lib/goal-store.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+function statusColor(status) {
+  switch (status) {
+    case 'Active': return chalk.cyan;
+    case 'Achieved': return chalk.green;
+    case 'Abandoned': return chalk.red;
+    case 'Pivoted': return chalk.yellow;
+    default: return chalk.dim;
+  }
+}
+
+export async function goalPortfolioCommand(opts = {}) {
+  const rootDir = process.cwd();
+
+  // Repair: ensure index matches filesystem (idempotent)
+  for (const id of listGoalIds(rootDir)) {
+    syncIndexEntry(id, rootDir);
+  }
+
+  const index = readGoalIndex(rootDir);
+  const entries = Object.entries(index.goals || {});
+
+  if (entries.length === 0) {
+    console.log();
+    console.log(chalk.dim('  No goals in portfolio. Create one: dw goal new G-001'));
+    console.log();
+    return;
+  }
+
+  const filter = opts.status ? opts.status : null;
+  const filtered = filter
+    ? entries.filter(([, g]) => g.status === filter)
+    : entries;
+
+  console.log();
+  console.log(chalk.bold(`  Goals portfolio (${filtered.length}${filter ? ` of ${entries.length}` : ''}):`));
+  console.log(chalk.dim(`  Source: .dw/goals/goals-index.json (O(1) read; W-1 fix)`));
+  console.log();
+
+  // Group by cycle (named first, no-cycle last)
+  const groups = new Map();
+  for (const [id, g] of filtered) {
+    const cycle = g.cycle || '(no cycle)';
+    if (!groups.has(cycle)) groups.set(cycle, []);
+    groups.get(cycle).push([id, g]);
+  }
+  const sortedGroups = [...groups.entries()].sort(([a], [b]) => {
+    if (a === '(no cycle)') return 1;
+    if (b === '(no cycle)') return -1;
+    return a.localeCompare(b);
+  });
+
+  for (const [cycle, items] of sortedGroups) {
+    console.log(chalk.cyan(chalk.bold(`  ▸ ${cycle}  `)) + chalk.dim(`(${items.length})`));
+    console.log();
+    for (const [id, g] of items) {
+      const color = statusColor(g.status);
+      const badge = color(`[${g.status || 'Draft'}]`);
+      const archived = g.archived_at ? chalk.red(' (archived)') : '';
+      const icon = g.icon || '🎯';
+      const prog = g.progress || { percent: 0, total: 0, done: 0 };
+      const progStr = prog.total > 0
+        ? chalk.dim(' · ') + chalk.green(`${prog.percent}%`) + chalk.dim(` (${prog.done}/${prog.total})`)
+        : '';
+      console.log(`    ${badge} ${icon} ${chalk.bold(id)}  ${g.title || ''}${archived}${progStr}`);
+      console.log(`       ${chalk.dim('Owner:')} ${g.owner || '?'}  ${chalk.dim('·')}  ${chalk.dim('Target:')} ${g.target_date || 'TBD'}  ${chalk.dim('·')}  ${chalk.dim('v')}${g.goal_version || 1}  ${chalk.dim('·')}  ${chalk.dim('Tasks:')} ${(g.linked_task_ids || []).length}`);
+      if (g.summary) {
+        console.log(`       ${chalk.dim('Summary:')} ${chalk.white(g.summary.length > 200 ? g.summary.slice(0, 197) + '...' : g.summary)}`);
+      }
+      console.log();
+    }
+  }
+
+  logEvent({
+    event: 'goal',
+    action: 'portfolio',
+    count: filtered.length,
+    total: entries.length,
+    filter,
+  }, rootDir);
+}