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

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

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

package/bundle/references/cli/single-name-protocol.yaml

@@ -1,42 +0,0 @@
-schema_version: agentera.single_name_protocol.v1
-status: active_authority
-decision: 58
-purpose: >-
-  Machine-readable Decision 58 boundary: forbidden legacy protocol identifiers
-  and scan surfaces for the single-name protocol regression test.
-human_index:
-  document: references/cli/vocabulary.md
-forbidden_protocol_substrings:
-  - pattern: instruction_file
-    rationale: D65 renamed DIRECTORY_REQUIREMENTS and contract fields to instruction_module.
-  - pattern: canonical_instruction_file
-    rationale: Use canonical_instruction_module in capability-instruction-contract.yaml.
-  - pattern: legacy_instruction_file
-    rationale: Historical paths belong in archive or migration modules only.
-  - pattern: instructionPath
-    rationale: capabilityContract loader exposes instructionModulePath only.
-forbidden_storage_protocol_markdown_artifacts:
-  - PROGRESS.md
-  - PLAN.md
-  - DECISIONS.md
-  - VISION.md
-  - HEALTH.md
-  - DOCS.md
-  - OBJECTIVE.md
-  - EXPERIMENTS.md
-scan_roots:
-  - packages/cli/src
-  - skills/agentera/capability_schema_contract.yaml
-  - skills/agentera/protocol.yaml
-  - references/cli/capability-instruction-contract.yaml
-  - references/cli/vocabulary.md
-  - references/cli/vocabulary-index.yaml
-  - registry.json
-scan_exclude_globs:
-  - "**/capabilities/**/instructions.ts"
-  - "**/migrateArtifactsV1ToV2.ts"
-  - "**/migrateArtifactsV2ToV3.ts"
-  - "**/migrateArtifacts*.ts"
-  - "**/*.test.ts"
-  - "**/test/**"
-comment_line_exempt: true

package/bundle/references/cli/upgrade-repair-wording.md

@@ -1,25 +0,0 @@
-# Upgrade repair wording
-
-## Runtime migration boundary
-
-Recognized v2-to-v3 project migration rewires existing Agentera v2 hook
-configurations to the npm CLI and retires only proven Agentera-owned legacy hook
-files. It does not copy or refresh plugins, agents, commands, or skill links.
-
-Runtime lifecycle installation and remediation are separate. Apply requires an
-explicit `--runtime` selector and `--yes`; declared ownership, collision
-remediation, and convergent retry behavior remain governed by `UPGRADE.md`.
-
-## v2 install track successor surfacing (#32)
-
-When a **v2-classified** managed app-home (`install_track: v2`) runs the **v3 TypeScript
-CLI** (`agentera doctor` / `agentera prime`), the next-major successor block must surface
-the stable-line forward successor (`3.0.0` on the development channel) with the preview
-command (`npx -y agentera@next upgrade --dry-run`) and the v2→v3 guide URL from
-`references/cli/update-channels.yaml`. A v2 install must not be silently reported as
-up to date against the v3 line.
-
-| Surface | Branch | Behavior |
-| --- | --- | --- |
-| TypeScript (`packages/cli/src/upgrade/nextMajorDoctor.ts`, doctor/prime wiring) | `feat/v3` | Resolve successor from `channels.stable.next_major` for v2 installs; omit the block for v3 npm installs and feat/v3 source checkouts. |
-| Python (`scripts/agentera_upgrade.py` doctor/prime writer) | `main` (stable) | Mirror the same v2-install successor block and preview command in stable-line doctor/prime output. Backport per the both-branch pattern; verify by round-trip parity with the v3 reader, not pytest in the feat/v3 worktree. |

package/bundle/references/cli/v3-handoff-manifest.schema.yaml

