anti-slop-engineering 0.4.0 → 1.1.0

package/.skills.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://skills.sh/schema.json",
   "name": "anti-slop-engineering",
-  "version": "0.4.0",
+  "version": "1.1.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) · [Agent skill](#agent-skill) · [Anti-pattern catalog](#anti-pattern-catalog-213-patterns)
+[Install](#install) · [What it catches](#what-it-catches) · [Engines](#engines) · [Decision Guard](#decision-guard) · [Agent skill](#agent-skill) · [Anti-pattern catalog](#anti-pattern-catalog-215-patterns)
 
 </div>
 
@@ -139,7 +139,7 @@ bunx anti-slop-engineering sre --max-nesting 4 --min-dup-lines 4 --max-function-
 
 ### Rust SHIT Interceptor (`services/anti-slop-rust`)
 
-A high-performance Axum HTTP microservice that audits diffs and source for four categories of agent failure — Scope creep (`S`), Hypothetical hardening (`H`), Intent violation (`I`), and Task thrashing (`T`) — plus the Senior Dev Ladder pattern: detecting custom implementations where platform primitives already exist (`crypto.randomUUID()`, `URLSearchParams`, `structuredClone()`).
+A high-performance Axum HTTP microservice that audits diffs and source for Scope creep (`S`), Hypothetical hardening (`H`), and Intent violation (`I`) in diffs, plus regex-based Senior Dev Ladder checks for hand-rolled alternatives to common platform primitives. Task-thrashing detection is not implemented.
 
 ```bash
 # Triage git changes through Rust engine:
@@ -158,9 +158,9 @@ A concurrent Go microservice for high-throughput SRE metric verification. Runs K
 
 ```bash
 # SRE audit across repository:
-bunx anti-slop-engineering toil audit
+bunx anti-slop-engineering toil audit .
 
-# Live git telemetry with error budget tracking:
+# Live git diff statistics (not a live error-budget calculation):
 bunx anti-slop-engineering toil stream
 
 # Start Go microservice daemon:
@@ -201,6 +201,29 @@ flowchart TD
 
 ---
 
+## Decision Guard
+
+The [Decision Guard module](skills/decision-guard/SKILL.md) addresses two decisions the code diff cannot catch: deriving an answer that already exists directly, and choosing a familiar technology stack without testing the product's actual requirements and future operating costs.
+
+| Situation | Agent behavior |
+| --- | --- |
+| Seven metrics infer a value present in a source field | Verify the field's semantics and propose using the direct answer |
+| A logged-in app triggers an automatic Next.js/Vercel/database bundle | Separate rendering, jobs, hosting, persistence and operations choices |
+| VPS appears cheaper than managed infrastructure | Compare recovery, maintenance, on-call, migration and actual workload |
+| New evidence invalidates days of prior work | Interrupt, explain the change and offer the smallest corrected path |
+
+The module is loaded selectively during Gate 0/1 for consequential decisions. It includes a portable skill, two focused workflows, decision references, nine evaluation scenarios and a standard-library JSON record checker.
+
+```bash
+node bin/cli.js decision audit skills/decision-guard/examples/architecture-record.json --json
+# Or, using the package CLI:
+npx anti-slop-engineering decision audit path/to/decision.json --json
+```
+
+Exit `0` means the record is structurally complete, `2` means required decision evidence is missing, and `1` means unreadable or malformed input. These are **not** claims that the chosen architecture is correct or that sources were verified. A complete record can intentionally recommend `pause` or `stop`.
+
+---
+
 ## Agent skill
 
 The agent skill wires Anti-Slop Engineering into your AI coding agent's context. Once installed, every code change the agent generates is governed by the Seven Gates, the 213-pattern anti-pattern catalog, and the Google SRE enforcement rules.
@@ -223,9 +246,9 @@ When installed via `npm install anti-slop-engineering` or `bun add anti-slop-eng
 
 ---
 
-## Anti-pattern catalog (213 patterns)
+## Anti-pattern catalog (215 patterns)
 
-The catalog in [`references/anti-pattern-catalog.md`](references/anti-pattern-catalog.md) documents 213 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 215 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: "0.4.0"
+  version: "1.1.0"
   focus: "engineering-discipline"
   repository: "https://github.com/imMamdouhaboammar/anti-slop-engineering"
 ---
@@ -37,6 +37,7 @@ metadata:
     - Climb the Senior Dev Ladder before authoring code: (1) Does this need to exist? (2) Does it already exist in the codebase? (3) Does the stdlib/platform do it? (4) Does native runtime cover it? (5) Does an existing dependency solve it? (6) Can it be a direct expression? (7) Write only minimal, necessary, tested code.
     - **Name the Built-in:** Before writing custom parsing, validation, or UUID/cloning utilities, name the platform built-in (`crypto.randomUUID()`, `URLSearchParams`, `structuredClone()`). Hand-rolling standard primitives is a defect.
     - **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.
 
 ## Activation / modes
 
@@ -47,6 +48,7 @@ Select the relevant mode and follow the same gates:
 - **REVIEW:** read-only diff and repository-context audit; report findings with severity, evidence, and counterfactual.
 - **CLEANUP:** establish an observable behavior baseline, isolate pure refactors from feature changes, prove no drift.
 - **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.
 
 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).
 
@@ -59,6 +61,7 @@ For extensive audits, load [anti-pattern catalog](references/anti-pattern-catalo
 - Read relevant open issues/PRs when available to avoid duplicates or fighting in-flight changes. Do not require network access to proceed when unavailable.
 - Record working tree status; do not overwrite user changes, reset, stash, or modify unrelated files without authorization.
 - 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 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,8 +3,8 @@
 // Copyright (c) 2026 Mamdouh Aboammar <mamdouhfces1997@gmail.com> and contributors
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
@@ -13,18 +13,26 @@ const __dirname = dirname(__filename);
 const rootDir = resolve(__dirname, "..");
 const diffGuardScript = resolve(rootDir, "scripts", "diff_guard.py");
 const sreGuardScript = resolve(rootDir, "scripts", "sre_guard.py");
-const rustBinPath = existsSync(resolve(rootDir, "dist", "bin", "anti-slop-rust"))
-  ? resolve(rootDir, "dist", "bin", "anti-slop-rust")
-  : resolve(rootDir, "services", "anti-slop-rust", "target", "release", "anti-slop-rust");
-const goBinPath = existsSync(resolve(rootDir, "dist", "bin", "toil-guard"))
-  ? resolve(rootDir, "dist", "bin", "toil-guard")
-  : resolve(rootDir, "services", "toil-guard-go", "bin", "toil-guard");
-
+const decisionGuardScript = resolve(rootDir, "scripts", "decision_guard.py");
+const nativeSuffix = process.platform === "win32" ? ".exe" : "";
+const rustExecutable = "anti-slop-rust" + nativeSuffix;
+const goExecutable = "toil-guard" + nativeSuffix;
+const disableNative = process.env.ANTI_SLOP_DISABLE_NATIVE === "1" || process.env.ANTI_SLOP_FORCE_FALLBACK === "1";
+const rustBinPath = !disableNative && existsSync(resolve(rootDir, "dist", "bin", rustExecutable))
+  ? resolve(rootDir, "dist", "bin", rustExecutable)
+  : (!disableNative ? resolve(rootDir, "services", "anti-slop-rust", "target", "release", rustExecutable) : "");
+const goBinPath = !disableNative && existsSync(resolve(rootDir, "dist", "bin", goExecutable))
+  ? resolve(rootDir, "dist", "bin", goExecutable)
+  : (!disableNative ? resolve(rootDir, "services", "toil-guard-go", "bin", goExecutable) : "");
+
+const invokedAs = basename(process.argv[1] ?? "").replace(/\.(?:js|cmd|exe)$/i, "");
+const executableAliases = { "sre-guard": "sre", "rust-guard": "rust", "toil-guard": "toil" };
 const args = process.argv.slice(2);
+if (executableAliases[invokedAs]) args.unshift(executableAliases[invokedAs]);
 
 function printBanner() {
   console.log(`
-🛡️  Anti-Slop Engineering CLI (v0.4.0)
+🛡️  Anti-Slop Engineering CLI (v1.1.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>
@@ -35,12 +43,13 @@ Usage:
   bunx anti-slop-engineering [command] [options]
 
 Commands:
-  rust, sts              Run native Rust Engine (Scope Creep, Hypothetical Hardening, Intent, Task Thrashing, Senior Dev Ladder)
+  rust, sts              Run native Rust Engine (Scope Creep, Hypothetical Hardening, Intent, Senior Dev Ladder)
   toil, go-guard         Run Go SRE Engine (KISS nesting, DRY token window, Toil & Error Budget)
   serve-rust             Start background Rust HTTP microservice daemon (default: :9091)
   serve-go               Start background Go HTTP SRE microservice daemon (default: :9092)
   build                  Compile both Rust and Go microservices
   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
   test                   Run unit test suite
   contribute             Print guidelines on reporting noted slop or opening PRs
 
@@ -64,7 +73,7 @@ function spawnProcess(execPath, execArgs, label) {
     process.exit(1);
   });
   child.on("close", (code) => {
-    process.exit(code ?? 0);
+    process.exit(code ?? 1); // Signal termination must never be reported as success.
   });
 }
 
