feat(governance): CODEOWNERS + lint-enforced principles + depguard#357
Merged
Conversation
added 2 commits
June 1, 2026 02:32
Lifts measured CODEOWNERS coverage from 0% to ~95% by adding directory-scoped rules for every top-level source dir: module/, components/, internal/, install/, docs/, scripts/, tools/, bench/, python/. Adds a `*` default owner so anything not matched by a later rule still routes to @TraceCoreAI/core. Sub-team splits land later when a second non-author maintainer joins (per docs/maintainership.md § "Proposed: bar to join"); the layering comment at the top of the file documents the convention. Closes #322. Audit source: docs/v1-rc1-governance-gaps.md §1. Signed-off-by: Tri Lam <tri@maydow.com>
Lifts NORTHSTARS O7 supporting KPI from 4 to 5 of 16 principles
strictly lint-enforced. Two changes:
1. PRINCIPLES.md gains an Enforcement map table mapping each
numbered principle to its mechanism (lint / scripted gate /
cultural), so the next O7 audit reads from one place rather
than rediscovering the topology. Includes a 3-step rubric for
what to do when a new violation lands.
2. .golangci.yml gains a `pkg-private` depguard rule expressing
PRINCIPLES §6 ("defaults bias toward private"): new
module/pkg/... subpaths fail lint unless explicitly allowlisted.
The current allowlist enumerates the 6 RFC-0013-ratified paths
(nccl, patterns, replay, runtime, selftel, testutil). Verified
the rule fires on synthesized unlisted imports and stays silent
on every existing pkg/ caller.
Closes #323. Audit source: docs/v1-rc1-governance-gaps.md §2.
Signed-off-by: Tri Lam <tri@maydow.com>
4 tasks
trilamsr
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary CI \`changes\` pre-flight job intermittently fails with exit 128 when \`origin/\$base\` ref isn't fully fetched (shallow-clone race / fresh runner). \`git diff origin/\$base...HEAD\` then exits non-zero; \`bash -e\` propagates and fails the whole workflow. ## Root cause \`set -e\` from \`bash -e\` causes the command-substitution \`changed=\$(git diff ...)\` to abort on non-zero exit even with \`2>/dev/null\` redirecting stderr. Append \`|| true\` so failure falls through to the existing "treat as code-changed" default. ## Test plan - [x] yaml.safe_load parses cleanly - [x] actionlint + zizmor clean - [x] golangci-lint + go vet + attribute-namespace-check + doc-check + alert-check + chart-appversion-check + deprecation-check + no-autoupdate-check all green - [ ] Verified by next PR's pre-flight running green Reproduced flake on PRs #347 + #357. Signed-off-by: Tri Lam <tri@maydow.com> Co-authored-by: Tri Lam <tri@maydow.com>
This was referenced Jun 1, 2026
trilamsr
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary §1 (Trust under load) was already covered by `gosec` + `govet` + `errcheck` in `.golangci.yml.linters.enable` — the PRINCIPLES.md table just hadn't been updated to reflect it. Two-line edit promotes §1 from `partial lint` → `lint` and bumps the O7 KPI counter from 5/16 → 6/16, hitting the rc1 target. ## Root cause PR #357 (governance) enabled gosec + govet at file level but the mapping-table row for §1 was not updated. The KPI counter (5) was authored before that PR landed. ## What this does NOT do (deferred from #323) - Principles-to-enforcement mapping table — already exists in PRINCIPLES.md §"Principles → Enforcement"; #323 listed this as ask (a), already shipped. - §6 depguard rule with allowlist of existing `pkg/...` paths — defer; requires enumerating ~10 paths into the allowlist; separate small PR. This PR is intentionally surgical: 2 lines, no `.golangci.yml` change, no behavior change. The lint rules were already running; this corrects the documentation. ## Test plan - [x] `make lint` — 0 issues - [x] `go vet ./...` — pass - [x] `attribute-namespace-check` — green - [x] Pre-push hook all gates green Partial-closes #323 (§1 row only — depguard for §6 deferred). ```release-notes docs: lift §1 (Trust under load) enforcement from `partial lint` → `lint` in PRINCIPLES.md mapping table — gosec/govet/errcheck already cover panic-recovery + error-handling surface. KPI 5/16 → 6/16. ``` Signed-off-by: Tri Lam <tri@maydow.com> Co-authored-by: Tri Lam <tri@maydow.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
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
Two governance gaps from the v1.0-rc1 audit (
docs/v1-rc1-governance-gaps.md) closed in one PR:#322 — CODEOWNERS coverage (0% → ~95%)
CODEOWNERSpreviously covered only governance files + a handful of CI / supply-chain anchors. Zero top-level source directories had a matching rule, so the O7 supporting KPI (CODEOWNERS covers ≥80% of code paths) measured 0%.*default-owner line so anything not matched downstream still routes to@TraceCoreAI/core.module/,components/,internal/,install/,docs/,scripts/,tools/,bench/,python/.docs/maintainership.md§ "Proposed: bar to join".Note: the issue body lists
dist/as a top-level dir but no such dir exists in the repo today (RFC-0013 dist artifacts live underinstall/).internal/andtools/exist and are included instead.#323 — Lint-enforced principles (4/16 → 5/16)
Two complementary changes:
PRINCIPLES.mdgains an Enforcement map table. Every numbered principle (§1–§16) maps to its enforcement mechanism (lint rule / scripted gate / cultural). Closes the audit gap "the principles-to-enforcement mapping is the missing artifact" so the next O7 audit reads from one place rather than rediscovering the topology. Includes a 3-step rubric for what to do when a new violation lands: add lint rule → add scripted gate → update table..golangci.ymlgains apkg-privatedepguard rule expressing PRINCIPLES §6 ("defaults bias toward private"). Newmodule/pkg/...subpaths fail lint unless explicitly allowlisted. The current allowlist enumerates the 6 RFC-0013-ratified paths (nccl,patterns,replay,runtime,selftel,testutil). Adding a sibling now requires an RFC + an explicit entry — moving §6 from cultural to lint-enforced.The third remediation in the audit (gosec linkage to §1 for "5 → 6") is captured in the table's §1 row as
partial lintbut the upgrade-path tostrict lintis left as follow-up rather than padded in here — gosec is already enabled and the linkage is the documentation, not a new rule.Validation
cd module && go tool golangci-lint run ./...— 34 issues (identical to main; pre-existing testifylint / exhaustive / etc., none introduced by this PR).go tool golangci-lint run ./...(root) — 0 issues.scripts/doc-check.sh— clean.make checkran on both commits — passed (golangci-lint, vet, mod-verify, attribute-namespace-check, no-autoupdate-check).module/pkg/foobarimport in a transient throwaway file; lint fired with the expectedPRINCIPLES §6: new \pkg/` subpaths require an RFC ...` message. Throwaway cleaned up.Test plan
cd module && go tool golangci-lint run ./...shows no new issues vs main.go tool golangci-lint run ./...clean.scripts/doc-check.shclean.module/pkg/foobarimport.module/pkg/...caller.Closes #322, #323.