---

name: antigravity-maintainer-batch-release description: "Run protected AAS maintainer sweeps, PR merge batches, canonical sync, Core preview checks, and scripted releases. Use for repository maintenance, main alignment, CLI/MCP/Workbench changes, or release work; not ordinary contribution tasks." risk: critical source: self date_added: "2026-07-18"

Antigravity Maintainer Batch Release

When to Use

Use this skill for repository-wide AAS maintenance, maintainer-side PR repair or merge batches, canonical synchronization, AAS Core or Workbench changes, protected releases, and hosted catalog or legacy redirect infrastructure. Do not use it for ordinary contribution work that does not require maintainer privileges or canonical convergence.

Protected-Main Contract

Treat the repository root containing this skill as pull-request-only:

• Read AGENTS.md, .github/MAINTENANCE.md, and current maintainer docs before mutation.
• Never commit or push directly to main, even when the user says “push to main.” That phrase names the final target state.
• Preserve unrelated dirty work. Use a clean temporary clone or a topic branch for maintainer changes.
• Use npm run merge:batch for accepted source PRs. Do not substitute a raw merge API, generic GitHub skill, or generic push helper.
• Let automation/canonical-repo-state own generated artifacts and contributor-credit convergence after the source batch.
• Use release:prepare and release:publish for releases. They never authorize a direct main push.

Source Checks

Before changing anything:

1. Fetch origin/main; prove the clean maintainer checkout is on main and equals origin/main.
2. Inspect live PRs, issues, discussions in scope, Actions failures, Dependabot, CodeQL, secret scanning, and npm audit where relevant.
3. Confirm current scripts from package.json; do not rely on remembered release behavior.
4. Capture user worktree status separately and keep those files out of maintainer commits.

Maintainer Sweep

1. Triage every open PR before editing.

   • Separate valid source changes, repairable PRs, conflicts, generated-only noise, promotional links, and unsupported ownership/license changes.
   • Review semantics, safety, provenance, risk labels, limitations, source credits, and changed-skill evidence.
   • Prefer narrow maintainer repairs on the contributor branch when maintainer edits are enabled.
   • Optional accelerator before editing: run npm run maintainer:sweep for repo health, open PR check rollup, advisory download of CI pr-evidence-* artifacts (when pr-evidence succeeded), optional Jev triage (TYPESAFE_API_KEY in .env.local), merge:batch --dry-run on CI-ready PRs, and a Next actions hint list. Prefer CI evidence over re-running npm run pr:evidence locally when the artifact head matches. For a single head only, use npm run maintainer:jev-hints -- --base origin/main --head <head-sha>. Sweep/Jev/CI summaries are advisory only; merge:batch recomputes from trusted main, and Tessl plus --reviewed-head attestation remain authoritative. See docs/maintainers/maintainer-sweep.md and docs/maintainers/jev-hints.md.

