@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/active-learning-loop/cli-commands.md

@@ -0,0 +1,320 @@
+# CLI reference — Active Learning Loop
+
+> Four new verbs. Each section covers the full contract: flags, behavior, exit codes, output examples.
+
+---
+
+## `aioson context:load`
+
+Records that an agent loaded a rule or brain. Writes a `rule_loaded` or `brain_loaded` event to `execution_events`.
+
+**Tier:** 1 (silent — no output by default)
+
+```
+aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [options]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--target=<type>:<slug>` | yes | Type (`rule` or `brain`) and identifier. Ex: `rule:authn-rules`, `brain:sheldon-005` |
+| `--agent=<name>` | yes | Name of the loading agent. Ex: `dev`, `qa`, `sheldon` |
+| `--batch="a,b,c"` | no | Additional slugs to record in batch (same type and agent). Comma-separated |
+| `--feature=<slug>` | no | Associated feature (for traceability in `execution_events`) |
+| `--verbose` | no | Prints confirmation for each recorded event |
+| `--json` | no | JSON output (`{ ok, event, target, agent }`) |
+
+### Behavior
+
+- Creates a row in `execution_events` with `event_type='rule_loaded'` or `event_type='brain_loaded'`, `payload_json` containing `target_slug`, `agent`, `feature_slug` (if provided).
+- `--batch="b,c"` records additional events for slugs `b` and `c` with the same type as the primary `--target`.
+- Payload cap: 4KB per event.
+- Cross-platform path normalization: slugs are normalized before writing.
+- Does not validate whether the rule/brain file exists — it's pure telemetry.
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Event(s) recorded successfully |
+| 1 | Argument error (malformed target, missing agent) |
+
+### Examples
+
+```bash
+# Basic
+aioson context:load --target=rule:authn-rules --agent=dev
+
+# Batch of 3 rules + verbose
+aioson context:load --target=rule:authn-rules --agent=dev \
+  --batch="jwt-patterns,session-management" --verbose
+
+# Associated with feature + JSON
+aioson context:load --target=brain:sheldon-006 --agent=sheldon \
+  --feature=authn-flow --json
+```
+
+---
+
+## `aioson memory:search`
+
+BM25 search over `project_learnings` (title + evidence) via SQLite FTS5.
+
+**Tier:** 1 (silent — does not emit notify)
+
+```
+aioson memory:search "<query>" [path] [options]
+```
+
+### Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `"<query>"` | — (required) | Search text. Maximum 500 characters |
+| `path` | `.` | Project root directory |
+| `--limit=N` | 5 | Maximum number of results |
+| `--surface=<value>` | `learnings` | Where to search: `rules`, `learnings`, or `all` |
+| `--include-archived` | false | Includes entries with `archived` status |
+| `--json` | false | JSON output |
+
+### Behavior and query sanitization
+
+Each token (whitespace-separated) is converted to a quoted phrase and ANDed with the others:
+
+```
+"JWT authentication"  →  '"JWT" "authentication"'
+```
+
+FTS5 operator characters (`* ( ) ^ : + - "`) are stripped before conversion. If after sanitization the query results in an empty string, the command returns `{ ok: false, reason: 'query_unparseable' }` with exit code 0 (not an error — expected behavior).
+
+Archived entries are excluded by default; `--include-archived` includes them.
+
+Ranking: BM25 (lower score = more relevant).
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Search executed (even with no results) |
+| 1 | Argument error or DB failure |
+
+### Output examples
+
+```bash
+aioson memory:search "JWT authentication"
+```
+
+```
+2 results for "JWT authentication"
+
+[1] authn-refresh-token-ttl  (promoted)
+    Refresh tokens must have a 7-day max TTL.
+    Evidence: 4 sessions
+
+[2] jwt-audience-check  (for_review)
+    Validate 'aud' claim on all endpoints.
+    Evidence: 2 sessions
+```
+
+No results:
+
+```
+0 results for "xyzzy"
+```
+
+Unparseable query:
+
+```json
+{ "ok": false, "reason": "query_unparseable" }
+```
+
+Full JSON output:
+
+```json
+{
+  "ok": true,
+  "query": "JWT authentication",
+  "sanitized_query": "\"JWT\" \"authentication\"",
+  "results": [
+    {
+      "id": "authn-refresh-token-ttl",
+      "title": "authn-refresh-token-ttl",
+      "status": "promoted",
+      "score": -2.14,
+      "snippet": "Refresh tokens must have a 7-day max TTL."
+    }
+  ],
+  "total": 2
+}
+```
+
+---
+
+## `aioson memory:archive`
+
+Archives a rule, learning, or brain: moves the physical file to `_archived/YYYY-MM-DD/` and records the history in `evolution_log`.
+
+**Tier:** 2 (notified — emits `notify --level=warn` before mutation)
+
+**Human-only:** refuses when `AIOSON_RUNTIME_HOOK=1` is set.
+
+```
+aioson memory:archive [path] --id=<rule|learning|brain>:<slug> --reason="<text>" [options]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--id=<type>:<slug>` | yes | Type and slug of the target. Types: `rule`, `learning`, `brain` |
+| `--reason="<text>"` | yes | Archival reason (recorded in `evolution_log`) |
+| `--feature=<slug>` | no | Associated feature (for traceability) |
+| `--dry-run` | no | Simulates without side effects — prints what would happen |
+| `--json` | no | JSON output |
+
+### Paths by type
+
+| Type | Source | Destination |
+|---|---|---|
+| `rule` | `.aioson/rules/<slug>.md` | `.aioson/rules/_archived/YYYY-MM-DD/<slug>.md` |
+| `brain` | `.aioson/brains/<slug>.brain.json` | `.aioson/brains/_archived/YYYY-MM-DD/<slug>.brain.json` |
+| `learning` | `.aioson/context/<slug>.json` | `.aioson/context/_archived/YYYY-MM-DD/<slug>.json` |
+
+Name collision at destination: `-{seq}` suffix is added automatically (`-1`, `-2`, etc.).
+
+### Behavior
+
+1. Checks `AIOSON_RUNTIME_HOOK=1` — refuses if set.
+2. Resolves the file path. Errors if not found.
+3. Idempotent noop if already archived.
+4. Emits `notify --level=warn` before any mutation.
+5. Atomic operation: BEGIN TRANSACTION, physical move, INSERT/UPDATE in `evolution_log`, COMMIT. If COMMIT fails, attempts to reverse the physical move.
+6. Records `event_type='archived'` in `evolution_log` (previous active entry receives `end_at`).
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Archived successfully (or noop if already archived) |
+| 0 | `--dry-run` executed |
+| 1 | Target not found, AIOSON_RUNTIME_HOOK=1, DB or FS failure |
+
+### Examples
+
+```bash
+# Dry-run first
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="replaced by JWT auth (authn-flow)" --dry-run
+
+# Real execution
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="replaced by JWT auth (authn-flow)"
+
+# With associated feature
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="replaced by JWT auth (authn-flow)" --feature=authn-flow
+
+# JSON
+aioson memory:archive --id=rule:legacy-session-cookies \
+  --reason="obsolete" --json
+```
+
+JSON output:
+
+```json
+{
+  "ok": true,
+  "action": "archived",
+  "type": "rule",
+  "slug": "legacy-session-cookies",
+  "source": ".aioson/rules/legacy-session-cookies.md",
+  "dest": ".aioson/rules/_archived/2026-05-14/legacy-session-cookies.md",
+  "evolution_log_rowid": 42
+}
+```
+
+---
+
+## `aioson memory:restore`
+
+Restores an archived item: moves it back to the original path and records `event_type='restored'` in `evolution_log`.
+
+**Tier:** 2 (notified — emits `notify --level=warn` before mutation)
+
+**Human-only:** refuses when `AIOSON_RUNTIME_HOOK=1` is set.
+
+```
+aioson memory:restore [path] --id=<rule|learning|brain>:<slug> [options]
+```
+
+### Flags
+
+| Flag | Required | Description |
+|---|---|---|
+| `--id=<type>:<slug>` | yes | Type and slug of the item to restore |
+| `--reason="<text>"` | no | Restoration reason (recorded in `evolution_log`) |
+| `--feature=<slug>` | no | Associated feature (for traceability) |
+| `--dry-run` | no | Simulates without side effects |
+| `--json` | no | JSON output |
+
+### Behavior
+
+1. Locates the most recent file in `_archived/*/` matching the slug.
+2. Verifies that the original destination path is available — errors if a file already exists there.
+3. Emits `notify --level=warn` before any mutation.
+4. Atomic operation: physical move + INSERT `event_type='restored'` + UPDATE `end_at` of the active `archived` entry.
+
+### Exit codes
+
+| Code | When |
+|---|---|
+| 0 | Restored successfully |
+| 0 | `--dry-run` executed |
+| 1 | Item not found in `_archived/`, original path already occupied, AIOSON_RUNTIME_HOOK=1 |
+
+### Examples
+
+```bash
+# Dry-run
+aioson memory:restore --id=rule:rate-limiting-rules --dry-run
+
+# Real execution with reason
+aioson memory:restore --id=rule:rate-limiting-rules \
+  --reason="rule still needed — removal was premature"
+
+# JSON
+aioson memory:restore --id=rule:rate-limiting-rules --json
+```
+
+---
+
+## `aioson feature:close` (modified)
+
+The existing `feature:close` command gained a distillation hook at the end. The syntax has not changed — only `--no-distill` was added.
+
+```
+aioson feature:close --slug=<slug> --verdict=<PASS|FAIL|ABANDONED> [--no-distill]
+```
+
+### Added flag
+
+| Flag | Description |
+|---|---|
+| `--no-distill` | Skips the distillation hook for this call (does not permanently alter config) |
+
+### Hook behavior
+
+- Only runs when `--verdict=PASS` and classification is not MICRO.
+- Foreground with 5s timeout (configurable in `learning-loop.json`).
+- Exit code always 0, even if distillation fails.
+- Emits exactly 1 notify `--level=info --topic=learning-loop` with the summary.
+- Records result in `evolution_log` (`auto_distillation` or `distillation_failed`).
+
+---
+
+## Continue reading
+
+- [How to use](./how-to-use.md) — end-to-end examples
+- [Doctor checks](./doctor-checks.md) — what the doctor checks mean
+- [Troubleshooting](./troubleshooting.md) — known issues

