[Feature]: Unify SDD artifacts under a configurable directory with staged legacy-layout retirement

Start by reading the hardcoded constitution paths in templates/commands/constitution.md, src/specify_cli/command_init.py, and src/specify_cli/presets/_manager.py, then trace the legacy constitution readers and templates/commands/specify.md instructions. Map the shared path resolution and configuration behavior across initialization, constitution sync, feature numbering, and downstream commands. Done means the staged rollout, migration behavior, documentation, and cross-platform coverage meet the acceptance criteria.

Problem and rationale

The project constitution currently lives at .specify/memory/constitution.md, while feature specifications and their related artifacts live under specs/. This separates governance from the artifacts it governs and mixes authored content with tooling/configuration.

Establish a clear boundary: .specify/ contains tooling/configuration; a configurable SDD root contains authored core-process artifacts. The selected proposed unified default is docs/speckit/sdd/, identifying ownership and purpose without claiming the generic specs/ directory. Deeper nesting and the assumption of a docs/ tree are tradeoffs, addressed by configurability.

Proposed solution

.specify/                         # Tooling and configuration
docs/speckit/sdd/                 # Unified SDD artifact root
  constitution.md
  001-user-auth/
    spec.md
    plan.md
    tasks.md

Initially make the unified layout explicit opt-in. Support relocating the entire root through an environment variable, provisionally SPECIFY_SPECS_DIR. Separate unified-layout selection from a custom root override so opting in can use the proposed default without specifying a custom path.

Define persistent project-level selection so missing environment variables do not accidentally switch layouts across terminals, agents, or CI. Proposed precedence: environment override, project setting, applicable layout default. Do not automatically persist transient environment overrides. Relative roots resolve against the Spec Kit project root, not the current working directory.

Preserve SPECIFY_FEATURE_DIRECTORY as a per-feature override that does not relocate the project constitution. Do not silently reinterpret recorded .specify/feature.json paths under a changed root.

Centralize deterministic root/constitution resolution and provide resolved paths to commands. Wire initialization, constitution creation/amendment, preset synchronization/provenance, feature creation/numbering, prerequisite/path helpers, and downstream readers together. Agent instructions must consume the same resolved paths rather than independently guessing configuration.

Migration of existing projects is explicit: preserve authored content, detect the legacy constitution before creating a new one, and report competing constitutions rather than arbitrarily selecting, synchronizing, overwriting, or deleting them. Final selection syntax and migration mechanics remain implementation-design work.

Four-stage rollout

1. Opt-in: Add unified/configurable paths while preserving legacy defaults for projects that have not opted in. Document selection and migration.
2. Deprecation warnings: Warn on the legacy layout with actionable migration guidance. Do not move files or change behavior.
3. Default flip with legacy opt-out: Default newly initialized projects to the unified layout. Preserve explicit legacy compatibility for existing projects, without silent moves or replacement constitutions.
4. Removal: Retire legacy-layout compatibility after an adequate announced transition period. Unmigrated projects receive actionable migration errors, not missing-constitution behavior or replacement artifacts.

No specific release versions are committed. PR boundaries alone are not compatibility windows; allow real release/adoption time. Deprecation applies to the legacy layout, not to configurable artifact roots.

Acceptance criteria

• Initial opt-in leaves all non-opted-in defaults unchanged.
• Unified defaults place constitution and feature directories under docs/speckit/sdd/; an environment override relocates the entire root.
• Selection, configuration precedence, persistence, and existing-project detection are explicit and documented.
• Relative paths resolve consistently from the project root, including invocations in subdirectories; invalid configuration fails explicitly rather than silently falling back.
• Every relevant reader/writer uses the resolved paths, including initialization and constitution-sync preset reconciliation/provenance.
• Per-feature overrides and persisted feature paths retain their meaning.
• Numbering scans the selected root and ignores the constitution file.
• Migration preserves authored content and is deliberate; conflicting constitutions are reported without automatic overwrites or arbitrary precedence.
• Warning, default-flip/opt-out, and removal stages implement the compatibility behavior above.
• Positive and negative coverage demonstrates legacy compatibility, custom roots, absent overrides, invalid configuration, conflicts, and preserved feature selection.
• Bash, Python, and Windows PowerShell 5.1 behavior remains consistent with appropriate validation evidence.
• Core command instructions and directly related documentation explain layout, relocation, migration, and retirement.
• Default flip and removal are gated on compatibility evidence and adequate announced transition time, not predetermined version numbers.

Alternatives and scope

Keeping the split layout avoids migration but not the organization/relocation problem. specs/constitution.md is shallower but still claims a generic root; users may select it through configuration. Environment-only selection risks accidental switching, and automatic moves risk duplicate constitutions or broken workflows.

This is a tracking issue for separate staged PRs, not a request for an all-stages implementation. Bug and idea-assessment extensions follow the common convention in separate tracking issues: github/spec-kit#5038 (https://github.com/github/spec-kit/issues/5038) and github/spec-kit#5039 (https://github.com/github/spec-kit/issues/5039). Core must not become responsible for their domain-specific paths.

Repository evidence: constitution write paths are hardcoded in templates/commands/constitution.md, src/specify_cli/command_init.py, and src/specify_cli/presets/_manager.py; other core commands read the legacy constitution; templates/commands/specify.md explicitly instructs feature creation/numbering under specs/. Changing scripts alone would be incomplete.

Replaces the mistakenly filed fork issue https://github.com/mnriem/spec-kit/issues/58, with the user's authorization. All agents are affected.

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 discussion. The agent inspected relevant repository paths and drafted the rationale, rollout, and acceptance criteria. The user authorized filing upstream and selected docs/speckit/sdd/ as the proposed unified default. Reasoning-effort setting was not available to report. No implementation changes were made.