diff --git a/ops/NEEDS_HUMAN.md b/ops/NEEDS_HUMAN.md index 1601be68d..387d96606 100644 --- a/ops/NEEDS_HUMAN.md +++ b/ops/NEEDS_HUMAN.md @@ -1,4 +1,36 @@ -# NEEDS_HUMAN — gate 3 launches; the block moved to Daytona capacity +# NEEDS_HUMAN — multiple blockers + +## Current blocker (2026-09-12, run afcc2c6f) — SDK compilation errors + +**Assessment:** Gate 3 hn-monitor-runner work is BLOCKED on SDK compilation errors. + +The gate 3 target (ops/TARGET.md) requires implementing `sdk/src/hn-monitor-runner.ts` with comprehensive test coverage. The definition of done includes "`cd packages/sdk && npm test` green (pretest hook builds the kernel automatically)". + +**The block:** The SDK does not compile. TypeScript errors prevent npm test from running: + +``` +src/authored-worker-step.ts(118,80): error TS2339: Property 'cwd' does not exist on type 'AgentOptions'. +src/cli/check-triggers.ts(23,19): error TS2339: Property 'handlers' does not exist on type 'AuthoredFlowDefinition'. +src/helper-preflight.ts(1,10): error TS2305: Module '"@relayflows/surface/runtime"' has no exported member 'helperProviders'. +src/helper-writeback.ts(5,10): error TS2305: Module '"@relayflows/surface/runtime"' has no exported member 'helperClients'. +src/preflight.ts(7,15): error TS2305: Module '"@relayflows/surface"' has no exported member 'TriggerSource'. +src/slack-preflight.ts(3,10): error TS2305: Module '"@relayflows/surface/runtime"' has no exported member 'helperProviders'. +src/slack-writeback.ts(3,15): error TS2305: Module '"@relayflows/surface"' has no exported member 'SlackHelper'. +src/trigger-executor.ts(1,10): error TS2305: Module '"@relayflows/surface"' has no exported member 'providerEventTypes'. +``` + +These errors indicate missing or incompatible dependencies from the `@relayflows/surface` package. + +**Question for human:** Should the Lead fix the SDK compilation errors first (which appears out of scope for the gate 3 hn-monitor-runner target), or is there an environment/dependency issue that needs resolution before this work can proceed? + +**Options:** +- **A:** Fix the SDK compilation errors first. This would be out-of-scope work (SDK package dependencies, not the runner itself), but it unblocks the target. +- **B:** Wait for human intervention to resolve the SDK compilation environment, since fixing package dependencies is outside the gate 3 scope defined in TARGET.md. +- **C:** Something else (e.g., the compilation errors are expected in this environment and there's a different test command to use). + +--- + +## Prior blocker (2026-09-08) — gate 3 launches; the block moved to Daytona capacity ## Status (2026-09-08 ~04:00Z) — supersedes the 2026-09-07 assessment below diff --git a/ops/NEXT.md b/ops/NEXT.md index ab03203b6..27fe88ecb 100644 --- a/ops/NEXT.md +++ b/ops/NEXT.md @@ -1,86 +1,103 @@ -# NEXT — gate 3: complete cloud review-swarm preflight validation and documentation +# ops/NEXT.md — work package for this tick -**Scope:** 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. Parallel to Track A (hn-monitor); different territory (`.github/` + `workflows/` — no overlap with `sdk/` work). +**Date:** 2026-09-12 +**Current gate:** Gate 2 (per RFC-0001 §3; gate 1 is GREEN per STATE.md) +**Assessor:** Relayflow Lead +**Target:** Gate 3 per ops/TARGET.md (though the work directly advances Gate 2's "hn-monitor runs as a relayflow in production" done-when) -## Why this matters +## Scope (quoted from ops/TARGET.md) -The local `~/AgentWorkforce/review-swarm-loop.sh` (chief-owned shell) is currently the only enforcement of RFC-0001 §2 rule 7 ("every PR met by a review swarm — our own, not a vendor's"). It works, but it lives on my laptop. When my session ends, so does swarm enforcement. +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. -The cloud version — `workflows/review-swarm.yaml` fired from `.github/workflows/review-swarm.yml` — must exist for gate 3+ work to be trustworthy. Prior attempts (#75, #77) each shipped real code but were rejected on progressively deeper findings we never resolved. +RFC-0001 §3 gate 2 is done when "hn-monitor runs as a relayflow in production, triggered by its real events, with zero bespoke persistence." Every primitive already exists in this repo — event triggers (PR #14), the flow spec (`testdata/hn-monitor.flow.yaml`), the poller (`sdk/src/hn-poller.ts`), the agent worker (`sdk/src/worker.ts` from PR #53), a one-shot demo (`sdk/src/demo-hn-monitor.ts`) — but nothing has ever run them together as a continuous workload. This PR fixes that. -## Current state +Prior attempt (PR #83, closed) produced a functional runner but was rejected by the swarm on five real findings. Address them in this attempt: -The review-swarm implementation is 90% complete. Analysis of the 9 non-negotiable requirements: +1. **Fail-closed on journal errors.** Only fetch-level errors (network flakiness, HN API rate limits) may be swallowed; a journal write failure MUST throw and terminate the runner. Split: `try { fetch } catch { onFetchError }` around the network call, `try { eventSubmit } catch { rethrow }` around the journal call. -1. ✅ Immutable gate — two checkout steps at `.github/workflows/review-swarm.yml:32-48` (pr-head + gate-files from main) -2. ✅ Unified verdict logic — `swarm-verdict.sh` sourced by both `review-swarm.yaml:132` and `swarm-post.sh:8` -3. ✅ Auth secret validation — all three are checked in the "Validate cloud authentication" step: `CLOUD_API_URL`, `CLOUD_API_KEY` and `RELAY_WORKSPACE_KEY` (`.github/workflows/review-swarm.yml:56-58`) -4. ✅ Sticky marker + transcripts — HTML anchors `` in swarm-post.sh:34,39,44,47 -5. ✅ No author whitelist — grep confirms absent -6. ✅ Cloud sandbox fetch on GHA runner — swarm-prepare.sh runs in step "Prepare review input" with GH_TOKEN -7. ✅ Timeout ordering — 60m (review-swarm.yaml:18) < 65m (review-swarm.yml:112) < 75m (review-swarm.yml:19) with comments -8. ✅ Wait step records status, post runs on always() — review-swarm.yml:106-130,132-137 -9. ✅ Transcript-to-run-id binding via freshness — swarm-prepare.sh:11 creates run-start marker; swarm-verdict.sh:33-34 rejects stale transcripts +2. **AgentWorker.close() must release the worker (or explicitly document it does not).** Either add a `workerRelease` verb and call it from `close()`, OR add a one-line comment on `close()` naming exactly what shutdown intentionally does NOT do. **Current state:** `sdk/src/worker.ts:32-37` already has the comment documenting this. No changes needed for finding #2. -Additionally: README.md is already correct and needs no edit. The secrets -table documents RELAY_WORKSPACE_KEY and CLOUD_API_KEY, and the sentence below -it concerns CLOUD_API_URL only. The stale CLOUD_API_ACCESS_TOKEN_EXPIRES_AT -mention was removed earlier in this branch, so the check below already passes. +3. **Class field declaration order.** Declare ALL fields at the top of the class body, before the constructor. + +4. **Signal handlers must be opt-in via AbortSignal.** Accept `signal?: AbortSignal` in options; the CLI wrapper (sub-PR C) can create + wire a process-signal-driven AbortController. + +5. **Test coverage for pollError branch.** Tests must assert the loop survives a fetcher throw AND the loop TERMINATES on a journal throw. + +## Objective + +Add `sdk/src/hn-monitor-runner.ts` that composes existing pieces into a continuous runner addressing all five findings from PR #83. ## Files in scope -Nothing. Every item this brief once listed is already done in this branch. The two items previously listed here — preflight validation and -the secrets table — are already done in this branch. A brief that asks for -finished work does not produce a no-op; it produces an agent that re-derives -the state, changes something to justify the trip, or declares a false blocked, -which is the wasted cycle this file exists to prevent. +- `sdk/src/hn-monitor-runner.ts` (new file) +- `sdk/src/index.ts` (export `HnMonitorRunner`) +- `sdk/tests/hn-monitor-runner.test.ts` (new file with comprehensive test coverage) ## Definition of done -1. ✅ Already satisfied — preflight checks all three required secrets: -``` -test -n "$CLOUD_API_URL" -test -n "$CLOUD_API_KEY" -test -n "$RELAY_WORKSPACE_KEY" -``` +ALL of the following must hold: -2. ✅ Already satisfied — README needs no change. Its table names - RELAY_WORKSPACE_KEY and CLOUD_API_KEY, and the stale expiry mention is gone: -``` -grep -c CLOUD_API_ACCESS_TOKEN_EXPIRES_AT README.md # already 0 -``` +1. `sdk/src/hn-monitor-runner.ts` exists, exports `HnMonitorRunner` from `sdk/src/index.ts` -3. All files continue to parse: -``` -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" -``` +2. The runner implementation: + - Constructs a `JournalClient` connected to the running `relayflowd` socket + - Constructs an `AgentWorker` and calls `workerAttach()` BEFORE first poll + - Loops: `pollHackerNewsOnce(spec, sink)` → sleep `POLL_INTERVAL_MS` (env-configurable, default 60000) → repeat + - Exits cleanly on `AbortSignal.abort` (drain in-flight steps, close client) + - All class fields declared at top of class body (finding #3) + - Accepts `signal?: AbortSignal` in options (finding #4) + - Fail-closed on journal errors: fetch errors swallowed, journal errors thrown (finding #1) + - NO scheduling logic beyond the sleep + - NO LLM calls -``` -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" -``` +3. `sdk/tests/hn-monitor-runner.test.ts` covers ALL of these (finding #5): + - fake fetch + mock journal client → runner submits an event on each tick + - abort signal triggers clean shutdown within one tick + - worker attach happens before first poll + - **fetch throw → loop survives** (onPollError called, next tick still runs) + - **journal throw → loop TERMINATES** (runner.run() rejects with the error) -4. No author whitelist exists: -``` -grep -i "whitelist\|github.event.pull_request.user.login" .github/workflows/review-swarm.yml || echo "No author whitelist found (GOOD)" -``` +4. `cd packages/sdk && npm test` green (pretest hook builds the kernel automatically) + +5. EVERY new test confirmed to FAIL against current code (comment out the source; the test fails), with the literal failing output pasted in the PR body + +6. As final action: run `git status --porcelain` and paste it + +## Explicit non-goals for THIS PR + +- Proving the workload actually executes end-to-end (dispatch → step complete). That is sub-PR B. +- CLI wrapper (`flows hn-monitor start`). That is sub-PR C. +- ops/STATE.md gate-2 GREEN declaration. That is sub-PR D. + +## Out of scope — DO NOT TOUCH + +- `.github/workflows/*` +- `kernel/*` +- `workflows/*.yaml` +- `ops/AUTODRIVE_BRIEF.md` +- `sdk/src/worker.ts` (finding #2 already satisfied by existing comment at lines 32-37) +- CLI wrapper (sub-PR C) +- end-to-end integration test (sub-PR B) +- ops/STATE.md gate-2 declaration (sub-PR D) + +## BLOCKED: SDK does not compile + +**STATUS:** BLOCKED_NEEDS_HUMAN + +The SDK currently has TypeScript compilation errors preventing `npm test` from running. Attempting `cd packages/sdk && npm ci && npm test` fails with: -5. As final action: ``` -git status --porcelain +error TS2339: Property 'cwd' does not exist on type 'AgentOptions'. +error TS2339: Property 'handlers' does not exist on type 'AuthoredFlowDefinition'. +error TS2305: Module '"@relayflows/surface/runtime"' has no exported member 'helperProviders'. +error TS2305: Module '"@relayflows/surface/runtime"' has no exported member 'helperClients'. +error TS2305: Module '"@relayflows/surface"' has no exported member 'TriggerSource'. +error TS2305: Module '"@relayflows/surface"' has no exported member 'SlackHelper'. +error TS2305: Module '"@relayflows/surface"' has no exported member 'providerEventTypes'. ``` -## Explicitly OUT of scope +These errors indicate missing or incompatible dependencies from the `@relayflows/surface` package. The work package CANNOT be completed without a working SDK test suite. + +**Question for human:** Should the Lead fix the SDK compilation errors first (which appears out of scope for the gate 3 hn-monitor-runner target), or is there an environment/dependency issue that needs resolution before this work can proceed? -- `workflows/review-swarm.yaml` (already correct) -- `.github/workflows/scripts/swarm-*.sh` (all three scripts already correct) -- `.gitignore` (already correct - no .review-target mask) -- `sdk/` (Track A) -- `kernel/` (gate 1 done, no changes) -- `ops/*` (chief owns briefs and state) -- Any GHA workflow other than review-swarm.yml -- Actually TESTING the workflow in CI (requires `RELAY_WORKSPACE_KEY` + `CLOUD_API_KEY` secrets set which is a human step per requirement #3's context) +The target is pinned to gate 3 and must not work on any other gate. If gate 3 is genuinely unreachable from the current state (SDK doesn't compile), this is the honest report of that blocker.