@jeger-ai/opengantry 1.0.0

package/templates/scripts/gxt-manifest-lib.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Node-only MANIFEST helpers for validate-gxt.sh (no jq dependency).
+ * Usage:
+ *   node scripts/gxt-manifest-lib.mjs prefixes [repoRoot]
+ *   node scripts/gxt-manifest-lib.mjs validate-manifest [repoRoot]
+ *   node scripts/gxt-manifest-lib.mjs validate-bypass-note  (JSON on stdin)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const FIXED_MSN_PREFIXES = [
+  ".gitagent/",
+  "WORKER_LOG.md",
+  ".githooks/",
+  ".github/workflows/gxt-validate.yml",
+];
+
+export function repoRootFromArg(arg) {
+  if (arg?.trim()) return path.resolve(arg.trim());
+  return process.cwd();
+}
+
+export function readManifest(repoRoot) {
+  const rel = ".gitagent/foreman/MANIFEST.json";
+  const abs = path.join(repoRoot, rel);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`validate-gxt: missing ${rel}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch (e) {
+    throw new Error(`validate-gxt: invalid JSON in ${rel}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parsed;
+}
+
+export function listMsnEnforcedPrefixes(repoRoot) {
+  const manifest = readManifest(repoRoot);
+  const skills = manifest.skills;
+  if (!skills || typeof skills !== "object" || Array.isArray(skills)) {
+    throw new Error("validate-gxt: MANIFEST skills must be a non-empty object");
+  }
+  const roots = Object.values(skills).flatMap((s) => {
+    if (!s || typeof s !== "object") return [];
+    return Array.isArray(s.tmvc_roots) ? s.tmvc_roots : [];
+  });
+  const out = new Set();
+  for (const p of [...FIXED_MSN_PREFIXES, ...roots]) {
+    if (typeof p !== "string" || !p.trim()) continue;
+    out.add(p.replace(/\\/g, "/"));
+  }
+  return [...out];
+}
+
+export function validateManifestStructure(repoRoot) {
+  const m = readManifest(repoRoot);
+  if (typeof m.schema_version !== "string" || m.schema_version.length === 0) {
+    throw new Error("validate-gxt: schema_version must be a non-empty string");
+  }
+  const skills = m.skills;
+  if (!skills || typeof skills !== "object" || Array.isArray(skills) || Object.keys(skills).length === 0) {
+    throw new Error("validate-gxt: skills must be a non-empty object");
+  }
+  if (!m.path_risks || typeof m.path_risks !== "object" || Array.isArray(m.path_risks)) {
+    throw new Error("validate-gxt: path_risks must be an object");
+  }
+  if (!Array.isArray(m.risk_keywords)) {
+    throw new Error("validate-gxt: risk_keywords must be an array");
+  }
+  for (const [key, skill] of Object.entries(skills)) {
+    if (!skill || typeof skill !== "object") {
+      throw new Error(`validate-gxt: skills.${key} must be an object`);
+    }
+    for (const field of ["trust_threshold", "tmvc_roots", "forbidden_zones"]) {
+      if (!(field in skill)) {
+        throw new Error(`validate-gxt: skills.${key} missing ${field}`);
+      }
+    }
+    if (!Array.isArray(skill.tmvc_roots)) {
+      throw new Error(`validate-gxt: skills.${key}.tmvc_roots must be an array`);
+    }
+    if (!Array.isArray(skill.forbidden_zones)) {
+      throw new Error(`validate-gxt: skills.${key}.forbidden_zones must be an array`);
+    }
+  }
+}
+
+export function validateBypassNoteJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  return (
+    parsed?.v === 1 &&
+    typeof parsed.reason === "string" &&
+    parsed.reason.length >= 10
+  );
+}
+
+function main() {
+  const cmd = process.argv[2];
+  const repoRoot = repoRootFromArg(process.argv[3]);
+
+  try {
+    switch (cmd) {
+      case "prefixes": {
+        for (const p of listMsnEnforcedPrefixes(repoRoot)) {
+          console.log(p);
+        }
+        break;
+      }
+      case "validate-manifest": {
+        validateManifestStructure(repoRoot);
+        console.log("MANIFEST OK");
+        break;
+      }
+      case "validate-bypass-note": {
+        const stdin = fs.readFileSync(0, "utf8");
+        process.exit(validateBypassNoteJson(stdin) ? 0 : 1);
+      }
+      default:
+        console.error(
+          "Usage: gxt-manifest-lib.mjs <prefixes|validate-manifest|validate-bypass-note> [repoRoot]",
+        );
+        process.exit(2);
+    }
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+}
+
+if (process.argv[1]?.includes("gxt-manifest-lib.mjs")) {
+  main();
+}

package/templates/scripts/gxt-pin-mission.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Pin the active GXT mission for gxt-runtime-env.sh and Cursor sessionStart hooks.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$ROOT" ]; then
+  echo "gxt-pin-mission: not inside a git repository" >&2
+  exit 1
+fi
+cd "$ROOT"
+
+if [ $# -lt 1 ]; then
+  cat >&2 <<'EOF'
+usage: scripts/gxt-pin-mission.sh .gitagent/missions/<file>.yaml
+
+Writes .gitagent/missions/.active-mission (gitignored) for:
+  - scripts/gxt-runtime-env.sh (no arg)
+  - .cursor/hooks/gxt-session-start.sh (new Agent sessions)
+EOF
+  exit 1
+fi
+
+MISSION="$1"
+if [ ! -f "$MISSION" ]; then
+  echo "gxt-pin-mission: mission file not found: $MISSION" >&2
+  exit 1
+fi
+
+mkdir -p .gitagent/missions
+printf '%s\n' "$MISSION" > .gitagent/missions/.active-mission
+printf 'Pinned active mission: %s\n' "$MISSION"

package/templates/scripts/gxt-resolve-mission.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Resolve active GXT mission path (repo-relative). Prints path on stdout; exit 1 if unset.
+set -euo pipefail
+
+ROOT="${GXT_RESOLVE_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || true)}"
+if [ -z "$ROOT" ]; then
+  exit 1
+fi
+cd "$ROOT"
+
+explicit="${1:-}"
+if [ -n "$explicit" ]; then
+  printf '%s\n' "$explicit"
+  exit 0
+fi
+
+if [ -n "${GAPMAN_MISSION:-}" ]; then
+  printf '%s\n' "$GAPMAN_MISSION"
+  exit 0
+fi
+
+if [ -n "${GXT_MISSION_FILE:-}" ]; then
+  printf '%s\n' "$GXT_MISSION_FILE"
+  exit 0
+fi
+
+if [ -f ".gitagent/missions/.active-mission" ]; then
+  line=""
+  IFS= read -r line < ".gitagent/missions/.active-mission" || true
+  line="$(printf '%s' "$line" | tr -d '[:space:]')"
+  if [ -n "$line" ]; then
+    printf '%s\n' "$line"
+    exit 0
+  fi
+fi
+
+if [ -f ".gitagent/missions/ACTIVE_MISSION.md" ]; then
+  printf '%s\n' ".gitagent/missions/ACTIVE_MISSION.md"
+  exit 0
+fi
+
+if [ -f ".gitagent/missions/ACTIVE_MISSION.yaml" ]; then
+  printf '%s\n' ".gitagent/missions/ACTIVE_MISSION.yaml"
+  exit 0
+fi
+
+exit 1

package/templates/scripts/gxt-runtime-env.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Load GXT Worker Runtime Contract into the current shell (any IDE terminal / manual runs).
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$ROOT" ]; then
+  echo "gxt-runtime-env: not inside a git repository" >&2
+  exit 1
+fi
+cd "$ROOT"
+
+MISSION=""
+if ! MISSION="$(scripts/gxt-resolve-mission.sh "${1:-}" 2>/dev/null)"; then
+  cat >&2 <<'EOF'
+gxt-runtime-env: no mission file resolved.
+  scripts/gxt-pin-mission.sh .gitagent/missions/<file>.yaml
+  source scripts/gxt-runtime-env.sh .gitagent/missions/<file>.yaml
+  export GAPMAN_MISSION=.gitagent/missions/<file>.yaml
+EOF
+  exit 1
+fi
+
+if command -v gapman >/dev/null 2>&1; then
+  eval "$(gapman runtime env --mission "$MISSION")"
+elif [ -f "dist/cli/index.js" ]; then
+  eval "$(node dist/cli/index.js runtime env --mission "$MISSION")"
+else
+  echo "gxt-runtime-env: gapman not found (npm ci && npm run build)" >&2
+  exit 1
+fi
+
+printf 'GXT runtime loaded: mission=%s skill=%s\n' "$GXT_MISSION_FILE" "${GXT_SKILL_KEY:-unknown}"

package/templates/scripts/validate-gxt.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# OpenGantry local + CI validation. Keep path-prefix rules in sync with
+# .github/workflows/gxt-validate.yml (msn_commits job).
+# MSN-enforced paths: fixed substrate + MANIFEST tmvc_roots (Node; no jq).
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "validate-gxt: not inside a git repository" >&2
+  exit 1
+}
+cd "$ROOT"
+
+MANIFEST_REL=".gitagent/foreman/MANIFEST.json"
+BYPASS_SHA256_REL=".gitagent/foreman/BYPASS.sha256"
+GXT_BYPASS_NOTES_REF="refs/notes/gxt-bypass"
+GXT_MANIFEST_LIB="scripts/gxt-manifest-lib.mjs"
+
+# Cached MSN-enforced path prefixes (fixed substrate + MANIFEST tmvc_roots).
+MSN_PREFIXES=()
+
+load_msn_prefixes() {
+  if [[ ${#MSN_PREFIXES[@]} -gt 0 ]]; then
+    return 0
+  fi
+  if [[ ! -f "$GXT_MANIFEST_LIB" ]]; then
+    echo "validate-gxt: missing $GXT_MANIFEST_LIB" >&2
+    exit 1
+  fi
+  mapfile -t MSN_PREFIXES < <(node "$GXT_MANIFEST_LIB" prefixes "$ROOT") || {
+    echo "validate-gxt: failed to load MSN-enforced prefixes from MANIFEST (Node required)" >&2
+    exit 1
+  }
+  if [[ ${#MSN_PREFIXES[@]} -eq 0 ]]; then
+    echo "validate-gxt: no MSN-enforced prefixes" >&2
+    exit 1
+  fi
+}
+
+# Returns 0 if commit has a valid gxt-bypass git note (JSON v1 + reason >= 10 chars).
+commit_has_gxt_bypass_note() {
+  local commit="$1"
+  local note
+  note="$(git notes --ref="$GXT_BYPASS_NOTES_REF" show "$commit" 2>/dev/null)" || return 1
+  printf '%s' "$note" | node "$GXT_MANIFEST_LIB" validate-bypass-note >/dev/null 2>&1
+}
+
+# Returns 0 when GXT_BYPASS_SECRET matches BYPASS.sha256 anchor (never commit the secret).
+is_bypass_secret_authorized() {
+  local anchor secret secret_hash
+  [[ -n "${GXT_BYPASS_SECRET:-}" ]] || return 1
+  [[ -f "$BYPASS_SHA256_REL" ]] || return 1
+  anchor="$(grep -E '^[a-fA-F0-9]{64}$' "$BYPASS_SHA256_REL" | head -1 | tr '[:upper:]' '[:lower:]')"
+  [[ -n "$anchor" ]] || return 1
+  secret_hash="$(printf '%s' "$GXT_BYPASS_SECRET" | sha256sum | awk '{print $1}' | tr '[:upper:]' '[:lower:]')"
+  [[ "$anchor" == "$secret_hash" ]]
+}
+
+# Returns 0 if this path should trigger [MSN-XXXX] subject enforcement.
+is_msn_enforced_path() {
+  local p="$1"
+  local prefix
+  load_msn_prefixes
+  for prefix in "${MSN_PREFIXES[@]}"; do
+    [[ -z "$prefix" ]] && continue
+    if [[ "$p" == "$prefix" ]]; then
+      return 0
+    fi
+    if [[ "$prefix" == */ ]] && [[ "$p" == "$prefix"* ]]; then
+      return 0
+    fi
+    if [[ "$prefix" != */ ]] && [[ "$p" == "$prefix"/* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+cmd_upgrade_tmp() {
+  local tracked
+  tracked="$(git ls-files '.gitagent/.upgrade-tmp' 2>/dev/null || true)"
+  if [[ -n "$tracked" ]]; then
+    echo "upgrade-tmp check FAILED: tracked files under .gitagent/.upgrade-tmp/ (must be gitignored staging only)" >&2
+    printf '%s\n' "$tracked" >&2
+    exit 1
+  fi
+  echo "upgrade-tmp OK (no tracked staging files)"
+}
+
+cmd_manifest() {
+  node "$GXT_MANIFEST_LIB" validate-manifest "$ROOT"
+}
+
+cmd_msn() {
+  local base_ref="$1"
+  local head_ref="$2"
+  local base_sha head_sha commit subject f touched
+
+  base_sha="$(git rev-parse --verify "${base_ref}^{commit}")"
+  head_sha="$(git rev-parse --verify "${head_ref}^{commit}")"
+
+  while IFS= read -r commit; do
+    [[ -n "$commit" ]] || continue
+    touched=0
+    while IFS= read -r f; do
+      [[ -n "$f" ]] || continue
+      if is_msn_enforced_path "$f"; then
+        touched=1
+        break
+      fi
+    done < <(git diff-tree --no-commit-id --name-only -r "$commit" 2>/dev/null || true)
+
+    if [[ "$touched" -eq 0 ]]; then
+      continue
+    fi
+
+    subject="$(git log -1 --format=%s "$commit")"
+    if [[ "$subject" =~ ^\[MSN-[0-9]{4}\] ]]; then
+      continue
+    fi
+    if commit_has_gxt_bypass_note "$commit"; then
+      continue
+    fi
+    echo "MSN check FAILED: commit $commit touches MSN-enforced paths but subject does not start with [MSN-NNNN] and has no gxt-bypass git note" >&2
+    echo "  subject: $subject" >&2
+    echo "  hint: run gapman verify --break-glass --reason \"...\" with GXT_BYPASS_SECRET, push refs/notes/gxt-bypass" >&2
+    echo "  touched paths (sample):" >&2
+    git diff-tree --no-commit-id --name-only -r "$commit" | head -20 >&2
+    exit 1
+  done < <(git rev-list --no-merges "${base_sha}..${head_sha}")
+
+  echo "MSN commit subjects OK (path-scoped: substrate + MANIFEST tmvc_roots)"
+}
+
+usage() {
+  cat <<'EOF' >&2
+Usage:
+  validate-gxt.sh [manifest]          Validate Foreman MANIFEST.json (default)
+  validate-gxt.sh msn <base> <head>   Require [MSN-NNNN] or gxt-bypass git note on commits
+                                      in range that touch MSN-enforced paths
+  validate-gxt.sh upgrade-tmp         Fail if .gitagent/.upgrade-tmp/ contains tracked files
+  validate-gxt.sh all [base head]     Run manifest, upgrade-tmp, then msn if base and head given
+Example:
+  ./scripts/validate-gxt.sh msn origin/main HEAD
+EOF
+}
+
+main() {
+  local cmd="${1:-manifest}"
+  shift || true
+  case "$cmd" in
+    manifest)
+      cmd_manifest
+      ;;
+    upgrade-tmp)
+      cmd_upgrade_tmp
+      ;;
+    msn)
+      if [[ $# -ne 2 ]]; then
+        usage
+        exit 2
+      fi
+      cmd_msn "$1" "$2"
+      ;;
+    all)
+      cmd_manifest
+      cmd_upgrade_tmp
+      if [[ $# -ge 2 ]]; then
+        cmd_msn "$1" "$2"
+      else
+        echo "Hint: pass <base> <head> to also run MSN checks, e.g. all origin/main HEAD" >&2
+      fi
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"

package/templates/skills/gapman.md

@@ -0,0 +1,5 @@
+# Skill: gapman
+
+Manifest key `gapman`. **gapman** CLI and tests under `src/cli/` per [`.gitagent/foreman/MANIFEST.json`](../.gitagent/foreman/MANIFEST.json).
+
+Substrate paths (`.gitagent/`, hooks, workflows) require Teacher legislation and **`substrate`** or explicit mission scope — do not edit Foreman law without a mission.

package/templates/skills/logic.md

@@ -0,0 +1,3 @@
+# Skill: logic
+
+Manifest key `logic`. Application logic and utilities within declared `tmvc_roots` in [`.gitagent/foreman/MANIFEST.json`](../.gitagent/foreman/MANIFEST.json).

package/templates/skills/substrate.md

@@ -0,0 +1,3 @@
+# Skill: substrate
+
+Manifest key `substrate`. Reserved for high-risk substrate work; requires Teacher mission per manifest.

package/templates/skills/ui.md

@@ -0,0 +1,3 @@
+# Skill: ui
+
+Manifest key `ui`. UI components and styles within declared `tmvc_roots` in [`.gitagent/foreman/MANIFEST.json`](../.gitagent/foreman/MANIFEST.json).