dna-sdk 0.1.0

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

@@ -0,0 +1,125 @@
+# Forecast — falseable forward-looking prediction (record plane).
+# would_change predictions are verified at outcome_check_at by the
+# cognitive/verification.py loop. Pair: SynthesisRun (oneiric, non-falseable).
+#
+# 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/Forecast.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: forecast
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Forecast
+  alias: sdlc-forecast
+  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: forecasts
+    marker: FORECAST.md
+    body_field: body
+  schema:
+    type: object
+    required:
+    - forecaster
+    - timeframe
+    - scope_ref
+    - scenario
+    - would_change
+    - evidence_from_present
+    - status
+    - outcome_check_at
+    properties:
+      forecaster:
+        type: string
+        description: Author — oracle slug or 'user'.
+      timeframe:
+        type: string
+        enum:
+        - in-7d
+        - in-30d
+        - in-90d
+        - in-1y
+      scope_ref:
+        type: string
+      lens:
+        type: string
+        description: Optional perspective tag (optimism|risk|friction|opportunity|neutral).
+      scenario:
+        type: string
+        maxLength: 2000
+        description: Prose framing of the hypothesis.
+      would_change:
+        type: array
+        items:
+          type: object
+          required:
+          - metric
+          - from
+          - to
+          properties:
+            metric:
+              type: string
+            from: {}
+            to: {}
+            by:
+              type: string
+        minItems: 1
+        description: Predictions checked by verification.py.
+      evidence_from_present:
+        type: array
+        items:
+          type: string
+        default: []
+      status:
+        type: string
+        enum:
+        - drafted
+        - observing
+        - fulfilled
+        - refuted
+        - expired
+      outcome_check_at:
+        type: string
+        format: date-time
+      drafted_at:
+        type: string
+        format: date-time
+      resolved_at:
+        type: string
+        format: date-time
+      verifications:
+        type: array
+        items:
+          type: object
+        default: []
+        description: Audit trail appended by verification loop.
+      generated_by:
+        type: string
+      source_oracle:
+        type: string
+  summary:
+    forecaster: ''
+    lens: null
+    status: ''
+  graph_style:
+    fill: '#60A5FA'
+    stroke: '#2563EB'
+    text_color: '#fff'
+  ascii_icon: 📊
+  display_label: Forecasts
+  docs: Forecast = falseable hypothesis. would_change predictions are verified at
+    outcome_check_at by the cognitive/verification.py loop. Authored by oracles or
+    user. Pair with SynthesisRun (oneiric artefact, non-falseable processing).

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

@@ -0,0 +1,87 @@
+# Insight — SLIM metadata binding a perpetual question to a target UA
+# (record plane; s-insight-slim-refactor). The UA owns persona + heuristics
+# + LLM config; the runner iterates active Insights and dispatches each.
+#
+# 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/Insight.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: insight
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Insight
+  alias: sdlc-insight
+  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: insights
+    marker: INSIGHT.md
+    body_field: description
+  schema:
+    type: object
+    required:
+    - question
+    - target_ua
+    properties:
+      question:
+        type: string
+        description: The perpetual question this oracle pursues.
+      target_ua:
+        type: string
+        description: Slug of the Agent that runs this oracle (e.g. 'oracle-health').
+          The UA owns the persona, tools, and LLM config — Insight only points.
+      icon:
+        type: string
+        description: Single emoji shown next to the oracle.
+      cadence_hours:
+        type: integer
+        minimum: 0
+        default: 24
+        description: How often the runner re-dispatches the target_ua. 0 disables
+          auto-run (manual only via /agent endpoint).
+      evidence_kinds:
+        type: array
+        items:
+          type: string
+        description: Hint of which Kinds the target_ua should read. Informational
+          — the UA itself decides via its tools.
+      active:
+        type: boolean
+        default: true
+        description: False to disable without deleting.
+      tags:
+        type: array
+        items:
+          type: string
+      description:
+        type: string
+        description: Optional 1-2 sentence human description of what this oracle answers.
+          The INSIGHT.md body.
+  summary:
+    question: ''
+    target_ua: ''
+    icon: ''
+    active: true
+  graph_style:
+    fill: '#7C3AED'
+    stroke: '#5B21B6'
+    text_color: '#fff'
+  ascii_icon: 🔮
+  display_label: Insights
+  docs: An Insight binds a perpetual question to a target UA (oracle-X). The UA owns
+    the persona + heuristics + LLM selection. The runner iterates active Insights
+    and dispatches each to its target_ua, which emits an StatusReport via create_status_report
+    tool.

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

