docs: tq / tqdev コマンドガイダンスを再整理

docs/design/system-prompts.ja.md

@@ -4,6 +4,24 @@
 
 オーケストレーターは、「ワークフローで定義した課題の変更はコーディングエージェントが行う」という Symphony の境界を保ちながら、エージェントが Issue Tracker を同期できるようにこれらのプロンプトを注入します。
 
+## Tasq コマンドの解決
+
+オーケストレーターは、課題を割り当てる前にビルドプロファイルから Tasq CLI コマンドを決定します。
+
+| ビルドプロファイル | コマンド |
+|---|---|
+| 空（本番） | `tq` |
+| `dev` | `tqdev` |
+
+その他のプロファイルはエラーになります。`service start` サブコマンドとオーケストレーターの単体起動は、選択したコマンドを `PATH` から解決できることを要求します。
+
+初回ターンでは、既定のタスク作業プロンプト注入が有効な場合に、開発ビルド用の次の文言をターン固有の指示より前へ追加します。開発ビルドの継続ターンでは常に追加します。
+
+```text
+Use the `tqdev` command instead of `tq`.
+When using the `tasq-cli` skill, interpret every `tq` command as `tqdev`.
+```
+
 ## タスク開始時のプロンプト
 
 初回実行で `Task.ResumeThreadID` が空の場合、runner は有効なワークフロープロンプトを展開します。`tasq.task_work_prompt` が `false` に設定されていない限り、Tasq はテンプレート変数を展開する前に、既定の task-work プロンプトを先頭へ追加します。
@@ -47,20 +65,9 @@ Lifecycle:
 
 ````
 
-`{{ issue.id }}` などのテンプレート変数は、このプロンプトを先頭へ追加した後に展開されます。`tasq.task_work_prompt: false` を設定すると、Issue Tracker と Artifact に関する指示を含む開始プロンプト全体が無効になりますが、継続時の動作は変わりません。
-
-本番ビルドでは `{{ tq.command }}` を `tq` として展開します。開発ビルドでは `tqdev` として展開し、既定のタスク作業プロンプトより前に次の 2 行を追加します。
-
-```text
-Use the `tqdev` command instead of `tq`.
-When using the `tasq-cli` skill, interpret every `tq` command as `tqdev`.
-```
-
-この開発用ガイダンスも既定のタスク作業プロンプト注入の一部であるため、初回ターンで `tasq.task_work_prompt: false` を設定すると無効になります。
-
-承認理由に関する契約を追加することで、承認待ちでブロックされたときのコメントから、運用者が必要な対応を判断できるようにします。runner は Codex app-server から受け取った request payload をすでに保持しているため、エージェントに対して、操作内容、対象範囲、必要性、想定される影響を `reason` に含めるよう指示します。この変更では、実行時の検証や Tasq の承認拒否方針は変更しません。
+Tasq は、開発ビルド用のコマンド解決ガイダンス、タスク作業プロンプトの順に追加し、最後に `{{ issue.id }}` や `{{ tq.command }}` などの変数を展開します。`tasq.task_work_prompt: false` を設定すると、初回ターンでは両方の注入を無効にしますが、継続時の動作は変わりません。
 
-Pull Request Artifact は、現在レビューを依頼している主要 PR を表します。同じ Artifact を再設定すると以前の URL が置き換わり、補助 PR はハンドオフコメントの補足情報として残します。PR を作成または更新した場合にだけ Artifact 登録が必要です。登録に失敗した場合は合理的な回数だけ再試行し、解決できなければブロッカーコメントを残して `review` へ移動してはいけません。
+承認理由に関する文言はエージェントの振る舞いを案内するものであり、実行時検証や Tasq の承認拒否方針は変更しません。Pull Request Artifact の指示は、エージェントが PR を作成または更新した場合にだけ適用します。
 
 ## タスク再開時のプロンプト
 
