Skip to content
fitme·story
fitme·story
Case studies
v7.8.3 · 7 min read

Cross-Repo State Sync (v7.8.3) — 10 PRs Across 2 Repos, 3-Attempt Cutover Ceremony, Reverse-Sync Infrastructure Live

Summary card · 60-second read
Version
v7.8.3
Date
2026-05-11
Tier
light

v7.8.3 is the first FitMe PM framework release that spans two git repos as a single coordinated Feature. Shipped 2026-05-11 via 10 PRs (5 FT2 + 5 fitme-story) in a single session: V2 gate promoted to enforced (Phase 0), PR cite cache + control-room aggregator (Phase 1), state_owner schema + 62-feature backfill (Phase 2), reverse-sync GitHub Action (Phase 3), and a 3-attempt Phase 4 cutover ceremony that certified the full round-trip by catching 3 latent framework bugs at 3 different enforcement layers. F11, F12, F13 documented as v7.9 candidates. HADF Phase 2-bis Sub-exp 1 unblocked.

Honest disclosures
  • •The Phase 4 cutover required 3 attempts to succeed. Each failure was a real latent bug in the framework (pre-commit spec compliance, GH Actions job-level secrets.* syntax, workflow_dispatch HEAD~1 window). None were operator error. The 3-attempt certification is treated as evidence the framework works, not as a reliability concern — the bugs were caught before any production feature relied on the broken paths.
  • •The plan estimated 35 cross-repo cite occurrences; the actual count was 63 (plan-adjustment A1). The discrepancy reflects 28 cites in case studies added after the spec was written. The validate-existing-cites target passed all 63 cleanly.
  • •The state_owner backfill count shifted from the PRD estimate of 47 features to 62. The backfill script auto-detected all features; the increase reflects new features shipped during the v7.8.3 execution window.
How to read this case studyT1/T2/T3 · ledger · kill criterion▾
T1Instrumented
Numbers come from a machine-generated ledger or commit. Reproducible. Highest reader trust.
T2Declared
Numbers stated by a structured declaration (PRD, plan, frontmatter) but not directly measured.
T3Narrative
Estimates and observations from session memory. Useful for context; not citable as evidence.
Ledger
Where to verify the claim — a file path, GitHub issue, or backlog entry. Anything labelled ledger: is the audit trail.
Kill criterion
The pre-registered threshold under which this work would have been killed mid-flight. Not fired = work shipped without hitting the threshold.
Deferred
Items intentionally not closed in this version. Each cites the ledger that tracks remaining work.

Visual aid · key numbers at a glance

