@brainervirus/workit-claude-code 7.7.0 → 8.0.1

package/dist/workit.js

@@ -65,7 +65,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@brainervirus/workit-cli",
-    version: "7.7.0",
+    version: "8.0.1",
     private: false,
     description: "Workit CLI — setup wizard, doctor, and task control for agentic coding workflows",
     keywords: [
@@ -103,9 +103,9 @@ var init_package = __esm(() => {
     },
     dependencies: {
       "@babel/parser": "7.29.9",
-      "@brainervirus/workit-core": "^7.7.0",
-      "@brainervirus/workit-cursor": "^7.7.0",
-      "@brainervirus/workit-opencode": "^7.7.0",
+      "@brainervirus/workit-core": "^8.0.1",
+      "@brainervirus/workit-cursor": "^8.0.1",
+      "@brainervirus/workit-opencode": "^8.0.1",
       "@inkjs/ui": "2.0.0",
       ink: "7.1.1",
       react: "19.2.8"
@@ -13267,7 +13267,7 @@ function authorSessions(cwd, rows, branch, range = { base: null, head: null }) {
     sessions.add(session);
   return sessions;
 }
-function effectiveOf(rows, authors) {
+function effectiveOf(rows, authors, sameCode) {
   let effective = null;
   for (const row of rows) {
     if (!effective) {
@@ -13278,7 +13278,7 @@ function effectiveOf(rows, authors) {
     const effIndependent = independenceReasons(effective, authors).length === 0;
     if (effIndependent && !rowIndependent)
       continue;
-    if (effIndependent && FAILING.has(String(effective.result)) && row.actor.session === effective.actor.session)
+    if (effIndependent && FAILING.has(String(effective.result)) && row.actor.session === effective.actor.session && sameCode(effective, row))
       continue;
     effective = row;
   }
@@ -13309,16 +13309,22 @@ function checkVerdicts(cwd, branch, rows) {
   const head = branchHead(cwd, branch);
   const fallbackBase = defaultBase(cwd);
   const keyCache = new Map;
-  const keyFor = (base) => {
-    if (!base || !head)
+  const keysAt = (base, at) => {
+    if (!base || !at)
       return { patchId: null, diffHash: null };
-    let key = keyCache.get(base);
+    const cacheKey = `${base}\x00${at}`;
+    let key = keyCache.get(cacheKey);
     if (!key) {
-      key = { patchId: patchId(cwd, base, head), diffHash: diffHash(cwd, base, head) };
-      keyCache.set(base, key);
+      key = { patchId: patchId(cwd, base, at), diffHash: diffHash(cwd, base, at) };
+      keyCache.set(cacheKey, key);
     }
     return key;
   };
+  const keyFor = (base) => keysAt(base, head);
+  const sameCode = (failed, row) => verdictBasis(failed, {
+    head: row.head,
+    ...keysAt(failed.base ?? fallbackBase, row.head)
+  }) !== "stale" || restackCarries(rows, branch, failed.head, row.head);
   const authors = authorSessions(cwd, rows, branch, { base: fallbackBase, head });
   const byKind = new Map;
   for (const row of rows)
@@ -13328,7 +13334,7 @@ function checkVerdicts(cwd, branch, rows) {
     }
   const verdicts = [];
   for (const [kind, list] of byKind) {
-    const row = effectiveOf(list, authors);
+    const row = effectiveOf(list, authors, sameCode);
     if (!row)
       continue;
     let basis = verdictBasis(row, { head, ...keyFor(row.base ?? fallbackBase) });
@@ -13354,11 +13360,11 @@ function checkVerdicts(cwd, branch, rows) {
   verdicts.sort((a, b) => a.verdict.seq - b.verdict.seq);
   const newestCurrent = verdicts.findLast((entry) => entry.current) ?? verdicts.at(-1) ?? null;
   const failing = verdicts.find((entry) => entry.current && entry.independent && FAILING.has(String(entry.verdict.result)));
-  const newestAccepted = verdicts.findLast((entry) => entry.accepted) ?? null;
+  const newestAccepted = verdicts.findLast((entry) => entry.accepted && STRONG_RESULTS.has(String(entry.verdict.result))) ?? null;
   const accepted = newestAccepted && !failing ? { accepted: true, verdict: newestAccepted.verdict, reasons: [] } : {
     accepted: false,
     verdict: failing?.verdict ?? null,
-    reasons: failing ? ["failing_verdict"] : newestCurrent?.reasons ?? ["no_verdict"]
+    reasons: failing ? ["failing_verdict"] : !newestCurrent ? ["no_verdict"] : newestCurrent.reasons.length ? newestCurrent.reasons : ["type_check_only"]
   };
   const selfEntry = failing ? undefined : verdicts.findLast((entry) => entry.current && !entry.independent && STRONG_RESULTS.has(String(entry.verdict.result)));
   return {
@@ -13587,6 +13593,9 @@ function summarizeRow(row) {
     case "pr.merged":
       summary = `#${row.pr ?? "?"} ${text("method")} at ${(row.head ?? "?").slice(0, 12)}${text("mergeSha") ? ` -> ${text("mergeSha").slice(0, 12)}` : ""}`;
       break;
+    case "merge.unverified":
+      summary = `#${row.pr ?? "?"} unverified merge requested at ${(row.head ?? "?").slice(0, 12)} (reason: ${text("reason")})`;
+      break;
     case "delivery.verified":
       summary = `${text("expect")} delivered at ${(row.head ?? "?").slice(0, 12)}`;
       break;
@@ -13911,7 +13920,7 @@ var init_ledger = __esm(() => {
       return false;
     }
   };
-  OBSERVED_ONLY = new Set(["check", ...PR_ROW_TYPES]);
+  OBSERVED_ONLY = new Set(["check", "merge.unverified", ...PR_ROW_TYPES]);
 });
 
 // packages/workit-core/src/core/policy/derive.ts
@@ -16656,7 +16665,7 @@ function requireGrant(cwd, kind, options = {}) {
     allowed: true,
     kind,
     source: configured ? autonomy.source : "default",
-    requireVerdict: kind === "merge" && value !== true,
+    allowUnverified: kind === "merge" && value === true,
     workspace
   };
 }
@@ -19123,20 +19132,30 @@ async function parseTaskArgs(argv, deps) {
   const judge = [];
   const seen = new Set;
   for (let i = 2;i < argv.length; i += 1) {
-    const token = argv[i];
+    if (argv[i] === "--") {
+      const extra = argv.slice(i + 1);
+      if (extra.length)
+        return parseUsage(`${family} ${actionName} takes no positional arguments (got: ${extra.join(" ")})`, json);
+      break;
+    }
+    const eq = argv[i].startsWith("--") ? argv[i].indexOf("=") : -1;
+    const token = eq > 0 ? argv[i].slice(0, eq) : argv[i];
+    const inline = eq > 0 ? argv[i].slice(eq + 1) : undefined;
     if (family === "policy" && (token === "--judge" || token === "--ref")) {
       if (token === "--ref") {
-        const value = argv[++i];
+        const value = inline ?? argv[++i];
         if (value === undefined || !value.trim())
           return parseUsage("--ref requires a value", json);
         judge.push(`ref=${value}`);
         continue;
       }
+      if (inline !== undefined)
+        judge.push(inline);
       while (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--"))
         judge.push(argv[++i]);
       continue;
     }
-    if (token === "--json" || token === "--confirm") {
+    if ((token === "--json" || token === "--confirm") && inline === undefined) {
       if (seen.has(token))
         return parseUsage(`duplicate argument: ${token}`, json);
       seen.add(token);
@@ -19145,8 +19164,8 @@ async function parseTaskArgs(argv, deps) {
       continue;
     }
     if (!["--payload", "--task", "--revision", "--workspace-revision", "--view", "--actor"].includes(token))
-      return parseUsage(`unknown argument: ${token}`, json);
-    const value = argv[++i];
+      return parseUsage(`unknown argument: ${argv[i]}`, json);
+    const value = inline ?? argv[++i];
     if (value === undefined || value.trim() === "" && token !== "--workspace-revision")
       return parseUsage(`${token} requires a value`, json);
     if (seen.has(token))
@@ -19205,6 +19224,12 @@ async function parseHandoffArgs(argv, deps) {
   const seen = new Set;
   for (let i = 0;i < argv.length; i += 1) {
     const token = argv[i];
+    if (token === "--") {
+      const extra = argv.slice(i + 1);
+      if (extra.length)
+        return parseUsage(`handoff takes no positional arguments (got: ${extra.join(" ")})`, json);
+      break;
+    }
     if (token === "--json") {
       if (seen.has(token))
         return parseUsage(`duplicate argument: ${token}`, json);
@@ -19212,14 +19237,18 @@ async function parseHandoffArgs(argv, deps) {
       json = true;
       continue;
     }
-    if (token !== "--task")
+    const inline = token.startsWith("--task=") ? token.slice("--task=".length) : undefined;
+    if (token !== "--task" && inline === undefined)
       return parseUsage(`unknown argument: ${token}`, json);
-    if (taskId !== undefined || argv[i + 1] === undefined || argv[i + 1].trim() === "")
+    const value = inline ?? argv[i + 1];
+    if (taskId !== undefined || value === undefined || value.trim() === "")
       return parseUsage("--task requires one non-empty value", json);
-    if (seen.has(token))
-      return parseUsage(`duplicate argument: ${token}`, json);
-    seen.add(token);
-    taskId = argv[++i];
+    if (seen.has("--task"))
+      return parseUsage("duplicate argument: --task", json);
+    seen.add("--task");
+    taskId = value;
+    if (inline === undefined)
+      i += 1;
   }
   if (!taskId)
     return parseUsage("handoff requires --task <id>", json);
@@ -19406,13 +19435,14 @@ var init_task = __esm(() => {
 
 // packages/workit-cli/src/verbs/task.ts
 function isImplicitTaskForm(argv) {
-  const [action, first] = argv;
+  const [action, ...rest] = argv;
   if (!action)
     return false;
   if (IMPLICIT2.has(action))
     return true;
+  const first = rest.find((arg) => arg !== "--json");
   if (action === "start")
-    return first !== undefined && !first.startsWith("--");
+    return first !== undefined && (first === "--" || !first.startsWith("--"));
   if (action === "close")
     return !argv.includes("--task") && !argv.includes("--payload");
   return false;
@@ -19421,6 +19451,10 @@ function parse4(argv) {
   const flags = { positionals: [], values: new Map, switches: new Set };
   for (let index = 0;index < argv.length; index += 1) {
     const arg = argv[index];
+    if (arg === "--") {
+      flags.positionals.push(...argv.slice(index + 1));
+      break;
+    }
     const [flag, inline] = arg.startsWith("--") && arg.includes("=") ? arg.split(/=(.*)/su) : [arg];
     if (SWITCHES.has(flag)) {
       flags.switches.add(flag);
@@ -34280,7 +34314,7 @@ function getSgrPrefix(code) {
   if (code.startsWith("›")) {
     return "›";
   }
-  return `${ESCAPE}${ANSI_CSI2}`;
+  return `${ESCAPE2}${ANSI_CSI2}`;
 }
 function createSgrCode(prefix, values) {
   return `${prefix}${values.join(";")}${ANSI_SGR_TERMINATOR2}`;
@@ -34289,7 +34323,7 @@ function getSgrFragments(code) {
   const fragments = [];
   const sgrPrefix = getSgrPrefix(code);
   let parameterString;
-  if (code.startsWith(`${ESCAPE}${ANSI_CSI2}`)) {
+  if (code.startsWith(`${ESCAPE2}${ANSI_CSI2}`)) {
     parameterString = code.slice(2, -1);
   } else if (code.startsWith("›")) {
     parameterString = code.slice(1, -1);
@@ -34450,7 +34484,7 @@ function parseHyperlinkCode(string, index) {
         endIndex: sequenceIndex + 1
       };
     }
-    if (character === ESCAPE && string[sequenceIndex + 1] === ANSI_OSC_TERMINATOR) {
+    if (character === ESCAPE2 && string[sequenceIndex + 1] === ANSI_OSC_TERMINATOR) {
       const code = string.slice(index, sequenceIndex + 2);
       const action = sequenceIndex === uriStart + 1 ? "close" : "open";
       return {
@@ -34533,7 +34567,7 @@ function parseControlStringCode(string, index) {
     if (supportsBellTerminator && string[sequenceIndex] === ANSI_BELL) {
       return createControlParseResult(string.slice(index, sequenceIndex + 1), sequenceIndex + 1);
     }
-    if (string[sequenceIndex] === ESCAPE && string[sequenceIndex + 1] === ANSI_OSC_TERMINATOR) {
+    if (string[sequenceIndex] === ESCAPE2 && string[sequenceIndex + 1] === ANSI_OSC_TERMINATOR) {
       return createControlParseResult(string.slice(index, sequenceIndex + 2), sequenceIndex + 2);
     }
     if (string[sequenceIndex] === C1_STRING_TERMINATOR) {
@@ -34758,7 +34792,7 @@ function tokenizeAnsi(string, { endCharacter = Number.POSITIVE_INFINITY } = {})
   }
   return tokens;
 }
-var ESCAPE_CODE_POINT = 27, C1_DCS_CODE_POINT = 144, C1_SOS_CODE_POINT = 152, C1_CSI_CODE_POINT = 155, C1_ST_CODE_POINT = 156, C1_OSC_CODE_POINT = 157, C1_PM_CODE_POINT = 158, C1_APC_CODE_POINT = 159, ESCAPES2, ESCAPE = "\x1B", ANSI_BELL = "\x07", ANSI_CSI2 = "[", ANSI_OSC2 = "]", ANSI_DCS = "P", ANSI_SOS = "X", ANSI_PM = "^", ANSI_APC = "_", ANSI_SGR_TERMINATOR2 = "m", ANSI_OSC_TERMINATOR = "\\", ANSI_STRING_TERMINATOR, C1_OSC = "", C1_STRING_TERMINATOR = "œ", ANSI_HYPERLINK_ESC_PREFIX, ANSI_HYPERLINK_C1_PREFIX, ANSI_HYPERLINK_ESC_CLOSE, ANSI_HYPERLINK_C1_CLOSE, CODE_POINT_0, CODE_POINT_9, CODE_POINT_SEMICOLON, CODE_POINT_COLON, CODE_POINT_CSI_PARAMETER_START, CODE_POINT_CSI_PARAMETER_END, CODE_POINT_CSI_INTERMEDIATE_START, CODE_POINT_CSI_INTERMEDIATE_END, CODE_POINT_CSI_FINAL_START, CODE_POINT_CSI_FINAL_END, REGIONAL_INDICATOR_SYMBOL_LETTER_A = 127462, REGIONAL_INDICATOR_SYMBOL_LETTER_Z = 127487, SGR_RESET_CODE = 0, SGR_EXTENDED_FOREGROUND_CODE = 38, SGR_DEFAULT_FOREGROUND_CODE = 39, SGR_EXTENDED_BACKGROUND_CODE = 48, SGR_DEFAULT_BACKGROUND_CODE = 49, SGR_COLOR_TYPE_ANSI_256 = 5, SGR_COLOR_TYPE_TRUECOLOR = 2, SGR_ANSI_256_FRAGMENT_LENGTH = 3, SGR_TRUECOLOR_FRAGMENT_LENGTH = 5, SGR_ANSI_256_LAST_PARAMETER_OFFSET = 2, SGR_TRUECOLOR_LAST_PARAMETER_OFFSET = 4, VARIATION_SELECTOR_16_CODE_POINT = 65039, COMBINING_ENCLOSING_KEYCAP_CODE_POINT = 8419, EMOJI_PRESENTATION_GRAPHEME_REGEX, GRAPHEME_SEGMENTER, endCodeNumbers;
+var ESCAPE_CODE_POINT = 27, C1_DCS_CODE_POINT = 144, C1_SOS_CODE_POINT = 152, C1_CSI_CODE_POINT = 155, C1_ST_CODE_POINT = 156, C1_OSC_CODE_POINT = 157, C1_PM_CODE_POINT = 158, C1_APC_CODE_POINT = 159, ESCAPES2, ESCAPE2 = "\x1B", ANSI_BELL = "\x07", ANSI_CSI2 = "[", ANSI_OSC2 = "]", ANSI_DCS = "P", ANSI_SOS = "X", ANSI_PM = "^", ANSI_APC = "_", ANSI_SGR_TERMINATOR2 = "m", ANSI_OSC_TERMINATOR = "\\", ANSI_STRING_TERMINATOR, C1_OSC = "", C1_STRING_TERMINATOR = "œ", ANSI_HYPERLINK_ESC_PREFIX, ANSI_HYPERLINK_C1_PREFIX, ANSI_HYPERLINK_ESC_CLOSE, ANSI_HYPERLINK_C1_CLOSE, CODE_POINT_0, CODE_POINT_9, CODE_POINT_SEMICOLON, CODE_POINT_COLON, CODE_POINT_CSI_PARAMETER_START, CODE_POINT_CSI_PARAMETER_END, CODE_POINT_CSI_INTERMEDIATE_START, CODE_POINT_CSI_INTERMEDIATE_END, CODE_POINT_CSI_FINAL_START, CODE_POINT_CSI_FINAL_END, REGIONAL_INDICATOR_SYMBOL_LETTER_A = 127462, REGIONAL_INDICATOR_SYMBOL_LETTER_Z = 127487, SGR_RESET_CODE = 0, SGR_EXTENDED_FOREGROUND_CODE = 38, SGR_DEFAULT_FOREGROUND_CODE = 39, SGR_EXTENDED_BACKGROUND_CODE = 48, SGR_DEFAULT_BACKGROUND_CODE = 49, SGR_COLOR_TYPE_ANSI_256 = 5, SGR_COLOR_TYPE_TRUECOLOR = 2, SGR_ANSI_256_FRAGMENT_LENGTH = 3, SGR_TRUECOLOR_FRAGMENT_LENGTH = 5, SGR_ANSI_256_LAST_PARAMETER_OFFSET = 2, SGR_TRUECOLOR_LAST_PARAMETER_OFFSET = 4, VARIATION_SELECTOR_16_CODE_POINT = 65039, COMBINING_ENCLOSING_KEYCAP_CODE_POINT = 8419, EMOJI_PRESENTATION_GRAPHEME_REGEX, GRAPHEME_SEGMENTER, endCodeNumbers;
 var init_tokenize_ansi = __esm(() => {
   init_ansi_styles();
   init_is_fullwidth_code_point();
@@ -34772,8 +34806,8 @@ var init_tokenize_ansi = __esm(() => {
     C1_PM_CODE_POINT,
     C1_APC_CODE_POINT
   ]);
-  ANSI_STRING_TERMINATOR = `${ESCAPE}${ANSI_OSC_TERMINATOR}`;
-  ANSI_HYPERLINK_ESC_PREFIX = `${ESCAPE}${ANSI_OSC2}8;`;
+  ANSI_STRING_TERMINATOR = `${ESCAPE2}${ANSI_OSC_TERMINATOR}`;
+  ANSI_HYPERLINK_ESC_PREFIX = `${ESCAPE2}${ANSI_OSC2}8;`;
   ANSI_HYPERLINK_C1_PREFIX = `${C1_OSC}8;`;
   ANSI_HYPERLINK_ESC_CLOSE = `${ANSI_HYPERLINK_ESC_PREFIX};`;
   ANSI_HYPERLINK_C1_CLOSE = `${ANSI_HYPERLINK_C1_PREFIX};`;
@@ -71015,18 +71049,14 @@ async function change(verb, argv, io, deps) {
   ]);
 }
 async function runGrant(argv, io, deps = defaultDeps) {
-  const [sub, ...rest] = argv;
+  const end = argv.indexOf("--");
+  const [sub, ...rest] = end < 0 ? argv : [...argv.slice(0, end), ...argv.slice(end + 1)];
   if (sub === "show")
     return show(rest, io);
-  if (sub === undefined || sub.startsWith("--") && sub !== "--help")
+  if (sub === undefined || sub.startsWith("--"))
     return show(argv, io);
   if (sub === "set" || sub === "unset")
     return change(sub, rest, io, deps);
-  if (sub === "--help" || sub === "-h") {
-    io.stdout(`usage: ${USAGE2}
-`);
-    return 0;
-  }
   return usage2(io, `unknown subcommand "${sub}"`);
 }
 var USAGE2 = "workit grant show [<workspace>] [--all] | grant set <workspace> <kind>=<true|false|verified>… [defaultEndpoint=commit|pr|green|merged] [verification=self|independent] | grant unset <workspace> <kind>…  (kinds: push, pr, merge, release, rerun, defaultEndpoint, verification)", AGENT_ENV, agentMarker = (env) => AGENT_ENV.find((name) => env[name]) ?? Object.keys(env).find((name) => name.startsWith("CODEX_") && env[name]), defaultDeps, parseValue = (raw) => raw === "true" || raw === "yes" || raw === "on" ? true : raw === "false" || raw === "no" || raw === "off" ? false : raw === "verified" ? "verified" : null, STOPS_AT, endpointLabel = (view) => view.effectiveEndpoint === view.defaultEndpoint ? view.defaultEndpoint : `${view.defaultEndpoint} (effective: ${view.effectiveEndpoint}${view.endpointReason ? `, ${view.endpointReason}` : ""})`, describe2 = (grants, configured, endpoint, verification) => [
@@ -72339,13 +72369,19 @@ async function createPullRequest(cwd, resolved, input, sleep) {
     head: sha,
     created,
     draft: input.draft,
-    recorded: row.ok ? { id: String(row.value.id) } : { error: row.error }
+    recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+    next: createNext(cwd)
   });
 }
 async function mergePullRequest(cwd, resolved, input, sleep) {
   const grant = requireGrant(cwd, "merge");
   if (!grant.allowed)
     return refuse(grant.error, grant.unblock, { reason: "grant_required" });
+  const bypass = input.unverified ?? null;
+  if (bypass && !bypass.reason.trim())
+    return failure3("invalid_input", "--unverified needs --reason <why the user asked for it>");
+  if (bypass && !grant.allowUnverified)
+    return refuse(`unverified_refused: workspace ${grant.workspace ? `"${grant.workspace}"` : "(none)"} grants merge: "verified", which never merges without an accepted independent verdict`, "a non-author session verifies the head (workit-review), then merge without --unverified", { reason: "unverified_refused" });
   const number = selectPr(cwd, resolved, { pr: input.pr });
   if (!number.ok)
     return number;
@@ -72379,27 +72415,40 @@ async function mergePullRequest(cwd, resolved, input, sleep) {
     if (reason)
       return refuse(`protected_branch: --delete-branch would delete ${branch}, which ${reason}; workit never deletes it`, `workit pr merge${input.pr ? ` --pr ${doc.number}` : ""} --method ${input.method}  # without --delete-branch`, { reason: "protected_branch" });
   }
+  const ledger = readLedger(cwd);
+  if (!ledger.ok)
+    return ledger;
+  const check = checkVerdicts(cwd, branch, ledger.value.rows);
+  const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
+  const covered = check.head === head && check.accepted.accepted;
   let verdict = {
-    required: grant.requireVerdict,
-    accepted: false,
-    verdictId: null
+    required: true,
+    accepted: covered,
+    verdictId: covered && typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null
   };
-  if (grant.requireVerdict) {
-    const ledger = readLedger(cwd);
-    if (!ledger.ok)
-      return ledger;
-    const check = checkVerdicts(cwd, branch, ledger.value.rows);
-    const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
-    if (check.head !== head)
-      return refuse(`head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`, `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`, { reason: "head_mismatch", verdict: summary });
-    if (!check.accepted.accepted)
-      return refuse(`NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`, `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}`, { reason: "needs_verdict", verdict: summary });
-    verdict = {
-      required: true,
-      accepted: true,
-      verdictId: typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null
-    };
-  }
+  let unverified = null;
+  if (!covered && bypass && check.accepted.reasons.includes("failing_verdict"))
+    return refuse(`failed_verdict: ${label} has a current independent failed verdict${typeof check.accepted.verdict?.id === "string" ? ` (${check.accepted.verdict.id})` : ""}; --unverified never merges over a rejection`, "a new independent verdict on the head supersedes it", { reason: "failed_verdict", verdict: summary });
+  if (!covered && bypass) {
+    const reason = bypass.reason.trim();
+    const recorded = appendObserved(cwd, {
+      type: "merge.unverified",
+      actor: input.actor,
+      branch,
+      head,
+      pr: doc.number,
+      base: doc.base,
+      reason,
+      grant: grant.source
+    });
+    if (!recorded.ok)
+      return failure3("failed", `unverified_unrecorded: the --unverified bypass could not be recorded (${recorded.error}); nothing was merged`);
+    verdict = { required: false, accepted: false, verdictId: null };
+    unverified = { reason, recorded: String(recorded.value.id) };
+  } else if (check.head !== head)
+    return refuse(`head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`, `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`, { reason: "head_mismatch", verdict: summary });
+  else if (!covered)
+    return refuse(`NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`, `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${grant.allowUnverified ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"` : ""}`, { reason: "needs_verdict", verdict: summary });
   const merged = resolved.forge.merge(doc.number, { sha: head, method: input.method });
   if (!merged.ok)
     return merged;
@@ -72437,6 +72486,7 @@ async function mergePullRequest(cwd, resolved, input, sleep) {
     mergeSha: merged.data.mergeSha,
     method: input.method,
     verdictId: verdict.verdictId,
+    ...unverified ? { unverified: unverified.recorded } : {},
     grant: grant.source
   });
   return {
@@ -72450,6 +72500,7 @@ async function mergePullRequest(cwd, resolved, input, sleep) {
       method: input.method,
       mergeSha: merged.data.mergeSha,
       verdict,
+      unverified,
       grant: { source: grant.source },
       deletedBranch,
       recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
@@ -72458,7 +72509,10 @@ async function mergePullRequest(cwd, resolved, input, sleep) {
     }
   };
 }
-var VERIFY_DELAYS_MS, noun = (resolved) => resolved.forge.kind === "github" ? "pull request" : "merge request", grantBlocked = (decision) => failure3("blocked", decision.error, decision.unblock), mergeBackFor = (cwd, base) => {
+var VERIFY_DELAYS_MS, noun = (resolved) => resolved.forge.kind === "github" ? "pull request" : "merge request", grantBlocked = (decision) => failure3("blocked", decision.error, decision.unblock), AFTER_REVIEW, createNext = (cwd) => {
+  const endpoint = resolveAutonomy(cwd).effectiveEndpoint;
+  return `a non-author verifies the head (workit-review); the endpoint is ${endpoint}, so ${AFTER_REVIEW[endpoint]}`;
+}, mergeBackFor = (cwd, base) => {
   try {
     const owners = workspaceReleaseTracks(cwd).tracks.filter((track) => track.productionBranch === base);
     if (owners.length !== 1)
@@ -72487,6 +72541,12 @@ var init_pr_ops = __esm(() => {
   init_ledger();
   init_report();
   VERIFY_DELAYS_MS = [1000, 2000, 4000];
+  AFTER_REVIEW = {
+    commit: "stop here; review comes when the user asks",
+    pr: "stop here; review comes when the user asks",
+    green: "babysit it to merge-ready, never merging",
+    merged: "babysit it, then land it after verification"
+  };
   NEXT_HINTS = {
     RESOLVE_CONFLICTS: "rebase onto the base, resolve, then workit git push --force-with-lease",
     REBASE: "rebase onto the base, then workit git push --force-with-lease",
@@ -73358,6 +73418,10 @@ function parseFlags(argv, spec) {
   const parsed = { values: {}, booleans: new Set, lists: {}, positionals: [] };
   for (let index = 0;index < argv.length; index += 1) {
     const arg = argv[index];
+    if (arg === "--") {
+      parsed.positionals.push(...argv.slice(index + 1));
+      break;
+    }
     if (arg === "--json")
       continue;
     if (!arg.startsWith("--")) {
@@ -73385,6 +73449,14 @@ function parseFlags(argv, spec) {
   }
   return parsed;
 }
+function unverifiedFlag(flags) {
+  const reason = flags.values.reason?.trim();
+  if (!flags.booleans.has("unverified"))
+    return reason === undefined ? null : "--reason is only used with --unverified";
+  if (!reason)
+    return "--unverified needs --reason <why the user asked for it>";
+  return reason.length > MAX_REASON ? `--reason is capped at ${MAX_REASON} characters` : { reason };
+}
 function positiveInt(value, flag) {
   if (value === undefined)
     return null;
@@ -73468,7 +73540,7 @@ function renderStatus(doc) {
   lines.push(`next: ${doc.next}`);
   return lines;
 }
-var forgeDeps, usage3 = (io, message, line) => emit(io, fail("invalid_input", message, { unblock: line })), forgeFail = (io, result, data) => emit(io, fail(result.code, result.error, { data, unblock: result.unblock })), short = (sha) => sha ? sha.slice(0, 7) : "?";
+var forgeDeps, MAX_REASON = 500, usage3 = (io, message, line) => emit(io, fail("invalid_input", message, { unblock: line })), forgeFail = (io, result, data) => emit(io, fail(result.code, result.error, { data, unblock: result.unblock })), short = (sha) => sha ? sha.slice(0, 7) : "?";
 var init_forge_common = __esm(() => {
   init_resolve();
   init_vcs_config();
@@ -73614,13 +73686,23 @@ async function create4(argv, io) {
     ...data.releaseTrack?.name ? [`release track: ${data.releaseTrack.name} (${data.releaseTrack.detail})`] : [],
     ...(data.releaseTrack?.warnings ?? []).map((warning) => `note: ${warning}`),
     `head ${data.head.slice(0, 12)} verified on the forge`,
-    ..."error" in data.recorded ? [`ledger: not recorded (${data.recorded.error})`] : []
+    ..."error" in data.recorded ? [`ledger: not recorded (${data.recorded.error})`] : [],
+    `next: ${data.next}`
   ]);
 }
 async function merge3(argv, io) {
-  const flags = parseFlags(argv, { pr: "value", method: "value", "delete-branch": "boolean" });
+  const flags = parseFlags(argv, {
+    pr: "value",
+    method: "value",
+    "delete-branch": "boolean",
+    unverified: "boolean",
+    reason: "value"
+  });
   if (typeof flags === "string")
     return usage3(io, flags, MERGE_USAGE);
+  const unverified = unverifiedFlag(flags);
+  if (typeof unverified === "string")
+    return usage3(io, unverified, MERGE_USAGE);
   if (flags.positionals.length)
     return usage3(io, `unexpected argument ${flags.positionals[0]}`, MERGE_USAGE);
   const pr = positiveInt(flags.values.pr, "--pr");
@@ -73632,7 +73714,13 @@ async function merge3(argv, io) {
   const connected = connect(io);
   if (!connected.ok)
     return forgeFail(io, connected);
-  const result = await mergePullRequest(io.cwd, connected.data, { pr, method, deleteBranch: flags.booleans.has("delete-branch"), actor: actorFromEnv(io.env) }, forgeDeps.sleep);
+  const result = await mergePullRequest(io.cwd, connected.data, {
+    pr,
+    method,
+    deleteBranch: flags.booleans.has("delete-branch"),
+    actor: actorFromEnv(io.env),
+    ...unverified ? { unverified } : {}
+  }, forgeDeps.sleep);
   if (!result.ok)
     return emit(io, fail(result.code, result.error, {
       unblock: result.unblock,
@@ -73640,7 +73728,7 @@ async function merge3(argv, io) {
     }));
   return emit(io, ok(result.data), (data) => [
     `merged ${connected.data.forge.kind === "github" ? "PR #" : "MR !"}${data.number} (${data.method}) at head ${data.head.slice(0, 12)}${data.mergeSha ? ` -> ${data.mergeSha.slice(0, 12)}` : ""}`,
-    data.verdict.required ? `verdict ${data.verdict.verdictId ?? "?"} accepted for that head` : "no verdict required (workspace grants merge: true)",
+    data.unverified ? `UNVERIFIED: merged without a verdict (--unverified: ${data.unverified.reason}); ledger ${data.unverified.recorded}` : `verdict ${data.verdict.verdictId ?? "?"} accepted for that head`,
     ...data.mergeBack.length ? [
       `merge back: ${data.base} is the ${data.mergeBackTrack} production branch; bring it into ${data.mergeBack.join(", ")}`
     ] : [],
@@ -73658,7 +73746,7 @@ async function run10(argv, io) {
     return merge3(rest, io);
   return usage3(io, sub && !sub.startsWith("-") ? `unknown pr subcommand "${sub}"` : "missing pr subcommand", USAGE4);
 }
-var STATUS_USAGE = "workit pr status [--pr <n> | --branch <b>] [--log-lines 60] [--json]", CREATE_USAGE = "workit pr create [--base <b> | --track <t>] (--title <t> [--body <text> | --body-file <f>] | --fill) [--draft] [--json]", MERGE_USAGE = "workit pr merge [--pr <n>] [--method squash|merge|rebase] [--delete-branch] [--json]", USAGE4 = "workit pr status|create|merge ... (workit help pr)", METHODS2;
+var STATUS_USAGE = "workit pr status [--pr <n> | --branch <b>] [--log-lines 60] [--json]", CREATE_USAGE = "workit pr create [--base <b> | --track <t>] (--title <t> [--body <text> | --body-file <f>] | --fill) [--draft] [--json]", MERGE_USAGE = "workit pr merge [--pr <n>] [--method squash|merge|rebase] [--delete-branch] [--unverified --reason <why>] [--json]", USAGE4 = "workit pr status|create|merge ... (workit help pr)", METHODS2;
 var init_pr = __esm(() => {
   init_pr_body();
   init_pr_ops();
@@ -74945,7 +75033,7 @@ function repoMismatch(ctx, stack) {
     return stackFail("blocked", `repo_mismatch: stack ${stack.name} was planned on ${stack.forge ?? "?"} ${stack.repo ?? "?"}, but this checkout resolves to ${kind} ${repo}`, `workit stack plan --name ${stack.name} <branch…>  # re-plan it here, or run from the right checkout`, { planned: { forge: stack.forge, repo: stack.repo }, resolved: { forge: kind, repo } });
   return null;
 }
-function qualify(ctx, stack, entry, doc, verdict, grant, binding = null) {
+function qualify(ctx, stack, entry, doc, verdict, grant, binding = null, bypass = false) {
   const label = entry.pr ? noun2(ctx.resolved, entry.pr) : entry.branch;
   const stop = (reason, detail, unblock, ready = false) => ({
     ok: false,
@@ -74964,9 +75052,11 @@ function qualify(ctx, stack, entry, doc, verdict, grant, binding = null) {
     return stop("base_not_trunk", `${label} targets ${doc.base}, not ${stack.trunk}`, "workit stack sync");
   if (doc.next !== "READY")
     return stop("not_ready", `${label} is ${doc.next}${doc.blockers.length ? ` (${doc.blockers.join(", ")})` : ""}`, doc.next === "WAITING_CI" ? `workit ci wait --pr ${entry.pr}` : `workit pr status --pr ${entry.pr}`);
-  const requireVerdict = grant.allowed ? grant.requireVerdict : true;
-  if (requireVerdict && !verdict.accepted)
-    return stop(verdict.reasons.includes("no_verdict") ? "no_verdict" : "needs_verdict", `${label} has no accepted independent verdict for ${doc.head.sha.slice(0, 12)} (${verdict.reasons.join(", ") || "none"})`, `an independent session verifies ${entry.branch} and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${entry.branch}`);
+  const allowUnverified = grant.allowed && grant.allowUnverified;
+  if (bypass && allowUnverified && verdict.reasons.includes("failing_verdict"))
+    return stop("failed_verdict", `${label} has a current independent failed verdict for ${doc.head.sha.slice(0, 12)}; --unverified never lands over a rejection`, "a new independent verdict on the head supersedes it");
+  if (!(bypass && allowUnverified) && !verdict.accepted)
+    return stop(verdict.reasons.includes("no_verdict") ? "no_verdict" : "needs_verdict", `${label} has no accepted independent verdict for ${doc.head.sha.slice(0, 12)} (${verdict.reasons.join(", ") || "none"})`, `an independent session verifies ${entry.branch} and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${entry.branch}${allowUnverified ? `; or, only if the user asks to land unverified: workit stack land --unverified --reason "<why>"` : ""}`);
   if (!grant.allowed)
     return stop("grant_required", `${label} is verified and ready, but ${grant.error}`, grant.unblock, true);
   return { ok: true };
@@ -75384,6 +75474,14 @@ async function landStack(ctx, stack, options) {
   const mismatch = repoMismatch(ctx, stack);
   if (mismatch)
     return failWith(mismatch);
+  const bypass = options.unverified ?? null;
+  if (bypass) {
+    const grant = requireGrant(ctx.cwd, "merge");
+    if (!grant.allowed)
+      return failWith(stackFail("blocked", grant.error, grant.unblock, { reason: "grant_required" }));
+    if (!grant.allowUnverified)
+      return failWith(stackFail("blocked", `unverified_refused: workspace ${grant.workspace ? `"${grant.workspace}"` : "(none)"} grants merge: "verified", which never lands without an accepted independent verdict`, "a non-author session verifies each head (workit-review), then land without --unverified", { reason: "unverified_refused" }));
+  }
   if (!options.dryRun) {
     const synced = syncStack(ctx.cwd, ctx, stack, { publish: true, dryRun: false, limit: 1 }, ctx.actor);
     if (!synced.ok)
@@ -75429,7 +75527,7 @@ async function landStack(ctx, stack, options) {
     const grant = requireGrant(ctx.cwd, "merge");
     const verdict = verdictOf(ctx.cwd, entry.branch, ledgerRows());
     const effective = options.dryRun && simulated.size > 0 && doc ? { ...doc, base: stack.trunk } : doc;
-    const q = qualify(ctx, stack, entry, effective, verdict, grant, doc ? prBinding(ctx, entry, doc) : null);
+    const q = qualify(ctx, stack, entry, effective, verdict, grant, doc ? prBinding(ctx, entry, doc) : null, bypass !== null);
     if (!q.ok) {
       outcome.stoppedAt = {
         pr: entry.pr,
@@ -75452,7 +75550,8 @@ async function landStack(ctx, stack, options) {
       method: options.method,
       deleteBranch: false,
       actor: ctx.actor,
-      expect: { base: stack.trunk, branch: entry.branch }
+      expect: { base: stack.trunk, branch: entry.branch },
+      ...bypass && !verdict.accepted ? { unverified: bypass } : {}
     }, ctx.sleep);
     if (!merged.ok) {
       if (merged.code === "blocked" && "refusal" in merged && merged.refusal) {
@@ -75468,7 +75567,12 @@ async function landStack(ctx, stack, options) {
       }
       return failWith(stackFail(merged.code, merged.error, merged.unblock));
     }
-    outcome.landed.push({ pr, branch: entry.branch, mergeSha: merged.data.mergeSha });
+    outcome.landed.push({
+      pr,
+      branch: entry.branch,
+      mergeSha: merged.data.mergeSha,
+      unverified: merged.data.unverified?.recorded ?? null
+    });
     entry.merged = { pr, mergeSha: merged.data.mergeSha, at: new Date().toISOString() };
     const written = writeStack(ctx.cwd, stack);
     if (!written.ok)
@@ -75701,10 +75805,15 @@ async function land(argv, io) {
     max: "value",
     method: "value",
     timeout: "value",
-    interval: "value"
+    interval: "value",
+    unverified: "boolean",
+    reason: "value"
   });
   if (typeof flags === "string")
     return usage3(io, flags, LAND_USAGE);
+  const unverified = unverifiedFlag(flags);
+  if (typeof unverified === "string")
+    return usage3(io, unverified, LAND_USAGE);
   if (flags.positionals.length)
     return usage3(io, `unexpected argument ${flags.positionals[0]}`, LAND_USAGE);
   const max = positiveInt(flags.values.max, "--max");
@@ -75735,7 +75844,7 @@ async function land(argv, io) {
       resolved: connected.data,
       actor: actorFromEnv(io.env),
       sleep: forgeDeps.sleep
-    }, fresh.data ?? selected.data, { dryRun: flags.booleans.has("dry-run"), max, method, timeoutMs, intervalMs });
+    }, fresh.data ?? selected.data, { dryRun: flags.booleans.has("dry-run"), max, method, timeoutMs, intervalMs, unverified });
   });
   if (!result.ok)
     return stackFailed(io, result);
@@ -75744,7 +75853,7 @@ async function land(argv, io) {
     ...data.dryRun ? [
       data.wouldLand.length ? `would land: ${data.wouldLand.map((item) => `${label(kind, item.pr)} (${item.branch})`).join(", ")}` : "would land nothing"
     ] : [
-      data.landed.length ? `landed: ${data.landed.map((item) => `${label(kind, item.pr)} (${item.branch}) -> ${short4(item.mergeSha)}`).join(", ")}` : "landed nothing"
+      data.landed.length ? `landed: ${data.landed.map((item) => `${label(kind, item.pr)} (${item.branch}) -> ${short4(item.mergeSha)}${item.unverified ? ` UNVERIFIED (ledger ${item.unverified})` : ""}`).join(", ")}` : "landed nothing"
     ],
     ...data.retargeted.length ? [`retargeted: ${data.retargeted.map((pr) => label(kind, pr)).join(", ")}`] : [],
     ...data.restacked.length ? [`restacked: ${data.restacked.join(", ")}`] : [],
@@ -75764,7 +75873,7 @@ async function run14(argv, io) {
     return land(rest, io);
   return usage3(io, sub && !sub.startsWith("-") ? `unknown stack subcommand "${sub}"` : "missing stack subcommand", USAGE7);
 }
-var PLAN_USAGE = "workit stack plan [--name <n>] [--trunk <b> | --track <t>] [<bottom> … <top>] [--json]", STATUS_USAGE2 = "workit stack status [--name <n>] [--json]", SYNC_USAGE = "workit stack sync [--name <n>] [--local] [--dry-run] [--force <branch>]… [--json]", LAND_USAGE = "workit stack land [--name <n>] [--dry-run] [--max <n>] [--method squash|merge|rebase] [--timeout 20m] [--interval 30s] [--json]", USAGE7 = "workit stack plan|status|sync|land ... (workit help stack)", short4 = (sha) => sha ? sha.slice(0, 12) : "?", stackFailed = (io, result) => emit(io, fail(result.code, result.error, { unblock: result.unblock, data: result.data ?? {} })), label = (forge, pr) => pr === null ? "no PR" : `${forge === "gitlab" ? "MR !" : "PR #"}${pr}`, renderSync = (data) => [
+var PLAN_USAGE = "workit stack plan [--name <n>] [--trunk <b> | --track <t>] [<bottom> … <top>] [--json]", STATUS_USAGE2 = "workit stack status [--name <n>] [--json]", SYNC_USAGE = "workit stack sync [--name <n>] [--local] [--dry-run] [--force <branch>]… [--json]", LAND_USAGE = "workit stack land [--name <n>] [--dry-run] [--max <n>] [--method squash|merge|rebase] [--unverified --reason <why>] [--timeout 20m] [--interval 30s] [--json]", USAGE7 = "workit stack plan|status|sync|land ... (workit help stack)", short4 = (sha) => sha ? sha.slice(0, 12) : "?", stackFailed = (io, result) => emit(io, fail(result.code, result.error, { unblock: result.unblock, data: result.data ?? {} })), label = (forge, pr) => pr === null ? "no PR" : `${forge === "gitlab" ? "MR !" : "PR #"}${pr}`, renderSync = (data) => [
   `${data.dryRun ? "would sync" : "synced"} stack ${data.name}${data.merged.length ? `; merged: ${data.merged.map((item) => item.branch).join(", ")}` : ""}`,
   ...data.steps.map((step) => [
     `  ${step.branch} on ${step.parent}:`,
@@ -94739,6 +94848,10 @@ function parse7(argv) {
   };
   for (let index = 0;index < argv.length; index += 1) {
     const raw = argv[index];
+    if (raw === "--") {
+      options.paths.push(...argv.slice(index + 1));
+      break;
+    }
     const [flag, inline] = raw.startsWith("--") && raw.includes("=") ? [raw.slice(0, raw.indexOf("=")), raw.slice(raw.indexOf("=") + 1)] : [raw, undefined];
     if (flag === "--json")
       continue;
@@ -95310,7 +95423,7 @@ async function resumeBrief(argv, io) {
   return emit(io, ok({ ...data, recorded }), human2);
 }
 async function run21(argv, io) {
-  if (!argv.includes("--task"))
+  if (!argv.some((arg) => arg === "--task" || arg.startsWith("--task=")))
     return resumeBrief(argv, io);
   await Promise.resolve().then(() => init_task());
   return runTaskCommand(["handoff", ...argv]);
@@ -95323,9 +95436,99 @@ var init_handoff = __esm(() => {
 
 // packages/workit-cli/src/main.ts
 init_package();
-init_output();
 import path52 from "node:path";
 
+// packages/workit-cli/src/help.ts
+var HELP_FLAGS = new Set(["--help", "-h"]);
+var ESCAPE = "A value that starts with - goes as --flag=value (or after a bare --).";
+var options = (args) => {
+  const end = args.indexOf("--");
+  return end < 0 ? args : args.slice(0, end);
+};
+var wantsHelp = (args) => options(args).some((arg) => HELP_FLAGS.has(arg));
+var firstWord = (args) => options(args).find((arg) => !arg.startsWith("-"));
+var valueFlags = (lines) => {
+  const out = new Map;
+  const group = /(?<![\w-])(--?[a-zA-Z][\w-]*(?:\|--?[a-zA-Z][\w-]*)*) (?=[<"a-z0-9])/gu;
+  for (const line of lines)
+    for (const match of line.matchAll(group)) {
+      const names = match[1].split("|");
+      const long = names.find((name) => name.startsWith("--")) ?? names[0];
+      for (const name of names)
+        out.set(name, long);
+    }
+  return out;
+};
+function helpAsValue(args, lines) {
+  const before = options(args);
+  const takes = valueFlags(lines);
+  for (let index = 1;index < before.length; index += 1) {
+    const flag = before[index];
+    const long = takes.get(before[index - 1]);
+    if (HELP_FLAGS.has(flag) && long)
+      return `\`${flag}\` looks like the value of ${before[index - 1]}; use ${long}=${flag} or put it after --`;
+  }
+  return null;
+}
+function takesPositionals(lines) {
+  const flag = /(?<![\w-])--?[a-zA-Z][\w-]*(?:\|--?[a-zA-Z][\w-]*)*(?:[ =](?!-)(?:<[^>]*>|"[^"]*"|[\w.,@/|=-]+)…?)?/gu;
+  return lines.some((line) => /<|"|\w…|\s…/u.test(line.replace(flag, "")));
+}
+var usageLines = (entry) => entry.subcommands?.length ? entry.subcommands.map((sub) => sub.usage) : [entry.usage];
+var examplesFor = (entry, sub) => (entry.examples ?? []).filter((example) => sub ? new RegExp(`^workit ${entry.name} ${sub.name}(?![\\w-])`, "u").test(example) : true);
+var exampleBlock = (examples) => examples.length ? ["", "examples:", ...examples.map((line) => `  ${line}`)] : [];
+function verbHelp(entry) {
+  const subs = entry.subcommands ?? [];
+  const usages = usageLines(entry);
+  const examples = examplesFor(entry);
+  const text = [
+    ...subs.length ? [
+      `workit ${entry.name}: ${entry.summary}`,
+      "",
+      ...subs.flatMap((sub) => [`usage: ${sub.usage}`, `    ${sub.summary}`])
+    ] : [`usage: ${entry.usage}`, "", entry.summary],
+    ...exampleBlock(examples),
+    "",
+    ...subs.length ? [`More: workit help ${entry.name} <${subs.map((sub) => sub.name).join("|")}>`] : [],
+    ESCAPE
+  ].join(`
+`);
+  return {
+    name: entry.name,
+    group: entry.group,
+    usage: usages[0],
+    usages,
+    summary: entry.summary,
+    examples,
+    text
+  };
+}
+function subcommandHelp(entry, sub) {
+  const examples = examplesFor(entry, sub);
+  return {
+    name: entry.name,
+    group: entry.group,
+    subcommand: sub.name,
+    usage: sub.usage,
+    usages: [sub.usage],
+    summary: sub.summary,
+    examples,
+    text: [
+      `usage: ${sub.usage}`,
+      "",
+      sub.summary,
+      ...exampleBlock(examples),
+      "",
+      ...sub.aliases?.length ? [`aliases: ${sub.aliases.join(", ")}`] : [],
+      ESCAPE
+    ].join(`
+`)
+  };
+}
+
+// packages/workit-cli/src/main.ts
+init_output();
+
 // packages/workit-cli/src/verbs/registry.ts
 var TASK_FAMILY_NAMES = [
   "task",
@@ -95336,13 +95539,97 @@ var TASK_FAMILY_NAMES = [
   "worker",
   "state"
 ];
-var family = (name) => ({
+var FAMILY_OPTIONS = "[--task <id>] [--payload <JSON|@file|->] [--revision <r>] [--workspace-revision <r|null>] [--view <v>] [--actor <a>] [--confirm]";
+var FAMILY_ACTIONS = {
+  task: {
+    list: "List the workspace's tasks",
+    inspect: "Show one task's full state",
+    revise: "Change a task's intent or scope",
+    progress: "Record progress on a task",
+    pause: "Pause a task",
+    resume: "Resume a paused task",
+    start: "Start a task from a full payload",
+    close: "Close a task by id"
+  },
+  policy: {
+    assess: "Judge the branch's work and record the derived checks, verdicts and gates",
+    preview: "Show what a judgment would derive, without recording it",
+    explain: "Explain the policy in force"
+  },
+  evidence: { record: "Record evidence against a task's requirements" },
+  finding: { record: "Record a finding", resolve: "Resolve a finding" },
+  decision: { record: "Record a task decision", revoke: "Revoke a task decision" },
+  worker: {
+    assign: "Assign a worker to a task",
+    report: "Report a worker's result",
+    cancel: "Cancel a worker assignment"
+  },
+  state: { export: "Export a task's state (v1)", import: "Import an exported task state" }
+};
+var POLICY_JUDGE = "--judge risk=trivial|normal|high behavior=yes|no product-choice=yes|no plan=yes|no [--ref <path>]…";
+var TASK_IMPLICIT = [
+  {
+    name: "status",
+    usage: "workit task status [--all]",
+    summary: "The current branch's task, or every task with --all"
+  },
+  {
+    name: "start",
+    usage: `workit task start "<objective>" | task start ${FAMILY_OPTIONS}`,
+    summary: "Start tracking the current branch's task (idempotent per branch)"
+  },
+  {
+    name: "note",
+    usage: 'workit task note [--next "<t>"] [--objective "<t>"] [--] "<text>"',
+    summary: "Add a progress note to the current branch's task (creates it if needed)"
+  },
+  {
+    name: "close",
+    usage: `workit task close [--outcome verified|limited|stopped] [--summary "<t>"] [--confirm] | task close ${FAMILY_OPTIONS}`,
+    summary: "Close the current branch's task, or a task by id"
+  },
+  {
+    name: "adopt",
+    usage: "workit task adopt <id>",
+    summary: "Bind a migrated or other task to the current branch"
+  }
+];
+var familySubcommands = (name) => {
+  const implicit = name === "task" ? TASK_IMPLICIT : [];
+  const grammar = Object.entries(FAMILY_ACTIONS[name]).filter(([action]) => !implicit.some((entry) => entry.name === action)).map(([action, summary]) => ({
+    name: action,
+    usage: name === "policy" && action !== "explain" ? `workit policy ${action} ${POLICY_JUDGE} ${FAMILY_OPTIONS}` : `workit ${name} ${action} ${FAMILY_OPTIONS}`,
+    summary
+  }));
+  return [...implicit, ...grammar];
+};
+var family = (name) => withSubcommands({
   name,
   group: "task",
-  usage: name === "task" ? 'workit task status [--all] | task start "<objective>" | task note "<text>" [--next "<t>"] | task close [--outcome verified|limited|stopped] | task adopt <id> | task <action> --payload <JSON>' : name === "policy" ? "workit policy assess|preview --judge risk=trivial|normal|high behavior=yes|no product-choice=yes|no plan=yes|no [--ref <path>] | policy explain" : `workit ${name} <action> [options]`,
   summary: name === "task" ? "The current branch's task (created by its first note, check or recording; no ids needed), or the task family" : name === "policy" ? "Judge the branch's work; Workit derives its checks, verdicts, decision and plan gates" : `Inspect and control a Workit task (${name} family)`,
+  subcommands: familySubcommands(name),
+  ...name === "task" ? {
+    examples: [
+      'workit task note "parser done; wiring the router" --next "add the router test"',
+      "workit task close --outcome verified"
+    ]
+  } : name === "policy" ? {
+    examples: [
+      "workit policy assess --judge risk=normal behavior=yes product-choice=no plan=no"
+    ]
+  } : {},
   load: async () => (await Promise.resolve().then(() => (init_family(), exports_family))).familyVerb(name)
 });
+function withSubcommands(entry, options = {}) {
+  const names = entry.subcommands.map((sub) => sub.name).join("|");
+  return {
+    ...entry,
+    usage: `workit ${entry.name} ${options.optional ? `[${names}]` : names} [options]`,
+    ...options.optional ? { optionalSubcommand: true } : {}
+  };
+}
+var VERIFY_OPTIONS = "[--expect pushed|pr|merged|released] [--pr <n> | --branch <b>] [--sha <sha>] [--tag <t>] [--package <name[@version]>]";
+var LEDGER_ACTOR = "[--branch <b> | --pr <n>] [--supersedes <id>] [--session <id> | --as <role>]";
 var VERBS = [
   {
     name: "init",
@@ -95354,28 +95641,28 @@ var VERBS = [
   {
     name: "upgrade",
     group: "setup",
-    usage: "workit upgrade [--hosts=a,b|none] [--cli] [--preview | --apply --confirm] [--json]",
+    usage: "workit upgrade [--hosts=a,b|none] [--cli] [--preview | --apply --confirm]",
     summary: "Preview upgrades (--apply --confirm to apply)",
     load: () => Promise.resolve().then(() => (init_upgrade2(), exports_upgrade))
   },
   {
     name: "launch",
     group: "setup",
-    usage: "workit launch <host> [--auto-upgrade] [-- args]",
+    usage: "workit launch <host> [--auto-upgrade] [-- <host args…>]",
     summary: "Upgrade before host startup, then start the host",
     load: () => Promise.resolve().then(() => (init_launch(), exports_launch))
   },
   {
     name: "doctor",
     group: "setup",
-    usage: "workit doctor [--json] [--fix-lock [--force [--yes]]]",
+    usage: "workit doctor [--fix-lock [--force [--yes]]]",
     summary: "Verify the offline installation health (--fix-lock clears a stale workit store lock)",
     load: () => Promise.resolve().then(() => (init_doctor2(), exports_doctor))
   },
   {
     name: "gc",
     group: "setup",
-    usage: "workit gc [--dry-run] [--prune-recovery --yes] [--json]",
+    usage: "workit gc [--dry-run] [--prune-recovery --yes]",
     summary: "Compact long task event logs, drop unreferenced blobs and old check logs; report (or prune) 2.x recovery copies",
     load: () => Promise.resolve().then(() => (init_gc(), exports_gc))
   },
@@ -95386,108 +95673,312 @@ var VERBS = [
     summary: "Remove workit host registrations interactively (~/.config/workit is kept)",
     load: () => Promise.resolve().then(() => (init_uninstall2(), exports_uninstall))
   },
-  {
+  withSubcommands({
     name: "grant",
     group: "setup",
-    usage: "workit grant show [<workspace>] [--all] | grant set <workspace> <kind>=<true|false|verified>… | grant unset <workspace> <kind>…",
     summary: "Show or change a workspace's autonomy grants (push, pr, merge, release, rerun) and default endpoint; raising needs the user at a terminal",
+    subcommands: [
+      {
+        name: "show",
+        usage: "workit grant show [<workspace>] [--all]",
+        summary: "Show the grants of the current (or named) workspace, or of every workspace"
+      },
+      {
+        name: "set",
+        usage: "workit grant set <workspace> <kind>=<true|false|verified>… [defaultEndpoint=commit|pr|green|merged] [verification=self|independent]",
+        summary: "Change grants (kinds: push, pr, merge, release, rerun); raising one asks the user to confirm at a terminal"
+      },
+      {
+        name: "unset",
+        usage: "workit grant unset <workspace> <kind>…",
+        summary: "Remove grants, falling back to the defaults"
+      }
+    ],
+    examples: ["workit grant show", "workit grant set my-repo push=true pr=true"],
     load: () => Promise.resolve().then(() => (init_grant(), exports_grant))
-  },
+  }, { optional: true }),
   ...TASK_FAMILY_NAMES.map(family),
   {
     name: "check",
     group: "delivery",
-    usage: "workit check <name> | workit check [--name <n>] [--shell] [--timeout <s>] [--task <id>] -- <cmd…>",
+    usage: "workit check <name> [--task <id>] [--base <ref>] | workit check [--name <n>] [--shell] [--timeout <s>] [--task <id>] [--base <ref>] -- <cmd…>",
     summary: "Run a configured or ad-hoc check and record CLI-observed evidence (exit = the command's)",
+    examples: ["workit check test", "workit check --name unit -- bun test test/unit"],
     load: () => Promise.resolve().then(() => (init_check(), exports_check))
   },
-  {
+  withSubcommands({
     name: "pr",
     group: "delivery",
-    usage: "workit pr status [--pr <n>] | pr create [--base <b> | --track <t>] (--title <t> | --fill) [--draft] | pr merge [--pr <n>] [--method squash|merge|rebase] [--delete-branch]",
     summary: "PR/MR state with failing log tails and next action; open a SHA-verified PR; merge only when READY, verified and granted",
+    subcommands: [
+      {
+        name: "status",
+        usage: "workit pr status [--pr <n> | --branch <b>] [--log-lines 60]",
+        summary: "PR/MR state, failing check log tails and the next action"
+      },
+      {
+        name: "create",
+        usage: "workit pr create [--base <b> | --track <t>] (--title <t> [--body <text> | --body-file <f>] | --fill) [--draft]",
+        summary: "Open a PR/MR for the pushed branch, verified against the local HEAD"
+      },
+      {
+        name: "merge",
+        usage: "workit pr merge [--pr <n>] [--method squash|merge|rebase] [--delete-branch] [--unverified --reason <why>]",
+        summary: "Merge when READY, verified by a non-author and granted"
+      }
+    ],
+    examples: [
+      'workit pr create --title "fix(cli): answer help flags first" --body-file pr.md',
+      "workit pr merge --method squash --delete-branch"
+    ],
     load: () => Promise.resolve().then(() => (init_pr(), exports_pr))
-  },
-  {
+  }),
+  withSubcommands({
     name: "ci",
     group: "delivery",
-    usage: "workit ci wait [--pr <n>] [--head <sha>] [--timeout 20m] | ci rerun [--failed | --check <name>…] --reason flake|infra [--force]",
     summary: "Wait for CI on the PR head (exit 0/1/3/4), or rerun failed jobs once per head",
+    subcommands: [
+      {
+        name: "wait",
+        usage: "workit ci wait [--pr <n> | --branch <b>] [--head <sha>] [--timeout 20m] [--interval 30s]",
+        summary: "Wait for CI on the PR head; exit 0 green, 1 red, 3 blocked, 4 still pending"
+      },
+      {
+        name: "rerun",
+        usage: "workit ci rerun [--pr <n> | --branch <b>] [--check <name>… | --failed] --reason flake|infra [--force]",
+        summary: "Rerun failed jobs once per head, with a recorded reason"
+      }
+    ],
+    examples: ["workit ci wait --timeout 30m", "workit ci rerun --failed --reason flake"],
     load: () => Promise.resolve().then(() => (init_ci(), exports_ci))
-  },
-  {
+  }),
+  withSubcommands({
     name: "git",
     group: "delivery",
-    usage: "workit git branch <name> [--base <b>] [--track <t>] | git commit -m <msg> [--all | -- <paths…>] | git push [--set-upstream] [--force-with-lease]",
     summary: "Policy-checked branch and commit (Workit-Session trailer); push with a lease and a verified remote tip",
+    subcommands: [
+      {
+        name: "branch",
+        usage: "workit git branch <name> | git branch --kind feature|bugfix|hotfix --slug <s>  [--base <b>] [--track <t>] [--carry]",
+        summary: "Create and switch to a branch from the trunk or a release track"
+      },
+      {
+        name: "commit",
+        usage: "workit git commit -m|--message <msg>… [-a|--all | [--] <paths…>]",
+        summary: "Commit with a linted Conventional Commit message and the session trailer"
+      },
+      {
+        name: "push",
+        usage: "workit git push [-u|--set-upstream] [--force-with-lease [--expect <sha>] [--overwrite-unintegrated]]",
+        summary: "Push the current branch and verify the remote tip (never a blind --force)"
+      }
+    ],
+    examples: [
+      "workit git branch --kind feature --slug help-everywhere",
+      'workit git commit -m "fix(cli): answer help flags first" --all',
+      "workit git push --set-upstream"
+    ],
     load: () => Promise.resolve().then(() => (init_git2(), exports_git))
-  },
-  {
+  }),
+  withSubcommands({
     name: "verify-delivery",
     group: "delivery",
-    usage: "workit verify-delivery [push|pr|merge|release] [--pr <n> | --branch <b>] [--sha <s>] [--tag <t>] [--package <p>]",
     summary: "Observe that a push, PR head, merge or release really landed on the remote (exit 1 when not)",
+    subcommands: [
+      ["push", "pushed", "the branch's remote tip is the local HEAD"],
+      ["pr", null, "the PR head is the local HEAD"],
+      ["merge", "merged", "the PR merged into its base"],
+      ["release", "released", "the release tag and package exist"]
+    ].map(([name, alias, what]) => ({
+      name,
+      ...alias ? { aliases: [alias] } : {},
+      usage: `workit verify-delivery ${name} ${VERIFY_OPTIONS}`,
+      summary: `Observe that ${what}`
+    })),
+    examples: ["workit verify-delivery push", "workit verify-delivery merge --pr 42"],
     load: () => Promise.resolve().then(() => (init_verify_delivery(), exports_verify_delivery))
-  },
-  {
+  }, { optional: true }),
+  withSubcommands({
     name: "stack",
     group: "delivery",
-    usage: "workit stack plan [<bottom> … <top>] | status | sync [--local] | land [--dry-run] [--max <n>] [--json]",
     summary: "Plan, restack (lease push + retarget) and land a base-branch stack of PRs, root first",
+    subcommands: [
+      {
+        name: "plan",
+        usage: "workit stack plan [--name <n>] [--trunk <b> | --track <t>] [<bottom> … <top>]",
+        summary: "Record the stack's branches, bottom first"
+      },
+      {
+        name: "status",
+        usage: "workit stack status [--name <n>]",
+        summary: "Each stacked PR's base, head, CI and verdict"
+      },
+      {
+        name: "sync",
+        usage: "workit stack sync [--name <n>] [--local] [--dry-run] [--force <branch>]…",
+        summary: "Restack onto the moved bases, lease-push and retarget the PRs"
+      },
+      {
+        name: "land",
+        usage: "workit stack land [--name <n>] [--dry-run] [--max <n>] [--method squash|merge|rebase] [--unverified --reason <why>] [--timeout 20m] [--interval 30s]",
+        summary: "Merge the stack root first, restacking the rest as each lands"
+      }
+    ],
+    examples: ["workit stack plan feature/a feature/b feature/c", "workit stack land --dry-run"],
     load: () => Promise.resolve().then(() => (init_stack2(), exports_stack))
-  },
-  {
+  }),
+  withSubcommands({
     name: "fanout",
     group: "delivery",
-    usage: "workit fanout plan <plan.json> [--name <n>] [--trunk <b> | --track <t>] [--take-lead] | fanout brief <slice> [--mode new|resume] [--attempt <n>] | fanout check [<slice>…] [--name <n>] [--base <ref>] [--offline] | fanout status [--name <n>] [--stuck-after 30m] [--offline] | fanout worktree create|release <slice> [--force] [--json]",
     summary: "Register parallel slices (complete briefs, disjoint scopes, shared-file owners), render each worker's brief with the standing orders, watch them (STUCK, PR, CI, verdict, landed, landing order), make and release slice worktrees, and gate fan-in: out-of-scope edits, trunk and sibling merge conflicts",
+    subcommands: [
+      {
+        name: "plan",
+        usage: "workit fanout plan <plan.json> [--name <n>] [--trunk <b> | --track <t>] [--take-lead]",
+        summary: "Register the slices of a plan file"
+      },
+      {
+        name: "brief",
+        usage: "workit fanout brief <slice> [--mode new|resume] [--attempt <n>] [--name <n>]",
+        summary: "Render one worker's brief with the standing orders"
+      },
+      {
+        name: "check",
+        usage: "workit fanout check [<slice>…] [--name <n>] [--base <ref>] [--offline]",
+        summary: "Gate fan-in: out-of-scope edits, trunk and sibling merge conflicts"
+      },
+      {
+        name: "status",
+        usage: "workit fanout status [--name <n>] [--stuck-after 30m] [--offline]",
+        summary: "Each slice's state: STUCK, PR, CI, verdict, landed, landing order"
+      },
+      {
+        name: "worktree",
+        usage: "workit fanout worktree create|release <slice> [--name <n>] [--force]",
+        summary: "Make or release a slice's worktree (--force applies to release only)"
+      }
+    ],
+    examples: [
+      "workit fanout plan plan.json --take-lead",
+      "workit fanout status --stuck-after 20m"
+    ],
     load: () => Promise.resolve().then(() => (init_fanout2(), exports_fanout))
-  },
-  {
+  }),
+  withSubcommands({
     name: "ledger",
     group: "delivery",
-    usage: "workit ledger decision|ruling|verdict|standing|list|check ...",
     summary: "Record and query decisions, rulings, SHA-keyed verdicts (patch-id carry-over across rebases) and a fanout's standing orders",
+    subcommands: [
+      {
+        name: "decision",
+        usage: `workit ledger decision "<what>" --why "<why>" [--ref <path|url>]… ${LEDGER_ACTOR}`,
+        summary: "Record a decision and why"
+      },
+      {
+        name: "ruling",
+        usage: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>" [--ref <path|url>]… ${LEDGER_ACTOR}`,
+        summary: "Record a ruling on an open choice, with the cost of being wrong"
+      },
+      {
+        name: "verdict",
+        usage: `workit ledger verdict <result> --how "<method/evidence>" [--kind unit|live|perf|review] [--base <ref>] [--surface ui|cli|api] [--evidence <ref>]… [--self] ${LEDGER_ACTOR} | ledger verdict [<branch>]`,
+        summary: "Record a SHA-keyed verdict on the branch head (result: verified, tests-verified, type-check-only, blocked, failed), or show the current verdicts"
+      },
+      {
+        name: "list",
+        aliases: ["show"],
+        usage: "workit ledger list|show [--branch <b>] [--pr <n>] [--type <t>] [--last <n>]",
+        summary: "List ledger rows, newest last"
+      },
+      {
+        name: "check",
+        usage: "workit ledger check [--pr <n> | --branch <b>]",
+        summary: "Whether the branch head carries an accepted non-author verdict"
+      },
+      {
+        name: "standing",
+        usage: `workit ledger standing add "<order>" | standing list | standing clear [<id>]  [--fanout <name>] [--supersedes <id>] [--session <id> | --as <role>]`,
+        summary: "The lead's standing orders for a fanout's workers"
+      },
+      {
+        name: "add",
+        usage: 'workit ledger add decision|ruling|verdict "<what>" …',
+        summary: "Same as the bare decision, ruling and verdict forms"
+      }
+    ],
+    examples: [
+      'workit ledger decision "keep the registry as the help source" --why "one place to update"',
+      'workit ledger verdict verified --how "ran the CLI against a scratch repo" --kind live --as verifier'
+    ],
     load: () => Promise.resolve().then(() => (init_ledger2(), exports_ledger))
-  },
+  }),
   {
     name: "test-audit",
     group: "delivery",
-    usage: "workit test-audit [paths…] [--diff [base]] [--rule <ids>] [--min-severity <level>] [--fail-on <level>] [--mutate [--test-cmd <cmd {files}>] [--max-mutants <n>] [--budget <s>]] [--json]",
+    usage: "workit test-audit [paths…] [--diff [<base>]] [--rule <ids>] [--min-severity <level>] [--fail-on <level>] [--mutate [--test-cmd <cmd {files}>] [--max-mutants <n>] [--budget <s>] [--timeout <s>]]",
     summary: "Flag tautological and low-value tests with a suggested independent oracle; --mutate checks changed lines with diff-scoped mutation",
     load: () => Promise.resolve().then(() => (init_test_audit(), exports_test_audit))
   },
-  {
+  withSubcommands({
     name: "knowledge",
     group: "delivery",
-    usage: "workit knowledge lint [--json]",
     summary: "Lint agent knowledge files: AGENTS.md byte budget, broken local links, scaffold-only files, duplicated rules (exit 1 on findings)",
+    subcommands: [
+      {
+        name: "lint",
+        usage: "workit knowledge lint",
+        summary: "Lint AGENTS.md and the knowledge files it links"
+      }
+    ],
     load: () => Promise.resolve().then(() => (init_knowledge2(), exports_knowledge))
-  },
-  {
+  }),
+  withSubcommands({
     name: "youtrack",
     group: "delivery",
-    usage: "workit youtrack note <ISSUE> (--markdown <t> | --file <p>) [--minutes <n>] | youtrack time|meeting <ISSUE> --minutes <n> [--text <t>] [--date auto|YYYY-MM-DD]",
     summary: "Post a YouTrack comment or log work time (host permission, no grant)",
+    subcommands: [
+      {
+        name: "note",
+        usage: "workit youtrack note <ISSUE> (--markdown <t> | --file <p>) [--minutes <n>] [--date auto|YYYY-MM-DD]",
+        summary: "Post a comment, optionally logging time"
+      },
+      {
+        name: "time",
+        usage: "workit youtrack time <ISSUE> --minutes <n> [--text <t>] [--date auto|YYYY-MM-DD]",
+        summary: "Log work time"
+      },
+      {
+        name: "meeting",
+        usage: "workit youtrack meeting <ISSUE> --minutes <n> --text <t> [--date auto|YYYY-MM-DD]",
+        summary: "Log meeting time"
+      }
+    ],
     load: () => Promise.resolve().then(() => (init_youtrack2(), exports_youtrack))
-  },
-  {
+  }),
+  withSubcommands({
     name: "changelog",
     group: "delivery",
-    usage: "workit changelog apply (--entries <JSON|@file|-> | --normalize-only) [--path CHANGELOG.md] [--preview]",
     summary: "Add entries under the Unreleased section of the changelog",
+    subcommands: [
+      {
+        name: "apply",
+        usage: "workit changelog apply (--entries <JSON|@file|-> | --normalize-only) [--path CHANGELOG.md] [--preview]",
+        summary: "Add entries (or only normalize the file)"
+      }
+    ],
     load: () => Promise.resolve().then(() => (init_changelog2(), exports_changelog))
-  },
+  }),
   {
     name: "handoff",
     group: "delivery",
-    usage: "workit handoff [--note <t>] [--next <t>] [--record] | workit handoff --task <id>",
+    usage: "workit handoff [--note <t>] [--next <t>] [--record] [--last <n>] | workit handoff --task <id>",
     summary: "Print a resume brief (branch, HEAD, dirty state, verdict, rulings, next command); --task exports v1 task state",
     load: () => Promise.resolve().then(() => (init_handoff(), exports_handoff))
   }
 ];
 var BY_NAME = new Map(VERBS.map((entry) => [entry.name, entry]));
 var findVerb = (name) => BY_NAME.get(name);
+var findSubcommand = (entry, name) => entry.subcommands?.find((sub) => sub.name === name || sub.aliases?.includes(name));
 
 // packages/workit-cli/src/main.ts
 var GROUP_TITLES = {
@@ -95519,20 +96010,17 @@ ${sections.join(`
 `)}
 
 Global flags:
-  --json        Machine-readable output: {"ok","code","data","error"?,"unblock"?}
-  --cwd <dir>   Run as if started in <dir>
-  --version     Print the CLI version
-  help <cmd>    Show usage for one command
+  --json             Machine-readable output: {"ok","code","data","error"?,"unblock"?}
+  --cwd <dir>        Run as if started in <dir>
+  --version          Print the CLI version
+  -h, --help         Show usage for the command and subcommand before it (runs nothing)
+  help <cmd> [<sub>] The same, as a command
 
 Exit codes: 0 ok · 1 failed · 2 usage · 3 blocked · 4 busy/pending · 5 unavailable
 
 Run \`npx @brainervirus/workit-cli init\` to configure platforms, YouTrack, VCS and project hygiene.
 `;
 }
-var verbHelp = (entry) => `usage: ${entry.usage}
-
-${entry.summary}${entry.planned ? ` (coming in ${entry.planned})` : ""}
-`;
 function parseGlobals(argv) {
   const rest = [];
   let json = false;
@@ -95578,18 +96066,38 @@ async function main(argv, overrides = {}, options = {}) {
     return emit(io, ok({ version: package_default.version }), (data) => data.version);
   }
   if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    const topic = command === "help" ? args.find((arg) => !arg.startsWith("-")) : undefined;
+    const [topic, sub] = command === "help" ? words2(args) : [];
     if (topic) {
       const entry = findVerb(topic);
       if (!entry)
         return unknown2(io, topic);
-      return emit(io, ok(describe3(entry)), () => verbHelp(entry));
+      if (sub === undefined)
+        return help(io, verbHelp(entry));
+      const found = findSubcommand(entry, sub);
+      if (!found)
+        return emit(io, fail("invalid_input", `unknown ${topic} subcommand "${sub}"`, {
+          unblock: `workit help ${topic}`
+        }));
+      return help(io, subcommandHelp(entry, found));
     }
     return emit(io, ok({ version: package_default.version, verbs: listed().map(describe3) }), () => helpText());
   }
   const entry = findVerb(command);
   if (!entry)
     return unknown2(io, command);
+  if (wantsHelp(verbArgs)) {
+    const word = firstWord(verbArgs);
+    const sub = word === undefined ? undefined : findSubcommand(entry, word);
+    const asValue = helpAsValue(verbArgs, sub ? [sub.usage] : usageLines(entry));
+    if (asValue)
+      return emit(io, fail("invalid_input", asValue, {
+        unblock: `workit help ${entry.name}${sub ? ` ${sub.name}` : ""}`
+      }));
+    return help(io, sub ? subcommandHelp(entry, sub) : verbHelp(entry));
+  }
+  const ended = endOfOptions(io, entry, args);
+  if (typeof ended === "number")
+    return ended;
   if (parsed.cwd !== null) {
     try {
       process.chdir(io.cwd);
@@ -95607,8 +96115,8 @@ async function main(argv, overrides = {}, options = {}) {
 `);
   const verb = await entry.load();
   if (!io.json)
-    return verb.run(args, io);
-  return runJsonPure(io, command, (pure) => verb.run(args, pure));
+    return verb.run(ended, io);
+  return runJsonPure(io, command, (pure) => verb.run(ended, pure));
 }
 var CODE_FOR_EXIT = {
   1: "failed",
@@ -95671,10 +96179,32 @@ var withJsonFlag = (args) => {
   return end < 0 ? [...args, "--json"] : [...args.slice(0, end), "--json", ...args.slice(end)];
 };
 var listed = () => VERBS.filter((entry) => !entry.planned);
+function endOfOptions(io, entry, args) {
+  const end = args.indexOf("--");
+  if (end < 0)
+    return args;
+  const word = firstWord(args);
+  const sub = word === undefined ? undefined : findSubcommand(entry, word);
+  const unblock = `workit help ${entry.name}${sub ? ` ${sub.name}` : ""}`;
+  if (entry.subcommands?.length && !sub) {
+    if (entry.optionalSubcommand || word !== undefined)
+      return args;
+    return emit(io, fail("invalid_input", `missing ${entry.name} subcommand`, { unblock }));
+  }
+  if (takesPositionals(sub ? [sub.usage] : [entry.usage]))
+    return args;
+  const extra = args.slice(end + 1);
+  if (extra.length)
+    return emit(io, fail("invalid_input", `${entry.name}${sub ? ` ${sub.name}` : ""} takes no positional arguments (got: ${extra.join(" ")})`, { unblock }));
+  return args.slice(0, end);
+}
+var words2 = (args) => args.filter((arg) => !arg.startsWith("-"));
+var help = (io, doc) => emit(io, ok(doc), (data) => data.text);
 var describe3 = (entry) => ({
   name: entry.name,
   group: entry.group,
   usage: entry.usage,
+  usages: usageLines(entry),
   summary: entry.summary,
   ...entry.planned ? { planned: entry.planned } : {}
 });