aiwcli 0.10.3 → 0.11.1

package/bin/run.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // Load environment variable compatibility layer first
-const {loadEnvWithCompatibility} = await import('../dist/lib/env-compat.js')
+const {loadEnvWithCompatibility} = await import('../dist/lib/env-compat.js')  
 loadEnvWithCompatibility()
 
 import {execute} from '@oclif/core'

package/dist/commands/clear.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { confirm } from '@inquirer/prompts';
 import { Flags } from '@oclif/core';
 import BaseCommand from '../lib/base-command.js';
-import { pruneGitignoreStaleEntries } from '../lib/gitignore-manager.js';
+import { computeGitignoreRemovals, pruneGitignoreStaleEntries, removeGitignoreEntries } from '../lib/gitignore-manager.js';
 import { pathExists } from '../lib/paths.js';
 import { reconstructIdeSettings } from '../lib/template-settings-reconstructor.js';
 import { EXIT_CODES } from '../types/exit-codes.js';
@@ -44,6 +44,7 @@ async function getInstalledMethodNames(targetDir) {
     for (const ide of Object.values(IDE_FOLDERS)) {
         const settingsPath = join(targetDir, ide.root, ide.settingsFile);
         try {
+            // eslint-disable-next-line no-await-in-loop
             const content = await fs.readFile(settingsPath, 'utf8');
             const settings = JSON.parse(content);
             if (settings.methods && typeof settings.methods === 'object') {
@@ -71,10 +72,6 @@ async function getInstalledMethodNames(targetDir) {
     }
     return methods;
 }
-/**
- * AIW gitignore section header marker
- */
-const AIW_GITIGNORE_HEADER = '# AIW Installation';
 /**
  * Check if a directory is empty.
  *
@@ -190,123 +187,6 @@ async function shouldDeleteIdeFolder(targetDir, ideFolder) {
 async function removeDirectory(dir) {
     await fs.rm(dir, { force: true, recursive: true });
 }
-/**
- * Update .gitignore to remove patterns for cleared folders.
- * Removes patterns from the AIW Installation section.
- *
- * @param targetDir - Directory containing .gitignore
- * @param foldersToRemove - Folder patterns to remove (without trailing slash)
- */
-async function updateGitignoreAfterClear(targetDir, foldersToRemove) {
-    const gitignorePath = join(targetDir, '.gitignore');
-    try {
-        const content = await fs.readFile(gitignorePath, 'utf8');
-        // Check if AIW Installation section exists
-        if (!content.includes(AIW_GITIGNORE_HEADER)) {
-            return;
-        }
-        // Split content into lines
-        const lines = content.split('\n');
-        const newLines = [];
-        let inAiwSection = false;
-        const aiwSectionLines = [];
-        // Parse lines and identify AIW section
-        for (const line of lines) {
-            if (line === AIW_GITIGNORE_HEADER) {
-                inAiwSection = true;
-                aiwSectionLines.push(line);
-                continue;
-            }
-            if (inAiwSection) {
-                // AIW section ends at empty line or another comment header
-                if (line === '' || (line.startsWith('#') && line !== AIW_GITIGNORE_HEADER)) {
-                    inAiwSection = false;
-                    // Process AIW section lines now
-                    const filteredAiwLines = filterAiwSection(aiwSectionLines, foldersToRemove);
-                    newLines.push(...filteredAiwLines, line);
-                }
-                else {
-                    aiwSectionLines.push(line);
-                }
-            }
-            else {
-                newLines.push(line);
-            }
-        }
-        // Handle case where AIW section is at end of file
-        if (inAiwSection) {
-            const filteredAiwLines = filterAiwSection(aiwSectionLines, foldersToRemove);
-            newLines.push(...filteredAiwLines);
-        }
-        // Clean up: remove AIW section entirely if only header remains
-        const finalContent = cleanupGitignoreContent(newLines.join('\n'));
-        await fs.writeFile(gitignorePath, finalContent, 'utf8');
-    }
-    catch {
-        // .gitignore doesn't exist or can't be read
-    }
-}
-/**
- * Filter AIW section lines to remove specified folders.
- *
- * @param aiwLines - Lines from AIW section (including header)
- * @param foldersToRemove - Folder names to remove
- * @returns Filtered lines
- */
-function filterAiwSection(aiwLines, foldersToRemove) {
-    const patternsToRemove = new Set(foldersToRemove.map((f) => `${f}/`));
-    return aiwLines.filter((line) => {
-        // Always keep the header
-        if (line === AIW_GITIGNORE_HEADER) {
-            return true;
-        }
-        // Remove matching patterns
-        return !patternsToRemove.has(line);
-    });
-}
-/**
- * Clean up gitignore content after filtering.
- * Removes AIW section if empty, cleans up extra newlines.
- *
- * @param content - Gitignore content
- * @returns Cleaned content
- */
-function cleanupGitignoreContent(content) {
-    const lines = content.split('\n');
-    const newLines = [];
-    let i = 0;
-    while (i < lines.length) {
-        const line = lines[i];
-        // Check if this is an AIW header with nothing following
-        if (line === AIW_GITIGNORE_HEADER) {
-            // Look ahead to see if there are any patterns
-            let hasPatterns = false;
-            const nextLine = lines[i + 1];
-            if (nextLine !== undefined && nextLine !== '' && !nextLine.startsWith('#')) {
-                hasPatterns = true;
-            }
-            if (!hasPatterns) {
-                // Skip the AIW header since it has no patterns
-                i++;
-                // Also skip any trailing empty lines that were before AIW section
-                while (newLines.length > 0 && newLines.at(-1) === '') {
-                    newLines.pop();
-                }
-                continue;
-            }
-        }
-        newLines.push(line);
-        i++;
-    }
-    // Ensure file ends with newline but not multiple
-    let result = newLines.join('\n');
-    result = result.replace(/\n+$/, '\n');
-    // Handle empty file case
-    if (result.trim() === '') {
-        return '';
-    }
-    return result;
-}
 /**
  * Clear workflow folders, output folders, IDE method folders, and update configurations.
  */
@@ -498,6 +378,18 @@ export default class ClearCommand extends BaseCommand {
                 this.logInfo(`${IDE_FOLDERS.windsurf.root}/ folder will be removed (will be empty)`);
                 this.log('');
             }
+            // Compute gitignore changes for dry-run display
+            const gitignoreSimulation = await computeGitignoreRemovals(targetDir);
+            if (gitignoreSimulation.toRemove.length > 0 || gitignoreSimulation.toKeep.length > 0) {
+                this.logInfo('Gitignore changes:');
+                for (const { entry, reason } of gitignoreSimulation.toKeep) {
+                    this.log(`  keep ${entry}/ (${reason})`);
+                }
+                for (const entry of gitignoreSimulation.toRemove) {
+                    this.log(`  remove ${entry}/`);
+                }
+                this.log('');
+            }
             // Dry run - just show what would happen
             if (flags['dry-run']) {
                 this.logInfo('Dry run complete. No files or folders were deleted.');
@@ -561,12 +453,16 @@ export default class ClearCommand extends BaseCommand {
             catch {
                 // .aiwcli doesn't exist or can't be accessed
             }
-            // Update .gitignore to remove .aiwcli if the container was deleted
-            if (removedAiwcliContainer) {
-                await updateGitignoreAfterClear(targetDir, [AIWCLI_CONTAINER]);
-                this.logDebug('Updated .gitignore');
+            // Smart gitignore removal: compute what should be removed based on disk state
+            const { toRemove, toKeep } = await computeGitignoreRemovals(targetDir);
+            for (const { entry, reason } of toKeep) {
+                this.logDebug(`Keeping ${entry}/ in .gitignore (${reason})`);
+            }
+            if (toRemove.length > 0) {
+                await removeGitignoreEntries(targetDir, toRemove);
+                this.logDebug(`Removed from .gitignore: ${toRemove.join(', ')}`);
             }
-            // Prune stale gitignore entries (paths that no longer exist on disk)
+            // Prune stale gitignore entries as safety net
             const pruned = await pruneGitignoreStaleEntries(targetDir);
             if (pruned) {
                 this.logDebug('Pruned stale .gitignore entries');
@@ -655,7 +551,7 @@ export default class ClearCommand extends BaseCommand {
                 parts.push(`${IDE_FOLDERS.windsurf.root}/ folder`);
             }
             this.logSuccess(`Cleared: ${parts.join(', ')}.`);
-            if (removedAiwcliContainer || pruned) {
+            if (toRemove.length > 0 || pruned) {
                 this.logSuccess('Updated .gitignore.');
             }
             if (updatedClaudeSettings) {
@@ -684,6 +580,7 @@ export default class ClearCommand extends BaseCommand {
      * @param targetDir - Project root directory
      * @param flags - Command flags (dry-run, force)
      */
+    // eslint-disable-next-line complexity
     async cleanRuntimeOutput(targetDir, flags) {
         const outputDir = join(targetDir, '_output');
         if (!(await pathExists(outputDir))) {
@@ -711,7 +608,7 @@ export default class ClearCommand extends BaseCommand {
                 // Log rotation: hook-log.jsonl > 1MB
                 if (entry.isFile() && entry.name === 'hook-log.jsonl') {
                     try {
-                        const stat = await fs.stat(entryPath);
+                        const stat = await fs.stat(entryPath); // eslint-disable-line no-await-in-loop
                         if (stat.size > 1_048_576) {
                             logAction = { path: entryPath, sizeBytes: stat.size };
                         }
@@ -725,7 +622,7 @@ export default class ClearCommand extends BaseCommand {
                 if (entry.isDirectory() && entry.name === 'contexts') {
                     const archivePath = join(entryPath, '_archive');
                     try {
-                        const archiveEntries = await fs.readdir(archivePath);
+                        const archiveEntries = await fs.readdir(archivePath); // eslint-disable-line no-await-in-loop
                         if (archiveEntries.length > 0) {
                             archiveDir = archivePath;
                             archiveCount = archiveEntries.length;
@@ -785,7 +682,7 @@ export default class ClearCommand extends BaseCommand {
         let deletedCount = 0;
         for (const item of toDelete) {
             try {
-                await fs.unlink(item.path);
+                await fs.unlink(item.path); // eslint-disable-line no-await-in-loop
                 deletedCount++;
             }
             catch (error) {

package/dist/commands/init/index.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { checkbox, confirm, input, select } from '@inquirer/prompts';
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../lib/base-command.js';
-import { updateGitignore } from '../../lib/gitignore-manager.js';
+import { AIW_GITIGNORE_ENTRIES, updateGitignore } from '../../lib/gitignore-manager.js';
 import { IdePathResolver } from '../../lib/ide-path-resolver.js';
 import { pathExists } from '../../lib/paths.js';
 import { getTargetSettingsFile, readClaudeSettings, writeClaudeSettings } from '../../lib/settings-hierarchy.js';
@@ -111,7 +111,7 @@ export default class Init extends BaseCommand {
                 await reconstructIdeSettings(targetDir, [], ['claude']);
                 // Update .gitignore if git repository exists
                 if (hasGit) {
-                    await updateGitignore(targetDir, ['.aiwcli']);
+                    await updateGitignore(targetDir, [...AIW_GITIGNORE_ENTRIES]);
                     this.logSuccess('✓ .gitignore updated');
                 }
                 this.log('');
@@ -178,7 +178,7 @@ export default class Init extends BaseCommand {
             });
             // Collect all folders that need gitignore entries
             // The .aiwcli/ container holds all template infrastructure and runtime data
-            const foldersForGitignore = ['.aiwcli'];
+            const foldersForGitignore = [...AIW_GITIGNORE_ENTRIES];
             // Report installation results
             if (result.installedFolders.length > 0) {
                 this.logSuccess(`✓ Installed: ${result.installedFolders.join(', ')}`);

package/dist/lib/gitignore-manager.d.ts

@@ -1,3 +1,7 @@
+/** Standard gitignore entries managed by AIW */
+export declare const AIW_GITIGNORE_ENTRIES: string[];
+/** Entries that should NEVER be removed from gitignore, even on clear */
+export declare const AIW_PERMANENT_ENTRIES: string[];
 /**
  * Prune stale entries from the AIW Installation section in .gitignore.
  * Checks each entry against disk existence and removes entries whose paths don't exist.
@@ -17,3 +21,31 @@ export declare function pruneGitignoreStaleEntries(targetDir: string): Promise<b
  * @param folders - List of folder names to add as gitignore patterns (e.g., ['_bmad', '.claude'])
  */
 export declare function updateGitignore(targetDir: string, folders: string[]): Promise<void>;
+/**
+ * Compute which AIW gitignore entries should be removed during clear.
+ * Returns a simulation result — the caller decides whether to apply.
+ *
+ * Logic per entry:
+ * - If in permanentEntries → keep (reason: "permanent")
+ * - If directory exists and is non-empty → keep (reason: "directory has content")
+ * - Otherwise → mark for removal
+ *
+ * @param targetDir - Directory containing .gitignore
+ * @param permanentEntries - Entries that should never be removed (defaults to AIW_PERMANENT_ENTRIES)
+ * @returns Lists of entries to remove and entries to keep with reasons
+ */
+export declare function computeGitignoreRemovals(targetDir: string, permanentEntries?: string[]): Promise<{
+    toKeep: Array<{
+        entry: string;
+        reason: string;
+    }>;
+    toRemove: string[];
+}>;
+/**
+ * Remove specific entries from the AIW section in .gitignore.
+ * Cleans up the section header if no entries remain.
+ *
+ * @param targetDir - Directory containing .gitignore
+ * @param entriesToRemove - Entry names to remove (without trailing slash)
+ */
+export declare function removeGitignoreEntries(targetDir: string, entriesToRemove: string[]): Promise<void>;

package/dist/lib/gitignore-manager.js

@@ -5,6 +5,10 @@ import { pathExists } from './paths.js';
  * AIW gitignore section header marker
  */
 const AIW_GITIGNORE_HEADER = '# AIW Installation';
+/** Standard gitignore entries managed by AIW */
+export const AIW_GITIGNORE_ENTRIES = ['.aiwcli', '_output', '.claude', '.windsurf'];
+/** Entries that should NEVER be removed from gitignore, even on clear */
+export const AIW_PERMANENT_ENTRIES = ['_output'];
 /**
  * Prune stale entries from the AIW Installation section in .gitignore.
  * Checks each entry against disk existence and removes entries whose paths don't exist.
@@ -35,7 +39,7 @@ export async function pruneGitignoreStaleEntries(targetDir) {
                 // AIW section ends at empty line or another comment header
                 if (line === '' || (line.startsWith('#') && line !== AIW_GITIGNORE_HEADER)) {
                     inAiwSection = false;
-                    const { lines: filtered, pruned: sectionPruned } = await pruneSection(aiwSectionLines, targetDir);
+                    const { lines: filtered, pruned: sectionPruned } = await pruneSection(aiwSectionLines, targetDir); // eslint-disable-line no-await-in-loop
                     if (sectionPruned)
                         pruned = true;
                     newLines.push(...filtered, line);
@@ -88,7 +92,7 @@ async function pruneSection(sectionLines, targetDir) {
         // Check if the path exists on disk
         const cleanPath = line.replace(/^\//, '').replace(/\/$/, '');
         const absPath = join(targetDir, cleanPath);
-        if (await pathExists(absPath)) {
+        if (await pathExists(absPath)) { // eslint-disable-line no-await-in-loop
             filtered.push(line);
         }
         else {
@@ -179,3 +183,138 @@ export async function updateGitignore(targetDir, folders) {
         await fs.writeFile(gitignorePath, patternsBlock + '\n', 'utf8');
     }
 }
+/**
+ * Compute which AIW gitignore entries should be removed during clear.
+ * Returns a simulation result — the caller decides whether to apply.
+ *
+ * Logic per entry:
+ * - If in permanentEntries → keep (reason: "permanent")
+ * - If directory exists and is non-empty → keep (reason: "directory has content")
+ * - Otherwise → mark for removal
+ *
+ * @param targetDir - Directory containing .gitignore
+ * @param permanentEntries - Entries that should never be removed (defaults to AIW_PERMANENT_ENTRIES)
+ * @returns Lists of entries to remove and entries to keep with reasons
+ */
+export async function computeGitignoreRemovals(targetDir, permanentEntries = AIW_PERMANENT_ENTRIES) {
+    const gitignorePath = join(targetDir, '.gitignore');
+    const toRemove = [];
+    const toKeep = [];
+    // Read AIW section entries from .gitignore
+    let content;
+    try {
+        content = await fs.readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        return { toRemove, toKeep };
+    }
+    if (!content.includes(AIW_GITIGNORE_HEADER)) {
+        return { toRemove, toKeep };
+    }
+    // Parse entries from the AIW section
+    const lines = content.split('\n');
+    let inAiwSection = false;
+    const aiwEntries = [];
+    for (const line of lines) {
+        if (line === AIW_GITIGNORE_HEADER) {
+            inAiwSection = true;
+            continue;
+        }
+        if (inAiwSection) {
+            if (line === '' || (line.startsWith('#') && line !== AIW_GITIGNORE_HEADER)) {
+                inAiwSection = false;
+            }
+            else {
+                // Strip trailing slash to get the directory name
+                const entry = line.replace(/\/$/, '');
+                if (entry) {
+                    aiwEntries.push(entry);
+                }
+            }
+        }
+    }
+    const permanentSet = new Set(permanentEntries);
+    // Evaluate each entry
+    await Promise.all(aiwEntries.map(async (entry) => {
+        if (permanentSet.has(entry)) {
+            toKeep.push({ entry, reason: 'permanent' });
+            return;
+        }
+        const dirPath = join(targetDir, entry);
+        const exists = await pathExists(dirPath);
+        if (exists) {
+            // Check if non-empty
+            try {
+                const entries = await fs.readdir(dirPath);
+                if (entries.length > 0) {
+                    toKeep.push({ entry, reason: 'directory has content' });
+                    return;
+                }
+            }
+            catch {
+                // Can't read — be safe, keep it
+                toKeep.push({ entry, reason: 'directory has content' });
+                return;
+            }
+        }
+        toRemove.push(entry);
+    }));
+    return { toRemove, toKeep };
+}
+/**
+ * Remove specific entries from the AIW section in .gitignore.
+ * Cleans up the section header if no entries remain.
+ *
+ * @param targetDir - Directory containing .gitignore
+ * @param entriesToRemove - Entry names to remove (without trailing slash)
+ */
+export async function removeGitignoreEntries(targetDir, entriesToRemove) {
+    const gitignorePath = join(targetDir, '.gitignore');
+    try {
+        const content = await fs.readFile(gitignorePath, 'utf8');
+        if (!content.includes(AIW_GITIGNORE_HEADER)) {
+            return;
+        }
+        const patternsToRemove = new Set(entriesToRemove.map((e) => `${e}/`));
+        const lines = content.split('\n');
+        const newLines = [];
+        let inAiwSection = false;
+        const aiwSectionLines = [];
+        for (const line of lines) {
+            if (line === AIW_GITIGNORE_HEADER) {
+                inAiwSection = true;
+                aiwSectionLines.push(line);
+                continue;
+            }
+            if (inAiwSection) {
+                if (line === '' || (line.startsWith('#') && line !== AIW_GITIGNORE_HEADER)) {
+                    inAiwSection = false;
+                    // Filter the AIW section
+                    const filtered = aiwSectionLines.filter((l) => l === AIW_GITIGNORE_HEADER || !patternsToRemove.has(l));
+                    newLines.push(...filtered, line);
+                }
+                else {
+                    aiwSectionLines.push(line);
+                }
+            }
+            else {
+                newLines.push(line);
+            }
+        }
+        // Handle AIW section at end of file
+        if (inAiwSection) {
+            const filtered = aiwSectionLines.filter((l) => l === AIW_GITIGNORE_HEADER || !patternsToRemove.has(l));
+            newLines.push(...filtered);
+        }
+        // Clean up empty AIW section
+        let result = cleanupEmptySections(newLines.join('\n'));
+        result = result.replace(/\n+$/, '\n');
+        if (result.trim() === '') {
+            result = '';
+        }
+        await fs.writeFile(gitignorePath, result, 'utf8');
+    }
+    catch {
+        // .gitignore doesn't exist or can't be read
+    }
+}

package/dist/templates/CLAUDE.md

@@ -22,9 +22,9 @@ Each template installs into `.aiwcli/` (method files) and `.{ide}/` (IDE integra
 ```
 packages/cli/src/templates/
 ├── _shared/                          # Cross-method infrastructure (installed by all methods)
-│   ├── hooks/                        # Shared hook scripts (context, tasks, sessions)
-│   └── lib/                          # Shared Python libraries
-│       ├── base/                     #   Core: atomic_write, constants, inference, utils
+│   ├── hooks-ts/                     # Shared TypeScript hook scripts (context, tasks, sessions)
+│   └── lib-ts/                       # Shared TypeScript libraries
+│       ├── base/                     #   Core: atomic-write, constants, inference, utils
 │       ├── context/                  #   Context CRUD, selection, formatting, plans, tasks
 │       ├── handoff/                  #   Session handoff document generation
 │       └── templates/                #   Output formatters, plan context templates
@@ -85,7 +85,7 @@ When multiple templates install, settings.json files merge:
 
 ## Hooks
 
-**Location:** Hooks live in `.aiwcli/_shared/hooks/` (cross-method) and `.aiwcli/_{method}/hooks/` (method-specific). They are configured in `.{ide}/settings.json`, not placed in IDE directories.
+**Location:** Hooks live in `.aiwcli/_shared/hooks-ts/` (cross-method, TypeScript) and `.aiwcli/_{method}/hooks/` (method-specific). They are configured in `.{ide}/settings.json`, not placed in IDE directories.
 
 **Configuration:**
 ```json
@@ -93,14 +93,14 @@ When multiple templates install, settings.json files merge:
   "hooks": {
     "PostToolUse": [{
       "matcher": "Write",
-      "hooks": [{ "type": "command", "command": "python .aiwcli/_cc-native/hooks/cc-native-plan-review.py", "timeout": 300000 }]
+      "hooks": [{ "type": "command", "command": "bun run .aiwcli/_cc-native/hooks/cc-native-plan-review.ts", "timeout": 300000 }]
     }]
   }
 }
 ```
 
 **Requirements:**
-- Prefix method-specific hooks with method name (e.g., `cc-native-plan-review.py`)
+- Prefix method-specific hooks with method name (e.g., `cc-native-plan-review.ts`)
 - Use relative paths from project root
 - Write outputs to `_output/{method}/`
 - Specify timeouts
@@ -161,7 +161,7 @@ Load and execute `_{method}/workflows/{name}.md`.
 | Template file | `UPPERCASE.md.template` | `PROJECT.md.template` |
 | Workflow file | `kebab-case.md` | `new-project.md` |
 | Output file | `UPPERCASE.md` | `PROJECT.md` |
-| Hook file | `{method}-{name}.{ext}` | `gsd-plan-review.py` |
+| Hook file | `{method}-{name}.{ext}` | `gsd-plan-review.ts` |
 | Settings key | `{method}` | `"gsd": {}` |
 | Readme | `{METHOD}-README.md` | `GSD-README.md` |
 
@@ -202,4 +202,4 @@ Load and execute `_{method}/workflows/{name}.md`.
 - Full workflows in IDE command files
 - Hardcoded paths without method namespace
 - Putting hook scripts directly in IDE directories (`.claude/hooks/`)
-- Creating `_shared/` directories inside method templates (e.g., `cc-native/_shared/`). All shared code lives in `packages/cli/src/templates/_shared/`. Method templates reference shared code via sys.path at runtime, not by copying.
+- Creating `_shared/` directories inside method templates (e.g., `cc-native/_shared/`). All shared code lives in `packages/cli/src/templates/_shared/`. Method templates reference shared code via imports at runtime, not by copying.

package/dist/templates/_shared/.claude/commands/handoff-resume.md

@@ -0,0 +1,64 @@
+# Resume Handoff
+
+Restore session context from a handoff document programmatically, then create actionable ISC tasks so work continues without re-discovering what was already learned.
+
+## Arguments
+
+- `$ARGUMENTS` - Optional path to a handoff folder or index.md. If omitted, auto-discovers the most recent handoff from the active context.
+
+## Instructions
+
+### Step 1: Gather Context via Script
+
+Run the resume script to collect and format all handoff sections:
+
+**If `$ARGUMENTS` is provided:**
+```bash
+bun .aiwcli/_shared/scripts/resume_handoff.ts "$ARGUMENTS"
+```
+
+**If `$ARGUMENTS` is empty:**
+The script auto-discovers the active context ID programmatically — no manual lookup needed:
+```bash
+bun .aiwcli/_shared/scripts/resume_handoff.ts
+```
+
+Present the script's output to the conversation. The output is already structured in priority order (dead ends first, then pending items, decisions, git delta, completed work, context notes).
+
+If the script exits with an error, show the error message and stop.
+
+### Step 2: Create ISC Tasks
+
+Convert each actionable item from the script output into a task via `TaskCreate`:
+- Each pending issue from the **Pending Items** section
+- Each remaining plan item from the **Plan — Remaining Items** section
+
+Each task follows ISC format — ~8 words, states a desired end-state (not an action), and is binary testable in 2 seconds.
+
+**Example:**
+
+| Source | ISC Task |
+|--------|----------|
+| Pending: "Fix race condition in SessionStore" | "SessionStore handles concurrent access without race conditions" |
+| Plan remaining: "Add retry logic to API client" | "API client retries failed requests with exponential backoff" |
+| Next step: "Write tests for auth flow" | "Auth flow has passing integration test coverage" |
+
+### Step 3: Confirm Ready
+
+After creating tasks, run `TaskList` and confirm ready to continue.
+
+## Constraints
+
+- Dead ends are presented verbatim from the script output — never summarize or omit entries
+- ISC tasks use ~8-word end-state format, not action descriptions
+- Skip missing files gracefully (the script handles this)
+- If the script warns about staleness (>7 days), surface the warning prominently
+
+## Success Criteria
+
+- [ ] Script ran successfully and output the structured briefing
+- [ ] Dead ends visible in conversation (not summarized)
+- [ ] Pending items converted to ISC tasks via TaskCreate
+- [ ] Plan completion percentage visible (if plan exists)
+- [ ] Git delta visible
+- [ ] Tasks confirmed via TaskList

package/dist/templates/_shared/.claude/commands/handoff.md

@@ -19,14 +19,15 @@ Generate a handoff document summarizing the current session's work, decisions, a
 
 ### Step 1: Get Context ID
 
-Extract the `context_id` from the system reminder injected by the context enforcer hook.
+Resolve the active context ID programmatically:
 
-Look for the pattern in the system reminder:
-```
-Active Context: {context_id}
+```bash
+bun .aiwcli/_shared/scripts/resolve_context.ts
 ```
 
-If no active context is found, inform the user and stop - handoffs require an active context.
+This prints the active context ID to stdout. Use its output as `{context_id}` in subsequent steps.
+
+If the script exits with an error (no active context found), inform the user and stop — handoffs require an active context.
 
 ### Step 2: Gather Information
 
@@ -150,7 +151,7 @@ If a plan document path was provided in `$ARGUMENTS`:
 Instead of writing the file directly, pipe your handoff content to the save script:
 
 ```bash
-python .aiwcli/_shared/scripts/save_handoff.py "{context_id}" <<'EOF'
+bun .aiwcli/_shared/scripts/save_handoff.ts "{context_id}" <<'EOF'
 {Your complete handoff markdown content from Step 3}
 EOF
 ```
@@ -159,9 +160,13 @@ This script:
 1. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
 2. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
 3. Copies the current plan (if any) to plan.md
-4. Records the event in the context's event log (informational only)
+4. Sets `handoff_path` to the index.md path and `handoff_consumed = false` in state.json
+5. Mode stays `active` — staging happens later via session_end hook
 
-Use the handoff folder for context in the next session.
+When the session ends, `session_end.ts` stages `active → has_handoff` (if handoff_path
+exists and handoff_consumed is false). On next `/clear`, `session_start.ts` picks up the
+`has_handoff` state, binds the new session, transitions to `active`, and injects the
+handoff content via `formatHandoffContinuation()`.
 
 ## Dead Ends Section Guidelines
 
@@ -198,7 +203,8 @@ After creating file, output:
   - plan.md (copy of current plan, if any)
 
 To continue next session:
-  The index.md will be automatically suggested when you start a new session.
+  Automatic: Handoff restored on next /clear via session_start hook.
+  Manual: Use /handoff-resume to explicitly load handoff context at any time.
   Read dead-ends.md first to avoid repeating failed approaches.
 
 ⚠️  {N} dead ends documented — avoid re-attempting these approaches
@@ -223,4 +229,4 @@ If plan was updated:
 - [ ] Git status included in index.md
 - [ ] If plan provided: checkboxes updated to reflect completion status
 - [ ] If plan provided: Session Progress Log appended
-- [ ] Context state updated to indicate handoff pending
+- [ ] State has handoff_path set and handoff_consumed = false