@delorenj/pjangler 1.3.0 → 1.3.7

package/templates/hermes-agent/template/.scripts/lifecycle.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Lifecycle helper — resolves the CANONICAL Krebs ticket lifecycle for this role.
+#
+# The state machine is NOT defined here. It lives in
+# krebs/spec/lifecycle.v1.yaml, which is the contract between ticket providers
+# and fleet orchestrators. This script is a reader: it answers "which tp band
+# does phase X map to" and "is this ticket stale" without any repo growing its
+# own private copy of the phase list. A second copy is how a PM ends up
+# transitioning against labels the board no longer uses.
+#
+# Provider LABELS are deliberately absent — those belong to the tp adapter's
+# normalized-state map (.scripts/providers/<provider>.sh). This layer speaks
+# only phases and the five tp bands.
+#
+# Usage:
+#   lifecycle.sh phases                 list every phase with band + staleness
+#   lifecycle.sh band <phase>           print the tp band for a phase
+#   lifecycle.sh staleness <phase>      print staleness minutes ("-" if none)
+#   lifecycle.sh is-terminal <phase>    exit 0 when the phase is terminal
+#   lifecycle.sh stale <phase> <iso8601>  exit 0 when that timestamp is stale
+#   lifecycle.sh spec                   print the resolved spec path
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolution order: explicit override, the 33GOD checkout, then a sibling walk
+# for hosts that keep the platform elsewhere.
+resolve_spec() {
+  if [ -n "${KREBS_LIFECYCLE_SPEC:-}" ] && [ -r "$KREBS_LIFECYCLE_SPEC" ]; then
+    printf '%s\n' "$KREBS_LIFECYCLE_SPEC"; return 0
+  fi
+  local candidates=(
+    "$HOME/code/33GOD/krebs/spec/lifecycle.v1.yaml"
+    "$SCRIPT_DIR/../../../../krebs/spec/lifecycle.v1.yaml"
+    "$SCRIPT_DIR/../../../../../krebs/spec/lifecycle.v1.yaml"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    [ -r "$c" ] && { printf '%s\n' "$c"; return 0; }
+  done
+  return 1
+}
+
+SPEC="$(resolve_spec || true)"
+
+need_spec() {
+  if [ -z "$SPEC" ]; then
+    echo "lifecycle: canonical spec not found (set KREBS_LIFECYCLE_SPEC)" >&2
+    echo "lifecycle: expected krebs/spec/lifecycle.v1.yaml in the 33GOD checkout" >&2
+    exit 2
+  fi
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "lifecycle: python3 required to read $SPEC" >&2
+    exit 2
+  fi
+}
+
+# One python entrypoint for every query keeps YAML parsing in exactly one place.
+query() {
+  need_spec
+  python3 - "$SPEC" "$@" <<'PY'
+import sys
+try:
+    import yaml
+except ImportError:
+    sys.exit("lifecycle: PyYAML required to read the lifecycle spec")
+
+spec_path, op = sys.argv[1], sys.argv[2]
+arg = sys.argv[3] if len(sys.argv) > 3 else None
+arg2 = sys.argv[4] if len(sys.argv) > 4 else None
+
+spec = yaml.safe_load(open(spec_path)) or {}
+states = {s["phase"]: s for s in (spec.get("states") or []) if s.get("phase")}
+if not states:
+    sys.exit(f"lifecycle: no states in {spec_path}")
+
+def need_phase(p):
+    if p not in states:
+        sys.exit(f"lifecycle: unknown phase {p!r}; known: {', '.join(states)}")
+    return states[p]
+
+if op == "phases":
+    print(f"{'phase':<14} {'tp_band':<12} {'terminal':<9} stale_after")
+    for name, s in states.items():
+        stale = s.get("staleness_minutes")
+        print(f"{name:<14} {str(s.get('tp_band')):<12} "
+              f"{str(bool(s.get('terminal'))).lower():<9} "
+              f"{(str(stale) + 'm') if stale else '-'}")
+elif op == "band":
+    print(need_phase(arg)["tp_band"])
+elif op == "staleness":
+    print(need_phase(arg).get("staleness_minutes") or "-")
+elif op == "is-terminal":
+    sys.exit(0 if need_phase(arg).get("terminal") else 1)
+elif op == "stale":
+    from datetime import datetime, timezone
+    mins = need_phase(arg).get("staleness_minutes")
+    if not mins:
+        sys.exit(1)  # phase has no staleness budget -> never stale
+    try:
+        ts = datetime.fromisoformat(arg2.replace("Z", "+00:00"))
+    except Exception:
+        sys.exit(f"lifecycle: unparseable timestamp {arg2!r} (want ISO 8601)")
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    age = (datetime.now(timezone.utc) - ts).total_seconds() / 60
+    sys.exit(0 if age > mins else 1)
+else:
+    sys.exit(f"lifecycle: unknown operation {op!r}")
+PY
+}
+
+case "${1:-phases}" in
+  phases)      query phases ;;
+  band)        query band "${2:?phase required}" ;;
+  staleness)   query staleness "${2:?phase required}" ;;
+  is-terminal) query is-terminal "${2:?phase required}" ;;
+  stale)       query stale "${2:?phase required}" "${3:?iso8601 timestamp required}" ;;
+  spec)        need_spec; printf '%s\n' "$SPEC" ;;
+  --help|-h|help)
+    sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' ;;
+  *)
+    echo "lifecycle: unknown operation ${1}" >&2
+    echo "try: phases | band <phase> | staleness <phase> | is-terminal <phase> | stale <phase> <ts> | spec" >&2
+    exit 2 ;;
+esac

