# pqdx/2.0.0 Directory Reference

**PQDX-GDE-0002** — Non-normative guidance
Companion to the pqdx/2.0.0 schema specification (PQDX-STD-0001)

---

## What This Document Covers

Every pqdx-governed project stores its governance artifacts in a
`.pqdx/` directory — the governance container. This document describes
what goes in that directory, how it scales with project complexity,
how its layout adapts to repository posture (private vs public), and
how it relates to domain-specific directories like `.pqdc/`.

---

## The Governance Container

```
project/
└── .pqdx/
    ├── {project}.state.yaml
    ├── spec/
    │   ├── pqdx-schema-spec.yaml
    │   ├── pqdx-schema-spec.md
    │   └── ...
    ├── vocab/
    │   ├── field/
    │   │   └── {profile-name}.vocab.yaml
    │   ├── specialty/
    │   ├── org/
    │   ├── team/
    │   └── individual/
    ├── decisions/
    │   ├── dr-template.md
    │   ├── DR-NNN-title.md
    │   └── internal/         (public posture only — gitignored)
    ├── docs/
    ├── runbooks/
    └── sessions/
        ├── prompts/
        ├── captures/
        └── artifacts/
```

`.pqdx/` is the governance root. It signals "this project is governed
by pqdx" the same way `.git/` signals "this project is version
controlled." Tools in the pqdx ecosystem discover governed projects
by walking up the directory tree looking for `.pqdx/`.

### Why `.pqdx/` and Not `.claude/`

Three reasons (per piqued-cc:ILD-434):

**Identity collision.** `.claude/` is Claude's configuration directory.
Governance artifacts and tool configuration are different things. A
human browsing `.claude/` can't tell what's Claude config and what's
project governance.

**Tool independence.** pqdx is a universal protocol. The governance
root is named after the protocol, not any specific AI tool. A project
governed by pqdx might use Claude, GPT, Gemini, or no AI at all.

**Ecosystem signaling.** `.pqdx/` tells every tool in the ecosystem —
validators, session managers, scaffolding tools, VS Code extensions —
"this project speaks pqdx." The folder name is the namespace.

---

## Directory Contents

### The State File

**Location:** `.pqdx/{project}.state.yaml`

The single source of truth for the project. Identity, milestones,
decisions, concerns, actions, sessions, queued items, notes —
everything the governance toolchain reads and writes. Everything a
dashboard renders comes from this file. Every session close-out
patches this file.

The filename includes the project name (`compass.state.yaml`, not
`state.yaml`) because state files travel. Attached to a Slack message,
uploaded to project knowledge, sitting in a downloads folder alongside
other state files — the filename alone must identify the project.

In **private posture**, the state file commits to git alongside other
governance artifacts. Public projections (if any) are generated as
`.pqdx/{project}.public-state.yaml` and treated as regenerable
output — gitignored.

In **public posture**, the canonical state file is gitignored from
this repo (it lives privately) and the projection is committed as the
authoritative public surface. See the Repository Posture section
below.

### `spec/` — Standard Reference Documents

**Location:** `.pqdx/spec/`

The pqdx standard documents that govern this project. These are
protocol infrastructure — identical across every governed project,
managed by pqdx-dist (the standard distribution tool), not authored
by the project team.

Contents (for pqdx/2.0.0):

| File | Doc ID | Role |
|------|--------|------|
| `pqdx-schema-spec.yaml` | PQDX-STD-0001a | Annotated schema |
| `pqdx-schema-spec.md` | PQDX-STD-0001b | Prose specification |
| `pqdx-template.yaml` | PQDX-STD-0001c | Bare template |
| `pqdx-fixture.state.yaml` | PQDX-STD-0001d | Canonical fixture |
| `pqdx-patching-guide.md` | PQDX-GDE-0001 | Patching guide |
| `pqdx-directory-reference.md` | PQDX-GDE-0002 | Directory reference |

Why a separate directory from `docs/`? Because the standard documents
are not project-specific. A steward browsing `.pqdx/docs/` should see
only their team's reference material. A steward browsing `.pqdx/spec/`
sees the protocol rules that govern every pqdx project. The consumer
questions are different: "what are the rules?" (spec/) vs "what did we
document?" (docs/).

