transcript-promotion

What this skill does

# Transcript Promotion

Lift substantive inline content from the ephemeral transcript surface to the durable plan-file surface. Extract verbatim, prepend canonical frontmatter, propagate to chezmoi-source so the autoCommit+autoPush cascade fires, and register the artifact in any series it belongs to.

## Why this exists

Sessions produce two kinds of substantive output:

1. **File-bound** — code edits, plan writes, IRF rows, memory entries. These propagate via `Write|Edit` tool hooks and naturally land on disk + remote.
2. **Conversation-bound** — dense reference deliveries, "engine logs", inline analyses, multi-section walkthroughs the user reads and reacts to in-chat.

Class (2) is durable in the JSONL transcript but invisible to `~/.claude/plans/INDEX.md`, `MEMORY.md`, and the chezmoi-source mirror. The transcript is on disk, but the content is buried inside conversation text rather than promoted to a discoverable artifact. A future session reading the plans index sees nothing; the content effectively dies with context exit.

Genesis case (2026-05-20 session `9cb55c4d`): three engine reference docs (LOG #1 statusLine, LOG #2 Hooks, LOG #3 Subagents) delivered inline. LOG #1 was persisted to a plan file by the same session. LOG #2 and #3 were marked "inline only — not file-persisted" in the closeout. Two days later (2026-05-22), under explicit prompt to verify durability, they were extracted from the JSONL and promoted via the protocol now codified in this skill.

Pairs with `artifact-resurfacing` as the inverse motion:
- `artifact-resurfacing` — citation points at nothing → reconcile the citation
- `transcript-promotion` — content exists with no citation → mint the citation

Both clear different sides of the same drift entropy.

## Authority boundary (read first)

This skill is **propagate-with-explicit-cascade** for routine plan files, **propose-not-apply** for any constitutional surface.

- Plan files in `~/.claude/plans/` may be written directly; the chezmoi auto-sync hook fails for bash-redirect file creation, so the skill manually runs `chezmoi add` to bring source into sync and let autoCommit+autoPush fire. This is the documented chezmoi gotcha protocol from home-scope CLAUDE.md.
- `CLAUDE.md`, `MEMORY.md`, `governance-rules.json`, `registry-v2.json`, any `seed.yaml`, `INST-INDEX-RERUM-FACIENDARUM.md` — never written by this skill. If transcript content names changes to a constitutional surface, defer to the conductor.
- Cross-organ push to a public ORGANVM `main` branch requires explicit per-session push authorization. This skill commits but surfaces the push decision to the user when the target is a public-main branch.

Discovery → propose-frontmatter → propagate via chezmoi → register in series. Four phases, last two require user-derived authorization for non-routine targets.

## When to use

- "Persist LOG #N to `~/.claude/plans/...`"
- "Promote this inline reference to a plan file"
- "Make sure this survives context exit"
- "Save the engine log to disk"
- "Another log for the engine" (canonically followed by promotion in the same or next turn)
- Closeout walks back and finds ≥1 deliverable flagged "inline only"
- User asks "all unique data survives present context upon exit?" and the audit table shows artifacts with `JSONL ✓ / plan file ✗`
- A `qa-audit` of substantive deliverables finds class-(2) content with no on-disk citation

## Four-phase protocol

### Phase 1 — Extract (verbatim from the JSONL)

The JSONL transcript is the canonical source. Extract assistant text and locate the content boundary by section anchor (preferred) or line range (fallback).

```bash
bash scripts/extract-anchor-range.sh \
  --jsonl ~/.claude/projects/<scope>/<project-uuid>.jsonl \
  --start-anchor "^## LOG #2 — Hooks: Complete Reference" \
  --end-anchor "^## LOG #3 — Subagents: Complete Reference" \
  --output "$CLAUDE_JOB_DIR/extracted-log-2.md"
```

The script:
1. Filters `assistant`-type entries, concatenates `.message.content[].text` via `jq`.
2. Greps for the start anchor; bails with non-zero exit if not found (Universal Rule #12: verify before acting).
3. Greps for the end anchor; if absent, falls back to EOF.
4. Writes verbatim slice to `$CLAUDE_JOB_DIR` (background-session safe path).

**Verbatim is non-negotiable.** The transcript is the canonical version; re-authoring breaks the audit trail. Future drift-reconciliation by `artifact-resurfacing` should be able to grep the transcript for the same string and find it.

### Phase 2 — Frontmatter (canonical, mirrors LOG #1 precedent)

Prepend the standard frontmatter block. Required fields:

```yaml
---
title: <Subject> — <Reference-Type>
date: <YYYY-MM-DD of original delivery, not promotion date>
scope: home (~/.claude/plans/) | repo (<path>) | organ (<organ>)
status: reference
extracted_from: <jsonl-path>
extraction_date: <YYYY-MM-DD of promotion>
related:
  - <sibling-artifact-paths>
  - <upstream-doc-urls>
  - <series-siblings if part of a series>
---

# <Title>

## Why this file exists

<One-paragraph rationale: who delivered it, when, why it's being promoted now, what precedent it mirrors.>

---

<verbatim extracted content>
```

For series content (LOG #N), the `related:` block includes all siblings in the series, allowing later members to grep-discover earlier ones via the cross-link.

```bash
python3 scripts/propose-frontmatter.py \
  --title "Claude Code Hooks — Complete Options Reference" \
  --date 2026-05-20 \
  --scope home \
  --extracted-from ~/.claude/projects/-Users-4jp/9cb55c4d-3191-4b61-a8e8-192e4710affb.jsonl \
  --series engine-log \
  --series-index 2 \
  --body "$CLAUDE_JOB_DIR/extracted-log-2.md" \
  --output ~/.claude/plans/2026-05-20-hooks-options-reference.md
```

The script enforces the schema, prepends frontmatter, prints the resulting file path. Slug convention: `YYYY-MM-DD-<topic-slug>-options-reference.md` for engine-log series; `YYYY-MM-DD-<topic-slug>.md` for one-offs.

### Phase 3 — Propagate (the chezmoi gotcha workaround)

Bash-redirect / `cat >` file creation bypasses the PostToolUse `Write|Edit` hook that fires `domus-memory-sync`. The runtime file exists but never reaches chezmoi-source or remote. **This is a documented silent-failure class** — see `references/known-promotion-pitfalls.md`.

Manual recovery is the chezmoi-documented protocol:

```bash
bash scripts/propagate-via-chezmoi.sh ~/.claude/plans/2026-05-20-hooks-options-reference.md ~/.claude/plans/2026-05-20-subagents-options-reference.md
```

The script:
1. Runs `chezmoi add <runtime-paths>` to copy runtime → source.
2. autoCommit+autoPush fires from chezmoi config (no separate `git push` needed for the chezmoi-source repo).
3. Verifies parity: `git -C <chezmoi-source> log @{u}..HEAD --oneline` should be empty.
4. If parity check fails, surfaces the divergence to the user and stops.

For non-chezmoi-managed plan files (per-repo `.claude/plans/`), the script falls back to `git add` + manual-commit-and-push surfacing.

### Phase 4 — Register (in any applicable series)

A solitary promoted artifact is durable. A *series* member needs registration so future members can discover the canonical series register.

For the engine-log series (`LOG #N` pattern), update `references/engine-log-series.md` in this skill with the new entry:

```markdown
| N | YYYY-MM-DD | Topic | Slug | Genesis session |
|---|---|---|---|---|
| 1 | 2026-05-20 | statusLine | 2026-05-20-statusline-options-reference | 9cb55c4d |
| 2 | 2026-05-20 | Hooks | 2026-05-20-hooks-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| 3 | 2026-05-20 | Subagents | 2026-05-20-subagents-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| ... | ... | ... | ... | ... |
```

For ad-hoc one-off promotions (not part of a series), no register update needed — the artifact's frontmatter `related:` cross-links suffice.

If promotion exposes a new silent-failure class (e.g., a new way auto-sync gets bypassed), append a row to