j7/StarrOS
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(amb): place AMB Substrate spec — fold a2a-amb-kanban-prexx-20260630 into StarrOS #10

Merged
j7 merged 1 commit from docs/amb-substrate-placement into main 2026-07-10 17:55:16 -04:00
Conversation 0 Commits 1 Files changed 5 +129 -4
j7 commented 2026-07-10 15:35:58 -04:00
Owner
Copy link

What this PR does

Places the AMB Substrate spec into StarrOS as the canonical design contract for the Agent Mesh Bus, per J7 directive 2026-07-10 (prompts/AMB-Substrate.md). The spec itself was authored externally by Claude and committed by J7 in ef91298; this PR is the placement half that wires it into canon.

Placement diff

File Change
decisions/0003-canonical-spec-boundaries.md §Glossary AMB row now points at the substrate spec + §9/§10 instead of a stand-alone one-liner
docs/runtime-state.md new §2.1 "AMB live map" — auth posture, live ACL users, canonical stream inventory, Phase 1A → 1C gulf crosswalk (sourced from ishii@run-13 probe 2026-07-10)
specs/starros-stack-spec.md §3, §10, §11 AMB row widened to cite the substrate spec; source-of-truth map gains AMB broker ACL + AMB Substrate rows; rollout table gains P-AMB-P, P8-AMB-L1, L2, L3, L4 lanes
docs/architecture/open-questions.md new OQ-7 A2A wire-compliance parked; re-evaluation trigger (first compatible a2a-sdk release OR concrete inbound external-agent request)
kanban/backlog.md new Epic E6 AMB Substrate integration — 11 cards across E6-P, Lane 1, Lane 2, Lane 3, Lane 4

Fold-back

This is the fold of a2a-amb-kanban-prexx-20260630 into StarrOS for the comms-layer half. Per J7, we're improving and folding it in as needed, not duplicating. The B1/B2/B3 daemon code (in a2a-amb-kanban-prexx-20260630/scripts/lib/hermes_amb/) drops into ~/.hermes/hermes-agent/hermes_amb/ via E6-L2-1.

Lane A4 closure note

This placement subsumes the Lane A card E4-A4 ("AMB visibility in spec §3 + runtime-state §2 port map + Phase 1A/1C labels defined") — the prior light-coverage is now overlaid by the substrate spec + runtime-state §2.1. Closed as done-by-placement per the integration note in prompts/AMB-Substrate.md.

Gate 0 — J7 decision briefs

# Decision Recommendation Blocks
D-AMB-1 Ratify classify-first as canonical gateway default; prohibit auto-invoke yes L2-2
D-AMB-2 Adopt A2A task-state model + context_id now; defer wire-compliance yes L2-1
D-AMB-3 Enforce amb:pack.broadcast San-write-only at ACL, not by convention yes L1-1 design
D-AMB-4 Sequence write-side ACL + first consumer group ahead of loop-guard work yes (matches) sequencing

No architectural change in this PR depends on D-AMB-1..3 for sign-off. They block E6 Lane 2 cards (created in ~/.hermes/kanban/boards/starros-v1/kanban.db after this PR merges).

Contradictions found between spec and canon

  • wiki/concepts/amb-channel-registry.md says broker is on :6379. Canonical reality is :6380. Wiki correction tracked on E6-L1-2 close.
  • The same wiki lists amb:kanban:task:* channels as live. They are not produced yet; emit is E6-L3-1 work.

Sequencing

P1: E6-P1 (flake hygiene)
└── gate
Lane 1: E6-L1-1 (write-side ACL) → E6-L1-2 (first consumer group)
└── blocks Lane 2/3
Lane 2: L2-1 (envelope v1.1) → L2-2 (classify-first) → L2-3..5 (loop guards)
Lane 4: L4-1 (CircuitBreaker + nixosTest) ── parallel with Lane 2
└── blocks Lane 3
Lane 3: L3-1 (kanban→AMB fan-out) → L3-2 (San dispatch rule) ← FOUNDING-INCIDENT FIX

