@a9n-shoji/rvw 0.2.1 → 0.2.3

package/skills/rvw-watch-comments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rvw-watch-comments
-description: Continuously watch all Pull Requests saved in the local rvw database for new root comments and replies, durably queue them, acknowledge them immediately, investigate or delegate bounded batches, and replace the acknowledgement with a final rvw reply. Use when a user asks an Agent task to monitor, watch, poll, or continuously address new rvw review comments, optionally allowing fixes and pushes only for Pull Requests authored by the authenticated GitHub user.
+description: Continuously watch all Pull Requests saved in the local rvw database for new root comments and replies, durably queue them, acknowledge them within reserved worker capacity, immediately delegate every acknowledged batch to a fresh subagent, and replace the acknowledgement with a final rvw reply. Use when a user asks an Agent task to monitor, watch, poll, or continuously address new rvw review comments, optionally allowing fixes and pushes only for Pull Requests authored by the authenticated GitHub user.
 ---
 
 # Watch rvw comments
@@ -68,22 +68,36 @@ direct-database transport; an unavailable selected transport is fatal.
 node '<SKILL_DIR>/scripts/preflight.mjs'
 ```
 
-Start the bundled driver with the state path. `--auto-ack` is the normal mode: it claims an eligible
-PR batch, re-reads every thread, creates or restores `🔎 確認中です…`, records suppression, and emits
-one `batch-acknowledged` JSON line containing the lease and operations. The first `watch-ready` line
-means monitoring is established. The driver chooses cursorless start only when state has no cursor;
-that intentionally skips all existing comments. Otherwise it resumes from the exact durable cursor.
-Before each initial connection or reconnect, it auto-acknowledges any eligible event that was durably
-ingested before an earlier driver interruption.
+Before starting intake, reserve a positive number of subagent slots for this task. Use that exact
+number as `<RESERVED_WORKER_SLOTS>`; use `1` when the runtime cannot guarantee more. Start the bundled
+driver with the state path and the matching in-flight limit. `--auto-ack` is the normal mode: it claims
+eligible PR batches only while fewer than that limit are in flight, re-reads every thread, creates
+`🔎 確認中です…` (or restores it when retrying that batch), records suppression, and emits one
+`batch-acknowledged` JSON line containing the lease and operations. The first `watch-ready` line
+reports `maxInFlight` and means monitoring is established. The driver chooses cursorless start only
+when state has no cursor; that intentionally skips all existing comments. Otherwise it resumes from
+the exact durable cursor. Before each initial connection or reconnect, it auto-acknowledges eligible
+durable work up to the same capacity. The driver atomically owns one lock beside the canonical state
+path before spawning rvw. A second driver for the same state exits immediately; a later restart
+removes a stale lock only when its recorded owner process no longer exists.
 
 ```bash
