@goodtek/vibeops 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to VibeOps are documented here.
 
+## Unreleased
+
+## 0.3.0 - 2026-05-13
+
+### Changed
+
+- **`vibeops plan` requires `vibeops init`**: exits early if `.vibeops.json` is missing so partial `.vibeops/` trees are not created outside a full VibeOps project.
+- **Interactive LLM planning** (default): OpenAI API key, **Codex (ChatGPT OAuth)** via `~/.codex/auth.json`, or **Cursor Agent CLI**; always lists all three providers; live model catalogs (`/v1/models`, Codex `/models` with `client_version`, `agent models`); **`--model`** skips the picker. Codex uses ChatGPT-account models (default **`gpt-5.4`**); **`VIBEOPS_CODEX_CLIENT_VERSION`** / `codex --version` / bundled default for `client_version`.
+- **Planning dialogue UX**: terminal **language picker** after model; **one question per turn**; **wrap up early** (`wrap` / `enough` or picker row) → `confirm` only; **go back** on pickers / `back` for text; **rough progress + ETA** line per question; **`confirm` then terminal Yes** before **`done`** ProjectBrief.
+- **`--apply-planner`**: second LLM pass from `plan-prompt.md`, parses `<!-- file: docs/... -->` fences, writes **`docs/project/*`** and **`docs/tasks/*`**; interactive **commit → optional `github init` before push → push → Notion sync** prompts; **`--apply-dry-run`**, **`--no-git-commit`**, **`--push`**, **`--no-notion-sync`**; optional **`git init`**, **`notion init`**, same flow as **`vibeops github init`** when setup is missing.
+- **LLM protocol / system prompt**: product-first pacing; session rule for wrap-up → `confirm` only.
+- **`vibeops task start`**: allows a dirty tree when changes are limited to governance doc paths (`docs/tasks/`, `docs/project/`, `docs/logs/`, `.vibeops/state/`).
+
 ## 0.2.0 - 2026-05-12
 
 Public release polish.

package/README.md

@@ -70,7 +70,8 @@ vibeops init
 # Non-interactive Git bootstrap:
 vibeops init --git --initial-commit
 
-# 2. Answer 20 short planning questions and generate a Cursor planning prompt.
+# 2. LLM planning session (OpenAI API key, Codex `codex login` / ~/.codex/auth.json, or Cursor `agent` CLI) → brief + planning prompt.
+#    Use `vibeops plan --legacy-wizard` for the original 20-question flow.
 vibeops plan
 
 # 3. Generate a TASK prompt or scaffold TASK markdown.
@@ -126,7 +127,7 @@ vibeops
 │       [--git|--no-git] [--initial-commit|--no-initial-commit]
 │       [--default-branch <name>] [--commit-message <message>]
 ├─ status [--json] [--cwd <path>]
-├─ plan [--idea <text>] [--from <path>] [--output <path>] [--non-interactive] [--cwd <path>]
+├─ plan [--idea <text>] [--from <path>] [--output <path>] [--non-interactive] [--legacy-wizard] [--provider <id>] [--cwd <path>]
 ├─ agent
 │  ├─ list [--json] [--cwd <path>]
 │  ├─ show <name> [--raw] [--cwd <path>]
@@ -159,7 +160,7 @@ Run any command with `--help` for the option details.
 
 ### Interactive Planner
 
