specweave 2.0.3 → 2.1.0

package/dist/src/sync/external-change-puller.js

@@ -12,6 +12,17 @@
  * @module sync/external-change-puller
  */
 import { consoleLogger } from '../utils/logger.js';
+import { maskCredentials } from '../utils/credential-masker.js';
+/** A rejected fetch must not be mistaken for a complete synchronization. */
+export class ExternalPullError extends Error {
+    constructor(changes, failures, completedPlatforms) {
+        super(`External pull incomplete: ${failures.map(f => f.platform).join(', ')}.`);
+        this.changes = changes;
+        this.failures = failures;
+        this.completedPlatforms = completedPlatforms;
+        this.name = 'ExternalPullError';
+    }
+}
 /**
  * ExternalChangePuller - Fetches changes from external tools
  *
@@ -23,6 +34,7 @@ export class ExternalChangePuller {
         this.projectRoot = options.projectRoot;
         this.logger = options.logger ?? consoleLogger;
         this.platforms = options.platforms ?? ['ado', 'jira', 'github'];
+        this.github = options.github;
     }
     /**
      * Fetch recent changes from all configured platforms
@@ -30,30 +42,42 @@ export class ExternalChangePuller {
      * @param since - Timestamp to query changes from
      * @param linkedItems - Optional map of platform -> item IDs to filter
      * @returns Array of external changes from all platforms
+     * @throws ExternalPullError with successful results when any provider fails
      */
     async fetchRecentChanges(since, linkedItems) {
         const allChanges = [];
+        const failures = [];
+        const recordFailure = (platform, error) => {
+            const message = maskCredentials(error instanceof Error ? error.message : String(error));
+            failures.push({ platform, message });
+            this.logger.warn(`${platform} fetch failed: ${message}`);
+        };
         this.logger.log(`⬇️  Fetching changes since ${since.toISOString()}`);
         // Fetch from each platform in parallel
         const fetchPromises = [];
         if (this.platforms.includes('ado')) {
             fetchPromises.push(this.fetchAdoChanges(since, linkedItems?.ado)
                 .then(changes => { allChanges.push(...changes); })
-                .catch(err => { this.logger.warn(`ADO fetch failed: ${err.message}`); }));
+                .catch(err => { recordFailure('ado', err); }));
         }
         if (this.platforms.includes('jira')) {
             fetchPromises.push(this.fetchJiraChanges(since, linkedItems?.jira)
                 .then(changes => { allChanges.push(...changes); })
-                .catch(err => { this.logger.warn(`JIRA fetch failed: ${err.message}`); }));
+                .catch(err => { recordFailure('jira', err); }));
         }
         if (this.platforms.includes('github')) {
             fetchPromises.push(this.fetchGitHubChanges(since, linkedItems?.github)
                 .then(changes => { allChanges.push(...changes); })
-                .catch(err => { this.logger.warn(`GitHub fetch failed: ${err.message}`); }));
+                .catch(err => { recordFailure('github', err); }));
         }
         await Promise.all(fetchPromises);
         // Sort by changedAt (most recent first)
         allChanges.sort((a, b) => new Date(b.changedAt).getTime() - new Date(a.changedAt).getTime());
+        if (failures.length > 0) {
+            failures.sort((a, b) => a.platform.localeCompare(b.platform));
+            const completed = this.platforms.filter(platform => !failures.some(f => f.platform === platform));
+            throw new ExternalPullError(allChanges, failures, completed);
+        }
         this.logger.log(`📥 Fetched ${allChanges.length} changes from external tools`);
         return allChanges;
     }
