DevFoundry/specs/archive/SPEC-002-asp-classic-framework-adoption.md

SPEC-002: Adopt RouteKit Classic ASP Framework + Concurrency/QA Follow-ups

• Status: COMPLETED
• Stack: DevFoundry process documentation (legacy ASP rules/personas/references)
• Target Files: .devfoundry/references/asp-classic-framework.md, .devfoundry/rules/legacy-asp-vb6.md, .devfoundry/rules/database-sql.md, .devfoundry/personas/legacy-specialist.md, .devfoundry/references/environments.md, .devfoundry/skills/regression-check.md, AGENTS.md

---

1. Business Context & Goal

A three-lens review of the process scaffold flagged three open gaps: (1) vague Access file-locking guidance for a multi-session web app, (2) no canonical ASP Classic framework reference, (3) QA Verifier had no explicit instruction to actually execute test commands versus trust checklist prose. The user clarified: the app is a web app with multiple ASP sessions writing Access concurrently; the user has an existing ASP Classic framework (RouteKit, cloned from https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework.git) that should be the standard for all ASP Classic apps; and agreed with the proposed “harness exists -> run it for real, else documented manual trace” QA rule.

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

2. Acceptance Criteria (Given / When / Then)

• AC-1: Given a spec touches Access with multiple concurrent ASP sessions, when the Legacy Specialist or Modern Builder reads database-sql.md, then it finds concrete request-scoped-connection, transaction, retry-on-lock-conflict, and maintenance-window guidance instead of a vague warning.
• AC-2: Given a new ASP Classic web app or feature is planned, when the Legacy Specialist reads legacy-asp-vb6.md and legacy-specialist.md, then both point to a new .devfoundry/references/asp-classic-framework.md describing the RouteKit framework's directory layout, generator workflow, DAL, error handling, and test harness.
• AC-3: Given the QA Verifier runs regression-check.md, when a real test harness exists for the affected stack, then it must actually execute it and record real output; when none exists, a documented manual trace is the only accepted substitute.
• AC-4: Given AGENTS.md's “No Hallucinated Libraries” rule, when RouteKit is used in an ASP Classic app, then it is explicitly exempted as the sanctioned framework rather than flagged as an unapproved dependency.

3. Technical Design & Contracts

• Data Model / Schema Changes: None.
• Functions / APIs / Interfaces: None.
• Architecture: Documentation-only. New reference file summarizes the already-existing RouteKit framework (read directly from its cloned repo) — directory layout, DAL()/DatabaseConnection() request-scoped connection pattern, Migrator_Class migration workflow, ErrorHandler_Class flat-file logging via EnableErrorLogging/ErrorLogPath, and the aspunit harness under tests/.
• Error Handling Strategy: No change to runtime behavior; documents the framework's existing ErrorHandler_Class behavior accurately against the source files read.

4. Implementation Plan (Atomic Steps, TDD-ordered)

• Step 1 (verification authoring): Write this spec's acceptance criteria before editing docs — files: specs/active/SPEC-002-asp-classic-framework-adoption.md — completed: 2026-08-20 02:10
• Step 2 (research): Clone and read the RouteKit framework repo (core/, app/, db/, tests/, README.md, TESTING.md, docs/development-guide.md) to ground the reference file in real code, not invented conventions — files: (external repo, read-only) — completed: 2026-08-20 02:15
• Step 3 (implementation): Add .devfoundry/references/asp-classic-framework.md — files: .devfoundry/references/asp-classic-framework.md — completed: 2026-08-20 02:20
• Step 4 (implementation): Update legacy rules/persona to reference the framework and RouteKit-specific error logging — files: .devfoundry/rules/legacy-asp-vb6.md, .devfoundry/personas/legacy-specialist.md, AGENTS.md — completed: 2026-08-20 02:22
• Step 5 (implementation): Add concrete Access multi-session concurrency rule — files: .devfoundry/rules/database-sql.md — completed: 2026-08-20 02:23
• Step 6 (implementation): Align environments.md fields with RouteKit's actual web.config keys — files: .devfoundry/references/environments.md — completed: 2026-08-20 02:24
• Step 7 (implementation): Update QA regression-check to require real execution when a harness exists, documented trace otherwise — files: .devfoundry/skills/regression-check.md — completed: 2026-08-20 02:25
• Step 8 (verification): Re-read all edited files end-to-end to confirm cross-references resolve and no contradictory guidance remains — files: listed target files — completed: 2026-08-20 02:27

5. Verification & Regression Plan

• Verify AC-1 by confirming database-sql.md contains request-scoped-connection, transaction, retry, and maintenance-window bullets (manual trace — no test harness for this documentation-only change).
• Verify AC-2 by confirming legacy-asp-vb6.md rule 6/8 and legacy-specialist.md reference asp-classic-framework.md (manual trace).
• Verify AC-3 by confirming regression-check.md steps 3–4 state the harness-exists/no-harness branching explicitly (manual trace).
• Verify AC-4 by confirming AGENTS.md rule 1 names the RouteKit exception (manual trace).
• No automated test harness applies to this documentation-only spec; verification was a manual trace per .devfoundry/skills/regression-check.md step 4.

6. Retrospective

Filled by the Process Improver per .devfoundry/skills/process-retrospective.md, after QA approval and before archiving.

• What worked: Cloning and reading the actual framework repo before writing the reference avoided inventing conventions; the user's three short clarifying answers (multi-session Access, framework repo URL, agreement on QA rule) were each directly actionable.
• Friction (rule/reference/interview gap, or none): none — the existing amendment/spec-interview machinery from SPEC-001 handled this cleanly.
• Logged in .devfoundry/improvement-log.md: yes