PSA/ee/docs/plans/2026-04-27-workflow-project-actions/SCRATCHPAD.md

# SCRATCHPAD — Workflow Project Actions

- Slug: `workflow-project-actions`
- Date: `2026-04-27`
- Status: Discovery / PRD convergence

## Initial request

Add workflow actions for project-management entities:

- FIND task / phase / project
- MOVE task (to different status + phase, or project + phase + status)
- RENAME task / phase / project
- ASSIGN task
- DUPLICATE task
- DELETE task / phase / project
- LINK TICKET to task
- ADD TAG to task or project
- EDIT task / phase / project description

## Context from request

Workflow actions are server-registered through `shared/workflow/runtime/registries/actionRegistry.ts`, commonly in `shared/workflow/runtime/actions/registerBusinessOperationsActions.ts` and domain files under `shared/workflow/runtime/actions/businessOperations/`.

Action schemas are Zod schemas converted to JSON Schema and consumed by the workflow designer. Picker/editor metadata can be attached via schema descriptions and normalized into `ActionInputField.editor`. Picker-backed fields should use `x-workflow-editor` where possible, with legacy picker metadata still supported.

## Repository discoveries

- Existing project workflow action file: `shared/workflow/runtime/actions/businessOperations/projects.ts`.
- Existing registered project action: `projects.create_task`.
- It already validates project, optional phase, optional project_task status, optional user/team assignee, optional ticket link, writes audit, and returns task URL/status metadata.
- Existing ticket action code has a generic ticket-to-entity pattern in `shared/workflow/runtime/actions/businessOperations/tickets.ts`, including `project` and `project_task` entity types.
- Plans live under `ee/docs/plans/YYYY-MM-DD-<slug>/` with `PRD.md`, `features.json`, `tests.json`, and `SCRATCHPAD.md`.

## Open questions

- Need decide whether FIND actions are exact-ID lookup actions, criteria/search actions, or both.
- Need define destructive delete semantics for phases/projects/tasks.
- Need define duplicate semantics for tasks (comments/checklists/tags/ticket links/time entries/subtasks?).
- Need confirm picker support needed for project/phase/task/status/tag resources in workflow fixed-value inputs.

## Decisions

- FIND scope: use both exact lookup and search/list-style actions, following existing workflow action patterns.
- Pattern fidelity is a primary design constraint. Existing examples:
  - `clients.find`: exact lookup by id/name/external ref with `on_not_found` and nullable output.
  - `clients.search`: query + filters + pagination, returns array, first result, page metadata, total.
  - `contacts.find` / `contacts.search`: same split.
  - `tickets.find`: exact lookup by id/number/external ref with optional include flags.
- Proposed PRD direction: project entities should mirror that split rather than inventing separate `get` naming unless the registry already uses it elsewhere.

- Delete semantics decision: target soft/archive semantics where the project domain supports them; use hard delete only where the domain's existing behavior is genuinely hard delete. Preserve existing domain guards and avoid workflow-specific cascade behavior.
## Delete/move/duplicate implementation fidelity discoveries

- User decision: delete semantics should mirror existing project UI/domain behavior exactly.
- Existing task delete UI action (`packages/projects/src/actions/projectTaskActions.ts`) checks `project:delete`, validates project read access, refuses delete when associated `time_entries` exist, deletes ticket links, deletes checklist items, then deletes `project_tasks`.
- Existing phase delete UI action (`packages/projects/src/actions/projectActions.ts`) checks `project:delete`, validates project read access, then calls `ProjectModel.deletePhase`.
- Existing project delete UI action (`packages/projects/src/actions/projectActions.ts`) uses `deleteEntityWithValidation('project', ...)`, cleans up project tags, task tags under phases, project ticket links, email reply tokens, then deletes through `ProjectModel.delete`.
- Existing API service (`server/src/lib/api/services/ProjectService.ts`) has simpler hard-delete methods, but workflow plan should prefer UI/domain action semantics when they are richer.
- Existing task move UI action: `moveTaskToPhase` supports target phase, optional target status mapping, optional target project, optional before/after positioning. It remaps status mappings on same-project phase moves and cross-project moves if no explicit target status is provided, regenerates WBS/order key, and updates ticket link project/phase references.
- Existing task duplicate UI action: `duplicateTaskToPhase` supports target phase, optional new status mapping, and options for primary assignee, additional assignees, checklist, and ticket links. It appends ` (Copy)`, resets actual hours to 0, creates task, optionally copies related records, and emits workflow events.

