# ═══════════════════════════════════════════════════════════════════════ # pqdx/2.0.0 Annotated Schema # ═══════════════════════════════════════════════════════════════════════ # # PQDX-STD-0001a — Annotated YAML # Structural companion to pqdx-schema-spec.md (PQDX-STD-0001b) # # PURPOSE: # The canonical field inventory for pqdx/2.0.0. Every field, every # constraint, every valid value, every extension point — documented # inline. This is the structural contract that validators and tool # builders implement against. # # THIS FILE IS NOT A TEMPLATE. # To bootstrap a new project, use pqdx-template.yaml (PQDX-STD-0001c). # # DOCUMENT SET: # PQDX-STD-0001a pqdx-schema-spec.yaml Annotated schema (this file) # PQDX-STD-0001b pqdx-schema-spec.md Prose specification # PQDX-STD-0001c pqdx-template.yaml Bare template # PQDX-STD-0001d pqdx-fixture.state.yaml Canonical fixture # PQDX-GDE-0001 pqdx-patching-guide.md Patching guide # PQDX-GDE-0002 pqdx-directory-reference.md Directory reference # # AUDIENCES: # Human — project stewards reading/editing in any text editor # AI — session tools consuming the file for orientation # Machine — validators, dashboards, parsers, linters # # PRINCIPLES: # 1. Structure vs. vocabulary — schema is rigid on structure, # permissive on vocabulary via vocabulary profiles # 2. Consumer Question Test — every field has a named consumer # and a named question it answers # 3. Chronological, append-only — arrays are oldest-first; # new entries appended, existing entries never reordered # 4. ID-prefixed entities — every trackable thing has a unique, # typed ID that is never reused # 5. Lifecycle-driven — every stateful entity has defined states, # transitions, guards, and terminal states # 6. Unified provenance — every entity tracks where it came from # via session + origin (§1.4) # 7. Visibility-aware — every entity supports trust boundary # projection via optional visibility field (§1.7) # # STANDARD: # Home: pqdx.dev # Prose spec: pqdx-schema-spec.md (PQDX-STD-0001b) # Reference validator: pqdc-cc validateState() (per DR-004) # # COPYRIGHT: # © 2026 Our Collaborative Space, LLC — CC-BY-ND 4.0 # pqdx™ and pqdc™ are trademarks of Our Collaborative Space, LLC. # # ═══════════════════════════════════════════════════════════════════════ # ─── §1.1 Schema Version ──────────────────────────────────────────── # REQUIRED. String. Pattern: pqdx/{semver} # Tools read this first. Major mismatch = warn/refuse. # Minor excess = process with warning. Patch = fully compatible. schema_version: "pqdx/2.0.0" # ─── §1.2 Top-Level Key Inventory ─────────────────────────────────── # Eleven keys: schema_version, vocabulary, projection, identity, # milestones, decisions, concerns, actions, sessions, queued, notes. # Tools SHOULD warn on unknown top-level keys but MUST NOT reject # the file (forward compatibility with future schema versions). # ─── §1.3 Vocabulary Block ────────────────────────────────────────── # REQUIRED. Mapping with exactly five layer keys (per DR-005, ILD-109). # Each layer holds a sequence of { profile, version } entries. # All five keys MUST be present — empty layers use [] (per ILD-114). # # Layers (lowest → highest precedence): # field — "How do we build?" — discipline vocabulary # specialty — "Who do we build for?" — intersection vocabulary # org — "Who are we?" — organization conventions # team — "Which team?" — team-level conventions # individual — "Personal prefs?" — individual display/workflow # # Precedence: # Cross-layer: individual > team > org > specialty > field # Within-layer: array order, first wins (per ILD-88) # # Resolution is advisory — tools MUST NOT fail if profiles are missing # (per ILD-87). Tools resolve profile names to {name}.vocab.yaml in # .pqdx/vocab/ directory (per ILD-145). vocabulary: field: [] specialty: [] org: [] team: [] individual: [] # ─── Projection (top-level key) ───────────────────────────────────── # OPTIONAL. String. Conditional presence (per STD-0001b §10.4): # MUST NOT be present on canonical state files. # REQUIRED on generated projection files. # Values: "public" (closed set in v2.0.0; future projection types # reserved as additional values). # Consumer: any tool reading a state file. # Question: "Is this the canonical source or a generated projection?" # Tools SHOULD treat files with projection: public as read-only. # Extension point: IMMUTABLE in v2.0.0; additional types require # schema amendment. # Full specification: STD-0001b §10.4. # projection: "public" # ─── §1.4 Provenance Model ────────────────────────────────────────── # All entity types use a unified two-field provenance model (per ILD-23, # updated S027): # # session — MUST. String. Which session formalized this entity, or # the creation surface if created outside a session ("dashboard", # "direct", "migrated:jira-1234"). Value SHOULD be a valid session # ID in governed projects. # # origin — OPTIONAL. String. Freeform. Where the information came # from, when different from the formalizing session. If absent, # the entity originated in the referenced session. # # Cross-cutting closure field (applicable to concerns, actions, # queued items, milestones, and decisions): # # closed_in — OPTIONAL. String. SHOULD be present when an entity # reaches a terminal status. Records what transitioned the entity to # its terminal state. Normally a session ID (^S\d+$). The reserved # sentinel value "ad-hoc" denotes a terminal transition performed by # a direct state-file edit OUTSIDE any numbered session (e.g. an # ad-hoc hygiene or archive pass); "ad-hoc" is intentionally # non-resolving and MUST NOT be flagged as an unresolved reference. # Tools MUST NOT error on unresolvable references. # ─── §1.7 Visibility ──────────────────────────────────────────────── # Every entity MAY carry a visibility field: # visibility: internal | skeleton | public # # DEFAULT: When absent, visibility is "internal" (security-first per # ILD-149). # # The three levels: # internal — Entity does not appear in public projections. # skeleton — Entity appears in stripped form, retaining only the # fields enumerated in the entity type's skeleton field # set (STD-0001b §10.5). # public — Entity appears in projection in full. Asserts the # entire entry is safe to publish (per ILD-140). # # Resolution order (per STD-0001b §10.3): # 1. Explicit field value # 2. Parent inheritance (nested entities only — milestone items # and produced artifacts inherit their parent's resolved value) # 3. Section default (per STD-0001b §10.3 section default table) # 4. internal floor # # Section visibility defaults (NORMATIVE — STD-0001b §10.3): # schema_version public # vocabulary public (filtered — field/specialty layers retained; # org/team/individual layers stripped) # identity public # milestones public # decisions internal # concerns internal # actions internal # sessions skeleton # queued internal # notes internal # # Skeleton field sets (NORMATIVE — STD-0001b §10.5): # Identity: project, entity, type, tier, posture, blast_radius, # created, status # Milestones: id, name, status, target, completed, session # Milestone items (within skeleton milestone): id, status, gate # Decisions: id, title, status, session, blast_radius, scope, # decision_date (DR adds: companion, reviewed_by, # superseded_by; OQ adds: impact; ILD adds: # superseded_by) # Concerns: id, type, severity, status, session, closed_in # Actions: id, status, priority, due, closed_in, session # Sessions: id, date, title, purpose, mode, participants # Queued: id, title, status, session, priority, scope, closed_in # Notes: id, date, session # # Full normative specification: STD-0001b §10 (Trust Boundary). # Validation rules: STD-0001b §11.10 (visibility validation), # §11.16 (posture validation), §11.17 (projection consistency), # §11.18 (validator diagnostic completeness). # ─── Validator Behavior — Diagnostic Completeness (§11.18) ────────── # NORMATIVE — full specification: STD-0001b §11.18. # # 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": # Batch validators — single invocation = full input # Incremental validators — single invocation = all operations in # one call; diagnostics aggregate across # operations into a single set; diagnostics # SHOULD be tagged with originating operation # # Exception (narrow): # YAML 1.2 grammar-level corruption of the source representation # only. Does NOT apply to typed-conversion, structural (including # uniqueness), referential (including missing-target), lifecycle # (including terminal-state gates), visibility, or projection # violations — all of these MUST accumulate. # # Partial-validity continuation: # Failure of one entity/section/operation does NOT block subsequent # validation passes or subsequent entries. # # Rollup thresholds: # Reserved for future additive update. At pqdx/2.0.0, no rollup-style # suppression is permitted. # # Conformance verification (pqdx-conformance fixtures): # At least 2 multi-error fixtures per validator pass category # (parser, validator/structural, validator/referential, # validator/lifecycle), N ≥ 3 expected diagnostics per fixture, # set-equality semantics. At least 1 cross-cutting fixture combining # parser + structural + referential. # # Companion DR: DR-011 (.pqdx/decisions/DR-011-validator-diagnostic-completeness.md) # Origin: pqdx-rs:DR-003 (architectural commitment to hybrid # value-tree-then-validate; unblocks pqdx-rs:S008+ on # ratification of this rule) # ═══════════════════════════════════════════════════════════════════════ # §2 IDENTITY — What is this project? # ═══════════════════════════════════════════════════════════════════════ # The project's fingerprint. Answers "what am I looking at?" for any # consumer encountering the state file for the first time. identity: # ── Required Fields ── project: "" # REQUIRED. String. Non-empty. SHOULD be lowercase kebab-case. # MUST match the {project} portion of the filename. description: > Replace with a concise description of the project. Include: purpose, key constraints, primary audience. Target: 2-4 sentences. # REQUIRED. String (multi-line via YAML folded scalar >). entity: "" # REQUIRED. String. Non-empty. Freeform — abbreviation, full name, # or identifier for the owning organization. type: "" # REQUIRED. String. Non-empty. # Universal base types (10): docs, engagement, event, initiative, # procurement, product, program, research, response, service # Domain profiles add types via additive mechanism (§11.5). # Extension point: ADDITIVE. tier: "" # REQUIRED. String. Values: minimal | standard | full # Governance intensity: minimal (lightweight), standard (default), # full (maximum ceremony). # Extension point: ALIASABLE. owner: "" # REQUIRED. String. Non-empty. SHOULD be a full human name. # The single person accountable for the project. blast_radius: "" # REQUIRED. String. Values: negligible | low | medium | high | critical # Blast radius can go up, never down. Tools SHOULD warn on reduction. # Extension point: ALIASABLE. # posture: private # OPTIONAL. String. Values: private | public | custom. Default: private. # Declares the project's trust-boundary posture (per STD-0001b §10.2). # Validation rules in §11.16. Aliasable for display only — the # underlying enum values remain canonical in state file content. created: "" # REQUIRED. String. ISO 8601 date (YYYY-MM-DD). # ── Optional Fields ── # status: active # OPTIONAL. String. Default: active (when absent). # Values: active | dormant | archived | complete # Extension point: IMMUTABLE. # contact: "" # OPTIONAL. String. Freeform reachability (email, Slack, phone, URL). # repo: "" # OPTIONAL. String. Repository URL or shorthand identifier. # version: "" # OPTIONAL. String. Current release version. SHOULD follow semver. # metrics: # key: value # OPTIONAL. Mapping. Freeform quantitative indicators. # Content is domain-specific; structure is a valid YAML mapping. # Extension point: IMMUTABLE (structure); content is freeform. # notes: > # Operational context beyond the description. # OPTIONAL. String. Answers "what else should I know about this # project?" — e.g., rename history, access constraints, legacy refs. # team: # - { name: "", role: authority, type: human } # OPTIONAL. Sequence of participant objects. Supplements owner. # S028: Accepted (DR-002). Reuses session participant model. # # Each entry: # name: MUST. String. # role: MUST. Same 9-value set as session participants: # authority | driver | facilitator | contributor | observer | # executor | recorder | reviewer | recipient # type: MUST. Same 3-value set as session participants: # human | collaborator | agent # # Consumer: portfolio viewer, handoff recipient, AI tool routing. # Question: "Who works on this project and what are their roles?" # The identity team is the structural roster — who works on the # project overall. Session participants are the operational record — # who was present in each session. # Extension point: role and type are ALIASABLE (same as sessions). # visibility: internal # OPTIONAL. §1.7. Default: internal. # ═══════════════════════════════════════════════════════════════════════ # §3 MILESTONES — Where is this project going? # ═══════════════════════════════════════════════════════════════════════ # Scoped work packages with checklist items. IDs are freeform (versions, # phases, sprints, etc.). Unique within milestones. milestones: - id: "" # REQUIRED. String. Unique within milestones. name: "" # REQUIRED. String. SHOULD follow "{id} — {Short Description}". status: planned # REQUIRED. String. Values: planned | in-progress | on-hold | complete | cancelled # Lifecycle (§3.3): planned → in-progress → complete (with guard). # Terminal: complete, cancelled. Guard: §3.4 completion conditions. target: null # OPTIONAL. String or null. Freeform (date, relative ref, qualitative). # depends_on: [] # OPTIONAL. Sequence of entity IDs. Planned sequencing. # blocked_by: [] # OPTIONAL. Sequence of entity IDs. Emergent impediments (distinct # from depends_on — a dependency can be met and a blocker still exist). # completed: "" # OPTIONAL. ISO 8601 date. SHOULD be present when status is complete. # closed_in: "" # OPTIONAL. §1.4. SHOULD be present when status is complete or cancelled. # session: "" # OPTIONAL. §1.4 provenance. Session that introduced this # milestone into the project's plan. Non-session values permitted: # "dashboard", "direct", "migrated:jira-EPIC-1247". Per DR-010. # origin: "" # OPTIONAL. §1.4 provenance. Freeform. Where this milestone # originally came from, when different from session. Per DR-010. notes: > Context about this milestone. # OPTIONAL. String. # visibility: internal # OPTIONAL. §1.7. Default: internal. items: - { id: "", text: "", status: open } # Item fields: # id: REQUIRED. Unique within parent milestone. Stable, never reused. # Convention: {milestone_prefix}-{N} (e.g., v01-1). # text: REQUIRED. Condition that can be verified true/false. # status: REQUIRED. Values: open | done | deferred | dropped | subsumed # All non-open states are terminal within the milestone. # Deferred = tombstone in source; fresh entry in target (ILD-43). # gate: OPTIONAL. Boolean. Default: false. When true, MUST be done # before parent milestone can complete (ILD-30). # notes: OPTIONAL. String. # visibility: OPTIONAL. §1.7. Inherits from parent milestone. # # Flow-style for scannability. Field order: id, text, status, [gate], [notes]. # Use block-style only when notes or extended context is needed. # ── Completion Guard (§3.4) ── # To transition to complete, a milestone MUST satisfy ALL of: # 1. At least one item with status: done # 2. Every gate: true item has status: done # 3. No item has status: open # ═══════════════════════════════════════════════════════════════════════ # §4 DECISIONS — What was decided? # ═══════════════════════════════════════════════════════════════════════ # Unified array: DR-NNN (formal), OQ-N (open questions), ILD-N (informal). # All three share one sequence — decisions interact across types. decisions: # ── Common fields (all three subtypes) ── # id: REQUIRED. Unique across the entire decisions array. # title: REQUIRED. String. Single sentence describing the decision. # status: REQUIRED. Values depend on subtype (see below). # session: MUST. §1.4 provenance. Session that formalized this. # origin: OPTIONAL. §1.4 provenance. Source when different from session. # blast_radius: OPTIONAL. Values: negligible | low | medium | high | critical. ALIASABLE. # scope: OPTIONAL. String. Freeform. What area/subsystem/domain this # decision constrains. S028: NEW. # Consumer: handoff recipient, portfolio viewer, dashboard filter. # Question: "What does this decision apply to?" # Projects SHOULD establish scope vocabulary early and use it # consistently across decisions for effective filtering/grouping. # Extension point: IMMUTABLE (freeform content). # decision_date: OPTIONAL. String. ISO 8601 date (YYYY-MM-DD). S028: NEW. # When the decision became binding — distinct from the session # date when the decision was proposed or formalized. # SHOULD be present on accepted DRs and resolved OQs. # Consumer: governance auditor, compliance reviewer. # Question: "When did this decision become binding?" # Extension point: IMMUTABLE. # notes: OPTIONAL. String. # visibility: OPTIONAL. §1.7. Default: internal. # ── DR — Decision Record ── - id: DR-001 # Pattern: ^DR-\d+$ (zero-padded, 3-digit minimum) title: "" status: proposed # Values: proposed | accepted | deferred | superseded | rejected | withdrawn # Terminal: superseded, rejected, withdrawn. session: "" # MUST. §1.4. # origin: "" # OPTIONAL. §1.4. # blast_radius: "" # OPTIONAL. ALIASABLE. # scope: "" # OPTIONAL. S028: NEW. Freeform — what area this DR constrains. # decision_date: "" # OPTIONAL. S028: NEW. When this DR was formally accepted. # SHOULD be present when status is accepted. # companion: "" # OPTIONAL (SHOULD for accepted). Location-schemed path to analysis doc. # Schemes: repo://, local://, url://, session://, project-knowledge://, # state://, pending:// # reviewed_by: [] # OPTIONAL. Sequence of strings (names). S028: NEW. # SHOULD be present on accepted DRs with critical or high blast_radius. # Records who reviewed and/or approved the decision. # Consumer: governance auditor, executive oversight. # Question: "Who reviewed and approved this decision?" # Extension point: IMMUTABLE. # superseded_by: "" # OPTIONAL. String (entity ID). S028: NEW. # SHOULD be present when status is superseded. # Consumer: decision archaeologist, handoff recipient. # Question: "What replaced this decision?" # Enables lineage tracing — follow the chain until a non-superseded # decision is reached. # Extension point: IMMUTABLE. # closed_in: "" # OPTIONAL. §1.4. SHOULD when terminal (superseded, rejected, withdrawn). # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. # ── OQ — Open Question ── - id: OQ-1 # Pattern: ^OQ-\d+$ (simple integer) title: "" status: open # Values: open | narrowed | deferred | resolved # Terminal: resolved. narrowed → open is invalid (ILD-47). session: "" # MUST. §1.4. # origin: "" # OPTIONAL. §1.4. # impact: "" # SHOULD be present. Values: negligible | low | medium | high | critical. ALIASABLE. # resolution_path: "" # OPTIONAL. Plan for answering this question. # blast_radius: "" # OPTIONAL. ALIASABLE. # scope: "" # OPTIONAL. S028: NEW. Freeform — what area this question affects. # decision_date: "" # OPTIONAL. S028: NEW. When this OQ was resolved. # SHOULD be present when status is resolved. # closed_in: "" # OPTIONAL. §1.4. SHOULD when terminal (resolved). # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. # ── ILD — Informal Locked Decision (S027: renamed from ID) ── - id: ILD-1 # Pattern: ^ILD-\d+$ (simple integer) title: "" status: locked # Values: pending | locked | superseded # pending = articulated, not yet confirmed. Authority deferred the lock. # locked = in effect. Binding. Most ILDs are born locked. # superseded = replaced by another decision. # Terminal: superseded. # Lifecycle: # pending → locked (authority confirms) # pending → superseded (different direction chosen) # locked → superseded (replaced after being in effect) # Invalid: locked → pending, superseded → any. session: "" # MUST. §1.4. # origin: "" # OPTIONAL. §1.4. # blast_radius: "" # OPTIONAL. ALIASABLE. # scope: "" # OPTIONAL. S028: NEW. Freeform — what area this ILD constrains. # decision_date: "" # OPTIONAL. S028: NEW. When the lock was confirmed. # Useful for ILDs that start pending and later transition to locked. # superseded_by: "" # OPTIONAL. String (entity ID). S028: NEW. # SHOULD be present when status is superseded. # Same semantics as DR.superseded_by — enables lineage tracing. # Extension point: IMMUTABLE. # closed_in: "" # OPTIONAL. §1.4. SHOULD when terminal (superseded). # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. # ═══════════════════════════════════════════════════════════════════════ # §5 CONCERNS — What is broken, at risk, or missing? # ═══════════════════════════════════════════════════════════════════════ # Typed deficiencies. Type and status are orthogonal — all types share # one lifecycle (ILD-48). concerns: - id: "" # REQUIRED. Pattern: ^[A-Z]{1,4}-\d+$ # Universal prefixes: BL (blocker), DBT (debt), DEF (defect), # GAP (gap), KI (known-issue), RSK (risk), SD (stale-doc) # Domain prefixes declared via vocabulary profile triple-mapping (§5.3). type: "" # REQUIRED. Values: blocker | debt | defect | gap | known-issue | risk | stale-doc # Exhaustive closed set. Extension point: ALIASABLE. # Prefix and type MUST agree (§11.9). severity: "" # REQUIRED. Values: negligible | low | medium | high | critical # S027: negligible added — floor below low, distinguishes chore from fix. # 5-value scale matching blast_radius. # Mutable (ILD-60) — changes tracked in session state_changes. # Extension point: ALIASABLE. text: "" # REQUIRED. String. Substantive description of the deficiency. status: open # REQUIRED. Values: open | monitoring | deferred | resolved # Lifecycle (§5.2): # open → monitoring | deferred | resolved # monitoring → open | deferred | resolved # deferred → open | resolved # Terminal: resolved. # Extension point: IMMUTABLE. Aliasable for display only. session: "" # MUST. §1.4 provenance. S027: elevated from SHOULD to MUST. # origin: "" # OPTIONAL. §1.4 provenance. # ref: "" # OPTIONAL. String. Freeform. S028: NEW. # Which artifact has this deficiency — a file path, document name, # entity ID, or any identifier that locates the affected artifact. # Consumer: person fixing the deficiency, triage dashboard. # Question: "Where is the thing that's broken/at-risk/missing?" # Orthogonal to blocks (which answers "what does this impede?"). # Extension point: IMMUTABLE. # resolution: "" # MUST be present when status is resolved. MUST NOT be present when open. # closed_in: "" # OPTIONAL. §1.4. SHOULD be present when resolved. # S027: renamed from resolved_in — universal closure field. # blocks: [] # OPTIONAL. String or sequence. Entity IDs this concern impedes. # Passive annotation — does not change on status transitions (ILD-61). # MAY reference entities without a blocked status field (ILD-63). # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. Default: internal. # ═══════════════════════════════════════════════════════════════════════ # §6 ACTIONS — What does a human need to do? # ═══════════════════════════════════════════════════════════════════════ # Discrete tasks from session close-outs or dashboard creation. # Binary (done or not). actions: - id: A-1 # REQUIRED. Pattern: ^A-\d+$ (bare integer, no padding) text: "" # REQUIRED. String. Task description. session: "" # MUST. §1.4 provenance. S027: replaces source — unified provenance. # Value SHOULD be a valid session ID. Non-session values permitted # for dashboard or migration origins ("dashboard", "migrated:jira-1234"). # origin: "" # OPTIONAL. §1.4. S027: NEW — two-field provenance now available. assignee: "" # SHOULD. String. Who is responsible. # S027: relaxed from MUST — solo/lightweight projects may omit. # Tools SHOULD warn when absent. status: open # REQUIRED. Values: open | blocked | deferred | done | cancelled # Terminal: done, cancelled. # Lifecycle (§6.2): # open → done | blocked | deferred | cancelled # blocked → open | done | cancelled # deferred → open | cancelled # Extension point: IMMUTABLE. Aliasable for display only. # priority: "" # OPTIONAL. Values: negligible | low | medium | high | critical # S027: NEW — 5-value scale matching severity and blast_radius. # Extension point: ALIASABLE. # due: "" # OPTIONAL. ISO 8601 date. Purely informational — no auto-escalation (ILD-55). # depends_on: [] # OPTIONAL. Sequence of entity IDs. # resolution: "" # OPTIONAL. How this was completed. SHOULD be present when status: done. # closed_in: "" # OPTIONAL. §1.4. SHOULD be present when status is done or cancelled. # S027: NEW — universal closure field. # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. Default: internal. # ═══════════════════════════════════════════════════════════════════════ # §7 SESSIONS — What happened and when? # ═══════════════════════════════════════════════════════════════════════ # Chronological audit trail. Immutable after creation (except produced # sequence — artifacts may be appended with amendment note, per ILD-56). # Pattern: ^S\d+$ (zero-padded, 3-digit minimum). Never renumbered or deleted. sessions: - id: S001 # REQUIRED. Pattern: ^S\d+$ date: "" # REQUIRED. ISO 8601 date. title: "" # REQUIRED. String. Scannable session summary. purpose: "" # MUST. Values: coordination | discussion | evaluation | production | transfer # Extension point: ALIASABLE. mode: "" # SHOULD. S027: relaxed from MUST. Informal sessions may omit. # Values: live-verbal | live-text | async | async-verbal | automated | hybrid # S027: expanded from 3 to 6 values. # live-verbal — synchronous, speech primary (in-person, video, phone) # live-text — synchronous, text primary (chat, AI dialogue, pair programming) # async — asynchronous, text-based (email, PR review, document review) # async-verbal — asynchronous, recorded speech/video (Loom, voice messages) # automated — system-initiated or machine-only (CI/CD, multi-agent, pipeline) # hybrid — multiple channels or timing modes combined # Extension point: ALIASABLE. participants: - { name: "", type: human, role: authority } # MUST. Sequence, at least one entry. Each entry: # # name: MUST. String. # # type: MUST. Values: human | collaborator | agent # human = person # collaborator = AI in dialogue mode (contributes to decisions) # agent = AI in execution mode (carries out instructions) # S027: formalized as closed set. Extension point: ALIASABLE. # # role: MUST. Values (9): authority | driver | facilitator | # contributor | observer | executor | recorder | reviewer | recipient # authority = decision-maker, final say # driver = doing the primary work # facilitator = managing session process (S027: NEW) # contributor = actively participating, not driving # observer = present but passive # executor = carrying out instructions (not deciding) # recorder = documenting (not deciding) # reviewer = evaluating output # recipient = receiving a handoff # S027: formalized as closed set (9 values). Extension point: ALIASABLE. # # Flow-style recommended. # ── Timing Fields (§7.1a) ── # duration: "" # OPTIONAL. String. Freeform. S028: NEW. # How much time this session actually consumed (effort duration). # Consumer: process improver, project lead, time analyst. # Question: "How much time did this session consume?" # For async sessions, effort duration is more meaningful than # wall-clock span (e.g., "~2h effort across 3 days"). # Tools MAY parse common patterns ("2h 15m", "45m") but MUST NOT # reject unusual formats. # Extension point: IMMUTABLE. # planned_duration: "" # OPTIONAL. String. Freeform. S028: NEW. # How much time was allocated/estimated for this session. # Consumer: scheduler, process improver (for delta analysis). # Question: "How much time was allocated for this session?" # When both duration and planned_duration are present, tools MAY # compute and display the delta for retrospective analysis. # Extension point: IMMUTABLE. # ── Output Fields (§7.2) ── # produced: # - description: "" # # MUST. String. What this artifact is. # purpose: "" # # MUST. Values: analysis | communication | decision | design | # # implementation | instruction | reference | scaffold # # Extension point: ALIASABLE. # format: "" # # MUST. Values: audio | code | composite | data | diagram | # # image | prose | slides | spreadsheet | video # # S028: 10-value set validated and locked. # # Extension point: ALIASABLE. # location: "" # # MUST. Location-schemed string. # # Schemes: repo://, project-knowledge://, state://, session://, # # url://, local://, pending:// # # notes: "" # # OPTIONAL. S027: restored per ILD-21 original design. # # Additional context about this artifact. # # visibility: internal # # OPTIONAL. §1.7. Inherits from parent session. # decisions_made: [] # OPTIONAL. Sequence of decision IDs (DR-NNN, OQ-N, ILD-N). # state_changes: [] # OPTIONAL. Sequence of strings. Brief, past-tense descriptions. # ── Handoff Fields (§7.3) ── # next_action: "" # OPTIONAL (SHOULD be present). The most important field for # session continuity — what the next session reads first. # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. Default: internal. # NON-NORMATIVE: commonly set to skeleton for public projections. # ═══════════════════════════════════════════════════════════════════════ # §8 QUEUED — What governed work is planned? # ═══════════════════════════════════════════════════════════════════════ # Queued Items — identified work needing governed attention. May resolve # in a single session, span multiple sessions, or complete through async # work. S027: renamed from "Design Session, Queued" — entity type is # "Queued Item", not limited to design sessions. # Pattern: ^QI-\d+$ queued: - id: QI-1 # REQUIRED. Pattern: ^QI-\d+$ (simple integer) # S027: renamed from DS-Q. title: "" # REQUIRED. String. status: pending # REQUIRED. Values: pending | in-progress | deferred | complete | cancelled # Terminal: complete, cancelled. # pending → complete is invalid — must pass through in-progress (ILD-53). # No blocked status — depends_on covers sequencing (ILD-51). session: "" # MUST. §1.4 provenance. S027: NEW — fills provenance gap. # origin: "" # OPTIONAL. §1.4. S027: NEW. # prompt: "" # OPTIONAL. Location-schemed path or inline preparation material. # The prompt for an AI-collaborative session. Same schemes as # produced[].location. # priority: "" # OPTIONAL. Values: negligible | low | medium | high | critical # S027: NEW — 5-value scale, consistent with actions. # Extension point: ALIASABLE. # depends_on: [] # OPTIONAL. Advisory, not hard-blocking (ILD-50). Tools SHOULD warn # on unresolved deps at in-progress transition but MUST NOT block. # scope: "" # OPTIONAL. Freeform. Answers "how big is this planned work?" # S027: NEW — estimation context (e.g., "2-3 sessions", "1 sprint"). # closed_in: "" # OPTIONAL. §1.4. SHOULD be present when complete or cancelled. # S027: NEW — traces queued item to completing session. # notes: "" # OPTIONAL. # visibility: internal # OPTIONAL. §1.7. Default: internal. # ═══════════════════════════════════════════════════════════════════════ # §9 NOTES — Freeform observations # ═══════════════════════════════════════════════════════════════════════ # Timestamped, session-attributed commentary. No lifecycle, no status. # Append-only. S027: gains id field (N-N) for referenceability. notes: - id: N-1 # REQUIRED. Pattern: ^N-\d+$ (simple integer) # S027: NEW — makes notes referenceable, enables stable visibility # overrides and cross-entity linking. date: "" # REQUIRED. ISO 8601 date. session: "" # MUST. §1.4 provenance. S027: replaces source — unified provenance. # Value SHOULD be a valid session ID. Non-session values permitted # ("dashboard", "direct"). # origin: "" # OPTIONAL. §1.4. S027: NEW. text: > Self-contained observation. Reader should understand without finding the referenced session. # REQUIRED. String. Non-empty. # visibility: internal # OPTIONAL. §1.7. Default: internal. # ═══════════════════════════════════════════════════════════════════════ # QUICK REFERENCE — Entity ID Patterns # ═══════════════════════════════════════════════════════════════════════ # # DR-NNN Decision Record decisions[] zero-padded, 3-digit minimum # OQ-N Open Question decisions[] simple integer # ILD-N Informal Locked Decision decisions[] simple integer # {PREFIX}-N Concern concerns[] 1-4 uppercase chars + integer # A-N Action actions[] bare integer (no padding) # SNNN Session sessions[] zero-padded, 3-digit minimum # QI-N Queued Item queued[] simple integer # N-N Note notes[] simple integer # (freeform) Milestone milestones[] convention: version-style # (freeform) Milestone Item milestones[].items[] convention: {ms}-N # # IDs are unique within their containing sequence and never reused. # Cross-project references: {project}:{entity-id} (e.g., pqdc-cc:DR-004) # Bare IDs are project-local. # # 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. # # S027 changes: ID-N → ILD-N, DS-QN → QI-N, notes gain N-N. # ═══════════════════════════════════════════════════════════════════════ # EXTENSION POINT SUMMARY # ═══════════════════════════════════════════════════════════════════════ # # IMMUTABLE — all fields not listed below # ALIASABLE — vocabulary profiles map aliases via triple-mapping: # identity.tier (minimal, standard, full) # identity.blast_radius (negligible, low, medium, high, critical) # identity.team.role (9 values — same as session participant role) # identity.team.type (human, collaborator, agent — same as session) # concern.type (7 universal types) # concern.severity (negligible, low, medium, high, critical) # concern.status (display alias only) # decision.blast_radius (negligible, low, medium, high, critical) # oq.impact (negligible, low, medium, high, critical) # action.priority (negligible, low, medium, high, critical) # action.status (display alias only) # queued.priority (negligible, low, medium, high, critical) # session.purpose (5 values) # session.mode (6 values) # session.participant.type (human, collaborator, agent) # session.participant.role (9 values) # produced.purpose (8 values) # produced.format (10 values) # ADDITIVE — identity.type (10 universal base + domain additions) # DELEGATED — concern ID prefix mappings (vocabulary profile provides full mapping) # # # S028 CHANGE LOG # ═══════════════════════════════════════════════════════════════════════ # New fields: scope on decisions (all subtypes), # decision_date on decisions (all subtypes), # reviewed_by on DRs (sequence of strings), # superseded_by on DRs and ILDs, # ref on concerns, # team on identity (DR-002 accepted), # duration on sessions, # planned_duration on sessions # Value set locks: produced.format — 10-value set validated # DR acceptance: DR-002 — team/role model on identity # # # S027 CHANGE LOG # ═══════════════════════════════════════════════════════════════════════ # Prefix renames: ID-N → ILD-N, DS-QN → QI-N # Field renames: source → session (actions, notes), resolved_in → closed_in (concerns) # New top-level key: projection # New cross-cutting: visibility (§1.7), closed_in (§1.4), unified provenance # New fields: notes on identity, notes on produced artifacts, # priority on actions/queued, scope on queued, # session+origin on actions/queued/notes, # closed_in on concerns/actions/queued/milestones, # id on notes (N-N), visibility on all entity types # Value set changes: severity gains negligible (5-value), # impact gains negligible (5-value), # ILD status gains pending (3-state), # mode expanded to 6 values, # participant type formalized (3 values), # participant role formalized (9 values) # Requirement changes: session → MUST (decisions, concerns), # assignee → SHOULD (actions), # mode → SHOULD (sessions) # ═══════════════════════════════════════════════════════════════════════ # pqdx/2.0.0 Annotated Schema — PQDX-STD-0001a # © 2026 Our Collaborative Space, LLC — CC-BY-ND 4.0 # ═══════════════════════════════════════════════════════════════════════