Default · no specialised visual declared
PRs shippedT1
10 total (FT2 #298-#302 + fitme-story #86-#90)
Features backfilled with state_ownerT1
62 / 62
Cross-repo cites validatedT1
63 / 63
Framework tests passing at Phase 2T1
20 / 20
Phase 4 cutover attemptsT1
3
V2 enforcement false positivesT1
0
STATE_OWNER_LOCATION_MISMATCH false positivesT1
0
v7.9 candidates addedT1
3 (F11, F12, F13)
Kill criterion · not fired
  • Reverse-sync PRs create gate-firing storm (>10 false-positive failures in first week of Phase 3 production) — halt Phase 3
  • state_owner backfill triggers integrity-cycle regression on >5 features within 72h post-merge — roll back schema
  • V2 enforcement fires on >3 already-shipped features (false positives) — revert to advisory + 7-day calibration
  • HADF Phase 2-bis Sub-exp 1 launch BLOCKED until all 5 phases ship and each phase calibration target is met

Context

v7.8.3 is the first release in the FitMe PM framework where a single PM-workflow Feature spans two git repositories. Before v7.8.3, fitme-story and FitTracker2 shared framework gate logic (ported in v7.8.1 Phase B) but had no synchronized state: a fitme-story-native feature could not have its state.json tracked in FT2's integrity cycle, and cross-repo PR citations were silently skipped by the BROKEN_PR_CITATION gate.

The v7.8.3 spec closed both gaps and added forward-sync infrastructure to propagate FT2's gate-coverage.jsonl into fitme-story's control-room dashboard — making the framework visible from both directions.

The 5-phase rollout

Phase 0 — Gate promotions + test infrastructure (FT2 PR #298)

V2 (CACHE_HITS_AUTO_INSTRUMENTATION_DRIFT) had been running in advisory mode since v7.8 shipped 2026-05-04. After 7 days with zero false positives, Phase 0 promoted it to enforced. V9 (Mechanism E merge driver) was extended to cover .claude/logs/<feature>.log.json via glob pattern in .gitattributes.

Phase 0 also shipped the snapshot protocol (scripts/snapshot-phase-completion.sh + make snapshot-phase) as a SanDisk Extreme disconnect guard, and established the tests/framework/ pytest package with 6 green tests as the TDD foundation for all subsequent phases.

Phase 1 — Telemetry foundations (FT2 PR #299 + fitme-story PR #86)

Two known bugs in BROKEN_PR_CITATION were fixed: (B1) silent skip on cross-repo [fitme-story#N] short-form cites; (B2) URL-form mis-routing. A unified scripts/refresh-pr-cache.py now resolves both citation forms against a single cache. make validate-existing-cites confirmed all 63 cross-repo cite occurrences in FT2 case studies pass cleanly.

The control-room extension (src/lib/control-room/gate-coverage-aggregator.ts) combines both repos' Mechanism A telemetry into a time-sorted, source-tagged list. The /control-room/framework page gained an aggregated gate-coverage count section.

Phase 2 — state_owner schema + 62-feature backfill (FT2 PR #300)

The state_owner enum field ("ft2" | "fitme-story") was added to the state.json schema, with three cooperating gates: STATE_OWNER_MISSING, STATE_OWNER_INVALID, and STATE_OWNER_LOCATION_MISMATCH. A morphed C-5 gate exempts files carrying state_owner_sync_origin: "fitme-story-reverse" from the location mismatch check so auto-synced reverse-mirror files are not false-positived.

scripts/backfill-state-owner.py ran mechanically against all 62 FT2 features. Zero missing findings post-backfill.

A notable self-catch: the first STATE_OWNER_LOCATION_MISMATCH implementation used re.search(r'/fitme-story\b', abs_path) — a word boundary that matched 3 FT2-canonical feature names beginning with fitme-story-. The pre-commit gate fired on its own Task 2.4 commit attempt and caught the bug before merge. Fixed by requiring a trailing slash: /fitme-story/.

Phase 3 — D-1 reverse-sync GitHub Action (fitme-story PR #87)

.github/workflows/reverse-sync-fitme-story-to-ft2.yml (141 lines) triggers on push to fitme-story main when paths match .claude/features/**/state.json. It detects files with state_owner: "fitme-story" and opens an auto-PR against FT2 main with the state_owner_sync_origin: "fitme-story-reverse" marker. The FT2_REPO_TOKEN secret was provisioned on Regevba/fitme-story as part of Phase 3 operator setup.

An implementation note from Phase 3: the GH Actions injection risk (routing context expressions through env: vars before run: shells) was proactively addressed during authoring. This practice later proved directly relevant when the job-level if: secrets.* bug surfaced in Attempt 2 of the Phase 4 cutover.

Phase 3 calibration was deferred to Phase 4: the first real fitme-story-native commit would trigger the actual workflow run.

Phase 4 — Cutover ceremony (fitme-story PRs #88, #89, #90 + FT2 PR #301)

The cutover assigned a real feature (3d-interactive-framework-flow-diagram) as the Phase 4 test subject: create a fitme-story-native state.json with state_owner: "fitme-story", push to fitme-story main, let the reverse-sync workflow open an auto-PR against FT2, merge it, and confirm forward-sync round-trips the state.json back.

It required 3 attempts.

The Phase 4 cutover dogfood narrative — 3 attempts, 3 layers

Attempt 1 — Pre-commit layer (fitme-story PR #88)

The first commit attempt for 3d-interactive-framework-flow-diagram/state.json was rejected by the v7.6 PHASE_TRANSITION_NO_LOG and PHASE_TRANSITION_NO_TIMING gates. The new state.json had current_phase: research but no corresponding log event and no timing.phases.research.started_at block.

Both gates were ported to fitme-story in Phase B (fitme-story PR #72, 2026-05-09). They fired correctly on the very first fitme-story-native state.json ever committed — catching a schema compliance gap before it reached the remote. The fix: run python3 scripts/append-feature-log.py to write the phase_started Tier 2.2 event and add the timing block. PR #88 merged at 2026-05-11T15:48:15Z.

Attempt 2 — Workflow-load layer (fitme-story PR #89)

After PR #88 merged to fitme-story main, the reverse-sync workflow fired immediately and failed in 0 seconds with "This run likely failed because of a workflow file issue" (run 25680885503). The message did not point at the offending line.

Root cause: the workflow YAML had if: ${{ vars.FT2_REPO_TOKEN_PROVISIONED == 'true' || secrets.FT2_REPO_TOKEN != '' }} at the job level. GitHub Actions does not permit secrets.* in job-level if: expressions — only in step-level expressions. The entire workflow file fails to load when this syntax is present.

The fix: move the token-presence guard into a new first step (token_check) using env-var indirection (HAS_TOKEN: ${{ secrets.FT2_REPO_TOKEN != '' }}), which is valid at step level. All subsequent steps gate on if: steps.token_check.outputs.skip == 'false'. A workflow_dispatch: trigger was added so the operator could manually re-trigger.

actionlint, the standard GitHub Actions linter, catches this class of error statically. This is the direct empirical basis for F12.

Attempt 3 — Workflow-trigger layer (fitme-story PR #90)

The manual workflow_dispatch run completed in 4 seconds reporting success — but opened no FT2 PR. The workflow's change-detection step uses git diff HEAD~1 HEAD -- '.claude/features/*/state.json'. When triggered via workflow_dispatch, HEAD points to the hotfix commit (PR #89). HEAD~1 is the commit before the hotfix. The diff sees only the YAML change, not the state.json change that is now 2 commits behind HEAD.

Fix: a third PR (#90) that adds a real state.json field on a path-filter-matching commit. When this PR merges to main, the standard push trigger fires, git diff HEAD~1 HEAD correctly sees the state.json change, the workflow detects state_owner: "fitme-story", and FT2 PR #301 is opened with the state_owner_sync_origin: "fitme-story-reverse" marker.

Operator merges FT2 PR #301. The C-5 gate exempts the file via the sync_origin marker. Round-trip complete.

The workflow_dispatch bootstrap path is documented as needing a source_commit input OR a full-repo scan of unmirrored fitme-story-native state.json files. Both deferred to v7.9 (F13).

F11, F12, F13 — v7.9 candidates surfaced

IDLayerGapProposed mechanism
F11Cycle-time advisoryBRANCH_ISOLATION_HISTORICAL flagged the reverse-sync mirror commit (merged via auto-PR from a reverse-sync/* branch) as bypassing branch isolation — false positiveExtend advisory branch-name allowlist to include reverse-sync/* OR morph to read state_owner_sync_origin
F12Workflow-loadJob-level secrets.* expression caused vague load failure; actionlint catches this staticallyAdd actionlint to pre-commit gate stack or verify-local CI-validation step
F13Workflow-triggerworkflow_dispatch HEAD~1 diff window breaks when a hotfix lands between cutover commit and dispatchAdd source_commit input to workflow_dispatch OR implement full-repo scan of unmirrored fitme-story-native state.json files

F11/F12/F13 join existing F1-F10 candidates ahead of the 2026-05-21 v7.9 promotion decision.

What this unlocks

HADF Phase 2-bis Sub-exp 1 was gated on v7.8.3 completion: all 5 phases shipped and each phase's calibration targets met. Phase 4 round-trip certified. Sub-exp 1 is unblocked once Task 4.11 post-merge verification confirms.

Track 6 HADF gate activation: V2 enforcement (Phase 0) was a stated prerequisite for Track 6. With V2 enforced and zero false positives, Track 6 is unblocked from the framework side.

Future fitme-story-native features follow the established pattern: create state.json with state_owner: "fitme-story", push to fitme-story main, the reverse-sync workflow opens an auto-PR against FT2, operator merges, forward-sync round-trips back. The 3d-interactive-framework-flow-diagram feature is the first to use this path.

v7.9 promotion decision (2026-05-21): F11/F12/F13 are input alongside existing F1-F10 candidates and gate-coverage.jsonl calibration data accumulating since 2026-05-11.

Cross-references