fix(workspace): permissive-by-default git mutation gates

[chubes4]

Summary

The datamachine_workspace_git_policies WordPress option gates git mutation ops (pull / add / commit / push) and git_add's path allowlist in the workspace wrapper. Before this change, every unconfigured repo failed every git mutation with git_write_disabled or no_allowed_paths, making the wrapper's git-family subcommands unusable out of the box.

Repro

On a fresh install (no datamachine_workspace_git_policies option set):

$ wp datamachine-code workspace git pull data-machine --allow-primary-mutation
Error: Git write operations are disabled for repo "data-machine".

The --allow-primary-mutation flag (the override documented in AGENTS.md) never gets evaluated because an earlier, undocumented gate fires first. The error message doesn't reference the option key or suggest a fix.

Workaround before this PR: git -C /var/lib/datamachine/workspace/<repo> pull — bypassing the wrapper entirely.

Root cause

ensure_git_mutation_allowed() treated "no entry in policy array" identically to "explicitly disabled":

// Before:
$repo = $policies['repos'][ $repo_name ] ?? null;
if ( ! is_array( $repo ) || empty( $repo['write_enabled'] ) ) {
    return new WP_Error( 'git_write_disabled', ... );
}

Combined with:

• No CLI to populate the option (workspace --help has no policy subcommands)
• No admin UI
• No filter (until this PR)
• No docs describing the option

…this was a hidden hard gate with no configuration surface.

A second, analogous gate lived in git_add(): the allowed_paths check returned no_allowed_paths when the list was empty, which it always is by default.

Fix

Permissive-by-default. The policy option becomes an opt-in restriction layer instead of a hidden requirement:

1. ensure_git_mutation_allowed() — null entry → allow. Entry present → honor explicit flags. write_enabled / push_enabled default to true when the flag itself is missing, so a partial config (e.g. only setting allowed_paths) doesn't accidentally disable writes.

2. git_add() — empty allowed_paths → no restriction. When configured, the allowlist still gates. Sensitive-path + traversal checks are always enforced regardless of policy.

3. Error messages now reference the policy option by name, so if someone does hit a deny, they know what to look at.

4. New filter datamachine_workspace_git_policies for runtime injection of policy (e.g. env-specific, or driven by site config managed elsewhere) without writing to the option.

5. get_workspace_git_policies() docblock documents the schema (write_enabled, push_enabled, allowed_paths, fixed_branch) and the permissive defaults.

What doesn't change

The primary-vs-worktree gate (ensure_primary_mutation_allowed + --allow-primary-mutation override) is the documented default safety mechanism per AGENTS.md:

"Primary is read-only by default: mutating ops on bare <repo> handles require --allow-primary-mutation."

That gate is untouched. It's the intended protection layer — the one users read about and expect.

To explicitly deny a repo

Set an option entry:

update_option( 'datamachine_workspace_git_policies', array(
    'repos' => array(
        'sensitive-repo' => array(
            'write_enabled' => false,
            'push_enabled'  => false,
        ),
    ),
) );

Or via the filter:

add_filter( 'datamachine_workspace_git_policies', function( $policies ) {
    $policies['repos']['sensitive-repo'] = array( 'write_enabled' => false );
    return $policies;
} );

Files

• inc/Workspace/Workspace.php — gate logic + filter + docblock
• data-machine-code.php — version bump 0.6.2 → 0.6.3
• docs/CHANGELOG.md — entry added

Testing

No existing unit tests cover the workspace git mutation gates (only tests/smoke-gitsync.php covers the separate GitSync subsystem, which uses its own policy storage via GitSync::updatePolicy() and is unaffected by this change).

Manual verification: with this PR applied, workspace git pull <repo> --allow-primary-mutation and workspace git commit/push <repo>@<branch> succeed on an unconfigured workspace, matching AGENTS.md's documented contract.

Related

Not blocking but discovered during a data-machine release cascade that involves pulling main via the workspace wrapper. With this fix, the wrapper becomes usable for its intended workflows without requiring manual option configuration first.