@@ -1,97 +0,0 @@
-schema_version: agentera.v3_handoff_manifest.v1
-status: active_authority
-purpose: >-
-  Contract for the v2→v3 handoff manifest written by the stable Python CLI at the
-  app-home root and read by the v3 TypeScript migration preflight. The manifest
-  lets v3 migration classify preserved user state in O(1) time instead of
-  scanning the entire app home.
-manifest_file: v3-handoff.json
-manifest_path: >-
-  {app_home}/v3-handoff.json where app_home is the platform data-home install
-  root (for example ~/.local/share/agentera on Linux).
-writers:
-  - v2 stable Python CLI on install, upgrade apply, and doctor (refresh when stale)
-readers:
-  - v3 TypeScript migration preflight in packages/cli/src/migrate/v2HandoffManifest.ts
-performance:
-  reader_preflight_budget_ms: 100
-  note: >-
-    When the manifest is present and valid, the v3 reader must complete parsing
-    and validation within 100ms. When absent or invalid, the reader may fall
-    back to a full app-home scan with no time budget.
-required_top_level_fields:
-  schema_version:
-    type: string
-    const: agentera.v3_handoff_manifest.v1
-  written_at:
-    type: string
-    format: iso8601_utc
-    description: UTC timestamp when the manifest was last written.
-  installed_v2_version:
-    type: string
-    min_length: 1
-    description: Installed Agentera suite version from the active v2 bundle marker.
-  app_home_path:
-    type: string
-    min_length: 1
-    description: Absolute resolved app-home path the writer used.
-  user_data_inventory:
-    type: array
-    min_items: 6
-    description: >-
-      One entry per catalog id below. Entries for paths that do not exist on disk
-      set exists=false; writers still emit the full catalog so v3 preflight can
-      trust absence without rescanning.
-  runtime_adapters:
-    type: array
-    items:
-      type: string
-    description: >-
-      Historical runtime adapter ids that the v2 install actively used at handoff.
-      The v3 reader treats these as migration evidence, not active runtime inventory.
-user_data_inventory_catalog:
-  - id: benchmarks
-    relative_path: benchmarks
-    kind: directory
-  - id: intermediate
-    relative_path: intermediate
-    kind: directory
-  - id: sessions
-    relative_path: sessions
-    kind: directory
-  - id: history
-    relative_path: history
-    kind: directory
-  - id: corpus
-    relative_path: corpus
-    kind: directory
-  - id: profile_files
-    kind: profile_files
-    members:
-      - relative_path: PROFILE.md
-        kind: file
-      - relative_path: USAGE.md
-        kind: file
-user_data_inventory_entry_shapes:
-  directory:
-    required: [id, relative_path, kind, exists]
-    kind_const: directory
-  file:
-    required: [id, relative_path, kind, exists]
-    kind_const: file
-  profile_files:
-    required: [id, kind, members]
-    kind_const: profile_files
-    members:
-      required: [relative_path, kind, exists]
-      kind_const: file
-freshness:
-  writer_obligations:
-    - Refresh the manifest on every v2 upgrade apply.
-    - Refresh the manifest on v2 doctor when stale or missing (after warning).
-  stale_when_any:
-    - Manifest file missing.
-    - schema_version mismatch.
-    - app_home_path differs from the resolved install root.
-    - installed_v2_version differs from the active bundle marker version.
-    - written_at is older than the bundle marker mtime.

package/bundle/references/meta/documentation-inventory.md

@@ -1,50 +0,0 @@
-# Documentation and file inventory
-
-Maintainer inventory of repository documentation, workpapers, and legacy surfaces.
-Authoritative Agentera docs live under `references/`, `skills/agentera/`, and root
-guides — not under `docs/`.
-
-**Last reviewed:** 2026-06-05
-
-## Design docs under `docs/`
-
-| Path | Topic |
-| ---- | ----- |
-| `docs/packaging/v3-packaging.md` | v3 CLI npm distribution and verification-lane contract |
-
-## Authority stack
-
-| Layer | Location |
-| --- | --- |
-| Protocol | `skills/agentera/protocol.yaml` |
-| CLI vocabulary authorities | `references/cli/*.yaml` |
-| Vocabulary index (normalization, Decision 44) | `references/cli/vocabulary-index.yaml` |
-| Human vocabulary index | `references/cli/vocabulary.md` |
-| Benchmark contract | `references/analysis/startup-measurement-contract.yaml` |
-| Benchmark runbook | `references/analysis/benchmark.md` |
-| Verification ownership and execution policy | `references/analysis/verification-policy.yaml` |
-| State storage, path, API, compatibility, and output authority | `references/artifacts/state-storage-authority.yaml` |
-| JSON surface budgets | `scripts/json_output_surface_manifest.yaml` |
-| Project drafts | `docs/` (gitignored except `docs/README.md` and `docs/packaging/`) |
-
-## `docs/` policy
-
-`docs/` is for **non-authoritative** local notes only. Nothing under `docs/` ships
-in the Agentera app bundle.
-
-## Archived workpapers
-
-| Archive path | Former location |
-| --- | --- |
-| `.agentera/archive/d47-app-home-vocabulary-inventory.md` | `docs/d47-app-home-vocabulary-inventory.md` |
-| `.agentera/archive/d58-json-output-surface-inventory.md` | `docs/d58-json-output-surface-inventory.md` |
-| `.agentera/archive/d59-json-output-budget-proposal.md` | `docs/d59-json-output-budget-proposal.md` |
-| `.agentera/archive/d59-json-output-closeout-measurements.md` | `docs/d59-json-output-closeout-measurements.md` |
-| `.agentera/archive/gap-analysis-2026-05-05.md` | `.agentera/gap-analysis-2026-05-05.md` |
-
-Live JSON enforcement uses `scripts/json_output_surface_manifest.yaml` only.
-
-## Remaining cleanup (see TODO.md)
-
-- Replace live `SPEC.md` references in `UPGRADE.md`, hooks, adapter docs, `contract.md`
-- Refresh or drop assertions against pre-migration characterization snapshots