<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/known-friction-points/">
  <id>https://docs.spec-kitty.ai/development/reference/known-friction-points/</id>
  <title>Known Current Friction Points</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/known-friction-points/"/>
  <summary>A time-stamped, fast-drifting list of current repo and tooling friction points a maintainer or agent hits mid-mission; re-verify against the tracker before trusting specifics.</summary>
  <content type="html">&lt;span id=&quot;known-current-friction-points&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;This page is deliberately time-sensitive and drifts fast.&lt;/strong&gt; It captures
repo and tooling friction that a maintainer — or an agent acting in a
maintainer capacity — is likely to hit while running a mission &lt;em&gt;today&lt;/em&gt;. It is
&lt;strong&gt;not&lt;/strong&gt; durable doctrine: specific issue numbers, version gates, and toggles
change as the codebase moves. Always re-verify against the authoritative
sources before trusting a specific number:
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/AGENTS.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt;&lt;/a&gt; (its “Test-run baseline-red gotcha” note),
&lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;ADR 2026-07-17-1&lt;/a&gt;,
and the issue tracker.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Snapshot date: 2026-09-30 · Spec Kitty 4.0.0rc5 (4.x cycle).&lt;/strong&gt; Proof that this list drifts:
&lt;code dir=&quot;auto&quot;&gt;#2772&lt;/code&gt; was a known-red P0 when this note was first drafted and has since been
closed — so the “known reds” below are already a different set than a month ago.&lt;/p&gt;
&lt;h2 id=&quot;the-friction-points&quot;&gt;The friction points&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; may be legitimately RED.&lt;/strong&gt; Honest P0 reproductions are left red on
purpose (in the nightly &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; lane, not per PR) (&lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;ADR 2026-07-17-1&lt;/a&gt;);
currently open examples: &lt;strong&gt;#2736&lt;/strong&gt;, &lt;strong&gt;#1834&lt;/strong&gt;. Before “fixing” any red,
&lt;strong&gt;attribute&lt;/strong&gt; it — reproduce on &lt;code dir=&quot;auto&quot;&gt;upstream/main&lt;/code&gt; / the merge-base. Never
green-wash a &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro&lt;/code&gt; red (it shows only in the nightly); that
erases a deliberate release-blocker signal.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CI-environment false reds that pass locally:&lt;/strong&gt; auth
(&lt;code dir=&quot;auto&quot;&gt;logged_out_on_connected_teamspace&lt;/code&gt;) and the pre-review gate opt-out
(&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SKIP_PRE_REVIEW_GATE&lt;/code&gt;, its own name since #3980). Config, not
your diff.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stale-install false reds.&lt;/strong&gt; Commands that shell out to &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; (e.g.
the &lt;code dir=&quot;auto&quot;&gt;merge-driver-*&lt;/code&gt; commands) only reflect your working tree after
&lt;code dir=&quot;auto&quot;&gt;pip install -e .&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;uv pip install -e .&lt;/code&gt;. Re-install after every rebase.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stale-venv false reds.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;ModuleNotFoundError&lt;/code&gt; for a package that is
declared and pinned usually means the &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; was never (re)synced, not a
real regression — run &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt; before recording it
as pre-existing (#648).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;pr:deferred&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;pr:skip-ci&lt;/code&gt; labels skip some PR workflows — a green
check can mean “not run,” not “passed.”&lt;/strong&gt; Jobs in &lt;code dir=&quot;auto&quot;&gt;ci-windows.yml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;check-spec-kitty-events-alignment.yml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;release-readiness.yml&lt;/code&gt; carry
&lt;code dir=&quot;auto&quot;&gt;if: !contains(github.event.pull_request.labels.*.name, &apos;pr:deferred&apos;) &amp;#x26;&amp;#x26; !contains(..., &apos;pr:skip-ci&apos;)&lt;/code&gt;, so either label makes them report
&lt;strong&gt;skipped&lt;/strong&gt;. Check the PR’s label list before treating an all-green run as
evidence the change is safe; a skipped job is unverified, not clean. (See
&lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;pr-landing.md §4&lt;/a&gt; for how to classify checks once
you &lt;em&gt;do&lt;/em&gt; have real CI results to read.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter lint&lt;/code&gt;’s project-DRG input (&lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/graph.yaml&lt;/code&gt;) looks
gitignored but is deliberately un-ignored — confirm it is tracked and
in-diff before filing a lint finding.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; blanket-excludes
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/**&lt;/code&gt; and then re-includes specific subpaths, including
&lt;code dir=&quot;auto&quot;&gt;!.kittify/charter-packs/graph.yaml&lt;/code&gt;; the file is meant to be committed and is
the first candidate &lt;code dir=&quot;auto&quot;&gt;charter_runtime/lint/_drg.py::_load_project_drg&lt;/code&gt;
reads (ahead of &lt;code dir=&quot;auto&quot;&gt;merged_drg.json&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;drg.json&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;compiled_drg.json&lt;/code&gt;). If
it is stale or absent, &lt;code dir=&quot;auto&quot;&gt;charter lint&lt;/code&gt; silently falls back to
&lt;code dir=&quot;auto&quot;&gt;GraphState.BUILT_IN_ONLY&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;MISSING&lt;/code&gt;) and skips project-layer checks
rather than failing loudly — so before treating a &lt;code dir=&quot;auto&quot;&gt;charter lint&lt;/code&gt; result as
authoritative, confirm &lt;code dir=&quot;auto&quot;&gt;git ls-files .kittify/charter-packs/graph.yaml&lt;/code&gt; shows it
tracked and that &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter synthesize&lt;/code&gt; regenerated it in your
diff if doctrine artifacts changed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;In a lane or clone, a bare &lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;pytest&lt;/code&gt; imports the PRIMARY &lt;code dir=&quot;auto&quot;&gt;src&lt;/code&gt;, not
your lane.&lt;/strong&gt; Always &lt;code dir=&quot;auto&quot;&gt;uv run &amp;#x3C;cmd&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CI gates that pass locally, then fail on the PR:&lt;/strong&gt; the terminology guard
(&lt;code dir=&quot;auto&quot;&gt;terminology&lt;/code&gt; job in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt;), the architectural battery (the
always-on &lt;code dir=&quot;auto&quot;&gt;architectural-fast&lt;/code&gt; gate, which runs on every PR shape, plus the two
code-scoped &lt;code dir=&quot;auto&quot;&gt;architectural-heavy&lt;/code&gt; legs), the canonical-producer lint (CP001 fires on a
hand-rolled event dict with &lt;code dir=&quot;auto&quot;&gt;event_type&lt;/code&gt;+&lt;code dir=&quot;auto&quot;&gt;payload&lt;/code&gt; keys — build via
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.lifecycle.*&lt;/code&gt; instead; &lt;code dir=&quot;auto&quot;&gt;scripts/lint_canonical_producers.py&lt;/code&gt;),
and the docs tests (&lt;code dir=&quot;auto&quot;&gt;tests-docs&lt;/code&gt; job). On the &lt;strong&gt;rebased&lt;/strong&gt; tip, run the
terminology guard, the specific &lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; gate files your diff
implicates (not the whole directory — see
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/internal/directives/no-full-heavy-suites-in-mission.directive.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;NO_FULL_HEAVY_SUITES_IN_MISSION&lt;/code&gt;&lt;/a&gt;;
CI owns the full sweep), and
&lt;code dir=&quot;auto&quot;&gt;PYTHONPATH=. python scripts/docs/check_docs_freshness.py --ci&lt;/code&gt; for docs
changes before declaring a branch green (&lt;code dir=&quot;auto&quot;&gt;errors=0&lt;/code&gt;; its inventory and
index staleness findings are warnings, because the &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt; bot
regenerates those files after merge).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An always-on &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_lifted_*.py&lt;/code&gt; gate re-runs an
out-of-matrix suite’s invariant, so share its code; never copy it.&lt;/strong&gt; The
source suite runs only in the nightly and its lift runs on every PR, so a
copied predicate keeps enforcing the old rule after the source changes (#5008).
Since #5015, the code a lift shares with its source lives once, in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_lifted_&amp;#x3C;topic&gt;.py&lt;/code&gt;, and both files import it. That
includes tests: &lt;code dir=&quot;auto&quot;&gt;from &amp;#x3C;home&gt; import test_x as test_x&lt;/code&gt; is what makes pytest
collect &lt;code dir=&quot;auto&quot;&gt;test_x&lt;/code&gt; in the importing module. The lift’s docstring names its
source in double backticks.
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_lift_single_source.py&lt;/code&gt; fails a lift that defines a
name its source, or a shared home, also defines, or that copies a body under
a new name. The name rule is strict: even an unrelated &lt;code dir=&quot;auto&quot;&gt;REPO_ROOT&lt;/code&gt; defined in
one file and bound in the other fails, so import it or rename it. To change a
lifted invariant, edit the shared home: both suites pick it up.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;git stash&lt;/code&gt; in lane worktrees&lt;/strong&gt; — the stash stack is shared across
worktrees, so a &lt;code dir=&quot;auto&quot;&gt;pop&lt;/code&gt; can steal a sibling lane’s work-in-progress.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; can hang on fan-out.&lt;/strong&gt; Background it and set
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_MOMENT_HANDLERS=1&lt;/code&gt; (the old &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SYNC_MINIMAL_IMPORT=1&lt;/code&gt;
spelling is still accepted as an alias, #3980).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;After &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;, verify the issue-matrix / coordination state.&lt;/strong&gt; 3.2.6
made the PRIMARY scaffolder idempotent; the coordination/consolidate reset
path is not fully verified (not re-checked on 4.0.0rc5).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Docs scripts need &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH=.&lt;/code&gt;&lt;/strong&gt;, and &lt;code dir=&quot;auto&quot;&gt;build_cli_reference.py&lt;/code&gt; defaults to
the &lt;em&gt;wrong&lt;/em&gt; output path — pass &lt;code dir=&quot;auto&quot;&gt;--output docs/api/cli-commands.md --agent-output docs/api/agent-subcommands.md&lt;/code&gt; explicitly.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shared-package boundary:&lt;/strong&gt; anchor new runtime code in
&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/_internal_runtime/&lt;/code&gt;; the old &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/next/&lt;/code&gt; shim
was removed on 2026-07-03 — do not recreate it. Consume events / tracker
only via &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.*&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;spec_kitty_tracker.*&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A pyenv-scoped editable &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; install shadows a pipx install.&lt;/strong&gt;
Recurring: if &lt;code dir=&quot;auto&quot;&gt;pyenv&lt;/code&gt; manages the Python version active for this repo (a
&lt;code dir=&quot;auto&quot;&gt;.python-version&lt;/code&gt; file, or &lt;code dir=&quot;auto&quot;&gt;pyenv local&lt;/code&gt;), an editable install left in that
pyenv version’s &lt;code dir=&quot;auto&quot;&gt;site-packages&lt;/code&gt; (an &lt;code dir=&quot;auto&quot;&gt;_editable_impl_spec_kitty_cli.pth&lt;/code&gt;
pointing at some checkout’s &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;) resolves ahead of the pipx-installed
&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;, so the CLI silently runs a stale or unrelated
checkout instead of the one you are working in. Detect:
&lt;code dir=&quot;auto&quot;&gt;which spec-kitty&lt;/code&gt; (a pyenv shim, e.g. &lt;code dir=&quot;auto&quot;&gt;~/.pyenv/shims/spec-kitty&lt;/code&gt;, instead
of the pipx shim under &lt;code dir=&quot;auto&quot;&gt;~/.local/bin&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;pip show -f spec-kitty-cli&lt;/code&gt; in
that pyenv version (an &lt;code dir=&quot;auto&quot;&gt;_editable_impl_spec_kitty_cli.pth&lt;/code&gt; / editable
project-location entry is the tell). Fix: &lt;code dir=&quot;auto&quot;&gt;pip uninstall spec-kitty-cli&lt;/code&gt;
inside the offending pyenv version, or reorder &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; so the pipx shim wins.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.git/hooks/pre-commit&lt;/code&gt; pins an absolute python interpreter.&lt;/strong&gt; The
commit-guard hook Spec Kitty installs (&lt;code dir=&quot;auto&quot;&gt;specify_cli.policy.hook_installer&lt;/code&gt;)
captures &lt;code dir=&quot;auto&quot;&gt;sys.executable&lt;/code&gt; at install time and hardcodes it into the hook —
by design, so the hook does not depend on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; (FR-009). Moving,
deleting, or rebuilding &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; at a different location (a renamed clone, a
relocated checkout) leaves the pinned path dangling. Symptom: &lt;code dir=&quot;auto&quot;&gt;git commit&lt;/code&gt;
fails because the hook’s interpreter path no longer exists. Fix: if only
the interpreter binary vanished, &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt; rebuilds
&lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; at the same path and the existing hook resolves again; if the
checkout itself moved, delete &lt;code dir=&quot;auto&quot;&gt;.git/hooks/pre-commit&lt;/code&gt; and re-run
&lt;code dir=&quot;auto&quot;&gt;spec-kitty implement &amp;#x3C;any-WP&gt;&lt;/code&gt; (or any path that allocates a lane
worktree) to regenerate the hook pinned to the new location.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;maintaining-this-page&quot;&gt;Maintaining this page&lt;/h2&gt;
&lt;p&gt;When you hit a new mid-mission friction point — or when one above stops being
true (a known-red P0 closes, a toggle is retired, a version gate passes) —
update this page and bump the snapshot date &lt;strong&gt;and the version tag&lt;/strong&gt; in the same
change. Keep entries
short and actionable; deep rationale belongs in the linked runbooks, not here.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;Landing contributor PRs&lt;/a&gt; — the maintainer landing runbook.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/getting-started/onboarding-run/&quot;&gt;Onboarding run&lt;/a&gt; — the mission-run priming prompt that
points here.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/testing/testing-flakiness/&quot;&gt;Test-flakiness handling policy&lt;/a&gt; — the never-retry-to-green rule.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/red-main-and-release-readiness/&quot;&gt;Red main and release readiness&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
