portability lint stage 3: stack/ecosystem opinion token class (child of #531)

[kyle-sexton]

This was generated by AI during triage (decomposition intake, rule 8f).

Part of #531.

Scope (from the control-tower plan comment on #531)

Stack/ecosystem opinion class: baked stack defaults in agnostic-flagged skills — dotnet / .NET, Clean-Architecture layer vocabulary, C#/Blazor globs shipped as "portable defaults." Mostly prevention (advances rather than retires open members): these need a userConfig seam, not a token removal.

Acceptance criteria

• Same lane discipline as Stages 1–2.
• Fixtures proving the stack/ecosystem token class is flagged where undeclared and honored where a userConfig seam declares it.

Prerequisite

Depends on Stage 2's declaration reader (portability lint stage 2: forge/branch/remote grammar class + plugin-scope declaration, child of #531) — do not start until that lands.

STOPGAP NOTE: plain child issue pending the #552 native sub-issues convention — convert when #552 lands.

[kyle-sexton]

This was generated by AI (decide lane — decision-brief pass).

Decision brief (2-minute read)

Problem. Stage 3 must define the stack/ecosystem opinion token class for the portability lint — what counts as a baked ecosystem default an agnostic-flagged skill must not ship (.NET/dotnet, Clean-Architecture layer vocabulary, C#/Blazor globs), and how that class is specified and exempted. The engine, token file, and declared-scope seam already shipped on main, so this is a ratify-and-sequence call on the class definition, not a greenfield design.

Today (verified against main).

• The engine is live: scripts/check-skill-portability.sh + scripts/skill-portability-tokens.txt + scripts/check-skill-portability.test.sh (the portability-lint job in ci.yml, shipped by PR feat(ci): add portability-lint gate for ecosystem/forge-agnostic skills (#531) #609). Ground truth is the code on main — note portability lint stage 1: cross-plugin bare-ref gate engine (child of #531) #612/portability lint: branch-class gate engine — origin/(main|master) token class + engine skeleton (child of #531, delivered by PR #609) #620 tracker state lags.
• The stack/ecosystem class already exists, STAGED (commented) in skill-portability-tokens.txt under --- STAGED ---: # dotnet, # \bClean Arch(itecture)?\b. It carries its own enable-trigger (".NET-example members land + an --all audit shows agnostic skills clean").
• Specification model is fixed and reusable: each token is one ERE pattern (data, not logic — a reviewer re-catch is a one-line data add). Exemption seams already shipped: a whole-file portability-scope: <reason> declaration excuses ecosystem-specific plugins (check-skill-portability.sh:141), a per-site portability-ok: <reason> excuses one line, and is_guarded() (:159) auto-recognizes guarded uses.
• Three activation constraints are already documented in the token file / script and are load-bearing for this class:
  1. The staged tokens are currently broken. \bdotnet\b / \bClean Arch\b rely on \b, which POSIX ERE does not define; on gawk and mawk/nawk \b matches a literal backspace, so these patterns match nothing (gate stays green while missing every violation). Must rewrite POSIX-safe before activating, e.g. [Dd]otnet or (^|[^a-zA-Z0-9_])dotnet([^a-zA-Z0-9_]|$).
  2. dotnet is high-volume: 56 corpus files today. Naive activation false-flags en masse; ecosystem-specific plugins must first declare portability-scope, and agnostic ones need a userConfig seam. Changed-file scoping means it never red-lines main — it forces fix-or-declare on the next edit.
  3. is_guarded() markers are branch-class-scoped only (symbolic-ref / merge-base / origin-HEAD evidence). This class needs its own class-scoped guard markers for legitimate optional-dependency presence (e.g. "requires the dotnet CLI"); a generic "if using" must never guard a bare hardcode (:151–:159).

Blocked assessment (task's hypothesis, tested against evidence). Stage 3 is not blocked on the umbrella #531 framework: the operator ACCEPTED Option A verbatim on #531 (declaration-first, grow one token-class at a time), and the engine is live. So "defer until #531's framework is decided" has no live premise and is deliberately not offered below. The real dependency is an activation gate, not a definition gate — this issue can settle the definition now while sequencing enable-flip behind: (a) #713's declaration-mechanism ratification (the reader shipped in code but the decision is still needs-decision), and (b) the corpus prerequisites in constraints 1–3 above.

Options.

• A — RECOMMENDED: high-precision ecosystem literals, activated one token at a time behind the documented gates. Define the class as the narrow, low-ambiguity set — [Dd]otnet, C#/Blazor file-extension/glob literals (.razor, .csproj, Blazor globs) — written POSIX-safe (never \b), kept in the existing --- STAGED --- block of skill-portability-tokens.txt, with a class-scoped optional-dependency guard marker added to is_guarded() and portability-scope: as the ecosystem-plugin exemption. Flip each token from staged→active only after its --all corpus audit is green and the dotnet cohort's seams/declarations land. Tradeoff: slower to full coverage, but every token ships proven against the real corpus and false positives surface one class at a time. Reversibility: high — data-only, per-token, independently removable. Rationale: reuses the shipped engine wholesale, honors the ratified one-class-at-a-time rollout, and draws the class boundary where precision is defensible.
• B — broad definition including Clean-Architecture layer vocabulary in prose. Add Clean Arch(itecture)? and layer-name tokens alongside the literals. Tradeoff: wider coverage, but layer vocabulary appears legitimately in architecture skills and prose, so it is a high false-positive class — it wants a portability-scope declaration convention and a corpus audit before it can activate, and risks the gate fighting correct content. Reversibility: medium. Fold the vocabulary token in only after the literals prove the seam works.
• C — prevention-only (leave staged as documented intent). Keep the class commented, never activate, and rely on the userConfig-seam member issues to fix instances by hand. Tradeoff: zero build cost, but this is effectively the status quo that produced the coupling class — no mechanical forcing function. Not recommended.

Enabling tokens is prevention/advances, not member closure: #405 / #406 / #421 / #428 need a userConfig seam built (separate work); the lint is the forcing function, not the fix. Fixtures: #404 / #429 (already closed).

Cross-links.

• ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 — parent umbrella; Option A ratified there; this is its Stage 3 (stack/ecosystem class), the last staged token set in skill-portability-tokens.txt.
• portability lint stage 2: forge/branch/remote grammar class + plugin-scope declaration (child of #531) #713 — sibling Stage 2; its declaration-mechanism decision (portability-scope: vs plugin.json keywords) is the reader this stage's ecosystem-plugin exemption rides on. Its brief recommends ratifying the shipped portability-scope: — the activation prerequisite here.
• issue-metadata conventions: operationalize native types, sub-issues hierarchy, dependencies, priority re-baseline, close-reason + documented conventions (umbrella) #552 — native sub-issues convention; portability lint stage 3: stack/ecosystem opinion token class (child of #531) #714 remains a plain STOPGAP child pending it (per this issue's own note), convert when issue-metadata conventions: operationalize native types, sub-issues hierarchy, dependencies, priority re-baseline, close-reason + documented conventions (umbrella) #552 lands.

(No #554 cross-link: #554 is the .work gitignore/control-surface issue, not a convention-template — it does not touch this token class.)

[kyle-sexton]

Operator ruling (ratification interview, 2026-07-22 ~03:05Z): RATIFIED as-is — no bulk activation. The external token data file (scripts/skill-portability-tokens.txt) + staged per-token rollout is the standing extension mechanism. Staged \bdotnet\b / \bClean Arch\b entries stay staged: POSIX ERE has no \b (patterns currently match nothing) and dotnet hits 56 corpus files. Per-token activation only after POSIX-safe rewrite + green --all audit + class-scoped guard marker, as this issue sequences. Applied by control tower; flipping to status: ready.