feat: support issue_id_mode=counter for sequential IDs (#2013)

* feat: support issue_id_mode=counter for sequential IDs (GH#2002)

When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`,
`bd create` now assigns monotonically increasing integer IDs instead of
hash-based IDs. The counter is stored in a new `issue_counter` table (one row
per prefix) and incremented atomically within the same transaction as the issue
insert.

- Add `issue_counter` table to schema (version bumped to 5)
- Add migration 006 to create `issue_counter` table on existing databases
- Add `GetNextIssueCounter()` to queries.go (standalone transaction, for
  callers outside CreateIssue)
- Modify `generateIssueID()` to check `issue_id_mode` config and use counter
  path when set to "counter"; hash mode remains the default when unset
- Explicit `--id` flag continues to take precedence over counter mode
- Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes,
  TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter,
  TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable

* docs: document issue_id_mode=counter feature (GH#2002)

Add documentation for the sequential counter ID mode across all relevant docs:
- docs/CONFIG.md: new issue_id_mode namespace entry and full example section
  with tradeoff table, migration guidance, and per-prefix counter isolation
- .beads/BD_GUIDE.md: counter mode section with when-to-use, migration
  considerations, and explicit --id override behavior
- docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference
  to CONFIG.md
- website/docs/reference/configuration.md: issue_id_mode under ID Generation
  with comparison table

* fix: seed counter from existing issues when enabling counter mode (GH#2002)

When issue_id_mode=counter is enabled on a repo that already has manually-created
sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1,
causing immediate collisions.

Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the
highest numeric suffix for the given prefix, and seeds the issue_counter table
from there. The function is idempotent (skips if a counter row already exists)
and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2).

The seeding is called at first counter use: in generateIssueID() (issues.go) and
GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix.

Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric
IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress).

* feat: add bd config schema and describe commands for agent discoverability (GH#2002)

Adds machine-readable config schema so agents can programmatically discover
all available configuration keys without reading source code.

- internal/config/schema.go: new ConfigKeyDef struct and Schema slice with
  43 entries covering core, sync, routing, jira, linear, gitlab, team, mail,
  and YAML-only keys; includes type, default, valid values, description, and
  storage location per key
- cmd/bd/config.go: adds 'bd config schema' (table + --json) and
  'bd config describe <key>' (single-key detail + --json) subcommands

Usage:
  bd config schema
  bd config schema --json | jq '.[] | select(.key == "issue_id_mode")'
  bd config describe issue_id_mode
  bd config describe jira.url --json

* refactor: remove overengineered config schema (keep docs only)

Remove the configSchemaCmd and configDescribeCmd subcommands added in
the previous commit, along with internal/config/schema.go (390 lines of
config key definitions). These are out of scope for GH#2002.

Author: gm2211

.beads/BD_GUIDE.md

@@ -132,6 +132,60 @@ history/
 - ✅ Preserves planning history for archeological research
 - ✅ Reduces noise when browsing the project
 
+### Counter Mode (Sequential IDs)
+
+By default, beads assigns hash-based IDs (e.g., `bd-a3f2`). For projects that prefer
+human-readable sequential IDs (e.g., `bd-1`, `bd-2`), enable counter mode:
+
+```bash
+bd config set issue_id_mode counter
+```
+
+**When to use counter mode:**
+
+- Project-management workflows where stakeholders reference issue numbers in conversations
+- Multi-agent coordination where readable IDs reduce confusion (e.g., "fix bd-42")
+- Teams migrating from Jira/Linear/GitHub Issues that expect sequential numbering
+
+**When to keep hash IDs (default):**
+
+- Multi-agent or multi-branch workflows where issues may be created concurrently on different branches
+- Hash IDs are collision-free by construction; counter IDs can diverge if parallel branches both create issues
+
+**How to enable:**
+
+```bash
+# Enable for this project
+bd config set issue_id_mode counter
+
+# New issues now get sequential IDs
+bd create "Fix login bug" -p 1    # → bd-1
+bd create "Add dark mode" -p 2    # → bd-2
+```
+
+**Migration considerations:**
+
+If the repo already has hash-based IDs, those existing IDs are unchanged. New issues created
+after enabling counter mode will start from 1 (or wherever the counter currently sits). To
+avoid collisions with any existing sequential IDs (e.g., from a previous counter-mode period),
+check the highest integer ID in use before switching.
+
+**Explicit --id overrides counter mode:**
+
+Passing `--id` on `bd create` always uses the provided ID and does not increment the counter:
+
+```bash
+bd create "Backport fix" -p 1 --id bd-special
+# → bd-special (counter unchanged)
+```
+
+**Per-prefix isolation:**
+
+Each prefix has its own counter. If this project routes to multiple prefixes, each prefix
+counts independently (e.g., `bd-1`, `bd-2` and `plug-1`, `plug-2` are separate sequences).
+
+See [docs/CONFIG.md](../docs/CONFIG.md) for full `issue_id_mode` reference.
+
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking

docs/ADAPTIVE_IDS.md

@@ -192,6 +192,29 @@ Potential improvements (not yet implemented):
 - **Dynamic adjustment**: Auto-adjust threshold based on observed collision rate
 - **Compaction-aware**: Don't count compacted issues in collision calculation
 
+## Alternative: Sequential Counter IDs
+
+Adaptive hash IDs are the default, but beads also supports sequential integer IDs
+(`bd-1`, `bd-2`, ...) for projects that prefer human-readable numbering.
+
+Counter mode is controlled by the `issue_id_mode` config key:
+
+```bash
+# Switch to sequential IDs
+bd config set issue_id_mode counter
+
+# Revert to hash IDs (default)
+bd config set issue_id_mode hash
+```
+
+**Tradeoff:**
+
+- **Hash IDs** (this document): Collision-free across parallel branches and agents; IDs are less predictable but always unique.
+- **Counter IDs**: Human-friendly and sequential; require care in multi-branch workflows where counters can diverge.
+
+See [CONFIG.md](CONFIG.md) for full documentation on `issue_id_mode=counter`, including migration
+guidance and per-prefix counter isolation.
+
 ## Related
 
 - [Migration Guide](../README.md#migration) - Converting from sequential to hash IDs

docs/CONFIG.md

@@ -311,6 +311,7 @@ Configuration keys use dot-notation namespaces to organize settings:
 
 - `compact_*` - Compaction settings (see EXTENDING.md)
 - `issue_prefix` - Issue ID prefix (managed by `bd init`)
+- `issue_id_mode` - ID generation mode: `hash` (default) or `counter` (sequential integers)
 - `max_collision_prob` - Maximum collision probability for adaptive hash IDs (default: 0.25)
 - `min_hash_length` - Minimum hash ID length (default: 4)
 - `max_hash_length` - Maximum hash ID length (default: 8)
@@ -333,6 +334,83 @@ Use these namespaces for external integrations:
 - `github.*` - GitHub integration settings
 - `custom.*` - Custom integration settings
 
+### Example: Sequential Counter IDs (issue_id_mode=counter)
+
+By default, beads generates hash-based IDs (e.g., `bd-a3f2`, `bd-7f3a8`). For projects that prefer
+short sequential IDs (e.g., `bd-1`, `bd-2`, `bd-3`), enable counter mode:
+
+```bash
+bd config set issue_id_mode counter
+```
+
+**Valid values:**
+
+| Value | Behavior |
+|-------|----------|
+| `hash` | (default) Hash-based IDs, adaptive length, collision-safe |
+| `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, ... |
+
+**Counter mode behavior:**
+- Each prefix (`bd`, `plug`, etc.) has its own independent counter
+- Counter is stored atomically in the database; concurrent creates within a single Dolt session are safe
+- Explicit `--id` flag always overrides counter mode (the counter is not incremented)
+
+**Enabling counter mode:**
+
+```bash
+bd config set issue_id_mode counter
+
+# Now new issues get sequential IDs
+bd create "First issue" -p 1
+# → bd-1
+
+bd create "Second issue" -p 2
+# → bd-2
+```
+
+**Migration warning:** If you switch an existing repository to counter mode, seed the counter
+to avoid collisions with existing IDs. Find your highest current integer ID and set the counter
+accordingly:
+
+```bash
+# Check your highest existing sequential ID (if any)
+bd list --json | jq -r '.[].id' | grep -E '^bd-[0-9]+$' | sort -t- -k2 -n | tail -1
+
+# Seed the counter (e.g., if highest existing ID is bd-42)
+bd config set issue_id_mode counter
+# The counter auto-initializes at 0; new issues start at 1
+# If you already have bd-1 through bd-42, manually set counter:
+# (no direct CLI for seeding — use bd dolt sql or create/delete N issues)
+```
+
+For fresh repositories switching to counter mode before any issues exist, no seeding is needed.
+
+**Per-prefix counter isolation:**
+
+Each issue prefix maintains its own counter independently. In multi-repo or routed setups,
+`bd-*` issues and `plug-*` issues each start at 1:
+
+```bash
+# Prefix "bd" and prefix "plug" have independent counters
+bd create "Core task" -p 1          # → bd-1
+bd create "Plugin task" -p 1        # → plug-1 (if prefix is "plug")
+```
+
+**Tradeoff — hash vs. counter:**
+
+| | Hash IDs | Counter IDs |
+|---|---|---|
+| Human readability | Lower (e.g., `bd-a3f2`) | Higher (e.g., `bd-1`) |
+| Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) |
+| Predictability | Unpredictable | Sequential |
+| Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs |
+
+Counter IDs are well-suited for linear project-management workflows and human-facing issue tracking.
+Hash IDs are safer when multiple agents or branches create issues concurrently, since each hash is
+independently unique without coordination.
+
+See [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) for full documentation on hash-based ID generation.
+
 ### Example: Adaptive Hash ID Configuration
 
 ```bash

internal/storage/dolt/issues.go

@@ -1084,9 +1084,115 @@ func recordEvent(ctx context.Context, tx *sql.Tx, issueID string, eventType type
 	return err
 }
 
-// generateIssueID generates a unique hash-based ID for an issue
-// Uses adaptive length based on database size and tries multiple nonces on collision
+// seedCounterFromExistingIssuesTx scans existing issues to find the highest numeric suffix
+// for the given prefix, then seeds the issue_counter table if no row exists yet.
+// This is called when counter mode is first enabled on a repo that already has issues,
+// to prevent counter collisions with manually-created sequential IDs (GH#2002).
+// It is idempotent: if a counter row already exists for this prefix, it does nothing.
+func seedCounterFromExistingIssuesTx(ctx context.Context, tx *sql.Tx, prefix string) error {
+	// Check whether a counter row already exists for this prefix.
+	// If it does, we must not overwrite it (the counter may already be in use).
+	var existing int
+	err := tx.QueryRowContext(ctx, "SELECT last_id FROM issue_counter WHERE prefix = ?", prefix).Scan(&existing)
+	if err == nil {
+		// Row exists - counter is already initialized, nothing to do.
+		return nil
+	}
+	if err != sql.ErrNoRows {
+		return fmt.Errorf("failed to check issue_counter for prefix %q: %w", prefix, err)
+	}
+
+	// No counter row yet. Scan existing issues to find the highest numeric suffix.
+	likePattern := prefix + "-%"
+	rows, err := tx.QueryContext(ctx, "SELECT id FROM issues WHERE id LIKE ?", likePattern)
+	if err != nil {
+		return fmt.Errorf("failed to query existing issues for prefix %q: %w", prefix, err)
+	}
+	defer rows.Close()
+
+	maxNum := 0
+	prefixDash := prefix + "-"
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return fmt.Errorf("failed to scan issue id: %w", err)
+		}
+		// Strip the prefix and attempt to parse the remainder as an integer.
+		suffix := strings.TrimPrefix(id, prefixDash)
+		if suffix == id {
+			// id did not start with prefix- (should not happen given LIKE, but be safe)
+			continue
+		}
+		var num int
+		if _, parseErr := fmt.Sscanf(suffix, "%d", &num); parseErr == nil && fmt.Sprintf("%d", num) == suffix {
+			if num > maxNum {
+				maxNum = num
+			}
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("failed to iterate existing issues for prefix %q: %w", prefix, err)
+	}
+
+	// Only insert a seed row if we found at least one numeric ID.
+	// If no numeric IDs exist, the counter will naturally start at 1 on first use.
+	if maxNum > 0 {
+		_, err = tx.ExecContext(ctx,
+			"INSERT INTO issue_counter (prefix, last_id) VALUES (?, ?)",
+			prefix, maxNum)
+		if err != nil {
+			return fmt.Errorf("failed to seed issue_counter for prefix %q at %d: %w", prefix, maxNum, err)
+		}
+	}
+
+	return nil
+}
+
+// generateIssueID generates a unique ID for an issue.
+// If issue_id_mode=counter is configured, generates sequential IDs (bd-1, bd-2, ...).
+// Otherwise uses the default hash-based ID generation.
 func generateIssueID(ctx context.Context, tx *sql.Tx, prefix string, issue *types.Issue, actor string) (string, error) {
+	// Check issue_id_mode config (within the current transaction)
+	var idMode string
+	err := tx.QueryRowContext(ctx, "SELECT value FROM config WHERE `key` = ?", "issue_id_mode").Scan(&idMode)
+	if err != nil && err != sql.ErrNoRows {
+		return "", fmt.Errorf("failed to read issue_id_mode config: %w", err)
+	}
+
+	if idMode == "counter" {
+		// Sequential counter mode: increment atomically within this transaction.
+		// If no counter row exists yet, seed from existing issues first to avoid
+		// collisions with manually-created sequential IDs (GH#2002).
+		var lastID int
+		err2 := tx.QueryRowContext(ctx, "SELECT last_id FROM issue_counter WHERE prefix = ?", prefix).Scan(&lastID)
+		if err2 == sql.ErrNoRows {
+			// No counter row yet - seed from existing issues before proceeding.
+			if seedErr := seedCounterFromExistingIssuesTx(ctx, tx, prefix); seedErr != nil {
+				return "", fmt.Errorf("failed to seed issue counter for prefix %q: %w", prefix, seedErr)
+			}
+			// Re-read the (possibly just-seeded) counter value.
+			err2 = tx.QueryRowContext(ctx, "SELECT last_id FROM issue_counter WHERE prefix = ?", prefix).Scan(&lastID)
+			if err2 != nil && err2 != sql.ErrNoRows {
+				return "", fmt.Errorf("failed to read issue counter after seeding for prefix %q: %w", prefix, err2)
+			}
+			if err2 == sql.ErrNoRows {
+				lastID = 0
+			}
+		} else if err2 != nil {
+			return "", fmt.Errorf("failed to read issue counter for prefix %q: %w", prefix, err2)
+		}
+		nextID := lastID + 1
+		_, err3 := tx.ExecContext(ctx, `
+			INSERT INTO issue_counter (prefix, last_id) VALUES (?, ?)
+			ON DUPLICATE KEY UPDATE last_id = ?
+		`, prefix, nextID, nextID)
+		if err3 != nil {
+			return "", fmt.Errorf("failed to update issue counter for prefix %q: %w", prefix, err3)
+		}
+		return fmt.Sprintf("%s-%d", prefix, nextID), nil
+	}
+
+	// Default hash-based ID generation
 	// Get adaptive base length based on current database size
 	baseLength, err := GetAdaptiveIDLengthTx(ctx, tx, prefix)
 	if err != nil {

internal/storage/dolt/migrations.go

@@ -24,6 +24,7 @@ var migrationsList = []Migration{
 	{"orphan_detection", migrations.DetectOrphanedChildren},
 	{"wisps_table", migrations.MigrateWispsTable},
 	{"wisp_auxiliary_tables", migrations.MigrateWispAuxiliaryTables},
+	{"issue_counter_table", migrations.MigrateIssueCounterTable},
 }
 
 // RunMigrations executes all registered Dolt migrations in order.

internal/storage/dolt/migrations/006_issue_counter.go

@@ -0,0 +1,29 @@
+package migrations
+
+import (
+	"database/sql"
+	"fmt"
+)
+
+// MigrateIssueCounterTable creates the issue_counter table used for
+// sequential issue ID generation when issue_id_mode=counter is configured.
+// The table stores one row per prefix, tracking the last assigned integer.
+func MigrateIssueCounterTable(db *sql.DB) error {
+	exists, err := tableExists(db, "issue_counter")
+	if err != nil {
+		return fmt.Errorf("failed to check issue_counter existence: %w", err)
+	}
+	if exists {
+		return nil
+	}
+
+	_, err = db.Exec(`CREATE TABLE issue_counter (
+    prefix VARCHAR(255) PRIMARY KEY,
+    last_id INT NOT NULL DEFAULT 0
+)`)
+	if err != nil {
+		return fmt.Errorf("failed to create issue_counter table: %w", err)
+	}
+
+	return nil
+}

internal/storage/dolt/migrations/migrations_test.go

@@ -291,3 +291,50 @@ func TestMigrateWispsTable(t *testing.T) {
 		t.Fatalf("expected title 'Test Wisp', got %q", title)
 	}
 }
+
+func TestMigrateIssueCounterTable(t *testing.T) {
+	db := openTestDolt(t)
+
+	// Verify issue_counter table does not exist yet
+	exists, err := tableExists(db, "issue_counter")
+	if err != nil {
+		t.Fatalf("failed to check table: %v", err)
+	}
+	if exists {
+		t.Fatal("issue_counter should not exist yet")
+	}
+
+	// Run migration
+	if err := MigrateIssueCounterTable(db); err != nil {
+		t.Fatalf("migration failed: %v", err)
+	}
+
+	// Verify issue_counter table now exists
+	exists, err = tableExists(db, "issue_counter")
+	if err != nil {
+		t.Fatalf("failed to check table after migration: %v", err)
+	}
+	if !exists {
+		t.Fatal("issue_counter should exist after migration")
+	}
+
+	// Run migration again (idempotent)
+	if err := MigrateIssueCounterTable(db); err != nil {
+		t.Fatalf("re-running migration should be idempotent: %v", err)
+	}
+
+	// Verify we can INSERT and query from issue_counter
+	_, err = db.Exec("INSERT INTO issue_counter (prefix, last_id) VALUES ('bd', 5)")
+	if err != nil {
+		t.Fatalf("failed to insert into issue_counter: %v", err)
+	}
+
+	var lastID int
+	err = db.QueryRow("SELECT last_id FROM issue_counter WHERE prefix = 'bd'").Scan(&lastID)
+	if err != nil {
+		t.Fatalf("failed to query issue_counter: %v", err)
+	}
+	if lastID != 5 {
+		t.Errorf("expected last_id 5, got %d", lastID)
+	}
+}