-`vibeops plan` asks 20 short questions and produces a normalized brief plus a Cursor planning prompt. A non-interactive mode is available for safe placeholder output.
+`vibeops plan` runs only inside a **VibeOps project** (expects **`.vibeops.json`** from `vibeops init`). It writes `.vibeops/brief/project-brief.md` and `.vibeops/generated/plan-prompt.md`; with **`--apply-planner`** it also writes `docs/project/*` and `docs/tasks/*` via the LLM. The command uses **OpenAI** (`OPENAI_API_KEY`), **Codex (ChatGPT OAuth)** via tokens from `codex login` (`~/.codex/auth.json`, same OAuth client as Hermes/OpenClaw `openai-codex`), or the **Cursor Agent CLI** (`agent login`). With a TTY you **always pick** among those three (each line shows ✓ or “needs setup”; Codex can start browser OAuth from that menu). Pass `--provider` to skip the menu when that path is already ready. Then pick a **model** from the provider catalog (or `--model`). Next you pick the **planning dialogue language** (preset list + Other); the LLM asks **one question per turn** in that language. Each question header shows a **rough ASCII progress line** and **ETA hint** (assumes up to ~14 steps; not a guarantee). **Multi**-choice suggestions use **checkboxes** (Space, Other, **Wrap up — draft summary now** when allowed, then **Go back** last when you can undo); **single**-choice uses **arrow select** with **Other**, wrap-up, and **Go back** last (no extra Continue step). **Text** answers: type `back` alone to go back when allowed, or `wrap` / `enough` to stop questions and ask for a draft summary from the thread so far. When the model is ready, it shows a **readable markdown summary**; you must **confirm** before the `ProjectBrief` is written. After that, **`--apply-planner`** runs the planner pass via the same provider: fills `docs/project/*` and initial `docs/tasks/*`. With a **TTY** and without **`--non-interactive`**, you are then asked **in order**: create a **git commit** (default Yes; if Git is not initialized yet, you can run **`git init`** + branch **`main`** from the same prompts), **git push** (default No; use **`--push`** to skip the question and push after a successful commit; after you choose push, you can run **`vibeops github init`** to connect or create a GitHub repo / set **`origin`**, same as the standalone command), and **Notion sync** when the brief enables it (default Yes; **`--no-notion-sync`** skips; if Notion is not configured, you can run **`vibeops notion init`** from the same flow, then sync retries once ready). In **`--non-interactive`** mode, commit runs automatically (unless **`--no-git-commit`**), push only with **`--push`**, and Notion runs when the brief enables it (unless **`--no-notion-sync`**). **`--apply-dry-run`** asks the model which files it would emit without writing. Codex defaults to ChatGPT-account models (`gpt-5.4`; override with `VIBEOPS_CODEX_MODEL`). Use `--legacy-wizard` for the fixed 20-question flow. `--non-interactive` and `--from` never call an LLM for the brief unless you add `--apply-planner` with `--provider` (and optional `--model`) for the apply step.
 
 ### Task Generator
 
@@ -167,7 +168,7 @@ Run any command with `--help` for the option details.
 
 ### Git Task Lifecycle
 
-`task start`, `task prompt`, `task check`, and `task done` keep one TASK moving through `Planned → In Progress → Review → Done`. `task done` defaults to `Review`; use `--finalize` only after human review.
+`task start`, `task prompt`, `task check`, and `task done` keep one TASK moving through `Planned → In Progress → Review → Done`. `task done` defaults to `Review`; use `--finalize` only after human review. `task start` still expects a clean tree for application code, but if the only uncommitted changes live under `docs/tasks/`, `docs/project/`, `docs/logs/`, or `.vibeops/state/`, it warns and continues so a prior doc-only finalize does not block the next TASK.
 
 ### Rollback Safety
 

package/dist/cli.js

@@ -51,14 +51,41 @@ program
 });
 program
     .command("plan")
-    .description("Run 20 interactive questions and produce a ProjectBrief + Cursor planning prompt")
+    .description("Requires `vibeops init`: LLM planning → ProjectBrief + planning prompt; optional --apply-planner runs the planner via the same LLM (docs + TASKs, commit, push, Notion). Use --legacy-wizard for the fixed 20-question flow")
     .option("--idea <text>", "One-line idea default (use `Name: idea` to extract the project name)")
     .option("--from <path>", "Read an existing brief markdown and regenerate the prompt")
     .option("--output <path>", "Output path for the Cursor planning prompt (default `.vibeops/generated/plan-prompt.md`)")
-    .option("--non-interactive", "Skip prompts and use the supplied values plus safe placeholders")
+    .option("--non-interactive", "Skip prompts and use the supplied values plus safe placeholders (no LLM)")
+    .option("--legacy-wizard", "Use the original 20-question wizard instead of an LLM planning session")
+    .option("--provider <id>", "LLM provider when several are available: openai | codex-oauth | cursor-agent")
+    .option("--model <id>", "LLM model id for the selected provider (skips interactive model list; same as setting VIBEOPS_*_MODEL for that path)")
     .option("--cwd <path>", "Run against a different directory")
