[hivecommons-hive]

Why

The #616 nav guard (page-map-adr-nav-drift.test.ts) requires every synced page to be listed in NAV_STRUCTURE_HIVE, but heal mode (#618/#620) only appended to sync-hive-docs.files.json. The first real heal would produce a refresh PR failing vitest. The two features contradicted each other.

Change

• Heal mode now also appends { '<Title>': '<target>' } for each healed page to the last section of NAV_STRUCTURE_HIVE (new exported addToHiveNav, text edit between the NAV_STRUCTURE_HIVE/NAV_STRUCTURE_HOTSHOT markers; title from first # heading, else filename; idempotent per '<target>').
• Report-only mode unchanged.
• Unit tests in sync-hive-docs.drift.test.ts: new entry appended, no duplicate, README→readme target.

Refs #624 (needs-human: workflow edit to add-paths in hive-docs-refresh.yml requires the workflows permission the hive App lacks)

Needs a human (workflows permission): add src/app/docs/page-map.ts to add-paths in .github/workflows/hive-docs-refresh.yml

Add this line to the add-paths list of the create-pull-request step:

+            src/app/docs/page-map.ts

(alongside docs/content and scripts/sync-hive-docs.files.json, matching existing indentation.)

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

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Deploy Preview for hivecommons-docs canceled.

Name	Link
🔨 Latest commit	c802289
🔍 Latest deploy log	https://app.netlify.com/projects/hivecommons-docs/deploys/6aec26d1f2ac5009d423a777

[hivecommons-hive]

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

hive/awaiting-ci: CI pending — sweep will merge when green.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

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

Review findings from adjudicator-4 (folded here because this head already carries its hive review):

Style review (read at head be78096; the queued head fef7be8 has been superseded). No blocker — advisory only.

1. The heal→nav wiring is only unit-tested, not exercised end-to-end. sync-hive-docs.main.test.ts:129 points process.cwd() at a temp dir with no src/app/docs/page-map.ts, so the fs.existsSync(pageMapPath) guard at scripts/sync-hive-docs.ts:488 silently skips the new branch in the heal test (main.test.ts:450). As a result navTitle (sync-hive-docs.ts:318-321, unexported) and the cache.get(f.source) → title → f.target ?? f.source mapping (:493-496) have zero coverage. Suggest seeding a minimal page-map fixture in the heal case and asserting the appended entry (and the # heading → title path) — the guard then also stops hiding a missing-fixture regression.

2. Silent no-op when markers are missing. addToHiveNav returns the input unchanged if either NAV_STRUCTURE_* marker or the ] closer is absent (:333, :341), while the drift report still says "Healed: appended … and synced them" (:370). A console.log (or throw, matching heal's fail-loud stance at :461) would make the resulting nav-drift test failure diagnosable from the refresh run.

3. Nit: PAGE_MAP_PATH (:315) is the third path constant but sits mid-file; FILES_LIST_PATH/ALLOWLIST_PATH live together at :34-35.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review (head be78096) — no blockers; CI unit tests green. Verified the splice point against the real src/app/docs/page-map.ts (inserts before the ] closing the Reference items, after the trailing-comma env-vars.md entry) and that the generated '<target>' literal is exactly what src/__tests__/page-map-adr-nav-drift.test.ts:52 checks for.

Advisory, non-blocking:

1. Nav title is taken from the un-scrubbed upstream text. scripts/sync-hive-docs.ts:494 calls navTitle(cache.get(f.source)), but the cache holds the raw fetched content (:430); scrubLegacyBranding is only applied on the write path (:442). A healed page whose # heading still carries legacy branding will surface it verbatim in the sidebar. Suggest navTitle(scrubLegacyBranding(cache.get(f.source) ?? ""), f.source).
2. As the PR body says, until .github/workflows/hive-docs-refresh.yml:67-69 add-paths includes src/app/docs/page-map.ts, the refresh PR still won't carry the nav edit, so the vitest failure this fixes persists on real heal runs until [scanner] sync-hive-docs heal mode produces refresh PRs that fail the #616 nav guard #624 is actioned. Not a regression — same state as today.
3. Healed adr/*.md siblings land flat in Reference rather than inside the 'Architecture Decision Records' group (scripts/sync-hive-docs.ts:341 always targets the section's last ]). Passes the guard; cosmetic only.

Hive filed review findings that do not block this PR as backlog items:

• [reviewer] Review backlog (correctness): listUpstreamDocs ignores the trees API truncated flag #619 (folded into an existing issue) — [reviewer] Review backlog (correctness): Healed ADR pages appended flat rather than into the ADR group ([reviewer] Review backlog (correctness): listUpstreamDocs ignores the trees API truncated flag #619)

Cap: 10 backlog item(s) per PR per day.

Review findings from reviewer (folded here because this head already carries its hive review):

Looks correct to me; the heal path and the #616 guard now agree.

What I verified at be78096:

• scripts/sync-hive-docs.ts:333-345 — addToHiveNav slices the same const NAV_STRUCTURE_HIVE … const NAV_STRUCTURE_HOTSHOT region and dedupes on '<target>', which is exactly the check src/__tests__/page-map-adr-nav-drift.test.ts:28-54 performs (nav.includes(\'${t}'`)witht = target ?? source`). A healed page therefore satisfies the guard on the next vitest run.
• src/app/docs/page-map.ts:203 — in the real file the last ] inside the hive region is the Reference section's items close (the nested ADR list closes as ] }, at :201, which lastIndexOf(" ]") correctly skips past). Insertion lands before ] with 6-space indent, matching the existing entries.
• scripts/sync-hive-docs.ts:483,494 — cache is populated by the second syncFiles pass before navTitle reads it, so healed pages do get their # heading rather than the filename fallback.
• The first guard test (:13-18, ADR regex over the whole file) also holds for a healed adr/*.md: the regex is position-independent, so an ADR appended to the Reference section still counts.

Two notes, neither a defect:

• Healed ADRs land in the last section rather than the nested ADR list — fine for keeping CI green; a human may want to move them when curating.
• navTitle (:318) takes the first # line anywhere in the page, so a page whose first such line is inside a fenced shell block would get that as its title. Unlikely for upstream docs; mentioning only so nobody is surprised.

As the body says, this PR alone does not make the refresh PR green: hive-docs-refresh.yml:67-69 add-paths still omits src/app/docs/page-map.ts, so the nav edit is written but never committed. That one-line workflow change needs a maintainer with the workflows permission; the Refs #624 (needs-human: …) line routes it correctly.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

The code is correct; the fix is only complete once a human edits the workflow.

Read the tree at be78096, not just the diff:

• addToHiveNav (scripts/sync-hive-docs.ts:327-343) slices the same NAV_STRUCTURE_HIVE…NAV_STRUCTURE_HOTSHOT region and tests presence with the same '<target>' quoting that the fix(nav): add synced crux-lanes and work-sources pages to the hive nav and guard all synced pages #616 guard uses (src/__tests__/page-map-adr-nav-drift.test.ts:28-33, 52). So anything the heal appends is exactly what the guard looks for, and the dedupe check cannot disagree with it.
• lastIndexOf(" ]") resolves to the last section's items close at src/app/docs/page-map.ts:203 (after the nested ADR group's ] }, on 201), and the inserted line uses the same 6-space indent as line 202. Verified against the real file, not only the test fixture.
• cache is filled by syncFiles (sync-hive-docs.ts:429-430, called at 483) before navTitle(cache.get(f.source) …) at 494, so titles come from real content, not the "" fallback.
• target: f.target ?? f.source (line 495) matches both healFilesList's README→readme rewrite and the guard's f.target ?? f.source at test line 46.
• npx vitest run scripts/sync-hive-docs.drift.test.ts → 16 passed locally.

Remaining gap, already stated in the PR body and confirmed in the tree: .github/workflows/hive-docs-refresh.yml:67-69 lists only docs/content and scripts/sync-hive-docs.files.json in add-paths. Until src/app/docs/page-map.ts is added there, a heal run will edit the nav in the runner's checkout and then drop it, and the resulting refresh PR will still fail the guard — the exact failure this PR exists to prevent. That is a .github/workflows/ edit (CODEOWNERS: clubanderson KPRoche), so it needs one of you, either as a follow-up commit on this branch or a separate PR merged alongside.

Minor, not blocking: if the last hive section ever ends with a nested group ( ] },) rather than a flat entry, lastIndexOf(" ]") will match inside that group's closing line and the new entry lands inside the nested group — still valid syntax and still satisfies the guard, just a different nav position.

I have not approved or changed anything.

Evidence bundle `#625c802289` sha256:7d2b9c13bf65e0769f07092a1b4e268f5ec9d05f90a8fcd4d8af2aa9dc3a898c — download from the dashboard or `hivectl review evidence #625`.

[hivecommons-hive]

docs-currency review (read at head be78096, which has moved on from the queued fef7be8)

The code change is sound, but the operator-facing text that describes heal mode was not updated and now understates what a heal run touches:

1. README.md:30-31 — still says heal mode "appends the drift to the list and syncs the new pages". It now also rewrites src/app/docs/page-map.ts (scripts/sync-hive-docs.ts:487-499). Add "...and adds a nav entry for each to NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts".
2. scripts/sync-hive-docs.ts:232-234 (the "File-list drift" header comment) — same stale sentence; same fix.
3. scripts/sync-hive-docs.ts:370 — the step-summary/PR report line Healed: appended N page(s) to scripts/sync-hive-docs.files.json and synced them: doesn't mention the page-map edit. Until the add-paths change from #624 lands, that edit is silently dropped from the refresh PR, so an operator reading the summary has no cue that page-map.ts was modified. Suggest: ...to \${FILES_LIST_PATH}` and `${PAGE_MAP_PATH}`, and synced them:`.
4. changelog.d/ — no fragment for this PR. changelog.d/README.md asks for one per user-visible change, and the still-unrolled added-612-sync-hive-docs-drift-check.md:5-6 describes heal mode with the old wording. Add e.g. changelog.d/fixed-625-heal-mode-hive-nav.md: "- sync-hive-docs heal mode now also adds each healed page to NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts, so refresh PRs pass the #616 nav guard (#625)."

All four are small text edits; no behavior concerns from this perspective. The workflow add-paths gap is already tracked in #624 and the PR body, so I am not re-raising it.

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

[hivecommons-hive]

Needs a decision, not a merge:

• the reviewer swarm returned requires_human @be78096
• the review found: sensitive-paths question from the correctness review
• reviewer question: @clubanderson should add src/app/docs/page-map.ts to the add-paths list in .github/workflows/hive-docs-refresh.yml (lines 67-69) so a heal run's nav edit actually reaches the refresh PR; the App cannot push workflow edits.
• the automerge lane will not merge this unattended

Head: verdict requires_human @be78096, 6/6 checks green, DCO yes, soak 0s of 10m0s.

What to do: approve this head (be78096) to merge as-is, or leave a changes requested review (or reply /hive decision <what to change>) and the hive will push the fix.

How to release it:

• After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed.

_{Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.}

[hivecommons-hive]

Read the tree, not just the diff. This looks correct to me.

• The membership check in addToHiveNav (scripts/sync-hive-docs.ts:340, region.includes(quote(p.target))) uses the same '<target>' string shape the #616 guard tests at src/__tests__/page-map-adr-nav-drift.test.ts:52-54, and the target it inserts is f.target ?? f.source (scripts/sync-hive-docs.ts:500) — the same expression the guard builds from files.json (line 44). So a healed README.md lands as 'readme.md' on both sides.
• The section-closer anchor (/^ {4}\]$/gm, last match) picks line 203 ] of page-map.ts on main — the real last NAV_STRUCTURE_HIVE section — and the new test for a trailing nested sub-list covers the case the previous head got wrong.
• cache.get(f.source) for the title is populated by the re-sync at scripts/sync-hive-docs.ts:433-434, which runs before the page-map write, so healed pages do have content at that point.

One verified status note, not a defect in this PR: .github/workflows/hive-docs-refresh.yml:67-69 still lists only docs/content and scripts/sync-hive-docs.files.json under add-paths, so until a human adds src/app/docs/page-map.ts there (#627 / the "Needs a human" section above), a heal run edits page-map.ts on the runner but the refresh PR will not carry it, and that PR still fails the #616 guard. Same outcome as today, so this PR is safe to land first; the workflow line is what completes the fix.

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