Control Metalayer Loop

interface:
  display_name: "Control Metalayer Loop"
  short_description: "Control-loop harness for autonomous code agents"
  default_prompt: "Set up this repository with a control-system metalayer, policy rules, commands, and folder topology for stable autonomous agent development."

version: 1
commands:
  - id: smoke
    command: make smoke
    preconditions:
      - dependencies_installed
    on_failure: fix_environment
  - id: check
    command: make check
    preconditions:
      - smoke_passed
    on_failure: fix_static_issues
  - id: test
    command: make test
    preconditions:
      - check_passed
    on_failure: diagnose_and_retry
  - id: recover
    command: make recover
    preconditions:
      - failure_detected
    on_failure: escalate_human

version: 1
controller:
  gate_sequence:
    - smoke
    - check
    - test
  retry_budget: 2
  escalation:
    trigger: retry_budget_exhausted
    owner: human_oncall
rules:
  - id: no-merge-with-failing-checks
    type: hard
    condition: "check == fail or test == fail"
    action: block_merge
  - id: require-plan-for-long-task
    type: hard
    condition: "task_duration_minutes > 30 and plan_missing"
    action: block_execution

{
  "version": 1,
  "last_audit_at": null,
  "last_entropy_review_at": null,
  "controller_mode": "governed",
  "notes": []
}

version: 1
zones:
  product_code:
    paths:
      - src/
      - app/
      - packages/
  control_plane:
    paths:
      - .control/
      - docs/control/
      - scripts/control/
      - evals/
ownership:
  policy_owner: engineering
  command_owner: platform
  observability_owner: sre

#!/usr/bin/env bash
set -euo pipefail

if [ -x ./scripts/control/check.sh ]; then
  ./scripts/control/check.sh
  exit 0
fi

if command -v make >/dev/null 2>&1; then
  make check
  exit 0
fi

echo "No check command available for pre-commit." >&2
exit 1

#!/usr/bin/env bash
set -euo pipefail

if [ -x ./scripts/control/test.sh ]; then
  ./scripts/control/test.sh
  exit 0
fi

if command -v make >/dev/null 2>&1; then
  make test
  exit 0
fi

echo "No test command available for pre-push." >&2
exit 1

name: CLI E2E

on:
  pull_request:
  workflow_dispatch:

jobs:
  cli-e2e:
    runs-on: ubuntu-latest
    env:
      APP_CLI_BIN: ${{ vars.APP_CLI_BIN }}
      APP_CLI_VERSION_ARG: ${{ vars.APP_CLI_VERSION_ARG }}
    steps:
      - uses: actions/checkout@v4

      - name: Run CLI e2e wrapper
        run: ./scripts/control/cli_e2e.sh

name: Control Harness CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  control:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run control CI
        run: make ci

name: Control Nightly Audit

on:
  schedule:
    - cron: '0 4 * * *'
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Baseline audit
        run: scripts/audit_control.sh .
      - name: Strict audit
        run: scripts/audit_control.sh . --strict

name: Web E2E

on:
  pull_request:
  workflow_dispatch:

