Review fork maintenance design: upstream ancestry, integration gates, and failure isolation

[marksverdhei]

Problem

The fork's history and maintenance workflows make upstream integration, review, and regression isolation harder than necessary. This issue records the findings from the September 5 repository-history review; proposed remedies are in a separate comment.

1. Squashed upstream ancestry conflicts with the sync strategy

The initial public release explicitly squashed the inherited history. In the non-shallow local checkout, git merge-base origin/clanker origin/main returns no common ancestor.

Nevertheless, the fork-sync configuration schedules upstream integration through a shared workflow. The reviewed shared workflow runs git rebase and then force-pushes the shared fork branch on success, with no intervening build/test gate. It creates backups, but those do not validate compatibility or prevent disruption to open branches. The caller also follows the mutable @main workflow reference.

Without shared ancestry, ordinary rebase cannot identify the original fork delta cleanly. Existing issue #16 reports widespread add/add conflicts, consistent with this mismatch. This issue complements that incident with the underlying design problem; it does not establish that every subsequent sync failure has the same cause.

2. Maintenance changes have bundled unrelated, consequential behavior

PR #46, titled dependency-refresh stabilization, changed 84 files (2,877 insertions and 1,293 deletions), including substantial Windows sandbox token, desktop-access, and process-launch behavior alongside dependencies, CI, and test repairs. This is a reviewability and rollback concern, not a claim that those sandbox changes are incorrect. The aggregate change makes it harder to validate or revert one decision independently.

3. One character collision blocks unrelated lookups

Introduced in #30, CharacterCatalog::resolve returns all catalog collision errors before considering the requested name. One conflicting package therefore prevents resolution of otherwise unambiguous characters. The remaining avatar stack (#83/#82) illustrates the impact: lazy materialization can create a collision with a preexisting custom alias and subsequently break startup.

4. Routine CI depends on unavailable historical workflow artifacts

repo-checks.yml stages an npm package using artifacts from one pinned upstream Actions run. The baseline build-test job fails with no valid artifacts found to download. An ordinary PR gate thus depends on the continued availability of external workflow artifacts, independently of the PR's code.

5. The merge workflow did not enforce the intended wait for CI

During this session, #84 merged immediately after gh pr merge --auto --rebase, while CI was unfinished. The executing agent should have checked effective merge-gate behavior first. This is an observed process failure; the exact protection/ruleset configuration still needs inspection before attributing it to a particular setting.

Impact

These choices increase upstream-sync friction, weaken confidence in merge readiness, enlarge regression blast radius, and complicate diagnosis and rollback. The primary concern is the ancestry/sync mismatch; the other findings should be addressed in separate, reviewable implementation changes.

[marksverdhei]

Proposed solutions and order

1. Contain shared-branch risk and establish a reproducible upstream baseline

• Change scheduled automation to update the upstream mirror and prepare an integration branch/PR, with no direct rebase/force-push of clanker. Pin the reusable workflow to a reviewed commit.
• Inspect effective branch protections and rulesets, including bypasses. Require the intended review and CI checks before integration; verify how auto-merge behaves instead of assuming --auto waits.
• Identify and verify the exact upstream commit underlying the initial public snapshot. Use version provenance as a starting point, then compare trees and reconstruct the downstream delta in an isolated branch. Preserve existing refs and release tags.
• Evaluate two explicit migration options: (a) rebuild the fork as reviewed downstream commits on the verified upstream base, accepting a coordinated history migration; or (b) preserve published history and establish upstream ancestry through a carefully reviewed one-time reconciliation merge. Neither should be done as a blind rebase or blanket conflict resolution.
• After establishing the baseline, integrate upstream through tested PRs. A patch-stack rebase can be prepared on a disposable branch if useful, but should not silently rewrite the shared integration branch.

Acceptance: documented, verifiable provenance; an upstream update demonstrated through a reviewable PR; relevant checks run before integration; existing published history remains recoverable. Coordinate #16 and the workflow-token work in #75 with this design so permission repairs do not merely enable the problematic push path.

2. Restore a trustworthy CI baseline in a separate change

• Replace the historical Actions-run dependency with durable, versioned artifacts with verified checksums, or build the required payloads within the workflow.
• Use deterministic local fixtures for package-layout tests where real native binaries are unnecessary, while retaining a separate test of real release packaging.
• Address the existing dependency-advisory failures separately from avatar work. Do not broadly suppress the checks merely to obtain a green result.

Acceptance: baseline repository checks no longer depend on that old upstream run, and required CI failures are either fixed or explicitly understood with a narrowly scoped, visible policy.

3. Fix alias ownership before landing the remaining behavior stack

• Resolve existing custom name ownership before installing a bundled character. Bundled materialization must not introduce a conflicting canonical name or alias.
• Add regression coverage through actual explicit-name and detected-identity startup paths using a custom character that owns a bundled-name alias.
• As a separate API decision, retain full-catalog collision reporting in validation, but allow runtime resolution of names unaffected by those collisions. Continue rejecting ambiguous requested names; do not pick an arbitrary winner.

Acceptance: selecting an existing custom alias succeeds without creating a conflicting package; unrelated valid characters remain resolvable; ambiguous names still produce actionable errors. This separates the immediate #83/#82 regression fix from the broader catalog-policy change.

4. Keep future implementation changes independently reviewable

• Separate dependency/lockfile updates, CI infrastructure repairs, test stabilization, and sandbox behavior changes wherever dependencies permit.
• Give sandbox behavior its own explicit rationale, platform validation, and rollback boundary.
• Keep the remaining avatar stages separate and land bottom-up after their own fixes and relevant checks. Fix the Centurion .ans Codespell false positive narrowly in tui: add Centurion and Jasonelle avatar assets #85.

I would prioritize containing direct shared-branch mutation and fixing baseline CI, then the immediate alias regression, followed by the deliberate ancestry migration. These are proposed follow-up changes, not authorization to rewrite history or alter repository settings as part of this issue creation.