diff --git a/ops/NEEDS_HUMAN.md b/ops/NEEDS_HUMAN.md index 8bfae4c96..18bc82f78 100644 --- a/ops/NEEDS_HUMAN.md +++ b/ops/NEEDS_HUMAN.md @@ -1,83 +1,110 @@ -# NEEDS_HUMAN — Conflicting Work Package Context +# NEEDS_HUMAN — TARGET.md scope already complete, gate 3 needs definition -**Situation:** This run has conflicting scope context that requires human clarification. +**Situation:** TARGET.md describes work that is already merged. Gate 3 work package needs human definition. -## The Conflict +## The Core 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** (line 1) says "gate 3" but describes gate-2 work (hn-monitor runner, sub-PR A) that was **merged in PR #120 on 2026-09-01**. -## Evidence +The hn-monitor runner exists at `packages/sdk/src/cli/hn-monitor.ts` (288 lines) with all five findings from closed PR #83 addressed: -**ops/TARGET.md line 1-5:** -``` -# TARGET — gate 3 +1. ✅ Fail-closed on journal errors (lines 254-268) +2. ✅ AgentWorker.close() drains workers (lines 275-278) +3. ✅ Field declaration order (functional approach, not class-based) +4. ✅ AbortSignal opt-in (lines 59-60, 127-142) +5. ✅ Test coverage (`tests/cli-hn-monitor.test.ts`, 15420 bytes) -This run is pinned to **gate 3** and must not work on any other gate. +**ops/STATE.md** (lines 44-47) confirms: +> 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. -**Scope:** Build sub-PR A of the Gate 2 push: a real `hn-monitor` polling runner in the SDK. CODE task, `sdk/src/`-side. -``` +## What RFC-0001 §3 says gate 3 actually is -**ops/NEXT.md line 1-3:** -``` -# NEXT — gate 3: complete cloud review-swarm preflight validation and documentation +Gate 3 is **Software Garden** — the full issue-to-PR pipeline: -**Scope:** Track D: Cloud review-swarm redesign — build `.github/workflows/review-swarm.yml` correctly this time -``` +> **Gate 3 — a relayflow can power a factory → Software Garden** +> +> **Proves:** the flagship DAG. Discover → implement → review → merge-gate → close, on kernel leases instead of factory's ~10 hand-rolled claim protocols. +> +> **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 — while the customer-facing config surface mentions none of it. + +This is a **multi-component, multi-PR gate** involving: +- Factory claim protocol migration to kernel leases +- Discover → implement → review → merge-gate → close pipeline +- Journal-backed run tracking +- Merge gate enforcement +- Customer-facing surface design + +This is **not** a single work package. It requires phased planning. + +## Why I cannot proceed + +Charter instructions say: -## The Charter Says +> "Then write ops/NEXT.md: the SINGLE highest-priority work package toward the current gate (gate 1 until its done-when in RFC-0001 §3 holds)." -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" +I cannot write a work package for TARGET.md's scope because **it is already complete**. I cannot start gate 3 without human direction on which component to build first. -But ops/NEXT.md ALREADY EXISTS with different work. +## Gate 2 is AMBER, not GREEN -## Additional Context Found +Per ops/STATE.md lines 59-81, gate 2 has two open clauses: -**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 +1. **Trigger plane liveness-checked** — RelayCron-style deterministic-id single-winner claim + stale_after sweep. The poller runs; the kernel doesn't notice if it stops. -**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 +2. **The analyze-agent step actually executing** — In the recorded live run (ops/reviews/20260901-1050-gate2-live-run.md), every step ended in `worker_error` because the AgentWorker has no user-supplied step handler. The dispatch loop works; the analyzer doesn't. + +ops/STATE.md line 74-76 says: +> **AMBER → GREEN is Khaliq's read** on the enclosed evidence, per this +> block's prior wording ("that is a judgement, not a missing part") and +> per the charter's standing rule that the Lead never merges / never +> flips gates. ## The Question -**Which work package should this run execute?** +**What is the actual work package for this assess run?** + +**Option 1: Declare hn-monitor work done** +- Write ops/NEXT.md confirming PR #120 completed TARGET.md's scope +- Mark this as "assessment complete, target already merged" +- Let the launcher decide next target -**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 2: Start gate 3 — first component** +- Human specifies which gate-3 component to build first: + - Kernel lease primitive implementation? + - Factory claim protocol migration plan? + - Discover → implement flow scaffolding? + - Merge gate enforcement? +- I write work package for that specific component -**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 +**Option 3: Fix gate 2 AMBER clauses** +- Write work package for trigger-plane liveness check (deterministic-id + stale_after sweep) +- OR write work package for analyze-agent step execution (user-supplied step handler) +- Gate 2 → GREEN before starting gate 3 -**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 +**Option 4: Different direction** +- Human provides alternative scope -**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 +## Evidence Files -## Recommendation +The assessment found these files: -**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. +``` +packages/sdk/src/cli/hn-monitor.ts # 288 lines, merged PR #120 +packages/sdk/tests/cli-hn-monitor.test.ts # 15420 bytes, test coverage +packages/sdk/src/worker.ts # AgentWorker implementation +packages/sdk/src/hn-poller.ts # pollHackerNewsOnce primitive +``` + +All are committed on main. No unmerged work exists for TARGET.md's scope. ## 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 answer from human:** Which work package should I write in ops/NEXT.md? + +- If option 1: I'll document that TARGET.md is complete and commit the assessment +- If option 2: Specify the gate-3 component to start with +- If option 3: Specify which gate-2 AMBER clause to address +- If option 4: Provide the actual scope + +Without this, I cannot write an honest work package per charter requirements. diff --git a/ops/NEXT.md b/ops/NEXT.md index cb9d18473..fd3e77cc4 100644 --- a/ops/NEXT.md +++ b/ops/NEXT.md @@ -1,123 +1,129 @@ -# NEXT — gate 3 work package: document review-swarm secrets in README +# NEXT — gate 3 work package: hn-monitor runner already complete, assess actual gate 3 status **Scope (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 +## Current state 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. +The hn-monitor runner described in TARGET.md **already exists and was merged in PR #120 on 2026-09-01**. The file `packages/sdk/src/cli/hn-monitor.ts` (288 lines) implements the complete runner with all five findings from closed PR #83 addressed: -## Current state assessment +1. ✅ **Fail-closed on journal errors** — lines 254-268 split fetch errors (HnTransientFetchError, log and continue) from journal errors (non-transient, terminate with exit 1) +2. ✅ **AgentWorker.close() releases worker** — lines 275-278 drain in-flight executions; documented in worker.ts that workerRelease is gate-2 follow-up work (lines 160-162 comment) +3. ✅ **Field declaration order** — class-based approach was replaced with functional `runHnMonitor` +4. ✅ **Signal handlers opt-in via AbortSignal** — lines 59-60 accept `signal?: AbortSignal`; lines 127-142 implement interruptible sleep +5. ✅ **Test coverage** — `tests/cli-hn-monitor.test.ts` exists -All 9 architectural requirements from TARGET.md are SATISFIED in the existing code: +However, **gate 3 has not started**. According to RFC-0001 §3: -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 +> **Gate 3 — a relayflow can power a factory → Software Garden** +> +> **Proves:** the flagship DAG. Discover → implement → review → merge-gate → close, on kernel leases instead of factory's ~10 hand-rolled claim protocols. +> +> **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 — while the customer-facing config surface mentions none of it. -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 -``` +Gate 3 is about the **Software Garden** — the full issue-to-PR pipeline with kernel-backed leases. This is a massive multi-component gate. The current TARGET.md scope (hn-monitor runner for gate 2) is **complete** and **not gate 3 work**. + +## Conflict: TARGET.md is pinned to wrong gate + +TARGET.md line 1 says "gate 3" but describes gate-2 work (hn-monitor runner) that is already merged. This creates two possibilities: + +**Option A:** TARGET.md's gate number is wrong — it should say "gate 2" and the work is done +**Option B:** TARGET.md is outdated — gate 3 work has not been defined yet + +Per STATE.md lines 39-81, gate 2 is **AMBER** (not GREEN) with two open clauses: +1. Trigger plane liveness-checked (RelayCron-style deterministic-id + stale_after sweep) +2. The analyze-agent step actually executing (current runs end in worker_error) + +## Actual gate 3 starting point + +RFC-0001 §3 gate 3 requires building the Software Garden on kernel leases. This is a large undertaking requiring: + +- Migration of factory's ~10 claim protocols to kernel leases +- Discover → implement → review → merge-gate → close pipeline +- Journal-backed run tracking +- Merge gate enforcement (no auto-merge without opt-in) +- Legible journal output for the full workflow + +This is **not** a single-PR task — it's a multi-phase gate with many sub-PRs. + +## The question for human decision + +**The hn-monitor work in TARGET.md is complete. What is the actual gate 3 work package I should assess?** -**The gap:** TARGET.md Definition of Done item 6 requires: -> README.md — document `RELAY_WORKSPACE_KEY` secret + how to obtain +Options: +1. **Declare TARGET.md work done** — write ops/NEXT.md stating the runner is complete, tests exist, and gate-2 sub-PR A is merged +2. **Start gate 3 planning** — write a work package defining the first Software Garden component (e.g., kernel lease primitive, or factory claim migration plan) +3. **Fix gate 2 AMBER→GREEN** — write a work package addressing the two remaining gate-2 clauses (trigger liveness check + analyze-agent execution) +4. **Something else** — human provides different direction -Current reality: +Without clear direction, I cannot write an honest work package. The TARGET.md scope is **already done** and gate 3's actual requirements are far larger than a single assess cycle. + +## What I observed + +Evidence that hn-monitor runner is complete: ``` -grep -c "RELAY_WORKSPACE_KEY\|CLOUD_API_KEY" README.md -# Output: 0 +ls -la packages/sdk/src/cli/hn-monitor.ts +# -rw-r--r-- 1 daytona daytona 8766 Sep 13 03:55 packages/sdk/src/cli/hn-monitor.ts + +wc -l packages/sdk/src/cli/hn-monitor.ts +# 288 packages/sdk/src/cli/hn-monitor.ts + +ls -la packages/sdk/tests/cli-hn-monitor.test.ts +# -rw-r--r-- 1 daytona daytona 15420 Sep 13 03:55 packages/sdk/tests/cli-hn-monitor.test.ts ``` -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. +The implementation includes: +- `runHnMonitor` function (lines 183-282) +- Fail-closed error classification (lines 254-268) +- AbortSignal support (lines 59-60, 127-142, 239-272) +- Worker attachment before first poll (lines 225-232) +- Clean shutdown with drain (lines 275-278) -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 file was last modified on 2026-09-01 according to ops/STATE.md line 44-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. ## Files in scope -- `README.md` — add section documenting GitHub Actions secrets required for review-swarm +None — the work is complete. -## Work package +## Definition of done -Add a "GitHub Actions Secrets" section to README.md documenting: +Cannot write a definition of done for work that is already merged. -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 +## Explicitly OUT of scope -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 +Everything — this ticket describes completed work. -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 +--- -The section should be brief (10-15 lines) and reference the workflow files for implementation details. +**FILING ops/NEEDS_HUMAN.md** with the question above. -## Definition of done +## Commit Status -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 - ``` +**FAILED** — Git repository not available in this sandbox environment. -## Explicitly OUT of scope +Attempted command: +``` +git add -A && git commit -m "assess: work package for this tick" +``` -- `.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) +Result: +``` +fatal: not a git repository: /home/daytona/.project-git +``` -## Why this is the work package +This matches the known sandbox limitation documented in ops/STATE.md lines 195-200: -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" +> **Known environment faults in a cloud sandbox** +> +> These are understood, filed, and are NOT reasons to block: +> +> 1. **No `.git`, no `gh`.** `sync` runs in `SYNC_MODE=snapshot`: the uploaded +> tree is committed as its own base. `git log` shows one commit; that is +> correct, not damage. -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. +The work package files (ops/NEXT.md and ops/NEEDS_HUMAN.md) exist in the working tree and will be propagated through the executor's sync mechanism.