jobs:
  web-e2e:
    runs-on: ubuntu-latest
    env:
      APP_BASE_URL: ${{ vars.APP_BASE_URL }}
      PLAYWRIGHT_BASE_URL: ${{ vars.PLAYWRIGHT_BASE_URL }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Node dependencies (if present)
        run: |
          if [ -f package-lock.json ]; then
            npm ci
          elif [ -f package.json ]; then
            npm install
          fi

      - name: Install Playwright browser deps (if configured)
        run: |
          if [ -f playwright.config.ts ] || [ -f playwright.config.js ]; then
            npx playwright install --with-deps
          fi

      - name: Run web e2e wrapper
        run: ./scripts/control/web_e2e.sh

version: 1
metrics:
  pass_at_1:
    target: 0.70
    alert_below: 0.55
  retry_rate:
    target: 0.20
    alert_above: 0.40
  merge_cycle_time_hours:
    target: 24
    alert_above: 48
  revert_rate:
    target: 0.03
    alert_above: 0.08
  human_intervention_rate:
    target: 0.20
    alert_above: 0.40

.PHONY: smoke check test recover hooks-install web-e2e cli-e2e ci-e2e control-audit ci

smoke:
	@./scripts/control/smoke.sh

check:
	@./scripts/control/check.sh

test:
	@./scripts/control/test.sh

recover:
	@if [ -x ./scripts/control/recover.sh ]; then ./scripts/control/recover.sh; else echo "recover primitive not installed"; exit 2; fi

hooks-install:
	@if [ -x ./scripts/control/install_hooks.sh ]; then ./scripts/control/install_hooks.sh; else echo "hooks primitive not installed"; exit 2; fi

web-e2e:
	@if [ -x ./scripts/control/web_e2e.sh ]; then ./scripts/control/web_e2e.sh; else echo "web primitive not installed"; exit 2; fi

cli-e2e:
	@if [ -x ./scripts/control/cli_e2e.sh ]; then ./scripts/control/cli_e2e.sh; else echo "cli primitive not installed"; exit 2; fi

control-audit:
	@./scripts/audit_control.sh .

ci: smoke check test

ci-e2e: ci web-e2e cli-e2e

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "tests/e2e/web",
  timeout: 45_000,
  use: {
    baseURL: process.env.PLAYWRIGHT_BASE_URL || process.env.APP_BASE_URL || "http://127.0.0.1:3000",
    trace: "retain-on-failure",
  },
  reporter: [["line"]],
});

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: scripts/audit_control.sh [repo_path] [--strict]

Audit repository for control metalayer artifacts.
USAGE
}

repo_path="."
strict=0

while [ $# -gt 0 ]; do
  case "$1" in
    --strict)
      strict=1
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      if [ "$repo_path" != "." ]; then
        echo "error: multiple repo paths provided" >&2
        exit 1
      fi
      repo_path="$1"
      ;;
  esac
  shift
done

if [ ! -d "$repo_path" ]; then
  echo "error: repo path not found: $repo_path" >&2
  exit 1
fi

repo_path=$(cd "$repo_path" && pwd)
failures=0

ok() { echo "[ok]      $1"; }
fail() {
  echo "[missing] $1"
  failures=$((failures + 1))
}

check_file() {
  local rel="$1"
  if [ -f "$repo_path/$rel" ]; then
    ok "$rel"
  else
    fail "$rel"
  fi
}

check_contains() {
  local rel="$1"
  local pattern="$2"
  local label="$3"
  local f="$repo_path/$rel"
  if [ ! -f "$f" ]; then
    fail "$label (file missing: $rel)"
    return
  fi
  if grep -Eq "$pattern" "$f"; then
    ok "$label"
  else
    fail "$label"
  fi
}

check_hooks_path() {
  if [ ! -d "$repo_path/.git" ]; then
    ok "git hooks path check skipped (not a git repo)"
    return
  fi
  local hooks_path
  hooks_path=$(git -C "$repo_path" config --get core.hooksPath || true)
  if [ "$hooks_path" = ".githooks" ]; then
    ok "git core.hooksPath configured"
  else
    fail "git core.hooksPath configured (.githooks expected)"
  fi
}

echo "Auditing control metalayer: $repo_path"
echo

baseline=(
  "AGENTS.md"
  "PLANS.md"
  "METALAYER.md"
  "Makefile.control"
  "scripts/audit_control.sh"
  "scripts/control/smoke.sh"
  "scripts/control/check.sh"
  "scripts/control/test.sh"
  "docs/control/ARCHITECTURE.md"
  "docs/control/OBSERVABILITY.md"
  ".github/workflows/control-harness.yml"
)

for rel in "${baseline[@]}"; do
  check_file "$rel"
done

echo
check_contains "AGENTS.md" "Harness Commands|Control Commands" "AGENTS.md command section"
check_contains "METALAYER.md" "Setpoints" "METALAYER setpoint section"
check_contains "Makefile.control" "^control-audit:" "Makefile.control control-audit target"
check_contains ".github/workflows/control-harness.yml" "make ci" "control harness workflow invokes make ci"

