Re-onboarding with `fullsend` v0.37 removes custom agent configuration

[redhat-chai-bot]

Summary

Re-onboarding a project to fullsend (v0.37) removes existing custom agent configuration. The onboarding scaffold overwrites .fullsend/config.yaml without preserving user customizations.

Evidence

• Re-onboarded roming22-org/fullsend-python using fullsend v0.37
• Resulting changeset: roming22-org/fullsend-python@da6ce8b
• PR fix(#6678): preserve per-repo config on re-onboarding #6679 attempted a fix by preserving the entire existing config.yaml, but this approach is too simplistic — it doesn't handle agent additions/removals between fullsend versions.

Root Cause

The scaffold install path (BuildScaffoldFiles → NewPerRepoConfig) bakes all defaults into config.yaml. This means:

1. User customizations and scaffold-generated defaults are mixed in the same file
2. Re-onboarding must choose between overwriting (losing customizations) or preserving (missing new defaults)
3. Neither approach handles agents added or removed in a new fullsend version

Proposed Solution: Leverage the Existing Three-Tier Layered Config (ADR 0069)

Fullsend already has a three-tier configuration hierarchy designed for exactly this scenario:

config.yaml (overlay, user-owned)  →  config.base.yaml (base, scaffold-managed)  →  code defaults

From the layered-config-reference:

"Upgrading a base layer (e.g., refreshing config.base.yaml) does not require editing config.yaml — the overlay inherits new defaults automatically."

The existing merge semantics already support this:

• Agents use keyed merge by DerivedName() — overlay entries merge with parent entries
• Marshal only emits locally-set values (no leaking of inherited defaults)
• loadExistingPerRepoConfig already reads both config.yaml and config.base.yaml

Required Changes

On initial install (admin install / github setup):

1. Generate config.base.yaml with scaffold defaults (roles, agents, runtime defaults)
2. Generate config.yaml as a minimal overlay — only version: "1" or truly user-specific overrides
3. Users customize agents/settings by editing config.yaml (overlay)

On re-onboarding (re-running install/setup on an existing repo):

1. Regenerate config.base.yaml with the new version's defaults
2. Never touch config.yaml — it is user-owned
3. The layered resolution handles the rest automatically

How This Solves Each Scenario

Scenario	Behavior
New agent added in fullsend upgrade	Appears in regenerated config.base.yaml, automatically visible via fallthrough
Agent removed in fullsend upgrade	Removed from config.base.yaml, no longer in effective config (unless user explicitly added it in overlay)
User customizes an agent (model, effort, runtime)	Override lives in config.yaml overlay, untouched during upgrade
User adds a custom agent	Defined in config.yaml overlay, persists across upgrades
User removes a default agent	Can override with enabled: false in overlay (if supported) or just not reference it in roles

Migration Path

For repos already onboarded with defaults baked into config.yaml:

1. On next re-onboarding, generate config.base.yaml from the new version's defaults
2. Diff the existing config.yaml against config.base.yaml to produce a minimal overlay containing only user customizations
3. Replace config.yaml with the minimal overlay
4. Present this as a clear PR diff showing the split

Environment

• fullsend CLI version: v0.37
• Repository: roming22-org/fullsend-python
• Related PR: fix(#6678): preserve per-repo config on re-onboarding #6679 (initial fix — preserves existing config.yaml verbatim)

[Roming22]

/fs-triage

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 1:02 PM UTC · Completed 1:08 PM UTC

Commit: 73ce2b2 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.30

[fullsend-ai-triage]

Root cause analysis

BuildScaffoldFiles in internal/repos/install.go always generates a fresh config.yaml via config.NewPerRepoConfig() when cfg.PerRepoConfig is nil — which is the standard re-onboarding path. The existing config in the target repo is never read or merged.

The scaffold architecture already has a mechanism to protect user content: layeredDirs in scaffold.go skips agents/, skills/, harness/, policies/, etc. during scaffold walks. However, config.yaml is generated separately in BuildScaffoldFiles and always overwritten.

Related issues

• reconcile-repos.sh: shim reconciliation destroys custom dispatch jobs #703 — similar problem in reconcile-repos.sh destroying custom dispatch jobs
• feat: add migrate-customizations command (ADR-0064) #2971 — migrate-customizations command (ADR-0064), related but distinct migration path

Recommended fix

The install flow should detect re-onboarding (the installed flag already distinguishes upgrade vs fresh install in ScaffoldCommitFunc) and either preserve the existing config.yaml or merge scaffold-managed fields into it. The converge path's driftInstallConfig already has partial awareness of existing state.

Proposed test case

func TestBuildScaffoldFiles_PreservesExistingConfig(t *testing.T) {
    // Setup: existing config with custom roles and runtime
    existingConfig := config.NewPerRepoConfig(
        []string{"triage", "code", "custom-agent"}, "org/repo",
    )
    existingConfig.SetRuntime("custom-runtime")

    cfg := InstallConfig{
        Owner: "org", Repo: "repo",
        Forge: ForgeGitHub,
        Roles: []string{"triage", "code"},  // default roles
        PerRepoConfig: existingConfig,        // should preserve custom
    }

    files, err := BuildScaffoldFiles(cfg)
    require.NoError(t, err)

    // Find config.yaml and verify custom fields survived
    for _, f := range files {
        if f.Path == ".fullsend/config.yaml" {
            assert.Contains(t, string(f.Content), "custom-agent")
            assert.Contains(t, string(f.Content), "custom-runtime")
        }
    }
}

---

Labels: Bug in the scaffold/install code path that destroys user config during re-onboarding — high priority given it blocks adoption workflows.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 1:10 PM UTC · Completed 1:25 PM UTC

Commit: 73ce2b2 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $6.68

[Roming22]

/fs-triage