From 7eacb99d4ee87f60ff41112bd40dba85cb26da2d Mon Sep 17 00:00:00 2001 From: Daniel Covington Date: Wed, 19 Aug 2026 22:46:28 -0400 Subject: [PATCH] SPEC-003: harden DevFoundry process docs --- .devfoundry/improvement-log.md | 10 ++++- .devfoundry/skills/technical-spec.md | 8 ++++ CLAUDE.md | 2 + README.md | 8 +++- docs/process-checks.md | 48 +++++++++++++++++++++ specs/.spec-counter | 2 +- specs/archive/SPEC-003-process-hardening.md | 45 +++++++++++++++++++ specs/templates/spec-template.md | 14 ++++-- 8 files changed, 131 insertions(+), 6 deletions(-) create mode 100644 docs/process-checks.md create mode 100644 specs/archive/SPEC-003-process-hardening.md diff --git a/.devfoundry/improvement-log.md b/.devfoundry/improvement-log.md index 6b35cff..3abf681 100644 --- a/.devfoundry/improvement-log.md +++ b/.devfoundry/improvement-log.md @@ -9,7 +9,7 @@ Maintained by the Process Improver: on every new log entry below, update the cou | Category | Affected file | Count | Spec IDs | | :--- | :--- | :--- | :--- | -| none | none | 2 | SPEC-001, SPEC-002 | +| none | none | 3 | SPEC-001, SPEC-002, SPEC-003 | --- @@ -28,3 +28,11 @@ Maintained by the Process Improver: on every new log entry below, update the cou - **Affected file:** none - **Proposed change:** none - **Status:** LOGGED + +## 2026-08-19 — SPEC-003 +- **What worked:** The new `docs/process-checks.md` made verification straightforward, and the checks caught one small regex mismatch before closeout. +- **Friction:** none +- **Category:** none +- **Affected file:** none +- **Proposed change:** none +- **Status:** LOGGED diff --git a/.devfoundry/skills/technical-spec.md b/.devfoundry/skills/technical-spec.md index 42fc816..8eaf4ec 100644 --- a/.devfoundry/skills/technical-spec.md +++ b/.devfoundry/skills/technical-spec.md @@ -18,8 +18,16 @@ Purpose: Convert confirmed requirements into a formal technical specification. - 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. +- If no database/schema changes are included, the Data Model / Schema Changes section records exactly: `No schema changes; rollback is git revert.` - Every implementation task has a preceding test/manual-verification task and includes space for `completed: ` timestamps. +## Abandoning a DRAFT Spec +If the user cancels a `DRAFT` spec before approval: +1. Set the spec's `Status` field to `ABANDONED`. +2. Add a brief cancellation reason in Business Context or a final note at the bottom of the spec. +3. Move it to `specs/archive/SPEC--.md`. +4. Do not decrement `specs/.spec-counter` and do not reuse the ID. + ## 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: 1. Do not edit the frozen sections in place. Append a new `## Revision — ` section to the bottom of the spec file describing what changed and why. diff --git a/CLAUDE.md b/CLAUDE.md index 43cbf6a..d744d6d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,7 @@ You are an expert polyglot software engineer operating in a strict **Spec-Driven - **Spec First:** Do not write code or modify files without an approved spec in `specs/active/`. - **Legacy Safety First:** - In Classic ASP / VB6: Explicitly release COM objects (`Set obj = Nothing`), avoid undocumented global state, and handle errors defensively (`On Error Resume Next` only with immediate `Err.Number` checks). + - In ASP Classic web applications: RouteKit Classic ASP is the sanctioned MVC framework for this workspace. Follow `.devfoundry/references/asp-classic-framework.md`; use its routing, DAL, migrations, error handling, and aspunit conventions, and do not modify its `core/` files unless an approved spec explicitly says so. - In Access (MDB/ACCDB): Watch for file locks, table locking during large batch operations, and driver variations between 32-bit and 64-bit systems. - Parameterize all database queries (ADO Parameters, PDO, or SqlCommand) to eliminate SQL injection vulnerabilities. - **Scope Discipline:** Touch only the files designated in the active task. @@ -14,6 +15,7 @@ You are an expert polyglot software engineer operating in a strict **Spec-Driven ## 2. Dynamic Stack Rules Lookup Before modifying or analyzing any file, check the appropriate rule file: - Classic ASP / VB6 / VBScript: `.devfoundry/rules/legacy-asp-vb6.md` +- ASP Classic RouteKit applications: `.devfoundry/references/asp-classic-framework.md` - C# / ASP.NET: `.devfoundry/rules/dotnet-csharp.md` - PHP: `.devfoundry/rules/php.md` - Access / SQLite / SQL Server / Postgres: `.devfoundry/rules/database-sql.md` diff --git a/README.md b/README.md index 0ffc159..933dd28 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ Spec Readiness Checklist before approval: - 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. +- Specs with no database/schema changes record exactly: `No schema changes; rollback is git revert.` - Every implementation task has a preceding test/manual-verification task with `completed: ` timestamp space. The Architect does not begin implementation — that only happens after approval. @@ -69,6 +70,9 @@ The Architect does not begin implementation — that only happens after approval ### 3. Approval gate The user reviews the DRAFT spec and approves it. Status flips `DRAFT -> APPROVED`, and the spec is now frozen: its Acceptance Criteria and Technical Design sections don't change without going back through this gate. +### 3a. Abandoning a draft +If the user cancels a DRAFT spec before approval, set its status to `ABANDONED`, add a brief cancellation reason in the Business Context or a final note, and move it to `specs/archive/SPEC--.md`. Do not decrement `specs/.spec-counter` and do not reuse the ID. + ### 4. Implementation (Builder) Depending on what's touched, either the **Legacy Specialist** or **Modern Builder** persona executes the implementation checklist one unchecked box at a time, in the TDD order the checklist was written in: write the failing test (or manual verification step) for a box, confirm it fails, then implement until it passes. @@ -115,9 +119,10 @@ See [.devfoundry/rules/dotnet-csharp.md](.devfoundry/rules/dotnet-csharp.md), [. | Path | Contents | | :--- | :--- | | `specs/active/` | Specs currently DRAFT, APPROVED, IN PROGRESS, or REVISED | -| `specs/archive/` | Completed, immutable specs | +| `specs/archive/` | Completed or abandoned immutable specs | | `specs/templates/` | `spec-template.md`, `tasks-template.md` | | `specs/.spec-counter` | Next unused spec ID; incremented by the Solution Architect each time a spec is created — never reused | +| `docs/process-checks.md` | Repeatable process verification checks for workflow documentation changes | | `.devfoundry/personas/` | The six agent roles in the lifecycle above | | `.devfoundry/skills/` | The step-by-step procedures each persona follows | | `.devfoundry/rules/` | Stack-specific coding standards (legacy, .NET, PHP, database/SQL, general) | @@ -132,5 +137,6 @@ See [.devfoundry/rules/dotnet-csharp.md](.devfoundry/rules/dotnet-csharp.md), [. | `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. | +| `ABANDONED` | User cancellation, recorded by the agent | Draft work was cancelled before approval; the spec is archived and its ID is never reused. | 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`. diff --git a/docs/process-checks.md b/docs/process-checks.md new file mode 100644 index 0000000..686dcde --- /dev/null +++ b/docs/process-checks.md @@ -0,0 +1,48 @@ +# Process Checks + +Use these repeatable checks after changing DevFoundry workflow docs, templates, skills, or personas. Run them from the repository root. + +## Filename Convention +Confirm live process docs and templates use the canonical `SPEC--.md` convention and do not reintroduce stale patterns: + +```powershell +rg "specs/active/-|specs/archive/-|SPEC--|specs/active/\.md|specs/archive/\.md" AGENTS.md README.md CLAUDE.md .devfoundry specs\templates -g "*.md" +``` + +Expected result: no matches. + +## Status Values +Confirm status guidance includes the lifecycle statuses, including cancelled draft handling: + +```powershell +rg "DRAFT|APPROVED|IN PROGRESS|REVISED|COMPLETED|ABANDONED" README.md specs\templates\spec-template.md .devfoundry\skills\technical-spec.md +``` + +Expected result: each status appears in the appropriate status table, template, or procedure. + +## Spec Readiness +Confirm readiness guidance exists in both the spec-generation skill and the spec artifact template: + +```powershell +rg "Spec Readiness Checklist|Spec Creation Checklist|No schema changes; rollback is git revert|completed: " README.md .devfoundry\skills\technical-spec.md specs\templates\spec-template.md +``` + +Expected result: all four phrases appear. + +## RouteKit ASP Classic Guidance +Confirm ASP Classic framework guidance is discoverable from the agent entry points: + +```powershell +rg "RouteKit|asp-classic-framework\.md|core/" AGENTS.md CLAUDE.md .devfoundry\references\asp-classic-framework.md +``` + +Expected result: `AGENTS.md`, `CLAUDE.md`, and the RouteKit reference match. + +## Retrospective Log +Confirm the improvement log keeps append-only entries while allowing the tally table to change: + +```powershell +rg "Friction Tally below is the one mutable|LOGGED|ESCALATED|APPLIED" .devfoundry\improvement-log.md +``` + +Expected result: the mutable-tally rule and retrospective statuses are present. diff --git a/specs/.spec-counter b/specs/.spec-counter index 00750ed..b8626c4 100644 --- a/specs/.spec-counter +++ b/specs/.spec-counter @@ -1 +1 @@ -3 +4 diff --git a/specs/archive/SPEC-003-process-hardening.md b/specs/archive/SPEC-003-process-hardening.md new file mode 100644 index 0000000..d4809d2 --- /dev/null +++ b/specs/archive/SPEC-003-process-hardening.md @@ -0,0 +1,45 @@ +# SPEC-003: Process Hardening + +- **Status:** COMPLETED +- **Stack:** DevFoundry process documentation +- **Target Files:** CLAUDE.md, README.md, specs/.spec-counter, specs/templates/spec-template.md, .devfoundry/skills/technical-spec.md, docs/process-checks.md + +--- + +### 1. Business Context & Goal +The DevFoundry workflow is usable, but the latest repo review identified several small hardening changes that would make spec creation, framework guidance, no-schema-change handling, abandoned specs, and repeatable process verification clearer. These updates are documentation/template-only and do not affect application code. + +No other active specs exist, so there are no target-file conflicts. + +### 2. Acceptance Criteria (Given / When / Then) +- **AC-1:** Given an agent creates a new spec, when it uses `spec-template.md`, then the spec artifact itself includes a Spec Creation Checklist. +- **AC-2:** Given an agent reads operational directives before ASP Classic work, when it checks `CLAUDE.md`, then it sees the sanctioned RouteKit Classic ASP framework exception/reference. +- **AC-3:** Given a docs-only, UI-only, or otherwise non-schema spec is drafted, when the agent fills the template, then the template provides an explicit no-schema-change rollback pattern. +- **AC-4:** Given a draft spec is cancelled, when an agent reads the process docs, then there is an explicit `ABANDONED` status and abandonment procedure that preserves the spec ID. +- **AC-5:** Given an agent wants to verify process docs after an update, when it reads `docs/process-checks.md`, then it has repeatable `rg` checks for naming, status, checklist, timestamp, and RouteKit guidance. + +### 3. Technical Design & Contracts +- **Data Model / Schema Changes:** None. Rollback is a git revert of documentation changes. +- **Functions / APIs / Interfaces:** None. +- **Architecture:** Documentation-only process update. +- **Error Handling Strategy:** Preserve existing safety gates and avoid weakening any rule. New guidance must be consistent with existing lifecycle and counter rules. + +### 4. Implementation Plan (Atomic Steps, TDD-ordered) +- [x] **Step 1 (verification authoring):** Write this spec and verification checklist before modifying process docs — files: `specs/active/SPEC-003-process-hardening.md`, `specs/.spec-counter` — completed: 2026-08-19 22:42 +- [x] **Step 2 (implementation):** Add spec creation checklist and no-schema rollback pattern — files: `specs/templates/spec-template.md` — completed: 2026-08-19 22:44 +- [x] **Step 3 (implementation):** Add RouteKit operational guidance and abandoned-spec process — files: `CLAUDE.md`, `README.md`, `.devfoundry/skills/technical-spec.md` — completed: 2026-08-19 22:44 +- [x] **Step 4 (implementation):** Add repeatable process verification checklist — files: `docs/process-checks.md`, `README.md` — completed: 2026-08-19 22:44 +- [x] **Step 5 (verification):** Run repeatable checks and confirm acceptance criteria — files: listed target files — completed: 2026-08-19 22:45 + +### 5. Verification & Regression Plan +- [x] Verify AC-1 by confirming `spec-template.md` includes a Spec Creation Checklist section. +- [x] Verify AC-2 by confirming `CLAUDE.md` references RouteKit and `.devfoundry/references/asp-classic-framework.md`. +- [x] Verify AC-3 by confirming `spec-template.md` includes the exact no-schema rollback pattern. +- [x] Verify AC-4 by confirming README and technical-spec document `ABANDONED` without reusing IDs. +- [x] Verify AC-5 by confirming `docs/process-checks.md` exists and contains repeatable `rg` checks. + +### 6. Retrospective +*Filled by the Process Improver per `.devfoundry/skills/process-retrospective.md`, after QA approval and before archiving.* +- **What worked:** The new `docs/process-checks.md` made verification straightforward, and the checks caught one small regex mismatch before closeout. +- **Friction (rule/reference/interview gap, or none):** none +- **Logged in `.devfoundry/improvement-log.md`:** [x] yes diff --git a/specs/templates/spec-template.md b/specs/templates/spec-template.md index ed46980..f380180 100644 --- a/specs/templates/spec-template.md +++ b/specs/templates/spec-template.md @@ -1,11 +1,19 @@ # SPEC-000: [Feature / Bug Fix Title] -- **Status:** DRAFT | APPROVED | IN PROGRESS | REVISED | COMPLETED +- **Status:** DRAFT | APPROVED | IN PROGRESS | REVISED | COMPLETED | ABANDONED - **Stack:** [e.g., ASP Classic + Access MDB | C# ASP.NET Core + Postgres | PHP + SQLite] - **Target Files:** [List of files to be created/modified] --- +### 0. Spec Creation Checklist +- [ ] Status is `DRAFT` before user approval. +- [ ] Target Files are listed and checked for overlap with other active specs. +- [ ] Build/test/lint commands are documented in `.devfoundry/references/environments.md`, or this 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. +- [ ] If there are no database/schema changes, record exactly: `No schema changes; rollback is git revert.` +- [ ] Every implementation task has a preceding test/manual-verification task and `completed: ` timestamp space. + ### 1. Business Context & Goal *Why is this change being made? What is the expected business outcome?* @@ -14,7 +22,7 @@ - **AC-2:** Given [invalid input], when [action], then [graceful error handling]. ### 3. Technical Design & Contracts -- **Data Model / Schema Changes:** (SQL statements or Access table structural updates) +- **Data Model / Schema Changes:** (SQL statements or Access table structural updates; if none, write exactly: `No schema changes; rollback is git revert.`) - **Functions / APIs / Interfaces:** (state preconditions, postconditions, and invariants per Design by Contract — see `.devfoundry/rules/general.md`) - `FunctionName(param1 As String, param2 As Integer) As Boolean` - Preconditions: @@ -23,7 +31,7 @@ - **Error Handling Strategy:** ### 4. Implementation Plan (Atomic Steps, TDD-ordered) -- [ ] **Step 1:** Prepare schema / table alterations (with rollback instructions) — files: [file list] — completed: +- [ ] **Step 1:** Prepare schema / table alterations with rollback instructions, or record `No schema changes; rollback is git revert.` — 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: - [ ] **Step 3 (implementation, green):** Implement core business logic / backend functions — only enough to make Step 2's tests pass — files: [file list] — completed: - [ ] **Step 4:** Update UI / output views (with tests first, where automatable) — files: [file list] — completed: