diff --git a/ops/NEEDS_HUMAN.md b/ops/NEEDS_HUMAN.md index 8bfae4c9..b590b018 100644 --- a/ops/NEEDS_HUMAN.md +++ b/ops/NEEDS_HUMAN.md @@ -1,83 +1,101 @@ -# NEEDS_HUMAN — Conflicting Work Package Context +# NEEDS_HUMAN — TARGET.md Describes Completed Work -**Situation:** This run has conflicting scope context that requires human clarification. +**Date:** 2026-09-15 +**Assessor:** Relayflow Lead (this assessment run) +**Status:** BLOCKED_STALE_TARGET -## The Conflict +## The Issue -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 specifies work that was already completed and merged 15 days ago: -## Evidence +**TARGET.md says:** +> Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. CODE task, `sdk/src/`-side. -**ops/TARGET.md line 1-5:** -``` -# TARGET — gate 3 +**Reality:** +- PR #120 merged 2026-09-01 08:29 UTC (per ops/STATE.md line 47) +- `packages/sdk/src/cli/hn-monitor.ts` exists (288 lines) +- `packages/sdk/tests/cli-hn-monitor.test.ts` exists (346 lines) +- All 5 findings from TARGET.md are addressed in the merged code -This run is pinned to **gate 3** and must not work on any other gate. +## Evidence -**Scope:** Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. CODE task, `sdk/src/`-side. +**Finding #1 (fail-closed on journal errors)** — ADDRESSED: +``` +packages/sdk/src/cli/hn-monitor.ts:257-268 +Splits HnTransientFetchError (continue) vs others (terminate) ``` -**ops/NEXT.md line 1-3:** +**Finding #2 (close() must release or document)** — ADDRESSED: +``` +packages/sdk/src/worker.ts:32-37 +Documents: "Not implemented: releasing the worker registration with the kernel" ``` -# 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 +**Finding #3 (field declaration order)** — MOOT: +Implementation uses function composition, not classes + +**Finding #4 (AbortSignal opt-in)** — ADDRESSED: +``` +packages/sdk/src/cli/hn-monitor.ts:59-60 +Accepts signal?: AbortSignal in args ``` -## The Charter Says +**Finding #5 (test coverage)** — ADDRESSED: +``` +packages/sdk/tests/cli-hn-monitor.test.ts:238 — SURVIVES HnTransientFetchError +packages/sdk/tests/cli-hn-monitor.test.ts:206 — terminates on JournalProtocolError +``` -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" +## The Question -But ops/NEXT.md ALREADY EXISTS with different work. +**What should this run do when TARGET.md describes completed work?** -## Additional Context Found +**Option A: Verify the merged code** +- Run `cd packages/sdk && npm test` +- Confirm all tests pass +- Report: "TARGET.md scope satisfied by PR #120" +- But this isn't a "work package," it's verification -**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 +**Option B: Move to gate 3 actual work** +- Ignore TARGET.md +- Start Software Garden DAG implementation (RFC-0001 §3 gate 3) +- But TARGET.md explicitly pins this run to different scope -**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 +**Option C: Report blocked and await direction** +- Write ops/NEEDS_HUMAN.md (this file) +- Update ops/NEXT.md to document the situation +- End with ASSESS_DONE per charter -## The Question +**I chose Option C** because: +1. Charter says: "If work is blocked on a human decision, write ops/NEEDS_HUMAN.md stating the exact question and the options — and then STILL end with ASSESS_DONE" +2. Cannot determine human intent when TARGET.md is 15 days stale +3. No open PRs need fixes (STATE.md line 129: "Open PRs: NONE") +4. No standing directives (ops/DIRECTIVES.md is empty) -**Which work package should this run execute?** +## What a Human Should Decide -**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 +1. **Is the launcher generating stale TARGET.md files?** + - This is the second time (previous run also hit hn-monitor/review-swarm conflict per old NEEDS_HUMAN.md) -**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 +2. **What is the actual highest-priority work?** + - Gate 2 completion (trigger-plane liveness + analyze-agent execution)? + - Gate 3 start (Software Garden DAG)? + - Infrastructure (review-swarm, which the old NEXT.md mentioned)? -**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 +3. **Should stale-TARGET runs abort early?** + - Or verify the merged code and report green? + - Or attempt to derive next work from RFC §3 gate sequence? -**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 +## Files Updated -## Recommendation +- `ops/NEXT.md` — assessment outcome (TARGET.md scope completed) +- `ops/NEEDS_HUMAN.md` — this file -**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. +## Commit Status -## What I Need +**Commit failed** (expected in cloud sandbox): +``` +fatal: not a git repository: /home/daytona/.project-git +``` -**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? +Per ops/STATE.md lines 195-208, sandboxes have no .git and cannot deliver. Charter instruction was to report commit failure rather than finish silently — reported here. diff --git a/ops/NEXT.md b/ops/NEXT.md index cb9d1847..d629e7de 100644 --- a/ops/NEXT.md +++ b/ops/NEXT.md @@ -1,123 +1,76 @@ -# NEXT — gate 3 work package: document review-swarm secrets in README +# NEXT — work package for this tick -**Scope (from TARGET.md):** +## Assessment outcome -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. +**TARGET.md references completed work.** The scope described in ops/TARGET.md ("Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK") was already completed and merged in PR #120 on 2026-09-01 per ops/STATE.md. -## Objective +## Evidence of completion -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. +**Code exists:** +- `packages/sdk/src/cli/hn-monitor.ts` (288 lines) — complete runner implementation +- `packages/sdk/tests/cli-hn-monitor.test.ts` (346 lines) — comprehensive test coverage -## Current state assessment +**All 5 TARGET.md findings addressed:** -All 9 architectural requirements from TARGET.md are SATISFIED in the existing code: +1. **Fail-closed on journal errors** ✓ + - `cli/hn-monitor.ts:257-268` splits HnTransientFetchError (continue) vs non-transient (terminate) -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 +2. **Worker.close() documentation** ✓ + - `src/worker.ts:32-37` explicitly documents what close() does NOT do (workerRelease not implemented) -Verification commands all pass: -``` -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 -``` - -**The gap:** TARGET.md Definition of Done item 6 requires: -> README.md — document `RELAY_WORKSPACE_KEY` secret + how to obtain +3. **Field declaration order** ✓ + - Implementation uses function composition, not classes (moot) -Current reality: -``` -grep -c "RELAY_WORKSPACE_KEY\|CLOUD_API_KEY" README.md -# Output: 0 -``` +4. **AbortSignal opt-in** ✓ + - `cli/hn-monitor.ts:59-60` accepts `signal?: AbortSignal` in args -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. +5. **Test coverage for pollError branches** ✓ + - `tests/cli-hn-monitor.test.ts:238` — "SURVIVES a typed HnTransientFetchError" + - `tests/cli-hn-monitor.test.ts:206` — "terminates on JournalProtocolError from eventSubmit" -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. +**STATE.md confirmation:** +- Line 47: "PR #120 (`201542a`, merged 2026-09-01 08:29 UTC) — `flows hn-monitor start`, the CLI runner" +- Line 129: "Open PRs: NONE" -## Files in scope +## Actual gate 3 status per RFC-0001 §3 -- `README.md` — add section documenting GitHub Actions secrets required for review-swarm +**Gate 3 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 (no auto-merge without opt-in), and the run legible in the journal" -## Work package +**Reality:** Gate 3 (Software Garden) is not implemented. The hn-monitor work is gate 2 scaffolding, which is AMBER per STATE.md lines 39-81. -Add a "GitHub Actions Secrets" section to README.md documenting: +## No actionable work package available -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 +**Why no package:** +1. TARGET.md describes completed work (hn-monitor runner, merged in PR #120) +2. No open PRs need fixes (STATE.md line 129) +3. No standing directives in ops/DIRECTIVES.md (file empty except header) +4. Gate 3's actual work (Software Garden DAG) requires architectural planning beyond a single tick -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 +**Previous assessor reached same conclusion:** ops/NEEDS_HUMAN.md from earlier run documented this exact conflict — TARGET.md (hn-monitor) vs NEXT.md (review-swarm) vs actual state (both stale). -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 +## Recommendation -The section should be brief (10-15 lines) and reference the workflow files for implementation details. +**This run should be marked as ASSESS_BLOCKED** because: +- TARGET.md scope is already completed +- No alternative work package can be derived from current state without human direction +- RFC-0001 §3 gate 3 requires substantial new architecture (Software Garden), not a single-tick package -## Definition of done +**What a human should do:** +1. Confirm PR #120 satisfies the TARGET.md intent (even though it merged before this run launched) +2. Decide whether gate 3 work should start (Software Garden DAG), or +3. Focus on completing gate 2 (trigger-plane liveness + analyze-agent execution per STATE.md lines 60-73) -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 - ``` +## Files checked -## Explicitly OUT of scope - -- `.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) - -## Why this is the work package +``` +packages/sdk/src/cli/hn-monitor.ts — EXISTS, 288 lines +packages/sdk/src/worker.ts — EXISTS, close() documented correctly +packages/sdk/tests/cli-hn-monitor.test.ts — EXISTS, 346 lines, all required tests present +ops/STATE.md — line 47 confirms PR #120 merged +ops/TARGET.md — describes hn-monitor work +ops/DIRECTIVES.md — empty (no standing directives) +``` -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" +## Final status -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. +**No work package written** because TARGET.md describes completed work. This assessment documents the state honestly rather than generating a work package for already-merged code.