Audit stale specialist runtime guidance

--- Build: pass | Tests: pass — 2162 passed (630 files)
2026-05-05 20:00:33 +02:00 · 2026-05-05 20:00:33 +02:00 · 485286604a
commit 485286604a
parent e52eb42e00
1 changed files with 155 additions and 0 deletions
--- a/docs/internal/STALE-SPECIALIST-AUDIT.md
+++ b/docs/internal/STALE-SPECIALIST-AUDIT.md
@ -0,0 +1,155 @@
+# Stale Specialist Knowledge Audit
+
+**Date:** 05.maj.2026  
+**Scope:** specialist skills and internal docs that can leak outdated runtime
+architecture into user-visible answers or operator guidance.
+
+## Current runtime truths
+
+These are the facts the audit uses as source of truth:
+
+- `DB_RUNTIME=host` is the default, not jail.
+  - [src/config.ts](/home/clawdie/clawdie-ai/src/config.ts:695)
+  - [setup/db.ts](/home/clawdie/clawdie-ai/setup/db.ts:4)
+- When `DB_RUNTIME=host`, jails reach PostgreSQL on `${SUBNET_BASE}.1`.
+  - [src/config.ts](/home/clawdie/clawdie-ai/src/config.ts:706)
+- `DB_RUNTIME=jail` is legacy / optional.
+  - [setup/db.ts](/home/clawdie/clawdie-ai/setup/db.ts:7)
+- Current additive-tenant / platform naming uses `system_brain` for the root
+  platform memory DB, not `clawdie_brain`.
+  - [src/config.ts](/home/clawdie/clawdie-ai/src/config.ts:691)
+- Current optional db jail path uses the current jail registry model, not the
+  old `10.0.1.x` controlplane/db jail layout.
+
+## Findings
+
+### 1. `.agent/skills/debug/SKILL.md`
+
+**Severity:** High  
+**Risk:** high operator breakage and high chance of wrong user-visible answers if
+this skill is used as a live explainer.
+
+#### Why it is stale
+
+- Hardcodes a retired controlplane jail model:
+  - `clawdie-controlplane jail (10.0.1.2)`
+  - `db jail (10.0.1.3)`
+  - [`.agent/skills/debug/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/debug/SKILL.md:14)
+- Hardcodes the wrong memory DB identity:
+  - `clawdie_brain`
+  - [`.agent/skills/debug/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/debug/SKILL.md:22)
+- Assumes service lifecycle happens inside a Bastille controlplane jail:
+  - repeated `sudo bastille cmd clawdie-controlplane ...`
+  - [`.agent/skills/debug/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/debug/SKILL.md:42)
+- Hardcodes the old `pi` path:
+  - `/opt/npm/bin/pi`
+  - [`.agent/skills/debug/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/debug/SKILL.md:111)
+- That conflicts with the current host launcher fallback in:
+  - [scripts/glass.sh](/home/clawdie/clawdie-ai/scripts/glass.sh:70)
+
+#### What current truth should replace it
+
+- Root runtime is host-led, not a `clawdie-controlplane` Bastille jail.
+- The default PostgreSQL path is host runtime with `DB_RUNTIME=host`.
+- The root platform memory DB is platform-owned (`system_brain`), not
+  `clawdie_brain`.
+- `pi` path must be treated as configurable (`PI_TUI_BIN`) with host-local
+  fallback, not hardcoded to `/opt/npm/bin/pi`.
+
+#### Recommendation
+
+- Do not use this skill for delegation in its current form.
+- Mark it as historical / rewrite-required.
+- Rewrite around the current host runtime, current DB naming, and current
+  configurable `pi` path before re-enabling it as a general debugging source.
+
+### 2. `.agent/skills/postgres-memory/SKILL.md`
+
+**Severity:** Medium  
+**Risk:** medium operator confusion; lower risk of spontaneous bad answers than
+`debug`, but still misstates the preferred runtime path.
+
+#### Why it is stale
+
+- Frontmatter still describes PostgreSQL memory as a dedicated FreeBSD jail:
+  - [`.agent/skills/postgres-memory/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/postgres-memory/SKILL.md:3)
+- Body presents jail mode as the canonical first-install flow:
+  - [`.agent/skills/postgres-memory/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/postgres-memory/SKILL.md:12)
+  - [`.agent/skills/postgres-memory/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/postgres-memory/SKILL.md:62)
+- It references a non-existent automation path:
+  - `infra/ansible/playbooks/db-memory-bootstrap.yaml`
+  - [`.agent/skills/postgres-memory/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/postgres-memory/SKILL.md:97)
+  - file check on current branch: missing
+
+#### What current truth should replace it
+
+- Host PostgreSQL is the default path.
+- Jail PostgreSQL is legacy / optional for installs that explicitly choose
+  `DB_RUNTIME=jail`.
+- This skill can still be useful, but only as an install-mode-specific guide
+  for the optional jail path.
+
+#### Recommendation
+
+- Narrow this skill explicitly to `DB_RUNTIME=jail`.
+- Do not let it act as the general explanation source for “how memory works”.
+- Remove or replace the missing Ansible handoff reference.
+
+### 3. `docs/internal/POSTGRES-MEMORY.md`
+
+**Severity:** Medium  
+**Risk:** medium. This is not as broken as `debug`, but it still describes the
+wrong default mode and old jail-specific details.
+
+#### Why it is stale
+
+- It states the wrong default:
+  - `Default: dedicated FreeBSD jail`
+  - `Optional: host-based PostgreSQL`
+  - [docs/internal/POSTGRES-MEMORY.md](/home/clawdie/clawdie-ai/docs/internal/POSTGRES-MEMORY.md:7)
+- It still presents jail-specific `.3` addressing as canonical:
+  - [docs/internal/POSTGRES-MEMORY.md](/home/clawdie/clawdie-ai/docs/internal/POSTGRES-MEMORY.md:24)
+  - [docs/internal/POSTGRES-MEMORY.md](/home/clawdie/clawdie-ai/docs/internal/POSTGRES-MEMORY.md:73)
+- It still uses pre-platform DB naming examples:
+  - `clawdie_skills`
+  - `clawdie_brain`
+  - [docs/internal/POSTGRES-MEMORY.md](/home/clawdie/clawdie-ai/docs/internal/POSTGRES-MEMORY.md:159)
+  - [docs/internal/POSTGRES-MEMORY.md](/home/clawdie/clawdie-ai/docs/internal/POSTGRES-MEMORY.md:166)
+
+#### What current truth should replace it
+
+- Host PostgreSQL should be described as the default install path.
+- Optional db jail should be described as secondary / legacy.
+- Examples should be updated to platform-owned naming where applicable.
+- The doc should stop being treated as a live architecture explainer until the
+  default-mode section is corrected.
+
+#### Recommendation
+
+- Rewrite the decision section first.
+- Then update IP and naming examples to current host-default/platform-default
+  behavior.
+
+## Cross-file mismatch
+
+### `pi` binary path
+
+- `debug` skill says `/opt/npm/bin/pi`
+  - [`.agent/skills/debug/SKILL.md`](/home/clawdie/clawdie-ai/.agent/skills/debug/SKILL.md:111)
+- current host launcher resolves:
+  - `PI_TUI_BIN`
+  - fallback `/home/clawdie/.npm-global/bin/pi`
+  - [scripts/glass.sh](/home/clawdie/clawdie-ai/scripts/glass.sh:68)
+
+**Recommendation:** treat `PI_TUI_BIN` as the source of truth everywhere and
+remove hardcoded path claims from specialist docs.
+
+## Proposed next actions
+
+1. Rewrite `.agent/skills/debug/SKILL.md` or temporarily exclude it from live
+   delegation.
+2. Narrow `.agent/skills/postgres-memory/SKILL.md` to optional jail installs
+   only.
+3. Rewrite the top of `docs/internal/POSTGRES-MEMORY.md` so host runtime is the
+   documented default.
+4. Replace hardcoded `pi` paths in specialist docs with `PI_TUI_BIN` guidance.