init-wiki --github silently overwrites Home.md when cloning a wiki that has pre-existing content

[psaboia]

Defect

wiki/init-wiki.sh:204-211 writes a redirect stub into Home.md:

# --- Write Home.md redirect (GitHub wiki landing page) ---
if [[ ! -f "$WIKI_DIR/Home.md" ]] || ! grep -qF "redirect" "$WIKI_DIR/Home.md" 2>/dev/null; then
cat > "$WIKI_DIR/Home.md" << REDIRECTEOF
<!-- redirect: this file exists for GitHub wiki compatibility -->
<!-- The real home page is ${HOME_NS}.md -->
See [${PROJECT_NAME}](${HOME_NS})
REDIRECTEOF
fi

The condition [[ ! -f Home.md ]] || ! grep -qF "redirect" Home.md is intended to be idempotent: leave the file alone on re-runs (where Home.md already has "redirect"), create it on first run (where the file is absent). But it has a third path that is silently destructive:

When init-wiki --github clones an existing GitHub wiki that has a substantive Home.md (no "redirect" marker in it), the script overwrites that file with the stub. No warning, no diff, no opportunity for the user to decline.

When this matters

adopt --apply --github-wiki against a project whose GitHub Wiki was used ad-hoc before adopting the llm-wiki pattern:

• Team had been using GitHub Wiki as a regular wiki, authored Home.md as a real landing page (e.g. project summary, links to other pages).
• They decide to adopt the llm-wiki pattern.
• Run adopt --apply --github-wiki. Phase 2B clones the existing wiki, then init-wiki silently rewrites Home.md with the redirect stub.
• Their original landing-page content is gone, both locally and on push to GitHub.

The pattern's other namespaced files (index_<repo>.md, log_<repo>.md, SCHEMA_<repo>.md) protect against this with the if [[ ! -f ... ]] guard alone (no grep -qF fallback path). Only Home.md has the second condition that triggers destruction.

How it surfaced

