# DigiDala — AI Handoff & Working Contract

This file is the entry point for continuing DigiDala work in a new ChatGPT chat.
It is a **working contract for the assistant**, not a project-state journal.

## 1. Mandatory startup procedure

When a new chat starts with a DigiDala archive, the assistant must:

1. Read this file first.
2. Read `docs/PROJECT_CONTEXT.md` for the stable product/context baseline.
3. Read `docs/PROJECT_STATE.md` for the current technical and release state.
4. Read `docs/ROADMAP.md` for the currently planned work and priorities.
5. Read `CHANGELOG.md` for release history.
6. Read `docs/PRODUCTION_DEPLOYMENT.md` when the task concerns staging/production deployment, runtime configuration, or the production bot.
7. Read the most recent `ALPHA*_CHANGESET.md` file(s), when present, for release-specific changes and acceptance criteria.
8. Inspect the repository itself when the task concerns implementation: relevant source files, `package.json`, tests, scripts, Git status/log/tags as needed.

The assistant must not rely on memory from another chat when the repository or these documents contain the answer.

If documents disagree, do not silently reconcile them. Identify the conflict and use the newest explicitly verified project state as the basis, unless the user gives a different instruction.

## 2. Core interaction rule: do only what was requested

Do not make unsolicited product, UX, text, visual, architectural, or behavioral changes.

A requested change is **scoped exactly as stated**. Do not "clean up", "improve", "standardize", or modify adjacent behavior merely because it looks related.

In particular:

- If the user asks to change one text, change only that text unless the user explicitly asks for all occurrences or a broader copy change.
- Existing UI strings that were not part of the task are frozen and must be preserved.
- Do not replace wording with a supposedly better wording, even when the new wording seems equivalent.
- Do not change behavior, layout, animation, API semantics, timing, or architecture outside the stated task.
- When a broader change appears necessary, explain why and ask for permission before expanding scope.

## 3. Preserve explicit requirements literally

When the project documentation or user has specified exact text, labels, API behavior, timing, state transitions, or UX behavior, reproduce it exactly. If an adjacent change seems desirable, propose it separately rather than including it.

Examples of requirements that must not be reinterpreted:

- exact Russian UI copy;
- which participant sees which completion message;
- who is allowed to initiate a server action;
- which client performs local visualization;
- which client performs the final server reset;
- polling intervals and other synchronization rules.

Do not substitute an approximate equivalent.

## 4. Server-authoritative lifecycle rule

For the shared Mandala lifecycle, the server is authoritative.

The intended pattern is:

- The last participant initiates destruction.
- The server changes the Mandala lifecycle to `destroying`.
- Other already-open clients observe that server transition through the existing synchronization mechanism and start the **local visual animation only**.
- Other clients do not independently initiate server destruction and do not call the server-side destruction-finish endpoint.
- Only the destroyer client completes the server-side reset.

Do not weaken or bypass server authority merely to make a client-side symptom disappear.

## 5. Release workflow — mandatory order

DigiDala releases are managed through the Windows development clone, GitHub, and the VPS. The VPS is not a manual development workspace.

Use this order:

### Development

1. Work in the Windows repository (VSCode).
2. Make the requested changes only.
3. Run the project's prescribed local checks, normally `npm.cmd run check`.
4. Review `git status` and the actual diff.
5. Stage only files that belong to the intended change.
6. Commit with an appropriate message.
7. Push the commit to `origin/main` on GitHub.

### Release

8. Create the release tag only after the commit is on GitHub.
9. Push the tag to GitHub.
10. The VPS obtains the tagged source from GitHub; never deploy by manually copying edited source files to the VPS.
11. Run the project's deployment script for the exact tag, normally `scripts/deploy-test.sh <tag>`.
12. Verify the deployed release path, `current` symlink, service status and HTTP health.
13. Perform the required manual Telegram QA.
14. When the same release is promoted to production, use the exact tag that passed staging QA; do not rebuild or modify the source between staging and production.
15. Perform a separate production Telegram QA after deployment.
16. Record the production outcome and any runtime-only configuration fixes in the project journals without changing the already released code tag.

For production specifically, the normal chain is:

```text
Windows development
  → local checks
  → commit
  → push main
  → release tag
  → staging deploy + Telegram QA
  → same exact tag to production
  → production runtime/smoke checks
  → production Telegram QA
  → documentation-only follow-up commit
```

Runtime-only content administration that is already supported by the bot (for example Competitive campaign creation/queue management or welcome/about editing) does not require a new code release. A new code change still follows the full release chain above.

A tag is an immutable release checkpoint. A prepared archive is not evidence that its contents have been installed in the user's repository. If a defect is found after tagging, do not silently move or rewrite the existing tag. Make a new commit and release a new alpha version.

## 6. Git discipline

The assistant must distinguish clearly between:

- what it prepared locally in the conversation/tool environment;
- what the user has actually executed in the Windows repository;
- what has been committed;
- what has been pushed to GitHub;
- what has been tagged;
- what has actually been deployed to the VPS;
- what has been manually verified.

Never claim that a commit, push, tag, deployment, or GitHub update happened unless the user/tool output proves it.

Do not infer that a local change is on GitHub merely because a file or archive was prepared.

## 7. Working-tree safety

The repository may contain unrelated or line-ending-only modifications.

Never use broad commands such as `git add .`, `git commit -a`, or mass restore/reset commands unless the user explicitly asks for them.

Stage and review the exact intended files.

If unrelated modified files exist, leave them untouched unless the user explicitly includes them in the task.

## 8. Assistant-side verification and patch delivery

