ralphy-spec 0.1.1 → 0.2.0

package/dist/core/workspace/patch-mode.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatchModeWorkspace = void 0;
+exports.getPatchWorkspaceRoot = getPatchWorkspaceRoot;
+const execa_1 = require("execa");
+const node_path_1 = __importDefault(require("node:path"));
+const file_contract_1 = require("../spec/file-contract");
+class PatchModeWorkspace {
+    repoRoot;
+    mode = "patch";
+    stateByTask = new Map();
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+    }
+    async prepare(taskId) {
+        const snapshotCommit = await this.git(["rev-parse", "HEAD"]);
+        this.stateByTask.set(taskId, { snapshotCommit });
+        return { taskId, workingDir: this.repoRoot };
+    }
+    getWorkingDir(_taskId) {
+        return this.repoRoot;
+    }
+    async getChangedFiles(_taskId) {
+        // name-status gives: A/M/D/R... <path> ...
+        const out = await this.git(["diff", "--name-status"]);
+        const lines = out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        const changed = [];
+        for (const line of lines) {
+            const parts = line.split(/\s+/);
+            const status = parts[0] ?? "";
+            const file = parts[1] ?? "";
+            if (!file)
+                continue;
+            changed.push({ file, isNew: status.startsWith("A") });
+        }
+        return changed;
+    }
+    async enforceContract(taskId, contract) {
+        const changedFiles = await this.getChangedFiles(taskId);
+        const violations = (0, file_contract_1.evaluateFileContract)({ changedFiles, contract });
+        if (violations.length) {
+            await this.revert(taskId);
+        }
+        return violations;
+    }
+    async checkpoint(taskId, message) {
+        // Best effort: commit all changes. If nothing to commit, return HEAD.
+        await this.git(["add", "-A"]);
+        const commitMsg = `[ralphy-spec] ${taskId}: ${message}`;
+        try {
+            await this.git(["commit", "-m", commitMsg]);
+        }
+        catch {
+            // likely "nothing to commit"
+        }
+        const ref = await this.git(["rev-parse", "HEAD"]);
+        return { ref };
+    }
+    async merge(_taskId) {
+        // Patch mode executes on main; merge is no-op.
+    }
+    async revert(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Hard revert to snapshot; also remove untracked files.
+        await this.git(["reset", "--hard", state.snapshotCommit]);
+        await this.git(["clean", "-fd"]);
+    }
+    async cleanup(_taskId) {
+        // No-op for patch mode.
+    }
+    async git(args) {
+        const res = await (0, execa_1.execa)("git", args, {
+            cwd: this.repoRoot,
+            stdio: "pipe",
+        });
+        return res.stdout.trim();
+    }
+}
+exports.PatchModeWorkspace = PatchModeWorkspace;
+function getPatchWorkspaceRoot(repoRoot) {
+    return node_path_1.default.resolve(repoRoot);
+}
+//# sourceMappingURL=patch-mode.js.map

package/dist/core/workspace/patch-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-mode.js","sourceRoot":"","sources":["../../../src/core/workspace/patch-mode.ts"],"names":[],"mappings":"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"}

package/dist/core/workspace/worktree-mode.d.ts

@@ -0,0 +1,28 @@
+import type { FileContract } from "../spec/types";
+import type { CheckpointRef, ContractViolation, WorkspaceContext, WorkspaceManager } from "./manager";
+/**
+ * WorktreeModeWorkspace uses git worktrees for task isolation.
+ *
+ * Each task runs in its own worktree branch, providing complete isolation
+ * from the main working directory. Changes are merged back on success.
+ */
+export declare class WorktreeModeWorkspace implements WorkspaceManager {
+    private readonly repoRoot;
+    mode: "worktree";
+    private readonly stateByTask;
+    private readonly worktreeBase;
+    constructor(repoRoot: string);
+    prepare(taskId: string): Promise<WorkspaceContext>;
+    getWorkingDir(taskId: string): string;
+    getChangedFiles(taskId: string): Promise<Array<{
+        file: string;
+        isNew: boolean;
+    }>>;
+    enforceContract(taskId: string, contract: FileContract): Promise<ContractViolation[]>;
+    checkpoint(taskId: string, message: string): Promise<CheckpointRef>;
+    merge(taskId: string): Promise<void>;
+    revert(taskId: string): Promise<void>;
+    cleanup(taskId: string): Promise<void>;
+    private git;
+}
+//# sourceMappingURL=worktree-mode.d.ts.map

