ticket: use base32 project record ids

2026-06-09 22:10:47 +09:00
parent 0803bc3725
commit 4203988d74
798 changed files with 477 additions and 105 deletions
@@ -0,0 +1,54 @@
+---
+title: "Add Pod archive and fresh-start path"
+state: "planning"
+created_at: "2026-06-07T23:45:30Z"
+updated_at: "2026-06-08T03:49:14Z"
+queued_by: "workspace-panel"
+queued_at: "2026-06-08T03:48:46Z"
+---
+
+## Background
+
+Panel Companion and Orchestrator lifecycle currently restore restorable Pods by name before spawning a missing Pod. This is correct for normal continuity, but after updating workflows/profiles/system guidance, a user may want to intentionally start a fresh same-name Pod instead of restoring old Pod metadata/history.
+
+Currently there is no explicit Panel/CLI path to archive or reset a restorable Pod name before fresh creation. The practical workaround is to manually rename/archive the Pod metadata directory under the user data dir, e.g. `~/.yoi/pods/<pod-name>/`, which is unsafe and not discoverable.
+
+Example:
+
+- Workspace Companion name is `yoi`.
+- `yoi panel` sees `yoi` as restorable and restores it.
+- User wants a fresh `yoi` Companion after workflow/profile changes.
+- There is no `fresh` / `archive` action in Panel or CLI, so manual metadata directory surgery is the only apparent route.
+
+## Goal
+
+Provide an explicit, safe Pod archive/reset/fresh-start path for same-name Pods so users do not need to manually edit `~/.yoi/pods` metadata.
+
+## Requirements
+
+- Add a user-facing way to archive or reset a stopped/restorable Pod name so the next same-name launch is fresh.
+- Refuse to archive/reset a live reachable Pod unless it is explicitly stopped first.
+- Preserve old metadata/history by default; prefer archive/rename over destructive delete.
+- Make the archive location/name deterministic and collision-safe.
+- Surface what will happen clearly:
+  - archived Pod metadata will no longer be restored by name;
+  - session logs/history are preserved where applicable;
+  - next launch with the same name will create a fresh Pod.
+- Support the Panel Companion use case where the workspace Companion name is fixed to the workspace basename, e.g. `yoi`.
+- Consider both CLI and Panel/TUI surfaces.
+  - CLI examples could be `yoi pod archive <name>` or `yoi pod reset <name>`.
+  - Panel could expose a bounded action/diagnostic path for `fresh Companion` if appropriate.
+- Keep normal lifecycle behavior unchanged: live -> use, restorable -> restore, missing -> spawn.
+- Do not silently bypass restore just because profiles/workflows changed; fresh must be explicit.
+- Avoid manual modification of `~/.yoi/pods` in docs except as an emergency/debug note.
+
+## Acceptance criteria
+
+- A stopped/restorable Pod can be archived via an official command/action.
+- After archive, the same Pod name is treated as missing for attach/panel lifecycle and can be spawned fresh.
+- Live Pods are protected from archive/reset without an explicit stop path.
+- Archive preserves enough metadata/history for later inspection or manual recovery.
+- Panel Companion `yoi` can be refreshed without hand-renaming data-dir metadata.
+- Tests cover archive refusal for live Pods, archive success for stopped/restorable Pods, and fresh same-name spawn after archive.
+- Relevant docs/help text are updated.
+- `cargo test` focused suites, `cargo fmt --check`, `git diff --check`, and `target/debug/yoi ticket doctor` pass.
@@ -0,0 +1,98 @@
+<!-- event: create author: LocalTicketBackend at: 2026-06-07T23:45:30Z -->
+
+## Created
+
+Created by LocalTicketBackend create.
+
+---
+
+<!-- event: decision author: Intake at: 2026-06-08T03:31:47Z -->
+
+## Decision
+
+## Intake refinement
+
+Readiness: `implementation_ready`
+Needs preflight: `true`
+Risk flags: `pod-lifecycle`, `persistence`, `cli`, `panel`, `recovery`
+
+### Binding decisions / invariants
+
+- Fresh start must be explicit. Profile/workflow/system-guidance changes must not silently bypass normal restore behavior.
+- Archive/reset targets only stopped/restorable Pod names. A live reachable Pod must be explicitly stopped before archive/reset is accepted.
+- Preserve by default: archive/rename old metadata rather than destructively deleting it, with deterministic collision-safe archive naming.
+- After archive, same-name launch should flow through the existing `missing -> spawn fresh` lifecycle rather than a hidden special-case restore bypass.
+- User-facing docs/help should guide users to the official command/action and mention manual `~/.yoi/pods` surgery only as emergency/debug context.
+- The implementation must be clear about what is preserved: Pod metadata/current-state and session logs/history should remain inspectable or recoverable where applicable.
+
+### Implementation latitude
+
+- The exact CLI spelling (`yoi pod archive <name>` versus `reset`/alias wording) can be chosen during design/preflight, provided the behavior and help text are explicit.
+- Panel support may be a bounded Companion fresh-start action or diagnostic path; it does not need to become a general Pod manager if CLI coverage plus discoverability is sufficient.
+- Archive storage may live under the Pod metadata root or a dedicated archive subdirectory if name lookup, collision handling, and recovery semantics remain simple.
+- Tests can be focused around Pod metadata/lifecycle helpers and CLI/panel lifecycle behavior; full E2E process spawning is not required unless the implementation already has a suitable harness.
+
+### Escalation conditions
+
+Escalate before implementation if the chosen design would delete metadata/history by default, change live-Pod stop semantics, require a storage migration, introduce a new authority/scope boundary, or make Panel bypass restore without an explicit user action.
+
+### Validation
+
+Expected validation includes focused Rust tests for live refusal, stopped/restorable archive success, and same-name fresh launch behavior; `cargo fmt --check`; `git diff --check`; `target/debug/yoi ticket doctor`; and `nix build .#yoi` because this touches CLI/runtime/panel behavior.
+
+---
+
+<!-- event: intake_summary author: Intake at: 2026-06-08T03:31:53Z -->
+
+## Intake summary
+
+Existing Ticket refined for an explicit safe Pod archive/fresh-start path. It is implementation_ready with needs_preflight=true because it touches Pod lifecycle metadata/persistence plus CLI and Panel UX. Binding decisions: fresh start must be explicit, live reachable Pods are protected, archive preserves by default with deterministic collision-safe naming, same-name launch after archive uses the normal missing->spawn path, and docs should prefer official command/action over manual ~/.yoi/pods edits. Escalate if implementation would delete by default, alter live stop semantics, require migration, add authority/scope boundaries, or silently bypass restore.
+
+---
+
+<!-- event: state_changed author: Intake at: 2026-06-08T03:31:53Z from: intake to: ready reason: intake_ready field: workflow_state -->
+
+## State changed
+
+Intake refinement is complete. Ticket is ready for Orchestrator routing; implementation must not start until the user queues it and Orchestrator accepts it as inprogress.
+
+---
+
+<!-- event: state_changed author: workspace-panel at: 2026-06-08T03:48:46Z from: ready to: queued reason: queued field: workflow_state -->
+
+## State changed
+
+Ticket queued for Orchestrator routing.
+
+
+---
+
+<!-- event: decision author: orchestrator at: 2026-06-08T03:49:14Z -->
+
+## Decision
+
+Routing decision: preflight_needed
+
+Reason:
+- Intake marked this Ticket `implementation_ready` but also explicitly `needs_preflight=true` for Pod lifecycle metadata/persistence plus CLI and Panel UX.
+- Several product/storage choices are still intentionally left open: command spelling (`archive`/`reset`), archive location/layout, deterministic collision naming, recovery semantics, and whether Panel support is a bounded Companion action or diagnostic path.
+- Those choices affect user-facing CLI, metadata preservation, live/restorable Pod safety, and recovery expectations, so coder delegation should wait until a short binding design note fixes the boundary.
+
+Evidence checked:
+- Ticket body: background, requirements, acceptance criteria.
+- Thread: Intake refinement, binding decisions/invariants, implementation latitude, escalation conditions, validation, and latest `ready -> queued` event.
+- Workspace state: no matching branch/worktree exists; main workspace has unrelated Ticket-record edits for other Intake work.
+- Visible Pods: only peer Intake Pods and this Orchestrator are live; no coder/reviewer implementation Pods are active.
+
+Next action:
+- Run `ticket-preflight-workflow` before implementation delegation.
+- Preflight should record: final CLI spelling and help text, archive storage layout, deterministic collision-safe naming format, exact live-Pod refusal/stop interaction, what metadata/history is moved or preserved, how same-name launch observes `missing -> spawn`, Panel Companion UX scope, recovery/inspection wording, and focused test strategy.
+- Leave this Ticket queued for now; do not transition `queued -> inprogress`, create `.worktree/add-pod-archive-fresh-start-path`, or spawn coder/reviewer Pods until preflight records implementation readiness.
+
+Escalate if:
+- The design would delete metadata/history by default.
+- The implementation would alter live-Pod stop semantics or silently bypass restore because profiles/workflows changed.
+- Archive requires a storage migration or a new authority boundary.
+- Panel support would become a broad Pod manager rather than a bounded explicit fresh-start path.
+
+---