its-magic 0.1.2-39 → 0.1.2-40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-39",
+  "version": "0.1.2-40",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {
@@ -17,10 +17,14 @@
     "scripts/intake_bug_routing_guard.py",
     "scripts/check_intake_template_parity.py",
     "scripts/materialize_codebase_map.py",
+    "scripts/remote_config_summary.py",
+    "scripts/guard_installer_publish.py",
     "bin/its-magic.js",
     "bin/postinstall.js"
   ],
   "scripts": {
+    "guard:installer": "python scripts/guard_installer_publish.py",
+    "prepublishOnly": "npm run guard:installer",
     "postinstall": "node bin/postinstall.js",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",

package/scripts/guard_installer_publish.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Prepublish / CI guard: installer.sh LF + POSIX-safe startup tokens (US-0084 / AC-2)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+INSTALLER_SH = ROOT / "installer.sh"
+
+FORBIDDEN_TOKENS = (
+    "set -euo",
+    "set -o pipefail",
+    "set -eu -o pipefail",
+    "set -o errexit",
+    "set -o nounset",
+)
+
+
+def main() -> int:
+    if not INSTALLER_SH.is_file():
+        print("guard_installer_publish: installer.sh missing", file=sys.stderr)
+        return 1
+    data = INSTALLER_SH.read_bytes()
+    if b"\r" in data:
+        print(
+            "guard_installer_publish: CR/LF (\\r) bytes found in installer.sh — "
+            "use LF only; see docs/engineering/runbook.md (US-0084).",
+            file=sys.stderr,
+        )
+        return 1
+    text = data.decode("utf-8", errors="replace")
+    for token in FORBIDDEN_TOKENS:
+        if token in text:
+            print(
+                f"guard_installer_publish: forbidden startup token {token!r} in installer.sh",
+                file=sys.stderr,
+            )
+            return 1
+    dash = shutil.which("dash")
+    if dash:
+        r = subprocess.run(
+            [dash, "-n", str(INSTALLER_SH)],
+            cwd=ROOT,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        if r.returncode != 0:
+            print(
+                "guard_installer_publish: dash -n installer.sh failed:\n"
+                + (r.stderr or r.stdout or ""),
+                file=sys.stderr,
+            )
+            return 1
+    else:
+        print(
+            "guard_installer_publish: dash not on PATH; skipping dash -n "
+            "(Python CRLF + token checks still enforced).",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/remote_config_summary.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Summarize .cursor/remote.json for operators (US-0084 / US-0064 alignment).
+
+Stdout: non-secret labels and env-reference names only (no key material).
+Stderr: errors and skip reasons.
+
+Exit codes:
+  0 OK or REMOTE_EXECUTION=0 skip (DEC-0070)
+  1 usage / CLI error
+  2 config missing or unreadable
+  3 invalid JSON
+  4 schema / contract mismatch vs runbook remote.json contract
+  5 reserved (unused; DEC-0070 maps REMOTE_EXECUTION=0 to 0)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+ENV_VAR_NAME = re.compile(r"^[A-Z][A-Z0-9_]*$")
+ALLOWED_TYPES = frozenset({"docker", "ssh", "vm"})
+AUTH_MODES = frozenset({"none", "env"})
+
+
+def _truthy_remote_execution(raw: str | None) -> bool:
+    if raw is None:
+        return False
+    return raw.strip() in {"1", "true", "TRUE", "yes", "YES", "on", "ON"}
+
+
+def _parse_args(argv: list[str]) -> tuple[argparse.Namespace, list[str]]:
+    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0], add_help=True)
+    p.add_argument(
+        "--config",
+        default=None,
+        help="Path to remote JSON (default: REMOTE_CONFIG env or .cursor/remote.json)",
+    )
+    return p.parse_known_args(argv)
+
+
+def _config_path(explicit: str | None) -> Path:
+    if explicit:
+        return Path(explicit).expanduser()
+    env = os.environ.get("REMOTE_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    return Path(".cursor/remote.json")
+
+
+def _validate_env_ref(name: str, value: Any, prefix: str) -> str | None:
+    if not isinstance(value, str):
+        return f"{prefix}: {name} must be a string env-reference name"
+    if not ENV_VAR_NAME.match(value):
+        return f"{prefix}: {name} must look like an env var name (A-Z_0-9)"
+    return None
+
+
+def validate_and_summarize(path: Path, data: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Return (stdout_lines, error_messages)."""
+    errs: list[str] = []
+    out: list[str] = []
+    out.append(f"remote_config={path.as_posix()}")
+
+    if not isinstance(data.get("version"), int):
+        errs.append("[REMOTE_CONFIG_ERROR] root.version: expected integer")
+    if not isinstance(data.get("defaultTarget"), str) or not data["defaultTarget"]:
+        errs.append("[REMOTE_CONFIG_ERROR] root.defaultTarget: expected non-empty string")
+    targets = data.get("targets")
+    if not isinstance(targets, list) or not targets:
+        errs.append("[REMOTE_CONFIG_ERROR] root.targets: expected non-empty array")
+
+    if errs:
+        return out, errs
+
+    by_id: dict[str, dict[str, Any]] = {}
+    for i, t in enumerate(targets):
+        prefix = f"targets[{i}]"
+        if not isinstance(t, dict):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}: expected object")
+            continue
+        tid = t.get("id")
+        if not isinstance(tid, str) or not tid:
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.id: expected non-empty string")
+        ttype = t.get("type")
+        if ttype not in ALLOWED_TYPES:
+            errs.append(
+                f"[REMOTE_CONFIG_ERROR] {prefix}.type: expected one of {sorted(ALLOWED_TYPES)}"
+            )
+        if not isinstance(t.get("enabled"), bool):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.enabled: expected boolean")
+        if not isinstance(t.get("host"), str) or not t["host"]:
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.host: expected non-empty string")
+        port = t.get("port")
+        if not isinstance(port, int) or not (1 <= port <= 65535):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.port: expected integer 1..65535")
+        if not isinstance(t.get("workspaceRoot"), str) or not t["workspaceRoot"]:
+            errs.append(
+                f"[REMOTE_CONFIG_ERROR] {prefix}.workspaceRoot: expected non-empty string"
+            )
+        auth = t.get("auth")
+        if auth is not None:
+            if not isinstance(auth, dict):
+                errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.auth: expected object")
+            else:
+                mode = auth.get("mode")
+                if mode not in AUTH_MODES:
+                    errs.append(
+                        f"[REMOTE_CONFIG_ERROR] {prefix}.auth.mode: expected one of {sorted(AUTH_MODES)}"
+                    )
+                elif mode == "env":
+                    env_keys = (
+                        "tokenEnv",
+                        "passwordEnv",
+                        "privateKeyPathEnv",
+                        "usernameEnv",
+                    )
+                    any_ref = False
+                    for k in env_keys:
+                        if k not in auth:
+                            continue
+                        any_ref = True
+                        err = _validate_env_ref(k, auth[k], f"{prefix}.auth")
+                        if err:
+                            errs.append(f"[REMOTE_CONFIG_ERROR] {err}")
+                    if not any_ref:
+                        errs.append(
+                            f"[REMOTE_CONFIG_ERROR] {prefix}.auth: mode=env requires at least one *Env field"
+                        )
+        if isinstance(tid, str) and tid:
+            by_id[tid] = t
+
+    default = data["defaultTarget"]
+    if default not in by_id:
+        errs.append(
+            f"[REMOTE_CONFIG_ERROR] defaultTarget={default!r} not found in targets[].id"
+        )
+    elif not by_id[default].get("enabled"):
+        errs.append(
+            f"[REMOTE_CONFIG_ERROR] defaultTarget={default!r} must reference an enabled target"
+        )
+
+    if errs:
+        return out, errs
+
+    out.append(f"defaultTarget={data['defaultTarget']}")
+    for t in targets:
+        assert isinstance(t, dict)
+        tid = t["id"]
+        parts = [
+            f"id={tid}",
+            f"type={t['type']}",
+            f"enabled={t['enabled']!s}",
+            f"host={t['host']}",
+            f"port={t['port']}",
+            f"workspaceRoot={t['workspaceRoot']}",
+        ]
+        auth = t.get("auth")
+        if isinstance(auth, dict):
+            parts.append(f"auth.mode={auth.get('mode')}")
+            for k in (
+                "tokenEnv",
+                "passwordEnv",
+                "privateKeyPathEnv",
+                "usernameEnv",
+            ):
+                if k in auth and isinstance(auth[k], str):
+                    parts.append(f"auth.{k}={auth[k]}")
+        out.append("target:" + " ".join(parts))
+
+    return out, []
+
+
+def main(argv: list[str] | None = None) -> int:
+    args, rest = _parse_args(argv or sys.argv[1:])
+    if rest:
+        print(
+            f"[REMOTE_CONFIG_SUMMARY] unknown arguments: {' '.join(rest)}",
+            file=sys.stderr,
+        )
+        return 1
+    if not _truthy_remote_execution(os.environ.get("REMOTE_EXECUTION")):
+        print(
+            "[REMOTE_CONFIG_SUMMARY] REMOTE_EXECUTION!=1: skip validation/summary "
+            "(zero overhead; DEC-0070 / US-0084).",
+            file=sys.stderr,
+        )
+        return 0
+
+    path = _config_path(args.config)
+    if not path.is_file():
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: file missing or unreadable. "
+            "Fix: create config or set REMOTE_EXECUTION=0.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as e:
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: read failed ({e}). Fix: permissions/path.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: invalid JSON ({e}). Fix: syntax.",
+            file=sys.stderr,
+        )
+        return 3
+    if not isinstance(data, dict):
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: expected JSON object at root.",
+            file=sys.stderr,
+        )
+        return 4
+
+    lines, errs = validate_and_summarize(path, data)
+    if errs:
+        for line in errs:
+            print(line, file=sys.stderr)
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: contract check failed. "
+            "Fix: align with docs/engineering/runbook.md remote contract (US-0084).",
+            file=sys.stderr,
+        )
+        return 4
+    for line in lines:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.cursor/commands/execute.md

@@ -152,6 +152,12 @@ parity for listed paths: **`python scripts/check_token_cost_parity.py --repo .`*
      fail fast with `REMOTE_CONNECTIVITY_CONFIG_INVALID`.
    - Never expose secrets in execution outputs; only sanitized endpoint data and
      env-reference names are allowed.
+17b. Remote evidence cues (US-0084):
+   - When `REMOTE_EXECUTION=1`, cite an **environment label** in
+     `handoffs/dev_to_qa.md` (e.g. `WSL`, `ssh:SSH_HOST` as the **env var name**,
+     `dockerOverSsh`) and state **where tests ran** (local vs remote host).
+   - Do not paste private keys, tokens, or resolved secret **values**; use
+     `python scripts/remote_config_summary.py` for a names-only summary when needed.
 18. Runtime QA autopilot execution contract (US-0065 / DEC-0047):
    - Treat runtime verification as mandatory for generated-project scope; static
      checks alone are not sufficient evidence for PASS readiness.

package/template/.cursor/commands/qa.md

@@ -114,6 +114,11 @@ verify no unresolved blockers.
    - If remote connectivity config is incomplete for required remote checks,
      mark blocking with deterministic reason code
      `REMOTE_CONNECTIVITY_CONFIG_INVALID`.
+   - **US-0084**: when `REMOTE_EXECUTION=1`, expect **`handoffs/dev_to_qa.md`**
+     to carry an **environment label** (`WSL`, `ssh:<hostEnv>`, `dockerOverSsh`, …)
+     and **test locus** (local vs remote); reject evidence that pastes secret
+     values (keys/passwords) — **names-only** refs align with
+     `python scripts/remote_config_summary.py` output.
 13. Runtime QA autopilot contract (US-0065 / DEC-0047):
    - Runtime truth path is mandatory for generated-project QA:
      `startup -> readiness/connectivity -> log scan -> bounded retry -> verdict`.

package/template/.cursor/scratchpad.md

@@ -101,9 +101,13 @@ SPRINT_BULK_MAX_STORIES=5
 SPRINT_BULK_MAX_SPRINTS=3
 SPRINT_BULK_SELECTION=priority_then_backlog_order
 #
-# Remote execution
-# - REMOTE_EXECUTION: 0|1
-# - REMOTE_CONFIG: path to remote config
+# Remote execution (US-0084 / US-0064)
+# - REMOTE_EXECUTION: 0|1 — 0 skips remote.json validation (zero overhead; DEC-0070).
+# - REMOTE_CONFIG: path to dev/Cursor remote JSON (default .cursor/remote.json).
+#   Release/QA SSH/Docker connectivity fields live in docs/engineering/release-targets.json
+#   (ssh-server, dockerOverSsh); map WSL vs SSH vs Docker-over-SSH in
+#   docs/engineering/runtime-connectivity.md and docs/engineering/us-0084-remote-e2e.md.
+# - Summary helper (names-only stdout): python scripts/remote_config_summary.py
 REMOTE_EXECUTION=0
 REMOTE_CONFIG=.cursor/remote.json
 #

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -28,6 +28,8 @@ scripts/intake_evidence_lib.py
 scripts/intake_bug_routing_guard.py
 scripts/check_intake_template_parity.py
 scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
 scripts/enforce-triad-hot-surface.py
 .github/workflows
 README.md
@@ -52,6 +54,8 @@ scripts/intake_evidence_lib.py
 scripts/intake_bug_routing_guard.py
 scripts/check_intake_template_parity.py
 scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
 scripts/enforce-triad-hot-surface.py
 .github/workflows/ci.yml
 .github/workflows/deploy.yml
@@ -69,4 +73,6 @@ scripts/intake_evidence_lib.py
 scripts/intake_bug_routing_guard.py
 scripts/check_intake_template_parity.py
 scripts/materialize_codebase_map.py
+scripts/remote_config_summary.py
+scripts/guard_installer_publish.py
 scripts/enforce-triad-hot-surface.py

package/template/docs/engineering/runbook.md

@@ -313,6 +313,7 @@ binding before backlog/acceptance writes.
 - Regression: `tests/intake_evidence_fixtures_test.py` (R-0055 **AC-8** matrix tiers A/B),
   invoked from `tests/run-tests.ps1` / `tests/run-tests.sh` §26k.
 - **Packaged installs (BUG-0001 / DEC-0063)**: `intake_evidence_validate.py`, `intake_evidence_lib.py`, and `intake_bug_routing_guard.py` are mirrored under `template/scripts/` and listed in `docs/engineering/context/installer-owned-paths.manifest` so fresh install and `upgrade` copy them to the consumer’s `scripts/`. Drift guard: `python scripts/check_intake_template_parity.py --repo .` (also §26N in `tests/run-tests.*`). **Release (S0060)**: operator notes `handoffs/releases/S0060-release-notes.md` (gate summary + verify steps).
+- **US-0084**: `remote_config_summary.py` and `guard_installer_publish.py` use the same **`template/scripts/`** mirror + manifest rows; npm **`package.json` `files`** also lists the active copies for publish.
 - **Installer completeness gate (BUG-0003 / DEC-0066)**: post-install invariant checks every path in `[required_install_script_paths]` from `docs/engineering/context/installer-owned-paths.manifest`. Missing paths fail closed with `INSTALL_COMPLETENESS_FAILED` and `INSTALL_REQUIRED_SCRIPT_MISSING:<path>`. Remediation: update manifest parity (active + `template/`), ensure required script exists under `template/scripts/`, keep install/clean ownership paired, then rerun `its-magic --mode missing|upgrade` (or `python installer.py --validate-install-completeness --target <repo>` for direct diagnostics).
 - **Guided** and **low-touch** (`INTAKE_GUIDED_MODE=0`) share the **same** pre-persistence
   validation pipeline; mandatory pack evidence is never skipped.
@@ -816,6 +817,36 @@ Operator troubleshooting:
   - Replace with env-var reference fields (`tokenEnv`, `passwordEnv`,
     `privateKeyPathEnv`, ...).
 
+### Published npm `installer.sh` / POSIX dash (US-0084)
+
+- **Symptom**: `set: Illegal option -` on an early line when running `its-magic` or
+  `sh installer.sh` on Debian/Ubuntu (**`/bin/sh`** → **dash**).
+- **Common causes**: bash-only `set` options (`pipefail`, `-o errexit`, `-u` bundles)
+  on the **unconditional** startup path, or **CRLF** line endings in the file that
+  ships from npm.
+- **`sh` vs `bash`**: the Unix CLI path uses **`sh` + `installer.sh`** (**BUG-0004** /
+  **DEC-0068**). Do not assume bash for the first lines of **`installer.sh`**.
+- **Remediation**:
+  - Upgrade to an **its-magic** build that includes **US-0084** (LF + POSIX guards).
+  - Normalize to **LF** only (e.g. `dos2unix installer.sh`, or fix checkout —
+    root **`.gitattributes`** uses `*.sh text eol=lf`).
+  - Reinstall from npm after verifying maintainer gates:
+    `python scripts/guard_installer_publish.py` (also **`npm run guard:installer`**
+    / **`prepublishOnly`**).
+- **Normative**: **`docs/engineering/architecture.md`** **`# US-0084`**.
+
+### Automated checks (US-0084)
+
+- `python tests/installer_shell_bug0004_test.py` — CR/LF rejection, forbidden
+  `set` tokens, optional **`dash -n`** when **`dash`** is on **`PATH`**.
+- `python scripts/guard_installer_publish.py` — same checks for publish/CI
+  (**`prepublishOnly`**).
+- `python scripts/remote_config_summary.py` — with **`REMOTE_EXECUTION=1`**,
+  read-only summary of **`REMOTE_CONFIG`** (default **`.cursor/remote.json`**);
+  stdout is **names-only** (no secret values). **`DEC-0070`**: when
+  **`REMOTE_EXECUTION=0`**, the helper exits **0** and skips validation
+  (stderr skip reason).
+
 ## Runtime QA autopilot contract (US-0065 / DEC-0047)
 
 Generated-project validation requires runtime proof, not static checks alone.

package/template/docs/engineering/runtime-connectivity.md

@@ -32,3 +32,23 @@ For each enabled target include:
 - Do not write inline credentials/tokens/private keys.
 - Only env reference names are permitted in connectivity artifacts.
 - Redact auth details in handoffs and release outputs.
+
+## Dev/QA remote profiles vs `release-targets.json` (US-0084)
+
+Use this table to map **where you run tests** to the **US-0064** release/QA
+connectivity model (**no parallel schema**). Cursor/dev **`REMOTE_CONFIG`** is
+documented in the runbook; it complements, not replaces, **`release-targets.json`**.
+
+| Operator path | Maps in `release-targets.json` | Scratchpad / dev config |
+|---------------|----------------------------------|-------------------------|
+| **WSL** | Local Linux on the same machine — not a separate target row by default. | Usually **`REMOTE_EXECUTION=0`**. Cite **environment label** **`WSL`** in QA evidence. |
+| **Bare SSH Linux** | **`ssh-server`**: `hostEnv`, `userEnv`, `authEnv`, `remoteCommand`, `runtime`, ingress. | **`REMOTE_EXECUTION=1`**, **`REMOTE_CONFIG=.cursor/remote.json`** (see **`.cursor/scratchpad.md`**). |
+| **Docker-over-SSH** | **`ssh-server.dockerOverSsh`**: `dockerHostEnv`, `dockerContextEnv`, `composeFile`, `service`. | Same scratchpad keys; operator sets **`DOCKER_HOST`** / context using **env names** only in docs. |
+
+### `docker_over_ssh` (operator summary)
+
+When **`dockerOverSsh.enabled`** is true on **`ssh-server`**, connectivity flows
+through SSH to a host where Docker commands run; **`dockerHostEnv`** and
+**`dockerContextEnv`** name the operator env vars (values never pasted into
+artifacts). **`composeFile`** and **`service`** identify the stack slice. Full
+fields remain in **`docs/engineering/release-targets.json`** and **DEC-0044**.

package/template/docs/engineering/us-0084-remote-e2e.md

@@ -0,0 +1,39 @@
+# US-0084 — Minimal remote sanity path (Windows → WSL or SSH Linux)
+
+Sprint **S0069** / story **US-0084**. This is a short operator walkthrough; normative
+contracts live in **`docs/engineering/architecture.md`** **`# US-0084`**,
+**`docs/engineering/release-targets.json`**, and **`docs/engineering/runtime-connectivity.md`**
+(**US-0064**).
+
+## Path A — WSL (local Linux on the Windows machine)
+
+1. Install/launch **WSL** and open a Linux shell in the repo (or clone the repo inside WSL).
+2. Ensure **Node.js** and **Python 3** are available on **PATH** (same as host runbook).
+3. Run **`npm pack`** / local **`its-magic`** or **`sh installer.sh --target <repo> --mode missing --create`** from the package root.
+4. Run **`python tests/installer_shell_bug0004_test.py`** and your stack’s **`TEST_COMMAND`** (from merged runbook / scratchpad).
+5. Evidence: set **environment label** **`WSL`** in QA handoffs; **`REMOTE_EXECUTION=0`** is typical (no **`.cursor/remote.json`** validation required).
+
+## Path B — SSH to a Linux host
+
+1. SSH into the Linux machine; clone or sync the repo there.
+2. Run the same **`sh`/`dash`** installer and **`python`** tests as on native Linux.
+3. For **release/QA connectivity** semantics, align with **`ssh-server`** in
+   **`docs/engineering/release-targets.json`** (`hostEnv`, `userEnv`, `authEnv`, …).
+4. For **Cursor/dev remote** validation, set **`REMOTE_EXECUTION=1`** and
+   **`REMOTE_CONFIG=.cursor/remote.json`** on the merged scratchpad; run
+   **`python scripts/remote_config_summary.py`** — stdout must list **names only**
+   (no keys/passwords).
+5. Evidence: cite **`ssh:<hostEnv>`** (the **env var name**, not the host value) plus
+   **environment label**; never paste private key material.
+
+## Path C — Docker-over-SSH
+
+1. Follow **Path B** on the SSH host; enable **`dockerOverSsh`** patterns per
+   **`runtime-connectivity.md`** (**`dockerHostEnv`**, **`dockerContextEnv`**, **`composeFile`**, **`service`**).
+2. Set operator **`DOCKER_HOST`** / context per your platform; document **env names**
+   only in handoffs.
+
+## Related
+
+- **`tests/run-tests.sh`** / **`tests/run-tests.ps1`** — **H1–H5** (**US-0084** / AC-10).
+- **`python scripts/guard_installer_publish.py`** — publish-time LF + POSIX guard.

package/template/scripts/guard_installer_publish.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Prepublish / CI guard: installer.sh LF + POSIX-safe startup tokens (US-0084 / AC-2)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+INSTALLER_SH = ROOT / "installer.sh"
+
+FORBIDDEN_TOKENS = (
+    "set -euo",
+    "set -o pipefail",
+    "set -eu -o pipefail",
+    "set -o errexit",
+    "set -o nounset",
+)
+
+
+def main() -> int:
+    if not INSTALLER_SH.is_file():
+        print("guard_installer_publish: installer.sh missing", file=sys.stderr)
+        return 1
+    data = INSTALLER_SH.read_bytes()
+    if b"\r" in data:
+        print(
+            "guard_installer_publish: CR/LF (\\r) bytes found in installer.sh — "
+            "use LF only; see docs/engineering/runbook.md (US-0084).",
+            file=sys.stderr,
+        )
+        return 1
+    text = data.decode("utf-8", errors="replace")
+    for token in FORBIDDEN_TOKENS:
+        if token in text:
+            print(
+                f"guard_installer_publish: forbidden startup token {token!r} in installer.sh",
+                file=sys.stderr,
+            )
+            return 1
+    dash = shutil.which("dash")
+    if dash:
+        r = subprocess.run(
+            [dash, "-n", str(INSTALLER_SH)],
+            cwd=ROOT,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        if r.returncode != 0:
+            print(
+                "guard_installer_publish: dash -n installer.sh failed:\n"
+                + (r.stderr or r.stdout or ""),
+                file=sys.stderr,
+            )
+            return 1
+    else:
+        print(
+            "guard_installer_publish: dash not on PATH; skipping dash -n "
+            "(Python CRLF + token checks still enforced).",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())