Mastermind Liveness

---
name: mastermind-liveness
description: Mastermind liveness — enforce the non-terminal issue liveness contract for agent-owned work. Checks if every in_progress/blocked/in_review issue has a valid action path (active run, queued wake, explicit blocker, or recovery action). Can checkout an issue to an agent run, release checkout, trigger wakeup decisions, and file explicit recovery actions for stalled issues. Based on Paperclip's execution-semantics.md liveness contract.
type: domain-skill
default_mode: auto
---

# Mastermind Liveness

This skill is invoked by `mastermind:liveness` or directly via `/mastermind:liveness`.

---

## Inputs

- `brain_context`: BRAIN CONTEXT block (injected by command, or loaded below if standalone)
- `org_name`: org to check (required)
- `action`: check | checkout | release | wakeup | recover
- `issue_id`: specific issue to operate on (required for checkout/release/wakeup/recover)
- `agent_id`: agent claiming checkout (required for checkout)
- `run_id`: execution run ID (required for checkout)
- `reason`: recovery reason (required for recover)
- `caller`: command | master

---

## Liveness Contract

An issue is **healthy** when the product can answer "what moves this forward next?" without requiring a human to reconstruct intent.

An issue is **stalled** when it is non-terminal but has no:
- active run linked to the issue
- queued wake or continuation deliverable to the responsible agent
- explicit execution-policy participant
- pending interaction waiting on a specific responder
- one-shot monitor (`nextCheckAt`) that will wake the assignee
- human owner (`assigneeUserId`)
- first-class blocker chain whose leaf issues are themselves healthy
- open explicit recovery action naming owner + next action

**Valid non-terminal statuses for agent-owned work:** `todo`, `in_progress`, `blocked`, `in_review`

**Status → execution expectation:**
- `todo`: actionable but not yet claimed — may still need wake path to assignee
- `in_progress`: must have agent assignee + active execution backing (strict)
- `blocked`: must have named external dependency (blockedByIssueIds) or explicit human decision needed
- `in_review`: review participant must be named; next move belongs to reviewer

---

## Step 0 — Brain Load (standalone only)

If `caller` is not "command", load brain context following mastermind-protocol/SKILL.md Brain Load Procedure with namespace: `ops`.

---

## Step 1 — Load Org and Issues

```bash
orgFile=".monomind/orgs/${org_name}.json"
[ ! -f "$orgFile" ] && { echo "ERROR: Org '${org_name}' not found."; exit 1; }

issuesFile=".monomind/orgs/${org_name}-issues.json"
stateFile=".monomind/orgs/${org_name}-state.json"
```

Normalize any legacy records written by a pre-2.10 version of these skills. Idempotent — safe to run on every load. Guarded because this skill tolerates a missing issues file.

```bash
[ -f "$issuesFile" ] && python3 - "$issuesFile" <<'PYEOF'
import json, sys
path = sys.argv[1]
data = json.load(open(path))
RENAME = {
    "assignee_id": "assigneeId", "assigned_to": "assigneeId",
    "created_at": "createdAt", "updated_at": "updatedAt",
    "closed_at": "closedAt", "project_id": "projectId",
    "parent_id": "parentId", "recovery_status": "recoveryStatus",
    "lastActivityAt": "updatedAt",
}
changed = False
for iss in data.get("issues", []):
    for old, new in RENAME.items():
        if old in iss:
            iss.setdefault(new, iss.pop(old))
            iss.pop(old, None)
            changed = True
    if iss.get("status") == "open":
        iss["status"] = "todo"
        changed = True
if changed:
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump(data, f, indent=2)
    import os; os.replace(tmp, path)
PYEOF
```

---

## Step 2 — Execute Action

### check (default)

Audit every non-terminal agent-owned issue for liveness. Flag stalled issues.

