Merge dev → main (automated)

.githooks/pre-push

@@ -1,20 +1,37 @@
 #!/bin/sh
 # worklog:pre-push-hook:v1
-# Auto-sync Worklog data before pushing (committed hooks).
-# Set WORKLOG_SKIP_PRE_PUSH=1 to bypass.
+#
+# Auto-sync Worklog data before pushing.
+#
+# This hook runs `wl sync` before any push to ensure worklog data is
+# committed and pushed to the dedicated refs/worklog/data branch.
+# It uses a temporary worktree to avoid corrupting the project working tree
+# (see WL-0MQRBT8BS00355AB for the bug this prevents).
+#
+# BYPASS: Set WORKLOG_SKIP_PRE_PUSH=1 to skip the sync entirely.
+#   export WORKLOG_SKIP_PRE_PUSH=1
+#   git push origin HEAD:refs/heads/dev
+#
 set -e
+
 if [ "$WORKLOG_SKIP_PRE_PUSH" = "1" ]; then
+  echo "worklog: pre-push sync skipped (WORKLOG_SKIP_PRE_PUSH=1)"
   exit 0
 fi
+
+# Read stdin to check which refs are being pushed.
+# If pushing to refs/worklog/data, skip the sync to avoid infinite loops.
 skip=0
 while read local_ref local_sha remote_ref remote_sha; do
   if [ "$remote_ref" = "refs/worklog/data" ]; then
     skip=1
   fi
 done
+
 if [ "$skip" = "1" ]; then
   exit 0
 fi
+
 if command -v wl >/dev/null 2>&1; then
   WL=wl
 elif command -v worklog >/dev/null 2>&1; then
@@ -23,5 +40,9 @@ else
   echo "worklog: wl/worklog not found; skipping pre-push sync" >&2
   exit 0
 fi
-"$WL" sync
+
+# Force the data branch to refs/worklog/data regardless of config.
+# This prevents the sync from accidentally pushing to a standard branch
+# if the user has overridden syncBranch in their worklog config.
+"$WL" sync --git-branch refs/worklog/data
 exit 0

.github/workflows/install-and-smoke-test.yml

@@ -37,26 +37,26 @@ jobs:
           node ./dist/cli.js list -n 1 --json > /dev/null
           echo "✓ wl CLI works"
 
-          # Verify the TUI module loads without errors
-          node -e "
-            const { ChatPane } = require('./dist/tui/chatPane.js');
-            const { ActionPalette } = require('./dist/tui/actionPalette.js');
-            const { runWl } = require('./dist/tui/wl-integration.js');
+          # Verify the TUI module loads without errors (using tsx for TypeScript imports)
+          npx tsx -e "
+            const { ChatPane } = await import('./packages/tui/extensions/chatPane.js');
+            const { ActionPalette } = await import('./packages/tui/extensions/actionPalette.js');
+            const { runWl } = await import('./packages/tui/extensions/wl-integration.js');
             console.log('✓ TUI modules load successfully');
           "
 
           # Verify chat pane can send messages
-          node -e "
-            const { ChatPane } = require('./dist/tui/chatPane.js');
+          npx tsx -e "
+            const { ChatPane } = await import('./packages/tui/extensions/chatPane.js');
             const pane = new ChatPane();
             pane.clear();
             console.log('✓ ChatPane instantiated');
           "
 
           # Verify action palette has default actions
-          node -e "
-            const { ChatPane } = require('./dist/tui/chatPane.js');
-            const { ActionPalette } = require('./dist/tui/actionPalette.js');
+          npx tsx -e "
+            const { ChatPane } = await import('./packages/tui/extensions/chatPane.js');
+            const { ActionPalette } = await import('./packages/tui/extensions/actionPalette.js');
             const chat = new ChatPane();
             const palette = new ActionPalette(chat);
             palette.open();

.gitignore

@@ -166,3 +166,4 @@ tmp/
 
 # Ignore generated test timings from local test runs
 test-timings.json
+__pycache__/

.pi/settings.json

@@ -0,0 +1,10 @@
+{
+  "llm-wiki": {
+    "notices": false
+  },
+  "context-hub": {
+    "showActivityIndicator": true,
+    "showHelpText": true,
+    "browseItemCount": 15
+  }
+}

