dna-sdk 0.1.0

package/dist/extensions/sdlc/kinds/archive-proposal.kind.yaml

@@ -0,0 +1,107 @@
+# ArchiveProposal — pruning proposal (record plane). Always a *proposal*,
+# never an execution: user (or Veto Hook) approves before the target moves
+# to _forgotten/. Reversible via `dna sdlc forget undo`.
+#
+# 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/ArchiveProposal.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: archive-proposal
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: ArchiveProposal
+  alias: sdlc-archive-proposal
+  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: archive-proposals
+    marker: ARCHIVE_PROPOSAL.md
+    body_field: body
+  schema:
+    type: object
+    required:
+    - target_kind
+    - target_name
+    - reason
+    - evidence
+    - proposed_by
+    - status
+    - review_deadline
+    properties:
+      target_kind:
+        type: string
+        description: Any Kind name (e.g. 'Plan', 'Story', 'Issue', 'Spec'). Self-references
+          rejected at execution time.
+      target_name:
+        type: string
+        description: Slug of the doc being proposed for forgetting.
+      reason:
+        type: string
+        enum:
+        - orphan
+        - superseded
+        - stale
+        - contradicted
+        - duplicate
+        description: Why prune. orphan = no inbound refs; superseded = newer doc replaces;
+          stale = no touch beyond threshold; contradicted = newer doc disagrees; duplicate
+          = identical.
+      evidence:
+        type: string
+        description: Plain-text justification. E.g. 'Unreferenced by any WorkflowEvent.methodology_artifact
+          in 91 entries scanned. Last touch 73 days ago.'
+      proposed_at:
+        type: string
+        format: date-time
+        description: Auto-stamped on creation.
+      proposed_by:
+        type: string
+        description: Oracle slug (typically 'cleanup-suggestions') or 'user'.
+      status:
+        type: string
+        enum:
+        - proposed
+        - approved
+        - vetoed
+        - executed
+        description: proposed → approved → executed (moves target to _forgotten/)
+          OR proposed → vetoed (target stays).
+      review_deadline:
+        type: string
+        format: date-time
+        description: 'Spec §15: default proposed_at + 14d. Stale proposals past this
+          date should be re-evaluated (not auto-vetoed).'
+      reviewer:
+        type: string
+        description: Auto-stamped on approve/veto. Username or 'system'.
+      reviewer_note:
+        type: string
+        description: Optional note explaining approval/veto reasoning.
+  summary:
+    target_kind: ''
+    target_name: ''
+    reason: ''
+    status: ''
+  embed:
+  - reason
+  - target_kind
+  - target_name
+  graph_style:
+    fill: '#94A3B8'
+    stroke: '#475569'
+    text_color: '#fff'
+  ascii_icon: 🪦
+  display_label: Arquivamento

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

@@ -0,0 +1,108 @@
+# Changelog — release notes per semver version, Keep a Changelog 1.1.0
+# (record plane). One doc per project (canonical name='CHANGELOG');
+# spec.versions[] is the reverse-chronological release list.
+#
+# 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/Changelog.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: changelog
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: Changelog
+  alias: sdlc-changelog
+  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: changelogs
+    marker: CHANGELOG.md
+    body_field: body
+  schema:
+    type: object
+    required:
+    - title
+    properties:
+      title:
+        type: string
+        description: Project name typically.
+      description:
+        type: string
+      versions:
+        type: array
+        items:
+          type: object
+          required:
+          - version
+          properties:
+            version:
+              type: string
+              description: SemVer 2.0 (e.g. '1.4.2') or '[Unreleased]'.
+            date:
+              type: string
+              format: date
+            added:
+              type: array
+              items:
+                type: string
+              description: New features.
+            changed:
+              type: array
+              items:
+                type: string
+              description: Changes in existing functionality.
+            deprecated:
+              type: array
+              items:
+                type: string
+              description: Soon-to-be removed.
+            removed:
+              type: array
+              items:
+                type: string
+              description: Removed in this version.
+            fixed:
+              type: array
+              items:
+                type: string
+              description: Bug fixes.
+            security:
+              type: array
+              items:
+                type: string
+              description: Vulnerability fixes.
+        description: Reverse-chronological list of versions.
+      body:
+        type: string
+        description: Optional full markdown CHANGELOG.md.
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+  summary:
+    title: ''
+    description: ''
+  graph_style:
+    fill: '#84CC16'
+    stroke: '#65A30D'
+    text_color: '#fff'
+  ascii_icon: 📋
+  display_label: Changelogs
+  docs: 'A Changelog records release notes per semver version per Keep a Changelog
+    1.1.0 convention. Six sections: Added, Changed, Deprecated, Removed, Fixed, Security.
+    Latest entry at top (reverse chronological). [Unreleased] section tracks work
+    in flight.'

