all-hands-cli 0.1.0

package/docs/harness/hooks/validation-hooks.md

@@ -0,0 +1,97 @@
+---
+description: "Hooks for schema validation of frontmatter, language-specific diagnostics (pyright, ruff, tsc), and code formatting enforcement on file writes."
+---
+
+# Validation Hooks
+
+Validation hooks enforce structural correctness at write time. They intercept file creation and editing to run schema checks, type diagnostics, and formatting rules, surfacing errors to agents before bad content reaches the repository.
+
+## Diagnostics Pipeline
+
+[ref:.allhands/harness/src/hooks/validation.ts:runDiagnostics:0e448c6] is the orchestrator. It dispatches to language-specific diagnostic runners based on file extension:
+
+| Language | Runner | Tool | File Extensions |
+|----------|--------|------|----------------|
+| Python | [ref:.allhands/harness/src/hooks/validation.ts:runPyrightDiagnostics:0e448c6] | pyright | `.py` |
+| Python | [ref:.allhands/harness/src/hooks/validation.ts:runRuffDiagnostics:0e448c6] | ruff | `.py` |
+| TypeScript | [ref:.allhands/harness/src/hooks/validation.ts:runTscDiagnostics:0e448c6] | tsc | `.ts`, `.tsx` |
+
+Each runner:
+1. Checks tool availability via [ref:.allhands/harness/src/hooks/validation.ts:isToolAvailable:0e448c6]
+2. Executes the tool against the target file
+3. Returns a `DiagnosticResult` with severity, message, and location
+
+For TypeScript, [ref:.allhands/harness/src/hooks/validation.ts:findTsConfig:0e448c6] walks up the directory tree to locate the nearest `tsconfig.json`, ensuring diagnostics respect project-level compiler settings.
+
+[ref:.allhands/harness/src/hooks/validation.ts:formatDiagnosticsContext:0e448c6] transforms diagnostic results into agent-readable markdown, grouping by severity and providing file:line references agents can act on.
+
+## Schema Validation
+
+Schema validation targets frontmatter in markdown files used by the harness (prompts, specs, alignment docs, flow files).
+
+### Delegation Architecture
+
+Schema parsing and validation logic lives in [ref:.allhands/harness/src/lib/schema.ts::c65e65d]. The hooks layer (`validation.ts`) delegates all core operations there:
+
+- **Frontmatter extraction** -- [ref:.allhands/harness/src/lib/schema.ts:extractFrontmatter:c65e65d] (imported into hooks)
+- **Schema loading** -- [ref:.allhands/harness/src/lib/schema.ts:loadSchema:c65e65d] (imported as `loadSchemaFromLib`)
+- **Frontmatter validation** -- [ref:.allhands/harness/src/lib/schema.ts:validateFrontmatter:c65e65d] (imported as `validateFrontmatterFromLib`)
+
+This consolidation eliminated 4 behavioral divergences that existed when hooks had their own implementations:
+
+1. Frontmatter parsing regex required a trailing newline after the closing `---` in hooks but not in lib
+2. Hooks were missing `boolean`, `date`, and `object` type validation branches
+3. Return type shape differences between hooks and lib validation results
+4. Schema field fallback behavior (`schema.fields` vs `schema.frontmatter`) was inconsistent
+
+```mermaid
+flowchart TD
+    A[File written] --> B{detectSchemaTypeLocal}
+    B -->|prompt| C[lib/schema.ts: loadSchema]
+    B -->|spec| C
+    B -->|flow| C
+    B -->|unknown| F[Skip validation]
+    C --> G[lib/schema.ts: extractFrontmatter]
+    G --> H{Valid YAML?}
+    H -->|No| I[Report parse error]
+    H -->|Yes| J[lib/schema.ts: validateFrontmatter]
+    J --> K{Skill file?}
+    K -->|Yes| L[validateSkillSpecificRules]
+    K -->|No| M[formatSchemaErrors]
+    L --> M
+    M --> N[Return to agent]
+```
+
+### Key Functions
+
+- [ref:.allhands/harness/src/hooks/validation.ts:detectSchemaTypeLocal:0e448c6] -- Thin wrapper over [ref:.allhands/harness/src/lib/schema.ts:detectSchemaType:c65e65d], determines which schema applies based on file path patterns
+- [ref:.allhands/harness/src/hooks/validation.ts:validateSkillSpecificRules:0e448c6] -- Additional validation for skill folders via [ref:.allhands/harness/src/hooks/validation.ts:extractSkillFolderName:0e448c6] (skill name must match containing folder)
+- [ref:.allhands/harness/src/hooks/validation.ts:runSchemaValidation:0e448c6] -- Full pipeline: detect type, delegate to lib for schema load/parse/validate, then apply skill-specific rules
+- [ref:.allhands/harness/src/hooks/validation.ts:runSchemaValidationOnContent:0e448c6] -- Same pipeline but accepts content string instead of reading from disk (used for PreToolUse interception before the file is written)
+- [ref:.allhands/harness/src/hooks/validation.ts:formatSchemaErrors:0e448c6] -- Formats validation errors with the schema type for agent display
+
+### Pre vs Post Validation
+
+Two hook entry points handle the timing difference:
+
+- [ref:.allhands/harness/src/hooks/validation.ts:validateSchemaPre:0e448c6] -- **PreToolUse**: Validates content _before_ it reaches disk. Uses `runSchemaValidationOnContent` on the proposed file content from `tool_input`. Blocks the write if schema violations are found.
+- [ref:.allhands/harness/src/hooks/validation.ts:validateSchema:0e448c6] -- **PostToolUse**: Validates the file _after_ it has been written. Uses `runSchemaValidation` on the persisted file. Reports errors as context for the agent to fix.
+
+The pre-validation path is stricter -- it can prevent invalid content from being committed. Post-validation is a safety net that catches issues from tools that bypass pre-hooks.
+
+## Formatting Enforcement
+
+[ref:.allhands/harness/src/hooks/validation.ts:runFormat:0e448c6] enforces code formatting after file writes. It reads format configuration from project settings via [ref:.allhands/harness/src/hooks/shared.ts:loadProjectSettings:ca0caaf] and dispatches to the appropriate formatter.
+
+[ref:.allhands/harness/src/hooks/validation.ts:getFormatCommand:0e448c6] maps file extensions to format commands from the project's `FormatConfig`. If a formatter is configured for the file type, it runs the command and reports any changes made.
+
+## Design Decision: Deny vs Context
+
+Schema validation uses [ref:.allhands/harness/src/hooks/shared.ts:denyTool:ca0caaf] for pre-write validation (prevents the tool call) and [ref:.allhands/harness/src/hooks/shared.ts:outputContext:ca0caaf] for post-write diagnostics (informs the agent). This distinction matters: pre-write denial is cheap (no disk I/O wasted), while post-write context lets the agent decide how to remediate.
+
+## Test Coverage
+
+Two e2e test suites verify schema validation behavior:
+
+- [ref:.allhands/harness/src/__tests__/e2e/validation-hooks.test.ts::363c496] -- **28 tests** covering PreToolUse (Write/Edit interception), PostToolUse (file-on-disk validation), and the contract suite verifying hook registration and schema discovery.
+- [ref:.allhands/harness/src/__tests__/e2e/validation-path-consistency.test.ts::d19007e] -- **17 tests** documenting the 4 behavioral divergences that existed before delegation consolidation. These tests pin the now-unified behavior: trailing newline handling, boolean/date/object type validation, return type shapes, and schema field fallback paths. Both the lib path and hooks path are exercised to confirm they produce identical results.