.ralph/event.pending

@@ -0,0 +1,8 @@
+{
+  "event_type": "error",
+  "timestamp": "2026-06-14T02:59:45.771260+00:00",
+  "work_item_ids": [
+    "WL-0MQD0YW40007RTKU"
+  ],
+  "title": "Extensible shortcut key system for Pi extension"
+}

CONFIG.md

@@ -62,6 +62,16 @@ The system loads configuration in this order:
 
 If no configuration exists at all, the system defaults to using `WI` as the prefix.
 
+## TUI Auto-Sync Settings
+
+Optional TUI auto-sync settings (edit `.worklog/config.yaml` or configure via `/wl settings`):
+
+- `autoSyncIntervalSeconds`: Number of seconds between automatic background syncs in the Pi TUI browse widget (default: `10`, range: 0–300, 0 = disabled).
+
+  When the TUI browse widget auto-refreshes (every 5 seconds), it checks if the time since the last successful sync exceeds this interval. If so, a background `wl sync` is triggered (fire-and-forget, non-blocking). An in-flight guard prevents concurrent syncs.
+
+  This setting is separate from the `autoSync` boolean config key, which controls automatic sync after database write operations.
+
 ## GitHub Settings
 
 Optional GitHub settings (edit `.worklog/config.yaml` manually):

DATA_FORMAT.md

@@ -72,6 +72,7 @@ Worklog uses a **dual-storage model** to combine the benefits of persistent data
 - **tags**: Array of string tags
 - **assignee**: Person assigned to the work item
 - **stage**: Current stage of the work item in the workflow
