@warpgogol/forge 2.21.1 → 2.21.5

package/README.md

@@ -16,6 +16,18 @@ Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my
 
 Replace `[describe your project]` with your idea — a game, a library, a knowledge base, anything. The AI agent installs Forge, scaffolds the project, and sets up a live preview. From there on, you just talk: describe what you want, and the agent builds it. No programming, no terminal, no commands.
 
+### After the prompt completes — the Bootstrap skill
+
+Once the AI agent has installed Forge and scaffolded your project, it will run the `/forge-bootstrap` skill. This is a required step that configures your project interactively:
+
+- The language the AI uses to communicate with you
+- The language for project documentation (RFCs, ADRs, READMEs) — defaults to English
+- Your preferred working style — business or creative
+- Your name and how you want to be addressed
+- Your stack configuration (or migration of an existing project)
+
+The skill asks a few simple questions in the chat, then sets everything up. After it completes, you're ready to create — just tell the AI agent what you want to build.
+
 ---
 
 ## What you can build with Forge
@@ -347,6 +359,94 @@ pnpm exec forge rfc.validate
 pnpm exec forge skill.list
 ```
 
+---
+
+## Working with your AI agent
+
+Forge works with any AI agent — Windsurf, Cursor, Claude Code, Codex CLI, or any IDE that supports agent skills. The setup is the same; only the conversation matters. Here are the patterns that make the biggest difference.
+
+### Start with questions, not commands
+
+The single most effective habit: before asking the agent to write code, ask it about the codebase. The agent can read files, search git history, and run Forge CLI commands — let it explore first.
+
+Good questions to start a session:
+
+- "How is this project structured?"
+- "What skills are available and what do they do?"
+- "Walk me through the RFC workflow in this project."
+- "What did we change this week?" (the agent reads git log)
+- "Why does this function have 15 parameters? Check git history."
+
+This works for onboarding too — new team members can get up to speed by asking the agent questions instead of reading code manually. The agent reads everything locally; nothing is uploaded or trained on.
+
+### AGENTS.md — your project's persistent memory
+
+Forge generates `AGENTS.md` files at the project root and in each workspace directory. The agent reads them automatically at the start of every session — think of them as instructions that survive between conversations.
+
+**What to put in AGENTS.md:**
+
+- Build and test commands (`pnpm test`, `pnpm run build:check`)
+- Code style conventions ("use 2 spaces, not tabs")
+- Architecture decisions ("the game package owns all scene logic")
+- "Do X, not Y" rules ("use `resolveImage()` for all image props, never raw `src`")
+- Common mistakes to avoid
+
+**When the agent makes a mistake**, tell it to update AGENTS.md so it doesn't repeat the error. Over time, AGENTS.md accumulates the team's hard-won knowledge.
+
+Forge generates AGENTS.md from `forge.yaml` via `forge.agents.generate`. Hand-written AGENTS.md files (without the generated marker) are preserved. Generated ones are regenerated when you run `forge upgrade` or `forge.agents.generate` — so put your custom rules in `forge.yaml` or in a hand-written AGENTS.md, not in a generated one.
+
+### Describe results, not steps
+
+The agent is an autonomous worker, not a typewriter. Tell it what you want, not how to do it.
+
+**Bad** (over-specified):
+
+> Open src/game/player.ts, add a function called calculateScore that takes a number array, sum it, return the result. Then open src/game/player.test.ts and add a test.
+
+**Good** (result-oriented):
+
+> Add a scoring system that calculates total points from collected items.
+
+For complex work, ask the agent to plan first:
+
+> I want to add a multiplayer mode. Make a plan first, show it to me, and wait for my approval before implementing.
+
+Forge's `/fo-idea` skill formalizes this: idea → audit → plan → implement → review. You can invoke it explicitly, or the agent will follow the pattern when the task is complex enough.
+
+### Let the agent explore
+
+Don't over-explain. The agent knows how to read files, search code, check git history, and run commands. Instead of pointing it to specific files, describe what you want to understand or change:
+
+**Instead of:** "Look in the src/game folder for player.ts and check if it has a move function."
+
+**Say:** "How does player movement work?"
+
+The agent will find the relevant files, trace the call chain, and explain it back to you. If it needs more context, it will ask.
+
+### Parallel work
+
+You can run multiple agent sessions simultaneously — in separate IDE windows, terminal tabs, or git worktrees. Each session works independently.
+
+This is useful for:
+
+- Writing an RFC in one session while implementing a different feature in another
+- Exploring two design approaches in parallel before committing to one
+- Running a long validation in one session while continuing work in another
+
+If you use the Werkstatt engine, its mission system keeps work isolated — each mission has its own workpiece directory, so parallel sessions don't conflict.
+
+### Let the agent verify its own work
+
+Give the agent criteria for "done" and let it check itself:
+
+- "Run the tests after you're done."
+- "Validate the RFC before committing."
+- "Check project health with `forge doctor`."
+
+Forge provides the tools — `forge doctor`, `forge rfc.validate`, `forge skill.list`, test runners. Tell the agent to use them. The agent can run commands, read the output, and fix issues without your intervention.
+
+---
+
 ## Stack profiles
 
 A stack profile defines the project scaffold: directory structure, dependencies, CI config, and first workspace. Choose a profile with `--profile` when creating a new project.

package/README.uk.md

@@ -16,6 +16,18 @@ Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my
 
 Замініть `[опишіть ваш проєкт]` на вашу ідею — гра, бібліотека, база знань, будь-що. ШІ-агент встановить Forge, згенерує каркас проєкту та налаштує живий перегляд. Далі ви просто розмовляєте: описуєте, що хочете, і агент будує це. Жодного програмування, жодного терміналу, жодних команд.
 
+### Після виконання промпту — навичка Bootstrap
+
+Коли ШІ-агент встановить Forge і згенерує каркас проєкту, він запустить навичку `/forge-bootstrap`. Це обов'язковий крок, який інтерактивно налаштовує ваш проєкт:
+
+- Мову, якою ШІ спілкується з вами
+- Мову документації проєкту (RFC, ADR, README) — за замовчуванням англійська
+- Ваш стиль роботи — діловий або творчий
+- Ваше ім'я та форму звертання
+- Конфігурацію стеку (або міграцію наявного проєкту)
+
+Навичка ставить кілька простих запитань у чаті, а потім налаштовує все. Після завершення ви готові творити — просто скажіть ШІ-агенту, що ви хочете створити.
+
 ---
 
 ## Що можна створити за допомогою Forge
@@ -338,6 +350,94 @@ pnpm exec forge rfc.validate
 pnpm exec forge skill.list
 ```
 