## Update action decision

- User decision: use generic update actions, not separate narrow rename/edit-description actions.
- PRD direction:
  - `projects.update` covers project name and description edits, plus only other fields intentionally included by this plan.
  - `projects.update_phase` covers phase name and description edits, plus only other fields intentionally included by this plan.
  - `projects.update_task` covers task title/name, description, assignment, status, phase/project move-adjacent fields only if they do not conflict with the dedicated move action. Prefer dedicated `projects.move_task` for phase/project/status relocation because existing domain logic is non-trivial.
- Avoid palette/action sprawl for `rename_*` and `edit_*_description` variants.

## Assignment action decision

- User decision: use a dedicated `projects.assign_task` action, matching `tickets.assign` fidelity.
- PRD direction:
  - Keep task assignment out of generic `projects.update_task` except possibly preserving current assignment when other fields update.
  - `projects.assign_task` should follow `tickets.assign` shape where practical: required assignment target, optional reason/comment if useful, `no_op_if_already_assigned` default true, output task id/assigned target/updated timestamp.
  - Existing project task model supports `assigned_to` primary user and additional task resources. Need decide if workflow assignment supports only primary user in v1 or primary + additional users.

## Task assignment model decision

- User decision: `projects.assign_task` should support primary user + additional users.
- PRD direction:
  - Primary assignee maps to `project_tasks.assigned_to`.
  - Additional users map to task resource/additional assignment records, matching existing project task UI/domain behavior.
  - Do not invent team assignment unless existing project task resource semantics support it; the first-class workflow task assignment model is user-centric.
  - Provide no-op behavior when primary and additional users already match, mirroring `tickets.assign`.

## Tag behavior discovery/decision

- User instruction: look at contact workflow/tag behavior and match it.
- There is no dedicated `contacts.add_tag` workflow action today; contact/client workflow search actions filter by existing tag text through `tag_mappings` + `tag_definitions` joins.
- Existing ticket workflow create/update tag handling creates missing `tag_definitions`, inserts mappings, treats duplicate mappings as no-op, and normalizes/uniquifies trimmed tag text.
- Existing generic tag domain action `createTag` also get-or-creates tag definitions, requires entity update permission, requires `tag:create` only when the definition is new, creates the mapping, and publishes tag events.
- `createTagsForEntityWithTransaction` get-or-creates definitions and continues on per-tag failures; this is used by imports including project task import.
- PRD direction: `projects.add_tag` should match existing tag application semantics: trim/validate tag text, get-or-create tag definition for tagged type (`project` or `project_task`), insert mapping idempotently/no-op on duplicate, use existing color generation/definition colors, and respect tag permissions when practical.
- Need be careful that workflow runtime direct DB implementation should either reproduce permission requirements or call shared tag-domain helper if callable from workflow runtime.

- Follow-up search for user-mentioned `Add Tag to Contact`: current worktree search did not find a dedicated workflow contact add-tag action in `shared/workflow/runtime/actions/businessOperations/contacts.ts` or elsewhere under workflow runtime. It may be in another branch/module or not present in this worktree.
- Concrete tag behavior found in `packages/tags/src/actions/tagActions.ts#createTag`: validates non-empty tag text, trims, max 50 chars, character whitelist, requires target entity update permission, requires `tag:create` only if creating a new definition, get-or-creates `tag_definitions`, inserts `tag_mappings`, publishes `TAG_DEFINITION_CREATED` and `TAG_APPLIED`, and returns the mapping id as `tag_id` for compatibility.

