PerfectDocRoot CLI Guidebook (v1)

This guidebook documents the PerfectDocRoot (PDR) command‑line interface: what it is for, how it is governed, and how developers should use it safely.

The PDR CLI is intentionally minimal, explicit, and governance‑first. It exists to help developers verify behavior, detect drift, and lock guarantees — not to expose prompts, reasoning, or hidden system state.

1. Purpose of the PDR CLI

The PDR CLI provides opt‑in developer tools for inspecting and validating how PerfectDocRoot builds and executes turns.

It is designed to:

  • Verify that execution inputs are deterministic
  • Compare behavior across execution surfaces (Guided vs TurnSpec)
  • Detect regressions early
  • Support reproducibility and trust
  • Enable safe automation (CI / BridgeOps)

The CLI is not a convenience wrapper around prompts or models. It is a governance surface.

2. Governance Model

All PDR CLI commands follow the same governance rules:

  • Opt‑in only — commands run only when explicitly invoked
  • Metadata‑only inspection — hashes and counts, never content
  • No prompt dumps — system prompts and user inputs are never printed
  • No chain‑of‑thought — reasoning is never exposed
  • No agents — commands do not act autonomously

If a CLI command produces output, it does so intentionally and safely.

Relationship to Inspect

Many CLI commands rely on the Inspect mechanism internally.

Inspect provides:

  • `inspect.messages_source`
  • `inspect.messages_count`
  • `inspect.messages_hash`

These signals allow verification without leakage. The CLI never bypasses Inspect’s guarantees.

3. Core Commands

3.1 `gc-test-prompts`

Purpose

Validates that Guided Creation turns can build server‑side messages correctly and deterministically.

This command is typically used to:

  • Smoke‑test message construction
  • Verify Inspect hash generation
  • Confirm that server‑built message paths are working

Example

```bash
wp pdr gc-test-prompts --user=1
```

What it outputs

  • Turn identifiers
  • Inspect hashes for server‑built messages

What it does NOT output

  • Prompt text
  • System instructions
  • User message content

This command is best used during development and initial validation.

3.2 `gc-parity-check`

Purpose

Verifies that Guided Creation and TurnSpec‑driven builds produce identical server‑built messages for the same deterministic inputs.

Parity is evaluated using governed inspection signals only:

  • `inspect.messages_count`
  • `inspect.messages_hash`

If both values match, the two execution paths are provably equivalent.

Basic usage

```bash
wp pdr gc-parity-check
```

Runs parity checks for all configured fixtures across Turn1, Turn2, and Turn3.

Limit checks to specific turns

```bash
wp pdr gc-parity-check --turns=turn1,turn2
```

Table output (default)

By default, table output uses shortened ASCII‑safe hash previews to avoid wrapping in narrow terminals:

```
43211653c9...a9fa258ec5
```

```bash
wp pdr gc-parity-check --format=table
```

Full hash output

To display full hashes:

```bash
wp pdr gc-parity-check --full-hash=1
```

This applies to both table and JSON output.

JSON output (automation‑friendly)

```bash
wp pdr gc-parity-check --format=json
```

  • JSON output includes full hashes by default
  • Use `--full-hash=0` to shorten hashes in JSON

Exit behavior

  • Exit code `0` → all fixtures PASS
  • Non‑zero exit → one or more fixtures FAIL

This makes `gc-parity-check` safe and effective for CI pipelines.

4. Inspect & CLI Interaction

CLI commands that involve execution verification rely on Inspect as the single source of truth.

Key properties:

  • Hashes are computed from canonical JSON
  • Counts represent exact message arrays
  • Matching hashes imply identical inputs

The CLI never inspects model output or reasoning — only execution inputs.

5. CI / Automation Patterns (BridgeOps)

The PDR CLI is designed to be automation‑friendly.

Example: Fail CI on parity regression

```bash
wp pdr gc-parity-check || exit 1
```

This pattern allows teams to:

  • Lock Guided ↔ TurnSpec parity
  • Detect drift early
  • Prevent silent regressions

Because the CLI is metadata‑only, this is safe to run in shared environments.

6. What the CLI Will Never Do

The PDR CLI will never:

  • Reveal system prompts
  • Expose user message content
  • Show chain‑of‑thought
  • Execute agents
  • Mutate state implicitly

If you ever feel tempted to add such behavior, it belongs outside the PDR CLI.

7. Design Principles

The CLI may appear minimal by design. This is intentional.

PerfectDocRoot CLI tools prioritize:

  • Determinism over convenience
  • Verification over introspection
  • Explicitness over magic
  • Trust over opacity

If a behavior cannot be governed safely, it does not belong here.

Closing

The PerfectDocRoot CLI is not a debugging toy.

It is a contract‑enforcing interface between developers, execution surfaces, and governance guarantees.

Use it to prove what happened — not to peek behind the curtain.