mktemp: no flag form is both non-deprecated and portable, and the bare form writes into the repo

[kyle-sexton]

Context

Skills across this marketplace instruct agents to create ephemeral files with mktemp, and the flag forms in use are either deprecated or not portable to macOS. There is currently no single documented form that is both.

Verified empirically in this environment (Git Bash on Windows, GNU coreutils 8.32):

$ mktemp --help | grep -A1 '^  -t'
  -t                  interpret TEMPLATE as a single file name component,
                        relative to a directory: $TMPDIR, if set; else the

GNU's own help text marks -t [deprecated]. Meanwhile --tmpdir is a GNU long option that BSD mktemp does not implement, so it is unavailable on macOS — which several of these skills explicitly claim to support, since they emit open <path> for macOS in the very same instruction block.

So today a skill author picks between a deprecated flag and a non-portable one.

Why this matters more than it looks

A bare mktemp with a relative template is actively dangerous, which is what pushes authors toward these flags in the first place:

$ cd <a repo worktree>
$ mktemp -u fc-test-XXXXXX
fc-test-tdvDNS            # relative — creates the file IN THE REPO
$ mktemp -u -t fc-test-XXXXXX
/tmp/fc-test-s5WOPv       # correct
$ mktemp -u
/tmp/tmp.wU8JAOjsg6       # correct

GNU's implicit --tmpdir applies only when no template is given. A producer supplying a relative template to preserve a readable filename — mktemp clarify-XXXXXX.html, the natural thing to write — creates the file in the current working directory. For a skill running inside a consumer's repository, that violates the topic-docs ephemeral tier's own "Never in the repo" rule and leaves an untracked file in their tree.

So the flag is not optional decoration; it is what keeps the file out of the repo. Which makes "there is no correct flag" a real gap rather than a style nit.

Scope

The flag choice originates in plugins/architecture/skills/improve/actions/deepening.md and has since been copied into other skills, including the five touched by PR #1708. It is a marketplace-wide inheritance, not a defect introduced by any one PR.

