agentera 0.0.0 → 3.0.0-dev.0

package/bundle/skills/agentera/schemas/artifacts/changelog.yaml

@@ -0,0 +1,60 @@
+# Changelog Artifact Schema
+#
+# Release history maintained by realisera. Tracks versioned releases with
+# categorized changes (Added, Changed, Fixed, Removed).
+#
+# Note: CHANGELOG.md is a human-facing Markdown artifact. It remains at the
+# project root and is not migrated to YAML. This schema exists for validation
+# and CLI discovery consistency.
+
+meta:
+  name: changelog
+  version: "1.0.0"
+  description: >-
+    Release history. Produced by realisera. Consumed by users and agents
+    for version context. Human-facing: remains Markdown at project root.
+  artifact_type: human_facing
+  path: "CHANGELOG.md"
+  producer: realisera
+  consumers: [hej, all_skills]
+  format: markdown
+
+GROUP_PREFIXES:
+  BUDGET: CB
+  RELEASE: CR
+  VALIDATION: CV
+
+BUDGET:
+  1:
+    id: CB1
+    token_budget: 5000
+    description: >-
+      Maximum tokens for CHANGELOG.md content. Exceeding triggers compaction.
+
+RELEASE:
+  1:
+    id: CR1
+    field: version
+    type: string
+    required: true
+    description: >-
+      Semantic version string (e.g., "2.0.0"). Must follow semver.
+    validation:
+      - "Must match semver format: MAJOR.MINOR.PATCH"
+  2:
+    id: CR2
+    field: date
+    type: string
+    required: true
+    description: >-
+      Release date in YYYY-MM-DD format.
+    validation:
+      - "Must match YYYY-MM-DD format"
+  3:
+    id: CR3
+    field: changes
+    type: list[string]
+    required: true
+    description: >-
+      List of changes in this release, categorized by type
+      (Added, Changed, Fixed, Removed).

package/bundle/skills/agentera/schemas/artifacts/decisions.yaml

