@a2f0/agent-tool 0.1.17 → 0.1.18

package/skills/ship-pr/SKILL.md

@@ -6,8 +6,9 @@ description: Complete an authorized commit, independent review, repair, PR, CI,
 # Ship PR
 
 Use the installed `agent-tool`. Read repository guidance and policy first;
-validation, versioning, package management, and hook installation remain project
-concerns. Shipping authorizes this workflow within the user's stated scope.
+validation, versioning, package management, and hook bodies remain project
+concerns. Use shared branch, hook, check, cleanup, and release commands where
+configured; keep application-specific commands in repository guidance. Shipping authorizes this workflow within the user's stated scope.
 Preserve unrelated edits and honor requested stopping points such as open-PR
 only, report-only review, or keeping the feature branch.
 
@@ -23,13 +24,16 @@ prepare`, `review`, and other commands whose output drives a decision directly.
 Prefer documented compact test reporters when they preserve required evidence;
 do not reduce test scope, skip checks, silence warnings, or mask failures.
 
-1. Finish the requested change on a feature branch. Create it with
-   `git switch --no-track -c <branch>`; settings such as
-   `branch.autosetupmerge=always` otherwise make it track a local branch.
+1. Finish the requested change on a feature branch. Use
+   `agent-tool branch create <branch> --base <base-branch> --remote <remote>`
+   from a clean checkout; it fetches and pins the base, checks naming policy and
+   collisions, and creates without a local upstream. Use `branch check` with
+   explicit destination names in CI or hooks.
    Validate it with appropriate project checks and commit only the intended
    files.
-2. Determine the current PR's base repository and branch, or the repository's
-   default branch when no PR exists. Fetch and pin its exact base. Integrate it
+2. Use `agent-tool repo context --fetch` to resolve the PR's base repository
+   and branch, or the default branch when no PR exists, and fetch its exact base.
+   Record the returned base/head identities. Integrate the fetched base
    using the repository's normal workflow, resolving conflicts without losing
    user work. If project policy versions packages, prepare versions against the
    pinned base after every integration or repair and before each review, using
@@ -39,21 +43,28 @@ do not reduce test scope, skip checks, silence warnings, or mask failures.
    version fields. Review the resulting committed HEAD with an independent
    reviewer using the bundled cross-agent-review skill. Repair blocking findings
    and review every changed HEAD again. Review failure blocks shipping.
-3. Push the reviewed HEAD through normal hooks, then verify the pushed SHA still
-   equals the reviewed SHA. If a hook changed content or HEAD, review that result.
+3. Run `agent-tool branch push <reviewed-head> --remote <remote>` through
+   normal hooks; it verifies local and remote identity afterward. If a hook
+   changed content or HEAD, review that result.
    Open the PR using the open-pr skill, or update the existing PR as needed.
-4. Allow any configured review bots time to respond, then fetch unresolved PR
-   review threads. Follow repository policy for feedback: fix valid findings,
-   reply in the original threads, and resolve only fully addressed comments.
+4. Allow configured review bots time to respond, then use
+   `agent-tool pr threads list` to fetch review threads and all comments. Follow repository policy for feedback: fix valid findings,
+   reply with `pr threads reply <comment-id>` (body file or stdin), and use
+   `pr threads resolve <thread-id>` only for fully addressed findings.
    Validate, commit, push, and independently review every feedback or CI repair.
-   Wait for CI, recheck the live base, PR base branch, and local and remote heads.
+   Wait with `agent-tool pr checks --wait --head <reviewed-head>`, then run
+   `agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>` to
+   recheck CI, live base, PR identity, local state, and explicit version policy.
    A changed base requires integration, validation, and another review. When
    versions are managed, `agent-tool versions check <base-oid>` must pass for the
    live base. Use the squash-merge skill to merge the exact reviewed HEAD.
 5. After confirmed MERGED, honor keep-branch; otherwise use the reset skill to
    return to the updated default branch and apply any documented project setup.
-6. When the project deploys the merged branch, verify the deployment for the
-   merge commit and run its documented live checks. Report deployment failures
+6. When the project publishes npm packages, use `agent-tool release verify
+   <package> <version> <merge-oid> --workflow <publish-workflow>` to verify the
+   exact workflow and tarball, allowing registry propagation time. When the
+   project deploys the merged branch, verify that deployment and documented
+   live checks. Report deployment failures
    separately from a successful merge; follow project policy for repairs.
 
 Never infer a clean review from process success alone or carry a review across

package/skills/squash-merge/SKILL.md

@@ -12,11 +12,13 @@ findings require repair and a new review before merging.
 Follow the repository's review-bot policy and require all actionable blocking
 review feedback to be addressed before merging.
 
-Wait for required checks using `gh pr checks --watch --fail-fast`. Refresh the
-PR and live base from the repository that owns the PR. Confirm local HEAD and PR
-HEAD both equal the reviewed commit, the base branch is unchanged, the live base
-still equals the reviewed base, and that base is an ancestor of reviewed HEAD.
-If any identity changed, refresh, validate, and review again.
+Wait with `agent-tool pr checks --wait --head <reviewed-head>`, which waits for
+checks to appear and for every workflow/job/event entry to finish. Run
+`agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>` immediately
+before merging. It checks local and PR identity, live base, ancestry, explicit
+version policy, merge readiness, configured strict rulesets, and passing checks.
+If an identity changed, refresh, integrate, validate, and review again. Read
+unresolved feedback with `pr threads list` and follow project review policy.
 
 Use a title that satisfies `agent-tool.json` and pass both reviewed HEAD and
 base branch:

package/src/cli.ts

@@ -16,16 +16,40 @@ import { squashMerge } from "./pr/squashMerge";
 import metadata from "../package.json";
 import { runCommand } from "./commands/run";
 import { inspectLog } from "./commands/output";
+import { runGroup, listRuns } from "./commands/group";
+import { branchCommand } from "./workflows/branch";
+import { commitsCommand, binariesCommand, gateCommand } from "./workflows/checks";
+import { hooksCommand } from "./workflows/hooks";
+import { repoCommand, policyCommand, toolchainCommand } from "./workflows/repository";
+import { prWorkflowCommand } from "./workflows/pr";
+import { releaseCommand } from "./release/commands";
 
 export const HELP = `agent-tool ${metadata.version}
 
 Usage: agent-tool [--repo <directory>] [--config <file>] <command>
 
   run [--label text] [--max-bytes N] [--tail-lines N] -- <command> [args...]
