FIN Central

ADR-003: Doc canon authoritative repo — `fin-central-intranet`

3 min read

ADR-003: Doc canon authoritative repo — fin-central-intranet

Status: accepted (2026-05-15) Date decided: 2026-05-15

Context

Engineering Spec §3.7 (“GitHub Is The Authored Doc Ledger”) requires that authored markdown source live in GitHub. The execution handoff §5.2 (No Repo Fork) keeps a single fin-agentic codebase serving both Central and tenant deployments. So which repo holds the authored docs?

Today both have copies after TZ-1 (Tenant Zero canon copy):

  • fin-agentic/docs/ — original location of all 15 canonical docs
  • fin-central-intranet/docs/ — copies seeded today via TZ-1

Without a tie-breaking decision, both will drift. Engineering Spec doesn’t prescribe which GitHub repo is authoritative — only that GitHub is.

Decision

fin-central-intranet is the authoritative source for canonical docs going forward. fin-agentic/docs/ becomes a transition mirror, eventually trimmed to code-adjacent docs only.

Effective immediately (2026-05-15):

  • All NEW canonical docs are authored in fin-central-intranet first
  • All EDITS to existing canonical docs land in fin-central-intranet first; fin-agentic/docs/ may be updated as a courtesy mirror but is not authoritative
  • The vault webhook (Phase 5 §5) ingests from fin-central-intranet ONLY into knowledge.domain = doc — fin-agentic/docs/ is NOT ingested

Eventual end state (timeline TBD):

  • fin-agentic/docs/ shrinks to just code-adjacent docs:
    • AGENTS.md (root) — operating contract for Claude Code in this repo
    • db/schema.sql (root) — schema reference
    • Maybe inline READMEs per package
  • Everything else (design specs, engineering specs, architecture, product, GTM, policies, runbooks, handoffs, decisions, reference) lives ONLY in fin-central-intranet

Consequences

Positive

  • Single source of truth for authored canonical docs
  • Vault webhook can safely ingest without worrying about which repo has the newest version
  • Doc projection pipeline (T7 — doc_backlink_projection + entity_doc_projection) operates against a coherent input
  • Partner-facing intranet (Quartz at central.fintail.net) renders the same content the agent operates on — no surprise drift between human-visible and agent-visible
  • Aligns with FIN-As-Tenant-Zero discipline — the FIN intranet runs on the platform it describes; that intranet IS fin-central-intranet

Negative

  • Transition period — both repos have content for now; risk of edits in fin-agentic/docs/ not propagating
  • Existing tooling that reads fin-agentic/docs/ (CI scripts, IDE plugins) needs updating
  • fin-agentic PRs that change docs become two-step: edit in vault, mirror in fin-agentic (or the reverse). Mitigation: scripts to sync, eventually retire fin-agentic/docs/

Neutral

  • The canonical doc tree under fin-central-intranet/docs/ mirrors the structure prescribed in FIN_PLATFORM_DOC_INDEX.md “Repo Organization (Target)” section — design/, engineering/, architecture/, product/, projections/, audits/, decisions/, runbooks/, sops/, reference/, proof/, policies/, programs/, handoffs/, archive/

Implementation

Done 2026-05-15:

  • TZ-1 copied 15 canonical docs from fin-agentic/docs/ to fin-central-intranet/docs/
  • Frontmatter audit doc landed at docs/audits/FRONTMATTER_AUDIT_2026-05-15.md surfacing the gap between current frontmatter and the full DocContent schema (most existing docs have only the 7-field convention)
  • Phase 5 §1 (Quartz render repo) verified building against fin-central-intranet content end-to-end (113 md → 353 HTML)

Pending:

  • Frontmatter expansion across the 15 originals to match full DocContent schema (per audit doc — landed during T7 or as a focused doc-cleanup session)
  • fin-agentic/docs/ trim plan (which docs stay code-adjacent; which retire)

Graph View