package/docs/harness/test-harness.md

@@ -0,0 +1,149 @@
+---
+description: "E2E test infrastructure providing fixture creation with realistic planning directories, a CLI runner that spawns the harness as a child process, a hook runner for testing hook contracts with typed inputs/outputs, and assertion libraries for CLI results, hook decisions, files, and git state."
+---
+
+# Test Harness
+
+The test harness enables headless end-to-end testing of the `ah` CLI and its hook system. It creates isolated test environments, executes commands against them, and provides domain-specific assertions that understand hook protocols and harness conventions.
+
+## Four Layers
+
+```mermaid
+graph TB
+    T[Test File] --> A[Assertions]
+    T --> H[Hook Runner]
+    T --> C[CLI Runner]
+    T --> F[Fixtures]
+    H --> C
+    C --> F
+    A --> H
+    A --> C
+    A --> F
+```
+
+Each layer builds on the ones below. Tests compose fixtures, runners, and assertions to verify end-to-end behavior.
+
+## Fixtures
+
+Fixtures create temporary directories that replicate the harness's expected file structure.
+
+[ref:.allhands/harness/src/__tests__/harness/fixture.ts:createFixture:507b666] is the base factory. It:
+- Creates a temp directory with a random suffix
+- Initializes a git repository
+- Copies the real `.allhands/harness` directory from the project (via [ref:.allhands/harness/src/__tests__/harness/fixture.ts:getRealHarnessDir:507b666]) so hooks and CLI resolve correctly
+- Accepts `FixtureOptions` to customize initial files, planning structure, and project settings
+- Returns a `TestFixture` with `dir` (path), `cleanup()` (removes temp dir), and helper methods
+
+[ref:.allhands/harness/src/__tests__/harness/fixture.ts:createSpecFixture:507b666] creates a fixture pre-populated with a spec and N prompt files (default 3), simulating a project mid-planning. Prompts use the `PROMPT_TEMPLATE` with proper frontmatter.
+
+[ref:.allhands/harness/src/__tests__/harness/fixture.ts:createMultiSpecFixture:507b666] creates a fixture with multiple specs, useful for testing spec switching and cross-spec operations.
+
+### Fixture Pooling
+
+[ref:.allhands/harness/src/__tests__/harness/fixture.ts:getPooledFixture:507b666] caches fixtures by name, reusing them across tests in a suite. [ref:.allhands/harness/src/__tests__/harness/fixture.ts:cleanupPool:507b666] tears down all pooled fixtures, typically called in `afterAll`. This avoids recreating expensive fixtures (git init, file copy) for every test.
+
+### Built-in Templates
+
+The fixture module exports templates for common file types:
+- `PROMPT_TEMPLATE` -- Markdown prompt with valid frontmatter
+- `ALIGNMENT_TEMPLATE` -- Alignment document structure
+- `SPEC_TEMPLATE` -- Spec file with required fields
+- `PYTHON_SAMPLE` / `TYPESCRIPT_SAMPLE` -- Source files for diagnostics testing
+
+## CLI Runner
+
+[ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runCli:432baa6] spawns the `ah` CLI as a child process using `tsx` for TypeScript execution. It captures stdout, stderr, and exit code into a `RunResult`. Supports timeout, stdin piping, environment overrides, and JSON output parsing.
+
+[ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runInFixture:432baa6] wraps `runCli` with a fixture's directory as `cwd`, the most common test pattern.
+
+### Specialized Runners
+
+| Runner | Purpose |
+|--------|---------|
+| [ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runKnowledgeSearch:432baa6] | Executes `ah knowledge search` with query, optional path and k |
+| [ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runValidate:432baa6] | Executes `ah validate` against a file path |
+| [ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runCodeSearch:432baa6] | Executes code search with optional budget |
+| [ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runToolsList:432baa6] | Lists available tools |
+| [ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runSpecsList:432baa6] | Lists available specs |
+
+[ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:runBatch:432baa6] executes multiple commands sequentially against the same fixture, returning results in order. Useful for testing multi-step workflows.
+
+[ref:.allhands/harness/src/__tests__/harness/cli-runner.ts:debugResult:432baa6] prints a formatted summary of a `RunResult` for test debugging.
+
+## Hook Runner
+
+[ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runHook:c357c05] executes a hook by building the correct CLI subcommand, piping `HookInput` as stdin JSON, and parsing the output as a `HookResult` with typed fields for `decision`, `reason`, `context`, and `output`.
+
+### Specialized Hook Runners
+
+| Runner | Hook | Input |
+|--------|------|-------|
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runContextHook:c357c05] | Any context hook | `PreToolUseInput` |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runEditInject:c357c05] | `edit-inject` | File path |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runReadEnforcer:c357c05] | `read-enforcer` | File path + optional offset/limit |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runSearchRouter:c357c05] | `search-router` | Search pattern |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runTldrInject:c357c05] | `tldr-inject` | Prompt text |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runValidationHook:c357c05] | Any validation hook | `PreToolUseInput` or `PostToolUseInput` |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runSchemaCheck:c357c05] | Schema validation | File path + content |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runLifecycleHook:c357c05] | Any lifecycle hook | `HookInput` |
+| [ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:runStopHook:c357c05] | Stop hook | Session ID |
+
+### Contract Testing
+
+[ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:testHookContract:c357c05] verifies that a hook adheres to a declared contract -- a `HookContract` specifying the hook name, input, and expected output properties (decision, required context strings, timing bounds). Returns a `ContractResult` with pass/fail and specific failure messages.
+
+[ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:testHookContracts:c357c05] runs an array of contracts in sequence, collecting all results. Combined with [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertContractsPassed:51c46b6], this enables declarative hook testing:
+
+```
+Define contract -> Run contract -> Assert all passed
+```
+
+[ref:.allhands/harness/src/__tests__/harness/hook-runner.ts:debugHookResult:c357c05] prints a formatted hook result for debugging failures.
+
+## Assertions
+
+The assertion library uses vitest's `expect` under the hood, adding domain-specific checks.
+
+### CLI Assertions
+
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertSuccess:51c46b6] -- Exit code 0
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertFailure:51c46b6] -- Non-zero exit code
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertStdoutContains:51c46b6] / [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertStderrContains:51c46b6] -- Substring match in output
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertStdoutMatches:51c46b6] -- Regex match in stdout
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertJsonOutput:51c46b6] -- Parse stdout as JSON and run a validator function
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertTimedWithin:51c46b6] -- Execution completed within a time budget
+
+### Hook Assertions
+
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertHookAllowed:51c46b6] -- Hook returned allow decision
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertHookDenied:51c46b6] -- Hook returned deny decision
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertHookBlocked:51c46b6] -- Hook returned block decision
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertHookInjectedContext:51c46b6] -- Hook output contains `additionalContext`
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertHookContextContains:51c46b6] -- Injected context contains a specific substring
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertDenialReasonContains:51c46b6] -- Denial reason contains expected text
+
+### Fixture Assertions
+
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertFileExists:51c46b6] / [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertFileNotExists:51c46b6] -- File presence in fixture
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertFileContains:51c46b6] / [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertFileMatches:51c46b6] -- File content checks
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertValidFrontmatter:51c46b6] -- Parses YAML frontmatter and checks required fields
+
+### Git Assertions
+
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertGitTracked:51c46b6] -- File is tracked by git
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertGitDirty:51c46b6] -- File has uncommitted changes
+
+### Composite Assertions
+
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertWorkflowSuccess:51c46b6] -- All results in a named sequence succeeded
+- [ref:.allhands/harness/src/__tests__/harness/assertions.ts:assertContractsPassed:51c46b6] -- All hook contracts passed
+
+## Barrel Export
+
+[ref:.allhands/harness/src/__tests__/harness/index.ts::c1cd207] re-exports everything from all four layers. Tests import from this single entry point:
+
+```
+import { createFixture, runInFixture, runHook, assertSuccess } from '../harness/index.js';
+```
+
+This keeps test files clean and decoupled from internal module structure.