+- **childCount** (computed, `wl next --json` only): Number of direct children for this work item. Not stored in JSONL; computed at query time from parent-child relationships. Items with no children return `0`. See [`wl next` JSON output](CLI.md#next-options) for details.
 - **issueType**: Optional interoperability field for imported issue types
 - **createdBy**: Optional interoperability field for imported creator/actor
 - **deletedBy**: Optional interoperability field for imported deleter/actor

IMPLEMENTATION_SUMMARY.md

@@ -27,12 +27,13 @@ All requirements from the problem statement have been successfully implemented:
 - Type-safe enums for status and priority
 - Input types for create and update operations
 
-### Database Layer (`src/database.ts`, `src/persistent-store.ts`)
+### Database Layer (`packages/shared/src/database.ts`, `packages/shared/src/persistent-store.ts`)
 - SQLite-backed persistent storage
 - CRUD operations (Create, Read, Update, Delete)
 - Hierarchical queries (children, descendants)
 - Filtering by status, priority, parent, tags
 - Import/export capabilities with JSONL integration
+- **In-memory query caching** (Phase 5): Configurable TTL-based cache for frequent read operations (`getWorkItem`, `getAllWorkItems`, `getAllComments`, etc.) with automatic invalidation on writes. Benchmarks show **3-168x speedup** depending on the operation.
 
 ### Storage Format (`src/jsonl.ts`)
 - JSONL (JSON Lines) format for Git-friendly sync

README.md

@@ -61,10 +61,10 @@ wl github import
 ### Using the TUI
 
 ```bash
-wl tui                # Interactive tree view of all items
-wl tui --in-progress  # Show only in-progress items
+wl tui                # Launch Pi-based TUI (interactive browse + agent chat)
+wl tui --in-progress  # Launch Pi-based TUI, show only in-progress items
 wl tui --perf         # Enable performance instrumentation and write diagnostics artifacts under .worklog/
-TUI_PROFILE=1 wl tui  # Enable profiling via environment variable
+wl tui --perf         # Launch Pi-based TUI with performance instrumentation
 ```
 
 Press `O` in the TUI to access the Pi agent chat pane. The Pi-based TUI provides natural language chat, an action palette with agent-driven flows, and all work item operations through the `wl` CLI. See [TUI.md](TUI.md) for controls, including quick stage filters (`Alt+T` for `intake_complete`, `Alt+P` for `plan_complete`) that exclude closed items.
@@ -120,6 +120,7 @@ You can get a lot of value from using Worklog as a memory for your agents. But y
 | [LOCAL_LLM.md](LOCAL_LLM.md) | Configure local LLM providers (Ollama, Foundry) |
 | [MULTI_PROJECT_GUIDE.md](MULTI_PROJECT_GUIDE.md) | Multi-project setup with custom prefixes |
 | [API.md](API.md) | REST API endpoints and usage |
+| [docs/FILE_PATH_CONVENTION.md](docs/FILE_PATH_CONVENTION.md) | File path convention for work item descriptions |
 
 ### Reference
 
@@ -142,6 +143,7 @@ You can get a lot of value from using Worklog as a memory for your agents. But y
 | [docs/migrations.md](docs/migrations.md) | Database migration system |
 | [docs/prd/sort_order_PRD.md](docs/prd/sort_order_PRD.md) | Sort order product requirements |
 | [docs/validation/status-stage-inventory.md](docs/validation/status-stage-inventory.md) | Status/stage validation rules |
+| [docs/SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) | Skill authoring guide with script best practices |
 
 ## Tutorials
 
@@ -157,6 +159,34 @@ Step-by-step guides for learning Worklog:
 
 See [docs/tutorials/README.md](docs/tutorials/README.md) for the full tutorial index.
 
+## Shell Completion
+
+Worklog ships with shell completion scripts for **bash** and **zsh**. The `wl completion` command generates a completion script that provides tab-completion for all subcommands, options, and dynamic work-item IDs.
+
+### Bash
+
+```bash
+# Source directly (current shell only)
+source <(wl completion bash)
+
+# Permanent installation
+wl completion bash > ~/.wl-completion.bash
+echo "source ~/.wl-completion.bash" >> ~/.bashrc
+```
+
+### Zsh
+
+```zsh
+# Source directly (current shell only)
+source <(wl completion zsh)
+
+# Permanent installation
+wl completion zsh > ~/.wl-completion.zsh
+echo "source ~/.wl-completion.zsh" >> ~/.zshrc
+```
+
+> **Note:** Dynamic work-item ID completion (e.g., `wl show <TAB>`) calls `wl list --json` in the background to fetch open work items. This may add a slight delay on first tab press in large repositories.
+
 ## Development
 
 ```bash
@@ -168,8 +198,24 @@ npm run test:coverage # Tests with coverage report
 npm run test:tui      # TUI tests only (CI/headless)
 ```
 
+### Vitest Configuration
+
+The project uses [Vitest](https://vitest.dev/) with the following settings in `vitest.config.ts`:
+
+- **Pool:** `'forks'` (child processes) — supports tests that use `process.chdir()` for temp directory setup
+- **maxWorkers:** `4` — limits concurrent worker count to prevent unbounded memory growth during test execution
+- **Exclusions:** Worktree directories (`.worklog/worktrees/**`) are excluded to prevent duplicate test file discovery
+
 See [tests/README.md](tests/README.md) for detailed testing documentation.
 
+### Test Mock Patterns
+
+The `tests/extensions/worklog-browse-extension.test.ts` file (1700+ lines, 68 tests) demonstrates key mock patterns used by this project:
+
+- **Comprehensive `node:fs` mock:** Rather than stubbing only the 4 fs functions used directly by the code under test, the mock covers ~12 functions (`existsSync`, `statSync`, `lstatSync`, `readdirSync`, `accessSync`, `watch`, `promises`, `constants`, `readFileSync`, `writeFileSync`, `mkdirSync`, `realpathSync`) that may be called during module initialization. This prevents cascading errors and heap OOM during import.
+- **`icons.js` mock:** The dynamic `require('dist/icons.js')` in the browse module is mocked with stub implementations for all 8 exported functions (`priorityIcon`, `statusIcon`, `stageIcon`, `auditIcon`, `epicIcon`, `iconsEnabled`, `riskIcon`, `effortIcon`), preventing uncontrolled file resolution during import.
+- **Infinite loop guard:** `custom()` mocks return `{ type: 'shortcut', command: '/test-exit' }` instead of `null` to break the `runBrowseFlow` while(true) loop, preventing infinite-loop-based OOM in test mocks.
+
 ## License
 
 MIT