aiwcli 0.12.3 → 0.12.7

package/dist/templates/_shared/handoff-system/workflows/handoff-resume.md

@@ -0,0 +1,66 @@
+# Resume Handoff Workflow
+
+## Purpose
+
+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.
+
+## Process
+
+### 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/handoff-system/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/handoff-system/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/{workflows → handoff-system/workflows}/handoff.md

@@ -1,254 +1,254 @@
-# Handoff Workflow
-
-Generate a handoff document summarizing the current session's work, decisions, and pending items. Optionally update a plan document to track completed vs remaining tasks.
-
-## Triggers
-
-- `/handoff` command
-- `/handoff path/to/PLAN.md` - with plan document integration
-- Phrases like "write a handoff", "create a session summary", "document what we did", "end session with notes"
-
-## Arguments
-
-- `$ARGUMENTS` - Optional path to a plan document. If provided, the handoff will:
-  1. Mark completed items in the plan with `[x]`
-  2. Add notes about partial progress
-  3. Append a "Session Progress" section to the plan
-
-## Process
-
-### Step 1: Get Context ID
-
-Extract the `context_id` from the system reminder injected by the user_prompt_submit hook.
-
-Look for the pattern in the system reminder:
-```
-Active Context: {context_id}
-```
-
-If no active context is found, inform the user and stop - handoffs require an active context.
-
-### Step 2: Gather Information
-
-1. Review conversation history for:
-   - Completed tasks and implementations
-   - Key decisions and their rationale
-   - Failed approaches (to avoid repeating)
-   - External context (deadlines, stakeholder requirements)
-
-2. Check git status if available:
-   ```bash
-   git status --short
-   git diff --stat
-   ```
-
-3. Look for TODOs/FIXMEs mentioned in session
-
-4. **If plan document provided**: Read the plan and identify:
-   - Tasks that are now completed
-   - Tasks that are partially done
-   - Tasks that were attempted but blocked
-   - New tasks discovered during implementation
-
-### Step 3: Generate Document
-
-Use this template. The `<!-- SECTION: name -->` markers are required for the save script to parse sections into sharded files.
-
-```markdown
----
-title: Session Handoff
-date: {ISO timestamp}
-session_id: {conversation ID if available}
-project: {project name from package.json, Cargo.toml, or directory name}
-context_id: {context_id from Step 1}
-plan_document: {path to plan if provided, or "none"}
----
-
-# Session Handoff — {Date}
-
-<!-- SECTION: summary -->
-## Summary
-{2-3 sentences: what's different now vs. session start}
-
-<!-- SECTION: completed -->
-## Work Completed
-{Grouped by category if multiple areas. Specific file:function references.}
-
-<!-- SECTION: dead-ends -->
-## Dead Ends — Do Not Retry
-
-These approaches were attempted and failed. Do not retry without addressing the root cause.
-
-| Approach | Why It Failed | Time Spent | Alternative |
-|----------|---------------|------------|-------------|
-| {What was attempted} | {Specific reason} | {Rough estimate} | {What to try instead} |
-
-<!-- SECTION: decisions -->
-## Key Decisions
-{Technical choices with rationale. Format: **Decision**: Rationale. Trade-off: X.}
-
-<!-- SECTION: pending -->
-## Pending Issues
-- [ ] {Issue} — {severity: HIGH/MED/LOW} {optional workaround note}
-
-<!-- SECTION: next-steps -->
-## Next Steps
-1. {Actionable item with file:line reference if applicable}
-
-<!-- SECTION: files -->
-## Files Modified
-{Significant changes only. Skip formatting-only edits.}
-
-<!-- SECTION: context -->
-## Context for Future Sessions
-{Non-obvious context: env quirks, stakeholder requirements}
-
-```
-
-### Step 4: Update Plan Document (if provided)
-
-If a plan document path was provided in `$ARGUMENTS`:
-
-1. **Read the plan document**
-2. **Identify completed items**:
-   - Find checkboxes `- [ ]` that match completed work
-   - Change them to `- [x]`
-3. **Add progress notes** to items that are partially complete:
-   - Append `(partial: {brief status})` to the line
-4. **Append Session Progress section** at the bottom:
-
-```markdown
-
----
-
-## Session Progress Log
-
-### {Date} — Session {session_id or timestamp}
-
-**Completed this session:**
-- [x] {Task from plan that was completed}
-- [x] {Another completed task}
-
-**Partially completed:**
-- {Task} — {current state, what remains}
-
-**Blocked/Deferred:**
-- {Task} — {reason, what's needed}
-
-**New items discovered:**
-- [ ] {New task not in original plan}
-- [ ] {Another new task}
-
----
-```
-
-5. **If no plan document was provided**:
-   - Skip plan creation - the handoff document serves as the session record
-
-### Step 5: Save and Update Status
-
-**⚠️ CRITICAL: Heredoc EOF Delimiter Placement**
-
-The closing `EOF` delimiter **MUST** be at column 0 (no leading spaces or tabs). Even a single space will cause bash to report: `unexpected EOF while looking for matching \`''`
-
-**Correct Example:**
-```bash
-bun .aiwcli/_shared/scripts/save_handoff.ts <<'EOF'
-content here
-EOF
-```
-← Notice: EOF is flush left at column 0
-
-**Wrong Example (will fail):**
-```bash
-bun .aiwcli/_shared/scripts/save_handoff.ts <<'EOF'
-content here
-  EOF
-```
-← This FAILS: EOF has leading spaces
-
----
-
-Instead of writing the file directly, pipe your handoff content to the save script:
-
-```bash
-bun .aiwcli/_shared/scripts/save_handoff.ts <<'EOF'
-{Your complete handoff markdown content from Step 3}
-EOF
-```
-
-This script:
-1. Auto-resolves the active context ID
-2. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
-3. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
-4. Copies the current plan (if any) to plan.md
-5. Sets `handoff_path` and `handoff_consumed=false` in state.json
-
-**After handoff is saved, the context becomes dormant:**
-- It will **not** auto-select when starting new sessions — new work gets a fresh context
-- It remains visible in the context picker (`^`) with a `[Handoff Ready]` label
-- To resume, use `^N` (where N is the context number) to explicitly select it
-- When selected via `^N`, the handoff content is automatically injected into the session
-- The `handoff_path` is cleared after injection to prevent re-injection
-
-## Dead Ends Section Guidelines
-
-This section is critical for preventing context rot across sessions. Be specific:
-
-**Bad (too vague):**
-> - Tried using library X, didn't work
-
-**Good (actionable):**
-> ### Fixing the race condition in SessionStore
-> | Approach Tried | Why It Failed |
-> |----------------|---------------|
-> | `async-mutex` package | Deadlock when nested calls to `getSession()` |
-> | Redis WATCH/MULTI | Our Redis 6.x cluster doesn't support WATCH in cluster mode |
-> | In-memory lock Map | Works single-node but breaks in horizontal scaling |
->
-> **What to try instead**: Upgrade to Redis 7.x which supports WATCH in cluster mode, or use Redlock algorithm
-
-**Capture these dead ends:**
-- Packages/libraries that had incompatibilities
-- Approaches that caused new bugs or regressions
-- Solutions that worked locally but failed in CI/staging/prod
-- Configurations that conflicted with existing setup
-- Rabbit holes that consumed significant time without progress
-
-## Post-Generation Output
-
-After creating file, output:
-
-```
-✓ Created handoff folder: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
-  - index.md (entry point with navigation)
-  - completed-work.md, dead-ends.md, decisions.md, pending.md, context.md
-  - 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.
-  Read dead-ends.md first to avoid repeating failed approaches.
-
-⚠️  {N} dead ends documented — avoid re-attempting these approaches
-```
-
-If plan was updated:
-```
-✓ Updated plan document: {path}
-   - {N} items marked complete
-   - {N} items partially complete
-   - {N} new items added
-```
-
-## Success Criteria
-
-- [ ] Handoff folder created at `handoffs/{YYYY-MM-DD-HHMM}/`
-- [ ] index.md contains summary and navigation table
-- [ ] All section files created (completed-work.md, dead-ends.md, etc.)
-- [ ] Dead ends use structured table format for quick scanning
-- [ ] plan.md copied from context if plan exists
-- [ ] Next steps are actionable with file references
-- [ ] 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
+# Handoff Workflow
+
+Generate a handoff document summarizing the current session's work, decisions, and pending items. Optionally update a plan document to track completed vs remaining tasks.
+
+## Triggers
+
+- `/handoff` command
+- `/handoff path/to/PLAN.md` - with plan document integration
+- Phrases like "write a handoff", "create a session summary", "document what we did", "end session with notes"
+
+## Arguments
+
+- `$ARGUMENTS` - Optional path to a plan document. If provided, the handoff will:
+  1. Mark completed items in the plan with `[x]`
+  2. Add notes about partial progress
+  3. Append a "Session Progress" section to the plan
+
+## Process
+
+### Step 1: Get Context ID
+
+Extract the `context_id` from the system reminder injected by the context enforcer hook.
+
+Look for the pattern in the system reminder:
+```
+Active Context: {context_id}
+```
+
+If no active context is found, inform the user and stop - handoffs require an active context.
+
+### Step 2: Gather Information
+
+1. Review conversation history for:
+   - Completed tasks and implementations
+   - Key decisions and their rationale
+   - Failed approaches (to avoid repeating)
+   - External context (deadlines, stakeholder requirements)
+
+2. Check git status if available:
+   ```bash
+   git status --short
+   git diff --stat
+   ```
+
+3. Look for TODOs/FIXMEs mentioned in session
+
+4. **If plan document provided**: Read the plan and identify:
+   - Tasks that are now completed
+   - Tasks that are partially done
+   - Tasks that were attempted but blocked
+   - New tasks discovered during implementation
+
+### Step 3: Generate Document
+
+Use this template. The `<!-- SECTION: name -->` markers are required for the save script to parse sections into sharded files.
+
+```markdown
+---
+title: Session Handoff
+date: {ISO timestamp}
+session_id: $CLAUDE_SESSION_ID
+context_id: {context_id from Step 1}
+project: {project name from package.json, Cargo.toml, or directory name}
+plan_document: {path to plan if provided, or "none"}
+---
+
+# Session Handoff — {Date}
+
+<!-- SECTION: summary -->
+## Summary
+{2-3 sentences: what's different now vs. session start}
+
+<!-- SECTION: completed -->
+## Work Completed
+{Grouped by category if multiple areas. Specific file:function references.}
+
+<!-- SECTION: dead-ends -->
+## Dead Ends — Do Not Retry
+
+These approaches were attempted and failed. Do not retry without addressing the root cause.
+
+| Approach | Why It Failed | Time Spent | Alternative |
+|----------|---------------|------------|-------------|
+| {What was attempted} | {Specific reason} | {Rough estimate} | {What to try instead} |
+
+<!-- SECTION: decisions -->
+## Key Decisions
+{Technical choices with rationale. Format: **Decision**: Rationale. Trade-off: X.}
+
+<!-- SECTION: pending -->
+## Pending Issues
+- [ ] {Issue} — {severity: HIGH/MED/LOW} {optional workaround note}
+
+<!-- SECTION: next-steps -->
+## Next Steps
+1. {Actionable item with file:line reference if applicable}
+
+<!-- SECTION: files -->
+## Files Modified
+{Significant changes only. Skip formatting-only edits.}
+
+<!-- SECTION: context -->
+## Context for Future Sessions
+{Non-obvious context: env quirks, stakeholder requirements}
+
+```
+
+### Step 4: Update Plan Document (if provided)
+
+If a plan document path was provided in `$ARGUMENTS`:
+
+1. **Read the plan document**
+2. **Identify completed items**:
+   - Find checkboxes `- [ ]` that match completed work
+   - Change them to `- [x]`
+3. **Add progress notes** to items that are partially complete:
+   - Append `(partial: {brief status})` to the line
+4. **Append Session Progress section** at the bottom:
+
+```markdown
+
+---
+
+## Session Progress Log
+
+### {Date} — Session {session_id or timestamp}
+
+**Completed this session:**
+- [x] {Task from plan that was completed}
+- [x] {Another completed task}
+
+**Partially completed:**
+- {Task} — {current state, what remains}
+
+**Blocked/Deferred:**
+- {Task} — {reason, what's needed}
+
+**New items discovered:**
+- [ ] {New task not in original plan}
+- [ ] {Another new task}
+
+---
+```
+
+5. **If no plan document was provided**:
+   - Skip plan creation - the handoff document serves as the session record
+
+### Step 5: Save and Update Status
+
+**⚠️ CRITICAL: Heredoc EOF Delimiter Placement**
+
+The closing `EOF` delimiter **MUST** be at column 0 (no leading spaces or tabs). Even a single space will cause bash to report: `unexpected EOF while looking for matching \`''`
+
+**Correct Example:**
+```bash
+bun .aiwcli/_shared/handoff-system/scripts/save_handoff.ts <<'EOF'
+content here
+EOF
+```
+← Notice: EOF is flush left at column 0
+
+**Wrong Example (will fail):**
+```bash
+bun .aiwcli/_shared/handoff-system/scripts/save_handoff.ts <<'EOF'
+content here
+  EOF
+```
+← This FAILS: EOF has leading spaces
+
+---
+
+Instead of writing the file directly, pipe your handoff content to the save script:
+
+```bash
+bun .aiwcli/_shared/handoff-system/scripts/save_handoff.ts <<'EOF'
+{Your complete handoff markdown content from Step 3}
+EOF
+```
+
+This script:
+1. Auto-resolves the active context ID
+2. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+3. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
+4. Copies the current plan (if any) to plan.md
+5. Sets `handoff_path` and `handoff_consumed=false` in state.json
+
+**After handoff is saved, the context becomes dormant:**
+- It will **not** auto-select when starting new sessions — new work gets a fresh context
+- It remains visible in the context picker (`^`) with a `[Handoff Ready]` label
+- To resume, use `^N` (where N is the context number) to explicitly select it
+- When selected via `^N`, the handoff content is automatically injected into the session
+- The `handoff_path` is cleared after injection to prevent re-injection
+
+## Dead Ends Section Guidelines
+
+This section is critical for preventing context rot across sessions. Be specific:
+
+**Bad (too vague):**
+> - Tried using library X, didn't work
+
+**Good (actionable):**
+> ### Fixing the race condition in SessionStore
+> | Approach Tried | Why It Failed |
+> |----------------|---------------|
+> | `async-mutex` package | Deadlock when nested calls to `getSession()` |
+> | Redis WATCH/MULTI | Our Redis 6.x cluster doesn't support WATCH in cluster mode |
+> | In-memory lock Map | Works single-node but breaks in horizontal scaling |
+>
+> **What to try instead**: Upgrade to Redis 7.x which supports WATCH in cluster mode, or use Redlock algorithm
+
+**Capture these dead ends:**
+- Packages/libraries that had incompatibilities
+- Approaches that caused new bugs or regressions
+- Solutions that worked locally but failed in CI/staging/prod
+- Configurations that conflicted with existing setup
+- Rabbit holes that consumed significant time without progress
+
+## Post-Generation Output
+
+After creating file, output:
+
+```
+✓ Created handoff folder: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
+  - index.md (entry point with navigation)
+  - completed-work.md, dead-ends.md, decisions.md, pending.md, context.md
+  - 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.
+  Read dead-ends.md first to avoid repeating failed approaches.
+
+⚠️  {N} dead ends documented — avoid re-attempting these approaches
+```
+
+If plan was updated:
+```
+✓ Updated plan document: {path}
+   - {N} items marked complete
+   - {N} items partially complete
+   - {N} new items added
+```
+
+## Success Criteria
+
+- [ ] Handoff folder created at `handoffs/{YYYY-MM-DD-HHMM}/`
+- [ ] index.md contains summary and navigation table
+- [ ] All section files created (completed-work.md, dead-ends.md, etc.)
+- [ ] Dead ends use structured table format for quick scanning
+- [ ] plan.md copied from context if plan exists
+- [ ] Next steps are actionable with file references
+- [ ] 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

package/dist/templates/_shared/hooks-ts/_utils/git-state.ts

@@ -1,2 +1,2 @@
-// Re-export from shared library — canonical location is lib-ts/base/git-state.ts
-export { getGitState } from "../../lib-ts/base/git-state.js";
+// Re-export from shared library — canonical location is lib-ts/base/git-state.ts
+export { getGitState } from "../../lib-ts/base/git-state.js";