Feature Request: Support Module-Level Persistent Specifications for Knowledge Retention

## Feature Request: Support Module-Level Persistent Specifications for Knowledge Retention

### Problem Statement

Currently, SpecKit follows a **task-centric workflow** where each development cycle generates specifications (`spec.md`, `plan.md`, `tasks.md`) that are scoped to a single feature or task. While this works well for isolated feature development, it creates a **knowledge gap** in brownfield/evolving projects:

**Current behavior:**
```
Task A → .speckit/specs/001-feature-a/spec.md → Code A (merged)
Task B → .speckit/specs/002-feature-b/spec.md → Code B (merged)
```
- The `spec.md` files describe **"what we're building this time"**
- After merging, these specs become historical artifacts
- **New developers** must reverse-engineer module state from code, not from specs
- **AI agents** lack context about existing module architecture when generating new code

---

### Real-World Use Case

**Scenario:** A team is building an authentication module over multiple sprints:

| Sprint | Task | Current Approach | Problem |
|--------|------|-----------------|---------|
| Sprint 1 | Add basic login | `specs/001-basic-login/spec.md` | Spec describes only "what's new" |
| Sprint 2 | Add OAuth | `specs/002-oauth/spec.md` | Previous spec doesn't reflect current module state |
| Sprint 3 | Add 2FA | `specs/003-2fa/spec.md` | New dev must read 3 specs + code to understand module |

**Pain points:**
- New team members can't understand the **complete current state** of the auth module from specs
- AI agents generate code without knowing what **already exists** in the module
- Team loses **institutional knowledge** as specs become disconnected from reality
- No single source of truth for "what this module does **right now**"

---

### Expected Behavior

Introduce a **two-tier specification architecture**:

#### 1. Task-Level Specs (Existing - No Change Needed)
- **Scope:** Describes **incremental changes** for the current task
- **Purpose:** Drives AI code generation for the specific feature
- **Example:** `.speckit/specs/003-add-2fa/spec.md`

#### 2. Module-Level Specs (New - Requested Feature)
- **Scope:** Describes **complete current state** of a module/component
- **Purpose:**
- Knowledge base for developers joining the project
- Context for AI when generating new code
- Living documentation that evolves with the codebase
- **Example:** `docs/specs/auth-module-spec.md`

**Desired workflow:**
```
Task A → task-spec-A.md → Code A → Update auth-module-spec.md
Task B → task-spec-B.md → Code B → Update auth-module-spec.md
↓
auth-module-spec.md (continuously evolving)
```

**Key expectation:**
- Module-level specs are **version-controlled** alongside code
- They reflect the **complete current capabilities** of each module
- They serve as **long-term knowledge artifacts**, not temporary task documents

---

### Benefits

1. **Knowledge Retention:** Module specs survive across development cycles, becoming institutional knowledge
2. **Onboarding:** New developers understand module state from documentation, not code archaeology
3. **AI Context:** AI agents generate better code by understanding existing module architecture
4. **Traceability:** Git history shows how module capabilities evolved over time
5. **Brownfield Support:** Critical for projects that evolve over months/years with multiple contributors
6. **Cross-team Consistency:** Different teams can understand module boundaries and contracts

---

### Open Questions

1. **Scope:** Should module-level specs be **mandatory** or **optional** (enabled via configuration)?
2. **Location:** What's the preferred directory structure? (`docs/specs/`, `.speckit/modules/`, or configurable?)
3. **Updates:** Should module spec updates be:
- Fully automated (on PR merge)?
- Semi-automated (AI suggests, human reviews)?
- Manual (developer-driven)?
4. **Granularity:** What constitutes a "module"? File-level? Directory-level? Logical component-level?

---

### Related Issues & Discussions

- #916: "Establish best practices for evolving specs" (focuses on SpecKit tool updates, not module-level knowledge)
- Discussion #152: "Evolving specs" (addresses spec evolution but not knowledge retention architecture)

This proposal complements those discussions by introducing a **dual-layer specification model** that addresses both task-level development (existing) and long-term knowledge management (new).

---

**Thank you for considering this enhancement!** This would make SpecKit significantly more powerful for real-world, long-term projects where knowledge retention is as important as feature delivery.