Handover 2026-04-22 — SSOT consolidation

Epic: neid404/fragjulia#640 Sub-issues: #641–#649 Status at handover: Scaffolding delivered to local working tree; nothing merged yet. PAT rotation is the only urgent open item.

---

What the session was about

The user (Dave / @neid404) came in flagging three connected problems: OneDrive was still being written to by some session, MCP connectors were "escalating" (repeatedly prompting for OAuth auth), and documentation + repo state had drifted across many locations. The explicit ask was: write a plan for a monolithic source of truth at docs.fragjulia.de, MDX-based, with a changelog, and a rule that no GitHub issue closes without documentation.

The plan I wrote (and the user approved) is now split across epic #640 and the nine linked sub-issues. This handover document is the narrative version of that plan.

What I discovered (the actual state of things)

Five parallel clones of the fragjulia repo

Each on a different branch, each with its own work:

Plus one snapshot dump (no .git/, had deleted-lock-file.zip) at ~/.claude/Github-fragJulia Repo/fragjulia-main/.

SSOT-3 (#643) collapses all of these into C:\code\fragjulia with a git worktree per active branch.

OneDrive leakage (active, not historical)

The user had already redirected the Windows Personal (Documents) shell folder out of OneDrive via reg add (visible in ~/.claude/settings.local.json backups). That worked — new default-path writes land locally. But C:\Users\dapar\OneDrive\Dokumente\Claude\Projects\fragJUlia\ contained nine HANDOFF-*.md / design-delta files written that same day (2026-04-22). Some session was writing there explicitly, not via the default Documents path. SSOT-4 (#644) migrates these into the docs site and removes the entire OneDrive/Dokumente/Claude/ tree to force the bad source to surface.

PAT leaked in five places (three illegitimate)

github_pat_11B5QNT2Q01I1yUDpCTNkg_*:

SSOT-1 (#641) covers the rotation. The learning — "PAT never in allowedTools" — is saved as a local feedback memory at ~/.claude/projects/C--Users-dapar/memory/feedback_pat_never_in_allowlist.md.

MCP auth churn

~/.claude/mcp-needs-auth-cache.json showed three cloud-configured (claude.ai) OAuth connectors stuck in needs-auth state: Hugging Face, Stripe, Atlassian Rovo. None are in the product stack; they just re-prompt every session. SSOT-2 (#642) disables them in claude.ai connector settings — the only sub-issue Claude cannot execute itself.

Also: ENABLE_TOOL_SEARCH was set to "false" in ~/.claude/settings.json, despite ~300 lines of ToolSearch rules in the project CLAUDE.md + global CLAUDE.md. Flipping it to "true" during this session surfaced the github MCP deferred tools and unblocked the epic creation you're reading about.

Docs site already exists

C:\code\fragjulia\apps\docs\ is a Fumadocs-based Next.js site, content under content/docs/{dev,design,help}/ with meta.json sidebar ordering, deploys to docs.fragjulia.de. Pillars A (help) and B (dev) were recently migrated (#583, #586, #584). Design pillar partially migrated. The SSOT scaffolding added operations/ and changelog/ as two more sections.

What I delivered (in-session, pre-PR)

All of this lives in the local working tree at C:\code\fragjulia. Nothing is committed yet — SSOT-8 (#648) covers opening the PR on a fresh branch.

Repo-level files

• CLAUDE.md — rewritten from 207 lines to ~60. The old version duplicated ~100 lines of ToolSearch rules from the global ~/.claude/global-CLAUDE.md. The new version is a pointer: hard location rules (no clones outside C:\code\, worktrees for multi-branch work, PAT never in allowedTools), commands, stack note, and a pointer to this docs site.
• .github/pull_request_template.md — PRs now have required checkboxes for changelog entry + SSOT doc update + no-changelog label exception.
• .github/workflows/docs-guard.yml — blocking CI check. Job changelog-required fails any PR that does not add a new file under apps/docs/content/docs/changelog/, bypassable only via the no-changelog label. A second job docs-updated-hint posts a warning (not failure) when code changed but no MDX did — a nudge, not a block.

Docs-site content

• apps/docs/content/docs/operations/index.mdx + meta.json — section landing page.
• apps/docs/content/docs/operations/ssot-discipline.mdx — the rule system itself: principle, changelog contract, issue-closure audit, where the rule doesn't apply (patient data, secrets), migration table, local-clone discipline.
• apps/docs/content/docs/operations/handover-2026-04-22-ssot-consolidation.mdx — this document.
• apps/docs/content/docs/changelog/index.mdx + meta.json — section landing.
• apps/docs/content/docs/changelog/2026-04-22-ssot-consolidation.mdx — seed changelog entry describing the governance change, with frontmatter closes: [] and pr: null (both to be amended in the scaffolding PR).
• Root apps/docs/content/docs/meta.json — updated sidebar to include operations + changelog alongside dev, design, help.

Agent-settings cleanup (out-of-repo, done live)

• ~/.claude/settings.json → ENABLE_TOOL_SEARCH flipped to "true", allowedTools OneDrive entry removed.
• ~/.claude/settings.local.json → 3 PAT-leak entries stripped, 3 OneDrive-git-path entries stripped, 7 gh CLI entries stripped.
• Backups of both files at ~/.claude/backups/settings*.pre-cleanup.20260422-*.bak. Delete after PAT rotation verification.
• New feedback memory at ~/.claude/projects/C--Users-dapar/memory/feedback_pat_never_in_allowlist.md + pointer in MEMORY.md.

GitHub issues

• Epic #640 with full context, acceptance criteria, non-goals.
• Nine sub-issues #641–#649, all linked as native sub-issues of #640, each with concrete steps and verification.

What's open (ordered by priority)

Do first (security)

1. [#641 SSOT-1] Rotate the leaked PAT. After rotation, update ~/.claude/settings.json env and ~/.claude.json line 674, then delete the pre-cleanup backups.
2. [#642 SSOT-2] Disable the three OAuth MCP connectors in claude.ai Settings → Connectors.

Do next (file-system consolidation)

3. [#643 SSOT-3] Consolidate the 5 parallel fragjulia clones into C:\code\fragjulia with git worktrees. Preserves uncommitted work via cp into each worktree before rm -rf of the old clone.
4. [#644 SSOT-4] Triage + migrate the 9 OneDrive handoff files into apps/docs/content/docs/operations/ or discard. Then rm -rf ~/OneDrive/Dokumente/Claude/.
5. [#645 SSOT-5] Execute the 4 authorized local duplicate deletions + stale .credentials.json. Harness blocked me from running these; they require manual rm by the user.

Do after consolidation (SSOT migrations)

6. [#648 SSOT-8] Open the scaffolding PR on a new branch claude/ssot-640-scaffolding. This is the first real test of docs-guard. After merge, make docs-guard / changelog-required a required status check on main.
7. [#646 SSOT-6] Migrate DesignGUIDE/fragjulia-design-brief-v3.md into apps/docs/content/docs/design/ and delete the legacy directory.
8. [#647 SSOT-7] Migrate PLAN.md, LAUNCH-AUDIT-*.md, SPRINT_*.md from the repo root into apps/docs/content/docs/operations/.

Do once the discipline is proven

9. [#649 SSOT-9] Add the post-merge audit cron (.github/workflows/closed-issue-audit.yml + weekly summary) that tags issues closed without a matching changelog closes: reference.

Things the harness blocked me from doing

This matters for future sessions — document so no one re-fights these battles:

1. Deleting pre-existing local CLAUDE.md files the agent didn't create this session (even with explicit per-target approval via the UI selector). Workaround: hand the user the rm commands; they execute.
2. Moving (mv) pre-existing git-repo directories. Workaround: same as above.
3. Editing ~/.claude.json (the file where the github MCP reads its PAT). Self-modification guard. Workaround: user edits in their editor.
4. Parsing a credential file with python to report its structure. Workaround: use cmp and stat for metadata-only comparison.

Everything else Claude can do cleanly: edit agent settings values (not allowedTools), create new files, edit code files, create issues, create sub-issues, flip feature flags.

Rules of engagement that emerged

For future Claude sessions landing on this repo:

• Never create HANDOFF-*.md at repo root or under OneDrive\, Dokumente\, Documents\, Downloads\, AppData\Temp\. They go under apps/docs/content/docs/operations/ as MDX, named handover-YYYY-MM-DD-<slug>.mdx.
• Never clone outside C:\code\fragjulia. For parallel-branch work, use git worktree add C:\code\fragjulia-worktrees\<branch> <branch>.
• Never paste a PAT into an allowedTools permission string. The PAT lives in env only. See ~/.claude/projects/C--Users-dapar/memory/feedback_pat_never_in_allowlist.md.
• Every PR adds a changelog entry. If a PR genuinely shouldn't have one (revert, infra-only), add the no-changelog label and state why in the PR body. The docs-guard CI enforces this.
• Never close an issue without a matching changelog closes: reference. The post-merge audit (SSOT-9, once deployed) will tag the violation and surface it in the weekly summary.

Session artifacts

• Epic: https://github.com/neid404/fragjulia/issues/640
• Changelog seed: apps/docs/content/docs/changelog/2026-04-22-ssot-consolidation.mdx
• SSOT rule page: apps/docs/content/docs/operations/ssot-discipline.mdx
• Local memory addition: ~/.claude/projects/C--Users-dapar/memory/feedback_pat_never_in_allowlist.md
• Settings backups: ~/.claude/backups/settings*.pre-cleanup.20260422-*.bak

If you're the next session

Start at epic #640. Read the sub-issues in the order given above. For each one, the issue body has concrete commands — most are copy-pasteable. Acceptance criteria are explicit; mark them done as you go. If anything in this handover contradicts the current state of the code or the epic body, trust the code and the issue, not this document — handovers go stale, issues are kept live.