```bash
echo "LIVENESS CHECK — ${org_name}"
echo "════════════════════════════════════════════════════════"

python3 - "$issuesFile" "$stateFile" <<'PYEOF'
import json, sys, os
from datetime import datetime, timedelta

issues_path = sys.argv[1]
state_path  = sys.argv[2]

# Load issues
if not os.path.exists(issues_path):
    print("  No issues file found. Org has no tracked issues.")
    sys.exit(0)

data   = json.load(open(issues_path))
issues = data.get("issues", [])

# Load active agent run IDs from state
active_runs = set()
if os.path.exists(state_path):
    try:
        state = json.load(open(state_path))
        for role in state.get("roles", []):
            if role.get("currentRunId"): active_runs.add(role["currentRunId"])
    except: pass

non_terminal_statuses = {"todo","in_progress","blocked","in_review"}
terminal_statuses     = {"done","cancelled"}

healthy, stalled, warnings = [], [], []
now = datetime.utcnow()

for iss in issues:
    status = iss.get("status","")
    iid    = iss.get("id","?")
    title  = (iss.get("title") or "?")[:50]

    if status in terminal_statuses:
        continue
    if status not in non_terminal_statuses:
        # Silently skipping an unknown status is how issues become invisible.
        warnings.append((iid, title, status, f"unknown status '{status}' — outside the canonical vocabulary"))
        continue

    aId = iss.get("assigneeAgentId")
    uId = iss.get("assigneeUserId")

    # Human-owned: the next move belongs to a person, not an execution path.
    if uId and not aId:
        healthy.append((iid, title, status, "user-owned"))
        continue

    paths = []

    run_id = iss.get("executionRunId") or iss.get("checkoutRunId")
    if run_id and run_id in active_runs:
        paths.append("active-run")

    resolved_ids = {i.get("id") for i in issues if i.get("status") in terminal_statuses}
    blockers = iss.get("blockedByIssueIds") or []
    if status == "blocked":
        if blockers:
            unresolved = [b for b in blockers if b not in resolved_ids]
            if unresolved:
                paths.append(f"blocked-by:{','.join(unresolved[:2])}")
            else:
                warnings.append((iid, title, status, "all blockers resolved but issue still blocked"))
        elif not iss.get("recoveryActions"):
            # Liveness Contract: blocked requires a named dependency or an
            # explicit human decision. This issue records neither.
            stalled.append((iid, title, status, "blocked with no blockedByIssueIds and no recovery action"))
            continue

    if iss.get("executionPolicy", {}).get("monitor", {}).get("nextCheckAt"):
        paths.append("monitor")

    if iss.get("recoveryActions") and any(
        r.get("status") not in ("resolved","cancelled")
        for r in iss.get("recoveryActions",[])
    ):
        paths.append("recovery-action")

    if iss.get("currentParticipant"):
        paths.append("participant")

    if status == "in_review" and not (iss.get("reviewerId") or iss.get("currentParticipant")):
        stalled.append((iid, title, status, "in_review with no named reviewer"))
        continue

    if status == "in_progress" and aId and not paths:
        updated = iss.get("updatedAt","")
        if updated:
            try:
                age = now - datetime.fromisoformat(updated[:19])
                if age > timedelta(hours=2):
                    stalled.append((iid, title, status, f"in_progress {int(age.total_seconds()//3600)}h with no active path"))
                    continue
            except Exception:
                pass
        stalled.append((iid, title, status, "in_progress with no active execution path"))
        continue

    if paths:
        healthy.append((iid, title, status, " + ".join(paths)))
    elif not aId:
        warnings.append((iid, title, status, "no assignee — nothing will pick this up"))
    elif status == "todo":
        warnings.append((iid, title, status, "todo assigned to agent — may need wakeup"))
    else:
        stalled.append((iid, title, status, f"{status} with an agent assignee but no execution path"))

print(f"  ✓ Healthy: {len(healthy)}")
if healthy:
    for iid, t, s, p in healthy[:5]:
        print(f"    {iid}: [{s}] {t} — {p}")
    if len(healthy) > 5: print(f"    … {len(healthy)-5} more")

print()
if stalled:
    print(f"  ✗ STALLED: {len(stalled)}")
    for iid, t, s, p in stalled:
        print(f"    {iid}: [{s}] {t}")
        print(f"      → {p}")
    print()
    print("  Fix: /mastermind:liveness --org <org> --action recover --issue-id <id> --reason 'execution path lost'")
else:
    print("  ✓ No stalled issues.")

if warnings:
    print()
    print(f"  ⚠ Warnings: {len(warnings)}")
    for iid, t, s, p in warnings:
        print(f"    {iid}: [{s}] {t} — {p}")
PYEOF
```

