Friction (empirical, this session — repeated commit-retry rounds)
An agent landing a commit/PR hits a SERIES of independent gates that are NOT run together upfront, so each surfaces only on a failed commit/push → repeated retry rounds:
- Source ref-ban (archaeology pre-commit hook): durable comments/JSDoc must not cite tracking refs. It bans BOTH
#NNNN ticket-refs AND ADR-NNNN refs — but its message only says "tracking tickets", which under-describes what it rejects. Cost this session: 4 commit-retry rounds on ONE refactor (removed #11573, then three separate ADR-0011 occurrences across the JSDoc summary, the @throws, and the throw message — each surfaced one at a time).
- Block-alignment: a new long import resets the import block's
from-column, so the whole block needs check-block-alignment --fix — a single re-run fixes it, but only after a failed commit reveals the drift.
- PR-body required sections:
lint-pr-body requires ## Post-Merge Validation (+ a Resolves #N) — surfaced only after PR-open via a reviewer [review-deferral] (#13804).
Each is individually cheap to fix; the friction is that they're discovered SERIALLY (commit fails → fix → commit fails again → …), not surfaced together before the first commit/push.
Proposed direction (design surface, not settled)
A single discoverable agent-preflight <files> (script or documented one-shot sequence) that, before the first commit/push:
- runs the archaeology ref-check and reports the exact lines + the
ticket-ref-ok: escape;
- runs
check-block-alignment --fix on the staged files;
- (for PRs) checks the PR-body template's required sections locally.
Quick win, independent of the above
- Make the archaeology-hook message name ADR-
NNNN refs explicitly — the current "tracking tickets" wording cost most of the 4 rounds (I didn't know ADR refs were banned until I'd removed all the #NNNN ones).
Open questions
- Script vs documented checklist vs extending the husky pre-commit to
--fix + report ALL gates in one pass?
- Which gates to bundle (the three above are the empirical set; are there others)?
Empirical anchor: @neo-opus-ada, this session (the #13794 pulls + discussions force-refetch builds, #13804 / #13812). Related: #9845 (linter config), #13144 (PR-review gate). Surfaced as friction→gold.
Friction (empirical, this session — repeated commit-retry rounds)
An agent landing a commit/PR hits a SERIES of independent gates that are NOT run together upfront, so each surfaces only on a failed commit/push → repeated retry rounds:
#NNNNticket-refs ANDADR-NNNNrefs — but its message only says "tracking tickets", which under-describes what it rejects. Cost this session: 4 commit-retry rounds on ONE refactor (removed#11573, then three separateADR-0011occurrences across the JSDoc summary, the@throws, and the throw message — each surfaced one at a time).from-column, so the whole block needscheck-block-alignment --fix— a single re-run fixes it, but only after a failed commit reveals the drift.lint-pr-bodyrequires## Post-Merge Validation(+ aResolves #N) — surfaced only after PR-open via a reviewer[review-deferral](#13804).Each is individually cheap to fix; the friction is that they're discovered SERIALLY (commit fails → fix → commit fails again → …), not surfaced together before the first commit/push.
Proposed direction (design surface, not settled)
A single discoverable
agent-preflight <files>(script or documented one-shot sequence) that, before the first commit/push:ticket-ref-ok:escape;check-block-alignment --fixon the staged files;Quick win, independent of the above
NNNNrefs explicitly — the current "tracking tickets" wording cost most of the 4 rounds (I didn't know ADR refs were banned until I'd removed all the#NNNNones).Open questions
--fix+ report ALL gates in one pass?Empirical anchor: @neo-opus-ada, this session (the #13794 pulls + discussions force-refetch builds, #13804 / #13812). Related: #9845 (linter config), #13144 (PR-review gate). Surfaced as friction→gold.