all-hands-cli 0.1.0

package/docs/sync-cli/systems/manifest-and-distribution.md

@@ -0,0 +1,51 @@
+---
+description: "Manifest system that classifies allhands files as distributable, internal, or gitignored to control what gets synced to target repositories"
+---
+
+# Manifest and Distribution System
+
+The manifest system is the gatekeeper for file distribution. Every file in the allhands source is classified into one of three categories, and only distributable files flow to target repositories.
+
+## File Classification
+
+```mermaid
+flowchart TD
+    F[File in allhands root] --> G{gitignored?}
+    G -- Yes --> X1[Excluded: gitignored]
+    G -- No --> I{internal?}
+    I -- Yes --> X2[Excluded: internal-only]
+    I -- No --> D[Distributable]
+```
+
+[ref:src/lib/manifest.ts:Manifest:e06b487] loads two data sources at construction:
+- **`.internal.json`** -- Lists glob patterns for internal-only files (not shipped to consumers)
+- **`.gitignore` files** -- Parsed by [ref:src/lib/gitignore.ts:GitignoreFilter:0ee79f8] across the full directory tree
+
+A file is distributable if and only if it passes both checks: `!isInternal(path) && !isGitignored(path)`.
+
+## Gitignore Parsing
+
+The gitignore system replicates git's own ignore semantics rather than shelling out to `git check-ignore`. This was a deliberate choice -- the allhands root may not itself be a git repository (e.g., when running from an npm package).
+
+[ref:src/lib/gitignore.ts:parseGitignoreFile:0ee79f8] handles:
+- Comment lines (`#`) and blank lines
+- Negation patterns (`!pattern`)
+- Directory-scoped patterns (trailing `/`)
+- Root-relative patterns (leading `/`)
+- Level-agnostic patterns (no slash -- matches at any depth via `**/` prefix)
+
+[ref:src/lib/gitignore.ts:matchesPattern:0ee79f8] resolves each rule relative to the `.gitignore` file's directory, matching git's behavior where nested `.gitignore` files scope their rules to their own subtree.
+
+[ref:src/lib/gitignore.ts:GitignoreFilter:0ee79f8] walks the entire directory tree, loading every `.gitignore` it encounters. The last-match-wins evaluation order mirrors git's precedence rules, with negation patterns able to re-include previously ignored paths.
+
+## Byte-Level Comparison
+
+[ref:src/lib/manifest.ts:filesAreDifferent:e06b487] performs an optimized two-step comparison:
+1. **Size check** -- If file sizes differ, return `true` immediately (no I/O beyond stat)
+2. **Content check** -- Full buffer comparison via `Buffer.equals`
+
+This avoids timestamp-based false positives that would trigger unnecessary conflict resolution during sync.
+
+## Directory Walking
+
+[ref:src/lib/fs-utils.ts:walkDir:3041b62] provides the recursive traversal used by both the gitignore filter and dotfile restoration. It skips `.git` and `node_modules` directories -- these are never relevant for distribution or ignore-rule collection.

package/docs/sync-cli/systems/path-resolution.md

