# SPEC-001: Process Documentation Cleanup

- **Status:** COMPLETED
- **Stack:** DevFoundry process documentation
- **Target Files:** AGENTS.md, README.md, specs/.spec-counter, specs/templates/spec-template.md, .devfoundry/skills/spec-interview.md, .devfoundry/skills/technical-spec.md, .devfoundry/skills/regression-check.md, .devfoundry/skills/process-retrospective.md, .devfoundry/personas/solution-architect.md, .devfoundry/improvement-log.md

---

### 1. Business Context & Goal
The DevFoundry scaffold is intended to be followed by coding agents without ambiguity. A repo review found several small inconsistencies that could cause process drift: mixed spec filename conventions, unclear task-versus-spec completion language, timestamp requirements that are referenced by QA but missing from the main spec template, implicit status transition ownership, and an append-only log with a mutable tally table.

No other active specs exist, so there are no target-file conflicts.

### 2. Acceptance Criteria (Given / When / Then)
- **AC-1:** Given an agent needs to create a spec, when it reads AGENTS, README, technical-spec, and Solution Architect docs, then all docs use the `SPEC-<id>-<short-name>.md` filename convention.
- **AC-2:** Given an implementation task is completed, when the Builder marks it done, then the docs distinguish task-level completion from spec-level QA approval.
- **AC-3:** Given QA checks TDD ordering, when it reviews the spec, then the main spec template includes `completed: <YYYY-MM-DD HH:MM>` timestamp guidance for test/manual-verification and implementation tasks.
- **AC-4:** Given a draft spec is prepared, when the user reviews it, then the docs provide a readiness checklist before approval.
- **AC-5:** Given a spec moves through the lifecycle, when an agent reads the README, then actor-owned status transitions are explicit.
- **AC-6:** Given the Process Improver updates the improvement log, when it reads the log instructions, then entries are append-only while the Friction Tally is explicitly mutable.
- **AC-7:** Given project-specific runtime/reference details are missing, when requirements are gathered, then the process prompts for them early enough to prevent Builder/QA guesswork.

### 3. Technical Design & Contracts
- **Data Model / Schema Changes:** None.
- **Functions / APIs / Interfaces:** None.
- **Architecture:** Documentation-only process update; no application architecture affected.
- **Error Handling Strategy:** Preserve existing safety gates and avoid weakening any rule. Documentation changes must be consistent across all listed files.

### 4. Implementation Plan (Atomic Steps, TDD-ordered)
- [x] **Step 1 (verification authoring):** Write the manual verification checklist in this spec before changing process docs — files: `specs/active/SPEC-001-process-doc-cleanup.md`, `specs/.spec-counter` — completed: 2026-08-19 22:14
- [x] **Step 2 (implementation):** Normalize spec filename references and task/spec completion language — files: `AGENTS.md`, `README.md`, `.devfoundry/personas/solution-architect.md`, `.devfoundry/skills/process-retrospective.md` — completed: 2026-08-19 22:14
- [x] **Step 3 (implementation):** Add spec readiness, timestamp, status-transition, reference-readiness, and improvement-log mutability guidance — files: `README.md`, `specs/templates/spec-template.md`, `.devfoundry/skills/spec-interview.md`, `.devfoundry/skills/technical-spec.md`, `.devfoundry/skills/regression-check.md`, `.devfoundry/improvement-log.md` — completed: 2026-08-19 22:14
- [x] **Step 4 (verification):** Search the updated docs for stale filename patterns and confirm each acceptance criterion is reflected — files: listed target files — completed: 2026-08-19 22:17

### 5. Verification & Regression Plan
- [x] Verify AC-1 by searching for stale `specs/active/<id>-<name>.md`, `specs/active/<id>-<short-name>.md`, and `specs/archive/<id>-<name>.md` references.
- [x] Verify AC-2 by confirming Builder task completion and QA spec completion are described separately.
- [x] Verify AC-3 by confirming `completed: <YYYY-MM-DD HH:MM>` appears in the main spec template.
- [x] Verify AC-4 by confirming a Spec Readiness Checklist exists before approval.
- [x] Verify AC-5 by confirming README contains an actor-owned status transition table.
- [x] Verify AC-6 by confirming the improvement log distinguishes append-only entries from mutable tally updates.
- [x] Verify AC-7 by confirming early project-reference prompts are documented.

### 6. Retrospective
*Filled by the Process Improver per `.devfoundry/skills/process-retrospective.md`, after QA approval and before archiving.*
- **What worked:** A compact process spec kept the documentation updates scoped, and verification searches caught that the executable interview skill also needed the early-reference prompt.
- **Friction (rule/reference/interview gap, or none):** none
- **Logged in `.devfoundry/improvement-log.md`:** [x] yes