### checkout

Claim an issue for execution by an agent run. Sets `checkoutRunId` and `executionRunId`.

```bash
[ -z "$issue_id" ] && { echo "ERROR: --issue-id required."; exit 1; }
[ -z "$agent_id" ] && { echo "ERROR: --agent-id required."; exit 1; }
[ -z "$run_id"   ] && { echo "ERROR: --run-id required."; exit 1; }
ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)

python3 - "$issuesFile" "$issue_id" "$agent_id" "$run_id" "$ts" <<'PYEOF'
import json, os, sys

path, iid, agentId, runId, ts = sys.argv[1:]
data = json.load(open(path))
issues = data.get("issues", [])

found = False
for iss in issues:
    if iss.get("id") == iid:
        existing = iss.get("checkoutRunId")
        if existing and existing != runId:
            print(f"  CONFLICT: Issue already checked out by run {existing}")
            print(f"  Release first: /mastermind:liveness --org <org> --action release --issue-id {iid}")
            sys.exit(1)
        iss["checkoutRunId"]  = runId
        iss["executionRunId"] = runId
        iss["assigneeId"]     = agentId
        iss["assigneeAgentId"]= agentId
        iss["assigneeUserId"] = None
        iss["status"]         = "in_progress"
        iss["checkedOutAt"]   = ts
        iss["updatedAt"]      = ts
        found = True
        print(f"  CHECKOUT: Issue {iid} → agent {agentId}, run {runId}")
        print(f"  Status set to: in_progress")
        break

if not found:
    print(f"  ERROR: Issue '{iid}' not found.")
    sys.exit(1)

data["issues"] = issues
tmp = path + ".tmp"
with open(tmp, "w") as f:
    json.dump(data, f, indent=2)
os.replace(tmp, path)
PYEOF

activityFile=".monomind/orgs/${org_name}-activity.jsonl"
jq -cn --arg iid "$issue_id" --arg ts "$ts" --arg st "in_progress" --arg ag "$agent_id" --arg sm "checkout $issue_id" \
  '{issue_id:$iid, ts:$ts, status:$st, tokens:null, agent:$ag, type:"checkout", summary:$sm}' \
  >> "$activityFile"
```

### release

Release the checkout lock on an issue.

```bash
[ -z "$issue_id" ] && { echo "ERROR: --issue-id required."; exit 1; }
ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)

python3 - "$issuesFile" "$issue_id" "$ts" "${run_id:-}" <<'PYEOF'
import json, sys, os

path, iid, ts, run_id = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
data = json.load(open(path))
issues = data.get("issues", [])

for iss in issues:
    if iss.get("id") == iid:
        current = iss.get("checkoutRunId","")
        if run_id and current != run_id:
            print(f"  WARNING: Releasing run {run_id} but issue has run {current}. Proceeding.")
        iss.pop("checkoutRunId", None)
        iss.pop("executionRunId", None)
        iss.pop("checkedOutAt", None)
        iss["updatedAt"] = ts
        print(f"  RELEASED: Checkout cleared for issue {iid}")
        print(f"  Status remains: {iss.get('status','?')} — update separately if needed.")
        data["issues"] = issues
        tmp = path + ".tmp"
        with open(tmp, "w") as f:
            json.dump(data, f, indent=2)
        os.replace(tmp, path)
        sys.exit(0)

print(f"  ERROR: Issue '{iid}' not found.")
sys.exit(1)
PYEOF

activityFile=".monomind/orgs/${org_name}-activity.jsonl"
currentStatus=$(jq -r --arg id "$issue_id" '(.issues // [])[] | select(.id == $id) | .status // "todo"' "$issuesFile")
jq -cn --arg iid "$issue_id" --arg ts "$ts" --arg st "$currentStatus" --arg ag "${agent_id:-operator}" --arg sm "release $issue_id" \
  '{issue_id:$iid, ts:$ts, status:$st, tokens:null, agent:$ag, type:"release", summary:$sm}' \
  >> "$activityFile"
```

### wakeup

Decide whether the assignee of a `todo` or `blocked` issue should be woken.

