pactkit 2.3.0__tar.gz → 2.3.3__tar.gz

{pactkit-2.3.0 → pactkit-2.3.3}/.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.2.0"
+version: "2.3.3"
 stack: python
 root: .
 developer: "slim"
@@ -56,6 +56,7 @@ rules:
   - 06-mcp-integration
   - 07-shared-protocols
   - 08-architecture-principles
+  - 09-sectional-write
 
 # CI/CD — set provider to github or gitlab to generate pipeline config
 ci:
@@ -112,3 +113,10 @@ agent_models:
   system-architect: opus
   system-medic: haiku
   visual-architect: sonnet
+
+# Custom — user-defined keys (preserved by PactKit)
+e2e:
+  blocking: false
+  env_file: .env.test
+  test_dir: tests/e2e
+  type: none

{pactkit-2.3.0 → pactkit-2.3.3}/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.3.3] - 2026-03-23
+
+### Added
+- **Auto Version Sync** (STORY-slim-023) — `pactkit update --if-needed` compares `pactkit.yaml` version vs installed `__version__`. If match, skips redeploy; if mismatch, proceeds with full deploy. Core Protocol prompt updated to run this at session start for zero-friction upgrades.
+
+### Fixed
+- **Guard Version Mismatch Detection** (HOTFIX-slim-024) — `pactkit guard` now checks version mismatch and prints warning with suggestion to run `pactkit update`. Also adds `e2e` to `_BACKFILL_KEYS` so new config section is auto-added during update.
+
+## [2.3.2] - 2026-03-23
+
+### Added
+- **E2E Testing Framework** (STORY-slim-022) — Config-driven E2E strategy in `pactkit.yaml` (`e2e.type`: none/cli/frontend/backend/fullstack). `/project-check` Phase 4 rewritten from hardcoded Strategy A/B to config-driven table. `env_file` field (default `.env.test`) for test credential isolation. Non-blocking by default (`e2e.blocking: false`).
+
+### Fixed
+- **Visualize CLI --mode** (HOTFIX-slim-023) — `pactkit visualize --mode class/call` previously failed with "unrecognized arguments". Added `--mode` parameter and wired non-lazy mode to execute graphs directly.
+- **Board Archive Section Headers** (HOTFIX-slim-021) — `archive_stories()` now preserves `## 🔄 In Progress` and `## ✅ Done` section headers when archiving removes all stories from a section.
+
+## [2.3.1] - 2026-03-23
+
+### Fixed
+- **Plan Phase 3.2 Stall** (STORY-slim-019) — Split monolithic Spec-writing phase into 4 sub-steps (3.2a Skeleton, 3.2b Acceptance Criteria, 3.2c Security Scope, 3.2d Spec Lint) with output checkpoints between each, eliminating AI buffering stall on large Spec generation.
+- **Explore Subagent Stall** (STORY-slim-020) — Added Bounded Delegation template to Plan Phase 1 (target/scope/limit/output constraints for Explore subagents), reduced `code-explorer` maxTurns from 50 to 15, and added scope-limiting instructions to prevent unbounded codebase exploration.
+- **CI Workflow** — Reverted `actions/checkout` and `actions/setup-python` from v6 back to v4/v5 for CI stability after Dependabot upgrades caused failures.
+
 ## [2.3.0] - 2026-03-22
 
 ### Added

{pactkit-2.3.0 → pactkit-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.3.0
+Version: 2.3.3
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit
@@ -158,21 +158,34 @@ Or run the full cycle in one command:
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
 
-### Role-Based Command Guide
+### When to Use What
 
-Choose commands based on your role:
+The core loop is **Plan → Act → Done**. Other commands plug in as needed:
 
-| Role | Commands | What You Do |
-|------|----------|-------------|
-| **BA** | `/project-clarify` | Surface ambiguities, produce Clarified Brief |
-| **PM** | `/project-design` | Generate PRD, decompose into Stories |
-| **Architect** | `/project-plan`, `/project-init` | Create Specs, initialize project governance |
-| **Developer** | `/project-act`, `/project-hotfix` | TDD implementation, emergency fixes |
-| **QA** | `/project-check` | Security + quality audit, spec alignment |
-| **DevOps** | `/project-done`, `/project-release`, `/project-pr` | Commit, release, pull request |
-| **Team Lead** | `/project-sprint` | One-command PDCA orchestration (**Claude Code only**) |
+```
+You have a task
+  │
+  ├─ Vague idea, multiple features? ──→ /project-design
+  │
+  ├─ Unclear requirement? ──→ /project-clarify → /project-plan
+  │
+  ├─ Clear feature or bug?
+  │   │
+  │   ├─ Small fix (1 file, obvious)? ──→ /project-hotfix
+  │   │
+  │   └─ Needs design? ──→ /project-plan → /project-act
+  │       │
+  │       ├─ Security-sensitive? ──→ /project-check (QA audit)
+  │       │
+  │       └─ /project-done
+  │           │
+  │           ├─ On feature branch? ──→ /project-pr
+  │           └─ Ready to release? ──→ /project-release
+  │
+  └─ Fully automated? ──→ /project-sprint (runs all phases)
+```
 
-> **Solo developer?** Focus on `/project-plan` → `/project-act` → `/project-done`. Other commands become valuable when you have team collaboration or external stakeholders.
+**Solo developer?** Start with `/project-plan` → `/project-act` → `/project-done`. Add `/project-hotfix` for small fixes and `/project-check` when security matters.
 
 ### Embedded Skills (auto-invoked by commands)
 

{pactkit-2.3.0 → pactkit-2.3.3}/README.md

@@ -132,21 +132,34 @@ Or run the full cycle in one command:
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
 
-### Role-Based Command Guide
+### When to Use What
 
-Choose commands based on your role:
+The core loop is **Plan → Act → Done**. Other commands plug in as needed:
 
-| Role | Commands | What You Do |
-|------|----------|-------------|
-| **BA** | `/project-clarify` | Surface ambiguities, produce Clarified Brief |
-| **PM** | `/project-design` | Generate PRD, decompose into Stories |
-| **Architect** | `/project-plan`, `/project-init` | Create Specs, initialize project governance |
-| **Developer** | `/project-act`, `/project-hotfix` | TDD implementation, emergency fixes |
-| **QA** | `/project-check` | Security + quality audit, spec alignment |
-| **DevOps** | `/project-done`, `/project-release`, `/project-pr` | Commit, release, pull request |
-| **Team Lead** | `/project-sprint` | One-command PDCA orchestration (**Claude Code only**) |
+```
+You have a task
+  │
+  ├─ Vague idea, multiple features? ──→ /project-design
+  │
+  ├─ Unclear requirement? ──→ /project-clarify → /project-plan
+  │
+  ├─ Clear feature or bug?
+  │   │
+  │   ├─ Small fix (1 file, obvious)? ──→ /project-hotfix
+  │   │
+  │   └─ Needs design? ──→ /project-plan → /project-act
+  │       │
+  │       ├─ Security-sensitive? ──→ /project-check (QA audit)
+  │       │
+  │       └─ /project-done
+  │           │
+  │           ├─ On feature branch? ──→ /project-pr
+  │           └─ Ready to release? ──→ /project-release
+  │
+  └─ Fully automated? ──→ /project-sprint (runs all phases)
+```
 
-> **Solo developer?** Focus on `/project-plan` → `/project-act` → `/project-done`. Other commands become valuable when you have team collaboration or external stakeholders.
+**Solo developer?** Start with `/project-plan` → `/project-act` → `/project-done`. Add `/project-hotfix` for small fixes and `/project-check` when security matters.
 
 ### Embedded Skills (auto-invoked by commands)
 

{pactkit-2.3.0 → pactkit-2.3.3}/pyproject.toml

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

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/__init__.py

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

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/cli.py

@@ -137,6 +137,13 @@ def main():
         default=False,
         help="Non-interactive mode: auto-accept defaults (CI/CD environments)",
     )
+    # STORY-slim-023: Auto version sync
+    update_parser.add_argument(
+        "--if-needed",
+        action="store_true",
+        default=False,
+        help="Only redeploy if installed version differs from pactkit.yaml version",
+    )
 
     # pactkit upgrade (alias for init, migrates legacy scafpy files)
     upgrade_parser = subparsers.add_parser("upgrade", help="Upgrade PactKit (migrate legacy scafpy config)")
@@ -237,10 +244,14 @@ def main():
     lint_tc_parser = subparsers.add_parser("lint-testcase", help="Validate test case file structure")
     lint_tc_parser.add_argument("path", help="Path to test case file")
 
-    # pactkit visualize --lazy (STORY-slim-014 R7)
+    # pactkit visualize --lazy --mode (STORY-slim-014 R7, HOTFIX-slim-023)
     viz_parser = subparsers.add_parser("visualize", help="Visualize code dependency graph")
     viz_parser.add_argument("--lazy", action="store_true", help="Skip if no source changes")
     viz_parser.add_argument("--stack", default="auto", help="Language stack (default: auto)")
+    viz_parser.add_argument(
+        "--mode", choices=["file", "class", "call"], default=None,
+        help="Graph mode (default: all three)",
+    )
 
     # pactkit doctor (STORY-slim-015 R1-R3)
     subparsers.add_parser("doctor", help="Diagnose project health")
@@ -286,6 +297,23 @@ def main():
     args = parser.parse_args()
 
     if args.command in ("init", "update", "upgrade"):
+        # STORY-slim-023: --if-needed skips deploy when versions match
+        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__:
+                    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...")
+
         from pactkit.generators.deployer import deploy
 
         deploy(
@@ -316,11 +344,17 @@ def main():
     elif args.command == "guard":
         from pathlib import Path
 
-        from pactkit.guards import check_init_markers
+        from pactkit.guards import check_init_markers, check_version_mismatch
 
-        ok, missing = check_init_markers(Path.cwd())
+        project_root = Path.cwd()
+        ok, missing = check_init_markers(project_root)
         if ok:
             print("Guard: PASS — all init markers present")
+            # HOTFIX-slim-024: check version mismatch
+            version_warn = check_version_mismatch(project_root)
+            if version_warn:
+                print(f"  ⚠️  {version_warn}")
+                print("     Run `pactkit update` to sync")
         else:
             for m in missing:
                 print(f"  ✗ {m}")
@@ -429,23 +463,22 @@ def main():
             print(f"{args.path}\n  Result: PASS")
 
     elif args.command == "visualize":
-        if args.lazy:
-            from pathlib import Path
+        from pathlib import Path
 
-            from pactkit.lazy_visualize import should_visualize
+        from pactkit.lazy_visualize import run_visualize_graphs, run_visualize_single, should_visualize
 
-            project_root = Path.cwd()
+        project_root = Path.cwd()
+        if args.lazy:
             should_run, reason = should_visualize(project_root, stack=args.stack)
             if not should_run:
                 print(reason)
                 raise SystemExit(0)
             print(f"Visualize needed: {reason}")
-            # Execute graph generation end-to-end (BUG-slim-006 R3)
-            from pactkit.lazy_visualize import run_visualize_graphs
+        # HOTFIX-slim-023: support --mode for single or all modes
+        if args.mode:
+            run_visualize_single(project_root, args.mode)
+        else:
             run_visualize_graphs(project_root)
-            raise SystemExit(0)
-        # Non-lazy: print guidance for manual run
-        print("Run visualize skill for full graph generation")
 
     elif args.command == "doctor":
         from pathlib import Path

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/config.py

@@ -69,6 +69,7 @@ VALID_RULES = frozenset(
         "06-mcp-integration",
         "07-shared-protocols",
         "08-architecture-principles",
+        "09-sectional-write",
     }
 )
 
@@ -82,6 +83,8 @@ VALID_ISSUE_PROVIDERS = frozenset({"github", "none"})
 
 VALID_HOOK_TEMPLATES = frozenset({"pre_commit_lint", "post_test_coverage", "pre_push_check"})
 
+VALID_E2E_TYPES = frozenset({"none", "cli", "frontend", "backend", "fullstack"})
+
 # Commands deprecated in v1.2.0 — converted to skills (STORY-011)
 DEPRECATED_COMMANDS = frozenset(
     {
@@ -164,6 +167,12 @@ def get_default_config() -> dict:
             "security_checklist": True,
             "security_scope_override": "none",
         },
+        "e2e": {
+            "type": "none",
+            "blocking": False,
+            "test_dir": "tests/e2e",
+            "env_file": ".env.test",
+        },
         "done": {
             "lesson_quality_threshold": 15,
         },
@@ -352,6 +361,7 @@ def load_config(path: Path | str | None = None) -> dict:
         "regression",
         "check",
         "done",
+        "e2e",
         "command_models",
     }
 
