Upgrade Safety

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 — how to override without touching framework files.
• Architecture — layer and ownership model.