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

package/.claude/hooks/pre-commit-gate.sh

@@ -96,27 +96,25 @@ fi
 # v1.6 (ADR-0009 R2-2): Agent OS post-hoc check.
 # When ≥1 active claim exists, verify staged files fall within an active claim's write_scope.
 # Cooperative protocol — warn only (cannot prevent non-compliant agents).
-if [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1 && [ -n "$STAGED_FILES" ]; then
+#
+# Issue #13 Bug 3 fix: previous version inlined `node -e` importing
+# `$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs` — that path is cwd-relative and
+# only exists in dw-kit's own repo, NOT in consumer projects. The block was
+# silently no-op everywhere else. Replaced by `dw agent check-staged --stdin`
+# which uses the installed binary. Prefer global `dw` on PATH; fall back to
+# `node $DW_BIN` for in-repo local development (where DW_BIN points at the
+# source bin script).
+if [ -n "$STAGED_FILES" ]; then
   CLAIMS_DIR="$CLAUDE_PROJECT_DIR/.dw/cache/agents/claims"
   if [ -d "$CLAIMS_DIR" ] && ls "$CLAIMS_DIR"/*.json >/dev/null 2>&1; then
-    OUT_OF_SCOPE=$(STAGED="$STAGED_FILES" node -e "
-      const fs = require('fs');
-      const path = require('path');
-      (async () => {
-        const { listClaims } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs');
-        const { pathMatchesScope } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-conflict.mjs');
-        const claims = listClaims(process.env.CLAUDE_PROJECT_DIR || '$CLAUDE_PROJECT_DIR').filter(c => c._live_status === 'created' || c._live_status === 'active');
-        if (claims.length === 0) return;
-        const allScopes = claims.flatMap(c => c.write_scope);
-        const staged = (process.env.STAGED || '').split(/\r?\n/).filter(Boolean);
-        const outside = staged.filter(f => !pathMatchesScope(f, allScopes));
-        if (outside.length > 0) {
-          console.log('Files NOT in any active claim write_scope:');
-          for (const f of outside.slice(0, 10)) console.log('  ' + f);
-          if (outside.length > 10) console.log('  ... +' + (outside.length - 10) + ' more');
-        }
-      })().catch(e => { /* fail-graceful */ });
-    " 2>/dev/null || true)
+    if command -v dw >/dev/null 2>&1; then
+      OUT_OF_SCOPE=$(echo "$STAGED_FILES" | dw agent check-staged --stdin 2>/dev/null || true)
+    elif [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1; then
+      # Local dev fallback: in-repo dw-kit work where global `dw` not on PATH
+      OUT_OF_SCOPE=$(echo "$STAGED_FILES" | node "$DW_BIN" agent check-staged --stdin 2>/dev/null || true)
+    else
+      OUT_OF_SCOPE=""
+    fi
     if [ -n "$OUT_OF_SCOPE" ]; then
       echo "⚠️  Agent OS (ADR-0009 R2-2): post-hoc claim check" >&2
       echo "$OUT_OF_SCOPE" >&2

package/.dw/core/schemas/agent-claim.schema.json

@@ -114,7 +114,27 @@
     },
     "worktree_path": {
       "type": "string",
-      "description": "If agent operates in a git worktree per R2-3, the worktree path. .dw/cache/worktrees/{agent-id}/"
+      "description": "Absolute path to the git worktree this agent operates in (issue #15). dw does NOT create or delete this directory — the caller harness owns lifecycle (`git worktree add` / `git worktree remove`). When two claims declare distinct worktree_path values, dw conflict detection skips write_scope comparison between them (physical isolation). One or both null → conservative; assume overlap."
+    },
+    "original_lease_expires": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: lease_expires at claim creation time (immutable). Renewals do NOT change this — caps total lease window via max_renewals."
+    },
+    "renewed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: timestamp of last `dw agent renew` call. Stamped on each renewal; previous value overwritten."
+    },
+    "renewal_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Issue #15: number of times this claim has been renewed. Bounded by MAX_RENEWALS (default 3) to prevent unbounded lease compounding."
+    },
+    "previous_lease_expires": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Issue #15: lease_expires value immediately before the most recent renewal. Provides self-describing renewal history without depending on events.jsonl."
     }
   },
   "allOf": [

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.2",
   "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,14 +179,24 @@ 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');
+    .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · renew · expire · claims · reports · conflicts · check-staged · verify');
 
   agentCmd
     .command('claim <task-id>')
@@ -213,6 +224,15 @@ export function run(argv) {
       await agentReleaseCommand(claimId, opts);
     });
 
