Delivery Protocol

Before starting any implementation task, verify all of the following. If any check fails, stop and report what is missing — do not write code.

Visibility failing is a refuse-and-report. The hook path and signing being unset are local one-liners: set them (the key and email are in .claude/CLAUDE.md) and say so — do not stop work over a config a single git config fixes.

Lint, fmt, and test cleanliness are the pre-push hook’s job, not a precondition for starting work. A pre-existing warning is not your task unless the user says so — fixing it in passing is scope growth. Missing or placeholder project docs are surfaced by cargo xtask validate (mandatory-content), not by refusing to start.

This protocol applies to a new external dependency or framework — not to an in-repo type, module, or helper pattern (for those: pick, and say why in one line).

Training data favors established projects, so verify the recommendation reflects the current landscape (the known stale defaults list). That is a reason to check, not a reason to prefer the newer option.

Before using any crate or library API for the first time in a project:

Do not write code against an API you have not verified. The cost of reading docs first is minutes; the cost of debugging wrong assumptions is hours.

Every todo list for a code task MUST include a final item: "Create issue, commit, push, open MR".

Every code change that adds endpoints, tables, events, commands, or public API surface updates the first two below; the rest change only when the change alters what they say:

Plans are .adoc files created + linked BEFORE implementation. The plan authoring rules and the canonical Status vocabulary are the single source of truth in coding conventions. Four rules govern plan quality and durability:

The plan must already pass all four questions in the author’s own judgment before it is handed to review. Review is a check, not a drafting stage; a plan written as a draft "for the reviewer to fix" is the failure the bound exists to prevent.

Round 1 is a fresh subagent given only the plan, the rules (told to read the path-scoped ones too — coding-conventions, test-authoring — or the conformance question is answered without the conventions it asks about), and the four questions — never the authoring session’s context. Self-review from inside the authoring context shares every blind spot the plan has, and a context-heavy author will take the cheaper reading of "contextless" if the rule allows it. After round 1 the agent always presents the plan and the verdict to the user; the user, not the verdict, decides between shipping and a second round — otherwise the author’s own subagent is the only gate a plan ever passes. Round 2 is run by the human through a different vendor’s model — the coding-agent harness cannot call another vendor, so the agent’s job is to hand over the plan and the four questions and record what comes back. Independence comes from the vendor, not the round count (thirty same-model passes share one set of blind spots). Record each round as round | vendor | resolved model | verdict under a == Review log heading — the resolved model, not a tier alias, so the record stays meaningful when vendors re-point names. Fix round-2 blockers, then ship; there is no round 3. * Plans freeze at implementation start. A deviation is a one-line dated erratum, not a Design rewrite. One exception, for multi-unit plans: when a unit that has not started yet depends on a Design section that no longer matches what was built, correct that section to as-built and record the correction in the erratum line. A later implementer reads the Design as their spec, so a stale section plus an erratum is worse than a corrected section. The boundary that keeps this from becoming the old living-spec churn: correct to as-built, never redesign, and only sections a pending unit depends on. An improvement found mid-execution is a GitLab issue or is dropped — never a new plan section, never scope growth in the current change. * Completion check. A one-line closing comment records the merge; it verifies nothing. Before Status flips to Done, run cargo xtask plan-lint --done <plan>. It blocks (exit 1) when a referenced issue is still open, a cited repo path does not exist, a line still says "TBD" or "this MR", or the plan is nav-linked anywhere but Archive; it advises (exit 3; --strict blocks) when the plan is over the ~300-line cap, the review log has more than two rounds or none, the plan is not nav-linked at all (a repo-only meta plan), or issue states could not be verified because glab is unavailable. Every one of those is decidable, which is why the check is a program and not an audit agent — the old Plan Completion Audit caught the same things at the cost of an agent spawn per plan.

The information cascade has three tiers, each with a distinct owner — keep facts in exactly one:

One fact, one home. If the same fact lives in two places, they will drift. Pick the owner (usually the Antora site or the most specific rule) and make the other a pointer. The Documentation Update Checklist routes project knowledge to the docs site precisely so the agent context budget does not grow without bound.

Universal standards (this page and its siblings, the .claude/rules/ digests, the git hooks) are maintained in the gadhs/templates/claude-quickstart template repo and distributed as synced files. When the template updates, cargo xtask check-docs reports DRIFT (read from version stamps: behind = older than the template, just sync; edited = same version, local edits to restore). Repair both the same way:

A template host that is unreachable / 5xx degrades to advisory SKIP. For air-gapped/mirrored environments, set CLAUDE_TEMPLATE_URL to an internal mirror’s raw base. An active sync-overrides entry tolerates an intentional divergence (exit 3, advisory); an expired or unknown override blocks.

Template Updates (above) is the one-way distribution channel; this is its counterpart — how a template-level problem gets back UPSTREAM instead of being silently worked around.

Micro vs macro — which problems escalate:

How to escalate (not by reaching into the template repo): ONE comment on the standing "macro feedback / sharp edges" tracking issue in claude-quickstart, batched per session (all findings in one comment) — never a new issue per finding. This respects the "don’t consult sibling projects unless directed" guardrail: escalation is a filed suggestion, not a silent edit of the upstream.

The channel. Downstream repos carry a maintainer-provisioned, claude-quickstart-scoped project access token (CQS_CONTRIBUTION_TOKEN), distributed as a CI/CD variable (verified working end-to-end). It gives a downstream agent a recognizable bot identity, label/triage capability (a member token can self-apply labels), and revocable, narrowly-scoped upstream access — chosen over anonymous public-repo issue creation for identity, labeling, and control. Provisioning and rotating the token is the maintainer’s action; the agent uses the injected credential and self-applies agent-suggestion + needs-triage when filing.