# Phase 33: Fresh-Start Commune + Auto-Resume - Context

**Gathered:** 2026-05-17
**Status:** Ready for planning

<domain>
## Phase Boundary

Two coordinated `/spt:live` skill flows:

1. **First-commune flow (FRESH-*)** — when `/spt:live` is invoked against an identity that pick-spec classifies as `kind:"prompt-new"` (FRESH-01) OR an identity whose `$LIVE psyche-download` returns `NO-CONTEXT` (FRESH-02), the skill surfaces a synthesized first-context summary and an explicit "anything to add, or proceed to init?" AskUserQuestion BEFORE `$LIVE start` runs.
2. **Auto-resume flow (AUTO-*)** — `/spt:live --auto` (no positional arg) resumes the most-recently-active live agent with a confirmation hop and surfaces any clear "next body of work" from the resumed agent's psyche-download payload; SessionStart hook emits a `<spt-live-auto-pick>` block on fresh startup to surface the auto-pick at session boot; a curated set of casual-language triggers route into `--auto`.

Touches:
- `plugin/spt/skills/live/SKILL.md` — first-commune branch under "ID Recollection" Step 2 dispatch; new `--auto` Step in skill body; description frontmatter rewrite for casual-language triggers; argument-hint update.
- `src/owl/plugin_session_start.rs` — emit `<spt-live-auto-pick>` XML block under the AUTO-03 allow-list predicate (research flag from STATE.md: predicate + 15+/15+ test corpus required pre-coding).
- `.planning/REQUIREMENTS.md` — strike FRESH-04 and FRESH-05 per D-03 (sentinel + cleared_at unnecessary; natural state transition covers single-fire).
- `.planning/ROADMAP.md` Phase 33 — revise success criterion 2 (sentinel + cleared_at language removed) in lockstep with REQUIREMENTS.md amendment.

No new binary subcommand. No new Rust schema fields. No new on-disk sentinel artifacts. The skill composes the first-commune summary via Self's session memory + project file synthesis at invocation time.

**REQUIREMENTS.md amendment required** — strike FRESH-04 and FRESH-05; revise FRESH-06 wording to reflect natural-consequence rather than active suppression. Doc-only commit at the top of Plan 01 (mirrors Phase 31 D-11 and Phase 32 LIST-04 amendment patterns).

</domain>

<decisions>
## Implementation Decisions

### First-Commune Summary Composition

- **D-01: FRESH-01 summary = in-skill synthesis (no binary path).** Skill instructs Claude to compose the first-commune summary from two sources, ordered by priority:
  1. **Primary**: Self's session memory — what the user and Claude have done in the current session so far (this IS the agent's first context).
  2. **Secondary**: Short project brief — read `README.md`, `CLAUDE.md`, and any project state file (e.g., `.planning/STATE.md` if present) to summarize current project state and progress.

  No new binary subcommand; synthesis is a skill-instruction at the AskUserQuestion call site. The synthesized text fills the `{first commune summary}` slot in the FRESH-03 prompt template verbatim.

- **D-02: FRESH-02 summary path = identical to FRESH-01.** When `$LIVE psyche-download` returns `NO-CONTEXT` for a known identity, the skill uses the SAME synthesis path as D-01. No special "prior-existence" annotation. NO-CONTEXT is treated as a blank-slate state — nothing useful to recover means nothing useful to differentiate.

### Sentinel + cleared_at (Drop both)

- **D-03: REQUIREMENTS.md amendment — strike FRESH-04 (sentinel) and FRESH-05 (cleared_at).** Neither artifact is necessary. Reasoning:

  - The "single-fire" intent is satisfied by natural state transition: once ANY commune lands (first-commune answer, regular commune, OR auto-fired echo-commune per Phase 29 AUTO-EC), `psyche-download` returns content instead of `NO-CONTEXT`. FRESH-02 stops firing automatically.
  - The "cleared vs never-had" distinction is moot when re-firing on a truly empty state is the *correct* user-facing behavior. A user who explicitly ran `/spt:clear-psyche` and then invokes `/spt:live <id>` SHOULD be re-prompted with the first-commune flow — they have wiped context and effectively want to start fresh.
  - Case-C analysis (proceed-to-init without ever communing): extremely improbable because FRESH-02 itself prompts the user to provide a first commune; even absent that, echo-communes auto-fire on `/clear` and `/compact`. A live agent reaching a state of zero psyche content after a successful start is vanishingly rare and re-prompting in that edge case is acceptable.

  Plan 01 begins with a REQUIREMENTS.md + ROADMAP.md amendment commit striking these two requirement IDs.

