pactkit 2.10.4__tar.gz → 2.10.6__tar.gz

{pactkit-2.10.4 → pactkit-2.10.6}/.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.6}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.10.6] - 2026-04-22
+
+### Fixed
+- **L3 SHOULD semantics** (STORY-slim-104) — Signal Strength Convention L3 Recommended changed from "Violation = warning, non-blocking" to "Default required — skip only with stated reason" (RFC 2119). Added clarification bullet that SHOULD is not optional. Prevents AI from systematically deferring SHOULD tasks.
+
+## [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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.10.4
+Version: 2.10.6
 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
@@ -41,13 +41,13 @@ Requires-Dist: tree-sitter>=0.25; extra == 'visualize'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/pactkit/pactkit/main/docs/assets/logo.png" alt="PactKit" width="480" />
+  <img src="https://raw.githubusercontent.com/pactkit/pactkit-src/main/docs/assets/logo.png" alt="PactKit" width="480" />
 </p>
 
 <p align="center">
   <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/v/pactkit" alt="PyPI version" /></a>
   <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/pyversions/pactkit" alt="Python" /></a>
-  <a href="https://github.com/pactkit/pactkit/actions/workflows/ci.yml"><img src="https://github.com/pactkit/pactkit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/pactkit/pactkit-src/actions"><img src="https://github.com/pactkit/pactkit-src/actions/workflows/pactkit.yml/badge.svg" alt="CI" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
 </p>
 

{pactkit-2.10.4 → pactkit-2.10.6}/README.md

@@ -1,11 +1,11 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/pactkit/pactkit/main/docs/assets/logo.png" alt="PactKit" width="480" />
+  <img src="https://raw.githubusercontent.com/pactkit/pactkit-src/main/docs/assets/logo.png" alt="PactKit" width="480" />
 </p>
 
 <p align="center">
   <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/v/pactkit" alt="PyPI version" /></a>
   <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/pyversions/pactkit" alt="Python" /></a>
-  <a href="https://github.com/pactkit/pactkit/actions/workflows/ci.yml"><img src="https://github.com/pactkit/pactkit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/pactkit/pactkit-src/actions"><img src="https://github.com/pactkit/pactkit-src/actions/workflows/pactkit.yml/badge.svg" alt="CI" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
 </p>
 

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

@@ -48,3 +48,5 @@
 | 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 |
+| 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 |

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

@@ -2,9 +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 |
 | 2026-03-24 | regression_workflow_impact hook/store matching uses node.id substring of changed file path, not reverse — e.g. 'useAuth' in 'src/hooks/useAuth.ts' | visualize.py:regression_workflow_impact |
 | 2026-03-25 | export_focus_graphs() in visualize.py uses forward_reach() (not reverse_reach()) because entry points (command/service/page) are graph roots that invoke downward — forward BFS shows their dependency tree | src/pactkit/skills/visualize.py:export_focus_graphs |
@@ -53,3 +50,6 @@
 | 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 |
+| 2026-04-22 | When the same bug pattern recurs 3+ times across specs (BUG-010, BUG-slim-089, STORY-033, STORY-slim-054), promote the fix from spec-level to a standing rule in 08-architecture-principles.md — ad-hoc spec fixes do not prevent recurrence | ~/.claude/rules/08-architecture-principles.md:§9 |
+| 2026-04-22 | Signal Strength L3 SHOULD semantics in rules.py:RULES_MODULES['core'] must use RFC 2119 wording — 'warning, non-blocking' caused AI to systematically defer all SHOULD tasks during Act | src/pactkit/prompts/rules.py:51 |

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

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 3762+ tests must pass before any commit to `main`.
+1. All 3790+ 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.6}/docs/product/archive/archive_202604.md

