@knowledge-bus/opencode 0.5.0

package/references/product-development/universe.kbp.yaml

@@ -0,0 +1,411 @@
+universe:
+  id: product-development
+  label: Product development
+  version: 0.5
+  conforms_to: kbp/0.5
+  ordering_frame: phase
+  overview:
+    covers: >
+      The reasoning around deliberate work — what makes it worth doing, what it should
+      be, and whether it held up. The work may produce something made or put in place,
+      a service rendered, or something learned; for a recipient — including your own
+      later self — who simply receives it, free to take it or leave it, or paying
+      for it.
+    for: >
+      Whoever is accountable for that judgement or has to account for it later — one person
+      on one machine, a group, or an organisation.
+    excludes: >
+      Doing or delivering the work itself.
+
+statuses: [conjecture, modelled, contracted, measured, adjudicated, superseded]
+
+frames:
+
+  - id: phase
+    code: ft1k1
+    role: ordering          # assigns every element its place in the sequence
+    set_by: universe        # fixed in this file, by whoever authors the universe
+    attaches_to: element
+    values:
+      - { id: strategy,     question: "Who are we, where are we going, and why that way?" }
+      - { id: discovery,    question: "What is worth solving, for whom, and is it viable?" }
+      - { id: design,       question: "What are we building and how does it behave?" }
+      - { id: validation,   question: "How do we know it works?" }
+      - { id: architecture, question: "How does it technically hold together?" }
+      - { id: operate,      question: "How is this carried out and kept working?" }
+
+  - id: time-separation
+    code: fn7cn
+    role: applicability     # decides whether writing anything down is warranted
+    set_by: instance        # per piece of work — this note, this effort
+    question: "Who has to reconstruct this reasoning without the author present?"
+    values: [none, across-sessions, across-people, across-organisations]
+
+  - id: reversibility
+    code: fzjkj
+    role: applicability
+    set_by: instance        # a given step is reversible or not; asked each time
+    question: "What does proceeding foreclose?"
+    values: [reversible, costly, irreversible]
+
+  - id: uptake
+    code: f6shk
+    role: gating            # switches elements and artifacts on or off
+    set_by: scope           # declared at whatever scope asserts it; narrower scopes inherit or re-declare
+    question: "How does the outcome reach the people it's for?"
+    values:
+      - { id: given,  question: "Does it arrive whether or not they'd choose it?" }
+      - { id: chosen, question: "Do they take it up only by deciding to, with nothing to pay?" }
+      - { id: bought, question: "Is paying how they take it up?" }
+
+  - id: authority
+    code: f6yr9
+    role: gating
+    set_by: scope
+    question: "Whose assent is a precondition?"
+    values: [none, discretionary, notify, approve, statutory]
+
+  - id: maturity
+    code: fcz7q
+    role: gating
+    set_by: scope           # re-asked as the work matures: unproven, proven, scaling
+    question: "How settled is the bet this work rests on?"
+    values: [unproven, proven, scaling]
+
+  - id: outcome
+    code: fdhsz
+    role: gating
+    set_by: instance        # per outcome-component: the chassis and the firmware answer differently
+    attaches_to: outcome-component
+    question: "What kind of thing does this work produce?"
+    facets:
+      form: [artifact, service, claim]
+      replication: [singular, serial, unbounded]
+      mutability: [fixed-at-delivery, field-updatable, continuously-deployed]
+
+  - id: audience
+    code: f80a5
+    role: selection         # shapes the composition when an artifact crosses
+    set_by: instance        # per crossing: this artifact, this recipient
+    values: [self, internal, counterparty, regulator, public]
+
+empty_composition:
+  when: { time-separation: [none], reversibility: [reversible] }
+
+relation_kinds:
+  - { id: presupposes,      ordered: true }
+  - { id: distinct-from,    ordered: false }
+  - { id: counterweight-to, ordered: false }
+  - { id: feeds,            ordered: true }
+  - { id: split-signal,     ordered: true }
+  - { id: descendant-of,    ordered: true }
+  - { id: requires,         ordered: true }
+  - { id: nests-under,      ordered: true }
+
+elements:
+
+  - { id: product-vision, code: emsdr, question: "What future are we committing to, and why is it worth wanting?", phase: strategy, cardinality: singleton }
+  - { id: positioning-statement, code: e9x77, question: "For whom, against what alternatives, why us?", phase: strategy, cardinality: per-segment, gate: { uptake: [chosen, bought] } }
+  - { id: customer-segments, code: ebvkm, question: "Who exactly is served, grouped how?", phase: discovery, cardinality: singleton }
+  - { id: value-proposition, code: edffx, question: "Why would a segment choose this over its alternatives?", phase: strategy, cardinality: per-segment, gate: { uptake: [bought] } }
+  - { id: case-for-change, code: eaddp, question: "Why is this worth doing at all, versus not doing it?", phase: strategy, cardinality: singleton }
+  - { id: problem-statement, code: eyhkm, question: "What pain, for whom, why now?", phase: discovery, cardinality: singleton }
+  - { id: solution-overview, code: eseq3, question: "What is the intended solution, in outline?", phase: design, cardinality: singleton }
+  - { id: goals-and-non-goals, code: ezw7x, question: "What outcomes is this aiming for — and pointedly not?", phase: design, cardinality: singleton }
+  - { id: channels, code: eeq3f, question: "How do we reach and deliver to each segment?", phase: strategy, cardinality: per-segment, gate: { uptake: [chosen, bought] } }
+  - { id: customer-relationships, code: e9h1v, question: "How is each segment acquired, retained, grown?", phase: strategy, cardinality: per-segment }
+  - { id: revenue-streams, code: ebs31, question: "How does delivered value convert to money?", phase: strategy, cardinality: per-stream, gate: { uptake: [bought] } }
+  - { id: funding-source, code: exzg8, question: "Where does the sustaining resource come from, with what conditions attached?", phase: strategy, cardinality: per-source }
+  - { id: cost-structure, code: ereet, question: "What does operating this cost, and what drives it?", phase: strategy, cardinality: singleton }
+  - { id: key-resources, code: e72wk, question: "What assets must be owned or controlled?", phase: strategy, cardinality: singleton }
+  - { id: key-activities, code: ea6q2, question: "What must be done ourselves, and done well?", phase: strategy, cardinality: singleton }
+  - { id: key-partnerships, code: er20v, question: "What is deliberately relied on others for?", phase: strategy, cardinality: per-partner }
+  - { id: unfair-advantage, code: e9g24, question: "What can't be easily copied or bought?", phase: strategy, cardinality: singleton, gate: { uptake: [bought] } }
+  - { id: trade-offs, code: e45f8, question: "What is deliberately not being done?", phase: strategy, cardinality: per-refusal }
+  - { id: growth-mechanism, code: evkfg, question: "How does usage compound?", phase: strategy, cardinality: singleton, gate: { uptake: [bought] } }
+  - { id: capabilities, code: eqsja, question: "What must we be able to do to execute?", phase: strategy, cardinality: singleton }
+  - { id: north-star-metric, code: ezg3v, question: "What single measure best proxies delivered value?", phase: validation, cardinality: singleton, gate: { uptake: [chosen, bought] } }
+  - { id: input-metrics, code: ehk97, question: "Which controllable measures drive the outcome?", phase: validation, cardinality: per-north-star }
+  - { id: guardrail-health-metrics, code: e2hrs, question: "What must not degrade while pushing forward?", phase: validation, cardinality: per-owner }
+  - { id: success-criteria, code: e0pge, question: "What observable result counts as 'it worked'?", phase: validation, cardinality: per-effort }
+  - { id: market-sizing, code: erw62, question: "How big is the addressable population, credibly?", phase: discovery, cardinality: singleton, gate: { uptake: [bought] } }
+  - { id: internal-strengths-weaknesses, code: ews8m, question: "Where are we strong or exposed, internally?", phase: strategy, cardinality: singleton }
+  - { id: external-opportunities-threats, code: egp69, question: "What outside forces help or endanger?", phase: strategy, cardinality: per-force, closable: false }
+  - { id: macro-environment-factors, code: earc7, question: "Which external forces shape the space?", phase: strategy, cardinality: per-lens, closable: true }
+  - { id: competitor-profile, code: e6fsz, question: "Who else solves this, how, and how well?", phase: discovery, cardinality: per-competitor, closable: false, gate: { uptake: [chosen, bought] } }
+  - { id: jobs-to-be-done, code: ev2wp, question: "What progress is being 'hired' for, in what circumstance?", phase: discovery, cardinality: per-job }
+  - { id: pains-and-gains, code: ekyn8, question: "What frustrates today, and what would better look like?", phase: discovery, cardinality: per-segment }
+  - { id: user-job-stories, code: ed6n5, question: "What behavior, in what situation, toward what outcome?", phase: design, cardinality: per-story }
+  - { id: stepwise-trace, code: e58p3, question: "What happens at each step, and what does each step hand to the next?", phase: design, cardinality: per-scenario }
+  - { id: risks-and-assumptions, code: edew6, question: "What must be true, what could break for us, and what's the response?", phase: discovery, cardinality: per-risk }
+  - { id: affected-and-interested-parties, code: eppxq, question: "Who is materially affected or burdened without owning this, and with what standing?", phase: discovery, cardinality: per-party }
+  - { id: decision-authority-and-approvals, code: eqj19, question: "Whose agreement is required for this to proceed, under what delegation?", phase: strategy, cardinality: per-gate }
+  - { id: consent-and-authority, code: e921t, question: "Under what authority is this permitted, from whom, obtained when, expiring when?", phase: strategy, cardinality: per-consent, gate: { authority: [discretionary, notify, approve, statutory] } }
+  - { id: scope-in-out, code: esk7t, question: "What is included now, deferred, or refused?", phase: design, cardinality: singleton }
+  - { id: constraints, code: emwtf, question: "What externally imposed fixed limits bound the work?", phase: design, cardinality: per-constraint }
+  - { id: as-built-survey, code: esy0b, question: "What is actually there, measured to what tolerance, observed when?", phase: discovery, cardinality: per-subject }
+  - { id: cross-cutting-concerns, code: eyn7j, question: "What system-wide obligations must the design uphold?", phase: design, cardinality: per-concern }
+  - { id: visual-identity-rules, code: ej174, question: "How must the brand be rendered, and what renderings are forbidden?", phase: design, cardinality: singleton }
+  - { id: verbal-identity-rules, code: ehpbb, question: "How must the brand be worded, and what wordings are forbidden?", phase: design, cardinality: singleton }
+  - { id: alternatives-considered, code: e7j8k, question: "What else could have been done, and why not?", phase: design, cardinality: per-decision }
+  - { id: decision-criteria, code: e32n2, question: "By what criteria are the options judged, and how are they traded off?", phase: design, cardinality: per-decision }
+  - { id: decision, code: e43c2, question: "What was decided, and on what reasoning?", phase: design, cardinality: per-decision }
+  - { id: accepted-consequences, code: er7ec, question: "What are we accepting as a consequence of this commitment?", phase: design, cardinality: per-decision }
+  - { id: reversal-condition, code: ebxtg, question: "What observable condition would reopen this?", phase: design, cardinality: per-decision }
+  - { id: hypothesis, code: eavvd, question: "What relation do we predict, and what observation would refute it?", phase: discovery, cardinality: per-hypothesis, gate: { outcome: { form: [claim] } } }
+  - { id: measurement-protocol, code: ewd2m, question: "By what prescribed procedure are data produced, and how is each construct operationalised into a measured quantity?", phase: validation, cardinality: per-construct, gate: { outcome: { form: [claim] } } }
+  - { id: prior-art, code: e0c8e, question: "How have others solved this, and what does that teach?", phase: design, cardinality: per-precedent }
+  - { id: rollout-and-phasing, code: erszc, question: "How does this reach reality, in graduated exposure, with kill criteria?", phase: operate, cardinality: singleton }
+  - { id: sequence-and-foreclosure, code: enbkd, question: "In what order must this be done, and what does each step foreclose?", phase: design, cardinality: singleton }
+  - { id: open-questions, code: edcxt, question: "What is knowingly unknown?", phase: design, cardinality: per-question }
+  - { id: system-boundary-and-context, code: ec73p, question: "What is inside the system, and what does it touch?", phase: architecture, cardinality: singleton }
+  - { id: components-and-responsibilities, code: eey7j, question: "What parts exist, each owning what?", phase: architecture, cardinality: per-component, gate: { outcome: { form: [artifact] } } }
+  - { id: data-flows-and-integrations, code: e11bw, question: "What moves where, over which contracts?", phase: architecture, cardinality: per-flow }
+  - { id: canonical-model, code: eenkt, question: "What named categories carve the domain, and what shape does each entry take?", phase: architecture, cardinality: singleton }
+
+artifacts:
+
+  - id: product-strategy-canvas
+    code: aqfpn
+    enablement: { action: "commit to a direction and the refusals that make it real", actor: decision-makers, timing: before allocating a cycle's resources }
+    alias: { kind: none, reason: no-aligned-form }
+    disabled_when: { uptake: [given] }
+    composition:
+      core: [product-vision, customer-segments, value-proposition, cost-structure, trade-offs,
+             north-star-metric, growth-mechanism, capabilities, unfair-advantage]
+      situational: [positioning-statement, input-metrics, revenue-streams, case-for-change]
+
+  - id: business-model-canvas
+    code: af0pt
+    enablement: { action: "judge whether the business logic closes — value, delivery and money", actor: operator or backer, timing: before or during commitment }
+    alias: { kind: normative, form: "Business Model Canvas (Osterwalder)" }
+    disabled_when: { uptake: [given, chosen] }
+    composition:
+      core: [customer-segments, value-proposition, channels, customer-relationships,
+             revenue-streams, key-resources, key-activities, key-partnerships, cost-structure]
+      situational: []
+
+  - id: lean-canvas
+    code: ajw0x
+    enablement: { action: "judge whether an early-stage bet is worth testing next", actor: founder or sponsor, timing: before fit is established }
+    alias: { kind: normative, form: "Lean Canvas (Maurya)" }
+    disabled_when: { uptake: [given, chosen] }
+    composition:
+      core: [problem-statement, customer-segments, value-proposition, solution-overview,
+             channels, revenue-streams, cost-structure, input-metrics, unfair-advantage]
+      situational: []
+
+  - id: startup-canvas
+    code: awrrs
+    enablement: { action: "commit to a venture direction with its business logic attached", actor: founder and backer, timing: at formation }
+    alias: { kind: none, reason: no-aligned-form }
+    disabled_when: { uptake: [given, chosen] }
+    composition:
+      core: [product-vision, customer-segments, value-proposition, cost-structure, trade-offs,
+             north-star-metric, growth-mechanism, capabilities, unfair-advantage, revenue-streams]
+      situational: [positioning-statement, input-metrics]
+
+  - id: swot-analysis
+    code: a7ds8
+    enablement: { action: "orient on position before choosing a direction", actor: planning group, timing: before strategy is set }
+    alias: { kind: normative, form: "SWOT" }
+    composition:
+      core: [internal-strengths-weaknesses, external-opportunities-threats]
+      situational: [macro-environment-factors, competitor-profile]
+
+  - id: pestle-analysis
+    code: amr2m
+    enablement: { action: "orient on external forces before committing to a direction", actor: planning group, timing: before strategy is set }
+    alias: { kind: normative, form: "PESTLE" }
+    composition:
+      core: [macro-environment-factors]
+      situational: [external-opportunities-threats, risks-and-assumptions]
+
+  - id: competitor-analysis
+    code: az67c
+    enablement: { action: "position against the alternatives a chooser actually has", actor: "strategy, marketing and sales", timing: continuous }
+    alias: { kind: descriptive, form: "competitor analysis" }
+    disabled_when: { uptake: [given] }
+    composition:
+      core: [competitor-profile]
+      situational: [positioning-statement, external-opportunities-threats, market-sizing]
+
+  - id: persona-profile
+    code: a7rcy
+    enablement: { action: "design for a specific circumstance rather than an average", actor: "designers, researchers and product", timing: before solution design }
+    alias: { kind: descriptive, form: "persona profile" }
+    composition:
+      core: [jobs-to-be-done, pains-and-gains]
+      situational: [customer-segments, user-job-stories, channels]
+
+  - id: opportunity-assessment
+    code: a2cwq
+    enablement: { action: "decide whether to pursue this at all", actor: sponsor, timing: before committing build resources }
+    alias: { kind: descriptive, form: "product brief / one-pager" }
+    composition:
+      core:
+        - { element: problem-statement, mode: owns }
+        - { element: case-for-change, mode: owns }
+        - { element: customer-segments, mode: owns }
+        - { element: risks-and-assumptions, mode: owns }
+        - { element: consent-and-authority, mode: owns, when: { authority: [approve, statutory] } }
+      situational: [market-sizing, value-proposition, competitor-profile, success-criteria,
+             affected-and-interested-parties, decision-authority-and-approvals, funding-source]
+
+  - id: risk-assessment
+    code: abewy
+    enablement: { action: "decide what to mitigate, accept or watch, and who owns each", actor: accountable owner, timing: before and throughout }
+    alias: { kind: descriptive, form: "risk register" }
+    composition:
+      core: [risks-and-assumptions, affected-and-interested-parties, scope-in-out]
+      situational: [guardrail-health-metrics, open-questions]
+
+  - id: design-doc
+    code: a0czz
+    enablement: { action: "agree or object to a proposed approach", actor: reviewer, timing: before build }
+    alias: { kind: descriptive, form: "RFC / RFD" }
+    composition:
+      core:
+        - { element: problem-statement, mode: links }
+        - { element: goals-and-non-goals, mode: owns }
+        - { element: solution-overview, mode: owns }
+        - { element: alternatives-considered, mode: owns }
+        - { element: open-questions, mode: owns }
+        - { element: constraints, mode: owns, when: { authority: [approve, statutory] } }
+        - { element: cross-cutting-concerns, mode: owns, when: { authority: [approve, statutory] } }
+        - { element: risks-and-assumptions, mode: owns, when: { authority: [approve, statutory] } }
+        - { element: sequence-and-foreclosure, mode: owns, when: { reversibility: [costly, irreversible] } }
+      situational: [rollout-and-phasing, prior-art, scope-in-out, success-criteria, user-job-stories,
+             stepwise-trace, canonical-model, as-built-survey, consent-and-authority]
+
+  - id: brand-identity-guide
+    code: atm2v
+    enablement: { action: "render and voice the identity correctly without asking", actor: anyone producing expression, timing: continuous }
+    alias: { kind: descriptive, form: "brand guidelines / style guide / DESIGN.md" }
+    composition:
+      core:
+        - { element: visual-identity-rules, mode: owns }
+        - { element: verbal-identity-rules, mode: owns }
+      situational:
+        - { element: product-vision, mode: links }
+        - { element: positioning-statement, mode: links }
+        - { element: constraints, mode: owns }
+        - { element: prior-art, mode: owns }
+        - { element: open-questions, mode: owns }
+
+  - id: scenario-walkthrough
+    code: azetx
+    enablement: { action: "verify one concrete path resolves end to end", actor: reviewer, timing: before build }
+    alias: { kind: descriptive, form: "key path scenario" }
+    composition:
+      core: [stepwise-trace]
+      situational: [user-job-stories, data-flows-and-integrations, constraints]
+
+  - id: success-metrics
+    code: ar2vy
+    enablement: { action: "tell whether the thing is working, and what to push and protect", actor: operator, timing: continuous after launch }
+    alias: { kind: descriptive, form: "North Star framework" }
+    disabled_when: { uptake: [given] }
+    composition:
+      core: [north-star-metric, input-metrics, guardrail-health-metrics]
+      situational: [success-criteria]
+
+  - id: architecture-overview
+    code: a74pm
+    enablement: { action: "understand the shape well enough to change part of it safely", actor: engineer or architect, timing: on joining or before changing }
+    alias: { kind: descriptive, form: "C4 levels 1–2" }
+    composition:
+      core: [system-boundary-and-context, components-and-responsibilities, data-flows-and-integrations]
+      situational: [constraints, trade-offs, risks-and-assumptions, canonical-model, as-built-survey]
+
+  - id: system-context-diagram
+    code: avxcm
+    enablement: { action: "see the boundary and what crosses it", actor: anyone new to the system, timing: on first contact }
+    alias: { kind: normative, form: "C4 level 1" }
+    composition:
+      core: [system-boundary-and-context, data-flows-and-integrations]
+      situational: []
+
+  - id: decision-brief
+    code: a20v3
+    enablement: { action: "choose among live alternatives by a set date", actor: the person accountable for the choice, timing: before the decision is taken }
+    alias: { kind: descriptive, form: "options paper / decision document (DACI, SPADE)" }
+    composition:
+      core:
+        - { element: alternatives-considered, mode: owns }
+        - { element: decision-criteria, mode: owns }
+        - { element: decision-authority-and-approvals, mode: owns, when: { authority: [approve, statutory] } }
+        - { element: problem-statement, mode: links }
+      situational: [constraints, risks-and-assumptions, prior-art, open-questions, scope-in-out]
+
+  - id: decision-record
+    code: ayx0k
+    enablement: { action: "know whether this decision still stands, and reopen it correctly if not", actor: future reader, timing: any time after }
+    alias: { kind: descriptive, form: "ADR (Nygard) / MADR / record of decision" }
+    composition:
+      core:
+        - { element: decision, mode: owns }
+        - { element: accepted-consequences, mode: owns }
+        - { element: reversal-condition, mode: owns }
+        - { element: alternatives-considered, mode: owns }
+        - { element: risks-and-assumptions, mode: owns }
+        - { element: problem-statement, mode: links }
+        - { element: decision-criteria, mode: links, when: { authority: [approve, statutory] } }
+      situational: [constraints, prior-art, open-questions]
+
+  - id: working-note
+    code: axh9h
+    enablement: { action: "resume your own work after a gap without re-deriving it", actor: the author at a later time, timing: across sessions }
+    alias: { kind: none, reason: no-aligned-form }
+    disabled_when: { time-separation: [none] }
+    composition:
+      core: [constraints, scope-in-out, open-questions]
+      situational: [trade-offs, as-built-survey, success-criteria]
+
+relations:
+
+  - { from: value-proposition, to: case-for-change, kind: distinct-from }
+  - { from: constraints, to: as-built-survey, kind: distinct-from }
+  - { from: constraints, to: trade-offs, kind: distinct-from }
+  - { from: goals-and-non-goals, to: scope-in-out, kind: distinct-from }
+  - { from: risks-and-assumptions, to: affected-and-interested-parties, kind: distinct-from }
+  - { from: hypothesis, to: success-criteria, kind: distinct-from }
+  - { from: hypothesis, to: risks-and-assumptions, kind: distinct-from }
+  - { from: rollout-and-phasing, to: sequence-and-foreclosure, kind: distinct-from }
+  - { from: key-activities, to: capabilities, kind: distinct-from }
+  - { from: components-and-responsibilities, to: canonical-model, kind: distinct-from }
+  - { from: customer-segments, to: canonical-model, kind: distinct-from }
+  - { from: prior-art, to: competitor-profile, kind: distinct-from }
+  - { from: accepted-consequences, to: trade-offs, kind: distinct-from }
+  - { from: alternatives-considered, to: decision, kind: distinct-from }
+  - { from: decision-criteria, to: goals-and-non-goals, kind: distinct-from }
+  - { from: decision-criteria, to: constraints, kind: distinct-from }
+  - { from: reversal-condition, to: risks-and-assumptions, kind: distinct-from }
+  - { from: goals-and-non-goals, to: trade-offs, kind: distinct-from }
+  - { from: visual-identity-rules, to: cross-cutting-concerns, kind: distinct-from }
+  - { from: verbal-identity-rules, to: positioning-statement, kind: distinct-from }
+  - { from: verbal-identity-rules, to: value-proposition, kind: distinct-from }
+  - { from: stepwise-trace, to: solution-overview, kind: distinct-from }
+  - { from: revenue-streams, to: funding-source, kind: distinct-from }
+  - { from: decision-authority-and-approvals, to: affected-and-interested-parties, kind: distinct-from }
+  - { from: constraints, to: consent-and-authority, kind: presupposes }
+  - { from: north-star-metric, to: input-metrics, kind: requires }
+  - { from: guardrail-health-metrics, to: input-metrics, kind: counterweight-to }
+  - { from: measurement-protocol, to: hypothesis, kind: presupposes }
+  - { from: external-opportunities-threats, to: macro-environment-factors, kind: feeds }
+  - { from: external-opportunities-threats, to: competitor-profile, kind: feeds }
+  - { from: as-built-survey, to: sequence-and-foreclosure, kind: feeds }
+  - { from: stepwise-trace, to: data-flows-and-integrations, kind: split-signal }
+  - { from: product-vision, to: product-vision, kind: nests-under, legality: permitted }
+  - { from: design-doc, to: opportunity-assessment, kind: presupposes }
+  - { from: persona-profile, to: problem-statement, kind: presupposes }
+  - { from: scenario-walkthrough, to: design-doc, kind: presupposes }
+  - { from: architecture-overview, to: design-doc, kind: presupposes }
+  - { from: success-metrics, to: north-star-metric, kind: requires }
+  - { from: success-criteria, to: trade-offs, kind: feeds, legality: permitted }
+  - { from: guardrail-health-metrics, to: decision, kind: feeds, legality: permitted, gate: { authority: approve } }
+  - { from: success-criteria, to: hypothesis, kind: feeds, legality: permitted-if-logged }
+  - { from: decision, to: scope-in-out, kind: feeds, freeze: baselined }
+  - { from: decision-criteria, to: decision, kind: feeds }
+  - { from: decision-record, to: design-doc, kind: distinct-from }
+  - { from: decision-brief, to: decision-record, kind: feeds }

package/runtime/kbp.py

@@ -0,0 +1,91 @@
+"""Run the bundled checker without writing into the plugin or changing scope."""
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def command(arguments, runtime=None, environ=None):
+    """Build an isolated checker invocation from verified bundled dependencies."""
+    runtime = (runtime or Path(__file__).resolve().parent).resolve()
+    env = dict(os.environ if environ is None else environ)
+    config = json.loads((runtime / "requirements.json").read_text())
+    requirement = config.get("requires_python", "")
+    match = re.fullmatch(r">=(\d+)\.(\d+)(?:\.(\d+))?", requirement)
+    if not match:
+        raise ValueError("Bundled Python requirement is missing or unsupported.")
+    minimum = tuple(int(part or 0) for part in match.groups())
+    if sys.version_info[:3] < minimum:
+        raise ValueError(
+            f"Knowledge Bus requires Python {requirement}; "
+            f"this interpreter is {'.'.join(map(str, sys.version_info[:3]))}."
+        )
+    uv = shutil.which("uv", path=env.get("PATH"))
+    if not uv:
+        raise ValueError("Knowledge Bus requires uv. See https://docs.astral.sh/uv/.")
+    wheel = runtime / config["wheel"]
+    if wheel.parent != runtime or not wheel.is_file():
+        raise ValueError("Bundled checker wheel is missing or outside the runtime.")
+    if hashlib.sha256(wheel.read_bytes()).hexdigest() != config["sha256"]:
+        raise ValueError("Bundled checker wheel does not match its recorded checksum.")
+    default = (
+        Path.home() / "Library/Caches"
+        if sys.platform == "darwin"
+        else Path(env.get("LOCALAPPDATA", str(Path.home() / "AppData/Local")))
+        if os.name == "nt"
+        else Path(env.get("XDG_CACHE_HOME", str(Path.home() / ".cache")))
+    )
+    cache = (
+        Path(env.get("KNOWLEDGE_BUS_CACHE_DIR", str(default / "knowledge-bus")))
+        .expanduser()
+        .resolve()
+    )
+    if cache == runtime.parent or runtime.parent in cache.parents:
+        raise ValueError("The runtime cache must be outside the installed plugin.")
+    env["UV_CACHE_DIR"] = str(cache)
+    env["UV_PYTHON_DOWNLOADS"] = "never"
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    for key in (
+        "UV_PROJECT_ENVIRONMENT",
+        "UV_PROJECT",
+        "UV_WORKING_DIRECTORY",
+        "UV_CONFIG_FILE",
+        "UV_NO_SYNC",
+        "UV_FROZEN",
+        "VIRTUAL_ENV",
+        "PYTHONPATH",
+        "PYTHONHOME",
+    ):
+        env.pop(key, None)
+    args = [
+        uv,
+        "run",
+        "--no-project",
+        "--no-config",
+        "--isolated",
+        "--python",
+        sys.executable,
+        "--with",
+        str(wheel),
+    ]
+    for requirement in config["dependencies"]:
+        args.extend(["--with", requirement])
+    return args + ["python", "-I", "-m", "kbp_conform.cli", *arguments], env
+
+
+def main():
+    try:
+        args, env = command(sys.argv[1:])
+        return subprocess.run(args, env=env, check=False).returncode
+    except (ValueError, OSError, KeyError) as error:
+        print(f"Knowledge Bus: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/requirements.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.0",
+  "wheel": "knowledge_bus-0.5.0-py3-none-any.whl",
+  "requires_python": ">=3.14",
+  "sha256": "9334bb61f23ba979e1a8466cce06a37388d71d38578870f9a8c8dff00c13cfc8",
+  "dependencies": [
+    "PyYAML==6.0.3"
+  ]
+}

package/skills/kb-check/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: kb-check
+description: Validate Knowledge Bus definitions and guidance after edits, and explain each failure and its fix.
+---
+
+# Check Spec Files
+
+**Purpose — answer "is this still valid?" with the clause that failed and the fix it calls for, never a bare pass/fail.**
+
+## The flow
+
+- **1. Locate.** The installed package supplies the checker and protocol. Explicit file or directory targets take precedence. Without a target, use the nearest `.knowledge-bus/` from the user's working directory upward. Pass the resolved absolute Knowledge Bus directory path when the agent host runs commands from a different directory. Never combine definitions from different Knowledge Bus directories. If no `.knowledge-bus/` exists, report it; checking never creates one. See [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). The implementation checkout retains its bundled-example default when no `.knowledge-bus/` directory is found.
+
+- **2. Run.** Follow [Checker for Agent Workflows](../../references/agent-runtime.md). Run the bundled checker with `--validate <resolved-target>`. The format self-check runs first; an unsound format stops the run.
+
+- **3. Interpret.** Every refusal names its clause. Translate each into the edit it calls for; see [Checker for Agent Workflows](../../references/agent-runtime.md) for the clause families.
+
+- **4. Report.** Per-file pass/fail, then refusals grouped by fix, not by file.
+
+## Common failures
+
+Each row is a registered refusal; every one has a corpus file that must fail for exactly this reason.
+
+| Refusal contains                      | Fix                                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `already carried by`                  | The code is taken. Mint a fresh one (`kbp --mint <kind> 1 <resolved-target>`); never reuse or reassign a code. |
+| `missing required`                    | The declaration lacks a required key (`id`, `code`, its identity). Add it; the message names which.            |
+| `may not be referenced by a universe` | A `when:` predicate names a factor. Factors are unwired by design — predicate on a frame instead.              |
+| `composition refs unknown elements`   | A composition entry names an element the spec never declares. Declare it or correct the id.                    |
+| `does not match`                      | `conforms_to` disagrees with the format version. Update it deliberately, against the changelog.                |

package/skills/kb-evolve/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: kb-evolve
+description: Add or re-examine document types in a Knowledge Bus universe, grounding structural changes in evidence.
+---
+
+# Evolve a Spec
+
+**Purpose — add a type the spec does not carry, or deepen one it already declares, so that every declaration is earned by evidence, every refusal is recorded with its reason, and the framework stays cohesive rather than locally patched.**
+
+Two entry points share one spine. Run the spine; take the branch that applies.
+
+- **Path A — new type.** A form exists in the world and the spec does not carry it. Governing question: *does it enable something no declared type enables?*
+- **Path B — re-evaluation.** A declared type is about to become load-bearing and its basis is unexamined. Governing question: *what in this type is inherited rather than earned?*
+
+## Knowledge Bus Directory
+
+Follow [Knowledge Bus Directory](../../references/knowledge-bus-directory.md). Use an explicit target when supplied; otherwise resolve the nearest `.knowledge-bus/` from the user's working directory. Inspect existing files before proposing changes and preserve existing definitions and decision history. Do not combine definitions from different Knowledge Bus directories. Write only inside the selected `.knowledge-bus/`; leave source files untouched. If definitions are absent, ask the user to select or explicitly create a set rather than inventing one silently.
+
+## Standing constraints
+
+- **Deepen by sharpening questions, splits and cross-connections — never by growing per-cell density.** A fattening cell means the essence is not grasped yet.
+- **Re-evaluate every row the new knowledge touches**, revising earlier depictions the evidence has outgrown. Cohesion over local patching.
+- **A refusal is an output.** Record what you declined to add and why, so it is not re-litigated.
+- **Nothing about a downstream app enters either file**, in any form.
+- **Surface, do not hack.** Where the model cannot express something honestly, say so and file it — do not bend a declaration to fit.
+- **Codes are stable.** Renaming an `id` is free; reusing or reassigning a code is not.
+
+## The flow
+
+- **1. State the suspicion before searching.** Write down what you expect to find wrong, then go looking. This is what stops a first-hit lineage from being confirmed rather than tested.
+  - **A:** name the form and the gap it claims to fill.
+  - **B:** name what looks inherited — a word in the id, a single-tradition guidance base, a question doing more than one job, an enablement promising something no element delivers.
+
+- **2. Group candidate sources by enablement, not by discipline.** Families are "what does this let someone *do*" — decide, know-what-stands, calibrate, follow-an-argument. Discipline groupings smuggle in the lineage you are trying to test.
+
+- **3. Fetch primary sources. Record every failed or degraded fetch.** Paywalled, rescinded, image-only, redirected — say so, and carry the caveat into the citation itself rather than leaving it for a reader to discover.
+
+- **4. Run the artifact test per family.** Identity is `(action, actor)`; add timing to break ties.
+  - **A:** if the enablement duplicates a declared type's, fold the form in as an alias — do not add a row.
+  - **B:** ask whether any *surveyed family* deserves a type the spec lacks. Refusing one is an output, not an omission — record why.
+
+- **5. Run the element test on every candidate field, against every declared question.** Identity is the question. Name the collision for each candidate and rule *sharpen existing / new / refused*.
+  - **A:** decompose the external form into its documented sections; reconcile each — fold into an existing row, split one, or add. Never duplicate.
+  - **B:** additionally audit the type's **existing** elements. A question with two conjunctions is usually two questions. A clause the instance layer already answers is a leak between levels, not a field.
+
+- **6. Derive strength; do not choose it.** Core iff the enabled action cannot be taken without it. Where a frame decides, express it as `when:` on a core entry rather than as a second row.
+
+- **7. Check the relation graph.**
+  - **A:** add boundaries for the near-misses step 5 surfaced.
+  - **B:** **re-point every edge naming a renamed or split declaration**, and promote any boundary that exists only as guidance prose into a `distinct-from` edge.
+
+- **8. Write the spec file.** See § Outputs.
+  - **A:** mint codes for everything new.
+  - **B:** **retain the code on any declaration keeping its identity**; mint only for genuinely new ones. A rename with a stable code costs nothing downstream — that is what codes are for.
+
+- **9. Write the guidance file.** See § Outputs.
+  - **A:** guidance starts empty; author it.
+  - **B:** guidance already exists and is keyed on ids you may have changed. Rekey it, and re-home entries whose subject moved — a boundary claim follows the element it is about.
+
+- **10. Verify mechanically.** Use [Checker for Agent Workflows](../../references/agent-runtime.md) for code minting and validation. Run the checker; expect it to catch the rekeying you missed. Grep for downstream leakage. Count codes and entries against expectation. Confirm the protocol version did not move unless you meant it to.
+
+- **11. Record the decision — including the refusals.** One record: what changed, why, what was refused and on what grounds, what would reverse it, what stayed ambiguous.
+
+- **12. Raise what you surfaced but did not solve.** A gap found and left unfiled becomes an assumption. File it as an item.
+
+## Outputs, by file
+
+**Spec file — carries only what something reads.**
+
+- Declarations: elements, artifact types, frames, factors — each with `id`, `code`, and its identity (`question` for an element, `enablement` for an artifact).
+- Composition: `core` / `situational`, each entry's `mode` (`owns` | `links`) and any `when:` predicate.
+- Relations: edges with `kind`, plus `legality`, `gate` or `freeze` where they apply.
+- The `alias` — the external form(s) the composition aligns with, and its kind.
+- Nothing advisory. Nothing about any app built on the spec. Nothing a reader is meant to weigh rather than resolve.
+
+**Guidance file — carries everything else, and is advisory by rule.**
+
+- One entry per claim: `kind`, `claim`, `source`, optional `when:`.
+- `convention` must cite a registry source; `pitfall`, `heuristic`, `empty`, `refresh`, `boundary` may be `asserted`.
+- Register each new source with `cite`, `url` and `checked`. **Put sourcing caveats inside the `cite` string** — rescinded, paywalled, secondary, abstract-only.
+- Give every `distinct-from` edge a `boundary` entry saying why the distinction holds.
+- Give every element you added an `empty` entry saying what an honest empty answer means.
+
+**Split rule:** a value belongs in the spec because something reads it; everything else belongs in guidance. A spec must stay valid with no guidance file present.