agentera 3.0.0-dev.14 → 3.0.0-dev.16

package/bundle/UPGRADE.md

@@ -0,0 +1,188 @@
+# Upgrade and runtime lifecycle
+
+Agentera 3.0 uses one upgrade command for project/app migration and explicitly
+selected runtime lifecycle work. Preview and apply are separate operations.
+
+Before the npm stable dist-tag promotion, use `agentera@next`. The stable 2.x
+channel remains `agentera@latest` until that promotion; this repository does
+not publish or retag as part of an upgrade run.
+
+## Start with a preview
+
+```bash
+npx -y agentera@next upgrade --dry-run
+```
+
+Without `--runtime`, upgrade handles only applicable project/app migration.
+Runtime lifecycle repair is opt-in:
+
+```bash
+npx -y agentera@next upgrade --runtime all --dry-run
+npx -y agentera@next upgrade --runtime cursor --dry-run
+```
+
+The active runtimes are OpenCode, Codex, Cursor, and GitHub Copilot. Selectors
+are `all`, `opencode`, `codex`, `cursor`, and `copilot`.
+`cursor-agent` is not a selector: Cursor Agent CLI and Cursor IDE are surfaces
+of the one `cursor` identity. CLI is required; IDE is conditional.
+
+The preview is strictly read-only. It creates no files, directories, locks,
+caches, ownership journals, telemetry, or other state changes. Its output
+includes:
+
+- observed runtime and surface evidence;
+- skill, plugin, hook, agent, configuration, enablement, trust, and native-action state;
+- planned operations and dependencies;
+- current ownership evidence and blocked reasons;
+- exact manual or host-native actions;
+- required support-floor gaps.
+
+`prime` exposes a bounded projection of the same snapshot. `doctor` exposes the
+detailed read-only diagnosis:
+
+```bash
+npx -y agentera@next prime --format json
+npx -y agentera@next doctor --format json
+```
+
+## Apply approved Agentera-owned work
+
+After reviewing the preview, rerun the same selection with `--yes`:
+
+```bash
+npx -y agentera@next upgrade --runtime all --yes
+```
+
+Apply can write only resources declared by the lifecycle contract and proven
+Agentera-owned by the append-only ownership journal. Matching names or bytes do
+not establish ownership. User-owned, ambiguous, shadowed, or malformed targets
+remain blocked.
+
+The operation outcomes are:
+
+- `applied` — the declared change was published;
+- `noop` — desired state was already exact;
+- `failed` — this operation failed; independent operations may continue;
+- `blocked_unowned` — ownership was not proven;
+- `skipped_dependency` — a prerequisite did not complete;
+- `action_required` — the user or host must perform the step.
+
+Retries are designed to converge. Completed work becomes `noop`; failed or
+pending work is re-observed and retried. Corrupt, forked, disconnected, or
+non-contiguous ownership journals fail closed.
+
+Secure automatic filesystem publication currently requires Linux
+`/proc/self/fd`. On macOS, Windows, or a Linux environment without that secure
+primitive, preview and diagnosis still work but mutation is returned as
+`action_required`.
+
+## Ownership and trust boundary
+
+The canonical skill is:
+
+```text
+~/.agents/skills/agentera
+```
+
+Agentera can maintain declared Agentera-owned skill, plugin, hook, and agent
+resources. It does not run native runtime package managers or approve:
+
+- runtime installation or self-update;
+- authentication;
+- plugin or hook enablement;
+- trust prompts or organizational policy;
+- user-owned configuration collisions.
+
+Those steps are reported with exact remediation and remain user-owned.
+
+## Cursor lifecycle
+
+Cursor is one runtime identity with two surfaces:
+
+| Surface | Support-floor role | Typical source |
+| --- | --- | --- |
+| Agent CLI | required | Cursor CLI binary and canonical shared skill |
+| IDE | conditional | `.cursor-plugin/plugin.json`, `.cursor/hooks.json`, `.cursor/agents/` |
+
+An absent IDE does not block a CLI-only installation. Once IDE evidence is
+present, its incomplete or denied mandatory evidence is reported beneath the
+same Cursor identity.
+
+## Retired Claude cleanup
+
+Claude Code is not an active Agentera runtime and cannot be passed to
+`--runtime`. Its legacy cleanup is a separate explicit selection:
+
+```bash
+npx -y agentera@next upgrade --legacy-cleanup claude --dry-run
+npx -y agentera@next upgrade --legacy-cleanup claude --yes
+```
+
+Cleanup is limited to the exact Agentera-owned legacy skill link recorded by
+the ownership ledger. It never removes Claude projects, transcripts, settings,
+credentials, caches, or other user data. Ambiguous or unowned resources remain
+blocked.
+
+Historical transcript import is independent of cleanup. Default extraction and
+analytics do not read Claude history. Import requires explicit local consent:
+
+```bash
+npx -y agentera@next report refresh --import-source claude
+```
+
+Imported records carry `historical_import` provenance, have no active runtime
+ID, and remain excluded from default active-runtime analytics.
+
+## v2 to v3 project migration
+
+Use the development channel explicitly while 3.0 is on `@next`:
+
+```bash
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+```
+
+The preview reports artifact migration, app migration, legacy cleanup, and any
+explicitly selected runtime work as separate phases. It does not cross the
+major boundary or mutate the project without `--yes`.
+
+Useful phase filters are repeatable:
+
+```bash
+npx -y agentera@next upgrade --only artifacts --dry-run
+npx -y agentera@next upgrade --only runtime --dry-run
+npx -y agentera@next upgrade --only cleanup --dry-run
+```
+
+## Verification and recovery
+
+After apply:
+
+```bash
+npx -y agentera@next doctor --format json
+npx -y agentera@next prime --format json
+```
+
+`upgrade --verify` adds doctor and capability-schema checks to an upgrade run.
+`upgrade --restore` restores the latest supported app-migration snapshot; it
+does not bypass lifecycle ownership or trust checks. For lifecycle partial
+failure, rerun the same preview and apply selection. Do not delete or hand-edit
+the ownership journal to force adoption.
+
+`--force` applies only where the owning migration contract explicitly permits
+replacement. It does not convert user-owned resources into Agentera-owned
+resources and does not approve native or trust actions.
+
+## Maintainer verification
+
+Release preparation does not publish, tag, or push:
+
+```bash
+pnpm -C packages/cli test
+pnpm -C packages/cli run typecheck
+pnpm -C packages/cli build
+node packages/cli/dist/bin/agentera.js check validate lifecycle-adapters
+node packages/cli/dist/bin/agentera.js check validate release-metadata
+pnpm -C packages/cli run bundle:data
+npm pack --dry-run --json --ignore-scripts
+```