@@ -447,6 +457,7 @@ def auto_merge_config_file(path: Union[Path, str]) -> list[str]:
         "regression",
         "check",
         "done",
+        "e2e",  # STORY-slim-022
     )
     for key in _BACKFILL_KEYS:
         if key not in user_data:
@@ -796,6 +807,30 @@ def validate_config(config: dict) -> None:
         if not isinstance(threshold, int) or threshold < 0 or threshold > 25:
             warnings.warn(f"done.lesson_quality_threshold should be an integer 0-25, got {threshold!r}")
 
+    # Validate e2e section (STORY-slim-022)
+    e2e = config.get("e2e", {})
+    if isinstance(e2e, dict):
+        e2e_type = e2e.get("type", "none")
+        if e2e_type not in VALID_E2E_TYPES:
+            warnings.warn(
+                f"e2e.type should be one of {', '.join(sorted(VALID_E2E_TYPES))}, got '{e2e_type}'"
+            )
+        e2e_blocking = e2e.get("blocking", False)
+        if not isinstance(e2e_blocking, bool):
+            warnings.warn(
+                f"e2e.blocking should be a boolean (true/false), got {type(e2e_blocking).__name__}"
+            )
+        e2e_test_dir = e2e.get("test_dir")
+        if e2e_test_dir is not None and not isinstance(e2e_test_dir, str):
+            warnings.warn(
+                f"e2e.test_dir should be a string, got {type(e2e_test_dir).__name__}"
+            )
+        e2e_env_file = e2e.get("env_file")
+        if e2e_env_file is not None and not isinstance(e2e_env_file, str):
+            warnings.warn(
+                f"e2e.env_file should be a string, got {type(e2e_env_file).__name__}"
+            )
+
     # enterprise section (STORY-047) — accepted without warnings
     # multi_agent field (STORY-046) — accepted without warnings
 
@@ -902,6 +937,15 @@ def generate_default_yaml() -> str:
     lines.append("done:")
     lines.append(f"  lesson_quality_threshold: {done_cfg.get('lesson_quality_threshold', 15)}")
 
+    # Write e2e section (STORY-slim-022)
+    e2e = cfg.get("e2e", {})
+    lines.extend(["", "# E2E Testing — configure end-to-end test strategy (none|cli|frontend|backend|fullstack)"])
+    lines.append("e2e:")
+    lines.append(f"  type: {e2e.get('type', 'none')}")
+    lines.append(f"  blocking: {'true' if e2e.get('blocking') else 'false'}")
+    lines.append(f"  test_dir: {e2e.get('test_dir', 'tests/e2e')}")
+    lines.append(f"  env_file: {e2e.get('env_file', '.env.test')}")
+
     # Write command_models section (STORY-073)
     cmd_models = cfg.get("command_models", {})
     if cmd_models:

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/guards.py

@@ -6,7 +6,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from pactkit.config import find_pactkit_yaml
+from pactkit import __version__
+from pactkit.config import find_pactkit_yaml, load_config
 
 
 def check_init_markers(project_root: Path) -> tuple[bool, list[str]]:
@@ -65,3 +66,20 @@ def check_config_completeness(project_root: Path) -> list[str]:
         if key not in data:
             warnings.append(f"Missing config section: '{key}' in {yaml_path.name}")
     return warnings
+
+
+def check_version_mismatch(project_root: Path) -> str | None:
+    """Check if pactkit.yaml version differs from installed __version__.
+
+    Returns:
+        Warning message if mismatch, None if versions match or yaml not found.
+    """
+    yaml_path = find_pactkit_yaml(project_root)
+    if yaml_path is None:
+        return None
+
+    cfg = load_config(yaml_path)
+    yaml_version = cfg.get("version", "")
+    if yaml_version and yaml_version != __version__:
+        return f"Version mismatch: pactkit.yaml {yaml_version} vs installed {__version__}"
+    return None

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/lazy_visualize.py