package/templates/hermes-agent/template/.scripts/providers/plane.sh

@@ -99,7 +99,7 @@ API="$BASE/api/v1/workspaces/$WS"
 
 if [ -z "${PLANE_API_KEY:-}" ]; then
   KEY="$(workspace_key "$WS")"
-  eval "PLANE_API_KEY=\${$KEY:-}"
+  PLANE_API_KEY="$(printenv "$KEY" 2>/dev/null || true)"
   if [ -z "${PLANE_API_KEY:-}" ] && [ -f "$FLEET_ENV" ]; then
     PLANE_API_KEY="$(dotenv_value "$FLEET_ENV" "$KEY")"
   fi

package/templates/hermes-agent/template/SOUL.md.jinja

@@ -147,14 +147,50 @@ declared` event so the fleet knows what to route to you.
   via Cloudflare Tunnel), `localhost` for same-host, Docker network service
   names for container-to-container, Tailscale for private machine-to-machine.
 
-## Memory hygiene
-
-Your durable memory is the shared **Hindsight bank `{{ target_repo }}`** — one
-bank per PROJECT, shared with the human-drivable Momo twin. Honcho and the
-per-agent `runtime/memories/` store are **neutralized** (see `config.yaml`
-`memory.provider: ""`): do not rely on `MEMORY.md`/`USER.md`. Retain with
-`hindsight memory retain {{ target_repo }} "…" --context <cat>`; recall with
-`hindsight memory recall {{ target_repo }} "…"`.
+## Memory: two namespaces, two questions
+
+You have **two** memory stores. They do not compete — they answer opposite
+questions, and you are expected to use both and play them off each other.
+
+| | **Identity memory** | **Project memory** |
+| --- | --- | --- |
+| Bank | `agent-{{ agent_id }}` | `{{ target_repo }}` |
+| Anchored to | **who you are** | **which repo** |
+| Follows you across repos | yes | no |
+| Written by | the runtime, automatically | you, explicitly |
+| Read by | you alone | every agent on this repo |
+| Answers | "which projects have I worked on, and how do I work?" | "what is true about this repo, and which agent learned it?" |
+
+**Identity memory** is wired to the Hermes memory provider
+(`memory.bank_id_template: agent-{profile}`), so it accrues on its own from
+your turns. It is keyed to your profile name, **never** to a repo or working
+directory — change directories, change projects, it follows you. Treat it as
+self-referential: your capabilities, your recurring mistakes and the
+corrections that stuck, operator preferences you have learned, and the shape of
+the projects you have touched. Do not put repo facts here; they would be
+invisible to every other agent working that repo.
+
+**Project memory** is the shared, temporally-sequenced record of a repository,
+queried by many agents including the human-drivable Momo twin. Write it
+explicitly, and always carry provenance — name yourself in the content so a
+later reader can answer *which agent experienced this*:
+
+```bash
+hindsight memory retain {{ target_repo }} "{{ agent_id }}: <fact>" --context <cat>
+hindsight memory recall {{ target_repo }} "<question>"
+```
+
+**The synergy.** Before starting work in a repo you have not touched lately,
+recall from BOTH: project memory tells you the state of the code; identity
+memory tells you how *you* previously failed or succeeded here and what the
+operator asked you to do differently. When you learn something, route it by
+asking one question — *would another agent on this repo need this?* If yes it
+is project memory; if it is only true of you, it is identity memory. A fact
+about the operator's preferences is identity memory; a fact about the build is
+project memory.
+
+`MEMORY.md` / `USER.md` are live again and are fed by the provider — they are a
+projection of identity memory, not a separate store to hand-maintain.
 
 ## Doctrine
 

package/templates/hermes-agent/template/hermes.jinja

@@ -7,6 +7,17 @@ set -euo pipefail
 ROLE_DIR="$(cd "$(dirname "$0")" && pwd)"
 RUNTIME_HOME="$ROLE_DIR/runtime"
 
+FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
+FLEET_ENV_LIBRARY="$ROLE_DIR/.scripts/lib/fleet-env.sh"
+FLEET_ENV_PARSER="$ROLE_DIR/.scripts/lib/parse-fleet-env.py"
+if [[ ! -f "$FLEET_ENV_LIBRARY" || -L "$FLEET_ENV_LIBRARY" ]]; then
+  echo "hermes: trusted fleet environment loader unavailable" >&2
+  exit 1
+fi
+# shellcheck source=.scripts/lib/fleet-env.sh
+builtin source "$FLEET_ENV_LIBRARY"
+load_fleet_environment "$FLEET_ENV" "$FLEET_ENV_PARSER"
+
 FLEET_HOME="${HERMES_FLEET_HOME:-$HOME/.hermes}"
 PROFILE_NAME="${HERMES_PROFILE_NAME:-{{ agent_id }}}"
 
@@ -16,19 +27,20 @@ PROFILE_NAME="${HERMES_PROFILE_NAME:-{{ agent_id }}}"
 # of a "profiles" dir makes get_active_profile_name() report "default" and
 # _global_auth_file_path() return None — silently disabling shared fleet auth
 # and giving the agent a divergent config.yaml. The profile dir is a REAL dir
-# whose shared entries (config.yaml, .env, skills) symlink to the fleet root
-# and whose owned entries (memories, sessions, state.db, ...) symlink into
-# $RUNTIME_HOME. Provision it with: pj migrate hermes.runtime-singleton
+# whose shared entries (.env, skills) symlink to the fleet root and whose owned
+# entries (memories, sessions, state.db, ...) symlink into $RUNTIME_HOME.
+#
+# config.yaml is NOT symlinked — it is GENERATED as
+# deep_merge(fleet config.yaml, <profile>/config.delta.yaml). Symlinking it
+# detached the profile on the first in-agent write (Hermes' atomic write does
+# os.replace, which swaps the symlink for a regular file) and left no way to
+# override anything. Edit config.delta.yaml, then render.
+# Provision it with: pj migrate hermes.runtime-singleton
 HERMES_HOME="$FLEET_HOME/profiles/$PROFILE_NAME"
 if ! REPO_ROOT="$(git -C "$ROLE_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
   REPO_ROOT="$ROLE_DIR"
 fi
 
-FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
-if [[ -f "$FLEET_ENV" ]]; then
-  # shellcheck disable=SC1090
-  source "$FLEET_ENV"
-fi
 # Never pass an identity-bearing chat credential from shared fleet state into
 # a profile process. Hermes loads the profile's own runtime/.env itself.
 unset TELEGRAM_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN

package/templates/hermes-agent/template/momo.jinja

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Momo provider dispatcher for {{ target_repo }} ({{ role }}).
+#
+# The stable, per-repo entrypoint Momo (and `pj audit --profile
+# momo-lifecycle-plane`) uses to reach this project's ticket board. It is a thin
+# seam ON PURPOSE: all real provider logic already lives in
+# .scripts/lib/ticket-provider.sh, which dispatches to
+# .scripts/providers/<provider>.sh based on repo-root .project.json. This file
+# adds no second implementation of that — duplicating it is how a repo ends up
+# with two disagreeing notions of "what board am I bound to".
+#
+# What this adds over calling `tp` directly:
+#   * one discoverable path per role (agents/hermes/<role>/momo) instead of
+#     "source the right lib from the right cwd"
+#   * --help / --smoke, so readiness is checkable without credentials
+#   * the canonical Krebs phase -> tp-band map, so callers reason in lifecycle
+#     phases rather than hardcoding provider labels
+#
+# Operations are forwarded verbatim to `tp`. See the contract at the top of
+# .scripts/lib/ticket-provider.sh: resolve, active_milestone, list_issues,
+# get_issue, comment, transition, create_board, create_issue.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB="$SCRIPT_DIR/.scripts/lib/ticket-provider.sh"
+
+# Canonical lifecycle spec. Phases are Krebs' vocabulary; tp bands are the five
+# normalized states every provider adapter must map. Kept in sync with
+# krebs/spec/lifecycle.v1.yaml — that file is the source of truth.
+LIFECYCLE_SPEC="${KREBS_LIFECYCLE_SPEC:-$HOME/code/33GOD/krebs/spec/lifecycle.v1.yaml}"
+
+usage() {
+  cat <<'MOMO_HELP'
+momo — ticket-board dispatcher for this repo's Hermes role
+
+USAGE
+  momo <operation> [args...]     forward an operation to the bound ticket provider
+  momo --help                    show this help
+  momo --smoke [root|nested]     verify wiring without credentials
+  momo --lifecycle               print the canonical phase -> tp-band map
+  momo --provider                print the resolved provider name
+
+OPERATIONS (implemented by .scripts/providers/<provider>.sh)
+  resolve                        -> {provider, board_id, board_url}
+  active_milestone               -> {id, name, state}
+  list_issues                    -> [ {id,key,title,state,state_type,...} ]
+  get_issue <id>                 -> {id,key,title,description,acceptance,...}
+  comment <id> <body>            -> comment id
+  transition <id> <state>        -> backlog|unstarted|started|in_review|completed|cancelled
+  create_board <name> <id> <d>   -> {board_id, board_url}
+  create_issue [--if-absent] <title> [desc]
+
+The provider and board binding come from repo-root .project.json
+(ticket_provider.*). Credentials come from the environment; see the header of
+the matching .scripts/providers/<provider>.sh.
+MOMO_HELP
+}
+
+# Phase -> tp band, read from the canonical spec when present so this never
+# becomes a stale second copy. The inline fallback exists only so --lifecycle
+# still answers on a host without the 33GOD checkout.
+print_lifecycle() {
+  if [ -r "$LIFECYCLE_SPEC" ] && command -v python3 >/dev/null 2>&1; then
+    python3 - "$LIFECYCLE_SPEC" <<'PY' && return 0
+import sys
+try:
+    import yaml
+except ImportError:
+    sys.exit(1)
+try:
+    spec = yaml.safe_load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+states = spec.get("states") or []
+if not states:
+    sys.exit(1)
+print(f"{'phase':<14} {'tp_band':<12} {'terminal':<9} stale_after")
+for s in states:
+    stale = s.get("staleness_minutes")
+    print(f"{str(s.get('phase')):<14} {str(s.get('tp_band')):<12} "
+          f"{str(bool(s.get('terminal'))).lower():<9} "
+          f"{(str(stale) + 'm') if stale else '-'}")
+PY
+  fi
+  # Fallback: spec unreadable or PyYAML absent.
+  cat <<'FALLBACK'
+phase          tp_band      terminal  stale_after
+backlog        backlog      false     -
+triage         unstarted    false     10m
+refining       unstarted    false     30m
+ready          unstarted    false     -
+in_progress    started      false     120m
+review         in_review    false     15m
+qa             in_review    false     -
+FALLBACK
+  echo "(fallback map: could not read $LIFECYCLE_SPEC)" >&2
+}
+
+require_lib() {
+  if [ ! -r "$LIB" ]; then
+    echo "momo: ticket-provider lib missing: $LIB" >&2
+    echo "momo: run the role's provisioning scripts, or pj migrate hermes.pm-scaffold" >&2
+    return 2
+  fi
+}
+
+# Credential-free wiring check. Verifies the pieces a board call needs are
+# present and resolvable; it deliberately does NOT hit the network, so it is
+# safe in CI and in `pj audit`.
+smoke() {
+  local scope="${1:-root}" rc=0
+  require_lib || return 2
+  # shellcheck source=/dev/null
+  . "$LIB"
+
+  local provider=""
+  provider="$(tp_provider_name 2>/dev/null || true)"
+  if [ -z "$provider" ]; then
+    echo "smoke: no ticket provider resolved (.project.json ticket_provider.type)" >&2
+    rc=1
+  else
+    echo "smoke: provider = $provider"
+  fi
+
+  local impl
+  impl="$(tp_providers_dir 2>/dev/null || true)/${provider}.sh"
+  if [ -n "$provider" ] && [ ! -f "$impl" ]; then
+    echo "smoke: provider adapter missing: $impl" >&2
+    rc=1
+  elif [ -n "$provider" ]; then
+    echo "smoke: adapter   = $impl"
+  fi
+
+  if [ -r "$SCRIPT_DIR/../../../.project.json" ]; then
+    echo "smoke: binding   = repo-root .project.json"
+  else
+    echo "smoke: .project.json not found from $SCRIPT_DIR" >&2
+    rc=1
+  fi
+
+  if [ "$scope" = "nested" ]; then
+    # Nested scope additionally asserts the normalized state vocabulary is
+    # intact, since that is what a nested adapter call would transition against.
+    local missing=""
+    for st in backlog unstarted started in_review completed cancelled; do
+      tp_is_valid_state "$st" || missing="$missing $st"
+    done
+    if [ -n "$missing" ]; then
+      echo "smoke: normalized states missing:$missing" >&2
+      rc=1
+    else
+      echo "smoke: states    = ok (6 normalized)"
+    fi
+  fi
+
+  [ "$rc" -eq 0 ] && echo "smoke: ok ($scope)"
+  return "$rc"
+}
+
+main() {
+  case "${1:---help}" in
+    --help|-h|help) usage ;;
+    --lifecycle)    print_lifecycle ;;
+    --smoke)        shift; smoke "${1:-root}" ;;
+    --provider)
+      require_lib || exit 2
+      # shellcheck source=/dev/null
+      . "$LIB"; tp_provider_name ;;
+    *)
+      require_lib || exit 2
+      # shellcheck source=/dev/null
+      . "$LIB"
+      tp "$@" ;;
+  esac
+}
+
+main "$@"