+---
+
+## Робота з вашим ШІ-агентом
+
+Forge працює з будь-яким ШІ-агентом — Windsurf, Cursor, Claude Code, Codex CLI або будь-яким IDE, що підтримує навички агентів. Налаштування однакове; важлива лише розмова. Ось патерни, які дають найбільший ефект.
+
+### Починайте з питань, а не з команд
+
+Найефективніша звичка: перед тим, як просити агента писати код, запитайте його про кодову базу. Агент може читати файли, шукати в історії git та запускати CLI-команди Forge — дайте йому спочатку дослідити.
+
+Добрі питання для початку сесії:
+
+- "Як структурований цей проєкт?"
+- "Які навички доступні і що вони роблять?"
+- "Проведи мене через RFC робочий процес у цьому проєкті."
+- "Що ми змінили цього тижня?" (агент читає git log)
+- "Чому ця функція має 15 параметрів? Перевір історію git."
+
+Це працює і для онбордингу — нові члени команди можуть швидко ввійти в курс справи, запитуючи агента, замість того, щоб вручну читати код. Агент читає все локально; нічого не завантажується та не тренується на вашому коді.
+
+### AGENTS.md — постійна пам'ять вашого проєкту
+
+Forge генерує файли `AGENTS.md` в корені проєкту та в кожній директорії робочого простору. Агент читає їх автоматично на початку кожної сесії — сприймайте їх як інструкції, які зберігаються між розмовами.
+
+**Що писати в AGENTS.md:**
+
+- Команди збірки та тестування (`pnpm test`, `pnpm run build:check`)
+- Угоди стилю коду ("використовуйте 2 пробіли, а не таби")
+- Архітектурні рішення ("пакет гри володіє всією логікою сцен")
+- Правила "роби X, а не Y" ("використовуйте `resolveImage()` для всіх image-пропів, ніколи сирий `src`")
+- Типові помилки, яких слід уникати
+
+**Коли агент помиляється**, скажіть йому оновити AGENTS.md, щоб він не повторював помилку. З часом AGENTS.md накопичує здобуті командою знання.
+
+Forge генерує AGENTS.md з `forge.yaml` через `forge.agents.generate`. Написані вручну AGENTS.md (без згенерованого маркера) зберігаються. Згенеровані файли регенеруються при запуску `forge upgrade` або `forge.agents.generate` — тому кладіть свої правила в `forge.yaml` або в написаний вручну AGENTS.md, а не в згенерований.
+
+### Описуйте результат, а не кроки
+
+Агент — автономний працівник, а не друкарська машинка. Скажіть йому, що ви хочете, а не як це зробити.
+
+**Погано** (занадто детально):
+
+> Відкрий src/game/player.ts, додай функцію calculateScore, яка приймає масив чисел, сумує його, повертає результат. Потім відкрий src/game/player.test.ts і додай тест.
+
+**Добре** (орієнтовано на результат):
+
+> Додай систему підрахунку очок, яка обчислює загальні бали за зібрані предмети.
+
+Для складних задач просіть агента спочатку спланувати:
+
+> Я хочу додати багатокористувацький режим. Спочатку склади план, покажи мені, і чекай на моє схвалення перед реалізацією.
+
+Навичка Forge `/fo-idea` формалізує це: ідея → аудит → план → реалізація → рев'ю. Ви можете викликати її явно, або агент буде слідувати цьому патерну, коли задача достатньо складна.
+
+### Дайте агенту дослідити
+
+Не пояснюйте занадто детально. Агент вміє читати файли, шукати в коді, перевіряти історію git та запускати команди. Замість того, щоб вказувати на конкретні файли, опишіть, що ви хочете зрозуміти або змінити:
+
+**Замість:** "Подивись у папці src/game файл player.ts і перевір, чи є там функція move."
+
+**Скажіть:** "Як працює рух гравця?"
+
+Агент знайде відповідні файли, простежить ланцюг викликів і пояснить вам. Якщо йому потрібен буде додатковий контекст, він запитає.
+
+### Паралельна робота
+
+Ви можете запускати кілька сесій агента одночасно — в різних вікнах IDE, вкладках терміналу або git worktrees. Кожна сесія працює незалежно.
+
+Це корисно для:
+
+- Написання RFC в одній сесії, паралельно з реалізацією іншої функції в іншій
+- Дослідження двох дизайн-підходів паралельно перед вибором одного
+- Запуску тривалої валідації в одній сесії, продовжуючи роботу в іншій
+
+Якщо ви використовуєте рушій Werkstatt, його система місій ізолює роботу — кожна місія має власну директорію workpiece, тому паралельні сесії не конфліктують.
+
+### Дозвольте агенту перевіряти власну роботу
+
+Дайте агенту критерії "готово" і дозвольте йому перевірити себе:
+
+- "Запусти тести після завершення."
+- "Валідуй RFC перед комітом."
+- "Перевір стан проєкту через `forge doctor`."
+
+Forge надає інструменти — `forge doctor`, `forge rfc.validate`, `forge skill.list`, тест-ранери. Скажіть агенту використовувати їх. Агент може запускати команди, читати вивід та виправляти проблеми без вашої втручання.
+
+---
+
 ## Профілі стеку
 
 Профіль стеку визначає каркас проєкту: структуру директорій, залежності, конфігурацію CI та перший робочий простір. Оберіть профіль прапорцем `--profile` під час створення проєкту.