Discovered while explaining the GitHub Wiki "first page" UI step for the virgin-adopt quick start (issue #64's Quick start section). For the virgin case, the overwrite is the correct behaviour: the user wrote a placeholder ("test") to materialize <repo>.wiki.git on GitHub, and init-wiki replacing that placeholder with the redirect is what should happen. For the non-virgin case (real Home.md content), the same overwrite is silently destructive.

Bloco 2 manual test of PR #60 against a FUNSD scratch (wiki already materialized with three pre-existing pages) saw the Home.md on disk become 135 bytes after init-wiki ran — the redirect stub, not whatever FUNSD's prior Home.md content may have been. The three other pre-existing pages were preserved correctly; only Home.md was clobbered.

Fix sketches

Option A — preserve and rename. Detect Home.md exists, lacks "redirect", and was likely host-authored (e.g. has substantive content beyond a one-liner). Rename to Home-original.md (or Home.host-authored.md) and then write the redirect stub. Lossless. The host can move content into Home_<repo>.md (the real namespaced home) afterwards, or link to Home-original from there.

Option B — refuse loudly. If Home.md exists and lacks "redirect", lw_die with an explicit message: "Existing Home.md detected at $WIKI_DIR/Home.md. The llm-wiki pattern uses Home.md as a redirect to Home_.md. Either delete Home.md (its content will be lost) or move its content into Home_.md before continuing." Forces the user to make a deliberate choice. Less ergonomic but never destructive without consent.

Option C — diff and prompt (interactive). Show the diff between the existing Home.md and the redirect stub, prompt for [k]eep / [o]verwrite / [m]ove-to-Home_<repo>. Most flexible, but interactive mode is awkward inside adopt --apply which is meant to be scriptable.

Option D — skip if not empty. If Home.md exists with any content, leave it alone. Loses the redirect benefit (GitHub UI users land on the host's old Home.md, not the namespaced one), but never destructive.

Recommendation: Option A (preserve and rename) is the most lossless. It is also the most consistent with the rest of init-wiki's defensive posture (e.g. index_<repo>.md is "create-only-if-absent" — never overwrites). The cost is one extra file in the wiki sub-repo (the renamed original) that the host can clean up at leisure.

A hybrid is possible: Option A by default, with --force-overwrite-home (or similar) restoring the current overwrite behaviour for the case where the host really does want to discard the existing Home.md.

Acceptance

• init-wiki --github against a wiki whose Home.md is substantive and lacks the "redirect" marker either:
  • (a) preserves the original (Option A: rename + write stub; user sees the rename in the adopt log), OR
  • (b) refuses with a loud error pointing at the exact file and the resolution path (Option B), OR
  • (c) some other non-destructive resolution.
• The virgin case continues to work: a tiny placeholder Home.md (from a one-time UI step) is replaced by the redirect stub without ceremony.
• Idempotency holds: re-running adopt or init-wiki against a wiki that already has the redirect Home.md is a no-op.
• A test fixture under scripts/test/tests/integration/ or scripts/test/tests/smoke/ exercises both paths (virgin vs non-virgin Home.md) and asserts the appropriate outcome for each.

Context

Pre-existing defect, predates PR #60 and the manifest consolidation. Surfaced during the documentation pass for issue #64 (quick start for the virgin-adopt case) while explaining what the "first page in the UI" placeholder content becomes after adopt: it gets overwritten. That answer is correct for the virgin case but exposes the silent destruction for the non-virgin case.

Adopt-side flow that triggers this: adopt --apply --github-wiki against a host whose GitHub Wiki has already been used ad-hoc. The init-wiki --github invocation in adopt's Phase 2B is where the overwrite happens.

Refs: PR #60 (manifest introduction; the manual adoption test surfaced this), #64 (the quick start that documents the virgin-case overwrite as expected behaviour and needs to flag the non-virgin destruction once this is fixed), #63 (the Next steps block could include "your previous Home.md content was preserved at Home-original.md" if Option A is chosen).

[psaboia]

Confirmation in the wild (real adoption on 2026-06-28)

Adopted PR #60's adopt --apply --github-wiki on an existing GitHub-hosted host repo whose wiki had been materialized via UI in the past but never substantively used. The wiki on GitHub contained only the default placeholder GitHub auto-generates when the wiki is created (Welcome to the <project> wiki!). init-wiki --github cloned the wiki and silently overwrote that placeholder with the redirect stub.

Verified directly in the wiki sub-repo after adopt completed:

$ git -C wiki/<project>.wiki/ log --oneline -- Home.md
<sha-init-wiki> Initialize wiki with llm-wiki pattern (namespaced)
<sha-original> Initial Home page
$ git -C wiki/<project>.wiki/ show HEAD~1:Home.md
Welcome to the <project> wiki!
$ cat wiki/<project>.wiki/Home.md
<!-- redirect: this file exists for GitHub wiki compatibility -->
<!-- The real home page is Home_<project>.md -->
See [<project>](Home_<project>)

In this case the overwrite was harmless — the original content was GitHub's default placeholder, not author-curated content. But this is exactly the silent-destruction mechanism the issue describes. If the adopter had used the GitHub Wiki for any substantive content before adopting llm-wiki (a project summary, a quickstart, links to other pages), that content would have been silently replaced by the redirect stub. The only record would be the HEAD~1 commit on the wiki sub-repo — the adopter has to know to look there.

This confirms the defect is real on the live adopt path (not just a theoretical concern from reading init-wiki.sh). Strengthens the case for Option A (preserve-and-rename) over Option D (skip-if-not-empty), because:

• Option A: the adopter sees a Home-original.md (or similar) on disk after adopt, making the rename discoverable and recoverable without git archaeology.
• Option D: would have left the original Welcome to the <project> wiki! placeholder in place, blocking the redirect stub from doing its job (GitHub UI would land users on the placeholder, not on the namespaced Home_<project>.md).

Option A is lossless AND preserves the redirect behaviour. Recommendation stands.

Source: this finding surfaced during the PR #60 manual adoption dogfood, which was conducted on a real host (anonymized here) following the Quick start recipe in issue #64.