package/templates/hermes-agent/template/role.yaml.jinja

@@ -2,32 +2,32 @@
 # The agent's actual state (memory, sessions, evolving SOUL) lives in the
 # ignored local runtime. This file is the immutable contract for this role.
 
-repo: {{ target_repo }}
-role: {{ role }}
-agent_id: {{ agent_id }}
-display_name: "{{ display_name }}"
-purpose: "{{ agent_purpose }}"
+repo: {{ target_repo | tojson }}
+role: {{ role | tojson }}
+agent_id: {{ agent_id | tojson }}
+display_name: {{ display_name | tojson }}
+purpose: {{ agent_purpose | tojson }}
 
 # Process-local gateway inference target (empty = inherit from shared
 # ~/.hermes/config.yaml). key_env is a variable NAME only; its secret value is
 # injected at runtime and must never be written here.
 model:
-  provider: "{{ model_provider }}"
-  name: "{{ model_name }}"
-  base_url: "{{ model_base_url }}"
-  api_mode: "{{ model_api_mode }}"
-  key_env: "{{ model_key_env }}"
+  provider: {{ model_provider | tojson }}
+  name: {{ model_name | tojson }}
+  base_url: {{ model_base_url | tojson }}
+  api_mode: {{ model_api_mode | tojson }}
+  key_env: {{ model_key_env | tojson }}
 
 # Hermes profile name. ~/.hermes/profiles/<name> is a REAL directory managed by
 # `pj migrate hermes.runtime-singleton`: shared config/auth/skills link to the
 # fleet root while role-owned state links into ./runtime. Never replace the
 # named profile with a symlink to runtime.
