richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane
running-control-plane
FlaggedCRITICAL INTAKE GATEWAY: use at the start of any non-trivial engineering task, feature, refactor, multi-file bugfix, work package or new idea, including requests to explore, brainstorm, build, fix or change something, before planning or code changes. Enforces read-only discovery, 1-3 structured questions with defaults, control-plane registration and the immutable four-pillar TASK_SPEC.md. Also runs the rest of the control plane: health ("run health check", "check os metrics", "system monitor", event bus, locks, memory, "is my signing identity ready" status check), transition simulation ("dry run transition", "simulate transition", "check edge X -> Y"), worktree selection, and gating on/off ("disable the control plane", "turn off the push guard", "stop gating my commits"). Not for project setup or key creation (use setting-up-agentic-os) or improving skills (use improving-skills-in-lab).
scripts/pre-commit-pipeline-guard
View on GitHub#!/usr/bin/env bash
# ==============================================================================
# pre-commit-pipeline-guard — Deterministic Pipeline Execution & Stage Gate
# ==============================================================================
# Purpose:
# Enforces that no git commit may proceed from an active task branch unless:
# 1. The task has reached an authorized implementation stage in SQLite control plane:
# IN_WORKTREE, WORKTREE_REVIEW, MULTI_AGENT_CODE_REVIEW, VERIFY_EXIT, or DONE;
# OR the commit contains exclusively planning documents under docs/plans/ or docs/superpowers/.
# 2. If a session began in the control plane, all recorded state transitions in
# task_transitions match valid_transitions, transition continuity from INTAKE
# is intact, and no entries exist in transition_violations.
# ==============================================================================
set -e
# Find repo root / git common dir (handles worktrees correctly)
COMMON_GIT_DIR="$(git rev-parse --git-common-dir 2>/dev/null || true)"
if [ -n "$COMMON_GIT_DIR" ]; then
REPO_ROOT="$(cd "$COMMON_GIT_DIR/.." 2>/dev/null && pwd)"
else
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
fi
# Script locations. `control_plane_mode.py enable` stamps the real path of the installed
# running-control-plane skill into this copy; an unstamped copy uses the folder it sits in.
AGENT_CONTROL="@AGENT_CONTROL@"
case "$AGENT_CONTROL" in "@"*) AGENT_CONTROL="$(cd "$(dirname "$0")" 2>/dev/null && pwd)/agent_control.py" ;; esac
# Declared control-plane mode (managed by the os-control-mode skill). The file holds one
# word. A missing file means "enabled", so installs that predate the mode behave as before.
# When it says "disabled" the gate is off BY DESIGN: say so visibly, then pass.
MODE_FILE="$REPO_ROOT/context/control-plane-mode"
if [ -f "$MODE_FILE" ] && [ "$(tr -d '[:space:]' < "$MODE_FILE" | tr '[:upper:]' '[:lower:]')" = "disabled" ]; then
echo "ℹ️ pre-commit-pipeline-guard: control plane is DISABLED (context/control-plane-mode) — commit is ungated by design." >&2
exit 0
fi
DB_PATH="$REPO_ROOT/context/control_plane.db"
# A production control plane must be a regular file: a symlink could point at a simulation database
if [ -L "$DB_PATH" ]; then
echo ""
echo "❌ COMMIT BLOCKED: context/control_plane.db is a symlink!"
echo " The production control plane must be a regular file (a symlink could point at a simulation database)."
echo ""
exit 1
fi
# If control plane database does not exist, pass through with warning
if [ ! -f "$DB_PATH" ]; then
echo "⚠️ WARNING: pre-commit-pipeline-guard found no control_plane.db — commit is ungated (no task registered for this repo)." >&2
exit 0
fi
# A database stamped as a simulation (copied into the production location) never gates real work
DB_IDENTITY="$(sqlite3 "$DB_PATH" "SELECT context FROM control_plane_identity WHERE singleton = 1;" 2>/dev/null || true)"
if [ -n "$DB_IDENTITY" ] && [ "$DB_IDENTITY" != "real" ]; then
echo ""
echo "❌ COMMIT BLOCKED: context/control_plane.db is stamped '$DB_IDENTITY', not 'real'!"
echo " A simulation database cannot stand in for the production control plane."
echo ""
exit 1
fi
# Determine current branch
CURRENT_BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || true)"
# Allow commit for main/master or detached HEAD directly
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ] || [ -z "$CURRENT_BRANCH" ]; then
exit 0
fi
# Reject branch names outside allowlist to prevent SQL injection
if ! echo "$CURRENT_BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then
echo "⚠️ WARNING: pre-commit-pipeline-guard found a branch name with disallowed characters ('$CURRENT_BRANCH') — commit is ungated (cannot safely query the control plane)." >&2
exit 0
fi
# Query SQLite control plane for task on this branch
QUERY_SQL="SELECT task_id, state FROM tasks WHERE worktree_branch = '$CURRENT_BRANCH' ORDER BY created_at DESC LIMIT 1;"
TASK_ROW="$(sqlite3 "$DB_PATH" "$QUERY_SQL" 2>/dev/null || true)"
# If no task associated with this branch, permit commit with warning
if [ -z "$TASK_ROW" ]; then
echo "⚠️ WARNING: pre-commit-pipeline-guard found no task registered for branch '$CURRENT_BRANCH' — commit is ungated." >&2
exit 0
fi
TASK_ID="$(echo "$TASK_ROW" | cut -d'|' -f1)"
TASK_STATE="$(echo "$TASK_ROW" | cut -d'|' -f2)"
# Guidance-compliance block: a human answered "no" (or gave no answer) to a
# transition's mandatory guidance-compliance confirmation. No commit may proceed
# until a human explicitly clears it via clear-guidance-block.
GUIDANCE_BLOCK="$(sqlite3 "$DB_PATH" "SELECT guidance_block_reason FROM tasks WHERE task_id = '$TASK_ID';" 2>/dev/null || true)"
if [ -n "$GUIDANCE_BLOCK" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Task Is Guidance-Blocked!"
echo ""
echo " Task ID: $TASK_ID"
echo " Reason: $GUIDANCE_BLOCK"
echo ""
echo " Clear this with explicit human authorization before committing:"
echo " python3 $AGENT_CONTROL clear-guidance-block --task-id $TASK_ID --reason '<reason>' --human-confirmed 'HUMAN-CONFIRMED: <what the human said>'"
echo ""
exit 1
fi
# Check staged files
STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACM || true)"
# Location-aware enforcement: once a task has an isolated worktree registered
# (worktree_path set and different from the main repo root), that worktree is
# the sole active location for the task -- a commit from anywhere else (e.g.
# the main checkout) on the same branch is a leak, not a legitimate commit.
# Found live (2026-09-13): an agent registered the main checkout itself as
# the "worktree" (a separate bug, now fixed in policy.py's
# _worktree_isolation_check), which meant this hook had no way to tell the
# difference between "working in the registered worktree" and "working in
# the main checkout" -- it only ever checked branch + transition history,
# never location. If worktree_path legitimately equals the repo root (the
# existing_worktree_exception case), reaching IN_WORKTREE at all already
# required that exception receipt per policy.py, so no separate check is
# needed here for that case.
case "$TASK_STATE" in
IN_WORKTREE|WORKTREE_REVIEW|MULTI_AGENT_CODE_REVIEW|VERIFY_EXIT|DONE)
TASK_WORKTREE_PATH="$(sqlite3 "$DB_PATH" "SELECT worktree_path FROM tasks WHERE task_id = '$TASK_ID';" 2>/dev/null || true)"
if [ -n "$TASK_WORKTREE_PATH" ]; then
RESOLVED_REPO_ROOT="$(cd "$REPO_ROOT" 2>/dev/null && pwd || echo "$REPO_ROOT")"
case "$TASK_WORKTREE_PATH" in
/*) RESOLVED_TASK_WORKTREE="$(cd "$TASK_WORKTREE_PATH" 2>/dev/null && pwd || echo "$TASK_WORKTREE_PATH")" ;;
*) RESOLVED_TASK_WORKTREE="$(cd "$RESOLVED_REPO_ROOT/$TASK_WORKTREE_PATH" 2>/dev/null && pwd || echo "$RESOLVED_REPO_ROOT/$TASK_WORKTREE_PATH")" ;;
esac
CURRENT_CHECKOUT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$REPO_ROOT")"
if [ "$RESOLVED_TASK_WORKTREE" != "$RESOLVED_REPO_ROOT" ] && [ "$CURRENT_CHECKOUT_ROOT" != "$RESOLVED_TASK_WORKTREE" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Commit Outside Registered Worktree (Leak)!"
echo ""
echo " Task ID: $TASK_ID"
echo " Task State: $TASK_STATE"
echo " Registered worktree: $RESOLVED_TASK_WORKTREE"
echo " Current location: $CURRENT_CHECKOUT_ROOT"
echo ""
echo " This task has an isolated worktree registered. All further commits for"
echo " this task's branch must happen inside that worktree, not here."
echo ""
exit 1
fi
fi
;;
esac
# Handle planning / proposal states
case "$TASK_STATE" in
INTAKE|INTERVIEW|DRAFT_PLAN|PLAN_REVIEW|MULTI_AGENT_REVIEW|AWAITING_APPROVAL)
# If staged files exist, check if all of them are planning docs
if [ -n "$STAGED_FILES" ]; then
NON_PLAN_FILES=$(echo "$STAGED_FILES" | grep -vE '^(docs/plans/|docs/superpowers/)' || true)
if [ -n "$NON_PLAN_FILES" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Proposal Mode Violation!"
echo ""
echo " Branch: $CURRENT_BRANCH"
echo " Task ID: $TASK_ID"
echo " Task State: $TASK_STATE"
echo ""
echo " Production code modifications are strictly prohibited while in proposal/planning mode."
echo " Non-planning files staged for commit:"
echo "$NON_PLAN_FILES" | sed 's/^/ • /'
echo ""
echo " To advance through the pipeline:"
echo " 1. Complete Socratic interview and draft spec/plan in docs/plans/"
echo " 2. Obtain human approval: python3 $AGENT_CONTROL coordinate-transition --task-id $TASK_ID --to APPROVED --approval APPROVAL --actor human"
echo " 3. Create worktree: python3 $AGENT_CONTROL coordinate-transition --task-id $TASK_ID --to IN_WORKTREE --actor controller"
echo ""
exit 1
fi
fi
# If only planning files are staged, permit commit
exit 0
;;
IN_WORKTREE|WORKTREE_REVIEW|MULTI_AGENT_CODE_REVIEW|VERIFY_EXIT|DONE)
# Verify complete pipeline execution if session began in control plane:
# Check transition_violations
VIOLATIONS_COUNT="$(sqlite3 "$DB_PATH" "SELECT COUNT(*) FROM transition_violations WHERE task_id = '$TASK_ID' AND kind = 'ILLEGAL_TRANSITION';" 2>/dev/null || echo "0")"
if [ "$VIOLATIONS_COUNT" -gt 0 ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Control Plane Transition Violations Detected!"
echo ""
echo " Task ID: $TASK_ID"
echo " Violations: $VIOLATIONS_COUNT illegal transition attempt(s) logged in transition_violations table."
echo " Tampering with SQLite state or skipping pipeline stages is strictly prohibited."
echo ""
exit 1
fi
# Check all transitions against valid_transitions
TRANSITIONS_ROWS="$(sqlite3 "$DB_PATH" "SELECT transition_id, from_state, to_state FROM task_transitions WHERE task_id = '$TASK_ID' ORDER BY transition_id ASC;" 2>/dev/null || true)"
if [ -z "$TRANSITIONS_ROWS" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: No Transition History Found!"
echo ""
echo " Task ID: $TASK_ID"
echo " No lifecycle transitions recorded in task_transitions table."
echo ""
exit 1
fi
LAST_TO=""
while IFS='|' read -r transition_id from_st to_st; do
[ -z "$from_st" ] && continue
if [ "$from_st" = "NONE" ] && [ "$to_st" = "INTAKE" ]; then
LAST_TO="INTAKE"
continue
fi
# Normal edges must be in valid_transitions. A non-DAG edge is valid only when
# this exact persisted transition has a consumed, human recovery approval.
IS_VALID="$(sqlite3 "$DB_PATH" "SELECT COUNT(*) FROM valid_transitions WHERE from_state = '$from_st' AND to_state = '$to_st';" 2>/dev/null || echo "0")"
if [ "$IS_VALID" -eq 0 ]; then
RECOVERY_VALID="$(sqlite3 "$DB_PATH" "SELECT COUNT(*) FROM transition_decisions WHERE task_id = '$TASK_ID' AND bound_transition_id = '$transition_id' AND from_state = '$from_st' AND to_state = '$to_st' AND decision_type = 'APPROVAL' AND actor = 'human' AND question_id LIKE 'recovery_approval_%' AND consumed_at IS NOT NULL;" 2>/dev/null || echo "0")"
if [ "$RECOVERY_VALID" -eq 0 ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Invalid State Transition Detected!"
echo ""
echo " Task ID: $TASK_ID"
echo " Edge: $from_st -> $to_st"
echo " This transition is not in valid_transitions and has no exact human recovery approval."
echo ""
exit 1
fi
fi
# Check continuity
if [ -n "$LAST_TO" ] && [ "$from_st" != "$LAST_TO" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Broken Pipeline State Chain!"
echo ""
echo " Task ID: $TASK_ID"
echo " Broken chain: Expected transition from '$LAST_TO', but found transition from '$from_st' to '$to_st'."
echo ""
exit 1
fi
LAST_TO="$to_st"
done <<< "$TRANSITIONS_ROWS"
# Check final transition matches current state
if [ -n "$LAST_TO" ] && [ "$LAST_TO" != "$TASK_STATE" ]; then
echo ""
echo "❌ GIT COMMIT BLOCKED: Current State Desynchronized From Transition Log!"
echo ""
echo " Task ID: $TASK_ID"
echo " Table State: $TASK_STATE"
echo " Log State: $LAST_TO"
echo ""
exit 1
fi
exit 0
;;
*)
echo ""
echo "❌ GIT COMMIT BLOCKED: Unauthorized Task State!"
echo ""
echo " Branch: $CURRENT_BRANCH"
echo " Task ID: $TASK_ID"
echo " Task State: $TASK_STATE"
echo ""
echo " Commits are forbidden in state '$TASK_STATE'."
echo ""
exit 1
;;
esac
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |