Canonical framework for workflow and pipeline architecture. Defines what we are building, why, and the rules every workflow follows in this ownerless self-governed repo.
This repo is ownerless and self-governed. The product itself runs the rules: detects breaks, fixes what it can, raises issues for what it cannot, and documents every change without human babysitting. The framework below describes what that system must look like.Target end state:
Six action workflows. One per concern. Maintenance scales with the number of concerns, not the number of scripts.
Workflows are thin dispatchers. YAML answers when, where, with what permissions. All business logic lives in governed scripts under operations/scripts/. Inline JavaScript over 50 lines is a defect.
Local CLI equivalence on every dispatcher. Any contributor (human or AI agent) can run any pipeline locally with --dry-run, with no CI trigger and no GitHub secrets, before pushing.
Prevention at the earliest layer (D-GOV-08). Every governance rule fires at the earliest possible layer. Detection at later layers is a fail-safe, never the primary mechanism. The five-layer chain – write time (PreToolUse hook), commit time (pre-commit), PR time (validator), post-merge (auto-repair), schedule (drift scan) – applies to every governed surface. A rule that only catches violations on schedule is a rule that lets violations land.
Detect, repair, escalate, verify. Every detection routes to a response. No headless scans. No findings die in a log. Remediators support --verify so successful fixes survive and only regressed files revert.
Self-documenting. The actions library, script registry, and decisions registry regenerate from data on every change. No manual documentation sync.
One taxonomy spine. 7 types times 7 concerns times 8 pipeline tags. Every workflow and every script declares all three. The system is searchable, mappable, and predictable.
Bottom-up integrity. Every script has a verified purpose, a known caller, an SME endorsement, and a place in the taxonomy. Orphan scripts are archived, not preserved out of caution.
Every folder is governed (D-GOV-08). No commit of files that do not belong. Every folder hosting repo-influencing files declares an explicit allowlist enforced through the five-layer prevention chain.
Composable at every tier. Every script (atomic, pipeline, meta) is independently runnable via node with --dry-run. A developer can call any pipeline directly without going through CI.
If any of those properties is missing, the framework is not yet implemented.
Every workflow YAML is a dispatcher. Workflows handle trigger, environment, permissions, secrets, concurrency, and orchestration. They do not contain business logic. Typed work lives in scripts.
All business logic, file I/O, exit codes, dry-run, verify, structured output
Yes (7-type taxonomy)
The type prefix in the filename identifies what the script does, not what the workflow does.Tier 1 workflow classes: the 6 dispatch-{concern}.yml files are the concern dispatchers (the “actions” in this framework’s terminology – one per concern). The 5 interface-governance-*.yml files (assign-reviewers, close-linked-issues, index-issues, intake-discord-issues, label-issues) wrap interface type scripts that react to issue/PR/webhook events; they are tagged # pipeline: P7 distinct from the P2–P6 dispatcher taxonomy. Both classes live in .github/workflows/ for an active total of 11 workflows.
The repo orchestrates work through four tiers. Every script at every tier is independently runnable via node with --dry-run. A developer can call any pipeline, any meta-bundle, or any atomic directly without going through CI.
Tier
What it is
Count (live 2026-05-25)
Composability
1. Action
Thin workflow YAML files in .github/workflows/. Fires on event, calls a meta dispatcher (or pipeline directly).
6 dispatch- actions + 5 interface-governance workflows = 11 active
Triggered by GitHub events only – not runnable locally.
2. Meta dispatcher
Optional script that bundles related pipelines into a higher-level entry point (for example: “all health PR pipelines”).
~20 (3 per concern average)
node dispatch-{concern}-{verb}.js --dry-run
3. Pipeline dispatcher
Owns one full detect-repair-verify-escalate cycle for one niche. Accepts --mode pr|scheduled|manual.
Single-purpose, type-pure (validator, audit, remediator, generator, integrator, or interface).
230 wired
node {type}-{thing}.js --files {paths}
Naming rules:
Action YAMLs: dispatch-{concern}.yml. Concern from the 7-enum.
Meta dispatchers: dispatch-{concern}-{verb}.js. Verb from the 11-enum and indicates which kind of pipelines are bundled (check for PR-time bundles, scan for scheduled bundles, repair for manual bundles, generate for post-merge bundles, update for scheduled integrator bundles, react/intake/index for event handlers).
Pipeline dispatchers: dispatch-{niche}.js. Verb dispatch because the pipeline orchestrates a full cycle (not a single verb’s work). Niche is the second-level grouping inside a concern (wcag, page-integrity, em-dashes, contract-addresses, folder-allowlist, etc.).
Atomic scripts: verb-noun where verb matches the script’s type (check-* for validators, scan-*/audit-* for audits, repair-* for remediators, generate-* for generators, fetch-*/update-* for integrators). One concern per atomic.
Type-purity is enforced at the atomic and meta levels. Pipeline dispatchers are deliberately mixed-type because they implement a full cycle (a WCAG pipeline calls a validator, a remediator, and an audit – that is the cycle, not type-mixing). The dispatcher’s verb is dispatch to signal this is intentional orchestration.Composability worked example:
# Run one pipeline (full WCAG lifecycle)node operations/scripts/dispatch/content/health/dispatch-wcag.js --dry-run# Run WCAG in scheduled mode (audit + repair + verify + escalate)node operations/scripts/dispatch/content/health/dispatch-wcag.js --mode scheduled --dry-run# Run all health PR pipelines via metanode operations/scripts/dispatch/content/health/dispatch-health-check.js --dry-run# Run a single atomic validator (skip dispatchers)node operations/scripts/validators/content/health/check-wcag.js --files v2/page.mdx
The full structure across all 6 actions. Each action expands to its meta dispatchers; each meta expands to its pipeline dispatchers; each pipeline expands to every atomic script needed for its full lifecycle (detect + repair + verify + escalate). Atomics marked (NEW – Phase 3) do not exist yet and will be created during implementation. A pipeline is not composable if any of its lifecycle atomics is missing – every pipeline shown here is targeted at full closure.The implicit verify step: after a pipeline runs its repair atomics, it re-runs its detect atomics on the affected files. This is the same script invocation with --verify flag rather than a separate atomic. Only files that pass re-detection survive; regressed files revert.The implicit escalate step: every pipeline includes lib/rolling-issue.js to open, update, or close a rolling GitHub issue per residual finding. Auto-fixable findings never reach escalation; only what cannot be repaired by the cycle gets human attention.
dispatch-health.yml (action)
dispatch-health-check.js (PR meta)
dispatch-health-scan.js (scheduled meta)
dispatch-health-repair.js (manual meta)
dispatch-brand.yml (action)
dispatch-copy.yml (action)
dispatch-discoverability.yml (action)
dispatch-maintenance.yml (action)
dispatch-governance.yml (action)
Phase 3 NEW atomic scripts (created during implementation; this Tree commits to the full closure of every pipeline):
Pipeline
New atomic
Type
Purpose
dispatch-page-structure
repair-anchor-usage.js
remediator
Pairs with check-anchor-usage
dispatch-page-structure
repair-description-quality.js
remediator
Pairs with check-description-quality
dispatch-page-structure
repair-lint-structure.js
remediator
Pairs with lint-structure
dispatch-page-rendering
check-broken-links.js, repair-broken-links.js
validator + remediator
Replace mintlify integration with first-party atomic
About 30 new atomic scripts to build in Phase 3 to close every pipeline’s lifecycle.Layer-1 hooks (Claude Code PreToolUse / PostToolUse / SessionStart) are atomic scripts invoked outside the CI dispatcher tree. They live in operations/scripts/dispatch/governance/ and are wired via .claude/settings.json. The CI dispatchers above never call them; they run in the local editor session before code reaches git.What the PR sees with this architecture:
PR touching v2/*.mdx triggers up to 6 action workflows (one per concern, filtered by paths:)
Each workflow runs ONE job per relevant trigger, with sequential steps inside calling pipeline dispatchers
Each job appears as ONE PR check named “Concern · PR Check” (for example, “Health · PR Check”)
A failed step in any job fails the entire concern check with a clear log entry showing which pipeline dispatcher caught what
This delivers six clear PR checks for full coverage, replacing the current 24-plus checks. Each pipeline dispatcher remains independently runnable locally via node operations/scripts/dispatch/{content|governance}/{concern}/dispatch-{niche}.js --dry-run.
Every Pattern B generator must have a matching Pattern C verifier that runs with --check on PR. The verifier compares the committed file to what the generator would produce. Drift fails the PR.Every Pattern E remediator must accept --verify. After applying fixes the script re-runs the matching validator on affected files and reverts only files that regressed. Successful fixes survive even when one file fails.
No headless scans. Every detection routes to one of four responses:
Detection
Route
Authority
Auto-fixable
Apply fix silently in CI
Highest preference
Auto-fixable but high blast radius
Open auto-fix PR
Medium
External dependency or human decision needed
Open rolling issue
Lower
Schema or syntax breakage on PR
Block merge with clear error
Last resort
Rolling issues auto-close when the underlying finding clears. The pattern is implemented in operations/scripts/interfaces/governance/lib/rolling-issue.js.
Every dispatcher has a matching local script that can run the same pipeline without a CI trigger. The workflow is the CI orchestrator; the script is the portable logic. Three requirements:
Every script accepts --dry-run (preview without writing)
Secrets-dependent scripts degrade gracefully when secrets are absent
The actions-library page documents the local invocation command
This makes the repo testable by any contributor, anywhere, before pushing.
Every governance rule fires at the earliest possible layer. Detection at later layers is a fail-safe, not the primary mechanism. A rule that only catches violations on schedule is a rule that lets violations land.The five enforcement layers, from earliest to latest:
Layer
Trigger
Owner
What it does
1. Write time
Claude PreToolUse hook
pre-tool-guard.js and siblings in operations/scripts/dispatch/governance/
Blocks Edit/Write before the file lands. Allowlist, render gate, em-dash sanitiser, frontmatter sanitiser.
2. Commit time
.githooks/pre-commit
Pre-commit hook
Rejects unauthorised paths and structural violations in the staged diff. Works for contributors not running Claude Code.
3. PR time
dispatch-{concern}.yml PR job → dispatch-{concern}-check.js meta
PR validator pipelines
Server-side check on every PR. Fails the check on violations. Posts advisory comment for soft gates.
4. Post-merge
dispatch-{concern}.yml post-merge job → dispatch-{concern}-sync.js or dispatch-{concern}-generate.js meta
Post-merge remediators and generators
If something landed despite layers 1-3 (direct push, hook bypassed), auto-archive or auto-fix on merge.
5. Schedule
dispatch-{concern}.yml scheduled job → dispatch-{concern}-scan.js meta
Scheduled audit pipelines
Last-resort drift scan with rolling issue. Fail-safe only – anything caught here represents an upstream gate that failed.
Every dispatcher this framework targets must declare which layer it serves and confirm that earlier layers exist for the same rule. A PR validator without a write-time hook is acceptable only when the violation cannot be detected before the file is written. A scheduled scan without a PR validator is a governance gap, not a design.
No commit of files that do not belong. Every folder hosting repo-influencing files declares an explicit allowlist enforced through the five-layer prevention chain above.Allowlist rules:
Explicit, closed list (exact paths or globs)
Stored at {folder}/.allowlist for portability
One entry per line, documented purpose per entry
Registered in operations/governance/config/repo-governance-surfaces.json (D-ACT-10)
Each governed folder has the full triplet wired: dispatch-folder-allowlist.js --mode pr (layer 3), --mode post-merge (layer 4), --mode scheduled (layer 5), plus the pre-tool-guard.js extension for layer 1 and the pre-commit gate for layer 2. The allowlist files themselves are governed by the same chain – they are the source of truth, not generated.
Pattern: type-concern-verb-name.ymlExample: integrator-maintenance-update-contract-addresses.ymlThe verb is one of a closed enum of 11: update, generate, check, scan, repair, dispatch, label, index, intake, close, assign.The name segment describes what the workflow does, not how it is implemented. If someone unfamiliar with the repo cannot guess the purpose from the filename, the name is bad.In the four-tier architecture, action workflows use dispatch-{concern}.yml (verb is dispatch, name is the concern). Pre-existing single-script workflows that have not yet been consolidated may still use type-prefixed names (e.g. integrator-maintenance-update-contract-addresses.yml) until they fold into their concern’s action.
18 decisions constrain the framework. Read the full text in .github/workspace/decisions-log.mdx and .github/workspace/design/governance/design-overview.md.
ID
Topic
Effect
D-ACT-01
interface is the 7th type
Event-reactive workflows are not pipeline-shaped
D-ACT-02
P5-auto distinct from P5
Read-write vs read-only have different error handling
D-ACT-03
Data-feed consolidation pattern
Many similar feeds collapse into one matrix dispatcher
D-ACT-04
Naming convention
type-concern-verb-name.yml with closed verb enum
D-ACT-05
7 concerns
Replaces earlier 4-concern model
D-ACT-06
Scripts live in operations/scripts/
No business logic in .github/scripts/
D-ACT-07
automation renamed integrator
Names what it does, not what it is
D-ACT-08
Workflows are dispatchers
Type reflects the script
D-ACT-09
Output location conventions
Reports, data, indexes, config each have a fixed home
D-ACT-10
Unified governance registry
operations/governance/config/repo-governance-surfaces.json is canonical
Historical 47-workflow target. Current target is 6 actions + composable dispatcher tiers. Kept for design history.
.github/workspace/framework-canonical.md
Working spec
Deeper internal detail. Synced from this published doc.
.github/workspace/outcomes.md
Reference only
Visual maps and Mermaid diagrams. Snapshot in time.
The current consolidation execution plan lives at /Users/alisonhaire/.claude/plans/soft-gliding-falcon.md for the active session. When the plan completes, its outcomes fold into this framework and the plan is archived.