- **D-04: FRESH-06 (fork/revive suppression) becomes a natural consequence — reword the requirement.** Original FRESH-06 implies active suppression of the first-commune flow on fork/revive paths. With D-03 in place, fork and revive paths bypass first-commune naturally:
  - `$LIVE fork <src> <new>` — copies psyche-md from `<src>` to `<new>`. The new identity's `psyche-download` returns content, not `NO-CONTEXT`. FRESH-02 doesn't fire.
  - `$LIVE revive <id>` — operates on an identity that already has context (revive is only meaningful for known agents with prior psyche state). `psyche-download` returns content. FRESH-02 doesn't fire.

  Reword FRESH-06 to: "first-commune branch only fires on the FRESH-01 (pick-spec kind:prompt-new) and FRESH-02 (psyche-download NO-CONTEXT) trigger conditions; fork and revive paths bypass by virtue of routing through psyche-download first."

### Next-Work Extraction (AUTO-02)

- **D-05: Two-step extraction order — structured marker, then Claude synthesis.** AUTO-02 "any clear next body of work" surfacing:
  1. Skill scans the resumed agent's `$LIVE psyche-download` payload for a structured H2 marker (see D-06).
  2. If no marker matches, skill instructs Claude to synthesize a 1-2 sentence "here's where we left off, next step looks like X" summary from the psyche-download output.

  Explicitly **NOT** used: surfacing the "last commune body" (chronological tail of the Pulse Log). Last-commune content is too noisy and often stale relative to the agent's current intent.

