waggle-os/docs/plans/MOCK-STUB-AUDIT-2026-04-19.md

MOCK / STUB / PLACEHOLDER Audit — 2026-04-19 (L-17)

Full-tree grep for TODO / FIXME / XXX / HACK / STUB / PLACEHOLDER / MOCK markers across packages/*/src, apps/web/src, and app/src-tauri (excluding .test.ts / .spec.ts / node_modules / dist/). Result: 19 real hits, split by category below.

Most are low-risk (self-documenting design markers or marked-demo connectors). Two genuine TODOs tie to HIGH-tier work already in the plan. One dead export was cleaned up in this commit.

Category A — Safe (design markers, not gaps)

Hit	What it is
packages/agent/src/evolution-gates.ts:17	Doc comment — explaining the gate's detection of placeholder-like patterns in generated prompts. Marker appears INSIDE a regex description, not as a real TODO.
packages/agent/src/evolution-gates.ts:261	Doc comment — the toDoFixMe gate rejects evolved prompts containing TODO: / FIXME: headers. Marker is part of the feature.
packages/agent/src/evolution-gates.ts (regex body)	Actual regex string — `^\s*(?:TODO
packages/server/src/local/routes/skills.ts:773	Template string returned to the USER when they create a new tool: 'TODO: implement'. User's responsibility to complete; not a Waggle TODO.

Action: None. These are intentional and part of shipping features.

Category B — Marked-demo connectors (Marko-aware)

packages/agent/src/connectors/mock-channel-connectors.ts — 9 MOCK: comments across 3 demo connectors:

• MockSlackConnector
• MockTeamsConnector
• MockDiscordConnector

File-header comment is explicit:

"DEMO: Mock channel connectors for testing and demo mode. Remove when real OAuth integration is ready."

Exported through packages/agent/src/connectors/index.ts and packages/agent/src/index.ts as MockSlackConnector etc. Appear in Settings → Connectors with "(Demo)" badge in their display names.

Action needed (your call):

1. Keep for launch — they're useful as demo surfaces for evaluators who don't want to wire up real OAuth. Label stays "(Demo)".
2. Gate to development-only — tier-check them out of production connector catalogs. Keep the code for dev-mode tests.
3. Delete — ship without these 3 entries. Requires replacement with real OAuth (tied to M-29 MS Graph effort) before they can reappear.

Recommendation: option 1 until real integrations land. Users see "(Demo)" affordance, know what they're getting, no production risk.

Category C — Genuine TODOs (feature gaps)

C1. packages/server/src/ws/gateway.ts:91 — Clerk JWT fallback

// TODO: Replace with full Clerk verification once CLERK_SECRET_KEY is always configured
const payload = decodeJwtPayload(token);

The WebSocket gateway currently decodes JWT payload without signature verification when CLERK_SECRET_KEY isn't set. Blocks H-36 (Clerk auth integration — already on the TO-DO list). When H-36 lands this TODO goes away.

Action: Tracked by H-36. No separate fix.

C2. packages/core/src/compliance/report-generator.ts:52 — classification date

riskClassifiedAt: null, // TODO: track classification date in workspace config

Compliance report emits riskClassifiedAt: null because the workspace config doesn't currently persist the timestamp. EU AI Act Article 14 expects "last risk classification date" in the provenance chain.

Action: add riskClassifiedAt?: string to WorkspaceConfig + set it when the Risk Level dropdown changes. ~1 hr. Fold into M-02..06 Compliance PDF block.

C3. packages/server/src/local/routes/fleet.ts:32 — per-session tokens

tokensUsed: 0, // TODO: track per-session tokens

Fleet cost report shows tokensUsed: 0 for every session because the orchestrator doesn't currently aggregate per-session token usage.

Action: add token accumulator to SessionStore schema + increment on each LLM response. ~3 hr. Priority: medium (cost visibility is a selling point, not launch-blocking).

C4. apps/web/src/components/os/apps/CapabilitiesApp.tsx:352 — marketplace dupes

{/* TODO: Marketplace tab may show duplicate data if getMarketplacePacks()
     returns same content as getSkills() — needs backend fix to serve
     distinct catalog */}

The Capabilities app's Marketplace tab may show duplicate rows because the two APIs return overlapping catalogs.

Action: verify backend returns disjoint catalogs, or de-dupe client- side by id. ~2 hr. Priority: medium (UX confusion).

C5. apps/web/src/hooks/useMemory.ts:54 — missing PATCH endpoint

// TODO: Ideally needs a dedicated PATCH /api/memory/frames/:id/access endpoint
// that atomically increments accessCount on the server. For now, we use PUT with

Memory access tracking uses PUT + full-field overwrite instead of an atomic increment. Race condition risk on concurrent frame access.

Action: add PATCH /api/memory/frames/:id/access that increments access_count atomically. ~1 hr. Priority: low — race condition is theoretical (access is per-user).

Category D — Cleanup shipped this commit

D1. Dead MOCK_FILES export (fixed)

apps/web/src/components/os/apps/files/file-utils.ts:40 — MOCK_FILES was a pre-adapter demo-seed array with 6 fake entries. Grep confirmed no consumers anywhere in apps/web/src or tests/.

Action taken: removed. FilesApp reads from adapter.getDocuments() and similar real paths; the mock array was unused since the adapter refactor.

Summary

Category	Count	Action
A. Safe design markers	4	No action
B. Marked-demo connectors	9	Your call (recommend option 1 — keep as "(Demo)")
C. Genuine TODOs	5	3 are ≤3hr fixes; 2 tie to existing H-36 / M-02..06
D. Cleanup	1	✅ Shipped (MOCK_FILES removed)

Net after this commit:

• Category A: unchanged (intentional)
• Category B: decision-blocked on Marko option 1/2/3
• Category C: 3 new backlog items (C2, C3, C4, C5 — though C1 folds into H-36)
• Category D: dead code removed

Backlog surfaces: C2 (classification date, folds into M-02..06), C3 (per-session tokens, new M-item), C4 (marketplace dedupe, new M-item), C5 (PATCH access endpoint, new L-item).

L-17 was scoped 4 hr; actual work was ~1 hr (scope turned out smaller than the HIGH-tier estimate — codebase is clean). Rest of the budget rolls back into the TO-DO list.