+    .option("--apply-planner", "After writing the brief + prompt: call the same LLM provider to emit docs/project + docs/tasks; then (TTY) ask commit → push → Notion in order, or (--non-interactive) commit unless --no-git-commit, push only with --push, Notion unless --no-notion-sync")
+    .option("--apply-dry-run", "With --apply-planner (or alone): call the LLM and list files that would be written; no writes, git, or Notion")
+    .option("--no-git-commit", "With --apply-planner: skip git commit after writes")
+    .option("--push", "With --apply-planner: run git push after commit (TTY: optional `vibeops github init` before push; skips the push Yes/No prompt)")
+    .option("--no-notion-sync", "With --apply-planner: skip Notion sync even when the brief enables it")
     .action(async (options) => {
-    await planCommand(options);
+    const provider = options.provider === "openai" ||
+        options.provider === "codex-oauth" ||
+        options.provider === "cursor-agent"
+        ? options.provider
+        : undefined;
+    await planCommand({
+        idea: options.idea,
+        from: options.from,
+        output: options.output,
+        nonInteractive: options.nonInteractive,
+        legacyWizard: options.legacyWizard === true,
+        provider,
+        llmModel: typeof options.model === "string" ? options.model : undefined,
+        cwd: options.cwd,
+        applyPlanner: options.applyPlanner === true,
+        applyPlannerDryRun: options.applyDryRun === true,
+        noGitCommit: options.noGitCommit === true,
+        gitPush: options.push === true,
+        noNotionSync: options.noNotionSync === true,
+    });
 });
 const agent = program
     .command("agent")
@@ -105,9 +132,9 @@ task
 });
 task
     .command("start <taskId>")
-    .description("Confirm a clean working tree, create the task branch, record Status/Git context, and print a Builder prompt")
+    .description("Confirm a clean working tree (or docs-only governance changes), create the task branch, record Status/Git context, and print a Builder prompt")
     .option("--dry-run", "Print the plan without touching files or Git")
