[Feature]: Move assessment artifacts to a configurable docs/speckit/assessments root through staged migration #5039

Problem and rationale

The bundled assess extension stores authored idea-assessment artifacts under .specify/assessments/<slug>/, mixing discovery evidence and decisions with tooling/configuration.

Align with #5037 (#5037): .specify/ holds tooling/configuration and docs/speckit/ provides a consistent authored-artifact hierarchy. Assessments remain a distinct discovery workflow, separate from SDD delivery and bug assessments. Parallel bug tracking: #5038 (#5038).

Proposed solution

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

docs/speckit/assessments/<slug>/
  intake.md
  research.md
  problem.md
  concept.md
  decision.md

The assessment extension owns selection and migration. Support an environment root override, provisionally SPECIFY_ASSESSMENTS_DIR, subject to existing conventions. Define project-level layout selection and environment/project/default precedence so absent environment overrides do not accidentally redirect later stages. Do not automatically persist transient overrides. Relative paths resolve against the Spec Kit project root.

Apply one resolved root consistently across intake/research/define/shape/decide, prerequisites, slug uniqueness/context reuse, artifact references/refinement, and decision-to-SDD handoff. Preserve recorded paths and ongoing workflow selection rather than silently rebasing them under changed configuration.

Migration is explicit and preserves content. Competing assessment copies cause a conflict, not arbitrary precedence, automatic merging, or overwrites. Preserve discovery stage prerequisites, evidence/verdict requirements, empty-project support, and optional forward handoff to SDD. Relocation must not introduce automatic SDD execution or couple discovery to SDD layout selection.

Four-stage rollout

1. Opt-in: Add unified/custom roots while retaining .specify/assessments/ defaults for non-opted-in projects.
2. Deprecation warnings: Warn on the legacy root with actionable migration guidance; no file moves or behavior changes.
3. Default flip with legacy opt-out: Default new adoption to docs/speckit/assessments/; preserve explicit compatibility for existing projects and in-progress assessments.
4. Removal: Retire legacy-root support after an adequate announced transition period. Unmigrated assessments receive migration errors instead of missing-prerequisite errors or duplicate artifacts.

Do not assign specific release versions. PR boundaries alone are not compatibility windows; allow release/adoption time. Assessment, bug, and core rollouts may progress independently.

Acceptance criteria

• Initial opt-in preserves legacy defaults unless explicitly selected.
• Opted-in defaults use docs/speckit/assessments/<slug>/; an environment override relocates the root.
• Layout selection, persistence, precedence, existing-project detection, and project-relative resolution are explicit across all five commands.
• Invalid configuration produces actionable errors rather than silent fallback.
• All artifact reads/writes, prerequisites, slug collision checks, context reuse, refinement, and handoff references use the selected root.
• Existing assessments, recorded paths, and ongoing stage selection remain coherent across upgrades/configuration changes.
• Migration is explicit and preserves content; conflicts across roots are reported without silent precedence or overwrites.
• Source-code write restrictions, overwrite protection, and path-safety guarantees remain intact, including symlink-component rejection and project containment for custom roots.
• Stage prerequisites, evidence/verdict rules, empty-project support, and deliberate optional SDD handoff remain unchanged.
• 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/unsafe roots, conflicts, and pipeline continuity.
• Extension instructions, documentation, examples, handoff guidance, and directly related references are updated together.
• Stages provide adequate announced adoption time without committing to specific versions.

Alternatives and scope

Keeping .specify/assessments/ avoids migration but not separation of authored artifacts from tooling. Putting discovery inside the SDD root blurs discovery/delivery. Core-owned extension paths or a mandatory shared parent variable unnecessarily couple independently configurable workflows. Environment-only selection and automatic moves risk broken continuity and duplicates.

This is a separate staged tracking issue, not an all-stages PR or a requirement to share implementation/release schedules with core and bug work.

extensions/assess/README.md documents current artifact names, slug reuse, explicit artifact refinement, optional decision.md handoff, and symlink rejection/project containment. Relocation must preserve those contracts. All agents are affected.

Replaces the mistakenly filed fork issue mnriem#60, 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.