Lane 3 cannot be marked done until Lane 1 and L2-1 land. Flagged in backlog.

Next step (after merge)

File-system kanban cards via hermes kanban CLI on the starros-v1 board, one per Epic E6 row. Wolf-mode for everything touching /etc/nixos/, *.age, the spec, ADRs (per docs/external-workers.md §3). The L2-1 envelope bump is the most defensibly external-eligible if any is.

## What this PR does **Places the AMB Substrate spec into StarrOS** as the canonical design contract for the Agent Mesh Bus, per J7 directive 2026-07-10 (`prompts/AMB-Substrate.md`). The spec itself was authored externally by Claude and committed by J7 in `ef91298`; this PR is the **placement half** that wires it into canon. ## Placement diff | File | Change | |---|---| | `decisions/0003-canonical-spec-boundaries.md` §Glossary | AMB row now points at the substrate spec + §9/§10 instead of a stand-alone one-liner | | `docs/runtime-state.md` new §2.1 | "AMB live map" — auth posture, live ACL users, canonical stream inventory, Phase 1A → 1C gulf crosswalk (sourced from ishii@run-13 probe 2026-07-10) | | `specs/starros-stack-spec.md` §3, §10, §11 | AMB row widened to cite the substrate spec; source-of-truth map gains AMB broker ACL + AMB Substrate rows; rollout table gains P-AMB-P, P8-AMB-L1, L2, L3, L4 lanes | | `docs/architecture/open-questions.md` new OQ-7 | A2A wire-compliance parked; re-evaluation trigger (first compatible `a2a-sdk` release OR concrete inbound external-agent request) | | `kanban/backlog.md` new Epic E6 | AMB Substrate integration — 11 cards across E6-P, Lane 1, Lane 2, Lane 3, Lane 4 | ## Fold-back This is the **fold** of `a2a-amb-kanban-prexx-20260630` into StarrOS for the comms-layer half. Per J7, we're improving and folding it in **as needed**, not duplicating. The B1/B2/B3 daemon code (in `a2a-amb-kanban-prexx-20260630/scripts/lib/hermes_amb/`) drops into `~/.hermes/hermes-agent/hermes_amb/` via E6-L2-1. ## Lane A4 closure note This placement **subsumes** the Lane A card `E4-A4` ("AMB visibility in spec §3 + runtime-state §2 port map + Phase 1A/1C labels defined") — the prior light-coverage is now overlaid by the substrate spec + runtime-state §2.1. Closed as **done-by-placement** per the integration note in `prompts/AMB-Substrate.md`. ## Gate 0 — J7 decision briefs | # | Decision | Recommendation | Blocks | |---|---|---|---| | D-AMB-1 | Ratify classify-first as canonical gateway default; prohibit auto-invoke | yes | L2-2 | | D-AMB-2 | Adopt A2A task-state model + `context_id` now; defer wire-compliance | yes | L2-1 | | D-AMB-3 | Enforce `amb:pack.broadcast` San-write-only at ACL, not by convention | yes | L1-1 design | | D-AMB-4 | Sequence write-side ACL + first consumer group ahead of loop-guard work | yes (matches) | sequencing | No architectural change in this PR depends on D-AMB-1..3 for sign-off. They block E6 Lane 2 cards (created in `~/.hermes/kanban/boards/starros-v1/kanban.db` after this PR merges). ## Contradictions found between spec and canon - `wiki/concepts/amb-channel-registry.md` says broker is on `:6379`. Canonical reality is `:6380`. Wiki correction tracked on E6-L1-2 close. - The same wiki lists `amb:kanban:task:*` channels as live. They are **not produced yet**; emit is E6-L3-1 work. ## Sequencing ``` P1: E6-P1 (flake hygiene) └── gate Lane 1: E6-L1-1 (write-side ACL) → E6-L1-2 (first consumer group) └── blocks Lane 2/3 Lane 2: L2-1 (envelope v1.1) → L2-2 (classify-first) → L2-3..5 (loop guards) Lane 4: L4-1 (CircuitBreaker + nixosTest) ── parallel with Lane 2 └── blocks Lane 3 Lane 3: L3-1 (kanban→AMB fan-out) → L3-2 (San dispatch rule) ← FOUNDING-INCIDENT FIX ``` Lane 3 cannot be marked done until Lane 1 and L2-1 land. Flagged in backlog. ## Next step (after merge) File-system kanban cards via `hermes kanban` CLI on the `starros-v1` board, one per Epic E6 row. Wolf-mode for everything touching `/etc/nixos/`, `*.age`, the spec, ADRs (per `docs/external-workers.md` §3). The L2-1 envelope bump is the most defensibly external-eligible if any is. 
Per J7 directive 2026-07-10: the reconciled AMB Substrate spec
(specs/AMB-Substrate.md, externally authored by Claude + placed by J7
in commits ef91298 and 7d75b36) is now the canonical design contract
for the Agent Mesh Bus.