## Tag action behavior decision/discovery

- User direction: match the existing workflow contact module's `contacts.add_tag` behavior.
- Existing `contacts.add_tag` behavior:
  - Action id: `contacts.add_tag`.
  - Input: `contact_id`, `tags: string[]`, optional `idempotency_key`.
  - Side-effectful with `idempotency: { mode: 'actionProvided', key: actionProvidedKey }`.
  - Requires `{ resource: 'contact', action: 'update' }`.
  - Ensures the contact exists.
  - Normalizes/uniques tag text.
  - Creates missing tag definitions for `tagged_type: 'contact'` with generated colors.
  - Inserts tag mappings idempotently via conflict ignore.
  - Returns `added`, `existing`, `added_count`, `existing_count`.
  - Writes run audit.
- PRD direction:
  - Add project/task tag actions should create missing tag definitions and idempotently attach mappings, not fail on missing tags.
  - Match output shape and idempotency behavior from `contacts.add_tag`.
  - Use resource permissions appropriate to the target entity (`project:update`; task likely project update after project/task read scoping, matching existing project task actions).

## Tag action shape decision

- User decision: two resource-specific actions.
- PRD direction:
  - `projects.add_tag` attaches tags to a project.
  - `projects.add_task_tag` attaches tags to a project task.
  - Both mirror `contacts.add_tag` behavior and output shape.

## Ticket-to-task link decision

- User decision: workflow task-ticket link should write both `project_ticket_links` and `ticket_entity_links`.
- PRD direction:
  - Add action likely named `projects.link_ticket_to_task`.
  - Validate task, its phase/project, and ticket exist.
  - Require appropriate project update and ticket read permissions, matching existing UI behavior plus workflow business action conventions.
  - Insert `project_ticket_links` idempotently/best-effort where duplicate constraints exist.
  - Insert/ensure `ticket_entity_links` with `entity_type: 'project_task'`, `entity_id: task_id`, `link_type: 'project_task'`, and metadata containing project/phase IDs, matching `projects.create_task` precedent.
  - Return IDs and counts/created-vs-existing indicators if practical.

## Picker/editor support decision

- User decision: hybrid picker support.
- PRD direction:
  - Add workflow fixed-value picker/editor support for project, phase, project task, and project task status/status mapping where needed.
  - Keep tag entry as free-text string array, matching `contacts.add_tag`; no tag picker in this plan.
  - Use dependency metadata so phase/task/status pickers can depend on selected project/phase as applicable.

## PRD approval

- User approved the PRD scope on 2026-04-27.
- Estimated feature list size: medium/large workflow action expansion, roughly 60-75 atomic features because it spans handler schemas, action behavior, permissions/audit, tag/link helpers, and designer picker support.
- Test plan should be Pareto-focused: DB-backed action handler coverage for representative read/update/mutation/destructive paths, plus picker metadata/designer resource coverage.


## Implementation checkpoint — 2026-04-27 (Find/Search foundation)

### Completed features

- `F001`: Added shared workflow schemas in `shared/workflow/runtime/actions/businessOperations/projects.ts` for:
  - `projectSummarySchema`
  - `phaseSummarySchema`
  - `taskSummarySchema`
  - `statusMappingSummarySchema`
  - `tagResultSchema`
  - `assignmentResultSchema`
  - `linkResultSchema`
  Rationale: establishes canonical output schema contracts for new action family.

- `F002`: Added reusable entity/context loaders with standardized `NOT_FOUND` errors:
  - `ensureProjectExists`
  - `ensurePhaseExists`
  - `ensureTaskContext`
  - `ensureTicketExists`
  - `ensureStatusMappingExists`
  Rationale: avoid repeated ad-hoc lookup/error logic across action handlers.

- `F003`: Added reusable permission + narrowing helpers:
  - `requireProjectReadPermission`
  - `requireProjectUpdatePermission`
  - `requireProjectDeletePermission`
  - `canReadProject` / `assertProjectReadable`
  Rationale: centralizes project read/auth narrowing behavior and future-proofs update/delete action implementation.

