portability lint stage 2: forge/branch/remote grammar class + plugin-scope declaration (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)

Extend the portability-lint engine's token set to the forge/branch/remote coupling class: origin/main, the origin remote name, gh / gh api forge-lock, Conventional-Commits branch grammar, and raw.githubusercontent / publisher-URL propagation. Add the declared-narrower-scope honor so a legitimately forge-locked plugin under a neutral name is exempt rather than falsely flagged.

Files: extend the Stage 1 orchestrator script + its test suite; new test fixtures per token; a short note in docs/PLUGIN-PHILOSOPHY.md.

Acceptance criteria

• Same lane discipline as Stage 1 (self-test-first, fail-closed, never silent-skips, shellcheck-clean, wired into ci-status.needs).
• New fixtures for each token class in scope.
• A fixture proving a declared-scope plugin is exempt while an undeclared one is flagged.
• The escape-hatch annotation token name finalized (currently a Stage-1 STOPGAP pending confirmation).

OPERATOR DECISION (unresolved — this stage is gated on it, not resolved here)

Plugin-scope declaration mechanism: how a plugin declares a narrower forge/stack lock so the gate exempts it. RECOMMENDED (from the #531 plan): read plugin.json's existing keywords field — no new frontmatter. Alternative: a dedicated declaration line or a per-plugin allowlist file. Also unresolved: the annotation token name (# portability-ok: <reason> STOPGAP vs. a confirmed/renamed final).

Prerequisite

Depends on the Stage 1 engine (portability lint stage 1: cross-plugin bare-ref gate engine, 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]

Decision brief (2-minute read)

Brief-writer lane — presents and recommends; the operator ratifies. No labels changed, nothing closed.

Problem. This stage extends the portability-lint engine to the forge/branch/remote coupling class and needs the plugin's agnosticism-scope declaration mechanism settled — the piece "declaration-first" was really about (the #441 forge-locked-under-neutral-name case). This issue's body carries two questions marked unresolved (the declaration mechanism, and the STOPGAP annotation token name), but the Stage 1 engine has since landed on main and already materializes an answer to both — so this brief is the planned formalization step the #531 plan called for ("finalize before Stage 2 hardens it"), not an open field.

What's verified today (cite paths).

• The engine is live on main at scripts/check-skill-portability.sh + scripts/skill-portability-tokens.txt + scripts/check-skill-portability.test.sh. (Tracker caveat: portability lint stage 1: cross-plugin bare-ref gate engine (child of #531) #612 is still OPEN, so treat the code on main, not the issue state, as ground truth.)
• The declaration mechanism already shipped is a dedicated whole-file comment, portability-scope: <reason> — not plugin.json keywords. The script header states it explicitly ("Scope declaration… no new frontmatter field") and the code greps for it: if grep -qE 'portability-scope:' -- "$file". This is the Alternative in this issue's body (a dedicated declaration line), not the body's stated RECOMMENDED (read keywords).
• keywords is a free-form string array — compatible with adding tokens, but already contaminated for lock-duty. It is populated for marketplace discovery with terms that overlap the forge/stack vocabulary: source-control → ["git","github","ci","code-review",…]; actionlint → ["github-actions",…]; biome-format → ["typescript","javascript",…]. A gate that read keywords as a scope-lock would auto-exempt source-control from all forge checks on the strength of its plain "github" discovery keyword — a false exemption. No collision exists with the dedicated portability-scope: token.
• The annotation token portability-ok: <reason> is already baked into the engine (script escape logic, token-file docs, test fixtures) but has zero skill-content occurrences — a code search surfaced it only in those 3 scripts/ files. It is a deliberate parallel to the established silent-skip-ok: <reason> convention (scripts/check-silent-skips.sh), which is used in real content (plugins/powershell-format/hooks/…, plugins/claude-ops/hooks/…).
• Note on the stale label: this issue body tags keywords as RECOMMENDED, but the ratified ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 language was "reuse/extend the philosophy's existing narrower-boundary mechanism" — the keywords phrasing is a stale artifact of the pre-Stage-1 plan.

Decision 1 — declaration mechanism.

• A — RECOMMENDED: dedicated whole-file portability-scope: <reason> comment (what Stage 1 shipped). Merits first: collision-free (a reserved token, unlike keywords), reviewer-visible in the diff at the point of exemption, and it sits at file granularity where an inherent forge/stack lock actually lives (the source-control: pull-request + babysit-prs are gh/GitHub-locked with no forge seam, under a forge-neutral plugin name #441 case). Cost of the alternative it beats: keywords carry overlapping discovery terms, so a keywords lock would need a reserved sub-namespace (e.g. forge:github) to avoid false auto-exemptions — extra machinery for no gain. Reversibility: high (a grep token; removing it is a one-line data/logic change). Ratifying also costs nothing since it is already implemented and tested.
• B — plugin.json keywords field (this issue's stated RECOMMENDED). Tradeoff: no new file, but requires a reserved sub-namespace to survive the discovery-term collision shown above, and the exemption is invisible at the coupling site (a reviewer reading the flagged line can't see why it's excused without opening plugin.json). Reversibility: medium. Not recommended given the collision evidence.
• C — per-plugin allowlist file. Tradeoff: central and greppable, but decouples the exemption from the code it excuses (drift risk) and adds a file to maintain. Reversibility: medium. Weakest fit — the declaration wants to live with the locked capability, not in a registry.

Decision 2 (sub-decision) — annotation token name: keep portability-ok: (do not rename). It is already live in the engine and, per the parallel silent-skip-ok: precedent, deliberately named for convention symmetry — the two gates read as one family. Rename cost is bounded but no longer free: it would touch the 3 engine/test files, with no skill-content uses to migrate (code-search completeness isn't guaranteed, but the conclusion holds at any count near zero). Renaming buys nothing and breaks the *-ok: parallel. Recommend: confirm portability-ok: as final.

Net. Both "unresolved" questions have a shipped, tested answer that this brief recommends the operator ratify on first-principles merits (collision-free dedicated tokens; convention symmetry), not merely because it exists. The only real alternative (keywords) is weaker on the evidence found here.

Cross-links.

• ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 — parent epic; Option A (declaration-first, grow one token-class at a time) was ratified there, and the forge/branch/remote class is the staged token set this stage activates (origin/(main|master) is already ACTIVE; raw.githubusercontent, gh …, dotnet are STAGED in skill-portability-tokens.txt).
• issue-metadata conventions: operationalize native types, sub-issues hierarchy, dependencies, priority re-baseline, close-reason + documented conventions (umbrella) #552 — native sub-issues convention; this remains a plain STOPGAP child pending issue-metadata conventions: operationalize native types, sub-issues hierarchy, dependencies, priority re-baseline, close-reason + documented conventions (umbrella) #552, convert when it lands (per this issue's own stopgap note).

[kyle-sexton]

Operator ruling (ratification interview, 2026-07-22 ~03:05Z): RATIFIED as-is. portability-scope: <reason> whole-file token and portability-ok: <reason> per-site token are the locked agnosticism-scope conventions. The plugin.json keywords alternative is rejected — discovery keywords are contaminated (e.g. source-control's plain "github" would false-auto-exempt it from forge checks). *-ok: family symmetry with silent-skip-ok: retained. Applied by control tower under decide-and-log; flipping to status: ready.

[kyle-sexton]

This was generated by AI during autonomous triage (gate-audit lane).

Gate-audit finding: human floor already satisfied, label stale. This issue's needs-human gate existed solely for the "OPERATOR DECISION" in the issue body (plugin-scope declaration mechanism + annotation token name). The 2026-07-22 operator ratification comment above directly answers both: portability-scope:/portability-ok: tokens locked, plugin.json keywords alternative rejected, control tower already flipped status: ready. No open decision remains — the residual work (fixtures, Stage-1-dependent implementation per the acceptance criteria) is spec-bounded execution, not a new judgment call.

Classification: C3 (scoped, bug/feature-shaped, locked spec). Not cross-cutting beyond the already-agreed portability-lint engine; not security-surface; not a dependency pin.

Flipping needs-human → agent-ready on the strength of the recorded operator ruling itself (stronger evidence than a panel simulation would provide). No code changed, no merge, no execution — label + comment only.

[kyle-sexton]

Lease takeover. The prior lane-claim on this issue — instance melo-lap-001-triage-20260727T125559Z (lane triage), expires=2026-07-27T17:52:00Z — is EXPIRED. No open close-linked PR, no branch referencing this issue, and no activity since 2026-07-27T16:52:43Z. Taking over the lease for instance MELO-LAP-001-worker-202607290838 (lane work-loop).