From c7c912d87cd00f10c18e244882cb901286184b48 Mon Sep 17 00:00:00 2001 From: Bottybotsterson Date: Sat, 19 Sep 2026 08:26:47 -0400 Subject: [PATCH] Import WSC-MVC agent starter pack (SPEC, AGENTS, IMPLEMENTATION_PLAN, CLAUDE, README) --- AGENTS.md | 59 ++++++++++++++++ CLAUDE.md | 23 +++++++ IMPLEMENTATION_PLAN.md | 54 +++++++++++++++ README.md | 16 +++++ SPEC.md | 152 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 304 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 README.md create mode 100644 SPEC.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..34a9919 --- /dev/null +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9d209d9 --- /dev/null +++ b/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 `` 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." diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..df0aabc --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3585f91 --- /dev/null +++ b/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. diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..7e1daf1 --- /dev/null +++ b/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 `` establishes COM identity; `` explicitly lists callable methods/properties; `