@@ -0,0 +1,106 @@
+# Kaizen — a continuous-improvement observation, first-class (record plane).
+#
+# The kaizen discipline (skill .claude/skills/kaizen): while working on ANY
+# task, noticing something improvable — a code smell, flow friction, a
+# repeated manual step, something hardcoded, a missing test/doc — and
+# flagging it WITHOUT derailing the current task. Historically these lived
+# only as `kaizen` timeline events on work items (`dna sdlc kaizen <wi>
+# --body`) — visible in the FOCUS feed but not queryable/searchable as docs.
+#
+# s-kaizen-kind: each observation is ALSO a Kaizen doc, so the backlog of
+# noticed-but-not-yet-routed improvements is queryable (kernel.query),
+# embeddable (semantic search), and auditable. Arc: observed (noticed) →
+# routed (an Issue/Story tracks the fix) → resolved (fix shipped).
+#
+# F3 P2 pilot (spec 2026-06-10-kinds-descriptor-f3): first builtin Kind
+# expressed as a descriptor instead of twin Py/TS classes. PARITY-CRITICAL
+# package data — the byte-identical mirror lives at
+# packages/sdk-{py,ts}/{dna/extensions,src/extensions}/sdlc/kinds/
+# kaizen.kind.yaml; edit one side, copy to the other byte-for-byte
+# (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: kaizen
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Kaizen
+  alias: sdlc-kaizen
+  origin: github.com/ruinosus/dna/sdlc
+  # SDLC primitives are project-level, not per-tenant.
+  tenant_scope: global
+  # Record plane — pure typed document: cacheless writes, never composes
+  # into agent prompts.
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: kaizens
+  # `work_item` is intentionally NOT here: it's a polymorphic "Kind/slug"
+  # string (Story/s-x, Issue/i-1, Spike/...) and dep_filters can only
+  # target ONE kind. `issue` is the routed-fix tracker and is an Issue
+  # slug by convention.
+  dep_filters:
+    issue: sdlc-issue
+  schema:
+    type: object
+    required: [body, status]
+    properties:
+      body:
+        type: string
+        description: The kaizen observation (what could be better).
+      work_item:
+        type: string
+        description: "Kind/slug of the work item where this was observed (polymorphic — Story/Spike/Issue)."
+      issue:
+        type: string
+        description: Issue/Story slug tracking the fix.
+      status:
+        type: string
+        enum: [observed, routed, resolved]
+        default: observed
+        description: "Observation arc: observed (flagged) → routed (fix tracked in `issue`) → resolved (fix shipped)."
+      actor:
+        type: string
+        description: Who flagged it.
+      labels:
+        type: array
+        items:
+          type: string
+        description: Free-form theme tags (weighted into semantic-search source text).
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+    # Strict (s-strict-schema-lint ratchet): new Kinds ship
+    # additionalProperties:false — schema is a contract.
+    additionalProperties: false
+  # List-endpoint projection ({field: default}).
+  summary:
+    status: observed
+    work_item: ""
+    issue: ""
+    actor: ""
+    labels: []
+  # Embedding source text (D4 derivation): essence is the observation body
+  # + labels (free-form tags like "dx", "hardcoded"). work_item/issue are
+  # slugs, not topical signal — found via refs, not embedding.
+  embed: [body, labels]
+  graph_style:
+    fill: "#10B981"
+    stroke: "#047857"
+    text_color: "#fff"
+  ascii_icon: "♻️"
+  display_label: Kaizens
+  docs: >-
+    A Kaizen is a continuous-improvement observation noticed while
+    working on something else — a smell, friction, a manual step, a
+    missing test — captured as a first-class doc WITHOUT derailing
+    the task at hand. Arc: observed → routed (an Issue/Story tracks
+    the fix) → resolved (fix shipped). Twin of the `kaizen` timeline
+    event on the originating work item (which carries a ref back to
+    this doc).

package/dist/extensions/sdlc/kinds/lesson-learned.kind.yaml