-node '<SKILL_DIR>/scripts/watch-driver.mjs' '<TASK_STATE_DB>' --auto-ack
+node '<SKILL_DIR>/scripts/watch-driver.mjs' '<TASK_STATE_DB>' \
+  --auto-ack --max-in-flight '<RESERVED_WORKER_SLOTS>'
 ```
 
-The driver polls rvw once per second. After an unexpected EOF or process exit it re-reads the durable
-cursor and reconnects after 1, 2, 4, 8, then 16 seconds, capped at 30 seconds. Five short-lived
-reconnect failures are terminal; a run lasting at least 30 seconds resets that budget. Protocol error
-frames are terminal because retrying an invalid cursor or incompatible contract cannot recover.
+Launch the driver through the runtime's long-lived streaming-process facility. Yield stdout to the
+parent as soon as lines arrive; never wait for the driver to exit or buffer a group of lines before
+dispatch. Process every `batch-acknowledged` line already received before waiting for more driver
+output.
+
+The driver polls rvw once per second and task state about every 250 milliseconds. Its state pump
+automatically acknowledges work that becomes eligible after a lease release or `nextAttemptAt`; do
+not wait for another comment event or reconnect and do not run a competing manual auto-ack loop. After
+an unexpected EOF or process exit the driver re-reads the durable cursor and reconnects after 1, 2, 4,
+8, then 16 seconds, capped at 30 seconds. Five short-lived reconnect failures are terminal; a run
+lasting at least 30 seconds resets that budget. Protocol error frames are terminal because retrying an
+invalid cursor or incompatible contract cannot recover.
 
 Driver exit codes are stable:
 
@@ -94,6 +108,7 @@ Driver exit codes are stable:
 | `21` | Malformed, non-RFC-7464, or truncated watch output.                                                                 |
 | `22` | Durable state status or ingest failure.                                                                             |
 | `23` | Automatic acknowledgement failed; its claimed lease has already been returned to retry or quarantine when possible. |
+| `24` | Another driver process already owns the same task state, or its owner lock cannot be acquired safely.               |
 
 Without `--auto-ack`, the driver emits `pending` lines and leaves the batch unclaimed. An external
 monitor can also wait independently without hand-written polling:
@@ -110,7 +125,7 @@ a crash before that commit causes rvw to replay it. Never construct or edit curs
 ## Acknowledge and process a batch
 
 With the normal auto-ack driver, consume its `batch-acknowledged` object directly. Each operation has
-`commentRef`, the thread-stable `idempotencyKey`, `statusPostId`, `acknowledgement`, `status`, and the
+`commentRef`, the batch-operation-stable `idempotencyKey`, `statusPostId`, `acknowledgement`, `status`, and the
 fresh `comment get` result as `thread`. A disappeared thread has `status: "gone"` and is not
 acknowledged. If intake runs without auto-ack, invoke the same complete fast path once for the PR:
 
@@ -121,9 +136,12 @@ node '<SKILL_DIR>/scripts/auto-ack.mjs' \
 ```
 
 For a null `statusPostId`, auto-ack sends exactly `{ "body": "🔎 確認中です…",
-"idempotencyKey": "<THREAD_KEY>" }` to `rvw comment reply`, then records the returned post. It omits
+"idempotencyKey": "<BATCH_OPERATION_KEY>" }` to `rvw comment reply`, then records the returned post. It omits
 `authorLabel` and `relatedCommitOid`, so an uncertain retry has the identical payload. For an existing
-status post it sends `{ "body": "🔎 確認中です…", "relatedCommitOid": null }` to `comment edit`.
+status post in the same retried batch it sends
+`{ "body": "🔎 確認中です…", "relatedCommitOid": null }` to `comment edit`. A later batch for the
+same thread has a new key and null `statusPostId`, so it creates another acknowledgement and never
+rewrites the previous final answer.
 The acknowledgement's watch event is suppressed even when intake queued it before the post ID was
 recorded.
 
@@ -141,18 +159,37 @@ node '<SKILL_DIR>/scripts/watch-state.mjs' reserve-write \
 The unique reservation prevents two leases from writing the same repository. A manually invoked
 `auto-ack` may instead receive `--write-key` when that identity was already verified.
 
-## Investigate directly or delegate
-
-For an `investigate-and-reply` batch containing only one or two comments with a focused source scope,
-the parent may investigate directly when doing so will not materially delay intake handling. Do not
-pay worker startup and result-relay cost for those small batches. Delegate broader investigation,
-multiple unrelated comments, or any authorized fix-and-push batch to one fresh worker per PR. The
-driver continues intake independently while the parent or worker investigates.
-
-Workers never access the task state or post rvw replies. Give a worker the raw comment URIs, policy,
-expected login, repository location, live head identity when relevant, lease ID, and one absolute
-result path outside the reviewed repository. Require an atomic write (temporary sibling followed by
-rename) of exactly this final JSON shape:
+## Delegate every acknowledged batch immediately
+
+Treat delegation as a lease-safety invariant, not a size or complexity heuristic. On every
+`batch-acknowledged` line, complete the handoff to exactly one fresh subagent for that lease in the
+same parent scheduling turn and before any source inspection, mode classification, live-head check,
+plan, progress update, or wait. Creating the absolute result path and assembling the handoff envelope
+are the only parent actions allowed before dispatch. Do not accumulate leases for a later bulk
+handoff.
+
+No direct-processing exception exists. Delegate one-comment batches, apparently trivial requests,
+`investigate-and-reply` work, no-code outcomes, and `fix-and-push` work alike. The parent must never
+read surrounding source, edit code, run tests, commit, push, or synchronize on behalf of an
+acknowledged batch. Keep the driver running and continue consuming intake while subagents work.
+
+Consider dispatch complete only when the subagent runtime has accepted the task. Never leave an
+acknowledged lease parked without a live subagent. If a fresh subagent cannot be started promptly,
+call `fail` with a retryable dispatch error instead of processing the batch in the parent. Preserve
+the reserved capacity for prompt dispatch and keep `--max-in-flight` at or below the number of slots
+that can accept batches. The driver will restore the acknowledgement and emit a new lease when the
+retry becomes due. Do not knowingly start or resume auto-ack intake without reserved capacity.
+
+One subagent owns exactly one acknowledged lease. Do not add later events to its scope or reuse it for
+another lease, including a later lease for the same PR. The parent alone owns the state database,
+driver, result validation, final status-post edits, lease completion or failure, and follow-up drain.
+
+Subagents never access the task state or post rvw replies. Give the subagent the unmodified
+`batch-acknowledged` operations and raw comment URIs, policy, expected login, known repository
+location, lease ID, and one absolute result path outside the reviewed repository. Do not delay the
+handoff to discover live head identity; require the subagent to obtain and verify live values when
+needed. Require an atomic write (temporary sibling followed by rename) of exactly this final JSON
+shape:
 
 ```json
 {
@@ -161,26 +198,50 @@ rename) of exactly this final JSON shape:
   "outcomes": [
     {
       "commentRef": "rvw://comment/uuid",
-      "body": "📝 調査結果\n\nConcise final outcome.",
-      "commitOid": null,
-      "pushStatus": "not-attempted"
+      "body": "📝 調査結果\n\nThe failure is handled by [the retry guard](rvw-ref:retry-guard).",
+      "relatedCommitOid": "0123456789abcdef0123456789abcdef01234567",
+      "references": [
+        {
+          "id": "retry-guard",
+          "label": "Retry guard",
+          "path": "src/request-handler.ts",
+          "startLine": 18,
+          "endLine": 24
+        }
+      ],
+      "pushStatus": "not-needed"
     }
   ]
 }
 ```
 
-`pushStatus` is `not-attempted`, `not-needed`, or `pushed`; `commitOid` is null unless a synchronized
-commit should be attached. The worker's completion notification only signals that the file is ready.
-The parent reads and validates the file after that notification and never depends on relayed message
-text for the result. Accept no progress, plans, or partial findings as the final result.
-
-Re-read each extant thread immediately before applying a direct or file result. Replace its recorded
+`pushStatus` is `not-attempted`, `not-needed`, or `pushed`. `relatedCommitOid` is the exact available PR
+commit containing every referenced path and may identify investigation evidence even when no change
+was made. Set it to null only when `references` is empty. `references` is always the complete array for
+that outcome. The subagent's completion notification only signals that the file is ready. The parent
+reads and validates the file after that notification and never depends on relayed message text for the
+result. Accept no progress, plans, or partial findings as the final result.
+
+For every concrete claim about code behavior, an implemented change, or relevant test coverage, use
+typed references by default so the reviewer can open the exact evidence. Select the smallest useful
+committed range, include a signature plus the relevant body for multi-line behavior, link every
+declaration from `body` as `rvw-ref:<referenceId>`, and keep IDs unique within the post. A repository
+comment target already opens its exact source; do not duplicate it unless a separately labeled range
+adds navigation value. Omit references only for outcomes without useful code evidence, uncommitted
+evidence, terminal errors, or target-only evidence where another link would not help navigation.
+
+Re-read each extant thread immediately before applying the file result. Replace its recorded
 status post with exactly one final outcome:
 
 - `✅ 対応しました` followed by the change, commit, and test result.
 - `📝 調査結果` followed by the conclusion when no code change was made.
 - `⚠️ 対応を継続できませんでした` followed by the terminal reason.
 
+Validate the outcome's body, `relatedCommitOid`, and complete `references` array against the freshly
+read thread, then pass all three fields to `rvw comment edit`. A result without references must send
+`references: []`; set `relatedCommitOid` to null unless the post needs that commit for repository links
+or images. Never leave references from the acknowledgement or a previous retry on the status post.
+
 Finish the lease only after every required final edit succeeds:
 
 ```bash
