Skip to content

docs(rfc): keep a slash-command name a rename gave up bound to its workflow - #28632

Open
jeeshofone wants to merge 1 commit into
mainfrom
docs/rfc-workflow-rename-reservation
Open

jeeshofone wants to merge 1 commit into
mainfrom
docs/rfc-workflow-rename-reservation

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Part of #23680

Problem / Motivation

Goal: Main records a design for keeping a slash-command name that a saved workflow gave up by renaming bound to that workflow, before any code for it is written.

Renaming a saved workflow frees its old slash-command name at once, so a later workflow can take it and a written-down /workflow <old name> silently runs the later one. The removal reservation in #27528 covers only the names a workflow holds when it is removed. The maintainers parked #23680 and asked for a design through docs/request-for-change.

Why it matters

A scheduled message or prompt that names a workflow by its command can start a different workflow after a rename, with nothing to say it changed.

Not a goal

  • Any code change. The implementation follows in its own PR once this design is accepted.
  • Releasing a former name, or back-filling names given up before the change lands.

What changed (motivation → approach → change)

Adds docs/request-for-change/rfc-workflow-rename-reservation.md (status draft) and its row in the index in docs/request-for-change/README.md. The document covers the problem, alternatives including doing nothing, the recommended design (a former_slugs list on each record, counted as taken by slug allocation and reserved on removal through #27528's _refs), how it builds on #27528, a migration plan and a test plan.

Backwards compatibility

Compatible: documentation only.

Tests

N/A: documentation only. scripts/docs_lint.py runs in Source Gates.

Manual verification

N/A: documentation only.

Screenshots / video

N/A: no UI change.

@jeeshofone
jeeshofone requested review from a team and KiroCrewCaptain as code owners November 2, 2026 22:25
@jeeshofone
jeeshofone requested a review from CrysisDeu November 2, 2026 22:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 2, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from 6b9a5f9 to 5720ea9 Compare November 2, 2026 23:07
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 8f98010b7fd84005c6ca09a7e59d3e458c20f99d ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 8f98010b7fd84005c6ca09a7e59d3e458c20f99d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 8f98010b7fd84005c6ca09a7e59d3e458c20f99d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

This PR only adds a draft RFC. The design reuses #27528's _refs path, and rolling back means editing a document.

Notes

[DESIGN-REVIEWED] 8f98010

Description read

[DESCRIPTION-READ] 7945e6dda893137238d0f5a7cecd792881571a72ea5ba19562fa13d82c370297

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 Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 8f98010b7fd84005c6ca09a7e59d3e458c20f99d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8f98010

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8f98010b7fd84005c6ca09a7e59d3e458c20f99d false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 8f98010b7fd84005c6ca09a7e59d3e458c20f99d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 8f98010

Verdict parsed from the review's SHA-scoped output markers for commit 8f98010b7fd84005c6ca09a7e59d3e458c20f99d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8f98010b7fd84005c6ca09a7e59d3e458c20f99d false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Hold: merge conflict, plus one design point to settle. Reviewed at 5720ea9.

GitHub reports this PR as conflicting with main, in docs/request-for-change/README.md where newer RFC rows landed next to this one. Rebase onto main and keep both rows; the new head will need another review.

Before the next round, please answer the Design Review note on destructive routes. §1.3 lets DELETE resolve through a former slug, so a stale DELETE deploy would remove the workflow that was renamed away from deploy. The security section covers only who can reach the record. Either limit PATCH/DELETE to id or current slug, or list it as an open question. The other note (no way to release a former slug) is a stated non-goal; naming the refusal in the allocation response would help. Checks are green.

— crew-pr-reviewer (r143)

@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from 5720ea9 to 706df70 Compare November 3, 2026 10:02
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto main (706df70), both index rows kept. §1.3 now limits PATCH and DELETE to id or current slug, so a stale DELETE deploy answers not found; §7 says so. The allocation response names the former-slug refusal; release stays a non-goal.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 3, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from 706df70 to 2165b45 Compare November 3, 2026 20:32
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 3, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design brief for rfc-workflow-rename-reservation (read in full at 8f2fa40).

What it does. When a rename changes a saved workflow's slug, the record keeps the old slug in a new former_slugs list. _refs then counts former slugs, so slug allocation never hands one to another workflow, and removal reserves them with the id and slug. A /workflow <former slug> run reaches the renamed workflow through a separate resolve_for_run lookup and says which command it now runs as. Plain get, PATCH and DELETE still match only an id or a current slug.

Pros.

  • It fixes the silent rebinding in #23680: a written-down /workflow deploy can no longer start a different workflow.
  • Rename becomes as safe as removal, closing the gap the removal RFC's section 4 records.
  • The redirect keeps scheduled messages working and tells the person to update them.
  • Destructive calls cannot reach a record through a former slug.
  • The field is optional on read, so no migration is needed.

Cons.

  • A name given up by a rename is never released, so a new workflow asking for it gets a numbered slug such as deploy-2, or an exact_slug refusal. That is a small visible change, and releasing a name is left as a non-goal.
  • It is blocked on #27528 (or needs the fallback in section 3).
  • Renames made before it lands are not back-filled.

Tech debt. No. It adds one optional list on the record and one lookup step on the run path.

Maintainer signs the direction. This is a comment, not an approval.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from 8f2fa40 to a987769 Compare November 5, 2026 12:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 5, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (conflict) at a987769.

The branch conflicts with main again in docs/request-for-change/README.md. Please rebase and keep both rows. A new head needs a fresh review.

The RFC itself needs nothing more from me. Our r143 point is answered: PATCH and DELETE match only an id or current slug (§1.3). The Design note asking whether an older build drops former_slugs on rename does not block. Main's rename keeps every existing field through **current (library.py#L314), so the list survives. An older build only stops adding to it, which §6 already describes. Optionally say so in §6. Checks are green.

— crew-pr-reviewer (r146)

@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from a987769 to 15ba375 Compare November 6, 2026 07:15
@jeeshofone

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for the r146 HOLD. Rebased onto main as 15ba375, still one commit. docs/request-for-change/README.md keeps both main's rows and this PR's row. No other change. Docs checks pass locally.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 6, 2026
iamwhatever
iamwhatever previously approved these changes Nov 6, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve at 15ba3759ea3537787725debfe2877ba345166fe1.

This is a docs-only draft RFC. Our r146 hold was only for the README conflict, and that conflict is gone; the index keeps main's rows. PATCH and DELETE still match only an id or a current slug (rfc#L66). All checks are green, and @bolichen97 signed the direction.

AI findings judged non-blocking

  • Design: §6 does not say whether an older build that rewrites a record drops former_slugs. Does not block: main's rename builds the record from **current, so the field survives (library.py#L314). A sentence in §6 saying so is optional.

Note: #28664 and #28633 edit the same README sentence, so the PRs that merge after this one will need another rebase.

— crew-pr-reviewer (r148)

@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 18:35
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 6, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-workflow-rename-reservation branch from 15ba375 to 9576075 Compare November 7, 2026 10:01
iamwhatever
iamwhatever previously approved these changes Nov 7, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE at 7920fb2.

This is a docs-only draft RFC plus its index row. The RFC text is identical to 15ba375, which I approved in r148; this head is a rebase, and the README change is the one new row and audit sentence with no conflict. PATCH and DELETE still match only an id or a current slug, and former-slug resolution stays on the run paths (rfc#L66). All checks are green, and @bolichen97 signed the direction.

AI findings judged non-blocking:

  • Design (note): §6 does not say whether an older build that rewrites a record drops former_slugs. Main's rename builds the record from **current, so the field survives (library.py#L314). A sentence in §6 saying so is optional.

— crew-pr-reviewer (r149)

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

A maintainer has already signed off the design direction on this PR. It now waits for a maintainer approval on this head, because the earlier approvals were dismissed by the rebases.

Review result on bff19ca: no blocking findings. This is a docs-only draft RFC plus one index row and one audit sentence in the RFC README. The review checked the main-side claims against workflows/library.py. _update_unlocked overwrites the slug and keeps no former value. _unique_slug counts only current slugs. The exact_slug path raises WorkflowSlugTakenError. The audit commit is on main. The claims about #27528 (_refs, _reserved_refs, _taken_refs) also hold at that PR's current head. The design keeps PATCH and DELETE on an id or the current slug, so a stale DELETE deploy cannot remove the renamed workflow. That is a good call.

Optional:

  • §1.2 says a former-slug refusal gets its own message and that "the allocation response names the refusal". Both user-facing paths replace the exception text with a fixed string: the dashboard 409 in dashboard/handlers/workflows.py and the change-card plan in change_card_catalog_plans.py. Either drop those sentences, since a -2 suffix or a plain 409 already keeps the name bound, or name both writers and the response field in §4 and §5.
  • §1.2 and §1.3 change the removal RFC's WFL16 and its lookup order, but the RFC never says it amends them. One sentence, plus the usual "amends ... in its own document" clause in the README row, would keep the two drafts consistent.
  • §1.3's third lookup step has no tie-break for a former slug that two live records both list. That can happen after a downgrade and a later rename. A fixed rule would help the implementation PR, for example "reach neither" or "reach the record that gave it up most recently".

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (conflict) at bff19ca.

docs/request-for-change/README.md conflicts with current main again (checked with git merge-tree against 4a0cb55). Please rebase and keep both main's rows and this PR's row.

The RFC itself is unchanged since 7920fb2, which we approved in r149, and PATCH and DELETE still match only an id or a current slug (§1.3). All checks are green. The Captain's three optional notes do not block a draft RFC; a sentence for the §1.3 tie-break would help the implementation PR.

A new head needs a fresh review.

— crew-pr-reviewer (r150)

@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 6% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

This PR only changes docs. It adds a draft RFC and one index row in the README, and it changes no code, so no test is needed. I checked the RFC's claims about main against src/⁠kiro_crew/workflows/library.py, and they hold:

  • _update_unlocked (line 581) overwrites slug and keeps no former value.
  • _refs returns only the id and slug.
  • _reserved_refs and _taken_refs are built on _refs, and the _reserved_refs docstring says outright that a slug given up by a rename is not reserved.
  • _ref_index matches ids first, then current slugs, and does not use _refs.
  • remove and update resolve the target through plain _resolve/get.
  • The removal RFC's §4 (lines 136–138) says a rename's former slug is not reserved and points to Renaming a saved workflow frees its old slash-command name for a different workflow #23680.

The design hangs together:

  • Adding former_slugs to _refs makes slug allocation treat them as taken and makes removal reserve them, with no other change needed.
  • Because _ref_index keeps matching only id and slug, plain get stays strict. Only a separate resolve_for_run follows former slugs.
  • So a stale PATCH or DELETE sent to a former slug answers not found and cannot change or remove the renamed workflow.
  • The securit

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 6f7e4bcf41 · 108 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto current main, past the #39262 guard fix that was failing Backend Tests shard 8. The RFC text is unchanged.

This branch has not been deployed

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

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants