relay autonomy followup

README.md

@@ -114,6 +114,25 @@ The project documentation is split into several focused files.
 | **[ROADMAP.md](docs/ROADMAP.md)** | **Future Plans**: Pending milestones and prioritized delivery backlog. |
 | **[CHANGES.md](docs/CHANGES.md)** | **Changelog**: Detailed history of v3.0 feature delivery, architecture work, and updates. |
 
+## Project Structure
+
+```text
+ytree/
+├── src/                 C source files
+├── include/             C headers
+├── tests/               pytest/pexpect test suite
+├── scripts/             helper scripts (build, relay, tooling)
+├── docs/                user, developer, and process documentation
+├── infra/               service and infrastructure templates
+├── etc/                 manpage source and related assets
+├── build/               build artifacts
+├── obj/                 object files
+├── coverage/            coverage outputs
+├── Makefile             primary build/test targets
+├── README.md            project overview
+└── AGENTS.md            Codex/agent discovery stub
+```
+
 ---
 
 ## Reporting Issues

docs/ai/PROMPT_TEMPLATE.md

@@ -50,10 +50,10 @@ Process requirements:
    - keep scope tight and avoid unrelated edits
 
 5) Validation:
-   - do not run checks or QA until I explicitly agree
+   - run required checks/QA autonomously; do not stop for checks approval
    - before first push, run a quick local gate (build + targeted smoke/tests)
    - run targeted tests as needed
-   - if I approve full QA for a unit state, run `make qa-all` at most once for that exact accepted state; rerun only after code changes
+   - run `make qa-all` at most once per accepted code state; rerun only after code changes
    - after task completion, run full gate:
      source .venv/bin/activate
      make qa-all
@@ -84,12 +84,28 @@ Important guardrails:
 - Status updates must be facts-first: report what was completed (with evidence handle) before stating next action.
 - If uncertain, ask before choosing behavior-changing options.
 - If anything is ambiguous, ask me to clarify instead of guessing.
+- Maintainer interruption is reserved for:
+  - `true_blocker_decision`
+  - `commit_message_approval`
 
 Operator UX contract (mandatory):
 - First line of every update MUST be exactly one of:
   - `ACTION NEEDED (maintainer): none`
   - `ACTION NEEDED (maintainer): reply "<exact text>"`
-- If `ACTION NEEDED` is `none`, keep the rest of the update to at most five concise lines.
+- If `ACTION NEEDED` is `none`, keep the rest of the update to at most six concise lines.
 - If `ACTION NEEDED` is not `none`, print that line before any other content.
+- Required section order (no extra sections):
+  1) `ACTION NEEDED`
+  2) `COMPLETED`
+  3) `RUN` (only when relay runtime is involved)
+  4) `NEXT`
+  5) `REPRO` (only when maintainer-run repro is needed)
+  6) `LATEST EVENT` (only when relay runtime is involved)
+- Repro instructions must be numbered with one step per line (no single-line paragraph lists).
+- Do not emit `Model:` / `Reasoning level:` banners in routine updates.
 - Do not ask the maintainer to extract machine/runtime internals from logs; provide exact values directly.
+- If relay prompt artifacts are needed, do not ask maintainer for source-path discovery; provide one exact command:
+  `scripts/relay-prompts.sh stage --run-id <run_id> --auto;scripts/relay-prompts.sh verify --run-id <run_id>`
+- If relay run start/resume is reported in the current update, include one exact launch command with concrete values:
+  `scripts/relay-run.sh --run-id <actual_run_id> --idempotency-key <actual_idempotency_key> --activity-timeout 900 --retry-limit 2`
 - On completion, proactively emit final delivery package (summary, verification evidence, commit-ready status, and exact approval text when needed) without waiting for maintainer prodding.

docs/ai/RELAY_PROMPT_TEMPLATE.md

@@ -67,17 +67,20 @@ Prompt/report artifact rules:
   - Do not emit “will do X” updates unless the prior event already emitted “did X” evidence for the previous action.
 - Runtime event labels should prefer explicit completion facts (`worker_command_started`, `worker_command_completed`, `worker_command_failed`, `unit_completed`, `unit_failed`, `retry_scheduled`, `workflow_completed`, `workflow_failed`).
 - Before requesting maintainer approval to dispatch `developer_run`, you MUST stage both relay prompt artifacts for this run_id:
-  - `scripts/relay-prompts.sh stage --run-id <run_id> --developer <developer_prompt_source> --auditor <auditor_prompt_source>`
+  - `scripts/relay-prompts.sh stage --run-id <run_id> --auto`
   - Then verify with `scripts/relay-prompts.sh verify --run-id <run_id>`
 - Do not claim dispatch/start for `developer_run` without runtime evidence (`unit_queued`, `lease_acquired`, or `worker_command_started`) and its `history_seq`.
 
 Stall/escalation policy:
 - If a unit exceeds timeout or misses heartbeat, watchdog MUST emit a stall event.
 - Watchdog then retries/reassigns within retry policy; if retries are exhausted, mark terminal failure and escalate.
