all-hands-cli 0.1.0

package/docs/solutions/integration_issue/blocktool-output-format-mismatch-hook-runner-20260130.md

@@ -0,0 +1,52 @@
+---
+description: "Documents how blockTool() outputs { decision: 'block' } but hook-runner assertHookBlocked expects { continue: false }, requiring raw JSON assertions for PostToolUse tests."
+title: "blockTool() output format mismatch with hook-runner assertHookBlocked helper"
+date: "2026-01-30"
+milestone: "feature/validation-tooling-practice"
+problem_type: integration_issue
+component: "hook-runner"
+symptoms:
+  - "assertHookBlocked assertion fails on PostToolUse hooks that correctly block"
+  - "Hook blocks tool but test assertion reports allowed"
+  - "PostToolUse test needs raw JSON inspection instead of helper assertions"
+root_cause: wrong_api_usage
+severity: medium
+tags:
+  - "blocktool"
+  - "hook-runner"
+  - "post-tool-use"
+  - "assertion"
+  - "test-harness"
+  - "format-mismatch"
+  - "integration-testing"
+source: agent-inferred
+---
+
+# blockTool Output Format Mismatch — Hook Runner
+
+## Problem
+
+The `blockTool()` helper in [ref:hooks/shared.ts] outputs `{ decision: 'block', reason: '...' }` for PostToolUse hooks. However, the hook-runner test harness's `assertHookBlocked` helper expects `{ continue: false }`. This means PostToolUse block assertions fail even when the hook correctly blocks the tool.
+
+Discovered in Prompt 07 (attempt 2) when writing integration tests for the `schema` PostToolUse validation hook.
+
+## Investigation
+
+Used `assertHookBlocked(result)` — the standard helper for verifying hook blocking behavior. This checks for `{ continue: false }` in the parsed output, which `blockTool()` does not produce. Required 3 attempts on Prompt 07 to work around this.
+
+## Solution
+
+Assert directly against the raw JSON output:
+```typescript
+expect(result.json.decision).toBe('block');
+```
+
+This bypasses the `assertHookBlocked` helper and checks the actual output format that `blockTool()` produces.
+
+## Prevention
+
+The hook-runner assertion helpers should be updated to handle both PostToolUse output formats (`{ decision: 'block' }` and `{ continue: false }`), or `blockTool()` should be updated to output the format the helpers expect. This is a known harness inconsistency tracked in memories.
+
+## Related
+
+- See `docs/solutions/integration_issue/dual-validation-path-divergence-schema-20260130.md` for the broader consolidation context that led to this discovery.

package/docs/solutions/integration_issue/dual-validation-path-divergence-schema-20260130.md

