specweave 1.0.205 → 1.0.206

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.203" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.205" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
 
 <!-- SW:SECTION:hook-priority version="1.0.171" -->
 ## ⛔ Hook Instructions Override Everything
@@ -13,7 +13,7 @@
 **SKILL FIRST ≠ only one skill.** Chain: hook skill → `sw-frontend:*` / `sw-backend:*` / etc → implement.
 <!-- SW:END:hook-priority -->
 
-<!-- SW:SECTION:header version="1.0.202" -->
+<!-- SW:SECTION:header version="1.0.205" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
@@ -123,7 +123,7 @@ claude plugin install sw@specweave --scope project  # Team-shared
 
 SpecWeave auto-installs: LSP → project scope, sw-* → user scope.
 
-<!-- SW:SECTION:start version="1.0.202" -->
+<!-- SW:SECTION:start version="1.0.205" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -133,7 +133,7 @@ SpecWeave auto-installs: LSP → project scope, sw-* → user scope.
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.202" -->
+<!-- SW:SECTION:autodetect version="1.0.205" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -143,7 +143,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.203" -->
+<!-- SW:SECTION:metarule version="1.0.205" -->
 ## Workflow Orchestration
 
 ### 1. Plan Mode Default
@@ -170,7 +170,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.202" -->
+<!-- SW:SECTION:rules version="1.0.205" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
@@ -189,7 +189,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
    Use next available number. **NEVER create duplicate prefixes.**
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.202" -->
+<!-- SW:SECTION:workflow version="1.0.205" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -235,7 +235,7 @@ project/
 **NEVER assume single-repo mode without scanning first!**
 <!-- SW:END:save-nested-repos -->
 
-<!-- SW:SECTION:reflect version="1.0.202" -->
+<!-- SW:SECTION:reflect version="1.0.205" -->
 ## Skill Memories
 
 SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
@@ -254,7 +254,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 - **2026-02-02**: Use subagents liberally for codebase analysis - up to 10+ concurrent for large-scale exploration
 - **2026-02-02**: Prefer leaderboard-style reporting when analyzing usage patterns or identifying deletion candidates
 
-<!-- SW:SECTION:context version="1.0.202" -->
+<!-- SW:SECTION:context version="1.0.205" -->
 ## Context
 
 **Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
@@ -262,7 +262,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Load context**: `/sw:context <topic>` loads relevant living docs into conversation
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:structure version="1.0.202" -->
+<!-- SW:SECTION:structure version="1.0.205" -->
 ## Structure
 
 ```
@@ -277,7 +277,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.202" -->
+<!-- SW:SECTION:taskformat version="1.0.205" -->
 ## Task Format
 
 ```markdown
