Skip to content

Initiatives Project: multi-repo rollout + reconciliation parity #415

Closed

Description

@don-petry

Follow-on to the pilot (#387). Bundles the architectural defers that didn't fit the single-repo scope.

Decision log — 2026-06-14: Multi-repo architecture decided (§1): reusable workflow + thin per-repo caller stubs, callers pinned to the add-to-project/stable channel per the org reusable-workflow versioning standard. Not the webhook handler. Execution stays gated on the #414 30-day review (keep / expand / roll back); this issue is now design-complete and shovel-ready. See decision comment.

Why one PR for all of this

These four findings share one architectural answer (a generic 'reconcile content with project' function parameterized by content type and eligibility predicate). Solving them piecemeal would mean rewriting the reconcile machinery once per finding. Bundle them so the underlying mechanism gets designed once.

In scope

1. Multi-repo deployment — ✅ decided

Today the workflow only fires for events in .github. Other repos' qualifying issues/PRs are invisible.

Decision (2026-06-14): reusable workflow + thin per-repo caller stubs. Matches the established dependabot-rebase / auto-rebase / feature-ideation / dev-lead stub pattern; avoids the hosting decision a webhook handler would require.

  • Extract logic into add-to-project-reusable.yml (hosted in .github); scripts in .github/scripts/add-to-project/ stay, threaded via an agent_ref-style input pinned to the same channel.

  • The existing add-to-project.yml becomes the thin caller stub for this repo.

  • Each adopting repo gets a thin caller pinned once to the moving stable channel tag, per ci-standards.md → Reusable workflow versioning:

    uses: petry-projects/.github/.github/workflows/add-to-project-reusable.yml@add-to-project/stable

    Never @main, never a SHA, never a frozen @vX.Y.Z.

  • Release process: merge to main → cut immutable add-to-project/vX.Y.Z → promote stable (single gated hop today until ring channels exist). .github's own caller is Ring 0 / self-host dogfood.

  • Deployment: stubs rolled out via scripts/deploy-standard-workflows.sh; compliance audit check_centralized_workflow_stubs enforces the canonical pin.

Rejected alternative — org-level webhook handler: one deploy, no per-repo stubs, but requires a hosting decision and diverges from the established stub pattern.

2. Issue/PR cleanup-on-label-change (Codex P2 from PR #388 review)

process_issue_or_pr currently only ADDS; it never removes. If an item is added with dev-lead and later receives one of the excluded labels (or has dev-lead removed), the project item stays. Needs:

  • Add unlabeled to issue/PR triggers
  • reconcile_content_with_project that mirrors reconcile_discussion's shape, parameterized by content type + eligibility predicate

3. Hard-coded labels and category

evaluate_noise_gate hard-codes dev-lead + 4 excluded labels. reconcile_discussion hard-codes Ideas. For a second Project to use the same scripts, both must be env-driven. This is the enabler for the reusable extraction in §1 — the gate (dev-lead, the 4 excluded labels, the Ideas category) becomes reusable inputs so each caller passes its own values.

4. Fork-PR maintainer-label gate

pull_request_target gate evaluates the PR author's author_association — so fork PRs from FIRST_TIMER/CONTRIBUTOR authors are skipped even when a maintainer applies dev-lead. Fix: also accept events where the labeler (github.actor on a labeled event) is trusted, OR move trust to head_repository.fork == false.

Out of scope

  • New views or fields on the existing project (those are content, not infra)
  • Program boards for Compliance / Fleet Monitor — separate decision at 30-day review

Related

Activity

  1. added
    dev-leadFor dev-lead agent pickup
    and removed
    dev-leadFor dev-lead agent pickup
    on Jun 8, 2026
  2. don-petry commented on Jun 14, 2026

    @don-petry
    ContributorAuthor

    Architecture decision — §1 Multi-repo deployment

    Decided: reusable workflow + thin per-repo caller stubs. Not the org-level webhook handler (avoids a hosting decision and matches the established dependabot-rebase / auto-rebase / feature-ideation / dev-lead stub pattern).

    Pinning (per ci-standards.md → Reusable workflow versioning — the stable channel): every caller pins the reusable's moving stable channel tag once —

    uses: petry-projects/.github/.github/workflows/add-to-project-reusable.yml@add-to-project/stable

    Never @main, never a SHA, never a frozen @vX.Y.Z. First-party reusable refs are SHA-pin-exempt.

    Release process: develop/merge to main → cut immutable add-to-project/vX.Y.Z at the merged commit → promote stable (single gated hop today until ring channels exist). The .github repo's own caller is Ring 0 / self-host dogfood — it runs the new version first at zero external blast radius before stable moves.

    Knock-on design (keeps "one architectural answer" for all four findings)

    • The existing add-to-project.yml becomes the thin caller stub; all logic moves into add-to-project-reusable.yml (scripts in .github/scripts/add-to-project/ stay, threaded via an agent_ref-style input pinned to the same channel).
    • §3 (hard-coded labels/category) is the enabler: dev-lead, the 4 excluded labels, and the Ideas category become reusable inputs, so each repo's caller passes its own gate. Design this once.
    • §2 (reconcile_content_with_project) and §4 (fork-PR maintainer-label gate) ride on the same parameterized reconcile function as planned.

    Deployment

    Per-repo caller stubs deployed via scripts/deploy-standard-workflows.sh; compliance audit's check_centralized_workflow_stubs then enforces the canonical pin (same as the other Tier-1 stubs).

    This unblocks §1; remaining decision needed items in this issue are resolved. Execution stays gated on the #414 30-day review (keep / expand / roll back) — this just makes "expand" shovel-ready.


    Generated by Claude Code

  3. don-petry commented on Jun 18, 2026

    @don-petry
    ContributorAuthor

    Rollout started early (owner-authorized, ahead of the 2026-07-07 gate)

    The implementation PR #466 is merged (main 151347e). Per owner decision, the multi-repo rollout is being kicked off now rather than waiting for the 30-day review gate (#414).

    Execution is happening from a session with org-wide repo + tag permissions (this session's credentials are scoped to petry-projects/.github and can't create the protected add-to-project/* tags or write to other repos). Sequenced as:

    1. Cut the channel — immutable add-to-project/v1.0.0 + moving add-to-project/stable at 151347e (per ci-standards reusable-workflow versioning). Strict prerequisite for step 2.
    2. Enable + deploy — add add-to-project.yml to DEPLOYABLE_WORKFLOWS in scripts/deploy-standard-workflows.sh, then deploy-standard-workflows.sh --workflow add-to-project.yml to the 7 other org repos (.github-private, google-app-scripts, bmad-bgreat-suite, broodly, TalkTerm, markets, ContentTwin).

    Prereqs being confirmed: petry-projects-planner app (ID 3985527) installation must include each target repo; org secrets INITIATIVES_APP_ID / INITIATIVES_APP_PRIVATE_KEY available to them. Watch check_centralized_workflow_stubs — adding the workflow to the deployable set may flag repos as non-compliant until the deploy lands, so enabler + deploy go together.

    Verification will follow the #414 smoke tests (dev-lead issue → board; noise-gate exclusion; Ideas discussion → draft). I'll update here with onboarded repos + results as steps land.


    Generated by Claude Code

  4. don-petry commented on Jun 18, 2026

    @don-petry
    ContributorAuthor

    ✅ Multi-repo rollout executed — all 7 consumer repos onboarded

    Owner-authorized to start early, ahead of the documented 2026-07-07 review gate (#414).

    Step 1 — stable channel cut (per ci-standards.md → Reusable workflow versioning)

    Both tags cut at the #466 merge commit 151347e and verified resolving to it:

    • add-to-project/v1.0.0 — immutable release tag (annotated) → 151347e
    • add-to-project/stable — moving production channel → 151347e

    (Phase-1 single-hop promotion: a reusable with only stable defined promotes in one gated hop until next/ringn channels exist.)

    Prerequisites verified

    • App install — petry-projects-planner (App ID 3985527) is installed org-wide (repository_selection: all) with exactly organization_projects: write, issues: read, pull_requests: read. No missing repos.
    • Org secrets — INITIATIVES_APP_ID / INITIATIVES_APP_PRIVATE_KEY existed but were selected-visibility scoped to .github only. Extended visibility to all 7 targets.

    Step 2a — deploy enabler (PR #477, merged)

    • Added add-to-project.yml to DEPLOYABLE_WORKFLOWS in scripts/deploy-standard-workflows.sh.
    • Added a narrow per-workflow SKIP_OVERRIDES map so .github-private (normally SKIP_REPOS, self-manages its fleet) receives only this stub. .github stays fully exempt — it hosts its own local-ref self-host caller that a channel-pinned stub must not overwrite.
    • Compliance check, as requested: check_centralized_workflow_stubs keys off its own hardcoded list (not DEPLOYABLE_WORKFLOWS) and only validates stubs that already exist; add-to-project.yml is not in REQUIRED_WORKFLOWS either — so enabling deployment flags no repo non-compliant. Enabler and deploy landed together regardless.

    Step 2b — stub deployed to all 7 targets

    Verbatim from standards/workflows/add-to-project.yml (reusable + agent_ref pinned to add-to-project/stable, project_id: PVT_kwDOD2inqs4BZq3-). All 7 verified carrying the stable pin, agent_ref, and project_id:

    Repo Path Mechanism
    .github-private direct (canonical script) ✅
    bmad-bgreat-suite direct ✅
    broodly direct ✅
    TalkTerm direct ✅
    google-app-scripts PR (#394) + admin-merge ✅
    markets PR (#275) + admin-merge ✅
    ContentTwin PR (#271) + admin-merge ✅

    Operational finding: deploy-standard-workflows.sh pushes directly to each repo's default branch via the Contents API. That works where org-admin bypasses the ruleset, but 3 repos (google-app-scripts, markets, ContentTwin) have branch rulesets that enforce required status checks on direct pushes (HTTP 409 "Required status check … expected") and were not bypassed by the Contents API. I deployed those three via a branch + PR (verbatim template) merged with admin once required checks were green. Worth a follow-up: teach the deploy script a PR mode for ruleset-protected repos rather than relying on direct-push bypass.

    Smoke tests — see #414. All green; @add-to-project/stable resolves with no startup_failure.

  5. don-petry commented on Jun 18, 2026

    @don-petry
    ContributorAuthor

    Follow-up filed for the operational finding noted above: #478 — deploy-standard-workflows.sh should deploy via PRs (reusing the PR-based primitive aw-standards-sync.sh already implements) instead of direct Contents-API pushes, which break on ruleset-protected repos and bypass review/CI elsewhere.

  6. added a commit that references this issue on Jun 18, 2026
  7. added 2 commits that reference this issue on Aug 31, 2026
  8. added 2 commits that reference this issue on Sep 7, 2026
  9. don-petry commented on Oct 21, 2026

    @don-petry
    ContributorAuthor

    Closing after the 2026-10-21 backlog triage.

    Why: Multi-repo rollout + reconcile parity shipped.
    Evidence: PRs #466 #477 #608 #616 merged

    Reopen if this still reproduces on main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickup

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions