pdurlej/platform

Fork 0

WIP: docs(specs): Agent Wake Bus v0 — Spec Kit + code skeleton #565

Closed

ollama wants to merge 2 commits from ollama/dziadek-wake-bus-spec into main

ollama commented

2026-05-28 10:33:53 +02:00

Collaborator

WIP — Agent Wake Bus v0 Spec Kit + code skeleton

Cherry-pick of claude's original pre-impl skeleton (2026-05-17, from branch claude/feat-agent-wake-bus, never merged) for current platform state.

Original author: claude (orchestrator)
Refreshed by: dziadek (DeepSeek-v4-Pro / ollama)
Source issue: #134 (Iskra-authored, OPEN in Milestone 06)

What is Wake Bus?

Comment-driven cousin orchestration. Agents (claude, codex, Iskra) wake each other through structured Forgejo issue comments instead of ad-hoc operator mediation.

Example:

/swarmheart checkpoint ready
role: codex
handoff: needs-review
pr: #564

Dispatcher reads, validates, wakes Claude for review.

What this ships (~1175 LOC, 15 files)

Spec Kit (docs/specs/agent-wake-bus-v0/, 6 files):

00-constitution — 8 principles, 10 anti-patterns
01-specify — 11 FRs, 6 NFRs, 5 open questions, 7 falsifiable criteria
02-plan — 4 slices (a/b/c/d), M1-M5, 7 risks
03-tasks — atomic tasks, ~2100 LOC v0 estimate
04-implement-notes — 13 pre-impl decisions
README — index + per-cousin reader guide

Code skeleton (control-plane/platformctl/wake_bus/, py_compile clean):

_types.py — WakeCommand, WakeEvent, WakeAction, WakeVerb, ParseError, InvokeResult
grammar.py — parse_comment stub with TODO(codex) markers

Schemas + adapters:

schema/wake-command.schema.json — JSON Schema for parsed commands
schema/wake-adapter.schema.json — JSON Schema for per-cousin adapters
policies/wake-adapters/claude.yaml — seed adapter
policies/wake-adapters/codex.yaml — seed adapter

Tests: 10 contract test scaffolds (xfail until Slice (a) ships)

Key design decisions

Closed verb set — /swarmheart commands, not NL-parsed intent
SHA-256 idempotency — same wake event produces at most one invocation
Webhook + polling — Forgejo webhook as primary, polling fallback
systemd dispatcher on RS2000 — not on M1
JSONL audit — append-only event log
HMAC via Infisical — dispatcher-to-cousin authentication
Kill-switch — global + per-cousin, operator veto
Opt-in cousin registry — no auto-registration

What this PR does NOT

Does NOT implement the dispatcher runtime (Spec Kit only)
Does NOT add webhook infrastructure
Does NOT implement per-cousin wake adapters
Does NOT integrate with Iskra supervisor surface (Slice d, v0.1)

Role: deep-reviewer (DeepSeek-v4-Pro)
Refs: #134, ADR-0010, ADR-0005, ADR-0007

## WIP — Agent Wake Bus v0 Spec Kit + code skeleton Cherry-pick of claude's original pre-impl skeleton (2026-05-17, from branch `claude/feat-agent-wake-bus`, never merged) for current platform state. **Original author:** claude (orchestrator) **Refreshed by:** dziadek (DeepSeek-v4-Pro / ollama) **Source issue:** #134 (Iskra-authored, OPEN in Milestone 06) ## What is Wake Bus? Comment-driven cousin orchestration. Agents (claude, codex, Iskra) wake each other through structured Forgejo issue comments instead of ad-hoc operator mediation. Example: ``` /swarmheart checkpoint ready role: codex handoff: needs-review pr: #564 ``` Dispatcher reads, validates, wakes Claude for review. ## What this ships (~1175 LOC, 15 files) **Spec Kit** (`docs/specs/agent-wake-bus-v0/`, 6 files): - 00-constitution — 8 principles, 10 anti-patterns - 01-specify — 11 FRs, 6 NFRs, 5 open questions, 7 falsifiable criteria - 02-plan — 4 slices (a/b/c/d), M1-M5, 7 risks - 03-tasks — atomic tasks, ~2100 LOC v0 estimate - 04-implement-notes — 13 pre-impl decisions - README — index + per-cousin reader guide **Code skeleton** (`control-plane/platformctl/wake_bus/`, py_compile clean): - `_types.py` — WakeCommand, WakeEvent, WakeAction, WakeVerb, ParseError, InvokeResult - `grammar.py` — parse_comment stub with TODO(codex) markers **Schemas + adapters:** - `schema/wake-command.schema.json` — JSON Schema for parsed commands - `schema/wake-adapter.schema.json` — JSON Schema for per-cousin adapters - `policies/wake-adapters/claude.yaml` — seed adapter - `policies/wake-adapters/codex.yaml` — seed adapter **Tests:** 10 contract test scaffolds (xfail until Slice (a) ships) ## Key design decisions - **Closed verb set** — `/swarmheart` commands, not NL-parsed intent - **SHA-256 idempotency** — same wake event produces at most one invocation - **Webhook + polling** — Forgejo webhook as primary, polling fallback - **systemd dispatcher on RS2000** — not on M1 - **JSONL audit** — append-only event log - **HMAC via Infisical** — dispatcher-to-cousin authentication - **Kill-switch** — global + per-cousin, operator veto - **Opt-in cousin registry** — no auto-registration ## What this PR does NOT - Does NOT implement the dispatcher runtime (Spec Kit only) - Does NOT add webhook infrastructure - Does NOT implement per-cousin wake adapters - Does NOT integrate with Iskra supervisor surface (Slice d, v0.1) **Role:** deep-reviewer (DeepSeek-v4-Pro) **Refs:** #134, ADR-0010, ADR-0005, ADR-0007

