adopt.sh: lw_die for --agent=cursor references closed issue #6 (broken anchor)

[psaboia]

Defect

scripts/adopt.sh:289 refuses --agent=cursor with:

case "$AGENT" in
    claude-code|none) ;;
    cursor)
        lw_die "agent 'cursor' is not yet supported (see issue #6, deferred)"
        ;;
    ...

Issue #6 was the original design issue for adopt.sh (adopt.sh: let an existing repository adopt llm-wiki-memory). It is now CLOSED — the design was implemented and merged. The lw_die message points readers at a closed issue that describes adopt's overall shape, not the deferred cursor work specifically. Anyone who runs adopt --agent=cursor hits the error, follows the link, and lands on a closed design issue that does not explain what is still pending or how to contribute the missing piece.

Why it surfaced now

During PR #60 review-resolution, while drafting the ADOPTING.md spec for issue #64 (recipe with explicit --agent=claude-code), the asymmetry between instantiate (accepts cursor, all) and adopt (refuses cursor) surfaced. Verified that #6 is closed; the lw_die's anchor went stale when #6 closed.

Fix sketches

Option A — repoint at a live issue (this one). Update line 289 to reference this issue (the new number, once filed):

lw_die "agent 'cursor' is not yet supported (see issue #65)"

This issue then becomes the canonical landing for the work: anyone arriving here sees the state, the fix sketches, and the path to picking up cursor support in adopt.

Option B — drop the issue reference entirely. Keep just the not yet supported message. Loses the "where to contribute" hint but never goes stale again.

Option C — repoint at the cursor overlay README (wiki/agents/cursor/README.md). Less useful because that README documents the overlay's use, not adopt's pending cursor support.

Option A is preferred. The lw_die message is the only on-ramp for anyone interested in cursor adopt support; pointing it at a live anchor with sketch + acceptance lets a contributor pick up the work without re-discovering the context.

Sub-question: what would "cursor support in adopt" actually entail

If someone picks up this issue, the surface includes:

