From 169000b478a646ff5ee1d61d88f175c27d5692db Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@extrachill.com>
Date: Fri, 24 Jul 2026 08:49:37 -0400
Subject: [PATCH] Refine generated agent routing guidance

---
 lib/agents-md-guidance.sh   | 239 +++++------------------
 tests/agents-md-guidance.sh |   5 +-
 tests/homeboy-agents-md.sh  | 365 +++++-------------------------------
 3 files changed, 92 insertions(+), 517 deletions(-)

diff --git a/lib/agents-md-guidance.sh b/lib/agents-md-guidance.sh
index 0b6fa9d..9417207 100644
--- a/lib/agents-md-guidance.sh
+++ b/lib/agents-md-guidance.sh
@@ -15,14 +15,13 @@
 #   agents_md_guidance_register <section_id> <priority> <label> <description> <content>
 #   agents_md_guidance_unregister <section_id>
 #   agents_md_guidance_sync_wordpress_agent_boundaries
-#   agents_md_guidance_sync_homeboy_cli          # presence-gated on `command -v homeboy`
-#   agents_md_guidance_register_homeboy_cli      # writes a LIVE-enumeration PHP block
+#   agents_md_guidance_sync_homeboy_cli          # presence-gated on an executable Homeboy binary
+#   agents_md_guidance_register_homeboy_cli      # writes a live presence-checked PHP block
 #   agents_md_guidance_unregister_homeboy_cli
 #
-# The homeboy-cli section is generated LIVE at AGENTS.md compose time: the
-# mu-plugin callback shells out to `homeboy --help` on every compose (cached
-# briefly on the binary mtime + version), so a `homeboy upgrade` converges on
-# the next compose without requiring a wp-coding-agents sync. See issue #254.
+# The homeboy-cli callback checks the current PATH at AGENTS.md compose time, so
+# an unavailable binary contributes no stale guidance. The live CLI help remains
+# authoritative for Homeboy's complete command surface.
 #
 # Honors DRY_RUN (logs intent, makes no changes).
 
