agentera 3.0.0-dev.41 → 3.0.0-dev.46

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

@@ -1,1015 +0,0 @@
-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 state plan list` state.
-doctor:
-  status: implemented_hard_rename
-  command: doctor
-  removed_command: bundle-status
-  compatibility_alias: forbidden
-  owns:
-    - Agentera CLI self-check status
-    - installed app and install-root status
-    - canonical shared-skill diagnosis
-    - project integration and project-state migration diagnostics
-    - bounded offline smoke checks when requested
-  excludes:
-    - project artifact health
-    - codebase quality audit findings
-    - inspektera architecture, test, dependency, or documentation audit output
-  adjacent_surfaces:
-    codebase_audit: /agentera audit routes to inspektera
-  rationale: >-
-    Decision 45 rejects `bundle-status` as too narrow and rejects an alias for
-     release-clean vocabulary; `doctor` is the CLI, app, shared-skill, and project
-     integration self-check vocabulary, while artifact health and codebase audits
-     remain separate concerns.
-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 state plan list --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
-        - app_home
-        - app
-        - mode
-        - profile
-        - v1_migration
-        - health
-        - todo
-        - plan
-        - docs
-        - progress
-        - objective
-        - state_presence
-        - project_integration
-        - attention
-        - history
-        - shared_skill
-        - 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 `packages/cli/src/capabilities/planera/instructions.ts`
-            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. Verification commands are
-            selected only from bounded verification-labelled rows in the root
-            AGENTS.md `When | Command` recipe table. Explicit root or `pnpm -C`
-            package.json scripts validate those references; exact script aliases are
-            resolved before duplicate-label conflict checks, and equivalent canonical
-            commands are deduplicated with bounded line/field source pointers retained.
-            Command, provenance, rejection, and diagnostic omissions are reported by
-            explicit counts below generic startup projection limits. Malformed
-            recipes, placeholders, shorthand, unsupported syntax, symlinked sources,
-            targets, or existing ancestors, missing scripts, cycles, out-of-root paths,
-            every missing Node entrypoint, and conflicting canonical label sets are
-            rejected with bounded diagnostics rather than inferred or executed. Node
-            arguments use tokens only and reject absolute or parent-traversing values,
-            including values after `=`; discovery never executes a recipe. 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 bounded `agentera state
-             decisions list --limit 20 --format json` plus exact `state decisions
-             get --id ID`, never infers satisfaction, never mutates decision entities,
-            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 state plan list --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 or explicit transient no-plan 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.
-build_transient_execution_request:
-  status: implemented
-  command: agentera prime --context build --input <file|-> --format json
-  schema_version: agentera.buildExecutionRequest.v1
-  transport:
-    sources:
-      - file
-      - stdin
-    request_text_in_argv: forbidden
-    max_utf8_bytes: 32768
-    malformed_utf8: fatal
-    document: YAML or JSON mapping
-    acquisition:
-      file: >-
-        Regular files only; symlinks and non-regular inputs fail closed. Open
-        no-follow where supported, verify the opened descriptor identity against
-        the observed file, precheck known size, and incrementally read at most
-        max_utf8_bytes + 1 before rejecting overflow.
-      stdin: >-
-        Incrementally read fd 0 in bounded chunks through max_utf8_bytes + 1;
-        reject overflow and never close fd 0. Injected test stdin is capped
-        immediately after the supplied value returns.
-  fields:
-    exact_required:
-      - schema_version
-      - scope
-      - acceptance
-    additional_fields: forbidden
-    scope:
-      type: string
-      non_empty: true
-      max_unicode_code_points: 160
-      control_characters: forbidden
-    acceptance:
-      type: list_of_strings
-      min_items: 1
-      max_items: 12
-      duplicate_items: forbidden
-      item_non_empty: true
-      item_max_unicode_code_points: 160
-      item_control_characters: forbidden
-  validation_failure:
-    envelope: agentera.invalidInputEnvelope.v2
-    exit_code: 2
-    sensitive_input_echo: forbidden
-  availability:
-    only_with_context: build
-    active_or_completed_current_plan: conflict
-    archived_history_without_current_executable_plan: allowed
-    malformed_or_degraded_plan_state: fail_safe
-  persistence:
-    request_persisted: false
-    orientation_state_extended: false
-    state_mutation: none
-    plan_creation_or_mutation: forbidden
-  no_plan_execution_context:
-    mode: no_plan
-    valid_request:
-      work_selection_reason: explicit_no_plan_scope
-      acceptance_source: exact transient request
-      source_path_inference: forbidden
-      plan_fallback: forbidden
-      plan_status_update_required: false
-      complete_for_execution_context: true when all non-plan required execution state is available
-    missing_request:
-      complete_for_execution_context: false
-      plan_fallback: forbidden
-      advancing_recovery: agentera prime --context build --input - --format json
-      caveat: Explicit scope and acceptance are required for no-plan execution.
-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 state decisions list --limit 20 --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 state plan list --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 state docs list --format json
-        included_state:
-          - artifact mapping
-          - version files
-          - semver policy
-          - indexed document freshness
-        missing_state: []
-        raw_artifact_reads_required: false
-      - command: agentera state todo list --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
-    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:
-          - packages/cli/src/capabilities/inspektera/instructions.ts
-          - 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 state plan list --format json
-      - family: plan_criteria
-        source: agentera state plan list --format json entries.acceptance
-        fallback: none when complete_for_plan_artifact is true
-      - family: progress_verification
-        source: agentera state progress list --limit 20 --format json latest verification
-        fallback: agentera state progress get --id ID --format json
-      - family: docs_state
-        source: agentera state docs list --format json summary and entries
-        fallback: agentera state docs list --format json
-      - family: health_state
-        source: agentera state health list --limit 20 --format json latest audit
-        fallback: agentera state health get --id ID --format json
-      - family: todo_state
-        source: agentera state todo list --format json known issues and source-contract TODOs
-        fallback: agentera state todo list --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 state decisions list --limit 20 --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
-        - app_home
-        - app
-        - mode
-        - profile
-        - v1_migration
-        - health
-        - todo
-        - plan
-        - docs
-        - progress
-        - objective
-        - state_presence
-        - project_integration
-        - attention
-        - history
-        - shared_skill
-        - 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
-    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) on the npm self-contained CLI. The smoke-check family is retired on
-    @next; run smoke maintainer harnesses on the stable Python line with
-    `uvx --from git+https://github.com/jgabor/agentera@main agentera check verify smoke installed-skills`.
-  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 family `eval`, show
-      `agentera verify <family> <target> [--format text|json]`, and include a
-      concrete eval example. Requests for the retired `smoke` family must exit
-      nonzero with explicit npm-retired guidance pointing to eval verify or the
-      stable Python maintainer path.
-    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.
-    - >-
-      Retired `smoke` verify requests on the npm self-contained CLI must fail with
-      bounded guidance instead of invoking Python smoke harnesses.
-  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 eval examples only on npm @next.
-    - the verify vitest tests (packages/cli/test/cli/verify.test.ts) cover eval success, smoke retirement, 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
-        `AGENTERA_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
-      - AGENTERA_PROFILE_DIR/USAGE.md
-      - platform data home agentera/USAGE.md
-    corpus_precedence:
-      - AGENTERA_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 `AGENTERA_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.