package/dist/extensions/sdlc/kinds/cognitive-policy.kind.yaml

@@ -0,0 +1,470 @@
+# CognitivePolicy — the UNIFIED declarative policy for the cognitive runtime
+# (record plane; scope-overridable like the old RecallPolicy: resolution is
+# scope doc → _lib default → code defaults, fail-soft).
+#
+# s-consolidate-cognitive-policies (f-kind-catalog-governance, 2026-07-07):
+# the 9 single-instance policy Kinds — RecallPolicy, DecayPolicy, the old
+# CognitivePolicy (now the `generation` section), MemoryPolicy,
+# AllocationPolicy, PaginationPolicy, EngramStrengthPolicy, EmbeddingProfile,
+# AffectPalette — were "fields that became Kinds". They shared plane (record),
+# instance count (exactly one `default` doc each) and resolution shape, so
+# they were consolidated into ONE Kind with one top-level section per former
+# Kind. A partial doc tunes only the sections it names (per-scope overrides
+# stay cheap: po-as-a-service carries only `recall.semantic`).
+#
+# Consumption invariants preserved at the CONSUMER, not the schema:
+#   - `embedding` is only ever read from the _lib doc
+#     (kernel.embedding_profile stays _lib-direct) — the embedding space is
+#     intrinsically global, a scope must NOT be able to fork it.
+#   - `pagination` keeps its own resolver entry point
+#     (dna_shared.pagination_policy) — REST data-plane ownership.
+#   - `memory` keeps the MemoryPolicy multi-matcher merge semantics via the
+#     `memory.policies[]` array (applies_to / defaults / remember,
+#     most-specific-wins — dna_shared.cognitive.memory_policy).
+#
+# Schema is CLOSED (additionalProperties: false) — this family left
+# _GRANDFATHERED_OPEN_SCHEMAS. The 8 retired names are pinned in
+# Kernel._REMOVED_KINDS (+ _REMOVED_KIND_NOTES). PARITY-CRITICAL:
+# byte-identical mirror at
+# packages/sdk-{py,ts}/{dna/extensions,src/extensions}/sdlc/kinds/
+# cognitive-policy.kind.yaml (test_descriptor_hash_parity enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: cognitive-policy
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: CognitivePolicy
+  alias: sdlc-cognitive-policy
+  origin: github.com/ruinosus/dna/sdlc
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  is_runtime_artifact: false
+  dep_filters: {}
+  storage:
+    type: yaml
+    container: cognitive-policies
+  schema:
+    type: object
+    additionalProperties: false
+    properties:
+      recall:
+        type: object
+        additionalProperties: false
+        description: Recall-tuning knobs for the ecphory engine (ex-RecallPolicy).
+        properties:
+          calibrated_for:
+            type: object
+            additionalProperties: false
+            description: Validity envelope — the embedding model/dimension/language
+              the semantic knobs were calibrated for. If the `embedding` section
+              changes, these are stale and must be re-calibrated.
+            properties:
+              embedding_model:
+                type: string
+              dimensions:
+                type: integer
+              language:
+                type: string
+          semantic:
+            type: object
+            additionalProperties: false
+            description: Embedding-coupled knobs (model+dimension+language). Cosine
+              only means anything within one embedding space — re-calibrate on change.
+            properties:
+              theta_in:
+                type: number
+                default: 0.30
+                description: Enter the working set when the fresh score >= this.
+              theta_out:
+                type: number
+                default: 0.23
+                description: Hold a prior member while its score >= this (hysteresis).
+              direct_threshold:
+                type: number
+                default: 0.30
+                description: Ecphory direct gate (mirrors theta_in).
+              cosine_weight:
+                type: number
+                default: 0.61
+                description: Weight on the raw embedding cosine in the content
+                  dimension (calibrated 0.55->0.61, 2026-06-15).
+          structural:
+            type: object
+            additionalProperties: false
+            description: Theory-derived weights (Tulving/Nairne/Semon). Stable across
+              model and language.
+            properties:
+              content_weight:
+                type: number
+                default: 0.55
+              summary_partial_weight:
+                type: number
+                default: 0.28
+              co_topics_weight:
+                type: number
+                default: 0.20
+              source_refs_weight:
+                type: number
+                default: 0.15
+              affect_weight:
+                type: number
+                default: 0.05
+              time_weight:
+                type: number
+                default: 0.05
+              novelty_boost:
+                type: number
+                default: 0.05
+              recency_boost:
+                type: number
+                default: 0.10
+              saturation_decay:
+                type: number
+                default: 0.6
+              saturation_threshold:
+                type: integer
+                default: 3
+                description: Recent-24h cue count that triggers saturation decay.
+          retrieval:
+            type: object
+            additionalProperties: false
+            description: Shape of retrieval — how many results, how to diversify and
+              spread. Not coupled to the embedding model nor to memory theory.
+            properties:
+              k:
+                type: integer
+                default: 5
+                description: Final working-set size injected per turn.
+              mmr_lambda:
+                type: number
+                default: 0.3
+                description: MMR redundancy penalty (diversity vs raw score).
+              limit_direct:
+                type: integer
+                default: 8
+                description: Max direct ecphory hits considered.
+              limit_homophonic:
+                type: integer
+                default: 6
+                description: Max homophony-expanded hits considered.
+              spread_depth:
+                type: integer
+                default: 2
+                description: Spreading-activation hops from the direct hits.
+              spread_decay:
+                type: number
+                default: 0.7
+                description: Activation decay per spreading hop.
+              search_n:
+                type: integer
+                default: 50
+                description: pgvector candidates pulled for the cosine overlay.
+      decay:
+        type: object
+        additionalProperties: false
+        description: Memory retention/forgetting knobs (ex-DecayPolicy).
+        properties:
+          stability_tiers:
+            type: object
+            additionalProperties: false
+            description: Ebbinghaus stability per confidence tier, in days.
+            properties:
+              faint:
+                type: number
+                default: 5.0
+              firm:
+                type: number
+                default: 15.0
+              burning:
+                type: number
+                default: 45.0
+          default_stability_days:
+            type: number
+            default: 15.0
+            description: Fallback stability when no tier/stability is on the doc.
+          max_stability_days:
+            type: number
+            default: 60.0
+            description: Per-recall bump ceiling (so frequent recalls don't compound forever).
+          relevance_decay_seed:
+            type: number
+            default: 0.95
+            description: Default multiplicative decay per 24h (spec override wins).
+          ranking_formula:
+            type: string
+            enum:
+            - simple
+            - actr
+            default: simple
+            description: 'simple = exponential decay (Sprint 1); actr = log power-law (Sprint 2).'
+      generation:
+        type: object
+        additionalProperties: false
+        description: Operational params for the memory-gen engines (the ORIGINAL
+          CognitivePolicy body, now one section among peers).
+        properties:
+          auto_shipped:
+            type: object
+            additionalProperties: false
+            description: Deterministic ship → engram producer.
+            properties:
+              lookback_days:
+                type: integer
+                default: 7
+                description: Window of recently-done Stories considered.
+              max_emit:
+                type: integer
+                default: 5
+                description: Max engrams emitted per run.
+          consolidation:
+            type: object
+            additionalProperties: false
+            description: Episodic → semantic consolidation.
+            properties:
+              min_cluster_size:
+                type: integer
+                default: 3
+                description: Min episodic engrams in an area before consolidating.
+          backfill:
+            type: object
+            additionalProperties: false
+            description: Distil done Stories/Features into engrams.
+            properties:
+              budget:
+                type: integer
+                default: 50
+                description: Max engrams written per backfill run (resumable).
+      memory:
+        type: object
+        additionalProperties: false
+        description: Agent-memory governance (ex-MemoryPolicy). Each entry in
+          `policies` keeps the old multi-doc matcher semantics — merged
+          most-specific-wins by dna_shared.cognitive.memory_policy.
+        properties:
+          policies:
+            type: array
+            items:
+              type: object
+              additionalProperties: false
+              properties:
+                applies_to:
+                  type: object
+                  additionalProperties: false
+                  description: 'Matcher: any of scope/owner/memory_type (absent =
+                    wildcard). Most-specific wins.'
+                  properties:
+                    scope:
+                      type: string
+                    owner:
+                      type: string
+                    memory_type:
+                      type: string
+                      enum:
+                      - episodic
+                      - semantic
+                      - procedural
+                defaults:
+                  type: object
+                  additionalProperties: false
+                  properties:
+                    visibility:
+                      type: string
+                      enum:
+                      - shared
+                      - private
+                      - pinned
+                      - archived
+                      default: shared
+                    include_agents:
+                      type: boolean
+                      default: true
+                    pinned_budget:
+                      type: integer
+                      default: 10
+                remember:
+                  type: object
+                  additionalProperties: false
+                  description: Topic steering (guidance; hard enforcement stays in
+                    the write path / Presidio).
+                  properties:
+                    never:
+                      type: array
+                      items:
+                        type: string
+                    always:
+                      type: array
+                      items:
+                        type: string
+      allocation:
+        type: object
+        additionalProperties: false
+        description: Engram allocation (dedup/archival) knobs (ex-AllocationPolicy).
+        properties:
+          threshold:
+            type: number
+            default: 0.85
+            description: Overlap >= this proposes archiving the loser (clamped 0.5-1.0).
+          loser_policy:
+            type: string
+            enum:
+            - weaker
+            - newer
+            default: weaker
+            description: Which of two overlapping engrams loses — the weaker
+              (lower strength) or the newer one.
+          overlap_weights:
+            type: object
+            additionalProperties: false
+            description: How overlap [0,1] is scored (sum 1.0).
+            properties:
+              source_refs:
+                type: number
+                default: 0.5
+                description: Jaccard of shared source_refs.
+              area:
+                type: number
+                default: 0.3
+                description: Same area bonus.
+              affect:
+                type: number
+                default: 0.2
+                description: Same affect bonus.
+      pagination:
+        type: object
+        additionalProperties: false
+        description: REST list pagination defaults/caps (ex-PaginationPolicy).
+          Data-plane ownership — read by dna_shared.pagination_policy, not the
+          cognitive engines.
+        properties:
+          default_limit:
+            type: integer
+            default: 50
+            description: Page size when the request omits ?limit=.
+          max_limit:
+            type: integer
+            default: 500
+            description: Hard cap — a larger ?limit= is clamped to this.
+      engram_strength:
+        type: object
+        additionalProperties: false
+        description: Initial-strength rules per engraphy trigger
+          (ex-EngramStrengthPolicy).
+        required:
+        - rules
+        properties:
+          rules:
+            type: array
+            minItems: 1
+            items:
+              type: object
+              additionalProperties: false
+              required:
+              - when
+              - initial_strength
+              properties:
+                when:
+                  type: string
+                  description: Trigger predicate
+                initial_strength:
+                  type: number
+                engraphy_intensity:
+                  type: number
+                  default: 1.0
+          default_decay_rate_per_day:
+            type: number
+            default: 0.02
+          default_decay_threshold_days:
+            type: integer
+            default: 30
+      embedding:
+        type: object
+        additionalProperties: false
+        description: Embedding model + dimension + search weights
+          (ex-EmbeddingProfile). ONLY meaningful on the _lib doc — the embedding
+          space is intrinsically global (stored vectors and every query must
+          share one model+dimension); kernel.embedding_profile reads _lib
+          directly and never a scope override. `recall.calibrated_for` points
+          back here.
+        required:
+        - model
+        - dimensions
+        properties:
+          model:
+            type: string
+            description: Embedding model id (must be served by the LiteLLM proxy).
+          dimensions:
+            type: integer
+            description: Vector dimension. MUST match the pgvector column + every
+              stored embedding — changing it requires a full re-embed.
+          max_input_tokens:
+            type: integer
+            default: 8192
+            description: Input ceiling for a single embed call (model-specific).
+          language:
+            type: string
+            description: Primary language the recall knobs were calibrated against.
+          search_weights:
+            type: object
+            additionalProperties: false
+            description: RRF fusion weights for `cognitive search` (hybrid retrieval).
+            properties:
+              bm25:
+                type: number
+                default: 0.4
+              vector:
+                type: number
+                default: 0.6
+              graph:
+                type: number
+                default: 0.3
+          notes:
+            type: string
+      affect:
+        type: object
+        additionalProperties: false
+        description: Affect vocabulary for the memory/affect engine
+          (ex-AffectPalette). The active palette steers engraphy affect tags.
+        required:
+        - palette
+        properties:
+          palette:
+            type: array
+            minItems: 1
+            items:
+              type: object
+              additionalProperties: false
+              required:
+              - id
+              - semantics
+              properties:
+                id:
+                  type: string
+                semantics:
+                  type: string
+                affect_weight:
+                  type: number
+                  default: 1.0
+                use_when:
+                  type: array
+                  items:
+                    type: string
+                  default: []
+      owner:
+        type: string
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+  summary:
+    owner: ''
+  graph_style:
+    fill: '#F472B6'
+    stroke: '#DB2777'
+    text_color: '#fff'
+  ascii_icon: ⚙️
+  display_label: Política Cognitiva