Multi-repo wiki workflow¶

The bidirectional contract¶

The wiki and code repos have a two-way relationship:

Wiki → Code repos (read): Every code repo mounts the wiki as a git submodule (./wiki) or references it via HTTPS. The repo's CLAUDE.md lists the specific wiki pages that must be read before writing any code for a given module. The wiki spec is the acceptance criteria.

Code repos → Wiki (write back): When code changes, a CI hook raises a PR in bank-wiki to update module status and documentation. This keeps the wiki current without manual effort.

How chat sessions feed the wiki¶

Planning chat (claude.ai)
    ↓ "generate wiki handoff files"
Handoff .md files (downloaded)
    ↓ dropped into bank-wiki/handoffs/
Claude Code (bank-wiki repo)
    ↓ "process all handoff files"
Wiki pages written, committed, pushed
    ↓ GitHub Actions triggers
Wiki site rebuilt and deployed

How code changes update the wiki¶

Engineer ships a module (e.g. MOD-009 built and merged)
    ↓ CI pipeline runs update-wiki.sh
PR raised in bank-wiki:
  - source/entities/modules/MOD-009.yaml: build_status → Built, code_commit → SHA
  - systems/SD02-kyc-platform/MOD-009-*.md: recompiled by compile.py
    ↓ Compliance reviews and merges
Wiki updated, site rebuilds

update-wiki.sh (CI hook in each code repo)¶

#!/bin/bash
# Called by CI after a module is merged or deployed
# Arguments: MODULE_ID STATUS COMMIT_SHA [NOTES]

MODULE=$1   # e.g. MOD-009
STATUS=$2   # Built | Deployed
COMMIT=$3   # git SHA
NOTES=$4    # optional engineer notes

# Clone wiki, create branch, update module front-matter
git clone git@github.com:bank/bank-wiki.git /tmp/wiki
cd /tmp/wiki
git checkout -b "ci/update-${MODULE}-$(date +%Y%m%d-%H%M)"

# Update build_status and code_commit in module page front-matter
# (uses yq or sed to update YAML)

git commit -am "chore(${MODULE}): status → ${STATUS} [${REPO}@${COMMIT}]"
git push origin HEAD

# Raise PR via GitHub CLI
gh pr create \
  --title "docs: ${MODULE} status update — ${STATUS}" \
  --body "Auto-raised by CI. Code: ${COMMIT}. ${NOTES}" \
  --label "auto-update,module-status"

Branch protection rules¶

Change type	Who can merge
Module status updates (build_status only)	Auto-merge if only module-register.yaml changed
Architecture page updates	1 tech lead approval
Policy content changes	CCO or delegate approval
Policy status changes (Draft → Approved)	CEO + CCO approval
Regulation register updates	CCO approval
Planning chat handoffs (new topics)	Domain owner approval within 48h

Staleness detection¶

Nightly CI job alerts when: - Module merged but wiki PR pending > 5 days → Slack alert to tech owner - Policy review date passed → Email to policy owner - Module status = Deployed but page = Draft → CI warning in code repo - Wiki submodule > 7 days behind main → Auto-PR to update submodule ref