package/bundle/agents/openai.yaml

@@ -0,0 +1,87 @@
+display_name: Agentera
+description: Portable Agentera suite for Codex: one bundled skill with exact bare `/agentera` routing and twelve routed capabilities.
+icon: AG
+brand_color: "#111827"
+default_prompt: Use $agentera to inspect project state and route to the right capability; exact bare `/agentera` uses the agentera prime dashboard path.
+policy:
+  allow_implicit_invocation: true
+support:
+  skill_discovery: /skills
+  plugin_discovery: /plugins
+  explicit_invocation: $agentera
+  implicit_invocation: the bundled skill may be invoked implicitly; exact bare `/agentera` belongs to agentera, not the legacy hej bridge
+  lifecycle_hooks: stable via codex_hooks; bundled config lives at hooks/codex-hooks.json and can be copied to ~/.codex/hooks.json or a project .codex/hooks.json for apply_patch artifact validation
+skills:
+  - name: agentera
+    display_name: agentera
+    path: ./skills/agentera
+    metadata: ./agents/openai.yaml
+    description: Compound agent orchestration suite with exact bare `/agentera` routing and twelve capabilities in one bundled skill.
+    invocation_hint: Use $agentera, or inspect it with /skills and /plugins. For a complete bare `/agentera` message, use the agentera prime dashboard path.
+    policy:
+      allow_implicit_invocation: true
+    capabilities:
+      - name: status
+        description: Entry-point orientation and routing for fresh or returning projects, including a complete user message exactly `/agentera`.
+        invocation_hint: Use $agentera status or ask $agentera for project status; exact bare `/agentera` uses this dashboard path.
+        policy:
+          allow_implicit_invocation: true
+      - name: research
+        description: External-source analysis mapped onto a project through Agentera artifacts.
+        invocation_hint: Use $agentera research for links or external source analysis.
+        policy:
+          allow_implicit_invocation: true
+      - name: profile
+        description: Decision-profile mining. Limited to available bounded Codex history, session, or config corpus data.
+        invocation_hint: Use $agentera profile when bounded Codex history, session, or config corpus data is available.
+        policy:
+          allow_implicit_invocation: false
+        required_capabilities:
+          - name: codex_session_corpus
+            status: ok
+            action: Run profile extraction; bounded Codex history, session, or config corpus data lands in the Section 22 corpus when present, with absent source families reported in corpus metadata.
+      - name: build
+        description: Autonomous development cycles grounded in project vision, TODO, and verification.
+        invocation_hint: Use $agentera build for autonomous development cycles.
+        policy:
+          allow_implicit_invocation: true
+      - name: optimize
+        description: Metric-driven optimization loops for measurable objectives.
+        invocation_hint: Use $agentera optimize for measured optimization work.
+        policy:
+          allow_implicit_invocation: true
+      - name: discuss
+        description: Structured deliberation for consequential decisions and tradeoffs.
+        invocation_hint: Use $agentera discuss for decision framing.
+        policy:
+          allow_implicit_invocation: true
+      - name: audit
+        description: Codebase health audits with severity, confidence, and trend tracking.
+        invocation_hint: Use $agentera audit for codebase health audits.
+        policy:
+          allow_implicit_invocation: true
+      - name: plan
+        description: Scale-adaptive planning with behavioral acceptance criteria.
+        invocation_hint: Use $agentera plan for multi-step planning.
+        policy:
+          allow_implicit_invocation: true
+      - name: vision
+        description: Project vision creation and refinement.
+        invocation_hint: Use $agentera vision for project direction work.
+        policy:
+          allow_implicit_invocation: true
+      - name: document
+        description: DTC-first documentation creation, maintenance, and audit.
+        invocation_hint: Use $agentera document for documentation work.
+        policy:
+          allow_implicit_invocation: true
+      - name: design
+        description: Visual identity system creation, refinement, and audit.
+        invocation_hint: Use $agentera design for design system work.
+        policy:
+          allow_implicit_invocation: true
+      - name: orchestrate
+        description: Plan-driven orchestration that dispatches capabilities and evaluates results.
+        invocation_hint: Use $agentera orchestrate for plan execution.
+        policy:
+          allow_implicit_invocation: true

