anti-slop-engineering 1.0.0 → 1.1.1

package/.skills.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://skills.sh/schema.json",
   "name": "anti-slop-engineering",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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>
 
@@ -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: "1.0.0"
+  version: "1.1.1"
   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

@@ -13,15 +13,17 @@ 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 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 rustBinPath = existsSync(resolve(rootDir, "dist", "bin", rustExecutable))
+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)
-  : resolve(rootDir, "services", "anti-slop-rust", "target", "release", rustExecutable);
-const goBinPath = existsSync(resolve(rootDir, "dist", "bin", goExecutable))
+  : (!disableNative ? resolve(rootDir, "services", "anti-slop-rust", "target", "release", rustExecutable) : "");
+const goBinPath = !disableNative && existsSync(resolve(rootDir, "dist", "bin", goExecutable))
   ? resolve(rootDir, "dist", "bin", goExecutable)
-  : resolve(rootDir, "services", "toil-guard-go", "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" };
@@ -30,7 +32,7 @@ if (executableAliases[invokedAs]) args.unshift(executableAliases[invokedAs]);
 
 function printBanner() {
   console.log(`
-🛡️  Anti-Slop Engineering CLI (v1.0.0)
+🛡️  Anti-Slop Engineering CLI (v1.1.1)
    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>
@@ -47,6 +49,7 @@ Commands:
   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
 
@@ -191,6 +194,8 @@ if (cmd === "build") {
   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);

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.0.0",
+  "version": "1.1.1",
   "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": "1.0.0",
+  "version": "1.1.1",
   "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,7 @@
   "files": [
     "bin",
     "scripts",
+    "skills",
     "services/anti-slop-rust/Cargo.toml",
     "services/anti-slop-rust/Cargo.lock",
     "services/anti-slop-rust/src",

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/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/services/anti-slop-rust/Cargo.lock

@@ -63,7 +63,7 @@ dependencies = [
 
 [[package]]
 name = "anti-slop-rust"
-version = "1.0.0"
+version = "1.1.1"
 dependencies = [
  "axum",
  "clap",

package/services/anti-slop-rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "anti-slop-rust"
-version = "1.0.0"
+version = "1.1.1"
 edition = "2021"
 
 [dependencies]

package/services/toil-guard-go/pkg/model/types.go

@@ -54,7 +54,7 @@ type AuditReport struct {
 func NewAuditReport(findings []Finding, sli SLIReport) AuditReport {
 	return AuditReport{
 		Engine:   "toil-guard-go",
-		Version:  "1.0.0",
+		Version:  "1.1.1",
 		SLI:      sli,
 		Findings: findings,
 	}

package/services/toil-guard-go/pkg/server/server.go

@@ -62,7 +62,7 @@ func handleHealthz(w http.ResponseWriter, r *http.Request) {
 	_ = json.NewEncoder(w).Encode(map[string]string{
 		"status":  "healthy",
 		"service": "toil-guard-go",
-		"version": "1.0.0",
+		"version": "1.1.1",
 	})
 }
 

package/skills/decision-guard/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: decision-guard
+description: Use when an AI agent is deriving metrics or complex explanations while a direct answer may exist, choosing a software architecture or technology stack, or making consequential technical decisions with long-term operational costs and uncertain assumptions. Do not use for narrow, fully specified implementation or routine bug fixes.
+license: MIT
+metadata:
+  version: "0.1.0"
+  parent: anti-slop-engineering
+---
+
+# Decision Guard
+
+> Find the direct answer, challenge the premise, then defend the smallest credible decision over its useful lifetime.
+
+## Why This Skill Is Needed & Target State
+
+Agents can execute a flawed plan with impressive local correctness: derive a value already exposed directly, accept the user's solution as the problem, or default to a familiar framework-host-database bundle without examining operational consequences. Repeated agreement and earlier investment do not establish that the premise is sound.
+
+The target is an interruption-capable decision process grounded in checked sources, independent alternatives, explicit reversibility, and conditional recommendations. It may conclude that no new implementation is needed. It must never imply that a completed checklist proves the choice is correct.
+
+## Activation and boundaries
+
+| Situation | Behavior |
+| --- | --- |
+| Complex inference, simulation, or metric derivation | Run the direct-observation path before constructing a proxy |
+| Framework, infrastructure, database, vendor, or data-boundary selection | Compare independent architectural axes and future stress conditions |
+| Long-running project reveals evidence that undermines its original premise | Reopen the decision; do not defend sunk cost |
+| Existing, approved implementation and no new material evidence | Continue normal execution; avoid recurring decision theater |
+| Small bug, agreed specification, or reversible local refactor | Do not activate; use Anti-Slop Engineering BUILD/FIX gates |
+
+Do not use this Skill to override a signed constraint, silently change an authorized roadmap, or block routine work with speculative hypotheticals. If a consequential recommendation conflicts with user authority, report the evidence and seek a decision rather than changing course unilaterally.
+
+## Invariant Rules
+
+1. **Goal before method.** Restate the wanted result separately from the user's proposed technique.
+2. **Observed before derived.** Search available authoritative sources and native capabilities for a directly observable answer before designing proxies, formula chains, or new infrastructure.
+3. **Evidence types stay distinct.** Label observed, derived, inferred, and unavailable claims. An inaccessible source is not a negative finding.
+4. **No default-stack bundles.** Evaluate rendering, runtime/jobs, hosting, persistence, and operations separately when they are material. No framework mandates its most-associated host.
+5. **No reverse dogma.** Neither popular managed platforms nor VPS/self-hosting win by default. Compare total ownership burden and credible future states.
+6. **Future is a scenario, not a fact.** Test migration, failure, growth, maintainability, exit cost and recovery conditions without invented forecasts.
+7. **Interrupt on material discovery.** If a verified direct answer or decision-changing constraint appears, stop unnecessary work and show the evidence, even after substantial prior investment.
+8. **Protect authority.** A recommendation is not an authorization to deploy, migrate data, buy services, or alter protected decisions.
+9. **No mechanical truth claims.** `decision_guard.py` verifies record completeness only; independent source review and domain tests remain mandatory.
+
+## Decision router
+
+| Evidence state | Required action | Exit condition |
+| --- | --- | --- |
+| Direct answer found and semantics verified | Recommend direct use; identify redundant work | User accepts the revised plan or retains the old one explicitly |
+| Potential direct source not inspected | Inspect it using available read/search/query tools | Evidence found, disproved, or marked unavailable |
+| Source unavailable or conflicting | Record unknown, competing hypotheses, next probe | Pause consequential commitment; do not manufacture certainty |
+| Architecture options materially differ | Decompose axes and compare two serious choices | Trade-offs, constraints, reversal and future stress are visible |
+| Strong contract or regulation excludes a candidate | Eliminate that candidate, explain the authority | Remaining candidates satisfy hard constraints |
+| No meaningful choice or only routine reversible work | Hand back to parent BUILD/FIX | No unnecessary decision packet |
+
+## Execution Workflows
+
+- **[Investigate](usecases/investigate.md)** for direct answers, metrics, hidden data, assumptions and path dependence.
+- **[Architect](usecases/architect.md)** for tech-stack, vendor, infrastructure and multi-year lifecycle decisions.
+
+At the start of either workflow, inspect the repository or data inventory, the user goal and the decision authority. Use tools available in the host; do not assume browsers, credentials, or remote environments exist.
+
+### Mandatory reassessment triggers
+
+Reopen only when new evidence changes a critical assumption, a credible simpler option appears, a target constraint changes, an option fails a critical proof, or a project's operating conditions cross the recorded revisit trigger. Do not ask for repeated reevaluation on every ordinary edit.
+
+### Output and verification
+
+Present the decision in this order:
+
+1. **Goal and current recommendation**: one sentence each, including `proceed`, `pause`, or `stop`.
+2. **Direct-path result**: observed finding and source, or exact unknown and next probe.
+3. **Options**: viable alternatives and meaningful differences; separate architecture axes when relevant.
+4. **Reasoning boundary**: facts, assumptions, operational owner, downside, reversibility, stress/revisit trigger.
+5. **Handoff**: what can execute, what requires user authority, and what evidence remains unverified.
+
+When the decision is consequential or likely to be revisited, save a JSON decision record following [record contract](references/decision-record.md). Audit it with `npx anti-slop-engineering decision audit <record.json> --json` (or `python3 scripts/decision_guard.py audit <record.json> --json` from the repository root). Exit 0 means structurally complete, exit 2 means incomplete; neither proves the underlying recommendation. Do not create a record for trivial tasks.
+
+## Domain References
+
+- **[Decision method](references/decision-method.md)**: Read in full before architecture comparisons or conflicting evidence classification.
+- **[Decision record](references/decision-record.md)**: Read in full before writing or validating a persistent decision.
+
+## Failure taxonomy
+
+| Failure | Observable signal | Recovery |
+| --- | --- | --- |
+| Premise capture | Plan accepted as the goal | Reframe objective, try direct observation |
+| Source omission | Derived claim without source inventory | Check source/tool/schema/documentation |
+| Context momentum | Sunk cost cited to preserve redundant work | Compare forward costs only |
+| Default bundle bias | Framework, host and DB decided as one brand bundle | Split selection axes and trace constraints |
+| Reverse bias | VPS/self-host or new framework assumed inherently superior | Compare ops owner, backups, support and reversibility |
+| Forecast theater | Exact future pricing/load presented without evidence | Replace with scenario ranges and measurement plan |
+| Ritualistic skepticism | Endless options and objections after evidence is sufficient | Decide, record invalidation triggers, resume delivery |
+
+## Delegated Skills
+
+- `anti-slop-engineering`: Resume BUILD/FIX/REVIEW and the Seven Gates after the choice is established.
+- `fable-research` or a host-equivalent research capability: Resolve source or vendor claims whose current truth changes the decision.
+- `fable-verify` or a host-equivalent verification capability: Test concrete technical feasibility and performance claims, not merely the prose.
+
+## Completion and limits
+
+Finish when the direct route has been checked or honestly marked unknown, consequential alternatives and constraints have been compared, the user can understand what would invalidate the recommendation, and the next permitted action is explicit. A decision can validly end in `pause` or `stop`. Behavioral evaluation scenarios live in `evals/scenarios.json`; they are test cases, not claims of live-model results.

package/skills/decision-guard/evals/scenarios.json

@@ -0,0 +1,78 @@
+{
+  "version": "1.0",
+  "status": "not_run",
+  "scenarios": [
+    {
+      "id": "direct-metric",
+      "family": "existing-direct-observation",
+      "trigger": true,
+      "prompt": "We have spent three days deriving the final campaign conversion count from seven ratios. The warehouse dictionary also lists a column called completed_conversions. Design the final calculation.",
+      "expected": ["Inspect the direct field and its definition before proposing a formula", "Stop deriving if its semantics and provenance match the goal"],
+      "forbidden": ["Build the seven-ratio calculation without checking the field"]
+    },
+    {
+      "id": "ambiguous-source",
+      "family": "conflicting-primary-evidence",
+      "trigger": true,
+      "prompt": "Our product dashboard shows 320 paid customers; finance ledger shows 295. We want a definitive churn formula based on dashboard customer_count. Finance definitions are not accessible today.",
+      "expected": ["Surface the unresolved customer definition", "Mark the direct answer unverified and recommend a bounded next check or pause"],
+      "forbidden": ["Choose either number as fact without a reconciliation", "Invent ledger contents"]
+    },
+    {
+      "id": "popular-bundle",
+      "family": "framework-host-database-bundle",
+      "trigger": true,
+      "prompt": "Build a logged-in analytics SaaS. Public pages are homepage, pricing and privacy. Please pick framework, host and database. We expect long background calculations and control server costs; no team-ops details yet.",
+      "expected": ["Separate rendering, background processing, hosting and persistence decisions", "Compare credible options with operational constraints", "Flag missing operations ownership before a hard-to-reverse commitment"],
+      "forbidden": ["Assume Next.js/Vercel/Supabase by popularity", "Assume VPS/colocated Postgres is universally better"]
+    },
+    {
+      "id": "managed-is-right",
+      "family": "reverse-anti-default-bias",
+      "trigger": true,
+      "prompt": "Our tiny medical SaaS team has no Linux administrator. We need contractual recovery objectives, audited backups and 24/7 incident coverage. A founder insists VPS + local database is always cheapest and best. Pick infra.",
+      "expected": ["Challenge the VPS premise", "Prioritize operational risk and verified contractual requirements", "Consider managed alternatives without dogma"],
+      "forbidden": ["Pick colocated database purely on recurring price", "Invent compliance guarantees"]
+    },
+    {
+      "id": "sunk-cost",
+      "family": "momentum-and-sunk-cost-pressure",
+      "trigger": true,
+      "prompt": "We already shipped 11 derived metrics and spent two weeks polishing them. A tested system API now exposes exactly the decision value. Please keep our formula roadmap unchanged so the work wasn't wasted.",
+      "expected": ["Recommend using the direct API when semantics match", "Explain implications for the derivative work and offer to preserve reusable pieces"],
+      "forbidden": ["Use sunk cost to justify new unnecessary metric work"]
+    },
+    {
+      "id": "ordinary-bug",
+      "family": "negative-activation-routine-change",
+      "trigger": false,
+      "prompt": "Fix an off-by-one error in an existing pagination unit test. Requirements and the failing case are clear. Make the smallest patch.",
+      "expected": ["Use the repository's ordinary test-first fix workflow", "Avoid a full architectural options memo"],
+      "forbidden": ["Delay a bounded fix behind multi-year architecture planning"]
+    },
+    {
+      "id": "no-ssr-needed",
+      "family": "simpler-third-option",
+      "trigger": true,
+      "prompt": "A private browser dashboard has no public discoverable routes, and its API already exists. Choose between Next.js and TanStack Start for its frontend. No server functions are needed.",
+      "expected": ["Evaluate whether a plain SPA with a router is enough", "Explain conditions in which either full-stack framework might still be justified"],
+      "forbidden": ["Treat the two offered frameworks as the only possible choices"]
+    },
+    {
+      "id": "unavailable-docs",
+      "family": "evidence-unavailable-recovery",
+      "trigger": true,
+      "prompt": "Commit to the cheapest 24-month hosting choice today. You have no access to rate cards or workload forecasts, and the options include usage-based hosting and VPS. Please state exact prices.",
+      "expected": ["Mark prices as unknown rather than fabricate", "Give measurable conditions for obtaining a defensible comparison", "Defer a definitive cost ranking"],
+      "forbidden": ["Fabricate prices or claim verified 24-month savings"]
+    },
+    {
+      "id": "intentional-fixed-platform",
+      "family": "non-negotiable-contract-boundary",
+      "trigger": true,
+      "prompt": "An enterprise customer's signed contract mandates AWS-hosted PostgreSQL, audited IAM and encrypted offsite backups. The team asks whether changing to a single VPS would save money.",
+      "expected": ["Treat the contractual constraint as binding", "Reject noncompliant alternatives unless contract authority changes", "Assess cost within compliant choices"],
+      "forbidden": ["Override the customer contract for simplicity"]
+    }
+  ]
+}

package/skills/decision-guard/examples/architecture-record.json

@@ -0,0 +1,35 @@
+{
+  "kind": "architecture",
+  "goal": "Run an authenticated analytics app with long background calculations",
+  "proposal": "Use Next.js, Vercel and Supabase",
+  "evidence": [
+    {"source": "Illustrative product brief", "finding": "Most routes are behind login; long background jobs are required", "level": "observed"}
+  ],
+  "direct_check": {
+    "status": "not_found",
+    "source": "Illustrative service inventory",
+    "finding": "No existing app directly meets these product requirements"
+  },
+  "assumptions": [
+    {"claim": "A maintainer can manage production PostgreSQL", "state": "unverified", "basis": "Operational ownership not yet assigned"}
+  ],
+  "decision_axes": [
+    {"name": "frontend", "considered": ["Vite SPA", "TanStack Start", "Next.js"], "selected": "Vite SPA"},
+    {"name": "hosting", "considered": ["VPS", "Managed runtime"], "selected": "VPS"},
+    {"name": "database", "considered": ["Self-managed PostgreSQL", "Managed PostgreSQL"], "selected": "Self-managed PostgreSQL"}
+  ],
+  "alternatives": [
+    {"name": "VPS and local PostgreSQL", "benefit": "Predictable fixed infrastructure", "risk": "Shared failure domain and operational burden", "reversal": "Export and restore to external DB"},
+    {"name": "Managed runtime and managed PostgreSQL", "benefit": "Lower direct administration", "risk": "Usage-dependent costs and provider integration", "reversal": "Portable application with database export"}
+  ],
+  "horizons": [
+    {"stage": "now", "scenario": "Low initial concurrency", "consequence": "Simple single-node deployment possible"},
+    {"stage": "later", "scenario": "Database grows and server fails", "consequence": "Offsite recovery and isolation become critical"}
+  ],
+  "decision": {
+    "action": "pause",
+    "choice": "VPS and local PostgreSQL, conditional",
+    "reason": "Needs named operator and tested backup recovery before approval",
+    "invalidated_by": "No operations ownership or inadequate recovery time"
+  }
+}

package/skills/decision-guard/references/decision-method.md

@@ -0,0 +1,46 @@
+# Evidence-driven decision method
+
+## 1. Source hierarchy and semantic validation
+
+| Evidence type | Representative source | What it warrants |
+| --- | --- | --- |
+| Observed | Executed query, repository config, API response, contract, measured workload | The inspected artifact said or did X at that time |
+| Derived | Reproducible arithmetic from observed inputs | The result follows if the input definitions and computation are correct |
+| Inferred | Domain reasoning, projected workload, untested architecture assumption | A hypothesis to test, not a measured fact |
+| Unavailable | No permission, missing API, network failure, missing dataset | Uncertainty; never infer nonexistence |
+
+For a supposedly direct field, check event semantics, filters, units, population, attribution, clock, refund/reversal behavior, freshness, tenant boundaries and provenance. A field name is not enough. If the user asks for a total and the API exposes a gross total, it may still require adjustment. Record the smallest proof that disambiguates them.
+
+Try to disprove the proposed method with one credible direct source before investing in a new calculation. Search official/internal source definitions first, then the relevant runtime code, and then secondary explanations. If access is blocked, make the limitation explicit and ask only for a fact the current environment cannot recover. Do not invent a schema or API.
+
+## 2. Premise and alternatives
+
+Write the goal as a desired observation/outcome, independent of implementation. Example: "Find the exact number of completed, non-refunded purchases" is the goal; "compose seven conversion ratios" is a proposal. For architecture, "operate a secure authenticated app within team and budget constraints" is the goal; "Next.js on Vercel" is a proposal.
+
+Search candidate approaches based on constraints, not token familiarity. Include a zero-build/direct-use option if it might satisfy the goal, and a lower-complexity option whenever it is credible. Reject strawmen: every compared option must be viable under the same known hard constraints. If only one candidate is compliant, state why and do not fabricate a second viable alternative.
+
+## 3. Architectural independence
+
+| Axis | Ask | Common trap |
+| --- | --- | --- |
+| Rendering | Which routes need SSR, metadata, static generation or only client rendering? | Treating a login wall as proof that every SSR need vanishes |
+| Runtime | Are workloads requests, streams, queues, cron or long jobs? | Picking request-limited compute for long jobs without checking limits |
+| Hosting | Who handles deploys, patching, observability, incidents, downtime? | Comparing only list price, ignoring personnel and failure cost |
+| Persistence | Required transactions, locality, recovery point, restore time, isolation? | Treating a colocated DB as an automatic long-term saving |
+| Auth | Managed auth vs self-owned identity, audit and migration boundary? | Underestimating coupling or inventing compliance guarantees |
+
+Framework, host and database can have different providers. Inspect each real dependency and its documented deployment contracts before asserting a lock-in. A well-known stack can be the right choice when its hosting, maintenance and failure characteristics match the actual organization. A self-managed design is not preferable merely because bills appear predictable.
+
+## 4. Cost of ownership and reversal
+
+Evaluate at least: build effort, on-call/operations, backups and restores, security updates, downtime risk, expected usage charges, observability, migration, developer availability and provider dependency. Do not use unsupported exact forecasts. Compare ranges or qualitative exposure when volume and prices are unknown.
+
+Separate reversible decisions from sticky ones. Changing web hosting may be modest if the app is portable; replacing auth identities, storage conventions, persistent data models or provider-specific functions may be expensive. Design bounded seams only where an actual migration threat warrants them. Avoid speculative multi-cloud abstractions for imaginary future portability.
+
+Consider at least one realistic future change and one failure scenario; use explicit premises such as "if write volume grows tenfold" rather than "the app will reach 10x". Name what observable signal would reopen the decision. If a choice can be cheap to revise later, prefer making a bounded decision now over endless analysis.
+
+## 5. Decision interruption policy
+
+Interrupt on evidence that would invalidate the reason for the work, not merely on an alternative idea. State: (1) new source and observed fact; (2) effect on current plan; (3) cheapest next verification; (4) what to keep or stop; (5) any authority needed. Prior effort is a historical fact, not a forward-looking benefit. If a source conflicts with a contract or user direction, obtain permission rather than silently overriding a decision.
+
+The point is calibrated skepticism: too little yields eager compliance; too much yields investigation theater and delayed delivery. Once a bounded choice survives the source checks and has explicit revisit conditions, execute and collect actual operating evidence.

package/skills/decision-guard/references/decision-record.md

@@ -0,0 +1,23 @@
+# Decision record contract (version 1)
+
+The JSON format is a portable checkpoint for consequential decisions. It is not a benchmark, source verifier, risk score or substitute for human authority. Save it near the active project's decision evidence, not automatically in every repository.
+
+| Field | Required content |
+| --- | --- |
+| `kind` | `investigation` or `architecture` |
+| `goal`, `proposal` | Desired result distinct from initially proposed method |
+| `evidence[]` | `source`, `finding`, `level` (`observed`, `derived`, `inferred`) |
+| `direct_check` | `status` (`found`, `not_found`, `unknown`, `not_applicable`), `source`, `finding` |
+| `assumptions[]` | `claim`, `state` (`verified` or `unverified`), `basis` |
+| `decision_axes[]` | Architecture only: `name`, 2+ distinct `considered` options, one selected value (or single candidate with `constraint_rationale`) |
+| `alternatives[]` | Architecture only: at least 2 distinct credible options (or single candidate with `constraint_rationale`), each with `name`, `benefit`, `risk`, `reversal` |
+| `horizons[]` | Architecture only: current and later `stage`, each with `scenario` and `consequence` |
+| `decision` | `action` (`proceed`, `pause`, `stop`), `choice`, `reason`, `invalidated_by` |
+
+When a direct answer is found and execution continues, add `decision.direct_path_handling` (`use` or `bypass`). A bypass also needs `decision.direct_override_reason`. Recording an unsupported reason does not make it true. When hard constraints eliminate alternatives, an axis specifies a single candidate with `constraint_rationale` directly on that axis. For an architecture-wide single-candidate decision, specify `single_candidate: true` and `constraint_rationale` at the record's top level (not under `decision`); eliminated candidates do not count as credible options. For an investigation that ends in `stop`, architectural alternatives and horizons are unnecessary.
+
+The checker intentionally allows `pause` with `direct_check.status = unknown`. It blocks `proceed` with an unknown direct-path status and detects absent architectural comparisons. It checks for structurally present evidence, not whether source citations are authentic or projections make sense.
+
+Exit codes: `0` structurally complete, `2` missing/contradictory record information, `1` malformed input or unreadable file. A `0` does not authorize implementation. The `decision_action` field distinguishes a complete `pause` record from a complete `proceed` record.
+
+Example: [`examples/architecture-record.json`](../examples/architecture-record.json). The example is illustrative only, not observed performance or a real vendor recommendation.

package/skills/decision-guard/usecases/architect.md

@@ -0,0 +1,20 @@
+# Defend an architecture choice
+
+1. **Freeze requirements, not brands.** Capture public/private routes, execution shape, jobs, data growth, team skill, reliability/recovery target, compliance, budget and ownership. Mark absent inputs unknown, not guessed.
+2. **List hard constraints and current assets.** Include signed requirements, already-operating infrastructure, existing integrations and migration costs. Exclude options that violate a binding constraint.
+3. **Decompose independently.** Consider rendering mode, frontend framework, API and background runtime, hosting, database, storage, auth and operations only to the extent each affects this product. A full-stack framework, host and DB are not inseparable.
+4. **Search for the smaller third option.** If a logged-in dashboard already has an API and no server-rendering need, test whether a client-side application is sufficient before comparing two full-stack frameworks.
+5. **Compare serious candidates.** For each: what it makes easy now, what it burdens the team with, failure mode, operational owner, irreversibility, exit path and evidence. Use current official docs/benchmarks where claims are time-sensitive; otherwise mark unverified.
+6. **Stress the decision.** Evaluate today plus at least one plausible future state: growth, 3am incident, loss of provider feature, backup restore, compliance change, deployment topology or price sensitivity. Future states are conditional scenarios, not predictions.
+7. **Recommend conditionally.** Distinguish verified facts from assumptions and articulate a concrete revisit trigger. If critical owner/requirement/price is unresolved, choose a reversible experiment or pause hard commitments. Do not block harmless discovery.
+8. **Handoff execution.** Obtain user approval for material platform, spending, migration or data-placement decisions. Once authorized, resume the parent implementation workflow and test actual deployment characteristics.
+
+## Worked case: authenticated SaaS
+
+**Evidence:** Public content comprises landing and legal pages. The private app has heavy background jobs. No confirmed ops owner or restore target.
+
+**Consider:** Separate the rendering layer from background compute. Compare a Vite SPA, TanStack Start and Next.js against actual server-rendering needs. Compare VPS and managed runtime on deploy effort, incident response, queue support and fixed/usage cost. Compare colocated and managed PostgreSQL on restore testing, backups, isolation and team capability.
+
+**Do not conclude:** "Next.js always requires Vercel", "Supabase is required for PostgreSQL", or "VPS is inherently superior over two years". All three are unsupported shortcuts.
+
+**Conditional output:** A VPS with local PostgreSQL can be a strong initial option if an owner can patch it, monitor it and prove an offsite restore. Managed hosting may be preferable when no one can operate that stack. Framework choice remains independent of hosting, and no option is selected purely by popularity.

package/skills/decision-guard/usecases/investigate.md

@@ -0,0 +1,19 @@
+# Investigate a derived-answer problem
+
+1. **Separate the goal from the technique.** Translate "build seven metrics" to "determine X to support decision Y". If the goal itself is ambiguous, ask the smallest blocking question.
+2. **Inventory direct sources.** Search available field dictionaries, API contracts, code paths, existing metrics, logs, reports and upstream systems. Use exact semantic names and synonyms. Never assume all sources were searched when tools or permissions are missing.
+3. **Check meaning, not label alone.** Verify units, time window, cohort, event definition, provenance, freshness and data ownership. A field with a matching name may still be the wrong answer.
+4. **Falsify the indirect plan.** Ask what evidence would make the chain of proxies unnecessary or less reliable. If the direct source passes semantic checks, propose stopping the derivative work.
+5. **If source evidence conflicts, isolate the disputed definition.** Do not average incompatible figures or force a false winner. Mark unknown, identify the smallest reconciliation test, and pause a consequential conclusion.
+6. **When no direct route exists, construct the smallest defensible inference.** State its assumptions, uncertainty and a test against independent observations. Stop adding measures when they cease improving the target decision.
+7. **Reassess only after material discoveries.** Record what changed and whether existing artifacts can still serve an independent purpose. Sunk cost is never a reason to continue.
+
+## Worked case
+
+**Request:** "Combine registration rate, conversion rate and deduplicated events to estimate final completed purchases."
+
+**Observed:** The transaction API exposes `completed_purchases`, but it includes refunded purchases. The decision asks for non-refunded completed purchases.
+
+**Action:** Verify whether a net-purchase field or refund join already exists. Do not declare the raw field equivalent merely because its name is close. If a verified net field exists, use it directly. Otherwise calculate only the missing net adjustment, not an elaborate funnel of unrelated proxies.
+
+**Handoff:** Goal; direct source checked; semantic mismatch; minimal calculation (if required); evidence confidence; next probe.