pqdx/2.0.0 Schema Specification

§1.1Schema Version

Every state file MUST begin with a schema_version field.

• Type: String
• Required: MUST be present. MUST be the first key in the file.
• Pattern: pqdx/{semver} where {semver} follows Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH).
• Current value: "pqdx/2.0.0"
• Consumer: Any tool opening a state file.
• Question: "What specification governs this file?"
• Validation: Tools MUST check schema_version before processing. Major version mismatch (e.g., tool expects pqdx/2.x.x, file says pqdx/3.0.0) SHOULD cause a warning or refusal to process. Minor version excess (file declares a higher minor than the tool knows) SHOULD produce a warning but MUST NOT cause rejection — the file may use features the tool doesn't know about. Patch difference MUST be treated as fully compatible.
• Extension point: Immutable.
• Governing decisions: ILD-9 (namespaced version format), ILD-10 (semver semantics), ILD-153 (top-level key inventory).

The namespace makes every state file self-identifying. A tool or human encountering the file in any context — attached to a Slack message, uploaded to project knowledge, sitting in a downloads folder — knows immediately what spec governs it.

Versioning semantics for the schema itself: additive changes (new optional fields, new extension points) are minor version bumps. Changed semantics on existing fields are major version bumps. Documentation-only changes are patch bumps.

§1.2Top-Level Key Inventory

A pqdx/2.0.0 state file has eleven top-level keys (per ILD-153):

All eleven keys MUST be present. Sequence keys MAY be empty ([]). The projection key is OPTIONAL on canonical state files (MUST NOT be present per §10.4); REQUIRED on generated projection files. Value: public. Identifies a state file as a generated public projection. Full specification at §10.4.

Forward compatibility: Tools SHOULD warn on unknown top-level keys but MUST NOT reject the file. Future schema versions may introduce additional keys. A tool built for pqdx/2.0.0 encountering a file with an unknown key should process all known keys normally and surface a warning that the file contains unrecognized content.

Governing decisions: ILD-153 (eleven-key inventory), ILD-152 (projection as top-level key).

§1.3Vocabulary Block

The vocabulary block declares which vocabulary profiles govern display and extension for this state file.

• Type: Mapping with exactly five keys.
• Required: MUST be present. All five layer keys MUST be present — empty layers use [] (per ILD-114).
• Governing decisions: DR-005 (vocabulary block replaces context_ref), ILD-109 (five-layer model), ILD-114 (empty layers), ILD-87 (advisory resolution), ILD-88 (first-wins merging), ILD-145 (.pqdx/vocab/ directory).

Layer Keys

Layer Entries

Each layer holds a sequence of { profile, version } entries:

vocabulary:
  field:
    - profile: pqdc-software-dev
      version: "1.0.0"
  specialty: []
  org:
    - profile: meridian-consulting
      version: "1.0.0"
  team: []
  individual: []

The profile value is a logical identifier that tools resolve to {profile}.vocab.yaml in the .pqdx/vocab/ directory (per ILD-145). The version value declares which version of the profile this file expects.

Precedence

Cross-layer precedence (highest wins): individual > team > org > specialty > field

Within a single layer, array order determines precedence — first entry wins (per ILD-88).

Resolution Semantics

Resolution is advisory — tools MUST NOT fail if referenced profiles are missing (per ILD-87). A state file that references a vocabulary profile that doesn't exist on disk is structurally valid. The missing profile means display aliases won't resolve, but the universal vocabulary in the state file remains readable.

The full vocabulary profile format is specified in PQDX-STD-0002.

§1.4Provenance Model

Every entity in a state file tracks where it came from. The provenance model is unified across all entity types — no exceptions.

The Two-Field Model

session — MUST be present on all entity types that carry it (see individual entity sections for requirement levels). String value identifying which session formalized this entity, or the creation surface if created outside a governed session.

Values SHOULD be valid session IDs (e.g., "S014") in governed projects. Non-session values are permitted for entities created outside session governance: "dashboard", "direct", "migrated:jira-1234". Tools MUST NOT reject non-session values.

origin — OPTIONAL on all entity types. String value. Freeform. Records where the information came from when different from the formalizing session. If absent, the entity originated in the session referenced by the session field.

Examples: "Inherited from firm security policy SEC-2024-017", "Carried from legacy wiki decommission project", "Firm all-hands Q&A — Managing Partner mentioned Compass by name".

The session (and optionally origin) opening-provenance fields are applicable to decisions, concerns, actions, queued items, notes, and — per DR-010 — milestones (optional). See per-entity sections (§3.1, §4.1, §5.1, §6.1, §7.1, §8.1, §9.1) for the MUST/OPTIONAL disposition on each entity type.

Governing decisions: ILD-23 (two-field provenance model), S027 unified provenance (session replaces source on actions and notes), DR-010 (milestone opening provenance — additive consistency).

The Closure Field

closed_in — OPTIONAL. String (session ID). A cross-cutting field applicable to concerns, actions, queued items, milestones, and decisions. SHOULD be present when an entity reaches a terminal status. Records which session transitioned the entity to its terminal state.

Tools MUST NOT error on unresolvable closed_in references — the referenced session may exist in another project or may not yet be written.

closed_in answers a distinct question from session: session says "where did this entity come from?" while closed_in says "where did this entity's lifecycle end?" For entities that are created and resolved in the same session, both fields carry the same value.

Governing decisions: S027 (closed_in replaces resolved_in as universal closure field), ILD-201 (extended to decisions).

§1.5Array Ordering Convention

All sequences in a state file are chronologically ordered — oldest first, newest last. New entries are appended to the end of their section. Existing entries are MUST NOT be reordered.

This convention applies to all top-level sequences (milestones, decisions, concerns, actions, sessions, queued, notes) and to nested sequences (milestones[].items, sessions[].produced, sessions[].decisions_made, sessions[].state_changes).

The array index of an entry is part of its identity in version control diffs. Reordering creates phantom changes that obscure real edits.

