@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/nsr-compliance/assets/nsrcompliance/templates/compliance/installer/install.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# deterministic harness installer: stamp .compliance/ + the compliance skill into a target repo.
+#
+# Usage:
+#   install.sh [TARGET] [--source DIR] [--force] [--dry-run]
+#
+# - TARGET defaults to the current directory.
+# - SOURCE defaults to the compliance templates inside the NSR skill found upward from this
+#   script (any directory containing assets/compliance + assets/agents_skills).
+# - Never overwrites existing files unless --force.
+# - Post-condition: the installed harness is sanity-checked (runner loads, gates skipped
+#   existing). Single repeatable command; re-run doubles as a drift check.
+set -e
+
+TARGET="${1:-.}"
+SOURCE=""
+FORCE=0
+DRY=0
+
+usage() {
+  echo "Usage: install.sh [TARGET] [--source DIR] [--force] [--dry-run]"
+  exit 1
+}
+
+find_repo_root() {
+  local d; d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/.compliance" ]; then echo "$d"; return 0; fi
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+find_source() {
+  local d repo
+  # 1. an ancestor that is itself a skill (assets/compliance + assets/agents_skills)
+  d="$(cd "$(dirname "$0")" && pwd)"
+  while [ "$d" != "/" ]; do
+    if [ -d "$d/assets/compliance" ] && [ -d "$d/assets/agents_skills" ]; then
+      echo "$d"; return 0
+    fi
+    d="$(dirname "$d")"
+  done
+  # 2. a skill dir inside the repo under .agents/skills/
+  repo="$(find_repo_root)" || return 1
+  for d in "$repo"/.agents/skills/*/; do
+    [ -d "$d" ] || continue
+    if [ -d "$d/assets/compliance" ] && [ -d "$d/assets/agents_skills" ]; then
+      echo "$d"; return 0
+    fi
+  done
+  return 1
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --source) SOURCE="$2"; shift 2 ;;
+    --force) FORCE=1; shift ;;
+    --dry-run) DRY=1; shift ;;
+    -h|--help) usage ;;
+    -*) echo "unknown option: $1"; usage ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+if [ -z "$SOURCE" ]; then
+  SKILL_ROOT="$(find_source)" \
+    || { echo "error: cannot auto-discover source; pass --source DIR with assets/compliance + assets/agents_skills"; exit 1; }
+  SOURCE="$SKILL_ROOT/assets"
+fi
+
+[ -d "$SOURCE/compliance" ] || { echo "error: $SOURCE/compliance not found"; exit 1; }
+[ -d "$SOURCE/agents_skills/NSRcompliance" ] || { echo "error: $SOURCE/agents_skills/NSRcompliance not found"; exit 1; }
+
+mkdir -p "$TARGET"
+TARGET="$(cd "$TARGET" && pwd)"
+
+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
+      if [ -e "$dst/$base" ] && [ "$FORCE" -eq 0 ]; then
+        echo "[installer] SKIP (exists): ${dst#$TARGET/}/$base"
+        continue
+      fi
+      if [ "$DRY" -eq 1 ]; then
+        echo "[installer] would write: ${dst#$TARGET/}/$base"
+      else
+        cp "$item" "$dst/$base"
+        echo "[installer] wrote: ${dst#$TARGET/}/$base"
+      fi
+    fi
+  done
+}
+
+echo "[installer] installing harness -> $TARGET"
+copy_tree "$SOURCE/compliance" "$TARGET/.compliance"
+copy_tree "$SOURCE/agents_skills/NSRcompliance" "$TARGET/.agents/skills/NSRcompliance"
+chmod -R u+x "$TARGET/.compliance" "$TARGET/.agents/skills/NSRcompliance" 2>/dev/null || true
+
+if [ "$DRY" -eq 1 ]; then
+  echo "[installer] dry-run complete (nothing written)"
+  exit 0
+fi
+
+if [ ! -f "$TARGET/.compliance/harness/runner.py" ]; then
+  echo "[installer] FAIL: runner.py missing after install"
+  exit 1
+fi
+if [ ! -f "$TARGET/.compliance/harness/envelopes/task_envelope.json" ]; then
+  echo "[installer] FAIL: task envelope schema missing after install"
+  exit 1
+fi
+
+echo "[installer] sanity: runner loads"
+python3 "$TARGET/.compliance/harness/runner.py" --help >/dev/null 2>&1 \
+  || { echo "[installer] FAIL: runner.py did not load"; exit 1; }
+
+echo "[installer] DONE: harness at $TARGET/.compliance + compliance skill at $TARGET/.agents/skills/NSRcompliance"
+exit 0

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

@@ -0,0 +1,11 @@
+# telemetry/ — __PROJECT__
+
+Observability & cost tracking.
+
+## Files
+- `logger.py` — SQLite logger: writes `runs`/`events` to `runs.db`.
+- `runs.db` — generated local store (git-ignored).
+
+## Rules
+- Every run logs tokens, latency, tool calls, cost.
+- One data path: agents write to SQLite; readers poll SQLite (`logger.py query`).

package/.agents/skills/pr-ops/README.md

@@ -0,0 +1,3 @@
+# pr-ops — pull requests — create, update, check status, request merge
+
+See `SKILL.md` for the full skill.

package/.agents/skills/pr-ops/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: pr-ops
+description: "Create and manage pull requests to the zerwiz/ymir main repo. Use when an agent needs to open a PR, update a PR description, or check PR status. Pairs with git-ops (branches/commits/sync) — pr-ops owns the PR lifecycle after the branch is ready."
+version: "1.0"
+allowed-tools: bash, read, write, edit
+---
+
+# pr-ops — pull requests — create, update, check status, request merge
+
+Every agent in Ymir should have this skill. It handles the full PR lifecycle
+to the main repo at `zerwiz/ymir`.
+
+## Prerequisites
+
+- `gh` CLI authenticated (`gh auth status` must show ✓)
+- A feature branch already pushed (`git-ops` skill handles branch creation)
+- The repo remote is set to `https://github.com/zerwiz/ymir.git`
+
+## Commands
+
+### `pr-create` — Open a new PR
+
+```bash
+pr-create <branch> [--title "Title"] [--body "Body"] [--reviewer <user>]
+```
+
+Creates a PR from `<branch>` → `main` on `zerwiz/ymir`.
+
+- If no `--title` is given, derives one from the branch name.
+- If no `--body` is given, generates one from the commit messages.
+- Optional `--reviewer` assigns a reviewer (default: the Allfather).
+
+### `pr-update` — Update an existing PR
+
+```bash
+pr-update <pr-number> [--title "New title"] [--body "New body"]
+```
+
+Updates the PR title and/or body.
+
+### `pr-status` — Check PR status
+
+```bash
+pr-status [<pr-number>]
+```
+
+Shows CI status, reviews, and mergeability. If no PR number given, shows the
+latest PR from the current branch.
+
+### `pr-merge` — Request merge
+
+```bash
+pr-merge <pr-number>
+```
+
+Marks the PR as ready for merge. **Does not merge** — human approval required.
+
+## Workflow
+
+```
+1. git-ops create_branch → feat/my-change
+2. Make changes, commit (git-ops safe_commit)
+3. git-ops sync_upstream → push + rebase
+4. pr-ops pr-create feat/my-change → opens PR
+5. pr-ops pr-status → check CI
+6. pr-ops pr-merge → request human approval
+```
+
+## PR Template
+
+Every PR should include:
+
+```markdown
+## What
+<One-line description of the change>
+
+## Why
+<Why this change is needed>
+
+## Changes
+- File1: <what changed>
+- File2: <what changed>
+
+## Testing
+<How this was tested>
+
+## Checklist
+- [ ] Follows Norse naming conventions
+- [ ] No secrets in committed files
+- [ ] Tests pass (if applicable)
+- [ ] Docs updated (if applicable)
+```
+
+## Rules
+
+1. **One thing per PR.** A PR does one focused thing.
+2. **No secrets.** Never commit `.env.local`, `.env.realm`, API keys, tokens.
+3. **Human approval.** No auto-merge. The Allfather must explicitly approve.
+4. **Follow git-ops.** Branch creation and commits go through git-ops scripts.
+5. **Norse naming.** Name subsystems for the figure whose role matches its work.
+
+## Integration with git-ops
+
+| Skill | Owns |
+|-------|------|
+| `git-ops` | Branch creation, commits, sync/push |
+| `pr-ops` | PR creation, status, merge request |
+
+They are complementary — git-ops prepares the branch, pr-ops opens the PR.

package/.agents/skills/ratatoskr-a2a/README.md

@@ -0,0 +1,3 @@
+# ratatoskr-a2a — A2A/MCP mesh — a2abridge + wayofteams; registration
+
+See `SKILL.md` for the full skill.

package/.agents/skills/ratatoskr-a2a/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: ratatoskr
+description: >-
+  Ratatoskr — Ymir's A2A/MCP mesh. Load when agents collaborate, when wiring or
+  debugging the a2abridge/A2A directory, when using the wayofteams control-plane
+  MCP, when registering an Eindri over A2A, or when a task is dispatched between
+  machines. Covers the engine, the Ymir front door, and both MCPs together.
+allowed-tools: read,write,bash,glob,grep
+---
+
+# ratatoskr-a2a — A2A/MCP mesh — a2abridge + wayofteams; registration
+
+The squirrel runs the World Tree. Agents collaborate over **A2A 1.0** (JSON-RPC +
+SSE, Agent Cards) via the **`a2abridge`** engine, and coordinate through the
+**Way of Teams** control plane — **both MCP servers at once**.
+
+## The pieces
+
+```
+parts[4]{thing,path,role}:
+  "engine","~/.a2abridge/bin/a2abridge","directory (discovery) · bridge (announce) · service · cert · doctor"
+  "front door","bin/ratatoskr.sh","status|doctor|directory|service|cert — Ymir's wrapper"
+  "wiring","bin/a2a-mcp.sh","installs both MCP servers into pi + opencode"
+  "registration","a2abridge bridge -name -model -skills -directory -advertise-host -id -state-dir","an agent announces by running bridge"
+```
+
+## Two MCPs, together
+
+- **`a2abridge`** — the mesh: `a2a_list_agents`, `a2a_send_message`, `a2a_inbox`,
+  `a2a_complete_task`. Peer-to-peer; standalone.
+- **`wayofteams`** — control plane: tickets, plans, standups, memory, knowledge.
+
+Complementary, not competing. Neither depends on the other. Glue: a Teams
+**ticket → `a2a_send_message`** to the peer; on **`a2a_complete_task`** the result
+goes back to Teams. Same `A2A_NAME` in both planes.
+
+## Use it
+
+```bash
+bin/ratatoskr.sh status          # engine + directory + served agents
+bin/ratatoskr.sh doctor          # health-check
+bin/a2a-mcp.sh install           # (re)wire the MCP servers into pi + opencode
+```
+
+**Production rules:** stable `-id`, `-advertise-host` = the machine's **Tailscale
+IP** (never 127.0.0.1), state in `.a2a/<agent>`, the directory as a **service**,
+heartbeat + deregister, and `cert` (ed25519) before federation. Cards are
+UNSIGNED until then. Realm boundaries hold.
+
+Plan + registration spec: `hodd/docs/ratatoskr.md` and `hodd/docs/a2a-runs.md`.
+
+## Joining the mesh and talking (skill-driven, no code)
+
+A seated Eindri joins and talks **by loading this skill** — the pi adaptor
+(`a2a-send` / `a2a-discover`) and the `a2abridge` MCP provide the tools; this
+skill says how to use them.
+
+**Every pi agent already carries the tools** (pi loads `Way-Of/pi-a2a-adaptor` +
+the `a2abridge` MCP). So inside a session:
+
+- `a2a-agents` / `a2a-discover` — list peers registered with the directory.
+- `a2a-send <peer> "<text>"` — task a peer; the reply comes back as a task.
+- `a2a-broadcast "<text>"` — FYI to the mesh.
+
+**To be reachable**, the agent's bridge must announce to the directory
+(`~/.pi/agent/mcp.json` → `a2abridge`, `A2A_DIRECTORY`). If a peer does not
+appear in `a2a-agents`, the bridge announced to the wrong directory — the fix is
+in the **skill/config**, not new code: point the bridge at
+`http://127.0.0.1:7777` with `-advertise-host <tailnet-ip>` and `-name <agent>`.
+
+**Outside a session** (Brokk, scripts): `bin/a2a-talk.sh agents` and
+`bin/a2a-talk.sh send <peer> "<text>"`.
+
+Rule: the mesh is used through the **skill's tools**, not bespoke code — if a
+capability is missing, extend this skill.
+
+## Delivering a message = injection into the chat
+
+An A2A task that only reaches the bridge is **never read**. The missing function
+is **injection**: the inbound text must be placed into the seated agent's chat.
+
+- **Talk to (deliver to) an Eindri:** `herdr agent prompt <agent-or-pane> "<text>"`
+  — the agent reads it as a new turn and answers in its pane.
+- **Capture the reply:** `herdr agent read <agent-or-pane>` (or pane read) and
+  attach it to the A2A task result.
+- **The rule:** A2A carries the task; **herdr injection makes the target agent
+  read it.** Without injection, an Eindri will not read the a2a.
+
+So the two halves are inseparable:
+```
+a2a-deliver[2]{half,mechanism}:
+  "transport","A2A message/send -> the bridge (JSON-RPC, SSE)"
+  "delivery","inject into the agent's chat via `herdr agent prompt`; read the reply back"
+```
+
+Any agent that can *send* over A2A must also *deliver* by injection on receipt.
+Extend this skill (not code) when the delivery path changes.
+
+## Peer addressing — names are NOT URLs
+
+The A2A tools take an **agent URL** (`a2a_call(agent_url, ...)`). A peer *name*
+like `hermes-zerwiz` is **not** a URL and fails with `Invalid URL`.
+
+**Always resolve first:** call `a2a-agents` (or `a2a-discover`) → find the peer →
+use its **`url`** field. Then `a2a_call(agent_url="<url>", text="…")`.
+
+```
+resolve[1]: a2a-agents -> [{"name":"hermes-zerwiz","url":"http://127.0.0.1:7777/"}, …]
+send[1]:    a2a_call agent_url="http://127.0.0.1:7777/" text="…"
+```
+
+## Tool reference (as shipped in pi)
+
+- **`a2a_call`** — args: `agent_url` (a URL string), `text`. Sends a task and
+  returns the reply. **`agent_url` must be a URL** — a name fails `Invalid URL`.
+- **`a2a-agents` / `a2a-discover`** — list peers as `{name, url, skills}`; use
+  the `url` to address one.
+- **`a2a-send-async`**, **`a2a-pending`**, **`a2a-conversations`** — long tasks.
+- **`a2a-broadcast`**, **`a2a-chain`** — fan-out to the mesh.
+- **Delivery on receipt** is injection (`herdr agent prompt <agent> "<text>"`);
+  the reply is read back with `herdr agent read <agent>` and attached to the task.
+
+Directory: `http://127.0.0.1:7777`. Config: `~/.pi/agent/mcp.json` → `a2abridge`.
+
+## Troubleshooting
+
+- **`Invalid URL`** — you passed a peer *name*. Resolve with `a2a-agents`, then
+  `a2a_call` the `url`.
+- **`Task … exceeded max attempts (N)`** — the call was addressed correctly and
+  the mesh created the task, but it never **completed**: the peer/bridge could
+  not deliver to a live receiving agent, or delivery-by-injection is not wired.
+  Check (a) the peer appears in `a2a-agents`, and (b) a receiving agent is
+  running its bridge so it can read the injected task and answer.
+- **No reply at all** — the transport carried it; the **return path** is missing
+  (the peer's answer was not captured onto the task result).
+
+Rule: a successful `a2a_call` needs **transport + a live peer + delivery
+(injection) + return**. Missing any one shows up as a timeout/attempts error.
+
+## Tools this skill drives (in `bin/`)
+
+```
+tools[4]{tool,does}:
+  "bin/a2a-mcp.sh install","wire the a2abridge (+ wayofteams) MCP servers into pi + opencode"
+  "bin/ratatoskr.sh status|doctor|directory|service|cert","engine + directory front door"
+  "bin/a2a-talk.sh agents|send <peer> \"<text>\"","Brokk-side A2A talk"
+  "bin/a2a-serve.py <pane> <name> <port>","per-Eindri A2A server: inject task -> read reply"
+```

package/.agents/skills/rules-check-drift/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: rules-check-drift
+description: "Check whether your rules file (AGENTS.md) still matches the codebase after recent changes — run before a merge, or fold into your code-review pass. Reports stale/now-false rules, drifted architecture-map entries, and any new invariant worth adding, each with the minimal edit. Advisory and anti-bloat: it keeps the rules file true, never longer than it needs to be."
+argument-hint: "[optional diff range, e.g. main...HEAD]"
+allowed-tools: read,write,bash,glob,grep
+---
+
+# /rules-check-drift — keep your rules file true, not longer
+
+Your rules file — **`AGENTS.md`** — is a **steering document, not documentation**: your ground
+rules, your conventions, and a current **map of where things live**. Its only failure mode that matters
+is being **wrong**: a stale rule or a drifted map actively misleads the agent on every future run.
+This skill checks the rules file against what just changed and proposes the **smallest** edit that
+keeps it true.
+
+> **Wrong rules are worse than missing rules. A longer rules file is worse than a lean one.** Most
+> changes need *no* edit at all — adding a wrong or verbose line makes it worse.
+
+## Input
+- `$ARGUMENTS` — optional diff range. Default: uncommitted + staged (`git diff HEAD`); fall back
+  to `main...HEAD`.
+- **Scope: the project's rules file(s)** — `AGENTS.md` (the root file + any package-level ones).
+  Ignore README, `docs/`, and `.agents/` agent/command/skill files. This skill exists to keep the
+  *rules* honest, nothing else.
+
+## Process
+
+### 1. See what changed
+`git diff <range>` + `git status`. Note: moved/renamed/removed files, new modules, changed
+conventions, and any new invariant the change establishes.
+
+### 2. Read the rules file as it is now
+Load the project's rules file — `AGENTS.md` (and any package-scoped ones). Hold each claim against
+the change set.
+
+### 3. Flag ONLY these three things
+1. **A stated rule or fact is now false** — e.g. "routes live in `src/routes/`" but they moved. →
+     fix it.
+2. **The architecture map drifted** — a path or "where things live" pointer no longer matches
+     reality. → fix the wrong entry (don't catalog every new file).
+3. **A new durable invariant must hold going forward** — the change introduces a rule that must
+     stay true (e.g. "never call the DB from handlers — go through `repository/`"). → add it as
+     **one line**.
+
+Everything else, leave alone. Do **not** suggest an edit to *record that a feature was added* (that's
+a changelog — the codebase is the source of truth), to restate what the code already makes obvious,
+or to add background/rationale/prose that doesn't steer future work.
+
+### 4. Write each suggestion the way AGENTS.md should read
+- **One bullet, not a paragraph.** A rule is a line, not an essay.
+- **Keep the map current — don't grow it.** Fix the wrong path; don't enumerate the new ones.
+- **State rules in natural language; reference the codebase, never paste code.** Copied code goes
+     stale; the codebase stays true. Good: "follow the error pattern in `src/core/errors/`." Bad:
+     pasting the class.
+
+## Output
+
+```
+## Rules-file drift check — range: <range>
+
+### Fix (now false)
+| Where | What's wrong | Minimal fix |
+|-------|--------------|-------------|
+| "Architecture" map | routes moved `src/routes/` → `src/api/routes/` | update the one path |
+
+### Add (new invariant only)
+- <one-line rule> — established by <the change that made it durable>
+
+### Checked, still true — no edit
+- <areas you verified need no change>
+```
+
+If nothing drifted: **"The rules file is still accurate for these changes — no edits needed."**
+
+## Rules
+
+- **Advisory.** Report the drift; only apply/edit files if the caller explicitly asks.
+- **Rules file only** (`AGENTS.md`). Not README, not docs.
+- **Lean by default.** When in doubt, suggest nothing.
+- **Run it before every merge** (or as part of `/piv-review-changes`) so your rules never drift
+  behind the code.

package/.agents/skills/saga-bearings/README.md

@@ -0,0 +1,3 @@
+# saga-bearings — bearings — fleet status digest (/bearings) + recap (/ahoy)
+
+See `SKILL.md` for the full skill.

package/.agents/skills/saga-bearings/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: saga
+description: >-
+  Sága — the seeress, the session's bearings. Load when the Allfather asks for
+  bearings, a morning brief, status, catch-up, "where did I leave off", "what's
+  in the works" (/bearings), or invokes /ahoy to recap visible events and be
+  walked through unresolved decisions. Covers the fleet digest, the dated status
+  artifact, the interactive fleet board, and the recap.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# saga-bearings — bearings — fleet status digest (/bearings) + recap (/ahoy)
+
+Sága sees and tells. This skill is how Brokk reports where things stand and
+closes unanswered calls.
+
+```
+assets[3]{path,load_when}:
+  "assets/bearings.md","/bearings — fleet status digest / pick-up-where-I-left-off; file + lavish modes"
+  "assets/recap.md","/ahoy — recap visible session events + unresolved Allfather decisions"
+  "assets/board-template.html","the interactive fleet board template armed by /bearings lavish"
+```
+
+A change to how Brokk reports bearings edits an asset here, not a new skill.