fix(skills): #1619 remainder — re-scope to the $-expansion trigger (original 31-skill git-based list is WRONG)

[kyle-sexton]

Follow-up to #1619. The mechanism and the fix are both confirmed there by direct probe; this issue
tracks the part of the blast radius that the first remediation pass deliberately left alone.

What was fixed

The #1619 remediation covered session-flow (7 skills) and source-control (5 skills) —
the highest-traffic skills, and the two plugins the original spec scoped. 12 of 43.

What is still broken

31 skills across 16 plugins still carry a multi-line precompute block containing a git command,
so they are still refused when invoked from a worktree-isolated agent:

plugin	skills
planning	devils-advocate, interview, plan, prd
testing	diagnose, plan, run-e2e, write
docs-hygiene	audit-derivability, audit-noise, compress, rename-references
discovery	blindspot, explore
code-tidying	audit-comment-residue, tidy
toolchain	check, lint
review	fanout, quality-gate
prototype	explore-directions, pressure-test
claude-ops	lanes, observability
architecture	improve
bug-report	write
codebase-health	audit
debugging	debug
implementation	implement
repo-hygiene	clean
verification	confirm

(planning shows 4 here rather than 7 — its audit-answers, design, and design-handoff each
have a single precompute line and load today. See #1619's sharp-edge note.)

The fix, unchanged

Identical to the remediation already applied: delete the git lines from ## Pre-computed context,
re-acquire those values in the skill body as individual Bash calls (one command per call), leave
non-git precompute lines untouched, leave the shell: bash frontmatter key alone.

Scoping

Each plugin owns its own plugin.json version and CHANGELOG.md, so this is one PR per plugin —
16 PRs. They are mutually independent (disjoint directories, no per-plugin versions in
marketplace.json) and can run in parallel worktrees.

Doing all skills in a plugin within that plugin's PR is required: a partial pass leaves the plugin
half-broken and forces a second version bump later.

Verification

A green CI run does not prove this fix — CI never invokes a skill from an isolated agent. Each
PR needs one invocation from an Agent with isolation: "worktree":

• before: the skill is refused with the worktree-isolation guard message;
• after: it renders its context section and runs;
• positive control: knowledge:course-digest (4 complex precompute lines, no git) loads either
  way. If the control ever starts failing, the cause is something other than fix(skills): worktree-isolated agents cannot invoke a skill whose pre-compute block contains a $-expansion (21 skills; NOT git — see correction comment) #1619.

Related

• fix(skills): worktree-isolated agents cannot invoke a skill whose pre-compute block contains a $-expansion (21 skills; NOT git — see correction comment) #1619 — the defect, the confirmed composition mechanism, the verbatim refusal text, and the full
  49-skill sweep.

[kyle-sexton]

This issue's file list is WRONG — re-scope before working it

The 31-skill list in the body was derived from a diagnosis that has since been refuted. See the
correction on #1619 for the full evidence.

Short version: the trigger is not git in a multi-line pre-compute block. It is a $-expansion in
pre-compute, in any form other than bare $HOME / "$HOME". Git, pipes, 2>/dev/null, ||, and
multi-line composition are all irrelevant — a verbatim git status --porcelain 2>/dev/null | head -20 || echo clean passes under isolation, while a git-free echo "${CLAUDE_CODE_SESSION_ID:-unknown}"
refuses.

What that changes here

Most of the 31 skills listed in the body are not affected — they are git-bearing but $-free, and
they load fine from an isolated agent. The actual affected set is different, smaller, and reaches
plugins this issue never mentioned.

Repo-wide sweep for $-expansion in a pre-compute line — 21 skills:

plugin	skills
session-flow	handoff, continue-in-background, orient, retro, running-retro, find-handoff (6)
claude-memory	audit
claude-ops	lanes, observability
code-tidying	audit-comment-residue, tidy
docs-hygiene	audit-noise, audit-derivability, compress
prototype	explore-directions, pressure-test
claude-config	audit-automation-gaps
education	teach
firecrawl	update
review	fanout
source-control	commit

source-control:commit is worth calling out: its ${CLAUDE_PLUGIN_ROOT} exec-bit probe means
#1679 does not fully fix it even after that PR's git migration lands.

session-flow's six mean #1676, already merged, did not fix them — it removed the git lines and
kept the $-bearing one.

The fix, restated

Remove $-expansion from the pre-compute block: move the read into a body Bash call, or emit the
value without ${}. Do not treat removing git as the remedy.

Whether bare $HOME can be relied on is an open judgment call — it is the one form observed to pass,
but the allowlist behind that is uncharacterized ($HOME passes, ${HOME} refuses).

Verification requirement

Any fix must be verified by invocation from an Agent with isolation: "worktree", including a
negative control — a skill predicted to still refuse. A pass without a control is what produced the
original wrong diagnosis. CI cannot test this at all; it never invokes a skill from an isolated agent.
The plugin cache is version-keyed, so a fix is unverifiable until it ships and plugins are updated.

I am leaving the original body in place rather than rewriting history, so the superseded list stays
visible as context for anyone who already read it.

[kyle-sexton]

session-flow's six are done — PR #1688 (0.17.16). 15 skills across 10 plugins remain here.

#1688 removes the $-expansion from all six session-flow skills on this issue's re-scoped list
(handoff, continue-in-background, orient, retro, running-retro, find-handoff).

Note on issue bookkeeping: #1688 carries Closes #1687 because pr-issue-linkage requires a
closing keyword, and #1687 duplicates this issue's corrected 21-skill list. This issue is the live
remainder tracker once #1688 merges. Remaining: claude-memory:audit, claude-ops:lanes,
claude-ops:observability, code-tidying:audit-comment-residue, code-tidying:tidy,
docs-hygiene:audit-noise, docs-hygiene:audit-derivability, docs-hygiene:compress,
prototype:explore-directions, prototype:pressure-test, claude-config:audit-automation-gaps,
education:teach, firecrawl:update, review:fanout, source-control:commit.

The open question in this issue is now settled — probe results

This issue asks: "Whether bare $HOME can be relied on is an open judgment call." Probed from a
worktree-isolated agent, one standalone Bash call per command:

command	result
echo $HOME	PASS
echo "$HOME"	PASS
echo ${HOME}	REFUSED
echo "${HOME}"	REFUSED
echo $CLAUDE_CODE_SESSION_ID	REFUSED
printenv CLAUDE_CODE_SESSION_ID	PASS
printenv CLAUDE_CODE_SESSION_ID || echo unknown	PASS
ls -1dt "$HOME/.claude/projects/"*/ 2>/dev/null | head -8 || echo "none"	PASS
ls -1dt ~/.claude/projects/*/ 2>/dev/null | head -3 || echo "none"	PASS
echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown"	REFUSED

Three things worth carrying into the remaining ten PRs.

1. The allowlist is name-specific, not form-specific. echo $CLAUDE_CODE_SESSION_ID — bare, no
braces, byte-identical in form to the passing echo $HOME — is refused. #1619's correction comment
flagged this as "inferred, not observed"; it is now observed. HOME remains the only member found,
across two independent probe sessions. So "drop the braces" is not a general remedy — it works
for HOME and nothing else tested.

2. printenv <NAME> is the clean replacement for an env read. It carries no $, passes under
isolation, and returns non-zero (so a || echo unknown fallback still works) when the variable is
unset. That is what #1688 uses in the skill bodies.

3. A $-free form is available for $HOME specifically. ~ expands and passes. It is immune to
the allowlist question entirely; the tradeoff is that ~ does not expand inside quotes, so the glob
goes unquoted and a home path containing a space would break it. #1688 kept "$HOME" for that
reason and flagged the dependency, but for a new line ~ is worth considering.

Nothing observed contradicts the rule as stated on #1619 / #1687.

Caveat that applies to every PR against this issue

The plugin cache is version-keyed, so an edited skill cannot be invoked until it ships. #1688 states
plainly that it verified command forms under isolation and did not verify that the edited
skills load — the claim #1676 made without doing it. Post-merge confirmation still needs a negative
control (a skill predicted to still refuse), and after #1688 merges there will be 15 of those
available in this repo, which makes the control trivial to source.

Separately: removing $-expansion from a pre-compute block makes a skill load. It does not fix
$-bearing shell in skill bodies and reference/ snippets, which remains subject to the same
guard at run time. session-flow:retro's transcript-parser invocation is one example. That is a
distinct, larger surface and is not covered by this issue's fix as written.

[kyle-sexton]

Superseded again — see the class split on #1687.

The 21-skill $-expansion list I posted in the previous comment is also wrong, for a different reason than the original 31-skill git list. Plugin variables (\, \, \) are substituted by the harness into literal paths before any shell sees them, so they never trip the guard and the skills using only them are not broken at all.

The real population is two classes:

• Class 1 — plugin-variable-only pre-compute: not broken, nothing to do. Confirmed loading under isolation: claude-config:audit-automation-gaps, prototype:pressure-test, docs-hygiene:audit-noise. Inferred same-shape: prototype:explore-directions, code-tidying:tidy, code-tidying:audit-comment-residue, source-control:commit, firecrawl:update.
• Class 2 — plugin variable mixed with a genuine shell expansion ($d, $(…), \default) in the same block: refused, but the shell expansion is the cause. Confirmed: claude-memory:audit. Inferred: claude-ops:observability, claude-ops:lanes, education:teach, review:fanout. Fix by hoisting the shell logic into a script called through the plugin variable.

session-flow's six are done — #1688 merged (0.17.16).

This issue has now been re-scoped twice and its body is two corrections stale. Recommend closing it in favor of #1687, which carries the current analysis, rather than layering a third correction on a stale body. Leaving it open only if someone wants the history in one place.

[kyle-sexton]

This was generated by AI (autonomous drain lane, delegated decision authority for this session: decisions recorded as comments for human review/veto; no merges).

DECISION — closed as superseded; #1687 reopened as the single canonical tracker

Executing the recommendation in the previous comment ("close it in favor of #1687"), with one correction to its premise: #1687 was already closed — auto-closed as completed by #1688's Closes keyword at 02:28:56Z on 2026-07-27, fifteen minutes before that recommendation was posted (02:44:24Z), and with its Class 2 work unfinished on origin/main. Closing this issue alone would have left zero live tracking surface for work that is verifiably still broken.

So the executed bookkeeping is:

• fix(skills): pre-compute Class 2 remainder — genuine shell expansion mixed into pre-compute in 5 plugins (canonical tracker; scope in comments, body list superseded) #1687 reopened and retitled — it carries the current analysis (class split, final guard rule) and now a canonical-scope comment listing the verified Class 2 remainder on origin/main @ 848df9e9: claude-memory:audit, claude-ops:lanes, claude-ops:observability, education:teach, review:fanout (one PR per plugin), plus a probe-pending disposition for code-tidying:audit-comment-residue's awk $NF.
• This issue closed as superseded (not planned). Its body is the original wrong 31-skill git list and has been corrected twice by comment; per this thread's own convention the body stays as history, and layering a third correction here was the worse option.

Cross-vendor advisory (codex-cli, read-only) concurred. All further work and discussion: #1687.