# 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.
- Approval bodies, expense details, attachments, and upstream schemas must remain real-time and must not be persisted.

## Git workflow

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

## Secrets and privacy

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

## Testing and safety

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

## Deployment and distribution

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