@@ -0,0 +1,66 @@
+---
+description: "Documents how hooks/validation.ts and lib/schema.ts had 4 behavioral divergences in schema validation, and how consolidation by delegating hooks to lib resolved all divergences."
+title: "Dual validation path divergence between hooks/validation.ts and lib/schema.ts"
+date: "2026-01-30"
+milestone: "feature/validation-tooling-practice"
+problem_type: integration_issue
+component: "schema-validation"
+symptoms:
+  - "Frontmatter accepted by hooks but rejected by lib (or vice versa)"
+  - "Boolean/date/object fields silently pass hooks validation without type checking"
+  - "extractFrontmatter returns null for content without trailing newline after closing ---"
+  - "Different error shapes between validation paths (ValidationResult vs ValidationError[])"
+root_cause: incomplete_implementation
+severity: high
+tags:
+  - "schema"
+  - "validation"
+  - "divergence"
+  - "consolidation"
+  - "hooks"
+  - "dual-path"
+  - "frontmatter"
+  - "type-checking"
+  - "deduplication"
+source: agent-inferred
+---
+
+# Dual Validation Path Divergence — Schema Enforcement
+
+## Problem
+
+Two independent implementations of schema validation existed in the harness:
+- [ref:lib/schema.ts] — the canonical validation library with 7 type branches, caching, and `ValidationResult` return type
+- [ref:hooks/validation.ts] — the hook enforcement layer with its own `parseFrontmatter`, `loadSchema`, and `validateFrontmatter` implementations
+
+These paths diverged in 4 specific ways, discovered via stability tests in Prompt 10:
+
+1. **Frontmatter regex**: lib requires trailing newline after closing `---`; hooks does not
+2. **Type branch coverage**: hooks handles string/integer/enum/array but NOT boolean/date/object — these silently pass
+3. **Return type shape**: lib returns `{ valid, errors }`, hooks returns `ValidationError[]`
+4. **schema.fields fallback**: lib uses `schema.frontmatter || schema.fields || {}`; hooks returns empty array if `!schema.frontmatter`
+
+## Investigation
+
+- Prompt 04: Added array item-type validation to BOTH paths (first indication of duplication)
+- Prompt 06: Unit tests for [ref:lib/schema.ts] revealed comprehensive type branch coverage
+- Prompt 07: Integration tests for hooks revealed the `blockTool` format mismatch (separate issue) and hook behavior
+- Prompt 10: Deliberately documented all 4 divergences with paired tests showing each path's behavior on identical input
+
+## Solution
+
+Jury Review item #8: Refactored [ref:hooks/validation.ts] to import and delegate to [ref:lib/schema.ts] for `loadSchema`, `extractFrontmatter`, and `validateFrontmatter`. Removed local `SchemaDefinition`, `ValidationError` types, and all local validation functions. This eliminated all 4 divergences in one consolidation.
+
+Jury Review item #9 extended this to [ref:commands/validation-tools.ts], replacing its local `extractFrontmatter` with the lib import.
+
+Prompt 11 (PR review fix) completed consolidation by replacing the manual `Array.isArray` guard in `listValidationSuites()` with `validateFrontmatter()` delegation.
+
+## Prevention
+
+- Schema validation should have a single source of truth ([ref:lib/schema.ts]). Other modules import, never reimplement.
+- When adding new validation logic (like array item-type checking), the need to update multiple files is a code smell indicating duplication.
+- Stability tests that document divergences between parallel implementations create a consolidation roadmap.
+
+## Related
+
+- See `docs/solutions/integration_issue/blocktool-output-format-mismatch-hook-runner-20260130.md` for the separate hook-runner assertion issue discovered during the same investigation chain.

package/docs/solutions/security-issues/unsanitized-domain-path-join-20260131.md

@@ -0,0 +1,52 @@
+---
+title: "Unsanitized domain value used in path.join enables path traversal"
+date: "2026-01-31"
+milestone: feature/workflow-domain-configuration
+problem_type: security_issue
+component: harness-tui
+symptoms:
+  - "User-selected domain value passed directly to path.join()"
+  - "No validation that domain value is a known domain"
+  - "Path construction could resolve to arbitrary filesystem locations"
+root_cause: missing_validation
+severity: high
+tags:
+  - path-traversal
+  - path-join
+  - input-validation
+  - domain-allowlist
+  - template-variables
+  - tui-actions
+  - workflow-domain
+source: review-fix
+---
+
+## Problem
+
+Three path construction sites in the harness accepted domain values (from spec frontmatter and TUI modal selection) and used them directly in `path.join()` to resolve workflow domain config file paths:
+
+- `buildTemplateContext()` in `tmux.ts`: `path.join(workflowsDir, domain + '.md')`
+- `openNewInitiativeModal()` in `tui/index.ts`: similar path construction
+- `openSteeringDomainModal()` in `tui/index.ts`: context override path
+
+A crafted `initial_workflow_domain` value like `../../etc/passwd` in spec frontmatter could resolve to arbitrary filesystem paths. The initiative-steering context override path additionally lacked an `existsSync` guard, meaning it would pass a nonexistent path as a template variable.
+
+## Investigation
+
+Jury review's Security reviewer and 1 additional reviewer flagged this as P1 — the path traversal vector existed at all 3 sites and the `existsSync` guard was missing only on the steering override.
+
+## Solution
+
+Prompt 11 implemented:
+
+1. **Domain allowlist** (`VALID_WORKFLOW_DOMAINS`): Constant array of valid domain values derived from the `SpecType` union type in `specs.ts`
+2. **Shared utility** (`getWorkflowDomain()`): Centralized function that reads `initial_workflow_domain` from spec frontmatter via `parseFrontmatter()`, validates against the allowlist, and returns `milestone` as fallback for unknown values
+3. **`existsSync` guard** on initiative-steering context override path: Only applies the override if the resolved path exists on disk
+4. All 3 path construction sites now use the validated domain from `getWorkflowDomain()` or the TUI modal's constrained selection
+
+## Prevention
+
+- When constructing filesystem paths from user-controlled or file-controlled values, validate against an allowlist before `path.join()`
+- Use centralized utility functions for domain-to-path resolution to ensure validation cannot be bypassed
+- Add `existsSync` guards when resolved paths are passed to downstream consumers that assume validity
+- The `VALID_WORKFLOW_DOMAINS` constant is derived from the TypeScript union type, ensuring schema and runtime validation stay in sync