-    .option("--allow-dirty", "Proceed even if the Git working tree is dirty")
+    .option("--allow-dirty", "Proceed even if the Git working tree is dirty (including non-doc changes)")
     .option("--agent <name>", "Agent to build the prompt with (default `builder`)")
     .option("--cwd <path>", "Run against a different directory")
     .action(async (taskId, options) => {

package/dist/commands/plan.js

@@ -1,8 +1,14 @@
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { briefToMarkdown, findMissingRequired, gatherBrief, parseBriefFromMarkdown, parseIdea, } from "../lib/brief.js";
+import { askYesNo } from "../lib/inquirer-helpers.js";
 import { pathExists, readText, writeText } from "../lib/filesystem.js";
 import { bold, cyan, dim, log, yellow } from "../lib/logger.js";
+import { applyPlannerMarkdownFlow, commitPlannerGit, pushPlannerGit } from "../lib/plan-apply-planner.js";
+import { gatherBriefViaLlm, pickPlanDialogueLocale, pickPlanLlmProvider } from "../lib/plan-llm-session.js";
+import { pickPlanExecutionModel } from "../lib/plan-llm-models.js";
+import { ensureGitForPlannerCommit, offerGithubInitBeforePush, runNotionSyncWithOptionalInit } from "../lib/plan-post-apply-setup.js";
 import { buildPlanPrompt } from "../lib/prompt-builder.js";
+import { projectPaths } from "../lib/paths.js";
 const DEFAULT_BRIEF_REL = ".vibeops/brief/project-brief.md";
 const DEFAULT_PROMPT_REL = ".vibeops/generated/plan-prompt.md";
 function toAbsolute(root, candidate) {
@@ -15,6 +21,13 @@ function relDisplay(root, abs) {
 export async function planCommand(options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const nonInteractive = options.nonInteractive === true;
+    const paths = projectPaths(cwd);
+    if (!(await pathExists(paths.config))) {
+        log.error(`Not a VibeOps project: ${cyan(".vibeops.json")} was not found under this directory.`);
+        log.info(`  ${dim("Run")} ${cyan("vibeops init")} ${dim("here first, then run")} ${cyan("vibeops plan")} ${dim("again.")}`);
+        process.exitCode = 1;
+        return;
+    }
     const briefAbs = join(cwd, DEFAULT_BRIEF_REL);
     const promptAbs = typeof options.output === "string" ? toAbsolute(cwd, options.output) : join(cwd, DEFAULT_PROMPT_REL);
     log.info(bold(`vibeops plan`));
@@ -23,10 +36,15 @@ export async function planCommand(options) {
         log.info(dim(`  from: ${options.from}`));
     if (options.idea)
         log.info(dim(`  idea: ${options.idea}`));
+    if (typeof options.llmModel === "string" && options.llmModel.trim().length > 0) {
+        log.info(dim(`  model: ${options.llmModel.trim()}`));
+    }
     if (nonInteractive)
         log.info(dim(`  mode: non-interactive`));
     log.blank();
     let bundle;
+    let llmProviderForApply;
+    let llmModelForApply;
     if (typeof options.from === "string" && options.from.length > 0) {
         bundle = await loadFromFile({
             cwd,
@@ -41,15 +59,64 @@ export async function planCommand(options) {
             process.exitCode = 1;
             return;
         }
-        log.step(nonInteractive
-            ? "non-interactive: build the ProjectBrief from flag values + safe placeholders"
-            : "interactive: build the ProjectBrief from 20 questions (arrow keys · Space · Enter)");
-        log.blank();
-        bundle = await gatherBrief({
-            cwd,
-            idea: options.idea,
-            nonInteractive,
-        });
+        if (nonInteractive) {
+            log.step("non-interactive: build the ProjectBrief from flag values + safe placeholders");
+            log.blank();
+            bundle = await gatherBrief({
+                cwd,
+                idea: options.idea,
+                nonInteractive: true,
+            });
+        }
+        else if (options.legacyWizard === true) {
+            log.step("legacy wizard: build the ProjectBrief from 20 fixed questions (arrow keys · Space · Enter)");
+            log.blank();
+            bundle = await gatherBrief({
+                cwd,
+                idea: options.idea,
+                nonInteractive: false,
+                legacyWizard: true,
+            });
+        }
+        else {
+            log.step("LLM planning: verify provider, then interactive discovery + structured brief");
+            log.blank();
+            const interactiveLogin = process.stdin.isTTY === true;
+            const provider = await pickPlanLlmProvider(cwd, options.provider, { interactiveLogin });
+            if (provider === null) {
+                return;
+            }
+            const forcedModel = typeof options.llmModel === "string" && options.llmModel.trim().length > 0
+                ? options.llmModel.trim()
+                : undefined;
+            const pickedModel = forcedModel ??
+                (await pickPlanExecutionModel({
+                    provider,
+                    cwd,
+                    interactive: interactiveLogin,
+                }));
+            log.blank();
+            const planningLocale = await pickPlanDialogueLocale();
+            try {
+                bundle = await gatherBriefViaLlm({
+                    cwd,
+                    idea: options.idea,
+                    provider,
+                    allowCodexBrowserLogin: interactiveLogin,
+                    llmModelOverride: pickedModel,
+                    planningLocale,
+                });
+                llmProviderForApply = provider;
+                llmModelForApply =
+                    typeof pickedModel === "string" && pickedModel.trim().length > 0 ? pickedModel.trim() : undefined;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                log.error(`LLM planning failed: ${msg}`);
+                process.exitCode = 1;
+                return;
+            }
+        }
     }
     const briefMd = briefToMarkdown(bundle.brief, bundle.meta);
     await writeText(briefAbs, briefMd);
@@ -67,12 +134,174 @@ export async function planCommand(options) {
         for (const a of bundle.meta.assumptions)
             log.info(`  · ${a}`);
     }
+    const wantsApply = options.applyPlanner === true || options.applyPlannerDryRun === true;
+    if (wantsApply) {
+        const applyDryRun = options.applyPlannerDryRun === true;
+        const exec = await resolvePlannerApplyExecution({
+            cwd,
+            nonInteractive,
+            fromLlmProvider: llmProviderForApply,
+            fromLlmModel: llmModelForApply,
+            cliProvider: options.provider,
+            cliModel: options.llmModel,
+        });
+        if (exec === null) {
+            return;
+        }
+        try {
+            const applyResult = await applyPlannerMarkdownFlow({
+                cwd,
+                planPromptMarkdown: promptMd,
+                provider: exec.provider,
+                model: exec.model,
+                dryRun: applyDryRun,
+            });
+            const applyInteractive = !nonInteractive && process.stdin.isTTY === true && !applyDryRun;
+            const hasWrittenFiles = !applyDryRun && applyResult.writtenRelativePaths.length > 0;
+            let doCommit = hasWrittenFiles && options.noGitCommit !== true;
+            if (doCommit && applyInteractive) {
+                log.blank();
+                log.step("Next: commit, push, and Notion (confirm each step)");
+                doCommit = await askYesNo({
+                    message: "[1] Create a git commit for the planner output (docs/project + docs/tasks)?",
+                    nonInteractive: false,
+                    defaultValue: true,
+                });
+            }
+            let committedOk = false;
+            if (doCommit) {
+                const gitReady = await ensureGitForPlannerCommit({
+                    cwd,
+                    interactive: applyInteractive,
+                });
+                if (!gitReady) {
+                    doCommit = false;
+                }
+            }
+            if (doCommit) {
+                try {
+                    await commitPlannerGit(cwd, applyResult.writtenRelativePaths, "docs: planner output from vibeops plan (--apply-planner)");
+                    log.ok("Git commit created for planner docs/tasks.");
+                    committedOk = true;
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    log.warn(`Git commit did not run (${msg}). Review changes and commit manually.`);
+                }
+            }
+            let doPush = false;
+            if (committedOk) {
+                if (options.gitPush === true) {
+                    doPush = true;
+                }
+                else if (applyInteractive) {
+                    doPush = await askYesNo({
+                        message: "[2] Push this commit to the remote (git push)? (If Yes, you may be offered `vibeops github init` to connect or create a GitHub repo / set `origin`.)",
+                        nonInteractive: false,
+                        defaultValue: false,
+                    });
+                }
+                if (doPush) {
+                    await offerGithubInitBeforePush({ cwd, interactive: applyInteractive });
+                    try {
+                        await pushPlannerGit(cwd);
+                        log.ok("git push complete.");
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        log.error(`git push failed: ${msg}`);
+                        process.exitCode = 1;
+                    }
+                }
+            }
+            else if (options.gitPush === true && !committedOk) {
+                log.warn("`--push` skipped (no successful commit: dry-run, --no-git-commit, you declined the commit prompt, commit error, or no files written).");
+            }
+            let doNotion = bundle.brief.useNotion === true && options.noNotionSync !== true && !applyDryRun;
+            if (doNotion && applyInteractive) {
+                doNotion = await askYesNo({
+                    message: "[3] Run Notion sync now (project + TASK metadata)?",
+                    nonInteractive: false,
+                    defaultValue: true,
+                });
+            }
+            if (doNotion) {
+                const hadErrBeforeNotion = process.exitCode === 1;
+                await runNotionSyncWithOptionalInit({ cwd, interactive: applyInteractive });
+                if (hadErrBeforeNotion) {
+                    process.exitCode = 1;
+                }
+                if (process.exitCode === 1 && !hadErrBeforeNotion) {
+                    log.warn("Notion sync failed — fix integration and run `vibeops notion sync`.");
+                }
+            }
+            else if (bundle.brief.useNotion === true && applyDryRun) {
+                log.info(dim("Notion sync skipped for --apply-dry-run."));
+            }
+            else if (bundle.brief.useNotion === true && options.noNotionSync === true) {
+                log.info(dim("Notion sync skipped (--no-notion-sync)."));
+            }
+            else if (bundle.brief.useNotion === true && applyInteractive && !doNotion) {
+                log.info(dim("Notion sync skipped (you chose No)."));
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            log.error(`Planner apply failed: ${msg}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
     log.blank();
     log.info(bold("Next steps:"));
-    log.info(`  1) Open a new Cursor chat and paste the full contents of ${cyan(relDisplay(cwd, promptAbs))}.`);
-    log.info(`  2) Review the Planner Agent's docs/project/* + initial backlog via git diff and commit.`);
-    log.info(`  3) To revise the brief, edit ${cyan(relDisplay(cwd, briefAbs))} and regenerate the prompt with`);
-    log.info(`     ${dim("vibeops plan --from " + DEFAULT_BRIEF_REL)}.`);
+    if (wantsApply && options.applyPlannerDryRun !== true) {
+        log.info(`  1) Open this repo in Cursor and run ${cyan("vibeops task start TASK-NNN")} for each backlog item.`);
+        log.info(`  2) The planning prompt is still at ${cyan(relDisplay(cwd, promptAbs))} if you need to re-run the planner.`);
+        log.info(`  3) To revise the brief only, edit ${cyan(relDisplay(cwd, briefAbs))} then:`);
+        log.info(`     ${dim("vibeops plan --from " + DEFAULT_BRIEF_REL + " [--apply-planner …]")}`);
+    }
+    else if (wantsApply && options.applyPlannerDryRun === true) {
+        log.info(`  1) Re-run without ${cyan("--apply-dry-run")} to write files, commit, and (if enabled) Notion sync.`);
+        log.info(`  2) Or paste ${cyan(relDisplay(cwd, promptAbs))} into Cursor for a manual planner pass.`);
+    }
+    else {
+        log.info(`  1) Open a new Cursor chat and paste the full contents of ${cyan(relDisplay(cwd, promptAbs))}.`);
+        log.info(`  2) Or run again with ${cyan("--apply-planner")}: the CLI calls the same LLM and writes ${cyan("docs/project/*")} + ${cyan("docs/tasks/*")} from the prompt (brief alone does not create TASK files).`);
+        log.info(`  3) Regenerate only the prompt from an edited brief:`);
+        log.info(`     ${dim("vibeops plan --from " + DEFAULT_BRIEF_REL + " [--apply-planner …]")}`);
+    }
+}
+async function resolvePlannerApplyExecution(inputs) {
+    if (inputs.fromLlmProvider !== undefined) {
+        return { provider: inputs.fromLlmProvider, model: inputs.fromLlmModel };
+    }
+    const tty = process.stdin.isTTY === true;
+    if (inputs.cliProvider !== undefined) {
+        const interactiveLogin = tty && !inputs.nonInteractive;
+        const provider = await pickPlanLlmProvider(inputs.cwd, inputs.cliProvider, { interactiveLogin });
+        if (provider === null)
+            return null;
+        let model = inputs.cliModel?.trim();
+        if (!model && tty && !inputs.nonInteractive) {
+            const picked = await pickPlanExecutionModel({
+                provider,
+                cwd: inputs.cwd,
+                interactive: true,
+            });
+            model = picked?.trim();
+        }
+        return { provider, model: model && model.length > 0 ? model : undefined };
+    }
+    if (!tty || inputs.nonInteractive) {
+        log.error("When using --apply-planner without an interactive LLM briefing in the same run, pass --provider openai | codex-oauth | cursor-agent (and optional --model / env defaults).");
+        process.exitCode = 1;
+        return null;
+    }
+    const provider = await pickPlanLlmProvider(inputs.cwd, undefined, { interactiveLogin: true });
+    if (provider === null)
+        return null;
+    const model = await pickPlanExecutionModel({ provider, cwd: inputs.cwd, interactive: true });
+    return { provider, model };
 }
 async function loadFromFile(inputs) {
     const { cwd, fromPath, nonInteractive, idea } = inputs;

package/dist/commands/task-start.js

@@ -1,6 +1,6 @@
 import { relative, resolve } from "node:path";
 import { branchNameForTaskFile, findTaskFile, upsertGitContext, updateInlineStatus, } from "../lib/task.js";
-import { detectDefaultBranch, gitBranchExists, gitCheckoutNewBranch, gitHeadCommit, readGitInfo, } from "../lib/git.js";
+import { detectDefaultBranch, gitBranchExists, gitCheckoutNewBranch, gitGovernanceOnlyDirty, gitHeadCommit, readGitInfo, } from "../lib/git.js";
 import { bold, cyan, dim, log } from "../lib/logger.js";
 import { buildTaskPromptString } from "../lib/task-prompt.js";
 import { projectPaths } from "../lib/paths.js";
@@ -25,9 +25,21 @@ export async function taskStartCommand(taskId, options = {}) {
         return;
     }
     if (git.dirty === true && options.allowDirty !== true) {
-        log.error("Git working tree is dirty. Commit or stash first, or rerun with --allow-dirty.");
-        process.exitCode = 1;
-        return;
+        const gov = await gitGovernanceOnlyDirty(cwd);
+        if (!gov.onlyGovernance) {
+            log.error("Git working tree is dirty. Commit or stash first, or rerun with --allow-dirty.");
+            if (gov.nonGovernancePaths.length > 0) {
+                log.info(dim("  Non-documentation changes:"));
+                for (const p of gov.nonGovernancePaths)
+                    log.info(`    · ${p}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        log.warn("Uncommitted governance docs only (tasks / project / logs / .vibeops/state). Proceeding — commit when convenient.");
+        for (const p of gov.allPaths)
+            log.info(`  ${dim("·")} ${p}`);
+        log.blank();
     }
     const baseBranch = git.branch ?? (await detectDefaultBranch(cwd)) ?? "main";
     const baseCommit = (await gitHeadCommit(cwd)) ?? "";

package/dist/lib/brief.js

@@ -195,7 +195,7 @@ export async function gatherBrief(inputs) {
     const meta = {
         vibeopsVersion: VERSION,
         generatedAt: new Date().toISOString(),
-        source: inputs.nonInteractive ? "non-interactive" : "interactive",
+        source: inputs.legacyWizard === true ? "legacy-wizard" : inputs.nonInteractive ? "non-interactive" : "interactive",
         schemaVersion: PROJECT_BRIEF_SCHEMA_VERSION,
         assumptions,
     };
@@ -240,8 +240,15 @@ export function briefToMarkdown(brief, meta) {
     lines.push("");
     lines.push(`> Generated: ${meta.generatedAt} · VibeOps ${meta.vibeopsVersion} · Source: ${meta.source} · schemaVersion: ${meta.schemaVersion}`);
     lines.push("");
-    lines.push("This brief is the input for the Cursor **Planner Agent**. VibeOps does not call LLMs directly.");
-    lines.push("The Planner Agent reads this brief, fills in `docs/project/*`, and creates the initial backlog.");
+    lines.push(meta.source === "llm-openai" ||
+        meta.source === "llm-codex-oauth" ||
+        meta.source === "llm-cursor-agent"
+        ? meta.source === "llm-codex-oauth"
+            ? "This brief was produced by an **LLM planning session** using **Codex (ChatGPT OAuth)** (`codex login`, read from ~/.codex/auth.json). Review and edit it, then let the Planner Agent fill `docs/project/*`."
+            : meta.source === "llm-openai"
+                ? "This brief was produced by an **LLM planning session** using an **OpenAI platform API key**. Review and edit it, then let the Planner Agent fill `docs/project/*`."
+                : "This brief was produced by an **LLM planning session** using the **Cursor Agent CLI**. Review and edit it, then let the Planner Agent fill `docs/project/*`."
+        : "This brief is the input for the Cursor **Planner Agent**. VibeOps collected these answers locally (or from `--from`) — the Planner Agent reads this brief, fills in `docs/project/*`, and creates the initial backlog.");
     lines.push("");
     for (const sec of SECTIONS) {
         lines.push(`## ${sec.num}. ${sec.title}`);
@@ -330,7 +337,7 @@ export function parseBriefFromMarkdown(md) {
     const meta = {
         vibeopsVersion: recordedVersion,
         generatedAt,
-        source: recordedSource === "from-file" ? "from-file" : recordedSource,
+        source: recordedSource,
         schemaVersion: PROJECT_BRIEF_SCHEMA_VERSION,
         assumptions,
     };

package/dist/lib/git.js

@@ -167,6 +167,48 @@ function parsePorcelain(lines) {
     }
     return out;
 }
+/** Paths under these prefixes may stay uncommitted across `task done` / doc updates. */
+const GOVERNANCE_DOC_REL_PREFIXES = [
+    "docs/tasks/",
+    "docs/project/",
+    "docs/logs/",
+    ".vibeops/state/",
+];
+function normalizeRepoRelPath(p) {
+    return p.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+export function isGovernanceDocumentationPath(repoRelativePath) {
+    const n = normalizeRepoRelPath(repoRelativePath);
+    for (const prefix of GOVERNANCE_DOC_REL_PREFIXES) {
+        if (n.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * When the index/worktree is dirty, classify whether every changed path is
+ * limited to governance docs (TASK files, project docs, logs, task state JSON).
+ * Used by `vibeops task start` so `task done --finalize` on main does not
+ * block the next TASK unless application code is also dirty.
+ */
+export async function gitGovernanceOnlyDirty(cwd) {
+    const lines = await gitStatusPorcelain(cwd);
+    const entries = parsePorcelain(lines);
+    const all = new Set();
+    for (const e of entries) {
+        all.add(e.path);
+        if (typeof e.origPath === "string" && e.origPath.length > 0) {
+            all.add(e.origPath);
+        }
+    }
+    const allPaths = [...all];
+    const nonGovernancePaths = allPaths.filter((p) => !isGovernanceDocumentationPath(p));
+    return {
+        allPaths,
+        nonGovernancePaths,
+        onlyGovernance: allPaths.length > 0 && nonGovernancePaths.length === 0,
+    };
+}
 export async function gitWorkingTreeChangedFiles(cwd) {
     const entries = parsePorcelain(await gitStatusPorcelain(cwd));
     return entries.filter((e) => e.unstaged).map((e) => e.path);