Skip to content

feat(workflows): remove a saved workflow from the library - #19040

Closed
jeeshofone wants to merge 1 commit into
kirodotdev:mainfrom
jeeshofone:feat/18998-workflow-library-remove
Closed

jeeshofone wants to merge 1 commit into
kirodotdev:mainfrom
jeeshofone:feat/18998-workflow-library-remove

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A user can remove a saved workflow from the library in the dashboard, and everything that was adapted from it keeps working.

Once a workflow is saved to the library, nothing in Kiro Crew can remove it. A stale workflow stays in Customize > Workflows, still runs from /workflow <slug>, is offered to agents by workflow_library_list, and seeds authoring. The only way out is moving its JSON file out of the library folder, which breaks the lineage of every draft or run adapted from it.

Why it matters

Stale workflows stay runnable and steer agents; the workaround breaks lineage.

Not a goal

  • Restoring a removed workflow. The tombstone allows it later.
  • Removing a workflow from an agent tool, an MCP tool or the CLI. Removal stays a human action in the dashboard.
  • Removing one revision, or deleting run history of a removed workflow.

What changed (motivation → approach → change)

Removal is a tombstone, not a hard delete:

  • workflows/library.py: removal writes a tombstone (every revision kept) under the library's cross-process lock. A removed definition leaves every list, lookup and run path and the authoring examples. The tombstone adds removed_at (and a v1 record's default format), skips re-gating stored revisions, and replaces every file holding a live copy, so a record saved under older redaction rules or placed by hand is removed too. A revision lands in the file its record came from, never on a same-id tombstone.
  • The id and the slug a workflow holds when it is removed are reserved for good, whether a later ref matches as an id or as a slug; a slug given up by an earlier rename is not covered (Renaming a saved workflow frees its old slash-command name for a different workflow #23680). workflows/library.py keeps one set, the id and slug of every removed record: every read by ref refuses a ref in it (ids match before slugs), and slug allocation never hands out an id or slug on disk. One index per read decides which record each ref reaches, and every list offers a record only under a ref that reaches it: a record's own slug or id that a removed record holds, or that another record answers to first (a hand-placed record whose id is its slug), is listed in shadowed_refs (computed, never stored) and not offered. With neither reaching it, the dashboard shows No slash command with actions off, and /workflow (chat_turn/slash_commands.py) and workflow_library_list (mcp_tools/workflows.py) leave it out; the latter never prints an id that does not reach it. Dashboard requests go to the id, else the slug, whichever reaches the record. An unreadable tombstone releases its refs and is logged as a warning.
  • workflows/service.py: lineage resolution reads tombstoned definitions and checks every copy of the parent's id, so drafts and runs adapted from a removed workflow keep saving; it never goes through the ref refusal. A run of a removed workflow says why it can't be saved.
  • dashboard/handlers/workflows.py, server_runtime/mcp_routes.py: one owner-only DELETE /api/workflows/definitions/{ref} route, behind the same owner guard as the sibling PATCH route, with one audit event per removal. Unknown or already-removed refs answer 404. PATCH and DELETE take an optional expected_id: a ref that now reaches another workflow answers 409, and nothing changes.
  • Website (WorkflowLibraryTab.tsx, api/client/workflows.ts): a Remove action, right-aligned and apart from Save. The confirmation leads with a bold "Kiro Crew can't undo this.", then says, with the real slug, what stops and what keeps working. Above the editor, behind a divider, sits the outcome: a status line naming the removed workflow, or ErrorNotice (cause in a collapsed ErrorDetails) and a "Try removing again" button. The retry is offered, by its current ref, only while the latest read gives the workflow one. Save and Remove send the shown id; a 404 or 409 re-reads the library afresh and drops the row only if the record is gone. Once any removal settles, failed ones included, the tab reads the library again, so no row keeps a ref the removal stopped reaching. The filter matches the shown ref, and a workflow no ref reaches has read-only fields. Strings in every catalog.
  • Docs: workflows spec, feature map and docs/workflows.md (the /workflow user doc).

Why not a hard delete: drafts and runs name it by id. Why not release the slug: a saved /workflow <slug> would run whatever takes it next.

Backwards compatibility

Compatible: nothing changes until a user removes a workflow. The dashboard's Run sends the workflow's id, which the run route has always accepted.

Reader: src/kiro_crew/workflows/library.py:list -- crew page -- removed definitions are excluded by design; test_removed_definition_is_absent_from_every_user_facing_read
Reader: src/kiro_crew/workflows/service.py:save_definition -- chat -- a removed parent still resolves by id; test_a_draft_adapted_from_a_removed_workflow_still_saves, test_a_run_adapted_from_a_removed_workflow_still_promotes
Reader: src/kiro_crew/workflows/library.py:get -- chat -- a ref a removed record holds, as an id or a slug, answers not found on get, the GET, PATCH, DELETE and run routes, /workflow and workflow_run, and a record carrying it still answers by its other ref; test_definition_routes_on_a_claimed_removed_slug, test_a_hand_written_id_equal_to_a_removed_slug_answers_not_found_by_it, test_routes_and_tools_refuse_a_hand_written_id_equal_to_a_removed_slug, test_a_record_whose_id_is_reserved_is_changed_and_removed_by_its_slug
Reader: src/kiro_crew/workflows/library.py:get -- cron -- a saved /workflow <slug> answers not found after a removal and never runs a workflow saved later under that slug or id; test_removed_workflow_no_longer_lists_runs_or_seeds_authoring, test_a_removed_slug_stays_dead_when_a_hand_written_record_claims_it, test_a_new_slug_never_equals_an_id_on_disk, test_a_hand_written_slug_equal_to_a_removed_id_answers_not_found_by_it, test_a_restored_copy_of_a_removed_record_is_reached_by_no_ref

Tests

  • test/test_workflows_library_remove.py: the tombstone is the stored record plus removed_at (and a v1 record's format), field for field (mutations -> red); absent from every user-facing read; the slug stays reserved for create and rename (mutation -> red); a record saved under older redaction rules is removable (mutation -> red); every copy of one id, under any file name, is gone from list/get//workflow/run (mutation -> red); a copy a failed removal leaves live answers only to its own free slug (mutation -> red); a removal waits for an in-flight revision and keeps it (mutation -> red); adapted drafts and runs still save and promote, also from a revision only a later copy of the parent holds (old code -> red); a record carrying a removed record's slug or id answers not found by that ref on every reader and route, and by its other ref everywhere; one holding both is listed but reached by nothing, and the chat and agent lists leave it out; a restored tombstone copy is reached by nothing; a PATCH through a restored copy's free slug leaves the same id's tombstone intact, keeps the retired slug refused and gives a create the next number, and a record under another file name is revised in place (mutation -> red); a DELETE or PATCH by a slug that moved to another workflow answers 409 with the shown expected_id and changes nothing, a malformed one is a 400, and a copy left beside its tombstone is removed in its own file (mutations -> red); the agent list never prints a reserved id; a new slug never equals an id on disk, live or removed, and a hand-written slug equal to a removed id answers not found (old code -> red); a free id beats another record's slug in either folder order, and the other record is listed under its own id in every list and that command runs it (old code and mutation -> red); of two records sharing a slug only the one it reaches is offered it; a revision offers the refs its own write leaves reaching it (mutation -> red); lineage still resolves removed and reserved-id parents; shadowed_refs is never stored and a stored copy is ignored; a run of a removed workflow says why it can't be saved; an unreadable file is warned about once until it changes, and again if it breaks after reading; workflow_library_list never prints /workflow or /workflow None (mutations -> red).
  • test_workflow_definition_handlers.py, test_r7_owner_gate_*: DELETE tombstones, audits, is owner-gated; unknown/removed 404; write failure has a code.
  • test_slash_command_no_channel.py: on KAS the / menu keeps /workflow and leaves harness commands out, and /workflow sent through the KAS gate offers and starts a workflow whose slug a removed one holds by its id, its slug answers not found, the harness never gets the text and no KAS notice is shown (a mutation on either side -> red).
  • website/src/test/WorkflowLibraryTab.test.tsx: the confirmation's slug bullet, real slug, no suffix; the row drops only after the server confirms; after a removal, after a failed one that tombstoned one of two copies, and after a second removal confirmed while the first one's re-read is in flight, the library is read again and a survivor whose id the removed slug now holds runs and saves by its own slug (mutations -> red); a list read in flight when the removal lands cannot bring the row back (old code -> red); switching or starting a new workflow mid-removal keeps edits, leaves the other Remove unbusy (mutation -> red) and still shows a late failure; a 500 renders ErrorNotice, cause behind a collapsed Details, then a retry it describes (mutation -> red) that re-sends with no second dialog; a pending retry shows no failure line (mutation -> red) and keeps focus; focus moves on success; no stale failure; a 404 drops the row only when a fresh read no longer has it, else shows the failure, and a retry goes to the ref that read gives (mutation -> red); Run, Save and Remove go to the id, else the slug when the id does not reach the workflow, and are off when neither works, with No slash command, a note and read-only fields; Save and Remove send the shown id, a Remove 409 re-reads the library and keeps the row, a 404 re-read does not join a list read in flight, the retry is not offered once no ref reaches the workflow, and the filter finds a row by the ref it shows (mutations -> red); a slug that does not reach the workflow, held by a removed one or another workflow's id, shows /workflow <id> in the row, the header and the confirmation, and Run goes to the id (old code -> red).

Run locally on main 278fc2d. Backend: the related pytest set from scripts/run_scoped_tests.py (1871 files) plus every test_*ratchet* and test_ws_event_scoping* file. That covers this PR's tests, the dashboard composition contract (the MCP route table counts main's new route and the DELETE route, 314 rows) and the owner-gate, error-code and event-scoping contracts. Frontend: the related vitest set (2503 files) with I18N_BASE_REF, tsc, eslint, i18n:check and lint:i18n with I18N_BASE_REF, and i18n:pseudo, which leaves en-XA.json unchanged. Gates: all 24 in pre_push_gate.py, among them black, isort, flake8, mypy src/kiro_crew/, docs, feature-map and comment-history. The capture script passes, and its frames each assert their state. Every test that failed in these runs fails the same way on main 278fc2d on this machine, and none is in a file this PR touches.

Manual verification

Every state, light and dark, asserted by the capture script.

Screenshots / video

Remove action, light
Confirmation, light
Removed, light
Last one removed, light
Failure, light
Details open, light
Removing, light
Other workflow mid-removal, light
Retry pending, light
Slug that does not reach it, light
Its confirmation, light
Id and slug both held, light

All variants

Remove action, dark
Confirmation, dark
Removed, dark
Failure, dark
Details open, dark
Removing, dark
Other workflow mid-removal, dark
Retry pending, dark
Slug that does not reach it, dark
Its confirmation, dark
Id and slug both held, dark

Related Issues

Fixes #18998

Checklist

  • One commit, with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@jeeshofone
jeeshofone marked this pull request as ready for review October 11, 2026 05:34
@jeeshofone
jeeshofone requested review from a team and KiroCrewCaptain as code owners October 11, 2026 05:34
@jeeshofone
jeeshofone requested a review from CrysisDeu October 11, 2026 05:34
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 5423c59f1a9b7acd7a51ce0c46d0367a7ca8d832 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

The committed screenshots cover every new control and state, so nothing blocks. No blind first-time reader has seen them, because this is a fork. Pushing the branch to this repository runs that pass.

Notes

  • The no_command_note sentence "A removed workflow holds this workflow's ID and slash-command name…" uses "ID", which users never see anywhere else on this page. Say what the user would notice instead: "This workflow's slash command belongs to a removed workflow…"

[UX-REVIEWED] 5423c59

Description read

[DESCRIPTION-READ] b7449b126957038ea94636ea2a7da2298ddd7837a10db8f6bc6ab3374dfda2ec

That sha256 names everything this verdict read: the PR description, plus the 27 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 5423c59f1a9b7acd7a51ce0c46d0367a7ca8d832 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: a tombstone keeps lineage working and reserves refs so a saved /workflow <slug> can't silently run something else, and every library reader goes through WorkflowService.

Notes

  • "Compatible: nothing changes until a user removes a workflow" isn't quite true. get now matches ids before slugs, and _unique_slug now treats live ids as taken, so resolution and allocation change even when nothing has been removed. Say so in the description; both are reversible.
  • Most of the shadowed_refs and _presented logic covers hand-placed duplicate or colliding records, which is a lot of read-time machinery for an edge case. Refusing such records at load, with a warning, would be smaller.

[DESIGN-REVIEWED] 5423c59

Description read

[DESCRIPTION-READ] 1ad5b20f509bb6e3e03d7f02c304da4854ca18fef5de46d1824cfc3f124eda41

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 5423c59f1a9b7acd7a51ce0c46d0367a7ca8d832 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Removal fills a real gap. The rest is machinery for hand-placed library files, which agents cannot write. It is heavy but reversible, so these are notes.

Notes

  • Item 4 — oversized: it handles hand-placed and copied records ("a hand-placed record whose id is its slug", "every file holding a live copy"), which the Goal never names. Subtraction: reserve only the removed slug, since wfd_… ids are minted, never chosen. Drop shadowed_refs, command_ref and the "No slash command" read-only row.
  • Item 5 — rides along: expected_id on PATCH and DELETE guards a ref that moves, but the description says "Dashboard requests go to the id", and ids never move. Subtraction: delete _expected_id, WorkflowRefMovedError and the PATCH parameter, and always send the id.
  • Item 7 — rides along: the warning for each unreadable file (_warn_unreadable, self._unreadable) exists only because of Item 4. Subtraction: keep the existing logger.debug skip.

What this change ships

Inventory (8 items) — 4 justified

Intent: a dashboard user removes a stale saved workflow while drafts and runs adapted from it keep their lineage. This is an ADDITION.

  1. Remove action, with a confirmation, in Customize > Workflows — justified
  2. Owner-only DELETE /api/workflows/definitions/{ref}, audited — justified
  3. A removed workflow's slug and id are reserved for good — justified
  4. Hand-placed or duplicate records are shown as "No slash command" and left out of /workflow and agent lists — oversized
  5. PATCH and DELETE answer 409 on a moved ref (expected_id) — rides along
  6. Lineage reads tombstones and checks every copy of an id — justified
  7. A warning is logged once for each unreadable library file — rides along
  8. Ids are now matched before slugs when resolving a ref — undeclared in Goal

[FIRST-PRINCIPLES-REVIEWED] 5423c59

Description read

[DESCRIPTION-READ] 604c5f65d9ec27061478c206077294effd7a1a0c64b715faca3205b14f0cc40c

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 5423c59f1a9b7acd7a51ce0c46d0367a7ca8d832 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5423c59

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed ada1251e909572d9713053dd1488d7d4547e0637 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ada1251

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: render mutation failures through ErrorNotice span=32b9fd35f606

The removal failure renders through ErrorNotice (WorkflowLibraryTab.tsx) with report={reportForError(removeDefinition.error)}, so endpoint, status and backend code reach the notice; no role="alert" paragraph is touched by this diff.
Hand-off stays off with a No hand-off comment naming the unsaved workflow editor, as the finding's own Fix asks.
Pin: WorkflowLibraryTab.test.tsx 500 workflow_definition_write_failed case asserts the ErrorNotice banner; mutation to a bare <p role="alert"> turns it red (verified locally). 404 renders no error (UX item).
Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: establish contention before asserting removal is blocked span=7a0116e622b7

The contention test now wraps the remover's _revisions_lock: at the removal's own lock attempt it probes the same lock file non-blocking and records whether it is held, then sets an event. The test waits on that event and asserts the probe found the lock held by the in-flight update.
No timeout expiry is a success condition: every wait is an "it happened" event bounded only as a failure ceiling.
Mutation (removal skips the lock) -> red: "the removal never asked for the library lock" (verified locally). Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: removal failure shown through ErrorNotice, not a hand-written alert span=de139bc24427

Same fix as the GPT lane's finding on this line: ErrorNotice with the structured report from reportForError (endpoint, status, code), plus a No hand-off comment naming the unsaved editor draft it protects.
Vitest pins the 500 workflow_definition_write_failed banner (bare-paragraph mutation -> red) and the 404 no-error path. Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: failure line has no next step and isn't translated span=3ec57d712240

The failure now shows the catalog string pages.overview.workflowLibrary.remove_failed ("Could not remove “{{name}}”. It is still in the library, so you can try again.") in every locale, never the raw server text. See failed-light/dark.png in the body. Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: the 404 path leaves a stale error span=4c437927f88c

A 404 on remove means another tab already removed it: the mutation settles as success, the row drops and no error shows. Vitest "treats a 404 as already removed and shows no error". Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: removed_by has zero consumers span=e400489a5411

Taken as the subtraction: removed_by is gone from WorkflowDefinitionLibrary.remove, WorkflowService.remove_definition, the handler call and the spec. removed_at is the only tombstone field; the actor lives in the route's SEL audit row. Test asserts "removed_by" not in on_disk. Fixed in d809070.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • acknowledged: Design PASS on 6054055

No items raised. This head subtracts removed_by and moves the failure surface onto ErrorNotice; the tombstone design, lock and route shape are unchanged.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Delta 6054055 -> d809070 (one commit, rebased onto main f071625):

  • Removal failure renders through ErrorNotice with the request's structured report and a translated "still in the library, try again" line; hand-off off (unsaved editor). 404 = already removed, no error.
  • Contention test synchronises on the removal's observed lock attempt; no timeout-as-success.
  • removed_by subtracted (FP); actor stays in the SEL audit row.
  • hi.json strings in the तुम register (hiStyle.test.ts green); ApiClient.refactor.surface.test.ts pinned order gains removeWorkflowDefinition in place.
  • E2E fork.spec.ts "passed only on a retry" on 6054055 is outside this diff (no fork code touched): tracked in E2E flake: fork.spec 'creates new tab' asserts the transient "Fork of" birth title #19049.

Local on the pushed head: black/isort/flake8, mypy src 0 errors, scripts/check_* guards, ratchets + facade + error-code contract, 1274 neighbour tests, boot smoke, docs-lint, website tsc/eslint/i18n/ui-index, full vitest (47985 passed, on the pre-rebase base; re-ran tsc + affected suites after the rebase).

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: freeing a removed workflow's slug is oversized span=f23d2191cc87

Taken as the subtraction. _unique_slug reads _load_all() again, so a removed workflow's slug stays reserved for create and rename; a new workflow with that name gets <slug>-2. Create is back to main's shape (no lock change). Spec and body say slugs stay reserved.
Pin: test_a_removed_workflow_keeps_its_slug_reserved; mutation (release via _live()) -> red. Fixed in 0bba3fe.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: removal ends without saying it worked span=e454df98e497

A success now shows a status line above the editor, "Removed “{{name}}” from the library." (role="status", every locale), so the user sees which workflow left before editing the next one. It clears when another workflow is chosen. Vitest "says which workflow left once the removal succeeds"; mutation (no note) -> red. removed-light/dark.png re-captured. Fixed in 0bba3fe.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: show a short note after a successful removal span=af5a5aa85f0a

Shipped as suggested: "Removed “{{name}}” from the library." where the editor sits. Same change as span e454df98e497. Fixed in 0bba3fe.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: remove_confirm_body names the result first span=97aeffee9eb0

English now reads "Removes it from the library and /workflow, and agents stop suggesting it. Past runs and workflows adapted from it keep working." (en-XA regenerated; the other catalogs already open on the action). See confirm-*.png. Fixed in 0bba3fe.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision: no first-time user has read these screens span=9ef2bdb46a46

This lane has no blind read and caps at CONCERNS for that reason; an author cannot supply one. A maintainer cold read of the confirm and failure frames in the body is the only thing that clears it.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 6, tombstoning every live copy of an id

Rebutted, no subtraction. The library loads every *.json in its folder, and a record's file name is not part of its identity, so a copied or restored file is a live, runnable definition on main today. Tombstoning only the file _path_for names would let a removal report success while such a copy stays runnable, which is the false success #18998 is about. test_workflows_library_remove.py pins a record stored as other-name.json gone from list, get, /workflow and run, and writing only to _path_for turns it red. The lineage check covers every copy for the same reason: the library reads copies in no fixed order, and a revision may live in only one of them.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 5, expected_id and its 409 on PATCH and DELETE

Rebutted, no subtraction. expected_id answers an upheld blocking GPT finding on c1f611e: the dashboard sends a record by its slug when its id is reserved, and another tab can rename that workflow and save a new one under the freed slug, so Save or Remove would reach the wrong workflow. The 409 is how the server refuses that. It does fire only on the id-reserved branch, so it goes if item 4 goes, and not on its own.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • acknowledged: a tombstone that does not read releases its id and slug, and only the log says so

Acknowledged, no change. A file that does not parse cannot be read for the refs it held, so nothing can keep them reserved. The rule is scoped to the id and the slug a record holds when it is removed, and a tombstone edited by hand into something unreadable is outside what a removal can protect. _warn_unreadable logs it as a warning once per file and version. A dashboard surface for unreadable library files is a separate feature.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 4, the reserved-ref flags and the No slash command state are oversized

Rebutted, no subtraction. The rule stays: the id and the slug a workflow holds when it is removed are reserved for good. A record that carries a reserved ref does not need hand placement: a copy left live by a failed multi-copy removal has its id reserved by the product's own tombstone write. Without the flags, the listings would offer that copy under a /workflow command that answers not found. With them, command_ref offers its free ref, or none, and the dashboard says why. The read-only editor and the slug hint follow from the same two flags.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed: advertised commands can execute a different workflow (library.py:207) span=da189d42b48e

Fixed in 0444a4d. Advertising now comes from resolution. _ref_index builds, once per read, the map from each ref to the live record it reaches (a reserved ref to none, ids before slugs, then file order), and _resolve looks a ref up in it. Each read checks the record's own slug and id against that index and lists the ones that do not reach it in shadowed_refs, which replaces slug_reserved and id_reserved. command_ref, the dashboard's row and header labels and its request ref, the workflow_library_list id clause and the /workflow start line all read that list, so an offered command runs the record it is listed on.
test_a_listed_command_runs_the_record_it_is_listed_on pins your trigger in both folder orders: B is listed as /workflow wfd_other and A as /workflow alpha in the library list, the HTTP list, /workflow and workflow_library_list, and /workflow wfd_other go starts B. It fails on 630bf0f, and on a mutant that counts any record a ref reaches as reaching this one. The same class covers two hand-placed records sharing one slug: only the record the slug reaches is offered it. A dashboard test pins the labels and that Run goes to wfd_other.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • taken in part: item 6, the handling of hand-placed records that hold a reserved ref

Taken in 0444a4d as far as the upheld GPT block on this head allows. slug_reserved and id_reserved are gone, and with them the hint under the editor's Slash-command name field and the removal confirmation's reserved-slug variant, with their two strings in every catalog. One read-time field replaces the flags: shadowed_refs, the record's own slug or id when the per-read index _resolve uses does not take it to the record. _presented stays, reduced to writing that field, because the dashboard and workflow_library_list read the list over HTTP and cannot ask the resolver themselves. command_ref, the No slash command state and the read-only editor stay: GPT upheld a block because a listed command ran another workflow, so a list must offer only a ref that reaches the record, and none when no ref does.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • rebutted: item 7, expected_id and the 409 on PATCH and DELETE

Kept in 0444a4d. The dashboard still sends a request to the slug when the record's id does not reach it, and that state needs no hand placement: a removal that fails after tombstoning one of several copies reserves the id of the copies it leaves live. Another tab can then rename that workflow and save a new one under the freed slug, and without expected_id a Save or Remove sent to that slug would reach the new workflow. The 409 is the server refusing that, which answers the upheld GPT finding on c1f611e. Dropping it needs every dashboard request to reach its record by id alone, and a reserved id rules that out.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision: the workflow-library RFC leaves deletion out of scope (item 1)

No RFC edit in this PR, as answered on 22b0a05. The amendment is its own docs PR, #23393, which amends §4 and §13 question 3 of rfc-global-workflow-library.md for the shape this PR ships: a tombstone that keeps every revision and the lineage, an id and slug that are never released, and no restore.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed by removal: slug_reserved_hint does not name the numbered slug

The hint is gone in 0444a4d, with slug_reserved itself, as part of the First Principles item 6 subtraction on this head. The editor header and the row show the command that reaches the workflow, /workflow <id>, and reserved-light.png and reserved-dark.png are re-shot without the hint.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • declined: no_command_note does not say where the workflow library folder is

Declined, as on 9a9ba32. The library folder sits under the data home, which an install can move with KIROCREW_HOME, so a path written into the catalogs would be wrong on that install, and showing the real one would send an absolute host path to the browser. The note names both ways out: give the file a new id and name, or delete it.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • acknowledged: a restore would have to release the reservation

Acknowledged, no change. Restore is a non-goal here, and #23393 records that a removal has no restore. The reserved set is read from tombstones on every read and never stored, so a restore that clears removed_at on a record's tombstones releases its id and slug with them, with nothing else to undo.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • acknowledged: an unreadable tombstone frees its refs, and only the log says so

Acknowledged, no change, as on 9a9ba32. A file that does not parse cannot be read for the refs it held, so nothing can keep them reserved, and a tombstone edited by hand into something unreadable is outside what a removal can protect. _warn_unreadable logs it once per file and version. A dashboard surface for unreadable library files is a separate feature.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • taken in part: the hand-placed and duplicate-record handling is the costliest part to maintain

Reduced in 0444a4d. The two reason flags became one read-time list, shadowed_refs, written from the same per-read index _resolve looks refs up in, so what a list offers and what a ref runs cannot drift apart. The editor hint and the reserved-slug confirmation variant are gone. Tombstoning every copy and writing to the record's own file stay: the library loads every *.json in its folder, so without them a removal could report success while a copy stays runnable.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 0444a4d.

The upheld GPT finding on 630bf0f is answered: advertised commands now come from the same per-read ref index that resolution uses. The other current-head lane notes have replies, all five AI lanes pass on this head, and every check is green.

What still blocks, and what clears each:

  1. Conflict. The branch conflicts with main again in test/test_dashboard_server_composition_contract_reach.py. A rebase clears it.
  2. Sensitive. It adds an owner-gated DELETE /api/workflows/definitions/{workflow_ref} route that tombstones stored definitions and reserves their id and slug for good (handler). A human reviewer must sign off on it, together with the RFC amendment in docs(rfc): record removing a saved workflow from the library as a tombstone #23393.
  3. One UX note has no reply. In the No slash command state, the read-only fields look editable. Give them the muted or disabled field style, or reply in a target=ux disposition.

Our earlier change request at f66ca8b is superseded by this hold.

— crew-pr-reviewer (r131)

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Head ae6c24d247: one commit, rebased onto main 278fc2d253 (the PR conflicted). Beyond the rebase it adds one test.

Rebase. The only textual conflict was the MCP route-table pin in test/test_dashboard_server_composition_contract_reach.py. Main's #24692 adds POST /api/agent-panel/dashboard/record and this PR adds DELETE /api/workflows/definitions/{workflow_ref}. Both sides moved the row count from 312 to 313, so git merged the count without a conflict, but the table now has 314 rows. The pin is 314 with the digest the test computes. Leaving out this PR's row gives main's pin exactly, and leaving out main's row gives this PR's previous pin. slash_commands.py, mcp_routes.py, the feature map and the 12 catalogs merged without conflict and keep both sides: each catalog has main's 4 new keys and this PR's 12, and npm run i18n:pseudo regenerates en-XA.json with no change.

/workflow on KAS. Main's #25098 leaves KAS-unsupported commands out of the / menu and keeps /workflow, which the slash gate answers before any KAS notice. test_the_workflow_command_the_kas_menu_offers_runs_only_what_resolves in test/test_slash_command_no_channel.py sends /workflow through the KAS gate. The menu keeps /workflow and leaves out /tools. The list offers a workflow whose slug a removed one holds by its id, the slug answers not found, the id starts it, and the harness never gets the text. The test turns red if the list names the slug again, or if the KAS menu stops leaving harness commands out.

Evidence. The capture script passes at this head, and every frame asserts its state. The frames match the committed ones apart from editor load timing, with one exception: on the new base the disabled Remove in the two reserved-both frames draws a fainter border. That styling comes from main, not this diff, so the committed frames stand.

Gates on this head. Backend: the related pytest set (1871 files) plus every test_*ratchet* and test_ws_event_scoping* file, 89963 passed. Frontend: the related vitest set with I18N_BASE_REF, 2482 of 2503 files passed, among them WorkflowLibraryTab, destructiveConfirm, the client surface and every src/i18n/ test. tsc, eslint, i18n:check and lint:i18n with I18N_BASE_REF, and all 24 gates in pre_push_gate.py, mypy src/kiro_crew/ among them: clean. The tests that failed here fail the same way on main 278fc2d253 on this machine, none is in a file this PR touches, and CI runs both suites on the merge ref. Main has moved to cc69e06a1f since, and this head merges with it cleanly.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • deferred: in the No slash command state the read-only fields look editable

Deferred to #25194, so this head stays as reviewed while it waits for sign-off. When no ref reaches the workflow, WorkflowEditor already sets readOnly on the Name, Slash-command name and Description fields and drops the source editor's change handler, so nothing typed there is saved. What is missing is the look. #25194 gives those fields the read-only style InstanceFormFields.tsx already uses (opacity-60 cursor-not-allowed, with aria-readonly).

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • deferred: no_command_note says ID, but the editor shows no ID field

Deferred to #25194. The note sends the user to the workflow's file, and the file names the two fields id and slug. #25194 names them that way in the note, in every catalog.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • deferred: the run input stays editable when no slash command reaches the workflow

Deferred to #25194. Run workflow is off in that state, so nothing typed in the input is used. #25194 makes the input read-only, in the same read-only style as the editor fields above it.

@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • acknowledged: item 5, the Backwards compatibility line "nothing changes until a user removes a workflow"

Acknowledged, no change. The line holds for every record the product writes. A generated id is wfd_ plus 16 hex characters, and every slug the library writes goes through _slugify, which keeps only [a-z0-9] words joined by hyphens, so no written slug can equal a written id. Matching ids before slugs, and keeping live ids out of slug allocation, change an answer only when a file placed by hand carries an id that could be a slug, such as debug-project. The Reader: lines in that section name those cases and the tests that pin them.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at ae6c24d for human review.

The r131 points are answered. The rebase onto main clears the conflict in test_dashboard_server_composition_contract_reach.py, and the branch merges cleanly with current main. The UX note about read-only fields that look editable now has a disposition deferring it to #25194, which names the fix. Every other current-head lane note has a reply, all five AI lanes pass, and every check is green.

What still holds it: the PR adds an owner-gated DELETE /api/workflows/definitions/{workflow_ref} route that tombstones stored definitions and reserves their id and slug for good (handler). A human reviewer must sign off on it, together with the RFC amendment in #23393, which is still open.

— crew-pr-reviewer (r133)

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Head ada1251e90: one commit, rebased onto main d9a20ee8a7 (the PR conflicted). Conflict resolutions only: the library keeps both error classes (WorkflowSlugTakenError from main, WorkflowRefMovedError from this PR); _revisions_lock opens the lock with main's open_create_or_existing; the spec paragraph names creates, updates and removals under the one lock, with main's exact_slug sentence; the feature-map row is main's with the Remove sentence and DELETE route added; the composition counts move by one on main's values (117 lazy imports, 337 MCP rows, new digest). One test change: the KAS menu now lists /tools on main, so the PR's /workflow KAS test drops its /tools absence clause and keeps its /workflow checks. Locally: 2028 Python tests on the changed and workflow test files pass, 3 vitest files pass, tsc -b, black, isort, flake8, mypy and the comment-history gate are clean, and Semgrep reports nothing on the changed lines.

A saved workflow could only be removed by moving its JSON file out of the
library folder from a terminal, which also broke every draft and run
adapted from it ("workflow lineage does not resolve to a saved revision").

Removal is now a tombstone written under the library's cross-process lock,
onto every file that holds a live copy of the record, without re-running
the save-time source gate. A removed definition leaves list, search, slug
and id lookup, /workflow, workflow_library_list, saved runs and the
authoring examples, and still resolves by id for lineage, so adapted
drafts and runs keep saving. A revision is written to the file its
record was read from, so a save never replaces a tombstone of the same
id.

The id and the slug a record holds when it is removed are reserved for
good, whether a later ref matches as an id or as a slug; a slug given up
by an earlier rename is not covered (kirodotdev#23680). Every read by ref refuses
the id and the slug of a removed record before matching, and slug
allocation never hands out an id or slug on disk. One index per library
read decides which record each ref reaches, and every list offers a
record only under a ref that reaches it: a slug or id that a removed
record holds, or that another record answers to first, is not offered.
With neither reaching it, the library lists it as having no slash
command and every other list leaves it out.

One owner-only DELETE /api/workflows/definitions/{ref} route backs a
Remove action with a confirmation in Customize > Workflows. No agent, MCP
or CLI path can remove a saved workflow. Save and Remove send the id the
editor shows as expected_id; a ref that now resolves to a different
workflow answers 409, and nothing is written or removed.

Fixes kirodotdev#18998
@jeeshofone

Copy link
Copy Markdown
Contributor Author
  • fixed in 5423c59f1a: a workflow.save card offered a removed workflow's slug as free. The card's "is it taken" read used get, which reaches nothing for a reserved ref, while the exact_slug create allocates against _taken_refs. The library now has slug_taken(slug), which reads _taken_refs the same way the allocator does, and the service exposes it under its definition lock. _workflow_state uses it for the save card. A new test removes a workflow and checks that a card asking for its slug is refused slug_taken at proposal time, while get still returns nothing for it. The test fake also takes expected_id the way the service does, which the update test needed after the rebase.

Integration (in-process gateway) on ada1251e90 failed in test_boot_smoke.py::test_a_second_boot_touches_only_known_module_globals on kiro_crew.recall_pool._settings_cache. This diff does not touch that module, and main's push CI passed the same job at 9158a9a1ad, which already includes the recall pool. The new head re-runs it.

First-pass check: R1-R8 OK.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Moved to #27528: same commits, now on a branch of this repo so CI uses the CodeBuild fleet. Review history stays here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Workflow library has no way to remove a saved workflow

2 participants