# Session Rules

This file records active working rules requested in this session.

## Decision Rules

- Keep JavaScript/TypeScript core files intact for upgrade safety whenever possible.
- Modularize at template/component level first.
- Keep main content as larger sections initially; split finer later.
- Use separate script includes (do not keep one monolithic script block).
- Use a staged rollout for AJAX navigation (pilot first, then expand by wave).

## File and Backup Rules

- For every touched existing file, create a fileNameOrig.ext backup.
- Keep change tracking docs up to date when implementation state changes.
- Maintain a manifest/inventory for modularization and AJAX rollout scope.

## Scope Rules

- Pilot AJAX routes are:
  - dist/indexOrig.html
  - dist/mailbox/inbox.html
  - dist/mailbox/read.html
  - dist/mailbox/compose.html
- Keep static/full-page navigation fallback available behind a feature flag.

## Testing Rules

- Validate lifecycle re-init and avoid duplicate listeners.
- Validate browser back/forward sync (URL/title/content/menu state).
- Validate accessibility focus and announcements after swaps.
- Validate error fallback and race handling before expanding waves.

## Documentation Rules

- Keep AJAX-NAVIGATION-PLAN.md and AJAX-PAGE-INVENTORY.md current.
- Record new decisions and constraints in this file as they are made.

## VS Code Trust and Approval Rules

Current observed state in this repo:

- Workspace-level VS Code settings are committed at .vscode/settings.json.
- Workspace-level extension recommendations are committed at .vscode/extensions.json.
- Workspace-level task file is committed at .vscode/tasks.json.
- No workspace-level launch file is currently committed under .vscode.
- No .code-workspace file is committed.
- Trust/approval behavior remains partly user-level (local VS Code profile/tooling mode), but workspace defaults now exist.

Session policy to use (non-default hardening):

- Keep this workspace trusted only for this project.
- Require approval before running terminal commands that modify files, install packages, or change git state.
- Allow read-only commands without extra prompts when possible.
- Block destructive commands unless explicitly requested and confirmed.
- Keep fallback to manual review checkpoints during AJAX rollout milestones.

Audit note:

- If we later add workspace-level VS Code settings, capture them in this file and back them up with fileNameOrig.ext before edits.

## Workspace Productivity Baseline

Applied in this session:

- Added workspace settings file: .vscode/settings.json
- Added workspace extension recommendations: .vscode/extensions.json
- Added workspace task runner file: .vscode/tasks.json

Purpose:

- Reduce noise and indexing overhead in large generated folders.
- Keep lint/format feedback fast and consistent.
- Improve navigation and source-control ergonomics during multi-file rollout work.

Operating guidance:

- Keep these settings minimal and repo-focused (avoid highly personal UI preferences).
- If a setting slows local workflow, adjust it in workspace settings and record the change here.

## Additional Productivity Suggestions

- Use VS Code Tasks for repeatable commands instead of manual terminal typing:
  - npm: lint
  - npm: build
  - npm: dev
  - npm: docs-serve
- Keep AJAX pilot changes behind a feature flag and add one dedicated smoke task once runtime code exists.
- Prefer small, frequent doc status updates after each implementation session (wave status + blockers).