You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Reviewer cycle 4 surfaced a structural insight (Gemini): mermaid
stateDiagram-v2 direction LR does NOT auto-draw edges across nested
state{} composites. The 'grouping = visible cross-dependencies'
promise from cycle 3 was unfulfilled — the workflows sat side-by-
side as disconnected boxes.
Doc:
- Draw explicit cross-workflow arrows where the handover endpoints
are both in the same diagram group:
* Group A2: LPM_DispatchFlakeFix -> LFF_Validate (sync dispatch-
workflow)
* Group A3: RA_T2_CreatePR -> RPS_ListPRs (async via label
AI-Issue-Regression-PR, picked up in RPS's next scheduled run)
- Move Handover Map from the bottom (after all diagrams) to
immediately AFTER Overview, BEFORE the first group diagram.
Reader now sees cross-workflow signals BEFORE the diagrams that
contain them. Three reviewers flagged the prior placement.
- Fix add_to_project Overview trigger row: clarify
pull_request_target fires but all jobs are gated off (GPT flagged
the overview/diagram contradiction).
- Add 'messages safe-output' glossary entry; table row max set to
n/a (Sonnet flagged undefined).
- Resolve AI-Auto-Resolve-* 'external' ambiguity: humans (manual,
opt-in) per labelops-pr-maintenance.md description.
- Add 'Affects-* family' glossary entry with all 7 area names.
Generator:
- Rule 48 added: cross-workflow arrows are MANDATORY when the
workflows are in the same Mermaid block. stateDiagram-v2 does
not auto-draw cross-composite edges; must declare explicitly.
Sync dispatch and async-via-label both modeled as labeled -->
with cross-workflow tag in the edge label.
- Rule 49 added: Handover Map placement MUST be after Overview
and before first group diagram. Bottom placement hides the
dependency map from the reader who needs it most.
Metrics: 560 -> 566 lines (+6, within +20 budget); 78 -> 78 pipe
rows (unchanged); 0 long edges; 6/6 mermaid blocks render.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy file name to clipboardExpand all lines: .github/docs/state-machine.md
+23-17Lines changed: 23 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,9 @@
23
23
-**`has_conflicts`** (labelops-pr-maintenance) — PR has merge conflicts.
24
24
-**`ci_blocked`** (labelops-pr-maintenance) — CI hasn't started yet (queued or blocked by other workflows).
25
25
-**`12h stuck guard`** (labelops-pr-maintenance) — Skip the PR if LabelOps already committed within the last 12 hours AND checks are still red. Prevents retry storms.
26
+
-**`messages` safe-output** — gh-aw runtime mechanism for posting lifecycle status updates (run-started, run-success, run-failure) and a per-run footer to a user-visible target (issue/PR comment). Templates support placeholders like `{workflow_name}`, `{run_url}`, `{event_type}`. Not rate-limited via `max:` — it's a per-run signaling channel, not a content output.
26
27
-**milestone 29 / `2026-05-12` cutoff** — Repo-specific operational constants: milestone 29 is applied by `add_to_project.yml` (internal milestone number; title unconfirmed from source); the `2026-05-12` cutoff in `labelops-pr-security-scan` is the date the scanner went live — PRs opened before that date are skipped to avoid re-scanning historical PRs.
28
+
-**`⚠️ Affects-*` family** (labelops-pr-security-scan) — agent-applied warning labels indicating which repository area a PR touches: `Build-Infra`, `Compiler-Output`, `Bootstrap`, `Restore`, `Design-Time`, `Test-Tooling`, `Agent-Config`. Drive reviewer attention to PRs touching sensitive code paths.
> **Cross-workflow signals at a glance.** Workflows talk to each other via labels, dispatch, indirect handoffs, and state-store branches. This map shows every cross-workflow signal documented below.
|`labelops-pr-maintenance.md`| Proven flake (flaky-test-detector ≥3 distinct unrelated PRs; test not introduced by current PR) |`labelops-flake-fix.md`|`dispatch-workflow: workflows: [labelops-flake-fix]`| Passes inputs; max 3/run |
72
+
|`aw-auto-update.md`| CHANGED_FILES non-empty after `gh aw upgrade + compile`| Copilot Coding Agent (CCA) |`create-agent-session` (base: main, max: 1) | CCA writes `.lock.yml` files using `COPILOT_GITHUB_TOKEN`|
|`repo-assist.md`| Regression test PR created (Task 2) |`regression-pr-shepherd.md`| Indirect via label `AI-Issue-Regression-PR` on PR | Shepherd picks up in subsequent scheduled run |
|`labelops-pr-maintenance.md`| Proven flake (flaky-test-detector ≥3 distinct unrelated PRs; test not introduced by current PR) |`labelops-flake-fix.md`|`dispatch-workflow: workflows: [labelops-flake-fix]`| Passes inputs; max 3/run |
551
-
|`aw-auto-update.md`| CHANGED_FILES non-empty after `gh aw upgrade + compile`| Copilot Coding Agent (CCA) |`create-agent-session` (base: main, max: 1) | CCA writes `.lock.yml` files using `COPILOT_GITHUB_TOKEN`|
|`repo-assist.md`| Regression test PR created (Task 2) |`regression-pr-shepherd.md`| Indirect via label `AI-Issue-Regression-PR` on PR | Shepherd picks up in subsequent scheduled run |
Copy file name to clipboardExpand all lines: .github/workflows/agentic-state-machine.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -314,6 +314,14 @@ You are a workflow-automation documentor. You read all workflow files in `.githu
314
314
315
315
47. **Mermaid grouping — workflows with cross-dependencies STAY in the same block.** Reviewers may complain that multi-workflow Mermaid blocks are "too dense" and propose one-workflow-per-block. **Resist this for any group whose workflows have cross-workflow signals** — shared labels (producer/consumer), shared state-store branches, dispatch-workflow handovers, indirect-via-label handoffs. Splitting these into separate diagrams hides the dependency graph: the reader sees independent islands and has to reconstruct the cross-edges by mental cross-reference with the Labels table and Handover Map. Keep them grouped so the visual proximity itself communicates "these interact." Acceptable to split groups whose workflows are truly independent (e.g., Group D — `branch-merge` / `skill-validation` / `copilot-setup-steps` share nothing). Per-workflow splits that erase visible cross-edges = MAJOR.
316
316
317
+
48. **Cross-workflow arrows are MANDATORY when grouped.** Rule 47 keeps cross-dependent workflows in the same Mermaid block. Rule 48 makes those cross-dependencies *visually* explicit: `stateDiagram-v2 direction LR` does NOT auto-draw edges across nested `state X { ... }` composites — it just renders side-by-side boxes. The reader sees no connection unless you declare it. For every cross-workflow handover documented in the Handover Map between workflows in the same diagram group, draw an EXPLICIT mermaid edge between the relevant inner states. Examples:
318
+
- **Sync dispatch** (workflow A dispatches workflow B in the same run): `LPM_DispatchFlakeFix --> LFF_Validate : 🤖 dispatch-workflow (cross-workflow, passes inputs)`
319
+
- **Async via label** (workflow A produces a label; workflow B picks it up in its next scheduled run): `RA_T2_CreatePR --> RPS_ListPRs : 🤖 async via label AI-Issue-Regression-PR (picked up in next RPS run)`
320
+
- **State-store handover** (workflow A writes to a memory branch read by workflow B in same run): same shape; label the transition with the branch name.
321
+
These declarations go in the outer `stateDiagram-v2` scope, AFTER both composites close (`}`) but BEFORE the diagram's closing ```` ``` ````. `stateDiagram-v2` supports bare state-name references across composites IF the inner state names are unique (prefix convention like `LPM_*`, `LFF_*` enforces this). Missing cross-edge for a documented handover whose endpoints are both in the same group = MAJOR — defeats the entire purpose of the grouping.
322
+
323
+
49. **Handover Map placement at TOP, not bottom.** Position the Handover Map immediately AFTER the Overview table and BEFORE the first group diagram. The map answers "how do these workflows interact?" — the reader needs that context BEFORE wading into individual control-flow diagrams. Burying the map at the bottom (the original "summary tables follow" pattern) forces the reader to discover cross-dependencies bottom-up: parse 6 diagrams in isolation, hit the map last, then mentally retrofit the connections. Three independent reviewers confirmed this. Handover Map placed AFTER any group diagram = MAJOR.
0 commit comments