wsc-mvc/AGENTS.md

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: define the contract first, including preconditions, postconditions, invariants, return/object ownership, and expected failure behavior; write or extend the closest failing test; implement the smallest production change; 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.

Use TDD for new behavior and bug fixes. When practical, observe the test fail for the intended reason before implementation, then rerun it after the fix. If Windows/IIS access is unavailable for a host-dependent contract, mark that check NOT RUN and provide exact commands rather than treating review or parsing as a pass.

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.
• Include contract tests for public APIs and trust boundaries: valid input, representative invalid input, Null/Empty/Nothing handling, object/scalar return semantics, and error paths.
• 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.