[codex] Harden alterations guides against 3.8.0

[sfmskywalker]

What changed

• rewrote the alterations overview around the actual release/3.8.0 execution modes, built-in types, Studio surfaces, and persistence/dispatcher options
• expanded the alteration plans guide with plan lifecycle, filter guidance, and Studio plan inspection behavior
• expanded the immediate execution docs with result semantics and the shipped bulk retry endpoint
• updated the documentation slice backlog to mark DOC-053 complete and select DOC-019 as the next recommended slice

Why

The existing alterations pages were partially outdated: they omitted the built-in Cancel alteration, did not cover Studio's alterations module and plan/job inspection, and did not document the released /alterations/workflows/retry endpoint.

Impact

Operators and Studio users now have a release-backed explanation of how to choose between plan-based and immediate alterations, how background job execution works, and which runtime surfaces are available in Elsa 3.8.0.

Validation

• verified claims and endpoint shapes against release/3.8.0 in elsa-core, elsa-studio, and elsa-extensions
• ran git diff --check
• verified the modified docs' relative links resolve locally

[greptile-apps]

Greptile Summary

• Refreshes the alterations overview for Elsa 3.8.0 execution modes, built-in alteration types, Studio surfaces, and persistence/dispatcher options.
• Expands alteration plan documentation with lifecycle details, filter guidance, dry-run behavior, and plan/job inspection notes.
• Documents immediate execution result semantics and the shipped bulk retry endpoint.
• Updates the documentation backlog to mark DOC-053 complete and recommend DOC-019 next.

Confidence Score: 4/5

The documentation updates are mostly safe to merge once the release-behavior mismatches in the alteration endpoint docs are corrected.

The reviewed changes are documentation-only and focused, but two endpoint details conflict with Elsa 3.8.0 behavior in ways that can mislead operators using retry results or alteration status authorization.

features/alterations/applying-alterations/rest-api.md and features/alterations/alteration-plans/rest-api.md

T-Rex Logs

What T-Rex did

• Ran a focused retry-endpoint harness for POST /alterations/workflows/retry with two workflow IDs and no activityIds, observed HTTP 200 OK with two runner invocations, and confirmed the response contained four alteration results across the two targeted workflow instances; each runner received the full set of workflowInstanceIds.
• Executed a focused metadata harness against Elsa release/3.8.0 alteration endpoints and observed that a run-only token maps to HTTP 403 for GET /alterations/{id} while a read-only token maps to HTTP 200, and that POST /alterations/submit and /alterations/dry-run require run:alterations, with run-only tokens returning 200 and read-only tokens returning 403.
• Compared base docs at 6e350d6... alongside the Elsa 3.8.0 contract check with head docs at 296bec1..., showing the new claims are backed by implementation for the requested endpoints.
• Compared Studio documentation before and after, noting the head adds the relevant Studio surfaces and that validation was performed via a script against the public release source since a runnable Studio app is not included.
• Documented that release/3.8.0 code registrations and lifecycle implementation include defaults to memory stores and a background dispatcher, EF Core store factories, MongoDB and MassTransit extension methods, and that SubmitAlterationPlan calls SaveAsync(plan) while GenerateAlterationJobs calls SaveManyAsync when workflowInstanceIds are present.
• Measured backlog validation, with the before artifact showing base contract failures and the after artifact showing all five changed-doc local relative links resolved and backlog checks passing with EXIT_CODE: 0.

_{Ran code and verified through T-Rex}

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
features/alterations/applying-alterations/rest-api.md:108
**Retry results multiply** The shipped retry endpoint does not always return one result per targeted workflow instance. In `release/3.8.0`, it loops over each loaded workflow instance, then calls the alteration runner with the full requested `workflowInstanceIds` collection each time. With two workflow IDs and omitted `activityIds`, callers can receive four results, and incident activity IDs from one instance can be applied to the other instance. The docs should describe this release behavior or recommend one workflow instance ID per retry request when relying on incident-derived activity IDs.

### Issue 2 of 2
features/alterations/alteration-plans/rest-api.md:5
**Wrong read permission** The status endpoint on this page does not use `run:alterations`. In `release/3.8.0`, `GET /alterations/{id}` is guarded by `read:alterations`, while submit and dry-run use `run:alterations`. An operator following this note can grant only `run:alterations` and still get authorization failures when trying to inspect plan/job status.

_{Reviews (1): Last reviewed commit: "docs: harden alterations guides against ..." | Re-trigger Greptile}

[greptile-apps]

Retry results multiply The shipped retry endpoint does not always return one result per targeted workflow instance. In release/3.8.0, it loops over each loaded workflow instance, then calls the alteration runner with the full requested workflowInstanceIds collection each time. With two workflow IDs and omitted activityIds, callers can receive four results, and incident activity IDs from one instance can be applied to the other instance. The docs should describe this release behavior or recommend one workflow instance ID per retry request when relying on incident-derived activity IDs.

Artifacts

Repro: executable retry endpoint harness

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: harness output showing 200 OK and multiplied results

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: features/alterations/applying-alterations/rest-api.md
Line: 108

Comment:
**Retry results multiply** The shipped retry endpoint does not always return one result per targeted workflow instance. In `release/3.8.0`, it loops over each loaded workflow instance, then calls the alteration runner with the full requested `workflowInstanceIds` collection each time. With two workflow IDs and omitted `activityIds`, callers can receive four results, and incident activity IDs from one instance can be applied to the other instance. The docs should describe this release behavior or recommend one workflow instance ID per retry request when relying on incident-derived activity IDs.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Wrong read permission The status endpoint on this page does not use run:alterations. In release/3.8.0, GET /alterations/{id} is guarded by read:alterations, while submit and dry-run use run:alterations. An operator following this note can grant only run:alterations and still get authorization failures when trying to inspect plan/job status.

Artifacts

Repro: executable authorization metadata harness for alteration endpoints

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: harness output showing endpoint permissions and HTTP status mappings

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: features/alterations/alteration-plans/rest-api.md
Line: 5

Comment:
**Wrong read permission** The status endpoint on this page does not use `run:alterations`. In `release/3.8.0`, `GET /alterations/{id}` is guarded by `read:alterations`, while submit and dry-run use `run:alterations`. An operator following this note can grant only `run:alterations` and still get authorization failures when trying to inspect plan/job status.

How can I resolve this? If you propose a fix, please make it concise.