[scanner] sync-hive-docs heal mode produces refresh PRs that fail the #616 nav guard #624

Summary

Heal mode in scripts/sync-hive-docs.ts (#618, enabled in the daily refresh by #620) appends every drifted upstream page to scripts/sync-hive-docs.files.json and syncs it — but it never adds the page to NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts. The nav guard added by #616 (src/__tests__/page-map-adr-nav-drift.test.ts, "lists every synced page in NAV_STRUCTURE_HIVE") requires every target ?? source in the files list to appear in that nav slice. So the first time the scheduled refresh actually heals anything, the resulting bot/hive-docs-refresh PR fails the required Run unit tests (vitest) check and cannot merge — and because peter-evans/create-pull-request regenerates that single branch daily, the refresh stays red until a human hand-edits the nav.

The two features are individually correct but contradict each other; the self-heal is currently self-defeating.

Evidence (main @ 9a8bbd6)

• scripts/sync-hive-docs.ts healFilesList() / main() — writes FILES_LIST_PATH only; nothing touches page-map.ts:
  

  docs/scripts/sync-hive-docs.ts

  Lines 300 to 312 in 9a8bbd6

  	export function healFilesList(
  	list: SyncFile[],
  	drift: DriftEntry[]
  	): SyncFile[] {
  	return [
  	...list,
  	...drift.map(e => {
  	const target = e.source.replace(/(^|\/)README\.md$/, "$1readme.md");
  	return target === e.source
  	? { source: e.source }
  	: { source: e.source, target };
  	}),
  	];

  
  

  docs/scripts/sync-hive-docs.ts

  Lines 442 to 456 in 9a8bbd6

  	if (heal && drift.length) {
  	healed = drift;
  	const added = healFilesList(files, drift).slice(files.length);
  	for (const f of added) {
  	files.push(f);
  	registerPage(f, true);
  	}
  	// Re-sync everything: links to the new pages now resolve to site routes.
  	refs = new Map();
  	await syncFiles(files, cache, refs);
  	const listPath = path.join(process.cwd(), FILES_LIST_PATH);
  	fs.mkdirSync(path.dirname(listPath), { recursive: true });
  	fs.writeFileSync(listPath, JSON.stringify(files, null, 2) + "\n");
  	drift = detect();
  	}

• src/__tests__/page-map-adr-nav-drift.test.ts — missing must be [], with urlOnly empty:
  

  docs/src/__tests__/page-map-adr-nav-drift.test.ts

  Lines 20 to 56 in 9a8bbd6

  	it("lists every synced page in NAV_STRUCTURE_HIVE", () => {
  	const sync = fs.readFileSync(
  	path.join(process.cwd(), "scripts/sync-hive-docs.ts"),
  	"utf8"
  	);
  	const map = fs.readFileSync(
  	path.join(process.cwd(), "src/app/docs/page-map.ts"),
  	"utf8"
  	);
  	const start = map.indexOf("const NAV_STRUCTURE_HIVE");
  	const end = map.indexOf("const NAV_STRUCTURE_HOTSHOT", start);
  	expect(start).toBeGreaterThan(-1);
  	expect(end).toBeGreaterThan(start);
  	const nav = map.slice(start, end);
  	// Covers both the synced files list (scripts/sync-hive-docs.files.json)
  	// and every `source:` entry in the sync script (`localHiveDocs`): local
  	// hive pages must be in the nav too.
  	const listed: Array<{ source: string; target?: string }> = JSON.parse(
  	fs.readFileSync(
  	path.join(process.cwd(), "scripts/sync-hive-docs.files.json"),
  	"utf8"
  	)
  	);
  	const targets = [
  	...listed.map(f => f.target ?? f.source),
  	...[
  	...sync.matchAll(/source:\s*"([^"]+)"(?:,\s*target:\s*"([^"]+)")?/g),
  	].map(m => m[2] ?? m[1]),
  	];
  	// Pages intentionally reachable by URL only; add a comment per entry.
  	const urlOnly = new Set<string>([]);
  	expect(targets.length).toBeGreaterThan(0);
  	const missing = targets.filter(
  	t => !urlOnly.has(t) && !nav.includes(`'${t}'`)
  	);
  	expect(missing).toEqual([]);
  	});

• .github/workflows/hive-docs-refresh.yml — add-paths is only docs/content + scripts/sync-hive-docs.files.json, so even a nav edit made during the run would not be committed; REQUIRED_CHECK_WORKFLOWS includes vitest.yml:
  

  docs/.github/workflows/hive-docs-refresh.yml

  Line 23 in 9a8bbd6

  # branch (see "Trigger required checks" below).

  
  

  docs/.github/workflows/hive-docs-refresh.yml

  Lines 62 to 64 in 9a8bbd6

  	# instead (same approach as meeting-recordings-refresh.yml).
  	token: ${{ secrets.GITHUB_TOKEN }}
  	signoff: true

Not yet observed in a live run (the first post-#620 cron at 06:17Z has not fired as of filing), but the failure is deterministic from the code: any non-empty healed list produces a files-list entry with no nav entry.

Decision taken by hive

Simplest additive, backward-compatible option: make heal mode complete the job it starts.

1. In scripts/sync-hive-docs.ts heal mode, after appending to the files list, also append one { '<Title>': '<target>' } entry per healed page to the last section of NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts (title derived from the page's first # heading, falling back to the filename), inserted just before that section's closing ]. Keep it a text edit scoped by the existing const NAV_STRUCTURE_HIVE … const NAV_STRUCTURE_HOTSHOT markers the guard already relies on; idempotent (skip targets already present as '<target>').
2. Add src/app/docs/page-map.ts to add-paths in hive-docs-refresh.yml so the nav edit ships in the same refresh PR.
3. Unit-test the nav insertion (new entry appended, existing entry not duplicated, README→readme target used) alongside the existing sync-hive-docs.drift.test.ts.

Report-only mode (PR builds / prebuild) is unchanged. Rejected alternatives: relaxing the #616 guard to skip healed pages (reintroduces the nav holes #616 fixed), or dropping heal mode (reintroduces #612).

Severity: medium — blocks the daily mirror refresh from merging on the first real heal; no data loss.

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88