vouchington-tooling 0.43.0 → 0.44.0

package/README.md

@@ -138,7 +138,13 @@ one, prints `download failed artifact=<name> exit=<n>`, exits non-zero (a downlo
 reported as 1 so it cannot be mistaken for absence), and writes no `availability` output.
 
 `require-up-to-date` fetches the requested remote branch and fails unless its fetched tip is an
-ancestor of `HEAD`. `gitleaks-directory-scan` builds and scans isolated staged-index and current
+ancestor of `HEAD`. `fresh-base` refreshes `<remote>/<branch>` (default `origin/main`, 8 s fetch timeout, `--skip-fetch`
+to compare the cached ref) and prints a JSON report classifying the worktree as `up-to-date`,
+`ahead`, `behind`, `diverged`, `dirty` (matches the base but has uncommitted changes),
+`fetch-failed` (a failed refresh outranks every other status), or `unknown`. It prints nothing
+outside a Git repository. Unlike `require-up-to-date` it never fails on staleness; callers decide
+what to do with the status.
+`gitleaks-directory-scan` builds and scans isolated staged-index and current
 nonignored-working-tree mirrors with an explicit config; `--directory` selects the repository root.
 `ast-grep-examples` runs native `ast-grep test`, then validates each scoped rule's `files:` and
 `ignores:` examples with project `languageGlobs` replay from its root `--config`.
@@ -292,6 +298,7 @@ import {
 } from 'vouchington-tooling/dependency-license-policy'
 import { checkGhaWorkspacePolicy } from 'vouchington-tooling/gha-workspace-policy'
 import { requireUpToDate } from 'vouchington-tooling/require-up-to-date'
+import { checkFreshBase, classifyFreshBase } from 'vouchington-tooling/fresh-base'
 import { runGitleaksDirectoryScan } from 'vouchington-tooling/gitleaks-directory-scan'
 import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
 import { astGrepPackPaths } from 'vouchington-tooling/ast-grep-pack'