```bash
[ -z "$issue_id" ] && { echo "ERROR: --issue-id required."; exit 1; }

python3 - "$issuesFile" "$stateFile" "$issue_id" "${agent_id:-}" <<'PYEOF'
import json, sys, os

issues_path, state_path, iid, actor_agent_id = sys.argv[1:]

data = json.load(open(issues_path))
iss = next((i for i in data.get("issues",[]) if i.get("id") == iid), None)
if not iss:
    print(f"  ERROR: Issue '{iid}' not found.")
    sys.exit(1)

checkout_agent = iss.get("assigneeAgentId") or ""
checkout_run   = iss.get("checkoutRunId","")

# Port of Paperclip's shouldWakeAssigneeOnCheckout logic
actor_is_agent     = bool(actor_agent_id)
actor_differs      = actor_agent_id != checkout_agent
checkout_has_no_run= not checkout_run

should_wake = (
    not actor_is_agent          # non-agent actor (board/human) → always wake
    or actor_differs            # different agent claiming → wake original
    or checkout_has_no_run      # no active run → wake to get work started
)

print(f"  Issue:   {iid} — {iss.get('title','?')[:60]}")
print(f"  Status:  {iss.get('status','?')}")
print(f"  Assignee:{checkout_agent or '(none)'}")
print(f"  Run:     {checkout_run or '(none)'}")
print(f"  Actor:   {actor_agent_id or '(board)'}")
print()
if should_wake:
    print("  WAKE: YES — assignee should be notified to pick up this issue.")
    print("  Reasons:")
    if not actor_is_agent:           print("    · Non-agent actor (board/human)")
    if actor_is_agent and actor_differs: print(f"    · Actor ({actor_agent_id}) != assignee ({checkout_agent})")
    if checkout_has_no_run:          print("    · No active execution run")
else:
    print("  WAKE: NO — assignee already has an active run for this issue.")
PYEOF
```

### recover

File an explicit recovery action on a stalled issue with a named owner and next step.

```bash
[ -z "$issue_id" ] && { echo "ERROR: --issue-id required."; exit 1; }
[ -z "$reason"   ] && { echo "ERROR: --reason required."; exit 1; }
ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
recoveryId="recovery-$(python3 -c 'import time; print(int(time.time()*1000))')"

python3 - "$issuesFile" "$issue_id" "$recoveryId" "${agent_id:-operator}" "$reason" "$ts" <<'PYEOF'
import json, os, sys

path, iid, rid, owner, cause, ts = sys.argv[1:]
data = json.load(open(path))
issues = data.get("issues", [])

for iss in issues:
    if iss.get("id") == iid:
        recovery = {
            "id": rid,
            "kind": "restore-liveness",
            "owner": owner,
            "cause": cause,
            "createdAt": ts,
            "status": "open",
            "nextAction": f"Investigate why issue '{iid}' has no active execution path and restore it.",
        }
        iss.setdefault("recoveryActions", []).append(recovery)
        iss["status"] = "blocked"
        iss["updatedAt"] = ts
        data["issues"] = issues
        tmp = path + ".tmp"
        with open(tmp, "w") as f:
            json.dump(data, f, indent=2)
        os.replace(tmp, path)
        print(f"  RECOVERY ACTION FILED: {rid}")
        print(f"  Issue {iid} → status: blocked (pending recovery)")
        print(f"  Owner: {owner}")
        print(f"  Cause: {cause}")
        print(f"  Resolve with: /mastermind:liveness --org <org> --action checkout --issue-id {iid} --agent-id <id> --run-id <id>")
        sys.exit(0)

print(f"  ERROR: Issue '{iid}' not found.")
sys.exit(1)
PYEOF

activityFile=".monomind/orgs/${org_name}-activity.jsonl"
jq -cn --arg iid "$issue_id" --arg ts "$ts" --arg st "blocked" --arg ag "${agent_id:-operator}" --arg sm "recover $issue_id" \
  '{issue_id:$iid, ts:$ts, status:$st, tokens:null, agent:$ag, type:"recover", summary:$sm}' \
  >> "$activityFile"
```

---

## Step 3 — Return Output

```yaml
domain: ops
status: complete
action: <action>
org_name: <org_name>
issue_id: <issue_id or all>
```

---

## Step 4 — Brain Write (standalone only)

If `caller` is not "command", follow mastermind-protocol/SKILL.md Brain Write Procedure for domain `ops`.