Point the Fleet Map at the Shipped Diagrams and Current Tooling - #703
Merged
Conversation
A re-analysis of docs/fleet-map.md after the P0-P4 closures and the #702 procedure-doc diagrams found the map's own copies of the STANDUP and RESYNC flows superseded at finer grain by the diagrams the procedure docs carry, with no cross-reference in either direction. By the map's own rule the procedure doc wins, so the derivative copies are removed in favor of pointers, the maintenance rule is extended to cover drawn flows, the stale Checked-anchor sentence and cold-start tool list are corrected after #701, OPERATIONS.md, repo_gate.py, pr_review.py, and spec/audit.py are surfaced as the entry points they are, #699 and #700 are cross-linked, and README gains the one link that makes the map discoverable from the front door.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates fleet documentation cross-links so docs/fleet-map.md points at the authoritative, shipped procedure diagrams and current tooling references, and exposes the fleet map from README for easier discovery.
Changes:
- Add a README reference-link to the hub-only fleet map behind the entry doors diagram.
- Replace duplicated STANDUP/RESYNC flow diagrams in
docs/fleet-map.mdwith pointer sentences, and refresh stale/incorrect prose (maintenance rule scope, cold-start tooling reference, and additional runnable entry-point links). - Add
worktreetocspell.jsonto support new cross-link wording.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Adds a reference-style link to docs/fleet-map.md from the entry doors section. |
| docs/fleet-map.md | Removes duplicated procedure diagrams, strengthens/extends the maintenance rule, refreshes stale references, and adds/uses reference links for key entry-point tooling/docs. |
| cspell.json | Adds worktree to the dictionary to avoid false positives. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
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 #700 Closes #707 Closes #711 Closes #712 Closes #714 Closes #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 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.
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
Checkedevidence-anchor sentence (the shipped register has no such cells, and theba392f9pin is historical) is removed, the cold-start tool node points atspec/host-tools.jsoninstead of an enumeration that drifted twice in two weeks (Self-Heal a Shadowing uv, jq, or git-restore-mtime Copy on Install #689, Add Docker install/upgrade support on Linux and Windows, with a version floor #701), and the dead "dashed arrows mark a gap" clause (zero dashed arrows exist) is removed.scripts/repo_gate.py,scripts/pr_review.py, andspec/audit.pyget reference links.worktreejoinscspell.jsonwords (used by the Propose a Repo and Worktree Layout Convention and a repo-worktree Skill #699 cross-link).Flag, not a task
docs/fleet-map.mdand the #702 diagrams exist only ondevelop(main is 22 commits behind and lacks the file entirely). Adeveloptomainpromotion is a maintainer decision and is not part of this change.Verification
All nine CI prose_lint checks pass tree-wide and
--diff developis 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.pyandjqpass, 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