agentera 3.0.0-dev.32 → 3.0.0-dev.39

package/bundle/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Changed
 
+- `agentera prime` now selects Build and Audit work from the complete plan task
+  graph, prioritizes in-progress work before dependency-ready pending tasks, and
+  keeps status recommendations aligned when the public task list is bounded.
 - Status now selects TODO recommendations from complete typed readiness state
   before applying startup bounds, preserves the selected TODO ID and exact
   retrieval command across JSON, terminal, and host projections, and abstains
@@ -33,18 +36,40 @@
 
 ### Added
 
+- Added `agentera report profile-glossary --input <file|->` for Profile Full
+  personal glossary output in `PROFILE.md`, with bounded
+  personal provenance, byte-preserving section replacement, deterministic
+  confidence decay and refresh, retained permanence, and no project-glossary
+  reads. Discuss, Plan, and Build consume it only through bounded glossary
+  advice after project-state acquisition proves the applicable authority.
+- Added canonical project-glossary discovery and a confirmed-variant guard to
+  `v1LegacyCruft`. Approved literal drift variants now fail validation when
+  reintroduced outside their retained evidence, with the canonical term,
+  source location, and correction.
+- Added `agentera report glossary-advice --input <file|-> --format json` for
+  active read-only glossary lookup. Exact project entries govern project work;
+  personal entries apply only after a valid project gap is proven; and inferred
+  equivalence requires host review. Discuss and interactive Plan/Build clarify
+  before disputed reliance. Autonomous Plan emits a bounded handoff intent for
+  Build, which owns privacy-safe progress caveat lifecycle writes. `prime`
+  reserves at most one of six attention slots for current glossary review while
+  preserving unrelated attention and next-action selection.
+- Added `agentera state glossary publish --input REQUEST` for explicitly
+  confirmed Audit terminology proposals. The build-owned writer revalidates
+  project evidence and atomically records separate approval and shared-entry
+  state, with dry-run, conflict rejection, and idempotent replay.
 - Added typed TODO readiness publication to `agentera state todo create` and
   `update`, including explain discovery, canonical dependency references,
   complete nested validation, replay-safe publication, and list/get round-tripping.
 - Added a validated TODO readiness authority with phase-derived capability
   destinations, explicit triage/block/gate/dependency outcomes, and
   reviewer-assigned deterministic queue ordering.
-- Added post-cutover entity-backed default state views, bare-ID durability diagnostics, and read-only historical migration-manifest target validation while preserving legacy numbered behavior before cutover.
-- Added a Git-backed entity cutover owned by the full development-channel `upgrade --yes` command, with deterministic direct publication, exact-target retries, marker-last authority activation, and first-unresolved-path handoff.
-- Added post-cutover decision entities for immutable bases and content revisions, replaceable satisfaction ownership, bare-ID exact and bounded reads, deterministic effective provenance, stale-base and transition validation, and explicit same-decision conflict detection; marker-absent projects retain the legacy numbered authority without dual writes.
+- Added entity-backed state views, bare-ID durability diagnostics, and read-only historical migration validation; marker-absent projects now require migration instead of exposing legacy numbered reads.
+- Added a Git-backed entity cutover owned by the full development-channel `upgrade --yes` command, with deterministic direct publication, exact-target retries, source-bound marker-last authority activation, and first-unresolved-path handoff.
+- Added decision entities for immutable bases and content revisions, replaceable satisfaction ownership, bare-ID exact and bounded reads, deterministic effective provenance, stale-base and transition validation, and serialized same-decision ownership. Migration preserves ordered legacy amendments, including whole-alternative replacements and dateless evidence, rejects invalid or stale claims, and requires source-bound provenance for inherited legacy confidence; marker-absent aggregate files remain migration input only.
 - Added the post-cutover progress entity writer and `state progress get|list` reads with bare IDs, one canonical file per cycle, atomic replay-safe publication, full provenance, bounded snapshot pagination, and no legacy projection or archive writes; legacy projects remain unchanged until the durable cutover marker exists.
 - Added authority-driven, one-file-per-entity storage primitives with secure project-wide IDs, symlink-safe discovery, conflict-safe publication, relationship validation, and `agentera check validate state` diagnostics.