@@ -221,19 +220,23 @@ agents_md_guidance_unregister() {
 agents_md_guidance_sync_wordpress_agent_boundaries() {
   local source_content abilities_content
 
-  source_content='## WordPress Source (Read-Only Reference)
+  source_content='## WordPress Source (Direct Reference, Read-Only)
 
-These directories are **read-only reference material** — grep and read them to understand code, but never edit them directly.
+Use the installed WordPress source to verify core APIs, hooks, conventions, and runtime behavior instead of relying on assumptions. Search and read these directories directly when working on WordPress:
 
 - `wp-content/plugins/` — plugin source (read-only)
 - `wp-content/themes/` — theme source (read-only)
-- `wp-includes/` — WordPress core (read-only)'
+- `wp-includes/` — WordPress core (read-only)
+
+These paths are **read-only references**. Make code changes in the configured managed workspace, not in the installed source tree.'
 
   abilities_content='## Abilities
 
 WordPress Abilities are the universal tool surface. Plugins expose abilities through the active runtime, REST API, MCP, and chat.
 
-Inspect the active runtime tool listings and plugin-specific `--help` output before assuming what is available.'
+**Default routing**
+- Use abilities exposed by the active runtime when they match the task.
+- Inspect the active runtime tool listings and plugin-specific `--help` before assuming a capability or argument is available.'
 
   AGENTS_MD_GUIDANCE_FRESHNESS=static \
     AGENTS_MD_GUIDANCE_CONDITIONS='Registered by wp-coding-agents on managed WordPress coding-agent installations.' \
@@ -241,7 +244,7 @@ Inspect the active runtime tool listings and plugin-specific `--help` output bef
       'wordpress-source' \
       1 \
       'WordPress Source' \
-      'Generic boundaries for installed WordPress source.' \
+      'Direct-reference and read-only boundaries for installed WordPress source.' \
       "$source_content"
 
   AGENTS_MD_GUIDANCE_FRESHNESS=static \
@@ -255,21 +258,16 @@ Inspect the active runtime tool listings and plugin-specific `--help` output bef
 }
 
 # ---------------------------------------------------------------------------
-# Homeboy CLI command map (issues #208, #254)
+# Homeboy routing guidance (issues #208, #254, #298)
 #
 # homeboy is an OPTIONAL host binary. The map is strictly presence-gated:
 #   - present (`command -v homeboy` succeeds) -> emit a first-class section
-#     whose callback ENUMERATES `homeboy --help` LIVE at AGENTS.md compose
-#     time. A `homeboy upgrade` therefore converges on the next compose,
-#     with no wp-coding-agents sync required (the #254 trigger gap).
+#     whose callback verifies Homeboy is still present at compose time.
 #   - absent -> complete no-op (unregister any stale section, emit nothing).
 #
-# The command list is NEVER baked into the mu-plugin as a frozen string;
-# the previous static-bake design was the #254 defect. The PHP helper that
-# performs the live enumeration is shipped inline in the homeboy-cli
-# section block (see _agents_md_guidance_render_homeboy_live_block), with
-# a WP transient cache keyed on the homeboy binary path + mtime + version
-# so steady-state compiles are free and the cache self-heals on upgrade.
+# The generated section intentionally contains routing, ownership, safety, and
+# discovery guidance rather than a copy of `homeboy --help`. The live CLI is the
+# authoritative command map.
 # ---------------------------------------------------------------------------
 
 # agents_md_guidance_sync_homeboy_cli
@@ -279,7 +277,9 @@ Inspect the active runtime tool listings and plugin-specific `--help` output bef
 # agree on presence. When homeboy is present, registers a LIVE-enumeration
 # section block (no content is baked at setup time).
 agents_md_guidance_sync_homeboy_cli() {
-  if command -v homeboy >/dev/null 2>&1; then
+  local homeboy_path
+  homeboy_path="$(type -P homeboy 2>/dev/null || true)"
+  if [ -n "$homeboy_path" ] && [ -f "$homeboy_path" ] && [ -x "$homeboy_path" ]; then
     agents_md_guidance_register_homeboy_cli
   else
     agents_md_guidance_unregister_homeboy_cli
@@ -288,14 +288,9 @@ agents_md_guidance_sync_homeboy_cli() {
 
 # agents_md_guidance_register_homeboy_cli
 #
-# Writes a self-contained PHP block whose SectionRegistry callback shells
-# out to `homeboy --help` at compose time and parses the Commands: block in
-# PHP. The block is marker-delimited (BEGIN/END agents-md-guidance:homeboy-cli)
+# Writes a self-contained PHP block whose SectionRegistry callback verifies the
+# Homeboy binary remains available at compose time. The block is marker-delimited
 # so it is idempotent and removable by the standard unregister path.
-#
-# No homeboy output is captured at setup time — that was the #254 bug. The
-# callback is the only thing that touches homeboy, and it runs on every
-# `wp datamachine memory compose AGENTS.md`.
 agents_md_guidance_register_homeboy_cli() {
   local file
   file="$(agents_md_guidance_mu_plugin_path)" || {
@@ -313,12 +308,6 @@ agents_md_guidance_register_homeboy_cli() {
 
   agents_md_guidance_ensure_mu_plugin_file || return 1
 
-  local new_block
-  new_block="$(_agents_md_guidance_render_homeboy_live_block)" || {
-    warn "  agents_md_guidance_register_homeboy_cli: could not render live block — skipping"
-    return 1
-  }
-
   if [ "${DRY_RUN:-false}" = true ]; then
     echo -e "${BLUE}[dry-run]${NC} Would register live AGENTS.md guidance section 'homeboy-cli' in $file"
     echo -e "${BLUE}[dry-run]${NC} Block:"
@@ -354,25 +343,9 @@ agents_md_guidance_unregister_homeboy_cli() {
 # _agents_md_guidance_render_homeboy_live_block
 #
 # Emits the PHP for the homeboy-cli section block. The block is
-# self-contained: it defines two helper functions (guarded by
-# `function_exists` so re-firing the datamachine_sections action does not
-# fatally redeclare them) and then registers a SectionRegistry section
-# whose callback invokes the live enumerator.
-#
-# The helpers:
-#   wp_coding_agents_render_homeboy_cli_section()
-#       Top-level orchestrator. Resolves `homeboy` on PATH, reads
-#       `--version` and the binary mtime for the cache key, checks the WP
-#       transient cache, shells out to `homeboy --help`, hands the help
-#       text to the parser, caches the rendered markdown, and returns it.
-#       Returns '' (section contributes nothing) when homeboy is absent,
-#       shell_exec is unavailable, the binary fails, or the help text has
-#       no parseable Commands: block.
-#   wp_coding_agents_parse_homeboy_cli_help( $help )
-#       Pure parser. Faithful PHP port of the original python parser:
-#       recognizes the `Commands:` block, ends at blank line / Options:,
-#       drops the `help`/`list` meta commands, renders the same markdown
-#       shape (intro, optional "Common entrypoints", full list, footer).
+# self-contained: it defines one helper (guarded by `function_exists` so
+# re-firing the datamachine_sections action does not fatally redeclare it) and
+# registers a SectionRegistry section whose callback checks live presence.
 #
 # Quoted heredoc ('PHP_BLOCK') so PHP $variables, backticks, and ${...}
 # are emitted verbatim — bash never touches them.
@@ -402,161 +375,41 @@ _agents_md_guidance_render_homeboy_live_block() {
                 return '';
             }
 
-            // shell_exec is the safe argv form here (hard-coded `homeboy`
-            // subcommands, no user input). It can be disabled in php.ini —
-            // in that case we degrade to a no-op rather than emit a broken
-            // section.
-            if ( ! is_callable( 'shell_exec' ) ) {
-                return '';
-            }
+            return <<<'MD'
+## Homeboy
 
-            // Cache key on the Homeboy identity and this installed renderer.
-            // Homeboy upgrades change the binary signals; wp-coding-agents
-            // upgrades change the generated MU-plugin hash. Either change
-            // must re-render the complete section because the cached value
-            // includes both command output and static guidance prose.
-            $version_out = @shell_exec( escapeshellarg( $homeboy ) . ' --version 2>/dev/null' );
-            $version      = ( is_string( $version_out ) ) ? trim( $version_out ) : '';
-            $mtime        = @filemtime( $homeboy );
-            $renderer_rev = @md5_file( __FILE__ );
-            $cache_key    = 'wca_homeboy_cli_agents_md_' . md5( $homeboy . '|' . $version . '|' . ( $mtime ?: '0' ) . '|' . ( $renderer_rev ?: 'unknown' ) );
-
-            if ( is_callable( 'get_transient' ) ) {
-                $cached = get_transient( $cache_key );
-                if ( is_string( $cached ) && $cached !== '' ) {
-                    return $cached;
-                }
-            }
+Homeboy orchestrates coding agents, deterministic gates, evidence, promotion, review, releases, and deployments. Data Machine Code owns authoritative repository and worktree state; Homeboy consumes managed worktrees to execute and finalize work.
 
-            $help = @shell_exec( escapeshellarg( $homeboy ) . ' --help 2>/dev/null' );
-            if ( ! is_string( $help ) || $help === '' ) {
-                return '';
-            }
-
-            $content = wp_coding_agents_parse_homeboy_cli_help( $help );
-            if ( $content === '' ) {
-                return '';
-            }
-
-            if ( is_callable( 'set_transient' ) ) {
-                set_transient( $cache_key, $content, 3600 );
-            }
-
-            return $content;
-        }
-    }
-
-    if ( ! function_exists( 'wp_coding_agents_parse_homeboy_cli_help' ) ) {
-        function wp_coding_agents_parse_homeboy_cli_help( $help ) {
-            // Faithful PHP port of the original python parser. See
-            // lib/agents-md-guidance.sh history.
-            $commands = array();
-            $in_commands = false;
-            foreach ( preg_split( '/\r\n|\r|\n/', (string) $help ) as $raw ) {
-                $stripped = trim( $raw );
-                if ( ! $in_commands ) {
-                    if ( $stripped === 'Commands:' ) {
-                        $in_commands = true;
-                    }
-                    continue;
-                }
-
-                // The commands block ends at the first blank line or the
-                // Options: header.
-                if ( $stripped === '' || $stripped === 'Options:' || strpos( $raw, 'Options:' ) === 0 ) {
-                    break;
-                }
-
-                if ( ! preg_match( '/^\s+([A-Za-z0-9][A-Za-z0-9_-]*)\s{2,}(.+?)\s*$/', $raw, $matches ) ) {
-                    // Continuation / wrapped summary lines have no command
-                    // token; ignore them.
-                    continue;
-                }
-
-                $commands[] = array( $matches[1], trim( $matches[2] ) );
-            }
-
-            if ( ! $commands ) {
-                return '';
-            }
-
-            // `help` / `list` are meta commands; drop them from the map.
-            // The footer already tells the agent how to discover
-            // everything.
-            $skip = array( 'help' => true, 'list' => true );
-            $commands = array_values(
-                array_filter(
-                    $commands,
-                    static function ( $c ) use ( $skip ) {
-                        return ! isset( $skip[ $c[0] ] );
-                    }
-                )
-            );
-
-            if ( ! $commands ) {
-                return '';
-            }
-
-            $summaries = array();
-            foreach ( $commands as $c ) {
-                $summaries[ $c[0] ] = $c[1];
-            }
-
-            $common_order = array(
-                'status',
-                'triage',
-                'worktree',
-                'review',
-                'build',
-                'test',
-                'agent-task',
-                'runs',
-            );
-
-            $lines = array();
-            $lines[] = 'Homeboy is the host orchestrator binary — build, deploy, release, triage, test, and inspect components from the CLI. The command map below is generated live from `homeboy --help` at AGENTS.md compose time, so it always reflects the currently-installed homeboy binary.';
-
-            $common_entrypoints = array();
-            foreach ( $common_order as $name ) {
-                if ( isset( $summaries[ $name ] ) ) {
-                    $common_entrypoints[] = $name;
-                }
-            }
-            if ( $common_entrypoints ) {
-                $lines[] = '';
-                $lines[] = 'Common entrypoints:';
-                foreach ( $common_entrypoints as $name ) {
-                    $lines[] = '- `homeboy ' . $name . '` — ' . $summaries[ $name ];
-                }
-            }
-
-            $lines[] = '';
-            foreach ( $commands as $c ) {
-                $lines[] = '- `homeboy ' . $c[0] . '` — ' . $c[1];
-            }
+**Default routing**
+- One tracked change: `homeboy agent-task cook`
+- Multiple independent changes: `homeboy agent-task fanout cook-batch`
+- Review a candidate: `homeboy review`
+- Inspect runs and evidence: `homeboy runs`
+- Repeating workflows: `homeboy agent-task loop`; explicitly stateful workflows: `homeboy agent-task controller`
+- Component and runner health: `homeboy status` and `homeboy runner status`
 
-            $lines[] = '';
-            $lines[] = 'For agent work, use `homeboy agent-task cook` for one issue or reviewable PR, `homeboy agent-task fanout cook-batch` for multiple independent issues, `homeboy agent-task loop` for a named repeating workflow, and `homeboy agent-task controller` for workflows with explicit actions, events, waits, or policy state.';
-            $lines[] = 'Inspect live configuration with `homeboy config show`. Discover current agent-task providers with `homeboy agent-task providers`.';
-            $lines[] = 'Discover everything: `homeboy --help`. Drill into a command with `homeboy <command> --help`, including `homeboy config --help` and `homeboy agent-task --help`. Releases (`homeboy release`) and deploys (`homeboy deploy`) are operator actions — run them only when the user explicitly asks.';
+**Operator boundary**
+Run `homeboy release` or `homeboy deploy` only when the user explicitly asks.
 
-            return implode( "\n", $lines );
+**Discovery**
+Use `homeboy --help` and `homeboy <command> --help` for the live command contract. Inspect active configuration with `homeboy config show` and provider readiness with `homeboy agent-task providers`.
+MD;
         }
     }
 
     \DataMachine\Engine\AI\SectionRegistry::register(
         'AGENTS.md',
         'homeboy-cli',
-        34,
+        30,
         static function () {
             return wp_coding_agents_render_homeboy_cli_section();
         },
         array(
-            'label'       => 'Homeboy CLI',
-            'description' => 'Host orchestrator command map, enumerated live from \'homeboy --help\' at AGENTS.md compose time.',
+            'label'       => 'Homeboy',
+            'description' => 'Host orchestration routing, safety, and discovery guidance.',
             'owner'       => 'wp-coding-agents',
             'freshness'   => 'live',
-            'conditions'  => 'Generated live from \'homeboy --help\' at AGENTS.md compose time on hosts where the homeboy binary is installed; removed when homeboy is absent. Cached briefly via WP transient keyed on the homeboy binary mtime and version, so a `homeboy upgrade` converges on the next compose without a wp-coding-agents sync.',
+            'conditions'  => 'Registered on hosts where the homeboy binary is installed and omitted at compose time when the binary is unavailable.',
         )
     );
     // END agents-md-guidance:homeboy-cli
diff --git a/tests/agents-md-guidance.sh b/tests/agents-md-guidance.sh
index 676eb9a..4ba6484 100755
--- a/tests/agents-md-guidance.sh
+++ b/tests/agents-md-guidance.sh
@@ -304,14 +304,15 @@ namespace {
         'abilities_static' => ( \$abilities[4]['freshness'] ?? null ) === 'static',
         'source_has_core' => str_contains( \$source_content, '\`wp-includes/\`' ),
         'source_has_code' => str_contains( \$source_content, '\`wp-content/plugins/\`' ) && str_contains( \$source_content, '\`wp-content/themes/\`' ),
-        'source_has_original_intro' => str_contains( \$source_content, 'grep and read them to understand code, but never edit them directly' ),
+        'source_promotes_direct_reference' => str_contains( \$source_content, 'verify core APIs, hooks, conventions, and runtime behavior instead of relying on assumptions' ),
+        'source_keeps_installed_tree_read_only' => str_contains( \$source_content, 'Make code changes in the configured managed workspace' ),
         'abilities_has_tools' => str_contains( \$abilities_content, 'active runtime tool listings' ),
     ]);
 }
 PHP
 
 RESULT=$(php "$MIXED_SHIM")
-EXPECTED='{"source_priority":1,"abilities_priority":2,"source_owner":"wp-coding-agents","abilities_owner":"wp-coding-agents","source_static":true,"abilities_static":true,"source_has_core":true,"source_has_code":true,"source_has_original_intro":true,"abilities_has_tools":true}'
+EXPECTED='{"source_priority":1,"abilities_priority":2,"source_owner":"wp-coding-agents","abilities_owner":"wp-coding-agents","source_static":true,"abilities_static":true,"source_has_core":true,"source_has_code":true,"source_promotes_direct_reference":true,"source_keeps_installed_tree_read_only":true,"abilities_has_tools":true}'
 assert_eq "$RESULT" "$EXPECTED" "wp-coding-agents owns ordered guidance after mixed-version registration"
 
 echo
diff --git a/tests/homeboy-agents-md.sh b/tests/homeboy-agents-md.sh
index 6895ef4..464e585 100755
--- a/tests/homeboy-agents-md.sh
+++ b/tests/homeboy-agents-md.sh
@@ -1,28 +1,5 @@
 #!/bin/bash
-# tests/homeboy-agents-md.sh — Regression coverage for the presence-gated
-# Homeboy CLI command map (issues #208, #254).
-#
-# Since #254 the section is registered as a LIVE-enumeration PHP block: the
-# mu-plugin callback shells out to `homeboy --help` at AGENTS.md compose
-# time and parses the Commands: block in PHP. The command list is therefore
-# never baked into the mu-plugin at setup time.
-#
-# Invariants covered:
-#   - homeboy present  -> the `homeboy-cli` section is registered with a
-#                         callback that ENUMERATES `homeboy --help` live;
-#                         the rendered markdown matches the live binary.
-#   - homeboy absent   -> complete no-op: no section, no stub, no warning.
-#   - live refresh     -> after a `homeboy upgrade` (simulated by swapping
-#                         the stub binary's --help output and bumping its
-#                         mtime + --version), re-invoking the SAME mu-plugin
-#                         callback picks up the new command surface WITHOUT
-#                         re-running the wp-coding-agents setup/sync path.
-#                         This is the #254 regression: previously the section
-#                         was a frozen string and the trigger gap meant the
-#                         map desynced until the next `./upgrade.sh`.
-#
-# We mock `homeboy` on PATH so the test never depends on a real install and
-# the command list is deterministic.
+# tests/homeboy-agents-md.sh — Homeboy AGENTS.md routing guidance regression.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
@@ -30,8 +7,9 @@ cd "$SCRIPT_DIR"
 
 TMP=$(mktemp -d)
 trap 'rm -rf "$TMP"' EXIT
+PHP_BIN=$(command -v php)
 
-mkdir -p "$TMP/wp-content/mu-plugins"
+mkdir -p "$TMP/wp-content/mu-plugins" "$TMP/bin"
 export SITE_PATH="$TMP"
 export DRY_RUN=false
 
@@ -41,16 +19,8 @@ source "$SCRIPT_DIR/lib/common.sh"
 source "$SCRIPT_DIR/lib/agents-md-guidance.sh"
 UPDATED_ITEMS=()
 
-VERBOSE=false
-for arg in "$@"; do
-  case "$arg" in
-    --verbose|-v) VERBOSE=true ;;
-  esac
-done
-if [ "$VERBOSE" = false ]; then
-  log() { :; }
-  warn() { echo "WARN: $1" >&2; }
-fi
+log() { :; }
+warn() { echo "WARN: $1" >&2; }
 
 MU_FILE="$TMP/wp-content/mu-plugins/wp-coding-agents-agents-md.php"
 FAILED=0
@@ -67,70 +37,20 @@ assert_eq() {
   fi
 }
 
-assert_php_lint() {
-  local file="$1" name="$2"
-  if php -l "$file" >/dev/null 2>&1; then
-    echo "  ok   $name"
-  else
-    echo "  FAIL $name"
-    php -l "$file" 2>&1 | sed 's/^/    /'
-    FAILED=$((FAILED + 1))
-  fi
-}
-
-# --- Mock homeboy --------------------------------------------------------
-# A fake `homeboy --help` that mimics the real clap-rendered command table,
-# including the meta `help`/`list` commands (which must be dropped) and a
-# wrapped continuation line (which must be ignored).
-MOCKBIN="$TMP/bin"
-mkdir -p "$MOCKBIN"
-cat > "$MOCKBIN/homeboy" <<'SH'
+cat > "$TMP/bin/homeboy" <<'SH'
 #!/bin/bash
-if [ "$1" = "agent-task" ] && [ "$2" = "providers" ]; then
-  echo "codebox-provider-snapshot"
-  exit 0
-fi
-if [ "$1" = "--help" ]; then
-  cat <<'HELP'
-Headless automation for agentic software engineering workflows
-
-Usage: homeboy [OPTIONS] <COMMAND>
-
-Commands:
-  deploy    Deploy components to remote server
-  release   Plan release workflows
-  triage    Read-only attention report for components, projects, fleets, and rigs
-  status    Actionable component status overview
-  list      List available commands (alias for --help)
-  help      Print this message or the help of the given subcommand(s)
-
-Options:
-  -h, --help     Print help
-  -V, --version  Print version
-HELP
-  exit 0
-fi
 exit 0
 SH
-chmod +x "$MOCKBIN/homeboy"
+chmod +x "$TMP/bin/homeboy"
 
-# --- Present case --------------------------------------------------------
-echo "==> homeboy present: emit generated CLI command map"
-(
-  export PATH="$MOCKBIN:$PATH"
-  agents_md_guidance_sync_homeboy_cli
-)
+echo "==> homeboy present: register concise routing guidance"
+PATH="$TMP/bin:$PATH" agents_md_guidance_sync_homeboy_cli
 
-assert_php_lint "$MU_FILE" "guidance mu-plugin parses with php -l (present)"
-
-if grep -q "BEGIN agents-md-guidance:homeboy-cli" "$MU_FILE"; then
-  echo "  ok   homeboy-cli block present"
-else
-  echo "  FAIL homeboy-cli block missing"
+if ! php -l "$MU_FILE" >/dev/null 2>&1; then
+  echo "  FAIL generated guidance does not parse"
   FAILED=$((FAILED + 1))
 fi
 
-echo "==> inspect generated section via datamachine_sections action"
 SHIM="$TMP/section-shim.php"
 cat > "$SHIM" <<PHP
 <?php
@@ -142,25 +62,16 @@ namespace DataMachine\Engine\AI {
         }
     }
 }
