@c-d-cc/reap 0.12.0 → 0.13.1

package/README.ja.md

@@ -28,10 +28,10 @@ REAPはアプリケーションの設計知識 — Genome（アーキテクチ
 - [なぜREAPか？](#なぜreapか)
 - [インストール](#インストール)
 - [クイックスタート](#クイックスタート)
-- [ライフサイクル](#ライフサイクル)
-- [コアコンセプト](#コアコンセプト)
+- [ライフサイクル](#ライフサイクル-)
+- [コアコンセプト](#コアコンセプト-)
 - [分散ワークフロー — 並行開発](#分散ワークフロー--並行開発)
-- [CLIコマンド](#cliコマンド)
+- [CLIコマンド](#cliコマンド-)
 - [エージェント連携](#エージェント連携)
 - [`reap init`後のプロジェクト構造](#reap-init後のプロジェクト構造)
 - [系譜圧縮（Lineage Compression）](#系譜圧縮lineage-compression)
@@ -240,6 +240,24 @@ REAPはスラッシュコマンドとセッションフックを通じてAIエ
 
 v0.11.0より、28個のスラッシュコマンドが**1行`.md`ラッパー + TypeScriptスクリプト**構造に移行しました。各`.md`ファイルは`reap run <cmd>`を呼び出し、TSスクリプト（`src/cli/commands/run/`）がすべての決定論的ロジックを処理して、AIエージェントにstructured JSONで指示します。一貫性とテスト容易性が大幅に向上しました。
 
+### 署名ベースロック（Signature-Based Locking） [↗](https://reap.cc/docs/advanced)
+
+REAPは暗号学的nonceチェーンを使用してステージの順序を強制します。ステージコマンドが実行されると、スクリプトがワンタイムnonceを生成し、そのハッシュを`current.yml`に保存して、nonceをAIエージェントに返します。`/reap.next`はこのnonceがなければ進行できず、なければ拒否されます。
+
+```
+Stage Command          current.yml              /reap.next
+─────────────          ───────────              ──────────
+nonce生成 ────────────→ hash(nonce)を保存
+AIにnonce返却                              ←── AIがnonceを渡す
+                                               hash(nonce)を検証
+                                               ✓ ステージ前進
+```
+
+これにより以下を防止します：
+- **ステージのスキップ** — 実行されていないステージには有効なnonceが存在しない
+- **トークンの偽造** — ハッシュは一方向であり、ハッシュからnonceを推測することは不可能
+- **古いnonceの再利用** — 各nonceはワンタイムで、現在のステージにバインドされている
+
 ### autoSubagentモード
 
 `/reap.evolve`実行時、自動的にsubagentにGenerationライフサイクル全体を委任できます：

package/README.ko.md

@@ -29,7 +29,7 @@ REAP은 Application의 설계 지식 — Genome(아키텍처, 컨벤션, 제약
 - [설치](#설치)
 - [빠른 시작](#빠른-시작)
 - [생애주기 (Life Cycle)](#생애주기-life-cycle)
-- [핵심 개념](#핵심-개념)
+- [핵심 개념](#핵심-개념-)
 - [분산 워크플로우 — 병렬 개발](#분산-워크플로우--병렬-개발)
 - [CLI 명령어](#cli-명령어)
 - [에이전트 연동](#에이전트-연동)
@@ -240,6 +240,24 @@ REAP은 슬래시 커맨드와 세션 훅을 통해 AI 에이전트와 통합됩
 
 v0.11.0부터 28개 슬래시 커맨드가 **1줄 `.md` wrapper + TypeScript 스크립트** 구조로 전환되었습니다. 각 `.md` 파일은 `reap run <cmd>`를 호출하고, TS 스크립트(`src/cli/commands/run/`)가 모든 결정적 로직을 처리하여 AI에게 structured JSON으로 지시합니다. 일관성과 테스트 용이성이 크게 향상되었습니다.
 
+### 서명 기반 잠금 (Signature-Based Locking) [↗](https://reap.cc/docs/advanced)
+
+REAP은 암호학적 nonce 체인을 사용하여 stage 순서를 강제합니다. stage 커맨드가 실행되면 스크립트가 일회용 nonce를 생성하여 해시를 `current.yml`에 저장하고, nonce를 AI 에이전트에게 반환합니다. `/reap.next`는 이 nonce가 있어야 다음 단계로 진행할 수 있으며, 없으면 진행이 거부됩니다.
+
+```
+Stage Command          current.yml              /reap.next
+─────────────          ───────────              ──────────
+nonce 생성 ──────────→ hash(nonce) 저장
+AI에게 nonce 반환                          ←── AI가 nonce 전달
+                                               hash(nonce) 검증
+                                               ✓ stage 전진
+```
+
+이를 통해 방지하는 것:
+- **Stage 건너뛰기** — 실행되지 않은 stage에는 유효한 nonce가 존재하지 않음
+- **토큰 위조** — 해시는 단방향이므로 해시에서 nonce를 추측할 수 없음
+- **이전 nonce 재사용** — 각 nonce는 일회용이며 현재 stage에 바인딩됨
+
 ### autoSubagent 모드
 
 `/reap.evolve` 실행 시 자동으로 subagent에게 Generation lifecycle 전체를 위임할 수 있습니다:

package/README.md

@@ -28,13 +28,13 @@ REAP captures an application's design knowledge — the Genome (architecture, co
 - [Why REAP?](#why-reap)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Life Cycle](#life-cycle)
-- [Core Concepts](#core-concepts)
-- [Distributed Workflow for Parallel Development](#distributed-workflow-for-parallel-development)
-- [CLI Commands](#cli-commands)
+- [Life Cycle](#life-cycle-)
+- [Core Concepts](#core-concepts-)
+- [Distributed Workflow](#distributed-workflow-)
+- [CLI Commands](#cli-commands-)
 - [Agent Integration](#agent-integration)
 - [Project Structure](#project-structure-after-reap-init)
-- [Lineage Compression](#lineage-compression)
+- [Lineage Compression](#lineage-compression-)
 - [Evolution Flow](#evolution-flow)
 - [Presets](#presets)
 - [Entry Modes](#entry-modes)
@@ -239,6 +239,24 @@ REAP integrates with AI agents through slash commands and session hooks. Current
 
 Since v0.11.0, all 28 slash commands follow a **1-line `.md` wrapper + TypeScript script** pattern. Each `.md` file simply calls `reap run <cmd>`, and the TS script (`src/cli/commands/run/`) handles all deterministic logic — returning structured JSON instructions for the AI agent. This ensures consistency and testability.
 
+### Signature-Based Locking [↗](https://reap.cc/docs/advanced)
+
+REAP uses a cryptographic nonce chain to enforce stage ordering. When a stage command runs, the script generates a one-time nonce, stores its hash in `current.yml`, and returns the nonce to the AI agent. `/reap.next` requires this nonce to advance — without it, progression is rejected.
+
+```
+Stage Command          current.yml              /reap.next
+─────────────          ───────────              ──────────
+generate nonce ──────→ store hash(nonce)
+return nonce to AI                         ←── AI passes nonce
+                                               verify hash(nonce)
+                                               ✓ advance stage
+```
+
+This prevents:
+- **Skipping stages** — no valid nonce exists for stages that were not executed
+- **Forging tokens** — the hash is one-way; guessing the nonce from the hash is infeasible
+- **Replaying old nonces** — each nonce is single-use and bound to the current stage
+
 ### autoSubagent Mode
 
 When `/reap.evolve` is run, REAP can automatically delegate the entire generation lifecycle to a subagent. This is controlled by:

package/README.zh-CN.md

@@ -28,10 +28,10 @@ REAP记录应用程序的设计知识 — Genome（架构、约定、约束）
 - [为什么选择REAP？](#为什么选择reap)
 - [安装](#安装)
 - [快速开始](#快速开始)
-- [生命周期](#生命周期)
-- [核心概念](#核心概念)
+- [生命周期](#生命周期-)
+- [核心概念](#核心概念-)
 - [分布式工作流 — 并行开发](#分布式工作流--并行开发)
-- [CLI命令](#cli命令)
+- [CLI命令](#cli命令-)
 - [代理集成](#代理集成)
 - [`reap init`后的项目结构](#reap-init后的项目结构)
 - [谱系压缩（Lineage Compression）](#谱系压缩lineage-compression)
@@ -240,6 +240,24 @@ REAP通过斜杠命令和会话钩子与AI代理集成。当前支持的代理
 
 从v0.11.0开始，28个斜杠命令全部采用**1行`.md` wrapper + TypeScript脚本**模式。每个`.md`文件仅调用`reap run <cmd>`，TS脚本（`src/cli/commands/run/`）处理所有确定性逻辑，以structured JSON形式指示AI代理。大幅提升了一致性和可测试性。
 
+### 签名锁定（Signature-Based Locking） [↗](https://reap.cc/docs/advanced)
+
+REAP使用加密nonce链来强制执行阶段顺序。当阶段命令运行时，脚本生成一次性nonce，将其哈希存储在`current.yml`中，并将nonce返回给AI代理。`/reap.next`需要此nonce才能推进 — 没有它，推进将被拒绝。
+
+```
+Stage Command          current.yml              /reap.next
+─────────────          ───────────              ──────────
+生成nonce ────────────→ 存储hash(nonce)
+将nonce返回给AI                            ←── AI传递nonce
+                                               验证hash(nonce)
+                                               ✓ 阶段推进
+```
+
+这可以防止：
+- **跳过阶段** — 未执行的阶段不存在有效的nonce
+- **伪造令牌** — 哈希是单向的，从哈希推测nonce是不可行的
+- **重放旧nonce** — 每个nonce是一次性的，绑定到当前阶段
+
 ### autoSubagent模式
 
 执行`/reap.evolve`时，可自动将整个Generation生命周期委托给subagent：

package/dist/cli.js

@@ -9947,10 +9947,19 @@ var init_lineage = __esm(() => {
 });
 
 // src/core/generation.ts
-import { createHash } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import { hostname } from "os";
 import { readdir as readdir7, mkdir as mkdir4, rename, unlink as unlink3 } from "fs/promises";
 import { join as join8 } from "path";
+function generateStageToken(genId, stage) {
+  const nonce = randomBytes(16).toString("hex");
+  const hash = createHash("sha256").update(nonce + genId + stage).digest("hex");
+  return { nonce, hash };
+}
+function verifyStageToken(token, genId, stage, expectedHash) {
+  const computed = createHash("sha256").update(token + genId + stage).digest("hex");
+  return computed === expectedHash;
+}
 function generateGenHash(parents, goal, genomeHash, machineId, startedAt) {
   const input = JSON.stringify({ parents, goal, genomeHash, machineId, startedAt });
   return createHash("sha256").update(input).digest("hex").slice(0, 6);
@@ -10391,6 +10400,16 @@ async function execute(paths, _phase) {
   if (!state) {
     emitError("next", "No active Generation. Run /reap.start first.");
   }
+  if (state.expectedTokenHash) {
+    const args = process.argv.slice(2);
+    const nonce = args.find((a) => !a.startsWith("-") && a !== "run" && a !== "next");
+    if (!nonce) {
+      emitError("next", `Stage transition blocked: no token provided. The stage command outputs a nonce that must be passed to /reap.next. Example: /reap.next <nonce>. This ensures the stage command was actually executed — you cannot skip stages.`);
+    }
+    if (!verifyStageToken(nonce, state.id, state.stage, state.expectedTokenHash)) {
+      emitError("next", `Token verification failed. The provided nonce does not match. Re-run the current stage command (reap run ${state.stage}) to get a valid token. You cannot forge or guess the token.`);
+    }
+  }
   const isMerge = state.type === "merge";
   let nextStage;
   if (isMerge) {
@@ -10405,6 +10424,7 @@ async function execute(paths, _phase) {
   if (!state.timeline)
     state.timeline = [];
   state.timeline.push({ stage: nextStage, at: new Date().toISOString() });
+  state.expectedTokenHash = undefined;
   await gm.save(state);
   const artifactFile = isMerge ? MERGE_ARTIFACT[nextStage] : NORMAL_ARTIFACT[nextStage];
   if (artifactFile) {
@@ -10439,7 +10459,7 @@ async function execute(paths, _phase) {
     status: "ok",
     command: "next",
     phase: "done",
-    completed: ["gate", "advance-stage", "create-artifact", "hooks"],
+    completed: ["gate", "nonce-verify", "advance-stage", "create-artifact", "hooks"],
     context: {
       generationId: state.id,
       previousStage,
@@ -10478,7 +10498,24 @@ var exports_back = {};
 __export(exports_back, {
   execute: () => execute2
 });
-async function execute2(paths, phase) {
+function getFlag(args, name) {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+}
+function getPositionals(args, valueFlags) {
+  const result = [];
+  for (let i = 0;i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const flagName = args[i].slice(2);
+      if (valueFlags.includes(flagName) && i + 1 < args.length)
+        i++;
+      continue;
+    }
+    result.push(args[i]);
+  }
+  return result;
+}
+async function execute2(paths, phase, argv = []) {
   const gm = new GenerationManager(paths);
   const state = await gm.current();
   if (!state) {
@@ -10500,16 +10537,17 @@ async function execute2(paths, phase) {
         type: state.type,
         id: state.id
       },
-      prompt: "Ask the human: (1) target stage (default: previous stage), (2) reason for regression, (3) related refs. Then run: reap run back --phase apply. Pass via env: REAP_BACK_TARGET, REAP_BACK_REASON, REAP_BACK_REFS (comma-separated).",
+      prompt: 'Ask the human: (1) target stage (default: previous stage), (2) reason for regression, (3) related refs. Then run: reap run back --phase apply <target-stage> --reason "<reason>" --refs "<a,b,c>"',
       nextCommand: "reap run back --phase apply"
     });
   }
   if (phase === "apply") {
     const originalStage = state.stage;
-    const targetEnv = process.env.REAP_BACK_TARGET;
+    const positionals = getPositionals(argv, ["reason", "refs"]);
+    const targetArg = positionals[0];
     let target;
-    if (targetEnv) {
-      target = targetEnv;
+    if (targetArg) {
+      target = targetArg;
     } else if (isMerge) {
       target = MergeLifeCycle.prev(state.stage);
     } else {
@@ -10519,8 +10557,8 @@ async function execute2(paths, phase) {
     if (!canTransition) {
       emitError("back", `Cannot regress from '${originalStage}' to '${target}'.`);
     }
-    const reason = process.env.REAP_BACK_REASON ?? "No reason provided";
-    const refs = (process.env.REAP_BACK_REFS ?? "").split(",").filter(Boolean);
+    const reason = getFlag(argv, "reason") ?? "No reason provided";
+    const refs = (getFlag(argv, "refs") ?? "").split(",").filter(Boolean);
     state.stage = target;
     state.timeline.push({
       stage: target,
@@ -10652,7 +10690,27 @@ __export(exports_start, {
 });
 import { join as join15 } from "path";
 import { readdir as readdir12 } from "fs/promises";
-async function execute3(paths, phase) {
+function getFlag2(args, name) {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+}
+function getPositionals2(args, valueFlags) {
+  const result = [];
+  for (let i = 0;i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const flagName = args[i].slice(2);
+      if (valueFlags.includes(flagName) && i + 1 < args.length)
+        i++;
+      continue;
+    }
+    result.push(args[i]);
+  }
+  return result;
+}
+async function execute3(paths, phase, argv = []) {
+  const positionals = getPositionals2(argv, ["backlog"]);
+  const goal = positionals.join(" ") || undefined;
+  const backlogFile = getFlag2(argv, "backlog");
   const gm = new GenerationManager(paths);
   if (!phase || phase === "scan") {
     const state = await gm.current();
@@ -10666,14 +10724,13 @@ async function execute3(paths, phase) {
       phase: "collect-goal",
       completed: ["gate", "backlog-scan"],
       context: { backlogItems },
-      prompt: backlogItems.length > 0 ? "Present the backlog items to the human. Ask: select one or enter a new goal. Set REAP_START_GOAL and optionally REAP_START_BACKLOG_FILE (selected backlog filename). Then run: reap run start --phase create" : "Ask the human for the goal of this generation. Set REAP_START_GOAL. Then run: reap run start --phase create",
+      prompt: backlogItems.length > 0 ? 'Present the backlog items to the human. Ask: select one or enter a new goal. Then run: reap run start --phase create "<goal>" (add --backlog <filename> if selected from backlog)' : 'Ask the human for the goal of this generation. Then run: reap run start --phase create "<goal>"',
       nextCommand: "reap run start --phase create"
     });
   }
   if (phase === "create") {
-    const goal = process.env.REAP_START_GOAL;
     if (!goal) {
-      emitError("start", "REAP_START_GOAL environment variable is required.");
+      emitError("start", 'Goal is required. Usage: reap run start --phase create "<goal>"');
     }
     const existing = await gm.current();
     if (existing && existing.id) {
@@ -10685,7 +10742,9 @@ async function execute3(paths, phase) {
       genomeVersion = lineageEntries.filter((e) => e.startsWith("gen-")).length + 1;
     } catch {}
     const state = await gm.create(goal, genomeVersion);
-    const backlogFile = process.env.REAP_START_BACKLOG_FILE;
+    const { nonce, hash } = generateStageToken(state.id, state.stage);
+    state.expectedTokenHash = hash;
+    await gm.save(state);
     if (backlogFile) {
       await markBacklogConsumed(paths.backlog, backlogFile, state.id);
     }
@@ -10897,7 +10956,14 @@ __export(exports_abort, {
 });
 import { join as join17 } from "path";
 import { readdir as readdir13, unlink as unlink5 } from "fs/promises";
-async function execute5(paths, phase) {
+function getFlag3(args, name) {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+}
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+async function execute5(paths, phase, argv = []) {
   const gm = new GenerationManager(paths);
   const state = await gm.current();
   if (!state || !state.id) {
@@ -10923,17 +10989,16 @@ async function execute5(paths, phase) {
         "  - If changes: offer rollback / stash / hold.",
         "  - If no changes: skip.",
         "Ask: 'Goal과 진행 상황을 backlog에 저장할까요? (yes/no)'",
-        "Set env vars: REAP_ABORT_REASON, REAP_ABORT_SOURCE_ACTION (rollback|stash|hold|none), REAP_ABORT_SAVE_BACKLOG (yes|no).",
-        "Then run: reap run abort --phase execute"
+        'Then run: reap run abort --phase execute --reason "<reason>" --source-action <rollback|stash|hold|none> [--save-backlog]'
       ].join(`
 `),
       nextCommand: "reap run abort --phase execute"
     });
   }
   if (phase === "execute") {
-    const reason = process.env.REAP_ABORT_REASON ?? "No reason provided";
-    const sourceAction = process.env.REAP_ABORT_SOURCE_ACTION ?? "none";
-    const saveBacklog = process.env.REAP_ABORT_SAVE_BACKLOG === "yes";
+    const reason = getFlag3(argv, "reason") ?? "No reason provided";
+    const sourceAction = getFlag3(argv, "source-action") ?? "none";
+    const saveBacklog = hasFlag(argv, "save-backlog");
     let backlogSaved = false;
     if (saveBacklog) {
       const objectiveContent = await readTextFile(paths.artifact("01-objective.md"));
@@ -11152,6 +11217,9 @@ async function execute7(paths, phase) {
     if (!content || content.length < 50) {
       emitError("objective", "01-objective.md appears incomplete (too short). Fill in the objective before completing.");
     }
+    const { nonce, hash } = generateStageToken(state.id, state.stage);
+    state.expectedTokenHash = hash;
+    await gm.save(state);
     const hookResults = await executeHooks(paths.hooks, "onLifeObjected", paths.projectRoot);
     emitOutput({
       status: "ok",
@@ -11162,7 +11230,7 @@ async function execute7(paths, phase) {
         id: state.id,
         hookResults
       },
-      message: "Objective stage complete. Proceed to the Planning stage with /reap.next."
+      message: `Objective stage complete. Advance with: /reap.next ${nonce}`
     });
   }
 }
@@ -11274,6 +11342,9 @@ async function execute8(paths, phase) {
     if (!content || content.length < 50) {
       emitError("planning", "02-planning.md appears incomplete. Fill in the plan before completing.");
     }
+    const { nonce, hash } = generateStageToken(state.id, state.stage);
+    state.expectedTokenHash = hash;
+    await gm.save(state);
     const hookResults = await executeHooks(paths.hooks, "onLifePlanned", paths.projectRoot);
     emitOutput({
       status: "ok",
@@ -11284,7 +11355,7 @@ async function execute8(paths, phase) {
         id: state.id,
         hookResults
       },
-      message: "Planning stage complete. Proceed to the Implementation stage with /reap.next."
+      message: `Planning stage complete. Advance with: /reap.next ${nonce}`
     });
   }
 }
@@ -11392,6 +11463,9 @@ async function execute9(paths, phase) {
     if (!await fileExists(artifactPath)) {
       emitError("implementation", "03-implementation.md does not exist. Complete the implementation work first.");
     }
+    const { nonce, hash } = generateStageToken(state.id, state.stage);
+    state.expectedTokenHash = hash;
+    await gm.save(state);
     const hookResults = await executeHooks(paths.hooks, "onLifeImplemented", paths.projectRoot);
     emitOutput({
       status: "ok",
@@ -11402,7 +11476,7 @@ async function execute9(paths, phase) {
         id: state.id,
         hookResults
       },
-      message: "Implementation stage complete. Proceed to the Validation stage with /reap.next."
+      message: `Implementation stage complete. Advance with: /reap.next ${nonce}`
     });
   }
 }
@@ -11521,6 +11595,9 @@ async function execute10(paths, phase) {
     if (!await fileExists(artifactPath)) {
       emitError("validation", "04-validation.md does not exist. Complete the validation work first.");
     }
+    const { nonce, hash } = generateStageToken(state.id, state.stage);
+    state.expectedTokenHash = hash;
+    await gm.save(state);
     const hookResults = await executeHooks(paths.hooks, "onLifeValidated", paths.projectRoot);
     emitOutput({
       status: "ok",
@@ -11531,7 +11608,7 @@ async function execute10(paths, phase) {
         id: state.id,
         hookResults
       },
-      message: "Validation stage complete. Proceed to the Completion stage with /reap.next."
+      message: `Validation stage complete. Advance with: /reap.next ${nonce}`
     });
   }
 }
@@ -11606,6 +11683,12 @@ function buildSubagentPrompt(paths, state, genomeSummaries, backlogSummary) {
   lines.push("## Project");
   lines.push(`- Path: ${paths.projectRoot}`);
   lines.push("");
+  lines.push("## Stage Chain Token");
+  lines.push("- Each stage command returns a `stageToken` in its output context.");
+  lines.push("- You MUST pass this token to `/reap.next --token <TOKEN>` (or set `REAP_STAGE_TOKEN` env var).");
+  lines.push("- Without a valid token, stage transition will be REJECTED.");
+  lines.push("- If token is missing or mismatched, re-run the current stage command to obtain a new token.");
+  lines.push("");
   lines.push("## Commit Rules");
   lines.push("- Create a git commit after implementation and after completion.");
   lines.push("- Use conventional commit format: `feat|fix|chore(scope): description`");
@@ -12003,7 +12086,7 @@ function buildLines(versionDisplay, lang, stateDisplay) {
     ...buildCommandTable(lang),
     "",
     TOPICS_LINE[lang],
-    "Usage: REAP_HELP_TOPIC=<topic> reap run help",
+    "Usage: /reap.help <topic>",
     CONFIG_LINE[lang]
   ];
 }
@@ -12017,7 +12100,8 @@ async function execute15(paths) {
   const rawLang = detectLanguage(configContent);
   const supported = isSupportedLanguage(rawLang);
   const lang = supported ? rawLang : "en";
-  const topic = process.env.REAP_HELP_TOPIC;
+  const args = process.argv.slice(2).filter((a) => !a.startsWith("-") && a !== "run" && a !== "help");
+  const topic = args[0] || undefined;
   const stateDisplay = state?.id ? `Active: **${state.id}** — ${state.goal} (Stage: ${state.stage})` : "No active Generation → `/reap.start` or `/reap.evolve`";
   const lines = buildLines(versionDisplay, lang, stateDisplay);
   if (topic) {
@@ -12613,7 +12697,9 @@ var exports_merge_start = {};
 __export(exports_merge_start, {
   execute: () => execute17
 });
-async function execute17(paths, phase) {
+async function execute17(paths, phase, argv = []) {
+  const positionals = argv.filter((a) => !a.startsWith("--"));
+  const targetBranchArg = positionals[0];
   const gm = new GenerationManager(paths);
   if (!phase || phase === "collect") {
     const state = await gm.current();
@@ -12629,14 +12715,14 @@ async function execute17(paths, phase) {
       context: {
         currentBranch
       },
-      prompt: "Ask the human for the target branch to merge. Set REAP_MERGE_TARGET_BRANCH to the branch name. Then run: reap run merge-start --phase create",
+      prompt: "Ask the human for the target branch to merge. Then run: reap run merge-start --phase create <branch-name>",
       nextCommand: "reap run merge-start --phase create"
     });
   }
   if (phase === "create") {
-    const targetBranch = process.env.REAP_MERGE_TARGET_BRANCH;
+    const targetBranch = targetBranchArg;
     if (!targetBranch) {
-      emitError("merge-start", "REAP_MERGE_TARGET_BRANCH environment variable is required.");
+      emitError("merge-start", "Target branch is required. Usage: reap run merge-start --phase create <branch>");
     }
     const existing = await gm.current();
     if (existing && existing.id) {
@@ -13269,7 +13355,9 @@ var exports_merge = {};
 __export(exports_merge, {
   execute: () => execute25
 });
-async function execute25(paths, phase) {
+async function execute25(paths, phase, argv = []) {
+  const positionals = argv.filter((a) => !a.startsWith("--"));
+  const targetBranchArg = positionals[0];
   const gm = new GenerationManager(paths);
   if (!phase || phase === "detect") {
     const state = await gm.current();
@@ -13288,17 +13376,16 @@ async function execute25(paths, phase) {
         "## Merge -- Full Merge Generation for a Local Branch",
         "",
         "Ask the human for the target branch to merge.",
-        "Set REAP_MERGE_TARGET_BRANCH to the branch name.",
-        "Then run: reap run merge --phase check"
+        "Then run: reap run merge --phase check <branch-name>"
       ].join(`
 `),
       nextCommand: "reap run merge --phase check"
     });
   }
   if (phase === "check") {
-    const targetBranch = process.env.REAP_MERGE_TARGET_BRANCH;
+    const targetBranch = targetBranchArg;
     if (!targetBranch) {
-      emitError("merge", "REAP_MERGE_TARGET_BRANCH environment variable is required.");
+      emitError("merge", "Target branch is required. Usage: reap run merge --phase check <branch>");
     }
     if (!gitRefExists(targetBranch, paths.projectRoot)) {
       emitError("merge", `Branch "${targetBranch}" does not exist.`);
@@ -13313,7 +13400,7 @@ async function execute25(paths, phase) {
         phase: "start-merge",
         completed: ["gate", "branch-verify"],
         context: { targetBranch, currentBranch },
-        prompt: `No lineage found. Run /reap.merge.start with REAP_MERGE_TARGET_BRANCH=${targetBranch} to begin the merge generation, then /reap.merge.evolve.`,
+        prompt: `No lineage found. Run /reap.merge.start ${targetBranch} to begin the merge generation, then /reap.merge.evolve.`,
         nextCommand: `reap run merge-start --phase create`
       });
       return;
@@ -13336,9 +13423,8 @@ async function execute25(paths, phase) {
         `Current branch: ${currentBranch}`,
         "",
         "Execute the following sequence:",
-        `1. Set REAP_MERGE_TARGET_BRANCH=${targetBranch}`,
-        "2. Run /reap.merge.start (creates merge generation + detect report)",
-        "3. Run /reap.merge.evolve (runs detect -> mate -> merge -> sync -> validation -> completion)",
+        `1. Run /reap.merge.start ${targetBranch} (creates merge generation + detect report)`,
+        "2. Run /reap.merge.evolve (runs detect -> mate -> merge -> sync -> validation -> completion)",
         "",
         "The merge generation will be archived upon completion."
       ].join(`
@@ -13358,7 +13444,9 @@ var exports_pull = {};
 __export(exports_pull, {
   execute: () => execute26
 });
-async function execute26(paths, phase) {
+async function execute26(paths, phase, argv = []) {
+  const positionals = argv.filter((a) => !a.startsWith("--"));
+  const targetBranchArg = positionals[0];
   const gm = new GenerationManager(paths);
   if (!phase || phase === "fetch") {
     const state = await gm.current();
@@ -13378,17 +13466,16 @@ async function execute26(paths, phase) {
         "",
         "1. Run `git fetch origin`",
         "2. Ask the human for the target remote branch (e.g., `origin/main`)",
-        "3. Set REAP_PULL_TARGET_BRANCH to the branch name",
-        "4. Then run: reap run pull --phase check"
+        "3. Then run: reap run pull --phase check <branch-name>"
       ].join(`
 `),
       nextCommand: "reap run pull --phase check"
     });
   }
   if (phase === "check") {
-    const targetBranch = process.env.REAP_PULL_TARGET_BRANCH;
+    const targetBranch = targetBranchArg;
     if (!targetBranch) {
-      emitError("pull", "REAP_PULL_TARGET_BRANCH environment variable is required.");
+      emitError("pull", "Target branch is required. Usage: reap run pull --phase check <branch>");
     }
     if (!gitRefExists(targetBranch, paths.projectRoot)) {
       emitError("pull", `Branch "${targetBranch}" does not exist. Run \`git fetch\` first.`);
@@ -13459,10 +13546,9 @@ async function execute26(paths, phase) {
         "## Branches have diverged -- full merge required",
         "",
         "Execute the following sequence:",
-        `1. Set REAP_MERGE_TARGET_BRANCH=${targetBranch}`,
-        "2. Run /reap.merge.start (creates merge generation + detect report)",
-        "3. Run /reap.merge.evolve (runs detect -> mate -> merge -> sync -> validation -> completion)",
-        "4. Run `git submodule update --init` after merge completes"
+        `1. Run /reap.merge.start ${targetBranch} (creates merge generation + detect report)`,
+        "2. Run /reap.merge.evolve (runs detect -> mate -> merge -> sync -> validation -> completion)",
+        "3. Run `git submodule update --init` after merge completes"
       ].join(`
 `)
     });
@@ -13516,7 +13602,7 @@ __export(exports_run, {
   runCommand: () => runCommand
 });
 import { execSync as execSync6 } from "child_process";
-async function runCommand(command, phase) {
+async function runCommand(command, phase, argv = []) {
   const cwd = process.cwd();
   const paths = new ReapPaths(cwd);
   if (!await paths.isReapProject()) {
@@ -13528,12 +13614,12 @@ async function runCommand(command, phase) {
   }
   try {
     const mod = await loader();
-    await mod.execute(paths, phase);
+    await mod.execute(paths, phase, argv);
   } catch (err) {
     try {
       const config = await ConfigManager.read(paths);
       if (config.autoIssueReport) {
-        const version = "0.12.0";
+        const version = "0.13.1";
         const errMsg = err instanceof Error ? err.message : String(err);
         const title = `[auto] reap run ${command}: ${errMsg.slice(0, 80)}`;
         const body = [
@@ -14119,7 +14205,7 @@ async function initProject(projectRoot, projectName, entryMode, preset, onProgre
   }
   const detectedLanguage = await AgentRegistry.readLanguage();
   const config = {
-    version: "0.12.0",
+    version: "0.13.1",
     project: projectName,
     entryMode,
     strict: false,
@@ -14718,7 +14804,7 @@ async function updateProject(projectRoot, dryRun = false) {
       result.skipped.push(`.claude/commands/ (${reapCmdFiles.length} unchanged)`);
     }
     await migrateLegacyFiles(paths, dryRun, result);
-    const currentVersion = "0.12.0";
+    const currentVersion = "0.13.1";
     const migrationResult = await MigrationRunner.run(paths, currentVersion, dryRun);
     for (const m of migrationResult.migrated) {
       result.updated.push(`[migration] ${m}`);
@@ -14916,7 +15002,7 @@ init_fs();
 init_version();
 init_config();
 import { join as join26 } from "path";
-program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.12.0");
+program.name("reap").description("REAP — Recursive Evolutionary Autonomous Pipeline").version("0.13.1");
 program.command("init").description("Initialize a new REAP project (Genesis)").argument("[project-name]", "Project name (defaults to current directory name)").option("-m, --mode <mode>", "Entry mode: greenfield, migration, adoption", "greenfield").option("-p, --preset <preset>", "Bootstrap with a genome preset (e.g., bun-hono-react)").action(async (projectName, options) => {
   try {
     const cwd = process.cwd();
@@ -15060,8 +15146,17 @@ program.command("help").description("Show REAP commands, slash commands, and wor
   }
   console.log(helpText);
 });
-program.command("run <command>").description("Run a REAP command script (internal, used by slash commands)").option("--phase <phase>", "Start from a specific phase").action(async (command, options) => {
+program.command("run <command>").description("Run a REAP command script (internal, used by slash commands)").option("--phase <phase>", "Start from a specific phase").allowUnknownOption().action(async (command, options, cmd) => {
+  const rawArgs = cmd.args.slice(1);
+  const passArgs = [];
+  for (let i = 0;i < rawArgs.length; i++) {
+    if (rawArgs[i] === "--phase") {
+      i++;
+      continue;
+    }
+    passArgs.push(rawArgs[i]);
+  }
   const { runCommand: runCommand2 } = await Promise.resolve().then(() => (init_run(), exports_run));
-  await runCommand2(command, options.phase);
+  await runCommand2(command, options.phase, passArgs);
 });
 program.parse();

package/dist/templates/commands/reap.abort.md

@@ -2,4 +2,4 @@
 description: "REAP Abort — Abort the current generation and return to initial state"
 ---
 
-Run `reap run abort` and follow the stdout instructions exactly.
+Run `reap run abort $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.back.md

@@ -2,4 +2,4 @@
 description: "REAP Back — Return to a previous lifecycle stage"
 ---
 
-Run `reap run back` and follow the stdout instructions exactly.
+Run `reap run back $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.help.md

@@ -2,4 +2,4 @@
 description: "REAP Help — Contextual help based on current state"
 ---
 
-Run `reap run help` and follow the stdout instructions exactly.
+Run `reap run help $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.merge.md

@@ -2,4 +2,4 @@
 description: "REAP Merge — Run a full merge generation for a local branch"
 ---
 
-Run `reap run merge` and follow the stdout instructions exactly.
+Run `reap run merge $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.merge.start.md

@@ -2,4 +2,4 @@
 description: "REAP Merge Start — Start a merge generation to combine divergent branches"
 ---
 
-Run `reap run merge-start` and follow the stdout instructions exactly.
+Run `reap run merge-start $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.next.md

@@ -2,4 +2,4 @@
 description: "REAP Next — Advance to the next lifecycle stage"
 ---
 
-Run `reap run next` and follow the stdout instructions exactly.
+Run `reap run next $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.pull.md

@@ -2,4 +2,4 @@
 description: "REAP Pull — Fetch remote, detect divergence, and run a full merge generation"
 ---
 
-Run `reap run pull` and follow the stdout instructions exactly.
+Run `reap run pull $ARGUMENTS` and follow the stdout instructions exactly.

package/dist/templates/commands/reap.start.md

@@ -2,4 +2,4 @@
 description: "REAP Start — Start a new Generation"
 ---
 
-Run `reap run start` and follow the stdout instructions exactly.
+Run `reap run start $ARGUMENTS` and follow the stdout instructions exactly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c-d-cc/reap",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Recursive Evolutionary Autonomous Pipeline — AI and humans evolve software across generations",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "dist/",
     "scripts/postinstall.cjs"
   ],
+  "preferGlobal": true,
   "engines": {
     "node": ">=18"
   },

package/scripts/postinstall.cjs

@@ -10,6 +10,14 @@ const { join, dirname } = require("path");
 const { homedir } = require("os");
 
 try {
+  // Warn if installed locally instead of globally
+  const isGlobal = process.env.npm_config_global === "true"
+    || (process.env.npm_config_prefix && !process.env.npm_config_prefix.includes("node_modules"));
+  if (!isGlobal) {
+    console.warn("\n  ⚠ @c-d-cc/reap is a CLI tool and should be installed globally:");
+    console.warn("    npm install -g @c-d-cc/reap\n");
+  }
+
   // Resolve commands source: dist/templates/commands/ relative to this script
   const commandsSource = join(dirname(__dirname), "dist", "templates", "commands");
   if (!existsSync(commandsSource)) {