-- Added an authoritative evidence-tier contract (`references/analysis/evidence-tier-authority.yaml`) and contract-model loader (`packages/cli/src/registries/evidenceTierContract.ts`) fixing the bounded full-evidence and signal tiers, supported Codex, Cursor, OpenCode, Copilot, and historical Claude source coverage, the consumer field-supply map including the latent startup-analysis reader, reserved signal semantics for the deferred glossary, and deterministic recovery outcomes for oversized, legacy, missing, corrupt, and incomplete state.
+- Added an authoritative evidence-tier contract (`references/analysis/evidence-tier-authority.yaml`) and contract-model loader (`packages/cli/src/registries/evidenceTierContract.ts`) fixing the bounded full-evidence and signal tiers, supported Codex, Cursor, OpenCode, Copilot, and historical Claude source coverage, the consumer field-supply map including the latent startup-analysis reader, bounded personal-glossary synthesis semantics, and deterministic recovery outcomes for oversized, legacy, missing, corrupt, and incomplete state.
 - Added bounded tier publication and direct retrieval (`packages/cli/src/analytics/extractCorpus/evidenceTiers.ts`): complete local evidence is retained as independently bounded, source-family shards that split when exceeding the reader cap; a derived, content-addressable bounded signal tier carries only contract-required fields plus a resolvable `evidence_anchor`; generations are staged and revealed by an atomic current-pointer swap so no consumer observes a partial publication; and direct retrieval resolves a signal identity to its full record. The monolithic `corpus.json` write is eliminated; tiers are the only canonical publication output.
 - Added bounded tier-aware reads for usage analytics, report status, prime corpus coverage, startup analysis, and profile synthesis so every analytics consumer reads from bounded evidence shards one at a time instead of loading the monolithic `corpus.json`. A new `tierReader.ts` module projects contract compatibility states and recovery guidance, streams full-evidence records, and reads signal-tier metadata. A new `profileSignals.ts` module reads the bounded signal tier, assesses per-family retention sufficiency against the contract threshold, and resolves synthesized claims' evidence anchors to retained full-evidence shards. Legacy `corpus.json` remains a fallback when no tiers are published; oversized legacy state is never loaded whole.
 - Added a schema-owned verbosity-budget authority that classifies numeric word limits, explicit no-limit declarations, and token-only budgets while rejecting malformed, ambiguous, unreadable, and unsupported ownership without fallback limits.
@@ -56,7 +81,7 @@
 - Added `agentera state plan list` and `agentera state plan get --plan PLAN_ID` for deterministic, cursor-paginated active and archived plan retrieval, full-plan exact reads, lifecycle provenance, and explicit legacy, invalid, missing, and ambiguous archive outcomes.
 - Added persisted plan identity across active-to-archive transitions, deterministic read-only identity for legacy plans, explicit lifecycle provenance, mirrored-path reporting, and structured ambiguity failures for identity collisions.
 - Added `agentera state plan tasks list` and `agentera state plan tasks get --task N` for bounded active-plan task retrieval with declared task-number order, opaque snapshot cursors, structured not-found and compatibility errors, and exact omission recovery in text and JSON plan output.