No entry is ever deleted from a state file. Resolved concerns stay. Completed actions stay. Superseded decisions stay. Cancelled milestones stay. The state file is an audit trail — deletion destroys history.

Governing decisions: ILD-22 (chronological ordering, flow-style convention).

§1.6Extension Point Model

The schema is rigid about structure and permissive about vocabulary. Every field in the schema has one of four extension point classifications:

Immutable

The field's value set and semantics are fixed by the schema. Vocabulary profiles MUST NOT modify, extend, or alias these fields. Most fields are immutable — id, text, session, notes, ref, scope, decision_date, duration, planned_duration, and all structural fields.

Aliasable

The field has a closed value set defined by the schema. Vocabulary profiles MAY provide display aliases via triple-mapping (canonical value → display label → back to canonical). The underlying values in the state file MUST always use universal vocabulary. Aliases affect display only — they never appear in the state file itself.

Aliasable fields: identity.tier, identity.blast_radius, identity.team.role, identity.team.type, concern.type, concern.severity, concern.status (display only), decision.blast_radius, oq.impact, action.priority, action.status (display only), queued.priority, session.purpose, session.mode, session.participant.type, session.participant.role, produced.purpose, produced.format.

Additive

The field has a base value set defined by the schema. Vocabulary profiles MAY add values — they MUST NOT remove or rename existing ones. New values MUST include a description in the vocabulary profile.

Additive fields: identity.type (10 universal base types, domain profiles add more).

Delegated

The field's value set is defined entirely by the vocabulary profile. The schema defines the structural slot; the profile fills it.

Delegated fields: concern ID prefix mappings (the vocabulary profile provides the complete mapping from prefix to concern type).

Governing decisions: ILD-82 (extension point classification), ILD-84 (alias mechanism), ILD-85 (additive mechanism), ILD-86 (context file syntax).

§1.7Visibility

Stateful entities in pqdx state files MAY carry an optional visibility field controlling whether and how they appear in public projections. The full normative specification of the visibility model — values, defaults, resolution order, section defaults, and projection algorithm — is given in §10 (Trust Boundary). See §10.3 for entity visibility, §10.4 for the projection top-level key, §10.5 for skeleton field sets, and §10.6 for the projection algorithm.

The visibility field accepts three values: internal, skeleton, public. Default when absent is internal (security- first per ILD-149). For full semantics including resolution order, section defaults, and inheritance rules for nested entities, see §10.3.

§1.8Cross-Reference Syntax

Entities reference each other by ID. Two reference scopes exist:

Project-local references: Bare entity IDs — DR-001, ILD-47, BL-1, S014. These reference entities within the same state file.

Cross-project references: Qualified syntax — {project}:{entity-id}. Example: pqdc-cc:DR-004. The project name MUST match the identity.project value of the target state file.

Cross-project references appear in notes, origin, depends_on, blocked_by, and blocks fields. Tools MUST NOT error on unresolvable cross-project references — the target project may not be accessible from the current context.

Governing decisions: ILD-20 (cross-reference syntax).

§3.2Milestone Item Fields

Milestone items are the atomic checklist entries within a milestone. They use flow-style YAML for scannability (per ILD-22):

- { id: v01-1, text: "Define repo directory structure", status: open }
- { id: v01-8, text: "Verification gate", status: open, gate: true }

Field order in flow-style is normative: id, text, status, then optional fields. Authoring tools SHOULD preserve this order. Items that require extended context (e.g., a notes field) MAY use block-style YAML.

§3.3Milestone Lifecycle

The milestone lifecycle defines the valid states and transitions for the status field on milestone entries.

States

Transition Table

Invalid Transitions

• complete → any state. Terminal. A completed milestone that needs reopening indicates a scope change — create a new milestone with the revised scope.
• cancelled → any state. Terminal.

Normative Notes

• on-hold is distinct from action blocked — on-hold expresses broader situational factors (legal hold, priority shift, resource reallocation) while blocked is a specific impediment to a specific task.
• in-progress → planned is valid (per ILD-58). Premature starts can retreat directly without an intermediate state.

Governing decisions: ILD-44 (no blocked status on milestones), ILD-45 (cancelled status), ILD-57 (on-hold status), ILD-58 (in-progress → planned valid).

§3.4Milestone Completion Guard

A milestone MUST satisfy ALL of the following conditions before transitioning to complete:

1. The milestone MUST have at least one item with status: done. A milestone that delivered nothing is cancelled, not complete.
2. Every item with gate: true MUST have status: done. Non-gate items MAY have any terminal status (done, deferred, dropped, subsumed).
3. No item in the milestone MAY have status: open. All items must have reached a terminal state.

A conforming validator MUST reject a complete milestone that violates any of these conditions.

Domain profiles MAY document additional requirements (e.g., "pqdc requires code review before milestone completion") and enforce them in domain-specific tooling, but they MUST NOT weaken or modify universal guards.

The schema is the behavioral floor. Domain profiles raise the floor; they never lower it.

Governing decisions: ILD-30 (gate items), ILD-59 (at-least-one-done guard).

§3.5Milestone Item Status Lifecycle

Milestone item status is simpler than milestone status. All transitions originate from open:

Invalid transitions: done → any state. deferred → any state. dropped → any state. subsumed → any state. All non-open states are terminal within the milestone. A deferred item gets a fresh lifecycle in the target milestone.

Normative Note: Deferred Asymmetry

