Codify orchestrated re-sync personas and full-replacement rule - #205
Merged
Conversation
Re-syncing the downstream fleet from the hub needs a durable, committed playbook (per-machine memory is lost on a machine switch). Add an "Orchestrated Re-Sync: Hub and Downstream Personas" subsection defining the hub/orchestrator vs downstream/derived separation of duties, and make the full-replacement rule explicit in "Staying in Sync": carried artifacts are replaced whole, never partially hand-merged, and re-syncing is not an occasion to add or grow comments. Guards the two recurring downstream regressions (partial carries, comment accretion); the orchestrator validates each result by diffing against the template. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds additional guidance to AGENTS.md for template-to-downstream re-sync work by (1) explicitly requiring full replacement (not partial merges) when re-syncing carried artifacts and (2) introducing an orchestrated re-sync playbook that distinguishes hub/orchestrator vs downstream/derived responsibilities.
Changes:
- Strengthen "Staying in Sync and Reporting Drift Upstream" to require full replacement of carried artifacts/sections.
- Add a new "Orchestrated Re-Sync: Hub and Downstream Personas" subsection describing responsibilities and validation expectations.
ptr727
added a commit
that referenced
this pull request
Jun 25, 2026
…eadme, carry-whole-file (#207) Phase-0 of the template-to-downstream convergence sweep: the template absorbs everything downstream repos had reinvented, so derived repos can take the carried artifacts verbatim with zero hand-rolling. Builds on #205 (orchestration personas) and #206 (per-PR merge-bot concurrency), which this branch incorporates. Held for end-gate review; not to be merged midway. ## What this PR does - **Absorbs downstream-led action pins** (template now leads per #204): `dependabot/fetch-metadata` v2.5.0 -> v3.1.0 and `softprops/action-gh-release` v2.6.2 -> v3.0.1, the SHAs the downstreams already run. - **Generalizes the release model + adds a loud guard.** Every release is a tag on the built commit plus an auto source zip, README, and LICENSE; targets amend it by uploading `release-asset-<branch>-*` artifacts (binaries/packages) or pushing elsewhere (image/registry). `github-release` collects assets by the `release-asset-<branch>-*` pattern so the job is target-agnostic and carries verbatim. - **Makes the Docker README + date badge main-only, caller-gated.** Neither has per-branch context, so both move out of the publisher branch matrix into single jobs gated on `main` being published. `publish-docker-readme-task.yml` is rebuilt generic: a matrix over a `repositories` input (or a manifest-derived list), a caller-passed `ref`, and an optional transform step (e.g. m4) to render the README before pushing. - **Adopts the carry-whole-file rule.** Replaces "drop the sections you don't ship": derived repos carry each shared file in full (an inert `[*.cs]` block or unused-language `CODESTYLE.md` section costs nothing), so every re-sync is a clean overwrite, not a partial merge. `CODESTYLE.md` is genericized into a self-contained drop-in (no demo-project names, no template-onboarding pointers) and carries both the .NET and Python sections whole. Only per-language `.vscode/tasks.json` task definitions still track the repo's language. All carried files stay self-contained (no template/demo/cross-project references except the sanctioned upstream-drift pointer). Workflow YAML and Markdown remain CRLF per the line-ending governance. Validated with actionlint and markdownlint-cli2 (clean). ## Documented adaptations (for review) These are the genuine, intentional deviations the maintainer should review at the end gate. Each is a sanctioned exception with its rationale recorded inline in the artifact; nothing here is accidental drift. - **`fail_on_unmatched_files: true` on `github-release`** - a promised `release-asset-*` that goes missing or is misnamed fails the release loudly; a Docker-only / no-file-target repo is the one case that relaxes it (no release asset to attach). - **`merge-bot-pull-request.yml` concurrency: per-PR group, `cancel-in-progress: false`** - under `pull_request_target` `github.ref` is the base branch, which would serialize every bot PR against that base, so the group keys on the PR number; cancellation would leave auto-merge in an inconsistent state, so events queue and each runs to completion. - **`publish-release.yml` concurrency: global ref-independent group, `cancel-in-progress: false`** - it publishes shared ref-independent artifacts (both branches' Docker tags/caches and GitHub releases) regardless of the triggering ref, so a ref-scoped group would let a scheduled run and a manual dispatch double-push; cancelling mid-flight can leave a partial tag set or half-created release. - **`dotnet/nbgv` consumed via `@master` (no SHA pin)** - the upstream tag stream lags `master` substantially and Dependabot's tag-tracking would propose a downgrade; this is the one documented no-SHA-pin exception. - **Ruleset-bound job name kept verbatim (no "job" suffix)** - `Check pull request workflow status` in `test-pull-request.yml` is referenced as a required-status-check `context:` in the branch ruleset; renaming it to fit the "every job name ends in job" convention would silently break required-status-check enforcement. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Jul 4, 2026
Promote the accumulated `develop` work to `main`. Twelve changes since the last promotion: - Add `WORKFLOW.md`: workflow style, architecture, behavioral contract, test methodology (#223) - Use NBGV `IGNORE_GITHUB_REF` instead of the ineffective `GITHUB_REF` override (#222) - Skip validate-release on smoke builds (#220) - Gate asset delete on the release create/refresh condition (#218) - Ship branch rulesets as versioned JSON in the re-sync / drift loop (#212) - Clean up transfer artifacts surgically at consumption, not blanket-delete (#216) - Version each publish leg against its own branch; validate at entry (#215) - Consolidate workspace configurations into a unified ProjectTemplate workspace (#210) - Template convergence barrier: absorb pins, generic release + docker-readme, carry-whole-file (#207) - Key merge-bot concurrency on PR number, not `github.ref` (#206) - Codify orchestrated re-sync personas and full-replacement rule (#205) - Lead action pins; affirm pattern-based artifact handoff (#204) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Foundation for orchestrating template→downstream re-sync from one session. Because per-machine agent memory is lost on a machine switch, the reusable playbook must live in a committed file.
What
AGENTS.mdsubsection "Orchestrated Re-Sync: Hub and Downstream Personas" (hub-only, under "Staying in Sync"): defines the hub/orchestrator persona (owns source of truth, drives consolidation, validates each downstream result for full-replacement + comment discipline + EOL/lint, fixes template gaps through the gate, never merges without maintainer OK) vs the downstream/derived persona (full-replace under direction, honor comment rules, report gaps upstream).Why
Targets the two recurring downstream regressions observed across re-syncs: agents doing partial updates where carry means full replacement, and accreting comments that violate the Comments rules. The orchestrator now catches both by diffing every result against the template.
Docs-only; markdownlint clean; line endings preserved.
🤖 Generated with Claude Code