agentera 3.0.0-dev.5 → 3.0.0-dev.7

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

@@ -0,0 +1,45 @@
+# Upgrade repair wording — v3 cursor agent skip
+
+When `agentera upgrade --runtime cursor` (or a full runtime phase) runs against a
+**project** directory, managed `.cursor/agents/*.md` descriptors are normally
+copied from the active app-home bundle. On a **v3 capability-surface** project
+that signal is suppressed so D65 `prime --context` bodies are not regressed to
+the retired `instructions.md` read path.
+
+## v3 surface probe
+
+Treat the project as v3 when **all twelve** instruction modules exist:
+
+`packages/cli/src/capabilities/<name>/instructions.ts`
+
+for every routed capability (`status`, `vision`, `discuss`, `research`,
+`plan`, `build`, `optimize`, `audit`, `document`, `profile`,
+`design`, `orchestrate`).
+
+If any module is missing, preserve v2 upgrade behavior (copy/refresh managed
+agents from the bundle).
+
+## Orchestrator behavior
+
+| Orchestrator | Branch | Behavior |
+| --- | --- | --- |
+| TypeScript (`packages/cli/src/upgrade/runtimeMigration.ts`) | `feat/v3` | On v3 probe match, emit `skipped` `copy-agent` items for in-tree `.cursor/agents/` instead of copying from the bundle. |
+| Python (`scripts/agentera_upgrade.py`) | `main` (stable) | Same probe before the cursor agent copy loop; do not schedule `copy-agent` targets under the project when the probe matches. Backport per the both-branch pattern. |
+
+## User-visible skip message
+
+`v3 capability instruction modules present; in-tree .cursor/agents/ uses prime --context and is not overwritten`
+
+## 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

@@ -0,0 +1,98 @@
+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: >-
+      Runtime adapter ids (references/adapters/runtime-adapter-registry.yaml)
+      that the v2 install actively uses — runtimes whose setup doctor status is
+      pass at write time.
+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/cli/vocabulary-index.yaml

@@ -26,17 +26,20 @@ authority_order:
   - DESIGN.md
   - .agentera/
 normalization_rules:
-  - rule: Internal workflows are capabilities.
-    use: capability, twelve capabilities, capability prose, capability schemas
-    avoid: Calling hej/realisera/etc. standalone skills, except in v1 history.
-  - rule: The runtime surface is a skill.
-    use: Agentera skill, single installed Agentera app
-    avoid: twelve-skill suite for v2 behavior.
+  - rule: Agentera is one agent, not a team; workflows are capabilities.
+    use: capability, twelve capabilities, one agent with many capabilities, capability prose, capability schemas
+    avoid: Calling status/build/etc. standalone skills or agents; "engineering team" as a product word; except in v1 history.
+  - rule: The runtime install is internal transport, not a product surface.
+    use: single Agentera agent, capabilities (the product word); "skill" and "plugin" survive only as internal transport (the skills/ directory and plugin.json manifests host editors require)
+    avoid: '"Agentera skill" or "plugin" as product words; "twelve-skill suite" or "plugin suite" for the capability set.'
+  - rule: Agentera is the agent; the host is the harness (Decision 74).
+    use: host runtime, harness, host coding agent (Claude, Cursor, Codex, Copilot, OpenCode); the CLI owns routing, memory, capability prose, and the worker-spec contract
+    avoid: Calling host coding agents peers or extension hosts of Agentera; implying Agentera is a module loaded into the host.
   - rule: /agentera is the main invocation.
     use: /agentera, $agentera for Codex-specific docs
     avoid: /hej except as a legacy bridge.
   - rule: The CLI source and rendered dashboard are different.
-    use: agentera hej source data, Hej dashboard rendered briefing
+    use: agentera prime source data, status dashboard rendered briefing
     avoid: Treating raw CLI labels as the user-facing dashboard.
   - rule: Routine state uses flat commands.
     use: agentera plan, agentera docs, agentera health
@@ -64,7 +67,7 @@ normalization_rules:
     avoid: Non-Git checkpoint or pre-dispatch commit gate in new docs.
   - rule: Capability instruction modules have current metadata and a runtime boundary.
     use: instructions.ts plus emitted prime_context first_invocation_read; runtime enforcement is true via the CLI prime command
-    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera planera commands.
+    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera plan commands.
 plain_language:
   lead_with_plain_phrase:
     - use: final state sync, the plan-level freshness checkpoint
@@ -150,10 +153,12 @@ decision_44:
       boundary: Preserve capability IDs, artifact IDs, group IDs, route IDs, and test fixture IDs unless a migration is planned.
     - surface: CLI labels and exit behavior
       boundary: Preserve current command names, parseable labels, exit codes, and source-contract labels unless an explicit CLI migration is recorded.
-    - surface: Canonical capability names
-      boundary: Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera.
-    - surface: Decision 43 aliases
-      boundary: Preserve /agentera status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, and orchestrate.
+    - surface: Canonical capability names (v3 surface)
+      boundary: >-
+        Preserve the Decision 43 English alias set as the binding canonical names for v3 and onward under the single-agent identity (Decision 74): status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate. Future capability additions follow the same transfer-friendly English-verb pattern (Decision 70). Per Decisions 70 and 74, the D43 alias set is the binding name set under one agent, one CLI, many capabilities; future renames require a new decision.
+    - surface: Legacy Swedish capability names (v2 stable only)
+      boundary: >-
+        Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera for the v2 stable distribution (`npx -y agentera@latest`, ships from `main`) and as historical references in archived plans, decisions, and changelogs. Out of scope for v3 surface per Decisions 70 and 74; the single-agent identity uses English capability names exclusively. Coexistence probe surfaces per-distribution naming divergence.
     - surface: Historical artifacts
       boundary: Do not rewrite old progress, changelog, archived plans, or decisions solely for vocabulary cleanup.
     - surface: Release version