--- phase: 34-version-change-changelog plan: 01 subsystem: docs+deploy tags: [doc-amendment, changelog, deploy, keep-a-changelog, stop-hook-pivot] dependency_graph: requires: [] provides: - "Repo-root CHANGELOG.md authored from git-log history (38 entries, Keep-a-Changelog 1.1.0)" - "DEPLOY.ps1 -Bump abort gate + stub-append + CHANGELOG.md sync to MarketSpt + CacheVer" - "Amended VERS-02/04/06/08/09 + ROADMAP SC1/SC2/SC5 per Phase 34 CONTEXT D-12" affects: - "Plan 02 (Rust hook + parser + sentinel) — unblocked: CHANGELOG.md exists with real content for unit + integration tests" - "Plan 03 (block-body Claude instructions + integration test) — unblocked: amended requirements + Stop-hook wording in place" - "Next end-of-milestone DEPLOY.ps1 -Bump patch — maintenance gate live" tech-stack: added: [] patterns: - "Doc-amendment-first plan structure (mirrors Phase 31 D-11, Phase 33 D-03/D-04)" - "Keep-a-Changelog 1.1.0 H2 shape `## [X.Y.Z] - YYYY-MM-DD`" - "DEPLOY.ps1 atomic-rewrite-then-verify pattern (extended to CHANGELOG.md stub)" key-files: created: - CHANGELOG.md modified: - .planning/REQUIREMENTS.md - .planning/ROADMAP.md - docs/DEPLOY.ps1 decisions: - "[Plan 34-01] CHANGELOG.md authored from `git log --grep='chore: bump'` skeleton — 38 entries, ranging v1.5.4 → v1.10.10" - "[Plan 34-01] DEPLOY.ps1 stub-append runs AFTER `git commit` (RESEARCH.md Pitfall 5) so stub stays in working tree only — never staged into the bump commit" - "[Plan 34-01] DEPLOY.ps1 abort gate also triggers on missing CHANGELOG.md (not just on stale TODO marker) so the file becomes a hard prerequisite for -Bump" - "[Plan 34-01] Sync targets: `{Marketplace}/plugin/spt/CHANGELOG.md` AND `{CacheVer}/CHANGELOG.md` (both sibling to plugin.json, not inside `.claude-plugin/`) per CONTEXT D-11" metrics: duration: "~25min (Task 2 CHANGELOG authoring ~15min, well under 90min timebox)" completed_date: "2026-05-17" --- # Phase 34 Plan 01: Doc Amendment + CHANGELOG Genesis + DEPLOY.ps1 Extension Summary One-liner: Doc-amendment-first commit (VERS-02/04/06/08/09 + ROADMAP SC1/2/5 Stop-hook pivot) plus retroactive Keep-a-Changelog 1.1.0 history (38 H2 sections covering v1.5.4 → v1.10.10) plus DEPLOY.ps1 maintenance gate (`-Bump` TODO-marker abort + stub-append + CHANGELOG sync to marketplace + cache). ## Commits | # | SHA | Subject | | - | -------- | ---------------------------------------------------------------------------- | | 1 | dd13d12 | docs(34): amend VERS-02/04/06/08/09 + ROADMAP SC1/2/5 per Phase 34 D-12 | | 2 | ebbb12a | docs(34): create repo-root CHANGELOG.md (Keep-a-Changelog 1.1.0) | | 3 | c3b1f75 | feat(34): DEPLOY.ps1 CHANGELOG.md sync + bump stub/abort gate | ## What Was Done ### Task 1: REQUIREMENTS.md + ROADMAP.md amendment (commit dd13d12) Mirrors Phase 31 D-11 + Phase 33 D-03/D-04 amendment-commit precedent. Amended five VERS-* bullets and three Phase 34 success criteria with the verbatim REPLACEMENT WORDING blocks from CONTEXT D-12: - **VERS-02**: SessionStart → Stop hook (`src/owl/hook_idle.rs`), gated on active perch resolution. - **VERS-04**: yes/no/dismiss → 4-option AUQ (`Yes, full changelog` / `Yes, highlights only` / `Remind me later` / `Skip`). - **VERS-06**: Dropped "never full prose for each interim version" constraint; 4-option AUQ shared between single-step and multi-step. - **VERS-08**: VERS-04 (Stop) + AUTO-03 (SessionStart) coexist by hook separation; no allow-list reconciliation. - **VERS-09**: Single write site at top of `hook_idle.rs::run()`; binary handoff race impossible because Stop hooks don't fire mid-swap. - **ROADMAP SC1**: First Stop hook fire (not SessionStart) silently writes sentinel on fresh install. - **ROADMAP SC2**: Stop hook emits `` block via `decision:"block"` + `reason`; 4-option AUQ; sentinel atomic-written at hook entry; `Remind me later` rolls sentinel back via `$OWL version-remind `. - **ROADMAP SC5**: Hook-separation collision-impossibility statement. Footer update line added under existing FRESH update line: `*Updated 2026-05-17 — VERS-02/04/06/08/09 amended per Phase 34 CONTEXT D-12 (Stop-hook pivot, 4-option AUQ, AUTO-03-coexistence-by-hook-separation).*` ### Task 2: CHANGELOG.md genesis (commit ebbb12a) Authored repo-root CHANGELOG.md in Keep-a-Changelog 1.1.0 format from `git log --oneline --grep='chore: bump'` skeleton. **38 H2 sections** (one per released version surfaced by the bump log; the four "skipped" versions called out in CONTEXT D-09 — 1.9.11, 1.9.6, 1.9.0/1/3/4 — were never bumped in git history and so are naturally absent). H2 shape `## [X.Y.Z] - YYYY-MM-DD` validates against the Plan 02 parser regex `^## \[(\d+)\.(\d+)\.(\d+)\] - (\d{4})-(\d{2})-(\d{2})\s*$`. Per-version bodies are curated prose drawn from `git log --oneline ..` ranges — `### Added` / `### Changed` / `### Fixed` / `### Removed` subsections per Keep-a-Changelog v1.1.0 conventions. Each entry is a 1-to-5-bullet release note focused on user-facing changes (feature adds, bug fixes, removals); pure-internal refactors and code-review nits are collapsed into single bullets where possible. No `[Unreleased]` section. No pre-release suffix versions. No link-reference lines at file bottom. Final size: 178 lines. Authoring time: ~15 minutes (well under the ~90min timebox in plan REVIEW-FIX #10). > [!WARNING] > **HISTORIC NOTE — Task 3 prose below describes a SUPERSEDED design.** > > The DEPLOY.ps1 curation-gate design described in this Task 3 section was found incorrect during the v1.10.13 UAT cycle (post-260517-n4b deploy). The correct, currently-shipping curation gate lives in commit **c99d7c9** (`fix(34): DEPLOY.ps1 curation gate enforces curated CHANGELOG before bump (D-08 round 2 post-UAT)`). > > **Correct implementation summary:** `DEPLOY.ps1 -Bump` inspects `CHANGELOG.md` for a `## [NEW_VERSION]` H2 BEFORE any mutation. If the H2 is absent, the script appends a TODO stub uncommitted and exits 1 (forcing the author to curate before retry). If the H2 contains the bare `TODO: changelog entry` marker, the script aborts. Only a curated H2 entry allows the bump to proceed. > > See: > - commit `c99d7c9` for the shipped script form > - commit `97e5a62` for the round-2 stub-append realignment that preceded c99d7c9 > - `.planning/phases/34-version-change-changelog/34-DISCUSSION-LOG.md` (line ~145) for the design-lock discussion > - gen46 psyche signoff for the final design rationale > - `.planning/phases/34-version-change-changelog/34-03-SUMMARY.md` UAT Amendment section for the closure evidence > > The Task 3 prose below is retained verbatim for historical traceability (it was correct given Plan 01's information state at the time of writing); do NOT re-implement against it. ### Task 3: DEPLOY.ps1 extension (commit c3b1f75) Four discrete insertions per the verified anchor lines in ``. Anchors matched the plan's line citations exactly — no drift, no deviations: 1. **TODO-marker abort gate (line 224, inserted before `# Read Cargo.toml ...` comment):** scans CHANGELOG.md for literal `TODO: changelog entry`; exits 1 if found OR if CHANGELOG.md is missing. 2. **CHANGELOG.md stub-append (line 290, inserted after `Write-SubStep "Committed bump..."`):** appends `## [NEW_VERSION] - YYYY-MM-DD\n\n- TODO: changelog entry\n` to CHANGELOG.md after the bump commit — intentionally unstaged so the next `-Bump`'s abort gate fires until the author fills + commits. `[DRY-RUN]` branch logs the intent without writing. 3. **CHANGELOG.md sync to MarketSpt (line 368, inserted before `Copy plugin.json -> $MarketPluginMeta`):** new `Invoke-Mutation "Copy CHANGELOG.md -> $MarketSpt"` block. 4. **CHANGELOG.md sync to CacheVer (line 498, inserted before `Copy plugin.json -> $CacheVer/.claude-plugin`):** new `Invoke-Mutation "Copy CHANGELOG.md -> $CacheVer"` block (sibling to plugin.json, not inside `.claude-plugin/`, per CONTEXT D-11). ## CHANGELOG.md final H2 Section Count **38 valid H2 sections** matching the Plan 02 parser regex. Bump-commit count from `git log --grep='chore: bump'` is also 38 (delta = 0, well within the plan's `≥ bump_count - 8` floor). ## Verify Surface — No-Bump `-DryRun` Ran `powershell -ExecutionPolicy Bypass -File docs/DEPLOY.ps1 -DryRun` (exit 0). The two new sync substeps surface in expected order: ``` [DRY-RUN] Copy CHANGELOG.md -> C:\Users\decid\.claude\plugins\marketplaces\cplugs\plugins\spt [DRY-RUN] Copy CHANGELOG.md -> C:\Users\decid\.claude\plugins\cache\cplugs\spt\1.10.10 ``` The `-Bump patch -DryRun` exercise (which would surface insertions 1 + 2 in the dry-run trace) was NOT run automatically per the plan's REVIEW-FIX #4 carve-out — it requires a clean working tree, and mid-execution we typically have plan + summary changes staged/unstaged. Task 3's `` block documents the manual reproduction protocol for that exercise. ## Build Smoke Check `cargo test --no-run` completed clean. All 19 test executables (lib unittests + main unittests + 17 integration suites including the new file-drop / plugin-session-start / auto-pick suites) compiled without warnings introduced by this plan. Plan 01 is pure doc/script — no Rust expected to change. ## Deviations from Plan **None — line citations in `` matched current DEPLOY.ps1 exactly.** The plan flagged that DEPLOY.ps1 evolves between phases and that anchor lines should be verified before editing. Verification: the four anchor regions (Cargo.toml dirty-state check ending at line 222; `Write-SubStep "Committed bump: $bumpSha (not pushed)"` at line 287; `Copy hooks/* -> $MarketHooks` ending at line 367; `Copy hooks/* -> $CacheVer/hooks` ending at line 497) all matched the plan-cited line numbers within ±0. Four insertions applied as written. The post-insertion file is now 519 lines (up from 504); each insertion landed at the indicated boundary. ## PowerShell Verify Hygiene (review-fix #3) All blocking verify commands in this plan use PowerShell syntax. They executed cleanly under the project's native shell (PowerShell 5.1). The Bash invocation environment strips `$` variable expansions when commands are passed inline via `-Command`, so multi-statement PowerShell verifies were materialized as `.ps1` script files and invoked via `-File` to preserve `$variable` semantics. This is a tooling note, not a plan deviation — the verify command bodies themselves match the plan verbatim. ## Authentication Gates None. ## Known Stubs None. Plan 01 is pure doc/script; no UI-bearing components introduced. ## Threat Flags None. The four files touched are doc + deploy script; no new network endpoint, auth path, or schema change at a trust boundary. ## Self-Check: PASSED - File `CHANGELOG.md` — FOUND - File `.planning/REQUIREMENTS.md` — modifications retained (5 amendments + footer line) - File `.planning/ROADMAP.md` — modifications retained (SC1/2/5 amendments) - File `docs/DEPLOY.ps1` — modifications retained (4 insertions) - Commit `dd13d12` — FOUND in `git log` - Commit `ebbb12a` — FOUND in `git log` - Commit `c3b1f75` — FOUND in `git log` - `cargo test --no-run` — passes - No-bump `-DryRun` exit 0, two new `Copy CHANGELOG.md` substeps present