From 8009478cf2515184c6d6b362de5855b31c53686e Mon Sep 17 00:00:00 2001 From: Mara Steiner <315884756+marassteiner@users.noreply.github.com> Date: Sun, 6 Sep 2026 20:41:19 +0200 Subject: [PATCH] Document script ownership of the issue-to-PR workflow. --- AGENTS.md | 6 ++ CONTRIBUTING.md | 8 ++- DESIGN.md | 77 ++++++++++++++++++++- README.md | 9 +++ src/agent_cli/skills/error-fix/SKILL.md | 6 ++ src/agent_cli/skills/pr-review/SKILL.md | 6 ++ src/agent_cli/skills/review-loop/SKILL.md | 6 ++ src/agent_cli/skills/session-store/SKILL.md | 7 ++ src/agent_cli/skills/spine/SKILL.md | 6 ++ 9 files changed, 127 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c961b08..7ca1232 100644 --- a/AGENTS.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d2754c..8cd17e4 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/DESIGN.md b/DESIGN.md index c4f257b..8d1cdc1 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -342,7 +342,7 @@ 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 `. 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 `. 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. @@ -350,7 +350,10 @@ The watcher runs on this device (write owner). It is a script, not the model. Th ### 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. diff --git a/README.md b/README.md index b7c4077..6b496c3 100644 --- a/README.md +++ b/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 diff --git a/src/agent_cli/skills/error-fix/SKILL.md b/src/agent_cli/skills/error-fix/SKILL.md index bf09ace..fe68057 100644 --- a/src/agent_cli/skills/error-fix/SKILL.md +++ b/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 `. Enrichment never diff --git a/src/agent_cli/skills/pr-review/SKILL.md b/src/agent_cli/skills/pr-review/SKILL.md index d5b8f77..7c9ed4a 100644 --- a/src/agent_cli/skills/pr-review/SKILL.md +++ b/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`. diff --git a/src/agent_cli/skills/review-loop/SKILL.md b/src/agent_cli/skills/review-loop/SKILL.md index 2c12be5..0a0f6d1 100644 --- a/src/agent_cli/skills/review-loop/SKILL.md +++ b/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`. diff --git a/src/agent_cli/skills/session-store/SKILL.md b/src/agent_cli/skills/session-store/SKILL.md index 79c8fa5..b6c3b58 100644 --- a/src/agent_cli/skills/session-store/SKILL.md +++ b/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. diff --git a/src/agent_cli/skills/spine/SKILL.md b/src/agent_cli/skills/spine/SKILL.md index a6915b4..f5b6277 100644 --- a/src/agent_cli/skills/spine/SKILL.md +++ b/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`.