@samaksh/git-worker 0.0.0-stage → 0.1.0

package/GIT_WORKER_PROJECT_PLAN.md

@@ -0,0 +1,499 @@
+# Git Worker — Implementation Blueprint
+
+**Status:** Proposed architecture, based on `REFERENCE.md` and the subsequent design decisions.  
+**Goal:** A safe, composable TypeScript CLI/TUI for applying reviewed file changes across many Git branches, with VS Code as the preferred editor/diff tool and Vim as a supported alternative.
+
+## 1. Product contract
+
+Git Worker lets a developer target a local Git repository or remote URL, select branches and a file, edit a reusable template, preview the exact per-branch changes without checking out branches, approve/reject them, and then commit and optionally push approved changes. It should work with a handful or 100+ branches without requiring one persistent worktree per branch.
+
+**Primary design principles**
+
+1. **Readable over clever:** small functions, explicit data types, straightforward control flow.
+2. **Functional core, imperative shell:** transformations, validation, planning, and diff decisions are pure; filesystem, Git, editor, and TUI interactions are injected services.
+3. **Pipeline composition:** `pipeline(stage1, stage2, ...)`, where each stage receives the previous stage's context and returns an updated context or a typed failure.
+4. **Inspect without checkout:** use Git object reads (`git show`, `git ls-tree`, `git cat-file`) to plan changes.
+5. **Review before mutation:** collect missing values and build exact diffs before checkout/commit.
+6. **Controlled destructive operations:** reset/clean only inside a verified, Git Worker-owned disposable checkout, never inside a user's original repository.
+7. **Explicit staging and pushes:** stage only intended paths; push only on confirmation or explicit policy.
+8. **Configuration in one place:** no scattered magic defaults, commands, timeouts, paths, or UI preferences.
+9. **Small first release:** `.env` is the first-class transformer; other file formats are extensions, not implied to be fully supported by the `.env` engine.
+
+## 2. Decisions settled in discussion
+
+| Topic | Final decision |
+|---|---|
+| Static `.env` entries | `DB_PORT=54331` enforces that value on every selected branch. |
+| Dynamic `.env` entries | `SERVICE_NAME={SERVICE_NAME}` takes the existing value from each branch. |
+| Missing dynamic key | Ask for a value for **each** affected branch, individually. |
+| Empty existing value | Empty is present and is preserved; do not prompt. |
+| Prompt timing | During planning/staging, before review and before any commits. |
+| Unmanaged keys | Preserve keys not mentioned in the template. |
+| Template persistence | Save the last **successfully applied** template locally for next run. |
+| Branch-specific binding persistence | Not necessary; Git branch contents are the source of truth. |
+| Drift behavior | Static values are re-enforced on each run; dynamic values are read fresh from each branch. No separate drift subsystem for MVP. |
+| Cleanup | Keep reset/clean before and after checkout, **only in a verified managed disposable checkout**. |
+| Editing/diffing | VS Code (`code --wait`, `code --diff`) preferred; Vim supported. |
+| Execution | Per-branch fault isolation; one branch failure does not silently corrupt another. |
+| Push | Prompt by default; `always` and `never` configurable. |
+| Deleting a key from template | **Proposed default:** do not delete it from branches; require an explicit delete operation. This remains a decision to confirm. |
+
+**Important distinction:** The template is authoritative for **keys it declares**. It is not a whole-file replacement: comments, formatting, ordering, and keys not declared in the template should be preserved by the `.env` transformer. A dynamic placeholder expresses *per-branch ownership of the value*, not a common literal value.
+
+## 3. Example semantics
+
+Template:
+
+```dotenv
+# Uniform values
+DB_NAME=postgres
+DB_PORT=54331
+
+# Values sourced from each branch
+SERVICE_NAME={SERVICE_NAME}
+```
+
+Existing `uat-payments/.env`:
+
+```dotenv
+DB_NAME=legacy
+DB_PORT=54330
+SERVICE_NAME=payments
+CUSTOM_FLAG=yes
+```
+
+Proposed result:
+
+```dotenv
+DB_NAME=postgres
+DB_PORT=54331
+SERVICE_NAME=payments
+CUSTOM_FLAG=yes
+```
+
+If `uat-orders` has no `SERVICE_NAME`, the staging/planning interaction asks:
+
+```text
+Branch: uat-orders
+Missing SERVICE_NAME
+Enter value for uat-orders > orders
+```
+
+It then stages and displays the proposed addition. If the user cancels, that branch is skipped with a recorded reason. Missing values for 50 branches result in 50 individual prompts (not a bulk editor).
+
+### `.env` parsing and preservation rules
+
+- Recognize blank lines, full-line comments, assignments, `export KEY=...` where supported, and inline comments where syntactically unambiguous.
+- Update the value of a declared existing key **in place**; preserve key ordering, unrelated lines, and comments.
+- Append declared keys that do not exist; preserve the file's existing newline style and final-newline convention where practical.
+- Treat `KEY=` as present with an empty value.
+- Define duplicate-key behavior explicitly: **fail that branch with a diagnostic** in MVP instead of guessing which assignment is authoritative.
+- Fail safely on unsupported or ambiguous syntax instead of rewriting it heuristically.
+- Resolve placeholders from the branch's existing key value first, and prompt only when the key is absent.
+- Use the exact `{NAME}` placeholder syntax from the discussion, with escaping and validation rules documented. Avoid silently mixing it with the earlier `${name}` syntax; support an alias only if intentionally configured.
+- Treat values as opaque text, preserving quoting when possible. Never print secret values in normal logs or persisted reports.
+- The template editor's instruction header is temporary and stripped before parsing/saving; real user comments remain.
+
+## 4. CLI/TUI user experience
+
+### Interactive default
+
+```text
+git-worker [repo]
+  1. Resolve/sync project workspace
+  2. Select branches (glob/regex, live refilter)
+  3. Select target file and operation (edit/add/rename)
+  4. Check eligibility per branch
+  5. Load saved template or synthesize first-run starter
+  6. Open template in VS Code (or Vim)
+  7. Validate template and inspect branch files
+  8. Prompt individually for missing dynamic values
+  9. Build out-of-tree before/after snapshots and diffs
+ 10. Review each branch; approve/reject/skip, batch actions optional
+ 11. Revalidate branch tips, apply approved changes, commit
+ 12. Confirm push policy; push eligible commits
+ 13. Display report; persist state only according to actual outcomes
+```
+
+### Example commands
+
+```bash
+git-worker
+git-worker --repo ../my-repo --branch 'uat*' --file .env
+git-worker --repo git@github.com:org/repo.git --branch '/^release\//' --editor code
+git-worker --ci --branch 'uat*' --file .env --push never
+```
+
+Keep the original CLI flags from the reference where useful: `--repo/-r`, `--branch/-b`, `--file/-f`, `--op/-o`, `--editor/-e`, `--commit-msg/-m`, `--push/-p`, `--remote`, `--auto-approve`, `--ci`, `--help`, `--version`. Validate incompatible combinations early. In noninteractive mode, unresolved dynamic variables **fail or skip explicitly**; never hang waiting for prompts or silently invent values. Provide a configured values-input mechanism later if CI needs dynamic additions.
+
+### Editor adapter
+
+- `code --wait <template-file>` for editing; `code --diff <before> <after>` for review. Ensure VS Code is actually installed; show a clear error or configurable fallback.
+- Vim editing through terminal ownership (`vim <template-file>`); diff via `vim -d <before> <after>` (or `vimdiff`).
+- Editor launch, cancellation, file-watch/save behavior, and error re-edit loops are centralized in the editor service.
+- Editor-specific flags are configuration, not hard-coded in the pipeline.
+
+## 5. Architecture: services + pipeline
+
+### Suggested directory layout
+
+```text
+src/
+  cli/
+    index.ts                 # parse args and launch
+    commands.ts
+  config/
+    defaults.ts              # all default values
+    schema.ts                # validate merged configuration
+    load.ts                  # defaults -> project config -> CLI
+  core/
+    types.ts                 # domain models and Result types
+    pipeline.ts              # generic stage composer
+    errors.ts
+  services/
+    git/                     # Git commands, refs, cleanup, commit, push
+    workspace/               # owned project checkout/cache
+    selection/               # branch/file selector and eligibility
+    editor/                  # VS Code/Vim adapter
+    template/                # parse, render, transform .env
+    state/                   # local saved templates
+    review/                  # snapshots, diffs, approvals
+    report/                  # terminal and optional JSON/Markdown
+  stages/
+    resolve-project.ts
+    sync.ts
+    select.ts
+    eligibility.ts
+    load-template.ts
+    edit-template.ts
+    plan.ts
+    review.ts
+    apply.ts
+    push.ts
+    report.ts
+  app.ts                     # composition root / dependency wiring
+```
+
+These are *logical boundaries*, not a mandate for dozens of classes or barrel files. A service is a small set of related functions behind an injected interface. Keep domain types separate from terminal rendering and Git process execution.
+
+### Composition root
+
+```ts
+const services = createServices(config);
+const context = createInitialContext(input, config);
+
+const run = pipeline(
+  resolveProject,
+  syncRepository,
+  selectTargets,
+  checkEligibility,
+  loadTemplate,
+  editTemplate,
+  planChanges,
+  reviewChanges,
+  applyChanges,
+  pushChanges,
+  reportResults,
+);
+
+const result = await run(context, services);
+```
+
+### Simple pipeline API
+
+```ts
+type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: AppError };
+
+type Stage<C, D> = (context: C, deps: D) => Promise<Result<C>>;
+
+function pipeline<C, D>(...stages: Stage<C, D>[]): Stage<C, D> {
+  return async (initial, deps) => {
+    let current = initial;
+    for (const stage of stages) {
+      const result = await stage(current, deps);
+      if (!result.ok) return result;
+      current = result.value;
+    }
+    return { ok: true, value: current };
+  };
+}
+```
+
+This intentionally uses one evolving typed context to minimize generic type complexity. If stage-specific input/output types become important, introduce typed composition overloads later. **Do not let stages mutate the context in place**; return new objects with added fields. For expensive branch data, use maps or immutable records and replace only changed entries.
+
+### Core context
+
+```ts
+type RunContext = {
+  runId: string;
+  input: CliInput;
+  project?: ManagedProject;
+  selectedBranches?: BranchRef[];
+  target?: TargetFile;
+  eligible?: BranchRef[];
+  template?: TemplateDocument;
+  plans?: BranchPlan[];
+  approvals?: Approval[];
+  results?: BranchResult[];
+  pushResults?: PushResult[];
+};
+```
+
+Stage preconditions are validated explicitly. For example, `applyChanges` refuses to run without plans and approvals. `BranchPlan` should capture `branch`, `baseCommitSha`, `path`, `beforeContentHash`, `afterContent`, `diff`, `status`, and an optional reason. Each stage has one job; the pipeline owns ordering, not business rules.
+
+### Pure vs impure responsibilities
+
+| Pure functions | Effectful services |
+|---|---|
+| Parse/validate template | Read Git objects |
+| Extract placeholders | Fetch remotes |
+| Compare template assignments | Launch editor |
+| Render branch-specific content | Prompt for missing values |
+| Compute eligibility decisions from supplied facts | Create staging files |
+| Build branch plan from content + answers | Reset/clean/checkout/commit/push |
+| Format report model | Print TUI / write report |
+
+Prefer dependency injection by passing service objects, not a service locator or class hierarchy.
+
+## 6. Workspace and Git safety
+
+### Workspace layout
+
+```text
+.git-worker/
+  projects/
+    <stable-project-id>/
+      repo/                # disposable checkout owned by git-worker
+      staging/<run-id>/    # outside repo: before/after files
+      state/               # local templates
+      reports/             # optional run reports
+```
+
+- Project ID derived from a canonicalized repository identity; avoid collisions and handle multiple remotes.
+- Never delete or reset the user's supplied local repository. If a local path is supplied, discover its remote and create/use a **separate managed checkout**; define an explicit error when no suitable remote exists rather than silently mutating the original.
+- Verify ownership with a marker file outside the checkout plus canonical real-path checks; reject paths that escape the workspace (including symlinks).
+- Serialize operations per managed checkout (lock file) to prevent concurrent runs corrupting one another.
+- Keep state/staging/reports outside `repo/` so cleanup cannot remove them.
+- `git reset --hard` and `git clean -fd` may run **before and after** branch switches inside the verified managed checkout. Document that ignored files are not removed by `-fd`; if a truly pristine tree is required, make `-fdx` a carefully gated, managed-checkout-only option, not the default.
+- Always stage only the target paths (`git add -- <path>`); check `git diff --cached --name-only` before committing.
+- If an operation fails, clean/reset the disposable checkout and continue to the next branch, recording the failure.
+
+### Preventing stale-plan commits
+
+Planning reads branch commit `A`. Before applying, fetch and verify the branch still points to `A`. If the tip changed, **skip that branch and require re-planning/re-review**. Do not apply an approved diff against a different version of the file. Use non-force pushes and report non-fast-forward failures.
+
+### Per-branch commit behavior
+
+1. Verify managed checkout and branch tip matches the reviewed plan.
+2. Clean before checkout, switch to the target branch, clean again.
+3. Verify target file still matches the reviewed before-content hash.
+4. Write only the approved after-content, using a temporary file/atomic replace where practical.
+5. Stage only the approved path(s), inspect staged names and staged diff.
+6. Skip no-op changes (no empty commits).
+7. Commit with configured message and identity; record SHA.
+8. On error, restore disposable checkout, mark branch failed, continue.
+9. Push only after commit phase and explicit push gate; record per-branch push outcome.
+
+A Git commit is atomic for its tree, but rollback after a successful commit is not automatic. Do not claim the entire multi-branch run is atomic: commits and pushes across different branches can partially succeed.
+
+## 7. Stateful living template, minimal persistence
+
+### State location and format
+
+One local state file per project + target path, for example:
+
+```json
+{
+  "schemaVersion": 1,
+  "targetPath": ".env",
+  "template": "DB_NAME=postgres\nDB_PORT=54331\nSERVICE_NAME={SERVICE_NAME}\n",
+  "updatedAt": "2026-10-28T00:00:00Z"
+}
+```
+
+**No persistent branch binding map**: branch-specific values are read directly from each branch's `.env` on every run. Avoid storing secrets or sensitive values in state, reports, or terminal logs.
+
+### First run
+
+- If saved state exists, load it into the editor.
+- Otherwise, synthesize a helpful draft from common keys/values across selected branches. This is a **proposal**, never automatically applied; distinguish uniform values from varying values and suggest placeholders for varying keys.
+- If synthesis is ambiguous, show a minimal valid blank template rather than inventing config values.
+
+### Subsequent runs
+
+- Load the last saved template; the developer edits it in VS Code/Vim.
+- Re-evaluate the **whole set of declared keys** against every selected branch: static values are enforced and dynamic values are read per branch.
+- Unmanaged keys remain untouched. Removing a key from the template does not implicitly delete it (proposed policy; confirm).
+- If no branches are approved/applied, don't overwrite the saved successful template. If only some branches succeed, retain a clear partial-run status in the report and make it obvious that a subsequent run will re-enforce the template on remaining branches.
+- **State persistence policy needs explicit finalization:** simplest policy is to save the new template after at least one successful local commit, with an accompanying last-run summary; when zero commits occur because everything already matches, allow saving the reviewed template after explicit approval. Never claim a template was applied to all branches when only some succeeded.
+
+### Drift and manual edits
+
+- No dedicated drift tracking needed in MVP. On each run, the current branch content is the truth for dynamic placeholders, and template literals are authoritative for static keys.
+- A branch that has a manually modified static value will show the proposed correction in its diff.
+- A manually modified dynamic value remains unchanged.
+
+## 8. Review UX and diff integrity
+
+- Staging stores `before` and `after` snapshots for each eligible branch, outside the checkout.
+- TUI displays statuses: `unchanged`, `changed`, `missing input`, `ineligible`, `approved`, `rejected`, `skipped`, `failed`.
+- Preview changes with VS Code side-by-side (`code --diff before after`); Vim diff is supported.
+- A branch may be approved/rejected independently. Batch approve/reject is a convenience, not a separate execution path.
+- Approval is tied to a **specific immutable plan hash** (branch, base SHA, target path, before/after content hashes). Any change to plan content invalidates approval and requires review again.
+- If the user edits the *after* snapshot during review, revalidate the resulting file and recompute the plan hash/diff before approval. For MVP, a simpler and safer alternative is **read-only diff review** and requiring a template re-edit to change results.
+- Provide an all-branch summary before the first destructive checkout.
+
+## 9. Configuration design
+
+### Precedence
+
+`defaults < project git-worker.config.json < CLI flags` (and environment variables only for explicitly documented options). Validate once at startup and pass a frozen `AppConfig` through dependency injection.
+
+Example:
+
+```json
+{
+  "git": {
+    "remote": "origin",
+    "fetchPrune": true,
+    "cleanMode": "tracked-and-untracked",
+    "pushPolicy": "prompt",
+    "commitMessage": "chore: sync configuration"
+  },
+  "workspace": {
+    "root": ".git-worker",
+    "lockTimeoutMs": 30000
+  },
+  "editor": {
+    "name": "code",
+    "editCommand": ["code", "--wait", "{file}"],
+    "diffCommand": ["code", "--diff", "{before}", "{after}"]
+  },
+  "template": {
+    "placeholderOpen": "{",
+    "placeholderClose": "}",
+    "missingValuePolicy": "prompt-each-branch",
+    "emptyValueIsPresent": true,
+    "unmanagedKeyPolicy": "preserve",
+    "removedTemplateKeyPolicy": "preserve"
+  },
+  "review": {
+    "autoApprove": false
+  },
+  "execution": {
+    "concurrency": 1,
+    "stopOnBranchError": false
+  },
+  "report": {
+    "writeJson": false,
+    "writeMarkdown": false,
+    "redactValues": true
+  }
+}
+```
+
+Keep security invariants **non-configurable**: never clean outside a verified owned workspace, never force-push by default, never stage unspecified paths, never bypass revalidation of a reviewed plan.
+
+## 10. Errors, cancellation, and reporting
+
+- Use typed error categories: `CONFIG`, `GIT`, `EDITOR`, `TEMPLATE`, `ELIGIBILITY`, `INPUT_CANCELLED`, `STALE_PLAN`, `APPLY`, `PUSH`.
+- Distinguish **run-fatal** errors (invalid config, workspace ownership failure) from **per-branch** errors (missing file, invalid syntax, rejected diff, failed commit).
+- Cancellation before apply must leave target branches unchanged.
+- End with an accurate summary per branch: eligible, skipped, rejected, unchanged, committed, pushed, failed; include commit SHA and reasons where relevant.
+- Reports must avoid leaking `.env` secret values. If a full diff is displayed, warn that it may contain secrets; redact exported reports by default.
+- Persistent Markdown/JSON reports are useful but can follow the terminal summary in implementation priority.
+
+## 11. Test strategy
+
+### Unit tests (pure logic)
+
+- `.env` tokenizer: comments, whitespace, quotes, empty values, CRLF, duplicate keys, `export`, malformed assignments.
+- Static enforcement; dynamic preservation; missing-key prompting request; absent vs empty distinction.
+- Unmanaged-key preservation; append semantics; no-op detection.
+- Template serialization and first-run synthesis.
+- Config precedence and schema validation.
+- Plan hash and stale-plan detection logic.
+- Pipeline short-circuit and context passing.
+
+### Integration tests (temporary local Git repositories)
+
+- 3–5 branches with different `.env` values; verify exact per-branch results.
+- Managed checkout cleanup never affects the source repository.
+- Dirty/untracked files inside managed checkout cannot enter commits.
+- Stale branch tip causes skip, not accidental commit.
+- One branch fails while later branches continue.
+- Stage only intended paths; no-op branches do not commit.
+- Push confirmation/never/always and non-fast-forward failures.
+- Editor adapter with fake command runner; real VS Code/Vim manual smoke tests.
+- Interrupted run leaves managed workspace recoverable.
+
+### Acceptance scenario
+
+1. Create three remote branches, each with unique `SERVICE_NAME` and an unmanaged key.
+2. First-run template enforces two static values and preserves `SERVICE_NAME`.
+3. Fourth branch lacks `SERVICE_NAME`; CLI asks once for that branch during staging.
+4. Review shows exact four branch diffs before any commit.
+5. Reject one branch; approve three; only three are committed.
+6. Push prompt defaults to explicit confirmation.
+7. Re-run: saved template opens; add `LOG_LEVEL=debug`; dynamic values are read from Git without re-prompting.
+8. Manually change a static value and a dynamic value on different branches; next run restores static but preserves dynamic.
+9. Force a branch to advance after review; it is skipped as stale.
+10. Source repository remains untouched throughout.
+
+## 12. Delivery roadmap
+
+### Phase 0 — Lock contracts and test fixtures
+- Confirm placeholder syntax, template-key deletion policy, source-repo handling, state-save semantics, and `.env` grammar.
+- Build fixture repositories and golden before/after files.
+
+### Phase 1 — Safe Git foundation
+- Config schema, workspace ownership, project identity, Git command runner, fetch, branch enumeration, clean/checkout/commit/push, lock, path-scoped staging.
+- Tests for isolation, cleanup, and branch-tip revalidation.
+
+### Phase 2 — Pure `.env` engine
+- Parser/tokenizer, static/dynamic rules, missing-input request generation, preservation rules, diagnostics, deterministic rendering.
+- Exhaustive unit tests.
+
+### Phase 3 — Interactive pipeline and staging
+- Branch/file selection, editor adapter, eligibility, missing-value prompts, out-of-tree snapshots, diff review, approvals.
+- End-to-end dry run that makes no commits.
+
+### Phase 4 — Apply and push
+- Revalidate approved plans, clean switch, path-scoped stage, commit, failure isolation, push gate, terminal summary.
+- Full integration tests.
+
+### Phase 5 — Living-template persistence
+- Save/load local template; first-run synthesis; accurate partial-success handling; incremental subsequent runs.
+- Tests for repeated execution and manual branch edits.
+
+### Phase 6 — Polish and extensions
+- Better TUI filtering, batch actions, exportable reports, CI behavior, additional file-format transformer plugins (Dockerfile/YAML/JSON/Groovy), optional shared state.
+- Add only when real use cases justify them.
+
+## 13. Explicit non-goals for first release
+
+- No one-worktree-per-branch persistent checkout farm.
+- No remote or team-shared template state.
+- No complex drift database or three-way merge engine.
+- No automatic guessing of missing dynamic values.
+- No implicit deletion of unmanaged keys.
+- No multi-repository distributed transaction or guarantee that all branch pushes succeed atomically.
+- No assumption that arbitrary YAML/JSON/Dockerfile/Groovy can be safely transformed by `.env` rules.
+
+## 14. Chosen defaults (open to change)
+
+These decisions were made as reasonable defaults; they can be revisited as needs evolve.
+
+| Decision | Default | Notes |
+|---|---|---|
+| **Removed template key** | **Preserve** on branches | Never delete keys implicitly. If deletion is needed, add an explicit delete operation later. |
+| **Source repository with no remote** | **Reject with error** | Fail fast rather than guessing. A remote (e.g., `origin`) is required to safely use a separate managed checkout without mutating a local-only repo. |
+| **Saved template on partial success** | **Save after first successful commit** (or after explicit approval if no commits occur because everything already matches) | Preserves progress on partial runs; reports clearly show partial status and remaining branches. |
+| **Editable review snapshots** | **Read-only diff for MVP** | Safer and simpler. To change results, re-edit the template and re-run the plan (with mandatory revalidation). |
+| **Secrets in diffs/reports** | **Show in interactive diff with a warning**; **redact from exported reports by default** | Needed to review `.env` changes, but exports (JSON/Markdown) must redact values by default to prevent accidental leaks. |
+
+## 15. Definition of done
+
+Git Worker is ready for its first stable release when a developer can run `git-worker` from anywhere, target a repository, select many branches, edit a remembered `.env` template in VS Code or Vim, provide missing per-branch values before review, inspect deterministic diffs, approve a subset, safely commit and optionally push only approved changes, and receive an accurate report—without modifying their original checkout or carrying accidental files into commits.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# Git Worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A safe, composable TypeScript CLI/TUI for applying reviewed file changes across many Git branches.
+
+## Overview
+
+Git Worker lets you target a Git repository, select branches and a file, edit a reusable template, preview exact per-branch changes without checking out branches, approve/reject them, and then commit and optionally push approved changes. It works with a handful or 100+ branches without requiring one persistent worktree per branch.
+
+## Design Principles
+
+- **Readable over clever** - Small functions, explicit types, straightforward control flow
+- **Functional core, imperative shell** - Pure transformations/validation; side effects injected via services
+- **Inspect without checkout** - Uses `git show`, `git ls-tree`, `git cat-file` to plan changes
+- **Review before mutation** - Collect missing values and build diffs before any checkout/commit
+- **Safe by default** - Never modifies your original repository; only commits to managed disposable checkouts
+- **Per-branch fault isolation** - One branch failure doesn't corrupt others
+
+## How It Works
+
+1. **Resolve & sync** - Detects current Git repository or prompts to clone a remote URL into `~/.git-worker`. If already cloned, reuses the cached clone and fetches latest branches.
+2. **Select** - Choose branches (glob e.g. `uat/*`, regex e.g. `/uat.*/`, select all, or invert selection) and target file
+3. **Template** - Edit a template in VS Code or Vim (or restore previously applied template):
+   - **For `.env` files (AST Reconciliation)**: `KEY=value` sets static values; `KEY={KEY}` reads existing branch values; unmanaged keys and comments are preserved.
+   - **For other files (`Dockerfile`, JSON, YAML, configs)**: The template is the declarative **Source of Truth**; variables like `${VAR}` or `${VAR:-default}` are resolved per-branch from that branch's `.env`, alongside built-ins (`${BRANCH_NAME}`, `${BRANCH_SLUG}`). The evaluated template overrides or creates the file.
+   - **Syntax Validation**: Checks JSON/YAML syntax immediately before planning.
+4. **Plan & review** - See exact diffs per branch, approve/reject individually
+5. **Apply & push** - Commits approved changes in a managed checkout, optionally pushes with confirmation
+
+## Configuration Defaults (Chosen)
+
+We made reasonable defaults for the open decisions. These are easy to change later.
+
+| Decision | Default | Rationale |
+|---|---|---|
+| **Remove key from template** | **Preserve** on branches | Safest - never deletes keys implicitly. If you need deletion, use an explicit delete operation in the future. |
+| **Source repo with no remote** | **Prompt or reject with error** | When outside a repo, prompts to clone remote or target path. Requires a remote to avoid mutating local-only repos unexpectedly. |
+| **Save template on partial success** | **Save after first successful commit** (or after explicit approval if no commits but reviewed) | Preserves progress if some branches succeed and others fail. Partial status is clearly reported. |
+| **Editable review snapshots** | **Read-only diff for MVP** | Much safer. To change results, re-edit the template and re-run the plan. Prevents accidental manual edits creating inconsistent diffs. |
+| **Secrets in diffs** | **Show in interactive diff with warning**; **redact from exported reports by default** | You need to see secrets to review `.env` changes, but exports (JSON/Markdown) redact by default to avoid accidental leaks. |
+
+## CLI Usage
+
+```bash
+# Interactive mode (prompts to use current repo, select cached repo, or clone remote)
+git-worker
+
+# Select from previously cloned/cached repositories directly
+git-worker --cached
+
+# Target a remote repository URL directly
+git-worker --repo https://github.com/my-org/my-project.git
+
+# Target a local repo with specific branches and file
+git-worker --repo ../my-repo --branch 'uat/*' --file .env
+
+# Non-interactive CI mode
+git-worker --repo git@github.com:org/repo.git --branch 'uat/*' --file .env --ci --push never
+
+# Cache management
+git-worker cache list               # List all cached repositories in ~/.git-worker
+git-worker cache clean [target]     # Clean a specific project or select interactively
+git-worker cache clean --all        # Clean all cached checkouts (or: git-worker clean -a -y)
+```
+
+Key flags: `--repo/-r`, `--cached/-c`, `--branch/-b`, `--invert-branch/-i`, `--file/-f`, `--editor/-e`, `--commit-msg/-m`, `--push/-p`, `--remote`, `--auto-approve`, `--ci`
+
+## Workspace Layout
+
+Git Worker stores all checkouts, templates, and state under `~/.git-worker/` in the user's home directory:
+
+```
+~/.git-worker/
+  projects/
+    <stable-project-id>/
+      repo/                # Disposable checkout owned by git-worker
+      staging/<run-id>/    # Before/after snapshots outside repo
+      state/               # Saved templates (per project+target)
+      reports/             # Run reports (optional)
+      .git-worker-marker   # Ownership verification marker
+      .git-worker-lock     # Process lock
+```
+
+**Safety guarantees:**
+- Never touches your original repository
+- Only stages target paths (`git add -- <path>`)
+- Revalidates branch tips before applying (skips if changed)
+- Resets/cleans only inside verified managed checkout
+- Commits/pushes per-branch with fault isolation
+
+## Supported Editors
+
+- **VS Code (preferred)**: `code --wait` for editing, `code --diff` for review
+- **Vim**: `vim` for editing, `vim -d`/`vimdiff` for review
+
+## Development Status
+
+This is the implementation blueprint. See [GIT_WORKER_PROJECT_PLAN.md](./GIT_WORKER_PROJECT_PLAN.md) for the full architecture, API contracts, and roadmap.
+
+## Non-Goals (MVP)
+
+- One-worktree-per-branch persistent checkout farm
+- Remote/team-shared template state  
+- Complex drift database or three-way merge
+- Automatic guessing of missing values
+- Implicit deletion of unmanaged keys
+- Multi-repo distributed transactions
+- Full support for arbitrary YAML/JSON/Dockerfile/Groovy (only `.env` in MVP)
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - Pipeline design, safety model, and structure
+- [Features](docs/FEATURES.md) - Complete feature list and capabilities  
+- [Services](docs/SERVICES.md) - Service APIs and dependency injection
+- [Usage Guide](docs/usage.md) - Detailed usage examples
+- [Implementation Plan](GIT_WORKER_PROJECT_PLAN.md) - Full blueprint and roadmap

