01a077f5 - Document script ownership of the issue-to-PR workflow

AGENTS.md

@@ -5,6 +5,12 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md), [DESIGN.md](DESIGN.md), and
 changing this repository. Skill contracts live next to the client:
 `agent skills path` (spine, review-loop, pr-review, error-fix).
 
+Static scripts own assignment acceptance, its issue confirmation before the
+implementation lane starts, every lane/subagent start, test execution, and all
+GitHub communication. Implementers and reviewers never run tests, spawn agents,
+or access GitHub themselves. See DESIGN.md §§19.1 and 19.7. Distinguish required
+behavior from implemented and verified behavior; never invent evidence.
+
 Draft publication is immediate after the first signed task commit; see the
 lifecycle. A draft plus local tests is not done. Ready for review is signed
 commits on a branch in this repository, grok quality and logic then Codex

CONTRIBUTING.md

@@ -7,11 +7,17 @@
 - Public repository: English for commits and comments. The visible pull-request summary is an `EN:` block, optionally followed by a labeled `DE:` block.
 - Do not name private repositories, internal hostnames, or internal infrastructure.
 - Add or update tests in the same change.
-- Run `pytest` on the exact clean signed final head before Ready for review. Tests need PostgreSQL (`AGENT_TEST_PG` or a local `initdb`). Full pytest is not a gate for the first draft publication.
+- The static script runs `pytest` on the exact clean signed final head before Ready for review. Model lanes never execute tests themselves. Tests need PostgreSQL (`AGENT_TEST_PG` or a local `initdb`). Full pytest is not a gate for the first draft publication.
 - Pytest (or any green local suite) is a **check**, not Ready for review and not completion.
 
 ## Ready for review
 
