guardian-framework 0.1.147 → 0.1.149

package/README.md

@@ -41,15 +41,24 @@ Enrich Module Docs     ←─ agent fills DDD content from exploration
 ADRs, Diagrams, Specs  ←─ you challenge decisions, finalize
     │
     ▼
-Roadmap Plan           ←─ you adopt phases, set priorities
+Roadmap Plan           ←─ one module per phase (Phase 0 = bootstrap)
     │
     ▼
-Epic Execution         ─── agents implement, you review PRs
+Epic Execution         ─── one branch + one PR per epic, local CI per issue
+    │                  └─ parallel epics: isolated worktrees, contract-freeze gate
+    ▼
+Wiring Check           ─── every module must be INSTALLED in the app shell
     │
     ▼
 Enforcement Pipeline   ─── CI blocks merges on violation
 ```
 
+> New since 0.1.128: exploration is terminal and self-driving, stubs follow the
+> detected language, epics ship as one PR, parallel epics are gated on frozen
+> contracts, and five enforcement controls make "can this actually block a
+> merge?" a machine-readable answer. See
+> [manual §30–39](docs/USER_MANUAL.md#30-exploration--roadmap--epic-the-current-pipeline).
+
 ---
 
 ## Walkthrough: From Intent to Enforcement
@@ -207,30 +216,42 @@ If someone (or an AI) adds a dependency from the domain layer to infrastructure,
 ## Quick Start
 
 ```bash
-# 1. Scaffold
+# 1. Init (installs .pi/ — prompts, extensions, validators)
 cd your-project
 npx guardian-framework init
 
-# 2. Explore (iterative — review, refine, repeat)
-/domain --explore "your business intent"   # agent classifies core/supporting/generic — YOU gate it
-/domain --validate <session-id>            # structural + UL + ADR-008 depth rules
-
-# 3. Generate architecture from exploration (module docs gain Modeling Depth + invariants)
-/domain --architect-scaffold <session-id>
+# 2. Explore — the agent classifies core/supporting/generic; YOU gate the depth.
+#    Delivers the full protocol in one message, then STOPS. Resume with --resume.
+/domain --explore "your business intent"
 
-# 4. Enrich module docs with full DDD content
-/domain --enrich <session-id>
+# 3. Validate the analysis against the files that were written (drift gate)
+guardian domain validate <session-id>
 
-# 5. Review and refine (ADRs, diagrams, modules — human-in-the-loop)
+# 4. Create module docs — never overwrites existing ones
+guardian domain scaffold --session <session-id>
+guardian domain enrich   --session <session-id>   # full DDD content, session-scoped
 
-# 6. Adopt the roadmap
+# 5. Roadmap — ONE module per phase, Phase 0 is Project Bootstrap
 /architect --roadmap
-/architect --adopt-roadmap
 