package/docs/harness/tui.md

@@ -0,0 +1,176 @@
+---
+description: "Terminal UI built on blessed providing a three-pane layout for agent orchestration: actions pane with new initiative spec type selection, prompts pane for tracking prompt status, status pane for monitoring active agents, and two toggles (Loop, Parallel) for controlling the unified event loop."
+---
+
+# Terminal User Interface (TUI)
+
+The TUI is the primary operator interface for the harness. It renders a three-pane terminal layout using the blessed library, integrates with the event loop for real-time state updates, and manages agent lifecycles through tmux window orchestration.
+
+## Layout Architecture
+
+```
++-------------------+-------------------+-------------------+
+|     HEADER        |  ALL HANDS        |  AGENTIC HARNESS  |
++-------------------+-------------------+-------------------+
+|                   |                   |                    |
+|   Actions Pane    |   Prompts Pane    |   Status Pane      |
+|                   |                   |                    |
+|  [1] Coordinator  |  * 01: Task A     |  Spec: api-v2      |
+|  [2] New Initiative  > 02: Task B     |  Branch: feat/api   |
+|  [3] Planner      |  - 03: Task C     |                    |
+|  [4] Review Jury  |                   |  Agents:           |
+|  [5] E2E Test Plan|                   |  executor-01 [run]  |
+|  [6] PR Action    |                   |  planner [run]      |
+|  ...              |                   |                    |
+|  -- Toggles --    |                   |  Activity Log:     |
+|  [O] Loop         |                   |  [12:30] Index ok  |
+|  [P] Parallel     |                   |  [12:31] Spawned   |
+|                   |                   |                    |
++-------------------+-------------------+-------------------+
+```
+
+### Pane Components
+
+**Actions Pane** -- [ref:.allhands/harness/src/tui/actions.ts:createActionsPane:17c53c1]
+Renders agent spawn buttons, toggle switches, and control actions. All actions are always visible -- agents exit early if preconditions are not met. [ref:.allhands/harness/src/tui/actions.ts:buildActionItems:17c53c1] constructs the full item list; [ref:.allhands/harness/src/tui/actions.ts:getSelectableItems:17c53c1] filters to navigable items.
+
+The complete action list:
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| 1 | Coordinator | Spawn coordinator agent |
+| 2 | New Initiative | Spec type selection modal, routes to ideation |
+| 3 | Planner | Spawn planner agent |
+| 4 | Review Jury | Spawn review jury |
+| 5 | E2E Test Plan | Spawn E2E test planner |
+| 6 | PR Action | Create PR / Rerun PR Review (state-dependent label) |
+| 7 | Address PR Review | Spawn PR review agent |
+| 8 | Compound | Spawn compound operation |
+| 9 | Complete | Mark spec as completed |
+| 0 | Switch Workspace | Open spec selection modal |
+| - | Custom Flow | Open flow selection modal |
+
+Two toggles follow the action list:
+
+| Key | Toggle | Description |
+|-----|--------|-------------|
+| O | Loop | Enable/disable the prompt execution loop |
+| P | Parallel | Enable/disable multi-executor parallel mode |
+
+**Prompts Pane** -- [ref:.allhands/harness/src/tui/prompts-pane.ts:createPromptsPane:822e9a7]
+Displays all prompts sorted by status: in_progress first, then pending, then done. Each prompt shows its number, title, and status icon via [ref:.allhands/harness/src/tui/prompts-pane.ts:getStatusIcon:822e9a7]. Selecting a prompt opens the file viewer.
+
+**Status Pane** -- [ref:.allhands/harness/src/tui/status-pane.ts:createStatusPane:ada300c]
+Shows the current spec, branch, base branch, active agents, and a scrolling activity log. [ref:.allhands/harness/src/tui/status-pane.ts:getSelectableItems:ada300c] builds a navigable list of spec, alignment doc, E2E test plan, and running agents. [ref:.allhands/harness/src/tui/status-pane.ts:formatAgentStatus:ada300c] renders each agent's running state.
+
+## Navigation
+
+The TUI uses vim-style keyboard navigation defined in the [ref:.allhands/harness/src/tui/index.ts:TUI:5e4554b] class:
+
+| Key | Action |
+|-----|--------|
+| Tab / Shift-Tab | Cycle between panes |
+| j / k | Navigate up/down within focused pane |
+| u / d | Page up/down (10 items) |
+| Space / Enter | Select current item |
+| Escape | Close active modal or file viewer |
+| x | Delete selected agent (status pane only) |
+| 1-9, 0, - | Hotkeys for action items |
+| O, P | Toggle Loop, Parallel |
+| Q, R, V, C | Quit, Refresh, View Logs, Clear Logs |
+
+Focused pane borders highlight in bright purple (`#a78bfa`); unfocused panes use muted purple (`#4A34C5`).
+
+## Modals and File Viewer
+
+[ref:.allhands/harness/src/tui/modal.ts:createModal:8c117c4] renders overlay modals with navigable item lists. Used for spec selection, log viewing, flow selection, and spec type selection (New Initiative). Supports optional `onClear` for deselection and `scrollable` mode for long content.
+
+[ref:.allhands/harness/src/tui/file-viewer-modal.ts:createFileViewer:812eabd] opens files in a read-only scrollable overlay. Used for viewing prompts, specs, alignment docs, and E2E test plans. [ref:.allhands/harness/src/tui/file-viewer-modal.ts:getPlanningFilePath:812eabd] resolves planning artifacts by branch and type. [ref:.allhands/harness/src/tui/file-viewer-modal.ts:getSpecFilePath:812eabd] locates spec files by ID.
+
+## State Management
+
+[ref:.allhands/harness/src/tui/index.ts:TUI:5e4554b] maintains a `TUIState` object tracking:
+- **Toggle states**: `loopEnabled`, `parallelEnabled`
+- **Prompt state**: Array of `PromptItem` with number, title, status, path
+- **Agent state**: Array of `AgentInfo` with name, type, running status
+- **Spec/branch context**: Current spec ID, branch name, base branch
+- **PR workflow**: `PRActionState` progresses through `create-pr` -> `awaiting-review` -> `rerun-pr-review`
+- **Custom flow counter**: Tracks custom flow window numbering
+
+State updates flow through `updateState()` which rebuilds action items and triggers re-render.
+
+## New Initiative Action
+
+Selecting **New Initiative** (key `2`) opens a spec type selection modal presenting 6 types:
+
+| Type | Description |
+|------|-------------|
+| milestone | Feature development with deep ideation |
+| investigation | Debug / diagnose issues |
+| optimization | Performance / efficiency work |
+| refactor | Cleanup / tech debt |
+| documentation | Coverage gaps |
+| triage | External signal analysis |
+
+On selection, the TUI dispatches a `new-initiative` action with the chosen `specType`. [ref:.allhands/harness/src/commands/tui.ts:handleAction:4ca2008] routes this through the ideation agent with an optional `flowOverride`:
+
+- **Milestone** gets `null` flow override (uses the ideation agent's default profile flow)
+- **All other types** get a scoping flow path resolved via [ref:.allhands/harness/src/commands/tui.ts:SCOPING_FLOW_MAP:4ca2008]
+
+`SCOPING_FLOW_MAP` is exported as `Record<SpecType, string | null>`:
+
+| SpecType | Flow File |
+|----------|-----------|
+| milestone | `null` (profile default) |
+| investigation | `INVESTIGATION_SCOPING.md` |
+| optimization | `OPTIMIZATION_SCOPING.md` |
+| refactor | `REFACTOR_SCOPING.md` |
+| documentation | `DOCUMENTATION_SCOPING.md` |
+| triage | `TRIAGE_SCOPING.md` |
+
+[ref:.allhands/harness/src/tui/actions.ts:buildActionItems:17c53c1] is exported for testability alongside `SCOPING_FLOW_MAP`.
+
+## Uncommitted Changes Guards
+
+Three actions check for a dirty working tree before proceeding:
+- **create-pr** -- Warns that uncommitted changes will not be included in the PR
+- **rerun-pr-review** -- Warns that uncommitted changes will not be included in the PR
+- **mark-completed** -- Warns that uncommitted changes will not be included in the final push
+
+All three use the shared `confirmProceedWithUncommittedChanges()` helper in [ref:.allhands/harness/src/commands/tui.ts:handleAction:4ca2008], which calls [ref:.allhands/harness/src/lib/git.ts:hasUncommittedChanges:d6d6363] and shows a confirmation modal via `tui.showConfirmation()`. The user can press Enter to proceed or Escape to cancel.
+
+## Event Loop Integration
+
+The TUI constructor starts an [ref:.allhands/harness/src/lib/event-loop.ts:EventLoop:940f18a] instance that monitors external state. Callback bindings connect event loop events to TUI state:
+
+- `onBranchChange` -- Updates branch/spec context and reloads prompts for the new planning directory
+- `onAgentsChange` -- Updates the active agents display
+- `onSpawnExecutor` -- Delegates to TUI options for executor spawning
+- `onSpawnEmergentPlanning` -- Delegates to TUI options for hypothesis planner spawning (no prompt argument)
+- `onPromptsChange` -- Updates prompt list and rebuilds action items
+- `onPRReviewFeedback` -- Transitions PR action state and unlocks Review PR
+- `onLoopStatus` -- Appends status messages to the activity log
+
+## CLI Daemon Integration
+
+When enabled in project settings (default: true), the TUI starts a [ref:.allhands/harness/src/lib/cli-daemon.ts:CLIDaemon:e269aee] for fast hook execution. This eliminates Node.js startup overhead for every hook invocation during active development.
+
+## Launch and Teardown
+
+[ref:.allhands/harness/src/commands/tui.ts:launchTUI:4ca2008] initializes the TUI with the working directory, loads initial state from git branch and planning directory, and starts background indexing (semantic index, call graph, knowledge bases, doc validation).
+
+[ref:.allhands/harness/src/commands/tui.ts:handleAction:4ca2008] dispatches TUI actions to their implementations: spawning agents via [ref:.allhands/harness/src/commands/tui.ts:spawnAgentsForAction:4ca2008], managing PR workflows, switching specs, and running compound operations.
+
+On destroy, the TUI kills all spawned tmux windows (tracked by the session registry), stops the event loop and CLI daemon, clears session state, and restores stdout/stderr interceptors with a 100ms delay to catch deferred terminal output.
+
+## Background Indexing
+
+On startup, the TUI runs a non-blocking indexing pipeline:
+1. Ensures the TLDR daemon is running
+2. Builds or rebuilds the semantic index (branch-aware via [ref:.allhands/harness/src/lib/tldr.ts:needsSemanticRebuild:702ae0d])
+3. Warms the call graph cache
+4. Validates agent profiles via [ref:.allhands/harness/src/lib/opencode/profiles.ts:loadAllProfiles:ef20442]
+5. Indexes knowledge bases (roadmap, docs) with incremental updates from git
+6. Validates documentation references
+
+All indexing errors are caught and logged to the activity pane -- they never crash the TUI.

package/docs/memories.md

@@ -0,0 +1,20 @@
+---
+description: "Lightweight learnings from past sessions, searchable via `ah memories search`. Captures technical patterns, engineer preferences, and harness behavior discoveries."
+---
+
+# Memories
+
+Per **Knowledge Compounding**, this file captures lightweight learnings from past sessions. For detailed technical solutions, see `docs/solutions/`.
+
+| Name | Domain | Source | Description |
+|------|--------|--------|-------------|
+| Motivation-driven suite documentation | validation | user-steering | Engineer reversed detailed CLI command documentation in browser-automation suite after hands-on testing. Commands are discoverable via `--help`; validation suite value is teaching agents HOW TO THINK about using a tool, not replicating command references. |
+| Stochastic terminology preference | planning | user-steering | Engineer chose "stochastic" over "heuristic" for the validation dimension taxonomy. Deterministic/stochastic is an established CS pair. All harness docs must use this terminology consistently. |
+| blockTool output format mismatch (resolved) | harness-tooling | agent-inferred | `blockTool()` in `hooks/shared.ts` outputs `{ decision: 'block', reason }`. Hook-runner now handles both `{ continue: false }` and `{ decision: 'block' }` formats for `assertHookBlocked`. Fixed during compounding. |
+| Dual validation path divergence | harness-tooling | agent-inferred | Before consolidation, [ref:hooks/validation.ts] and [ref:lib/schema.ts] had 4 behavioral divergences: (1) frontmatter regex trailing newline requirement, (2) hooks missing boolean/date/object type branches, (3) return type shape differences, (4) schema.fields fallback behavior. Consolidation in Jury Review resolved all 4 by delegating hooks to lib. |
+| validation-tools path resolution | harness-tooling | agent-inferred | `validation-tools list` resolves file paths relative to source code (`__dirname`), not the working directory. Fixture-based testing cannot simulate empty validation directories — use invariant tests (structure, types) instead. |
+| Array item-type validation gap | harness-tooling | agent-inferred | Schema enforcement for array fields originally only checked `Array.isArray(value)` without validating item types against `items` specification. `tools: [123]` would pass when `items: string`. Fixed in both [ref:hooks/validation.ts] and [ref:lib/schema.ts]. |
+| Pre-existing test failures baseline | validation | agent-inferred | 10 pre-existing test failures persisted throughout the spec: spec `branch` field validation, search-router hook contracts, command timeout. Confirmed identical across all prompts via `git stash` comparison. These are not regressions from this spec. |
+| Emergent testing compounds value | implementation | agent-inferred | 5 emergent prompts (06-10) were all kept, producing 147 new tests for previously untested infrastructure. Prompt 10 divergence documentation directly enabled Jury Review dual-path consolidation. Emergent work chains (06→07→10, 08→09) compound — each builds on discoveries from prior. |
+| TypeScript unit testing suite gap | validation | agent-inferred | No TypeScript unit testing validation suite exists for the harness. Flagged by Prompt 06 for CREATE_VALIDATION_TOOLING follow-up. Tests were written manually without suite guidance. |
+| ENV credential guidance declined | planning | user-steering | Engineer chose not to add secret-sourcing guidance to browser-automation.md ENV Configuration section. ENV docs document variables and their purpose, not how to securely source credentials. |

package/docs/solutions/agentic-issues/premature-agent-deletion-tui-action-dependency-20260130.md

@@ -0,0 +1,49 @@
+---
+description: "Solution for premature agent profile deletion breaking TUI compound action due to undetected tui_action field dependency between co-dependent agent profiles."
+title: "Premature agent profile deletion breaks TUI action that depends on tui_action field"
+date: "2026-01-30"
+milestone: "feature/unified-workflow-orchestration"
+problem_type: agentic_issue
+component: "tui-actions"
+symptoms:
+  - "Compound TUI action spawns only one agent instead of two"
+  - "Agent profile deleted during cleanup but still referenced by tui_action handler"
+  - "Missing agent in multi-agent TUI action"
+root_cause: agentic_miscommunication
+severity: high
+tags:
+  - agent-profile-deletion
+  - tui-action-dependency
+  - compound-action
+  - documentor-agent
+  - workflow-cleanup
+  - cross-file-dependency
+---
+
+## Problem
+
+During workflow cleanup (Prompt 07), the agent deleted [ref:.allhands/agents/documentor.yaml] and [ref:.allhands/flows/DOCUMENTATION.md] as part of consolidating documentation orchestration into the hypothesis planner model. The compound TUI action relies on scanning all agent profiles with `tui_action: compound` to determine which agents to spawn. Both `compounder.yaml` and `documentor.yaml` had this field, so deleting `documentor.yaml` silently reduced the compound action to spawning only the compounder.
+
+## Root Cause
+
+The prompt's cleanup task ("Remove documentor.yaml agent profile and DOCUMENTATION.md flow") was scoped by architectural reasoning (documentation now handled by hypothesis planner) without verifying downstream references to the `tui_action` field. The `typescript-typecheck` validation suite and `ah validate agents` both passed because the deletion was structurally valid — no TypeScript imports referenced the YAML file, and the remaining agent profiles were individually valid.
+
+## Solution
+
+User-patch Prompt 17 restored both files with exact content from `main` branch using `git show main:<path>`.
+
+## Prevention
+
+Before deleting any agent profile:
+1. Check the `tui_action` field value in the profile being deleted
+2. Search for other profiles with the same `tui_action` value — if multiple profiles share a `tui_action`, they are co-dependencies for that TUI action
+3. Verify the TUI action handler logic to understand if it expects multiple agents
+
+## Failed Approaches
+
+- Relying on `npx tsc --noEmit` — YAML files are not part of the TypeScript dependency graph
+- Relying on `ah validate agents` — validates individual profiles, not cross-profile action dependencies
+
+## Related
+
+None yet.

package/docs/solutions/agentic-issues/ref-anchor-scope-mismatch-skill-references-20260131.md

@@ -0,0 +1,55 @@
+---
+title: "[ref:] anchors silently go stale in skill reference docs"
+date: "2026-01-31"
+milestone: refactor/harness-maintenance-skill
+problem_type: agentic_issue
+component: harness-maintenance-skill
+symptoms:
+  - "[ref:] anchors added to skill reference docs with git hashes"
+  - "ah docs validate reports frontmatter errors on skill reference files"
+  - "Git hashes in [ref:] anchors become stale after any source file change"
+  - "ah docs finalize cannot resolve directory-level [ref:] anchors"
+root_cause: wrong_api_usage
+severity: medium
+tags:
+  - ref-anchors
+  - docs-validate
+  - docs-finalize
+  - skill-references
+  - stale-metadata
+  - harness-maintenance
+  - scope-limitation
+  - context-is-precious
+source: agent-inferred
+---
+
+## Problem
+
+During the harness-maintenance skill restructure, an agent added `[ref:]` code reference anchors (with git hashes) to `core-architecture.md` (6 anchors) and `tools-commands-mcp-hooks.md` (10 occurrences). These anchors are designed to be validated by `ah docs validate` and finalized by `ah docs finalize`.
+
+The problem: both `ah docs validate` and `ah docs finalize` are scoped to the `docs/` directory only (hardcoded default in `harness/src/commands/docs.ts`). Skill reference docs live in `.allhands/skills/*/references/`, which is outside the docs tooling scope. The anchors were:
+- Never validated automatically
+- Contained git hashes that would silently go stale on any source file change
+- Created false confidence that references were current
+- Added noise to files loaded every agent session (violating Context is Precious)
+
+## Investigation
+
+1. Agent ran `ah docs validate --path .allhands/skills/harness-maintenance/references/ --json` — it processed the files but reported frontmatter validation errors (skill references don't have standard doc frontmatter)
+2. Agent ran `ah docs finalize` — it resolved 9 file-level anchors to hashed refs but failed on 8 directory-level anchors (directories don't have git blob hashes)
+3. The partial success masked the fundamental issue: even "finalized" anchors would go stale because no automated pipeline re-validates skill reference docs
+
+## Solution
+
+Engineer directed stripping all `[ref:]` anchors and reverting to plain-text backtick paths:
+- 6 anchors stripped from `core-architecture.md`
+- 10 anchors stripped from `tools-commands-mcp-hooks.md`
+- Scope guard added to SKILL.md maintainer checklist: "NEVER run `ah docs validate`/`finalize` on skill references — those commands are scoped to `docs/` only"
+
+Plain backtick paths (`\`.allhands/harness/src/cli.ts\``) are more readable and don't create false freshness guarantees.
+
+## Prevention
+
+- **Scope guard**: The harness-maintenance SKILL.md maintainer checklist now explicitly prohibits running docs-validate/finalize on skill references
+- **Rule of thumb**: Only use `[ref:]` anchors in files under `docs/` where the docs pipeline automatically validates and re-finalizes them
+- **Broader principle**: Never embed metadata that requires external tooling validation in files outside that tooling's scope — the metadata will silently rot

package/docs/solutions/agentic-issues/tautological-tests-routing-20260131.md

@@ -0,0 +1,52 @@
+---
+title: "Agent-generated tautological tests assert constants against themselves"
+date: "2026-01-31"
+milestone: feature/workflow-domain-configuration
+problem_type: agentic_issue
+component: harness-tests
+symptoms:
+  - "Tests pass but exercise no real code paths"
+  - "Assertions compare constructed values against identical constructions"
+  - "Test coverage appears high but is hollow"
+root_cause: agentic_hallucination
+severity: medium
+tags:
+  - tautological-tests
+  - self-asserting
+  - agentic-hallucination
+  - test-quality
+  - hollow-coverage
+  - routing-tests
+  - vitest
+source: review-fix
+---
+
+## Problem
+
+During Prompt 05 (TUI Integration & Execution Gating), the agent generated 3 routing tests in `new-initiative-routing.test.ts` that passed but verified nothing:
+
+1. **Self-asserting path construction**: Built a path with `path.join()` then asserted it equals the same `path.join()` call
+2. **Guaranteed-unique set**: Created a `Set` from a literal array and asserted `set.size === array.length` — tautologically true for any array of distinct literals
+3. **Config-shape-you-just-built**: Constructed a config object then asserted its shape matched the literal used to build it
+
+All 3 tests passed on every run, creating an illusion of coverage.
+
+## Investigation
+
+The 7-member jury review's YAGNI reviewer flagged these as "tautological — they assert constants against themselves, never exercise real code." The agent had followed a pattern of writing tests that structurally resemble valid tests but contain no meaningful assertions.
+
+## Solution
+
+Prompt 12 replaced all 3 tests with assertions that exercise real artifacts:
+
+- **Filesystem existence checks**: For each of the 6 workflow domain configs, assert the file exists at the expected path using `existsSync()`
+- **Runtime output assertion**: Call `buildActionItems()` and assert the output includes `initiative-steering` — exercises real code that constructs action items
+
+The replacement tests use `getFlowsDirectory()` parent for correct path resolution in the vitest execution environment.
+
+## Prevention
+
+- After writing tests, verify each assertion's left-hand and right-hand sides come from **different sources** — one from code under test, one from expected values
+- Assertions where both sides are computed from constants or literals are suspect
+- Prefer assertions against runtime behavior (function calls, filesystem state, API responses) over assertions against values you just constructed
+- Jury review's YAGNI dimension reliably catches this pattern — include it for infrastructure specs