+  agentCmd
+    .command('renew <claim-id>')
+    .description('Extend lease on an active claim WITHOUT changing claim_id (preserves audit continuity vs expire+reclaim). Capped at 3 renewals (issue #15)')
+    .option('-l, --lease <duration>', 'New lease window (e.g. 30m, 1h, 4h)', '1h')
+    .action(async (claimId, opts) => {
+      const { agentRenewCommand } = await import('./commands/agent-claim.mjs');
+      await agentRenewCommand(claimId, opts);
+    });
+
   agentCmd
     .command('expire <claim-id>')
     .description('Mark a claim as expired or invalidated (orchestrator action)')
@@ -254,6 +274,165 @@ export function run(argv) {
       await agentConflictsCommand(opts);
     });
 
+  agentCmd
+    .command('check-staged [files...]')
+    .description('Check staged files against active claim write_scopes (R2-2 cooperative; used by pre-commit-gate hook). Always exits 0; warning on stdout.')
+    .option('--stdin', 'Read file list from stdin (one path per line) instead of positional args')
+    .action(async (files, opts) => {
+      const { agentCheckStagedCommand } = await import('./commands/agent-check-staged.mjs');
+      await agentCheckStagedCommand(files, opts);
+    });
+
+  agentCmd
+    .command('verify <task-id>')
+    .description('Check events.jsonl well-formedness for a task (detects malformed JSON lines; exits 1 if any). Note: not full tamper-evidence — use git log for that.')
+    .option('-v, --verbose', 'Show raw line content for malformed entries')
+    .option('--no-strict', 'Report malformed lines but always exit 0')
+    .action(async (taskId, opts) => {
+      const { agentVerifyCommand } = await import('./commands/agent-verify.mjs');
+      await agentVerifyCommand(taskId, 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/agent-check-staged.mjs

@@ -0,0 +1,63 @@
+import { createInterface } from 'node:readline';
+import { listClaims } from '../lib/agent-claim.mjs';
+import { pathMatchesScope } from '../lib/agent-conflict.mjs';
+
+/**
+ * `dw agent check-staged <files...>` or `dw agent check-staged --stdin`
+ *
+ * Issue #13 Bug 3: pre-commit-gate.sh R2-2 block used inline `node -e` with
+ * `import('$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs')` — dead code in
+ * consumer projects (cwd-relative path resolves to non-existent file) and
+ * exposed path-injection via shell variable substitution into JS string.
+ * This subcommand replaces the inline JS — hooks now invoke `dw agent
+ * check-staged --stdin` cleanly via the installed binary.
+ *
+ * Output contract (cooperative-only per ADR-0009 R2):
+ *   - stdout: warning text if any staged files fall outside active claim
+ *             write_scopes; empty otherwise
+ *   - exit code: ALWAYS 0 (cooperative protocol — never blocks commits)
+ *
+ * Hook detects out-of-scope by checking stdout is non-empty.
+ */
+export async function agentCheckStagedCommand(files, opts = {}) {
+  const rootDir = process.cwd();
+  let inputFiles = Array.isArray(files) ? [...files] : [];
+
+  if (opts.stdin) {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (trimmed) inputFiles.push(trimmed);
+    }
+  }
+
+  // No files to check → silent success
+  if (inputFiles.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // No active claims → nothing to check against; silent success
+  const claims = listClaims(rootDir).filter(
+    (c) => c._live_status === 'created' || c._live_status === 'active'
+  );
+  if (claims.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Aggregate all active write_scopes. pathMatchesScope normalizes separators
+  // internally (Bug 2 fix) so legacy backslash claims still match correctly.
+  const allScopes = claims.flatMap((c) => c.write_scope);
+  const outside = inputFiles.filter((f) => !pathMatchesScope(f, allScopes));
+
+  if (outside.length > 0) {
+    console.log('Files NOT in any active claim write_scope:');
+    for (const f of outside.slice(0, 10)) console.log('  ' + f);
+    if (outside.length > 10) console.log('  ... +' + (outside.length - 10) + ' more');
+    // Black-bot C-4: exit 0 here intentional (cooperative protocol; hook detects
+    // out-of-scope via non-empty stdout, not exit code). Single exit at end below.
+  }
+
+  process.exit(0);
+}