Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
107 lines (86 loc) · 3.36 KB

ARCHITECTURE.md

File metadata and controls

107 lines (86 loc) · 3.36 KB
Raw

Imprint Architecture

Data flow, signal format, hook wiring, regeneration steps.

Hook Pipeline

SessionStart ─── health_check.py ──→ detects .stale flag → signals AI
PreToolUse ───── three-questions ──→ exit 2 if no recent pass
Stop ─────────── quality_gate.py ──→ mtime check → writes .stale flag → exit 2
                                         │
                         ┌───────────────┘
                         ▼
                  AI regenerates self-model.md
                         │
                         ▼
                  log_regeneration.py → JSONL audit → deletes flag

Data Flow

growth-log/*.md  ─┐
decisions/log.md  ├── quality_gate.py reads mtime
ratings/*.md     ─┘       │
                           ▼
              self-model.md older than latest?
                      │           │
                     NO          YES
                      │           │
                   exit 0    write .self-model-stale → exit 2
                                   │
                            Next SessionStart:
                            health_check reads flag
                            → "REGENERATE_NEEDED"
                            → AI regenerates self-model
                            → log_regeneration writes JSONL + deletes flag

File Dependency Map

SOUL.md          ← Static. You edit. Identity.
    ↓
INTERFACE.md     ← Static. Per-model calibration.
    ↓
BODY.md          ← Static. Rules + process.
    ↓
MEMORY.md        ← Semi-static. Knowledge index.
    ↓
self-model.md    ← DYNAMIC. Regenerated.
    ↑
growth-log/ + decisions/ + ratings/ + relations/

Signal Format

health_check.py (stdout, JSON):

{"signal": "SELF_MODEL:CLEAN"}
{"signal": "SELF_MODEL:REGENERATE_NEEDED"}
{"signal": "SELF_MODEL:CLEANED_ORPHAN"}

Always exit 0. Never blocks startup.

quality_gate.py (exit codes):

Code Meaning
0 Pass. Session can end.
2 Block. Self-model stale or disk critical.

log_regeneration.py (JSONL append):

{"timestamp":"...","old":"v0.4","new":"v0.5","sources":["growth-log/..."],"trigger":"flag"}

Crash-consistent: write + fsync BEFORE flag deletion.

Regeneration Protocol (5 Steps)

Step Who Action Verifiable?
1 quality_gate.py mtime comparison → write flag → exit 2 ✅ file mtime
2 health_check.py Read flag → emit signal → exit 0 ✅ stdout
3 AI Read growth-logs → synthesize self-model ❌ needs AI
4 log_regeneration.py JSONL audit → delete flag ✅ fsync + JSONL
5 self-model.md Updated file feeds into startup sequence ✅ file content

4 of 5 steps are file-system verifiable facts.

Configuration

All thresholds at script top. Open and edit:

Script Constant Default
quality_gate.py DISK_CRIT_GB 15
quality_gate.py STALE_GRACE_DAYS 1

Design Meta-Rule

"Can this be fixed retroactively?"

  • Stale identity → Block (damage already done, can't retroactively know who you were)
  • Stale growth-log → Warn (can backfill)
  • Low disk → Block (can't write = can't operate)

Boundary by reversibility, not importance.