Skip to content

feat: generate the ecosystem status diagram from a status file - #8

Open
chaksaray wants to merge 2 commits into
developfrom
feat/7-status-diagram
Open

chaksaray wants to merge 2 commits into
developfrom
feat/7-status-diagram

Conversation

@chaksaray

@chaksaray chaksaray commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

Closes #7

What and why

ECO-1. Hand-drawn diagrams drift. ecosystem-status.yaml now lists each component with a state and the claim that backs it, and scripts/render_status.py draws diagrams/status.mmd and the block in profile/README.md from it.

Decisions you gave (recorded on #7):

  • AVE is drawn outside the Bawbel box, with a long-dash outline, labelled "AVE, separate org".
  • A fifth state, offline, so PiranhaDB is drawn as what it is: built, not serving. States: live, pre-release, designed, offline, not-built.
  • AVE keeps evidence claim C-01, so the evidence check is red until the READMEs that lag are fixed.

Each state is written in the node text and has its own dash pattern (designed 3 3, offline 2 4, not-built 5 4, outside 8 3), so colour is never the only cue. The tests check both.

Verify (run this session)

python3 -m pytest tests                              -> 65 passed
python3 scripts/render_status.py --check             -> current: diagrams/status.mmd, profile/README.md   (exit 0)
python3 scripts/render_status.py --verify-evidence   -> error: ave: state live but C-01 is FAIL in claims/STATUS.md   (exit 1, by design)

Test count: 23 at the base commit plus 42 new = 65.

Mutation check on a copy of the generator, 13 changes, each fails at least one test: FAIL treated as ok, UNVERIFIED treated as ok, a missing result ignored, every state checked, nothing checked, AVE drawn inside the boundary, the outside dash dropped, labels unescaped, the state not written as text, --check ignoring the diagram file, --check ignoring the README block, the offline dash dropped, edges dropped.

python3 scripts/verify_claims.py --output <scratch> on this branch: 7 FAIL, 1 UNVERIFIED, 12 PASS, the same seven as on develop. The new text trips no wording claim. It also shows profile/README.md:64 still says "The scanner never executes what it scans" (C-11); that is ECO-5.

Acceptance

  • scripts/render_status.py: no network (a test greps the source), deterministic (a test renders twice and --write twice)
  • Setting a component to live with a failing evidence claim fails: tested for FAIL, UNVERIFIED and a missing result, and end to end through the command (gate set to live while C-10 fails -> exit 1). It also reports the real case, AVE.
  • diagrams/status.mmd embedded in the org profile README and each repo README. Done for the org profile. The repository READMEs are other repositories, so they are separate tasks. The script takes --readme PATH and the same two marker comments, so each is a small change.
  • The diagram carries a one-line legend (a node in the diagram) and the README block adds a link to claims/STATUS.md

CI on this PR (gh pr checks 8)

tests      pass   7s
current    pass   9s
evidence   fail   6s    error: ave: state live but C-01 is FAIL in claims/STATUS.md

Things you should know

  1. The evidence job is red on this PR, on purpose. C-01 is FAIL because README counts in gate, piranha-api, integrations and scanner lag the 87 published records. tests and current are separate jobs and are the ones that say whether the generator and the committed files are right. The evidence job reads the committed claims/STATUS.md, which on develop is still the 2026-10-12 run. PR docs: how Bawbel components consume the AVE standard #4 regenerates it.
  2. I edited a sentence you did not ask me to. The paragraph above the diagram said "Target architecture. No integration with the runtimes named below ships today". The hand-drawn block that named OpenShell, Cloudflare and AWS is gone, so "named below" pointed at nothing, and the new diagram shows current state, not a target. It now reads "The diagram below is generated from ecosystem-status.yaml. No integration with other agent runtimes ships today, and identity, reputation, and delegation are not built." ECO-5 asked to keep the target-architecture sentence; this is the smallest change that keeps the paragraph true.
  3. The profile README now contradicts itself in two table rows until ECO-5. The diagram says PiranhaDB is offline; the component table and the "What exists today" table still say Live. ECO-5 changes those rows.
  4. The hub node is labelled "Hub, inside gate repo" as in the runbook. There is no separate hub repository.

Not verified

  • That GitHub renders the Mermaid block. I read the generated syntax; I did not run a Mermaid parser or view the page. The first thing to check after merge is the org profile page.

chaksaray and others added 2 commits October 23, 2026 07:01
scripts/render_status.py does not exist yet, so these fail. They cover the
rendering (deterministic, state shown as text and as a dash pattern, AVE
outside the boundary and dashed, escaping, legend with the status path),
validation of ecosystem-status.yaml, the rule that a live component needs a
PASS in claims/STATUS.md, the --write and --check commands against stale
files, and that the committed files in this repository are current.

Refs #7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015T9K217kxBqsUZ3omKYv9P
Signed-off-by: chaksaray <chaksaray@gmail.com>
ecosystem-status.yaml lists each component with a state (live, pre-release,
designed, offline, not-built) and the claim that backs it. render_status.py draws
diagrams/status.mmd and the marked block in profile/README.md from it:
deterministic, no network. AVE is drawn outside the Bawbel boundary with a long
dash, and PiranhaDB is offline. Each state is written in the node and has its own
dash pattern, so colour is not the only cue.

--check fails when a generated file is stale. --verify-evidence fails when a
live component's evidence claim is not PASS in claims/STATUS.md. It reports AVE
today, because C-01 is FAIL while README counts in other repositories lag.

The hand-drawn interoperability block in the profile README is replaced by the
generated one. A workflow runs the tests, --check and --verify-evidence as three
jobs.

Closes #7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015T9K217kxBqsUZ3omKYv9P
Signed-off-by: chaksaray <chaksaray@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant