--- phase: 260421-0ws plan: 01 subsystem: docs/deploy tags: [reorientation, session-start-hook, skill-docs, deploy, version-bump] dependency_graph: requires: - Phase 18.8-03 prior deploy (v1.9.2 cache + marketplace baseline) provides: - v1.9.3 binary + plugin with expanded SessionStart reorientation primer affects: - Every /clear and /compact in Claude Code (reorientation text rendered) - DEPLOY.ps1 keep-set (1.9.2 + 1.9.3 preserved for handoff safety) tech_stack: added: [] patterns: - "format!(r#\"...\"#, id = owl_id) named-placeholder idiom — preferred over positional {} x N for multi-reference string templates" key_files: created: [] modified: - src/owl/resume.rs - plugin/spt/.claude-plugin/plugin.json - Cargo.toml - Cargo.lock decisions: - "Use named placeholder `id = owl_id` (not positional `{}` x 7) in inject_reorientation format string — compiler-checked, 1 argument instead of 7, easier to read" - "Bump 1.9.2 -> 1.9.3 as patch (not minor) — docs-only edit + reorientation text expansion, no API/behavior change" - "Skill doc scan re-verified (three files): zero literal `$OWL listen` hits, no edits needed. Mode-word `listen` (in `$OWL poll listen` and `info.json \"mode\":\"listen\"`) preserved per plan scope" metrics: duration_seconds: 221 duration_human: "3 min 41 sec" completed: 2026-04-21 tasks: 3 tasks_auto_completed: 2 tasks_checkpoint_pending: 1 # Task 3 UAT awaits user sign-off files_modified: 4 requirements: - 260421-0ws-R1 # SessionStart reorientation teaches send/receive (auto verify + Task 3 UAT) - 260421-0ws-R2 # Skill docs clean of $OWL listen (auto grep confirmed zero hits) - 260421-0ws-R3 # Plugin + binary at 1.9.3, DEPLOY.ps1 successful (auto verify), UAT pending --- # Quick Task 260421-0ws: Update Skill Docs and SessionStart Hook Summary Expanded SessionStart `inject_reorientation` with a send/receive primer (fire-and-forget vs ring vs send; two-path receive via poll completion and PreToolUse hook XML), verified three skill docs (listen, listen-stop, list-ready) remain clean of the removed `$OWL listen` CLI subcommand, bumped plugin + binary 1.9.2 -> 1.9.3, and deployed via DEPLOY.ps1 to cache and cplugs marketplace. ## What Changed ### src/owl/resume.rs Replaced the body of `inject_reorientation` (lines 355-380). Old payload listed 5 commands in ~9 lines. New payload (23 lines of injected context) teaches: - **Send:** `$OWL deliver` (fire-and-forget), `$OWL ring` (send + wait), `$OWL send` (no-perch variant that creates a temp reply perch), `$OWL reply` (respond to sender). Each line shows the heredoc call shape. - **Receive (two paths, explicit):** idle → background `$OWL poll` task completes with `__REPLY_TO__:\n`; busy → PreToolUse hook injects `` XML into the next tool call context. - **Identity:** auto-detected; trailing-arg override documented. - **Other:** `$OWL list`, `$OWL stop`, `$OWL new-alarm`, `$OWL doctor`. Implementation: switched from positional `{}` x 7 to named placeholder `format!(r#"..."#, id = owl_id)` — one argument, compiler-checked, no counting errors. Outer `hookSpecificOutput` wrap and fallback `unwrap_or_else` branch preserved verbatim. `resume_xml` (dead-perch branch) and `print_skill_context` (active-perch branch) NOT touched — different scenarios with already-correct CLI. ### plugin/spt/.claude-plugin/plugin.json `"version": "1.9.2"` -> `"version": "1.9.3"`. Indentation preserved. ### Cargo.toml `version = "1.9.2"` -> `version = "1.9.3"` (line 3). ### Cargo.lock Auto-synced owl crate `version = "1.9.2"` -> `version = "1.9.3"` during first `cargo check` after Cargo.toml bump. Staged manually (DEPLOY.ps1 does not touch Cargo.lock per Phase 18.8-03 Cargo.lock-sync note). ### plugin/spt/skills/{listen,listen-stop,list-ready}/SKILL.md **No changes.** Plan's audit findings predicted zero literal `$OWL listen` hits across these three files. Re-scan during Task 1b confirmed: - `listen/SKILL.md`: uses `$OWL poll [mode] --setup` (current). Mode-word `listen` appears as CLI argument value + `/spt:listen` slash-command name — both legitimate, preserved. - `listen-stop/SKILL.md`: uses `$OWL stop` / `$OWL stop --all`. Zero hits. - `list-ready/SKILL.md`: uses `$OWL list`. Zero hits. Repo-wide confirmation: `grep "\$OWL listen" src/ plugin/ docs/DEPLOY.md` returns **zero hits** (historical phase-18.2 plan doc and v1-9 feature-sprint design narrative permitted to still match per plan scope exclusion). ## Commits | Task | Scope | Hash | | --------- | -------------------------------------------------------- | ----------- | | 1 + 2 | Reorientation primer expansion + version bump 1.9.2->1.9.3 + deploy | `ee7b579` | Combined per plan step 2d explicit ordering (commit AFTER DEPLOY.ps1 finishes so marketplace sync completes before spt-repo commit lands). Single atomic commit for resume.rs + plugin.json + Cargo.toml + Cargo.lock. Marketplace commit (separate repo, pushed by DEPLOY.ps1): `3ecdd34` on `cplugs/main` — `cfe1410..3ecdd34`. ## DEPLOY.ps1 Output Highlights - Step 3 (build): `cargo build --release` clean, 3 pre-existing warnings (unused `should_fire`, `check_alive`, `source` field). - Step 4 (marketplace sync): owl.exe + skills/* + hooks/* + plugin.json copied to `~/.claude/plugins/marketplaces/cplugs/plugins/spt/`. - Step 5 (marketplace commit+push): `spt: deploy v1.9.3` committed as `3ecdd34`, pushed successfully to `https://github.com/SaberMage/cplugs.git`. - Step 6-7 (cache sync + prune): new cache dir `~/.claude/plugins/cache/cplugs/spt/1.9.3/` created with owl.exe + skills/ + hooks/ + .claude-plugin/. Keep-set: `1.9.3, 1.9.2`. Pruned: `1.8.11, 1.9.0, 1.9.1` (all removed cleanly, no sharing-violation residue). - Step 8 (legacy cleanup): no manual-install dir at `~/.claude/plugins/spt` — nothing to clean. - Step 9 (installed_plugins.json refresh): `claude plugin install spt@cplugs` reported "Successfully installed plugin: spt@cplugs (scope: user)". Post-deploy `installed_plugins.json` entry: ```json { "scope": "user", "installPath": "C:\\Users\\decid\\.claude\\plugins\\cache\\cplugs\\spt\\1.9.3", "version": "1.9.3", "installedAt": "2026-04-21T07:46:48.968Z", "lastUpdated": "2026-04-21T07:46:48.968Z", "gitCommitSha": "3ecdd349ae902addf0305d76dd6e2132e5238f7c" } ``` ## Verification Results - `cargo check --quiet`: PASSED (3 pre-existing warnings, no new errors). - `cargo test --lib resume::`: PASSED (2 is_worker_perch tests green). - `grep -c "fire-and-forget" src/owl/resume.rs`: **1** (new phrase present). - `grep "\"version\": \"1.9.3\"" plugin/spt/.claude-plugin/plugin.json`: matched line 3. - `grep "version = \"1.9.3\"" Cargo.toml`: matched line 3. - `grep -r "\$OWL listen" src/ plugin/ docs/DEPLOY.md`: **zero hits**. - Deployed `~/.claude/plugins/cache/cplugs/spt/1.9.3/owl.exe --version`: `owl 1.9.3`. - `SPT_TRAMPOLINE_GUARD=1 .../1.9.3/owl.exe --help | grep listen`: **no listen subcommand** (regression confirmed). - Prior-ver dir preserved: `~/.claude/plugins/cache/cplugs/spt/1.9.2/` still on disk (handoff-safe). - `installed_plugins.json` `spt@cplugs` entry: `version: 1.9.3`, `gitCommitSha: 3ecdd349`. ## Deviations from Plan ### [Rule 2 — critical automation] Cargo.lock synced automatically before commit **Found during:** Task 2a. **Issue:** Plan step 2a predicted Cargo.lock would need manual staging ("Stage Cargo.lock for commit in step 2d"). Reality: `cargo check` run during Task 1d already synced `name = "owl" / version = "1.9.3"` in Cargo.lock, so by the time Task 2a `cargo build --release` ran, the lockfile was already current. **Fix:** Staged Cargo.lock in the single combined commit per plan step 2d. No behavior change — plan anticipated this file in the commit list regardless. **Files modified:** Cargo.lock (auto). **Commit:** `ee7b579`. ### [Out of scope — logged to deferred-items.md] Pre-existing test failures **Found during:** Task 2b. **Issue:** `cargo test --release` reported 9 failures across `owl::cleanup::tests::*`, `live::commune::tests::commune_result_bumps_cursor_on_offline_spool`, `live::context::tests::amend_signoff_result_bumps_cursor_after_write`, `live::signoff::tests::signoff_result_bumps_cursor_when_psyche_reachable`, `live::wrapper::tests::passive_ctx_mix_keeps_future_only`, `owl::hook_idle::tests::sentinel_created_for_live_with_psyche_ready`. **A/B verification:** `git stash` all 260421-0ws changes, re-ran `cargo test --release --lib` — 7 failures (same cluster, 2 of the 9 are flakes that appear intermittently). Plan changes are orthogonal to these failures. **Root cause (known):** Parallel test isolation race on shared `SPT_HOME` process-global env var. Documented in STATE.md Phase 18.7 Plan 01 decision — module-local ENV_LOCK mutexes don't coordinate across modules. **Scope determination:** This plan modifies reorientation TEXT + version strings only. Zero code paths touched by these failing tests. Applied executor scope boundary ("only auto-fix issues DIRECTLY caused by the current task's changes"). Not fixed. **Follow-up:** Full detail logged at `.planning/quick/260421-0ws-update-skill-docs-and-sessionstart-hook-/deferred-items.md`. Should be addressed in a dedicated test-isolation refactor phase using the unique-id-per-test sandbox pattern proven in Phase 18.7.1 integration tests. ### No skill doc edits required Plan anticipated this possibility ("expected no-op") — three SKILL.md files already clean of `$OWL listen`. Reading + verifying cost ~zero. Not a deviation from plan *intent*, called out for traceability. ## Authentication Gates None — no auth challenges during build or deploy. `claude plugin install spt@cplugs` ran non-interactively. ## Known Stubs None. All text added to `inject_reorientation` is substantive — no placeholder strings, no TODO/FIXME, no empty branches. ## Threat Flags None. Plan's threat register items T-0ws-01..04 all dispositioned as `accept` (with T-0ws-03 mitigated by explicit `cargo build --release` before deploy — satisfied). Reorientation text is Rust `format!` macro output with owl_id sourced from info.json — no user-controlled input. ## Pending — Task 3 Checkpoint Task 3 is a `checkpoint:human-verify` UAT. Executor is halting here per plan and orchestrator constraint. UAT steps to perform: 1. `/reload-plugins` inside Claude Code (DEPLOY.ps1 does not run this). 2. Restart Claude Code session (close + reopen outer shell or File -> New Window). 3. In a Bash tool call: `$OWL --version` — confirm reports `1.9.3`. 4. Register a listener: `/spt:listen uat-0ws` (or `$OWL poll uat-0ws --setup` with `run_in_background: true`). Confirm `READY:uat-0ws (spt v1.9.3)` in stderr. 5. In same session: type `/compact` — triggers `inject_reorientation` via `plugin_session_start.rs::inject_reorientation_if_needed`. 6. Ask the agent to summarize the reorientation context — it MUST reference: - `$OWL deliver` (fire-and-forget) vs `$OWL ring` (send+wait) vs `$OWL send` (no-perch variant) - Two receive paths: background poll completion AND PreToolUse hook `` XML 7. Confirm `$OWL --help` subcommand list does NOT include `listen` (regression check). 8. (Optional) From a second agent: `$OWL deliver uat-0ws < version 1.9.3: CONFIRMED --- ## Post-checkpoint amendment (2026-04-21) **Trigger:** User asked to verify the primer covered background poll revival. It did not — primer taught send/receive but not the dead-poll detection + revive pattern (scenario experienced first-hand earlier in session when binary handoff 1.9.2→1.9.3 left perch pid="BUSY"). **Amendment commit:** `551ac68` feat(260421-0ws): add poll-revival primer to reorientation (1.9.4) Added block between "Receive messages" and "Other commands" in `inject_reorientation`: ``` Revive dead poll (critical — `$OWL poll` fires once then exits): - Each `$OWL poll {id}` call handles ONE message then exits. After every fire (and after binary handoff), restart it or you stop receiving. - Check status: `$OWL list` — if your entry shows `pid:"BUSY"` or is missing, poll is dead. - Revive: run `$OWL poll {id}` as a BACKGROUND Bash task (`run_in_background: true`). Do this after every message you process AND after any handoff/restart. ``` **Deploy chain:** - 1.9.3 → 1.9.4 (this amendment, commit 551ac68 + marketplace 3ecdd34..6c58800) - 1.9.4 → 1.9.5 (Phase 18.8 code-review-fix pass landed on top, commit 909413c) Current state: binary at `~/.claude/plugins/cache/cplugs/spt/1.9.5/owl.exe` reports `owl 1.9.5`, carries the poll-revival primer. Task 3 UAT now validates expanded primer + 1.9.5 deploy.