@@ -0,0 +1,461 @@
+# Decisions Artifact Schema
+#
+# Reasoning trail maintained by resonera. Each deliberation session appends
+# one entry. Decisions are referenced by realisera, optimera, and profilera
+# for context on why choices were made.
+#
+# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
+# following capability_schema_contract.yaml and protocol.yaml conventions.
+#
+# ── Field-by-field mapping: v1 DECISIONS.md → v2 decisions.yaml ──
+#
+# v1 Field                              v2 Field               v2 ID
+# ─────────────────────────────────────────────────────────────────────
+# ## Decision N · date                  DECISION.number        DC1
+# (date from heading)                   DECISION.date          DC2
+# **Question**: <text>                  DECISION.question      DC3
+# **Context**: <text>                   DECISION.context       DC4
+# **Alternatives**: (list)              ALTERNATIVE entry      DA1
+# (named alt, e.g. "[Foo], chosen")     ALTERNATIVE.name       DA2
+# (chosen/rejected status)              ALTERNATIVE.status     DA3
+# **Choice**: <text>                    DECISION.choice        DC5
+# **Reasoning**: <text>                 DECISION.reasoning     DC6
+# **Confidence**: <label>               DECISION.confidence    DC7
+# **Feeds into**: <text>               DECISION.feeds_into     DC8
+# ## Archived Decisions                 (implicit section)     —
+# - Decision N (date): [Choice] — ...  ARCHIVE.summary        DR1
+#
+# Protocol references:
+#   confidence: DL1-DL3 (protocol.yaml DECISION_LABELS)
+
+meta:
+  name: decisions
+  version: "1.0.0"
+  description: >-
+    Reasoning trail maintained by resonera. Each deliberation session
+    appends one entry. Decisions are referenced by realisera, optimera,
+    profilera, planera, inspektera, hej, dokumentera, visionera, resonera,
+    and orkestrera for context on why choices were made.
+  artifact_type: agent_facing
+  path: ".agentera/decisions.yaml"
+  producer: resonera
+  consumers: [dokumentera, hej, inspektera, optimera, orkestrera, planera, profilera, realisera, resonera, visionera]
+  format: yaml
+
+GROUP_PREFIXES:
+  BUDGET: DB
+  COMPACTION: DX
+  DECISION: DC
+  ALTERNATIVE: DA
+  SATISFACTION: DS
+  ARCHIVE: DR
+  VALIDATION: DV
+
+BUDGET:
+  1:
+    id: DB1
+    scope: per_decision_entry
+    max_words: 200
+    description: >-
+      Maximum words per decision entry. Budgets are guidelines, not hard
+      blockers.
+  2:
+    id: DB2
+    scope: full_file
+    max_words: null
+    description: >-
+      No full-file word budget. Compaction manages size via entry count.
+
+COMPACTION:
+  1:
+    id: DX1
+    rule: uniform_10_40_50
+    description: >-
+      Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
+      entries, 40 one-line archive entries, drop beyond 50 total.
+  2:
+    id: DX2
+    full_detail:
+      max_entries: 10
+      selection: "10 most recent decisions"
+      format: "Standard decision entry format (all fields)"
+    description: >-
+      The 10 most recent decisions are kept in full detail with all fields.
+  3:
+    id: DX3
+    one_line_archive:
+      max_entries: 40
+      selection: "Decisions 11 through 50"
+      format: "Decision N (YYYY-MM-DD): [Choice] — <=15-word summary"
+      fields: [number, date, choice, summary]
+    description: >-
+      Decisions 11 through 50 are collapsed to compact archive entries under
+      the archive section. Compact summaries preserve decision number, date,
+      and chosen alternative; structured compact fields preserve outcome and
+      explicit feeds_into references when present so CLI downstream references
+      remain non-inferential.
+  4:
+    id: DX4
+    dropped:
+      threshold: 50
+      action: "Removed entirely"
+    description: >-
+      Decisions older than 50 are dropped entirely.
+  5:
+    id: DX5
+    trigger: "When resonera writes a new decision"
+    description: >-
+      Compaction runs when the producing skill writes a new entry.
+      If >10 full-detail entries exist, collapse the oldest to one-line.
+      If >40 one-line entries exist, drop the oldest.
+  6:
+    id: DX6
+    archive_section:
+      heading: "Archived Decisions"
+      placement: "Below recent decisions"
+    description: >-
+      Archive entries sit below the recent decisions section.
+  7:
+    id: DX7
+    insertion_rule: >-
+      New full entry is inserted in the active section immediately before
+      the archive section; if no archive exists, append at end of file.
+      Active entries must have unique numbers and remain ascending.
+      Do not reuse or renumber except when repairing artifact corruption.
+    description: >-
+      Rules for inserting new decision entries and maintaining order.
+
+DECISION:
+  1:
+    id: DC1
+    field: number
+    type: integer
+    required: true
+    description: >-
+      Monotonically increasing decision number. One greater than the
+      highest decision number in active and archived entries.
+    validation:
+      - "Must be a positive integer"
+      - "Must be unique across active and archived entries"
+      - "Must be one greater than the previous highest"
+  2:
+    id: DC2
+    field: date
+    type: string
+    format: "YYYY-MM-DD"
+    required: true
+    description: "When the decision was recorded."
+    validation:
+      - "Must match YYYY-MM-DD format"
+  3:
+    id: DC3
+    field: question
+    type: string
+    required: true
+    description: >-
+      The question or decision being made. Phrased as a question that
+      the decision answers.
+    validation:
+      - "Non-empty string"
+  4:
+    id: DC4
+    field: context
+    type: string
+    required: true
+    description: >-
+      Background information framing the decision. Why this question
+      matters, what constraints exist, what prior decisions are relevant.
+    validation:
+      - "Non-empty string"
+  5:
+    id: DC5
+    field: choice
+    type: string
+    required: true
+    description: >-
+      The chosen alternative, with explanation of what was chosen and why
+      it is the right answer in context.
+    validation:
+      - "Non-empty string"
+  6:
+    id: DC6
+    field: reasoning
+    type: string
+    required: true
+    description: >-
+      Why this choice was made over the alternatives. The deliberative
+      reasoning trail that justifies the decision.
+    validation:
+      - "Non-empty string"
+  7:
+    id: DC7
+    field: confidence
+    type: string
+    required: true
+    description: >-
+      Decision confidence label. References protocol.yaml DECISION_LABELS
+      (DL1-DL3). Firm = committed, provisional = best current answer,
+      exploratory = direction to try.
+    protocol_ref: DECISION_LABELS
+    validation:
+      - "Must be one of: firm, provisional, exploratory"
+  8:
+    id: DC8
+    field: feeds_into
+    type: string
+    required: false
+    description: >-
+      What artifacts, skills, or work items this decision affects.
+      Downstream consumers that should be aware of this choice.
+  9:
+    id: DC9
+    field: satisfaction
+    type: map
+    required: false
+    description: >-
+      First-class satisfaction state for this decision. Missing satisfaction is
+      valid legacy data, but consumers must derive review_needed=true rather
+      than treating the decision as satisfied.
+
+SATISFACTION:
+  1:
+    id: DS1
+    field: state
+    parent: DECISION.satisfaction
+    type: string
+    required: true
+    description: >-
+      Canonical satisfaction state. This is the only satisfaction state field;
+      review_needed is derived from missing or stale protected state, not stored
+      as a fourth state.
+    validation:
+      - "Must be one of: open, provisionally_satisfied, user_confirmed_satisfied"
+  2:
+    id: DS2
+    field: evidence
+    parent: DECISION.satisfaction
+    type: string
+    required: false
+    description: >-
+      Evidence that an agent may attach when state is provisionally_satisfied.
+      Provisional satisfaction requires non-empty evidence that cites concrete
+      implemented behavior, tests, artifacts, or user-visible outcomes.
+  3:
+    id: DS3
+    field: user_confirmation
+    parent: DECISION.satisfaction
+    type: map
+    required: false
+    description: >-
+      Explicit user authority metadata required when state is
+      user_confirmed_satisfied. Agents must not create this state unless the
+      current user directly confirms the decision is satisfied.
+    children:
+      - field: confirmed_by
+        type: string
+        required: true
+      - field: confirmed_at
+        type: string
+        required: true
+
+ALTERNATIVE:
+  1:
+    id: DA1
+    field: entry
+    type: map
+    required: true
+    description: >-
+      Each alternative is a structured entry within the decision's
+      alternatives list. At least one alternative must be present.
+    min_count: 1
+  2:
+    id: DA2
+    field: name
+    parent: ALTERNATIVE.entry
+    type: string
+    required: true
+    description: >-
+      Short name or bracketed label for this alternative
+      (e.g., '[Suite bundle first]').
+    validation:
+      - "Non-empty string"
+  3:
+    id: DA3
+    field: status
+    parent: ALTERNATIVE.entry
+    type: string
+    required: true
+    description: >-
+      Whether this alternative was chosen or rejected.
+      Exactly one alternative in each decision must be 'chosen'.
+    validation:
+      - "Must be one of: chosen, rejected"
+  4:
+    id: DA4
+    field: description
+    parent: ALTERNATIVE.entry
+    type: string
+    required: false
+    description: >-
+      Brief explanation of the alternative. May be omitted when the
+      name is self-explanatory.
+
+ARCHIVE:
+  1:
+    id: DR1
+    field: summary
+    type: string
+    required: true
+    description: >-
+      Summary for a compacted decision. Format:
+      'Decision N (YYYY-MM-DD): [Choice] — <=15-word summary'.
+      Preserves decision number, date, and chosen alternative.
+    validation:
+      - "Must include decision number"
+      - "Must include date in YYYY-MM-DD format"
+      - "Must include chosen alternative"
+      - "Summary portion must be <=15 words"
+  2:
+    id: DR2
+    field: number
+    type: integer
+    required: false
+    description: >-
+      Decision number retained when a full decision is compacted. Legacy
+      compacted entries may expose the number only inside summary.
+  3:
+    id: DR3
+    field: date
+    type: string
+    format: "YYYY-MM-DD"
+    required: false
+    description: >-
+      Decision date retained when a full decision is compacted. Legacy
+      compacted entries may expose the date only inside summary.
+  4:
+    id: DR4
+    field: choice
+    type: string
+    required: false
+    description: >-
+      Chosen alternative retained when a full decision is compacted. This is
+      the source for compacted CLI outcome when present.
+  5:
+    id: DR5
+    field: outcome
+    type: string
+    required: false
+    description: >-
+      Outcome retained for structured consumers of compacted decisions. When
+      omitted by legacy entries, CLI output marks outcome missing instead of
+      requiring raw artifact or git-history fallback.
+  6:
+    id: DR6
+    field: feeds_into
+    type: string
+    required: false
+    description: >-
+      Explicit downstream references retained from the full decision when
+      present. Consumers must not infer downstream consequences when absent.
+  7:
+    id: DR7
+    field: satisfaction
+    type: map
+    required: false
+    description: >-
+      Satisfaction state retained when a confirmed full decision is compacted.
+      Legacy compacted entries may omit this field; such entries are valid but
+      review-needed, and compaction must not silently drop them.
+
+VALIDATION:
+  1:
+    id: DV1
+    rule: unique_decision_numbers
+    severity: error
+    description: >-
+      Active decision entries must have unique numbers and remain ascending
+      by decision number. Do not reuse or renumber except when repairing
+      artifact corruption.
+    checks:
+      - "All decision numbers are unique across active and archived entries"
+      - "Active entries are in ascending order by decision number"
+  2:
+    id: DV2
+    rule: required_fields
+    severity: error
+    description: >-
+      Each full-detail decision entry must have: number, date, question,
+      context, alternatives, choice, reasoning, and confidence.
+    checks:
+      - "number is present and is a positive integer"
+      - "date is present and matches YYYY-MM-DD"
+      - "question is present and non-empty"
+      - "context is present and non-empty"
+      - "alternatives list is present with at least one entry"
+      - "choice is present and non-empty"
+      - "reasoning is present and non-empty"
+      - "confidence is present and is a valid label"
+  3:
+    id: DV3
+    rule: exactly_one_chosen
+    severity: error
+    description: >-
+      Exactly one alternative in each decision must have status 'chosen'.
+    checks:
+      - "Each decision has exactly one alternative with status: chosen"
+  4:
+    id: DV4
+    rule: compaction_thresholds
+    severity: warning
+    description: >-
+      Warn if the file exceeds compaction thresholds: >10 full-detail
+      entries or >40 one-line archive entries.
+    checks:
+      - "Full-detail entries <= 10"
+      - "One-line archive entries <= 40"
+      - "Total entries <= 50"
+  5:
+    id: DV5
+    rule: word_budget
+    severity: advisory
+    description: >-
+      Advisory check. Per-decision entry should be <=200 words.
+    checks:
+      - "Per-decision word count <= 200"
+  6:
+    id: DV6
+    rule: satisfaction_contract
+    severity: error
+    description: >-
+      Satisfaction, when present, must use the canonical state model. Agents
+      may mark provisional satisfaction only with evidence. User-confirmed
+      satisfaction requires explicit user-confirmation metadata.
+    checks:
+      - "satisfaction.state is one of: open, provisionally_satisfied, user_confirmed_satisfied"
+      - "provisionally_satisfied requires non-empty satisfaction.evidence"
+      - "user_confirmed_satisfied requires satisfaction.user_confirmation.confirmed_by and confirmed_at"
+  7:
+    id: DV7
+    rule: legacy_review_needed
+    severity: advisory
+    description: >-
+      Active or archived legacy decisions without satisfaction remain valid but
+      consumers must derive review_needed=true rather than silently treating
+      them as satisfied.
+    checks:
+      - "missing satisfaction is valid legacy data"
+      - "missing satisfaction derives review_needed=true"
+  8:
+    id: DV8
+    rule: stale_review_trigger
+    severity: warning
+    description: >-
+      Open, provisionally satisfied, or legacy review-needed decisions are
+      protected from compaction/drop. If such decisions exceed compaction
+      budgets, or are encountered during health audits or release closeout,
+      user review is required before treating the state as healthy or
+      release-ready.
+    checks:
+      - "open decisions are protected"
+      - "provisionally_satisfied decisions are protected"
+      - "legacy missing satisfaction is protected until reviewed"

