dna-sdk 0.1.0

package/dist/extensions/sdlc/kinds/status-report.kind.yaml

@@ -0,0 +1,129 @@
+# StatusReport — frozen snapshot of one Insight's run (record plane).
+# Append-only ledger: each run writes a new report; confidence ascends or
+# regresses as the project accumulates data. Schema mirrors AssessmentReport.
+#
+# F3 lote-2 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the hand-written class twins were deleted. PARITY-CRITICAL
+# package data — byte-identical mirror under packages/sdk-{py,ts};
+# tests/test_descriptor_hash_parity.py enforces. Equivalence vs the extinct
+# class frozen in tests/test_lote2_descriptor_equivalence.py (golden:
+# tests/goldens/lote2/StatusReport.golden.json). Deltas intencionais (semântica
+# canônica = port): summary curado substitui o eco whole-spec do KindBase
+# default (list endpoints não usam kp.summary()); parse valida contra o
+# schema (classe era pass-through); to_card morto não migrado.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: status-report
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: StatusReport
+  alias: sdlc-status-report
+  origin: github.com/ruinosus/dna/sdlc
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: status-reports
+  dep_filters:
+    insight: sdlc-insight
+  schema:
+    type: object
+    required:
+    - insight
+    - verdict
+    - confidence
+    properties:
+      insight:
+        type: string
+        description: Name of the Insight that produced this report.
+      question:
+        type: string
+        description: Echo of the oracle's question at run time.
+      verdict:
+        type: string
+        description: Human-readable answer (1-3 sentences pt-BR). Synthesized by the
+          LLM from the heuristic numbers.
+      confidence:
+        type: string
+        enum:
+        - certain
+        - guess
+        - insufficient
+        description: How firm the verdict is. `insufficient` = the heuristic didn't
+          have enough data — the LLM was NOT called and the verdict is a stock message.
+      rag_status:
+        type: string
+        enum:
+        - red
+        - amber
+        - green
+        description: PMO-standard RAG status (Red/Amber/Green) for executive dashboards.
+          Red = action needed; Amber = watch; Green = healthy. Optional — heuristics
+          that map metrics → RAG should populate this.
+      metrics:
+        type: object
+        description: Deterministic numbers the heuristic computed (cycle counts, frequencies,
+          averages). Free-form object — schema varies per oracle.
+      heuristic_explanation:
+        type: string
+        description: 'Plain-text walkthrough of HOW the heuristic computed the metrics
+          and decided the confidence. Transparency: a reader can audit the math.'
+      evidence_refs:
+        type: array
+        items:
+          type: string
+        description: Doc refs (Kind/name) cited as evidence for this verdict. Studio
+          renders these as navigable links.
+      generated_at:
+        type: string
+        format: date-time
+      generated_by:
+        type: string
+        description: Model + actor (e.g. 'claude-sonnet-4-6').
+      ascended_from:
+        type: string
+        enum:
+        - certain
+        - guess
+        - insufficient
+        - ''
+        description: If the previous verdict's confidence differs from this one, this
+          is the previous level. Empty string when it's the first verdict.
+      thresholds:
+        type: object
+        description: 'Self-describing thresholds the heuristic used (e.g. `to_certain:
+          ''pattern_freq > 0.9 AND n>=5''`). Lets the reader know what would change
+          the verdict.'
+      bumped_remembrances:
+        type: array
+        items:
+          type: string
+        description: 'Phase 2B (squishy-jumping-nebula): audit trail written by oracle_cue_hook
+          listing the LessonLearned slugs whose cue history was bumped because this
+          report cited them. Bidirectional pairing with LessonLearned.cues_history.
+          Empty when the run had nothing to bump (the field is omitted, not stored
+          as []).'
+      owner:
+        type: string
+        description: 'Slug reference to a Agent. When set, this StatusReport
+          is PRIVATE to that agent. When null, it is GENERAL. Phase: cognitive-reflection.'
+  summary:
+    insight: ''
+    verdict: ''
+    confidence: ''
+    generated_at: ''
+    owner: null
+  embed:
+  - verdict
+  - question
+  - heuristic_explanation
+  graph_style:
+    fill: '#A78BFA'
+    stroke: '#7C3AED'
+    text_color: '#fff'
+  ascii_icon: 📜
+  display_label: Insight Reports

package/dist/extensions/sdlc/kinds/synthesis-run.kind.yaml

@@ -0,0 +1,279 @@
+# SynthesisRun — oneiric processing artefact (record plane). Surreal
+# recombination of memory fragments + dominant affect + one captured symbol.
+# NOT a prediction (that's Forecast) — synthesis processes, never predicts.
+# Curated summary drops the extinct to_card's DERIVED counts
+# (insight_count/belief_count/skill_count) — computed fields are not
+# expressible as a declared projection and the to_card had zero consumers.
+#
+# F3 lote-2 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the hand-written class twins were deleted. PARITY-CRITICAL
+# package data — byte-identical mirror under packages/sdk-{py,ts};
+# tests/test_descriptor_hash_parity.py enforces. Equivalence vs the extinct
+# class frozen in tests/test_lote2_descriptor_equivalence.py (golden:
+# tests/goldens/lote2/SynthesisRun.golden.json). Deltas intencionais (semântica
+# canônica = port): summary curado substitui o eco whole-spec do KindBase
+# default (list endpoints não usam kp.summary()); parse valida contra o
+# schema (classe era pass-through); to_card morto não migrado.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: synthesis-run
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: SynthesisRun
+  alias: sdlc-synthesis-run
+  origin: github.com/ruinosus/dna/sdlc
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: synthesis-runs
+    marker: SYNTHESIS_RUN.md
+    body_field: body
+  schema:
+    type: object
+    required:
+    - dreamer
+    - affect
+    - symbol
+    - scenario
+    - fragments
+    properties:
+      dreamer:
+        type: string
+        description: Author — UA slug ('oneiric-scribe') or 'user'.
+      affect:
+        type: string
+        enum:
+        - anxiety
+        - longing
+        - triumph
+        - eerie
+        - vertigo
+        - wistful
+        - ominous
+        - dread
+        - wonder
+        description: Dominant emotional register of the dream.
+      symbol:
+        type: string
+        maxLength: 200
+        description: '1-line metaphor that captures the dream as a whole. Image-based,
+          not analytic. Ex: ''A Feature corre por um corredor que se estreita sem
+          fim.'''
+      scenario:
+        type: string
+        maxLength: 2000
+        description: Imagistic prose, 3-6 sentences. The scene unfolding. Can have
+          dialogue, surreal events, affect-loaded imagery. NOT a prediction or hedge.
+      fragments:
+        type: array
+        items:
+          type: object
+          required:
+          - source
+          properties:
+            source:
+              type: string
+              description: 'Doc ref: ''LessonLearned/rem-foo'', ''Story/s-bar'', etc.'
+            lifted:
+              type: string
+              description: Specific phrase or detail recombined into the dream.
+        minItems: 2
+        description: 3-5 pieces of real project memory that got recombined to form
+          the dream. Like ecforia cues.
+      juxtapositions:
+        type: array
+        items:
+          type: string
+        default: []
+        description: 'Impossible / surreal combinations of fragments. Ex: ''rem-X
+          encontra forget-Y e oferece uma troca.'' Optional but encouraged.'
+      echo:
+        type: array
+        items:
+          type: string
+        default: []
+        description: Engram slugs activated (resonance, not analytic weight).
+      woke_thought:
+        type: string
+        description: Optional. The single thought lingering on waking. Where reflection
+          might begin, not a prediction.
+      drafted_at:
+        type: string
+        format: date-time
+      generated_by:
+        type: string
+      source_oracle:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+        default: []
+      owner:
+        type: string
+        description: 'Slug reference to a Agent. When set, this SynthesisRun
+          is PRIVATE to that agent (gerado a partir de LessonsLearned com mesmo owner).
+          When null, the SynthesisRun is GENERAL. Phase: cognitive-reflection. S5
+          (dream-engines-v2): also matches a SynthesizerState.role when the dream
+          came from hybrid-topn engine.'
+      lens:
+        type: string
+        description: SynthesisRunLens.name used to frame this dream (e.g. 'hindsight-cf',
+          'future-projection', 'skill-extractor'). Null = generated from SynthesizerState
+          voice alone.
+      confidence:
+        type: number
+        minimum: 0.0
+        maximum: 1.0
+        description: Self-rated confidence in the dream's claims. 0.0 = pure imagination;
+          1.0 = ≥3 strong source_event_ids per claim + critic-pass clean. Used by
+          ranker + clinical-guardrails.
+      source_event_ids:
+        type: array
+        items:
+          type: string
+        default: []
+        description: Doc refs of the memories this dream is grounded in. Required
+          for every claim in insight_candidates + belief_updates. Provenance for critic-pass
+          + eval-suite.
+      insight_candidates:
+        type: array
+        items:
+          type: object
+          required:
+          - claim
+          - evidence
+          properties:
+            claim:
+              type: string
+              maxLength: 500
+              description: 1-2 sentences. The proposed insight.
+            evidence:
+              type: array
+              items:
+                type: string
+              minItems: 1
+              description: source_event_ids supporting the claim.
+            confidence:
+              type: number
+              minimum: 0.0
+              maximum: 1.0
+            speculation:
+              type: boolean
+              default: false
+              description: True = goes beyond evidence. Marked for human review before
+                promotion.
+        default: []
+        description: Discrete proposals to promote into StatusReport / LessonLearned
+          / Skill via downstream scribes. Each item is independently rankable + verifiable.
+      belief_updates:
+        type: array
+        items:
+          type: object
+          required:
+          - before
+          - after
+          - reason
+          properties:
+            target_ref:
+              type: string
+              description: Optional Doc ref for the belief being updated (e.g. LessonLearned/X
+                or specific spec field path).
+            before:
+              type: string
+              maxLength: 400
+              description: Prior framing the dream challenges.
+            after:
+              type: string
+              maxLength: 400
+              description: Proposed new framing.
+            reason:
+              type: string
+              maxLength: 400
+              description: Why the shift — tie to source_event_ids.
+            confidence:
+              type: number
+              minimum: 0.0
+              maximum: 1.0
+        default: []
+        description: Belief deltas the dream proposes. Each is a before/after pair
+          with reasoning. Scribe downstream may apply, reject, or queue for human
+          review.
+      skill_candidates:
+        type: array
+        items:
+          type: object
+          required:
+          - name
+          - applies_when
+          properties:
+            name:
+              type: string
+              maxLength: 80
+              description: Short imperative skill name.
+            applies_when:
+              type: string
+              maxLength: 300
+              description: Trigger condition (Voyager-style).
+            script:
+              type: string
+              description: Procedural sketch (NOT executable). Voyager pattern — promote
+                to real Skill via skill-synthesis.
+            prerequisites:
+              type: array
+              items:
+                type: string
+              default: []
+        default: []
+        description: Voyager-style skill seeds. Each is a name + trigger condition
+          + procedural sketch. skill-synthesis engine consumes these.
+      contradictions:
+        type: array
+        items:
+          type: object
+          required:
+          - conflict
+          properties:
+            conflict:
+              type: string
+              maxLength: 500
+              description: What contradicts what.
+            refs:
+              type: array
+              items:
+                type: string
+              description: Doc refs on each side.
+            resolution_options:
+              type: array
+              items:
+                type: string
+              default: []
+              description: ≥2 ways to resolve, ranked.
+        default: []
+        description: Detected contradictions between source_event_ids the dream surfaced.
+          NOT auto-resolved — flagged for human or scribe arbitration.
+  summary:
+    dreamer: ''
+    affect: ''
+    symbol: ''
+    owner: null
+    lens: null
+    confidence: null
+  embed:
+  - scenario
+  - dreamer
+  graph_style:
+    fill: '#A78BFA'
+    stroke: '#7C3AED'
+    text_color: '#fff'
+  ascii_icon: 🔮
+  display_label: Sínteses
+  docs: SynthesisRun = oneiric artefact. Surreal recombination of project memory (fragments
+    lifted from LessonLearned/Story/ArchiveProposal/WorkflowEvent) + impossible juxtapositions
+    + dominant affect + one captured symbol. NOT falseable, NOT a prediction. Pair
+    with Forecast for the predictive dimension.

package/dist/extensions/sdlc/kinds/synthesizer-state.kind.yaml

@@ -0,0 +1,196 @@
+# SynthesizerState — persona contract for a dream-gen agent (record plane;
+# role + goal + backstory + method + voice_markers + memory_policy +
+# constitution + few-shots; read by the hybrid-topn engine — S2
+# dream-engines-v2). Bundle: dreamers/<slug>/SYNTHESIZER.md, body=backstory.
+#
+# F3 lote-3 (spec 2026-06-10-kinds-descriptor-f3): the twin
+# SynthesizerStateKind classes (Py+TS) were DELETED — this descriptor is
+# the single source. PARITY-CRITICAL package data: byte-identical mirror
+# under both runtimes' sdlc/kinds/ (tests/test_descriptor_hash_parity.py
+# enforces). Equivalence frozen in test_lote3_descriptor_equivalence.py
+# (golden: tests/goldens/lote3/SynthesizerState.golden.json).
+#
+# The DREAMER_METHODS enum was local to the extinct class (no other
+# consumer in either runtime) — frozen here as the single source.
+# summary is a curated projection (the dead to_card's elected fields:
+# role/method/linked_agent) replacing the KindBase whole-spec echo.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: synthesizer-state
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: SynthesizerState
+  alias: sdlc-synthesizer-state
+  origin: github.com/ruinosus/dna/sdlc
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: synthesizers
+    marker: SYNTHESIZER.md
+    body_field: backstory
+  schema:
+    type: object
+    required:
+    - role
+    - goal
+    - method
+    - voice_markers
+    properties:
+      role:
+        type: string
+        description: 'Short label for this dreamer. Usually matches a Agent
+          slug. Ex: ''scribe-engram'', ''oracle-risk'', ''narrative-historian''.'
+      goal:
+        type: string
+        description: 'What this dreamer is FOR. Ex: ''consolidate episódios em padrões
+          reutilizáveis'' (scribe), ''flag tail-risks antes que cristalizem em incidente''
+          (oracle-risk).'
+      backstory:
+        type: string
+        description: Narrative background (CrewAI pattern). 2-4 sentences. Anchors
+          voice + perspective. Stored as bundle body so it can grow long.
+      method:
+        type: string
+        enum:
+        - analogical
+        - causal
+        - surreal
+        - structural
+        - narrative
+        - counterfactual
+        - metaphorical
+        description: How this dreamer reasons. analogical = compare-and-contrast;
+          causal = chain of events; surreal = juxtaposition; structural = patterns/relations;
+          narrative = arc; counterfactual = 'what if'; metaphorical = imagistic
+          transfer.
+      voice_markers:
+        type: array
+        items:
+          type: string
+        minItems: 1
+        description: 'Words/structures/cadence that mark this dreamer''s voice.
+          Ex: [''vestígio'', ''arquivo subterrâneo'', ''frase nominal curta'', ''metáfora
+          geológica'']. Used by ranker for voice fingerprint match (anti-drift).'
+      non_goals:
+        type: array
+        items:
+          type: string
+        default: []
+        description: 'What this dreamer MUST NOT do. Used as explicit critic-pass
+          guardrails. Ex: ''never make diagnostic claims'', ''never name living
+          people in dreams''.'
+      memory_policy:
+        type: object
+        default: {}
+        properties:
+          areas:
+            type: array
+            items:
+              type: string
+            description: LessonLearned.area values to prioritize.
+          source_kinds:
+            type: array
+            items:
+              type: string
+            description: Doc Kinds to prefer as memory sources.
+          affects:
+            type: array
+            items:
+              type: string
+            description: LessonLearned.affect values to prioritize.
+          min_confidence_score:
+            type: number
+            minimum: 0.0
+            maximum: 1.0
+            default: 0.0
+        additionalProperties: true
+        description: Routing hints for memory retrieval. Hybrid- topn engine respects
+          these when assembling memory_subset. Empty dict = match-all.
+      dreamer_memory_stream_ref:
+        type:
+        - string
+        - 'null'
+        default: null
+        description: 'Reference to this dreamer''s persistent memory stream — coleção
+          dos SynthesisRuns anteriores deste dreamer (cross-session continuity).
+          Generative Agents (Park 2023) evidence: voz individuada emerge de memory
+          stream + reflexão, NÃO de voice_markers adjetivos. Hybrid-topn engine
+          deve injetar últimos N dreams + reflexões no prompt context. Format esperado:
+          ''<scope>/SynthesisRunCollection/<dreamer-slug>'' OR simples slug-name
+          resolvido contra um SynthesisRunCollection Kind (a definir). Cross-synth
+          ref: f-unique-voice-is-memory-not-prompt.'
+      constitution:
+        type: array
+        items:
+          type: string
+        default: []
+        description: 'Constitutional AI principles (DSI/Anthropic pattern). Ex:
+          [''ground every claim in source_event_ids'', ''mark speculation as such'',
+          ''prefer evidence over invention'']. Critic-pass evaluates dream output
+          against these.'
+      examples_positive:
+        type: array
+        items:
+          type: object
+          required:
+          - scenario
+          properties:
+            scenario:
+              type: string
+            symbol:
+              type: string
+            why_good:
+              type: string
+        default: []
+        description: 2-3 exemplary dreams in this dreamer's voice. Few-shot prompts
+          to anchor style.
+      examples_negative:
+        type: array
+        items:
+          type: object
+          required:
+          - scenario
+          - why_bad
+          properties:
+            scenario:
+              type: string
+            why_bad:
+              type: string
+        default: []
+        description: 2-3 anti-patterns. Critic-pass uses these as explicit negative
+          examples (what to avoid).
+      linked_agent:
+        type: string
+        description: 'Optional Agent slug this SynthesizerState pairs with
+          (1:1 — same persona, two surfaces: agent runs synchronous, dreamer runs
+          offline).'
+      drafted_at:
+        type: string
+        format: date-time
+      drafted_by:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+        default: []
+  summary:
+    role: ''
+    method: ''
+    linked_agent: ''
+  graph_style:
+    fill: '#C4B5FD'
+    stroke: '#7C3AED'
+    text_color: '#1E1B4B'
+  ascii_icon: 🌙
+  display_label: Sintetizadores
+  docs: SynthesizerState = persona contract for a dream-gen agent. Declares role
+    + goal + backstory + method + voice_markers + non_goals + memory_policy + constitution
+    + examples. Read by hybrid-topn engine to drive voice + memory routing. Pairs
+    1:1 with a Agent (scribe-engram, oracle-risk, ...). Multiple co-exist;
+    SynthesisRunTriggerPolicy routes events.