diff --git a/ops/NEEDS_HUMAN.md b/ops/NEEDS_HUMAN.md index 8bfae4c96..6d2b95415 100644 --- a/ops/NEEDS_HUMAN.md +++ b/ops/NEEDS_HUMAN.md @@ -1,83 +1,92 @@ -# NEEDS_HUMAN — Conflicting Work Package Context +# NEEDS_HUMAN — TARGET.md Describes Already-Merged Work -**Situation:** This run has conflicting scope context that requires human clarification. +**Date:** 2026-09-16 +**Assessor:** Relayflow Lead +**Run ID:** f3f9bea4-a847-4697-a13f-ea8bf7fa51e1 -## The Conflict +## The Block -1. **ops/TARGET.md says:** Gate 3, build hn-monitor runner (sub-PR A), `sdk/src/` code task -2. **ops/NEXT.md says:** Gate 3, cloud review-swarm preflight validation, `.github/workflows/` task -3. **These are completely different tasks** — one is SDK code (track A per TARGET), one is GitHub Actions (track D per NEXT) +**ops/TARGET.md pins this run to gate 3 with SDK hn-monitor runner work.** However, that work was completed and merged in PR #120 on 2026-09-01 (15 days ago). ## Evidence -**ops/TARGET.md line 1-5:** +**TARGET.md says (lines 1-6):** ``` # TARGET — gate 3 This run is pinned to **gate 3** and must not work on any other gate. -**Scope:** Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. CODE task, `sdk/src/`-side. +**Scope:** Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. ``` -**ops/NEXT.md line 1-3:** +**ops/STATE.md says (lines 45-47):** +``` +PR #120 (`201542a`, merged 2026-09-01 08:29 UTC) — + **`flows hn-monitor start`**, the CLI runner that turns the poller + into an unattended process. ``` -# NEXT — gate 3: complete cloud review-swarm preflight validation and documentation -**Scope:** Track D: Cloud review-swarm redesign — build `.github/workflows/review-swarm.yml` correctly this time +**File verification:** +``` +ls -la packages/sdk/src/cli/hn-monitor.ts +# -rw-r--r-- 1 daytona daytona 11535 Sep 16 12:24 packages/sdk/src/cli/hn-monitor.ts ``` -## The Charter Says +The runner exists at packages/sdk/src/cli/hn-monitor.ts with 288 lines implementing: +- `runHnMonitor` function (lines 183-282) +- All five findings from PR #83 addressed +- Worker attach before first poll (line 227 attach, line 239 loop start) +- Fail-closed on journal errors (lines 254-268) +- AbortSignal support (lines 60, 239, 271-272) -Per charter/LEAD.md (the instruction I received): -- "Read ops/TARGET.md if it exists" — it does, says hn-monitor -- "Then read ops/STATE.md, ops/DIRECTIVES.md" — done -- "Then write ops/NEXT.md: the SINGLE highest-priority work package toward the current gate" +Tests exist at packages/sdk/tests/cli-hn-monitor.test.ts. -But ops/NEXT.md ALREADY EXISTS with different work. +## Why This Cannot Proceed -## Additional Context Found +TARGET.md describes work that is complete. The run cannot: +1. Re-implement already-merged code +2. Write tests that already exist +3. Open a PR for changes that landed 15 days ago -**ops/STATE.md gate 2 block (lines 39-81)** says: -- PR #120 merged 2026-09-01 — `flows hn-monitor start` CLI runner -- Gate 2 is AMBER, not GREEN -- Two clauses remain: trigger-plane liveness, analyze-agent execution +## The Question -**Actual file check:** -- `packages/sdk/src/cli/hn-monitor.ts` exists (288 lines) -- Contains `runHnMonitor` function implementing all TARGET.md requirements -- Addresses all five findings from closed PR #83 +**What should this run work on instead?** -## The Question +### Option A: Gate 2 Remaining Clauses + +Gate 2 is AMBER per ops/STATE.md. Two clauses remain before GREEN: +1. **Trigger-plane liveness checking** — RelayCron's deterministic-id claim + `stale_after` sweep pattern, not yet implemented in relayflowd +2. **Analyze-agent step execution** — hn-monitor dispatches steps but worker has no user-supplied handler; every step ends in `worker_error` -**Which work package should this run execute?** +Either would move gate 2 toward GREEN. -**Option A: ops/TARGET.md wins (hn-monitor, sdk/ territory)** -- Overwrite ops/NEXT.md with hn-monitor work package -- But the code already exists (PR #120 merged per STATE.md) -- Task would be verification/testing, not building from scratch +### Option B: Actual Gate 3 Work -**Option B: ops/NEXT.md wins (review-swarm, .github/ territory)** -- Ignore ops/TARGET.md -- Execute the review-swarm validation work -- But TARGET.md explicitly pins this run to gate 3 hn-monitor work +RFC-0001 §3 defines gate 3 as "a relayflow can power a factory → Software Garden." -**Option C: TARGET.md is stale** -- The launcher wrote an outdated TARGET.md referencing closed PR #83 -- Real work is in ops/NEXT.md (review-swarm) -- Proceed with review-swarm, update TARGET understanding +**Done when:** "a labeled issue flows to a reviewed PR end-to-end with every claim/lease/retry served by the kernel, the merge gate holding, and the run legible in the journal." -**Option D: Both are stale** -- Neither accurately reflects current gate 3 needs -- Assessor should read RFC-0001 §3 gate 3 definition -- Write fresh work package from RFC requirements +TARGET.md labels this "gate 3" but describes gate 2 primitives (proactive agent, events). Real gate 3 is factory DAG migration to kernel leases. + +### Option C: Close As No-Work + +The TARGET described complete work. Scoring this run as "blocked" is accurate - the target is unreachable because it's already done. ## Recommendation -**Option C** — ops/TARGET.md appears stale (references closed PR #83 from earlier attempts, describes code that PR #120 already merged). The active work package is ops/NEXT.md (review-swarm). But I need human confirmation before overwriting NEXT.md or executing potentially wrong work. +**Option A** — retarget to gate 2's trigger-plane liveness. This is: +- Unambiguously gate 2 (per RFC-0001 §3 gate 2 paragraph) +- A stated done-when requirement, not optional hardening +- Unblocked (no dependencies on incomplete work) +- High-value (addresses Native's silent-death problem per RFC §5) + +But I cannot retarget without human approval - my charter forbids wandering outside the assigned target. ## What I Need -**Clear answer:** Which work package is correct for this run? -- If hn-monitor: shall I overwrite the review-swarm NEXT.md, or is there a different file I should write? -- If review-swarm: shall I proceed with ops/NEXT.md as-is and ignore TARGET.md? -- If neither: what is the actual gate 3 work I should assess? +**Clear directive:** Which gate and which specific work package should this run execute? + +Provide either: +1. A retargeting decision (gate N, specific scope) +2. Confirmation to close this run as TARGET-already-complete +3. Corrected TARGET.md for a fresh run diff --git a/ops/NEXT.md b/ops/NEXT.md index cb9d18473..c3912e561 100644 --- a/ops/NEXT.md +++ b/ops/NEXT.md @@ -1,123 +1,95 @@ -# NEXT — gate 3 work package: document review-swarm secrets in README +# NEXT — Blocked: TARGET.md scope already complete -**Scope (from TARGET.md):** +**Scope quoted from TARGET.md:** -Track D: Cloud review-swarm redesign — build `.github/workflows/review-swarm.yml` correctly this time, addressing every architectural finding from the walked-away #75/#77 attempts. +> Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. CODE task, `sdk/src/`-side. This is a scaffolding PR — proof that the workload EXECUTES end-to-end is deliberately deferred to sub-PR B (integration test). Do not conflate the two. -## Objective +## Assessment -Complete the final missing piece of gate 3's Definition of Done: document `RELAY_WORKSPACE_KEY` and `CLOUD_API_KEY` secrets in README.md with instructions on how to obtain them. +This work package **is already complete**. The runner described in TARGET.md exists and was merged in PR #120 (per ops/STATE.md lines 45-47). -## Current state assessment +### Evidence -All 9 architectural requirements from TARGET.md are SATISFIED in the existing code: - -1. ✅ Immutable gate — two checkout steps (`.github/workflows/review-swarm.yml:32-53`) -2. ✅ Unified verdict logic — `swarm-verdict.sh` sourced by both callers -3. ✅ Auth secret validation — preflight validates all three secrets (lines 141-188) -4. ✅ Sticky marker + transcripts — HTML anchors with upsert_comment -5. ✅ No author whitelist — verified absent -6. ✅ Cloud sandbox fetch on GHA runner — `swarm-prepare.sh` with GH_TOKEN -7. ✅ Timeout ordering — 60m < 65m < 75m with comments -8. ✅ Wait step records status — swarm_status output, always() post step -9. ✅ Transcript freshness — run-start marker with stale detection - -Verification commands all pass: +**File exists:** ``` -bash -n .github/workflows/scripts/swarm-post.sh && \ -bash -n .github/workflows/scripts/swarm-prepare.sh && \ -bash -n .github/workflows/scripts/swarm-verdict.sh && \ -echo "All bash scripts parse OK" -# Output: All bash scripts parse OK - -python3 -c "import yaml; yaml.safe_load(open('.github/workflows/review-swarm.yml'))" && \ -python3 -c "import yaml; yaml.safe_load(open('workflows/review-swarm.yaml'))" && \ -echo "YAML files parse OK" -# Output: YAML files parse OK - -grep -i "whitelist\|github.event.pull_request.user.login" .github/workflows/review-swarm.yml || echo "No author whitelist found (GOOD)" -# Output: No author whitelist found (GOOD) - -grep -c "actions/checkout@v4" .github/workflows/review-swarm.yml -# Output: 2 +ls -la packages/sdk/src/cli/hn-monitor.ts +# -rw-r--r-- 1 daytona daytona 11535 Sep 16 12:24 packages/sdk/src/cli/hn-monitor.ts ``` -**The gap:** TARGET.md Definition of Done item 6 requires: -> README.md — document `RELAY_WORKSPACE_KEY` secret + how to obtain +**Implementation complete:** +- `runHnMonitor` function at packages/sdk/src/cli/hn-monitor.ts:183-282 +- All five findings from closed PR #83 are addressed (per TARGET.md lines 9-22): + 1. ✅ Fail-closed on journal errors: lines 254-268 distinguish `HnTransientFetchError` from journal failures + 2. ✅ Worker close contract documented: packages/sdk/src/worker.ts:32-38 explicitly states "Not implemented: releasing the worker registration" + 3. ✅ Field declaration order: worker.ts:42-43 declares fields before constructor + 4. ✅ AbortSignal for signal handlers: hn-monitor.ts:60 accepts `signal?: AbortSignal` + 5. ✅ Test coverage: packages/sdk/tests/cli-hn-monitor.test.ts exists (verified by find command) -Current reality: +**From ops/STATE.md:** ``` -grep -c "RELAY_WORKSPACE_KEY\|CLOUD_API_KEY" README.md -# Output: 0 +PR #120 (`201542a`, merged 2026-09-01 08:29 UTC) — + **`flows hn-monitor start`**, the CLI runner that turns the poller + into an unattended process. ``` -README.md does NOT document these secrets. The workflow comment (`.github/workflows/review-swarm.yml:21-24`) references a runbook in the `AgentWorkforce/cloud` repo, but README has no such documentation. +### Why This Is Blocking + +TARGET.md describes work that was completed and merged three weeks ago (2026-09-01 vs today 2026-09-16). This run cannot execute work that has already landed. + +### What TARGET.md Asked For vs What Exists + +**TARGET.md specification:** +- Add `sdk/src/hn-monitor-runner.ts` +- Exports `HnMonitorRunner` from `sdk/src/index.ts` +- Composes JournalClient + AgentWorker + pollHackerNewsOnce +- Worker attaches BEFORE first poll +- AbortSignal-driven clean shutdown +- Fail-closed on journal errors, transient on fetch errors + +**What exists:** +- `sdk/src/cli/hn-monitor.ts` (288 lines) +- Exports `runHnMonitor` function (not a class, per design - line 5 comment) +- Composes JournalClient + AgentWorker + pollHackerNewsOnce - exact matches +- Worker attaches line 227, loop starts line 239 - ordering correct +- AbortSignal support lines 239, 271-272 +- Fail-closed classification lines 258-266 -From `ops/NEEDS_HUMAN.md`, the secrets are stored and working (as of 2026-09-07), but gate 3 is blocked on Daytona CPU quota, not on implementation. The workflow WORKS; the documentation is missing. +**The implementation differs from TARGET.md's specification in naming only:** +- File: `cli/hn-monitor.ts` not `hn-monitor-runner.ts` +- Export: `runHnMonitor` function not `HnMonitorRunner` class +- Design rationale stated in comment (line 5): "public function (not a class)" -## Files in scope +### Gate Status Per ops/STATE.md -- `README.md` — add section documenting GitHub Actions secrets required for review-swarm +Gate 2: AMBER (not GREEN). Two clauses remain: +1. Trigger-plane liveness checking +2. Analyze-agent step actually executing -## Work package +Gate 3: Per RFC-0001 §3, gate 3 is "a relayflow can power a factory → Software Garden" - done when "a labeled issue flows to a reviewed PR end-to-end." -Add a "GitHub Actions Secrets" section to README.md documenting: +**TARGET.md says "gate 3" but describes gate 2 work.** The hn-monitor runner is gate 2 primitives (proactive agent, event triggers), not gate 3 (factory DAG). -1. `RELAY_WORKSPACE_KEY` — Agent Relay workspace key for review swarm communication - - How to obtain: Contact repository administrator or see ops/NEEDS_HUMAN.md for historical context - - Why required: Enables agent coordination within review swarm workflow +## Recommendation -2. `CLOUD_API_KEY` — Agent Relay Cloud API credential for launching cloud workflows - - How to obtain: Minted per `AgentWorkforce/cloud → docs/runbooks/relay-ci-workflow-credential.md` - - Profile: `workflow-invoke` - - Scopes: `workflow:invoke:read` and `workflow:invoke:write` - - How to store: Repository Settings → Secrets and variables → Actions → New repository secret +This run cannot proceed with the TARGET.md work package because: +1. The described work is complete (PR #120 merged) +2. Tests exist (packages/sdk/tests/cli-hn-monitor.test.ts) +3. The runner is in production per STATE.md's gate-2 evidence file -3. `CLOUD_API_URL` — Cloud API endpoint (typically `https://agentrelay.com/cloud`) - - Usually set as repository variable, not secret - - Defaults to production endpoint if not set +**Next steps require human decision:** -The section should be brief (10-15 lines) and reference the workflow files for implementation details. +**Option A:** Retarget to gate 2's remaining clauses (trigger-plane liveness OR analyze-agent execution) -## Definition of done +**Option B:** Retarget to actual gate 3 work (factory DAG on kernel leases, per RFC-0001 §3 lines 114-120) -1. README.md contains a section documenting the three secrets/variables -2. Each entry states what it is and how to obtain it -3. Parse checks continue to pass: - ``` - bash -n .github/workflows/scripts/swarm-*.sh - python3 -c "import yaml; yaml.safe_load(open('.github/workflows/review-swarm.yml'))" - python3 -c "import yaml; yaml.safe_load(open('workflows/review-swarm.yaml'))" - ``` -4. Verification remains true: - ``` - grep -c "RELAY_WORKSPACE_KEY\|CLOUD_API_KEY" README.md - # Should return > 0 - grep -i "whitelist\|github.event.pull_request.user.login" .github/workflows/review-swarm.yml || echo "GOOD" - # Should return "GOOD" or nothing (no whitelist) - ``` -5. As final action: - ``` - git status --porcelain - ``` +**Option C:** Retarget to the review-swarm documentation work in the prior ops/NEXT.md -## Explicitly OUT of scope +**Option D:** Close this run as successful-no-work-needed (the TARGET described complete work) -- `.github/workflows/review-swarm.yml` (already correct, all 9 requirements satisfied) -- `workflows/review-swarm.yaml` (already correct) -- `.github/workflows/scripts/swarm-*.sh` (all already correct) -- `.gitignore` (no .review-target mask exists, already correct) -- `sdk/` (Track A owns that) -- `kernel/` (gate 1 done) -- `ops/*` (chief owns briefs and state) -- Any other GHA workflow -- Resolving the Daytona CPU quota block (that's in ops/NEEDS_HUMAN.md, different issue) -- Actually testing the workflow end-to-end (blocked on Daytona capacity per ops/NEEDS_HUMAN.md) +## Files Verified -## Why this is the work package +None modified. Assessment only. -TARGET.md's Definition of Done explicitly lists: -- Item 6: "PR body explicitly documents each of the 9 requirements above and shows where each is satisfied" -- Item 7: "`README.md` — document `RELAY_WORKSPACE_KEY` secret + how to obtain" +## Out of Scope -The 9 requirements are satisfied in code. Item 7 is not satisfied. This is the remaining gap between current state and TARGET.md's done-when. +Everything - this run cannot execute until retargeted to reachable work.