aienvmp 0.1.44 → 0.1.46

package/BUGFIXES.md

@@ -52,6 +52,18 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `doctor`, status/context, handoff, and the dashboard now expose same-target multi-agent records through advisory warnings and `agentActivity`.
 - Verification: tests cover multi-agent record detection, later handoff reset, status JSON, handoff text, dashboard HTML, and recommended actions.
 
+### Post-change loop was too many commands for routine AI handoff
+
+- Issue: after an environment change, agents had to remember separate record, sync, status, and handoff commands.
+- Fix: `aienvmp checkpoint` now performs the post-change loop and records an explicit sync ledger entry so follow-ups can be closed.
+- Verification: checkpoint tests cover text/JSON output, status artifact refresh, timeline entries, handoff recording, and cleared follow-ups.
+
+### Light SBOM risk required too much parsing
+
+- Issue: AI consumers could see package and vulnerability details, but had to infer risk level and next commands from several nested fields.
+- Fix: `lightSbom.riskSummary` and preflight `sbomRisk` now provide a compact risk score, signals, review targets, and advisory next steps.
+- Verification: tests cover risk scoring, top-risk severity fallback, scanner-off guidance, status/context exposure, dashboard rendering, and recommended actions.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.46
+
+- Added `lightSbom.riskSummary` with compact risk level, score, scanner state, signals, review targets, and next commands.
+- Added `sbomRisk` to the shared AI preflight contract so status/context consumers can read SBOM risk without deep parsing.
+- Surfaced SBOM risk in `context --json`, `AIENV.md`, and the dashboard Light SBOM card.
+- Added recommended actions for read-only security scans and high light-SBOM risk review.
+- Used top-risk package severity as a fallback when scanner summary severity counts are incomplete.
+- Updated dependency change hints to point agents to `aienvmp checkpoint` after accepted dependency changes.
+- Added regression tests for risk scoring, scanner-off guidance, status/context outputs, dashboard rendering, and recommended actions.
+
+## 0.1.45
+
+- Added `aienvmp checkpoint` as a one-command post-environment-change flow for record, sync, status, and handoff.
+- Added quiet command support so checkpoint can compose existing commands without noisy intermediate output.
+- Added checkpoint sync ledger entries so follow-up detection can prove the refresh step happened.
+- Added checkpoint guidance to the shared preflight, decision, manifest, dependency protocol, and status outputs.
+- Updated AIENV, handoff, plan, dashboard, and agent pointer rendering to prefer checkpoint after environment changes.
+- Shortened the README environment-change flow to intent plus checkpoint.
+- Added checkpoint regression coverage for JSON output, ledger updates, follow-up closure, status artifacts, and rendered guidance.
+
 ## 0.1.44
 
 - Added multi-agent record warnings when multiple agents record environment changes for the same target after the last handoff.

package/README.md

@@ -23,10 +23,7 @@ Before environment changes:
 
 ```bash
 npx aienvmp intent --actor agent:codex --action "change dependency" --target dependency
-npx aienvmp record --actor agent:codex --summary "dependency-change" --target dependency
-npx aienvmp sync
-npx aienvmp status --write
-npx aienvmp handoff --record --actor agent:codex
+npx aienvmp checkpoint --actor agent:codex --summary "dependency-change" --target dependency
 ```
 
 Use `--dir <workspace>` when AI or CI runs outside the target project.
@@ -50,6 +47,7 @@ AIENV.md                 # Markdown env map for AI agents
 - `schema --json` prints the stable AI-readable output contract without scanning.
 - `status.json.nextAgent` tells the next AI what to read and whether to review first.
 - `dependencyReadSet` lists manifests and lockfiles before package or security changes.
+- `sbomRisk` gives AI a compact light-SBOM risk level, signals, and next command.
 - `coordination.conflictTargets` shows where multiple agents are planning changes.
 - `agentActivity.multiActorTargets` shows where multiple agents actually recorded env changes.
 - `followUps` shows records that still need `sync`, `status`, or `handoff`.
@@ -79,6 +77,7 @@ aienvmp plan --write            # read-only action plan
 aienvmp handoff --record        # next-agent summary
 aienvmp intent                  # record planned env change
 aienvmp record                  # record what changed
