dna-sdk 0.1.0

package/dist/extensions/sdlc/kinds/narrative.kind.yaml

@@ -0,0 +1,189 @@
+# Narrative — curated human-readable summary of project activity (record
+# plane). [DEPRECATED Phase 2.2d 2026-05-26]: split into ADR + Retrospective;
+# kept read-only for backward-compat (removal planned post rollback window).
+# NOTE: NOT in `embed:` — the legacy embedding text joins spec.paragraphs
+# with "\n\n" (source_text_for branch), which a declared field-join cannot
+# reproduce byte-identically; Narrative stays in _EMBED_LEGACY.
+#
+# 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/Narrative.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: narrative
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Narrative
+  alias: sdlc-narrative
+  origin: github.com/ruinosus/dna/sdlc
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  scope_inheritable: false
+  storage:
+    type: bundle
+    container: narratives
+    marker: NARRATIVE.md
+    body_field: body
+  dep_filters:
+    covers_features: sdlc-feature
+    covers_epics: sdlc-epic
+    covers_stories: sdlc-story
+  schema:
+    type: object
+    required:
+    - title
+    - body
+    properties:
+      title:
+        type: string
+        description: Headline for this narrative. Shown above the body.
+      body:
+        type: string
+        description: Markdown body of the narrative (lives in NARRATIVE.md). Free-form
+          — paragraphs, bullets, links to Stories/Features/commits. Should read like
+          a human update, not a log dump.
+      period_start:
+        type: string
+        format: date-time
+        description: Start of the period this narrative covers (ISO-8601).
+      period_end:
+        type: string
+        format: date-time
+        description: End of the period (often the moment the narrative was written).
+      actor:
+        type: string
+        description: Who wrote this narrative (Actor name, 'claude-code', 'human',
+          etc.).
+      auto_generated:
+        type: boolean
+        description: true = LLM-generated draft; false = human or agent-curated prose.
+          Studio shows a small badge so readers know what they're reading.
+      summary:
+        type: string
+        description: Optional one-line tl;dr. When present, the Studio card shows
+          this above the body for scanning.
+      covers_features:
+        type: array
+        items:
+          type: string
+        description: Feature names this narrative discusses.
+      covers_epics:
+        type: array
+        items:
+          type: string
+        description: Epic names this narrative discusses.
+      covers_stories:
+        type: array
+        items:
+          type: string
+        description: Story names this narrative discusses.
+      covers_session:
+        type: string
+        description: AgentSession name this narrative was auto-derived from (Karpathy
+          'context ephemeral, files durable' pattern). Set by `dna sdlc session capture`
+          when the post-capture narrative hook runs.
+      tags:
+        type: array
+        items:
+          type: string
+        description: Free-form tags for filtering (daily, release, retro, ...).
+      paragraphs:
+        type: array
+        items:
+          type: string
+        description: 'Structured prose: list of past-tense paragraphs describing what
+          shipped. Studio renders these as the hero block; falls back to `body` when
+          empty.'
+      decisions:
+        type: array
+        items:
+          type: object
+          required:
+          - summary
+          properties:
+            summary:
+              type: string
+              description: What was decided (1 sentence).
+            reason:
+              type: string
+              description: Why — the tradeoff or driving constraint.
+            trade_offs:
+              type: string
+              description: 'Optional: what we gave up to make this choice.'
+        description: Ratified decisions made during the period covered by this narrative.
+          Each captures the WHY, not just the WHAT — the decision-extractor pattern.
+      open_items:
+        type: array
+        items:
+          type: object
+          required:
+          - title
+          properties:
+            title:
+              type: string
+            owner:
+              type: string
+            blocker:
+              type: string
+        description: Work that started but didn't close in this period. Studio's 'still
+          open' section reads from this when present (otherwise computes heuristically
+          from event diff).
+      author_intent:
+        type: string
+        enum:
+        - daily
+        - weekly
+        - release
+        - retro
+        - incident
+        - freeform
+        description: What kind of narrative this is. Drives how the morning panel
+          groups multiple narratives — daily stack on the timeline, releases pin as
+          marquee, retros surface in a 'lessons' filter.
+      journey_phase:
+        type: string
+        enum:
+        - discover
+        - specify
+        - plan
+        - build
+        - verify
+        - reflect
+        description: Universal journey phase (discover → specify → plan → build →
+          reflect). Additive layer over Story/Feature/Epic status, Spec phase, etc.
+          Lets the journey ledger pin this doc to one of five universal phases compatible
+          with Superpowers / BMAD / Spec Kit / Kiro.
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+  summary:
+    title: ''
+    summary: ''
+    actor: ''
+    author_intent: ''
+    auto_generated: false
+    period_end: ''
+  graph_style:
+    fill: '#A78BFA'
+    stroke: '#7C3AED'
+    text_color: '#fff'
+  ascii_icon: 📜
+  display_label: Narratives
+  docs: A Narrative is a curated, human-readable summary of project activity. Stored
+    as a NARRATIVE.md bundle with markdown body. Names usually encode the period (ISO
+    date for daily, milestone slug for releases). Replaces ad-hoc 'what happened tonight?'
+    chat scrolling — the agent stamps a Narrative at session end so future readers
+    (CEO, customer, new-hire) can open one page and get the story.

package/dist/extensions/sdlc/kinds/pattern-insight.kind.yaml

@@ -0,0 +1,204 @@
+# PatternInsight — output of a dream-interp engine (record plane).
+#
+# Schema is loose by design: each framework produces different structured
+# output (Hill = exploration/insight/action; Jung = amplifications/
+# archetypes; Gestalt = identifications). `framework` discriminates;
+# multiple interpretations per SynthesisRun coexist (polyphonic engines).
+#
+# F3 lote-1 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the PatternInsightKind class (Py) was deleted. This kind was
+# Py-ONLY before F3 — the descriptor gives TS the kind for free
+# (kind-registry-parity.json: moved py_only_allowlist → ts_aliases).
+# PARITY-CRITICAL package data — byte-identical mirror under
+# packages/sdk-{py,ts}; tests/test_descriptor_hash_parity.py enforces.
+# A classe tinha um to_card morto (zero consumidores) — não migrado.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: pattern-insight
+spec:
+  target_api_version: github.com/ruinosus/dna/cognitive/v1
+  target_kind: PatternInsight
+  alias: cognitive-pattern-insight
+  origin: github.com/ruinosus/dna/cognitive
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: pattern-insights
+    marker: PATTERN_INSIGHT.md
+    body_field: body
+  dep_filters:
+    dream_ref: sdlc-synthesis-run
+  schema:
+    type: object
+    required:
+    - dream_ref
+    - framework
+    - engine
+    - summary
+    properties:
+      dream_ref:
+        type: string
+        description: Slug of the SynthesisRun being interpreted.
+      framework:
+        type: string
+        enum:
+        - hill
+        - jung
+        - gestalt
+        - pattern
+        - freudian
+        - other
+        description: Interpretation school applied.
+      engine:
+        type: string
+        description: Engine name from registry (e.g. 'hill-interp').
+      engine_params:
+        type: object
+        default: {}
+        description: Params passed to the engine.
+      summary:
+        type: string
+        maxLength: 800
+        description: 1-3 sentence overview of the interpretation.
+      exploration:
+        type: object
+        description: 'Hill: stage 1 — re-reading, associations, trigger, affect
+          layer.'
+        properties:
+          re_reading:
+            type: string
+          associations:
+            type: array
+            items:
+              type: object
+              properties:
+                fragment:
+                  type: string
+                amplifies_to:
+                  type: array
+                  items:
+                    type: string
+          trigger:
+            type: string
+          affect_layer:
+            type: string
+      insight:
+        type: object
+        description: 'Hill: stage 2 — what does the dream MEAN? Level in {waking,
+          phenomenological, past, parts-of-self}.'
+        properties:
+          level:
+            type: string
+            enum:
+            - waking
+            - phenomenological
+            - past
+            - parts-of-self
+          statement:
+            type: string
+            maxLength: 1500
+          questions:
+            type: array
+            items:
+              type: string
+      action:
+        type: object
+        description: 'Hill: stage 3 — what would you DO differently? May propose
+          concrete docs (ArchiveProposal, Story, PreMortem) for HITL approval.'
+        properties:
+          propose:
+            type: array
+            items:
+              type: object
+              properties:
+                kind:
+                  type: string
+                name:
+                  type: string
+                reason:
+                  type: string
+          follow_up:
+            type: string
+      amplifications:
+        type: array
+        items:
+          type: object
+          properties:
+            symbol:
+              type: string
+            archetype:
+              type: string
+            amplifies_to:
+              type: array
+              items:
+                type: string
+        description: 'Jung: each symbol expanded by association.'
+      individuation_question:
+        type: string
+        description: 'Jung: integration question opening reflection.'
+      identifications:
+        type: array
+        items:
+          type: object
+          properties:
+            element:
+              type: string
+            i_am_voice:
+              type: string
+        description: 'Gestalt: voice of each element as the dreamer.'
+      drafted_at:
+        type: string
+        format: date-time
+      generated_by:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+        default: []
+      owner:
+        type: string
+        description: 'Slug reference to a Agent. When set, this PatternInsight
+          is PRIVATE to that agent. When null, it is GENERAL. Phase: cognitive-reflection.'
+      lens:
+        type: string
+        description: 'Perspectiva da interpretação. Valores convencionais: ''hill'',
+          ''jung'', ''gestalt'', ''pattern'', um slug de Agent (ex: ''jarvis'',
+          ''architect''), ou ''synthesis-by-<agent>'' pra meta-synthesis. Pode coincidir
+          com framework — lens é o ponto de vista, framework é a metodologia. Phase:
+          cognitive-reflection.'
+      synthesizes:
+        type: array
+        items:
+          type: string
+        default: []
+        description: 'PatternInsight IDs (names/slugs) que esta interpretação sintetiza.
+          Vazia pra interpretações de 1ª camada (hill, jung, agent-interp). Não-vazia
+          pra synthesis engines (agent-synthesis) que lêem N interps + SynthesisRun
+          e produzem leitura final. Phase: cognitive-reflection.'
+  # Curated list/tree projection (essência que o to_card morto elegia).
+  # DELTA INTENCIONAL: a classe ecoava o spec inteiro (KindBase default);
+  # list endpoints não usam summary() — produção inalterada.
+  summary:
+    dream_ref: ''
+    framework: ''
+    engine: ''
+    summary: ''
+    owner: null
+    lens: null
+    synthesizes: []
+  graph_style:
+    fill: '#F472B6'
+    stroke: '#BE185D'
+    text_color: '#fff'
+  ascii_icon: 💭
+  display_label: Pattern Insights
+  docs: PatternInsight = output of a dream-interp engine. Multiple interpretations
+    per SynthesisRun OK — engines are complementary lenses, not exclusive. Hill
+    engine produces exploration/insight/action structure; Jung produces amplifications
+    + archetypes; Gestalt produces identifications.

