agentera 0.0.0 → 3.0.0-dev.0

package/bundle/references/cli/app-lifecycle-vocabulary.yaml

@@ -0,0 +1,233 @@
+schema_version: agentera.app_lifecycle_vocabulary.v1
+status: active_authority
+decision: 54
+purpose: >-
+  Define the app lifecycle vocabulary shared by doctor, hej, upgrade, docs,
+  and tests so structured status metadata, operation verbs, deprecated aliases,
+  and consumer ownership boundaries have one machine-readable source.
+sources:
+  decisions:
+    - .agentera/decisions.yaml#Decision-54
+  prose:
+    - references/cli/vocabulary.md#app-lifecycle-status-vocabulary
+scope:
+  includes:
+    - Agentera app lifecycle status metadata emitted by doctor, hej, and upgrade.
+    - Upgrade workflow operation verbs for app files, data migration, and no-change outcomes.
+    - Cross-major status concepts that annotate migration work without adding parallel status enums.
+    - Transitional deprecated aliases needed to classify shipped or historical consumers.
+  excludes:
+    - Capability names.
+    - Artifact names or paths.
+    - Exit signals.
+    - Task statuses.
+    - Health grades.
+    - Update channel names, dist-tag resolution, and override keys.
+    - General prose outside app lifecycle metadata.
+compatibility_boundary: >-
+  Compatibility identifiers such as `.agentera-bundle.json`, `bundle.status`,
+  `activeBundleRoot`, and `--only bundle` may remain until an explicit migration
+  exists. They do not make bundle/fresh/stale/refresh/fixed canonical app
+  lifecycle status vocabulary.
+canonical_status_order:
+  - up_to_date
+  - outdated
+  - repair_needed
+  - migration_needed
+  - manual_review_needed
+  - ready_to_apply
+  - applied
+  - no_changes_needed
+canonical_statuses:
+  up_to_date:
+    concept: installed_app_current
+    definition: Installed app matches the expected version and required commands are present.
+    deprecated_aliases:
+      - fresh
+      - current
+      - ready
+      - ok
+  outdated:
+    concept: installed_app_version_behind
+    definition: Installed app files are valid but older than the expected version.
+    deprecated_aliases:
+      - stale
+      - old
+      - update_needed
+  repair_needed:
+    concept: app_files_missing_incomplete_or_broken
+    definition: App files are missing, incomplete, or broken.
+    deprecated_aliases:
+      - refresh_required
+      - broken
+      - invalid
+      - app_refresh_required
+  migration_needed:
+    concept: compatibility_boundary_migration_required
+    definition: v1 project state or legacy app-home layout needs migration.
+    deprecated_aliases:
+      - upgrade_needed
+      - stale_v1
+  manual_review_needed:
+    concept: unsafe_to_choose_write_path_automatically
+    definition: Agentera cannot safely choose a write path without the user.
+    deprecated_aliases:
+      - blocked
+      - needs decision
+  ready_to_apply:
+    concept: dry_run_has_approved_safe_pending_work
+    definition: A no-write plan has pending approved-safe work.
+    deprecated_aliases:
+      - pending
+      - ready to fix
+  applied:
+    concept: approved_work_completed
+    definition: Approved work completed.
+    deprecated_aliases:
+      - fixed
+  no_changes_needed:
+    concept: idempotent_no_write_required
+    definition: No write is needed.
+    deprecated_aliases:
+      - noop
+      - already OK
+status_concept_order:
+  - major_boundary_crossing
+status_concepts:
+  major_boundary_crossing:
+    definition: >-
+      Work that crosses the v2→v3 compatibility boundary (Python managed app-home
+      to npm self-contained 3.x). Never implied by stable-channel resolution or
+      @latest; requires explicit --target-major 3 opt-in before apply.
+    applies_to_verbs:
+      - migrate
+      - upgrade
+    typical_statuses:
+      - manual_review_needed
+      - migration_needed
+    requires_explicit_opt_in:
+      flag: --target-major
+      value: 3
+    item_tag: requires_explicit_major_opt_in
+    never_implicit_on_channels:
+      - stable
+    authority_cross_ref: references/cli/update-channels.yaml
+operation_verb_order:
+  - install
+  - repair
+  - update
+  - migrate
+  - upgrade
+  - refresh
+operation_verbs:
+  install:
+    scope: Put Agentera app files where they do not exist.
+    lifecycle_allowed: true
+  repair:
+    scope: Restore missing, incomplete, or broken Agentera app files.
+    lifecycle_allowed: true
+  update:
+    scope: >-
+      Move existing Agentera app files from an older version to the expected version
+      within the selected update channel's distribution major. Stable channel updates
+      stay on the 2.x line; development channel updates track 3.x pre-releases.
+      Cross-major v2→v3 moves are migrate work tagged major_boundary_crossing, not
+      channel updates.
+    lifecycle_allowed: true
+    channel_aware: true
+    authority_cross_ref: references/cli/update-channels.yaml
+  migrate:
+    scope: Change layout, data, or schema across a compatibility boundary.
+    lifecycle_allowed: true
+  upgrade:
+    scope: Umbrella CLI workflow that may install, repair, update, migrate, configure, or clean up.
+    lifecycle_allowed: true
+  refresh:
+    scope: Data regeneration only, such as `agentera stats refresh`; not app lifecycle state.
+    lifecycle_allowed: false
+consumer_order:
+  - doctor
+  - hej
+  - upgrade
+  - docs
+  - tests
+consumers:
+  doctor:
+    owns:
+      - structured app self-check status metadata.
+      - human-readable app lifecycle diagnostics derived from canonical status metadata.
+    may_emit_statuses:
+      - up_to_date
+      - outdated
+      - repair_needed
+      - migration_needed
+      - manual_review_needed
+    may_use_verbs:
+      - repair
+      - update
+      - migrate
+      - upgrade
+    may_define_new_statuses: false
+  hej:
+    owns:
+      - installed app gate summary exposed in the composite state briefing.
+      - recovery prompts derived from doctor and upgrade metadata.
+    may_emit_statuses:
+      - up_to_date
+      - outdated
+      - repair_needed
+      - migration_needed
+      - manual_review_needed
+    may_use_verbs:
+      - repair
+      - update
+      - migrate
+      - upgrade
+    may_define_new_statuses: false
+  upgrade:
+    owns:
+      - app lifecycle preview and apply workflow metadata.
+      - concrete operation item naming for install, repair, update, migrate, cleanup, and no-change outcomes.
+    may_emit_statuses:
+      - ready_to_apply
+      - applied
+      - no_changes_needed
+      - manual_review_needed
+    may_use_verbs:
+      - install
+      - repair
+      - update
+      - migrate
+      - upgrade
+    may_define_new_statuses: false
+  docs:
+    owns:
+      - human-readable explanation of this authority.
+      - plain-language recovery wording boundaries.
+    may_emit_statuses: []
+    may_use_verbs:
+      - install
+      - repair
+      - update
+      - migrate
+      - upgrade
+      - refresh
+    may_define_new_statuses: false
+  tests:
+    owns:
+      - regression coverage proving consumers remain synchronized with this authority.
+      - deprecated alias classification and rejection as canonical status values.
+    may_emit_statuses: []
+    may_use_verbs:
+      - install
+      - repair
+      - update
+      - migrate
+      - upgrade
+      - refresh
+    may_define_new_statuses: false
+docs_delegation:
+  document: references/cli/vocabulary.md
+  required_anchor: App lifecycle status vocabulary
+  authority_path: references/cli/app-lifecycle-vocabulary.yaml
+  must_not_duplicate_large_table: true

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -0,0 +1,355 @@
+schema_version: agentera.audience_namespace_cli_migration.v1
+status: target_design_contract
+purpose: >-
+  Target CLI command tree, audience namespace grouping, and phased alias migration
+  policy for the Run 2 hybrid CLI consolidation. Documents the post-migration surface
+  before parser and dispatch changes land in plan tasks 2–4.
+sources:
+  decisions:
+    - .agentera/decisions.yaml#Decision-45
+    - .agentera/decisions.yaml#Decision-59
+    - .agentera/decisions.yaml#Decision-43
+  parent_contract: references/cli/agent-ready-state-contract.yaml
+  active_plan: .agentera/plan.yaml
+  implementation_entrypoint: the agentera CLI
+implementation_status: design_only
+non_goals:
+  - Do not implement parser, dispatch, or help-grouping changes in this contract task.
+  - Do not remove top-level aliases until the phased migration completes.
+  - Do not add capability workflow execution commands such as `agentera planera`.
+  - Do not expose top-level `agentera corpus`; corpus generation stays behind
+    `report refresh --consent local-history`.
+target_surface_summary: >-
+  Reduce the flat ~33 top-level verbs to ~18 by grouping routine state reads,
+  analytics, and maintainer gates under three audience namespaces while preserving
+  eleven top-level capability routing commands plus lifecycle commands.
+audience_tags:
+  agent: >-
+    Orientation, routine project-state reads, capability startup context, and
+    capability routing guidance the agent uses before raw artifact access.
+  user: >-
+    Install lifecycle, diagnostics, and privacy-gated analytics a human operator
+    runs without maintainer-only verification gates.
+  maintainer: >-
+    Validation, verification, lint, compaction, and repository gate checks used in
+    CI, hooks, and maintainer workflows.
+top_level_commands:
+  control_plane:
+    prime:
+      audience: [agent]
+      status: target_canonical
+      replaces: hej
+      default_behavior: >-
+        Composite orientation briefing currently owned by `hej` (installed-app gate,
+        health, plan, attention, next_action, source_contract). Static priming prose
+        moves to an explicit flag such as `--guidance` when still needed.
+      modes:
+        default: composite orientation briefing (formerly `hej`)
+        context: >-
+          `agentera prime --context <capability> --format json` — slim
+          `capability_context` startup capsule per Decision 59
+        dashboard: >-
+          `agentera prime --dashboard` / `--orientation` — orientation JSON mode
+          (provisional flag spelling)
+      skill_routing: >-
+        Bare `/agentera` and bare `hej` skill routes target `agentera prime`, not
+        a separate `hej` CLI command.
+      removed_from_top_level: hej
+    schema:
+      audience: [agent]
+      status: target_canonical
+      replaces: describe
+      owns:
+        - command tree discovery
+        - audience tag metadata
+        - filters and output format discovery
+        - structured output shape metadata
+        - field selection metadata
+        - Decision 43 slash-route alias descriptions
+        - artifact schema discovery
+        - linked contract section pointers
+      migration_alias:
+        command: describe
+        stderr: one-line deprecation naming `schema`
+        removal: after one minor alias release
+  capabilities:
+    audience: [agent]
+    status: preserved_top_level
+    count: 11
+    excludes: hej
+    commands:
+      - visionera
+      - resonera
+      - inspirera
+      - planera
+      - realisera
+      - optimera
+      - inspektera
+      - dokumentera
+      - profilera
+      - visualisera
+      - orkestrera
+    behavior: >-
+      Top-level capability-name commands emit routing guidance only. They do not
+      execute capability workflows. Capability startup JSON remains on
+      `agentera prime --context <capability> --format json`, not on capability tops.
+    non_goals:
+      - Do not demote capability tops to `prime --context` only.
+      - Do not add `agentera hej` back as a capability top.
+  lifecycle:
+    upgrade:
+      audience: [user]
+      status: preserved_top_level
+      notes: Stays top-level; no `setup` namespace wrapper.
+    doctor:
+      audience: [user]
+      status: preserved_top_level
+      notes: Agentera CLI/install/runtime self-check only; see parent contract `doctor`.
+audience_namespaces:
+  state:
+    audience: [agent]
+    status: target_canonical_namespace
+    purpose: Routine artifact reads and advanced artifact query.
+    subcommands:
+      plan:
+        canonical_shape: agentera state plan [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: plan
+      progress:
+        canonical_shape: agentera state progress [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: progress
+      health:
+        canonical_shape: agentera state health [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: health
+      todo:
+        canonical_shape: agentera state todo [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: todo
+      decisions:
+        canonical_shape: agentera state decisions [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: decisions
+      docs:
+        canonical_shape: agentera state docs [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: docs
+      objective:
+        canonical_shape: agentera state objective [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: objective
+      experiments:
+        canonical_shape: agentera state experiments [--format text|json|yaml] [--fields ...]
+        legacy_top_level_alias: experiments
+      query:
+        canonical_shape: agentera state query [--list-artifacts] [<artifact>] [--format ...]
+        legacy_top_level_alias: query
+        notes: Advanced artifact access; not the normal routine state interface.
+    decision_45_policy: >-
+      Decision 45 routine state command names (`plan`, `progress`, `health`, `todo`,
+      `decisions`, `docs`, `objective`, `experiments`, `query`) remain stable during
+      Phase 1–2 as top-level stderr-deprecation aliases that delegate to
+      `agentera state <name>`. Canonical namespace form is `state <name>`; JSON/YAML
+      envelopes and source_contract shapes are unchanged.
+  report:
+    audience: [user]
+    status: target_canonical_namespace
+    purpose: Privacy-gated usage analytics.
+    subcommands:
+      default_read:
+        canonical_shape: agentera report [--format text|json] [--project VALUE]
+        delegates_from: stats
+        behavior: Matches today's plain `agentera stats` read-only analytics.
+      refresh:
+        canonical_shape: >-
+          agentera report refresh [--dry-run] [--consent local-history]
+          [--project-root PATH] [--format text|json]
+        delegates_from: stats refresh
+        behavior: Matches today's `agentera stats refresh` including consent gates.
+    legacy_top_level_alias: stats
+    rejected_top_level: corpus
+    notes: >-
+      `agentera usage` and `agentera usage` remain backward-compatible
+      maintainer seams per AGENTS.md until separately classified; public user-facing
+      analytics consolidate under `report`.
+  check:
+    audience: [maintainer]
+    status: target_canonical_namespace
+    purpose: Validation, verification, lint, and repository compaction gates.
+    subcommands:
+      validate:
+        canonical_shape: agentera check validate <family> [target options]
+        delegates_from: validate
+        notes: Preserves existing validate families (capability, artifact, descriptors, etc.).
+      verify:
+        canonical_shape: agentera check verify <family> <target> [options]
+        delegates_from: verify
+        notes: Smoke and eval gate families unchanged.
+      lint:
+        canonical_shape: agentera check lint --artifact <ARTIFACT> [options]
+        delegates_from: lint
+      compact:
+        canonical_shape: agentera check compact [--project PATH] [--mode check|fix] [--format text|json]
+        delegates_from:
+          - compact
+          - gate
+        notes: >-
+          `check compact` in default check-only mode matches today's `agentera gate`.
+          Artifact compaction budget checks remain on `check compact`.
+    legacy_top_level_aliases:
+      - validate
+      - verify
+      - lint
+      - gate
+      - compact
+help_grouping:
+  agent: [prime, state, schema, capabilities]
+  user: [upgrade, doctor, report]
+  maintainer: [check]
+prime_hej_schema_migration_boundary:
+  prime_absorbs_hej:
+    status: target
+    hej_cli: >-
+      Top-level `hej` is removed from the public parser after the alias period.
+      `agentera hej` prints one stderr deprecation naming `prime` and delegates
+      during Phase 1–2.
+    hej_skill_route: >-
+      Bare `hej` in the Agentera skill still routes to orientation, but the installed
+      CLI gate calls `agentera prime` and renders from that composite result.
+    prime_default: >-
+      Bare `agentera prime` emits the composite orientation briefing currently owned
+      by `hej`, not static priming-only prose. Static priming moves to `--guidance`
+      when retained.
+    prime_context_unchanged: >-
+      `agentera prime --context <capability> --format json` remains the sole supported
+      capability startup JSON seam per Decision 59; slim `capability_context` shape
+      and JSON budgets are unchanged.
+    doctor_default: >-
+      After migration, `agentera doctor --expect-command` defaults to `prime`, not
+      `hej`.
+  schema_replaces_describe:
+    status: target
+    canonical: agentera schema [--format json|yaml]
+    alias: >-
+      `agentera describe` prints one stderr deprecation naming `schema` and delegates
+      during Phase 1–2.
+    discovery_ownership: >-
+      `schema` owns runtime CLI/schema introspection formerly on `describe`, including
+      command tree, audience tags, artifact locations, and linked contract sections.
+      Capability startup contracts that reference discovery must point agents to
+      `agentera schema`, not `agentera describe`.
+decision_reconciliation:
+  decision_59:
+    prime_context_seam: >-
+      `prime --context` remains the capability startup seam. Top-level capability
+      names route to capability guidance; `prime` prepares the agent. Historical
+      `hej --capability-context` and `--context-profile full` paths stay removed.
+    prime_consolidation: >-
+      User direction consolidates dashboard/orientation into `prime` default briefing
+      rather than keeping bare `prime` as static-only priming plus a separate `hej`
+      dashboard owner.
+  decision_45:
+    routine_state_aliases: >-
+      Routine state names stay stable via top-level aliases during migration. Canonical
+      reads become `agentera state <name>`; envelopes, field selection, and
+      source_contract semantics are unchanged.
+    slash_route_separation: >-
+      Decision 43 slash aliases remain excluded from the CLI command surface. The
+      shared word `plan` keeps three distinct meanings documented below.
+plan_routing_distinction:
+  slash_route:
+    invocation: /agentera plan
+    surface: Agentera skill slash route (Decision 43 primary alias)
+    routes_to: planera
+    meaning: >-
+      Request-to-capability routing — start or continue Planera planning work. This
+      is not a CLI command and does not read `.agentera/plan.yaml` by itself.
+  state_read:
+    invocation: agentera state plan
+    legacy_alias: agentera plan
+    surface: CLI routine state read
+    meaning: >-
+      Read-only access to the active plan artifact summary, tasks, acceptance
+      criteria, evidence, and source_contract. Does not invoke Planera workflow
+      execution.
+  capability_top:
+    invocation: agentera planera
+    surface: CLI top-level capability routing command
+    meaning: >-
+      Emits Planera routing guidance prose/schemas pointers. Does not replace
+      `state plan` reads or `/agentera plan` slash routing. Capability startup JSON
+      for Planera remains `agentera prime --context planera --format json`.
+  agent_guidance: >-
+    Use `/agentera plan` when the user wants planning work routed to Planera; use
+    `agentera state plan` (or legacy `agentera plan`) when the agent needs plan
+    artifact state; use `agentera planera` for capability routing guidance; use
+    `agentera prime --context planera` for bounded Planera startup context.
+migration_phases:
+  phase_1:
+    name: add_namespaces_and_delegate
+    actions:
+      - Add `state`, `report`, and `check` namespace parsers.
+      - Delegate to existing handlers without behavior change.
+      - Add `schema` top-level command delegating from `describe`.
+      - Make `prime` default emit composite orientation briefing.
+      - Keep legacy top-level names as stderr-deprecation aliases.
+  phase_2:
+    name: update_contracts_docs_hooks
+    actions:
+      - Update SKILL.md, AGENTS.md, hooks, CI, and semantic fixtures to prefer canonical forms.
+      - Emit audience tags and command tree from `agentera schema`.
+      - Record measurement evidence for JSON surface moves.
+  phase_3:
+    name: remove_deprecated_top_level_parsers
+    actions:
+      - >-
+        Remove `hej`, public `describe`, and `gate` from top-level parser help.
+      - >-
+        Remove other deprecated top-level parsers except documented capability and
+        lifecycle names and the Phase 1–2 alias set until post-major cleanup.
+      - >-
+        Deferred final removal of all routine-state top-level aliases after one
+        minor alias release.
+alias_policy:
+  stderr_format: one-line deprecation naming the canonical command
+  delegation: forward to canonical handler with unchanged JSON/text envelopes
+  duration: one minor release minimum for hej, describe, and routine-state tops
+  forbidden:
+    - bundle-status compatibility alias (Decision 45 hard rename)
+    - adding Decision 43 slash aliases as CLI commands
+    - silent fallback without stderr during the alias period
+command_tree_target:
+  top_level_count: ~18
+  groups:
+    - prime [agent]
+    - schema [agent]
+    - visionera [agent]
+    - resonera [agent]
+    - inspirera [agent]
+    - planera [agent]
+    - realisera [agent]
+    - optimera [agent]
+    - inspektera [agent]
+    - dokumentera [agent]
+    - profilera [agent]
+    - visualisera [agent]
+    - orkestrera [agent]
+    - upgrade [user]
+    - doctor [user]
+    - state [agent]
+    - report [user]
+    - check [maintainer]
+
+deprecated_top_level_aliases:
+  # Command aliases that emit stderr deprecation warnings
+  - { legacy: hej, canonical: prime }
+  - { legacy: describe, canonical: schema }
+  - { legacy: plan, canonical: "state plan" }
+  - { legacy: progress, canonical: "state progress" }
+  - { legacy: health, canonical: "state health" }
+  - { legacy: todo, canonical: "state todo" }
+  - { legacy: decisions, canonical: "state decisions" }
+  - { legacy: docs, canonical: "state docs" }
+  - { legacy: objective, canonical: "state objective" }
+  - { legacy: experiments, canonical: "state experiments" }
+  - { legacy: query, canonical: "state query" }
+  - { legacy: compact, canonical: "check compact" }
+  - { legacy: gate, canonical: "check compact" }
+  - { legacy: verify, canonical: "check verify" }
+  - { legacy: stats, canonical: report }
+  - { legacy: lint, canonical: "check lint" }
+  - { legacy: validate, canonical: "check validate" }