+aienvmp checkpoint              # record + sync + status + handoff after env change
 aienvmp doctor --strict security|policy|coordination|all
 ```
 

package/package.json

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

package/src/actions.js

@@ -20,6 +20,7 @@ export function recommendedActions(manifest = {}, context = {}) {
   }
 
   actions.push(...securityActions(manifest.security));
+  actions.push(...sbomRiskActions(manifest.lightSbom?.riskSummary));
 
   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."));
@@ -36,6 +37,18 @@ export function recommendedActions(manifest = {}, context = {}) {
   return dedupeActions(actions).slice(0, 8);
 }
 
+function sbomRiskActions(risk = {}) {
+  const actions = [];
+  if (!risk.level) return actions;
+  if (risk.scanner === "off" && risk.vulnerabilityCount === 0) {
+    actions.push(action("scan-sbom-risk", "medium", "security", "Run a read-only security scan before dependency or release decisions.", "aienvmp sync --security"));
+  }
+  if (["urgent", "high"].includes(risk.level)) {
+    actions.push(action("review-sbom-risk", "high", "security", `Review light SBOM risk summary before dependency changes: ${(risk.signals || []).slice(0, 2).join("; ") || risk.level}.`, "aienvmp plan --write"));
+  }
+  return actions;
+}
+
 function securityActions(security = {}) {
   if (!security.enabled) return [];
 

package/src/cli.js

@@ -14,6 +14,7 @@ import { handoffWorkspace } from "./commands/handoff.js";
 import { planWorkspace } from "./commands/plan.js";
 import { statusWorkspace } from "./commands/status.js";
 import { schemaWorkspace } from "./commands/schema.js";
+import { checkpointWorkspace } from "./commands/checkpoint.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -32,7 +33,8 @@ const commands = new Map([
   ["handoff", handoffWorkspace],
   ["plan", planWorkspace],
   ["status", statusWorkspace],
-  ["schema", schemaWorkspace]
+  ["schema", schemaWorkspace],
+  ["checkpoint", checkpointWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -108,6 +110,7 @@ Usage:
   aienvmp context [--dir .] [--json]
   aienvmp status [--dir .] [--json] [--write] [--quiet]
   aienvmp handoff [--dir .] [--json] [--record --actor agent:id]
+  aienvmp checkpoint [--dir .] --actor agent:id --summary "what changed" [--target dependency] [--json]
   aienvmp plan [--dir .] [--json] [--write]
   aienvmp schema [--json]
 
@@ -116,6 +119,7 @@ Common:
   aienvmp status    print one simple environment decision; --write saves .aienvmp/status.json
   aienvmp context   print the AI preflight brief
   aienvmp handoff   print the next-agent handoff summary
+  aienvmp checkpoint record, sync, status, and handoff after an env change
   aienvmp plan      print a read-only AI environment action plan
   aienvmp schema    print the stable AI-readable output contract
   aienvmp snippet   print an AGENTS.md pointer snippet
@@ -127,6 +131,7 @@ Advanced:
   aienvmp intent [--dir .] --actor agent:codex --action "install pnpm"
   aienvmp resolve [--dir .] --actor human:you --id <intent-id> [--status resolved|cancelled]
   aienvmp record [--dir .] --actor agent:codex --summary "updated .nvmrc" [--target node] [--before 20] [--after 24]
+  aienvmp checkpoint [--dir .] --actor agent:codex --summary "updated dependency" [--target dependency]
   aienvmp snippet [agents|claude|gemini] [--write AGENTS.md]
   aienvmp compile [--dir .]
   aienvmp diff [--dir .]

package/src/commands/checkpoint.js

@@ -0,0 +1,68 @@
+import { handoffWorkspace } from "./handoff.js";
+import { recordWorkspace } from "./record.js";
+import { statusWorkspace } from "./status.js";
+import { syncWorkspace } from "./sync.js";
+import { appendJsonLine } from "../fsutil.js";
+import { timelinePath, workspaceDir } from "../paths.js";
+import { observedTrust } from "../trust.js";
+
+export async function checkpointWorkspace(args) {
+  const actor = required(args.actor, "actor");
+  const summary = required(args.summary || args.change, "summary");
+  const quiet = args.quiet || args.json;
+  const base = { ...args, actor, summary, quiet: true };
+
+  const record = await recordWorkspace(base);
+  const sync = await syncWorkspace({ ...base, json: false, quiet: true });
+  await recordCheckpointSync(base);
+  const handoff = await handoffWorkspace({ ...base, json: false, record: true, quiet: true });
+  const status = await statusWorkspace({ ...base, json: false, write: true, quiet: true });
+
+  const result = {
+    status: "ok",
+    mode: "post-environment-change",
+    actor,
+    summary,
+    target: args.target || "",
+    record,
+    outputs: sync.outputs,
+    state: status.state,
+    warnings: status.counts?.warnings || 0,
+    followUps: status.followUps || [],
+    agentActivity: status.agentActivity || {},
+    handoff: {
+      status: handoff.status,
+      recommendedNext: handoff.recommendedNext
+    },
+    next: "Share .aienvmp/status.json or run `aienvmp context --json` before another environment change."
+  };
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!quiet) {
+    console.log(`checkpoint: ${result.state}`);
+    console.log(`record: ${record.summary}${record.target ? ` (${record.target})` : ""}`);
+    console.log(`status: ${result.outputs.status}`);
+    console.log(`handoff: ${handoff.status}`);
+    console.log(`next: ${result.next}`);
+  }
+
+  return result;
+}
+
+async function recordCheckpointSync(args) {
+  const now = new Date();
+  await appendJsonLine(timelinePath(workspaceDir(args)), {
+    at: now.toISOString(),
+    actor: args.actor,
+    type: "sync",
+    summary: "checkpoint sync",
+    target: "",
+    trust: observedTrust(now)
+  });
+}
+
+function required(value, name) {
+  if (!value) throw new Error(`checkpoint: --${name} is required`);
+  return String(value);
+}

package/src/commands/context.js

@@ -27,6 +27,7 @@ export async function contextWorkspace(args) {
       status: warnings.length ? "review-required" : "clear",
       preflight,
       coordination: preflight.coordination,
+      sbomRisk: preflight.sbomRisk,
       followUps: preflight.followUps,
       decision,
       enforcement: enforcementAdvice(warnings),
@@ -75,6 +76,7 @@ function lightSbomSummary(lightSbom = {}) {
       guidance: "No lockfile policy detected."
     },
     dependencyChangeHints: (lightSbom.dependencyChangeHints || []).slice(0, 8),
+    riskSummary: lightSbom.riskSummary || {},
     source: lightSbom.source || {},
     confidence: lightSbom.confidence || {},
     limitations: lightSbom.limitations || [],

package/src/commands/handoff.js

@@ -24,7 +24,7 @@ export async function handoffWorkspace(args) {
 
   if (args.json) {
     console.log(JSON.stringify(handoff, null, 2));
-  } else {
+  } else if (!args.quiet) {
     console.log(renderHandoff(handoff));
   }
   return handoff;
@@ -95,6 +95,7 @@ function dependencyHandoffSummary(preflight = {}) {
       packageManagerPolicy: protocol.packageManagerPolicy || "not-detected",
       recordIntent: protocol.commands?.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency",
       recordAfterChange: protocol.commands?.recordAfterChange || "aienvmp record --actor agent:id --summary dependency-change --target dependency",
+      checkpointAfterChange: protocol.commands?.checkpointAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency",
       handoff: protocol.commands?.handoff || "aienvmp handoff --record --actor agent:id"
     }
   };

package/src/commands/plan.js

@@ -103,7 +103,7 @@ function environmentSteps(warnings = []) {
 }
 
 function environmentCategory(code = "") {
-  if (["conflicting-open-intents", "stale-open-intent", "handoff-stale"].includes(code)) return "coordination";
+  if (["conflicting-open-intents", "stale-open-intent", "handoff-stale", "multi-agent-records"].includes(code)) return "coordination";
   if (code.includes("docker")) return "container";
   if (code.includes("lockfile") || code.includes("package-manager")) return "package-manager";
   if (code.includes("node") || code.includes("python") || code.includes("version") || code.includes("runtime")) return "runtime";
@@ -115,13 +115,13 @@ function environmentStepLines(code = "") {
     "Read .nvmrc and the detected Node version before changing tools.",
     "Prefer project-local version managers such as nvm, mise, or asdf.",
     "Ask before changing global Node or npm installations.",
-    "Run aienvmp sync and record the change after alignment."
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target node after alignment."
   ];
   if (code === "python-version-mismatch") return [
     "Read .python-version and the detected Python version before changing tools.",
     "Prefer project-local virtual environments or version managers.",
     "Ask before changing global Python installations.",
-    "Run aienvmp sync and record the change after alignment."
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target python after alignment."
   ];
   if (code === "mixed-node-lockfiles" || code === "package-manager-policy-mismatch") return [
     "Identify the intended package manager from project policy and lockfiles.",
@@ -133,13 +133,13 @@ function environmentStepLines(code = "") {
     "Confirm whether the Python project is active.",
     "Prefer project-local Python setup before global installation.",
     "Ask before installing a global Python runtime.",
-    "Run aienvmp sync after setup."
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target python after setup."
   ];
   if (code === "docker-missing") return [
     "Confirm whether Docker is required for the current task.",
     "Do not change Docker daemon or context without user approval.",
     "Document fallback commands if Docker is unavailable.",
-    "Run aienvmp sync after Docker availability changes."
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target docker after Docker availability changes."
   ];
   if (code === "manifest-stale") return [
     "Run aienvmp sync before environment changes.",
@@ -158,10 +158,14 @@ function environmentStepLines(code = "") {
     "Run aienvmp handoff --record --actor agent:id before the next AI continues.",
     "Review recent changes before new environment work."
   ];
+  if (code === "multi-agent-records") return [
+    "Review agentActivity and recent timeline records for the shared target.",
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target environment before more environment work."
+  ];
   return [
     "Review the warning before changing environment state.",
     "Ask before global environment changes.",
-    "Run aienvmp sync after any accepted change."
+    "Run aienvmp checkpoint --actor agent:id --summary what-changed --target environment after any accepted change."
   ];
 }
 

package/src/commands/record.js

@@ -22,7 +22,8 @@ export async function recordWorkspace(args) {
     trust: changedTrust(now, requiresReview)
   };
   await appendJsonLine(timelinePath(dir), entry);
-  console.log(`recorded ${entry.type} by ${actor}`);
+  if (!args.quiet) console.log(`recorded ${entry.type} by ${actor}`);
+  return entry;
 }
 
 export function followUpForRecord(record = {}) {
@@ -42,6 +43,7 @@ export function followUpForRecord(record = {}) {
       ? "Dependency or security records should refresh the env map and handoff context."
       : "Environment records should refresh the env map and handoff context.",
     commands: [
+      `aienvmp checkpoint --actor agent:id --summary ${isDependency ? "dependency-change" : "what-changed"} --target ${isDependency ? "dependency" : target || "environment"}`,
       "aienvmp sync",
       "aienvmp status --write",
       "aienvmp handoff --record --actor agent:id"

package/src/commands/status.js

@@ -25,6 +25,7 @@ export async function statusWorkspace(args) {
     console.log(`next: ${output.nextCommand}`);
     console.log(`ai: ${output.quickstart.readFirst} -> ${output.quickstart.detailCommand}`);
     console.log(`intent: ${output.intentTargets[0]?.command || output.commands.recordIntent}`);
+    console.log(`checkpoint: ${output.commands.checkpoint}`);
     console.log(`handoff: ${output.nextAgent.handoffCommand}`);
     console.log(`strict: ${output.enforcement.recommendedCommand}`);
     if (artifact) console.log(`status: ${artifact}`);

package/src/contract.js

@@ -4,7 +4,7 @@ export function preflightContract() {
     version: 1,
     stability: "additive",
     requiredFields: ["schemaVersion", "state", "decision", "quickstart", "commands", "artifacts"],
-    aiEntryFields: ["state", "summary", "nextAgent", "coordination", "agentActivity", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "nextAgent", "coordination", "agentActivity", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }

package/src/decision.js

@@ -25,6 +25,7 @@ export function aiDecision(warnings = [], intents = []) {
       : ["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>",
+      checkpointAfterChange: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment",
       refreshAfterChange: "aienvmp sync",
       recordAfterChange: "aienvmp record --actor agent:id --summary what-changed",
       handoff: "aienvmp handoff --record --actor agent:id",

package/src/dependencies.js

@@ -108,6 +108,7 @@ export function buildLightSbom(snapshot = {}, security = {}) {
       transitiveOrUnmatchedVulnerablePackages: transitiveOrUnmatched.length
     },
     topRisk,
+    riskSummary: lightSbomRiskSummary({ packages, security, directVulnerable, transitiveOrUnmatched, topRisk, lockfiles: snapshot.lockfiles || [] }),
     packageManagerPolicy: packageManagerPolicy(snapshot.lockfiles || []),
     dependencyChangeHints: dependencyChangeHints(packages, topRisk, snapshot.lockfiles || []),
     aiUse: {
@@ -119,6 +120,74 @@ export function buildLightSbom(snapshot = {}, security = {}) {
   };
 }
 
+export function lightSbomRiskSummary({ packages = [], security = {}, directVulnerable = [], transitiveOrUnmatched = [], topRisk = [], lockfiles = [] } = {}) {
+  const signals = [];
+  let score = 0;
+  const critical = Math.max(Number(security.summary?.critical || 0), topRisk.filter((pkg) => pkg.severity === "critical").length);
+  const high = Math.max(Number(security.summary?.high || 0), topRisk.filter((pkg) => pkg.severity === "high").length);
+  const total = Number(security.summary?.total || 0);
+  if (critical > 0) {
+    score += 45;
+    signals.push(`${critical} critical vulnerability finding(s)`);
+  }
+  if (high > 0) {
+    score += 30;
+    signals.push(`${high} high vulnerability finding(s)`);
+  }
+  if (directVulnerable.length) {
+    score += 15;
+    signals.push(`${directVulnerable.length} vulnerable direct dependency package(s)`);
+  }
+  if (transitiveOrUnmatched.length) {
+    score += 8;
+    signals.push(`${transitiveOrUnmatched.length} vulnerable transitive or unmatched package(s)`);
+  }
+  if (packageManagerPolicy(lockfiles).status === "review-required") {
+    score += 10;
+    signals.push("mixed package manager lockfiles");
+  }
+  if (packages.length && security.enabled !== true) {
+    score += 5;
+    signals.push("security scanner summary is off");
+  }
+  const level = score >= 90 ? "urgent" : score >= 60 ? "high" : score >= 30 ? "medium" : score > 0 ? "low" : "clear";
+  const reviewTargets = [
+    ...new Set([
+      ...topRisk.map((pkg) => pkg.manifest).filter(Boolean),
+      ...topRisk.map((pkg) => pkg.name).filter(Boolean).slice(0, 5)
+    ])
+  ].slice(0, 8);
+  return {
+    level,
+    score,
+    signals,
+    scanner: security.enabled ? "enabled" : "off",
+    vulnerabilityCount: total,
+    directVulnerablePackages: directVulnerable.length,
+    reviewTargets,
+    next: riskNext(level, security.enabled, topRisk),
+    commands: riskCommands(level, security.enabled)
+  };
+}
+
+function riskNext(level, securityEnabled, topRisk = []) {
+  if (!securityEnabled) return "Run read-only security scan before dependency or release decisions.";
+  if (level === "urgent" || level === "high") return "Review dependency read set and topRisk before remediation; do not auto-fix without user approval.";
+  if (topRisk.length) return "Review topRisk packages before dependency changes.";
+  return "No SBOM risk signal requires action in the lightweight snapshot.";
+}
+
+function riskCommands(level, securityEnabled) {
+  const commands = [];
+  if (!securityEnabled) commands.push("aienvmp sync --security");
+  if (["urgent", "high", "medium"].includes(level)) {
+    commands.push("aienvmp intent --actor agent:id --action dependency-review --target dependency");
+    commands.push("aienvmp plan --write");
+  }
+  commands.push("aienvmp checkpoint --actor agent:id --summary dependency-review --target dependency");
+  return commands;
+}
+
 function packageManagerPolicy(lockfiles = []) {
   const byEcosystem = {};
   for (const lockfile of lockfiles) {
@@ -196,8 +265,7 @@ function dependencyChangeHints(packages = [], topRisk = [], lockfiles = []) {
     ],
     afterChange: [
       "Run project tests or the narrowest relevant validation.",
-      "Run aienvmp sync.",
-      "Record the dependency change with aienvmp record."
+      "Run aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency."
     ]
   }));
 }

package/src/manifest.js

@@ -42,7 +42,8 @@ export async function buildManifest(dir, options = {}) {
       handoffCommand: "aienvmp handoff",
       intentCommand: "aienvmp intent --actor agent:id --action planned-change",
       recordCommand: "aienvmp record --actor agent:id --summary what-changed",
-      afterEnvironmentChange: ["aienvmp sync"],
+      checkpointCommand: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment",
+      afterEnvironmentChange: ["aienvmp checkpoint --actor agent:id --summary what-changed --target environment"],
       trustModel: {
         agentWritable: ["observed", "planned", "changed", "review", "stale"],
         verifiedRequires: "human-or-ci",

package/src/preflight.js

@@ -16,6 +16,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   const coordination = coordinationSummary(intents);
   const followUps = pendingFollowUps(timeline);
   const agentActivity = agentActivitySummary(timeline);
+  const sbomRisk = manifest.lightSbom?.riskSummary || {};
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -57,6 +58,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     nextAgent: nextAgentHint(state, dependencyReadSet, dependencyChangeProtocol),
     coordination,
     agentActivity,
+    sbomRisk,
     followUps,
     intentTargets,
     dependencyReadSet,
@@ -76,6 +78,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
       context: "aienvmp context --json",
       plan: "aienvmp plan --write",
       handoff: "aienvmp handoff --record --actor agent:id",
+      checkpoint: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment",
       recordIntent: intentTargets[0]?.command || "aienvmp intent --actor agent:id --action planned-change"
     },
     topAction,
@@ -220,6 +223,7 @@ function dependencyProtocol(manifest = {}, dependencyReadSet = []) {
       recordIntent: "aienvmp intent --actor agent:id --action planned-change --target dependency",
       refreshAfterChange: "aienvmp sync",
       recordAfterChange: "aienvmp record --actor agent:id --summary dependency-change --target dependency",
+      checkpointAfterChange: "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency",
       handoff: "aienvmp handoff --record --actor agent:id"
     },
     mustNotDo: [
@@ -335,7 +339,8 @@ function agentQuickstart(reviewRequired) {
     readFirst: "aienvmp status --write",
     detailCommand: "aienvmp context --json",
     beforeEnvironmentChange: "aienvmp intent --actor agent:id --action planned-change --target <runtime|package-manager|docker|dependency>",
-    afterEnvironmentChange: "aienvmp sync && aienvmp record --actor agent:id --summary what-changed",
+    afterEnvironmentChange: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment",
+    checkpointAfterChange: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment",
     handoff: "aienvmp handoff --record --actor agent:id",
     rule: reviewRequired
       ? "Review warnings or open intents before environment changes; project-local work may continue."

package/src/render.js

@@ -13,9 +13,7 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push("2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.");
   lines.push("3. Ask the user before changing global environment state.");
   lines.push("4. Record planned environment changes with `aienvmp intent --actor agent:id --action planned-change`.");
-  lines.push("5. After environment changes, run `aienvmp sync`.");
-  lines.push("6. Record what changed with `aienvmp record --actor agent:id --summary what-changed`.");
-  lines.push("7. At handoff, run `aienvmp handoff --record --actor agent:id`.", "");
+  lines.push("5. After environment changes, run `aienvmp checkpoint --actor agent:id --summary what-changed --target environment`.", "");
   lines.push(...preflightLines(manifest.preflight), "");
   lines.push("## Current Policy", "");
   lines.push(...policyLines(policy));
@@ -107,7 +105,7 @@ function preflightLines(preflight = {}) {
     lines.push(`- Mode: ${dependencyProtocol.mode}`);
     lines.push(`- Package manager policy: ${dependencyProtocol.packageManagerPolicy}`);
     lines.push(`- Intent: \`${dependencyProtocol.commands.recordIntent}\``);
