ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source)

[kyle-sexton]

Category: CI gate (umbrella) · Source: control-tower gap-hunt 2026-07-19 (signal mining)

Pattern — 19 open issues, one root cause, zero prevention

Skills declared ecosystem/forge/tracker-agnostic ship hardcoded stack/forge/branch/marketplace-internal defaults. Members: #404 #405 #406 #408 #410 #412 #415 #416 #418 #421 #422 #423 #428 #429 #432 #438 #439 #441 #442.

Root cause: agnosticism is asserted in prose, never enforced. This is also the dominant review-churn class — the external reviewer re-catches instances on PR after PR (#467 branch/remote ×4, #453 seam-conditional eval, #491/#492 .NET-flavored examples) — meaning the pipeline pays for the same defect class repeatedly at review time instead of once at gate time.

Note: #445's CI-gate backlog covers mechanical conformance only (CHANGELOG/version/frontmatter) — it does NOT cover coupling.

Proposed fix

New ci.yml lane: grep agnostic-flagged skills for coupling tokens (dotnet, Clean Arch, origin/main, gh api, raw.githubusercontent, marketplace-internal names, …), silent-skip-gate shape per #445. Allowlist mechanism for legitimately guarded forward refs (the #412 disposition: presence-gated refs are FINE — the gate must distinguish guarded from bare).

Design questions for triage:

• How does a skill declare its agnosticism scope (frontmatter field vs directory convention)? The declaration is the gate's contract.
• Token list ownership: starts curated, should grow from review findings (every reviewer re-catch of this class = a missing token — closing the loop makes the gate self-improving).

Leverage

Kills a 19-issue class wholesale + the top review-churn source; prevention instead of 19 hand-fixes plus indefinite future recurrence.

Relations

Members above; #445 (sibling gate backlog); #412 (guarded-forward-ref disposition the gate must honor); #491/#492 (todays hand-fixes this gate would have made unnecessary).

Additional members (cluster-routed here at historic-normalization triage, cycle 7)

• claude-ops:morning-brief: Queues section label set hardcoded to melodic-software taxonomy — parameterize or degrade like the telemetry-issue path #610 (claude-ops:morning-brief Queues section hardcodes the four queue labels) — self-identified in its own body as "likely folds into ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531's lint-lane scope."
• portability gate: escape-hatch grammar rigor — standalone-comment-only matching + required nonempty reason (pair from PR #609 re-review) #624 (portability gate escape-hatch grammar rigor, PR feat(ci): add portability-lint gate for ecosystem/forge-agnostic skills (#531) #609 re-review pair) — explicitly deferred together with ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 items 1-2's operator-convention ratification.
• work-items:work: dispatch brief unconditionally imposes per-plugin version-bump/CHANGELOG obligations even when installed in a non-plugin consuming repo #636 (work-items:work dispatch brief imposes plugin-repo obligations in non-plugin consuming repos) — self-identified as "likely folds into ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 (portability lint) enforcement and/or convention: codify batch-1 operator precedents — two-lane defaults (discover via setup, never pre-prescribe) + built-in-first customization gate #557."

[kyle-sexton]

This was generated by AI during triage. · Category: CI gate (umbrella) · Priority: priority: high (kills a 19-issue coupling class wholesale + the dominant review-churn source — prevention over 19 hand-fixes + indefinite recurrence). Routed needs-human + wayfind: design.

Why needs-human

The direction (a ci.yml lane that greps agnostic-flagged skills for coupling tokens, silent-skip-gate shape) is sound, but two design decisions are the gate's actual contract and must be set by the maintainer:

1. How a skill declares its agnosticism scope — a frontmatter field vs a directory convention. This declaration IS the gate's contract; everything keys off it.
2. Token-list ownership + growth — starts curated (dotnet, Clean Arch, origin/main, gh api, raw.githubusercontent, marketplace-internal names, …); should grow from review findings so every reviewer re-catch becomes a new token (closing the loop makes the gate self-improving). The ownership/growth mechanism is a design call.

Plus cross-repo placement: the lane shape follows #445 and likely lives in melodic-software/ci-workflows (per cross-repo ownership).

Critical correctness constraint

The gate MUST distinguish guarded cross-references (presence-gated forward refs — the #412 disposition ruled these FINE) from bare ones. A gate that flags guarded refs would fight the correct pattern. The allowlist/guard-detection mechanism is part of the design.

Relationship to the 19-issue class (NOT a blocking carrier)

Members #404/#405/#406/#408/#410/#412/#415/#416/#418/#421/#422/#423/#428/#429/#432/#438/#439/#441/#442 are the individual coupling instances — several already triaged ready this session (#405/#412/#416/#418/#422 get hand-fixed now). #531 is the prevention that stops recurrence; it does not block the members. Cross-link, don't gate.

Relations: #445 (sibling mechanical-conformance gate), #412 (guarded-ref disposition the gate must honor), #491/#492 (today's hand-fixes this gate would obviate).

[kyle-sexton]

Decision brief (2-minute read)

Problem. Nineteen open issues share one root cause: skills declared ecosystem/forge/tracker-agnostic ship hardcoded stack, forge, branch, or marketplace-internal defaults, because agnosticism is asserted in prose and never enforced mechanically. This is also the top review-churn class — the external reviewer re-catches instances PR after PR, so the pipeline pays for the same defect at review time instead of once at gate time.

Today. The agnosticism contract lives in docs/PLUGIN-PHILOSOPHY.md "Design boundary" (lines 8–33): runtime behavior must not depend on publisher names, org env vars, repo names, or absolute paths, and "a bare unguarded cross-plugin reference is a defect" (lines 27–29), which already draws the guarded-vs-declared distinction #412 turns on. Enforcement is partial, not absent: ci.yml's machine-specific-paths lane (lines 120–127) already mechanically catches the absolute-path slice. What is missing is any check for stack/forge/branch/marketplace coupling tokens, and any machine-readable way for a skill to declare its agnosticism scope — that declaration is the gate's contract. A precedent for the declaration already exists: the "Cross-platform contract" permits a plugin to declare "a narrower, inherent platform boundary" (line 242). CI adds lanes by appending a job and listing it under ci-status.needs (lines 360–391); the silent-skip-gate lane (lines 234–245, scripts/check-silent-skips.sh) is the working template for the grep-tripwire-plus-annotated-exemption shape this gate would follow.

Options.

• A — RECOMMENDED: incremental, declaration-first. Land the scope-declaration contract first (reuse/extend the philosophy's existing "narrower, inherent platform boundary" mechanism rather than inventing a new frontmatter field), then grow enforcement one token-class at a time from a curated seed list (dotnet, Clean Arch, origin/main, gh api, raw.githubusercontent, marketplace-internal names). The gate must distinguish guarded/presence-gated refs (FINE, per toolchain: dotnet.md references dotnet-msbuild:* plugin skills that do not exist in this marketplace #412) from bare ones, mirroring check-silent-skips.sh's annotated-exemption escape hatch, and honor a declared narrower scope so a legitimately GitHub-locked skill under a neutral name is not falsely flagged (the source-control: pull-request + babysit-prs are gh/GitHub-locked with no forge seam, under a forge-neutral plugin name #441 exemption). Tradeoff: slower to full coverage, but each class ships proven against real corpus, false positives surface one class at a time, and the token list becomes self-improving as every reviewer re-catch closes back into a new token. Future-state risk: low — a curated list can lag novel coupling, mitigated by the review-feedback loop. Reversibility: high — per-class lanes are independently removable. Rationale: the contract is the load-bearing decision and deserves to be settled before mass enforcement; partial enforcement already exists to extend, not replace.
• B — big-bang lane. One new lane enforcing the full token list against all agnostic-flagged skills at once. Tradeoff: fastest to coverage but a wall of initial failures to triage, and the declaration contract must be fully right on day one or it fights correct code. Reversibility: medium.
• C — convention-only. Strengthen the philosophy prose and rely on review to catch instances. Tradeoff: zero build cost, but this is the status quo that produced the 19-issue class and the review churn — it does not stop recurrence. Not recommended.

Open design question (do not pre-decide): placement. Per the org cross-repo ownership rule, reusable Actions execution belongs in melodic-software/ci-workflows with only the wiring in this repo's ci.yml. Whether the coupling detector is a ci-workflows composite action (like the other lanes) or a repo-local script (like silent-skip-gate) is a design call, not a settled fact.

Related.

• source-control: pull-request + babysit-prs are gh/GitHub-locked with no forge seam, under a forge-neutral plugin name #441 — recommends a declared-GitHub-scope exemption; the gate's scope-declaration must support exactly this narrower-boundary case.
• toolchain: dotnet.md references dotnet-msbuild:* plugin skills that do not exist in this marketplace #412 — ruled guarded/presence-gated forward refs FINE; the gate must not flag them.
• CI-gate backlog: automatable conformance checks surfaced by the #313 fleet audit #445 — sibling CI-gate backlog, mechanical conformance only (CHANGELOG/version/frontmatter); explicitly does not cover coupling.
• quality-net: skill changes ship with zero regression detection — 120 evals.json unexecuted, skill-quality:check uninvoked (staged eval/gate/pass^k umbrella) #530 — sibling umbrella; owns absent signal (evals/gates never wired). Different class — cross-link, no overlap.
• convention: false-green checks — surfaces report success while the capability is dead or findings invisible (liveness-assertion umbrella) #532 — sibling umbrella; owns false signal (checks that run green but lie). This issue is a different axis (coupling), not liveness — cross-link only.
• Members implementation: Clean-Architecture layer vocabulary baked as universal execution order #404/implementation: .NET-only marketplace-skill references in every mode context (origin coupling, low severity) #405/implementation: TDD-by-default fires when consumer CLAUDE.md is silent — no userConfig toggle #406/discovery: ecosystem-discovery table is a closed set with no consumer-extension seam #408/toolchain: publisher org/repo/branch URL propagates into consumer-tracked .claude/ecosystems/*.yaml headers #410/toolchain: dotnet.md references dotnet-msbuild:* plugin skills that do not exist in this marketplace #412/planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415/planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416/planning: plan close-out and tracker-write phases emit gh-hardcoded tracker writes; close-out hardcodes docs/adr + docs/specs #418/verification: .NET/Blazor globs shipped as "portable defaults" — silent-skip for non-.NET consumers #421/verification: bare unguarded cross-plugin references to dotnet-*/cloudflare plugins in measure contexts #422/verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423/testing: evals grade against the private source monorepo's layout and house test stack (+ ghost testing.md ref) #428/testing: C#/.NET idioms are the fallback defaults and only worked examples in ecosystem-agnostic skills #429/session-flow: topic-docs placement contract resolved via hardcoded raw.githubusercontent URL instead of bundled copy #432/source-control: babysit worktree pruner hard-depends on ghq (undeclared, author-personal repo-layout tool) #438/source-control: PR-body "Generated with Claude Code" attribution is unconditional — no trailer_policy-equivalent seam #439/source-control: pull-request + babysit-prs are gh/GitHub-locked with no forge seam, under a forge-neutral plugin name #441/source-control: remote name origin hardcoded in pull-request create flow (low severity) #442 — individual instances; this is prevention, cross-link not block.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 3; relayed).

ACCEPTED — the decision brief's RECOMMENDED option verbatim.

Re-intake: removing needs-human, adding priority: needs-triage for routing.