**English** | [Русский](/ru/docs/upgrade)

# Upgrade Safety

<!-- doc-map: reader=user; zone=getting-started -->

What bootstrap touches, what it leaves alone, and how to upgrade without losing your work.

## The two trees

```
<repo>/
├── stacks/                ← framework-owned. Bootstrap rewrites this.
├── scripts/               ← framework-owned.
├── bootstrap/             ← framework-owned.
├── harness/                ← framework-owned.
├── .claude/               ← bootstrap output (ignore-able; regenerable).
└── .tausik/               ← YOUR data. Bootstrap NEVER touches this.
    ├── tausik.db
    ├── config.json
    ├── stacks/            ← your stack overrides
    └── venv/
```

## Bootstrap-owned vs user-owned

| Path | Owner | Survives upgrade? |
|---|---|---|
| `stacks/<name>/stack.json` | Framework | No — overwritten on every bootstrap. |
| `harness/stacks/*.md` (legacy) | Framework | Replaced on bootstrap; legacy fallback only. |
| `.claude/` | Bootstrap output | Regenerated each run. |
| `.tausik/stacks/<name>/stack.json` | **You** | **Yes — bootstrap never touches it.** |
| `.tausik/config.json` | **You** | **Yes.** |
| `.tausik/tausik.db` | **You** | **Yes.** |

The `tests/test_bootstrap_non_destructive.py` suite enforces this contract. Every bootstrap path is checked to make sure it never writes inside `.tausik/`.

## Upgrade workflow

1. `git pull` (or update the framework however you installed it).
2. `python bootstrap/bootstrap.py --no-detect` — refreshes `.claude/`, copies new `stacks/`, regenerates the MCP `_STACKS_ENUM` block.
3. `tausik stack lint` — validate that your overrides still parse against the new schema.
4. `tausik stack diff <name>` — for each stack you've overridden, sanity-check that the built-in didn't change in a way that breaks your assumptions.

## What can break a stack override

A non-trivial framework upgrade *can* invalidate an override even though the file isn't touched:

- The schema gained a required field. `tausik stack lint` will report it.
- A field was renamed (e.g. `detect[].kind` → `detect[].type`). `lint` will report unknown-field errors.
- An `extends: "builtin:NAME"` target was renamed or removed. `lint` will surface "extends target not found".
- A gate name moved between stacks. Your override referencing it via `null` (to disable) becomes a no-op silently — review with `stack export`.

The framework prefers additive changes; breaking changes ship in a major version with a migration note in the changelog.

## When something goes wrong

| Symptom | What to do |
|---|---|
| Bootstrap fails or warns about `.tausik/stacks/` | Run `tausik stack lint` to spot validation errors. |
| `tausik task add --stack X` rejects a stack you defined | Confirm `.tausik/stacks/X/stack.json` exists and parses; check `tausik stack list`. |
| A gate stops firing after upgrade | `tausik stack info <name>` to see active gates; `stack export <name>` to confirm merge order. |
| You want to start over | `tausik stack reset <name>` removes a single override; `rm -rf .tausik/stacks/` blows them all away. |

## Disaster recovery

If `.tausik/` itself is corrupted or you want to nuke local state, only the database (`.tausik/tausik.db`) is irreplaceable — everything else can be regenerated by re-running bootstrap. Back up `.tausik/tausik.db` and `.tausik/stacks/` before doing anything destructive.

## Version Policy

- **Patch (x.y.Z)** — bug fixes, no API or schema changes.
- **Minor (x.Y.0)** — new features, additive DB migrations, API extends without breaking changes.
- **Major (X.0.0)** — breaking API/schema changes; a migration note in `CHANGELOG.md` is mandatory.

`tausik doctor` after an upgrade reports drift or config issues.

## See Also

- [Customization](https://github.com/Kibertum/tausik-core/blob/v1.11.0/docs/en/customization.md) — how to override without touching framework files.
- [Architecture](/docs/architecture) — layer and ownership model.