@samaksh/git-worker 0.0.0-stage → 0.1.0

package/dist/stages/select.js

@@ -0,0 +1,250 @@
+import { ok, err } from "../core/types.js";
+import { workspaceError, inputCancelledError } from "../core/errors.js";
+import { clack, sectionHeader, statusLine, sym } from "../utils/ui.js";
+import chalk from "chalk";
+/**
+ * Matches a branch name against a pattern.
+ * Supports:
+ * - Regex: /uat.*\/, /^release\//, /pattern/i
+ * - Glob: uat/*, *orders, uat*
+ * - Exact name: main, develop
+ * - Trailing slash prefix: uat/
+ * - Substring fallback: orders
+ */
+export function matchesBranchPattern(name, pattern) {
+    const trimmed = pattern.trim();
+    if (!trimmed)
+        return false;
+    // 1. Regex pattern: /regex/ or /regex/flags
+    const regexMatch = trimmed.match(/^\/(.+)\/([a-z]*)$/i);
+    if (regexMatch) {
+        try {
+            return new RegExp(regexMatch[1], regexMatch[2]).test(name);
+        }
+        catch {
+            return false;
+        }
+    }
+    // 2. Glob pattern with * or ?
+    if (trimmed.includes("*") || trimmed.includes("?")) {
+        const escaped = trimmed
+            .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+            .replace(/\*/g, ".*")
+            .replace(/\?/g, ".");
+        try {
+            return new RegExp(`^${escaped}$`).test(name);
+        }
+        catch {
+            return false;
+        }
+    }
+    // 3. Exact match
+    if (name === trimmed) {
+        return true;
+    }
+    // 4. Prefix match if pattern ends with '/'
+    if (trimmed.endsWith("/") && name.startsWith(trimmed)) {
+        return true;
+    }
+    // 5. Fallback substring match
+    return name.includes(trimmed);
+}
+export const selectTargetsStage = async (context, deps) => {
+    if (!context.project) {
+        return err(workspaceError("Project not resolved"));
+    }
+    sectionHeader("Branch & Target Selection");
+    const s = clack.spinner();
+    s.start("Listing branches…");
+    const result = await deps.services.git.listBranches(context.project.managedRepoPath, deps.config.git.remote);
+    if (!result.ok) {
+        s.stop(chalk.red("Failed to list branches"));
+        return result;
+    }
+    s.stop(`Found ${result.value.length} branches`);
+    let branches = result.value;
+    // De-duplicate by name (prefer remote over local)
+    const seen = new Map();
+    for (const b of branches) {
+        if (!seen.has(b.name) || b.isRemote) {
+            seen.set(b.name, b);
+        }
+    }
+    branches = Array.from(seen.values());
+    // Filter by pattern if supplied via CLI
+    if (context.input.branch) {
+        const pattern = context.input.branch;
+        const invert = Boolean(context.input.invertBranch);
+        branches = branches.filter((b) => {
+            const matched = matchesBranchPattern(b.name, pattern);
+            return invert ? !matched : matched;
+        });
+        statusLine("info", `Pattern '${pattern}'${invert ? " (inverted)" : ""} matched ${branches.length} branch(es)`);
+    }
+    // Interactive branch selection (non-CI when no --branch provided)
+    if (!context.input.ci && !context.input.branch) {
+        if (branches.length === 0) {
+            clack.log.warn("No branches found in this repository.");
+            return err(inputCancelledError("No branches available"));
+        }
+        const allBranches = branches;
+        let selectedNames = new Set();
+        while (true) {
+            const selectedCount = selectedNames.size;
+            const totalCount = allBranches.length;
+            const options = [];
+            if (selectedCount > 0) {
+                options.push({
+                    value: "confirm",
+                    label: `➜ Confirm and proceed with ${selectedCount} branch(es)`,
+                    hint: "proceed to target file selection",
+                });
+                options.push({
+                    value: "invert",
+                    label: `🔄 Invert selection (select the other ${totalCount - selectedCount} branches)`,
+                    hint: "flip current selection",
+                });
+                options.push({
+                    value: "pattern",
+                    label: "🔍 Filter by pattern or regex",
+                    hint: "glob (uat/*) or regex (/uat.*/)",
+                });
+                options.push({
+                    value: "list",
+                    label: "📋 Customize selection from list",
+                    hint: "toggle individual checkboxes",
+                });
+                options.push({
+                    value: "all",
+                    label: `🌟 Select ALL branches (${totalCount} branches)`,
+                });
+            }
+            else {
+                options.push({
+                    value: "pattern",
+                    label: "🔍 Filter by pattern or regex",
+                    hint: "glob (uat/*) or regex (/uat.*/)",
+                });
+                options.push({
+                    value: "all",
+                    label: `🌟 Select ALL branches (${totalCount} branches)`,
+                    hint: "select every branch in repository",
+                });
+                options.push({
+                    value: "list",
+                    label: "📋 Choose individually from list",
+                    hint: "select branches with checkboxes",
+                });
+                options.push({
+                    value: "invert",
+                    label: `🔄 Invert selection (select all ${totalCount} branches)`,
+                });
+            }
+            const previewText = selectedCount > 0
+                ? `${selectedCount} of ${totalCount} selected: ${chalk.cyan(Array.from(selectedNames).slice(0, 3).join(", ") +
+                    (selectedCount > 3 ? `, +${selectedCount - 3} more` : ""))}`
+                : `0 of ${totalCount} branches selected`;
+            const choice = await clack.select({
+                message: `Branch selection (${previewText}):`,
+                options,
+            });
+            if (clack.isCancel(choice)) {
+                return err(inputCancelledError("Branch selection cancelled"));
+            }
+            if (choice === "confirm") {
+                if (selectedNames.size === 0) {
+                    clack.log.warn("Please select at least one branch before proceeding.");
+                    continue;
+                }
+                break;
+            }
+            if (choice === "all") {
+                selectedNames = new Set(allBranches.map((b) => b.name));
+                statusLine("ok", `Selected all ${totalCount} branch(es)`);
+                continue;
+            }
+            if (choice === "invert") {
+                const inverted = allBranches.filter((b) => !selectedNames.has(b.name));
+                selectedNames = new Set(inverted.map((b) => b.name));
+                statusLine("ok", `Inverted selection: ${selectedNames.size} of ${totalCount} branch(es) selected`);
+                continue;
+            }
+            if (choice === "pattern") {
+                const patternInput = await clack.text({
+                    message: "Enter glob pattern (e.g. uat/*) or regex (e.g. /uat.*/):",
+                    placeholder: "/uat.*/ or uat/*",
+                    validate: (v) => {
+                        if (!v || v.trim().length === 0) {
+                            return "Please enter a pattern or regex";
+                        }
+                    },
+                });
+                if (clack.isCancel(patternInput)) {
+                    continue;
+                }
+                const pattern = patternInput.trim();
+                const matched = allBranches.filter((b) => matchesBranchPattern(b.name, pattern));
+                if (matched.length === 0) {
+                    clack.log.warn(`Pattern '${pattern}' matched 0 of ${totalCount} branches.`);
+                    continue;
+                }
+                selectedNames = new Set(matched.map((b) => b.name));
+                statusLine("ok", `Pattern '${pattern}' matched ${matched.length} branch(es):`);
+                for (const b of matched.slice(0, 5)) {
+                    console.log(chalk.gray(`    • ${b.name}`));
+                }
+                if (matched.length > 5) {
+                    console.log(chalk.gray(`    ... and ${matched.length - 5} more`));
+                }
+                continue;
+            }
+            if (choice === "list") {
+                const picked = await clack.multiselect({
+                    message: "Select branches to process (Space to toggle, Enter to confirm):",
+                    options: allBranches.map((b) => ({
+                        value: b.name,
+                        label: `${sym.branch} ${b.name}`,
+                        hint: b.isRemote
+                            ? `remote/${b.remote}  ${b.sha.slice(0, 8)}`
+                            : `local  ${b.sha.slice(0, 8)}`,
+                    })),
+                    initialValues: Array.from(selectedNames),
+                    required: false,
+                });
+                if (clack.isCancel(picked)) {
+                    continue;
+                }
+                selectedNames = new Set(picked);
+                statusLine("ok", `Selection updated: ${selectedNames.size} branch(es) selected`);
+                continue;
+            }
+        }
+        branches = allBranches.filter((b) => selectedNames.has(b.name));
+    }
+    if (branches.length === 0) {
+        clack.log.warn("No branches selected.");
+        return err(inputCancelledError("No branches selected"));
+    }
+    // Target file selection
+    let targetPath = context.input.file;
+    if (!targetPath && !context.input.ci) {
+        const fileInput = await clack.text({
+            message: "Target file path:",
+            placeholder: ".env",
+            defaultValue: ".env",
+        });
+        if (clack.isCancel(fileInput)) {
+            return err(inputCancelledError("File selection cancelled"));
+        }
+        targetPath = fileInput || ".env";
+    }
+    else if (!targetPath) {
+        targetPath = ".env";
+    }
+    statusLine("ok", `Selected ${branches.length} branch(es) → ${targetPath}`);
+    return ok({
+        ...context,
+        selectedBranches: branches,
+        target: { path: targetPath },
+    });
+};

