DevFoundry/specs/archive/SPEC-004-routekit-bootstrap.md

SPEC-004: Bootstrap RouteKit Classic ASP Framework into This Repo

• Status: COMPLETED
• Stack: ASP Classic + RouteKit MVC framework + MS Access (.accdb)
• Target Files: public/ (Default.asp, web.config), core/* (vendored framework internals, read-only per rule), app/ (controllers/, views/, models/, repositories/, autoload files), db/webdata.accdb, db/migrations/, scripts/*.vbs (generators), tests/ (aspunit harness, bootstrap.asp, test-manifest.asp), applicationhost.config, run_site.cmd, TESTING.md, logs/, .devfoundry/references/environments.md

---

0. Spec Creation Checklist

• Status is DRAFT before user approval.
• Target Files are listed and checked for overlap with other active specs — specs/active/ was empty; no conflict.
• Build/test/lint commands are documented in .devfoundry/references/environments.md.
• 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 and completed: timestamp space.

1. Business Context & Goal

Every ASP Classic rule and reference in this repo (.devfoundry/rules/legacy-asp-vb6.md rules 6 and 8, .devfoundry/references/asp-classic-framework.md) assumes a RouteKit Classic ASP application already exists under public/, core/, app/, db/, tests/. None of those directories existed in this repo before this spec — DevFoundry was pure process scaffold with no application code. This spec vendors the framework in and confirms its baseline (migrations, error logging, aspunit harness) actually works. This is the first non-meta spec DevFoundry has completed — SPEC-001–003 were all documentation-only.

No other active specs existed, so there were no target-file conflicts.

Blocking questions resolved during drafting (research performed instead of guessing, per .devfoundry/skills/spec-interview.md step 7):

1. Framework source access: Confirmed reachable — cloned https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework.git at commit e15cf7bf56a44f72471d07503ae16c481e6fed3f (“Refactor project into generic starter template”).
2. Runtime target: The framework ships its own self-contained dev runtime — IIS Express driven by run_site.cmd + applicationhost.config — rather than requiring a full Windows Server IIS install. Confirmed IIS Express is installed on this machine (C:\Program Files\IIS Express\iisexpress.exe, both x86 and x64), and Microsoft.ACE.OLEDB.12.0 plus 64-bit Access ODBC drivers are registered.
3. Environment values: Set real, working local-dev values directly (see Step 4 below) rather than leaving placeholders.
4. Test execution command: Determined from TESTING.md and confirmed by actually running it (see Step 6): the aspunit runner UI is JS-driven (ASPUnitRunner.asp fetches each manifest page client-side as <page>?task=test); for non-interactive/agent verification, hitting each manifest page directly with ?task=test returns raw JSON results.

Deviation from the source repo found during vendoring: despite the source commit's message claiming removal of “domain-specific controllers, models, repositories, and views,” the checkout still contained one leftover domain-specific migration (db/migrations/20260324110000_add_do_not_call_fields_to_households.asp, referencing Households/HouseholderNames tables) and two scripts from an unrelated prior project (scripts/migrate_isbusiness_to_households.vbs, scripts/deploy-iis-git.ps1, the latter hardcoded to a project named “asp-territory”). Queried db/webdata.accdb directly via ADODB.Connection.OpenSchema before vendoring — it only contains schema_migrations and users tables, confirming the domain-specific migration was never actually applied to this copy. All three leftover files were excluded from vendoring rather than silently included.

2. Acceptance Criteria (Given / When / Then)

• AC-1: Given the framework source repo, when its core/, public/, db/, scripts/, tests/ directories are vendored into this repo root, then the layout matches .devfoundry/references/asp-classic-framework.md exactly. — PASS
• AC-2: Given the framework is vendored, when public/web.config <appSettings> is configured, then ConnectionString, Environment, EnableErrorLogging, and ErrorLogPath hold real working values (no secret committed in plaintext) matching .devfoundry/references/environments.md. — PASS
• AC-3: Given the tests/ aspunit harness is wired up as its own IIS application per TESTING.md, when it is run, then the framework's own baseline test suite passes with zero application code added yet. — PASS
• AC-4: Given the baseline migration state, when cscript scripts\runMigrations.vbs status then up is run against db/webdata.accdb, then the schema_migrations table exists and no pending migrations remain. — PASS
• AC-5: Given the bootstrap is complete, when .devfoundry/references/environments.md is reviewed, then Runtime Versions and Build/Test/Lint Commands are filled in with real confirmed values, not blanks. — PASS

3. Technical Design & Contracts

• Data Model / Schema Changes: No new application schema. db/webdata.accdb was vendored as-is (contains schema_migrations and users tables only — verified via ADODB.Connection.OpenSchema before any migration ran). No pending migrations were run beyond the framework's own pre-applied baseline. Rollback: delete the vendored public/, core/, app/, db/, scripts/, tests/, applicationhost.config, run_site.cmd, TESTING.md, logs/ directories/files — this reverts the repo to its pre-SPEC-004 scaffold-only state (no destructive change was made to any pre-existing DevFoundry file's content, only .devfoundry/references/environments.md was edited in place).
• Functions / APIs / Interfaces: None new — this spec vendors existing framework code, it does not add application logic. Design by Contract does not apply to unmodified vendored core/ files.
• Architecture: MVC via RouteKit itself (controllers/models/views as documented in asp-classic-framework.md), satisfying the MVC-by-default rule trivially since no custom architecture decision was made here.
• Error Handling Strategy: ErrorHandler_Class as already documented in asp-classic-framework.md. EnableErrorLogging was turned on (true) with a real ErrorLogPath so future feature specs have working error logging from day one; no handled error has occurred yet, so the log file itself has not been created (flagged for the next spec that exercises an error path, not treated as a blocker here).

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

• Step 1 (verification authoring): Confirmed the framework source is reachable and recorded the exact commit vendored — files: this spec — completed: 2026-08-19 22:50
• Step 2 (test, red): Confirmed baseline: no public/, core/, tests/ existed in this repo prior to vendoring (find returned nothing) — files: specs/active/SPEC-004-routekit-bootstrap.md — completed: 2026-08-19 22:51
• Step 3 (implementation): Vendored core/, public/, app/, db/, scripts/, tests/, applicationhost.config, run_site.cmd, TESTING.md into this repo root, excluding the three leftover domain-specific files described above — files: as listed in Target Files — completed: 2026-08-19 22:55
• Step 4 (implementation): Configured public/web.config (ConnectionString pointed at the vendored db/webdata.accdb, EnableErrorLogging=true, ErrorLogPath set), created logs/, added a second IIS Express site (Tests Web Site, port 8085) to applicationhost.config, set tests/web.config's ProductionAppBaseUrl to the real production port, and mirrored all real values into .devfoundry/references/environments.md — files: public/web.config, applicationhost.config, tests/web.config, .devfoundry/references/environments.md — completed: 2026-08-19 22:58
• Step 5 (implementation, green): Ran cscript scripts/runMigrations.vbs status — output: “Applied migrations: 1 ... Pending migrations: 0” — confirmed schema_migrations/users tables exist and nothing is pending — files: db/webdata.accdb — completed: 2026-08-19 22:59
• Step 6 (verification): Started both IIS Express sites (discovered and fixed a real bug: iisexpress /config: without /site: only auto-starts the first <site>, so run_site.cmd was corrected to launch one process per site with ASPC_STARTER_ROOT set). Fetched http://localhost:8080/ and got a real rendered HomeController page. Ran all 8 registered aspunit test pages directly via <page>?task=test (since the browser runner is JS-driven and not curl-observable) and recorded real JSON output for each — files: tests/, run_site.cmd — completed: 2026-08-19 23:00

5. Verification & Regression Plan

• Verify AC-1: vendored tree (core/, public/, app/, db/, scripts/, tests/) matches asp-classic-framework.md's documented layout — confirmed via find listing during vendoring.
• Verify AC-2: public/web.config appSettings confirmed non-placeholder (ConnectionString points at the real vendored .accdb path, EnableErrorLogging=true, real ErrorLogPath); no secret committed (Access connection string has no password field for this provider).
• Verify AC-3 (real harness executed, real output recorded per .devfoundry/skills/regression-check.md step 3 — no manual-trace substitute used): all 8 manifest pages returned "passed":true" with 26/26 tests passing, 0 failures:
  • unit/TestHelpers.asp — 6/6 pass
  • unit/TestControllerRegistry.asp — 5/5 pass
  • component/TestHomeController.asp — 2/2 pass
  • integration/TestMvcDispatch.asp — 2/2 pass
  • integration/TestRoutes.asp — 3/3 pass
  • integration/TestConfigSettings.asp — 3/3 pass
  • integration/TestRenderedOutput.asp — 2/2 pass (hit the real running production site at http://localhost:8080/ and /404, got real 200/404 responses with real rendered markup)
  • integration/TestSharedLayout.asp — 3/3 pass
• Verify AC-4: runMigrations.vbs status output showed Pending migrations: 0.
• Verify AC-5: re-read .devfoundry/references/environments.md — Runtime Versions and Build/Test/Lint Commands sections now contain real confirmed values, no blanks remain in those sections.
• Regression check: no pre-existing DevFoundry process file's content was broken; .devfoundry/references/environments.md was extended, not replaced.

6. Retrospective

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

• What worked: Actually cloning the source repo (rather than trusting asp-classic-framework.md's prose alone) surfaced two real, otherwise-invisible problems before they became runtime bugs: leftover domain-specific artifacts misdescribed as a “generic starter,” and an IIS Express multi-site startup behavior that silently drops the second site. Querying the .accdb's actual schema via ADODB before running any migration avoided assuming the “generic” claim was accurate. Running the real aspunit suite directly against each manifest page's ?task=test endpoint (bypassing the JS-driven browser runner, which curl can't execute) gave real, parseable, per-suite pass/fail output instead of a checklist claim.
• Friction (rule/reference/interview gap, or none): reference-gap — .devfoundry/references/asp-classic-framework.md (written in SPEC-002) describes the framework's structure accurately but doesn't mention that: (a) the source repo can carry leftover non-generic artifacts that must be checked against the actual .accdb schema before trusting a “generic” claim, or (b) IIS Express requires one process per site with explicit /site: even when serverAutoStart="true" is set on all sites. Both are now documented directly in environments.md and run_site.cmd's own comments rather than only in this spec, so a future spec doesn't have to rediscover them.
• Logged in .devfoundry/improvement-log.md: yes