docs(.claude/ATT): Protocol A/B + Cooperative Savant Council + skeleton-fill

AdaWorldAPI · AdaWorldAPI · commit 5e2f95a12260 · 2026-05-18T23:03:09.000+02:00
Folds in the strategic orchestration loop:
- Two-Protocol Operating Modes (§14 of autoattended-orchestrator-spec.md)
  Protocol B = design loop on N docs jointly; Protocol A = implementation
  loop with skeleton-first preflight.
- Commented-out Rust skeleton as PP-16's Protocol-A deliverable (§14.4)
  Canonical token: todo!("SOURCE: &lt;path&gt;:&lt;lines&gt;") per language.
  Validation: WAVE-018 skeleton-compiles / WAVE-019 source-annotated /
  WAVE-020 no-runtime / WAVE-021 protocol-declared / WAVE-022 coherence.
- Cooperative Savant Council (§15) — NOT independent-parallel + super-
  verdict aggregation, but a shared scratchpad where savants iterate,
  cross-refer, and withdraw duplicates over R rounds (default max 3).
  Super-verdict CONVERGE / SPLIT / BLOCK at chairman synthesis.
  Validation: WAVE-023..WAVE-029.
- Savant Mindsets (§4.0) — savants are mindsets, not verdict-producers.
  PP-13 = implementation principal; PP-14 = creative-design / R&amp;D;
  PP-15 = DTO/interface architect; PP-16 = principal system architect.
- Skeleton-Fill Contract (§13 of anti-skim-agent-spec.md) — what workers
  do when PP-16 hands them a skeleton: source-range read, SHA-pin verify,
  signature preserved, no new todo!(), SAFETY comments preserved.
- Universal wire format (§1.3 of agent-coordination-mcp-spec.md) —
  tee -a [bug/proposal] markdown blob IS the MCP A2A wire format AND
  the log format. Three uses, one write.
- Tables-over-prose discipline (§1.4 of agent-coordination-mcp-spec.md).
- Cooperative-Savant Scratchpad Bus (§13 of agent-coordination-mcp-spec.md)
  with directory convention .claude/board/savant-council-&lt;topic&gt;/ and
  per-savant per-round file schema. Native MCP endpoint sketch:
  post_council_finding / read_council_round / subscribe_council_round.

Additive only.
diff --git a/.claude/ATT/agent-coordination-mcp-spec.md b/.claude/ATT/agent-coordination-mcp-spec.md
@@ -36,6 +36,62 @@ Both modes implement the same three-layer model (§3) with the same
 schemas (§6). The native server is a thin serde layer over the
 workaround's wire format.
 
