spec-kitty / spec-kitty/spec-kitty
Terminology: disambiguate overloaded 'primary' (4 senses) & 'merge' (3 senses) — glossary + prose/help, no code rename
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 22m
- Merged PRs (30d)
- 343
Description
## Summary
Two Spec Kitty terms are badly overloaded and actively cause misreads. During a plan
double-check (mission `implement-loop-commit-hardening-01KXJ1ZX`) a `kind=None → PRIMARY`
**partition** verdict was nearly implemented as "route to the primary **branch** (main)" —
which would have re-broken the WP00 refusal-to-main fix. The overload is already baked into
governance prose: ADR `docs/adr/3.x/2026-06-24-2-write-branch-resolution-primary-anchor.md`
uses "primary checkout", "PRIMARY-partition kinds", and "primary target_branch" **in one
paragraph**.
Scope here is **glossary + prose/help disambiguation only — NO code-symbol rename** (that
is a separate, deferred, bulk-edit-gated mission; see below).
## The overload (planner-priti census)
**"primary" — 4 senses, ~1,857 occurrences across 185 `src/**/*.py` (+671 docs, +170 doctrine):**
| Sense | Meaning | Canonical term | Aliases to avoid |
|-------|---------|----------------|------------------|
| A. Partition | artifact-kind partition (PRIMARY planning vs COORD status) | **PRIMARY partition** (keep) | bare "primary" without "partition/artifact" |
| B. Branch | repo main/master/default | **default branch** | "primary branch", "the primary" |
| C. Surface/checkout | canonical repo-root checkout vs lane worktree (~490 occ — the dominant cluster) | **canonical checkout / root checkout** | "primary surface", "primary checkout" |
| D. Ref/target | ref planning artifacts commit to | **target ref / commit target** | "primary target", "primary ref" |
**"merge" — 3 operations:**
| Sense | Meaning | Canonical term |
|-------|---------|----------------|
| 1 | `spec-kitty merge` — LOCAL lane consolidation into the mission branch (no push) | **lane consolidation / "consolidate"** |
| 2 | `git merge` (branch integration) | **branch integration / git merge** (explicit) |
| 3 | PR merge to origin/main (operator-only) | **publish to origin/main / operator merge** |
## Deliverables (this issue — cheap + safe)
1. **Glossary entry** for both terms and all senses (via the glossary pipeline; `glossary/contexts/`
is currently unpopulated — seed `orchestration.md` for senses A/1–3 and `execution.md` for B/C/D).
2. **Prose/help disambiguation sweep** (no symbol renames): `CLAUDE.md` (already carries
3 defensive warnings — a smell), `spec-kitty merge --help`, the doctrine merge-step prompts,
and the conflating ADR paragraph.
## MUST NOT rename (shipped/serialized contracts)
`spec-kitty merge` command name; `merge/` package + `MergeState` + `merge-state.json` keys;
strategy enum (`"merge"/"squash"/"rebase"`); `is_primary_artifact_kind` / `MissionArtifactKind`;
`target_branch` serialized field. Also fold the duplicate `resolve_primary_branch` defs
(`core/git_ops.py:270` + `cli/commands/agent/tasks_shared.py:56`) — but any *symbol* rename is out of scope here.
## Deferred sibling (do NOT bundle)
The Sense-B/C **code-symbol** rename (`primary_feature_dir_*` cluster ~490 occ →
`canonical_checkout_*`, `resolve_primary_branch` → `resolve_default_branch`) is 185 files on
resolver hot-paths (`_read_path_resolver.py` 178, `surface_resolver.py` 74) — real regression
risk against the WP00 fix, and a bulk edit requiring the `occurrence_map.yaml` 8-category
guardrail. File as a separate, gated mission only if judged worth the churn.
Surfaced by mission `implement-loop-commit-hardening-01KXJ1ZX` (a #2533 follow-up). Recorded in
that mission's tracer files.
Contributor guide
Assessment
This issue has not been assessed yet.