@@ -72,6 +79,6 @@ Pull Request Artifact は、現在レビューを依頼している主要 PR を
 First run `<tasq-command> issue update <issue-id> --status in_progress` to keep the issue tracker synchronized. Then continue the same task in this live thread without repeating completed work, and stop when it is ready for handoff. Before requesting approval for a command execution or file change, provide a non-empty, specific reason. The reason must identify what needs approval, the target scope (the command and working directory or the file paths), why approval is required, and the expected effect. Do not send a null, empty, or vague reason such as only saying that approval is required. If this continuation creates or updates a pull request, register the primary PR before handoff with `<tasq-command> artifact set <issue-id> --type pull_request <pr-url>`. On success, add the handoff comment, then move the issue to `review`; on failure, retry reasonably, then leave a blocker comment and do not move to `review` if it remains unresolved. Otherwise, artifact registration is not required.
 ```
 
-`<tasq-command>` は本番ビルドでは `tq`、開発ビルドでは `tqdev` になります。開発ビルドの継続プロンプトには、上記と同じ 2 行のコマンドおよび `tasq-cli` の読み替えガイダンスも先頭へ追加します。`<issue-id>` はターン開始前に現在の課題 ID で埋め込まれます。同じ継続プロンプトは、有効な複数ターン実行の後続ターンでも使われます。既存の再開条件または後続ターン条件によって継続ターンが選ばれた場合だけ送信され、継続が無効な場合に余分なターンを追加することはありません。担当する変更要求の指示がある場合は、従来どおりこの注意事項の後ろに追加されます。
+`<tasq-command>` には [Tasq コマンドの解決](#tasq-コマンドの解決)で決定したコマンドを使い、`<issue-id>` には現在の課題 ID を設定します。開発ビルドでは、上記と同じ 2 行の読み替えガイダンスを先頭へ追加します。
 
-再開した thread と後続 turn には完全な開始プロンプトが再送されないため、承認理由に関する同じ契約を継続用プロンプトにも記載します。
+有効な複数ターン実行の後続ターンでも、同じ継続プロンプトを使います。既存の再開条件または継続条件が次のターンを選んだ場合だけ送信し、継続が無効な場合に余分なターンを追加することはありません。担当する変更要求の指示がある場合は、この注意事項の後ろに追加します。

docs/design/system-prompts.md

@@ -4,6 +4,25 @@ This document records the Tasq-owned prompt text that the orchestrator injects i
 
 The orchestrator injects these prompts so agents can keep the issue tracker synchronized while preserving the Symphony boundary where workflow-defined ticket mutations are performed by the coding agent.
 
+## Tasq Command Resolution
+
+The orchestrator resolves the Tasq CLI command from its build profile before dispatch:
+
+| Build profile | Command |
+|---|---|
+| empty (production) | `tq` |
+| `dev` | `tqdev` |
+
+Any other profile is rejected. Both the `service start` subcommand and standalone orchestrator startup require the selected command to resolve on `PATH`.
+
+On initial turns with default task-work injection enabled, development prompts add this guidance
+before the turn-specific text. Development continuation turns always add it.
+
+```text
+Use the `tqdev` command instead of `tq`.
+When using the `tasq-cli` skill, interpret every `tq` command as `tqdev`.
+```
+
 ## Task Start Prompt
 
 On a first run, when `Task.ResumeThreadID` is empty, the runner renders the effective workflow prompt. Unless `tasq.task_work_prompt` is set to `false`, Tasq prepends the default task-work prompt before template expansion.
@@ -47,20 +66,9 @@ Lifecycle:
 
 ````
 
-Template variables such as `{{ issue.id }}` are rendered after this prompt is prepended. Setting `tasq.task_work_prompt: false` disables this entire start prompt, including its tracker and artifact instructions; it does not change continuation behavior.
-
-Production builds render `{{ tq.command }}` as `tq`. Development builds render it as `tqdev` and prepend these two lines before the default task-work prompt:
-
-```text
-Use the `tqdev` command instead of `tq`.
-When using the `tasq-cli` skill, interpret every `tq` command as `tqdev`.
-```
-
-The development guidance is part of the default task-work prompt injection, so `tasq.task_work_prompt: false` disables it on the first turn as well.
-
-The approval-reason contract makes blocked approval comments actionable because the runner already preserves the app-server request payload. It instructs the agent to populate the request reason with the operation, target scope, necessity, and expected effect; it does not add runtime validation or change Tasq's approval-denial policy.
+Tasq prepends the command-resolution guidance for development builds, then prepends the task-work prompt, and finally expands variables such as `{{ issue.id }}` and `{{ tq.command }}`. Setting `tasq.task_work_prompt: false` disables both injected sections on the first turn; it does not change continuation behavior.
 
-The pull-request artifact represents the primary PR currently submitted for review. Setting it again replaces the prior URL, while supporting PRs remain handoff-comment context. Artifact registration is conditional on creating or updating a PR. A registration failure must be retried reasonably and, if unresolved, reported as a blocker without a transition to `review`.
+The approval-reason wording guides agent behavior but does not add runtime validation or change Tasq's approval-denial policy. The pull-request artifact instructions apply only when the agent creates or updates a PR.
 
 ## Task Resume Prompt
 
@@ -72,6 +80,6 @@ The injected resume prompt is:
 First run `<tasq-command> issue update <issue-id> --status in_progress` to keep the issue tracker synchronized. Then continue the same task in this live thread without repeating completed work, and stop when it is ready for handoff. Before requesting approval for a command execution or file change, provide a non-empty, specific reason. The reason must identify what needs approval, the target scope (the command and working directory or the file paths), why approval is required, and the expected effect. Do not send a null, empty, or vague reason such as only saying that approval is required. If this continuation creates or updates a pull request, register the primary PR before handoff with `<tasq-command> artifact set <issue-id> --type pull_request <pr-url>`. On success, add the handoff comment, then move the issue to `review`; on failure, retry reasonably, then leave a blocker comment and do not move to `review` if it remains unresolved. Otherwise, artifact registration is not required.
 ```
 