package/bundle/extract-corpus-parity.json

@@ -1,17 +1,15 @@
 {
   "schema_version": "agentera-extract-corpus-parity-v1",
-  "adapter_version": "agentera-v2-corpus-1",
+  "adapter_version": "agentera-v3-corpus-2",
   "max_sqlite_sessions": 60,
   "max_sqlite_rows": 100000,
   "max_tool_arg_text": 500,
   "copilot_sparse_remediation": "/chronicle reindex",
   "runtime_store_globs": {
     "codex": "*.jsonl",
-    "claude-code": "*.jsonl",
     "cursor": "*.jsonl",
-    "cursor-agent": "store.db",
     "opencode": "opencode.db",
-    "github-copilot": "session-store.db"
+    "copilot": "session-store.db"
   },
   "families": [
     "instruction_document",

package/bundle/hooks/codex-hooks.json

@@ -0,0 +1,31 @@
+{
+  "description": "agentera v3 Codex CLI hooks (PascalCase lifecycle events PreToolUse, PostToolUse): schema-backed apply_patch artifact validation; copied to ~/.codex/hooks/codex-hooks.json by upgrade",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^apply_patch$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y agentera@next hook validate-artifact",
+            "timeout": 10,
+            "statusMessage": "validating artifact"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^apply_patch$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y agentera@next hook validate-artifact",
+            "timeout": 10,
+            "statusMessage": "validating artifact"
+          }
+        ]
+      }
+    ]
+  }
+}

