portability: three unowned origin/(main|master) couplings in playbooks:boris and work-items:track

[kyle-sexton]

Category: bug (latent) / hygiene · Source: agent session, 2026-07-24 — bash scripts/check-skill-portability.sh --all run against the current tree.

Filed by an agent session. The three hits below are the gate's own verbatim output, not a hand-read of the files.

The three couplings

COUPLING: plugins/playbooks/skills/boris/reference/foundations.md:15: origin/(main|master) -> git worktree add .claude/worktrees/my-worktree origin/main
COUPLING: plugins/work-items/skills/track/actions/start.md:61: origin/(main|master) -> … On `yes`, emit `git checkout -b <type>/<N>-<slug> origin/main` for the user. …
COUPLING: plugins/work-items/skills/track/actions/start.md:65: origin/(main|master) -> … Emit `git checkout -b <type>/<N>-<slug> origin/main` for the user.

Reproduce: bash scripts/check-skill-portability.sh --all.

Why CI is green, and why that is correct

The gate runs in changed-file mode against the PR base ref — scripts/check-skill-portability.sh "origin/$BASE_REF" (.github/workflows/ci.yml:658) — so these surface only when those files are themselves touched, or in --all mode, which nothing runs.

That is deliberate and documented, not an oversight. scripts/check-skill-portability.sh header:

Changed-FILE (not whole-skill-dir) scoping keeps a PR responsible only for the files it actually edits, so enabling a token class never red-lines main […] existing violations wait for the owning follow-up fix or the file's next edit.

and ci.yml:636-638:

enabling a token class prevents NEW coupling without red-lining existing violations that member issues own.

What is actually missing: an owner

That design assumes each pre-existing violation has an owning issue. These three do not. All 19 members of the #531 coupling class were checked (#404 #405 #406 #408 #410 #412 #415 #416 #418 #421 #422 #423 #428 #429 #432 #438 #439 #441 #442) — the closest are #442 (origin remote name in source-control:pull-request) and #415/#418 (planning's branch grammar and tracker writes). None covers plugins/playbooks/skills/boris or plugins/work-items/skills/track.

So this is the owning follow-up the gate's own header points at, filed to close the assumption rather than to relitigate the scoping decision.

Resolutions

Each site takes one of the script's three documented escapes — a co-located detection-first branch-resolution command, a portability-ok: <reason> comment at the site, or a portability-scope: <reason> declaration in the file. Per-site read, offered as a starting point rather than a verdict:

• work-items/track/actions/start.md:61,65 — the skill emits git checkout -b <type>/<N>-<slug> origin/main for the user on a tracker-agnostic path, and the surrounding action already runs bash for branch detection. A detection-first resolution ladder (origin/HEAD / symbolic-ref / merge-base / PR baseRefName) co-located on the line is the fix the gate is asking for; an escape comment here would record a default nobody chose.
• playbooks/skills/boris/reference/foundations.md:15 — this is a fenced example inside a mirror of upstream howborisusesclaudecode.com content, where the example command is the upstream author's, not this repo's recommendation. Rewriting it would make the mirror diverge from its source. Either escape may be right; the choice is a judgment about what that file is, and the owners hold it.

Note for whoever fixes this: #624 will tighten the escape grammar (standalone-comment-only matching, required nonempty reason). Any portability-ok: / portability-scope: written here should already satisfy that form so it does not need a second pass.

Relations

#531 (umbrella), #620 (the branch-class gate engine that flags these), #624 / #611 (escape-hatch grammar, affects any escape chosen above).

[kyle-sexton]

This was generated by AI during triage.

Verified

All three coupling sites confirmed present at this commit by direct read:

• plugins/playbooks/skills/boris/reference/foundations.md:15 — git worktree add .claude/worktrees/my-worktree origin/main
• plugins/work-items/skills/track/actions/start.md:61 — git checkout -b <type>/<N>-<slug> origin/main
• plugins/work-items/skills/track/actions/start.md:65 — same command, second emission site

The item's central claim — that these are pre-existing violations with no owning issue — is the load-bearing one and it checks out as filed: all 19 named members of the #531 coupling class were enumerated in the body, and none covers plugins/playbooks/skills/boris or plugins/work-items/skills/track. The gate's changed-file scoping (ci.yml:658) is correctly identified as deliberate, so this is the owning follow-up the gate's own header points at, not a request to relitigate scoping.

Classification