-    lines.push(`- After change: \`${dependencyProtocol.commands.refreshAfterChange}\` then \`${dependencyProtocol.commands.recordAfterChange}\``);
+    lines.push(`- After change: \`${dependencyProtocol.commands.checkpointAfterChange || dependencyProtocol.commands.recordAfterChange}\``);
     lines.push(`- Handoff: \`${dependencyProtocol.commands.handoff}\``);
     for (const item of dependencyProtocol.mustNotDo.slice(0, 3)) lines.push(`- Must not: ${item}`);
   }
@@ -127,8 +125,7 @@ Before changing runtimes, package managers, Docker settings, global packages, or
 3. Read \`AIENV.md\`.
 4. If status or context says \`review-required\`, ask the user before changing the environment.
 5. Record planned environment changes with the recommended target, for example \`aienvmp intent --actor agent:id --action planned-change --target dependency\`.
-6. After environment changes, run \`aienvmp sync\` and \`aienvmp record --actor agent:id --summary what-changed\`.
-7. At handoff, run \`aienvmp handoff --record --actor agent:id\`.
+6. After environment changes, run \`aienvmp checkpoint --actor agent:id --summary what-changed --target environment\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
@@ -160,9 +157,7 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "- Treat policy mismatches as review-required, not as permission to break ongoing operations.",
     "- Prefer project-local version files and local environments.",
     "- Before planned env changes, run `aienvmp intent --actor agent:id --action planned-change`.",
-    "- After env changes, run `aienvmp sync`.",
-    "- Then run `aienvmp record --actor agent:id --summary what-changed`.",
-    "- Before handing work to another AI, run `aienvmp handoff --record --actor agent:id`.",
+    "- After env changes, run `aienvmp checkpoint --actor agent:id --summary what-changed --target environment`.",
     "",
     "Warnings:",
     ...(warnings.length ? warnings.map((w) => `- ${w.message}`) : ["- none"]),
@@ -254,7 +249,7 @@ function dependencyHandoffLines(dependencyHandoff = {}) {
     lines.push("- Read: no dependency files detected");
   }
   lines.push(`- Intent: ${protocol.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency"}`);
-  lines.push(`- After change: ${protocol.recordAfterChange || "aienvmp record --actor agent:id --summary dependency-change --target dependency"}`);
+  lines.push(`- After change: ${protocol.checkpointAfterChange || protocol.recordAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"}`);
   lines.push(`- Handoff: ${protocol.handoff || "aienvmp handoff --record --actor agent:id"}`);
   return lines;
 }