-
 namespace {
     define( 'ABSPATH', '/' );
     function datamachine_agents_md_enabled(): bool { return true; }
     \$GLOBALS['actions'] = [];
-    function add_action( \$tag, \$callback, \$priority = 10 ) {
-        \$GLOBALS['actions'][\$tag][] = \$callback;
-    }
-    // The live enumerator uses the WP transient API for its cache. Provide
-    // no-op stubs so each invocation re-shells-out (the cache path itself is
-    // exercised separately by the cache-hit unit below).
-    function get_transient( \$k ) { return false; }
-    function set_transient( \$k, \$v, \$t ) { return true; }
+    function add_action( \$tag, \$callback, \$priority = 10 ) { \$GLOBALS['actions'][\$tag][] = \$callback; }
     require '$MU_FILE';
-    foreach ( \$GLOBALS['actions']['datamachine_sections'] ?? [] as \$callback ) {
-        \$callback();
-    }
+    foreach ( \$GLOBALS['actions']['datamachine_sections'] ?? [] as \$callback ) { \$callback(); }
     \$call = \DataMachine\Engine\AI\SectionRegistry::\$calls['homeboy-cli'] ?? null;
     \$content = \$call ? (string) call_user_func( \$call[3] ) : '';
+    if ( '1' === getenv( 'CONTENT_ONLY' ) ) { echo \$content; exit; }
     echo json_encode([
         'filename' => \$call[0] ?? null,
         'slug' => \$call[1] ?? null,
@@ -168,251 +79,61 @@ namespace {
         'label' => \$call[4]['label'] ?? null,
         'owner' => \$call[4]['owner'] ?? null,
         'freshness' => \$call[4]['freshness'] ?? null,
-        'has_live_freshness' => ( \$call[4]['freshness'] ?? '' ) === 'live',
-        'has_live_intro' => str_contains( \$content, 'generated live from \`homeboy --help\` at AGENTS.md compose time' ),
-        'no_false_refresh_prose' => ! str_contains( \$content, 'refreshes whenever homeboy is upgraded' ),
-        'has_deploy' => str_contains( \$content, '- \`homeboy deploy\` — Deploy components to remote server' ),
-        'has_release' => str_contains( \$content, '- \`homeboy release\` — Plan release workflows' ),
-        'has_triage' => str_contains( \$content, '- \`homeboy triage\` — Read-only attention report' ),
-        'has_status' => str_contains( \$content, '- \`homeboy status\` — Actionable component status overview' ),
-        'has_orchestrator_intro' => str_contains( \$content, 'Homeboy is the host orchestrator binary' ),
-        'has_common_entrypoints' => str_contains( \$content, 'Common entrypoints:' ),
-        'drops_help_meta' => ! str_contains( \$content, 'homeboy help' ),
-        'drops_list_meta' => ! str_contains( \$content, 'homeboy list' ),
-        'has_agent_task_workflow_selection' => str_contains( \$content, 'use \`homeboy agent-task cook\` for one issue or reviewable PR, \`homeboy agent-task fanout cook-batch\` for multiple independent issues, \`homeboy agent-task loop\` for a named repeating workflow, and \`homeboy agent-task controller\` for workflows with explicit actions, events, waits, or policy state' ),
-        'has_config_show' => str_contains( \$content, 'Inspect live configuration with \`homeboy config show\`' ),
-        'has_agent_task_providers' => str_contains( \$content, '\`homeboy agent-task providers\`' ),
-        'does_not_render_provider_snapshot' => ! str_contains( \$content, 'codebox-provider-snapshot' ),
-        'has_discover_footer' => str_contains( \$content, 'Discover everything: \`homeboy --help\`' ),
-        'has_per_command_footer' => str_contains( \$content, 'homeboy <command> --help' ),
-        'has_config_help' => str_contains( \$content, '\`homeboy config --help\`' ),
-        'has_agent_task_help' => str_contains( \$content, '\`homeboy agent-task --help\`' ),
+        'has_heading' => str_starts_with( \$content, '## Homeboy' ),
+        'has_boundary' => str_contains( \$content, 'Data Machine Code owns authoritative repository and worktree state' ),
+        'has_cook' => str_contains( \$content, 'homeboy agent-task cook' ),
+        'has_fanout' => str_contains( \$content, 'homeboy agent-task fanout cook-batch' ),
+        'has_review' => str_contains( \$content, 'homeboy review' ),
+        'has_runs' => str_contains( \$content, 'homeboy runs' ),
+        'has_stateful' => str_contains( \$content, 'homeboy agent-task loop' ) && str_contains( \$content, 'homeboy agent-task controller' ),
+        'has_health' => str_contains( \$content, 'homeboy status' ) && str_contains( \$content, 'homeboy runner status' ),
+        'has_operator_boundary' => str_contains( \$content, 'only when the user explicitly asks' ),
+        'has_discovery' => str_contains( \$content, 'homeboy --help' ) && str_contains( \$content, 'homeboy <command> --help' ),
+        'no_exhaustive_map' => ! str_contains( \$content, 'Common entrypoints:' ) && ! str_contains( \$content, 'Deploy components to remote server' ),
     ]);
 }
 PHP
 
-RESULT=$(PATH="$MOCKBIN:$PATH" php "$SHIM")
-EXPECTED='{"filename":"AGENTS.md","slug":"homeboy-cli","priority":34,"label":"Homeboy CLI","owner":"wp-coding-agents","freshness":"live","has_live_freshness":true,"has_live_intro":true,"no_false_refresh_prose":true,"has_deploy":true,"has_release":true,"has_triage":true,"has_status":true,"has_orchestrator_intro":true,"has_common_entrypoints":true,"drops_help_meta":true,"drops_list_meta":true,"has_agent_task_workflow_selection":true,"has_config_show":true,"has_agent_task_providers":true,"does_not_render_provider_snapshot":true,"has_discover_footer":true,"has_per_command_footer":true,"has_config_help":true,"has_agent_task_help":true}'
-assert_eq "$RESULT" "$EXPECTED" "SectionRegistry receives live Homeboy CLI map"
+RESULT=$(PATH="$TMP/bin:$PATH" php "$SHIM")
+EXPECTED='{"filename":"AGENTS.md","slug":"homeboy-cli","priority":30,"label":"Homeboy","owner":"wp-coding-agents","freshness":"live","has_heading":true,"has_boundary":true,"has_cook":true,"has_fanout":true,"has_review":true,"has_runs":true,"has_stateful":true,"has_health":true,"has_operator_boundary":true,"has_discovery":true,"no_exhaustive_map":true}'
+assert_eq "$RESULT" "$EXPECTED" "SectionRegistry receives concise Homeboy routing guidance"
 
 echo "==> re-sync with homeboy present (idempotent)"
 HASH_BEFORE=$(md5sum "$MU_FILE" | cut -d' ' -f1)
-(
-  export PATH="$MOCKBIN:$PATH"
-  agents_md_guidance_sync_homeboy_cli
-)
+PATH="$TMP/bin:$PATH" agents_md_guidance_sync_homeboy_cli
 HASH_AFTER=$(md5sum "$MU_FILE" | cut -d' ' -f1)
 assert_eq "$HASH_AFTER" "$HASH_BEFORE" "file unchanged on re-sync"
 
-# --- Live refresh (issue #254 regression) --------------------------------
-# The defining property of the live-at-compose fix: a `homeboy upgrade` that
-# changes the command surface is picked up by re-invoking the SAME mu-plugin
-# section callback — NO second wp-coding-agents sync required. The previous
-# static-bake design failed this exact scenario.
-echo "==> live refresh: simulate homeboy upgrade, re-invoke callback, no setup re-run"
-
-# Swap the stub binary to a "newer" homeboy that adds a `fuzz` command and
-# drops `triage`, and bump its version string. Also bump mtime by touching
-# the file with a future timestamp so the cache key flips even if the
-# version-keyed path were ever removed.
-cat > "$MOCKBIN/homeboy" <<'SH'
-#!/bin/bash
-if [ "$1" = "--version" ]; then
-  echo "homeboy 0.900.1+upgraded"
-  exit 0
-fi
-if [ "$1" = "--help" ]; then
-  cat <<'HELP'
-Headless automation for agentic software engineering workflows
-
-Usage: homeboy [OPTIONS] <COMMAND>
-
-Commands:
-  deploy    Deploy components to remote server
-  release   Plan release workflows
-  status    Actionable component status overview
-  fuzz      Fuzz test components
-  list      List available commands (alias for --help)
-  help      Print this message or the help of the given subcommand(s)
-
-Options:
-  -h, --help     Print help
-  -V, --version  Print version
-HELP
-  exit 0
+echo "==> live callback omits guidance when homeboy disappears"
+EMPTY_BIN="$TMP/empty-bin"
+mkdir -p "$EMPTY_BIN"
+ABSENT_RESULT=$(CONTENT_ONLY=1 PATH="$EMPTY_BIN" "$PHP_BIN" "$SHIM")
+if [ -n "$ABSENT_RESULT" ]; then
+  echo "  FAIL callback rendered guidance without homeboy: $ABSENT_RESULT"
+  FAILED=$((FAILED + 1))
+else
+  echo "  ok   callback omits guidance without homeboy"
 fi
-exit 0
-SH
-chmod +x "$MOCKBIN/homeboy"
-# BSD/macOS touch does not support GNU's `-d`; a fixed future timestamp is
-# sufficient to make the binary mtime cache key differ on every platform.
-touch -t 203001010000 "$MOCKBIN/homeboy"
-
-LIVE_SHIM="$TMP/live-shim.php"
-cat > "$LIVE_SHIM" <<PHP
-<?php
-namespace DataMachine\Engine\AI {
-    class SectionRegistry {
-        public static array \$calls = [];
-        public static function register( string \$filename, string \$slug, int \$priority, callable \$callback, array \$args = [] ): void {
-            self::\$calls[ \$slug ] = [ \$filename, \$slug, \$priority, \$callback, \$args ];
-        }
-    }
-}
-namespace {
-    define( 'ABSPATH', '/' );
-    function datamachine_agents_md_enabled(): bool { return true; }
-    \$GLOBALS['actions'] = [];
-    function add_action( \$tag, \$callback, \$priority = 10 ) {
-        \$GLOBALS['actions'][\$tag][] = \$callback;
-    }
-    function get_transient( \$k ) { return false; }
-    function set_transient( \$k, \$v, \$t ) { return true; }
-    require '$MU_FILE';
-    foreach ( \$GLOBALS['actions']['datamachine_sections'] ?? [] as \$callback ) {
-        \$callback();
-    }
-    \$call = \DataMachine\Engine\AI\SectionRegistry::\$calls['homeboy-cli'] ?? null;
-    \$content = \$call ? (string) call_user_func( \$call[3] ) : '';
-    echo json_encode([
-        'has_fuzz'        => str_contains( \$content, '- \`homeboy fuzz\` — Fuzz test components' ),
-        'has_deploy'      => str_contains( \$content, '- \`homeboy deploy\` — Deploy components to remote server' ),
-        'dropped_triage'  => ! str_contains( \$content, 'homeboy triage' ),
-        'version_reflected' => str_contains( \$content, 'homeboy fuzz' ),
-    ]);
-}
-PHP
 
-LIVE_RESULT=$(PATH="$MOCKBIN:$PATH" php "$LIVE_SHIM")
-LIVE_EXPECTED='{"has_fuzz":true,"has_deploy":true,"dropped_triage":true,"version_reflected":true}'
-assert_eq "$LIVE_RESULT" "$LIVE_EXPECTED" "live refresh picks up homeboy upgrade without setup re-run"
-
-# --- Renderer refresh (issue #288 regression) ----------------------------
-# A previous renderer cached the complete markdown using only the Homeboy
-# identity. Newly installed static guidance must not reuse that stale entry.
-echo "==> renderer refresh: stale pre-upgrade cache cannot mask new guidance"
-RENDERER_SHIM="$TMP/renderer-shim.php"
-cat > "$RENDERER_SHIM" <<PHP
-<?php
-namespace DataMachine\Engine\AI {
-    class SectionRegistry {
-        public static array \$calls = [];
-        public static function register( string \$filename, string \$slug, int \$priority, callable \$callback, array \$args = [] ): void {
-            self::\$calls[ \$slug ] = [ \$filename, \$slug, \$priority, \$callback, \$args ];
-        }
-    }
-}
-namespace {
-    define( 'ABSPATH', '/' );
-    function datamachine_agents_md_enabled(): bool { return true; }
-    \$GLOBALS['actions'] = [];
-    function add_action( \$tag, \$callback, \$priority = 10 ) {
-        \$GLOBALS['actions'][\$tag][] = \$callback;
-    }
-    function get_transient( \$k ) {
-        \$GLOBALS['requested_cache_key'] = \$k;
-        return false;
-    }
-    function set_transient( \$k, \$v, \$t ) { return true; }
-    require '$MU_FILE';
-    foreach ( \$GLOBALS['actions']['datamachine_sections'] ?? [] as \$callback ) {
-        \$callback();
-    }
-    \$call = \DataMachine\Engine\AI\SectionRegistry::\$calls['homeboy-cli'] ?? null;
-    \$content = \$call ? (string) call_user_func( \$call[3] ) : '';
-    \$homeboy = '$MOCKBIN/homeboy';
-    \$version = trim( (string) shell_exec( escapeshellarg( \$homeboy ) . ' --version 2>/dev/null' ) );
-    \$mtime = filemtime( \$homeboy );
-    \$legacy_cache_key = 'wca_homeboy_cli_agents_md_' . md5( \$homeboy . '|' . \$version . '|' . ( \$mtime ?: '0' ) );
-    echo json_encode([
-        'ignored_stale_render' => ( \$GLOBALS['requested_cache_key'] ?? '' ) !== \$legacy_cache_key,
-        'has_current_guidance' => str_contains( \$content, 'homeboy agent-task cook' ),
-    ]);
-}
-PHP
-RENDERER_RESULT=$(PATH="$MOCKBIN:$PATH" php "$RENDERER_SHIM")
-RENDERER_EXPECTED='{"ignored_stale_render":true,"has_current_guidance":true}'
-assert_eq "$RENDERER_RESULT" "$RENDERER_EXPECTED" "renderer revision invalidates pre-upgrade cached markdown"
-
-# --- Cache hit path ------------------------------------------------------
-# The transient cache must short-circuit the shell-out when a cached render
-# is present. Verify by returning a marker string from get_transient and
-# asserting the callback returns it verbatim.
-echo "==> cache hit: get_transient short-circuits the shell-out"
-CACHE_SHIM="$TMP/cache-shim.php"
-cat > "$CACHE_SHIM" <<PHP
-<?php
-namespace DataMachine\Engine\AI {
-    class SectionRegistry {
-        public static array \$calls = [];
-        public static function register( string \$filename, string \$slug, int \$priority, callable \$callback, array \$args = [] ): void {
-            self::\$calls[ \$slug ] = [ \$filename, \$slug, \$priority, \$callback, \$args ];
-        }
-    }
-}
-namespace {
-    define( 'ABSPATH', '/' );
-    function datamachine_agents_md_enabled(): bool { return true; }
-    \$GLOBALS['actions'] = [];
-    function add_action( \$tag, \$callback, \$priority = 10 ) {
-        \$GLOBALS['actions'][\$tag][] = \$callback;
-    }
-    function get_transient( \$k ) { return 'CACHED_MARKER_VALUE'; }
-    function set_transient( \$k, \$v, \$t ) { return true; }
-    require '$MU_FILE';
-    foreach ( \$GLOBALS['actions']['datamachine_sections'] ?? [] as \$callback ) {
-        \$callback();
-    }
-    \$call = \DataMachine\Engine\AI\SectionRegistry::\$calls['homeboy-cli'] ?? null;
-    \$content = \$call ? (string) call_user_func( \$call[3] ) : '';
-    echo json_encode([ 'returned_cached' => \$content === 'CACHED_MARKER_VALUE' ]);
-}
-PHP
-CACHE_RESULT=$(PATH="$MOCKBIN:$PATH" php "$CACHE_SHIM")
-CACHE_EXPECTED='{"returned_cached":true}'
-assert_eq "$CACHE_RESULT" "$CACHE_EXPECTED" "transient cache short-circuits live enumeration"
-
-# --- Absent case ---------------------------------------------------------
-echo "==> homeboy absent: complete no-op (section removed, no stub)"
-# Build a sandbox bin dir that has the coreutils the registry needs (grep,
-# mktemp, mv, cmp, chmod, python3, md5sum) but deliberately NO homeboy, then
-# point PATH at it alone. `command -v homeboy` must fail while the rest of the
-# helper still functions — proving the absence path is a true no-op, not a
-# crash, even on a host where homeboy happens to be installed elsewhere.
+echo "==> sync removes section when homeboy is absent"
 SANDBIN="$TMP/sandbin"
 mkdir -p "$SANDBIN"
 for tool in grep mktemp mv cmp chmod python3 md5sum cat sed awk rm cut stat dirname; do
   resolved="$(command -v "$tool" 2>/dev/null || true)"
   [ -n "$resolved" ] && ln -sf "$resolved" "$SANDBIN/$tool"
 done
-(
-  export PATH="$SANDBIN"
-  if command -v homeboy >/dev/null 2>&1; then
-    echo "  FAIL test setup: homeboy still resolvable on sandboxed PATH"
-    exit 1
-  fi
-  agents_md_guidance_sync_homeboy_cli
-) || FAILED=$((FAILED + 1))
+PATH="$SANDBIN" agents_md_guidance_sync_homeboy_cli
 
 if grep -q "BEGIN agents-md-guidance:homeboy-cli" "$MU_FILE"; then
-  echo "  FAIL homeboy-cli block still present when homeboy absent"
-  FAILED=$((FAILED + 1))
-else
-  echo "  ok   homeboy-cli block removed when homeboy absent"
-fi
-
-if grep -qi "homeboy" "$MU_FILE" && grep -qi "not installed\|unavailable\|stub" "$MU_FILE"; then
-  echo "  FAIL emitted an absent-homeboy stub instead of a no-op"
+  echo "  FAIL homeboy-cli block remained after absence sync"
   FAILED=$((FAILED + 1))
 else
-  echo "  ok   no absent-homeboy stub emitted"
+  echo "  ok   homeboy-cli block removed"
 fi
 
-assert_php_lint "$MU_FILE" "post-no-op file parses with php -l"
-
 echo
 if [ "$FAILED" -gt 0 ]; then
   echo "FAILED: $FAILED assertion(s)"
   exit 1
 fi
-echo "OK: all Homeboy CLI command-map assertions passed"
+echo "OK: all Homeboy AGENTS.md routing assertions passed"