refactor: stop narrating core's datamachine namespace in DMC AGENTS.md section (#735)

DMC's AgentsMdSections.php hand-typed core's entire `datamachine` command
surface as a static heredoc, a layer inversion: core now registers its own
reflected AGENTS.md section (data-machine#2640), and the hand-copy had already
drifted (the `datamachine analytics|logs` line was wrong — analytics moved to
data-machine-business).

- Remove the hand-typed core `datamachine ...` narration (Memory/Automation/
  Communication/Content-ops/System bullets). Core owns that section.
- Rename the section to `datamachine-code` and keep only the workspace/worktree/
  github guidance DMC rightfully owns.
- Reflect the `worktree` operation list from its dispatch `match` arms via a new
  CommandIntrospector::match_arm_pipe_list() helper, mirroring how workspace/
  github are already reflected. No hand-typed DMC command lists remain; the
  reflected list also recovers operations the literal omitted.

Refs #734

Author: chubes4

inc/Runtime/AgentsMdSections.php

@@ -83,78 +83,48 @@ private static function register_auto_generated_marker( string $wp ): void {
 
 	private static function register_datamachine_section( string $wp ): void {
 		self::register_section(
-			'AGENTS.md', 'datamachine', 10, function () use ( $wp ) {
+			'AGENTS.md', 'datamachine-code', 10, function () use ( $wp ) {
 				$workspace_path = self::resolve_workspace_path();
-				$agent_slug     = self::resolve_agent_slug();
-				$agent_suffix   = '' !== $agent_slug ? ' --agent=' . $agent_slug : '';
-				$agent_note     = '' !== $agent_slug
-					? "On this site, scope memory commands with `--agent={$agent_slug}` when reading, writing, searching, or composing agent memory."
-					: 'On multi-agent installs, pass `--agent=<slug>` to memory commands when auto-resolution is ambiguous.';
 
 				// Generate DMC's own command surface from reflection so the lists
-				// never drift from the registered truth (see #671). The fallback
-				// pipe-lists are only used if a command class is somehow
-				// unavailable in this compose context.
+				// never drift from the registered truth (see #671, #734). The
+				// fallback pipe-lists are only used if a command class is somehow
+				// unavailable in this compose context. Core's `datamachine`
+				// namespace is NOT narrated here — core registers its own
+				// reflected AGENTS.md section (data-machine#2640); hand-copying it
+				// here is a layer inversion that silently drifts (e.g. the removed
+				// `datamachine analytics` line, now owned by data-machine-business).
 				$workspace_subcmds = CommandIntrospector::pipe_list(
 					'\\DataMachineCode\\Cli\\Commands\\WorkspaceCommand',
 					'adopt|clone|list|show|path|hygiene|remove|worktree|read|write|grep|edit|git|patch|ls'
 				);
+				$worktree_subcmds  = CommandIntrospector::match_arm_pipe_list(
+					'\\DataMachineCode\\Cli\\Commands\\WorkspaceCommand',
+					'worktree',
+					'add|list|remove|prune|cleanup|cleanup-artifacts|reconcile-metadata|refresh-context|finalize|mark-cleanup-eligible'
+				);
 				$github_subcmds    = CommandIntrospector::pipe_list(
 					'\\DataMachineCode\\Cli\\Commands\\GitHubCommand',
 					'issues|pulls|repos|status|view|close|review-flow|comment'
 				);
 				return <<<MD
-## Data Machine
-
-Data Machine is your operating layer — memory, automation, and orchestration via WP-CLI.
-
-Discover the full command surface: `{$wp} datamachine --help`. The groups below are the major command families — always run `--help` on any subcommand to see its options.
-
-**Memory & Agents:** Persistent files across sessions plus agent identity management.
-- Memory paths / read / write / search / compose: `{$wp} datamachine memory paths|read|write|search|compose{$agent_suffix}`
-- Agent management: `{$wp} datamachine agent list|create|access|token|installed|install|diff` — identities, permissions, bearer tokens, portable bundles
-- Update MEMORY.md when you learn something persistent — read it first, append new info.
-- {$agent_note}
-
-**Automation:** Self-scheduling workflows that run without human intervention.
-- Flows: `{$wp} datamachine flow create|run|list` — scheduled or on-demand tasks
-- Pipelines: `{$wp} datamachine pipeline create|list` — multi-step processing chains
-- Jobs / pending actions: `{$wp} datamachine jobs list|retry|summary`, `{$wp} datamachine pending-actions` — monitor queued work and approval gates
-- Drain due work: `{$wp} datamachine drain` — run due actions until empty or budgeted
-- Discover available step types: `{$wp} datamachine step-types list`
-- Discover available handlers: `{$wp} datamachine handlers list`
-- Processed items (dedupe): `{$wp} datamachine processed-items`
-- Retention policies: `{$wp} datamachine retention`
-
-**Communication:** Chat sessions and email I/O.
-- Chat: `{$wp} datamachine chat` — multi-turn agent conversations with tool calling
-- Email: `{$wp} datamachine email` — IMAP read / SMTP reply (wired to the site's mail stack)
-
-**Content ops:** Post-level and site-wide content tooling.
-- Posts / taxonomy / blocks: `{$wp} datamachine post|taxonomy|block`
-- SEO helpers: `{$wp} datamachine alt-text|meta-description|image|link|indexnow`
-- Analytics & logs: `{$wp} datamachine analytics|logs`
-- Settings & auth: `{$wp} datamachine settings|auth`
-- External sites & handler tests: `{$wp} datamachine external|test`
-
-**Code (data-machine-code):** All code changes happen in Data Machine Code worktrees under `{$workspace_path}`. DMC owns workspace lifecycle, evidence capture, and GitHub workflow glue; file CRUD inside a worktree uses whatever tool is fastest.
+## Data Machine Code
+
+All code changes happen in Data Machine Code worktrees under `{$workspace_path}`. DMC owns workspace lifecycle, evidence capture, and GitHub workflow glue; file CRUD inside a worktree uses whatever tool is fastest. Core's `datamachine` operating layer (memory, automation, communication, content ops, system) is documented in its own AGENTS.md section — run `{$wp} datamachine --help` to discover it.
+
 - Workspace root: `{$workspace_path}`
 - **Workspace:** `{$wp} datamachine-code workspace {$workspace_subcmds}` — lifecycle (clone/adopt/list/show/path/hygiene/remove/worktree), plus the file-I/O surface you work through inside a worktree (`read`, `write`, `grep`, `edit`, `patch`, `ls`, `git`). Keeps the on-disk registry consistent and enforces the `<repo>@<slug>` handle convention.
-- **Worktrees:** `{$wp} datamachine-code workspace worktree add|list|remove|prune|cleanup|cleanup-artifacts|reconcile-metadata|refresh-context|finalize|mark-cleanup-eligible` — create isolated branches, refresh agent context, attach lifecycle metadata, and clean up safely.
+- **Worktrees:** `{$wp} datamachine-code workspace worktree {$worktree_subcmds}` — create isolated branches, refresh agent context, attach lifecycle metadata, and clean up safely.
 - **GitHub:** `{$wp} datamachine-code github {$github_subcmds}` — list/read GitHub state, manage issues and PRs, install review flows, and comment on reviews.
 - **Editing inside a worktree:** any tool. Local agents on the same disk should use native file I/O and raw `git`; routing edits through workspace abilities is ceremony, not safety.
 - **Workspace lifecycle:** use `workspace clone` for primary checkout adoption/cloning and `workspace worktree add` for isolated branches. Use the CLI `--help` output for current flags and subcommands.
 - **Primary freshness:** before using a primary checkout for investigation or verification, inspect `workspace list|show|hygiene` freshness metadata. If the primary is stale, run `workspace git pull <repo> --allow-primary-refresh` or create the worktree from an explicit remote ref with `worktree add <repo> <branch> --from=origin/<base>`. Stale primary reads require an explicit `--allow-stale-primary` opt-in. Do not clone a second top-level primary for the same remote just to get fresh code.
 - **Primary is read-only.** Never edit `<workspace>/<repo>` (no `@slug`). Safe primary refresh uses `--allow-primary-refresh`; primary commit, push, reset, and rebase require the stronger `--allow-dangerous-primary-mutation` approval. The primary tracks the deployed branch — operate on a worktree.
 - **Rule:** Never modify files under `wp-content/plugins/` or `wp-content/themes/` directly. Those paths are **read-only reference**. All code changes go through the workspace so they are tracked in git and reviewed via pull requests.
-
-**System:** `{$wp} datamachine system health|prompts|run` — site health, prompt inspection, diagnostic runs.
-
-Use `--help` on any command to discover options and subcommands.
 MD;
 			}, array(
-				'label'       => 'Data Machine',
-				'description' => 'Memory, automation, workspace, and system operations.',
+				'label'       => 'Data Machine Code',
+				'description' => 'Workspace, worktree, and GitHub operations owned by Data Machine Code.',
 				'owner'       => 'data-machine-code',
 				'freshness'   => 'snapshot',
 				'conditions'  => 'Always registered when Data Machine Code and composable memory section registration are available.',

inc/Runtime/CommandIntrospector.php

@@ -103,6 +103,105 @@ public static function pipe_list( string $command_class, string $fallback = '' )
 		return implode('|', $names);
 	}
 
+	/**
+	 * Render a `a|b|c` pipe-list of the string-literal `match` arm keys inside a
+	 * command method, in declaration order, de-duplicated.
+	 *
+	 * Some `@subcommand` methods dispatch a second operand (e.g. `workspace
+	 * worktree <op>`) through an internal `match ( $operation ) { ... }` rather
+	 * than separate annotated methods. The arm keys ARE the real operation
+	 * surface, so reflecting them keeps AGENTS.md truthful without hand-typing
+	 * the list (see Extra-Chill/data-machine-code#734).
+	 *
+	 * Falls back to the supplied default string when reflection yields nothing,
+	 * so AGENTS.md never renders an empty command line.
+	 *
+	 * @param string $command_class Fully-qualified command class name.
+	 * @param string $method        Method whose body holds the dispatch `match`.
+	 * @param string $fallback      Pipe-list to use when reflection is unavailable.
+	 * @return string
+	 */
+	public static function match_arm_pipe_list( string $command_class, string $method, string $fallback = '' ): string {
+		$keys = self::match_arm_keys($command_class, $method);
+		if ( empty($keys) ) {
+			return $fallback;
+		}
+
+		return implode('|', $keys);
+	}
+
+	/**
+	 * Extract the string-literal arm keys of the first `match` expression in a
+	 * method body, in source order and de-duplicated.
+	 *
+	 * Reads the method's source range via reflection and scans the `match (...)`
+	 * block for `'literal' =>` / `"literal" =>` arm keys (including comma-grouped
+	 * keys mapping to one result). The `default =>` arm is ignored.
+	 *
+	 * Returns an empty array when the class/method/source is unavailable, so
+	 * callers can fall back gracefully without fatals in any context.
+	 *
+	 * @param string $command_class Fully-qualified command class name.
+	 * @param string $method        Method name to inspect.
+	 * @return string[] Ordered, de-duplicated list of match arm keys.
+	 */
+	public static function match_arm_keys( string $command_class, string $method ): array {
+		if ( ! class_exists('WP_CLI_Command', false) ) {
+			return array();
+		}
+
+		// class_exists() triggers autoloading; once it returns true the
+		// ReflectionClass constructor cannot throw, so no try/catch is needed.
+		if ( ! class_exists($command_class) ) {
+			return array();
+		}
+
+		$reflection = new \ReflectionClass($command_class);
+		if ( ! $reflection->hasMethod($method) ) {
+			return array();
+		}
+
+		$reflection_method = $reflection->getMethod($method);
+		$file              = $reflection_method->getFileName();
+		$start_line        = $reflection_method->getStartLine();
+		$end_line          = $reflection_method->getEndLine();
+
+		if ( false === $file || ! is_readable($file) || $start_line < 1 || $end_line < $start_line ) {
+			return array();
+		}
+
+		$source_lines = file($file, FILE_IGNORE_NEW_LINES);
+		if ( false === $source_lines ) {
+			return array();
+		}
+
+		$body = implode("\n", array_slice($source_lines, $start_line - 1, ( $end_line - $start_line ) + 1));
+
+		// Isolate the first `match (...)` block so we don't pick up unrelated
+		// associative arrays elsewhere in the method body.
+		if ( ! preg_match('/\bmatch\s*\(/', $body, $match_pos, PREG_OFFSET_CAPTURE) ) {
+			return array();
+		}
+		$body = substr($body, (int) $match_pos[0][1]);
+
+		// Each arm key is a single- or double-quoted literal immediately
+		// preceding `=>` (comma-grouped keys each match individually).
+		if ( ! preg_match_all('/([\'"])([^\'"\\\\]+)\1\s*=>/', $body, $arm_matches) ) {
+			return array();
+		}
+
+		$keys = array();
+		foreach ( $arm_matches[2] as $key ) {
+			$key = trim($key);
+			if ( '' === $key || in_array($key, $keys, true) ) {
+				continue;
+			}
+			$keys[] = $key;
+		}
+
+		return $keys;
+	}
+
 	/**
 	 * Pull the `@subcommand <name>` value out of a PHPDoc block.
 	 *