93 lines
4.5 KiB
Markdown
93 lines
4.5 KiB
Markdown
# Tht Documentation Convergence Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Align current documentation and documentation smoke checks with the converged native host CLI `tht`, while preserving historical references only where they describe past decisions or evidence.
|
|
|
|
**Architecture:** Treat `tools/tht/cmd/tht/main.go` as the canonical host CLI surface for installation, authentication, diagnostics, lifecycle, and workspace operations. Keep the Python `harness/.venv/bin/tht` distinction explicit for the workflow runtime, and update current operator/test instructions to invoke the native `tht` with `--installation`.
|
|
|
|
**Tech Stack:** Markdown documentation, shell smoke tests, Go CLI command surface, repository search-based verification.
|
|
|
|
---
|
|
|
|
### Task 1: Classify current and historical legacy CLI references
|
|
|
|
**Files:**
|
|
- Inspect: `README.md`, `PROJECT_STATE.md`, `AGENTS.md`, `docs/**`, `scripts/**`
|
|
- Reference: `tools/tht/cmd/tht/main.go`
|
|
|
|
**Step 1:** Build a complete occurrence inventory with a case-insensitive search for the former host CLI name and classify every match.
|
|
|
|
**Step 2:** Classify each occurrence as current operator documentation, documentation smoke expectation, executable/script contract, or historical design/evidence.
|
|
|
|
**Step 3:** Record the classification in the implementation notes before editing.
|
|
|
|
### Task 2: Update canonical operator and installation documentation
|
|
|
|
**Files:**
|
|
- Modify: `README.md`
|
|
- Modify: `AGENTS.md`
|
|
- Modify: `PROJECT_STATE.md`
|
|
- Modify: `docs/guida-utente.md`
|
|
- Modify: `docs/contracts/workspace-preprocessing-cli.md`
|
|
- Rename/update: `docs/contracts/tht-pi.md` as the current `tht` Pi contract
|
|
- Modify: relevant installation and architecture pages that expose operator commands
|
|
|
|
**Step 1:** Replace current host/operator invocations with `tht --installation ...`.
|
|
|
|
**Step 2:** Document the distinction between the native host CLI `tht` and the Python harness CLI invoked by the backend/runtime.
|
|
|
|
**Step 3:** Update command examples for `start`, `status`, `doctor`, `auth`, `workspace`, and `pi`.
|
|
|
|
**Step 4:** Add a short historical note only where a document must explain the former name.
|
|
|
|
### Task 3: Rewrite authentication acceptance and manual test instructions
|
|
|
|
**Files:**
|
|
- Modify: `docs/testing/authentication-manual-acceptance.md`
|
|
- Modify: `docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md`
|
|
- Modify: `docs/install/authentication-local.md`
|
|
- Modify: `docs/install/authentication-oidc.md`
|
|
- Modify: `docs/install/authentik.md`
|
|
|
|
**Step 1:** Make `tht auth status`, `tht auth check`, `tht auth check --interactive`, and `tht doctor --json` the canonical terminal preflight.
|
|
|
|
**Step 2:** Use `tht status`, `tht start`, and `tht workspace inspect --workspace psd-clinical --json` for PSD deployment checks.
|
|
|
|
**Step 3:** Clarify that the P8 L2 gate is authentication-to-application integration through the first reviewer gate.
|
|
|
|
**Step 4:** Retain the prior functional test suite as a baseline and add only the authentication boundary smoke required for this acceptance.
|
|
|
|
### Task 4: Align documentation smoke tests
|
|
|
|
**Files:**
|
|
- Modify: `scripts/auth-docs-smoke.sh`
|
|
- Modify: `scripts/test-auth-docs-smoke.sh`
|
|
- Inspect/update: any current smoke script whose user-facing command examples still require the legacy CLI name
|
|
|
|
**Step 1:** Replace forbidden/current command assertions with `tht` equivalents.
|
|
|
|
**Step 2:** Preserve negative checks for obsolete authentication CLI wording.
|
|
|
|
**Step 3:** Run the positive and negative documentation fixtures.
|
|
|
|
### Task 5: Preserve or annotate historical material
|
|
|
|
**Files:**
|
|
- Inspect the historical discovery specification for context, without treating it as current operator documentation.
|
|
- Inspect: dated reports and archived acceptance scripts
|
|
|
|
**Step 1:** Do not rewrite historical titles, commit evidence, or old implementation names solely to erase history.
|
|
|
|
**Step 2:** Add a concise “historical nomenclature” note where an archived document could otherwise be mistaken for current instructions.
|
|
|
|
### Task 6: Verify the convergence
|
|
|
|
**Step 1:** Run `scripts/auth-docs-smoke.sh` and `scripts/test-auth-docs-smoke.sh`.
|
|
|
|
**Step 2:** Search active documentation for remaining legacy CLI references.
|
|
|
|
**Step 3:** Confirm every remaining match is either an explicit historical note, an ignored runtime directory name, or a non-document executable compatibility artifact.
|
|
|
|
**Step 4:** Run `git diff --check` and report the exact files changed plus any intentionally retained historical references.
|