aienvmp 0.1.56 → 0.1.57

package/BUGFIXES.md

@@ -130,6 +130,12 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `aiReadiness` now includes `requiresHumanReview`, `safeProjectLocalActions`, and `reviewOnlyEnvironmentChanges`; `summary.md` includes the first safe-local-work hint.
 - Verification: regression tests cover status, context, summary, and schema outputs; Windows smoke confirmed generated JSON and summary fields.
 
+### Standalone SBOM did not expose the dependency-change loop directly
+
+- Issue: AI agents reading only `.aienvmp/sbom.json` could see risk and hints, but still had to infer the safe dependency-change sequence from several fields.
+- Fix: `aiDependencyReview` now gives a top-level advisory review block with read order, safe actions, review targets, before-change commands, and after-change checkpoint guidance.
+- Verification: regression tests cover the new SBOM block and schema metadata; local sync smoke confirmed generated `sbom.json` separates before-change commands from after-change checkpoint commands.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.57
+
+- Added `aiDependencyReview` to the standalone `.aienvmp/sbom.json` artifact.
+- Linked SBOM risk to dependency-change read order, safe actions, review targets, and before/after commands.
+- Kept dependency review advisory and non-blocking while making the AI handoff more explicit.
+- Documented `sbom.json.aiDependencyReview` in the README and schema contract.
+- Fixed dependency-review command grouping so `checkpoint` appears after dependency changes, not before.
+- Added regression tests for SBOM dependency review and schema metadata.
+
 ## 0.1.56
 
 - Added `aiReadiness.requiresHumanReview` so agents can distinguish review-needed signals from hard blocking.

package/README.md

@@ -53,6 +53,7 @@ AIENV.md                 # Markdown env map for AI agents
 - `aiReadiness` gives a one-field ready/review signal for AI continuation.
 - `dependencyReadSet` lists manifests and lockfiles before package or security changes.
 - `sbomRisk` gives AI a compact light-SBOM risk level, signals, and next command.
+- `sbom.json.aiDependencyReview` connects SBOM risk to safe dependency-change steps.
 - `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`.

package/package.json

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

package/src/commands/sbom.js

@@ -36,6 +36,7 @@ export function buildSbomArtifact(manifest = {}) {
     topRisk: (lightSbom.topRisk || []).slice(0, 20),
     packageManagerPolicy: lightSbom.packageManagerPolicy || {},
     dependencyChangeHints: (lightSbom.dependencyChangeHints || []).slice(0, 20),
+    aiDependencyReview: aiDependencyReview(lightSbom),
     aiUse: {
       purpose: "Standalone AI-readable light SBOM artifact.",
       readBefore: "Dependency changes, vulnerability remediation, release review, or shared AI handoff.",
@@ -45,6 +46,40 @@ export function buildSbomArtifact(manifest = {}) {
   };
 }
 
+function aiDependencyReview(lightSbom = {}) {
+  const risk = lightSbom.riskSummary || {};
+  const hints = lightSbom.dependencyChangeHints || [];
+  const policy = lightSbom.packageManagerPolicy || {};
+  const level = risk.level || "clear";
+  const reviewTargets = (risk.reviewTargets || []).length
+    ? risk.reviewTargets
+    : hints.map((item) => item.manifest).filter(Boolean);
+  const review = ["urgent", "high", "medium"].includes(level) || policy.status === "review-required";
+  return {
+    status: review ? "review" : "ready",
+    mode: "advisory",
+    readFirst: ["riskSummary", "dependencyChangeHints", "packageManagerPolicy", "topRisk"],
+    reviewTargets: [...new Set(reviewTargets)].slice(0, 8),
+    safeActions: [
+      "read SBOM, status, summary, context, and dependency manifests before dependency changes",
+      "plan remediation without installing, upgrading, downgrading, or switching package managers",
+      "record intent before dependency or lockfile changes when another AI may be working"
+    ],
+    beforeDependencyChange: uniqueCommands([
+      ...planningCommands(risk.commands || []),
+      "aienvmp intent --actor agent:id --action dependency-review --target dependency",
+      "aienvmp plan --write"
+    ]),
+    afterDependencyChange: [
+      "run the narrowest relevant project validation",
+      "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"
+    ],
+    rule: review
+      ? "Review SBOM risk and package manager policy before dependency changes; default behavior is advisory and non-blocking."
+      : "No light SBOM signal requires action; still record intent before dependency or lockfile changes."
+  };
+}
+
 export async function writeSbomArtifact(dir, sbom) {
   const out = sbom.bomFormat === "CycloneDX" ? cyclonedxSbomPath(dir) : sbomJsonPath(dir);
   await writeJson(out, sbom);
@@ -136,6 +171,14 @@ function normalizeFormat(format = "") {
   return "aienvmp";
 }
 
+function uniqueCommands(commands = []) {
+  return [...new Set(commands.filter(Boolean))];
+}
+
+function planningCommands(commands = []) {
+  return commands.filter((command) => !String(command).includes(" checkpoint "));
+}
+
 function hashText(text = "") {
   let hash = 0;
   for (const ch of String(text)) hash = ((hash << 5) - hash + ch.charCodeAt(0)) >>> 0;

package/src/contract.js

@@ -42,7 +42,7 @@ export function schemaContract() {
       sbom: {
         file: ".aienvmp/sbom.json",
         command: "aienvmp sbom --json",
-        rootFields: ["schemaVersion", "schemaName", "workspace", "summary", "riskSummary", "topRisk", "packageManagerPolicy", "dependencyChangeHints"]
+        rootFields: ["schemaVersion", "schemaName", "workspace", "summary", "riskSummary", "topRisk", "packageManagerPolicy", "dependencyChangeHints", "aiDependencyReview"]
       },
       cyclonedxLite: {
         file: ".aienvmp/sbom.cdx.json",