[Feature]: Move bug workflow artifacts to a configurable docs/speckit/bugs root through staged migration #5038

Problem and rationale

The bundled bug extension stores authored bug reports under .specify/bugs/<slug>/, mixing workflow evidence with tooling/configuration.

Align with #5037 (#5037): keep tooling/configuration in .specify/ and authored workflow artifacts under a clearly owned documentation hierarchy. Bug artifacts remain distinct from SDD and idea-assessment artifacts. Parallel assessment tracking: #5039 (#5039).

Proposed solution

Introduce explicit opt-in to a configurable bug artifact root, defaulting in the new layout to:

docs/speckit/bugs/<slug>/
  assessment.md
  fix.md
  test.md

The bug extension owns selection and migration; core must not acquire bug-specific knowledge merely to enforce a directory convention. Support an environment root override, provisionally SPECIFY_BUGS_DIR, subject to existing configuration conventions. Define project-level layout selection and environment/project/default precedence so absent environment variables do not redirect ongoing workflows. Do not automatically persist transient overrides. Relative roots resolve against the Spec Kit project root.

Apply one resolved root consistently across assess/fix/test, slug uniqueness, prerequisites, reads/writes, hook context (BUG_DIR), and completion/handoff references. Preserve recorded paths and ongoing workflow selection rather than silently rebasing them under changed configuration.

Migration is explicit and preserves authored content. Competing copies of the same slug must cause an actionable conflict, not arbitrary selection, merging, overwriting, or duplicate workflows. Preserve existing stage semantics, source-editing restrictions, overwrite confirmation, and applicable path-safety guarantees.

Four-stage rollout

1. Opt-in: Support unified/custom roots while retaining .specify/bugs/ defaults for non-opted-in projects.
2. Deprecation warnings: Warn on the legacy root with actionable migration guidance, without moving files or changing behavior.
3. Default flip with legacy opt-out: Default new adoption to docs/speckit/bugs/; preserve explicit legacy compatibility for existing projects and in-progress bugs.
4. Removal: Retire legacy-root support after an adequate announced transition period. Detect unmigrated workflows and provide migration errors rather than missing-report errors or duplicate artifact creation.

Do not assign specific release versions. Consecutive PRs are not a compatibility window; allow release/adoption time. The extension can progress independently of core and assessment rollouts.

Acceptance criteria

• Initial opt-in preserves legacy defaults unless explicitly selected.
• Opted-in defaults use docs/speckit/bugs/<slug>/; an environment override can relocate the root.
• Selection, persistence, precedence, existing-project detection, and project-relative path resolution are explicit across commands.
• Invalid configuration produces actionable errors rather than silent fallback.
• Assess/fix/test, prerequisites, slug collision checks, hooks, and report references use the same selected root.
• Existing reports, recorded paths, and in-progress stage selection remain coherent across upgrades/configuration changes.
• Migration is explicit and preserves content; duplicate slugs across roots are surfaced without silent precedence or overwrites.
• Existing stage semantics, source-code editing restrictions, overwrite protection, and applicable path-safety guarantees remain intact.
• Warnings do not change behavior; default flip retains documented legacy opt-out; removal reports clear migration errors.
• Positive and negative coverage demonstrates legacy compatibility, opt-in/custom roots, absent overrides, invalid roots, collisions, and workflow continuity.
• Extension instructions, documentation, examples, hook guidance, and directly related references are updated together.
• The staged transition allows adequate announced adoption time without committing to specific versions.

Alternatives and scope

Keeping .specify/bugs/ avoids migration but leaves authored evidence mixed with tooling. Implementing extension paths in core or adding a shared parent-directory variable introduces unnecessary coupling. Environment-only selection and automatic moves risk broken ongoing work and duplicates.

This is a separate tracking issue, not an expansion of the core SDD implementation or an all-stages PR. The existing contract is documented in extensions/bug/README.md, including the three artifact names and hook reuse of BUG_DIR. All agents are affected.

Replaces the mistakenly filed fork issue mnriem#59, with the user's authorization.

AI disclosure

Drafted and filed on behalf of @mnriem using GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), in human-supervised interactive mode. The agent inspected the bundled README and drafted the rationale, rollout, and acceptance criteria from the user-approved discussion. The user authorized upstream filing. Reasoning-effort setting was not available to report. No implementation changes were made.