docs(contracts): assess external reports and answer the load-bearing question before dispatch (refs #3001) - #3002
Conversation
…question before dispatch refs #3001 On #3000 the design question was asked and a fixer dispatched before the answer arrived. The answer showed the project's libs.versions.toml entry is the ktlint-gradle PLUGIN version, not a CLI version, so the briefed remedy would have compared 14.2.0 against 1.8.0 and reported a large, entirely false skew — worse than the silence it exists to remove. Three external lanes the same day each out-reasoned the lane they fed, so the rule also says to cite a reporter's reasoning as authority rather than paraphrase it. Contract lands in AGENTS.md; the merge-train skill only points at it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ing answer refs #3001 The existing rule named PR reviews only, and was read that narrowly: agent-written issue triage, assessments, remainder comments and replies asking a reporter for measurements all went out with no disclosure. Anything an agent posts where someone outside this repo reads it now says so, once, at the end. The comment that asks a reporter to spend effort is the one where it matters most. Internal artifacts are excluded: ledger, briefs, commit messages, and issues nobody outside reads. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
ci-classifier: infra-kill (no failing assertion; [mem-watch] KILLED WITH HEADROOM — no failing assertion, and no sample fell below 9844 MB of 15989 MB, so the box was not short of memory at any sample point (2000ms sampling: a shorter spike, or a pressure-based kill by systemd-oomd, would not show up here). Read the kernel kill evidence step for the signal's sender. exitCode=137 totalMb=15989 lowWaterAvailableMb=9844 lowWaterAt=15:09:27 childPid=2455; heaviest files by peak RSS: tests/config/vi-mock-export-sweep.test.ts (3952 MB), tests/index-integration.test.ts (1710 MB), tests/clients/flake-shape-ratchet.test.ts (1352 MB); kernel evidence: dmesg and cgroup both show no OOM/kill records; auto-rerun triggered) |
github-actions
Bot
added
ci:real
|
A required check is failing on the current head:
|
github-actions
Bot
added
ci:infra
github-actions
Bot
removed
the
ci:infra
|
2 participants
Refs #3001
Summary
Codifies how external reports are handled. Contract text only — no runtime, no scripts, no tests.
#3001is referenced rather than closed so a maintainer credits it after reading; every acceptance criterion is met by this diff.Why
On #3000 I asked the reporter the one question that would shape the design — is the project's pinned tool version statically readable? — and then dispatched a fixer before the answer arrived.
The answer invalidated the brief's central premise. That project's
gradle/libs.versions.tomlcarriesktlint = "14.2.0", which is the ktlint-gradle plugin version, not a ktlint CLI version; the CLI (1.5.0) is transitive from the plugin's default and nothing setsKtlintExtension.version. The briefed remedy — read the declared version, compare, decline on skew — would have compared14.2.0against a resolved1.8.0and reported an enormous skew that does not exist.A confidently wrong claim is worse than the silence the fix exists to remove: it sends someone hunting a mismatch that is not there, and it would be least reliable on a fresh clone, which is exactly when it would fire. The correction cost a mid-flight
plegma_sendand rework that waiting about ten minutes would have avoided.What the reporters contributed, which is the other half of the argument
package.jsonrange is not a version either.Three in one day is why the last rule says to cite a reporter's reasoning as authority rather than paraphrase it.
The change
AGENTS.md, under "Issue triage (standing rule)" — four bullets added, no existing rule altered:.claude/skills/merge-train/SKILL.md— a pointer section only, plus the train-specific consequence (an external lane's first dispatch is often worth delaying by one exchange). The contract stays single-sourced in AGENTS.md, per the repo's rule that skills point and never duplicate.No numbered defect shape is added. This is process contract rather than a defect shape, and the catalog counter is currently contended by open PRs #2995, #2987, #2988 and #2913 — adding a number here would force another renumbering round.
Tests
No new tests. This PR adds no code and no detector, so there is no guard to prove red-first and nothing to mutate.
.claude/**is excluded from every vitest project, so no suite scans the skill text.The one governance test that reads these paths is
tests/config/label-manifest-coverage.test.ts, run below.Blast radius
AGENTS.md— four bullets appended inside an existing list. No existing bullet changed..claude/skills/merge-train/SKILL.md— one new section before "Filing issues (orchestrator)". No existing section changed..changelog/3001-external-report-triage.md— new fragment.Observability
No new failure path and no record added: this change contains no executable lines.
Verification
npm run buildnpx markdownlint-cli2 --no-globs AGENTS.mdnpx markdownlint-cli2 --no-globs .claude/skills/merge-train/SKILL.mdnpm test -- --run tests/config/label-manifest-coverage.test.tsgit log origin/master..HEAD --format=%s | grep -i -E 'closes|fixes|resolves'Not run, and why
The full
tests/configlane was not run in this worktree — those tests belong to named vitest projects rather than the default one, and rather than guess a project selector I ran the single governance file that actually reads these paths. CI runs the whole lane and is authoritative. The full 1,095-file population was not run and is not warranted for a prose-only diff.Reported honestly rather than implied green: the only suite executed locally is the one named above.