Skip to content

Docs: close the workflow-reference gaps (canary, dummies, gendoc-docs) and refresh stale pages #241

Description

@Reefact

Problem

3 of 15 workflows have no reference page and are absent from the workflows/README.md index (canary.yml, dummies.yml, gendoc-docs.yml — ci.en.md:102 even self-flags canary as "(no reference page yet)"). Three existing pages are stale after the July 17–19 pipeline churn: ci.en.md documents two of ci.yml's three jobs (the net472 framework-floor job — ADR-0022's enforcement point — is invisible); release-dryrun.en.md twice says "the two published projects" while the yml packs three trains and also rehearses release-notes generation; smaller stale pointers (tag-format example v1.2.3 vs lib-v*, the lib|cli) allowlist quote missing dum) compound it.

Impact

The doc layer's whole value proposition — protecting workflow intent from well-meaning cleanup — fails exactly for the undocumented workflows, and the project's own precedence rule ("the YAML wins — and the page should be corrected") is currently violated.

Direction

  • Write EN+FR reference pages for canary, dummies, gendoc-docs (purpose, triggers, structure, permissions, "Handle with care") and index them.
  • Update ci.en/fr.md (framework-floor job) and release-dryrun.en/fr.md (three trains, release-notes step); sweep the stale pointers batch (§11.5).
  • The workflow-doc coverage check in Docs: codify the real bilingual policy and add advisory docs-consistency checks #240 keeps this closed permanently.

Acceptance criteria

  • 15/15 workflows have EN+FR pages and index rows; the ci and release-dryrun pages match their YAML; the stale-pointer list from §11.5 is cleared.

Context

Surfaced by the 2026-07-20 architecture, design & ecosystem audit (doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §11.5/§14-HV9; branch claude/firstclasserrors-audit-83gap7).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions