@event4u/agent-config 2.6.0 → 2.7.0

package/scripts/agent-config

@@ -34,13 +34,89 @@ CONSUMER_ROOT="$(pwd)"
 VERSION_FILE="$PACKAGE_ROOT/package.json"
 
 usage() {
+  # Tier filter — see docs/contracts/command-surface-tiers.md.
+  # Default prints Tier-0 only; --tier=1 adds Tier-1; --tier=all adds Tier-2.
+  local tier="${1:-0}"
+
   cat <<'EOF'
 agent-config — event4u/agent-config CLI
 
 Usage:
   ./agent-config <command> [options]
+  ./agent-config --help [--tier=0|1|all]
+EOF
+
+  cat <<'EOF'
+
+Tier 0 — daily-driver (init → sync → validate → work):
+  init                       One-shot project install. Forwards to `scripts/install`
+                             with all args. Entry point for `npx @event4u/agent-config init`.
+                             Flags: --tools=<list> | --ai=<list> | --yes | --force
+  sync                       Replay agents/installed-tools.lock — re-installs any
+                             tool whose bridge marker is missing locally (ADR-008).
+                             Flags: --dry-run | --force | --project=<path>
+  validate                   Read-only drift detection on the manifest
+                             (marker missing, scope divergence, version drift).
+                             Exits 1 on drift. Flags: --quiet | --skip-version-check
+  work                       Drive the work_engine Python engine on a free-form prompt
+                             (Option-A loop; called by the /work command)
+  implement-ticket           Drive the work_engine Python engine on a ticket envelope
+                             (Option-A loop; called by the /implement-ticket command)
+  first-run                  Guided first-run setup — cost profile, settings, tooling
+  keys:install-anthropic     Install the Anthropic API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
+  keys:install-openai        Install the OpenAI API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
+  council:estimate           Pre-call council cost preview (no API call, no spend)
+                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
+  council:run                Run the council. Requires --confirm to spend.
+                             Usage: council:run <question> --output <path> --confirm
+  council:render             Re-render a saved council responses JSON to markdown
+                             Usage: council:render <responses.json>
+  help                       Show this help (default Tier-0; --tier=1|all expands)
+  --version, -V              Print package version
+EOF
+
+  if [[ "$tier" == "1" || "$tier" == "all" ]]; then
+    cat <<'EOF'
+
+Tier 1 — power-user (release shape, audit, migration):
+  update                     Update the agent_config_version pin in .agent-settings.yml
+                             Flags: --check (read-only) | --to <version> (explicit pin)
+  versions                   List available @event4u/agent-config versions
+                             on npm. Marks the current pin and latest.
+                             Flags: --offline | --limit=N | --json
+  global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
+                             Forwards to `scripts/install --global` (ADR-007).
+                             Flags: --tools=<list> | --ai=<list> | --yes | --force
+  export                     Eject a tool's canonical content into a chosen path
+                             (real file, no symlink). Idempotent; --force overrides
+                             content drift. See `./agent-config export --list`.
+                             Flags: --tool=<id> | --output=<path> | --force | --list
+  uninstall                  Remove bridge markers (project) or lockfile
+                             entries (global). Idempotent. User-deployed
+                             content under ~/.<tool>/ is preserved unless
+                             --purge is passed (destructive).
+                             Flags: --global | --tools=<list> | --dry-run
+                                    | --purge | --force | --project=<path>
+  prune                      Remove project bridge markers not declared in
+                             agents/installed-tools.lock (npm-prune style).
+                             Hard-floors when lockfile is absent.
+                             Flags: --dry-run | --json | --project=<path>
+                                    | --all-missing-lock
+  doctor                     Read-only drift report: manifest ↔ filesystem.
+                             Lists missing, modified, and foreign files.
+                             Exits 1 on drift, 2 on missing lockfile.
+                             Flags: --json | --project=<path>
+  migrate                    One-shot migration off legacy composer / npm install paths
+                             Flags: --dry-run (detect only)
+EOF
+  fi
+
+  if [[ "$tier" == "all" ]]; then
+    cat <<'EOF'
 
-Commands:
+Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
                              (pass --claude-desktop to also write user-scope config)
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
@@ -52,15 +128,8 @@ Commands:
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
-  keys:install-anthropic     Install the Anthropic API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
-  keys:install-openai        Install the OpenAI API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
-  first-run                  Guided first-run setup — cost profile, settings, tooling
-  implement-ticket           Drive the work_engine Python engine on a ticket envelope
-                             (Option-A loop; called by the /implement-ticket command)
-  work                       Drive the work_engine Python engine on a free-form prompt
-                             (Option-A loop; called by the /work command)
+  hooks:status               Print the runtime hook matrix (per-platform install + bindings)
+                             Flags: --format json|table, --strict (CI), --project-root <path>
   migrate-state              Migrate a legacy .implement-ticket-state.json file
                              to the v1 .work-state.json schema (preserves .bak)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
@@ -83,92 +152,46 @@ Commands:
   dispatch:hook              Universal hook dispatcher (Phase 7, hook-architecture-v1.md)
                              Usage: dispatch:hook --platform <name> --event <event> [--native-event <native>]
                              Reads scripts/hook_manifest.yaml and runs the resolved concern chain.
-  hooks:status               Print the runtime hook matrix (per-platform install + bindings)
-                             Flags: --format json|table, --strict (CI), --project-root <path>
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
-  council:estimate           Pre-call council cost preview (no API call, no spend)
-                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
-  council:run                Run the council. Requires --confirm to spend.
-                             Usage: council:run <question> --output <path> --confirm
-  council:render             Re-render a saved council responses JSON to markdown
-                             Usage: council:render <responses.json>
-  update                     Update the agent_config_version pin in .agent-settings.yml
-                             Flags: --check (read-only) | --to <version> (explicit pin)
-  migrate                    One-shot migration off legacy composer / npm install paths
-                             Flags: --dry-run (detect only)
-  init                       One-shot project install. Forwards to `scripts/install`
-                             with all args. Entry point for `npx @event4u/agent-config init`.
-                             Flags: --tools=<list> | --ai=<list> | --yes | --force
-  global                     Install to user-scope paths (~/.claude/, ~/.cursor/, …)
-                             Forwards to `scripts/install --global` (ADR-007).
-                             Flags: --tools=<list> | --ai=<list> | --yes | --force
-  export                     Eject a tool's canonical content into a chosen path
-                             (real file, no symlink). Idempotent; --force overrides
-                             content drift. See `./agent-config export --list`.
-                             Flags: --tool=<id> | --output=<path> | --force | --list
-  sync                       Replay agents/installed-tools.lock — re-installs any
-                             tool whose bridge marker is missing locally (ADR-008).
-                             Flags: --dry-run | --force | --project=<path>
-  validate                   Read-only drift detection on the manifest
-                             (marker missing, scope divergence, version drift).
-                             Exits 1 on drift. Flags: --quiet | --skip-version-check
-  uninstall                  Remove bridge markers (project) or lockfile
-                             entries (global). Idempotent. User-deployed
-                             content under ~/.<tool>/ is preserved unless
-                             --purge is passed (destructive).
-                             Flags: --global | --tools=<list> | --dry-run
-                                    | --purge | --force | --project=<path>
-  prune                      Remove project bridge markers not declared in
-                             agents/installed-tools.lock (npm-prune style).
-                             Hard-floors when lockfile is absent.
-                             Flags: --dry-run | --json | --project=<path>
-                                    | --all-missing-lock
-  doctor                     Read-only drift report: manifest ↔ filesystem.
-                             Lists missing, modified, and foreign files.
-                             Exits 1 on drift, 2 on missing lockfile.
-                             Flags: --json | --project=<path>
-  versions                   List available @event4u/agent-config versions
-                             on npm. Marks the current pin and latest.
-                             Flags: --offline | --limit=N | --json
-  help                       Show this help
-  --version, -V              Print package version
+EOF
+  fi
 
-Examples:
-  ./agent-config mcp:render
-  ./agent-config mcp:render --claude-desktop
-  ./agent-config mcp:check
-  ./agent-config mcp:setup
-  ./agent-config mcp:run
-  ./agent-config roadmap:progress
-  ./agent-config hooks:install
-  ./agent-config keys:install-anthropic
-  ./agent-config keys:install-openai
+  if [[ "$tier" == "0" ]]; then
+    cat <<'EOF'
+
+(Hidden: 9 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
+or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
+EOF
+  fi
+
+  cat <<'EOF'
+
+Examples (Tier 0):
+  ./agent-config init --tools=claude-code,cursor --yes
+  ./agent-config sync --dry-run
+  ./agent-config sync
+  ./agent-config validate
   ./agent-config first-run
-  ./agent-config implement-ticket --state-file .work-state.json
   ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
-  ./agent-config migrate-state
-  ./agent-config memory:lookup --types domain-invariants --key billing
-  ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
-  ./agent-config memory:check --path agents/memory
-  ./agent-config refine-ticket:detect ticket-body.txt
-  ./agent-config telemetry:status
-  ./agent-config telemetry:status --format json
-  ./agent-config telemetry:report --since 30d --top 20
-  ./agent-config telemetry:report --since 7d --format json --top 0
+  ./agent-config implement-ticket --state-file .work-state.json
+  ./agent-config keys:install-anthropic
+  ./agent-config keys:install-openai
   ./agent-config council:estimate prompt.txt
   ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
   ./agent-config council:render agents/council-sessions/out.json
-  ./agent-config init --tools=claude-code,cursor --yes
+EOF
+
+  if [[ "$tier" == "1" || "$tier" == "all" ]]; then
+    cat <<'EOF'
+
+Examples (Tier 1):
   ./agent-config global --tools=claude-code --yes
   ./agent-config global --ai=cursor,windsurf
   ./agent-config export --list
   ./agent-config export --tool=agents-md --output=AGENTS.md
   ./agent-config export --tool=copilot-instructions --output=.github/copilot-instructions.md
-  ./agent-config sync --dry-run
-  ./agent-config sync
-  ./agent-config validate
   ./agent-config uninstall --tools=cursor --dry-run
   ./agent-config uninstall --global --tools=windsurf --purge
   ./agent-config prune --dry-run
@@ -180,6 +203,33 @@ Examples:
   ./agent-config versions --json
   ./agent-config init --offline --tools=claude-code,cursor --yes
   ./agent-config update --offline --to=2.2.0
+EOF
+  fi
+
+  if [[ "$tier" == "all" ]]; then
+    cat <<'EOF'
+
+Examples (Tier 2):
+  ./agent-config mcp:render
+  ./agent-config mcp:render --claude-desktop
+  ./agent-config mcp:check
+  ./agent-config mcp:setup
+  ./agent-config mcp:run
+  ./agent-config roadmap:progress
+  ./agent-config hooks:install
+  ./agent-config migrate-state
+  ./agent-config memory:lookup --types domain-invariants --key billing
+  ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
+  ./agent-config memory:check --path agents/memory
+  ./agent-config refine-ticket:detect ticket-body.txt
+  ./agent-config telemetry:status
+  ./agent-config telemetry:status --format json
+  ./agent-config telemetry:report --since 30d --top 20
+  ./agent-config telemetry:report --since 7d --format json --top 0
+EOF
+  fi
+
+  cat <<'EOF'
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -710,7 +760,20 @@ main() {
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;
     versions)                cmd_versions "$@" ;;
-    help|--help|-h|"")        usage ;;
+    help|--help|-h|"")
+      # Optional `--tier=0|1|all` filter (default 0).
+      local tier_arg="0"
+      for arg in "$@"; do
+        case "$arg" in
+          --tier=0|--tier=1|--tier=all) tier_arg="${arg#--tier=}" ;;
+          --tier|-t) ;; # next arg
+          0|1|all)
+            # Positional after --tier/-t.
+            tier_arg="$arg" ;;
+          --all) tier_arg="all" ;;
+        esac
+      done
+      usage "$tier_arg" ;;
     --version|-V)            print_version ;;
     *)
       echo "❌  agent-config: unknown command: $cmd" >&2

package/scripts/hermetic-install.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# scripts/hermetic-install.sh — verified-offline install entrypoint.
+#
+# Phase 2 Step 5 of agents/roadmaps/road-to-distribution-maturity.md.
+# Council-revised semantic: this is a **verified-offline install**.
+# The script name keeps "hermetic" for roadmap continuity; the
+# Anthropic Phase 2 verdict requires the checksum manifest to be
+# delivered through a separate channel (not bundled in the tarball)
+# so the trust model is not circular.
+#
+# Operator brings the trust root (--gpg-key). No embedded key.
+# Unix-only (macOS + Linux). Windows is future scope per o1 verdict.
+#
+# Sub-criteria from the roadmap:
+#  (a) stages a tarball from `npm pack` or operator-supplied .tgz
+#  (b) verifies sha256sum against a separate-channel manifest +
+#      operator GPG key
+#  (c) invokes `scripts/install.py --offline --package-dir=<staging>`
+#  (d) writes additive lockfile fields under schema_version: 1
+#      (installation_mode, package_checksum, signature_verified)
+#
+# Exit codes:
+#   0   — install + verification succeeded
+#   1   — argument error
+#   2   — checksum mismatch
+#   3   — GPG verification failed
+#   4   — install.py invocation failed
+#   5   — required dependency missing
+
+set -euo pipefail
+
+# ---------------------------------------------------------------- usage
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  hermetic-install.sh --tarball <file.tgz> --manifest <file.sha256>
+                      --gpg-key <pubkey.gpg> [--package-dir <staging>]
+                      [--package-version <semver>] [--dry-run]
+
+Required:
+  --tarball         Path to the agent-config-<version>.tgz produced
+                    by `npm pack @event4u/agent-config@<version>`.
+  --manifest        Path to the separate-channel sha256 manifest.
+                    Manifest must be detached-signed by the operator
+                    key; the script verifies the signature before
+                    using the manifest for checksum comparison.
+  --gpg-key         Path to the operator-supplied GPG public key
+                    (ASCII-armored or binary). No embedded trust root.
+
+Optional:
+  --package-dir     Staging dir for the extracted tarball
+                    (default: $(mktemp -d)).
+  --package-version Override the semver written to installed.lock
+                    (default: parse package.json after extraction).
+  --dry-run         Verify everything but skip install.py invocation.
+
+Exit codes: 0 ok · 1 args · 2 checksum · 3 gpg · 4 install · 5 dep
+USAGE
+}
+
+# ---------------------------------------------------------------- deps
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "❌  missing required command: $1" >&2
+    exit 5
+  }
+}
+
+require bash
+require tar
+require gpg
+
+# Prefer sha256sum (Linux); fall back to shasum -a 256 (macOS).
+SHA256_CMD=""
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256_CMD="sha256sum"
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256_CMD="shasum -a 256"
+else
+  echo "❌  missing sha256sum / shasum" >&2
+  exit 5
+fi
+
+# ---------------------------------------------------------------- args
+
+TARBALL=""
+MANIFEST=""
+GPG_KEY=""
+PACKAGE_DIR=""
+PACKAGE_VERSION=""
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --tarball) TARBALL="$2"; shift 2 ;;
+    --manifest) MANIFEST="$2"; shift 2 ;;
+    --gpg-key) GPG_KEY="$2"; shift 2 ;;
+    --package-dir) PACKAGE_DIR="$2"; shift 2 ;;
+    --package-version) PACKAGE_VERSION="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "❌  unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$TARBALL" || -z "$MANIFEST" || -z "$GPG_KEY" ]]; then
+  echo "❌  --tarball, --manifest, --gpg-key are required" >&2
+  usage
+  exit 1
+fi
+
+for f in "$TARBALL" "$MANIFEST" "$GPG_KEY"; do
+  [[ -f "$f" ]] || { echo "❌  file not found: $f" >&2; exit 1; }
+done
+
+# ---------------------------------------------------------------- gpg
+
+# Use a throwaway GPG home so we never touch the operator's
+# real keyring. Cleanup on exit.
+GPGHOME="$(mktemp -d)"
+trap 'rm -rf "$GPGHOME"' EXIT
+export GNUPGHOME="$GPGHOME"
+
+echo "🔐  importing operator GPG key from $GPG_KEY"
+gpg --batch --quiet --import "$GPG_KEY"
+
+# Verify the manifest signature. Expect detached signature at
+# <manifest>.asc OR inline-signed manifest. Try both.
+if [[ -f "${MANIFEST}.asc" ]]; then
+  echo "🔐  verifying detached signature: ${MANIFEST}.asc"
+  gpg --batch --quiet --verify "${MANIFEST}.asc" "$MANIFEST" || {
+    echo "❌  GPG verification failed (detached)" >&2
+    exit 3
+  }
+else
+  echo "🔐  verifying inline signature on $MANIFEST"
+  gpg --batch --quiet --verify "$MANIFEST" || {
+    echo "❌  GPG verification failed (inline)" >&2
+    echo "    hint: provide ${MANIFEST}.asc as a detached signature" >&2
+    exit 3
+  }
+fi
+SIGNATURE_VERIFIED=true
+
+# ---------------------------------------------------------------- sha
+
+echo "🔍  computing tarball checksum"
+ACTUAL_SHA="$($SHA256_CMD "$TARBALL" | awk '{print $1}')"
+
+# Manifest format: lines of "<sha256>  <relative-tarball-path>".
+# Match by basename to avoid path-prefix surprises.
+TARBALL_BASE="$(basename "$TARBALL")"
+EXPECTED_SHA="$(awk -v base="$TARBALL_BASE" '
+  $2 == base || $2 == "*"base || $2 ~ "/"base"$" {print $1; exit}
+' "$MANIFEST")"
+
+if [[ -z "$EXPECTED_SHA" ]]; then
+  echo "❌  no checksum entry for $TARBALL_BASE in manifest" >&2
+  exit 2
+fi
+
+if [[ "$ACTUAL_SHA" != "$EXPECTED_SHA" ]]; then
+  echo "❌  checksum mismatch" >&2
+  echo "    expected: $EXPECTED_SHA" >&2
+  echo "    actual:   $ACTUAL_SHA" >&2
+  exit 2
+fi
+
+PACKAGE_CHECKSUM="sha256:${ACTUAL_SHA}"
+echo "✅  checksum verified: $PACKAGE_CHECKSUM"
+
+# ---------------------------------------------------------------- stage
+
+if [[ -z "$PACKAGE_DIR" ]]; then
+  PACKAGE_DIR="$(mktemp -d -t agent-config-hermetic-XXXXXX)"
+fi
+mkdir -p "$PACKAGE_DIR"
+echo "📦  staging tarball into $PACKAGE_DIR"
+tar -xzf "$TARBALL" -C "$PACKAGE_DIR"
+
+# npm pack produces a top-level `package/` directory.
+STAGED="$PACKAGE_DIR/package"
+[[ -d "$STAGED" ]] || {
+  echo "❌  staged dir missing expected 'package/' subdir: $STAGED" >&2
+  exit 4
+}
+
+if [[ -z "$PACKAGE_VERSION" ]] && [[ -f "$STAGED/package.json" ]]; then
+  # Pull the literal value bound to the "version" key, not the next
+  # quoted token on the same line (which is the package name when
+  # package.json is single-line).
+  PACKAGE_VERSION="$(
+    sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+      "$STAGED/package.json" | head -n 1
+  )"
+fi
+[[ -n "$PACKAGE_VERSION" ]] || {
+  echo "❌  could not determine package version" >&2
+  exit 4
+}
+
+# ---------------------------------------------------------------- install.py
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  echo "🟡  --dry-run: skipping install.py invocation"
+  echo "    would invoke: scripts/install.py --offline --package-dir=$STAGED"
+  echo "    installation_mode=hermetic"
+  echo "    package_checksum=$PACKAGE_CHECKSUM"
+  echo "    signature_verified=$SIGNATURE_VERIFIED"
+  exit 0
+fi
+
+# install.py is shipped inside the staged package — invoke that
+# copy, not whatever happens to be in $PWD.
+INSTALL_PY="$STAGED/scripts/install.py"
+[[ -f "$INSTALL_PY" ]] || {
+  echo "❌  install.py not found in staged package: $INSTALL_PY" >&2
+  exit 4
+}
+
+echo "🚀  invoking install.py --offline --package-dir=$STAGED"
+# Pass the hermetic metadata via environment so install.py can record
+# the additive lockfile fields without changing its CLI surface.
+AGENT_CONFIG_INSTALLATION_MODE="hermetic" \
+AGENT_CONFIG_PACKAGE_CHECKSUM="$PACKAGE_CHECKSUM" \
+AGENT_CONFIG_SIGNATURE_VERIFIED="$SIGNATURE_VERIFIED" \
+AGENT_CONFIG_PACKAGE_VERSION="$PACKAGE_VERSION" \
+python3 "$INSTALL_PY" --offline --package-dir="$STAGED" || {
+  echo "❌  install.py exited non-zero" >&2
+  exit 4
+}
+
+echo "✅  verified-offline install complete (version $PACKAGE_VERSION)"

