Skip to content

feat(governance): CODEOWNERS + lint-enforced principles + depguard#357

Merged
trilamsr merged 3 commits into
mainfrom
feat/governance-codeowners-and-principles
Jun 1, 2026
Merged

feat(governance): CODEOWNERS + lint-enforced principles + depguard#357
trilamsr merged 3 commits into
mainfrom
feat/governance-codeowners-and-principles

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

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%)

CODEOWNERS previously 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%.

  • Added a * default-owner line so anything not matched downstream still routes to @TraceCoreAI/core.
  • Added directory-scoped rules for every top-level source dir: module/, components/, internal/, install/, docs/, scripts/, tools/, bench/, python/.
  • Documented the layering convention at the top of the file (catch-all → directory → file-scoped; matched-last semantics). Sub-team splits land later when a second non-author maintainer joins, per 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 under install/). internal/ and tools/ exist and are included instead.

#323 — Lint-enforced principles (4/16 → 5/16)

Two complementary changes:

  1. PRINCIPLES.md gains 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.

  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). 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 lint but the upgrade-path to strict lint is left as follow-up rather than padded in here — gosec is already enabled and the linkage is the documentation, not a new rule.

Governance: CODEOWNERS now covers every top-level source directory
(module/, components/, internal/, install/, docs/, scripts/, tools/,
bench/, python/) — lifts measured O7 coverage from 0% to ~95%.
PRINCIPLES.md gains an Enforcement map table linking each numbered
principle to its lint rule / scripted gate. A new `pkg-private`
depguard rule lifts PRINCIPLES §6 to lint-enforced: new `pkg/`
subpaths require an RFC + explicit allowlist entry.

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.
  • Pre-commit make check ran on both commits — passed (golangci-lint, vet, mod-verify, attribute-namespace-check, no-autoupdate-check).
  • Negative test for the depguard rule: synthesized a module/pkg/foobar import in a transient throwaway file; lint fired with the expected PRINCIPLES §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.
  • Root go tool golangci-lint run ./... clean.
  • scripts/doc-check.sh clean.
  • depguard rule fires on a synthesized new module/pkg/foobar import.
  • depguard rule stays silent on every existing module/pkg/... caller.

Closes #322, #323.

Tri Lam 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>
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>
@trilamsr trilamsr merged commit 6677f54 into main Jun 1, 2026
11 checks passed
@trilamsr trilamsr deleted the feat/governance-codeowners-and-principles branch June 1, 2026 20:12
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[rc1-prep] CODEOWNERS coverage: add directory-scoped rules for all top-level source dirs

1 participant