package/dist/stages/sync.d.ts

@@ -0,0 +1,3 @@
+import { Stage } from "../core/pipeline.js";
+import { RunContext, AppDeps } from "../core/types.js";
+export declare const syncRepositoryStage: Stage<RunContext, AppDeps>;

package/dist/stages/sync.js

@@ -0,0 +1,47 @@
+import { ok, err } from "../core/types.js";
+import { workspaceError } from "../core/errors.js";
+import { clack, statusLine } from "../utils/ui.js";
+import chalk from "chalk";
+export const syncRepositoryStage = async (context, deps) => {
+    if (!context.project) {
+        return err(workspaceError("Project not resolved"));
+    }
+    const s = clack.spinner();
+    s.start(context.project.isCached
+        ? "Syncing cached repository with remote…"
+        : "Cloning repository into managed workspace…");
+    const cloneResult = await deps.services.workspace.ensureManagedClone(context.project);
+    if (!cloneResult.ok) {
+        s.stop(chalk.red("Clone failed"));
+        return cloneResult;
+    }
+    if (cloneResult.value.isCached) {
+        s.message("Using cached repository — fetching latest branches…");
+    }
+    // Acquire workspace lock
+    const lockResult = await deps.services.workspace.acquireLock(context.project, deps.config.workspace.lockTimeoutMs);
+    if (!lockResult.ok) {
+        s.stop(chalk.red("Could not acquire workspace lock"));
+        return lockResult;
+    }
+    // Register lock release on process exit
+    const releaseLock = lockResult.value;
+    process.on("exit", () => { releaseLock(); });
+    process.on("SIGINT", () => { releaseLock(); process.exit(130); });
+    process.on("SIGTERM", () => { releaseLock(); process.exit(143); });
+    // Fetch latest from remote
+    if (context.project.remoteUrl) {
+        const fetchResult = await deps.services.git.fetch(context.project.managedRepoPath, deps.config.git.remote, deps.config.git.fetchPrune);
+        if (!fetchResult.ok) {
+            s.stop(chalk.yellow("Fetch warning — continuing with cached refs"));
+            statusLine("warn", fetchResult.error.message);
+        }
+        else {
+            s.stop(chalk.green("Repository synced"));
+        }
+    }
+    else {
+        s.stop(chalk.green("Checkout ready (no remote to fetch)"));
+    }
+    return ok(context);
+};