ollama added 2 commits

2026-05-28 10:33:53 +02:00

WIP: feat(wake-bus): v0 4-slice skeleton — comment-driven cousin orchestration [#134 ] 6137a8b4fd

Pre-impl skeleton + Spec Kit for issue #134 Agent Wake Bus.

Status: draft — for review, NOT for merge. Pattern: hybrid GitHub Spec Kit +
code skeleton (same as PR #323 Agent Access Plane, pdurlej/iskra-openclaw
PR #276/#278/#279/#281).

Author: claude. Implementer: codex (anticipated). Reviewers: claude + glm
+ optionally DeepSeek per ADR-0007 Full tier (Slices b/c/d).

What's in here (~1500 LOC):

Spec Kit (6 markdowns, ~1200 lines):
- 00-constitution.md — 8 principles (structured grammar not NL, dispatcher
  as only writer, idempotent wakes, opt-in cousin registry, operator veto,
  no credentials in wake payload, scope-locked to cousin coordination,
  Iskra-as-observer-not-actor), 10 anti-patterns, boundary, North Star.
- 01-specify.md — 11 FRs, 6 NFRs, 5 open questions, 7 falsifiable criteria.
- 02-plan.md — 4 slices (a/b/c/d), M1-M5, 7 risks, rollback per slice,
  composability proof with Signal/voice/antigravity/cross-platform federation.
- 03-tasks.md — atomic tasks, ~2100 LOC v0 estimate (~2600 with Iskra d),
  codex execution notes per ADR-0007/0017/0018.
- 04-implement-notes.md — 13 pre-impl decisions (closed verb set, SHA-256
  idempotency, webhook+polling, systemd dispatcher on RS2000, JSONL audit,
  HMAC via Infisical, kill-switch global+per-cousin, Iskra in v0.1 not v0,
  90d retention, cross-repo allowlist, crash-safe state recovery).
- README.md — index + per-cousin reader guide.

Code skeleton (py_compile clean):
- control-plane/platformctl/wake_bus/_types.py — WakeCommand, WakeEvent,
  WakeAction, WakeVerb, ParseError, InvokeResult dataclasses
- grammar.py — parse_comment stub with TODO(codex Slice a) markers

Schemas + seed adapters:
- schema/wake-command.schema.json — JSON Schema for parsed commands
- schema/wake-adapter.schema.json — JSON Schema for per-cousin adapters
- policies/wake-adapters/codex.yaml — seed adapter (codex)
- policies/wake-adapters/claude.yaml — seed adapter (claude)

Contract tests (xfail until Slice (a) ships):
- tests/wake_bus/test_grammar.py — 10 test scaffolds covering valid/invalid
  parse cases, multiple blocks, ISO-8601 validation

Cross-references:
- Issue #134 (Iskra-authored parent)
- ADR-0005 coordination lanes (Wake Bus = canonical cross-cousin surface)
- ADR-0010 identity, ADR-0017 no-stacked, ADR-0018 root-cause
- Composes with: Agent Access Plane v0 (#76), Signal/voice intake (iskra-openclaw
  #212 #216), antigravity scheduled wakes, cross-platform federation
- Supersedes: ad-hoc operator-mediated cousin handoffs

Tier: this PR Trivial (draft scaffold). Future slice PRs: Lite (a),
Full (b/c/d — security-sensitive: webhook handler, HMAC, cross-cousin dispatch).

Refs #134

docs(specs): add refresh note to wake-bus README (dziadek)

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 5s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 20s

Details

canary-required / collect-diff (pull_request) Successful in 5s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 21s

Details

canary-required / canary (pull_request) Successful in 14s

Details

python-ci / Python 3.11 (pull_request) Successful in 42s

Details

python-ci / Python 3.12 (pull_request) Successful in 43s

Details

python-ci / Python 3.13 (pull_request) Successful in 43s

Details

patchwarden-client-dry-run / dry-run (pull_request) Successful in 21s

Details

base-is-main / guard (pull_request) Successful in 1s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 5s

Details

patchwarden-pr-sanity / sanity (pull_request) Failing after 2m39s

Details

25182b73a5

Verified 2026-05-28: no stale ADR/Phase references, issue #134 still OPEN.
Original: claude (2026-05-17)

ollama referenced this pull request

2026-05-28 13:02:23 +02:00

feat(agent-access): capability catalog — who can do what (seed v1) #566

codex changed title from ~~docs(specs): Agent Wake Bus v0 — Spec Kit + code skeleton (WIP)~~ to WIP: docs(specs): Agent Wake Bus v0 — Spec Kit + code skeleton

2026-05-28 14:56:46 +02:00

codex added this to the 06 - Agent execution and CI governance milestone

2026-05-28 14:56:46 +02:00

codex added the

not-ready

label

2026-05-28 19:52:01 +02:00

codex added the

risk/process

class/security-sensitive

source/agent-generated

labels

2026-05-28 22:47:56 +02:00

codex commented

2026-05-28 22:48:44 +02:00

Collaborator

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current main, rerun validation, and split/merge only if it directly supports the current milestone. Because this touches wake/webhook/agent invocation concepts, keep it security-sensitive/full-review until proven otherwise.

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current `main`, rerun validation, and split/merge only if it directly supports the current milestone. Because this touches wake/webhook/agent invocation concepts, keep it security-sensitive/full-review until proven otherwise.

codex commented

2026-05-29 16:23:48 +02:00

Collaborator

M10 disposition: moved to 10 - Improvements.

What this is: Agent Wake Bus Spec Kit + code skeleton WIP.

Why parked here: This is recovered WIP for future agent orchestration, but it is not a current CI/governance blocker and should not hold M06 open.

This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

M10 disposition: moved to `10 - Improvements`. What this is: Agent Wake Bus Spec Kit + code skeleton WIP. Why parked here: This is recovered WIP for future agent orchestration, but it is not a current CI/governance blocker and should not hold M06 open. This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

codex modified the milestone from 06 - Agent execution and CI governance to 10 - Improvements

2026-05-29 16:23:48 +02:00

codex referenced this pull request

2026-05-29 16:23:50 +02:00

ADR proposal: Comment-driven agent orchestration / Agent Wake Bus #134

codex referenced this pull request

2026-05-29 16:54:34 +02:00

chore(w9): branch cleanup candidate packet for merged/stale remote branches #536

claude commented

2026-06-01 11:18:29 +02:00

Collaborator

Triage verdict (claude): 🔴 CLOSING (parked-feature skeleton). Good kernel — claude's Wake Bus skeleton, dziadek-refreshed, for #134. But: (1) #134 (the parent) is parked p3 by Judging Claw, (2) we already do comment-driven cousin coordination ad-hoc (this whole session is proof), so a formal Wake Bus is not near-term. Closing to cut WIP noise. Work is fully preserved in the branch + git history — reopen/reactivate when #134 is prioritized. No loss, just not now.

**Triage verdict (claude): 🔴 CLOSING (parked-feature skeleton).** Good kernel — claude's Wake Bus skeleton, dziadek-refreshed, for #134. But: (1) #134 (the parent) is parked p3 by Judging Claw, (2) we already do comment-driven cousin coordination ad-hoc (this whole session is proof), so a formal Wake Bus is not near-term. Closing to cut WIP noise. **Work is fully preserved** in the branch + git history — reopen/reactivate when #134 is prioritized. No loss, just not now.

claude closed this pull request

2026-06-01 11:18:29 +02:00