@goodtek/vibeops 3.1.9 → 3.3.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to VibeOps are documented here.
 
 ## Unreleased
 
+## 3.3.0 - 2026-10-18
+
+### Added
+
+- **`task add --repair-baseline`**: open the TASK that repairs a broken baseline even in `enforce` mode (failures shown as warnings for that command only); the TASK file records it (`## Baseline` → Repair) and its `task ship` requires every baseline check to pass, whatever the mode (D-015, TASK-052).
+
+## 3.2.0 - 2026-10-18
+
+### Fixed
+
+- **`task ship --new-cycle` recorded the TASK's own commit as Base Commit** (the task branch HEAD after the follow-up commit). It now records where the cycle starts on the base: the merge base of the task branch and the freshly fetched `<remote>/<base>` (TASK-050).
+
+### Added
+
+- **`task merge` updates a stale PR branch** (GitHub, `merge.updateBranch`, default on): update-branch merges the base into the PR branch on the host (no force push), the gate waits for the new head's CI and re-checks with the same rules, repeating while bot PRs keep moving the base, within `waitTimeoutSeconds`; conflicts stop. `task ship`'s push-rejected hint now says merge (`git pull --no-rebase`), never rebase + force-push (D-014, TASK-048).
+- **`vibeops status` shows the repository baseline**: the baseline checks, mode, the persona crew and its pinned catalog commit, and other remote branches (`--json` → `baseline`) (TASK-047).
+- **`task release --tag`**: after the release merge, tag the merge commit `v<package.json version>` and push the tag (refuses when the commit is not on the production branch, the version is not semver, or the tag already exists) — merge into production and tagging for publish become one step (D-013, TASK-046).
+- **Baseline checks before `task add` / `task ship`** (`.vibeops.json` → `baseline`): `branch-policy` (integration ≠ production), `default-branch` (remote default = integration), and with `baseline.crew` set `personas` / `agents-contract`. `mode`: `warn` (default), `enforce` (stop, exit 1), `off` (D-012, TASK-045).
+
 ## 3.1.9 - 2026-10-17
 
 ### Fixed

package/README.md

@@ -147,7 +147,7 @@ vibeops llm use auto   # auto | codex-oauth | cursor-agent | openai
 - **`task ship`**: `-m/--message`, `--new-cycle`, `--no-commit`, `--dry-run`, `--no-pr`, `--non-interactive`, `--allow-open-mr`, `--no-integrate`, `--recreate-branch`, `--skip-llm`
 - **`task merge`**: `--dry-run`, `--merge`, `--rebase`
 - **`task sync`**: `--dry-run`, `--no-remote-delete`, `--force`
-- **`task release`**: `--dry-run`, `--no-merge`, `--merge`, `--rebase`
+- **`task release`**: `--dry-run`, `--no-merge`, `--merge`, `--rebase`, `--tag` (after the merge, tag the release merge commit `v<package.json version>` and push it; never moves an existing tag)
 - **`pull`**: `--dry-run`
 - **`status`**: `--json`
 