package/os/mission/handlers/archive.test.ts

@@ -147,16 +147,16 @@ describe("mission.archive", () => {
     expect(data.skipped.some((s) => s.reason === "destination exists")).toBe(true);
   });
 
-  test("unreadable manifest → skipped with 'unreadable manifest' reason", async () => {
+  test("unreadable manifest with empty dir → skipped with 'empty remnant' reason", async () => {
     const missionDir = path.join(missionsDir, "test-m008");
     await fs.mkdir(missionDir, { recursive: true });
-    // No mission.yaml — unreadable
+    // No mission.yaml, no workpiece — empty remnant
 
     const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
 
     expect(data.moved).toHaveLength(0);
     expect(data.skipped).toHaveLength(1);
-    expect(data.skipped[0].reason).toBe("unreadable manifest");
+    expect(data.skipped[0].reason).toBe("empty remnant — use --clean-orphans to remove");
   });
 
   test("open mission in archive/ → moved back to missions/ (bidirectional)", async () => {
@@ -388,4 +388,134 @@ describe("mission.archive", () => {
     );
     expect(installCall).toBeUndefined();
   });
+
+  // RFC-0982: Fallback state detection and --clean-orphans tests
+
+  test("RFC-0982: orphaned workpiece with only .astro/ cache → state detected as closed, archived", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-01");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(path.join(workpieceDir, ".astro"), { recursive: true });
+    await fs.writeFile(path.join(workpieceDir, ".astro", "cache.txt"), "cache\n");
+    // No mission.yaml — orphaned remnant
+
+    const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
+
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].missionId).toBe("test-r982-01");
+    expect(data.moved[0].state).toBe("closed");
+    expect(data.moved[0].direction).toBe("into-archive");
+    expect(existsSync(path.join(missionsDir, "archive", "closed", "test-r982-01"))).toBe(true);
+  });
+
+  test("RFC-0982: .closed marker fallback → state detected as closed", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-02");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(workpieceDir, { recursive: true });
+    await fs.writeFile(path.join(workpieceDir, ".closed"), "2026-08-29T12:00:00Z\n");
+    // Also add a source file so it's not cache-only
+    await fs.writeFile(path.join(workpieceDir, "src.ts"), "// source\n");
+    // No mission.yaml — but .closed marker present
+
+    const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
+
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].missionId).toBe("test-r982-02");
+    expect(data.moved[0].state).toBe("closed");
+    expect(existsSync(path.join(missionsDir, "archive", "closed", "test-r982-02"))).toBe(true);
+  });
+
+  test("RFC-0982: --clean-orphans trashes orphaned remnant dir", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-03");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(path.join(workpieceDir, ".astro"), { recursive: true });
+    await fs.writeFile(path.join(workpieceDir, ".astro", "cache.txt"), "cache\n");
+    // No mission.yaml — orphaned remnant with only cache
+
+    const data = unwrap(
+      await runMissionArchive(makeInput({ "clean-orphans": true }), makeContext(tmpDir)),
+    );
+
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].missionId).toBe("test-r982-03");
+    expect(data.moved[0].direction).toBe("trashed-orphan");
+    expect(data.moved[0].to).toBe("(trashed)");
+    expect(existsSync(missionDir)).toBe(false);
+  });
+
+  test("RFC-0982: --clean-orphans --dry-run → reported but not trashed", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-04");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(path.join(workpieceDir, ".astro"), { recursive: true });
+    await fs.writeFile(path.join(workpieceDir, ".astro", "cache.txt"), "cache\n");
+
+    const data = unwrap(
+      await runMissionArchive(
+        makeInput({ "clean-orphans": true, "dry-run": true }),
+        makeContext(tmpDir),
+      ),
+    );
+
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].direction).toBe("trashed-orphan");
+    expect(data.dryRun).toBe(true);
+    // Dir should still exist in dry-run
+    expect(existsSync(missionDir)).toBe(true);
+  });
+
+  test("RFC-0982: --clean-orphans skips non-orphaned dir with mission.yaml", async () => {
+    await writeMissionManifest(missionsDir, "test-r982-05", "closed");
+    const workpieceDir = path.join(missionsDir, "test-r982-05", "workpiece");
+    await fs.mkdir(path.join(workpieceDir, ".astro"), { recursive: true });
+
+    const data = unwrap(
+      await runMissionArchive(makeInput({ "clean-orphans": true }), makeContext(tmpDir)),
+    );
+
+    // Should be archived normally, not trashed
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].direction).toBe("into-archive");
+    expect(existsSync(path.join(missionsDir, "archive", "closed", "test-r982-05"))).toBe(true);
+  });
+
+  test("RFC-0982: skip reason 'manually inspect' for dir with non-cache content but no mission.yaml", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-06");
+    const workpieceDir = path.join(missionDir, "workpiece");
+    await fs.mkdir(workpieceDir, { recursive: true });
+    // Source file in workpiece — non-cache content, no .closed marker
+    await fs.writeFile(path.join(workpieceDir, "src.ts"), "// source code\n");
+    // No mission.yaml
+
+    const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
+
+    expect(data.moved).toHaveLength(0);
+    expect(data.skipped).toHaveLength(1);
+    expect(data.skipped[0].reason).toContain("manually inspect");
+  });
+
+  test("RFC-0982: --clean-orphans trashes empty remnant dir (no workpiece, no mission.yaml)", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-08");
+    await fs.mkdir(missionDir, { recursive: true });
+    // No mission.yaml, no workpiece — empty remnant, state would be null
+
+    const data = unwrap(
+      await runMissionArchive(makeInput({ "clean-orphans": true }), makeContext(tmpDir)),
+    );
+
+    expect(data.moved).toHaveLength(1);
+    expect(data.moved[0].missionId).toBe("test-r982-08");
+    expect(data.moved[0].direction).toBe("trashed-orphan");
+    expect(existsSync(missionDir)).toBe(false);
+  });
+
+  test("RFC-0982: skip reason 'use --clean-orphans' for empty remnant dir", async () => {
+    const missionDir = path.join(missionsDir, "test-r982-07");
+    await fs.mkdir(missionDir, { recursive: true });
+    // No mission.yaml, no workpiece, no content — empty remnant
+
+    const data = unwrap(await runMissionArchive(makeInput(), makeContext(tmpDir)));
+
+    expect(data.moved).toHaveLength(0);
+    expect(data.skipped).toHaveLength(1);
+    expect(data.skipped[0].reason).toContain("use --clean-orphans");
+  });
 });