if [ "$strict" -eq 1 ]; then
  echo
  strict_files=(
    ".control/policy.yaml"
    ".control/commands.yaml"
    ".control/topology.yaml"
    ".control/state.json"
    "docs/control/CONTROL_LOOP.md"
    "evals/control-metrics.yaml"
    "scripts/control/install_hooks.sh"
    ".githooks/pre-commit"
    ".githooks/pre-push"
    "scripts/control/recover.sh"
    "scripts/control/web_e2e.sh"
    "scripts/control/cli_e2e.sh"
    "tests/e2e/web/smoke.spec.ts"
    "tests/e2e/cli/smoke.sh"
    "playwright.config.ts"
    ".github/workflows/web-e2e.yml"
    ".github/workflows/cli-e2e.yml"
    ".github/workflows/control-nightly.yml"
  )
  for rel in "${strict_files[@]}"; do
    check_file "$rel"
  done
  check_hooks_path
fi

echo
if [ "$failures" -gt 0 ]; then
  echo "Control audit failed: $failures issue(s)."
  exit 1
fi

echo "Control audit passed."

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ -n "${CONTROL_CHECK_CMD:-}" ]; then
  eval "$CONTROL_CHECK_CMD"
  exit 0
fi

if [ -f Cargo.toml ] && command -v cargo >/dev/null 2>&1; then
  cargo clippy --all-targets --all-features -- -D warnings
  exit 0
fi

if [ -f package.json ] && command -v npm >/dev/null 2>&1; then
  npm run -s lint
  npm run -s typecheck || true
  exit 0
fi

if [ -f pyproject.toml ]; then
  if command -v ruff >/dev/null 2>&1; then
    ruff check .
  fi
  if command -v mypy >/dev/null 2>&1; then
    mypy .
  fi
  exit 0
fi

echo "No check command detected. Set CONTROL_CHECK_CMD."
exit 1

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ -n "${CONTROL_CLI_E2E_CMD:-}" ]; then
  eval "$CONTROL_CLI_E2E_CMD"
  exit 0
fi

if [ -x ./tests/e2e/cli/smoke.sh ]; then
  ./tests/e2e/cli/smoke.sh
  exit 0
fi

cli_bin="${APP_CLI_BIN:-}"
if [ -n "$cli_bin" ]; then
  "$cli_bin" --help >/dev/null
  echo "CLI reachable: $cli_bin"
  exit 0
fi

echo "No CLI e2e command configured. Set CONTROL_CLI_E2E_CMD or APP_CLI_BIN." >&2
exit 1

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ ! -d .git ]; then
  echo "error: not a git repository: $root" >&2
  exit 1
fi

mkdir -p .githooks
chmod +x .githooks/pre-commit .githooks/pre-push

git config core.hooksPath .githooks
echo "Git hooks installed: core.hooksPath=.githooks"

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

echo "Recovery workflow"
echo "1) Re-run smoke"
echo "2) Re-run check"
echo "3) Capture failing tests and open escalation if needed"

./scripts/control/smoke.sh || true
./scripts/control/check.sh || true
./scripts/control/test.sh || true

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ -n "${CONTROL_SMOKE_CMD:-}" ]; then
  eval "$CONTROL_SMOKE_CMD"
  exit 0
fi

if [ -f Cargo.toml ] && command -v cargo >/dev/null 2>&1; then
  cargo check --quiet
  exit 0
fi

if [ -f package.json ] && command -v npm >/dev/null 2>&1; then
  npm run -s build || npm run -s smoke
  exit 0
fi

if [ -f pyproject.toml ] && command -v pytest >/dev/null 2>&1; then
  pytest -q -k smoke || pytest -q -k "not integration and not e2e"
  exit 0
fi

echo "No smoke command detected. Set CONTROL_SMOKE_CMD."
exit 1

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ -n "${CONTROL_TEST_CMD:-}" ]; then
  eval "$CONTROL_TEST_CMD"
  exit 0
fi

if [ -f Cargo.toml ] && command -v cargo >/dev/null 2>&1; then
  cargo test --quiet
  exit 0
fi

if [ -f package.json ] && command -v npm >/dev/null 2>&1; then
  npm run -s test
  exit 0
fi

if [ -f pyproject.toml ] && command -v pytest >/dev/null 2>&1; then
  pytest -q
  exit 0
fi

echo "No test command detected. Set CONTROL_TEST_CMD."
exit 1

#!/usr/bin/env bash
set -euo pipefail

root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
cd "$root"

