feat: add explicit brainstorm state-dir selection

[yejiming]

What problem are you trying to solve?

The brainstorm companion currently pushes persistent session state into the working tree when --project-dir is used, under <project>/.superpowers/brainstorm/.

For open source repos, that creates repo pollution and leads users toward .gitignore churn just to hide AI-tool state. Persistent brainstorm state should default to a user-owned location outside the repository, while still allowing explicit in-repo storage when someone really wants it.

What does this PR change?

This adds a new --state-dir flag and SUPERPOWERS_STATE_DIR environment variable for explicit brainstorm state storage.

It also changes the default persistent storage root to a user-owned data directory outside the working tree, and keeps --project-dir as a compatibility alias that still resolves to <project>/.superpowers/brainstorm/<session-id>/.

Is this change appropriate for the core library?

Yes.

This is general-purpose core behavior for brainstorm session storage, not a project-specific workflow or third-party integration. Any user of the brainstorm companion can hit the same repo-pollution problem.

What alternatives did you consider?

1. Remove --project-dir immediately.
   Rejected because it would break existing workflows that already rely on in-repo persistence.

2. Keep /tmp as the default persistent location.
   Rejected because it is ephemeral and may be unsuitable for retaining brainstorm sessions across restarts.

3. Add a more complex platform-specific storage abstraction.
   Rejected because a simple user-owned default path plus explicit override mechanisms solves the problem with less complexity.

Does this PR contain multiple unrelated changes?

No. This PR is limited to brainstorm session storage selection and the associated documentation/tests.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: none found

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
Codex desktop	current	GPT-5.4	GPT-5.4

Evaluation

• What was the initial prompt you (or your human partner) used to start the session that led to this change?

  • Investigate issue Brainstorm session storage should not default to the working tree #975 and implement a minimal fix that moves brainstorm state out of the working tree by default while preserving compatibility.

• How many eval sessions did you run AFTER making the change?

  • One targeted shell test pass for path selection plus one manual smoke run of start-server.sh with --state-dir.

• How did outcomes change compared to before the change?

  • Before: the script only supported --project-dir, and persistent in-repo storage was the documented path.
  • After: the script supports --state-dir and SUPERPOWERS_STATE_DIR, defaults to a user-owned storage directory outside the working tree, and still accepts --project-dir as a compatibility alias.

Rigor

• If this is a skills change: I used superpowers:writing-plans style discipline for scoped implementation and added targeted test coverage for the new path-selection behavior
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

Verification run:

• bash tests/brainstorm-server/start-server-paths.test.sh
• git diff --check
• manual smoke run:
  • bash skills/brainstorming/scripts/start-server.sh --state-dir /tmp/sp-state-smoke --foreground

Human review

• A human has reviewed the COMPLETE proposed diff before submission

[obra]

It looks like you opened two similar pull requests for this same thing. What's going on?

[yejiming]

It looks like you opened two similar pull requests for this same thing. What's going on?

Yeah, I'll close the other one