@@ -88,6 +97,54 @@ function runPythonScript(scriptPath, scriptArgs, scriptLabel) {
   spawnProcess("python3", [scriptPath, ...scriptArgs], scriptLabel);
 }
 
+function unsupportedFallback(engine, request) {
+  console.error(`Error: ${engine} native binary is required for ${request}. Run 'anti-slop-engineering build'.`);
+  process.exit(1);
+}
+
+function extractCommonFlags(flags, engine, onUnrecognized) {
+  const mapped = [];
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (flag === "--base" && flags[i + 1]) {
+      mapped.push("--base", flags[++i]);
+    } else if (flag === "--format" && flags[i + 1] === "json") {
+      mapped.push("--json");
+      i++;
+    } else if (flag === "--format" && flags[i + 1] === "text") {
+      i++;
+    } else if (onUnrecognized) {
+      onUnrecognized(flag);
+    } else {
+      unsupportedFallback(engine, `option ${flag}`);
+    }
+  }
+  return mapped;
+}
+
+function runRustFallback(request) {
+  const [command, ...flags] = request;
+  if (command !== "triage") unsupportedFallback("Rust", command);
+  const mapped = ["--fail-on-blocker", ...extractCommonFlags(flags, "Rust")];
+  runPythonScript(diffGuardScript, mapped, "diff_guard");
+}
+
+function runGoFallback(request) {
+  const [command, ...flags] = request;
+  if (command !== "audit") unsupportedFallback("Go", command);
+  const paths = [];
+  const mapped = extractCommonFlags(flags, "Go", (flag) => {
+    if (flag.startsWith("-")) unsupportedFallback("Go", `audit option ${flag}`);
+    else paths.push(flag);
+  });
+  if (paths.length > 0) {
+    if (mapped.includes("--base")) unsupportedFallback("Go", "audit with both --base and paths");
+    mapped.push("--files", ...paths);
+  } else if (!mapped.includes("--base")) mapped.push("--base", "HEAD");
+  mapped.push("--strict");
+  runPythonScript(sreGuardScript, mapped, "sre_guard");
+}
+
 function runBuild() {
   console.log("Compiling Rust microservice...");
   const cargo = spawn("cargo", ["build", "--release"], {
@@ -102,7 +159,8 @@ function runBuild() {
     }
 
     console.log("Compiling Go microservice...");
-    const goBuild = spawn("go", ["build", "-o", "bin/toil-guard", "./cmd/toil-guard"], {
+    mkdirSync(resolve(rootDir, "services", "toil-guard-go", "bin"), { recursive: true });
+    const goBuild = spawn("go", ["build", "-o", "bin/" + goExecutable, "./cmd/toil-guard"], {
       cwd: resolve(rootDir, "services", "toil-guard-go"),
       stdio: "inherit",
     });
@@ -125,21 +183,19 @@ if (cmd === "build") {
 } else if (cmd === "rust" || cmd === "rust-guard" || cmd === "sts") {
   const subArgs = args.slice(1);
   const forwardArgs = subArgs.length > 0 ? subArgs : ["triage"];
-  runBinary(rustBinPath, forwardArgs, "anti-slop-rust", () => {
-    runPythonScript(diffGuardScript, ["--base", "HEAD"], "diff_guard");
-  });
+  runBinary(rustBinPath, forwardArgs, "anti-slop-rust", () => runRustFallback(forwardArgs));
 } else if (cmd === "toil" || cmd === "toil-guard" || cmd === "go-guard") {
   const subArgs = args.slice(1);
   const forwardArgs = subArgs.length > 0 ? subArgs : ["audit"];
-  runBinary(goBinPath, forwardArgs, "toil-guard-go", () => {
-    runPythonScript(sreGuardScript, ["--base", "HEAD"], "sre_guard");
-  });
+  runBinary(goBinPath, forwardArgs, "toil-guard-go", () => runGoFallback(forwardArgs));
 } else if (cmd === "serve-rust") {
   runBinary(rustBinPath, ["serve", ...args.slice(1)], "anti-slop-rust daemon", null);
 } else if (cmd === "serve-go") {
   runBinary(goBinPath, ["serve", ...args.slice(1)], "toil-guard-go daemon", null);
 } else if (cmd === "sre" || cmd === "sre-guard") {
   runPythonScript(sreGuardScript, args.slice(1), "sre_guard");
+} else if (cmd === "decision") {
+  runPythonScript(decisionGuardScript, args.slice(1), "decision_guard");
 } else if (args.includes("--help") || args.includes("-h")) {
   printBanner();
   process.exit(0);
@@ -164,7 +220,7 @@ Path B: Submit a PR (Problem + Solution Integrated)
     cwd: rootDir,
     stdio: "inherit",
   });
-  pyTest.on("close", (code) => process.exit(code ?? 0));
+  pyTest.on("close", (code) => process.exit(code ?? 1));
 } else if (cmd === "test-all") {
   spawnProcess("make", ["test-all"], "test-all");
 } else if (cmd === "check-all") {

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": "0.4.0",
+  "version": "1.1.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,15 +1,15 @@
 {
   "name": "anti-slop-engineering",
-  "version": "0.4.0",
+  "version": "1.1.0",
   "description": "An Engineering Discipline Playbook, Agent Skill & Triage Guard for AI Coding Agents",
   "type": "module",
   "main": "bin/cli.js",
   "bin": {
-    "anti-slop-engineering": "./bin/cli.js",
-    "diff-guard": "./bin/cli.js",
-    "sre-guard": "./bin/cli.js",
-    "rust-guard": "./bin/cli.js",
-    "toil-guard": "./bin/cli.js"
+    "anti-slop-engineering": "bin/cli.js",
+    "diff-guard": "bin/cli.js",
+    "sre-guard": "bin/cli.js",
+    "rust-guard": "bin/cli.js",
+    "toil-guard": "bin/cli.js"
   },
   "repository": {
     "type": "git",
@@ -22,6 +22,13 @@
   "files": [
     "bin",
     "scripts",
+    "skills",
+    "services/anti-slop-rust/Cargo.toml",
+    "services/anti-slop-rust/Cargo.lock",
+    "services/anti-slop-rust/src",
+    "services/toil-guard-go/go.mod",
+    "services/toil-guard-go/cmd",
+    "services/toil-guard-go/pkg",
     "references",
     "assets",
     "SKILL.md",

package/references/anti-pattern-catalog.md

@@ -18,6 +18,7 @@ Format: **ID | pattern | how to verify / safer alternative**. Numbers are stable
 - **REQ-10 | Skipped acceptance criteria.** PR satisfies prose loosely but not contract; maintain acceptance evidence mapping.
 - **REQ-11 | Incorrect partial-success semantics.** Batch reports complete when only half succeeded; model outcomes and retryable failures.
 - **REQ-12 | Placeholder leakage.** Temporary behavior, fake data, TODO 'later' shipped as final; enumerate and resolve release blockers.
+- **REQ-13 | Indirect-answer tunnel.** Agent constructs proxy metrics or inference chains while the answer already exists in an accessible source; inspect direct fields and their semantics before calculating.
 
 ## B. Architecture, boundaries, and repository consistency
 
@@ -36,6 +37,7 @@ Format: **ID | pattern | how to verify / safer alternative**. Numbers are stable
 - **ARC-13 | Inappropriate inheritance.** A shared base class couples unrelated behavior; prefer composition only if it clarifies.
 - **ARC-14 | Leaky plugin architecture.** Dynamic extension point without real callers; reduce indirection.
 - **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.
 
 ## C. Simplicity, duplication, and code readability
 

package/references/clean-room-recon.md

@@ -59,7 +59,7 @@ No code from any reference repository is copied or decompiled. Only functional m
       |   - Scope Creep Detector     |                    | • Concurrency & Toil Guard   |
       |   - Hypothetical Hardening   |                    | • Sliding-Window DRY Scanner |
       |   - Intent Violation Gate    |                    | • SLI/SLO Error Budget Engine|
-      |   - Task Thrashing Watcher   |                    | • Prometheus /metrics Server |
+      |   - Rule-based diff checks   |                    | • Prometheus /metrics Server |
       | • Senior Dev Ladder Auditor  |                    | • HTTP REST Service (/v1/..) |
       | • Axum REST Server (/v1/..)  |                    +------------------------------+
       +------------------------------+                                   |
@@ -75,19 +75,19 @@ No code from any reference repository is copied or decompiled. Only functional m
 ```
 
 ### 2.1 Rust Microservice (`services/anti-slop-rust`)
-- **Focus:** Ultra-fast AST pattern triage, SHIT boundary violation interception, token waste analysis, and deterministic circuit-breaker protection.
+- **Focus:** Regex-based diff triage for scope, speculative hardening, and read-only intent, plus simple built-in replacement checks.
 - **Key Modules:**
   - `src/shit_interceptor.rs`: Scope creep detection, unread checksum/hash generation checks, speculative try-catch error swallowing, and file boundary guards.
-  - `src/ladder_auditor.rs`: Code reduction ratio auditing, stdlib built-in identification, and 3-point abstraction gate checks.
-  - `src/server.rs`: Lightweight HTTP microservice (`axum` + `tokio`) exposing `/health`, `/v1/triage`, `/v1/shit-check`, and `/v1/ladder`.
+  - `src/ladder_auditor.rs`: Regex-based built-in replacement suggestions and conjunction naming hints.
+  - `src/server.rs`: Lightweight HTTP microservice (`axum` + `tokio`) exposing `/health`, `/v1/triage`, `/v1/shit-check`, and `/v1/ladder-audit`.
   - `src/main.rs`: High-performance CLI interface powered by `clap`.
 
 ### 2.2 Go Microservice (`services/toil-guard-go`)
 - **Focus:** Concurrent repository-wide stream analysis, Google SRE metric verification (KISS, DRY, YAGNI, Scale), automated toil detection, and SLI/SLO budget verification.
 - **Key Modules:**
   - `pkg/sre/complexity.go`: Control flow nesting level (<=4) and function length (<=80 lines) verification.
-  - `pkg/sre/dry_window.go`: Sliding-window token hash scanner across files.
-  - `pkg/sre/toil.go`: SRE anti-pattern heuristics (unbounded concurrency, blind sleep synchronization, missing exponential backoff + jitter).
+  - `pkg/sre/dry.go`: Sliding-window token hash scanner across files.
+  - `pkg/sre/toil.go`: SRE anti-pattern heuristics (blind sleep synchronization, fixed retry loops, and silent error swallowing).
   - `pkg/sre/sli.go`: Error budget calculation and slop index scoring.
-  - `pkg/server/server.go`: Production Go HTTP microservice with graceful shutdown, `/healthz`, `/metrics`, and `/v1/toil-audit`.
+  - `pkg/server/server.go`: Production Go HTTP microservice with graceful shutdown, `/healthz`, `/metrics`, and `/v1/audit`.
   - `cmd/toil-guard/main.go`: Multi-subcommand CLI runner (`audit`, `stream`, `serve`).

package/references/engineering-judgment.md

@@ -16,6 +16,9 @@ A huge mandatory checklist can itself cause excessive code, bureaucracy and agen
 - Changing existing tests is valid when the approved contract changes; changing tests to fit a regression is not.
 - Unit vs integration vs E2E should reflect system risk and cost; neither all-unit nor all-E2E is a universal rule.
 - Rule thresholds (file length, diff size, number of files) are prompts for scrutiny, not blockers without measured harm.
+- A directly named metric is not automatically the right observation: validate event semantics, units, cohort, freshness and provenance before replacing inference with a source field.
+- A familiar managed stack and a self-hosted VPS stack are both legitimate options. Separate rendering, compute, hosting, data and operational ownership; do not equate lower infrastructure spend with lower total risk.
+- A multi-year architecture scenario is a conditional test, not an exact forecast. Reopen decisions on material evidence changes, not at every routine edit.
 - In existing codebases, preserve established version constraints and lockfile stability without uncoordinated major-version drift. However, when introducing **new** libraries, packages, or SDK integrations, always strictly resolve and pin the **latest stable version** from the official registry rather than guessing outdated versions from model training memory.
 - For greenfield projects, new modules, or SDK integrations, always use the **official boilerplate, CLI installer, or generator** (e.g., `uv init`, `cargo init`, `bun create`, official SDK starters). Hand-rolling ad-hoc scaffolding from memory introduces missing build flags, broken toolchains, and dirty slop.
 - UI microcopy should be succinct, high-signal, and respectful of the user's attention. Tooltips and helper text should clarify non-obvious interactions, not narrate obvious UI controls.

package/scripts/decision_guard.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Check decision-record completeness; never certify the truth of its evidence."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def filled(value):
+    """Check whether value is a non-empty string after stripping whitespace."""
+    return isinstance(value, str) and bool(value.strip())
+
+
+def one_of(value, allowed):
+    """Check whether value is a string belonging to the allowed collection."""
+    return isinstance(value, str) and value in allowed
+
+
+def _audit_architecture(packet, require):
+    """Validate architecture-specific decision axes, alternatives, and horizon stress scenarios."""
+    axes = packet.get("decision_axes")
+    require(isinstance(axes, list) and len(axes) > 0, "MISSING_DECISION_AXES", "Compare independent decision axes instead of assuming a bundled stack")
+    if isinstance(axes, list):
+        for index, axis in enumerate(axes):
+            if not isinstance(axis, dict):
+                require(False, "INVALID_DECISION_AXIS", f"decision_axes[{index}] must be an object")
+                continue
+            name = axis.get("name")
+            considered = axis.get("considered")
+            selected = axis.get("selected")
+            eliminated = axis.get("eliminated") if isinstance(axis.get("eliminated"), list) else []
+            eliminated_set = set(map(str, eliminated))
+            active_considered = [c for c in considered if str(c) not in eliminated_set] if isinstance(considered, list) else []
+            constraint_rationale = axis.get("constraint_rationale")
+            has_single_flag = axis.get("single_candidate") is True
+            has_rationale = filled(constraint_rationale)
+            is_single_candidate = has_single_flag or has_rationale
+
+            if is_single_candidate:
+                valid = (filled(name) and isinstance(considered, list)
+                         and len(active_considered) == 1
+                         and filled(active_considered[0])
+                         and filled(selected) and selected == active_considered[0]
+                         and has_rationale)
+                require(valid, "INVALID_DECISION_AXIS", f"decision_axes[{index}] single candidate requires exactly one active candidate with constraint_rationale")
+            else:
+                valid = (filled(name) and isinstance(considered, list)
+                         and len(set(map(str, active_considered))) >= 2
+                         and all(filled(v) for v in active_considered)
+                         and filled(selected) and selected in active_considered)
+                require(valid, "INVALID_DECISION_AXIS", f"decision_axes[{index}] must compare >=2 distinct candidates and select one")
+
+    alternatives = packet.get("alternatives")
+    has_alts_list = isinstance(alternatives, list)
+    alt_names = [item.get("name").strip() for item in alternatives if isinstance(item, dict) and filled(item.get("name"))] if has_alts_list else []
+    distinct_alt_names = set(alt_names)
+    packet_rationale = packet.get("constraint_rationale")
+    if not packet_rationale and isinstance(packet.get("decision"), dict):
+        packet_rationale = packet.get("decision", {}).get("constraint_rationale")
+    is_single_alt = packet.get("single_candidate") is True or filled(packet_rationale)
+
+    if is_single_alt:
+        require(
+            has_alts_list and len(alternatives) == 1 and len(distinct_alt_names) == 1 and len(alt_names) == 1,
+            "MISSING_ALTERNATIVES",
+            "Single candidate architecture record must contain exactly one alternative"
+        )
+        require(filled(packet_rationale), "MISSING_CONSTRAINT_RATIONALE", "Single candidate requires constraint_rationale explaining eliminated alternatives")
+    else:
+        require(
+            has_alts_list and len(alternatives) >= 2 and len(distinct_alt_names) >= 2 and len(alt_names) == len(alternatives),
+            "MISSING_ALTERNATIVES",
+            "Compare at least two distinct architectural alternatives"
+        )
+    if has_alts_list:
+        for index, item in enumerate(alternatives):
+            valid = isinstance(item, dict) and all(filled(item.get(key)) for key in ("name", "benefit", "risk", "reversal"))
+            require(valid, "INVALID_ALTERNATIVE", f"alternatives[{index}] needs benefit, risk and reversal path")
+
+    horizons = packet.get("horizons")
+    valid_horizons = isinstance(horizons, list) and all(
+        isinstance(item, dict) and one_of(item.get("stage"), {"now", "later"})
+        and filled(item.get("scenario")) and filled(item.get("consequence"))
+        for item in horizons
+    )
+    require(valid_horizons, "INVALID_HORIZONS", "horizons requires stage (now/later), scenario and consequence")
+    if isinstance(horizons, list):
+        require(any(isinstance(item, dict) and item.get("stage") == "later" for item in horizons),
+                "MISSING_FUTURE_SCENARIO", "Test at least one credible future growth, failure or migration scenario")
+        require(any(isinstance(item, dict) and item.get("stage") == "now" for item in horizons),
+                "MISSING_CURRENT_SCENARIO", "Evaluate the near-term operational reality")
+
+
+def _audit_proceed(packet, direct, valid_direct, decision, valid_decision, evidence, require):
+    """Validate conditions required when a decision concludes with a proceed action."""
+    if not (valid_direct and valid_decision and decision.get("action") == "proceed"):
+        return
+    grounded = isinstance(evidence, list) and any(
+        isinstance(item, dict) and one_of(item.get("level"), {"observed", "derived"})
+        for item in evidence
+    )
+    require(grounded, "NO_GROUNDED_EVIDENCE", "Proceed requires at least one observed or derived source; inference alone is insufficient")
+    if direct.get("status") == "unknown":
+        require(False, "DIRECT_PATH_UNRESOLVED", "Investigate direct path or pause before committing")
+    if direct.get("status") == "found":
+        handling = decision.get("direct_path_handling")
+        require(one_of(handling, {"use", "bypass"}), "DIRECT_PATH_OVERRIDE_REQUIRED", "Explicitly use the direct path or justify bypassing it")
+        if handling == "bypass":
+            require(filled(decision.get("direct_override_reason")), "DIRECT_PATH_OVERRIDE_REQUIRED", "Explain why an indirect approach beats the observed direct answer")
+
+
+def audit(packet):
+    """Audit a decision packet against structural completeness requirements."""
+    findings = []
+
+    def require(condition, code, message):
+        if not condition:
+            findings.append({"code": code, "message": message})
+
+    kind = packet.get("kind")
+    require(one_of(kind, {"investigation", "architecture"}), "INVALID_KIND", "kind must be investigation or architecture")
+    for key in ("goal", "proposal"):
+        require(filled(packet.get(key)), "MISSING_" + key.upper(), key + " must be nonempty")
+
+    evidence = packet.get("evidence")
+    require(isinstance(evidence, list) and len(evidence) > 0, "MISSING_EVIDENCE", "List at least one traceable source and finding")
+    if isinstance(evidence, list):
+        for index, item in enumerate(evidence):
+            valid = (isinstance(item, dict) and filled(item.get("source"))
+                     and filled(item.get("finding"))
+                     and one_of(item.get("level"), {"observed", "derived", "inferred"}))
+            require(valid, "INVALID_EVIDENCE", f"evidence[{index}] requires source, finding and valid level")
+
+    direct = packet.get("direct_check")
+    valid_direct = (isinstance(direct, dict)
+                    and one_of(direct.get("status"), {"found", "not_found", "unknown", "not_applicable"})
+                    and filled(direct.get("source")) and filled(direct.get("finding")))
+    require(valid_direct, "MISSING_DIRECT_CHECK", "Record direct-answer/source search, including unknown or unavailable evidence")
+    if valid_direct and kind == "investigation":
+        require(direct["status"] != "not_applicable", "DIRECT_CHECK_SKIPPED", "Investigations must inspect or explicitly mark the direct source unknown")
+
+    assumptions = packet.get("assumptions", [])
+    require(isinstance(assumptions, list), "INVALID_ASSUMPTIONS", "assumptions must be a list")
+    if isinstance(assumptions, list):
+        for index, item in enumerate(assumptions):
+            valid = (isinstance(item, dict) and filled(item.get("claim"))
+                     and one_of(item.get("state"), {"verified", "unverified"})
+                     and filled(item.get("basis")))
+            require(valid, "INVALID_ASSUMPTION", f"assumptions[{index}] must distinguish verified from unverified")
+
+    decision = packet.get("decision")
+    valid_decision = isinstance(decision, dict) and one_of(decision.get("action"), {"proceed", "pause", "stop"})
+    require(valid_decision, "MISSING_DECISION", "decision.action must be proceed, pause or stop")
+    if isinstance(decision, dict):
+        for key in ("choice", "reason", "invalidated_by"):
+            require(filled(decision.get(key)), "MISSING_DECISION_FIELD", f"decision.{key} is required")
+
+    if kind == "architecture":
+        _audit_architecture(packet, require)
+
+    _audit_proceed(packet, direct, valid_direct, decision, valid_decision, evidence, require)
+
+    return {
+        "record_status": "complete" if not findings else "incomplete",
+        "decision_action": decision.get("action") if isinstance(decision, dict) and isinstance(decision.get("action"), str) else None,
+        "machine_check_only": True,
+        "findings": findings,
+    }
+
+
+def main():
+    """Parse command-line arguments and run the decision-record audit."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=["audit"])
+    parser.add_argument("record", type=Path)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    try:
+        packet = json.loads(args.record.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError) as error:
+        print(f"Invalid JSON or unreadable decision record: {error}", file=sys.stderr)
+        return 1
+    if not isinstance(packet, dict):
+        print("Invalid JSON: decision record must be an object", file=sys.stderr)
+        return 1
+    result = audit(packet)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Decision record: {result['record_status']} ({result['decision_action']})")
+        for finding in result["findings"]:
+            print(f"  {finding['code']}: {finding['message']}")
+        print("Structural check only; sources and reasoning require independent verification.")
+    return 2 if result["findings"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/sre_guard.py

@@ -130,7 +130,7 @@ def normalize_line(line):
     stripped = line.strip()
     if not stripped or stripped.startswith(('#', '//', '/*', '*', 'import ', 'from ', 'package ', 'use ')):
         return ''
-    if (stripped.startswith('"') and stripped.endswith('"')) or (stripped.startswith("'") and stripped.endswith("'")):
+    if re.fullmatch(r'''(?:"[^"]*"|'[^']*'),?''', stripped):
         return ''
     if stripped in ('{', '}', '(', ')', '};', '];', ');', 'return', ']', '['):
         return ''