if [ -n "${CONTROL_WEB_E2E_CMD:-}" ]; then
  eval "$CONTROL_WEB_E2E_CMD"
  exit 0
fi

base_url="${APP_BASE_URL:-${PLAYWRIGHT_BASE_URL:-}}"

if [ -f package.json ] && command -v npm >/dev/null 2>&1; then
  if node -e 'const p=require("./package.json"); process.exit(p.scripts&&p.scripts["e2e:web"]?0:1)' >/dev/null 2>&1; then
    npm run -s e2e:web
    exit 0
  fi
fi

if [ -f playwright.config.ts ] && command -v npx >/dev/null 2>&1; then
  npx playwright test tests/e2e/web --reporter=line
  exit 0
fi

if [ -n "$base_url" ] && command -v curl >/dev/null 2>&1; then
  curl -fsS "$base_url" >/dev/null
  echo "Web deployment reachable: $base_url"
  exit 0
fi

echo "No web e2e command configured. Set CONTROL_WEB_E2E_CMD or APP_BASE_URL, or install Playwright config/tests." >&2
exit 1

#!/usr/bin/env bash
set -euo pipefail

cli_bin="${APP_CLI_BIN:-}"
if [ -z "$cli_bin" ]; then
  echo "Set APP_CLI_BIN for CLI E2E smoke." >&2
  exit 1
fi

"$cli_bin" --help >/dev/null
if [ -n "${APP_CLI_VERSION_ARG:-}" ]; then
  "$cli_bin" "$APP_CLI_VERSION_ARG" >/dev/null
fi

echo "CLI smoke test passed for $cli_bin"

import { expect, test } from "@playwright/test";

test("home page loads", async ({ page }) => {
  await page.goto("/");
  await expect(page.locator("body")).toBeVisible();
});

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: audit_control.sh [repo_path] [--strict]

Audit repository for control metalayer artifacts.
USAGE
}

repo_path="."
strict=0

while [ $# -gt 0 ]; do
  case "$1" in
    --strict)
      strict=1
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      if [ "$repo_path" != "." ]; then
        echo "error: multiple repo paths provided" >&2
        exit 1
      fi
      repo_path="$1"
      ;;
  esac
  shift
done

if [ ! -d "$repo_path" ]; then
  echo "error: repo path not found: $repo_path" >&2
  exit 1
fi

repo_path=$(cd "$repo_path" && pwd)
failures=0

ok() { echo "[ok]      $1"; }
fail() {
  echo "[missing] $1"
  failures=$((failures + 1))
}

check_file() {
  local rel="$1"
  if [ -f "$repo_path/$rel" ]; then
    ok "$rel"
  else
    fail "$rel"
  fi
}

check_contains() {
  local rel="$1"
  local pattern="$2"
  local label="$3"
  local f="$repo_path/$rel"
  if [ ! -f "$f" ]; then
    fail "$label (file missing: $rel)"
    return
  fi
  if grep -Eq "$pattern" "$f"; then
    ok "$label"
  else
    fail "$label"
  fi
}

check_hooks_path() {
  if [ ! -d "$repo_path/.git" ]; then
    ok "git hooks path check skipped (not a git repo)"
    return
  fi
  local hooks_path
  hooks_path=$(git -C "$repo_path" config --get core.hooksPath || true)
  if [ "$hooks_path" = ".githooks" ]; then
    ok "git core.hooksPath configured"
  else
    fail "git core.hooksPath configured (.githooks expected)"
  fi
}

echo "Auditing control metalayer: $repo_path"
echo

baseline=(
  "AGENTS.md"
  "PLANS.md"
  "METALAYER.md"
  "Makefile.control"
  "scripts/audit_control.sh"
  "scripts/control/smoke.sh"
  "scripts/control/check.sh"
  "scripts/control/test.sh"
  "docs/control/ARCHITECTURE.md"
  "docs/control/OBSERVABILITY.md"
  ".github/workflows/control-harness.yml"
)

for rel in "${baseline[@]}"; do
  check_file "$rel"
done

echo
check_contains "AGENTS.md" "Harness Commands|Control Commands" "AGENTS.md command section"
check_contains "METALAYER.md" "Setpoints" "METALAYER setpoint section"
check_contains "Makefile.control" "^control-audit:" "Makefile.control control-audit target"
check_contains ".github/workflows/control-harness.yml" "make ci" "control harness workflow invokes make ci"

