agent-control-plane 0.1.0

package/tools/bin/install-dashboard-launchd.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  install-dashboard-launchd.sh [--host 127.0.0.1] [--port 8765] [--label ai.agent.dashboard]
+
+Installs a per-user LaunchAgent so the ACP worker dashboard starts automatically
+after login/restart.
+EOF
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FLOW_SKILL_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+HOME_DIR="${ACP_DASHBOARD_HOME_DIR:-${HOME:-}}"
+SOURCE_HOME="${ACP_DASHBOARD_SOURCE_HOME:-$(cd "${FLOW_SKILL_DIR}/../../.." && pwd)}"
+RUNTIME_HOME="${ACP_DASHBOARD_RUNTIME_HOME:-${HOME_DIR}/.agent-runtime/runtime-home}"
+WORKSPACE_DIR="${ACP_DASHBOARD_WORKSPACE_DIR:-${HOME_DIR}/.agent-runtime/control-plane/workspace}"
+PROFILE_REGISTRY_ROOT="${ACP_DASHBOARD_PROFILE_REGISTRY_ROOT:-${ACP_PROFILE_REGISTRY_ROOT:-${HOME_DIR}/.agent-runtime/control-plane/profiles}}"
+LAUNCH_AGENTS_DIR="${ACP_DASHBOARD_LAUNCH_AGENTS_DIR:-${HOME_DIR}/Library/LaunchAgents}"
+LOG_DIR="${ACP_DASHBOARD_LOG_DIR:-${HOME_DIR}/.agent-runtime/logs}"
+LABEL="${ACP_DASHBOARD_LABEL:-ai.agent.dashboard}"
+HOST="${ACP_DASHBOARD_HOST:-127.0.0.1}"
+PORT="${ACP_DASHBOARD_PORT:-8765}"
+BASE_PATH="${ACP_DASHBOARD_PATH:-/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin}"
+SYNC_SCRIPT="${ACP_DASHBOARD_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/sync-shared-agent-home.sh}"
+BOOTSTRAP_SCRIPT="${ACP_DASHBOARD_BOOTSTRAP_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/dashboard-launchd-bootstrap.sh}"
+WRAPPER_PATH="${WORKSPACE_DIR}/bin/agent-dashboard-launchd.sh"
+PLIST_PATH="${LAUNCH_AGENTS_DIR}/${LABEL}.plist"
+STDOUT_LOG="${LOG_DIR}/agent-dashboard.stdout.log"
+STDERR_LOG="${LOG_DIR}/agent-dashboard.stderr.log"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --host)
+      HOST="${2:-}"
+      shift 2
+      ;;
+    --port)
+      PORT="${2:-}"
+      shift 2
+      ;;
+    --label)
+      LABEL="${2:-}"
+      PLIST_PATH="${LAUNCH_AGENTS_DIR}/${LABEL}.plist"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 64
+      ;;
+  esac
+done
+
+if [[ -z "${HOME_DIR}" ]]; then
+  echo "install-dashboard-launchd requires HOME or ACP_DASHBOARD_HOME_DIR" >&2
+  exit 64
+fi
+
+mkdir -p "${WORKSPACE_DIR}/bin" "${LAUNCH_AGENTS_DIR}" "${LOG_DIR}"
+
+cat >"${WRAPPER_PATH}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export ACP_DASHBOARD_HOME_DIR='${HOME_DIR}'
+export ACP_DASHBOARD_SOURCE_HOME='${SOURCE_HOME}'
+export ACP_DASHBOARD_RUNTIME_HOME='${RUNTIME_HOME}'
+export ACP_DASHBOARD_PROFILE_REGISTRY_ROOT='${PROFILE_REGISTRY_ROOT}'
+export ACP_DASHBOARD_HOST='${HOST}'
+export ACP_DASHBOARD_PORT='${PORT}'
+export ACP_DASHBOARD_PATH='${BASE_PATH}'
+export ACP_DASHBOARD_SYNC_SCRIPT='${SYNC_SCRIPT}'
+exec bash '${BOOTSTRAP_SCRIPT}'
+EOF
+chmod +x "${WRAPPER_PATH}"
+
+cat >"${PLIST_PATH}" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>${LABEL}</string>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>${WRAPPER_PATH}</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>WorkingDirectory</key>
+	<string>${WORKSPACE_DIR}</string>
+	<key>StandardErrorPath</key>
+	<string>${STDERR_LOG}</string>
+	<key>StandardOutPath</key>
+	<string>${STDOUT_LOG}</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+		<key>HOME</key>
+		<string>${HOME_DIR}</string>
+		<key>PATH</key>
+		<string>${BASE_PATH}</string>
+		<key>ACP_PROFILE_REGISTRY_ROOT</key>
+		<string>${PROFILE_REGISTRY_ROOT}</string>
+		<key>PYTHONDONTWRITEBYTECODE</key>
+		<string>1</string>
+	</dict>
+</dict>
+</plist>
+EOF
+
+if [[ "${ACP_DASHBOARD_SKIP_LAUNCHCTL:-0}" == "1" ]]; then
+  printf 'LAUNCHD_INSTALL_STATUS=skipped-launchctl\n'
+  printf 'LABEL=%s\n' "${LABEL}"
+  printf 'PLIST=%s\n' "${PLIST_PATH}"
+  printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"
+  printf 'URL=http://%s:%s\n' "${HOST}" "${PORT}"
+  exit 0
+fi
+
+user_domain="gui/$(id -u)"
+launchctl bootout "${user_domain}/${LABEL}" >/dev/null 2>&1 || true
+launchctl bootstrap "${user_domain}" "${PLIST_PATH}"
+launchctl kickstart -k "${user_domain}/${LABEL}"
+
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if curl -fsS "http://${HOST}:${PORT}/api/snapshot.json" >/dev/null 2>&1; then
+    printf 'LAUNCHD_INSTALL_STATUS=ok\n'
+    printf 'LABEL=%s\n' "${LABEL}"
+    printf 'PLIST=%s\n' "${PLIST_PATH}"
+    printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"
+    printf 'URL=http://%s:%s\n' "${HOST}" "${PORT}"
+    exit 0
+  fi
+  sleep 1
+done
+
+printf 'LAUNCHD_INSTALL_STATUS=unhealthy\n'
+printf 'LABEL=%s\n' "${LABEL}"
+printf 'PLIST=%s\n' "${PLIST_PATH}"
+printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"
+printf 'URL=http://%s:%s\n' "${HOST}" "${PORT}"
+exit 1

