Import WSC-MVC agent starter pack (SPEC, AGENTS, IMPLEMENTATION_PLAN, CLAUDE, README)

AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md — WSC-MVC Repository Instructions
+
+## Role and mission
+You are the principal developer and test engineer for a VBScript-only Windows Script Components MVC framework hosted by Classic ASP in IIS. Follow `SPEC.md` as the authoritative product/technical contract and `IMPLEMENTATION_PLAN.md` as the ordered execution queue. Ship small, working, verified vertical slices.
+
+## Precedence
+User instructions > `SPEC.md` accepted decisions > this file > implementation plan > local component notes. On contradictions, surface the conflict and avoid silently redefining the architecture. Do not modify the fixed decisions in SPEC without explicit user approval.
+
+## Mandatory start-of-task routine
+1. Read `SPEC.md`, `IMPLEMENTATION_PLAN.md`, `docs/DECISIONS.md` (if present), and affected source/tests.
+2. Inspect current repo state and last test evidence; do not overwrite user edits or change unrelated files.
+3. Identify current milestone and minimum coherent work needed for its next acceptance test.
+4. Check available host and tools. Windows/IIS tests unavailable on Linux/macOS: label NOT RUN and provide exact Windows commands.
+5. State assumptions only where necessary; prefer a small executable experiment over guessing about WSC/IIS semantics.
+
+## Hard architecture rules
+- Classic ASP/IIS HTTP host; one thin `Default.asp` bootstrap.
+- VBScript WSC files supply application components, registered as COM with stable ProgID/CLSID.
+- Separate HTML templates; no business logic in ASP or views.
+- Never use ASP host objects inside domain services or repositories.
+- No hidden controllers or method invocation from arbitrary URL strings; use explicit route allowlists.
+- No speculative auto-reflection, native inheritance, DI framework, ORM, or new runtime dependencies.
+- Request-created COM objects stay request scoped; never put WSC instances in ASP Session/Application.
+- Security-sensitive files and private templates must be inaccessible over HTTP.
+- Keep registration/deployment elevated and separate from request handling.
+
+## VBScript and WSC rules
+- `Option Explicit` for every VBScript compilation unit where supported; explicitly declare variables and check for naming collisions.
+- Public WSC XML declarations must exactly match script procedures, parameters, and casing conventions; validate behavior on the target host.
+- WSC public object is not the same thing as a VBScript `Class`; never paste a class into WSC expecting automatic exposure.
+- Use `Set` when assigning object references and when returning objects. Define whether an API returns scalar or object.
+- Test Null, Empty, Nothing, missing dictionary keys, array bounds, and default properties deliberately.
+- Use parentheses in VBScript calls according to syntax (`Call Foo(a)` versus `Foo a`); don't import VB.NET/VBA-only features.
+- No `On Error Resume Next` across an entire function; check `Err.Number` immediately, capture details, clear and restore normal handling.
+- Avoid broad reliance on `Execute`, `Eval`, and other dynamic code execution.
+- No implicit web or filesystem access from a service merely because a host object happens to be available.
+
+## Design and implementation workflow
+For each change: explain a small intended behavior -> write/extend a test -> implement -> execute available tests -> review security and cleanup -> update docs. Keep one milestone in flight at a time. Prefer the simplest viable component contracts over prematurely generic abstractions. Keep `Default.asp` small and free from business rules.
+
+## Registration and deployment
+- Each WSC class has unique, immutable CLSID and documented ProgID. Never reuse GUIDs or quietly rename registered interfaces.
+- Registration scripts must report elevated privilege requirements, filesystem path, and x86/x64 mode; use script-component registration commands only after verifying them on target Windows.
+- Unregistration must target only this project's identities and must not delete arbitrary registry trees or shared dependencies.
+- Check app-pool identity, IIS ASP feature, NTFS ACLs, direct source exposure, and bitness.
+- Any change that might affect running COM clients gets a rollback plan; do not claim live reload works unless tested.
+
+## Testing and evidence
+- Never claim passing tests from reasoning or XML parsing alone. Record PASS/FAIL/NOT RUN with exact commands, OS, IIS, app-pool bitness, and observed result.
+- Test both WSH component creation and IIS HTTP behavior where applicable.
+- For M1 verify `/hello` status/content-type/exact body; denied direct `.wsc` access; safe failure; reversible registration; basic concurrent requests.
+- Add regression tests before fixing discovered bugs. Flag concurrency and cross-request state risks.
+- Do not claim production readiness until the relevant security/performance phases and deployment tests pass.
+
+## Agent autonomy and self-improvement
+You MAY propose additions to `docs/DECISIONS.md`, `docs/LEARNINGS.md`, component-level notes, or new test cases whenever a verified lesson emerges. You MAY create a focused `skills/` note only for a repeatable workflow with tested commands and a concrete trigger. You MUST NOT silently loosen safety rules, alter fixed decisions, delete failing tests, expand scope to new runtimes, or rewrite AGENTS.md/CLAUDE.md to justify a shortcut. Propose substantive agent-rule changes as a diff and obtain user approval before applying them. Preserve a short change history and evidence for every accepted improvement.
+
+## End-of-task report
+Report: milestone, changed files, actual behavior, commands run and outcomes, remaining issues, next smallest task. If IIS or Windows is unavailable, mark host-dependent checks NOT RUN and supply copy-paste commands; don't mask the limitation.

CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md — Claude Code Instructions for WSC-MVC
+
+Read `AGENTS.md`, then `SPEC.md`, then `IMPLEMENTATION_PLAN.md` before changing code. AGENTS.md contains the shared operating rules for all coding agents; this file is a concise Claude-specific execution entry point, not a competing architecture.
+
+## Primary task
+Implement WSC-MVC milestone by milestone: IIS/Classic ASP host, registered VBScript WSC components, and separate HTML templates. Start with the `/hello` vertical slice. Do not start with scaffolding every speculative class.
+
+## Planning and context discipline
+- At the start of each session, determine current milestone from implementation plan and actual tests, not from filenames alone.
+- Inspect changed files and prior decisions; preserve user changes.
+- For a task crossing architectural boundaries, first write a brief plan referencing the exact SPEC acceptance criteria.
+- Use small edits and run the closest available test after each meaningful increment.
+- If tool access lacks Windows or IIS, implement only what can be responsibly checked and clearly report Windows integration as NOT RUN.
+- Do not turn guesses about WSC registration, COM marshaling, WSC XML semantics, IIS rewrite, or hot reload into established facts.
+
+## Code review checklist
+Confirm: VBScript `Option Explicit`; WSC `<public>` and script procedure agreement; stable COM identity; object/scalar assignment semantics; checked error paths; request-scoped state; safe response ownership; no URL-controlled arbitrary ProgID/method; no publicly accessible source/config/templates; tests updated; docs accurate.
+
+## Before concluding
+Summarize modified files, what actually ran, proof of acceptance or blocked tests, and the single next milestone. Never say 'done' for a host-dependent milestone without IIS evidence. Propose rule improvements with evidence; do not silently edit architectural guardrails.
+
+## Useful prompt to resume
+"Read AGENTS.md, SPEC.md, IMPLEMENTATION_PLAN.md, and docs/DECISIONS.md. Identify the first unmet acceptance criterion in the current milestone. Implement its smallest testable vertical slice, run all available tests, and report PASS/FAIL/NOT RUN with commands and evidence. Do not advance milestones until its gate passes."

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,54 @@
+# WSC-MVC — Agent Execution Plan
+
+Use this as an ordered queue. A checkbox is complete ONLY with actual test evidence in `docs/TEST-RESULTS.md`.
+
+## M0 — Environment and feasibility
+- [ ] Inventory Windows version, IIS/Classic ASP/URL Rewrite availability, app pool bitness/identity, WSC registration tool, permissions.
+- [ ] Run a minimal registered WSC hello-world test outside IIS. Confirm `.wsc` XML/registration syntax and COM creation.
+- [ ] Record tested registration/unregistration commands and path/bitness behavior.
+- [ ] Record unsupported assumptions and needed adaptations in `docs/DECISIONS.md`.
+Gate: a WSC can be registered, instantiated, called, unregistered, and re-registered on target Windows.
+
+## M1 — Vertical HTTP slice
+- [ ] Create thin `Default.asp`, `Application.wsc`, and `HomeController.wsc`.
+- [ ] Choose and test host-to-COM argument/response contract. If ASP intrinsic objects cannot be passed safely, implement minimal primitive adapter.
+- [ ] Add explicit rewrite/deny rules; verify static-file bypass.
+- [ ] Add registration/unregistration scripts and component/HTTP tests.
+- [ ] Verify `GET /hello` = 200, expected content-type and exact body.
+- [ ] Verify direct source access denied, broken component gives safe error, basic concurrency and clean re-registration.
+Gate: all M1 SPEC acceptance tests pass on IIS, or mark blocked with evidence; do not call the milestone done without host verification.
+
+## M2 — Lifecycle and errors
+- [ ] Define per-request context and response ownership.
+- [ ] Explicit creation/cleanup of objects; no shared request state.
+- [ ] Central unexpected/expected error handling; headers/body commitment tests.
+- [ ] Add correlation-safe diagnostics.
+Gate: repeated/concurrent requests and failure cases behave predictably.
+
+## M3 — Routing
+- [ ] Explicit route map with GET/POST, literal routes first.
+- [ ] Safe decoding/validation, 400/404/405, Allow header.
+- [ ] No arbitrary URL-to-ProgID or URL-to-method dispatch.
+Gate: route matrix and malformed URL tests pass.
+
+## M4 — Views
+- [ ] Safe separate template loading, text-context encoding, default-deny for private templates.
+- [ ] Template missing/escaping tests; add layout after renderer works.
+Gate: output is deterministic and untrusted text does not become HTML.
+
+## M5 — Data
+- [ ] ADODB contract and provider-specific integration test database.
+- [ ] Parameterized operations, transaction ownership, cleanup on error.
+Gate: real DB integration tests pass and input is not concatenated into SQL values.
+
+## M6 — Hardening
+- [ ] Authentication/authorization design and security regression tests.
+- [ ] Production logging and deployment rollback.
+- [ ] Concurrent load and performance baseline with stated host specs.
+Gate: documented security and performance results.
+
+## M7 — Developer experience
+- [ ] Component generator and interface-contract validator.
+- [ ] Reproducible clean-room deployment/test guide.
+- [ ] Review and propose evidenced AGENTS/CLAUDE improvements.
+Gate: another developer can reproduce setup and first request from docs.