- `F004`: Added project picker metadata helpers and kinds:
  - picker kinds: `project`, `project-phase`, `project-task`, `project-task-status`
  - helper: `withWorkflowPicker`
  Rationale: fixed-value mode can render dependency-aware project entity pickers.

- `F005` + `F006`: Implemented `projects.find` schema + handler:
  - supports `project_id`, exact `name`, optional `external_ref`, `on_not_found`
  - enforces tenant scoping + project read permission + auth narrowing
  - returns nullable `project` summary output

- `F007` + `F008`: Implemented `projects.search` schema + handler:
  - query + filters + pagination
  - deterministic ordering + `first_project` + `total`
  - authorization-filtered results

- `F009` + `F010`: Implemented `projects.find_phase` schema + handler:
  - supports `phase_id` or project-scoped exact `name`
  - supports `on_not_found`
  - enforces project read auth via phase->project context validation

- `F011` + `F012`: Implemented `projects.search_phases` schema + handler:
  - supports project scope, query, filters, pagination
  - deterministic ordering + `first_phase` + `total`
  - auth-filtered by parent project visibility

- `F013` + `F014`: Implemented `projects.find_task` schema + handler:
  - supports `task_id` or scoped exact task `name`
  - supports `on_not_found`
  - validates task->phase->project context and project read authorization

- `F015` + `F016`: Implemented `projects.search_tasks` schema + handler:
  - supports query + project/phase/status mapping/status/assignee/tag filters
  - returns `tasks`, `first_task`, page metadata, total
  - tenant-scoped + project-auth filtered

### Completed tests

- `T001`: Added `shared/workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts`
  - validates registration, labels, side-effect/idempotency metadata, category
  - validates picker metadata presence and dependencies for project/phase/task/status fields

- `T002` + `T003` + `T004`: Added DB-backed tests in
  `shared/workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`
  - covers `projects.find` + `projects.search` happy paths, not-found behavior, pagination/tenant scoping
  - covers `projects.find_phase` + `projects.search_phases` project scoping and deterministic ordering
  - covers `projects.find_task` + `projects.search_tasks` scoped lookups, filters, first/total/page metadata

### Commands / runbook used

- Targeted test run:
  - `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`

### Gotchas discovered

- Shared runtime package does not resolve `@alga-psa/authorization/kernel` in this test runtime; switched to local schema-aware read narrowing helper.
- Test DB schema differs from legacy assumptions (`project_number` required; status column variants; user/client columns vary); test fixtures were made column-aware via `information_schema` checks.
- Throwing standardized action objects inside try/catch requires pass-through handling; otherwise generic rethrow path can incorrectly map to `INTERNAL_ERROR`.

## Implementation checkpoint — 2026-04-27 (Generic update actions)

### Completed features

- `F017` + `F018`: Implemented `projects.update` schema+handler:
  - non-empty patch validation (`project_name`, `description`)
  - project update permission + project read auth check
  - changed-field diffing + `no_op` support
  - output includes updated project summary + changed metadata
  - workflow run audit writes include `changed_fields` and `no_op`

- `F019` + `F020`: Implemented `projects.update_phase` schema+handler:
  - non-empty patch validation (`phase_name`, `description`)
  - phase->project context validation
  - project update permission + read auth check
  - changed-field output + `no_op` + run audit

- `F021` + `F022`: Implemented `projects.update_task` schema+handler:
  - non-empty patch validation for task `task_name` and `description`
  - excludes move/status relocation fields by schema design
  - task->phase->project context validation
  - project update permission + read auth check
  - changed-field output + `no_op` + run audit

### Completed tests

- `T006`: Added DB-backed coverage for update happy paths and audit writes:
  - validates name/description updates for project, phase, and task
  - checks returned changed fields/no-op flags
  - asserts audit log operation records exist for all three update actions

