# Phase 34: Version-Change Changelog - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-17
**Phase:** 34-version-change-changelog
**Areas discussed:** Hook→prompt emission shape, Changelog source delivery, CHANGELOG.md backfill genesis, Multi-version skip rendering

---

## Gray Area Selection

| Option | Description | Selected |
|--------|-------------|----------|
| Hook→prompt emission shape | Hook mechanism + ordering vs Phase 33 AUTO-03 + sentinel write site + block payload | ✓ |
| Changelog source delivery | Where CHANGELOG.md lives at runtime + parser ownership + format + excerpt body | ✓ |
| CHANGELOG.md backfill genesis | One-shot author vs bin subcommand vs DEPLOY auto-generate; maintenance gate; sync site | ✓ |
| Multi-version skip rendering | (folded into Excerpt body of area 2 + final AUQ shape) | ✓ |

**User's choice:** All 4 areas.

---

## Hook → Prompt Emission Shape

### Round 1: Hook emission mechanism

| Option | Description | Selected |
|--------|-------------|----------|
| XML block via hookSpecificOutput (mirror AUTO-03 Pattern S2) | Phase 33 emit_auto_pick pattern, SessionStart-style | partial — superseded |
| Skill-mediated | New `/spt:changelog` skill owns AUQ + render | |
| Inline context, dispatcher routes | Cross-skill coupling via existing skill | |

**User's choice:** "XML via additionalContext, but only if spt is in use (spt listen/live/revive invoked, or currently in a live agent session). for this reason, the check should be in UserPromptSubmit rather than SessionStart"

**Notes:** Pivot from SessionStart to UserPromptSubmit. Predicate: agent has an active spt perch. Hook resolution in `hook_prompt.rs:31-39` already provides this gate via `find_perch_by_session` / `find_perch_by_parent_pid` early-return.

### Round 2: Emission ordering vs Phase 33 AUTO-03 Step 6.5

User marked n/a — different hook makes the ordering question moot.

### Round 3: Sentinel write site

| Option | Description | Selected |
|--------|-------------|----------|
| Immediately at run() entry, before any emission | Per VERS-05 regardless-of-response, write at top | ✓ (provisionally; later inverted) |
| After version-mismatch detection succeeds | Conditional write tied to mismatch | |
| After full hook run() completes | Defer to end | |

**User's choice:** "Immediately at run() entry, before any emission". Later refined via the Ack-path inversion in the final batch.

### Round 4: Block payload shape

| Option | Description | Selected |
|--------|-------------|----------|
| Minimal {old, new, single_step:bool} | Thinnest hot path | |
| Rich: include rendered excerpt | Couples Rust to CHANGELOG parsing | |
| Just versions, skill body renders | Decouples Rust entirely | |

**User's choice:** "old, new, old_date, new_date, step_count"

**Notes:** Dates surface in payload — drives later decisions about CHANGELOG.md format owning dates inline (`## [X.Y.Z] - YYYY-MM-DD`).

### Round 5: Confirm "spt in use" predicate (after UserPromptSubmit pivot)

| Option | Description | Selected |
|--------|-------------|----------|
| owl_id resolves in hook_prompt.rs | Piggyback existing perch resolution | superseded |
| owl_id + perch is live | Live-agent only | |
| owl_id OR recent owlery activity | Looser timeline gate | |

**User's choice:** "after thinking it through, pivoting again: use the `Stop` hook. if owl_id resolves, block `Stop` with the version-change emission, making the agent share it before Stop again (which then wouldn't block, because the version-change sentinel has been written). --- WHY: because UserPromptSubmit might be a user telling an agent 'go do this' --> user walks away --> version-change AskUserQuestion --> user comes back many minutes later to find no progress due to the version-change question. so it's best if the version-change question comes right before the agent ends their turn."

**Notes:** Second architectural pivot. Final hook = Stop (`hook_idle.rs`). Question lands at end-of-turn, after the agent finishes its current work, before any new turn. Existing perch resolution + `OWL_ECHO_COMMUNE` recursion guard reused verbatim.

---

## Changelog Source Delivery

