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

package/README.md

@@ -10,17 +10,46 @@ surface.
 Until the stable dist-tag is promoted, run 3.0 through `@next`:
 
 ```bash
-npx -y agentera@next prime --format json
+npx -y agentera@next prime --context status --format json
 npx -y agentera@next doctor --format json
 ```
 
+The first command is the one-call pre-cutover bootstrap. Clean, v2, and
+partially migrated projects return bounded `blocked` output with the exact full
+entity-upgrade command in `state_cutover.recovery_command`; v3 returns `ok`
+unless health state makes it `degraded`. Every recovery command remains on
+`@next`, and an `ok` outcome needs no fallback or second dashboard call. Served
+capability instructions and bundled startup schemas use that same exact
+development-channel executable. Package verification parses every registry-owned
+instructional Markdown, YAML, and JSON surface, rejects duplicate keys and
+unsafe aliases, reason-classifies non-guidance and generated declarations, and
+closes every static constructor importer and re-exporter through conservative
+TypeScript module closure. Every closure module is an explicit producer or
+reasoned non-producer. Generated declaration fields and source/package records
+must match exactly, and unused exemptions fail. Only the
+adjacent ordered stable-v2 preview/apply pair in `UPGRADE.md` may execute
+`@latest`. The second command is an independent read-only evidence probe on the
+same channel.
+
 `prime --format json` returns a bounded decision brief (at most 12000 UTF-8
-bytes); use `prime --dashboard --format json` for the full orientation payload.
-Status startup is one call: `prime --context status --format json` returns
+bytes). Status startup returns
 `capability_context.instructions` and bounded
 `capability_context.context.status_context` together (at most 25000 UTF-8
 bytes). Omitted detail names its authoritative recovery command. `doctor`
-returns detailed read-only evidence and exact user actions.
+returns detailed read-only evidence and exact user actions. Entity-mode projects
+with an absent or unsafe TODO reconciliation marker return `action_required`
+instead of `ok` or `up_to_date`; use the reported preview command, then the
+preview's exact effect-bound apply command:
+
+```bash
+npx -y agentera@next state todo activate --dry-run --format json
+npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json
+npx -y agentera@next state todo repair --dry-run --format json
+npx -y agentera@next state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json
+```
+
+`check validate state` reports the same bounded, read-only diagnosis. Healthy
+active TODO projections keep the existing output.
 
 ## Shared-skill integration
 

package/bundle/CHANGELOG.md

@@ -2,8 +2,39 @@
 
 ## [Unreleased]
 
+- Fixed pre-cutover bootstrap so clean, v2, partially migrated, and v3 projects
+  can call `npx -y agentera@next prime --context status --format json` once;
+  marker-absent state now blocks with exact full-cutover recovery, while active
+  help, metadata, route, detail, recovery, every served capability body, and
+  active bundled bootstrap authorities stay on `@next`. Parse-aware Markdown,
+  YAML, and duplicate-key-safe JSON checks now parse the complete shell context
+  and reject every subcommand plus prompt, list, prose, table, wrapper,
+  operator, substitution, split-token, multiline, nested, malformed,
+  alias-cycle, or wrong-channel evasion with one diagnostic per invocation.
+  Stable-channel tokens are confined independently of command recognition.
+  Exact source/package parity now includes all generated declaration fields,
+  unused exemptions, and conservative import/re-export closure with explicit
+  producer or non-producer classification.
+
 ### Changed
 
+- `agentera prime` now returns TODO state only through the canonical `todo`
+  field. Requests for the retired `issues` field fail with one structured
+  correction to `todo` instead of emitting a duplicate alias and warning.
+- `agentera prime --context <capability> --format json` now returns one bounded
+  startup availability projection with an `ok`, `degraded`, or `blocked`
+  outcome. Deferred detail names its exact read command; writer payloads are
+  available only through `agentera schema`. Status uses the same outcome in one
+  call, and `prime --dashboard` is a deprecated status-startup alias.
+- Semantic route abstentions now return a self-describing nullable receipt guide.
+  `agentera route request --input - --format json` and `agentera route receipt
+  --help` expose the exact `agentera.route_receipt.v1` schema, valid outcomes,
+  nullability, compound and UTF-8 span rules, plus a runnable stdin round trip.
+- Development releases now separate explicit metadata preparation, source and
+  candidate qualification, candidate-bound approval, staged exact-version
+  publication, and forward-only tag promotion. Preparation is registry-free;
+  qualification retains one immutable artifact with content-addressed receipts
+  and cold-state smoke evidence; ordinary CI pushes cannot publish it.
 - State record families now use canonical bounded `list` and exact `get` reads,
   with predictable summary counts, selectors, queue ordering, omission metadata,
   and exact-detail recovery generated from the retrieval authority.
