Skip to content

Commit deccc07

Browse files
omoshola-oomoshola-o
committed
chore: enforce strict gitignore rules
1 parent b8a5a24 commit deccc07

35 files changed

Lines changed: 16794 additions & 50 deletions

‎.gitignore‎

Lines changed: 18 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,30 @@
11
# Rust
2-
/target/
3-
**/target/
4-
**/*.rs.bk
5-
6-
# OS
7-
.DS_Store
8-
Thumbs.db
9-
10-
# IDE
11-
.idea/
12-
.vscode/
2+
target/
133
*.swp
144
*.swo
15-
*~
16-
17-
# Environment
18-
.env
19-
.env.local
20-
21-
# LaTeX
22-
*.aux
23-
*.bbl
24-
*.blg
25-
*.log
26-
*.out
27-
*.toc
28-
*.fls
29-
*.fdb_latexmk
30-
*.synctex.gz
315

326
# Python
337
__pycache__/
34-
*.pyc
35-
.pytest_cache/
8+
*.py[cod]
9+
*$py.class
3610
*.egg-info/
11+
*.egg
3712
dist/
3813
build/
14+
.eggs/
15+
*.whl
3916
.venv/
17+
venv/
18+
env/
4019

41-
# Test artifacts
42-
*.tmp
43-
*.bak
44-
45-
# Planning docs build artifacts
46-
planning-docs/_build/
47-
planning-docs/.cache/
48-
49-
# Internal docs / AI planning / prompt artifacts (do not publish)
50-
planning-docs/
51-
docs/internal/
52-
CLAUDE-CODE-INSTRUCTIONS*.md
53-
SPEC-*.md
54-
.claude/
55-
56-
# Local runtime state
57-
.agentra/
58-
docs/REPO_HYGIENE.md
59-
ECOSYSTEM-CONVENTIONS.md
20+
# IDE
21+
.vscode/
22+
.idea/
23+
*.iml
24+
.fleet/
6025

61-
# Local goals (internal only)
62-
goals/
26+
# OS
27+
.DS_Store
28+
Thumbs.db
29+
*.swp
30+
*~

‎docs/REPO_HYGIENE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Repository Hygiene Policy
2+
3+
This repository follows a public-source hygiene rule set.
4+
5+
## Do Not Commit
6+
7+
- AI planning scratchpads and prompt session artifacts.
8+
- Internal-only strategy documents that are not part of product docs.
9+
- Local runtime state and generated caches.
10+
- Secrets, tokens, private keys, and local env files.
11+
12+
## Required Controls
13+
14+
- `.gitignore` MUST block planning/prompt/internal folders.
15+
- Public docs MUST live under `docs/` and be product-meaningful.
16+
- Release and publish workflows MUST only ship production artifacts.
17+
18+
## Pre-Push Checklist
19+
20+
- Confirm no `planning` or `prompt` files are staged.
21+
- Confirm no `.env*`, credentials, or local machine artifacts are staged.
22+
- Run project verification (`fmt`, `clippy/lint`, `test`) before publishing.

‎docs/internal/AUTONOMIC_OPS_USER_IMPACT_WALKTHROUGH.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Autonomic Ops User Impact Walkthrough
2+
3+
Date: 2026-02-21
4+
Scope: AgenticMemory, AgenticVision, AgenticCodebase
5+
Objective: Keep daily operation hands-off so users do not manually manage lifecycle tasks.
6+
Canonical references:
7+
- `CANONICAL_ECOSYSTEM_INDEPENDENCE_CONTRACT.md`
8+
- `CANONICAL_SISTER_KIT.md`
9+
10+
## 1) What Is Implemented Now (Phase 4)
11+
12+
### AgenticMemory
13+
14+
- Autonomous maintenance loop is wired into MCP runtime and tenant sessions.
15+
- Loop runs:
16+
- Auto-save checks
17+
- Rolling backup + retention pruning
18+
- Sleep-cycle maintenance (decay refresh, tier balancing, completed-session auto-archive)
19+
- Profile-driven posture via `AMEM_AUTONOMIC_PROFILE` (`desktop|cloud|aggressive`).
20+
- Storage migration is policy-gated via `AMEM_STORAGE_MIGRATION_POLICY` (`auto-safe|strict|off`).
21+
- Legacy `.amem` checkpoint + auto-migration occurs in `auto-safe` mode.
22+
- SLA-aware throttling for heavy maintenance under sustained mutation pressure (`AMEM_SLA_MAX_MUTATIONS_PER_MIN`).
23+
- Health-ledger snapshot output for operations visibility (`AMEM_HEALTH_LEDGER_DIR` or shared `AGENTRA_HEALTH_LEDGER_DIR`, default `~/.agentra/health-ledger`).
24+
25+
### AgenticVision
26+
27+
- Daemon starts a background maintenance loop automatically.
28+
- Loop performs map cache expiry cleanup and registry delta GC.
29+
- Profile-driven posture via `CORTEX_AUTONOMIC_PROFILE` (`desktop|cloud|aggressive`).
30+
- Cache migration policy via `CORTEX_STORAGE_MIGRATION_POLICY` (`auto-safe|strict|off`).
31+
- Legacy cached `.ctx` maps are rewritten forward in `auto-safe` mode.
32+
- SLA-aware throttling for registry GC under sustained cache pressure (`CORTEX_SLA_MAX_CACHE_ENTRIES_BEFORE_GC_THROTTLE`).
33+
- Health-ledger snapshot output (`CORTEX_HEALTH_LEDGER_DIR` or shared `AGENTRA_HEALTH_LEDGER_DIR`, default `~/.agentra/health-ledger`).
34+
35+
### AgenticCodebase
36+
37+
- Compile performs automatic pre-write rolling backup on existing `.acb` outputs.
38+
- Collective cache self-maintains by periodic expiry eviction.
39+
- Profile-driven posture via `ACB_AUTONOMIC_PROFILE` (`desktop|cloud|aggressive`).
40+
- Storage migration policy via `ACB_STORAGE_MIGRATION_POLICY` (`auto-safe|strict|off`).
41+
- Legacy `.acb` files checkpoint + auto-migrate on read in `auto-safe` mode.
42+
- SLA-aware throttling for collective cache maintenance under sustained registry load (`ACB_SLA_MAX_REGISTRY_OPS_PER_MIN`).
43+
- Health-ledger snapshot output for registry and CLI operations (`ACB_HEALTH_LEDGER_DIR` or shared `AGENTRA_HEALTH_LEDGER_DIR`, default `~/.agentra/health-ledger`).
44+
45+
## 2) Day-to-Day Effect for Users
46+
47+
- Default is still zero-config and conservative.
48+
- Teams can now choose operational posture by profile instead of low-level tuning.
49+
- Strict environments can block migration automatically.
50+
- Upgrade-friendly environments can auto-migrate with checkpoints.
51+
52+
## 3) User Experience by Environment
53+
54+
### Local desktop
55+
56+
- `desktop` profile gives low-noise maintenance cadence and safer background behavior.
57+
58+
### MCP desktop agents (Codex/Claude/Desktop clients)
59+
60+
- Connected sessions continuously self-maintain with low operational overhead.
61+
- Sleep-cycle behavior improves long-running graph health with minimal user involvement.
62+
63+
### Cloud/fleet
64+
65+
- `cloud` profile increases maintenance cadence and retention posture for high-churn runtimes.
66+
- Policy gates allow stricter migration controls when needed.
67+
68+
## 4) What Is Still Pending (Phase 5+)
69+
70+
- Full physical tiered storage classes (separate on-disk hot/warm/cold backends).
71+
- Major-version migration policy matrix with explicit compatibility windows.
72+
- Unified ledger aggregation endpoint (optional adapter) while preserving standalone execution.
73+
74+
## 5) Canonical Constraint (Must Remain True)
75+
76+
All autonomic operations must preserve sister independence:
77+
78+
- Each repo remains independently installable and operable.
79+
- No hard runtime dependency between sisters.
80+
- Cross-sister integration remains optional adapter behavior.
81+
- Missing sister components must degrade gracefully, never block core operation.
82+
83+
This constraint is canonical for all future implementation work.

‎docs/internal/CANONICAL_ECOSYSTEM_INDEPENDENCE_CONTRACT.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Canonical Ecosystem Independence Contract
2+
3+
Date ratified: 2026-02-21
4+
Scope: AgenticMemory, AgenticVision, AgenticCodebase
5+
Status: Canonical (normative)
6+
7+
## Purpose
8+
9+
Preserve modular adoption while autonomic operations are introduced.
10+
11+
Users must be able to install and run any single sister project without
12+
requiring the others.
13+
14+
## Relationship to Sister Kit
15+
16+
This independence contract is one part of the broader canonical sister standard.
17+
For all current and future sisters, the full operational baseline lives in:
18+
19+
- `docs/ecosystem/CANONICAL_SISTER_KIT.md`
20+
21+
That file defines the cross-repo requirements for:
22+
23+
- release artifact naming and composition
24+
- install contract and fallback behavior
25+
- reusable CI guardrails
26+
- README canonical layout
27+
- MCP canonical profile
28+
- packaging readiness policy
29+
- versioning and release policy
30+
- design asset contract
31+
- environment variable namespace contract
32+
- new-sister bootstrap requirements
33+
34+
## Canonical Rules (MUST)
35+
36+
1. Each sister MUST remain independently installable and operable.
37+
2. No sister MAY require another sister as a hard runtime dependency.
38+
3. Cross-sister integration MUST be optional adapter behavior.
39+
4. Default autonomic ops MUST run locally within each repo boundary.
40+
5. Feature parity MAY differ, but lifecycle ownership MUST be local-first.
41+
6. If a sister is missing, the running sister MUST degrade gracefully, not fail.
42+
7. Packaging and install UX MUST keep single-project setup as first-class.
43+
8. Migration, backup, and maintenance policies MUST be repo-local by default.
44+
9. Any future unified OS layer MUST NOT break standalone mode.
45+
10. Public docs MUST state standalone support explicitly.
46+
47+
## Canonical Rules (SHOULD)
48+
49+
1. Shared policy vocabulary should be reused across sisters (`tier`, `sleep-cycle`, `backup`, `migrate`).
50+
2. Health reporting should expose the same concepts in all sisters.
51+
3. Optional adapters should be capability-detected, not config-fragile.
52+
53+
## User Promise
54+
55+
Users can:
56+
57+
- Install only AgenticMemory, only AgenticVision, or only AgenticCodebase.
58+
- Get autonomic lifecycle benefits in that single project.
59+
- Add other sisters later without re-architecting existing usage.
60+
61+
## Design Implication for Autonomic Ops
62+
63+
Autonomic ops is implemented as:
64+
65+
- Local policy engine per sister
66+
- Local scheduler/sleep-cycle per sister
67+
- Local backup and migration strategy per sister
68+
69+
Optional cross-sister coordination can be added later through adapters,
70+
but it is never required for baseline reliability.
71+
72+
## Change Control
73+
74+
Any proposal that violates independent installability requires explicit written
75+
approval and a migration plan that preserves standalone behavior.
76+
77+
## Conformance Checklist (for PRs and future models)
78+
79+
- Does this introduce a hard dependency on another sister at runtime?
80+
- Can a user still install and run this project alone?
81+
- Does failure of another sister break this one?
82+
- Are lifecycle tasks still executable in standalone mode?
83+
- Is the README still clear about standalone support?
84+
85+
If any answer is negative, the change is non-conformant.

0 commit comments

Comments
 (0)