agentera 0.0.0 → 3.0.0-dev.1

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -0,0 +1,950 @@
+interface: AgentReadyStateCli
+status: design_contract
+decision: 45
+purpose: >-
+  Define the Agentera state CLI command vocabulary and agent-ready interface
+  boundaries before executable Decision 45 tasks implement doctor, structured
+  output, field selection, describe, and input hardening behavior.
+sources:
+  decisions:
+    - .agentera/decisions.yaml#Decision-45
+    - .agentera/decisions.yaml#Decision-43
+    - .agentera/decisions.yaml#Decision-59
+  playbook: /home/jgabor/docs/agent-ready-interface-playbook.md
+  active_plan: .agentera/plan.yaml
+linked_addenda:
+  audience_namespace_cli_migration:
+    path: references/cli/audience-namespace-cli-migration.yaml
+    status: target_design_contract
+    purpose: >-
+      Target CLI command tree, audience namespaces (`state`, `report`, `check`),
+      prime/hej and schema/describe migration boundaries, Decision 45 routine-state
+      alias policy, and `/agentera plan` versus `state plan` versus `planera` routing
+      distinction. Parser implementation is deferred to plan tasks 2–4.
+principles:
+  - Keep the CLI state-oriented; capability routing remains a slash-command surface.
+  - Preserve stable routine state command names unless a task records an explicit migration.
+  - Prefer runtime structured output and introspection over static prompt stuffing.
+  - Validate agent-facing inputs at the CLI boundary before resolving paths or emitting partial output.
+routine_state_commands:
+  status: stable
+  commands:
+    - hej
+    - plan
+    - progress
+    - health
+    - todo
+    - decisions
+    - docs
+    - objective
+    - experiments
+    - query
+  rationale: >-
+    Decision 45 explicitly preserves routine state command names. These commands
+    are the top-level state seam used by agents and docs; changing them would
+    break Decision 44's stable labels and Decision 39's query-CLI direction.
+slash_route_aliases:
+  status: excluded_from_cli_commands
+  aliases:
+    status: hej
+    vision: visionera
+    discuss: resonera
+    research: inspirera
+    plan: planera
+    build: realisera
+    optimize: optimera
+    audit: inspektera
+    document: dokumentera
+    profile: profilera
+    design: visualisera
+    orchestrate: orkestrera
+  rationale: >-
+    Decision 43 aliases are exact `/agentera <alias>` routes, not CLI state
+    commands. Teaching `status`, `build`, `audit`, or `document` as CLI commands
+    would blur route vocabulary with state access; the shared word `plan` keeps
+    separate meanings as `/agentera plan` routing and `agentera plan` state.
+doctor:
+  status: implemented_hard_rename
+  command: doctor
+  removed_command: bundle-status
+  compatibility_alias: forbidden
+  owns:
+    - Agentera CLI self-check status
+    - installed bundle status
+    - install-root status
+    - runtime adapter availability and configuration diagnostics
+    - hook, package, and schema availability checks when implemented
+  excludes:
+    - project artifact health
+    - codebase quality audit findings
+    - inspektera architecture, test, dependency, or documentation audit output
+  adjacent_surfaces:
+    project_artifact_health: agentera health
+    codebase_audit: /agentera audit routes to inspektera
+    setup_specific_diagnostics: packages/cli/src/setup/doctor.ts
+  rationale: >-
+    Decision 45 rejects `bundle-status` as too narrow and rejects an alias for
+    release-clean vocabulary. `doctor` is Agentera CLI/install/runtime
+    self-check vocabulary only; artifact health and codebase audits remain owned
+    by `agentera health` and inspektera.
+schema:
+  status: implemented_runtime_introspection
+  command: schema
+  migration_alias:
+    command: describe
+    stderr: one-line deprecation naming schema
+  owns:
+    - command discovery
+    - filters and output format discovery
+    - structured output shapes
+    - field selection metadata
+    - Decision 43 slash-route alias descriptions
+    - artifact schema discovery
+    - doctor self-check categories
+  does_not_own:
+    - adding CLI commands for slash aliases
+    - replacing routine state commands
+    - claiming unavailable schema facts as implemented
+  rationale: >-
+    The playbook prioritizes runtime schema introspection so agents can discover
+    the current interface on demand. `schema` owns public discovery; `describe`
+    remains a stderr-deprecation alias during migration.
+describe:
+  status: deprecated_alias_for_schema
+  command: describe
+  canonical_replacement: schema
+  rationale: >-
+    Deprecated alias retained for one minor release; agents and docs should use
+    `agentera schema`.
+structured_output:
+  status: implemented_for_routine_state_commands
+  formats:
+    - json
+    - yaml
+  applies_to:
+    - hej
+    - plan
+    - progress
+    - health
+    - todo
+    - decisions
+    - docs
+    - objective
+    - experiments
+  excludes:
+    - adding new route-alias commands
+    - replacing human text output
+    - changing persisted artifact shapes
+    - selecting undocumented raw artifact fields
+  envelope:
+    routine_state_commands:
+      fields:
+        - command
+        - status
+        - entries
+        - counts
+        - source
+        - filters
+        - summary
+        - source_contract
+      status_values:
+        - ok
+        - empty
+      source_metadata:
+        - artifact
+        - path
+        - exists
+        - kind
+      source_contract:
+        plan:
+          status: implemented_complete_plan_artifact_envelope
+          fields:
+            - complete_for_plan_artifact
+            - complete_for_normal_startup_evaluation
+            - raw_artifact_reads_required
+            - raw_artifact_read_policy
+            - included_state
+            - complete_state
+            - raw_artifact_access_boundary
+            - missing_state
+            - fallback
+            - fallback_policy
+            - summary_fields
+            - entry_fields
+          complete_semantics: >-
+            When `complete_for_plan_artifact` is true, `agentera plan --format
+            json` includes plan summary metadata, tasks, dependencies, acceptance
+            criteria, evidence, overall acceptance, surprises, and previous-plan
+            archive references needed for normal read-only startup/evaluation
+            context; agents should skip defensive `.agentera/plan.yaml` reads.
+            Raw mapped plan artifact access remains valid for writes, archival,
+            validation, corruption diagnostics, or unavailable/incomplete CLI state
+            after CLI fallbacks. Legacy `entries`-shaped plan artifacts must not
+            report this complete state because they do not expose the current plan
+            summary/task/evidence envelope.
+        decisions:
+          status: implemented_normal_deliberation_envelope
+          fields:
+            - complete_for_returned_decisions
+            - complete_for_decision_context
+            - complete_for_returned_full_detail
+            - complete_for_normal_deliberation_context
+            - normal_deliberation_context
+            - decision_context_truth_table
+            - missing_full_detail_boundary
+            - missing_artifact_boundary
+            - filtered_result_boundary
+            - satisfaction_review_boundary
+            - compacted_history_boundary
+            - raw_artifact_access_boundary
+            - raw_artifact_reads_required
+            - raw_artifact_read_policy
+            - fallback_policy
+          complete_semantics: >-
+            `complete_for_decision_context` and
+            `complete_for_returned_full_detail` are full-detail signals and may be
+            false for compacted history, missing full-detail fields, or satisfaction
+            review pressure. Normal deliberation should key off
+            `complete_for_normal_deliberation_context`; when it is true, agents use
+            returned entries plus `missing_fields`, `compacted`, `caveats`, and
+            satisfaction review state without raw `.agentera/decisions.yaml` reads
+            or inference. Empty filtered results mean no returned decisions matched
+            the filter, not missing decision state. Missing artifacts make normal
+            deliberation context unavailable and enter CLI fallback/diagnostic
+            boundaries before any raw artifact repair.
+          raw_access_semantics: >-
+            Raw decision artifact access is reserved for Resonera-owned decision
+            writes/repairs, artifact corruption diagnostics, or CLI defect
+            investigation. It is not required merely because returned decisions are
+            compacted, incomplete, filtered, or require satisfaction review.
+      empty_state: >-
+        Missing or empty artifacts emit status=empty, entries=[], counts.entries=0,
+        and source.exists=false when the source file is absent.
+    hej:
+      fields:
+        - command
+        - status
+        - bundle
+        - mode
+        - profile
+        - v1_migration
+        - health
+        - issues
+        - plan
+        - docs
+        - progress
+        - objective
+        - state_presence
+        - attention
+        - decision_attention
+        - next_action
+        - orchestration_context
+        - closeout_context
+        - evidence_context
+        - benchmark_context
+        - execution_context
+        - source
+        - source_contract
+      source_contract:
+        capability_startup:
+          status: implemented_complete_startup_envelope
+          fields:
+            - complete_for_capability_startup
+            - raw_artifact_reads_required
+            - raw_artifact_read_policy
+            - available_state
+            - missing_state
+            - confidence_caveats
+            - cli_fallback
+          complete_semantics: >-
+            When complete_for_capability_startup is true, raw_artifact_reads_required
+            must be false and agents should not perform defensive raw artifact reads
+            for normal capability startup.
+          incomplete_semantics: >-
+            When startup state is incomplete, missing_state, confidence_caveats,
+            and cli_fallback must be explicit. Agents should try the named CLI
+            fallback commands before any last-resort raw artifact read.
+          capability_context_semantics: >-
+            Agentera 3.0 capability startup uses
+            `agentera prime --context <capability> --format json` as the sole
+            supported seam. The response emits only `command`, `status`, and
+            top-level `capability_context` as a startup capsule; its `state` block
+            owns declared read needs, included and missing state families, artifact
+            inventory, and `fallback_commands`, while its `context` block owns
+            capability-specific startup payloads and `first_invocation_read`.
+            Historical v2 paths `agentera hej --format json --capability-context`,
+            `--context-profile full`, and `--context-profile slim` are removed and
+            must not be taught as supported behavior.
+          planera_startup_context_semantics: >-
+            `agentera prime --context planera --format json` may include a bounded
+            `startup_contract` for normal Planera execution startup at
+            `capability_context.context.planning_context.startup_contract`. The
+            contract can summarize planning levels, step markers, CLI-first
+            orientation, raw plan artifact boundaries, full-plan review/self-audit
+            requirements, handoff expectations, and the Planera prose authority
+            boundary without reading `planera/instructions.md` at runtime. It must
+            not introduce `agentera planera`, new top-level commands, or hidden
+            capability-name aliases; `agentera schema` owns runtime/schema
+            introspection rather than a capability workflow payload.
+          orchestration_context_semantics: >-
+            `agentera prime --context orkestrera --format json` may include
+            orchestration_context with dependency-ready tasks, blocked task reasons,
+            selected next task, task acceptance/evidence summaries, caveats, fallback
+            commands, and a source contract. It must not introduce `agentera
+            orkestrera` or other capability-name CLI commands.
+          closeout_context_semantics: >-
+            `agentera prime --context dokumentera --format json` may include
+            closeout_context with artifact mappings, version policy, TODO blockers,
+            changelog boundary, progress evidence, benchmark evidence or an unavailable
+            caveat, local metadata/tag versus publication boundary state, fallback
+            commands, caveats, provenance pointers, non-empty evidence flags, and a
+            raw-read-last-resort source contract. It must not introduce `agentera
+            dokumentera`, new top-level commands, or new subcommands.
+          evidence_context_semantics: >-
+            `agentera prime --context inspektera --format json` may include
+            evidence_context with an evaluation target, plan criteria, progress
+            verification, docs state, health state, TODO state, protected-state and
+            version boundary status values, decision-context caveats, attributed
+            residual risks, fallback commands, caveats, provenance pointers, non-empty
+            evidence flags, and a raw-read-last-resort source contract. It must not
+            introduce `agentera inspektera`, new top-level commands, or new subcommands.
+          benchmark_context_semantics: >-
+            `agentera prime --context optimera --format json` may include
+            benchmark_context with retained startup benchmark source status, latest
+            report summary, aggregate history summary, runtime coverage caveats,
+            state-access rates, token-impact estimates, comparison null reasons,
+            recommendation action, manual-refresh guidance, privacy boundary,
+            fallback commands, and a raw-read-last-resort source contract. It must
+            not introduce `agentera optimera`, new top-level commands, or new subcommands.
+          execution_context_semantics: >-
+            `agentera prime --context realisera --format json` may include
+            execution_context with selected work, task details, acceptance criteria,
+            constraints, verification expectations, artifact update requirements,
+            progress logging requirements, changelog boundary, scope boundary,
+            fallback commands, caveats, read-only plan-completion sweep metadata,
+            and a raw-read-last-resort source contract. It must not introduce
+            `agentera realisera`, `agentera build`, new top-level commands, or new subcommands.
+          decision_attention_semantics: >-
+            `agentera prime --format json` may include one bounded `decision_attention`
+            payload when returned decisions require satisfaction review. The payload
+            derives from the same `_decision_context_entry` and
+            `_decision_satisfaction_context` semantics as `agentera decisions --format
+            json`, never infers satisfaction, never mutates `.agentera/decisions.yaml`,
+            keeps top-level attention bounded, and must not change `next_action`
+            routing priority.
+          evidence_context_target_contract: evidence_context_target_contract
+          current_status: complete
+          current_missing_state: []
+      empty_state: >-
+        Fresh projects emit mode=fresh with explicit plan/docs/progress absence
+        reasons, zero issue counts, source.artifacts_present=false, state_presence
+        absence metadata, and a caller-owned dashboard source_contract.
+  rationale: >-
+    The playbook calls for machine-readable output as a first-class path. Task 3
+    should add parseable routine output while keeping current command names and
+    useful human text output stable.
+startup_completeness:
+  status: implemented_complete_startup_envelope
+  owning_command: prime
+  preserves_routine_state_commands: true
+  slash_route_alias_cli_commands_added: false
+  complete_output_requires:
+    complete_for_capability_startup: true
+    raw_artifact_reads_required: false
+  incomplete_output_requires:
+    - missing_state
+    - confidence_caveats
+    - cli_fallback
+  fallback_policy: >-
+    Incomplete startup state must point agents to existing routine state commands
+    before any raw artifact read. Complete startup state must never require raw
+    artifact reads for normal capability startup.
+  current_cli_fallback:
+    - agentera plan --format json
+    - agentera docs --format json
+    - agentera progress --format json
+  state_families_added:
+    - plan task details, dependencies, acceptance criteria, and evidence summaries
+    - docs artifact mapping and source-contract completeness metadata
+    - latest progress verification metadata needed for Orkestrera evaluation
+    - Optimera benchmark_context metadata for retained startup benchmark summaries
+    - Realisera execution_context metadata for plan-driven implementation startup
+  empty_state_behavior: >-
+    agentera prime reports absent plan, docs, and progress state explicitly through
+    structured summaries and state_presence absence metadata instead of forcing
+    artifact discovery. Top-level `agentera hej` remains a migration alias.
+  repair_guidance_behavior: >-
+    agentera prime carries stale app repair commands through bundle/app_home output and
+    v1 migration preview/apply commands through v1_migration output.
+  non_goals:
+    - Do not add Decision 43 slash-route aliases to the CLI command surface.
+    - Do not remove or rename routine state commands.
+    - Do not add a separate benchmark command; Optimera benchmark comparison stays inside benchmark_context.
+evidence_context_target_contract:
+  status: task_1_design_contract
+  planned_context_name: evidence_context
+  planned_invocation: agentera prime --context inspektera --format json
+  implementation_status: implemented_provenance_and_boundary_contract
+  status_vocabulary:
+    protected_and_version_boundaries:
+      - verified_local
+      - not_checked_by_design
+      - requires_manual_check
+      - unavailable
+  inventory:
+    cli_first_sources:
+      - command: agentera prime --context orkestrera --format json
+        included_state:
+          - plan
+          - progress
+          - health
+          - todo
+          - docs
+        missing_state:
+          - decisions
+          - vision
+          - profile
+        fallback_commands:
+          - agentera decisions --format json
+        caveats:
+          - profile-derived state is stale and must not trigger profile refresh
+          - orchestration_context is incomplete for missing decisions, vision, and profile state
+      - command: agentera plan --format json
+        included_state:
+          - active plan header and summary
+          - task dependencies
+          - task statuses
+          - task acceptance criteria
+          - task evidence summaries
+          - previous_plan_archived pointer
+        missing_state: []
+        raw_artifact_reads_required: false
+      - command: agentera progress --format json
+        included_state:
+          - latest progress cycles
+          - latest verification text
+          - cycle provenance
+        missing_state:
+          - explicit retry-attempt count
+        raw_artifact_reads_required: false
+      - command: agentera docs --format json
+        included_state:
+          - artifact mapping
+          - version files
+          - semver policy
+          - indexed document freshness
+        missing_state: []
+        raw_artifact_reads_required: false
+      - command: agentera health --format json
+        included_state:
+          - latest audit
+          - dimension grades
+          - findings
+          - trajectory
+        missing_state: []
+        raw_artifact_reads_required: false
+      - command: agentera todo --format json
+        included_state:
+          - open 2.3.10 evidence-context TODO
+          - deferred 2.3.11 and 2.3.12 source-contract TODOs
+          - known open issues
+        missing_state: []
+        raw_artifact_reads_required: false
+      - command: agentera decisions --format json
+        included_state:
+          - decisions 51 and 52 with complete context
+          - compacted historical decision summaries
+        missing_state:
+          - full context for 40 compacted historical entries
+        raw_artifact_reads_required: false
+        caveats:
+          - compacted decisions expose missing_fields and caveats instead of reconstructed history
+    last_resort_raw_fallbacks:
+      - reason: archived previous-plan status is not exposed by routine CLI state
+        path: .agentera/archive/PLAN-2026-05-15-2-3-9-dokumentera-closeout-context-source-contract.yaml
+        verified_field: header.status=complete
+      - reason: Inspektera prose and schemas are validated directly; complete evidence_context covers normal evaluation startup without raw plan/progress/docs/health/TODO/decisions reads.
+        paths:
+          - skills/agentera/capabilities/inspektera/instructions.md
+          - skills/agentera/capabilities/inspektera/schemas/artifacts.yaml
+          - skills/agentera/capabilities/inspektera/schemas/validation.yaml
+        raw_artifact_reads_required_for_startup: false
+    stale_state_caveats:
+      - profile-derived state is stale; record as caveat and do not refresh profile
+      - installed app state, when stale or update-needed, is a caveat and not approval to run upgrade, repair, or refresh
+    archive_boundary:
+      previous_plan: .agentera/archive/PLAN-2026-05-15-2-3-9-dokumentera-closeout-context-source-contract.yaml
+      verified_header_status: complete
+      scope_decision: previous-plan archival is already handled by Planera activation and is not implementation scope for 2.3.10 Task 1
+  target_selection:
+    source: CLI state only during normal startup
+    no_raw_plan_or_progress_reads_required: true
+    selection_order:
+      - order: 1
+        selector: current in-progress plan task
+        selection_reason: in_progress_task
+      - order: 2
+        selector: first dependency-ready pending plan task from orchestration_context.selected_next_task or plan entries
+        selection_reason: first_dependency_ready_pending_task
+      - order: 3
+        selector: most recent completed plan task with non-empty evidence summary
+        selection_reason: latest_completed_task_with_evidence
+      - order: 4
+        selector: repository-level evidence context with no task target
+        selection_reason: no_plan_task_target
+    no_target_behavior:
+      status: no_target
+      complete_for_evidence_context: false
+      caveat: No plan task target was selected; evaluate repository-level evidence only and keep fallback commands visible.
+      raw_artifact_reads_required: false
+    required_target_fields:
+      - target_type
+      - target_number
+      - target_name
+      - target_status
+      - selection_reason
+      - source_provenance
+      - caveats
+  evidence_matrix:
+    required_for_normal_task_evaluation:
+      - family: evaluation_target
+        source: plan/orchestration CLI state
+        fallback: agentera plan --format json
+      - family: plan_criteria
+        source: agentera plan --format json entries.acceptance
+        fallback: none when complete_for_plan_artifact is true
+      - family: progress_verification
+        source: agentera progress --format json latest verification
+        fallback: agentera progress --format json
+      - family: docs_state
+        source: agentera docs --format json summary and entries
+        fallback: agentera docs --format json
+      - family: health_state
+        source: agentera health --format json latest audit
+        fallback: agentera health --format json
+      - family: todo_state
+        source: agentera todo --format json known issues and source-contract TODOs
+        fallback: agentera todo --format json
+      - family: source_contract
+        source: evidence_context.source_contract
+        fallback: listed existing CLI commands before raw reads
+    optional_or_caveated_for_normal_task_evaluation:
+      - family: decisions_context
+        source: agentera decisions --format json
+        caveat: compacted historical entries remain incomplete and must not be reconstructed from raw artifacts
+      - family: vision_context
+        source: hej startup only when included by capability context
+        caveat: missing vision is a caveat, not a raw-read requirement for normal evaluation startup
+      - family: profile_context
+        source: hej profile summary
+        caveat: stale or missing profile is a caveat, not approval to refresh or read profile directly during normal startup
+      - family: protected_state_checks
+        source: local CLI-visible evidence only
+        caveat: use statuses verified_local, not_checked_by_design, requires_manual_check, or unavailable
+      - family: version_checks
+        source: local docs/version state only
+        caveat: do not contact remotes, registries, installed apps, or profile generation
+      - family: publication_or_remote_state
+        source: none during normal evidence context
+        caveat: not_recorded_in_cli_state unless a supported local command explicitly exposes it
+  prohibited_actions:
+    - agentera inspektera
+    - adding new top-level CLI commands for this contract
+    - adding new subcommands for this contract
+    - refreshing installed app state
+    - refreshing profile state
+    - editing .agentera/vision.yaml
+    - editing objective state
+field_selection:
+  status: implemented_sparse_response_layer
+  applies_after: structured_output
+  syntax: --fields FIELD[,FIELD...]
+  applies_to:
+    - hej
+    - plan
+    - progress
+    - health
+    - todo
+    - decisions
+    - docs
+    - objective
+    - experiments
+  fields_by_command:
+    routine_state_commands:
+      fields:
+        - command
+        - status
+        - entries
+        - counts
+        - source
+        - filters
+        - summary
+        - source_contract
+    hej:
+      fields:
+        - command
+        - status
+        - bundle
+        - mode
+        - profile
+        - v1_migration
+        - health
+        - issues
+        - plan
+        - docs
+        - progress
+        - objective
+        - state_presence
+        - attention
+        - decision_attention
+        - next_action
+        - orchestration_context
+        - closeout_context
+        - evidence_context
+        - benchmark_context
+        - execution_context
+        - source
+        - source_contract
+  retained_context:
+    - command
+    - status
+  owns:
+    - sparse selection over documented structured output fields
+    - clear unsupported-field errors with available fields
+    - required identity or status context retained in sparse responses
+  does_not_own:
+    - selecting arbitrary raw YAML artifact paths
+    - silently dropping unsupported fields
+    - changing default human text behavior
+  rationale: >-
+    The playbook treats context as currency. Field selection belongs on the
+    structured output contract from Task 3, not on raw artifact internals.
+input_hardening:
+  status: implemented_boundary_validation
+  applies_to:
+    - artifact names
+    - field names
+    - output formats
+    - path-like values
+    - doctor roots
+    - upgrade roots
+  required_boundaries:
+    - reject unsupported identifiers with clear errors
+    - reject traversal and encoded traversal in path-like inputs
+    - reject control characters in agent-facing strings
+    - sandbox project artifact paths to project-owned or documented global roots
+    - preserve explicit approval flows before writes
+  does_not_own:
+    - mutating install roots without approval
+    - expanding artifact identity beyond the artifact registry and docs.yaml mapping rules
+    - response sanitization for externally ingested untrusted content
+    - typed protocol surfaces such as MCP or JSON-RPC
+  rationale: >-
+    The playbook warns that agents hallucinate structurally unsafe inputs. Task 6
+    should validate these boundaries without broadening the CLI command surface.
+validate_namespace:
+  status: implemented
+  command: validate
+  purpose: >-
+    Define the supported `agentera validate` namespace so agents can use one
+    discoverable validation surface without guessing unsupported capability-name
+    CLI commands.
+  supported_target_families:
+    capability:
+      command_shape: agentera validate capability <capability-or-path> [--format text|json]
+      required_inputs:
+        - capability-or-path: canonical capability name or capability directory path
+      valid_capability_names:
+        - hej
+        - visionera
+        - resonera
+        - inspirera
+        - planera
+        - realisera
+        - optimera
+        - inspektera
+        - dokumentera
+        - profilera
+        - visualisera
+        - orkestrera
+      output_formats:
+        - text
+        - json
+      expected_examples:
+        - agentera validate capability hej
+        - agentera validate capability skills/agentera/capabilities/hej --format json
+      validation_engine: agentera check validate capability
+      compatibility_constraint: >-
+        `agentera check validate capability skills/agentera/capabilities/<name>` and
+        `agentera check validate capability --self-validate` remain supported direct
+        validator commands with their existing observable behavior.
+    artifact:
+      command_shape: agentera validate artifact --artifact <ARTIFACT> [--file <PATH>] [--cwd <PROJECT>] [--format text|json]
+      required_inputs:
+        - artifact: canonical artifact label
+      optional_inputs:
+        - file: artifact file path; defaults through docs.yaml mapping when omitted
+        - cwd: project directory for relative paths and docs.yaml mapping
+      valid_artifacts:
+        - CHANGELOG.md
+        - DECISIONS.md
+        - DESIGN.md
+        - DOCS.md
+        - HEALTH.md
+        - PLAN.md
+        - PROGRESS.md
+        - TODO.md
+        - VISION.md
+      output_formats:
+        - text
+        - json
+      expected_examples:
+        - agentera validate artifact --artifact PLAN.md --file .agentera/plan.yaml --format json
+        - agentera validate artifact --artifact PROGRESS.md --format text
+      validation_engine: hooks/validate_artifact.py
+      compatibility_constraint: >-
+        `hooks/validate_artifact.py --artifact <ARTIFACT> --file <PATH> --format
+        text|json` remains a supported direct validator command with existing
+        docs.yaml mapping, JSON envelope, violation wording, and hook behavior.
+  invalid_input_behavior:
+    family_error: >-
+      Unsupported validate target families must name the valid families
+      `capability` and `artifact`, show the correct syntax, and include one
+      concrete capability example plus one concrete artifact example.
+    capability_error: >-
+      Unsupported capability targets must list valid capability names, show
+      `agentera validate capability <capability-or-path> [--format text|json]`,
+      and include `agentera validate capability hej` as an example.
+    artifact_error: >-
+      Unsupported artifact labels must list canonical artifact labels, show
+      `agentera validate artifact --artifact <ARTIFACT> [--file <PATH>] [--format text|json]`,
+      and include `agentera validate artifact --artifact PLAN.md --file .agentera/plan.yaml --format json`
+      as an example.
+    format_error: >-
+      Unsupported formats must list valid values `text` and `json` and must not
+      fall back silently to a different format.
+  output_contract:
+    text: >-
+      Human-readable output may mirror the existing validator text, including
+      PASS/FAILED summaries and violation lines.
+    json: >-
+      JSON output must use a stable validation result envelope with command,
+      status, target_family, target, file or path metadata when applicable, and
+      violations or errors. Artifact JSON should preserve the existing
+      `validate-artifact` semantics unless a compatibility-preserving wrapper
+      field is explicitly added in the implementation task.
+    status_values:
+      - pass
+      - fail
+  non_goals:
+    - Do not implement `agentera validate` behavior in Task 1.
+    - Do not add capability-name CLI commands such as `agentera realisera`.
+    - Do not replace or remove `agentera check validate capability`.
+    - Do not replace or remove `hooks/validate_artifact.py`.
+    - Do not rename artifact labels, capability names, or schema contract groups.
+    - Do not implement D48 smoke, verify, corpus, or usage namespaces.
+    - Do not redesign validation semantics or persisted artifact shapes.
+  evidence_sources:
+    - agentera --help exposes the validate namespace for capability and artifact validation.
+    - agentera check validate capability --help defines capability_dir, --self-validate, --validate-protocol, and --check-primitives.
+    - hooks/validate_artifact.py --help defines --artifact, --file, --cwd, and --format text|json.
+    - hooks/validate_artifact.py invalid artifact JSON lists valid canonical artifact labels.
+verify_namespace:
+  status: implemented_with_task_3_coverage
+  command: verify
+  rejected_umbrella_command: smoke
+  purpose: >-
+    Define the supported `agentera verify` namespace so agents can run or inspect
+    smoke and eval gates through one discoverable verification surface without
+    guessing direct script names or unsupported capability-name CLI commands.
+  namespace_rationale: >-
+    `agentera verify` is the public command for the evaluation gates (skills and
+    semantic). The smoke-check family was retired in the self-contained package.
+  command_shape: agentera verify <family> <target> [--format text|json] [target options]
+  supported_gate_families:
+    eval:
+      command_shape: agentera verify eval <target> [--format text|json] [target options]
+      valid_targets:
+        skills:
+          direct_entrypoint: in-process eval engine (packages/cli/src/eval/evalSkills.ts)
+          expected_default_behavior: >-
+            Skill eval verification runs the in-process eval-skills engine. Any
+            runtime-backed eval work is host-dependent and must be
+            explicitly opted in or bounded through existing dry-run, runtime, timeout,
+            skill, and parallel controls.
+          safety_requirements:
+            - Default verify behavior must not start long-running runtime-backed evals without explicit opt-in or a documented bounded mode.
+            - Runtime-backed runs must retain per-skill timeout and concurrency bounds.
+            - Dry-run listing remains available for safe discovery.
+        semantic:
+          direct_entrypoint: in-process semantic engine (packages/cli/src/eval/semanticEval.ts)
+          expected_default_behavior: >-
+            Offline semantic fixture evaluation remains the direct compatibility
+            surface. Verify must require explicit fixture paths or a documented bounded
+            fixture selection; it must not scan broad corpora by default.
+          safety_requirements:
+            - Offline fixture evaluation only by default.
+            - Missing or broad fixture input fails with bounded guidance instead of starting an unbounded search.
+      output_formats:
+        - text
+        - json
+      expected_examples:
+        - agentera verify eval skills --format json
+        - agentera verify eval skills --dry-run --format json
+        - agentera verify eval semantic fixtures/semantic/hej-bare-message.md
+        - agentera verify eval semantic fixtures/semantic/hej-bare-message.md --format json
+  output_contract:
+    text: >-
+      Human-readable output must identify the verify family, target, status, direct
+      engine used, and bounded diagnostics. It may mirror existing direct script PASS
+      or FAIL wording when that preserves compatibility.
+    json: >-
+      JSON output must use a stable verification result envelope with command,
+      status, family, target, format, engine command, exit_code, diagnostics, and
+      safety/opt-in metadata when applicable. Raw runtime transcripts, credentials,
+      private paths beyond explicit command inputs, and unbounded logs are excluded.
+    status_values:
+      - pass
+      - fail
+      - invalid
+      - skipped
+  invalid_input_behavior:
+    family_error: >-
+      Unknown verify families must exit nonzero, list valid families `smoke` and
+      `eval`, show `agentera verify <family> <target> [--format text|json]`, and
+      include concrete examples for one smoke target and one eval target.
+    target_error: >-
+      Unknown targets must exit nonzero, list valid targets for the selected family,
+      show the correct family syntax, and include one concrete example for that family.
+    format_error: >-
+      Unknown formats must exit nonzero, list valid values `text` and `json`, show
+      syntax using `--format text|json`, and must not silently fall back to another format.
+    unsafe_live_default_error: >-
+      Requests that would run live, host-dependent, mutating, or long-running gates
+      without required opt-in must exit nonzero with bounded diagnostics explaining
+      the missing opt-in, the safe default, valid opt-in flags or environment contract,
+      correct syntax, and a concrete explicitly bounded example.
+  compatibility_constraints:
+    - >-
+      `agentera verify eval skills` remains callable directly with existing `--skill`,
+      `--dry-run`, `--parallel`, `--timeout`, and `--runtime` behavior.
+    - >-
+      `agentera verify eval semantic` remains callable directly with fixture path arguments
+      and existing offline semantic fixture behavior.
+      offline default behavior plus the explicit `--real-npx` opt-in path.
+      default behavior and explicit `--live`/`--yes` live-host opt-in behavior.
+      observable smoke-check behavior, including current non-argparse `--help` behavior.
+      observable local bootstrap diagnostics and failure behavior.
+  non_goals:
+    - Do not add unsupported capability-name CLI commands such as `agentera realisera` or `agentera orkestrera`.
+    - Do not reintroduce the retired smoke gate-family.
+    - Do not implement D48 `validate`, `corpus`, or `usage` work.
+    - Do not run live network, installed-app mutation, profile refresh, publication, push, tag, or package-update flows as part of this contract definition.
+  evidence_sources:
+    - agentera --help exposes the `verify` namespace and safe smoke/eval examples.
+    - the verify vitest tests (packages/cli/test/cli/verify.test.ts) covers smoke success, eval success, text output, JSON output, invalid input feedback, safety boundaries, and preserved direct-script compatibility.
+    - agentera verify eval skills --help defines `--skill`, `--dry-run`, `--parallel`, `--timeout`, and `--runtime`.
+    - agentera verify eval semantic --help defines fixture path inputs for offline semantic evaluation.
+usage_namespace:
+  status: implemented
+  command: usage
+  rejected_namespace_command: corpus
+  purpose: >-
+    Define the supported `agentera usage` namespace so agents can run suite usage
+    analytics through one discoverable CLI surface without guessing the direct
+    analytics script or conflating reporting with corpus extraction.
+  namespace_rationale: >-
+    `agentera usage` is the selected public command because the existing product is
+    usage analytics and USAGE.md reporting. `agentera corpus` is rejected for this
+    plan because it implies corpus extraction or lifecycle management, which belongs
+    to profilera/Section 22 tooling rather than usage reporting.
+  command_shape: agentera usage [--format text|json] [--corpus PATH] [--project VALUE]
+  direct_entrypoint: agentera usage
+  supported_options:
+    format:
+      values:
+        - text
+        - json
+      default: text
+      text_behavior: >-
+        Delegates to `agentera usage`, writes USAGE.md to the existing report
+        destination, and prints the existing bounded stdout summary.
+      json_behavior: >-
+        Delegates to `agentera usage --json`, preserves the existing top-level
+        analytics payload, and does not write USAGE.md.
+    corpus:
+      syntax: --corpus PATH
+      behavior: >-
+        Uses the supplied Section 22 corpus.json envelope. When omitted, default
+        corpus lookup remains owned by `agentera usage` and follows
+        `PROFILERA_PROFILE_DIR/intermediate/corpus.json` before platform data-home
+        defaults.
+    project:
+      syntax: --project VALUE
+      behavior: >-
+        Scopes analytics using the direct script's project matching behavior.
+        Unmatched values are valid and produce an empty scoped report rather than a
+        nonzero invalid-input error.
+  output_contract:
+    text: >-
+      Human-readable output preserves the direct script's summary lines, including
+      scope, skill count, invocation totals, report path, run timestamp, and corpus
+      extraction timestamp.
+    json: >-
+      JSON output preserves the direct script analytics payload with top-level
+      `generated_at`, `extracted_at`, `project_filter`, `skills`, `per_project`, and
+      `invocations` fields. It is intentionally not wrapped in a facade envelope.
+  path_contract:
+    report_precedence:
+      - AGENTERA_USAGE_DIR/USAGE.md
+      - PROFILERA_PROFILE_DIR/USAGE.md
+      - platform data home agentera/USAGE.md
+    corpus_precedence:
+      - PROFILERA_PROFILE_DIR/intermediate/corpus.json
+      - platform data home agentera/intermediate/corpus.json
+    test_isolation: >-
+      Facade tests that exercise default text writes must set temporary
+      `AGENTERA_USAGE_DIR` and `PROFILERA_PROFILE_DIR` values and must not write the
+      real user data home.
+  invalid_input_behavior:
+    format_error: >-
+      Unknown formats must exit nonzero, list valid values `text` and `json`, show
+      `agentera usage [--format text|json] [--corpus PATH] [--project VALUE]`, and
+      include one concrete example.
+    missing_corpus: >-
+      Missing or unusable corpus data preserves `agentera usage` actionable
+      guidance and must not auto-build corpus data, refresh profiles, scan home
+      directories, or run live host extraction.
+    project_filter: >-
+      Unmatched `--project` values are valid empty reports. Diagnostics must not list
+      private corpus-derived project IDs as valid values.
+  compatibility_constraints:
+    - >-
+      `agentera usage` remains callable directly with existing `--json`,
+      `--corpus`, and `--project` behavior.
+    - >-
+      JSON consumers continue to receive the existing direct analytics payload shape
+      without a namespace wrapper envelope.
+    - >-
+      Default text behavior continues to write USAGE.md only through the existing
+      usage report destination rules.
+  non_goals:
+    - Do not add `agentera corpus` in this plan.
+    - Do not build or refresh corpus data.
+    - Do not refresh PROFILE.md or run profilera.
+    - Do not run live host scans or mine home directories beyond direct script path lookup.
+    - Do not remove, rename, or redesign `agentera usage`.
+    - Do not add unsupported capability-name CLI commands.
+    - Do not implement additional D48 validate, verify, or corpus namespace work.
+  evidence_sources:
+    - agentera --help exposes the `usage` namespace and a JSON example.
+    - the usage/report vitest tests covers text output, JSON output, corpus/project flags, missing-corpus guidance, invalid format, help discovery, test path isolation, and direct-script compatibility.
+    - the usageStats vitest tests remains the direct analytics engine coverage.
+non_goals_for_task_1:
+  - Do not rename bundle-status to doctor.
+  - Do not add doctor behavior.
+  - Do not add describe behavior.
+  - Do not add structured output behavior.
+  - Do not add field selection behavior.
+  - Do not harden executable inputs.
+  - Do not mark Task 1 complete in .agentera/plan.yaml.