agentera 0.0.0 → 3.0.0-dev.1

package/bundle/references/cli/routing-execution-vocabulary.yaml

@@ -0,0 +1,281 @@
+schema_version: agentera.routing_execution_vocabulary.v1
+status: active_authority
+purpose: >-
+  Define routing and execution vocabulary boundaries so request routing, next-action
+  recommendation, Orkestrera task assignment, worker launch, runtime support, and
+  worker-safety Git commits stay distinct without forcing mechanical renames of
+  shipped compatibility identifiers or historical evidence.
+sources:
+  prose:
+    - references/cli/vocabulary.md#routing-and-execution-vocabulary
+scope:
+  includes:
+    - Request-to-capability routing through the Agentera skill entry point.
+    - Hej and capability next-action recommendations that wait for confirmation.
+    - Orkestrera assignment of approved plan work to worker capabilities.
+    - Realisera and Optimera launch of runtime workers.
+    - Runtime subagent support mechanisms and compatibility identifiers.
+    - Git commit safety language before spawning isolated worker execution.
+  excludes:
+    - Broad current-prose replacement across capability instructions.
+    - Repository-wide ambiguous dispatcher/dispatch/router/conductor occurrence rejection.
+    - Capability instruction-file rename work.
+    - "`first_invocation_read` metadata or startup-read behavior."
+    - Objective state, decision satisfaction state, package publication, and installed app refreshes.
+compatibility_boundary: >-
+  Compatibility identifiers, code symbols, fixture names, literal paths, archived
+  plans, changelog/progress/decision history, and concrete runtime API names may
+  keep older dispatcher, dispatch, conductor, worktree dispatch, and pre-dispatch
+  wording when the spelling is the contract or historical evidence. New conceptual
+  prose should use the canonical concept terms below.
+canonical_concept_order:
+  - request_to_capability_routing
+  - next_action_recommendation
+  - orkestrera_task_assignment
+  - worker_launch
+  - runtime_subagent_support
+  - worker_safety_git_commit
+canonical_concepts:
+  request_to_capability_routing:
+    definition: >-
+      Agentera chooses the capability that should handle a user request, using
+      direct routes, primary route aliases, trigger schemas, disambiguation, or
+      fallback to hej.
+    preferred_terms:
+      - Agentera router
+      - request-to-capability routing
+      - route
+      - routing
+    forbidden_ambiguous_shortcuts:
+      - master dispatcher
+      - bare dispatch
+      - skill dispatcher
+      - conductor
+  next_action_recommendation:
+    definition: >-
+      A capability recommends a concrete next capability or action and waits for
+      user confirmation before state-changing work begins.
+    preferred_terms:
+      - suggest
+      - suggestion
+      - next-action recommendation
+      - suggested next action
+    forbidden_ambiguous_shortcuts:
+      - dispatch
+      - force
+      - chain
+      - conductor handoff
+  orkestrera_task_assignment:
+    definition: >-
+      Orkestrera assigns approved plan work to a worker capability during an
+      explicitly orchestrated flow; it evaluates the result instead of implementing
+      the task itself.
+    preferred_terms:
+      - delegate
+      - delegation
+      - Orkestrera task delegation
+      - assigned plan work
+    forbidden_ambiguous_shortcuts:
+      - conductor
+      - conductor protocol
+      - dispatch
+      - orchestrator implementation
+  worker_launch:
+    definition: >-
+      Realisera or Optimera starts a worker through the host runtime when an
+      implementation or measurement cycle needs isolated execution.
+    preferred_terms:
+      - spawn
+      - spawn worker
+      - worker spawn
+      - worker launch
+    forbidden_ambiguous_shortcuts:
+      - dispatch
+      - worktree dispatch
+      - subagent dispatch
+      - launch substrate
+  runtime_subagent_support:
+    definition: >-
+      Runtime-specific support that lets Agentera use a host's subagent surface,
+      descriptor model, or equivalent worker mechanism.
+    preferred_terms:
+      - subagent mechanism
+      - runtime subagent mechanism
+      - host subagent mechanism
+      - runtime worker mechanism
+    forbidden_ambiguous_shortcuts:
+      - runtime dispatch substrate
+      - dispatch substrate
+      - subagent dispatch
+      - adapter dispatch
+  worker_safety_git_commit:
+    definition: >-
+      The Git-only commit synchronization required before spawning isolated worker
+      execution so the worker starts from a coherent base.
+    preferred_terms:
+      - pre-spawn Git commit
+      - pre-spawn commit
+      - Git commit before spawning workers
+      - commit before worker spawn
+    forbidden_ambiguous_shortcuts:
+      - pre-dispatch commit
+      - pre-dispatch checkpoint commit
+      - pre-dispatch commit gate
+      - checkpoint before dispatch
+classification_order:
+  - canonical_concept
+  - compatibility_identifier
+  - code_identifier
+  - path_like_reference
+  - historical_record
+  - fixture_only
+  - generic_plain_language
+  - ambiguous_current_prose
+classification_rules:
+  canonical_concept:
+    meaning: Usage matches one of the canonical concepts and uses a preferred term.
+    action: Keep and prefer in new current prose.
+  compatibility_identifier:
+    meaning: The spelling is a shipped field, command flag, runtime group name, descriptor key, or parseable label.
+    action: Preserve until an explicit migration exists.
+  code_identifier:
+    meaning: The spelling is a Python, JavaScript, TOML, YAML, test, or API identifier consumed by code or runtime descriptors.
+    action: Preserve unless a code migration is explicitly in scope.
+  path_like_reference:
+    meaning: The occurrence is a literal file path, glob, manifest path, fixture path, archive path, or code path.
+    action: Preserve the concrete path spelling.
+  historical_record:
+    meaning: The occurrence is in changelog, progress, decision, archived plan, migration history, or release evidence.
+    action: Do not rewrite solely for vocabulary cleanup; qualify when current prose interprets it.
+  fixture_only:
+    meaning: The occurrence is test fixture input, expected compatibility output, stale-path data, or semantic-eval evidence.
+    action: Preserve when the test proves compatibility or rejection behavior.
+  generic_plain_language:
+    meaning: The occurrence is ordinary English unrelated to Agentera routing, recommendation, orchestration assignment, worker launch, runtime support, or Git safety.
+    action: Allowed, but prefer object-specific terms when risk is high.
+  ambiguous_current_prose:
+    meaning: The occurrence uses dispatcher, dispatch, router, conductor, worktree dispatch, runtime dispatch substrate, or pre-dispatch commit language as a conceptual shortcut in current prose.
+    action: Replace or qualify with the relevant canonical concept term.
+focused_scan:
+  allowed_classifications:
+    - canonical
+    - compatibility-preserved
+    - historical
+    - fixture-only
+    - code-identifier
+    - generic
+  paths:
+    - AGENTS.md
+    - references/cli/vocabulary.md
+    - references/adapters/runtime-feature-parity.md
+    - (retired maintainer measurement tool)
+    - skills/agentera/SKILL.md
+    - skills/agentera/references/contract.md
+    - skills/agentera/capabilities/realisera/instructions.md
+    - skills/agentera/capabilities/optimera/instructions.md
+    - skills/agentera/capabilities/orkestrera/instructions.md
+    - tests/test_skill_dispatch_contract.py
+    - tests/test_runtime_adapters.py
+    - tests/test_runtime_adapter_registry.py
+  allowed_occurrences:
+    - path: ^AGENTS\.md$
+      text: Agentera router routes incoming requests
+      classification: canonical
+      reason: AGENTS names the canonical request-to-capability routing term.
+    - path: ^references/cli/vocabulary\.md$
+      text: Agentera router|request-to-capability routing|suggest|delegate|spawn|subagent mechanism|pre-spawn Git commit
+      classification: canonical
+      reason: Vocabulary docs present the canonical routing and execution terms.
+    - path: ^references/cli/vocabulary\.md$
+      text: pre-dispatch commit gate|pre-dispatch checkpoint commit|Conductor protocol|orchestration loop|The loop is select, dispatch, evaluate, resolve, and log
+      classification: historical
+      reason: Decision 44 and glossary tables preserve deprecated wording as historical examples.
+    - path: ^references/cli/vocabulary\.md$
+      text: dispatching cycles|dispatcher rule governs hej and capability handoff prompts
+      classification: canonical
+      reason: Handoff guidance uses dispatch only for the Orkestrera-owned autonomous orchestration flow.
+    - path: ^references/cli/vocabulary\.md$
+      text: subagent_dispatch|fixture names
+      classification: compatibility-preserved
+      reason: Routing vocabulary docs preserve explicit compatibility identifiers and fixture terminology.
+    - path: ^references/adapters/runtime-feature-parity\.md$
+      text: prompt rewrite router|Subagent Dispatch|Dispatch surface|Capability dispatch|subagent dispatch
+      classification: compatibility-preserved
+      reason: Runtime parity docs name concrete host and compatibility surfaces around descriptor dispatch support.
+    - path: ^scripts/measure_token_payload\.py$
+      text: static dispatch payload|Agentera router
+      classification: historical
+      reason: The payload metric retains the historical dispatch-payload measurement name while listing canonical contents.
+    - path: ^skills/agentera/SKILL\.md$
+      text: '`dispatch`: invoke another capability autonomously|`chain`: dispatch multiple capabilities autonomously'
+      classification: canonical
+      reason: Agentera router guidance reserves dispatch and chain for explicitly owned orchestration flows.
+    - path: ^skills/agentera/references/contract\.md$
+      text: '\| hej \| \(router; reads artifacts but produces none\) \|'
+      classification: canonical
+      reason: The contract uses router for the hej request-routing role.
+    - path: ^skills/agentera/references/contract\.md$
+      text: Dispatch the skill via the eval mechanism capability
+      classification: generic
+      reason: Evaluation-gate prose uses dispatch as ordinary test-run invocation wording, not Agentera routing authority.
+    - path: ^skills/agentera/references/contract\.md$
+      text: checkpoint before worktree dispatch
+      classification: compatibility-preserved
+      reason: The contract preserves the parseable historical checkpoint commit message string.
+    - path: ^skills/agentera/capabilities/realisera/instructions\.md$
+      text: 'Step 5: Dispatch|checkpoint before worktree dispatch'
+      classification: compatibility-preserved
+      reason: Realisera preserves the current step heading and checkpoint commit message compatibility string.
+    - path: ^skills/agentera/capabilities/optimera/instructions\.md$
+      text: checkpoint before worktree dispatch
+      classification: compatibility-preserved
+      reason: Optimera preserves the current checkpoint commit message compatibility string.
+    - path: ^skills/agentera/capabilities/orkestrera/instructions\.md$
+      text: review pressure in dispatch|dispatch/evaluation context|`dispatch` and `chain` are autonomous orchestration verbs
+      classification: canonical
+      reason: Orkestrera capability prose uses dispatch for its explicitly owned orchestration loop.
+    - path: ^tests/test_skill_dispatch_contract\.py$
+      text: '`dispatch`: invoke another capability autonomously|`chain`: dispatch multiple capabilities autonomously|In orkestrera only, `dispatch` and `chain` are autonomous'
+      classification: fixture-only
+      reason: Skill dispatch contract tests assert the canonical Orkestrera dispatch reservation.
+    - path: ^tests/test_runtime_adapters\.py$
+      text: opencode bare-hej router|routeBareHejMessage|subagent_dispatch
+      classification: fixture-only
+      reason: Runtime adapter tests assert plugin routing helpers and compatibility identifier fixtures.
+    - path: ^tests/test_runtime_adapter_registry\.py$
+      text: subagent_dispatch
+      classification: code-identifier
+      reason: Runtime adapter registry tests preserve the shipped subagent_dispatch field name.
+compatibility_identifiers:
+  runtime_adapter:
+    - subagent_dispatch
+    - RuntimeAdapter.subagent_dispatch
+    - subagent_dispatch.supported
+    - subagent_dispatch.group
+  route_aliases:
+    - ROUTE_ALIASES
+    - primary_aliases
+  command_and_schema_surfaces:
+    - agentera validate descriptors
+    - descriptor_sources
+    - invocation_pattern
+code_identifiers:
+  - subagent_dispatch
+  - test_runtime_adapter_subagent_dispatch_metadata_is_complete
+  - test_cross_runtime_capability_subagent_dispatch_support
+historical_terms:
+  - pre-dispatch commit
+  - pre-dispatch checkpoint commit
+  - pre-dispatch commit gate
+  - worktree dispatch
+  - runtime dispatch substrate
+  - master dispatcher
+  - conductor protocol
+fixture_terms:
+  - subagent_dispatch fixture
+  - worktree dispatch fixture
+docs_delegation:
+  document: references/cli/vocabulary.md
+  required_anchor: Routing and execution vocabulary
+  authority_path: references/cli/routing-execution-vocabulary.yaml
+  must_not_duplicate_large_table: true

