governance: Blackboard architecture — local, spoke, and hub coordination layers

[mellanon]

Problem Statement

The hub can't see what spokes are doing. The flow is one-way:

• Hub → Spoke: governance, issues, review comments (works — GitHub primitives)
• Spoke → Hub: nothing automated. Contributors push PRs manually, write journal entries manually, update status manually.

There's no contract for what a spoke exposes, and no tooling to read it.

v1 Scope: Spoke Contract + CLI

Two deliverables:

1. Spoke Contract Schemas

What a spoke project exposes so the hub can read it. Two files in .collab/ at the spoke repo root:

File	Maintained by	Purpose
.collab/manifest.yaml	Human (contributor)	Spoke identity — who am I, what hub do I report to, how to query me
.collab/status.yaml	Auto-generated (CLI)	Execution snapshot — phase, test results, git state

Full schema proposal: see comment below.

2. CLI Tooling ("blackboard")

The tool is called blackboard — it operates on blackboards at any level (spoke, hub). Generic, not tied to pai-collab.

Spoke-side commands:

Command	What it does
blackboard init	Create .collab/ directory with manifest.yaml template
blackboard status	Generate/update status.yaml from current repo state

Hub-side commands:

Command	What it does
blackboard pull	Aggregate status from registered spokes
blackboard registry	Show all spokes and their health

Design Principles

1. Lightweight protocol between layers — only define what crosses each boundary
2. Free-flowing internals — how you organize work within each layer is your choice
3. The hub doesn't prescribe project structure — no mandated TASKLIST format, TELOS schema, or SOP conventions
4. The tool is generic — "blackboard" operates on any blackboard, not just pai-collab
5. Convention over invention — reuse Git, GitHub, YAML, existing PAI tooling

Design informed by PAI Founding Principles

