Repository Working Rules

Scope and architecture

This repository implements one lightweight stdio bridge and one unified remote gateway for DingTalk OA and XFT approvals.
The supported customer architecture uses one gateway OAuth login for both approval sources. Do not reintroduce a local DWS dependency or a second user login without explicit product approval.
The gateway must derive identity from its verified OAuth token. Never accept caller-supplied userId, employee ID, owner ID, or equivalent identity selectors.
The gateway must not persist approval bodies, expense details, attachments, or upstream schemas; they remain real-time. The only exception is a user-explicit local submission draft stored on the Agent machine under the current OS user's private data directory. Local drafts must never be uploaded to the gateway or repository, and every resumed draft must be revalidated against the live template schema before submission.

Use Git for every source, documentation, test, deployment, and distribution change.
Keep main releasable. Develop non-trivial changes on short-lived branches named feat/<topic>, fix/<topic>, docs/<topic>, or chore/<topic>.
Prefer small, atomic commits using Conventional Commit subjects such as feat:, fix:, docs:, test:, refactor:, and chore:.
Do not rewrite published history, force-push, or delete remote branches/tags unless the user explicitly requests it.
Before commit, run npm test, relevant distribution checks, and git diff --check. Update docs when architecture, installation, tools, authentication, or deployment changes.
Releases should be tagged only from a tested main commit. Do not commit generated dist, release, test bundles, package archives, or npm caches.

Never commit .secrets, .runtime, .env, the root secret file, OAuth databases, tokens, cookies, credentials, approval data, or machine-specific absolute paths.
Before the first push and every release, inspect the staged file list and scan it for likely secrets.
Logs, tests, fixtures, and support references must not expose access tokens, AppSecret, AuthoritySecret, private approval IDs, internal user IDs, or raw upstream payloads.

All approval reads and writes in product tests must go through MCP tools; do not bypass MCP to claim end-to-end coverage.
Automated tests must use mocks unless the user explicitly authorizes a real approval write. Never run real reject or return actions implicitly.
Preserve the distinction between failed, succeeded, and outcome_uncertain; never automatically retry an uncertain write.
Keep opaque approval references user-bound, source-bound, expiring, and revalidated against live ownership before every write.

Use ./deploy/install.sh for gateway installation and updates and ./deploy/uninstall.sh for gateway removal. These are server-operator commands; keep both idempotent and preserve server secrets by default.
Customer installation and updates must use the signed native client installer. Do not reintroduce global npm installation, Node-version-specific MCP paths, prose-only installation, or direct mutation of host-private configuration.
Release manifests must be Ed25519 signed. Never commit, publish, or expose the release private key; release verification must fail closed on missing/invalid signatures or artifact hashes.
Customer installation must remain user-level, lightweight, and free of enterprise credentials. The distributed MCP command is dingtalk-approval-bridge pointing at the HTTPS gateway.
A complete test release must expose both DingTalk OA and XFT. Treat either source being disabled as a release error.