agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/bundle/references/artifacts/verbosity-budget-authority.yaml

@@ -0,0 +1,42 @@
+schema_version: agentera.verbosityBudgetAuthority.v1
+status: active_authority
+purpose: >-
+  Define which artifact schema owns each verbosity budget. Budget values stay
+  in the owning schema so validators and future consumers cannot introduce a
+  second value table.
+authority:
+  source: references/artifacts/verbosity-budget-authority.yaml
+  schema_directory: ../../skills/agentera/schemas/artifacts
+  single_source_rule: >-
+    Each supported artifact resolves to exactly one schema BUDGET group.
+    Missing, unreadable, duplicate, or malformed declarations are authority
+    errors; consumers must not substitute generic or historical limits.
+classification:
+  numeric_limit: A positive max_words value.
+  explicit_no_limit: A null max_words value.
+  non_word_unit: A positive token_budget value; it does not authorize word lint.
+  invalid_declaration: A missing, duplicate, ambiguous, or malformed declaration.
+scope:
+  supported_artifacts:
+    - artifact_id: changelog
+      schema: changelog.yaml
+    - artifact_id: decisions
+      schema: decisions.yaml
+    - artifact_id: design
+      schema: design.yaml
+    - artifact_id: docs
+      schema: docs.yaml
+    - artifact_id: experiments
+      schema: experiments.yaml
+    - artifact_id: health
+      schema: health.yaml
+    - artifact_id: objective
+      schema: objective.yaml
+    - artifact_id: plan
+      schema: plan.yaml
+    - artifact_id: progress
+      schema: progress.yaml
+    - artifact_id: todo
+      schema: todo.yaml
+    - artifact_id: vision
+      schema: vision.yaml

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

@@ -2,7 +2,7 @@ schema_version: agentera.app_lifecycle_vocabulary.v1
 status: active_authority
 decision: 54
 purpose: >-
-  Define the app lifecycle vocabulary shared by doctor, hej, upgrade, docs,
+  Define the app lifecycle vocabulary shared by doctor, status, upgrade, docs,
   and tests so structured status metadata, operation verbs, deprecated aliases,
   and consumer ownership boundaries have one machine-readable source.
 sources:
@@ -12,7 +12,7 @@ sources:
     - references/cli/vocabulary.md#app-lifecycle-status-vocabulary
 scope:
   includes:
-    - Agentera app lifecycle status metadata emitted by doctor, hej, and upgrade.
+    - Agentera app lifecycle status metadata emitted by doctor, status, and upgrade.
     - Upgrade workflow operation verbs for app files, data migration, and no-change outcomes.
     - Cross-major status concepts that annotate migration work without adding parallel status enums.
     - Transitional deprecated aliases needed to classify shipped or historical consumers.
@@ -25,10 +25,9 @@ scope:
     - Update channel names, dist-tag resolution, and override keys.
     - General prose outside app lifecycle metadata.
 compatibility_boundary: >-
-  Compatibility identifiers such as `.agentera-bundle.json`, `bundle.status`,
-  `activeBundleRoot`, and `--only bundle` may remain until an explicit migration
-  exists. They do not make bundle/fresh/stale/refresh/fixed canonical app
-  lifecycle status vocabulary.
+  Retired v2 identifiers such as `.agentera-bundle.json`, `bundle.status`,
+  `activeBundleRoot`, and `--only bundle` may remain only in migration readers,
+  fixtures, and released history. They are not current app lifecycle vocabulary.
 canonical_status_order:
   - up_to_date
   - outdated
@@ -155,7 +154,7 @@ operation_verbs:
     lifecycle_allowed: false
 consumer_order:
   - doctor
-  - hej
+  - status
   - upgrade
   - docs
   - tests
@@ -176,7 +175,7 @@ consumers:
       - migrate
       - upgrade
     may_define_new_statuses: false
-  hej:
+  status:
     owns:
       - installed app gate summary exposed in the composite state briefing.
       - recovery prompts derived from doctor and upgrade metadata.

package/bundle/references/cli/capability-instruction-contract.yaml

@@ -3,9 +3,10 @@ status: active_authority
 decision: 57
 purpose: >-
   Define the Decision 57 capability instruction-file contract: the canonical
