all-hands-cli 0.1.0

package/docs/harness/cli/cli-entry-and-command-discovery.md

@@ -0,0 +1,91 @@
+---
+description: "CLI entry point architecture: how the `ah` binary boots, auto-discovers command modules, and provides base-command utilities for tracing, context, and output formatting."
+---
+
+# CLI Entry and Command Discovery
+
+## Why This Architecture Exists
+
+The harness CLI (`ah`) serves as the single entry surface for both human operators and agent processes. Two constraints shaped its design:
+
+1. **Commands must be independently deployable** -- adding a new capability should require only dropping a file into the commands directory, with zero registration boilerplate.
+2. **Every invocation must be observable** -- agents operate autonomously, so every command execution needs trace logging for post-hoc debugging.
+
+These constraints produced a three-layer stack: a thin entry point, a filesystem-based command registry, and a shared base-command layer that handles cross-cutting concerns.
+
+## Boot Sequence
+
+```mermaid
+sequenceDiagram
+    participant User as ah CLI
+    participant Main as main()
+    participant Discover as discoverAndRegister()
+    participant Modules as Command Modules
+    participant Commander as Commander.js
+
+    User->>Main: process invocation
+    Main->>Commander: create program with name, version, default action
+    Main->>Discover: pass program instance
+    Discover->>Discover: readdirSync(commands/)
+    loop each .ts file (skip index.ts)
+        Discover->>Modules: dynamic import(./module.js)
+        Modules->>Commander: module.register(program)
+    end
+    Main->>Commander: parseAsync()
+    Commander->>User: execute matched command or launch TUI
+```
+
+When no subcommand is provided, [ref:.allhands/harness/src/cli.ts:main:dc6aae1] falls through to the default action, which launches the TUI via `launchTUI`. This makes the bare `ah` command an interactive experience while subcommands remain agent-scriptable.
+
+## Command Auto-Discovery
+
+[ref:.allhands/harness/src/commands/index.ts:discoverAndRegister:33f0cd2] implements convention-over-configuration discovery:
+
+| Rule | Behavior |
+|------|----------|
+| File ends with `.ts` | Candidate for import |
+| File is `index.ts` | Skipped (it *is* the registry) |
+| File is a directory | Skipped (single-file modules only) |
+| Module exports `register(program)` | Registered as a command |
+| Module fails to load | Warning logged, other commands unaffected |
+
+The `CommandModule` interface enforces a single contract: export a `register` function that receives a Commander `Command` instance. This means adding a new CLI command is a single-file operation with no central manifest to update.
+
+**Key decision**: Error isolation. A broken command module logs a warning but does not prevent the rest of the CLI from functioning. This is critical for agent reliability -- a partial harness is better than no harness.
+
+## Base Command Utilities
+
+[ref:.allhands/harness/src/lib/base-command.ts::b6b76d4] provides the cross-cutting layer that every command can opt into.
+
+### Environment Context
+
+[ref:.allhands/harness/src/lib/base-command.ts:getEnvContext:b6b76d4] reads agent identity from environment variables (`AGENT_TYPE`, `PROMPT_NUMBER`, `SPEC_NAME`). These are set by the tmux window spawner when agents are launched, providing automatic trace attribution without commands needing to accept explicit agent flags.
+
+### Context Resolution
+
+[ref:.allhands/harness/src/lib/base-command.ts:parseContext:b6b76d4] merges CLI options with environment context. The precedence order:
+
+1. Explicit `--agent` flag (highest)
+2. `AGENT_TYPE` environment variable
+3. Undefined (no agent context)
+
+This allows both human operators (who pass flags) and automated agents (who inherit env vars) to use the same commands.
+
+### Output Formatting
+
+[ref:.allhands/harness/src/lib/base-command.ts:formatOutput:b6b76d4] switches between JSON (for agent consumption) and human-readable text based on the `--json` flag. Every command that uses `executeCommand` gets this for free.
+
+### Traced Execution
+
+Two patterns exist for adding trace logging:
+
+| Pattern | Use Case |
+|---------|----------|
+| [ref:.allhands/harness/src/lib/base-command.ts:executeCommand:b6b76d4] | Commands that return `CommandResult` objects |
+| [ref:.allhands/harness/src/lib/base-command.ts:tracedAction:b6b76d4] | Lightweight wrapper for commands that handle their own output |
+
+Both patterns log start, success, and error events to the trace store. `tracedAction` is the more common pattern -- it wraps a Commander action handler and extracts arguments for logging automatically, filtering out the Commander object that Commander.js appends as the last argument.
+
+### Common Options
+
+[ref:.allhands/harness/src/lib/base-command.ts:addCommonOptions:b6b76d4] attaches `--agent`, `--json`, and `--verbose` flags to any command. These are the harness-standard options that enable agent-mode operation and observability.