@@ -46,9 +77,59 @@
 - Changed `agentera check lint` verbosity checks to consume schema-owned full-file and per-entry word limits, skip no-limit and token-only dimensions, and report authority failures without fallback budgets.
 - Corrected packaged experiment-publication authority to declare validated objective-scoped archive-before-projection ownership and reject contradictory structured scope metadata.
 - Synchronized bounded plan, plan-task, and experiment retrieval across help, schema introspection, capability guidance, operator docs, packaged contracts, output bounds, archive ownership, and structured recovery errors.
+- Retained references now have one machine-validated inventory. Current and
+  migration-only contracts require exact reachable production consumers,
+  maintainer runbooks require working source-checkout commands, and unowned,
+  historical, test-only, or comment-only files no longer ship as live authority.
 
 ### Fixed
 
+- Fixed `agentera doctor --format json` to report bounded, read-only retirement
+  diagnostics for stale native resources. Each candidate now names its exact ID,
+  path-only evidence, and a `doctor --retired-resource ID` preview command;
+  user-owned collisions and unreadable paths remain action-required without
+  leaking contents or mutating runtime state.
+- Fixed retired installed-hook preview commands to retain the resolved
+  `--install-root`, so an exact diagnostic cannot replay against the default
+  app root.
+- Fixed v2 hook retirement to remove only whole-resource-proven hooks and to
+  preserve ambiguous resources for manual review. Upgrade no longer rewrites
+  legacy hooks to a retired `agentera hook` command, which is no longer a
+  public CLI surface.
+- Fixed explicit native-resource cleanup previews to omit unrelated app and
+  project migration work. v2 cleanup now removes independently proven legacy
+  agents beside preserved user-owned agent collisions, which remain manual
+  review and keep the cleanup non-success, including on replay.
+- Fixed native resource cleanup to replay historical Codex descriptor ownership
+  IDs, preserve identity collisions and unowned files, and expose the complete
+  retired native-resource vocabulary for v2-only upgrade discovery.
+- Fixed release qualification provenance and isolation. CI approvals now bind
+  the contracted qualification repository, workflow, full branch ref, run, and
+  API-backed head SHA before environment approval or artifact mutation;
+  stable shim releases require packaged-input source provenance; retained
+  artifacts keep and revalidate mode `0444`; and npm/pnpm probes and mutation
+  validation use fresh sanitized state. Added a three-run non-mutating
+  qualification benchmark plus a content-bound, monotonic stage/L2/promote
+  publication envelope with a strict two-minute budget, reconciled timing,
+  replay evidence, and first-failure reporting. Source qualification now runs a
+  bounded evidence DAG: one generated-overlap execution supplies source,
+  package, build, and overlap proof beside isolated stress and typecheck owners,
+  followed by a solo performance barrier and concurrent compact and
+  capability-contract readers. The solo phase prevents CPU contention from
+  invalidating machine-sensitive performance evidence. Failures preserve the
+  first owner, settle overlap safely, block candidate work, and issue no
+  receipt. Generated-overlap now receives the
+  actual source deadline, reserves bounded cleanup and parent-reconciliation
+  time, and removes its generated state after failure. Source receipts now mark
+  and validate all nine successful gate outcomes and reject semantic tampering.
+  The read-only `source-check` command now lets explicitly configured
+  version/gitRef-only pre-commits reuse matching source evidence without
+  skipping build, compact, parity, or later release qualification.
+  Candidate qualification timing now closes construction before exact-artifact
+  smoke and reconciles non-overlapping gate intervals with explicit overhead.
+  Staging now rejects an absent exact version when the public tag already names
+  that target, before candidate inspection, credentials, or publication.
+
 - Fixed bare `agentera prime` briefs to compact absolute path diagnostics before
   routing and history evidence, preserving executable plan selection, next-action
   recovery, and full or compacted history under the 12,000-byte output bound
@@ -64,6 +145,15 @@
   non-cooperating writer that races after final successful validation remains
   outside the contract. One bounded activation transaction rejects duplicate
   ID-less rows before requiring canonical IDs for all newly managed rows.
+- Fixed TODO cutover and activation to require a complete one-to-one inventory,
+  preserve Markdown-owned status and order, and block implicit mutation. The
+  effect-complete `agentera state todo activate --dry-run` preview now binds
+  its confirmed apply to the exact reported targets and effect digest.
+- Fixed unsafe TODO reconciliation recovery and reporting. `agentera state todo
+  repair` collapses only proven duplicate or stale projections without reopening
+  completed work, while `agentera prime`, `agentera doctor`, and `agentera check
+  validate state` report inactive and unsafe-active projects with exact bounded
+  recovery commands.
 - Fixed plan task append and update to require bounded YAML/JSON file-or-stdin
   records and patches with bare ten-letter selectors and relationships. Complete
   plan create now resolves positive integer or canonical numeric-string ordinals
