Skip to content

Repository navigation

Converge plugin guidance on team policy #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acgxv merged 1 commit into from
Sep 15, 2026
Merged

Converge plugin guidance on team policy #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
## Repository

This repository publishes ACG Box engineering standards as small Codex plugins.
Start with [OpenWiki quickstart](openwiki/quickstart.md). Read the owning plugin
skill and its direct references before you change runtime guidance.
Use [OpenWiki quickstart](openwiki/quickstart.md) for repository navigation. Read
the owning skill and relevant canonical sections when changing runtime guidance.

## Authority

Expand All @@ -25,6 +25,8 @@ skill and its direct references before you change runtime guidance.
skills, and `agents/openai.yaml`.
- Keep one canonical standard. Link to it instead of copying its rules into
OpenWiki or the README.
- Skills supply team policy, non-obvious constraints, and completion criteria.
Leave general implementation, troubleshooting, and test selection to the model.
- Run `cargo make check`, the Plugin Creator validator, and the Skill Creator
validator before a ready claim.
- For durable workflow or layout changes, update source authority first. Then run
Expand Down
21 changes: 4 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,29 +13,16 @@ Small, reusable ACG Box engineering standards.

### GitHub Settings

`gh-settings` audits GitHub Enterprise, organization, and repository governance
without changing it by default. It puts each enforceable control at the highest
supported scope, separates central defaults from repository residuals, and shows the
exact planned fields or Web UI controls before an authorized reconciliation. It also
prevents implicit paid-product enablement and reads every changed setting back.
Its merge-commit-only baseline keeps merge commits enabled, disables squash and
rebase, and rejects conflicting linear-history rules.
Organization-wide mode is central-first and can require zero repository-owned
rulesets. Repository-scoped mode audits parent state but never widens authority to
change it.
`gh-settings` audits or reconciles GitHub governance against an authorized profile,
with central organization controls and repository-scoped operation.

Read the [canonical GitHub settings standard](plugins/gh-settings/skills/sync/references/standard.md)
or invoke `$gh-settings:sync` after installation.

### ACG Release

`acg-release` is the organization release-standard owner for repositories whose
canonical GitHub owner is `acg-box`. Its only current skill audits, migrates,
normalizes, operates, and verifies Developer ID releases for Sparkle-enabled macOS
ZIP applications. It stops as not applicable for repositories outside `acg-box/*`
and does not claim support for DMG, PKG, or non-Sparkle workflows. Future release
types get separate skills only after they have real evidence and an independent
owner contract.
`acg-release` guides Developer ID-notarized Sparkle macOS ZIP releases for
repositories whose canonical GitHub owner is `acg-box`.

Read the [canonical ACG Box macOS release standard](plugins/acg-release/skills/macos/references/standard.md)
or invoke `$acg-release:macos` after installation.
Expand Down
148 changes: 18 additions & 130 deletions openwiki/acg-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,133 +15,21 @@ openwiki:

# ACG Release: macOS

## Runtime And Ownership Boundary

`plugins/acg-release/` is the complete installed runtime for ACG Box organization
release standards. It currently contains one `macos` skill, its invocation metadata,
and one canonical Sparkle ZIP release standard. It has no executable, hook, app, MCP
server, credential, network client, template, or writable state.

The plugin is extensible by release type, but only after a real release type has an
independent owner contract and evidence. Do not add empty skills, compatibility
aliases, or a generic root standard. The only current public invocation is
`$acg-release:macos`.

The installed plugin guides repository work. GitHub Actions runs only the target
repository's checked-in adapter and never loads the plugin.

## Applicability Gate

The `macos` skill resolves the target repository's canonical GitHub owner before it
audits or changes release behavior. It continues only for `acg-box/*`. A repository
outside `acg-box` is not applicable: the skill must not audit it toward adoption,
change it, operate or verify its release under the standard, or inspect or apply the
ACG Box certificate, notary, Sparkle-key, secret, environment, or publisher topology.
An unresolved canonical owner is an applicability gap, not permission to assume
membership.

