# Decision Schema — Layer 3 Reusable Entity Type # KNO Schema Version: 0.1.0 # # Layer 3 reusable schema for decision entities — the "WHY" record that # pairs with AS2 activities (the "WHAT" record). When an agent or human # makes a non-trivial choice (which schema to evolve, which proposal to # approve, which transformation to apply, which option to route a # request to), the decision is recorded as a first-class .kno entity # with full context, options considered, evidence per option, rationale, # and outcome. # # DOMAIN: Decision recording across agent and human actors # PURPOSE: Auditable, versionable, relationship-bearing records of # choices the platform makes — distinguishable from # activities (events) and observations (signals). # # DESIGN DECISIONS: # - DD-D-01: Decisions are first-class entities (P1 single-output), # not embedded fragments inside activities. Each decision gets an # ID, slug, and TerminusDB version history. # - DD-D-02: VCS-Mandatory per bedrock kno-foundational-principles.md. # Every decision-entity write fires a TerminusDB commit (graceful # degradation: warning logged if VCS unavailable, write still # succeeds in primary store — same pattern as Hive saveEntity). # - DD-D-03: Open `decision_subtype` accommodates emergent decision # classes (e.g. A12 Hindsight's "ac_inference", A13 Drift Detective's # "guard_proposed") without schema changes. The closed `decision_type` # enum captures the broad lifecycle category; subtype refines. # - DD-D-04: `inferred: bool` distinguishes prospective decisions # (made before action) from retrospective (reconstructed after the # fact, e.g. by A12 Hindsight Reviewer #2007). Audit consumers can # filter on this; it is NOT a quality signal — both kinds are # legitimate. # - DD-D-05: `supersedes` is a typed relationship to a previous # decision this one revises. When a decision is revised, the # superseder is emitted as a fresh entity (not an in-place update); # audit trail preserves both. WOQL queries can walk the chain # backward via VCS history OR forward via supersedes references. # - DD-D-06: Deferred-XRI resolution in `affects[]`: at decision # time, an entity affected by the decision may not exist yet. # Schema accepts placeholder XRIs (`pspace://placeholder/`) # that are bound after the affected entity is created. Stable # entity XRIs replace placeholders in a later supersedes-chain # entry once binding is complete. # - DD-D-07: Per-option verdict + evidence (Framework F-5): # PASS/PARTIAL/FAIL/SKIP/UNTESTABLE. Same vocabulary used in # mini-retro scoped audits and the code-auditor skill. Consistency # across artifacts is intentional. # # Created for: M22-P2 F2 (#850), per #2018 futro carry-forward A-4. # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # BASIC TIER # ============================================================================= id: 01KQ402AC5H899P5PZ0FVVWZNZ slug: decision-schema type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "Decision Schema" purpose: | Define the schema for decision entities — the auditable, versionable artifact that records WHY a non-trivial choice was made. **Decision vs Activity vs Observation:** | Concept | What it records | Storage | Mutability | |---|---|---|---| | **Activity** (AS2) | An event happened ("X created Y") | postgres in pspace-activity | append-only | | **Observation** (F3 #851) | A signal worth noting ("event Y looks like pattern Z") | .kno files in `content/observations/` | append-only | | **Decision** (this schema) | A choice was made and these were the alternatives | .kno files in `content/decisions/` + TerminusDB VCS | append-only (revisions emit a new entity with `supersedes`) | The three are complementary. An agent that makes a choice typically emits all three: a `Decide` activity (event), one or more observations (signals that informed the choice), and a decision entity (the choice itself, with options and rationale). Drift Detective (#2013) and Hindsight Reviewer (#2007) are heavy consumers of decision entities for retrospective analysis. **Why versioned VCS storage?** Decisions evolve. A decision made in Q1 with the evidence then available may need revision in Q3 when new evidence surfaces. The VCS history preserves the original decision for audit; the `supersedes` relationship makes the revision discoverable; both versions stay queryable. **Why open `decision_subtype`?** The closed `decision_type` enum (5 values) captures the broad lifecycle category. Downstream agents need finer specialization that would explode the closed enum: - A13 Drift Detective: `drift_finding`, `surface_discovered`, `guard_proposed` - A12 Hindsight Reviewer: `ac_inference`, `ac_revision` - Capability provisioning agents: per-step decisions Closing the enum forces every persona PR to bump this schema. Keeping `decision_subtype` free-form (with a registry pattern available later if needed) avoids that pressure. Drift-guard catches typos by checking subtype usage frequency over time. **Layer 3 position:** Layer 3 reusable. Extends document-schema (Layer 2). Composed of identity / history / quality (Layer 1). # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01KQ402AC5H899P5PZ0FVVWZNZ timestamp: "2026-04-25T22:50:00Z" tool: manual issue: "https://github.com/PossibilityTruthy/possibility-space/issues/850" taxonomy: topics: - decisions - audit - vcs - agents - m22 keywords: - decision - choice - rationale - evidence - vcs-mandatory - audit-trail # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type — decisions are documents about a choice" composes: - xri: "kno://specs/identity-schema" reason: "id, slug, type, version" - xri: "kno://specs/history-schema" reason: "_history + VCS commit metadata" - xri: "kno://specs/quality-schema" reason: "quality field for confidence assessment" related_to: - xri: "kno://specs/activity-schema" reason: "Decisions emit a 'Decide' AS2 activity at the moment of choice; activity captures the WHAT, decision the WHY" - xri: "kno://specs/agent-card-schema" reason: "decision.decided_by references an agent's XRI; agents producing decisions declare relevant perception domains" - xri: "kno://specs/perception-domain-schema" reason: "decision.evidence may cite specific perception domains the decision drew on" - url: "https://www.w3.org/TR/activitystreams-vocabulary/" reason: "AS2 vocabulary defines the 'Decide' activity verb (registered for Possibility per #850)" quality: completeness: 0.9 last_reviewed: "2026-04-25" review_status: draft # ============================================================================= # HISTORY # ============================================================================= _history: version: 1 created: "2026-04-25T22:50:00Z" created_by: "claude" modified: "2026-04-25T22:50:00Z" modified_by: "claude" # ============================================================================= # SPECIFICATION # ============================================================================= spec: status: Draft changelog: - version: "0.1.0" date: "2026-04-25" changes: - "Initial creation for M22-P2 F2 (#850)" - "Closed decision_type enum (5 values) + open decision_subtype (DD-D-03)" - "inferred field for retrospective decisions (DD-D-04, A12 #2007)" - "supersedes relationship for revision lineage (DD-D-05)" - "Deferred-XRI resolution in affects[] (DD-D-06)" - "Per-option verdict + evidence following F-5 vocabulary (DD-D-07)" - "VCS-Mandatory storage per bedrock kno-foundational-principles.md (DD-D-02)" schema: type: object required: - id - slug - type - version - decision_type - context - decided_by properties: $schema: type: string const: "decision@0.1.0" description: "Schema declaration" id: type: string description: "Unique identifier (ULID) for this decision" examples: - "01KQ402AC5H899P5PZ0FVVWZNZ" slug: type: string description: | Kebab-case identifier. Decisions are usually slugged with a short summary of their nature plus a short hash or sequence, e.g. "f1-composition-option-c-2026-04-25" or "drift-guard-2030-add-env-scoping". Slugs help humans navigate the decision archive; the ULID is the canonical reference. type: type: string const: "decision" description: "Always 'decision' for instances of this schema" version: type: string description: "Semver of the decision entity itself (rare to bump; typically the whole decision is superseded instead)" # ----------------------------------------------------------------------- # CORE DECISION FIELDS # ----------------------------------------------------------------------- decision_type: type: string enum: - schema-evolution - proposal-approval - transformation-selection - routing-classification - configuration-change - other description: | Closed enum of broad decision categories: - schema-evolution: bump or extend a schema (e.g. F1 v0.2.0) - proposal-approval: accept/reject a structural proposal - transformation-selection: choose between competing transformers - routing-classification: decide which agent/path handles a request - configuration-change: alter platform configuration - other: subtype field carries the specialization decision_subtype: type: string description: | Open free-form refinement of `decision_type`. Examples in use: - A13 Drift Detective: "drift_finding", "surface_discovered", "guard_proposed" - A12 Hindsight Reviewer: "ac_inference", "ac_revision" - Capability orchestrator: "auth_realm_provision", "secret_store_provision" The subtype is informational; closed-enum routing should use decision_type as the primary axis and only consult subtype for specialization. inferred: type: boolean default: false description: | When true, this decision was reconstructed retrospectively (e.g. by A12 Hindsight Reviewer regenerating ACs from shipped work). When false (default), the decision was made prospectively (before or at the moment of the action). Inferred decisions are still legitimate audit artifacts; this field clarifies provenance. context: type: string description: | What prompted this decision. Should answer "why was a choice needed at this moment?" — the situation that demanded a decision. CommonMark may be used. options: type: array description: | The alternatives considered. SHOULD include at least 2 options when a decision was meaningful (a "decision" with one option is typically not a decision — it's an action). Each option records its evidence and a verdict so reviewers can see what was weighed. items: type: object required: - id - description - verdict properties: id: type: string description: "Stable identifier within this decision (e.g., 'option-a', 'extend-existing-schema')" description: type: string description: "Human-readable description of this option" evidence: type: array items: type: string description: | List of evidence strings. Each entry SHOULD be a citation or reference (e.g., "specs/agent-card-schema.kno line 30", "issue #2020 spike findings", "P1 retro #2017"). Evidence grounds the verdict. verdict: type: string enum: - PASS - PARTIAL - FAIL - SKIP - UNTESTABLE description: | Verdict on this option's viability. Same vocabulary used by the code-auditor and mini-retro scoped audit (F-5). confidence: type: number minimum: 0 maximum: 1 description: "Confidence in the verdict (0-1)" chosen: type: string description: | ID of the selected option (must match an `options[i].id`). Required for non-deferred decisions; may be null only when the decision is explicitly deferred (decision_type=other, decision_subtype=deferred). rationale: type: string description: | Why the chosen option was selected over the alternatives. Distinct from `context` (which describes the situation) — rationale describes the reasoning. CommonMark may be used. confidence: type: number minimum: 0 maximum: 1 description: | Overall confidence in the decision (0-1). Lower confidence decisions are candidates for `supersedes` revision when new evidence emerges. affects: type: array description: | XRIs of entities affected by this decision. Examples: - kno://specs/agent-card-schema (the schema this decision evolves) - pspace://capability/auth-realm/01HXYZ... (the capability instance affected) - pspace://placeholder/ (deferred binding — entity doesn't exist yet at decision time, see DD-D-06) Drift-guard test asserts no permanent placeholder XRIs in decisions older than 24h. items: type: string decided_by: type: string description: | XRI of the actor (agent or user) who made the decision. Examples: - pspace://agent/drift-detective - pspace://user/usr_01HXYZ... - pspace://system/code-auditor (for system-issued decisions) # ----------------------------------------------------------------------- # LINEAGE # ----------------------------------------------------------------------- supersedes: type: string description: | XRI of a previous decision this one revises. When non-null, this decision invalidates the prior; readers SHOULD prefer the most recent in the supersedes chain. The chain is discoverable forward (from old → new via incoming `supersedes` references) AND backward (from new → old via this field + VCS history). expires_at: type: string format: date-time description: | ISO-8601 timestamp after which this decision should be revisited. Optional. Used for time-bounded decisions (e.g., "approve auto-retransform for ADOPT items for 30 days"). Drift-guard surfaces decisions past their expiry. # ----------------------------------------------------------------------- # INTERMEDIATE FINDINGS (Framework F-3, Document-As-You-Go) # ----------------------------------------------------------------------- intermediate_findings: type: array description: | Findings observed during the decision process but not yet consolidated into the final rationale. F-3 pattern: persist intermediate state so reviewers can audit the process, not just the final outcome. Optional. items: type: object required: - timestamp - note properties: timestamp: type: string format: date-time note: type: string evidence: type: array items: type: string # ----------------------------------------------------------------------- # RELATIONSHIP TO ACTIVITY # ----------------------------------------------------------------------- activity_xri: type: string description: | XRI of the AS2 'Decide' activity emitted at the moment this decision was recorded. Bidirectional reference: decision → activity via this field; activity → decision via activity.object.xri. Optional but recommended; allows traversal across the activity stream and decision archive. # ============================================================================= # EXAMPLES # ============================================================================= examples: - title: "Schema evolution decision (F1 composition pattern)" description: "The decision to use Option C composition for agent-card v0.2.0, made during F1 of M22-P2" content: | $schema: decision@0.1.0 id: 01KQ402DEMOFOR1COMPOSITION slug: f1-agent-card-v020-composition-option-c-2026-04-25 type: decision version: 0.1.0 decision_type: schema-evolution decision_subtype: composition-pattern context: | F1 (#849) needed to add perception/goals/boundaries to agent-card-schema. Three composition options were viable: (A) migrate instances to declare $schema: agent-card@0.2.0 directly, (B) duplicate fields into service-config-schema, or (C) keep instances on $schema: service-config@0.3.0 with subtype: agent-card and add fields to agent-card-schema for the documented type. options: - id: option-a-migrate description: "Migrate all agent instances to declare $schema: agent-card@0.2.0 directly" evidence: - "spike #2020 findings" - "specs/agent-card-schema.kno v0.1.0 declares $schema const" verdict: FAIL confidence: 0.85 - id: option-b-duplicate description: "Add the new fields to BOTH agent-card-schema AND service-config-schema" evidence: - "would require maintaining two definitions" - "blindspot B-001 (schema inflation)" verdict: FAIL confidence: 0.9 - id: option-c-extend description: "Make agent-card-schema additive (v0.2.0); instances stay on service-config@0.3.0 + subtype: agent-card" evidence: - "spike #2020 §Composition" - "no breaking changes" - "echo-agent.kno + design-reviewer-v3.kno already follow the subtype pattern" verdict: PASS confidence: 0.95 chosen: option-c-extend rationale: | Strict-additive bump preserves all v0.1.0 fields and avoids breaking the 8 known direct schema references and 12 code consumers. Existing instances adopt v0.2.0 by adding the new optional blocks — no $schema change needed. confidence: 0.95 affects: - kno://specs/agent-card-schema - pspace://content/agents/echo-agent - pspace://content/agents/design-reviewer-v3 decided_by: pspace://user/max # human-driven decision (claude proposed, user approved) activity_xri: pspace://activity/act_DEMO_F1_COMPOSITION - title: "Drift finding decision (A13 Drift Detective example)" description: "How A13 will record a discovered drift surface as a decision" content: | $schema: decision@0.1.0 id: 01KQ402DEMOFORA13DRIFT0001 slug: drift-finding-changelog-vs-commits-2026-05-01 type: decision version: 0.1.0 decision_type: other decision_subtype: drift_finding context: | Routine drift sweep detected misalignment between CHANGELOG.md entries and the actual git commit history for the period 2026-04-15 to 2026-04-30. Three commits affecting public APIs landed without corresponding CHANGELOG entries. options: - id: propose-changelog-update description: "Open a PR adding the missing entries to CHANGELOG.md" evidence: - "git log --oneline 2026-04-15..2026-04-30 — three commits without entries" - "blindspot B-005 not directly relevant" verdict: PASS confidence: 0.85 - id: defer-to-next-release description: "Leave for the next release-prep session" evidence: - "next release window is 2026-05-15" verdict: PARTIAL confidence: 0.5 - id: dismiss-as-non-issue description: "Treat as intentional gap — these commits don't warrant entries" evidence: - "two commits are pre-commit hook fixes (chore-tier)" verdict: PARTIAL confidence: 0.4 chosen: propose-changelog-update rationale: | One of the three commits IS a public-API change (#XXX adding a new endpoint); CHANGELOG must reflect it for downstream consumers. Other two are chore-tier and do not need entries — documented as such in the proposed PR. confidence: 0.85 affects: - pspace://placeholder/changelog-pr-uuid-pending # PR doesn't exist yet - kno://CHANGELOG.md decided_by: pspace://agent/drift-detective intermediate_findings: - timestamp: "2026-05-01T03:42:13Z" note: "Initial sweep flagged 5 commits" evidence: - "git log output, sweep cycle 2026-05-01-03" - timestamp: "2026-05-01T03:42:31Z" note: "After deduplication, 3 commits remain unaddressed" - timestamp: "2026-05-01T03:42:48Z" note: "Of 3 remaining, only 1 affects public API"