-  `instructions.md` file name, implemented CLI/schema first-invocation read
-  discoverability, compact-startup exception boundaries, and runtime behavior
-  that remains intentionally unsupported.
+  `instructions.ts` module path, implemented CLI/schema first-invocation read
+  discoverability, the `prime_context` runtime-enforcement boundary, and
+  retirement of the historical `full`/`compact_startup`/`skip` values
+  superseded by Decision 65.
 sources:
   decision: .agentera/decisions.yaml#decision-57
   prose:
@@ -13,91 +14,85 @@ sources:
     - README.md#development
 scope:
   includes:
-    - Documentation authority for the implemented capability instruction-file name.
+    - Documentation authority for the implemented capability instruction module path.
     - CLI/schema discoverability for first capability invocation startup-read metadata.
-    - Compact-startup exception semantics and boundaries.
-    - Current canonical references to existing `instructions.md` files.
+    - The single `prime_context` first-invocation shape enforced by the runtime.
+    - Current canonical references to existing `instructions.ts` modules.
     - Explicit separation from runtime behavior work.
   excludes:
     - Implementing first-invocation read behavior.
     - Marking Decision 57 satisfied or editing protected vision/objective/profile/installed-app state.
 current_state:
   canonical_instruction_file:
-    path: skills/agentera/capabilities/<name>/instructions.md
+    path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_canonical_implemented
     definition: >-
-      The human-readable instruction file for each capability.
+      The TypeScript module that exports the capability's behavioral
+      instructions as a default-exported string constant. The runtime loads
+      the compiled .js path and serves the instructions through the slim
+      `capability_context` capsule's `instructions` field.
   legacy_instruction_file:
+    path: skills/agentera/capabilities/<name>/instructions.md
+    status: historical_or_compatibility_evidence_only
+    definition: >-
+      The pre-D65 Markdown instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
+  legacy_prose_file:
     path: skills/agentera/capabilities/<name>/prose.md
     status: historical_or_compatibility_evidence_only
     definition: >-
-      The former capability instruction filename. It may survive only in archived
-      history, compatibility fixtures, benchmark evidence, or explicit migration
-      documentation; real capability directories do not use it as canonical.
+      The pre-D57 capability instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
   validator_requirement:
-    current_required_path: instructions.md
-    future_required_path: instructions.md
+    current_required_path: packages/cli/src/capabilities/<name>/instructions.ts
+    future_required_path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_requirement_enforced
   cli_metadata:
     field: first_invocation_read
     status: emitted_in_prime_capability_context
     current_behavior: >-
-      `agentera prime --context <name> --format json` emits
-      `capability_context` metadata including `first_invocation_read` for
-      supported capabilities. Historical `hej --capability-context` is removed in 3.0.
+      `npx -y agentera@next prime --context <name> --format json` emits
+      `capability_context` metadata including `first_invocation_read`
+      (value: `prime_context`, runtime_enforcement: true) and the full instructions
+      in the `instructions` field for supported capabilities. Historical
+      `hej --capability-context` is removed in 3.0.
 first_invocation_read:
-  field_status: cli_schema_discoverability_implemented
+  field_status: runtime_enforced
   definition: >-
-    Capability metadata declaring what instruction content an agent must read on
-    the first invocation of that capability in a session.
+    Capability metadata declaring what instruction content an agent must
+    read on the first invocation of that capability in a session. Decision
+    65 collapses the legacy `full`/`compact_startup` distinction into a
+    single `prime_context` value because the CLI now owns the instructions and
+    the runtime can mechanically shell out to the prime command.
   allowed_values:
-    full:
-      meaning: >-
-        The first capability invocation must read `instructions.md` in full before
-        executing capability-specific work.
-      obligation: full_instruction_file_read_required
-    compact_startup:
-      meaning: >-
-        A declared compact startup contract may satisfy initial orientation without
-        reading the full instruction file first.
-      obligation: compact_contract_must_name_covered_guidance_and_escalation_rules
-    skip:
+    prime_context:
       meaning: >-
-        No first-invocation instruction read is required for the declared scope.
-      obligation: requires_explicit_contract_justification
-      caution: >-
-        Reserved for narrow future surfaces; not a default and not implemented by
-        this authority.
-  default_rule: full
+        The first capability invocation must shell out to
+        `npx -y agentera@next prime --context <name> --format json` and read the
+        returned `instructions` field (the full Markdown body) before executing
+        capability-specific work.
+      obligation: shell out to npx -y agentera@next prime --context <name> --format json
+  default_rule: prime_context
   full_read_obligation: >-
