Superpowers Artifact Ignore Policy Design

Status: proposed
Date: 2026-08-25
Scope: repository cleanup for this project plus a machine-wide Git ignore safeguard for future projects

Problem

Superpowers runtime directories contain orchestration state rather than product source. SDD ledgers, task briefs, reports, review diffs, screenshots, generated visual companions, local worktree registrations, command output, and absolute local paths create noisy changes and may expose operational or sensitive context when committed.

The current repository demonstrates the failure mode: main tracks 27 files under .superpowers/, totaling roughly 374 KB, and its decision to track those files conflicts with the feature branch's broad .superpowers/ ignore rule.

Policy

Operational Superpowers and worktree directories are private local state and must not be committed:

**/.superpowers/
**/.claude/superpowers/
**/.worktrees/

Intentional design and implementation documents remain normal project source under:

docs/superpowers/specs/
docs/superpowers/plans/

The dot-directory and documentation-directory policies are deliberately different. .superpowers/ is generated session state; docs/superpowers/ contains authored, reviewable project decisions.

Defense in Depth

The policy is enforced in two places:

The machine-wide Git excludes file protects every local repository, including new projects that have not yet added repository rules.
Each repository's .gitignore carries the same exclusions so collaborators and other machines receive the protection.

Global-only enforcement would not protect collaborators. Repository-only enforcement would depend on remembering to add the rules to every new project. Both layers are therefore required.

Current Repository Cleanup

The feature branch will merge the current origin/main. The .gitignore conflict will resolve in favor of the broad operational-directory exclusions plus the existing application build, dependency, secret, deployment, and generated-artifact rules.

The .superpowers/ files introduced on main will be removed from Git's index and from the resulting repository tree without rewriting history. Local copies will be retained as ignored files when present. The authored files under docs/superpowers/ remain tracked.

The existing demo-start and demo-complete tags remain unchanged. No branch or tag history is rewritten.

Global Configuration

The existing user-level ignore file at ~/.config/git/ignore will retain its current rules and gain the three operational-directory exclusions. No repository-specific build paths or application secrets belong in the global file.

The global ignore protects only untracked files. It does not retroactively remove already tracked artifacts, which is why the current repository also needs an index cleanup commit.

Safety and Failure Handling

Fetch and merge only the named origin/main into feature/uups-bank-demo.
If any conflict other than .gitignore appears, stop and inspect it rather than applying a broad resolution.
Remove .superpowers/ from the index without deleting local copies.
Do not rewrite published history or force-push.
Do not move or recreate tags.
Preserve existing global ignore entries byte-for-byte apart from appending the approved rules once.
Never print or inspect the contents of operational artifacts as part of cleanup.

Verification

The cleanup is accepted only when all of the following hold:

git ls-files '.superpowers/**' returns no paths in the feature result.
git check-ignore confirms representative .superpowers/, .claude/superpowers/, and .worktrees/ paths are ignored by both repository and global policy.
docs/superpowers/specs/ and docs/superpowers/plans/ remain tracked.
The merge commit contains no unexpected path changes beyond the current main merge, artifact removal, ignore policy, and this approved policy documentation.
make verify and git diff --check exit successfully.
The feature branch pushes normally without force and PR #2 becomes mergeable.

Non-goals

Purging .superpowers/ artifacts from existing Git history.
Rotating credentials; no credential exposure has been established.
Changing Superpowers runtime behavior or storage locations.
Ignoring intentional project documents under docs/superpowers/.
Applying repository-specific ignores to unrelated existing repositories automatically.

4.4 KiB Raw Permalink Blame History