@@ -0,0 +1,42 @@
+---
+description: "Allhands root path resolution that discovers the package source directory via ALLHANDS_PATH env var or import.meta.url-based package-relative traversal"
+---
+
+# Path Resolution
+
+[ref:src/lib/paths.ts:getAllhandsRoot:696872e] is the single function responsible for answering: "where are the allhands source files?" Every command depends on this answer to locate the manifest, distributable files, and configuration.
+
+## Resolution Strategy
+
+```mermaid
+flowchart TD
+    A[getAllhandsRoot called] --> B{ALLHANDS_PATH env set?}
+    B -- Yes --> C{resolved path has .internal.json?}
+    C -- Yes --> D[Return env path]
+    C -- No --> E[Fall through to package discovery]
+    B -- No --> E
+    E --> F{__dirname/.. has .internal.json?}
+    F -- Yes --> G[Return parent of bin/]
+    F -- No --> H{__dirname/../.. has .internal.json?}
+    H -- Yes --> I[Return grandparent]
+    H -- No --> J[Throw Error]
+```
+
+## Two Discovery Modes
+
+| Mode | When | How |
+|---|---|---|
+| **Env var** | Local development, testing | `ALLHANDS_PATH` points directly to the repo root |
+| **Package-relative** | Production (`npx` usage) | Walks up from the bundled `bin/cli.js` location |
+
+The `.internal.json` file serves as a sentinel -- its presence confirms the directory is a valid allhands root. This avoids false positives from similarly-named directories.
+
+## Package-Relative Traversal
+
+After esbuild bundles the CLI into `bin/cli.js`, the runtime `import.meta.url` resolves to that file's location. The function tries two levels of parent traversal:
+- One level up: handles `bin/cli.js` -> package root
+- Two levels up: handles `dist/lib/paths.js` -> package root (unbundled development)
+
+## Upstream Constants
+
+[ref:src/lib/paths.ts:UPSTREAM_REPO:696872e] and [ref:src/lib/paths.ts:UPSTREAM_OWNER:696872e] define the canonical upstream repository coordinates. These are used exclusively by the push command for fork and PR operations. Hardcoding them (rather than reading from git remotes) ensures push always targets the correct upstream regardless of the user's remote configuration.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "all-hands-cli",
+  "version": "0.1.0",
+  "description": "Agentic harness for model-first software development",
+  "type": "module",
+  "bin": {
+    "all-hands": "./bin/sync-cli.js",
+    "allhands": "./bin/sync-cli.js"
+  },
+  "scripts": {
+    "build": "esbuild src/sync-cli.ts --bundle --platform=node --target=node18 --outfile=bin/sync-cli.js --format=esm --banner:js=\"#!/usr/bin/env node\"",
+    "dev": "npm run build -- --watch",
+    "prepublishOnly": "npm run build",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "claude",
+    "agents",
+    "agentic",
+    "harness",
+    "sync-cli"
+  ],
+  "author": "kalem-edlin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kalem-edlin/all-hands-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/yargs": "^17.0.32",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.3.0"
+  },
+  "dependencies": {
+    "minimatch": "^10.0.1",
+    "yargs": "^17.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install-shim.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Install the ah shim to ~/.local/bin
+# Run this during local development to set up the ah command
+
+set -e
+
+SHIM_DIR="$HOME/.local/bin"
+SHIM_PATH="$SHIM_DIR/ah"
+
+mkdir -p "$SHIM_DIR"
+
+cat > "$SHIM_PATH" << 'EOF'
+#!/bin/bash
+# AllHands CLI shim - finds and executes project-local .allhands/ah
+# Installed by: npx all-hands init
+
+dir="$PWD"
+while [ "$dir" != "/" ]; do
+  if [ -x "$dir/.allhands/ah" ]; then
+    exec "$dir/.allhands/ah" "$@"
+  fi
+  dir="$(dirname "$dir")"
+done
+
+echo "error: not in an all-hands project (no .allhands/ah found)" >&2
+echo "hint: run 'npx all-hands init .' to initialize this project" >&2
+exit 1
+EOF
+
+chmod +x "$SHIM_PATH"
+
+echo "Installed: $SHIM_PATH"
+
+# Check if in PATH
+if [[ ":$PATH:" != *":$SHIM_DIR:"* ]]; then
+  echo ""
+  echo "⚠️  $SHIM_DIR is not in your PATH"
+  echo "Add this to your ~/.zshrc or ~/.bashrc:"
+  echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
+fi

package/scripts/pre-pack.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Pre-pack script: Rename dotfiles that npm hardcode-excludes
+# Run this in CI before `npm pack`
+# Only targets .claude/ directory (what we distribute)
+
+set -e
+
+DOTFILES=(".gitignore" ".npmrc" ".npmignore")
+
+for dotfile in "${DOTFILES[@]}"; do
+  nodot="${dotfile#.}"
+
+  # Only rename within .claude/, excluding node_modules
+  # Use /usr/bin/find to avoid fd alias
+  /usr/bin/find .claude -name "$dotfile" \
+    -not -path "*/node_modules/*" \
+    -type f | while read -r file; do
+    dir=$(dirname "$file")
+    newname="$dir/$nodot"
+    echo "Renaming: $file -> $newname"
+    mv "$file" "$newname"
+  done
+done
+
+echo "Pre-pack dotfile rename complete"

package/specs/harness-maintenance-skill.spec.md

@@ -0,0 +1,138 @@
+---
+name: harness-maintenance-skill
+domain_name: infrastructure
+type: refactor
+status: completed
+dependencies: []
+branch: refactor/harness-maintenance-skill
+---
+
+# Harness Maintenance Skill Restructure
+
+## Motivation
+
+The harness-maintenance skill currently serves as an architecture reference document — it describes the system but doesn't effectively guide agents through specific maintenance scenarios. Per **Knowledge Compounding**, maintenance knowledge needs to compound into every harness modification, not just exist as a passive reference.
+
+The current state:
+- The skill's SKILL.md is a monolithic reference doc (~375 lines) covering everything from TUI lifecycle to hook categories
+- There are no reference subdocs — all knowledge lives in one file, violating **Context is Precious**
+- Skill discovery is enumeration-only (`ah skills list`), so agents match via reasoning alone
+- The existing `WRITING_HARNESS_FLOWS.md` shared flow contains valuable flow-authoring knowledge but is disconnected from the skill system
+- `CREATE_VALIDATION_TOOLING_SPEC.md` contains validation suite creation knowledge that should be accessible as a reference, not only as a flow
+- No flows exist for other maintenance domains (commands, hooks, MCP, orchestration, skills, knowledge/compounding)
+
+Engineer desires a **hub-and-spoke model**: SKILL.md routes to domain-specific reference docs based on the maintenance scenario, with first principles and architectural invariants always front-loaded. Corresponding thin flows in `flows/harness/` serve as execution entry points that discover the skill automatically.
+
+## Goals
+
+### 1. Restructure the harness-maintenance skill directory
+
+Engineer expects the skill to follow this structure:
+
+```
+skills/harness-maintenance/
+  SKILL.md                          # Hub: principles, invariants, routing table
+  references/
+    writing-flows.md                # Flow authoring best practices
+    tools-commands-mcp-hooks.md     # Extending CLI capability surface
+    core-architecture.md            # TUI, event loop, orchestration, prompt types, emergent
+    harness-skills.md               # Creating and maintaining skills
+    validation-tooling.md           # Creating validation suites and tooling specs
+    knowledge-compounding.md        # Docs, knowledge indexes, solutions, memories
+```
+
+### 2. Restructure SKILL.md as a routing hub
+
+Engineer expects SKILL.md to contain:
+- Linked references to `.allhands/principles.md` and core pillar documents so they are always considered
+- Architectural invariants that apply across all maintenance scenarios (concise, not exhaustive)
+- A reference routing table mapping maintenance scenarios to specific reference docs
+
+Engineer desires concise full coverage — no missed principles, but no bloat. The SKILL.md should be easy to maintain itself. Per **Context is Precious**, agents should only load the reference they need, not all of them.
+
+### 3. Create reference docs with domain-specific knowledge
+
+Each reference doc should provide:
+- The core principles most relevant to that domain
+- Concise full coverage of the domain's use cases, conventions, and patterns
+- Grounded in codebase reality (file paths, schema fields, command examples)
+- Easy to maintain — structured so updates are localized
+
+Content sources:
+- `writing-flows.md`: Migrate knowledge from current `WRITING_HARNESS_FLOWS.md` (the flow file remains but becomes thin)
+- `tools-commands-mcp-hooks.md`: Extract from current SKILL.md sections on hooks, commands, and extension points. These are adjacent enough to share one reference since they all follow the auto-discovery pattern.
+- `core-architecture.md`: Extract from current SKILL.md sections on TUI, event loop, agent profiles, schemas, hypothesis domains. Should capture both the architectural map (how things connect) and invariants (what must be preserved).
+- `harness-skills.md`: New content covering the skill schema, directory conventions, discovery mechanism, and when/how to create new skills
+- `validation-tooling.md`: Migrate knowledge from `CREATE_VALIDATION_TOOLING_SPEC.md` (research, tool validation, suite writing philosophy, evidence capture patterns)
+- `knowledge-compounding.md`: New content covering documentation schema, knowledge indexes, solutions, memories, and the compounding principles for maintaining these
+
+### 4. Create thin flows in `flows/harness/`
+
+Each flow serves as an execution entry point for a specific maintenance domain:
+
+```
+flows/harness/
+  WRITING_HARNESS_FLOWS.md
+  WRITING_HARNESS_TOOLS.md
+  WRITING_HARNESS_ORCHESTRATION.md
+  WRITING_HARNESS_SKILLS.md
+  WRITING_HARNESS_VALIDATION_TOOLING.md
+  WRITING_HARNESS_KNOWLEDGE.md
+```
+
+Engineer expects each flow to be thin — its primary step is skill discovery via `ah skills` which routes to the correct reference. The flow provides the execution context (inputs, outputs, constraints), the skill reference provides the knowledge. This ensures the skill gets automatically loaded when agents enter any harness maintenance flow.
+
+### 5. Migrate existing flow content
+
+- `flows/shared/WRITING_HARNESS_FLOWS.md`: Deep knowledge moves to `references/writing-flows.md`. The flow becomes a thin entry point that discovers the skill. The existing CLAUDE.md reference to this file continues to work.
+- `flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md`: Research, tool validation, suite writing philosophy, and evidence capture knowledge moves to `references/validation-tooling.md`. Execution steps (spec creation, engineer interview, handoff) stay in the flow or move to the new `WRITING_HARNESS_VALIDATION_TOOLING.md`.
+
+## Non-Goals
+
+- Changing the skill schema itself (no new required frontmatter fields, no `tools` field). Schema improvements are a separate concern.
+- Adding programmatic skill matching (`ah skills match`, `ah skills search`). Discovery improvements are out of scope.
+- Bridging All Hands skills with Claude Code native skill features. That divergence is a separate architectural decision.
+- Creating new validation suites or other non-maintenance skills. This milestone is about the maintenance skill only.
+- Modifying the harness TypeScript source code. This is a content and organization change.
+
+## Open Questions
+
+- **Reference doc density calibration**: The validation-suite schema mandates 5 structured sections. Should reference docs follow a similar required-sections pattern, or stay flexible per **Frontier Models are Capable**? Architect should determine the right structure that balances maintainability with coverage.
+- **CLAUDE.md routing update**: Currently CLAUDE.md points directly to `WRITING_HARNESS_FLOWS.md` in `flows/shared/`. Should this be updated to point to the new `flows/harness/WRITING_HARNESS_FLOWS.md`, or should the shared flow remain as a redirect? Architect should decide based on how other CLAUDE.md references work.
+- **Existing SKILL.md content disposition**: The current SKILL.md has ~375 lines of architecture reference. Some of this maps cleanly to specific reference docs, but some cross-cuts (e.g., "Key Design Patterns" applies to multiple domains). Architect should decide how to decompose cross-cutting content — duplicate where relevant, or keep a minimal cross-cutting section in SKILL.md.
+- **Flow location**: Engineer specified `flows/harness/` as the subdirectory. Existing convention uses `flows/shared/` for progressively disclosed flows with `<inputs>`/`<outputs>` tags. Architect should determine whether `flows/harness/` is a new convention or should follow `flows/shared/harness/`.
+
+## Technical Considerations
+
+- The existing `WRITING_HARNESS_FLOWS.md` is referenced in `CLAUDE.md` which is loaded at conversation start for every agent. Any path change must update that reference.
+- Skill glob patterns in the current SKILL.md frontmatter already cover all `.allhands/` subdirectories. The restructured skill should maintain the same glob coverage so discovery still works for any harness file modification.
+- The `ah schema skill` command defines minimal frontmatter (`name`, `description`, `globs`, optional `version`). The `references/` subdirectory pattern is a convention, not schema-enforced — the spec should establish clear conventions for reference doc naming and structure.
+- `CREATE_VALIDATION_TOOLING_SPEC.md` is currently referenced by `ASSESS_VALIDATION_TOOLING.md` flow. This reference chain must be preserved or updated during migration.
+- The skill currently has `version: 1.0.0`. This restructure should bump to `2.0.0` to signal the architectural change in how maintenance knowledge is organized.
+
+## Implementation Reality
+
+### What Was Implemented
+
+All 5 spec goals were achieved across 14 prompts (3 planned, 5 emergent, 5 review-fix, 1 user-patch):
+
+- **Goal 1 (Skill directory restructure)**: SKILL.md decomposed from 375 lines to 61-line routing hub + 6 domain-specific reference docs in `references/`. Version bumped to 2.0.0. Knowledge audit confirmed 95.7% preservation (45/47 units), 2 intentionally omitted.
+- **Goal 2 (SKILL.md as routing hub)**: Single merged routing table with scenario and trigger columns. Principles reference, cross-cutting patterns, maintainer checklist, and cross-skill disambiguation all in hub.
+- **Goal 3 (Reference docs)**: All 6 created with domain-specific content, cross-domain navigation footers, and flexible per-domain structure.
+- **Goal 4 (Thin flows)**: All 6 flows created at 27 lines each in `flows/harness/`. Identical structural pattern with domain-specific `<goal>` principle citations.
+- **Goal 5 (Flow migration)**: CLAUDE.md updated to reference skill directly (not a flow). `flows/shared/WRITING_HARNESS_FLOWS.md` thinned to 11-line redirect. `CREATE_VALIDATION_TOOLING_SPEC.md` deep knowledge migrated to skill reference.
+
+### How Engineer Desires Evolved
+
+- **CLAUDE.md routing**: Engineer chose to reference the skill itself rather than a specific flow — a more fundamental routing change than the spec anticipated. CLAUDE.md scope also broadened from `flows/` to all `.allhands/` files.
+- **[ref:] anchors rejected**: Emergent prompt 04 added code reference anchors to ground docs in source. Engineer directed removal (prompt 12) because `ah docs validate`/`finalize` are scoped to `docs/` only — anchors in skill references silently go stale.
+- **Audit artifacts rejected**: Knowledge completeness audit (prompt 06) was valuable as a process but engineer directed removal of the embedded HTML comment artifact from SKILL.md — stale metadata violates Context is Precious.
+- **Consolidated routing**: Engineer preferred merging duplicate routing tables (Reference Routing + Maintenance Triggers) into a single table rather than maintaining parallel routing structures.
+- **Naming consistency**: `harness_skills.md` (snake_case) renamed to `harness-skills.md` (kebab-case) — flagged independently by 3 jury reviewers.
+
+### Key Technical Decisions
+
+- **Hub-and-spoke with single hub table**: One routing table serves both scenario-based routing ("I'm working on flows") and change-based routing ("I changed a hook") via dual columns.
+- **Cross-skill disambiguation**: Explicit Related Skills section resolves glob overlap between harness-maintenance and claude-code-patterns skills.
+- **Scope guard for docs tooling**: Maintainer checklist explicitly prohibits `ah docs validate`/`finalize` on skill references.
+- **Redirect flow preserved**: `flows/shared/WRITING_HARNESS_FLOWS.md` kept as 11-line redirect distinguishing knowledge source (skill reference) from execution source (harness flow).

package/specs/roadmap/git-spec-lifecycle-management.spec.md

@@ -0,0 +1,113 @@
+---
+name: git-spec-lifecycle-management
+domain_name: infrastructure
+type: milestone
+status: roadmap
+dependencies: []
+branch: feature/git-spec-lifecycle-management
+initial_workflow_domain: milestone
+---
+
+## Motivation
+
+Git lifecycle management is the harness's primary pain point. The current implementation is fragile, inconsistent, and too complex. The CLI and TUI disagree on completion behavior (CLI moves specs to `specs/`, TUI moves to `specs/completed/`). There are zero `git fetch` or `git pull` operations anywhere in the codebase, so branches start stale and stay stale. The `switch-spec` action has no uncommitted changes guard. The `mark-completed` action runs destructive `git checkout -- . && git clean -fd` automatically — even if the preceding commit failed. `commitFilesToBranch` uses temp worktree tricks that introduce race conditions. `ah specs persist` bundles two distinct concerns (commit spec to main + create feature branch) into one command. Multiple worktrees create ambiguity about where a spec is actively being worked on, with no cross-worktree detection.
+
+The engineer desires a model where the harness performs minimal, predictable git operations and the developer is responsible for being in the right state. Zero git errors from the harness. A mental model that fits on an index card.
+
+## Goals
+
+### Guiding Principles
+
+1. **Developer preparedness over harness magic** — the harness does minimal, predictable git ops. The developer is responsible for being in the right state (on main, conflicts resolved).
+2. **Forward-only lifecycle** — specs move from roadmap to completed. No resurrection, no clearing, no going backwards.
+3. **Sync at critical junctures** — remote main is pulled at activation, PR creation, and completion. Not continuously, not silently.
+4. **Errors are signals, not failures** — merge conflicts surface to the user (TUI modal or CLI error for agents). The system doesn't try to be clever about resolution yet.
+5. **Kill what's unnecessary** — if it adds complexity without value, it goes.
+
+### Spec Creation
+
+- Engineer expects to be on the base branch (main) when creating specs. The harness enforces this — error if not on main.
+- The spec file is written to `specs/roadmap/{name}.spec.md`, committed directly on main, and pushed to remote main.
+- Only the newly added spec file is committed and pushed — not a blanket push of main.
+- Spec creation no longer creates a feature branch. Branch creation happens at activation time.
+
+### Spec Activation (Switching To)
+
+- Activation pulls `origin main` first.
+- If the spec's feature branch does not exist, it is created from the updated main.
+- If the spec's feature branch already exists, main is merged into it to keep it current.
+- If merge conflicts arise, the error is propagated: TUI shows a blocking warning modal describing the conflicts; CLI returns an error for agents to handle autonomously.
+- Before activating, the harness checks all local git worktrees for an existing `.planning/` directory corresponding to this spec.
+  - If found in another worktree: TUI shows a warning modal with the worktree path, suggesting the user switch to that directory. CLI returns an error with the path for agents to handle.
+  - If not found elsewhere: proceeds with activation, creating `.planning/` in the current project if needed.
+- The developer is checked out onto the feature branch after successful activation.
+
+### Spec Completion
+
+- Pulls `origin main` into the current feature branch.
+- If merge conflicts exist: surfaces the conflicts to the user (TUI modal / CLI error) and aborts. The user must resolve conflicts and push to remote themselves, then retry completion.
+- If no conflicts: moves the spec file from `specs/roadmap/{name}.spec.md` to `specs/{name}.spec.md` on the feature branch, updates frontmatter `status` to `completed`, commits, and pushes to remote.
+- Assumes the feature branch will be merged back to main via PR, at which point main reflects the spec's completed status and all dependent branches see it.
+- Engineer expects that no branch cleanup or `.planning/` cleanup occurs — that is the developer's responsibility.
+
+### Ideation on Active Milestone
+
+- When ideation detects a current milestone is selected (on a feature branch with an active spec), it enters a mode that builds upon the existing spec.
+- The existing spec file is revised/appended with new ideation content.
+- Any existing planning content (alignment docs, prompts) is treated as stale — the planner re-plans from the updated spec on the next planning run.
+
+### Removals
+
+- **Kill `specs/completed/` directory** — two directories only: `specs/roadmap/` for planned, `specs/` for completed. `loadAllSpecs` category logic simplifies accordingly.
+- **Kill `ah specs persist` as a standalone command** — its responsibilities are split between creation (commit + push to main) and activation (branch creation + checkout + sync).
+- **Kill `commitFilesToBranch`** — no more temp worktree commit tricks. Spec creation is a direct commit on main.
+- **Kill `ah specs resurrect`** — specs move forward only. Once completed, they're done.
+- **Kill TUI `clear-spec` action** — no deactivation concept. Developer manually checks out main if needed.
+- **Kill destructive auto-cleanup** — no `git checkout -- . && git clean -fd` on completion. No `git stash` tricks.
+
+## Technical Considerations
+
+### Current Git Audit Findings (Grounded in Codebase Exploration)
+
+- **Zero `git fetch`/`git pull` in the entire codebase** — the harness only pushes, never syncs from remote. This is a root cause of stale branches.
+- **Raw `execSync` with string interpolation** — all git commands use unescaped string interpolation. Branch names from spec frontmatter could break commands. Shell escaping approach is an open question for the planner.
+- **`hasUncommittedChanges` returns false on git failure** (`git.ts:155`) — if git itself fails, the function claims no uncommitted changes, potentially enabling destructive operations. This false-negative pattern needs fixing.
+- **`switch-spec` has no uncommitted changes guard** — unlike other TUI actions, it does `git checkout` without checking dirty state first.
+- **TUI `mark-completed` runs `git add -A specs/`** — stages all changes under `specs/`, not just the moved file. The new model should stage only the specific file.
+- **Stash pop order bug in compaction.ts** — stashes files in forward order but pops LIFO, causing incorrect restoration order. Tangential to this milestone but worth noting.
+- **No command injection protection** — branch names, spec IDs, and file paths are interpolated directly into shell commands without escaping.
+
+### Remote Sync Points
+
+The new model introduces `git fetch`/`git pull` at three junctures:
+1. **Activation** — pull origin main into the feature branch
+2. **PR creation** — pull origin main into the feature branch (Assuming PR submission workflow exists)
+3. **Completion** — pull origin main into the feature branch, abort on conflicts
+
+### Directory Structure Simplification
+
+Current (three directories with confused semantics):
+```
+specs/roadmap/   -> planned specs
+specs/           -> ambiguous (CLI completion target)
+specs/completed/ -> TUI completion target
+```
+
+New (two directories with clear semantics):
+```
+specs/roadmap/   -> planned/in-progress specs
+specs/           -> completed specs
+```
+
+### Conflict Resolution (Future TODO)
+
+Engineer desires future agentic conflict resolution (potentially using open-code SDK with task context). For this milestone, merge conflicts are surfaced to the developer via TUI modals or CLI errors. This is explicitly marked as a future capability, not in scope for this milestone.
+
+## Open Questions
+
+- What shell escaping approach should be used for git command arguments? (e.g., `shell-escape` library, argument arrays with `spawnSync`, or manual escaping)
+- Should the `git push` after spec creation be a `git push origin main` targeting just the spec commit, or a regular `git push`?
+- How should the TUI modal for worktree detection be structured? (blocking vs dismissible, what information to show beyond the worktree path)
+- When ideation revises an active spec, should it explicitly mark planning content as stale (e.g., a frontmatter flag), or does the planner infer staleness from spec file modification timestamps?
+- How does the removal of `persist` affect the `CREATE_SPEC.md` flow and any other flows that call it?
+- What happens if the developer is on main but main has uncommitted changes unrelated to the spec? Should spec creation refuse to commit, or only commit the spec file?

package/specs/sync-init-flag.spec.md

@@ -0,0 +1,117 @@
+---
+name: sync-init-flag
+domain_name: infrastructure
+type: milestone
+status: completed
+dependencies: []
+branch: feature/sync-init-flag
+---
+
+# Sync CLI `--init` Flag
+
+## Motivation
+
+The sync command currently treats all distributable files identically — every sync overwrites the target repo's copies. This works for harness internals (flows, agents, schemas) that should always match the source, but is destructive for files that target repos are expected to customize: project settings, hook configuration, validation suites, and non-core skills.
+
+Engineers syncing harness updates to a target repo lose their repo-specific `.allhands/settings.json`, `.claude/settings.json` (all hooks), `.tldr/config.json`, validation suites, and any custom skills. The only workaround is manual backup and restore after every sync.
+
+The harness needs a clean separation between "always ship" files (harness internals) and "init-only" files (target-repo-owned configuration seeded once as defaults).
+
+## Goals
+
+### 1. `--init` Flag on the `sync` Command
+
+Engineer expects a `--init` flag on the sync command (`src/commands/sync.ts`). Behavior:
+
+- **Without `--init`**: Init-only files are withheld from sync. Target repo customizations are preserved. This is the common-case operation.
+- **With `--init`**: Init-only files are included in sync, following the existing replace flow (conflict detection, backup, overwrite). This is for first-time setup or resetting to defaults.
+
+The `push` command never ships init-only files regardless of flags — PRs contain only always-shipped files.
+
+### 2. `.internal.json` Restructure
+
+Engineer expects `.internal.json` to move from a flat glob list to a two-key structure:
+
+```json
+{
+  "internal": ["src/**", "bin/**", "...existing patterns..."],
+  "initOnly": [
+    ".allhands/skills/**",
+    "!.allhands/skills/claude-code-patterns/**",
+    "!.allhands/skills/harness-maintenance/**",
+    ".allhands/validation/**",
+    ".allhands/settings.json",
+    ".allhands/docs.json",
+    ".tldr/config.json",
+    ".claude/settings.json"
+  ]
+}
+```
+
+Resolution logic:
+1. Matches `internal` → never ship
+2. Matches `initOnly` → ship only with `--init` on `sync`, never on `push`
+3. Everything else → always ship
+
+The `initOnly` list supports negation patterns (`!` prefix) to carve out exceptions. Skills use this: `.allhands/skills/**` makes all skills init-only, while `!.allhands/skills/claude-code-patterns/**` and `!.allhands/skills/harness-maintenance/**` exempt the two core skills so they always ship.
+
+New skills added to `.allhands/skills/` automatically become init-only without manual configuration.
+
+### 3. `docs.json` Moves to Init-Only
+
+Engineer expects `docs.json` to move from the `internal` list (never distributed) to the `initOnly` list. This means target repos receive it on first `--init` sync as a default, then own it independently. The existing JSON schema at `harness/src/schemas/docs.schema.json` is sufficient — no schema changes needed.
+
+### 4. Manifest System Updates
+
+The `Manifest` class (`src/lib/manifest.ts`) needs to understand the new `.internal.json` structure. Engineer expects:
+
+- Parsing of the two-key format with negation pattern support in `initOnly`
+- An API surface that distinguishes "not distributable" (internal), "init-only", and "always distributable"
+- The `push` command's `collectFilesToPush` uses the manifest to exclude both `internal` and `initOnly` files
+- The `sync` command conditionally includes `initOnly` files based on the `--init` flag
+
+### 5. Remove Dead `fullReplace` Code
+
+`src/lib/full-replace.ts` exports `fullReplace()` but it is not imported or called anywhere in the codebase. Engineer expects it removed as dead code cleanup.
+
+### 6. README Documentation
+
+Engineer expects the README to document the `--init` flag: its purpose, when to use it (first-time setup), and that regular syncs preserve target-repo configuration.
+
+## Non-Goals
+
+- **Auto-detection of first-time setup** — The sync command does not infer whether `--init` is needed. Documentation guides the engineer.
+- **Merge strategies for config files** — No partial merging of settings or hooks. Init-only files are all-or-nothing per the existing replace flow.
+- **Changes to the `pull-manifest` command** — The pull-manifest scaffolding is unaffected.
+- **New validation suites or skills** — This milestone establishes the init-only gate, not new content.
+
+## Open Questions
+
+- **Manifest class API design** — How should the Manifest class expose the init-only concept? Options include a new `isInitOnly(path)` method alongside `isDistributable(path)`, or a single method returning a tri-state (`internal | initOnly | distributable`). Architect should determine the cleanest API that serves both `sync` and `push` consumers.
+- **Negation pattern implementation** — The `initOnly` list needs gitignore-style negation. The codebase already uses `GitignoreFilter` (from `src/lib/gitignore.ts`) for gitignore parsing. Architect should determine whether to reuse that infrastructure or use a lighter pattern matcher for the `initOnly` patterns.
+- **Backward compatibility of `.internal.json`** — Existing consumer repos may have tooling that reads `.internal.json` as a flat array. Architect should assess whether a migration path is needed or if the restructure is safe given the file's internal-only nature.
+
+## Technical Considerations
+
+- The sync command (`src/commands/sync.ts`) currently calls `manifest.getDistributableFiles()` which returns all non-internal, non-gitignored files. The `--init` flag adds a conditional filter step on the returned set based on `initOnly` patterns.
+- The push command (`src/commands/push.ts`) uses `collectFilesToPush()` which already has a multi-stage filtering pipeline (distributable set → blocklist → include/exclude → gitignore → byte-diff). Adding `initOnly` exclusion is an additional filter stage.
+- `fullReplace` in `src/lib/full-replace.ts` is dead code — exported but never imported. Safe removal with no downstream impact.
+- The `GitignoreFilter` class in `src/lib/gitignore.ts` already handles glob pattern matching with the `ignore` npm package, which natively supports negation patterns. This may be reusable for `initOnly` pattern resolution.
+- `.internal.json` is itself listed in the `internal` array (self-referencing to prevent distribution). This must be preserved in the restructured format.
+
+## Implementation Reality
+
+**What was implemented**: All 6 goals delivered as specified. No deviations from the original plan.
+
+**Open Questions resolved**:
+- **Manifest API**: `isInitOnly(path)` method alongside existing `isDistributable()` — simpler two-method approach over tri-state, since consumers (sync/push) only need a boolean gate
+- **Negation patterns**: Standalone minimatch loop with last-match-wins semantics, not `GitignoreFilter` — appropriate for small, simple root-relative pattern set
+- **Backward compatibility**: Non-issue — `.internal.json` is in its own `internal` list and never distributed to consumer repos
+
+**Execution profile**: 4 planned prompts + 1 review-fix (Gemini Code Assist feedback to pre-compile minimatch patterns). All first-attempt. No emergent prompts, no reverts. Prompts 02/03 parallelized successfully after 01 completed.
+
+**Key technical decisions**:
+- `getDistributableFiles()` unchanged — still returns init-only files. Filtering happens downstream in sync/push consumers
+- Sync filters by mutating the distributable `Set` in-place before conflict detection
+- Push places init-only guard as the first filter in both Phase 1 and Phase 2 loops, unconditionally excluding init-only files even from `--include` patterns
+- `docs.json` moved from `internal` to `initOnly`, enabling first-time distribution to target repos