- `T007`: Added DB-backed validation/permission guard coverage:
  - empty patch rejects at schema parse time
  - missing project/phase/task returns `NOT_FOUND`
  - denied `project:update` returns `PERMISSION_DENIED`
  - verifies denied update does not mutate persisted project data

### Checklist correction

- `T001` was initially marked complete during the first checkpoint but that was premature because it requires registration coverage for the full final project action surface. Reset to `implemented:false` until the full action set is present.

## Implementation checkpoint — 2026-04-27 (Task move action)

### Completed features

- `F023`: Added `projects.move_task` input schema with:
  - `task_id`
  - `target_phase_id`
  - optional `target_project_status_mapping_id`
  - optional `target_project_id`
  - optional `before_task_id` / `after_task_id` (mutually exclusive)
  - picker metadata and dependency wiring for project/phase/task/status fields

- `F024` + `F025`: Implemented status remap/default resolution when explicit status mapping is omitted:
  - attempts same-project mapping reuse
  - attempts same underlying status id mapping in target project
  - falls back to first visible target project mapping by display order
  - cross-project path uses target-project mappings only

- `F026`: Implemented move-time WBS/order metadata updates:
  - regenerates `wbs_code` based on target phase WBS + next ordinal
  - updates `order_key` when supported by schema

- `F027`: Implemented `project_ticket_links` context rewrite on move:
  - updates `project_id` + `phase_id` for all links tied to moved `task_id`

- `F028`: Added move output schema/result payload with previous/current project/phase/status mapping/status ids plus updated WBS/order/updated_at.

- `F029`: Added permission checks, validation errors, and workflow run audit logging for `projects.move_task`.

### Completed tests

- `T008`: DB-backed same-project move test validates:
  - phase relocation
  - status mapping/status resolution non-null path
  - WBS/order metadata change
  - move audit record creation

- `T009`: DB-backed cross-project move test validates:
  - target project/phase assignment
  - status mapping resolution in target project
  - `project_ticket_links` project/phase context updates

- `T010`: DB-backed validation guard test validates:
  - missing task => `NOT_FOUND`
  - missing target phase => `NOT_FOUND`
  - invalid explicit target mapping => `VALIDATION_ERROR`

### Gotchas discovered

- Ticket fixture schema for this branch requires adaptive field population (e.g., `client_id` constraints and varying timestamp columns), so the test helper was made schema-aware via `information_schema`.
- Same-project status remap behavior can legitimately keep source mapping in some fixture shapes; tests were adjusted to verify remap outcomes without over-constraining mapping identity.

## Implementation checkpoint — 2026-04-27 (Task assignment action)

### Completed features

- `F030`: Added `projects.assign_task` input schema:
  - `task_id`
  - `primary_user_id`
  - `additional_user_ids` (array; deduped)
  - optional `reason`
  - `no_op_if_already_assigned` default `true`
  - optional `idempotency_key`
  - schema guard that rejects `additional_user_ids` containing the primary user

- `F031`: Added assignment user resolution helper for active tenant users:
  - validates primary user exists and is active
  - validates all additional users exist and are active
  - enforces internal-user filtering where user schema supports `user_type`
  - returns deterministic deduped/sorted additional user ids

- `F032`: Implemented no-op comparison for assignment requests:
  - compares current `project_tasks.assigned_to`
  - compares current `task_resources.additional_user_id` set
  - honors `no_op_if_already_assigned` (default true)

- `F033`: Implemented assignment mutation and additional-user reconciliation:
  - updates `project_tasks.assigned_to`
  - clears `assigned_team_id` when present
  - replaces `task_resources` rows for the task with the resolved additional users

- `F034`: Implemented assign action output shape:
  - `task_id`, `assigned_to`, `additional_user_ids`, `no_op`, `updated_at`

- `F035`: Added permission checks and run audit logging for `projects.assign_task`:
  - requires `project:update`
  - validates project readability through task->phase->project context
  - writes `workflow_action:projects.assign_task` audit rows for both no-op and mutation paths