-- Do not run checks or QA until maintainer explicitly agrees.
-- When maintainer approves checks/QA for a unit state, avoid duplicate full-gate churn:
-  - `make qa-all` runs at most once per accepted unit state.
+- Run required checks/QA autonomously; do not ask maintainer approval for checks.
+- Avoid duplicate full-gate churn:
+  - `make qa-all` runs at most once per accepted code state.
   - Re-run full gate only if code changed after the last full-gate evidence.
+- Maintainer interruption is reserved only for:
+  - `true_blocker_decision`
+  - `commit_message_approval`
 
 Developer prompt requirements (for each unit):
 - Strict scope and explicit non-goals
@@ -114,27 +117,34 @@ Response format to maintainer:
 - Include handles only when they changed or are newly created.
 - For any required maintainer decision/approval, include one standalone explicit line:
   - `ACTION NEEDED (maintainer): reply "<exact text to send>"`
-  - Example: `ACTION NEEDED (maintainer): reply "approve checks for BUG-11.2"`
+  - Example: `ACTION NEEDED (maintainer): reply "approve commit message: fix(ui): ..."`
 - If no maintainer input is required, include:
   - `ACTION NEEDED (maintainer): none`
 - Use delta-only updates: include only net-new state, next action, and new/changed handles unless maintainer asks for a full recap.
-- Include `Latest relay event` in each update with direction + unit + handle.
+- Include `LATEST EVENT` in each update with direction + unit + handle.
 - Do not repeat full historical handle inventories unless the maintainer explicitly requests a full recap.
-- Include handoff block for relay role-to-role traceability only (maintainer does not need to copy/paste this):
-  Model: <selected model>
-  Reasoning level: <selected level>
-  Handoff line: <next-role>: Execute $WORK_KIND $TASK from handle <handoff-handle> exactly as written.
+- Do not emit `Model:` / `Reasoning level:` banners in routine updates.
+- Handoff is one optional short line only, and only when changed:
+  `HANDOFF: <next-role>: Execute $WORK_KIND $TASK from handle <handoff-handle> exactly as written.`
 
 Non-negotiable operator UX contract:
 - First line of every update MUST be exactly one of:
   - `ACTION NEEDED (maintainer): none`
   - `ACTION NEEDED (maintainer): reply "<exact text>"`
 - If `ACTION NEEDED` is not `none`, emit that line before any other content.
-- If `ACTION NEEDED` is `none`, keep update body to at most five concise lines.
-- On run start/resume, provide exactly one copy-paste command line for runtime launch:
-  - `scripts/relay-run.sh --run-id <run_id> --idempotency-key <idempotency_key> --activity-timeout 900 --retry-limit 2`
+- If `ACTION NEEDED` is `none`, keep update body to at most six concise lines.
+- Required section order (no extra sections):
+  1) `ACTION NEEDED`
+  2) `COMPLETED`
+  3) `RUN`
+  4) `NEXT`
+  5) `REPRO` (only when maintainer-run repro is needed)
+  6) `LATEST EVENT`
+- Repro instructions must be numbered with one step per line (no single-line paragraph lists).
+- On run start/resume in the current update, provide exactly one copy-paste runtime command line with concrete values (not placeholders):
+  - `scripts/relay-run.sh --run-id <actual_run_id> --idempotency-key <actual_idempotency_key> --activity-timeout 900 --retry-limit 2`
 - If prompt artifacts are required, provide exactly one copy-paste command line for staging+verify:
-  - `scripts/relay-prompts.sh stage --run-id <run_id> --developer <developer_prompt_source> --auditor <auditor_prompt_source>;scripts/relay-prompts.sh verify --run-id <run_id>`
+  - `scripts/relay-prompts.sh stage --run-id <run_id> --auto;scripts/relay-prompts.sh verify --run-id <run_id>`
 - Do not require maintainer to query runtime internals (run_id lookup, idempotency lookup, history parsing); architect must provide exact values.
 - On `workflow_completed`, immediately emit final delivery package without maintainer prodding: summary, pass/fail, commit-ready status, commit-message approval line (or `none`), PR/CI status, and cleanup commands.
 ```

docs/ai/RELAY_QUICKSTART.md

@@ -1,89 +1,46 @@
 # Relay Quickstart (Minimal)
 
-## One-time (or after relay config/unit changes)
+## 1) [BASH] One-time (or after relay config/unit changes)
 
 ```bash
 cd ~/ytree
 scripts/setup_relay_runtime.sh
 ```
 
-## Each working session
+## 2) [BASH] Each session
 
 ```bash
 cd ~/ytree
 scripts/relay-workers.sh start
 ```
 
-## Prompt source (AI chat/IDE)
+## 3) [IDE] Paste the task prompt
 
 - Non-trivial work: `docs/ai/RELAY_PROMPT_TEMPLATE.md`
 - Single quick unit: `docs/ai/PROMPT_TEMPLATE.md`
 
-In IDE, open a fresh AI thread and paste the task-customized template.
-Do not run prompt text in bash.
-
-## Start a durable run
+## 4) [BASH] Run the exact start/resume command the IDE gives
 
 ```bash
