83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```gitignore
|
|
**/.superpowers/
|
|
**/.claude/superpowers/
|
|
**/.worktrees/
|
|
```
|
|
|
|
Intentional design and implementation documents remain normal project source under:
|
|
|
|
```text
|
|
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:
|
|
|
|
1. The machine-wide Git excludes file protects every local repository, including new projects that have not yet added repository rules.
|
|
2. 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:
|
|
|
|
1. `git ls-files '.superpowers/**'` returns no paths in the feature result.
|
|
2. `git check-ignore` confirms representative `.superpowers/`, `.claude/superpowers/`, and `.worktrees/` paths are ignored by both repository and global policy.
|
|
3. `docs/superpowers/specs/` and `docs/superpowers/plans/` remain tracked.
|
|
4. The merge commit contains no unexpected path changes beyond the current `main` merge, artifact removal, ignore policy, and this approved policy documentation.
|
|
5. `make verify` and `git diff --check` exit successfully.
|
|
6. 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.
|