• Work class: C3 scoped, bug-fix-shaped (latent defect / hygiene). Bounded to three sites in two files, verifiable by a deterministic gate (bash scripts/check-skill-portability.sh --all must come back clean), and trivially revertible.
• Priority: medium — latent, CI is correctly green, nothing is broken for a user today.

Queued for C3 ratification — not yet dispatchable

Routed human-gated under the first-drain C3 ratification gate, not because the work is ambiguous but because the earn-trust period is still open. Read live from the work-loop lane's durable state at the time of this sweep: "first_drain_complete": false. Per the admission gate, an unratified C3 bug-fix candidate is queued rather than dispatched. Once ratified, this returns to the frontier autonomous-eligible and dispatches on a later cycle — the ratification travels with the item, so it is never re-queued.

Intended dispatch, if ratified

The two start.md sites and the boris site want different escapes, and the item is right that only one of them is mechanical:

• work-items/skills/track/actions/start.md:61,65 — a detection-first branch-resolution ladder (origin/HEAD → symbolic-ref → merge-base → PR baseRefName), co-located per the gate's documented escape. The surrounding action already shells out for branch detection, so this adds no new mechanism. An escape comment here would record a default nobody chose.
• playbooks/skills/boris/reference/foundations.md:15 — this half is a judgment call and should not be defaulted. The file mirrors upstream howborisusesclaudecode.com content; the command is the upstream author's, not this repo's recommendation. Rewriting it makes the mirror diverge from its source. A portability-ok: / portability-scope: escape preserves mirror fidelity, but which one — and whether the mirror framing is even the right read of that file — belongs to the file's owners. A ratifier should decide this site explicitly rather than accept it as part of the mechanical half.

Constraint for the implementer: #624 will tighten the escape grammar to standalone-comment-only matching with a required nonempty reason. Any escape written here should already satisfy that form so it does not need a second pass. Related: #531 (umbrella), #620 (the gate engine), #611.

[kyle-sexton]

This was generated by AI. Triage lane claimed for a gate audit of the first-drain C3 ratification hold on this item. No labels changed by this comment.

[kyle-sexton]

This was generated by AI during a gate audit of the first-drain C3 ratification hold. No labels were changed. This is not a ratification — it does not reply to the kind=ratify-c3 marker, and the item stays gated.

Lead correction: this item is 2/3 stale — one site remains, not three

Verified at origin/main (c9879fb7):

Filed site	State now
plugins/work-items/skills/track/actions/start.md:61	resolved
plugins/work-items/skills/track/actions/start.md:65	resolved
plugins/playbooks/skills/boris/reference/foundations.md:15	still open

• git grep -nE "origin/(main\|master)" origin/main -- plugins/work-items/skills/track/actions/start.md returns zero hits. Both sites were fixed in work-items 0.25.2 (plugins/work-items/CHANGELOG.md:58-80) with a detection-first ladder that asks the remote first (git ls-remote --symref origin HEAD), falls back to the refs/remotes/origin/HEAD cache, validates the name against a conservative charset, and never falls back to a literal.
• bash scripts/check-skill-portability.sh --paths <both files> now emits exactly one line:
  COUPLING: plugins/playbooks/skills/boris/reference/foundations.md:15: origin/(main|master) -> git worktree add .claude/worktrees/my-worktree origin/main
