@uipath/skills 1.195.0

package/skills/uipath-governance/references/access-policy/plugins/executable/planning.md

@@ -0,0 +1,122 @@
+# Actor Process Plugin — Planning
+
+> **User-facing terminology vs JSON field.** The user-facing name for this block is **Actor Process rule**. The underlying JSON field is `executableRule` — that name is only shown in code / CLI contexts. When summarizing the policy to the user, always say "Actor Process rule", never "Executable rule".
+
+The `executableRule` block identifies the **caller** — the Actor Process that uses the resource. The access policy has exactly one `executableRule` block, but that block can contain multiple per-type entries.
+
+## When to Use
+
+Always. Every access policy this skill authors has exactly one `executableRule`.
+
+## Block shape (conceptual)
+
+```text
+executableRule = {
+    values: [
+        { type: <Agent | AgenticProcess | CaseManagement | Flow>, values: [...], operator: <Or | None> },
+        ...                                                       # one entry per executable type
+    ],
+    tags: { values: [...], operator: <Or | And | None> }          # optional, applies to all entries
+}
+```
+
+- `executableRule.values[]` — one entry per executable **type** the user mentioned.
+- `executableRule.tags` — optional. When present, narrows the set for every entry in `values[]`.
+
+## Intent → executable type
+
+Map the user's phrasing to the enum. These are the only valid executable `type` values.
+
+| User phrase | User-facing label | JSON `type` |
+|-------------|-------------------|-------------|
+| "agent", "AI agent" | Agent | `Agent` |
+| "maestro", "maestro process", "agentic process" | **Maestro** | `AgenticProcess` |
+| "case management", "case" | Case Management | `CaseManagement` |
+| "flow" | Flow | `Flow` |
+
+> Always say **Maestro** in user-facing text (Spec narrative, summaries, review gate); emit `AgenticProcess` only inside JSON code blocks (Critical Rule #14).
+
+> **Not valid here:** `RPAWorkflow` and `APIWorkflow` are resource-only types. They live in `selectors[]` (see [selector/planning.md](../selector/planning.md)); they cannot appear in `executableRule.values[].type`.
+
+## Targeting modes
+
+Same two modes as selectors, plus a third pattern that operates on the entry's `type` rather than its `values`:
+
+| Mode | Entry shape | When to use |
+|------|-------------|-------------|
+| **All of this type** | `{ type: <T>, values: ["*"], operator: "Or" }` | "Any `<T>` caller". |
+| **Specific IDs** | `{ type: <T>, values: ["<UUID>", ...], operator: "Or" }` | "These specific `<T>` callers". |
+| **Exclude specific IDs** | `{ type: <T>, values: ["<UUID>", ...], operator: "None" }` | "Any `<T>` caller except these UUIDs". |
+| **Exclude a whole type** | `{ type: <T>, values: ["*"], operator: "None" }` — and **omit every other type** from `values[]` | "Any caller type except `<T>`". Caller types not listed in `values[]` are NoOp on this filter (the policy does not constrain them). See [Excluding a caller type](#excluding-a-caller-type). |
+
+`values: ["*"]` is required on every entry (Critical Rule #5). Missing it returns `400`.
+
+### Resolving Actor Process names to UUIDs
+
+If the user named a specific caller ("the Maestro Production process"), resolve the name to a UUID via [resource-lookup-guide.md](../../resource-lookup-guide.md) using the **two-step flow**:
+
+1. **Discover the folder first** — `uip or processes list` requires `--folder-path`. If the user did not say which folder, run `uip or folders list --output json` and ask the user to pick before searching.
+2. **Translate the Actor Process type** — Orchestrator's `--process-type` is **not** the same string as the access-policy `type`. For Actor Process values, map: `Agent`→`Agent`, `AgenticProcess`→`ProcessOrchestration`, `Flow`→`Flow`, `CaseManagement`→`CaseManagement`. See the full table in [resource-lookup-guide.md § Access-policy type → Orchestrator `--process-type`](../../resource-lookup-guide.md#access-policy-type--orchestrator---process-type).
+3. **Search** — `uip or processes list --folder-path "<PATH>" --process-type "<ORCHESTRATOR_TYPE>" --name "<SUBSTR>" --output json`. Present the matching rows as a numbered picker. Use the returned `Key` field as the UUID.
+
+Never ask the user to leave the chat to find a UUID — run the lookup first. Only surface an open question when the lookup returns no match after broadening the search.
+
+## Multi-type executable rules
+
+If the user says "allow Agents **and** Maestros to use…", emit two entries (one per JSON `type`):
+
+```text
+executableRule:
+  values:
+    1. type: Agent,           values: ["*"], operator: Or
+    2. type: AgenticProcess,  values: ["*"], operator: Or
+  tags: { values: ["Production"], operator: Or }    # applied to both entries
+```
+
+The shared `executableRule.tags` applies uniformly across every entry — there is **no per-entry `tags`** inside `executableRule.values[]`. If different executable types need different tag rules, the policy is probably really two policies; flag this during Phase 1 and ask the user.
+
+## Excluding a caller type
+
+When the user says "any caller **except** `<type>`" — e.g. "block Agent callers, allow everything else" — emit ONE entry of the **excluded** type with `operator: "None"` and `values: ["*"]`, and OMIT every other type from `values[]`. Do NOT enumerate the allowed types.
+
+```text
+# Intent: "any caller except Agent"
+executableRule:
+  values:
+    1. type: Agent, values: ["*"], operator: None
+```
+
+**Why this works.** Caller types not listed in `executableRule.values[]` are NoOp on this filter — the policy does not constrain them. The single `None`-on-`Agent` entry says "this policy applies when the caller's type is NOT `Agent`". Combined with `enforcement: "Allow"`, the policy contributes Allow for every non-`Agent` caller.
+
+**Why NOT enumerate.** Listing `AgenticProcess`, `CaseManagement`, `Flow` with `Or` produces the same runtime effect but:
+- It is verbose and obscures the user's "all except X" intent.
+- It rots when new caller types are added to the platform.
+- It tempts authors to "just add another type with `Or`" instead of reasoning about exclusion.
+
+The canonical shape is the single-entry `None`-on-excluded-type form. See [executable/impl.md — Example E](./impl.md#e-all-caller-types-except-a-specific-type-canonical-idiom).
+
+> **"Exclude UUIDs" vs "exclude a type" vs "exclude a tag"** are three different operators that all happen to use `None`:
+> - **Exclude UUIDs** — `{ type: <T>, values: ["<UUID1>", ...], operator: "None" }` matches any `<T>` caller whose UUID is NOT in the list.
+> - **Exclude a type** — `{ type: <T>, values: ["*"], operator: "None" }` matches any caller whose type is NOT `<T>` (this section).
+> - **Exclude a tag** — `tags: { values: ["<TAG>"], operator: "None" }` (top-level on `executableRule`) matches callers that do NOT carry the tag. See [tags/planning.md — Deny-to-Allow flip](../tags/planning.md#deny-to-allow-flip).
+
+## Top-level `tags` vs per-entry `values`
+
+- `executableRule.tags` — applies once, to all entries in `values[]`. The only place tag filters live in this block.
+- Per-entry `values` — targets individual executables by UUID.
+
+## Deny-flipped intent
+
+"Deny flows from using Production Agents" flips to: Allow all flows to use Agents **except** Production-tagged ones. The flip lives on the **selector**'s tags (`operator: None` on `Production`), not on the executable. See [tags/planning.md — Deny-to-Allow flip](../tags/planning.md#deny-to-allow-flip) for the decision procedure.
+
+## Anti-patterns
+
+- Do NOT put `RPAWorkflow` or `APIWorkflow` in `executableRule.values[].type` — those are resource-only.
+- Do NOT omit `values` — it is required per entry.
+- Do NOT confuse the Actor Process rule (`executableRule`, the calling workflow) with the Actor Identity rule (`actorRule`, the user/group triggering it). See [planning-arch.md § The three rule blocks](../../planning-arch.md#the-three-rule-blocks-boundary-table) for the boundary.
+- Do NOT merge distinct `type` values into one entry — one entry per type.
+- Do NOT use `operator: And` on `values` — only `Or` / `None`.
+
+## Next: compose the JSON
+
+When Phase 2 needs the concrete JSON for the `executableRule` block, read [executable/impl.md](./impl.md).

package/skills/uipath-governance/references/access-policy/plugins/selector/impl.md

@@ -0,0 +1,169 @@
+# Selector Plugin — Implementation
+
+Concrete JSON for a single entry in `selectors[]`. Phase 2 reads this file to compose every selector before assembling the top-level `PolicyDefinition` (see [planning-impl.md — Step 2](../../planning-impl.md#step-2--compose-each-block-via-plugins)).
+
+> **Required field: `values`.** Every `selectors[]` entry must include `values` (use `["*"]` for "all of this type") — it cannot be omitted, even when `tags` narrow the scope. Missing `values` returns `400 Bad Request` (Critical Rule #5).
+
+## Single selector entry
+
+```json
+{
+    "resourceType": "<Agent | AgenticProcess | RPAWorkflow | APIWorkflow | CaseManagement | Flow>",
+    "values": ["*"],
+    "operator": "<Or | None>",
+    "tags": {
+        "values": ["<TAG_1>", "<TAG_2>"],
+        "operator": "<Or | And | None>"
+    }
+}
+```
+
+### Field rules
+
+| Field | Required | Value rules |
+|-------|----------|-------------|
+| `resourceType` | yes | One of: `Agent`, `AgenticProcess`, `RPAWorkflow`, `APIWorkflow`, `CaseManagement`, `Flow`. |
+| `values` | yes | `["*"]` for all-of-type, or `["<UUID>", ...]` for specific IDs. Never empty. |
+| `operator` | yes | `"Or"` to include matching IDs; `"None"` to exclude them. |
+| `tags` | optional | Omit entirely when the user did not specify tags. When present, compose via [tags/impl.md](../tags/impl.md). |
+
+## Full `selectors[]` array shape
+
+The top-level `PolicyDefinition.selectors` is always an array:
+
+```json
+"selectors": [
+    { /* entry 1 */ },
+    { /* entry 2 */ }
+]
+```
+
+One array entry per distinct `resourceType` row in the Spec Components Table.
+
+---
+
+## Worked examples
+
+### A. All-of-type with tag filter
+
+**Intent:** "All Production Agents".
+
+```json
+{
+    "resourceType": "Agent",
+    "values": ["*"],
+    "operator": "Or",
+    "tags": {
+        "values": ["Production"],
+        "operator": "Or"
+    }
+}
+```
+
+### B. Specific UUIDs, no tag filter
+
+**Intent:** "Agents with IDs abc-123 and def-456".
+
+```json
+{
+    "resourceType": "Agent",
+    "values": [
+        "abc-123",
+        "def-456"
+    ],
+    "operator": "Or"
+}
+```
+
+(Note: `tags` is omitted — the user did not mention any.)
+
+### C. Specific UUIDs plus tag filter
+
+**Intent:** "Agent abc-123 (must also be Production-tagged)".
+
+```json
+{
+    "resourceType": "Agent",
+    "values": ["abc-123"],
+    "operator": "Or",
+    "tags": {
+        "values": ["Production"],
+        "operator": "Or"
+    }
+}
+```
+
+Both filters apply — the policy matches resources that appear in `values` **and** satisfy `tags`.
+
+### D. Multi-entry (two resource types in one policy)
+
+**Intent:** "Production Agents and Production Flows".
+
+```json
+"selectors": [
+    {
+        "resourceType": "Agent",
+        "values": ["*"],
+        "operator": "Or",
+        "tags": { "values": ["Production"], "operator": "Or" }
+    },
+    {
+        "resourceType": "Flow",
+        "values": ["*"],
+        "operator": "Or",
+        "tags": { "values": ["Production"], "operator": "Or" }
+    }
+]
+```
+
+### E. Deny-flipped (exclude Development tags)
+
+**Intent (original):** "block Development Agents". **Flipped to Allow** with the `None` operator on tags (see [tags/planning.md — Deny-to-Allow flip](../tags/planning.md#deny-to-allow-flip)):
+
+```json
+{
+    "resourceType": "Agent",
+    "values": ["*"],
+    "operator": "Or",
+    "tags": {
+        "values": ["Development"],
+        "operator": "None"
+    }
+}
+```
+
+This matches every Agent **except** those tagged `Development`.
+
+---
+
+## Update-flow use
+
+When `policy-manage-guide.md — Update` needs to modify an existing selector, pass the existing entry back through this file:
+
+1. Start from the existing entry (already in the working file's `selectors[]`).
+2. Change only the field the user asked about (e.g. add an ID to `values`, swap a tag operator).
+3. Preserve every other field verbatim.
+
+Example: the user says "add UUID `xyz-789` to the first selector's values". The resulting entry:
+
+```json
+{
+    "resourceType": "Agent",
+    "values": ["abc-123", "xyz-789"],
+    "operator": "Or",
+    "tags": { "values": ["Production"], "operator": "Or" }
+}
+```
+
+Everything except `values` is unchanged from the original.
+
+---
+
+## Debug
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `400 Bad Request` / `Selectors[0].Values is required` | `values` missing or empty | Always pass `["*"]` or real UUIDs. Never an empty array. |
+| `400 Bad Request` / unknown `resourceType` | Typo or non-existent enum | Use exactly one of the six enum values above. |
+| Policy matches nothing at runtime | `values` has specific UUIDs that don't exist, or tag filter doesn't match any resource | Re-run `uip gov access-policy evaluate` with a real resource UUID to confirm matching; check the Resource Catalog tags on the resource. |
+| Selectors for multiple types merged into one entry | Attempted to put multiple `resourceType` values in one entry | Split into multiple `selectors[]` entries. Each entry is single-type. |

package/skills/uipath-governance/references/access-policy/plugins/selector/planning.md

@@ -0,0 +1,98 @@
+# Selector Plugin — Planning
+
+> **User-facing terminology vs JSON field.** The user-facing name for this block is **Selection Rule** (the Resource being protected). The underlying JSON field is `selectors[]` — that name is only shown in code / CLI contexts.
+
+The `selectors[]` block identifies the **Resource** the access policy is about — what is being used by the Actor Process. One entry per distinct resource type the user mentioned.
+
+## When to Use
+
+Always. Every access policy this skill authors has at least one selector entry.
+
+- One selector entry → one resource type.
+- User mentioned multiple resource types ("Agents and Flows") → emit multiple entries, one per type. Do NOT merge types into a single entry.
+
+## Block shape (conceptual)
+
+```text
+selectors[i] = {
+    resourceType: <Agent | AgenticProcess | RPAWorkflow | APIWorkflow | CaseManagement | Flow>,
+    values: [...],                                                # required — UUIDs or ["*"]
+    operator: <Or | None>,
+    tags: { values: [...], operator: <Or | And | None> }          # optional — per-entry
+}
+```
+
+## Intent → resource type
+
+Map the user's phrasing to the enum. These are the only valid `resourceType` values.
+
+| User phrase | User-facing label | JSON `resourceType` |
+|-------------|-------------------|---------------------|
+| "agent", "AI agent" | Agent | `Agent` |
+| "maestro", "maestro process", "agentic process" | **Maestro** | `AgenticProcess` |
+| "RPA workflow", "RPA", "robot process" | **RPA** | `RPAWorkflow` |
+| "API workflow", "API" | API Workflow | `APIWorkflow` |
+| "case management", "case", "case work item" | Case Management | `CaseManagement` |
+| "flow" | Flow | `Flow` |
+
+> Always say **Maestro** and **RPA** in user-facing text; emit `AgenticProcess` and `RPAWorkflow` only inside JSON (Critical Rule #14).
+
+If a phrase is ambiguous (e.g. "process" could be Maestro/`AgenticProcess` or RPA/`RPAWorkflow`), ask the user before picking.
+
+## Targeting modes
+
+Each selector entry picks one of two targeting modes. This is always expressed via the `values` field.
+
+| Mode | `values` | `operator` | When to use |
+|------|----------|------------|-------------|
+| **All of this type** | `["*"]` | `Or` | User said "all agents", "any flow", or didn't name specific resources. Tag filter then narrows the set. |
+| **Specific IDs** | `["<UUID1>", "<UUID2>", ...]` | `Or` | User named specific resources by UUID. |
+| **Exclude specific IDs** | `["<UUID>", ...]` | `None` | Rare — user said "all agents except X". Usually easier to re-express via tag `None`. |
+
+`values: ["*"]` is **required** even when you are using `tags` to narrow the scope. It is NOT optional. Missing `values` returns `400 Bad Request` (Critical Rule #5).
+
+If the user mentions specific resources by **name** (e.g. "the Invoice Agent"), you need UUIDs. Resolve via [resource-lookup-guide.md](../../resource-lookup-guide.md) using the **two-step flow**:
+
+1. **Discover the folder first** — `uip or processes list` requires `--folder-path` (or `--folder-key`). If the user did not say which folder, run `uip or folders list --output json`, show the folders, and ask the user to pick.
+2. **Translate the resource type** — the Orchestrator `--process-type` value is **not** the same string as the access-policy `resourceType`. Use the mapping table in [resource-lookup-guide.md § Access-policy type → Orchestrator `--process-type`](../../resource-lookup-guide.md#access-policy-type--orchestrator---process-type) — notably `AgenticProcess`→`ProcessOrchestration`, `RPAWorkflow`→`Process`, `APIWorkflow`→`Api`.
+3. **Search** — `uip or processes list --folder-path "<PATH>" --process-type "<ORCHESTRATOR_TYPE>" --name "<SUBSTR>" --output json`. Present the matching rows as a numbered picker. Use the returned `Key` field as the UUID.
+
+Only surface an Open question in the Phase 1 Spec when the lookup still returns no match after broadening the search.
+
+## Tag filter
+
+Any tag phrase the user used ("Production Agent", "tagged Staging", "not Development") becomes a `tags` sub-object nested inside the selector entry. Tag composition is handled by the [tags plugin](../tags/planning.md).
+
+The `tags` filter applies at the **per-entry level** (inside `selectors[N].tags`) — each `selectors[]` entry has its own independent tag filter. There is no top-level `selectors.tags` shared across entries. Two resource types with different tag filters → two `selectors[]` entries.
+
+Omit `tags` entirely if the user did not mention any tags. Do NOT add empty `tags: { values: [], operator: "Or" }` objects.
+
+## Multi-type selectors
+
+If the policy targets multiple resource types, emit one `selectors[]` entry per type:
+
+In the Spec Components Table (see [planning-arch.md — Spec output format](../../planning-arch.md#spec-output-format)), render multi-type targeting as one Resource row group per type, with user-friendly phrasing:
+
+```text
+  Resource filters (which resource processes this policy protects):
+    1. Resource type: Agent
+       Applies to:   all Agent resources
+       Tag filter:   Any-of ["Production"]
+    2. Resource type: Flow
+       Applies to:   all Flow resources
+       Tag filter:   Any-of ["Production"]
+```
+
+Each entry's `tags` is independent — a Production Agent selector does NOT imply a Production Flow selector.
+
+## Anti-patterns
+
+- Do NOT omit `values` — it is required even when `tags` narrow the scope.
+- Do NOT put callers or identities here — this block is for Resources only. See [planning-arch.md § The three rule blocks](../../planning-arch.md#the-three-rule-blocks-boundary-table) for the boundary.
+- Do NOT merge distinct resource types into one entry — one entry per `resourceType`.
+- Do NOT use `operator: And` on `values` — only `Or` (include) and `None` (exclude) are supported at the values level.
+- Do NOT put resource UUIDs in `tags.values`. Tag names and resource IDs live in different arrays — UUIDs go in the selector's own `values`, tag names go in `tags.values`.
+
+## Next: compose the JSON
+
+When Phase 2 needs the concrete JSON for a selector entry, read [selector/impl.md](./impl.md).

package/skills/uipath-governance/references/access-policy/plugins/tags/impl.md

@@ -0,0 +1,153 @@
+# Tags Plugin — Implementation
+
+Concrete JSON for the shared `tags` sub-object. Phase 2 reads this file whenever a selector entry or `executableRule` needs a tag filter (see [planning-impl.md — Step 2](../../planning-impl.md#step-2--compose-each-block-via-plugins)).
+
+> **Required when `tags` is present: `values` and `operator`.** When the `tags` key exists, both `tags.values` (non-empty array) and `tags.operator` (`Or` / `And` / `None`) are required. Omit the entire `tags` key when there is no tag constraint — never emit `"tags": {}` or `"tags": { "values": [] }`.
+
+## Shape
+
+```json
+"tags": {
+    "values": ["<TAG_1>", "<TAG_2>"],
+    "operator": "<Or | And | None>"
+}
+```
+
+### Field rules
+
+| Field | Required | Value rules |
+|-------|----------|-------------|
+| `values` | yes (when `tags` is present) | Non-empty array of Resource Catalog tag name strings. Never `[]`. |
+| `operator` | yes (when `tags` is present) | One of `"Or"`, `"And"`, `"None"`. Case-sensitive. |
+
+Omit the entire `tags` key when the user did not specify tags. Do NOT emit `"tags": {}` or `"tags": { "values": [] }`.
+
+## Operator cheat-sheet
+
+| Operator | Rule semantics |
+|----------|----------------|
+| `"Or"` | Match if the resource has **any** of `values`. |
+| `"And"` | Match if the resource has **all** of `values`. |
+| `"None"` | Match if the resource has **none** of `values` (i.e., exclude). |
+
+See [tags/planning.md](./planning.md) for when to pick each.
+
+---
+
+## Worked examples
+
+### A. Single-tag `Or` (most common)
+
+**Intent:** "only Production resources".
+
+```json
+"tags": {
+    "values": ["Production"],
+    "operator": "Or"
+}
+```
+
+### B. Multi-tag `And`
+
+**Intent:** "resources tagged both Production and Critical".
+
+```json
+"tags": {
+    "values": ["Production", "Critical"],
+    "operator": "And"
+}
+```
+
+Only resources carrying both tags match.
+
+### C. Deny-flip with `None`
+
+**Intent (original):** "deny Development resources". **Flipped to Allow** (see [planning.md — Deny-to-Allow flip](./planning.md#deny-to-allow-flip)):
+
+```json
+"tags": {
+    "values": ["Development"],
+    "operator": "None"
+}
+```
+
+This matches every resource **except** those tagged `Development`.
+
+### D. Multi-tag `None` (exclude any of several)
+
+**Intent (original):** "block Development or Staging flows". On the selector (`resourceType: Flow`):
+
+```json
+"tags": {
+    "values": ["Development", "Staging"],
+    "operator": "None"
+}
+```
+
+Matches every Flow that does **not** carry either tag.
+
+---
+
+## Where this block embeds
+
+Paste the composed `tags` object into the parent block returned by [selector/impl.md](../selector/impl.md) or [executable/impl.md](../executable/impl.md). Example embedded in a selector entry:
+
+```json
+{
+    "resourceType": "Agent",
+    "values": ["*"],
+    "operator": "Or",
+    "tags": {
+        "values": ["Production"],
+        "operator": "Or"
+    }
+}
+```
+
+And embedded at the top of `executableRule` (applies to every entry in `executableRule.values[]`):
+
+```json
+"executableRule": {
+    "values": [
+        { "type": "AgenticProcess", "values": ["*"], "operator": "Or" }
+    ],
+    "tags": {
+        "values": ["Production"],
+        "operator": "Or"
+    }
+}
+```
+
+---
+
+## Update-flow use
+
+When `policy-manage-guide.md — Update` needs to change tags on an existing block:
+
+1. Start from the existing `tags` object in the working file (copied from `.Data` in the update prelude).
+2. Mutate only the fields the user asked about — add/remove entries in `values`, or flip `operator`.
+3. If the user wants to remove tag filtering entirely, delete the `tags` key (do not leave behind an empty object).
+
+Example: the user says "also exclude Staging". Existing:
+
+```json
+{ "values": ["Development"], "operator": "None" }
+```
+
+After update:
+
+```json
+{ "values": ["Development", "Staging"], "operator": "None" }
+```
+
+---
+
+## Debug
+
+| Error / symptom | Cause | Fix |
+|-----------------|-------|-----|
+| `400 Bad Request` / `Tags.Values is required` | `tags.values` is missing or empty | Either populate with at least one tag, or remove the `tags` key entirely. |
+| `400 Bad Request` / unknown operator | Typo (e.g. `"or"`, `"NOT"`, `"Not"`) | Use exactly `"Or"`, `"And"`, or `"None"` — case-sensitive. |
+| Policy never matches anything at runtime | Tag name doesn't exist in the Resource Catalog of the policy's tenant, or target resource isn't labeled with it | Verify the tag with `uip admin rcs tag list --output json` (no `--tenant` — the default targets the policy's own tenant). See [resource-lookup-guide.md § 4](../../resource-lookup-guide.md#4-resource-catalog-tags). If the tag is missing, add it to the Resource Catalog of the policy's tenant or pick a tag from the returned list. |
+| `None` operator matches more than expected | `None` excludes only the named tags — everything else matches | If the user meant "only these and nothing else", they want `Or`, not `None`. Re-check intent with them. |
+| API rejected `enforcement: "Deny"` | The skill emitted `enforcement: "Deny"` — never authorable (Critical Rule #2) | Switch to `enforcement: "Allow"` and re-author. See [planning.md — Deny-to-Allow flip](./planning.md#deny-to-allow-flip). |

package/skills/uipath-governance/references/access-policy/plugins/tags/planning.md

@@ -0,0 +1,117 @@
+# Tags Plugin — Planning
+
+> **User-facing terminology vs JSON field.** User-facing label: **tag filter**. JSON field: `tags` sub-object — shown only in code / CLI contexts.
+
+The `tags` sub-object is the shared **Resource Catalog Tag** filter used inside selector entries and inside `executableRule`. It is the primary mechanism for scoping an access policy to a subset of resources / executables without listing individual UUIDs.
+
+## When to Use
+
+Add a `tags` sub-object to a `selectors[]` entry or to `executableRule` whenever the user mentions a tag-style attribute on the Resource or Actor Process side. Omit the entire `tags` key when no tag constraint applies. **Resource Catalog Tags** are labels assigned to resources in the UiPath Resource Catalog; the `tags` sub-object matches on those labels at evaluation time.
+
+> `actorRule` does **not** support `tags` today — never emit `actorRule.tags`.
+
+## Block shape (conceptual)
+
+```text
+tags = { values: ["<tag1>", "<tag2>", ...], operator: <Or | And | None> }
+```
+
+- `values` — list of tag names. Must be non-empty when the `tags` key is present. Omit the whole key when there are no tag constraints.
+- `operator` — how `values` is applied. One of `Or` (Any-of), `And` (All-of), `None` (Exclude).
+
+## Operator semantics
+
+| Operator | Meaning | Example phrasing |
+|----------|---------|------------------|
+| `Or` | Match resources with **any** of the listed tags | "Production or Staging agents" |
+| `And` | Match resources with **all** of the listed tags | "agents tagged both Production and Critical" |
+| `None` | **Exclude** resources with any of the listed tags | "agents not tagged Development" |
+
+Worked mental model:
+
+- `{ values: ["Production", "Staging"], operator: "Or" }` → matches resources tagged Production **or** Staging.
+- `{ values: ["Production", "Critical"], operator: "And" }` → matches resources tagged Production **and** Critical.
+- `{ values: ["Development"], operator: "None" }` → matches resources **not** tagged Development.
+
+## Common Resource Catalog tag names
+
+The Resource Catalog tag set is tenant-specific, but these names recur across UiPath environments:
+
+- **Environment:** `Production`, `Development`, `Staging`, `Test`
+- **Criticality / data class:** `Critical`, `PII`, `Confidential`
+- **Team / org:** `Finance`, `Marketing`, `HR`, `Platform`
+- **Product / domain:** user-specific product names
+
+> Tags the user mentions must actually exist in the Resource Catalog of the **policy's own tenant** (the tenant in `~/.uipath/.auth`). A policy that references `DoesNotExist` silently matches nothing. **Confirm tag names during Phase 1** before approving the Spec by running `uip admin rcs tag list --output json` (no `--tenant` — the default targets the policy's tenant; see [resource-lookup-guide.md § 4](../../resource-lookup-guide.md#4-resource-catalog-tags)). If the tag is missing, surface it as an Open question and ask the user to either pick a returned tag or add the missing one to the Resource Catalog before the JSON is composed.
+
+## Deny-to-Allow flip
+
+> **Internal mechanic — not user-facing copy.** Do NOT surface "Deny-to-Allow flip", "None operator", or "enforcement: Deny is not authorable" jargon to the user. The Spec narrative describes the policy in plain English of **what's allowed** — the flip happens silently inside the agent.
+
+Access policies of type `ToolUsePolicy` only support `enforcement: "Allow"` (Critical Rule #2) — `enforcement: "Deny"` is **not authorable**. Intent phrased as Deny must be reframed as an equivalent Allow rule. Two equivalent shapes; pick whichever produces the clearer Spec narrative:
+
+- **Reframe scope.** Translate to "Allow only `<positive-set>`" and target it with `operator: "Or"`. Example: "Deny Development agents" → "Allow only Production / Staging agents" with `tags: { values: ["Production", "Staging"], operator: "Or" }`.
+- **`None`-operator flip.** Keep "everything except X" framing and emit `operator: "None"` on the relevant `tags` or `values`. The rest of this section walks through the `None`-operator pattern.
+
+### When to flip via tags
+
+| User phrasing | Flipped intent | `tags` |
+|---------------|----------------|--------|
+| "Deny Development agents" | Allow agents **except** Development-tagged | `{ values: ["Development"], operator: "None" }` |
+| "Block Staging resources" | Allow resources **except** Staging | `{ values: ["Staging"], operator: "None" }` |
+| "Prevent PII-tagged data being used by flows" | Allow flows to use everything **except** PII-tagged | `{ values: ["PII"], operator: "None" }` on the selector |
+
+### Decision procedure for Deny intent
+
+1. Identify the negative predicate (the set the user wants to exclude).
+2. Check whether the predicate is expressible as a tag (or set of tags) on the resource or executable.
+3. If yes, emit the affirmative complement on the correct block:
+   - Deny by **resource attribute** → `None` on the selector's `tags`.
+   - Deny by **caller attribute** → `None` on the `executableRule`'s `tags`.
+4. If the predicate is over UUIDs rather than tags, use `operator: "None"` on `values` instead (see [selector/planning.md](../selector/planning.md) and [executable/planning.md](../executable/planning.md)).
+5. If no clean flip exists (e.g. "deny for user X" — that is an actor predicate and the access policy cannot express it as a tag filter), stop and consult [actor/planning.md](../actor/planning.md).
+
+### Three worked flips
+
+**A. Single tag.** "Deny Development agents" → selector `tags: { values: ["Development"], operator: "None" }`.
+
+**B. Multiple tags.** "Block Development or Staging flows" → selector (`resourceType: Flow`) `tags: { values: ["Development", "Staging"], operator: "None" }`. The `None` operator on multiple values excludes resources tagged with **any** of them.
+
+**C. Mixed tag + UUID exclusion.** "Block specific process `xyz-789` and everything tagged Development" — two parts. Flip the UUID exclusion onto `values` with `operator: "None"`, and flip the tag exclusion onto `tags` with `operator: "None"`. These go on the same selector entry. Note that this does not combine cleanly when the user also wants an include; split into two selectors or escalate to the user.
+
+## Decision tree: picking the operator
+
+```text
+Is the user denying / excluding something?
+├── yes → operator: None   (and go read the Deny-to-Allow flip section above)
+└── no  → Is the user listing alternatives ("Production or Staging")?
+           ├── yes → operator: Or
+           └── no  → Is the user requiring all tags at once ("both X and Y")?
+                      ├── yes → operator: And
+                      └── no  → default to Or with a single tag, or omit tags entirely
+```
+
+## Where the block lives
+
+The same `tags` shape appears in two blocks of the access policy:
+
+| Block | Effect |
+|-------|--------|
+| `selectors[].tags` | Narrows the set of **resources** a selector matches (Selection Rule). |
+| `executableRule.tags` | Narrows the set of **Actor Processes** (callers) — applies across all entries in `executableRule.values[]`. |
+
+> **`actorRule` does NOT support tags today.** Identity-side tag filters are unsupported — emitting `actorRule.tags` returns `400 Bad Request`. Enumerate the matching users / groups directly under `actorRule.values[].values` instead. See [actor/planning.md](../actor/planning.md) and Critical Rule #5.
+
+There is no per-entry `tags` inside `executableRule.values[]`. If different entry types need different tag filters, split into two policies.
+
+## Anti-patterns
+
+- Do NOT emit `enforcement: "Deny"` ever. The API does not support it (Critical Rule #2). Reframe the user's intent as Allow + scope filter, or use `operator: "None"` on `tags` / `values` to express "everything except X".
+- Do NOT invent tag names. If the user hasn't confirmed a tag exists in the Resource Catalog, run `uip admin rcs tag list --output json` against the policy's tenant (the default — no `--tenant`) and ask the user to pick from the returned list.
+- Do NOT pass an empty `values: []` array. Either include at least one tag, or omit the entire `tags` key.
+- Do NOT use `operator: "And"` with a single tag — it's equivalent to `Or` with one tag; use `Or` for clarity.
+- Do NOT confuse Resource Catalog Tags with executable `type` or with free-text descriptions. Only named labels assigned in the Resource Catalog qualify.
+
+## Next: compose the JSON
+
+When Phase 2 needs the concrete JSON for a `tags` block, read [tags/impl.md](./impl.md).