package/tools/bin/install-project-launchd.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  install-project-launchd.sh --profile-id <id> [options]
+
+Install a per-user LaunchAgent so one ACP project runtime starts automatically
+after login/restart.
+
+Options:
+  --profile-id <id>       Installed profile id to manage
+  --label <label>         Override LaunchAgent label (default: ai.agent.project.<id>)
+  --delay-seconds <n>     Initial supervisor delay before first bootstrap (default: 0)
+  --interval-seconds <n>  Supervisor interval between bootstrap passes (default: 15)
+  --help                  Show this help
+EOF
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+append_path_dir() {
+  local value_name="${1:?value name required}"
+  local candidate="${2:-}"
+  local current=""
+
+  [[ -n "${candidate}" && -d "${candidate}" ]] || return 0
+  current="${!value_name:-}"
+  case ":${current}:" in
+    *":${candidate}:"*) return 0 ;;
+  esac
+  if [[ -n "${current}" ]]; then
+    printf -v "${value_name}" '%s:%s' "${current}" "${candidate}"
+  else
+    printf -v "${value_name}" '%s' "${candidate}"
+  fi
+}
+
+resolved_tool_dir() {
+  local tool_name="${1:-}"
+  local tool_path=""
+
+  [[ -n "${tool_name}" ]] || return 1
+  tool_path="$(command -v "${tool_name}" 2>/dev/null || true)"
+  [[ -n "${tool_path}" ]] || return 1
+  dirname "${tool_path}"
+}
+
+build_launchd_base_path() {
+  local path_value="${ACP_PROJECT_RUNTIME_PATH:-/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin}"
+  local tool_name=""
+  local tool_dir=""
+
+  for tool_name in node gh git python3 openclaw codex claude; do
+    tool_dir="$(resolved_tool_dir "${tool_name}" || true)"
+    append_path_dir path_value "${tool_dir}"
+  done
+
+  printf '%s\n' "${path_value}"
+}
+
+profile_id_override=""
+label_override=""
+delay_seconds="0"
+interval_seconds="15"
+profile_registry_root_override="${ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT:-${ACP_PROFILE_REGISTRY_ROOT:-}}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile-id) profile_id_override="${2:-}"; shift 2 ;;
+    --label) label_override="${2:-}"; shift 2 ;;
+    --delay-seconds) delay_seconds="${2:-}"; shift 2 ;;
+    --interval-seconds) interval_seconds="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 64 ;;
+  esac
+done
+
+if [[ -z "${profile_id_override}" ]]; then
+  usage >&2
+  exit 64
+fi
+
+case "${delay_seconds}" in
+  ''|*[!0-9]*) echo "--delay-seconds must be numeric" >&2; exit 64 ;;
+esac
+
+case "${interval_seconds}" in
+  ''|*[!0-9]*) echo "--interval-seconds must be numeric" >&2; exit 64 ;;
+esac
+
+export ACP_PROJECT_ID="${profile_id_override}"
+export AGENT_PROJECT_ID="${profile_id_override}"
+if [[ -n "${profile_registry_root_override}" ]]; then
+  export ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root_override}"
+fi
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+if ! flow_require_explicit_profile_selection "${FLOW_SKILL_DIR}" "install-project-launchd.sh"; then
+  exit 64
+fi
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+if [[ ! -f "${CONFIG_YAML}" ]]; then
+  printf 'profile not installed: %s\n' "${profile_id_override}" >&2
+  exit 66
+fi
+
+PROFILE_ID="$(flow_resolve_adapter_id "${CONFIG_YAML}")"
+profile_slug="$(printf '%s' "${PROFILE_ID}" | tr -c 'A-Za-z0-9._-' '-')"
+HOME_DIR="${ACP_PROJECT_RUNTIME_HOME_DIR:-${HOME:-}}"
+SOURCE_HOME="${ACP_PROJECT_RUNTIME_SOURCE_HOME:-$(cd "${FLOW_SKILL_DIR}/../../.." && pwd)}"
+RUNTIME_HOME="${ACP_PROJECT_RUNTIME_RUNTIME_HOME:-${HOME_DIR}/.agent-runtime/runtime-home}"
+WORKSPACE_DIR="${ACP_PROJECT_RUNTIME_WORKSPACE_DIR:-${HOME_DIR}/.agent-runtime/control-plane/workspace}"
+PROFILE_REGISTRY_ROOT="${ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT:-${ACP_PROFILE_REGISTRY_ROOT:-${HOME_DIR}/.agent-runtime/control-plane/profiles}}"
+LAUNCH_AGENTS_DIR="${ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR:-${HOME_DIR}/Library/LaunchAgents}"
+LOG_DIR="${ACP_PROJECT_RUNTIME_LOG_DIR:-${HOME_DIR}/.agent-runtime/logs}"
+LABEL="${label_override:-${ACP_PROJECT_RUNTIME_LAUNCHD_LABEL:-ai.agent.project.${profile_slug}}}"
+BASE_PATH="$(build_launchd_base_path)"
+SYNC_SCRIPT="${ACP_PROJECT_RUNTIME_SYNC_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/sync-shared-agent-home.sh}"
+BOOTSTRAP_SCRIPT="${ACP_PROJECT_RUNTIME_BOOTSTRAP_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-launchd-bootstrap.sh}"
+SUPERVISOR_SCRIPT="${ACP_PROJECT_RUNTIME_SUPERVISOR_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-runtime-supervisor.sh}"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+SUPERVISOR_PID_FILE="${STATE_ROOT}/runtime-supervisor.pid"
+ENV_FILE="${ACP_PROJECT_RUNTIME_ENV_FILE:-${PROFILE_REGISTRY_ROOT}/${PROFILE_ID}/runtime.env}"
+WRAPPER_PATH="${WORKSPACE_DIR}/bin/agent-project-${profile_slug}-launchd.sh"
+PLIST_PATH="${LAUNCH_AGENTS_DIR}/${LABEL}.plist"
+STDOUT_LOG="${LOG_DIR}/agent-project-${profile_slug}.stdout.log"
+STDERR_LOG="${LOG_DIR}/agent-project-${profile_slug}.stderr.log"
+
+if [[ -z "${HOME_DIR}" ]]; then
+  echo "install-project-launchd requires HOME or ACP_PROJECT_RUNTIME_HOME_DIR" >&2
+  exit 64
+fi
+
+mkdir -p "${WORKSPACE_DIR}/bin" "${LAUNCH_AGENTS_DIR}" "${LOG_DIR}" "$(dirname "${SUPERVISOR_PID_FILE}")"
+
+cat >"${WRAPPER_PATH}" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export ACP_PROJECT_RUNTIME_HOME_DIR='${HOME_DIR}'
+export ACP_PROJECT_RUNTIME_SOURCE_HOME='${SOURCE_HOME}'
+export ACP_PROJECT_RUNTIME_RUNTIME_HOME='${RUNTIME_HOME}'
+export ACP_PROJECT_RUNTIME_PROFILE_REGISTRY_ROOT='${PROFILE_REGISTRY_ROOT}'
+export ACP_PROJECT_RUNTIME_PROFILE_ID='${PROFILE_ID}'
+export ACP_PROJECT_RUNTIME_ENV_FILE='${ENV_FILE}'
+export ACP_PROJECT_ID='${PROFILE_ID}'
+export AGENT_PROJECT_ID='${PROFILE_ID}'
+export ACP_PROJECT_RUNTIME_PATH='${BASE_PATH}'
+export ACP_PROJECT_RUNTIME_SYNC_SCRIPT='${SYNC_SCRIPT}'
+export ACP_PROFILE_REGISTRY_ROOT='${PROFILE_REGISTRY_ROOT}'
+exec bash '${SUPERVISOR_SCRIPT}' --bootstrap-script '${BOOTSTRAP_SCRIPT}' --pid-file '${SUPERVISOR_PID_FILE}' --delay-seconds '${delay_seconds}' --interval-seconds '${interval_seconds}'
+EOF
+chmod +x "${WRAPPER_PATH}"
+
+cat >"${PLIST_PATH}" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>${LABEL}</string>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>${WRAPPER_PATH}</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>WorkingDirectory</key>
+	<string>${WORKSPACE_DIR}</string>
+	<key>StandardErrorPath</key>
+	<string>${STDERR_LOG}</string>
+	<key>StandardOutPath</key>
+	<string>${STDOUT_LOG}</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+		<key>HOME</key>
+		<string>${HOME_DIR}</string>
+		<key>PATH</key>
+		<string>${BASE_PATH}</string>
+		<key>ACP_PROFILE_REGISTRY_ROOT</key>
+		<string>${PROFILE_REGISTRY_ROOT}</string>
+	</dict>
+</dict>
+</plist>
+EOF
+
+if [[ "${ACP_PROJECT_RUNTIME_SKIP_LAUNCHCTL:-0}" == "1" ]]; then
+  printf 'LAUNCHD_INSTALL_STATUS=skipped-launchctl\n'
+  printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
+  printf 'LABEL=%s\n' "${LABEL}"
+  printf 'PLIST=%s\n' "${PLIST_PATH}"
+  printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"
+  exit 0
+fi
+
+user_domain="gui/$(id -u)"
+launchctl bootout "${user_domain}/${LABEL}" >/dev/null 2>&1 || true
+launchctl bootstrap "${user_domain}" "${PLIST_PATH}"
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if launchctl print "${user_domain}/${LABEL}" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+launchctl kickstart -k "${user_domain}/${LABEL}" >/dev/null 2>&1 || true
+
+printf 'LAUNCHD_INSTALL_STATUS=ok\n'
+printf 'PROFILE_ID=%s\n' "${PROFILE_ID}"
+printf 'LABEL=%s\n' "${LABEL}"
+printf 'PLIST=%s\n' "${PLIST_PATH}"
+printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"