• plugins/playbooks/skills/boris/vendor/SKILL.md:237 carries the byte-identical command but is gate-exempt (scripts/check-skill-portability.sh:80 excludes */vendor/*).
• Citation drift, non-substantive: the body's ci.yml:658 is now .github/workflows/ci.yml:871. The wiring claim itself holds.

--all mode did not complete inside a 2-minute timeout on a Windows checkout; --paths is the same scan path and was used instead.

The body's stated reason for the remaining site names the wrong mechanism

The body says reference/foundations.md is "a mirror of upstream" that would "diverge from its source" if rewritten. The byte mirror is vendor/SKILL.md:

• plugins/playbooks/skills/boris/SKILL.md:31 — "The verbatim upstream baseline lives at vendor/SKILL.md for drift detection only".
• plugins/playbooks/skills/boris/scripts/update.sh:11-13 — --apply "does NOT rewrite the SKILL.md body or reference/.md content — distilled"; :178 — "Manual integration of new tips into reference/.md is required after --apply."

But the concern survives its wrong mechanism. SKILL.md:18-22 declares "Content parity tracked against https://howborisusesclaudecode.com/api/install", the frontmatter carries author: Boris Cherny (tips) / source: howborisusesclaudecode.com / upstream-version: 8.13.0, and the tip block at foundations.md:13-19 is byte-identical to vendor/SKILL.md:233-240 (same md5). So this line does reproduce the upstream author's own example verbatim, under a stated parity claim — even though no automated gate compares the two.

Counter-evidence, stated because it cuts against the above: reference/ prose has been edited for repo-wide policy before (279ad688, docs.claude.com → code.claude.com). That was a factual correction upstream would agree with; changing a command's semantics is a different kind of edit.

Panel — prior rationale withheld from both external seats

Neutral packet = title + body + a labeled verified-state section. The kind=ratify-c3 marker, the work-class label, and all prior lane conclusions were withheld.

Seat	Class	(a) security	(b) dep-pin	(c) cross-cutting	(d) hard to reverse	(e) human call	Autonomous PR?	Confidence
A — fresh Claude reviewer	C3	NO	NO	NO	NO	NO	YES	medium-high
B — OpenAI Codex	C3	NO	NO	NO	NO	NO	YES	high
C — this agent	C3	NO	NO	NO	NO	YES	NO	high

Unanimous and solid: the remaining work is C3 — bounded, one line in one file — and is not a security-surface change, not a dependency-pin/checksum/SHA change, not cross-cutting, and not hard to reverse. Those four axes are clear and no seat dissented.

Why it stays gated anyway

The two seats that voted YES prescribe mutually exclusive fixes, each calling the other's wrong.

• Seat A recommends the per-site portability-ok: escape and calls the detection-first rewrite "available, not recommended" — because it rewrites a user-facing distilled tip quoting the upstream author's example, "and that is where a human's editorial preference legitimately sits before the work."
• Seat B prescribes the detection-first rewrite and states an exemption "lacks supporting scope rationale and precedent."

A consensus that work is dispatchable needs agreement on what would be dispatched. There is none.

And the escape branch is disqualified on a fact neither YES seat reached. #624's body states the portability-ok: / portability-scope: tokens "are the same escapes awaiting operator-convention ratification on #531 (items 1-2)". #531 is OPEN, and its declaration design question is still listed unresolved: "How does a skill declare its agnosticism scope…? The declaration is the gate's contract." Seat A's named residual unknown was only "#624's exact final escape grammar" — one step short of the ratification dependency.

Supporting: git grep "portability-ok\|portability-scope" origin/main -- 'plugins/*/skills/*' returns zero. All 16 in-repo portability-ok: uses live under plugins/*/hooks/ and *.test.sh and are honored by a different gate (scripts/check-shell-portability.sh, separate token list). Either escape here would be the repo's first in skill scope — precedent for the rest of the #531 class, set from a one-line site, while #624 is actively rewriting the grammar.

Also relevant to either branch: the escape must sit inside the user-visible ```bash fence (a non-comment line resets the gate's carry-forward, and the fence line is non-comment). Seats A and C traced this independently; Seat A names the cost as "gate machinery leaking into consumer-facing tips prose."

So neither branch is available to an autonomous implementer without a human choosing first. The gate's hold is doing real work here, not only earn-trust.

Open decision

RECOMMENDED — Defer this site to #531's escape-convention ratification. It is the same decision #531 items 1-2 already own; a single one-line site is a poor forum for setting the fleet-wide precedent, and #624 is actively rewriting the grammar that any escape written today would have to satisfy. Cost: the coupling stays on main (harmless — CI is correctly green by design), now with an owning issue, which was this item's actual purpose.

Alternative A — Authorize the portability-ok: escape now (Seat A's pick). Accepts gate machinery rendering inside consumer-facing tips prose, and spends the escape convention ahead of #531's ratification.

Alternative B — Authorize the detection-first rewrite (Seat B's pick). Accepts divergence from a block that is byte-identical to the upstream baseline under the stated content-parity claim. Note the gate recognizes only origin/HEAD / symbolic-ref / merge-base / baseRefName as co-located resolution evidence — ls-remote --symref, the mechanism work-items 0.25.2 actually adopted, is not among them, so the start.md precedent is not directly copyable onto a one-line fenced example.

Suggestion, not applied: the title says "three … couplings" and now overstates the scope by 2. Retitling to one site in playbooks:boris would keep the queue honest. Left to a human — this audit changed no labels and no title.

[kyle-sexton]

This was generated by AI. Triage lane released; gate audit complete, item left gated, no labels changed.