package/docs/solutions/test-failures/event-loop-mock-ordering-checkAgentWindows-20260130.md

@@ -0,0 +1,63 @@
+---
+description: "Solution for event loop test failures caused by checkAgentWindows running before checkPromptLoop in each tick, requiring listWindows mock to return executor windows to prevent state reconciliation."
+title: "Event loop tests fail due to checkAgentWindows reconciliation clearing spawn timestamps"
+date: "2026-01-30"
+milestone: "feature/unified-workflow-orchestration"
+problem_type: test_failure
+component: "event-loop"
+symptoms:
+  - "Cooldown timer tests fail unexpectedly"
+  - "Spawn callback fires when cooldown should prevent it"
+  - "lastExecutorSpawnTime reset between tick phases"
+  - "Event loop tests pass individually but fail in sequence"
+root_cause: timing_issue
+severity: medium
+tags:
+  - event-loop-testing
+  - vitest-mocking
+  - checkAgentWindows
+  - checkPromptLoop
+  - spawn-cooldown
+  - tick-ordering
+  - listWindows-mock
+---
+
+## Problem
+
+When writing unit tests for [ref:.allhands/harness/src/lib/event-loop.ts:checkPromptLoop], cooldown timer tests failed because `lastExecutorSpawnTime` was being cleared between test assertions. The root cause: each `forceTick()` call runs `checkAgentWindows()` before `checkPromptLoop()`. If `listWindows` mock returns no windows, `checkAgentWindows` reconciles by clearing `activeExecutorPrompts` and resetting spawn-related timestamps, invalidating cooldown state before `checkPromptLoop` can check it.
+
+## Root Cause
+
+The event loop tick has two phases executed sequentially:
+1. `checkAgentWindows()` — reconciles tracked state against actual tmux windows
+2. `checkPromptLoop()` — makes spawn decisions based on state
+
+When `listWindows` returns an empty array (the default mock), phase 1 treats all tracked executors as departed and resets state. Phase 2 then sees clean state and makes incorrect spawn decisions.
+
+## Solution
+
+Configure `listWindows` mock to return executor window entries matching the expected active executors:
+
+```typescript
+vi.mocked(listWindows).mockResolvedValue([
+  { name: 'executor-01', active: true }
+]);
+```
+
+This prevents reconciliation from clearing state, allowing `checkPromptLoop` to see the correct timestamps and cooldown values.
+
+## Prevention
+
+When testing any event loop decision logic:
+1. Always configure `listWindows` to return windows matching the expected active state
+2. Remember tick ordering: agent window reconciliation runs first
+3. For cooldown tests specifically, ensure executor windows persist across ticks
+
+## Failed Approaches
+
+- Mocking only `loadAllPrompts` without `listWindows` — reconciliation clears state
+- Running cooldown tests without any active windows — timestamps reset each tick
+
+## Related
+
+None yet.

package/docs/sync-cli/README.md

@@ -0,0 +1,19 @@
+---
+description: "Index of sync CLI documentation covering the CLI entry point, sync/push/pull-manifest commands, and shared systems (manifest, git/GitHub, path resolution, interactive UI)."
+---
+
+# Sync CLI
+
+CLI for distributing the all-hands framework to other repositories and contributing changes back upstream.
+
+## Entry Point
+
+`docs/sync-cli/cli-entrypoint-and-commands.md` — Top-level CLI structure, yargs registration, and dependency checks.
+
+## Commands
+
+See `docs/sync-cli/commands/README.md` for the full list.
+
+## Systems
+
+Shared libraries used across commands. See `docs/sync-cli/systems/README.md`.