@@ -287,7 +287,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.202" -->
+<!-- SW:SECTION:secrets version="1.0.205" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -301,7 +301,7 @@ gh auth status
 **SECURITY**: NEVER use `grep TOKEN .env` without `-q` flag - it exposes credentials in terminal!
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.202" -->
+<!-- SW:SECTION:syncing version="1.0.205" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **Commands**: `/sw-github:sync {id}` (issues) | `/sw:sync-specs` (living docs only)
@@ -311,7 +311,7 @@ gh auth status
 **Config**: Set `sync.github.enabled: true` + `canUpdateExternalItems: true` in config.json
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:testing version="1.0.202" -->
+<!-- SW:SECTION:testing version="1.0.205" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -323,7 +323,7 @@ vi.mock('./module', () => ({ func: mockFn }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:tdd version="1.0.202" -->
+<!-- SW:SECTION:tdd version="1.0.205" -->
 ## TDD Mode (Test-Driven Development)
 
 **When `testing.defaultTestMode: "TDD"` is configured**, follow RED-GREEN-REFACTOR discipline:
@@ -384,7 +384,7 @@ When TDD is enabled, tasks include phase markers:
 **Rule**: Complete dependencies BEFORE dependent tasks (RED before GREEN).
 <!-- SW:END:tdd -->
 
-<!-- SW:SECTION:api version="1.0.202" -->
+<!-- SW:SECTION:api version="1.0.205" -->
 ## API Development (OpenAPI-First)
 
 **For API projects only.** Commands: `/sw:api-docs --all` | `--openapi` | `--postman` | `--validate`
@@ -392,13 +392,13 @@ When TDD is enabled, tasks include phase markers:
 Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.202" -->
+<!-- SW:SECTION:limits version="1.0.205" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.203" -->
+<!-- SW:SECTION:troubleshooting version="1.0.205" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -411,7 +411,7 @@ Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 | Session stuck | Kill + `rm -f .specweave/state/*.lock` + restart |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:lazyloading version="1.0.202" -->
+<!-- SW:SECTION:lazyloading version="1.0.205" -->
 ## Plugin Auto-Loading
 
 Plugins load automatically based on project type and keywords. Manual install if needed:
@@ -425,7 +425,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 **Token savings**: Core ~3-5K tokens vs all plugins ~60K+
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.203" -->
+<!-- SW:SECTION:principles version="1.0.205" -->
 ## Principles
 
 ### SpecWeave Principles
@@ -441,7 +441,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 - **Demand Elegance**: For non-trivial changes, pause and ask "is there a more elegant way?" - but skip this for simple, obvious fixes (don't over-engineer).
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.202" -->
+<!-- SW:SECTION:linking version="1.0.205" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -449,7 +449,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.202" -->
+<!-- SW:SECTION:mcp version="1.0.205" -->
 ## External Services
 
 **Priority**: CLI tools first (simpler) → MCP for complex integrations
@@ -471,7 +471,7 @@ claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server
 MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:auto version="1.0.202" -->
+<!-- SW:SECTION:auto version="1.0.205" -->
 ## Auto Mode
 
 **Commands**: `/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency only)
@@ -488,7 +488,7 @@ MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 **STOP & ASK** if: Spec conflicts | Task unnecessary | Requirement ambiguous
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.202" -->
+<!-- SW:SECTION:docs version="1.0.205" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com)

package/bin/specweave.js

@@ -409,6 +409,34 @@ program
     });
   });
 
+// Decision log command - Query structured decision logs
+program
+  .command('decision-log')
+  .description('Query structured decision logs from hooks')
+  .option('--hook <name>', 'Filter by hook name (stop-auto, stop-reflect)')
+  .option('--decision <type>', 'Filter by decision type (approve, block)')
+  .option('--since <window>', 'Filter by time window (1h, 24h, 7d)')
+  .option('--limit <number>', 'Number of entries to show (default: 20)', '20')
+  .option('--json', 'Output raw JSON format')
+  .option('--tail', 'Follow log in real-time (like tail -f)')
+  .action(async (options) => {
+    const { decisionLogCommand, decisionLogTail } = await import('../dist/src/cli/commands/decision-log.js');
+    if (options.tail) {
+      await decisionLogTail({
+        hook: options.hook,
+        decision: options.decision
+      });
+    } else {
+      await decisionLogCommand({
+        hook: options.hook,
+        decision: options.decision,
+        since: options.since,
+        limit: parseInt(options.limit, 10),
+        json: options.json
+      });
+    }
+  });
+
 // Status line command - Display current increment progress
 program
   .command('status-line')

package/dist/src/cli/commands/decision-log.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file decision-log.ts
+ * @description CLI command to query structured decision logs from hooks
+ *
+ * Usage:
+ *   specweave decision-log                     # Show last 20 decisions
+ *   specweave decision-log --hook stop-auto    # Filter by hook
+ *   specweave decision-log --decision block    # Filter by decision type
+ *   specweave decision-log --since 1h          # Filter by time window
+ *   specweave decision-log --json              # Raw JSON output
+ *   specweave decision-log --limit 50          # Custom limit
+ */
+export interface DecisionLogEntry {
+    timestamp: string;
+    hook: string;
+    decision: 'approve' | 'block';
+    reason: string;
+    reasonCode: string;
+    durationMs: number;
+    context: Record<string, unknown>;
+}
+export interface DecisionLogCommandOptions {
+    projectRoot?: string;
+    hook?: string;
+    decision?: 'approve' | 'block';
+    since?: string;
+    limit?: number;
+    json?: boolean;
+    tail?: boolean;
+}
+export interface DecisionLogResult {
+    entries: DecisionLogEntry[];
+    format: 'table' | 'json';
+}
+/**
+ * CLI command to query decision logs
+ */
+export declare function decisionLogCommand(options?: DecisionLogCommandOptions): Promise<DecisionLogResult>;
+/**
+ * Watch mode for --tail option (follows log file)
+ */
+export declare function decisionLogTail(options?: DecisionLogCommandOptions): Promise<void>;
+//# sourceMappingURL=decision-log.d.ts.map

package/dist/src/cli/commands/decision-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-log.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/decision-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B;AAqJD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAmC5B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CA2Df"}

package/dist/src/cli/commands/decision-log.js

@@ -0,0 +1,216 @@
+/**
+ * @file decision-log.ts
+ * @description CLI command to query structured decision logs from hooks
+ *
+ * Usage:
+ *   specweave decision-log                     # Show last 20 decisions
+ *   specweave decision-log --hook stop-auto    # Filter by hook
+ *   specweave decision-log --decision block    # Filter by decision type
+ *   specweave decision-log --since 1h          # Filter by time window
+ *   specweave decision-log --json              # Raw JSON output
+ *   specweave decision-log --limit 50          # Custom limit
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+/**
+ * Parse time window string (1h, 24h, 7d) to milliseconds
+ */
+function parseSinceWindow(since) {
+    const match = since.match(/^(\d+)(h|d|m)$/);
+    if (!match) {
+        throw new Error(`Invalid time window format: ${since}. Use 1h, 24h, 7d, etc.`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    const multipliers = {
+        m: 60 * 1000, // minutes
+        h: 60 * 60 * 1000, // hours
+        d: 24 * 60 * 60 * 1000, // days
+    };
+    return value * multipliers[unit];
+}
+/**
+ * Read and parse the decisions.jsonl file
+ */
+async function readDecisionLog(logPath) {
+    if (!fs.existsSync(logPath)) {
+        return [];
+    }
+    const content = fs.readFileSync(logPath, 'utf-8');
+    const lines = content.split('\n').filter((line) => line.trim());
+    const entries = [];
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            entries.push(entry);
+        }
+        catch {
+            // Skip malformed JSON lines
+        }
+    }
+    return entries;
+}
+/**
+ * Filter entries based on options
+ */
+function filterEntries(entries, options) {
+    let filtered = [...entries];
+    // Filter by hook name
+    if (options.hook) {
+        filtered = filtered.filter((e) => e.hook === options.hook);
+    }
+    // Filter by decision type
+    if (options.decision) {
+        filtered = filtered.filter((e) => e.decision === options.decision);
+    }
+    // Filter by time window
+    if (options.since) {
+        const windowMs = parseSinceWindow(options.since);
+        const cutoff = Date.now() - windowMs;
+        filtered = filtered.filter((e) => {
+            const entryTime = new Date(e.timestamp).getTime();
+            return entryTime >= cutoff;
+        });
+    }
+    return filtered;
+}
+/**
+ * Sort entries by timestamp (most recent first) and apply limit
+ */
+function sortAndLimit(entries, limit) {
+    return entries
+        .sort((a, b) => {
+        const timeA = new Date(a.timestamp).getTime();
+        const timeB = new Date(b.timestamp).getTime();
+        return timeB - timeA; // Most recent first
+    })
+        .slice(0, limit);
+}
+/**
+ * Format a single entry for table display
+ */
+function formatEntryForTable(entry) {
+    const timestamp = new Date(entry.timestamp).toLocaleString();
+    const hook = entry.hook.padEnd(15);
+    const decision = entry.decision === 'approve'
+        ? chalk.green('✓ approve')
+        : chalk.red('✗ block');
+    const decisionPadded = decision.padEnd(20);
+    const reason = entry.reason.substring(0, 40);
+    const duration = `${entry.durationMs}ms`;
+    return `${timestamp.padEnd(22)} ${hook} ${decisionPadded} ${duration.padEnd(10)} ${reason}`;
+}
+/**
+ * Display entries in table format
+ */
+function displayTable(entries) {
+    if (entries.length === 0) {
+        console.log(chalk.yellow('No decision log entries found.'));
+        return;
+    }
+    console.log('\n' + chalk.bold.underline('Decision Log') + '\n');
+    console.log(chalk.bold('Timestamp'.padEnd(22) +
+        ' Hook'.padEnd(16) +
+        ' Decision'.padEnd(21) +
+        ' Duration'.padEnd(11) +
+        ' Reason'));
+    console.log(chalk.dim('─'.repeat(100)));
+    for (const entry of entries) {
+        console.log(formatEntryForTable(entry));
+    }
+    console.log('\n' + chalk.dim(`Showing ${entries.length} entries`) + '\n');
+}
+/**
+ * Display entries in JSON format
+ */
+function displayJson(entries) {
+    for (const entry of entries) {
+        console.log(JSON.stringify(entry));
+    }
+}
+/**
+ * CLI command to query decision logs
+ */
+export async function decisionLogCommand(options = {}) {
+    const { projectRoot = process.cwd(), hook, decision, since, limit = 20, json = false, } = options;
+    // Determine log file path
+    const logPath = path.join(projectRoot, '.specweave', 'logs', 'decisions.jsonl');
+    // Read all entries
+    const allEntries = await readDecisionLog(logPath);
+    // Apply filters
+    const filtered = filterEntries(allEntries, { hook, decision, since });
+    // Sort and limit
+    const result = sortAndLimit(filtered, limit);
+    // Display output (only when running as CLI, not when testing)
+    if (!options.projectRoot || options.projectRoot === process.cwd()) {
+        if (json) {
+            displayJson(result);
+        }
+        else {
+            displayTable(result);
+        }
+    }
+    return {
+        entries: result,
+        format: json ? 'json' : 'table',
+    };
+}
+/**
+ * Watch mode for --tail option (follows log file)
+ */
+export async function decisionLogTail(options = {}) {
+    const { projectRoot = process.cwd(), hook, decision } = options;
+    const logPath = path.join(projectRoot, '.specweave', 'logs', 'decisions.jsonl');
+    console.log(chalk.yellow(`Watching ${logPath} for new entries...`));
+    console.log(chalk.dim('Press Ctrl+C to stop.\n'));
+    // Track file position
+    let lastSize = 0;
+    if (fs.existsSync(logPath)) {
+        const stats = fs.statSync(logPath);
+        lastSize = stats.size;
+    }
+    // Watch for changes
+    const watcher = fs.watch(path.dirname(logPath), (event, filename) => {
+        if (filename === 'decisions.jsonl') {
+            if (!fs.existsSync(logPath))
+                return;
+            const stats = fs.statSync(logPath);
+            if (stats.size > lastSize) {
+                // Read new content
+                const fd = fs.openSync(logPath, 'r');
+                const buffer = Buffer.alloc(stats.size - lastSize);
+                fs.readSync(fd, buffer, 0, buffer.length, lastSize);
+                fs.closeSync(fd);
+                const newContent = buffer.toString('utf-8');
+                const lines = newContent.split('\n').filter((l) => l.trim());
+                for (const line of lines) {
+                    try {
+                        const entry = JSON.parse(line);
+                        // Apply filters
+                        if (hook && entry.hook !== hook)
+                            continue;
+                        if (decision && entry.decision !== decision)
+                            continue;
+                        console.log(formatEntryForTable(entry));
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+                lastSize = stats.size;
+            }
+            else if (stats.size < lastSize) {
+                // File was truncated/rotated
+                lastSize = stats.size;
+            }
+        }
+    });
+    // Keep process alive
+    process.on('SIGINT', () => {
+        watcher.close();
+        console.log('\nStopped watching.');
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=decision-log.js.map

package/dist/src/cli/commands/decision-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-log.js","sourceRoot":"","sources":["../../../../src/cli/commands/decision-log.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.205",
+  "version": "1.0.206",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/stop-reflect.sh

@@ -1,16 +1,24 @@
 #!/bin/bash
-# stop-reflect.sh - Session Reflection Hook (v3.0 - Uses TypeScript)
+# stop-reflect.sh - Session Reflection Hook (v3.1 - Structured Decision Logging)
 #
-# ARCHITECTURE (v3.0):
+# ARCHITECTURE (v3.1):
 # - Uses specweave CLI (TypeScript) for reflection
 # - Learnings go to CLAUDE.md under "## Skill Memories" section
 # - User can disable via config: { "reflect": { "enabled": false } }
+# - Structured decision logging to .specweave/logs/decisions.jsonl
 #
 # This hook ALWAYS approves (never blocks sessions) but may trigger
 # background learning extraction if enabled.
 
 set +e  # Never fail - this is a non-critical hook
 
+# Capture start time for duration tracking (macOS doesn't support %N, fallback to seconds only)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    _START_TIME_MS=$(($(date +%s) * 1000))
+else
+    _START_TIME_MS=$(($(date +%s) * 1000 + $(date +%N 2>/dev/null | cut -c1-3 || echo "0")))
+fi
+
 # Read input from stdin (required by Claude Code hooks)
 INPUT=$(cat)
 
@@ -23,6 +31,23 @@ CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
 LOGS_DIR="$PROJECT_ROOT/.specweave/logs/reflect"
 STATE_DIR="$PROJECT_ROOT/.specweave/state"
 
+# Source the shared decision logging utility
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/log-decision.sh" ]; then
+    source "$SCRIPT_DIR/log-decision.sh"
+fi
+
+# Get duration in milliseconds
+_get_duration_ms() {
+    local end_time_ms
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        end_time_ms=$(($(date +%s) * 1000))
+    else
+        end_time_ms=$(($(date +%s) * 1000 + $(date +%N 2>/dev/null | cut -c1-3 || echo "0")))
+    fi
+    echo $((end_time_ms - _START_TIME_MS))
+}
+
 # Ensure logs directory exists
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
@@ -44,13 +69,45 @@ log_reflect() {
     echo "[$timestamp] [$level] $*" >> "$log_file" 2>/dev/null || true
 }
 
+# Log decision with context for structured logging
+log_reflect_decision() {
+    local reason_code="$1"
+    local reason="$2"
+    local transcript_lines="${3:-0}"
+    local reflection_enabled="${4:-true}"
+    local learnings_extracted="${5:-0}"
+    local learning_categories_json="${6:-[]}"
+
+    if type log_decision &>/dev/null; then
+        local context_json
+        context_json=$(jq -n \
+            --argjson transcriptLines "$transcript_lines" \
+            --argjson reflectionEnabled "$reflection_enabled" \
+            --argjson learningsExtracted "$learnings_extracted" \
+            --argjson learningCategories "$learning_categories_json" \
+            --arg exitReason "$reason_code" \
+            --arg triggerReason "session_end" \
+            '{
+                transcriptLines: $transcriptLines,
+                reflectionEnabled: $reflectionEnabled,
+                learningsExtracted: $learningsExtracted,
+                learningCategories: $learningCategories,
+                exitReason: $exitReason,
+                triggerReason: $triggerReason
+            }')
+
+        log_decision "stop-reflect" "approve" "$reason_code" "$reason" "$context_json" "$(_get_duration_ms)"
+    fi
+}
+
 # Check if reflection is enabled
 is_reflect_enabled() {
     if [ ! -f "$CONFIG_FILE" ]; then
         return 0  # Default to enabled if no config
     fi
 
-    local enabled=$(jq -r '.reflect.enabled // true' "$CONFIG_FILE" 2>/dev/null)
+    # Note: can't use // true because jq treats false as falsy
+    local enabled=$(jq -r 'if .reflect.enabled == false then "false" else "true" end' "$CONFIG_FILE" 2>/dev/null)
     [ "$enabled" = "true" ]
 }
 
@@ -131,6 +188,82 @@ run_reflection() {
     return 0
 }
 
+# Run reflection with structured logging (synchronous for test purposes, captures learnings)
+run_reflection_with_logging() {
+    local transcript="$1"
+    local transcript_lines="$2"
+    local learnings_extracted=0
+    local learning_categories="[]"
+    local exit_reason="nothing_to_learn"
+    local reason_msg="No learnings extracted"
+
+    log_reflect "info" "Starting reflection ($transcript_lines lines)"
+
+    # Use specweave CLI (TypeScript implementation)
+    if command -v specweave >/dev/null 2>&1; then
+        # Create a temp file to capture output
+        local temp_output
+        temp_output=$(mktemp)
+
+        (
+            cd "$PROJECT_ROOT"
+            run_with_timeout 60 specweave reflect-stop "$transcript" --silent 2>&1 | tee "$temp_output" >> "$LOGS_DIR/auto-reflect.log"
+            local result=$?
+
+            # Parse learnings from output
+            if [ -f "$temp_output" ]; then
+                # Try to extract learnings count from output
+                local count_line
+                count_line=$(grep -i "learnings extracted:" "$temp_output" 2>/dev/null | head -1)
+                if [ -n "$count_line" ]; then
+                    learnings_extracted=$(echo "$count_line" | grep -oE '[0-9]+' | head -1)
+                    learnings_extracted=${learnings_extracted:-0}
+                fi
+
+                # Try to extract categories from output
+                local cat_line
+                cat_line=$(grep -i "categories:" "$temp_output" 2>/dev/null | head -1)
+                if [ -n "$cat_line" ]; then
+                    # Convert "Categories: devops, logging" to JSON array
+                    local cats
+                    cats=$(echo "$cat_line" | sed 's/.*[Cc]ategories:[[:space:]]*//' | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$' | jq -R . | jq -s .)
+                    learning_categories=${cats:-"[]"}
+                fi
+            fi
+
+            # Determine exit reason based on result and learnings
+            if [ $result -eq 124 ]; then
+                exit_reason="timeout"
+                reason_msg="Reflection timed out"
+                log_reflect "warn" "Reflection timed out"
+            elif [ $result -ne 0 ]; then
+                exit_reason="error"
+                reason_msg="Reflection error (exit $result)"
+                log_reflect "warn" "Reflection completed with exit code $result"
+            elif [ "$learnings_extracted" -gt 0 ]; then
+                exit_reason="learnings_saved"
+                reason_msg="Extracted $learnings_extracted learnings"
+                log_reflect "info" "Reflection completed successfully"
+            else
+                exit_reason="nothing_to_learn"
+                reason_msg="No learnings to extract"
+                log_reflect "info" "Reflection completed - no learnings"
+            fi
+
+            # Log the decision with full context
+            log_reflect_decision "$exit_reason" "$reason_msg" "$transcript_lines" true "$learnings_extracted" "$learning_categories"
+
+            rm -f "$temp_output" 2>/dev/null
+        ) &
+        log_reflect "info" "Reflection started in background"
+    else
+        log_reflect "warn" "specweave CLI not found"
+        log_reflect_decision "error" "specweave CLI not found" "$transcript_lines" true 0 "[]"
+    fi
+
+    return 0
+}
+
 # Main execution
 main() {
     # SILENT approve - prevents UI feedback loops
@@ -139,14 +272,45 @@ main() {
     # Always cleanup ephemeral session state
     cleanup_session_state
 
+    # Check if reflection is enabled first
+    local reflect_enabled=true
+    if [ -f "$CONFIG_FILE" ]; then
+        local enabled_val
+        # Note: can't use // true because jq treats false as falsy
+        # Use if-then-else to properly handle boolean false
+        enabled_val=$(jq -r 'if .reflect.enabled == false then "false" else "true" end' "$CONFIG_FILE" 2>/dev/null)
+        if [ "$enabled_val" = "false" ]; then
+            reflect_enabled=false
+        fi
+    fi
+
     # Quick bail if no transcript
     if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+        log_reflect_decision "no_transcript" "No transcript available" 0 "$reflect_enabled" 0 "[]"
+        echo "$silent_approve"
+        exit 0
+    fi
+
+    # Get transcript line count
+    local transcript_lines
+    transcript_lines=$(wc -l < "$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ') || transcript_lines=0
+
+    # Check if reflection is disabled
+    if [ "$reflect_enabled" = "false" ]; then
+        log_reflect_decision "disabled" "Reflection disabled in config" "$transcript_lines" false 0 "[]"
+        echo "$silent_approve"
+        exit 0
+    fi
+
+    # Check if transcript is too short
+    if [ "$transcript_lines" -lt 10 ]; then
+        log_reflect_decision "transcript_too_short" "Transcript too short ($transcript_lines lines)" "$transcript_lines" true 0 "[]"
         echo "$silent_approve"
         exit 0
     fi
 
-    # Run reflection (async, non-blocking)
-    run_reflection "$TRANSCRIPT_PATH"
+    # Run reflection (async, non-blocking) and capture learnings
+    run_reflection_with_logging "$TRANSCRIPT_PATH" "$transcript_lines"
 
     # Always approve
     echo "$silent_approve"

package/plugins/specweave/skills/image-generation/SKILL.md

@@ -14,6 +14,29 @@ model: opus
 
 Expert in generating professional-quality images using multi-provider resilience: **Pollinations.ai** (primary) with **Stable Horde** (fallback) - both FREE, no API keys required.
 
+---
+
+## 🛑 STEP 1: RUN THIS BASH COMMAND FIRST (MANDATORY - NO EXCEPTIONS)
+
+**YOU MUST EXECUTE THIS BASH COMMAND BEFORE DOING ANYTHING ELSE.**
+
+This is not optional. Do not skip. Do not generate URLs first. **RUN THIS FIRST:**
+
+```bash
+TEMP=$(mktemp) && curl -s -L -o "$TEMP" --max-time 10 "https://image.pollinations.ai/prompt/test?width=64&height=64&nologo=true" 2>/dev/null && TYPE=$(file -b "$TEMP" | cut -d',' -f1) && rm -f "$TEMP" && if [[ "$TYPE" == "PNG image data" ]] || [[ "$TYPE" == "JPEG image data" ]]; then echo "PROVIDER=pollinations"; else echo "PROVIDER=stablehorde"; echo "REASON=Got $TYPE instead of image"; fi
+```
+
+### Based on Output:
+
+| Output | What To Do |
+|--------|------------|
+| `PROVIDER=pollinations` | ✅ Use Pollinations.ai URLs below |
+| `PROVIDER=stablehorde` | 🔄 **SKIP Pollinations entirely** → Use Stable Horde API (see fallback section) |
+
+**If you did NOT run the Bash command first, STOP and run it now.**
+
+---
+
 ## ⚠️ CRITICAL: Health Check First (MANDATORY)
 
 **BEFORE generating any image, ALWAYS run this CONTENT-BASED health check:**

package/src/templates/AGENTS.md.template

@@ -107,45 +107,70 @@
 
 **Claude Code has built-in orchestration features. Non-Claude tools must implement these manually.**
 
-### 1. Plan Mode Default
+### 1. Plan Mode Default (Use SpecWeave Increments!)
 
-**Claude Code**: Has `EnterPlanMode` tool that automatically enters planning state for complex tasks.
+**Claude Code**: Has `EnterPlanMode` tool → triggers `/sw:increment` workflow automatically.
 
-**Non-Claude Tools - Manual Planning Protocol:**
+**Non-Claude Tools - Use SpecWeave Increment Structure:**
 ```
 BEFORE implementing ANY non-trivial task (3+ steps):
 
 1. STOP - Don't start coding immediately
-2. Create `.specweave/increments/XXXX-feature/plan.md`
-3. List all steps required
-4. Identify dependencies between steps
-5. Note architectural decisions needed
-6. GET USER APPROVAL before implementing
+2. Create increment folder: `.specweave/increments/XXXX-feature/`
+3. Create the 3 required files:
+   - spec.md   → WHAT & WHY (user stories, acceptance criteria)
+   - plan.md   → HOW (architecture, approach, risks)
+   - tasks.md  → Task checklist with test plans
+4. GET USER APPROVAL before implementing
 
 If something goes sideways during implementation:
 → STOP and re-plan (don't keep pushing)
-→ Update plan.md with revised approach
+→ Update spec.md/plan.md with revised approach
 → Get approval again if scope changed
 ```
 
-**Planning Template (plan.md):**
+**SpecWeave Planning Files:**
+
+**spec.md** (WHAT & WHY):
+```markdown
+---
+increment: 0001-feature-name
+title: "Feature Title"
+---
+
+### US-001: User Story Title
+**Project**: my-app              # ← MANDATORY! Get from: specweave context projects
+
+**As a** [user type]
+**I want** [goal]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: [Criterion 1]
+- [ ] **AC-US1-02**: [Criterion 2]
+```
+
+**plan.md** (HOW):
 ```markdown
 # Plan: Feature Name
 
 ## Approach
-[High-level approach description]
-
-## Steps
-1. [ ] Step one
-2. [ ] Step two (depends on: #1)
-3. [ ] Step three
+[High-level architecture/approach]
 
-## Risks/Decisions
+## Risks & Decisions
 - [ ] Decision: [question needing user input]
 - Risk: [potential issue and mitigation]
+```
 
-## Approval
-- [ ] User approved this plan
+**tasks.md** (Checklist):
+```markdown
+### T-001: Task Title
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01
+**Status**: [ ] pending
+
+**Test Plan** (BDD):
+- Given [context] → When [action] → Then [result]
 ```
 
 ### 2. Subagent Strategy (Parallel Execution)
@@ -304,9 +329,9 @@ git diff  # Review what actually changed
 
 | Capability | Claude Code | Non-Claude Tools |
 |------------|-------------|------------------|
-| **Plan Mode** | `EnterPlanMode` tool (automatic) | Manual: Create plan.md, get approval |
+| **Plan Mode** | `EnterPlanMode` → `/sw:increment` | Manual: Create spec.md + plan.md + tasks.md |
 | **Subagents** | `Task` tool spawns parallel agents | Manual: Split work, parallel prompts |
-| **Verification** | PostToolUse hooks validate | Manual: Run tests, check checklist |
+| **Verification** | PostToolUse hooks validate | Manual: Run tests, check AC checklist |
 | **Hooks** | Auto-run on events | YOU must mimic (see below) |
 | **Task sync** | Automatic AC updates | Manual: Edit tasks.md + spec.md |
 | **Commands** | Slash syntax works | Read command .md, follow manually |