agentera 3.0.0-dev.4 → 3.0.0-dev.41

package/bundle/UPGRADE.md

@@ -0,0 +1,201 @@
+# Upgrade and migration
+
+Agentera 3.0 uses one upgrade command for app/project migration and explicit
+native Agentera resource cleanup. Preview and apply are separate operations.
+Current runtime installation and repair are not upgrade operations.
+
+Before the npm stable dist-tag promotion, use `agentera@next`. The stable 2.x
+channel remains `agentera@latest` until that promotion; upgrade does not publish
+or retag packages.
+
+## Active integration
+
+Agentera has one active integration contract:
+
+```text
+~/.agents/skills/agentera + agentera CLI
+```
+
+Normal `prime`, `doctor`, `schema`, help, and project-integration output reports
+that shared skill and CLI/app/project state. Normal `upgrade` has no
+current-runtime selector or native-resource operation set. It creates no current
+plugin, hook, agent, command, descriptor, or marketplace file and does not run
+runtime package managers, authentication, enablement, or trust operations.
+
+Passing `--runtime` fails before mutation. Remove `--runtime`, ensure the runtime
+can read `~/.agents/skills/agentera`, and invoke the CLI directly. The supported
+v2 migration and native Agentera resource cleanup routes below are separate from
+normal active integration.
+
+## Preview and apply
+
+Preview normal app/project work:
+
+```bash
+npx -y agentera@next upgrade --dry-run --channel development
+```
+
+The preview is strictly read-only: it creates no files, directories, locks,
+caches, ownership records, telemetry, or other state. Apply only after reviewing
+the generated command:
+
+```bash
+npx -y agentera@next upgrade --yes --channel development
+```
+
+`prime` and `doctor` expose the same app/project classification and shared-skill
+state:
+
+```bash
+npx -y agentera@next prime --format json
+npx -y agentera@next doctor --format json
+```
+
+Retries re-observe the current app/project state. Completed migration work
+converges to no change; interrupted v2 migration continues through the same full
+apply command.
+
+## Native Agentera resource cleanup
+
+Cleanup is a distinct resource route, not a host selection. Codex, Cursor,
+OpenCode, and Copilot remain supported through the canonical shared skill and
+CLI. Accepted smoke evidence records that Codex and Cursor loaded Agentera's
+skill instructions, OpenCode listed the canonical skill, and Copilot's listed
+canonical skill is intentionally disabled.
+
+Use `agentera upgrade --legacy-cleanup RESOURCE_ID --dry-run|--yes` with one
+declared native Agentera resource ID.
+
+```bash
+npx -y agentera@next upgrade --legacy-cleanup claude.agentera-skill-link --dry-run
+npx -y agentera@next upgrade --legacy-cleanup claude.agentera-skill-link --yes
+```
+
+The contract also inventories retired Codex descriptor files. Each file needs a
+matching whole-resource ledger identity and fingerprint before it can be
+removed. Codex descriptor previews report each shared configuration key as
+`action_required` without adding it to the selected resource's apply work.
+Agentera has no durable key-level ownership proof, so matching values, markers,
+names, or whole file contents never authorize a shared `config.toml` mutation.
+Preview is read-only; approved apply is idempotent and preserves ambiguous or
+unowned resources.
+
+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-source analytics.
+
+## Stable v2 line
+
+The stable `@latest` channel remains on the supported 2.x line. Preview before
+applying an in-line upgrade:
+
+```bash
+npx -y agentera@latest upgrade --dry-run
+npx -y agentera@latest upgrade --yes
+```
+
+Use the v3 development migration below only when you explicitly intend to leave
+the stable line.
+
+## Upgrading v2 to v3 development channel
+
+Recognized marker-absent v2 aggregate state has one supported forward route:
+
+```bash
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+```
+
+The optional preview is read-only. Before apply, commit or restore the complete
+v2 migration source: every input must be a regular file tracked by Git and
+unchanged at `HEAD`. Apply performs the full project rewiring and entity-state
+cutover, then validates state and representative `prime` startup. Rewiring may
+update recognized v2 project files; it does not install current native resources.
+
+Forward migration is one-way. Returning to the Python 2.x line is unsupported,
+and cross-major apply has no rollback, restore, non-Git, or partial workflow.
+If apply is interrupted, rerun the same full apply command.
+
+### Compacted v2 summaries
+
+Entity-cutover publication for valid v2 compaction output is implemented for
+`progress`, `decisions`, and `health`. Each valid summary becomes one immutable,
+read-only canonical
+`progress_summary`, `decision_summary`, or `health_summary` entity. The entity
+requires `summary`, preserves every source-retained field except forbidden
+identity aliases, and records the source path plus source-record SHA-256.
+
+Ordinary summary readers and startup projection are implemented. Reads report
+`detail_availability: summary`, `compatibility: degraded`, record-level source
+provenance, and applicable caveats; startup presents summary-only history as
+degraded history rather than current detail. Full records retain their existing
+temporal order; the degraded-summary segment follows in deterministic canonical-ID
+order and makes no chronology claim. Retained decision-summary satisfaction is
+inline and read-only, may be absent, and never creates a standalone satisfaction
+ target. Preview reports independent source roots separately from generated
+ relationship dependents: `root_blockers + dependent_blockers = blockers`, and
+ each dependent names its stable `root_source_identity`. A Git-backed regression
+ copies the supported `progress`, `decisions`, and `health` sources from pinned
+ v2.7.11 compaction output; its protected experiment evidence remains unchanged
+ and excluded. It verifies preview bindings and target hashes, marker-last
+ publication and interrupted exact-target retry, canonical validation, ordinary
+ list/get reads for retained full and summary entries, human/JSON prime, and
+ repeated no-change upgrade behavior while aggregate source hashes remain stable.
+Inherited full-decision `high`, `medium`, and `low` confidence remains readable
+with a legacy caveat; newly supplied or amended confidence remains strict.
+
+Protected objective experiments, runtime-local session state, and compacted TODO
+rows that already satisfy the canonical TODO shape are outside this summary
+scope. This contract does not reconstruct Git history, normalize source records,
+create dual authority, or add a repair or import command.
+
+## Unsupported legacy state
+
+Pending v1 Markdown state and unknown marker-absent state are not automatic
+mutation inputs. `state migrate`, `state backfill`, projection repair, v1
+conversion, restore, and downgrade are unsupported. The read-only
+`state migrate entities --dry-run` diagnostic may inventory cutover input but
+cannot publish it.
+
+## Verification and recovery
+
+After apply:
+
+```bash
+npx -y agentera@next doctor --format json
+npx -y agentera@next prime --format json
+```
+
+`upgrade --verify` without `--yes` is a read-only doctor and capability-context
+verification. With `--yes`, it runs those checks after approved migration.
+Explicit native Agentera resource cleanup with `--verify` requires `--yes`.
+
+`--force` applies only where the owning migration contract explicitly permits
+replacement. It never adopts user-owned resources.
+
+## 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 capability-contract --format json
+node packages/cli/dist/bin/agentera.js check validate release-metadata
+```
+
+## Mutation ownership
+
+Upgrade apply holds the required project lock before migration begins. Explicit
+native Agentera resource cleanup additionally uses its ownership journal and
+shared lock. Lock creation is atomic, and release succeeds only for the matching
+ownership token.
+A stale or malformed lock stops the operation; inspect the named lock file,
+remove only that file after confirming no operation owns it, then rerun.

package/bundle/extract-corpus-parity.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": "agentera-extract-corpus-parity-v1",
+  "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",
+    "cursor": "*.jsonl",
+    "opencode": "opencode.db",
+    "copilot": "session-store.db"
+  },
+  "families": [
+    "instruction_document",
+    "history_prompt",
+    "conversation_turn",
+    "tool_call",
+    "project_config_signal"
+  ]
+}

package/bundle/fixtures/routing/hybrid-corpus.yaml

@@ -0,0 +1,154 @@
+schema_version: agentera.hybrid_routing_corpus.v3
+status: frozen
+text_provenance: All request text in this fixture is synthetic and authored for conformance testing.
+retention_policy: >-
+  This fixture may contain only synthetic or explicitly consented text. Evaluation
+  reports retain case IDs and aggregate metrics, never private request strings.
+freeze_policy: >-
+  Development and adversarial entries are the sole frozen synthetic implementation
+  corpus. Additions or expectation changes require a new schema_version and a new
+  corpus file; no hidden, sealed, or vendor-host corpus is required.
+partitions:
+  development: { status: frozen, purpose: phrase inventory and structural contract development }
+  adversarial: { status: frozen, purpose: "abstention, separator, and invalid-receipt safety" }
+
+route_cases:
+  - { id: DEV-PHRASE-STATUS, partition: development, request: "show project briefing for the checkout", expected: { phase1: deterministic_selection, tier: phrase, capability: status } }
+  - { id: DEV-PHRASE-VISION, partition: development, request: "define product direction for collaboration", expected: { phase1: deterministic_selection, tier: phrase, capability: vision } }
+  - { id: DEV-PHRASE-DISCUSS, partition: development, request: "help me decide: cache or queue", expected: { phase1: deterministic_selection, tier: phrase, capability: discuss, topic: ": cache or queue" } }
+  - { id: DEV-PHRASE-RESEARCH, partition: development, request: "study external patterns for durable jobs", expected: { phase1: deterministic_selection, tier: phrase, capability: research } }
+  - { id: DEV-PHRASE-PLAN, partition: development, request: "make an implementation plan for import safety", expected: { phase1: deterministic_selection, tier: phrase, capability: plan } }
+  - { id: DEV-PHRASE-BUILD, partition: development, request: "implement the approved plan for task one", expected: { phase1: deterministic_selection, tier: phrase, capability: build } }
+  - { id: DEV-PHRASE-OPTIMIZE, partition: development, request: "improve a measured bottleneck in startup", expected: { phase1: deterministic_selection, tier: phrase, capability: optimize } }
+  - { id: DEV-PHRASE-AUDIT, partition: development, request: "check codebase health before release", expected: { phase1: deterministic_selection, tier: phrase, capability: audit } }
+  - { id: DEV-PHRASE-DOCUMENT, partition: development, request: "refresh project documentation for setup", expected: { phase1: deterministic_selection, tier: phrase, capability: document } }
+  - { id: DEV-PHRASE-PROFILE, partition: development, request: "save a decision profile for local work", expected: { phase1: deterministic_selection, tier: phrase, capability: profile } }
+  - { id: DEV-PHRASE-DESIGN, partition: development, request: "shape the interface for review", expected: { phase1: deterministic_selection, tier: phrase, capability: design } }
+  - { id: DEV-PHRASE-ORCHESTRATE, partition: development, request: "execute the approved plan for phase two", expected: { phase1: deterministic_selection, tier: phrase, capability: orchestrate } }
+  - { id: DEV-ABSTAIN-STATUS, partition: development, request: "show project briefings", expected: { phase1: semantic_required, reason: literal_abstention, boundary: status } }
+  - { id: DEV-ABSTAIN-VISION, partition: development, request: "define our product direction", expected: { phase1: semantic_required, reason: literal_abstention, boundary: vision } }
+  - { id: DEV-ABSTAIN-DISCUSS, partition: development, request: "help us decide", expected: { phase1: semantic_required, reason: literal_abstention, boundary: discuss } }
+  - { id: DEV-ABSTAIN-RESEARCH, partition: development, request: "research patterns", expected: { phase1: semantic_required, reason: literal_abstention, boundary: research } }
+  - { id: DEV-ABSTAIN-PLAN, partition: development, request: "make implementation plan", expected: { phase1: semantic_required, reason: literal_abstention, boundary: plan } }
+  - { id: DEV-ABSTAIN-BUILD, partition: development, request: "implement approved plan", expected: { phase1: semantic_required, reason: literal_abstention, boundary: build } }
+  - { id: DEV-ABSTAIN-OPTIMIZE, partition: development, request: "optimize measured bottleneck", expected: { phase1: semantic_required, reason: literal_abstention, boundary: optimize } }
+  - { id: DEV-ABSTAIN-AUDIT, partition: development, request: "audit the codebase health", expected: { phase1: semantic_required, reason: literal_abstention, boundary: audit } }
+  - { id: DEV-ABSTAIN-DOCUMENT, partition: development, request: "update documentation", expected: { phase1: semantic_required, reason: literal_abstention, boundary: document } }
+  - { id: DEV-ABSTAIN-PROFILE, partition: development, request: "save decision profile", expected: { phase1: semantic_required, reason: literal_abstention, boundary: profile } }
+  - { id: DEV-ABSTAIN-DESIGN, partition: development, request: "design an interface", expected: { phase1: semantic_required, reason: literal_abstention, boundary: design } }
+  - { id: DEV-ABSTAIN-ORCHESTRATE, partition: development, request: "execute approved plan", expected: { phase1: semantic_required, reason: literal_abstention, boundary: orchestrate } }
+  - { id: DEV-BARE, partition: development, request: "/agentera", expected: { phase1: deterministic_selection, tier: bare, capability: status } }
+  - { id: DEV-DIRECT, partition: development, request: "/agentera plan import safety", expected: { phase1: deterministic_selection, tier: direct, capability: plan } }
+  - { id: ADV-BARE-WITH-TEXT, partition: adversarial, request: "/agentera what time is it", expected: { phase1: semantic_required, reason: nonbare_request, boundary: bare } }
+  - { id: ADV-DIRECT-PARTIAL, partition: adversarial, request: "/agentera planner import safety", expected: { phase1: semantic_required, reason: invalid_direct_name, boundary: direct } }
+  - { id: ADV-QUOTED-PHRASE, partition: adversarial, request: 'The words "help me decide" appear in this quote.', expected: { phase1: semantic_required, reason: nonleading_phrase } }
+  - { id: ADV-NEGATED-PHRASE, partition: adversarial, request: "Do not help me decide; just show alternatives.", expected: { phase1: semantic_required, reason: nonleading_phrase } }
+  - { id: ADV-PUNCTUATED-PHRASE, partition: adversarial, request: "help me decide: now", expected: { phase1: deterministic_selection, tier: phrase, capability: discuss, topic: ": now" } }
+  - { id: ADV-EMDASH-SEPARATOR, partition: adversarial, request: "help me decide—now", expected: { phase1: deterministic_selection, tier: phrase, capability: discuss, topic: "—now" } }
+  - { id: ADV-FULLWIDTH-PHRASE, partition: adversarial, request: "ＨＥＬＰ　ＭＥ　ＤＥＣＩＤＥ： cache", expected: { phase1: deterministic_selection, tier: phrase, capability: discuss, topic: "： cache" } }
+  - { id: ADV-REPEATED-WHITESPACE, partition: adversarial, request: "help\t\tme   decide\ncache", expected: { phase1: deterministic_selection, tier: phrase, capability: discuss, topic: "\ncache" } }
+  - { id: ADV-PARTIAL-PHRASE, partition: adversarial, request: "help me deciding now", expected: { phase1: semantic_required, reason: partial_token } }
+  - { id: ADV-UNSUPPORTED-PUNCTUATION, partition: adversarial, request: "help me decide! now", expected: { phase1: semantic_required, reason: unsupported_separator } }
+
+receipt_cases:
+  - id: DEV-RECEIPT-SELECT-PASS
+    partition: development
+    valid: true
+    request: "How should we divide the import work?"
+    expected_terminal: selected
+    receipt: { version: agentera.route_receipt.v1, request_sha256: c28396095a91d6b3f0f6485f8cc4a898f7d012a1d01d000653786fa869626b70, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: none }
+  - id: ADV-RECEIPT-SELECT-MISSING-CAPABILITY
+    partition: adversarial
+    valid: false
+    request: "How should we divide the import work?"
+    expected_terminal: invalid_receipt
+    error: required.capability
+    receipt: { version: agentera.route_receipt.v1, request_sha256: c28396095a91d6b3f0f6485f8cc4a898f7d012a1d01d000653786fa869626b70, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, compound: none }
+  - id: DEV-RECEIPT-CLARIFY-PASS
+    partition: development
+    valid: true
+    request: "Make it better"
+    expected_terminal: clarification
+    receipt: { version: agentera.route_receipt.v1, request_sha256: d71e91121b85d9e84a5dea968dc995878667e4b631b92f8742622427a23cdaa6, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: clarify, question: "Do you want a plan or implementation?" }
+  - id: ADV-RECEIPT-CLARIFY-MISSING-QUESTION
+    partition: adversarial
+    valid: false
+    request: "Make it better"
+    expected_terminal: invalid_receipt
+    error: required.question
+    receipt: { version: agentera.route_receipt.v1, request_sha256: d71e91121b85d9e84a5dea968dc995878667e4b631b92f8742622427a23cdaa6, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: clarify }
+  - id: DEV-RECEIPT-NO-MATCH-PASS
+    partition: development
+    valid: true
+    request: "What time is the train?"
+    expected_terminal: status_fallback
+    receipt: { version: agentera.route_receipt.v1, request_sha256: b712acb8d881cc37a94f06c8ec9efb91f6ce24fa4e7349883dbbb36b57c5d7bc, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: no_match }
+  - id: ADV-RECEIPT-NO-MATCH-FORBIDDEN-CAPABILITY
+    partition: adversarial
+    valid: false
+    request: "What time is the train?"
+    expected_terminal: invalid_receipt
+    error: not
+    receipt: { version: agentera.route_receipt.v1, request_sha256: b712acb8d881cc37a94f06c8ec9efb91f6ce24fa4e7349883dbbb36b57c5d7bc, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: no_match, capability: plan }
+  - id: DEV-RECEIPT-COMPOUND-PRESERVE-PASS
+    partition: development
+    valid: true
+    request: "Plan the migration and then implement it"
+    expected_terminal: selected
+    receipt: { version: agentera.route_receipt.v1, request_sha256: f26da5835071b706a176032b263b0131817a56dcd2965f4198e57e2e23b0ac60, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: preserve, remainder_span: { start: 4, end: 40 } }
+  - id: ADV-RECEIPT-COMPOUND-INVALID
+    partition: adversarial
+    valid: false
+    request: "Plan the migration and then implement it"
+    expected_terminal: invalid_receipt
+    error: compound.enum
+    receipt: { version: agentera.route_receipt.v1, request_sha256: f26da5835071b706a176032b263b0131817a56dcd2965f4198e57e2e23b0ac60, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: clarify }
+  - id: ADV-RECEIPT-MISSING-VERSION
+    partition: adversarial
+    valid: false
+    request: "Map the migration before implementation."
+    expected_terminal: invalid_receipt
+    error: required.version
+    receipt: { request_sha256: fc8dfdefc423ea7c375669b044a01c443b48be880e0c4e769579d296ef048f74, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: none }
+  - id: ADV-RECEIPT-INVALID-DIGEST
+    partition: adversarial
+    valid: false
+    request: "Which capability should handle this?"
+    expected_terminal: invalid_receipt
+    error: request_sha256.pattern
+    receipt: { version: agentera.route_receipt.v1, request_sha256: not-a-digest, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: none }
+  - id: ADV-RECEIPT-UNKNOWN-CAPABILITY
+    partition: adversarial
+    valid: false
+    request: "Which capability should handle this?"
+    expected_terminal: invalid_receipt
+    error: binding.capability
+    receipt: { version: agentera.route_receipt.v1, request_sha256: 9516783492db2d389ec305dfea5f60d23e6d136c7cd27e236bbc29daeca427df, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: unknown, compound: none }
+  - id: ADV-RECEIPT-OUT-OF-BOUNDS-SPAN
+    partition: adversarial
+    valid: false
+    request: "Keep the second request deferred."
+    expected_terminal: invalid_receipt
+    error: binding.remainder_span
+    receipt: { version: agentera.route_receipt.v1, request_sha256: 8b5ea821ff9831f5d5c9a87e2b5a2eefbfbbce54032d2f1bc160ada48eb82180, semantic_capsule_sha256: f885d882a3d08a59aac28cebbb9a3270a28096b6f411f55f99e8772c3ce7637e, outcome: select, capability: plan, compound: preserve, remainder_span: { start: 0, end: 999 } }
+  - id: ADV-RECEIPT-MISSING-CAPSULE-DIGEST
+    partition: adversarial
+    valid: false
+    request: "Which capability should handle this?"
+    expected_terminal: invalid_receipt
+    error: required.semantic_capsule_sha256
+    receipt: { version: agentera.route_receipt.v1, request_sha256: 9516783492db2d389ec305dfea5f60d23e6d136c7cd27e236bbc29daeca427df, outcome: select, capability: plan, compound: none }
+  - id: ADV-RECEIPT-INVALID-CAPSULE-DIGEST
+    partition: adversarial
+    valid: false
+    request: "Which capability should handle this?"
+    expected_terminal: invalid_receipt
+    error: semantic_capsule_sha256.pattern
+    receipt: { version: agentera.route_receipt.v1, request_sha256: 9516783492db2d389ec305dfea5f60d23e6d136c7cd27e236bbc29daeca427df, semantic_capsule_sha256: not-a-digest, outcome: select, capability: plan, compound: none }
+  - id: ADV-RECEIPT-STALE-CAPSULE-DIGEST
+    partition: adversarial
+    valid: false
+    request: "Which capability should handle this?"
+    expected_terminal: invalid_receipt
+    error: binding.semantic_capsule_sha256
+    receipt: { version: agentera.route_receipt.v1, request_sha256: 9516783492db2d389ec305dfea5f60d23e6d136c7cd27e236bbc29daeca427df, semantic_capsule_sha256: "0000000000000000000000000000000000000000000000000000000000000000", outcome: select, capability: plan, compound: none }