package/bundle/references/cli/update-channels.yaml

@@ -0,0 +1,147 @@
+schema_version: agentera.update_channels.v1
+status: active_authority
+purpose: >-
+  Define dual update channels that select which published Agentera line upgrade,
+  doctor, and prime resolve: stable tracks the supported 2.x line; development
+  tracks 3.x alphas and release candidates.
+sources:
+  prose:
+    - references/cli/vocabulary.md#update-channels
+scope:
+  includes:
+    - Channel names, default selection, and resolution precedence.
+    - npm dist-tag and git ref resolution per channel.
+    - Environment, config, and CLI override keys.
+  excludes:
+    - App lifecycle canonical statuses and operation verb definitions.
+    - Migration orchestration phases, apply semantics, and compatibility detection.
+    - Package publication, dist-tag retirement, and release approval decisions.
+compatibility_boundary: >-
+  Stable channel must continue resolving to 2.x until an explicit release decision
+  retires it. Cross-major v2→v3 migration is never implied by default channel
+  resolution or stable-channel @latest semantics; see
+  references/cli/app-lifecycle-vocabulary.yaml status_concepts.major_boundary_crossing.
+default_channel: stable
+channel_order:
+  - stable
+  - development
+channels:
+  stable:
+    concept: v2_support_line
+    definition: >-
+      Tracks the supported 2.x release line for users who must not cross the v2→v3
+      major boundary without explicit opt-in.
+    distribution_major: 2
+    resolution:
+      npm:
+        dist_tag: latest
+        update_command: npx -y agentera@latest
+      git:
+        ref: main
+        update_command: uvx --from git+https://github.com/jgabor/agentera@main agentera
+  development:
+    concept: v3_pre_release_line
+    definition: >-
+      Tracks 3.x alphas, betas, and release candidates for early adopters and
+      maintainers testing the npm self-contained distribution.
+    distribution_major: 3
+    resolution:
+      npm:
+        dist_tag: next
+        update_command: npx -y agentera@next
+      git:
+        ref: feat/v3
+        update_command: >-
+          uvx --from git+https://github.com/jgabor/agentera@feat/v3 agentera
+override_precedence:
+  - cli_flag
+  - env_var
+  - config_file
+  - default
+override_keys:
+  cli:
+    flag: --channel
+    values:
+      - stable
+      - development
+  env:
+    name: AGENTERA_UPDATE_CHANNEL
+    values:
+      - stable
+      - development
+  config:
+    file: ~/.config/agentera/config.toml
+    key: update.channel
+    values:
+      - stable
+      - development
+consumer_order:
+  - upgrade
+  - doctor
+  - prime
+  - docs
+  - tests
+consumers:
+  upgrade:
+    owns:
+      - channel resolution for preview and apply command rendering.
+      - channel metadata in agentera.upgrade.v2 payloads.
+    may_resolve_channels:
+      - stable
+      - development
+  doctor:
+    owns:
+      - channel-aware repair and update command strings in diagnostics.
+    may_resolve_channels:
+      - stable
+      - development
+  prime:
+    owns:
+      - channel-aware v1 migration and app-home gate command strings.
+    may_resolve_channels:
+      - stable
+      - development
+  docs:
+    owns:
+      - human-readable explanation of this authority.
+    may_resolve_channels:
+      - stable
+      - development
+  tests:
+    owns:
+      - regression coverage proving consumers remain synchronized with this authority.
+    may_resolve_channels:
+      - stable
+      - development
+version_resolution:
+  running_version:
+    priority:
+      - bundle_marker
+      - npm_package_version
+      - suite_registry
+  latest_on_channel:
+    resolver: npm_dist_tag_with_offline_defaults
+    offline_defaults:
+      stable: "2.7.6"
+      development: "3.0.0-dev.1"
+  irreversibility:
+    downgrade_to_v2: permanently_blocked
+    supported_downgrade_lines: []
+  forward_major_gate:
+    mechanism: semver_compare_running_to_latest_on_selected_channel
+    apply_requires:
+      - dry_run_preview
+      - yes_flag
+  outcome_concepts:
+    - same_major_update
+    - forward_major_upgrade
+    - migration_to_latest_on_channel
+    - channel_line_mismatch
+    - blocked_downgrade_to_v2
+    - blocked_downgrade_not_implemented
+    - up_to_date
+docs_delegation:
+  document: references/cli/vocabulary.md
+  required_anchor: Update channels
+  authority_path: references/cli/update-channels.yaml
+  must_not_duplicate_large_table: true