-profile: {{ agent_id }}
+profile: {{ agent_id | tojson }}
 
 # Telegram bot identity (one bot per agent — see docs/architecture.md).
 telegram:
   provisioning_status: "deferred"
-  bot_username: "{{ bot_handle }}"
+  bot_username: {{ bot_handle | tojson }}
   bot_id: ""
 
 # Slack is opt-in. Credentials live only in runtime/.env; this block records
@@ -44,14 +44,14 @@ slack:
 # The heartbeat reconciliation pass talks ONLY to this via .scripts/lib/ticket-provider.sh;
 # swapping providers is a one-line change here. Filled in by 42-ticket-provider.sh.
 ticket_provider:
-  name: {{ ticket_provider }}
+  name: {{ ticket_provider | tojson }}
   board_id: ""
   board_url: ""
 {%- if ticket_provider == 'linear' %}
   team: ""        # Linear team key, e.g. DEL  (set before first sentinel run)
   project: ""     # optional Linear project name to scope milestones/issues
 {%- elif ticket_provider == 'plane' %}
-  workspace: "{{ plane_workspace }}"
+  workspace: {{ plane_workspace | tojson }}
   project: ""     # Plane project uuid (set by 42-ticket-provider.sh)
 {%- elif ticket_provider == 'trello' %}
   board: ""       # Trello board id (set by 42-ticket-provider.sh)