-`<tasq-command>` uses `tq` in production builds and `tqdev` in development builds. Development continuations prepend the same two-line command and `tasq-cli` reinterpretation guidance shown above. `<issue-id>` is filled from the current task issue ID before the turn starts. The same continuation prompt is also used for later turns in an enabled multi-turn run. It is sent only when the runner's existing resume or later-turn conditions select a continuation turn; the runner does not add an extra turn when continuation is disabled. Assigned change-request guidance, when present, remains appended after this reminder.
+`<tasq-command>` uses the command from [Tasq Command Resolution](#tasq-command-resolution), and `<issue-id>` is filled from the current task. Development runs prepend the same two-line reinterpretation guidance shown above.
 
-The same approval-reason contract is repeated here because resumed threads and later turns do not receive the full task-start prompt again.
+The same continuation prompt is used for later turns in an enabled multi-turn run. The runner sends it only when existing resume or continuation conditions select another turn; it does not add a turn when continuation is disabled. Assigned change-request guidance, when present, is appended after this reminder.

docs/references/makefile.ja.md

@@ -115,7 +115,7 @@ make run-logs
 | `make install-tq version=v0.1.0` | 特定のリリースタグから `tq` と管理対象サービスの実行ファイルをインストールします。 |
 | `make install-tq-prerelease` | 最新の prerelease から `tq` と管理対象サービスの実行ファイルをインストールします。`gh` が必要です。 |
 | `make install-tq-prerelease version=v0.1.0-pre.1` | 特定の prerelease タグから `tq` と管理対象サービスの実行ファイルをインストールします。 |
-| `make build-tq-dev` | `dev` プロファイルを埋め込んだ `tqdev` とサービスバイナリをビルドします。サービス起動前に `tqdev` を `PATH` へ配置する必要があります。 |
+| `make build-tq-dev` | `dev` プロファイルを埋め込んだ `tqdev` と管理対象サービスのバイナリをビルドします。サービス起動前に `tqdev` を `PATH` へ配置する必要があります。 |
 | `make deploy-tq-dev` | `tqdev` のサービスを停止し、`build-tq-dev` を実行して、生成された `tqdev` バイナリを `$HOME/.local/bin` に移動した後、サービスを再起動します。 |
 | `make deploy-tq-dev ARGS=/path/to/bin` | 生成された `tqdev` バイナリを `$HOME/.local/bin` の代わりに指定したディレクトリへ配置します。 |
 

docs/references/makefile.md

@@ -115,7 +115,7 @@ make run-logs
 | `make install-tq version=v0.1.0` | Install `tq` and its managed service executables from a specific release tag. |
 | `make install-tq-prerelease` | Install `tq` and its managed service executables from the latest prerelease. Requires `gh`. |
 | `make install-tq-prerelease version=v0.1.0-pre.1` | Install `tq` and its managed service executables from a specific prerelease tag. |
-| `make build-tq-dev` | Build `tqdev` and service binaries with the `dev` profile. `tqdev` must be on `PATH` before starting services. |
+| `make build-tq-dev` | Build `tqdev` and the managed service binaries with the `dev` profile. `tqdev` must be on `PATH` before starting services. |
 | `make deploy-tq-dev` | Stop the `tqdev` services, run `build-tq-dev`, move the resulting `tqdev` binary to `$HOME/.local/bin`, and restart the services. |
 | `make deploy-tq-dev ARGS=/path/to/bin` | Deploy the resulting `tqdev` binary to the specified directory instead of `$HOME/.local/bin`. |