Collaboration rules

English is authoritative; Chinese reference . Follow the owner’s latest explicit task scope.

Authorization and worktrees

Work only within the owner-authorized scope. The Fieldnotes portfolio, independent log site, tests and CI/CD configuration are authorized. The owner also authorized their local integration and commit on main, subject to the commit checkpoint. Remote publication needs separate authorization.
Ask about unclear requirements, conflicts, or owner decisions; stop dependent work. Silence is not approval.
The owner requested one local documentation-only initial commit on main, subject to the commit checkpoint below. Do not push it.
Every later PR/change, including docs, starts from current main in a dedicated sibling ../<feature-name> worktree and its own branch. Keep the canonical main/ worktree for integration/inspection.
No direct main pushes. Merge through a PR after required checks pass; deploy automatically after merge once implemented. CI/CD is configured in source; remote enforcement and production activation remain pending.

Review selection and quality

Before writing requirements or implementation for each new feature/independent change, ask which of the requirements, plan, execution, and acceptance reviews to run. An explicit selection already given for that task is sufficient; record it once. Do not infer a default or carry a waiver into another task.
Follow requirements → plan → execution → acceptance. Run only the independent sub-agent review gates selected by the owner, before advancing past those gates. Record omitted gates as owner-waived, never as passed. Read-only discovery may precede the selection.
Every selected review must check correctness and use first principles to challenge complexity: what requirement makes each part necessary, what simpler approach would suffice, what existing mechanism can be reused, and whether maintenance cost is justified. Check test value, document value, and privacy as relevant.
Resolve blockers and verify the fix within the selected review before advancing, unless the owner explicitly changes that gate. Reviewers must be independent of the author. A review pass does not authorize unrequested work or a commit.

Dependencies and tool versions

When introducing or upgrading direct dependencies and build/deployment tools, verify the latest stable release against the official registry or release page. Exclude alpha, beta, RC and canary releases. Record selected versions, verification date and source links in the change log. Ask the owner if compatibility requires an older version; do not silently downgrade.
Pin exact versions for all direct dependencies, including development/optional packages, and tools such as Node.js, pnpm, Hugo, Go and Wrangler when used. Do not use version ranges (^, ~, *, inequalities) or floating labels such as latest. Pin Git dependencies and CI Actions to full commit SHAs corresponding to the selected stable release, with its release version noted.
Commit generated lockfiles to fix transitive resolutions; do not force every transitive dependency to the newest release independently of its parent’s constraints. Save pnpm dependencies exactly and use pnpm install --frozen-lockfile in CI. Keep versions fixed between explicit upgrade PRs.
Current pins and the owner-approved TypeScript compatibility exception are recorded in change 0003. Re-verify official releases for each future dependency upgrade.

Documentation and public data

Website UI/content, README, persistent development documents, and PR logs are English-primary with Simplified Chinese references. Temporary local acceptance handbooks are Chinese-only as specified below. Commit messages are English only.
Keep one index.md / index.zh.md pair per change under logs/changes/<id>/, with selected reviews beside the relevant stages. Keep pre-merge iterations in that record; give later PRs linked records and attach real PR metadata when available.
Log effective requirements, material technical choices and rejected alternatives, significant findings, and reproducible acceptance evidence. Omit prompt recaps, apologies, agent misunderstandings/corrections, clerical review churn, and repetitive progress narration. Do not omit a defect or limitation that affects the delivered result.
Put reusable guides in docs/. Add evidence/ only for necessary supporting material; do not archive discarded process noise. Use real revisions and precise review scopes; do not carry a pass onto changed content or fabricate tests/approvals. Avoid mandatory per-stage files, manifests, and whole-repository hash machinery for routine changes.
Use repository-relative file links and paths, including logs and attachments. Public external sources may use HTTPS URLs. Do not publish private personal data, local absolute paths, credentials, private service addresses, or raw sessions. Minimize/redact evidence before publication and identify any redacted copy accurately; do not retain sensitive originals in a public archive.
Run checks appropriate to the change. Application changes need meaningful tests; use the documented verification commands and distinguish local results from external deployment checks.

Acceptance handbook and migration

Every change, including documentation-only work, must deliver or update a Chinese-only developer acceptance handbook at .local/acceptance/<change-id>.md in its feature worktree. Waiving a review never waives it. This directory is gitignored, never committed (including force-add) or published; keep it outside Hugo mounts. Link the local file in the final handoff, not in public Markdown links.
Give ordered, reproducible steps: starting revision and prerequisites; environment/dependency/configuration setup; applicable server start/stop commands and URLs; manual checks and automated commands with expected results. Record actual results and unverified items separately. Scale to the change; mark irrelevant steps as not applicable with a reason.
Explicitly assess migration from the preceding baseline: affected dependencies, configuration, content/data, routes and deployment. When needed, give ordered migration commands/actions, backup needs, post-migration checks and rollback/recovery steps, including irreversible limits. Otherwise state “No migration required” and why. Ask before unresolved migration decisions or destructive actions.
Keep detailed per-change steps in the local handbook. Preserve concise actual results, key verification commands, material migration decisions and any lasting upgrade/rollback instructions in the existing public EN/ZH log pair or an appropriate durable guide. Reusable setup belongs in docs/development.md; do not copy temporary checklists into public docs. The local handbook is not Git-synchronized: finish acceptance or save it separately before removing its worktree. A selected acceptance review must check reproducibility and this separation.

Commit checkpoint

Use an English Conventional Commit, type(scope): imperative subject (scope optional), with a suitable type such as docs, feat, fix, test, ci, or chore.
Multiple substantive changes require an English bullet-point body.
Before every commit, inspect the staged diff, show the exact staged paths and complete message, and wait for owner confirmation. If contents or message change, show a new preview. Commit only confirmed content; remote actions need applicable authorization.