docs(rfc): session tag-change event surface (#7663)

[bolichen97]

Summary

Adds an RFC for the session tag-change event surface requested in #7663: a fire-and-forget server-side event fired when a session's status tags change, so an automation can react to a lane transition (motivating case: a close-out prompt when a session enters Done).

Per GOVERNANCE.md, a new public event interface that other automations subscribe to and that is "expensive to reverse once anything subscribes" must be written up as an RFC before code. This PR is the design of record only. No implementation code is landed (SessionTagsChanged has zero hits in src/; HOOK_EVENTS and ALLOWED_HOOK_EVENTS still carry exactly the five turn-lifecycle events).

What is in this PR

• New: docs/request-for-change/rfc-session-tag-change-event.md (following the repo RFC schema and aligned with the neighboring rfc-mcp-lifecycle-event-log.md)
• Edited: docs/request-for-change/README.md (one draft index row + a matching audit-preamble note)

Positions taken on the four design questions + placement

1. Payload carries the delta (added / removed) plus the resulting status_tags list plus session_key, so consumers need no prior-state file.
2. Scope is status tags only (status: true); routine non-status auto-tags do not fire.
3. Failure semantics are fail-open / informational, never vetoing (aligned with the mcp-lifecycle RFC's "observability, not audit" posture and PreToolUse script hooks fail open: a deny hook that times out, crashes, or is missing is silently approved #7339); a broken hook cannot brick the board.
4. Re-entrancy uses advisory provenance (origin, hook_reentry_depth), settled now per the Stop precedent (hooks.py:4213-4221) rather than an enforced cap.
5. Placement is a sixth HOOK_EVENTS entry (run-now automation is the script-hook engine's job), over an events/ session kind, justified against GOVERNANCE.md and the PR feat(hooks): Add regex/contains matcher modes and declarative skills injection #3952 precedent.

Scope correction over the issue

The issue names two tag writers; the RFC enumerates the full status-tag write surface as a table, including the folder-inheritance path via validate_folder_tag_ids (which screens shape/vocabulary but not status:true, so an inherited folder status tag can move a session into a lane without either named handler running) and the channel-filing appends. Load-time reconstruction sites stay silent; fork emission is left as an explicit open question. It recommends a single choke-point emitter so no write site can silently skip the event.

Testing

Docs-only change; no build/test/docker applies. Every file:line citation in the RFC was verified against the current tree HEAD 6581a04ee (the issue's 2ba6fb53e numbers had drifted and were not copied). A semantic review of the RFC returned APPROVED with no blocking issues.

Notes for reviewers

• Front-matter author is a placeholder (issue #7663 author) and doc-pr: null should be set to this PR number once it lands.
• Open questions (payload key names, coalescing, fork emission, events/-package alignment) are called out in the RFC and are the reversible-once-subscribed decisions to settle before any implementation PR.

Closes #7663 is intentionally NOT set: this RFC does not implement the event; implementation PRs will reference it by number per GOVERNANCE.md.

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a75d4af

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable a75d4afb84df6d56143cc5a679d0f0a86a54bca6: <one-sentence reason>

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of a75d4afb84df6d56143cc5a679d0f0a86a54bca6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Citations verified. The RFC's structure is sound; the one weak leg is the re-entrancy design it claims to settle.

Design-Verdict: CONCERNS

The re-entrancy question the RFC claims "settled now" isn't settleable as written: hook-write attribution has no mechanism, and advisory-only leaves loops unbounded.

Watch

• The origin=hook / hook_reentry_depth design assumes the server can attribute a tag write to a running hook, but hooks are external fire-and-forget scripts reacting via the same public tags API a user calls — the RFC specifies no correlation mechanism (token, header, loop-local context). Without one, every hook-driven write stamps origin=user, depth stays 0, and Phase 2's exit criteria are unmeetable. Specify the mechanism before declaring Question 4 settled.
• The rejection of an enforced cap ("would swallow a legitimate Done → In Review → Done") conflates cases: user-driven rapid transitions carry depth 0 and a cap on hook-originated depth never touches them. The Stop precedent is bounded by the turn ending; two tag hooks ping-ponging a status tag have no natural bound, and fail-open means nothing else stops them — advisory-only relies on the buggy hook self-limiting, the one thing it won't do.

Suggestions

• Keep advisory provenance, but add a generous enforced ceiling on hook_reentry_depth only (e.g. stop dispatching past depth N); it costs nothing for human workflows and closes the loop case.

[DESIGN-REVIEWED] a75d4af

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of a75d4afb84df6d56143cc5a679d0f0a86a54bca6 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- docs/request-for-change/rfc-session-tag-change-event.md:323 -- "two chat_tags.py handlers" omits api_chat_tag_delete, which strips status tags from every affected slot without emitting removed -> Fix: include tag deletion in the write-surface table, Phase 1 wiring, and exit criteria. (origin: validation)
[GPT-REVIEWED] a75d4af

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a75d4afb84df6d56143cc5a679d0f0a86a54bca6: <one-sentence reason>

[buluoray]

Reviewed at head a75d4afb84df6d56143cc5a679d0f0a86a54bca6. Docs-only RFC (2 files: the new rfc-session-tag-change-event.md and its README index row). Verdict: approve.

Blocking: 0.

I spot-checked the load-bearing claims about existing code against source at the audited commit 6581a04ee, and they hold:

• HOOK_EVENTS carries exactly the five turn-lifecycle events (hooks.py:93-99, constants above), matched by ALLOWED_HOOK_EVENTS (validation.py:92-94); SessionTagsChanged has zero hits tree-wide.
• The two named write sites and their push_slots_update() tails are accurate: api_chat_slot_tags writes slot.tags (chat_tags.py:562) and api_chat_slot_drop writes written_tags after the status-filtered kept split (chat_tags.py:980-983); nothing server-side consumes the transition.
• The chat_auto_tag never-status guard is where claimed (chat_auto_tag.py:102-108), and the events/ package exists (base.py, kinds.py, backfill.py) with the session/message kind (events/kinds.py:40).
• The Stop advisory-provenance precedent is quoted verbatim and correctly located (hooks.py:4213-4221).

Filing is correct per the Specification-management rules: the README index row is added with a verified against 6581a04ee note, so docs-lint.sh is satisfied. It contradicts no shipped spec under docs/system-specs/modules/ — it is additive design-of-record and states plainly that nothing is on main.

Non-blocking (1): Question 4 ("Re-entrancy settled now") asserts an origin=hook / hook_reentry_depth design but specifies no mechanism by which the server attributes a slot.tags write to a running hook — hooks are external fire-and-forget scripts that react through the same public tags API a user calls, so without a correlation signal (token/header/loop-local context) every hook-driven write would stamp origin=user at depth 0, making Phase 2's exit criteria unmeetable. This is a design-completeness gap in the proposal, not an inaccuracy about current code; naming the correlation mechanism (or moving it to Open questions) would make Question 4 genuinely "settled." The advisory Design Review lane raises the same point independently.

Could not verify with certainty: whether the events/ package has zero live emitters (I confirmed the package and its kinds exist and that SessionTagsChanged is absent, but did not exhaustively trace every from kiro_crew.events edge to prove none emits — the RFC only leans on this for its Option B alternative, not its recommendation).

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• PR #7669 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #7669: KEEP. The merged PR is a design document, not an implementation, so it supersedes nothing. Worth adding to this PR: update the RFC's implementation-prs / status and the index row's on-main column, and state the SessionLaneChanged-vs-SessionTagsChanged rename where the RFC's readers will see it. Files: docs/request-for-change/rfc-session-tag-change-event.md.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.