Skip to content

docs: restore README workflow inventory to match the live control plane - #3884

Merged
marcusrbrown merged 2 commits into
mainfrom
fix/readme-workflow-inventory-drift
Sep 14, 2026
Merged

marcusrbrown merged 2 commits into
mainfrom
fix/readme-workflow-inventory-drift

Conversation

@fro-bot

@fro-bot fro-bot commented Sep 13, 2026

Copy link
Copy Markdown
Owner

What drifted

Two facts in README.md no longer matched .github/workflows/:

Claim Reality
Structure tree: # 25 GitHub Actions workflows 29 files in .github/workflows/
Automation tables: 26 rows (7 + 14 + 5) 29 workflows exist

Three workflows were missing from the tables entirely: Cross-Repo Dispatch, Publish Wiki, and Unpublish Wiki (emergency takedown). All three are described in README prose (Cross-Repo Goal Dispatch, Web-Rendered Wiki) but absent from the inventory a reader scans first.

Why it matters

README.md is canonical context #1 in .github/copilot-instructions.md. An agent that reads "25 workflows" and a 26-row table builds a model of the control plane that is missing its Pages publish path and its emergency takedown path. That is a wrong map, not a typo.

This is the same drift class as #3649, which corrected only the number. The number drifted again. Correcting the count and the tables in the same pass means they now agree at 29 — the next divergence between them is visible rather than silent.

Changes

  • Structure tree comment: 2529
  • Three rows added to the Fro Bot control plane table, triggers read from each workflow's on: block

Counts derived from ls .github/workflows/*.yaml | wc -l and each file's name: field, per the generating-project-docs inventory rules.

Verification

pnpm bootstrap, pnpm check-types, pnpm lint (including check:md-links), pnpm test (79 files, 3683 passed) all green on this branch. Documentation-only diff — no code, workflow, or config paths touched.

The structure tree claimed 25 workflows; `.github/workflows/` holds 29. The
Automation tables listed 26 of them, silently omitting Cross-Repo Dispatch,
Publish Wiki, and Unpublish Wiki — three surfaces that are described in
README prose but absent from the inventory a reader scans first.

README.md is canonical context #1 for agents working in this repo, so a
wrong count is a wrong mental model, not a cosmetic typo. Same drift class
as #3649; adding the missing rows means the count and the tables now agree,
which makes the next drift visible instead of silent.
@fro-bot

fro-bot commented Sep 13, 2026

Copy link
Copy Markdown
Owner Author

Daily remediation pass — categories 1–4

Swept the control plane for breakage. Found one thing actually broken, fixed it here. Everything else is either green, owned by another loop, or outside the scope cap.

1. Errored PRs — none

Two open PRs, both app/fro-bot (trusted automation). Inspected check runs and legacy commit statuses on each head SHA — the two legacy records (Security: Private Leak Scan, renovate/stability-days) are SUCCESS, so nothing hides in the gap between the two APIs.

PR Head SHA Checks State
#3882 renovate/pnpm-11.x ebbd3be 19/19 non-skipped green MERGEABLE / BEHIND
#3877 renovate/github-actions e7dadb5 18/18 non-skipped green MERGEABLE / BEHIND

Both have auto-merge armed and sit at REVIEW_REQUIRED. They aren't stuck on CI — they're stuck on a human. I don't approve PRs, so they stay where they are. No failing workflow runs across the last 60 on any branch.

2. Security — one open alert, below the remediation bar

One open Dependabot alert: @humanfs/node, medium, symlink-following recursive copy, transitive through the ESLint toolchain in pnpm-lock.yaml. Medium is under the critical/high bar that authorizes a dependency change in this pass, and Renovate owns routine bumps. No PR opened, by policy, not by oversight.

Scorecard's VulnerabilitiesID (high) is the same alert wearing a different badge. BranchProtectionID (high) is branch protection — a surface I'm explicitly forbidden from touching, and correctly so.

3. Control-plane integrity — clean

  • SHA pinning: every third-party uses: across 29 workflows and .github/actions/setup resolves to a 40-char SHA with a version comment. Zero floating tags.
  • Strip-only TypeScript: no enum, namespace, parameter properties, or import x = aliases in scripts/*.ts. The only match was a comment in scripts/repos-metadata.ts:476 explaining why the pattern is avoided — the guardrail documenting itself.
  • Least privilege: all 29 workflows declare top-level permissions; four declare permissions: {} and mint scoped tokens per job. Nothing over-broad.
  • Guards: wiki-authority, privacy gates, and branch protection untouched. This run wrote nothing to knowledge/** or metadata/**.

4. Code quality — green, with one real defect found outside the gates

pnpm bootstrapcheck-typeslinttest all pass on main. 79 test files, 3683 passed, 3 todo. Working tree clean, no generated-artifact drift.

The defect the gates can't see is what this PR fixes: README.md claimed 25 workflows against 29 on disk, and its Automation tables listed 26 — omitting Cross-Repo Dispatch, Publish Wiki, and Unpublish Wiki. check-md-links validates that links resolve, not that counts are true, which is precisely why this drifted twice (#3649 corrected the number alone; the number drifted again). Correcting the count and the tables together means they now agree at 29, so the next divergence is a visible contradiction instead of a quiet one.

This discharges finding #6 from the daily report issue #3883.


Needs Human Attention

@vitest/coverage-v8 is seven patches behind vitest. package.json declares vitest@4.1.11 and @vitest/coverage-v8@4.1.4; the gap opened when the vitest security bump (#3873) advanced core without the provider. Vitest expects the provider to track core. The smallest safe fix is one line in package.json"@vitest/coverage-v8": "4.1.11" — followed by pnpm bootstrap and pnpm coverage. I did not apply it: this pass may change dependency versions only to remediate a confirmed critical/high advisory or repair a security PR, and this is neither. It needs a human or a Renovate run to land. Reported independently as #3883 finding #5.

@humanfs/node medium advisory (alert #59). Transitive via the ESLint toolchain. Below the auto-heal bar; left for Renovate. Do not hand-edit pnpm-lock.yaml to resolve it — the correct path is an upstream ESLint bump.

#3882 and #3877 are blocked on human review, not CI. Both are green and auto-merge-armed. They will sit BEHIND indefinitely until reviewed. Nothing to repair; just review them.

Durable knowledge this run surfaced, which it cannot persist. The README workflow count has now drifted twice, and both times pnpm lint was green while the doc was wrong. The generalizable lesson — a documented count with no machine check is a claim, not a fact, and will drift back; the mitigation is to make the count and the enumeration agree so they contradict each other visibly on the next drift — belongs in the wiki or docs/solutions/. This job delivers via branch-pr and has no wiki-write step, so it dies here unless someone captures it. A run dispatched with output-mode: working-dir can write it; knowledge/** is off-limits from this pass by design.

🤖 Generated by Fro Bot · run 34671730863

@marcusrbrown
marcusrbrown enabled auto-merge (squash) September 14, 2026 07:12
@marcusrbrown
marcusrbrown merged commit 10d078b into main Sep 14, 2026
18 checks passed
@marcusrbrown
marcusrbrown deleted the fix/readme-workflow-inventory-drift branch September 14, 2026 07:14
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.

2 participants