Implementation Plan: Canonical Baseline and Repository Boundary
Branch: main | Date: 2026-04-10 | Spec: spec.md Input: Feature specification from kitty-specs/081-canonical-baseline-and-repository-boundary/spec.md
Summary
This mission is contract-only: it defines the canonical 3-tier terminology (project / repository / build), a corrected identity layer model (repository_uuid as stable local identity, project_uuid as optional SaaS binding), and migration sequencing guidance for follow-up implementation missions.
No code renames, help-text rewrites, config migrations, or SaaS contract changes are executed in this mission. The deliverables are the terminology contract documents, glossary definitions, and migration strategy — all of which serve as the authoritative reference for subsequent missions.
Technical Context
Language/Version: Python 3.11+ (existing spec-kitty codebase) Primary Dependencies: ruamel.yaml (YAML frontmatter for glossary), rich (console output for any validation tooling) Storage: Filesystem only (glossary YAML, markdown documents) Testing: pytest (glossary integration tests, terminology validation) Target Platform: Cross-platform (Linux, macOS, Windows 10+) Project Type: Single project (spec-kitty CLI) Performance Goals: N/A (document-only mission) Constraints: Contract-only; no code, CLI, config, or wire protocol changes Scale/Scope: Terminology contract covering 6 subsystems, 47+ call sites, 2 wire protocols, 1 SQLite schema, 1 upstream contract
Charter Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| Charter Requirement | Status | Notes |
|---|---|---|
| Python 3.11+ | Pass | Existing codebase; glossary entries are YAML/markdown |
| pytest 90%+ coverage for new code | Pass | Glossary entries and docs don't require test coverage; any validation scripts will have tests |
| mypy --strict | Pass | No new Python modules in this mission |
| CLI operations < 2 seconds | N/A | No CLI changes |
| Cross-platform | Pass | Documents are platform-independent |
| Architecture decisions in ADRs | Pass | The terminology contract itself serves as the ADR (decision + rationale + alternatives) |
| Terminology canon: Mission not Feature | Pass | Spec and plan use "mission" throughout; checked for stray "feature" usage |
Post-Phase 1 re-check: All gates still pass. No design decisions introduced charter conflicts.
Project Structure
Documentation (this mission)
kitty-specs/081-canonical-baseline-and-repository-boundary/
├── spec.md # Terminology contract specification (complete)
├── plan.md # This file
├── research.md # Phase 0: identity consumer map, migration strategies
├── data-model.md # Phase 1: before/after identity model, field mappings
├── quickstart.md # Phase 1: contributor reference for canonical terms
├── checklists/
│ └── requirements.md # Specification quality checklist (complete)
└── tasks/
└── README.md # Placeholder (tasks generated by /spec-kitty.tasks)Source Code (repository root)
This mission adds terminology contract artifacts only. No source code changes.
src/specify_cli/
└── glossary/ # Existing glossary system (mission 047+)
└── ... # New canonical term entries added here
docs/
└── reference/
└── ... # New terminology reference document added hereStructure Decision: Single-project layout. This mission adds glossary entries to the existing src/specify_cli/glossary/ system and a terminology reference to docs/reference/. No new packages or modules.
Deliverables
This mission produces five concrete deliverables:
D1: Canonical Identity Model Definition
The corrected identity model documented in data-model.md:
repository_uuid: Stable local repository identity and required namespace key (renamed from mislabeledproject_uuid)repository_label: Human-readable display name (renamed fromproject_slug)repo_slug: Optionalowner/repoGit provider reference (unchanged meaning)project_uuid: Optional SaaS-assigned collaboration binding (absent until binding)build_id: Checkout/worktree identity (unchanged)node_id: Machine fingerprint (unchanged)
Including before/after config.yaml schema, before/after wire protocol schema, namespace/dedup key migration, and field mapping tables for all renames.
D2: Terminology Contract
The canonical definitions, invariants, and rules documented in spec.md:
- 3 domain terms defined (project, repository, build)
- 9 invariants that all surfaces must satisfy
- Representative drift catalog across 6 categories (including namespace/dedup drift)
- 13 functional requirements, 3 non-functional requirements, 6 constraints
- 7 user scenarios with acceptance criteria (including body sync after migration)
D3: Glossary Definitions
Machine-readable canonical term entries for the glossary system:
| Term | Canonical Definition | Prohibited Aliases |
|---|---|---|
| project | The SaaS collaboration surface grouping one or more repositories | "project" when meaning repository or checkout |
| repository | The local Git resource (one .git directory) | "project" when meaning the Git resource |
| build | One checkout or worktree of one repository | "project" when meaning a checkout |
| repository_uuid | Stable local repository identity and required namespace key, minted once | "project_uuid" for locally minted identity |
| repository_label | Human-readable repository display name, mutable | "project_slug" |
| project_uuid | Optional SaaS-assigned collaboration identity | "project_uuid" for locally minted identity |
| repo_slug | Optional owner/repo Git provider reference (unchanged meaning) | Repurposing for display names |
| build_id | Per-checkout/worktree identity | (no prohibited aliases; already correct) |
D4: Migration Strategy and Sequencing
The implementation ordering for follow-up missions, documented in quickstart.md and research.md:
Phase 1 — CLI-only (can ship in one release): 1. Config migration: project: → repository: section, uuid → repository_uuid, slug → repository_label, repo_slug unchanged. Add deprecated-key reader. 2. Identity class rename: ProjectIdentity → RepositoryIdentity, project_slug → repository_label. repo_slug unchanged. 3. Namespace/queue key migration: project_uuid → repository_uuid in NamespaceRef, body_upload_queue SQLite schema, upstream contract, and coalescence keys. Same UUID value, new field name. 4. Path resolution rename: locate_project_root → locate_repository_root (consolidate duplicates first) 5. CLI help text, error messages, and variable names
Phase 2 — Coordinated CLI + SaaS: 6. Wire protocol dual-write: CLI sends both old and new field names for all renamed fields (project_uuid/repository_uuid AND project_slug/repository_label). repo_slug unchanged (no dual-write needed). 7. SaaS cutover: server reads new names, tolerates old 8. Wire protocol cleanup: CLI drops old field names
Key constraint: Steps 1-5 are internal to the CLI and can be released together. Steps 6-8 require coordinated releases between CLI and SaaS, with a deprecation window between each step.
D5: Contributor Terminology Reference
A quick-reference document for contributors (quickstart.md) covering:
- The three canonical terms and when to use each
- Naming conventions for variables, functions, classes, config keys, and CLI help text
- Decision tree for ambiguous cases
- Migration sequencing for follow-up work
Implementation Approach
Since this is a contract-only mission, the implementation consists of:
1. Add glossary entries to src/specify_cli/glossary/ for each canonical term (project, repository, build, repository_uuid, repository_label, project_uuid, repo_slug, build_id, node_id) 2. Add terminology reference to docs/reference/ as a human-readable version of the quickstart 3. Validate that no existing glossary entries conflict with the new definitions 4. Update any existing docs that reference the glossary to include the new terms
The spec, plan, research, data-model, and quickstart documents produced during this mission serve as the authoritative contract that follow-up missions implement against.
Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Follow-up missions deviate from the contract | Medium | High | Glossary enforcement catches non-canonical usage; review checklist references this contract |
| SaaS wire protocol migration takes longer than expected | Medium | Low (for this mission) | This mission only defines the strategy; timeline is a planning decision for follow-up missions |
| Contributors continue using old terminology in new code | High | Medium | Glossary linting flags violations; quickstart reference is discoverable in docs |
| Existing config.yaml migration breaks on edge cases | Low | Medium | Migration strategy includes backwards-compatible reader during deprecation |
Complexity Tracking
No charter violations to justify. This mission stays within charter constraints:
- Single project (spec-kitty CLI)
- No new dependencies
- No architectural pattern violations
- Terminology canon ("Mission" not "Feature") followed throughout