package/bundle/hooks/codex-plugin-hooks.json

@@ -0,0 +1,31 @@
+{
+  "description": "agentera v3 Codex plugin hooks (PascalCase lifecycle events PreToolUse, PostToolUse): schema-backed apply_patch artifact validation bundled via .codex-plugin/plugin.json using PLUGIN_ROOT",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^apply_patch$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y agentera@next hook validate-artifact",
+            "timeout": 10,
+            "statusMessage": "validating artifact"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^apply_patch$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y agentera@next hook validate-artifact",
+            "timeout": 10,
+            "statusMessage": "validating artifact"
+          }
+        ]
+      }
+    ]
+  }
+}

package/bundle/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "agentera",
+  "version": "3.0.0",
+  "description": "Agentera 3.0.0 for GitHub Copilot CLI: one portable skill, twelve capabilities, shared project state, lifecycle hooks, and exact /agentera dashboard routing. profile uses bounded Copilot corpus metadata when present and reports missing source families. Runtime installation, enablement, authentication, and trust remain user-owned.",
+  "skills": "skills",
+  "hooks": ".github/hooks",
+  "agentera": {
+    "packageShape": "suite-bundle",
+    "installRoot": ".",
+    "sharedPaths": ["skills", "hooks", "registry.json", "plugin.json", "README.md", "UPGRADE.md"],
+    "singleSkillInstall": "Single-skill installs keep core SKILL.md workflow behavior; suite tools are bundle-only enhancements."
+  }
+}

package/bundle/references/adapters/cursor.md

@@ -1,14 +1,12 @@
 # Cursor adapter reference
 
-Agentera v1 ships Cursor as two registry identities:
+Agentera ships one active Cursor registry identity: `cursor`. The accepted
+`cursor-agent` spelling is an inactive compatibility alias that resolves to
+Cursor-owned behavior and source data; it is not independently discoverable.
 
-| Identity | Host | Support status |
-| -------- | ---- | -------------- |
-| `cursor` | Cursor IDE (Composer / Agent) | supported |
-| `cursor-agent` | Cursor Agent CLI (`cursor-agent`, `agent`) | degraded |
-
-Decision 63 owns v1 scope. Cloud agents are unsupported. Bare text `hej` routing
-stays metadata-only like Claude, Copilot, and Codex.
+Cursor Agent CLI is the required lifecycle surface and Cursor IDE is
+conditional. Cloud agents are unsupported. Bare prompt routing remains
+metadata-only like GitHub Copilot and Codex.
 
 ## Quick install
 
@@ -32,16 +30,16 @@ and project walk-up do not resolve a managed root).
 
 ```bash
 npx skills add jgabor/agentera -g -a cursor --skill agentera -y
-uvx --from git+https://github.com/jgabor/agentera agentera upgrade --project "$PWD" --runtime cursor --yes
-uvx --from git+https://github.com/jgabor/agentera agentera doctor --runtime cursor
+npx -y agentera@next upgrade --project "$PWD" --runtime cursor --dry-run
+npx -y agentera@next upgrade --project "$PWD" --runtime cursor --yes
+npx -y agentera@next doctor --format json
 ```
 
 Use the plugin path for a user-global install. Use upgrade when you need
 project-committed `.cursor/hooks.json` and `.cursor/agents/` copies. Both paths can
 be combined.
 
