refactor(validation): add io module, improve validation flow and tests

- Add src/pb_spec/validation/io.py for reusable validation I/O helpers
- Refactor build.py and plan.py validation logic
- Expand test coverage in tests/test_validate.py
- Update pyproject.toml and uv.lock for dependency changes
- Update pb-plan/pb-improve skill docs and configs

Author: Akagi201

.rumdl.toml

@@ -3,7 +3,7 @@
 # Global configuration options
 [global]
 # List of rules to disable (uncomment and modify as needed)
-disable = ["MD013", "MD033", "MD041", "MD036"]
+disable = ["MD013", "MD033", "MD041", "MD036", "MD031", "MD040"]
 
 # List of rules to enable exclusively (if provided, only these rules will run)
 # enable = ["MD001", "MD003", "MD004"]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pb-spec"
-version = "1.1.2"
+version = "1.1.3"
 description = "Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills"
 readme = "README.md"
 license = "Apache-2.0"

skills/pb-improve/SKILL.md

@@ -326,19 +326,56 @@ Write ONE `tasks.md` with tasks from ALL findings numbered sequentially. **Tasks
   - RED step: run scenario, capture failing output
   - GREEN step: implement, run scenario, capture passing output
   - REFACTOR step: clean up, re-run to confirm
-- Each task includes: Context, Verification, Scenario Coverage, Loop Type (BDD+TDD or TDD-only), Behavioral Contract, Simplification Focus, Status (🔴 TODO), BDD Verification, Advanced Test Verification, Runtime Verification
 - Ordered: infrastructure/scaffolding first (Phase 1), then findings in priority order
 - Verification commands with expected results
 
 **Cross-finding dependencies:** If Finding B depends on Finding A, place Finding A's tasks first and note the dependency in the task Context.
 
-**Task Quality Checklist:**
-
+> **⚠️ CRITICAL — Required Fields Contract (MUST follow for every task):**
+>
+> Every `### Task X.Y:` block MUST include ALL 10 of these fields, or pb-build will reject the spec:
+>
+> 1. `Context:` — why this task exists
+> 2. `Verification:` — how to verify the task is complete
+> 3. `Scenario Coverage:` — feature file + scenario name, or `N/A — [reason]`
+> 4. `Loop Type:` — `BDD+TDD` or `TDD-only`
+> 5. `Behavioral Contract:` — what behavior must be preserved
+> 6. **`Simplification Focus:`** — what to simplify, or `N/A — [reason]`
+> 7. `Status:` — `🔴 TODO`
+> 8. **`BDD Verification:`** — concrete scenario check command, or `N/A — [reason]`
+> 9. `Advanced Test Verification:` — command or `N/A — [reason]`
+> 10. `Runtime Verification:` — command or `N/A — [reason]`
+>
+> **Template for every task block:**
+>
+> ```markdown
+> ### Task X.Y: [Name]
+>
+> > **Context:** [why]
+> > **Verification:** [how]
+> > **Scenario Coverage:** [feature/scenario or N/A with reason]
+>
+> - **Loop Type:** `BDD+TDD` or `TDD-only`
+> - **Behavioral Contract:** `Preserve existing behavior` or `[change]`
+> - **Simplification Focus:** `[what]` or `N/A — [reason]`
+> - **Status:** 🔴 TODO
+> - [ ] Step 1: ...
+> - [ ] BDD Verification: [command or N/A — reason]
+> - [ ] Advanced Test Verification: [command or N/A — reason]
+> - [ ] Runtime Verification: [command or N/A — reason]
+> ```
+
+**Task Quality Checklist (verify EVERY task before writing):**
+
+- [ ] **ALL 10 required fields present** (Context, Verification, Scenario Coverage, Loop Type, Behavioral Contract, Simplification Focus, Status, BDD Verification, Advanced Test Verification, Runtime Verification)
+- [ ] **Simplification Focus** is filled in (not missing) — this is the #1 field pb-improve forgets
+- [ ] **BDD Verification** is filled in (not missing) — this is the #2 field pb-improve forgets
 - [ ] Each BDD+TDD task maps to ONE scenario
 - [ ] RED evidence is required (failing output captured)
 - [ ] GREEN evidence is required (passing output captured)
 - [ ] No task can be marked done without GREEN evidence
 - [ ] Tasks are ordered by dependency across findings, not just within findings