@@ -201,6 +201,27 @@ A branch counts only when its name has the **generated form** `task/<NNN>` or `t
 
 If a configured remote cannot be fetched, `task add` stops without creating a TASK file. Across machines, `task ship` re-checks the remote (`git ls-remote`) right before pushing and refuses if another task branch with the same number already exists there.
 
+## Baseline checks
+
+`task add` and `task ship` first check that the repository follows the VibeOps flow (`.vibeops.json` → `baseline`):
+
+| Check | OK when |
+|-------|---------|
+| `branch-policy` | `git.integrationBranch` ≠ `git.productionBranch` (e.g. `develop` → `main`) |
+| `default-branch` | the remote's default branch (`git ls-remote --symref <remote> HEAD`) is the integration branch |
+| `personas` | with `baseline.crew` set: `.personas/<crew>/SOURCE` exists |
+| `agents-contract` | with `baseline.crew` set: AGENTS.md has the `<!-- getpersona:<crew> -->` section |
+
+```json
+{ "baseline": { "mode": "warn", "crew": "vibe-crew" } }
+```
+
+- `mode`: `warn` (default — print each failing check with a fix and continue), `enforce` (stop with exit code 1, nothing created or pushed), `off`.
+- `crew`: persona crew to require; omitted → the crew checks are skipped.
+- `vibeops status` shows the same checks (`Baseline …`), the crew's pinned catalog commit, and remote branches other than integration / production / `task/*` / `sync/*` (`status --json` → `baseline`).
+- The block is validated strictly (unknown keys / values are errors and stop the command).
+- **Repairing in `enforce` mode:** `vibeops task add --repair-baseline` opens the TASK anyway (failures shown as warnings for that command only) and writes a `## Baseline` section ("Repair …") into the TASK file; `task ship` of that TASK goes through only when every baseline check passes, whatever `baseline.mode` is.
+
 ## Merge gate
 
 > **3.0.0 breaking:** a PR/MR with **no checks at all** is refused by default. Repos without CI: set `"merge": {"allowNoChecks": true}` in `.vibeops.json`. Requires **gh ≥ 2.13.0**.
@@ -227,7 +248,7 @@ Before calling `gh pr merge` / `glab mr merge`:
 - **After the merge:** `gh pr merge` / `glab mr merge` return the result synchronously (GitHub `merged: true`, GitLab `state: "merged"`), so VibeOps reads the PR/MR once to confirm. Not merged at that point (merge queue / auto-merge) is reported, not waited for.
 - **The merge is pinned to the checked commit:** right before merging the gate re-reads the PR head; if it moved, the new head is evaluated from scratch. The merge itself uses `gh pr merge --match-head-commit <sha>` (requires **gh ≥ 2.13.0**) / `glab mr merge --auto-merge=false --sha <sha>` (verified with glab 1.106), so a push between the last check and the merge makes the host refuse. A GitLab `405` re-runs the gate and retries once with the same flags.
 - **Unreadable Git Context stops `task ship` / `task add`:** a TASK file whose `## Git Context` cannot be read (e.g. an edit left `## ## Git Context`) makes `task ship` exit 1 before committing or pushing, naming the line; `task add` refuses to "resume" such a TASK (it would write a second section) and names the file and line.
-- **`task merge` refuses a stale base:** the head commit the gate approved must contain the current `<remote>/<base>` (`git merge-base --is-ancestor`, after fetching the base branch and the head commit). A head that does not — the base moved since the branch was pushed, or the branch was rebuilt on an old base (e.g. `git reset --soft <stale origin/develop>` + commit) — can silently revert work merged into the base since, and a squash merge lands that revert. Bring the branch up to date (`git fetch` + `git merge <remote>/<base>`, test, `task ship`), wait for CI, then rerun `task merge`. A fetch failure refuses (fail closed). `task release` does not apply this check (with merge-commit releases the production branch is normally not an ancestor of the integration branch).
+- **`task merge` refuses a stale base:** the head commit the gate approved must contain the current `<remote>/<base>` (`git merge-base --is-ancestor`, after fetching the base branch and the head commit). A head that does not — the base moved since the branch was pushed, or the branch was rebuilt on an old base (e.g. `git reset --soft <stale origin/develop>` + commit) — can silently revert work merged into the base since, and a squash merge lands that revert. On GitHub (`merge.updateBranch`, default `true`) `task merge` brings the branch up to date itself: [update-branch](https://docs.github.com/rest/pulls/pulls#update-a-pull-request-branch) merges the base into the PR branch on the host (a merge commit — no rebase, no force push), then the gate waits for the new head and checks it with the same rules, again if the base moved meanwhile, all within `waitTimeoutSeconds`; a merge conflict stops with the local-merge instruction. Otherwise (GitLab, or `updateBranch: false`) bring the branch up to date yourself (`git fetch` + `git merge <remote>/<base>`, test, `task ship`), wait for CI, then rerun `task merge`. A fetch failure refuses (fail closed). `task release` does not apply this check (with merge-commit releases the production branch is normally not an ancestor of the integration branch).
 
 ### Configuration (`.vibeops.json` → `merge`)
 
@@ -252,6 +273,7 @@ Before calling `gh pr merge` / `glab mr merge`:
 | `pollIntervalSeconds` | `10` | integer ≥ 1, ≤ timeout | Poll interval while waiting (same default as `gh pr checks --watch`). |
 | `emptyRollupGraceSeconds` | `0` | integer ≥ 0, ≤ timeout | Only when no GitHub Actions workflow is expected: how long an empty check list is re-polled before "no checks" applies. Default `0`: name CI outside GitHub Actions in `requiredChecks` so the gate waits for it by name, instead of guessing how long it takes to report. |
 | `allowNoChecks` | `false` | boolean | Merge a PR that has no checks at all (repo without CI). Prints one warning per such merge. |
+| `updateBranch` | `true` | boolean | `task merge` on GitHub: update a stale PR branch with update-branch (merge, no force push) and re-check, instead of refusing. |
 
 - Check names are exact (`CheckRun.name` / `StatusContext.context`) or a `*` glob (`"lint*"`, `"* · linux"`). Required checks are GitHub-only; GitLab gates on the head pipeline.
 - The block is validated strictly: it must be an object, unknown keys (typos) and wrong types are errors, and `task merge` / `task release` exit 1 naming the key.

package/dist/cli.js

@@ -67,9 +67,11 @@ task
     .option("--dry-run", "Plan only")
     .option("--non-interactive", "CI: minimal scaffold (optional --idea)")
     .option("--idea <text>", "Short description (CI)")
+    .option("--repair-baseline", "Open a TASK that repairs the baseline even in enforce mode (its ship requires every check to pass)")
     .option("--cwd <path>", "Target directory")
     .action(async (opts) => {
     await taskAddCommand({
+        repairBaseline: Boolean(opts.repairBaseline),
         dryRun: Boolean(opts.dryRun),
         nonInteractive: Boolean(opts.nonInteractive),
         idea: opts.idea,
@@ -161,9 +163,11 @@ task
     .option("--squash", "Squash merge (default is merge commit for release)")
     .option("--merge", "Merge commit (default for release)")
     .option("--rebase", "Rebase merge")
+    .option("--tag", "After the merge, tag the release merge commit v<package.json version> and push it")
     .option("--cwd <path>", "Target directory")
     .action(async (opts) => {
     await taskReleaseCommand({
+        tag: Boolean(opts.tag),
         dryRun: Boolean(opts.dryRun),
         noMerge: opts.merge === false,
         merge: Boolean(opts.merge),

package/dist/commands/status.js

@@ -6,6 +6,7 @@ import { readGitInfo } from "../lib/git.js";
 import { buildLlmStatusReport } from "../lib/llm-status.js";
 import { bold, cyan, dim, green, log, yellow } from "../lib/logger.js";
 import { projectPaths } from "../lib/paths.js";
+import { summarizeBaseline } from "../lib/project-baseline.js";
 import { VERSION } from "../version.js";
 import { computeNextHint, hintToLines, hintToText, listInProgressTasks, pickFocusTask, relPath, taskBranchExistsFor, } from "../lib/task-context.js";
 import { hasOpenTaskMergeRequest, isMergeRequestMerged, resolveTaskMergeRequestUrl, taskNeedsSync, } from "../lib/task-effective-status.js";
@@ -77,6 +78,7 @@ async function buildReport(cwd) {
         hasLocalChanges: git.dirty === true,
     });
     const llm = isVibeopsProject ? await buildLlmStatusReport(cwd) : null;
+    const baseline = isVibeopsProject && config?.git && git.isRepo ? await summarizeBaseline(cwd, config.git) : null;
     return {
         vibeopsVersion: VERSION,
         isVibeopsProject,
@@ -100,6 +102,7 @@ async function buildReport(cwd) {
         nextHint: hintToText(hint, cwd, focus),
         nextLines: [...hintToLines(hint, cwd, focus)],
         llm,
+        baseline,
     };
 }
 function filledLabel(ok) {
@@ -183,6 +186,23 @@ function printDetails(report) {
     if (hostBits.length > 0) {
         log.info(`  ${dim("Git")}       ${hostBits.join(" · ")}`);
     }
+    if (report.baseline) {
+        const b = report.baseline;
+        if (b.configError !== null) {
+            log.info(`  ${dim("Baseline")}  ${yellow(b.configError)}`);
+        }
+        const failing = b.checks.filter((c) => !c.ok);
+        const crew = b.crew !== null ? ` · ${b.crew}${b.crewCommit ? ` ${b.crewCommit.slice(0, 7)}` : ""}` : "";
+        log.info(`  ${dim("Baseline")}  ${failing.length === 0
+            ? `ok (${b.checks.map((c) => c.id).join(", ")})`
+            : yellow(failing.map((c) => `${c.id}: ${c.detail}`).join("; "))} · mode ${b.mode}${crew}`);
+        if (b.otherBranches === null) {
+            log.info(`  ${dim("Branches")}  ${dim("(remote branches unreadable)")}`);
+        }
+        else if (b.otherBranches.length > 0) {
+            log.info(`  ${dim("Branches")}  other remote branches: ${b.otherBranches.join(", ")}`);
+        }
+    }
     if (report.llm) {
         const active = report.llm.active !== null
             ? `${report.llm.active} (ok)`

package/dist/commands/task-add.js

@@ -3,6 +3,7 @@ import { pathExists, writeText } from "../lib/filesystem.js";
 import { GitConfigError, requireGitConfig } from "../lib/git-config.js";
 import { ensureIntegrationSynced, printIntegrationSyncDiagnosis, } from "../lib/git-integration-sync.js";
 import { askInput } from "../lib/inquirer-helpers.js";
+import { BASELINE_REPAIR_SECTION, BASELINE_REPAIR_TEXT, preflightBaseline, } from "../lib/project-baseline.js";
 import { bold, cyan, dim, log, yellow } from "../lib/logger.js";
 import { projectPaths } from "../lib/paths.js";
 import { slugify } from "../lib/slug.js";
@@ -12,7 +13,7 @@ import { findBlockingTask, relPath } from "../lib/task-context.js";
 import { allocateTaskId, TaskIdAllocationError } from "../lib/task-id-allocation.js";
 import { readTaskLockConfig, TaskLockConfigError, TaskLockHeldError, withTaskLock, } from "../lib/task-lock.js";
 import { isIncompleteTaskStart, startTaskBranch } from "../lib/task-start.js";
-import { branchNameForTaskFile, damagedGitContext, loadActionableTasks, readGitContext, } from "../lib/task.js";
+import { branchNameForTaskFile, damagedGitContext, withSectionAfterStatus, loadActionableTasks, readGitContext, } from "../lib/task.js";
 async function loadGitConfigOrNull(root, dryRun) {
     try {
         return await requireGitConfig(root);
@@ -80,6 +81,11 @@ export async function taskAddCommand(opts = {}) {
     const gitCfg = await loadGitConfigOrNull(root, dryRun);
     if (!dryRun && gitCfg === null)
         return;
+    const repair = opts.repairBaseline === true;
+    if (gitCfg !== null && !(await preflightBaseline(root, gitCfg, "task add", { repair }))) {
+        process.exitCode = 1;
+        return;
+    }
     let lockCfg;
     try {
         lockCfg = await readTaskLockConfig(root);
@@ -243,9 +249,12 @@ export async function taskAddCommand(opts = {}) {
             }
         }
         const taskId = formatTaskId(taskNumber);
-        const markdown = taskId === provisionalId
+        const drafted = taskId === provisionalId
             ? draftMarkdown
             : draftMarkdown.replace(new RegExp(`\\b${provisionalId}\\b`, "g"), taskId);
+        const markdown = repair
+            ? withSectionAfterStatus(drafted, BASELINE_REPAIR_SECTION, BASELINE_REPAIR_TEXT)
+            : drafted;
         const { filePath } = uniqueTaskPath(paths.docsTasks, taskId, slugify(slug || title), tasks.map((t) => t.filePath));
         const relFile = relPath(root, filePath);
         const integration = gitCfg?.integrationBranch ?? "integration";

package/dist/commands/task-merge.js

@@ -108,7 +108,11 @@ export async function taskMergeCommand(taskRef, options = {}) {
             method,
             requiredChecks,
             gate,
-            requireBaseInHead: { remote: gitCfg.remote, baseBranch: ctx.baseBranch },
+            requireBaseInHead: {
+                remote: gitCfg.remote,
+                baseBranch: ctx.baseBranch,
+                updateBranch: mergeCfg.updateBranch,
+            },
             dryRun: true,
         });
         log.blank();
@@ -142,7 +146,11 @@ export async function taskMergeCommand(taskRef, options = {}) {
                 waitForCi: true,
                 requiredChecks,
                 gate,
-                requireBaseInHead: { remote: gitCfg.remote, baseBranch: ctx.baseBranch },
+                requireBaseInHead: {
+                    remote: gitCfg.remote,
+                    baseBranch: ctx.baseBranch,
+                    updateBranch: mergeCfg.updateBranch,
+                },
             });
             const verified = await assertMergeRequestMerged({
                 cwd,
@@ -181,7 +189,11 @@ export async function taskMergeCommand(taskRef, options = {}) {
                 waitForCi: true,
                 requiredChecks,
                 gate,
-                requireBaseInHead: { remote: gitCfg.remote, baseBranch: ctx.baseBranch },
+                requireBaseInHead: {
+                    remote: gitCfg.remote,
+                    baseBranch: ctx.baseBranch,
+                    updateBranch: mergeCfg.updateBranch,
+                },
             });
             const verified = await assertMergeRequestMerged({
                 cwd,

package/dist/commands/task-release.js

@@ -5,7 +5,8 @@ import { formatHostCliHint, formatHostCliMissingMessage } from "../lib/git-host-
 import { detectGitHost, mergeRequestLabel } from "../lib/git-host.js";
 import { gitRemoteUrl } from "../lib/git.js";
 import { bold, dim, log } from "../lib/logger.js";
-import { createMergeRequest, findMergeRequestByBranches, getMergeRequestState, MergeGateError, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
+import { createMergeRequest, findMergeRequestByBranches, getMergeRequestDetails, getMergeRequestState, MergeGateError, mergeMergeRequest, probeMergeRequestCli, } from "../lib/pr-create.js";
+import { tagReleaseCommit } from "../lib/release-tag.js";
 import { assertMergeRequestMerged } from "../lib/task-merge-verify.js";
 function resolveReleaseMergeMethod(opts) {
     if (opts.rebase === true)
@@ -17,6 +18,11 @@ function resolveReleaseMergeMethod(opts) {
 export async function taskReleaseCommand(options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const dryRun = options.dryRun === true;
+    if (options.tag === true && options.noMerge === true) {
+        log.error("--tag needs the merge: it tags the release merge commit (drop --no-merge).");
+        process.exitCode = 1;
+        return;
+    }
     let gitCfg;
     try {
         gitCfg = await requireGitConfig(cwd);
@@ -72,6 +78,9 @@ export async function taskReleaseCommand(options = {}) {
             if (mergeCfg.allowNoChecks) {
                 log.info("  · allowNoChecks: true (a release PR with no checks would merge)");
             }
+            if (options.tag === true) {
+                log.info(`  · tag the release merge commit v<package.json version> and push the tag to ${remote}`);
+            }
         }
         return;
     }
@@ -157,6 +166,19 @@ export async function taskReleaseCommand(options = {}) {
             return;
         }
         log.ok(`Release ${label} merged into ${productionBranch}.`);
+        if (options.tag === true) {
+            const merged = await getMergeRequestDetails(cwd, host, releaseUrl);
+            const commit = merged?.mergeCommitSha ?? null;
+            const tagged = commit === null
+                ? { ok: false, message: `the host did not report the merge commit of ${releaseUrl}` }
+                : await tagReleaseCommit({ cwd, remote, productionBranch, commit });
+            if (!tagged.ok) {
+                log.error(`Release merged, but not tagged: ${tagged.message}.`);
+                process.exitCode = 1;
+                return;
+            }
+            log.ok(`Tagged ${tagged.tag} → ${tagged.commit.slice(0, 7)} and pushed to ${remote}.`);
+        }
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);

package/dist/commands/task-ship.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { readText } from "../lib/filesystem.js";
 import { requireGitConfig } from "../lib/git-config.js";
+import { BASELINE_REPAIR_SECTION, preflightBaseline } from "../lib/project-baseline.js";
 import { gitCommitsAhead, gitHeadCommit, gitPush, gitRemoteBranchExists, readGitInfo, } from "../lib/git.js";
 import { askYesNo, isInteractiveSession } from "../lib/inquirer-helpers.js";
 import { bold, cyan, dim, green, log, yellow } from "../lib/logger.js";
@@ -14,7 +15,7 @@ import { runPostMergeNewCycle } from "../lib/task-new-cycle.js";
 import { applyTaskShipMemory, fallbackResultSections, llmCompleteTaskShip, writeTaskResultSections, } from "../lib/task-ship-llm.js";
 import { detectShipPrState, prRefLabel, resolveShipAction, } from "../lib/task-ship-state.js";
 import { finishTaskWithPullRequest } from "../lib/task-push-pr.js";
-import { hasNonEmptySection, parseTaskFilename, gitContextProblem, readGitContext, readTaskFile, updateInlineStatus, } from "../lib/task.js";
+import { hasNonEmptySection, parseTaskFilename, gitContextProblem, readGitContext, readSection, readTaskFile, updateInlineStatus, } from "../lib/task.js";
 import { assertTaskIdFreeOnRemote } from "../lib/task-id-allocation.js";
 function describePushFailure(message) {
     const lower = message.toLowerCase();
@@ -28,7 +29,7 @@ function describePushFailure(message) {
         lower.includes("fetch first") ||
         lower.includes("rejected") ||
         lower.includes("behind")) {
-        return "Push rejected — the remote branch has commits you don't. Pull/rebase the task branch, then rerun.";
+        return "Push rejected — the remote branch has commits you don't. Merge them in (git pull --no-rebase), then rerun; never rebase + force-push a shared task branch.";
     }
     return `git push failed: ${message}`;
 }
@@ -330,6 +331,13 @@ export async function taskShipCommand(taskRef, options = {}) {
         log.info(`  ${dim("PR")}    ${prRefLabel(prCtx.number)} (${prCtx.state})`);
     }
     log.blank();
+    const baselineGit = await requireGitConfig(cwd).catch(() => null);
+    const repairTask = readSection(body, BASELINE_REPAIR_SECTION).startsWith("Repair");
+    if (baselineGit !== null &&
+        !(await preflightBaseline(cwd, baselineGit, "task ship", { requireOk: repairTask }))) {
+        process.exitCode = 1;
+        return;
+    }
     const ctx = {
         cwd,
         taskId,

package/dist/lib/config.js

@@ -65,6 +65,7 @@ export async function readConfig(root) {
             const llm = parseLlmBlock(parsed.llm);
             const git = parseGitBlock(parsed.git);
             const merge = parsed.merge;
+            const baseline = parsed.baseline;
             const clients = parseClientsBlock(parsed.clients) ?? ["cursor"];
             return {
                 name: parsed.name,
@@ -75,6 +76,7 @@ export async function readConfig(root) {
                 ...(git ? { git } : {}),
                 ...(llm ? { llm } : {}),
                 ...(merge !== undefined ? { merge } : {}),
+                ...(baseline !== undefined ? { baseline } : {}),
             };
         }
         return null;
@@ -93,6 +95,7 @@ export function buildConfig(name, clients, git, existing, nowIso) {
         git,
         llm: existing?.llm ?? { provider: "auto" },
         ...(existing?.merge !== undefined ? { merge: existing.merge } : {}),
+        ...(existing?.baseline !== undefined ? { baseline: existing.baseline } : {}),
     };
 }
 export function configToJson(config) {

package/dist/lib/merge-config.js

@@ -21,6 +21,8 @@ export const MERGE_GATE_DEFAULTS = {
     // to report.
     emptyRollupGraceSeconds: 0,
     allowNoChecks: false,
+    // GitHub's own "Update branch" (merge, no force push) — see `updateGitHubPullBranch`.
+    updateBranch: true,
 };
 /** Inclusive bounds for the numeric settings (seconds); cross-checks below keep them ≤ the wait. */
 export const MERGE_GATE_LIMITS = {
@@ -35,6 +37,7 @@ const KNOWN_KEYS = new Set([
     "pollIntervalSeconds",
     "emptyRollupGraceSeconds",
     "allowNoChecks",
+    "updateBranch",
 ]);
 /** Invalid `merge` block in `.vibeops.json`. Merge commands refuse to run. */
 export class MergeConfigError extends Error {
@@ -96,7 +99,14 @@ export function parseMergeConfig(raw) {
             ? MERGE_GATE_DEFAULTS.emptyRollupGraceSeconds
             : seconds("emptyRollupGraceSeconds", o.emptyRollupGraceSeconds),
         allowNoChecks: MERGE_GATE_DEFAULTS.allowNoChecks,
+        updateBranch: MERGE_GATE_DEFAULTS.updateBranch,
     };
+    if (o.updateBranch !== undefined) {
+        if (typeof o.updateBranch !== "boolean") {
+            throw new MergeConfigError("`updateBranch` must be true or false.");
+        }
+        cfg.updateBranch = o.updateBranch;
+    }
     if (o.allowNoChecks !== undefined) {
         if (typeof o.allowNoChecks !== "boolean") {
             throw new MergeConfigError("`allowNoChecks` must be true or false.");

package/dist/lib/pr-create.js

@@ -570,6 +570,39 @@ function isMergeHttp405(error) {
     const msg = error instanceof Error ? error.message : String(error);
     return msg.includes("405") || msg.toLowerCase().includes("method not allowed");
 }
+/**
+ * GitHub "Update a pull request branch": merges the base branch into the PR branch on the
+ * host (a merge commit — no rebase, no force push) and answers `202 Accepted`; a
+ * non-matching `expected_head_sha` answers 422
+ * (docs.github.com/rest/pulls/pulls#update-a-pull-request-branch).
+ */
+export async function updateGitHubPullBranch(cwd, url, expectedHeadSha) {
+    const pr = parseGitHubPullUrl(url);
+    if (pr === null)
+        return "error";
+    try {
+        await execFileAsync("gh", [
+            "api",
+            "--hostname",
+            pr.hostname,
+            "--method",
+            "PUT",
+            `repos/${pr.owner}/${pr.repo}/pulls/${pr.number}/update-branch`,
+            "--raw-field",
+            `expected_head_sha=${expectedHeadSha}`,
+        ], { cwd, maxBuffer: 1024 * 1024 });
+        return "accepted";
+    }
+    catch (e) {
+        const text = `${e.stderr ?? ""} ${e instanceof Error ? e.message : ""}`.toLowerCase();
+        if (text.includes("conflict"))
+            return "conflict";
+        if (text.includes("expected head sha") || text.includes("head branch was modified")) {
+            return "head-moved";
+        }
+        return "error";
+    }
+}
 export async function closeMergeRequest(opts) {
     const ref = prRefFromUrl(opts.url);
     const label = mergeRequestLabel(opts.host);
@@ -599,8 +632,10 @@ export async function mergeMergeRequest(opts) {
             : "";
         log.info(`would check ${label} status checks (all green${required}) before merging`);
         if (opts.requireBaseInHead !== undefined) {
-            const { remote, baseBranch } = opts.requireBaseInHead;
-            log.info(`would refuse unless the head commit contains ${remote}/${baseBranch} (stale base)`);
+            const { remote, baseBranch, updateBranch } = opts.requireBaseInHead;
+            log.info(updateBranch === true && opts.host === "github"
+                ? `would update a stale branch from ${remote}/${baseBranch} on the host (update-branch, merge) and re-check`
+                : `would refuse unless the head commit contains ${remote}/${baseBranch} (stale base)`);
         }
         if (opts.host === "gitlab") {
             log.info(`would ${label} merge ${ref} (glab ${gitLabMergeArgs(ref, method, "<head sha>").join(" ")})`);
@@ -610,31 +645,56 @@ export async function mergeMergeRequest(opts) {
         }
         return;
     }
+    const timing = { ...mergeGateTiming(MERGE_GATE_DEFAULTS), ...opts.gate };
+    // One budget for the whole merge, including branch updates (`waitTimeoutSeconds`).
+    const deadline = Date.now() + timing.timeoutMs;
     const runGate = async () => {
-        const gate = await waitForMergeGate(opts.cwd, opts.host, opts.url, {
-            ...opts.gate,
-            waitForPending: opts.waitForCi === true,
-            requiredChecks: opts.requiredChecks ?? [],
-        });
-        if (!gate.ok)
-            throw new MergeGateError(label, gate.problems);
-        if (gate.alreadyMerged)
-            return null;
-        if (gate.details.headSha === null || gate.details.headSha.trim().length === 0) {
-            // Strict read already guarantees this; never merge unpinned.
-            throw new MergeGateError(label, ["host did not report the head commit SHA"]);
-        }
-        if (opts.requireBaseInHead !== undefined) {
-            const fresh = await checkBaseInHead({
-                cwd: opts.cwd,
-                remote: opts.requireBaseInHead.remote,
-                baseBranch: gate.details.baseBranch ?? opts.requireBaseInHead.baseBranch,
-                headSha: gate.details.headSha,
+        let updateErrors = 0;
+        for (;;) {
+            const gate = await waitForMergeGate(opts.cwd, opts.host, opts.url, {
+                ...opts.gate,
+                timeoutMs: Math.max(1, deadline - Date.now()),
+                waitForPending: opts.waitForCi === true,
+                requiredChecks: opts.requiredChecks ?? [],
             });
-            if (!fresh.ok)
+            if (!gate.ok)
+                throw new MergeGateError(label, gate.problems);
+            if (gate.alreadyMerged)
+                return null;
+            const headSha = gate.details.headSha;
+            if (headSha === null || headSha.trim().length === 0) {
+                // Strict read already guarantees this; never merge unpinned.
+                throw new MergeGateError(label, ["host did not report the head commit SHA"]);
+            }
+            const base = opts.requireBaseInHead;
+            if (base === undefined)
+                return gate.details;
+            const baseBranch = gate.details.baseBranch ?? base.baseBranch;
+            const fresh = await checkBaseInHead({ cwd: opts.cwd, remote: base.remote, baseBranch, headSha });
+            if (fresh.ok)
+                return gate.details;
+            const canUpdate = base.updateBranch === true && opts.host === "github" && fresh.problem.startsWith("stale base:");
+            if (!canUpdate)
                 throw new MergeGateError(label, [fresh.problem]);
+            if (Date.now() >= deadline) {
+                throw new MergeGateError(label, [fresh.problem, "gave up updating the branch (waitTimeoutSeconds)"]);
+            }
+            const outcome = await updateGitHubPullBranch(opts.cwd, opts.url, headSha);
+            if (outcome === "conflict") {
+                throw new MergeGateError(label, [
+                    fresh.problem,
+                    `update-branch reports a merge conflict — merge ${base.remote}/${baseBranch} into the task branch locally, resolve, task ship`,
+                ]);
+            }
+            if (outcome === "error") {
+                // Read / API error: exponential back-off with full jitter, within the same budget.
+                await sleep(Math.min(errorBackoffMs(timing.intervalMs, updateErrors++), deadline - Date.now()));
+                continue;
+            }
+            updateErrors = 0;
+            log.info(dim(`${baseBranch} moved — updated the ${label} branch on the host (merge, no force push); re-checking the new head…`));
+            await waitForHeadChange(opts.cwd, opts.host, opts.url, headSha, deadline, timing.intervalMs, label);
         }
-        return gate.details;
     };
     const details = await runGate();
     if (details === null)
@@ -662,6 +722,21 @@ export async function mergeMergeRequest(opts) {
         maxBuffer: 4 * 1024 * 1024,
     });
 }
+/** After update-branch (202, applied asynchronously): wait until the PR reports a new head. */
+async function waitForHeadChange(cwd, host, url, oldHead, deadline, intervalMs, label) {
+    for (;;) {
+        const details = await getMergeRequestDetails(cwd, host, url);
+        if (details !== null && (details.state === "merged" || (details.headSha !== null && details.headSha !== oldHead))) {
+            return;
+        }
+        if (Date.now() >= deadline) {
+            throw new MergeGateError(label, [
+                `update-branch was accepted but the ${label} head is still ${oldHead.slice(0, 7)} (gave up, waitTimeoutSeconds)`,
+            ]);
+        }
+        await sleep(Math.min(intervalMs, deadline - Date.now()));
+    }
+}
 /** `gh pr merge` argv. `--match-head-commit` needs gh ≥ 2.13.0. */
 export function gitHubMergeArgs(ref, method, headSha) {
     return ["pr", "merge", ref, `--${method}`, "--match-head-commit", headSha];

package/dist/lib/project-baseline.js

@@ -0,0 +1,196 @@
+import { join } from "node:path";
+import { readTextOrNull } from "./filesystem.js";
+import { runGit } from "./git.js";
+import { dim, log } from "./logger.js";
+import { VIBEOPS_CONFIG_FILE } from "./paths.js";
+export const BASELINE_DEFAULTS = { mode: "warn", crew: null };
+export class BaselineConfigError extends Error {
+    constructor(message) {
+        super(`Invalid \`baseline\` block in .vibeops.json: ${message}`);
+        this.name = "BaselineConfigError";
+    }
+}
+const MODES = ["off", "warn", "enforce"];
+const CREW_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Strict: object with only `mode` / `crew`. `undefined` → defaults. */
+export function parseBaselineConfig(raw) {
+    if (raw === undefined)
+        return BASELINE_DEFAULTS;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new BaselineConfigError("must be an object.");
+    }
+    const o = raw;
+    const unknown = Object.keys(o).filter((k) => k !== "mode" && k !== "crew");
+    if (unknown.length > 0) {
+        throw new BaselineConfigError(`unknown key \`${unknown[0]}\` (known: mode, crew).`);
+    }
+    let mode = BASELINE_DEFAULTS.mode;
+    if (o.mode !== undefined) {
+        if (typeof o.mode !== "string" || !MODES.includes(o.mode)) {
+            throw new BaselineConfigError("`mode` must be one of off, warn, enforce.");
+        }
+        mode = o.mode;
+    }
+    let crew = null;
+    if (o.crew !== undefined) {
+        if (typeof o.crew !== "string" || !CREW_RE.test(o.crew)) {
+            throw new BaselineConfigError("`crew` must be a crew name like `vibe-crew`.");
+        }
+        crew = o.crew;
+    }
+    return { mode, crew };
+}
+export async function readBaselineConfig(root) {
+    const text = await readTextOrNull(join(root, VIBEOPS_CONFIG_FILE));
+    if (text === null)
+        return BASELINE_DEFAULTS;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new BaselineConfigError("file is not valid JSON.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return BASELINE_DEFAULTS;
+    }
+    return parseBaselineConfig(parsed.baseline);
+}
+/** The remote's default branch from `git ls-remote --symref <remote> HEAD`, or null. */
+async function remoteDefaultBranch(cwd, remote) {
+    try {
+        const { stdout } = await runGit(cwd, ["ls-remote", "--symref", remote, "HEAD"]);
+        const m = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m.exec(stdout);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runBaselineChecks(cwd, git, cfg) {
+    const checks = [];
+    const gitflow = git.integrationBranch !== git.productionBranch;
+    checks.push({
+        id: "branch-policy",
+        ok: gitflow,
+        detail: gitflow
+            ? `${git.integrationBranch} (integration) → ${git.productionBranch} (production)`
+            : `integration and production are both ${git.integrationBranch}`,
+        fix: "set `git.integrationBranch` (e.g. develop) ≠ `git.productionBranch` (main) in .vibeops.json",
+    });
+    const def = await remoteDefaultBranch(cwd, git.remote);
+    checks.push({
+        id: "default-branch",
+        ok: def === git.integrationBranch,
+        detail: def === null
+            ? `could not read the default branch of ${git.remote}`
+            : `${git.remote} default branch is ${def}`,
+        fix: git.host === "gitlab"
+            ? `glab api --method PUT projects/:id --raw-field default_branch=${git.integrationBranch}`
+            : `gh repo edit --default-branch ${git.integrationBranch}`,
+    });
+    if (cfg.crew !== null) {
+        const source = await readTextOrNull(join(cwd, ".personas", cfg.crew, "SOURCE"));
+        checks.push({
+            id: "personas",
+            ok: source !== null,
+            detail: source !== null ? `.personas/${cfg.crew}/SOURCE present` : `.personas/${cfg.crew}/SOURCE missing`,
+            fix: `install the ${cfg.crew} crew (it writes .personas/${cfg.crew}/ and the AGENTS.md section)`,
+        });
+        const agents = await readTextOrNull(join(cwd, "AGENTS.md"));
+        const marker = `<!-- getpersona:${cfg.crew} -->`;
+        const has = agents !== null && agents.includes(marker);
+        checks.push({
+            id: "agents-contract",
+            ok: has,
+            detail: has ? `AGENTS.md has the ${cfg.crew} section` : `AGENTS.md lacks ${marker}`,
+            fix: `install the ${cfg.crew} crew (AGENTS.md section between ${marker} markers)`,
+        });
+    }
+    return checks;
+}
+/** Section `task add --repair-baseline` writes into the TASK file (read back by `task ship`). */
+export const BASELINE_REPAIR_SECTION = "Baseline";
+export const BASELINE_REPAIR_TEXT = "Repair — opened with `vibeops task add --repair-baseline`. `task ship` requires every baseline check to pass (whatever `baseline.mode` is).";
+/**
+ * Run the configured checks and print failures. Returns false only in `enforce` mode with a
+ * failing check (the caller stops); `warn` prints and continues; `off` skips. See
+ * {@link PreflightOptions} for the baseline-repair flow.
+ */
+export async function preflightBaseline(cwd, git, command, opts = {}) {
+    let cfg;
+    try {
+        cfg = await readBaselineConfig(cwd);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (opts.repair !== true) {
+            log.error(msg);
+            return false;
+        }
+        log.warn(`${msg} — continuing with defaults (baseline repair).`);
+        cfg = BASELINE_DEFAULTS;
+    }
+    if (cfg.mode === "off" && opts.repair !== true && opts.requireOk !== true)
+        return true;
+    const failed = (await runBaselineChecks(cwd, git, cfg)).filter((c) => !c.ok);
+    if (failed.length === 0) {
+        if (opts.repair === true)
+            log.info(dim("baseline: every check passes already (--repair-baseline not needed)."));
+        return true;
+    }
+    const stop = opts.requireOk === true || (cfg.mode === "enforce" && opts.repair !== true);
+    for (const c of failed) {
+        const line = `baseline ${c.id}: ${c.detail}`;
+        if (stop)
+            log.error(line);
+        else
+            log.warn(line);
+        if (c.fix)
+            log.info(dim(`  fix: ${c.fix}`));
+    }
+    if (opts.requireOk === true) {
+        log.info(dim(`${command} stopped: a baseline-repair TASK ships only when every check passes.`));
+        return false;
+    }
+    if (stop) {
+        log.info(dim(`${command} stopped (.vibeops.json baseline.mode: enforce). To repair: vibeops task add --repair-baseline`));
+        return false;
+    }
+    if (opts.repair === true)
+        log.info(dim("baseline repair: failures reported as warnings for this TASK."));
+    return true;
+}
+/** Read-only summary for `vibeops status` (never throws). */
+export async function summarizeBaseline(cwd, git) {
+    let cfg = BASELINE_DEFAULTS;
+    let configError = null;
+    try {
+        cfg = await readBaselineConfig(cwd);
+    }
+    catch (e) {
+        configError = e instanceof Error ? e.message : String(e);
+    }
+    const checks = await runBaselineChecks(cwd, git, cfg);
+    let crewCommit = null;
+    if (cfg.crew !== null) {
+        const source = await readTextOrNull(join(cwd, ".personas", cfg.crew, "SOURCE"));
+        crewCommit = source === null ? null : (/^commit:\s*(\S+)/m.exec(source)?.[1] ?? null);
+    }
+    let otherBranches = null;
+    try {
+        const { stdout } = await runGit(cwd, ["ls-remote", "--heads", git.remote]);
+        otherBranches = stdout
+            .split("\n")
+            .map((l) => l.split("\t")[1]?.replace(/^refs\/heads\//, "") ?? "")
+            .filter((b) => b.length > 0 &&
+            b !== git.integrationBranch &&
+            b !== git.productionBranch &&
+            !b.startsWith("task/") &&
+            !b.startsWith("sync/"));
+    }
+    catch {
+        otherBranches = null;
+    }
+    return { mode: cfg.mode, crew: cfg.crew, crewCommit, checks, otherBranches, configError };
+}

package/dist/lib/release-tag.js

@@ -0,0 +1,64 @@
+import { fetchBaseBranch } from "./merge-base-freshness.js";
+import { gitIsAncestor, runGit } from "./git.js";
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/**
+ * Tag the release merge commit `v<package.json version>` and push the tag, so "merged into
+ * production" and "tagged for publishing" are one step. Refuses when the commit is not on the
+ * freshly fetched `<remote>/<production>`, when package.json has no plain semver `version`,
+ * or when the tag already exists locally or on the remote (tags are never moved).
+ */
+export async function tagReleaseCommit(opts) {
+    const { cwd, remote, productionBranch, commit } = opts;
+    let prodRef;
+    try {
+        prodRef = await fetchBaseBranch(cwd, remote, productionBranch);
+    }
+    catch (e) {
+        return { ok: false, message: `could not fetch ${remote}/${productionBranch}: ${firstLine(e)}` };
+    }
+    if (!(await gitIsAncestor(cwd, commit, prodRef))) {
+        return { ok: false, message: `${short(commit)} is not on ${remote}/${productionBranch}` };
+    }
+    let version;
+    try {
+        const { stdout } = await runGit(cwd, ["show", `${commit}:package.json`]);
+        version = JSON.parse(stdout).version;
+    }
+    catch {
+        return { ok: false, message: `no readable package.json at ${short(commit)} to take the version from` };
+    }
+    if (typeof version !== "string" || !SEMVER_RE.test(version)) {
+        return { ok: false, message: `package.json version at ${short(commit)} is not a semver string` };
+    }
+    const tag = `v${version}`;
+    try {
+        await runGit(cwd, ["rev-parse", "-q", "--verify", `refs/tags/${tag}`]);
+        return { ok: false, message: `tag ${tag} already exists locally — tags are not moved` };
+    }
+    catch {
+        // absent locally: good
+    }
+    try {
+        const { stdout } = await runGit(cwd, ["ls-remote", "--tags", remote, `refs/tags/${tag}`]);
+        if (stdout.trim().length > 0) {
+            return { ok: false, message: `tag ${tag} already exists on ${remote} — tags are not moved` };
+        }
+    }
+    catch (e) {
+        return { ok: false, message: `could not list tags on ${remote}: ${firstLine(e)}` };
+    }
+    try {
+        await runGit(cwd, ["tag", tag, commit]);
+        await runGit(cwd, ["push", remote, `refs/tags/${tag}`]);
+    }
+    catch (e) {
+        return { ok: false, message: `could not create / push ${tag}: ${firstLine(e)}` };
+    }
+    return { ok: true, tag, commit };
+}
+function short(sha) {
+    return sha.slice(0, 7);
+}
+function firstLine(e) {
+    return (e instanceof Error ? e.message : String(e)).split("\n")[0];
+}

package/dist/lib/task-new-cycle.js

@@ -206,7 +206,7 @@ export async function runPostMergeNewCycle(taskRef, options = {}) {
         log.info(dim("Updating open MR/PR (--allow-open-mr)."));
     }
     else {
-        gitCtx = await refreshGitContextBaseCommit(taskFile, gitCtx, cwd);
+        gitCtx = await refreshGitContextBaseCommit(taskFile, gitCtx, cwd, remote);
         gitCtx = await prepareGitContextForReship(cwd, taskFile, gitCtx);
         await commitReshipMetadata({
             cwd,

package/dist/lib/task-reship.js

@@ -1,8 +1,9 @@
 import { resolve } from "node:path";
 import { GitConfigError, requireGitConfig } from "./git-config.js";
-import { gitBranchExists, gitCheckout, gitCheckoutNewBranch, gitDeleteBranch, gitFetchRemote, gitHeadCommit, gitMergeRemoteBranch, gitMergeInProgress, gitFetch, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, gitSwitchToBranch, listUnmergedRelPaths, readGitInfo, } from "./git.js";
+import { gitBranchExists, gitCheckout, gitCheckoutNewBranch, gitDeleteBranch, gitFetchRemote, gitMergeRemoteBranch, gitMergeInProgress, gitFetch, gitRemoteBranchExists, gitRemoteUrl, gitRevParse, gitSwitchToBranch, listUnmergedRelPaths, readGitInfo, runGit, } from "./git.js";
 import { fastForwardLocalIntegration, leaveTaskBranch, logLocalIntegrationUpdate, resolveIntegrationBaseRef, } from "./git-worktree.js";
 import { dim, log } from "./logger.js";
+import { fetchBaseBranch } from "./merge-base-freshness.js";
 import { findMergeRequestByBranches } from "./pr-create.js";
 import { normalizeTaskRef } from "./resolve-task.js";
 import { getTaskMergeRequestLifecycle, resolveGitHostForCwd, } from "./task-effective-status.js";
@@ -234,11 +235,26 @@ export async function assertMergeRequestNotOpen(cwd, taskFile, allowOpenMr) {
     log.error("Current MR/PR is still open. Merge or close it first, or rerun with --allow-open-mr.");
     return false;
 }
-export async function refreshGitContextBaseCommit(taskFile, gitCtx, cwd) {
-    const head = await gitHeadCommit(cwd);
-    if (head === null || head.length === 0)
+/**
+ * Base Commit of a new PR cycle: where this cycle starts on the base branch — the merge base
+ * of the task branch and the freshly fetched `<remote>/<base>` (the base tip after the
+ * integration merge; the fork point with `--no-integrate`). Not the task branch HEAD, which
+ * after the follow-up commit is the TASK's own work. Fetch / read failure keeps the previous
+ * value (with a warning) rather than recording a wrong one.
+ */
+export async function refreshGitContextBaseCommit(taskFile, gitCtx, cwd, remote) {
+    try {
+        const baseRef = await fetchBaseBranch(cwd, remote, gitCtx.baseBranch);
+        const { stdout } = await runGit(cwd, ["merge-base", "HEAD", baseRef]);
+        const base = stdout.trim();
+        if (base.length === 0)
+            return gitCtx;
+        return { ...gitCtx, baseCommit: base };
+    }
+    catch {
+        log.warn(`Could not read ${remote}/${gitCtx.baseBranch} — Base Commit left at ${gitCtx.baseCommit.slice(0, 7)}.`);
         return gitCtx;
-    return { ...gitCtx, baseCommit: head };
+    }
 }
 export async function prepareGitContextForReship(cwd, taskFile, gitCtx) {
     const previous = [...(gitCtx.previousMergeRequestUrls ?? [])];

package/dist/lib/task.js

@@ -335,6 +335,12 @@ function insertSectionAfter(body, afterTitle, newTitle, newContent) {
     const after = lines.slice(block.end);
     return [...before, ...newSection, ...after].join("\n");
 }
+/** Add (or replace) a `## <title>` section right after `## Status`. */
+export function withSectionAfterStatus(body, title, content) {
+    if (locateSection(body, title) !== null)
+        return replaceSectionContent(body, title, content);
+    return insertSectionAfter(body, "Status", title, content);
+}
 export async function updateInlineStatus(filePath, next) {
     const raw = await readText(filePath);
     const display = statusDisplay(next);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodtek/vibeops",
-  "version": "3.1.9",
+  "version": "3.3.0",
   "description": "Minimal CLI rails for Cursor-based TASK-driven vibe coding.",
   "type": "module",
   "packageManager": "pnpm@9.15.9",