package/dist/extensions/sdlc/kinds/postmortem.kind.yaml

@@ -0,0 +1,168 @@
+# Postmortem — blameless incident analysis per Google SRE (record plane).
+# Factual: the incident HAPPENED (timeline + root cause + action items).
+# Distinct from PreMortem (hypothetical) and Retrospective (period summary).
+#
+# 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/Postmortem.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: postmortem
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Postmortem
+  alias: sdlc-postmortem
+  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: postmortems
+    marker: POSTMORTEM.md
+    body_field: body
+  dep_filters:
+    related_stories: sdlc-story
+    related_features: sdlc-feature
+  schema:
+    type: object
+    required:
+    - title
+    - incident_at
+    - severity
+    - root_cause
+    properties:
+      title:
+        type: string
+        description: Short incident headline.
+      incident_at:
+        type: string
+        format: date-time
+        description: When incident started.
+      resolved_at:
+        type: string
+        format: date-time
+        description: When incident was mitigated.
+      severity:
+        type: string
+        enum:
+        - sev1
+        - sev2
+        - sev3
+        - sev4
+        - sev5
+        description: Incident severity (sev1=full outage, sev5=cosmetic).
+      blameless:
+        type: boolean
+        default: true
+        description: Google SRE requirement — should always be true.
+      impact:
+        type: string
+        description: Customer-facing impact in plain language (downtime, errors, etc.).
+      timeline:
+        type: array
+        items:
+          type: object
+          required:
+          - at
+          - event
+          properties:
+            at:
+              type: string
+              format: date-time
+            event:
+              type: string
+            actor:
+              type: string
+        description: Chronological event log.
+      root_cause:
+        type: string
+        description: Primary cause (1-3 paragraphs).
+      contributing_factors:
+        type: array
+        items:
+          type: string
+        description: Secondary factors that worsened the incident.
+      what_went_well:
+        type: array
+        items:
+          type: string
+        description: Detection / response things that worked.
+      what_went_wrong:
+        type: array
+        items:
+          type: string
+        description: Detection / response things that didn't work.
+      action_items:
+        type: array
+        items:
+          type: object
+          required:
+          - title
+          properties:
+            title:
+              type: string
+            owner:
+              type: string
+            due:
+              type: string
+              format: date
+            story_ref:
+              type: string
+            status:
+              type: string
+              enum:
+              - todo
+              - in-progress
+              - done
+        description: Concrete follow-ups to prevent recurrence.
+      lessons_learned:
+        type: array
+        items:
+          type: string
+        description: Insights that generalize beyond this incident.
+      related_stories:
+        type: array
+        items:
+          type: string
+        description: Story slugs related to root cause or action items.
+      related_features:
+        type: array
+        items:
+          type: string
+      tags:
+        type: array
+        items:
+          type: string
+      body:
+        type: string
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+  summary:
+    title: ''
+    severity: ''
+    incident_at: ''
+    resolved_at: ''
+  graph_style:
+    fill: '#DC2626'
+    stroke: '#991B1B'
+    text_color: '#fff'
+  ascii_icon: 🚨
+  display_label: Postmortems
+  docs: 'A Postmortem captures a factual analysis of an incident that happened — timeline,
+    root cause, contributing factors, action items, lessons learned. Google SRE convention:
+    blameless. Distinct from PreMortem (hypothetical) and Retrospective (recurring
+    period summary).'