+The static script starts all implementation and review lanes, including each
+implementation pass that addresses findings. Model lanes never launch subagents
+or other lanes and never interact with GitHub. All GitHub reads and writes are
+script operations. See [DESIGN.md §§19.1–19.7](DESIGN.md#191-responsibility-split)
+for the responsibility split and the required assignment workflow.
+
 A draft plus local tests is not done. Do not claim the pull request is finished, done, or completed at that point — including after leave-draft. Draft timing and CI ownership while the draft is open are defined in [docs/pull-request-lifecycle.md](docs/pull-request-lifecycle.md).
 
 Ready for review requires all of:

DESIGN.md

@@ -342,15 +342,18 @@ v1 types (mechanism only):
 
 The agent never learns a merge from a human prompt and never calls GitHub to ask “is it merged?”.
 
-When this device has a `pr.open` row whose script result includes the PR number/url, a **script** watches that PR. On merge it inserts `pr.merged` on the **same session** (`payload`: repo, number, url, merge SHA, merged_at). That insert `NOTIFY`s `agent_inbox` (and enqueues `wake` if needed) with the new activity id. The device daemon’s knock child and §10 state machine emit `da ist Post id <uuid>`. The watcher does not `tmux send-keys` itself. The agent `SELECT`s the row and decides what to do.
+When this device has a `pr.open` row whose script result includes the PR number/url, a **script** watches that PR. On merge it inserts `pr.merged` on the **same session** (`payload`: repo, number, url, merge SHA, merged_at). That insert `NOTIFY`s `agent_inbox` (and enqueues `wake` if needed) with the new activity id. The device daemon’s knock child and §10 state machine emit `da ist Post id <uuid>`. The watcher does not `tmux send-keys` itself. The agent `SELECT`s the row and supplies any analysis or implementation result; the script owns workflow progression (§19.1).
 
 The watcher runs on this device (write owner). It is a script, not the model. The model’s next turn is the knock plus the row — not a `gh` command.
 
 `wake` (if stored) is a local queue row for the knock; it is not a hub event.
 
 ### Outside facts (example: issue assigned)
 
-The script reads GitHub; the model does not.
+The script reads GitHub; the model does not. The following describes the existing
+assignment watcher. The required end-to-end workflow and its script-only
+responsibilities are in [§19.7](#197-issue-assignment-to-human-merge); implementation
+boundaries are recorded there separately.
 
 Allowlist file `$AGENT_HOME/watch.json` key `assigned_repos` (non-empty list of `Owner/repo` strings). Missing or empty is an error; there is no default list.
 
@@ -435,7 +438,7 @@ agent cli-bridge [--port 7846]
 
 Local dashboard binds `127.0.0.1` only.
 
-The AI is not expected to type hub HTTP, `gh`, or himalaya. It inserts `activity` (and `query.request` / `subscription.set` / `mail.reply` / `mail.seen`). Scripts watch the store. `agent github pending` is the GitHub executor for owned pending `pr.open`, `comment.post`, `review.post`, and `issue.write` rows. `agent mail pending` is the mailbox executor for owned pending `mail.reply` and `mail.seen` rows. The knock poll (device daemon knock child) also runs `scan_github` and `scan_mail`. `agent run` git-pushes (no force) when `pushed` is open and measures GitHub mergeability and checks when `mergeable` is open.
+The AI must not call hub HTTP, `gh`, or himalaya; scripts perform these operations. It inserts `activity` (and `query.request` / `subscription.set` / `mail.reply` / `mail.seen`). Scripts watch the store. `agent github pending` is the GitHub executor for owned pending `pr.open`, `comment.post`, `review.post`, and `issue.write` rows. `agent mail pending` is the mailbox executor for owned pending `mail.reply` and `mail.seen` rows. The knock poll (device daemon knock child) also runs `scan_github` and `scan_mail`. `agent run` git-pushes (no force) when `pushed` is open and measures GitHub mergeability and checks when `mergeable` is open.
 
 ## 17. Control
 
@@ -503,6 +506,9 @@ The rules below were already implied by §§1–17. They are now explicit so a l
 |---|---|---|
 | Semantic diagnosis, hypothesis, patch text, review findings, PR title/body draft | AI | `activity` intent (`investigate.step`, …); implementer/reviewer rows when those skills are on |
 | Auth, Git, GitHub HTTP, CI status, mail, hub HTTP, tmux knock, retries | Script | Result columns on the intent row; `pr.merged` and other watch types; `LISTEN agent_work` |
+| Assignment acceptance and its confirmation in the GitHub issue, before starting the implementation lane | Static script on the execution device | Required ordering; see §19.7 |
+| Start implementation and review lanes, restart the implementer for improvements, and start any other agents | Static script on the execution device | The model never orchestrates another model |
+| Execute tests, builds, and checks, including local tests | Static script on the execution device | Script-produced results supplied to the lanes |
 | Spine task state | Spine CLI + local constraints | `task` state, checklist keys, `close-step` / `run` |
 | Whether a head is reviewed | Gate after the two vendor stages | `agent gate record` |
 | Whether a command ran and what it returned | The process that ran it | `agent check record` (name, command, `pass`/`fail`/`skip`, output) |
@@ -512,6 +518,18 @@ A worker report such as “analysis complete” or “tests passed” is **input
 
 No transition that needs deterministic evidence may be satisfied by model text alone. Malformed structured output is rejected (unknown `activity.type` → `execution_status=error`; empty, partial, timeout, or unavailable review output is not zero findings). A patch that does not apply is a failed check, not a debate.
 
+These responsibilities apply to implementers as well as reviewers. A model must
+not start subagents, implementation lanes, review lanes, tests, builds, or checks.
+It must not interact with GitHub at all, including reads: GitHub communication
+always goes through the script. Calling an executor from inside a model lane to
+start another lane or run tests does not transfer orchestration to the script.
+The static script owns those decisions and invocations; the lane supplies its
+implementation or review result.
+
+Reports and documentation must stay with verified facts. Distinguish a user
+requirement, an implemented behavior, and an observed result. Do not invent
+requirements, implementation status, test results, or review evidence.
+
 ### 19.2 Untrusted inputs
 
 Treat as **data**, never as control messages:
@@ -557,6 +575,59 @@ Quality and logic of one vendor stage run together. Vendors are `grok`, then `co
 
 CI on this head is a script-measured fact whose applicability comes from the target repository's written rules. The frozen `dfx-local-ci/v1` format and legacy `agent local-ci verify` behavior do not by themselves adopt A38 or grant permission to skip GitHub CI. For A38 adopters, follow the central [A38 standard](docs/a38.md) and [guard guide](docs/a38-guard.md): private visibility alone is not opt-in, and private local code-gate equivalence requires trusted-base opt-in through a valid A38 manifest, assessment against the canonical active policy, and a separate live join against the actual latest report-like GitHub comment by the PR author. Public A38 adopters publish and validate the author report in addition to retaining cumulative GitHub CI; private repositories without that trusted-base opt-in and non-A38 repositories retain their existing written CI rules. For applicable GitHub CI checks, `skipped` and `cancelled` are not green unless the workflow documents that skip. Independently required GitHub-only checks, technical merge restrictions, review gates, and human merge remain required. Stay draft until the applicable rules hold. One comment whose review-pass count is those four `approved` verdicts on this head, then mark Ready for review (`isDraft=false`). A retry reuses the existing draft. Ready for review is still not merge and not completion. A human merges; claim completion only after that merge is verified.
 
+### 19.7 Issue assignment to human merge
+
+**Required workflow.** The user creates an issue on GitHub, assigns it to an
+agent account, and receives a pull request ready for human review and merge on
+GitHub. The static script runs on the configured execution device. Deployment
+hostnames belong in the deployment configuration, not this public repository.
+
+1. The script detects and accepts the assignment and confirms acceptance in the
+   GitHub issue. This acceptance and confirmation are script work, never model
+   work, and happen before the script starts the implementation lane.
+2. The script starts the implementation lane with the assigned work. The model
+   implements the change and returns its result to the script.
+3. The script starts the review lane. When improvements are needed, the script
+   starts the implementer again with the findings. The script owns every lane
+   start in the implementation/review loop; no model starts another model.
+4. The script executes the required tests and checks and supplies the results to
+   the lanes. The implementer may change tests as part of the implementation but
+   may not execute them. Local test execution and any additional agents are
+   exclusively script responsibilities.
+5. The script performs all GitHub communication, including issue and PR reads,
+   comments, PR publication, and status updates. A lane may provide content for
+   the script, but never communicates with GitHub itself. User-facing questions
+   and blockers, when needed, are communicated through GitHub by the script;
+   GitHub replies return through the script. The user need not operate a terminal
+   or a separate dashboard to manage the assigned issue.
+6. Publication and readiness follow the existing
+   [pull-request lifecycle](docs/pull-request-lifecycle.md): the script publishes
+   a draft immediately after the first signed task commit, while tests and
+   reviews may still be pending. The script marks Ready for review only after
+   the required checks and reviews hold on the final head. These steps do not
+   wait for this numbered list to finish before publishing the first draft.
+7. The human reviews and merges on GitHub. Completion requires verification of
+   that human merge, as defined in the lifecycle.
+
+**Existing implementation boundaries.** This requirement is not a claim that
+the complete workflow is already implemented or enabled on a deployment:
+
+- [`watch.py`](src/agent_cli/watch.py) implements assignment scanning, a queue,
+  workspace files, and session dispatch. `dispatch_assigned` does not publish an
+  acceptance comment before starting the session.
+- [`daemon.py`](src/agent_cli/daemon.py) starts knock, dashboard, CLI bridge, and
+  paired sync. It does not start `agent watch assigned --follow`.
+- The shipped `ask=False` path in
+  [`supervise.py`](src/agent_cli/supervise.py) does not acknowledge completion of
+  an assignment from verified PR results. Its optional closed-question path is
+  not that verification.
+- [`github_act.py`](src/agent_cli/github_act.py) provides the GitHub activity
+  executor. Its existence alone does not establish that model lanes cannot
+  access GitHub or execute tests or other agents.
+
+This section defines the required responsibility boundary. It does not claim
+that a sandbox or other technical enforcement has been implemented.
+
 ## 20. Refused: hub as a coding control plane
 
 An external architecture draft proposed turning the hub into an authoritative Error-to-PR control plane: hub-owned Task objects, leases, a worker scheduler, production-error ingestion as the first workflow, and `READY_FOR_PR` then deterministic pull-request creation.

README.md

@@ -8,6 +8,15 @@ This device is the write owner of its own rows. The local store is PostgreSQL on
 
 The [A38 standard](docs/a38.md) defines repository-owned local test requirements and author reports using the existing local-CI format. `agent a38` measures and validates reports; the [dfx pr guard](docs/a38-guard.md) explains repository rules and checks author comments without executing pull-request code.
 
+The required GitHub issue-to-PR workflow is defined in
+[DESIGN.md §19.7](DESIGN.md#197-issue-assignment-to-human-merge), together with the
+current implementation boundaries. A static script accepts the assignment and
+confirms it in the issue before starting the implementation lane. Scripts own
+all lane starts, tests, and GitHub communication; model lanes do not start
+subagents, run tests, or access GitHub. The user works in GitHub and merges the
+reviewed PR there. This is a workflow requirement, not a claim of a complete
+deployed integration.
+
 ## Install
 
 ```bash

src/agent_cli/skills/error-fix/SKILL.md

@@ -24,6 +24,12 @@ rules live in DESIGN.md §§14–15, §19, and §21.
 
 ## Loop
 
+The static script starts implementation and review lanes, starts the implementer
+again for improvements, executes tests, and performs all GitHub communication.
+Model lanes never start subagents or execute tests themselves. Executor commands
+below belong to the script. See
+[DESIGN.md §19.1](../../../../DESIGN.md#191-responsibility-split).
+
 1. A **script** on this device queries a configured log source, redacts,
    fingerprints, and inserts or enriches `activity.type=error.seen` on this
    session. First insert knocks `da ist Post id <uuid>`. Enrichment never

src/agent_cli/skills/pr-review/SKILL.md

@@ -17,6 +17,12 @@ replace it with a second store or a side process.
 
 ## Gates
 
+The static script starts every review lane and any implementation pass needed
+to address findings. Reviewers return findings to that script; they never start
+subagents or interact with GitHub. Gate recording and GitHub publication below
+are script operations. See
+[DESIGN.md §19.1](../../../../DESIGN.md#191-responsibility-split).
+
 Two dimensions (quality, logic) and two vendor stages (`grok-pr`, then
 `codex-pr`). Codex stages run only if both grok dimensions are `approved`.
 

src/agent_cli/skills/review-loop/SKILL.md

@@ -13,6 +13,12 @@ Without this skill, implementer and reviewer `agent agent` commands refuse.
 
 ## Loop
 
+The static script owns this loop: it starts the implementer, starts the reviewer,
+and starts the implementer again for improvements. The commands below are script
+operations, not instructions for a model to launch another lane. Neither role
+may start subagents, execute tests, or access GitHub. See
+[DESIGN.md §19.1](../../../../DESIGN.md#191-responsibility-split).
+
 No round cap. Repeat until the reviewer sets `approved` or the implementer is
 `blocked`.
 

src/agent_cli/skills/session-store/SKILL.md

@@ -8,6 +8,13 @@ description: >-
 
 # Session store
 
+All GitHub communication, tests, and lane/subagent starts belong to static
+scripts, never to model lanes. For the required assignment workflow, the script
+accepts the issue and confirms acceptance on GitHub before it starts the
+implementation lane. See
+[DESIGN.md §19.7](../../../../DESIGN.md#197-issue-assignment-to-human-merge), which
+separates this requirement from the existing watcher behavior described below.
+
 Install this package locally and put `agent` on `PATH`. There is no second
 binary.
 

src/agent_cli/skills/spine/SKILL.md

@@ -20,6 +20,12 @@ Without spine, `task`, `checklist`, `round`, `check`, `work`, `allow`, `next`,
 
 ## One open step
 
+The static script owns execution and progression. A model lane must not invoke
+`agent run` to launch another lane, run tests, or perform GitHub operations.
+Tests and lane starts in the workflow below are script responsibilities; models
+return their implementation or review results. See
+[DESIGN.md §19.1](../../../../DESIGN.md#191-responsibility-split).
+
 `agent next`, `agent close-step`, and `agent run` are the spine. Do not skip
 keys. Quality and logic of the same vendor stage may be open together.
 `close-step` applies chain guards, then writes via `checklist set`.