SPEC-001: process-doc cleanup (dogfooded) - normalize SPEC-<id>-<name>.md filenames, distinguish task vs spec completion, add readiness checklist, actor-owned status table, mutable friction tally, early reference-gap prompts

.devfoundry/improvement-log.md

@@ -2,13 +2,21 @@
 
 Append-only record of retrospectives run by the Process Improver persona, per `.devfoundry/skills/process-retrospective.md`. Each entry is dated and tied to a spec ID. When the same friction (category + affected file) recurs 3+ times, it must be escalated into a proposed edit to the relevant rule, skill, persona, or reference file.
 
-Do not edit or delete past entries. Correct a wrong entry by appending a new one that references it.
+Do not edit or delete past entries. Correct a wrong entry by appending a new one that references it. The Friction Tally below is the one mutable part of this file and is updated in place as entries are appended.
 
 ## Friction Tally
 Maintained by the Process Improver: on every new log entry below, update the count and spec-ID list here for that entry's Category + affected file. This is what makes the "3+ occurrences" escalation rule in `.devfoundry/skills/process-retrospective.md` step 7 checkable at a glance instead of requiring a full re-read of the log.
 
 | Category | Affected file | Count | Spec IDs |
 | :--- | :--- | :--- | :--- |
-| _(none logged yet)_ | | | |
+| none | none | 1 | SPEC-001 |
 
 ---
+
+## 2026-08-19 — SPEC-001
+- **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:** none
+- **Category:** none
+- **Affected file:** none
+- **Proposed change:** none
+- **Status:** LOGGED

.devfoundry/personas/solution-architect.md

@@ -10,7 +10,7 @@ Translate confirmed requirements into a formal technical specification.
 - Backward compatibility with legacy systems
 
 ## Output
-A completed `specs/active/<id>-<name>.md` file, status `DRAFT`, ready for user approval.
+A completed `specs/active/SPEC-<id>-<short-name>.md` file, status `DRAFT`, ready for user approval.
 
 ## Behavioral Rules
 - Reference `.devfoundry/references/sql-dialects.md` and `.devfoundry/references/data-dictionary.md` before proposing schema changes.

.devfoundry/skills/process-retrospective.md

@@ -5,7 +5,7 @@ Purpose: Convert a completed spec's execution history into logged lessons, and e
 Trigger: After the QA Verifier approves a spec (all acceptance criteria pass), before the spec is moved to `specs/archive/`.
 
 ## Steps
-1. **Reconstruct the spec's history.** Read the spec in `specs/active/<id>.md`, its `tasks-template`-derived task list, and the Verification & Regression Plan checklist.
+1. **Reconstruct the spec's history.** Read the spec in `specs/active/SPEC-<id>-<short-name>.md`, its Implementation Plan task list, and the Verification & Regression Plan checklist.
 2. **Ask the deviation question.** Did Builder (Legacy Specialist / Modern Builder) deviate from any rule in `.devfoundry/rules/`, or did QA catch something a rule should have prevented? If yes, note what rule was missing or insufficient.
 3. **Ask the reference-gap question.** Did anyone have to look up or guess environment details, schema facts, or dialect quirks that `.devfoundry/references/*` should already document? If yes, draft the missing fact as a direct edit.
 4. **Ask the requirements question.** Did the spec-interview (`.devfoundry/skills/spec-interview.md`) miss a question that caused rework after implementation started? If yes, note the missing interview question.

.devfoundry/skills/regression-check.md

@@ -4,7 +4,7 @@ Purpose: Validate that a change has not broken existing functionality, especiall
 
 ## Steps
 1. Re-read the spec's Acceptance Criteria and Verification Plan.
