From 40602702ef408861808a5fb6a96c4ba465c3a762 Mon Sep 17 00:00:00 2001 From: AIOSAI Date: Wed, 24 Jun 2026 06:51:18 -0700 Subject: [PATCH] docs(backup): correct backup/.backup/.backupignore docs across the system 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) Claude-Session: https://claude.ai/code/session_01QEQZXCtgnF3NQtcttTErpq --- .aipass/tier1_navmap.md | 2 +- .backupignore | 2 - CHANGELOG.md | 13 +++++ README.md | 9 +++- .../backup/.aipass/aipass_local_prompt.md | 8 +-- src/aipass/backup/README.md | 54 +++++++++++++++++-- src/aipass/backup/run/.backupignore | 28 ---------- 7 files changed, 76 insertions(+), 40 deletions(-) delete mode 100644 src/aipass/backup/run/.backupignore diff --git a/.aipass/tier1_navmap.md b/.aipass/tier1_navmap.md index ab898dd7..b5874ec2 100644 --- a/.aipass/tier1_navmap.md +++ b/.aipass/tier1_navmap.md @@ -55,7 +55,7 @@ src/aipass// - @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 diff --git a/.backupignore b/.backupignore index f606661b..57595e6b 100644 --- a/.backupignore +++ b/.backupignore @@ -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 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ba30e5a..5c75a389 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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] diff --git a/README.md b/README.md index 91ba5f31..6ef5535d 100644 --- a/README.md +++ b/README.md @@ -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) | @@ -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 ``` diff --git a/src/aipass/backup/.aipass/aipass_local_prompt.md b/src/aipass/backup/.aipass/aipass_local_prompt.md index e7cd8959..881d433d 100644 --- a/src/aipass/backup/.aipass/aipass_local_prompt.md +++ b/src/aipass/backup/.aipass/aipass_local_prompt.md @@ -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 diff --git a/src/aipass/backup/README.md b/src/aipass/backup/README.md index 0952e8d0..c130fadf 100644 --- a/src/aipass/backup/README.md +++ b/src/aipass/backup/README.md @@ -64,11 +64,59 @@ apps/ backup register [--name ] # Register a project for backup backup snapshot # Full mirror backup backup versioned # Incremental timestamped backup -backup all # Snapshot + versioned +backup all # Snapshot + versioned + drive backup status # Show backup info and history -backup --version # Show version +backup restore list # List available versions of a file +backup restore file # Restore a file version to output path +backup settings # Settings UI (stub) +backup drive_sync # Google Drive sync (stub — DPLAN-003) +backup drive_check # Drive connectivity check (stub — DPLAN-003) +backup drive_stats # Drive storage stats (stub — DPLAN-003) +backup drive_clear # 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 `/.backup/` during memory overflow +- **@flow** — closed plans archived to `/.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) diff --git a/src/aipass/backup/run/.backupignore b/src/aipass/backup/run/.backupignore deleted file mode 100644 index 57595e6b..00000000 --- a/src/aipass/backup/run/.backupignore +++ /dev/null @@ -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