Skip to main content

Docs Pipeline

The documentation-maintenance pipeline turns code changes into reviewed documentation updates — grounded in the product code, held for human approval, never auto-published.

  • Proposes one concrete, structured change per area (append / replace-section / create), grounded strictly in the code — never free prose.
  • Scans every proposal for secret leaks and MDX-safety before it can reach the review gate.
  • Holds each proposal at a human gate; on approval, opens a pull request, merges, and verifies the published site.

Implementation​

DocsProposeService (api/src/tenancy/docs-propose.service.ts) drives proposals in three grounding modes:

  • Journal mode — reasons over the recent project journal via RagService and AgentClient embeddings (NAMESPACE="journey", TOP_K=8).
  • Code+doc mode — active when groundPaths (or a GROUND ON: block) are present: reads the real source with readGroundFiles (CODE_FILE_CAP=64_000, non-silent truncation), extractGroundPaths (MAX_GROUND_FILES=12, bounded ** glob), then assembles via assembleGroundingBlock.
  • Arch mode (docs/ARCH_* targets) — selects the SYSTEM_ARCH prompt, appends MODULE WIRING evidence from scanModuleWiring (honest "foundation only — not yet wired" for zero-importer modules), and runs value-only scanForSecretValues.

validate / validatePinned enforce inventory (live GithubInventorySource from GitHub main), unambiguous sections, MDX safety (scanMdxHazards), and unconditional leak guards (leak-scan.ts). They also run nearDuplicateRatio (trigram-Jaccard) and abstain at NEAR_DUP_THRESHOLD=0.97, plus attach SectionOverwrite (from computeSectionOverwrite in section-overwrite.ts) as overwriteWarning on replace_section. Empty content yields a grounded abstain. applyChange proves each edit is surgical in memory. leak-scan.ts additionally maintains USER_FACING_SCHEMA_ALLOWLIST (exact-match only) so user-facing stewardship columns are exempt from the schema-id block.

Publication is performed by GithubDocsPrService (api/src/tenancy/github-docs-pr.service.ts, wired by 3 callers). It first calls assertNoPublicSchemaLeak (both path and content signatures for DDL/RLS/ERD/catalog) then, after a recorded hil_decision=approved check in provenance_ledger, opens or reuses a branch via branchFor + idempotent findOpenPr, applies the change, waits via pollMergeable, merges with classified bounded retry in mergeWithRetry/classifyMergeError (transient vs. conflict/auth), records docs_publish_failed on error, runs cleanupAfterMerge + reconcileDocsPrs, and finally verifies live content via confirmDeploy/pollDeploy (marker-based, with DOCS_ACTION_TOKEN re-run only for deploy-job failures). Tokens are fetched from org_secrets via DOCS_PR_TOKEN/DOCS_MERGE_TOKEN/DOCS_ACTION_TOKEN and never embedded. DocsPublishStatusController (api/src/tenancy/docs-publish-status.controller.ts) surfaces the docs_publish_failed ledger and supports owner/admin reconcile.