Milestone item deferred is terminal (the item's lifecycle in this milestone is over — tombstone model). Concern deferred is non-terminal (the concern stays in the same list and can reopen). The underlying principle is consistent: "deferred" means "not now." The divergence is in what happens next — milestone items relocate on deferral; concerns do not.

Governing decisions: ILD-43 (tombstone model), ILD-49 (concern deferred is non-terminal), ILD-54 (done vs complete terminology).

§4.1Common Fields (All Subtypes)

These fields are shared by DR, OQ, and ILD entries.

§4.2DR — Decision Record

Decision Records are formal decisions requiring structured analysis. They SHOULD have a companion document with context, options, trade-offs, and consequences.

ID pattern: ^DR-\d+$ (zero-padded, 3-digit minimum).

DR-Specific Fields

companion

• Constraints: Location-schemed path to the analysis document. Schemes: repo://, local://, url://, session://, project-knowledge://, state://, pending://.

• Default: None.

  is the full analysis for this decision?"

• Validation: Non-empty string when present. Tools SHOULD validate scheme prefix.

• Extension point: Immutable.

• Governing decisions: ILD-96 (companion field).

reviewed_by

critical or high blast_radius.

• Default: None. When absent, the session participants list is the fallback.

  reviewer. Question: "Who reviewed and approved this decision?"

• Validation: When present, sequence MUST contain at least one non-empty string.

• Extension point: Immutable.

• Governing decisions: S028 (reviewed_by formalized).

superseded_by

superseded.

• Default: None.

  decision lineage. Question: "What replaced this decision?"

• Validation: Non-empty string when present. Tools MUST NOT error on unresolvable references.

• Extension point: Immutable.

• Governing decisions: S028 (superseded_by formalized).

The superseded_by field enables lineage tracing — follow the chain from a superseded decision to its replacement until a non-superseded decision is reached. Without this field, lineage requires parsing freeform notes.

DR Lifecycle

States

Transition Table

Invalid Transitions

• superseded → any state. Terminal.
• rejected → any state. Terminal.
• withdrawn → any state. Terminal.
• accepted → proposed. A decision that was accepted cannot return to proposed — if it needs re-evaluation, supersede it and propose a new DR.

Governing decisions: ILD-46 (withdrawn status), ILD-82 (deferred added).

§4.3OQ — Open Question

Open Questions track uncertainties with impact assessment. They represent things the project doesn't know yet that affect its direction.

ID pattern: ^OQ-\d+$ (simple integer).

OQ-Specific Fields

impact

• Constraints: Values: negligible | low | medium | high | critical. Five-value scale.

• Default: None.

  knowing the answer to this question affect the project?"

• Validation: Value MUST be in the enumerated set when present.

• Extension point: Aliasable.

• Governing decisions: ILD-148 (negligible added, five-value congruence).

resolution_path

• Default: None.

  the plan for answering this question?"

• Validation: No constraints.

• Extension point: Immutable.

OQ Lifecycle

States

Transition Table

Invalid Transitions

• resolved → any state. Terminal. A resolved OQ that generates new questions is a new OQ, not a reopening.
• narrowed → open. Information gain doesn't reverse (per ILD-47). If new information expands the option space, either update notes (incorrect narrowing) or create a new OQ (fundamentally different question).

Governing decisions: ILD-47 (narrowed → open invalid), ILD-82 (deferred added).

§4.4ILD — Informal Locked Decision

Informal Locked Decisions are quick governance locks — recording what was decided without the full analysis of a DR. Most project decisions are ILDs.

ID pattern: ^ILD-\d+$ (simple integer).

Migration note: The ILD prefix was renamed from ID- in S027 (per ILD-154) to eliminate collision with the word "identifier." The migration procedure is documented in PQDX-GDE-0001 Appendix A. DR-006 documents the decision rationale and downstream impact.

ILD-Specific Fields

superseded_by

superseded.

• Default: None.

  this decision?"

• Validation: Non-empty string when present. Same semantics as DR superseded_by.

• Extension point: Immutable.

• Governing decisions: S028 (superseded_by formalized).

ILD Lifecycle

States

Transition Table

Invalid Transitions

• locked → pending. A confirmed decision cannot return to unconfirmed. If it needs revisiting, supersede it and create a new decision.
• superseded → any state. Terminal.

Governing decisions: ILD-34 (superseded status), S027 (pending status added, three-state lifecycle).

§5.2Concern Lifecycle

All seven concern types share a single lifecycle. Type and status are orthogonal — a blocker and a stale-doc have the same valid transitions.

States

Transition Table

Invalid Transitions

• resolved → any state. Terminal. A resolved concern that recurs is a new concern, not a reopening.

Normative Note: Deferred Is Non-Terminal

Concern deferred is non-terminal (reopenable). This is an intentional asymmetry with milestone item deferred (which is terminal). Milestone items relocate on deferral (tombstone model, ILD-43). Concerns don't relocate — they stay in the same concerns list and can reopen when the deferral reason expires.

Governing decisions: ILD-48 (orthogonal type/status), ILD-49 (deferred non-terminal), ILD-100 (monitoring status).

§5.3Concern Prefix Mapping

The concern ID prefix encodes the type. The universal mapping is:

Domain profiles provide this mapping via vocabulary profile triple-mapping — the full mapping (canonical type → prefix → display label) is declared in the profile. Tools use this mapping for ID validation (§11.9) and display.

§6.2Action Lifecycle

States

Transition Table

Invalid Transitions

• done → any state. Terminal.
• cancelled → any state. Terminal.
• deferred → done. Deferred actions must return to open before completing — the deferral implies work was not done, so completing from deferred would skip the work step.
• deferred → blocked. A deferred action is not being worked on, so a blocker is irrelevant while deferred. Return to open first.

Governing decisions: ILD-38 (action lifecycle), ILD-54 (done vs complete), ILD-82 (deferred added).

§7.2Produced Artifacts

The produced field tracks what a session created.

"What did this session produce?"

Each artifact entry has the following fields:

§7.3Session Output and Handoff Fields

§7.4Session Immutability

Sessions are immutable records (per ILD-56). Once a session entry is written, the following fields MUST NOT change: id, date, title, purpose, mode, participants, decisions_made, state_changes, next_action, notes, duration, planned_duration.

The produced array is the sole exception. Artifacts discovered or completed after the session may be appended with a note on the new entry indicating the amendment session.

Governing decisions: ILD-56 (session immutability).

§8.2Queued Item Lifecycle

States

Transition Table

Invalid Transitions

• pending → complete. Work must pass through in-progress (per ILD-53). You cannot complete work that was never started. If queued work becomes moot before starting, the correct path is pending → cancelled.
• complete → any state. Terminal.
• cancelled → any state. Terminal.

Normative Note: No Blocked Status

Queued items have no blocked status (per ILD-51). The depends_on field covers planned sequencing. External blockers are tracked as concerns with blocks references pointing to the queued item. Adding blocked would create ambiguity with depends_on (blocked because of a dependency, or because of an external factor?). Actions need blocked because they lack depends_on. Queued items have the dependency mechanism, so external blockers go in concerns.

Governing decisions: ILD-51 (no blocked on queued), ILD-52 (in-progress → pending valid), ILD-53 (pending → complete invalid), ILD-54 (complete vs done terminology), ILD-82 (deferred added).

§10.1Posture Model

A pqdx project's posture is a configuration of three orthogonal axes:

Two named postures are defined as default configurations of those axes:

Other axis combinations are valid; operators MAY compose them with appropriate gitignore configuration. Valid-but-unnamed combinations are referred to as custom postures.

New named postures MUST be added via Decision Record. Operators MUST NOT mint posture names ad hoc and have them recognized as ecosystem- standard.

Every pqdx-governed project declares a posture. The schema slot for declaration is specified in §10.2. Silent posture ambiguity is itself a posture violation — for projects whose declared posture is custom, prose justification SHOULD appear in onboarding documentation.

Governing decisions: DR-009 (posture model); §10.2 (declaration site); §10.3 (visibility values used in projection generation).

§10.2Posture Declaration —

The identity.posture field is the schema slot for posture declaration on every pqdx-governed project's state file.

§10.3Entity Visibility — field

Every stateful entity in a state file MAY carry an optional visibility field declaring whether and how the entity appears in public projections.

§10.4Projection Key —

The top-level projection key is the file-identification marker for generated public projection files.

§10.5Skeleton Field Set

When an entity's resolved visibility (§10.3) is skeleton, the projection algorithm (§10.6) emits the entity with only the fields enumerated in the entity type's skeleton field set. All other fields are stripped.

The skeleton field sets defined in this section are normative. Two conformant projection tools MUST produce identical output for skeleton entities given identical canonical input. Domain profiles and tools MAY add fields to an entity that are not enumerated here; such fields are stripped from skeleton output regardless of their absence from this enumeration (skeleton field sets are whitelist, not blacklist).

The design principle for every skeleton: classification metadata and lifecycle traceability are retained; substantive content is stripped. A reader of a skeleton entity can verify that the entity exists, see how it is classified, and trace its lifecycle, but cannot read its substantive content.

Vocabulary (special case — layer-based, not field-based)

The vocabulary block is not subject to skeleton field semantics. Public projection retains the field and specialty layers in full and strips the org, team, and individual layers (per ILD-131 and S036 OQ-A). This rule is specified in §10.3's section default table; no entity-level visibility declaration applies to the vocabulary block.

Identity

• Skeleton fields: project, entity, type, tier, posture, blast_radius, created, status
• Stripped fields: description, owner, contact, metrics, team, notes
• Rationale: Project fingerprint (what it is, who governs it, when it started, current operational state) is retained. Personnel (owner, contact, team), substantive description, quantitative metrics, and freeform notes are stripped.
• Governing decisions: ILD-150 (skeleton normative across entity types); ILD-139 (sensitive content guidance for metrics).

Identity defaults to public per the section default table (§10.3); skeleton on identity is meaningful only when an operator explicitly downgrades.

Milestones

• Skeleton fields: id, name, status, target, completed, session
• Stripped fields: notes, items field content (see below)
• Items in skeleton: Each milestone item is reduced to id, status, gate. The text and notes fields are stripped from items.
• Rationale: Scope structure (which version contains which item slots) and progress (which items are done, which gate items remain) are retained. The substantive description of each item is stripped. Opening-session provenance is retained as lifecycle-traceability metadata, consistent with skeleton field sets for other entity types that carry session (per DR-010).
• Governing decisions: ILD-150 (skeleton normative); ILD-151 (nested inheritance — items inherit milestone visibility unless explicitly overridden); DR-010 (session added to milestone skeleton).

Decisions (DR, OQ, ILD)

• Skeleton fields (all subtypes): id, title, status, session, blast_radius, scope, decision_date
• Stripped fields (all subtypes): notes, origin, closed_in
• DR additional skeleton fields: companion (location reference, not content), reviewed_by, superseded_by
• OQ additional skeleton fields: impact
• OQ additional stripped fields: resolution_path
• ILD additional skeleton fields: superseded_by
• Rationale: Decision metadata (what was decided, what status, what scope, when it became binding) is retained. Substantive notes, resolution paths, and provenance trails are stripped. Title is retained because it is the decision's identity; operators with sensitive titles SHOULD use internal visibility, not skeleton.
• Governing decisions: ILD-150; ILD-165 (blast_radius common); ILD-173 (scope common); ILD-174 (decision_date common).

Concerns

• Skeleton fields: id, type, severity, status, session, closed_in
• Stripped fields: text, ref, resolution, blocks, notes, origin
• Rationale: Concern classification (what kind of deficiency, how severe, what state) and lifecycle provenance (which session opened it, which session closed it) are retained. Substantive description, resolution narrative, and block relationships are stripped.
• Governing decisions: ILD-150; ILD-67 (universal concern types); ILD-148 (severity scale).

Actions

• Skeleton fields: id, status, priority, due, closed_in, session
• Stripped fields: text, assignee, origin, depends_on, resolution, notes
• Rationale: Action lifecycle (what state, what priority, when due, when closed, what session formalized it) is retained. Personnel (assignee), substantive description, dependencies, and resolution narrative are stripped. The deliberate omission of text from skeleton means a reader sees that an action exists and where it is in its lifecycle, but not what the action requires.
• Governing decisions: ILD-150; ILD-162 (priority on actions); ILD-166 (assignee SHOULD, not MUST).

Sessions

• Skeleton fields: id, date, title, purpose, mode, participants
• Stripped fields: produced, decisions_made, state_changes, next_action, notes, duration, planned_duration, origin
• Rationale: Session structural metadata (when it happened, what kind of session, who was present, what mode of communication) is retained. Substantive output (produced, decisions_made, state_changes, next_action) and operational telemetry (duration, planned_duration) are stripped. Participants are retained because the governance trail "who was in the room" is part of session identity.
• Governing decisions: ILD-137 (S024 — session skeleton field set, the precedent for all other entity skeletons).

Queued items

• Skeleton fields: id, title, status, session, priority, scope, closed_in
• Stripped fields: prompt, depends_on, origin, notes
• Rationale: Queue lifecycle metadata (what is planned, what state, how big, when closed) is retained. Substantive prompt content, dependency graph, and notes are stripped.
• Governing decisions: ILD-150; ILD-39 (priority on queued items); ILD-163 (scope on queued items).

Notes

• Skeleton fields: id, date, session
• Stripped fields: text, origin
• Rationale: Note existence and provenance (when, which session) are retained. The note's content is stripped. Skeleton on notes is meaningful for audit-trail purposes — proving that observations were recorded without disclosing what was observed.
• Governing decisions: ILD-150; ILD-164 (notes gain id).

Behavior on extension fields

Domain profiles and individual projects MAY introduce additional fields on entities (per the extension point model in PQDX-STD-0002). Such extension fields are stripped from skeleton output unless explicitly enumerated in this section.

A future revision of this specification MAY add extension fields to skeleton field sets — for example, if a domain profile field becomes commonly-needed for skeleton-projection purposes, the schema could be amended to include it. Until such amendment, conformant projection tools strip all non-enumerated fields.

This whitelist approach is the security-conservative default: an operator adding a new field cannot accidentally publish its content via skeleton projection without an explicit schema amendment.

§10.6Projection Algorithm

The projection algorithm transforms a canonical state file into a public projection file. The transformation is mechanical, deterministic, and reproducible across implementations: two conformant projection tools given the same canonical state file, the same loaded vocabulary profiles, and the same posture declaration MUST produce byte-identical projection output.

The algorithm is a strict subset operation (per ILD-138). The projection emits a subset of the canonical's content — never modified, paraphrased, summarized, or substituted. Stripping fields and omitting entries are the only permitted transformations.

§10.6.1 Inputs

A projection algorithm implementation accepts:

1. Canonical state file ({project}.state.yaml), parsed into the schema's data model.
2. Vocabulary profiles referenced in the canonical's vocabulary block, loaded and resolved per PQDX-STD-0002 §6.5.
3. Posture declaration read from the canonical's identity.posture field (or the default private if absent).

§10.6.2 Preconditions

Before generating a projection:

1. The canonical state file MUST validate against the pqdx/2.0.0 schema. Tools MUST refuse to project an invalid canonical.
2. identity.posture MUST be public. Tools MUST refuse to generate a projection for private posture (no projection is needed) or for custom posture without explicit operator opt-in (custom posture's projection mode is operator-declared).
3. The canonical MUST NOT itself carry the top-level projection key (per §10.4). Tools encountering a projection key on a canonical MUST emit a structural error and refuse.

If any precondition fails, the tool emits an error describing the failure and exits without producing output.

§10.6.3 Output scaffold

The projection's top-level structure is constructed in this order:

1. schema_version — copied verbatim from canonical.
2. projection: public — added to identify the file as a projection (per §10.4 and ILD-152).
3. vocabulary — emitted per §10.6.5 (vocabulary projection).
4. identity — emitted per §10.3 visibility resolution. Identity defaults to public; skeleton applies if the operator marked identity skeleton; the entity is omitted entirely if marked internal.
5. Each remaining section (milestones, decisions, concerns, actions, sessions, queued, notes) — emitted per §10.6.4 (section processing).

Sections that produce empty output (all entries internal, or section was empty in canonical) MUST be emitted as empty arrays ([]), not omitted. The eleven top-level keys present in canonical state files are also present in projections; absence of a key is reserved for forward compatibility, not for "no entries to emit."

§10.6.4 Section processing

For each entity-bearing section in the canonical:

1. Iterate entries in canonical order. The projection MUST preserve the canonical's entry order; reordering is a structural violation.
2. For each entry, compute the entry's resolved visibility per §10.3 resolution order (explicit value → parent inheritance → section default → internal floor).
3. Apply visibility to determine emission:
   • internal — Skip the entry entirely. The projection contains no record of the entry.
   • skeleton — Emit the entry with only the fields enumerated in §10.5 for the entity type. All other fields are stripped.
   • public — Emit the entry with all fields present in the canonical, with no field-level filtering (per ILD-140 — the entry is the unit of trust).
4. Nested entities (milestone items, produced artifacts) are processed within their parent's emission per §10.3 inheritance rules and §10.5 skeleton field sets.

§10.6.5 Vocabulary block projection

The vocabulary block in the projection retains the field and specialty layers from the canonical and strips the org, team, and individual layers (per §10.3 section default rule and ILD-131).

The retained layers are emitted in their full canonical form; profile entries within retained layers are not subject to per-entity visibility filtering. Stripped layers MUST be emitted as empty arrays:

vocabulary:
  field:
    - profile: pqdc-software-dev
      version: 1.0.0
  specialty: []
  org: []
  team: []
  individual: []

The five-layer key inventory is preserved structurally regardless of which layers contain content (per ILD-114).

§10.6.6 Serialization conventions

For byte-deterministic output, conformant projection tools MUST emit YAML following these conventions:

1. Encoding. UTF-8 with no byte-order mark.
2. Line endings. LF (\n). CRLF is non-conformant.
3. Final newline. A single trailing newline at end of file.
4. Indentation. Two-space indentation for nested structures. Tabs are non-conformant.
5. Key order within mappings. Schema-canonical order. For each entity type, the field order is the order specified in the entity's schema definition (PQDX-STD-0001a). Operator-authored field order in canonical is NOT preserved in projection output.
6. List style. Block style for multi-element lists in most sections. Flow style is required for milestone items (per ILD-22) and for inline arrays (decisions_made, depends_on, blocks, blocked_by per PQDX-GDE-0001 Rule 5). Empty arrays use the flow-style empty literal [].
7. String quoting. Double quotes only when required by YAML grammar (strings containing colons, leading/trailing whitespace, ambiguous values such as yes/no/true/false, or starting with reserved characters). Otherwise unquoted.
8. Multi-line strings. Folded scalar (>) for prose; literal scalar (|) for content where line breaks are semantically significant. The choice MUST follow the form used in the canonical.
9. Boolean and null serialization. Booleans as true / false. Nulls as the literal null, never as empty string.
10. Date serialization. ISO 8601 dates as unquoted bare strings (YYYY-MM-DD).
11. Numeric serialization. Integers as bare integers; decimals as bare decimals with a leading digit (0.5, never .5).
12. Comments. Comments in the canonical are NOT preserved in the projection. Comments are operator authoring aids; they do not survive projection.

These conventions are defined normatively to ensure projection determinism. Tools whose YAML serialization library produces output deviating from these conventions MUST apply a post-processing step to normalize the output before writing.

§10.6.7 Conformance

A projection tool is conformant with §10.6 when, for every well-formed canonical state file with identity.posture: public and a fully resolved vocabulary stack, it produces byte-identical output to the reference implementation.

The reference implementation for pqdx/2.0.0 is currently pqdx-rs's prototype projection tool (per DR-009 Risks & Mitigations: "Block production tooling implementations until SD-6 resolution lands the algorithm spec inside STD-0001's trust boundary section"). Reference status will transfer to pqtf (Piqued Transform) when shipped.

A projection tool that diverges from byte-identity is non-conformant. Divergences are a structural defect, not a styling preference — non-conformance breaks the audit invariant that the public projection is a deterministic function of canonical state plus posture.

§10.6.8 Regeneration discipline

Per ILD-142, the projection file MUST be regenerated before any push to a public-tracked branch. Tools generating projections SHOULD provide a CI guard mode that:

1. Regenerates the projection from the current canonical.
2. Compares the regenerated output against the committed projection file.
3. Fails if they differ.

This discipline catches stale projections before they reach published surfaces. The pattern is analogous to go mod tidy or gofmt -d CI checks.

Operators MAY suppress regeneration during local edits, but the CI guard MUST run on every public-branch push. A drift between committed projection and current canonical is a governance defect.

§10.7Standard Infrastructure vs Project-Authored Content

A pqdx-governed repository contains two categories of content within .pqdx/:

• Standard infrastructure — files distributed by pqsn spec push (or equivalent distribution mechanism) that are identical across all projects governed by the same standard version. The standard schema specs, bundled vocabulary profiles, ecosystem documents (Piqued Manifesto, C² Methodology), and standard-level decision records.
• Project-authored content — files written by the project's operators for the project's own purposes. Session artifacts, project-specific decision records, project-specific runbooks, project-specific documentation.

These categories carry different posture implications. This section specifies the distinction and the projection rules that follow from it. The discrimination mechanism for project-authored mixed- provenance directories is deferred to OQ-11.

§10.7.1 Standard Infrastructure

Files in .pqdx/spec/ and .pqdx/vocab/ are standard infrastructure when they originate from pqsn spec push distribution. These directories are managed by distribution tooling (currently pqsn, future pqtf); their contents are identical across all projects governed by the same standard version.

Standard infrastructure is not subject to project posture filtering. The contents of .pqdx/spec/ and .pqdx/vocab/:

• MUST be tracked in version control regardless of project posture.
• MUST be present in fresh clones for the project's governance to be operational.
• Are not subject to the projection algorithm in §10.6 — the projection algorithm operates on the state file, not on infrastructure files alongside it.

Rationale: standard infrastructure is the project's governance configuration, not project-authored content. A public-posture project cannot omit .pqdx/spec/ from its public-tracked tree — the spec is what tells consumers (and tools) which standard the project is governed by. Withholding it would render the project ungovernable.

Vocabulary layer exception. Per ILD-222, vocabulary profiles are organized by layer in .pqdx/vocab/{layer}/ subdirectories. The org, team, and individual layer subdirectories may contain operator-internal alias mappings; per §10.3 section default and ILD-131, only field and specialty layer profiles project to public-state. For public-posture projects, the org, team, and individual layer subdirectories MAY be gitignored at the directory level — this is gitignore-time filtering, distinct from projection-time visibility filtering. The directory structure persists via the structural persistence pattern (ILD-223 / ILD-224).

§10.7.2 Project-Authored Mixed-Provenance Content

Three .pqdx/ subdirectories contain content of mixed provenance:

• .pqdx/docs/ — project-authored governance documentation, sometimes alongside synced kit content (templates and references redistributed from upstream) and operator drafts.
• .pqdx/runbooks/ — project-authored operational procedures, sometimes alongside synced standard runbooks and operator drafts.
• .pqdx/sessions/ — session artifacts (prompts, captures, deliverables) produced during AI-collaborative work, whose individual provenance varies (project-authored deliverables, synced kit prompts, operator-internal verbatim transcripts).

For public posture, these directories require a mechanism to discriminate project-authored content (commits to public history) from synced kit content and operator-internal drafts (gitignored). Without such a mechanism, public-posture projects either commit content that should remain private, or rely entirely on operator discipline at authoring time — which is fragile.

This specification does NOT mandate a specific discrimination mechanism in pqdx/2.0.0. The choice is deferred to OQ-11 (per DR-009 §Alternatives Considered, Alternative D). Three candidate mechanisms with materially different trade-offs are tracked in OQ-11 for comparison-depth analysis:

• Filename-prefix re-allow — .gitignore re-allows files matching {project}-*.md. Two-line rule. Fragile under rename.
• Subdirectory-based provenance — docs/project/, docs/synced/, docs/drafts/ separate provenance at directory level. Increases nesting; provenance is explicit.
• Frontmatter-based discrimination — each doc carries a visibility: field; gitignore via metadata. Most flexible; requires tooling support.

OQ-11 will select among these (or compose them) and produce the normative mechanism via a follow-on Decision Record.

§10.7.3 Interim guidance pending OQ-11

Until OQ-11 resolves, public-posture projects MUST address provenance discrimination through one or more of the following operational patterns:

1. Operator discipline at PR-review time. Reviewers verify that commits to .pqdx/docs/, .pqdx/runbooks/, and .pqdx/sessions/ contain only project-authored content intended for the public surface. This is the minimum pattern; it is fragile but workable at small operator counts.

2. Recursive ignore plus structural persistence (per ILD-223 and ILD-224). The standard .pqdx/ subdirectory structure persists in fresh clones via .gitkeep re-allow rules; content within those subdirectories is gitignored except where explicit re-allow rules opt content in. This is the pattern prototyped in pqdx-rs:S001 and adopted by DR-009 for both private and public postures.

3. Filename-prefix re-allow (per the pqdx-rs:S001 prototype, ungoverned by this specification at v2.0.0). Operators MAY apply !/{project}-*.md re-allow rules to .pqdx/docs/ and .pqdx/runbooks/ as a transitional pattern. Operators choosing this path SHOULD document the choice as a project-local deviation pending OQ-11 resolution.

Operators MUST NOT treat the absence of an OQ-11 resolution as license to commit operator-internal content to public history. The OQ-11 deferral is a deferral of mechanism choice, not of the underlying constraint that operator-internal content stay out of public-tracked surfaces.

When OQ-11 resolves with a chosen mechanism, public-posture projects following interim patterns SHOULD migrate to the resolved mechanism. The migration cost is tracked as part of OQ-11's downstream impact.

§11.1Schema Version Validation

Tools MUST check schema_version before processing. The value MUST match pqdx/{semver}. Major mismatch SHOULD cause a warning or refusal. Minor excess SHOULD warn but MUST NOT reject. Patch difference is fully compatible.

§11.2Top-Level Key Validation

All eleven keys (§1.2) MUST be present. Tools SHOULD warn on unknown top-level keys but MUST NOT reject the file (per ILD-153).

§11.3Vocabulary Block Validation

The vocabulary mapping MUST have exactly five keys: field, specialty, org, team, individual. All five MUST be present. Each key's value MUST be a sequence (empty [] is valid). Each entry in a layer MUST have profile (string) and version (string) fields.

§11.4Entity ID Validation

Uniqueness

IDs MUST be unique within their containing sequence:

• Decision IDs unique within decisions (across all three subtypes)
• Concern IDs unique within concerns
• Action IDs unique within actions
• Session IDs unique within sessions
• Queued item IDs unique within queued
• Note IDs unique within notes
• Milestone IDs unique within milestones
• Milestone item IDs unique within their parent milestone's items

Pattern Validation

Entity ID sequence numbers are unbounded decimal integers. Canonical spelling: Session and DR are zero-padded to a minimum of three digits; OQ, ILD, concerns, queued, and notes carry no leading zeros. Consumers MUST order IDs by integer value, never lexically.

§11.5Status Validation

Each stateful entity type has a closed status set. Tools MUST reject unknown status values.

§11.6Required Field Validation

Tools MUST verify that all MUST-level fields are present and non-empty on every entity. The specific fields are documented per entity type in §2–§9.

§11.7Milestone Completion Guard

When a milestone has status: complete, tools MUST verify the three conditions in §3.4. Violation is an error.

§11.8Value Set Validation

For all fields with closed value sets (status, severity, impact, priority, blast_radius, tier, type, purpose, mode, format, participant type, participant role), tools MUST validate that the value is in the enumerated set. Unknown values are errors for immutable fields, warnings for aliasable fields (the value may come from a vocabulary profile the tool doesn't have).

§11.9Concern Prefix-Type Agreement

The concern ID prefix and type field MUST agree. A concern with id: BL-1 MUST have type: blocker. The universal mapping is defined in §5.3. Domain profiles extend this mapping — tools SHOULD load available vocabulary profiles to validate domain-specific prefixes.

§11.10Visibility Validation

When present, the visibility field MUST have a value of internal, skeleton, or public. Unknown values are errors. Full value semantics, resolution order, section defaults, and inheritance rules are specified normatively in §10.3.

§11.11Skeleton Field Sets

The normative skeleton field sets for every entity type are specified in §10.5. When generating projections, tools MUST use those field sets for entities with resolved visibility skeleton; only the enumerated fields are preserved and all others are stripped. Two independent implementers MUST produce identical skeleton output for the same input entity (per §10.5 conformance requirement).

§11.12Projection Validation

Files with projection: "public" MUST NOT contain entities with visibility: internal. Tools SHOULD warn if a projection file contains internal entities — this indicates a generation error. The full projection algorithm and conformance requirements are specified in §10.4 (projection key) and §10.6 (projection algorithm); §11.17 specifies additional structural-consistency rules between canonical and projection files.

§11.13Cross-Entity Reference Validation

Tools MUST NOT error on unresolvable entity references in depends_on, blocked_by, blocks, decisions_made, superseded_by, or cross-project references. The referenced entity may be in another project, may not yet exist, or may have been removed from scope.

Tools MAY warn on unresolvable references as an aid to the author.

§11.14Date Validation

All date fields (created, date, completed, due, decision_date) MUST parse as valid ISO 8601 dates (YYYY-MM-DD) when present.

§11.15Resolution Guard

Concerns with status: resolved MUST have a resolution field. Concerns with status: open MUST NOT have a resolution field.

§11.16Posture Validation

The following rules govern the identity.posture field:

1. When identity.posture is present, its value MUST be one of private, public, custom. Unrecognized values are validation errors.
2. When identity.posture is absent, validators MUST treat the file as posture private (per §10.2 defaulting behavior).
3. When identity.posture is public, the file MUST NOT carry the top-level projection key (per §10.4 — the projection key is valid only on generated projection files).
4. When identity.posture is public, validators SHOULD verify that a corresponding {project}.public-state.yaml projection file exists in the canonical's directory, OR that the project's documentation declares the projection as regenerable. Validators MUST NOT block on absence — projection generation may be deferred to a build step.
5. When identity.posture is custom, validators SHOULD warn if onboarding documentation is not present at conventional locations (README.md, CONTRIBUTING.md, .pqdx/docs/). Validators MUST NOT block on custom posture; the value is informational.
6. Tools MUST NOT silently rewrite or "upgrade" absent posture fields to explicit private (per §10.2). Migration tools that explicitly add the field at operator request MAY do so; non-migration operations MUST NOT.

§11.17Projection Consistency

The following rules govern the relationship between a canonical state file and its generated public projection:

1. A file carrying the top-level projection: public is a generated projection file. Tools MUST NOT treat it as canonical, MUST NOT apply patches to it via apply_patch or equivalent canonical-mutation operations, and SHOULD treat it as read-only.
2. A canonical state file (one without the projection key) at .pqdx/{project}.state.yaml whose identity.posture is public MUST have its projection regenerated before any push to a public-tracked branch (per §10.6.8 and ILD-142).
3. The vocabulary block in a projection MUST contain only field and specialty layer entries (per §10.6.5). Validators encountering org, team, or individual layer entries in a file carrying projection: public MUST flag a structural error.
4. Entities marked visibility: skeleton in a projection MUST contain only the fields enumerated in §10.5 for the entity type. Additional fields beyond the skeleton field set are structural errors.
5. Entities marked visibility: internal MUST NOT appear in a projection. Any record of an internal entity in a file carrying projection: public is a structural error.
6. The projection's section ordering and entry ordering within each section MUST match the canonical's order (per §10.6.4 — projection is order-preserving). Reordering is a structural defect.
7. The projection MUST be a strict subset of the canonical (per ILD-138). Any field value in a projection that does not match the corresponding field in the canonical (after applying skeleton stripping) is a structural error indicating the projection has been modified outside the projection algorithm.

§11.18Validator Diagnostic Completeness

(MUST)

Within a single validation invocation, a pqdx validator MUST emit all diagnostics surfaced by its validation rule set rather than terminating after the first diagnostic.

Scope of "single invocation"

For batch validators (whole-file validation entry points such as a CLI validator invoked on a state file), a single invocation covers the full input. For incremental validators that validate per-operation (such as MCP-server patch-entry validators), a single invocation covers all operations submitted in one call; diagnostics from across operations MUST be aggregated into a single diagnostic set, and individual diagnostics SHOULD be tagged with their originating operation when more than one operation is present in the batch.

Exception — irrecoverable source-syntax failures

A validator MAY emit a single diagnostic and terminate early when the underlying source representation cannot be parsed under the YAML 1.2 grammar (for example: unterminated block scalar, structurally invalid token stream, malformed UTF-8 at the byte level). The exception applies only to YAML-grammar-level corruption of the source representation. It does NOT apply to:

• typed-conversion failures,
• structural-rule violations (including ID uniqueness violations),
• referential-rule violations (including missing-target failures on update operations),
• lifecycle-rule violations (including terminal-state gate failures),
• visibility-rule violations,
• projection-rule violations,
• or any other rule violation across one or more sections of the parsed input.

Partial-validity continuation

When typed-conversion fails for one entity or one top-level section, validator passes (structural, referential, lifecycle, visibility consistency, projection determinism) MUST continue to operate on the typed-conversion-successful subset. When one entry within a multi-operation batch fails validation, the validator MUST continue validating subsequent entries. Diagnostics produced by downstream passes against a partial-result subset MAY include a help-text marker indicating the upstream cause when the downstream diagnostic is a direct consequence of the missing typed entity.

Rollup thresholds

Reserved for a future additive update. At pqdx/2.0.0 this rule does not permit rollup-style diagnostic suppression; an implementation MUST emit all diagnostics surfaced by its validation rule set, subject only to the partial-validity continuation clause and the irrecoverable-source-syntax exception above.

Conformance verification

pqdx-conformance provides multi-error fixtures under parser/multi-error-*/, validator/structural/multi-error-*/, validator/referential/multi-error-*/, and validator/lifecycle/multi-error-*/. Each multi-error fixture asserts an expected diagnostic set of size N ≥ 3 using set-equality semantics (order tolerated, contents exact) per pqdx-conformance fixture conventions. An implementation claiming parser or validator capability MUST emit a diagnostic set whose contents exactly match the fixture's expected set for each multi-error fixture's input. The conformance fixture set MUST include at least 2 fixtures per validator pass category and at least 1 cross-cutting fixture combining parser, structural, and referential diagnostics in a single input.

Normative Note: Tool-Behavior Rules in §11

§11.18 is a validator-behavior rule (governing how diagnostics are emitted) rather than a state-file-property rule (governing what a valid state file looks like). It is placed in §11 following the §10.6 precedent — the projection algorithm, a tool-behavior rule, sits alongside state-file-property rules in §10 without sub-section split. Should additional validator-behavior rules accumulate (3+ beyond §11.18), §11 and §10 may be reorganized into structural/behavioral sub-sections via a future spec-organization DR.