@@ -304,7 +299,7 @@ function dependencyProtocolPlanLines(protocol = {}) {
     `- Mode: ${protocol.mode || "advisory"}`,
     `- Package manager policy: ${protocol.packageManagerPolicy || "not-detected"}`,
     `- Intent: ${protocol.commands.recordIntent}`,
-    `- After change: ${protocol.commands.refreshAfterChange}; ${protocol.commands.recordAfterChange}`,
+    `- After change: ${protocol.commands.checkpointAfterChange || `${protocol.commands.refreshAfterChange}; ${protocol.commands.recordAfterChange}`}`,
     ...(protocol.mustNotDo || []).slice(0, 3).map((item) => `- Must not: ${item}`)
   ];
 }
@@ -421,10 +416,12 @@ const lightSbom=manifest.lightSbom||{};
 const lightSbomSummary=lightSbom.summary||{};
 const pmPolicy=lightSbom.packageManagerPolicy||{};
 const topRisk=lightSbom.topRisk||[];
+const riskSummary=lightSbom.riskSummary||{};
 const dependencyHints=lightSbom.dependencyChangeHints||[];
 const dependencyHintsHtml=dependencyHints.length?'<div class="timeline">'+dependencyHints.slice(0,5).map(h=>\`<div class="event"><time>\${esc(h.ecosystem||'deps')}</time><div><b>\${esc(h.manifest)}</b> <code>\${esc(h.manager||'unknown')}</code> \${esc(h.packages||0)} packages\${h.riskPackages?.length?\`<div class="path">risk: \${esc(h.riskPackages.map(p=>p.name).join(', '))}</div>\`:''}<div class="path">\${esc((h.groups||[]).join(', ')||'no groups')}\${h.lockfiles?.length?\` / lockfiles: \${esc(h.lockfiles.map(l=>l.file).join(', '))}\`:''}</div></div></div>\`).join('')+'</div>':'<div class="okline">No dependency change hints available.</div>';
 const pmPolicyHtml='<table><tr><th>Status</th><td><code>'+esc(pmPolicy.status||'no-lockfile')+'</code></td></tr><tr><th>Guidance</th><td>'+esc(pmPolicy.guidance||'No lockfile policy detected.')+'</td></tr></table>';
-const lightSbomHtml=\`<table><tr><th>Packages</th><td><code>\${esc(lightSbomSummary.packages||0)}</code></td></tr><tr><th>Vulnerabilities</th><td><code>\${esc(lightSbomSummary.vulnerabilities||0)}</code></td></tr><tr><th>Direct vulnerable</th><td><code>\${esc(lightSbomSummary.directVulnerablePackages||0)}</code></td></tr><tr><th>Manifests</th><td><code>\${esc((lightSbomSummary.manifests||[]).join(', ')||'none')}</code></td></tr><tr><th>Lockfiles</th><td><code>\${esc((lightSbomSummary.lockfiles||[]).map(l=>l.file).join(', ')||'none')}</code></td></tr></table><h3 style="margin-top:12px">Package manager policy</h3>\${pmPolicyHtml}\${topRisk.length?'<div class="timeline">'+topRisk.slice(0,5).map(p=>\`<div class="event"><time>\${esc(p.priority)}</time><div><b>\${esc(p.name)}</b> \${esc(p.severity)} \${p.directDependency?'<code>direct</code>':'<code>transitive</code>'}<div class="path">\${esc(p.manifest||p.ecosystem)} \${esc(p.version||'')}</div></div></div>\`).join('')+'</div>':'<div class="okline">No high-risk package summary in the current light SBOM.</div>'}<h3 style="margin-top:12px">Dependency change hints</h3>\${dependencyHintsHtml}\`;
+const riskSummaryHtml=riskSummary.level?\`<table><tr><th>Level</th><td><code>\${esc(riskSummary.level)}</code> \${esc(riskSummary.score||0)}</td></tr><tr><th>Scanner</th><td><code>\${esc(riskSummary.scanner||'unknown')}</code></td></tr><tr><th>Next</th><td>\${esc(riskSummary.next||'No SBOM action required.')}</td></tr><tr><th>Targets</th><td>\${esc((riskSummary.reviewTargets||[]).join(', ')||'none')}</td></tr></table>\${riskSummary.signals?.length?'<div class="timeline">'+riskSummary.signals.slice(0,5).map(s=>\`<div class="event"><time>risk</time><div>\${esc(s)}</div></div>\`).join('')+'</div>':''}\`:'<div class="okline">No risk summary available.</div>';
+const lightSbomHtml=\`<table><tr><th>Packages</th><td><code>\${esc(lightSbomSummary.packages||0)}</code></td></tr><tr><th>Vulnerabilities</th><td><code>\${esc(lightSbomSummary.vulnerabilities||0)}</code></td></tr><tr><th>Direct vulnerable</th><td><code>\${esc(lightSbomSummary.directVulnerablePackages||0)}</code></td></tr><tr><th>Manifests</th><td><code>\${esc((lightSbomSummary.manifests||[]).join(', ')||'none')}</code></td></tr><tr><th>Lockfiles</th><td><code>\${esc((lightSbomSummary.lockfiles||[]).map(l=>l.file).join(', ')||'none')}</code></td></tr></table><h3 style="margin-top:12px">Risk summary</h3>\${riskSummaryHtml}<h3 style="margin-top:12px">Package manager policy</h3>\${pmPolicyHtml}\${topRisk.length?'<div class="timeline">'+topRisk.slice(0,5).map(p=>\`<div class="event"><time>\${esc(p.priority)}</time><div><b>\${esc(p.name)}</b> \${esc(p.severity)} \${p.directDependency?'<code>direct</code>':'<code>transitive</code>'}<div class="path">\${esc(p.manifest||p.ecosystem)} \${esc(p.version||'')}</div></div></div>\`).join('')+'</div>':'<div class="okline">No high-risk package summary in the current light SBOM.</div>'}<h3 style="margin-top:12px">Dependency change hints</h3>\${dependencyHintsHtml}\`;
 const sec=manifest.security||{};
 const secSummary=sec.summary||{total:0,critical:0,high:0,moderate:0,low:0,info:0};
 const secPackages=sec.topPackages||[];
@@ -470,7 +467,7 @@ const activityHtml=activityTargets.length?'<div class="timeline">'+activityTarge
 const dependencyReadSet=manifest.preflight?.dependencyReadSet||[];
 const dependencyReadSetHtml=dependencyReadSet.length?'<div class="timeline">'+dependencyReadSet.slice(0,5).map(d=>\`<div class="event"><time>\${esc(d.ecosystem||'deps')}</time><div><b>\${esc(d.manifest||'dependency files')}</b> <code>\${esc(d.manager||'unknown')}</code><div class="path">\${esc([d.manifest,...(d.lockfiles||[])].filter(Boolean).join(', '))}</div>\${d.riskPackages?.length?\`<div class="path">risk: \${esc(d.riskPackages.join(', '))}</div>\`:''}</div></div>\`).join('')+'</div>':'<div class="okline">No dependency files detected.</div>';
 const dependencyProtocol=manifest.preflight?.dependencyChangeProtocol||{};
-const dependencyProtocolHtml=dependencyProtocol.commands?'<table><tr><th>Mode</th><td><code>'+esc(dependencyProtocol.mode||'advisory')+'</code></td></tr><tr><th>Policy</th><td><code>'+esc(dependencyProtocol.packageManagerPolicy||'not-detected')+'</code></td></tr><tr><th>Intent</th><td><code>'+esc(dependencyProtocol.commands.recordIntent)+'</code></td></tr><tr><th>After</th><td><code>'+esc(dependencyProtocol.commands.refreshAfterChange)+'</code> then <code>'+esc(dependencyProtocol.commands.recordAfterChange)+'</code></td></tr></table><div class="timeline">'+(dependencyProtocol.mustNotDo||[]).slice(0,3).map(item=>\`<div class="event"><time>avoid</time><div>\${esc(item)}</div></div>\`).join('')+'</div>':'<div class="okline">No dependency change protocol available.</div>';
+const dependencyProtocolHtml=dependencyProtocol.commands?'<table><tr><th>Mode</th><td><code>'+esc(dependencyProtocol.mode||'advisory')+'</code></td></tr><tr><th>Policy</th><td><code>'+esc(dependencyProtocol.packageManagerPolicy||'not-detected')+'</code></td></tr><tr><th>Intent</th><td><code>'+esc(dependencyProtocol.commands.recordIntent)+'</code></td></tr><tr><th>After</th><td><code>'+esc(dependencyProtocol.commands.checkpointAfterChange||dependencyProtocol.commands.recordAfterChange)+'</code></td></tr></table><div class="timeline">'+(dependencyProtocol.mustNotDo||[]).slice(0,3).map(item=>\`<div class="event"><time>avoid</time><div>\${esc(item)}</div></div>\`).join('')+'</div>':'<div class="okline">No dependency change protocol available.</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;
@@ -638,6 +635,10 @@ function lightSbomLines(lightSbom = {}) {
     lines.push(`- Source: ${lightSbom.source?.dependencies || "project manifests"}; vulnerabilities: ${lightSbom.source?.vulnerabilities || "not scanned"}`);
     lines.push(`- Confidence: direct ${lightSbom.confidence?.directDependencies || "unknown"}; transitive ${lightSbom.confidence?.transitiveDependencies || "unknown"}`);
   }
+  if (lightSbom.riskSummary) {
+    lines.push(`- Risk summary: ${lightSbom.riskSummary.level || "clear"}/${lightSbom.riskSummary.score || 0}; ${lightSbom.riskSummary.next || "no action"}`);
+    if (lightSbom.riskSummary.signals?.length) lines.push(`- Risk signals: ${lightSbom.riskSummary.signals.join("; ")}`);
+  }
   if (lightSbom.packageManagerPolicy) {
     lines.push(`- Package manager policy: ${lightSbom.packageManagerPolicy.status}`);
     lines.push(`- Package manager guidance: ${lightSbom.packageManagerPolicy.guidance}`);