Skip to content

Platform Context Sync Model (Hybrid)

Why this exists

bz-platform-context should stay continuously useful without creating noise from every repo PR. Full mirroring is expensive and quickly becomes unreadable.

This document defines a hybrid model:

  • Auto-sync high-signal changes continuously
  • Manual-sync intent-heavy content through normal PR review

Sync policy

Auto-sync (continuous)

Auto-sync should run when these high-signal areas change in source repos:

  • API contracts and schema snapshots
  • Security controls and infra baseline changes
  • Governance metadata (AGENTS.md, issue templates, workflow policy files)
  • Release/process metadata that impacts cross-repo coordination

Auto-sync writes machine-readable status files under sync-state/:

  • sync-state/reservation-api-server.json
  • sync-state/admin-web-app.json
  • sync-state/venuplus-app.json
  • sync-state/customer-web-app.json

Each file stores:

  • latest source SHA/ref
  • sync mode (auto or manual)
  • signal tags
  • short summary
  • rolling history (last 25 signals)

Manual-sync (human reviewed)

Do not auto-sync these:

  • ADR content
  • constitution changes
  • glossary decisions
  • cross-repo architecture narratives
  • rollout decisions and tradeoffs

These remain standard PRs with owner review.

Reusable workflow

This repo exposes:

  • .github/workflows/platform-context-sync-reusable.yml

Caller repos can use it to publish sync signals into this repo.

Caller workflow pattern (in each source repo)

Use path filters to avoid per-PR spam and trigger only on high-signal paths.

name: Platform Context Sync

on:
  push:
    branches: [main]
    paths:
      - '.github/workflows/**'
      - '.github/ISSUE_TEMPLATE/**'
      - 'AGENTS.md'
      - 'bookingzone/**'
      - 'aws-infra/**'
      - 'docs/security/**'

jobs:
  sync:
    uses: aerospace-apps/bz-platform-context/.github/workflows/platform-context-sync-reusable.yml@main
    permissions:
      contents: read
    with:
      source-repo: reservation-api-server
      source-sha: ${{ github.sha }}
      source-ref: ${{ github.ref_name }}
      sync-mode: auto
      change-summary: 'High-signal push to main'
      signal-tags: 'api,security,governance'
      source-run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
    secrets:
      PLATFORM_CONTEXT_TOKEN: ${{ secrets.PLATFORM_CONTEXT_TOKEN }}

Guardrails to keep overhead low

  • Keep one rolling sync branch per source repo: sync/<repo>
  • Keep one open sync PR per source repo (update in place)
  • Store only compact metadata, not full code mirrors
  • Limit history to the latest 25 records
  1. Enable on reservation-api-server first (pilot)
  2. Tune paths/tags for 1 sprint
  3. Roll out to other three app repos
  4. Add monthly review of sync-state/*.json for stale sources