@maycombhq/atticus 2.0.0-beta.21 → 2.0.0-beta.22

package/dist/{chunk-HSZMPH5T.js → chunk-IDKCWSM5.js}

@@ -8,22 +8,22 @@ import {
   addStoreReference,
   readStoreMarker,
   readStoreVia
-} from "./chunk-D2WSW4GU.js";
+} from "./chunk-UUU4CLJG.js";
 import {
   AdapterError,
   mergeBlockers,
   requireApproval
-} from "./chunk-4KNOJC6J.js";
+} from "./chunk-7IGKHZ4Z.js";
 import {
   outsideProfileSystems,
   readCatalog
-} from "./chunk-4SLBCEPD.js";
+} from "./chunk-J2JAKCIW.js";
 import {
   baseClonePath,
   createGit,
   readChangeRepos,
   writeChangeRepos
-} from "./chunk-XOL3GFW2.js";
+} from "./chunk-PKBHS4AA.js";
 import {
   ChangeArtifact,
   ChangeLifecycle,
@@ -50,13 +50,15 @@ import {
   questionsRelOf,
   readFlow,
   readQuestion,
-  require_dist,
   specFlowFiles,
   toCanonicalYaml
-} from "./chunk-PAINMSID.js";
+} from "./chunk-Q2TECDIT.js";
 import {
   writeFileAtomic
-} from "./chunk-ODMBPDDV.js";
+} from "./chunk-TUULXQRW.js";
+import {
+  require_dist
+} from "./chunk-BQGDB6ZL.js";
 import {
   __toESM
 } from "./chunk-TV45EUGM.js";
@@ -628,22 +630,33 @@ function changeStore(root) {
       await writeFileAtomic(path, serializeChange(value));
       return path;
     },
