pactkit 2.10.2__tar.gz → 2.10.4__tar.gz

{pactkit-2.10.2 → pactkit-2.10.4}/.opencode/pactkit.yaml

@@ -2,7 +2,7 @@
 # Edit this file to customize which components are deployed.
 # Remove items from a list to disable them. Default: all enabled.
 
-version: "2.10.2"
+version: "2.10.4"
 stack: python
 root: .
 developer: "slim"

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

@@ -4,6 +4,16 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.10.4] - 2026-04-20
+
+### Added
+- **Hotfix Impact Check** (STORY-slim-100) — `/project-hotfix` now includes Phase 0.5 that reads existing `.mmd` call graph files before fixing. Warns when target function has 3+ callers. Advisory (L3), non-blocking, gracefully skips when no graphs exist.
+
+## [2.10.3] - 2026-04-20
+
+### Fixed
+- **Protected parent dirs in `pactkit clean`** — `rglob("dist")` was matching `node_modules/*/dist`, destroying npm dependency internals. Added `_inside_protected()` guard for `node_modules/` and `.git/`; explicit path patterns (e.g., `node_modules/.cache`) now use direct matching instead of rglob.
+
 ## [2.10.2] - 2026-04-20
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.10.2
+Version: 2.10.4
 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.2 → pactkit-2.10.4}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -46,3 +46,5 @@
 | 2026-03-24 | Plan Phase 3.2a scaffold-first: replaced AI freeform Write with {SCAFFOLD_CMD} create_spec + Read + Edit in src/pactkit/prompts/commands.py. Removed 3 inline format examples (~240 chars). Pre-existing tests (test_bug034, test_story055_commands, test_story_slim019) needed updates for new checkpoint wording. | src/pactkit/prompts/commands.py:Phase3.2a |
 | 2026-03-24 | spec_linter.py _check_acceptance_criteria: per-subsection GWT check must use raw_text (with code blocks) not stripped text, because specs legitimately wrap Gherkin in fenced blocks | spec_linter.py:_check_acceptance_criteria |
 | 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 |

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

@@ -2,8 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 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 |
 | 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 |
@@ -53,3 +51,5 @@
 | 2026-04-17 | 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. | src/pactkit/prompts/rules.py:RULES_MODULES |
 | 2026-04-18 | 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 | guards.py:check_version_mismatch |
 | 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 |

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

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

@@ -205,3 +205,10 @@
 - [x] Update Shared Protocols Referenced-by line
 - [x] Redeploy via pactkit update
 - [x] Verify deployed plugin sync
+
+### [STORY-slim-100] Hotfix impact check via .mmd call graph
+> Spec: docs/specs/STORY-slim-100.md
+
+- [x] Add Phase 0.5 Impact Check to HOTFIX_PROMPT
+- [x] Add tests for new phase
+- [x] Deploy verification

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

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-04-20T10:21:11+08:00 by pactkit context
+> Last updated: 2026-04-20T17:32:07+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 0 | In Progress: 0 | Done: 0 stories
@@ -15,11 +15,11 @@ develop
 * main
 
 ## Key Decisions
-- Weighted hotspot formula (complexity 25% + docstring 15% + smells 15% + layers 10% + test 20% + blast 15%) gives meaningful scores across different project profiles; _generate_suggested_tasks auto-scaffolds BUG/HOTFIX specs with Done-completed filter for idempotency
-- Dual-dimension audit (config+code 50/50) gives accurate project health picture; scanning ~/.claude/ global config catches harness setup invisible at project level
 - 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.
 
 ## Next Recommended Action
 `/project-design`

pactkit-2.10.4/docs/specs/STORY-slim-100.md