+  run-group <plan.json>                  Sequential checks with durable source-bound receipts
+  runs list [--head oid] [--branch name] [--since ISO-date]
+  branch check [name...|--pre-push] | status
+  branch create <name> [--base branch] [--remote origin]
+  branch push <reviewed-head> [--remote origin]
+  commits check --range <range> [--exclude ref] [--exclude-remotes remote]
+  commits check --message-file <file>    Commit-msg attribution and subject policy
+  checks binaries [--staged|--all|--range range|--from-upstream]
+  hooks install [--apply] [--adopt] | check
+  repo context [--fetch] | cleanup <PR> <shipped-head> [--apply] [--keep-branch]
+  policy check | toolchain check
+  ci gate <needs.json|-> [--policy policy.json]
+  release plan <package.json> [--github-output] [--allow-private-source]
+  release verify <package> <version> <merge-oid> --workflow name [--timeout seconds]
   logs <file> [--max-bytes N] [--tail-lines N]  Bounded local log tail
   review <claude|codex|opencode> [effort] [--base <local-ref>]
   pr open [title]                       Body from stdin; branch already pushed
   pr merge <subject-or-empty> <head-oid> <base-branch>
+  pr context | checks [--wait] [--head oid] [--timeout seconds]
+  pr preflight <reviewed-head> <base-branch> <reviewed-base>
+  pr threads list | reply <comment-id> [--body-file file] | resolve <thread-id>
   versions <plan|bump|check|prepare> <base-oid>
   versions resolve-conflicts
   dependencies check-terraform-plan <json-file>  Read-only destructive-plan check
@@ -67,6 +91,8 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
   }
   if (command === "--version") { usage(args.length === 0, "Unexpected version arguments."); writeSync(1, `${metadata.version}\n`); return 0; }
   if (command === "run") return runCommand(args);
