aienvmp 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.13
+
+- Added `recommendedActions` to AI handoff output.
+- Added a Recommended Actions dashboard card for human review.
+- Reused the same advisory action engine across context, doctor, handoff, and dashboard.
+
+## 0.1.12
+
+- Added AI-readable `recommendedActions` to `context --json` and `doctor --json`.
+- Added concise recommended actions to text context and doctor output.
+- Kept recommendations advisory-only; strict failure still requires `doctor --ci`.
+
 ## 0.1.11
 
 - Added bounded remediation details to security summaries, including fix versions and advisory references.

package/README.md

@@ -55,8 +55,8 @@ npx aienvmp snippet agents
 ```bash
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
-aienvmp context --json    # machine-readable AI decision context
-aienvmp handoff           # next-agent handoff summary
+aienvmp context --json    # machine-readable AI decision context + recommended actions
+aienvmp handoff           # next-agent handoff summary + recommended actions
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed
 aienvmp doctor --ci       # strict CI check

package/package.json

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

package/src/actions.js

@@ -0,0 +1,87 @@
+export function recommendedActions(manifest = {}, context = {}) {
+  const warnings = context.warnings || [];
+  const intents = context.intents || [];
+  const actions = [];
+
+  if (isStaleWarning(warnings)) {
+    actions.push(action("sync-snapshot", "high", "sync", "Refresh the environment snapshot before changing runtimes or package managers.", "aienvmp sync"));
+  }
+
+  if (intents.length) {
+    actions.push(action("review-open-intents", "high", "coordination", "Review or resolve open environment intents before another agent changes the environment.", "aienvmp context --json"));
+  }
+
+  if (warnings.some((warning) => warning.code === "conflicting-open-intents")) {
+    actions.push(action("coordinate-agents", "high", "coordination", "Multiple agents are planning changes to the same environment target. Coordinate with the user before proceeding."));
+  }
+
+  actions.push(...securityActions(manifest.security));
+
+  if (hasRuntimePolicyWarning(warnings)) {
+    actions.push(action("review-version-policy", "medium", "runtime", "Detected runtime or package manager policy drift. Prefer project-local version files and ask before global changes."));
+  }
+
+  if (warnings.some((warning) => warning.code === "handoff-stale")) {
+    actions.push(action("record-handoff", "medium", "handoff", "Record an AI handoff after environment changes so the next agent starts with current context.", "aienvmp handoff --record --actor agent:id"));
+  }
+
+  if (!actions.length) {
+    actions.push(action("continue-project-local", "low", "workflow", "Continue with project-local work. Record intent before environment changes.", "aienvmp intent --actor agent:id --action planned-change"));
+  }
+
+  return dedupeActions(actions).slice(0, 8);
+}
+
+function securityActions(security = {}) {
+  if (!security.enabled) return [];
+
+  const summary = security.summary || {};
+  const highRisk = Number(summary.critical || 0) > 0 || Number(summary.high || 0) > 0;
+  const packages = (security.topPackages || []).slice(0, 5);
+  if (!highRisk && !packages.length) return [];
+
+  const packageHints = packages.map((pkg) => {
+    const fix = pkg.fixVersions?.length ? `fix ${pkg.fixVersions.slice(0, 2).join(", ")}` : pkg.fixAvailable ? "fix available" : "review required";
+    return `${pkg.name} (${pkg.severity}, ${fix})`;
+  });
+
+  return [action(
+    "review-security-remediation",
+    highRisk ? "high" : "medium",
+    "security",
+    packageHints.length
+      ? `Review vulnerable packages before dependency or deployment changes: ${packageHints.join("; ")}.`
+      : "Review vulnerability summary before dependency or deployment changes.",
+    "aienvmp context --json"
+  )];
+}
+
+function action(id, priority, category, summary, command = "") {
+  return { id, priority, category, summary, command };
+}
+
+function dedupeActions(actions) {
+  const seen = new Set();
+  return actions.filter((item) => {
+    if (seen.has(item.id)) return false;
+    seen.add(item.id);
+    return true;
+  });
+}
+
+function isStaleWarning(warnings) {
+  return warnings.some((warning) => warning.code === "manifest-stale" || warning.code === "stale-open-intent");
+}
+
+function hasRuntimePolicyWarning(warnings) {
+  return warnings.some((warning) => [
+    "node-version-mismatch",
+    "python-version-mismatch",
+    "mixed-node-lockfiles",
+    "python-missing",
+    "docker-missing",
+    "policy-node-mismatch",
+    "policy-python-mismatch",
+    "policy-package-manager-mismatch"
+  ].includes(warning.code));
+}

package/src/commands/context.js

@@ -4,6 +4,7 @@ import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderContext } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function contextWorkspace(args) {
   const dir = workspaceDir(args);
@@ -14,10 +15,12 @@ export async function contextWorkspace(args) {
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const decision = contextDecision(warnings, intents);
+  const actions = recommendedActions(manifest, { warnings, intents });
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
       decision,
+      recommendedActions: actions,
       trust: manifest.trust || {},
       guidance: decision,
       workspace: manifest.workspace,
@@ -35,7 +38,7 @@ export async function contextWorkspace(args) {
     }, null, 2));
     return;
   }
-  console.log(renderContext(manifest, timeline, warnings, intents, policy));
+  console.log(renderContext(manifest, timeline, warnings, intents, policy, actions));
 }
 
 function securitySummary(security = {}) {

package/src/commands/dash.js

@@ -7,6 +7,7 @@ import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { dashboardPath, intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderDashboard } from "../render.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function dashWorkspace(args) {
   const dir = workspaceDir(args);
@@ -16,7 +17,7 @@ export async function dashWorkspace(args) {
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
-  const html = renderDashboard(manifest, timeline, warnings, intents, policy);
+  const html = renderDashboard({ ...manifest, recommendedActions: recommendedActions(manifest, { warnings, intents }) }, timeline, warnings, intents, policy);
   const out = dashboardPath(dir);
   await fs.mkdir(path.dirname(out), { recursive: true });
   await fs.writeFile(out, html, "utf8");

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import { readJson } from "../fsutil.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
+import { recommendedActions } from "../actions.js";
 
 export async function doctorWorkspace(args) {
   const dir = workspaceDir(args);
@@ -12,13 +13,15 @@ export async function doctorWorkspace(args) {
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
+  const actions = recommendedActions(manifest, { warnings, intents });
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "warning" : "ok",
       trust: manifest.trust || {},
       policy,
       openIntentCount: intents.length,
-      warnings
+      warnings,
+      recommendedActions: actions
     }, null, 2));
     if (args.ci && warnings.length) {
       process.exitCode = 1;
@@ -32,6 +35,10 @@ export async function doctorWorkspace(args) {
   for (const warning of warnings) {
     console.log(`[${warning.code}] ${warning.message}`);
   }
+  console.log("recommended actions:");
+  for (const item of actions) {
+    console.log(`- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`);
+  }
   console.log("doctor: warnings are non-blocking by default; pass --ci to fail automation.");
   if (args.ci) {
     process.exitCode = 1;

package/src/commands/handoff.js

@@ -5,6 +5,7 @@ import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.
 import { renderHandoff } from "../render.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
 import { changedTrust } from "../trust.js";
+import { recommendedActions } from "../actions.js";
 
 export async function handoffWorkspace(args) {
   const dir = workspaceDir(args);
@@ -42,6 +43,7 @@ async function recordHandoff(file, handoff, actor) {
 
 export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
+  const actions = recommendedActions(manifest, { warnings, intents });
   return {
     status: reviewRequired ? "review-required" : "clear",
     trust: manifest.trust || {},
@@ -63,6 +65,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
     },
     openIntents: intents.slice(-5).reverse(),
     warnings,
+    recommendedActions: actions,
     recentChanges: timeline.slice(-5).reverse(),
     mustNotDo: [
       "do not change global runtimes without user approval",

package/src/render.js

@@ -84,7 +84,7 @@ Before changing runtimes, package managers, Docker settings, global packages, or
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
 
-export function renderContext(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
+export function renderContext(manifest, timeline = [], warnings = [], intents = [], policy = {}, recommendedActions = []) {
   const status = warnings.length ? "review-required" : "clear";
   const next = warnings.length ? "Review warnings before changing the environment." : "Continue with project-local work. Record intent before environment changes.";
   return [
@@ -115,6 +115,9 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "Warnings:",
     ...(warnings.length ? warnings.map((w) => `- ${w.message}`) : ["- none"]),
     "",
+    "Recommended actions:",
+    ...(recommendedActions.length ? recommendedActions.map((item) => `- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`) : ["- none"]),
+    "",
     "Open intents:",
     ...(intents.length ? intents.slice(-5).reverse().map((i) => `- ${i.actor}: ${i.action}`) : ["- none"]),
     "",
@@ -146,6 +149,9 @@ export function renderHandoff(handoff) {
     "Warnings:",
     ...(handoff.warnings.length ? handoff.warnings.map((w) => `- ${w.message}`) : ["- none"]),
     "",
+    "Recommended actions:",
+    ...(handoff.recommendedActions?.length ? handoff.recommendedActions.map((item) => `- [${item.priority}] ${item.summary}${item.command ? ` (${item.command})` : ""}`) : ["- none"]),
+    "",
     "Recent changes:",
     ...(handoff.recentChanges.length ? handoff.recentChanges.map((t) => `- ${formatTimeline(t)}`) : ["- none"]),
     "",
@@ -231,6 +237,8 @@ const warnHtml=warnings.length?'<div class="warnings">'+warnings.map(w=>\`<div c
 const timelineHtml=timeline.length?'<div class="timeline">'+timeline.slice(-8).reverse().map(t=>\`<div class="event"><time>\${esc(t.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(t.actor||'system')}</b> \${esc(timelineLabel(t))}</div></div>\`).join('')+'</div>':'<div class="okline">No previous environment changes recorded.</div>';
 const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reverse().map(i=>\`<div class="event"><time>\${esc(i.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(i.actor)}</b> plans \${esc(i.action)}</div></div>\`).join('')+'</div>':'<div class="okline">No pending agent intents recorded.</div>';
 const policyHtml=entries(policy).length?\`<table>\${rows(policy)}</table>\`:'<div class="okline">No explicit version policy set.</div>';
+const actions=manifest.recommendedActions||[];
+const actionsHtml=actions.length?'<div class="timeline">'+actions.slice(0,6).map(a=>\`<div class="event"><time>\${esc(a.priority)}</time><div><b>\${esc(a.category)}</b> \${esc(a.summary)}\${a.command?\`<div class="path">\${esc(a.command)}</div>\`:''}</div></div>\`).join('')+'</div>':'<div class="okline">No recommended actions. Continue project-local work.</div>';
 const card=(title,badge,body)=>\`<section class="card"><div class="card-head"><h2>\${title}</h2>\${badge||''}</div>\${body}</section>\`;
 const reviewRequired=warnings.length>0||intents.length>0;
 const recentChanges=timeline.slice(-8).length;
@@ -270,6 +278,8 @@ document.getElementById('app').innerHTML=\`
     \${card('Security Summary',sec.enabled?'<span class="pill warn">security</span>':'<span class="pill off">basic</span>',securityHtml)}
   </div>
   <aside>
+    \${card('Recommended Actions','<span class="pill">'+actions.length+' actions</span>',actionsHtml)}
+    <div style="height:14px"></div>
     \${card('Environment Health',warnings.length?'<span class="pill warn">attention</span>':'<span class="pill">clear</span>',warnHtml)}
     <div style="height:14px"></div>
     \${card('Version Policy','<span class="pill">'+entries(policy).length+' rules</span>',policyHtml)}