@@ -0,0 +1,87 @@
+# STORY-slim-100: Hotfix impact check via .mmd call graph
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-100 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.4 |
+
+## Background
+
+The `/project-hotfix` playbook locates target code via `Grep`/`Glob` (Phase 0) and immediately proceeds to fix (Phase 1) without consulting the project's `.mmd` call graph files. This means "No Side Effects" (Phase 1.3) is enforced purely by AI judgment, not data. In contrast, `/project-act` uses `pactkit-trace` (Phase 1) and `code_graph.mmd` importer counts (Phase 3) to detect high-fan-in functions before modifying them. A hotfix that changes a function with 5+ callers can silently break upstream consumers.
+
+## Requirements
+
+### R1: Lightweight Impact Check Phase (MUST)
+
+Insert a new **Phase 0.5: Impact Check** between Phase 0 (Locate & Register) and Phase 1 (Fix) in the `HOTFIX_PROMPT`. This phase reads existing `.mmd` call graph files (`call_graph.mmd`, `reverse_call_graph.mmd`, or `code_graph.mmd`) to identify callers of the target function/file.
+
+### R2: High-Fan-In Warning (SHOULD)
+
+If the target function/file has **3+ callers** in the call graph, the playbook SHOULD warn the user about potential impact scope and suggest considering `/project-act` for the full PDCA workflow.
+
+### R3: Graceful Degradation (MUST)
+
+If `.mmd` files do not exist in `docs/architecture/graphs/`, the impact check MUST skip silently with a log message ("No call graph available — skipping impact check"). This preserves hotfix's lightweight nature for projects without visualize data.
+
+### R4: Non-Blocking (MUST)
+
+The impact check MUST NOT block the hotfix workflow — it is advisory only (L3 signal). The user can acknowledge the warning and proceed.
+
+## Acceptance Criteria
+
+### AC1: Impact Check Phase Exists in Prompt (R1)
+
+- **Given** the `HOTFIX_PROMPT` string in `workflows.py`
+- **When** the prompt text is inspected
+- **Then** it contains "Phase 0.5" and "Impact Check" and references `.mmd` call graph files
+
+### AC2: High-Fan-In Warning Text Present (R2)
+
+- **Given** the `HOTFIX_PROMPT` string
+- **When** the prompt text is inspected
+- **Then** it contains a threshold (e.g., "3+ callers") and a suggestion to consider `/project-act`
+
+### AC3: Graceful Skip When No Graphs (R3)
+
+- **Given** the `HOTFIX_PROMPT` string
+- **When** the prompt text is inspected
+- **Then** it contains instructions to skip silently if `.mmd` files do not exist
+
+### AC4: Non-Blocking Advisory Signal (R4)
+
+- **Given** the `HOTFIX_PROMPT` string
+- **When** the prompt text is inspected
+- **Then** the impact check is described as advisory (not a gate), and the phase does not use "MUST STOP" or blocking language
+
+## Target Call Chain
+
+`HOTFIX_PROMPT` (workflows.py:543) → imported by `commands.py:3` → registered in `COMMANDS_CONTENT["project-hotfix.md"]` (commands.py:750) → deployed by `deployer.py` via `_render_prompt()` → output to `pactkit-plugin/commands/project-hotfix.md` and `.github/prompts/project-hotfix.prompt.md`
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/workflows.py` | Add Phase 0.5 Impact Check text to `HOTFIX_PROMPT` between Phase 0 and Phase 1 | None | Low |
+| 2 | `tests/unit/test_hotfix_command.py` | Add test class verifying Phase 0.5 keywords exist in prompt | Step 1 | Low |
+| 3 | Deploy verification | Run `pactkit deploy` and verify `pactkit-plugin/commands/project-hotfix.md` contains the new phase | Step 1 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | Prompt text only, no executable injection surface |
+| SEC-2 | N/A | No user input processing — playbook instruction text |
+| SEC-3 | N/A | No database patterns |
+| SEC-4 | N/A | No frontend files |
+| SEC-5 | N/A | No auth/session handling — false positive on keyword match |
+| SEC-6 | N/A | No API/route files |
+| SEC-7 | N/A | No error handling patterns |
+| SEC-8 | N/A | No dependency manifests |
+
+## Out of Scope
+
+- Full `pactkit-trace` integration (too heavy for hotfix; Act already handles it)
+- Updating `code_graph.mmd` or `call_graph.mmd` during hotfix (hotfix is read-only on graphs)
+- Blocking hotfix workflow based on impact check results

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

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

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

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

{pactkit-2.10.2 → pactkit-2.10.4}/src/pactkit/cleaners.py

@@ -15,6 +15,9 @@ _CLEANUP_PATTERNS: dict[str, list[str]] = {
     "java": ["target/", "build/", ".gradle/"],
 }
 
+# Directories whose contents must never be cleaned by rglob patterns
+_PROTECTED_PARENTS = {"node_modules", ".git"}
+
 # Stack detection markers (ordered by priority)
 _STACK_MARKERS: list[tuple[str, str]] = [
     ("pyproject.toml", "python"),
@@ -27,6 +30,12 @@ _STACK_MARKERS: list[tuple[str, str]] = [
 ]
 
 
+def _inside_protected(path: Path, project_root: Path) -> bool:
+    """Return True if path is inside a protected parent directory."""
+    rel = path.relative_to(project_root)
+    return bool(_PROTECTED_PARENTS & set(rel.parts[:-1]))
+
+
 def detect_stacks(project_root: Path) -> list[str]:
     """Detect all project stacks from marker files.
 
@@ -84,9 +93,21 @@ def clean_artifacts(
     removed: list[Path] = []
 
     for pattern in patterns:
-        if "*" in pattern:
+        if "/" in pattern:
+            # Explicit path (e.g., "node_modules/.cache") — match directly
+            target = project_root / pattern
+            if target.exists():
+                removed.append(target)
+                if not dry_run:
+                    if target.is_dir():
+                        shutil.rmtree(target)
+                    else:
+                        target.unlink()
+        elif "*" in pattern:
             # Glob pattern (e.g., "*.pyc")
             for match in project_root.rglob(pattern):
+                if _inside_protected(match, project_root):
+                    continue
                 removed.append(match)
                 if not dry_run:
                     if match.is_dir():
@@ -94,9 +115,11 @@ def clean_artifacts(
                     else:
                         match.unlink()
         else:
-            # Directory or file name (e.g., "__pycache__", ".pytest_cache")
+            # Directory or file name (e.g., "__pycache__", "dist")
             clean_name = pattern.rstrip("/")
             for match in project_root.rglob(clean_name):
+                if _inside_protected(match, project_root):
+                    continue
                 removed.append(match)
                 if not dry_run:
                     if match.is_dir():

{pactkit-2.10.2 → pactkit-2.10.4}/src/pactkit/prompts/workflows.py

@@ -573,6 +573,16 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 6.  **Add Board Entry**: Add the hotfix to the Board:
     - `{BOARD_CMD} add_story HOTFIX-{NNN} "Short title" "Fix description"`
 
+## 🔍 Phase 0.5: Impact Check (Lightweight)
+> **PURPOSE**: Data-driven side-effect awareness — read existing call graphs to surface upstream callers before modifying code. This is advisory (L3 SHOULD), non-blocking.
+1.  **Check Graph Availability**: Look for `docs/architecture/graphs/call_graph.mmd` or `docs/architecture/graphs/reverse_call_graph.mmd` or `docs/architecture/graphs/code_graph.mmd`.
+    - If none exist: log "No call graph available — skipping impact check" and proceed to Phase 1.
+2.  **Identify Callers**: Search the available `.mmd` file for the target function/file identified in Phase 0. Count how many other nodes reference it (callers/importers).
+3.  **High-Fan-In Warning**: If the target has **3+ callers**, SHOULD warn the user:
+    > "⚠️ Target has {N} callers in the call graph. Changes may affect upstream consumers. Consider `/project-act` for full impact analysis."
+    - This warning is advisory — the user can acknowledge and proceed.
+4.  **Proceed**: Continue to Phase 1 regardless of findings.
+
 ## 🔧 Phase 1: Fix
 1.  **Fix**: Use `Edit` or `Write` to directly fix the target code.
 2.  **Scope**: Keep the modification scope as small as possible — only change what must be changed, no extra optimization or refactoring.

{pactkit-2.10.2 → pactkit-2.10.4}/tests/unit/test_hotfix_command.py

@@ -138,6 +138,43 @@ class TestBackwardCompatibility:
             assert agent in p.AGENTS_EXPERT, f"Missing agent {agent}"
 
 
+class TestImpactCheckPhase:
+    """Scenario 8: Phase 0.5 Impact Check exists (STORY-slim-100)"""
+
+    def test_has_phase_05(self):
+        p = _prompts()
+        assert 'Phase 0.5' in p.HOTFIX_PROMPT
+
+    def test_has_impact_check_title(self):
+        p = _prompts()
+        assert 'Impact Check' in p.HOTFIX_PROMPT
+
+    def test_references_mmd_files(self):
+        p = _prompts()
+        text = p.HOTFIX_PROMPT
+        assert 'call_graph.mmd' in text or 'reverse_call_graph.mmd' in text or 'code_graph.mmd' in text
+
+    def test_has_fan_in_threshold(self):
+        p = _prompts()
+        assert '3+' in p.HOTFIX_PROMPT or '3 or more' in p.HOTFIX_PROMPT
+
+    def test_suggests_project_act(self):
+        p = _prompts()
+        assert '/project-act' in p.HOTFIX_PROMPT
+
+    def test_graceful_skip_when_no_graphs(self):
+        p = _prompts()
+        text = p.HOTFIX_PROMPT.lower()
+        assert 'skip' in text and ('no call graph' in text or 'do not exist' in text or 'not exist' in text)
+
+    def test_non_blocking_advisory(self):
+        """Impact check must not use blocking language."""
+        p = _prompts()
+        text = p.HOTFIX_PROMPT
+        assert 'MUST STOP' not in text or text.index('Phase 0.5') > text.index('MUST STOP')
+        assert 'advisory' in text.lower() or 'non-blocking' in text.lower() or 'SHOULD' in text
+
+
 class TestDeployment:
     """Scenario 7: 部署后文件存在"""
 

{pactkit-2.10.2 → pactkit-2.10.4}/tests/unit/test_story063_prompt_slimming.py

@@ -203,7 +203,8 @@ class TestAC6DevRefGhostResolved:
 # STORY-slim-072/073: bumped +2489 for Check Phase 4.5/4.7 (PactGuard + Observe)
 # STORY-slim-091: bumped +248 for Done Phase 3.8 harness audit refresh
 # audit --if-needed in Done playbook
-BASELINE_TOTAL_CHARS = 79143
+# STORY-slim-100: bumped +1212 for Hotfix Phase 0.5 Impact Check
+BASELINE_TOTAL_CHARS = 80355
 
 
 class TestAC7PromptSizeReduced:

{pactkit-2.10.2 → pactkit-2.10.4}/tests/unit/test_story_slim014_clean.py

@@ -87,3 +87,47 @@ class TestCleanArtifacts:
 
         removed = clean_artifacts(tmp_path, stack="auto")
         assert len(removed) >= 1
+
+    def test_clean_node_skips_dist_inside_node_modules(self, tmp_path):
+        """dist inside node_modules must NOT be deleted."""
+        (tmp_path / "package.json").write_text("{}")
+        # Create a dependency with dist/
+        dep_dist = tmp_path / "node_modules" / "some-pkg" / "dist"
+        dep_dist.mkdir(parents=True)
+        (dep_dist / "index.js").write_text("module.exports = {}")
+        # Create a project-level dist/ that SHOULD be cleaned
+        proj_dist = tmp_path / "dist"
+        proj_dist.mkdir()
+        (proj_dist / "bundle.js").write_text("")
+
+        removed = clean_artifacts(tmp_path, stack="node")
+        assert proj_dist not in list(tmp_path.iterdir())
+        assert dep_dist.exists(), "node_modules/*/dist must survive clean"
+
+    def test_clean_node_modules_cache_still_cleaned(self, tmp_path):
+        """node_modules/.cache is explicitly targeted and should be cleaned."""
+        (tmp_path / "package.json").write_text("{}")
+        nm_cache = tmp_path / "node_modules" / ".cache"
+        nm_cache.mkdir(parents=True)
+        (nm_cache / "babel").mkdir()
+        (nm_cache / "babel" / "data.json").write_text("{}")
+
+        removed = clean_artifacts(tmp_path, stack="node")
+        assert any("node_modules/.cache" in str(p) for p in removed)
+        assert not nm_cache.exists()
+
+    def test_clean_skips_pyc_inside_node_modules(self, tmp_path):
+        """Glob patterns (*.pyc) must not match inside node_modules."""
+        (tmp_path / "pyproject.toml").write_text("[project]")
+        # A .pyc in node_modules (unlikely but possible in hybrid projects)
+        nm_pyc = tmp_path / "node_modules" / "weird" / "file.pyc"
+        nm_pyc.parent.mkdir(parents=True)
+        nm_pyc.write_text("")
+        # A normal .pyc that should be cleaned
+        normal_pyc = tmp_path / "src" / "mod.pyc"
+        normal_pyc.parent.mkdir(parents=True)
+        normal_pyc.write_text("")
+
+        removed = clean_artifacts(tmp_path, stack="python")
+        assert not normal_pyc.exists(), "src/*.pyc should be cleaned"
+        assert nm_pyc.exists(), "node_modules/**/*.pyc must survive clean"