@@ -265,7 +355,7 @@
 - Removed v1 legacy migration paths, standalone skill bundle wording, and obsolete v1 fixture assumptions from the 3.x tree after the 3.0 boundary (`packages/cli/test/cli/v1LegacyCruft.test.ts` guards against reintroduction).
 - Removed `hej`, `describe`, and `gate` from top-level `agentera --help` and dispatch; unsupported structured requests return runnable corrections to `agentera prime`, `agentera schema`, and `agentera check compact`.
 - Removed the requirement for `uv` or a git checkout on the development channel; `uvx --from git+https://github.com/jgabor/agentera@main agentera` remains the stable 2.x Python line only.
-- Removed `agentera state migrate`, `agentera state backfill`, projection repair, and automatic v1 conversion. Recognized v2 aggregate projects now have one forward mutation path: full `agentera upgrade --yes`; `state migrate entities --dry-run` remains read-only.
+- Removed `agentera state migrate`, `agentera state backfill`, projection repair, and automatic v1 conversion. Recognized v2 aggregate projects now use `agentera upgrade --dry-run` for preview and full `agentera upgrade --yes` for the one forward mutation path.
 - Removed host-native runtime selectors, repair actions, package manifests, plugins, hooks, agents, and Bun single-binary delivery from the v3 distribution. Migration fixtures, ownership evidence, and explicit native Agentera resource cleanup remain internal migration surfaces.
 
 ### Migration notes

package/bundle/README.md

@@ -16,21 +16,27 @@ in the repository so work can continue across sessions and runtimes.
 
 Agentera 3.0 is the self-contained TypeScript package on npm. Before the stable
 dist-tag promotion, use `@next`; after promotion, the same commands work with
-`agentera@latest` or an installed `agentera` binary.
+the stable npm channel or an installed CLI binary.
 
 ```bash
-npx -y agentera@next prime
+npx -y agentera@next prime --context status --format json
 ```
 
 Run that from a git project. In an editor runtime, invoke `/agentera`
 (`$agentera` in Codex) for the rendered status dashboard.
 
-`prime` is deliberately bounded: it summarizes current project state and the
-next useful action. Use `doctor` when you need app, project-state, shared-skill,
-and CLI evidence.
+This is the pre-cutover bootstrap. One `@next` call returns the status
+instructions, a bounded startup outcome, and any exact recovery command. Clean,
+v2, and partially migrated projects return `blocked` with
+`state_cutover.recovery_command` set to the full development-channel entity
+upgrade. A v3 project returns `ok` when no independent health degradation
+applies and needs no fallback or second dashboard call. Do not substitute bare
+or stable-channel CLI forms; those can resolve stable v2 until promotion.
+
+Use the same channel for a separate read-only doctor probe when you need full
+app, project-state, shared-skill, and CLI evidence:
 
 ```bash
-npx -y agentera@next prime --format json
 npx -y agentera@next doctor --format json
 ```
 
@@ -41,8 +47,9 @@ skill at `~/.agents/skills/agentera` plus the Agentera CLI. Normal `upgrade`
 previews and applies only app/project migration; it has no current-runtime
 selector and creates no native plugin, hook, agent, command, descriptor, or
 marketplace file. See [UPGRADE.md](./UPGRADE.md) for the distinct one-way v2
-migration and explicit native-resource cleanup route:
-`agentera upgrade --legacy-cleanup RESOURCE_ID --dry-run|--yes`.
+migration and explicit native-resource cleanup route. The guide shows separate
+`@next` preview and apply commands for each cleanup resource.
+The cleanup option pair is `--legacy-cleanup RESOURCE_ID --dry-run|--yes`.
 
 `doctor` reports read-only app, project-state, shared-skill, and CLI evidence.
 `prime`, status, and project-integration output use the app/project recommendation
@@ -64,13 +71,13 @@ does not create an active runtime identity.
 ## Project state
 
 Agentera resolves artifact paths through the CLI and `.agentera/docs.yaml`.
-Normal reads use `agentera state`; supported writes use the typed writer.
+Normal reads use the state namespace; supported writes use the typed writer.
 
 ```bash
-agentera state todo list --format json
-agentera state plan list --status open --format json
-agentera state query --list-artifacts
-agentera state progress explain --verb append --format json
+npx -y agentera@next state todo list --format json
+npx -y agentera@next state plan list --status open --format json
+npx -y agentera@next state query --list-artifacts
+npx -y agentera@next state progress explain --verb append --format json
 ```
 
 Bounded collection retrieval uses stable identities, opaque snapshot cursors,
