From 485286604af2ce245daef127f863b8f350dff9db Mon Sep 17 00:00:00 2001 From: Operator & Codex Date: Tue, 5 May 2026 20:00:33 +0200 Subject: [PATCH] Audit stale specialist runtime guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Build: pass | Tests: pass — 2162 passed (630 files) --- docs/internal/STALE-SPECIALIST-AUDIT.md | 155 ++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/internal/STALE-SPECIALIST-AUDIT.md diff --git a/docs/internal/STALE-SPECIALIST-AUDIT.md b/docs/internal/STALE-SPECIALIST-AUDIT.md new file mode 100644 index 0000000..62f6c33 --- /dev/null +++ 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.