### Completed tests

- `T011`: Added DB-backed happy-path assignment test validating:
  - primary assignee change
  - additional-user reconciliation in `task_resources`
  - deterministic output
  - audit record creation

- `T012`: Added DB-backed no-op test validating:
  - identical requested assignment returns `no_op: true`
  - task `updated_at` unchanged when no-op short-circuits

- `T013`: Added DB-backed validation failure test validating:
  - inactive primary user rejected
  - missing additional user rejected
  - no partial mutation of `project_tasks.assigned_to` or existing `task_resources`

### Commands/runbook used

- `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`

### Gotchas discovered

- `task_resources` has no uniqueness constraint on (`task_id`, `additional_user_id`), so reconciliation uses delete+reinsert to keep assignment state canonical.
- UUID lexical ordering is non-semantic; tests were adjusted to compare additional-user sets order-insensitively where needed.

## Implementation checkpoint — 2026-04-27 (Task duplicate action)

### Completed features

- `F036`: Added `projects.duplicate_task` input schema with:
  - `source_task_id`
  - `target_phase_id`
  - optional `target_project_status_mapping_id`
  - copy toggles for primary assignee, additional assignees, checklist, and ticket links

- `F037`: Implemented core duplicate behavior:
  - clones source task into target phase
  - appends ` (Copy)` suffix to task name
  - preserves estimated hours when schema supports it
  - resets actual hours to `0` when schema supports it
  - resolves target status mapping/status similarly to move semantics

- `F038`: Implemented optional checklist copy:
  - copies `task_checklist_items` rows to new task with new ids/timestamps
  - returns copied checklist count

- `F039`: Implemented optional assignment copy:
  - optional primary assignment copy to `project_tasks.assigned_to`
  - optional additional assignment copy via `task_resources`
  - clears `assigned_team_id` on duplicates when that column exists

- `F040`: Implemented optional ticket link copy with permission-aware filtering:
  - checks `ticket:read` permission before copying links
  - copies `project_ticket_links` into target project/phase/task context
  - writes matching `ticket_entity_links` records for duplicated task links

- `F041`: Added duplicate action output schema:
  - source/new task ids
  - target project/phase/status mapping/status ids
  - copied relation counts
  - `created_at`

- `F042`: Added permission checks and run audit logging:
  - requires `project:create` and project read checks for source/target context
  - writes `workflow_action:projects.duplicate_task` audit with target ids and copied counts

### Completed tests

- `T014`: DB-backed duplicate core behavior test validates:
  - new task creation in target phase/project
  - ` (Copy)` suffix
  - description copy
  - estimated-hours preservation + actual-hours reset when columns exist
  - status mapping/status target metadata in output

- `T015`: DB-backed optional relation copy test validates:
  - checklist copy count and persisted copied checklist rows
  - primary/additional assignment copy count and `task_resources` rows
  - ticket-link copy count and copied `project_ticket_links` target context

### Commands/runbook used

- `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`

### Gotchas discovered

- `task_checklist_items`/`task_resources`/`project_tasks` schemas vary slightly across migrations in this branch; test fixtures and assertions were kept column-aware to avoid false failures.
- `task_resources` assignment rows are easiest to keep coherent via full-row clone with refreshed ids/timestamps and target task id, while overriding `assigned_to` according to copy options.

## Implementation checkpoint — 2026-04-27 (Delete task/phase/project actions)

### Completed features

- `F043`: Added `projects.delete_task` input/output schemas with cleanup count fields:
  - input: `task_id`
  - output: `task_id`, `deleted`, `deleted_ticket_link_count`, `deleted_checklist_item_count`

- `F044`: Implemented delete-task guard for associated project task time entries:
  - checks `time_entries` by `work_item_type='project_task'` and `work_item_id=task_id`
  - rejects with `VALIDATION_ERROR` when entries exist

