Saxonite/AGENTS.md

Repository Guidelines

Project Structure

Workspace/Saxonite.sln contains the Saxonite applications, libraries, and tests. Assets and other repository-level materials are outside Workspace. The solution consumes projects from the sibling ../../Common-VS/Workspace; preserve this relative layout and read Common's repository guidance when changing shared dependencies or APIs. The parent workspace map at ../../AGENTS.md is informational; repository instructions and trackers govern this repository.

Build and Validation

Run commands from Workspace:

dotnet restore Saxonite.sln
dotnet build Saxonite.sln --configuration Debug
dotnet test Saxonite.sln --configuration Debug

For Common API, framework, package, or shared-behavior changes, validate Common first, then Saxonite. Coordinate framework upgrades across the dependency boundary. Report any unavailable platform, database, or machine configuration separately from source failures.

Coding and File Conventions

Follow the existing C# style and this repository's .gitattributes. Follow shared file-editing guidance at ../../Common-VS/Workspace/docs/instructions/file-editing-conventions.md. Do not edit generated files or build output under bin, obj, or TestResults. Keep machine-specific configuration and credentials out of source control.

Conversation Tracking

Read docs/README.md, docs/topics.md, and docs/component-reviews.md before repository review or follow-up work. Update the trackers when work is identified, started, completed, or a component is reviewed. Use ISO YYYY-MM-DD dates and repository-relative links.

Branches and Pull Requests

• Use short-lived feature branches targeting master. Do not create or maintain a shared develop branch. Push feature branches and use pull requests; do not push directly to master, force-push, or rewrite its history.
• Before creating a pull request, prepare a concise proposed title and description and ask the user to confirm both. The description starts with a 2–3 sentence summary, followed by short bullets for significant files, file groups, or folders. Omit minor cleanup and cosmetic changes.
• For functional pull requests, propose incrementing Saxonite's application patch version and obtain the user's confirmation before applying it. The application version is the first three components of Sax.Version in Workspace/SaxoniteStandardBase/Base/App/Sax-Version.cs; synchronize that value and add the release entry to Workspace/SaxoniteStandardBase/Resources/Data/Application/VersionHistory.json. Prefix the confirmed title with vX.Y.Z and end the description with Application version: X.Y.Z. Documentation/process-only pull requests do not need a version prefix and use — as the tracker version.
• Do not merge a pull request unless the user asks. After merge, remove its local feature branch; remove the remote branch if the hosting service has not already done so.
• Before completing or merging a pull request, move its active topic to Completed Topics and record the PR number, confirmed application version (or —), and the actual date the work became ready for PR completion. Show the proposed tracker change and wait for review before committing it. After approval, commit and push the tracker update separately, verify it is present, and only then proceed with PR completion.
• Do not require branch protection checks until CI is available and the relevant check has been verified.

Security Changes

For encryption changes, follow Common's ../../Common-VS/Workspace/.agents/skills/common-security-change/SKILL.md and ../../Common-VS/Workspace/docs/authenticated-encryption-migration.md. Preserve fail-closed behavior, purpose separation, expiry checks, and the documented clean-break compatibility consequences.

Change Discipline

Check Git status before editing and preserve unrelated work. Treat Common and Saxonite as independent repositories. Do not change Common as part of a Saxonite task unless the user explicitly requests it.