From de3416cf3bbae20928fc1c77dd389bbe693f1dbf Mon Sep 17 00:00:00 2001
From: Hare <kei.hiracchi.0928@gmail.com>
Date: Sat, 18 Jul 2026 19:10:51 +0900
Subject: [PATCH] dev: document workspace process switcher

---
 .yoi/tickets/00001KXTB7H5N/artifacts/.gitkeep |  0
 .yoi/tickets/00001KXTB7H5N/item.md            | 28 ++++++
 .yoi/tickets/00001KXTB7H5N/resolution.md      |  1 +
 .yoi/tickets/00001KXTB7H5N/thread.md          | 85 +++++++++++++++++++
 scripts/dev-workspace.sh                      | 19 +++++
 5 files changed, 133 insertions(+)
 create mode 100644 .yoi/tickets/00001KXTB7H5N/artifacts/.gitkeep
 create mode 100644 .yoi/tickets/00001KXTB7H5N/item.md
 create mode 100644 .yoi/tickets/00001KXTB7H5N/resolution.md
 create mode 100644 .yoi/tickets/00001KXTB7H5N/thread.md

diff --git a/.yoi/tickets/00001KXTB7H5N/artifacts/.gitkeep b/.yoi/tickets/00001KXTB7H5N/artifacts/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/.yoi/tickets/00001KXTB7H5N/item.md b/.yoi/tickets/00001KXTB7H5N/item.md
new file mode 100644
index 00000000..7d90de88
--- /dev/null
+++ b/.yoi/tickets/00001KXTB7H5N/item.md
@@ -0,0 +1,28 @@
+---
+title: 'Document dev workspace process script usage'
+state: 'closed'
+created_at: '2026-07-18T10:09:26Z'
+updated_at: '2026-07-18T10:10:43Z'
+assignee: null
+queued_by: 'yoi ticket'
+queued_at: '2026-07-18T10:09:33Z'
+---
+
+## 背景
+
+`scripts/dev-workspace.sh` は backend/runtime/frontend を停止・再起動する開発用スクリプトで、誤って foreground 実行や frontend restart を行うと API セッションやブラウザ接続に影響する。スクリプト本体を読むだけで安全な使い方と注意が分かるようにする。
+
+## 要件
+
+- スクリプト先頭コメントに基本コマンドを記載する。
+- `start` / `stop` / `restart` が既定で detached schedule されることを明記する。
+- `restart` は frontend を触らないことを明記する。
+- frontend も付け替える時は `start` / `stop` を使う注意を書く。
+- foreground override は通常使わない注意を書く。
+
+## 受け入れ条件
+
+- `scripts/dev-workspace.sh` の先頭を読めば使い方と注意が分かる。
+- `bash -n scripts/dev-workspace.sh` が通る。
+- `scripts/dev-workspace.sh --help` が通る。
+- mutating action は実行しない。
diff --git a/.yoi/tickets/00001KXTB7H5N/resolution.md b/.yoi/tickets/00001KXTB7H5N/resolution.md
new file mode 100644
index 00000000..7aaf19d8
--- /dev/null
+++ b/.yoi/tickets/00001KXTB7H5N/resolution.md
@@ -0,0 +1 @@
+Added top-of-file usage and safety comments to `scripts/dev-workspace.sh`, documenting detached default behavior, restart/frontend semantics, foreground override risk, and scheduled log follow-up.
diff --git a/.yoi/tickets/00001KXTB7H5N/thread.md b/.yoi/tickets/00001KXTB7H5N/thread.md
new file mode 100644
index 00000000..9ddeaf56
--- /dev/null
+++ b/.yoi/tickets/00001KXTB7H5N/thread.md
@@ -0,0 +1,85 @@
+<!-- event: create author: "yoi ticket" at: 2026-07-18T10:09:26Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---
+
+<!-- event: intake_summary author: hare at: 2026-07-18T10:09:33Z -->
+
+## Intake summary
+
+Marked ready by `yoi ticket state`.
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T10:09:33Z from: planning to: ready reason: cli_state field: state -->
+
+## State changed
+
+Marked ready by `yoi ticket state`.
+
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T10:09:33Z from: ready to: queued reason: queued field: state -->
+
+## State changed
+
+Ticket を `yoi ticket` が queued にしました。
+
+
+---
+
+<!-- event: state_changed author: "yoi ticket" at: 2026-07-18T10:09:33Z from: queued to: inprogress reason: cli_state field: state -->
+
+## State changed
+
+State changed to `inprogress`.
+
+
+---
+
+<!-- event: implementation_report author: hare at: 2026-07-18T10:10:43Z -->
+
+## Implementation report
+
+`scripts/dev-workspace.sh` の先頭に使い方と注意コメントを追加した。
+
+追記内容:
+- `status` / `restart` / `start` / `stop` の基本用途。
+- `start` / `stop` / `restart` は既定で detached schedule されること。
+- `restart` は backend/runtime のみで frontend を触らないこと。
+- frontend を worktree 間で移す場合は `start` / `stop` を使うこと。
+- `YOI_DEV_WORKSPACE_FOREGROUND=1` は active API session 中に避けるべきこと。
+- detached action 後は `scheduled_log` を確認すること。
+
+検証:
+- `bash -n scripts/dev-workspace.sh`
+- `scripts/dev-workspace.sh --help >/dev/null`
+- `scripts/dev-workspace.sh status >/dev/null`
+- `git diff --check`
+
+mutating action (`start`/`stop`/`restart`) は実行していない。
+
+
+---
+
+<!-- event: state_changed author: hare at: 2026-07-18T10:10:43Z from: inprogress to: closed reason: closed field: state -->
+
+## State changed
+
+Ticket を closed にしました。
+
+
+---
+
+<!-- event: close author: hare at: 2026-07-18T10:10:43Z status: closed -->
+
+## 完了
+
+Added top-of-file usage and safety comments to `scripts/dev-workspace.sh`, documenting detached default behavior, restart/frontend semantics, foreground override risk, and scheduled log follow-up.
+
+
+---
diff --git a/scripts/dev-workspace.sh b/scripts/dev-workspace.sh
index 1660b0bc..af339899 100755
--- a/scripts/dev-workspace.sh
+++ b/scripts/dev-workspace.sh
@@ -1,4 +1,23 @@
 #!/usr/bin/env bash
+# Development process switcher for the workspace web/backend/runtime stack.
+#
+# Common usage:
+#   scripts/dev-workspace.sh status    # inspect managed pids and port listeners only
+#   scripts/dev-workspace.sh restart   # restart backend/runtime only; frontend is left running
+#   scripts/dev-workspace.sh start     # move runtime/backend/frontend listeners to this checkout
+#   scripts/dev-workspace.sh stop      # stop runtime/backend/frontend listeners
+#
+# Safety notes:
+# - start/stop/restart are detached by default and run after
+#   YOI_DEV_ACTION_DELAY_SECONDS=60. This gives API/tool-call sessions time to
+#   persist their result before backend/runtime processes are stopped.
+# - Use restart for normal backend/runtime code changes. It intentionally does
+#   not touch the frontend dev server.
+# - Use start or stop when the frontend listener must also move between
+#   worktrees; frontend binds to 0.0.0.0 by default for browser access.
+# - Avoid YOI_DEV_WORKSPACE_FOREGROUND=1 during active API sessions; it runs the
+#   mutating action synchronously and can interrupt the session that invoked it.
+# - Check the printed scheduled_log after a detached action completes.
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"