Skip to content

RFC: renumber Approval Prompt Markdown to 0002, resolve questions, align frontmatter#13

Merged
omarshahine merged 3 commits into
mainfrom
rfc-0002-approval-prompt-renumber
Jun 21, 2026
Merged

RFC: renumber Approval Prompt Markdown to 0002, resolve questions, align frontmatter#13
omarshahine merged 3 commits into
mainfrom
rfc-0002-approval-prompt-renumber

Conversation

@omarshahine

@omarshahine omarshahine commented Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Per @kevinlin's request in maintainer-discussion, this renumbers the Approval Prompt Markdown Contract RFC from 0005 to 0002, resolves its open questions, and cleans up frontmatter left inconsistent after the needs_refactoring reorg.

Renumber + resolved questions (0002-approval-prompt-markdown.md)

  • 0005-approval-prompt-markdown.md → 0002-approval-prompt-markdown.md. No other files referenced the old name.
  • The three previously Unresolved questions are now decisions, reflected in the Proposal:
    1. Underline — excluded from the canonical subset; core stays at the strict cross-channel intersection and never emits underline (iMessage may map a channel-local marker out of band).
    2. Capability shape — a field, approvalText, on the existing channel approval capability object, declared via the public plugin SDK, defaulting to "plaintext". No standalone capability or parallel registration path.
    3. Exec fence language hints — a small fixed advisory set (sh / none-or-txt); channels may honor a hint or drop an unsupported one safely without altering the fenced content.

Parked-folder cleanup (needs_refactoring/)

