aienvmp 0.1.24 → 0.1.26

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.26
+
+- Shared one AI decision contract across `context --json`, `plan`, and `handoff`.
+- Added decision mode and required command guidance to plan and handoff outputs.
+- Reduced duplicated guidance so multiple AI agents receive the same environment-change rules.
+
+## 0.1.25
+
+- Added a more explicit AI decision contract to `context --json`.
+- Included project-local work allowance, environment-change review state, warning codes, and required follow-up commands.
+- Clarified that local project work can continue while environment changes remain intent-gated and review-oriented.
+
 ## 0.1.24
 
 - Added a dashboard CI Readiness card for `doctor --strict security|policy|coordination|all`.

package/README.md

@@ -10,7 +10,7 @@
 
 It helps Codex, Claude, Gemini, and humans avoid silent Node, Python, package manager, Docker, and security drift.
 
-Core loop: scan once, give AI a preflight context, write a read-only action plan, and hand off safe next steps.
+Core loop: scan once, give AI a shared decision contract, write a read-only action plan, and hand off safe next steps.
 
 ## Quick Start
 
@@ -80,9 +80,9 @@ The dashboard shows which strict scopes are CI-ready before you enforce them.
 ```bash
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
-aienvmp context --json    # AI decision context + actions + compact step summary
-aienvmp plan              # read-only AI action plan for drift and remediation
-aienvmp handoff           # next-agent handoff summary + recommended actions
+aienvmp context --json    # AI decision contract + actions + compact step summary
+aienvmp plan              # read-only AI action plan using the same decision contract
+aienvmp handoff           # next-agent handoff summary using the same decision contract
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed
 aienvmp doctor --ci       # strict CI check for all warnings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {

package/src/commands/context.js

@@ -6,6 +6,7 @@ import { renderContext } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { recommendedActions } from "../actions.js";
 import { buildPlan, compactStepSummary } from "./plan.js";
+import { aiDecision } from "../decision.js";
 
 export async function contextWorkspace(args) {
   const dir = workspaceDir(args);
@@ -15,7 +16,7 @@ export async function contextWorkspace(args) {
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
-  const decision = contextDecision(warnings, intents);
+  const decision = aiDecision(warnings, intents);
   const actions = recommendedActions(manifest, { warnings, intents });
   const stepSummary = compactStepSummary(buildPlan(manifest, warnings, intents, policy));
   if (args.json) {
@@ -61,25 +62,3 @@ function inventorySummary(inventory = {}) {
     groups: Object.fromEntries(Object.entries(tools).map(([name, items]) => [name, items.length]))
   };
 }
-
-function contextDecision(warnings, intents) {
-  const reviewRequired = warnings.length > 0 || intents.length > 0;
-  return {
-    canProceed: !reviewRequired,
-    safeForProjectLocalWork: warnings.length === 0,
-    reviewRequired,
-    environmentChangeRequiresIntent: true,
-    globalEnvironmentChangesRequireUserApproval: true,
-    pendingIntentCount: intents.length,
-    mustNotDo: [
-      "do not change global runtimes without user approval",
-      "do not install or remove global package managers without user approval",
-      "do not change Docker daemon/context assumptions without user approval",
-      "do not ignore open intents or review-required warnings"
-    ],
-    recommendedNextActions: warnings.length
-      ? ["review warnings", "ask the user before environment changes", "record intent before changes"]
-      : ["continue with project-local work", "run aienvmp intent before environment changes"],
-    nextCommand: warnings.length ? "review warnings before changing environment" : "continue with project-local work"
-  };
-}

package/src/commands/handoff.js

@@ -6,6 +6,7 @@ import { renderHandoff } from "../render.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { changedTrust } from "../trust.js";
 import { recommendedActions } from "../actions.js";
+import { aiDecision } from "../decision.js";
 
 export async function handoffWorkspace(args) {
   const dir = workspaceDir(args);
@@ -48,6 +49,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
     status: reviewRequired ? "review-required" : "clear",
     trust: manifest.trust || {},
     schemaVersion: manifest.schemaVersion || 1,
+    decision: aiDecision(warnings, intents),
     workspace: manifest.workspace,
     safeRuntime: {
       node: manifest.runtimes?.node || "not detected",

package/src/commands/plan.js

@@ -6,6 +6,7 @@ import { intentsPath, manifestPath, planJsonPath, planMdPath, timelinePath, work
 import { renderPlan } from "../render.js";
 import { recommendedActions } from "../actions.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+import { aiDecision } from "../decision.js";
 
 export async function planWorkspace(args) {
   const dir = workspaceDir(args);
@@ -39,6 +40,7 @@ export function buildPlan(manifest, warnings = [], intents = [], policy = {}) {
     status,
     workspace: manifest.workspace || {},
     trust: manifest.trust || {},
+    decision: aiDecision(warnings, intents),
     policy: {
       node: policy.node || "not set",
       python: policy.python || "not set",

package/src/decision.js

@@ -0,0 +1,35 @@
+export function aiDecision(warnings = [], intents = []) {
+  const warningCodes = warnings.map((warning) => warning.code).filter(Boolean);
+  const reviewRequired = warnings.length > 0 || intents.length > 0;
+  const mode = reviewRequired ? "review-first" : "project-local-work";
+  return {
+    schemaVersion: 1,
+    mode,
+    canProceed: !reviewRequired,
+    canContinueProjectLocalWork: true,
+    canChangeEnvironmentWithoutReview: !reviewRequired,
+    safeForProjectLocalWork: warnings.length === 0,
+    reviewRequired,
+    warningCodes,
+    environmentChangeRequiresIntent: true,
+    globalEnvironmentChangesRequireUserApproval: true,
+    pendingIntentCount: intents.length,
+    mustNotDo: [
+      "do not change global runtimes without user approval",
+      "do not install or remove global package managers without user approval",
+      "do not change Docker daemon/context assumptions without user approval",
+      "do not ignore open intents or review-required warnings"
+    ],
+    recommendedNextActions: reviewRequired
+      ? ["review warnings and open intents", "ask the user before environment changes", "record intent before changes"]
+      : ["continue with project-local work", "run aienvmp intent before environment changes"],
+    requiredCommands: {
+      beforeEnvironmentChange: "aienvmp intent --actor agent:id --action planned-change --target <runtime|package-manager|docker>",
+      refreshAfterChange: "aienvmp sync",
+      recordAfterChange: "aienvmp record --actor agent:id --summary what-changed",
+      handoff: "aienvmp handoff --record --actor agent:id",
+      reviewPlan: "aienvmp plan"
+    },
+    nextCommand: reviewRequired ? "aienvmp plan" : "continue project-local work; use aienvmp intent before environment changes"
+  };
+}

package/src/render.js

@@ -92,6 +92,7 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "",
     `Status: ${status}`,
     `Next: ${next}`,
+    "Project-local work: allowed; environment changes require intent and review when warnings or open intents exist.",
     `Trust: ${manifest.trust?.state || "observed"} (verified requires human or CI)`,
     `Workspace: ${manifest.workspace.path}`,
     `Node: ${manifest.runtimes.node || "not detected"}`,
@@ -132,6 +133,7 @@ export function renderHandoff(handoff) {
     "# AI Handoff",
     "",
     `Status: ${handoff.status}`,
+    `Decision: ${handoff.decision?.mode || handoff.status}`,
     `Trust: ${handoff.trust?.state || "observed"} (not AI-verified)`,
     `Schema: ${handoff.schemaVersion}`,
     `Workspace: ${handoff.workspace?.path || "unknown"}`,
@@ -169,6 +171,7 @@ export function renderPlan(plan) {
     "# AI Environment Plan",
     "",
     `Status: ${plan.status}`,
+    `Decision: ${plan.decision?.mode || plan.status}`,
     `Generated: ${plan.generatedAt}`,
     `Workspace: ${plan.workspace?.path || "unknown"}`,
     "",