package/scripts/install.py

@@ -2023,7 +2023,14 @@ SCOPE_SUPPORT = {
     "cline":          "both",
     "gemini-cli":     "both",
     "copilot":        "both",
-    "augment":        "both",
+    # `augment` is global-only by design: a single user-scope deploy to
+    # `~/.augment/` is the canonical surface. The package owner accepts
+    # that the full rule set exceeds Augment's 49,512-char workspace-
+    # guidelines limit — the overflow is a known, surfaced trade-off
+    # (see ADR-007 § Amendment 2026-05-13 — global-only). Project-scope
+    # installs are rejected so the per-repo `.augment/` surface stays
+    # out of the install matrix entirely.
+    "augment":        "global",
     "aider":          "both",
     "codex":          "both",
     # Phase 2.4: roocode / kilocode lifted to "both" — global deploys

package/scripts/lint_command_tiers.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Lint slash-command frontmatter for the `tier:` key.
+
+Hard-fails CI if any command under .agent-src.uncompressed/commands/
+lacks a `tier:` declaration or uses an unknown tier value. The valid
+tier set is locked by docs/contracts/command-surface-tiers.md.
+
+Hooked into `task ci` after `task lint-rule-tiers`.
+
+Exit codes:
+  0  every command declares a valid tier
+  1  one or more commands missing or using an invalid tier
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO = Path(__file__).resolve().parents[1]
+COMMANDS_DIR = REPO / ".agent-src.uncompressed" / "commands"
+# Consumer-facing projection — must also carry tier so .augment/commands/
+# (which symlinks to .agent-src/commands/) renders the tier filter.
+COMMANDS_DIR_COMPRESSED = REPO / ".agent-src" / "commands"
+
+VALID_TIERS = frozenset({"0", "1", "2"})
+
+
+def parse_tier(text: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    for line in text[4:end].splitlines():
+        if ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        if k.strip() == "tier":
+            return v.strip().strip('"').strip("'")
+    return None
+
+
+def lint(commands_dir: Path, *, quiet: bool = False) -> int:
+    """Lint a commands directory. Returns 0 on success, 1 on failure."""
+    if not commands_dir.is_dir():
+        print(
+            f"lint_command_tiers: no commands dir at {commands_dir}",
+            file=sys.stderr,
+        )
+        return 1
+
+    files = sorted(commands_dir.rglob("*.md"))
+    # Sub-AGENTS.md companions are not slash commands.
+    commands = [p for p in files if p.name != "AGENTS.md"]
+
+    if not commands:
+        print(
+            f"lint_command_tiers: no commands found under {commands_dir}",
+            file=sys.stderr,
+        )
+        return 1
+
+    missing: list[str] = []
+    invalid: list[tuple[str, str]] = []
+
+    for cmd in commands:
+        rel = cmd.relative_to(commands_dir).as_posix()
+        tier = parse_tier(cmd.read_text(encoding="utf-8"))
+        if tier is None:
+            missing.append(rel)
+        elif tier not in VALID_TIERS:
+            invalid.append((rel, tier))
+
+    if missing or invalid:
+        print(
+            f"❌  lint_command_tiers: {len(missing)} missing, "
+            f"{len(invalid)} invalid (of {len(commands)} commands)",
+            file=sys.stderr,
+        )
+        for name in missing:
+            print(f"    missing tier: {name}", file=sys.stderr)
+        for name, tier in invalid:
+            print(f"    invalid tier '{tier}': {name}", file=sys.stderr)
+        print(
+            f"    valid tiers: {sorted(VALID_TIERS)}",
+            file=sys.stderr,
+        )
+        print(
+            "    contract: docs/contracts/command-surface-tiers.md",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not quiet:
+        print(
+            f"✅  lint_command_tiers: {len(commands)} commands, "
+            f"all tier values valid"
+        )
+    return 0
+
+
+def main() -> int:
+    rc = lint(COMMANDS_DIR, quiet=QUIET)
+    # The compressed projection is the consumer-facing tree (via the
+    # .augment/commands → .agent-src/commands symlink). It must also
+    # carry tier so the surface stays uniform.
+    if COMMANDS_DIR_COMPRESSED.is_dir():
+        rc |= lint(COMMANDS_DIR_COMPRESSED, quiet=QUIET)
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/mcp_server/__init__.py

@@ -1,5 +1,10 @@
 """MCP server for agent-config — Phase 1 MVP.
 
+mcp_scope: full — local stdio access can be extended to tool execution
+under the Phase 7 wake-up triggers in `docs/contracts/mcp-cloud-scope.md`.
+The hosted Worker (`workers/mcp/`) is `mcp_scope: lite` and is
+intentionally narrower.
+
 Exposes a hand-picked subset of `.agent-src/skills/` as MCP `prompts`
 over stdio. Read-only and instructional per the A0 execution-safety
 boundary in `agents/roadmaps/road-to-mcp-server.md`. No `tools`

package/scripts/schemas/command.schema.json

@@ -12,6 +12,11 @@
       "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$",
       "$comment": "Top-level commands use the bare slug (`commit`). Nested cluster commands under `commands/<cluster>/<sub>.md` use the colon form (`council:default`) to mirror Claude Code's `/cluster:sub` rendering. Directory slug for `.claude/skills/` is the hyphenated form (`council-default`), generated by compress.py."
     },
+    "tier": {
+      "type": "integer",
+      "enum": [0, 1, 2],
+      "description": "Command-surface tier per docs/contracts/command-surface-tiers.md. 0 = daily-driver (rendered in default `./agent-config --help`), 1 = power-user (rendered with `--tier=1`), 2 = maintenance/internal (rendered only with `--tier=all`). Default for new commands is 2 — promotion is gated by ADR criteria, never by author preference."
+    },
     "description": {
       "type": "string",
       "minLength": 1,