vouchington-tooling 0.86.0 → 0.87.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +2 -2
- package/dist/mcp-server/dispatch.mjs +2 -0
- package/dist/mcp-server/fake-blackboard.test-helpers.d.mts +4 -0
- package/dist/mcp-server/fake-blackboard.test-helpers.mjs +7 -1
- package/dist/mcp-server/handlers-snapshot-archive.d.mts +8 -0
- package/dist/mcp-server/handlers-snapshot-archive.mjs +67 -0
- package/dist/mcp-server/snapshot-entry-digests.d.mts +12 -0
- package/dist/mcp-server/snapshot-entry-digests.mjs +48 -0
- package/dist/mcp-server/tools.mjs +21 -0
- package/docs/mcp-server.md +26 -2
- package/package.json +2 -2
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/blackboard/SKILL.md +3 -1
- package/skills/bounded-iteration/SKILL.md +7 -5
- package/skills/bounded-iteration/references/sweep-patterns.md +3 -0
- package/skills/glide-mq/SKILL.md +2 -1
- package/skills/manifest.json +29 -29
- package/skills/postgres-node-performance-tuning/SKILL.md +6 -0
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +22 -5
- package/skills/postgres-schema-design/SKILL.md +7 -0
- package/skills/postgres-schema-design/references/table-shapes.md +3 -1
- package/skills/retrospective-distill/SKILL.md +14 -9
- package/skills/triage-loop/SKILL.md +5 -0
- package/skills/triage-sweep/SKILL.md +5 -2
|
@@ -1 +1 @@
|
|
|
1
|
-
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 host-storage Check free space on caller-supplied paths\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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 (KEEP_MIN or --main-history)\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 verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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 [--main-history] [--apply|--dry-run] [<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>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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, snapshot_partition, snapshot_cleanup, 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\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI command in a workflow run block or shell script (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
1
|
+
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 host-storage Check free space on caller-supplied paths\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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 (KEEP_MIN or --main-history)\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 verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n final-review Post, revoke, check, or benchmark multi-pillar final reviews\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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 [--main-history] [--apply|--dry-run] [<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>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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, snapshot_export, snapshot_partition,\n snapshot_archive, snapshot_cleanup, 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\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\nfinal-review post --repo owner/name --pr N --head-sha SHA --input findings.json [--dry-run]\nfinal-review diff --repo owner/name --pr N\nfinal-review revoke --repo owner/name --pr N\nfinal-review status --repo owner/name --pr N\nfinal-review bench --cases cases.json --prompts DIR --out DIR [--pillar NAME]... [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL]\nfinal-review bench-verifier --cases cases.json --findings-from DIR --prompts DIR --out DIR [--case ID]... [--model NAME] [--jobs N] [--max-turns N] [--score-only] [--judge MODEL] [--checker MODEL]\n post renders verified findings as one or more COMMENT reviews (verdict, reviewed SHA and effort in\n the header; inline comments where the diff allows, the rest in the body) and adds the \"final\n approval\" label on Approve or removes it otherwise. It refuses when the head moved. diff prints the pull request\n diff with base and head line numbers on every line, for reviewers to cite. revoke removes\n the label before a re-review. status exits 0 only when the newest final review approved the current\n head and the label is present. bench runs each pillar prompt against labeled cases from a git-free\n snapshot of the pre-merge head and scores recall and precision; --judge grades by claim\n with a model instead of by location. bench-verifier runs only the verifier, one call per case\n and no subagents, on the pillar findings a bench --out DIR saved (each judged-real finding is\n also planted under a second pillar), and scores real findings kept, label recall, severity\n agreement, duplicates merged, and other blocking and high findings confirmed by --checker;\n --prompts is the skill's references directory.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI command in a workflow run block or shell script (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
package/dist/cli/usage-text.mjs
CHANGED
|
@@ -146,8 +146,8 @@ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH
|
|
|
146
146
|
mcp
|
|
147
147
|
(no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,
|
|
148
148
|
session_ensure, retrospective_check, retrospective_save,
|
|
149
|
-
pr_validate, pr_create, pr_update,
|
|
150
|
-
|
|
149
|
+
pr_validate, pr_create, pr_update, snapshot_export, snapshot_partition,
|
|
150
|
+
snapshot_archive, snapshot_cleanup, and session_archive over stdio.
|
|
151
151
|
Needs the optional @modelcontextprotocol/sdk peer (and zod).
|
|
152
152
|
Launch it from inside the repository's git worktree.
|
|
153
153
|
|
|
@@ -5,6 +5,7 @@ import { journalAppend, journalEntries } from "./handlers-journal.mjs";
|
|
|
5
5
|
import { retrospectiveSave } from "./handlers-retrospective.mjs";
|
|
6
6
|
import { retrospectiveCheck } from "./retrospective-check.mjs";
|
|
7
7
|
import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
|
|
8
|
+
import { snapshotArchive } from "./handlers-snapshot-archive.mjs";
|
|
8
9
|
import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
|
|
9
10
|
import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
|
|
10
11
|
import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
|
|
@@ -28,6 +29,7 @@ const HANDLERS = {
|
|
|
28
29
|
pr_update: handlePrUpdate,
|
|
29
30
|
snapshot_export: snapshotExport,
|
|
30
31
|
snapshot_partition: snapshotPartition,
|
|
32
|
+
snapshot_archive: snapshotArchive,
|
|
31
33
|
snapshot_cleanup: snapshotCleanup,
|
|
32
34
|
session_archive: sessionArchive,
|
|
33
35
|
};
|
|
@@ -26,6 +26,10 @@ export type FakeOptions = {
|
|
|
26
26
|
};
|
|
27
27
|
entries?: StoredEntry[];
|
|
28
28
|
entriesError?: unknown;
|
|
29
|
+
/** Fails the read of just these sessions, keyed by session id. */
|
|
30
|
+
entriesErrors?: Record<string, unknown>;
|
|
31
|
+
/** Fails the archive of just these sessions, keyed by session id. */
|
|
32
|
+
archiveErrors?: Record<string, unknown>;
|
|
29
33
|
/** An entry another caller writes just before the next append, after that append's read. */
|
|
30
34
|
lateEntry?: StoredEntry;
|
|
31
35
|
};
|
|
@@ -45,6 +45,8 @@ export function fakeBlackboard(options = {}) {
|
|
|
45
45
|
return options.conflictingSession;
|
|
46
46
|
}
|
|
47
47
|
async archive(sessionId) {
|
|
48
|
+
if (options.archiveErrors && sessionId in options.archiveErrors)
|
|
49
|
+
throw options.archiveErrors[sessionId];
|
|
48
50
|
calls.archive.push(sessionId);
|
|
49
51
|
}
|
|
50
52
|
}
|
|
@@ -68,7 +70,11 @@ export function fakeBlackboard(options = {}) {
|
|
|
68
70
|
calls.get.push(input);
|
|
69
71
|
if (options.entriesError !== undefined)
|
|
70
72
|
throw options.entriesError;
|
|
71
|
-
|
|
73
|
+
const id = input.sessionId;
|
|
74
|
+
if (options.entriesErrors && id in options.entriesErrors)
|
|
75
|
+
throw options.entriesErrors[id];
|
|
76
|
+
// An entry with no sessionId belongs to whichever session is read, as before.
|
|
77
|
+
yield* stored.filter((entry) => entry.sessionId === undefined || entry.sessionId === id);
|
|
72
78
|
}
|
|
73
79
|
}
|
|
74
80
|
class Snapshots {
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { ToolHandler } from './context.mts';
|
|
2
|
+
/**
|
|
3
|
+
* Archives each listed session whose live entries still match the ones `snapshot_export` recorded.
|
|
4
|
+
* The server reads the snapshot and the live journal itself, so no entry content reaches the
|
|
5
|
+
* caller: the result names only the sessions archived and a reason for each one skipped. The
|
|
6
|
+
* token is only read, never spent, so `snapshot_cleanup` can still use it.
|
|
7
|
+
*/
|
|
8
|
+
export declare const snapshotArchive: ToolHandler;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { archiveBlackboardSession } from "../agent-blackboard/index.mjs";
|
|
2
|
+
import { assertSessionId } from "../agent-blackboard/session-id.mjs";
|
|
3
|
+
import { requiredString, requiredStringArray } from "./args.mjs";
|
|
4
|
+
import { readEntriesIfPresent } from "./journal-read.mjs";
|
|
5
|
+
import { entryDigest, readExportedDigests } from "./snapshot-entry-digests.mjs";
|
|
6
|
+
const MAX_ARCHIVE_SESSIONS = 100;
|
|
7
|
+
const MAX_REASON = 200;
|
|
8
|
+
function readSessionIds(value) {
|
|
9
|
+
if (value.length > MAX_ARCHIVE_SESSIONS)
|
|
10
|
+
throw new Error(`sessionIds holds at most ${MAX_ARCHIVE_SESSIONS} session ids`);
|
|
11
|
+
for (const id of value)
|
|
12
|
+
assertSessionId(id);
|
|
13
|
+
return [...new Set(value)];
|
|
14
|
+
}
|
|
15
|
+
function sameEntries(exported, live) {
|
|
16
|
+
const current = new Set(live.map((entry) => entryDigest(entry.data)));
|
|
17
|
+
return current.size === exported.size && [...current].every((digest) => exported.has(digest));
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Archives each listed session whose live entries still match the ones `snapshot_export` recorded.
|
|
21
|
+
* The server reads the snapshot and the live journal itself, so no entry content reaches the
|
|
22
|
+
* caller: the result names only the sessions archived and a reason for each one skipped. The
|
|
23
|
+
* token is only read, never spent, so `snapshot_cleanup` can still use it.
|
|
24
|
+
*/
|
|
25
|
+
export const snapshotArchive = async (args, context) => {
|
|
26
|
+
const token = requiredString(args, 'cleanupToken');
|
|
27
|
+
const sessionIds = readSessionIds(requiredStringArray(args, 'sessionIds'));
|
|
28
|
+
const record = context.snapshots.take(token, context.sessionId, context.worktree);
|
|
29
|
+
const archived = [];
|
|
30
|
+
const skipped = [];
|
|
31
|
+
try {
|
|
32
|
+
const exported = await readExportedDigests(record.path, new Set(sessionIds), record.checksum);
|
|
33
|
+
for (const sessionId of sessionIds) {
|
|
34
|
+
const expected = exported.get(sessionId);
|
|
35
|
+
if (expected === undefined) {
|
|
36
|
+
skipped.push({ sessionId, reason: 'not in the export' });
|
|
37
|
+
continue;
|
|
38
|
+
}
|
|
39
|
+
try {
|
|
40
|
+
const live = await readEntriesIfPresent(sessionId, context.env, context.dependencies);
|
|
41
|
+
if (live === undefined)
|
|
42
|
+
skipped.push({ sessionId, reason: 'session not found' });
|
|
43
|
+
else if (!sameEntries(expected, live))
|
|
44
|
+
skipped.push({ sessionId, reason: 'entries changed since the export' });
|
|
45
|
+
else {
|
|
46
|
+
await archiveBlackboardSession({
|
|
47
|
+
sessionId,
|
|
48
|
+
env: context.env,
|
|
49
|
+
dependencies: context.dependencies,
|
|
50
|
+
});
|
|
51
|
+
archived.push(sessionId);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
catch (error) {
|
|
55
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
56
|
+
skipped.push({ sessionId, reason: `failed: ${reason}`.slice(0, MAX_REASON) });
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
throw new Error(`snapshot archive failed before any session was archived and the cleanupToken is still valid. ${error.message}`, { cause: error });
|
|
62
|
+
}
|
|
63
|
+
finally {
|
|
64
|
+
context.snapshots.restore(token, record);
|
|
65
|
+
}
|
|
66
|
+
return { sessionId: context.sessionId, archived, skipped };
|
|
67
|
+
};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { SnapshotChecksum } from '../agent-blackboard/snapshot-types.mts';
|
|
2
|
+
/**
|
|
3
|
+
* The identity of one entry: its content without the server-assigned `timestamp`, so entries that
|
|
4
|
+
* differ only in it are one event. Hashed, so a comparison holds digests, never entry content.
|
|
5
|
+
*/
|
|
6
|
+
export declare function entryDigest(data: unknown): string;
|
|
7
|
+
/**
|
|
8
|
+
* Reads the snapshot once and returns, for each requested session present in it, the set of its
|
|
9
|
+
* entries' digests. The file is read through a no-follow descriptor and, when the export reported
|
|
10
|
+
* a checksum, verified against it, so a file replaced since the export is refused.
|
|
11
|
+
*/
|
|
12
|
+
export declare function readExportedDigests(path: string, wanted: ReadonlySet<string>, checksum: SnapshotChecksum | undefined): Promise<Map<string, Set<string>>>;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { constants } from 'node:fs';
|
|
3
|
+
import { open } from 'node:fs/promises';
|
|
4
|
+
import { canonicalFeedback } from "../agent-blackboard/feedback-canonical.mjs";
|
|
5
|
+
import { parseSnapshotRecord } from "../agent-blackboard/snapshot-partition-format.mjs";
|
|
6
|
+
import { isObject } from "../agent-blackboard/snapshot-partition-guards.mjs";
|
|
7
|
+
import { readLines } from "../agent-blackboard/snapshot-partition-io.mjs";
|
|
8
|
+
/**
|
|
9
|
+
* The identity of one entry: its content without the server-assigned `timestamp`, so entries that
|
|
10
|
+
* differ only in it are one event. Hashed, so a comparison holds digests, never entry content.
|
|
11
|
+
*/
|
|
12
|
+
export function entryDigest(data) {
|
|
13
|
+
const content = isObject(data)
|
|
14
|
+
? Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'timestamp'))
|
|
15
|
+
: data;
|
|
16
|
+
return createHash('sha256').update(canonicalFeedback(content)).digest('hex');
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Reads the snapshot once and returns, for each requested session present in it, the set of its
|
|
20
|
+
* entries' digests. The file is read through a no-follow descriptor and, when the export reported
|
|
21
|
+
* a checksum, verified against it, so a file replaced since the export is refused.
|
|
22
|
+
*/
|
|
23
|
+
export async function readExportedDigests(path, wanted, checksum) {
|
|
24
|
+
const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
25
|
+
const digests = new Map();
|
|
26
|
+
const hash = createHash('sha256');
|
|
27
|
+
try {
|
|
28
|
+
if (!(await file.stat()).isFile())
|
|
29
|
+
throw new Error('snapshot path is not a regular file');
|
|
30
|
+
for await (const line of readLines(file, hash)) {
|
|
31
|
+
const record = parseSnapshotRecord(line);
|
|
32
|
+
if (record.type === 'session') {
|
|
33
|
+
const id = record.session.id;
|
|
34
|
+
if (wanted.has(id))
|
|
35
|
+
digests.set(id, new Set());
|
|
36
|
+
}
|
|
37
|
+
else if (record.type === 'entry') {
|
|
38
|
+
digests.get(record.entry.sessionId)?.add(entryDigest(record.entry.data));
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
finally {
|
|
43
|
+
await file.close();
|
|
44
|
+
}
|
|
45
|
+
if (checksum !== undefined && hash.digest('hex') !== checksum.value)
|
|
46
|
+
throw new Error('snapshot checksum does not match the export');
|
|
47
|
+
return digests;
|
|
48
|
+
}
|
|
@@ -91,6 +91,27 @@ export const TOOLS = [
|
|
|
91
91
|
},
|
|
92
92
|
maxBytes: { type: 'integer', minimum: 1, description: 'Bytes per partition (1048576).' },
|
|
93
93
|
}, ['cleanupToken']),
|
|
94
|
+
tool('snapshot_archive', 'Archives, in one call, every listed session whose live entries still match the ones ' +
|
|
95
|
+
'snapshot_export recorded. Takes the cleanupToken snapshot_export returned and sessionIds ' +
|
|
96
|
+
'(the sessions to archive, not the caller; at most 100). For each, the server confirms the ' +
|
|
97
|
+
'session is in the export, reads its live entries, compares them with the exported ones by ' +
|
|
98
|
+
'content without the server-assigned timestamp, and archives only on an exact match; ' +
|
|
99
|
+
'otherwise it skips with a reason (not in the export, session not found, entries changed ' +
|
|
100
|
+
'since the export, or failed). Returns only { archived, skipped: [{ sessionId, reason }] }, ' +
|
|
101
|
+
'never entry content. Archiving makes session metadata immutable. The token stays valid for ' +
|
|
102
|
+
'snapshot_cleanup; keep the snapshot until the last archive call. Each call holds the token ' +
|
|
103
|
+
'while it runs, so send archive calls one at a time and call snapshot_cleanup only after ' +
|
|
104
|
+
'the last one returns.', MUTATING, {
|
|
105
|
+
cleanupToken: { type: 'string', description: 'The cleanupToken snapshot_export returned.' },
|
|
106
|
+
sessionIds: {
|
|
107
|
+
type: 'array',
|
|
108
|
+
items: { type: 'string', pattern: ID_PATTERN, maxLength: 256 },
|
|
109
|
+
minItems: 1,
|
|
110
|
+
maxItems: 100,
|
|
111
|
+
uniqueItems: true,
|
|
112
|
+
description: 'Sessions to archive, from the export (at most 100 per call).',
|
|
113
|
+
},
|
|
114
|
+
}, ['cleanupToken', 'sessionIds']),
|
|
94
115
|
tool('snapshot_cleanup', 'Deletes the snapshot file and the partition directory (from snapshot_partition) that ' +
|
|
95
116
|
'snapshot_export produced. Takes only the cleanupToken it returned: the server resolves the ' +
|
|
96
117
|
'paths from its own record, never from the caller. The token is bound to the sessionId and ' +
|
package/docs/mcp-server.md
CHANGED
|
@@ -82,6 +82,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
|
|
|
82
82
|
| `retrospective_save` | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings` |
|
|
83
83
|
| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
|
|
84
84
|
| `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
|
|
85
|
+
| `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
|
|
85
86
|
| `snapshot_cleanup` | `cleanupToken` | `sessionId`, `cleaned: true` |
|
|
86
87
|
| `session_archive` | none | `sessionId`, `archived: true` |
|
|
87
88
|
|
|
@@ -134,8 +135,9 @@ keeping its content. `rejectedCount` and `worktreeRejectedCount` report those re
|
|
|
134
135
|
corrected retry with the same `sourceEventId` is accepted. `outbox_flush` also returns
|
|
135
136
|
`rejected: [{ sourceEventId, diagnostic }]` for what it moved. Flushing an empty
|
|
136
137
|
outbox does not create the directory. `snapshot_export` never accepts a destination: the
|
|
137
|
-
`agent-blackboard` client chooses a private file and returns its path. `session_archive`
|
|
138
|
-
destructive
|
|
138
|
+
`agent-blackboard` client chooses a private file and returns its path. `session_archive` and
|
|
139
|
+
`snapshot_archive` are the destructive tools; archived metadata is immutable, while entries stay
|
|
140
|
+
appendable.
|
|
139
141
|
|
|
140
142
|
### Snapshot partition
|
|
141
143
|
|
|
@@ -158,6 +160,28 @@ returns), and the client requires the snapshot to sit directly in its own `os.tm
|
|
|
158
160
|
recorded partition directory together. A failed partition leaves the token valid for a retry, and a
|
|
159
161
|
snapshot is partitioned once: a second call fails until a fresh export.
|
|
160
162
|
|
|
163
|
+
### Snapshot archive
|
|
164
|
+
|
|
165
|
+
`snapshot_archive` archives many distilled sessions in one call, verified by the server, so a pass
|
|
166
|
+
neither reads every session's entries into the agent's context nor makes one `session_archive` call
|
|
167
|
+
per session. It takes the `cleanupToken` `snapshot_export` returned and `sessionIds` (the sessions to
|
|
168
|
+
archive, not the caller; at most 100 per call, duplicates ignored).
|
|
169
|
+
|
|
170
|
+
- **Server-side comparison.** The server reads the snapshot from its own record (through a no-follow
|
|
171
|
+
descriptor, verified against the export's checksum when it reported one), and for each listed
|
|
172
|
+
session confirms it is in the export, reads the live entries, and compares the two sets by content
|
|
173
|
+
with the server-assigned `timestamp` left out, so entries that differ only in it are one event.
|
|
174
|
+
It archives on an exact match.
|
|
175
|
+
- **Skips, not failures.** A session that is not in the export (`not in the export`), no longer
|
|
176
|
+
exists (`session not found`), gained, lost, or changed an entry (`entries changed since the
|
|
177
|
+
export`), or whose read or archive failed (`failed: ...`) is skipped with that reason and left for
|
|
178
|
+
the next pass. The result is only `{ archived, skipped: [{ sessionId, reason }] }`.
|
|
179
|
+
- **Not spent.** The token stays valid for `snapshot_cleanup`. A snapshot that cannot be read or
|
|
180
|
+
verified fails the whole call before anything is archived, and the token stays valid.
|
|
181
|
+
- **One call at a time.** A call holds the token while it runs, so a parallel `snapshot_archive`,
|
|
182
|
+
`snapshot_partition`, or `snapshot_cleanup` with the same token fails as unknown. Send archive
|
|
183
|
+
calls sequentially and call `snapshot_cleanup` only after the last one returns.
|
|
184
|
+
|
|
161
185
|
### Snapshot cleanup
|
|
162
186
|
|
|
163
187
|
`snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.87.0",
|
|
4
4
|
"description": "Vouchington CLI and extractable tooling libraries.",
|
|
5
5
|
"homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -539,7 +539,7 @@
|
|
|
539
539
|
"@vouchington/postgres": "0.4.0",
|
|
540
540
|
"@vouchington/worker-runtime": "0.3.1",
|
|
541
541
|
"glide-mq": "^0.20.0",
|
|
542
|
-
"next": "16.4.
|
|
542
|
+
"next": "16.4.4",
|
|
543
543
|
"no-mistakes": "0.108.0",
|
|
544
544
|
"pg": "8.23.1",
|
|
545
545
|
"react": "19.3.1",
|
|
Binary file
|
|
@@ -15,7 +15,7 @@ subagent-identity rules.
|
|
|
15
15
|
|
|
16
16
|
Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
|
|
17
17
|
`journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `session_ensure`,
|
|
18
|
-
`snapshot_export`, and `session_archive`. Harnesses name them differently, so match the bare tool
|
|
18
|
+
`snapshot_export`, `snapshot_archive`, and `session_archive`. Harnesses name them differently, so match the bare tool
|
|
19
19
|
name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
|
|
20
20
|
underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
|
|
21
21
|
or the `vouchington-tooling` namespace reached through `GetDynamicTools` and `CallDynamicTool`.
|
|
@@ -25,6 +25,8 @@ Every call takes an exact `sessionId`, never inferred, whose meaning depends on
|
|
|
25
25
|
session unless a runner ensures a child identity.
|
|
26
26
|
- `journal_entries` and `session_archive`: the session read or archived, which during distillation
|
|
27
27
|
belongs to another agent.
|
|
28
|
+
- `snapshot_archive`: the caller, which also owns the `cleanupToken`; its `sessionIds` name the
|
|
29
|
+
sessions archived.
|
|
28
30
|
- `snapshot_export`, `outbox_status`, and `outbox_flush`: only the caller. The outbox is per
|
|
29
31
|
worktree, so `outbox_status` and `outbox_flush` report two counts: `pendingCount` is the unsent
|
|
30
32
|
records of that `sessionId`, and `worktreePendingCount` is the unsent records of every session in
|
|
@@ -44,11 +44,13 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
|
|
|
44
44
|
continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
|
|
45
45
|
or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
|
|
46
46
|
reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
|
|
47
|
-
sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned.
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
47
|
+
sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
|
|
48
|
+
simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
|
|
49
|
+
ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
|
|
50
|
+
`MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
|
|
51
|
+
or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
|
|
52
|
+
cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
|
|
53
|
+
with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
|
|
52
54
|
memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
|
|
53
55
|
list-read change against the plain single walk, not only against the base branch. See
|
|
54
56
|
[`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
@@ -342,6 +342,9 @@ CROSS JOIN LATERAL (
|
|
|
342
342
|
) due;
|
|
343
343
|
```
|
|
344
344
|
|
|
345
|
+
This is a complex shape: keep it only with `EXPLAIN ANALYZE` plans showing it beats the plain
|
|
346
|
+
query.
|
|
347
|
+
|
|
345
348
|
The loose scan beats a small thresholds table here because the intervals are chosen per row and
|
|
346
349
|
there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
|
|
347
350
|
thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
|
package/skills/glide-mq/SKILL.md
CHANGED
|
@@ -44,7 +44,8 @@ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
|
|
|
44
44
|
|
|
45
45
|
Dispatchers, paged fan-out, and job-id deduplication follow
|
|
46
46
|
[bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
|
|
47
|
-
replaces holding a PostgreSQL transaction
|
|
47
|
+
replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
|
|
48
|
+
used; see
|
|
48
49
|
[performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
|
|
49
50
|
|
|
50
51
|
Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
|
package/skills/manifest.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
{
|
|
5
5
|
"name": "agent-workflow",
|
|
6
6
|
"plugin": "vouchington-workflow",
|
|
7
|
-
"pluginVersion": "0.16.
|
|
7
|
+
"pluginVersion": "0.16.1",
|
|
8
8
|
"path": "agent-workflow/SKILL.md",
|
|
9
9
|
"prerequisites": [
|
|
10
10
|
"blackboard",
|
|
@@ -24,19 +24,19 @@
|
|
|
24
24
|
{
|
|
25
25
|
"name": "blackboard",
|
|
26
26
|
"plugin": "vouchington-workflow",
|
|
27
|
-
"pluginVersion": "0.16.
|
|
27
|
+
"pluginVersion": "0.16.1",
|
|
28
28
|
"path": "blackboard/SKILL.md"
|
|
29
29
|
},
|
|
30
30
|
{
|
|
31
31
|
"name": "bounded-iteration",
|
|
32
32
|
"plugin": "vouchington-database",
|
|
33
|
-
"pluginVersion": "0.
|
|
33
|
+
"pluginVersion": "0.11.0",
|
|
34
34
|
"path": "bounded-iteration/SKILL.md"
|
|
35
35
|
},
|
|
36
36
|
{
|
|
37
37
|
"name": "dependabot",
|
|
38
38
|
"plugin": "vouchington-workflow",
|
|
39
|
-
"pluginVersion": "0.16.
|
|
39
|
+
"pluginVersion": "0.16.1",
|
|
40
40
|
"path": "dependabot/SKILL.md",
|
|
41
41
|
"prerequisites": ["github-actions-checklist"]
|
|
42
42
|
},
|
|
@@ -50,38 +50,38 @@
|
|
|
50
50
|
{
|
|
51
51
|
"name": "final-review",
|
|
52
52
|
"plugin": "vouchington-workflow",
|
|
53
|
-
"pluginVersion": "0.16.
|
|
53
|
+
"pluginVersion": "0.16.1",
|
|
54
54
|
"path": "final-review/SKILL.md"
|
|
55
55
|
},
|
|
56
56
|
{
|
|
57
57
|
"name": "git-commit-checklist",
|
|
58
58
|
"plugin": "vouchington-workflow",
|
|
59
|
-
"pluginVersion": "0.16.
|
|
59
|
+
"pluginVersion": "0.16.1",
|
|
60
60
|
"path": "git-commit-checklist/SKILL.md"
|
|
61
61
|
},
|
|
62
62
|
{
|
|
63
63
|
"name": "github-actions-authoring",
|
|
64
64
|
"plugin": "vouchington-workflow",
|
|
65
|
-
"pluginVersion": "0.16.
|
|
65
|
+
"pluginVersion": "0.16.1",
|
|
66
66
|
"path": "github-actions-authoring/SKILL.md",
|
|
67
67
|
"prerequisites": ["github-actions-checklist"]
|
|
68
68
|
},
|
|
69
69
|
{
|
|
70
70
|
"name": "github-actions-checklist",
|
|
71
71
|
"plugin": "vouchington-workflow",
|
|
72
|
-
"pluginVersion": "0.16.
|
|
72
|
+
"pluginVersion": "0.16.1",
|
|
73
73
|
"path": "github-actions-checklist/SKILL.md"
|
|
74
74
|
},
|
|
75
75
|
{
|
|
76
76
|
"name": "github-issue",
|
|
77
77
|
"plugin": "vouchington-workflow",
|
|
78
|
-
"pluginVersion": "0.16.
|
|
78
|
+
"pluginVersion": "0.16.1",
|
|
79
79
|
"path": "github-issue/SKILL.md"
|
|
80
80
|
},
|
|
81
81
|
{
|
|
82
82
|
"name": "glide-mq",
|
|
83
83
|
"plugin": "vouchington-database",
|
|
84
|
-
"pluginVersion": "0.
|
|
84
|
+
"pluginVersion": "0.11.0",
|
|
85
85
|
"path": "glide-mq/SKILL.md"
|
|
86
86
|
},
|
|
87
87
|
{
|
|
@@ -94,26 +94,26 @@
|
|
|
94
94
|
{
|
|
95
95
|
"name": "npm-publishing",
|
|
96
96
|
"plugin": "vouchington-workflow",
|
|
97
|
-
"pluginVersion": "0.16.
|
|
97
|
+
"pluginVersion": "0.16.1",
|
|
98
98
|
"path": "npm-publishing/SKILL.md"
|
|
99
99
|
},
|
|
100
100
|
{
|
|
101
101
|
"name": "organize-github-issues",
|
|
102
102
|
"plugin": "vouchington-workflow",
|
|
103
|
-
"pluginVersion": "0.16.
|
|
103
|
+
"pluginVersion": "0.16.1",
|
|
104
104
|
"path": "organize-github-issues/SKILL.md",
|
|
105
105
|
"prerequisites": ["github-issue"]
|
|
106
106
|
},
|
|
107
107
|
{
|
|
108
108
|
"name": "package-json-checklist",
|
|
109
109
|
"plugin": "vouchington-workflow",
|
|
110
|
-
"pluginVersion": "0.16.
|
|
110
|
+
"pluginVersion": "0.16.1",
|
|
111
111
|
"path": "package-json-checklist/SKILL.md"
|
|
112
112
|
},
|
|
113
113
|
{
|
|
114
114
|
"name": "planning",
|
|
115
115
|
"plugin": "vouchington-workflow",
|
|
116
|
-
"pluginVersion": "0.16.
|
|
116
|
+
"pluginVersion": "0.16.1",
|
|
117
117
|
"path": "planning/SKILL.md",
|
|
118
118
|
"prerequisites": ["github-issue"]
|
|
119
119
|
},
|
|
@@ -127,78 +127,78 @@
|
|
|
127
127
|
{
|
|
128
128
|
"name": "postgres-node-performance-tuning",
|
|
129
129
|
"plugin": "vouchington-database",
|
|
130
|
-
"pluginVersion": "0.
|
|
130
|
+
"pluginVersion": "0.11.0",
|
|
131
131
|
"path": "postgres-node-performance-tuning/SKILL.md"
|
|
132
132
|
},
|
|
133
133
|
{
|
|
134
134
|
"name": "postgres-partitioning-uuid-v7",
|
|
135
135
|
"plugin": "vouchington-database",
|
|
136
|
-
"pluginVersion": "0.
|
|
136
|
+
"pluginVersion": "0.11.0",
|
|
137
137
|
"path": "postgres-partitioning-uuid-v7/SKILL.md"
|
|
138
138
|
},
|
|
139
139
|
{
|
|
140
140
|
"name": "postgres-schema-design",
|
|
141
141
|
"plugin": "vouchington-database",
|
|
142
|
-
"pluginVersion": "0.
|
|
142
|
+
"pluginVersion": "0.11.0",
|
|
143
143
|
"path": "postgres-schema-design/SKILL.md"
|
|
144
144
|
},
|
|
145
145
|
{
|
|
146
146
|
"name": "pr-description",
|
|
147
147
|
"plugin": "vouchington-workflow",
|
|
148
|
-
"pluginVersion": "0.16.
|
|
148
|
+
"pluginVersion": "0.16.1",
|
|
149
149
|
"path": "pr-description/SKILL.md"
|
|
150
150
|
},
|
|
151
151
|
{
|
|
152
152
|
"name": "ready-and-shepherd",
|
|
153
153
|
"plugin": "vouchington-workflow",
|
|
154
|
-
"pluginVersion": "0.16.
|
|
154
|
+
"pluginVersion": "0.16.1",
|
|
155
155
|
"path": "ready-and-shepherd/SKILL.md",
|
|
156
156
|
"prerequisites": ["stacked-prs"]
|
|
157
157
|
},
|
|
158
158
|
{
|
|
159
159
|
"name": "retrospective",
|
|
160
160
|
"plugin": "vouchington-workflow",
|
|
161
|
-
"pluginVersion": "0.16.
|
|
161
|
+
"pluginVersion": "0.16.1",
|
|
162
162
|
"path": "retrospective/SKILL.md"
|
|
163
163
|
},
|
|
164
164
|
{
|
|
165
165
|
"name": "retrospective-distill",
|
|
166
166
|
"plugin": "vouchington-workflow",
|
|
167
|
-
"pluginVersion": "0.16.
|
|
167
|
+
"pluginVersion": "0.16.1",
|
|
168
168
|
"path": "retrospective-distill/SKILL.md",
|
|
169
169
|
"prerequisites": ["github-issue"]
|
|
170
170
|
},
|
|
171
171
|
{
|
|
172
172
|
"name": "review-ci-logs",
|
|
173
173
|
"plugin": "vouchington-workflow",
|
|
174
|
-
"pluginVersion": "0.16.
|
|
174
|
+
"pluginVersion": "0.16.1",
|
|
175
175
|
"path": "review-ci-logs/SKILL.md",
|
|
176
176
|
"prerequisites": ["github-actions-checklist", "pr-description"]
|
|
177
177
|
},
|
|
178
178
|
{
|
|
179
179
|
"name": "review-github-issue-taxonomy",
|
|
180
180
|
"plugin": "vouchington-workflow",
|
|
181
|
-
"pluginVersion": "0.16.
|
|
181
|
+
"pluginVersion": "0.16.1",
|
|
182
182
|
"path": "review-github-issue-taxonomy/SKILL.md",
|
|
183
183
|
"prerequisites": ["github-issue"]
|
|
184
184
|
},
|
|
185
185
|
{
|
|
186
186
|
"name": "revisit-followups",
|
|
187
187
|
"plugin": "vouchington-workflow",
|
|
188
|
-
"pluginVersion": "0.16.
|
|
188
|
+
"pluginVersion": "0.16.1",
|
|
189
189
|
"path": "revisit-followups/SKILL.md",
|
|
190
190
|
"prerequisites": ["github-issue"]
|
|
191
191
|
},
|
|
192
192
|
{
|
|
193
193
|
"name": "stacked-prs",
|
|
194
194
|
"plugin": "vouchington-workflow",
|
|
195
|
-
"pluginVersion": "0.16.
|
|
195
|
+
"pluginVersion": "0.16.1",
|
|
196
196
|
"path": "stacked-prs/SKILL.md"
|
|
197
197
|
},
|
|
198
198
|
{
|
|
199
199
|
"name": "static-analysis-checklist",
|
|
200
200
|
"plugin": "vouchington-workflow",
|
|
201
|
-
"pluginVersion": "0.16.
|
|
201
|
+
"pluginVersion": "0.16.1",
|
|
202
202
|
"path": "static-analysis-checklist/SKILL.md",
|
|
203
203
|
"prerequisites": ["github-actions-checklist"]
|
|
204
204
|
},
|
|
@@ -225,14 +225,14 @@
|
|
|
225
225
|
{
|
|
226
226
|
"name": "triage-loop",
|
|
227
227
|
"plugin": "vouchington-workflow",
|
|
228
|
-
"pluginVersion": "0.16.
|
|
228
|
+
"pluginVersion": "0.16.1",
|
|
229
229
|
"path": "triage-loop/SKILL.md",
|
|
230
230
|
"prerequisites": ["ready-and-shepherd", "github-issue"]
|
|
231
231
|
},
|
|
232
232
|
{
|
|
233
233
|
"name": "triage-prs",
|
|
234
234
|
"plugin": "vouchington-workflow",
|
|
235
|
-
"pluginVersion": "0.16.
|
|
235
|
+
"pluginVersion": "0.16.1",
|
|
236
236
|
"path": "triage-prs/SKILL.md",
|
|
237
237
|
"prerequisites": [
|
|
238
238
|
"pr-description",
|
|
@@ -246,7 +246,7 @@
|
|
|
246
246
|
{
|
|
247
247
|
"name": "triage-sweep",
|
|
248
248
|
"plugin": "vouchington-workflow",
|
|
249
|
-
"pluginVersion": "0.16.
|
|
249
|
+
"pluginVersion": "0.16.1",
|
|
250
250
|
"path": "triage-sweep/SKILL.md",
|
|
251
251
|
"prerequisites": [
|
|
252
252
|
"triage-loop",
|
|
@@ -11,6 +11,12 @@ Local policy overrides these defaults; do not reload an already-read adapter or
|
|
|
11
11
|
|
|
12
12
|
Measure the query plan and the workload shape before changing code.
|
|
13
13
|
|
|
14
|
+
Owner's principle: "the basic premise is to use the simplest query, and making it more complex
|
|
15
|
+
requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
|
|
16
|
+
subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
|
|
17
|
+
it beats that simple query, not merely the previous version; see
|
|
18
|
+
[simplest query first](references/performance-patterns.md#simplest-query-first).
|
|
19
|
+
|
|
14
20
|
- Select only the required columns.
|
|
15
21
|
- Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
|
|
16
22
|
the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
|
|
4
4
|
Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
|
|
5
5
|
transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
|
|
6
|
-
Never hold a transaction
|
|
7
|
-
in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
|
|
6
|
+
Never use advisory locks, and never hold a transaction or connection across an external call; take
|
|
7
|
+
a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
|
|
8
8
|
renewal fails, and guard any write a stale owner could make with the token.
|
|
9
9
|
|
|
10
10
|
For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
|
|
@@ -21,6 +21,19 @@ data, but it does not replace suitable local indexes or predicates that permit p
|
|
|
21
21
|
|
|
22
22
|
## Query shapes
|
|
23
23
|
|
|
24
|
+
### Simplest query first
|
|
25
|
+
|
|
26
|
+
Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
|
|
27
|
+
entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
|
|
28
|
+
join, or subquery; then `ORDER BY` and `LIMIT`.
|
|
29
|
+
|
|
30
|
+
These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
|
|
31
|
+
query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
|
|
32
|
+
capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
|
|
33
|
+
fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
|
|
34
|
+
candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
|
|
35
|
+
continuation cursor is fine.
|
|
36
|
+
|
|
24
37
|
Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
|
|
25
38
|
`NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
|
|
26
39
|
UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
|
|
@@ -32,7 +45,8 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
|
|
|
32
45
|
The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
|
|
33
46
|
reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
|
|
34
47
|
`LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
|
|
35
|
-
viewer-scoped set
|
|
48
|
+
viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
|
|
49
|
+
candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
|
|
36
50
|
cross-partition query. Choose the partition key from dominant access patterns; a hot reader
|
|
37
51
|
of `RANGE (id)` needs an id or time bound.
|
|
38
52
|
|
|
@@ -98,7 +112,8 @@ count over its output. A restriction on a grouping column can still be pushed be
|
|
|
98
112
|
so let the plan decide. Confirm from the
|
|
99
113
|
plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
|
|
100
114
|
base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
|
|
101
|
-
restriction can reach inside the view.
|
|
115
|
+
restriction can reach inside the view. Reach for this only after the plan shows the simple
|
|
116
|
+
query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
|
|
102
117
|
a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
|
|
103
118
|
against the base tables instead. A plain join to the page is a join clause, not a restriction
|
|
104
119
|
inside the view, so the planner can still build the whole aggregate first.
|
|
@@ -148,7 +163,9 @@ Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rat
|
|
|
148
163
|
alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
|
|
149
164
|
sequential-await lint only when each step consumes the previous step's result; a shared
|
|
150
165
|
transaction client or lock ordering is not a data dependency. A lock that must be taken first
|
|
151
|
-
stays a separate, earlier statement; never reorder or parallelize it.
|
|
166
|
+
stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
|
|
167
|
+
because it exists: one that fails the lock rule in
|
|
168
|
+
[schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
|
|
152
169
|
|
|
153
170
|
Correctness comes before round trips. Before folding a statement away, state the guarantee it
|
|
154
171
|
gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
|
|
@@ -14,6 +14,13 @@ Local policy overrides these portable conventions.
|
|
|
14
14
|
- Split differing shapes, share identical values, and keep history documents as JSON.
|
|
15
15
|
- Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
|
|
16
16
|
- Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
|
|
17
|
+
- No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
|
|
18
|
+
have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
|
|
19
|
+
concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
|
|
20
|
+
parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
|
|
21
|
+
effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
|
|
22
|
+
slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
|
|
23
|
+
deleting it, not by swapping in another serializer.
|
|
17
24
|
- Reuse parameterized trigger functions instead of copying bodies.
|
|
18
25
|
- Comment every table, column, and view; document reviewed exceptions explicitly.
|
|
19
26
|
|
|
@@ -29,7 +29,9 @@ Default to a queue job whose job id is the durable row id, enqueued after commit
|
|
|
29
29
|
sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
|
|
30
30
|
backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
|
|
31
31
|
reason: legal or payment records, old values that vanish at commit, or an outcome that must
|
|
32
|
-
commit with domain rows.
|
|
32
|
+
commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
|
|
33
|
+
for a cap; count up to the cap and write, as in the lock rule in
|
|
34
|
+
[schema design](../SKILL.md).
|
|
33
35
|
|
|
34
36
|
When a table is justified, fence with one compare-and-set on the outcome or a generation
|
|
35
37
|
(`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.
|
|
@@ -71,11 +71,14 @@ Use when completed retrospectives or journals should become durable follow-up wo
|
|
|
71
71
|
denied-external tracking behavior.
|
|
72
72
|
7. Archive only verified records fully processed across every represented repository, and never
|
|
73
73
|
while any worktree's `outbox_status` reports a `worktreePendingCount` above 0, under the
|
|
74
|
-
repository's retention rules.
|
|
75
|
-
|
|
76
|
-
archive
|
|
77
|
-
|
|
78
|
-
|
|
74
|
+
repository's retention rules. Archive with the `snapshot_archive` tool, passing the
|
|
75
|
+
`cleanupToken` from `snapshot_export` and up to 100 `sessionIds` per call, which are the sessions
|
|
76
|
+
to archive, not the caller. The server confirms each session is in that export, reads its live
|
|
77
|
+
entries, compares them with the exported ones by content (entries that differ only in
|
|
78
|
+
the server-assigned `timestamp` are one event), and archives only on an exact match. Do not read
|
|
79
|
+
sessions with `journal_entries` to compare them yourself. It returns only
|
|
80
|
+
`{archived, skipped: [{sessionId, reason}]}`: leave every skipped session for the next pass,
|
|
81
|
+
because an entry added after the export would never be distilled. Archiving makes the session's metadata immutable, so it needs the archival authorization that
|
|
79
82
|
local policy requires. A one-repository pass leaves a multi-repository session active until the other
|
|
80
83
|
repositories are reviewed. Report reviewed, fixed, duplicate, deferred, quarantined, and
|
|
81
84
|
actionable dispositions with reasons. Keep the top five themes in human prose without dropping
|
|
@@ -128,7 +131,8 @@ difference is a conflicting payload and stays quarantined.
|
|
|
128
131
|
summary: partition index, deduplicated themes with their session IDs, and each session's
|
|
129
132
|
disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape
|
|
130
133
|
is determined structurally.
|
|
131
|
-
- Keep the verified snapshot until the last `
|
|
134
|
+
- Keep the verified snapshot until the last `snapshot_archive` call, because the server's archival
|
|
135
|
+
check reads it.
|
|
132
136
|
Then call `snapshot_cleanup`, which removes the snapshot and the partitions
|
|
133
137
|
`snapshot_partition` recorded, in a cleanup path that runs even when no session is archived.
|
|
134
138
|
- Report reviewed, fixed, duplicate, deferred, quarantined, actionable, created, updated,
|
|
@@ -138,8 +142,9 @@ difference is a conflicting payload and stays quarantined.
|
|
|
138
142
|
|
|
139
143
|
Cleanup, as a finally step: whether processing succeeded or failed, call `snapshot_cleanup` with
|
|
140
144
|
the `cleanupToken` from `snapshot_export`, with the same `sessionId` and `worktree`, once the
|
|
141
|
-
snapshot and its partitions are no longer needed.
|
|
142
|
-
retry the same
|
|
145
|
+
snapshot and its partitions are no longer needed. `snapshot_partition` and `snapshot_archive` leave the token valid, so cleanup comes after the last
|
|
146
|
+
archive call. The token is single-use and server-restart-scoped; if cleanup fails, retry the same
|
|
147
|
+
call.
|
|
143
148
|
|
|
144
149
|
Use source records only for local verification and leave them in the repository's approved journal
|
|
145
150
|
or retention system. Public issue bodies contain only the minimum bounded facts or redacted
|
|
@@ -150,5 +155,5 @@ copy its contents into an issue.
|
|
|
150
155
|
|
|
151
156
|
This skill supplies no issue repository, labels, milestones, projects, or approval model; it reads
|
|
152
157
|
sessions only from the snapshot file that `snapshot_export` writes, and archives them only with
|
|
153
|
-
`
|
|
158
|
+
`snapshot_archive`. Consumer wrappers cannot weaken this export
|
|
154
159
|
boundary; they provide only those local details.
|
|
@@ -32,6 +32,11 @@ Resolve these first and stop to ask when one is missing; never guess.
|
|
|
32
32
|
- **Issue taxonomy:** milestone and project rules, and where sensitive issues go.
|
|
33
33
|
- **Dispatch targets:** isolated-worktree subagents, and any terminal workspace manager whose
|
|
34
34
|
agents accept prompts.
|
|
35
|
+
- **Distill cutoffs:** `retroDays` and `sessionDays` (non-negative finite day counts), and whether
|
|
36
|
+
archiving the distilled sessions is authorized. The values come from the repository's
|
|
37
|
+
[retrospective-distill](../retrospective-distill/SKILL.md) adapter (the alias its `AGENTS.md`
|
|
38
|
+
declares, otherwise `.agents/skills/retrospective-distill/SKILL.md`); Phase E of
|
|
39
|
+
`triage-sweep` passes them through.
|
|
35
40
|
- **Fallback interval:** the cron cadence for a full sweep (default every 6 hours).
|
|
36
41
|
- **Late-review window:** how far back Phase F rescans merged PRs (default 14 days).
|
|
37
42
|
|
|
@@ -95,8 +95,11 @@ PR. For each one, under the adapter's taxonomy through
|
|
|
95
95
|
## Phase E - Retrospective distill
|
|
96
96
|
|
|
97
97
|
Run [retrospective-distill](../retrospective-distill/SKILL.md) for sessions completed after
|
|
98
|
-
`retroCursor
|
|
99
|
-
|
|
98
|
+
`retroCursor`, with the adapter's distill cutoffs (`retroDays` and `sessionDays`; see the loop's
|
|
99
|
+
[adapter parameters](../triage-loop/SKILL.md#adapter-parameters)). Stop and ask when either is
|
|
100
|
+
missing. File the verified follow-ups through [github-issue](../github-issue/SKILL.md). The
|
|
101
|
+
grant covers archiving the sessions it distilled, only when the adapter authorizes archival;
|
|
102
|
+
otherwise skip step 7 and still clean up. Advance `retroCursor` only after cleanup
|
|
100
103
|
succeeds.
|
|
101
104
|
|
|
102
105
|
## Phase F - Missed code reviews
|