refactor: make AGENTS workspace policy filterable (#760)

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

inc/Runtime/AgentsMdSections.php

@@ -92,7 +92,9 @@ 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-code', 10, function () use ( $wp ) {
-				$workspace_path = self::resolve_workspace_path();
+				$workspace_path           = self::resolve_workspace_path();
+				$workspace_policy_intro   = self::render_workspace_policy_intro($workspace_path);
+				$workspace_policy_section = self::render_workspace_policy_section($workspace_path, $wp);
 
 				// Generate DMC's own command surface from reflection so the lists
 				// never drift from the registered truth (see #671, #734). The
@@ -118,17 +120,15 @@ private static function register_datamachine_section( string $wp ): void {
 				return <<<MD
 ## 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_policy_intro}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 {$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.
+{$workspace_policy_section}
 MD;
 			}, array(
 				'label'       => 'Data Machine Code',
@@ -140,6 +140,49 @@ private static function register_datamachine_section( string $wp ): void {
 		);
 	}
 
+	private static function render_workspace_policy_intro( string $workspace_path ): string {
+		$default = "All code changes happen in Data Machine Code worktrees under `{$workspace_path}`. ";
+
+		/**
+		 * Filters the site-owned workspace policy sentence rendered before DMC command facts.
+		 *
+		 * @param string $default        Default policy markdown.
+		 * @param string $workspace_path Resolved DMC workspace root.
+		 */
+		$filtered = apply_filters('datamachine_code_workspace_policy_intro', $default, $workspace_path);
+		if ( ! is_string($filtered) ) {
+			return $default;
+		}
+
+		return $filtered;
+	}
+
+	private static function render_workspace_policy_section( string $workspace_path, string $wp ): string {
+		$default = <<<'MD'
+- **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.
+MD;
+
+		/**
+		 * Filters site-owned workspace policy guidance rendered in AGENTS.md.
+		 *
+		 * Data Machine Code owns the workspace command facts above. Callers own
+		 * local policy, such as primary checkout mutability and read-only source
+		 * directory rules. Return an empty string to omit the policy block.
+		 *
+		 * @param string $default        Default policy markdown.
+		 * @param string $workspace_path Resolved DMC workspace root.
+		 * @param string $wp             WP-CLI command prefix.
+		 */
+		$filtered = apply_filters('datamachine_code_workspace_policy_section', $default, $workspace_path, $wp);
+		if ( ! is_string($filtered) ) {
+			return $default;
+		}
+
+		return trim($filtered);
+	}
+
 	private static function register_workspace_inventory_section( string $wp ): void {
 		self::register_section(
 			'AGENTS.md', 'workspace-inventory', 15, function () use ( $wp ) {

tests/smoke-agents-md-sections.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DataMachine\Engine\AI {
+	final class MemoryFileRegistry {
+		public const LAYER_SHARED = 'shared';
+
+		public static array $files = array();
+
+		public static function register( string $file, int $priority, array $metadata ): void {
+			self::$files[] = compact('file', 'priority', 'metadata');
+		}
+	}
+
+	final class SectionRegistry {
+		public static array $sections = array();
+
+		public static function register( string $file, string $section, int $priority, callable $callback, array $metadata ): void {
+			self::$sections[ $section ] = compact('file', 'section', 'priority', 'callback', 'metadata');
+		}
+	}
+}
+
+namespace {
+	if ( ! defined('ABSPATH') ) {
+		define('ABSPATH', '/var/www/html');
+	}
+
+	$GLOBALS['datamachine_code_test_filters'] = array();
+
+	function datamachine_agents_md_enabled(): bool {
+		return true;
+	}
+
+	function is_multisite(): bool {
+		return false;
+	}
+
+	function apply_filters( string $hook_name, mixed $value, mixed ...$args ): mixed {
+		$filters = $GLOBALS['datamachine_code_test_filters'][ $hook_name ] ?? array();
+		foreach ( $filters as $filter ) {
+			$value = $filter($value, ...$args);
+		}
+
+		return $value;
+	}
+
+	function add_test_filter( string $hook_name, callable $callback ): void {
+		$GLOBALS['datamachine_code_test_filters'][ $hook_name ][] = $callback;
+	}
+
+	function assert_contains( string $needle, string $haystack, string $message ): void {
+		if ( ! str_contains($haystack, $needle) ) {
+			throw new RuntimeException($message);
+		}
+	}
+
+	function assert_not_contains( string $needle, string $haystack, string $message ): void {
+		if ( str_contains($haystack, $needle) ) {
+			throw new RuntimeException($message);
+		}
+	}
+
+	require_once dirname(__DIR__) . '/inc/Runtime/CommandIntrospector.php';
+	require_once dirname(__DIR__) . '/inc/Runtime/AgentsMdSections.php';
+
+	\DataMachineCode\Runtime\AgentsMdSections::register();
+
+	$sections = \DataMachine\Engine\AI\SectionRegistry::$sections;
+	if ( ! isset($sections['datamachine-code']) ) {
+		throw new RuntimeException('datamachine-code section was not registered');
+	}
+
+	$render = $sections['datamachine-code']['callback'];
+	$default = $render();
+
+	assert_contains(
+		'All code changes happen in Data Machine Code worktrees under `unavailable; run datamachine-code workspace path to diagnose`. DMC owns workspace lifecycle',
+		$default,
+		'default workspace policy intro changed'
+	);
+	assert_contains(
+		'- **Primary is read-only.** Never edit `<workspace>/<repo>` (no `@slug`).',
+		$default,
+		'default workspace policy section missing'
+	);
+	assert_contains(
+		'- **Workspace:** `wp datamachine-code workspace adopt|clone|list|show|path|hygiene|remove|worktree|read|write|grep|edit|git|patch|ls`',
+		$default,
+		'DMC workspace command facts missing'
+	);
+
+	add_test_filter(
+		'datamachine_code_workspace_policy_intro',
+		static function ( string $default, string $workspace_path ): string {
+			return "Use local project policy for `{$workspace_path}`. ";
+		}
+	);
+	add_test_filter(
+		'datamachine_code_workspace_policy_section',
+		static function (): string {
+			return '- **Local policy:** caller-owned workspace rules.';
+		}
+	);
+
+	$filtered = $render();
+	assert_contains('Use local project policy for `unavailable; run datamachine-code workspace path to diagnose`. DMC owns workspace lifecycle', $filtered, 'workspace policy intro filter was not applied');
+	assert_contains('- **Local policy:** caller-owned workspace rules.', $filtered, 'workspace policy section filter was not applied');
+	assert_not_contains('- **Primary is read-only.** Never edit `<workspace>/<repo>` (no `@slug`).', $filtered, 'default policy section remained after filter override');
+	assert_contains('- **Workspace:** `wp datamachine-code workspace adopt|clone|list|show|path|hygiene|remove|worktree|read|write|grep|edit|git|patch|ls`', $filtered, 'DMC command facts changed after policy filter');
+
+	fwrite(STDOUT, "agents-md sections smoke passed\n");
+}