[architecture] Extract repository-governance: review, labels and project lifecycle automation #383

Proposal / validation gate: this issue records an extraction design for maintainer validation. Repository/package names are candidates. Approve the boundary and migration plan before implementation; this task does not authorize creating repositories, implementing the extraction, releases or consumer rollout.

Problem and proposal

The domain split needs an owner for genuine repository governance, not a new catch-all github-actions package. Propose php-fast-forward/repository-governance for review intake, labels, assignment and project lifecycle policy currently in review.yml, auto-assign.yml, label-sync.yml, .github/actions/review, label-sync and project-board.

Scope and exclusions

Own these domain workflows/Actions, policy configuration, validated GitHub adapters and contributor/review procedures. A PHP library/CLI is optional only if local reusable behavior exists; do not build a framework just for YAML symmetry. Changelog owns release policy; testing owns test/coverage comments; documentation owns Wiki/Pages; each uses an explicit governance adapter only when it truly needs project transitions.
Transient infrastructure retries and generic summary transport require an owner decision: keep small domain-local adapters first, extract a tiny shared helper only after demonstrated reuse and no dependency back to DevTools. Do not resurrect generic central ownership for all workflows.

Concrete tasks / acceptance

• Inventory event -> policy -> mutation -> permissions for issue, PR, review and project transitions; record supported consumer overrides and exact status labels.
• Keep policy implementations independently testable and non-mutating plan mode available. Publication/mutation remains isolated from untrusted PR code; repository/PR/head/event identity must be validated.
• Prevent duplicate/stale comments or project transitions; preserve independent maintainer decisions. Generic review requests never replace actual human/code review.
• Reconcile Add github/local-action to dev-tools local workflow validation path #347 local-action, Integrate github/gh-aw for workflow/action inspection in dev-tools #348 gh-aw, Adopt github/spec-kit specs and pinned-action hash governance #349 specs/pins, Add component-preference skill/reference for Fast Forward dependency guidance #350 guidance and Add first-class llms.txt support for AI-native repositories #144 llms.txt by capability: validation belongs with each owning package; cross-domain onboarding belongs to DevTools composition skills or the residual skills option evaluated in [architecture] Map domain-owned skills and replace redundant agent distribution #195. Do not close these independent feature questions.
• Reconcile historical .github#2 (closed), .github#3, open github-actions#2 and DevTools [architecture] Plan domain-owned tooling extraction and DevTools orchestration #240 without importing their monolithic runtime direction. Preserve existing work/history and discuss reuse, not automatic merge/close of PRs.
• Prove fork/trusted-event cases, least permissions, stable checks, idempotency, retries bounded to genuine infrastructure errors and separate rollback for each migrated consumer.

Alternatives

Organization .github keeps profile/brand/community defaults; it need not become the runtime for every domain. Existing github-actions scaffold is not evidence of deployed domain ownership.

Skills-first distribution

Move github-issues, github-pull-request and pull-request-review procedures to this domain. Convert issue-editor, issue-implementer and review-guardian role prompts into composable skills where equivalent. A specialist agent format requires demonstrated benefit; do not make a new central agents repo the default. LLM Skills installs/version-selects payloads; no replacement copy/symlink installer. See reconciled #195.

Delivery and migration gates

• One domain owner for library/CLI, relevant reusable workflow/Action, portable skill, tests and versioned docs; adapters call the same implementation. Do not create a surface solely for symmetry.
• No production dependency back to DevTools; no generic Actions repository as mandatory runtime. CPX/external execution does not isolate PHPUnit/config classes loaded in the same PHP process.
• Preserve project overrides, exit codes, JSON contracts, working directory/cache/color options, and PHP consumer compatibility. Distinguish tool runtime from application minimum.
• Validate Composer archives, runtime resources and skill provenance outside the source checkout; no host-cache absolute paths in consumer files.
• Release availability, exact workflow/runtime/skill compatibility, then pilot consumer PRs and rollback are separate gates. Never point consumers at a not-yet-published version. No release/merge/deploy/repository creation is performed by this planning issue.
• Root architecture tracking: [architecture] Plan domain-owned tooling extraction and DevTools orchestration #240; release-safe refs Define release-safe refs for consumer workflow wrappers and checked-out actions #238; open distribution redesign PR feat!: distribute DevTools through CPX and portable skills #376 must be revalidated before implementation. Evidence baseline: DevTools main 35d27ee (2026-10-21), not an assertion that PR feat!: distribute DevTools through CPX and portable skills #376 is merged.

Architectural / Isolation Criteria

• MUST: Core logic MUST live in dedicated services; commands/controllers only orchestrate.
• MUST: Separate input resolution, domain transformations and rendering; keep CLI/framework I/O out of reusable behavior.
• MUST: Support reuse/extensibility without major refactoring and deterministic, testable exits/output.
• MUST: Separate gathering/transformation from writes/publishing; repeated execution MUST be idempotent or explicitly bounded.
• MUST: Update README, command/config docs, skill references and synchronized consumer examples with the actual new ownership.

Repository-split decision gate

Before implementation, compare independent consumers, current code size, dependency/release cadence and maintenance cost with keeping this responsibility as a bounded module under the nearest domain or DevTools. A separate repository is a candidate, not mandatory. If reuse/lifecycle does not justify it, document the smaller grouping and avoid artificial fragmentation. Validate the recommendation with the maintainer.