chore(830-lint-static-analysis-gaps): prune epic brief now that the topic is fully landed

[kyle-sexton]

Summary

docs/topics/lint-static-analysis-gaps/PLAN.md is a contract-tier topic doc per docs/conventions/topic-docs/README.md: committed on the task branch only, pruned before merge once the topic's outcome lands (§"Contract-slice lifecycle"). It was added by PR #829 and never pruned. Epic #830 and all 6 sub-issues (#831-#836) plus the related setup-lifecycle epic (#837) are now merged and closed, so the topic's outcome has fully landed — pruning now, mirroring the same fix already applied to #836's leaked plan doc in PR #966.

Content preserved for the record (from commit 4a289ab389, PR #829):

Epic Brief (pruned)

Lint / static-analysis gaps

Brief

TLDR

Close the fleet's lint/static-analysis gaps with one epic in this repo (typos hook plugin, Go
coverage in both lanes, lychee-offline + pyright batch additions, .NET runtime guard,
hook-observability convention, bespoke-guard routing), plus two epics owned elsewhere
(setup-lifecycle convention here as its own design effort; standards adoption sweep +
ecosystem-declaration in melodic-software/standards).

Goal

Local lanes catch what CI gates, so agents fix findings at edit time instead of burning
commit–push–CI round-trips. Every addition follows the plugin philosophy: consumer-config-driven,
zero shipped opinions, runtime detection over assumptions, advisory hooks that auto-fix silently
and surface only residual unfixables.

Epic sub-items (discuss-first honored — file only on explicit request; epic + sub-issues shape):

1. typos hook plugin — per-file autofix (typos -w), consumer _typos.toml ancestor walk-up,
   false-positive remediation via consumer allowlist entries (extend-words /
   extend-identifiers / extend-ignore-re), advisory residual-only context, hook-precision +
   hook-telemetry conventions.
2. Go coverage, both lanes — new go batch ecosystem default (golangci-lint v2, format,
   go mod tidy; govulncheck optional) and a Go format hook plugin. Formatter selection
   (gofmt / goimports / gofumpt / golangci-lint fmt) is an implementation-time field survey per
   the pick-for-the-problem discipline; criteria: official/authoritative, maintained,
   feature-fit. golangci-lint is batch-only by design (package-scope analysis, per its FAQ).
3. lychee-offline added to cross-cutting.yaml (on-disk link/anchor integrity; gating in CI,
   no network).
4. pyright added to python.yaml check-cmd (CI gates it; local batch was ruff-only).
5. .NET batch guard — dotnet ecosystem entry detects analyzer/.editorconfig configuration
   presence at runtime each run; skips with a visible notice when absent. No assumptions about
   consumer state; .NET stays batch-lane only.
6. Hook-observability fleet convention — every fleet hook emits statusMessage (during run),
   systemMessage (failure/notable action), and the hook-telemetry OTel envelope. Grounded in
   current official hooks docs at authoring time (no native user-visible hook UI exists as of
   2026-07-21; OTel events + author-emitted messages are the sanctioned surfaces). Optional
   sub-item: upstream feature request for a native verbose-hooks UI toggle.
7. Bespoke CI guards (comment-hygiene, exec-bit, machine-specific-paths,
   reference-integrity) — sub-issue routed to ci-workflows/standards: local lane must invoke
   the same owned source (pointer-not-copy), which needs a small distribution decision those
   repos own.

Constraints

• Plugin philosophy governs: repo/user/machine/org-agnostic, two-lane convention posture,
  native-first, cross-platform (Windows/macOS/Linux), setup contract, graceful degradation.
• Lane rule (locked): fast (<~2s), per-file, auto-fixing, consumer-config-discovering tool =
  hook plugin; slow / repo-wide / package-scope tool = toolchain batch entry; both when both fit.
• Hooks auto-fix silently, never block, surface only residual unfixables (markdown-format
  pattern); hook-precision convention bounds false-positive noise.
• New plugins conform to the setup-lifecycle convention once that epic lands.

Acceptance criteria

• Each epic sub-item lands as its own planned change with the normal pipeline
  (explore/research → plan → implement → review).