The `spec/` directory is the scope boundary for pqdx-dist — the
distribution tool owns everything inside it and touches nothing else.
Updates are atomic: archive old versions, install new ones.

Standard documents are committed to version control alongside the
state file — they are part of the project's governance configuration,
not ephemeral working files. Per PQDX-STD-0001b §10.7.1, standard
infrastructure (`.pqdx/spec/` and `.pqdx/vocab/`) is **not subject to
project posture filtering** — it MUST be tracked in version control
regardless of posture, and is not subject to the projection algorithm
in §10.6 (the algorithm operates on the state file, not on
infrastructure files alongside it).

### `vocab/` — Vocabulary Profiles

**Location:** `.pqdx/vocab/{layer}/{profile-name}.vocab.yaml`

Vocabulary profiles that customize display labels, add domain-specific
types, and configure alias mappings for this project. The state file's
`vocabulary` block references profiles by name within layer; tools
resolve those names to files in this directory (per ILD-145, with
placement refined by ILD-222).

Profiles are organized into subdirectories matching their layer:

| Subdirectory | Layer | Examples |
|---|---|---|
| `vocab/field/` | Field (universal-to-domain) | `pqdc-software-dev.vocab.yaml` |
| `vocab/specialty/` | Specialty (intersection profiles) | `pqdc-rust-systems.vocab.yaml` |
| `vocab/org/` | Organization-specific | `acme-corp-conventions.vocab.yaml` |
| `vocab/team/` | Team-specific | `platform-team.vocab.yaml` |
| `vocab/individual/` | Operator-specific | `jdoe.vocab.yaml` |

Layered subdirectories make the layer hierarchy explicit at the
filesystem level (no naming-convention guessing) and enable visibility
filtering for public posture, where operator-layer profiles are
gitignored as directories.

Field- and specialty-layer profiles are governed artifacts — they
should be committed to version control alongside the state file in
both postures. Operator-layer profiles (org, team, individual) commit
in private posture and are gitignored in public posture.

### `decisions/` — DR Companion Files

**Location:** `.pqdx/decisions/DR-NNN-title.md`

When a decision is significant enough for formal analysis — context,
options, trade-offs, consequences — it gets a DR entry in the state
file and a companion markdown file here. The state file entry is the
index; the companion file is the depth.

The `dr-template.md` file lives here as a scaffold for new DRs. Copy
it, fill it in. The template encodes the DR structure: frontmatter
schema, sections for context, options, recommendation, consequences,
and review.

The `companion` field on the DR entry creates the link:
`companion: "repo://decisions/DR-001-pgvector-adoption.md"`. Dashboards
render this as a navigable reference.

Why a separate directory instead of inline? Because DRs can be multi-
page documents with diagrams, code samples, and detailed analysis.
YAML is for structured data. Prose lives in prose files.

#### `decisions/internal/` (Public Posture)

In public posture, some DRs have internal-only context (security
debate, strategic considerations, personnel context, pre-disclosure
reasoning) that doesn't belong in public history while the DR's
existence and outcome should. Internal context lives at
`.pqdx/decisions/internal/DR-NNN-context.md` and is gitignored.

Public DRs reference their internal context **by acknowledgement
only** — no schema field, no auto-linking, no relative-path
resolution. Example: a public DR may state *"Internal context
preserved at `decisions/internal/DR-NNN-context.md` (private)."*
Operators with canonical-side access find the file by naming
convention; public visitors see only that internal context exists.

The `decisions/internal/` directory is irrelevant in private posture
and may be omitted from the scaffolding.

### `docs/` — Governed Reference Documents

**Location:** `.pqdx/docs/{document-name}.md`

Reference documents that aren't decisions and aren't runbooks.
Architecture documents, API specs, standard operating procedures,
this directory reference itself. These are stable artifacts that
multiple sessions reference but no single session owns.

In public posture, `.pqdx/docs/` is one of three project-authored
mixed-provenance directories specified in PQDX-STD-0001b §10.7.2;
the discrimination mechanism between project-authored, synced, and
operator-internal content is tracked as **OQ-11**. Until OQ-11
resolves, follow the interim guidance in §10.7.3 — operator
discipline at PR-review time, recursive ignore plus structural
persistence (per ILD-223/224), or filename-prefix re-allow as a
transitional pattern.