package/bundle/skills/agentera/schemas/artifacts/design.yaml

@@ -0,0 +1,55 @@
+# Design Artifact Schema
+#
+# Visual identity system maintained by visualisera. Defines design tokens,
+# palette, typography, spacing, and component styling rules.
+#
+# Note: DESIGN.md is a human-facing Markdown artifact. It remains at the
+# project root and is not migrated to YAML. This schema exists for validation
+# and CLI discovery consistency.
+
+meta:
+  name: design
+  version: "1.0.0"
+  description: >-
+    Visual identity system. Produced by visualisera. Consumed by capabilities
+    that need visual identity context. Human-facing: remains Markdown at root.
+  artifact_type: human_facing
+  path: "DESIGN.md"
+  producer: visualisera
+  consumers: [dokumentera, hej, inspektera, realisera, visionera, visualisera]
+  format: markdown
+
+GROUP_PREFIXES:
+  BUDGET: DB
+  TOKEN: DT
+  VALIDATION: DV
+
+BUDGET:
+  1:
+    id: DB1
+    token_budget: 2000
+    description: >-
+      Maximum tokens for DESIGN.md content. Exceeding triggers compaction.
+
+TOKEN:
+  1:
+    id: DT1
+    field: category
+    type: string
+    required: true
+    description: >-
+      Token category: palette, typography, spacing, component, or animation.
+  2:
+    id: DT2
+    field: name
+    type: string
+    required: true
+    description: >-
+      Token name (e.g., "primary", "body-text", "gap-md").
+  3:
+    id: DT3
+    field: value
+    type: string
+    required: true
+    description: >-
+      Token value (e.g., hex color, font stack, spacing unit).