adopt.sh: --github-wiki flag (port from instantiate.sh) + README alias snippet by psaboia · Pull Request #59 · crcresearch/llm-wiki-memory-template

psaboia · 2026-06-28T01:37:47Z

Context

Closes the UX gap PR #51 (adopt orchestrator) and #55 (default grants) left open: adopting an existing repo still required four manual github.com clicks (enable Wikis, seed the first page via UI, wire the wiki remote, push) before the wiki sub-repo could be published. scripts/instantiate.sh already automates this dance via --github-wiki for projects created from the template.

Chris recommended (Slack, 2026-06-27) shipping --github-wiki on adopt instead of building a separate gh extension: the bundle case for an extension (version pinning, migrate-existing-wiki) isn't justified yet since neither has emerged as recurring demand.

Planning trail and scope are in /home/pmoreira/.claude/plans/cozy-soaring-honey.md.

What this PR ships

`scripts/adopt.sh`

New --github-wiki flag (declaration, usage, parser).
New Phase 2B sub-step between init-wiki and overlay setup. When the flag is passed:
- Derives wiki URL via lw_origin_url + lw_wiki_url.
- Attempts a seed-push to materialize <repo>.wiki.git (mirrors instantiate.sh:486-499).
- On success: invokes init-wiki.sh --github so it clones the now-real wiki.
- On 404 (GitHub's "first page must exist via UI" architecture quirk): captures GITHUB_WIKI_STATUS=failed, prints the workaround on stderr via new _github_wiki_fallback_message helper, falls back to local init-wiki. Adopt remains exit 0, additive contract preserved.
Non-github origins (gitlab.com, self-hosted) soft-skipped via inline host check BEFORE lw_wiki_url is called (avoids its lw_die).
Missing origin remote soft-skipped.
Dry-run (--github-wiki without --apply) runs read-only probes and emits a new GITHUB WIKI section with would-apply / would-skip status. No mutation.
Manifest gains - github-wiki: <status> (<detail>) line. Status vocabulary: applied | wiki-already-materialized | failed | skipped (five distinct skip reasons enumerated).

Three new integration fixtures

Fixture	Tests
`adopt-apply-github-wiki-no-origin`	Soft-skip when host has no `origin`. Init-wiki local fallback. No 404 message on stderr.
`adopt-apply-github-wiki-fake-origin`	Seed-push 404 capture. Manifest reports `failed (seed-push 404; GitHub UI step required ...)`. Workaround block on stderr names the re-run command pointing at `adopt.sh` (not `instantiate.sh`). Init-wiki local fallback.
`adopt-apply-github-wiki-non-github-origin`	Inline host check catches `gitlab.com` BEFORE `lw_wiki_url` runs (so `lw_die` is never triggered). Manifest reports `skipped (non-github host 'gitlab.com')`.

Observe-the-failure mutations

Three targeted mutations applied during development; each turns the right assertions red and only those:

Remove the empty-origin soft-skip branch → no-origin fixture turns red as expected.
Remove the inline non-github host check → non-github fixture turns red AND surfaces a hidden expectation: lw_wiki_url dies inside command substitution but the script continues with empty _wiki_url, garbage-cascading. The inline check is load-bearing for correctness, not just politeness.
Remove the fallback-message call → fake-origin fixture's stderr assertions turn red.

Revert → 25/25 green.

End-to-end verification

Real virgin host (Linux): scratch clone of crcresearch/FUNSD with a fake-github origin, --apply --github-wiki. Result:

- init-wiki: applied (ran wiki/init-wiki.sh --repo-name funsd-adopt-test)
- github-wiki: failed (seed-push 404; GitHub UI step required (open <repo>/wiki, create Home, re-run --github-wiki))

Note init-wiki shows NO --github flag — local fallback fired. Adopt exit 0. Dry-run separately verified: GITHUB WIKI (--github-wiki preview; read-only) section appears with would-apply (seed-push to ... wiki.git (master); wiki not yet materialized).

`README.md`

New section 3 "Adopt the pattern into an existing project" with the common adoption flow, --github-wiki behavior, and the alias snippet:

alias adopt='bash ~/src/llm-wiki-memory-template/scripts/adopt.sh --target=.'
# Then: cd <project> && adopt --apply --github-wiki

Old sections 3-9 renumbered to 4-10. Forward references updated.

Reuse points (no helper changes needed)

lw_origin_url, lw_wiki_url, lw_repo_slug from scripts/lib/git.sh.
wiki/init-wiki.sh --github mode (already shipped).
command -v gh guard pattern from instantiate.sh.
Manifest status-capture idiom (INIT_WIKI_STATUS, INIT_WIKI_DETAIL).

Out of scope (deferred)

gh extension wrapper (defer until version-pinning or migrate-existing-wiki demands materialize).
Auto-pushing the wiki sub-repo content after init-wiki --github clones it (instantiate also leaves this manual; same precedent).
template-manifest.sh consolidation (Open Question Attribute every wiki log entry to a user, one commit per log entry #4 in the design page; tracked separately).

Test plan

Three new fixtures: 25/25 green, 3 mutations turn the right assertions red.
Full local suite: 728 pass / 30 fail (baseline SCHEMA pre-existing). Zero regression from main (703 → 728, +25 from new fixtures).
End-to-end on Linux against a real virgin host (FUNSD scratch with fake-github origin).
CI green on all 5 jobs (Linux × 3 git versions + ubuntu-latest + macOS).
End-to-end on macOS bash 3.2.57 against chrissweet/FHI360_Lite (separate confirmation script for Priscila).

Co-authored-by: Priscila Saboia Moreira pmoreira@nd.edu

…s snippet Closes the UX gap that PRs #51 and #55 left open: adopting an existing repo still required four manual github.com clicks (enable Wikis, seed the first wiki page via UI, wire the wiki remote, push) before the wiki sub-repo could be published. The same dance was already automated by `scripts/instantiate.sh` for projects created from the template. Chris recommended (Slack, 2026-06-27) shipping --github-wiki on adopt instead of building a separate `gh` extension: the bundle case for an extension (version pinning, migrate-existing-wiki) isn't justified yet since neither has emerged as recurring demand. What this PR does scripts/adopt.sh: - New --github-wiki flag (declaration, usage text, case parser). - New Phase 2B sub-step: between init-wiki and overlay setup. When the flag is passed, derives the wiki URL via lw_origin_url + lw_wiki_url, attempts a seed-push to materialize <repo>.wiki.git on GitHub (mirrors instantiate.sh:486-499), and on success invokes init-wiki.sh with --github so it clones the now-real wiki. On the GitHub architecture quirk (first wiki page must exist via UI), seed-push returns 404 and adopt captures it into GITHUB_WIKI_STATUS=failed, prints the workaround on stderr via a new _github_wiki_fallback_message helper, and falls back to local init-wiki -- adopt remains exit 0, additive contract preserved. - Non-github origins (gitlab.com, self-hosted git) soft-skipped via an inline host check BEFORE lw_wiki_url is called (which would otherwise lw_die and crash the whole script). - Missing origin remote soft-skipped. - Dry-run (--github-wiki without --apply) runs read-only probes only (lw_origin_url, host check, lw_wiki_url, git ls-remote) and reports a 'would-apply' or 'would-skip' status in a new GITHUB WIKI section of the dry-run report. No mutation. - Manifest gains a '- github-wiki: <status> (<detail>)' line after the init-wiki line. Status vocabulary: applied | wiki-already-materialized | failed | skipped (with five distinct skip reasons enumerated in the detail). Three new integration fixtures: - adopt-apply-github-wiki-no-origin: virgin host without origin; verifies soft-skip + init-wiki local fallback + no workaround on stderr. - adopt-apply-github-wiki-fake-origin: virgin host with fake github URL; verifies seed-push 404 capture + workaround on stderr + init-wiki local fallback + manifest contains exact 'failed (seed-push 404; GitHub UI step required ...)' detail. - adopt-apply-github-wiki-non-github-origin: virgin host with gitlab origin; verifies inline host check catches the case BEFORE lw_wiki_url is invoked + manifest reports skipped (non-github host 'gitlab.com') with exact text. Mutation discriminators (observe-the-failure): replacing the empty-origin guard, the inline non-github host check, or the fallback-message call each turns the right assertions red across the relevant fixture and only those; revert returns 25/25 green. End-to-end on a real virgin host (Linux): scratch clone of crcresearch/ FUNSD with a fake-github origin, --apply --github-wiki. Manifest reports 'github-wiki: failed (seed-push 404; ...)' AND 'init-wiki: applied (ran wiki/init-wiki.sh --repo-name funsd-adopt-test)' (note: no --github flag, confirming local fallback fired). Exit 0. Dry-run separately verified to report the prospective status in the GITHUB WIKI section. Full local suite: 728 pass, 30 fail (baseline SCHEMA pre-existing) -- zero regression from main (which was 703 pass; +25 from the new fixtures). README.md: - New section 3, 'Adopt the pattern into an existing project', explaining the common adoption flow with --github-wiki and an alias snippet for power users who adopt multiple projects from one machine. Old sections 3-9 renumbered to 4-10. Reuse points (no helper changes needed): - lw_origin_url, lw_wiki_url, lw_repo_slug from scripts/lib/git.sh. - wiki/init-wiki.sh --github mode (already shipped). - 'command -v gh' guard pattern from instantiate.sh. - Manifest status-capture idiom (INIT_WIKI_STATUS, INIT_WIKI_DETAIL). Out of scope (deferred): - gh extension wrapper (defer until version-pinning or migrate-existing- wiki demands materialize). - Auto-pushing the wiki sub-repo content after init-wiki --github clones it (instantiate also leaves this manual; same precedent). - template-manifest.sh consolidation (Open Question #4 in the design page; tracked separately). Co-authored-by: Priscila Saboia Moreira <pmoreira@nd.edu>

psaboia · 2026-06-28T01:52:56Z

End-to-end macOS bash 3.2.57 verification against chrissweet/FHI360_Lite — all three scenarios pass.

Ran on Priscila's macOS, HEAD dadd4c4. Three scratch clones of the same fork Chris used to write the PR #51 review, exercising the no-origin soft-skip, the 404 fallback, and the dry-run preview.

Test GW-A — virgin clone with NO origin (soft-skip path):

--- --apply --github-wiki ---
Applied: 28 file(s) created in .../testGWA
RC=0

--- manifest github-wiki + init-wiki lines ---
- init-wiki: applied (ran wiki/init-wiki.sh --repo-name testGWA)
- github-wiki: skipped (no origin remote on target; cannot derive wiki URL)

Init-wiki invocation has no --github flag, confirming the local fallback fired correctly.

Test GW-B — virgin clone with fake-github origin (the 404 path the workaround targets):

--- --apply --github-wiki ---
  1. Open https://github.com/example-org-fake/fhi360-gw-test/wiki in a browser.
  2. Click "Create the first page", title "Home", any content, save.
  3. Re-run: bash scripts/adopt.sh --target=.../testGWB --apply --github-wiki

Or, to skip GitHub Wiki entirely and use a local-only wiki, omit --github-wiki.

Applied: 28 file(s) created in .../testGWB
RC=0

--- manifest github-wiki + init-wiki lines ---
- init-wiki: applied (ran wiki/init-wiki.sh --repo-name fhi360-gw-test)
- github-wiki: failed (seed-push 404; GitHub UI step required (open <repo>/wiki, create Home, re-run --github-wiki))
init-wiki does NOT contain --github flag (local fallback): YES

Notable: the re-run hint in the workaround block points at scripts/adopt.sh, not instantiate.sh. The _github_wiki_fallback_message helper parameterized that hint correctly.

Test GW-C — dry-run preview:

--- dry-run --github-wiki ---
GITHUB WIKI (--github-wiki preview; read-only)
  would-apply (seed-push to https://github.com/example-org-fake/fhi360-gw-preview.wiki.git (master); wiki not yet materialized)

--- manifest NOT written (dry-run): YES

Read-only probes work; no side effects.

Coverage summary:

Item	Linux	macOS bash 3.2.57
no-origin soft-skip	fixture + CI	Test GW-A on FHI360_Lite
404 fallback (additive)	fixture + CI + scratch FUNSD	Test GW-B on FHI360_Lite
dry-run preview	fixture + scratch FUNSD	Test GW-C on FHI360_Lite
non-github host inline guard	fixture + CI	(covered by fixture, not separately on macOS)

All five CI jobs (Linux × 3 git versions + ubuntu-latest + macOS-latest) green at dadd4c4. Ready to mark ready-for-review whenever Priscila is comfortable.

Adds two fixtures closing review-resolution gaps before marking PR #59 ready: adopt-apply-github-wiki-agent-none — verifies the github-wiki dispatch is agent-orthogonal. The seed-push runs (or fails with the 404 fallback) regardless of --agent=none. The overlay setup and its delegated TOUCH grants (CLAUDE.md managed-block, .claude/settings.json merge) skip with the --agent=none reason; the .gitignore append-only TOUCH still runs because it does not delegate to the overlay. 13 assertions. adopt-dryrun-github-wiki — verifies the dry-run preview block emits the GITHUB WIKI section with the prospective status (would-apply / would-skip), and that the host is NOT mutated: no manifest, no ADD files, no .gitignore change, no .claude/ directory. 13 assertions. Mutation discriminators driven on both fixtures: - Removing the dry-run preview block turns the dry-run fixture's GITHUB-WIKI assertions RED. - Adding an && AGENT != none guard to the github-wiki dispatch turns the agent-none fixture's manifest + stderr assertions RED. Revert returns 26 of 26 green. Full local suite: 754 pass / 30 fail (the 30 are pre-existing SCHEMA failures; +26 from the new fixtures over the prior 728). Also fills a documentation gap: wiki/Adopt-Existing-Repo-Design page gains a new 'Decision: --github-wiki flag' section recording the behavior matrix, the inline non-github host check, the dry-run preview semantics, the agent-orthogonality reasoning, and an empirical dry-run sweep across 9 real repos. Wiki commit: 3df0c7f. Co-authored-by: Priscila Saboia Moreira <pmoreira@nd.edu>

Temporary manual test script for Priscila to run on macOS bash 3.2.57 against chrissweet/FHI360_Lite. Exercises the two new fixtures from the review-resolution round end-to-end on a real host: - GW-D: --apply --github-wiki --agent=none - GW-E: dry-run --github-wiki (no --apply) Will be reverted in the next commit; not part of the merge target.

…w-resolution real-repo run) The script at scripts/test/manual/fhi360-gw-newfixtures.sh was pushed temporarily so Priscila could pull and run it on macOS to verify the two new review-resolution fixtures end-to-end against chrissweet/ FHI360_Lite. Both tests passed: GW-D (--apply --github-wiki --agent=none): RC=0; manifest reports github-wiki failed (seed-push 404), init-wiki applied without --github (local fallback), overlay setup skipped (--agent=none), CLAUDE.md (managed-block) and settings.json (merge) TOUCH grants skipped, .gitignore (append-only) created from canonical. GW-E (dry-run --github-wiki): GITHUB WIKI preview section emits would-apply with the prospective wiki URL; manifest NOT written, llm-wiki.md NOT copied, wiki sub-repo NOT created, .claude/ NOT created. Removing the script now that the verification is complete and recorded in the PR comment. Co-authored-by: Priscila Saboia Moreira <pmoreira@nd.edu>

psaboia · 2026-06-28T03:18:45Z

Review-resolution gap closure: real-repo end-to-end on Linux + macOS bash 3.2.57 for the two new fixtures.

After the original PR #59 round, two new fixtures were added in commit c334985 to close gaps:

adopt-apply-github-wiki-agent-none — verifies the github-wiki dispatch is agent-orthogonal (the wiki is useful regardless of --agent)
adopt-dryrun-github-wiki — verifies the dry-run preview path that no end-to-end test had covered before

Both fixtures green locally (754 pass / 30 baseline) and on CI. To close the discipline check, both were also exercised end-to-end against real hosts.

Linux real-repo (crcresearch/FUNSD scratch with fake-github origin):

Test D-Linux — --apply --github-wiki --agent=none:

- init-wiki: applied (ran wiki/init-wiki.sh --repo-name funsd-agent-none-gw)
- github-wiki: failed (seed-push 404; GitHub UI step required ...)
- overlay setup: skipped (--agent=none, no overlay to set up)

TOUCH applied (3):
  - CLAUDE.md (managed-block): skipped (--agent=none, ...)
  - .gitignore (append-only): applied
  - .claude/settings.json (merge): skipped (--agent=none, ...)

All 8 verification points pass: CLAUDE.md has no lw:memory-boundary sentinel; .claude/settings.json not created; .gitignore got the wiki rule (append-only TOUCH ran without the overlay); init-wiki has no --github flag (local fallback after 404).

macOS bash 3.2.57 real-repo (chrissweet/FHI360_Lite scratch with fake-github origin):

Test GW-D — --apply --github-wiki --agent=none:

- init-wiki: applied (ran wiki/init-wiki.sh --repo-name fhi360-gw-agent-none)
- github-wiki: failed (seed-push 404; ...)
- overlay setup: skipped (--agent=none, no overlay to set up)

TOUCH applied (3):
  - CLAUDE.md (managed-block): skipped (--agent=none, ...)
  - .gitignore (append-only): created from canonical
  - .claude/settings.json (merge): skipped (--agent=none, ...)

8 of 8 verification points pass.

Test GW-E — dry-run --github-wiki:

GITHUB WIKI (--github-wiki preview; read-only)
  would-apply (seed-push to https://github.com/example-org-fake/fhi360-gw-dryrun-preview.wiki.git (master); wiki not yet materialized)

Manifest NOT written, llm-wiki.md NOT copied, wiki sub-repo NOT created, .claude/ NOT created, host preserved.

Coverage matrix across all 5 fixtures:

Fixture	Synthetic CI	Linux real-repo	macOS bash 3.2.57 real-repo
`adopt-apply-github-wiki-no-origin`	✓	(sweep)	✓ (initial round)
`adopt-apply-github-wiki-fake-origin`	✓	✓ FUNSD	✓ FHI360_Lite (initial round)
`adopt-apply-github-wiki-non-github-origin`	✓	(sweep)	(initial round)
`adopt-apply-github-wiki-agent-none`	✓	✓ FUNSD	✓ FHI360_Lite
`adopt-dryrun-github-wiki`	✓	(sweep)	✓ FHI360_Lite

Plus the dry-run preview sweep across 9 real repos (FUNSD, team-ai-Engineering, p28-behavioral-test, pad-analytics-workshop, pad-ml-pipeline, tai_ner, CSE-60868, llm-wiki-branch-test, markov_embeddings_and_rag) — covered in commit c334985 and recorded in the wiki page.

scripts/test/manual/fhi360-gw-newfixtures.sh was pushed in 8b3906e only as a vehicle for the macOS run and reverted in e1871df. Not part of the merge target.

chrissweet · 2026-06-28T14:19:42Z

macOS bash 3.2.57(1) verification done (macOS 15.4.1 arm64) against chrissweet/FHI360_Lite (which has a populated wiki from yesterday's migration):

Dry-run GITHUB WIKI preview: would-skip (wiki already materialized ...; would clone via init-wiki --github)
Apply manifest: - github-wiki: wiki-already-materialized (https://github.com/chrissweet/FHI360_Lite.wiki.git responds; skipping seed push)
init-wiki invoked with the --github flag — clone-mode confirmed end-to-end
Wiki sub-repo: 19 files (14 migrated pages + 5 scaffold), origin wired to chrissweet/FHI360_Lite.wiki.git, git log shows yesterday's migrate: commit + the scaffold commit
Standard adoption alongside: 28 files added, 3 TOUCH grants fired (created from canonical), overlay setup applied
Exit 0, no bash 3.2 issues

Bonus data point: wiki-already-materialized is the one status your hermetic fixtures don't directly exercise (the fake-origin fixture covers the 404 path, the non-github fixture covers the inline check, but a real responsive remote isn't easily faked). This run exercises it. Last checkbox closed.

psaboia added 3 commits June 27, 2026 23:00

psaboia marked this pull request as ready for review June 28, 2026 03:20

psaboia merged commit 3b0619a into main Jun 28, 2026
10 checks passed

psaboia deleted the feature/adopt-github-wiki branch June 28, 2026 03:24

This was referenced Jun 28, 2026

template-manifest: single source of truth for template-owned files #60

Merged

instantiate.sh & adopt.sh: closing-message guidance + CLAUDE.md content + README announcement gaps after bootstrap #63

Open

Navigation Menu

Uh oh!

adopt.sh: --github-wiki flag (port from instantiate.sh) + README alias snippet - #59

adopt.sh: --github-wiki flag (port from instantiate.sh) + README alias snippet#59
psaboia merged 4 commits into
mainfrom
feature/adopt-github-wiki

psaboia commented Jun 28, 2026

Uh oh!

psaboia commented Jun 28, 2026

Uh oh!

psaboia commented Jun 28, 2026

Uh oh!

Uh oh!

chrissweet commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

psaboia commented Jun 28, 2026

Context

What this PR ships

scripts/adopt.sh

Three new integration fixtures

Observe-the-failure mutations

End-to-end verification

README.md

Reuse points (no helper changes needed)

Out of scope (deferred)

Test plan

Uh oh!

psaboia commented Jun 28, 2026

Uh oh!

psaboia commented Jun 28, 2026

Uh oh!

Uh oh!

chrissweet commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`scripts/adopt.sh`

`README.md`