### `runbooks/` — Procedural How-To Documents

**Location:** `.pqdx/runbooks/{topic}.runbook.md`

Procedural how-to documents. A runbook answers "how do I do X?" —
step-by-step, copy-pasteable, tested. Deployment procedures, capture
workflows, migration playbooks.

Distinct from docs (which describe what IS) and session captures
(which record what HAPPENED). Runbooks describe what TO DO.

Present at standard tier and above. Minimal tier projects don't need
runbooks — they're simple enough that the state file and a README
suffice.

The same OQ-11 deferral that applies to `docs/` applies here for
public-posture projects (per §10.7.2 / §10.7.3).

### `sessions/` — Session Lifecycle on Disk

Three subdirectories, each serving a different stage in the session
governance workflow.

#### `sessions/prompts/`

Input specs for Claude Code or other AI execution tools. When a
governance session produces a specification — design doc,
implementation prompt, migration plan — the prompt file lands here.
Session management tools route files here based on naming convention.

Why a dedicated directory? Because prompts are governed artifacts.
They record what the AI was asked to do. When you trace why a piece
of code exists, the prompt that created it is primary evidence.

#### `sessions/captures/`

Output recordings from sessions. Three file types:

- **`{slug}.record.md`** — Full terminal recordings. Everything that
  happened in the terminal, captured as markdown with timestamps.
  The raw transcript.

- **`{slug}.claude-code.jsonl`** — Claude Code's structured session
  log. Every tool call, file edit, and reasoning step in machine-
  readable format.

- **`{slug}.capture.md`** — Intentional clipboard snapshots.
  Timestamped, frontmattered records of specific moments worth
  preserving.

The naming convention (`{slug}.{source}.{format}`) is the routing
rule. Tools don't need configuration to know what a file is — the
filename carries the metadata.

#### `sessions/artifacts/`

Chat deliverables that aren't prompts. Design documents, analysis
reports, zip archives of session output. The landing zone for
everything a chat session produces that an execution tool doesn't
consume.

Distinct from captures (which are evidence of what happened) and
prompts (which are instructions for what to do). Artifacts are
deliverables — what the session produced.

---

## Repository Posture

Beyond tier (which sizes the directory tree), pqdx-governed projects
declare a **posture** that determines where the canonical state file
lives in version control and what role any public projection plays.
The posture model — three orthogonal axes (canonical visibility,
projection role, operator coordination), the named `private` and
`public` defaults, and `custom` for unnamed combinations — is
specified normatively in PQDX-STD-0001b §10.1. The
`identity.posture` schema slot and its declaration semantics are
specified in §10.2. New named postures require a Decision Record
(per DR-009 / §10.1).

This section captures the operational guidance that follows from
those rules: where files go in version control, what differs
between postures at the directory level, and what scaffolding each
posture needs.

### Private Posture (default)

The canonical state file commits to git in this repo. Repo access
controls handle confidentiality. Any `{project}.public-state.yaml`
projection (if it exists) is regenerable output, gitignored.

Use private posture when the repository is private to the team or
organization, there is no requirement to publish a curated public
surface, and multi-operator coordination is git-mediated.

### Public Posture

The canonical state file is **gitignored from this repo** — it lives
in a private companion repo, on operator's disk, or via pqsy-mediated
sync. The `{project}.public-state.yaml` projection commits to git as
the **authoritative public surface**. Public-posture projects publish
a deliberate, curated subset of governance state; internal context
(in-flight DR debates, exploratory thinking, sensitive findings under
disclosure embargo) stays canonical-side.

Use public posture when the repository is public, or will become
public, a curated public projection is the intended external
surface, and permanent public git history of canonical content is
unacceptable.

Public posture requires:

- **Vocabulary subdirectory layering** (per ILD-222 — see `vocab/`
  above). Operator-layer profiles (`org/`, `team/`, `individual/`)
  must be gitignorable as a directory rather than enumerated as
  filenames.
- **`decisions/internal/`** subdirectory for per-DR private context
  (security debates, strategic considerations, personnel context).
  Public DRs reference internal context by acknowledgement only — no
  schema field, no auto-linking.
