ThothII/docs/superpowers/specs/2026-08-20-workspace-install-docs-fixture-self-containment-design.md

Workspace Install Docs Fixture Self-Containment — Design

Date: 2026-08-20

Status: Approved for implementation

Purpose

Restore the documented direct invocation of scripts/verify-workspace-install-docs.sh so it passes in a clean environment without inheriting TMPDIR or THT_AUTH_CONFIG_ROOT from the operator. The verifier must prove that its generated local/server installation fixtures are complete by themselves.

Observed regression

Two independent gaps stop the current --fixtures-only path:

1. several mktemp calls expand TMPDIR under set -u without a default;
2. the authentication lifecycle commit made THT_AUTH_CONFIG_ROOT mandatory in compose.yaml, while the local, server, and canonical Compose fixture environments still omit it.

The failure is unrelated to the PSD checklist commits. Supplying both values externally makes the entire fixture suite pass, which confirms the missing-input boundary but is not an acceptable long-term workaround.

Scope

Modify only:

• scripts/verify-workspace-install-docs.sh
• scripts/test-verify-workspace-install-docs.sh

Do not modify Compose, authentication runtime code, documentation examples, the PSD server, Docker resources, or the legacy stack.

Required behavior

Temporary directory contract

Every mktemp call in the production verifier must use /tmp when TMPDIR is absent. An explicitly provided TMPDIR remains supported. The verifier must not mutate or export the caller's environment.

Authentication fixture contract

Each Compose-rendering fixture owns a distinct authentication configuration directory inside its fixture root:

• local installation example fixture;
• server installation example fixture;
• canonical local/server Compose fixture.

Each generated fixture environment sets THT_AUTH_CONFIG_ROOT to that directory. The directory is created before Compose rendering and contains no real credential. Tests assert that the rendered core service mounts the expected source at /run/thothii-auth read-only, so an ambient host value cannot mask an incomplete fixture.

Regression-test contract

The test runner invokes the production --fixtures-only verifier with both TMPDIR and THT_AUTH_CONFIG_ROOT explicitly absent. This test must fail on the current source for the observed reason and pass only after both self-containment gaps are fixed.

TDD sequence

1. Change only the test runner so it removes both variables for the production-verifier call.
2. Run the focused test and retain the expected RED result.
3. Add the /tmp fallback to the production verifier; rerun and confirm the remaining RED result is the missing auth root.
4. Add fixture-owned auth directories, environment entries, and rendered-mount assertions.
5. Run the focused test and direct clean-environment verifier to GREEN.
6. Run shell syntax checks, documentation smoke checks, and git diff --check.

Failure handling

• A missing fixture auth directory or environment entry fails before a PASS is printed.
• A rendered auth mount with the wrong source, target, or read-only flag fails the fixture.
• A scanner or Compose error remains an error; it is not reclassified as an expected negative.
• Temporary fixture cleanup remains bounded to paths created by mktemp.

Acceptance

All of the following must pass from the repository root:

env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
  bash scripts/verify-workspace-install-docs.sh --fixtures-only

env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
  bash scripts/test-verify-workspace-install-docs.sh

bash -n scripts/verify-workspace-install-docs.sh
bash -n scripts/test-verify-workspace-install-docs.sh
bash scripts/auth-docs-smoke.sh
git diff --check

No acceptance command starts, stops, reloads, builds, or otherwise mutates the PSD server stack.