### Round 1: Runtime source

| Option | Description | Selected |
|--------|-------------|----------|
| include_str! compiled-in | Hermetic, binary bloats with history | |
| Runtime-read from `$CLAUDE_PLUGIN_ROOT/CHANGELOG.md` | DEPLOY syncs to plugin meta dir | ✓ |
| Skill reads from repo / synced location | Defers source-of-truth | |

**User's choice:** "Runtime-read from `$CLAUDE_PLUGIN_ROOT/CHANGELOG.md`"

### Round 2: Parser ownership

| Option | Description | Selected |
|--------|-------------|----------|
| Rust hook does it once | Deterministic, testable | ✓ |
| Rust extracts versions+dates, Claude renders excerpt | Split-of-work | |
| Claude does all of it | Tightest Rust surface | |

**User's choice:** "Rust hook does it once (Recommended)"

### Round 3: CHANGELOG.md format

| Option | Description | Selected |
|--------|-------------|----------|
| Keep-a-Changelog `## [1.10.10] - 2026-05-16` | Industry standard, one regex | ✓ |
| Plain `## v1.10.10 — 2026-05-16` | Friendlier but emdash varies | |
| Bare `## 1.10.10` (date in body) | Decouples version from date | |

**User's choice:** "Keep-a-Changelog: `## [1.10.10] - 2026-05-16` (Recommended)"

### Round 4: Excerpt body shape

| Option | Description | Selected |
|--------|-------------|----------|
| All H2 sections between old<v≤new verbatim | Single rendering policy | partial |
| Single-step verbatim; multi-step summary (per VERS-06) | Closer to VERS-06 wording | |
| Always summary + pointer | Minimal hot path | |

**User's choice:** "Split 'yes' answer option into 'Yes, full changelog' and 'Yes, highlights only'. the latter is the full changelog stripped down to just the most impactful feature adds and fixes, agent's discretion."

**Notes:** User overrides VERS-06's "never full prose" constraint — pushed to user-choice via 4-option AUQ. Highlights extraction = Claude's discretion.

---

## CHANGELOG.md Backfill Genesis

### Round 1: Initial creation

| Option | Description | Selected |
|--------|-------------|----------|
| Author one-shot at Plan 01 start | Manual prose | ✓ |
| Bin subcommand `owl changelog backfill` | Reusable | |
| DEPLOY.ps1 generates-if-missing | Couples to deploy | |

**User's choice:** "Author one-shot at Plan 01 start (Recommended)"

### Round 2: Forward maintenance

| Option | Description | Selected |
|--------|-------------|----------|
| DEPLOY.ps1 -Bump appends stub, author fills | Stub forces format | partial |
| DEPLOY.ps1 -Bump abort if CHANGELOG unchanged | Raw enforcement | partial |
| Manual, no enforcement | No gate | |

**User's choice:** "1 + 2. if changelog is unchanged, DEPLOY.ps1 -Bump appends the stub H2 **without committing it**, outputs that it must be updated and committed before deploy will succeed."

**Notes:** Combined enforcement — stub injection (uncommitted) + abort-on-unchanged-TODO marker gate on next `-Bump`.

### Round 3: Sync target

| Option | Description | Selected |
|--------|-------------|----------|
| `{Marketplace}/plugin/spt/CHANGELOG.md` | Sibling to plugin.json | ✓ |
| `{Marketplace}/plugin/spt/.claude-plugin/CHANGELOG.md` | Inside .claude-plugin/ | |
| `{Marketplace}/plugin/spt/docs/CHANGELOG.md` | Under docs subdir | |

**User's choice:** "`{Marketplace}/plugin/spt/CHANGELOG.md` (Recommended)"

---

## Final Batch: AUQ Shape + step_count + Dates + Amendment Scope

### Round 1: AskUserQuestion 4-option shape

| Option | Description | Selected |
|--------|-------------|----------|
| Yes-full / Yes-highlights / No / Dismiss | Sentinel pre-written at hook time | superseded |
| Yes-full / Yes-highlights / Skip | Three options | |
| Yes-full / Yes-highlights / No / Dismiss, sentinel tied to choice | Risks re-fire | |