```mermaid
flowchart TD
marketplace["marketplace entry"] --> plugin["acg-release manifest"]
plugin --> skill["macos skill"]
skill --> ownerGate{"canonical owner = acg-box?"}
ownerGate -->|no or unresolved| stop["stop: not applicable"]
ownerGate -->|yes| scopeGate{"Sparkle macOS ZIP?"}
scopeGate -->|no| stop
scopeGate -->|yes| standard["canonical macOS standard"]
standard --> adapter["target repository adapter"]
adapter --> workflow["repository-owned release workflow"]
```

This flow keeps plugin discovery, organization applicability, distribution scope,
target identity, and executable release work as separate owners. The skill loads
the detailed standard only after both applicability gates pass.

## Release Policy And Adapter

The current skill supports one regular Sparkle-enabled macOS app in a GitHub
Release ZIP. Production requires Developer ID Application signing, Hardened Runtime,
secure timestamps, Apple notarization, app stapling, strict code-signature checks,
Gatekeeper acceptance, a final post-stapling ZIP, Sparkle signature and appcast,
checksum, and draft-first GitHub publication. An Apple Development, Personal Team,
timestamp-free, unnotarized, or Open Anyway path is migration drift.

The plugin contains no Apple Team ID, certificate suffix, product identity, or
Sparkle public key. Each applicable target repository owns its paid Team ID,
expected Developer ID identity selector, app and bundle identity, versions, assets,
feeds, entitlements, Sparkle pin and public key, build commands, and smoke tests.

The skill does not support DMG, PKG, Mac App Store, bare-app, non-Sparkle, or
multi-product distribution. A future release type needs a separate skill only when
its owner contract exists.

## Release And Trust Flow

One immutable annotated stable tag binds the source. The workflow runs Linux source
validation, then macOS native test, build, signing, notarization, stapling, and
packaging, then a protected Linux publisher. The notarization upload ZIP is temporary
and never public. Apple must return an `Accepted` result and log before the app is
stapled. Only then does the workflow create the final ZIP and bind its exact bytes to
the Sparkle appcast signature and checksum.