A sweep for mktemp across plugins/** will find the full set; every call site needs the same answer, so this wants one decision recorded in an owner doc rather than five independent judgements.

Proposed work

• Determine a mktemp form that is non-deprecated and portable across GNU coreutils and BSD/macOS, verified by actually running it on both rather than by reading man pages. A candidate worth testing first is setting the directory explicitly and passing an absolute template:

  tmpdir="${TMPDIR:-/tmp}"; mktemp "$tmpdir/name-XXXXXX.html"
  

  which sidesteps both -t and --tmpdir. Confirm the .html suffix survives on BSD — GNU auto-implies --suffix when the template does not end in X, and BSD's behavior here needs checking, not assuming.

• Record the chosen form in the topic-docs ephemeral tier as the normative instruction, so rule 1 names a specific portable invocation instead of "the platform's temp primitive".

• Migrate every existing call site to that form.

• State plainly what happens where no portable form exists, if that turns out to be the case — an honest per-platform branch beats a form that silently misbehaves on one of them.

Acceptance criteria

• A portable, non-deprecated mktemp form is identified and verified by execution on both GNU and BSD, with the outputs recorded.
• The topic-docs ephemeral tier names that exact form.
• Every mktemp call site under plugins/** uses it; a sweep confirms no bare-relative-template invocations remain.
• If no single portable form exists, the per-platform branch is documented explicitly rather than left to the author.

References

• docs/conventions/topic-docs/README.md — the ephemeral tier and its "Never in the repo" rule
• plugins/architecture/skills/improve/actions/deepening.md — origin of the current flag choice
• PR fix(plugins): bring five ephemeral-file producers onto the tier contract #1708 — spreads the current form to four more skills; its description carries the same limitation note
• GNU coreutils mktemp --help (-t marked deprecated); BSD mktemp(1) has no --tmpdir

[kyle-sexton]

This was generated by AI during triage. Raw-intake triage complete for this item; claim released. Verdict and routing labels posted below; raw-intake marker cleared.

[kyle-sexton]

This was generated by AI during triage.

Verdict: real and well-scoped, but blocked on a verification surface this org does not have

Work class: scoped (the migration itself is mechanical once the form is chosen). Gated not on judgment about the fix, but on an acceptance criterion that cannot currently be satisfied.

The finding is real

The two claims hold. GNU coreutils marks -t deprecated in its own help text, and --tmpdir is a GNU long option with no BSD equivalent, so a skill author targeting both platforms genuinely has no non-deprecated portable flag. The danger the item identifies is also real and is the reason the flag matters: GNU's implicit --tmpdir applies only when no template is given, so mktemp clarify-XXXXXX.html — the natural thing to write when you want a readable filename — creates the file in the current working directory, which for a skill running inside a consumer's repository violates the topic-docs ephemeral tier's "Never in the repo" rule.

The blocker

Acceptance criterion 1 requires the chosen form be "verified by execution" on both GNU and BSD, explicitly "rather than by reading man pages."

There is no BSD/macOS execution surface available to this org today. Verified this pass: every workflow in .github/workflows/ runs on ubuntu-24.04 — 23 of 23, no exceptions. There is no macOS runner and no Windows runner anywhere in CI. (This is the same structural gap #1414 raises for Windows; it extends to macOS.)

So an autonomous agent picking this up can satisfy every criterion except the one the item deliberately made the gate — and the honest failure mode is that it verifies on GNU, reads the BSD man page, and reports the criterion met. That is precisely what the item was written to prevent, which is why this needs an operator call rather than a best-effort attempt.

---

Decision-ready summary

The question: how should the BSD/macOS half of "verified by execution" be satisfied?

RECOMMENDED — Option A: add a throwaway macos-latest verification job, run it, record the output, then delete it

Add a temporary workflow that runs the candidate forms on a GitHub-hosted macOS runner, paste the real output into this issue as the evidence artifact, then remove the job. GitHub-hosted macOS runners are available to this org's plan; this is the only option that satisfies the criterion as written and it costs one short CI run.

Why: the criterion exists because BSD mktemp behavior — specifically whether a .html suffix survives when the template does not end in X — is exactly the kind of detail a man page states ambiguously and an execution settles. The item flags that suffix question as needing "checking, not assuming." Note the candidate form the body proposes (tmpdir="${TMPDIR:-/tmp}"; mktemp "$tmpdir/name-XXXXXX.html") is the one most likely to differ across the two implementations, so this is not a formality.

Option B: stand up a permanent multi-OS CI matrix first

Make this issue depend on #1414 and verify on the resulting matrix. Trade-off: strictly better long-term and fixes a broader gap, but converts a small scoped item into one blocked behind infrastructure work of a different size and owner.

Option C: relax the criterion to authoritative-documentation verification

Amend acceptance criterion 1 to accept the BSD mktemp(1) man page as the source for the BSD half, GNU verified by execution. Trade-off: cheapest, and honest only if the amendment is written into the issue explicitly rather than quietly satisfied. Weakest evidence on exactly the platform we cannot test — and the item's fourth criterion (document a per-platform branch if no single portable form exists) becomes a judgment made without data.

Not recommended: leave as-is for autonomous pickup

An agent will verify GNU, consult the BSD man page, and mark the box done. That is the specific failure the criterion was written to prevent.

---

Labels: needs-human, status: needs-decision, work-class: scoped, priority: medium. Removed priority: needs-triage.

Once the verification path above is chosen, the remaining work (pick the form, record it in the topic-docs ephemeral tier, migrate every plugins/** call site, sweep for bare-relative-template invocations) is mechanical and can go straight to agent-ready without re-triage.

[kyle-sexton]

This was generated by AI in the decide-and-implement lane (operator authorization: human gates become decision work for frontier consensus). Decision: Option A, executed — a throwaway macos-latest job ran the candidate forms on real BSD mktemp, the outputs are recorded below, and the job is already deleted from the branch. The verified portable, non-deprecated form is the one the topic-docs ephemeral tier already names: mktemp "${TMPDIR:-/tmp}/<name>-XXXXXX" (add -d for a directory), positional absolute template, trailing Xs, no flags. The suffix question the issue flagged as "needs checking, not assuming" turned out to be worse than the man pages suggest: macOS does not reject …-XXXXXX.html — it silently creates the file literally named verify1709-XXXXXX.html, with no X substitution at all, i.e. a fixed predictable path with zero randomness, which is a collision/security failure rather than a loud error. That vindicates making trailing-Xs a hard rule and the -d-plus-fixed-filename idiom the escape for meaningful names. Sweep result: no bare-relative-template invocations exist under plugins/**; the only remaining non-conforming call sites were two mktemp -t <name>-XXXXXX.json in claude-config's fix-plugin-drift.sh (GNU marks -t deprecated; BSD -t treats the argument as a prefix, not a template), migrated in the linked PR.

GNU, executed locally (coreutils 9.4, Linux):

mktemp (GNU coreutils) 9.4
1. mktemp "${TMPDIR:-/tmp}/verify1709-XXXXXX"      -> created: /tmp/verify1709-6HIIoF (mode 0600)
2. mktemp -d "${TMPDIR:-/tmp}/verify1709-XXXXXX"   -> created dir: /tmp/verify1709-oKBbm7
3. mktemp "${TMPDIR:-/tmp}/verify1709-XXXXXX.html" -> accepted: /tmp/verify1709-0nesE5.html (implied --suffix, GNU-only)
4. (cd tmpdir; mktemp verify1709-XXXXXX)           -> created: verify1709-Y3bFrD in the CWD (the danger)

BSD/macOS, executed on a GitHub-hosted macos-latest runner (macOS 26.5.2, arm64), run 31594143233:

1. mktemp "${TMPDIR:-/tmp}/verify1709-XXXXXX"      -> created: /var/folders/df/…/T//verify1709-HFysSx (mode 0600)
2. mktemp -d "${TMPDIR:-/tmp}/verify1709-XXXXXX"   -> created dir: /var/folders/df/…/T//verify1709-tZKjLd
3. mktemp "${TMPDIR:-/tmp}/verify1709-XXXXXX.html" -> "accepted": file created VERBATIM as verify1709-XXXXXX.html — no X substitution, no randomness
4. (cd tmpdir; mktemp verify1709-XXXXXX)           -> created: verify1709-ElvR8k in the CWD (same danger)

Acceptance criteria: (1) verified by execution on both, outputs above; (2) the topic-docs ephemeral tier already names this exact form (landed after this issue was filed); (3) call-site sweep clean after the PR's two-site migration; (4) no per-platform branch needed — one form works on both, and the meaningful-filename case is covered by the documented -d + fixed-name-inside idiom.