# 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 the most recent `ALPHA*_CHANGESET.md` file(s), when present, for release-specific changes and acceptance criteria.
7. 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.

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. 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.

## 9. 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.

## 10. 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.
- `AI_HANDOFF.md` — rules for how the assistant must work with all of the above.

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

## 11. 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. 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 → `scripts/deploy-test.sh <tag>` → deployment verification → manual QA. 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.