topic-docs: tier table has no ephemeral row, so two plugins invented a scratchpad-first answer

[kyle-sexton]

Context

The topic-docs tier table sorts documents by one question — "does anything downstream enforce against this?" — which cannot express lifetime. Its finest-grained cell is the memory tier .work/<slug>/, which conflates two kinds with opposite requirements: state that must SURVIVE the session (resume artifacts, ledgers, captures), and files that DIE with it (a rendered HTML view, a spill file, a throwaway).

With no row naming the ephemeral cell, two plugins independently invented the same answer, and both reached for an undocumented harness path:

• plugins/adhd/skills/clarify/SKILL.md:127 — "an OS temp path (the session's scratchpad directory when the harness provides one, else the platform temp dir)"
• plugins/architecture/skills/improve/research/deepening/html-report.md:3 — "rendered as self-contained HTML in the OS temp directory"

Under PLUGIN-PHILOSOPHY.md's convention registry ("a new cross-plugin convention lands in an owner doc before a second plugin adopts it"), that trigger has already fired.

Why the session scratchpad is not the answer. Verified against primary sources: zero occurrences of "scratchpad" in the full 6.4 MB docs corpus (curl https://code.claude.com/docs/llms-full.txt + grep) — it is system-prompt-injected only. It is keyed by CWD (every worktree gets a distinct root) and scoped by session UUID. Measured on one machine: 230 directories, 31,260 files, 2.96 GB in 10 days, no pruning observed. Three upstream requests to make it a supported surface are all CLOSED / NOT_PLANNED (anthropics/claude-code#45745 2026-06-11, anthropics/claude-code#17936 2026-02-27, anthropics/claude-code#21248 2026-03-01) — upstream has not merely failed to document it, it has declined three times to support it.

$CLAUDE_JOB_DIR/tmp IS documented ("Per-session scratch directory. Writes here don't prompt for permission. Removed when the session is deleted") but is set for BACKGROUND sessions only — verified UNSET in an interactive session where a scratchpad path WAS injected. Preferring it when present makes file placement depend on how the session was launched, which is invisible from inside the plugin.

Cost of leaving it: the next plugin needing a throwaway file invents a third answer, and the two existing adopters keep depending on a surface upstream has declined to support.

Proposed work

• Add one additive Ephemeral row to the tier table in docs/conventions/topic-docs/README.md: location = an OS-API-created temp directory, git = never in the repo, holds = files that die with the session.
• State four rules at the row: (1) resolve ONE deterministic path and clean up in a finally — never branch on whether the harness injected a scratchpad path or set CLAUDE_JOB_DIR; (2) never the session scratchpad — plugins never require it, publish pointers to it, or change semantics based on its presence; (3) nothing durable lands here — if a later session, another checkout, or a reviewer must read it, it belongs in the memory or contract tier; (4) customization is a userConfig typed directory defaulting to empty (machine-scope, so userConfig per the philosophy's configuration-ownership table — NOT a topic-docs.yaml key, which would imply a tracked team decision).
• Migrate both existing adopters off the scratchpad-first wording.
• Add a re-derivation trigger at the row rather than a date stamp.
• Include a rationale section recording that git-visibility, promotion-stage, and write-contention were each examined and found already covered (see References) — so the analysis is not re-run later.

Acceptance criteria

• docs/conventions/topic-docs/README.md carries an Ephemeral row with all four rules stated.
• docs/conventions/topic-docs/CHANGELOG.md records the change as a MINOR version — no tier moves, no topic-docs.yaml key renames, no slug-spec change, no visibility guarantee altered, so the eight bindings need no synchronized adoption wave.
• plugins/adhd/skills/clarify/SKILL.md no longer references the session scratchpad.
• plugins/architecture/skills/improve/research/deepening/html-report.md resolves its temp path by the new row's rule.
• The row carries a re-derivation trigger naming the observable change that invalidates it (an upstream versioned interface for the scratchpad with guaranteed injection, lifecycle, ownership, quota, and cleanup semantics).
• A rationale section records why the other three axes needed no change.

References

• docs/conventions/topic-docs/README.md — tier table and Versioning section (v2.3.0)
• docs/PLUGIN-PHILOSOPHY.md — convention registry, native-first adoption gate, two-lane convention posture, configuration ownership table
• melodic-software/standards conventions/engineering/shareable-artifact-design.md — externalize what a consumer may decide, and its YAGNI counterweight
• plugins/work-items/reference/tracker-seam.md:90,182,199 — write-contention already covered: race-safe claim + lease at the seam
• Per-session scratch directory environment variable for temporary files anthropics/claude-code#45745, [FEATURE] Use CLAUDE_CODE_TMPDIR for Session Scratchpad anthropics/claude-code#17936, [FEATURE] Scratchpad should persist beyond session and be user-accessible by default anthropics/claude-code#21248 — all CLOSED / NOT_PLANNED
• Claude Code docs env-vars.md:305 (CLAUDE_CODE_SESSION_ID), env-vars.md:330 (CLAUDE_CODE_TMPDIR), memory.md "Storage location" (auto memory)