package/dist/utils/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function sha256(content: string): string;
+export declare function planHash(branchName: string, baseCommitSha: string, targetPath: string, beforeContentHash: string, afterContentHash: string): string;

package/dist/utils/hash.js

@@ -0,0 +1,7 @@
+import { createHash } from "crypto";
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function planHash(branchName, baseCommitSha, targetPath, beforeContentHash, afterContentHash) {
+    return sha256(`${branchName}|${baseCommitSha}|${targetPath}|${beforeContentHash}|${afterContentHash}`);
+}

package/dist/utils/ui.d.ts

@@ -0,0 +1,21 @@
+import * as clack from "@clack/prompts";
+export { clack };
+export declare const sym: {
+    check: string;
+    cross: string;
+    skip: string;
+    dot: string;
+    warn: string;
+    arrow: string;
+    branch: string;
+};
+export declare function banner(): void;
+export declare function sectionHeader(title: string): void;
+export declare function divider(): void;
+export declare function statusLine(status: "ok" | "fail" | "warn" | "skip" | "info", message: string, detail?: string): void;
+export declare function renderDiff(diff: string, redact?: boolean): void;
+export declare function renderBranchTable(rows: Array<{
+    name: string;
+    status: string;
+    detail?: string;
+}>): void;

package/dist/utils/ui.js