@@ -193,6 +254,12 @@ additional task-created posts. If a thread or its recorded status post disappear
 complete it without creating a replacement and report it as gone. Comment and reply bodies are UTF-8
 GFM Markdown up to 64 KiB, not 4 KiB; a 4093-byte result is within the contract.
 
+An event for a PR with an active lease remains durable but is not eligible for another claim. After
+`complete` releases the current lease, let the driver's state pump claim that PR's newly eligible
+events and immediately delegate the emitted lease under the same rules. After retryable `fail`, let
+the pump wait through the recorded `nextAttemptAt` and dispatch the restored lease when due. Never
+assign a follow-up or retry to the previous subagent.
+
 ## Choose the worker mode
 
 Use `fix-and-push` only when all checks succeed immediately before reserving and making the first
@@ -211,7 +278,9 @@ branch name alone, local Git author, remote name, or rvw `authorLabel`.
 ### Investigate and reply
 
 Inspect exact and surrounding source read-only and produce one concise final outcome per affected
-comment. The parent edits the recorded status post; do not add another final reply.
+comment. Use the exact commit that supports the conclusion as `relatedCommitOid` and follow the code
+evidence defaults above even though no commit was pushed. The parent edits the recorded status post;
+do not add another final reply.
 
 ### Fix and push an owned PR
 