• Remove the parser refusal at adopt.sh:289
• Verify lw_manifest_assemble_active_files "" "cursor" produces the expected union (TEMPLATE_SHARED_INFRA + TEMPLATE_OVERLAY_CURSOR). The manifest accessor already supports --agent=cursor in agent mode (see PR template-manifest: single source of truth for template-owned files #60); only adopt's parser blocks it.
• Audit Phase 2B's overlay setup: adopt invokes wiki/agents/$AGENT/setup.sh — confirm wiki/agents/cursor/setup.sh exists and exposes the same interface (--hook subcommand for .claude/settings.json merge analog, etc.). The Cursor overlay's hook story may differ from Claude Code's; this is the place where the asymmetry needs to be reconciled.
• Validate end-to-end on a real adopt scenario. Per README.md "Status" section: Only the Claude Code path has been validated end-to-end. Cursor overlay is shipped but unvalidated in a live session. Cursor adopt adds a new layer to that unvalidated surface; the validation gap should be acknowledged in the same way.

Acceptance

• adopt.sh:289's lw_die references a live issue (this one) or whichever live anchor the team prefers.
• If Option A: this issue stays open as the "cursor support in adopt" anchor. If Option B: lw_die is updated and this issue can close.
• No regression in existing adopt tests (no test currently exercises --agent=cursor since it is refused; a future cursor-support PR adds the fixture).

Context

Trivially fixable defect (one-line change to lw_die) surfaced during the documentation pass for issue #64. Filed as a separate issue because it is independent of the manifest consolidation, the docs runbook, and the other PR #60 follow-ups (#61–#64) — its only relationship to PR #60 is "the manifest already supports cursor in its accessor; only adopt's parser blocks it."

Refs: PR #60 (manifest's lw_manifest_assemble_active_files already handles agent=cursor), issue #6 (closed design issue currently referenced by lw_die), issue #64 (where this defect surfaced).

[psaboia]

Empirical validation of the Cursor overlay (live session, 2026-06-30)

Tested the Cursor overlay end-to-end on a real GitHub-hosted host that had already adopted via --agent=claude-code. Cursor overlay artifacts were installed manually (workaround for this issue's parser refusal): fresh template-main clone, copy .cursor/rules/*.mdc with {{REPO_NAME}} substituted, copy wiki/agents/cursor/, run bash wiki/agents/cursor/setup.sh. The setup script was idempotent on CLAUDE.md — claude-code had already injected the sentinels, cursor's setup detected presence and skipped.

What Cursor reported as loaded on session open

• Always-applied workspace rules:
  • wiki-as-memory.mdc (proactive read/write context)
  • CLAUDE.md (Cursor treats CLAUDE.md as a global rule, so the project's Conventions section reaches Cursor too)
• Agent-requestable workspace rules: wiki-experiment.mdc, wiki-source.mdc, wiki-lint.mdc (fetched on demand or @-mention — the correct Cursor convention for non-always rules)

Behavioural validation (4 tests)

Test 1 — proactive read ("What does SCHEMA say about page types?")
Cursor opened SCHEMA_<repo>.md and returned the actual table verbatim (types, required-structure pages with their constraints, frontmatter contracts). No fabrication. wiki-as-memory.mdc produces proactive read behaviour. ✅

Test 2 — link discipline without explicit reminder ("What's the state of develop and the last merged PR?")
Cursor cited real SHAs, real PR numbers, real authors, with inline canonical URLs like [PR #N](https://github.com/<owner>/<repo>/pull/N) and [<sha>](https://github.com/.../commit/<sha>). The link discipline came from the host's CLAUDE.md ## Conventions when editing section (custom, added per this host's policy); Cursor honoured it automatically without the prompt asking for it. ✅

Test 3 — @wiki-experiment write ("@wiki-experiment register develop branch state. Apply link discipline.")
Cursor:

• investigated with real git log + gh pr view
• proposed a type: synthesis page with up:, related:, tags: frontmatter
• applied link discipline body-wide (14 canonical https://github.com/... URLs in the final page — every PR, commit, branch name linked)
• updated index_<repo>.md with the new entry
• appended a ## [YYYY-MM-DD] ingest | ... log entry
• committed in two separate commits (page+index, then log) — the one-commit-per-log-entry rule was honoured
• did NOT push (correctly held for explicit OK)

✅ end-to-end functional.

Test 4 — honest reporting acid test
Cursor referenced an open PR in its output. gh pr view <num> against the host confirmed the PR exists, with the same title/state/refs Cursor quoted. No fabrication. ✅

Two minor observations (non-blocking)

1. Commit without asking: Cursor committed in the wiki sub-repo without a pre-commit stop-and-confirm checkpoint. Initial concern, but this is the designed behaviour per CLAUDE.md.template's lw:wiki-maintenance section: "Execute these without asking — local commits in the wiki repo are trivially reversible. Push only when explicitly asked." Claude Code overlay behaves the same way. The stop-and-confirm gates live at PUSH, not COMMIT.

2. Rhetorical "prior snapshot" framing: Cursor's response narrated the write as "refreshed to 's snapshot" and mentioned changes "from the prior 's snapshot", but no such prior snapshot existed on disk (this was the first creation of the page). Not a factual fabrication (no fake SHAs/PR numbers) — closer to rhetorical framing. Worth tightening in the .cursor/rules/wiki-experiment.mdc spec: a sentence like "do not narrate updates relative to states that do not exist in git history."

Bearing on this issue

• Cursor overlay itself works end-to-end: validation gap from the template's README Status ("shipped but unvalidated in a live session") is now closed with empirical evidence.
• Adopt's --agent=cursor refusal is the remaining blocker in this issue's scope. The manual install workaround (copy files + substitute + run setup) is functional but is a workaround. Resolving this issue means making adopt --apply --agent=cursor (and the "add cursor on top of an existing adoption" variant) accept and install the same artifacts the manual workaround installs — the manifest accessor lw_manifest_assemble_active_files "" "cursor" already returns the correct file set (per PR template-manifest: single source of truth for template-owned files #60).

Concrete suggestion

The fix for this issue is not strictly a one-line change. It needs three parts:

1. Remove the parser refusal at adopt.sh:289 (the lw_die for cursor). One line.

2. Decide the semantics for the realistic case: hosts that already adopted with --agent=claude-code and want to add cursor on top (the scenario empirically validated above). Two options:

   • (a) Reuse --force: adopt --apply --force --agent=cursor. Composite detector aborts on the 2-of-3 signal match unless --force is passed; classifier then runs additively (SHARED + OVERLAY_CLAUDE → SKIP, OVERLAY_CURSOR → ADD, HOST_OWNED → idempotent on sentinels). Smaller surface, less explicit semantics.

   • (b) New flag --add-agent=cursor: explicit semantic of "extending an existing adoption with a new agent overlay"; bypasses the composite detector without --force. Cleaner semantics, more design surface.

3. Two integration fixtures, not one:

   • adopt-apply-cursor-virgin: brand-new host, --apply --agent=cursor
   • adopt-apply-cursor-onto-claude-code: host that already adopted with claude-code, command per the semantics chosen in (2)

The behavioural validation of the cursor overlay itself (whether the rules load and produce correct behaviour) is no longer a question per the live test above; the open work is the adopt entry-point.

A follow-up PR could update the template's README Status from "shipped but unvalidated" to "validated end-to-end on a real adopting project (); rules load automatically, link discipline applied, honest reporting honoured."

[psaboia]

Retraction of one observation in the validation comment above

In the earlier validation comment, I flagged two non-blocking observations. The second one — that Cursor narrated a "prior 2026-06-29 snapshot" of Develop-Branch-State.md that did not exist on disk, calling this "rhetorical framing of first creation as if it were an update" — was wrong on my side, not Cursor's.

Verified after the fact by running git log --all --oneline -- Develop-Branch-State.md against the host's wiki sub-repo:

12bd82b 2026-06-30 02:27:28 -0400 update: Develop-Branch-State snapshot 2026-06-30 with link discipline
02d4bfc 2026-06-29 14:35:44 -0400 Record develop branch state snapshot (2026-06-29): HEAD b25c3a2, last PR #77, divergence from master

The 2026-06-29 commit 02d4bfc is the real prior snapshot Cursor was referencing. Cursor's narration was accurate; my observation was a projection (I assumed there was no prior page without checking the git log of the wiki sub-repo).

What this changes:

• The empirical validation of the Cursor overlay still stands — all four tests passed.
• Only one minor observation remains (commit-without-asking is the designed behaviour, not a defect).
• The "tighten .cursor/rules/wiki-experiment.mdc to forbid narrating updates relative to non-existent prior states" follow-up is retracted — there is no defect to fix; Cursor was correct.

The Cursor-Overlay-Validation analysis page on the template's wiki carries this retraction in its history (see commits 089dd22 page correction and 9468647 log entry on crcresearch/llm-wiki-memory-template.wiki); the page now records the correction explicitly rather than silently removing the original observation, so future readers see the correction was made.

Carrying this forward as a lesson: the Verification-Gate's "no projections, only real script outputs" clause currently focuses on numerical claims in the page body. The original retracted observation passed the gate because it concerned agent behaviour, not page numbers. A natural follow-up is to extend the gate's scope: any claim that could have been verified against a real artefact before being asserted (here, the wiki sub-repo's git log) belongs in the same category as numerical claims. Filed as new follow-up #4 on the Cursor-Overlay-Validation page.