package/dist/core/workspace/worktree-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-mode.d.ts","sourceRoot":"","sources":["../../../src/core/workspace/worktree-mode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,WAAW,CAAC;AAQnB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAKhD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,IAAI,EAAE,UAAU,CAAc;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,QAAQ,EAAE,MAAM;IAIvC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoCxD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK/B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IA2BjF,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYrF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBnE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBpC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASrC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAiB9B,GAAG;CAalB"}

package/dist/core/workspace/worktree-mode.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeModeWorkspace = void 0;
+const execa_1 = require("execa");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const file_contract_1 = require("../spec/file-contract");
+/**
+ * WorktreeModeWorkspace uses git worktrees for task isolation.
+ *
+ * Each task runs in its own worktree branch, providing complete isolation
+ * from the main working directory. Changes are merged back on success.
+ */
+class WorktreeModeWorkspace {
+    repoRoot;
+    mode = "worktree";
+    stateByTask = new Map();
+    worktreeBase;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+        this.worktreeBase = node_path_1.default.join(repoRoot, ".ralphy", "worktrees");
+    }
+    async prepare(taskId) {
+        // Ensure worktree base directory exists
+        await promises_1.default.mkdir(this.worktreeBase, { recursive: true });
+        // Get current HEAD as base
+        const baseCommit = await this.git(["rev-parse", "HEAD"], this.repoRoot);
+        // Create a unique branch name for this task
+        const branchName = `ralphy/${taskId}/${Date.now()}`;
+        const worktreePath = node_path_1.default.join(this.worktreeBase, taskId.replace(/[^a-zA-Z0-9-_]/g, "_"));
+        // Clean up existing worktree if present
+        try {
+            await promises_1.default.rm(worktreePath, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+        // Remove stale worktree entry if any
+        try {
+            await this.git(["worktree", "remove", "--force", worktreePath], this.repoRoot);
+        }
+        catch {
+            // Ignore if doesn't exist
+        }
+        // Create new worktree with a new branch
+        await this.git(["worktree", "add", "-b", branchName, worktreePath, baseCommit], this.repoRoot);
+        this.stateByTask.set(taskId, { worktreePath, branchName, baseCommit });
+        return { taskId, workingDir: worktreePath };
+    }
+    getWorkingDir(taskId) {
+        const state = this.stateByTask.get(taskId);
+        return state?.worktreePath ?? this.repoRoot;
+    }
+    async getChangedFiles(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return [];
+        // Get changes compared to base commit
+        const out = await this.git(["diff", "--name-status", state.baseCommit], state.worktreePath);
+        const lines = out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        const changed = [];
+        for (const line of lines) {
+            const parts = line.split(/\s+/);
+            const status = parts[0] ?? "";
+            const file = parts[1] ?? "";
+            if (!file)
+                continue;
+            changed.push({ file, isNew: status.startsWith("A") });
+        }
+        return changed;
+    }
+    async enforceContract(taskId, contract) {
+        const changedFiles = await this.getChangedFiles(taskId);
+        const violations = (0, file_contract_1.evaluateFileContract)({ changedFiles, contract });
+        if (violations.length) {
+            // Revert the worktree to base state
+            await this.revert(taskId);
+        }
+        return violations;
+    }
+    async checkpoint(taskId, message) {
+        const state = this.stateByTask.get(taskId);
+        if (!state) {
+            throw new Error(`No worktree state for task ${taskId}`);
+        }
+        // Stage and commit all changes in worktree
+        await this.git(["add", "-A"], state.worktreePath);
+        const commitMsg = `[ralphy-spec] ${taskId}: ${message}`;
+        try {
+            await this.git(["commit", "-m", commitMsg], state.worktreePath);
+        }
+        catch {
+            // Likely nothing to commit
+        }
+        const ref = await this.git(["rev-parse", "HEAD"], state.worktreePath);
+        return { ref };
+    }
+    async merge(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Get the current branch in main repo
+        const currentBranch = await this.git(["rev-parse", "--abbrev-ref", "HEAD"], this.repoRoot);
+        // Merge the task branch back using --squash for clean history
+        try {
+            await this.git(["merge", "--squash", state.branchName], this.repoRoot);
+            await this.git(["commit", "-m", `[ralphy-spec] Merge task ${taskId}`], this.repoRoot);
+        }
+        catch (err) {
+            // If merge fails, user may need to resolve manually
+            throw new Error(`Failed to merge task ${taskId}: ${err?.message ?? String(err)}. Manual resolution may be required.`);
+        }
+    }
+    async revert(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        // Hard reset worktree to base commit
+        await this.git(["reset", "--hard", state.baseCommit], state.worktreePath);
+        await this.git(["clean", "-fd"], state.worktreePath);
+    }
+    async cleanup(taskId) {
+        const state = this.stateByTask.get(taskId);
+        if (!state)
+            return;
+        try {
+            // Remove the worktree
+            await this.git(["worktree", "remove", "--force", state.worktreePath], this.repoRoot);
+            // Delete the branch
+            await this.git(["branch", "-D", state.branchName], this.repoRoot);
+        }
+        catch {
+            // Best effort cleanup
+        }
+        this.stateByTask.delete(taskId);
+    }
+    async git(args, cwd) {
+        const res = await (0, execa_1.execa)("git", args, {
+            cwd,
+            stdio: "pipe",
+            reject: false,
+        });
+        if (res.exitCode !== 0 && res.stderr) {
+            throw new Error(`git ${args.join(" ")} failed: ${res.stderr}`);
+        }
+        return res.stdout.trim();
+    }
+}
+exports.WorktreeModeWorkspace = WorktreeModeWorkspace;
+//# sourceMappingURL=worktree-mode.js.map

package/dist/core/workspace/worktree-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-mode.js","sourceRoot":"","sources":["../../../src/core/workspace/worktree-mode.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,18 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const init_1 = require("./commands/init");
-const validate_1 = require("./commands/validate");
-const update_1 = require("./commands/update");
+const init_1 = require("./cli/init");
+const validate_1 = require("./cli/validate");
+const update_1 = require("./cli/update");
+const run_1 = require("./cli/run");
+const status_1 = require("./cli/status");
+const report_1 = require("./cli/report");
+const tail_1 = require("./cli/tail");
+const checkpoint_1 = require("./cli/checkpoint");
 function buildProgram() {
     const program = new commander_1.Command();
     program
         .name("ralphy-spec")
         .description("One-command setup for Ralph loop + OpenSpec workflows across Cursor, OpenCode, and Claude Code.")
-        .version("0.1.1");
+        .version("0.1.2");
     (0, init_1.registerInitCommand)(program);
     (0, validate_1.registerValidateCommand)(program);
     (0, update_1.registerUpdateCommand)(program);
+    (0, run_1.registerRunCommand)(program);
+    (0, status_1.registerStatusCommand)(program);
+    (0, report_1.registerReportCommand)(program);
+    (0, tail_1.registerTailCommand)(program);
+    (0, checkpoint_1.registerCheckpointCommand)(program);
     return program;
 }
 async function main() {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAAA,yCAAoC;AACpC,0CAAsD;AACtD,kDAA8D;AAC9D,8CAA0D;AAE1D,SAAS,YAAY;IACnB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CACV,iGAAiG,CAClG;SACA,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAAA,yCAAoC;AACpC,qCAAiD;AACjD,6CAAyD;AACzD,yCAAqD;AACrD,mCAA+C;AAC/C,yCAAqD;AACrD,yCAAqD;AACrD,qCAAiD;AACjD,iDAA6D;AAE7D,SAAS,YAAY;IACnB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CACV,iGAAiG,CAClG;SACA,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;IACjC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,wBAAkB,EAAC,OAAO,CAAC,CAAC;IAC5B,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;IAC/B,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;IAC7B,IAAA,sCAAyB,EAAC,OAAO,CAAC,CAAC;IAEnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,IAAI,EAAE,CAAC"}

package/dist/templates/shared/openspec-tasks-template.md

@@ -3,11 +3,15 @@
 Use this structure for `openspec/changes/<change-name>/tasks.md`.
 
 ## 1. Planning / Scaffolding
-- [ ] 1.1 Confirm scope and affected modules
+- [ ] 1.1 Confirm scope, non-goals, and impacted modules
+  - Acceptance criteria:
+    - GIVEN the current `openspec/specs/` baseline
+    - WHEN this change is implemented
+    - THEN only the intended domains are affected
   - Test plan: N/A
 
 ## 2. Implementation
-- [ ] 2.1 Implement feature behavior
+- [ ] 2.1 Implement feature behavior (spec-driven)
   - Acceptance criteria:
     - GIVEN ...
     - WHEN ...
@@ -16,13 +20,29 @@ Use this structure for `openspec/changes/<change-name>/tasks.md`.
     - Run: `npm test`
     - Assert: ...
 
+## 3. Validators / Budgets (v2+)
+- [ ] 3.1 Define or update validators used by this change
+  - Notes:
+    - Validators are the ground truth (deterministic pass/fail)
+    - Prefer: `npm run typecheck`, `npm test`, `npm run lint`
+  - Test plan:
+    - Run the validator commands locally/CI
+
+- [ ] 3.2 If the change introduces budgeted execution (v2.1+), document expected behavior
+  - Notes:
+    - Optimal → Warning → Hard tier expectations
+    - WARNING tier should shrink context + enforce repair-only constraints
+    - HARD tier should stop safely (no silent retries)
+  - Test plan:
+    - Run a small demo task that crosses WARNING tier and confirm behaviors
+
 ## 3. Validation
 - [ ] 3.1 Add/adjust tests to cover all scenarios
   - Test plan:
     - Run: `npm test`
 
 ## 4. Documentation / Archive
-- [ ] 4.1 Update specs and archive change
+- [ ] 4.1 Update OpenSpec docs/spec deltas (if needed) and archive change
   - Test plan:
     - Run: `npm test`
 

package/dist/templates/shared/project-template.yml

@@ -0,0 +1,232 @@
+# ralphy-spec Project Configuration
+# Generated by: ralphy-spec init
+# Version: 2.1 (Budget Intelligence + Sprint Semantics)
+
+version: "1.1"
+
+project:
+  name: "my-project"
+  repoRoot: "."
+  language: "ts"
+  packageManager: "npm"          # user-defined: npm | pnpm | yarn | bun
+
+defaults:
+  backend: "cursor"
+  workspaceMode: "patch"       # "worktree" | "patch"
+  checkpointMode: "commit"     # "commit" | "patch"
+  validators:
+    - typecheck
+    - test
+    - lint
+
+# Artifacts (IDE-friendly human interface)
+# NOTE: These are defaults; users can override or disable.
+artifacts:
+  enabled: true
+  rootDir: "ralphy-spec"        # default; can be overridden via CLI: --artifact-dir
+  statusIcons: "emoji"          # "emoji" | "ascii" | "none"
+
+# Run-level budgets (hard limits for entire run)
+budgets:
+  run:
+    money_usd: 20              # Max USD per run
+    tokens: 2000000            # Max tokens per run
+    wall_time_minutes: 90      # Max wall clock time
+    max_iterations_total: 80   # Max total iterations across all tasks
+  
+  limits:
+    max_parallel_tasks: 1      # Concurrent tasks (v1: always 1)
+    max_parallel_validators: 2 # Concurrent validators
+    command_timeout_seconds: 900
+
+# Sprint size defaults (applied when task has sprint.size but no explicit budget)
+# Users can override per-task
+sprint_defaults:
+  XS:
+    optimal: { usd: 0.20, tokens: 15000, time_minutes: 3 }
+    warning: { usd: 0.35, tokens: 25000, time_minutes: 5 }
+    hard: { usd: 0.50, tokens: 40000, time_minutes: 8, max_iterations: 3 }
+  S:
+    optimal: { usd: 0.50, tokens: 40000, time_minutes: 5 }
+    warning: { usd: 0.80, tokens: 65000, time_minutes: 8 }
+    hard: { usd: 1.20, tokens: 100000, time_minutes: 12, max_iterations: 5 }
+  M:
+    optimal: { usd: 1.20, tokens: 80000, time_minutes: 10 }
+    warning: { usd: 2.00, tokens: 150000, time_minutes: 15 }
+    hard: { usd: 3.00, tokens: 250000, time_minutes: 20, max_iterations: 8 }
+  L:
+    optimal: { usd: 2.50, tokens: 150000, time_minutes: 20 }
+    warning: { usd: 4.00, tokens: 280000, time_minutes: 35 }
+    hard: { usd: 6.00, tokens: 450000, time_minutes: 50, max_iterations: 12 }
+  XL:
+    optimal: { usd: 5.00, tokens: 300000, time_minutes: 40 }
+    warning: { usd: 8.00, tokens: 550000, time_minutes: 70 }
+    hard: { usd: 12.00, tokens: 900000, time_minutes: 100, max_iterations: 20 }
+
+backends:
+  cursor:
+    command: "cursor"
+    modelTiers:
+      default: { hint: "balanced" }
+      cheap: { hint: "cheap" }
+      strong: { hint: "strong" }
+  opencode:
+    command: "opencode"
+    modelTiers:
+      default: {}
+      cheap: {}
+  claude_code:
+    command: "claude"
+    modelTiers:
+      default: {}
+
+validators:
+  - id: "typecheck"
+    # Avoid hard-coding package manager. Choose commands that match your repo.
+    run: "npm run typecheck"
+    timeout_seconds: 600
+    parser: "tsc"
+  - id: "test"
+    run: "npm test"
+    timeout_seconds: 900
+    parser: "jest"
+  - id: "lint"
+    run: "npm run lint"
+    timeout_seconds: 600
+    parser: "eslint"
+
+# Tasks - define your implementation tasks here
+tasks: []
+
+# ============================================================
+# TASK EXAMPLES (uncomment and modify as needed)
+# ============================================================
+
+# Example 1: Simple fix (XS sprint, uses defaults)
+# - id: "fix-typo-001"
+#   title: "Fix typo in error message"
+#   goal: "Correct spelling in validation error"
+#   
+#   sprint:
+#     size: XS                 # Uses XS defaults: $0.20 optimal, 3 max iter
+#     intent: "fix"            # No refactoring allowed
+#   
+#   files_contract:
+#     allowed: ["src/utils/validation.ts"]
+#     forbidden: []
+#     allow_new_files: false
+#   
+#   acceptance:
+#     - id: "acc-1"
+#       text: "Error message spelled correctly"
+#       type: "behavior"
+
+# Example 2: Feature (M sprint with custom budget)
+# - id: "auth-001"
+#   title: "JWT middleware"
+#   goal: "Add JWT auth middleware for API routes"
+#   
+#   sprint:
+#     size: M
+#     intent: "feature"        # Limited refactoring allowed
+#   
+#   budget:                    # Optional: override sprint defaults
+#     optimal:
+#       usd: 1.2
+#       tokens: 80000
+#       time_minutes: 10
+#     warning:
+#       usd: 2.0
+#       tokens: 150000
+#       time_minutes: 15
+#     hard:
+#       usd: 3.0
+#       tokens: 250000
+#       time_minutes: 20
+#       max_iterations: 8
+#   
+#   files_contract:
+#     allowed:
+#       - "src/middleware/**"
+#       - "src/api/**"
+#     forbidden:
+#       - "src/db/**"
+#     allow_new_files: true
+#   
+#   context:
+#     docs: ["README.md"]
+#     files: ["src/api/index.ts"]
+#   
+#   acceptance:
+#     - id: "acc-1"
+#       text: "Requests without token return 401"
+#       type: "behavior"
+#     - id: "acc-2"
+#       text: "Valid tokens allow access"
+#       type: "behavior"
+#     - id: "acc-3"
+#       text: "Unit tests added"
+#       type: "evidence"
+#       evidence:
+#         must_include_files: ["src/**/__tests__/**"]
+#   
+#   validators: ["typecheck", "test", "lint"]
+#   done_policy:
+#     require_all_validators_pass: true
+#     require_acceptance_evidence: true
+
+# Example 3: Large refactor (L sprint)
+# - id: "refactor-db-001"
+#   title: "Migrate to Prisma"
+#   goal: "Replace raw SQL with Prisma ORM"
+#   deps: ["auth-001"]         # Depends on auth task
+#   
+#   sprint:
+#     size: L
+#     intent: "refactor"       # Full refactoring allowed
+#   
+#   files_contract:
+#     allowed:
+#       - "src/db/**"
+#       - "prisma/**"
+#     forbidden:
+#       - "src/api/**"         # Don't touch API layer
+#     allow_new_files: true
+#   
+#   acceptance:
+#     - id: "acc-1"
+#       text: "All database queries use Prisma"
+#       type: "behavior"
+#     - id: "acc-2"
+#       text: "Existing tests pass"
+#       type: "evidence"
+
+# ============================================================
+# BUDGET TIERS EXPLAINED
+# ============================================================
+# 
+# OPTIMAL: Expected cost for correct completion
+#   - Agent operates normally with full context
+#   - All features enabled (self-review, planning)
+#
+# WARNING: Still acceptable but attention needed
+#   - Context shrink: fewer files, only failing tests
+#   - Repair-only mode: "fix only, no refactor"
+#   - Optional calls disabled
+#   - STATUS.md shows pressure signals
+#
+# HARD: Must stop immediately
+#   - Task marked as BLOCKED
+#   - Workspace preserved for debugging
+#   - Failure summary written
+#   - No silent retries
+#
+# ============================================================
+# SPRINT SIZES GUIDE
+# ============================================================
+#
+# XS: Single file fix, typo, simple config change
+# S:  Small function, add a test, minor refactor
+# M:  Feature slice, new endpoint, component
+# L:  Multi-file feature, significant change
+# XL: Infrastructure, major refactor, migration

package/dist/utils/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/utils/installer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAgBvC,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB9E;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CA+Df"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/utils/installer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAiBvC,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD9E;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CA+Df"}