After the June 5 reorg, the parked RFCs still held canonical numbers. Vacated them so the folder is uniformly number-free (they'll get fresh numbers when re-proposed):

  • 0002-doctor-health-upgrades.md → doctor-health-upgrades.md
  • 0003-policy-conformance.md → policy-conformance.md
  • 0004-imessage-channel-configuration-cleanup.md → imessage-channel-configuration-cleanup.md

Frontmatter alignment to the new lifecycle

Added the status / issue keys (modeled on 0007) to every RFC missing them: the three parked RFCs, plus 0001-lts-release-policy and 0006-feeds. All set status: accepted (they're merged/on main) with issue: blank. Left existing rfc_pr values untouched (including the TBD on 0001/0006).

Note: the approval RFC originally merged via #4 as 0005; this PR amends it in place. rfc_pr is left pointing at the original #4.

🤖 Generated with Claude Code

@clawsweeper

clawsweeper Bot commented Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown

Codex review: needs real behavior proof before merge. Reviewed June 21, 2026, 4:51 PM ET / 20:51 UTC.

Summary
The PR renames the approval prompt markdown RFC from 0005 to 0002, resolves its open design questions, and renames three parked RFC files while adding accepted/issue frontmatter.

Reproducibility: yes. Inspecting the virtual merge commit shows accepted-with-blank-issue frontmatter, while current README/template text requires implementation issue URLs for accepted RFCs.

Review metrics: 3 noteworthy metrics.

  • RFC files affected: 4 changed. The diff combines one substantive RFC amendment with three parked-file renames and metadata changes.
  • Accepted metadata added: 4 accepted statuses, 0 issue URLs. Every newly accepted document in the merge result lacks the implementation issue URL required by the current lifecycle docs.
  • Parked RFCs changed: 3 renamed and marked accepted. The needs_refactoring files are described as awaiting re-proposal, so their lifecycle metadata needs maintainer attention before merge.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Populate implementation issue URLs for RFCs that remain accepted, or use accurate non-accepted statuses.
  • Clarify the intended lifecycle state for the needs_refactoring documents before merging their metadata changes.

Risk before merge

  • [P1] Merging would record accepted RFC metadata with blank issue fields even though the current README and template require implementation issue URLs before accepted RFCs merge.
  • [P1] Merging would mark three needs_refactoring documents accepted while the PR body describes those files as parked until they are re-proposed with fresh numbers.

Maintainer options:

  1. Correct lifecycle metadata (recommended)
    Populate implementation issue URLs for documents that are truly accepted and avoid accepted status for parked RFCs before merge.
  2. Codify a lifecycle exception
    If legacy accepted RFCs may intentionally keep blank issue fields, update the README/template policy and state how parked RFCs should be represented.
  3. Split the cleanup
    Land the approval-RFC renumbering and resolved decision text separately while the parked-document lifecycle state is decided.

Next step before merge

  • [P1] A maintainer or contributor needs to supply implementation issue URLs or decide the lifecycle state for parked RFCs; automation should not invent those policy choices.

Security
Cleared: The diff changes only Markdown RFC files and introduces no executable, dependency, workflow, secret, or supply-chain surface.

Review findings

  • [P2] Link accepted RFCs to implementation issues — rfcs/0002-approval-prompt-markdown.md:7-8
  • [P2] Do not mark parked RFCs accepted — rfcs/needs_refactoring/doctor-health-upgrades.md:7-8
Review details

Best possible solution:

Keep the renumbering and resolved approval-RFC decisions, but make lifecycle metadata policy-consistent by linking implementation issues for accepted RFCs and using an accurate parked/deferred state for needs_refactoring documents.

Do we have a high-confidence way to reproduce the issue?

Yes. Inspecting the virtual merge commit shows accepted-with-blank-issue frontmatter, while current README/template text requires implementation issue URLs for accepted RFCs.

Is this the best way to solve the issue?

No. The renumbering and resolved approval-RFC text are reasonable, but the metadata changes need correction or an explicit lifecycle exception before this is the narrowest maintainable solution.

Full review comments:

  • [P2] Link accepted RFCs to implementation issues — rfcs/0002-approval-prompt-markdown.md:7-8
    The lifecycle docs say an accepted RFC should fill issue with the implementation GitHub issue before merge. This adds status: accepted with a blank issue, so the accepted metadata would conflict with the repository contract.
    Confidence: 0.98
  • [P2] Do not mark parked RFCs accepted — rfcs/needs_refactoring/doctor-health-upgrades.md:7-8
    These documents live under needs_refactoring, and the PR body says they will get fresh numbers when re-proposed. Marking them accepted records the opposite lifecycle state, so use a supported parked/deferred state or leave the status change out until maintainers decide it.
    Confidence: 0.96

Overall correctness: patch is incorrect
Overall confidence: 0.96

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 0e353436f90b.

Label changes

Label justifications:

  • P3: This is RFC documentation and metadata cleanup with no urgent runtime or user-facing regression.
  • merge-risk: 🚨 compatibility: The PR changes machine-readable RFC lifecycle metadata in a way that conflicts with the documented accepted-RFC process and parked-document state.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This is an RFC-only Markdown change, so runtime after-fix behavior proof is not applicable.
Evidence reviewed

What I checked:

  • Target AGENTS.md check: No AGENTS.md or .agents/maintainer-notes path is tracked or present in the target repository checkout, so no target-specific policy file applied. (0e353436f90b)
  • Current lifecycle requirement: Current main says accepted RFCs should create an implementation issue, set status to accepted, fill issue with that GitHub issue URL, and then merge. (README.md:91, 0e353436f90b)
  • Template repeats issue requirement: The RFC template says issue stays blank only until acceptance; once accepted, the issue field should be filled with the implementation issue URL. (rfcs/0000-template.md:21, 0e353436f90b)
  • PR merge result leaves accepted issue blank: The virtual merge commit has status: accepted immediately followed by a blank issue field in the renamed approval RFC. (rfcs/0002-approval-prompt-markdown.md:7, fe4e65572944)
  • PR merge result marks parked RFCs accepted: The virtual merge commit marks a needs_refactoring document accepted with a blank issue field; the same pattern is added to the other two parked RFC renames. (rfcs/needs_refactoring/doctor-health-upgrades.md:7, fe4e65572944)
  • Current accepted examples use issue URLs: Accepted RFCs on current main include non-empty implementation issue URLs, matching the documented lifecycle. (rfcs/0008-context-engine-runtime-settings.md:7, 0e353436f90b)

Likely related people:

  • kevinslin: Git blame ties the accepted-RFC lifecycle text to e366ea9, and file history ties the needs_refactoring move to 5f9f47a. (role: RFC lifecycle policy author and parked-folder reorganization contributor; confidence: high; commits: e366ea9825a4, 5f9f47ac8529, dcbf6c0462bb; files: README.md, rfcs/0000-template.md, rfcs/needs_refactoring/0002-doctor-health-upgrades.md)
  • omarshahine: History ties this person to the merged approval markdown RFC being amended and to the iMessage RFC whose parked filename is changed. (role: original approval RFC contributor and adjacent affected RFC contributor; confidence: high; commits: f346050b2878, 54b2f430a77f, 1a545b1de86d; files: rfcs/0005-approval-prompt-markdown.md, rfcs/needs_refactoring/0004-imessage-channel-configuration-cleanup.md)
  • giodl73-repo: File history ties this handle to the doctor and policy RFCs whose parked filenames and lifecycle metadata are changed by the PR. (role: original parked RFC contributor and recent policy RFC updater; confidence: high; commits: 597685d8c2a3, ccc5e4c64d1c, e46c2a113cc9; files: rfcs/needs_refactoring/0002-doctor-health-upgrades.md, rfcs/needs_refactoring/0003-policy-conformance.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label Jun 11, 2026
@omarshahine @claude
RFC: renumber approval prompt markdown to 0002, resolve questions, al…
f708434 
…ign frontmatter

Renumber the Approval Prompt Markdown Contract from 0005 to 0002 per
maintainer request, and resolve its three open questions into decisions:
- Underline: excluded from the canonical subset (strict cross-channel
  intersection only); core never emits underline.
- Capability: a field (approvalText) on the existing channel approval
  capability object, declared via the public SDK, defaulting to plaintext.
- Exec fence language hints: a small fixed advisory set; channels may honor
  or safely drop them.

Repo cleanup after the needs_refactoring reorg:
- Vacate numeric prefixes on all parked RFCs (doctor-health-upgrades,
  policy-conformance, imessage-channel-configuration-cleanup) so the parked
  folder is uniformly number-free pending re-proposal.
- Align frontmatter to the new RFC lifecycle by adding status/issue keys to
  the parked RFCs plus 0001-lts-release-policy and 0006-feeds.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@omarshahine
omarshahine force-pushed the rfc-0002-approval-prompt-renumber branch from 4a099ce to f708434 Compare June 11, 2026 16:51
@omarshahine omarshahine changed the title RFC: renumber Approval Prompt Markdown Contract to 0002 and resolve open questions RFC: renumber Approval Prompt Markdown to 0002, resolve questions, align frontmatter Jun 11, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. and removed rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. labels Jun 12, 2026
kevinslin and others added 2 commits June 19, 2026 12:20
@kevinslin
Merge remote-tracking branch 'origin/main' into rfc-0002-approval-pro…
dcbf6c0 
…mpt-renumber

# Conflicts:
#	rfcs/0001-lts-release-policy.md
#	rfcs/0006-feeds.md
@omarshahine
Merge remote-tracking branch 'origin/main' into rfc-0002-approval-pro…
fa7e6b8 
…mpt-renumber

# Conflicts:
#	rfcs/needs_refactoring/policy-conformance.md
@omarshahine
omarshahine merged commit bab3348 into main Jun 21, 2026
@omarshahine
omarshahine deleted the rfc-0002-approval-prompt-renumber branch June 21, 2026 22:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kevinslin kevinslin kevinslin approved these changes

Assignees

No one assigned

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@omarshahine @kevinslin