anti-slop-engineering 1.2.1 → 1.4.0

package/.skills.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://skills.sh/schema.json",
   "name": "anti-slop-engineering",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "An Engineering Discipline Playbook & Guard System for AI Coding Agents. Enforces Google SRE, Clean-Room Senior Dev Ladders, and Rust/Go Microservices.",
   "repository": "https://github.com/imMamdouhaboammar/anti-slop-engineering",
   "author": "Mamdouh Aboammar",

package/README.md

@@ -12,7 +12,7 @@
 [![Skills.sh](https://img.shields.io/badge/Skills.sh-Compatible-000000?style=flat-square&logo=vercel&logoColor=white)](https://skills.sh)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Certified%20Skill-D97706?style=flat-square&logo=anthropic&logoColor=white)](https://claude.ai)
 
-[Install](#install) · [What it catches](#what-it-catches) · [Engines](#engines) · [Decision Guard](#decision-guard) · [Root-Fix Gate](#root-fix-gate) · [Agent skill](#agent-skill) · [Anti-pattern catalog](#anti-pattern-catalog-216-patterns)
+[Install](#install) · [What it catches](#what-it-catches) · [Engines](#engines) · [Decision Guard](#decision-guard) · [Root-Fix Gate](#root-fix-gate) · [Future-Scale Gate](#future-scale-gate) · [Paranoid Architect](#the-paranoid-principal-architect) · [Install Anti-Slop](#install-anti-slop-oxlint) · [Agent skill](#agent-skill) · [Anti-pattern catalog](#anti-pattern-catalog-217-patterns)
 
 </div>
 
@@ -245,9 +245,62 @@ The JSON checker uses only Python standard library and Git when diff inspection
 
 ---
 
+## Future-Scale Gate
+
+The [Future-Scale Gate](skills/future-scale-gate/SKILL.md) protects long-lived systems against two opposite failures: locking a core contract to today's workload, and implementing expensive infrastructure for an unverified hypothetical future.
+
+| Question | Required evidence |
+| --- | --- |
+| What changes over the product's lifetime? | Credible scenarios with sources, stress axes and failure consequences |
+| Which foundation would be costly to change later? | Reversal cost, alternative designs and migration/exit path |
+| What must be established now? | Small stable boundary and a representative evolution test |
+| What should wait? | Deferred capacity with a concrete revisit trigger |
+
+Examples include a simulation language keeping its semantics portable across runtimes, a versioned public data format, or a future tenant-isolation constraint. The Gate does not require microservices, Rust, distributed systems or a provider bundle by default.
+
+```bash
+node bin/cli.js future-scale audit skills/future-scale-gate/examples/runtime-envelope-record.json --json
+```
+
+The bundled example intentionally recommends `pause` because its alternate-engine experiment has not been run. The zero-dependency checker validates record completeness, not forecast accuracy or actual scalability. The ten semantic evaluation scenarios are proposed tests, not measured model effectiveness.
+
+---
+
+## The Paranoid Principal Architect
+
+The [Paranoid Principal Architect](skills/paranoid-principal-architect/SKILL.md) skill enforces an uncompromising, zero-trust engineering posture designed for day-one 10,000,000 concurrent user scale. It rejects optimistic "happy-path" code generation, unparsed inputs, unbounded async loops, hot-key lock contention, and client authority.
+
+| Pillar | Strict Enforcement |
+| --- | --- |
+| **10M Concurrent Users Axiom** | Little's Law capacity budgeting, 16-shard counters, keyset cursor pagination (`LIMIT <= 100`), semaphore worker pools |
+| **The Internet is a Battlefield** | Parse don't validate (Zod/Valibot `.strict()`), data-layer ownership checks in queries, constant-time `crypto.timingSafeEqual` |
+| **Murphy's Law by Default** | Mandatory `Idempotency-Key` headers on mutations, `AbortSignal.timeout(ms)` on all outbound I/O, exponential backoff with full jitter |
+| **Modern Web Standards** | Native platform primitives (`structuredClone`, Web Streams, `URLSearchParams`), native `<dialog>` modals, strict branded types |
+
+Audit architectural threat records:
+
+```bash
+bunx anti-slop-engineering paranoid audit skills/paranoid-principal-architect/examples/paranoid-architecture-record.json --json
+```
+
+---
+
+## Install Anti-Slop (Oxlint)
+
+For TypeScript and JavaScript projects, install the opinionated anti-slop Oxlint lint rules to catch runtime type assertion risks, unconstrained object parameters, and module mocking leaks at lint-time:
+
+```bash
+# In your target repository:
+npx skills add imMamdouhaboammar/anti-slop-engineering
+```
+
+Follow the procedure in [install-anti-slop](skills/install-anti-slop/SKILL.md) to register the bundled plugins (`anti-slop` and optional `anti-slop-effect`) directly into `oxlint.config.ts` or `.oxlintrc.json`.
+
+---
+
 ## Agent skill
 
-The agent skill wires Anti-Slop Engineering into your AI coding agent's context. Once installed, code changes are guided by the Seven Gates, the 216-pattern anti-pattern catalog, and the Google SRE enforcement rules.
+The agent skill wires Anti-Slop Engineering into your AI coding agent's context. Once installed, code changes are guided by the Seven Gates, the 217-pattern anti-pattern catalog, and the Google SRE enforcement rules.
 
 **Supported environments:**
 
@@ -267,9 +320,9 @@ When installed via `npm install anti-slop-engineering` or `bun add anti-slop-eng
 
 ---
 
-## Anti-pattern catalog (216 patterns)
+## Anti-pattern catalog (217 patterns)
 
-The catalog in [`references/anti-pattern-catalog.md`](references/anti-pattern-catalog.md) documents 216 diagnostic patterns across 14 engineering domains, each with a canonical ID, symptom, root cause, and remediation.
+The catalog in [`references/anti-pattern-catalog.md`](references/anti-pattern-catalog.md) documents 217 diagnostic patterns across 14 engineering domains, each with a canonical ID, symptom, root cause, and remediation.
 
 **Domains covered:**
 

package/SKILL.md

@@ -4,7 +4,7 @@ description: Prevent, detect, and repair AI coding slop and dirty engineering in
 author: Mamdouh Aboammar <mamdouhfces1997@gmail.com>
 license: MIT
 metadata:
-  version: "1.2.1"
+  version: "1.4.0"
   focus: "engineering-discipline"
   repository: "https://github.com/imMamdouhaboammar/anti-slop-engineering"
 ---
@@ -39,6 +39,8 @@ metadata:
     - **Practical DRY 3-Point Barrier:** Shared utilities or abstractions are permitted only when appearing in >=2 real existing call-sites, when all call-sites require identical modifications upon change, and when the abstraction can be named without coordinating conjunctions (`and`, `or`).
 15. **Decision Guard before consequential commitments:** When the task proposes derived metrics, an architectural stack, infrastructure, persistence, or a difficult-to-reverse engineering decision, read [Decision Guard](skills/decision-guard/SKILL.md). Check direct evidence and independent alternatives before treating the proposed method as necessary. Never substitute the decision record's structural check for source verification.
 16. **Root-Fix Gate for scattered symptom patches:** When a local behavior change spreads through controllers, views, endpoints or multiple layers, read [Root-Fix Gate](skills/root-fix-gate/SKILL.md). Trace the owner of the domain invariant, compare a coherent source correction with consumer workarounds, and inspect actual change paths. Do not assume the model owns every rule or that few files prove safety.
+17. **Future-Scale Gate for irreversible foundations:** Before locking in a core runtime, public contract, persistence model, or platform boundary for a long-lived product, read [Future-Scale Gate](skills/future-scale-gate/SKILL.md). Establish credible future operating scenarios, assess reversal cost and run a bounded evolution proof. Design the cheap necessary foundation now; defer speculative infrastructure with measurable revisit triggers. Lack of a present bottleneck does not disprove future architectural constraints.
+18. **Paranoid Principal Architect for 10M scale & zero-trust:** When designing system architectures, generating backend/frontend code, refactoring critical paths, conducting adversarial security reviews, or diagnosing scale bottlenecks, race conditions, memory leaks, and EDoS vulnerabilities, read [Paranoid Principal Architect](skills/paranoid-principal-architect/SKILL.md). Enforce the 10,000,000 Concurrent Users Axiom and Active Battlefield Zero-Trust mindset. Reject happy-path assumptions, unbounded async loops, hot keys, client authority, and unparsed inputs from line one.
 
 ## Activation / modes
 
@@ -51,6 +53,8 @@ Select the relevant mode and follow the same gates:
 - **NOTED_SLOP:** codify newly observed AI slop into a diagnostic catalog pattern, agent directive, and automated diff guard heuristic (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 - **DECIDE:** when premises, direct answers or long-term architecture choices are materially uncertain, follow [Decision Guard](skills/decision-guard/SKILL.md) before BUILD. Return to ordinary modes after a decision; skip the extra protocol for routine repairs.
 - **ROOT-FIX:** when a symptom attracts scattered fixes or ownership is uncertain, follow [Root-Fix Gate](skills/root-fix-gate/SKILL.md) to establish the change boundary, then resume BUILD/FIX with regression tests.
+- **FUTURE-SCALE:** when an architecture commitment would be expensive to reverse as the product evolves, follow [Future-Scale Gate](skills/future-scale-gate/SKILL.md). Skip routine reversible edits and avoid capacity theater.
+- **PARANOID-ARCHITECT:** when building or reviewing systems against 10M concurrent user load, adversarial traffic, race conditions, hot-key contention, or zero-trust boundaries, follow [Paranoid Principal Architect](skills/paranoid-principal-architect/SKILL.md).
 
 For extensive audits, load [anti-pattern catalog](references/anti-pattern-catalog.md). For Google SRE discipline and distributed resilience patterns, load [google-sre-discipline](references/google-sre-discipline.md). For any test changes, load [test integrity policy](references/test-integrity.md). For a PR or merge request, load [PR review protocol](references/pr-review.md). For elevated permissions, sensitive code, network access, or deployment, load [security and execution boundaries](references/security-and-operations.md). For project-specific exceptions, load [judgment and exceptions](references/engineering-judgment.md). For community contributions, follow [contributor guidelines](CONTRIBUTING.md).
 
@@ -65,6 +69,7 @@ For extensive audits, load [anti-pattern catalog](references/anti-pattern-catalo
 - Run an appropriate baseline build/test if feasible; label any existing failure as baseline, not caused by this change.
 - For a derived-answer task, inspect existing direct sources before constructing proxies. For an architectural commitment, inspect the product's actual rendering, workload, operations and persistence needs instead of defaulting to a familiar provider bundle. Load `skills/decision-guard/SKILL.md` only when this uncertainty is material.
 - For a proposed cross-layer patch, identify the first incorrect boundary and trace writes/reads before editing consumers. Load `skills/root-fix-gate/SKILL.md` when the same symptom would otherwise be patched in several places.
+- For a foundational architectural commitment, classify credible future stresses and costly reversal points before using today's workload as an excuse to hard-wire the system. Load `skills/future-scale-gate/SKILL.md` only for consequential choices and verify an actual evolution path before claiming future readiness.
 - For new projects, services, components, or SDK integrations, identify the official installer, CLI generator, and canonical starter boilerplate before writing code. Do not manually assemble configurations or directory trees from memory. Never generate unprompted documentation files, submission dossiers, or speculative third-party platform guides.
 
 ### Gate 1: Establish a change contract

package/bin/cli.js

@@ -3,7 +3,7 @@
 // Copyright (c) 2026 Mamdouh Aboammar <mamdouhfces1997@gmail.com> and contributors
 
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
@@ -15,6 +15,9 @@ const diffGuardScript = resolve(rootDir, "scripts", "diff_guard.py");
 const sreGuardScript = resolve(rootDir, "scripts", "sre_guard.py");
 const decisionGuardScript = resolve(rootDir, "scripts", "decision_guard.py");
 const rootFixGuardScript = resolve(rootDir, "scripts", "root_fix_guard.py");
+const futureScaleGuardScript = resolve(rootDir, "scripts", "future_scale_guard.py");
+const paranoidGuardScript = resolve(rootDir, "scripts", "paranoid_guard.py");
+const bumpVersionScript = resolve(rootDir, "scripts", "bump_version.py");
 const nativeSuffix = process.platform === "win32" ? ".exe" : "";
 const rustExecutable = "anti-slop-rust" + nativeSuffix;
 const goExecutable = "toil-guard" + nativeSuffix;
@@ -33,7 +36,7 @@ if (executableAliases[invokedAs]) args.unshift(executableAliases[invokedAs]);
 
 function printBanner() {
   console.log(`
-🛡️  Anti-Slop Engineering CLI (v1.2.1)
+🛡️  Anti-Slop Engineering CLI (v1.4.0)
    Clean-Room AI Coding Guard & High-Performance Polyglot Architecture
    Engines: Standard Library Python Guard | Rust Microservice | Go Toil Guard
    Author: Mamdouh Aboammar <mamdouhfces1997@gmail.com>
@@ -52,6 +55,9 @@ Commands:
   sre, sre-guard         Run Python Google SRE Guard (zero-dependency stdlib fallback)
   decision audit <file>  Check a Decision Guard JSON record for missing evidence and trade-offs
   root-fix audit <file>  Check root-cause ownership, change plan and optional Git diff
+  future-scale audit <file>  Check future operating envelope, reversibility and evolution proof
+  paranoid audit <file>  Check a Paranoid Architect record for zero-trust and 10M scale compliance
+  bump [part]            Bump version across all 10 manifests (patch, minor, major, or explicit)
   test                   Run unit test suite
   contribute             Print guidelines on reporting noted slop or opening PRs
 
@@ -172,7 +178,16 @@ function runBuild() {
         console.error(`Go build failed with exit code ${goCode}`);
         process.exit(goCode ?? 1);
       }
-      console.log("All native microservices built successfully.");
+      mkdirSync(resolve(rootDir, "dist", "bin"), { recursive: true });
+      copyFileSync(
+        resolve(rootDir, "services", "anti-slop-rust", "target", "release", rustExecutable),
+        resolve(rootDir, "dist", "bin", rustExecutable)
+      );
+      copyFileSync(
+        resolve(rootDir, "services", "toil-guard-go", "bin", goExecutable),
+        resolve(rootDir, "dist", "bin", goExecutable)
+      );
+      console.log("All native microservices built successfully and staged in dist/bin/.");
       process.exit(0);
     });
   });
