Structural debt audit — wiki IA and operational maturity¶

Purpose: Name structural tech debt as the wiki grows (hundreds of pages, 120+ analyses): analysis sprawl, weak canonical ownership, guide-shaped pages without a clear type, maturity signals that don’t distinguish “essay” from “field procedure,” and navigation pain from flat index.md lists. Complements Structural audit — repository shape and canonical routing, Structural audit — page ownership, entity gaps, and hub routing, and Domain content overview.

Epistemic: Counts are approximate (repository snapshot); re-count with find wiki/analyses -name '*.md' | wc -l.

1. Findings¶

Signal	Evidence	Risk
Large `analyses/` cardinality	~123 markdown files under `wiki/analyses/` vs ~430 total wiki pages	Readers land on query syntheses, one-off summaries, and canonical chapters without a sort key in the filename alone.
Parallel “overview” voices	Domain overview, strategic audit, execution readiness audit, repository analysis	Three competing “north stars” if not labeled—mitigated by role labels in `Domain content overview` and this audit’s routing table.
Meta-audit proliferation	Multiple structural / strategic / IA / gap audits	Backlog drift if tables are copied instead of linked—follow `AGENTS.md` canonicalization.

Mitigation (governance): AGENTS.md — Canonicalization before proliferation, hub maintenance, page ownership map (structural-audit-page-ownership-entity-gaps-and-hub-routing).

Signal	Evidence	Risk
Clusters without a named owner	Described in ownership audit table	Duplicate chapters and inconsistent gates.
Guide packages only under `analyses/`	e.g. Pi k3s / Longhorn runbook hub	Discoverability depends on index lines and topic hubs—not a separate directory (by design today).

Mitigation: Topic hubs (Two-site smart farm operations, Wiki navigation and structural hubs), business-plan package hub, reference architecture hub.

Gap	What was wrong	Target state
No first-class `guide` directory	Runbooks and how-to packages use `page_type: analysis` only	Keep paths flexible; document `page_subtype` `operational_guide` or `standard` in `AGENTS.md`.
`status` vs “how tested”	`draft` / `active` / `deprecated` lifecycle ≠ pilot vs field	Add optional `operational_maturity` orthogonal to `status` (see `AGENTS.md`).

Signal	Problem
`review_status`	Editorial quality (`unreviewed` / `reviewed` / `stale`), not deployment provenance.
`confidence`	Epistemic source strength, not “we ran this drill twice.”

Target: Optional operational_maturity: draft → pilot_ready → field_tested; use superseded together with superseded_by.

Pain	Mitigation implemented
Single long “Analyses” list in `index.md`	`Wiki navigation and structural hubs` — themed tables to canonical entries (not a full mirror).
Agents start from `index` only	`index.md` Overview links this audit and the navigation topic.

Fix	Where
`page_subtype` and `operational_maturity` documented	`AGENTS.md` — Page taxonomy + Frontmatter schema
Navigation hub (grouped routing )	`Wiki navigation and structural hubs`
Debt audit (this page )	Canonical meta record for 2026-04 IA / ops maturity policy**
Exemplar frontmatter on Pi runbook hub	`How to provision k3s, Longhorn, and Rancher on a Raspberry Pi fleet` — `page_subtype: operational_guide`, `operational_maturity: pilot_ready`
Index + domain overview + ownership audit cross-links	`index.md`, `domain-content-overview.md`, `structural-audit-page-ownership-entity-gaps-and-hub-routing.md`

Incrementally tag runbooks and standards with page_subtype + operational_maturity when touched.
Prefer extending canonical hubs over new parallel “overview” analyses — log exceptions in wiki/log.md.
Optional validator warning: unknown operational_maturity values (future ).