package/docs/sync-cli/cli-entrypoint-and-commands.md

@@ -0,0 +1,39 @@
+---
+description: "Top-level CLI entrypoint that registers sync, push, and pull-manifest commands via yargs, with git dependency gating at startup"
+---
+
+# CLI Entrypoint and Command Registration
+
+The sync-cli is the distribution tool for the allhands framework. It handles moving framework files between the upstream source and target repositories, managing conflicts, and contributing changes back.
+
+## Startup Sequence
+
+```mermaid
+flowchart TD
+    A[main] --> B{git installed?}
+    B -- No --> C[Exit 1: git required]
+    B -- Yes --> D[Parse argv via yargs]
+    D --> E{command?}
+    E -- sync --> F[cmdSync]
+    E -- push --> G[cmdPush]
+    E -- pull-manifest --> H[cmdPullManifest]
+    E -- none --> I[Exit: demandCommand error]
+```
+
+[ref:src/sync-cli.ts:main:d536164] gates on [ref:src/lib/git.ts:checkGitInstalled:70a743c] before any command parsing occurs. This is the only dependency check at the entrypoint level -- the `push` command performs its own additional prerequisite checks (gh CLI, auth, repo detection).
+
+## Command Surface
+
+| Command | Entry | Purpose |
+|---|---|---|
+| `sync [target]` | [ref:src/sync-cli.ts:syncHandler:d536164] | Initialize or update allhands in a target repo |
+| `push` | [ref:src/commands/push.ts:cmdPush:e7d51e3] | Contribute local changes back upstream via fork + PR |
+| `pull-manifest` | [ref:src/commands/pull-manifest.ts:cmdPullManifest:92ad739] | Scaffold the sync config file for push customization |
+
+## Key Design Decision: Separated Builder/Handler
+
+[ref:src/sync-cli.ts:syncBuilder:d536164] and [ref:src/sync-cli.ts:syncHandler:d536164] are extracted as named functions rather than inlined in the yargs `.command()` call. This enables reuse if the sync command needs to be composed or tested independently. The other commands inline their builders since they have no reuse need.
+
+## Process Exit Convention
+
+Every command handler resolves to a numeric exit code (`Promise<number>`). The entrypoint calls `process.exit(code)` after awaiting the handler. This keeps command implementations testable (they return codes, not call exit themselves) while ensuring the CLI process terminates cleanly.

package/docs/sync-cli/commands/README.md

@@ -0,0 +1,11 @@
+---
+description: "Index of sync CLI command documentation covering sync (framework installation/update), push (upstream contribution), and pull-manifest (config scaffolding)."
+---
+
+# Sync CLI Commands
+
+| Command | Purpose | Doc |
+|---|---|---|
+| sync | Initialize or update the allhands framework with conflict resolution | `docs/sync-cli/commands/sync-command.md` |
+| push | Contribute local changes back upstream via GitHub fork and PR | `docs/sync-cli/commands/push-command.md` |
+| pull-manifest | Scaffold the sync config file for push customization | `docs/sync-cli/commands/pull-manifest-command.md` |

package/docs/sync-cli/commands/pull-manifest-command.md

