@massa-ai/codex-plugin 1.55.0 → 1.57.0

package/skills/massa-ai/references/skill-architect/authoring-principles.md

@@ -0,0 +1,37 @@
+# Skill Authoring Principles
+
+Read once, before Phase 1 of `workflows/skill-architect.md`. This file carries
+the principles and the conversational manner; the workflow carries the five
+phases, their exit criteria, and the hard rules.
+
+## Core Philosophy
+
+1. **Understand before building.** Never generate a SKILL.md until you've completed Discovery and Architecture phases. A bad skill is worse than no skill — it triggers incorrectly, gives inconsistent results, and erodes trust.
+
+2. **Progressive disclosure is everything.** The three-level system (frontmatter → SKILL.md body → linked files) exists for a reason: token economy. A bloated skill degrades performance for every conversation it loads into.
+
+3. **Composability over completeness.** Skills coexist with other skills. Never assume yours is the only one loaded. Be a good neighbor.
+
+4. **Specificity beats verbosity.** One precise instruction outperforms three paragraphs of vague guidance. Code beats prose for deterministic checks.
+
+5. **Skills are for agents, not humans.** No README.md inside the skill folder. No onboarding documentation. Write for an LLM that needs clear, actionable instructions.
+
+## Phase Sequence
+
+```
+DISCOVERY → ARCHITECTURE → CRAFT → VALIDATE → DELIVER
+```
+
+Move through phases sequentially. Never skip Discovery. Each phase has
+explicit exit criteria before you advance.
+
+## Conversation Style
+
+- Ask questions one area at a time — don't dump all Discovery questions at once
+- Give concrete suggestions the user can react to ("Would something like X work?")
+- If the user provides a vague request, propose a specific interpretation and ask
+  if it matches their intent
+- If the conversation already contains a workflow (user says "turn this into a
+  skill"), extract what you can from history FIRST, then fill gaps with questions
+- Match the user's technical level — explain terms if they seem non-technical
+- Be direct about tradeoffs: if a design choice has a downside, say so

package/skills/massa-ai/references/verification-ladder.md

@@ -10,6 +10,8 @@ Classify implementation size before editing:
 - Standard: <=10 files or <=500 changed LOC within one ownership area, or shared behavior/public API/test impact that still has clear acceptance criteria and no unresolved architecture decision.
 - Spec-driven: >10 files, >500 changed LOC, multiple ownership areas, unclear acceptance criteria, new dependency, migration, irreversible operation, security/privacy/auth, public compatibility, cross-service contract, or any unresolved architecture/product decision.
 
+Get the file and LOC halves from `bun skills/massa-ai/scripts/size_change.ts` (`--staged` for the index, `--range <a>..<b>` for a range) rather than counting a diff by eye. It reports changed files, changed LOC (added + deleted), and the resulting **size floor**. The qualitative half of each bullet above — acceptance criteria, dependencies, migrations, irreversible operations, security/privacy/auth, public compatibility, cross-service contracts, unresolved decisions — is invisible to a diff, so the script's answer is a lower bound: raise it when any of those applies, never lower it.
+
 Quick tasks can proceed inside the active workflow. Standard tasks need an explicit verification recipe before edits. Spec-driven tasks should route to `workflows/spec-driven.md` or be split into atomic tasks.
 
 ## Shared Reference Trigger Table

package/skills/massa-ai/scripts/check_commit.ts

@@ -33,7 +33,10 @@
 
 import { readFileSync } from "node:fs";
 
-const TYPES = ["feat", "fix", "refactor", "docs", "test", "style", "perf", "build", "ci", "chore"];
+// `revert` is in the list because `workflows/commit.md` §8 names it in the type
+// precedence order the workflow tells the agent to pick from. Without it the
+// script rejected a message the workflow had just instructed the agent to write.
+const TYPES = ["feat", "fix", "refactor", "docs", "test", "style", "perf", "build", "ci", "chore", "revert"];
 
 // massa-ai patch (D1c): an optional leading Jira-style key prefix, e.g.
 // "[SA-142] feat(auth): reject expired tokens" (workflows/commit.md §8). The

package/skills/massa-ai/scripts/ensure_worktree.ts

@@ -0,0 +1,311 @@
+#!/usr/bin/env bun
+/**
+ * ensure_worktree.ts - Stage 0-1 of the Implementation Delivery Protocol.
+ *
+ * `references/implementation-delivery.md` Stage 0 records which capabilities are
+ * present, and Stage 1 fetches the base and creates a worktree on a new branch
+ * before the first repository mutation. This runs both and prints the worktree
+ * path and branch — the isolation evidence Stage 1 requires be recorded the
+ * moment it completes. Bun builtins only, zero dependencies, agent-agnostic.
+ *
+ * This is the HOW, not the WHEN. The Isolation Gate line in each of the 16
+ * implementation workflows is what decides that isolation is due; it is
+ * byte-identical across those files and gated by
+ * `scripts/__tests__/workflow-harness-contract.test.ts`, and nothing here
+ * replaces it.
+ *
+ * The two legal skips are the reference's, quoted verbatim, and the script
+ * refuses to invent a third:
+ *   1. The target is not a git repository.
+ *   2. The user explicitly declined isolation for this task.
+ * Only the first is detectable from the tree, and only that one is emitted
+ * automatically. The second must be passed with --skip-declined, because a
+ * script cannot observe a user declining anything.
+ *
+ * Failure handling mirrors the Stage 1 table: a taken branch name is suffixed
+ * `-2`, `-3`, ...; a taken worktree path is reused ONLY when its branch already
+ * matches, and is otherwise an error rather than a silent reuse.
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/ensure_worktree.ts --branch feat/login-retry
+ *   bun skills/massa-ai/scripts/ensure_worktree.ts --branch fix/x --base main --path ../wt-fix-x
+ *   bun skills/massa-ai/scripts/ensure_worktree.ts --skip-declined
+ *   bun skills/massa-ai/scripts/ensure_worktree.ts --branch feat/x --dry-run
+ *
+ * Exit codes: 0 isolated or legally skipped, 1 isolation failed, 2 usage error.
+ */
+
+import path from "node:path";
+import { realpathSync } from "node:fs";
+
+const USAGE =
+  "usage: ensure_worktree.ts [-h] (--branch BRANCH | --skip-declined) [--base REF] [--path DIR] [--root ROOT] [--dry-run] [--json]";
+const HELP = `${USAGE}
+
+Run Stage 0-1 of references/implementation-delivery.md and print the isolation evidence.
+
+options:
+  -h, --help          show this help message and exit
+  --branch BRANCH     branch to create, e.g. feat/login-retry
+  --base REF          base ref to branch from (default: origin/HEAD, then main)
+  --path DIR          worktree directory (default: ../<repo>-<branch slug> beside the repo)
+  --root ROOT         run git in this directory (default: cwd)
+  --skip-declined     record the "user explicitly declined isolation" skip and exit 0
+  --dry-run           print the commands that would run, change nothing
+  --json              emit a JSON object instead of the text report`;
+
+interface Args {
+  branch: string | null;
+  base: string | null;
+  worktreePath: string | null;
+  root: string;
+  skipDeclined: boolean;
+  dryRun: boolean;
+  json: boolean;
+}
+
+interface Result {
+  isolated: boolean;
+  worktreePath: string | null;
+  branch: string | null;
+  base: string | null;
+  skipReason: string | null;
+  capabilities: { gitRepo: boolean; gh: boolean; ghAuthenticated: boolean };
+  commands: string[];
+}
+
+/** The reference's two legal skip reasons, verbatim. Any third is a protocol violation. */
+const SKIP_NOT_A_REPO = "The target is not a git repository.";
+const SKIP_USER_DECLINED = "The user explicitly declined isolation for this task.";
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\nensure_worktree.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  const args: Args = {
+    branch: null, base: null, worktreePath: null, root: ".",
+    skipDeclined: false, dryRun: false, json: false,
+  };
+  const valued: Record<string, keyof Args> = {
+    "--branch": "branch", "--base": "base", "--path": "worktreePath", "--root": "root",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    }
+    if (a === "--skip-declined") { args.skipDeclined = true; continue; }
+    if (a === "--dry-run") { args.dryRun = true; continue; }
+    if (a === "--json") { args.json = true; continue; }
+    const eq = a.indexOf("=");
+    const flag = eq === -1 ? a : a.slice(0, eq);
+    const key = valued[flag];
+    if (key === undefined) {
+      printUsageError(`unrecognized argument: ${a}`);
+      return null;
+    }
+    let value: string;
+    if (eq !== -1) value = a.slice(eq + 1);
+    else {
+      if (i + 1 >= argv.length) {
+        printUsageError(`argument ${flag}: expected one argument`);
+        return null;
+      }
+      value = argv[++i]!;
+    }
+    (args as Record<string, unknown>)[key] = value;
+  }
+  if (!args.skipDeclined && args.branch === null) {
+    printUsageError("one of --branch or --skip-declined is required");
+    return null;
+  }
+  return args;
+}
+
+interface Run { ok: boolean; stdout: string; stderr: string }
+
+function run(root: string, cmd: string[]): Run {
+  const proc = Bun.spawnSync(cmd, { cwd: root, stdout: "pipe", stderr: "pipe" });
+  const dec = new TextDecoder();
+  return { ok: proc.exitCode === 0, stdout: dec.decode(proc.stdout), stderr: dec.decode(proc.stderr) };
+}
+
+function git(root: string, gitArgs: string[]): Run {
+  return run(root, ["git", ...gitArgs]);
+}
+
+/** See resolve_scope.ts's defaultBase — same rule, same reason not to invent one. */
+function defaultBase(root: string): string | null {
+  const symref = git(root, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
+  if (symref.ok) return symref.stdout.trim().replace(/^refs\/remotes\//, "");
+  for (const candidate of ["origin/main", "origin/master", "main", "master"]) {
+    if (git(root, ["rev-parse", "--verify", "--quiet", candidate]).ok) return candidate;
+  }
+  return null;
+}
+
+/** `feat/login-retry` -> `login-retry`, for the default worktree directory name. */
+function slug(branch: string): string {
+  return branch.replace(/[^A-Za-z0-9._/-]/g, "-").split("/").filter(Boolean).join("-");
+}
+
+/** First free branch name: `name`, then `name-2`, `name-3`, ... per the Stage 1 table. */
+function freeBranch(root: string, wanted: string): string {
+  if (!git(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${wanted}`]).ok) return wanted;
+  for (let n = 2; n < 100; n++) {
+    const candidate = `${wanted}-${n}`;
+    if (!git(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${candidate}`]).ok) return candidate;
+  }
+  return `${wanted}-${Date.now()}`;
+}
+
+/**
+ * Canonical form for comparing two paths that may differ only by a symlink.
+ *
+ * On macOS the system temp dir is `/var/folders/...`, a symlink to
+ * `/private/var/folders/...`, and `git worktree list` reports the resolved
+ * form while an argument-derived path keeps the unresolved one. `path.resolve`
+ * does not resolve symlinks, so comparing with it alone reports "no worktree
+ * here" for a worktree that is very much here.
+ */
+function canonical(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/** The branch an existing worktree at `dir` is on, or null when there is none. */
+function worktreeBranchAt(root: string, dir: string): string | null {
+  const out = git(root, ["worktree", "list", "--porcelain"]);
+  if (!out.ok) return null;
+  const want = canonical(path.resolve(root, dir));
+  let current: string | null = null;
+  for (const line of out.stdout.split("\n")) {
+    if (line.startsWith("worktree ")) current = line.slice("worktree ".length).trim();
+    else if (line.startsWith("branch ") && current !== null && canonical(current) === want) {
+      return line.slice("branch ".length).trim().replace(/^refs\/heads\//, "");
+    }
+  }
+  return null;
+}
+
+function ensure(args: Args): Result {
+  const commands: string[] = [];
+  const isRepo = git(args.root, ["rev-parse", "--is-inside-work-tree"]).ok;
+  // `Bun.which`, never a spawned `command -v`: `command` is a shell builtin that
+  // macOS also ships as /usr/bin/command and Ubuntu does not, so spawning it
+  // succeeds on one CI runner and kills the process with ENOENT on the other.
+  const gh = Bun.which("gh") !== null;
+  const ghAuthenticated = gh && run(args.root, ["gh", "auth", "status"]).ok;
+  const capabilities = { gitRepo: isRepo, gh, ghAuthenticated };
+
+  if (!isRepo) {
+    return { isolated: false, worktreePath: null, branch: null, base: null, skipReason: SKIP_NOT_A_REPO, capabilities, commands };
+  }
+  if (args.skipDeclined) {
+    return { isolated: false, worktreePath: null, branch: null, base: null, skipReason: SKIP_USER_DECLINED, capabilities, commands };
+  }
+
+  const base = args.base ?? defaultBase(args.root);
+  if (base === null) {
+    throw new Error("no base ref could be resolved and none was given. Pass --base; do not invent a base.");
+  }
+  const wanted = args.branch!;
+  const repoName = path.basename(path.resolve(args.root));
+  const dir = args.worktreePath ?? path.join("..", `${repoName}-${slug(wanted)}`);
+
+  // Resolve the existing-worktree question BEFORE bumping the branch name.
+  // Bumping first turns the reuse case into a mismatch against a name the
+  // caller never asked for: the path is on `feat/x`, the bumped request is
+  // `feat/x-2`, and a legal reuse reads as a collision.
+  const existingBranch = worktreeBranchAt(args.root, dir);
+  if (existingBranch !== null && !args.dryRun) {
+    // Stage 1: "Worktree path taken -> reuse it only if its branch matches."
+    if (existingBranch !== wanted) {
+      throw new Error(
+        `worktree path ${dir} already exists on branch '${existingBranch}', not '${wanted}'. Reuse is legal only when the branch matches.`,
+      );
+    }
+    return {
+      isolated: true,
+      worktreePath: path.resolve(args.root, dir),
+      branch: existingBranch,
+      base,
+      skipReason: null,
+      capabilities,
+      commands: [`# reused existing worktree at ${dir} on ${existingBranch}`],
+    };
+  }
+
+  const branch = freeBranch(args.root, wanted);
+
+  // `git fetch origin <base>` only makes sense for a remote-tracking base; a
+  // purely local base has nothing to fetch and the fetch would fail noisily.
+  const remoteBase = base.startsWith("origin/") ? base.slice("origin/".length) : null;
+  if (remoteBase !== null) commands.push(`git fetch origin ${remoteBase}`);
+  commands.push(`git worktree add -b ${branch} ${dir} ${base}`);
+
+  if (args.dryRun) {
+    return { isolated: false, worktreePath: path.resolve(args.root, dir), branch, base, skipReason: null, capabilities, commands };
+  }
+
+  if (remoteBase !== null) {
+    const fetched = git(args.root, ["fetch", "origin", remoteBase]);
+    if (!fetched.ok) throw new Error(`git fetch origin ${remoteBase} failed: ${fetched.stderr.trim()}`);
+  }
+  const added = git(args.root, ["worktree", "add", "-b", branch, dir, base]);
+  if (!added.ok) throw new Error(`git worktree add failed: ${added.stderr.trim()}`);
+
+  return { isolated: true, worktreePath: path.resolve(args.root, dir), branch, base, skipReason: null, capabilities, commands };
+}
+
+function report(r: Result, dryRun: boolean): void {
+  const cap = r.capabilities;
+  console.log(`git repository: ${cap.gitRepo ? "yes" : "no"}`);
+  console.log(`gh:             ${cap.gh ? (cap.ghAuthenticated ? "present, authenticated" : "present, NOT authenticated") : "absent"}`);
+  if (!cap.gh || !cap.ghAuthenticated) {
+    console.log("                -> Stage 4 takes the degraded path in references/implementation-delivery.md");
+  }
+  console.log("");
+  if (r.skipReason !== null) {
+    console.log("isolation SKIPPED, legal reason (record it verbatim in the completion report):");
+    console.log(`  ${r.skipReason}`);
+    return;
+  }
+  for (const c of r.commands) console.log(`  $ ${c}`);
+  console.log("");
+  if (dryRun) {
+    console.log("dry run — nothing was changed.");
+    return;
+  }
+  console.log("isolation evidence — record both in the session status now:");
+  console.log(`  worktree path: ${r.worktreePath}`);
+  console.log(`  branch:        ${r.branch} (from ${r.base})`);
+  console.log("");
+  console.log("A fresh worktree has no node_modules, no dist and no .env. Provision it");
+  console.log("before the first gate; a gate that fails only for that is an environment");
+  console.log("failure, not a code failure.");
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+  let result: Result;
+  try {
+    result = ensure(args);
+  } catch (err) {
+    process.stderr.write(`ensure_worktree: ${(err as Error).message}\n`);
+    return 1;
+  }
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else report(result, args.dryRun);
+  return 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}

package/skills/massa-ai/scripts/resolve_scope.ts

@@ -0,0 +1,263 @@
+#!/usr/bin/env bun
+/**
+ * resolve_scope.ts - deterministic audit scope packet.
+ *
+ * `references/audit-scope.md` requires every audit to produce a compact scope
+ * packet before analysis: scope type, target focus, resolution method, base and
+ * head, resolved files, exclusions, and a freshness timestamp. Assembling that
+ * by hand means running three or four git commands and transcribing their
+ * output, which is where a packet drifts from the tree it claims to describe.
+ * This emits the packet as JSON from the tree itself. Bun builtins only, zero
+ * dependencies, agent-agnostic.
+ *
+ * It resolves FILES, not judgment. It cannot decide whether a target focus is
+ * too vague to audit, and it does not try: `--target` is recorded verbatim, and
+ * the ask-when-vague rule stays with the agent and `references/audit-scope.md`.
+ *
+ * Exclusions are reported, never silently applied twice: the excluded paths are
+ * listed in the packet alongside the resolved files, so a reader can see what
+ * was dropped rather than inferring it from a count that does not add up.
+ *
+ * Usage:
+ *   bun skills/massa-ai/scripts/resolve_scope.ts --scope modified
+ *   bun skills/massa-ai/scripts/resolve_scope.ts --scope range --range abc123..def456
+ *   bun skills/massa-ai/scripts/resolve_scope.ts --scope branch --base main
+ *   bun skills/massa-ai/scripts/resolve_scope.ts --scope files --target 'src/**\/*.ts'
+ *   bun skills/massa-ai/scripts/resolve_scope.ts --scope whole
+ *
+ * Exit codes: 0 resolved, 1 git failure or unresolvable scope, 2 usage error.
+ */
+
+const SCOPES = ["modified", "range", "branch", "files", "whole"] as const;
+type Scope = (typeof SCOPES)[number];
+
+const USAGE =
+  "usage: resolve_scope.ts [-h] --scope {modified,range,branch,files,whole} [--range REV_RANGE] [--base REF] [--head REF] [--target TARGET] [--root ROOT]";
+const HELP = `${USAGE}
+
+Emit the shared audit scope packet from references/audit-scope.md as JSON.
+
+options:
+  -h, --help          show this help message and exit
+  --scope SCOPE       one of: ${SCOPES.join(", ")}
+  --range REV_RANGE   revision range for --scope range, e.g. abc123..def456
+  --base REF          base ref for --scope branch (default: origin/HEAD, then main)
+  --head REF          head ref for --scope branch (default: HEAD)
+  --target TARGET     the target focus, recorded verbatim; a git pathspec for --scope files
+                      (git's '*' crosses '/', so 'src/*.ts' also matches 'src/a/b.ts')
+  --root ROOT         run git in this directory (default: cwd)`;
+
+/**
+ * Paths excluded from every audit scope per references/audit-scope.md
+ * ("generated, dependency, build, log, cache, temporary, and secret paths").
+ * Matched as a path segment so `src/dist-helper.ts` is not caught by `dist`.
+ */
+const EXCLUDED_SEGMENTS = [
+  "node_modules", "vendor", ".venv", "__pycache__", "dist", "build", ".next",
+  "out", "bin", "obj", "target", "Pods", ".gradle", ".expo", ".dart_tool",
+  "logs", ".cache", "tmp", ".git",
+];
+const EXCLUDED_FILE_RE = /(?:\.min\.(?:js|css)|\.lock|\.log|\.pem|\.key|\.pyc|\.map)$/;
+
+interface Args {
+  scope: Scope | null;
+  range: string | null;
+  base: string | null;
+  head: string | null;
+  target: string | null;
+  root: string;
+}
+
+function printUsageError(msg: string): void {
+  process.stderr.write(`${USAGE}\nresolve_scope.ts: error: ${msg}\n`);
+}
+
+function parseArgs(argv: string[]): Args | null {
+  const args: Args = { scope: null, range: null, base: null, head: null, target: null, root: "." };
+  const valued: Record<string, keyof Args> = {
+    "--scope": "scope", "--range": "range", "--base": "base",
+    "--head": "head", "--target": "target", "--root": "root",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    }
+    const eq = a.indexOf("=");
+    const flag = eq === -1 ? a : a.slice(0, eq);
+    const key = valued[flag];
+    if (key === undefined) {
+      printUsageError(`unrecognized argument: ${a}`);
+      return null;
+    }
+    let value: string;
+    if (eq !== -1) {
+      value = a.slice(eq + 1);
+    } else {
+      if (i + 1 >= argv.length) {
+        printUsageError(`argument ${flag}: expected one argument`);
+        return null;
+      }
+      value = argv[++i]!;
+    }
+    (args as Record<string, unknown>)[key] = value;
+  }
+  if (args.scope === null) {
+    printUsageError("argument --scope is required");
+    return null;
+  }
+  if (!(SCOPES as readonly string[]).includes(args.scope)) {
+    printUsageError(`argument --scope: invalid choice '${args.scope}' (choose from ${SCOPES.join(", ")})`);
+    return null;
+  }
+  if (args.scope === "range" && args.range === null) {
+    printUsageError("--scope range requires --range");
+    return null;
+  }
+  if (args.scope === "files" && args.target === null) {
+    printUsageError("--scope files requires --target");
+    return null;
+  }
+  return args;
+}
+
+/** Runs git and returns stdout, or null when git itself failed. */
+function git(root: string, gitArgs: string[], quiet = false): string | null {
+  const proc = Bun.spawnSync(["git", ...gitArgs], { cwd: root, stdout: "pipe", stderr: "pipe" });
+  if (proc.exitCode !== 0) {
+    if (!quiet) process.stderr.write(new TextDecoder().decode(proc.stderr));
+    return null;
+  }
+  return new TextDecoder().decode(proc.stdout);
+}
+
+function lines(out: string | null): string[] {
+  return (out ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
+}
+
+function isExcluded(p: string): boolean {
+  if (EXCLUDED_FILE_RE.test(p)) return true;
+  return p.split("/").some((seg) => EXCLUDED_SEGMENTS.includes(seg));
+}
+
+/**
+ * The base ref for a branch comparison, when the user named none.
+ *
+ * `origin/HEAD` is the repository's own answer and is preferred over guessing
+ * `main`; the fallbacks exist because a clone made with `--single-branch` has no
+ * `origin/HEAD` symref at all. Returning null rather than defaulting silently is
+ * deliberate: audit-scope.md says "Do not invent a base."
+ */
+function defaultBase(root: string): string | null {
+  const symref = git(root, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], true);
+  if (symref) return symref.trim().replace(/^refs\/remotes\//, "");
+  for (const candidate of ["origin/main", "origin/master", "main", "master"]) {
+    if (git(root, ["rev-parse", "--verify", "--quiet", candidate], true)) return candidate;
+  }
+  return null;
+}
+
+interface Packet {
+  scopeType: Scope;
+  targetFocus: string | null;
+  resolutionMethod: string;
+  base: string | null;
+  head: string | null;
+  files: string[];
+  excluded: string[];
+  freshness: string;
+}
+
+function resolve(args: Args): Packet | null {
+  const scope = args.scope!;
+  let method: string;
+  let base: string | null = null;
+  let head: string | null = null;
+  let raw: string[];
+
+  if (scope === "modified") {
+    method = "git status --porcelain --untracked-files=all (staged, unstaged, and untracked)";
+    head = "working-tree";
+    base = "HEAD";
+    // `--porcelain` covers untracked files, which `git diff --name-only` omits;
+    // audit-scope.md counts relevant untracked source as in scope.
+    // --untracked-files=all, not the default `normal`: git collapses an entirely
+    // untracked directory to a single `?? src/` entry, and a scope packet listing
+    // `src/` instead of the files under it under-reports the audit surface.
+    const out = git(args.root, ["status", "--porcelain", "--untracked-files=all"]);
+    if (out === null) return null;
+    // Not lines(): porcelain columns are `XY<space>path`, and X is a space for
+    // an unstaged-only change. Trimming the line first eats that column and
+    // then slice(3) eats the path's first character instead.
+    raw = out.split("\n").filter((l) => l.length > 3).map((l) => {
+      const path = l.slice(3);
+      // A rename is `R  old -> new`; the audit target is the new path.
+      const arrow = path.indexOf(" -> ");
+      return arrow === -1 ? path : path.slice(arrow + 4);
+    });
+  } else if (scope === "range") {
+    method = `git diff --name-only ${args.range}`;
+    const [b, h] = args.range!.split("..");
+    base = b || null;
+    head = h || "HEAD";
+    const out = git(args.root, ["diff", "--name-only", args.range!]);
+    if (out === null) return null;
+    raw = lines(out);
+  } else if (scope === "branch") {
+    base = args.base ?? defaultBase(args.root);
+    if (base === null) {
+      process.stderr.write(
+        "resolve_scope: no base ref could be resolved and none was given. Pass --base; do not invent a base.\n",
+      );
+      return null;
+    }
+    head = args.head ?? "HEAD";
+    method = `git diff --name-only ${base}...${head} (merge-base three-dot)`;
+    const out = git(args.root, ["diff", "--name-only", `${base}...${head}`]);
+    if (out === null) return null;
+    raw = lines(out);
+  } else if (scope === "files") {
+    method = `git ls-files -- ${args.target}`;
+    const out = git(args.root, ["ls-files", "--", args.target!]);
+    if (out === null) return null;
+    raw = lines(out);
+    if (raw.length === 0) {
+      process.stderr.write(
+        `resolve_scope: pathspec '${args.target}' matched no tracked file. Ask for a concrete target.\n`,
+      );
+      return null;
+    }
+  } else {
+    method = "git ls-files (whole repository — explicitly requested scope only)";
+    const out = git(args.root, ["ls-files"]);
+    if (out === null) return null;
+    raw = lines(out);
+  }
+
+  const excluded = raw.filter(isExcluded).sort();
+  const files = raw.filter((p) => !isExcluded(p)).sort();
+  return {
+    scopeType: scope,
+    targetFocus: args.target,
+    resolutionMethod: method,
+    base,
+    head,
+    files,
+    excluded,
+    freshness: new Date().toISOString(),
+  };
+}
+
+function main(argv: string[]): number {
+  const args = parseArgs(argv);
+  if (args === null) return 2;
+  const packet = resolve(args);
+  if (packet === null) return 1;
+  console.log(JSON.stringify(packet, null, 2));
+  return 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}