if [ "$strict" -eq 1 ]; then
  echo
  strict_files=(
    ".control/policy.yaml"
    ".control/commands.yaml"
    ".control/topology.yaml"
    ".control/state.json"
    "docs/control/CONTROL_LOOP.md"
    "evals/control-metrics.yaml"
    "scripts/control/install_hooks.sh"
    ".githooks/pre-commit"
    ".githooks/pre-push"
    "scripts/control/recover.sh"
    "scripts/control/web_e2e.sh"
    "scripts/control/cli_e2e.sh"
    "tests/e2e/web/smoke.spec.ts"
    "tests/e2e/cli/smoke.sh"
    "playwright.config.ts"
    ".github/workflows/web-e2e.yml"
    ".github/workflows/cli-e2e.yml"
    ".github/workflows/control-nightly.yml"
  )
  for rel in "${strict_files[@]}"; do
    check_file "$rel"
  done
  check_hooks_path
fi

echo
if [ "$failures" -gt 0 ]; then
  echo "Control audit failed: $failures issue(s)."
  exit 1
fi

echo "Control audit passed."

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage: bootstrap_control.sh [repo_path] [--force]

Install baseline control metalayer templates into a target repository.
USAGE
}

repo_path="."
force=0

while [ $# -gt 0 ]; do
  case "$1" in
    --force)
      force=1
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      if [ "$repo_path" != "." ]; then
        echo "error: multiple repo paths provided" >&2
        exit 1
      fi
      repo_path="$1"
      ;;
  esac
  shift
done

if [ ! -d "$repo_path" ]; then
  echo "error: repo path not found: $repo_path" >&2
  exit 1
fi

repo_path=$(cd "$repo_path" && pwd)
script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
skill_dir=$(cd "$script_dir/.." && pwd)
template_dir="$skill_dir/assets/templates"

copy_template() {
  local rel="$1"
  local src="$template_dir/$rel"
  local dst="$repo_path/$rel"

  if [ ! -f "$src" ]; then
    echo "[error] missing template: $rel" >&2
    exit 1
  fi

  mkdir -p "$(dirname "$dst")"

  if [ -f "$dst" ] && [ "$force" -ne 1 ]; then
    echo "[skip]  $rel"
    return
  fi

  cp "$src" "$dst"
  echo "[write] $rel"
}

baseline=(
  "AGENTS.md"
  "PLANS.md"
  "METALAYER.md"
  "Makefile.control"
  "scripts/audit_control.sh"
  "scripts/control/smoke.sh"
  "scripts/control/check.sh"
  "scripts/control/test.sh"
  "docs/control/ARCHITECTURE.md"
  "docs/control/OBSERVABILITY.md"
  ".github/workflows/control-harness.yml"
)

for rel in "${baseline[@]}"; do
  copy_template "$rel"
done

makefile="$repo_path/Makefile"
if [ ! -f "$makefile" ]; then
  cat > "$makefile" <<'MAKEFILE'
-include Makefile.control
MAKEFILE
  echo "[write] Makefile"
elif ! grep -Eq '(^|[[:space:]])-?include[[:space:]]+Makefile\.control([[:space:]]|$)' "$makefile"; then
  cat >> "$makefile" <<'MAKEFILE'

# Control metalayer targets
-include Makefile.control
MAKEFILE
  echo "[update] Makefile"
else
  echo "[skip]  Makefile already includes Makefile.control"
fi

chmod +x \
  "$repo_path/scripts/audit_control.sh" \
  "$repo_path/scripts/control/smoke.sh" \
  "$repo_path/scripts/control/check.sh" \
  "$repo_path/scripts/control/test.sh"

echo
echo "Baseline control metalayer bootstrap complete."
echo "Next: run python3 scripts/control_wizard.py audit $repo_path"

#!/usr/bin/env python3
"""Typer wizard for control metalayer setup in agent-operated repositories."""

from __future__ import annotations

import subprocess
from enum import Enum
from pathlib import Path
from typing import Dict, Iterable, List, Tuple

try:
    import typer
