diff --git a/.github/workflows/proposal-numbering.yml b/.github/workflows/proposal-numbering.yml
new file mode 100644
index 0000000..069ebe2
--- /dev/null
+++ b/.github/workflows/proposal-numbering.yml
@@ -0,0 +1,161 @@
+name: Check Proposal Numbering
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ paths:
+ - 'proposals/*.md'
+
+permissions:
+ pull-requests: write
+ contents: read
+
+jobs:
+ check-numbering:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Check proposal file numbering
+ id: check
+ env:
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ run: |
+ # Find all .md files directly in proposals directory (not subdirectories)
+ ALL_PROPOSAL_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep '^proposals/[^/]*\.md$' || true)
+
+ # Filter out non-proposal files (README.md and template)
+ PROPOSAL_FILES=""
+ for file in $ALL_PROPOSAL_FILES; do
+ # Skip README.md and the template
+ if [[ "$file" == "proposals/README.md" ]] || [[ "$file" == "proposals/000-template.md" ]]; then
+ continue
+ fi
+ PROPOSAL_FILES="$PROPOSAL_FILES $file"
+ done
+
+ if [ -z "$PROPOSAL_FILES" ]; then
+ echo "No proposal files found in this PR"
+ echo "has_proposal=false" >> $GITHUB_OUTPUT
+ exit 0
+ fi
+
+ echo "has_proposal=true" >> $GITHUB_OUTPUT
+
+ # Expected filename pattern: proposals/0{PR_NUMBER}-*.md
+ EXPECTED_PREFIX=$(printf "proposals/%03d-" $PR_NUMBER)
+
+ INCORRECT_FILES=""
+ for file in $PROPOSAL_FILES; do
+ if [[ ! "$file" =~ ^${EXPECTED_PREFIX} ]]; then
+ if [ -z "$INCORRECT_FILES" ]; then
+ INCORRECT_FILES="$file"
+ else
+ INCORRECT_FILES="$INCORRECT_FILES,$file"
+ fi
+ fi
+ done
+
+ if [ -n "$INCORRECT_FILES" ]; then
+ echo "incorrect=true" >> $GITHUB_OUTPUT
+ echo "files=$INCORRECT_FILES" >> $GITHUB_OUTPUT
+ echo "expected_prefix=$EXPECTED_PREFIX" >> $GITHUB_OUTPUT
+ else
+ echo "incorrect=false" >> $GITHUB_OUTPUT
+ fi
+
+ - name: Update PR description if numbering is incorrect
+ if: steps.check.outputs.incorrect == 'true'
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const prNumber = context.payload.pull_request.number;
+ const expectedPrefix = '${{ steps.check.outputs.expected_prefix }}';
+ const incorrectFilesRaw = '${{ steps.check.outputs.files }}';
+
+ // Format files as markdown list
+ const filesList = incorrectFilesRaw.split(',').map(f => `- ${f}`).join('\n');
+
+ const warningSection = [
+ '---',
+ '',
+ '## ⚠️ Proposal File Numbering',
+ '',
+ 'This PR contains proposal files that don\'t follow the expected numbering scheme:',
+ '',
+ filesList,
+ '',
+ `**Expected naming:** ${expectedPrefix}<descriptive-name>.md`,
+ '',
+ `Please rename your proposal file to use PR #${prNumber}:`,
+ '',
+ '```bash',
+ `git mv proposals/000-.md ${expectedPrefix}.md`,
+ '# or rename from current name to correct name',
+ `git commit -m "Rename proposal to use PR number ${prNumber}"`,
+ 'git push',
+ '```',
+ '',
+ 'See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the complete workflow.',
+ '',
+ ''
+ ].join('\n');
+
+ // Get current PR
+ const { data: pr } = await github.rest.pulls.get({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ pull_number: prNumber,
+ });
+
+ let currentBody = pr.body || '';
+
+ // Remove existing warning section if present
+ const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal File Numbering[\s\S]*?/;
+ currentBody = currentBody.replace(markerRegex, '').trim();
+
+ // Append new warning section
+ const newBody = currentBody + '\n' + warningSection;
+
+ await github.rest.pulls.update({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ pull_number: prNumber,
+ body: newBody
+ });
+
+ - name: Remove warning from PR description if numbering is correct
+ if: steps.check.outputs.has_proposal == 'true' && steps.check.outputs.incorrect == 'false'
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const prNumber = context.payload.pull_request.number;
+
+ // Get current PR
+ const { data: pr } = await github.rest.pulls.get({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ pull_number: prNumber,
+ });
+
+ let currentBody = pr.body || '';
+
+ // Check if warning section exists
+ const markerRegex = /---\s*\n\s*##\s*⚠️\s*Proposal File Numbering[\s\S]*?/;
+
+ if (markerRegex.test(currentBody)) {
+ // Remove warning section
+ const newBody = currentBody.replace(markerRegex, '').trim();
+
+ await github.rest.pulls.update({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ pull_number: prNumber,
+ body: newBody
+ });
+
+ console.log('Removed numbering warning from PR description - file is now correctly named');
+ }
diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
new file mode 100644
index 0000000..5b582a9
--- /dev/null
+++ b/MIGRATION_GUIDE.md
@@ -0,0 +1,109 @@
+# Proposal Numbering Migration Guide
+
+This guide contains the migration instructions for existing open proposal PRs to adopt the new PR-number-based numbering system.
+
+## Background
+
+We've adopted a new proposal numbering system where proposal numbers match their PR numbers. This eliminates collisions and simplifies the workflow.
+
+## Migration Instructions by PR
+
+### PR #70 - Routing API
+**Current file:** `proposals/004-routing-api.md`
+**New file:** `proposals/070-routing-api.md`
+
+```bash
+git mv proposals/004-routing-api.md proposals/070-routing-api.md
+git commit -m "Rename proposal to use PR number 70"
+git push
+```
+
+### PR #82 - Kroxylicious 1.0
+**Current file:** `proposals/007-kroxylicious-1.0.md`
+**New file:** `proposals/082-kroxylicious-1.0.md`
+
+```bash
+git mv proposals/007-kroxylicious-1.0.md proposals/082-kroxylicious-1.0.md
+git commit -m "Rename proposal to use PR number 82"
+git push
+```
+
+### PR #83 - Hot Reload Feature
+**Current file:** `proposals/012-hot-reload-feature.md`
+**New file:** `proposals/083-hot-reload-feature.md`
+
+```bash
+git mv proposals/012-hot-reload-feature.md proposals/083-hot-reload-feature.md
+git commit -m "Rename proposal to use PR number 83"
+git push
+```
+
+### PR #85 - Audit Logging
+**Current file:** `proposals/nnn-audit-logging.md`
+**New file:** `proposals/085-audit-logging.md`
+
+```bash
+git mv proposals/nnn-audit-logging.md proposals/085-audit-logging.md
+git commit -m "Rename proposal to use PR number 85"
+git push
+```
+
+### PR #88 - Frontend Handler Refactoring
+**Current file:** `proposals/014-frontend-handler-refactoring-and-centralised-session-context.md`
+**New file:** `proposals/088-frontend-handler-refactoring-and-centralised-session-context.md`
+
+```bash
+git mv proposals/014-frontend-handler-refactoring-and-centralised-session-context.md proposals/088-frontend-handler-refactoring-and-centralised-session-context.md
+git commit -m "Rename proposal to use PR number 88"
+git push
+```
+
+### PR #93 - Correlated Request/Response Data API
+**Current file:** `proposals/xxx-correlated-request-response-data-api.md`
+**New file:** `proposals/093-correlated-request-response-data-api.md`
+
+```bash
+git mv proposals/xxx-correlated-request-response-data-api.md proposals/093-correlated-request-response-data-api.md
+git commit -m "Rename proposal to use PR number 93"
+git push
+```
+
+### PR #94 - TLS Configuration Deprecation
+**Current file:** `proposals/nnn-tls-configuration.md`
+**New file:** `proposals/094-tls-configuration.md`
+
+```bash
+git mv proposals/nnn-tls-configuration.md proposals/094-tls-configuration.md
+git commit -m "Rename proposal to use PR number 94"
+git push
+```
+
+## Comment Template for PR Authors
+
+Use this template to comment on each PR:
+
+---
+
+Hi! We've updated the proposal numbering system to use PR numbers instead of sequential allocation. This eliminates number collisions and simplifies the workflow.
+
+**Action required:** Please rename your proposal file to use this PR's number.
+
+**Current file:** `proposals/XXX-name.md`
+**New file:** `proposals/0YY-name.md`
+
+```bash
+git mv proposals/XXX-name.md proposals/0YY-name.md
+git commit -m "Rename proposal to use PR number YY"
+git push
+```
+
+See [proposals/README.md](https://github.com/kroxylicious/design/blob/main/proposals/README.md) for the updated workflow. Going forward, a GitHub Action will automatically remind you if the filename doesn't match the PR number.
+
+---
+
+## After Migration
+
+Once all open PRs have been renamed:
+- The GitHub workflow will automatically check new proposals
+- No manual index maintenance is needed - the directory listing is the index
+- Proposal numbers will match PR numbers going forward
diff --git a/proposals/000-template.md b/proposals/000-template.md
index 538db1e..0088dc7 100644
--- a/proposals/000-template.md
+++ b/proposals/000-template.md
@@ -1,7 +1,21 @@
-
+
#
+**Proposal**: #
+
Provide a brief summary of the feature you are proposing to add to Kroxylicious.
## Current situation
diff --git a/proposals/002-test-workflow.md b/proposals/002-test-workflow.md
new file mode 100644
index 0000000..a0a59f1
--- /dev/null
+++ b/proposals/002-test-workflow.md
@@ -0,0 +1,13 @@
+# Test Proposal for Workflow
+
+**Proposal**: #TBD
+
+This is a test proposal to verify the GitHub workflow correctly detects incorrect proposal numbering and updates the PR description.
+
+## Purpose
+
+Verify that:
+1. The workflow detects this file (starts with 000-)
+2. The workflow updates the PR description with a warning
+3. The workflow provides the correct renaming command
+4. HTML entities are used instead of backticks (cleaner syntax)
diff --git a/proposals/README.md b/proposals/README.md
index 83b3bfb..48ded65 100644
--- a/proposals/README.md
+++ b/proposals/README.md
@@ -1,66 +1,37 @@
# Kroxylicious Proposals
-This repository lists proposals for the Kroxylicious project.
+This directory contains proposals for the Kroxylicious project.
-## For Proposal Authors
+## Creating a New Proposal
-When creating a new proposal:
+1. **Create your proposal file** using a placeholder name based on the [template](./000-template.md):
+ ```
+ proposals/000-.md
+ ```
-1. Create your proposal PR with a temporary filename (e.g. `proposals/nnn-my-proposal.md`) based on the [template](./000-template.md).
-2. After your proposal PR is created, raise a **separate PR** updating this README file to:
- - Allocate your proposal the next sequential number
- - Add an entry in the "Open Proposals" table below
- - Link to your proposal PR
- - Announce your proposal on the mailing list (https://kroxylicious.io/join-us/mailing-lists/)
-3. Once the REAME PRs is merged, rename your proposal file to use the allocated number
-4. When your proposal is approved and about to to be merged:
- - Move your proposal from the "Open Proposals" table to the "Accepted Proposals" table
- - Update the link to point to the merged file instead of the PR
+2. **Commit and open a Pull Request**:
+ - Push your branch and open a PR on GitHub
+ - Note your PR number (e.g., #105)
-This process ensures proposal numbers are allocated in chronological order and avoids conflicts.
+3. **Rename the file** to use your PR number (three-digit zero-padded):
+ ```bash
+ git mv proposals/000-.md proposals/105-.md
+ git commit -m "Rename proposal to use PR number"
+ git push
+ ```
-## Open Proposals (Pull Requests)
+4. **Announce** your proposal on the [mailing list](https://kroxylicious.io/join-us/mailing-lists/)
-Proposals are numbered in chronological order by PR creation date.
+When your proposal is **accepted and merged**, the proposal number remains the same as the PR number.
-⚠️ **Note:** Some proposals have number collisions with accepted proposals and need to be renumbered:
-- PR #70 (currently 004) → should be 016
-- PR #82 (currently 007) → should be 017
-- PR #83 (currently 012) → should be 018
-- PR #85 (currently nnn) → should be 019
-- PR #88 (currently 014) → should be 020
-- PR #89 (currently 016) → should be 021
-- PR #92 (currently xxx) → should be 022
-- PR #93 (currently xxx) → should be 023
-- PR #94 (currently nnn) → should be 024
+## Finding Proposals
-| # | Title | PR |
-|:--:|:----------------------------------------------------------------------|:--:|
-| 24 | [Cleaning up TLS configurations](https://github.com/kroxylicious/design/pull/94) | [#94](https://github.com/kroxylicious/design/pull/94) |
-| 23 | [Request/Response Contextual Data API](https://github.com/kroxylicious/design/pull/93) | [#93](https://github.com/kroxylicious/design/pull/93) |
-| 22 | [Migrate Kroxylicious Operator to Strimzi v1 API](https://github.com/kroxylicious/design/pull/92) | [#92](https://github.com/kroxylicious/design/pull/92) |
-| 21 | [Virtual Cluster Lifecycle](https://github.com/kroxylicious/design/pull/89) | [#89](https://github.com/kroxylicious/design/pull/89) ⚠️ |
-| 20 | [Frontend Handler Refactoring & Client Session Context](https://github.com/kroxylicious/design/pull/88) | [#88](https://github.com/kroxylicious/design/pull/88) ⚠️ |
-| 19 | [Audit logging](https://github.com/kroxylicious/design/pull/85) | [#85](https://github.com/kroxylicious/design/pull/85) |
-| 18 | [Changing Active Proxy Configuration (Hot Reload)](https://github.com/kroxylicious/design/pull/83) | [#83](https://github.com/kroxylicious/design/pull/83) ⚠️ |
-| 17 | [Kroxylicious 1.0 and patch releases](https://github.com/kroxylicious/design/pull/82) | [#82](https://github.com/kroxylicious/design/pull/82) ⚠️ |
-| 16 | [A Routing API](https://github.com/kroxylicious/design/pull/70) | [#70](https://github.com/kroxylicious/design/pull/70) ⚠️ |
+- **All proposals:** Browse the directory listing above
+- **Open proposals:** [View open proposal PRs](https://github.com/kroxylicious/design/pulls?q=is%3Apr+is%3Aopen+label%3Aproposal)
+- **Merged proposals:** Proposal files in this directory (sorted alphabetically)
-## Accepted Proposals
+## Numbering
-| # | Title |
-|:--:|:----------------------------------------------------------------------|
-| 15 | [Entity Isolation Filter](./015-entity-isolation.md) |
-| 14 | [Restrict Operator to a Configurable Set of Namespaces](./014-operator-namespace-restriction.md) |
-| 13 | [Upgrade Project JDK to Java 21](./013-upgrade-project-jdk-to-java-21.md) |
-| 11 | [Plugin API for selecting TLS client credentials for proxy-to-server connection](./011-plugin-api-to-select-tls-credentials-for-server-connection.md) |
-| 10 | [Extend the automatic discovery of bootstrap address feature to handle TLS listeners](./010-automatic-discovery-of-strimzi-bootstrap-server-tls.md) |
-| 9 | [Authorization Filter](./009-authorizer.md) |
-| 8 | [Resolve Topic Names from Topic IDs in the Filter Framework](./008-topic-name-lookup-facility.md) |
-| 7 | [Azure KMS Implementation](./007-azure-kms.md) |
-| 6 | [API to expose client SASL information to Filters](./006-filter-api-to-expose-client-sasl-info.md) |
-| 5 | [Filter API to expose client and server TLS info](./005-filter-api-to-expose-client-and-server-tls-info.md) |
-| 4 | [Terminology for Authentication](./004-terminology-for-authentication.md) |
-| 3 | [Improvements to Kroxylicious (Proxy) Metrics](./003-metric-improvements.md) |
-| 2 | [Automatically trigger a deployment rollout of affected proxies on Kubernetes config change](./002-Automaticly-reload-on-Kubernetes-config-change.md) |
-| 1 | [Kroxylicious Operator API (v1alpha)](./001-kroxylicious-operator-api-v1alpha.md) |
+Proposal numbers match PR numbers, using three-digit zero-padding (e.g., `092-`, `105-`).
+
+Proposals 001-019 predate this system and retain their original numbers.