• typos + Go hook plugins pass the plugin contract gate and fleet conformance audit.
• Batch additions (go, lychee-offline, pyright, dotnet guard) are rung-4 defaults only —
  consumer .claude/ecosystems/*.yaml override ladder unchanged.
• Hook-observability convention documented as an owner doc (convention registry row) and adopted
  by every fleet hook; conformance audited.
• CI/local parity: gaps identified 2026-07-21 (Go toolchain, lychee-offline, pyright) have local
  coverage.

Captured assumptions

• No work-machine tool-install restriction (winget/brew acceptable). User to correct if wrong.
• Single Go repo today (ci-runner); Go hook plugin justified by completeness preference
  (user choice) despite one consumer.

Out of scope

• Standards distribution-model redesign — model is settled (ADR-0001, accepted 2026-07-10);
  dissatisfaction, if it persists after reading the ADR rationale, is an ADR-supersede
  discussion in standards.
• Consumer-config adoption gaps (ruff/pyright targets, dotnet-analysis to itinerary-planner /
  medley, TS/JS component admission, medley lychee) — standards epic below.
• Setup-lifecycle convention design — own epic below.

Deferred questions

• YAML lint/format plugin — arbiter: USER-RESERVED. Trigger: a CI YAML gate lands in the fleet,
  or Biome ships YAML support (unshipped as of the 2026 roadmap). Facts: yamllint validate-only;
  yamlfmt autofixes but imposes defaults without consumer config.
• gitleaks per-edit hook — arbiter: USER-RESERVED. Trigger: a local leaked-secret incident.
  Facts: dir mode (detect/protect deprecated v8.19), entropy false-positive noise, no autofix.
• dotnet format whitespace --folder fast path — arbiter: USER-RESERVED. Whitespace-only today
  (bypasses MSBuild/restore; the only sub-2s path — full/style/analyzer modes pay project-load,
  ~1.3s minimum single file). Links: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format,
  Slow performance for --include with single file dotnet/format#757. Trigger: an MSBuild-free style/analyzer path
  appears upstream.
• Upstream feature request for native verbose-hooks UI — arbiter: /planning:plan (optional
  sub-item of the observability convention).

Related epics (owned elsewhere)

• Setup-lifecycle convention (this repo, own design session) — DONE (Epic: setup-lifecycle convention (verbs, per-skill vs plugin setup, philosophy update) #837, PR docs(philosophy): lock setup-lifecycle convention #990).
• Standards adoption sweep + ecosystem-declaration enhancement
  (melodic-software/standards) — still open, separate repo (standards#230).

Plan

(Empty — /planning:plan fills this per epic sub-item.)

Verification

• git rm -r only — no other changes; no build/test impact.
• Content fully preserved in git history (commit 4a289ab389) and in this PR body.

Related

No linked issue — epic #830 is already closed (manually, since all 6 sub-issues plus the related setup-lifecycle epic #837 were done); this is a follow-up hygiene fix, not new epic work. Related PRs: #829 (added the brief), #966 (same fix applied to #836's leaked plan doc), #990 (#837, the last related item to land before this cleanup).

[claude]

Claude finished @kyle-sexton's task in 1m 18s —— View job

---

PR Review — chore(830-prune-epic-brief)

• Gather context and understand the change
• Check for dangling references to the deleted file
• Verify directory state after deletion
• Confirm alignment with topic-docs lifecycle convention
• Post final review

---

Verdict: Approve. This is a clean lifecycle prune with one minor observation worth noting.

What changed

Pure deletion — docs/topics/lint-static-analysis-gaps/PLAN.md (111 lines), no other files touched. The docs/topics/lint-static-analysis-gaps/ directory is now empty and will disappear from the tree, which is correct behavior in git.

Alignment with convention

The PR body correctly cites § "Contract-slice lifecycle" in docs/conventions/topic-docs/README.md: topic plan docs are committed on the task branch only and pruned once the topic's outcome lands. Epic #830 + all sub-issues (#831–#836) and the related #837 are closed; the prune is overdue and warranted. Mirrors the same fix from PR #966.

Content is durably preserved in git history at commit 4a289ab389 and in this PR body — nothing is lost.

One observation: stale path in CHANGELOG

plugins/toolchain/CHANGELOG.md:17 contains:

Per Brief item 3, `docs/topics/lint-static-analysis-gaps/PLAN.md`. Closes #833.

That path is now a dead reference. This is a changelog entry (historical record of what informed the change at authoring time), so a dead path here is low-severity — it doesn't break anything and the content is traceable through git. No action required, but it's worth being aware that future readers following that path will find it gone. A git-history note in the PR body (already present) is the right mitigation.

No concerns

• Scope is exactly as claimed: one file deleted, zero other changes.
• No build or test impact.
• No plugin manifests, skill files, or settings reference this path.
• PR title, branch name, and commit message follow the Conventional Commits convention enforced by .github/workflows/pr-title.yml.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2876e99313

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 42s —— View job

---

PR Review — chore(830-prune-epic-brief)

• Review the updated diff (commit cc74066)
• Verify the CHANGELOG fix addresses the dangling reference
• Confirm full PR is clean and ready to merge

---

Verdict: Approve. The follow-up commit addresses the one open observation from the initial review.

What changed across both commits

Commit	Change
2876e99	Delete docs/topics/lint-static-analysis-gaps/PLAN.md (111 lines) — the lifecycle prune
cc74066	Fix the dangling PLAN.md path in plugins/toolchain/CHANGELOG.md

CHANGELOG fix (cc74066)

plugins/toolchain/CHANGELOG.md:17:

- Per Brief item 3, `docs/topics/lint-static-analysis-gaps/PLAN.md`. Closes #833.
+ Per epic #830 ("lint/static-analysis gap closure"), sub-issue #833.

The dead file path is replaced with a durable issue/epic reference. Issue numbers are permanent identifiers in GitHub; they survive directory restructuring and cleanup passes. The replacement also drops "Brief item 3" — a label that only made sense relative to the deleted document — and substitutes the self-describing epic name. No information is lost; the attribution is now more discoverable, not less. This directly addresses the Codex P2 finding and the observation in the prior review.

No remaining concerns

• Scope matches the PR description: two files, one deletion, one one-line CHANGELOG fix.
• No plugin manifests, skill files, or settings reference the deleted path.
• Both commit messages follow Conventional Commits (enforced by .github/workflows/pr-title.yml).
• Content preserved in git history at commit 4a289ab389 and in the PR body.