This is the detailed operating contract. Start with the short canonical maintainer skill. Classification lives in tools/config/maintenance-policy.json; generated paths live in tools/config/generated-files.json. Read these files at the exact protected base. Cache knowledge by their Git object identities, never by an assumed version or a previous chat’s completion claim.
Preserve dirty checkouts. Fetch protected main into an isolated clone; read its AGENTS.md, MAINTENANCE.md, canonical skill and package.json before mutation. Mandatory commands must exist on that base. Never import a retired helper from another branch, worktree, stash, installed copy, or historical commit. Inspect removal history if instructions conflict.
Main is PR-only, with strict up-to-date protection and administrator enforcement. merge:batch is the only fork-run approval and merge authority. No direct main pushes, admin bypass, deferred GitHub auto-merge, raw merge helper, or local-integration exception. The helper does not rewrite PR metadata and does not retry base drift automatically. Repair conflicts on the source branch, rerun invalidated checks, then resume deliberately.
Triage all PRs/issues in the requested scope; inspect live Actions, security alerts and advisories. Repair mergeable source PRs on their branches and retain unrelated changes. Use the default PR template and Quality Bar Checklist. Do not close unrelated issues or publish releases just because a sweep is requested. Jev and SkillSpector are advisory, never required protection or substitutes for review. Jev defaults to five skills; keep keys only in ignored .env.local and never print them.
pr:preflight computes the immutable base/head diff and runs maintenance:validate in an isolated checkout. Never validate a dirty tree as an immutable head. Every expected command has a result in the completion receipt; missing, skipped or failed checks fail closed. Unknown, mixed, executable/link/mode, workflow, policy, generator and shared-dependency changes receive full checks.
| Change | Validation |
|---|---|
| Changelog or known editorial docs | Documentation/reference consistency and documentation security; no runtime or web suite |
| Canonical skill or support files | Global schema/uniqueness, warning budget, source credits, generated preview, references, catalog integrity, documentation security; complete semantic review |
| Runtime/CLI/MCP/installer | Catalog checks plus runtime and package/installer tests; platform preview where selected |
| Web source | Catalog contracts plus web coverage and build |
| Unknown, policy, generators or shared dependencies | Full script suite and web coverage/build |
pr-evidence runs in parallel with source-validation after pr-policy. Artifact preview depends on source validation. It does not wait for pr-evidence.
Required checks remain pr-policy, pr-evidence, source-validation, artifact-preview, from GitHub Actions app 15368. The protected-base classifier, not PR-controlled policy, authorizes fork execution. source-validation generates ephemeral previews once; artifact-preview verifies their exact head/workflow/run-attempt manifest. impact_profile remains shadow-only; validation_profile chooses execution. Do not infer semantic approval from a green deterministic gate.
Merged main validates its source diff and discards generated changes. Ordinary maintenance never creates a canonical-sync PR. Repo Hygiene tests ephemeral generated state, without write permissions. Tracked indexes, plugin mirrors, manifests and catalogs describe the last prepared distribution, not necessarily current source main. Use npm run chain in a scratch checkout for a development view. It already includes catalog generation.
Git copy records bind the changed destination; copying an unchanged canonical file into a generated release mirror does not create a new canonical-content review. Renames and deletions still bind the old canonical tree.
Review the entire tracked skills/<skill-id>/** subtree, including references, scripts, licenses, modes and links. Inspect purpose, semantics, safety, provenance, declared risk, limitations, and all bundled files. Changes under apps/web-app/src/** that require human review still need exact-head maintainer attestation. A real Tessl review is distinct from manual-review-required; the latter is not a passing Tessl review.
Safe, unprivileged analysis can start before review. Sensitive workflow/code changes still require the existing owner authorization: same-repository PR authored by the repository owner and exact full-head review. Protected-base tools/config/reviewed-fork-skills.json is the only reviewed-fork bundle exception; no PR-controlled ledger or general executable allowlist is permitted.
For persistent review reuse, create a private mode-0700 state directory outside every source checkout. Pass --state-dir, --reviewer, --review-evidence, and the explicitly reviewed --reviewed-head FULL_SHA. The evidence must describe an actual completed review, not a tool score. The helper signs a receipt with a locally generated private 256-bit key. Never copy receipts or the key into a PR.
Reuse is limited to skill-only changes with identical complete skill trees and identical protected/head evaluator, schemas, dependency and operational context. Changes to any bound content or mode invalidate reuse. A base-only update can reuse content review, but the helper still authorizes only the exact current full SHA and requires current checks/protection. Missing or invalid receipts cannot authorize merge. Deterministic evidence is also authenticated and reusable only for the same repository, evaluator, merge base, head and raw diff. A valid receipt never authorizes new unrelated web/runtime changes.
Use npm run merge:batch -- --prs 123,124 --state-dir /absolute/private/state with necessary review arguments. --prepare-only starts safe analyses without merging. The journal preserves attempts, timings and blocked results. Every resume fetches current GitHub state; saved green checks are not authority. Already merged PRs must have a merge commit reachable from current protected main. Independent PRs continue after one is blocked. Any blocked result gives a failing command status. If the evaluator contract changes, refresh the protected checkout before resuming.
When a runtime release is requested, write truthful changelog notes based on the actual tag diff, then use release:prepare -- X.Y.Z from clean current main. This creates release/vX.Y.Z, synchronizes distribution snapshots, plugin compatibility, Codex/Claude mirrors, editorial bundles, manifests and marketplaces together, validates them, and opens a protected PR. Contributor credit comes from reviewed frontmatter and data/source-credits.json; generated leaderboards are never edited by hand.
Prepared release PRs and their merged main commit run snapshot/schema/reference/security/compatibility checks; the full runtime/web suite and platform matrix execute on the immutable tag candidate. The separate agent-first preview also defers a valid prepared snapshot to that candidate, avoiding a second package and platform matrix before the tag.
The prepared data/distribution-snapshot.json binds version and tracked tree modes/content independently of commit SHA. Packaging unprepared development main fails through prepack. Ephemeral PR test packing explicitly uses --ignore-scripts; it does not produce publication authority. The release workflow seals the final staged tree after generator convergence. Exactly one merged release PR authored by the repository owner must match the version.
Check out that immutable merged release commit and run release:publish -- X.Y.Z. It verifies protected-main ancestry, prepared snapshot and tag identity; main may have advanced. Never retag a published version. Stable npm releases use latest, prereleases use next.
distribution-candidate.yml validates the immutable tag, builds catalog/npm tarball/site once, and exercises the exact packed bytes on Linux and Windows with Node 22 and 24, including the supported PowerShell checks. The candidate manifest binds repository, commit, workflow, run ID/attempt, version, lockfile digest and both artifact digests. Only a successful complete candidate run can feed publication. npm and Pages verify origin and digests, then consume the same bytes without regeneration or repeated full testing. Missing/expired artifacts require a new complete candidate run, never an unchecked publisher rebuild.
Pages runtime deployment is dispatched at the release tag with deployment_target=release; direct development-main deployment is retired. Canonical host is https://github.com/ibrdot/swe-re-expert/, root base /. Check the legacy redirect bridge separately.
After the compatible runtime is published, catalog-distribution.yml can be dispatched on protected main with an independent SemVer revision, such as 2026.10.18. It generates and validates a complete data archive plus site, publishes catalog-vREVISION assets and deploys the same tested site. It neither changes runtime version nor publishes npm. Revisions are immutable: never overwrite a tag or asset.
The descriptor identifies revision, source commit, catalog digest/schema, minimum runtime and runtime major, plus archive SRI. Catalogs contain complete skill/support trees as inert regular files; safe internal links are materialized and executable permission bits are removed. Nothing is executed during import. Index paths must remain inside verified skill trees. Explicitly pin revision and SRI:
aas catalog update --cache-root /absolute/cache --revision 2026.10.18 --integrity 'sha512-EXACT_RELEASE_DIGEST'
The downloader uses only the official repository’s release URL and bounded HTTPS asset redirects. --archive /absolute/catalog.tgz supports offline import with the same required integrity. The immutable cache verifies all bytes on use. Select/rollback explicitly by catalog digest; no automatic ranking or selection is added. stack plan requires an explicitly cached compatible --runtime-version; apply re-verifies both identities and compatibility. Legacy embedded catalogs keep their original exact runtime coupling. Direct installer preview is only for npm-backed catalogs; independent revisions use the stack plan/apply path and retain its existing experimental approval gate.
Every stable or prerelease version must finish with the full-release-alignment gate. Run release:verify against the immutable release: prepared snapshots and plugin versions, tag/GitHub Release/npm version and intended dist-tag, exact-commit CI/CodeQL/candidate/Pages, fresh npm installation and integrity, live catalog/SEO, and legacy bridge must agree. A public artifact mismatch or stale public surface keeps the public release incomplete. Independent catalog publication additionally verifies the published descriptor/archive and live catalog-release.json.
Report personal environment alignment separately. Update only authorized existing host entries, pin agentic-awesome-skills@X.Y.Z and --version X.Y.Z, and test a real MCP initialize/tools/list handshake. A separate probe is not proof that a native client reloaded its running session. Do not invent native-client confirmation. Personal reloads do not block a verified public release.
Measure from first preparation/analysis through final required main/public verification. Record queue time, execution, retries, manual interventions and cache state. Compare equivalent editorial, skill-only and release cycles; report sample sizes and raw timestamps. Local microbenchmarks and simulated failures are separate evidence and never a measured end-to-end speedup. Do not remove checks to manufacture a faster result.