Agent tooling

Agent tooling is the Forge issue-tracker driver and the pull request automation an agent runs on this repository's behalf, split across four units:

• forge.mjs — the client that owns every Forge credential and API call.
• auto-merge.mjs — the policy-driven pilot that merges into staging on its own.
• review-pr.mjs — the delegator to an external review kit.
• forge-purge-issues.mjs — a destructive administrative script kept apart from the rest.

Authentication

forge.mjs holds the one Forge credential every other tool here uses — tools/lib/auto-merge/forge-api.mjs and scripts/forge-purge-issues.mjs both import its parseRemote and resolveAuthHeaders rather than resolving a token of their own. Before an agent runs anything in this area, the git credential store for the Forge remote's host needs an entry. Only when that store has nothing is FORGE_TOKEN in the environment read. A request to a host that is neither the git remote's host nor FORGE_BASE_URL carries no credential at all, by construction, and reads back as a 404 rather than an auth failure.

The ordinary sequence

1. Read the ticket. node tools/forge.mjs issue <n>, and node tools/forge.mjs comments <n> for the discussion so far.
2. Open a pull request. node tools/forge.mjs create-pr --base <b> --head <h> --title <t> prints one JSON line with the new number, so a script can pick it up directly.
3. Watch its checks. node tools/auto-merge.mjs --pr <n> --dry-run evaluates the same policy the pilot uses. It reports back exactly what is missing — a label, a review, or a pending or failing status context — without writing anything.
4. Merge. Into staging, auto-merge.mjs merges on its own, once its policy is satisfied and it is armed. Into any other branch, merging is node tools/forge.mjs merge <n> --head-sha <sha> by hand; --head-sha guards against merging a head nobody reviewed.

What these tools refuse to do

Each refusal below replaces a check a reviewer would otherwise have to remember by hand.

• auto-merge.mjs merges only into staging: main is the release branch, merged by hand, and dev needs no pull request at all. It also passes on a fork head, a pull request carrying the no-automerge label, or one that edits .forgejo/workflows/* on its own head. Such a change cannot clear the gate it is rewriting.
• node tools/forge.mjs create-issue is a raw primitive: nothing on that path checks a body against any schema, so it is never the way to file a ticket in this repository.
• forge-purge-issues.mjs refuses to delete any issue absent from its local archive, and refuses outright when the archive file itself is missing.
• review-pr.mjs resolves where the review kit sits at run time rather than hard-coding an absolute path, so the same review:pr script in package.json works on every checkout.

Units in this area

Every unit in agent tooling, with the page that documents it.

Unit	What it does
forge-purge-issues.mjs	Deletes every live Forgejo issue in this repository, but only once each one is confirmed present in the local archive.
auto-merge.mjs	Merges pull requests into staging once they clear this repository's auto-merge policy, run once or on a watch interval.
forge.mjs	The Forgejo client every script and agent in this repository talks to the issue tracker and pull requests through.
label-check.mjs	Reads every open ticket on the Forge and refuses a tracker whose triage labels have drifted.
review-pr.mjs	Runs the forge review kit's review-pr entrypoint against this repository, resolving where that kit lives at run time.
ticket-lint.mjs	Reads one ticket body against this repository's ticket standard and names every section that does not meet it.
ticket-new.mjs	Files a Forge issue whose body is rendered from this repository's ticket standard, checked against it, and whose acceptance command has been run and seen to fail.