package/docs/harness/cli/docs-command.md

@@ -0,0 +1,87 @@
+---
+description: "Documentation integrity system that validates file references and symbol lookups via ctags, detects stale hashes, and finalizes placeholder refs into versioned references with git blob hashes (content-addressable, stable across merges and rebases)."
+---
+
+## Intent
+
+Documentation in this codebase uses file-reference markers (with file path, symbol name, and git hash components) instead of code snippets. This solves the staleness problem -- when code changes, refs become stale rather than silently incorrect. The docs command provides the validation and finalization pipeline that makes this reference system work.
+
+The core trade-off: **references add maintenance overhead but eliminate silent drift**. A stale ref is a known problem; a stale code snippet is an unknown one.
+
+## Reference Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Placeholder: Writer creates ref marker
+    Placeholder --> Finalized: ah docs finalize
+    Finalized --> Valid: Hash matches current file
+    Valid --> Stale: Source file modified
+    Stale --> Finalized: ah docs finalize (re-run)
+    Finalized --> Invalid: Symbol removed or file deleted
+    Invalid --> [*]: Manual fix required
+```
+
+Writers create placeholder refs during authoring (file path and symbol name, without a hash). The finalize command resolves these into versioned refs by appending the git blob hash of the referenced file. Blob hashes are content-addressable, meaning they depend only on file content -- not commit history. This makes staleness detection resilient to merges, rebases, squash merges, and cherry-picks. Validation then checks that hashes still match and symbols still exist.
+
+## Validation Pipeline
+
+[ref:.allhands/harness/src/commands/docs.ts:validate:3912018] orchestrates the full validation pass:
+
+1. Check ctags availability ([ref:.allhands/harness/src/lib/ctags.ts:checkCtagsAvailable:45c4520])
+2. Generate a ctags index for the project ([ref:.allhands/harness/src/lib/ctags.ts:generateCtagsIndex:45c4520])
+3. Find all markdown files in the docs path ([ref:.allhands/harness/src/lib/docs-validation.ts:findMarkdownFiles:8f3104d])
+4. For each file, run [ref:.allhands/harness/src/lib/docs-validation.ts:validateDocs:8f3104d] which:
+   - Validates frontmatter (requires `description` field) via [ref:.allhands/harness/src/lib/docs-validation.ts:validateFrontMatter:8f3104d]
+   - Extracts all ref patterns via [ref:.allhands/harness/src/lib/docs-validation.ts:extractRefs:8f3104d]
+   - Validates each ref via [ref:.allhands/harness/src/lib/docs-validation.ts:validateRef:8f3104d]
+   - Detects placeholder hashes via [ref:.allhands/harness/src/lib/docs-validation.ts:detectPlaceholders:8f3104d]
+   - Detects unfinalized refs via [ref:.allhands/harness/src/lib/docs-validation.ts:detectUnfinalizedRefs:8f3104d]
+
+### Ref Validation Logic
+
+[ref:.allhands/harness/src/lib/docs-validation.ts:validateRef:8f3104d] classifies each reference into three states:
+
+| State | Condition | Meaning |
+|-------|-----------|---------|
+| **valid** | File exists, hash matches, symbol found (if code file) | Reference is current |
+| **stale** | File exists but hash differs from ref | Source has been modified since ref was created |
+| **invalid** | File missing, git hash lookup failed, or symbol not found | Reference is broken |
+
+For non-code files (markdown, YAML, JSON), the symbol portion is treated as a label -- only the file hash is verified. For code files, [ref:.allhands/harness/src/lib/ctags.ts:lookupSymbol:45c4520] checks that the symbol exists in the ctags index.
+
+## Finalization
+
+[ref:.allhands/harness/src/commands/docs.ts:finalize:3912018] converts placeholder refs into finalized refs:
+
+1. Scan all markdown files for ref patterns without existing hash
+2. Batch-collect all referenced files and compute their blob hashes via [ref:.allhands/harness/src/lib/docs-validation.ts:batchGetBlobHashes:8f3104d]
+3. For each placeholder in [ref:.allhands/harness/src/commands/docs.ts:finalizeSingleFile:3912018]:
+   - Verify the file exists
+   - Look up the blob hash
+   - For code files with symbols, verify the symbol exists via [ref:.allhands/harness/src/lib/ctags.ts:findSymbolInFile:45c4520]
+   - Append the resolved blob hash to each placeholder ref
+4. Write modified content back to disk
+
+Supports both single-file and directory (batch) operation. Certain paths are excluded from processing (e.g., `docs/memories.md`, `docs/solutions`).
+
+### Refresh Mode
+
+When `--refresh` is passed, `ah docs finalize --refresh` operates on ALL finalized refs (not just placeholders). For each existing `[ref:file:symbol:hash]` marker, it recomputes the current blob hash and replaces the stored hash in-place. This is useful after switching from commit-based hashes to blob-based hashes, or after any operation that may have caused hash drift without changing file content (e.g., merges, rebases).
+
+Counts reported: updated (hash changed), unchanged (hash already correct), errored (file missing or hash lookup failed).
+
+## Ctags Integration
+
+The ctags layer ([ref:.allhands/harness/src/lib/ctags.ts::45c4520]) provides symbol lookup without requiring language-specific AST parsers:
+
+- [ref:.allhands/harness/src/lib/ctags.ts:generateCtagsIndex:45c4520] runs Universal Ctags to build an index mapping files to their symbols
+- [ref:.allhands/harness/src/lib/ctags.ts:lookupSymbol:45c4520] finds symbols by name within a specific file
+- [ref:.allhands/harness/src/lib/ctags.ts:findSymbolInFile:45c4520] is the single-file variant used during finalization
+- [ref:.allhands/harness/src/lib/ctags.ts:searchSymbol:45c4520] searches across all files for a symbol name
+- [ref:.allhands/harness/src/lib/ctags.ts:getFileSymbols:45c4520] returns all symbols in a file (used by the complexity command)
+
+This design choice (ctags over AST parsing) trades precision for breadth -- ctags supports TypeScript, Python, Go, Rust, Java, and Ruby with a single tool.
+
+## Doc Tree Coverage
+
+[ref:.allhands/harness/src/commands/docs.ts:tree:3912018] generates a source tree annotated with documentation coverage. For each source file, it checks whether a corresponding doc exists at predictable paths (`docs/{path}.md`, `docs/{dir}/{name}.md`, `docs/{path}/index.md`). The output includes coverage statistics (total files, covered files, percentage).

package/docs/harness/cli/knowledge-command.md

@@ -0,0 +1,91 @@
+---
+description: "Embedding-based semantic search over project knowledge: how documents are indexed into USearch HNSW indexes, searched by similarity, and incrementally reindexed from git changes."
+---
+
+# Knowledge Command
+
+## Intent
+
+Agents need to discover relevant project knowledge without knowing exact file paths or keywords. The knowledge system provides semantic search -- query with a natural language description and get back the most relevant documents ranked by embedding similarity. This is the infrastructure behind `ah knowledge docs search <query>`.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    Query["Search Query"] --> Embed["Embed query<br/>gtr-t5-quant"]
+    Embed --> Search["USearch HNSW<br/>cosine similarity"]
+    Search --> Filter["Threshold + Token Budget"]
+    Filter --> Aggregate{"Total tokens > 3500?"}
+    Aggregate -->|Yes| AI["AI Aggregator<br/>synthesize insights"]
+    Aggregate -->|No| Raw["Return raw results"]
+    AI --> Output["Structured output:<br/>insight, LSP entry points, design notes"]
+    Raw --> Output
+```
+
+## Index Configuration
+
+[ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] manages multiple named indexes, each configured for a specific document domain:
+
+| Index | Paths Scanned | Description |
+|-------|---------------|-------------|
+| `docs` | `docs/`, `specs/` | Project documentation and specifications |
+| `roadmap` | `specs/roadmap/` | Planned work specifications |
+
+Each index stores its data as two files in `.allhands/harness/.knowledge/`:
+- `{name}.usearch` -- the HNSW vector index (768-dimensional, cosine metric)
+- `{name}.meta.json` -- bidirectional path-to-ID mappings, document metadata, timestamps
+
+Files named `memories.md` are excluded from indexing -- they contain project-specific learnings that are not suited for semantic search.
+
+## Embedding and Search
+
+[ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] exposes an `embed` method that generates 768-dimensional embeddings using the `gtr-t5-quant` model from `@visheratin/web-ai-node`. The model is lazy-loaded on first use and cached for the process lifetime.
+
+The `search` method on [ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] executes similarity search with several filtering layers:
+
+| Filter | Threshold | Purpose |
+|--------|-----------|---------|
+| Similarity minimum | 0.65 (configurable) | Discard irrelevant results |
+| Token budget | 5000 tokens (configurable) | Bound context size for agents |
+| Full context threshold | 0.82 (configurable) | Only include full file content for high-confidence matches |
+
+The similarity score converts cosine distance to a 0-1 scale: `similarity = 1 - distance/2`. The search over-fetches by 2x to compensate for deleted entries that remain in the vector index (USearch does not support true deletion).
+
+Thresholds are configurable via project settings under `knowledge.similarityThreshold`, `knowledge.contextTokenLimit`, and `knowledge.fullContextSimilarityThreshold`.
+
+## Search Command with Aggregation
+
+[ref:.allhands/harness/src/commands/knowledge.ts:SearchCommand:681f3dc] adds an AI aggregation layer on top of raw search results. When the total token count of results exceeds 3500 tokens, it invokes an aggregator agent that synthesizes the raw results into structured output: an insight summary, LSP entry points for code navigation, and design notes.
+
+The aggregation can be disabled with `--no-aggregate` for raw results, or `--metadata-only` for just file paths and descriptions without content.
+
+## Indexing
+
+### Full Reindex
+
+The `reindexAll` method on [ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] rebuilds an index from scratch:
+
+1. Discovers all files matching the index configuration (paths + extensions)
+2. Parses frontmatter from markdown files for metadata (description, relevant_files)
+3. Strips frontmatter from content before embedding (when configured)
+4. Generates embeddings and adds vectors to a fresh USearch index
+5. Saves index and metadata to disk
+
+### Incremental Reindex
+
+The `reindexFromChanges` method on [ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] updates an existing index based on a list of file changes:
+
+- **Added/Modified files**: Re-embed and upsert into the index
+- **Deleted files**: Remove from metadata (vector remains in index but is filtered during search)
+
+[ref:.allhands/harness/src/commands/knowledge.ts:getChangesFromGit:681f3dc] detects changes by comparing the current branch against the base branch using `git diff --name-status`. This powers the `--from-changes` flag on reindex commands.
+
+[ref:.allhands/harness/src/commands/knowledge.ts:ReindexCommand:681f3dc] supports both full and incremental modes, and can operate on a single index or all indexes at once.
+
+### Document Indexing
+
+The `indexDocument` method on [ref:.allhands/harness/src/lib/knowledge.ts:KnowledgeService:0f31ba1] handles individual document insertion. It assigns or reuses numeric IDs, removes old entries before re-adding (USearch requires unique keys), generates embeddings, and stores metadata including description, relevant files, and estimated token count.
+
+## Status Checking
+
+[ref:.allhands/harness/src/commands/knowledge.ts:StatusCommand:681f3dc] reports which indexes exist on disk, enabling agents to determine whether they need to trigger a reindex before searching.