README.md

@@ -0,0 +1,16 @@
+# WSC-MVC Agent Starter Pack
+
+This is a *planning and agent-control package*, not yet an executable framework.
+
+## Files
+- `SPEC.md` — authoritative product, architectural, security, milestone and acceptance specification.
+- `AGENTS.md` — shared instructions for coding agents.
+- `CLAUDE.md` — Claude Code entry point; defers to AGENTS.md.
+- `IMPLEMENTATION_PLAN.md` — gated execution checklist.
+
+## Start a coding agent
+Copy these files to the **root of the new WSC-MVC repository**, then issue:
+
+> Read AGENTS.md, SPEC.md, IMPLEMENTATION_PLAN.md. Execute M0 and then the smallest testable piece of M1. Record actual commands/results and do not claim IIS tests passed unless you ran them on Windows IIS.
+
+Choose the Windows/IIS machine as the execution host for M0/M1 wherever possible. A Linux-only agent can prepare text/config but cannot establish Windows COM/IIS behavior.

SPEC.md

@@ -0,0 +1,152 @@
+# WSC-MVC — Technical and Product Specification
+
+Version: 0.1 (development specification)  
+Status: Proposed; implementation behavior must be verified on the target Windows/IIS host.
+
+## 1. Mission
+Build a small, maintainable, WSC-first MVC framework for Classic ASP. IIS receives HTTP traffic; a single ASP bootstrap dispatches requests to VBScript Windows Script Components registered as COM objects. Application behavior lives in WSC files; presentation lives in separate HTML templates. Ship verified increments rather than an elaborate untested framework.
+
+## 2. Fixed decisions
+- Runtime: Windows, IIS, Classic ASP, VBScript; no ASP.NET, PHP, Node.js, or JScript runtime dependency.
+- Object architecture: registered `.wsc` COM components; stable ProgIDs and CLSIDs.
+- Presentation: separate `.html` templates, served only through the rendering layer when containing placeholders or private content.
+- Entry point: one `Default.asp`, plus IIS rewrite configuration and optional `Global.asa` only if justified.
+- IIS is a hard runtime requirement for HTTP integration; WSH-based component smoke tests are a separate concern.
+- Prefer built-in Windows/IIS capabilities and ADODB; no third-party framework required.
+- Business logic must not reference ASP Request, Response, Server, or Session.
+- All behavior dependent on WSC/COM/IIS quirks must be tested on Windows and documented; do not infer support from ordinary VBScript class behavior.
+
+## 3. Non-goals for v0.1
+No ORM, controller auto-discovery, automatic reflection, hot reload, plugin system, migrations, authentication, session-backed COM instances, application-scoped WSC instances, database-backed example, complex DI, or production-ready HTML parser. Do not implement these speculatively.
+
+## 4. Initial execution path
+`GET /hello` -> IIS URL Rewrite -> `/Default.asp` -> `Server.CreateObject("WscMvc.Application")` -> `Application.Run(...)` -> `WscMvc.HomeController` -> string/response contract -> HTTP 200, `text/html; charset=utf-8`, body `Hello from WSC-MVC!`.
+
+Prefer a bootstrap with `Option Explicit`, no business logic, no includes, no embedded HTML, and only request-host wiring. Define and verify a precise ownership rule for HTTP status, headers, and writing: do not write a partially successful response before dispatch can fail. Test whether COM calls can accept the proposed ASP built-in objects; if passing an object fails, use a tested host adapter or pass only primitive request data. Do not silently assume an ASP object is serializable or universally callable from WSC.
+
+## 5. Target project structure
+```
+WSC-MVC/
+  Default.asp
+  web.config
+  Framework/
+    Application.wsc
+    Router.wsc                 # phase 3
+    RequestContext.wsc         # phase 2; only after host interop proven
+    ResponseResult.wsc         # phase 2; optional if simpler contract works
+    ViewRenderer.wsc           # phase 4
+  Controllers/
+    HomeController.wsc
+  Views/
+    Home.html                  # phase 4
+    Layout.html                # phase 4
+  tests/
+    Test-Components.vbs
+    Test-Http.ps1
+  tools/
+    Register-Components.ps1
+    Unregister-Components.ps1
+  docs/
+    ARCHITECTURE.md
+    DECISIONS.md
+    TEST-RESULTS.md
+  SPEC.md
+  IMPLEMENTATION_PLAN.md
+  AGENTS.md
+  CLAUDE.md
+  README.md
+```
+The tree is a target, not an instruction to create placeholder classes before their phase.
+
+## 6. Component contract
+- Each `.wsc` represents one named, cohesive component. The `.wsc` XML `<registration>` establishes COM identity; `<public>` explicitly lists callable methods/properties; `<script language="VBScript">` contains implementation.
+- Do not assume a VBScript `Class ... End Class` placed inside a WSC becomes its exposed COM object. Use and validate the WSC script/public syntax on the target host.
+- Use PascalCase for file names and public members, `WscMvc.ComponentName` ProgIDs, and a unique, stable GUID per component (never recycle across unrelated components).
+- A component has a minimal documented public API. Unexposed functions remain internal. `Initialize(...)` is a framework convention, not an automatic WSC constructor.
+- Use explicit parameter and return contracts, including whether values are objects (`Set`) or scalars, and how missing/Null/Empty values are handled.
+- Use composition; do not invent inheritance, decorators, interfaces, or reflection that VBScript/WSC cannot provide.
+- Limit cross-component COM calls inside hot loops; keep interface calls coarse enough to measure.
+- Do not store ASP host objects or mutable request data in persistent scopes.
+
+## 7. HTTP and routing contract (phase 3)
+- Support GET and POST initially; distinguish unsupported methods with a deliberate HTTP status.
+- Normalize path consistently; preserve an explicit original path; match literal routes before parameterized routes.
+- URL-decode exactly once where appropriate; validate route values and reject ambiguous or malformed paths rather than guessing.
+- Static assets bypass the rewrite. WSC, config, source, tests, logs, and private templates must not be served publicly.
+- Return deliberate 404 for unmatched routes, 405 for disallowed methods (with Allow where possible), 400 for malformed requests, 500 for unexpected failures.
+- Don't use unvalidated request values as filesystem paths, ProgIDs, method names, SQL identifiers, or template names.
+- Do not implement arbitrary controller/method activation from a URL; use an explicit allowlisted route map.
+
+## 8. View contract (phase 4)
+- Templates live separately from code and are not directly browser-accessible if they contain private information or placeholders.
+- Default-encode data for HTML text; define separate, explicit handling for attributes, URLs, JS contexts, and raw HTML. Avoid unsafe universal substitution.
+- Never execute VBScript or arbitrary expression code supplied by a template. Prefer a minimal documented placeholder syntax.
+- Use a deliberate layout convention and report missing templates as server errors without exposing local filesystem paths.
+
+## 9. Database contract (later phase)
+- ADODB with provider-specific adapters only when needed; parameterized commands for values, never string-concatenate untrusted SQL data.
+- Parameterize with correct order/type/size for the provider; identifier selection must use an allowlist.
+- Connection, recordset, command, and transaction ownership must be explicit. Release objects and close resources on success and failure.
+- Services/repositories do not depend on ASP host objects. Transactions have a clear owner and rollback path.
+
+## 10. Security and operations
+- Default deny direct HTTP access to `.wsc`, `.vbs`, `.ps1`, `.md`, `.config` where appropriate, source/private directories, test output, logs, and templates. IIS configuration must be tested, including direct-extension and path variations.
+- Avoid printing debug stacks, COM registration details, connection strings, paths, secrets, or raw exception text to clients.
+- Record request correlation ID, route, elapsed time, outcome, and safe diagnostic information without sensitive payloads.
+- No broad filesystem write privileges. Register WSCs from an elevated, controlled deployment step; do not let a web request register COM classes.
+- Validate application pool identity, architecture (32/64-bit), DCOM/COM permissions where applicable, and IIS/ASP feature installation.
+- Do not cache COM objects in Session/Application. Favor short-lived request-owned instances and document threading implications.
+- Changes to COM registration must be idempotent, reversible, and explicit about privilege and architecture.
+- `web.config` is not a substitute for NTFS permissions or placing private source outside webroot; verify both where practical.
+
+## 11. Error-handling contract
+- Local `On Error Resume Next` only around an operation whose `Err.Number` is immediately checked and cleared; otherwise use `On Error GoTo 0`.
+- Handle errors at the nearest layer that can add useful context or recover. Central HTTP boundary emits a safe 500 response if headers/body are not committed.
+- Define a testable strategy for already-committed responses. Never pretend an exception can undo a sent body.
+- Distinguish an expected not-found/validation result from a programmer/COM failure.
+
+## 12. Definition of done for each component
+1. Contract and source file exist; XML is well-formed.
+2. Public declarations match implemented functions/procedures and documented names.
+3. ProgID/CLSID identities are recorded and stable.
+4. Registration/unregistration is tested on Windows at the required bitness.
+5. WSH smoke test instantiates it where applicable; IIS HTTP integration runs when host objects are required.
+6. Failure path and cleanup are tested; no unmanaged mutable shared request state.
+7. Security review covers direct HTTP exposure and untrusted input.
+8. README or architecture docs reflect actual implementation, not intentions.
+9. Tests are reported as PASS, FAIL, or NOT RUN with commands, host details, and evidence.
+
+## 13. Milestone sequence and gates
+M0: Inspect repository/environment; record OS/IIS/ASP/bitness/permissions and missing tools. No claim of execution on Linux/macOS. 
+M1: `Application.wsc` and `HomeController.wsc` register and instantiate; `/hello` returns expected 200/body; isolated WSH test where possible; registration is reversible.
+M2: Request/response context, central error mapping, per-request object lifetime; concurrent request smoke test.
+M3: Static route table, GET/POST method dispatch, 400/404/405 tests, safe URL handling.
+M4: Separate HTML templates and encoding tests; layout only after basic rendering passes.
+M5: ADODB connection lifecycle, parameterized queries, transactions, repository tests against an explicitly configured test DB.
+M6: Security, session/auth architecture, logging, deployment and concurrency hardening.
+M7: Scaffolding, repeatable tests, documentation, agent-guided quality improvements.
+Each milestone needs passing evidence before the next. Explicitly document any blocked milestone.
+
+## 14. Acceptance tests for M1
+- `cscript //nologo tests\Test-Components.vbs` reports successful creation and expected method result (if the component's public API is host-independent).
+- `powershell -File tests\Test-Http.ps1 -BaseUrl http://localhost:<port>` verifies status, content type, and exact body for `/hello`.
+- Direct requests to WSC files and private directories are denied.
+- Missing ProgID or broken registration produces a safe 500; no filesystem path or raw internal exception is exposed.
+- Unregistration removes the project registrations only and is reversible by re-registration.
+- Test at least two concurrent HTTP requests; no cross-request leakage.
+- No tests are described as passed without actual output.
+
+## 15. Open questions to resolve experimentally
+- Can the proposed WSC Application COM method receive ASP intrinsic objects across this specific IIS/COM boundary reliably? If not, use a small ASP-host adapter and primitive arguments.
+- What exact registration tool and script-component XML forms work on the deployment OS and the relevant 32/64-bit host?
+- What is the safe reload/deployment procedure for an updated WSC under load? Do not promise hot reload before measuring it.
+- Which response contract best preserves error handling before bytes are sent?
+Record experiments, chosen behavior, tradeoffs, and evidence in `docs/DECISIONS.md`.
+
+## 16. Reference reading
+- Microsoft, Windows Script Components in IIS: https://learn.microsoft.com/en-us/previous-versions/iis/6.0-sdk/ms524594(v=vs.90)
+- Microsoft, Server.CreateObject: https://learn.microsoft.com/en-us/previous-versions/iis/6.0-sdk/ms524786(v=vs.90)
+- Microsoft, Setting Scope of COM Objects: https://learn.microsoft.com/en-us/previous-versions/iis/6.0-sdk/ms525036(v=vs.90)
+- Microsoft, Selecting a Threading Model: https://learn.microsoft.com/en-us/previous-versions/iis/6.0-sdk/ms525101(v=vs.90)
+- Microsoft, Classic ASP in IIS: https://learn.microsoft.com/en-us/iis/application-frameworks/running-classic-asp-applications-on-iis-7-and-iis-8/scenario-build-a-classic-asp-website-on-iis
+Archived documentation may describe older IIS/OS versions; experimentally validate modern OS behavior.