package/tools/bin/issue-publish-scope-guard.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  issue-publish-scope-guard.sh --worktree <path> --base-ref <git-ref> [--issue-id <number>]
+
+Fail fast when an issue worker branch is too broad to publish safely as a single
+PR slice.
+EOF
+}
+
+worktree=""
+base_ref=""
+issue_id=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --worktree) worktree="${2:-}"; shift 2 ;;
+    --base-ref) base_ref="${2:-}"; shift 2 ;;
+    --issue-id) issue_id="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$worktree" || -z "$base_ref" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -d "$worktree" ]]; then
+  echo "missing worktree: $worktree" >&2
+  exit 1
+fi
+
+changed_files="$(
+  git -C "$worktree" diff --name-only --diff-filter=ACMR "${base_ref}...HEAD"
+)"
+
+issue_title=""
+issue_body=""
+if [[ -n "$issue_id" ]]; then
+  CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+  REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+  issue_json="$(flow_github_issue_view_json "${REPO_SLUG}" "${issue_id}" 2>/dev/null || true)"
+  if [[ -n "$issue_json" ]]; then
+    issue_title="$(jq -r '.title // ""' <<<"$issue_json" 2>/dev/null || true)"
+    issue_body="$(jq -r '.body // ""' <<<"$issue_json" 2>/dev/null || true)"
+  fi
+fi
+
+CHANGED_FILES="$changed_files" ISSUE_ID="$issue_id" ISSUE_TITLE="$issue_title" ISSUE_BODY="$issue_body" node <<'EOF'
+const files = String(process.env.CHANGED_FILES || '')
+  .split('\n')
+  .map((file) => file.trim())
+  .filter(Boolean);
+
+const issueId = String(process.env.ISSUE_ID || '').trim();
+const issueTitle = String(process.env.ISSUE_TITLE || '').trim();
+const issueBody = String(process.env.ISSUE_BODY || '').trim();
+
+const isDoc = (file) =>
+  /^openspec\//.test(file) ||
+  /^docs\//.test(file) ||
+  /^scripts\/README\.md$/.test(file) ||
+  /\.md$/i.test(file);
+
+const isTest = (file) =>
+  /(?:^|\/)__tests__\//.test(file) ||
+  /(?:^|\/)e2e\//.test(file) ||
+  /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(file);
+
+const isLocaleResource = (file) =>
+  /^packages\/i18n\/src\/resources\/[^/]+\.json$/.test(file);
+
+const isProductNonTest = (file) =>
+  !isDoc(file) &&
+  !isTest(file) &&
+  !isLocaleResource(file) &&
+  (/^apps\//.test(file) || /^packages\//.test(file));
+
+const isMobileRouteFile = (file) =>
+  /^apps\/mobile\/app\/.+\.[cm]?[jt]sx?$/.test(file) &&
+  !isTest(file);
+
+const mobileSurfaceKey = (file) => {
+  const relative = file
+    .replace(/^apps\/mobile\/app\//, '')
+    .replace(/\.[cm]?[jt]sx?$/, '');
+  const segments = relative
+    .split('/')
+    .filter(Boolean)
+    .filter((segment) => !/^\(.+\)$/.test(segment));
+  if (segments.length === 0) return relative;
+  return segments[0];
+};
+
+const isAuthCriticalProductFile = (file) =>
+  /^apps\/api\/src\/modules\/auth\//.test(file) ||
+  file === 'apps/api/src/entities/user.entity.ts' ||
+  /^apps\/api\/src\/migrations\/.*(?:Email|Phone|Auth|User).*\.[cm]?[jt]s$/.test(file) ||
+  /^apps\/api\/src\/common\/utils\/(?:phone|tenant|email|auth)[^/]*\.[cm]?[jt]s$/.test(file);
+
+const isAuthAdjacentProductFile = (file) =>
+  isAuthCriticalProductFile(file) ||
+  /^apps\/web\/src\/app\/\(auth\)\//.test(file) ||
+  /^apps\/api\/src\/modules\/organization\//.test(file);
+
+const productNonTestFiles = files.filter(isProductNonTest);
+const mobileProductFiles = productNonTestFiles.filter((file) => /^apps\/mobile\//.test(file));
+const localeResourceFiles = files.filter(isLocaleResource);
+const mobileRouteFiles = productNonTestFiles.filter(isMobileRouteFile);
+const mobileSurfaceKeys = [...new Set(mobileRouteFiles.map(mobileSurfaceKey))];
+const authCriticalTouched = productNonTestFiles.some(isAuthCriticalProductFile);
+const authMixedScopeFiles = authCriticalTouched
+  ? productNonTestFiles.filter((file) => !isAuthAdjacentProductFile(file))
+  : [];
+const openspecChangeFiles = files.filter((file) => /^openspec\/changes\//.test(file));
+const workflowRuleFiles = files.filter((file) =>
+  /^(?:AGENTS\.md|openspec\/AGENT_RULES\.md)$/.test(file),
+);
+const docsDeclaredScope =
+  /^(?:docs?|documentation)\b/i.test(issueTitle) ||
+  /^docs?\(/i.test(issueTitle) ||
+  /\b(?:docs?|documentation|openspec)[ -]?only\b/i.test(issueTitle) ||
+  /(?:^|\n)\s*(?:scope|mode|type)\s*:\s*(?:docs?|documentation|openspec)(?:[- ]only)?\b/i.test(issueBody) ||
+  /(?:^|\n)\s*(?:docs?|documentation|openspec)[ -]?only\b/i.test(issueBody);
+
+const reasons = [];
+if (productNonTestFiles.length > 14) {
+  reasons.push(`product_non_test_count=${productNonTestFiles.length} exceeds max=14`);
+}
+if (mobileProductFiles.length >= 8) {
+  reasons.push(`mobile_product_count=${mobileProductFiles.length} exceeds max=7`);
+}
+if (localeResourceFiles.length > 8 && productNonTestFiles.length >= 6) {
+  reasons.push(
+    `locale_resource_count=${localeResourceFiles.length} with product_non_test_count=${productNonTestFiles.length} exceeds mixed-scope limit`,
+  );
+}
+if (mobileRouteFiles.length > 3) {
+  reasons.push(`mobile_route_file_count=${mobileRouteFiles.length} exceeds max=3`);
+}
+if (mobileSurfaceKeys.length > 2) {
+  reasons.push(`mobile_surface_count=${mobileSurfaceKeys.length} exceeds max=2`);
+}
+if (authMixedScopeFiles.length > 0) {
+  reasons.push(
+    `auth_mixed_scope_count=${authMixedScopeFiles.length} requires a dedicated auth slice before publish`,
+  );
+}
+if (docsDeclaredScope && productNonTestFiles.length > 0) {
+  reasons.push(`docs_declared_scope_contains_product_changes=${productNonTestFiles.length}`);
+}
+if (openspecChangeFiles.length > 0 && productNonTestFiles.length > 0) {
+  reasons.push(
+    `product_and_openspec_change_mix=product:${productNonTestFiles.length},openspec_change:${openspecChangeFiles.length}`,
+  );
+}
+if (workflowRuleFiles.length > 0 && productNonTestFiles.length > 0) {
+  reasons.push(
+    `workflow_rule_files_mixed_with_product_changes=${workflowRuleFiles.length}`,
+  );
+}
+
+if (reasons.length === 0) {
+  process.stdout.write('SCOPE_GUARD_STATUS=ok\n');
+  process.stdout.write(`PRODUCT_NON_TEST_COUNT=${productNonTestFiles.length}\n`);
+  process.stdout.write(`MOBILE_PRODUCT_COUNT=${mobileProductFiles.length}\n`);
+  process.stdout.write(`LOCALE_RESOURCE_COUNT=${localeResourceFiles.length}\n`);
+  process.stdout.write(`MOBILE_ROUTE_FILE_COUNT=${mobileRouteFiles.length}\n`);
+  process.stdout.write(`MOBILE_SURFACE_COUNT=${mobileSurfaceKeys.length}\n`);
+  process.stdout.write(`AUTH_MIXED_SCOPE_COUNT=${authMixedScopeFiles.length}\n`);
+  process.exit(0);
+}
+
+const lines = [
+  `Scope guard blocked issue${issueId ? ` #${issueId}` : ''} from publishing as a single PR.`,
+  '',
+  'The branch is too broad for the current flow and should be split into a smaller slice before publish.',
+  '',
+  'Why it was blocked:',
+  ...reasons.map((reason) => `- ${reason}`),
+];
+
+if (productNonTestFiles.length > 0) {
+  lines.push('', 'Representative product files:');
+  for (const file of productNonTestFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+if (localeResourceFiles.length > 0) {
+  lines.push('', 'Locale resource files touched:');
+  for (const file of localeResourceFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+if (openspecChangeFiles.length > 0) {
+  lines.push('', 'OpenSpec change files touched:');
+  for (const file of openspecChangeFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+if (workflowRuleFiles.length > 0) {
+  lines.push('', 'Workflow or repo-rule files touched:');
+  for (const file of workflowRuleFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+if (mobileRouteFiles.length > 0) {
+  lines.push('', 'Mobile route files touched:');
+  for (const file of mobileRouteFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+if (authMixedScopeFiles.length > 0) {
+  lines.push('', 'Files that should move to a separate follow-up PR from the auth slice:');
+  for (const file of authMixedScopeFiles.slice(0, 12)) {
+    lines.push(`- ${file}`);
+  }
+}
+
+lines.push(
+  '',
+  'Required next step:',
+  '- re-run the issue as a narrower slice that stays within one primary product surface, at most two mobile route surfaces, one dedicated auth/security contract change, or one docs/OpenSpec-only branch with no product code',
+);
+
+process.stderr.write(`${lines.join('\n')}\n`);
+process.exit(42);
+EOF

package/tools/bin/issue-requires-local-workspace-install.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ISSUE_BODY="${ISSUE_BODY:-${1:-}}"
+
+ISSUE_BODY="$ISSUE_BODY" node <<'EOF'
+const body = process.env.ISSUE_BODY || '';
+const scheduled = /^\s*(?:Agent schedule|Schedule|Cadence)\s*:\s*(?:every\s+)?(\d+)\s*([mhd])\s*$/im.test(body);
+
+if (!scheduled) {
+  process.stdout.write('no\n');
+  process.exit(0);
+}
+
+if (/^\s*(?:Local workspace install|Worktree local install)\s*:\s*yes\s*$/im.test(body)) {
+  process.stdout.write('yes\n');
+  process.exit(0);
+}
+
+const installLikePatterns = [
+  /(^|\n)\s*\d+\.\s*`(?:pnpm|npm|yarn)\s+(?:install|i|ci|add|remove|rm|up|update|rebuild|dlx)\b/im,
+  /(^|\n)\s*\d+\.\s*`pnpm\s+exec\s+pod\s+install\b/im,
+  /(^|\n)\s*\d+\.\s*`(?:npx\s+pod-install|expo\s+prebuild|pod\s+install|bundle\s+install)\b/im,
+  /`(?:pnpm|npm|yarn)\s+(?:install|i|ci|add|remove|rm|up|update|rebuild|dlx)\b/im,
+  /`pnpm\s+exec\s+pod\s+install\b/im,
+  /`(?:npx\s+pod-install|expo\s+prebuild|pod\s+install|bundle\s+install)\b/im,
+];
+
+const needsLocalInstall = installLikePatterns.some((pattern) => pattern.test(body));
+process.stdout.write(needsLocalInstall ? 'yes\n' : 'no\n');
+EOF

package/tools/bin/issue-resource-class.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-shell-lib.sh"
+
+ISSUE_ID="${1:?usage: issue-resource-class.sh ISSUE_ID}"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+ADAPTER_BIN_DIR="${FLOW_SKILL_DIR}/bin"
+
+"${ADAPTER_BIN_DIR}/issue-resource-class.sh" "$ISSUE_ID"