GitHub coordination and policy
GitHub coordination turns an epic issue into a shared delivery record. It keeps ownership, dependencies, validation, review, labels, and publication state aligned between GitHub and the local work-item store. This page complements orchestration and autonomous workflows, workflow execution and worktrees, work-item loops and epics, and coordination inventory and goals.
Coordination boundary
The coordination boundary is the part of delivery work that must be visible to more than one worker or system. GitHub is the shared source for epic state. The local store is a work-item projection that helps other workflows use the same state without replacing the GitHub record.
Epic records
An epic record is an open GitHub issue that represents a delivery unit. Its body carries a marked coordination state, while labels provide a quick state signal and comments provide an append-only action trail. The record can also describe task checkboxes and issue-number dependencies.
References: scripts/…/state.js• L14-35 scripts/…/parsing.js• L13-28 scripts/…/state.js• L137-155
Coordination projections
The local projection gives each GitHub epic a stable work-item identity. It maps GitHub states to local states such as open, in-progress, blocked, needs-review, and done, while retaining the full coordination state as metadata. A store can be disabled when only GitHub changes are needed.
References: scripts/…/store.js• L10-18 scripts/…/store.js• L19-47 scripts/…/state.js• L157-173
Coordination lifecycle
The command set moves an epic through claim, decomposition, validation, review, and publication. Sync and unblock keep records aligned as related issues change.
Command surface
The scripts/github-coordination.js command is the operator entry point. It requires a repository in owner/repo form and supports human-readable or JSON output. The --dry-run option previews changes without writing to GitHub or the local store.
| Command | Coordination purpose |
|---|---|
claim | Assign an available open epic and start active work. |
decompose | Reconcile task checkboxes and issue references from the epic body. |
validate | Check that recorded dependencies are closed. |
review | Record requested, approved, or changes-requested review. |
publish | Complete validation and review gates, then mark the epic published. |
unblock | Move blocked epics to ready when all dependencies are closed. |
sync | Reconcile eligible GitHub issues and local snapshots. |
References: scripts/github-coordination.js• L21-46 scripts/github-coordination.js• L118-152
Epic progression
The normal path starts with an available epic and ends with a published epic. Each action updates the marked body state and coordination labels. Actions that need a shared record also write a comment so that collaborators can see what changed.
This diagram shows the main delivery path and the dependency-driven return from blocked work.
flowchart LR
A[Available epic] --> B[Claimed]
B --> C[Decomposed]
C --> D[Validated]
D --> E[Review approved]
E --> F[Published]
B --> G[Blocked]
C --> G
G -->|Dependencies closed| D
E -->|Changes requested| B
claim rejects closed issues and issues already marked claimed. publish runs validation again and requires review approval when the policy enables review. This makes publication a gate rather than a simple label change.
References: scripts/…/actions.js• L38-81 scripts/…/actions.js• L147-233 scripts/…/actions.js• L236-267 scripts/…/state.js• L209-235
State reconciliation
sync finds epics by the configured epic label and also finds issues that contain the coordination marker. The second search lets sync recover an epic after label drift. It then restores the marked body state, plans label changes, and updates the local projection unless dry-run is active.
References: scripts/…/actions.js• L83-145 scripts/…/state.js• L91-130
GitHub adapters
The GitHub adapters keep command logic separate from the external gh command. They normalize repository and issue inputs, read the issue data needed for coordination, and apply body, label, and comment changes through one boundary.
GitHub API adapter
The API adapter validates repository and issue-number inputs before it reads or changes issues. It reads and lists issue data and writes issue bodies, labels, assignees, and comments through gh, while returning structured JSON for reads. A configured command shim exists for isolated tests, but it is not a production replacement for gh.
References: scripts/…/gh-api.js• L5-21 scripts/…/gh-api.js• L61-79 scripts/…/gh-api.js• L83-167
Action adapters
Action adapters combine a read, a state check, a state transition, and one or more GitHub writes. They also pass the resulting state to the local projection. This gives each command the same contract: inspect current state first, derive the next state, then publish the shared record.
References: scripts/…/actions.js• L46-80 scripts/…/actions.js• L193-234 scripts/…/actions.js• L310-359
Policy evaluation
Policy evaluation defines which labels and gates the coordination actions use. The loader takes a repository-local policy when present, fills omitted sections from safe defaults, and rejects malformed top-level data or an empty epic label.
Policy sources
The default policy file is config/github-native-coordination.json. A command may provide another file with --config. If no file exists, the command uses the built-in policy. Object sections are merged with defaults so a small policy change does not need to repeat every label or field name.
References: scripts/…/policy.js• L6-48 scripts/…/policy.js• L50-94 scripts/github-coordination.js• L165-178
Policy gates
The policy controls the labels for epic and coordination states. It also declares whether review and validation are required, whether work uses epic-only branches, and whether a project projection is enabled. The action layer uses these values to choose labels, set review defaults during claim, and block publication until its gates pass.
References: config/github-native-coordination.json• L2-37 scripts/…/state.js• L91-109 scripts/…/actions.js• L56-63 scripts/…/actions.js• L193-214
Native coordination configuration
Native coordination stores the shared state in GitHub issue content instead of requiring a separate coordination service. The configuration gives that state a schema marker and names the labels and project fields that other systems must recognize.
Coordination schema
The ecc.github.coordination.v1 schema is enclosed by the ecc-coordination:start and ecc-coordination:end markers. The enclosed JSON carries the epic kind, status, owner, branch, validation, review, project state, dependencies, tasks, labels, and action timestamps. Body merging replaces only this marked section, so the issue narrative remains available to collaborators.
References: config/github-native-coordination.json• L2-3 scripts/…/parsing.js• L13-28 scripts/…/parsing.js• L79-117
Label projection
Labels provide the fast filter used by people and automation. Every coordinated epic keeps the epic and synced labels, then receives a state label for availability, claim, readiness, blockage, validation, review, or publication. Stale coordination labels are removed so the label set describes the current state.
References: config/github-native-coordination.json• L4-15 scripts/…/state.js• L91-109 scripts/…/actions.js• L31-36
Branch and project policy
The default branch model treats the epic as the coordination unit and does not create task branches. Project integration is declared but disabled by default. State still carries a project projection so a repository can enable that integration without changing the core GitHub record shape.
References: config/github-native-coordination.json• L24-37 scripts/…/state.js• L176-184 scripts/…/store.js• L26-31
GitHub Actions policy
GitHub Actions provides the repository-wide checks that support collaborative delivery. It also applies repository policy to pull request intake and prevents duplicate or unsafe workflow runs.
Pull request moderation
The PR Burst Guard protects review capacity by applying metadata-only rules when a pull request is opened or reopened. It counts creations in a rolling window, limits each author’s open pull requests, and treats trusted repository contributors as exempt from burst and denied-account checks while keeping the open-PR cap in force.
The guard closes excess pull requests and locks those above the burst threshold. It can also block a denied account or a severe burst when an owner-scoped token is configured. It records one bot-authored issue per author and day, while keeping the decision based on stable author IDs and creation data rather than titles, bodies, or patch quality.
The workflow queues up to 100 pending events for each author. Its burst scan also handles delayed or out-of-order GitHub data, so queued events do not rely on one exact event order.
This diagram shows how an incoming pull request moves through the moderation policy before normal review continues.
flowchart LR
A[Opened or reopened PR] --> B[Read author and creation metadata]
B --> C{Trusted contributor?}
C -->|Yes| D[Apply open-PR cap]
C -->|No| E[Check burst and denied-account rules]
E --> F[Close and lock excess PRs]
E --> G[Alert maintainers or block owner-scoped account]
D --> H[Continue with normal review]
F --> H
G --> H
References: .github/PR_MODERATION.md• L1-37 .github/PR_MODERATION.md• L39-69 .github/…/pr-burst-guard.yml• L1-40 .github/pr-burst-policy.json• L1-8 scripts/…/pr-burst-guard.js• L170-227
Continuous integration coverage
The main CI workflow checks the project across supported operating systems, Node.js versions, and package managers. Its test matrix separates full-suite lanes from focused package-manager lanes, which keeps compatibility coverage while avoiding repeated full runs. It also validates repository components, exercises the Python package, scans dependencies, measures coverage, and runs lint checks.
The workflow uses Linux across the supported Node.js lines, current Node.js on Windows and macOS, and focused npm, pnpm, Yarn, and Bun lanes where package-manager behavior matters. Independent jobs pack one installer artifact, test that exact artifact on three operating systems, validate repository components and generated profiles, run Python and fixture checks, scan security, measure coverage, and run lint. Concurrency cancellation and read-only permissions limit duplicate or unsafe runs.
References: .github/…/ci.yml• L1-49 .github/…/ci.yml• L51-213 .github/…/ci.yml• L217-283 .github/…/ci.yml• L285-355 .github/…/ci.yml• L357-596
Release verification and publication
The release workflows turn a version tag into a checked and traceable publication. The tag-triggered workflow in .github/…/release.yml handles normal releases, while .github/…/reusable-release.yml accepts an explicit tag from another workflow or a manual run.
Both entry paths require the tag to point to the current main commit. They also check the signed tag, exact-SHA CI gates, package version, release metadata, and reviewed release notes before they create one package artifact with a checksum. The tag-triggered path additionally checks VERSION and the current pi/core profile. The lifecycle stage installs the exact artifact on Linux, macOS, and Windows before the publish stage can use it.
This diagram shows how release evidence moves from a tag to publication.
flowchart LR
A[Version tag or workflow call] --> B[Verify commit, tag, gates, and metadata]
B --> C[Pack and checksum one artifact]
C --> D[Install check on three operating systems]
D --> E[Recheck artifact and tag]
E --> F[Publish npm package and GitHub release]
Publication is guarded against an already published but different package. The workflow checks registry integrity before reuse, verifies the downloaded artifact again, and binds the publish check to the commit that passed the release gate. It publishes with provenance when needed, waits for registry visibility, and promotes the verified version to the correct npm distribution tag. Prerelease tags use next and are not marked as the latest GitHub release; stable tags use latest and can become latest. The reusable path repeats the tag check from the verified source and sets the GitHub release tag from its input.
References: .github/…/release.yml• L1-25 .github/…/release.yml• L34-167 .github/…/release.yml• L169-196 .github/…/release.yml• L198-295 .github/…/reusable-release.yml• L1-38 .github/…/reusable-release.yml• L41-165 .github/…/reusable-release.yml• L167-194 .github/…/reusable-release.yml• L196-288
Reusable test contract
The reusable test workflow exposes one shared test contract for callers that need a chosen operating system, Node.js version, or package manager. Its defaults provide a normal Ubuntu, Node 20, npm run. The workflow installs dependencies in a script-free mode, runs the common test entry point, and uploads test data when the run fails.
References: .github/…/reusable-test.yml• L1-26 .github/…/reusable-test.yml• L28-98
Focused taste checks
The taste workflow gives the taste application and distillation skills a focused check path. It runs only when those skills, their taste tests, or the workflow changes. Its offline job uses Python 3.12, installs local media dependencies, builds and installs the reusable engine as a wheel, tests the canonical engine and original creative scripts, checks a packaged fixture, and confirms that the command-line entry point is available.
References: .github/…/taste-skills.yml• L1-20 .github/…/taste-skills.yml• L21-44
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the coordination schema marker, body parser, body renderer, and body merger aligned. A marker or shape change can make existing GitHub issues unreadable.
- Keep policy label names aligned with the state-to-label mapping and stale-label cleanup. A renamed label can leave old state labels on issues or hide epics from
sync. - Keep review and validation policy changes aligned with the
claim,validate,review, andpublishgates. A relaxed setting must not leave publication blocked by an old assumption. - Keep work-item status mapping aligned with the states written to GitHub. A new GitHub state can otherwise appear as the wrong local status.
- Keep dependency parsing and dependency lookup limits aligned. An issue outside the scan range can look open even when it is closed.
- Keep repository and issue-number normalization aligned with every GitHub adapter call. A stricter input rule can reject values that a caller still formats or passes through.
- Keep the
ghcommand arguments and any isolated command shim contract aligned. The API adapter depends on the exact issue fields returned by reads. - Keep the burst policy thresholds, denied IDs, notification logins, and open-PR cap aligned with the moderation script and its operator guide. A policy-only change can alter who is closed or blocked.
- Keep the moderation workflow's trusted-branch checkout, event types, permissions, concurrency queue, and secret separation aligned. A change can either execute untrusted pull request code or leave events unchecked.
- Keep burst actions and open-PR cap actions distinct. Burst excess is locked and can trigger blocking, while cap excess is closed with a reversible contributor notice.
- Keep the per-author moderation queue limit aligned with the full burst scan. A queue change can alter when delayed events are handled.
- Keep the CI full-suite and package-manager lane scopes aligned with the tests that read the package-manager setting. A new compatibility-sensitive test can otherwise run only in the wrong lane.
- Keep the main CI matrix, the reusable workflow inputs, and each package-manager install path aligned. A supported lane can otherwise pass through one workflow and fail through the other.
- Keep focused workflow path filters aligned with the skills and tests they protect. A new input path can bypass the taste checks if it is not included.
- Keep packed-artifact output names and digest outputs aligned with the cross-platform lifecycle job. A changed artifact contract can make install checks use the wrong package.
- Keep the release verify outputs aligned with the lifecycle and publish jobs. A changed package filename, checksum, version, or registry tag can make later jobs verify or publish the wrong release.
- Keep the tag-triggered and reusable release workflows aligned. A fix in one release entry path can leave manual or called releases without the same version, metadata, artifact, or publication guard.
- Keep release-gate source binding aligned with each trigger contract. The tag-triggered path binds the event commit to the verified commit, while the reusable path must recheck the caller-provided tag from the verified source.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Coordination JSON in an issue body is malformed | The state cannot be read reliably. The command falls back to default state after a warning. | Preserve the marked JSON block and use sync after repairing it. |
| Two callers claim the same open epic at the same time | Both can pass the read-and-check step and write a claim. | Serialize claim work outside this command. |
| A dependency is missing from the issue scan | Validation does not count it as closed. The epic cannot publish or unblock. | Use a scan limit that includes every dependency and check cross-repository references separately. |
| Review is required but not approved | publish stops before changing the epic to published. | Run review with approval after the required review work. |
| The configured epic label is empty or the policy JSON is invalid | Policy loading fails before coordination starts. | Keep the policy a JSON object with a non-empty epic label. |
| A repository or issue number is malformed | The API adapter rejects the request before it reaches GitHub. | Pass an owner/repo value and a positive safe integer issue number. |
| The GitHub CLI is unavailable or returns invalid JSON | Reads and writes fail at the GitHub boundary. | Check gh access and repository credentials before running commands. |
| A moderation policy threshold or notification login is invalid | The PR guard fails before it makes a moderation decision. | Keep the policy values positive and keep notification names in the accepted GitHub login form. |
| An outsider exceeds the burst or open-PR limit | Excess pull requests are closed. Burst excess is locked and can alert or block the account. | Review the bot alert and use the policy file and creation metadata as the decision record. |
| A severe burst has no owner-scoped block token | Closure and alerting still run, but account blocking is unavailable and the job fails. | Configure PR_MODERATION_BLOCK_TOKEN only through repository Actions secrets. |
| The moderation workflow checks out a pull request head | Untrusted pull request content could run in a privileged pull_request_target job. | Check out the trusted default-branch SHA and use sparse checkout for the policy and guard script. |
| An author's moderation queue reaches 100 pending events | A pull request event can remain unchecked by the cap guard. | Keep the queue limit in view and use the guard's full open-PR scan when a later event runs. |
| Repository ownership changes from a personal account or the block token uses another identity | Account blocking fails even though repository moderation can continue. | Verify the owner identity and provide a separate design for organization-level blocking. |
| A CI matrix lane uses an unsupported package-manager or runtime combination | Compatibility coverage becomes false or the lane fails before tests run. | Keep matrix entries, lane scopes, and setup/install branches in sync. |
| A package-manager-sensitive test is not selected by the focused lane | A package-manager regression can pass because only the full npm lane exercises it. | Keep the package-manager test selection marker and matrix scope aligned. |
| A focused workflow omits a changed skill or test path | A pull request can change taste behavior without running its dedicated checks. | Update the workflow path filters with each protected input path. |
| The packed installer name or checksum output does not match the lifecycle job | Cross-platform install validation cannot download or verify the intended artifact. | Preserve the pack-to-download output contract when changing release packaging. |
A release tag does not point to the current main commit or does not pass the signed-tag and CI gates | The release verify stage stops before an artifact can be published. | Create the tag from the intended main commit and keep the required checks and tag protection in place. |
The release tag, package version, VERSION, or reviewed notes do not match | The release is rejected before publication or uses no release body. | Update the release metadata and reviewed notes together with the version tag. |
| The packed artifact changes between verification and publication | The publish stage stops instead of sending an untested or altered package to npm. | Pass the verified artifact outputs through the lifecycle and publish jobs and preserve checksum checks. |
| The npm registry cannot confirm an existing or newly published artifact | The workflow cannot prove that the registry package is the tested candidate. | Treat registry lookup errors as failures and allow time for the post-publish integrity check. |
| A called or manual release uses behavior that differs from the tag-triggered release | One release path can skip a version, metadata, source, or publication guard. | Keep the two workflows aligned where their trigger contracts allow, and preserve the reusable path's explicit tag checks. |
Key files
| File | Why to read it |
|---|---|
| scripts/github-coordination.js | Shows the public coordination command surface, options, output modes, and dispatch. |
| scripts/…/actions.js | Shows how each coordination action changes the shared delivery state. |
| scripts/…/policy.js | Defines policy defaults and the rules for loading repository configuration. |
| config/github-native-coordination.json | Shows the active schema marker, labels, gates, branch model, and project setting. |
| scripts/…/gh-api.js | Defines the GitHub read and write boundary used by the actions. |
| scripts/…/parsing.js | Defines the issue-body state contract and task/dependency extraction. |
| scripts/…/state.js | Defines state defaults, label projection, review comments, and dependency checks. |
| scripts/…/store.js | Defines the local work-item projection of a GitHub epic. |
| .github/pr-burst-policy.json | Defines the active pull request burst, open-PR, denied-account, and notification limits. |
| .github/PR_MODERATION.md | Explains the pull request moderation policy, activation requirements, recovery, and security boundary. |
| scripts/…/pr-burst-guard.js | Applies metadata-based moderation and separates burst enforcement from the open-PR cap. |
| .github/…/pr-burst-guard.yml | Defines the trusted event trigger, permissions, queue, checkout, and moderation secret boundary. |
| .github/…/ci.yml | Shows the repository-wide quality gates, compatibility matrix, focused package-manager lanes, artifact checks, and security limits. |
| .github/…/release.yml | Shows the tag-triggered release checks, artifact handoff, npm publication, and GitHub release creation. |
| .github/…/reusable-release.yml | Shows the callable and manual release entry point and its shared publication guards. |
| .github/…/reusable-test.yml | Shows the shared test interface for callers that choose a runtime and package manager. |
| .github/…/taste-skills.yml | Shows the focused offline checks for taste-related skills and tests. |