package/dist/extensions/sdlc/kinds/pre-mortem.kind.yaml

@@ -0,0 +1,145 @@
+# PreMortem — "what would have happened" hindsight rewrite of a Story's
+# outcome (record plane). Pairs with SynthesisRun (forward-looking) for the
+# cognitive memory triad's hindsight dimension. Verifiable:
+# would_have_changed predictions are checked at outcome_check_at by the
+# same verifier as SynthesisRun.
+#
+# F3 lote-1 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the PreMortemKind class (Py) was deleted. This kind was
+# Py-ONLY before F3 — the descriptor gives TS the kind for free
+# (kind-registry-parity.json: moved py_only_allowlist → ts_aliases).
+# PARITY-CRITICAL package data — byte-identical mirror under
+# packages/sdk-{py,ts}; tests/test_descriptor_hash_parity.py enforces.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: pre-mortem
+spec:
+  target_api_version: github.com/ruinosus/dna/cognitive/v1
+  target_kind: PreMortem
+  alias: cognitive-pre-mortem
+  origin: github.com/ruinosus/dna/cognitive
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: pre-mortems
+    marker: PRE_MORTEM.md
+    body_field: body
+  dep_filters:
+    source_story: sdlc-story
+  schema:
+    type: object
+    required:
+    - source_story
+    - source_outcome
+    - alternative
+    - divergence_point
+    - would_have_changed
+    properties:
+      source_story:
+        type: string
+        description: Slug of the Story being rewritten (e.g. 's-foo-bar').
+      source_outcome:
+        type: string
+        enum:
+        - cancelled
+        - done
+        - dropped
+        - paused
+        description: What ACTUALLY happened to source_story.
+      alternative:
+        type: string
+        description: 'Prose: ''If instead of <outcome>, the Story had <other path>,
+          then...''. 2-4 sentences.'
+      divergence_point:
+        type: string
+        description: Decision/event that branched the timeline. Cite a date or trigger
+          event.
+      evidence_for:
+        type: array
+        items:
+          type: string
+        default: []
+        description: Doc refs supporting the counterfactual.
+      evidence_against:
+        type: array
+        items:
+          type: string
+        default: []
+        description: Doc refs that complicate the counterfactual.
+      would_have_changed:
+        type: array
+        items:
+          type: object
+          required:
+          - metric
+          - from
+          - to
+          properties:
+            metric:
+              type: string
+            from: {}
+            to: {}
+            by:
+              type: string
+              format: date
+        description: Predictions same shape as SynthesisRun.would_change. Verifiable
+          via same measure_metrics path.
+      strength:
+        type: string
+        enum:
+        - weak
+        - medium
+        - strong
+        default: medium
+      status:
+        type: string
+        enum:
+        - drafted
+        - observing
+        - realized
+        - falsified
+        default: drafted
+      outcome_check_at:
+        type: string
+        format: date-time
+        description: When to verify (same loop as SynthesisRun).
+      drafted_at:
+        type: string
+        format: date-time
+      generated_by:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+        default: []
+      verifications:
+        type: array
+        items:
+          type: object
+        default: []
+        description: Verification trace (auto-populated by the verifier).
+  # Curated list/tree projection (campos-âncora do arc do PreMortem; defaults
+  # de status/strength espelham os defaults do schema). DELTA INTENCIONAL: a
+  # classe ecoava o spec inteiro (KindBase default); list endpoints não usam
+  # summary() — produção inalterada.
+  summary:
+    source_story: ''
+    source_outcome: ''
+    status: drafted
+    strength: medium
+  graph_style:
+    fill: '#FBBF24'
+    stroke: '#D97706'
+    text_color: '#fff'
+  ascii_icon: ↩️
+  display_label: PreMortems
+  docs: 'A PreMortem rewinds a Story''s history and asks what would have happened
+    on the other branch. Generated by a deep-sleep hindsight hook after Stories
+    ship/cancel. Verifiable: would_have_changed predictions are compared against
+    current state at outcome_check_at — same verifier as SynthesisRun.'