@m16khb/llm-wiki 0.1.0 → 0.1.2

package/internal/wiki/cleanup.go

@@ -0,0 +1,1189 @@
+package wiki
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"unicode"
+)
+
+// RepositoryReferenceCleanupOptions controls the destructive repository
+// reference cleanup. The default is a dry-run; callers must set Apply to write.
+type RepositoryReferenceCleanupOptions struct {
+	Apply       bool   `json:"apply"`
+	ArchiveRoot string `json:"archive_root,omitempty"`
+}
+
+// RepositoryReferenceCleanupResult describes planned or applied cleanup work.
+type RepositoryReferenceCleanupResult struct {
+	Applied               bool                               `json:"applied"`
+	Date                  string                             `json:"date"`
+	Scope                 string                             `json:"scope"`
+	ArchiveRoot           string                             `json:"archive_root"`
+	Bundles               []RepositoryReferenceCleanupBundle `json:"bundles"`
+	RewrittenFiles        []string                           `json:"rewritten_files,omitempty"`
+	SkippedProtectedFiles []string                           `json:"skipped_protected_files,omitempty"`
+	ReportPaths           []string                           `json:"report_paths,omitempty"`
+	Warnings              []string                           `json:"warnings,omitempty"`
+}
+
+// RepositoryReferenceCleanupBundle is a canonical replacement for fragmented
+// dated repository-reference pages.
+type RepositoryReferenceCleanupBundle struct {
+	Repository    string   `json:"repository"`
+	BundlePath    string   `json:"bundle_path"`
+	BundleSlug    string   `json:"bundle_slug"`
+	FragmentPaths []string `json:"fragment_paths"`
+	ArchivedPaths []string `json:"archived_paths"`
+}
+
+// DuplicateSlugCleanupOptions controls duplicate slug resolution. The default
+// is a dry-run; callers must set Apply to rename files.
+type DuplicateSlugCleanupOptions struct {
+	Apply bool `json:"apply"`
+}
+
+// DuplicateSlugCleanupResult describes planned or applied duplicate slug fixes.
+type DuplicateSlugCleanupResult struct {
+	Applied        bool                  `json:"applied"`
+	Date           string                `json:"date"`
+	Scope          string                `json:"scope"`
+	Renames        []DuplicateSlugRename `json:"renames"`
+	RewrittenFiles []string              `json:"rewritten_files,omitempty"`
+	ReportPaths    []string              `json:"report_paths,omitempty"`
+	Warnings       []string              `json:"warnings,omitempty"`
+}
+
+// DuplicateSlugRename is a planned or applied file rename that makes a slug
+// unique while leaving one canonical page at the original slug.
+type DuplicateSlugRename struct {
+	Slug          string `json:"slug"`
+	CanonicalPath string `json:"canonical_path"`
+	FromPath      string `json:"from_path"`
+	ToPath        string `json:"to_path"`
+}
+
+type repositoryReferenceCleanupPlan struct {
+	result      RepositoryReferenceCleanupResult
+	bundles     []repositoryReferenceBundlePlan
+	linkTargets map[string]string
+	sharedPages []repositoryReferenceSharedPage
+}
+
+type repositoryReferenceBundlePlan struct {
+	Repository string
+	BundlePath string
+	BundleSlug string
+	Fragments  []repositoryReferenceFragmentPlan
+}
+
+type repositoryReferenceFragmentPlan struct {
+	Page         Page
+	Content      string
+	Title        string
+	Snippet      string
+	ArchivedPath string
+}
+
+type repositoryReferenceSharedPage struct {
+	Slug  string
+	Title string
+	Path  string
+}
+
+type duplicateSlugCleanupPlan struct {
+	result  DuplicateSlugCleanupResult
+	renames []duplicateSlugRenamePlan
+}
+
+type duplicateSlugRenamePlan struct {
+	Rename DuplicateSlugRename
+	Page   Page
+}
+
+// CleanupRepositoryReferences merges fragmented repository-specific reference
+// pages into one canonical bundle per repository, archives the originals, and
+// rewrites active wikilinks. It never modifies .obsidian or 10-sources content.
+func (v *Vault) CleanupRepositoryReferences(opts RepositoryReferenceCleanupOptions) (RepositoryReferenceCleanupResult, error) {
+	plan, err := v.planRepositoryReferenceCleanup(opts)
+	if err != nil {
+		return RepositoryReferenceCleanupResult{}, err
+	}
+	if !opts.Apply {
+		return plan.result, nil
+	}
+	if len(plan.bundles) == 0 {
+		plan.result.Applied = true
+		return plan.result, nil
+	}
+	for _, bundle := range plan.bundles {
+		if err := v.writeRepositoryReferenceBundle(plan.result.Date, plan.result.ArchiveRoot, bundle); err != nil {
+			return plan.result, err
+		}
+		for _, fragment := range bundle.Fragments {
+			if err := v.archiveRepositoryReferenceFragment(plan.result.Date, bundle.BundleSlug, fragment); err != nil {
+				return plan.result, err
+			}
+		}
+	}
+	rewritten, skipped, err := v.rewriteRepositoryReferenceLinks(plan.linkTargets)
+	if err != nil {
+		return plan.result, err
+	}
+	plan.result.RewrittenFiles = append(plan.result.RewrittenFiles, rewritten...)
+	plan.result.SkippedProtectedFiles = append(plan.result.SkippedProtectedFiles, skipped...)
+	if err := v.updateRepositoryReferenceIndex(plan.result.Date, plan.result.Bundles, plan.sharedPages, &plan.result); err != nil {
+		return plan.result, err
+	}
+	if err := v.appendRepositoryReferenceCleanupLog(plan.result.Date, plan.result.Bundles, &plan.result); err != nil {
+		return plan.result, err
+	}
+	plan.result.Applied = true
+	if err := v.writeRepositoryReferenceCleanupReport(&plan.result, plan.sharedPages); err != nil {
+		return plan.result, err
+	}
+	sort.Strings(plan.result.RewrittenFiles)
+	sort.Strings(plan.result.SkippedProtectedFiles)
+	return plan.result, nil
+}
+
+// CleanupDuplicateSlugs renames non-canonical pages from duplicate slug groups
+// so lint no longer reports Obsidian ambiguity warnings. It does not modify
+// 10-sources bodies.
+func (v *Vault) CleanupDuplicateSlugs(opts DuplicateSlugCleanupOptions) (DuplicateSlugCleanupResult, error) {
+	plan, err := v.planDuplicateSlugCleanup(opts)
+	if err != nil {
+		return DuplicateSlugCleanupResult{}, err
+	}
+	if !opts.Apply {
+		return plan.result, nil
+	}
+	for _, item := range plan.renames {
+		if err := v.applyDuplicateSlugRename(plan.result.Date, item); err != nil {
+			return plan.result, err
+		}
+		plan.result.RewrittenFiles = append(plan.result.RewrittenFiles, item.Rename.ToPath)
+	}
+	if len(plan.renames) > 0 {
+		if err := v.appendDuplicateSlugCleanupLog(plan.result.Date, plan.result.Renames, &plan.result); err != nil {
+			return plan.result, err
+		}
+		plan.result.Applied = true
+		if err := v.writeDuplicateSlugCleanupReport(&plan.result); err != nil {
+			return plan.result, err
+		}
+	} else {
+		plan.result.Applied = true
+	}
+	sort.Strings(plan.result.RewrittenFiles)
+	return plan.result, nil
+}
+
+func (v *Vault) planDuplicateSlugCleanup(opts DuplicateSlugCleanupOptions) (duplicateSlugCleanupPlan, error) {
+	pages, err := v.ListPages()
+	if err != nil {
+		return duplicateSlugCleanupPlan{}, err
+	}
+	groups := map[string][]Page{}
+	usedPaths := map[string]bool{}
+	for _, page := range pages {
+		groups[page.Slug] = append(groups[page.Slug], page)
+		usedPaths[page.Path] = true
+	}
+	plan := duplicateSlugCleanupPlan{
+		result: DuplicateSlugCleanupResult{
+			Applied: opts.Apply,
+			Date:    v.nowDate(),
+			Scope:   "duplicate-slugs",
+			Renames: []DuplicateSlugRename{},
+		},
+	}
+	slugs := make([]string, 0, len(groups))
+	for slug, group := range groups {
+		if len(group) > 1 {
+			slugs = append(slugs, slug)
+		}
+	}
+	sort.Strings(slugs)
+	for _, slug := range slugs {
+		group := groups[slug]
+		canonical := chooseDuplicateSlugCanonical(group)
+		sort.Slice(group, func(i, j int) bool { return group[i].Path < group[j].Path })
+		for _, page := range group {
+			if page.Path == canonical.Path {
+				continue
+			}
+			if isProtectedDuplicateSlugPath(page.Path) {
+				plan.result.Warnings = append(plan.result.Warnings, "protected duplicate slug page not renamed: "+page.Path)
+				continue
+			}
+			toPath, err := v.duplicateSlugTargetPath(page, usedPaths)
+			if err != nil {
+				return plan, err
+			}
+			rename := DuplicateSlugRename{Slug: slug, CanonicalPath: canonical.Path, FromPath: page.Path, ToPath: toPath}
+			plan.result.Renames = append(plan.result.Renames, rename)
+			plan.renames = append(plan.renames, duplicateSlugRenamePlan{Rename: rename, Page: page})
+		}
+	}
+	return plan, nil
+}
+
+func chooseDuplicateSlugCanonical(group []Page) Page {
+	pages := append([]Page(nil), group...)
+	sort.Slice(pages, func(i, j int) bool {
+		left := duplicateSlugCanonicalRank(pages[i])
+		right := duplicateSlugCanonicalRank(pages[j])
+		if left == right {
+			return pages[i].Path < pages[j].Path
+		}
+		return left > right
+	})
+	return pages[0]
+}
+
+func duplicateSlugCanonicalRank(page Page) int {
+	rank := 0
+	switch {
+	case strings.HasPrefix(page.Path, "10-sources/"):
+		rank += 1000
+	case strings.HasPrefix(page.Path, "00-meta/"):
+		rank += 900
+	case strings.HasPrefix(page.Path, "_archive/"):
+		rank -= 100
+	case strings.Contains(page.Path, "/"):
+		rank += 500
+	default:
+		rank -= 100
+	}
+	if strings.EqualFold(page.Metadata.Status, "active") {
+		rank += 20
+	}
+	if strings.EqualFold(page.Metadata.Status, "archived") {
+		rank -= 50
+	}
+	for _, tag := range page.Metadata.Tags {
+		if strings.EqualFold(tag, "compatibility") || strings.EqualFold(tag, "generated-artifact-boundary") {
+			rank -= 200
+		}
+	}
+	return rank
+}
+
+func isProtectedDuplicateSlugPath(path string) bool {
+	return strings.HasPrefix(path, "10-sources/") || path == ".obsidian" || strings.HasPrefix(path, ".obsidian/")
+}
+
+func (v *Vault) duplicateSlugTargetPath(page Page, usedPaths map[string]bool) (string, error) {
+	dir := filepath.ToSlash(filepath.Dir(page.Path))
+	if dir == "." {
+		dir = ""
+	}
+	baseSlug := duplicateSlugReplacementSlug(page)
+	if baseSlug == "" {
+		baseSlug = "renamed-" + page.Slug
+	}
+	for i := 0; ; i++ {
+		slug := baseSlug
+		if i > 0 {
+			slug = fmt.Sprintf("%s-%d", baseSlug, i+1)
+		}
+		candidate := filepath.ToSlash(filepath.Join(dir, slug+".md"))
+		if !usedPaths[candidate] {
+			if _, err := v.SafeJoin(candidate); err != nil {
+				return "", err
+			}
+			usedPaths[candidate] = true
+			return candidate, nil
+		}
+	}
+}
+
+func duplicateSlugReplacementSlug(page Page) string {
+	if !strings.Contains(page.Path, "/") {
+		if pageHasTag(page, "compatibility") || strings.Contains(strings.ToLower(page.Metadata.Title), "compatibility") {
+			return "root-compatibility-" + page.Slug
+		}
+		return "root-" + page.Slug
+	}
+	withoutExt := strings.TrimSuffix(page.Path, filepath.Ext(page.Path))
+	parts := strings.Split(withoutExt, "/")
+	if len(parts) <= 1 {
+		return "renamed-" + page.Slug
+	}
+	prefix := Slugify(strings.Join(parts[:len(parts)-1], "-"))
+	if prefix == "" {
+		prefix = "renamed"
+	}
+	return prefix + "-" + page.Slug
+}
+
+func pageHasTag(page Page, tag string) bool {
+	for _, value := range page.Metadata.Tags {
+		if strings.EqualFold(value, tag) {
+			return true
+		}
+	}
+	return false
+}
+
+func (v *Vault) applyDuplicateSlugRename(date string, item duplicateSlugRenamePlan) error {
+	content, err := os.ReadFile(item.Page.AbsPath)
+	if err != nil {
+		return err
+	}
+	targetAbs, err := v.SafeJoin(item.Rename.ToPath)
+	if err != nil {
+		return err
+	}
+	if _, err := os.Stat(targetAbs); err == nil {
+		return fmt.Errorf("duplicate slug target already exists: %s", item.Rename.ToPath)
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(targetAbs), 0o755); err != nil {
+		return err
+	}
+	updated := markDuplicateSlugRenamed(date, item.Rename, string(content))
+	if err := os.WriteFile(targetAbs, []byte(updated), 0o644); err != nil {
+		return err
+	}
+	return os.Remove(item.Page.AbsPath)
+}
+
+func markDuplicateSlugRenamed(date string, rename DuplicateSlugRename, content string) string {
+	notice := fmt.Sprintf("> Renamed by duplicate-slug cleanup on %s. Canonical page: [[%s]] (`%s`). Previous path: `%s`.\n\n", date, rename.Slug, rename.CanonicalPath, rename.FromPath)
+	lines := strings.Split(content, "\n")
+	if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" {
+		end := -1
+		for i := 1; i < len(lines); i++ {
+			if strings.TrimSpace(lines[i]) == "---" {
+				end = i
+				break
+			}
+		}
+		if end > 0 {
+			header := upsertFrontmatterField(lines[1:end], "updated", date)
+			var b strings.Builder
+			b.WriteString("---\n")
+			b.WriteString(strings.Join(header, "\n"))
+			b.WriteString("\n---\n\n")
+			b.WriteString(notice)
+			b.WriteString(strings.TrimLeft(strings.Join(lines[end+1:], "\n"), "\n"))
+			if !strings.HasSuffix(b.String(), "\n") {
+				b.WriteString("\n")
+			}
+			return b.String()
+		}
+	}
+	return fmt.Sprintf("---\ntitle: %s\ntype: reference\nstatus: active\ncreated: %s\nupdated: %s\ntags: [duplicate-slug-cleanup]\ndomain: meta\n---\n\n%s%s\n", yamlQuote(titleizeSlug(rename.ToPath)), date, date, notice, strings.TrimSpace(content))
+}
+
+func (v *Vault) appendDuplicateSlugCleanupLog(date string, renames []DuplicateSlugRename, result *DuplicateSlugCleanupResult) error {
+	logRel := "00-meta/log.md"
+	abs, err := v.SafeJoin(logRel)
+	if err != nil {
+		return err
+	}
+	data, err := os.ReadFile(abs)
+	if errors.Is(err, os.ErrNotExist) {
+		if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+			return err
+		}
+		data = []byte(fmt.Sprintf("---\ntitle: \"LLM Wiki Log\"\ntype: log\nstatus: active\ncreated: %s\nupdated: %s\ntags: [log]\ndomain: meta\n---\n\n# Log\n", date, date))
+	} else if err != nil {
+		return err
+	}
+	line := fmt.Sprintf("- %s: Duplicate slug cleanup renamed %d non-canonical pages to remove Obsidian ambiguity warnings.\n", date, len(renames))
+	if strings.Contains(string(data), strings.TrimSpace(line)) {
+		return nil
+	}
+	if err := os.WriteFile(abs, []byte(strings.TrimRight(string(data), "\n")+"\n"+line), 0o644); err != nil {
+		return err
+	}
+	result.RewrittenFiles = append(result.RewrittenFiles, logRel)
+	return nil
+}
+
+func (v *Vault) writeDuplicateSlugCleanupReport(result *DuplicateSlugCleanupResult) error {
+	reportRel, err := v.uniqueVaultRel(fmt.Sprintf("00-meta/reports/duplicate-slug-cleanup-%s.md", result.Date))
+	if err != nil {
+		return err
+	}
+	abs, err := v.SafeJoin(reportRel)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+		return err
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	fmt.Fprintf(&b, "title: %s\n", yamlQuote("Duplicate Slug Cleanup "+result.Date))
+	b.WriteString("type: lint-report\n")
+	b.WriteString("status: active\n")
+	fmt.Fprintf(&b, "created: %s\n", result.Date)
+	fmt.Fprintf(&b, "updated: %s\n", result.Date)
+	b.WriteString("tags: [cleanup, duplicate-slug, ai-slop-cleaner]\n")
+	b.WriteString("domain: meta\n")
+	b.WriteString("---\n\n")
+	fmt.Fprintf(&b, "# Duplicate Slug Cleanup %s\n\n", result.Date)
+	fmt.Fprintf(&b, "- Applied: `%t`\n", result.Applied)
+	fmt.Fprintf(&b, "- Renames: `%d`\n\n", len(result.Renames))
+	b.WriteString("## Renames\n\n")
+	for _, rename := range result.Renames {
+		fmt.Fprintf(&b, "### `%s`\n\n", rename.Slug)
+		fmt.Fprintf(&b, "- Canonical: [[%s]] (`%s`)\n", rename.Slug, rename.CanonicalPath)
+		fmt.Fprintf(&b, "- Rename: `%s` → `%s`\n\n", rename.FromPath, rename.ToPath)
+	}
+	if len(result.Warnings) > 0 {
+		b.WriteString("## Warnings\n\n")
+		for _, warning := range result.Warnings {
+			fmt.Fprintf(&b, "- %s\n", warning)
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("## Changelog\n\n")
+	fmt.Fprintf(&b, "- %s: Generated by `llm-wiki cleanup --scope duplicate-slugs --apply`.\n", result.Date)
+	if err := os.WriteFile(abs, []byte(b.String()), 0o644); err != nil {
+		return err
+	}
+	result.ReportPaths = append(result.ReportPaths, reportRel)
+	return nil
+}
+
+func (v *Vault) planRepositoryReferenceCleanup(opts RepositoryReferenceCleanupOptions) (repositoryReferenceCleanupPlan, error) {
+	date := v.nowDate()
+	archiveRoot := strings.Trim(strings.TrimSpace(filepath.ToSlash(opts.ArchiveRoot)), "/")
+	if archiveRoot == "" {
+		archiveRoot = "_archive/repository-reference-fragments-" + date
+	}
+	if archiveRoot == "10-sources" || strings.HasPrefix(archiveRoot, "10-sources/") || archiveRoot == ".obsidian" || strings.HasPrefix(archiveRoot, ".obsidian/") {
+		return repositoryReferenceCleanupPlan{}, fmt.Errorf("archive root is protected: %s", archiveRoot)
+	}
+	if _, err := v.SafeJoin(archiveRoot); err != nil {
+		return repositoryReferenceCleanupPlan{}, err
+	}
+
+	pages, err := v.ListPages()
+	if err != nil {
+		return repositoryReferenceCleanupPlan{}, err
+	}
+	groups := map[string][]Page{}
+	var sharedPages []repositoryReferenceSharedPage
+	for _, page := range pages {
+		repo, ok := repositoryReferenceRepo(page.Path)
+		if !ok {
+			continue
+		}
+		if repo == "shared" {
+			sharedPages = append(sharedPages, repositoryReferenceSharedPage{Slug: page.Slug, Title: pageTitle(page), Path: page.Path})
+			continue
+		}
+		if isRepositoryReferenceBundleSlug(page.Slug) {
+			continue
+		}
+		groups[repo] = append(groups[repo], page)
+	}
+	sort.Slice(sharedPages, func(i, j int) bool { return sharedPages[i].Path < sharedPages[j].Path })
+
+	plan := repositoryReferenceCleanupPlan{
+		result: RepositoryReferenceCleanupResult{
+			Applied:     opts.Apply,
+			Date:        date,
+			Scope:       "repository-references",
+			ArchiveRoot: archiveRoot,
+			Bundles:     []RepositoryReferenceCleanupBundle{},
+		},
+		linkTargets: map[string]string{},
+		sharedPages: sharedPages,
+	}
+	repos := make([]string, 0, len(groups))
+	for repo := range groups {
+		repos = append(repos, repo)
+	}
+	sort.Strings(repos)
+	usedArchivePaths := map[string]bool{}
+	for _, repo := range repos {
+		fragments := groups[repo]
+		if len(fragments) <= 1 {
+			continue
+		}
+		sort.Slice(fragments, func(i, j int) bool { return fragments[i].Path < fragments[j].Path })
+		bundleSlug := repo + "-reference-bundle-" + date
+		bundlePath := filepath.ToSlash(filepath.Join("20-wiki/concepts/repository-references", repo, bundleSlug+".md"))
+		bundlePlan := repositoryReferenceBundlePlan{Repository: repo, BundlePath: bundlePath, BundleSlug: bundleSlug}
+		bundleResult := RepositoryReferenceCleanupBundle{Repository: repo, BundlePath: bundlePath, BundleSlug: bundleSlug}
+		for _, page := range fragments {
+			content, err := os.ReadFile(page.AbsPath)
+			if err != nil {
+				return plan, err
+			}
+			archivedPath := uniqueArchivePath(archiveRoot, repo, "archived-"+page.Slug+".md", usedArchivePaths)
+			fragment := repositoryReferenceFragmentPlan{
+				Page:         page,
+				Content:      string(content),
+				Title:        cleanupPageTitle(page, string(content)),
+				Snippet:      summarizeMarkdownBody(string(content)),
+				ArchivedPath: archivedPath,
+			}
+			bundlePlan.Fragments = append(bundlePlan.Fragments, fragment)
+			bundleResult.FragmentPaths = append(bundleResult.FragmentPaths, page.Path)
+			bundleResult.ArchivedPaths = append(bundleResult.ArchivedPaths, archivedPath)
+			plan.linkTargets[page.Slug] = bundleSlug
+			plan.linkTargets[strings.TrimSuffix(page.Path, ".md")] = bundleSlug
+			plan.linkTargets[page.Path] = bundleSlug
+		}
+		plan.bundles = append(plan.bundles, bundlePlan)
+		plan.result.Bundles = append(plan.result.Bundles, bundleResult)
+	}
+	return plan, nil
+}
+
+func (v *Vault) writeRepositoryReferenceBundle(date, archiveRoot string, bundle repositoryReferenceBundlePlan) error {
+	if len(bundle.Fragments) == 0 {
+		return nil
+	}
+	abs, err := v.SafeJoin(bundle.BundlePath)
+	if err != nil {
+		return err
+	}
+	if _, err := os.Stat(abs); err == nil {
+		return fmt.Errorf("bundle already exists: %s", bundle.BundlePath)
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(abs, []byte(renderRepositoryReferenceBundle(date, archiveRoot, bundle)), 0o644)
+}
+
+func (v *Vault) archiveRepositoryReferenceFragment(date, bundleSlug string, fragment repositoryReferenceFragmentPlan) error {
+	archiveAbs, err := v.SafeJoin(fragment.ArchivedPath)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(archiveAbs), 0o755); err != nil {
+		return err
+	}
+	content := markRepositoryReferenceFragmentArchived(date, bundleSlug, fragment.Page.Path, fragment.Content)
+	if err := os.WriteFile(archiveAbs, []byte(content), 0o644); err != nil {
+		return err
+	}
+	if err := os.Remove(fragment.Page.AbsPath); err != nil {
+		return err
+	}
+	return nil
+}
+
+func renderRepositoryReferenceBundle(date, archiveRoot string, bundle repositoryReferenceBundlePlan) string {
+	title := titleizeSlug(bundle.Repository) + " Reference Bundle " + date
+	var b strings.Builder
+	b.WriteString("---\n")
+	fmt.Fprintf(&b, "title: %s\n", yamlQuote(title))
+	b.WriteString("type: reference\n")
+	b.WriteString("status: active\n")
+	fmt.Fprintf(&b, "created: %s\n", date)
+	fmt.Fprintf(&b, "updated: %s\n", date)
+	fmt.Fprintf(&b, "tags: [repository-reference, cleanup, %s]\n", bundle.Repository)
+	b.WriteString("domain: repository-references\n")
+	b.WriteString("---\n\n")
+	fmt.Fprintf(&b, "# %s\n\n", title)
+	fmt.Fprintf(&b, "> Consolidated on %s from %d repository-reference fragments. Archived originals live under `%s/%s/`.\n\n", date, len(bundle.Fragments), archiveRoot, bundle.Repository)
+	b.WriteString("## Canonical Use\n\n")
+	b.WriteString("- Prefer this bundle over dated per-topic repository fragments when retrieving project-specific rules.\n")
+	b.WriteString("- Treat archived fragment pages as provenance only; update this bundle for future curated corrections.\n\n")
+	b.WriteString("## Consolidated Fragment Summaries\n\n")
+	for _, fragment := range bundle.Fragments {
+		fmt.Fprintf(&b, "### %s\n\n", fragment.Title)
+		fmt.Fprintf(&b, "- Original path: `%s`\n", fragment.Page.Path)
+		fmt.Fprintf(&b, "- Archived path: `%s`\n", fragment.ArchivedPath)
+		if fragment.Snippet != "" {
+			fmt.Fprintf(&b, "- Summary: %s\n", fragment.Snippet)
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("## Archived Fragment Inventory\n\n")
+	for _, fragment := range bundle.Fragments {
+		fmt.Fprintf(&b, "- `%s` → `%s`\n", fragment.Page.Path, fragment.ArchivedPath)
+	}
+	b.WriteString("\n## Changelog\n\n")
+	fmt.Fprintf(&b, "- %s: Consolidated repository-reference fragments via `llm-wiki cleanup --scope repository-references --apply`.\n", date)
+	return b.String()
+}
+
+func markRepositoryReferenceFragmentArchived(date, bundleSlug, originalPath, content string) string {
+	lines := strings.Split(content, "\n")
+	if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" {
+		end := -1
+		for i := 1; i < len(lines); i++ {
+			if strings.TrimSpace(lines[i]) == "---" {
+				end = i
+				break
+			}
+		}
+		if end > 0 {
+			header := upsertFrontmatterField(lines[1:end], "status", "archived")
+			header = upsertFrontmatterField(header, "updated", date)
+			var b strings.Builder
+			b.WriteString("---\n")
+			b.WriteString(strings.Join(header, "\n"))
+			b.WriteString("\n---\n\n")
+			fmt.Fprintf(&b, "> Archived by repository-reference cleanup on %s. Canonical replacement: [[%s]]. Original path: `%s`.\n\n", date, bundleSlug, originalPath)
+			b.WriteString(strings.TrimLeft(strings.Join(lines[end+1:], "\n"), "\n"))
+			if !strings.HasSuffix(b.String(), "\n") {
+				b.WriteString("\n")
+			}
+			return b.String()
+		}
+	}
+	return fmt.Sprintf("---\ntitle: %s\ntype: reference\nstatus: archived\ncreated: %s\nupdated: %s\ntags: [repository-reference, archived]\ndomain: repository-references\n---\n\n> Archived by repository-reference cleanup on %s. Canonical replacement: [[%s]]. Original path: `%s`.\n\n%s\n", yamlQuote(titleizeSlug(strings.TrimSuffix(filepath.Base(originalPath), ".md"))), date, date, date, bundleSlug, originalPath, strings.TrimSpace(content))
+}
+
+func upsertFrontmatterField(lines []string, key, value string) []string {
+	prefix := key + ":"
+	out := append([]string(nil), lines...)
+	for i, line := range out {
+		if strings.HasPrefix(strings.TrimSpace(line), prefix) {
+			out[i] = key + ": " + value
+			return out
+		}
+	}
+	return append(out, key+": "+value)
+}
+
+func (v *Vault) rewriteRepositoryReferenceLinks(linkTargets map[string]string) ([]string, []string, error) {
+	if len(linkTargets) == 0 {
+		return nil, nil, nil
+	}
+	var rewritten []string
+	var skipped []string
+	err := filepath.WalkDir(v.Root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			if path != v.Root && shouldSkipDir(d.Name()) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.EqualFold(filepath.Ext(d.Name()), ".md") {
+			return nil
+		}
+		rel := v.Rel(path)
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		updated := rewriteCleanupWikilinks(string(data), linkTargets)
+		if updated == string(data) {
+			return nil
+		}
+		if strings.HasPrefix(rel, "10-sources/") {
+			skipped = append(skipped, rel)
+			return nil
+		}
+		if err := os.WriteFile(path, []byte(updated), 0o644); err != nil {
+			return err
+		}
+		rewritten = append(rewritten, rel)
+		return nil
+	})
+	return compactSortedStrings(rewritten), compactSortedStrings(skipped), err
+}
+
+func rewriteCleanupWikilinks(content string, linkTargets map[string]string) string {
+	return wikilinkPattern.ReplaceAllStringFunc(content, func(match string) string {
+		parts := wikilinkPattern.FindStringSubmatch(match)
+		if len(parts) != 2 {
+			return match
+		}
+		raw := strings.TrimSpace(parts[1])
+		targetPart := raw
+		label := ""
+		if split := strings.SplitN(raw, "|", 2); len(split) == 2 {
+			targetPart = strings.TrimSpace(split[0])
+			label = strings.TrimSpace(split[1])
+		}
+		targetWithoutAnchor := strings.TrimSpace(strings.SplitN(targetPart, "#", 2)[0])
+		normalized := strings.TrimSuffix(strings.Trim(targetWithoutAnchor, "/"), ".md")
+		replacement, ok := linkTargets[normalized]
+		if !ok {
+			replacement, ok = linkTargets[normalizeWikilink(raw)]
+		}
+		if !ok {
+			return match
+		}
+		if label != "" {
+			return "[[" + replacement + "|" + label + "]]"
+		}
+		return "[[" + replacement + "]]"
+	})
+}
+
+func (v *Vault) updateRepositoryReferenceIndex(date string, bundles []RepositoryReferenceCleanupBundle, sharedPages []repositoryReferenceSharedPage, result *RepositoryReferenceCleanupResult) error {
+	indexRel := "00-meta/index.md"
+	abs, err := v.SafeJoin(indexRel)
+	if err != nil {
+		return err
+	}
+	data, err := os.ReadFile(abs)
+	if errors.Is(err, os.ErrNotExist) {
+		if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+			return err
+		}
+		data = []byte(renderRepositoryReferenceIndexScaffold(date))
+	} else if err != nil {
+		return err
+	}
+	section := renderRepositoryReferenceIndexSection(bundles, sharedPages)
+	updated, _ := replaceMarkdownSection(string(data), "### Repository-specific technical references", section)
+	updated = replaceRepositorySpecificTechReferencesBlock(updated, bundles, sharedPages)
+	updated = dedupeRepositoryReferenceIndexBullets(updated, bundles)
+	if updated == string(data) {
+		return nil
+	}
+	if err := os.WriteFile(abs, []byte(updated), 0o644); err != nil {
+		return err
+	}
+	result.RewrittenFiles = append(result.RewrittenFiles, indexRel)
+	return nil
+}
+
+func renderRepositoryReferenceIndexScaffold(date string) string {
+	return fmt.Sprintf("---\ntitle: \"LLM Wiki Index\"\ntype: index\nstatus: active\ncreated: %s\nupdated: %s\ntags: [index]\ndomain: meta\n---\n\n# Index\n\n", date, date)
+}
+
+func renderRepositoryReferenceIndexSection(bundles []RepositoryReferenceCleanupBundle, sharedPages []repositoryReferenceSharedPage) string {
+	var b strings.Builder
+	b.WriteString("### Repository-specific technical references\n\n")
+	if len(bundles) == 0 && len(sharedPages) == 0 {
+		b.WriteString("- No repository-specific technical references found.\n")
+		return b.String()
+	}
+	for _, bundle := range bundles {
+		fmt.Fprintf(&b, "- [[%s]] — consolidated `%s` reference (%d archived fragments).\n", bundle.BundleSlug, bundle.Repository, len(bundle.FragmentPaths))
+	}
+	for _, page := range sharedPages {
+		title := page.Title
+		if title == "" {
+			title = titleizeSlug(page.Slug)
+		}
+		fmt.Fprintf(&b, "- [[%s]] — shared reference: %s.\n", page.Slug, title)
+	}
+	return b.String()
+}
+
+func replaceRepositorySpecificTechReferencesBlock(content string, bundles []RepositoryReferenceCleanupBundle, sharedPages []repositoryReferenceSharedPage) string {
+	const header = "**Repository-specific tech references**"
+	lines := strings.Split(content, "\n")
+	start := -1
+	for i, line := range lines {
+		if strings.TrimSpace(line) == header {
+			start = i
+			break
+		}
+	}
+	if start < 0 {
+		return content
+	}
+	end := start + 1
+	for end < len(lines) {
+		trimmed := strings.TrimSpace(lines[end])
+		if strings.HasPrefix(trimmed, "### ") {
+			break
+		}
+		end++
+	}
+	replacement := []string{header}
+	for _, bundle := range bundles {
+		replacement = append(replacement, "- [["+bundle.BundleSlug+"]]")
+	}
+	for _, page := range sharedPages {
+		replacement = append(replacement, "- [["+page.Slug+"]]")
+	}
+	replacement = append(replacement, "")
+	out := make([]string, 0, len(lines)-end+start+len(replacement))
+	out = append(out, lines[:start]...)
+	out = append(out, replacement...)
+	out = append(out, lines[end:]...)
+	return strings.Join(out, "\n")
+}
+
+func dedupeRepositoryReferenceIndexBullets(content string, bundles []RepositoryReferenceCleanupBundle) string {
+	bundleSlugs := map[string]bool{}
+	for _, bundle := range bundles {
+		bundleSlugs[bundle.BundleSlug] = true
+	}
+	if len(bundleSlugs) == 0 {
+		return content
+	}
+	lines := strings.Split(content, "\n")
+	lastBundleOnlyLine := ""
+	for i, line := range lines {
+		if !strings.HasPrefix(strings.TrimSpace(line), "- ") || !strings.Contains(line, "[[") {
+			if strings.TrimSpace(line) != "" {
+				lastBundleOnlyLine = ""
+			}
+			continue
+		}
+		links := wikilinkPattern.FindAllStringSubmatch(line, -1)
+		if len(links) == 0 {
+			continue
+		}
+		hasBundle := false
+		ordered := make([]string, 0, len(links))
+		seenLinks := map[string]bool{}
+		for _, link := range links {
+			slug := normalizeWikilink(link[1])
+			if bundleSlugs[slug] {
+				hasBundle = true
+			}
+			if seenLinks[link[0]] {
+				continue
+			}
+			seenLinks[link[0]] = true
+			ordered = append(ordered, link[0])
+		}
+		if !hasBundle || !isWikilinkOnlyBullet(line) {
+			lastBundleOnlyLine = ""
+			continue
+		}
+		normalized := "- " + strings.Join(ordered, ", ")
+		if lastBundleOnlyLine == normalized {
+			lines[i] = ""
+			continue
+		}
+		lastBundleOnlyLine = normalized
+		lines[i] = normalized
+	}
+	return removeRepeatedBlankLines(strings.Join(lines, "\n"))
+}
+
+func isWikilinkOnlyBullet(line string) bool {
+	trimmed := strings.TrimSpace(line)
+	if !strings.HasPrefix(trimmed, "- ") {
+		return false
+	}
+	withoutLinks := wikilinkPattern.ReplaceAllString(strings.TrimSpace(strings.TrimPrefix(trimmed, "- ")), "")
+	withoutLinks = strings.TrimSpace(strings.ReplaceAll(withoutLinks, ",", ""))
+	return withoutLinks == ""
+}
+
+func removeRepeatedBlankLines(content string) string {
+	lines := strings.Split(content, "\n")
+	out := make([]string, 0, len(lines))
+	previousBlank := false
+	for _, line := range lines {
+		blank := strings.TrimSpace(line) == ""
+		if blank && previousBlank {
+			continue
+		}
+		out = append(out, line)
+		previousBlank = blank
+	}
+	return strings.Join(out, "\n")
+}
+
+func replaceMarkdownSection(content, header, replacement string) (string, bool) {
+	lines := strings.Split(content, "\n")
+	start := -1
+	for i, line := range lines {
+		if strings.TrimSpace(line) == header {
+			start = i
+			break
+		}
+	}
+	replacementLines := strings.Split(strings.TrimRight(replacement, "\n"), "\n")
+	if start < 0 {
+		if strings.TrimSpace(content) == "" {
+			return strings.Join(replacementLines, "\n") + "\n", true
+		}
+		sep := "\n\n"
+		if strings.HasSuffix(content, "\n") {
+			sep = "\n"
+		}
+		return content + sep + strings.Join(replacementLines, "\n") + "\n", true
+	}
+	end := start + 1
+	for end < len(lines) {
+		trimmed := strings.TrimSpace(lines[end])
+		if strings.HasPrefix(trimmed, "### ") && trimmed != header {
+			break
+		}
+		end++
+	}
+	out := make([]string, 0, len(lines)-end+start+len(replacementLines))
+	out = append(out, lines[:start]...)
+	out = append(out, replacementLines...)
+	out = append(out, lines[end:]...)
+	return strings.Join(out, "\n"), true
+}
+
+func (v *Vault) appendRepositoryReferenceCleanupLog(date string, bundles []RepositoryReferenceCleanupBundle, result *RepositoryReferenceCleanupResult) error {
+	logRel := "00-meta/log.md"
+	abs, err := v.SafeJoin(logRel)
+	if err != nil {
+		return err
+	}
+	data, err := os.ReadFile(abs)
+	if errors.Is(err, os.ErrNotExist) {
+		if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+			return err
+		}
+		data = []byte(fmt.Sprintf("---\ntitle: \"LLM Wiki Log\"\ntype: log\nstatus: active\ncreated: %s\nupdated: %s\ntags: [log]\ndomain: meta\n---\n\n# Log\n", date, date))
+	} else if err != nil {
+		return err
+	}
+	line := fmt.Sprintf("- %s: Repository reference cleanup consolidated %d repositories into canonical bundles and archived dated fragments.\n", date, len(bundles))
+	if strings.Contains(string(data), strings.TrimSpace(line)) {
+		return nil
+	}
+	updated := strings.TrimRight(string(data), "\n") + "\n" + line
+	if err := os.WriteFile(abs, []byte(updated), 0o644); err != nil {
+		return err
+	}
+	result.RewrittenFiles = append(result.RewrittenFiles, logRel)
+	return nil
+}
+
+func (v *Vault) writeRepositoryReferenceCleanupReport(result *RepositoryReferenceCleanupResult, sharedPages []repositoryReferenceSharedPage) error {
+	reportRel, err := v.uniqueVaultRel(fmt.Sprintf("00-meta/reports/repository-reference-cleanup-%s.md", result.Date))
+	if err != nil {
+		return err
+	}
+	abs, err := v.SafeJoin(reportRel)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(abs), 0o755); err != nil {
+		return err
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	fmt.Fprintf(&b, "title: %s\n", yamlQuote("Repository Reference Cleanup "+result.Date))
+	b.WriteString("type: lint-report\n")
+	b.WriteString("status: active\n")
+	fmt.Fprintf(&b, "created: %s\n", result.Date)
+	fmt.Fprintf(&b, "updated: %s\n", result.Date)
+	b.WriteString("tags: [cleanup, repository-reference, ai-slop-cleaner]\n")
+	b.WriteString("domain: meta\n")
+	b.WriteString("---\n\n")
+	fmt.Fprintf(&b, "# Repository Reference Cleanup %s\n\n", result.Date)
+	fmt.Fprintf(&b, "- Applied: `%t`\n", result.Applied)
+	fmt.Fprintf(&b, "- Archive root: `%s`\n", result.ArchiveRoot)
+	fmt.Fprintf(&b, "- Bundles: `%d`\n", len(result.Bundles))
+	fmt.Fprintf(&b, "- Protected files skipped: `%d`\n\n", len(result.SkippedProtectedFiles))
+	b.WriteString("## Bundles\n\n")
+	for _, bundle := range result.Bundles {
+		fmt.Fprintf(&b, "### [[%s]]\n\n", bundle.BundleSlug)
+		fmt.Fprintf(&b, "- Repository: `%s`\n", bundle.Repository)
+		fmt.Fprintf(&b, "- Bundle path: `%s`\n", bundle.BundlePath)
+		b.WriteString("- Archived fragments:\n")
+		for i := range bundle.FragmentPaths {
+			fmt.Fprintf(&b, "  - `%s` → `%s`\n", bundle.FragmentPaths[i], bundle.ArchivedPaths[i])
+		}
+		b.WriteString("\n")
+	}
+	if len(sharedPages) > 0 {
+		b.WriteString("## Shared References Preserved\n\n")
+		for _, page := range sharedPages {
+			fmt.Fprintf(&b, "- [[%s]] (`%s`)\n", page.Slug, page.Path)
+		}
+		b.WriteString("\n")
+	}
+	if len(result.SkippedProtectedFiles) > 0 {
+		b.WriteString("## Protected Files Not Rewritten\n\n")
+		for _, path := range result.SkippedProtectedFiles {
+			fmt.Fprintf(&b, "- `%s`\n", path)
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("## Changelog\n\n")
+	fmt.Fprintf(&b, "- %s: Generated by `llm-wiki cleanup --scope repository-references --apply`.\n", result.Date)
+	if err := os.WriteFile(abs, []byte(b.String()), 0o644); err != nil {
+		return err
+	}
+	result.ReportPaths = append(result.ReportPaths, reportRel)
+	return nil
+}
+
+func (v *Vault) uniqueVaultRel(rel string) (string, error) {
+	rel = filepath.ToSlash(rel)
+	abs, err := v.SafeJoin(rel)
+	if err != nil {
+		return "", err
+	}
+	if _, err := os.Stat(abs); errors.Is(err, os.ErrNotExist) {
+		return rel, nil
+	} else if err != nil {
+		return "", err
+	}
+	ext := filepath.Ext(rel)
+	base := strings.TrimSuffix(rel, ext)
+	for i := 2; ; i++ {
+		candidate := fmt.Sprintf("%s-%d%s", base, i, ext)
+		abs, err := v.SafeJoin(candidate)
+		if err != nil {
+			return "", err
+		}
+		if _, err := os.Stat(abs); errors.Is(err, os.ErrNotExist) {
+			return candidate, nil
+		} else if err != nil {
+			return "", err
+		}
+	}
+}
+
+func repositoryReferenceRepo(path string) (string, bool) {
+	const prefix = "20-wiki/concepts/repository-references/"
+	if !strings.HasPrefix(path, prefix) {
+		return "", false
+	}
+	rest := strings.TrimPrefix(path, prefix)
+	parts := strings.Split(rest, "/")
+	if len(parts) < 2 || strings.TrimSpace(parts[0]) == "" {
+		return "", false
+	}
+	return parts[0], true
+}
+
+func isRepositoryReferenceBundleSlug(slug string) bool {
+	return strings.Contains(slug, "-reference-bundle-")
+}
+
+func uniqueArchivePath(root, repo, filename string, used map[string]bool) string {
+	rel := filepath.ToSlash(filepath.Join(root, repo, filename))
+	if !used[rel] {
+		used[rel] = true
+		return rel
+	}
+	ext := filepath.Ext(filename)
+	base := strings.TrimSuffix(filename, ext)
+	for i := 2; ; i++ {
+		rel = filepath.ToSlash(filepath.Join(root, repo, fmt.Sprintf("%s-%d%s", base, i, ext)))
+		if !used[rel] {
+			used[rel] = true
+			return rel
+		}
+	}
+}
+
+func cleanupPageTitle(page Page, content string) string {
+	if title := pageTitle(page); title != "" {
+		return title
+	}
+	_, body, ok := ParseFrontmatter(content)
+	if !ok {
+		body = content
+	}
+	if heading := firstMarkdownHeading(body); heading != "" {
+		return heading
+	}
+	return titleizeSlug(page.Slug)
+}
+
+func pageTitle(page Page) string {
+	return strings.TrimSpace(page.Metadata.Title)
+}
+
+func firstMarkdownHeading(body string) string {
+	for _, line := range strings.Split(body, "\n") {
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "#") {
+			return strings.TrimSpace(strings.TrimLeft(line, "#"))
+		}
+	}
+	return ""
+}
+
+func summarizeMarkdownBody(content string) string {
+	_, body, ok := ParseFrontmatter(content)
+	if !ok {
+		body = content
+	}
+	var paragraph []string
+	for _, line := range strings.Split(body, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			if len(paragraph) > 0 {
+				break
+			}
+			continue
+		}
+		if strings.HasPrefix(trimmed, "#") || strings.HasPrefix(trimmed, ">") {
+			continue
+		}
+		paragraph = append(paragraph, trimmed)
+	}
+	summary := sanitizeCleanupSummary(strings.Join(paragraph, " "))
+	summary = whitespacePattern.ReplaceAllString(summary, " ")
+	return truncateRunes(summary, 280)
+}
+
+func sanitizeCleanupSummary(summary string) string {
+	summary = wikilinkPattern.ReplaceAllStringFunc(summary, func(match string) string {
+		parts := wikilinkPattern.FindStringSubmatch(match)
+		if len(parts) != 2 {
+			return match
+		}
+		raw := strings.TrimSpace(parts[1])
+		if split := strings.SplitN(raw, "|", 2); len(split) == 2 && strings.TrimSpace(split[1]) != "" {
+			return strings.TrimSpace(split[1])
+		}
+		return normalizeWikilink(raw)
+	})
+	summary = strings.ReplaceAll(summary, "[[", "")
+	summary = strings.ReplaceAll(summary, "]]", "")
+	return summary
+}
+
+func truncateRunes(s string, max int) string {
+	if max <= 0 {
+		return ""
+	}
+	runes := []rune(s)
+	if len(runes) <= max {
+		return s
+	}
+	if max <= 3 {
+		return string(runes[:max])
+	}
+	return strings.TrimSpace(string(runes[:max-3])) + "..."
+}
+
+func titleizeSlug(slug string) string {
+	parts := regexp.MustCompile(`[-_]+`).Split(slug, -1)
+	for i, part := range parts {
+		if part == "" {
+			continue
+		}
+		runes := []rune(part)
+		runes[0] = unicode.ToUpper(runes[0])
+		parts[i] = string(runes)
+	}
+	return strings.Join(parts, " ")
+}
+
+func compactSortedStrings(values []string) []string {
+	seen := map[string]bool{}
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		if strings.TrimSpace(value) == "" || seen[value] {
+			continue
+		}
+		seen[value] = true
+		out = append(out, value)
+	}
+	sort.Strings(out)
+	return out
+}
+
+var whitespacePattern = regexp.MustCompile(`\s+`)