Terminology Migration List¶
| Field | Value |
|---|---|
| Status | Active |
| Date | 2026-09-09 |
| Authority | ADR-0027 (upstream docs governing), factory-operating-contract §16, ADR-0022 (historical Gas City foundation) |
| Scope | All Bluefly engineering documents, skill files, and runbooks |
Purpose¶
This document tracks every instance of stale terminology that must be corrected per ADR-0022 and ADR-0023. Each entry identifies the file, the violation, and the required replacement.
Two categories of stale terminology are tracked:
- Gas Town as architectural parent or native platform — Any document that describes Gas Town as Bluefly's "parent," "foundation," "control plane," or orchestration owner. Current docs.gascity.com and factory-operating-contract.md: Gas Town is upstream's predecessor project and an optional imported Pack. It is not a peer orchestration platform. ADR-0022's "peer consumer" phrasing is superseded for target architecture by ADR-0027 (2026-09-09).
- Unqualified "canonical" for repository authority — Any document that uses "canonical" without an explicit authority qualifier (Development, Source, Deployment, Recovery). Per ADR-0023, "canonical" must always be followed by the authority type.
Scan Scope¶
| Source | Scanned? | Violations Found |
|---|---|---|
outputs/ session documents |
Yes | 4 |
| Local skill files (all plugins) | Yes | 0 |
| Git repository contents (26 repos) | No | Unknown |
| GitLab wikis | No | Unknown |
| NAS Scratch/ documents | No | Unknown |
| NAS BluCity-Docs/ | No | Unknown |
Note: Scanning Git repository internals (READMEs, wikis, inline docs) requires Mac filesystem access to $ESTATE_ROOT/Applications/. The NAS Scratch/ and BluCity-Docs/ directories also require mounted filesystem access. These should be scanned in a follow-up pass.
Violations Found¶
Category 1: Gas Town as Architectural Parent¶
No violations found. All scanned documents either do not reference Gas Town, or reference it only in corrective context (ADR-0022 itself). The skill files contain no Gas Town references.
Category 2: Unqualified "canonical" — Repository Authority¶
File: workspace-convergence-classification.md¶
| Line | Current Text | Required Replacement | Severity |
|---|---|---|---|
| 11 | "NAS becomes canonical, Mac gets a symlink" | "NAS holds the Recovery Authority clone; Mac gets a symlink to NAS" | High — directly conflates NAS with canonical authority |
| 293 | "Phase 3 — NAS Canonical (read-only actions on Mac)" | "Phase 3 — Recovery Authority Alignment (read-only actions on Mac)" | High — section header using stale terminology |
File: workstream-0-repository-authority.md¶
| Line | Current Text | Required Replacement | Severity |
|---|---|---|---|
| 43 | "Canonical Remote" (column header) | "Source Authority Remote" | Medium — field correctly points to GitLab but uses unqualified "canonical" |
| 44 | "Canonical Branch" (column header) | "Source Authority Branch" | Medium — field correctly points to GitLab but uses unqualified "canonical" |
Category 3: Skill Files¶
No violations found. 17 skill files contain the word "canonical" but all uses are contextual and correct:
- "canonical commit reference" — refers to a specific git commit, not repository authority
- "canonical entry point" — refers to a code entry point, not repository authority
- "canonical SSE" — refers to Server-Sent Events protocol, not repository authority
- "canonical work path" — refers to a filesystem path convention, not repository authority
These are standard English usage of "canonical" and do not conflict with ADR-0023's terminology rules, which apply to repository authority context.
Unscanned Sources — Expected Violations¶
The following sources are likely to contain violations based on their creation timeline (before ADR-0022 and ADR-0023):
| Source | Expected Violation Type | Priority |
|---|---|---|
NAS Scratch/*.md (~40 files) |
Gas Town as parent, unqualified "canonical" | High — draft architecture docs predate ADRs |
NAS BluCity-Docs/ |
Gas Town as parent | Medium — may contain legacy architecture descriptions |
| Repository READMEs (26 repos) | Unqualified "canonical" | Medium — boilerplate may reference "canonical branch" |
| GitLab wiki pages | Both categories | Medium — wiki documentation predates ADRs |
blucity-packs repo docs |
Gas Town role references (Mayor, Polecat, Deacon) | High — Gas City/Gas Town boundary code |
Migration Procedure¶
For each violation:
- Verify the violation still exists (file may have been updated since scan).
- Apply the replacement text from the table above.
- Review surrounding context to ensure the replacement reads correctly in paragraph flow.
- Record the correction date in this document by striking through the entry.
- Commit with message format:
docs: apply ADR-000X terminology — <file>
For bulk migrations (e.g., scanning all 26 repo READMEs), use grep -rn with patterns:
# Category 1: Gas Town as parent
grep -rni "gas.town.*parent\|gas.town.*foundation\|gas.town.*control.plane\|architectural.*parent.*gas.town" .
# Category 2: Unqualified canonical in repository context
grep -rni "NAS.*canonical\|canonical.*NAS\|canonical.*remote\|canonical.*branch\|canonical.*backup\|canonical.*source" .
# Category 1 supplement: Gas Town role leakage into platform code
grep -rni "Mayor\|Polecat\|Deacon" --include="*.php" --include="*.ts" --include="*.js" --include="*.yaml" --include="*.yml" .
Completion Criteria¶
This migration list is complete when:
- All entries in the "Violations Found" section are struck through with correction dates.
- All "Unscanned Sources" have been scanned and any findings added to the violations table.
- No remaining documents use "canonical" without an authority qualifier in repository context.
- No remaining documents describe Gas Town as Bluefly's architectural parent.
References¶
- ADR-0022: Bluefly Runtime Architecture — Gas City as Foundation
- ADR-0023: Repository Authority Model
- Workstream 0: Repository Authority Convergence