ralphy-spec 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-23
+
+### Added
+- Initial public release of `ralphy-spec`.
+- Astro-powered documentation site with i18n (en/zh/ko/ja).
+
+### Changed
+- N/A
+
+### Fixed
+- N/A
+
+## [0.3.0] - 2026-01-23
+
+### Added
+- Budget intelligence: three-tier budgets (optimal → warning → hard) with hard-cap blocking + failure summaries.
+- Sprint semantics: `sprint.size` defaults, `sprint.intent` constraints, and configurable scope guard policy (`off|warn|block`).
+- Artifact system: `ralphy-spec/` folder, STATUS/TASKS/BUDGET writers, per-task artifacts, immutable run logs, and `--artifact-dir`.
+- New CLI command: `ralphy-spec budget` and a full CLI docs page on the website.
+- Test suite (Vitest) covering the above behaviors.
+
+### Changed
+- `ralphy-spec run` now supports `worktree` mode and real backend selection (`cursor|opencode|claude-code|noop`).
+- Docs + README (all languages) updated to reflect the new artifacts and CLI.
+

package/README.ja.md

@@ -5,6 +5,8 @@
 **スペック駆動AI開発 + 反復実行。** OpenSpecとRalph Loopを組み合わせて、予測可能なAI支援コーディングを実現します。
 
 **ウェブサイト:** [https://ralphy-spec.org](https://ralphy-spec.org)
+**ドキュメント:** [https://ralphy-spec.org/ja/docs/](https://ralphy-spec.org/ja/docs/)
+**変更履歴:** [https://ralphy-spec.org/ja/changelog/](https://ralphy-spec.org/ja/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
 ## クイックスタート
 
@@ -12,25 +14,34 @@
 npx ralphy-spec init
 ```
 
+CLI 基本:
+
+```bash
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
+```
+
 次に、AIツールに対応するコマンドを使用します：
 
 ### Cursor
 
 | コマンド | 機能 |
 |----------|------|
-| `/ralphy:plan` | 要件からスペック作成 |
-| `/ralphy:implement` | 反復ループでビルド |
-| `/ralphy:validate` | 受け入れ基準を検証 |
-| `/ralphy:archive` | 完了してアーカイブ |
+| `/ralphy-plan` | 要件からスペック作成 |
+| `/ralphy-implement` | 反復ループでビルド |
+| `/ralphy-validate` | 受け入れ基準を検証 |
+| `/ralphy-archive` | 完了してアーカイブ |
 
 ### Claude Code
 
 | コマンド | 機能 |
 |----------|------|
-| `/ralphy:plan` | 要件からスペック作成 |
-| `/ralphy:implement` | 反復ループでビルド |
-| `/ralphy:validate` | 受け入れ基準を検証 |
-| `/ralphy:archive` | 完了してアーカイブ |
+| `/ralphy-plan` | 要件からスペック作成 |
+| `/ralphy-implement` | 反復ループでビルド |
+| `/ralphy-validate` | 受け入れ基準を検証 |
+| `/ralphy-archive` | 完了してアーカイブ |
 
 ### OpenCode
 
@@ -50,16 +61,16 @@ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</pro
 
 ```bash
 # 1. 計画: アイデアからスペック作成
-You: /ralphy:plan JWT ユーザー認証を追加
+You: /ralphy-plan JWT ユーザー認証を追加
 
 # 2. 実装: AIが反復的にビルド
-You: /ralphy:implement add-user-auth
+You: /ralphy-implement add-user-auth
 
 # 3. 検証: テストパスを確認
-You: /ralphy:validate
+You: /ralphy-validate
 
 # 4. アーカイブ: 変更を完了
-You: /ralphy:archive add-user-auth
+You: /ralphy-archive add-user-auth
 ```
 
 ## 作成されるファイル
@@ -79,11 +90,23 @@ openspec/
 ├── archive/              # 完了
 └── project.md            # コンテキスト
 
-.ralphy/
-├── config.json
-└── ralph-loop.state.json
+ralphy-spec/              # ローカル状態 + アーティファクト（IDE向け）
+├── state.db              # SQLite 実行/タスクログ
+├── STATUS.md             # ライブ状態（`ralphy-spec status` が優先）
+├── TASKS.md              # タスクボード
+├── BUDGET.md             # コスト/予算
+├── runs/                 # 不変の実行ログ（`runs/<runId>.md`）
+├── logs/                 # バックエンド出力（ベストエフォート）
+├── worktrees/            # Git worktree（worktreeモード時）
+└── tasks/                # タスク別アーティファクト（CONTEXT / REPAIR / NOTES）
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
+> 注: 既存の `.ralphy/` フォルダが見つかった場合、`ralphy-spec/` へ自動的に移行します。
+
 ## 仕組み
 
 **Ralph Wiggum Loop:** AIがタスク完了まで同じプロンプトを繰り返し受け取ります。各イテレーションで、ファイルの以前の作業を見て自己修正します。

package/README.ko.md

@@ -5,6 +5,8 @@
 **스펙 기반 AI 개발 + 반복 실행.** OpenSpec과 Ralph Loop를 결합하여 예측 가능한 AI 지원 코딩을 실현합니다.
 
 **웹사이트:** [https://ralphy-spec.org](https://ralphy-spec.org)
+**문서:** [https://ralphy-spec.org/ko/docs/](https://ralphy-spec.org/ko/docs/)
+**변경 로그:** [https://ralphy-spec.org/ko/changelog/](https://ralphy-spec.org/ko/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
 ## 빠른 시작
 
@@ -12,25 +14,34 @@
 npx ralphy-spec init
 ```
 
+CLI 기본 사용:
+
+```bash
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
+```
+
 그런 다음 AI 도구에 맞는 명령을 사용하세요:
 
 ### Cursor
 
 | 명령 | 기능 |
 |------|------|
-| `/ralphy:plan` | 요구사항에서 스펙 생성 |
-| `/ralphy:implement` | 반복 루프로 빌드 |
-| `/ralphy:validate` | 인수 기준 검증 |
-| `/ralphy:archive` | 완료 및 아카이브 |
+| `/ralphy-plan` | 요구사항에서 스펙 생성 |
+| `/ralphy-implement` | 반복 루프로 빌드 |
+| `/ralphy-validate` | 인수 기준 검증 |
+| `/ralphy-archive` | 완료 및 아카이브 |
 
 ### Claude Code
 
 | 명령 | 기능 |
 |------|------|
-| `/ralphy:plan` | 요구사항에서 스펙 생성 |
-| `/ralphy:implement` | 반복 루프로 빌드 |
-| `/ralphy:validate` | 인수 기준 검증 |
-| `/ralphy:archive` | 완료 및 아카이브 |
+| `/ralphy-plan` | 요구사항에서 스펙 생성 |
+| `/ralphy-implement` | 반복 루프로 빌드 |
+| `/ralphy-validate` | 인수 기준 검증 |
+| `/ralphy-archive` | 완료 및 아카이브 |
 
 ### OpenCode
 
@@ -50,16 +61,16 @@ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</pro
 
 ```bash
 # 1. 계획: 아이디어에서 스펙 생성
-You: /ralphy:plan JWT 사용자 인증 추가
+You: /ralphy-plan JWT 사용자 인증 추가
 
 # 2. 구현: AI가 반복적으로 빌드
-You: /ralphy:implement add-user-auth
+You: /ralphy-implement add-user-auth
 
 # 3. 검증: 테스트 통과 확인
-You: /ralphy:validate
+You: /ralphy-validate
 
 # 4. 아카이브: 변경 완료
-You: /ralphy:archive add-user-auth
+You: /ralphy-archive add-user-auth
 ```
 
 ## 생성되는 파일
@@ -79,11 +90,23 @@ openspec/
 ├── archive/              # 완료됨
 └── project.md            # 컨텍스트
 
-.ralphy/
-├── config.json
-└── ralph-loop.state.json
+ralphy-spec/              # 로컬 상태 + 아티팩트(IDE 친화적)
+├── state.db              # SQLite 실행/태스크 로그
+├── STATUS.md             # 라이브 상태(`ralphy-spec status`가 우선 사용)
+├── TASKS.md              # 태스크 보드
+├── BUDGET.md             # 비용/예산
+├── runs/                 # 불변 실행 로그(`runs/<runId>.md`)
+├── logs/                 # 백엔드 원본 출력(가능한 경우)
+├── worktrees/            # Git worktree(worktree 모드 사용 시)
+└── tasks/                # 태스크별 아티팩트(CONTEXT / REPAIR / NOTES)
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
+> 참고: 기존 `.ralphy/` 폴더가 있으면 자동으로 `ralphy-spec/`로 마이그레이션됩니다.
+
 ## 작동 방식
 
 **Ralph Wiggum Loop:** AI가 작업 완료까지 동일한 프롬프트를 반복적으로 받습니다. 각 반복에서 파일의 이전 작업을 보고 자기 수정합니다.

package/README.md

@@ -5,6 +5,8 @@
 **Spec-driven AI development with iterative execution.** Combines OpenSpec + Ralph Loop for predictable AI-assisted coding.
 
 **Website:** [https://ralphy-spec.org](https://ralphy-spec.org)
+**Docs:** [https://ralphy-spec.org/en/docs/](https://ralphy-spec.org/en/docs/)
+**Changelog:** [https://ralphy-spec.org/en/changelog/](https://ralphy-spec.org/en/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
 ## Quick Start
 
@@ -12,25 +14,34 @@
 npx ralphy-spec init
 ```
 
+CLI basics:
+
+```bash
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
+```
+
 Then use the commands for your AI tool:
 
 ### Cursor
 
 | Command | What it does |
 |---------|--------------|
-| `/ralphy:plan` | Create specs from requirements |
-| `/ralphy:implement` | Build with iterative loop |
-| `/ralphy:validate` | Verify acceptance criteria |
-| `/ralphy:archive` | Complete and archive |
+| `/ralphy-plan` | Create specs from requirements |
+| `/ralphy-implement` | Build with iterative loop |
+| `/ralphy-validate` | Verify acceptance criteria |
+| `/ralphy-archive` | Complete and archive |
 
 ### Claude Code
 
 | Command | What it does |
 |---------|--------------|
-| `/ralphy:plan` | Create specs from requirements |
-| `/ralphy:implement` | Build with iterative loop |
-| `/ralphy:validate` | Verify acceptance criteria |
-| `/ralphy:archive` | Complete and archive |
+| `/ralphy-plan` | Create specs from requirements |
+| `/ralphy-implement` | Build with iterative loop |
+| `/ralphy-validate` | Verify acceptance criteria |
+| `/ralphy-archive` | Complete and archive |
 
 ### OpenCode
 
@@ -50,16 +61,16 @@ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</pro
 
 ```bash
 # 1. Plan: Create spec from your idea
-You: /ralphy:plan Add user authentication with JWT
+You: /ralphy-plan Add user authentication with JWT
 
 # 2. Implement: AI builds it iteratively  
-You: /ralphy:implement add-user-auth
+You: /ralphy-implement add-user-auth
 
 # 3. Validate: Verify tests pass
-You: /ralphy:validate
+You: /ralphy-validate
 
 # 4. Archive: Complete the change
-You: /ralphy:archive add-user-auth
+You: /ralphy-archive add-user-auth
 ```
 
 ## What Gets Created
@@ -79,11 +90,23 @@ openspec/
 ├── archive/              # Completed
 └── project.md            # Context
 
-.ralphy/
-├── config.json
-└── ralph-loop.state.json
+ralphy-spec/              # Local state + artifacts (IDE-friendly)
+├── state.db              # SQLite run/task ledger
+├── STATUS.md             # Live run snapshot (primary for `ralphy-spec status`)
+├── TASKS.md              # Task board view
+├── BUDGET.md             # Spend/budget breakdown
+├── runs/                 # Immutable run logs (`runs/<runId>.md`)
+├── logs/                 # Raw backend outputs (best-effort)
+├── worktrees/            # Git worktrees per task (when enabled)
+└── tasks/                # Per-task artifacts (CONTEXT / REPAIR / NOTES)
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
+> Note: Legacy `.ralphy/` folders are migrated to `ralphy-spec/` automatically when found.
+
 ## How It Works
 
 **Ralph Wiggum Loop:** AI receives the same prompt repeatedly until task completion. Each iteration, it sees previous work in files and self-corrects.

package/README.zh.md

@@ -5,6 +5,8 @@
 **规范驱动的 AI 开发 + 迭代执行。** 结合 OpenSpec 和 Ralph 循环，实现可预测的 AI 辅助编码。
 
 **官网：** [https://ralphy-spec.org](https://ralphy-spec.org)
+**文档：** [https://ralphy-spec.org/zh/docs/](https://ralphy-spec.org/zh/docs/)
+**更新日志：** [https://ralphy-spec.org/zh/changelog/](https://ralphy-spec.org/zh/changelog/) · [GitHub](https://github.com/wenqingyu/ralphy-openspec/blob/main/CHANGELOG.md)
 
 ## 快速开始
 
@@ -12,25 +14,34 @@
 npx ralphy-spec init
 ```
 
+CLI 基础用法：
+
+```bash
+ralphy-spec run --dry-run
+ralphy-spec run
+ralphy-spec status
+ralphy-spec budget --json
+```
+
 然后使用你的 AI 工具对应的命令：
 
 ### Cursor
 
 | 命令 | 功能 |
 |------|------|
-| `/ralphy:plan` | 从需求创建规范 |
-| `/ralphy:implement` | 迭代循环构建 |
-| `/ralphy:validate` | 验证验收标准 |
-| `/ralphy:archive` | 完成并归档 |
+| `/ralphy-plan` | 从需求创建规范 |
+| `/ralphy-implement` | 迭代循环构建 |
+| `/ralphy-validate` | 验证验收标准 |
+| `/ralphy-archive` | 完成并归档 |
 
 ### Claude Code
 
 | 命令 | 功能 |
 |------|------|
-| `/ralphy:plan` | 从需求创建规范 |
-| `/ralphy:implement` | 迭代循环构建 |
-| `/ralphy:validate` | 验证验收标准 |
-| `/ralphy:archive` | 完成并归档 |
+| `/ralphy-plan` | 从需求创建规范 |
+| `/ralphy-implement` | 迭代循环构建 |
+| `/ralphy-validate` | 验证验收标准 |
+| `/ralphy-archive` | 完成并归档 |
 
 ### OpenCode
 
@@ -50,16 +61,16 @@ ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</pro
 
 ```bash
 # 1. 规划：从你的想法创建规范
-You: /ralphy:plan 添加 JWT 用户认证
+You: /ralphy-plan 添加 JWT 用户认证
 
 # 2. 实现：AI 迭代构建
-You: /ralphy:implement add-user-auth
+You: /ralphy-implement add-user-auth
 
 # 3. 验证：确保测试通过
-You: /ralphy:validate
+You: /ralphy-validate
 
 # 4. 归档：完成变更
-You: /ralphy:archive add-user-auth
+You: /ralphy-archive add-user-auth
 ```
 
 ## 创建的文件
@@ -79,11 +90,23 @@ openspec/
 ├── archive/              # 已完成
 └── project.md            # 上下文
 
-.ralphy/
-├── config.json
-└── ralph-loop.state.json
+ralphy-spec/              # 本地状态 + 可读产物（IDE 友好）
+├── state.db              # SQLite 运行/任务日志
+├── STATUS.md             # 实时状态（`ralphy-spec status` 优先读取）
+├── TASKS.md              # 任务看板
+├── BUDGET.md             # 花费/预算
+├── runs/                 # 不可变运行日志（`runs/<runId>.md`）
+├── logs/                 # 后端原始输出（尽力写入）
+├── worktrees/            # Git worktree（启用 worktree 模式时）
+└── tasks/                # 单任务产物（CONTEXT / REPAIR / NOTES）
+    └── <taskId>/
+        ├── CONTEXT.md
+        ├── REPAIR.md
+        └── NOTES.md
 ```
 
+> 注意：如果检测到旧的 `.ralphy/`，会自动迁移到 `ralphy-spec/` 并提示。
+
 ## 工作原理
 
 **Ralph Wiggum 循环：** AI 重复接收相同提示直到任务完成。每次迭代，它都能看到文件中的之前工作并自我纠正。

package/dist/cli/budget.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerBudgetCommand(program: Command): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/cli/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/cli/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwE5D"}

package/dist/cli/budget.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBudgetCommand = registerBudgetCommand;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const persistence_1 = require("../core/memory/persistence");
+const folders_1 = require("../core/folders");
+const spend_1 = require("../core/reporting/spend");
+const loader_1 = require("../core/spec/loader");
+function registerBudgetCommand(program) {
+    program
+        .command("budget")
+        .description("Show budget/spend information for the latest run")
+        .option("--json", "Machine-readable output", false)
+        .action(async (opts) => {
+        const repoRoot = process.cwd();
+        const candidateRoots = [];
+        try {
+            const spec = await new loader_1.SpecLoader(repoRoot).loadProjectSpec();
+            if (spec.artifacts?.rootDir)
+                candidateRoots.push(spec.artifacts.rootDir);
+        }
+        catch {
+            // ignore
+        }
+        candidateRoots.push(undefined);
+        for (const rootDir of candidateRoots) {
+            const budgetPath = node_path_1.default.join((0, folders_1.getRalphyRoot)(repoRoot, rootDir), folders_1.FILES.budget);
+            try {
+                const md = await promises_1.default.readFile(budgetPath, "utf8");
+                if (!opts.json) {
+                    process.stdout.write(md.trimEnd() + "\n");
+                    return;
+                }
+                // If JSON requested, fall back to DB-derived structure below.
+                break;
+            }
+            catch {
+                // try next
+            }
+        }
+        const persistence = await persistence_1.PersistenceLayer.openForRepo(repoRoot);
+        try {
+            const run = persistence.getLatestRun();
+            if (!run) {
+                process.stdout.write(opts.json ? JSON.stringify({ ok: true, run: null }) + "\n" : "No runs found.\n");
+                return;
+            }
+            const ledger = persistence.listLedger({ runId: run.runId, limit: 2000 });
+            const entries = (0, spend_1.extractSpendFromLedger)(ledger);
+            const breakdown = (0, spend_1.aggregateSpend)(entries);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({
+                    ok: true,
+                    runId: run.runId,
+                    spend: {
+                        total: breakdown.total,
+                        byTask: Object.fromEntries(breakdown.byTask),
+                        byBackend: Object.fromEntries(breakdown.byBackend),
+                        byPhase: Object.fromEntries(breakdown.byPhase),
+                        entries: breakdown.entries,
+                    },
+                }, null, 2) + "\n");
+            }
+            else {
+                process.stdout.write(`No ${folders_1.FILES.budget} artifact found.\nRun again with artifacts enabled to generate it.\n`);
+            }
+        }
+        finally {
+            persistence.close();
+        }
+    });
+}
+//# sourceMappingURL=budget.js.map

package/dist/cli/budget.js.map

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

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkC1D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwCzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyC1D"}

package/dist/cli/init.js

@@ -8,6 +8,7 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const detector_1 = require("../utils/detector");
 const installer_1 = require("../utils/installer");
 const paths_1 = require("../utils/paths");
+const folders_1 = require("../core/folders");
 function parseToolsArg(arg) {
     if (!arg)
         return undefined;
@@ -60,7 +61,12 @@ function registerInitCommand(program) {
         const tools = options.tools ?? (await promptForTools(defaultTools));
         await (0, installer_1.ensureOpenSpecScaffold)(options.dir);
         await (0, installer_1.installToolTemplates)(options.dir, tools, { force: options.force });
+        await (0, folders_1.ensureRalphyFolders)(options.dir);
         process.stdout.write(`Initialized Ralph-OpenSpec in ${options.dir}\nConfigured tools: ${tools.join(", ")}\n`);
+        process.stdout.write(`\nArtifact folder created: ${(0, folders_1.getRalphyRoot)(options.dir)}\n` +
+            `\n.gitignore suggestions:\n` +
+            `- Commit: ${(0, folders_1.getRalphyRoot)(options.dir)}/STATUS.md, ${(0, folders_1.getRalphyRoot)(options.dir)}/TASKS.md, ${(0, folders_1.getRalphyRoot)(options.dir)}/BUDGET.md\n` +
+            `- Ignore: ${(0, folders_1.getRalphyRoot)(options.dir)}/state.db, ${(0, folders_1.getRalphyRoot)(options.dir)}/runs/, ${(0, folders_1.getRalphyRoot)(options.dir)}/logs/, ${(0, folders_1.getRalphyRoot)(options.dir)}/worktrees/\n`);
     });
 }
 //# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

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

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+EzD"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiGzD"}

package/dist/cli/run.js

@@ -7,18 +7,42 @@ exports.registerRunCommand = registerRunCommand;
 const node_path_1 = __importDefault(require("node:path"));
 const loader_1 = require("../core/spec/loader");
 const dag_1 = require("../core/spec/dag");
+const claude_code_1 = require("../core/backends/claude-code");
+const cursor_1 = require("../core/backends/cursor");
 const noop_1 = require("../core/backends/noop");
+const opencode_1 = require("../core/backends/opencode");
 const patch_mode_1 = require("../core/workspace/patch-mode");
+const worktree_mode_1 = require("../core/workspace/worktree-mode");
 const loop_1 = require("../core/engine/loop");
+function createBackend(id) {
+    switch (id) {
+        case "cursor":
+            return new cursor_1.CursorBackend();
+        case "opencode":
+            return new opencode_1.OpenCodeBackend();
+        case "claude-code":
+            return new claude_code_1.ClaudeCodeBackend();
+        case "noop":
+            return new noop_1.NoopBackend("noop");
+        default:
+            // Fallback: treat as noop for unknown ids (but retain id for diagnostics).
+            return new noop_1.NoopBackend(id);
+    }
+}
 function registerRunCommand(program) {
     program
         .command("run")
         .description("Execute the ralphy-spec engine loop")
-        .option("--backend <id>", "Backend id: cursor|opencode|claude-code", "cursor")
-        .option("--workspace <mode>", "Workspace mode: worktree|patch", "patch")
+        .option("--backend <id>", "Backend id: cursor|opencode|claude-code|noop")
+        .option("--workspace <mode>", "Workspace mode: worktree|patch")
+        .option("--artifact-dir <dir>", "Override artifact root directory (enables artifacts)")
         .option("--task <taskId>", "Run a single task (skips dependency checks)")
         .option("--dry-run", "Validate spec and print plan only", false)
         .option("--json", "Machine-readable output", false)
+        .addHelpText("after", `\nConcepts:\n` +
+        `- Budget tiers: optimal -> warning -> hard. WARNING enables degrade behaviors; HARD blocks the task.\n` +
+        `- Sprint sizing: XS/S/M/L/XL (optional per task via sprint.size).\n` +
+        `- Sprint intent: fix|feature|refactor|infra (optional per task via sprint.intent).\n`)
         .action(async (opts) => {
         const repoRoot = process.cwd();
         const loader = new loader_1.SpecLoader(repoRoot);
@@ -32,6 +56,16 @@ function registerRunCommand(program) {
             process.exitCode = 4;
             return;
         }
+        if (opts.artifactDir) {
+            spec = {
+                ...spec,
+                artifacts: {
+                    ...(spec.artifacts ?? {}),
+                    enabled: true,
+                    rootDir: opts.artifactDir,
+                },
+            };
+        }
         // Always build DAG in run/dry-run to validate deps/cycles unless --task is used.
         try {
             if (!opts.task)
@@ -50,13 +84,12 @@ function registerRunCommand(program) {
             process.stdout.write(opts.json ? JSON.stringify(out, null, 2) + "\n" : `${plan.join("\n")}\n`);
             return;
         }
-        if (opts.workspace === "worktree") {
-            process.stderr.write(`Workspace mode "worktree" is not implemented in this MVP. Use --workspace patch.\n`);
-            process.exitCode = 6;
-            return;
-        }
-        const backend = new noop_1.NoopBackend(opts.backend);
-        const workspace = new patch_mode_1.PatchModeWorkspace(node_path_1.default.resolve(repoRoot));
+        const backendId = opts.backend ?? spec.defaults.backend ?? "cursor";
+        const workspaceMode = opts.workspace ?? spec.defaults.workspaceMode ?? "patch";
+        const backend = createBackend(backendId);
+        const workspace = workspaceMode === "worktree"
+            ? new worktree_mode_1.WorktreeModeWorkspace(node_path_1.default.resolve(repoRoot))
+            : new patch_mode_1.PatchModeWorkspace(node_path_1.default.resolve(repoRoot));
         const engine = new loop_1.EngineLoop();
         const outcome = await engine.run({
             repoRoot,