package/docs/harness/cli/minor-cli-commands.md

@@ -0,0 +1,65 @@
+---
+description: "Smaller CLI utilities: skills discovery from YAML frontmatter, desktop notifications via jamf/Notifier with gate/hook variants, and ctags-based complexity metrics for files and directories."
+---
+
+## Skills Discovery
+
+[ref:.allhands/harness/src/commands/skills.ts:listSkills:4fb6c9f] scans `.allhands/skills/*/SKILL.md` for skill definitions. Each skill file must have YAML frontmatter with `name`, `description`, and `globs` fields. The command outputs a JSON array of discovered skills with their glob patterns, enabling agents to find domain-specific expertise.
+
+Skills are organized as directories under `.allhands/skills/`, where each directory contains a `SKILL.md` file. The frontmatter schema:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | Yes | Skill identifier |
+| `description` | Yes | What the skill provides |
+| `globs` | Yes | File patterns the skill is relevant for |
+| `version` | No | Skill version |
+| `license` | No | License information |
+
+## Desktop Notifications
+
+The notification system uses jamf/Notifier (macOS) for system-level desktop notifications. This is designed for situations where agents need human attention -- gate approvals, idle detection, or completion signals.
+
+### Notification Layout
+
+[ref:.allhands/harness/src/lib/notification.ts:sendNotification:8f14a76] constructs notifications with three parts:
+- **Title**: Event type (e.g., "Agent Stopped", "Plan Gate")
+- **Subtitle**: Auto-detected from `repo + branch` context
+- **Message**: Specific details for the user
+
+### Notification Variants
+
+| Function | Type | Behavior |
+|----------|------|----------|
+| [ref:.allhands/harness/src/lib/notification.ts:sendNotification:8f14a76] | Configurable | Base function, supports banner or alert |
+| [ref:.allhands/harness/src/lib/notification.ts:sendGateNotification:8f14a76] | `alert` | Persists until dismissed. Used for decisions requiring human input |
+| `sendHookNotification` | `banner` | Auto-dismisses. Used for informational hook events |
+
+Banners auto-dismiss after the system default; alerts persist until the user interacts with them. The `--sound` option triggers a macOS system sound.
+
+The notifier binary is located at `/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier` or via PATH lookup. If not installed, notifications silently fail (no error propagation) -- this is intentional so agents don't break on systems without the notifier.
+
+## Complexity Analysis
+
+[ref:.allhands/harness/src/commands/complexity.ts:complexity:ec1532e] provides complexity metrics for files and directories using ctags for symbol counting rather than language-specific AST parsers.
+
+### File Metrics
+
+For a single file, the output includes:
+
+| Metric | Source |
+|--------|--------|
+| lines | Line count |
+| functions | ctags `function` + `method` kinds |
+| classes | ctags `class` kind |
+| interfaces | ctags `interface` + `type` kinds |
+| imports | Regex match on `^import\s` |
+| exports | Regex match on `^export\s` |
+| total_symbols | Total ctags entries |
+| estimated_tokens | `lines * 10` (rough heuristic) |
+
+### Directory Metrics
+
+For directories, the command recursively scans source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`), generates a ctags index for the subtree, and aggregates line counts and symbol counts across all files. The output includes `file_count` alongside the aggregated metrics.
+
+Both modes require Universal Ctags to be installed ([ref:.allhands/harness/src/lib/ctags.ts:checkCtagsAvailable:45c4520]).

package/docs/harness/cli/oracle-command.md

@@ -0,0 +1,113 @@
+---
+description: "LLM-powered oracle system: multi-provider inference layer, PR generation from alignment docs, conversation analysis for compaction, and action recommendation for agent retry logic."
+---
+
+# Oracle Command
+
+## Intent
+
+The oracle is the harness's bridge to external LLM providers. It serves two purposes:
+
+1. **Generic inference** (`ah oracle ask`) -- a provider-agnostic way for any harness component to call an LLM
+2. **Harness-specific AI tasks** -- PR generation, conversation analysis, and retry recommendations that are internal functions not exposed to agents
+
+The separation between [ref:.allhands/harness/src/lib/llm.ts::697d7e2] (generic provider layer) and [ref:.allhands/harness/src/lib/oracle.ts::3d01f6c] (harness-specific logic) keeps the LLM infrastructure reusable while concentrating domain-specific prompting in one place.
+
+## Provider Architecture
+
+```mermaid
+flowchart TD
+    Ask["ask(query, options)"] --> Resolve["Resolve provider"]
+    Resolve --> Key["Read API key<br/>from environment"]
+    Key --> Build["Build prompt:<br/>context + files + query"]
+    Build --> Dispatch{"Provider?"}
+    Dispatch -->|gemini| Gemini["callGemini()<br/>@google/genai SDK"]
+    Dispatch -->|openai| OpenAI["callOpenAI()<br/>OpenAI-compatible API"]
+    Gemini --> Result["LLMResult:<br/>text, model, provider, durationMs"]
+    OpenAI --> Result
+```
+
+[ref:.allhands/harness/src/lib/llm.ts:ask:697d7e2] is the unified entry point. It resolves the provider, reads the API key from environment, builds a prompt with optional file and context prefixes, dispatches to the provider-specific implementation, and returns a result with timing metadata.
+
+### Provider Configuration
+
+| Provider | API Key Env Var | Default Model | SDK |
+|----------|----------------|---------------|-----|
+| Gemini | `GEMINI_API_KEY` | `gemini-3-pro-preview` | `@google/genai` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-5.2` | OpenAI-compatible REST |
+
+[ref:.allhands/harness/src/lib/llm.ts:getDefaultProvider:697d7e2] reads the default from project settings (`oracle.defaultProvider`), falling back to `gemini`.
+
+[ref:.allhands/harness/src/lib/llm.ts:getCompactionProvider:697d7e2] is separate because compaction (conversation analysis) benefits from large context windows. It defaults to `gemini` for its 1M+ token context, configurable via `oracle.compactionProvider`.
+
+### Provider Implementations
+
+[ref:.allhands/harness/src/lib/llm.ts:callGemini:697d7e2] uses the official `@google/genai` SDK with API key authentication (Gemini Developer API, not Vertex AI).
+
+[ref:.allhands/harness/src/lib/llm.ts:callOpenAI:697d7e2] uses the OpenAI-compatible REST API.
+
+[ref:.allhands/harness/src/lib/llm.ts:callProvider:697d7e2] dispatches to the appropriate implementation based on provider name.
+
+## PR Generation
+
+[ref:.allhands/harness/src/lib/oracle.ts:buildPR:3d01f6c] orchestrates the full PR creation workflow:
+
+```mermaid
+sequenceDiagram
+    participant Build as buildPR()
+    participant Plan as Planning State
+    participant Gen as generatePRDescription()
+    participant GH as gh CLI
+    participant Comments as postPRComments()
+
+    Build->>Plan: Read alignment doc + status
+    Build->>Gen: Generate title, body, review steps
+    Gen-->>Build: PRContent
+    alt PR already exists in status.yaml
+        Build->>GH: Update PR description
+        Build->>Comments: Update review comments
+    else No existing PR
+        Build->>GH: Push branch + create PR
+        Build->>Comments: Post review comments
+        Build->>Plan: Update status.yaml with PR info
+    end
+```
+
+[ref:.allhands/harness/src/lib/oracle.ts:generatePRDescription:3d01f6c] takes alignment content, spec name, and optional spec content, then:
+
+1. Gets the git diff from base branch
+2. Parses changed files from the diff
+3. Prompts the LLM to generate a title, body, and review steps grouped by file category
+4. Validates the response against a Zod schema (`PRContentSchema`)
+5. Falls back to [ref:.allhands/harness/src/lib/oracle.ts:extractAlignmentSummary:3d01f6c] + [ref:.allhands/harness/src/lib/oracle.ts:generateFallbackReviewSteps:3d01f6c] if LLM fails
+
+**Key decision**: The fallback groups changed files by type (Core Logic, API/Routes, Components, Tests, Configuration) using path pattern matching, ensuring review steps always exist even when the LLM is unavailable.
+
+[ref:.allhands/harness/src/lib/oracle.ts:postPRComments:3d01f6c] adds review step comments to the PR via `gh api`. [ref:.allhands/harness/src/lib/oracle.ts:updatePRDescription:3d01f6c] and [ref:.allhands/harness/src/lib/oracle.ts:updatePRComments:3d01f6c] handle the update-existing-PR path, finding and replacing previous harness-generated comments.
+
+## Conversation Analysis
+
+[ref:.allhands/harness/src/lib/oracle.ts:analyzeConversation:3d01f6c] examines agent conversation logs after a session to extract:
+
+- Whether the agent was making meaningful progress
+- Estimated completion percentage (0-100)
+- Key learnings for the next attempt
+- Blockers that prevented completion
+- Partial work worth preserving
+
+The response is validated against `ConversationAnalysisSchema` (Zod with `z.coerce` to handle LLMs returning strings for boolean/number fields). On failure, it returns a conservative fallback assuming 50% progress.
+
+## Action Recommendation
+
+[ref:.allhands/harness/src/lib/oracle.ts:recommendAction:3d01f6c] uses the conversation analysis to decide the next step:
+
+| Decision | Criteria |
+|----------|----------|
+| `continue` | >40% progress, code compiles, meaningful logic exists |
+| `scratch` | <20% progress, code broken, mostly boilerplate, wrong approach |
+
+The recommendation includes `preserveFiles` and `discardFiles` lists, enabling selective code preservation during retry. On LLM failure, it defaults to `continue` to avoid losing code unnecessarily.
+
+## Response Parsing
+
+All oracle functions that expect structured LLM responses use [ref:.allhands/harness/src/lib/oracle.ts:extractJSON:3d01f6c] to handle the variety of response formats LLMs produce. It tries markdown code block extraction first (```` ```json ... ``` ````), then falls back to brace-matching with proper string escape handling.

