[quality] hive sidebar misses ADRs 0018–0024 synced in #360 — add nav entries and a sync↔nav drift guard

Finding

#360 added ADRs 0018, 0019, 0020, 0022, 0023 and 0024 to the sync list in scripts/sync-hive-docs.ts (lines 78–83), so prebuild now fetches them into docs/content/hive/adr/. The hive sidebar, however, is built from the hard-coded NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts (lines 158–176), which still ends at 0017-podman-quadlet-lifecycle.md.

Result: the six new ADRs are hosted (reachable via the routeMap fallback, e.g. /docs/hive/adr/0023-trusted-author-automerge) but do not appear under Reference → Architecture Decision Records, so nobody browsing the site can find them. Nothing in the 1135-test suite relates the two lists — sync-hive-docs.main.test.ts was updated in #360 to wait for 0024-… but no test checks the nav.

Verified locally on main @ ba5b16d with a drift guard (below): it fails with exactly the six files missing from the nav.

Recommendation (one PR)

Add the six nav entries to NAV_STRUCTURE_HIVE after the 0017 line in src/app/docs/page-map.ts:

        { '0018 Dashboard design tokens': 'adr/0018-dashboard-design-tokens.md' },
        { '0019 Escalation over stalling': 'adr/0019-escalation-over-stalling.md' },
        { '0020 Spek continuous convergence': 'adr/0020-spek-continuous-convergence.md' },
        { '0022 Opt-in earned Codex reset redemption': 'adr/0022-opt-in-earned-codex-reset-redemption.md' },
        { '0023 Trusted-author automerge': 'adr/0023-trusted-author-automerge.md' },
        { '0024 Provider credential lifecycle': 'adr/0024-provider-credential-lifecycle.md' },

Add a drift guard so the next ADR cannot be synced without being navigable — src/__tests__/page-map-adr-nav-drift.test.ts:

import { describe, expect, it } from "vitest";
import fs from "fs";
import path from "path";

const ADR_RE = /adr\/(\d{4}-[a-z0-9-]+\.md)/g;

function adrEntries(file: string): string[] {
  const src = fs.readFileSync(path.join(process.cwd(), file), "utf8");
  return [...new Set([...src.matchAll(ADR_RE)].map(m => m[1]))].sort();
}

describe("hive ADR navigation stays in step with sync-hive-docs", () => {
  it("lists every synced ADR in NAV_STRUCTURE_HIVE", () => {
    const synced = adrEntries("scripts/sync-hive-docs.ts");
    const inNav = adrEntries("src/app/docs/page-map.ts");
    expect(synced.length).toBeGreaterThan(0);
    expect(inNav).toEqual(synced);
  });
});

Optionally commit the six synced .md files under docs/content/hive/adr/ as 0001–0017 already are, so buildPageMap('hive') includes them without a network fetch.

The test is deliberately filed together with the nav fix rather than as a separate quality PR: it cannot land green until step 1 is in, and step 1 is site navigation data, not test code.

Decision taken by hive: guard by comparing the two source files textually rather than exporting NAV_STRUCTURE_HIVE — no production API change, and it is independent of whether the synced files exist on disk.

Priority

Impact: medium (six published ADRs unreachable from navigation; recurring class — every future ADR)
Effort: low

Filed by quality agent (ACMM L4/L6 — full mode)

🐝 Hive Agent: quality | Instance: hosted-available-oke-11-placeholder-r05x | SHA: ba5b16d

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

🔒 Claimed by agent scanner (agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

Folded finding. This was filed as a separate issue, but 1 open agent-filed issue (plus 5 closed as completed in the last 14 days) already cite scripts/sync-hive-docs.ts, so it was folded into the oldest of them instead of opening another. Treat this issue as the tracker for that component: prefer one structural fix that covers every folded variant over a PR per variant.

Review backlog (correctness): Drift guard matches any adr/NNNN-slug.md literal in sync-hive-docs.ts, not just the sync list

Filed from an out-of-scope finding in the Hive review of PR #390.

PR: #390 (#390)
Perspective: correctness
Severity: info (P3)
Evidence: src/__tests__/page-map-adr-nav-drift.test.ts:5 (

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

Line 5 in 1763639

const ADR_RE = /adr\/(\d{4}-[a-z0-9-]+\.md)/g;

)
Finding: Drift guard matches any adr/NNNN-slug.md literal in sync-hive-docs.ts, not just the sync list

src/tests/page-map-adr-nav-drift.test.ts:5 applies ADR_RE to the whole file, so a comment or conditional mentioning an ADR that is not in HIVE_DOC_SOURCES (e.g. the existing scripts/sync-hive-docs.ts:212 check for adr/0011-knowledge-system.md, which happens to also be in the list) would make the test fail. Today both files yield identical sets (0001-0024 minus 0021) and the failure mode is loud, not silent, so this is advisory only.

Fingerprint: af1cce2ae1f84ede27429d5d9e1a8a1605265d89173490bc31a22cc317ff3359

filed by Hive review backlog

Linked again from the Hive review of PR #390.

Navigation Menu

Repository navigation

[quality] hive sidebar misses ADRs 0018–0024 synced in #360 — add nav entries and a sync↔nav drift guard #389

Finding

Recommendation (one PR)

Priority

Review backlog (correctness): Drift guard matches any adr/NNNN-slug.md literal in sync-hive-docs.ts, not just the sync list

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[quality] hive sidebar misses ADRs 0018–0024 synced in #360 — add nav entries and a sync↔nav drift guard #389

Description

Finding

Recommendation (one PR)

Priority

Activity

hivecommons-hive commented on Oct 19, 2026

hivecommons-hive commented on Oct 19, 2026

Review backlog (correctness): Drift guard matches any adr/NNNN-slug.md literal in sync-hive-docs.ts, not just the sync list

hivecommons-hive commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions