Sweep existing ephemeral-HTML producers onto the topic-docs ephemeral tier

[kyle-sexton]

Follow-up from Codex review threads on #1675, deliberately deferred rather than folded into that PR.

#1675 adds the ephemeral row to the topic-docs tier table and migrates the two plugins that had a stake in it (adhd, architecture). Introducing the row retroactively reclassifies HTML producers elsewhere in the marketplace. Codex has been enumerating them one per push; this issue is the sweep, so the docs PR is not held open while the fleet migrates.

Known producers

1. planning:interview round tables

thread — plugins/planning/skills/interview/context/loop.md:108 writes <memory_dir>/<topic-slug>/interview-round-<n>.html to the memory tier, while calling it "read-only scanning" with the ledger and terminal as the tracked record. One file per round is the accumulating tree the footprint rule prohibits.

Open question first: are the round tables genuinely disposable? Rounds are numbered across a session and answered by number in the terminal, so a user on round 3 may legitimately want round 1's table still readable. If so these are memory-tier by nature and the binding should document the downstream reader instead of migrating.

2. education:teach lesson HTML

thread — plugins/education/skills/teach/context/lessons.md ("Ephemeral placement") labels the file ephemeral but places it under ${CLAUDE_PLUGIN_DATA}/<project-slug>/<mode>/<topic>/concepts/<concept>/, which the tier table classifies as machine state — persistent and accumulating. The doc contradicts itself: it says ephemeral and writes durable.

Open question first: teach is a multi-session coach whose learning-records are explicitly durable. If a learner reopens a past concept's lesson page, the HTML is a durable teaching artifact and the fix is to stop calling it ephemeral — not to move it to temp.

Shape of the work

Each is its own PR: manifest version bump, changelog entry, and binding-doc update (plugins/<name>/reference/topic-docs.md). Neither should be resolved by moving files before answering its open question — the ephemeral row is a classification, and the honest outcome for a producer may be "it was never ephemeral, fix the label."

Acceptance

Per producer, either migrate to the ephemeral tier with one file per run, or record in that plugin's binding doc why a later session reads the file and classify it accordingly. Not silence.

[kyle-sexton]

Status update — both named producers are now resolved on #1675

This issue was filed to keep #1675 from being held open while the fleet migrated. Later commits on that branch resolved both producers, so the deferral no longer applies to either. Verified against the current branch state.

Producer 1 — planning:interview round tables: migrated

plugins/planning/skills/interview/context/loop.md:108 now writes to the ephemeral tier, explicitly "not the memory slice". The open design question this issue raised — are the round tables genuinely disposable, given a user on round 3 may want round 1's table still readable? — was answered rather than assumed:

• The producer creates one temp directory per interview run and writes every interview-round-<n>.html inside it, so earlier rounds stay readable for the whole run. That directly addresses the concern; what the footprint rule prohibits is an accumulating tree, and one directory per run is the shape the tier explicitly sanctions ("one file, or one directory, per run").
• Resume was handled deliberately, not overlooked: a resumed interview starts a new run directory, because after a handoff-and-clear the prior path is not re-resolvable. The record survives in the ledger and Brief; the temp path is deliberately recorded nowhere, on the grounds that a pointer into the temp tree is not memory-tier content.

Producer 2 — education:teach HTML: reclassified, not moved

The caveat raised in the review thread turned out to be the right call. plugins/education/skills/teach/context/lessons.md:51 now states that workspace HTML is machine state, not ephemeral, with the reasoning recorded: a concept's HTML is that concept's lesson artifact, so it belongs in the concept slice beside reference.md, and resume opens that slice to pick a concept back up. Writing it to OS temp would leave a concept holding a reference and an exercise with its lesson missing.

The doc also separates the two senses of the word that caused the confusion: "ephemeral" describes a lesson pedagogically (rarely revisited, regenerable), never where it is stored.

primer HTML is genuinely ephemeral — it creates no workspace and its output is read once — so that half routes to the ephemeral tier.

What is still open, and it is not what this issue was filed for

Two things worth tracking rather than closing silently:

1. A P1 that landed in the migration itself. lessons.md:52 prescribes mktemp "${TMPDIR:-/tmp}/primer-XXXXXX.html" — a suffix after the Xs. The FreeBSD mktemp(1) manual states the trailing Xs are replaced, so that form fails on macOS/FreeBSD; GNU coreutils auto-implies --suffix when the template does not end in X, which is why it works on Linux and Git Bash and nowhere else. plugins/architecture/skills/improve/actions/deepening.md:39 carries the same form. Both skills emit open <path> for macOS in the same instruction block, so they claim the platform they cannot run on. This is being fixed on docs(topic-docs): add the ephemeral tier row so throwaway files stop reaching for the scratchpad #1675; noting it here because it entered through this migration.

   (loop.md:108 is already safe — it uses mktemp -d with no suffix.)

2. The broader sweep. fix(plugins): bring five ephemeral-file producers onto the tier contract #1708 covers five further violators found by a nineteen-producer audit (firecrawl, prototype/explore-directions, visualization/visualize, event-storming/simulation, context7/lookup). The marketplace-wide mktemp flag question is mktemp: no flag form is both non-deprecated and portable, and the bare form writes into the repo #1709.

Recommendation: close this issue once #1675 merges — both producers it names are resolved there, and everything remaining has its own tracking issue. Leaving it open would imply migration work that no longer exists.

[kyle-sexton]

This was generated by AI (triage lane, gate-audit pass — cycle 2 retry, instance melo-lap-001-triage-20260727T125559Z).

Verdict: real, but the work this issue was filed for no longer exists.

Per the maintainer status update above, both named producers (planning:interview round tables, education:teach lesson HTML) are resolved on #1675 — one migrated, one deliberately reclassified. What remains is a close decision, not implementation, so this is classified read-only and left human-gated. Recommend closing once #1675 merges; this lane does not close.

Cross-references: the remaining sweep is tracked by #1708 (five further producers) and #1709 (marketplace-wide mktemp suffix question) — both named in the update above.

Labels: priority: low, work-class: read-only, needs-human, status: needs-decision (removed priority: needs-triage).