@@ -0,0 +1,113 @@
+/**
+ * Terminal UI utilities using chalk for color and @clack/prompts for interactive prompts.
+ * All UX-facing output goes through this module.
+ */
+import chalk from "chalk";
+import * as clack from "@clack/prompts";
+export { clack };
+// ── Symbols ────────────────────────────────────────────────────────────────
+export const sym = {
+    check: chalk.green("✓"),
+    cross: chalk.red("✗"),
+    skip: chalk.gray("–"),
+    dot: chalk.gray("•"),
+    warn: chalk.yellow("⚠"),
+    arrow: chalk.cyan("→"),
+    branch: chalk.cyan("⎇"),
+};
+// ── Box / header ───────────────────────────────────────────────────────────
+export function banner() {
+    console.log("");
+    console.log(chalk.bold.cyan("  ◆ git-worker"));
+    console.log(chalk.gray("  Safe multi-branch file sync"));
+    console.log("");
+}
+export function sectionHeader(title) {
+    console.log("");
+    console.log(chalk.bold(`  ${title}`));
+    console.log(chalk.gray("  " + "─".repeat(Math.max(title.length, 40))));
+}
+export function divider() {
+    console.log(chalk.gray("  " + "─".repeat(60)));
+}
+// ── Status lines ──────────────────────────────────────────────────────────
+export function statusLine(status, message, detail) {
+    const icon = status === "ok" ? sym.check :
+        status === "fail" ? sym.cross :
+            status === "warn" ? sym.warn :
+                status === "skip" ? sym.skip :
+                    sym.dot;
+    const color = status === "ok" ? chalk.green :
+        status === "fail" ? chalk.red :
+            status === "warn" ? chalk.yellow :
+                status === "skip" ? chalk.gray :
+                    chalk.white;
+    console.log(`  ${icon} ${color(message)}`);
+    if (detail)
+        console.log(chalk.gray(`    ${detail}`));
+}
+// ── Diff rendering ────────────────────────────────────────────────────────
+export function renderDiff(diff, redact = false) {
+    if (!diff) {
+        console.log(chalk.gray("    (no changes)"));
+        return;
+    }
+    const lines = diff.split("\n");
+    for (const line of lines) {
+        if (line.startsWith("+++") || line.startsWith("---")) {
+            console.log(chalk.gray(`    ${line}`));
+        }
+        else if (line.startsWith("@@")) {
+            console.log(chalk.cyan(`    ${line}`));
+        }
+        else if (line.startsWith("+")) {
+            const display = redact ? redactLine(line) : line;
+            console.log(chalk.green(`    ${display}`));
+        }
+        else if (line.startsWith("-")) {
+            const display = redact ? redactLine(line) : line;
+            console.log(chalk.red(`    ${display}`));
+        }
+        else {
+            console.log(chalk.gray(`    ${line}`));
+        }
+    }
+}
+function redactLine(line) {
+    // Redact value portion: +KEY=value → +KEY=[REDACTED]
+    return line.replace(/^([+-][A-Za-z_][A-Za-z0-9_]*)=.+$/, "$1=[REDACTED]");
+}
+// ── Branch status table ───────────────────────────────────────────────────
+export function renderBranchTable(rows) {
+    const maxName = Math.max(...rows.map((r) => r.name.length), 10);
+    for (const row of rows) {
+        const name = row.name.padEnd(maxName);
+        let statusStr;
+        switch (row.status) {
+            case "committed":
+                statusStr = chalk.green("committed");
+                break;
+            case "failed":
+                statusStr = chalk.red("failed   ");
+                break;
+            case "rejected":
+                statusStr = chalk.yellow("rejected ");
+                break;
+            case "unchanged":
+                statusStr = chalk.gray("unchanged");
+                break;
+            case "skipped":
+                statusStr = chalk.gray("skipped  ");
+                break;
+            case "changed":
+                statusStr = chalk.cyan("changed  ");
+                break;
+            case "error":
+                statusStr = chalk.red("error    ");
+                break;
+            default:
+                statusStr = chalk.gray(row.status.padEnd(9));
+        }
+        console.log(`  ${sym.branch} ${chalk.white(name)}  ${statusStr}  ${chalk.gray(row.detail ?? "")}`);
+    }
+}

package/dist/utils/which.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Find the full path of an executable on PATH.
+ * Returns null if not found.
+ */
+export declare function which(name: string): Promise<string | null>;

package/dist/utils/which.js

