Canonical Doc Frontmatter Audit — 2026-05-15
Context
The 15 canonical docs from fin-agentic/docs/ were copied into fin-central-intranet as part of the Tenant Zero bootstrap (TZ-1 of the Phase 1 follow-on plan). Per DocContent schema (Engineering Spec §3.1) every doc needs 30+ fields in frontmatter for the ingest pipeline to classify, embed, and project correctly.
This audit captures the gap between current frontmatter and required.
Current frontmatter inventory
Docs with NO frontmatter at all (4)
These cannot be classified by doc_kind at all. The ingest pipeline will reject them or default to doc_kind: authored with no further metadata.
| File | Notes |
|---|---|
docs/design/FIN_INTRANET_HUMAN_AGENT_PROJECTION_LAYER_DESIGN_2026-05-13.md | Should be doc_kind: authored, data_plane: universal_intelligence, visibility: company |
docs/engineering/FIN_AGENTIC_HARNESS_SPEC_2026-05-15.md | Should be doc_kind: authored, visibility: company |
docs/engineering/FIN_INTRANET_HUMAN_AGENT_PROJECTION_ENGINEERING_SPEC_2026-05-13.md | Should be doc_kind: authored, visibility: company |
docs/projections/PROJECTION_CATALOG_2026-05-15.md | Per its own §11: “This catalog is itself a doc and lives in the GitHub vault.” Should be doc_kind: authored with tags: [projection_catalog, master_inventory] |
Docs with partial frontmatter (11)
All have the standard 7-field convention (doc_id, title, status, audience, maintained_by, last_revised, review_cadence). Missing required DocContent fields per §3.1.
| File | Has | Missing required |
|---|---|---|
docs/FIN_PLATFORM_DOC_INDEX.md | 7 fields | schema_version, doc_kind, slug, source_system, visibility, data_plane, lifecycle_status, tags, source_attribution, created_at, updated_at |
docs/architecture/FIN_CENTRAL_TENANT_DEMARCATION_PLAN_2026-05-15.md | 7 fields | (same set as above) |
docs/architecture/FIN_MCP_SURFACE_ARCHITECTURE_2026-05-15.md | 7 fields | (same set) |
docs/engineering/FIN_API_LAYER_SPEC_2026-05-15.md | 7 fields | (same set) |
docs/policies/anonymization/FIN_ANONYMIZATION_POLICY_V1_2026-05-15.md | 10 fields (has policy_version, effective_date, supersedes) | schema_version, doc_kind, slug, source_system, visibility, data_plane, lifecycle_status, tags, source_attribution, created_at, updated_at |
docs/product/FIN_DATA_SIGNAL_OFFERINGS_2026-05-15.md | 7 fields | (same set) |
docs/product/FIN_PRODUCT_TIER_ARCHITECTURE_2026-05-15.md | 7 fields | (same set) |
docs/programs/FIN_TWO_WEEK_EXECUTION_PROGRAM_2026-05-15.md | 8 fields (has program_window) | (same set) |
docs/reference/FIN_FOUNDER_BIO_2026-05-15.md | 7 fields | (same set) |
docs/runbooks/PHASE_1_DEMARCATION_PROVISIONING_RUNBOOK_2026-05-15.md | 7 fields | (same set) |
docs/runbooks/PHASE_5_FIN_CENTRAL_INTRANET_BOOTSTRAP_RUNBOOK_2026-05-15.md | 7 fields | (same set) |
Recommended remediation
Pattern for “authored” canonical docs
---
schema_version: 1
doc_id: <existing>
doc_kind: authored
title: <existing>
slug: <kebab-case-from-doc-id>
source_system: github_vault
visibility: company # or partner / federal / mixed if originally `audience` field implied broader
data_plane: universal_intelligence # for FIN-level platform docs
lifecycle_status: active # was `status: canonical` — map to `active`
tags: [<keywords from doc>]
source_attribution: ["author:rob_garcia"]
created_at: <YYYY-MM-DDT00:00:00Z> # use last_revised as proxy if unknown
updated_at: <YYYY-MM-DDT00:00:00Z> # use last_revised
# existing 7-field convention preserved for backward compat:
audience: <existing>
maintained_by: <existing>
last_revised: <existing>
review_cadence: <existing>
---Pattern for “decision_record” docs
Same as authored, plus body must be 100% authored sections (§3.4).
Pattern for “runbook” docs (Phase 1 + Phase 5)
---
schema_version: 1
doc_id: <existing>
doc_kind: runbook
title: <existing>
slug: <kebab-case>
source_system: github_vault
visibility: company
data_plane: universal_intelligence
lifecycle_status: active
last_validated_at: <ISO datetime when last walked through> # runbook-specific
tags: [<keywords>]
source_attribution: ["author:rob_garcia"]
created_at: ...
updated_at: ...
---Pattern for FIN_PLATFORM_DOC_INDEX.md (special)
This is itself an index doc but also serves as the rendered intranet home page. Should be doc_kind: authored with tags: [doc_index, intranet_home, master_navigation].
Pattern for PROJECTION_CATALOG_2026-05-15.md (special)
Per its own §11, the catalog is a doc but also a decision_record for the system of intelligence surface area. Could be either doc_kind: authored or doc_kind: decision_record. Recommend authored since it’s an ongoing reference, not a one-time decision.
Status mapping (existing status field → DocContent lifecycle_status)
Existing status | DocContent lifecycle_status |
|---|---|
| canonical | active |
| draft | draft |
| superseded | archived (plus superseded_by retained) |
| stale | archived (plus stale_reason note) |
| archived | archived |
Visibility mapping (existing audience → DocContent visibility)
Existing audience | DocContent visibility (5-state) | Notes |
|---|---|---|
| internal | company | |
| partner | partner_visible / company | depends on which partners — explicit per doc |
| public | public_anonymized / customer_visible | depends on aggregation |
| federal | restricted (with audience flag) | federal_audience_flag = true |
| mixed | mixed | renderer enforces per-section visibility |
| all | company | the doc index is “all” but visibility is still company in v0.2 |
Open question for resolution
Should canonical fin-agentic/docs/ docs be authoritatively edited in the fin-central-intranet vault, or in their original fin-agentic/docs/ location?*
Per Engineering Spec §3.7 (“GitHub Is The Authored Doc Ledger”) + handoff §3.7: authored markdown source lives in GitHub. The question is which GitHub repo.
Options:
- Vault is authoritative — edit here, fin-agentic/docs/ is just for in-repo developer reference. Vault webhook ingest is the only path into
knowledge.domain = doc. - fin-agentic/docs/ is authoritative — vault is a sync mirror. Periodic sync job moves authored content into the vault.
- Hybrid — vault is authoritative for content the agent surfaces (entity profiles, runbooks, policies); fin-agentic/docs/ keeps developer-targeted technical specs.
This is a real architectural decision that affects the ingest pipeline design. Resolve before T7 lands the vault webhook.
Phase 1 vs T7 dependency
This frontmatter cleanup IS part of T7’s scope (Doc projection pipeline scaffold). The audit lives here so the scope is clear before T7 starts. Don’t attempt to fix the 26+ frontmatter gaps as part of Phase 1 — that’s pipeline preparation work, not provisioning work.