spec-kitty-cli 3.2.0rc4__tar.gz → 3.2.0rc5__tar.gz

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/CHANGELOG.md

@@ -17,6 +17,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [3.2.0rc5] - 2026-05-11
+
+3.2.0rc5 closes the remaining CLI-side TeamSpace migration readiness gaps found
+while rechecking the historical mission-state migration parent issue.
+
+### Changed
+
+- Documented the deterministic historical mission-state repair contract and
+  safe release sequencing used before any repository-wide repair is required.
+
+### Fixed
+
+- Block TeamSpace dry-run/import envelope synthesis when audit findings still
+  contain TeamSpace blockers, so legacy mission-state rows cannot bypass the
+  readiness audit.
+- Reject historical mission-state sync batches with legacy status fields before
+  network submission, preserving the local queue and returning remediation.
+
 ## [3.2.0rc4] - 2026-05-11
 
 3.2.0rc4 tightens the TeamSpace release candidate against the published

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0rc4
+Version: 3.2.0rc5
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -141,9 +141,19 @@ It is probably overkill for one-off edits, tiny scripts, or teams that do not us
 Install the CLI:
 
 ```bash
-pip install spec-kitty-cli
-# or
+pipx install spec-kitty-cli
+```
+
+`pipx` is the preferred installer for the CLI because it keeps Spec Kitty in its
+own virtual environment and avoids the `externally-managed-environment` errors
+common on modern Linux distributions.
+
+Other supported install methods:
+
+```bash
 uv tool install spec-kitty-cli
+# or, inside an activated virtual environment
+python -m pip install spec-kitty-cli
 ```
 
 Create or initialize a project:

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/README.md

@@ -43,9 +43,19 @@ It is probably overkill for one-off edits, tiny scripts, or teams that do not us
 Install the CLI:
 
 ```bash
-pip install spec-kitty-cli
-# or
+pipx install spec-kitty-cli
+```
+
+`pipx` is the preferred installer for the CLI because it keeps Spec Kitty in its
+own virtual environment and avoids the `externally-managed-environment` errors
+common on modern Linux distributions.
+
+Other supported install methods:
+
+```bash
 uv tool install spec-kitty-cli
+# or, inside an activated virtual environment
+python -m pip install spec-kitty-cli
 ```
 
 Create or initialize a project:

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0rc4"
+version = "3.2.0rc5"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/src/doctrine/graph.yaml

@@ -107,6 +107,9 @@ nodes:
   kind: paradigm
 - urn: paradigm:big-upfront-design
   kind: paradigm
+- urn: paradigm:brownfield-onboarding
+  kind: paradigm
+  label: Brownfield Onboarding
 - urn: paradigm:c4-incremental-detail-modeling
   kind: paradigm
   label: C4 Incremental Detail Modeling
@@ -142,6 +145,9 @@ nodes:
 - urn: procedure:issue-triage-state-machine
   kind: procedure
   label: Issue Triage State Machine
+- urn: procedure:legacy-codebase-triage
+  kind: procedure
+  label: Legacy Codebase Triage
 - urn: procedure:migrate-project-guidance-to-spec-kitty-charter
   kind: procedure
   label: Migrate Project Guidance to Spec Kitty Charter
@@ -255,6 +261,9 @@ nodes:
 - urn: tactic:entity-value-object-classification
   kind: tactic
   label: Entity vs Value Object Classification
+- urn: tactic:forensic-repository-audit
+  kind: tactic
+  label: Forensic Repository Audit
 - urn: tactic:glossary-curation-interview
   kind: tactic
   label: Glossary Curation Interview
@@ -969,6 +978,28 @@ edges:
   reason: "A single all-in-one architecture diagram conflates audiences and abstraction
     levels, producing a poster that nobody can review in a reasonable time. C4 explicitly
     separates concerns into distinct levels.\n"