package/docs/harness/cli/planning-command.md

@@ -0,0 +1,95 @@
+---
+description: "Branch-keyed planning directories: how the harness creates and manages per-branch planning state including status tracking, alignment documents, and decision logs."
+---
+
+# Planning Command
+
+## Intent
+
+Every spec under active development needs a working directory for mutable planning state: which stage the work is in, what decisions have been made, and what the alignment document says. The planning system maps this state to git branches, making the current branch the sole determinant of which planning context is active.
+
+This is the harness's answer to the question: *where does ephemeral implementation state live?*
+
+## Branch-to-Directory Model
+
+```mermaid
+flowchart LR
+    Branch["git branch<br/>feature/auth-flow"] -->|sanitize| Key["feature-auth-flow"]
+    Key -->|resolve| Dir[".planning/feature-auth-flow/"]
+    Dir --> Status["status.yaml"]
+    Dir --> Alignment["alignment.md"]
+    Dir --> Prompts["prompts/"]
+```
+
+[ref:.allhands/harness/src/lib/planning.ts:sanitizeBranchForDir:41639ef] converts branch names to filesystem-safe directory keys by replacing non-alphanumeric characters (slashes, dots) with hyphens. `feature/foo-bar` becomes `feature-foo-bar`.
+
+### Locked Branches
+
+Not every branch should have planning state. [ref:.allhands/harness/src/lib/planning.ts:isLockedBranch:41639ef] prevents planning directories for:
+
+| Category | Examples |
+|----------|----------|
+| Protected names | `main`, `master`, `develop`, `staging`, `production` |
+| Configured base branch | Whatever `BASE_BRANCH` resolves to |
+| Prefix patterns | `wt-*` (worktrees), `quick/*` (quick fixes) |
+
+## Planning Directory Structure
+
+Each planning directory at `.planning/{key}/` contains:
+
+| File | Purpose | Managed By |
+|------|---------|------------|
+| `status.yaml` | Session state: stage, loop config, PR info | [ref:.allhands/harness/src/lib/planning.ts:writeStatus:41639ef] |
+| `alignment.md` | Decisions, overview, hard requirements | [ref:.allhands/harness/src/lib/planning.ts:initializeAlignment:41639ef] |
+| `prompts/` | Prompt files for agent execution | External (planner agents) |
+
+### Status Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> planning: initializeStatus()
+    planning --> executing: Agent begins prompt work
+    executing --> reviewing: All prompts completed
+    reviewing --> pr: PR created
+    pr --> compound: Compound run triggered
+    compound --> pr: PR updated
+```
+
+[ref:.allhands/harness/src/lib/planning.ts:initializeStatus:41639ef] creates the initial `StatusFile` with the `planning` stage, linking it to the spec path and recording the original branch name for collision detection.
+
+[ref:.allhands/harness/src/lib/planning.ts:updateStatus:41639ef] performs partial updates, merging new fields into the existing status while preserving the `updated` timestamp.
+
+### Alignment Document
+
+The alignment document is the shared memory between planning and execution agents. It contains:
+
+- **Frontmatter**: spec name, spec path, timestamps
+- **Overview**: high-level description from the planner
+- **Hard Requirements**: non-negotiable constraints from the spec
+- **Decisions**: append-only log of implementation decisions
+
+[ref:.allhands/harness/src/lib/planning.ts:appendDecision:41639ef] adds timestamped decision entries recording which prompt prompted the decision, what was decided, which files were affected, and a summary. This creates an audit trail that execution agents and PR reviewers can reference.
+
+[ref:.allhands/harness/src/lib/planning.ts:readAlignment:41639ef] returns the full alignment content, while [ref:.allhands/harness/src/lib/planning.ts:readAlignmentFrontmatter:41639ef] returns just the parsed YAML header for metadata access without loading the full document body.
+
+## CLI Subcommands
+
+[ref:.allhands/harness/src/commands/planning.ts:register:351bd20] exposes three subcommands:
+
+- **`ah planning status`** -- Reports the current branch's planning state. Resolves the branch, finds the linked spec via [ref:.allhands/harness/src/lib/specs.ts:getSpecForBranch:ce6f7c5], and reads the status file. Outputs spec info, stage, and PR status when available.
+
+- **`ah planning list`** -- Enumerates all planning directories via [ref:.allhands/harness/src/lib/planning.ts:listPlanningDirs:41639ef], showing key, spec path, stage, and marking the current branch's directory.
+
+- **`ah planning ensure`** -- Idempotent setup: creates the planning directory and initializes status if they do not exist for the current branch. Requires a spec to be linked to the branch.
+
+## Planning Utilities
+
+[ref:.allhands/harness/src/lib/planning-utils.ts:findSpecForPath:f283c2d] resolves a spec path to its planning directory key, bridging the gap when code needs to go from a spec file to its planning state. It does this by checking spec frontmatter for a `branch` field and sanitizing it.
+
+[ref:.allhands/harness/src/lib/planning-utils.ts:listAllSpecs:f283c2d] provides a flat list of all specs with their planning directory links, useful for TUI spec selection and overview displays.
+
+## Key Design Decisions
+
+- **Branch as key, not spec name**: Using the branch ensures each working context is independent even when the same spec is attempted on different branches.
+- **Append-only decisions**: The alignment document never overwrites previous decisions, preserving the reasoning chain for future agents and human reviewers.
+- **Locked branches**: Prevents accidental planning state on shared branches, which would cause conflicts in multi-agent environments.