+- [ ] Run `uv run pb-spec validate --plan <spec-dir>` before finishing to catch missing fields
 
 Finish by writing `specs/README.md` with the consolidated spec entry:
 

skills/pb-improve/references/plan-template.md

@@ -169,10 +169,22 @@ For the human/agent who owns this code after the change lands:
 
 ## tasks.md Template
 
-> **CRITICAL:** Every task block MUST include all 10 required fields or pb-build validation will fail.
-> Required fields: `Context:`, `Verification:`, `Scenario Coverage:`, `Loop Type:`,
-> `Behavioral Contract:`, `Simplification Focus:`, `Status:`, `BDD Verification:`,
-> `Advanced Test Verification:`, `Runtime Verification:`
+> **⚠️ CRITICAL — pb-build REJECTS tasks.md if ANY of these 10 fields is missing:**
+>
+> | # | Field | Common Mistake |
+> |---|-------|----------------|
+> | 1 | `Context:` | — |
+> | 2 | `Verification:` | — |
+> | 3 | `Scenario Coverage:` | — |
+> | 4 | `Loop Type:` | — |
+> | 5 | `Behavioral Contract:` | — |
+> | 6 | **`Simplification Focus:`** | **#1 forgotten field** — always add it |
+> | 7 | `Status:` | — |
+> | 8 | **`BDD Verification:`** | **#2 forgotten field** — always add it |
+> | 9 | `Advanced Test Verification:` | — |
+> | 10 | `Runtime Verification:` | — |
+>
+> **Before writing tasks.md, verify each task block has ALL 10 fields.**
 
 ```markdown
 # <Feature Name> — Tasks

skills/pb-plan/SKILL.md

@@ -285,7 +285,7 @@ Write a **compact** design doc to `specs/<spec-dir>/design.md`. Only include sec
 
 > Map critical business flows from Given-When-Then to Mermaid state diagrams. Gherkin is essentially state transitions: `Given` (initial state) → `When` (triggering event) → `Then` (result state).
 
-```mermaid
+```
 stateDiagram-v2
     [*] --> InitialState : Given [precondition]
     InitialState --> ActionState : When [action/event]

src/pb_spec/config.py

@@ -4,6 +4,7 @@
 
 import logging
 import os
+import threading
 from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
@@ -31,24 +32,29 @@ class TimeoutConfig:
 
 
 _timeout_config: TimeoutConfig | None = None
+_config_lock = threading.Lock()
 
 
 def get_timeout_config() -> TimeoutConfig:
     """Get timeout configuration from environment variables with defaults.
 
-    Cached after first call. Call _reset_timeout_config_cache() to refresh.
+    Cached after first call with thread-safe double-checked locking.
+    Call _reset_timeout_config_cache() to refresh.
     """
     global _timeout_config
     if _timeout_config is None:
-        _timeout_config = TimeoutConfig(
-            git_ls_files=_parse_int_env("PB_SPEC_GIT_TIMEOUT", 60),
-            rumdl_check=_parse_int_env("PB_SPEC_RUMDL_CHECK_TIMEOUT", 10),
-            rumdl_format=_parse_int_env("PB_SPEC_RUMDL_FORMAT_TIMEOUT", 30),
-        )
+        with _config_lock:
+            if _timeout_config is None:
+                _timeout_config = TimeoutConfig(
+                    git_ls_files=_parse_int_env("PB_SPEC_GIT_TIMEOUT", 60),
+                    rumdl_check=_parse_int_env("PB_SPEC_RUMDL_CHECK_TIMEOUT", 10),
+                    rumdl_format=_parse_int_env("PB_SPEC_RUMDL_FORMAT_TIMEOUT", 30),
+                )
     return _timeout_config
 
 
 def _reset_timeout_config_cache() -> None:
     """Reset the cached config. For testing only."""
     global _timeout_config
-    _timeout_config = None
+    with _config_lock:
+        _timeout_config = None

src/pb_spec/validation/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pb_spec.validation.build import validate_build, validate_task
+from pb_spec.validation.io import read_file_content, read_spec_file
 from pb_spec.validation.parser import (
     ALLOWED_LOOP_TYPES,
     ALLOWED_TASK_STATUSES,
@@ -21,11 +22,7 @@
     validate_contract_blocks,
 )
 from pb_spec.validation.plan import (
-    _CONTRACT_CONFIG,
-    _FULL_MODE_REQUIRED,
-    _LIGHTWEIGHT_MODE_REQUIRED,
-    _NA_REASON_FIELDS,
-    _TASK_REQUIRED_FIELDS,
+    _load_contract_config,
     validate_plan,
 )
 from pb_spec.validation.result import (
@@ -54,12 +51,9 @@
     "ValidationError",
     "ValidationMode",
     "ValidationResult",
-    "_CONTRACT_CONFIG",
-    "_FULL_MODE_REQUIRED",
-    "_LIGHTWEIGHT_MODE_REQUIRED",
-    "_NA_REASON_FIELDS",
-    "_TASK_REQUIRED_FIELDS",
     "make_validation_error",
+    "read_file_content",
+    "read_spec_file",
     "validate_build",
     "validate_plan",
     "validate_task",
@@ -70,4 +64,5 @@
     "required_sections_for_contract_block",
     "task_display_name",
     "validate_contract_blocks",
+    "_load_contract_config",
 ]

src/pb_spec/validation/build.py

@@ -7,13 +7,14 @@
 
 from pb_spec.exceptions import FileReadError
 from pb_spec.git_utils import get_git_modified_files
+from pb_spec.validation.io import read_file_content, read_spec_file
 from pb_spec.validation.parser import (
     TASK_CHECKBOX_RE,
     UNCHECKED_TASK_CHECKBOX_RE,
+    TaskBlock,
     parse_task_blocks,
     task_display_name,
 )
-from pb_spec.validation.plan import read_file_content, read_spec_file
 from pb_spec.validation.result import (
     ErrorSeverity,
     ValidationError,
@@ -51,23 +52,24 @@ def validate_feature_scenarios(spec_dir: Path) -> list[ValidationError]:
     return errors
 
 
-def run_codebase_scan(mode: ValidationMode) -> ScanResult:
+def run_codebase_scan(mode: ValidationMode, root_dir: Path | str = ".") -> ScanResult:
     """Scan codebase for code quality issues.
 
     Args:
         mode: ValidationMode.TASK for subagent self-check (scoped to git-modified
             files), ValidationMode.BUILD for full scan.
+        root_dir: Root directory to scan. Defaults to current working directory.
 
     Returns:
         Pure ScanResult without side effects. Callers are responsible
         for presenting the results.
     """
     target_files: set[Path] | None = None
     if mode == ValidationMode.TASK:
-        target_files = get_git_modified_files()
+        target_files = get_git_modified_files(root_dir)
 
     scanner = CodeScanner(
-        root_dir=".",
+        root_dir=root_dir,
         check_skipped_tests=True,
         check_not_implemented=True,
         check_todos=True,
@@ -99,7 +101,7 @@ def _scan_result_to_errors(scan_result: ScanResult) -> list[ValidationError]:
     return errors
 
 
-def _validate_task_completion(task_blocks: list, content: str) -> list[ValidationError]:
+def _validate_task_completion(task_blocks: list[TaskBlock], content: str) -> list[ValidationError]:
     """Validate that all tasks are marked DONE with complete steps.
 
     Args:
@@ -176,7 +178,7 @@ def _validate_task_completion(task_blocks: list, content: str) -> list[Validatio
     return errors
 
 
-def _validate_task_completion_warnings(task_blocks: list) -> list[str]:
+def _validate_task_completion_warnings(task_blocks: list[TaskBlock]) -> list[str]:
     """Collect warnings for non-DONE tasks (SKIPPED, OBSOLETE).
 
     Args:
@@ -193,9 +195,9 @@ def _validate_task_completion_warnings(task_blocks: list) -> list[str]:
     return warnings
 
 
-def _validate_codebase_scan() -> list[ValidationError]:
+def _validate_codebase_scan(root_dir: Path | str = ".") -> list[ValidationError]:
     """Run codebase scan and return errors."""
-    scan_result = run_codebase_scan(mode=ValidationMode.BUILD)
+    scan_result = run_codebase_scan(mode=ValidationMode.BUILD, root_dir=root_dir)
     if not scan_result.has_issues:
         return []
 
@@ -231,7 +233,6 @@ def validate_build(spec_dir: Path) -> ValidationResult:
             ],
         )
 
-    tasks_file = spec_dir / "tasks.md"
     content, error_result = read_spec_file(tasks_file)
     if error_result is not None:
         return error_result
@@ -250,19 +251,27 @@ def validate_build(spec_dir: Path) -> ValidationResult:
     task_blocks = parse_task_blocks(content)
     warnings.extend(_validate_task_completion_warnings(task_blocks))
     errors.extend(_validate_task_completion(task_blocks, content))
-    errors.extend(_validate_codebase_scan())
+
+    # Determine project root: spec_dir is typically specs/xxx, so root is two levels up
+    project_root = spec_dir.parent.parent if spec_dir.parent.name == "specs" else spec_dir.parent
+    errors.extend(_validate_codebase_scan(root_dir=project_root))
+
     errors.extend(validate_feature_scenarios(spec_dir))
 
     return ValidationResult(is_valid=len(errors) == 0, errors=errors, warnings=warnings)
 
 
-def validate_task() -> ValidationResult:
+def validate_task(root_dir: Path | str = ".") -> ValidationResult:
     """Subagent self-check before signaling READY_FOR_EVAL.
 
-    Returns a pure ValidationResult without side effects.
-    Callers are responsible for presenting the results.
+    Args:
+        root_dir: Root directory to scan. Defaults to current working directory.
+
+    Returns:
+        A pure ValidationResult without side effects.
+        Callers are responsible for presenting the results.
     """
-    scan_result = run_codebase_scan(mode=ValidationMode.TASK)
+    scan_result = run_codebase_scan(mode=ValidationMode.TASK, root_dir=root_dir)
     if not scan_result.has_issues:
         return ValidationResult(is_valid=True)
 

src/pb_spec/validation/io.py

@@ -0,0 +1,41 @@
+"""File I/O utilities for validation module."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pb_spec.exceptions import FileReadError
+from pb_spec.validation.result import (
+    ErrorSeverity,
+    ValidationResult,
+    make_validation_error,
+)
+
+
+def read_file_content(file_path: Path) -> str:
+    """Read file content with error handling.
+
+    Raises:
+        FileReadError: If the file cannot be read.
+    """
+    try:
+        return file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        raise FileReadError(f"Cannot read file {file_path}: {e}") from e
+
+
+def read_spec_file(file_path: Path) -> tuple[str, None] | tuple[None, ValidationResult]:
+    """Read a spec file, returning (content, None) on success or (None, error_result) on failure."""
+    try:
+        return read_file_content(file_path), None
+    except FileReadError as e:
+        return None, ValidationResult(
+            is_valid=False,
+            errors=[
+                make_validation_error(
+                    message=str(e),
+                    file_path=str(file_path),
+                    severity=ErrorSeverity.CRITICAL,
+                )
+            ],
+        )