+- source: paradigm:brownfield-onboarding
+  target: directive:DIRECTIVE_001
+  relation: requires
+- source: paradigm:brownfield-onboarding
+  target: directive:DIRECTIVE_003
+  relation: requires
+- source: paradigm:brownfield-onboarding
+  target: tactic:forensic-repository-audit
+  relation: suggests
+  when: Use when starting investigation of a mature codebase to surface hotspots, change coupling, and ownership signals before proposing structural change.
+- source: paradigm:brownfield-onboarding
+  target: procedure:legacy-codebase-triage
+  relation: suggests
+  when: Use to bucket findings from forensic and qualitative investigation into action categories before any non-trivial restructure.
+- source: paradigm:brownfield-onboarding
+  target: paradigm:domain-driven-design
+  relation: suggests
+  when: Apply strategic DDD (Bounded Contexts, Context Mapping) as the structural overlay for interpreting forensic findings on a mature codebase.
+- source: paradigm:brownfield-onboarding
+  target: paradigm:deep-module-design
+  relation: suggests
+  when: Use deep-module heuristics to read complexity findings -- distinguishing shallow interfaces in need of deepening from genuinely necessary depth.
 - source: paradigm:deep-module-design
   target: directive:DIRECTIVE_001
   relation: requires
@@ -1429,6 +1460,54 @@ edges:
 - source: procedure:example-mapping-workshop
   target: tactic:stakeholder-alignment
   relation: requires
+# ---------------------------------------------------------------------------
+# Forensic Repository Audit (tactic) and Legacy Codebase Triage (procedure)
+# Authored by Curator Cassidy from ratified Decision Moment outcome DM-A.
+# Tactic encodes git-only audit recipes; procedure orchestrates triage
+# bucketing on top of the tactic, with optional DDD overlay.
+# ---------------------------------------------------------------------------
+- source: procedure:legacy-codebase-triage
+  target: tactic:forensic-repository-audit
+  relation: requires
+- source: procedure:legacy-codebase-triage
+  target: tactic:strategic-domain-classification
+  relation: suggests
+- source: procedure:legacy-codebase-triage
+  target: tactic:eisenhower-prioritisation
+  relation: requires
+- source: procedure:legacy-codebase-triage
+  target: tactic:connascence-analysis
+  relation: suggests
+- source: procedure:legacy-codebase-triage
+  target: tactic:premortem-risk-identification
+  relation: suggests
+- source: procedure:legacy-codebase-triage
+  target: procedure:situational-assessment
+  relation: suggests
+- source: procedure:legacy-codebase-triage
+  target: directive:DIRECTIVE_028
+  relation: requires
+- source: procedure:legacy-codebase-triage
+  target: directive:DIRECTIVE_001
+  relation: suggests
+- source: procedure:legacy-codebase-triage
+  target: directive:DIRECTIVE_003
+  relation: suggests
+- source: tactic:forensic-repository-audit
+  target: tactic:connascence-analysis
+  relation: suggests
+- source: tactic:forensic-repository-audit
+  target: tactic:premortem-risk-identification
+  relation: suggests
+- source: tactic:forensic-repository-audit
+  target: tactic:eisenhower-prioritisation
+  relation: suggests
+- source: tactic:forensic-repository-audit
+  target: directive:DIRECTIVE_028
+  relation: requires
+- source: tactic:forensic-repository-audit
+  target: directive:DIRECTIVE_001
+  relation: suggests
 - source: directive:DIRECTIVE_035
   target: tactic:occurrence-classification-workflow
   relation: requires

spec_kitty_cli-3.2.0rc5/src/doctrine/paradigms/shipped/brownfield-onboarding.paradigm.yaml

