Automation permission matrix maintainer

Maintains automations/docs/automation-operations-permissions.md: the per-role availability matrix for every user-facing AIR Automations operation. The document has three generated sections — Matrix current (today's behaviour, from code), Matrix target (intended future model), and Matrix diff — plus a static "How to read", "Notes", and "Open questions" section that you must preserve.

Run this skill:

• at the end of any task that adds or changes an automation operation or its authorization (backend controller / service permission wrapper, gateway guard, or a frontend action), or
• after the doc was edited by hand (a reviewer added/changed rows or target values).

The five columns

Each operation row has five availability cells, then a functionality description:

Cell values: Yes, No, N/A (code does not determine it). A trailing ? (e.g. Yes?) marks a target value that has not been verified by a human yet — only ever add ? in Matrix target, never in Matrix current.

Permission model (how to derive cell values from code)

Authorization is JCP AuthZ (Can-I) on the air_automation entity with actions read / update / delete, plus a repo-access check (unconditional). Model assumes AIR_CLOUD_PROJECTS_FEATURE_FLAG on.

1. Find the gate. In the controller, find the withAutomation*Permission / withAutomationSnapshot*Permission wrapper the handler uses (in automations, automation-runs, notifications, triggers services):
   • ...ReadPermission → read action.
   • ...EditPermission → update action.
   • ...DeletePermission → delete action.
   • No wrapper → note it (may be a gap or a client-side/gateway path). Check gateway guards and repo checks.
2. Map action → roles:
   • read → creator + any project member + any project admin.
   • update / delete → creator + project admin. Plain members do not get these (unless they are the creator).
3. Repo access is enforced at exactly one place — automation.service.ts createAutomation (assertUserHasRepositoryAccess, ~line 101), which also runs on the save/edit path (createAutomation with an id). It is write for a project automation (projectId set) and read for a private one; it is not re-checked on read/pause/delete/stop/etc. So the + repo and − repo columns differ only for create and snapshot-save operations.
4. Ownership split. Because the creator always holds direct read+update+delete grants, update/delete-class operations behave differently by creator. Split such operations into two rows:
   • <feature> — own — project automation the actor created (creator grants apply).
   • <feature> — another project member — created by someone else (role-based only); the Private cell is N/A. Read-class, create, and no-per-automation-check ([g]) operations are not split.
5. Reusable value patterns (Matrix current):
   • Read-class op: Yes | Yes | Yes | Yes | Yes (Private N/A if it is project-only, e.g. list-by-project).
   • Create / snapshot-save [w]: Yes | Yes | No | Yes | No.
   • Save — own [w]: Yes | Yes | No | Yes | No. Save — another project member [w]: N/A | No | No | Yes | No.
   • Non-repo update — own (pause, stop, update-status, delete): Yes | Yes | Yes | Yes | Yes. — another project member: N/A | No | No | Yes | Yes.
   • No per-automation check [g] (webhook token, Run Now): Yes | Yes | Yes | Yes | Yes.
6. Markers (append in backticks to the feature name; document under Notes): [w] repo-write-gated save; [g] no per-automation authorization; [r] write gated only by read permission; [n] notification-config nuance.
7. Exclude internal service-to-service endpoints (@AllowPrincipalTypes(PrincipalType.Service), internal* controllers, health, launcher dispatch) and non-per-automation endpoints (access/permanent tokens, Jira provisioning). If unsure whether an operation is user-facing, add it with N/A cells and a note.

Procedure

1. Detect what changed

git status --porcelain
git diff --stat HEAD          # working + staged; add --cached if needed
git diff -- automations/docs/automation-operations-permissions.md

Classify the changes:

• Code changes touching automation operations: new/changed HTTP handlers under automations/apps/backend/src/modules/*/controllers/, their services' permission wrappers, gateway automations controller/guards, or frontend actions under cloud/frontend/src/modules/automations/ and cloud/frontend/src/pages/automations/.
• Manual doc edits: rows or cells a human changed in automations/docs/automation-operations-permissions.md.

If neither is present, stop — nothing to do.

2. Reconcile new/changed operations

For each new user-facing operation found in code:

1. Derive its Matrix current cells using the model above (open the controller + service and cite file:line in the row rationale you keep in your working notes / commit message, not in the table).
2. Decide whether it is ownership-sensitive; if so add both the — own and — another project member rows.
3. Insert the row(s) into Matrix current in the logical group (create → read → update → delete → tokens/run → out of scope), and the same row(s) into Matrix target with every cell copied from current plus a trailing ? (so the reviewer verifies them).

For a changed operation (its gate changed in code), update its Matrix current cells and add ? to the corresponding Matrix target cells if the target value is now uncertain.

For manual doc edits:

• If a human added/edited rows in Matrix current, keep them, but re-derive from code to confirm; if a value is wrong per code, correct it and note the discrepancy under "Open questions".
• If a human edited Matrix target values, preserve them — do not overwrite target intent.
• Ensure Matrix current and Matrix target have the same feature rows in the same order. If one matrix is missing a feature the other has, add it (target additions get ? cells copied from current).

3. Recompute the Matrix diff

Rebuild the Matrix diff section from scratch by comparing Matrix current and Matrix target cell by cell, textually (so Yes vs Yes? counts as a difference — it flags an unverified target):

• Include a row only if at least one of its five cells differs between current and target.
• For each such row, show current → target in the differing cells and — in unchanged cells.
• If no cells differ anywhere, replace the table with: _No differences: Matrix target matches Matrix current._

4. Keep formatting clean

• Preserve the "How to read", "Notes & caveats", "Open questions", and "Keeping this document up to date" sections.
• If you added a new marker (e.g. a new [x]), document it under the marker legend.
• Keep the tables valid GitHub-flavored Markdown; column alignment is normalized by Prettier on commit, so exact padding is not required, but keep it readable. Do not reorder or rename the five columns.

5. Report

Summarize what changed: operations added/updated (with the code file:line that justifies each), any values you corrected, and the new Matrix diff rows. Call out anything you could not determine from code (left as N/A / added to Open questions) so the human can fill it in.