pactkit 2.10.4__tar.gz → 2.10.5__tar.gz

{pactkit-2.10.4 → pactkit-2.10.5}/.github/workflows/pactkit.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          pip install -e ".[visualize]"
           pip install pytest ruff
           pactkit init
 

{pactkit-2.10.4 → pactkit-2.10.5}/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.10.5] - 2026-04-21
+
+### Added
+- **Solution Design Protocol** (STORY-slim-101) — New rule `12-solution-design.md` requires capability delta assessment before implementation. Prevents framework blindness, project blindness, and hardcoded coupling. Includes Implementation Constraints (no magic values, OCP, SRP, dependency direction). Integrated into Plan Phase 1 and Act Phase 1.
+
+### Changed
+- **Global version tracking** (STORY-slim-102) — Version tracking moved from project-level `pactkit.yaml` to global `~/.claude/.pactkit-version` marker. Eliminates cross-project desync when PactKit is upgraded. `auto_merge_config_file()` now removes stale `version` field from existing project yamls.
+
 ## [2.10.4] - 2026-04-20
 
 ### Added

{pactkit-2.10.4 → pactkit-2.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.10.4
+Version: 2.10.5
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit-public

{pactkit-2.10.4 → pactkit-2.10.5}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -48,3 +48,4 @@
 | 2026-03-24 | Standalone scripts (visualize.py) need try/except ImportError guards for yaml.safe_load when reading pactkit.yaml — they cannot import from pactkit library | visualize.py:_load_scan_excludes |
 | 2026-03-24 | Inline data in standalone scripts must have canonical-source comments pointing to the library module (e.g. _STACK_MARKERS → cleaners.py, _LANG_FILE_EXT → workflows.py) per Architecture Principle 1 | visualize.py:_STACK_MARKERS |
 | 2026-03-24 | Worktree isolation diverges from working-tree: verify visualize.py _scan_files() signature is preserved across stories to avoid breaking callers | visualize.py:_scan_files |
+| 2026-03-24 | Extracting _detect_stack() from _detect_file_ext() enables both file discovery and test mapping to share stack detection — DRY refactoring | visualize.py:_detect_stack |

{pactkit-2.10.4 → pactkit-2.10.5}/docs/architecture/governance/lessons.md

@@ -2,7 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 2026-03-24 | Extracting _detect_stack() from _detect_file_ext() enables both file discovery and test mapping to share stack detection — DRY refactoring | visualize.py:_detect_stack |
 | 2026-03-24 | Standalone skill scripts using exec() require all imports in _SHARED_HEADER; new stdlib imports (dataclass) must be added to skills/__init__.py _SHARED_HEADER, not just the standalone header section | skills/__init__.py:_SHARED_HEADER |
 | 2026-03-24 | detect_topology() must delegate to _TOPOLOGY_PARSERS parser.detect() first, not _TOPOLOGY_MARKERS alone — parsers and markers can diverge silently causing empty graphs | visualize.py:detect_topology |
 | 2026-03-24 | _scan_hooks() only accepts files with 'use' prefix in hook dirs (src/hooks/, composables/) to prevent utility files from becoming hook nodes | visualize.py:_scan_hooks |
@@ -53,3 +52,4 @@
 | 2026-04-20 | Plugin deployer (_deploy_commands in deployer.py:952-954) uses _rewrite_skills_prefix instead of _render_prompt, keeping raw placeholders like {BOARD_CMD} — not a deploy drift bug but by-design template behavior | src/pactkit/generators/deployer.py:_deploy_commands |
 | 2026-04-20 | pactkit clean rglob patterns must exclude protected parent dirs (node_modules, .git) — recursive pattern matching deletes dependency internals | cleaners.py:_inside_protected |
 | 2026-04-20 | Hotfix playbook lacked data-driven impact awareness — AI-only 'no side effects' checks miss high-fan-in functions. Adding lightweight .mmd graph reads makes the advisory concrete without blocking the fast-fix path. | workflows.py:HOTFIX_PROMPT |
+| 2026-04-21 | Version tracking in pactkit.yaml caused cross-project desync — moved to ~/.claude/.pactkit-version as single source of truth for deploy state. config.py get_default_config() no longer includes version field. | STORY-slim-102 |

{pactkit-2.10.4 → pactkit-2.10.5}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 3762+ tests must pass before any commit to `main`.
+1. All 3787+ tests must pass before any commit to `main`.
 2. Specs (`docs/specs/`) are the source of truth — code conforms to specs, not the reverse.
 3. CLI entry point is `pactkit` via `src/pactkit/cli.py:main`.
 4. No runtime dependencies beyond `pyyaml`.

{pactkit-2.10.4 → pactkit-2.10.5}/docs/product/archive/archive_202604.md

@@ -212,3 +212,18 @@
 - [x] Add Phase 0.5 Impact Check to HOTFIX_PROMPT
 - [x] Add tests for new phase
 - [x] Deploy verification
+
+### [STORY-slim-101] Solution Design Protocol Rule
+> Spec: docs/specs/STORY-slim-101.md
+
+- [x] Add RULE_12_SOLUTION_DESIGN to rules.py
+- [x] Add to VALID_RULES in config.py
+- [x] Add unit test
+
+### [STORY-slim-102] Move version tracking to global deploy marker
+> Spec: docs/specs/STORY-slim-102.md
+
+- [x] Write .pactkit-version in deployer
+- [x] Update --if-needed to read global marker
+- [x] Remove version from project yaml
+- [x] Update tests

{pactkit-2.10.4 → pactkit-2.10.5}/docs/product/context.md

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-04-20T17:32:07+08:00 by pactkit context
+> Last updated: 2026-04-21T17:13:02+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 0 | In Progress: 0 | Done: 0 stories
@@ -15,11 +15,11 @@ develop
 * main
 
 ## Key Decisions
-- Dual-anchor pattern: declare principle in RULES_MODULES['core'] (01-core-protocol.md), detail in dedicated module (11-pdca-nudge.md). Prevents attention dilution when rules/ has 10+ files — Core Protocol acts as behavioral constitution anchor.
 - Version comparison guards must use semantic (tuple) comparison, not string equality — string != treats 2.10.1 != 2.5.0 without direction, giving wrong upgrade advice
 - Plugin deployer (_deploy_commands in deployer.py:952-954) uses _rewrite_skills_prefix instead of _render_prompt, keeping raw placeholders like {BOARD_CMD} — not a deploy drift bug but by-design template behavior
 - pactkit clean rglob patterns must exclude protected parent dirs (node_modules, .git) — recursive pattern matching deletes dependency internals
 - Hotfix playbook lacked data-driven impact awareness — AI-only 'no side effects' checks miss high-fan-in functions. Adding lightweight .mmd graph reads makes the advisory concrete without blocking the fast-fix path.
+- Version tracking in pactkit.yaml caused cross-project desync — moved to ~/.claude/.pactkit-version as single source of truth for deploy state. config.py get_default_config() no longer includes version field.
 
 ## Next Recommended Action
 `/project-design`

pactkit-2.10.5/docs/specs/STORY-slim-101.md

@@ -0,0 +1,155 @@
+# STORY-slim-101: Solution Design Protocol Rule
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-101 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.5 |
+
+## Background
+
+LLM tends to implement features using "quick and dirty" approaches that work but have poor maintainability, robustness, and extensibility. Three core anti-patterns observed:
+
+1. **Framework Blindness**: LLM doesn't know what native capabilities the framework provides, so it reinvents the wheel (e.g., writing custom context storage when LangGraph has memory store)
+2. **Project Blindness**: LLM doesn't check what the project has already encapsulated, so it bypasses existing abstractions (e.g., instantiating AzureChatOpenAI directly instead of using `get_precise_llm()`)
+3. **Hardcoded Dependencies**: LLM couples directly to framework internals instead of using project abstraction layers
+
+Root cause: No protocol requires LLM to evaluate capability delta (framework native + project existing) before implementation. Information exists (Context7 for framework docs, grep for project code, call chain for dependencies) but LLM is not required to use it.
+
+## Requirements
+
+### R1: Rule File Creation (MUST)
+
+Create `~/.claude/rules/12-solution-design.md` containing the Solution Design Protocol that defines capability assessment before implementation.
+
+### R2: Framework Capability Query (MUST)
+
+The protocol MUST define a prioritized query path for framework native capabilities:
+1. Context7 MCP (if available) — real-time, authoritative
+2. WebFetch official docs (if network available) — real-time, requires parsing
+3. AI training data (fallback) — must declare framework version to avoid outdated APIs
+
+### R3: Project Capability Discovery (MUST)
+
+The protocol MUST define methods to discover project existing capabilities:
+- Grep import statements to find framework usage
+- Grep factory function patterns (`get_*`, `build_*`, `create_*`) to find encapsulated capabilities
+- Pattern match wiring layer files (`wiring.py`, `deps.py`, `container.*`, `di.*`, `providers.*`)
+- Use call chain visualization for dependency analysis
+
+### R4: Delta Assessment Matrix (MUST)
+
+The protocol MUST define a decision matrix based on capability delta:
+- Framework has & project not used → prefer enabling framework capability
+- Framework has & project encapsulated → reuse project abstraction, do not bypass
+- Neither has → only then implement new
+
+### R5: Decision Constraints (MUST)
+
+The protocol MUST enforce:
+- MUST NOT bypass project abstraction layer to use framework directly
+- SHOULD prefer framework native over custom implementation
+- MUST state reasoning if not using available framework capability
+
+### R6: Output Format (SHOULD)
+
+The protocol SHOULD define output format for:
+- Plan phase: Technical Design section in Spec
+- Act phase: Brief assessment output before implementation
+
+### R7: Stack-Agnostic Design (MUST)
+
+The protocol MUST be stack-agnostic, supporting dependency files for:
+- Python: `pyproject.toml`, `requirements.txt`
+- Node: `package.json`
+- Go: `go.mod`
+- Java: `pom.xml`, `build.gradle`
+- Rust: `Cargo.toml`
+
+### R8: Playbook Integration (MUST)
+
+The rule MUST be integrated into PDCA playbooks:
+- `project-plan.md`: Add `@~/.claude/rules/12-solution-design.md` import and reference protocol in Phase 1
+- `project-act.md`: Add `@~/.claude/rules/12-solution-design.md` import and reference protocol in Phase 1
+
+## Acceptance Criteria
+
+### AC1: Rule File Exists (R1)
+
+- **Given** PactKit rules directory at `~/.claude/rules/`
+- **When** `pactkit init` or `pactkit deploy` is run
+- **Then** `12-solution-design.md` is deployed with full protocol content
+
+### AC2: Framework Query Fallback Chain (R2)
+
+- **Given** A requirement involving a framework (e.g., LangGraph)
+- **When** Solution Design Protocol is executed
+- **Then** Framework capabilities are queried via Context7 → WebFetch → Training Data fallback chain
+
+### AC3: Project Capability Discovery (R3)
+
+- **Given** A project with `pyproject.toml` listing `langgraph>=0.4`
+- **When** Solution Design Protocol Step 3 is executed
+- **Then** Protocol identifies: (a) framework imports in src/, (b) factory functions like `get_*`/`build_*`, (c) wiring layer files
+
+### AC4: Delta Assessment Decision (R4)
+
+- **Given** Framework has memory store capability, project has checkpointer but not memory
+- **When** Requirement is "add cross-session context"
+- **Then** Protocol recommends "enable framework capability" not "implement custom"
+
+### AC5: Abstraction Bypass Prevention (R5)
+
+- **Given** Project has `get_precise_llm()` in wiring.py
+- **When** LLM attempts to directly instantiate AzureChatOpenAI
+- **Then** Protocol constraint blocks this and directs to use existing encapsulation
+
+### AC6: Output Format in Spec (R6)
+
+- **Given** Plan phase executes Solution Design Protocol
+- **When** Capability assessment is complete
+- **Then** Output is written to `## Technical Design` section with: capability table, reuse points, new implementation list
+
+### AC7: Multi-Stack Support (R7)
+
+- **Given** A Node.js project with `package.json`
+- **When** Solution Design Protocol Step 1 is executed
+- **Then** Protocol correctly reads dependencies from `package.json` not `pyproject.toml`
+
+### AC8: Playbook References Protocol (R8)
+
+- **Given** User runs `/project-plan` or `/project-act`
+- **When** Phase 1 executes
+- **Then** Solution Design Protocol is triggered for requirements involving frameworks
+
+## Target Call Chain
+
+Not applicable — this is a new rule file, not modifying existing code.
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/rules.py` | Add `RULE_12_SOLUTION_DESIGN` constant with full protocol content | None | Low |
+| 2 | `src/pactkit/config.py` | Add `12-solution-design` to `VALID_RULES` | Step 1 | Low |
+| 3 | `src/pactkit/prompts/commands.py` | Update `COMMAND_PLAN` and `COMMAND_ACT` to import rule and reference protocol in Phase 1 | Step 1 | Medium |
+| 4 | `tests/unit/test_rules.py` | Add test for new rule deployment | Steps 1-3 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | No secrets — rule file contains only protocol text |
+| SEC-2 | N/A | No user input handling — rule file is static content |
+| SEC-3 | N/A | No database operations |
+| SEC-4 | N/A | No frontend code |
+| SEC-5 | N/A | No authentication logic |
+| SEC-6 | N/A | No API endpoints |
+| SEC-7 | N/A | No error handling code |
+| SEC-8 | N/A | No dependency changes |
+
+## Out of Scope
+
+- Auto-generation of capability index files — protocol uses dynamic discovery
+- Framework-specific capability lists — protocol relies on Context7/WebFetch for real-time data

pactkit-2.10.5/docs/specs/STORY-slim-102.md

@@ -0,0 +1,135 @@
+# STORY-slim-102: Move version tracking from project yaml to global deploy marker
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-102 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.5 |
+
+## Background
+
+The `version` field in project-level `pactkit.yaml` tracks which PactKit version last deployed. When PactKit is upgraded via `pipx upgrade pactkit`, running `pactkit update` in one project updates that project's yaml, but all other projects remain stale. This causes `pactkit update --if-needed` (triggered every session by Core Protocol) to report mismatch and run a full redeploy in every other project — even though the global deployment directory (`~/.claude/`) is already up to date.
+
+Root cause: version tracking is in the wrong place. Project yaml's role is **configuration** (which agents/skills/rules to deploy). Deployment **state** (which version last deployed) should live in the global deployment directory alongside the deployed files.
+
+### Current Flow (broken cross-project)
+```
+pipx upgrade pactkit → __version__ = 2.10.5
+cd projectA → pactkit update → projectA yaml = 2.10.5, ~/.claude/ = 2.10.5 ✓
+cd projectB → pactkit update --if-needed → projectB yaml = 2.10.1 ≠ 2.10.5 → full redeploy (unnecessary)
+```
+
+### Target Flow
+```
+pipx upgrade pactkit → __version__ = 2.10.5
+cd projectA → pactkit update → ~/.claude/.pactkit-version = 2.10.5 ✓
+cd projectB → pactkit update --if-needed → reads ~/.claude/.pactkit-version = 2.10.5 → skip ✓
+```
+
+## Requirements
+
+### R1: Global Version Marker (MUST)
+
+Classic deployer MUST write `~/.claude/.pactkit-version` containing `__version__` after successful deployment. This is the single source of truth for "which version is currently deployed globally."
+
+### R2: Update --if-needed Reads Global Marker (MUST)
+
+`pactkit update --if-needed` MUST read `~/.claude/.pactkit-version` (not project yaml) to decide whether to skip. If the marker matches `__version__`, skip. If missing or mismatched, proceed to deploy.
+
+### R3: Remove version from Project YAML (MUST)
+
+- `get_default_config()` MUST NOT include a `version` key
+- `auto_merge_config_file()` MUST NOT sync version — and MUST remove existing `version` field if present (cleanup migration)
+- `_rewrite_yaml()` MUST NOT write a version line
+- `load_config()` MUST NOT break if `version` key is absent
+
+### R4: Guard Version Check Uses Global Marker (MUST)
+
+`check_version_mismatch()` in `guards.py` MUST read the global marker instead of project yaml version.
+
+## Acceptance Criteria
+
+### AC1: Global Marker Written on Deploy (R1)
+
+- **Given** `~/.claude/.pactkit-version` does not exist or has old version
+- **When** `pactkit update` runs successfully
+- **Then** `~/.claude/.pactkit-version` contains `__version__` (e.g., `2.10.5`)
+
+### AC2: Skip When Global Marker Matches (R2)
+
+- **Given** `~/.claude/.pactkit-version` contains `2.10.5` and `__version__ == 2.10.5`
+- **When** `pactkit update --if-needed` is run from any project directory
+- **Then** Output is `"PactKit 2.10.5 up-to-date — skipping redeploy"` and exit code 0
+
+### AC3: Deploy When Global Marker Mismatches (R2)
+
+- **Given** `~/.claude/.pactkit-version` contains `2.10.1` and `__version__ == 2.10.5`
+- **When** `pactkit update --if-needed` is run
+- **Then** Full deploy executes and marker is updated to `2.10.5`
+
+### AC4: Default Config Has No Version (R3)
+
+- **Given** `get_default_config()` is called
+- **When** Result is inspected
+- **Then** No `version` key exists in the returned dict
+
+### AC5: Auto-merge Removes Stale Version (R3)
+
+- **Given** A project yaml with `version: "2.10.1"` and stale components
+- **When** `auto_merge_config_file()` is called
+- **Then** New components are added AND `version` field is removed from the yaml file
+
+### AC6: Guard Uses Global Marker (R4)
+
+- **Given** `~/.claude/.pactkit-version` matches `__version__`
+- **When** `pactkit guard` is run from a project with stale yaml version
+- **Then** No version mismatch warning is printed
+
+### AC7: Old YAML With Version Still Loads (R3)
+
+- **Given** A project yaml containing `version: "2.10.1"` (legacy field not yet cleaned)
+- **When** `load_config()` is called
+- **Then** Config loads without error
+
+## Target Call Chain
+
+```
+pactkit update --if-needed
+  → cli.py: read ~/.claude/.pactkit-version (R2)
+  → if match: skip, exit 0
+  → if mismatch: deploy() → _deploy_classic()
+    → deployer.py: write ~/.claude/.pactkit-version (R1)
+
+pactkit guard
+  → guards.py: check_version_mismatch()
+    → read ~/.claude/.pactkit-version (R4)
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/generators/deployer.py` | Write `.pactkit-version` at end of `_deploy_classic()` | None | Low |
+| 2 | `src/pactkit/cli.py` | Change `--if-needed` to read global marker | Step 1 | Low |
+| 3 | `src/pactkit/guards.py` | Change `check_version_mismatch()` to read global marker | Step 1 | Low |
+| 4 | `src/pactkit/config.py` | Remove `version` from `get_default_config()`, `auto_merge`, `_rewrite_yaml` | None | Medium |
+| 5 | `tests/unit/` | Update version-related tests | Steps 1-4 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | No secrets |
+| SEC-2 | N/A | No user input handling |
+| SEC-3 | N/A | No database operations |
+| SEC-4 | N/A | No frontend code |
+| SEC-5 | N/A | No authentication logic |
+| SEC-6 | N/A | No API endpoints |
+| SEC-7 | N/A | No error handling code |
+| SEC-8 | N/A | No dependency changes |
+
+## Out of Scope
+
+- Adapter packages (codex, copilot, opencode) — they already have their own `.pactkit-version` mechanism
+- Plugin/marketplace manifests — `version` in `plugin.json` and `marketplace.json` is package metadata, not deployment state

{pactkit-2.10.4 → pactkit-2.10.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pactkit"
-version = "2.10.4"
+version = "2.10.5"
 description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
 readme = "README.md"
 license = "MIT"

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/__init__.py

@@ -1,3 +1,3 @@
 """PactKit - Spec-driven agentic DevOps toolkit."""
 
-__version__ = "2.10.4"
+__version__ = "2.10.5"

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/cli.py

@@ -350,20 +350,16 @@ def main():
     args = parser.parse_args()
 
     if args.command in ("init", "update", "upgrade"):
-        # STORY-slim-023: --if-needed skips deploy when versions match
+        # STORY-slim-102: --if-needed checks global deploy marker, not project yaml
         if args.command == "update" and getattr(args, "if_needed", False):
             from pathlib import Path
 
-            from pactkit.config import load_config
-
-            yaml_path = Path.cwd() / ".claude" / "pactkit.yaml"
-            if yaml_path.exists():
-                cfg = load_config(yaml_path)
-                yaml_version = cfg.get("version", "")
-                if yaml_version == __version__:
+            marker = Path.home() / ".claude" / ".pactkit-version"
+            if marker.exists():
+                deployed_version = marker.read_text().strip()
+                if deployed_version == __version__:
                     print(f"PactKit {__version__} up-to-date — skipping redeploy")
                     raise SystemExit(0)
-                print(f"PactKit version mismatch: {yaml_version} → {__version__}. Updating...")
             else:
                 print("No pactkit.yaml found. Running first-time setup...")
 

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/config.py

@@ -9,8 +9,6 @@ from typing import Union
 
 import yaml
 
-from pactkit import __version__
-
 # ---------------------------------------------------------------------------
 # Valid identifiers (the registry of all known components)
 # ---------------------------------------------------------------------------
@@ -88,6 +86,7 @@ VALID_RULES = frozenset(
         "08-architecture-principles",
         "09-sectional-write",
         "11-pdca-nudge",
+        "12-solution-design",
     }
 )
 
@@ -154,7 +153,6 @@ class PactKitConfig:
 def get_default_config() -> dict:
     """Return the default config with all components enabled."""
     return {
-        "version": __version__,
         "stack": "auto",
         "root": ".",
         "developer": "",
@@ -511,10 +509,10 @@ def auto_merge_config_file(path: Union[Path, str]) -> list[str]:
             user_data[key] = defaults[key]
             added.append(f"section: {key}")
 
-    # BUG-026: Sync version to installed __version__
-    if user_data.get("version") != __version__:
-        user_data["version"] = __version__
-        added.append(f"version: {__version__}")
+    # STORY-slim-102: Remove stale version field from project yaml
+    if "version" in user_data:
+        del user_data["version"]
+        added.append("removed: version (now tracked globally)")
 
     if added:
         _rewrite_yaml(path, user_data)
@@ -582,7 +580,6 @@ def _rewrite_yaml(path: Path, data: dict) -> None:
         "# Edit this file to customize which components are deployed.",
         "# Remove items from a list to disable them. Default: all enabled.",
         "",
-        f'version: "{__version__}"',
         _render_stack_line(data.get('stack', 'auto')),
         f"root: {data.get('root', '.')}",
         f'developer: "{data.get("developer", "")}"',
@@ -996,7 +993,6 @@ def generate_default_yaml(stack=None) -> str:
         "# All agents, commands, skills, and rules are deployed by default.",
         "# To exclude specific items, add an exclude list (e.g., exclude_skills: [pactkit-draw]).",
         "",
-        f'version: "{cfg["version"]}"',
         _render_stack_line(cfg['stack']),
         f"root: {cfg['root']}",
         f'developer: "{cfg["developer"]}"',

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/generators/deployer.py

@@ -397,6 +397,10 @@ def _deploy_classic(config=None, target=None):
         f"({n_skills} embedded + {n_commands} commands), "
         f"{n_rules}/{total_rules} Rules"
     )
+
+    # STORY-slim-102: Write global version marker
+    atomic_write(claude_root / ".pactkit-version", f"{__version__}\n")
+
     _print_mcp_recommendations()
 
 

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/guards.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from pactkit import __version__
-from pactkit.config import find_pactkit_yaml, load_config
+from pactkit.config import find_pactkit_yaml
 
 
 def check_init_markers(project_root: Path) -> tuple[bool, list[str]]:
@@ -76,33 +76,37 @@ def _parse_version(v: str) -> tuple[int, ...]:
         return ()
 
 
+def _get_global_version_marker() -> Path:
+    """Return path to the global deploy version marker."""
+    return Path.home() / ".claude" / ".pactkit-version"
+
+
 def check_version_mismatch(project_root: Path) -> str | None:
-    """Check if pactkit.yaml version differs from installed __version__.
+    """Check if global deploy marker version differs from installed __version__.
 
     Returns:
-        Warning message if mismatch, None if versions match or yaml not found.
+        Warning message if mismatch, None if versions match or marker not found.
     """
-    yaml_path = find_pactkit_yaml(project_root)
-    if yaml_path is None:
+    marker = _get_global_version_marker()
+    if not marker.exists():
         return None
 
-    cfg = load_config(yaml_path)
-    yaml_version = cfg.get("version", "")
-    if not yaml_version or yaml_version == __version__:
+    deployed_version = marker.read_text().strip()
+    if not deployed_version or deployed_version == __version__:
         return None
 
-    yaml_v = _parse_version(yaml_version)
+    deployed_v = _parse_version(deployed_version)
     installed_v = _parse_version(__version__)
 
-    if not yaml_v or not installed_v:
-        return f"Version mismatch: pactkit.yaml {yaml_version} vs installed {__version__}"
+    if not deployed_v or not installed_v:
+        return f"Version mismatch: deployed {deployed_version} vs installed {__version__}"
 
-    if yaml_v > installed_v:
+    if deployed_v > installed_v:
         return (
-            f"Version mismatch: pactkit.yaml {yaml_version} > installed {__version__}\n"
+            f"Version mismatch: deployed {deployed_version} > installed {__version__}\n"
             f"         Run `pipx upgrade pactkit` to update the CLI"
         )
     return (
-        f"Version mismatch: pactkit.yaml {yaml_version} < installed {__version__}\n"
+        f"Version mismatch: deployed {deployed_version} < installed {__version__}\n"
         f"         Run `pactkit update` to sync"
     )

{pactkit-2.10.4 → pactkit-2.10.5}/src/pactkit/prompts/commands.py

@@ -79,6 +79,9 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 3.  **Topology-Aware Trace (Conditional)** — if `detect_topology(root)` includes `api_call` or `agent`:
     - For **api_call**: Run `api_convention_summary(root)` and include path prefixes, fetch function names, and total call count in the Archaeologist Report. This prevents API path convention bugs in downstream implementation.
     - For **agent**: Note orchestration edges from AgentParser (LangGraph/YAML/MCP) in the report so downstream changes respect agent flow.
+4.  **Solution Design Protocol (Conditional)** — if the requirement involves frameworks already used by the project:
+    - Execute the **Solution Design Protocol** from `12-solution-design.md` to evaluate capability delta (framework native + project existing vs. needs implementation).
+    - Include the Capability Assessment output in Phase 2 Spec writing.
 
 ## 🎬 Phase 2: Design & Impact
 1.  **Diff**: Compare User Request vs Current Reality (from Phase 1).
@@ -175,6 +178,9 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 3.  **Topology-Aware Trace (Conditional)** — if `detect_topology(root)` includes `api_call` or `agent`:
     - For **api_call**: Run `api_convention_summary(root)` to check API path prefixes and fetch function conventions. Use these conventions when writing new API calls to maintain consistency.
     - For **agent**: Check AgentParser output for orchestration edges so new code doesn't break agent flow.
+4.  **Solution Design Protocol (Conditional)** — if the implementation involves frameworks already used by the project:
+    - Execute the **Solution Design Protocol** from `12-solution-design.md` to evaluate capability delta before writing code.
+    - Output brief capability assessment before proceeding to Phase 2.
 
 ## 🎬 Phase 2: Test Scaffolding (TDD)
 1.  **Constraint**: NEVER write source code in this phase — doing so breaks TDD causality: tests must exist before the code they verify.