@@ -331,6 +338,30 @@ await processDiffCommand({ executable: 'git', args: ['diff', 'origin/main...HEAD
 // Use changedFileCount only after processDiffCommand resolves.
 ```
 
+`vouchington-tooling/gh-cli` also parses pull request body references.
+`parseClosingIssueReferences` finds GitHub closing keywords (`close`/`closes`/`closed`,
+`fix`/`fixes`/`fixed`, `resolve`/`resolves`/`resolved`) followed by `#N`, `owner/repo#N` or an issue
+URL, deduplicated by key (`#N` or lowercased `owner/repo#N`, see `formatReferenceKey`).
+`parseNonClosingRefs` collects `Ref`, `Refs` and `Part of` keys from text the caller has already
+scoped, such as a "Related issues" section.
+
+`vouchington-tooling/pull-request-diff` counts added and deleted lines in unified-diff text
+(`countDiffLineChanges`, excluding `+++`/`---` headers) and compares them with caller-supplied
+`LargeDiffThresholds` through `exceedsLargeDiffThreshold`. `DEFAULT_LARGE_DIFF_THRESHOLDS`
+(5,000 added, 20,000 deleted) is only an example default.
+
+```ts
+import {
+  countDiffLineChanges,
+  exceedsLargeDiffThreshold,
+} from 'vouchington-tooling/pull-request-diff'
+
+exceedsLargeDiffThreshold(countDiffLineChanges(diffText), {
+  addedLines: 5000,
+  deletedLines: 20_000,
+})
+```
+
 This breaking minor removes `getDiffAgainstBase`; migrate callers to `processDiffCommand` and pass
 the command they need to run.
 
@@ -700,6 +731,19 @@ reexports, and literal dynamic/require loads. Missing or incomplete facts for a
 throw; external specifiers resolve to `null`. The default file inventory limit is 10,000
 files and can be reduced with `maxFiles`.
 
+## Retrospective distill classifier
+
+`vouchington-tooling/retrospective-distill` exports `classifySession(session, entries, cutoffs)`,
+which assigns a session one of `retrospective`, `entry-type-unresolved`, `checkpoint-only`,
+`journal-only`, `zero-entry-child`, or `zero-entry-root` and decides distillation eligibility
+against caller-supplied `retroCutoff` and `sessionCutoff` timestamps. It deduplicates replayed
+source events, quarantines unknown entry types, invalid feedback envelopes, and conflicting source
+events, and never marks an `entry-type-unresolved` session eligible. `readPartitionRecords(path)`
+reads a local agent-blackboard partition JSONL file; `parseDistillClassifyArgs` and
+`runDistillClassify` wrap both behind `<partition.jsonl> --retro-cutoff <iso> --session-cutoff
+<iso>` and print one tab-separated line per session. The code is the source of truth for the
+taxonomy; the retrospective-distill skill is its human-facing description.
+
 ## Static schema-allowlist pairs
 
 `extractStaticStringPairs(source)` from `pg-schema-snapshot` collects the first two string literals

package/dist/cli/commands/fresh-base.d.mts

@@ -0,0 +1,6 @@
+/** Prints the JSON report (nothing outside a Git repository). Exits 0 whenever a report is made. */
+export declare function runFreshBase(options: {
+    remote?: string;
+    branch?: string;
+    skipFetch: boolean;
+}): number;

package/dist/cli/commands/fresh-base.mjs

@@ -0,0 +1,14 @@
+import { checkFreshBase } from "../../fresh-base/index.mjs";
+/** Prints the JSON report (nothing outside a Git repository). Exits 0 whenever a report is made. */
+export function runFreshBase(options) {
+    try {
+        const report = checkFreshBase(options);
+        if (report !== null)
+            process.stdout.write(`${JSON.stringify(report)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -21,6 +21,7 @@ import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs
 import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
 import { runMcpCommand } from "./commands/mcp.mjs";
 import { runWithHostLock } from "./commands/with-host-lock.mjs";
+import { runFreshBase } from "./commands/fresh-base.mjs";
 import { runRequireUpToDate } from "./commands/require-up-to-date.mjs";
 import { runAstGrepExamplesCommand } from "./commands/ast-grep-examples.mjs";
 import { runAstGrepPackCommand } from "./commands/ast-grep-pack.mjs";
@@ -135,6 +136,8 @@ export function runCli(argv = process.argv) {
             return runMcpCommand(parsed.args);
         case 'require-up-to-date':
             return runRequireUpToDate(parsed);
+        case 'fresh-base':
+            return runFreshBase(parsed);
         case 'gitleaks-directory-scan':
             return runScript('bash', packageScriptPath('scripts/gitleaks-directory-scan.sh'), [
                 '--config',

package/dist/cli/parse-fresh-base.d.mts

@@ -0,0 +1,2 @@
+import type { ParsedCli } from './parse.mts';
+export declare function parseFreshBase(args: readonly string[]): ParsedCli;

package/dist/cli/parse-fresh-base.mjs

@@ -0,0 +1,15 @@
+import { parseOptions } from "./parse-direct-options.mjs";
+export function parseFreshBase(args) {
+    const skipFetch = args.includes('--skip-fetch');
+    const rest = args.filter((arg) => arg !== '--skip-fetch');
+    const options = parseOptions(rest, ['remote', 'branch'], 'fresh-base', 'name');
+    if ('kind' in options)
+        return options;
+    const { remote, branch } = options.values;
+    return {
+        kind: 'fresh-base',
+        skipFetch,
+        ...(remote === undefined ? {} : { remote }),
+        ...(branch === undefined ? {} : { branch }),
+    };
+}

package/dist/cli/parse.d.mts

@@ -70,6 +70,11 @@ export type ParsedCli = {
     kind: 'require-up-to-date';
     remote: string;
     branch: string;
+} | {
+    kind: 'fresh-base';
+    remote?: string;
+    branch?: string;
+    skipFetch: boolean;
 } | {
     kind: 'gitleaks-directory-scan';
     config: string;

package/dist/cli/parse.mjs

@@ -1,6 +1,7 @@
 import { parseGhaArtifactsCleanup, } from "./parse-gha-artifacts-cleanup.mjs";
 import { parseGhaRuntimeAudit } from "./parse-gha-runtime-audit.mjs";
 import { parseForwardedCommand } from "./parse-forwarded-commands.mjs";
+import { parseFreshBase } from "./parse-fresh-base.mjs";
 import { commandNames } from "./usage.mjs";
 import { parseAstGrepExamples, parseAstGrepPack, parseGhaWorkspacePolicy, parseGitleaksDirectoryScan, parseHttpOrigin, parseLinkSkill, parseRequireUpToDate, parseRunnerPortPolicy, } from "./parse-options.mjs";
 const SCRIPT_COMMANDS = new Set([
@@ -50,6 +51,8 @@ export function parseCli(argv) {
         return parseLinkSkill(rest);
     if (command === 'require-up-to-date')
         return parseRequireUpToDate(rest);
+    if (command === 'fresh-base')
+        return parseFreshBase(rest);
     if (command === 'gitleaks-directory-scan')
         return parseGitleaksDirectoryScan(rest);
     if (command === 'ast-grep-examples')

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -5,6 +5,7 @@ Commands:
   with-host-lock       Run a command under a host-wide lock
   gha-runtime-audit             Audit successful GitHub Actions job runtimes
   require-up-to-date            Require HEAD to include a fetched remote branch
+  fresh-base                    Classify the worktree against a remote base branch
   gitleaks-directory-scan       Scan a directory with Gitleaks
   ast-grep-examples             Run AST-grep rule examples
   ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON
@@ -74,6 +75,7 @@ gha-runtime-audit
   --push-workflow <name|/regex/>   Repeatable
 
 require-up-to-date --remote <name> --branch <name>
+fresh-base [--remote <name>] [--branch <name>] [--skip-fetch]
 gitleaks-directory-scan --config <path> [--directory <path>]
 ast-grep-examples --rules <directory> --config <path>
 ast-grep-pack

package/dist/fresh-base/classify.d.mts

@@ -0,0 +1,21 @@
+export type FreshBaseFetch = 'fresh' | 'skipped' | 'failed';
+export type FreshBaseTree = 'clean' | 'dirty' | 'unknown';
+export type FreshBaseRelation = 'matches' | 'behind' | 'ahead' | 'diverged' | 'unknown';
+export type FreshBaseStatus = 'up-to-date' | 'ahead' | 'behind' | 'diverged' | 'dirty' | 'fetch-failed' | 'unknown';
+export interface FreshBaseInput {
+    /** Commits on HEAD that the base lacks; null when the comparison was unavailable. */
+    readonly ahead: number | null;
+    /** Commits on the base that HEAD lacks; null when the comparison was unavailable. */
+    readonly behind: number | null;
+    readonly tree: FreshBaseTree;
+    readonly fetch: FreshBaseFetch;
+}
+export interface FreshBaseClassification extends FreshBaseInput {
+    readonly status: FreshBaseStatus;
+    readonly relation: FreshBaseRelation;
+    /** True for every status except `up-to-date`. */
+    readonly needsAttention: boolean;
+}
+export declare function relationOf(ahead: number | null, behind: number | null): FreshBaseRelation;
+/** Pure classification of a worktree against its base from already-gathered facts. */
+export declare function classifyFreshBase(input: FreshBaseInput): FreshBaseClassification;

package/dist/fresh-base/classify.mjs

@@ -0,0 +1,29 @@
+export function relationOf(ahead, behind) {
+    if (ahead === null || behind === null)
+        return 'unknown';
+    if (ahead === 0 && behind === 0)
+        return 'matches';
+    if (ahead === 0)
+        return 'behind';
+    if (behind === 0)
+        return 'ahead';
+    return 'diverged';
+}
+function statusOf(relation, input) {
+    // A failed refresh means a cached "matches" is not evidence of freshness.
+    if (input.fetch === 'failed')
+        return 'fetch-failed';
+    if (relation === 'unknown')
+        return 'unknown';
+    if (relation !== 'matches')
+        return relation;
+    if (input.tree === 'dirty')
+        return 'dirty';
+    return input.tree === 'clean' ? 'up-to-date' : 'unknown';
+}
+/** Pure classification of a worktree against its base from already-gathered facts. */
+export function classifyFreshBase(input) {
+    const relation = relationOf(input.ahead, input.behind);
+    const status = statusOf(relation, input);
+    return { ...input, relation, status, needsAttention: status !== 'up-to-date' };
+}

package/dist/fresh-base/index.d.mts

@@ -0,0 +1,4 @@
+export { classifyFreshBase, relationOf } from './classify.mts';
+export type { FreshBaseClassification, FreshBaseFetch, FreshBaseInput, FreshBaseRelation, FreshBaseStatus, FreshBaseTree, } from './classify.mts';
+export { checkFreshBase } from './run.mts';
+export type { FreshBaseOptions, FreshBaseReport, GitResult, GitRunner } from './run.mts';

package/dist/fresh-base/index.mjs

@@ -0,0 +1,2 @@
+export { classifyFreshBase, relationOf } from "./classify.mjs";
+export { checkFreshBase } from "./run.mjs";

package/dist/fresh-base/run.d.mts

@@ -0,0 +1,25 @@
+import type { FreshBaseClassification } from './classify.mts';
+export interface GitResult {
+    readonly status: number;
+    readonly stdout: string;
+}
+export type GitRunner = (args: readonly string[], cwd?: string, timeoutMs?: number) => GitResult;
+export interface FreshBaseOptions {
+    readonly remote?: string;
+    readonly branch?: string;
+    readonly cwd?: string;
+    /** Skip the refresh and compare against the cached remote-tracking ref. */
+    readonly skipFetch?: boolean;
+    readonly fetchTimeoutMs?: number;
+    readonly git?: GitRunner;
+}
+export interface FreshBaseReport extends FreshBaseClassification {
+    readonly base: string;
+    /** Current branch name, or `detached HEAD`. */
+    readonly branch: string;
+}
+/**
+ * Refreshes the base, then classifies the worktree against it. Returns null outside a Git
+ * repository. Git failures never throw; they surface as `fetch-failed` or `unknown`.
+ */
+export declare function checkFreshBase(options?: FreshBaseOptions): FreshBaseReport | null;

package/dist/fresh-base/run.mjs

@@ -0,0 +1,66 @@
+import { spawnSync } from 'node:child_process';
+import { classifyFreshBase } from "./classify.mjs";
+const DEFAULT_FETCH_TIMEOUT_MS = 8000;
+const defaultGit = (args, cwd, timeoutMs) => {
+    const result = spawnSync('git', [...args], {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    });
+    return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+};
+function validateName(value, option) {
+    if (value === '' || value.startsWith('-')) {
+        throw new Error(`${option} must be a non-option Git name`);
+    }
+}
+function countsOf(git, ref, cwd) {
+    // A shallow history can hide the ancestry that connects HEAD and the base.
+    const shallow = git(['rev-parse', '--is-shallow-repository'], cwd);
+    if (shallow.status !== 0 || shallow.stdout.trim() !== 'false') {
+        return { ahead: null, behind: null };
+    }
+    const counts = git(['rev-list', '--left-right', '--count', `${ref}...HEAD`], cwd);
+    const [behind, ahead] = counts.stdout.trim().split(/\s+/u).map(Number);
+    if (counts.status !== 0 || !Number.isInteger(behind) || !Number.isInteger(ahead)) {
+        return { ahead: null, behind: null };
+    }
+    return { ahead: ahead, behind: behind };
+}
+/**
+ * Refreshes the base, then classifies the worktree against it. Returns null outside a Git
+ * repository. Git failures never throw; they surface as `fetch-failed` or `unknown`.
+ */
+export function checkFreshBase(options = {}) {
+    const remote = options.remote ?? 'origin';
+    const branch = options.branch ?? 'main';
+    validateName(remote, 'remote');
+    validateName(branch, 'branch');
+    const git = options.git ?? defaultGit;
+    const { cwd } = options;
+    if (git(['rev-parse', '--git-dir'], cwd).status !== 0)
+        return null;
+    if (git(['check-ref-format', '--branch', branch], cwd).status !== 0) {
+        throw new Error('branch must be a valid Git branch name');
+    }
+    const ref = `refs/remotes/${remote}/${branch}`;
+    let fetch = 'skipped';
+    if (options.skipFetch !== true) {
+        const timeout = options.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+        const fetched = git(['fetch', remote, `+refs/heads/${branch}:${ref}`, '--quiet'], cwd, timeout);
+        fetch = fetched.status === 0 ? 'fresh' : 'failed';
+    }
+    const current = git(['branch', '--show-current'], cwd).stdout.trim();
+    const status = git(['status', '--porcelain', '--untracked-files=normal'], cwd);
+    let tree = 'unknown';
+    if (status.status === 0)
+        tree = status.stdout.trim() === '' ? 'clean' : 'dirty';
+    const available = git(['rev-parse', '--verify', '--quiet', ref], cwd).status === 0;
+    const counts = available ? countsOf(git, ref, cwd) : { ahead: null, behind: null };
+    return {
+        ...classifyFreshBase({ ...counts, tree, fetch }),
+        base: `${remote}/${branch}`,
+        branch: current === '' ? 'detached HEAD' : current,
+    };
+}

package/dist/gh-cli/closing-refs.d.mts

@@ -0,0 +1,24 @@
+export type ClosingIssueReference = {
+    key: string;
+    number: number;
+    owner: string | undefined;
+    repo: string | undefined;
+};
+/**
+ * GitHub closing keywords (close/closes/closed, fix/fixes/fixed, resolve/resolves/resolved,
+ * optionally followed by a colon) followed by `#N`, `owner/repo#N` or a
+ * `https://github.com/owner/repo/issues/N` URL. Owner and repo are lowercased and references are
+ * deduplicated by key, in first-seen order.
+ *
+ * The body is scanned as raw text: closing keywords inside HTML comments or code spans/fences (for
+ * example a PR template example) are reported too. Callers that must ignore them blank those spans
+ * out before calling, as `parseNonClosingRefs` callers do with their scoped text.
+ */
+export declare function parseClosingIssueReferences(body: string): ClosingIssueReference[];
+export declare function hasClosingIssueReference(body: string): boolean;
+/** `#N` for a same-repository reference, otherwise lowercased `owner/repo#N`. */
+export declare function formatReferenceKey(ref: {
+    number: number;
+    owner?: string | undefined;
+    repo?: string | undefined;
+}): string;

package/dist/gh-cli/closing-refs.mjs

@@ -0,0 +1,37 @@
+const CLOSING_ISSUE_RE = /\b(?:close(?:s|d)?|fix(?:es|ed)?|resolve(?:s|d)?):?[ \t]+(?:(?<repo>[\w.-]+\/[\w.-]+)?#(?<number>\d+)|https?:\/\/github\.com\/(?<urlRepo>[\w.-]+\/[\w.-]+)\/issues\/(?<urlNumber>\d+))\b/gi;
+/**
+ * GitHub closing keywords (close/closes/closed, fix/fixes/fixed, resolve/resolves/resolved,
+ * optionally followed by a colon) followed by `#N`, `owner/repo#N` or a
+ * `https://github.com/owner/repo/issues/N` URL. Owner and repo are lowercased and references are
+ * deduplicated by key, in first-seen order.
+ *
+ * The body is scanned as raw text: closing keywords inside HTML comments or code spans/fences (for
+ * example a PR template example) are reported too. Callers that must ignore them blank those spans
+ * out before calling, as `parseNonClosingRefs` callers do with their scoped text.
+ */
+export function parseClosingIssueReferences(body) {
+    const refs = [];
+    const seen = new Set();
+    for (const match of body.matchAll(CLOSING_ISSUE_RE)) {
+        const number = Number(match.groups?.number ?? match.groups?.urlNumber);
+        if (!Number.isSafeInteger(number) || number < 1)
+            continue;
+        const repoRef = (match.groups?.repo ?? match.groups?.urlRepo)?.toLowerCase();
+        const [owner, repo] = repoRef?.split('/') ?? [undefined, undefined];
+        const key = formatReferenceKey({ number, owner, repo });
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push({ key, number, owner, repo });
+    }
+    return refs;
+}
+export function hasClosingIssueReference(body) {
+    return parseClosingIssueReferences(body).length > 0;
+}
+/** `#N` for a same-repository reference, otherwise lowercased `owner/repo#N`. */
+export function formatReferenceKey(ref) {
+    return ref.owner !== undefined && ref.repo !== undefined
+        ? `${ref.owner.toLowerCase()}/${ref.repo.toLowerCase()}#${ref.number}`
+        : `#${ref.number}`;
+}

package/dist/gh-cli/index.d.mts

@@ -6,3 +6,6 @@ export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from './body-len
 export type { GitHubBodyLengthValidation } from './body-length.mts';
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './pr-create.mts';
 export type { AssertHeadPushedOptions, BuildGhPrCreateArgsOptions, CreatePullRequestExecutors, CreatePullRequestOptions, } from './pr-create.mts';
+export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, } from './closing-refs.mts';
+export type { ClosingIssueReference } from './closing-refs.mts';
+export { parseNonClosingRefs } from './non-closing-refs.mts';

package/dist/gh-cli/index.mjs

@@ -2,3 +2,5 @@ export { createCommandRunner, runGh, runGit } from "./exec.mjs";
 export { DiffCommandError, processDiffCommand } from "./diff.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./body-length.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./pr-create.mjs";
+export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, } from "./closing-refs.mjs";
+export { parseNonClosingRefs } from "./non-closing-refs.mjs";

package/dist/gh-cli/non-closing-refs.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Collects non-closing references (`Ref`, `Refs`, `Part of`, optionally followed by a colon) from
+ * `referenceText`. Returns reference keys (`#N` or lowercased `owner/repo#N`, the format
+ * `formatReferenceKey` produces) rather than bare numbers, so a `Refs owner/other-repo#42` cannot
+ * disposition a same-numbered local `#42`; callers match by key.
+ *
+ * The caller decides which text counts: pass only the section that carries issue dispositions (for
+ * example a "Related issues" section with code, comments and HTML blanked out), so an incidental
+ * `Refs #N` elsewhere does not satisfy an audit.
+ */
+export declare function parseNonClosingRefs(referenceText: string): Set<string>;

package/dist/gh-cli/non-closing-refs.mjs

@@ -0,0 +1,24 @@
+import { formatReferenceKey } from "./closing-refs.mjs";
+const NON_CLOSING_REF_RE = /\b(?:refs?|part\s+of):?[ \t]+(?:(?<ownerRepo>[\w.-]+\/[\w.-]+))?#(?<number>\d+)\b/gi;
+/**
+ * Collects non-closing references (`Ref`, `Refs`, `Part of`, optionally followed by a colon) from
+ * `referenceText`. Returns reference keys (`#N` or lowercased `owner/repo#N`, the format
+ * `formatReferenceKey` produces) rather than bare numbers, so a `Refs owner/other-repo#42` cannot
+ * disposition a same-numbered local `#42`; callers match by key.
+ *
+ * The caller decides which text counts: pass only the section that carries issue dispositions (for
+ * example a "Related issues" section with code, comments and HTML blanked out), so an incidental
+ * `Refs #N` elsewhere does not satisfy an audit.
+ */
+export function parseNonClosingRefs(referenceText) {
+    const keys = new Set();
+    for (const match of referenceText.matchAll(NON_CLOSING_REF_RE)) {
+        const number = Number(match.groups?.number);
+        if (!Number.isSafeInteger(number) || number < 1)
+            continue;
+        const ownerRepo = match.groups?.ownerRepo?.toLowerCase();
+        const [owner, repo] = ownerRepo?.split('/') ?? [undefined, undefined];
+        keys.add(formatReferenceKey({ number, owner, repo }));
+    }
+    return keys;
+}

package/dist/index.d.mts

@@ -19,6 +19,8 @@ export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/i
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';
 export { checkGhaWorkspacePolicy } from './gha-workspace-policy/index.mts';
 export type { GhaWorkspacePolicyOptions } from './gha-workspace-policy/index.mts';
+export { checkFreshBase, classifyFreshBase, relationOf } from './fresh-base/index.mts';
+export type { FreshBaseClassification, FreshBaseFetch, FreshBaseInput, FreshBaseOptions, FreshBaseRelation, FreshBaseReport, FreshBaseStatus, FreshBaseTree, GitResult, GitRunner, } from './fresh-base/index.mts';
 export { requireUpToDate } from './require-up-to-date/index.mts';
 export type { GitExecutor, RequireUpToDateOptions } from './require-up-to-date/index.mts';
 export { gitleaksDirectoryScanArguments, runGitleaksDirectoryScan, } from './gitleaks-directory-scan/index.mts';
@@ -101,3 +103,7 @@ export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from './gh-cli/i
 export type { GitHubBodyLengthValidation } from './gh-cli/index.mts';
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from './gh-cli/index.mts';
 export type { AssertHeadPushedOptions, BuildGhPrCreateArgsOptions, CreatePullRequestExecutors, CreatePullRequestOptions, } from './gh-cli/index.mts';
+export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, parseNonClosingRefs, } from './gh-cli/index.mts';
+export type { ClosingIssueReference } from './gh-cli/index.mts';
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from './pull-request-diff/index.mts';
+export type { DiffLineChanges, LargeDiffThresholds } from './pull-request-diff/index.mts';

package/dist/index.mjs

@@ -10,6 +10,7 @@ export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgC
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from "./sql-scanner/index.mjs";
 export { auditCiJobRuntime, parseWorkflowNameMatch } from "./gha-runtime-audit/index.mjs";
 export { checkGhaWorkspacePolicy } from "./gha-workspace-policy/index.mjs";
+export { checkFreshBase, classifyFreshBase, relationOf } from "./fresh-base/index.mjs";
 export { requireUpToDate } from "./require-up-to-date/index.mjs";
 export { gitleaksDirectoryScanArguments, runGitleaksDirectoryScan, } from "./gitleaks-directory-scan/index.mjs";
 export { astGrepExamplesArguments, compareAstGrepCompanions, runAstGrepExamples, } from "./ast-grep-examples/index.mjs";
@@ -55,3 +56,5 @@ export { createCommandRunner, runGh, runGit } from "./gh-cli/index.mjs";
 export { DiffCommandError, processDiffCommand } from "./gh-cli/index.mjs";
 export { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from "./gh-cli/index.mjs";
 export { assertHeadPushed, buildGhPrCreateArgs, createPullRequest, DetachedHeadError, HeadNotPushedError, HeadOutOfDateError, resolveHeadBranch, } from "./gh-cli/index.mjs";
+export { formatReferenceKey, hasClosingIssueReference, parseClosingIssueReferences, parseNonClosingRefs, } from "./gh-cli/index.mjs";
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from "./pull-request-diff/index.mjs";

package/dist/pull-request-diff/diff-size.d.mts

@@ -0,0 +1,29 @@
+export type DiffLineChanges = {
+    added: number;
+    deleted: number;
+};
+export type LargeDiffThresholds = {
+    /** A diff adding strictly more lines than this is large. */
+    addedLines: number;
+    /** A diff deleting strictly more lines than this is large. */
+    deletedLines: number;
+};
+/**
+ * Example thresholds for a "decide whether to split this PR" gate: additions are the trigger for a
+ * split, while deletion-heavy retirement work stays coherent at a larger limit. Callers pass their
+ * own `LargeDiffThresholds`; these are only a default.
+ */
+export declare const DEFAULT_LARGE_DIFF_THRESHOLDS: Readonly<LargeDiffThresholds>;
+/**
+ * Added + removed lines in a unified diff (`git diff <base>...HEAD` output), excluding the
+ * `+++`/`---` file-header lines so renamed/moved files don't double-count their path lines.
+ *
+ * Known limitation: this matches the literal `+++`/`---` prefix, not "is this actually a file
+ * header." An added line whose content starts with `++`, or a removed line whose content starts
+ * with `--` (a SQL comment, a CLI flag), renders as `+++`/`---` once the diff marker is prepended
+ * and is silently excluded from the count. For a coarse "probably needs a split" heuristic with an
+ * explicit override, that undercount is acceptable; this is not a full hunk parser.
+ */
+export declare function countDiffLineChanges(diffText: string): DiffLineChanges;
+/** True when either count is strictly greater than its threshold. */
+export declare function exceedsLargeDiffThreshold(changes: DiffLineChanges, thresholds?: LargeDiffThresholds): boolean;

package/dist/pull-request-diff/diff-size.mjs

@@ -0,0 +1,35 @@
+/**
+ * Example thresholds for a "decide whether to split this PR" gate: additions are the trigger for a
+ * split, while deletion-heavy retirement work stays coherent at a larger limit. Callers pass their
+ * own `LargeDiffThresholds`; these are only a default.
+ */
+export const DEFAULT_LARGE_DIFF_THRESHOLDS = Object.freeze({
+    addedLines: 5000,
+    deletedLines: 20_000,
+});
+/**
+ * Added + removed lines in a unified diff (`git diff <base>...HEAD` output), excluding the
+ * `+++`/`---` file-header lines so renamed/moved files don't double-count their path lines.
+ *
+ * Known limitation: this matches the literal `+++`/`---` prefix, not "is this actually a file
+ * header." An added line whose content starts with `++`, or a removed line whose content starts
+ * with `--` (a SQL comment, a CLI flag), renders as `+++`/`---` once the diff marker is prepended
+ * and is silently excluded from the count. For a coarse "probably needs a split" heuristic with an
+ * explicit override, that undercount is acceptable; this is not a full hunk parser.
+ */
+export function countDiffLineChanges(diffText) {
+    const changes = { added: 0, deleted: 0 };
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            continue;
+        if (line.startsWith('+'))
+            changes.added++;
+        else if (line.startsWith('-'))
+            changes.deleted++;
+    }
+    return changes;
+}
+/** True when either count is strictly greater than its threshold. */
+export function exceedsLargeDiffThreshold(changes, thresholds = DEFAULT_LARGE_DIFF_THRESHOLDS) {
+    return changes.added > thresholds.addedLines || changes.deleted > thresholds.deletedLines;
+}

package/dist/pull-request-diff/index.d.mts

@@ -0,0 +1,2 @@
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from './diff-size.mts';
+export type { DiffLineChanges, LargeDiffThresholds } from './diff-size.mts';

package/dist/pull-request-diff/index.mjs

@@ -0,0 +1 @@
+export { countDiffLineChanges, DEFAULT_LARGE_DIFF_THRESHOLDS, exceedsLargeDiffThreshold, } from "./diff-size.mjs";

package/dist/retrospective-distill/args.d.mts

@@ -0,0 +1,13 @@
+export type DistillClassifyArgs = {
+    partitionPath: string;
+    retroCutoff: string;
+    sessionCutoff: string;
+};
+/**
+ * Parses `<partition.jsonl> --retro-cutoff <iso> --session-cutoff <iso>`.
+ *
+ * The classifier never computes its own cutoffs: the eligibility rule is evaluated against
+ * whatever `retroCutoff`/`sessionCutoff` the caller passes in, so a classifier run always matches
+ * the caller's own idea of "eligible" for that same run.
+ */
+export declare function parseDistillClassifyArgs(argv: string[]): DistillClassifyArgs;