@@ -0,0 +1,70 @@
+schema_version: "1.0"
+id: brownfield-onboarding
+name: Brownfield Onboarding
+summary: >
+  DRAFT / PROVISIONAL (2026-05-08). Approach a mature, in-use codebase as a
+  teacher rather than a problem. Legacy code is the durable record of
+  constraints, edge cases, and prior decisions the team has already paid for;
+  it deserves epistemic humility before it deserves restructuring. Brownfield
+  onboarding treats investigation as a precondition to non-trivial change:
+  forensic methods (git-history mining, hotspot and change-coupling analysis
+  via tactic:forensic-repository-audit) surface "what" and "where";
+  qualitative methods (SME interviews, decision archaeology) answer "why";
+  structural overlays (DDD strategic classification, deep-module analysis)
+  give the findings a vocabulary the team can act on. None of these methods
+  alone is sufficient. The durable artifact of the engagement is not a
+  refactor plan but a hierarchical reference bundle -- system overview,
+  subsystem maps, click paths, terminology aliases, design paradigms inferred
+  from the code -- that lowers bus-factor risk before code shape is touched.
+  Knowledge transfer is load-bearing: the DM-D principle ("document and
+  transfer first, then refactor") protects the implicit invariants that
+  restructure would otherwise erase. Respect for prior decisions and
+  willingness to change are held in tension on purpose: refusing to remove
+  what you do not yet understand is Chesterton's-fence discipline; refusing
+  to change because change is hard is preservation by inertia. The paradigm
+  walks the line between them by gating structural moves on captured
+  understanding, not on courage or on caution alone.
+
+directive_refs:
+  - DIRECTIVE_001
+  - DIRECTIVE_003
+
+opposed_by:
+  - type: paradigm
+    id: big-ball-of-mud
+    reason: >
+      A Big Ball of Mud is the failure mode brownfield onboarding is built
+      to interrupt. Where Big Ball of Mud lets coupling and concepts leak
+      without investigation, brownfield onboarding insists that the leaks
+      be mapped and named before they are either preserved or removed.
+  - type: paradigm
+    id: big-upfront-design
+    reason: >
+      Big Upfront Design assumes the right structure can be derived from
+      first principles before contact with the existing system. Brownfield
+      onboarding inverts the priority: the existing system is the primary
+      evidence, and design proposals must be grounded in what the codebase,
+      its history, and its SMEs already encode.
+# ---------------------------------------------------------------------------
+# Provisional notes -- iterate freely.
+# ---------------------------------------------------------------------------
+# - This paradigm is DRAFT as of 2026-05-08. It codifies the worldview that
+#   emerged from the 2026-05 CaaCS engagement on spec-kitty itself
+#   (architecture/audits/2026-05-spec-kitty-caacs.md and the meta-assessment
+#   companion). It is deliberately authored before issues #665 (hierarchical
+#   reference bundles as a skill) and #666 (SME-interview tactic) ship, so
+#   that the worldview anchors those artifacts rather than trailing them.
+# - [provisional: candidate for refinement] The DM-D ordering ("document and
+#   transfer first, then refactor") is stated as a principle here. Whether
+#   it should escalate to a directive is left open for the next curation
+#   pass; promotion would obligate every mission on a mature codebase to
+#   gate refactor work on a captured knowledge artifact, which is a strong
+#   claim and deserves explicit ratification.
+# - [provisional: candidate for refinement] Bus factor is treated as a
+#   first-class risk surface here. The empirical basis is the 2026-05
+#   spec-kitty CaaCS run; a broader evidence base from other brownfield
+#   engagements would strengthen or qualify the claim.
+# - Cross-links into the doctrine graph are declared in src/doctrine/graph.yaml
+#   alongside this file. The motivating tactic is forensic-repository-audit
+#   and the motivating procedure is legacy-codebase-triage; the structural
+#   overlays are domain-driven-design and deep-module-design.

spec_kitty_cli-3.2.0rc5/src/doctrine/procedures/shipped/legacy-codebase-triage.procedure.yaml

@@ -0,0 +1,188 @@
+schema_version: "1.0"
+id: legacy-codebase-triage
+name: Legacy Codebase Triage
+purpose: >
+  Convert an unfamiliar brownfield codebase into a defensible action plan
+  by gathering version-control evidence, overlaying structural and
+  complexity signals, optionally classifying domains, and bucketing the
+  resulting findings into fix-this-week, fix-this-quarter, do-not-worry,
+  and parallelisable work. The output is a triage document that anchors
+  subsequent planning conversations and ADRs; it is not a replacement
+  for deeper investigation, only a fast, evidence-backed first pass.
+entry_condition: >
+  A brownfield engagement has begun (new maintainer, acquisition,
+  takeover, or audit request) and the team has no current architectural
+  map of the codebase, OR an explicit audit has been requested by the
+  decision authority. Entry also fires when an existing project has
+  drifted enough that the previous map is no longer trustworthy.
+exit_condition: >
+  A triage report has been produced containing: the audit exclusion list,
+  hotspot table (churn, bug, complexity overlay), bus-factor table,
+  velocity series, firefighting count and ratio, optional domain
+  classification overlay, and a bucketed action plan
+  (fix-this-week / fix-this-quarter / don't-worry / parallelisable).
+  Each bucket lists concrete files or modules with a short rationale.
+  The triage report has been reviewed by at least one human stakeholder
+  and is linked from any subsequent ADR, prestudy, or work package that
+  cites it.
+steps:
+  - title: Confirm scope and exclusion list
+    description: >
+      With the requesting stakeholder, agree the audit window (default
+      one year), the repositories in scope, and the vanity-file exclusion
+      list (lockfiles, generated bundles, vendored dependencies, snapshot
+      fixtures, translation catalogs). Record the agreement in the triage
+      report header so the audit is reproducible.
+    actor: human
+    on_failure: >
+      If scope cannot be agreed (for example because ownership of related
+      repositories is unclear), record the gap as a known limitation in
+      the report and proceed with the narrower scope rather than blocking.
+  - title: Run the forensic repository audit
+    description: >
+      Execute the forensic-repository-audit tactic end-to-end against
+      the agreed scope. Produce the churn table, bus-factor table,
+      bug-hotspot table, velocity series, firefighting count, and
+      complexity overlay. Do not interpret the findings yet; this step
+      is evidence collection only. The audit report sections feed
+      directly into the triage report.
+    actor: agent
+  - title: Cross-reference hotspots with bug and complexity data
+    description: >
+      Compute the intersection sets from the audit output: files in
+      both the top churn list and the top bug-hotspot list (refactor
+      priorities); files in both the top complexity list and the top
+      churn list (load-bearing complexity); files with single-author
+      ownership above seventy percent that also appear in any hotspot
+      list (knowledge-transfer priorities). Each intersection becomes a
+      candidate for the action buckets in step 6.
+    actor: agent
+  - title: Optional — apply strategic domain classification overlay
+    description: >
+      If the project has identifiable bounded contexts (or the engagement
+      has produced a context map separately), apply the
+      strategic-domain-classification tactic to the audit findings.
+      Hotspots in core domains warrant disproportionate investment;
+      hotspots in generic subdomains may be candidates for replacement
+      with off-the-shelf alternatives rather than refactoring. Skip this
+      step entirely if no context map exists yet — do not stall the
+      triage on a discovery exercise that is out of scope here.
+    actor: agent
+    on_failure: >
+      If the overlay reveals that domains are too tangled to classify
+      meaningfully, record the observation as a follow-up
+      (event-storming or context discovery) rather than blocking the
+      triage. The triage proceeds without the overlay.
+  - title: Optional — gather security and dependency signals
+    description: >
+      Run lightweight security and dependency probes appropriate to the
+      stack (`pip-audit`, `npm audit`, `bundler-audit`, `cargo audit`,
+      or equivalent SBOM scan) and capture the headline counts of high
+      and critical findings. Attach as an appendix to the triage report.
+      This is a lightweight overlay, not a full security assessment;
+      flag any finding that meaningfully changes the action buckets.
+    actor: agent
+  - title: Bucket findings using Eisenhower prioritisation
+    description: >
+      Apply the eisenhower-prioritisation tactic to the consolidated
+      findings. Map every candidate to one of four buckets:
+      'fix this week' (high importance, high urgency: load-bearing
+      complexity that recently produced a fire);
+      'fix this quarter' (high importance, lower urgency: hotspots that
+      have not yet failed but will);
+      'don't worry' (low importance regardless of urgency: noisy but
+      stable, or out of scope);
+      'parallelisable' (independent of the critical path, candidates for
+      delegation, automation, or a separate work package).
+      Each bucket entry must cite the evidence that placed it there
+      (which table, which intersection).
+    actor: agent
+  - title: Compile the triage report and review with stakeholders
+    description: >
+      Assemble the triage report: scope and exclusion list, audit
+      tables, intersections, optional domain overlay, optional security
+      appendix, and the bucketed action plan. Review with the
+      requesting stakeholder and the team that will execute the
+      remediation work. Capture corrections, accept the report, and
+      link it from any subsequent ADR, prestudy, or work package.
+    actor: human
+    on_success: >
+      The triage is complete. The accepted report is the canonical
+      input to the planning conversation that follows. When the
+      brownfield-investigation skill (issue #665/#666) becomes
+      available, this triage feeds into it as the first-pass evidence
+      base; until then, the triage stands on its own as the
+      decision-grade output of the procedure.
+anti_patterns:
+  - name: Treating triage as a verdict
+    description: >
+      The buckets are an action plan, not a judgement on the team or
+      the codebase. Files in 'fix this week' are not bad; they are
+      load-bearing and fragile, which is information about how to
+      invest, not a moral claim.
+  - name: Skipping the exclusion list
+    description: >
+      Without the vanity-file exclusion list agreed in step 1, the
+      churn and bug-hotspot tables will be dominated by lockfiles and
+      generated bundles. Any triage that omits the exclusion list is
+      invalid and must be re-run.
+  - name: Blocking on the optional steps
+    description: >
+      The domain-classification overlay (step 4) and the security
+      overlay (step 5) are explicitly optional. Treat them as
+      enrichments, not gates. A triage with a clean audit and a
+      sound bucket plan is decision-grade even without either overlay.
+  - name: Substituting triage for deeper investigation
+    description: >
+      This procedure produces a first-pass evidence base. It is not
+      the brownfield-investigation skill (issue #665/#666), is not a
+      default gate on any mission, and does not replace event storming,
+      context discovery, threat modelling, or full architecture review
+      where those are warranted. Cite this triage as input to those
+      activities; do not let it stand in for them.
+  - name: Over-reading squash-merged history
+    description: >
+      Repositories that squash every PR collapse multi-commit work into
+      single events; the audit recipes will undercount activity. The
+      triage must note the merge strategy and corroborate with PR
+      metadata or issue-tracker data before drawing strong conclusions.
+references:
+  - type: tactic
+    id: forensic-repository-audit
+    reason: The forensic-repository-audit tactic is the evidence-gathering core of this procedure; step 2 invokes it directly.
+  - type: tactic
+    id: strategic-domain-classification
+    reason: Optional overlay invoked in step 4 when the project has identifiable bounded contexts.
+  - type: tactic
+    id: eisenhower-prioritisation
+    reason: Step 6 buckets the consolidated findings into the urgency-and-importance matrix that drives the action plan.
+  - type: tactic
+    id: connascence-analysis
+    reason: After triage identifies refactor priorities, connascence analysis classifies the coupling that drives the hotspot status.
+  - type: tactic
+    id: premortem-risk-identification
+    reason: Before scheduling any large remediation work that the triage flags, run a premortem on the proposed plan.
+  - type: procedure
+    id: situational-assessment
+    reason: When the triage uncovers questions larger than its scope, escalate into a full situational assessment to establish shared context before design.
+  - type: directive
+    id: DIRECTIVE_028
+    reason: Governs the local tooling (git, cloc, language-specific complexity probes) the procedure relies on.
+  - type: directive
+    id: DIRECTIVE_001
+    reason: Triage findings that surface load-bearing complexity or single-author critical modules feed architectural-integrity decisions.
+  - type: directive
+    id: DIRECTIVE_003
+    reason: The accepted triage report is itself a documented decision input and is linked from any subsequent ADR or prestudy.
+notes: |
+  Out of scope.
+
+  This procedure is *not* the brownfield-investigation skill described in
+  issues #665 and #666. When that skill ships, this triage feeds into it
+  as a first-pass evidence base; until then, the triage stands on its
+  own as a decision-grade output. This procedure is also *not* a default
+  gate on any mission — it fires only when the entry conditions match —
+  and it does not encode the full body of Adam Tornhill's behavioural
+  code analysis methodology, which the underlying audit tactic
+  acknowledges as theoretical underpinning rather than cited recipe
+  source.

{spec_kitty_cli-3.2.0rc4 → spec_kitty_cli-3.2.0rc5}/src/doctrine/skills/spec-kitty-setup-doctor/SKILL.md

@@ -63,7 +63,8 @@ spec-kitty verify-setup
 If `spec-kitty` is not installed:
 
 ```bash
-pip install spec-kitty-cli
+pipx install spec-kitty-cli
+pipx ensurepath
 spec-kitty --version
 ```