-cd ~/ytree
 scripts/relay-run.sh --run-id <run_id> --idempotency-key <idempotency_key> --activity-timeout 900 --retry-limit 2
 ```
 
-Expected output:
-
-- `RUN STARTED: <run_id>` (or `RUN RESUMED: <run_id>`)
-- `PROMPT ARTIFACTS READY: <run_id>` **or** `PROMPT ARTIFACTS PENDING: <run_id>`
-
-If prompt artifacts are pending, stage them:
-
-```bash
-cd ~/ytree
-scripts/relay-prompts.sh stage --run-id <run_id> --developer <developer_prompt_source> --auditor <auditor_prompt_source>
-scripts/relay-prompts.sh verify --run-id <run_id>
-```
-
-## Optional monitoring (single terminal)
+## 5) [BASH] If prompts are pending
 
 ```bash
-cd ~/ytree
-scripts/relay-monitor.sh --run <run_id> --view quiet
+scripts/relay-prompts.sh stage --run-id <run_id> --auto;scripts/relay-prompts.sh verify --run-id <run_id>
 ```
 
-Other views:
+## 6) [BASH] Optional monitor
 
 ```bash
-scripts/relay-monitor.sh --run <run_id> --view normal
-scripts/relay-monitor.sh --run <run_id> --view verbose
+scripts/relay-monitor.sh --run <run_id> --view quiet --sound
 ```
 
-- `quiet` = status + `ACTION NEEDED` only
-- `normal` = key transitions
-- `verbose` = full stream (includes heartbeats)
-
-Stop monitor with `Ctrl+C`.
-
-## What to look for in AI updates
-
-Every update should include exactly one explicit line:
-
-- `ACTION NEEDED (maintainer): none`
-- or `ACTION NEEDED (maintainer): reply "<exact text>"`
-
-(“maintainer” means you.)
-
-## Finish / shutdown
+## 7) [BASH] Done
 
 ```bash
-cd ~/ytree
 scripts/relay-workers.sh stop
 ```
 
-## Numbered flow
-
-1. Run setup once: `scripts/setup_relay_runtime.sh`
-2. Start workers for the session: `scripts/relay-workers.sh start`
-3. Paste task prompt in IDE (not bash)
-4. Run the exact `scripts/relay-run.sh ...` line
-5. If pending, run `scripts/relay-prompts.sh stage ...` then `verify`
-6. Optional monitor: `scripts/relay-monitor.sh --run <run_id> --view quiet`
-7. When done: `scripts/relay-workers.sh stop`
+For setup/details/troubleshooting, use `docs/ai/RELAY_RUNBOOK.md`.

docs/ai/RELAY_RUNBOOK.md

@@ -31,7 +31,7 @@ If prompt artifacts are still pending, stage them immediately:
 
 ```bash
 cd ~/ytree
-scripts/relay-prompts.sh stage --run-id <run_id> --developer <developer_prompt_source> --auditor <auditor_prompt_source>
+scripts/relay-prompts.sh stage --run-id <run_id> --auto
 scripts/relay-prompts.sh verify --run-id <run_id>
 ```
 
@@ -42,10 +42,21 @@ cd ~/ytree
 scripts/relay-monitor.sh --run <run_id> --view quiet
 ```
 
+Sound notifications (optional):
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ffmpeg
+scripts/relay-monitor.sh --run <run_id> --view quiet --sound
+```
+
 Detail levels:
 - `quiet`: status + `ACTION NEEDED (maintainer)` only
 - `normal`: key transitions (heartbeat noise filtered)
 - `verbose`: full event stream including heartbeats
+- on terminal completion/failure, monitor includes report handles plus an exact IDE fallback line if IDE goes silent
+- `--sound` plays notifications for maintainer input needed, workflow failure, and workflow completion
+- if no supported player is available, monitor warns and falls back to terminal bell
 
 Convenience:
 - omit `--run` to monitor the latest run in durable relay state.
@@ -61,6 +72,7 @@ If no input is required:
 - `ACTION NEEDED (maintainer): none`
 
 In relay messages, **maintainer** means you (operator/user).
+Checks/QA run autonomously; maintainer interruption is for blocker clarification or commit-message approval.
 
 ## Stop workers when done
 

docs/ai/WORKFLOW.md

@@ -273,7 +273,7 @@ The run wrapper auto-loads relay env and prints `RUN STARTED: <run_id>` (or `RUN
 If pending, stage them with:
 
 ```bash
-scripts/relay-prompts.sh stage --run-id <run_id> --developer <developer_prompt_source> --auditor <auditor_prompt_source>
+scripts/relay-prompts.sh stage --run-id <run_id> --auto
 scripts/relay-prompts.sh verify --run-id <run_id>
 ```