slaguru666/AIPass
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(backup): correct backup/.backup/.backupignore docs across the system

Browse Source 
Streamlined prompts had drifted from reality. Full-context investigation
(3 agents + @memory storyline) corrected:

- .backup/ documented as a SHARED runtime namespace (3 writers: @backup
  snapshot stores, @memory rollover safety copies, @flow processed_plans),
  not @backup-exclusive.
- @backup README: full 11-command coverage, .backup/ store layout, and a
  .backupignore (gitignore-for-backups: pathspec/gitwildmatch, BUILTIN_IGNORES,
  self-exclusion, ships as config) section.
- @backup branch prompt: stale .backup_system/ -> .backup/ (3x), drive_test.py
  -> drive_check.py (was misleading the agent every turn).
- Root README: @backup added to roster + uninstall covers .backup/.backupignore.
  navmap @backup line corrected (Drive planned + shared namespace).
- Shipped root /.backupignore realigned to BUILTIN_IGNORES (dropped stale
  .backup_system/, removed over-broad *logs).
- Removed dead backup/run/ test dir.

@backup verified: 220 tests green, seedgo 100%. Closes td-218.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QEQZXCtgnF3NQtcttTErpq
This commit is contained in:
AIOSAI
2026-06-24 06:51:18 -07:00
co-authored by Claude Opus 4.8
parent c771a22771
commit 40602702ef
7 changed files with 76 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.aipass/tier1_navmap.md
+1 -1
View File
@@ -55,7 +55,7 @@ src/aipass/<name>/
- @skills — capability framework. Discoverable, self-contained skill units any agent can run; consume AIPass services as opt-in imports (e.g. the Telegram skill).
- @daemon — task scheduler. Cron-triggered firing; each branch owns its `.daemon/schedule.json`, the daemon discovers and fires.
- @commons — the social space. Where branches post, comment, vote, and gather as a community.
- @backup — local-first backups. Project-owned snapshots and restore for any directory; no external service.
- @backup — local-first backups. Snapshots + versioning + restore for any directory; optional Google Drive sync (planned). `.backup/` is a shared runtime namespace — @memory rollover and @flow (plan archive) also write there.
# Daily commands
.backupignore
-2
View File
@@ -2,7 +2,6 @@
# Lines starting with # are comments. Blank lines are ignored.
# Edit this file to customize. Source defaults: handlers/ignore/patterns.py
.backup_system/
.backup/
.git/
.svn/
@@ -27,4 +26,3 @@ dist/
*.log
.ruff_cache/
.coverage
*logs
CHANGELOG.md
+13
View File
@@ -32,6 +32,19 @@ PyPI version — not the changelog header.
the event, its `BULLETINS.central.json` store no longer exists, and prax
already prunes `bulletin_board` as a deprecated section. Archived + unwired
from the event registry; prax's pruning stays (td-102).
- **Dead `backup/run/` test dir** — leftover from an ad-hoc backup test run
(only its generated `.backupignore` had been tracked); removed (td-218).
### Documentation
- **Backup docs corrected** — `.backup/` is now documented as a **shared runtime
namespace** (@backup stores + @memory rollover safety copies + @flow plan
archive), not @backup-exclusive. @backup's README gained full command coverage,
the `.backup/` store layout, and a `.backupignore` ("gitignore for backups")
section; its branch prompt's stale `.backup_system/` / `drive_test.py` names
were fixed. Root README lists @backup and documents `.backupignore`; the navmap
was corrected. The shipped root `/.backupignore` was realigned to
`BUILTIN_IGNORES` (dropped stale `.backup_system/` + over-broad `*logs`).
## [2026-06-23]
README.md
+7 -2
View File
@@ -155,7 +155,7 @@ drone @ai_mail dispatch @agent "Archive old sessions" "Find sessions older than
## The Reference Implementation
AIPass ships with 13 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.
AIPass ships with 14 core agents that maintain and develop the framework itself — proving the architecture works at scale. You don't need any of these to use AIPass in your own project. They're here as examples and as services your project can call.
```
devpulse (orchestrator)
@@ -170,7 +170,8 @@ devpulse (orchestrator)
├── memory — automatic archival, ChromaDB, semantic search
├── api — LLM access layer (OpenRouter, multi-provider)
├── trigger — event-driven automation + self-healing
└── cli — terminal formatting and rich output
├── cli — terminal formatting and rich output
└── backup — local-first snapshots + restore (optional Drive sync)
```
These agents work on the **same filesystem, same project, same time** — no sandboxes, no worktrees. This is the pattern your projects inherit.
@@ -201,6 +202,7 @@ These agents work on the **same filesystem, same project, same time** — no san
| [**hooks**](src/aipass/hooks/README.md) | Hook engine — per-project config, sound control, event dispatch |
| [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
| [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output |
| [**backup**](src/aipass/backup/README.md) | Local-first backups — snapshots, versioning, restore (optional Google Drive sync) |
</details>
@@ -266,6 +268,9 @@ AIPass stores everything locally in your project directory. To remove it:
rm -rf .aipass/ .claude/ .ai_mail.local/ hooks/ src/
rm -f CLAUDE.md AGENTS.md *_REGISTRY.json .gitignore
# If you ran the backup system, also remove its local state + shipped config
rm -rf .backup/ && rm -f .backupignore
# If you installed via pip
pip uninstall aipass
```
src/aipass/backup/.aipass/aipass_local_prompt.md
+4 -4
View File
@@ -39,7 +39,7 @@ apps/
│ ├── settings.py # Settings UI (stub — low priority)
│ ├── drive_sync.py # Drive sync (stub — DPLAN-003)
│ ├── drive_stats.py # Drive stats (stub)
│ ├── drive_test.py # Drive test (stub)
│ ├── drive_check.py # Drive check (stub — DPLAN-003)
│ └── drive_clear.py # Drive clear (stub)
└── handlers/
├── copy/ # File copying (snapshot + versioned)
@@ -47,7 +47,7 @@ apps/
├── ignore/ # .backupignore patterns + whitelist
├── json/ # JSON persistence, atomic writes, ops log
├── path/ # Backup path building
├── project/ # Config, registry, setup (.backup_system/)
├── project/ # Config, registry, setup (.backup/)
├── report/ # Result formatting
├── scan/ # Directory walking + filtering
├── state/ # Changelog, metadata, timestamps
@@ -58,11 +58,11 @@ apps/
## Integration
- **Depends on:** @prax for logging, @cli for Rich console output
- **Serves:** Any project on the PC — backups are project-owned (.backup_system/ in target root)
- **Serves:** Any project on the PC — backups are project-owned (.backup/ in target root)
## Working Habits
- Project-owned design: .backup_system/ and .backupignore live in the TARGET project, not centrally
- Project-owned design: .backup/ and .backupignore live in the TARGET project, not centrally
- Normal citizen namespace: uses `from aipass.backup.apps.modules.*` / `from aipass.backup.apps.handlers.*`
- Entry point sets AIPASS_BRANCH_NAME env var for Prax
- BUILTIN_IGNORES in patterns.py is the single source for default ignore patterns
src/aipass/backup/README.md
+51 -3
View File
@@ -64,11 +64,59 @@ apps/
backup register <path> [--name <name>] # Register a project for backup
backup snapshot <path|@name> # Full mirror backup
backup versioned <path|@name> # Incremental timestamped backup
backup all <path|@name> # Snapshot + versioned
backup all <path|@name> # Snapshot + versioned + drive
backup status <path|@name> # Show backup info and history
backup --version # Show version
backup restore <path|@name> list <file> # List available versions of a file
backup restore <path|@name> file <f> <o> # Restore a file version to output path
backup settings <path|@name> # Settings UI (stub)
backup drive_sync <path|@name> # Google Drive sync (stub — DPLAN-003)
backup drive_check <path|@name> # Drive connectivity check (stub — DPLAN-003)
backup drive_stats <path|@name> # Drive storage stats (stub — DPLAN-003)
backup drive_clear <path|@name> # Clear Drive sync state (stub — DPLAN-003)
```
All 11 commands are auto-discovered by the entry point router.
---
## `.backup/` Store Structure
Each registered project gets a `.backup/` directory at its root:
```
.backup/
├── config.json # Project backup configuration
├── snapshots/ # Full mirror copies (eager — created on register)
├── versioned/ # Incremental timestamped backups (lazy)
├── logs/ # Operation logs (eager — created on register)
├── timestamps.json # Backup timing metadata (lazy)
├── changelog.json # Change history (lazy)
└── drive_tracker.json # Drive sync dedup tracker (lazy)
```
On `register`, only `snapshots/` and `logs/` are created eagerly (plus `config.json`). The rest are created lazily on first use.
**Shared namespace:** `.backup/` is NOT exclusive to @backup. Three writers use it:
- **@backup** — snapshot/versioned stores at a registered project root
- **@memory** — rollover safety copies (`rollover_backup_*.json`) written to `<branch>/.backup/` during memory overflow
- **@flow** — closed plans archived to `<repo-root>/.backup/processed_plans/` for vectorization by @memory
The root `.gitignore` covers all three with a single `.backup/` entry.
---
## `.backupignore`
A true `.gitignore` for backups, using real pathspec/gitwildmatch semantics:
- `#` comments, blank lines ignored
- `!` negation (un-ignore a path)
- Trailing `/` for directory-only matching
- Last-match-wins ordering
Lives at the **project root** and is the single source of truth governing snapshot, versioned, Drive sync, and mirror-cleanup operations. Generated from `BUILTIN_IGNORES` in `handlers/ignore/patterns.py` during `register`. The `.backup/` directory is included in `BUILTIN_IGNORES`, so the store self-excludes from its own backups.
The repo-root `/.backupignore` ships intentionally as the curated default so users don't snapshot junk.
---
## Integration Points
@@ -78,4 +126,4 @@ backup --version # Show version
- @cli — Rich console output
### Provides To
- Any project on the PC — backups are project-owned (.backup/ in target root)
- Any project on the PC — backups are project-owned (`.backup/` in target root)
src/aipass/backup/run/.backupignore
-28
View File
@@ -1,28 +0,0 @@
# Backup System ignore patterns (gitignore-style)
# Lines starting with # are comments. Blank lines are ignored.
# Edit this file to customize. Source defaults: handlers/ignore/patterns.py
.backup/
.git/
.svn/
.hg/
__pycache__/
.pytest_cache/
*.pyc
*.pyo
*.egg-info/
.venv/
venv/
.tox/
node_modules/
.vscode/
.idea/
*.swp
*.swo
.DS_Store
Thumbs.db
build/
dist/
*.log
.ruff_cache/
.coverage