Documentation / Implementation Boundary Contract¶
Applies to every agent, regardless of role (Registrar, source worker, Mayor, IaC agent, Drupal agent, A2A agent, release/merge agent, security agent, research agent). Extends the composition-vs-implementation principle in constitution.md (
Bluefly owns composition. Bluefly does not own implementation.) with directory-level and session-receipt specificity for the BluCity-Docs repository itself.
0. Master rule¶
blueflyio/blu/blucity-docs is organizational memory:
canonical standards, authority, ontology, catalogs, architecture, governance,
decisions, evidence, reference, product documentation, operating knowledge.
It is not an application, infrastructure, script, runtime, CI-component, Terraform, service, or tool-implementation repository.
1. Two sources of truth¶
- BluCity-Docs answers: what exists, what it's called, what it means, who
owns it, which authority decides, which product/capability/repository it
maps to, what evidence supports the claim, what lifecycle state it's in,
what's canonical vs. superseded vs.
NOT_ESTABLISHED. - The owning project repository answers: how it's implemented, built, tested, packaged, deployed; what APIs/config schema it exposes.
Documentation of organizational truth → BluCity-Docs. Implementation of capability → the owning project. Never reversed.
2. Decision test before creating or touching anything¶
- Is there already a canonical file for this concept? (search first)
- Is this documentation or implementation?
- Which ontology object is this — Product, Repository, Capability, Platform, Authority, Tool, Technology, Pack, Deployment, or Document? (never conflate two of these because names look similar)
- Who owns the concept? Who owns the implementation?
- Can I update an existing canonical document instead of creating one?
- Am I in the correct role for this change?
If describes ownership/authority/capability/product/platform/deployment identity/architectural boundary/standard/governance/decision/evidence/ lifecycle/terminology/canonical relationship → BluCity-Docs may own it. If it executes code, shell, Terraform, Ansible, Docker/K8s manifests, CI component logic, migrations, or runtime automation → it belongs with an implementation owner, not here.
3. Documentation must not duplicate implementation¶
Forbidden: application source under Products/, scripts under assets/ or
Engineering-Standard/tools/, vendored CI components, copied service
repos/modules, deployment manifests treated as authoritative, "temporary"
executable source left in place.
Documents point outward (owner repo + evidence SHA/MR/link), never copy implementation inward.
4. Existing violations are debt, not precedent¶
Finding executable material already in BluCity-Docs does not make BluCity-Docs
its owner. Classify DOCS_IMPLEMENTATION_BOUNDARY_VIOLATION, then: delete if
duplicate, migrate if a real owner exists, delete if obsolete, or mark
OWNER_NOT_ESTABLISHED. Never create a new repository just to evacuate
something from docs. (Precedent: assets/scripts/check-ucd-law-unique.mjs —
implementation owner gitlab_components; BluCity-Docs owns the UCD law only.
Vendored copy removed 2026-08-28; enforcement via pinned
gitlab_components/ucd-law-unique include in .gitlab-ci.yml, not a local
script copy.)
5. Single purpose per repository, single authority per concept¶
Every repository has one primary purpose; don't turn docs into tooling, iac into application config, or product docs into source trees. Every concept has exactly one canonical authority — see the canonical-owner map in platform-ownership-matrix.md and document-ownership-matrix.md. Do not create competing tables (a second product table, a second capability inventory, a second tool registry, etc.) — extend the canonical one.
6. Directory contract (BluCity-Docs)¶
| Path | Owns | Never |
|---|---|---|
README.md, AGENTS.md, CLAUDE.md, GEMINI.md |
entry point, agent operating instructions | product implementation |
.gitlab-ci.yml |
minimal docs-repo validation/publishing | shared CI implementation authority |
Engineering-Standard/architecture,authority,catalog,decision-records,glossary,governance,indexes,operating-model,platform,reference,rules,standards |
see README.md directory contract | — |
Engineering-Standard/infrastructure |
documentation about infrastructure | Terraform/deploy implementation |
Engineering-Standard/integration |
integration contracts/architecture | adapter implementation |
Engineering-Standard/Runtime |
runtime documentation/observed topology | runtime source |
Engineering-Standard/tools |
documentation about tools | tool source/scripts |
Engineering-Standard/verification |
evidence definitions/verification records | test implementation |
Evidence/ |
observations, receipts, attestations | executable tooling |
Playbooks/ |
human-readable procedures/checklists | shell scripts, automation engines |
Products/ |
product descriptions, architecture, offerings | React/Go/Drupal/Terraform source |
projections/ |
generated/derived documentation views | executable runtime projections |
Research/ |
investigations, source comparisons | production implementation |
assets/ |
diagrams, images, static docs assets | scripts, CI helpers, runtime code |
_ARCHIVE/ |
historical documentation retained for traceability | old source code kept instead of deleted (git history is the archive for source) |
.agents/, .claude/, .cursor/ |
repo-specific agent instructions | hidden script dirs, alternative doctrine stores |
New top-level directories require a distinct documentation purpose. No
misc/, scripts/, tools-code/, infra-code/, temp/, old/, stuff/,
generated-code/.
7. Generated documents¶
Generated Markdown (e.g. catalog/*.md) may remain in BluCity-Docs; the
generator that produces it should not permanently live there long-term —
existing generators inside this repo (authority/generate-catalogs.py) are
migration debt, not a pattern to extend. Never hand-edit a generated output;
edit the authority source (Portfolio-Registry.yaml), regenerate, verify
SECOND_RUN_DIFF=0.
8. Secret boundary¶
May document secret names, semantic references, authority, rotation policy.
Must never contain secret values, PATs, private keys, resolved .env, or
copied 1Password values. 1Password owns secret lifecycle.
9. Separation of duties¶
| Role | Owns |
|---|---|
| Registrar | canonical organizational truth: Portfolio-Registry.yaml, catalogs, ontology, naming, lifecycle/evidence classification, cross-catalog consistency, reproducibility. Does not implement source fixes, mutate IaC, deploy, or fix runtime/merge issues outside its own branch. |
| Source worker | implementation |
| Mayor | work/runtime authority, production observation |
| IaC agent | cloud/host desired state |
| agent-docker owner | runtime/container desired state |
| gitlab_components owner | reusable CI |
| 1Password | secrets |
| Project owner | project source/config/API |
| Merge owner | merge/release convergence |
| Auditor | evidence and verification |
No agent absorbs another role merely because it discovered a problem there — route it with evidence instead.
10. Evidence-to-registry loop¶
upstream specification -> Bluefly authority/registry -> catalog/standard/decision
-> implementation owner -> build/artifact -> deployment -> runtime observation
-> evidence -> Registrar reconciliation
Runtime evidence may correct the catalog; catalog authority may expose implementation drift. No layer steals another layer's ownership. When a worker's session changes a durable organizational fact, it routes evidence (subject, object type, old/new fact, evidence, source repo/SHA/MR) to the Registrar rather than hand-editing the registry itself, unless that session explicitly holds Registrar authority.
11. Session discipline¶
Every meaningful session should leave the estate more aligned than it found
it: correct what's in your authority, route what isn't. Don't invent work to
avoid stopping, and don't turn every implementation task into a documentation
essay — if implementation changed but organizational truth didn't, no master
doc change is required. Use VERIFIED / OBSERVED / PROPOSED /
NOT_ESTABLISHED / CONFLICTING_EVIDENCE for claims; never upgrade
uncertainty by inference. Before creating a document, search for an existing
canonical owner first — prefer update/merge/delete over a new file.
12. Success condition¶
Fewer, better canonical documents. One owner per concept, one implementation owner per capability. Zero duplicate sources. Zero implementation in master docs. Zero competing authority tables. Traceable evidence. BluCity-Docs becomes the place to learn what Bluefly is, what exists, who owns it, where its source lives, how the parts relate, and what's canonical vs. retired vs. not established — without ever needing to contain the implementation itself.