package/demo/README.md

@@ -0,0 +1,58 @@
+# git-worker Demo
+
+End-to-end functional verification that exercises every pipeline stage using a **real local Git repository** with 4 branches.
+
+## What it does
+
+1. **Creates** a local bare Git repo (acts as the "remote") in `/tmp/git-worker-demo/`
+2. **Populates** 4 UAT branches with different `.env` files:
+
+| Branch | Contents | Notes |
+|---|---|---|
+| `uat/payments` | All keys present | Baseline |
+| `uat/orders` | `LOG_LEVEL` **missing** | Triggers per-branch prompt |
+| `uat/inventory` | Has `export LEGACY_VAR=…` | Verifies `export` prefix preserved |
+| `uat/notifications` | `DB_NAME=legacy_db` (wrong) | Verifies static enforcement |
+
+3. **Pre-loads** this template (skips editor opening):
+```dotenv
+# Static — enforced on all branches
+DB_NAME=uat_db
+
+# Dynamic — read from each branch
+DB_PORT={DB_PORT}
+SERVICE_NAME={SERVICE_NAME}
+LOG_LEVEL={LOG_LEVEL}
+```
+
+4. **Runs `git-worker`** against the repo matching pattern `/^uat\//`
+5. **Verifies** results: DB_NAME corrected, CUSTOM_FLAG preserved, SERVICE_NAME intact
+
+## Run
+
+```bash
+# Interactive — full TUI with prompts and per-branch diff review
+npx tsx demo/index.ts
+
+# Non-interactive — CI mode, auto-approve, uat/orders skipped (LOG_LEVEL missing)
+npx tsx demo/index.ts --ci
+
+# Clean up demo files
+npx tsx demo/index.ts --clean
+```
+
+## Expected outcomes
+
+| Branch | Outcome |
+|---|---|
+| `uat/payments` | `DB_NAME` stays `uat_db`, all dynamic values preserved |
+| `uat/orders` | **CI:** skipped (missing `LOG_LEVEL`) — **Interactive:** prompted, then committed |
+| `uat/inventory` | `export LEGACY_VAR` prefix preserved, `DB_NAME` unchanged |
+| `uat/notifications` | `DB_NAME` corrected `legacy_db → uat_db`, `CUSTOM_FLAG` preserved |
+
+## What each verification checks
+
+After the run, the script reads `.env` from each branch via `git show origin/BRANCH:.env` and asserts:
+- `DB_NAME=uat_db` (static enforcement worked)
+- `CUSTOM_FLAG` still present (unmanaged key preservation)
+- `SERVICE_NAME` still present (dynamic placeholder — value unchanged)