@@ -61,91 +85,77 @@ export class ExternalChangePuller {
      * Fetch changes from Azure DevOps
      */
     async fetchAdoChanges(since, linkedItemIds) {
-        try {
-            // Dynamic import to avoid initialization errors when ADO is not configured
-            const { AdoClient } = await import('../integrations/ado/ado-client.js');
-            const client = new AdoClient();
-            const adoChanges = await client.fetchRecentChanges(since, linkedItemIds);
-            // Map to unified format
-            return adoChanges.map(change => ({
-                platform: 'ado',
-                externalId: change.externalId,
-                changedAt: change.changedAt,
-                changedBy: change.changedBy,
-                changedFields: change.changedFields,
-                currentState: {
-                    status: change.currentState.status,
-                    priority: change.currentState.priority,
-                    assignee: change.currentState.assignee,
-                },
-            }));
-        }
-        catch (err) {
-            this.logger.debug(`ADO not configured or error: ${err.message}`);
-            return [];
-        }
+        // Dynamic import to avoid initialization errors when ADO is not configured
+        const { AdoClient } = await import('../integrations/ado/ado-client.js');
+        const client = new AdoClient();
+        const adoChanges = await client.fetchRecentChanges(since, linkedItemIds);
+        // Map to unified format
+        return adoChanges.map(change => ({
+            platform: 'ado',
+            externalId: change.externalId,
+            changedAt: change.changedAt,
+            changedBy: change.changedBy,
+            changedFields: change.changedFields,
+            currentState: {
+                status: change.currentState.status,
+                priority: change.currentState.priority,
+                assignee: change.currentState.assignee,
+            },
+        }));
     }
     /**
      * Fetch changes from JIRA
      */
     async fetchJiraChanges(since, linkedIssueKeys) {
-        try {
-            // Dynamic import to avoid initialization errors when JIRA is not configured
-            const { JiraClient } = await import('../integrations/jira/jira-client.js');
-            const client = new JiraClient();
-            const jiraChanges = await client.fetchRecentChanges(since, linkedIssueKeys);
-            // Map to unified format
-            return jiraChanges.map(change => ({
-                platform: 'jira',
-                externalId: change.externalId,
-                changedAt: change.changedAt,
-                changedBy: change.changedBy,
-                changedFields: change.changedFields,
-                currentState: {
-                    status: change.currentState.status,
-                    priority: change.currentState.priority,
-                    assignee: change.currentState.assignee,
-                },
-            }));
-        }
-        catch (err) {
-            this.logger.debug(`JIRA not configured or error: ${err.message}`);
-            return [];
-        }
+        // Dynamic import to avoid initialization errors when JIRA is not configured
+        const { JiraClient } = await import('../integrations/jira/jira-client.js');
+        const client = new JiraClient();
+        const jiraChanges = await client.fetchRecentChanges(since, linkedIssueKeys);
+        // Map to unified format
+        return jiraChanges.map(change => ({
+            platform: 'jira',
+            externalId: change.externalId,
+            changedAt: change.changedAt,
+            changedBy: change.changedBy,
+            changedFields: change.changedFields,
+            currentState: {
+                status: change.currentState.status,
+                priority: change.currentState.priority,
+                assignee: change.currentState.assignee,
+            },
+        }));
     }
     /**
      * Fetch changes from GitHub
      */
     async fetchGitHubChanges(since, linkedIssueNumbers) {
-        try {
-            // Dynamic import to avoid initialization errors when GitHub is not configured
-            const { GitHubClientV2 } = await import('../../plugins/specweave/lib/integrations/github/github-client-v2.js');
-            // Detect repo from git remote
-            const detected = await GitHubClientV2.detectRepo(this.projectRoot);
-            if (!detected) {
-                this.logger.debug('GitHub: No git remote detected');
-                return [];
-            }
-            const client = GitHubClientV2.fromRepo(detected.owner, detected.repo);
-            const githubChanges = await client.fetchRecentChanges(since, linkedIssueNumbers);
-            // Map to unified format (GitHub returns slightly different format)
-            return githubChanges.map(change => ({
-                platform: 'github',
-                externalId: change.externalId,
-                changedAt: change.changedAt,
-                changedBy: change.changedBy,
-                changedFields: change.changedFields,
-                currentState: {
-                    status: change.currentState.status,
-                    priority: null, // GitHub doesn't have priority
-                    assignee: change.currentState.assignee,
-                },
-            }));
-        }
-        catch (err) {
-            this.logger.debug(`GitHub not configured or error: ${err.message}`);
-            return [];
+        // Dynamic import to avoid initialization errors when GitHub is not configured
+        const { GitHubClientV2 } = await import('../../plugins/specweave/lib/integrations/github/github-client-v2.js');
+        // Detect repo from git remote
+        const detected = this.github ?? await GitHubClientV2.detectRepo(this.projectRoot);
+        if (!detected) {
+            throw new Error('No GitHub repository configured and no GitHub remote detected. Run specweave sync setup.');
         }
+        const client = new GitHubClientV2({
+            provider: 'github',
+            displayName: `${detected.owner}/${detected.repo}`,
+            config: { owner: detected.owner, repo: detected.repo, ...(this.github?.token ? { token: this.github.token } : {}) },
+            timeRange: { default: '1M', max: '6M' },
+        }, this.projectRoot);
+        const githubChanges = await client.fetchRecentChanges(since, linkedIssueNumbers);
+        // Map to unified format (GitHub returns slightly different format)
+        return githubChanges.map(change => ({
+            platform: 'github',
+            externalId: change.externalId,
+            changedAt: change.changedAt,
+            changedBy: change.changedBy,
+            changedFields: change.changedFields,
+            currentState: {
+                status: change.currentState.status,
+                priority: null, // GitHub doesn't have priority
+                assignee: change.currentState.assignee,
+            },
+        }));
     }
     /**
      * Map external status to SpecWeave status

package/dist/src/sync/external-change-puller.js.map

@@ -1 +1 @@
-{"version":3,"file":"external-change-puller.js","sourceRoot":"","sources":["../../../src/sync/external-change-puller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"external-change-puller.js","sourceRoot":"","sources":["../../../src/sync/external-change-puller.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
-  "version": "2.0.3",
-  "description": "100+ domain-expert AI skills — PM, Architect, Frontend, QA, Security and more. Skills learn your team's patterns permanently. Spec-first planning, autonomous execution, multi-agent teams, synced to GitHub/JIRA. Claude Code, Cursor, Copilot & more.",
+  "version": "2.1.0",
+  "description": "Keep intent, specifications, and verified progress portable across AI coding tools. A local live work board, append-only task evidence, explicit handoffs, and optional GitHub/Jira/Azure DevOps integrations.",
   "type": "module",
   "bin": {
     "specweave": "./bin/specweave.js"
@@ -10,7 +10,7 @@
     "preinstall": "node scripts/check-node-version.js || exit 0",
     "preuninstall": "node scripts/preuninstall.cjs",
     "version": "node scripts/build/auto-changelog.js && node scripts/build/stamp-plugin-version.cjs && git add CHANGELOG.md plugins/specweave/.claude-plugin/plugin.json .claude-plugin/marketplace.json",
-    "postversion": "echo '✅ Version bumped with CHANGELOG entry'",
+    "postversion": "echo '\u2705 Version bumped with CHANGELOG entry'",
     "clean": "rm -rf dist/",
     "build": "tsc && npm run build:dashboard && npm run copy:locales && npm run copy:plugins && npm run copy:hook-deps && npm run copy:adapters && npm run stamp:plugin-version",
     "stamp:plugin-version": "node scripts/build/stamp-plugin-version.cjs",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
-  "description": "SpecWeave: increment lifecycle for any AI tool. 10 skills (increment, do, done, review, team, handoff, sync, auto, brainstorm, qa), 4 exec-form hooks, and the specweave CLI for everything deterministic.",
-  "version": "2.0.3",
+  "description": "Portable intent and verified progress across coding tools. Ten focused workflow skills, two default lifecycle hooks, and a deterministic CLI and live local dashboard.",
+  "version": "2.1.0",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "SpecWeave hooks: portable command strings and bounded worker execution.",
+  "description": "Minimal hooks: compact session context and an opt-in auto loop. Handoffs are explicit CLI actions.",
   "hooks": {
     "SessionStart": [
       {
@@ -12,18 +12,6 @@
         ]
       }
     ],
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" pre-tool-use",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
     "Stop": [
       {
         "hooks": [
@@ -34,17 +22,6 @@
           }
         ]
       }
-    ],
-    "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" pre-compact",
-            "timeout": 10
-          }
-        ]
-      }
     ]
   }
 }

package/plugins/specweave/hooks/run.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // SpecWeave hook supervisor: parent deadline remains live while the worker blocks in Git.
 import { spawn, spawnSync } from 'node:child_process';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,6 +10,27 @@ const worker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'run-work
 const budget = event === 'stop' ? 25000 : 7500;
 let child, finished = false, input = '', output = '', size = 0;
 const started = Date.now();
+// Ordinary turns should not resolve npm, import the CLI, or start a second Node
+// process. Auto mode is explicit and its small local marker is authoritative.
+function hasActiveAutoSession(data) {
+  let current = path.resolve(typeof data.cwd === 'string' ? data.cwd : process.cwd());
+  for (let depth = 0; depth < 100; depth++) {
+    const state = path.join(current, '.specweave', 'state');
+    if (existsSync(path.join(current, '.specweave', 'config.json'))) {
+      const sessionId = process.env.CLAUDE_SESSION_ID;
+      // Match session-state-manager's path-safe IDs, including dots and spaces.
+      const scoped = sessionId && !/[/\\]|\.\.|\0/.test(sessionId)
+        ? path.join(state, 'sessions', sessionId, 'auto-mode.json') : null;
+      const marker = scoped && existsSync(scoped) ? scoped : path.join(state, 'auto-mode.json');
+      try { return JSON.parse(readFileSync(marker, 'utf8')).active === true; }
+      catch { return false; }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return false;
+}
 function record(reason) {
   try {
     const dir = path.join(homedir(), '.specweave', 'logs');
@@ -49,6 +70,8 @@ process.stdin.on('end',()=>{
   try {data=JSON.parse(input);if(!data || typeof data!=='object'||Array.isArray(data))throw Error();}
   catch {return finish({},'invalid_input');}
   if(!['session-start','pre-tool-use','pre-compact','stop'].includes(event))return finish({});
+  if(process.env.SPECWEAVE_DISABLE_HOOKS === '1')return finish({});
+  if(event === 'stop' && !hasActiveAutoSession(data))return finish({});
   const env={...process.env};
   child=spawn(process.execPath,[worker,event],{env,detached:process.platform !== 'win32',stdio:['pipe','pipe','pipe']});
   child.stdout.setEncoding('utf8');

package/plugins/specweave/skills/increment/SKILL.md

@@ -11,11 +11,13 @@ An increment is one folder — `.specweave/increments/NNNN-slug/` — holding
 `ledger.jsonl` (state, written by the CLI) and `metadata.json`. It is the unit of
 work and the tracker; every commit for it carries its id in the subject.
 
-## Plan mode first (blocking)
+## Scope before implementation
 
-Planning produces a document the user approves before any code is written. If your
-tool has a plan mode, enter it now (Claude Code: `EnterPlanMode`) and wait for
-confirmation. Do not create files, do not implement, until the plan is approved.
+Write a concise plan for work that needs shared acceptance criteria. Ask only about
+material ambiguity or actions beyond the user's authorization. When the user has
+asked for autonomous execution, make routine decisions and continue through
+implementation and verification. A small self-contained fix can remain a
+lightweight intent without this workflow.
 
 ## Steps
 
@@ -79,7 +81,7 @@ confirmation. Do not create files, do not implement, until the plan is approved.
    least one task; every task needs a `Test:` that a machine can run (or an explicit
    "manual: <what to check>"). Shared contracts (types, schema, migrations) go in an early
    task everything else depends on.
-6. **Present the plan** (problem, ACs, task list, risks) and get approval. Then leave plan mode.
+6. **Share the plan** (problem, ACs, tasks, material risks). Resolve any remaining decision that needs the user; otherwise continue within existing authorization.
 7. **Hand off to execution**: `sw:do <id>` for one agent; `sw:team <id>` when the work has
    3+ disjoint lanes or 15+ tasks.
 

package/src/templates/AGENTS.md.template

@@ -1,7 +1,7 @@
 <!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
+SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -9,6 +9,7 @@ SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-
 
 ```
 .specweave/
+  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
   increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
   docs/                    ADRs and hand-written docs (read before changing architecture)
   config.json
@@ -23,7 +24,7 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 
 | Step | Command (each step is also a standalone skill you can install into any tool with `npx vskill install anton-abyzov/specweave/sw-do` — same for `sw-increment`, `sw-review`, `sw-handoff`, `sw-task`) |
 |---|---|
-| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), get approval before any code | `specweave create-increment "title"` |
+| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), resolve material scope questions before implementation | `specweave create-increment "title"` |
 | Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → commit (`NNNN: …`) → `specweave task done T-NN --run "<test cmd>"` (the command runs through your OS shell: cmd.exe on Windows, sh elsewhere) |
 | Verify the whole increment | `specweave verify` |
 | Review before closing (recommended for anything that ships) | in a fresh session: read spec.md, list findings by severity citing path:line, re-verify each before writing `reports/review.md`; the authoring session never approves its own work |
@@ -31,7 +32,7 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 | Stop for any reason | `specweave handoff` |
 
 Without the `specweave` CLI: create the folder by hand (id = highest existing 4-digit prefix + 1, zero-padded); append one JSON line per event to `ledger.jsonl` as UTF-8 without BOM, LF-terminated, e.g. `{"t":"T-01","e":"claim","by":"<tool>@<host>","at":"<ISO>"}` (bash: `>>`; PowerShell: `[IO.File]::AppendAllText('ledger.jsonl', $line + "`n")`, never `>>`, it writes UTF-16); mark done with the same line using `"e":"done","evidence":"<commit sha>"` after the Test command exits 0; write `reports/verify.md` with the real test output and say the increment is ready to close (closing itself needs the CLI).
-Start every feature with an increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
+Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
 <!-- /SECTION -->
 
 <!-- SECTION:verify required -->
@@ -48,8 +49,7 @@ Run the project's build/test/lint (see **Commands**) before reporting any task c
 3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
 4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."` (no CLI: append a `skip` ledger line with a reason), never ticked.
 5. When you stop: `specweave task release --all-mine` then `specweave handoff`.
-
-Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
+Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
 <!-- /SECTION -->
 
 <!-- SECTION:conventions required -->

package/src/templates/CLAUDE.md.template

@@ -1,7 +1,7 @@
 <!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
+SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -9,6 +9,7 @@ SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-
 
 ```
 .specweave/
+  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
   increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
   docs/                    ADRs and hand-written docs (read before changing architecture)
   config.json
@@ -23,14 +24,14 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 
 | Step | Command |
 |---|---|
-| Plan a feature (spec.md with ACs + Approach, in plan mode; approved before any code) | `/sw:increment "title"` |
+| Plan a feature (spec.md with ACs + Approach; resolve material scope questions) | `/sw:increment "title"` |
 | Work the tasks (claim → implement → commit → done with evidence) | `/sw:do` (loops `specweave task next` / `claim` / `done --run`) |
 | Verify the whole increment | `specweave verify` |
 | Review before closing (recommended for anything that ships: fresh context, findings cite path:line and are re-verified) | `/sw:review` |
 | Close (needs a green verify or `--reason`) | `/sw:done` |
 | Stop for any reason (context, tokens, switching tools) | `/sw:handoff` |
 
-Start every feature with the increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
+Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
 <!-- /SECTION -->
 
 <!-- SECTION:verify required -->
@@ -47,8 +48,7 @@ Run the project's build/test/lint (see **Commands**) before reporting any task c
 3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
 4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."`, never ticked.
 5. When you stop: `specweave task release --all-mine` then `/sw:handoff`.
-
-Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
+Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
 <!-- /SECTION -->
 
 <!-- SECTION:conventions required -->