2. Validate changed skills truthfully.

   • Run npm run validate, npm run validate:references, npm run security:docs, changed-skill evidence, and the relevant tests.
   • Treat the entire tracked skills/<skill-id>/** subtree as skill content. Inspect semantics, safety, provenance, declared risk, limitations, and every bundled file directly, including nested examples, scripts, lockfiles, references, and assets. Never reduce evidence or review to SKILL.md or a fixed support-directory allowlist.
   • Require changed-skill evidence to cover every Git record in each changed canonical skill subtree. Require the skill-review workflow for changes under skills/** or plugins/**/skills/**; its reusable result must be keyed by the complete nearest skill-directory fingerprint on the exact current head SHA.
   • Keep canonical skill ownership lookup proportional to changed-path depth, not total registry size, and preserve the five-minute trusted evaluator budget so repository-wide evidence completes without weakening fail-closed checks. Parse a legacy executable-mode canonical SKILL.md only as private, non-executable snapshot data; keep it reported as unsafe and never materialize symlinks, gitlinks, or other executable files.
   • review means Tessl semantic review actually ran or a valid identical-content result was reused.
   • manual-review-required means Tessl credentials or credits were unavailable, or Tessl did not produce a passing result. Perform the maintainer semantic review and attest with --reviewed-head <full-40-character-sha>.
   • Any non-passing Tessl outcome produces manual-review-required; complete the semantic review and bind the judgment to the exact head instead of treating a heuristic score as merge authority.
   • Never report manual-review-required as “Tessl passed.”
   • Scoped content-review fingerprints document exact bytes and observed checks, not general reliability. Keep explicit compatibility aliases and their complete local support bundles synchronized; the alias-integrity regression checks equality without affecting selection eligibility. Report remaining corpus debt rather than awarding an unqualified validation badge.
   • A verified upstream repository rename may bypass the provenance-identity blocker only through an exact entry in the trusted protected-base exception ledger. Record the skill ID, old and new source_repo, stable upstream repository ID, verification date, and canonical GitHub URL; all other provenance changes remain blocked.

3. Run checks in parallel where independent.

   • Use the repository validation, test, docs-security, source-credit, reference, warning-budget, and targeted app checks required by the changed files.
   • Fix deterministic policy failures in the source; do not wait for them as if they were flaky CI.
   • For source-only changed paths, a Git copy changes only its destination; renames change both paths. Preserve independent raw-record and blob safety checks and regressions for genuine generated-file mutations.
   • Treat pr-policy fork classification from the exact protected-base implementation as an unprivileged fail-fast gate before dependent work, never as approval authority. Install and resolve every dependency used by that classifier from the same protected-base worktree; never expose it to pull-request-controlled node_modules. merge:batch must still recompute the current trusted decision before approving any fork run or merging. The intake allowlist also covers browser source under apps/web-app/src/** (.css, .ts, .tsx); those fork runs may be approved, but every web-app source change still requires an exact-head maintainer attestation before merge.
   • Treat impact_profile as shadow-only telemetry. It must not skip, downgrade, or satisfy any required check.
   • For ordinary source PRs, require source-validation to generate preview state once and artifact-preview to verify the manifest bound to the exact head and run identity. For canonical-sync PRs, rely on pr-policy exact-tree reproduction, keep source-validation lightweight, require artifact-preview to confirm no drift, and retain final CI and CodeQL on the merged main commit.
   • Keep timing observational and test sharding opt-in. Required CI must continue to run the full unsharded npm run test; deterministic local shards may be used only through npm run test:local -- --shard-index N --shard-count M.

4. Merge accepted source PRs in conflict-aware order.

   • Run a dry classification first when useful.

   • For changed skill content, review the exact head and run:

     npm run merge:batch -- --prs <PR_LIST> --reviewed-head <FULL_HEAD_SHA>
     

   • merge:batch does not rewrite the PR body and does not close or reopen the PR. It evaluates the current immutable PR tuple and may approve only workflow runs bound to that PR and exact head SHA.

   • Same-repository location is not sufficient authority for sensitive changes. The guarded same-repository exception is limited to a PR authored by the repository owner and requires an exact full-head attestation; collaborator-authored sensitive PRs fail closed under the external safety policy.

   • The routine protected checks are pr-policy, pr-evidence, source-validation, and artifact-preview. The retired aas-v1-baseline workflow is not a merge prerequisite and must not be awaited or approved during source or canonical-sync batches.

   • If the PR head or base changes, discard stale evidence, refresh to the current origin/main, and rerun the batch. The command does not retry base drift automatically.

5. Converge canonical state once after the source batch.

   • Wait for the protected automation/canonical-repo-state PR.
   • Verify its managed-only diff, required checks, merge result, and the resulting origin/main.
   • If an unmanaged repair remains, use a topic PR; never patch main directly.

Reviewed fork bundle exceptions

tools/config/reviewed-fork-skills.json is a protected-base ledger for the two explicitly reviewed fork contributions #1337 and #1413. Each entry binds the base repository, fork repository, PR number, original full reviewed head and complete Git skill-tree object. It permits only Python files under that skill's scripts/ subtree and its root LICENSE, with a read-only Git copy origin when needed. It does not allow workflows, arbitrary script types, generated-file mutations, unsafe modes, links, invalid paths/objects or oversized content.

Both CI intake and merge:batch load the ledger from their trusted evaluator checkout, never the PR's repository directory. Any change anywhere in the skill subtree invalidates the exception. A base-only merge may reuse identical content, but the maintainer must inspect the new complete PR diff and attest its exact current head with --reviewed-head. Evidence, source-only checks, truthful skill review, immutable PR/workflow binding and strict branch protection all remain mandatory. Missing or malformed ledger data fails closed. Further exceptions or policy expansions need explicit maintainer authorization and protected review.

Workflow Contract Change Gate

When changing maintainer scripts, workflows, or policy, update the canonical skill, maintainer documentation, and regression tests in the same source PR. Add a negative test for every failure mode being fixed, run the relevant dry-run path, and reject any implementation/documentation mismatch. Source PRs must exclude generated registries and plugin mirrors; the protected canonical-sync PR owns that derived state, except for files intentionally staged by the scripted protected-release flow.

Repository documentation consistency

When auditing repository documentation, compare operational guides and translations with exact-base scripts and workflow behavior. Check local links, heading anchors and documented npm commands with tools/scripts/tests/test_documentation_consistency.py; dated evidence and backup snapshots are historical, not current instructions. Keep canonical guides discoverable from docs/README.md, distinguish source merge from release availability, and report the scope of the audit without claiming that all skill procedures or external integrations ran.

Specialized Plugin Consistency

Use data/specialized-plugin-candidates.json for specialized-plugin membership and data/editorial-bundles.json for the installable composition, descriptions, limits and starter prompts. Review changes against canonical skills_index.json; keep IDs stable unless a migration is explicitly requested. Derive the web catalog and prerender/live-verifier counts from these sources instead of maintaining copied lists or fixed counts. Verify full skill-list expansion, sourc