spec-kitty / spec-kitty/spec-kitty
Repo-wide cleanup: retire stale Priivacy-ai/spec-kitty references (post org move)
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Summary
On **2026-09-07** the canonical repository moved `Priivacy-ai/spec-kitty` → `spec-kitty/spec-kitty`. The stale org name still appears across the tree. This ticket tracks a **repo-wide cleanup** of the *live* references while explicitly **preserving** historical citations. A glossary-pack source fix (`repo_slug` example) is already in flight as **PR #4561** — this ticket covers **the rest**.
This is a **`change_mode: bulk_edit` mission**. The implementer MUST drive the occurrence-classification guardrail (`occurrence_map.yaml` / the `spec-kitty-bulk-edit-classification` skill) before touching files — do not `sed` blindly across the tree. The classification rule below is authoritative and self-contained.
## Census (tracked files, excluding `dist/**` and `.worktrees/**`)
Verified this session from repo root with:
```
git grep -n "Priivacy-ai/spec-kitty" -- . ':(exclude)dist/**' ':(exclude).worktrees/**'
```
- **2,469 occurrence lines** across **938 tracked files**.
- **~1,723 lines are PRESERVE-shape citations** — `Priivacy-ai/spec-kitty(-events)?#NNN` or `.../issues|pull|commit|commits|graphs/...` URLs. These point at real historical issue/PR/commit records under the old org and MUST NOT be rewritten.
- **~746 lines are non-citation shape** (potential UPDATE candidates), but **543 of those are under `kitty-specs/**`** (immutable mission snapshots → PRESERVE) and a further chunk is under `docs/adr/**` (→ PRESERVE).
**Files by top-level area:** `kitty-specs/` 641 · `docs/` 180 (of which `docs/adr/` 56) · `tests/` 52 · `src/` 36 · `kitty-ops/` 18 · `.kittify/` 5 · `scripts/` 3 · `packs/` 1 · `.gitignore` 1 · `CONTRIBUTORS.md` 1.
**Actual UPDATE surface — ~175 non-citation lines in edit-eligible areas** (excluding `kitty-specs/**`, `docs/adr/**`, `docs/changelog/**`). Notable clusters:
- `docs/development/contributing.md` — install/clone instructions: `git clone https://github.com/Priivacy-ai/spec-kitty.git`, `uv tool install "spec-kitty-cli @ git+https://github.com/Priivacy-ai/spec-kitty.git@main"`, `pipx install ...`, `uvx --from git+https://github.com/Priivacy-ai/spec-kitty.git@refs/pull/...` (≈8 lines). **UPDATE** — live reader guidance.
- `docs/development/how-to/pr-landing.md` — `gh pr comment --repo Priivacy-ai/spec-kitty`, `gh run list --repo ...`, `gh api "/repos/Priivacy-ai/spec-kitty/actions/..."`. **UPDATE** — live command targets.
- `docs/**` source-navigation links of the form `https://github.com/Priivacy-ai/spec-kitty/blob/main/` (many files: `docs/api/*.md`, `docs/architecture/*.md`, `docs/development/testing/*.md`, `docs/guides/*.md`). **UPDATE** — live nav links. NB: some of these links *point at* ADR files (`blob/main/docs/adr/...`); the **link** is UPDATE even though the ADR content itself is PRESERVE.
- `docs/docfx.json` — `"repo": "https://github.com/Priivacy-ai/spec-kitty"`. **UPDATE**.
- `docs/development/contributing.md:30` — `.../labels/feedback-welcome` label URL. **UPDATE**.
- Glossary/terminology `repo_slug` example (`e.g. Priivacy-ai/spec-kitty`) in `.kittify/glossaries/spec_kitty_core.yaml:444`, `packs/built-in/glossary_packs/spec-kitty-core.glossary-pack.yaml:493`, `docs/api/terminology.md:35`, `docs/context/identity-fields.md:65`. **UPDATE** — example-as-current-guidance. (Sibling of the PR #4561 fix; #4561 owns its specific `repo_slug` line, this ticket owns these.)
- `tests/**` — 30 non-citation lines; most are string literals/fixtures naming the repo. **Case-by-case**: a literal asserting the *current* repo identity is UPDATE; a literal reproducing a historical value/snapshot is PRESERVE. Classify per occurrence.
- `scripts/lint_canonical_producers.py` — mostly `#NNN` citations (PRESERVE); confirm no live target hides among them.
- `src/**` — 36 files but **overwhelmingly `Priivacy-ai/spec-kitty#NNN` citations in comments/docstrings** (e.g. `zeitgeist_bridge.py`, `lifecycle_events.py`). **PRESERVE** — verify none is a live URL/API target before finishing.
- `CONTRIBUTORS.md` — all-contributors bot table with `.../commits?author=X`, `.../issues?q=author%3AX`, `.../graphs/contributors` links. **Judgment cluster**: these are live repo-navigation links (favor UPDATE), but the file is bot-generated — prefer regenerating via the all-contributors tool over hand-editing so the next bot run doesn't revert the change. Flag in the PR.
- `.gitignore:97` — comment `# upstream as Priivacy-ai/spec-kitty#1166`. **PRESERVE** (citation).
## Classification rule (authoritative — do not re-derive)
**UPDATE** (rewrite `Priivacy-ai/spec-kitty` → `spec-kitty/spec-kitty`) — live owner/repo references:
- `gh --repo Priivacy-ai/spec-kitty` / `gh api repos/Priivacy-ai/spec-kitty/...` command targets.
- Install/clone guidance: `git clone`, `git+https://...`, `uv tool install`, `pipx install`, `uvx --from`.
- Source-navigation links `https://github.com/Priivacy-ai/spec-kitty/blob/...`, `/tree/...`, `/labels/...`, and tooling config (`docfx.json` `repo`).
- Example slugs presented as current guidance (`repo_slug` example, `e.g. Priivacy-ai/spec-kitty`).
- Source/test string literals naming the *current* repository identity.
**PRESERVE — do NOT change:**
- Historical issue/PR-link citations `Priivacy-ai/spec-kitty(-events)?#NNN` and `.../issues|pull|commit|commits/NNN` URLs — they resolve to real historical records under the old org.
- Immutable mission snapshots under `kitty-specs/**`.
- ADRs under `docs/adr/**` (content); changelog history under `docs/changelog/**`.
- Any quoted historical record. **When in doubt, preserve and flag.**
**Generated-vs-source trap:** fix canonical **sources** only — `.kittify/glossaries/*` seeds, `packs/built-in/**`, `src/**`, `docs/**`, `scripts/**`, `tests/**`. Do **not** edit generated agent copies under `.claude/`, `.agents/`, `.github/prompts/`, `.gemini/`, `.cursor/`, `.qwen/`, `.opencode/`, `.windsurf/`, `.kilocode/`, `.augment/`, `.amazonq/`, `.kiro/`, `.agent/`, nor `dist/**` or `.worktrees/**` — a `spec-kitty upgrade` regenerates those from the sources.
## Acceptance criteria
1. `git grep "Priivacy-ai/spec-kitty"` over the **UPDATE-class surfaces** returns **zero** hits (excluding PR #4561's line if it has not yet merged).
2. PRESERVE-class citations (issue/PR/commit URLs, `#NNN` refs, `kitty-specs/**`, `docs/adr/**`, changelog history) are **untouched** — verify the pre/post PRESERVE-shape line count is unchanged (~1,723).
3. No generated agent-copy directory is edited; sources only.
4. PR body carries a **short rationale line per preserved cluster** (why each was left) and calls out the `CONTRIBUTORS.md` bot-regeneration decision.
5. `change_mode: bulk_edit` guardrail satisfied (`occurrence_map.yaml` present and classification recorded).
## Out of scope
- PR #4561 (glossary-pack `repo_slug` source fix) — already in flight; do not duplicate its line.
- Any rewrite of historical issue/PR citations.
Contributor guide
Research direction
Start at the repository root with the documented git grep census, then use occurrence_map.yaml and the spec-kitty-bulk-edit-classification skill to classify occurrences. Review canonical sources under docs/, tests/, src/, .kittify/, packs/, scripts/, and CONTRIBUTORS.md while leaving generated copies and preserved historical areas untouched. Done means the UPDATE surfaces are clean, preserve counts are unchanged, the guardrail is recorded, and the PR rationale covers preserved clusters and bot regeneration.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github, python
- Domain
- documentation, testing-qa, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100