Add 11 diagrams, vendor mermaid, and stop the site fetching code from a CDN - #77
Merged
Conversation
Eva Benn is no longer a co-lead of the Identity workstream. She remains a co-lead of Outreach, so she keeps her CODEOWNERS entries and her line in CONTRIBUTORS.md, and `project.owasp.yaml` never named her because its schema caps leaders at five and carries the project lead plus the two creators. `GOVERNANCE.md` states that two leads per workstream keeps decisions moving when one is unavailable. That sentence stops describing Identity the moment this lands, so rather than leave it quietly false, the second seat is recorded as open alongside the Reference Implementation, Documentation, and Testing and Validation seats. `GOVERNANCE.md` is a build input. `tools/render_landing.py` parses the workstream table into the published landing page, so this changes the site. Verified by building the full pipeline: the table renders Identity as Richard Bird alone and Outreach unchanged with Eva and Aruneesh, and the single-lead row parses without incident. 204 tests pass, `mkdocs build --strict` clean. Signed-off-by: rocklambros <rock@rockcyber.com>
Promote integration to main: README rewrite with diagrams
Trace events, AgBOM formats, and conformance profiles describe shapes (parallel mappings, one-to-many derivation, layering on a floor) in prose alone. Draw each one next to the paragraph that defines it. The in-action walkthrough's plain-text sequence art becomes a mermaid sequenceDiagram in place, so the whole flow reads before the 263 lines of step-by-step detail. The conformance diagram states plainly that a layer is a self-declared claim, not a verified fact, matching the page's own disclaimer that no claim is verified in v0.1.0. Signed-off-by: rocklambros <rock@rockcyber.com>
The runtime path, the handshake, the five dispositions, the hook taxonomy, and the session lifecycle each carry a wire protocol or a state machine in prose alone. Add one small diagram after the prose that introduces each mechanism, matching the style of the existing diagram in docs/identity/standards.md. Signed-off-by: rocklambros <rock@rockcyber.com>
Signed-off-by: rocklambros <rock@rockcyber.com>
rocklambros
requested review from
GangGreenTemperTatum,
afogel,
almogbhl,
bar-capsule,
fewdisc,
mamicidal,
sclintonowasp and
stefanoamorelli
as code owners
September 10, 2026 04:08
afogel
previously approved these changes
Sep 10, 2026
rocklambros
dismissed
afogel’s stale review
September 10, 2026 12:51
The merge-base changed after approval.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds 11 diagrams to the specification and concept documentation, and fixes two problems found while verifying they actually display.
The diagrams
Eleven across nine pages, placed where a reader meets each mechanism rather than collected in a gallery. The runtime path and the constraint that the LLM layer cannot read policy code, the handshake, the five dispositions, the hook taxonomy, the session lifecycle, the Trace mappings into OpenTelemetry and OCSF, the AgBOM serializations, conformance profile layering, and the in-action walkthrough.
Before this,
docs/acs.mdat 773 lines,specification.mdat 433, andACS_in_action_example.mdat 263 carried a wire protocol, a two-layer Guardian, five dispositions, and a full scenario in prose alone.Two problems found by rendering them in a browser
The published site fetches executable JavaScript from a third party. mkdocs-material's bundle lazily loads mermaid from
https://unpkg.com/mermaid@11/dist/mermaid.min.jswhenever it meets a diagram. Verified live: loading the current publishedidentity/standardspage issues that request. The version is a range, so unpkg decides which 11.x a reader executes.The third-party guard missed it because
stray_scriptsallowlists the theme bundle by digest and never reads what is inside it. Confirmed three ways:third_party_hostson the rendered page returns none,stray_scriptsreturns none, and the allowlisted bundle contains two unpkg URLs.Mermaid has never rendered on this site. The one diagram already in
docs/identity/standards.mdresolves to an empty element with no SVG on the live site today. The theme's pass replaces the source block with an empty div before drawing, so the text is gone by the time mermaid is asked for a picture.The fix
Mermaid 11.17.2 is vendored at
docs/assets/javascripts/mermaid.min.jsand declared throughextra_javascript. The superfences custom fence now emits classacs-diagramrather thanmermaid, so the theme does not recognise a diagram, never reaches its loader, and never empties a block.mermaid-init.jsrenders from the vendored copy. Authors still write ```mermaid fences and GitHub still renders them natively.Cost: 3.5 MB uncompressed, about 956 KB gzipped, on pages that load it.
Guards
stray_scriptsnow accepts a built script whose digest matches a file indocs/assets/javascripts/, which proves it is byte-identical to what is committed here rather than merely allowed by path.A new guard asserts that package-CDN references in built JavaScript match a reviewed set. The three surviving unpkg references are documented with why each cannot fire. Proven by injection: adding a jsdelivr URL fails the test, removing it passes.
NOTICErecords the MIT attribution, matching the standard the file already sets for the Inter font and the AGT bundle.Verification
Every diagram rendered in a real browser, not asserted from a bracket count. 11 of 11 produce SVGs across all nine pages, zero raw blocks remain, and zero third-party requests are issued. 206 tests pass,
mkdocs build --strictclean.