agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/dist/cli/orientation/attention.js

@@ -1,13 +1,13 @@
 import { projectIntegrationAttention } from "../../upgrade/projectIntegration.js";
-import { isV2ManagedInstallAtAppHome } from "../../upgrade/coexistenceProbe.js";
 import { corpusCoverageAttention } from "./corpusCoverage.js";
 import { firstPresent } from "../stateQuery.js";
 import { TODO_SEVERITY_ORDER } from "../todoSeverity.js";
 export function buildOrientationAttention(state) {
-    const { profile_status: profileStatus, profile_dict: profileDict, v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, glossary_caveat_attention: glossaryCaveatAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, } = state;
+    const { v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, glossary_caveat_attention: glossaryCaveatAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, todo_reconciliation: todoReconciliation, } = state;
     const attention = [];
-    if (isV2ManagedInstallAtAppHome(state.app.appHome)) {
-        attention.push(`normal: v2/v3 coexistence at ${state.app.appHome}; pick one line: complete v3 migration, uninstall v3, or stay on v2`);
+    if (todoReconciliation?.status === "action_required") {
+        const label = todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+        attention.push(`action-required: TODO reconciliation is ${label}; preview \`${todoReconciliation.preview_command ?? "n/a"}\`; apply \`${todoReconciliation.apply_command ?? "n/a"}\``);
     }
     const skillDivergenceSignals = (state.app.signals ?? []).filter((s) => s.kind === "skill_root_divergence");
     for (const signal of skillDivergenceSignals) {
@@ -26,18 +26,6 @@ export function buildOrientationAttention(state) {
     if (v1Migration.detected && projectIntegration.recommendation !== "upgrade") {
         attention.push(`degraded: v1 artifacts detected; preview \`${v1Migration.dry_run_command}\`; files=${v1Migration.affected_files.join(", ")}`);
     }
-    if (profileStatus === "absent") {
-        attention.push(`degraded: PROFILE.md absent; ${profileDict.validity.recovery ?? "generate the profile before retrying"}`);
-    }
-    else if (profileStatus === "repair_needed") {
-        attention.push(`degraded: PROFILE.md repair needed; ${profileDict.validity.recovery ?? "repair the profile before retrying"}`);
-    }
-    else if (profileDict.stale) {
-        const daysSince = profileDict.days_since_generated ?? "?";
-        const staleDays = profileDict.stale_threshold_days ?? "?";
-        attention.push(`normal: profile stale (${daysSince} days since last refresh; ` +
-            `threshold=${staleDays}); suggest running profile to refresh PROFILE.md`);
-    }
     if (health.stale) {
         const auditId = health.id ?? "unknown";
         const daysSince = health.days_since_audit ?? "?";
@@ -69,4 +57,3 @@ export function buildOrientationAttention(state) {
     }
     return attention;
 }
-//# sourceMappingURL=attention.js.map

package/dist/cli/orientation/corpusCoverage.js

@@ -100,4 +100,3 @@ export function corpusCoverageAttention(summary) {
     return (`flagged: corpus coverage loss (EX2): available runtimes skipped (${skipped}); ` +
         "suggest running profile stats refresh without --no-* flags");
 }
-//# sourceMappingURL=corpusCoverage.js.map

package/dist/cli/orientation.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { preCutoverCommand } from "./preCutoverCommand.js";
 import { loadArtifactRecord, resolveArtifactPath, } from "../registries/artifactRegistry.js";
 import { activeObjectiveName, artifactPath, resolveRegistryModelPath, } from "./appContext.js";
 import { asList, extractEntries, firstPresent, loadArtifact, recentCycles, truncate, } from "./stateQuery.js";
@@ -19,18 +20,18 @@ import { numberedArchiveContract } from "../state/archiveDiscovery.js";
 const PLAN_FAMILY = entityListFamily("plans");
 const PLAN_TASK_FAMILY = entityListFamily("plan_tasks");
 const OBJECTIVE_FAMILY = entityListFamily("objective");
-const PLAN_LIST_COMMAND = `agentera state ${PLAN_FAMILY.commandTokens.join(" ")} list --format json`;
+const PLAN_LIST_COMMAND = preCutoverCommand(`state ${PLAN_FAMILY.commandTokens.join(" ")} list --format json`);
 function planTaskListCommand(planId) {
     const selector = typeof planId === "string" && planId ? ` ${planId}` : "";
-    return `agentera state ${PLAN_TASK_FAMILY.commandTokens.join(" ")} list${selector} --limit 100 --format json`;
+    return preCutoverCommand(`state ${PLAN_TASK_FAMILY.commandTokens.join(" ")} list${selector} --limit 100 --format json`);
 }
 function planTaskGetCommand(taskId) {
     const selector = typeof taskId === "string" && taskId ? taskId : "ID";
-    return `agentera state ${PLAN_TASK_FAMILY.commandTokens.join(" ")} get --id ${selector} --format json`;
+    return preCutoverCommand(`state ${PLAN_TASK_FAMILY.commandTokens.join(" ")} get --id ${selector} --format json`);
 }
 function objectiveGetCommand(objectiveId) {
     const selector = typeof objectiveId === "string" && objectiveId ? objectiveId : "ID";
-    return `agentera state ${OBJECTIVE_FAMILY.commandTokens.join(" ")} get --id ${selector} --format json`;
+    return preCutoverCommand(`state ${OBJECTIVE_FAMILY.commandTokens.join(" ")} get --id ${selector} --format json`);
 }
 /**
  * Orientation summaries layer for prime/status. Faithful port of the
@@ -863,4 +864,3 @@ export function selectStatusNextAction(plan, health, objective, todoItems, decis
     const { recommended } = selectStatusReadiness(plan, health, objective, todoItems, decision, savedContext, completeTodoReadiness);
     return { object: recommended.object, capability: recommended.capability, reason: recommended.reason };
 }
-//# sourceMappingURL=orientation.js.map

package/dist/cli/planArtifacts.js

@@ -348,4 +348,3 @@ export function planCatalogEntry(artifact, activePath, identity) {
         },
     };
 }
-//# sourceMappingURL=planArtifacts.js.map

package/dist/cli/planEvidence.js

@@ -155,4 +155,3 @@ export function resolvePlanTaskEvidence(artifact, tasks, schemas) {
     });
     return { tasks: resolved, complete, sources: [...sources].sort() };
 }
-//# sourceMappingURL=planEvidence.js.map

package/dist/cli/planLifecycleState.js

@@ -1,7 +1,8 @@
 import { entityListFamily } from "../state/entityRetrievalHelp.js";
 import { sourceProvenance } from "./capabilityContext/shared.js";
 import { asList } from "./stateQuery.js";
-const PLAN_LIST_COMMAND = `agentera state ${entityListFamily("plans").commandTokens.join(" ")} list --format json`;
+import { preCutoverCommand } from "./preCutoverCommand.js";
+const PLAN_LIST_COMMAND = preCutoverCommand(`state ${entityListFamily("plans").commandTokens.join(" ")} list --format json`);
 function diagnosticEntries(value) {
     return asList(value).filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
 }
@@ -33,4 +34,3 @@ export function planLifecycleState(plan) {
             : [],
     };
 }
-//# sourceMappingURL=planLifecycleState.js.map

package/dist/cli/planTaskIndex.js

@@ -9,4 +9,3 @@ export function planTaskIndex(plan) {
         ? plan.tasks.filter((task) => Boolean(task) && typeof task === "object" && !Array.isArray(task))
         : []);
 }
-//# sourceMappingURL=planTaskIndex.js.map

package/dist/cli/preCutoverCommand.js

@@ -0,0 +1,32 @@
+import { CANONICAL_DEVELOPMENT_CLI } from "../core/developmentChannel.js";
+export const PRE_CUTOVER_CLI = CANONICAL_DEVELOPMENT_CLI;
+export function assertPreCutoverCommand(command) {
+    if (!command.startsWith(`${PRE_CUTOVER_CLI} `) || command.includes("agentera@latest")) {
+        throw new Error(`pre-cutover v3 command must use ${PRE_CUTOVER_CLI}: ${command}`);
+    }
+    return command;
+}
+export function preCutoverCommand(argumentsText) {
+    if (!argumentsText.trim() || /(?:^|\s)(?:npx|agentera(?:@\S+)?)(?:\s|$)/.test(argumentsText)) {
+        throw new Error(`pre-cutover command arguments must not select an executable or channel: ${argumentsText}`);
+    }
+    return assertPreCutoverCommand(`${PRE_CUTOVER_CLI} ${argumentsText}`);
+}
+export function preCutoverCommandFromBare(command) {
+    if (!command.startsWith("agentera ")) {
+        throw new Error(`expected a bare Agentera command before pre-cutover channel binding: ${command}`);
+    }
+    return preCutoverCommand(command.slice("agentera ".length));
+}
+const BARE_V3_COMMAND = /(?<![\w@-])agentera (?=(?:prime|doctor|upgrade|route|state|schema|check|report)\b)/g;
+/** Bind every executable Agentera command in a pre-cutover instruction body. */
+export function preCutoverInstructionBody(body) {
+    if (/\bagentera@latest\b/.test(body) || /\bnpx\s+(?:-y\s+)?agentera\s/.test(body)) {
+        throw new Error(`pre-cutover instruction body selects a bare or stable Agentera executable`);
+    }
+    const bound = body.replace(BARE_V3_COMMAND, `${PRE_CUTOVER_CLI} `);
+    if (BARE_V3_COMMAND.test(bound)) {
+        throw new Error(`pre-cutover instruction body retains a bare Agentera command`);
+    }
+    return bound;
+}

package/dist/cli/prime-blob.js

@@ -1,9 +1,10 @@
-export const PRIME_BLOB = [
+import { preCutoverInstructionBody } from "./preCutoverCommand.js";
+export const PRIME_BLOB = preCutoverInstructionBody([
     "# agentera priming guide",
     "",
     "## Routing: agentera vs native tools",
     "",
-    "Use top-level `agentera <state>` commands for routine questions about project state.",
+    "Use the top-level state-command namespace for routine questions about project state.",
     "Use native tools (read, grep, glob, edit, bash) for source code operations.",
     "",
     "Agentera queries return compact answers from structured state. Do NOT read",
@@ -31,8 +32,8 @@ export const PRIME_BLOB = [
     "",
     "Supported typed writes:",
     "  agentera state progress append ...            # Record verified cycle evidence",
-    "  agentera state decisions append|update ...    # Record decisions or satisfaction",
-    "  agentera state plan append|update --input TASK_RECORD ... # bare task IDs; lifecycle verbs remain flag-only",
+    "  agentera state decisions explain --format json # Discover decision record operations",
+    "  agentera state plan explain --format json      # Discover plan record operations",
     "  plan create ordinals are atomic-input symbols only; published plan/task identities are bare ten-letter IDs",
     "  agentera state health append --input PATH     # Record one complete audit",
     "  agentera state experiments publish --objective ID --input PATH  # Publish one validated experiment",
@@ -67,5 +68,4 @@ export const PRIME_BLOB = [
     "  1. Run `agentera schema --format json`.",
     "  2. Make sure Agentera's app files exist at the reported `managedAppRoot` path.",
     "  3. Run `agentera doctor` for a plain-language repair preview.",
-].join("\n") + "\n";
-//# sourceMappingURL=prime-blob.js.map
+].join("\n") + "\n");

package/dist/cli/profileAcquisition.js

@@ -165,4 +165,3 @@ export function acquireProfile(schemasDir, env = process.env, hooks = {}) {
         return result(profilePath, env, "repair_needed", validityClass, contract.repairRecovery);
     }
 }
-//# sourceMappingURL=profileAcquisition.js.map

package/dist/cli/startupCompletenessContract.js

@@ -57,4 +57,3 @@ export function startupCompletenessContract(input = {}) {
 export function capabilityStartupComplete(input = {}) {
     return Boolean(startupCompletenessContract(input).complete_for_capability_startup);
 }
-//# sourceMappingURL=startupCompletenessContract.js.map

package/dist/cli/stateQuery.js

@@ -7,8 +7,9 @@ import { validateAgentString, validateIdentifier } from "./argvalidate.js";
 import { emitStructured } from "./structured.js";
 import { truncateCodePoints } from "../core/text.js";
 import { boundStructuredProjection } from "../state/projectionPolicy.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
 /** Shared state-query infrastructure ported from scripts/agentera. */
-export const REQUIRED_SPARSE_CONTEXT_FIELDS = ["command", "status"];
+export const REQUIRED_SPARSE_CONTEXT_FIELDS = ["command", "outcome"];
 export const ROUTINE_STRUCTURED_FIELDS = [
     "command",
     "status",
@@ -21,40 +22,36 @@ export const ROUTINE_STRUCTURED_FIELDS = [
     "source_contract",
 ];
 /** Canonical structured field set for the bare prime orientation briefing.
- *  Single consumer-facing authority: `agentera schema` discovery, the emitted
- *  prime JSON `source_contract.fields`, the text-mode source_contract line, and
- *  the agent-ready-state contract all derive from this list so the four-way drift
- *  documented in references/cli/prime-consumer-compatibility.yaml cannot recur.
- *  See public_output_policy.canonical_field_set. The published bare-prime shape
+ *  `agentera schema` discovery, the emitted prime JSON `source_contract.fields`,
+ *  and the text-mode source-contract line derive from this list. The shared skill
+ *  is the permanent host integration authority. The published bare-prime shape
  *  stays stable: omission of default-only conditional payload is governed by
  *  `state_presence` (missing-vs-empty) and named recovery commands, not by
  *  trimming this set. */
 export const PRIME_STRUCTURED_FIELDS = [
-    "command", "status", "app_home", "app", "mode", "profile", "v1_migration", "health",
+    "command", "outcome", "app_home", "app", "mode", "v1_migration", "health",
     "todo", "plan", "docs", "progress", "objective", "state_presence", "shared_skill", "project_integration", "attention",
     "history",
     "decision_attention", "next_action", "orchestration_context", "closeout_context",
-    "evidence_context", "benchmark_context", "execution_context", "source", "source_contract",
+    "evidence_context", "benchmark_context", "execution_context", "startup", "source", "source_contract",
 ];
-/** Deprecated JSON field selectors kept for pre-3.0.0 consumers; selectable
- *  through `--fields` and emitted as aliases, but not part of the published
- *  `source_contract.fields` set. `issues` aliases `todo` with a stderr
- *  deprecation warning. Removable at the 3.0.0 stable cut (TODO [fix:3.0.0]). */
-export const DEPRECATED_PRIME_FIELD_ALIASES = ["issues"];
+/** Retired prime fields that receive one structured correction instead of
+ *  falling through to the generic unsupported-field error. */
+export const RETIRED_PRIME_FIELD_CORRECTIONS = {
+    issues: "todo",
+};
 /** Field declared available on the prime selector but emitted only by the
  *  `prime --context <capability>` surface, not by the bare default briefing.
  *  The bare briefing carries it as a `source_contract.capability_context`
  *  pointer with a `fetch_command`. */
 export const PRIME_CONTEXT_ONLY_FIELDS = ["capability_context"];
 /** Fields selectable via `prime [--context <cap>] --fields`. Derives the
- *  canonical structured set, the context-only `capability_context` pointer, and
- *  the deprecated transition aliases from one authority, so schema discovery and
- *  the prime selector cannot drift. */
+ *  canonical structured set and the context-only `capability_context` pointer
+ *  from one authority, so schema discovery and the prime selector cannot drift. */
 export function availablePrimeFields(command) {
-    const base = command === "prime"
+    return command === "prime"
         ? [...PRIME_STRUCTURED_FIELDS, ...PRIME_CONTEXT_ONLY_FIELDS]
         : [...PRIME_STRUCTURED_FIELDS];
-    return [...base, ...DEPRECATED_PRIME_FIELD_ALIASES];
 }
 export const COMMAND_FILTERS = {
     prime: [],
@@ -79,8 +76,8 @@ export function surfaceMissingMessage(surface, p, model = activeAppModel()) {
     return (`${surface} is missing. Agentera cannot find it at ${p}. ` +
         `Agentera directory: ${payload.appHome}. ` +
         `App files directory: ${payload.managedAppRoot}. ` +
-        "Run `agentera doctor` to preview the repair; run " +
-        "`agentera doctor --format json` for structured details. " +
+        `Run \`${preCutoverCommand("doctor")}\` to preview the repair; run ` +
+        `\`${preCutoverCommand("doctor --format json")}\` for structured details. ` +
         `Technical details: appHome=${payload.appHome} managedAppRoot=${payload.managedAppRoot} ` +
         `skillRoot=${payload.skillRoot} runtimeRoot=${payload.runtimeRoot}.`);
 }
@@ -342,4 +339,3 @@ export function validateFilterValues(args, names) {
         }
     }
 }
-//# sourceMappingURL=stateQuery.js.map

package/dist/cli/structured.js

@@ -15,4 +15,3 @@ export function emitStructured(value, outputFormat, out) {
         out(YAML.stringify(value, { sortMapEntries: false }));
     }
 }
-//# sourceMappingURL=structured.js.map

package/dist/cli/todoMarkdown.js

@@ -44,4 +44,3 @@ export function renderTodoPublicRecord(record) {
     }
     return String(record.description ?? "");
 }
-//# sourceMappingURL=todoMarkdown.js.map

package/dist/cli/todoReadinessSelection.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { preCutoverCommand } from "./preCutoverCommand.js";
 import { loadTodoReadinessContract } from "../registries/todoReadinessContract.js";
 import { TODO_SEVERITY_ORDER } from "./todoSeverity.js";
 import { renderTodoPublicRecord } from "./todoMarkdown.js";
@@ -120,7 +121,7 @@ export function evaluateTodoReadinessQueue(entities, sourceRoot) {
             eligible: authority.eligible === true,
             attention: String(authority.attention),
             recovery: declaredRecovery ?? (typeof authority.recovery === "string" ? authority.recovery : null),
-            retrieval: { exact: `agentera state todo get --id ${entity.id} --format json` },
+            retrieval: { exact: preCutoverCommand(`state todo get --id ${entity.id} --format json`) },
             ...(capability ? {
                 capability,
                 phase: contract.phaseByCapability.get(capability),
@@ -189,4 +190,3 @@ export function evaluateTodoReadinessQueue(entities, sourceRoot) {
         abstainRecovery: !selected ? abstainRecovery : null,
     };
 }
-//# sourceMappingURL=todoReadinessSelection.js.map

package/dist/cli/todoSeverity.js

@@ -16,4 +16,3 @@ export const TODO_SEVERITY_ORDER = {
     info: 3,
     annoying: 3,
 };
-//# sourceMappingURL=todoSeverity.js.map

package/dist/core/atomicWriter.js

@@ -18,4 +18,3 @@ export function writeFileAtomic(target, data, encoding = "utf8") {
         throw err;
     }
 }
-//# sourceMappingURL=atomicWriter.js.map

package/dist/core/developmentChannel.js

@@ -0,0 +1 @@
+export const CANONICAL_DEVELOPMENT_CLI = "npx -y agentera@next";