-From a clone, replace `uvx … agentera` with `uv run scripts/agentera`. User-facing
-install steps also live in [`README.md`](../../README.md) and
+User-facing install steps also live in [`README.md`](../../README.md) and
 [`UPGRADE.md`](../../UPGRADE.md).
 
 ## Repo-native surfaces
@@ -52,18 +50,21 @@ This repository dogfoods committed Cursor surfaces:
 - `.cursor/agents/agentera.md` — single managed agent descriptor (D73)
 - `.cursor-plugin/plugin.json` — marketplace submission-ready manifest
 
-Hooks invoke the TypeScript CLI through `npx -y agentera hook …` (or
-`npx -y agentera@next hook …` on the development channel). `sessionStart` exports
-`AGENTERA_HOME` through Cursor hook JSON (`env`) before subsequent hook executions
-run.
+Install and repair these Cursor IDE resources through the public lifecycle command
+`agentera upgrade --runtime cursor`: use `--dry-run` to preview and `--yes` to
+apply Agentera-owned operations. The installed hook file calls private lifecycle
+callbacks packaged with the CLI; those callbacks are runtime wiring, not a
+user-facing command namespace, and are intentionally absent from public CLI help.
+The managed `sessionStart` callback exports `AGENTERA_HOME` through Cursor hook JSON
+(`env`) before subsequent callbacks run.
 
 ## AGENTERA_HOME wiring
 
-Primary path: `agentera hook cursor-session-start` resolves the install root from
-`AGENTERA_HOME`, project walk-up, the plugin/checkout root, or the platform default
-app home when env and walk-up do not resolve a managed root, then returns
-`{"env": {"AGENTERA_HOME": "<root>"}}` plus optional `additional_context` from
-the shared session digest.
+Primary path: the managed Cursor IDE `sessionStart` callback resolves the install
+root from `AGENTERA_HOME`, project walk-up, the plugin/checkout root, or the
+platform default app home when env and walk-up do not resolve a managed root,
+then returns `{"env": {"AGENTERA_HOME": "<root>"}}` plus optional
+`additional_context` from the shared session digest.
 
 Fallback: `packages/cli/src/setup/cursor.ts` reports persistent shell configuration
 only when live shell-tool smoke proves session env does not propagate to CLI
@@ -74,7 +75,7 @@ subprocesses. Agentera does not write shell rc files by default.
 | Surface | Behavior | Claim status |
 | ------- | -------- | ------------ |
 | IDE `preToolUse` (Write/Edit) | Deny invalid reconstructable artifact candidates | Verified after live preToolUse Write smoke (2026-05-24) |
-| IDE `postToolUse` (Write/Edit) | Advisory validation through shared `validate_artifact.py` | Active |
+| IDE `postToolUse` (Write/Edit) | Advisory validation through the managed artifact-validation callback | Active |
 | CLI | Degraded; depends on workspace hook install and env propagation | Follows IDE smoke evidence only |
 
 Live preToolUse Write smoke passed on 2026-05-24 with invalid-block and valid-allow
@@ -89,36 +90,42 @@ IDE: managed descriptors under `.cursor/agents/` with `<!-- agentera: managed --
 ownership markers. Upgrade refreshes Agentera-owned targets and preserves unknown
 collisions.
 
-CLI: host-managed `cursor-agent` print mode; no separate TOML descriptor install.
-Eval coverage targets `cursor-agent` first.
+CLI: host-managed `cursor-agent` print mode through the inactive Cursor alias;
+there is no separate descriptor install. Eval coverage may accept the alias but
+must report the canonical runtime identity as `cursor`.
 
 ## Upgrade and doctor
 
 ```bash