**User's choice:** "Yes-full / Yes-highlights / Remind me later / Skip --- 'Remind me later' just surfaces on the next Stop hook (no extra code, just foregoes sentinel update)"

**Notes:** "Remind me later" introduces sentinel-rollback path. Clarified in follow-up round below.

### Round 2: step_count

| Option | Description | Selected |
|--------|-------------|----------|
| Count of H2 sections between old (exclusive) and new (inclusive) | Single-step = 1, multi = N | ✓ |
| step_count drives option set | Asymmetric UX | |
| Don't surface in prompt body | Carry in payload only | |

**User's choice:** "Count of H2 sections between old (exclusive) and new (inclusive) (Recommended)"

### Round 3: Dates source

| Option | Description | Selected |
|--------|-------------|----------|
| Parsed from CHANGELOG.md H2 line | Author-authoritative | ✓ |
| git commit timestamp of bump commit | git dep at hook time | |
| Skip dates entirely | Just versions | |

**User's choice:** "Parsed from CHANGELOG.md H2 line (Recommended)"

### Round 4: REQUIREMENTS.md / ROADMAP.md amendment scope

| Option | Description | Selected |
|--------|-------------|----------|
| VERS-02, 04, 06, 08, 09 | Hook pivot + AUQ-shape + multi-version + coexistence + write-site | ✓ |
| Plus VERS-07 | Also lock CHANGELOG.md format + sync target | |
| Minimal: VERS-02, VERS-09 only | Hook pivot only | |

**User's choice:** "VERS-02, VERS-04, VERS-06, VERS-08, VERS-09 (Recommended)"

### Round 5: Sentinel-write mechanism reconciliation ("Remind me later" path)

| Option | Description | Selected |
|--------|-------------|----------|
| New `owl version-ack` invoked on Yes/Skip | Sentinel write coupled to user intent | inverted |
| Skill-mediated `/spt:changelog-prompt` | New skill surface | |
| Block-body inline instructions, no new subcommand | Claude does file IO directly | |

**User's choice:** "like option 1 but inverted: `$OWL version-remind` clears the sentinel, with sentinel write being the default Stop hook behavior. this way the most-used paths (Yes/Skip) have the least UX bloat."

**Notes:** Stop hook writes new-version sentinel at run() entry by default. `$OWL version-remind <old>` subcommand rolls sentinel back to `<old>`. Claude invokes on `Remind me later` only.

### Follow-up clarification: `version-remind` invocation arg

User clarified: "note that the agent will need to actually call it like `$OWL version-remind <old version>` so that the rollback knows which old version to set within the `%LOCALAPPDATA%/spt/` dir"

**Notes:** Locked `$OWL version-remind <old version>` invocation. `<old version>` is a literal positional arg (e.g. `$OWL version-remind 1.10.9`). Block-body MUST surface the exact invocation string verbatim with the `old` value substituted — Claude has no way to infer the rollback target otherwise.

---

## Claude's Discretion

- Stop hook `decision:"block"` + `reason` injection semantics — research-flag for hooks reference doc confirmation. Fallback to PreToolUse / UserPromptSubmit if broken.
- `<spt-version-changelog>` block exact XML shape (child elements vs JSON-as-text vs hybrid) — planner picks.
- CHANGELOG.md parser regex tightness (`[Unreleased]` reject, link reference lines ignored) — add to RESEARCH.md test corpus.
- `Yes, highlights only` extraction policy framing — final wording in Plan 02.
- Plan split (likely 3 plans) — final boundary at planner's discretion.
- Block payload embedded full excerpt vs Claude-reads-at-yes-time — planner picks.

## Deferred Ideas

- `owl changelog backfill` subcommand
- `/spt:changelog` skill
- Sentinel with reminder flag (richer schema)
- Telemetry for AUQ option distribution
- `Yes, highlights only` rubric formalization (H3 subsections)
- PreToolUse fallback if Stop block doesn't propagate text
- UserPromptSubmit revisit if future security-update phase needs session-start surface