package/bundle/references/cli/vocabulary-index.yaml

@@ -0,0 +1,160 @@
+schema_version: agentera.vocabulary_index.v1
+status: active_authority
+purpose: >-
+  Machine-readable vocabulary index: authority order, normalization rules, and
+  Decision 44 replacement boundaries. Human prose index lives in
+  references/cli/vocabulary.md, which delegates here for enforced tables.
+human_index:
+  document: references/cli/vocabulary.md
+  must_not_duplicate_large_tables: true
+authority_order:
+  - skills/agentera/protocol.yaml
+  - skills/agentera/capability_schema_contract.yaml
+  - skills/agentera/schemas/artifacts/
+  - references/artifacts/artifact-registry-interface-model.yaml
+  - references/cli/app-lifecycle-vocabulary.yaml
+  - references/cli/update-channels.yaml
+  - references/cli/bundle-skill-vocabulary.yaml
+  - references/cli/capability-instruction-contract.yaml
+  - references/cli/routing-execution-vocabulary.yaml
+  - skills/agentera/SKILL.md
+  - skills/agentera/capabilities/*/instructions.md
+  - the agentera CLI
+  - packages/cli/src/upgrade (doctor/upgrade)
+  - README.md
+  - UPGRADE.md
+  - DESIGN.md
+  - .agentera/
+normalization_rules:
+  - rule: Internal workflows are capabilities.
+    use: capability, twelve capabilities, capability prose, capability schemas
+    avoid: Calling hej/realisera/etc. standalone skills, except in v1 history.
+  - rule: The runtime surface is a skill.
+    use: Agentera skill, single installed Agentera app
+    avoid: twelve-skill suite for v2 behavior.
+  - rule: /agentera is the main invocation.
+    use: /agentera, $agentera for Codex-specific docs
+    avoid: /hej except as a legacy bridge.
+  - rule: The CLI source and rendered dashboard are different.
+    use: agentera hej source data, Hej dashboard rendered briefing
+    avoid: Treating raw CLI labels as the user-facing dashboard.
+  - rule: Routine state uses flat commands.
+    use: agentera plan, agentera docs, agentera health
+    avoid: agentera query plan for routine state.
+  - rule: query is advanced access.
+    use: agentera query --list-artifacts, agentera query <artifact>
+    avoid: Calling it the normal state interface.
+  - rule: Canonical artifact names are identifiers.
+    use: VISION.md maps to .agentera/vision.yaml
+    avoid: Assuming display names are literal paths.
+  - rule: Exit signals are fixed.
+    use: complete, flagged, stuck, waiting
+    avoid: blocked, partial, escalated as exit signals.
+  - rule: Current-state language names the object.
+    use: Agentera app files need repair, artifacts are current, plan-level current-state check
+    avoid: Bare freshness in new docs.
+  - rule: App lifecycle state is canonical metadata.
+    use: up_to_date, outdated, repair_needed, migration_needed, manual_review_needed, ready_to_apply, applied, no_changes_needed
+    avoid: fresh, stale, refresh, fixed, ready, or noop as app lifecycle status values.
+  - rule: Update channel selects the published line.
+    use: stable channel, development channel, AGENTERA_UPDATE_CHANNEL, --channel stable|development
+    avoid: Treating @latest or default upgrade as implicit v2→v3 migration.
+  - rule: Worker safety commits are Git-only.
+    use: pre-spawn Git commit
+    avoid: Non-Git checkpoint or pre-dispatch commit gate in new docs.
+  - rule: Capability instruction files have current metadata and a runtime boundary.
+    use: instructions.md plus emitted first_invocation_read; runtime enforcement remains false
+    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera planera commands.
+plain_language:
+  lead_with_plain_phrase:
+    - use: final state sync, the plan-level freshness checkpoint
+      avoid: Bare freshness checkpoint
+    - use: Agentera app files need repair
+      avoid: bundle freshness gap in user-facing diagnostics
+    - use: v1 migration check
+      avoid: Bare upgrade guard in onboarding or recovery text
+    - use: checkpoint commit
+      avoid: Bare checkpoint
+  layers:
+    - layer: Product identity
+      rule: Branded, memorable, and opinionated.
+    - layer: Protocol internals
+      rule: Precise, canonical, and schema-aligned.
+    - layer: User operations
+      rule: Plain, traditional, and searchable.
+    - layer: Diagnostics and errors
+      rule: Object, state, cause, fix.
+    - layer: Onboarding
+      rule: Plain phrase first, Agentera term second.
+decision_44:
+  summary: >-
+    Source of truth for Decision 44 wording changes. Stable identifiers, enums,
+    persisted state shapes, routing semantics, CLI exit behavior, canonical
+    Swedish capability names, and Decision 43 aliases are protected compatibility
+    surfaces unless a later decision records migration.
+  deprecated_scan_pattern: >-
+    freshness|\\bcheckpoint\\b|\\bguard\\b|Reality Verification Gate|
+    conductor protocol|memory layer|operating record|\\bdrift\\b|drifts|
+    drifted|drifting|DTC-first|\\bDTC\\b
+  replacements:
+    - deprecated: freshness as a general protocol label
+      preferred: current, up to date, out of date, synced, status, needs sync
+      rationale: Plain state words are clearer and avoid turning several conditions into one branded abstraction.
+    - deprecated: freshness checkpoint, plan-level freshness checkpoint
+      preferred: final state sync, plan-level current-state check
+      rationale: Plan closure updates durable state; it is not a Git checkpoint or a special freshness concept.
+    - deprecated: Non-Git checkpoint
+      preferred: state sync, current-state check, milestone, or the specific action
+      rationale: checkpoint remains Git-only so commit synchronization is unambiguous.
+    - deprecated: Most guard wording
+      preferred: check, status check, stop condition, safety rule, or pre-routing check
+      rationale: The replacement says what happens instead of using security-flavored jargon.
+    - deprecated: Reality Verification Gate
+      preferred: behavioral verification gate
+      rationale: Keep gate only for hard pass/fail verification boundaries, and name the behavior being verified.
+    - deprecated: Conductor protocol
+      preferred: orchestration loop
+      rationale: The loop is select, dispatch, evaluate, resolve, and log; the plain phrase explains the action.
+    - deprecated: memory layer
+      preferred: saved project context
+      rationale: Agentera persists context in project files and profile data, not model memory.
+    - deprecated: operating record
+      preferred: saved project context, project history, or progress log
+      rationale: The replacement states the artifact role directly.
+    - deprecated: Prose/label drift
+      preferred: mismatch, out of sync, or the concrete mismatch type
+      rationale: drift is vague in user-facing vocabulary; mismatch wording states the observable problem.
+    - deprecated: DTC, DTC-first
+      preferred: docs-first workflow, document intended behavior before tests and code
+      rationale: Keep the working principle while removing acronym friction.
+  allowed_uses:
+    - term: checkpoint
+      allowed: Git commits only, such as checkpoint commit or pre-dispatch checkpoint commit.
+      rationale: Git users understand checkpoint as commit synchronization; non-Git lifecycle use is deprecated.
+    - term: gate
+      allowed: Hard pass/fail boundaries, especially behavioral verification gate or regression pass/fail decisions.
+      rationale: Gate remains useful when a failed check must stop the workflow.
+    - term: guard
+      allowed: Existing code identifiers, historical text, or conventional phrases where changing the word would imply behavior or API migration.
+      rationale: Compatibility and searchability can outweigh prose cleanup in stable surfaces.
+    - term: drift
+      allowed: Historical entries, test fixture names, version-drift/package-drift diagnostics, and deliberate compatibility labels where drift is already a stable concept.
+      rationale: Some existing diagnostics and tests use drift as a compatibility signal.
+    - term: fresh, stale, fresh project
+      allowed: Plain English state descriptions when they are natural user wording, especially fresh project versus returning project.
+      rationale: Decision 44 deprecates freshness as protocol jargon, not ordinary adjectives.
+  protected_surfaces:
+    - surface: Schema fields and artifact shapes
+      boundary: Preserve field names, enum values, YAML structures, and validation semantics.
+    - surface: Stable IDs
+      boundary: Preserve capability IDs, artifact IDs, group IDs, route IDs, and test fixture IDs unless a migration is planned.
+    - surface: CLI labels and exit behavior
+      boundary: Preserve current command names, parseable labels, exit codes, and source-contract labels unless an explicit CLI migration is recorded.
+    - surface: Canonical capability names
+      boundary: Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera.
+    - surface: Decision 43 aliases
+      boundary: Preserve /agentera status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, and orchestrate.
+    - surface: Historical artifacts
+      boundary: Do not rewrite old progress, changelog, archived plans, or decisions solely for vocabulary cleanup.
+    - surface: Release version
+      boundary: Keep Decision 44 under pending 2.2.0; do not create a later version for this cleanup without policy-driven rationale.