+  if (command === "ci") { usage(args.shift() === "gate", "Usage: ci gate <needs.json|-> [--policy policy.json]"); return gateCommand(args); }
+  if (command === "release") return releaseCommand(args);
   if (command === "logs") return inspectLog(args);
   if (command === "dependencies") {
     usage(args.length === 2 && args[0] === "check-terraform-plan", "Usage: agent-tool dependencies check-terraform-plan <json-file>");
@@ -124,6 +150,15 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
   const root = gitRoot();
   process.chdir(root);
   loadConfig(root); // Validate policy before running a reviewer or mutating GitHub.
+  if (command === "branch") return branchCommand(args);
+  if (command === "commits") return commitsCommand(args);
+  if (command === "hooks") return hooksCommand(args);
+  if (command === "repo") return repoCommand(args);
+  if (command === "policy") return policyCommand(args);
+  if (command === "toolchain") return toolchainCommand(args);
+  if (command === "run-group") return runGroup(args);
+  if (command === "runs") return listRuns(args);
+  if (command === "checks") { usage(args.shift() === "binaries", "Usage: checks binaries [--staged|--all|--range range|--from-upstream]"); return binariesCommand(args); }
   if (command === "review") {
     const name = args.shift(); usage(!!name, "Usage: agent-tool review <claude|codex|opencode> [effort] [--base ref]");
     let effort: string | undefined, base: string | undefined;
@@ -135,6 +170,7 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
     return review(root, name!, effort, base);
   }
   if (command === "pr") {
+    if (["context", "checks", "preflight", "threads"].includes(args[0]!)) return prWorkflowCommand(args);
     const action = args.shift();
     if (action === "open") { usage(args.length <= 1, "Usage: agent-tool pr open [title]"); return openPr(root, args[0]); }
     usage(action === "merge" && args.length === 3, "Usage: agent-tool pr merge <subject-or-empty> <reviewed-head-oid> <base-branch>");

package/src/commands/group.ts

@@ -0,0 +1,88 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runCommand, type RunReceipt } from "./run";
+import { assert, git, head, oid, option, output } from "../workflows/core";
+import { gitEnvironment } from "../git/environment";
+
+export interface SourceState { headOid: string; treeOid: string; branch: string | null; fingerprint: string }
+export function sourceState(): SourceState {
+  const hash = createHash("sha256");
+  const add = (value: string | Buffer) => { hash.update(String(Buffer.byteLength(value))); hash.update(":" ); hash.update(value); };
+  const rawDiff = (args: string[]) => execFileSync("git", ["diff", "--no-ext-diff", "--no-textconv", "--binary", ...args, "--"], { env: gitEnvironment(), maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  add(rawDiff(["HEAD"])); add(rawDiff(["--cached"]));
+  for (const record of git(["status", "--porcelain=v2", "--ignore-submodules=none", "-z"]).split("\0")) {
+    if (/^[12] /.test(record)) { const submodule = record.split(" ")[2]!; assert(!submodule.startsWith("S") || submodule === "S...", "Dirty submodules cannot be fingerprinted; validate from a clean submodule state."); }
+  }
+  for (const file of git(["ls-files", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean).sort()) {
+    add(file); const stat = lstatSync(file); add(String(stat.mode));
+    if (stat.isSymbolicLink()) add(readlinkSync(file));
+    else { assert(stat.isFile(), `Cannot fingerprint non-file '${file}'.`); add(readFileSync(file)); }
+  }
+  return { headOid: head(), treeOid: git(["rev-parse", "HEAD^{tree}"]), branch: git(["branch", "--show-current"]) || null, fingerprint: hash.digest("hex") };
+}
+
+function reportsDirectory(): string { return path.join(git(["rev-parse", "--path-format=absolute", "--git-common-dir"]), "agent-tool", "runs"); }
+function save(file: string, value: unknown): void {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  renameSync(temporary, file);
+}
+interface Step { label: string; command: string[] }
+export function parseGroup(source: string): { label: string; steps: Step[] } {
+  const plan = JSON.parse(source) as { label: string; steps: Step[] };
+  const label = (value: unknown) => typeof value === "string" && value.length > 0 && value.length <= 120 && !/[\x00-\x1f]/.test(value);
+  assert(plan && typeof plan === "object" && !Array.isArray(plan) && Object.keys(plan).every(key => ["label", "steps"].includes(key)) && label(plan.label) && Array.isArray(plan.steps) && plan.steps.length > 0, "Invalid run-group plan; expected label and nonempty steps.");
+  const labels = new Set<string>();
+  for (const step of plan.steps) {
+    assert(step && Object.keys(step).every(key => ["label", "command"].includes(key)) && label(step.label) && !labels.has(step.label) && Array.isArray(step.command) && step.command.length > 0 && step.command.every(arg => typeof arg === "string" && !arg.includes("\0")) && step.command[0], "Each step needs a unique label and nonempty command argv.");
+    labels.add(step.label);
+  }
+  return plan;
+}
+export async function runGroup(args: string[]): Promise<number> {
+  assert(args.length === 1, "Usage: run-group <plan.json>");
+  const plan = parseGroup(readFileSync(args[0]!, "utf8"));
+  const before = sourceState();
+  const directory = reportsDirectory(); mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const id = `${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
+  const report = path.join(directory, `${id}.json`);
+  const started = performance.now();
+  const record = { schemaVersion: 1, id, label: plan.label, startedAt: new Date().toISOString(), endedAt: null as string | null, durationMs: 0, status: "running", before, after: null as SourceState | null, steps: plan.steps.map(step => ({ label: step.label, status: "pending", receipt: null as RunReceipt | null })), error: null as string | null };
+  save(report, record);
+  let code = 0;
+  try {
+    for (const [index, step] of plan.steps.entries()) {
+      record.steps[index]!.status = "running"; save(report, record);
+      code = await runCommand(["--label", step.label, "--", ...step.command], receipt => { record.steps[index]!.receipt = receipt; record.steps[index]!.status = receipt.status; save(report, record); }, { quiet: true, reraiseChildSignal: false });
+      const after = sourceState();
+      assert(JSON.stringify(after) === JSON.stringify(before), "Source state changed during validation; results do not establish the current checkout.");
+      if (code !== 0) break;
+    }
+  } catch (error) { code = 1; record.error = (error as Error).message; }
+  record.status = code === 0 ? "passed" : "failed";
+  record.endedAt = new Date().toISOString(); record.durationMs = Math.round(performance.now() - started);
+  try { record.after = sourceState(); } catch (error) { code = 1; record.status = "failed"; record.error ??= (error as Error).message; }
+  save(report, record);
+  output({ ...record, report }); return code;
+}
+
+export function listRuns(args: string[]): number {
+  assert(args.shift() === "list", "Usage: runs list [--head <oid>] [--branch <name>] [--since <ISO-date>]");
+  const expectedHead = option(args, "--head"); const branch = option(args, "--branch"); const since = option(args, "--since");
+  assert(!args.length && (!since || Number.isFinite(Date.parse(since))), "Invalid run history filter.");
+  if (expectedHead) oid(expectedHead);
+  const directory = reportsDirectory();
+  const skipped: { file: string; reason: string }[] = [];
+  const runs = (existsSync(directory) ? readdirSync(directory) : []).filter(file => file.endsWith(".json")).flatMap(file => {
+    try {
+      const full = path.join(directory, file); const stat = lstatSync(full);
+      assert(stat.isFile() && stat.size <= 1024 * 1024, "Invalid validation receipt file.");
+      const run = JSON.parse(readFileSync(full, "utf8")) as { startedAt: string; before: SourceState };
+      assert(typeof run.startedAt === "string" && Number.isFinite(Date.parse(run.startedAt)) && typeof run.before?.headOid === "string" && (run.before.branch === null || typeof run.before.branch === "string"), "Invalid validation receipt shape.");
+      return [run];
+    } catch (error) { skipped.push({ file, reason: (error as Error).message }); return []; }
+  }).filter(run => (!expectedHead || run.before.headOid === expectedHead) && (!branch || run.before.branch === branch) && (!since || Date.parse(run.startedAt) >= Date.parse(since))).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+  output({ runs, skipped }); return 0;
+}

package/src/commands/run.ts

@@ -6,8 +6,10 @@ import { createLog } from "./logFile";
 
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
 
+export interface RunReceipt { status: string; label?: string; exitCode: number; signal: string | null; durationMs: number; outputBytes: number; log: string }
+
 /** Run directly into a private file: child output never accumulates in memory. */
-export async function runCommand(args: string[]): Promise<number> {
+export async function runCommand(args: string[], record?: (receipt: RunReceipt) => void, options: { quiet?: boolean; reraiseChildSignal?: boolean } = {}): Promise<number> {
   const limits = { ...DEFAULT_LIMITS };
   let label: string | undefined;
   while (args[0] !== "--" && args.length) {
@@ -77,7 +79,9 @@ export async function runCommand(args: string[]): Promise<number> {
       forward("SIGKILL");
     }
     const exitCode = signal ? 128 + (constants.signals[signal] ?? 0) : status ?? 1;
-    writeSync(1, `${JSON.stringify({ status: exitCode === 0 ? "passed" : "failed", ...(label ? { label } : {}), exitCode, signal, durationMs: Math.round(performance.now() - started), outputBytes: fstatSync(fd).size, log })}\n`);
+    const receipt: RunReceipt = { status: exitCode === 0 ? "passed" : "failed", ...(label ? { label } : {}), exitCode, signal, durationMs: Math.round(performance.now() - started), outputBytes: fstatSync(fd).size, log };
+    record?.(receipt);
+    if (!options.quiet) writeSync(1, `${JSON.stringify(receipt)}\n`);
     if (exitCode !== 0) printLogTail(log, limits, 2);
   } finally {
     if (timer) clearTimeout(timer);
@@ -86,7 +90,12 @@ export async function runCommand(args: string[]): Promise<number> {
   }
   // Preserve signal termination for calling shells/supervisors, after the receipt.
   if (signal) {
-    process.kill(process.pid, signal);
+    if (interrupted || options.reraiseChildSignal !== false) {
+      process.kill(process.pid, signal);
+      // Let the runtime deliver its signal before main sets process.exitCode
+      // can turn signal termination into an ordinary numeric exit under load.
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
     return 128 + (constants.signals[signal] ?? 0);
   }
   return status ?? 1;

package/src/config.ts

@@ -1,15 +1,16 @@
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parseImages, type ImagesConfig } from "./images/config";
+import { WORKFLOW_DEFAULTS, validateWorkflowConfig, type WorkflowConfig } from "./workflows/config";
 
 export interface RequiredCheck {
   name: string;
   workflow?: string;
 }
 
-export interface AgentToolConfig {
+export interface AgentToolConfig extends WorkflowConfig {
   schemaVersion: 1;
-  subject: { conventional: boolean; maxLength: number; types: string[] };
+  subject: { conventional: boolean; maxLength: number; types: string[]; lowercaseInitial: boolean; rejectTerminalPeriod: boolean; ignoreGenerated: boolean };
   merge: { requireChecks: boolean; requiredChecks: RequiredCheck[]; requireStrictBaseFreshness: boolean };
   review: { claudeModel: string | null; codexModel: string | null; opencodeModel: string; opencodeVariants: Record<string, string>; timeoutMs: number };
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
@@ -18,11 +19,15 @@ export interface AgentToolConfig {
 }
 
 export const DEFAULT_CONFIG: AgentToolConfig = {
+  ...WORKFLOW_DEFAULTS,
   schemaVersion: 1,
   subject: {
     conventional: true,
     maxLength: 72,
     types: ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
+    lowercaseInitial: false,
+    rejectTerminalPeriod: false,
+    ignoreGenerated: false,
   },
   merge: { requireChecks: true, requiredChecks: [], requireStrictBaseFreshness: false },
   review: { claudeModel: null, codexModel: null, opencodeModel: "deepseek/deepseek-v4-pro", opencodeVariants: { low: "low", medium: "medium", high: "high", xhigh: "max", max: "max" }, timeoutMs: 600_000 },
@@ -54,15 +59,17 @@ export function parseConfig(source: string): AgentToolConfig {
   keys(input, Object.keys(DEFAULT_CONFIG), "config");
   if (input.schemaVersion !== 1) throw new Error("Unsupported config schemaVersion; expected 1.");
   const result = structuredClone(DEFAULT_CONFIG);
-  for (const section of ["subject", "merge", "review", "versions", "pr"] as const) {
+  for (const section of ["subject", "merge", "review", "versions", "pr", "branch", "commits", "hooks", "binaries"] as const) {
     if (input[section] === undefined) continue;
     const settings = object(input[section], section);
     keys(settings, Object.keys(result[section]), section);
     Object.assign(result[section], settings);
   }
   if (input.images !== undefined) result.images = parseImages(input.images);
+  if (input.branch !== undefined && !Object.hasOwn(input.branch as object, "enforce")) result.branch.enforce = true;
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };
   if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");
+  for (const key of ["lowercaseInitial", "rejectTerminalPeriod", "ignoreGenerated"] as const) if (typeof result.subject[key] !== "boolean") invalid(`subject.${key}`);
   if (!Number.isSafeInteger(result.subject.maxLength) || result.subject.maxLength < 1) invalid("subject.maxLength");
   if (!strings(result.subject.types) || result.subject.types.length === 0 || result.subject.types.some(type => !/^[a-z]+$/.test(type))) invalid("subject.types");
   if (typeof result.merge.requireChecks !== "boolean") invalid("merge.requireChecks");
@@ -89,6 +96,7 @@ export function parseConfig(source: string): AgentToolConfig {
   if (!Array.isArray(result.versions.validate) || result.versions.validate.some(command => !strings(command) || command.length === 0 || !/^[\w.+-]+$/.test(command[0]!))) invalid("versions.validate");
   if (typeof result.versions.commitMessage !== "string" || !result.versions.commitMessage.trim() || /[\r\n]/.test(result.versions.commitMessage)) invalid("versions.commitMessage");
   if (typeof result.pr.rejectClaudeBranding !== "boolean") invalid("pr.rejectClaudeBranding");
+  validateWorkflowConfig(result);
   return result;
 }
 

package/src/pr/squashMerge.ts

@@ -108,7 +108,7 @@ export function parsePullRequestMergeTarget(
   return { baseRefName, headOid, id };
 }
 
-function resolvePullRequestMergeTarget(
+export function resolvePullRequestMergeTarget(
   pr: {
     prNumber: string;
     repo: string;

package/src/pr/validateCommitSubject.ts

@@ -1,12 +1,16 @@
 import { loadConfig } from "../config";
 
 /** Validate a data-only header policy without running branch-controlled code. */
-export function validateCommitSubject(rootDir: string, subject: string): void {
+export function validateCommitSubject(rootDir: string, subject: string, options: { allowGenerated?: boolean } = {}): void {
   const policy = loadConfig(rootDir).subject;
   if (!subject.trim() || /[\r\n]/.test(subject)) throw new Error("Commit subject must be a nonempty single line.");
+  if (options.allowGenerated && policy.ignoreGenerated && /^(?:Merge\b|Revert\b|(?:fixup|squash|amend)! |Initial commit$)/.test(subject)) return;
   if ([...subject].length > policy.maxLength) throw new Error(`Commit subject exceeds ${policy.maxLength} characters.`);
   if (policy.conventional) {
     const match = /^([a-z]+)(?:\([^\r\n()]+\))?!?: \S.*$/.exec(subject);
     if (!match || !policy.types.includes(match[1]!)) throw new Error(`Commit subject must use a conventional type: ${policy.types.join(", ")}.`);
   }
+  const text = subject.replace(/^[a-z]+(?:\([^\r\n()]+\))?!?: /, "");
+  if (policy.lowercaseInitial && /^[A-Z]/.test(text)) throw new Error("Commit subject must start with lowercase text.");
+  if (policy.rejectTerminalPeriod && text.endsWith(".")) throw new Error("Commit subject must not end with a period.");
 }

package/src/release/commands.ts

@@ -0,0 +1,67 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync } from "node:fs";
+import { decidePublish, readRegistryState } from "./npm";
+import { assert, flag, json, oid, option, output, poll, repository, timeoutOptions } from "../workflows/core";
+
+function packageName(name: unknown): asserts name is string { assert(typeof name === "string" && /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name), "Invalid npm package name."); }
+export interface ReleaseRun { databaseId: number; status: string; conclusion: string; headSha: string; url: string }
+export async function verifyTarball(metadata: { name: string; version: string; dist: { tarball: string; integrity: string } }): Promise<{ tarball: string; integrity: string }> {
+  const url = new URL(metadata.dist.tarball);
+  assert(url.protocol === "https:" && url.hostname === "registry.npmjs.org", "Expected an HTTPS npm registry tarball.");
+  const integrity = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(metadata.dist.integrity);
+  assert(integrity, "Package must have SHA-512 tarball integrity.");
+  const response = await fetch(url, { signal: AbortSignal.timeout(60_000), redirect: "error" });
+  assert(response.ok && response.body, "Could not download the published tarball.");
+  const chunks: Uint8Array[] = []; let size = 0;
+  for await (const chunk of response.body) { size += chunk.length; assert(size <= 100 * 1024 * 1024, "Tarball exceeds the 100 MiB verification limit."); chunks.push(chunk); }
+  const archive = Buffer.concat(chunks);
+  assert(createHash("sha512").update(archive).digest("base64") === integrity[1], "Published tarball integrity does not match registry metadata.");
+  // Read one member to stdout: do not extract untrusted archive paths to disk.
+  const manifest = JSON.parse(execFileSync("tar", ["-xzOf", "-", "package/package.json"], { input: archive, encoding: "utf8", maxBuffer: 1024 * 1024, timeout: 30_000 }));
+  assert(manifest.name === metadata.name && manifest.version === metadata.version, "Published tarball manifest does not match the requested package/version.");
+  return { tarball: url.href, integrity: metadata.dist.integrity };
+}
+
+export async function inspectRelease(
+  runs: ReleaseRun[],
+  expected: { name: string; version: string; commit: string },
+  readMetadata = () => fetch(`https://registry.npmjs.org/${encodeURIComponent(expected.name)}/${expected.version}`, { signal: AbortSignal.timeout(30_000) }),
+  checkArtifact = verifyTarball,
+) {
+  const run = runs.filter(run => run.headSha === expected.commit).sort((a, b) => b.databaseId - a.databaseId)[0];
+  if (!run || run.status !== "completed") return { done: false, value: { ok: false, reason: "Publishing workflow has not completed.", run: run ?? null } };
+  assert(run.conclusion === "success", `Publishing workflow failed: ${run.url} (${run.conclusion}).`);
+  const response = await readMetadata();
+  if (response.status === 404) return { done: false, value: { ok: false, reason: "Version has not propagated to npm.", run } };
+  assert(response.ok, `npm registry returned HTTP ${response.status}.`);
+  const metadata = await response.json() as { name: string; version: string; gitHead?: string; dist: { tarball: string; integrity: string } };
+  assert(metadata.name === expected.name && metadata.version === expected.version, "Registry returned a different package version.");
+  assert(!metadata.gitHead || metadata.gitHead === expected.commit, "Registry gitHead differs from the publishing merge commit.");
+  const artifact = await checkArtifact(metadata);
+  return { done: true, value: { ok: true, reason: "Workflow and published tarball verified.", run, ...artifact, gitHead: metadata.gitHead ?? null } };
+}
+
+export async function releaseCommand(args: string[]): Promise<number> {
+  const action = args.shift();
+  if (action === "plan") {
+    const githubOutput = flag(args, "--github-output");
+    const allowPrivateSource = flag(args, "--allow-private-source");
+    assert(args.length === 1, "Usage: release plan <package.json> [--github-output] [--allow-private-source]");
+    const manifest = JSON.parse(readFileSync(args[0]!, "utf8"));
+    packageName(manifest.name);
+    assert(manifest.private !== true || allowPrivateSource, "Private source manifest; use --allow-private-source only when the build creates a publishable manifest.");
+    const decision = decidePublish(manifest.version, readRegistryState(manifest.name));
+    if (githubOutput) { assert(process.env.GITHUB_OUTPUT, "--github-output requires GITHUB_OUTPUT."); appendFileSync(process.env.GITHUB_OUTPUT, `publish=${decision.publish}\n`); }
+    output({ name: manifest.name, version: manifest.version, privateSource: manifest.private === true, ...decision }); return 0;
+  }
+  const workflow = option(args, "--workflow");
+  const options = timeoutOptions(args);
+  assert(action === "verify" && args.length === 3 && workflow, "Usage: release verify <package> <version> <merge-oid> --workflow <name> [--timeout seconds] [--interval seconds]");
+  const [name, version, commit] = args as [string, string, string];
+  packageName(name); oid(commit);
+  assert(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version), "Expected a stable package version.");
+  const repo = repository().nameWithOwner;
+  const result = await poll(() => inspectRelease(json<ReleaseRun[]>(["run", "list", "-R", repo, "--workflow", workflow, "--commit", commit, "--limit", "100", "--json", "databaseId,status,conclusion,headSha,url"]), { name, version, commit }), options);
+  output({ repo, name, version, commit, ...result }); return 0;
+}

package/src/release/npm.ts

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+
+const registry = "https://registry.npmjs.org";
+
+/** Every version npm has for the package, and its latest tag. */
+export interface RegistryState {
+  latest: string;
+  versions: string[];
+}
+
+export interface PublishDecision {
+  publish: boolean;
+  reason: string;
+}
+
+// Plain major.minor.patch, as the version tooling bumps; a prerelease published
+// without a dist-tag would become npm's latest. Bun also accepts "1.0".
+const versionPattern = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+
+/**
+ * CI publishes only a version newer than npm's latest. A merge that keeps the
+ * version, a re-run, and a run that finishes after a newer release succeed
+ * without publishing, so the latest tag never moves backwards.
+ */
+export function decidePublish(version: string, state: RegistryState): PublishDecision {
+  if (!versionPattern.test(version)) throw new Error(`invalid package version: ${JSON.stringify(version)}`);
+  if (state.versions.includes(version)) return { publish: false, reason: `${version} is already on npm` };
+  if (Bun.semver.order(version, state.latest) <= 0) {
+    return { publish: false, reason: `${version} is not newer than npm's latest (${state.latest})` };
+  }
+  return { publish: true, reason: `${version} is newer than npm's latest (${state.latest})` };
+}
+
+/**
+ * Parses `npm view <name> versions dist-tags --json`, which prints versions as
+ * a string rather than an array when only one exists. A package npm does not
+ * have yet fails: npm configures a trusted publisher only for an existing
+ * package, so its first version is published by hand.
+ */
+export function parseRegistryState(json: string): RegistryState {
+  const view = JSON.parse(json);
+  if (view?.error?.code === "E404") {
+    throw new Error("the package is not on npm yet; publish its first version by hand, then add the trusted publisher");
+  }
+  const versions: unknown = view?.versions;
+  const latest: unknown = view?.["dist-tags"]?.latest;
+  const list = typeof versions === "string" ? [versions] : versions;
+  if (typeof latest !== "string" || !Array.isArray(list) || !list.every(version => typeof version === "string")) {
+    throw new Error(`unexpected npm view output: ${json}`);
+  }
+  return { latest, versions: list };
+}
+
+export function readRegistryState(name: string): RegistryState {
+  // A scope registry overrides --registry, so pin the scope as well.
+  const result = spawnSync("npm", [
+    "view", name, "versions", "dist-tags", "--json",
+    "--registry", registry, ...(name.startsWith("@") ? [`--${name.split("/")[0]}:registry=${registry}`] : []),
+  ], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"], timeout: 60_000 });
+  if (result.error) throw result.error;
+  // A failed view, including a missing package, still prints a JSON error.
+  const state = result.stdout.trim() ? parseRegistryState(result.stdout) : null;
+  if (result.status !== 0 || !state) throw new Error(`npm view ${name} exited with ${result.status}`);
+  return state;
+}