- `F045`: Implemented delete-task cleanup flow mirroring UI semantics:
  - deletes task ticket links
  - deletes task checklist items
  - removes task resources and task-side ticket entity links before deleting task row

- `F046`: Added delete-task permission checks and audit logging:
  - requires `project:delete`
  - validates task->project context readability
  - writes `workflow_action:projects.delete_task` run audit

- `F047`: Added `projects.delete_phase` input/output and handler:
  - input: `phase_id`
  - output: `phase_id`, `project_id`, `deleted`
  - deletes phase with project context validation

- `F048`: Added delete-phase validation, permissions, standardized errors, and audit logging:
  - requires `project:delete`
  - validates phase + project context and readability
  - writes `workflow_action:projects.delete_phase` run audit

- `F049`: Added `projects.delete` input/output schemas exposing validation/result fields:
  - input: `project_id`
  - output includes `success`, `deleted`, `can_delete`, `code`, `message`, `dependencies`, `alternatives`

- `F050`: Implemented project delete handler with cleanup behavior:
  - collects phase/task descendants
  - blocks delete when descendant task time entries exist
  - cleans up project tags + task tags (`tag_mappings`)
  - cleans up project/task ticket links and project email reply tokens
  - removes descendant tasks/phases then project row

- `F051`: Added delete-project permission checks, failure shape, and run audit logging:
  - requires `project:delete`
  - returns structured validation failure result when blocked
  - writes `workflow_action:projects.delete` run audit on mutation path

### Completed tests

- `T016`: DB-backed destructive task-delete happy path validates:
  - ticket-link + checklist cleanup counts
  - task row removed
  - related checklist/link rows removed

- `T017`: DB-backed destructive guard test validates:
  - task delete rejected when project_task time entries exist
  - task/checklist/link rows remain intact

- `T018`: DB-backed destructive phase/project delete coverage validates:
  - phase delete happy path
  - project delete happy path including cleanup of project/task tags, project ticket links, and email reply tokens
  - project delete validation-failure path when descendant task time entries exist

### Commands/runbook used

- `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`

### Gotchas discovered

- `time_entries` schema in this branch requires additional non-null columns (e.g., `work_date`, `work_timezone`), so destructive guard fixtures needed column-aware inserts.
- Project delete cleanup needs to tolerate optional tables (`email_reply_tokens`, `task_resources`, `ticket_entity_links`) across schema variants; helper deletion logic was made table-existence-aware.

## Implementation checkpoint — 2026-04-27 (Ticket-link + tag actions)

### Completed features

- `F052`: Added `projects.link_ticket_to_task` input schema:
  - `task_id`, `ticket_id`, optional `project_id`, optional `phase_id`, optional `idempotency_key`
  - picker metadata and dependency paths for task/project/phase context fields

- `F053`: Added task/ticket/project/phase validation for link action:
  - validates task context exists
  - validates ticket exists
  - validates optional project/phase inputs match task context

- `F054`: Implemented ensure/insert behavior for `project_ticket_links`:
  - idempotent existing-link detection
  - insert-on-miss with created vs existing signaling

- `F055`: Implemented ensure/insert behavior for `ticket_entity_links`:
  - `entity_type='project_task'`, `entity_id=task_id`, `link_type='project_task'`
  - metadata includes project/phase ids
  - created vs existing signaling

- `F056`: Added link output schema with idempotency indicators and resolved ids:
  - `project_ticket_link_id`, `ticket_entity_link_id`
  - `project_ticket_link_created`, `ticket_entity_link_created`

- `F057`: Added permission checks + run audit logging for link action:
  - requires `project:update`
  - writes `workflow_action:projects.link_ticket_to_task`

- `F058`: Added shared project/project-task tag helper behavior mirroring `contacts.add_tag`:
  - tag normalization + dedupe
  - generated colors
  - tag definition upsert (conflict ignore)
  - mapping insert conflict ignore
  - returns `added` + `existing`