@@ -0,0 +1,16 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+const execAsync = promisify(exec);
+/**
+ * Find the full path of an executable on PATH.
+ * Returns null if not found.
+ */
+export async function which(name) {
+    try {
+        const { stdout } = await execAsync(`which ${name}`);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}

package/docs/FEATURES.md

@@ -0,0 +1,84 @@
+# Features
+
+## Core Features
+
+### Multi-branch Operations
+- Target multiple branches simultaneously via glob patterns (`uat/*`) or regex patterns (`/uat.*/`)
+- Interactive branch selector with **Select All**, **Invert Selection**, **Pattern Filter**, and manual checkbox list
+- Command-line pattern inversion support via `--invert-branch` (`-i`)
+- No persistent worktree per branch - uses git object reads for planning
+- Per-branch fault isolation - failures don't affect other branches
+
+### Safe .env Template System
+- **Static values**: `KEY=value` enforced on every selected branch
+- **Dynamic placeholders**: `KEY={KEY}` reads existing value from each branch
+- **Missing values**: Prompted individually per branch during planning
+- **Unmanaged keys preserved**: Keys not in template are never touched
+- **Comment preservation**: Comments and formatting preserved
+- **Export support**: Handles `export KEY=value` syntax
+- **Quoted values**: Preserves quoted values and spaces correctly
+- **Empty values**: `KEY=` treated as present with empty value
+- **Duplicate detection**: Fails safely if duplicates found
+
+### Declarative Source-of-Truth Templates (Dockerfile, JSON, YAML)
+- **Full File Override / Creation**: The template represents the authoritative source of truth.
+- **Variable Substitution**: Replaces `${VAR}` placeholders with values resolved from each branch's `.env`.
+- **Fallback Defaults**: Supports `${VAR:-default}` syntax (e.g. `${PORT:-8080}`) to use fallback values when missing.
+- **Built-in Branch Variables**: Injects `${BRANCH_NAME}`, `${BRANCH_SLUG}`, `${REPO_NAME}`, `${COMMIT_SHA}`, and `${SHORT_SHA}`.
+- **Pre-Plan Syntax Validation**: Validates JSON syntax, YAML indentation/structure, and template delimiters before planning.
+- **State Persistence**: Applied templates are saved in `~/.git-worker/projects/<id>/state/` and automatically restored on subsequent runs.
+
+### Review Workflow
+- Plan all changes before any mutations
+- Preview diffs per branch in terminal or external viewer (VS Code/Vim)
+- Approve/reject branches individually
+- Pre-destructive checkout confirmation
+- Branch tip revalidation before apply (stale plans skipped)
+
+### Safe Application
+- Uses managed disposable checkout in `~/.git-worker` (separate from original repo)
+- **Requires remote** - refuses repos without remotes by default
+- Workspace ownership verification
+- Cross-process locking
+- Resets/cleans only in managed checkout
+- Stages only target paths
+- Commits per branch independently
+- Push with policy (prompt/always/never), respects CI mode
+
+### Repository Discovery & Remote Clones
+- Automatically detects if current directory is a Git repository
+- Lists and selects from already cloned and cached repositories (`name`, `remote-url`)
+- If run outside a repository, prompts to select from cache, clone a remote URL (HTTP/HTTPS/SSH), or provide a local path
+- Direct command-line targeting via `--repo <url-or-path>` or `--cached` (`-c`)
+
+### Cache Management & Notifications
+- Centralized storage in `~/.git-worker/projects/<project-id>`
+- Detects existing clones and notifies user of cached repository reuse
+- Interactive cached repository picker showing Name and Remote URL
+- `git-worker cache list` (or `ls`) displays all cached workspaces in a formatted table
+- `git-worker cache clean [target]` (or `clear`) removes specific projects or provides an interactive removal menu
+- `git-worker cache clean --all -y` batch cleans all workspaces safely
+
+### State Persistence
+- Saves last successfully applied template
+- Saves on partial success (after first commit or explicit approval)
+- Loaded on subsequent runs
+- No persistent branch-specific bindings
+- Loaded on subsequent runs
+- No persistent branch-specific bindings
+
+## Interactive TUI
+- Modern prompts with @clack/prompts
+- Multi-select for branches
+- Per-branch value input
+- Diff review with viewer options
+- Confirmation before destructive operations
+
+## CI Mode
+- Non-interactive operation
+- Missing values cause explicit failure/skip (no hanging)
+- Auto-approve or explicit flags required
+- Push policy enforced
+
+## Demo Suite
+Run `npm run demo` to test with self-contained multi-branch scenarios.

package/docs/SERVICES.md

@@ -0,0 +1,57 @@
+# Services Documentation
+
+Git Worker uses dependency injection with services for all side effects. Each service is created via a factory function.
+
+## Core Services
+
+### Git Reader (`services/git/reader.ts`)
+- `listBranches(repoPath)` - Lists all local and remote branches
+- `readFileFromBranch(repoPath, branch, filePath)` - Reads file content from a branch without checkout using `git show`
+- `getBranchSha(repoPath, branchName)` - Gets current SHA of a branch
+- `fetch(repoPath, remote)` - Fetches from remote with prune
+- `getCurrentBranch(repoPath)` - Gets current branch name
+
+### Git Ops (`services/git/ops.ts`)
+- `ensureRepo(repoPath)` - Validates it's a git repo
+- `checkoutBranch(repoPath, branchName)` - Checks out a branch
+- `resetHard(repoPath)` - Hard reset (managed checkout only)
+- `clean(repoPath)` - Clean untracked files/dirs
+- `writeAndStage(repoPath, filePath, content)` - Write file and stage it
+- `commit(repoPath, message)` - Create commit
+- `push(repoPath, remote, branchName)` - Push to remote
+- `verifyOwnership(managedRepoPath, markerPath)` - Verifies workspace ownership via marker
+
+### Workspace Manager (`services/workspace/manager.ts`)
+- `resolveProject(sourceRepoPath, remote?)` - Resolves/creates project, **requires remote** (fails if no remote by default)
+- `ensureManagedClone(project)` - Clones or ensures managed repo exists
+- `acquireLock(project)` - Acquires per-project lock with stale PID detection
+- `releaseLock(project)` - Releases lock
+
+### Template Service (`services/template/`)
+**env.ts**: Parsing and validation
+- `parseEnvTemplate(raw)` - Parses template, validates syntax, detects duplicates, extracts placeholders
+
+**transform.ts**: Transformation logic
+- `parseEnvFile(content)` - Parses existing .env file
+- `transformEnv(branchContent, template, branchValues)` - Applies template: enforces static values, preserves dynamic values from branch, prompts for missing
+
+### State Service (`services/state/index.ts`)
+Persists templates per project+target. Saves on success/partial success per configured policy.
+- `loadState(project, targetPath)` - Load saved template
+- `saveState(project, targetPath, template)` - Save template
+- `getStatePath(project, targetPath)` - Get state file path
+
+### Editor Service (`services/editor/index.ts`)
+Opens files in VS Code or Vim.
+- `editFile(filePath, editorName)` - Opens editor and waits for close
+- `diffFiles(before, after, editorName)` - Opens diff viewer
+
+### Review Service (`services/review/index.ts`)
+Manages review snapshots and diff generation.
+- `createSnapshot(content, branch, targetPath)` - Creates before/after snapshots in staging
+- `generateDiff(before, after)` - Generates unified diff
+
+### Report Service (`services/report/index.ts`)
+Generates reports. **Redacts values by default** for exported reports.
+- `generateReport(context)` - Creates report object
+- `writeReport(project, report)` - Writes JSON/Markdown reports (values redacted)

package/docs/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+Git Worker follows a functional core, imperative shell pattern with a pipeline composition model.
+
+## Core Concepts
+
+- **Pipeline**: Stages compose sequentially, each receiving context and deps, returning `Result<T>`
+- **Context**: Single evolving typed object passed through all stages
+- **Services**: Injected dependencies for side effects (git, fs, editor, prompts)
+- **Pure Functions**: Template parsing, transformation, validation are pure
+
+## Directory Structure
+
+```
+src/
+  cli/         # CLI entry point
+  config/      # Configuration schema, defaults, loading
+  core/        # Types, errors, pipeline
+  services/    # Side effect implementations
+    git/       # Git operations (read, write)
+    workspace/ # Managed workspace management
+    template/  # .env parsing and transformation
+  stages/      # Pipeline stages
+  utils/       # Utilities
+```
+
+## Safety Model
+
+1. **No mutation of original repo** - All changes go through managed checkout
+2. **Remote required** - Rejects repos without remotes by default
+3. **Per-branch isolation** - Failures don't cascade
+4. **Tip revalidation** - Branch tips checked before apply (stale plans skipped)
+5. **Path-scoped staging** - Only target files staged
+6. **Read-only diff review by default** - Snapshots not editable in MVP
+
+## Decisions
+
+See [README](../README.md) for all chosen defaults.