-- Added `agentera state decisions amend --number N [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes a record-local revision under `.agentera/revisions/decisions.yaml` that composes over the immutable numbered archive at read time. Apply never rewrites the decisions projection, preserves unrelated decisions' bytes (including comments, block scalars, quoting, and inherited legacy confidence labels), refuses a broken revision document or unsafe record-local boundary without side effects, retries converge on a stable revision identity, and an identical re-submission is an idempotent replay. Append, satisfaction update, and amend tolerate untouched inherited confidence labels as explicit legacy caveats while requiring current vocabulary for new or amended content.
+- Added `agentera state decisions amend --id ID --base-sha256 HASH [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes one immutable decision revision entity. Effective reads compose the base, ordered revisions, and current satisfaction entity; stale-base and same-base conflicts fail before publication, and identical retries converge.
 
 - Added an executable bounded-retrieval authority and reserved CLI grammar for plan tasks, plans, and objective-scoped experiments, including stable and legacy identity rules, experiment `0`, opaque cursors, explicit omissions, and structured compatibility errors; retrieval execution remains staged for subsequent tasks.
 - Added one shared skill at `~/.agents/skills/agentera` plus the CLI and entity-backed project state as the active integration contract; host-native plugin, hook, agent, and package surfaces are not shipped.
@@ -99,6 +124,51 @@
 
 ### Fixed
 
+- Fixed `agentera state query changelog`, Build Prime, and Document closeout to
+  use one bounded Keep-a-Changelog reader with matching headings, boundary,
+  provenance, and fail-safe recovery for missing, malformed, unsafe, ambiguous,
+  or oversized input.
+- Fixed explicit-home upgrade planning to ignore inherited
+  `OPENCODE_CONFIG_DIR` values outside the selected home, preventing unrelated
+  OpenCode resources from blocking fixture, package, or isolated project
+  upgrades while retaining in-home overrides.
+- Fixed `agentera prime --context build` to accept bounded, transient no-plan
+  scope and acceptance through `--input <file|->`, complete execution context
+  without creating plan state or returning non-advancing plan recovery, and
+  reject active-plan conflicts.
+- Fixed `agentera prime --context build` to derive bounded verification commands
+  from `AGENTS.md` and package scripts, preserve exact provenance, canonicalize
+  aliases, and reject placeholders, conflicts, unsafe paths, missing targets,
+  and over-limit input.
+- Fixed `agentera prime --context build` instructions to log TODO, progress,
+  changelog, and plan closeout before one commit, and to describe canonical
+  progress entity publication instead of numbered aggregate compaction.
+- Fixed plan supersession and open-plan completion to require every replacement
+  task to be complete with latest persisted PASS evidence. Existing records
+  remain readable, and affected open plans retain the narrow first-PASS repair.
+- Fixed same-minute progress recency to use persisted writer-owned publication
+  order instead of opaque IDs. List and `prime` now select the final committed
+  publication after restart or copy. Version 2 snapshot cursors preserve
+  deterministic pagination and reject prior-ordering continuations with an
+  actionable omit-`--cursor` recovery.
+- Fixed typed entity updates to retain exact source bytes, reject invalid UTF-8,
+  and revalidate descriptor-pinned displaced bytes before no-clobber canonical
+  publication. Post-displacement failures now restore the exact prior target or
+  surface a retained recovery path without clobbering competing bytes, while
+  post-commit cleanup faults retain an independent exact-byte baseline snapshot
+  and attempt-owned links under the private, Git-ignored, same-filesystem
+  `.agentera/.entity-recovery/` namespace instead of invalidating canonical
+  entity discovery or misreporting durable updates as failed.
+- Fixed `agentera state plan record-evaluation` to recover the first PASS for an
+  unevaluated complete replacement named by a same-plan superseded predecessor
+  while the plan remains open, without relaxing other terminal or retry guards.
+- Fixed Discuss, Plan, and Build profile grounding to use `agentera report
+  profile-grounding --format json`, which preserves non-glossary profile content
+  while excluding the owned personal Glossary section and failing closed on
+  ambiguous boundaries.
+- Fixed bounded personal glossary admission to reject missing or unknown
+  evidence-tier schema versions before reading signals, returning corrupt-state
+  recovery without candidates.
 - Fixed `agentera state plan create` and `agentera state todo create` rejecting
   valid migrated decision and progress summaries during descriptor-pinned
   publication; logical provenance now validates against the real project root,

package/bundle/references/adapters/package-publication.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "agentera.packagePublication.v1",
+  "owner": "repository/package scripts",
+  "invariants": {
+    "preparation": "Metadata preparation is non-publishing and leaves version and gitRef changes for review and commit.",
+    "preflight": "Publication requires explicit authority, a clean tree, committed package metadata, an adapter-valid version, and an existing gitRef before registry mutation.",
+    "publication": "Publish directly to the expected tag, then require bounded exact-version integrity and tag convergence.",
+    "access": "Publish the unscoped package with public access.",
+    "retry": "An exact version with matching integrity and expected tag is a successful replay; conflicting integrity or an expected tag already ahead of the committed version fails without mutation.",
+    "smoke": "Run one non-mutating no-project exact-version --version command after convergence; failure is explicit and does not imply rollback.",
+    "construction": "Each adapter returns the exact npm name, version, file count, packed and unpacked sizes, shasum, integrity, expected tag, artifact path, warnings, and complete file manifest before publication.",
+    "credentials": "Only the npm publish child receives credentials, through a mode-0600 temporary user config; inherited npm/pnpm lifecycle settings and token variables are removed from its environment, and the config is deleted when the child exits.",
+    "orchestration": "Root package scripts are the shared local and CI interface. Push-only development and stable jobs run the matching transaction after required gates; replay needs no credentials, mutation without credentials fails, and development publication precedes exact-version L2 bootstrap verification.",
+    "outputModes": "Default construction output omits the per-file list; --json and --verbose retain the complete npm pack manifest.",
+    "output": ["package", "version", "expectedTag", "phase", "outcome", "nextAction"]
+  },
+  "packages": {
+    "development": {
+      "label": "development TypeScript package",
+      "packagePath": "packages/cli",
+      "manifestPath": "packages/cli/package.json",
+      "expectedTag": "next",
+      "preparation": "incrementDevPrerelease",
+      "construction": "isolatedTypeScriptPackage",
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+    },
+    "stable": {
+      "label": "transitional stable shim",
+      "packagePath": "packages/cli/shim",
+      "manifestPath": "packages/cli/shim/package.json",
+      "expectedTag": "latest",
+      "preparation": "incrementPatch",
+      "construction": "stableShim",
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+    }
+  },
+  "bounds": {
+    "registryAttempts": 6,
+    "registryDelayMs": 5000,
+    "commandTimeoutMs": 120000,
+    "diagnosticCharacters": 1000
+  }
+}