@@ -0,0 +1,36 @@
+---
+description: "Pull-manifest command that scaffolds the sync config file for customizing which files are included or excluded during push operations"
+---
+
+# Pull-Manifest Command
+
+[ref:src/commands/pull-manifest.ts:cmdPullManifest:92ad739] is the simplest command in the CLI -- it writes a template configuration file that lets repositories customize their push behavior.
+
+## Intent
+
+The push command needs to know which additional files to include and which to exclude when creating upstream PRs. Rather than requiring users to always pass `--include` and `--exclude` flags, the sync config file persists these preferences in version control.
+
+## Guard Rails
+
+The command enforces two preconditions:
+- Must be in a git repository (checked via [ref:src/lib/git.ts:isGitRepo:70a743c])
+- Config file must not already exist (prevents accidental overwrite of user customizations)
+
+If the file exists, the user is told to remove it first and re-run. This is intentional -- there's no merge logic for config files, so regeneration should be a conscious choice.
+
+## Config File Shape
+
+The template is defined as [ref:src/lib/constants.ts:SYNC_CONFIG_TEMPLATE:61d6025] and written to the path defined by [ref:src/lib/constants.ts:SYNC_CONFIG_FILENAME:61d6025] (`.allhands-sync-config.json`):
+
+```
+{
+  "$comment": "Customization for claude-all-hands push command",
+  "includes": [],
+  "excludes": []
+}
+```
+
+- **includes** -- Glob patterns for additional files to push beyond the standard distributable set
+- **excludes** -- Glob patterns for files to skip, even if they differ from upstream
+
+The config file itself is in [ref:src/lib/constants.ts:PUSH_BLOCKLIST:61d6025], so it is never pushed back upstream -- it's purely a local customization mechanism.

package/docs/sync-cli/commands/push-command.md

