ThothII/docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md

Workspace Diagnostic Contract Extension Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task.

Goal: Make workspace connector diagnostics executable without weakening least privilege or storing secrets in Git.

Architecture: Extend the canonical descriptor with vector database/schema identity, optional writer-only bindings, and declared REST/embedding diagnostic contracts. The backend resolves only local *_FILE values, uses bounded transport adapters, and runs a vector write probe only when a reversible writer RPC and a distinct local writer binding both exist.

Tech Stack: TypeScript, Zod, YAML, Fastify, native fetch, OpenSSH, Vitest.

Global Constraints

• Descriptor Git files never contain secrets; all secrets are deterministic local variables ending _FILE.
• Writer credentials are optional and distinct from reader credentials; never substitute a reader key.
• A write probe requires a declared reversible RPC, bounded cleanup in finally, and must never call an upsert-only endpoint.
• REST diagnostics use only descriptor-declared method, path, auth mode and response fields.
• SSH uses StrictHostKeyChecking=yes, a short-lived local forward, and cleanup in finally.
• Every diagnostic uses workspaceDiagnosticTimeoutMs, emits only stable redacted errors, and is tested with fakes or loopback only.

File Structure

Path	Responsibility
backend/src/workspaces/schema.ts	Canonical vector identity and diagnostics contracts.
backend/src/workspaces/contracts.ts	Reader/writer variable names and .env.example documentation.
backend/src/workspaces/runtime-renderer.ts	Renders vector database and schema, not DWH identity.
backend/src/workspaces/diagnostics.ts	Bounded direct/REST/SSH/vector/embedding adapters.
backend/test/workspaces-{schema,contracts,diagnostics}.test.ts	TDD coverage for validation, protocol and cleanup.
docs/workspace-diagnostic-protocol.md	Service-operator protocol and local variable contract.

Task 1: Define canonical diagnostic contracts

Files: modify backend/src/workspaces/schema.ts, backend/src/workspaces/contracts.ts, backend/src/workspaces/runtime-renderer.ts; test backend/test/workspaces-schema.test.ts, backend/test/workspaces-contracts.test.ts.

• Write failing tests that reject blank vector_store.database/schema, render their distinct values, and generate VECTOR_WRITER_*_FILE only for an optional vector_writer role.
• Run npx vitest run test/workspaces-schema.test.ts test/workspaces-contracts.test.ts and observe failure.
• Implement vector_store.database, vector_store.schema, optional vector_writer, diagnostics.dwh_rest, diagnostics.vector_rest (metadata plus optional reversible probe), and diagnostics.embedding, all strictly validated. Keep reader-only workspace valid.
• Re-run focused tests and npx tsc --noEmit -p ..
• Commit feat: define workspace diagnostic contracts.

Task 2: Implement declared bounded diagnostics

Files: modify backend/src/workspaces/diagnostics.ts; test backend/test/workspaces-diagnostics.test.ts.

• Write failing faked-transport tests for POST /rpc/ping, vector metadata dimensions/metric/collection, reader-only non-write activation, writer probe cleanup after timeout, direct/SSH declared vector database/schema, strict SSH known-host arguments, and redacted malformed response/timeout errors.
• Run npx vitest run test/workspaces-diagnostics.test.ts and observe failure.
• Implement production adapters using descriptor-declared contracts only, AbortController timeouts, injected direct-protocol and SSH process factories, local secret files, and bounded finally cleanup after a successful writer probe.
• Run focused diagnostics, npx vitest run, and npx tsc --noEmit -p ..
• Commit feat: run bounded workspace connector diagnostics.

Task 3: Specify installation and server protocols

Files: create docs/workspace-diagnostic-protocol.md; modify docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md; test backend/test/workspaces-contracts.test.ts.

• Write a failing documentation-contract test that writer workspaces render the writer _FILE variables.
• Run npx vitest run test/workspaces-contracts.test.ts and observe failure.
• Document request/response requirements for DWH ping, vector metadata, reversible writer probe, embedding dimensions, SSH known-hosts, reader-only fallback, and every local variable name.
• Run npx vitest run && npx tsc --noEmit -p . && git diff --check.
• Commit docs: specify workspace diagnostic protocols.