package/bundle/references/adapters/package-surface-characterization.md

@@ -39,6 +39,18 @@ bundle data disappears, or if a current host-native descriptor/runtime path
 enters the package. Contributors use `pnpm -C packages/cli run pack:dry-run`;
 direct checkout packing remains rejected by the canonical packaging authority.
 
+## Publication adapters
+
+[`package-publication.json`](./package-publication.json) owns the shared
+repository publication transaction and distinguishes the development
+TypeScript package from the transitional stable shim. Both require separately
+prepared and committed version and `gitRef` metadata, explicit publication
+authority, a clean tree, exact registry convergence, safe exact-version replay,
+and bounded phase results. Development retains isolated construction and the
+`next` tag; stable retains shim tests/construction and the `latest` tag. Each
+adapter's only publication smoke is its non-mutating, no-project exact-version
+`--version` invocation, so publication does not absorb migration coverage.
+
 ## Native package boundary
 
 The package registry defines no host-native manifest parity, package-manager

package/bundle/references/analysis/evidence-tier-authority.yaml

@@ -171,69 +171,67 @@ source_families:
 
 signal_semantics:
   fixed_taxonomy_rule: >-
-    The signal semantics below are fixed. Current consumers and the deferred
-    glossary consumer depend on their meaning; the contract must preserve that
-    meaning even though glossary implementation and profile levels remain out
-    of scope. A semantic kind present here must remain derivable from a bounded
-    signal record without restoring unbounded transcript content.
+    The signal semantics below are fixed. Current profile and personal-glossary
+    consumers depend on their meaning. A semantic kind present here must remain
+    derivable from a bounded signal record without restoring unbounded
+    transcript content.
   kinds:
     correction:
       meaning: >-
         A user signal that revises a prior position ("no", "not quite",
         "actually", "instead"). Used to detect decision drift and overrides.
       derivable_from: history_prompt and conversation_turn records
-      deferred_consumer: glossary
+      consumer: glossary
     decision:
       meaning: >-
         A decision-bearing signal (decide, prefer, trade-off, scope, approve,
         reject). The primary profile-synthesis input.
       derivable_from: history_prompt and conversation_turn records
-      deferred_consumer: glossary
+      consumer: glossary
       current_consumer: profile_synthesis
     question:
       meaning: >-
         An interrogative signal ("why", "how", "should", or a "?"). Surfaces
         uncertainty and information-gathering intent.
       derivable_from: history_prompt and conversation_turn records
-      deferred_consumer: glossary
+      consumer: glossary
     instruction:
       meaning: >-
         Explicit user-authored instructions (AGENTS.md and project memory
         documents). The highest-signal, most durable evidence.
       derivable_from: instruction_document records
-      deferred_consumer: glossary
+      consumer: glossary
       current_consumer: profile_synthesis
     configuration:
       meaning: >-
         Recurring config patterns across projects (manifest names, scripts,
         dependencies, build/tool config). Objective evidence of what shipped.
       derivable_from: project_config_signal records
-      deferred_consumer: glossary
+      consumer: glossary
       current_consumer: profile_synthesis
     record_identity:
       meaning: >-
         The stable, addressable identity (`source_id`) of one full record. Lets
         any consumer cite evidence without retaining its content.
       derivable_from: every record's source_id
