guardian-framework 0.1.146 → 0.1.148

package/dist/cli.js

@@ -3206,7 +3206,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.146", 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.148", 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.146", 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.148", 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.146",
+	"version": "0.1.148",
 	"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

@@ -492,7 +492,7 @@ export default function architectExtension(pi: ExtensionAPI) {
 			const tokens = raw ? parseArgs(raw) : [];
 			if (tokens.length === 0) {
 				ctx.ui.notify(
-					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] [--pr-per epic|issue] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
+					"Usage: /architect [--epic Name] [--tracking-issue N] [--tdd] [--pr-per epic|issue] [--parallel|--worktree] | --roadmap | --phase \"Phase 1\" | --phase-status | --phase-done <N> | --phase-module-done <N> \"Module\" | status | next-epic | abort",
 					"info",
 				);
 				return;
@@ -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"] } },
 							],
@@ -863,6 +863,8 @@ export default function architectExtension(pi: ExtensionAPI) {
 			// legacy per-issue PR flow.
 			const prPerFlag = (findFlag(tokens, "--pr-per") ?? "epic").toLowerCase();
 			const epicPrStrategy: "issue" | "epic" = prPerFlag === "issue" ? "issue" : "epic";
+			const useWorktree = tokens.includes("--worktree");
+			const parallelFlag = tokens.includes("--parallel");
 			try {
 				const epicStatePath = join(ctx.cwd, ".pi", ".guardian-epic-state.json");
 				const st = existsSync(epicStatePath)
@@ -887,6 +889,44 @@ export default function architectExtension(pi: ExtensionAPI) {
 					return;
 				}
 
+				// ── Parallel epics (--parallel / --worktree) ───────────────
+				// One module per worktree keeps parallel epics isolated; the
+				// contract-freeze gate refuses to start before shared contracts
+				// are frozen (epic-parallel.sh exits 2 when blocked).
+				if (parallelFlag || useWorktree) {
+					const reg = join(ctx.cwd, ".pi", "scripts", "epic-registry.sh");
+					if (!existsSync(reg)) {
+						ctx.ui.notify("epic-registry.sh not found — run `guardian update` to install parallel-epic scripts.", "error");
+						return;
+					}
+					const prep = runScript(ctx.cwd, `bash .pi/scripts/epic-parallel.sh "${epicName.replace(/"/g, '\\"')}"`);
+					if (prep.exitCode === 2) {
+						ctx.ui.notify(
+							`Parallel epic blocked: contracts for "${epicName}" are not frozen. Merge the Contract Freeze issue, then: bash .pi/scripts/epic-registry.sh freeze "${epicName}" --frozen`,
+							"error",
+						);
+						return;
+					}
+					if (prep.exitCode !== 0) {
+						ctx.ui.notify(`Worktree preparation failed: ${String(prep.stdout).slice(0, 300)}`, "error");
+						return;
+					}
+					// Record on the epic state so later steps stay consistent.
+					try {
+						const p = join(ctx.cwd, ".pi/.guardian-epic-state.json");
+						const st = existsSync(p) ? (JSON.parse(readFileSync(p, "utf-8")) as Record<string, unknown>) : {};
+						st.parallel = true;
+						st.worktree = String(prep.stdout).match(/worktree:\s*(\S+)/)?.[1] ?? "";
+						writeFileSync(p, JSON.stringify(st, null, 2), "utf-8");
+					} catch {
+						// ignore
+					}
+					ctx.ui.notify(
+						"Parallel epic prepared — worktree + epic branch created (contracts frozen).",
+						"success",
+					);
+				}
+
 				const state = await manager.startEpic(ctx, epicName, trackingIssueId, tddEnabled);
 
 				if (!state?.slices?.length) {
@@ -924,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/epic.ts

@@ -0,0 +1,113 @@
+// Canonical Reference: .pi/architecture/modules/epic-parallel.md#epic-command
+/**
+ * /epic — parallel epic scale-out (companion to /architect --epic).
+ *
+ * One module -> one epic branch -> one worktree -> one PR. The command shares
+ * the same registry + contract-freeze gate as /architect --parallel so both
+ * entry points behave identically.
+ *
+ *   /epic parallel "<Module>"     create worktree + branch (gated)
+ *   /epic freeze "<Module>"       record that contracts are frozen
+ *   /epic status                  list registered epics (all worktrees)
+ *   /epic prompt                  show the scale-out procedure
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type ExtensionContext = { cwd: string; ui: { notify(message: string, level?: string): void } };
+type ExtensionAPI = {
+	registerCommand(
+		name: string,
+		options: { description: string; handler(args: unknown, ctx: ExtensionContext): unknown },
+	): void;
+};
+
+function unquote(s: string): string {
+	return s.trim().replace(/^["']|["']$/g, "");
+}
+
+function run(cwd: string, cmd: string): { code: number; out: string } {
+	try {
+		const out = execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+		return { code: 0, out };
+	} catch (e) {
+		const err = e as { status?: number; stdout?: string; stderr?: string };
+		return { code: err.status ?? 1, out: `${err.stdout ?? ""}${err.stderr ?? ""}` };
+	}
+}
+
+export default function epicExtension(pi: ExtensionAPI) {
+	pi.registerCommand("epic", {
+		description: "Parallel epics: one worktree per module, gated on frozen contracts",
+		handler: async (args: unknown, ctx: ExtensionContext) => {
+			const raw = String(args ?? "").trim();
+			const [action, ...rest] = raw.split(/\s+/);
+			const moduleName = unquote(rest.join(" "));
+
+			if (!action) {
+				ctx.ui.notify(
+					[
+						"Usage:",
+						'  /epic parallel "<Module>"   create worktree + epic branch (requires frozen contracts)',
+						'  /epic freeze "<Module>"     record that shared contracts are frozen',
+						"  /epic status                list registered epics across worktrees",
+						"  /epic prompt                show the scale-out procedure",
+					].join("\n"),
+					"info",
+				);
+				return;
+			}
+
+			if (action === "freeze") {
+				if (!moduleName) {
+					ctx.ui.notify('Usage: /epic freeze "<Module>"', "error");
+					return;
+				}
+				const r = run(ctx.cwd, `bash .pi/scripts/epic-registry.sh freeze "${moduleName}" --frozen`);
+				ctx.ui.notify(r.code === 0 ? `Contracts frozen for "${moduleName}"` : r.out.slice(0, 300), r.code === 0 ? "success" : "error");
+				return;
+			}
+
+			if (action === "parallel") {
+				if (!moduleName) {
+					ctx.ui.notify('Usage: /epic parallel "<Module>"', "error");
+					return;
+				}
+				const r = run(ctx.cwd, `bash .pi/scripts/epic-parallel.sh "${moduleName}"`);
+				if (r.code === 2) {
+					ctx.ui.notify(
+						`Blocked: contracts for "${moduleName}" are not frozen. Merge the Contract Freeze issue, then /epic freeze "${moduleName}".`,
+						"error",
+					);
+					return;
+				}
+				ctx.ui.notify(
+					r.code === 0
+						? `Worktree ready for "${moduleName}". Next: cd into it and run /architect --epic "${moduleName}"`
+						: r.out.slice(0, 400),
+					r.code === 0 ? "success" : "error",
+				);
+				return;
+			}
+
+			if (action === "status") {
+				const r = run(ctx.cwd, "bash .pi/scripts/epic-registry.sh list");
+				ctx.ui.notify(r.out || "(no epics registered)", "info");
+				return;
+			}
+
+			if (action === "prompt") {
+				const p = join(ctx.cwd, ".pi", "prompts", "epic-parallel.md");
+				if (existsSync(p)) {
+					ctx.ui.notify(`Procedure: ${p}`, "info");
+					return readFileSync(p, "utf-8");
+				}
+				ctx.ui.notify("Run `bash .pi/scripts/epic-parallel.sh <Module>` after freezing contracts.", "info");
+				return;
+			}
+
+			ctx.ui.notify(`Unknown /epic action "${action}". Try /epic for usage.`, "error");
+		},
+	});
+}

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:24:59Z",
+  "timestamp": "2026-11-07T14:10:40Z",
   "mode": "all",
   "stages_run": [],
   "summary": {
@@ -8,7 +8,7 @@
     "failed": 1,
     "skipped": 12
   },
-  "duration_seconds": 1,
+  "duration_seconds": 0,
   "results": [
   {
     "name": "check_mr_traceability.sh",

package/templates/pi/prompts/epic-parallel.md

@@ -0,0 +1,54 @@
+# Epic Scale-out — start parallel epics (one worktree per module)
+
+<!--
+Canonical Reference: .pi/prompts/epic-parallel.md
+Implements: parallel epics (/architect --parallel / --worktree and /epic)
+-->
+
+**Purpose:** Run several module epics at the same time without them colliding on
+shared contracts. One module → one epic branch → one worktree → one PR.
+
+---
+
+## Preconditions
+
+1. **Contracts frozen.** The module's shared contracts (ports, DTOs, error envelope,
+   composition-root seam) are merged to the base branch. Parallel epics must never
+   redefine shared contracts — that is what produces merge conflicts and rework.
+2. Clean base: `git status` clean, `main` up to date.
+
+---
+
+## Procedure (per module, can be repeated in parallel)
+
+```bash
+# 1. Record the contract freeze (done once, after the freeze issue merges)
+bash .pi/scripts/epic-registry.sh freeze "<Module>" --frozen
+
+# 2. Create the worktree + epic branch (blocked with exit 2 if not frozen)
+bash .pi/scripts/epic-parallel.sh "<Module>"
+
+# 3. In the new worktree, start the epic (epic mode: one branch, one PR)
+cd ../<repo>-<module>
+/architect --epic "<Module>"
+```
+
+Repeat steps 2–3 for each additional module — the worktrees are isolated, so the
+epics run concurrently. Each epic still commits only to its own `epic/<module>`
+branch and opens exactly one PR at the end (epic mode).
+
+---
+
+## Rules
+
+- **Never** start two epics for the same module in parallel.
+- **Never** bypass the freeze gate; if it blocks, run the Contract Freeze issue first.
+- Register/new worktrees are visible across all worktrees via the shared registry
+  (`.git/guardian/epics.json`):
+
+```bash
+bash .pi/scripts/epic-registry.sh list
+```
+
+- Merge order: freeze branches first, then epics in dependency order (see the
+  roadmap `### Dependencies`). An epic whose dependency is not merged must wait.

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