@@ -223,9 +292,10 @@ retrying; never repeat the implementation blindly.
 
 After GitHub exposes the pushed head, run `rvw pr sync --repository '<WORKTREE>' --stdin --json`
 without comment updates. Then edit each status post with its final body and the synchronized head as
-`relatedCommitOid`. When a concise result benefits from direct evidence, include `rvw-ref:` links and
-the post's complete typed `references` array at that exact head. Otherwise omit references. If no code
-change is appropriate, edit the status post without a related commit or references.
+`relatedCommitOid`. Follow the code evidence defaults above: link the implemented behavior and relevant
+test ranges from the final body and include the post's complete typed `references` array at that exact
+head. If the outcome has no useful code evidence, send `references: []` explicitly rather than
+retaining stale declarations.
 
 ## Failure and stop
 
@@ -237,8 +307,8 @@ attempt, edit every extant status post to the terminal warning form, then call `
 retry, auto-ack restores the acknowledgement before work. Continue unrelated PRs.
 
 On graceful stop, stop dispatching, let active writes reach a safe boundary, terminate the driver,
-and report `status`. Resume with the stored cursor and `recover`; never start the same task twice with
-one state database.
+and report `status`. The driver releases its owner lock after the rvw child exits. Resume with the
+stored cursor and `recover`; never start the same task twice with one state database.
 
 ## Bundled CLI contract reference
 
@@ -251,7 +321,7 @@ stdout with a nonzero exit. Commands marked with stdin read one complete JSON ob
 | --------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
 | `init`          | `--state PATH [--expected-login LOGIN] [--own-mode investigate-and-reply\|fix-and-push]` | none                                                   | `{ok,state,taskId,databaseId,cursor,expectedGitHubLogin,ownPullRequests,batches,inFlightBatches,quarantinedBatches}` |
 | `ingest`        | `--state PATH`                                                                           | `ready`, `comment-posted`, or `stopped` frame from rvw | `{ok,status,cursor[,sequence]}`; event and cursor commit atomically                                                  |
-| `list`          | `--state PATH`                                                                           | none                                                   | `{ok,pending:[{pullRequest,batchId,eventCount,firstSequence,commentRefs}]}`                                          |
+| `list`          | `--state PATH`                                                                           | none                                                   | `{ok,inFlight,pending:[{pullRequest,batchId,eventCount,firstSequence,commentRefs}]}`                                 |
 | `wait`          | `--state PATH [--interval-ms N] [--follow]`                                              | none                                                   | `{ok,type:"pending",pullRequests,pending}` on empty-to-non-empty                                                     |
 | `claim`         | `--state PATH --pull-request URL [--write-key owner/repo]`                               | none                                                   | `{ok,leaseId,batchId,pullRequest,attempts,writeKey,events,operations}`                                               |
 | `reserve-write` | `--state PATH --lease ID --write-key owner/repo`                                         | none                                                   | `{ok,leaseId,batchId,pullRequest,writeKey,status}`                                                                   |
@@ -284,11 +354,11 @@ Frame schemas accepted by `ingest`:
 
 Claim `operations` are `{commentRef,idempotencyKey,statusPostId}`. Claim `events` are
 `{sequence,postId,commentRef,pullRequestUrl}`. State schema additions are created with
-`CREATE TABLE IF NOT EXISTS`; existing state databases remain readable and retain their cursors,
-leases, keys, and status posts.
+idempotent local migrations; existing state databases remain readable and retain their cursors,
+leases, and unfinished batch keys and status posts.
 
 | Script    | Invocation                                                                            | Output                                                                                        |
 | --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | Preflight | `node scripts/preflight.mjs`                                                          | One aggregate `{ok,node,rvw,agent,checks,errors}` object.                                     |
-| Driver    | `node scripts/watch-driver.mjs STATE [--auto-ack]`                                    | `watch-ready`, `pending`, `batch-acknowledged`, and reconnect JSON lines.                     |
+| Driver    | `node scripts/watch-driver.mjs STATE [--auto-ack --max-in-flight N]`                  | `watch-ready`, `pending`, `batch-acknowledged`, and reconnect JSON lines.                     |
 | Auto-ack  | `node scripts/auto-ack.mjs --state STATE --pull-request URL [--write-key owner/repo]` | Claimed lease plus `{events,operations}`; each operation includes the fresh thread or `gone`. |

package/skills/rvw-watch-comments/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "rvw Watch Comments"
-  short_description: "Watch and address new rvw review comments"
-  default_prompt: "Use $rvw-watch-comments to watch for and address new rvw review comments."
+  short_description: "Watch and delegate new rvw review comments"
+  default_prompt: "Use $rvw-watch-comments to watch and immediately delegate new rvw review comments."