package/os/mission/handlers/archive.ts

@@ -18,6 +18,7 @@ archive subdirectories back to missions/.
   <item>RFC-0801: add service-folder cleanup (node_modules, dist, .astro, .wrangler, .cache, .turbo) before archive move.</item>
   <item>RFC-0733: add pinned-files pre-check — skip pinned mission directories with warning instead of moving them.</item>
   <item>RFC-0804: auto-refresh pnpm-lock.yaml after directory moves.</item>
+  <item>RFC-0982: fallback state detection for orphaned workpiece dirs (no mission.yaml) via .closed marker and cache-only heuristic; --clean-orphans flag; improved skip reasons.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -63,6 +64,11 @@ async function cleanServiceFolders(workpieceDir: string): Promise<string[]> {
   return removed;
 }
 
+// RFC-0982: Shared cache-entry predicate — prevents filter logic divergence.
+function isCacheEntry(name: string): boolean {
+  return name.startsWith(".") || name === "node_modules" || name === "dist";
+}
+
 async function readMissionState(missionDir: string): Promise<string | null> {
   const manifestPath = path.join(missionDir, "mission.yaml");
   try {
@@ -70,10 +76,64 @@ async function readMissionState(missionDir: string): Promise<string | null> {
     const parsed = parseYaml(raw) as Record<string, unknown>;
     const state = parsed?.state;
     if (typeof state === "string") return state.trim();
-    return null;
   } catch {
-    return null;
+    // Fall through to secondary checks
+  }
+
+  // RFC-0982: Secondary — check for workpiece/.closed marker
+  const closedMarker = path.join(missionDir, "workpiece", ".closed");
+  if (existsSync(closedMarker)) return "closed";
+
+  // RFC-0982: Tertiary — if workpiece/ exists and contains only cache entries,
+  // treat as closed (post-close remnant pattern)
+  const workpieceDir = path.join(missionDir, "workpiece");
+  if (existsSync(workpieceDir)) {
+    const entries = await fs.readdir(workpieceDir);
+    const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+    if (nonCacheEntries.length === 0) {
+      return "closed";
+    }
   }
+
+  return null;
+}
+
+// RFC-0982: Check if a mission directory is an orphaned remnant — no mission.yaml
+// and workpiece/ contains only cache entries (or no workpiece at all).
+async function isOrphanedRemnant(missionDir: string): Promise<boolean> {
+  const manifestPath = path.join(missionDir, "mission.yaml");
+  if (existsSync(manifestPath)) return false;
+
+  const workpieceDir = path.join(missionDir, "workpiece");
+  if (!existsSync(workpieceDir)) return true;
+
+  const entries = await fs.readdir(workpieceDir);
+  const nonCacheEntries = entries.filter((e) => !isCacheEntry(e));
+  return nonCacheEntries.length === 0;
+}
+
+// RFC-0982: Check if a mission directory has non-cache content (source files,
+// configs, etc.) that warrants manual inspection rather than auto-cleanup.
+async function hasNonCacheContent(missionDir: string): Promise<boolean> {
+  const entries = await fs.readdir(missionDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === "workpiece") continue;
+    if (entry.isDirectory() && isCacheEntry(entry.name)) {
+      continue;
+    }
+    // Any file or non-cache directory at mission root is content
+    return true;
+  }
+
+  // Check workpiece/ for non-cache content
+  const workpieceDir = path.join(missionDir, "workpiece");
+  if (existsSync(workpieceDir)) {
+    const wpEntries = await fs.readdir(workpieceDir);
+    const nonCacheEntries = wpEntries.filter((e) => !isCacheEntry(e));
+    if (nonCacheEntries.length > 0) return true;
+  }
+
+  return false;
 }
 
 interface MoveAttempt {
@@ -158,6 +218,7 @@ export async function runMissionArchive(
 
   const dryRun = context.dryRun || input.flags["dry-run"] === true;
   const statusFilter = input.flags["status"] as string | undefined;
+  const cleanOrphans = input.flags["clean-orphans"] === true;
 
   if (statusFilter && !MISSION_TERMINAL_STATUSES.includes(statusFilter as never)) {
     throw new Error(
@@ -223,13 +284,35 @@ export async function runMissionArchive(
 
   for (const missionId of rootDirs) {
     const missionDir = path.join(missionsPath, missionId);
+    const sourceRel = `${MISSIONS_DIR}/${missionId}`;
+
+    // RFC-0982: --clean-orphans — trash orphaned remnant directories before state
+    // detection. This catches dirs where mission.yaml is missing and only cache
+    // entries remain, regardless of whether readMissionState returns "closed" or null.
+    if (cleanOrphans && (await isOrphanedRemnant(missionDir))) {
+      if (!dryRun) {
+        await trashPath(missionDir);
+      }
+      moved.push({
+        missionId,
+        state: "closed",
+        from: sourceRel,
+        to: "(trashed)",
+        direction: "trashed-orphan",
+      });
+      continue;
+    }
+
     const state = await readMissionState(missionDir);
 
     if (state === null) {
+      const hasContent = await hasNonCacheContent(missionDir);
       skipped.push({
         missionId,
         dir: `${MISSIONS_DIR}/${missionId}`,
-        reason: "unreadable manifest",
+        reason: hasContent
+          ? "unreadable manifest — manually inspect or add mission.yaml"
+          : "empty remnant — use --clean-orphans to remove",
       });
       continue;
     }
@@ -257,7 +340,6 @@ export async function runMissionArchive(
     const targetDir = path.join(missionsPath, ARCHIVE_DIR_NAME, state);
     const targetPath = path.join(targetDir, missionId);
     const targetRel = `${MISSIONS_DIR}/${ARCHIVE_DIR_NAME}/${state}/${missionId}`;
-    const sourceRel = `${MISSIONS_DIR}/${missionId}`;
 
     // RFC-0733: Check if mission directory is pinned before moving
     // Gap fix: exempt intra-directory moves (dir stays within the same pinned parent)

package/os/mission/mission.module.ts

@@ -7,6 +7,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0573: initial forgeMissionModule registering mission.archive command.</item>
+  <item>RFC-0982: add --clean-orphans flag for trashing orphaned remnant directories.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -42,6 +43,11 @@ export const forgeMissionModule: ForgeModule = {
           kind: "string",
           description: "Filter to a single terminal status (closed, aborted).",
         },
+        "clean-orphans": {
+          kind: "boolean",
+          description:
+            "Trash orphaned directories (no mission.yaml, only cache files) instead of archiving them.",
+        },
       },
       execute: runMissionArchive,
     });

package/os/mission/types.ts

@@ -10,6 +10,7 @@ manifest state extraction, and archive result shapes.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0573: initial mission archive types.</item>
+  <item>RFC-0982: add "trashed-orphan" to MissionArchiveMove.direction.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -23,7 +24,7 @@ export interface MissionArchiveMove {
   state: string;
   from: string;
   to: string;
-  direction: "into-archive" | "out-of-archive";
+  direction: "into-archive" | "out-of-archive" | "trashed-orphan";
 }
 
 export interface MissionArchiveSkip {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.21.1",
+  "version": "2.21.5",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/skills/meta/forge-bootstrap/SKILL.md

@@ -66,12 +66,20 @@ Before any operator interaction, silently check whether the installed `@warpgogo
 
 Read `PREFERENCES.md` at the project root. `forge create` writes a placeholder with `aiLanguage: en` and `documentationLanguage: en`.
 
-Ask the operator:
+Ask the operator two questions, one at a time:
+
+**Question 1 — AI communication language:**
 
-> In which language should the AI communicate with you? (e.g. en, ru, uk, de, es) In which language should project documentation be written? (RFCs, ADRs, READMEs)
+> In which language should the AI communicate with you? (e.g. en, ru, uk, de, es)
 
 Accept free-form answers like "Russian", "русский", "uk" or "English". Prefer IETF BCP 47 language tags when the operator provides them.
 
+**Question 2 — Documentation language:**
+
+> In which language should project documentation be written? (RFCs, ADRs, READMEs) Press Enter to use English (default).
+
+Accept free-form answers like "Russian", "русский", "uk" or "English". If the operator presses Enter or says "default" / "English", use `en`. Prefer IETF BCP 47 language tags when the operator provides them.
+
 Write or merge the values into `PREFERENCES.md`. **All subsequent communication in this skill session uses the operator's chosen `aiLanguage`.**
 
 If `PREFERENCES.md` already has non-default `aiLanguage` set (re-run of the skill), confirm the existing values with the operator instead of asking again. The operator may change them if desired.

package/src/onboarding/create.ts

@@ -397,7 +397,7 @@ Your Forge project is ready. The next step is mandatory: run \`/forge-bootstrap\
 Run \`/forge-bootstrap\` now. It will ask you:
 
 - Which language the AI should communicate with you in
-- Which language project documentation should be written in
+- Which language project documentation should be written in (defaults to English)
 - Whether you prefer a business or creative working style
 - Your name and how you want to be addressed
 - Your stack configuration (or migrate an existing project)