- **Conformance with the projection algorithm in PQDX-STD-0001b
  §10.6.** Per-entity visibility resolution is specified in §10.3,
  skeleton field sets in §10.5, and projection-consistency
  validation rules in §11.17. Tools generating the public projection
  MUST follow that algorithm; pqdx-rs's prototype is the v2.0.0
  reference implementation.

### Multi-Operator Public Posture

Multi-operator coordination of private canonical state files in
public-posture projects has no documented architecture as of
pqdx/2.0.0. pqsy (Piqued Sync, planned) is the intended solution but
is not yet shipped. Solo public posture is supported now;
**multi-operator public posture is not yet recommended for
production** (tracked as OQ-12).

### Posture Migration

Migration from private to public posture is functionally one-way.
Once canonical state file content is committed to a public repo, it
cannot be effectively retracted (force-push breaks downstream clones;
mirrors and archives retain originals). Choose posture from inception
for any project that might eventually go public.

---

## Git Visibility

Not everything in `.pqdx/` should be tracked in version control.
What's committed and what's gitignored depends on the project's
posture.

### Private Posture

**Always committed:**

- The state file (`{project}.state.yaml`)
- Standard reference documents (`spec/`)
- Vocabulary profiles (`vocab/` — including all layer subdirectories)
- Decision companions (`decisions/`)
- Reference docs (`docs/`)
- Runbooks (`runbooks/`)

**Always git-ignored:**

- `sessions/prompts/` — may evolve during development
- `sessions/captures/` — raw transcripts, potentially sensitive
- `sessions/artifacts/` — intermediate deliverables
- `.pqsn-active` — transient session state for session management tools
- `*.public-state.yaml` — generated projections (regenerable output)
- Tool-managed transient state, e.g. `.backups/` (per ILD-226)

### Public Posture

**Always committed:**

- The public projection (`{project}.public-state.yaml`)
- Standard reference documents (`spec/`)
- Universal-to-domain vocabulary profiles (`vocab/field/`,
  `vocab/specialty/`)
- Public decision companions (`decisions/DR-NNN-*.md`,
  `decisions/dr-template.md`)
- Project-authored reference docs (mechanism for distinguishing
  project-authored from synced/draft content tracked as OQ-11)
- Project-authored runbooks (same OQ-11 deferral)

**Always git-ignored:**

- The canonical state file (`{project}.state.yaml`) — lives privately
- Operator-specific vocabulary profiles (`vocab/org/`, `vocab/team/`,
  `vocab/individual/`)
- Internal DR context (`decisions/internal/`)
- Session working files (`sessions/prompts/`, `sessions/captures/`,
  `sessions/artifacts/`)
- `.pqsn-active`, `.backups/`, and other tool-managed transient state
- Any `docs/` and `runbooks/` content that isn't project-authored
  (mechanism pending OQ-11)

### Structural Persistence

Standard pqdx subdirectories whose contents are gitignored
(`sessions/`, operator-layer `vocab/` directories,
`decisions/internal/`) persist in fresh clones via the
recursive-ignore + structural-re-allow pattern (per ILD-223), paired
with a universal `!**/.gitkeep` re-allow (per ILD-224). Fresh clones
see the standard pqdx tree even when content is empty or local-only.

### Where to Put Pqdx-Specific Ignore Rules

Project-root `.gitignore` is the default location for pqdx-specific
ignore rules. `.pqdx/.gitignore` is permitted as an alternative when
pqdx-specific rules exceed roughly 15 lines (per ILD-225, a heuristic,
not a hard threshold). Trade-off: discoverability (project-root) vs.
encapsulation (`.pqdx/.gitignore`).

---

## Tier Scaling

The `.pqdx/` directory scales with the project's `identity.tier`
value: `minimal | standard | full`. Tier and posture are orthogonal —
any tier can be either posture.

### Minimal Tier

```
.pqdx/
├── {project}.state.yaml
└── decisions/          (if any DRs exist)
    └── dr-template.md
```

Just the state file. Maybe a decisions directory if the project has
formal DRs. Lightweight governance — the file exists for traceability,
not ceremony. Appropriate for small projects, personal tools, proofs
of concept.

### Standard Tier