@@ -212,3 +212,32 @@
 - [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
+
+### [STORY-slim-103] Rules anti-pattern: Merge-over-Replace + Parameterize-over-Hardcode
+> Spec: docs/specs/STORY-slim-103.md
+
+- [x] Add §9 to 08-architecture-principles
+- [x] Expand No Magic Values in 12-solution-design
+- [x] Verify no new rules files
+
+### [STORY-slim-104] Fix L3 SHOULD semantics in Signal Strength Convention
+> Spec: docs/specs/STORY-slim-104.md
+
+- [x] Change L3 Semantics text in rules.py
+- [x] Add SHOULD clarification note
+- [x] Add test for L3 content

pactkit-2.10.6/docs/product/context.md

@@ -0,0 +1,28 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-04-22T19:00:19+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 0 | In Progress: 0 | Done: 0 stories
+
+## Current Stories
+None
+
+## Recent Completions
+None
+
+## Active Branches
+develop
+* main
+
+## Key Decisions
+- 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.
+- When the same bug pattern recurs 3+ times across specs (BUG-010, BUG-slim-089, STORY-033, STORY-slim-054), promote the fix from spec-level to a standing rule in 08-architecture-principles.md — ad-hoc spec fixes do not prevent recurrence
+- Signal Strength L3 SHOULD semantics in rules.py:RULES_MODULES['core'] must use RFC 2119 wording — 'warning, non-blocking' caused AI to systematically defer all SHOULD tasks during Act
+
+## Next Recommended Action
+`/project-design`
+
+## Agent Continuation
+No active work session.

pactkit-2.10.6/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.6/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.6/docs/specs/STORY-slim-103.md

@@ -0,0 +1,100 @@
+# STORY-slim-103: Rules anti-pattern: add Merge-over-Replace and Parameterize-over-Hardcode to existing rules
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-103 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.6 |
+
+## Background
+
+LLM has two systematic design biases that current rules fail to counter:
+
+1. **Full-replace bias**: LLM defaults to full file overwrites (Write tool) instead of incremental edits (Edit tool / merge). This has caused 5+ bugs in PactKit history (BUG-010, BUG-slim-089, STORY-033, STORY-slim-054) where user config was silently destroyed.
+
+2. **Hardcode bias**: LLM defaults to writing concrete values inline instead of extracting configurable parameters. The existing `No Magic Values` constraint in `12-solution-design.md` only covers code implementation — it misses rules, Specs, configs, and playbooks.
+
+Both biases are LLM cognitive shortcuts (lower token cost, simpler reasoning). Without standing rules, each occurrence is discovered as a bug post-facto and fixed as a one-off spec, never promoted to a reusable principle.
+
+### PDCA Coverage Map (Rules → Commands)
+
+| Rules File | Referenced By |
+|---|---|
+| `08-architecture-principles.md` | Plan, Act, Design, Sprint |
+| `12-solution-design.md` | Plan (Phase 1), Act (Phase 1) |
+
+Both target files are loaded into context during architecture decisions (08) and implementation design (12) — the exact phases where these biases manifest.
+
+## Requirements
+
+### R1: Merge over Replace Principle in 08-architecture-principles.md (MUST)
+
+Add §9 to `~/.claude/rules/08-architecture-principles.md` establishing "Merge over Replace" as a standing architecture principle:
+- Signal level: L3 SHOULD (non-blocking, but violation = data loss risk)
+- MUST include a Decision Matrix: when full-replace is safe vs. when incremental merge is required
+- MUST define the criteria: "If the target file may contain user-modified content or sections managed by other tools, use incremental merge"
+- SHOULD reference the 5 historical bugs as evidence (without bloating the rule)
+
+### R2: Expand No Magic Values to All Artifacts in 12-solution-design.md (MUST)
+
+Expand the existing `No Magic Values` constraint in `12-solution-design.md` Implementation Constraints:
+- Broaden scope from "code implementation" to "all artifacts" (rules, Specs, configs, playbooks, prompts)
+- Add a **Flexibility Litmus Test**: "If changing this value requires grep + multi-file edits, it should be parameterized"
+- Add explicit examples for non-code artifacts (rule thresholds, path patterns, tool names)
+
+### R3: No New Rules Files (MUST NOT)
+
+MUST NOT create any new rules file. All changes MUST be edits to existing `08-architecture-principles.md` and `12-solution-design.md` — violation breaks the user's constraint of keeping the rules count stable.
+
+## Acceptance Criteria
+
+### AC1: Merge over Replace principle exists in 08 (R1)
+
+- **Given** `08-architecture-principles.md` is loaded by Plan/Act/Design/Sprint
+- **When** LLM reads the file during any PDCA command
+- **Then** §9 "Merge over Replace" is present with a Decision Matrix distinguishing safe-to-replace vs. must-merge scenarios
+
+### AC2: No Magic Values scope covers all artifacts (R2)
+
+- **Given** `12-solution-design.md` is loaded by Plan/Act
+- **When** LLM enters Implementation Constraints during Solution Design Protocol
+- **Then** "No Magic Values" explicitly states it applies to rules, Specs, configs, playbooks — not just code
+- **Then** a Flexibility Litmus Test is present ("If changing this value requires grep + multi-file edits → parameterize")
+
+### AC3: No new rules files created (R3)
+
+- **Given** the current rules directory has N files
+- **When** this story is implemented
+- **Then** the rules directory still has exactly N files (no additions, no deletions)
+
+## Target Call Chain
+
+N/A — this story modifies rules files (prompt-level artifacts), not source code. No call chain.
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `~/.claude/rules/08-architecture-principles.md` | Add §9 Merge over Replace with Decision Matrix after §8 | None | Low |
+| 2 | `~/.claude/rules/12-solution-design.md` | Expand No Magic Values scope + add Flexibility Litmus Test | None | Low |
+| 3 | Verify | Confirm no new files in `~/.claude/rules/`, spec-lint passes | Step 1-2 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 Input Validation | N/A | Docs/rules only |
+| SEC-2 Auth/AuthZ | N/A | Docs/rules only |
+| SEC-3 Data Exposure | N/A | Docs/rules only |
+| SEC-4 Injection | N/A | Docs/rules only |
+| SEC-5 Cryptography | N/A | Docs/rules only |
+| SEC-6 Dependency | N/A | Docs/rules only |
+| SEC-7 Logging | N/A | Docs/rules only |
+| SEC-8 Config | N/A | Docs/rules only |
+
+## Out of Scope
+
+- Modifying PDCA skill files (skill.md) — the `@` references already load 08 and 12, no skill changes needed
+- Adding enforcement tooling (linter, hook) — this story adds principles only; automation is a separate story
+- Modifying PactKit source code — rules files are prompt-level artifacts

pactkit-2.10.6/docs/specs/STORY-slim-104.md

@@ -0,0 +1,77 @@
+# STORY-slim-104: Fix L3 SHOULD semantics in Signal Strength Convention
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-104 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.6 |
+
+## Background
+
+Signal Strength Convention 表中 L3 Recommended 的 Semantics 列当前定义为 "Violation = warning, non-blocking"。这个措辞让 AI 将 SHOULD 误解为 "可以不做"，导致 Spec 中标记为 SHOULD 的 task 被系统性 defer。
+
+RFC 2119 对 SHOULD 的正确定义是："除非有充分理由，否则必须做"（there may exist valid reasons to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course）。当前措辞与 RFC 2119 语义不符。
+
+**实际影响**: 观测到 AI 在 Act 阶段完成所有 MUST task 后，将全部 SHOULD task defer，给出的理由包括 "context 太长"、"改动大下次做" 等。这些 SHOULD task 最终全部被补回，总共只花 15 分钟。
+
+**Canonical source**: `src/pactkit/prompts/rules.py:51`，`RULES_MODULES["core"]` 模板字符串。
+
+## Requirements
+
+### R1: Fix L3 Semantics to RFC 2119 (MUST)
+
+Change L3 Recommended row Semantics from `Violation = warning, non-blocking` to `Default required — skip only with stated reason`. This aligns with RFC 2119 SHOULD semantics: the default is to do it, and skipping requires an explicit, stated justification.
+
+### R2: Add SHOULD clarification note (SHOULD)
+
+Add a bullet point after the table clarifying that `SHOULD` (L3) is NOT optional — it means "do unless you have a stated reason not to". This prevents the table's compact format from being misread.
+
+## Acceptance Criteria
+
+### AC1: L3 Semantics text updated (R1)
+
+- **Given** `src/pactkit/prompts/rules.py` contains the Signal Strength Convention table
+- **When** I read the L3 Recommended row
+- **Then** the Semantics column reads `Default required — skip only with stated reason` (not `Violation = warning, non-blocking`)
+
+### AC2: Clarification note present (R2)
+
+- **Given** `src/pactkit/prompts/rules.py` contains the Signal Strength Convention section
+- **When** I read the bullet points after the table
+- **Then** there is a bullet clarifying that SHOULD (L3) is not optional — skipping requires a stated reason
+
+### AC3: Deployed rules file reflects change (R1, R2)
+
+- **Given** pactkit has been deployed via `pactkit init` or `pactkit deploy`
+- **When** I read `~/.claude/rules/01-core-protocol.md`
+- **Then** the L3 row and clarification note match the source in `rules.py`
+
+## Target Call Chain
+
+`RULES_MODULES["core"]` (rules.py:4) → `deployer._deploy_rules()` → writes `01-core-protocol.md`
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/rules.py` | Change L3 Semantics text + add SHOULD clarification bullet | None | Low |
+| 2 | `tests/` | Add/update test verifying L3 row content | Step 1 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | Prompt text change only, no code execution logic |
+| SEC-2 | N/A | No user input handling |
+| SEC-3 | N/A | No database patterns |
+| SEC-4 | N/A | No frontend files |
+| SEC-5 | N/A | No auth/session logic |
+| SEC-6 | N/A | No API/route files |
+| SEC-7 | N/A | No error handling logic |
+| SEC-8 | N/A | No dependency changes |
+
+## Out of Scope
+
+- STORY-slim-086 Spec 中的中文版表格（历史记录，不影响部署）
+- 其他 rules 文件中对 SHOULD 的使用（语义由此表定义，使用方不需改）

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

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

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

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