@@ -0,0 +1,84 @@
+---
+description: "Push command that contributes local allhands changes back to upstream via GitHub fork, temp clone, and pull request creation"
+---
+
+# Push Command
+
+The push command enables downstream consumers to contribute their local allhands modifications back to the upstream repository. It uses a fork-based workflow -- forking the upstream repo, cloning to a temp directory, copying changed files, and opening a pull request.
+
+## Contribution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI as cmdPush
+    participant GH as GitHub API
+    participant TempDir as Temp Clone
+
+    CLI->>CLI: checkPrerequisites (gh, auth, repo)
+    CLI->>CLI: loadSyncConfig
+    CLI->>CLI: collectFilesToPush
+
+    alt dry-run
+        CLI->>User: Print file list, exit
+    end
+
+    CLI->>User: Prompt for title/body
+    CLI->>GH: Check for existing fork
+
+    alt no fork
+        CLI->>GH: Fork upstream
+        CLI->>GH: waitForFork (poll up to 30s)
+    end
+
+    CLI->>TempDir: Clone fork (depth=1)
+    CLI->>TempDir: Add upstream remote
+    CLI->>TempDir: Fetch upstream/main
+    CLI->>TempDir: Create branch from upstream/main
+    CLI->>TempDir: Copy changed files from CWD
+    CLI->>TempDir: git add + commit
+    CLI->>GH: Push branch to fork
+    CLI->>GH: Create PR against upstream
+    CLI->>User: Print PR URL
+    CLI->>TempDir: Cleanup temp directory
+```
+
+## File Collection Logic
+
+[ref:src/commands/push.ts:collectFilesToPush:e7d51e3] determines which files to include in the PR through a layered filtering pipeline:
+
+1. **Distributable files** -- Gets the upstream manifest's distributable set via [ref:src/lib/manifest.ts:Manifest:e06b487]
+2. **Blocklist filter** -- Removes files in [ref:src/lib/constants.ts:PUSH_BLOCKLIST:61d6025] (e.g., `CLAUDE.project.md`, sync config)
+3. **Exclude filter** -- Removes files matching user-provided or config-defined exclude patterns
+4. **Gitignore filter** -- Skips files not tracked by git in the user's repo
+5. **Diff filter** -- Only includes files where [ref:src/lib/manifest.ts:filesAreDifferent:e06b487] detects byte-level changes
+6. **Include expansion** -- [ref:src/commands/push.ts:expandGlob:e7d51e3] adds extra files matching include patterns that aren't already queued
+
+Files are classified as `M` (modified upstream file) or `A` (additional file via includes).
+
+## Sync Config Integration
+
+[ref:src/commands/push.ts:loadSyncConfig:e7d51e3] reads `.allhands-sync-config.json` if present. CLI flags (`--include`, `--exclude`) take precedence over config values. This allows repositories to persist their push customization in version control while still supporting one-off overrides.
+
+## Prerequisite Checks
+
+[ref:src/commands/push.ts:checkPrerequisites:e7d51e3] validates four conditions before any work begins:
+
+| Check | Failure |
+|---|---|
+| `gh` CLI installed | [ref:src/lib/gh.ts:checkGhInstalled:64ba656] |
+| `gh` authenticated | [ref:src/lib/gh.ts:checkGhAuth:64ba656] |
+| Current directory is a git repo | [ref:src/lib/git.ts:isGitRepo:70a743c] |
+| GitHub username resolvable | [ref:src/lib/gh.ts:getGhUser:64ba656] |
+
+## Fork Readiness Polling
+
+[ref:src/commands/push.ts:waitForFork:e7d51e3] handles GitHub's async fork creation by polling the fork's existence via the gh API every 2 seconds for up to 30 seconds (15 attempts). This avoids race conditions where the CLI tries to clone a fork that hasn't propagated yet.
+
+## Branch Naming Convention
+
+Branches are created as `contrib/<github-user>/<timestamp>`, ensuring uniqueness across multiple pushes from the same user without collision. The branch is based on `upstream/main` regardless of the fork's default branch state.
+
+## Temp Directory Lifecycle
+
+The entire git operation (clone, branch, copy, commit, push) happens in a temp directory under `os.tmpdir()`. The directory is cleaned up in a `finally` block via [ref:src/commands/push.ts:createPullRequest:e7d51e3], ensuring no orphaned clones accumulate even on failure.

package/docs/sync-cli/commands/sync-command.md

@@ -0,0 +1,71 @@
+---
+description: "Sync command that initializes or updates the allhands framework in a target repository, handling conflict resolution, dotfile restoration, target-line injection, and ah CLI shim installation"
+---
+
+# Sync Command
+
+The sync command is the primary distribution mechanism. It copies distributable files from the allhands package source into a target repository, detecting whether this is a first-time initialization or an incremental update, and handling conflicts accordingly.
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> ResolveTarget
+    ResolveTarget --> DetectMode: target exists
+    ResolveTarget --> Error: target missing
+    DetectMode --> FirstTimeInit: no .allhands/ dir
+    DetectMode --> IncrementalUpdate: .allhands/ exists
+
+    FirstTimeInit --> CopyFiles
+
+    IncrementalUpdate --> StagedCheck
+    StagedCheck --> Error: staged conflicts in managed files
+    StagedCheck --> DetectConflicts: no staged conflicts
+    DetectConflicts --> AskResolution: conflicts found
+    DetectConflicts --> CopyFiles: no conflicts
+    AskResolution --> CreateBackups: user picks backup
+    AskResolution --> CopyFiles: user picks overwrite
+    AskResolution --> Abort: user cancels
+
+    CopyFiles --> RestoreDotfiles
+    RestoreDotfiles --> HandleDeletedFiles: update mode
+    RestoreDotfiles --> SyncTargetLines: init mode
+    HandleDeletedFiles --> SyncTargetLines
+    SyncTargetLines --> CopyEnvExamples
+    CopyEnvExamples --> SetupShim: init mode
+    CopyEnvExamples --> Done: update mode
+    SetupShim --> Done
+    Done --> [*]
+```
+
+## Conflict Resolution Strategy
+
+[ref:src/commands/sync.ts:cmdSync:ca521c9] employs a two-phase conflict detection approach:
+
+1. **Staged file guard** -- Before any file operations, checks if the target repo has staged git changes that overlap with managed files. This prevents the sync from silently overwriting work the user intends to commit. Uses [ref:src/lib/manifest.ts:Manifest:e06b487] to determine the managed file set and [ref:src/lib/git.ts:getStagedFiles:70a743c] to detect staging conflicts.
+
+2. **Content-level diff** -- Iterates all distributable files and uses [ref:src/lib/manifest.ts:filesAreDifferent:e06b487] (byte-level comparison) to identify files that differ between source and target. The user is then presented with three options via [ref:src/lib/ui.ts:askConflictResolution:6374626]:
+
+| Resolution | Behavior |
+|---|---|
+| **Backup** | Creates `file.backup_N.ext` via [ref:src/lib/ui.ts:getNextBackupPath:6374626], then overwrites |
+| **Overwrite** | Replaces target files directly (local changes lost) |
+| **Cancel** | Aborts with no changes made |
+
+The `--yes` flag forces overwrite mode, skipping all interactive prompts.
+
+## Post-Copy Processing
+
+After file copying, three post-processing steps run in sequence:
+
+- **Dotfile restoration** -- [ref:src/lib/dotfiles.ts:restoreDotfiles:8d2662f] renames npm-safe names back to dotfiles (e.g., `gitignore` to `.gitignore`). This is necessary because npm strips dotfiles during package publishing.
+- **Target-line injection** -- [ref:src/lib/target-lines.ts:ensureTargetLines:c2f18b9] appends required lines to target-repo files (like `.gitignore`, `CLAUDE.md`, `.tldrignore`) without duplicating existing entries.
+- **Deleted file cleanup** (update only) -- Detects files that exist in the target but were removed from the source, prompting the user to delete them.
+
+## The `ah` CLI Shim
+
+On first-time init, [ref:src/commands/sync.ts:setupAhShim:ca521c9] installs a bash shim to `~/.local/bin/ah`. The shim walks up the directory tree from `$PWD` looking for `.allhands/harness/ah`, enabling project-local `ah` invocation from anywhere within a synced repository. It warns if `~/.local/bin` is not in `PATH`.
+
+## Full Replace Alternative
+
+[ref:src/lib/full-replace.ts:fullReplace:827a9fa] provides a wholesale directory replacement strategy as an alternative to the file-by-file approach in `cmdSync`. It backs up entire `.allhands` and `.claude` directories with timestamped names via [ref:src/lib/full-replace.ts:getBackupDirName:827a9fa], then restores preserved items (like `node_modules` and `settings.local.json`) from the backup. [ref:src/lib/full-replace.ts:checkPreservedFiles:827a9fa] identifies root-level files that should never be overwritten (`.env`, `.env.ai`, `.env.local`).