@@ -70,7 +70,7 @@ reconcile:
 # Plane project (1:1 with this agent) — retained for fleet-registry back-compat.
 plane:
   # Empty -> resolved from ~/.config/hermes-agent-template/config.toml [plane].workspace
-  workspace: "{{ plane_workspace }}"
+  workspace: {{ plane_workspace | tojson }}
   # identifier is set by .scripts/42-ticket-provider.sh after creation (plane only)
   identifier: ""
 
@@ -81,16 +81,16 @@ bloodbank:
   # Quarantine gate: discovery is safe; execution requires explicit activation.
   enabled: false
   gateway_scope: fleet
-  target_agent_id: "{{ agent_id }}"
-  producer: "hermes-agent:{{ agent_id }}"
+  target_agent_id: {{ agent_id | tojson }}
+  producer: {{ ("hermes-agent:" ~ agent_id) | tojson }}
 
 # Pure-local role-owned state. HERMES_HOME itself is the named profile directory
 # above; the legacy GitHub identity remains metadata-only for locating old
 # archives, and provisioning never creates or attaches a submodule.
 runtime:
   # Empty owner -> resolved from config.toml [github].runtime_repo_owner.
-  github_owner: "{{ runtime_repo_owner }}"
-  github_repo: "{{ runtime_repo }}"
+  github_owner: {{ runtime_repo_owner | tojson }}
+  github_repo: {{ runtime_repo | tojson }}
   local_path: "./runtime"
   checkpoint:
     cadence: "disabled"