@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/skills/nsr-compliance/assets/nsrcompliance/harness/runner.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+# harness runner: orchestrates feature scripts + gates and validates typed envelopes.
+# Self-contained: resolves the repo root relative to this file, so it runs from
+# the compliance skill (.agents/skills/NSRcompliance/) OR from a generated .compliance/ tree.
+import argparse
+import json
+import pathlib
+import subprocess
+import sys
+import time
+
+
+def find_root():
+    for parent in pathlib.Path(__file__).resolve().parents:
+        if (parent / ".agents").is_dir():
+            return parent
+    raise SystemExit("error: no repo root (.agents/ not found upward from runner)")
+
+
+ROOT = find_root()
+SKILL = ROOT / ".agents" / "skills" / "compliance"
+FEATURES = ROOT / ".agents" / "skills" / "features"
+
+GATES_MAIN = ROOT / ".compliance" / "gates"
+GATES_SKILL = SKILL / "gates"
+
+ENVELOPES_MAIN = ROOT / ".compliance" / "harness" / "envelopes"
+ENVELOPES_SKILL = SKILL / "harness" / "envelopes"
+
+TELEMETRY_MAIN = ROOT / ".compliance" / "telemetry" / "logger.py"
+TELEMETRY_SKILL = SKILL / "telemetry" / "logger.py"
+
+ACTIONS = ["setup", "test", "smoke_test", "rollback", "start", "stop", "status"]
+
+
+def first_existing(*paths):
+    for p in paths:
+        if p.exists():
+            return p
+    return None
+
+
+def envelopes_dir():
+    d = first_existing(ENVELOPES_MAIN, ENVELOPES_SKILL)
+    if d is None:
+        d = ENVELOPES_SKILL
+        d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def telemetry_logger():
+    return first_existing(TELEMETRY_MAIN, TELEMETRY_SKILL)
+
+
+# --- danger model (mirrors .compliance/gates/check_danger.sh) -------------------
+DANGER_PRIMS = [
+    r"rm[ \t]+-rf", r"rm[ \t]+-fr",
+    r":\(\)", r"kill[ \t]+-9", r"\bpkill\b", r"\btaskkill\b",
+    r"git[ \t]+push[ \t]+--force", r"git[ \t]+reset[ \t]+--hard",
+    r"DROP[ \t]+(TABLE|DATABASE)", r"TRUNCATE[ \t]+TABLE",
+    r"dd[ \t]+if=", r"\bmkfs\b", r"chmod[ \t]+-R[ \t]+777",
+    r"curl[ \t].*\|[ \t]*sh", r"wget[ \t].*\|[ \t]*sh",
+]
+GATE_RE = r"^[ \t]*# gate:[ \t]*(dev|guard|human)([ \t:]+|$)"
+
+
+def gate_level(script):
+    if not pathlib.Path(script).exists():
+        return "none"
+    text = pathlib.Path(script).read_text(errors="ignore")
+    m = __import__("re").search(GATE_RE, text, __import__("re").M | __import__("re").I)
+    if m:
+        return m.group(1).lower()
+    if any(__import__("re").search(p, text, __import__("re").I) for p in DANGER_PRIMS):
+        return "ungated"
+    return "none"
+
+
+# --- gates -------------------------------------------------------------------
+def run_gates():
+    results = {}
+    if not GATES_MAIN.is_dir():
+        print("[harness] no gates at %s" % GATES_MAIN.relative_to(ROOT))
+        return {}
+    for gate in sorted(GATES_MAIN.glob("*.sh")):
+        print("[harness] gate %s" % gate.name)
+        results[gate.name] = subprocess.run(["bash", str(gate)], cwd=ROOT).returncode
+    return results
+
+
+# --- feature scripts ---------------------------------------------------------
+def run_feature(feature, action):
+    script = FEATURES / feature / ("%s.sh" % action)
+    if not script.exists():
+        return 1, "missing script: %s" % script.relative_to(ROOT)
+    level = gate_level(script)
+    print("[harness] running %s (gate: %s)" % (script.relative_to(ROOT), level))
+    rc = subprocess.run(["bash", str(script)], cwd=ROOT).returncode
+    return rc, "%s:%s" % (feature, action), level
+
+
+# --- envelopes ---------------------------------------------------------------
+def satisfies(ftype, value):
+    if ftype == "string":
+        return isinstance(value, str)
+    if ftype == "array":
+        return isinstance(value, list)
+    if ftype == "object":
+        return isinstance(value, dict)
+    if ftype == "boolean":
+        return isinstance(value, bool)
+    if ftype == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if ftype == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    return True
+
+
+def validate_envelope(data, schema):
+    errors = []
+    for name, spec in schema.get("fields", {}).items():
+        if spec.get("required", False) and name not in data:
+            errors.append("missing required field: %s" % name)
+            continue
+        if name not in data:
+            continue
+        value = data[name]
+        ftype = spec.get("type")
+        if ftype and not satisfies(ftype, value):
+            errors.append("field %s: expected %s, got %s" % (name, ftype, type(value).__name__))
+            continue
+        if ftype == "array" and isinstance(value, list):
+            item_type = (spec.get("items") or {}).get("type")
+            for i, item in enumerate(value):
+                if item_type and not satisfies(item_type, item):
+                    errors.append("field %s[%d]: expected %s" % (name, i, item_type))
+        enum = spec.get("enum")
+        if enum and value not in enum:
+            errors.append("field %s: must be one of %s, got %r" % (name, enum, value))
+    return errors
+
+
+def load_envelope(path, schema):
+    try:
+        data = json.loads(pathlib.Path(path).read_text())
+    except (OSError, ValueError) as exc:
+        return None, ["cannot read envelope %s: %s" % (path, exc)]
+    return data, validate_envelope(data, schema)
+
+
+def load_schema():
+    schema = first_existing(ENVELOPES_MAIN / "task_envelope.json",
+                            ENVELOPES_SKILL / "task_envelope.json")
+    if schema is None:
+        raise SystemExit("error: task_envelope.json schema not found")
+    return json.loads(schema.read_text())
+
+
+# --- observability -----------------------------------------------------------
+def telemetry(phase, status, latency_ms=0.0, run_id=None):
+    logger = telemetry_logger()
+    if logger is None:
+        return
+    cmd = ["python3", str(logger), "log", "--phase", phase, "--status", status,
+           "--latency-ms", str(latency_ms)]
+    if run_id:
+        cmd += ["--run-id", run_id]
+    subprocess.run(cmd, cwd=ROOT)
+
+
+def write_result(task_id, status, gates, detail, error):
+    result = {
+        "envelope": "result",
+        "task_id": task_id,
+        "status": status,
+        "gates": gates,
+        "evidence": ["gates pass"] if status == "success" else [],
+        "ts": time.time(),
+    }
+    if detail:
+        result["artifacts"] = [detail]
+    if error:
+        result["error"] = error
+    out = envelopes_dir() / ("result_%s.json" % task_id)
+    out.write_text(json.dumps(result, indent=2) + "\n")
+    print("[harness] wrote %s" % out.relative_to(ROOT))
+
+
+# --- commands ----------------------------------------------------------------
+def cmd_envelope(args):
+    data, errors = load_envelope(args.envelope, load_schema())
+    for err in errors:
+        print("[harness] ENVELOPE FAIL: %s" % err, file=sys.stderr)
+    if not errors:
+        print("[harness] envelope OK: %s (task %s)" % (args.envelope, data.get("task_id")))
+    return 1 if errors else 0
+
+
+def cmd_plan(args):
+    data, errors = load_envelope(args.plan, load_schema())
+    task_id = (data or {}).get("task_id", "unknown")
+    if errors:
+        for err in errors:
+            print("[harness] ENVELOPE FAIL: %s" % err, file=sys.stderr)
+        write_result(task_id, "fail", {}, None, "envelope invalid")
+        telemetry("plan", "fail")
+        return 1
+
+    gates = run_gates()
+    gate_fail = [name for name, rc in gates.items() if rc != 0]
+    if gate_fail:
+        print("[harness] PLAN FAIL: gates failed: %s" % ", ".join(gate_fail))
+        write_result(task_id, "fail", gates, None, "gates failed")
+        telemetry("plan", "fail")
+        return 1
+
+    script = FEATURES / data["feature"] / ("%s.sh" % args.action)
+    level = gate_level(script) if script.exists() else "none"
+    if level in ("human", "guard") and not args.confirm_gate:
+        print("[harness] PLAN REFUSED: %s %s is gated '%s' (irreversible); "
+              "human must run it or pass --confirm-gate" % (data["feature"], args.action, level))
+        write_result(task_id, "escalate", gates, None, "human-gated script")
+        telemetry("plan", "escalate")
+        return 1
+    if level == "ungated":
+        print("[harness] PLAN FAIL: script has dangerous primitives but no # gate: annotation")
+        write_result(task_id, "fail", gates, None, "ungated dangerous script")
+        telemetry("plan", "fail")
+        return 1
+
+    t0 = time.time()
+    rc, detail, _ = run_feature(data["feature"], args.action)
+    if rc != 0:
+        print("[harness] PLAN FAIL: feature %s %s failed" % (data["feature"], args.action))
+        write_result(task_id, "fail", gates, detail, "feature failed")
+        telemetry("plan", "fail", latency_ms=(time.time() - t0) * 1000.0)
+        return 1
+
+    print("[harness] PLAN PASS")
+    write_result(task_id, "success", gates, detail, None)
+    telemetry("plan", "success", latency_ms=(time.time() - t0) * 1000.0)
+    return 0
+
+
+def stub_marker(path):
+    try:
+        return bool(__import__("re").search(r"\bSTUB\b|# stub[: ]", path.read_text(errors="ignore"), __import__("re").I))
+    except (OSError, ValueError):
+        return True
+
+
+def cmd_list(_args):
+    print("[harness] registry (root %s)" % ROOT)
+    for domain in ("lifecycle", "git_ops", "features"):
+        d = ROOT / ".agents" / "skills" / domain
+        if not d.is_dir():
+            continue
+        scripts = sorted(p.name for p in d.glob("*.sh"))
+        if not scripts:
+            continue
+        print("  %s/  %s" % (domain, " ".join(scripts)))
+    fdir = FEATURES
+    print("[harness] features: %s" % (" ".join(sorted(p.name for p in fdir.iterdir() if p.is_dir()))
+                                      if fdir.is_dir() else "(none)"))
+    for feature_dir in sorted(fdir.iterdir()) if fdir.is_dir() else []:
+        if not feature_dir.is_dir():
+            continue
+        line = []
+        for s in sorted(feature_dir.glob("*.sh")):
+            line.append("%s%s" % (s.stem, "*STUB" if stub_marker(s) else ""))
+        print("  features/%s  %s" % (feature_dir.name, " ".join(line)))
+    return 0
+
+
+def main():
+    p = argparse.ArgumentParser(description="WayOfNorthStar deterministic harness runner (self-contained)")
+    p.add_argument("--envelope", metavar="FILE", help="validate a task envelope; exit 1 on violation")
+    p.add_argument("--plan", metavar="ENVELOPE", help="full run: envelope -> gates -> feature -> result envelope")
+    p.add_argument("--feature", help="feature name under .agents/skills/features/")
+    p.add_argument("--action", choices=ACTIONS, default="test")
+    p.add_argument("--gates", action="store_true", help="run all validation gates")
+    p.add_argument("--list", action="store_true", help="show the script registry (stubs flagged)")
+    p.add_argument("--confirm-gate", action="store_true", help="allow running a human/guard-gated script")
+    a = p.parse_args()
+
+    if a.list:
+        return cmd_list(a)
+    if a.envelope:
+        return cmd_envelope(a)
+    if a.plan:
+        return cmd_plan(a)
+    if a.gates:
+        results = run_gates()
+        return 0 if all(rc == 0 for rc in results.values()) else 1
+    if a.feature:
+        rc, _, _ = run_feature(a.feature, a.action)
+        return rc
+    p.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/nsr-compliance/assets/nsrcompliance/telemetry/logger.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# telemetry logger: SQLite observability.
+# One data path: agents write to SQLite (runs/events); readers poll SQLite.
+import argparse
+import json
+import pathlib
+import sqlite3
+import sys
+import time
+import uuid
+
+
+def find_root():
+    for parent in pathlib.Path(__file__).resolve().parents:
+        if (parent / ".agents").is_dir():
+            return parent
+    raise SystemExit("error: not in a NorthStar repo (no .agents/ upward)")
+
+
+ROOT = find_root()
+DB = ROOT / ".compliance" / "telemetry" / "runs.db"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS runs (
+  id TEXT PRIMARY KEY,
+  ts REAL NOT NULL,
+  phase TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'success',
+  tokens INTEGER NOT NULL DEFAULT 0,
+  latency_ms REAL NOT NULL DEFAULT 0,
+  tool_invocations INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT,
+  ts REAL NOT NULL,
+  type TEXT NOT NULL,
+  detail TEXT
+);
+"""
+
+
+def connect():
+    DB.parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(str(DB))
+    con.executescript(SCHEMA)
+    return con
+
+
+def cmd_log(args):
+    run_id = args.run_id or uuid.uuid4().hex[:12]
+    con = connect()
+    con.execute(
+        "INSERT INTO runs (id, ts, phase, status, tokens, latency_ms, tool_invocations, cost_usd) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+        (run_id, time.time(), args.phase, args.status, args.tokens,
+         args.latency_ms, args.tool_invocations, args.cost),
+    )
+    for ev in args.event or []:
+        etype, _, detail = ev.partition(":")
+        con.execute(
+            "INSERT INTO events (run_id, ts, type, detail) VALUES (?, ?, ?, ?)",
+            (run_id, time.time(), etype, detail),
+        )
+    con.commit()
+    print("[telemetry] logged %s (%s): tokens=%d latency=%.1fms tools=%d cost=$%.4f"
+          % (args.phase, run_id, args.tokens, args.latency_ms, args.tool_invocations, args.cost))
+    con.close()
+
+
+def cmd_query(args):
+    con = connect()
+    rows = con.execute(
+        "SELECT id, ts, phase, status, tokens, latency_ms, tool_invocations, cost_usd "
+        "FROM runs ORDER BY ts DESC LIMIT ?",
+        (args.last,),
+    ).fetchall()
+    for row in rows:
+        print(json.dumps(dict(zip(
+            ["run_id", "ts", "phase", "status", "tokens", "latency_ms", "tool_invocations", "cost_usd"],
+            row))))
+    con.close()
+
+
+def main():
+    p = argparse.ArgumentParser(description="WayOfNorthStar telemetry logger (SQLite)")
+    sub = p.add_subparsers(dest="cmd")
+    logp = sub.add_parser("log", help="write a run/event record")
+    logp.add_argument("--run-id")
+    logp.add_argument("--phase", default="debug")
+    logp.add_argument("--status", default="success")
+    logp.add_argument("--tokens", type=int, default=0)
+    logp.add_argument("--latency-ms", type=float, default=0.0)
+    logp.add_argument("--tool-invocations", type=int, default=0)
+    logp.add_argument("--cost", type=float, default=0.0)
+    logp.add_argument("--event", action="append", help="type[:detail]")
+    qp = sub.add_parser("query", help="read recent runs (readers poll SQLite)")
+    qp.add_argument("--last", type=int, default=10)
+    args = p.parse_args()
+    if args.cmd == "log":
+        cmd_log(args)
+        return 0
+    if args.cmd == "query":
+        cmd_query(args)
+        return 0
+    p.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/README.md

@@ -0,0 +1,18 @@
+# .compliance/ — __PROJECT__
+
+Deterministic harness engine. Programmatic guardrails for every agent run.
+
+## Structure
+```
+.compliance/
+├── config/         # core_four.yaml (Core Four)
+├── gates/          # check_env.sh, check_paths.sh, check_platform.sh
+├── harness/        # runner.py + envelopes/
+├── telemetry/      # logger.py
+└── installer/      # install.sh
+```
+
+## Rules
+- Code-based gates: `$? == 0`, never text parsing.
+- Typed envelopes for inter-agent handoffs.
+- Observability logged for every run.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/config/README.md

@@ -0,0 +1,10 @@
+# config/ — __PROJECT__
+
+Core Four configuration.
+
+## Files
+- `core_four.yaml` — Context, Model, Prompt, Tools per agent phase.
+
+## Rules
+- Everything governed via config; no agent discretion.
+- Read by `.compliance/harness/runner.py`.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/gates/README.md

@@ -0,0 +1,12 @@
+# gates/ — __PROJECT__
+
+Deterministic validation gates. Decided by exit code.
+
+## Files
+- `check_env.sh` — required env vars present.
+- `check_paths.sh` — no absolute paths.
+- `check_platform.sh` — POSIX-portable.
+
+## Rules
+- Gates evaluate by `$? == 0`.
+- Run before commit and before deploy.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/gates/check_env.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Gate: verify required env vars are present (env-driven config).
+set -e
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+if [ -f "$ROOT/.env" ]; then
+  set -a; . "$ROOT/.env"; set +a
+fi
+
+REQUIRED=()
+[ -n "${REQUIRED_ENV:-}" ] && IFS=',' read -ra REQUIRED <<< "$REQUIRED_ENV" || true
+
+missing=0
+for var in "${REQUIRED[@]}"; do
+  if [ -z "${!var:-}" ]; then
+    echo "[check_env] MISSING: $var"
+    missing=1
+  fi
+done
+
+[ "$missing" -ne 0 ] && { echo "[check_env] FAIL"; exit 1; }
+echo "[check_env] PASS"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/gates/check_paths.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Gate: enforce RELATIVE filepaths only. Rejects absolute paths in scripts/configs.
+set -e
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+violations=0
+for ext in sh py yaml yml json; do
+  for f in $(find . -type f -name "*.$ext" -not -path './.git/*' -not -path './.compliance/telemetry/*'); do
+    while IFS= read -r line; do
+      case "$line" in
+        /*|C:*|D:*) echo "[check_paths] ABSOLUTE PATH: $f -> $line"; violations=1 ;;
+      esac
+    done < "$f"
+  done
+done
+
+[ "$violations" -ne 0 ] && { echo "[check_paths] FAIL"; exit 1; }
+echo "[check_paths] PASS"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/gates/check_platform.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Gate: validate scripts are POSIX-portable (Mac/Linux/Windows).
+set -e
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+violations=0
+for f in $(find . -type f -name "*.sh" -not -path './.git/*' -not -path './.compliance/gates/*' -not -path './.agents/skills/NSRcompliance/*' -not -path './.agents/skills/NSR/*' -not -path './.agents/skills/NSR-SKILLMAKER/*' -not -path './mockprojectroot/*'); do
+  for cmd in 'taskkill' 'pkill' 'kill -9'; do
+    if grep -qE "$cmd" "$f" 2>/dev/null; then
+      echo "[check_platform] NON-PORTABLE: $f uses '$cmd'"
+      violations=1
+    fi
+  done
+  if grep -q $'\r' "$f" 2>/dev/null; then
+    echo "[check_platform] CRLF in $f"
+    violations=1
+  fi
+done
+
+[ "$violations" -ne 0 ] && { echo "[check_platform] FAIL"; exit 1; }
+echo "[check_platform] PASS"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/harness/README.md

@@ -0,0 +1,11 @@
+# harness/ — __PROJECT__
+
+Local execution harness.
+
+## Files
+- `runner.py` — orchestrator (feature scripts + gates).
+- `envelopes/` — typed handoff schemas.
+
+## Rules
+- Runner invokes `.agents/skills/features/<feature>/*.sh` and evaluates exit codes.
+- Handoffs use typed envelopes.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/harness/envelopes/README.md

@@ -0,0 +1,10 @@
+# envelopes/ — __PROJECT__
+
+Typed inter-agent handoff schemas.
+
+## Files
+- `task_envelope.json` — standard task packet schema.
+
+## Rules
+- No unstructured text summaries between agents.
+- New envelope types added here before use.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/installer/README.md

@@ -0,0 +1,10 @@
+# installer/ — __PROJECT__
+
+Self-install tooling for the deterministic harness.
+
+## Files
+- `install.sh` — install the harness into a repo.
+
+## Rules
+- Single repeatable command to install `.compliance/`.
+- Installs config, gates, harness, envelopes, telemetry.