@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/skills/nsr-compliance/assets/nsr/scripts/scaffold.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# NSR scaffold: create OR convert a project to the WayOfNorthStar layout.
+# Fully self-contained — copies templates from THIS skill's assets/ and gates the result.
+#
+# Usage:
+#   scaffold.sh /path/to/project --name "MyProject" [--description "What it does"] [--force]
+#
+# - Creates the full NSR tree (root routing files, RULES/, docs/, .agents/skills/, .compliance/).
+# - Never overwrites existing files unless --force is passed.
+# - Substitutes __PROJECT__ / __DESCRIPTION__ / __project__ in templates.
+# - Post-condition: runs validate.sh and requires it to pass.
+set -e
+
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ASSETS="$SKILL_DIR/assets"
+
+PROJECT_DIR=""
+PROJECT_NAME=""
+PROJECT_DESCRIPTION="__DESCRIPTION__"
+FORCE=0
+
+usage() {
+  echo "Usage: scaffold.sh <dir> --name <ProjectName> [--description <text>] [--force]"
+  exit 1
+}
+
+# --- parse args ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name) PROJECT_NAME="$2"; shift 2 ;;
+    --description) PROJECT_DESCRIPTION="$2"; shift 2 ;;
+    --force) FORCE=1; shift ;;
+    -h|--help) usage ;;
+    -*) echo "Unknown option: $1"; usage ;;
+    *) PROJECT_DIR="$1"; shift ;;
+  esac
+done
+
+[ -n "$PROJECT_DIR" ] && [ -n "$PROJECT_NAME" ] || usage
+
+# slug for env templates (lowercase, hyphenated)
+SLUG=$(printf '%s' "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')
+
+mkdir -p "$PROJECT_DIR"
+cd "$PROJECT_DIR"
+DEST_ROOT="$(pwd)"
+
+echo "[nsr] scaffolding $PROJECT_NAME -> $DEST_ROOT"
+
+copy_tree() {
+  local src="$1"; local dst="$2"
+  mkdir -p "$dst"
+  for item in "$src"/*; do
+    [ -e "$item" ] || continue
+    local base; base="$(basename "$item")"
+    if [ -d "$item" ]; then
+      copy_tree "$item" "$dst/$base"
+    else
+      local target="$dst/$base"
+      if [ -e "$target" ] && [ "$FORCE" -eq 0 ]; then
+        echo "[nsr] SKIP (exists): $target"
+        continue
+      fi
+      # placeholder substitution
+      sed -e "s|__PROJECT__|$PROJECT_NAME|g" \
+          -e "s|__DESCRIPTION__|$PROJECT_DESCRIPTION|g" \
+          -e "s|__project__|$SLUG|g" \
+          "$item" > "$target"
+      echo "[nsr] wrote: $target"
+    fi
+  done
+}
+
+echo "[nsr] root routing files + RULES/"
+copy_tree "$ASSETS/root" "$DEST_ROOT"
+copy_tree "$ASSETS/RULES" "$DEST_ROOT/RULES"
+
+echo "[nsr] docs/ tree"
+copy_tree "$ASSETS/docs" "$DEST_ROOT/docs"
+
+echo "[nsr] .agents/skills/ tree"
+copy_tree "$ASSETS/agents_skills" "$DEST_ROOT/.agents/skills"
+
+echo "[nsr] .compliance/ tree (generated by the self-contained compliance skill)"
+if [ -f "$DEST_ROOT/.agents/skills/NSRcompliance/generate.sh" ]; then
+  bash "$DEST_ROOT/.agents/skills/NSRcompliance/generate.sh" "$DEST_ROOT" --force
+else
+  echo "[nsr] (fallback) stamping from assets/compliance"
+  copy_tree "$ASSETS/compliance" "$DEST_ROOT/.compliance"
+fi
+
+# make scripts executable
+find "$DEST_ROOT/.agents/skills" -name "*.sh" -type f -exec chmod u+x {} + 2>/dev/null || true
+find "$DEST_ROOT/.compliance" -name "*.sh" -type f -exec chmod u+x {} + 2>/dev/null || true
+chmod +x "$DEST_ROOT/docs/CI_CD/deployment/deploy.sh" 2>/dev/null || true
+
+echo "[nsr] running validation"
+"$SKILL_DIR/scripts/validate.sh" "$DEST_ROOT"
+
+echo "[nsr] DONE: $PROJECT_NAME scaffolded at $DEST_ROOT"
+echo "[nsr] next: git init, fill TECH_STACK.md/FEATURES.md, add features under .agents/skills/features/"
+
+exit 0

package/.agents/skills/nsr-compliance/assets/nsr/scripts/validate.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# NSR validate: audit a repo against NSR compliance gates.
+#
+# Usage: validate.sh [project-dir]   (defaults to current dir)
+#
+# Runs: verify_docs (structure) -> check_env -> check_paths -> check_platform.
+# Any non-zero exit fails validation.
+set -e
+
+PROJECT_DIR="${1:-$(pwd)}"
+cd "$PROJECT_DIR"
+ROOT="$(pwd)"
+
+echo "[nsr/validate] validating $ROOT"
+
+fail=0
+
+echo "[nsr/validate] 1/4 structure + docs (verify_docs.py)"
+if python3 "$ROOT/.agents/skills/NSRcompliance/gates/verify_docs.py"; then
+  echo "[nsr/validate] structure OK"
+else
+  echo "[nsr/validate] STRUCTURE FAIL"; fail=1
+fi
+
+echo "[nsr/validate] 2/4 env (check_env.sh)"
+if bash "$ROOT/.compliance/gates/check_env.sh"; then
+  echo "[nsr/validate] env OK"
+else
+  echo "[nsr/validate] ENV FAIL"; fail=1
+fi
+
+echo "[nsr/validate] 3/4 paths (check_paths.sh)"
+if bash "$ROOT/.compliance/gates/check_paths.sh"; then
+  echo "[nsr/validate] paths OK"
+else
+  echo "[nsr/validate] PATHS FAIL"; fail=1
+fi
+
+echo "[nsr/validate] 4/4 platform (check_platform.sh)"
+if bash "$ROOT/.compliance/gates/check_platform.sh"; then
+  echo "[nsr/validate] platform OK"
+else
+  echo "[nsr/validate] PLATFORM FAIL"; fail=1
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "[nsr/validate] FAILED"
+  exit 1
+fi
+
+echo "[nsr/validate] PASS — repo is NSR-compliant"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsrcompliance/SKILL.md

@@ -0,0 +1,71 @@
+# SKILL.md — Embedded Agent Skill Compliance
+
+Headless CLI runner + local validation layer — the sole, script-first compliance mechanism.
+
+The compliance skill is **self-contained**: it needs no rest of the NSR repo. It carries its own runner, gates, telemetry, envelopes, templates, and a generator that stamps `.compliance/` into whatever repo it is deployed into.
+
+## Purpose
+
+- Generate the deterministic `.compliance/` harness into a repo with one command.
+- Execute feature + lifecycle scripts and gate checks locally inside that repo.
+- Enforce typed envelopes (validated before any run) and wired, non-stub scripting.
+- Record every run (phase, status, latency, cost) into a local SQLite DB.
+
+## Capabilities
+
+- **Generate** — `generate.sh [TARGET]` stamps a `.compliance/` tree into the host repository (idempotent; `--force`). Stack-agnostic: the wiring that follows adapts to whatever stack the repo uses.
+- **Harness** — `harness/runner.py` orchestrates gates + feature scripts; validates typed envelopes; full `--plan` runs (envelope → gates → feature action → result envelope); `--list` shows the script registry.
+- **Danger validation** — `gates/check_danger.sh` flags scripts containing dangerous primitives unless they declare `# gate: dev|guard|human`. The runner refuses to auto-run human/guard-gated scripts.
+- **Wiring awareness** — `gates/check_wiring.sh` reports which scripts are still shipped stubs vs bound to the project's real commands (`--strict` must pass before agents are trusted).
+- **Gates** — `gates/check_env.sh`, `check_paths.sh`, `check_platform.sh`, `validate_code.sh`, `verify_docs.py` decide pass/fail by `$? == 0`.
+- **Config** — `config/core_four.yaml` governs Context, Model, Prompt, Tools per phase.
+- **Envelopes** — `harness/envelopes/task_envelope.json` (+ `result_envelope.json`) valid task packets; success must be earned.
+- **Telemetry** — `telemetry/logger.py` writes runs/events to SQLite (`runs.db`); readers poll SQLite.
+
+## Usage
+
+```
+# 1. Generate the harness into this repo (self-contained)
+.agents/skills/NSRcompliance/generate.sh
+
+# 2. Report wiring status; strict before trusting agents
+.compliance/gates/check_wiring.sh
+.compliance/gates/check_wiring.sh --strict
+
+# 3. Danger audit
+.compliance/gates/check_danger.sh
+
+# 4. Validate a task envelope (exit 1 on any schema violation)
+.compliance/harness/runner.py --envelope .compliance/harness/envelopes/task_envelope.json
+
+# 5. Full run: envelope -> gates -> feature action -> result envelope
+.compliance/harness/runner.py --plan <task-envelope.json> --action test
+
+# 6. Run a feature / all gates / inspect the registry
+.compliance/harness/runner.py --feature <name> --action test
+.compliance/harness/runner.py --gates
+.compliance/harness/runner.py --list
+
+# 7. Telemetry
+.compliance/telemetry/logger.py log --phase plan --status success --latency-ms 120
+.compliance/telemetry/logger.py query --last 10
+```
+
+## Wiring to the project (what binds the compliance to your stack)
+
+The compliance is project-agnostic by design; the WIRING layer is where it benefits the specific project.
+
+1. Replace the stub bodies in `.agents/skills/lifecycle/{start,stop,status,smoke_test}.sh` with your real commands (Phoenix: `mix phx.server`; Node: `npm run dev`; Django: `manage.py runserver`...). Existing procedures are **wrapped, never replaced** — delegate to them and add env/exit-code guards.
+2. For every feature in `FEATURES.md`, wire `features/<name>/{setup,test,smoke_test,rollback}.sh` to the app's real suites and seeds.
+3. Add `# gate: dev|guard|human` to any script that touches production-affecting primitives.
+4. Prove it: `check_wiring.sh --strict` and `check_danger.sh` must pass.
+
+Walkthrough: `docs/BEST_PRACTICES/compliance-wiring.md`.
+
+## Rules
+
+- Zero ad-hoc shell commands — invoke compliance scripts only.
+- Gate results are evaluated by `$? == 0`, never by parsing text output.
+- Never lose a function: wiring delegates to existing procedures and adds guards.
+- Generated `.compliance/` is derived from this skill — regenerate, don't hand-edit both copies.
+- Syncs with WayOfTeams (Kanban Board, Knowledge Base, Anchor Memory) over MCP.

package/.agents/skills/nsr-compliance/assets/nsrcompliance/config/core_four.yaml

@@ -0,0 +1,16 @@
+core_four:
+  context:
+    default: "docs/features/*.md"
+    routing: "AGENTS.md, STRUCTURE.md, FEATURES.md"
+    scoped: ".agents/skills/**/SKILL.md"
+  model:
+    coding: "fast-cheap-model"
+    planning: "large-reasoning-model"
+    default: "default-model"
+  prompt:
+    system: "Follow WayOfNorthstarRules.md and AGENTS.md. No ad-hoc shell commands."
+    per_feature: ".agents/skills/features/<feature>/SKILL.md"
+  tools:
+    allowed_scripts: ".agents/skills/**"
+    forbidden: ["npm test", "git commit -m", "kill -9"]
+    handoff_format: "JSON/YAML typed envelopes"

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# check_danger: validate that scripts may be run by the compliance, or are explicitly gated.
+#
+# Any script containing a dangerous primitive (data loss, force ops, shell
+# injection, destructive commands) MUST declare its blast radius in a comment:
+#
+#   # gate: dev    - safe for agents/automation in dev; human confirm in prod
+#   # gate: guard  - must not run until a required guard script passes
+#   # gate: human  - irreversible; agents must never run this alone
+#
+# A script with dangerous primitives and no # gate: annotation FAILS this check.
+#
+# Usage:
+#   check_danger.sh            # scan .agents/skills/{lifecycle,git_ops,features,compliance}
+#   check_danger.sh --path <f> # evaluate a single script in isolation
+set -e
+
+find_root() {
+  local d; d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.agents" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+ROOT="$(find_root)" || { echo "[check_danger] FAIL: no repo root (.agents/ not found upward)"; exit 1; }
+SINGLE_PATH=""
+
+DANGER_PRIMS=(
+  'rm[[:space:]]+-rf'
+  'rm[[:space:]]+-fr'
+  ':\(\)[[:space:]]*\{'
+  'kill[[:space:]]+-9'
+  'pkill'
+  'taskkill'
+  'git[[:space:]]+push[[:space:]]+--force'
+  'git[[:space:]]+reset[[:space:]]+--hard'
+  'DROP[[:space:]]+(TABLE|DATABASE)'
+  'TRUNCATE[[:space:]]+TABLE'
+  'dd[[:space:]]+if='
+  'mkfs'
+  'chmod[[:space:]]+-R[[:space:]]+777'
+  'curl[[:space:]].*\|[[:space:]]*sh'
+  'wget[[:space:]].*\|[[:space:]]*sh'
+)
+
+GATE_RE='^[[:space:]]*# gate:[[:space:]]*(dev|guard|human)([[:space:]]+.*|:|$)'
+
+has_danger() {
+  local f="$1" prim
+  for prim in "${DANGER_PRIMS[@]}"; do
+    grep -qiE "$prim" "$f" 2>/dev/null && return 0
+  done
+  return 1
+}
+
+has_gate() { grep -qiE "$GATE_RE" "$1" 2>/dev/null; }
+
+check_file() {
+  local f="$1" g
+  has_danger "$f" || return 0
+  if has_gate "$f"; then
+    g="$(grep -iE "$GATE_RE" "$f" | head -1 | sed -E 's/^[[:space:]]*//')"
+    echo "  OK   [gated] $g"
+    echo "        $f"
+  else
+    echo "  FAIL [ungated danger] $f"
+    echo "        contains a dangerous primitive but no '# gate:' annotation"
+    return 1
+  fi
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path) SINGLE_PATH="$2"; shift 2 ;;
+    -h|--help) echo "usage: check_danger.sh [--path FILE]"; exit 0 ;;
+    -*) echo "unknown option: $1"; exit 1 ;;
+    *) SINGLE_PATH="$1"; shift ;;
+  esac
+done
+
+fail=0
+
+if [ -n "$SINGLE_PATH" ]; then
+  check_file "$SINGLE_PATH" || fail=1
+else
+  echo "[check_danger] scanning $ROOT/.agents/skills for dangerous primitives"
+  for f in "$ROOT"/.agents/skills/lifecycle/*.sh \
+           "$ROOT"/.agents/skills/git_ops/*.sh \
+           "$ROOT"/.agents/skills/features/*/*.sh; do
+    [ -f "$f" ] || continue
+    check_file "$f" || fail=1
+  done
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "[check_danger] FAIL: dangerous scripts without a # gate: annotation"
+  exit 1
+fi
+echo "[check_danger] PASS: no undeclared dangerous scripts"
+exit 0

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# check_wiring: does the compliance actually touch the project, or is it still stubs?
+#
+# A script is WIRED when the shipped STUB marker is gone from its body. A freshly
+# scaffolded repo is 100% stubs — that is fine during bootstrap. Before you trust
+# the compliance (run agents against it, deploy for real) run --strict: it must pass.
+#
+# Usage:
+#   check_wiring.sh             # report wired vs stub; exit 0 unless required scripts missing
+#   check_wiring.sh --strict    # exit 1 if any required script is missing or still a stub
+set -e
+
+find_root() {
+  local d; d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.agents" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+ROOT="$(find_root)" || { echo "[check_wiring] FAIL: no repo root (.agents/ not found upward)"; exit 1; }
+STRICT=0
+[ "${1:-}" = "--strict" ] && STRICT=1
+
+fail=0
+
+echo "[check_wiring] scanning for real-world wiring under $ROOT"
+
+is_stub() {
+  grep -qiE '\bSTUB\b|# stub[: ]' "$1" 2>/dev/null
+}
+
+check_script() {
+  local f="$1"
+  [ -f "$f" ] || { [ "$STRICT" -eq 1 ] && { echo "  FAIL [MISSING] $f"; fail=1; }; return 0; }
+  if is_stub "$f"; then
+    if [ "$STRICT" -eq 1 ]; then
+      echo "  FAIL [STUB  ] $f"
+      fail=1
+    else
+      echo "  warn [STUB  ] $f (not wired — see docs/BEST_PRACTICES/compliance-wiring.md)"
+    fi
+  else
+    echo "  ok   [WIRED ] $f"
+  fi
+}
+
+# lifecycle is mandatory for a project to be operable
+for f in start stop status smoke_test; do
+  check_script "$ROOT/.agents/skills/lifecycle/$f.sh"
+done
+
+# every feature dir must have its five script domains wired
+for d in "$ROOT"/.agents/skills/features/*/; do
+  [ -d "$d" ] || continue
+  for f in setup test smoke_test rollback; do
+    check_script "$d/$f.sh"
+  done
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "[check_wiring] STRICT FAIL — compliance scripts are stubs/missing, not wired to the project."
+  echo "[check_wiring] Wire them per docs/BEST_PRACTICES/compliance-wiring.md, then re-run."
+  exit 1
+fi
+[ "$STRICT" -eq 1 ] && echo "[check_wiring] PASS (strict) — every required script is wired"
+[ "$STRICT" -eq 0 ] && echo "[check_wiring] PASS (report) — nothing missing for a bootstrap repo"
+exit 0

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Deterministic gate: run test + lint checks. Exit 0 = pass, non-zero = fail.
+set -e
+
+echo "[gate] validate_code: running lint + test gates"
+
+gates_passed=0
+
+for gate in .compliance/gates/*.sh; do
+  if [ -x "$gate" ]; then
+    echo "[gate] running $gate"
+    "$gate" || gates_passed=1
+  fi
+done
+
+for script in .agents/skills/features/*/test.sh; do
+  if [ -f "$script" ]; then
+    echo "[gate] running $script"
+    bash "$script" || gates_passed=1
+  fi
+done
+
+if [ "$gates_passed" -eq 0 ]; then
+  echo "[gate] PASS ($? == 0)"
+  exit 0
+fi
+
+echo "[gate] FAIL"
+exit 1

package/.agents/skills/nsr-compliance/assets/nsrcompliance/gates/verify_docs.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# Deterministic gate: ensure STRUCTURE.md, FEATURES.md, HOSTING/, DEVELOPER_SETUP/ and TECH_STACK.md are in sync with the repo.
+import json
+import pathlib
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[4]
+MANDATORY = [
+    "AGENTS.md", "ARCHITECTURE.md", "STRUCTURE.md", "FEATURES.md",
+    "RULES.md", "BEST_PRACTICES.md", "CI_CD.md", "TECH_STACK.md", "README.md",
+]
+MANDATORY_DIRS = [
+    "RULES", "docs/features", "docs/BEST_PRACTICES", "docs/CI_CD",
+    "docs/DEVELOPER_SETUP", "docs/HOSTING", "docs/RUNBOOK", "docs/research",
+    ".agents/skills", ".compliance",
+]
+EXPLICIT_DOCS = {
+    "docs/HOSTING": ["README.md", "_template.md"],
+    "docs/DEVELOPER_SETUP": ["README.md"],
+}
+EXPLICIT_SUBDIRS = {
+    "docs/HOSTING": [],          # hosting-N.md files are enumerated dynamically
+    "docs/DEVELOPER_SETUP": ["developers"],  # dev-N.md files are enumerated dynamically
+}
+
+
+def enumerate_explicit(directory: str, subdir: str) -> list:
+    base = ROOT / directory
+    if subdir:
+        base = base / subdir
+    if not base.exists():
+        return []
+    return sorted(p.name for p in base.glob("*.md") if p.name not in ("README.md", "_template.md"))
+
+
+def main() -> int:
+    missing = [f for f in MANDATORY if not (ROOT / f).exists()]
+    missing_dirs = [d for d in MANDATORY_DIRS if not (ROOT / d).exists()]
+
+    problems = []
+    for directory, required in EXPLICIT_DOCS.items():
+        for name in required:
+            if not (ROOT / directory / name).exists():
+                problems.append(f"{directory}/{name}")
+
+    # Every hosting/developer must have its own explicit file (numbered *_N.md or dev-N.md)
+    for directory, subdirs in EXPLICIT_SUBDIRS.items():
+        subdirs_to_check = subdirs if subdirs else [""]
+        for subdir in subdirs_to_check:
+            entries = enumerate_explicit(directory, subdir)
+            if not entries:
+                problems.append(f"{directory}/{subdir}/<explicit file missing>" if subdir else f"{directory}/<hosting file missing>")
+
+    if missing or missing_dirs or problems:
+        print(json.dumps({
+            "missing_files": missing,
+            "missing_dirs": missing_dirs,
+            "explicit_docs_missing": problems,
+        }))
+        return 1
+    print(json.dumps({"ok": True, "docs_synced": True}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/nsr-compliance/assets/nsrcompliance/generate.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# generate.sh — stamp a .compliance/ deterministic harness into a repo, from this skill alone.
+#
+# The compliance skill is fully self-contained: it needs no rest of the NSR repo.
+# Everything it generates lives under .compliance/ at the target repo root.
+#
+# Usage:
+#   generate.sh [TARGET_REPO] [--force] [--dry-run]
+#     TARGET_REPO  default = repo root found upward from this skill (.agents/ ancestor)
+#     --force      overwrite existing generated files (idempotency check by default)
+#     --dry-run    show what would be written without writing
+#
+# Post-condition: the generated harness loads and the wiring/danger gates are present.
+set -e
+
+SKILL="$(cd "$(dirname "$0")" && pwd)"
+TARGET=""
+FORCE=0
+DRY=0
+
+usage() {
+  echo "Usage: generate.sh [TARGET_REPO] [--force] [--dry-run]"
+  exit 1
+}
+
+find_repo_root() {
+  local d; d="$SKILL"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.agents" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --force) FORCE=1; shift ;;
+    --dry-run) DRY=1; shift ;;
+    -h|--help) usage ;;
+    -*) echo "unknown option: $1"; usage ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+[ -n "$TARGET" ] || TARGET="$(find_repo_root)" || { echo "error: run from a repo (no .agents/ ancestor found)"; exit 1; }
+mkdir -p "$TARGET"
+TARGET="$(cd "$TARGET" && pwd)"
+
+put_file() {
+  local src="$1" dst="$2"
+  if [ "$src" -ef "$dst" ]; then
+    echo "[generate] SKIP (same file): ${dst#$TARGET/}"
+    return 0
+  fi
+  if [ -e "$dst" ] && [ "$FORCE" -eq 0 ]; then
+    [ "$DRY" -eq 0 ] && echo "[generate] SKIP (exists): ${dst#$TARGET/}"
+    return 0
+  fi
+  if [ "$DRY" -eq 1 ]; then
+    echo "[generate] would write: ${dst#$TARGET/}"
+  else
+    mkdir -p "$(dirname "$dst")"
+    cp "$src" "$dst"
+    echo "[generate] wrote: ${dst#$TARGET/}"
+  fi
+}
+
+copy_tree() {
+  local src="$1" dst="$2"
+  mkdir -p "$dst"
+  for item in "$src"/*; do
+    [ -e "$item" ] || continue
+    local base; base="$(basename "$item")"
+    if [ -d "$item" ]; then
+      copy_tree "$item" "$dst/$base"
+    else
+      put_file "$item" "$dst/$base"
+    fi
+  done
+}
+
+echo "[generate] self-contained compliance skill -> $TARGET"
+echo "[generate] phase 1: static .compliance/ tree from templates"
+copy_tree "$SKILL/templates/compliance" "$TARGET/.compliance"
+
+echo "[generate] phase 2: runtime files (runner, logger, config, gates, envelopes)"
+put_file "$SKILL/harness/runner.py"                 "$TARGET/.compliance/harness/runner.py"
+put_file "$SKILL/telemetry/logger.py"               "$TARGET/.compliance/telemetry/logger.py"
+put_file "$SKILL/telemetry/logger.py"               "$TARGET/.agents/skills/NSRcompliance/telemetry/logger.py"
+put_file "$SKILL/harness/runner.py"                 "$TARGET/.agents/skills/NSRcompliance/harness/runner.py"
+put_file "$SKILL/config/core_four.yaml"             "$TARGET/.compliance/config/core_four.yaml"
+put_file "$SKILL/gates/check_danger.sh"             "$TARGET/.compliance/gates/check_danger.sh"
+put_file "$SKILL/gates/check_wiring.sh"             "$TARGET/.compliance/gates/check_wiring.sh"
+put_file "$SKILL/harness/envelopes/task_envelope.json"  "$TARGET/.compliance/harness/envelopes/task_envelope.json"
+put_file "$SKILL/harness/envelopes/result_envelope.json" "$TARGET/.compliance/harness/envelopes/result_envelope.json"
+
+chmod -R u+x "$TARGET/.compliance" 2>/dev/null || true
+
+if [ "$DRY" -eq 1 ]; then
+  echo "[generate] dry-run complete (nothing written)"
+  exit 0
+fi
+
+echo "[generate] sanity: runner loads"
+python3 "$TARGET/.compliance/harness/runner.py" --help >/dev/null 2>&1 \
+  || { echo "[generate] FAIL: generated runner did not load"; exit 1; }
+
+echo "[generate] DONE: .compliance/ ready at $TARGET/.compliance"
+exit 0

package/.agents/skills/nsr-compliance/assets/nsrcompliance/harness/envelopes/result_envelope.json

@@ -0,0 +1,14 @@
+{
+  "envelope": "result",
+  "version": "1.0",
+  "description": "Run verdict envelope written by the harness into envelopes/. Success must be earned: status flips to success only when every gate and phase passed.",
+  "fields": {
+    "task_id": { "type": "string", "required": true },
+    "status": { "enum": ["success", "fail", "retry", "noop", "escalate"], "required": true },
+    "gates": { "type": "object", "required": true },
+    "evidence": { "type": "array", "items": { "type": "string" }, "required": false },
+    "artifacts": { "type": "array", "items": { "type": "string" }, "required": false },
+    "ts": { "type": "number", "required": true },
+    "error": { "type": "string", "required": false }
+  }
+}

package/.agents/skills/nsr-compliance/assets/nsrcompliance/harness/envelopes/task_envelope.json

@@ -0,0 +1,20 @@
+{
+  "envelope": "task",
+  "version": "2.0",
+  "description": "Structured task packet (murraycole): objective, non-goals, context, acceptance, capabilities, checks, terminal states, evidence, rollback.",
+  "fields": {
+    "task_id": { "type": "string", "required": true },
+    "feature": { "type": "string", "required": true },
+    "objective": { "type": "string", "required": true },
+    "non_goals": { "type": "array", "items": { "type": "string" }, "required": false },
+    "context": { "type": "string", "required": false },
+    "acceptance_criteria": { "type": "array", "items": { "type": "string" }, "required": true },
+    "checks": { "type": "array", "items": { "type": "string" }, "required": false },
+    "terminal_states": { "type": "array", "items": { "type": "string" }, "required": false },
+    "evidence": { "type": "array", "items": { "type": "string" }, "required": false },
+    "rollback": { "type": "string", "required": false },
+    "capabilities": { "type": "object", "required": false },
+    "artifacts": { "type": "array", "items": { "type": "string" }, "required": false },
+    "status": { "enum": ["success", "fail", "retry", "noop", "escalate"] }
+  }
+}