# 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.