+### §1.3 The universal wire format: `tee -a [bug/proposal]`
+
+The same markdown blob serves **three purposes simultaneously**:
+
+| Purpose | Reader | Mutability |
+|---|---|---|
+| **MCP orchestration message** | the orchestrator (and any subscribed session via `subscribe_pr_activity`) | append-only |
+| **A2A wire format** | sibling agents (worker → worker, worker → meta, savant → savant) | append-only |
+| **Log format (audit + replay)** | any future session reading git history | immutable once committed |
+
+One write, three uses. This is by design: it means the same code
+that posts an entry to the file-blackboard (Layer 1) ALSO emits the
+log line ALSO becomes a cross-session-readable orchestration message
+the moment it lands on a coordination PR's branch.
+
+The blob's shape is **always a typed envelope + a body**:
+
+```
+## YYYY-MM-DDTHH:MM — KIND[severity]: one-line headline (author, branch)
+
+**Author:** <agent-id | session-id>
+**Kind:** BUG | PROPOSAL | HANDOVER | FINDING | DECISION | RFC | STATUS
+**Severity:** P0 | P1 | INFO       (optional; defaults to INFO)
+**Refs:** <commit-sha> | <PR-#> | <handover-id>
+**Proof-of-read:**
+- file=<path> sha256=<...> lines=<N> depth=<D>
+- file=<path> sha256=<...> lines=<N> depth=<D>
+
+---
+
+<body — free-form markdown, but `## ` sub-headings preferred over prose>
+```
+
+The `tee -a` envelope is the wire; the body is the payload. Routers
+(orchestrator, meta-agent, MCP server) dispatch by `Kind` and
+`Severity`; readers grep by `Author` + `Refs`; auditors replay by
+the immutable git-log order.
+
+### §1.4 Tables over prose (NLSpec discipline)
+
+Implementations SHOULD prefer tabular content over prose for every
+catalog (anti-patterns, validation rules, verdict vocabularies,
+configuration defaults, parity matrices). Rationale:
+
+| Property | Table | Prose |
+|---|---|---|
+| Machine-parseable | yes | no |
+| Forces consistency (all rows have the same columns) | yes | no |
+| Compressible (each row is a fact) | yes | no |
+| Diffs cleanly in PRs | yes | partial |
+| Resists hedging language | yes (cell width caps qualifiers) | no |
+| Suitable for English narrative | no | yes |
+
+Use prose for: section overviews, rationale paragraphs, conflict
+explanations. Use tables for: everything else.
+
 ### §1.3 What this spec is NOT
 
 - Not a workflow engine. Wave / sprint structure is in
@@ -542,4 +598,146 @@ If the task is...
 
 ---
 
+## §13 Cooperative-Savant Scratchpad Bus
+
+> Added 2026-05-18. The transport layer for the Cooperative Savant
+> Council defined in `autoattended-orchestrator-spec.md` §15.
+
+### §13.1 What the scratchpad bus is
+
+A purpose-shaped extension of the Layer-1 File Blackboard (§3.2)
+used specifically for the savant council's iterative cooperation.
+Same wire format (`tee -a` markdown), same append-only governance
+(§7), one new directory convention:
+
+```
+.claude/board/savant-council-<topic>/
+├── ROUND-0-ARTIFACT.md                  snapshot of artifact under review
+├── ROUND-<N>-<savant>.md                one file per (round, savant)
+└── COUNCIL-VERDICT.md                   chairman's synthesis after CONVERGE
+```
+
+Topic naming: `savant-council-<sprint-id>` (e.g.
+`savant-council-SPRINT-17-attractor-fold-in/`).
+
+### §13.2 Per-savant file schema
+
+```markdown
+# ROUND-{N} {savant_id} — {topic}
+
+**Round:** N
+**Savant:** PP-13 | PP-14 | PP-15 | PP-16
+**Read at round start:** [list of peer files read this round]
+**Status:** IN-PROGRESS | ROUND-COMPLETE
+
+## New findings (this round)
+
+### F{round}-{savant}-{N}: {one-line headline}
+**Axis:** AP1..AP9 | BAP1..BAP10 | PD1..PD10 | EP1..EP8
+**Severity:** P0 | P1
+**File:** <path>:<line>
+**Detail:** <one paragraph>
+**Remediation:** <one paragraph>
+
+## Cross-references to peers' findings
+
+- F{R}-PP-X-N: NOTED — my angle: <one-line>
+- F{R}-PP-Y-N: SUPERSEDED-BY my F{R+1}-{self}-M
+
+## Withdrawals (my prior findings I am retracting)
+
+- F{R-1}-{self}-N: WITHDRAWN — covered by PP-X round R from a stronger angle
+```
+
+### §13.3 Reading-and-writing protocol
+
+Each savant in each round:
+
+1. **Read** ALL `ROUND-(R-1)-*.md` files (peer findings from previous
+   round) plus its own `ROUND-(R-1)-<self>.md` if any.
+2. **Decide** cross-refs, withdrawals, new findings.
+3. **Write** `ROUND-R-<self>.md` in one `tee -a` call (no
+   partial writes — savants share a directory and partial
+   writes confuse peers' next round).
+4. **Emit** `Status: ROUND-COMPLETE` if no new findings AND no
+   un-addressed cross-refers from peers.
+
+### §13.4 Chairman synthesis
+
+After CONVERGE (all four savants `ROUND-COMPLETE` in the same
+round) the chairman savant (declared in sprint config; default
+PP-16 for Protocol A, PP-15 for Protocol B) reads ALL ROUND-*.md
+files in lexical order and writes a single `COUNCIL-VERDICT.md`
+matching the schema in `autoattended-orchestrator-spec.md` §15.5.
+
+The chairman:
+- MUST cite every kept finding with its raised-by + cross-referrals.
+- MUST consolidate duplicates that survived the cooperation rounds
+  (rare — most should withdraw themselves, but races can leave a
+  pair that needs one merged into the other).
+- MUST NOT add findings of its own that did not appear in any
+  `ROUND-*.md` (the chairman is a synthesizer, not a fifth voice).
+- MUST set `super_verdict` per §15.5 rules.
+
+### §13.5 Concurrency contract
+
+Savants may run on separate sessions; the scratchpad bus is the
+synchronization point.
+
+- **Round boundary** is implicit: a savant starts round R only after
+  it has read all four `ROUND-(R-1)-*.md` files (including its own).
+- **Last-writer-wins** is acceptable for the per-savant per-round
+  file since each (savant, round) pair has exactly one writer by
+  construction. If a savant writes twice in the same round (e.g. a
+  retry after a tool-call loop), the second write replaces the first.
+- **Round skipping** is forbidden: a savant MUST NOT write
+  `ROUND-(R+2)` until `ROUND-(R+1)` exists for it.
+
+### §13.6 Decision matrix update
+
+Extends §4 with one new row:
+
+| Need | Workaround | Native MCP equivalent | Cost |
+|---|---|---|---|
+| Cooperative multi-agent review with iterative cross-refer + withdraw | Layer-1 File Blackboard scoped to `savant-council-<topic>/` directory (§13) | `post_council_finding` + `read_council_round` + `subscribe_council_round` | Medium: `tee -a` per round + git commit per round |
+
+### §13.7 Native MCP endpoints (sketch)
+
+```yaml
+endpoint: post_council_finding
+params:
+  topic: string                          # e.g. "SPRINT-17-attractor-fold-in"
+  round: integer
+  savant: enum (PP-13 | PP-14 | PP-15 | PP-16)
+  payload: FindingsFile                  # matches §13.2 schema
+returns:
+  file_id: string
+
+endpoint: read_council_round
+params:
+  topic: string
+  round: integer
+returns:
+  findings_by_savant: map[savant -> FindingsFile]
+  complete_savants: list[savant]         # those that emitted ROUND-COMPLETE
+
+endpoint: subscribe_council_round
+params:
+  topic: string
+streams:
+  event_kinds: [ findings_appended, savant_round_complete, council_converged, council_stalled, council_blocked ]
+```
+
+### §13.8 Validation rules
+
+| Rule | Description | Severity |
+|---|---|---|
+| `COORD-001 directory-naming` | Council scratchpad MUST live at `.claude/board/savant-council-<topic>/`. | ERROR |
+| `COORD-002 file-naming` | Per-savant files MUST be named `ROUND-<N>-PP-<NN>.md`. | ERROR |
+| `COORD-003 append-only` | The scratchpad directory inherits the append-only governance of §7. | ERROR |
+| `COORD-004 chairman-no-new-findings` | The chairman's `COUNCIL-VERDICT.md` MUST NOT introduce findings absent from any `ROUND-*.md`. | ERROR |
+| `COORD-005 round-monotonic` | Each savant MUST write `ROUND-(R+1)` only after `ROUND-R-<self>.md` exists. | ERROR |
+
+---
+
 *End of `agent-coordination-mcp-spec.md`.*
diff --git a/.claude/ATT/anti-skim-agent-spec.md b/.claude/ATT/anti-skim-agent-spec.md
@@ -440,4 +440,82 @@ work.
 
 ---
 
+## §13 Skeleton-Fill Contract (Protocol A)
+
+> Added 2026-05-18. Applies to workers operating in
+> `autoattended-orchestrator-spec.md` Protocol A (implementation),
+> where PP-16's preflight has produced a commented-out Rust
+> skeleton (per §14.4 of the orchestrator spec).
+
+### §13.1 What the worker receives
+
+Three inputs:
+
+1. The skeleton file(s) at `skeleton_output_path` containing
+   `todo!("SOURCE: <path>:<lines>")` macros at every body site.
+2. The original spec / reference-source files referenced in each
+   `SOURCE:` annotation.
+3. A SHA-256 of both the skeleton AND each referenced source file,
+   pinned by PP-16 at preflight time.
+
+### §13.2 Worker's obligations
+
+For every `todo!("SOURCE: <path>:<lines>")` the worker fills:
+
+1. **Read the source range** at the declared depth (§3.3); default
+   for ports is `full`.
+2. **Record proof-of-read** for the source file at the declared
+   line range (§7.1).
+3. **Replace `todo!(...)` with the body**, preserving the surrounding
+   signature exactly. The signature came from PP-16; the worker
+   does not change it without an Iron-Rule-amending RFC.
+4. **Quote the source line range in the commit message body** (per
+   `autoattended-orchestrator-spec.md` §5.6).
+5. **Confirm the skeleton's SHA-256 against the pinned value** at
+   start of work. If the skeleton has drifted (e.g. a sibling worker
+   touched it), the worker MUST STOP and file an `EXTERNAL_DEPENDENCY`
+   blocker in `META/REQUESTS-FROM-AGENTS.md`.
+
+### §13.3 Forbidden in skeleton-fill mode
+
+- Changing a signature provided by the skeleton (RFC required).
+- Adding a `todo!()` that did NOT come from the skeleton (would
+  bypass PP-16's source-annotation discipline).
+- Removing a `// SAFETY:` comment from an `unsafe` block (PP-13
+  will reject; PP-16 wrote it for a reason).
+- Filling bodies in a file outside `skeleton_output_path` (§5.1
+  unique-file write discipline).
+
+### §13.4 Reading depth required
+
+| Source kind | Minimum depth |
+|---|---|
+| `SOURCE: <reference-source>:<lines>` (the function being ported) | `full` for the named line range |
+| `UNSAFE-SOURCE: <reference-source>:<lines>` | `thorough` for the named range AND the function's callers |
+| The skeleton file itself | `read` (to confirm the surrounding signature you're filling into) |
+| `META/INVARIANTS.md` | `thorough` (per §3.3) |
+
+### §13.5 Validation rules
+
+| Rule | Description | Severity |
+|---|---|---|
+| `FILL-001 source-range-read` | Every `todo!("SOURCE: P:L-M")` the worker fills MUST appear in the worker's proof-of-read with `file=P, lines covering L-M, depth=full`. | ERROR |
+| `FILL-002 skeleton-sha-pin` | Worker MUST verify the skeleton's SHA-256 against the value PP-16 pinned, at start of work. Drift → STOP + `EXTERNAL_DEPENDENCY`. | ERROR |
+| `FILL-003 signature-preserved` | Worker MUST NOT change a signature provided by the skeleton without a merged RFC. Diff inspection by PP-15 enforces. | ERROR |
+| `FILL-004 unsafe-safety-preserved` | `// SAFETY:` comments on `unsafe` blocks from the skeleton MUST survive into the filled body. PP-13 enforces. | ERROR |
+| `FILL-005 no-new-todo` | Worker MUST NOT introduce new `todo!()` calls; every `todo!()` in the filled file MUST trace back to a skeleton entry. | ERROR |
+
+### §13.6 Definition of Done (skeleton-fill)
+
+- [ ] Every `todo!()` in the assigned skeleton file(s) is replaced.
+- [ ] No new `todo!()` introduced (FILL-005).
+- [ ] Skeleton SHA matched at start; final SHA different (FILL-002).
+- [ ] Proof-of-read covers every `SOURCE:` annotation (FILL-001).
+- [ ] All signatures preserved (FILL-003).
+- [ ] All `// SAFETY:` comments preserved (FILL-004).
+- [ ] Tier-1 toolchain green on filled file (§8.1).
+- [ ] Status file written per `autoattended-orchestrator-spec.md` §9.1.
+
+---
+
 *End of `anti-skim-agent-spec.md`.*
diff --git a/.claude/ATT/autoattended-orchestrator-spec.md b/.claude/ATT/autoattended-orchestrator-spec.md