-uv run scripts/agentera upgrade --runtime cursor --dry-run
-uv run scripts/agentera doctor --runtime cursor
+npx -y agentera@next upgrade --project "$PWD" --runtime cursor --dry-run
+npx -y agentera@next upgrade --project "$PWD" --runtime cursor --yes
+npx -y agentera@next doctor --format json
 ```
 
-Upgrade copies managed hooks, agents, and plugin metadata into target projects
-with the same ownership protections used for OpenCode and Codex.
+Upgrade treats Cursor Agent CLI and Cursor IDE as surfaces of one `cursor` runtime.
+It manages the shared canonical skill used by both surfaces and, for the
+conditional IDE surface, project hooks, the Agentera descriptor, and plugin
+metadata. The shared lifecycle engine creates or repairs only Agentera-owned
+resources and preserves unowned collisions.
 
-Doctor reports helper access, hook presence, and managed agent alignment.
+Doctor reports all active runtimes in one read-only lifecycle snapshot, including
+Cursor CLI and IDE evidence; it does not accept a Cursor-only runtime filter.
 
 ## Eval
 
 ```bash
-uv run scripts/eval_skills.py --runtime cursor-agent --skill hej --dry-run
+agentera check verify eval skills --runtime cursor --skill agentera --dry-run
 ```
 
 Print mode uses `cursor-agent -p --output-format json --force`. Harnesses apply
 bounded timeouts because some CLI builds hang after completion.
 
-## Unsupported in v1
+## Current limitations
 
 - Cloud agents (no project hook or managed-agent guarantees)
-- Bare `hej` prompt rewrite routing
+- Bare prompt rewrite routing
 - Session compaction injection beyond shared hook helpers
-- Separate cursor-agent hook install distinct from IDE workspace surfaces
+- No separate Cursor Agent CLI hook install distinct from Cursor workspace surfaces
 
 ## Profilera session corpus (Section 22)
 
@@ -135,8 +142,9 @@ maps each record type to Cursor IDE local storage on disk.
 | `~/.config/cursor/chats/<md5(project-path)>/<session-id>/store.db` | Cursor Agent CLI chat store (gap-fill when JSONL absent) |
 
 Override the projects root with `--cursor-projects-dir`, the CLI chats root with
-`--cursor-chats-dir`, or disable both Cursor runtimes with `--no-cursor` on
-`scripts/extract_corpus.py` and `agentera stats refresh`.
+`--cursor-chats-dir`, or disable both Cursor source stores with `--no-cursor` on
+`agentera report refresh`. The Python extractor wrapper is a maintainer-only parity
+surface, not the user-facing command.
 
 Project slug convention: absolute project path segments joined with `-`, lowercased
 (for example `/home/user/git/agentera` → `home-user-git-agentera`). CLI workspace
@@ -156,9 +164,9 @@ Each line is a JSON object:
 Roles are `user` or `assistant`. `message.content` is a list of blocks. Text blocks
 use `type: "text"`. Tool blocks use `type: "tool_use"` with `name` and `input`.
 
-### Cursor Agent CLI `store.db` shape
+### Cursor source-product `store.db` shape
 
-Runtime id `cursor-agent` reads SQLite stores at
+The inactive `cursor-agent` input alias reads Cursor-owned SQLite stores at
 `~/.config/cursor/chats/<workspace-hash>/<session-id>/store.db`. Each store has:
 
 | Table | Purpose |
@@ -209,6 +217,8 @@ appear in errors, smoke output, or test assertions.
 
 ## Source of truth
 
-RuntimeAdapter records live in
-`references/adapters/runtime-adapter-registry.yaml`. Parity comparisons belong in
-`references/adapters/runtime-feature-parity.md`.
+Runtime identity and surfaces live in
+`references/adapters/runtime-lifecycle-authority.yaml`; eight-category behavior
+lives in `references/adapters/runtime-lifecycle-adapters.yaml`. Host-event facts
+remain in `references/adapters/runtime-adapter-registry.yaml`, and parity
+comparisons belong in `references/adapters/runtime-feature-parity.md`.