+    listWithProblems,
     async list() {
-      let names;
+      return (await listWithProblems()).changes;
+    }
+  };
+  async function listWithProblems() {
+    let names;
+    try {
+      names = (await readdir2(changesDirOf(root), { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== "archive" && RecordId.safeParse(d.name).success).map((d) => d.name).sort();
+    } catch {
+      return { changes: [], problems: [] };
+    }
+    const changes = [];
+    const problems = [];
+    for (const n of names) {
       try {
-        names = (await readdir2(changesDirOf(root), { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== "archive" && RecordId.safeParse(d.name).success).map((d) => d.name).sort();
-      } catch {
-        return [];
-      }
-      const out = [];
-      for (const n of names) {
         const c = await tryRead(n);
         if (c)
-          out.push(c);
+          changes.push(c);
+      } catch (e) {
+        if (!(e instanceof ChangeFileError))
+          throw e;
+        problems.push({ file: e.path, message: e.message });
       }
-      return out;
     }
-  };
+    return { changes, problems };
+  }
 }
 
 // packages/changes/dist/codeowners.js
@@ -1650,8 +1663,19 @@ async function checkFindings(root, change, gates) {
       continue;
     const round2 = Math.max(...rounds);
     const dir = join7(base, String(round2));
+    const files = (await readdir4(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
+    const unfinished = {
+      code: "round-unfinished",
+      message: `Critic round ${round2} on the ${gate} gate didn't finish: run atticus critic ${change.id} --gate ${gate} again.`
+    };
+    let hasMeta = false;
     try {
       const meta = (0, import_yaml5.parse)(await readFile6(join7(dir, "meta", "round.yaml"), "utf8"));
+      hasMeta = true;
+      if (meta?.state === "in-progress") {
+        reasons.push(unfinished);
+        continue;
+      }
       for (const l of meta?.lenses ?? [])
         if (l.state === "waiting")
           reasons.push({
@@ -1665,7 +1689,10 @@ async function checkFindings(root, change, gates) {
           });
     } catch {
     }
-    const files = (await readdir4(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
+    if (!hasMeta && files.length === 0) {
+      reasons.push(unfinished);
+      continue;
+    }
     for (const f of files) {
       const rel = `review/${gate}/${round2}/${f}`;
       let data;
@@ -1837,19 +1864,87 @@ var NothingFile = external_exports.strictObject({
     commit: external_exports.string().regex(/^[0-9a-f]{7,64}$/).optional(),
     at: external_exports.string().min(1),
     by: external_exports.string().min(1)
-  }))
+  })),
+  /**
+   * Review round 48: the change branch's commit when Sync first read each release PR merged, so
+   * a merged PR stands only while the branch is there (work landed since needs a PR of its own).
+   */
+  merged: external_exports.array(external_exports.strictObject({
+    repo: external_exports.string().min(1),
+    number: external_exports.number().int().positive(),
+    commit: external_exports.string().regex(/^[0-9a-f]{7,64}$/),
+    at: external_exports.string().min(1)
+  })).optional()
 });
-async function readNothing(root, id) {
+async function readReleaseFile(root, id) {
+  const empty = { schemaVersion: 1, nothingToRelease: [] };
   const text = await readFile8(join9(changeFolder(root, id), RELEASE_PRS_FILE), "utf8").catch(() => void 0);
   if (text === void 0)
-    return [];
+    return empty;
   try {
     const r = NothingFile.safeParse((0, import_yaml7.parse)(text));
-    return r.success ? r.data.nothingToRelease : [];
+    return r.success ? r.data : empty;
   } catch {
-    return [];
+    return empty;
   }
 }
+async function readNothing(root, id) {
+  return (await readReleaseFile(root, id)).nothingToRelease;
+}
+async function writeReleaseFile(root, id, nothing, merged) {
+  const byRepo = (xs) => [...xs].sort((a, b) => a.repo < b.repo ? -1 : a.repo > b.repo ? 1 : 0);
+  await writeFile(join9(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({
+    schemaVersion: 1,
+    nothingToRelease: byRepo(nothing),
+    ...merged.length ? { merged: byRepo(merged) } : {}
+  })), "utf8");
+}
+function repoDir(root, r) {
+  const dirs = [join9(root, r.worktree)];
+  try {
+    dirs.push(baseClonePath(root, r.id));
+  } catch {
+  }
+  return dirs.find((d) => existsSync(d));
+}
+async function staleReleasePrs(root, id, o = {}) {
+  const out = /* @__PURE__ */ new Set();
+  const cr = await readChangeRepos(root, id).catch(() => void 0);
+  const merged = (await readReleaseFile(root, id)).merged ?? [];
+  if (!cr || !merged.length)
+    return out;
+  const git = o.git ?? createGit({ timeoutMs: 3e4 });
+  const remote = o.remote ?? "origin";
+  for (const r of cr.repos) {
+    if (r.pr?.state !== "merged")
+      continue;
+    const entry = merged.find((x) => x.repo === r.id && x.number === r.pr.number);
+    if (!entry)
+      continue;
+    const dir = repoDir(root, r);
+    if (!dir)
+      continue;
+    if (await movedPast(git, dir, remote, r.branch, entry.commit))
+      out.add(r.id);
+  }
+  return out;
+}
+async function movedPast(git, dir, remote, branch, commit) {
+  const ref = `refs/heads/${branch}`;
+  const known = (sha) => git(["cat-file", "-e", `${sha}^{commit}`], dir).then(() => true, () => false);
+  const here = await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
+  const onHost = await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+  if (onHost && !sameSha(onHost, commit) && !await known(onHost))
+    await git(["fetch", "-q", remote, `+${ref}:refs/remotes/${remote}/${branch}`], dir).catch(() => void 0);
+  const ahead = async (sha) => {
+    if (!sha || sameSha(sha, commit))
+      return false;
+    if (!await known(sha) || !await known(commit))
+      return true;
+    return git(["merge-base", "--is-ancestor", sha, commit], dir).then(() => false, () => true);
+  };
+  return await ahead(here) || await ahead(onHost);
+}
 async function nothingToRelease(root, id, o = {}) {
   const entries = await readNothing(root, id);
   const out = /* @__PURE__ */ new Set();
@@ -1866,12 +1961,7 @@ async function nothingToRelease(root, id, o = {}) {
   }
   return out;
   async function moved(r, commit) {
-    const dirs = [join9(root, r.worktree)];
-    try {
-      dirs.push(baseClonePath(root, r.id));
-    } catch {
-    }
-    const dir = dirs.find((d) => existsSync(d));
+    const dir = repoDir(root, r);
     if (!dir)
       return false;
     const ref = `refs/heads/${r.branch}`;
@@ -1912,12 +2002,15 @@ async function raiseReleasePrs(root, id, o) {
   const rows = [];
   let changed2 = false;
   const repos = cr.repos.map((r) => ({ ...r }));
-  const before = await readNothing(root, id);
+  const file = await readReleaseFile(root, id);
+  const before = file.nothingToRelease;
   const nothing = new Map(before.map((x) => [x.repo, x]));
+  const stale = await staleReleasePrs(root, id, { git, remote });
   for (const r of repos) {
-    if (!live(r.pr))
+    const movedOn = r.pr?.state === "merged" && stale.has(r.id) ? `Release PR #${r.pr.number} merged before ${r.branch} moved on; this one carries what landed since.` : void 0;
+    if (!live(r.pr) || movedOn)
       nothing.delete(r.id);
-    if (live(r.pr)) {
+    if (live(r.pr) && !movedOn) {
       rows.push({
         repo: r.id,
         outcome: "kept",
@@ -1964,7 +2057,7 @@ async function raiseReleasePrs(root, id, o) {
       });
       continue;
     }
-    const notes = [];
+    const notes = movedOn ? [movedOn] : [];
     const dir = join9(root, r.worktree);
     if (existsSync(dir)) {
       const onHost = await git(["ls-remote", "--heads", remote, `refs/heads/${r.branch}`], dir).then((x) => x.stdout.trim() ? "yes" : "no").catch((e) => {
@@ -2048,8 +2141,10 @@ async function raiseReleasePrs(root, id, o) {
   if (changed2)
     await writeChangeRepos(root, { ...cr, repos });
   const after = [...nothing.values()].sort((a, b) => a.repo < b.repo ? -1 : 1);
-  if (JSON.stringify(after) !== JSON.stringify(before))
-    await writeFile(join9(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({ schemaVersion: 1, nothingToRelease: after })), "utf8");
+  const mergedBefore = file.merged ?? [];
+  const mergedAfter = mergedBefore.filter((x) => repos.some((r) => r.id === x.repo && r.pr?.number === x.number && r.pr.state === "merged"));
+  if (JSON.stringify(after) !== JSON.stringify(before) || mergedAfter.length !== mergedBefore.length)
+    await writeReleaseFile(root, id, after, mergedAfter);
   return { change: id, rows };
 }
 async function syncReleasePrs(root, id, o) {
@@ -2060,6 +2155,9 @@ async function syncReleasePrs(root, id, o) {
   const now = o.now ?? nowIso();
   let changed2 = false;
   const repos = cr.repos.map((r) => ({ ...r }));
+  const file = await readReleaseFile(root, id);
+  const merged = [...file.merged ?? []];
+  let mergedChanged = false;
   for (const r of repos) {
     if (!r.pr)
       continue;
@@ -2100,6 +2198,16 @@ async function syncReleasePrs(root, id, o) {
       r.build = { ...r.build, status: build, at: now };
       changed2 = true;
     }
+    if (pr.state === "merged" && !merged.some((x) => x.repo === r.id && x.number === pr.number)) {
+      const commit = await branchTip(root, r, o.git, o.remote ?? "origin");
+      if (commit) {
+        for (let i = merged.length - 1; i >= 0; i--)
+          if (merged[i].repo === r.id)
+            merged.splice(i, 1);
+        merged.push({ repo: r.id, number: pr.number, commit, at: now });
+        mergedChanged = true;
+      }
+    }
     rows.push({
       repo: r.id,
       outcome: "kept",
@@ -2109,8 +2217,25 @@ async function syncReleasePrs(root, id, o) {
   }
   if (changed2)
     await writeChangeRepos(root, { ...cr, repos });
+  if (mergedChanged)
+    await writeReleaseFile(root, id, file.nothingToRelease, merged);
   return { change: id, rows };
 }
+async function branchTip(root, r, g, remote) {
+  const dir = repoDir(root, r);
+  if (!dir)
+    return void 0;
+  const git = g ?? createGit({ timeoutMs: 3e4 });
+  const ref = `refs/heads/${r.branch}`;
+  const onHost = await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+  if (onHost) {
+    await git(["fetch", "-q", remote, `+${ref}:refs/remotes/${remote}/${r.branch}`], dir).catch(() => void 0);
+    if (/^[0-9a-f]{7,64}$/.test(onHost))
+      return onHost;
+  }
+  const here = await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim(), () => "");
+  return /^[0-9a-f]{7,64}$/.test(here) ? here : void 0;
+}
 function buildOf(pr) {
   if (!pr.checks.length)
     return void 0;
@@ -2137,10 +2262,18 @@ async function releasePrReasons(root, id, o = {}) {
     return [];
   const merged = await requireMergedPrs(root);
   const nothing = await nothingToRelease(root, id, o);
+  const stale = await staleReleasePrs(root, id, o);
   const out = [];
   for (const r of cr.repos) {
     if (!r.pr && nothing.has(r.id))
       continue;
+    if (r.pr?.state === "merged" && stale.has(r.id)) {
+      out.push({
+        code: "release-pr-stale",
+        message: `${r.id}: ${r.branch} has commits since release PR #${r.pr.number} merged, so they haven't reached its default branch: raise the release PRs again (Release \u203A Raise the release PRs, or atticus change release-prs ${id} --approve).`
+      });
+      continue;
+    }
     if (!r.pr || r.pr.state === "closed")
       out.push({
         code: "release-pr-missing",
@@ -2394,12 +2527,13 @@ function gitHandoffPublisher(opts = {}) {
       const gitDir = await out(["rev-parse", "--absolute-git-dir"]);
       await tryOut(["fetch", "--quiet", remote, base]);
       await tryOut(["fetch", "--quiet", remote, branch]);
-      const start = await tryOut([
+      const onRemote = await tryOut([
         "rev-parse",
         "--verify",
         "--quiet",
         `refs/remotes/${remote}/${branch}^{commit}`
-      ]) ?? await tryOut([
+      ]);
+      const start = onRemote ?? await tryOut([
         "rev-parse",
         "--verify",
         "--quiet",
@@ -2414,9 +2548,9 @@ function gitHandoffPublisher(opts = {}) {
         const tree = (await staged(["write-tree"], root)).stdout.trim();
         const startTree = await out(["rev-parse", `${start}^{tree}`]);
         const commit = tree === startTree ? start : await out(["commit-tree", tree, "-p", start, "-m", message]);
-        await out(["update-ref", `refs/heads/${branch}`, commit]);
         await out(["push", "--quiet", remote, `${commit}:refs/heads/${branch}`]);
-        return { commit };
+        await keepLocalBranch(out, tryOut, branch, start, commit);
+        return { commit, changed: commit !== onRemote };
       } finally {
         await rm(index, { force: true });
       }
@@ -2424,6 +2558,23 @@ function gitHandoffPublisher(opts = {}) {
   }
 }
 var queue = /* @__PURE__ */ new Map();
+async function keepLocalBranch(out, tryOut, branch, start, commit) {
+  const ref = `refs/heads/${branch}`;
+  const local = await tryOut(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  if (local === commit)
+    return;
+  const list = await tryOut(["worktree", "list", "--porcelain"]) ?? "";
+  if (list.split(/\r?\n/).includes(`branch ${ref}`))
+    return;
+  if (!local) {
+    await tryOut(["update-ref", ref, commit, ""]);
+    return;
+  }
+  const own = await tryOut(["rev-list", "--count", `${start}..${local}`]);
+  if (own === void 0 || own !== "0")
+    return;
+  await out(["update-ref", ref, commit, local]).catch(() => void 0);
+}
 
 // packages/changes/dist/handoff.js
 import { readdir as readdir6, readFile as readFile12 } from "node:fs/promises";
@@ -2985,7 +3136,7 @@ async function handoff(root, id, opts) {
   if (live2 && live2.phase === phase) {
     const pr2 = await handoffPr(opts.gitHost, repo, id, live2);
     if (pr2.state === "open" || pr2.state === "draft") {
-      await opts.publisher?.publish({
+      const published = await opts.publisher?.publish({
         root,
         branch,
         base: pr2.base,
@@ -2993,7 +3144,9 @@ async function handoff(root, id, opts) {
         message: `${handoffName(a.type, phase)}: update`,
         approval: opts.approval
       });
-      await opts.gitHost.comment(repo, pr2.number, `${by} updated the hand-off for another review.`, opts.approval);
+      const unchanged = published ? published.changed === false : sameArtifacts(hashed, live2.artifacts);
+      if (!unchanged)
+        await opts.gitHost.comment(repo, pr2.number, `${by} updated the hand-off for another review.`, opts.approval);
       const updated = {
         ...live2,
         state: "open",
@@ -3014,6 +3167,13 @@ async function handoff(root, id, opts) {
     live2.state = "closed";
     live2.updatedAt = now;
   }
+  if (change.state === "returned") {
+    const open = (await opts.gitHost.listPullRequests(repo, { head: branch })).find((p) => p.state === "open" || p.state === "draft");
+    if (open) {
+      const message = `PR #${open.number} from ${branch} is still open on the Git host (${open.url}): close it there first (the return asked for that), then resubmit the change.`;
+      throw new ChangeError("refused", message, [{ code: "host-refused", message }]);
+    }
+  }
   const base = opts.base ?? (await opts.gitHost.getRepo(repo)).defaultBranch;
   const next = a.next;
   await opts.publisher?.publish({
@@ -3024,13 +3184,23 @@ async function handoff(root, id, opts) {
     message: `${handoffName(a.type, phase)}: ${change.title}`,
     approval: opts.approval
   });
-  const pr = await opts.gitHost.createPullRequest({
-    repo,
-    head: branch,
-    base,
-    title: `${change.title}: ${handoffName(a.type, phase)}`,
-    body: prBody(a, phase, change.state === "returned" ? nextAfterResubmit(a, phase) : next, [...files.map((f) => `${rel}/${id}/${f}`), ...questionFiles], reviewers, opts.review)
-  }, opts.approval);
+  let pr;
+  try {
+    pr = await opts.gitHost.createPullRequest({
+      repo,
+      head: branch,
+      base,
+      title: `${change.title}: ${handoffName(a.type, phase)}`,
+      body: prBody(a, phase, change.state === "returned" ? nextAfterResubmit(a, phase) : next, [...files.map((f) => `${rel}/${id}/${f}`), ...questionFiles], reviewers, opts.review)
+    }, opts.approval);
+  } catch (e) {
+    if (!(e instanceof AdapterError) || e.code !== "conflict")
+      throw e;
+    const open = (await opts.gitHost.listPullRequests(repo, { head: branch }).catch(() => [])).filter((p) => p.base === base && (p.state === "open" || p.state === "draft")).at(0);
+    if (!open)
+      throw e;
+    pr = open;
+  }
   const h = {
     phase,
     branch,
@@ -3057,6 +3227,10 @@ async function handoff(root, id, opts) {
   });
   return h;
 }
+function sameArtifacts(a, b) {
+  const key = (xs) => JSON.stringify([...xs].map((x) => `${x.path} ${x.sha256}`).sort());
+  return key(a) === key(b);
+}
 function nextAfterResubmit(a, phase) {
   const next = a.type.phases[a.type.phases.indexOf(phase) + 1];
   return next ? phaseState(next) : "released";
@@ -3839,7 +4013,7 @@ async function metarepoOrigin(root, git = createGit()) {
     return void 0;
   }
 }
-async function referenceMetarepoIn(root, repoDir, o = {}) {
+async function referenceMetarepoIn(root, repoDir2, o = {}) {
   const { settings } = await loadOpenSpecSettings(orgPackDirOf(root));
   if (!settings.referenceInRepos)
     return { action: "off" };
@@ -3851,7 +4025,7 @@ async function referenceMetarepoIn(root, repoDir, o = {}) {
       file,
       why: marker.missing ? `this metarepo isn't an OpenSpec store yet (no ${STORE_MARKER}): run atticus upgrade --openspec-store, commit the file, then hand down again` : `this metarepo's ${STORE_MARKER} can't be read (${marker.notes.join("; ")})`
     };
-  const path = join17(repoDir, "openspec", "config.yaml");
+  const path = join17(repoDir2, "openspec", "config.yaml");
   const text = await readFile15(path, "utf8").catch(() => void 0);
   if (text === void 0)
     return {
@@ -4106,6 +4280,7 @@ export {
   prApprovers,
   RELEASE_PR_STATES,
   RELEASE_PRS_FILE,
+  staleReleasePrs,
   nothingToRelease,
   raiseReleasePrs,
   syncReleasePrs,

package/dist/{chunk-BXZ4PKIT.js → chunk-IFKEI4SA.js}

@@ -89,6 +89,7 @@ import {
   splitTargetGroups,
   staleFlows,
   staleTargetQuestions,
+  staleTopicQuestions,
   suggestionWhy,
   targetGroupQuestion,
   targetGroupWordings,
@@ -106,22 +107,24 @@ import {
   withExcludes,
   withPluginScan,
   writeCatalog
-} from "./chunk-4SLBCEPD.js";
-import "./chunk-64AADMTW.js";
-import "./chunk-JYMIB5XY.js";
-import "./chunk-CPK7QSBG.js";
-import "./chunk-YO2PKTXT.js";
-import "./chunk-TWQRPM76.js";
-import "./chunk-XOL3GFW2.js";
-import "./chunk-QHJJMZLX.js";
-import "./chunk-7AB6OWTV.js";
+} from "./chunk-J2JAKCIW.js";
+import "./chunk-745DAZ4L.js";
+import "./chunk-CXJ6FUKN.js";
+import "./chunk-QKUJMING.js";
+import "./chunk-6ZGLAACW.js";
+import "./chunk-CQDGOPGH.js";
+import "./chunk-3NFFJL5D.js";
+import "./chunk-PKBHS4AA.js";
+import "./chunk-P32RUW3B.js";
+import "./chunk-QA4O2GGC.js";
 import {
   fieldKey,
   lineNamesField,
   lineNamesRoute,
   lineNamesWord
-} from "./chunk-PAINMSID.js";
-import "./chunk-ODMBPDDV.js";
+} from "./chunk-Q2TECDIT.js";
+import "./chunk-TUULXQRW.js";
+import "./chunk-BQGDB6ZL.js";
 import "./chunk-TV45EUGM.js";
 export {
   CLEAR_MATCH,
@@ -213,6 +216,7 @@ export {
   splitTargetGroups,
   staleFlows,
   staleTargetQuestions,
+  staleTopicQuestions,
   suggestionWhy,
   targetGroupQuestion,
   targetGroupWordings,

package/dist/{chunk-XG4WJHLQ.js → chunk-IGOE6KPG.js}

@@ -6,10 +6,13 @@ var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
 import {
   aliasArgv,
   isLegacy
-} from "./chunk-BXBCMGIQ.js";
+} from "./chunk-24OXGB3P.js";
 import {
   isHandoffStep
 } from "./chunk-4Q3NN7VF.js";
+import {
+  optionsFor
+} from "./chunk-QA4O2GGC.js";
 
 // packages/cli/dist/command-catalog.js
 var AREAS = [
@@ -189,24 +192,45 @@ function parseArgs(id, usage) {
   }
   return out;
 }
-function parseFlags(text, summaries) {
+function requiredFlags(usage) {
+  let masked = "";
+  let depth = 0;
+  let quoted = false;
+  for (const ch of usage) {
+    if (ch === '"')
+      quoted = !quoted;
+    else if (!quoted && (ch === "[" || ch === "<"))
+      depth++;
+    else if (!quoted && (ch === "]" || ch === ">"))
+      depth = Math.max(0, depth - 1);
+    masked += depth || quoted || ch === '"' || ch === "]" || ch === ">" ? "_" : ch;
+  }
+  const tokens = masked.split(/\s+/).filter(Boolean);
+  const flagOf = (t) => /^--[a-z]/.test(t) ? t.split("=")[0] : void 0;
+  const bar = tokens.indexOf("|");
+  if (bar < 0)
+    return new Set(tokens.map(flagOf).filter((f) => !!f));
+  const first = tokens.slice(0, bar).map(flagOf).filter((f) => !!f);
+  return new Set(first.slice(0, -1));
+}
+function parseFlags(text, summaries, required, options) {
   const out = /* @__PURE__ */ new Map();
   const re = /(--[a-z][a-z-]*)(?:[ =]("[^"]*"|<[^>]+>|[A-Za-z0-9][\w.,=-]*(?:\|[\w.-]+)*))?/g;
   for (const m of text.matchAll(re)) {
     const name = m[1];
     if (out.has(name))
       continue;
-    const before = text.slice(0, m.index);
-    const opened = (before.match(/\[/g) ?? []).length - (before.match(/\]/g) ?? []).length;
+    const type = options[name.slice(2)]?.type;
     let value = m[2]?.replace(/^<|>$/g, "");
-    if (value?.startsWith("--") || value && /^[a-z]+$/.test(value) && !m[2].startsWith("<"))
-      value = /^(m|n|t|s|k|f|c|d|o|p|file|dir|id)$/.test(value) ? value : void 0;
+    if (value?.startsWith("--") || type === "boolean")
+      value = void 0;
+    else if (type === "string")
+      value ??= "value";
     const summary = summaries.get(name);
     out.set(name, {
       name,
       ...value ? { value } : {},
-      // `<folder> | --org <org>`: the option is given instead of the argument, not as well.
-      required: opened <= 0 && !/(<[^>]+>|"[^"]*")\s*\|\s*$/.test(before),
+      required: required.has(name),
       ...summary ? { summary } : {}
     });
   }
@@ -235,13 +259,14 @@ function parseHelp(help) {
     const written = cut > 0 ? b.line.slice(cut).trim() : b.below ?? "";
     const summary = written.replace(/(\s*\[[^\]]*--[^\]]*\](\.\.\.)?)+\s*$/, "");
     const tokens = usage.split(" ").slice(1);
-    const words = [];
+    const named = [];
     for (const t of tokens) {
       if (!isWord(t))
         break;
-      words.push(t);
+      named.push(t);
     }
-    const id = words.join(" ");
+    const after = tokens[named.length];
+    const ways = after && /^[a-z][a-z-]*(\|[a-z][a-z-]*)+$/.test(after) ? after.split("|") : [];
     const summaries = /* @__PURE__ */ new Map();
     for (const m of b.more) {
       const c = m.search(/ {2,}/);
@@ -253,21 +278,24 @@ function parseHelp(help) {
     }
     const optionText = [
       `${usage} `,
-      written,
+      written.slice(summary.length),
       // Each option line's option part only: its description may hold brackets of its own.
       ...b.more.map((m) => {
         const c = m.search(/ {2,}/);
         return `[${(c > 0 ? m.slice(0, c) : m).replace(/^\[|\]$/g, "")}]`;
       })
     ].join(" ");
-    out.push({
-      id,
-      words,
-      usage,
-      summary,
-      args: parseArgs(id, usage.slice(`atticus ${id}`.length)),
-      flags: parseFlags(optionText, summaries)
-    });
+    const required = requiredFlags(usage);
+    const approves = APPROVE_FLAGS.filter((f) => new RegExp(`${f}(?![a-z-])`).test(written));
+    const rest = usage.slice(`atticus ${[...named, ...ways.length ? [after] : []].join(" ")}`.length);
+    for (const words of ways.length ? ways.map((w) => [...named, w]) : [named]) {
+      const id = words.join(" ");
+      const flags = parseFlags(optionText, summaries, required, optionsFor(words));
+      for (const name of approves)
+        if (!flags.some((f) => f.name === name))
+          flags.push({ name, required: false });
+      out.push({ id, words, usage, summary, args: parseArgs(id, rest), flags });
+    }
   }
   return out;
 }
@@ -298,6 +326,7 @@ function commandCatalog(help) {
 
 export {
   AREAS,
+  requiredFlags,
   parseHelp,
   commandCatalog
 };