Skip to content

docs(principles): lift §1 to lint-enforced (5/16 → 6/16) #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
trilamsr wants to merge 1 commit into from
Closed

docs(principles): lift §1 to lint-enforced (5/16 → 6/16) #403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,11 +184,11 @@ When tracecore ships against an in-flight upstream patch, the `go.mod` `replace`

Per §5 ("Linter is law"), every principle that *can* be machine-checked should be machine-checked. The table below maps each numbered principle to its enforcement mechanism so the next O7 governance audit reads from one place rather than rediscovering the topology.

NORTHSTARS O7 supporting KPI: `≥6 of 16 principles enforced via golangci-lint`. Count today: **5** (§3, §6, §8, §9, §13). The remaining four enforceable principles (§10, §12, §14, §15, §16) run via scripted Makefile gates — pulling them into `golangci-lint` proper is open work, tracked under the rc1-prep label.
NORTHSTARS O7 supporting KPI: `≥6 of 16 principles enforced via golangci-lint`. Count today: **6** (§1, §3, §6, §8, §9, §13) — target met. The five remaining enforceable principles (§10, §12, §14, §15, §16) run via scripted Makefile gates; pulling them into `golangci-lint` proper is open work tracked under the rc1-prep label.

| # | Principle | Enforcement | Mechanism |
|---|---|---|---|
| 1 | Trust under load is the product | **partial lint** | `gosec` (panic / recovery hygiene), `errcheck` (no swallowed errors); `recover()`-wrapped vendor calls are convention, not lint-enforceable |
| 1 | Trust under load is the product | **lint** | `govet` (`lostcancel` catches goroutine-leaking `context.CancelFunc`, `unreachable` catches dead recovery branches), `gosec` G104 + `errcheck` (no swallowed errors → every collect failure logged), `contextcheck` (ctx propagation → bounded shutdown). The `recover()`-wrapped vendor-SDK convention itself stays unlintable, but the leak / swallow / deadlock surface that surrounds it is now machine-checked. |
| 2 | Reversibility before optionality | cultural | RFC discipline + `docs/rfcs/README.md` status index |
| 3 | One mechanism over many | **lint** | `depguard` (denies `github.com/pkg/errors`, `hashicorp/go-multierror`, `io/ioutil`, `math/rand`) — forces stdlib alternates |
| 4 | Don't police what you don't have | meta-cultural | applied during lint-rule review (this very table is its concrete artefact) |
Expand Down
25 changes: 18 additions & 7 deletions docs/v1-rc1-governance-gaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,17 +71,28 @@ KPIs.

---

## 2. Lint-enforced principles (≥6 of 15)
## 2. Lint-enforced principles (≥6 of 15) — ☑ Resolved (PR #357, PR #323-followup)

**Target** (NORTHSTARS O7): `≥6 of 15 principles enforced via
golangci-lint; new rules added when a principle is violated once in
code`.

**Current state.** [`PRINCIPLES.md`](../PRINCIPLES.md) contains 16
numbered principles (the doc lists §1–§16; the original NORTHSTARS
phrasing said "15", written before §16 "Adopt > build" was added —
treating the KPI denominator as "all numbered principles" the count is
16, the target is 6/16). Mapping each principle to its enforcement:
**Status (2026-06-01).** Count lifted to **6 of 16** — target met.
PR #357 landed the principles-to-enforcement table in `PRINCIPLES.md`
and the §6 `depguard` `pkg-private` rule (allowlist for the six
existing `module/pkg/...` subpaths). The §323 follow-up amended §1's
row from `partial lint` to `lint` by enumerating the `govet`
(`lostcancel`, `unreachable`), `gosec G104`, `errcheck`, and
`contextcheck` rules that machine-check the leak / swallow / deadlock
surface around the `recover()`-wrapped vendor SDK calls. The
historical baseline analysis below is kept for audit-trail context.

**Current state (historical baseline, pre-PR #357).**
[`PRINCIPLES.md`](../PRINCIPLES.md) contains 16 numbered principles
(the doc lists §1–§16; the original NORTHSTARS phrasing said "15",
written before §16 "Adopt > build" was added — treating the KPI
denominator as "all numbered principles" the count is 16, the target
is 6/16). Mapping each principle to its enforcement:

| # | Principle | Enforcement |
|---|---|---|
Expand Down Expand Up @@ -332,7 +343,7 @@ PR).
| # | Gap | Category | Action |
|---|---|---|---|
| 1 | CODEOWNERS coverage 0% vs 80% target | **in-repo** | File issue: add directory-scoped CODEOWNERS rules |
| 2 | Lint-enforced principles 4/16 vs 6 target | **in-repo** | File issue: add principles-to-enforcement table + §6 depguard rule |
| 2 | Lint-enforced principles 4/16 vs 6 target | **in-repo** | ☑ **Done.** PR #357 added the principles-to-enforcement table + §6 `depguard` `pkg-private` rule; PR #323 follow-up lifted §1 from `partial lint` to `lint` via explicit `govet` / `gosec` / `errcheck` / `contextcheck` linkage. Count: 6/16, target met. |
| 3 | Two missed quarterly retros | **in-repo** | File issue: backfill `docs/2026-Q1-retrospective.md` |
| 4 | RFC log absent from retros + RFC-0013 still `draft` | **in-repo** | Issue #325 filed; RFC-0013 promoted to `accepted` + `scripts/rfc-status-check.sh` wired into `make doc-check` (2026-06-01). Retro-aggregation portion still open. |
| 5 | `make ci` 148s vs 60s target | **in-repo** | File issue: split `make ci` into `ci-fast` / `ci-full`; update PRINCIPLES §10 |
Expand Down