This commit closes the placement half:

- decisions/0003 glossary AMB row: points at the new spec + §9/§10
  rather than carrying the standalone one-liner that previously stood
  in for the broker.
- docs/runtime-state.md: new §2.1 'AMB live map' — auth posture (plain
  requirepass Phase 1A; aclfile declared but not emitted), live ACL
  users (default user; 11 per-wolf rows planned in 1C), canonical
  stream inventory, and the Phase 1A → 1C gulf crosswalk. Source:
  ishii@run-13 live probe 2026-07-10.
- specs/starros-stack-spec.md: AMB row in §3 widened to cite the
  substrate spec §2/§3/§4/§5/§6/§7/§9/§10, with the core invariant
  ('signals on the bus, state on the blackboard') named; §10
  source-of-truth map gains AMB broker ACL/module + AMB Substrate
  rows; §11 rollout adds P-AMB-P, P8-AMB-L1, L2, L3, L4 lanes.
- docs/architecture/open-questions.md: new OQ-7 'When does the
  wolfpack adopt A2A-protocol wire compliance?' — Q-status WAIT, with
  re-evaluation trigger (first compatible a2a-sdk release OR a
  concrete inbound external-agent request).
- kanban/backlog.md: new Epic E6 'AMB Substrate integration' with
  E6-P1 flake hygiene + E6 Lane 1 (L1-1 write-side ACL, L1-2 first
  consumer group) + E6 Lane 2 (L2-1..L2-5 loop-safety guards) +
  E6 Lane 3 (L3-1 kanban->AMB fan-out, L3-2 San dispatch rule)
  + E6 Lane 4 (L4-1 CircuitBreaker + Phase 1E nixosTest).

Lane A card A4 ('AMB visibility in spec §3 + runtime-state §2 port
map + Phase 1A/1C labels') is now subsumed by this PR. Closing it
as 'done-by-placement' rather than re-running.

Gate-0 decision briefs (D-AMB-1..4) for J7 to ratify:
  D-AMB-1 ratify classify-first as canonical gateway default
  D-AMB-2 adopt A2A task state model + context_id now; defer wire
  D-AMB-3 enforce amb:pack.broadcast San-write-only at ACL
  D-AMB-4 sequence write-side ACL + first consumer group ahead of
          loop-guard work
(no architectural change implied without sign-off; cards L2-1/2
hard-block on D-AMB-1/D-AMB-2).

Contradictions flagged (small, defer to follow-up):
- wiki/concepts/amb-channel-registry.md says broker is on port 6379;
  canonical reality is 6380 per AMB Substrate spec §2 + runtime-state
  §2. Wiki to be corrected on E6-L1-2 close.

Ref: prompts/AMB-Substrate.md.
j7 merged commit cfb9576d93 into main 2026-07-10 17:55:16 -04:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
j7/StarrOS!10
No description provided.