feat: register fork-main integration divergence

[tiago-peixoto]

Intent

Register the first carried fork divergence in the fork divergence ledger: the permanent fork-main integration workflow, submitted upstream as pull request 1944 and still open there. This is the retroactive bookkeeping the ledger was built for - the fork has carried this workflow since before the ledger existed, and until now no manifest unit described it. IMPORTANT DELIVERY REQUIREMENT: merge with the REGULAR merge method, never squash and never rebase. The two-parent merge IS the deliverable: bin/fm-fork-status.sh requires every manifest unit to have a reachable branch-level integration merge whose second parent is an ancestor of its canonical topic, so squashing or rebasing this pull request would destroy the very link that makes the registration valid and would leave the fork unhealthy. PRECISE CHANGE SET, stated this way deliberately because a vaguer wording previously caused an acceptance-criterion conflict across two gates: the first-parent diff changes exactly ONE file, fork-divergences.json, adding the manifest entry for id fork-main-integration with class pending, its canonical topic, its open upstream pull-request record, its falsifiable retirement condition, and the 33 exact paths its patch touches. There is deliberately NO product-content change: the canonical topic reproduces work already present on fork main, so the integration merge records ownership and provenance rather than altering code. An acceptance criterion must expect a manifest-only diff plus a two-parent merge commit. The canonical topic is one aggregate non-merge commit based on current official upstream, and git cherry against upstream reports exactly one non-equivalent commit, which is the invariant that makes upstream squash or rebase equivalence measurable later. The topic deliberately excludes the governance manifest itself, excludes the supervision guard fix that will be registered as its own separate unit, and excludes integration-path documentation artifacts that earlier pipeline runs committed, so the unit's patch matches its stated intent exactly. Follow the fork-main-integration procedure: isolated candidate from the private fork integration clone, validation through the isolated fork-target registration, no force-push, and no rewriting of published history.

What Changed

• Register fork-main-integration as a pending divergence with its canonical topic, open upstream PR feat(fork): add permanent fork-main integration kunchenguid/firstmate#1944, and retirement condition.
• Record the exact 33 paths owned by the carried workflow without changing product content.
• Integrate the manifest-only registration through a two-parent merge whose second parent is the aggregate topic commit.

Risk Assessment

🚨 High: The source diff and topic shape are correct, but merging without the canonical branch would immediately make the registered divergence unhealthy and inoperable.

Testing

Inspected the base/target and first-parent diffs, asserted the required merge and canonical-topic invariants, matched all 33 declared paths to the actual topic patch, verified upstream PR 1944 remains open, and exercised the production fork-status CLI end-to-end with zero structural errors. The reviewer-visible transcript was preserved and testing left the worktree clean; the eventual outer PR merge remains outside this test phase and must use the regular merge method.

Evidence: End-to-end registration evidence

PR 1944 open; two-parent integration merge; manifest-only first-parent diff; exactly one canonical topic commit; declared and actual paths match 33/33; fork status reports errors=0.

$ gh-axi pr view 1944 --repo kunchenguid/firstmate
pull_request:
  number: 1944
  title: "feat(fork): add permanent fork-main integration"
  state: open
  author: tiago-peixoto
  draft: no
  merged: no
  checks: "13 passed, 0 failed, 13 total"
  body: "## Intent\n\nMake Firstmate run from the personal fork's main as a permanent live integration branch, upstreaming at our own pace so locally accepted changes are dogfooded immediately and produce evidence that can enrich their upstream pull requests or justify discarding them. This branch is not a toolkit newly built today: it preserves the existing fork-integration toolkit at 3137752, already reviewed through several validation rounds in PR#1944. Today's change is exactly one non-rewriting merge \n... (truncated, 27434 chars total - use --full to see complete body)"
  comment_count: 3 — use --comments to see full comments
  review_count: 0 — use --reviews to see full reviews

$ git show -s --format="commit=%H%nparents=%P%nsubject=%s" c4f48b2b1559b5ce77e56e574dec2fd6e134df7d
commit=c4f48b2b1559b5ce77e56e574dec2fd6e134df7d
parents=39d18f2658f0589ba36a32d366bf8ac6b573f190 06925cf8b67e33cd576e830b7724b0c60943c40e
subject=Merge divergence fork-main-integration

$ git diff --name-only c4f48b2^1 c4f48b2
fork-divergences.json

