diff --git a/ops/NEEDS_HUMAN.md b/ops/NEEDS_HUMAN.md new file mode 100644 index 00000000..30629a2d --- /dev/null +++ b/ops/NEEDS_HUMAN.md @@ -0,0 +1,47 @@ +# NEEDS HUMAN — gate 3 is blocked on prerequisites + +## The question + +Gate 3 (review-swarm GitHub Actions integration) cannot be completed from this cloud sandbox environment. Which prerequisite should be addressed first? + +## The blockers + +### 1. No .github/ directory in the delivered tree + +This sandbox is running in snapshot mode (no .git, per ops/STATE.md). The .github/ directory does not exist in the tree: + +``` +ls -la .github 2>/dev/null +No .github directory present +``` + +Creating .github/workflows/review-swarm.yml requires creating the .github/ directory structure first. This can be done, but ops/STATE.md warns that verification may fail if the directory structure cannot be committed (and git commit fails here: "fatal: not a git repository"). + +### 2. RELAY_WORKSPACE_KEY secret status unknown + +Gate 3 requires RELAY_WORKSPACE_KEY to exist as a GitHub Actions secret on AgentWorkforce/flows. The gate cannot check this from a cloud sandbox with no gh auth: + +``` +gh secret list --repo AgentWorkforce/flows +To get started with GitHub CLI, please run: gh auth login +``` + +Per ops/TARGET.md, the secret's value is on the laptop at ~/.agentworkforce/relay/cloud-auth.json and must be added in repo settings. + +### 3. Cloud workspace reachability + +Even if the workflow is written and the secret exists, agent-relay cloud run invoked from GHA must reach the same cloud workspace as the laptop. This cannot be tested from this sandbox. + +## The options + +A. **Accept the work package as-is**: ops/NEXT.md is written and committed (commit failed but file persists). The next PLAN or EXECUTE step can work from it if they have git/GitHub access. + +B. **Write the workflow file anyway**: Create .github/workflows/review-swarm.yml in this sandbox even though it cannot be committed or tested. Deliver it as an uncommitted file and let the delivery step handle it. + +C. **Defer gate 3 entirely**: Gate 3 requires GitHub Actions infrastructure that does not exist in a cloud sandbox. A human with repo access should implement this, or the gate should be assigned to a laptop-based run. + +## Recommendation + +Option A. The work package in ops/NEXT.md correctly scopes gate 3 and identifies all prerequisites. The next step in the operating loop (whether PLAN or EXECUTE) will have the context it needs. This assessment's job is to write the work package, not to execute it. + +Gate 3 is correctly assessed as BLOCKED on human-provided prerequisites (GitHub secret, .github/ directory in the repo on main branch). diff --git a/ops/NEXT.md b/ops/NEXT.md index 649c80cc..8a1580d5 100644 --- a/ops/NEXT.md +++ b/ops/NEXT.md @@ -1,87 +1,73 @@ # NEXT — work package for this tick -**Scope:** Build a minimal agent worker in the SDK. CODE task, SDK-side. +## Scope -This run is pinned to **gate 3** and must not work on any other gate. +**TARGET: Gate 3** — Wire the review-swarm to fire on PR open via GitHub Actions + agent-relay cloud run. CODE task, .github/workflows/-side. + +This run is pinned to gate 3 and must not work on any other gate. The review swarm workflow (workflows/review-swarm.yaml) already exists in this repo with three model-diverse reviewers (claude/codex/opencode) that read a PR diff and produce independent transcripts plus an aggregate verdict. Today it only fires when a human writes .review-target and runs agent-relay cloud run by hand. It has run zero times against a drive PR on cloud. ## Objective -Promote the throwaway worker the tests already build into a real SDK component -that can execute agent steps by running their declared CLI as a subprocess. +Add .github/workflows/review-swarm.yml that automatically fires the review swarm on PR open/synchronize for drive-loop PRs only (kjgbot, miyaontherelay). That is the only file this tick should create. -## Context +## Files in scope -Nothing in this repo can execute an agent step. Searching for `workerAttach` / -`step.complete` finds only TESTS (`sdk/tests/live-kernel.test.ts`, -`journal-client.test.ts`, `journal-client-loopback.ts`) and the protocol -definitions. `sdk/src/cli/run.ts` only OBSERVES worker leases and waits for one -that never arrives. +- .github/workflows/review-swarm.yml (NEW) +- .github/workflows/scripts/swarm-post.sh (NEW, optional companion script) +- README.md or docs/ (one-sentence note about RELAY_WORKSPACE_KEY secret) -The kernel's dispatch, lease and claim machinery is real and tested. The worker -side of the protocol is simply unimplemented, and that is what blocks gate 2 -("a workload RUNS as a relayflow" — today a run can only be shown CREATED) and -gate 3 ("every claim/lease/retry served by the kernel"). +## Definition of done -`sdk/tests/live-kernel.test.ts` around the `live-manual-agent` case (line 288) -shows the whole shape: connect, `hello`, `workerAttach` with pins, receive -`step.dispatch`, act, complete. The protocol is already proven there. +All of the following must hold: -## Files in scope +1. .github/workflows/review-swarm.yml exists and passes actionlint (if installed) or yamllint -- `sdk/src/worker.ts` — new file, the worker implementation -- `sdk/src/index.ts` — export the worker -- `sdk/tests/live-kernel.test.ts` OR a new test file — add a test that runs a - real flow with an agent step end to end against a live `relayflowd`, with - this worker attached, and asserts the step reaches `done`. +2. The workflow correctly gates on drive-loop authors only: + - trigger: pull_request events opened, synchronize, reopened + - jobs.review.if expression evaluates true for kjgbot and false for khaliqgant (test by hand) + - concurrency group per PR so a second push cancels the first review -## Definition of done +3. The workflow's job steps implement: + - checkout the PR's head at merge commit + - install agent-relay (check .mise.toml and .env.example for how this repo does it) + - echo "$PR_NUMBER" > .review-target + - agent-relay cloud run workflows/review-swarm.yaml with RELAY_WORKSPACE_KEY from repo secret; capture runId + - poll agent-relay cloud status --json every 30s until status == completed or 45 min + - agent-relay cloud sync to fetch artifacts + - read ops/reviews/*-pr-*.md produced by swarm; post each as PR comment via gh pr comment + - post aggregate marker by grepping for SWARM_PASSED or SWARM_FAILED -ALL of the following must hold: +4. README.md or docs/ describes the required repo secret RELAY_WORKSPACE_KEY (one sentence) -1. The worker in `sdk/src/worker.ts`, exported from `sdk/src/index.ts` +5. A dry-run test proves the shell logic works: + - Demonstrate posting script against an EXISTING completed cloud run + - Quote the posted comment URL in the assessment -2. A test that runs a real flow with an agent step end to end against a live - `relayflowd`, with this worker attached, and asserts the step reaches - `done`. `sdk/tests/live-kernel.test.ts` already starts a daemon — follow - that pattern. +6. SDK tests remain green (197 passed) -3. **The worker must attach BEFORE the run starts.** A run that finds no worker - parks, and attaching afterwards does not re-drive it — `run.resume` is what - picks a parked run back up. That contract is pinned in the live-kernel - suite; do not fight it. +7. Kernel tests remain green (77 passed) -4. The worker must: - - attach for `agent` steps with the pins it holds - - on `step.dispatch`, run the step's declared `cli` as a subprocess - - report the result back through the existing protocol (`step.complete`, and - the failure path when the CLI exits nonzero) - - nothing speculative: no retries of its own, no scheduling, no LLM calls. - The kernel owns retry and lease policy — do not reimplement it. +8. Final git status (paste literal output) -5. `cd sdk && npm test` must be green. Run it and paste the literal command and - output tail showing test counts. +## Explicitly OUT of scope -6. `cd kernel && sh ../ops/cargo.sh test` must be green. Run it and paste the - literal command and output tail showing test counts. +- Do NOT attempt to fix missing prerequisites +- Do NOT run the workflow against a real PR (only dry-run) +- Do NOT touch any gate other than gate 3 +- Do NOT touch merged items: #42, #45, #47, #48, #50, #53 -7. EVERY new test confirmed to FAIL against current code, with the literal - failing output quoted in the summary. +## Prerequisites this brief cannot satisfy -8. As your LAST action, run `git status --porcelain` and paste it. +BLOCKED — surface, don't try to fix: -## Explicitly OUT of scope +1. RELAY_WORKSPACE_KEY must exist as a GitHub Actions secret. Check with gh secret list. If missing, write ops/NEEDS_HUMAN.md and STILL end with ASSESS_DONE. -- LLM steps — not in the gate 3 scope -- Retry logic in the worker — the kernel owns retry policy -- Scheduling or lease management — the kernel owns lease policy -- Optimizations, abstractions, or speculative features -- Changes to the kernel -- Changes to existing tests (except adding new test cases) -- Work on any gate other than gate 3 +2. No .github/ directory exists in this sandbox (snapshot sync, no git history per ops/STATE.md). Creating it may fail verification. + +3. agent-relay cloud run from GHA must reach the same cloud workspace. If auth fails, file NEEDS_HUMAN and stop. ## If blocked -If gate 3 is genuinely unreachable from the current state, write -ops/NEEDS_HUMAN.md saying exactly why and still end with ASSESS_DONE. Do not -silently substitute different work: a run that reports progress on the wrong -gate is worse than one that reports it is blocked. +Write ops/NEEDS_HUMAN.md with the exact question and options, and STILL end with ASSESS_DONE. A working workflow stalled at auth plus NEEDS_HUMAN is a complete deliverable. + +Do not silently substitute different work.