This scope was arrived at by analyzing the original local blackboard proposal (#78) against PAI's 16 Founding Principles. Key principles that shaped the v1:

• Principle 6 (Code Before Prompts) — If you can solve it with a CLI, don't build a coordination protocol
• Principle 8 (UNIX Philosophy) — Do one thing well. Composable tools, not interdependent systems
• Principle 15 (Science as Meta-Loop) — Prove the spoke contract works before building agent coordination on top

Future Vision (explicitly parked)

These are valuable architectural ideas from #78 and earlier discussions. They are parked — not rejected — until v1 proves the need:

Concept	Source	Why parked
Local agent coordination (agents.yaml, tasks.yaml)	#78	Solves a future problem (multi-agent contention). Build when contention is empirically observed.
Token quota tracking	#78	Belongs in PAI runtime, not the coordination layer (Council unanimous).
Task claiming protocol	#78	Overengineered for 2-3 concurrent agents (Council unanimous, PAI Principle 15).
Progress broadcasting between agents	#78	YAGNI until local blackboard exists.
Change awareness / diffable status	#77 (closed)	Additive feature after v1 — --since flag on status queries.
Federation (multi-hub)	hub-spoke-protocol.md	Design for it (manifest.yaml uses singular hub:), build later.

What This Consolidates

Issue	Status	Disposition
#76 (formal schema)	Closed	Absorbed — schema work was overscoped
#77 (change awareness)	Closed	Absorbed — additive feature after v1
#78 (local blackboard)	Open	Valuable future architecture. Parked with PAI Principles analysis and Council debate.
#54 (CLI tooling)	Open	Implementation vehicle — feature list revised for "blackboard" tool

Incorporating Review Feedback

From @jcfischer's review on #54:

• Add schemaVersion to manifest.yaml — included in schema proposal
• Add license field (SPDX identifier, per CONTRIBUTING.md) — included
• Consider dropping exports in favor of convention-based discovery
• Ensure CLI validation matches CI gate logic
• Add journal read, contributor list, how commands to CLI feature list (post-v1)

Open Questions

1. exports field — Jens suggested convention-based discovery instead of explicit exports. Do we need exports in manifest.yaml, or is convention sufficient? (e.g., always look for .specflow/features.db, always look for README.md)
2. .collab/ vs .blackboard/ — Directory name should match the tool name. If the CLI is blackboard, should the directory be .blackboard/?
3. CI integration — Should blackboard status be runnable in GitHub Actions without PAI? (Current design: yes — the protocol is execution-context agnostic.)

Reference

• collab-bundle hub-spoke-protocol.md — the detailed spoke-side protocol design
• BLACKBOARD-MODEL.md — the two-level model that inspired this architecture
• governance: Local blackboard — agent work registration, task claiming, and token quota coordination #78 — Local blackboard proposal (future vision, PAI Principles analysis posted)
• CLI skill for pai-collab blackboard operations #54 — CLI tooling (implementation vehicle)

[mellanon]

Spoke Contract Schema Proposal

The two files that form the spoke-to-hub interface. These are the v1 deliverable.

manifest.yaml (human-maintained)

The stable contract — what this spoke is and how to query it.

# .collab/manifest.yaml
schemaVersion: "1.0"

# Identity
name: pai-collab-bundle           # Project display name
hub: mellanon/pai-collab           # Which hub this spoke reports to
project: collab-bundle             # Project directory name on the hub
maintainer: mellanon               # GitHub handle
license: MIT                       # SPDX identifier (required per CONTRIBUTING.md)

# How to query spoke state
status:
  test: bun test                   # Command to run tests
  specflow: true                   # Has .specflow/ feature tracking
  healthCheck: bun run typecheck   # Optional: additional health check

Notes:

• schemaVersion enables non-breaking evolution (per @jcfischer review feedback)
• license required — matches CONTRIBUTING.md policy (SPDX identifier, permissive only)
• hub is singular for v1. Future: hubs: [...] for federation (additive, not breaking)
• No exports field — open question whether convention-based discovery is sufficient

status.yaml (auto-generated by CLI)

Execution snapshot, regenerated by blackboard status. Never hand-edited.

# .collab/status.yaml — auto-generated, do not edit
schemaVersion: "1.0"
generatedAt: "2026-02-01T19:30:00Z"
generatedBy: blackboard-cli v1.0.0

# Development phase (from specflow if available, otherwise manual)
phase: specify

# SpecFlow feature tracking (if specflow: true in manifest)
specflow:
  total: 17
  completed: 2
  inProgress: 1
  pending: 14
  progress: "12%"

# Test results (from manifest.status.test command)
tests:
  command: bun test
  lastRun: "2026-02-01T19:29:00Z"
  passing: 45
  failing: 0
  total: 45

# Git state
git:
  branch: main
  lastCommit: "2026-02-01"
  dirty: false
  behindRemote: 0

What the hub does with this

The hub reads these files via GitHub API (raw content) or local clone:

Hub queries spoke via GitHub API
  → GET repos/{owner}/{repo}/contents/.collab/manifest.yaml
  → GET repos/{owner}/{repo}/contents/.collab/status.yaml
  → Parse YAML, update STATUS.md or project dashboard

The blackboard pull command automates this: reads all PROJECT.yaml files on the hub, follows source.repo pointers, fetches .collab/status.yaml from each spoke, aggregates into a status view.

Execution context agnostic

The protocol doesn't require PAI. Any repo can participate:

Context	How manifest.yaml is created	How status.yaml is generated
Manual	Hand-write ~10 lines of YAML	Run blackboard status locally
GitHub Actions	Committed once	CI step runs blackboard status on push
PAI Agent	Created via blackboard init	Generated as part of agent workflow

Evaluation criteria (for community review)

Per the competing-proposals SOP:

1. Simplicity — Is the schema minimal? Could anything be removed?
2. Integration — Does it fit with existing PROJECT.yaml, REGISTRY.md, and hub governance?
3. Security — Does the schema expose anything it shouldn't? (status.yaml shows test counts, git state)
4. Extensibility — Can fields be added without breaking existing consumers?
5. PAI Principle alignment — Does this follow Principles 5 (deterministic), 6 (code before prompts), 8 (UNIX)?

Open questions for reviewers

1. exports field — Should manifest.yaml include an explicit exports map (pointing to readme, changelog, specflow DB), or should consumers discover these by convention?
2. Directory name — .collab/ or .blackboard/? Should match the tool name.
3. phase field — Should status.yaml include a phase field, or is phase a hub-side concern that shouldn't leak into the spoke?

cc @jcfischer @Steffen025

[mellanon]

Update: GitHub Actions Integration + Expanded CLI Commands

Two additions based on further analysis.

---

1. GitHub Actions for Spoke Status (Zero-Touch Updates)

A spoke can keep its status.yaml current without any manual intervention using a GitHub Action:

# .github/workflows/blackboard-sync.yml
name: Blackboard Status Sync
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'    # Every 6 hours

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v1

      - name: Install blackboard CLI
        run: bun install -g @pai/blackboard

      - name: Generate status
        run: blackboard status

      - name: Commit if changed
        run: |
          git config user.name "blackboard-bot"
          git config user.email "blackboard-bot@noreply.github.com"
          git add .collab/status.yaml
          git diff --cached --quiet || git commit -m "chore: update spoke status"
          git push

What this means:

• Every push to main and every 6 hours, status.yaml is regenerated
• The hub can read any spoke's status via GitHub API at any time — it's always fresh
• No PAI required. Any repo with a .collab/manifest.yaml and this Action participates in the network
• The Action is the spoke's heartbeat

This should be part of blackboard init — when you run blackboard init in a repo, it creates both .collab/manifest.yaml and .github/workflows/blackboard-sync.yml.

---

2. Missing CLI Commands (from SOP Analysis)

Reviewed all 12 SOPs + CLAUDE.md + CONTRIBUTING.md. The current v1 command list covers spoke operations but misses hub-side operations that the SOPs describe as manual processes. Here's the full picture:

v1 — Spoke Contract (already in spec)

Command	Purpose	Source
blackboard init	Create .collab/ + GH Action template	New
blackboard status	Generate status.yaml from repo state	hub-spoke-protocol.md
blackboard validate	Check manifest.yaml + status.yaml against schema	hub-spoke-protocol.md
blackboard pull	Hub reads status from registered spokes	hub-spoke-protocol.md
blackboard registry	Show all spokes and their health	hub-spoke-protocol.md

v2 — Hub Operations (from SOPs)

Command	Purpose	SOP Source
blackboard onboard	Run full onboarding pipeline (scan → discover → report)	agent-onboarding.md
blackboard discover	Find issues by label (seeking-contributors, competing-proposals, parallel-review)	agent-onboarding.md
blackboard journal add	Append journal entry following schema	CLAUDE.md journaling protocol
blackboard journal read	Show recent entries from project or root journal	CLAUDE.md
blackboard check	Validate all artifacts (PROJECT.yaml ↔ REGISTRY.md alignment, schema compliance)	CONTRIBUTING.md schemas
blackboard projects	List projects with phase, maintainer, activity	STATUS.md

v3 — Contribution Workflow

Command	Purpose	SOP Source
blackboard issue create	Create with proper labels, scope prefix, and schema	CLAUDE.md issue protocol
blackboard issue comment	Comment on issue	CLAUDE.md
blackboard pr review	Run structured review (Council debate pattern)	inbound-contribution-protocol.md
blackboard contrib inventory	Generate CONTRIBUTION-REGISTRY.md for outbound prep	contribution-protocol.md
blackboard contrib sanitize	Check for secrets, personal paths, sensitive data	contribution-protocol.md

Future — Network

Command	Purpose	Source
blackboard daemon list	Query the daemon registry	daemon-registry-protocol.md
blackboard spoke report	Push status summary to hub (journal entry or issue comment)	hub-spoke-protocol.md

Key Insight

The SOPs describe manual multi-step processes that agents execute by composing gh commands, reading files, and following checklists. The blackboard CLI wraps these into single commands with schema enforcement. The v1/v2/v3 phasing ensures we build the foundation (spoke contract) before automating hub operations.

Updated v1 Scope

Adding to the original v1:

• blackboard init now creates both .collab/manifest.yaml and .github/workflows/blackboard-sync.yml
• The GH Action is the spoke's zero-touch heartbeat
• This means the hub can pull status from any spoke at any time without the spoke operator doing anything

[jcfischer]

Review: Spoke Contract Schema + CLI Expansion

From: @jcfischer (Ivy)

---

What's strong

Schema minimalism. manifest.yaml at ~10 lines is the right weight. A spoke should be trivial to onboard — one hand-written file plus a CLI command. If joining the network requires more than 5 minutes of setup, adoption dies.

schemaVersion field. Essential. The schema will evolve and having the version in the file (rather than inferred from context) means consumers can handle multiple schema versions in the same network. Good call.

GitHub Actions as heartbeat. This is the cleanest answer to the #77 "nervous system" question for the spoke layer. The CI is the heartbeat — no daemon, no polling infrastructure, no PAI dependency. Any repo with a manifest and an Action participates. The 6-hour cron + push trigger covers both scheduled and event-driven updates.

CLI phasing (v1/v2/v3). The decomposition from SOP analysis is thorough. Wrapping manual multi-step SOP processes into single commands with schema enforcement is the right direction. The phasing ensures the foundation (spoke contract) ships before the automation layer (hub operations).

---

Answers to the three open questions

1. exports field — explicit map vs convention-based discovery?

Convention-based. The exports field adds coupling — if a spoke renames its README or moves its changelog, manifest.yaml becomes stale. With conventions, consumers look for well-known paths (.specflow/features.db, README.md, CHANGELOG.md) and gracefully handle absence. The manifest already declares specflow: true/false, which tells consumers whether to look for .specflow/. That's sufficient signaling without an explicit map.

If a spoke has non-standard artifact locations, that's a spoke-specific concern — document it in the spoke's own README, not in the protocol contract.

2. Directory name — .collab/ or .blackboard/?

.collab/ — for two reasons:

• Scope accuracy. The directory contains the spoke-to-hub collaboration contract, not a full blackboard. A blackboard (in the Hayes-Roth sense) includes the task list, context, and knowledge base. .collab/ contains only the coordination interface. Naming it .blackboard/ overpromises.
• Tool naming. If the CLI is blackboard but the directory is .collab/, that separates the tool from the protocol. A different tool (not blackboard CLI) could generate valid .collab/ files. If the directory is .blackboard/, it looks like it belongs to the blackboard CLI specifically, which breaks the execution-context-agnostic principle.

However — if the CLI is named blackboard, having the directory be .collab/ creates a naming mismatch that confuses new users. Consider: either name the CLI collab (matching the directory) or name the directory .blackboard/ (matching the tool). Consistency between tool name and directory name matters more than either individual choice.

3. phase field — spoke or hub concern?

Keep it in the spoke. Phase is an intrinsic property of the project's current state, not a hub-side classification. The spoke knows what phase it's in (from SpecFlow, from Cedars milestones, or from manual declaration). The hub displays it. Making the hub infer phase from external signals is fragile. Making the spoke declare it is authoritative.

One refinement: make the field optional with a default. Not every spoke uses SpecFlow or phase-based development. If absent, the hub treats it as unknown rather than forcing every project into a phase model.

# Optional — only present if the spoke tracks phases
phase: specify    # Or omitted entirely

---

The layering gap

The title says "local, spoke, and hub coordination layers" but the body covers the spoke layer only. That's fine for a v1 deliverable — the spoke contract is the right thing to ship first. But the relationship between layers needs to be explicit, because it affects the schema design:

┌─────────────────────────────────┐
│  HUB (pai-collab)               │  PROJECT.yaml + REGISTRY.md + STATUS.md
│  Inter-operator coordination    │  Aggregates spoke statuses
├─────────────────────────────────┤
│  SPOKE (.collab/)               │  manifest.yaml + status.yaml ← THIS ISSUE
│  Spoke-to-hub interface         │  Published to GitHub, read by hub
├─────────────────────────────────┤
│  LOCAL (~/.pai/blackboard/)     │  agents.yaml + tasks.yaml + quota.yaml ← #78
│  Intra-operator agent coord    │  On operator's machine, not published
└─────────────────────────────────┘

The key relationship: status.yaml should be a projection of local blackboard state, not an independent data source.

If the local blackboard (#78) tracks which agents are active, what work is claimed, and how many tokens remain, then blackboard status (the CLI command that generates status.yaml) should read from the local blackboard and project a public summary:

# .collab/status.yaml — fields sourced from local blackboard
agentActivity:
  activeAgents: 2
  lastActivity: "2026-02-01T11:15:00Z"
  currentWork:
    - "Addressing PR #56 review findings"
    - "Reviewing #68 introduction"

This is optional and additive — spokes without a local blackboard still generate status.yaml from git + specflow + tests. But spokes with a local blackboard get richer status that answers the #77 question: "is anyone actively working on this right now?"

This doesn't change the v1 spoke schema. It's a v2 enrichment that becomes possible once the local blackboard (#78) exists.

---

Schema-specific feedback

Security — git.dirty and git.behindRemote:
These are useful for the spoke maintainer but potentially noisy for hub consumers. A spoke that's dirty or behind remote isn't necessarily unhealthy — it might just mean the developer is mid-work. Consider whether the hub should act on these fields or just display them. If display-only, they're fine. If the hub uses them for health scoring, "dirty = unhealthy" will generate false alarms.

Concurrency — status.yaml as auto-committed file:
The GH Action commits status.yaml on push to main. If two pushes happen close together, you get a race condition where the second push fails because the first push's status.yaml commit changed main. The Action needs a pull-before-push or a retry loop:

- name: Commit if changed
  run: |
    git pull --rebase origin main
    git add .collab/status.yaml
    git diff --cached --quiet || git commit -m "chore: update spoke status"
    git push

generatedBy field:
Good for provenance. Suggest including the generation context (CI vs local vs agent) so consumers know how fresh the data is:

generatedBy: blackboard-cli v1.0.0
generatedContext: github-actions    # or: local-cli, pai-agent

---

CLI phasing feedback

v1 scope is right. The five spoke commands (init, status, validate, pull, registry) are the minimum viable spoke contract. Ship this.

v2 — blackboard journal add/read:
This is high-value. Journaling is the most manual part of the current workflow. A CLI command that formats the entry, validates against the schema, and appends to the correct file would remove real friction. Suggest promoting this to v1.5 — ship it right after the spoke contract, before the full hub operations set.

v2 — blackboard check:
This already exists as the pr-schema-check scripts in .github/workflows/. The CLI command should wrap those same scripts rather than reimplementing validation. Code reuse, not duplication.

v3 — blackboard pr review:
Ambitious. Structured review with Council debate is a full PAI skill invocation, not a CLI command. Suggest this stays as a PAI skill (/review) that uses blackboard CLI for data gathering rather than being part of blackboard CLI itself. Keep the CLI focused on data operations. Let PAI skills handle cognitive operations.

---

Summary

The spoke contract schema is solid and ready for implementation. The three open questions have reasonable answers (convention over exports, .collab/ for directory, phase as optional spoke-side field). The GH Actions heartbeat is the right architecture for spoke-level change awareness.

The main gap is making the layering explicit — how the local blackboard (#78) feeds into spoke status (#80) feeds into hub aggregation. This doesn't block v1 but should be documented in the architecture so v2 enrichment has a clear integration path.

[Steffen025]

Security Review: Spoke Contract Schema

From: @Steffen025 (Jeremy — OpenCode/Claude Opus 4.5)

Thanks for the tag, @mellanon. Adding security-focused feedback to complement @jcfischer's excellent architectural review.

---

Security Assessment: status.yaml Exposure

The auto-generated status.yaml is publicly visible on GitHub. Here's what each field reveals and the associated risk:

Field	What It Reveals	Risk Level	Recommendation
phase	Current development stage	LOW	Keep — useful for coordination
specflow.*	Feature counts, progress %	LOW	Keep — aggregate data only
tests.passing/failing	Test health	LOW	Keep — useful signal
tests.command	Build tooling (bun test)	LOW	Keep — not sensitive
git.branch	Active branch name	LOW	Keep
git.lastCommit	Last activity date	LOW	Keep
git.dirty	Uncommitted changes exist	MEDIUM	⚠️ See below
git.behindRemote	Sync status with remote	MEDIUM	⚠️ See below

⚠️ Concern: git.dirty and git.behindRemote

These fields are operational metadata rather than coordination data:

1. Information leakage: Tells observers when a maintainer is mid-work (dirty) or hasn't pulled (behind). This is timing information that could be used for social engineering or targeted attacks during "distracted" periods.

2. False health signals: As @jcfischer noted, dirty=true doesn't mean unhealthy — it means someone is working. But automated tooling might misinterpret this.

Recommendation:

Option A: Remove from v1, add in v2 with opt-in flag:

# manifest.yaml
status:
  includeGitState: false  # Default: don't expose dirty/behind

Option B: Keep but document that hub SHOULD NOT use for health scoring.

I lean toward Option A — minimize surface area for v1, expand later if there's demonstrated need.

---

Security Assessment: manifest.yaml

Field	Risk	Notes
maintainer	LOW	Public GitHub handle
hub	LOW	Points to public repo
status.test	MEDIUM	Reveals build tooling
status.healthCheck	MEDIUM	Could reveal internal tooling

status.test and status.healthCheck: These expose internal command structure. For most open-source projects, this is fine. For private spokes that might join the network, consider:

# Don't expose actual commands
status:
  test: true              # Just "yes we have tests"
  healthCheck: true       # Just "yes we have health checks"

The hub doesn't need to run these commands — it just needs to read the results from status.yaml. Exposing the actual commands is unnecessary coupling.

---

GitHub Actions Security

The proposed blackboard-sync.yml workflow is mostly sound, but:

1. Bot commits should use a GitHub App token, not default GITHUB_TOKEN:

# Current (works but limited)
git config user.name "blackboard-bot"
git push

# Better (auditable, revocable)
- uses: tibdex/github-app-token@v1
  id: app-token
  with:
    app_id: ${{ secrets.BLACKBOARD_APP_ID }}
    private_key: ${{ secrets.BLACKBOARD_APP_PRIVATE_KEY }}

This makes bot commits attributable to a specific GitHub App rather than an anonymous bot identity.

2. Race condition fix is good (@jcfischer's git pull --rebase suggestion). Add retry logic:

- name: Commit if changed
  run: |
    for i in 1 2 3; do
      git pull --rebase origin main && break || sleep 5
    done
    git add .collab/status.yaml
    git diff --cached --quiet || git commit -m "chore: update spoke status"
    git push

---

Answers to Open Questions (Security Lens)

1. exports field: Agree with @jcfischer — convention over explicit mapping. Explicit maps become stale and create maintenance burden. More importantly, explicit paths could inadvertently expose internal structure (exports.secrets: .env — oops).

2. Directory name: .collab/ is better from a security perspective. It's less likely to be targeted by automated scanners looking for .blackboard/ (hypothetically). Though this is minor — security through obscurity isn't real security.

3. phase field: Keep in spoke. The spoke is authoritative about its own state. Hub inference would require the hub to have read access to spoke internals, which is a larger attack surface.

---

Summary

The schema is security-appropriate for v1 with two recommendations:

1. Remove or opt-in git.dirty and git.behindRemote — operational metadata shouldn't be default-public
2. Abstract status.test/healthCheck to booleans — commands don't need to be exposed, only results

The GitHub Actions pattern is sound with the race condition fix. Consider GitHub App tokens for better auditability.

Overall: ✅ Ready for v1 with minor tweaks

---

Review by @Steffen025 using PAI security infrastructure

[Steffen025]

🔒 Security Review: Hub-Spoke Schema (Deep Analysis)

Reviewer: @Steffen025 + Jeremy (PAI-OpenCode)
Method: Adversarial analysis (red team perspective)
Verdict: ⚠️ CONDITIONAL APPROVAL — solid foundation, but critical issues need addressing before v1

---

🔴 CRITICAL (Must Fix Before v1)

1. Command Injection via manifest.yaml

status:
  test: bun test
  healthCheck: bun run typecheck

Risk: Arbitrary code execution. A malicious spoke could set a command that downloads and executes remote code. Hub executes this when aggregating status.

Mitigation: Whitelist allowed commands:

allowedCommands:
  - "bun test"
  - "npm test"
  - "yarn test"
  - "bun run typecheck"

2. Supply Chain Risk in GHA

- run: bun install -g @anthropic/blackboard-cli

Risk: No version pin, no integrity hash. Attacker compromises npm → owns all spokes.

Mitigation: Pin with integrity:

- run: bun install -g @anthropic/blackboard-cli@1.0.0 --integrity sha512-abc123...

3. Command Echo in status.yaml

tests:
  command: bun test  # ← Broadcasts the command publicly

Risk: Confirms attack success if injected command appears in output.

Mitigation: Hash the command instead:

tests:
  commandHash: sha256:abc123...

---

🟠 HIGH (Should Address)

Issue	Risk	Mitigation
git.dirty: true exposed	Signals "changes not committed yet" = vulnerability window	Consider omitting or making opt-in
git.behindRemote: 5	Advertises "5 commits behind" = known vulns not patched	Same
generatedBy: blackboard-cli v1.0.0	Version fingerprinting for targeted exploits	Omit version or make configurable
No GHA concurrency control	Race conditions on parallel pushes	Add concurrency: group: ${{ github.ref }}
No status.yaml validation	Malformed YAML could break hub aggregation	Schema validation before commit

---

✅ What's Good

• schemaVersion field enables safe evolution
• License requirement enforces legal clarity
• Execution-context agnostic design (works with or without PAI)
• Clear separation: manifest (human) vs status (generated)

---

Recommended Schema Additions

# manifest.yaml additions
security:
  allowedCommands: ["bun test", "npm test"]  # Whitelist
  
# status.yaml changes  
tests:
  commandHash: sha256:...  # Instead of command echo
  
# Optional: omit or redact
git:
  # dirty: false      ← Consider removing
  # behindRemote: 0   ← Consider removing

---

Bottom line: The architecture is sound. These are hardening issues, not design flaws. Fix the command injection vector and supply chain risk before v1, and this becomes a solid foundation.

Happy to elaborate on any finding. Full adversarial analysis available on request.

— @Steffen025 + Jeremy (PAI-OpenCode)