except ImportError as exc:  # pragma: no cover - import guard
    raise SystemExit(
        "Missing dependency: typer. Install with `python3 -m pip install typer`."
    ) from exc

app = typer.Typer(help="Control metalayer wizard for agentic repository setup.")
primitive_app = typer.Typer(help="Manage control primitives.")
app.add_typer(primitive_app, name="primitive")

SCRIPT_DIR = Path(__file__).resolve().parent
SKILL_DIR = SCRIPT_DIR.parent
TEMPLATE_DIR = SKILL_DIR / "assets" / "templates"
BOOTSTRAP_SCRIPT = SCRIPT_DIR / "bootstrap_control.sh"
AUDIT_SCRIPT = SCRIPT_DIR / "audit_control.sh"

BASELINE_FILES: Tuple[str, ...] = (
    "AGENTS.md",
    "PLANS.md",
    "METALAYER.md",
    "Makefile.control",
    "scripts/audit_control.sh",
    "scripts/control/smoke.sh",
    "scripts/control/check.sh",
    "scripts/control/test.sh",
    "docs/control/ARCHITECTURE.md",
    "docs/control/OBSERVABILITY.md",
    ".github/workflows/control-harness.yml",
)


class Profile(str, Enum):
    baseline = "baseline"
    governed = "governed"
    autonomous = "autonomous"


class Primitive(str, Enum):
    policy = "policy"
    commands = "commands"
    topology = "topology"
    loop = "loop"
    metrics = "metrics"
    hooks = "hooks"
    recovery = "recovery"
    state = "state"
    nightly = "nightly"
    web = "web"
    cli = "cli"


PRIMITIVE_FILES: Dict[Primitive, Tuple[str, ...]] = {
    Primitive.policy: (".control/policy.yaml",),
    Primitive.commands: (".control/commands.yaml",),
    Primitive.topology: (".control/topology.yaml",),
    Primitive.loop: ("docs/control/CONTROL_LOOP.md",),
    Primitive.metrics: ("evals/control-metrics.yaml",),
    Primitive.hooks: (
        "scripts/control/install_hooks.sh",
        ".githooks/pre-commit",
        ".githooks/pre-push",
    ),
    Primitive.recovery: ("scripts/control/recover.sh",),
    Primitive.state: (".control/state.json",),
    Primitive.nightly: (".github/workflows/control-nightly.yml",),
    Primitive.web: (
        "scripts/control/web_e2e.sh",
        ".github/workflows/web-e2e.yml",
        "tests/e2e/web/smoke.spec.ts",
        "playwright.config.ts",
    ),
    Primitive.cli: (
        "scripts/control/cli_e2e.sh",
        ".github/workflows/cli-e2e.yml",
        "tests/e2e/cli/smoke.sh",
    ),
}

GOVERNED_PRIMITIVES: Tuple[Primitive, ...] = (
    Primitive.policy,
    Primitive.commands,
    Primitive.topology,
    Primitive.loop,
    Primitive.metrics,
    Primitive.hooks,
)

AUTONOMOUS_PRIMITIVES: Tuple[Primitive, ...] = (
    *GOVERNED_PRIMITIVES,
    Primitive.recovery,
    Primitive.state,
    Primitive.nightly,
    Primitive.web,
    Primitive.cli,
)


def _resolve_repo(path: Path) -> Path:
    repo = path.expanduser().resolve()
    if not repo.exists() or not repo.is_dir():
        typer.secho(f"error: repo path does not exist: {repo}", fg=typer.colors.RED, err=True)
        raise typer.Exit(code=2)
    return repo


def _run(script: Path, args: List[str]) -> None:
    if not script.exists():
        typer.secho(f"error: script not found: {script}", fg=typer.colors.RED, err=True)
        raise typer.Exit(code=2)
    result = subprocess.run([str(script), *args], check=False)
    if result.returncode != 0:
        raise typer.Exit(code=result.returncode)


def _copy_template(relative_path: str, repo: Path, force: bool) -> str:
    source = TEMPLATE_DIR / relative_path
    target = repo / relative_path

    if not source.exists():
        typer.secho(f"error: missing template: {source}", fg=typer.colors.RED, err=True)
        raise typer.Exit(code=2)

    target.parent.mkdir(parents=True, exist_ok=True)
    if target.exists() and not force:
        return "skip"

    target.write_bytes(source.read_bytes())
    if target.suffix == ".sh" or relative_path.startswith(".githooks/"):
        target.chmod(0o755)
    return "write"