$ git cherry 64d61ae 06925cf
+ 06925cf8b67e33cd576e830b7724b0c60943c40e

$ manifest/topic path comparison
declared paths: 33
canonical topic paths: 33
path diff: exact match

$ bin/fm-fork-status.sh --repo <candidate> --fork-ref HEAD --upstream-ref upstream/main --facts-only
Fork divergence health: retained=1 patches=1 not-upstream=8 integration-artifacts=7 retired-history-patches=0 accepted-upstream-patches=0 trend=up superseded=0 signals=7 errors=0
Refs: fork=refs/heads/target@c4f48b2b upstream=refs/heads/upstream@64d61aed
Classes: pending=1 rejected-but-retained=0 private=0 superseded=0
Oldest pending: fork-main-integration introduced=2026-08-17 age_days=1
Last upstream merge touched: 0
fork-main-integration [pending] topic=fm/divergence/fork-main-integration upstream=open https://github.com/kunchenguid/firstmate/pull/1944
  does: Permanent fork-main integration workflow: guarded remote topology, isolated fork-target validation clone, divergence manifest and health report, topic integrate and discard helpers, upstream merge helper, and the startup upstream probe.
  retire when: Upstream pull request 1944 is merged into official upstream main, so official upstream ships the fork-main integration workflow itself.
Accepted upstream and retired: 0
Manifest/Git signals (informational):
  - non-upstream commit fe30ee2e2ccf678bba877659e47bae71318a5fab is not represented by a canonical manifest topic
  - non-upstream commit 067881f8a67c9270edfb621784f7cf530fd38ccf is not represented by a canonical manifest topic
  - non-upstream commit 2def68de4882b16f3c5160dc44616a650606b321 is not represented by a canonical manifest topic
  - non-upstream commit d0a5f5a3f72a36e833b5ace9229d8bad8d1c407f is not represented by a canonical manifest topic
  - non-upstream commit 00e17f65aa3173ab9d3a3824565609baba569db6 is an integration-path artifact after cb61bd3364cdc8e2d0ef04fcad8096664bc1df60, not a carried divergence
  - non-upstream commit d51c7085780b106ec2b3b7d1847bf47e898889c6 is an integration-path artifact after 86df18c97a02421e3baf8003353476458293a208, not a carried divergence
  - non-upstream commit aee6c2e1eb55b8fca88d2d5cf216bc3e7bb28030 is an integration-path artifact after 3c9a985ad8763d92d9806284514a20b6af1ce5a0, not a carried divergence

Evidence: Upstream PR 1944

Source: Upstream PR 1944

Live upstream pull request verified open and unmerged.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 error

• 🚨 fork-divergences.json:66 - The requirement says “The canonical topic is one aggregate non-merge commit based on current official upstream,” and this entry names fm/divergence/fork-main-integration, but the fork publishes no such branch (git ls-remote --heads origin refs/heads/fm/divergence/fork-main-integration returned nothing). Although commit 06925cf is reachable as the merge's second parent, fm_fork_topic_ref resolves only a published or local canonical branch, so normal clones will report the unit missing and cannot validate or discard it. Before the captain merges, publish exactly 06925cf under that branch with a non-forced push, or provide evidence that the production fork exposes the canonical ref.

✅ **Test** - passed

✅ No issues found.

• git show -s --format='commit=%H%nparents=%P%nsubject=%s' c4f48b2b1559b5ce77e56e574dec2fd6e134df7d
• git diff --name-only c4f48b2b1559b5ce77e56e574dec2fd6e134df7d^1 c4f48b2b1559b5ce77e56e574dec2fd6e134df7d
• Targeted Git/JQ assertions for two-parent topology, canonical topic ancestry, absence of topic merges, and exact 33-path manifest coverage
• git cherry 64d61aed84373e02b1a28c4e6b262908ed8128d5 06925cf8b67e33cd576e830b7724b0c60943c40e
• GIT_DIR=<isolated-fixture>/repo.git GIT_WORK_TREE=$PWD FM_FORK_TOPOLOGY_VALIDATED_REPO=$PWD bin/fm-fork-status.sh --repo "$PWD" --fork-ref refs/heads/target --upstream-ref refs/heads/upstream --facts-only
• gh-axi pr view 1944 --repo kunchenguid/firstmate --json state,url,mergedAt,headRefName,title
• Final evidence-integrity, clean-worktree, and transient-fixture cleanup verification

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.