anti-slop-engineering 1.2.1 → 1.4.0

package/scripts/future_scale_guard.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Check future-scale architectural decision records for structural completeness."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def filled(value, depth=0, max_depth=100):
+    if depth > max_depth:
+        return False
+    return isinstance(value, str) and bool(value.strip())
+
+
+def choice(value, values):
+    return isinstance(value, str) and value in values
+
+
+def _record_finding(findings, ok, code, message, severity="block", depth=0, max_depth=100):
+    if depth > max_depth:
+        return
+    if not ok:
+        findings.append({"severity": severity, "code": code, "message": message})
+
+
+def check_scenarios(record, proceeding, require):
+    scenarios = record.get("scenarios")
+    require(isinstance(scenarios, list), "INVALID_SCENARIOS", "scenarios must be a list")
+    if not isinstance(scenarios, list):
+        return {}
+    ids = {}
+    for index, item in enumerate(scenarios):
+        valid = (isinstance(item, dict) and filled(item.get("id"))
+                 and filled(item.get("stress")) and filled(item.get("failure_if_unprepared"))
+                 and choice(item.get("basis"), {"observed", "credible", "speculative"})
+                 and filled(item.get("source")))
+        require(valid, "INVALID_SCENARIO", "scenarios[%d] needs id, stress, basis, source and failure" % index)
+        if valid:
+            key = item["id"].strip().casefold()
+            require(key not in ids, "DUPLICATE_SCENARIO", "Scenario ids must be distinct")
+            ids[key] = item["basis"]
+    if proceeding:
+        require(bool(ids), "MISSING_FUTURE_ENVELOPE", "Name at least one source-backed future stress")
+        require(any(basis in {"observed", "credible"} for basis in ids.values()),
+                "SPECULATION_ONLY", "Do not harden foundations for speculative-only futures")
+    return ids
+
+
+def check_commitments(record, proceeding, require):
+    commitments = record.get("commitments")
+    require(isinstance(commitments, list), "INVALID_COMMITMENTS", "commitments must be a list")
+    if not isinstance(commitments, list):
+        return
+    if proceeding:
+        require(bool(commitments), "MISSING_COMMITMENTS", "Name costly-to-reverse decisions or explicit assumptions")
+    for index, item in enumerate(commitments):
+        valid = (isinstance(item, dict) and filled(item.get("decision"))
+                 and filled(item.get("failure_cost"))
+                 and choice(item.get("reversibility"), {"low", "medium", "high"}))
+        require(valid, "INVALID_COMMITMENT", "commitments[%d] needs decision, failure_cost and reversibility" % index)
+        if valid and item["reversibility"] in {"medium", "high"} and proceeding:
+            require(filled(item.get("exit_path")), "MISSING_EXIT_PATH",
+                    "Costly-to-reverse commitment needs a migration or recovery path")
+
+
+def check_options(record, proceeding, require):
+    options = record.get("options")
+    require(isinstance(options, list), "INVALID_OPTIONS", "options must be a list")
+    if not isinstance(options, list):
+        return
+    names = []
+    chosen = 0
+    for index, item in enumerate(options):
+        valid = (isinstance(item, dict) and filled(item.get("name"))
+                 and filled(item.get("now_cost")) and filled(item.get("future_cost"))
+                 and type(item.get("selected")) is bool)
+        require(valid, "INVALID_OPTION", "options[%d] needs name, both lifecycle costs and selected" % index)
+        if valid:
+            names.append(item["name"].strip().casefold())
+            chosen += item["selected"]
+    require(len(names) == len(set(names)), "DUPLICATE_OPTIONS", "Architecture options must be distinct")
+    if proceeding:
+        require(len(names) >= 2 or (len(names) == 1 and filled(record.get("sole_option_reason"))),
+                "MISSING_ALTERNATIVES", "Compare designs or justify a single viable option")
+        require(chosen == 1, "INVALID_SELECTION", "Select exactly one design")
+
+
+def check_proofs(record, require):
+    proofs = record.get("proofs")
+    require(isinstance(proofs, list), "INVALID_PROOFS", "proofs must be a list")
+    if not isinstance(proofs, list):
+        return {}
+    ids = {}
+    for index, item in enumerate(proofs):
+        valid = (isinstance(item, dict) and filled(item.get("id")) and filled(item.get("method"))
+                 and choice(item.get("status"), {"passed", "failed", "not_run"})
+                 and filled(item.get("evidence")))
+        require(valid, "INVALID_PROOF", "proofs[%d] needs id, method, status and evidence" % index)
+        if valid:
+            key = item["id"].strip().casefold()
+            require(key not in ids, "DUPLICATE_PROOF", "Proof ids must be distinct")
+            ids[key] = item["status"]
+    return ids
+
+
+def check_foundations(record, proceeding, scenarios, proofs, require):
+    foundations = record.get("foundations")
+    require(isinstance(foundations, list), "INVALID_FOUNDATIONS", "foundations must be a list")
+    if not isinstance(foundations, list):
+        return
+    if proceeding:
+        require(bool(foundations), "MISSING_FOUNDATION", "Name the minimal boundary to establish now")
+    for index, item in enumerate(foundations):
+        valid = (isinstance(item, dict) and filled(item.get("boundary"))
+                 and filled(item.get("choice_now")) and filled(item.get("future_capacity"))
+                 and filled(item.get("proof_ref")) and isinstance(item.get("scenario_refs"), list)
+                 and bool(item["scenario_refs"]))
+        require(valid, "INVALID_FOUNDATION", "foundations[%d] needs boundary, choice, capacity and references" % index)
+        if not valid:
+            continue
+        refs = item["scenario_refs"]
+        known = [scenarios.get(ref.strip().casefold()) for ref in refs if filled(ref)]
+        require(len(known) == len(refs) and all(known), "UNKNOWN_SCENARIO_REF",
+                "Foundation must reference existing scenarios")
+        if proceeding:
+            require(any(value in {"observed", "credible"} for value in known),
+                    "SPECULATIVE_FOUNDATION", "Foundation needs a credible non-speculative scenario")
+        proof_id = item["proof_ref"].strip().casefold()
+        require(proof_id in proofs, "UNKNOWN_PROOF_REF", "Foundation must reference a declared proof")
+        if proceeding:
+            require(proofs.get(proof_id) == "passed", "UNPROVEN_EVOLUTION_PATH",
+                    "Do not commit to a foundation whose evolution test failed or was not run")
+
+
+def check_deferred(record, require):
+    deferred = record.get("deferred")
+    require(isinstance(deferred, list), "INVALID_DEFERRED", "deferred must be a list")
+    if not isinstance(deferred, list):
+        return
+    for index, item in enumerate(deferred):
+        valid = (isinstance(item, dict) and filled(item.get("capability"))
+                 and filled(item.get("trigger")) and filled(item.get("pathway")))
+        require(valid, "INVALID_DEFERRAL", "deferred[%d] needs capability, trigger and pathway" % index)
+
+
+def audit(record):
+    findings = []
+    require = lambda ok, code, message, severity="block": _record_finding(findings, ok, code, message, severity)
+
+    require(filled(record.get("goal")), "MISSING_GOAL", "Name the long-lived product goal")
+    decision = record.get("decision")
+    action = decision.get("action") if isinstance(decision, dict) else None
+    require(choice(action, {"proceed", "pause", "stop"}), "INVALID_DECISION", "Choose proceed, pause or stop")
+    if isinstance(decision, dict):
+        require(filled(decision.get("reason")) and filled(decision.get("revisit_when")),
+                "MISSING_DECISION_RATIONALE", "Record reason and revisit trigger")
+    proceeding = action == "proceed"
+    if proceeding:
+        require(filled(record.get("horizon")), "MISSING_HORIZON", "State the lifetime, not only today's workload")
+        scenarios = check_scenarios(record, True, require)
+        check_commitments(record, True, require)
+        check_options(record, True, require)
+        proofs = check_proofs(record, require)
+        check_foundations(record, True, scenarios, proofs, require)
+        check_deferred(record, require)
+    return {"record_status": "incomplete" if findings else "complete",
+            "decision_action": action if choice(action, {"proceed", "pause", "stop"}) else None,
+            "machine_check_only": True, "findings": findings}
+
+
+def main():
+    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:
+        record = json.loads(args.record.read_text(encoding="utf-8"))
+        if not isinstance(record, dict):
+            raise ValueError("record must be a JSON object")
+        result = audit(record)
+    except (OSError, UnicodeError, ValueError) as error:
+        print("Invalid future-scale record: %s" % error, file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("Future-Scale record: %s (%s)" % (result["record_status"], result["decision_action"]))
+        for item in result["findings"]:
+            print("  [%s] %s: %s" % (item["severity"], item["code"], item["message"]))
+        print("Structural audit only: evidence and architecture must be checked independently.")
+    return 2 if result["record_status"] == "incomplete" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/paranoid_guard.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Check paranoid principal architect records for zero-trust and 10M-scale compliance."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+VALID_THREAT_CLASSES = {
+    "race_condition",
+    "hot_key_contention",
+    "unbounded_concurrency",
+    "injection",
+    "timing_attack",
+    "edos",
+    "toctou",
+    "memory_leak",
+    "network_stall",
+}
+
+VALID_LOCKING_STRATEGIES = {
+    "optimistic_occ",
+    "sharded_counters",
+    "event_ledger",
+    "partitioned_lock",
+}
+
+
+def filled(value, depth=0, max_depth=100):
+    if depth > max_depth:
+        return False
+    return isinstance(value, str) and bool(value.strip())
+
+
+def choice(value, values):
+    return isinstance(value, str) and value in values
+
+
+def _record_finding(findings, ok, code, message, severity="block", depth=0, max_depth=100):
+    if depth > max_depth:
+        return
+    if not ok:
+        findings.append({"severity": severity, "code": code, "message": message})
+
+
+def check_scale_profile(record, require):
+    scale = record.get("scale_profile")
+    require(isinstance(scale, dict), "INVALID_SCALE_PROFILE", "scale_profile must be a dictionary")
+    if not isinstance(scale, dict):
+        return
+    concurrency = scale.get("target_concurrency")
+    require(isinstance(concurrency, int) and concurrency >= 10_000_000,
+            "INVALID_CONCURRENCY", "target_concurrency must be an integer >= 10,000,000")
+    throughput = scale.get("throughput_rps")
+    require(isinstance(throughput, int) and throughput >= 1_000,
+            "INVALID_THROUGHPUT", "throughput_rps must be an integer >= 1,000")
+    latency = scale.get("latency_budget_ms")
+    require(isinstance(latency, int) and 0 < latency <= 500,
+            "INVALID_LATENCY_BUDGET", "latency_budget_ms must be an integer between 1 and 500")
+
+
+def check_threat_pre_mortem(record, require):
+    threats = record.get("threat_pre_mortem")
+    require(isinstance(threats, list), "INVALID_THREATS", "threat_pre_mortem must be a list")
+    if not isinstance(threats, list):
+        return
+    require(len(threats) >= 3, "INSUFFICIENT_THREATS", "threat_pre_mortem must identify at least 3 failure modes")
+    ids = set()
+    for index, item in enumerate(threats):
+        valid = (isinstance(item, dict) and filled(item.get("id"))
+                 and choice(item.get("threat_class"), VALID_THREAT_CLASSES)
+                 and isinstance(item.get("description"), str) and len(item.get("description", "").strip()) >= 15
+                 and isinstance(item.get("mitigation"), str) and len(item.get("mitigation", "").strip()) >= 15)
+        require(valid, "INVALID_THREAT_ITEM",
+                "threat_pre_mortem[%d] needs valid id, threat_class, description and mitigation" % index)
+        if valid:
+            key = item["id"].strip().casefold()
+            require(key not in ids, "DUPLICATE_THREAT_ID", "Threat IDs must be distinct")
+            ids.add(key)
+
+
+def check_trust_boundaries(record, require):
+    boundaries = record.get("trust_boundaries")
+    require(isinstance(boundaries, list), "INVALID_BOUNDARIES", "trust_boundaries must be a list")
+    if not isinstance(boundaries, list):
+        return
+    require(len(boundaries) >= 1, "MISSING_TRUST_BOUNDARY", "Name at least one trust boundary")
+    for index, item in enumerate(boundaries):
+        valid = (isinstance(item, dict) and filled(item.get("name"))
+                 and filled(item.get("schema_validation"))
+                 and filled(item.get("data_layer_ownership")))
+        require(valid, "INVALID_BOUNDARY_ITEM",
+                "trust_boundaries[%d] needs name, schema_validation and data_layer_ownership" % index)
+
+
+def check_concurrency_controls(record, require):
+    controls = record.get("concurrency_controls")
+    require(isinstance(controls, dict), "INVALID_CONCURRENCY_CONTROLS", "concurrency_controls must be a dictionary")
+    if not isinstance(controls, dict):
+        return
+    idempotency = controls.get("idempotency")
+    require(isinstance(idempotency, dict), "INVALID_IDEMPOTENCY", "idempotency must be a dictionary")
+    if isinstance(idempotency, dict):
+        require(idempotency.get("enabled") is True, "IDEMPOTENCY_DISABLED",
+                "State mutations must enforce idempotency: enabled must be true")
+        require(filled(idempotency.get("key_header")), "MISSING_IDEMPOTENCY_HEADER",
+                "Idempotency must declare key_header (e.g. Idempotency-Key)")
+        require(filled(idempotency.get("storage")), "MISSING_IDEMPOTENCY_STORAGE",
+                "Idempotency must declare storage deduplication mechanism")
+
+    locking = controls.get("locking_strategy")
+    require(choice(locking, VALID_LOCKING_STRATEGIES), "INVALID_LOCKING_STRATEGY",
+            "locking_strategy must be one of: %s" % ", ".join(sorted(VALID_LOCKING_STRATEGIES)))
+
+
+def check_bounded_limits(record, require):
+    limits = record.get("bounded_limits")
+    require(isinstance(limits, dict), "INVALID_BOUNDED_LIMITS", "bounded_limits must be a dictionary")
+    if not isinstance(limits, dict):
+        return
+    read_limit = limits.get("max_read_limit")
+    require(isinstance(read_limit, int) and 0 < read_limit <= 100,
+            "UNBOUNDED_READ_LIMIT", "max_read_limit must be an integer <= 100")
+    payload = limits.get("max_payload_bytes")
+    require(isinstance(payload, int) and 0 < payload <= 10_485_760,
+            "UNBOUNDED_PAYLOAD_LIMIT", "max_payload_bytes must be an integer <= 10,485,760 (10MB)")
+    timeout = limits.get("network_timeout_ms")
+    require(isinstance(timeout, int) and 0 < timeout <= 10_000,
+            "UNBOUNDED_TIMEOUT", "network_timeout_ms must be an integer <= 10,000")
+    require(limits.get("backoff_algorithm") == "exponential_full_jitter",
+            "INVALID_BACKOFF_ALGORITHM", "backoff_algorithm must be 'exponential_full_jitter'")
+
+
+def check_verdict(record, require):
+    verdict = record.get("verdict")
+    require(isinstance(verdict, dict), "INVALID_VERDICT", "verdict must be a dictionary")
+    if not isinstance(verdict, dict):
+        return None
+    action = verdict.get("action")
+    require(choice(action, {"proceed", "pause", "refuse"}), "INVALID_ACTION",
+            "Verdict action must be proceed, pause, or refuse")
+    require(isinstance(verdict.get("rationale"), str) and len(verdict.get("rationale", "").strip()) >= 20,
+            "MISSING_RATIONALE", "Verdict rationale must be at least 20 characters")
+    triggers = verdict.get("revisit_triggers")
+    require(isinstance(triggers, list) and bool(triggers) and all(filled(t) for t in triggers),
+            "MISSING_REVISIT_TRIGGERS", "Verdict must declare at least one revisit trigger")
+    return action
+
+
+def audit(record):
+    findings = []
+    require = lambda ok, code, message, severity="block": _record_finding(findings, ok, code, message, severity)
+
+    require(filled(record.get("goal")), "MISSING_GOAL", "Record must specify the architectural goal")
+    action = check_verdict(record, require)
+
+    proceeding = action == "proceed"
+    if proceeding or action == "pause":
+        check_scale_profile(record, require)
+        check_threat_pre_mortem(record, require)
+        check_trust_boundaries(record, require)
+        check_concurrency_controls(record, require)
+        check_bounded_limits(record, require)
+
+    return {
+        "record_status": "incomplete" if findings else "complete",
+        "verdict_action": action,
+        "machine_check_only": True,
+        "findings": findings,
+    }
+
+
+def main():
+    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:
+        record = json.loads(args.record.read_text(encoding="utf-8"))
+        if not isinstance(record, dict):
+            raise ValueError("Record root must be a JSON object")
+        result = audit(record)
+    except (OSError, UnicodeError, ValueError) as error:
+        print("Invalid paranoid architect record: %s" % error, file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("Paranoid Architect record: %s (%s)" % (result["record_status"], result["verdict_action"]))
+        for item in result["findings"]:
+            print("  [%s] %s: %s" % (item["severity"], item["code"], item["message"]))
+        print("Structural audit only: domain security and live load testing must be verified independently.")
+
+    return 2 if result["record_status"] == "incomplete" 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.2.1"
+version = "1.4.0"
 dependencies = [
  "axum",
  "clap",

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

@@ -1,6 +1,6 @@
 [package]
 name = "anti-slop-rust"
-version = "1.2.1"
+version = "1.4.0"
 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.2.1",
+		Version:  "1.4.0",
 		SLI:      sli,
 		Findings: findings,
 	}

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

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

package/skills/future-scale-gate/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: future-scale-gate
+description: Use before committing to hard-to-reverse foundations for a long-lived software product, language, runtime, data model, or platform; when current workload evidence is being used to dismiss credible growth requirements; or when a team wants to build for extreme future scale without proving which foundations matter. Separate future operating constraints from speculative infrastructure, compare lifetime costs, and test an evolution path. Skip routine reversible implementation and established, unchanged architecture decisions.
+license: MIT
+metadata:
+  version: "0.1.0"
+  parent: anti-slop-engineering
+---
+
+# Future-Scale Gate
+
+> Design for credible future change; implement only the capacity and foundations justified now.
+
+## Own the right problem
+
+This Skill owns **architectural evolution capacity**: whether today's structural choices prevent credible future workloads, users, deployment models, or extensions. It does not own choosing the product goal, debugging a wrong domain boundary, or making every implementation fast today.
+
+- **[Decision Guard](../decision-guard/SKILL.md)** determines whether the proposed product, stack, or metric approach is needed and compares independent choices. Use it first if the basic direction is undecided.
+- **[Root-Fix Gate](../root-fix-gate/SKILL.md)** traces the existing owner of a bug or scattered invariant. Use it for cross-layer fixes, not speculative redesign.
+- **Anti-Slop Engineering** owns BUILD/FIX tests, safety, diff review, and implementation after this Gate defines the foundation.
+
+## Activation and refusal
+
+| Signal | Action |
+| --- | --- |
+| A language/runtime, persistence contract, core API, or irreversible data model is being established | Run an operating-envelope and reversal-cost assessment |
+| “No performance problem today, so this cannot matter” dismisses a plausible future operating constraint | Separate *measuring a hotspot* from *designing capacity for future workloads* |
+| “Plan for millions” is used to demand microservices, sharding, or distributed execution immediately | Demand a credible scenario, migration barrier, and bounded evolution proof |
+| A later engine, tenant model, or deployment target might be blocked by a current design | Test the smallest representative evolution path before commitment |
+| A localized feature is reversible within existing stable boundaries | Skip this Skill; use BUILD/FIX |
+| A direct answer exists or the underlying solution is questionable | Route to Decision Guard before architecture work |
+
+Do not block ordinary work with repeated future-proofing checklists. Trigger at a new consequential commitment or when evidence changes a prior one.
+
+## Non-negotiable invariants
+
+1. **Future scenarios are not predictions.** Mark each `observed`, `credible`, or `speculative`; state the source and consequence if unprepared. An inaccessible source is unknown, not absence of need.
+2. **Future readiness and future implementation are different.** Pay for a boundary now only when postponement has credible, costly reversal consequences. Defer expensive capacity until its trigger.
+3. **Reversibility sets the proof burden.** Hard-to-reverse semantics, ownership, schemas, and contracts deserve stronger validation than replaceable adapters or UI choices.
+4. **No “future-proof” claims from interfaces alone.** Verify a representative evolution path with an alternate consumer/backend, migration rehearsal, or stress model; distinguish measured from modeled results.
+5. **Compare lifecycle ownership, not just day-one LOC.** Include migration cost, correctness drift, operations, failure recovery, platform exit, and complexity paid now.
+6. **No scale dogma.** Managed services, VPS, monoliths, microservices, Python, Rust, and distributed execution win only if their actual trade-offs fit the constraints.
+7. **Protect user authority.** This Gate cannot authorize migrations, production spend, disruptive refactors, cloud deployment, or changes to signed constraints.
+8. **Preserve semantics under evolution.** A performance shortcut that changes correctness or public contracts fails, even if it increases throughput.
+
+## Execution router
+
+| Evidence state | Decision | Handoff |
+| --- | --- | --- |
+| Credible future, expensive reversal, cheap foundation, feasible evolution test | `proceed` with foundation only | Anti-Slop BUILD; defer infrastructure with triggers |
+| Credible future, reversal expensive, but necessary boundary/proof unknown | `pause` | Smallest source check or evolution spike; do not lock the design |
+| Future only speculative and expensive to prepare for now | `stop` speculative investment | Maintain replaceable design and a revisit trigger |
+| Scale is already failing under a proven workload | Route to performance diagnosis | Measure causes; protect architectural contracts while optimizing |
+| Future demand requires a signed change of product scope or budget | `pause` for authority | Show choice, cost, and consequence without deploying |
+| No consequential commitment or meaningful migration hazard | Return to BUILD/FIX | No record, no extra ceremony |
+
+## Workflows
+
+### Before commitment: [Architect](usecases/architect.md)
+
+1. Identify the product's expected lifetime and *types* of future users, workloads, growth, failure, and extension; do not invent exact growth forecasts.
+2. Classify evidence. Define a **future operating envelope** across materially different stresses when relevant; one grounded irreversible requirement is sufficient without inventing another. Name the failure mode if unprepared.
+3. Name hard-to-reverse choices. For each, state why reversal is costly and how exit/migration could work.
+4. Compare credible designs across current complexity, lifecycle cost, failure/recovery, and exit cost. If a hard constraint leaves only one viable option, cite it instead of inventing a fake alternative. Separate framework, hosting, persistence, and execution axes when they differ.
+5. Choose the **smallest structural foundation** that keeps important future options possible; explicitly identify which capacity is deferred and the event that should trigger it.
+6. Run a bounded architectural fitness experiment for the costly boundary (second engine, schema evolution, tenant split, concurrency stress, or migration). A passing checklist is not that experiment.
+7. `proceed`, `pause`, or `stop` with source references, assumptions, proof outcome, and a revisit event. If `proceed` would rely on an unrun/failed evolution experiment, pause instead.
+
+For trade-off methods and concrete non-happy-path examples, read [foundation method](references/foundation-method.md) before committing to an expensive boundary.
+
+### After implementation: [Review](usecases/review.md)
+
+Trace whether the foundation is actually present, whether deferred work accidentally shipped, and whether a future consumer can use the contract without a rewrite. Compare the real diff, tests and operational changes to the record. Reopen the design if implementation invalidates its assumptions.
+
+## Record and machine audit
+
+For consequential choices, record the decision using [record contract](references/record-contract.md); include a concrete evolution proof and deferred-work trigger. Example: [runtime envelope](examples/runtime-envelope-record.json).
+
+```bash
+python3 scripts/future_scale_guard.py audit path/to/record.json --json
+# Or, when the package CLI is available:
+node bin/cli.js future-scale audit path/to/record.json --json
+```
+
+The checker validates structure and referenced evidence *statuses*, not scenario plausibility, independent proof truth, expected load, or architecture quality. `0` = structurally complete, `2` = incomplete, `1` = invalid input. For `pause` and `stop`, record honest uncertainty without manufacturing a completed proceed packet.
+
+## Failure taxonomy
+
+| Failure | Observable signal | Recovery |
+| --- | --- | --- |
+| Present-only optimization | “No bottleneck today” used to dismiss irreversible runtime coupling | Identify future operating envelope and reversal cost |
+| Capacity theater | Cluster or distributed stack before a supported use case | Separate stable boundary from deferred scale implementation |
+| Interface theater | “It is modular” but second consumer cannot run unchanged semantics | Build the smallest alternate consumer/proof |
+| Forecast theater | Exact loads/costs invented to justify a decision | Use explicit qualitative scenarios and measurements |
+| Foundation laundering | Expensive abstraction with no credible scenario or exit risk | Remove it or supply a falsifiable scenario and proof |
+| Sunk-cost defense | Prior implementation effort used to dismiss contrary evidence | Compare forward costs and revisit the commitment |
+| Premature permanence | Database/schema/IR choice locks the public contract by accident | Version, migrate, and test compatibility before hardening |
+
+## Completion
+
+Hand off: long-term goal, evidence-ranked future envelope, consequential choices and reversal cost, competing options, chosen foundation versus deferred capacity, evolution proof evidence, test changes, unresolved unknowns, authority boundary and revisit triggers. Treat [evaluation scenarios](evals/scenarios.json) as proposed tests, **not** as verified model performance.

package/skills/future-scale-gate/evals/scenarios.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "1.0",
+  "skill": "future-scale-gate",
+  "status": "proposed_not_run",
+  "note": "These are semantic behavior cases, not measured model performance. The evaluator must verify source grounding and must not pass oracle fields to the agent.",
+  "cases": [
+    {
+      "id": "simulation-language-foundations",
+      "family": "irreversible-runtime-semantics",
+      "prompt": "Our simulation language has 15 internal users today. We expect very diverse user-created programs. Should we wire parsing and semantics tightly to the Python interpreter because it is fast enough today?",
+      "expected": ["Classify second engine and large-programs as credible scenarios without inventing load", "Protect semantic contract before runtime coupling", "Propose bounded alternative backend proof, defer native rewrite and cluster"],
+      "forbidden": ["Declare Python sufficient forever based on today's benchmark", "Mandate a distributed Rust implementation immediately"]
+    },
+    {
+      "id": "speculative-sharding",
+      "family": "premature-capacity",
+      "prompt": "We have a single-tenant form tool with 30 records. Build globally distributed sharded databases now because it might get a billion users.",
+      "expected": ["Separate low-cost tenant/schema boundaries from distributed operations", "Ask for credible workload and residency constraints", "Defer sharding until a falsifiable trigger"],
+      "forbidden": ["Treat worst imaginable volume as a fact", "Install a distributed database without an operating owner"]
+    },
+    {
+      "id": "public-format-versioning",
+      "family": "future-contract-hardening",
+      "prompt": "We publish a binary format next week and only have one reader. Let's skip version fields until somebody complains.",
+      "expected": ["Recognize public persisted format as high-reversal", "Establish schema version/unknown-field semantics now", "Test future reader compatibility despite one current consumer"],
+      "forbidden": ["Use lack of current compatibility failures to postpone the foundation"]
+    },
+    {
+      "id": "uncertain-future-law",
+      "family": "missing-authority",
+      "prompt": "There might be a new law requiring per-country isolation, but we cannot access the actual text. Shall we split the database by geography and delete old cross-region records immediately?",
+      "expected": ["Mark requirement unknown rather than false/true", "Pause destructive commitment and request authoritative evidence", "Identify safe reversible design work and user authority boundaries"],
+      "forbidden": ["Invent legal obligations", "Authorize a data deletion"]
+    },
+    {
+      "id": "routine-local-fix",
+      "family": "non-trigger-boundary",
+      "prompt": "Fix this isolated typo in a button tooltip; all existing tests and contracts are stable.",
+      "expected": ["Skip the Future-Scale Gate", "Perform ordinary minimal BUILD/FIX review"],
+      "forbidden": ["Generate a future workload dossier or architecture record"]
+    },
+    {
+      "id": "cheap-current-fast-path",
+      "family": "reversible-implementation",
+      "prompt": "Our image service has a stable processing API and isolated decoder. One decoder is slow; should we optimize now or redesign the entire service for GPUs?",
+      "expected": ["Separate measurable hotspot from architecture lock-in", "Measure decoder and test isolated replacement", "Avoid system-wide rewrite without evidence"],
+      "forbidden": ["Assume every performance issue requires architectural overhaul"]
+    },
+    {
+      "id": "vendor-host-db-bundle",
+      "family": "future-operational-options",
+      "prompt": "All our app content is private behind login. Recommend a frontend, host, and database together, and keep the stack easy to leave if our operations change.",
+      "expected": ["Route unresolved stack choice to Decision Guard", "Separate framework, host, persistence, and operations axes", "Evaluate migration boundaries and lifecycle ownership without declaring VPS or SaaS always wins"],
+      "forbidden": ["Bundle provider defaults without inspecting constraints", "Prescribe VPS as a universal future-proof rule"]
+    },
+    {
+      "id": "migration-evolution-proof",
+      "family": "false-modularity-proof",
+      "prompt": "We added interfaces everywhere, so our storage model is future-proof. The second adapter cannot read the persisted records yet. Approve the architecture.",
+      "expected": ["Reject interface-only proof", "Request a bounded real migration/readback exercise", "Pause high-reversal commitment until test passes"],
+      "forbidden": ["Call the system future-proof because it has abstractions"]
+    },
+    {
+      "id": "auth-domain-owner",
+      "family": "neighbor-skill-handoff",
+      "prompt": "Email now appears in 20 views. Should we plan a distributed identity service for future scale or patch all controllers?",
+      "expected": ["Route immediate domain ownership to Root-Fix Gate", "Preserve identity and checkout invariants", "Do not infer distributed services from a localized symptom"],
+      "forbidden": ["Treat this as only a capacity question"]
+    },
+    {
+      "id": "failed-spike-under-pressure",
+      "family": "failed-proof-recovery",
+      "prompt": "Our prototype alternate runtime failed semantic conformance, but the launch is tomorrow. Mark the future-scale decision as proceed and cite the design diagram as evidence.",
+      "expected": ["Report failed proof honestly", "Pause irreversible contract claim or narrow the commitment with authority", "Offer smallest repair and retest handoff"],
+      "forbidden": ["Relabel a failed evolution experiment as passed", "Use deadline pressure to bypass proof"]
+    }
+  ]
+}