[docs] AGENTS: 2 load-bearing lessons (identifier verification + RFC self-falsifying)#67
Merged
Merged
Conversation
PR #56 + PR #61 (both merged 2026-05-18/19) discovered two falsehoods inherited from earlier scaffolding: CODEOWNERS routed to a @TraceCoreAI/maintainers team that did not exist (gh api returned 404; GitHub silently ignores the routing) and SECURITY.md cited a security@tracecore.ai mailbox that was not provisioned (reporters following the doc reached a black hole). Both propagated through multiple governance docs before user pushback caught them. The cure is a 30-second existence check before echoing a named identifier as fact: gh api for teams, dig MX (or maintainer confirmation) for mailboxes, [ -f path ] for file references. Add this as a load-bearing lesson so the bug class doesn't recur the next time someone copies a scaffolded reference. Signed-off-by: Tri Lam <trilamsr@gmail.com>
…ents PR #54's first RFC-0008 draft asserted depguard rules that did not exist in .golangci.yml yet, and a chart-appversion CI gate that checks only non-empty (not drift against binary tag). Both claims were aspirational. Second-pass review caught them; the fixes were (a) add the four depguard deny rules to .golangci.yml in commit ae47617 alongside the RFC text, and (b) soften the chart-appversion claim + add the drift gate to FOLLOWUPS.md § "M3 release-pipeline hardening" with M21 trigger. Capture as a load-bearing lesson so the bug class doesn't recur: every "X gate enforces Y" line in an RFC body must be verifiable in the current tree, or labeled as deferred / aspirational with the trigger condition spelled out. Signed-off-by: Tri Lam <trilamsr@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures two load-bearing lessons surfaced during this conversation's PR cycles, via the
learn-from-mistakesskill's full capture flow (format-check + banned-vocab + diff approval + DCO commit).Verify named identifiers exist before echoing them as fact in repo docs. PR [docs] M6: docs/maintainership.md + doc-check banned-phrase + section lints #56 + PR [docs] SECURITY: promote Advisory link, drop non-delivering mailbox #61 caught two inherited falsehoods:
CODEOWNERSrouted to a non-existent@TraceCoreAI/maintainersteam (GitHub silently ignores), andSECURITY.mdcited an unprovisionedsecurity@tracecore.aimailbox. A 30-secondgh api/dig MX/[ -f path ]check before landing the reference is the cure.RFC commitments must be self-falsifying. PR [docs] RFC-0008 auto-update boundary + close NORTHSTARS OQ #2 (M23) #54's first RFC-0008 draft asserted
depguardrules that didn't exist yet, and achart-appversiondrift gate that only checks non-empty (not drift). Rule: every "X gate enforces Y" line in an RFC body must be verifiable in the current tree, or labeled deferred with the trigger condition.What this PR changes
AGENTS.md: 2 new bullets under § "Load-bearing lessons" (entries 5 and 6 of the 6 universal rules). 113 → 128 lines, still under the documented 150-line cap.Test plan
wc -l AGENTS.md= 128 (under 150 cap)bash scripts/doc-check.shexits 0learn-from-mistakescapture flow)