Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / github-coordination-and-policy

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.

CommandCoordination purpose
claimAssign an available open epic and start active work.
decomposeReconcile task checkboxes and issue references from the epic body.
validateCheck that recorded dependencies are closed.
reviewRecord requested, approved, or changes-requested review.
publishComplete validation and review gates, then mark the epic published.
unblockMove blocked epics to ready when all dependencies are closed.
syncReconcile 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, and publish gates. 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 gh command 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

TriggerConsequenceGuard
Coordination JSON in an issue body is malformedThe 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 timeBoth can pass the read-and-check step and write a claim.Serialize claim work outside this command.
A dependency is missing from the issue scanValidation 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 approvedpublish 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 invalidPolicy loading fails before coordination starts.Keep the policy a JSON object with a non-empty epic label.
A repository or issue number is malformedThe 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 JSONReads and writes fail at the GitHub boundary.Check gh access and repository credentials before running commands.
A moderation policy threshold or notification login is invalidThe 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 limitExcess 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 tokenClosure 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 headUntrusted 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 eventsA 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 identityAccount 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 combinationCompatibility 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 laneA 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 pathA 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 jobCross-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 gatesThe 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 matchThe 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 publicationThe 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 artifactThe 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 releaseOne 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

FileWhy to read it
scripts/github-coordination.jsShows the public coordination command surface, options, output modes, and dispatch.
scripts/…/actions.jsShows how each coordination action changes the shared delivery state.
scripts/…/policy.jsDefines policy defaults and the rules for loading repository configuration.
config/github-native-coordination.jsonShows the active schema marker, labels, gates, branch model, and project setting.
scripts/…/gh-api.jsDefines the GitHub read and write boundary used by the actions.
scripts/…/parsing.jsDefines the issue-body state contract and task/dependency extraction.
scripts/…/state.jsDefines state defaults, label projection, review comments, and dependency checks.
scripts/…/store.jsDefines the local work-item projection of a GitHub epic.
.github/pr-burst-policy.jsonDefines the active pull request burst, open-PR, denied-account, and notification limits.
.github/PR_MODERATION.mdExplains the pull request moderation policy, activation requirements, recovery, and security boundary.
scripts/…/pr-burst-guard.jsApplies metadata-based moderation and separates burst enforcement from the open-PR cap.
.github/…/pr-burst-guard.ymlDefines the trusted event trigger, permissions, queue, checkout, and moderation secret boundary.
.github/…/ci.ymlShows the repository-wide quality gates, compatibility matrix, focused package-manager lanes, artifact checks, and security limits.
.github/…/release.ymlShows the tag-triggered release checks, artifact handoff, npm publication, and GitHub release creation.
.github/…/reusable-release.ymlShows the callable and manual release entry point and its shared publication guards.
.github/…/reusable-test.ymlShows the shared test interface for callers that choose a runtime and package manager.
.github/…/taste-skills.ymlShows the focused offline checks for taste-related skills and tests.