cleveragents-core/docs/reference/plan_apply.md

Plan Diff & Apply Reference

This document describes the diff review and apply integration features added in D0b.apply.

CLI Commands

agents plan diff <plan_id>

Show the ChangeSet produced during Execute as a unified diff, grouped by resource path.

Options:

Flag	Description
--format, -f	Output format: rich (default), plain, json, yaml

Examples:

# Rich output with coloured operation labels
agents plan diff 01HXYZ...

# Plain unified-diff output
agents plan diff 01HXYZ... --format plain

# Machine-readable JSON
agents plan diff 01HXYZ... --format json

Output fields (JSON/YAML):

Field	Type	Description
changeset_id	string	ULID of the ChangeSet
plan_id	string	ULID of the plan
total_changes	int	Number of change entries
summary	object	{creates, modifies, deletes, renames, paths_changed, resources_involved}
entries	list	Per-file entries with path, operation, hashes, timestamps

agents plan artifacts <plan_id>

Show plan artifacts: ChangeSet metadata, sandbox references, file change list, and validation results.

Options:

Flag	Description
--format, -f	Output format: rich (default), plain, json, yaml

Output fields (JSON/YAML):

Field	Type	Description
plan_id	string	Plan ULID
phase	string	Current lifecycle phase
processing_state	string	Current processing state
changeset_id	string	ChangeSet ULID (null if Execute not complete)
sandbox_refs	list	Active sandbox reference IDs
changeset_summary	object	Summary counts from SpecChangeSet
files_changed	list	{path, operation} per changed file
validation_summary	object	Validation results (if available)
apply_summary	object	Files changed count, validations run (after apply)

Apply Integration

Empty ChangeSet Guard

The apply pipeline checks whether the ChangeSet has any entries before proceeding. If the ChangeSet is empty, apply is blocked with a clear message:

Plan <id> has an empty ChangeSet. No changes to apply. Use --allow-empty to override.

Set --allow-empty to bypass this check for plans that intentionally produce no file changes (e.g. validation-only plans).

Apply Summary Persistence

When apply completes, the following metadata is stored in the plan:

• apply_files_changed: Number of files written/modified/deleted
• apply_validations_run: Number of validation checks executed
• apply_completed_at: ISO-8601 timestamp of apply completion

This metadata is visible via agents plan status and agents plan artifacts.

Merge Failure Handling

When a sandbox merge fails during apply:

1. The plan transitions to ERRORED processing state
2. error_message is set to "Merge failed: <details>"
3. error_details includes:
   • merge_conflict: Description of the conflict
   • sandbox_rollback: Set to "pending" for cleanup

Recovery steps:

1. Review conflict details via agents plan status <id>
2. Re-run execute phase after resolving conflicts: agents plan execute <id>
3. Or fix validation issues and retry apply

Processing State Flow

Execute/COMPLETE
    |
    v
Apply/QUEUED  -->  Apply/PROCESSING  -->  Apply/APPLIED (terminal success)
                        |
                        +-->  Apply/ERRORED (merge failure)
                        +-->  Apply/CONSTRAINED (invariant violation)

Service API

PlanApplyService

from cleveragents.application.services.plan_apply_service import PlanApplyService

service = PlanApplyService(
    lifecycle_service=lifecycle,
    changeset_store=store,  # optional InMemoryChangeSetStore
)

# Generate diff
diff_text = service.diff(plan_id, fmt="json")

# Get artifacts
artifacts = service.artifacts(plan_id, fmt="json")

# Guard empty changeset
service.guard_empty_changeset(plan_id, allow_empty=False)

# Persist apply summary
service.persist_apply_summary(plan_id, files_changed=5, validations_run=3)

# Handle merge failure
service.handle_merge_failure(plan_id, conflict_details="...")