-    On initial capability invocation, read `instructions.md` in full unless that
-    capability declares a compact-startup exception with explicit coverage and
-    escalation boundaries.
-compact_startup_exception:
-  status: implemented_for_planera_compact_startup_discoverability
-  allowed_when:
-    - A machine-readable startup contract is available through supported state access.
-    - The compact contract states which instruction topics it covers.
-    - The compact contract states when the agent must escalate to a full instruction-file read.
-    - The compact contract preserves unsupported-command and raw-artifact-read boundaries.
-  not_allowed_when:
-    - The agent is editing the capability's own instructions or schemas.
-    - The compact contract is missing, incomplete, stale, or contradictory.
-    - The requested work touches behavior not covered by the compact contract.
-    - Safety rails, validation, exit semantics, or cross-capability boundaries are ambiguous.
+    On initial capability invocation, shell out to
+    `npx -y agentera@next prime --context <name> --format json` and read the
+    `capability_context.instructions` field in full.
 implementation_state:
-  instructions_md_files: renamed
-  validators_require_instructions_md: true
+  instructions_ts_modules: implemented
+  validators_require_instructions_ts: true
   first_invocation_read_cli_metadata: true
   first_invocation_read_schema_metadata: true
-  runtime_first_invocation_behavior: false
-  descriptors_rewritten_to_instructions_md: true
-  package_metadata_rewritten_to_instructions_md: true
+  runtime_first_invocation_behavior: true
 compatibility_preservation:
   preserve_legacy_references_only_when_classified:
-    - skills/agentera/capabilities/*/instructions.md paths
+    - skills/agentera/capabilities/*/instructions.md paths (historical)
+    - packages/cli/src/capabilities/*/instructions.ts paths (current canonical)
     - skills/agentera/capability_schema_contract.yaml directory requirements
-    - runtime descriptors and generated agent guidance that point to `instructions.md`
+    - runtime descriptors and generated agent guidance that point to `instructions.md` (retired)
     - archived v1/v2 migration records and progress evidence
     - compatibility fixtures and tests that intentionally preserve old behavior evidence
     - README, AGENTS, and vocabulary references that explicitly describe the current canonical state
@@ -114,8 +109,51 @@ surface_inventory:
   docs_vocabulary: delegates_to_this_authority
   readme: concise_user_facing_current_and_future_authoring_seam
   capability_schema_contract: current_canonical_validator_reference
-  runtime_descriptors: current_canonical_instructions_md_pointers
   capability_instruction_files: current_canonical_instruction_files
+evaluator_handoff:
+  status: implemented
+  purpose: >-
+    Define the inspektera evaluation report schema and citation requirements
+    for orkestrera Step 3 Surface 2 delegations and post-plan health checks.
+  report_schema_version: agentera.inspekteraEvaluationReport.v1
+  row_schema:
+    required_fields:
+      - criterion
+      - status
+      - evidence
+    status_values:
+      - PASS
+      - WARN
+      - FAIL
+    citation_required_for:
+      - WARN
+      - FAIL
+    citation_formats:
+      file_line:
+        pattern: "^[^:\\s]+:\\d+$"
+        description: Relative repo path with 1-based line number, e.g. TODO.md:15
+      not_applicable:
+        prefix: "not-applicable:"
+        min_reason_length: 8
+        description: >-
+          Use when no file anchor exists; prefix with not-applicable: and give a
+          concrete reason (at least 8 characters after the prefix).
+    warn_verify_command:
+      required_when: file_line_citation
+      allowed_prefixes:
+        - grep
+        - git show
+      description: >-
+        WARN rows with a file:line citation MUST include verify_command with the
+        exact grep or git show invocation that reproduces the evidence at the
+        cited line.
+  orchestration_context_fields:
+    output_requirements:
+      citation_required_for:
+        - WARN
+        - FAIL
+      warn_verify_command_required: true
+      schema_authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff
 docs_delegation:
   document: references/cli/vocabulary.md
   required_anchor: Capability instruction contract