```
.pqdx/
├── {project}.state.yaml
├── spec/
│   ├── pqdx-schema-spec.yaml
│   ├── pqdx-schema-spec.md
│   └── ...
├── vocab/
│   ├── field/
│   │   └── {profile}.vocab.yaml
│   └── specialty/
├── decisions/
│   ├── dr-template.md
│   └── DR-001-title.md
├── docs/
├── runbooks/
│   └── {topic}.runbook.md
└── sessions/
    ├── prompts/
    ├── captures/
    └── artifacts/
```

State file, standard reference documents, vocabulary profiles,
decisions, runbooks, and the full session infrastructure. Active
governance with session capture, procedural documentation, and
AI-collaborative workflow. This is the working tier for most governed
projects.

Public-posture standard tier additionally provisions
`vocab/{org,team,individual}/` and `decisions/internal/`, all
gitignored but structurally persistent.

### Full Tier

Everything in standard, plus additional structured reference material,
CI integration artifacts, and potentially generated documentation.
Maximum ceremony for high-blast-radius projects. A full tier project
missing expected directories may generate validator warnings.

### Tier Is Guidance, Not Gatekeeping

The tier doesn't gate what you can create — you can add a `runbooks/`
directory to a minimal project anytime. The tier signals what the
project *expects* to have, which informs scaffolding tools and
validators. A full tier project missing `runbooks/` might get a
warning. A minimal tier project without it is perfectly normal.

---

## Scaffolding Commands

For projects using pqdc-init or manual setup. Posture-specific steps
are noted; common steps apply to both postures.

### Common — Standard Tier Base

#### PowerShell (Windows)

```powershell
$dirs = @(".pqdx", ".pqdx/spec",
          ".pqdx/vocab", ".pqdx/vocab/field", ".pqdx/vocab/specialty",
          ".pqdx/decisions",
          ".pqdx/docs", ".pqdx/runbooks", ".pqdx/sessions",
          ".pqdx/sessions/prompts", ".pqdx/sessions/captures",
          ".pqdx/sessions/artifacts")
$dirs | ForEach-Object { New-Item -ItemType Directory -Path $_ -Force }
Copy-Item "dr-template.md" ".pqdx/decisions/dr-template.md"
```

#### Bash (macOS / Linux)

```bash
mkdir -p .pqdx/{spec,decisions,docs,runbooks}
mkdir -p .pqdx/vocab/{field,specialty}
mkdir -p .pqdx/sessions/{prompts,captures,artifacts}
cp dr-template.md .pqdx/decisions/dr-template.md
```

### Public Posture — Additional Steps

Public posture requires the operator-layer vocab subdirectories and
the `decisions/internal/` directory, all gitignored (structural
persistence per ILD-223 keeps them visible).

```bash
mkdir -p .pqdx/vocab/{org,team,individual}
mkdir -p .pqdx/decisions/internal
touch .pqdx/vocab/{org,team,individual}/.gitkeep
touch .pqdx/decisions/internal/.gitkeep
touch .pqdx/sessions/prompts/.gitkeep
touch .pqdx/sessions/captures/.gitkeep
touch .pqdx/sessions/artifacts/.gitkeep
```

### .gitignore Additions

#### Private Posture

```gitignore
# pqdx — private posture
.pqdx/sessions/prompts/
.pqdx/sessions/captures/
.pqdx/sessions/artifacts/
.pqdx/.pqsn-active
.pqdx/.backups/

# Public projections (generated, not authored)
.pqdx/*.public-state.yaml
```

#### Public Posture

```gitignore
# pqdx — public posture
# Canonical state file lives privately
.pqdx/{project}.state.yaml

# Operator-specific vocab layers
.pqdx/vocab/org/
.pqdx/vocab/team/
.pqdx/vocab/individual/

# Internal DR context
.pqdx/decisions/internal/

# Session working files (recursive ignore + structural re-allow)
.pqdx/sessions/**
!.pqdx/sessions/prompts/
!.pqdx/sessions/captures/
!.pqdx/sessions/artifacts/

# Tool transient state
.pqdx/.pqsn-active
.pqdx/.backups/

# Universal .gitkeep re-allow (structural persistence)
!**/.gitkeep
```

For projects that prefer encapsulation, the same rules can live in
`.pqdx/.gitignore` with paths root-relative to `.pqdx/` (per ILD-225).

---

## Relationship to Domain Directories

