droboticflow/AGENTS.md
Codex 0040988fe9
Some checks are pending
web-ci / checks (push) Waiting to run
web-ci / pool-search-mongo (push) Waiting to run
🧭 Enforce dev mainline and release identity
2026-11-10 01:35:25 -08:00

92 lines
10 KiB
Markdown

# Project Instructions
## Working Root
- The repository root is `/Users/d-robotics/Desktop/fanyu/droboticflow`. The unified development checkout is `local-data/worktrees/recent-integration` on `dev`. The main checkout and existing unmerged worktrees retain protected work; do not reset, switch or discard them as part of routine development.
- Cluster kubeconfig (`fanyu.conf`), BOS credential CSV, downloaded captures, and the local workspace mount live under this repo's untracked `local-data/` directory; `~/Desktop/fanyu` still holds legacy copies (`fanyu.conf`, `泛宇-aksk.csv`) and is being retired (see `docs/HANDOFF.md` § 0).
- Before reading code to explain production behavior or starting changes, run `bash scripts/local/branch-freshness.sh` (read-only). If it reports the checkout is behind `origin/dev`, missing a live build commit, or only locally compared without remote/live confirmation, tell the user and work in a worktree that contains the live commit instead of a stale checkout.
## Engineering Principles
These principles guide implementation choices. Specific business contracts and this document's release, authorization, and data safety rules take precedence.
1. Check contracts and implementation first. Read `CONTEXT.md`, relevant ADRs, business docs, code, and tests (`docs/agents/domain.md`). Distinguish current behavior, approved unimplemented designs, and superseded rules. Use the controlled Chinese terms from `CONTEXT.md` in customer-facing copy, specs, issues, and domain discussions; ask the user when a request conflicts with existing agreements and affects business outcomes.
2. Define the compatibility scope before making changes. For APIs, Mongo records, workflow definitions, operator inputs/outputs, delivery formats, or task states, check callers, existing data, and in-flight tasks. Preserve active migration and recovery paths; before removing an old path, verify migration completion and explain rollback impact. Internal implementations may be refactored directly when contracts remain unchanged.
3. Keep solutions simple, incremental, and verifiable. Abstractions and indirection must serve a concrete requirement; authentication, permission isolation, data consistency, retries, and recovery are part of requirements. For multi-layer changes, connect the smallest complete flow first and validate replacement paths before removing old ones. State the scope, limitations, and replacement conditions of any temporary solution.
4. Follow responsibility boundaries and reuse existing capabilities. Place changes in the module responsible for that behavior. Enforce permissions and business constraints on the server; use frontend validation for interaction feedback and keep generated files updated from authoritative sources. Inspect existing code, standard libraries, and installed dependencies before adding new ones, and consult primary sources for unfamiliar or hard-to-reverse choices.
5. Complete delivery with verification evidence. Run the scoped checks (`docs/agents/verification.md`) and verify relevant behavior in the appropriate local environment. Cover failure, restart recovery, and legacy data scenarios for async, persistence, or compatibility changes. Compare existing failures against the baseline by specific test case and cause (`npm run test:frontend:gate` / `npm run test:go:gate`), update contracts when behavior changes, and clearly report what passed, failed, or remains unverified.
## Deployment Environment
- The `dev` branch uses Fanyu. Leave `DEPLOY_ENV` unset or set it to `fanyu`; the loader rejects other targets, including `poc` and `wjzh`.
- POC-like branches resolve to `poc` and require that target. Feature branches outside these routing rules may select a target explicitly with `DEPLOY_ENV`.
- Supply Fanyu secrets and environment-specific settings through the loader's existing local override files; the tracked preset contains only non-secret defaults.
- Verify the target cluster and namespace before every release, including when the environment is inferred from the branch.
## Git Workflow
- Before assuming a remote target, inspect the remote URL with credentials redacted (`git remote -v | sed -E 's#//[^@/[[:space:]]+@#//<redacted>@#g'`). Never print raw credential-bearing `.git/config` URLs into logs or reports; prefer migrating Git credentials to the system Keychain.
- After making code or documentation changes for the user, stage only the files changed for that task. Do not stage or commit unrelated user changes already present in the working tree.
- Commit with an English, emoji-prefixed commit message.
- `dev` is the single integration and release mainline. Reuse the unified `dev` checkout for normal authorized work. Create a branch or worktree only when the user explicitly requests it; record its purpose and merge-back plan first. Read-only diagnosis creates neither.
- Existing unmerged branches and uncommitted work remain untouched until the user requests their integration or disposal. Completed branches are cleaned only after their commits are in `origin/dev`, their work is preserved, and no service uses the worktree. Follow `docs/agents/branch-workflow.md` for synchronization and cleanup.
- Push and PR each require explicit user authorization. An explicit request to synchronize remote `dev` authorizes that bounded fast-forward push; it does not authorize a deployment or unrelated pending changes. Never force-push or rewrite `dev` history. Otherwise commit locally and report the state.
- When a task ends, run `python3 scripts/agent_status.py --no-fetch` (or with fetch if network/remote checks are needed) and report the branch's local state to the user.
## Release Workflow
- For release preparation, deployment, rollback, or resuming release work, read `docs/release/README.md` first and run `python3 scripts/release.py status <release-id>` when a record exists. Follow the recorded state and evidence; a successful rollout alone is not business acceptance.
- Every new release must use exactly the synchronized local `dev` and remote `origin/dev` tip at release time. Integrate and verify fixes on `dev` before preparing a release; unmerged-branch releases have no exception. `scripts/release.py` checks both refs during prepare and refreshes `origin/dev` again before deployment. Existing release records and unchanged components retain their historical identities; later development may advance `dev` beyond the deployed version.
- Fanyu image releases use `scripts/release.py` (`scripts/deploy-k8s.sh` blocks Fanyu). Configuration changes or migrations outside its supported scope require a separately reviewed plan and the corresponding user authorization.
## Credentials
- Never hardcode credentials (BOS AK/SK, Mongo, Gitea token, cluster kubeconfig) in any tracked file, and never echo raw credentials from untracked files (`.git/config`, `local-data/*`) into conversation output, `.scratch/` notes, or test logs.
- Read secrets from untracked local files, environment variables, or the system Keychain; see `scripts/local/` for the established pattern.
## Release Approval and Customer Data Safety
- Pushing branches, creating/submitting a pull request, and deploying to any company cluster require explicit user approval (either individually or via an explicit combined instruction such as "push and open PR"); approving one action never implicitly authorizes another. Local review and commits remain unsubmitted until approved.
- Cluster verification is read-only against customer data: use isolated synthetic fixtures or existing records without mutation, and never delete, overwrite, or add customer data. If a test requires a write or destructive operation, stop and obtain explicit approval for that exact operation.
## Development verification
- Before choosing checks for a change, read `docs/agents/verification.md`. Start with `npm run verify:plan -- --base <task-base>`; use quick checks while editing and affected task checks once before delivery. Expand only for changed dependencies, failures or uncovered risk.
- Reuse unchanged evidence within a task using the recorded source, dependency, configuration and environment identities. Report skipped, timed-out and unmapped coverage as pending; quick checks never replace release evidence.
- Keep local implementation and verification moving within the authorized scope. The existing push, PR, production-data and deployment approval rules still apply.
## Local Environment
- Local Mongo environments serve distinct purposes (`docs/HANDOFF.md` § 0, `docs/local-dev-guide.zh-CN.md` § 0):
- **Snapshot Mongo (`127.0.0.1:27018`, `env-local-snapshot.sh`)**: realistic replica of production data structure for workbench/API verification before a PR. Keep shared snapshot task claim states clean before running Go baseline gates (`npm run test:go:gate`).
- **Empty/isolated Mongo (`127.0.0.1:27017`, `env-local.sh`, or per-test isolated databases on 27018)**: synthetic fixtures, unit/integration tests, and clean-slate workflow CRUD debugging.
- Verification commands and known pitfalls (upstream test debt, session auth flag, workspace mount) are documented in `docs/HANDOFF.md`.
- Comparing test failures against the known-failure baseline ALWAYS goes through `npm run test:frontend:gate` / `npm run test:go:gate` (they diff against `tests/known-failures.json`; only NEW failures fail). Never hand-diff failure lists with stash/scratch files. Quick edits check changed-file formatting; the full formatting gate remains `npm run format:check` at integration/release scope.
- The company cluster and BOS bucket are read-only by default; any write requires explicit user approval.
## Agent skills
### Issue tracker
Issues and specs use local Markdown under `.scratch/`. Before reading or publishing tickets, read `docs/agents/issue-tracker.md`.
### Triage labels
Use the five default triage roles. Before triaging issues, read `docs/agents/triage-labels.md`.
### Domain docs
Use a single-context layout: root `CONTEXT.md` and `docs/adr/`. Before exploring domain concepts or decisions, read `docs/agents/domain.md`.
### Coding standards
Before writing or reviewing pool/list eligibility logic (claim buttons, `canClaim`, task-pool gating), read `docs/CODING_STANDARDS.md` — eligibility flags are server-shipped; the UI renders them, it never rebuilds them.
### UI copy and presentation
Before adding or changing any customer-facing page, component, or copy, read `docs/ui/copy-guidelines.md`. Its minimal-copy rules and applicable visual checks are required acceptance criteria for implementation and review, including bug fixes and generated UI. Apply them to new work as well as existing pages.