-2. Confirm TDD was actually followed, not just that tests exist: for each implementation task in the spec's Implementation Plan, its paired test/manual-verification task should appear before it and there should be no implementation task without one. Check the red/green timestamp note recorded against each pair (per `specs/templates/tasks-template.md`) — the test task's completion time must precede the implementation task's. If a test was clearly written after its implementation, or no timestamp note was recorded, flag it as a process gap for the retrospective.
+2. Confirm TDD was actually followed, not just that tests exist: for each implementation task in the spec's Implementation Plan, its paired test/manual-verification task should appear before it and there should be no implementation task without one. Check the red/green timestamp note recorded against each pair (per `specs/templates/spec-template.md` and `specs/templates/tasks-template.md`) — the test task's completion time must precede the implementation task's. If a test was clearly written after its implementation, or no timestamp note was recorded, flag it as a process gap for the retrospective.
 3. For legacy ASP/VB6/Access code, manually trace affected queries, forms, and reports.
 4. For modern stacks, run the existing automated test suite plus any new tests.
 5. Check any known dependent features listed in `.devfoundry/references/data-dictionary.md`.

.devfoundry/skills/spec-interview.md

@@ -9,5 +9,5 @@ Purpose: Elicit clear, unambiguous requirements before drafting a technical spec
 4. Confirm acceptance criteria in Given/When/Then format.
 5. Identify files/modules likely affected.
 6. Confirm rollback or backward-compatibility needs if database schema changes are involved.
-7. If `.devfoundry/references/environments.md` does not yet list a Build/Test/Lint command for the affected stack, ask the user for the exact command(s) and record them there before drafting the spec — QA Verifier and Builder both depend on these being known, not guessed.
+7. If `.devfoundry/references/environments.md` or `.devfoundry/references/data-dictionary.md` lacks project facts needed by Builder or QA, ask before drafting the spec and record the answer in the relevant reference file. Do not guess. At minimum, confirm build/test/lint commands, runtime versions, database engine and schema source, driver constraints, and legacy error-log paths when they apply.
 8. Summarize findings back to the user for confirmation before drafting the spec.

.devfoundry/skills/technical-spec.md

@@ -9,7 +9,16 @@ Purpose: Convert confirmed requirements into a formal technical specification.
 3a. Before finalizing **Target Files**, check every other spec currently in `specs/active/` for overlap with this list. If another active spec already lists one of the same files, flag it to the user and note the conflicting spec ID in this spec's Business Context — do not silently proceed with both specs touching the same file concurrently.
 4. Define function/API contracts with explicit parameter types.
 5. Break the work into an atomic implementation checklist per `.devfoundry/skills/task-decomposition.md`, pairing each implementation task with a preceding failing-test (or manual-verification, for legacy stacks) task per the TDD rule in `.devfoundry/rules/general.md`.
-6. Mark spec status as `DRAFT` and present to the user for approval before implementation begins.
+6. Run the Spec Readiness Checklist below.
+7. Mark spec status as `DRAFT` and present to the user for approval before implementation begins.
+
+## Spec Readiness Checklist
+- Status is `DRAFT`.
+- Business Context, Acceptance Criteria, Technical Design & Contracts, Implementation Plan, Verification & Regression Plan, and Target Files are complete.
+- Active specs in `specs/active/` have been checked for Target Files overlap.
+- Build/test/lint commands are documented in `.devfoundry/references/environments.md`, or the spec explicitly records that no command exists for the affected stack.
+- If database changes are included, current schema notes, target-engine DDL, dependent queries/views/reports, and rollback or backup steps are documented.
+- Every implementation task has a preceding test/manual-verification task and includes space for `completed: <YYYY-MM-DD HH:MM>` timestamps.
 
 ## Amending an APPROVED or IN PROGRESS Spec
 An `APPROVED` (or later) spec's Acceptance Criteria and Technical Design are frozen. If the user requests a genuine scope change (not a bug in the Builder's execution) after that point:

AGENTS.md

@@ -9,13 +9,16 @@
 [1. Requirements Analyst]  --> Creates/Refines Problem Statement & Acceptance Criteria
       |
       v
-[2. Solution Architect]    --> Creates Technical Design & Schema in specs/active/<id>.md
+[2. Solution Architect]    --> Assigns next ID from specs/.spec-counter; creates
+                                Technical Design & Schema in specs/active/SPEC-<id>-<short-name>.md
       |
       v
 [User Approves Spec]       --> Spec Status changes from DRAFT to APPROVED (Frozen)
       |
       v