def _activate_hooks(repo: Path) -> None:
    install_script = repo / "scripts" / "control" / "install_hooks.sh"
    if not install_script.exists():
        return
    result = subprocess.run([str(install_script)], cwd=str(repo), check=False)
    if result.returncode != 0:
        typer.secho(
            "  [warn] failed to activate git hooks automatically; run scripts/control/install_hooks.sh manually.",
            fg=typer.colors.YELLOW,
        )


def _apply_primitives(repo: Path, primitives: Iterable[Primitive], force: bool) -> None:
    for primitive in primitives:
        typer.secho(f"\n[{primitive.value}]", fg=typer.colors.CYAN)
        for relative_path in PRIMITIVE_FILES[primitive]:
            state = _copy_template(relative_path, repo, force)
            label = "write" if state == "write" else "skip "
            typer.echo(f"  [{label}] {relative_path}")
        if primitive == Primitive.hooks:
            _activate_hooks(repo)


@app.command()
def init(
    repo_path: Path = typer.Argument(Path("."), help="Target repository path."),
    profile: Profile = typer.Option(Profile.governed, "--profile", "-p", help="Setup profile."),
    force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
) -> None:
    """Initialize control metalayer in a repository."""
    repo = _resolve_repo(repo_path)
    typer.secho(f"Initializing control metalayer in {repo}", fg=typer.colors.GREEN)

    args = [str(repo)]
    if force:
        args.append("--force")
    _run(BOOTSTRAP_SCRIPT, args)

    if profile == Profile.baseline:
        return

    primitives = GOVERNED_PRIMITIVES if profile == Profile.governed else AUTONOMOUS_PRIMITIVES
    _apply_primitives(repo, primitives, force)
    typer.secho("\nInitialization complete.", fg=typer.colors.GREEN)


@app.command()
def audit(
    repo_path: Path = typer.Argument(Path("."), help="Target repository path."),
    strict: bool = typer.Option(False, "--strict", help="Require governed/autonomous primitives."),
) -> None:
    """Run control metalayer audit."""
    repo = _resolve_repo(repo_path)
    args = [str(repo)]
    if strict:
        args.append("--strict")
    _run(AUDIT_SCRIPT, args)


@app.command()
def status(
    repo_path: Path = typer.Argument(Path("."), help="Target repository path."),
) -> None:
    """Show baseline and primitive coverage."""
    repo = _resolve_repo(repo_path)
    typer.secho(f"Control metalayer status for {repo}", fg=typer.colors.GREEN)
    typer.echo()

    baseline_present = sum(1 for rel in BASELINE_FILES if (repo / rel).exists())
    typer.echo(f"baseline: {baseline_present}/{len(BASELINE_FILES)}")
    for rel in BASELINE_FILES:
        marker = "OK " if (repo / rel).exists() else "MISS"
        typer.echo(f"  [{marker}] {rel}")

    typer.echo()
    typer.echo("primitives:")
    for primitive in Primitive:
        files = PRIMITIVE_FILES[primitive]
        present = sum(1 for rel in files if (repo / rel).exists())
        marker = "OK " if present == len(files) else "PARTIAL" if present > 0 else "MISS"
        typer.echo(f"  [{marker}] {primitive.value}: {present}/{len(files)}")


@primitive_app.command("list")
def primitive_list() -> None:
    """List primitive names and files."""
    for primitive in Primitive:
        typer.echo(primitive.value)
        for rel in PRIMITIVE_FILES[primitive]:
            typer.echo(f"  - {rel}")


@primitive_app.command("add")
def primitive_add(
    primitives: List[Primitive] = typer.Argument(..., help="Primitive names to add."),
    repo: Path = typer.Option(Path("."), "--repo", "-r", help="Target repository path."),
    force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
) -> None:
    """Add selected primitives incrementally."""
    repo_path = _resolve_repo(repo)
    _apply_primitives(repo_path, primitives, force)
    typer.secho("\nPrimitive update complete.", fg=typer.colors.GREEN)


if __name__ == "__main__":
    app()