When the user provides a current project archive and asks for an implementation change, the assistant must perform the repository-side preparation and verification itself before asking the user to apply anything.

The mandatory assistant workflow is:

1. Treat the provided archive as the current source of truth and inspect the relevant implementation, tests, documentation, and Git state.
2. Implement only the requested change, preserving unrelated working-tree modifications.
3. Run the prescribed automated checks in the assistant's working copy, normally `npm run check` (or the repository-equivalent check command).
4. Inspect the resulting diff itself, including `git status`, the intended file list, the diff/stat, tests, and documentation/version consistency. Do not delegate this self-review to the user merely to compensate for the assistant having prepared an unverified archive.
5. Resolve any problems found during this self-review before delivering the files. This includes stale test counts, inconsistent release numbers, missing change logs, unintended files, broken paths, temporary files, and other packaging mistakes.
6. Deliver a **patch archive only**: include only the changed and/or newly created project files, with their original repository paths preserved. Do not normally deliver a full copy of the repository. Exclude `.git`, temporary files, debug output, screenshots, generated artifacts, and unrelated files unless the user explicitly asks for them.
7. Clearly distinguish assistant-side verification from user-side verification. The assistant may state which automated checks passed in its own working copy, but must not claim that the user's Windows repository, Git index, GitHub, VPS, or deployment changed until the user's output or an available tool confirms it.
8. After delivering a verified patch, keep the user's required local operations minimal. Normally the user only needs to replace the files, run `npm.cmd run check` in the Windows clone, and then continue with the normal Git release workflow. Do not routinely require the user to send back the full diff for review when the assistant has already reviewed the exact patch.

For every delivered patch, the assistant must know and be able to state:

- which files changed or were added;
- which automated checks passed in the assistant environment;
- that the archive contains only the intended patch files;
- whether any manual QA, deployment, Git commit, push, tag, or production action remains for the user.

The assistant must never deliver an archive as a "candidate" or "verified" artifact unless the exact delivered contents have been self-checked. It must not make the user perform repeated assistant-side QA merely because the assistant prepared the files.

## 9. Testing and acceptance

Automated tests are necessary but do not replace manual product QA.

For each release, distinguish:

- automated verification;
- deployment verification;
- manual Telegram verification;
- unresolved issues / release gates.

Do not call a release "fully verified" while documented manual acceptance criteria remain untested.

## 10. How to reason about bugs

Before changing code:

1. Locate the actual state transition or data flow causing the observed symptom.
2. Confirm the intended behavior from the project documents and the user's current request.
3. Make the smallest change that fixes the confirmed cause.
4. Preserve existing invariants and unrelated behavior.
5. Add/update tests when appropriate.
6. Run the prescribed checks.

Do not fix symptoms by changing architecture when a local client-side cause is established.

## 11. Handoff/update rule

At the end of a meaningful work session, update the project journals so a new chat can resume without relying on conversation memory.

Keep responsibilities separate:

- `PROJECT_CONTEXT.md` — stable, compact understanding of the product and architecture.
- `PROJECT_STATE.md` — current factual state, verified checkpoints, open issues, active release, deployment state.
- `ROADMAP.md` — what should happen next and why.
- `CHANGELOG.md` — release history.
- `ALPHA*_CHANGESET.md` — release-specific implementation/change summary and acceptance notes.
- `docs/PRODUCTION_DEPLOYMENT.md` — production runtime separation, first-time bootstrap requirements and deployment/rollback procedure.
- `AI_HANDOFF.md` — rules for how the assistant must work with all of the above.

When a production-only runtime correction is made without a code change, record the factual result in the journals but do not rewrite the corresponding release tag or pretend the correction was part of the tagged source.

Do not turn `PROJECT_STATE.md` into a transcript of the chat.

## 12. New-chat bootstrap prompt

When continuing DigiDala in a new ChatGPT chat, paste the following after attaching the current project archive:

> You are continuing the DigiDala project from a previous chat. Treat the attached repository/archive as the source of truth.
>
> First read `AI_HANDOFF.md`. Then read, in order: `docs/PROJECT_CONTEXT.md`, `docs/PROJECT_STATE.md`, `docs/ROADMAP.md`, `CHANGELOG.md`, and the latest `ALPHA*_CHANGESET.md` files. When the task concerns deployment or production runtime, also read `docs/PRODUCTION_DEPLOYMENT.md`. Then inspect the repository/Git state and the relevant implementation files needed for my task.
>
> Follow `AI_HANDOFF.md` as a mandatory working contract. Do not rely on memory from another chat when the repository or project journals contain the answer. Do not silently reconcile contradictions in the journals. Do not make unsolicited changes: preserve all existing behavior and exact UI text unless I explicitly ask to change it. Never expand the scope of a requested change without telling me and getting approval.
>
> For releases, follow this exact chain: Windows development clone → checks → review/stage → commit → push `main` to GitHub → create and push release tag → VPS obtains the exact tag from GitHub → staging deployment → manual Telegram QA → the same exact tag to production → production verification and manual Telegram QA → documentation-only follow-up commit. Never manually copy development files to the VPS, and never claim that a Git/GitHub/VPS operation happened unless it is confirmed by command output.
>
> Before acting, reconstruct the current project state from the files. Then proceed with my request using the smallest correct change.
>
> When I provide a project archive for implementation work, perform the repository inspection, automated checks, diff review, documentation consistency review, and patch packaging yourself before giving me files to apply. Deliver only the changed/new files in a patch archive with their original paths. Do not make me perform repeated assistant-side QA such as rechecking your diff simply because the archive was prepared by you. After I apply the patch, I should normally only need to run `npm.cmd run check` and continue with the established Git/release workflow.