-[3. Builder Agent]         --> Executes tasks step-by-step (Legacy Specialist or Modern Builder)
+[3. Builder Agent]         --> Executes tasks step-by-step (Legacy Specialist or Modern Builder).
+                                A post-freeze scope change goes through the REVISED amendment
+                                flow in .devfoundry/skills/technical-spec.md, not a silent edit.
       |
       v
 [4. QA Verifier]           --> Validates against Acceptance Criteria & Regression Matrix
@@ -25,7 +28,7 @@
                                 friction into proposed rule/skill/reference edits
       |
       v
-[Archive Spec]             --> Moves spec to specs/archive/<id>.md
+[Archive Spec]             --> Moves spec to specs/archive/SPEC-<id>-<short-name>.md
 ```
 
 ## Agent Persona Routing Table
@@ -43,5 +46,5 @@
 1. **No Hallucinated Libraries:** Do not introduce third-party libraries/DLLs or modern framework features into legacy stacks unless specified in `.devfoundry/references/environments.md`.
 2. **Schema Invariant:** Database modifications must specify fallback steps and preserve backward compatibility with existing legacy queries.
 3. **Context Passing:** When adopting a role, explicitly reference the persona markdown file in `.devfoundry/personas/` and apply the relevant procedures in `.devfoundry/skills/`.
-4. **Audit Gate:** A task is only marked complete when the QA Verifier confirms all acceptance criteria in the spec pass without regression.
+4. **Audit Gate:** Builder task checkboxes may be marked complete after their local verification passes, but a spec is only marked `COMPLETED` when the QA Verifier confirms all acceptance criteria pass without regression.
 5. **Continuous Improvement Loop:** Every spec passes through the Process Improver before archiving. Lessons are appended to `.devfoundry/improvement-log.md`; friction that recurs 3+ times must be escalated into a proposed amendment to the relevant rule, skill, persona, or reference file, subject to user approval. This is how the workflow itself improves rather than repeating the same manual corrections across specs.

README.md

@@ -13,7 +13,7 @@ See [CLAUDE.md](CLAUDE.md) for the operational directives an agent follows, and
 [1. Requirements Analyst]  --> Elicits problem statement & acceptance criteria
       |
       v
-[2. Solution Architect]    --> Drafts specs/active/<id>-<name>.md (status: DRAFT)
+[2. Solution Architect]    --> Drafts specs/active/SPEC-<id>-<short-name>.md (status: DRAFT)
       |
       v
 [User Approves Spec]       --> Status: DRAFT -> APPROVED (frozen)
@@ -28,7 +28,7 @@ See [CLAUDE.md](CLAUDE.md) for the operational directives an agent follows, and
 [5. Process Improver]      --> Retrospective; logs lessons; escalates recurring friction
       |
       v
-[Archive Spec]             --> Moves spec to specs/archive/<id>-<name>.md
+[Archive Spec]             --> Moves spec to specs/archive/SPEC-<id>-<short-name>.md
 ```
 
 ## Step by Step