@@ -80,6 +80,20 @@ def should_visualize(
     return (False, "Graph up-to-date — no source changes")
 
 
+def run_visualize_single(project_root: Path, mode: str) -> None:
+    """Execute visualize.py for a single graph mode (HOTFIX-slim-023)."""
+    import sys
+
+    viz_script = Path(__file__).resolve().parent / "skills" / "visualize.py"
+    if not viz_script.exists():
+        print(f"visualize.py not found: {viz_script}")
+        return
+    subprocess.run(
+        [sys.executable, str(viz_script), "visualize", "--mode", mode],
+        cwd=str(project_root),
+    )
+
+
 def run_visualize_graphs(project_root: Path) -> None:
     """Execute visualize.py to regenerate all graph files.
 

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/prompts/agents.py

@@ -248,7 +248,7 @@ Generate system architecture diagrams using Draw.io XML. Supports three diagram
     "code-explorer": {
         "desc": "Deep code analysis and execution tracing.",
         "tools": "Read, Bash, Grep, Glob, Find",
-        "maxTurns": 50,
+        "maxTurns": 15,  # STORY-slim-020: reduced from 50 to prevent unbounded exploration stalls
         "memory": "user",
         "prompt": """You are the **Code Explorer** (aka System Archaeologist).
 **Motto**: "Read little, understand much."

{pactkit-2.3.0 → pactkit-2.3.3}/src/pactkit/prompts/commands.py

@@ -64,11 +64,18 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 6.  **Output**: The enriched_input (original + answers) is used as context for Phase 1 onwards.
 
 ## 🎬 Phase 1: Archaeology (The "Know Before You Change" Step)
-1.  **Visual Scan**: Run `visualize` to see the module dependency graph. Use `--mode class` for structure, `--mode call` for logic.
-    - For large codebases (50+ files), use `--focus <module> --depth 2` to limit scope.
+> **Subagent Scope Rule**: When delegating research to an Explore subagent, always provide a **bounded** prompt: target function/class, directory scope, file limit, and expected output. Never delegate open-ended "trace the whole codebase" tasks.
+
+1.  **Visual Scan**: Run `visualize --focus <module> --depth 2` to see the targeted dependency graph. Only expand to `--mode class` or `--mode call` if the focused scan is insufficient.
 2.  **Logic Trace (CRITICAL)** — use pactkit-trace skill:
     - If modifying existing logic, trace the current implementation.
     - *Goal*: Identify the exact function/class responsible for the logic.
+    - **Delegation Template**: When using an Explore subagent for trace, formulate the prompt with:
+      - **Target**: specific function or class name to trace
+      - **Scope**: specific directory (e.g., `src/pactkit/generators/`)
+      - **Limit**: read at most 8-10 files
+      - **Output**: what to return (entry file, call chain, key data transformations)
+      - Example: `Agent(subagent_type="Explore", prompt="Find the deploy() entry point in src/pactkit/generators/deployer.py. Trace the call chain to file writes. Read at most 8 files. Return: entry function, call chain list, key data transformations.")`
 
 ## 🎬 Phase 2: Design & Impact
 1.  **Diff**: Compare User Request vs Current Reality (from Phase 1).
@@ -79,9 +86,9 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 1.  Run `pactkit next-id` to get the next Story ID (reads developer prefix from pactkit.yaml, scans `docs/specs/`).
 2.  **Output checkpoint**: Print "Story ID determined: {ID}. Writing Spec now."
 
-## 🎬 Phase 3.2: Write Spec
-1.  **Spec**: Create `docs/specs/{ID}.md` detailing the *Change*.
-    - **MUST — Metadata Table**: Include a metadata table at the top of the Spec using this EXACT format:
+## 🎬 Phase 3.2a: Spec Skeleton (Metadata + Requirements)
+1.  **Create file**: Create `docs/specs/{ID}.md` with the following sections:
+    - **MUST — Metadata Table**: Include a metadata table at the top using this EXACT format:
       ```markdown
       | Field | Value |
       |-------|-------|
@@ -91,41 +98,41 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
       | Release | {version} |
       ```
       Field names MUST be exact case (ID, Status, Priority, Release) — not bold, not different names.
-    - *Requirement*: Include a "Target Call Chain" section in the Spec based on your Trace findings.
+    - **MUST**: Fill in the `Release` metadata field by reading the `version` field from `{PACTKIT_YAML}` or `pyproject.toml`. Use that EXACT value — do NOT increment or predict a future version. If the file cannot be read, use `TBD`.
+    - **MUST**: Include `## Background` and `## Target Call Chain` sections based on your Trace findings.
     - **MUST**: Fill in the `## Requirements` section using RFC 2119 keywords (MUST/SHOULD/MAY).
-    - **MUST**: Fill in the `## Acceptance Criteria` section with Given/When/Then scenarios.
+2.  **Output checkpoint**: Print "Spec skeleton written. Adding acceptance criteria."
+
+## 🎬 Phase 3.2b: Acceptance Criteria & Implementation Steps
+1.  **MUST**: Add `## Acceptance Criteria` section with Given/When/Then scenarios.
     - Each Scenario SHOULD map to a verifiable test case in `docs/test_cases/`.
-    - **MUST**: Fill in the `Release` metadata field by reading the `version` field from `{PACTKIT_YAML}` or `pyproject.toml`. Use that EXACT value — do NOT increment or predict a future version. If the file cannot be read, use `TBD`.
-    - **OPTIONAL — Implementation Steps**: If Phase 1 Trace identifies 2+ files to modify, add `## Implementation Steps` section with table format:
-      ```
-      | Step | File | Action | Dependencies | Risk |
-      |------|------|--------|--------------|------|
-      | 1 | `src/foo.py` | Description | None | Low |
-      ```
-      The `Dependencies` column accepts `None`, `Step N`, or comma-separated step references. The `Risk` column accepts `Low`, `Medium`, `High`. This section is optional but RECOMMENDED for multi-file changes.
-    - **MUST — Security Scope**: Run `pactkit sec-scope <changed-files>` to auto-detect SEC-1~SEC-8 applicability. Paste the output Markdown table into the `## Security Scope` section of the Spec. If `pactkit sec-scope` is unavailable, apply these detection rules manually:
-      | Check | Applicable When |
-      |-------|-----------------|
-      | SEC-1 | Any source code file modified (`.py`, `.js`, `.ts`, `.go`, `.java`, etc.) |
-      | SEC-2 | Code contains `request.`, `form.`, `input`, `argv`, `sys.stdin`, `process.argv` |
-      | SEC-3 | Files in `models/`, `dao/`, `repository/`; or code contains SQL/ORM patterns |
-      | SEC-4 | Frontend files (`.tsx`, `.vue`, `.svelte`, `.html`); or code contains `innerHTML`, `dangerouslySetInnerHTML` |
-      | SEC-5 | Files in `auth/`, `session/`, `login/`; or code contains `token`, `jwt`, `cookie`, `session` |
-      | SEC-6 | Files in `api/`, `routes/`, `endpoints/`, `controllers/` |
-      | SEC-7 | Files in `api/`, `routes/`; or code contains exception handling patterns |
-      | SEC-8 | Dependency files modified (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`) |
-
-      **Docs/tests-only shortcut**: If ONLY `docs/**`, `tests/**`, `*.md`, `README*` files changed, mark ALL checks N/A with Reason "docs/tests only".
-
-      Output format (the table must include a Reason column):
-      ```markdown
-      ## Security Scope
-      | Check | Applicable | Reason |
-      |-------|------------|--------|
-      | SEC-1 | Yes | Source code modified |
-      | SEC-2 | N/A | No user input handling |
-      ```
-    - **Spec Lint Self-Check**: After writing the Spec, run `pactkit spec-lint docs/specs/{ID}.md`. If ERROR rules fail, self-correct the Spec immediately (you wrote it — you have authority to fix it). Re-run until clean. This prevents the Spec from being rejected at Act Phase 0.5.
+2.  **OPTIONAL — Implementation Steps**: If Phase 1 Trace identifies 2+ files to modify, add `## Implementation Steps` section with table format:
+    ```
+    | Step | File | Action | Dependencies | Risk |
+    |------|------|--------|--------------|------|
+    | 1 | `src/foo.py` | Description | None | Low |
+    ```
+    The `Dependencies` column accepts `None`, `Step N`, or comma-separated step references. The `Risk` column accepts `Low`, `Medium`, `High`.
+3.  **Output checkpoint**: Print "Acceptance criteria written. Running security scope."
+
+## 🎬 Phase 3.2c: Security Scope
+1.  **MUST**: Run `pactkit sec-scope <changed-files>` to auto-detect SEC-1~SEC-8 applicability. Append the output to `## Security Scope` in the Spec.
+2.  **Fallback**: If `pactkit sec-scope` is unavailable, manually assess each SEC-1 through SEC-8 check based on changed file paths and code patterns. Apply docs/tests-only shortcut if applicable (mark ALL N/A with Reason "docs/tests only").
+3.  **Output format** (the table must include a Reason column):
+    ```markdown
+    ## Security Scope
+    | Check | Applicable | Reason |
+    |-------|------------|--------|
+    | SEC-1 | Yes | Source code modified |
+    | SEC-2 | N/A | No user input handling |
+    ```
+4.  **Output checkpoint**: Print "Security scope appended. Running lint."
+
+## 🎬 Phase 3.2d: Spec Lint Self-Check
+1.  Run `pactkit spec-lint docs/specs/{ID}.md`.
+2.  If ERROR rules fail, self-correct the Spec immediately (you wrote it — you have authority to fix it). Re-run until clean.
+3.  This prevents the Spec from being rejected at Act Phase 0.5.
+4.  **Output checkpoint**: Print "Spec lint passed."
 
 ## 🎬 Phase 3.3: Board, Memory & Handover
 1.  **Board**: Add Story using `add_story`.
@@ -300,22 +307,25 @@ For each finding, assign a severity (P0-P3). Flag issues that may cause silent f
 3.  **Report**: For each finding, assign the severity above and include it in the Phase 5 verdict.
 4.  **Gate**: If any P1 test quality issue is found, flag it as a required fix (same as a code quality P1).
 
-## Phase 4: Layered Execution
-Choose the strategy identified in Phase 0:
+## Phase 4: E2E Execution (Config-Driven)
+> Read `pactkit.yaml` field `e2e.type` to select strategy. Default: `none` (skip).
 
-### Strategy A: API Level (Fast & Stable)
-* **Context**: Backend logic, calculations.
-* **Action**: Create/Run `tests/e2e/api/test_{STORY_ID}.py` using `pytest` + `requests`.
+| e2e.type | Test Path | Tools | Cleanup |
+|----------|-----------|-------|---------|
+| `none` | Skip — log "E2E skipped" | — | — |
+| `cli` | `{e2e.test_dir}/cli/test_{STORY_ID}_cli.py` | pytest + subprocess | pytest `tmp_path` fixture (auto) |
+| `frontend` | `{e2e.test_dir}/browser/test_{STORY_ID}_browser.py` | Playwright + MSW mock from `e2e.api_spec` | MSW in-memory interceptors (auto) |
+| `backend` | `{e2e.test_dir}/api/test_{STORY_ID}_api.py` | pytest + httpx, contract via `e2e.api_spec` | transaction rollback via fixtures |
+| `fullstack` | `{e2e.test_dir}/browser/test_{STORY_ID}_full.py` | docker-compose up + Playwright | `docker-compose down -v` |
 
-### Strategy B: Browser Level (Visual & Real)
-* **Context**: UI, DOM, User Flows.
-* **Action**: Create/Run `tests/e2e/browser/test_{STORY_ID}_browser.py`.
-* **Playwright MCP (Conditional)**: IF Playwright MCP is available, use it for browser-level verification (navigation, snapshots, interactions).
-* **Chrome DevTools MCP (Conditional)**: IF Chrome DevTools MCP is available, use it for performance tracing and runtime diagnostics.
+* **Playwright MCP**: IF available, use for browser verification (frontend/fullstack).
+* **Chrome DevTools MCP**: IF available, use for performance tracing.
+* **`e2e.env_file`** (default `.env.test`): Load test credentials (API tokens, DB strings) from this file before running E2E. If file missing, WARN but continue.
+* **`e2e.blocking`** (default `false`): If `false`, E2E failures → WARN. If `true`, E2E failures → FAIL (blocks `/project-done`).
 
 ## Phase 5: The Verdict
-1.  **Run Suite**: Execute the specific test file created above (Story E2E test).
-2.  **Run Unit (Incremental)**: Run `pactkit test-map <changed-files>` to map source files to test files. Run only mapped tests. Fallback to full suite if no mapping.
+1.  **Run Unit (Incremental)**: Run `pactkit test-map <changed-files>` to map source files to test files. Run only mapped tests. Fallback to full suite if no mapping.
+2.  **Run E2E**: If `e2e.type` is not `none`, execute the E2E test file created in Phase 4.
 3.  **Report**: Output structured verdict:
 
 ```