-      deferred_consumer: glossary
+      consumer: glossary
     date:
       meaning: >-
         The record timestamp anchoring evidence in time. Drives decay,
         recency, and watermark windows.
       derivable_from: every record's timestamp field
-      deferred_consumer: glossary
+      consumer: glossary
     evidence_anchor:
       meaning: >-
         The resolvable link from a bounded signal record back to exactly one
         retained full-evidence shard. Guarantees that bounded analysis never
         severs the citation chain.
       derivable_from: signal record evidence_anchor -> full_evidence source_id
-      deferred_consumer: glossary
+      consumer: glossary
   preservation_rule: >-
     Fixing the contract must not remove the required meaning of any kind above
-    from current or declared deferred consumers. A deferred consumer (glossary)
-    is named here so the contract reserves the fields and semantics it will
-    need, even though its implementation is out of scope.
+    from current consumers. Personal glossary synthesis is named here because it
+    actively consumes these bounded-history fields and semantics.
 
 consumer_map:
   supply_rule: >-
@@ -300,10 +298,12 @@ consumer_map:
         - evidence_anchor
       source_identity: source_id and evidence_anchor for every synthesized claim
       input_contract: signal tier instruction/decision/question/config projection
-  deferred_consumers:
+  semantic_consumers:
     glossary:
       tier: signal
-      status: declared_deferred
+      status: active
+      input_scope: bounded_personal_history
+      excluded_evidence_classes: [project_file]
       required_semantics:
         - correction
         - decision
@@ -314,9 +314,11 @@ consumer_map:
         - date
         - evidence_anchor
       rule: >-
-        The glossary is out of scope to implement, but its required semantics
-        are fixed here so the signal contract reserves them. Implementation must
-        not drop a reserved semantic or remove the field that carries it.
+        Personal glossary synthesis actively consumes bounded personal-history
+        signals. Project-file provenance remains repository evidence under the
+        shared glossary ownership contract and is never represented as retained-
+        history evidence. Implementations must not drop a required semantic or
+        remove the field that carries it.
 
 profile_sufficiency:
   question: >-

package/bundle/references/analysis/verification-policy.yaml

@@ -129,6 +129,7 @@ conservative_routing:
     - packages/cli/scripts/verification-barrier.mjs
     - packages/cli/scripts/verify-generated-overlap.mjs
     - packages/cli/scripts/pack-package.mjs
+    - packages/cli/scripts/package-construction.mjs
     - packages/cli/scripts/reject-direct-prepack.mjs
     - packages/cli/test/sourceSetup.ts
     - packages/cli/test/helpers/sourceSubprocess.ts

package/bundle/references/artifacts/artifact-registry-interface-model.yaml

@@ -12,19 +12,24 @@ source_of_truth:
   producer_field: meta.producer
   consumers_field: meta.consumers
   artifact_type_field: meta.artifact_type
+  implementation_status_field: meta.implementation_status
   added_contract_fields:
     display_name: >-
       Human-facing canonical artifact name used by capability schemas, docs.yaml
       mapping keys, validators, and bounded CLI override lookup.
     scope: >-
       Where the artifact lives and how path overrides may apply.
+    implementation_status: >-
+      Whether registry relationships describe shipped behavior or an explicitly
+      declared-deferred contract.
     path_template: >-
       Structured path facts when meta.path contains a placeholder or points to a
       global, archive, or local-harness location.
   single_authority_rule: >-
     Consumers may project these facts into views, but must not maintain separate
-    display-name, default-path, producer, consumer, scope, type, or special-case
-    maps outside this registry Interface and runtime docs.yaml override loading.
+    display-name, default-path, producer, consumer, scope, type, implementation
+    status, or special-case maps outside this registry Interface and runtime
+    docs.yaml override loading.
 record:
   required_groups:
     - identity
@@ -61,6 +66,7 @@ record:
       owns:
         - producer capability IDs
         - consumer capability IDs
+        - implementation status
       required_fields:
         producers: list[string]
         consumers: list[string]
@@ -172,6 +178,9 @@ required_artifact_identities:
     - artifact_id: vision
       display_name: VISION.md
       default_path: .agentera/vision.yaml
+    - artifact_id: glossary
+      display_name: GLOSSARY.md
+      default_path: .agentera/glossary.yaml
   project_root:
     - artifact_id: todo
       display_name: TODO.md