@@ -78,11 +85,11 @@ explicit omissions, and exact detail commands. The runtime contract is
 [`references/artifacts/state-storage-authority.yaml`](./references/artifacts/state-storage-authority.yaml).
 
 ```bash
-agentera state plan list --format json
-agentera state plan get --id PLAN_ID --format json
-agentera state plan tasks list --limit 20 --format json
-agentera state experiments list --objective OBJECTIVE_ID --format json
-agentera state experiments get --id EXPERIMENT_ID --format json
+npx -y agentera@next state plan list --format json
+npx -y agentera@next state plan get --id PLAN_ID --format json
+npx -y agentera@next state plan tasks list --limit 20 --format json
+npx -y agentera@next state experiments list --objective OBJECTIVE_ID --format json
+npx -y agentera@next state experiments get --id EXPERIMENT_ID --format json
 ```
 
 Plan list/get spans the active plan and immutable plan archives. Plan task
@@ -92,7 +99,7 @@ or unavailable.
 
 Ordinary mutable state uses one canonical file per entity. Every public record
 has only `id` and `artifact` identity, and is accessed through bounded `list`,
-exact `get --id`, and typed `agentera state <artifact> explain` write contracts.
+exact `get --id`, and typed `npx -y agentera@next state <artifact> explain` write contracts.
 Do not edit files under `.agentera/entities/` directly.
 
 The intentional singleton project state is:

package/bundle/UPGRADE.md

@@ -4,8 +4,8 @@ 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
+Before the npm stable dist-tag promotion, select the development npm channel. The stable npm
+channel remains on 2.x until that promotion; upgrade does not publish
 or retag packages.
 
 ## Active integration
@@ -51,6 +51,22 @@ npx -y agentera@next prime --format json
 npx -y agentera@next doctor --format json
 ```
 
+Before stable promotion, `prime --context status --format json` is the one-call
+bootstrap for clean, v2, partially migrated, and v3 projects. Marker-absent
+clean, v2, and partial projects return bounded `blocked` output with the exact
+full entity-upgrade recovery; v3 returns `ok` unless health is degraded. No
+recovery resolves `@latest`, and healthy v3 needs no second dashboard call.
+
+`doctor --format json` also reports bounded `retired_resources` candidates. Each
+entry has an exact retired resource ID, a path-only or fingerprint-safe
+observation, and a read-only, ID-scoped preview command. The command repeats
+the ID and resolved app root as `doctor --install-root ROOT --retired-resource
+ID --format json`; it does not select `upgrade --legacy-cleanup` and cannot
+remove a resource. Doctor never includes resource contents, adopts a name
+collision as Agentera-owned, or changes a diagnosed path. Absent resources
+report `clean`; present or uninspectable candidates require manual ownership
+review.
+
 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.
@@ -63,22 +79,41 @@ 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.
+Use the separate `@next` preview and apply commands below with one declared
+native Agentera resource ID.
+The cleanup option pair is `--legacy-cleanup RESOURCE_ID --dry-run|--yes`.
 
 ```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.
+The retirement contract gives historical plugins, commands, primary and
+capability agents, stale skill links, installed hooks, and registrations one
+vocabulary. It keeps the v2-only inventory separate from the explicit cleanup
+route until cutover approves more cleanup selectors. The current cleanup route
+also recognizes the historical `codex.agents.NAME` descriptor identity as
+`codex.agent-descriptor.NAME`. Each selected 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. An
+explicit cleanup preview contains only its selected resource's lifecycle plan,
+bounded configuration report, and ownership blockers; it does not include
+app/project migration phases. During v2 cleanup, a preserved user-owned legacy
+agent collision remains manual-review work but does not stop independently
+proven legacy-agent removals. The collision still leaves the cleanup non-success
+until it is resolved outside Agentera.
+
+V2 hook retirement never rewrites a native hook to another Agentera command.
+Upgrade removes a whole hook resource only when its complete content proves
+Agentera v2 ownership and its path identity and fingerprint still match the
+preview. Mixed or otherwise unproven resources remain unchanged with manual
+review guidance. The complete v2-only deletion set is machine-readable in
+`references/adapters/runtime-retired-resources.yaml` under
+`cutover_deletion_inventory`; it remains until an approved stable cutover.
 
 Historical transcript import is independent of cleanup. Default extraction and
 analytics do not read Claude history. Import requires explicit local consent:
@@ -159,9 +194,9 @@ create dual authority, or add a repair or import command.
 
 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.
+conversion, restore, and downgrade are unsupported. Only
+`npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run`
+may inventory cutover input; it cannot publish it.
 
 ## Verification and recovery