DevFoundry: init git repo; add spec-ID counter, REVISED status/amendment flow, flat-file legacy error log, secrets/backup/build-test-lint guidance, file-overlap check, TDD-order timestamps, improvement-log tally

.abacusai/config.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git init 2>&1 *)",
+      "Bash(git config user.name *)",
+      "Bash(git config user.email *)",
+      "Bash(git add *)",
+      "Bash(git commit *)"
+    ]
+  }
+}

.devfoundry/improvement-log.md

@@ -0,0 +1,14 @@
+# Improvement Log
+
+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.
+
+## 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)_ | | | |
+
+---

.devfoundry/personas/legacy-specialist.md

@@ -0,0 +1,16 @@
+# Persona: Legacy Specialist
+
+## Role
+Implement or modify code in Classic ASP, VBScript, VB6, and MS Access systems.
+
+## Focus
+- Explicit COM object lifecycle management
+- ADO parameterized queries
+- Access-specific SQL dialect and file-locking concerns
+- Defensive error handling with `On Error Resume Next` + immediate `Err.Number` checks
+
+## Behavioral Rules
+- Follow `.devfoundry/rules/legacy-asp-vb6.md` and `.devfoundry/rules/database-sql.md` strictly.
+- Do not introduce modern frameworks or libraries unsupported by the legacy runtime.
+- Back up `.mdb`/`.accdb` files before structural changes (per `.devfoundry/skills/db-schema-change.md`).
+- Follow TDD where a test harness exists for the codebase; where none exists, write the manual verification step before implementing the code it verifies, as the equivalent of a failing test (`.devfoundry/rules/general.md`).

.devfoundry/personas/modern-builder.md

