docs: correct drift between the docs and the running system

[joryirving]

Summary

• Seven documented behaviours that no longer match the code, corrected against the code.

What was wrong

Each verified directly rather than taken from a report:

Claim	Reality
"No webhook receiver for real-time updates" (README.md)	src/app/api/pr-followup/webhook/route.ts exists and ingests PR events. Issue-label events are still not consumed.
"/api/sync currently does not require DISPATCH_AGENT_TOKEN"	It calls authorizeRequest, same as the other agent endpoints.
"Cache freshness is owned by agent harness heartbeat sync rather than a Dispatch background worker", and an internal scheduler is something "Phase 1 intentionally avoids"	src/lib/scheduler.ts runs five jobs: sync, groomer, pr-followup, prune-closed, reconcile.
PR_FOLLOWUP_BOT_IDENTITIES is "a JSON object mapping bot logins to a behaviour label", with a JSON example	src/lib/pr-followup-ingestion.ts:41 does split(","). Following the documented format produced garbage.
DISPATCH_LANE_CONFIG / DISPATCH_GROOMER_INTERVAL_SECONDS	The variables are DISPATCH_LANE_CONFIG_JSON and DISPATCH_GROOMER_INTERVAL_MS.
"Out of the box, Dispatch configures three lanes: normal, escalated, backlog"	The shipped defaults are default and backlog.
Status label list	Omitted status/blocked entirely, including the distinction that a block with a blockedReason needs a human while one without is recovered by the groomer (#862).

The PR_FOLLOWUP_BOT_IDENTITIES and DISPATCH_GROOMER_INTERVAL_SECONDS entries are the ones worth noting: both are documented in a form that cannot work, so anyone configuring from the docs gets silent misbehaviour rather than an error.

Deliberately not changed

An audit flagged the ~29 lane=normal examples in AGENTS.md and the harness docs as returning HTTP 400. That is true of the shipped defaults but not of this deployment, whose live DISPATCH_LANE_CONFIG_JSON carries laneAliases: {normal: local, escalated: frontier, cloud: local}. Rewriting them would have broken working examples to match a configuration we do not run.

Added one note in AGENTS.md recording that normal is an alias rather than a built-in lane, so the dependency is visible to anyone copying the examples into a different deployment.

Verification

• Every claim above checked against the referenced source file on main.
• Live lane config read from the running Deployment's env to settle the alias question.
• Docs only; no code paths touched.

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M3@https://litellm.jory.dev/v1 (anthropic) — escalated (fast_low_confidence)

Recommendation: approve

This PR is a docs-only correction pass that aligns five markdown files with what the code on main actually does. Each change is verifiable against the running repo, the body documents seven concrete drift items with their respective source files, and the Deliberately not changed section explicitly explains the one item the author chose to leave alone (the lane=normal aliases). CI is green across the board (lint, typecheck, build, tests, smoke, migrations, Docker Build ×2, Coverage, Database integration, npm audit), so there is no infra regression hiding in the diff.

Change-by-change findings

AGENTS.md

• Adds a blockquote immediately above the worker loop calling out that normal is a deployment-specific alias (normal → local) and that the shipped defaults are default + backlog. This is consistent with docs/configurable-lanes.md and with DISPATCH_LANE_CONFIG_JSON reference in the rest of AGENTS.md. Good.
• must_check: no mandatory checklist items were emitted for this file, and the standards file does not forbid this kind of inline caveat.

README.md

• Lanes description (Execution Lanes): "two lanes: default and backlog" and DISPATCH_LANE_CONFIG_JSON. Matches docs/configurable-lanes.md table and the env-var reference earlier in README.
• Status labels: added status/blocked line including the blockedReason vs no-reason distinction. The grep evidence shows src/lib/groomer/selector.ts:49 and src/lib/groomer/selector.test.ts:295 reference issue PR 862 with the parked/recoverable semantics, so the wording matches the code.
• Groomer interval var: DISPATCH_GROOMER_INTERVAL_SECONDS → DISPATCH_GROOMER_INTERVAL_MS, default 600000. AGENTS.md env-var table lists the same name with default 600000, so the docs are now internally consistent.
• PR_FOLLOWUP_BOT_IDENTITIES: the old docs claimed a JSON-object format that src/lib/pr-followup-ingestion.ts does not actually consume. The new description (comma-separated logins, default github-actions[bot]) matches the split(",") behavior the PR body cites. This is the most consequential fix in the PR — operators following the old docs were getting silent misbehavior.
• Scheduled Issue Sync Strategy: the framing that cache freshness is owned by the in-process scheduler in src/lib/scheduler.ts (with heartbeat sync as a secondary path) replaces the prior claim that an internal scheduler is "Phase 1 intentionally avoided." The git history (29c9bdb feat(scheduler): in-app scheduler; internalize scheduled sync) and the reference to src/lib/scheduler.ts in the new README support this. The body also notes five jobs (sync, groomer, pr-followup, prune-closed, reconcile); AGENTS.md's env-var table separately mentions DISPATCH_RECONCILE_*, which is consistent with the scheduler handling reconcile on its own interval.
• /api/sync auth: corrected to require DISPATCH_AGENT_TOKEN via authorizeRequest. Plausible — the body says the route calls authorizeRequest like other agent endpoints; the search did not surface src/app/api/sync/route.ts itself, so I cannot independently verify the exact call, but the surrounding PR diff context and the linked "Deliberately not changed" rationale imply this was checked against the source.
• Known Limitations: item 6 rewritten from "No webhook receiver for real-time updates" to "Partial webhook coverage" with a pointer at /api/pr-followup/webhook. Issue-label events remain undocumented as consumed, which matches the diff and the body.

docs/configurable-lanes.md

• Default-lanes table drops normal/escalated and replaces them with default. Consistent with README and AGENTS.md.
• New paragraph under the table: DISPATCH_LANE_CONFIG_JSON, normal/escalated are not built in, and laneAliases keeps older stored IDs resolving. This makes the alias pattern discoverable for someone copy-pasting examples.
• Two DISPATCH_LANE_CONFIG references → DISPATCH_LANE_CONFIG_JSON (in the example block and the "if not set" sentence). Internally consistent.

docs/hosted-groomer.md

• DISPATCH_GROOMER_INTERVAL_SECONDS → DISPATCH_GROOMER_INTERVAL_MS with default 600000, matching the AGENTS.md env-var table.
• "Scheduling" section rewritten so the endpoint is driven by the in-process scheduler at DISPATCH_GROOMER_INTERVAL_MS (default 10 min), while still allowing direct external invocations. Matches AGENTS.md and README.

docs/issue-lane-classification.md

• One rename: DISPATCH_LANE_CONFIG → DISPATCH_LANE_CONFIG_JSON. Consistent with the rest of the PR.

Standards Compliance

The repository standards file (AGENTS.md excerpt) is the file being modified, so the relevant checks are whether the modifications remain consistent with the file's own conventions:

• "No agent-specific names in generic docs" — the new lane-alias caveat does not name agents. ✅
• "Validate inputs before database operations" / "API routes return appropriate HTTP status codes" — not applicable, docs only.
• "No commit of secrets" — diff is markdown only. ✅
• The standards file itself documents DISPATCH_GROOMER_INTERVAL_MS (default 600000) and DISPATCH_LANE_CONFIG_JSON in its env-var table; this PR brings README/docs in line with those entries. The PR strengthens compliance with the standards, it does not weaken it.

Tool Harness Findings

The native harness issued no tool calls. CI results are reported as terminal-success across all 11 checks (lint, typecheck, build, tests, smoke, coverage, migrations, Database integration, Docker Build ×2, npm audit). Image-digest provenance shows no image changes — expected for a docs-only PR.

Unknowns or Needs Verification

• The exact auth call inside src/app/api/sync/route.ts was not directly visible in the diff. The PR body's wording is plausible and consistent with the surrounding AGENTS.md/README guidance, but I cannot independently grep that file from this corpus. Treat as soft-verified via the author's claim and the diff context.
• The DISPATCH_RECONCILE_* family referenced by AGENTS.md is implied by the PR body to be part of the scheduler's five jobs; the exact scheduler job list and interval variables for reconcile were not surfaced by the diff itself, only by the README's rewrite. Low risk because the change is purely narrative, but flagging as a follow-up if reconcile interval naming needs its own doc pass later.

Findings

None of the corrections in this PR contradict what the repository impact scan or the linked git history show. The diff is internally consistent across the five files, removes concrete documented misbehavior (especially the JSON-vs-comma PR_FOLLOWUP_BOT_IDENTITIES discrepancy), and the deliberate decision not to rewrite the lane=normal examples is well-reasoned and disclosed in the PR body. Approving.