# Requirements Archive: SPT v1.7.1 Seamlessification II **Defined:** 2026-05-16 **Shipped:** 2026-05-18 **Audit:** PASSED (39/39 verified end-to-end) **Core Value:** Reliable, zero-dependency agent-to-agent messaging that just works on any machine, with a live-agent layer that survives `/clear`, `/compact`, binary handoffs, and orphan boundaries without losing context. **Milestone Goal:** Polish round on live-agent friction — listing/picker correctness, skill hint surface, fresh-start commune prompt, auto-resume affordance, plugin-update changelog notification. ## v1 Requirements — Final State All 39 v1 requirements VERIFIED. Categories grouped by phase ownership. ### Picker Correctness (PICK) — Phase 31 - [x] **PICK-01**: `$LIVE pick-spec` emits `kind:"all-live"` when every known agent in the current repo is online. - [x] **PICK-02**: `kind:"all-live"` envelope includes online agent identities (label + last_active + cwd-match flag). - [x] **PICK-04**: Existing v1 kind discriminators (`auto`, `pick`, `prompt-new`) unchanged — D5 schema freeze preserved (additive only). - [x] **PICK-05**: `/spt:live` dispatch table handles `kind:"all-live"` as "fork or pick a new name" — never auto-attaches. - [x] **PICK-06**: Test `pick_one_online_agent_filters_to_prompt_new` renamed to `pick_one_online_agent_emits_all_live` and asserts new behavior. **PICK-03 struck:** Former item #3 (`online: bool` field on `kind:"pick"`) deferred to v1.8+ per Phase 31 CONTEXT D-10/D-11. ### List Overhaul (LIST) — Phase 32 - [x] **LIST-01**: `$OWL list` / `$LIVE list` default to online-only. - [x] **LIST-02**: `--all` includes offline. - [x] **LIST-03**: `--offline` exclusively offline; `conflicts_with` `--all`. - [x] **LIST-04**: `--here` filters by `info.json.project_history` repo-name match. Orthogonal to `--all`/`--offline`. - [x] **LIST-05**: Empty-online list emits stderr discovery hint `No online listeners. Pass --all to include offline.` (Minor wording deviation from spec literal `...offline perches.`; behavioral contract met.) - [x] **LIST-06**: `src/live/list.rs` refactored to share `ListMode` + filter with `src/owl/list.rs` via `src/common/list_filter.rs`. - [x] **LIST-07**: `perch_has_repo_history` extracted to `src/common/owlery.rs`; reused by both list flows. - [x] **LIST-08**: Golden fixtures regenerated for new default; orphan fixtures deleted. ### Skill Hint Audit (HINT) — Phase 32 - [x] **HINT-01**: Every `/spt:*` skill ships an `argument-hint:` field (17/17). - [x] **HINT-02**: `list-ready` / `list-live` / `list-psyche` gained `argument-hint: "[--all] [--offline] [--here]"`. - [x] **HINT-03**: Corrected inaccurate hints — `/spt:commune` → `""`, `/spt:psyche-download` → `"[]"`, `/spt:whoami` → `""`. - [x] **HINT-04**: YAML-significant values double-quoted (`listen`, `live`, `revive`, `send` updated). - [x] **HINT-05**: `tests/skill_hints.rs` regression guard (3 test functions, zero `serde_yaml` dep). ### Fresh-Start Commune (FRESH) — Phase 33 - [x] **FRESH-01**: When `/spt:live` invoked with `kind:"prompt-new"`, skill skips `$LIVE psyche-download` and enters first-commune flow. - [x] **FRESH-02**: When `/spt:live` proceeds with existing identity but `$LIVE psyche-download` returns `NO-CONTEXT`, skill enters first-commune flow. - [x] **FRESH-03**: First-commune flow surfaces verbatim template "Here is a summary of my first context as live agent {agent_id}. Anything I should add, or proceed to init? {first commune summary}". - [x] **FRESH-06** (reworded): Fork and revive paths bypass first-commune branch naturally — both route through `$LIVE psyche-download` first, which returns content (not NO-CONTEXT) for any forked or revived identity. No active suppression mechanism required. **FRESH-04, FRESH-05 struck:** Per Phase 33 CONTEXT D-03 — replaced by natural-transition contract (no sentinel, no `cleared_at`). ### Auto-Resume + Casual Activation (AUTO) — Phase 33 - [x] **AUTO-01**: `/spt:live --auto` runs `$LIVE pick-spec`; auto-launches on `kind:"auto"`, otherwise confirmation hop then launch. - [x] **AUTO-02**: Post-launch, skill surfaces "any clear next body of work" — domain-agnostic — sourced from psyche-download H2 markers (`## Current Focus` / `## Next Up` / `## Next Steps`) with Claude synthesis fallback. - [x] **AUTO-03**: SessionStart hook emits `` XML block via 6-gate allow-list predicate (source = startup, no live perch attached to parent_pid, no subagent env vars). - [x] **AUTO-04**: SessionStart auto-pick rejects silently inside subagent/wrapper contexts — no stderr leakage. 4 integration tests assert silence. - [x] **AUTO-05**: `/spt:live` `description:` frontmatter lists 8 casual-language triggers ("resume my agent", "wake up my agent", "live agent continue/resume", etc.). - [x] **AUTO-06**: Bare ambiguous phrases ("keep going", "resume work", `"continue" (bare)`) explicitly REJECTED in "Does NOT route here" block. Regression test enforces. - [x] **AUTO-07**: Every `$LIVE start` via casual path fires AskUserQuestion confirmation hop before launch. - [x] **AUTO-08**: `argument-hint: " [--period ] | [--auto]"` (double-quoted per HINT-04); pinned in `tests/skill_hints.rs`. ### Version-Change Changelog (VERS) — Phase 34 - [x] **VERS-01**: `$SPT_HOME/last-seen-version.json` sentinel sibling to `owlery/`. Single source of truth via `src/common/owlery.rs::sentinel_path()`. - [x] **VERS-02**: Stop hook in `src/owl/hook_idle.rs` gated on perch resolution; compares `env!("CARGO_PKG_VERSION")` against sentinel (debug-only `SPT_OVERRIDE_PKG_VERSION` test seam). - [x] **VERS-03**: First-install (sentinel missing) silently writes current version; no prompt. - [x] **VERS-04** (amended by hotfix 6om): AskUserQuestion with **three** options (`Yes, full changelog` / `Yes, highlights only` / `Skip`). "Remind me later" dropped — rolled the sentinel back causing infinite re-fire (UAT-confirmed pathology). Question text includes `step_count` when > 1; floors at 1 on degraded path (n4b fix). - [x] **VERS-05**: Sentinel atomically rewritten via `atomic_write_string` (tmp + rename); pre-write before emission so prompt does not re-fire. - [x] **VERS-06**: Multi-version skip shares the AUQ; `Yes, full changelog` renders interim H2 sections verbatim via `parse_changelog` + `sections_between` (exclusive low, inclusive high). - [x] **VERS-07**: Repo-root `CHANGELOG.md` exists with H2-per-version sections (40 entries 1.5.4 → 1.10.13); `docs/DEPLOY.ps1` syncs into marketplace + cache. - [x] **VERS-08**: VERS-04 (Stop) and AUTO-03 (SessionStart) coexist by hook separation — distinct hook entry points, no shared dispatch path. Collision impossible by construction. - [x] **VERS-09**: Single write site at top of `hook_idle.rs::run()` after perch resolution + OWL_ECHO_COMMUNE + stop_hook_active guards. Atomic via `atomic_write_string`. Binary handoff (Phase 18.4/18.5) does not race. **Amendments after execution:** - **VERS-04 amended via hotfix 260517-6om** — "Remind me later" dropped; transport reworked from `decision:"block"` to silent owl-message via `spool_message_deferred("version-change", ...)`. CHANGELOG entries 1.10.11 / 1.10.12 document the pivot. - **VERS-04/06 hardened via hotfix 260517-n4b** — `step_count.max(1)` floor; `is_informational` extension recognizes `` so primer rides the calm info banner (not "STOP your current task"); DEPLOY.ps1 curation gate enforces TODO-stub-then-curate cycle. CHANGELOG entry 1.10.13. - **DEPLOY.ps1 curation gate hardened via hotfix 260517-wpf** — stub insertion switched from append-at-bottom to insert-above-first-H2. ## v2 Requirements — Deferred (Carried forward to future milestone planning — captured here for archival completeness.) ### Auto-Resume Differentiators (AUTO+) - **AUTO-D1**: Task-level "obvious next body of work" auto-resume (no confirmation). - **AUTO-D2**: Confirmation hop surfaces last commune body summary inline (decorator on AUTO-07). ### Version Differentiators (VERS+) - **VERS-D1**: `dismissed_versions` field in sentinel — user can dismiss a specific version permanently. - **VERS-D2**: `/spt:dismiss-changelog` skill for explicit dismiss control. ### Deploy Integration (HINT+) - **HINT-D1**: `docs/DEPLOY.ps1` runs a frontmatter linter gate; fails deploy if any SKILL.md missing `argument-hint` or fails YAML safety. ## Out of Scope (validated decisions, archived) | Feature | Reason | |---------|--------| | New crate adoption for `--here` repo detection (e.g. `git2`) | Single-binary, zero-runtime-deps constraint | | GSD-coupling in AUTO-02 "next body of work" | spt is wholly decoupled from GSD; surface must be domain-agnostic | | Reading `plugin.json` at runtime for version detection | Phase 18.4/18.5 handoff hazard; `env!("CARGO_PKG_VERSION")` is the only safe source | | Schema-breaking changes to pick-spec v1 JSON | D5 schema freeze (Phase 26-03) — additive new kinds only | | Auto-detecting agent for casual prompts in subagent sessions | CP-3 — would misfire in psyche-wrapper and researcher contexts | | Per-version `changelog-acked-v{ver}` sentinel files | Single `last-seen-version.json` is simpler; multi-file scheme adds GC pressure | | Changelog body extraction from per-milestone files in `.planning/milestones/` | Repo-root `CHANGELOG.md` is the canonical source | ## Final Traceability | Requirement | Phase | Final Status | |-------------|-------|--------------| | PICK-01..02, 04..06 (5) | Phase 31 | Complete + Verified | | LIST-01..08 (8) | Phase 32 | Complete + Verified | | HINT-01..05 (5) | Phase 32 | Complete + Verified | | FRESH-01..03, 06 (4) | Phase 33 | Complete + Verified | | AUTO-01..08 (8) | Phase 33 | Complete + Verified | | VERS-01..09 (9) | Phase 34 | Complete + Verified (with hotfix amendments) | **Coverage:** 39 v1 requirements / 39 verified end-to-end / 0 unsatisfied / 0 orphaned --- *Requirements defined: 2026-05-16* *Milestone shipped: 2026-05-18* *Audit: PASS — see `.planning/v1.7.1-MILESTONE-AUDIT.md`*