@@ -0,0 +1,270 @@
+# LessonLearned — affective recall artifact (record plane; memory triad).
+#
+# Surfaces unbidden when the current cycle resembles a past one in the same
+# area. Authored by the Sage oracle during the deep-sleep ritual (mostly) or
+# manually. Body prose lives in the bundle marker (LESSON_LEARNED.md);
+# structured fields in the YAML frontmatter. Studio surface label is
+# enterprise pt-BR ("Lições Aprendidas" — s-sdlcv2-memorias-market-viz).
+#
+# F3 lote-1 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the twin LessonLearnedKind classes (Py+TS) were deleted.
+# PARITY-CRITICAL package data — byte-identical mirror under
+# packages/sdk-{py,ts}; tests/test_descriptor_hash_parity.py enforces.
+# O descriptor cura um drift real Py↔TS: a classe TS era strict e NÃO tinha
+# affect_reason/affect_evidence_refs/encoding extras — o canônico é a
+# superfície Py (o que kinds-api serve em produção). A classe Py tinha um
+# to_card morto (zero consumidores) — não migrado de propósito.
+# `embed:` substitui o branch hardcoded de source_text_for + a entrada no
+# frozenset legado EMBEDDABLE_KINDS (F3 D4) — mesmos campos, mesmo join.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: lesson-learned
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: LessonLearned
+  alias: sdlc-lesson-learned
+  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: lessons-learned
+    marker: LESSON_LEARNED.md
+    body_field: body
+  schema:
+    type: object
+    required:
+    - area
+    - surface_when
+    - source_refs
+    - affect
+    - summary
+    properties:
+      area:
+        type: string
+        description: 'Scoped target: Feature/X, Epic/Y, or Roadmap/Z. The LessonLearned
+          surfaces when this area is touched.'
+      surface_when:
+        type: array
+        items:
+          type: string
+          enum:
+          - feature_touched
+          - cycle_open
+          - session_start
+          - oracle_consult
+        minItems: 1
+        description: Triggers that surface this LessonLearned. Mirrors how human
+          recall fires unbidden in context.
+      source_refs:
+        type: array
+        items:
+          type: string
+        minItems: 1
+        description: Pointers to source artifacts (Narrative/X, WorkflowEvent/Y,
+          etc.) that this memory derives from.
+      affect:
+        type: string
+        enum:
+        - triumph
+        - regret
+        - surprise
+        - wistful
+        - ominous
+        description: 'Emotional tone. Evocative palette (Spec §15 decision): triumph,
+          regret, surprise, wistful, ominous.'
+      affect_reason:
+        type: string
+        minLength: 20
+        description: Story s-remembrance-affect-reason-required. Concrete justification
+          for the chosen affect — names specific slugs/SHAs/AC counts/state. NOT
+          generic ('Story closed', 'shipped successfully'). Validator rejects writes
+          that lack reason OR have boilerplate. Required for high-stakes affects
+          (regret/ominous/surprise); optional for triumph/wistful but encouraged.
+      affect_evidence_refs:
+        type: array
+        items:
+          type: string
+        description: Concrete refs (rem-X, verdict-Y, Story/s-Z) that back the affect
+          choice. Required for high-stakes affects so the LLM's claim is auditable
+          against actual artifacts in the manifest.
+      summary:
+        type: string
+        maxLength: 280
+        description: 1-2 sentence 'Lembre-se de...' — the recalled essence.
+      relevance_decay_seed:
+        type: number
+        default: 0.95
+        description: Multiplicative decay factor applied per 24h. Default 0.95 (~30%
+          relevance after 14 days).
+      last_surfaced:
+        type: string
+        format: date-time
+        description: Auto-stamped on each surfacing; null until first surface.
+      surface_count:
+        type: integer
+        default: 0
+        description: Increments on each surface. Damps re-surfacing via scoring
+          formula in retrieval.py.
+      confidence_score:
+        type: number
+        default: 1.0
+        description: Semon engram intensity. Multiplies BM25 score in retrieval.
+          Bumps when homophonic LessonsLearned (same area) are filed — engrams reinforce
+          each other. Decays with surface_count for hygiene.
+      cues_history:
+        type: array
+        items:
+          type: object
+          properties:
+            at:
+              type: string
+              format: date-time
+            cue:
+              type: string
+            actor:
+              type: string
+        default: []
+        description: Semon ecforia trace. Each time the LessonLearned is surfaced
+          via remember(), the cue (query + actor + timestamp) is appended. History
+          of WHY this memory kept getting recalled.
+      revisions:
+        type: array
+        items:
+          type: object
+          properties:
+            at:
+              type: string
+              format: date-time
+            by:
+              type: string
+            delta:
+              type: string
+        default: []
+        description: Reconsolidation log (Nader 2000 / neo-Semon). Append-only when
+          a recall reawakens the engram and the consumer updates the summary.
+      tags:
+        type: array
+        items:
+          type: string
+        default: []
+      owner:
+        type: string
+        description: 'ATTRIBUTION: which agent authored this memory (e.g. claude-code,
+          jarvis). Orthogonal to scope + to tenant (tenant separates USERS, owner
+          separates AGENTS). Recall AUDIENCE is governed by `visibility`, NOT by
+          owner (s-agent-memory-phase-0-bridge, 2026-06-02 — supersedes the 2026-05-17
+          owner-implies-private semantics). When absent: an unowned/project lesson
+          (shared).'
+      visibility:
+        type: string
+        enum:
+        - shared
+        - private
+        - pinned
+        - archived
+        default: shared
+        description: 'Recall audience (the customization axis): shared = all agents
+          in scope recall it (cross-agent knowledge, default); private = only `owner`
+          recalls it (an agent''s raw working memory); pinned = always injected
+          into working memory at bootstrap, bypassing recall scoring (the Letta
+          ''memory block''); archived = retained + auditable but excluded from default
+          recall (soft-forget). Humans audit ALL regardless of visibility (audit
+          != recall). Phase 0 (2026-06-02).'
+      memory_type:
+        type: string
+        enum:
+        - episodic
+        - semantic
+        - procedural
+        description: 'CoALA taxonomy — ORTHOGONAL to the Semon EngramState (type
+          vs state): episodic = what happened (instance/sequence); semantic = a
+          generalized fact about the world/user; procedural = how to act (a skill/rule).
+          Absent = untyped (legacy).'
+      valid_from:
+        type: string
+        format: date-time
+        description: 'World-time validity start (Zep bi-temporal). Default: created_at.'
+      valid_to:
+        type: string
+        format: date-time
+        description: World-time validity end. Set when superseded/contradicted —
+          the memory is INVALIDATED, never hard-deleted. Default recall excludes
+          valid_to<now.
+      superseded_by_memory:
+        type: string
+        description: Name of the memory that invalidated this one (not `superseded_by`
+          — that's an ADR dep_filter token). Pairs with valid_to for point-in-time
+          audit.
+      encoding_context:
+        type: object
+        description: Snapshot of the conditions at engraphy. semon-recaller scores
+          ecphory candidates by partial-match against this dict.
+        properties:
+          area:
+            type: string
+          affect:
+            type: string
+          co_topics:
+            type: array
+            items:
+              type: string
+            description: Last 3-5 topic tags active at engraphy.
+          source_refs:
+            type: array
+            items:
+              type: string
+          time_of_day:
+            type: string
+            description: morning|afternoon|evening|night — coarse temporal cue.
+          day_of_week:
+            type: string
+          engraphed_by:
+            type: string
+            description: Agent slug that decided to engraph (semon-scribe by default).
+        additionalProperties: true
+      homophonic_links:
+        type: array
+        description: Semon homophony — engrams sharing substrate features. Each
+          link records target + resonance score + basis. semon-recaller propagates
+          a small strength boost (+0.02) to neighbors on ecphory (resonance).
+        items:
+          type: object
+          properties:
+            target_name:
+              type: string
+            resonance_score:
+              type: number
+              minimum: 0
+              maximum: 1
+            basis:
+              type: string
+              description: co-area | co-affect | co-temporal | semantic | manual
+          required:
+          - target_name
+        default: []
+  # Curated list/tree projection. DELTA INTENCIONAL vs a classe extinta: o
+  # KindBase default ecoava o spec INTEIRO no navigator — gordo demais. Os
+  # campos abaixo são a essência que a classe TS (summary) e o to_card morto
+  # já elegiam. List endpoints (/docs/{kind}) não usam summary() — payloads
+  # de produção inalterados (pinado no teste de equivalência).
+  summary:
+    area: ''
+    affect: ''
+    summary: ''
+    surface_count: 0
+    owner: null
+  embed:
+  - summary
+  - body
+  graph_style:
+    fill: '#FBBF24'
+    stroke: '#D97706'
+    text_color: '#fff'
+  ascii_icon: 💭
+  display_label: Lições Aprendidas