package/docs/sync-cli/systems/README.md

@@ -0,0 +1,14 @@
+---
+description: "Index of sync CLI shared system documentation covering manifest/distribution, git/GitHub integration, path resolution, and interactive UI."
+---
+
+# Sync CLI Systems
+
+Shared libraries used across sync CLI commands.
+
+| System | Purpose | Doc |
+|---|---|---|
+| Manifest & distribution | File classification (distributable, internal, gitignored) | `docs/sync-cli/systems/manifest-and-distribution.md` |
+| Git & GitHub integration | Structured wrappers for git and gh CLI operations | `docs/sync-cli/systems/git-and-github-integration.md` |
+| Path resolution | Allhands root discovery via env var or package-relative lookup | `docs/sync-cli/systems/path-resolution.md` |
+| Interactive UI | Terminal prompts, conflict resolution, backup path generation | `docs/sync-cli/systems/interactive-ui.md` |

package/docs/sync-cli/systems/git-and-github-integration.md

@@ -0,0 +1,49 @@
+---
+description: "Git and GitHub CLI wrapper layers that provide structured result types for repo detection, file listing, authentication checks, and API calls"
+---
+
+# Git and GitHub Integration
+
+The sync-cli wraps both `git` and `gh` (GitHub CLI) behind thin abstraction layers that normalize output into structured result types. These wrappers are consumed across all three commands.
+
+## Result Type Convention
+
+Both [ref:src/lib/git.ts:git:70a743c] and [ref:src/lib/gh.ts:gh:64ba656] return the same shape:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `success` | `boolean` | Exit code === 0 |
+| `stdout` | `string` | Trimmed stdout |
+| `stderr` | `string` | Trimmed stderr |
+
+Both use `spawnSync` (not `execSync`) for structured access to exit codes and stderr without try/catch. The 10MB max buffer accommodates large repos with many files.
+
+## Git Operations
+
+[ref:src/lib/git.ts::70a743c] exposes four capabilities:
+
+| Function | Used By | Purpose |
+|---|---|---|
+| [ref:src/lib/git.ts:checkGitInstalled:70a743c] | CLI entrypoint | Pre-flight: is `git` available? |
+| [ref:src/lib/git.ts:isGitRepo:70a743c] | sync, push, pull-manifest | Guards commands that require a repo context |
+| [ref:src/lib/git.ts:getStagedFiles:70a743c] | sync | Detects staged changes that would conflict with sync |
+| [ref:src/lib/git.ts:getGitFiles:70a743c] | push | Lists tracked + untracked-but-not-ignored files |
+
+[ref:src/lib/git.ts:getGitFiles:70a743c] combines `git ls-files` (tracked) with `git ls-files --others --exclude-standard` (untracked, not ignored) to produce a complete view of files the user's repo considers relevant. This is critical for the push command's gitignore-respecting file collection.
+
+## GitHub CLI Operations
+
+[ref:src/lib/gh.ts::64ba656] provides authentication and identity primitives:
+
+| Function | Used By | Purpose |
+|---|---|---|
+| [ref:src/lib/gh.ts:checkGhInstalled:64ba656] | push | Pre-flight: is `gh` available? |
+| [ref:src/lib/gh.ts:checkGhAuth:64ba656] | push | Is the user authenticated with GitHub? |
+| [ref:src/lib/gh.ts:getGhUser:64ba656] | push | Resolves the authenticated GitHub username |
+| [ref:src/lib/gh.ts:gh:64ba656] | push (fork, clone, PR) | General-purpose gh command runner |
+
+The push command is the sole consumer of the gh layer -- sync and pull-manifest only need local git operations.
+
+## Design Trade-off: Synchronous Execution
+
+Both wrappers use `spawnSync` (blocking). This simplifies control flow throughout the CLI since commands execute sequentially. The trade-off is that long-running git operations (like cloning in the push command) block the event loop, but this is acceptable for a CLI tool where the user is waiting for completion anyway.

