# Repository Working Agreement

## Authorization gate

- For a newly requested change, first inspect requirements and produce a plan.
- Do not modify files, publish artifacts, trigger Jenkins, or change external state until the user explicitly says `开始实施`.
- Once implementation is authorized, keep work inside the frozen scope. A material scope expansion requires a new confirmation.

## Product goal

- A host that installs the Xuqm update SDK must be able to enable plugin architecture, create plugins, build, publish, update, and roll back with minimal configuration and the smallest practical amount of application code.
- Tooling must be generic and must not depend on YiwangxinApp4 paths, aliases, global variables, or private runtime bridges.

## Architecture constraints

- Shared behavior must have one canonical implementation across common/update/xwebview/bugcollect.
- Plugin runtime state, bundle manifests, compatibility checks, atomic activation, crash-safe rollback, and embedded recovery belong to the SDK/tooling rather than each host app.
- CLI operations must support interactive local use and deterministic non-interactive CI use.
- Do not integrate or expand `@xuqm/rn-push` for the current scope.
- Public API changes must update package exports, native files where applicable, tests, examples, CLI help, README, and docs together.

## Delivery constraints

- Published npm packages must include every declared native file, CLI script, config template, and type required by documented usage.
- Snapshot/alpha publication precedes host integration.
- All XuqmGroup artifact publication and deployment must run through `https://jenkins.xuqinmin.com/`; do not publish npm packages, Maven artifacts, or services directly from a developer machine.
- Jenkins typecheck/tests/builds are hard gates; do not swallow failures.
- Before handoff, run formatting, lint, typecheck, tests, package-content verification, CLI fixture tests, Android builds, bundle/update/rollback integration, and documentation checks.
- Keep `docs/IMPLEMENTATION_HANDOFF.md` synchronized while work is in progress so another agent can resume from the current verified state without reconstructing context from chat history.