Add mermaid flow diagrams to the kept-authority docs - #702
Merged
Conversation
Gives the fleet's kept-authority docs the same at-a-glance mermaid diagrams docs/fleet-map.md already uses, so a reader gets the shape of the flow inside the procedure doc itself rather than only in the hub-only summary map: - README.md: entry-doors flowchart in 'How This Repo Operates', matching the Getting Started table's rows. - STANDUP.md: full section-by-section procedure map (0 through 5). - RESYNC.md: primary route/measure/apply/ship flow, plus a detail diagram for the section 4 deletion remedy. - AUDIT.md: primary measurement-pipeline map (0 through 8) plus a section 9/10 escalate-vs-converge diagram. - AGENTS.md: a small Fleet Bootstrap diagram using the same door names as README's, so the agent-entry and human-entry views are visibly the same graph. - WORKFLOW.md: no new diagrams; 3 existing diagram node labels get their governing D-guarantee number appended (label text only). Every new node label opens with the section number or name it maps to, so each diagram doubles as a navigable index of its own doc. Verified clean with markdownlint-cli2, cspell, and editorconfig- checker; cross-checked every diagram's node set against its source doc's actual headings for completeness, order, and no invented door. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds at-a-glance Mermaid flow diagrams to key procedure docs (README/STANDUP/RESYNC/AUDIT/AGENTS) to make the routing and step order visible inside each document, and updates existing WORKFLOW.md diagrams to include the governing D-guarantee tags in node labels.
Changes:
- Add Mermaid flowcharts to README.md, STANDUP.md, RESYNC.md, AUDIT.md, and AGENTS.md to visualize their procedures/routing.
- Add a secondary deletion-remedy Mermaid diagram to RESYNC.md section 4.
- Append
(D#)tags to existing Mermaid node labels in WORKFLOW.md to tie diagram nodes to guarantee definitions.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| WORKFLOW.md | Adds (D#) tags to existing Mermaid diagram node labels to reference D-guarantees. |
| STANDUP.md | Adds a section-by-section Mermaid map of the cold-start standup procedure. |
| RESYNC.md | Adds a primary resync routing/apply/shipping diagram plus a deletion-remedy detail diagram. |
| README.md | Adds an entry-doors flowchart aligned with the “Getting Started” entry points. |
| AUDIT.md | Adds Mermaid diagrams for the measurement pipeline and escalate-vs-converge decision. |
| AGENTS.md | Adds a Fleet Bootstrap Mermaid diagram matching the README door names. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Uh oh!
There was an error while loading. Please reload this page.
Declare the apply subgraph before any edge references its id, since referencing it both before and after the declaration risked a Mermaid id collision between the implicit node and the subgraph. Drop the incorrect '5' tag on the re-audit node (section 5 is 'What a Resync Cannot Detect', not re-auditing; the actual re-audit step is described in section 6 'Ship It'), anchoring section 5's actual content, the intent-fidelity caveat, on the intent-files node where it belongs instead. Also replaces a non-ASCII em dash with ASCII punctuation, per GOVERNANCE.md 'Documentation Style Conventions'. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Aug 14, 2026
## Why A re-analysis of `docs/fleet-map.md`, applying the same gap-finding method that created it, after the P0-P4 closures, the #689/#701 install-model changes, and the #702 procedure-doc diagrams. ## What - **Diagram authority**: #702 put authoritative flow diagrams into STANDUP.md, RESYNC.md, AUDIT.md, and AGENTS.md. The map's own copies of the STANDUP and RESYNC flows were coarser duplicates with no cross-reference in either direction, and by the map's own rule the procedure doc wins. The two derivative diagrams are replaced with pointer sentences, and the Entry Points intro states the ownership rule. The five diagrams no procedure doc draws (System Map, Pre-Agent Cold Start, Daily Development, Hub-Side Operations, G3 remedy loop) stay. - **Maintenance rule extended**: it covered register rows but not drawn flows, which is exactly the class this batch fixes. It also cited G4 for register staleness, which is at best an analogy, so the sentence states the class directly. - **Stale content**: the vestigial `Checked` evidence-anchor sentence (the shipped register has no such cells, and the `ba392f9` pin is historical) is removed, the cold-start tool node points at `spec/host-tools.json` instead of an enumeration that drifted twice in two weeks (#689, #701), and the dead "dashed arrows mark a gap" clause (zero dashed arrows exist) is removed. - **Unmapped entry points surfaced**: OPERATIONS.md is named as the runnable form of the Hub-Side Operations door and of the daily-dev gates node, and `scripts/repo_gate.py`, `scripts/pr_review.py`, and `spec/audit.py` get reference links. - **Cross-links**: #699 and #700 join the Decision Ledger Cross-References per the #671-cluster precedent, and the #689 PATH self-heal is noted in the cold-start prose. - **Discoverability**: README links the map from the doors diagram it sits behind. AGENTS.md is deliberately untouched (byte-locked Fleet Bootstrap, and a carried file must not reference a hub-only doc). - `worktree` joins `cspell.json` words (used by the #699 cross-link). ## Flag, not a task `docs/fleet-map.md` and the #702 diagrams exist only on `develop` (main is 22 commits behind and lacks the file entirely). A `develop` to `main` promotion is a maintainer decision and is not part of this change. ## Verification All nine CI prose_lint checks pass tree-wide and `--diff develop` is clean, markdownlint reports 0 issues on both edited files, cspell is clean on README and leaves only the six pre-existing fleet-map findings (the file is not CI spell-gated), editorconfig-checker passes (CRLF preserved, diff is line-scoped), `spec/validate.py` and `jq` pass, all 6 remaining mermaid fences (5 in fleet-map, README doors) parse OK via mermaid@11, and a two-way reference-link check (every use defined, every relative target exists) passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
ptr727 added a commit
that referenced
this pull request
Aug 15, 2026
…Python CI Gates (#718) Thirty-one squashes, `56f4d7d..d54862a`. 115 files, +20436/-5298. **Merge with a merge commit, never a squash, and never with `--delete-branch`.** This pull request's head is `develop` itself. ## What lands **Fleet Skills.** The `.agents/skills/` source tree, the generated `.claude-plugin/` distribution, `scripts/build_dist.py` with its `--check` gate, and `scripts/skills_install.py` with its host stamp (#676). Packaged as skills on top of the scaffold: PR review conduct and Copilot instructions upkeep (#677), comment and doc style (#678), resync-a-repo and fleet-conformance-check (#679), the per-language codestyles (#680), git commit conventions and operational vs release workflow (#681), stand up a repo (#683), and repo-worktree (#717). Coverage gaps closed in three passes (#690, #691, #692) plus the P4 sentence-length opt-in (#697). **Host setup.** The Windows host-setup tooling and its PowerShell gate (#674), the Windows bootstrap loader (#682), Docker install and upgrade on Linux and Windows with a version floor (#701, #705), a `uv` floor in `spec/host-tools.json` (#698), self-healing of a shadowing `uv`, `jq`, or `git-restore-mtime` copy (#689), node's real winget package id (#696), and a README for the Linux host-setup nuances (#710). **Python and CI.** Python tooling in CI with the script tests moved to `scripts/tests` (#704), `ruff format` adopted and gated (#709), and the PSScriptAnalyzer claim conditioned on repos that carry `.ps1` files (#686). **Conduct rules.** Triage-order and scope guardrails in pr-review-conduct (#684), `pr_review.py wait` requesting a review rather than only polling for one (#685), a tech-agnostic signed-commit verification (#708), execution rather than analogy to verify platform-specific code (#715), and a unique worktree for every task (#717). **Docs.** The fleet map and gap register with peer messaging declared (#687), mermaid flow diagrams in the kept-authority docs (#702), and the map pointed at the shipped diagrams and current tooling (#703). ## Issues this promotion closes Each landed on `develop` on its own pull request. The keyword fires only on a merge into `main`, so it sits here rather than on the feature pull requests. Closes#700Closes#707Closes#711Closes#712Closes#714Closes#688#699 stays open on purpose: #717 shipped the layout convention and the skill, and the physical migration of existing checkouts is still tracked there. ## Review record Every squash closed its own Copilot loop on its own pull request before merging to `develop`. This promotion carries no new content of its own, so its review is the merged tree as a whole. ## Consequence worth stating The `GOVERNANCE.md` and `AGENTS.md` sections these squashes changed become the canonical the moment this reaches `main`, and every carrying repository reads as drifted from that point until it resyncs. That is the ordinary consequence of a canonical moving rather than a defect. The Skills installer added here is also how a machine picks the new skills up, so a session that keeps restating a rule already packaged as a skill is the signal to run it.
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 freeto 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.
Gives README.md, STANDUP.md, RESYNC.md, and AUDIT.md the same at-a-glance
mermaid diagrams
docs/fleet-map.mdalready uses, so a reader gets theshape of the flow inside the procedure doc itself instead of only in the
hub-only summary map. Also adds a small matching diagram to
AGENTS.md'sFleet Bootstrap section, and appends the governing
D-guarantee numberto 3 already-existing
WORKFLOW.mddiagram labels (no new diagramsthere, no structural change).
What changed
README.md: entry-doors flowchart in "How This Repo Operates",matching the "Getting Started" table's rows.
STANDUP.md: full section-by-section procedure map (0 through 5).RESYNC.md: primary route/measure/apply/ship flow, plus a detaildiagram for the section 4 deletion remedy.
AUDIT.md: primary measurement-pipeline map (0 through 8), plus asection 9/10 escalate-vs-converge diagram.
AGENTS.md: a small Fleet Bootstrap diagram reusing README's doornames, so the agent-entry and human-entry views are the same graph.
WORKFLOW.md: 3 existing diagram node labels get a(D#)tagappended; label text only, no graph-shape change.
Design principle: every new node label opens with the section
number or name it maps to, so each diagram doubles as a navigable
index of its own document and a renamed/renumbered section shows up
as a mismatched node rather than drifting silently.
Scope note:
docs/fleet-map.mditself is intentionally untouched(no register gap is closing, no disagreement with a procedure doc to
fix).
AUDIT.mdandAGENTS.mdwere added to scope beyond the threefiles first requested, since they complete the same triangle
fleet-map.mdnames and close a real divergence risk (AGENTS.md'sFleet Bootstrap and README's Getting Started table already described
the same routing in two independent prose blocks).
Verification: markdownlint-cli2, cspell, and editorconfig-checker
all ran clean via Docker over the six changed files. Every diagram's
node set was cross-checked against its source doc's actual headings
and table rows for completeness, order, and no invented door.
🤖 Generated with Claude Code