aienvmp 0.1.56 → 0.1.58

package/BUGFIXES.md

@@ -130,6 +130,18 @@ 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.
+
+### SBOM dependency review was not visible across all review surfaces
+
+- Issue: `aiDependencyReview` was available in standalone SBOM output, but the manifest-backed dashboard and compact summary did not surface the same dependency-review guidance.
+- Fix: manifest generation now includes `lightSbom.aiDependencyReview`; the dashboard Light SBOM card and `summary.md` show the AI dependency review status and commands.
+- Verification: regression tests cover generation, dashboard rendering, SBOM artifact reuse, and summary output; local sync smoke confirmed dashboard and SBOM artifacts include the block.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.58
+
+- Added `lightSbom.aiDependencyReview` during manifest generation so all generated artifacts share the same dependency-review block.
+- Reused generated `aiDependencyReview` in standalone `.aienvmp/sbom.json`.
+- Added an `AI Dependency Review` section to the dashboard Light SBOM card.
+- Added the AI dependency review status and first command to `.aienvmp/summary.md`.
+- Added regression tests for light SBOM generation, dashboard rendering, SBOM artifact output, and summary output.
+
+## 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.58",
   "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: lightSbom.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/commands/summary.js

@@ -55,6 +55,7 @@ export function renderSummary(status = {}, manifest = {}) {
   const aiReadiness = status.aiReadiness || {};
   const aiSignals = toList(aiReadiness.signals).slice(0, 5);
   const aiNext = aiReadiness.next || "Run aienvmp context --json for details.";
+  const aiDependencyReview = manifest.lightSbom?.aiDependencyReview || {};
 
   return [
     "# aienvmp summary",
@@ -85,6 +86,7 @@ export function renderSummary(status = {}, manifest = {}) {
     "",
     `- source: ${manifest.lightSbom?.source?.dependencies || "project manifests"}`,
     `- confidence: transitive ${manifest.lightSbom?.confidence?.transitiveDependencies || "not-resolved"}`,
+    `- AI dependency review: ${aiDependencyReview.status || "unknown"} / ${aiDependencyReview.beforeDependencyChange?.[0] || "aienvmp sbom --json"}`,
     `- signals: ${riskSignals.length ? riskSignals.join("; ") : "none"}`,
     `- verify: ${sbomRisk.next || "Use a dedicated scanner for security decisions."}`,
     "",

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",

package/src/dependencies.js

@@ -111,6 +111,7 @@ export function buildLightSbom(snapshot = {}, security = {}) {
     riskSummary: lightSbomRiskSummary({ packages, security, directVulnerable, transitiveOrUnmatched, topRisk, lockfiles: snapshot.lockfiles || [] }),
     packageManagerPolicy: packageManagerPolicy(snapshot.lockfiles || []),
     dependencyChangeHints: dependencyChangeHints(packages, topRisk, snapshot.lockfiles || []),
+    aiDependencyReview: aiDependencyReview({ topRisk, lockfiles: snapshot.lockfiles || [] }),
     aiUse: {
       beforeDependencyChanges: "Read lightSbom.summary and lightSbom.topRisk before changing dependencies.",
       securityMode: security.enabled ? "scanner-summary" : "scanner-off",
@@ -120,6 +121,34 @@ export function buildLightSbom(snapshot = {}, security = {}) {
   };
 }
 
+function aiDependencyReview({ topRisk = [], lockfiles = [] } = {}) {
+  const risk = lightSbomRiskSummary({ topRisk, lockfiles });
+  const review = ["urgent", "high", "medium"].includes(risk.level) || packageManagerPolicy(lockfiles).status === "review-required";
+  return {
+    status: review ? "review" : "ready",
+    mode: "advisory",
+    readFirst: ["riskSummary", "dependencyChangeHints", "packageManagerPolicy", "topRisk"],
+    reviewTargets: risk.reviewTargets,
+    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: [
+      "aienvmp sync --security",
+      "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 function lightSbomRiskSummary({ packages = [], security = {}, directVulnerable = [], transitiveOrUnmatched = [], topRisk = [], lockfiles = [] } = {}) {
   const signals = [];
   let score = 0;

package/src/render.js

@@ -430,10 +430,12 @@ const pmPolicy=lightSbom.packageManagerPolicy||{};
 const topRisk=lightSbom.topRisk||[];
 const riskSummary=lightSbom.riskSummary||{};
 const dependencyHints=lightSbom.dependencyChangeHints||[];
+const aiDependencyReview=lightSbom.aiDependencyReview||{};
 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 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 aiDependencyReviewHtml=aiDependencyReview.status?\`<table><tr><th>Status</th><td><code>\${esc(aiDependencyReview.status)}</code> \${esc(aiDependencyReview.mode||'advisory')}</td></tr><tr><th>Read first</th><td>\${esc((aiDependencyReview.readFirst||[]).join(', ')||'riskSummary')}</td></tr><tr><th>Targets</th><td>\${esc((aiDependencyReview.reviewTargets||[]).join(', ')||'none')}</td></tr><tr><th>Before</th><td><code>\${esc((aiDependencyReview.beforeDependencyChange||[]).slice(0,3).join(' -> ')||'aienvmp intent --actor agent:id --action dependency-review --target dependency')}</code></td></tr><tr><th>After</th><td><code>\${esc((aiDependencyReview.afterDependencyChange||[]).slice(-1)[0]||'aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency')}</code></td></tr></table><div class="path">\${esc(aiDependencyReview.rule||'Dependency review is advisory and non-blocking.')}</div>\`:'<div class="okline">No AI dependency review block available. Run <code>aienvmp sync</code>.</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">AI Dependency Review</h3>\${aiDependencyReviewHtml}<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||[];