-# 6. Execute
-/architect --phase "Phase 0"
+# 6. Execute — epic mode is the default: one branch, local CI per issue, one PR
+/architect --epic "Policy Engine"
+
+#    ...or run several in parallel (gated on frozen contracts)
+bash .pi/scripts/epic-registry.sh freeze "Policy Engine" --frozen
+bash .pi/scripts/epic-parallel.sh "Policy Engine"     # isolated worktree
+
+# 7. Prove it is actually wired, not just implemented
+bash .pi/scripts/check_composition_root.sh
+bash .pi/scripts/validate-wiring-claims.sh
+
+# 8. See what can block a merge
+bash .pi/scripts/validate-guards.sh --list
 ```
 
+Minimal project bootstrap is the default (shared kernel only). Add bounded-context
+folders with `--withContexts`, or let the roadmap phases create them.
+
 ---
 
 ## What This Means
@@ -248,6 +269,8 @@ Guardian was proven on [Rigorix](https://github.com/arman-jalili/rigorix-oss): 1
 | | |
 |---|---|
 | **User Manual** | [docs/USER_MANUAL.md](docs/USER_MANUAL.md) — every workflow, command, and extension |
+| **Pipeline (0.1.148)** | [manual §30–39](docs/USER_MANUAL.md#30-exploration--roadmap--epic-the-current-pipeline) — explore → roadmap → epic → wiring → controls |
+| **Design note** | [docs/design/exploration-and-roadmap-pipeline.md](docs/design/exploration-and-roadmap-pipeline.md) |
 | **Proven on** | [Rigorix](https://github.com/arman-jalili/rigorix-oss) — 146K LOC Rust, 30 modules |
 | **Source** | [github.com/arman-jalili/guardian-framework](https://github.com/arman-jalili/guardian-framework) |
 | **License** | MIT |

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.147", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.149", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/dist/exports.js

@@ -1991,7 +1991,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.147", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.149", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.147",
+	"version": "0.1.149",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/architecture/wiring-claims.tsv

@@ -0,0 +1,13 @@
+# Wiring claims (ADR-009): make "it is wired" claims checkable.
+#
+# validate-wiring-claims.sh fails both ways:
+#   * a CONFIRMED row whose evidence disappears — the wiring was removed and
+#     the doc still claims it;
+#   * a GAP row whose evidence appears (promote it) or whose module doc stops
+#     declaring the gap.
+#
+# Columns (tab-separated): claim  module  status  evidence  note
+#   status    CONFIRMED | GAP
+#   evidence  path or path:symbol that proves (or disproves) the wiring
+#
+# claim	module	status	evidence	note

package/templates/pi/coverage-floors.tsv

@@ -0,0 +1,12 @@
+# Coverage floors (ADR-010) — a floor is a RATCHET.
+#
+# Raise a floor when a layer improves; never lower one to make a build pass.
+# validate-coverage-floors.sh fails when a floor decreases or a layer
+# disappears, compared against the merge base.
+#
+# Columns (tab-separated): layer  floor  measured  target  note
+#   floor     the value that gates (ratchet; never decreases)
+#   measured  last measured coverage (informational)
+#   target    the roadmap criterion (gap printed when unmet)
+#
+# layer	floor	measured	target	note

package/templates/pi/extensions/architect.ts

@@ -635,7 +635,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 								items: existingIssues,
 								steps: [
 									{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-									{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
+									{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring", "guards", "drift", "shell", "claims", "floors"] } },
 									{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 									{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 								],
@@ -697,7 +697,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 							items,
 							steps: [
 								{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-								{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
+								{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring", "guards", "drift", "shell", "claims", "floors"] } },
 								{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 								{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 							],
@@ -964,7 +964,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 					items,
 					steps: [
 						{ name: "implement", prompt: ".pi/prompts/issue-implementation-series.md", acceptance: { type: "validator", validators: ["ci"] } },
-						{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] } },
+						{ name: "validate", acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring", "guards", "drift", "shell", "claims", "floors"] } },
 						{ name: "create-mr", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "none" } },
 						{ name: "merge", prompt: ".pi/prompts/epic-closeout.md", acceptance: { type: "validator", validators: ["ci", "canonical"] } },
 					],

package/templates/pi/extensions/pipeline.ts

@@ -45,6 +45,12 @@ const VALIDATOR_SCRIPTS: Record<string, string> = {
 	integration: ".pi/scripts/validate-integration.sh",
 	// ADR-009: implemented modules must be INSTALLED in the composition root
 	wiring: ".pi/scripts/check_composition_root.sh",
+	// ADR-010: controls that make the other controls enforceable
+	guards: ".pi/scripts/validate-guards.sh",
+	drift: ".pi/scripts/validate-script-drift.sh",
+	claims: ".pi/scripts/validate-wiring-claims.sh",
+	floors: ".pi/scripts/validate-coverage-floors.sh",
+	shell: ".pi/scripts/validate-shell-exit-status.sh",
 };
 
 // ── Helpers ──
@@ -1445,7 +1451,7 @@ function buildSteps(stepNames: string[]): StepConfig[] {
 		},
 		validate: {
 			name: "validate",
-			acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring"] },
+			acceptance: { type: "validator", validators: ["ci", "tests", "security", "wiring", "guards", "drift", "shell", "claims", "floors"] },
 		},
 		"create-mr": {
 			name: "create-mr",

package/templates/pi/guards.tsv

@@ -0,0 +1,33 @@
+# Self-owned guard registry (ADR-010).
+#
+# Every root .pi/scripts/validate-*.sh MUST appear here. `validate-guards.sh`
+# fails when a guard exists but is unclassified, so a new guard cannot be
+# silently left un-gated.
+#
+# Columns (tab-separated):
+#   guard      path to the guard script, relative to the repo root
+#   class      the pattern class it owns
+#   tier       gating | advisory
+#              gating   = a non-zero exit fails a mandatory path
+#              advisory = informational; it does not stop a merge
+#   run_here   yes | no   (yes = `validate-guards.sh --run` executes it)
+#   owner      who is accountable for the class
+#   notes      how it gates / what it does
+#
+# guard	class	tier	run_here	owner	notes
+.pi/scripts/validate-guards.sh	guards	advisory	no	architecture	meta: registry integrity; --run executes the gating set
+.pi/scripts/validate-script-drift.sh	script-drift	gating	yes	architecture	mirrored .pi/scripts differ and are unrecorded
+.pi/scripts/validate-wiring-claims.sh	wiring-claims	gating	yes	architecture	wiring claims need live evidence; gaps must stay documented
+.pi/scripts/validate-coverage-floors.sh	coverage-floors	gating	yes	quality	a coverage floor may not be lowered or removed
+.pi/scripts/validate-shell-exit-status.sh	shell-exit	gating	yes	quality	arithmetic statement returns 1 on a passing path
+.pi/scripts/validate-architecture.sh	architecture	gating	yes	architecture	dispatches the per-language architecture checks
+.pi/scripts/validate-canonical.sh	canonical	gating	yes	architecture	canonical headers and references resolve
+.pi/scripts/validate-tests.sh	tests	gating	yes	quality	tests exist, run and cover the contract
+.pi/scripts/validate-security.sh	security	gating	yes	security	secret scan and unsafe-pattern gates
+.pi/scripts/validate-ci.sh	ci	gating	yes	platform	CI pipeline matches the blueprint
+.pi/scripts/validate-integration.sh	integration	gating	yes	architecture	components integrate through their declared seams
+.pi/scripts/validate-operations.sh	operations	gating	yes	platform	readiness: observability, error handling, cancellation
+.pi/scripts/validate-runtime-wiring.sh	runtime-wiring	gating	yes	architecture	implemented modules are reachable at runtime
+.pi/scripts/validate-architecture-readiness.sh	readiness	advisory	no	architecture	architecture docs are complete enough to implement
+.pi/scripts/validate-exploration-depth.sh	exploration-depth	advisory	no	architecture	domain exploration depth is sufficient
+.pi/scripts/validate-ubiquitous-language.sh	ubiquitous-language	gating	yes	architecture	code and docs share the canonical glossary

package/templates/pi/mirrors.tsv

@@ -0,0 +1,9 @@
+# Extra trees compared by validate-script-drift.sh (one path per line).
+#
+Each path is a directory containing a `scripts/` subtree whose files are
+compared against every other tree by path. The repo root .pi/ and every
+immediate subdirectory carrying .pi/scripts are always compared; list here
+trees that are NOT in that shape.
+#
+This repo ships a canonical tree (templates/pi) and mirrors it to .pi/.
+templates/pi

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-11-07T13:34:25Z",
+  "timestamp": "2026-11-07T14:25:39Z",
   "mode": "all",
   "stages_run": [],
   "summary": {
@@ -8,7 +8,7 @@
     "failed": 1,
     "skipped": 12
   },
-  "duration_seconds": 0,
+  "duration_seconds": 1,
   "results": [
   {
     "name": "check_mr_traceability.sh",

package/templates/pi/script-drift-allow.tsv

@@ -0,0 +1,13 @@
+# Recorded per-tree differences for mirrored .pi/scripts (ADR-010).
+#
+# validate-script-drift.sh fails when a file mirrored across trees (the repo
+# root plus any subdirectory carrying a .pi/ directory) differs and is NOT
+# matched by a pattern here.
+#
+# Columns (tab-separated): pattern  trees  reason
+#   pattern  glob matched against the path relative to <tree>/.pi/scripts
+#   trees    which trees carry the file (informational)
+#   reason   why the difference is tolerated
+#
+# pattern	trees	reason
+ci/stage_security.sh	templates/pi,.pi	guardian generates a project-specific security stage (secret scan + dep audit) into .pi/scripts/ci; the template carries the dispatcher stub, same as stage_build.sh and stage_test.sh

package/templates/pi/scripts/ci/check_architecture_conformance.sh

@@ -149,7 +149,7 @@ check_tenant_isolation() {
                     has_tenant_filter=true
                 fi
                 if [[ "$has_tenant_filter" == "false" ]]; then
-                    ((violations++))
+                    violations=$((violations + 1))
                     log_fail "$check_name" "Model $(basename "$model_file") has tenant_id but no tenant-scoped queries"
                 fi
             fi
@@ -521,7 +521,7 @@ check_runtime_baseline() {
         while IFS= read -r var; do
             var_name=$(echo "$var" | cut -d= -f1)
             if [[ -z "${!var_name:-}" ]]; then
-                ((unbound++))
+                unbound=$((unbound + 1))
             fi
         done < <(grep -v "^#" .env.example 2>/dev/null | grep "=" || true)
         if [[ $unbound -eq 0 ]]; then
@@ -603,7 +603,7 @@ check_arch_sanity() {
     local orphaned_imports=0
     for f in $(find . -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" 2>/dev/null | head -30); do
         if grep -qE "^import.*UNUSED|^from.*UNUSED" "$f" 2>/dev/null; then
-            ((orphaned_imports++))
+            orphaned_imports=$((orphaned_imports + 1))
         fi
     done
     if [[ $orphaned_imports -gt 0 ]]; then
@@ -636,7 +636,7 @@ check_arch_sanity() {
                 example_val=$(grep "^${var_name}=" ".env.example" | cut -d= -f2-)
                 actual_val=$(grep "^${var_name}=" ".env" | cut -d= -f2-)
                 if [[ "$example_val" == "$actual_val" ]]; then
-                    ((collisions++))
+                    collisions=$((collisions + 1))
                 fi
             fi
         done < <(grep -v "^#" .env.example 2>/dev/null | grep "=" || true)
@@ -683,13 +683,13 @@ check_import_boundaries() {
             [[ -f "$file" ]] || continue
             if [[ "$layer_dir" == *"domain" ]]; then
                 if grep -qE "from.*infrastructure|from.*api|from.*interfaces|import.*infrastructure|import.*api|import.*interfaces" "$file" 2>/dev/null; then
-                    ((violations++))
+                    violations=$((violations + 1))
                     log_fail "$check_name" "Domain layer imports from outer layer in $(basename "$file")"
                 fi
             fi
             if [[ "$layer_dir" == *"application" ]]; then
                 if grep -qE "from.*api|from.*interfaces|import.*api|import.*interfaces" "$file" 2>/dev/null; then
-                    ((violations++))
+                    violations=$((violations + 1))
                     log_fail "$check_name" "Application layer imports from api/interfaces in $(basename "$file")"
                 fi
             fi

package/templates/pi/scripts/ci/run_hardening_stages.sh

@@ -102,14 +102,14 @@ run_stage() {
         return 0
     fi
 
-    ((TOTAL_STAGES++))
+    TOTAL_STAGES=$((TOTAL_STAGES + 1))
 
     # Check conditional
     case "$conditional" in
         main_only)
             if [[ "${CI_COMMIT_BRANCH:-}" != "main" && "${GITHUB_REF_NAME:-}" != "main" ]]; then
                 log_stage_skip "$stage_name" "Not on main branch"
-                ((SKIPPED_STAGES++))
+                SKIPPED_STAGES=$((SKIPPED_STAGES + 1))
                 return 0
             fi
             ;;
@@ -122,14 +122,14 @@ run_stage() {
             fi
             if [[ "$has_migration" == "false" ]]; then
                 log_stage_skip "$stage_name" "No migration changes detected"
-                ((SKIPPED_STAGES++))
+                SKIPPED_STAGES=$((SKIPPED_STAGES + 1))
                 return 0
             fi
             ;;
         sonar_required)
             if [[ -z "${SONAR_TOKEN:-}" || -z "${SONAR_HOST_URL:-}" ]]; then
                 log_stage_skip "$stage_name" "SONAR_TOKEN or SONAR_HOST_URL not set"
-                ((SKIPPED_STAGES++))
+                SKIPPED_STAGES=$((SKIPPED_STAGES + 1))
                 return 0
             fi
             ;;
@@ -139,21 +139,21 @@ run_stage() {
 
     if [[ ! -f "$stage_script" ]]; then
         log_stage_skip "$stage_name" "Script not found: $stage_script"
-        ((SKIPPED_STAGES++))
+        SKIPPED_STAGES=$((SKIPPED_STAGES + 1))
         return 0
     fi
 
     local output
     if output=$(bash "$stage_script" 2>&1); then
         log_stage_pass "$stage_name"
-        ((PASSED_STAGES++))
+        PASSED_STAGES=$((PASSED_STAGES + 1))
         STAGE_RESULTS+=("PASS:$stage_name")
         if [[ "$VERBOSE" == "true" ]]; then
             echo "$output"
         fi
     else
         log_stage_fail "$stage_name" "$output"
-        ((FAILED_STAGES++))
+        FAILED_STAGES=$((FAILED_STAGES + 1))
         STAGE_RESULTS+=("FAIL:$stage_name:$(echo "$output" | head -5)")
     fi
 }

package/templates/pi/scripts/ci/run_preflight.sh

@@ -65,8 +65,8 @@ log_pass() {
     if [[ "$JSON" == "false" ]]; then
         echo -e "  ${GREEN}[PASS]${NC} $1 (${2}s)"
     fi
-    ((PASSED++))
-    ((TOTAL++))
+    PASSED=$((PASSED + 1))
+    TOTAL=$((TOTAL + 1))
     RESULTS+=("{\"name\": \"$1\", \"status\": \"pass\", \"message\": \"\", \"duration\": $2}")
 }
 
@@ -74,8 +74,8 @@ log_fail() {
     if [[ "$JSON" == "false" ]]; then
         echo -e "  ${RED}[FAIL]${NC} $1 — $2 (${3}s)"
     fi
-    ((FAILED++))
-    ((TOTAL++))
+    FAILED=$((FAILED + 1))
+    TOTAL=$((TOTAL + 1))
     RESULTS+=("{\"name\": \"$1\", \"status\": \"fail\", \"message\": \"$2\", \"duration\": $3}")
 }
 
@@ -83,8 +83,8 @@ log_skip() {
     if [[ "$JSON" == "false" ]]; then
         echo -e "  ${YELLOW}[SKIP]${NC} $1 — $2"
     fi
-    ((SKIPPED++))
-    ((TOTAL++))
+    SKIPPED=$((SKIPPED + 1))
+    TOTAL=$((TOTAL + 1))
     RESULTS+=("{\"name\": \"$1\", \"status\": \"skip\", \"message\": \"$2\", \"duration\": 0}")
 }
 

package/templates/pi/scripts/ci/stage_docs_policy.sh

@@ -13,8 +13,8 @@ ARCH_DIR="${PI_DIR}/architecture"
 PASS=0
 FAIL=0
 
-log_pass() { echo "  ✓ PASS: $1"; ((PASS++)); }
-log_fail() { echo "  ✗ FAIL: $1 — $2"; ((FAIL++)); }
+log_pass() { echo "  ✓ PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  ✗ FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
 
 echo "  Checking MR traceability..."
 
@@ -26,7 +26,7 @@ if command -v git &>/dev/null; then
         files_without_ref=0
         while IFS= read -r file; do
             if ! grep -q "Canonical Reference\|canonical.*reference" "$file" 2>/dev/null; then
-                ((files_without_ref++))
+                files_without_ref=$((files_without_ref + 1))
                 log_fail "MR traceability" "${file} missing canonical reference to architecture"
             fi
         done <<< "$changed_files"

package/templates/pi/scripts/ci/stage_lint.sh

@@ -11,8 +11,8 @@ set -euo pipefail
 FAIL=0
 PASS=0
 
-log_pass() { echo "  ✓ PASS: $1"; ((PASS++)); }
-log_fail() { echo "  ✗ FAIL: $1 — $2"; ((FAIL++)); }
+log_pass() { echo "  ✓ PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  ✗ FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
 
 echo "  Running lint checks..."
 

package/templates/pi/scripts/ci/stage_remaining.sh

@@ -13,8 +13,8 @@ PI_DIR=".pi"
 FAIL=0
 PASS=0
 
-log_pass() { echo "  ✓ PASS: $1"; ((PASS++)); }
-log_fail() { echo "  ✗ FAIL: $1 — $2"; ((FAIL++)); }
+log_pass() { echo "  ✓ PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  ✗ FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
 
 STAGE="${1:-all}"
 
@@ -69,7 +69,7 @@ run_stage_7_security() {
         local secrets_found=0
         for pattern in "sk-[A-Za-z0-9]{32,}" "ghp_[A-Za-z0-9]{36}" "AKIA[0-9A-Z]{16}" "BEGIN (RSA |EC )?PRIVATE KEY"; do
             if grep -rE "$pattern" . --include="*.py" --include="*.ts" --include="*.env" 2>/dev/null | grep -v ".git" | grep -v "node_modules" | head -1 | grep -q .; then
-                ((secrets_found++))
+                secrets_found=$((secrets_found + 1))
                 log_fail "secret scan" "Potential secret pattern detected: $pattern"
             fi
         done

package/templates/pi/scripts/ci/stage_static_analysis.sh

@@ -12,8 +12,8 @@ set -euo pipefail
 FAIL=0
 PASS=0
 
-log_pass() { echo "  ✓ PASS: $1"; ((PASS++)); }
-log_fail() { echo "  ✗ FAIL: $1 — $2"; ((FAIL++)); }
+log_pass() { echo "  ✓ PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  ✗ FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
 
 echo "  Running static analysis..."
 
@@ -61,7 +61,7 @@ else
     if [[ -d "app/domain" ]]; then
         while IFS= read -r file; do
             if grep -qE "from.*infrastructure|from.*api|import.*infrastructure" "$file" 2>/dev/null; then
-                ((violations++))
+                violations=$((violations + 1))
                 log_fail "import boundary" "$(basename "$file") imports from infrastructure/api"
             fi
         done < <(find app/domain -name "*.py" 2>/dev/null)
@@ -93,7 +93,7 @@ if [[ -f ".env.example" && -f ".env" ]]; then
             example_val=$(grep "^${var_name}=" ".env.example" 2>/dev/null | cut -d= -f2-)
             actual_val=$(grep "^${var_name}=" ".env" 2>/dev/null | cut -d= -f2-)
             if [[ "$example_val" == "$actual_val" && -n "$example_val" ]]; then
-                ((collisions++))
+                collisions=$((collisions + 1))
                 log_fail "env collision" "${var_name} in .env matches .env.example value"
             fi
         fi

package/templates/pi/scripts/ci/stage_unit.sh

@@ -14,8 +14,8 @@ FAIL=0
 PASS=0
 COVERAGE_PCT=0
 
-log_pass() { echo "  ✓ PASS: $1"; ((PASS++)); }
-log_fail() { echo "  ✗ FAIL: $1 — $2"; ((FAIL++)); }
+log_pass() { echo "  ✓ PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  ✗ FAIL: $1 — $2"; FAIL=$((FAIL + 1)); }
 
 echo "  Running unit tests..."
 

package/templates/pi/scripts/ci/validate_agent_output.sh

@@ -48,13 +48,13 @@ check_section_present() {
     local section="$1"
     if echo "$CONTENT" | grep -qi "$section"; then
         RESULTS+=("{\"check\": \"$section\", \"status\": \"pass\"}")
-        ((CHECKS_PASSED++))
+        CHECKS_PASSED=$((CHECKS_PASSED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${GREEN}✓${NC} Section present: $section"
         fi
     else
         RESULTS+=("{\"check\": \"$section\", \"status\": \"fail\", \"message\": \"Section '$section' not found\"}")
-        ((CHECKS_FAILED++))
+        CHECKS_FAILED=$((CHECKS_FAILED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${RED}✗${NC} Missing section: $section"
         fi
@@ -73,20 +73,20 @@ check_no_contradictions() {
             must_count=$(echo "$CONTENT" | grep -ci "${topic}.*must " || echo 0)
             must_not_count=$(echo "$CONTENT" | grep -ci "${topic}.*must not\|${topic}.*must not " || echo 0)
             if [[ $must_count -gt 0 && $must_not_count -gt 0 ]]; then
-                ((contradictions++))
+                contradictions=$((contradictions + 1))
             fi
         fi
     done < <(echo "$CONTENT" | grep -E "^\s*[-*]\s+\*\*" || true)
 
     if [[ $contradictions -eq 0 ]]; then
         RESULTS+=("{\"check\": \"no_contradictions\", \"status\": \"pass\"}")
-        ((CHECKS_PASSED++))
+        CHECKS_PASSED=$((CHECKS_PASSED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${GREEN}✓${NC} No internal contradictions"
         fi
     else
         RESULTS+=("{\"check\": \"no_contradictions\", \"status\": \"fail\", \"message\": \"Found $contradictions contradictions\"}")
-        ((CHECKS_FAILED++))
+        CHECKS_FAILED=$((CHECKS_FAILED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${RED}✗${NC} Found $contradictions contradictions"
         fi
@@ -100,13 +100,13 @@ check_decision_consistency() {
 
     if [[ $decisions -eq 0 ]] || [[ $evidence -gt 0 ]]; then
         RESULTS+=("{\"check\": \"decision_consistency\", \"status\": \"pass\"}")
-        ((CHECKS_PASSED++))
+        CHECKS_PASSED=$((CHECKS_PASSED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${GREEN}✓${NC} Decision consistency"
         fi
     else
         RESULTS+=("{\"check\": \"decision_consistency\", \"status\": \"fail\", \"message\": \"Decisions without supporting evidence\"}")
-        ((CHECKS_FAILED++))
+        CHECKS_FAILED=$((CHECKS_FAILED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${RED}✗${NC} Decisions without supporting evidence"
         fi
@@ -120,13 +120,13 @@ check_acceptance_criteria() {
 
     if [[ $has_criteria -gt 0 ]]; then
         RESULTS+=("{\"check\": \"acceptance_criteria\", \"status\": \"pass\"}")
-        ((CHECKS_PASSED++))
+        CHECKS_PASSED=$((CHECKS_PASSED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${GREEN}✓${NC} Acceptance criteria present"
         fi
     else
         RESULTS+=("{\"check\": \"acceptance_criteria\", \"status\": \"fail\", \"message\": \"No acceptance criteria found\"}")
-        ((CHECKS_FAILED++))
+        CHECKS_FAILED=$((CHECKS_FAILED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${RED}✗${NC} No acceptance criteria found"
         fi
@@ -138,13 +138,13 @@ check_canonical_references() {
 
     if [[ $has_refs -gt 0 ]]; then
         RESULTS+=("{\"check\": \"canonical_references\", \"status\": \"pass\"}")
-        ((CHECKS_PASSED++))
+        CHECKS_PASSED=$((CHECKS_PASSED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${GREEN}✓${NC} Canonical references present"
         fi
     else
         RESULTS+=("{\"check\": \"canonical_references\", \"status\": \"fail\", \"message\": \"No canonical references found\"}")
-        ((CHECKS_FAILED++))
+        CHECKS_FAILED=$((CHECKS_FAILED + 1))
         if [[ "$JSON" == "false" ]]; then
             echo -e "  ${RED}✗${NC} No canonical references found"
         fi

package/templates/pi/scripts/languages/python/validate-canonical.sh

@@ -55,7 +55,7 @@ if [ -d ".pi/architecture/modules" ]; then
             if [ -n "$impl_path" ]; then
                 if [ ! -f "$impl_path" ]; then
                     warn "Architecture references $impl_path but file does not exist"
-                    ((MISSING++))
+                    MISSING=$((MISSING + 1))
                 fi
             fi
         done < <(grep -oE '`[a-z_/]+\.py`' "$module_file" 2>/dev/null || true)
@@ -76,9 +76,9 @@ INIT_DOCS=0
 INIT_WITHOUT_DOCS=0
 for init_file in $(find "$SRC_DIR" -name "__init__.py" 2>/dev/null | head -20); do
     if grep -qE '"""|"""' "$init_file" 2>/dev/null; then
-        ((INIT_DOCS++))
+        INIT_DOCS=$((INIT_DOCS + 1))
     else
-        ((INIT_WITHOUT_DOCS++))
+        INIT_WITHOUT_DOCS=$((INIT_WITHOUT_DOCS + 1))
     fi
 done
 if [ "$INIT_DOCS" -gt 0 ]; then