@samaksh/git-worker 0.1.0 → 0.2.1

package/GIT_WORKER_PROJECT_PLAN.md

@@ -1,499 +0,0 @@
-# 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/demo/README.md

@@ -1,58 +0,0 @@
-# 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)