Six follow-ups from the round8-12 hotfix retrospective: - web-ci.yml: lint + Go/frontend tests on every push and PR (nothing ran app checks before; the round10 dev-mode regression shipped green) - tests/known-failures.json + check-test-baseline.mjs: gate by exact failing-test id instead of hand-counted failure totals (14 frontend, 70 Go upstream debts recorded from the dev tip) - devboot.test.mjs: boots the real Vite dev server and pins the movi loader contract that broke round10 (query-less DEV url, /vendor stays off the module pipeline) - scripts/local/smoke-workbench.mjs: pre-release smoke covering the seven recurring acceptance points (login/pool/claim/play-while-loading/ captions/4x/playhead), 3x green against the local replica - docs/CODING_STANDARDS.md + AGENTS pointer: eligibility flags are server-shipped, the UI renders them (rounds 9+12 lesson) - vendor README host-element quirks section, HANDOFF gate pointers and movi-path verification rule, perf-audit report pinned with the post-round12 production 500 observation - husky pre-commit: lint-staged (repo prettier scope) + tsc + gofmt - gofmt: restore lint:go green on the dev tip (drift shipped silently in the perf merge and round12 because nothing gated it)
7.5 KiB
Project Instructions
Working Root
- This repository directory is the single working root; the sibling
~/Desktop/fanyufolder is legacy and will be retired. - Cluster kubeconfig (
fanyu.conf), BOS credential CSV, downloaded captures, and the local workspace mount are being migrated under this repo's untracked local data path (seedocs/HANDOFF.md§ 0 for the live layout).
Engineering Principles
These principles guide implementation choices. Specific business contracts and this document's release, authorization, and data safety rules take precedence.
-
Check contracts and implementation first. Follow the Domain docs reading rules to review relevant business documentation, ADRs, code, and tests. Distinguish current behavior, approved designs that are not yet implemented, and superseded rules. Identify specific conflicts between the current request and existing agreements; ask the user when a conflict affects business outcomes and cannot be resolved independently.
-
Define the compatibility scope before making changes. For APIs, Mongo records, workflow definitions, operator inputs and outputs, delivery formats, or task states, check callers, existing data, and in-flight tasks. Before removing an old path, establish that compatibility is no longer needed or migration is complete, and explain the rollback impact. Preserve migration and recovery paths that still serve a purpose. Internal implementations may be refactored directly when contracts remain unchanged.
-
Choose the simplest solution that meets current requirements and known constraints. Abstractions, configuration, and indirection must serve a concrete purpose. Authentication, permission isolation, data consistency, and necessary retries and recovery are part of the requirements. For temporary solutions, state their scope, limitations, and replacement conditions; avoid shortcuts known to fall short of confirmed requirements.
-
Implement incrementally through verifiable business flows. For changes spanning multiple layers, first connect the smallest complete flow required by the current request, then extend its capabilities. Validate replacement paths before removing existing implementations. A minimal version determines implementation order; the final delivery must still meet all acceptance criteria for the current request.
-
Follow existing responsibility boundaries. Locate the relevant components, API wrappers, business logic, storage, and execution entry points, and place changes in the module responsible for that behavior. Enforce permissions and business constraints on the server; use frontend validation for interaction feedback. Keep shared rules consistent and update generated files from their authoritative sources.
-
Reuse before adding dependencies. Before writing a new implementation or adding a dependency, inspect existing project code, standard libraries, and the documentation, types, and available capabilities for installed dependency versions. When existing capabilities are insufficient, choose well-maintained libraries that reduce overall complexity, and explain their purpose and adoption costs.
-
Consult established approaches where useful. For unfamiliar, consequential, or hard-to-reverse design choices, consult official sources or relevant approaches in mature products, and explain the conditions under which they apply. Follow existing project patterns for routine changes; adapt external approaches to this project's business contracts.
-
Complete delivery with verification evidence. Run the checks required for the scope of the change and verify relevant behavior in the local replica environment. For changes involving asynchronous processing, persistence, or compatibility, cover the relevant failure, restart recovery, and legacy data scenarios. Compare existing failures against the baseline by specific test case and cause, rather than failure counts alone. Update the corresponding contracts when behavior changes, and clearly report what passed, failed, or remains unverified.
Deployment Environment
- The
devbranch uses Fanyu. LeaveDEPLOY_ENVunset or set it tofanyu; the loader rejects other targets, includingpocandwjzh. - POC-like branches resolve to
pocand require that target. Feature branches outside these routing rules may select a target explicitly withDEPLOY_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, run
git remote -v. - After making code or documentation changes for the user, stage only the files changed for that task.
- Commit with an English, emoji-prefixed commit message.
- Push only when the user explicitly says push. Default action after commit: stay local.
- When push is approved, push the user's personal feature branch only; never push
devorpocdirectly. - Do not stage or commit unrelated user changes already present in the working tree.
Release Workflow
- For release preparation, deployment, rollback, or resuming release work, read
docs/release/README.mdfirst and runpython3 scripts/release.py status <release-id>when a record exists. Follow the recorded state and evidence; a successful rollout alone is not business acceptance. - Fanyu image releases use
scripts/release.py. 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.
- Read secrets from untracked local files or environment variables; see
scripts/local/for the established pattern.
Release Approval and Customer Data Safety
- Creating or submitting a pull request requires the user's explicit approval for that specific action; local review and commits may remain unsubmitted.
- Deploying to any company cluster requires the user's explicit approval immediately before the deployment; verification work must stop when that approval is absent.
- 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.
Local Environment
- Local replica stack (Vite 5173, Go API 3001, snapshot Mongo 27018) is the default verification surface before any PR.
- Verification commands and known pitfalls (upstream test debt, session auth flag, workspace mount) are documented in
docs/HANDOFF.md. - 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.