package/docs/en/active-learning-loop/diagrams.md

@@ -0,0 +1,225 @@
+# Diagrams — Active Learning Loop in ASCII
+
+> Canonical flows for the feature. ASCII because it renders in any terminal, any Markdown viewer, and any diff.
+
+---
+
+## 1. `feature:close` → distillation → `evolution_log` → `doctor`
+
+```
+aioson feature:close --slug=my-feature --verdict=PASS
+  │
+  ├── [existing] gate validation
+  ├── [existing] dossier finalize
+  ├── [existing] features.md update
+  │
+  └── [NEW] runHookOnFeatureClose()
+        │
+        ├── Read PRD frontmatter classification
+        │   └── MICRO? → notify "skipped: MICRO classification" → exit 0
+        │
+        ├── Read features.md status
+        │   └── abandoned? → silent skip → exit 0
+        │
+        ├── --no-distill passed? → skip → exit 0
+        │
+        ├── Attempt to acquire lock:
+        │   INSERT INTO evolution_log
+        │     (feature_slug='my-feature', event_type='auto_distillation',
+        │      start_at=now(), end_at=NULL, actor='auto', payload='{"state":"start"}')
+        │   └── active row already exists? → notify "already in progress" → exit 0
+        │
+        ├── setTimeout(5000ms) → AbortController.abort()
+        │
+        ├── try {
+        │     learning:auto-promote --feature=my-feature
+        │       └── returns { promoted: N, for_review: M }
+        │   }
+        │   catch (err) {
+        │     UPDATE evolution_log SET event_type='distillation_failed',
+        │       end_at=now(), payload='{"error":"...", "phase":"auto-promote"}'
+        │     // swallow exception — do not rethrow
+        │   }
+        │
+        ├── UPDATE evolution_log SET end_at=now(),
+        │     payload='{"state":"complete","promoted":N,"review":M,"merge":0,"duration_ms":D}'
+        │
+        ├── aioson notify --level=info --topic=learning-loop
+        │     --message="distillation: N promoted, M for review, 0 merge candidates"
+        │
+        └── exit 0  ← always 0, regardless of distillation failure
+```
+
+---
+
+## 2. Lock pattern (DD-3 — two simultaneous terminals)
+
+```
+Terminal A                              Terminal B
+──────────────────────────────────      ──────────────────────────────────
+feature:close --slug=X                  feature:close --slug=X (simultaneous)
+
+SELECT 1 FROM evolution_log
+  WHERE feature_slug='X'
+    AND event_type='auto_distillation'
+    AND end_at IS NULL
+  → 0 rows
+
+INSERT row (end_at=NULL) → rowid=42
+                                        SELECT 1 ... → 1 row (rowid=42)
+                                        notify "already in progress" → exit 0
+
+(distillation runs ~2-3s)
+
+UPDATE rowid=42 SET end_at=now()
+notify "N promoted, M for review"
+exit 0
+```
+
+---
+
+## 3. `memory:archive` — atomic operation with rollback
+
+```
+aioson memory:archive --id=rule:authn --reason="obsolete after OAuth"
+  │
+  ├── Check AIOSON_RUNTIME_HOOK=1 → refuse (tier-2 human-only)
+  │
+  ├── Resolve path: .aioson/rules/authn.md
+  │   └── not found? → error: "target not found"
+  │
+  ├── Already archived? → noop (idempotent)
+  │
+  ├── aioson notify --level=warn --topic=memory-archive
+  │     --message="archiving rule:authn — authn.md"
+  │
+  ├── BEGIN TRANSACTION (SQLite)
+  │
+  ├── physical move:
+  │   .aioson/rules/authn.md
+  │     → .aioson/rules/_archived/2026-05-14/authn.md
+  │   └── move error → ROLLBACK → exit 1
+  │
+  ├── INSERT evolution_log (event_type='archived', start_at=now(), end_at=NULL,
+  │     target_type='rule', target_id='authn', reason='obsolete after OAuth',
+  │     actor='human', feature_slug=<--feature if passed>)
+  │
+  ├── UPDATE evolution_log SET end_at=now()
+  │     WHERE target_id='authn' AND end_at IS NULL AND event_type != 'archived'
+  │   (closes previous active entry)
+  │
+  ├── COMMIT
+  │   └── COMMIT error → attempt to reverse physical move → exit 1
+  │
+  └── { ok: true, path: "_archived/2026-05-14/authn.md" }
+```
+
+---
+
+## 4. `doctor` cycle with the new checks
+
+```
+$ aioson doctor .
+        │
+        ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ runDoctor(targetDir)                                             │
+│  └─ checks[]                                                     │
+│      ├─ ... [existing checks severity='error'] ...               │
+│      ├─ living-memory:bootstrap_coverage   [severity: warning]   │
+│      ├─ living-memory:features_dir         [severity: warning]   │
+│      ├─ living-memory:claude_commands      [severity: warning]   │
+│      ├─ living-memory:version_drift        [severity: warning]   │
+│      ├─ living-memory:permissions_in_sync  [severity: warning]   │
+│      │                                                           │
+│      ├─ [NEW] living-memory:rule_staleness   [severity: warning] │
+│      │    └─ query: execution_events WHERE event_type='rule_loaded'
+│      │           AND context LIKE 'feature=%' GROUP BY slug
+│      │           → stale if no hit in last N features            │
+│      │                                                           │
+│      ├─ [NEW] living-memory:learning_orphans [severity: warning] │
+│      │    └─ query: project_learnings WHERE status='promoted'    │
+│      │           LEFT JOIN execution_events (rule_loaded, after  │
+│      │           promoted_at) → orphan if join returns NULL      │
+│      │                                                           │
+│      └─ [NEW] living-memory:distillation_lag [severity: warning] │
+│           └─ count(closed features) vs count(auto_distillation   │
+│              in evolution_log) → lag if closed > distillations   │
+│                                                                  │
+│  report.ok = errorCount === 0                                    │
+│  (warnings count in failedCount but do not affect ok)            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Validity-window in `evolution_log`
+
+```
+Initial state (active rule):
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | NULL   ← active
+
+memory:archive runs:
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | 2026-05-14  ← closed
+   2   |   'rule'    |  'authn'  |  'archived'| 2026-05-14 | NULL        ← active
+
+memory:restore runs:
+─────────────────────────────────────────────────────────────────
+ rowid | target_type | target_id | event_type | start_at   | end_at
+   1   |   'rule'    |  'authn'  |  'created' | 2026-01-10 | 2026-05-14
+   2   |   'rule'    |  'authn'  |  'archived'| 2026-05-14 | 2026-05-14  ← closed
+   3   |   'rule'    |  'authn'  |  'restored'| 2026-05-14 | NULL        ← active
+
+Invariant: start_at and reason never change after INSERT.
+           Only end_at is updated, and only once.
+```
+
+---
+
+## 6. FTS5 — sync flow and search
+
+```
+project_learnings (normal table)
+        │
+        │ SQL triggers (INSERT, UPDATE, DELETE)
+        ▼
+project_learnings_fts (FTS5 virtual table)
+   indexed columns: title, evidence
+   ranking: BM25 (default)
+        │
+        │ aioson memory:search "JWT authentication"
+        ▼
+  Query sanitization:
+    input:  "JWT authentication"
+    tokens: ["JWT", "authentication"]
+    FTS5:   '"JWT" "authentication"'  ← token-AND, each token is a literal phrase
+        │
+        ▼
+  SELECT l.*, fts.rank
+  FROM project_learnings_fts fts
+  JOIN project_learnings l ON l.rowid = fts.rowid
+  WHERE fts MATCH '"JWT" "authentication"'
+    AND l.status != 'archived'   ← excluded by default
+  ORDER BY fts.rank              ← BM25 (lower = more relevant)
+  LIMIT 5
+        │
+        ▼
+  Result:
+  [1] jwt-refresh-token-ttl (score: -2.14)
+      "Refresh JWT tokens must have a 7-day TTL..."
+  [2] jwt-audience-validation (score: -1.87)
+      ...
+```
+
+---
+
+## Continue reading
+
+- [What is the Active Learning Loop](./active-learning-loop.md) — concept and phases
+- [How to use](./how-to-use.md) — concrete examples
+- [Doctor checks](./doctor-checks.md) — what the checks mean
+- [Troubleshooting](./troubleshooting.md) — known issues

package/docs/en/active-learning-loop/doctor-checks.md

@@ -0,0 +1,151 @@
+# Doctor checks — memory curation
+
+> The three new checks appear in `aioson doctor .` with `severity='warning'`. Warnings do not affect `ok=true` — the project keeps working. But each one represents a curation gap that, if ignored, makes project memory less useful over time.
+
+---
+
+## How the checks appear
+
+```bash
+aioson doctor .
+```
+
+When everything is healthy:
+
+```
+[OK] living-memory:rule_staleness
+[OK] living-memory:learning_orphans
+[OK] living-memory:distillation_lag
+```
+
+When there are gaps:
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  ...
+[WARN] living-memory:learning_orphans (1 orphan)
+  ...
+[WARN] living-memory:distillation_lag
+  ...
+```
+
+All three checks only run on projects with **SMALL** or **MEDIUM** classification. MICRO projects opt out automatically — none of the three will appear.
+
+---
+
+## `living-memory:rule_staleness`
+
+**What it detects:** rules (files in `.aioson/rules/`) with zero `rule_loaded` events in the last N closed features.
+
+**Why it matters:** if no agent loaded a rule in the last N features, it has likely lost relevance — the project context changed, the rule was superseded, or it was simply never used. Stale rules occupy space in agents' context windows without adding value.
+
+**How N is calculated:**
+
+```
+N = max(5, ceil(average days between last 5 features / 7))
+```
+
+Projects with frequent features (1 per week) get N = 5. Projects with a slower pace (1 per month) get a larger N — the window expands to cover the same real period of time.
+
+`staleness_window_features_min: 5` in `learning-loop.json` defines the floor.
+
+**Typical output:**
+
+```
+[WARN] living-memory:rule_staleness (2 stale rules)
+  Rule 'legacy-session-cookies' has 0 rule_loaded events in last 7 features.
+  Rule 'old-rate-limit-policy' has 0 rule_loaded events in last 7 features.
+  Hint:
+    aioson memory:archive --id=rule:legacy-session-cookies --reason="<reason>"
+    aioson memory:archive --id=rule:old-rate-limit-policy --reason="<reason>"
+```
+
+**How to act:**
+
+1. Check if the rule is still relevant to the current project.
+2. If not: use the doctor's hint to archive it.
+3. If still relevant but not being loaded: add `context:load` to the agents that should use it.
+4. If unsure: archive with `--dry-run` to see the impact before executing.
+
+**False positive:** the check only works when agents are using `aioson context:load` to declare loads. If your custom agents don't do this, the check will report everything as stale. Solution: add `aioson context:load` to the beginning of sessions.
+
+---
+
+## `living-memory:learning_orphans`
+
+**What it detects:** learnings with `status='promoted'` whose target rule had no `rule_loaded` events after the promotion date.
+
+**Why it matters:** when a learning is promoted, it generated (or should have generated) a rule. If that rule was never loaded by any agent since the promotion, it means one of two things: either the rule was never actually created (a failure in the promotion flow), or it was created but agents aren't consulting it. Either way, it's a gap.
+
+**Typical output:**
+
+```
+[WARN] living-memory:learning_orphans (1 orphan)
+  Learning 'jwt-expiry-pattern' (promoted 2026-04-10) — target rule had no
+  rule_loaded events after promotion date.
+  Hint:
+    aioson memory:archive --id=learning:jwt-expiry-pattern --reason="<reason>"
+```
+
+**How to act:**
+
+1. Check if the corresponding rule exists in `.aioson/rules/`.
+2. If the rule doesn't exist: the learning was promoted but never materialized a rule — create the rule manually or archive the learning.
+3. If the rule exists but was never loaded: add `context:load` where appropriate, or archive the rule if it's no longer relevant.
+4. If the learning was promoted by mistake: archive it.
+
+---
+
+## `living-memory:distillation_lag`
+
+**What it detects:** projects where the number of closed features significantly exceeds the number of `auto_distillation` events recorded in `evolution_log`. Threshold: 5+ features closed with fewer distillations than closures.
+
+**Why it matters:** if `feature:close` is being called but distillation isn't running, the loop is silently broken. Learnings are accumulating without distillation. It may be that `--no-distill` is being used consistently, that the hook is failing silently, or that the project migrated to the framework after closing several features.
+
+**Typical output:**
+
+```
+[WARN] living-memory:distillation_lag
+  8 features closed, 5 auto_distillation events recorded.
+  Hint: check if distillation is failing silently:
+    sqlite3 .aioson/runtime/aios.sqlite \
+      "SELECT feature_slug, payload_json FROM evolution_log \
+       WHERE event_type='distillation_failed' ORDER BY start_at DESC LIMIT 5;"
+  Or run distillation manually on recent features.
+```
+
+**How to act:**
+
+1. Run the SQLite command from the hint to see if there are recorded silent failures.
+2. If there are `distillation_failed` entries: check `payload_json.error_phase` to understand where it's failing and consult [Troubleshooting](./troubleshooting.md).
+3. If there are no failures but there is lag: features were probably closed with `--no-distill` or before the hook existed. The lag will decrease naturally as new features are closed.
+4. If the project is new to the framework but had old features: the lag is expected and will resolve itself.
+
+---
+
+## Quick summary
+
+| Check | Problematic signal | Immediate action |
+|---|---|---|
+| `rule_staleness` | Rule with no `rule_loaded` in N features | Check relevance → archive or add `context:load` |
+| `learning_orphans` | Promoted learning, rule never loaded | Check if rule exists → create, archive learning, or add `context:load` |
+| `distillation_lag` | More features closed than distillations | Inspect `distillation_failed` in `evolution_log` |
+
+---
+
+## About `warning` severity
+
+The three checks have `severity='warning'`, not `severity='error'`. This means:
+
+- `report.ok` remains `true` even with warnings.
+- `report.failedCount` includes warnings.
+- There is no automatic `doctor --fix` for these checks — the actions are semantic and require human judgment.
+- The hint for each check includes the exact command to run when you decide to act.
+
+---
+
+## Continue reading
+
+- [How to use](./how-to-use.md) — examples of archive and restore
+- [CLI reference](./cli-commands.md) — flags for `memory:archive` and `memory:restore`
+- [Troubleshooting](./troubleshooting.md) — stuck lock, distillation failures