package/docs/sync-cli/systems/interactive-ui.md

@@ -0,0 +1,43 @@
+---
+description: "Terminal prompt utilities for yes/no confirmation, conflict resolution menus, free-text questions, and incrementing backup path generation"
+---
+
+# Interactive UI
+
+[ref:src/lib/ui.ts::6374626] provides the interactive terminal layer for the sync-cli. It wraps Node's `readline` interface into purpose-built prompt functions used across the sync and push commands.
+
+## Prompt Functions
+
+| Function | Returns | Used By |
+|---|---|---|
+| [ref:src/lib/ui.ts:askQuestion:6374626] | `string` | push (PR title) |
+| [ref:src/lib/ui.ts:confirm:6374626] | `boolean` | sync (continue, delete), push (create PR) |
+| [ref:src/lib/ui.ts:askConflictResolution:6374626] | `ConflictResolution` | sync (conflict handling) |
+
+Each function creates and closes its own `readline.Interface` instance. This avoids keeping a persistent readline open, which would interfere with process exit.
+
+## Conflict Resolution Menu
+
+[ref:src/lib/ui.ts:askConflictResolution:6374626] presents a three-option menu when the sync command detects files that differ between source and target:
+
+- **`b` (backup)** -- Create numbered backup files before overwriting
+- **`o` (overwrite)** -- Replace directly, losing local changes
+- **`c` (cancel)** -- Abort the entire sync with no changes
+
+The menu loops on invalid input, requiring an explicit valid choice. This is the only multi-option prompt in the CLI -- all other interactions are simple yes/no via [ref:src/lib/ui.ts:confirm:6374626].
+
+## Backup Path Generation
+
+[ref:src/lib/ui.ts:getNextBackupPath:6374626] generates non-colliding backup filenames using an incrementing counter:
+
+```
+original.ts -> original.backup_1.ts
+             -> original.backup_2.ts
+             -> original.backup_3.ts
+```
+
+It scans the directory for existing backup files matching the pattern `<base>.backup_<N><ext>` and selects `N+1`. The regex is built with escaped characters from the original filename to avoid glob injection from filenames containing special characters.
+
+## Design Choice: No Persistent State
+
+The UI module is stateless -- no prompt history, no saved preferences. The `--yes` flag on sync and the `--title`/`--body` flags on push bypass interactive prompts entirely, enabling non-interactive CI usage. This separation means the UI layer is purely a human interface concern that can be skipped wholesale in automation.