`.pqdx/` and domain directories (`.pqdc/`, `.pqdh/`, `.pqde/`, etc.)
are complementary, not competing.

**`.pqdx/`** contains the **project state** — the state file,
decisions, sessions, captures. It tells tools *what has happened* in
this project and *where it's going*.

**`.pqdc/`** (or other domain directory) contains the **domain
profile** — context configuration, framework reference, AI rules,
review perspectives. It tells tools *how to work* on this project.

A software project governed by pqdx with the pqdc software development
profile has both directories. `.pqdc/` is the playbook. `.pqdx/` is
the record.

A non-software project governed by pqdx with a different domain
profile (healthcare, education, legal) would have `.pqdx/` and their
own domain directory, but not `.pqdc/`.

A project governed by pqdx with no domain profile at all has only
`.pqdx/`. The universal standard works without any domain overlay.

---

## Key Rules

1. **The state file is the source of truth.** Everything else in
   `.pqdx/` supplements it. If the state file and a companion document
   disagree, the state file wins.

2. **The filename includes the project name.** Always
   `{project}.state.yaml`, never `state.yaml`.

3. **One state file per project.** Multiple state files in one
   `.pqdx/` directory is not supported. Multi-project governance uses
   separate directories or portfolio tooling.

4. **Vocabulary profiles are committed (universal-to-domain layers).**
   Field- and specialty-layer profiles are part of the project's
   governance configuration. Operator-layer profiles (org, team,
   individual) commit in private posture and are gitignored in public
   posture.

5. **Public projections are generated, not authored.** Files matching
   `*.public-state.yaml` are outputs of the projection algorithm
   specified in PQDX-STD-0001b §10.6 and identified by the top-level
   `projection: public` key (§10.4). Don't edit them directly —
   they'll be overwritten on the next regeneration, and tools refuse
   to apply patches to projection files (per §11.17 rule 1 and
   PQDX-GDE-0001 Rule 10). In public posture, the projection IS the
   public authoritative surface and IS committed; in private posture,
   the projection is regenerable output and is gitignored.

6. **Posture is declared, not implicit.** Every pqdx-governed
   project declares its posture in `identity.posture` (per
   PQDX-STD-0001b §10.2). Absent posture defaults to `private`;
   public and custom postures MUST be set explicitly. Silent
   ambiguity on `custom` posture is itself a posture violation —
   `custom` SHOULD be accompanied by onboarding documentation
   describing the chosen axis values (per §10.1 / §10.2). Schema
   validation rules for posture are in §11.16.

7. **The CQT governs directory contents.** Every file added to
   `.pqdx/` must be net-positive by the Consumer Question Test. If
   no consumer asks a question this file answers, it belongs elsewhere.

---

## Governing Decisions

| Decision | Summary |
|----------|---------|
| ILD-92 | State file lives at `.pqdx/{project}.state.yaml` |
| ILD-144 | `.pqdx/` is the complete governance container (supersedes ILD-93) |
| ILD-145 | Vocabulary profiles in `.pqdx/vocab/` (supersedes ILD-111 flat-`.pqdx/` model) — placement refined by ILD-222 |
| ILD-146 | Playbook subdirectory structure within `.pqdx/` |
| ILD-147 | `contexts/` directory removed from repo root |
| ILD-182 | `.pqdx/spec/` directory for standard reference documents — protocol infrastructure distinct from project docs |
| piqued-cc:ILD-434 | `.pqdx/` not `.claude/` — protocol identity, not tool identity |
| DR-009 | Posture Model for pqdx-Governed Projects — defines private, public, and custom postures and their architectural patterns. Operationalized normatively in PQDX-STD-0001b §10 (Trust Boundary). |
| ILD-222 | Vocab profile subdirectory layering by layer (supersedes ILD-145's flat-vocab/ structure) |
| ILD-223 | Structural persistence via recursive ignore + directory re-allows |
| ILD-224 | Universal `!**/.gitkeep` re-allow companion to structural persistence |
| ILD-225 | `.pqdx/.gitignore` as documented alternative to project-root `.gitignore` |
| ILD-226 | Tooling-transient ignore convention |

---

*PQDX-GDE-0002 — pqdx/2.0.0 Directory Reference*
*© 2026 Our Collaborative Space, LLC — CC-BY-ND 4.0*