The publisher uses a secret-free protected `release` environment and the ephemeral
workflow token with `contents: write`; other jobs default to `contents: read`.
Publication is draft-first and non-idempotent. Final acceptance requires public
metadata and downloaded-byte verification. For uncertain responses, use
[bounded GitHub reconciliation](../plugins/acg-release/skills/macos/references/standard.md#bounded-github-reconciliation),
which owns recovery and reporting of unresolved publication state.

Shared Developer ID and team App Store Connect API-key material uses unambiguous
organization-secret names. Conformance requires effective target access and no
lower-scope shadowing. Organization visibility `all` is allowed, while a tighter
`selected` scope is also conforming when it grants the repository access. Each
application keeps its own Sparkle private key and checks in its public key.

Apple certificate creation or rotation, Sparkle-key rotation, secret mutation,
repository writes, tag push, environment approval, public Release mutation, and app
installation remain separate authorization boundaries. The release contract never
rotates the Developer ID certificate and Sparkle trust key in the same update.

## Public-Surface Change Recipe

A behavior change starts in `plugins/acg-release/skills/macos/SKILL.md` or its
canonical standard. Keep these surfaces synchronized:

- `.agents/plugins/marketplace.json` discovers `acg-release` at
`./plugins/acg-release`.
- `plugins/acg-release/.codex-plugin/plugin.json` owns the organization scope,
plugin metadata, and `./skills/` entrypoint.
- `plugins/acg-release/skills/macos/agents/openai.yaml` owns the invocation label
and default prompt.
- `VERSION` and every plugin manifest use the same repository release version.
- `PRIVACY.md` owns the shared instruction-only privacy boundary.

There is no generated, bundled, or published mirror in this repository. Validate
the internal skill and marketplace-resolved plugin boundary separately. Do not add
a generic workflow, signing script, or future skill until evidence gives it one
stable interface and validation owner.

## Validation

Run the Plugin Creator validator, Skill Creator validator, Plugin Eval, and
`cargo make check` when this plugin changes. Review the physical runtime file set:
only the manifest, `macos` skill, invocation metadata, and canonical reference
belong in the plugin.

Forward tests must show three routing outcomes: an applicable legacy `acg-box`
Sparkle ZIP workflow is migration drift; an applicable Developer ID-notarized
fixture is preserved; and an outside-owner repository or a DMG, PKG, or non-Sparkle
request stops without adoption guidance or ACG Box topology.

These checks prove checked-in guidance and installability only. They do not prove a
usable local Developer ID identity, notary credentials, hosted runner, protected
environment, GitHub publication, public bytes, Gatekeeper behavior, or installed
app.

## Ownership Relationships

The [marketplace entry](../.agents/plugins/marketplace.json) discovers this plugin;
the [operations guide](operations.md) validates its installable boundary. The
[canonical macOS standard](../plugins/acg-release/skills/macos/references/standard.md)
is the release authority, while this page explains repository structure and change
impact.
`plugins/acg-release/` contains the installed manifest, `macos` skill, invocation
metadata, and canonical release standard. It is instruction-only; target
repositories own executable release workflows and product-specific adapters.

Use the [skill](../plugins/acg-release/skills/macos/SKILL.md) for applicability
and task scope. Use the [standard](../plugins/acg-release/skills/macos/references/standard.md)
for release requirements. Its sections cover source and workflow policy, secret
topology, signing, final assets, publication, trust-root changes, and acceptance.
Read the sections relevant to focused work, or the whole standard for a complete
release audit, migration, or operation.

Change runtime policy in those source files. The manifest and
`agents/openai.yaml` describe the public invocation `$acg-release:macos`; the
marketplace resolves the plugin at `./plugins/acg-release`. Keep those surfaces
consistent when changing discovery or applicability.

See [Operations](operations.md) for validation and installation. This wiki page
provides repository navigation; release policy remains in the canonical standard.
102 changes: 17 additions & 85 deletions openwiki/gh-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,88 +15,20 @@ openwiki:

# GitHub Settings

## Runtime Boundary

`plugins/gh-settings/` is the complete installed runtime. It contains one `sync`
skill, invocation metadata, and one canonical GitHub governance standard. It has no
executable, hook, app, MCP server, credential, network client, or writable state.

The canonical standard owns operating-mode selection, target binding, central-first
classification, exact drift preview, public and private security baselines, mutation
authority, paid-product and automatic dependency submission billing gates, ruleset
migration or retirement safety, UI fallback, and authoritative readback. It
distinguishes an attached or enforced parent configuration from an unattached
catalog entry. Automatic dependency submission is a separate GitHub Actions workload,
not a Dependabot runner setting: supported manifests, Actions availability, runner
choice, and billing must be checked independently. Do not copy these rules into
OpenWiki.

```mermaid
flowchart TD
marketplace["marketplace entry"] --> plugin["plugin manifest"]
plugin --> skill["sync skill"]
skill --> standard["canonical GitHub governance standard"]
standard --> currentDocs["current official GitHub docs"]
standard --> target["Enterprise, organization, and repository evidence"]
```

## Ownership And Modes

The plugin owns GitHub governance audit and explicitly authorized reconciliation.
Organization-wide mode is central-first: it selects Enterprise enforcement,
organization enforcement, a central default, or a true repository residual in that
order. When the selected profile requires zero repository-owned rulesets, a nonzero
count on any repository fails acceptance.

Repository-scoped mode binds one exact repository. It audits parent rulesets,
defaults, policies, and security configurations but keeps all parent state
read-only. A request for one repository never authorizes organization or Enterprise
mutation.

The merge-commit-only baseline keeps the three repository merge toggles as residual
state and uses a parent pull-request rule where GitHub supports central allowed-method
enforcement. The standard requires a complete conflict check for linear-history
rules before activation.

For security baselines, automatic dependency submission gets its own preview and
readback row. Enable it only after dependency graph, GitHub Actions, supported
ecosystem, runner, and billing evidence is bound; prefer free Dependabot graph jobs
where they take precedence. Private or internal repositories require explicit
acceptance of Actions usage and possible billing.

A local ruleset in a zero-local profile is either migrated with equivalent parent
readback or explicitly retired after the user accepts the protection delta. The
workflow does not invent a team, role, app, or preservation adapter for semantics
that the approved profile says to remove.

For stale previews or uncertain writes, use the canonical
[reconciliation rules](../plugins/gh-settings/skills/sync/references/standard.md#reconciliation).
That section owns bounded readback and the conditions for resuming writes.

The public invocation is `$gh-settings:sync`.

## Public-Surface Change Recipe

A behavior change starts in `skills/sync/SKILL.md` or the canonical standard. Keep
these surfaces synchronized:

- `.agents/plugins/marketplace.json` owns discovery at `./plugins/gh-settings`.
- `.codex-plugin/plugin.json` owns plugin metadata and the `./skills/` entrypoint.
- `agents/openai.yaml` owns the invocation label and default prompt.
- `VERSION` and every plugin manifest use the same repository release version.
- `PRIVACY.md` owns the shared instruction-only privacy boundary.

GitHub APIs, UI controls, plans, and billing boundaries can change. The runtime
standard therefore requires current official documentation before live work instead
of treating a checked-in endpoint example as permanent authority.

## Validation

Run the Plugin Creator validator, the Skill Creator validator, and
`cargo make check`. Review the physical runtime file set: only the manifest, skill,
invocation metadata, and canonical reference belong in the plugin. Run Plugin Eval
when available.

When installation is in scope, install after repository checks and verify pickup in
a fresh Codex task. Installation does not prove that the task that performed the
install loaded the new runtime.
`plugins/gh-settings/` contains the installed manifest, `sync` skill, invocation
metadata, and canonical governance standard. It has no executable runtime.

Use the [skill](../plugins/gh-settings/skills/sync/SKILL.md) for task scope and the
[standard](../plugins/gh-settings/skills/sync/references/standard.md) for team
policy. The standard covers scope and authority, security profiles, dependency
submission, Dependabot defaults, rulesets, merge policy, other settings, and
reconciliation. Load the sections relevant to the requested profile; a complete
governance audit uses the whole standard.

Change policy in those runtime files. The manifest and `agents/openai.yaml`
describe `$gh-settings:sync`; the marketplace resolves the plugin at
`./plugins/gh-settings`. Keep those surfaces consistent when changing discovery.

See [Operations](operations.md) for validation and installation. GitHub's current
documentation and observed account state establish provider behavior; this page
is repository navigation, not a second governance standard.
15 changes: 4 additions & 11 deletions openwiki/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,8 @@ openwiki:
`acg-box/exp` publishes small ACG Box engineering standards as Codex plugins. Both
current plugins are instruction-only:

- `gh-settings` audits GitHub governance, puts enforceable controls at the highest
supported scope in organization-wide mode, keeps parent state read-only in
repository-scoped mode, previews exact drift, and reconciles only explicitly
approved changes. Its canonical standard is
[`plugins/gh-settings/skills/sync/references/standard.md`](../plugins/gh-settings/skills/sync/references/standard.md).
- `acg-release` owns release standards only for repositories whose canonical
GitHub owner is `acg-box`. Its only current skill manages Developer ID-notarized
Sparkle macOS ZIP releases. Its canonical standard is
[`plugins/acg-release/skills/macos/references/standard.md`](../plugins/acg-release/skills/macos/references/standard.md).
- [`gh-settings`](gh-settings.md) owns GitHub governance profiles.
- [`acg-release`](acg-release.md) owns the ACG Box macOS release standard.

The repository has no application, reusable package, executable, MCP server, or
checked-in test program. Installable runtime belongs under `plugins/`; maintainer
Expand All @@ -40,8 +33,8 @@ context belongs under `openwiki/`.
2. Read [GitHub Settings](gh-settings.md) or [ACG Release: macOS](acg-release.md)
for the plugin you are changing.
3. Read [Install And Validation](operations.md) for narrow checks and release limits.
4. Before changing runtime behavior, read the full canonical standard for the
selected plugin.
4. Before changing runtime behavior, read the relevant canonical sections for
the selected plugin.

## Task Routing

Expand Down
Loading