[architecture] Extract repository-metadata policies without moving bootstrap orchestration #382

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

Propose php-fast-forward/repository-metadata / fast-forward/repository-metadata for policy-aware repository metadata generation/merging. Source baseline also includes License, Funding, CodeOwners, GitIgnore and GitAttributes commands and dedicated services/resources.

Boundary

Own license selection/rendering, funding reconciliation, CODEOWNERS generation, managed ignore/export policy and Composer metadata edits/normalization adapters. DevTools owns profile selection, package composition, provenance manifest, upgrade planning and safe orchestration. git-hooks remains #336; domain workflow/skill payloads belong to their domain packages. Do not create a repository-sync monolith that reabsorbs all domains.

Concrete tasks / acceptance

• Inventory ownership of every generated field/path and source precedence (explicit user config before package defaults); license choice is not guessed and author/contact data is not silently overwritten.
• Separate pure read/plan/merge transformations from apply; preserve comments/order/manual entries where format supports them. Changes to Composer requirements, allowlists and scripts must be scoped, with unrelated entries retained.
• Define proposed manifest resource descriptor used by the DevTools orchestrator: source package/version/path, owned target regions, hash, policy, schema version and rollback data. This package implements metadata policy, not central cross-domain sync.
• Coordinate Composer Normalize with code-standards so one canonical implementation/writer exists; compatibility aliases can delegate.
• Test local overrides, missing/invalid metadata, repeated no-op application, path/symlink escape rejection, preexisting files, three-way conflicts and interrupted apply. Check/dry-run must not install plugins, modify files or execute hooks.
• Respect closed Make consumer synchronization manifest-driven and policy-aware #143/Add check and dry-run support for skills, agents, and wiki synchronization #141 as history, not proof the new cross-package descriptor and skill ownership contract exists. No reopening historical tasks merely for this larger scope.

Alternatives

One repo per license/funding/ignore command is premature. Keeping metadata policy permanently inside bootstrap couples reusable transformations to the orchestrator. Start one coherent metadata domain and split only with concrete independent consumers.

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.