- **D-06: H2 marker set = `## Current Focus | ## Next Up | ## Next Steps`.** Skill scans for the FIRST match among these three exact (case-sensitive) H2 markdown headers; surfaces the matched section verbatim until the next H2 boundary. `## Current Focus` is the existing convention (e.g., doyle's psyche-context.md memformat). The other two markers tolerate agent-authoring variation. No regex fuzz-matching; exact-string match only to keep skill logic trivial.

### Casual-Language Triggers (AUTO-05/06)

- **D-07: Enforcement = skill description wording only. No in-skill body guard.** AUTO-06's "ambiguous phrases rejected" rule is satisfied by:
  1. Curating the `/spt:live` skill's `description:` frontmatter to list EXPLICIT accepted phrases (D-08) and EXPLICIT non-triggers (D-08 rejected set).
  2. Relying on Claude Code's natural-language skill dispatcher to honor the description's specificity.
  3. AUTO-07's mandatory `AskUserQuestion` confirmation hop BEFORE any `$LIVE start` invocation serves as the safety net for any dispatcher false-positive — if a user is mis-routed into `--auto`, the confirmation hop gives them a clean exit.

  No regex/predicate inside the skill body. Two enforcement layers (description curation + AUTO-07 confirmation) are sufficient.

- **D-08: Accepted casual-language trigger phrases (exactly 8).** All contain BOTH `live` and either `agent` or `work` — satisfies AUTO-06's "explicit live/agent reference" rule:
  - `continue live work`
  - `resume live work`
  - `continue live agent`
  - `resume live agent`
  - `live agent continue`
  - `live agent resume`
  - `live work continue`
  - `live work resume`

  Explicitly **rejected** (called out in description as non-triggers): `keep going`, `resume work`, `continue` (bare). These bare phrases must NOT route to `--auto`.

### `--auto` Edge-Case Dispatch (AUTO-01)

- **D-09: `--auto` on non-resumable pick-spec kinds falls through to normal `/spt:live` flow.** AUTO-01 specifies behavior for `kind:"auto"` (auto-launch) and "otherwise present most-recent for confirmation". The "otherwise" includes:
  - `kind:"pick"` (2+ offline agents): present `options[0]` (already sorted last_active desc per pick-spec convention) for AskUserQuestion confirmation; on yes → `$LIVE start options[0].label`; on no → fall through to normal pick flow.
  - `kind:"prompt-new"` (0 known agents) → fall through to normal `/spt:live` flow (ID Recollection Step 2 prompt-new dispatch — starter AskUserQuestion).
  - `kind:"all-live"` (all known online) → fall through to normal `/spt:live` flow (ID Recollection Step 2 all-live dispatch — Fork-each AskUserQuestion).

  `--auto` is a no-op enhancement on `prompt-new` and `all-live`. Never errors; never refuses; never emits stderr hint.

### Claude's Discretion

- **SessionStart `<spt-live-auto-pick>` XML payload shape (AUTO-03)** — exact tag name, child elements vs inline JSON, whether to wrap pick-spec output verbatim or add metadata. Flagged in STATE.md as research-required pre-coding. Planner / researcher decides.
- **AUTO-03 allow-list predicate exact env-var set** — confirmed gates: `source = "startup"` (not `"clear"`/`"compact"`), no live perch attached to current `parent_pid`, no `OWL_HANDOFF_CHILD`, no `SPT_PSYCHE_WRAPPER`. Audit for additional subagent indicators during research phase. Flagged in STATE.md.
- **15+/15+ AUTO-03 test corpus design** — fixture shapes for should-fire vs should-NOT-fire startup contexts. Flagged in STATE.md.
- **Exact wording of FRESH-03 surface text** when SessionStart auto-fires `<spt-live-auto-pick>` — versus when user invokes `--auto` manually. May want a one-line distinguishing prefix; finalize during planning.
- **Plan split** — likely 3 plans (FRESH bundle / AUTO --auto skill flow / AUTO-03 SessionStart hook + test corpus), but Plan 01 must include the REQUIREMENTS.md/ROADMAP.md amendment per D-03/D-04. Final boundary at planner's discretion.
- **AUTO-08 argument-hint exact form** — `argument-hint: "<id> [--period <seconds>] | [--auto]"` vs `argument-hint: "[<id>] [--period <seconds>] [--auto]"`. Pick during Plan 02 to satisfy Phase 32 HINT-04 YAML quoting rules.
- **`AUTO-01` "most-recently-active" tie-breaker for `kind:"pick"`** — pick-spec already sorts `last_active desc, then id asc` (Phase 31 D-12 / pick_spec.rs:155). Skill uses `options[0]` deterministically. No alternate sort needed.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase requirements + planning artifacts
- `.planning/REQUIREMENTS.md` FRESH-01..FRESH-06, AUTO-01..AUTO-08 — 14 requirements. **FRESH-04 and FRESH-05 to be struck per D-03; FRESH-06 to be reworded per D-04.** Plan 01 begins with the amendment commit.
- `.planning/ROADMAP.md` Phase 33 — goal + 5 success criteria. **Success criterion 2 to be revised in lockstep with REQUIREMENTS.md amendment** (drop sentinel + cleared_at language). Success criteria 1, 3, 4, 5 unchanged.
- `.planning/STATE.md` "Research Flags" section — Phase 33 flagged for CP-3 allow-list predicate + CP-4 test corpus design steps pre-coding (no full `/gsd-research-phase` required, but research surfacing required in plan).

### Cross-references to prior phase decisions
- `.planning/phases/31-picker-correctness/31-CONTEXT.md` D-12 — `kind:"all-live"` envelope shape + D-11 amendment-commit pattern (Plan 01 mirrors this). pick-spec sort order convention (`last_active desc, then id asc`) carries forward to AUTO-01 `options[0]` selection.
- `.planning/phases/32-list-overhaul-skill-hint-audit/32-CONTEXT.md` D-02..D-08 — `info.json.project_history` field + repo-name derivation helpers (informational only — Phase 33 does not consume `--here` but planner should know these exist). D-17 three-plan split pattern + D-18 regression-guard test pattern as reference for Phase 33's plan structure. AUTO-08 argument-hint update per HINT-04 YAML quoting rules.

### Core skill surface
- `plugin/spt/skills/live/SKILL.md` — `description:` frontmatter (rewrite per D-07/D-08), `argument-hint:` frontmatter (update per AUTO-08), Step 1 + Step 2 ID Recollection dispatch table (add first-commune branch + `--auto` step), Cancel handling block (audit for `--auto` interaction).
- `plugin/spt/skills/live/SKILL.md:138-189` — current Step 2 dispatch on pick-spec `kind` field. First-commune branch attaches under `kind:"prompt-new"` (FRESH-01); FRESH-02 trigger is a separate pre-`start` predicate run by the skill after psyche-download.

### Pick-spec interaction surface
- `src/live/pick_spec.rs` — five kinds: `auto`, `pick`, `prompt-new`, `all-live`, `resolve`. All schema-v1 frozen (no reshape allowed). AUTO-01 dispatches on `kind` field via existing emitters; no new kind required.
- `src/live/pick_spec.rs:447` — test `pick_one_online_agent_filters_to_prompt_new` updated in Phase 31; informational only.

### Psyche-download payload + NO-CONTEXT signal
- `src/live/context.rs:444-452` — `run_download` emits `NO-CONTEXT:{id} (no stored context)` on stderr (live_status `S_WARN` tag) when psyche-md file is missing. Skill predicate: detect this stderr token to drive FRESH-02 trigger. Confirm via planning whether the predicate keys on stderr substring or exit-code variant.
- `src/live/context.rs:431-437` — `download_payload_for_injection` strips Pulse Log; SessionStart injection path. Distinct from `run_download` (CLI path). Confirm AUTO-03 hook uses which variant.
- `src/live/context.rs:575-582` — `run_clear` removes psyche-md file. After D-03, no change to this function (cleared_at field NOT added). Clear-psyche remains pure remove.

### SessionStart hook + auto-pick emission site (AUTO-03)
- `src/owl/plugin_session_start.rs:10-46` — `run` entry. AUTO-03 emission point is after the existing `inject_reorientation_if_needed` branch (Step 6) and before `resume::run_with_input` (Step 6 delegation). Predicate gates: `source = "startup"` from stdin JSON, no live perch on `parent_pid` (use existing `find_perch_by_parent_pid` helper at hook_output), no `OWL_HANDOFF_CHILD` or `SPT_PSYCHE_WRAPPER` env vars set.
- `src/owl/resume.rs:223,372` — existing NO-CONTEXT handling in resume path. Confirm AUTO-03 emission does NOT collide with resume's reorientation emission.

### Memformat + ## Current Focus convention (AUTO-02 D-06)
- `psyche.md` (repo root, embedded in binary via `include_str!`) — memformat schema + `<topic name="focus">` template. The `## Current Focus` H2 marker is the rendered surface that the Psyche writes into tracked psyche-md files via commune cycles.
- Existing example: `${SPT_HOME}/psyches/tracked/doyle.md` contains `## Current Focus` section verbatim. D-06 marker set matches this convention.

### Fork + Revive interaction (FRESH-06)
- `src/live/fork.rs:56` — `NO_CONTEXT:{id}` error path when forking from an empty source. Underscored variant (not hyphen). Confirm skill predicate doesn't accidentally match this — fork is a separate command from psyche-download.
- `plugin/spt/skills/live/SKILL.md:166` — D8 fork flow (referenced by Phase 31 D-02 + Phase 33 D-04).
- Revive subcommand source — under `src/live/` (audit for the exact entry point during planning).

### Phase 29 echo-commune auto-fire (D-03 rationale)
- `src/owl/plugin_session_start.rs:21-26` — `snapshot_prior_session_id` + `FIRE_ECHO_COMMUNE_NOW` dispatch. Confirms echo-communes auto-fire on `/clear` and `/compact`, supporting D-03's claim that a true never-communed live agent is vanishingly rare.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `$LIVE pick-spec` (no flag): returns canonical `kind:"auto" | "pick" | "prompt-new" | "all-live"` JSON. Both first-commune (FRESH-01) and auto-resume (AUTO-01) flows dispatch on this. No new kind needed.
- `$LIVE pick-spec --resolve <name>`: cross-repo collision routing. Already used by `/spt:live` Step 3; first-commune branch reuses this for free-text new-name routing under `kind:"prompt-new"`.
- `psyche-download` `NO-CONTEXT:{id}` token (context.rs:449): well-defined signal for FRESH-02 trigger.
- `find_perch_by_parent_pid` (hook_output helper, used at plugin_session_start.rs:96): existing AUTO-03 allow-list gate.
- `is_perch_online` / `perch_dir` / `enumerate_perches` (owlery): unchanged, no new helpers needed.
- AskUserQuestion native "Other" free-text field: the FRESH-03 prompt's "anything to add" follow-up is a plain-text user reply — AskUserQuestion not strictly required for the follow-up, but the skill MAY frame it as AskUserQuestion with options `Proceed to init` + native Other for free-text additions.

### Established Patterns
- **Schema additivity (Phase 26 PLAN-OVERVIEW Q4, Phase 31 D-12)**: never reshape existing pick-spec kinds. Phase 33 honors this — no kind reshape, no new kind required.
- **Doc-amendment-first plan structure** (Phase 31 Plan 01, Phase 32 Plan 01): when a phase's discovered design contradicts a requirement-as-written, Plan 01's first commit amends REQUIREMENTS.md + ROADMAP.md before any code. Phase 33 follows this for D-03 (strike FRESH-04, FRESH-05) and D-04 (reword FRESH-06).
- **Skill-instructs-Claude synthesis** (no new binary subcommand): D-01 and D-05's synthesis-path keep the binary surface tight. Pattern matches existing skill instructions like "absorb context after psyche-download" (live/SKILL.md:102).
- **Description-first dispatcher reliance** (Phase 32 HINT-01 / HINT-04 audit): skill description frontmatter precision drives Claude Code's natural-language match. Phase 33 D-07 leans on this; AUTO-07 confirmation hop is the safety net.
- **AUTO-EC echo-commune auto-fire (Phase 29 D3)**: critical D-03 rationale support — echo-communes auto-fire on `/clear` and `/compact`, ensuring psyche-md content emerges within seconds of any meaningful live session boundary, defeating the never-communed edge case.

### Integration Points
- `plugin/spt/skills/live/SKILL.md` Step 2 dispatch table: first-commune branch attaches under `kind:"prompt-new"`. FRESH-02 trigger lives BEFORE Step 1 `$LIVE start` (skill runs `$LIVE psyche-download` first, branches on NO-CONTEXT). May require small re-ordering of Step 1 + Step 2 flow documentation.
- `plugin/spt/skills/live/SKILL.md` description frontmatter: rewrite for D-07/D-08 trigger phrases. AUTO-05 satisfied here.
- `plugin/spt/skills/live/SKILL.md` argument-hint frontmatter: update for AUTO-08 `[--auto]` addition. Honor Phase 32 HINT-04 YAML quoting if `|` or `[` characters appear in the hint string.
- `src/owl/plugin_session_start.rs`: AUTO-03 emission site between `inject_reorientation_if_needed` and `resume::run_with_input`. Predicate uses existing helpers; no new struct fields on `InfoJson` required.
- `tests/skill_hints.rs` (Phase 32 D-18 regression guard): will assert AUTO-08's updated argument-hint. No new test file needed for the frontmatter side of HINT-05's enforcement; AUTO-03 test corpus is a separate (new) test surface flagged in STATE.md research flags.

</code_context>

<specifics>
## Specific Ideas

- **FRESH-03 prompt template (verbatim, locked by REQUIREMENTS.md)**: `"Here is a summary of my first context as live agent {agent_id}. Anything I should add, or proceed to init? {first commune summary}"`. The `{first commune summary}` slot is filled per D-01/D-02 synthesis.
- **D-08 trigger phrase list (exactly 8)**: must appear verbatim in the `/spt:live` skill description frontmatter to satisfy AUTO-05 dispatcher routing.
- **D-08 rejected phrases**: `keep going`, `resume work`, bare `continue` — call out explicitly in description as non-triggers (e.g., `"Does NOT route to --auto: 'keep going', 'resume work', 'continue' (bare)."`).
- **REQUIREMENTS.md amendment text (D-03)**: strike FRESH-04 and FRESH-05 entries entirely; do NOT replace with sentinel-less wording. The single-fire intent is now an emergent property of the FRESH-01/02 predicates + Phase 29 echo-commune auto-fire, not an artifact-backed contract.
- **REQUIREMENTS.md amendment text (D-04)**: reword FRESH-06 to: `"Fork (\`$LIVE fork\`) and revive paths bypass the first-commune branch naturally — both paths route through \`$LIVE psyche-download\` first, which returns content (not NO-CONTEXT) for any forked or revived identity. No active suppression mechanism required."`.
- **ROADMAP.md Phase 33 success criterion 2 amendment**: drop sentinel + cleared_at language. Reword to reflect the natural-transition rationale (echo-commune auto-fire defeats double-fire; cleared psyches re-fire correctly).
- **D-06 H2 marker matching**: exact case-sensitive string match on `## Current Focus`, `## Next Up`, `## Next Steps`. No trimming of inline trailing content (e.g., `## Current Focus (gen 45)` is treated as a match because the prefix matches). Confirm prefix-vs-exact during planning.
- **D-09 fall-through to normal flow**: `--auto` on `kind:"prompt-new"` and `kind:"all-live"` produces NO user-visible difference from invoking `/spt:live` without `--auto`. Planner may want a debug-level stderr breadcrumb (`AUTO_FALLTHROUGH:{kind}`) to aid diagnosis, but it's not user-facing.

</specifics>

<deferred>
## Deferred Ideas

- **AUTO-D1 (task-level auto-resume)**: starts the next action without confirmation. Explicitly out of scope — AUTO-07 mandates confirmation hop. Re-evaluate in a future phase if a concrete user need surfaces.
- **AUTO-D2 (decorator on AUTO-07 confirmation)**: surface last commune body summary inline in the AUTO-07 confirmation prompt. Composes with D-05 (which deliberately excludes last-commune surfacing for the next-work pane); if AUTO-D2 is implemented later, the two surfaces need clear visual separation. Out of Phase 33 scope.
- **SessionStart auto-pick rich payload**: AUTO-03's `<spt-live-auto-pick>` XML is currently planned to carry pick-spec JSON only. Future extension could include preview of D-05's next-work surface so the user sees "where we'd resume" without invoking the skill. Out of scope.
- **Casual-language trigger telemetry**: optional log of how often each D-08 phrase routes correctly vs falls through to AUTO-07 cancel. Useful for tuning the description; not in Phase 33.
- **Trigger-phrase expansion to non-English locales**: D-08 phrases are English-only. Future i18n consideration; out of scope per the project's English-only convention.
- **`--auto` + `--period`**: should `--auto` accept `--period <seconds>` and pass it through to `$LIVE start`? D-09 fall-through implies yes for the launching path. Confirm during planning; flag if any surprise interaction with the SessionStart auto-pick path.
- **first-commune flow when invoked from SessionStart auto-pick**: if AUTO-03 fires `<spt-live-auto-pick>` and the resumed agent's payload yields NO-CONTEXT, does the user see first-commune through SessionStart's surface? Likely yes (composes naturally), but confirm during planning.

</deferred>

---

*Phase: 33-fresh-start-commune-auto-resume*
*Context gathered: 2026-05-17*