- `F059`: Implemented `projects.add_tag`:
  - schema with `project_id`, `tags[]`, optional `idempotency_key`
  - action-provided idempotency metadata
  - project validation + `project:update` permission
  - added/existing counts + audit logging

- `F060`: Implemented `projects.add_task_tag`:
  - schema with `task_id`, `tags[]`, optional `idempotency_key`
  - action-provided idempotency metadata
  - task/project context validation + `project:update` permission
  - added/existing counts + audit logging

### Completed tests

- `T019`: DB-backed link action happy path validates both link tables and project/phase metadata.
- `T020`: DB-backed link idempotency test validates repeat calls do not duplicate effective links and report existing state.
- `T021`: DB-backed project tag action test validates definition creation, idempotent mappings, and added/existing counts.
- `T022`: DB-backed project-task tag action test validates definition creation, idempotent mappings, and added/existing counts.

### Commands/runbook used

- `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`

### Gotchas discovered

- `project_ticket_links`/`ticket_entity_links` idempotency needed explicit existing-row fallback because unique constraints vary by schema/migration state.
- Tag helper had to be column-aware for `tag_definitions`/`tag_mappings` to remain robust across branch schema variants.

## Implementation checkpoint — 2026-04-27 (Picker resources + compatibility closeout)

### Completed features

- `F061`: Registered project fixed-picker resource support in workflow designer pickers:
  - added `project` to supported fixed-picker resources
  - picker now routes through fixed-value control path alongside existing resources

- `F062`: Registered project-phase picker resource support with dependency handling:
  - added `project-phase` support
  - dependency hint defaults include `project_id`, `target_project_id`, and `filters.project_id`

- `F063`: Registered project-task picker resource support with dependency handling:
  - added `project-task` support
  - dependency hint defaults include project + phase scoped paths (`project_id`, `phase_id`, `target_project_id`, `target_phase_id`, filter variants)

- `F064`: Registered project-task-status picker support with dependency handling:
  - added `project-task-status` support
  - dependency hint defaults include project + phase scoped paths and filter variants

- `F065`: Ensured dependency-aware picker metadata is honored end-to-end in fixed-value mode:
  - new project/phase/task/status kinds surface dependency-disabled explanations until upstream fixed values are provided
  - preserved no-tag-picker behavior (tags remain free-text arrays)

- `F066`: Confirmed new project actions are present in workflow registry metadata with labels/descriptions/categories/schema/side-effect-idempotency metadata.

- `F067`: Confirmed side-effectful project actions continue using standardized action errors, tenant-scoped mutations, and workflow run audit records.

- `F068`: Verified `projects.create_task` compatibility remains intact after shared helper/picker expansion.

### Completed tests

- `T001`: Registry metadata test verifies new project actions are registered with expected flags/schemas/idempotency metadata.
- `T005`: DB-backed authorization/tenant-scope test verifies project find/search/task search behavior is tenant scoped and authorization aware (with schema-aware branch handling when `users.client_id` is unavailable).
- `T023`: Schema/picker metadata assertions validate project/phase/task/status picker metadata + dependency paths and absence of tag picker metadata.
- `T024`: Workflow designer fixed-picker test validates project-related pickers render and dependency-disabled behavior is shown until upstream fixed values exist.
- `T025`: Compatibility regression test verifies `projects.create_task` remains registered and functional.

### Commands/runbook used

- `cd shared && npx vitest run workflow/runtime/actions/__tests__/registerProjectActionsMetadata.test.ts workflow/runtime/actions/__tests__/businessOperations.projects.db.test.ts`
- `cd ee/server && npx vitest run src/components/workflow-designer/__tests__/InputMappingEditorPickerFields.test.tsx -t "T024"`

### Gotchas discovered

- Project fixed pickers use async option loading in fallback `CustomSelect` mode (non-dedicated picker kinds), so immediate enabled assertions can be flaky; T024 now uses `waitFor` on project picker readiness.
- Authorization fixture assumptions can differ across schema variants (`users.client_id` optional); T005 now guards for column presence to keep assertions meaningful in both variants.