@@ -42,18 +42,27 @@ Before any technical design starts, the Requirements Analyst persona ([.devfound
 4. Acceptance criteria, stated as Given/When/Then.
 5. Which files/modules are likely affected.
 6. Rollback or backward-compatibility needs if schema changes are involved.
-7. A summary handed back to the user for confirmation.
+7. Any missing project-reference facts needed for Builder or QA work: runtime versions, build/test/lint commands, database engine and schema sources, driver constraints, and legacy error-log paths.
+8. A summary handed back to the user for confirmation.
 
 This persona never proposes a technical solution — that's the next stage's job. If the request is ambiguous, it asks rather than assumes.
 
 ### 2. Drafting the spec (Solution Architect)
 Once requirements are confirmed, the Solution Architect persona ([.devfoundry/personas/solution-architect.md](.devfoundry/personas/solution-architect.md)) runs [.devfoundry/skills/technical-spec.md](.devfoundry/skills/technical-spec.md):
 
-1. Copy [specs/templates/spec-template.md](specs/templates/spec-template.md) to `specs/active/<id>-<short-name>.md`.
+1. Copy [specs/templates/spec-template.md](specs/templates/spec-template.md) to `specs/active/SPEC-<id>-<short-name>.md`.
 2. Fill in **Business Context**, **Acceptance Criteria**, and **Technical Design & Contracts** — schema changes, function/API signatures with their preconditions and postconditions (see [Coding Standards](#coding-standards) below), architecture, and error handling strategy. Schema and dialect decisions are checked against [.devfoundry/references/sql-dialects.md](.devfoundry/references/sql-dialects.md) and [.devfoundry/references/data-dictionary.md](.devfoundry/references/data-dictionary.md).
 3. If the spec touches a database schema, [.devfoundry/skills/db-schema-change.md](.devfoundry/skills/db-schema-change.md) applies: document the current schema, write exact DDL for the target engine, identify dependent queries/views/reports, and provide a rollback/backup step (mandatory for `.mdb`/`.accdb` files — copy before altering).
 4. Break the work into an atomic, dependency-ordered implementation checklist ([.devfoundry/skills/task-decomposition.md](.devfoundry/skills/task-decomposition.md)): schema changes first, then backend logic, then UI, then verification. Each task touches the minimum files necessary and has a clear definition of done.
-5. Mark the spec `DRAFT` and present it to the user.
+5. Run the Spec Readiness Checklist, mark the spec `DRAFT`, and present it to the user.
+
+Spec Readiness Checklist before approval:
+- Status is `DRAFT`.
+- Business Context, Acceptance Criteria, Technical Design & Contracts, Implementation Plan, Verification & Regression Plan, and Target Files are complete.
+- Active specs have been checked for target-file overlap.
+- Build/test/lint commands are documented in [.devfoundry/references/environments.md](.devfoundry/references/environments.md), or the spec explicitly records that no command exists for the affected stack.
+- Database changes include current schema notes, target-engine DDL, dependent queries/views/reports, and rollback or backup steps.
+- Every implementation task has a preceding test/manual-verification task with `completed: <YYYY-MM-DD HH:MM>` timestamp space.
 
 The Architect does not begin implementation — that only happens after approval.
 
@@ -66,7 +75,7 @@ Depending on what's touched, either the **Legacy Specialist** or **Modern Builde
 - **Legacy Specialist** ([.devfoundry/personas/legacy-specialist.md](.devfoundry/personas/legacy-specialist.md)) — `.asp`, `.vbs`, `.bas`, `.frm`, `.cls`, `.mdb`, `.accdb`. Follows [.devfoundry/rules/legacy-asp-vb6.md](.devfoundry/rules/legacy-asp-vb6.md) and [.devfoundry/rules/database-sql.md](.devfoundry/rules/database-sql.md): explicit COM object release, parameterized ADO queries, defensive error handling, backups before structural Access changes, and TDD via a test harness where one exists (manual verification steps written first, otherwise).
 - **Modern Builder** ([.devfoundry/personas/modern-builder.md](.devfoundry/personas/modern-builder.md)) — `.cs`, `.php`, SQL Server/Postgres/SQLite scripts. Follows [.devfoundry/rules/dotnet-csharp.md](.devfoundry/rules/dotnet-csharp.md) and [.devfoundry/rules/php.md](.devfoundry/rules/php.md): parameterized queries, TDD (test written and run red before any implementation).
 
-Both personas touch only the files listed under the current task, and check the box `[x]` in the spec once a step is done and verified.
+Both personas touch only the files listed under the current task. They may check a task box `[x]` once that task's local verification passes and its `completed: <YYYY-MM-DD HH:MM>` note is recorded. The overall spec is not complete until the QA Verifier approves every acceptance criterion and regression check.
 
 ### 5. QA verification (QA Verifier)
 The QA Verifier persona ([.devfoundry/personas/qa-verifier.md](.devfoundry/personas/qa-verifier.md)) runs [.devfoundry/skills/regression-check.md](.devfoundry/skills/regression-check.md):
@@ -89,7 +98,7 @@ Once QA passes, the Process Improver persona ([.devfoundry/personas/process-impr
 This is what keeps the process itself improving — recurring corrections get folded back into the rules instead of being repeated by hand on every spec.
 
 ### 7. Archive
-The completed spec moves from `specs/active/<id>-<name>.md` to `specs/archive/<id>-<name>.md`. Archived specs are immutable history and are never edited by later retrospectives.
+The completed spec moves from `specs/active/SPEC-<id>-<short-name>.md` to `specs/archive/SPEC-<id>-<short-name>.md`. Archived specs are immutable history and are never edited by later retrospectives.
 
 ## Coding Standards
 
@@ -113,9 +122,15 @@ See [.devfoundry/rules/dotnet-csharp.md](.devfoundry/rules/dotnet-csharp.md), [.
 | `.devfoundry/skills/` | The step-by-step procedures each persona follows |
 | `.devfoundry/rules/` | Stack-specific coding standards (legacy, .NET, PHP, database/SQL, general) |
 | `.devfoundry/references/` | Project-specific facts: environments, data dictionary, SQL dialects |
-| `.devfoundry/improvement-log.md` | Append-only log of retrospectives across all specs |
+| `.devfoundry/improvement-log.md` | Append-only retrospective entries plus a maintained Friction Tally |
 
 ## Spec Status Values
-`DRAFT` → `APPROVED` → `IN PROGRESS` → `COMPLETED` (then archived).
-`APPROVED` flips to `IN PROGRESS` when the Builder checks the first Implementation Plan box.
+| Status | Set by | Meaning / next step |
+| :--- | :--- | :--- |
+| `DRAFT` | Solution Architect | Spec is ready for user review, but implementation has not started. |
+| `APPROVED` | User approval, recorded by the agent | Acceptance Criteria and Technical Design are frozen; Builder may start. |
+| `IN PROGRESS` | Builder | First Implementation Plan task has been started or checked off. |
+| `REVISED` | Solution Architect / Builder, after a post-freeze scope change | Frozen sections have an amendment pending user approval. |
+| `COMPLETED` | QA Verifier | All acceptance criteria and regression checks passed; Process Improver runs before archive. |
+
 A spec can also move `APPROVED`/`IN PROGRESS` → `REVISED` if the user requests a genuine scope change after freeze — see "Amending an APPROVED or IN PROGRESS Spec" in [.devfoundry/skills/technical-spec.md](.devfoundry/skills/technical-spec.md). Once the revision is approved, it returns to `APPROVED` or `IN PROGRESS` and continues toward `COMPLETED`.

specs/.spec-counter

@@ -1 +1 @@
-1
+2

specs/archive/SPEC-001-process-doc-cleanup.md

@@ -0,0 +1,48 @@
+# 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

specs/templates/spec-template.md

@@ -23,11 +23,11 @@
 - **Error Handling Strategy:**
 
 ### 4. Implementation Plan (Atomic Steps, TDD-ordered)
-- [ ] **Step 1:** Prepare schema / table alterations (with rollback instructions).
-- [ ] **Step 2:** Write failing test(s) for the core business logic / backend functions (or, for legacy stacks with no test harness, write the manual verification steps for them). Confirm they fail for the right reason before proceeding.
-- [ ] **Step 3:** Implement core business logic / backend functions — only enough to make Step 2's tests pass.
-- [ ] **Step 4:** Update UI / output views (with tests first, where automatable).
-- [ ] **Step 5:** Run the full manual or automated verification checks.
+- [ ] **Step 1:** Prepare schema / table alterations (with rollback instructions) — files: [file list] — completed:
+- [ ] **Step 2 (test, red):** Write failing test(s) for the core business logic / backend functions (or, for legacy stacks with no test harness, write the manual verification steps for them). Confirm they fail for the right reason before proceeding — files: [test/spec file list] — completed: <YYYY-MM-DD HH:MM>
+- [ ] **Step 3 (implementation, green):** Implement core business logic / backend functions — only enough to make Step 2's tests pass — files: [file list] — completed: <YYYY-MM-DD HH:MM>
+- [ ] **Step 4:** Update UI / output views (with tests first, where automatable) — files: [file list] — completed:
+- [ ] **Step 5:** Run the full manual or automated verification checks — files: [file list] — completed:
 
 ### 5. Verification & Regression Plan
 - [ ] Verify AC-1 manually or via test script.