Project Context Convergence Playbook¶

Standard: STD-REPO-002 Formula: blucity-packs/formulas/project-context-converge.yaml CI component: blueflyio/gitlab_components → jobs/validate-project-context.yml Owner: HARBORMASTER Trigger: New repository onboarding, quarterly audit, or remediation Bead.

What Must Be True Before Starting¶

BEAD_CLAIMED=YES
RIG_IDENTIFIED=YES
TARGET_REPO_ACCESS=YES         # read + write to target repository
BLUCITY_DOCS_READ_ACCESS=YES  # to verify what belongs centrally

Step 1 — Inventory¶

# In the target repository
git ls-files | wc -l                  # total tracked files
git ls-files | grep "\.md$" | wc -l  # markdown files
ls -1                                 # root-level entries

Record:

TRACKED_FILES=
MD_FILES=
ROOT_FILES_PRESENT=      # README, AGENTS, CLAUDE, llms.txt, OWNERSHIP
ROOT_FILES_MISSING=

Step 2 — Classify Every Root File¶

Apply the placement test (STD-REPO-002 §1):

If this repository disappeared tomorrow, who would still need this information?

For each file / directory:
  BELONGS=  # project | blucity-docs | beads | gitlab | agentictools | blucity-packs | delete

Red flags:

- BluCity-Docs doctrine copied into AGENTS.md / CLAUDE.md
- Shared Skills/Agents defined locally instead of in AgenticTools
- Bead backlog or session state in Markdown files
- `.gc/` or runtime cache tracked in Git
- Machine-absolute paths (e.g. ~/...)
- `scratch/`, `agent-memory/`, `verification/` directories
- vendor files (CLAUDE.md, GEMINI.md) with independent doctrine > 20 lines

Step 3 — Deduplicate¶

For every duplicate pair found:

SOURCE_A=
SOURCE_B=
EXACT_DUPLICATE=
UNIQUE_CONTENT_A=
UNIQUE_CONTENT_B=
CANONICAL_OWNER=
DISPOSITION=

Never delete before preserving unique content.

Step 4 — Migrate Unique Value¶

For content that belongs centrally (BluCity-Docs):

UNIQUE_CONTENT=YES
TARGET=BluCity-Docs/Engineering-Standard/ or Playbooks/
EXISTING_OWNER_CHECKED=YES    # use codegraph explore or grep first
NO_DUPLICATE_CREATED=YES
MR_TO_BLUCITY_DOCS_REQUIRED=YES

For content that belongs to another project:

DO_NOT_MUTATE_TARGET (if no write authority)
CREATE_BEAD_FOR_OWNER=YES
ROUTE_VIA=gc mail or gc sling

Step 5 — Generate/Regenerate AI Projection Files¶

# CLAUDE.md — thin adapter
cat > CLAUDE.md << 'EOF'
# Claude Code

Read AGENTS.md first. AGENTS.md is the authoritative repository instruction entry point.

Use project-local docs/ for project-specific context.
Use the governed BluCity-Docs retrieval path for organizational standards.

Do not treat this file as an independent source of architecture,
policy, work state, agent identity, or operational truth.
EOF

# GEMINI.md — only if Gemini tooling is active in this repo
# Same pattern as CLAUDE.md

# llms.txt — discovery index
# Point to README, AGENTS.md, docs/, key source dirs, BluCity-Docs for shared standards
# Do not duplicate content

Step 6 — Normalize Document Metadata¶

Every governed Markdown document in the repo must have front matter with at minimum:

---
title:
type:      # architecture | decision | standard | reference | runbook | audit
owner:
updated_at:
---

Batch check:

# Find .md files missing front matter
git ls-files "*.md" | xargs grep -L "^---" | head -20

# Find .md files missing updated_at
git ls-files "*.md" | xargs grep -l "^---" | xargs grep -L "updated_at" | head -20

Step 7 — Validate¶

# Run shared CI component locally
# (once gitlab_components/jobs/validate-project-context.yml exists)
# Until then, manual checks:

echo "=== Required files ==="
for f in README.md AGENTS.md CLAUDE.md llms.txt OWNERSHIP.md; do
  test -f "$f" && echo "OK: $f" || echo "MISSING: $f"
done

echo "=== CLAUDE.md size ==="
wc -l CLAUDE.md

echo "=== Machine absolute paths ==="
git ls-files | xargs grep -l "/Users/" 2>/dev/null | grep -v ".git"

echo "=== Tracked runtime state ==="
git ls-files | grep -E "^\.gc/|^\.beads/" | head -10

# Manually craft or regenerate llms.txt to reflect current structure
# Format: purpose statement + links to key entry points
# Target ≤ 50 lines

Step 9 — Commit, MR, CI, Verify, Close¶

git add -A
git commit -m "chore(bc-XXXX): converge project context to STD-REPO-002"
git push origin feature/bc-XXXX-project-context
# Create MR → <project-target-branch> (e.g. release/v0.1.x, develop, main — check project AGENTS.md)
# Confirm CI green
# Update Bead with evidence
# WITNESS sign-off
# Close Bead

Delivery Receipt Template¶

BEAD=
RIG=
FORMULA=project-context-converge
OWNER=HARBORMASTER

FILES_INVENTORIED=
DUPLICATES_REMOVED=
UNIQUE_CONTENT_MIGRATED=
AI_FILES_REGENERATED=
METADATA_NORMALIZED=

README_PRESENT=YES
AGENTS_PRESENT=YES
CLAUDE_PRESENT=YES   CLAUDE_LINES=
LLMS_PRESENT=YES
OWNERSHIP_PRESENT=YES

MACHINE_ABSOLUTE_PATHS=0
TRACKED_RUNTIME_STATE=0
VENDOR_DOCTRINE=0

MR=
PIPELINE=
CI=GREEN
BEAD_CLOSED=YES