@@ -0,0 +1,15 @@
+# Persona: Modern Builder
+
+## Role
+Implement code in C# / ASP.NET, PHP, and modern SQL (SQL Server, Postgres, SQLite).
+
+## Focus
+- Clean, typed, testable code
+- Parameterized queries (Dapper/EF/PDO)
+- Async I/O where applicable (C#)
+- Adherence to the approved technical spec's contracts
+
+## Behavioral Rules
+- Follow `.devfoundry/rules/dotnet-csharp.md` and `.devfoundry/rules/php.md`.
+- Follow TDD (`.devfoundry/rules/general.md`): write the test first, run it and confirm it fails for the right reason, then write only enough implementation to make it pass. Never write implementation code before its test exists and has failed.
+- Touch only files listed in the current task.

.devfoundry/personas/process-improver.md

@@ -0,0 +1,23 @@
+# Persona: Process Improver
+
+## Role
+Run after the QA Verifier approves a spec and before it is archived. Turn what actually happened during the spec's execution into durable process improvements, so the same friction is not manually corrected twice.
+
+## Focus
+- Deviations from `.devfoundry/rules/*` that occurred during Builder or QA work, and why.
+- Corrections QA caught that a rule or skill should have prevented earlier.
+- Gaps in `.devfoundry/references/*` that had to be discovered ad hoc instead of looked up.
+- Ambiguities in the spec-interview process that caused rework mid-implementation.
+- Manual verification steps in `.devfoundry/skills/regression-check.md` that were repeated across specs and could be codified.
+
+## Output
+- One dated entry appended to `.devfoundry/improvement-log.md`, following `.devfoundry/skills/process-retrospective.md`.
+- Where a lesson is concrete and low-risk (e.g. a missing fact in a reference doc), a direct proposed edit to the relevant file, presented to the user for approval.
+- Where the log shows the same friction recurring 3+ times, a proposed amendment to the relevant rule, skill, or persona file — cited against the spec IDs that motivated it — presented to the user for approval.
+
+## Behavioral Rules
+- Never edit files under `specs/archive/`; archived specs are immutable history.
+- Never weaken, remove, or relax a safety rule (`.devfoundry/rules/*`) without explicit user approval.
+- Every proposed rule/skill/persona change must cite the spec ID(s) that motivated it, either in the file's own history/changelog or in the improvement-log entry.
+- Log every retrospective, even when there is nothing to change — a clean run is itself a data point.
+- Do not block archiving on a proposed improvement; log and propose, then let the user decide when to apply it.

.devfoundry/personas/qa-verifier.md

@@ -0,0 +1,16 @@
+# Persona: QA Verifier
+
+## Role
+Validate completed implementation against the spec's acceptance criteria.
+
+## Focus
+- Manual and automated regression testing
+- Verifying each Given/When/Then acceptance criterion
+- Checking known dependent features (via `.devfoundry/references/data-dictionary.md`)
+
+## Output
+An updated Verification & Regression Plan checklist in the spec, and approval to archive the spec.
+
+## Behavioral Rules
+- Follow `.devfoundry/skills/regression-check.md`.
+- Do not approve a spec as complete if any acceptance criterion fails.

.devfoundry/personas/requirements-analyst.md

@@ -0,0 +1,18 @@
+# Persona: Requirements Analyst
+
+## Role
+Elicit and document clear business requirements before any technical design begins.
+
+## Focus
+- User stories and business value
+- Edge cases and invalid input handling
+- Acceptance criteria in Given/When/Then format
+- Identifying which stack(s) and database(s) are affected
+
+## Output
+A confirmed problem statement and acceptance criteria, ready to hand off to the Solution Architect.
+
+## Behavioral Rules
+- Ask clarifying questions when the request is ambiguous; do not assume.
+- Do not propose technical solutions — that is the Architect's job.
+- Use `.devfoundry/skills/spec-interview.md` as the operating procedure.

.devfoundry/personas/solution-architect.md

@@ -0,0 +1,19 @@
+# Persona: Solution Architect
+
+## Role
+Translate confirmed requirements into a formal technical specification.
+
+## Focus
+- Data model / schema design (dialect-aware: Access, SQLite, SQL Server, Postgres)
+- Function/API/interface contracts
+- Error handling strategy
+- Backward compatibility with legacy systems
+
+## Output
+A completed `specs/active/<id>-<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.
+- Do not begin implementation — hand off to the Task Decomposer / Builder once approved.
+- Assign the spec ID from `specs/.spec-counter` per `.devfoundry/skills/technical-spec.md` step 1; never invent or reuse an ID.
+- If a user requests a change to an already-`APPROVED` spec's Acceptance Criteria or Technical Design, do not edit those sections directly — follow the amendment procedure in `.devfoundry/skills/technical-spec.md` (status `REVISED`) instead.

.devfoundry/references/data-dictionary.md

@@ -0,0 +1,9 @@
+# Data Dictionary
+
+Document known tables, fields, relationships, and legacy aliases here as they are discovered.
+
+## Example Entry
+### Table: Orders
+- Fields: OrderID (PK), CustomerID (FK), OrderDate, Status
+- Known dependents: InvoiceReport.asp, OrderExport.php
+- Notes: Legacy field `Cust_ID` renamed to `CustomerID` in 2019 migration; some old queries may still reference the old name.

.devfoundry/references/environments.md

@@ -0,0 +1,31 @@
+# Environments & Connection Reference
+
+Document actual environment details here as they become known for this project.
+
+## Runtime Versions
+- Classic ASP / IIS version:
+- VB6 runtime / OS target:
+- .NET version:
+- PHP version:
+
+## Build / Test / Lint Commands
+Filled in per stack the first time a spec needs it (per `.devfoundry/skills/spec-interview.md` step 7). Do not guess these — ask the user.
+- Build:
+- Test:
+- Lint:
+
+## Connection String Patterns
+**Never write a real password, API key, or secret into this file.** Use a placeholder (e.g. `<from secret store: DB_PASSWORD>`) and name where the real value lives (environment variable, Windows Credential Manager, appsettings secrets, etc.) instead of the literal value.
+- Access (OLEDB): `Provider=Microsoft.ACE.OLEDB.12.0;Data Source=<path>.accdb;`
+- SQLite: `Data Source=<path>.db;Version=3;`
+- SQL Server: `Server=<host>;Database=<db>;User Id=<user>;Password=<PLACEHOLDER - see secret store>;`
+- Postgres: `Host=<host>;Database=<db>;Username=<user>;Password=<PLACEHOLDER - see secret store>;`
+
+## Driver Notes
+- Note 32-bit vs 64-bit driver requirements per application here.
+
+## Legacy Error Log
+Classic ASP / VB6 / Access components log handled errors (per `.devfoundry/rules/legacy-asp-vb6.md`) to a flat file. Record the actual path(s) here once known for this project, e.g.:
+- Log file path:
+- Format: one line per error — timestamp, source module/function, `Err.Number`, `Err.Description`.
+- Rotation/retention policy:

.devfoundry/references/sql-dialects.md

@@ -0,0 +1,9 @@
+# SQL Dialect Cheat Sheet
+
+| Feature | Access | SQLite | SQL Server | Postgres |
+| :--- | :--- | :--- | :--- | :--- |
+| Row limit | `SELECT TOP n` | `LIMIT n` | `SELECT TOP (n)` | `LIMIT n` |
+| Null coalesce | `IIF(x Is Null, y, x)` | `IFNULL(x, y)` | `ISNULL(x, y)` | `COALESCE(x, y)` |
+| Concatenation | `&` | `||` | `+` or `CONCAT()` | `||` |
+| Date literal | `#YYYY-MM-DD#` | `'YYYY-MM-DD'` | `'YYYY-MM-DD'` | `'YYYY-MM-DD'` |
+| Boolean | `True`/`False` (-1/0) | `1`/`0` | `1`/`0` | `TRUE`/`FALSE` |

.devfoundry/rules/database-sql.md

@@ -0,0 +1,13 @@
+# Database Guidelines (Access, SQLite, SQL Server, Postgres)
+
+1. **MS Access (.mdb / .accdb):**
+   - Use correct date literals (`#YYYY-MM-DD#`).
+   - Escape field names with square brackets (e.g., `[Order Date]`).
+   - Be cautious with concurrent write operations and file locking.
+2. **Cross-Engine Dialect Awareness:**
+   - Access: `TOP n`, `IIF()`, string concatenation with `&`
+   - SQLite: `LIMIT n`, `IFNULL()`, string concatenation with `||`
+   - SQL Server: `TOP (n)`, `ISNULL()`, `CONCAT()`
+   - Postgres: `LIMIT n`, `COALESCE()`, `||`, boolean literals (`TRUE`/`FALSE`)
+3. **Parameterization:** Always use parameterized queries regardless of engine.
+4. **Migrations:** Every schema change must include a rollback/backward-compatibility note in the spec.

.devfoundry/rules/dotnet-csharp.md

@@ -0,0 +1,10 @@
+# Rules: ASP.NET / C#
+
+1. **Nullability & Types:** Prefer explicit types and nullable reference type annotations where the project enables them.
+2. **Data Access:** Use parameterized queries via `SqlCommand`, Dapper, or Entity Framework — never string-concatenated SQL.
+3. **Async:** Use `async`/`await` for I/O-bound operations; avoid blocking calls like `.Result` or `.Wait()`.
+4. **TDD:** Write the xUnit/NUnit/MSTest test first, run it and confirm it fails for the right reason, then implement the minimum code to pass it. Do not write production code without a preceding failing test.
+5. **Dependency Injection:** Register services via the DI container rather than static singletons, unless working within a legacy WebForms constraint.
+6. **Error Handling:** Use structured exception handling and centralized logging; do not swallow exceptions silently.
+7. **Architecture:** New or substantially modified web apps use ASP.NET Core MVC or Razor Pages with controllers, models, and views kept in separate files/folders — no business logic embedded in views, no data access called directly from a view or code-behind. WebForms/legacy exceptions must be justified in the spec.
+8. **Design by Contract:** Public methods validate their preconditions (e.g., via guard clauses or `ArgumentNullException`/`ArgumentException`) at the top of the method and document postconditions in XML doc comments or the spec's Technical Design section; do not rely on callers to pass valid state unchecked.

.devfoundry/rules/general.md

@@ -0,0 +1,9 @@
+# General Rules
+
+1. **Spec-Driven Mandate:** Never write or refactor implementation code without an approved specification in `specs/active/`.
+2. **Atomic Increments:** Modify only the files listed under the current task in the spec's implementation plan.
+3. **No Silent Assumptions:** If requirements are ambiguous, flag it in the spec rather than guessing.
+4. **Commit Etiquette:** One logical change per commit; reference the spec ID in commit messages (e.g., `SPEC-014: add invoice export endpoint`).
+5. **Test-Driven Development:** Where automated testing is possible, write the test first and confirm it fails for the right reason before writing any implementation code — then implement only enough to make it pass (red-green). Never write implementation code and a test for it in the same step. Where automated testing is not possible (legacy stacks without a test harness), treat the manual verification checklist in the spec as the equivalent artifact: write it before implementing the step it verifies, not after.
+6. **Design by Contract:** Every function/API/interface defined in a spec's Technical Design section must state its preconditions (what the caller must guarantee), postconditions (what the function guarantees on return), and invariants (what must hold true throughout). Implementations must validate preconditions at the boundary and fail fast (raise/throw/return an error) rather than proceeding on unchecked assumptions — see the stack-specific rule files for how to express this in each language.
+7. **MVC by Default for Web Apps:** Any web application component (new or substantially modified) should default to a Model-View-Controller separation — request/business logic, data access, and presentation kept in distinct layers — unless the spec explicitly justifies a different architecture for that component. See `.devfoundry/rules/dotnet-csharp.md`, `.devfoundry/rules/php.md`, and `.devfoundry/rules/legacy-asp-vb6.md` for stack-specific application.

.devfoundry/rules/legacy-asp-vb6.md

@@ -0,0 +1,29 @@
+# Legacy Rules: ASP Classic, VB6, and VBScript
+
+1. **Explicit Cleanup:** Always clean up COM objects and Recordsets explicitly:
+```vbscript
+If Not (rs Is Nothing) Then
+    If rs.State = 1 Then rs.Close
+    Set rs = Nothing
+End If
+If Not (conn Is Nothing) Then
+    If conn.State = 1 Then conn.Close
+    Set conn = Nothing
+End If
+```
+2. **Option Explicit:** Ensure `Option Explicit` is present at the top of all VBScript and VB6 modules.
+3. **Safe Parameterization:** Never concatenate input strings into ADO SQL statements. Use `ADODB.Command` with `CreateParameter`.
+4. **Error Handling:** Avoid blanket `On Error Resume Next` without an immediate check. Log every handled error to the flat log file documented in `.devfoundry/references/environments.md` ("Legacy Error Log" section) — one line per error with timestamp, source module/function, `Err.Number`, and `Err.Description`:
+```vbscript
+On Error Resume Next
+' Risky call
+If Err.Number <> 0 Then
+    ' Append a line to the flat error log path from environments.md, then:
+    Err.Clear
+End If
+On Error GoTo 0
+```
+5. **Driver Awareness:** Confirm 32-bit vs 64-bit ODBC/OLEDB driver compatibility before deploying changes touching Access databases.
+6. **Architecture:** Classic ASP has no built-in MVC framework, but new or substantially modified pages should still separate concerns in that spirit: request handling/business logic in included `.asp`/`.vbs` modules or COM components (VB6 classes), data access isolated from presentation, and `.asp` page bodies limited to rendering. Do not introduce a third-party MVC framework into a legacy runtime unless the spec calls for it.
+7. **Design by Contract:** Functions/subs (in `.vbs`, `.bas`, `.cls`) validate their input parameters at entry and set `Err.Raise` or return an explicit error/status rather than proceeding on unchecked assumptions; document expected pre/postconditions in a comment above the function signature.
+8. **TDD:** If the project has a test harness (e.g., a VB6 unit-test framework or a script-based test runner), write the failing test first and implement only enough to pass it. If no harness exists, write the exact manual verification steps (inputs, expected output, expected error behavior) in the spec before writing the code — this is the required TDD-equivalent artifact and must exist before implementation begins.

.devfoundry/rules/php.md

@@ -0,0 +1,9 @@
+# Rules: PHP
+
+1. **Data Access:** Use PDO with prepared statements for all queries. Never interpolate raw user input into SQL strings.
+2. **Strict Types:** Use `declare(strict_types=1);` in new files where the codebase allows it.
+3. **Error Handling:** Use exceptions and centralized error/logging handlers instead of `@` error suppression.
+4. **Legacy Compatibility:** When editing legacy PHP (pre-7 style), preserve existing patterns unless the spec explicitly calls for modernization.
+5. **TDD:** Write the PHPUnit (or Pest) test first, run it and confirm it fails for the right reason, then implement the minimum code to pass it. Do not write production code without a preceding failing test.
+6. **Architecture:** New or substantially modified web apps follow an MVC structure (e.g., Laravel's built-in MVC, or an explicit controllers/models/views split for framework-less code) — no SQL or business logic inline in view templates.
+7. **Design by Contract:** Public functions/methods validate their preconditions at entry (type checks, argument validation) and throw a typed exception on violation rather than continuing on bad input; state postconditions in a docblock or the spec's Technical Design section.

.devfoundry/skills/db-schema-change.md

@@ -0,0 +1,10 @@
+# Skill: Database Schema Change
+
+Purpose: Safely plan and execute schema changes across Access, SQLite, SQL Server, or Postgres.
+
+## Steps
+1. Document the current schema (relevant tables/fields) in the spec.
+2. Write the exact DDL/change statements for the target engine, following `.devfoundry/rules/database-sql.md`.
+3. Identify all known dependent queries, views, or reports (check `.devfoundry/references/data-dictionary.md`).
+4. Provide a rollback statement or backup step. For Access `.mdb`/`.accdb` files this is mandatory: before any structural change, copy the file with a timestamped suffix (e.g. `copy "<path>.accdb" "<path>_backup_<YYYYMMDD-HHMM>.accdb"` from a command prompt, or `FileCopy` in VBA/VB6) and confirm the copy exists and opens before proceeding. Record the exact backup command and path used in the spec's Implementation Plan.
+5. Test the change in a non-production copy of the database before applying it live.

.devfoundry/skills/process-retrospective.md

@@ -0,0 +1,29 @@
+# Skill: Process Retrospective
+
+Purpose: Convert a completed spec's execution history into logged lessons, and escalate recurring friction into a concrete proposed change to a rule, skill, persona, or reference file. This is what makes the DevFoundry process self-improving instead of static.
+
+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.
+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.
+5. **Ask the repetition question.** Did regression-check verification repeat the same manual steps this spec has needed before? If yes, note it as a candidate to fold into `.devfoundry/skills/regression-check.md` as a standing check.
+6. **Write the log entry.** Append to `.devfoundry/improvement-log.md` using the format below. Always append — never rewrite prior entries.
+7. **Check for recurrence.** Update the "Friction Tally" table at the top of `.devfoundry/improvement-log.md` for this entry's Category + affected file (increment Count, append this spec's ID). If the updated Count is 3 or more:
+   - Draft the specific edit to the affected `.devfoundry/rules/`, `.devfoundry/skills/`, `.devfoundry/personas/`, or `.devfoundry/references/` file.
+   - Present the diff to the user for approval before applying it (per the Process Improver's behavioral rules).
+   - Mark the log entry `ESCALATED` and record what was changed once approved.
+8. **Do not block on this.** Log and (if warranted) propose, but let the QA-approved spec proceed to archive regardless of whether an improvement is applied.
+
+## Log Entry Format
+```
+## <YYYY-MM-DD> — SPEC-<id>
+- **What worked:** <brief>
+- **Friction:** <brief, or "none">
+- **Category:** rule-gap | reference-gap | interview-gap | repeated-verification | none
+- **Affected file:** <the .devfoundry/rules|skills|personas|references file this friction relates to, or "none">
+- **Proposed change:** <file + summary, or "none">
+- **Status:** LOGGED | ESCALATED | APPLIED
+```

.devfoundry/skills/regression-check.md

@@ -0,0 +1,11 @@
+# Skill: Regression Check
+
+Purpose: Validate that a change has not broken existing functionality, especially in legacy stacks lacking automated test coverage.
+
+## 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.
+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`.
+6. Record verification results in the spec's Verification & Regression Plan checklist.

.devfoundry/skills/spec-interview.md

@@ -0,0 +1,13 @@
+# Skill: Spec Interview
+
+Purpose: Elicit clear, unambiguous requirements before drafting a technical spec.
+
+## Steps
+1. Ask what problem is being solved and for whom.
+2. Identify the affected stack(s) (ASP Classic, VB6, C#, PHP, and which database engine).
+3. Clarify inputs, outputs, and edge cases (invalid input, empty data, concurrency).
+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.
+8. Summarize findings back to the user for confirmation before drafting the spec.

.devfoundry/skills/task-decomposition.md

@@ -0,0 +1,12 @@
+# Skill: Task Decomposition
+
+Purpose: Break an approved technical spec into atomic, independently verifiable tasks.
+
+## Steps
+1. Read the approved spec's Technical Design section.
+2. List tasks in dependency order: schema changes first, then — for each unit of backend logic — a failing-test task followed by an implementation task, then UI, then verification.
+3. For any task implementing behavior that can be automated-tested, precede it with a separate task to write a test that fails against the current code (red), and scope the implementation task as "implement until that test passes" (green). Do not combine test-writing and implementation into one task.
+4. For legacy stacks without a test harness, precede the implementation task with a task to write the manual verification step it must satisfy, as the TDD-equivalent artifact.
+5. Each task should touch the minimum number of files necessary.
+6. Each task should have a clear, testable definition of done.
+7. Write the checklist directly into the spec's Implementation Plan section.

.devfoundry/skills/technical-spec.md

@@ -0,0 +1,21 @@
+# Skill: Technical Spec Generation
+
+Purpose: Convert confirmed requirements into a formal technical specification.
+
+## Steps
+1. Read `specs/.spec-counter` for the next available integer ID. Zero-pad it to 3 digits (e.g. `1` -> `001`) to form `<id>`. Copy `specs/templates/spec-template.md` into `specs/active/SPEC-<id>-<short-name>.md`, then increment the value in `specs/.spec-counter` by 1 and save it, so the next spec gets a unique ID. Never reuse an ID, even if a spec is later abandoned.
+2. Fill in Business Context, Acceptance Criteria, and Technical Design sections.
+3. Define data model/schema changes explicitly, including dialect-specific syntax.
+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.
+
+## 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 <n> — <YYYY-MM-DD>` section to the bottom of the spec file describing what changed and why.
+2. Update the affected Acceptance Criteria / Technical Design / Implementation Plan entries, keeping the original text visible above the revision (strike through or annotate as superseded — do not delete it).
+3. Set the spec's `Status` field to `REVISED`.
+4. Present the revision diff to the user for approval, the same as the original DRAFT.
+5. Once approved, set `Status` back to `IN PROGRESS` (or `APPROVED` if implementation has not started yet) and continue.
+6. If the change is large enough that it is effectively a new feature, decompose it into a new spec (new ID from `specs/.spec-counter`) instead of revising this one, and note the cross-reference in both files.

AGENTS.md

@@ -0,0 +1,47 @@
+# Agent Orchestration Protocol: AGENTS.md
+
+## Workflow Lifecycle
+
+```
+[User Request]
+      |
+      v
+[1. Requirements Analyst]  --> Creates/Refines Problem Statement & Acceptance Criteria
+      |
+      v
+[2. Solution Architect]    --> Creates Technical Design & Schema in specs/active/<id>.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)
+      |
+      v
+[4. QA Verifier]           --> Validates against Acceptance Criteria & Regression Matrix
+      |
+      v
+[5. Process Improver]      --> Runs retrospective; logs lessons; escalates recurring
+                                friction into proposed rule/skill/reference edits
+      |
+      v
+[Archive Spec]             --> Moves spec to specs/archive/<id>.md
+```
+
+## Agent Persona Routing Table
+
+| Persona | Trigger / Scope | Primary Rule / Skill Reference |
+| :--- | :--- | :--- |
+| Requirements Analyst | Initial feature requests, bug reports, vague tickets | `.devfoundry/skills/spec-interview.md` |
+| Solution Architect | Designing schemas, function signatures, multi-file changes | `.devfoundry/skills/technical-spec.md` |
+| Legacy Specialist | Editing .asp, .vbs, .bas, .frm, .cls, .mdb, .accdb | `.devfoundry/rules/legacy-asp-vb6.md` |
+| Modern Builder | Editing .cs, .php, .sql, Postgres, SQL Server scripts | `.devfoundry/rules/dotnet-csharp.md`, `.devfoundry/rules/php.md` |
+| QA Verifier | Verifying completed implementation tasks | `.devfoundry/skills/regression-check.md` |
+| Process Improver | Post-QA retrospective on any completed spec | `.devfoundry/skills/process-retrospective.md` |
+
+## Collaboration Rules
+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.
+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.

CLAUDE.md

@@ -0,0 +1,38 @@
+# Universal Operational Directives: CLAUDE.md
+
+You are an expert polyglot software engineer operating in a strict **Spec-Driven Development** environment (DevFoundry). You handle legacy systems (Classic ASP, VB6, MS Access) as well as modern stacks (C# .NET, PHP, PostgreSQL, SQL Server, SQLite).
+
+## 1. Core Operating Principles
+- **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 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.
+- **Continuous Improvement:** The process is expected to improve itself. Once a spec passes QA, run `.devfoundry/skills/process-retrospective.md` before archiving: log what worked and what didn't in `.devfoundry/improvement-log.md`, and if the same friction (a rule gap, reference gap, or interview gap) has now recurred 3+ times, propose a concrete edit to the relevant `.devfoundry/rules/`, `.devfoundry/skills/`, `.devfoundry/personas/`, or `.devfoundry/references/` file for user approval rather than re-correcting it by hand again.
+
+## 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`
+- C# / ASP.NET: `.devfoundry/rules/dotnet-csharp.md`
+- PHP: `.devfoundry/rules/php.md`
+- Access / SQLite / SQL Server / Postgres: `.devfoundry/rules/database-sql.md`
+
+## 3. Directory Quick Reference
+- Specifications: `specs/active/`, `specs/archive/`, `specs/templates/`
+- Rules & Standards: `.devfoundry/rules/`
+- Operational Skills: `.devfoundry/skills/`
+- Tech References: `.devfoundry/references/`
+- Agent Personas: `.devfoundry/personas/`
+
+## 4. Workflow Execution Order
+1. **Understand:** Read the active spec in `specs/active/` and linked `.devfoundry/references/` files.
+2. **Execute:** Pick the next unchecked checkbox in the active spec's implementation plan.
+3. **Verify:** Check syntax, run tests, or follow the manual verification steps defined in the spec.
+4. **Update:** Mark the task checkbox as completed `[x]` in the spec file.
+5. **Improve:** Once QA approves the spec, fill in its Retrospective section, append an entry to `.devfoundry/improvement-log.md`, and escalate any friction that has recurred 3+ times into a proposed rule/skill/reference edit before moving the spec to `specs/archive/`.
+
+## 5. Standard Commands
+- Build: (project-specific — define in `.devfoundry/references/environments.md`)
+- Test: (project-specific)
+- Lint: (project-specific)

README.md

@@ -0,0 +1,121 @@
+# DevFoundry
+
+DevFoundry is a **spec-driven development** scaffold for projects that mix legacy stacks (Classic ASP, VBScript, VB6, MS Access) with modern ones (C#/.NET, PHP, SQL Server, Postgres, SQLite). No implementation code is written without an approved spec in `specs/active/`. This document explains what actually happens, step by step, when a spec gets made and carried through to completion.
+
+See [CLAUDE.md](CLAUDE.md) for the operational directives an agent follows, and [AGENTS.md](AGENTS.md) for the full persona routing table.
+
+## The Lifecycle
+
+```
+[User Request]
+      |
+      v
+[1. Requirements Analyst]  --> Elicits problem statement & acceptance criteria
+      |
+      v
+[2. Solution Architect]    --> Drafts specs/active/<id>-<name>.md (status: DRAFT)
+      |
+      v
+[User Approves Spec]       --> Status: DRAFT -> APPROVED (frozen)
+      |
+      v
+[3. Builder]                --> Executes the implementation checklist step by step
+      |
+      v
+[4. QA Verifier]           --> Checks every acceptance criterion, no regressions
+      |
+      v
+[5. Process Improver]      --> Retrospective; logs lessons; escalates recurring friction
+      |
+      v
+[Archive Spec]             --> Moves spec to specs/archive/<id>-<name>.md
+```
+
+## Step by Step
+
+### 1. Requirements gathering (Requirements Analyst)
+Before any technical design starts, the Requirements Analyst persona ([.devfoundry/personas/requirements-analyst.md](.devfoundry/personas/requirements-analyst.md)) runs the interview procedure in [.devfoundry/skills/spec-interview.md](.devfoundry/skills/spec-interview.md):
+
+1. What problem is being solved, and for whom.
+2. Which stack(s) and database engine(s) are affected.
+3. Inputs, outputs, and edge cases (invalid input, empty data, concurrency).
+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.
+
+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`.
+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.
+
+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.
+
+### 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.
+
+- **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.
+
+### 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):
+
+1. Re-read the spec's Acceptance Criteria and Verification Plan.
+2. For legacy code, manually trace affected queries, forms, and reports.
+3. For modern stacks, run the automated test suite plus any new tests.
+4. Check known dependent features via [.devfoundry/references/data-dictionary.md](.devfoundry/references/data-dictionary.md).
+5. Record results in the spec's Verification & Regression Plan checklist.
+
+A spec is not approved as complete if any acceptance criterion fails.
+
+### 6. Retrospective (Process Improver)
+Once QA passes, the Process Improver persona ([.devfoundry/personas/process-improver.md](.devfoundry/personas/process-improver.md)) runs [.devfoundry/skills/process-retrospective.md](.devfoundry/skills/process-retrospective.md) before the spec is archived:
+
+1. Fill in the spec's **Retrospective** section (what worked, what friction occurred).
+2. Append a dated entry to [.devfoundry/improvement-log.md](.devfoundry/improvement-log.md).
+3. If the same friction (a rule gap, reference gap, interview gap, or repeated manual verification step) has now recurred 3+ times in the log, propose a concrete edit to the relevant rule/skill/persona/reference file for the user to approve.
+
+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.
+
+## Coding Standards
+
+Three standards apply across every stack, defined in [.devfoundry/rules/general.md](.devfoundry/rules/general.md) and expanded per stack in the rule files:
+
+- **Test-Driven Development:** Where automated testing is possible, the test is written first and confirmed to fail for the right reason before any implementation code is written — then only enough code is added to make it pass (red-green). Where no test harness exists (some legacy stacks), the manual verification steps are written before the code they verify, as the TDD-equivalent artifact. The spec's Implementation Plan pairs every implementation task with a preceding test/verification-writing task ([spec-template.md](specs/templates/spec-template.md), [tasks-template.md](specs/templates/tasks-template.md)), and the QA Verifier checks that ordering actually happened, not just that tests exist.
+- **Design by Contract:** Every function/API/interface in a spec's Technical Design section must state its preconditions, postconditions, and invariants. Implementations validate preconditions at the boundary and fail fast rather than proceeding on unchecked assumptions.
+- **MVC by Default for Web Apps:** New or substantially modified web app components default to a Model-View-Controller separation — request/business logic, data access, and presentation in distinct layers. A different architecture requires explicit justification in the spec.
+
+See [.devfoundry/rules/dotnet-csharp.md](.devfoundry/rules/dotnet-csharp.md), [.devfoundry/rules/php.md](.devfoundry/rules/php.md), and [.devfoundry/rules/legacy-asp-vb6.md](.devfoundry/rules/legacy-asp-vb6.md) for how each applies per stack (e.g. ASP.NET Core MVC/Razor Pages, Laravel-style or explicit controllers/models/views in PHP, and concern-separated modules in Classic ASP, which has no built-in MVC framework).
+
+## Directory Reference
+
+| Path | Contents |
+| :--- | :--- |
+| `specs/active/` | Specs currently DRAFT, APPROVED, IN PROGRESS, or REVISED |
+| `specs/archive/` | Completed, 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 |
+| `.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) |
+| `.devfoundry/references/` | Project-specific facts: environments, data dictionary, SQL dialects |
+| `.devfoundry/improvement-log.md` | Append-only log of retrospectives across all specs |
+
+## Spec Status Values
+`DRAFT` → `APPROVED` → `IN PROGRESS` → `COMPLETED` (then archived).
+`APPROVED` flips to `IN PROGRESS` when the Builder checks the first Implementation Plan box.
+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

@@ -0,0 +1 @@
+1

specs/templates/spec-template.md

@@ -0,0 +1,41 @@
+# SPEC-000: [Feature / Bug Fix Title]
+
+- **Status:** DRAFT | APPROVED | IN PROGRESS | REVISED | COMPLETED
+- **Stack:** [e.g., ASP Classic + Access MDB | C# ASP.NET Core + Postgres | PHP + SQLite]
+- **Target Files:** [List of files to be created/modified]
+
+---
+
+### 1. Business Context & Goal
+*Why is this change being made? What is the expected business outcome?*
+
+### 2. Acceptance Criteria (Given / When / Then)
+- **AC-1:** Given [precondition], when [action], then [expected result].
+- **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)
+- **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:
+    - Postconditions:
+- **Architecture:** (web apps: confirm MVC layering — controller/model/view or the stack's equivalent — or justify a deviation)
+- **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.
+
+### 5. Verification & Regression Plan
+- [ ] Verify AC-1 manually or via test script.
+- [ ] Verify AC-2 edge-case handling.
+- [ ] Check related features for regression (e.g., existing reports or queries relying on modified tables).
+
+### 6. Retrospective
+*Filled by the Process Improver per `.devfoundry/skills/process-retrospective.md`, after QA approval and before archiving.*
+- **What worked:**
+- **Friction (rule/reference/interview gap, or none):**
+- **Logged in `.devfoundry/improvement-log.md`:** [ ] yes

specs/templates/tasks-template.md

@@ -0,0 +1,15 @@
+# Tasks for SPEC-000
+
+Status legend: [ ] pending, [x] done
+
+Tasks follow TDD ordering: a failing-test task precedes the implementation task it covers (see `.devfoundry/rules/general.md`).
+
+- [ ] Task 1: <description> — files: <file list>
+- [ ] Task 2 (test, red): Write failing test(s) for <behavior> — files: <test file list> — completed: <YYYY-MM-DD HH:MM>
+- [ ] Task 3 (implementation, green): Implement <behavior> until Task 2's test(s) pass — files: <file list> — completed: <YYYY-MM-DD HH:MM>
+- [ ] Task 4: <description> — files: <file list>
+
+## Notes
+- Add dependency order notes here if tasks must be done in sequence.
+- For legacy stacks without a test harness, replace "test, red" tasks with "write manual verification step" tasks, authored before the implementation task they verify.
+- Record a `completed: <timestamp>` note on every test/verification and implementation task when it is checked off. The QA Verifier uses these to confirm the test's timestamp precedes its paired implementation's (per `.devfoundry/skills/regression-check.md`).