@@ -200,6 +215,12 @@ if (cmd === "build") {
   runPythonScript(decisionGuardScript, args.slice(1), "decision_guard");
 } else if (cmd === "root-fix") {
   runPythonScript(rootFixGuardScript, args.slice(1), "root_fix_guard");
+} else if (cmd === "future-scale") {
+  runPythonScript(futureScaleGuardScript, args.slice(1), "future_scale_guard");
+} else if (cmd === "paranoid") {
+  runPythonScript(paranoidGuardScript, args.slice(1), "paranoid_guard");
+} else if (cmd === "bump") {
+  runPythonScript(bumpVersionScript, args.slice(1), "bump_version");
 } else if (args.includes("--help") || args.includes("-h")) {
   printBanner();
   process.exit(0);

package/install.sh

@@ -35,18 +35,24 @@ install_to() {
   mkdir -p "$(dirname "$dest")"
   rm -rf "$dest"
   mkdir -p "$dest"
-  cp -R "$SOURCE_DIR/"* "$dest/"
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --exclude 'target' --exclude 'node_modules' --exclude '.git' "$SOURCE_DIR/" "$dest/"
+  else
+    cp -R "$SOURCE_DIR/"* "$dest/"
+    rm -rf "$dest/services/anti-slop-rust/target" "$dest/node_modules" 2>/dev/null || true
+  fi
   # Ensure scripts are executable
   chmod +x "$dest/bin/cli.js" 2>/dev/null || true
   chmod +x "$dest/scripts/diff_guard.py" 2>/dev/null || true
   chmod +x "$dest/scripts/sre_guard.py" 2>/dev/null || true
   chmod +x "$dest/scripts/decision_guard.py" 2>/dev/null || true
   chmod +x "$dest/scripts/root_fix_guard.py" 2>/dev/null || true
+  chmod +x "$dest/scripts/future_scale_guard.py" 2>/dev/null || true
   chmod +x "$dest/install.sh" 2>/dev/null || true
   echo "  ✅ Installed anti-slop-engineering for ${label} -> ${dest}"
 
   # Install each bundled module as a discoverable top-level skill.
-  for module in decision-guard root-fix-gate; do
+  for module in decision-guard root-fix-gate future-scale-gate; do
     if [ -d "$SOURCE_DIR/skills/$module" ]; then
       local module_dest="$(dirname "$dest")/$module"
       rm -rf "$module_dest"

package/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-plugin-manifest.json",
   "name": "anti-slop-engineering",
   "displayName": "Anti-Slop Engineering",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "An Engineering Discipline Playbook, Agent Skill & Triage Guard for AI Coding Agents. Enforces behavioral contracts, focused diffs, test integrity, Google SRE principles, and native Rust/Go clean-room microservices.",
   "author": {
     "name": "Mamdouh Aboammar",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anti-slop-engineering",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "An Engineering Discipline Playbook, Agent Skill & Triage Guard for AI Coding Agents",
   "type": "module",
   "main": "bin/cli.js",
@@ -21,6 +21,7 @@
   "homepage": "https://github.com/imMamdouhaboammar/anti-slop-engineering#readme",
   "files": [
     "bin",
+    "dist",
     "scripts",
     "skills",
     "services/anti-slop-rust/Cargo.toml",
@@ -49,6 +50,7 @@
     "sre-guard": "bun bin/cli.js sre",
     "test": "python3 -m unittest discover -s tests -v",
     "test-all": "make test-all",
+    "bump": "python3 scripts/bump_version.py",
     "check": "make check",
     "check-all": "make check-all"
   },

package/references/anti-pattern-catalog.md

@@ -39,6 +39,7 @@ Format: **ID | pattern | how to verify / safer alternative**. Numbers are stable
 - **ARC-15 | Manual scaffolding improvisation.** Hand-crafting directory structures, build configs, and boilerplate files (`tsconfig.json`, `package.json`, `pyproject.toml`, Dockerfiles) from memory instead of using the official framework/language CLI installer, starter template, or generator; introduces missing build flags, non-standard layouts, and broken tooling.
 - **ARC-16 | Familiar-stack default and short-horizon choice.** Agent bundles framework, host and database by popularity without testing actual workload, operations, recovery, exit paths or credible future states; compare independent axes, constraints and reversibility. Managed services and VPS are each legitimate where evidence supports them.
 - **ARC-17 | Symptom fan-out and wrong-layer repair.** Agent fixes a repeated symptom separately in many consumers instead of checking the responsible domain or boundary contract; trace writes and reads, compare owner correction with distributed patches, and preserve distinct context-specific policies. A one-file model rewrite is not automatically safer than a justified multi-layer change.
+- **ARC-18 | Present-state foundation trap.** Agent treats the absence of today's workload bottleneck as evidence that future architecture does not matter, permanently coupling semantics, storage or identity to a cheap current implementation. Alternatively it builds speculative high-scale infrastructure without a credible use case. Distinguish hard-to-reverse foundations from replaceable capacity, rank future scenarios by evidence, and test the smallest evolution path before committing.
 
 ## C. Simplicity, duplication, and code readability
 

package/scripts/bump_version.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Mamdouh Aboammar <mamdouhfces1997@gmail.com> and contributors
+"""Bump version across repository manifests, documentation, and native services."""
+
+import argparse
+import datetime
+import hashlib
+import json
+import pathlib
+import shutil
+import sre_compile
+import subprocess
+import sys
+
+SEMVER_PATTERN = sre_compile.compile(
+    r'^(?P<major>\d{1,8})\.(?P<minor>\d{1,8})\.(?P<patch>\d{1,8})(?:-(?P<prerelease>[0-9A-Za-z.-]{1,50}))?$'
+)
+
+MANIFEST_TARGETS = [
+    {
+        "file": "package.json",
+        "pattern": sre_compile.compile(r'("version"\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "pyproject.toml",
+        "pattern": sre_compile.compile(r'(version\s*=\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": ".skills.json",
+        "pattern": sre_compile.compile(r'("version"\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "marketplace.json",
+        "pattern": sre_compile.compile(r'("version"\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "SKILL.md",
+        "pattern": sre_compile.compile(r'(version\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "bin/cli.js",
+        "pattern": sre_compile.compile(r'Anti-Slop Engineering CLI \(v[^\)]+\)'),
+        "replacement": r'Anti-Slop Engineering CLI (v{version})',
+    },
+    {
+        "file": "CITATION.cff",
+        "pattern": sre_compile.compile(r'(version\s*:\s*)[^\n]+'),
+        "replacement": r'\g<1>{version}',
+    },
+    {
+        "file": "CITATION.cff",
+        "pattern": sre_compile.compile(r'(date-released\s*:\s*)[^\n]+'),
+        "replacement": r'\g<1>{release_date}',
+    },
+    {
+        "file": "services/anti-slop-rust/Cargo.toml",
+        "pattern": sre_compile.compile(r'(\[package\][\s\S]*?version\s*=\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "services/toil-guard-go/pkg/model/types.go",
+        "pattern": sre_compile.compile(r'(Version\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+    {
+        "file": "services/toil-guard-go/pkg/server/server.go",
+        "pattern": sre_compile.compile(r'("version"\s*:\s*)"[^"]+"'),
+        "replacement": r'\g<1>"{version}"',
+    },
+]
+
+
+def parse_semver(version_str, depth=0, max_depth=100):
+    """Parse semver string into (major, minor, patch, prerelease)."""
+    if depth > max_depth:
+        return None
+    cleaned = version_str.lstrip("v").strip()
+    match = SEMVER_PATTERN.match(cleaned)
+    if not match:
+        return None
+    return {
+        "major": int(match.group("major")),
+        "minor": int(match.group("minor")),
+        "patch": int(match.group("patch")),
+        "prerelease": match.group("prerelease"),
+    }
+
+
+def compute_next_version(current_ver, bump_type, depth=0, max_depth=100):
+    """Calculate the next semver string based on bump type or target version."""
+    if depth > max_depth:
+        raise ValueError("Maximum recursion depth exceeded")
+
+    candidate = bump_type.lstrip("v").strip()
+    if SEMVER_PATTERN.match(candidate):
+        return candidate
+
+    parsed = parse_semver(current_ver)
+    if not parsed:
+        raise ValueError(f"Current version '{current_ver}' is not valid semver")
+
+    bump = bump_type.lower()
+    if bump == "patch":
+        return f"{parsed['major']}.{parsed['minor']}.{parsed['patch'] + 1}"
+    if bump == "minor":
+        return f"{parsed['major']}.{parsed['minor'] + 1}.0"
+    if bump == "major":
+        return f"{parsed['major'] + 1}.0.0"
+
+    raise ValueError(
+        f"Invalid bump type or version '{bump_type}'. Choose patch, minor, major, or explicit semver (e.g. 1.3.0)"
+    )
+
+
+def read_current_version(root_dir, depth=0, max_depth=100):
+    """Read the current canonical version from package.json."""
+    if depth > max_depth:
+        raise ValueError("Maximum depth exceeded")
+    pkg_path = pathlib.Path(root_dir) / "package.json"
+    if not pkg_path.is_file():
+        raise FileNotFoundError(f"Missing canonical manifest at {pkg_path}")
+    data = json.loads(pkg_path.read_text(encoding="utf-8"))
+    version = data.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError(f"package.json has missing or invalid version: {version}")
+    return version.strip()
+
+
+def apply_target_update(compiled_pattern, repl_str, content, depth=0, max_depth=100):
+    """Apply single precompiled regex replacement pattern to file content."""
+    if depth > max_depth:
+        return content, False
+    new_content, count = compiled_pattern.subn(repl_str, content, count=1)
+    return new_content, count > 0
+
+
+def update_attestation_hash(root_dir, new_pkg_content, depth=0, max_depth=100):
+    """Update package.json sha256 in .fable/heal-attestation.json if present."""
+    if depth > max_depth:
+        return False
+    attestation_path = pathlib.Path(root_dir) / ".fable" / "heal-attestation.json"
+    if not attestation_path.is_file():
+        return False
+    try:
+        data = json.loads(attestation_path.read_text(encoding="utf-8"))
+        if "file_hashes" in data and "package.json" in data["file_hashes"]:
+            new_hash = hashlib.sha256(new_pkg_content.encode("utf-8")).hexdigest()
+            data["file_hashes"]["package.json"] = new_hash
+            attestation_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+            return True
+    except (OSError, ValueError):
+        return False
+    return False
+
+
+def sync_cargo_lock(root_dir):
+    """Synchronize Cargo.lock if cargo is available."""
+    cargo_bin = shutil.which("cargo")
+    cargo_toml = pathlib.Path(root_dir) / "services" / "anti-slop-rust" / "Cargo.toml"
+    if cargo_bin and cargo_toml.is_file():
+        subprocess.run(
+            [cargo_bin, "check", "--manifest-path", str(cargo_toml)],
+            capture_output=True,
+            check=False,
+        )
+
+
+def bump_repository_version(root_dir, bump_type, release_date=None, dry_run=False, depth=0, max_depth=100):
+    """Perform version bump across all registered repository manifests."""
+    if depth > max_depth:
+        raise ValueError("Maximum depth exceeded")
+    root = pathlib.Path(root_dir).resolve()
+    current_ver = read_current_version(root)
+    next_ver = compute_next_version(current_ver, bump_type)
+    rel_date = release_date or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d")
+
+    results = []
+    file_contents = {}
+
+    for target in MANIFEST_TARGETS:
+        rel_path = target["file"]
+        file_path = root / rel_path
+        if not file_path.is_file():
+            results.append({"file": rel_path, "status": "skipped_missing"})
+            continue
+
+        content = file_contents.get(rel_path)
+        if content is None:
+            content = file_path.read_text(encoding="utf-8")
+
+        repl_str = target["replacement"].format(version=next_ver, release_date=rel_date)
+        new_content, updated = apply_target_update(target["pattern"], repl_str, content)
+
+        if updated:
+            file_contents[rel_path] = new_content
+            results.append({"file": rel_path, "status": "updated"})
+        else:
+            results.append({"file": rel_path, "status": "pattern_not_found"})
+
+    if not dry_run:
+        for rel_path, content in file_contents.items():
+            (root / rel_path).write_text(content, encoding="utf-8")
+
+        if "package.json" in file_contents:
+            update_attestation_hash(root, file_contents["package.json"])
+
+        sync_cargo_lock(root)
+
+    return {
+        "previous_version": current_ver,
+        "new_version": next_ver,
+        "release_date": rel_date,
+        "dry_run": dry_run,
+        "updated_files": list(dict.fromkeys(r["file"] for r in results if r["status"] == "updated")),
+        "details": results,
+    }
+
+
+def main():
+    """Command-line entrypoint for bumping version."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "bump",
+        nargs="?",
+        default="patch",
+        help="Bump type (patch, minor, major) or explicit semver version (e.g. 1.3.0)",
+    )
+    parser.add_argument("--repo", default=".", help="Root directory of the repository")
+    parser.add_argument("--date", default=None, help="Release date override (YYYY-MM-DD)")
+    parser.add_argument("--dry-run", action="store_true", help="Preview version changes without writing")
+    parser.add_argument("--json", action="store_true", help="Output machine-readable JSON summary")
+    parser.add_argument("--git-tag", action="store_true", help="Create git tag vX.Y.Z after bump")
+    parser.add_argument("--git-commit", action="store_true", help="Create git commit after bump")
+    args = parser.parse_args()
+
+    try:
+        report = bump_repository_version(
+            root_dir=args.repo,
+            bump_type=args.bump,
+            release_date=args.date,
+            dry_run=args.dry_run,
+        )
+    except (ValueError, FileNotFoundError) as err:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+
+    if args.git_commit and not args.dry_run:
+        ver = report["new_version"]
+        subprocess.run(["git", "-C", args.repo, "add", "-A"], check=False)
+        subprocess.run(["git", "-C", args.repo, "commit", "-m", f"chore(release): v{ver}"], check=False)
+
+    if args.git_tag and not args.dry_run:
+        ver = report["new_version"]
+        subprocess.run(["git", "-C", args.repo, "tag", "-a", f"v{ver}", "-m", f"Release v{ver}"], check=False)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        status_prefix = "[DRY-RUN] " if report["dry_run"] else ""
+        print(f"{status_prefix}Bumped version: v{report['previous_version']} ➜ v{report['new_version']}")
+        print(f"Release Date: {report['release_date']}")
+        print(f"Updated {len(set(report['updated_files']))} manifest files:")
+        for file in sorted(set(report["updated_files"])):
+            print(f"  ✓ {file}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())