aienvmp 0.1.58 → 0.1.60

package/BUGFIXES.md

@@ -142,6 +142,18 @@ Short record of bugs, fixes, and follow-up checks.
 - 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.
 
+### Scanner-off SBOM state could look safer than intended
+
+- Issue: AI agents could read `aiDependencyReview.status: ready` while the security scanner was off, making the state look more verified than it was.
+- Fix: `aiDependencyReview` now includes `statusReason` and `securityConfidence`, and generation reuses the computed risk summary instead of recalculating a weaker review signal.
+- Verification: regression tests cover scanner-off confidence, dashboard/summary rendering, schema metadata, and standalone SBOM fallback behavior; local sync smoke confirmed `scanner-off` appears in generated artifacts.
+
+### Strict mode guidance required too much inference
+
+- Issue: AI and CI consumers could see scoped strict results, but still had to infer which `doctor --strict` command should be used without disrupting local operation.
+- Fix: `strictPlan` now provides local advisory command, recommended strict scope, CI command, all-scope command, scope statuses, and the strict-use rule.
+- Verification: regression tests cover enforcement advice, doctor JSON, status/context, summary, dashboard, and schema outputs; local sync smoke confirmed summary emits the CI strict command.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.60
+
+- Added `enforcement.strictPlan` to help AI agents and CI choose the narrowest explicit strict scope.
+- Added `preflight.enforcementProfile.strictPlan` so status/context consumers see the same strict guidance.
+- Added CI strict command output to `.aienvmp/summary.md`.
+- Added strict-plan CI command and rule display to the dashboard Enforcement Mode card.
+- Documented strict-plan consumption in `schema --json` and README.
+- Added regression tests for enforcement advice, doctor JSON, status/context, summary, dashboard, and schema outputs.
+
+## 0.1.59
+
+- Added `aiDependencyReview.statusReason` so AI agents can distinguish actual review risk from scanner-off uncertainty.
+- Added `aiDependencyReview.securityConfidence` across generated light SBOM, standalone SBOM, dashboard, summary, and schema metadata.
+- Reused the computed `riskSummary`, package-manager policy, and dependency hints when building `aiDependencyReview` to avoid drift between artifacts.
+- Updated dashboard and summary surfaces to show dependency-review confidence.
+- Updated README and regression tests for scanner-off dependency review behavior.
+
 ## 0.1.58
 
 - Added `lightSbom.aiDependencyReview` during manifest generation so all generated artifacts share the same dependency-review block.

package/README.md

@@ -53,7 +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.
+- `sbom.json.aiDependencyReview` connects SBOM risk, scanner confidence, and 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`.
@@ -98,6 +98,7 @@ aienvmp doctor --strict security|policy|coordination|all
 ## CI
 
 The GitHub Action writes status, summary, schema, doctor, plan, SBOM, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
+Use `doctor --json` or `context --json` to read `strictPlan` and choose the narrowest CI strict scope.
 
 ```yaml
 - uses: soovwv/aienvmp@main

package/package.json

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

package/src/commands/sbom.js

@@ -55,8 +55,15 @@ function aiDependencyReview(lightSbom = {}) {
     ? risk.reviewTargets
     : hints.map((item) => item.manifest).filter(Boolean);
   const review = ["urgent", "high", "medium"].includes(level) || policy.status === "review-required";
+  const scannerOff = risk.scanner === "off" || lightSbom.source?.vulnerabilities === "not scanned" || lightSbom.confidence?.vulnerabilities === "not-scanned";
   return {
     status: review ? "review" : "ready",
+    statusReason: review
+      ? "SBOM risk or package manager policy requires dependency review before changes."
+      : scannerOff
+        ? "No scanned vulnerability finding is present because the security scanner is off; run read-only security scan before security decisions."
+        : "No light SBOM signal requires dependency review.",
+    securityConfidence: scannerOff ? "scanner-off" : "scanner-summary",
     mode: "advisory",
     readFirst: ["riskSummary", "dependencyChangeHints", "packageManagerPolicy", "topRisk"],
     reviewTargets: [...new Set(reviewTargets)].slice(0, 8),

package/src/commands/summary.js

@@ -56,6 +56,7 @@ export function renderSummary(status = {}, manifest = {}) {
   const aiSignals = toList(aiReadiness.signals).slice(0, 5);
   const aiNext = aiReadiness.next || "Run aienvmp context --json for details.";
   const aiDependencyReview = manifest.lightSbom?.aiDependencyReview || {};
+  const strictPlan = status.enforcementProfile?.strictPlan || status.enforcement?.strictPlan || {};
 
   return [
     "# aienvmp summary",
@@ -66,6 +67,7 @@ export function renderSummary(status = {}, manifest = {}) {
     `- AI safe local work: ${toList(aiReadiness.safeProjectLocalActions)[0] || "read artifacts and avoid environment changes until reviewed"}`,
     `- AI read first: ${readFirst}, then ${detail}`,
     `- mode: advisory by default; strict is opt-in with ${strict}`,
+    `- CI strict: ${strictPlan.ciCommand || `${strict} --json`}`,
     "",
     `- state: ${status.state || "unknown"}`,
     `- workspace: ${workspace}`,
@@ -86,7 +88,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"}`,
+    `- AI dependency review: ${aiDependencyReview.status || "unknown"} / ${aiDependencyReview.securityConfidence || "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

@@ -29,7 +29,7 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "aiReadiness", "coordination", "agentPointers", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "preflight", "aiReadiness", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",
@@ -42,7 +42,8 @@ export function schemaContract() {
       sbom: {
         file: ".aienvmp/sbom.json",
         command: "aienvmp sbom --json",
-        rootFields: ["schemaVersion", "schemaName", "workspace", "summary", "riskSummary", "topRisk", "packageManagerPolicy", "dependencyChangeHints", "aiDependencyReview"]
+        rootFields: ["schemaVersion", "schemaName", "workspace", "summary", "riskSummary", "topRisk", "packageManagerPolicy", "dependencyChangeHints", "aiDependencyReview"],
+        aiDependencyReviewFields: ["status", "statusReason", "securityConfidence", "readFirst", "reviewTargets", "beforeDependencyChange", "afterDependencyChange", "rule"]
       },
       cyclonedxLite: {
         file: ".aienvmp/sbom.cdx.json",
@@ -54,7 +55,8 @@ export function schemaContract() {
       stability: "additive",
       consumerRule: "Ignore unknown fields. Do not require optional fields unless listed in requiredFields.",
       localBehavior: "read-only; this command does not scan, install, update, or lock anything.",
-      aiReadinessRule: "When aiReadiness.level is review, project-local code work may still continue if aiReadiness.projectLocalWork is allowed; environment changes should follow intent/review guidance."
+      aiReadinessRule: "When aiReadiness.level is review, project-local code work may still continue if aiReadiness.projectLocalWork is allowed; environment changes should follow intent/review guidance.",
+      strictPlanRule: "Use enforcement.strictPlan or preflight.enforcementProfile.strictPlan to choose the narrowest explicit strict scope for CI."
     }
   };
 }

package/src/dependencies.js

@@ -75,6 +75,9 @@ export function buildLightSbom(snapshot = {}, security = {}) {
     fixAvailable: pkg.fixAvailable === true || Boolean(pkg.fixVersions?.length),
     fixVersions: (pkg.fixVersions || []).slice(0, 3)
   }));
+  const riskSummary = lightSbomRiskSummary({ packages, security, directVulnerable, transitiveOrUnmatched, topRisk, lockfiles: snapshot.lockfiles || [] });
+  const pmPolicy = packageManagerPolicy(snapshot.lockfiles || []);
+  const changeHints = dependencyChangeHints(packages, topRisk, snapshot.lockfiles || []);
   return {
     schemaVersion: 1,
     mode: "light-sbom",
@@ -108,10 +111,10 @@ 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 || []),
-    aiDependencyReview: aiDependencyReview({ topRisk, lockfiles: snapshot.lockfiles || [] }),
+    riskSummary,
+    packageManagerPolicy: pmPolicy,
+    dependencyChangeHints: changeHints,
+    aiDependencyReview: aiDependencyReview({ riskSummary, packageManagerPolicy: pmPolicy, security }),
     aiUse: {
       beforeDependencyChanges: "Read lightSbom.summary and lightSbom.topRisk before changing dependencies.",
       securityMode: security.enabled ? "scanner-summary" : "scanner-off",
@@ -121,14 +124,20 @@ 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";
+function aiDependencyReview({ riskSummary = {}, packageManagerPolicy = {}, security = {} } = {}) {
+  const review = ["urgent", "high", "medium"].includes(riskSummary.level) || packageManagerPolicy.status === "review-required";
+  const scannerOff = security.enabled !== true;
   return {
     status: review ? "review" : "ready",
+    statusReason: review
+      ? "SBOM risk or package manager policy requires dependency review before changes."
+      : scannerOff
+        ? "No scanned vulnerability finding is present because the security scanner is off; run read-only security scan before security decisions."
+        : "No light SBOM signal requires dependency review.",
+    securityConfidence: scannerOff ? "scanner-off" : "scanner-summary",
     mode: "advisory",
     readFirst: ["riskSummary", "dependencyChangeHints", "packageManagerPolicy", "topRisk"],
-    reviewTargets: risk.reviewTargets,
+    reviewTargets: riskSummary.reviewTargets || [],
     safeActions: [
       "read SBOM, status, summary, context, and dependency manifests before dependency changes",
       "plan remediation without installing, upgrading, downgrading, or switching package managers",

package/src/enforcement.js

@@ -33,6 +33,7 @@ export function enforcementAdvice(warnings = []) {
     gate: enforcementGate(""),
     suggestedStrictScopes,
     scopes: scopeResults,
+    strictPlan: strictScopePlan(suggestedStrictScopes, scopeResults),
     recommendedCommand: suggestedStrictScopes.length
       ? `aienvmp doctor --strict ${suggestedStrictScopes[0]}`
       : "aienvmp doctor --strict all",
@@ -40,6 +41,26 @@ export function enforcementAdvice(warnings = []) {
   };
 }
 
+export function strictScopePlan(suggestedStrictScopes = [], scopeResults = []) {
+  const firstScope = suggestedStrictScopes[0] || "all";
+  return {
+    mode: "advisory-local-strict-ci",
+    localDefault: "aienvmp doctor --json",
+    recommendedStrictScope: firstScope,
+    recommendedStrictCommand: `aienvmp doctor --strict ${firstScope}`,
+    ciCommand: `aienvmp doctor --strict ${firstScope} --json`,
+    allScopesCommand: "aienvmp doctor --strict all --json",
+    scopeStatuses: scopeResults.map((item) => ({
+      scope: item.scope,
+      status: item.status,
+      matchedWarningCodes: item.matchedWarningCodes || []
+    })),
+    rule: suggestedStrictScopes.length
+      ? "Use the narrowest failing strict scope first; keep local operation advisory unless CI or the user explicitly requests failure."
+      : "No scope currently fails; use --strict all only for explicit CI health checks."
+  };
+}
+
 export function enforcementGate(scope = "") {
   const strictScope = normalizeStrictScope(scope);
   return {

package/src/preflight.js

@@ -36,6 +36,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
       gate: enforcementGate(""),
       reason: "Avoid disrupting shared servers or developer machines while still making drift visible.",
       recommendedStrictCommand: enforcement.recommendedCommand,
+      strictPlan: enforcement.strictPlan,
       strictCommands: [
         "aienvmp doctor --strict security",
         "aienvmp doctor --strict policy",

package/src/render.js

@@ -434,7 +434,7 @@ 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 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 aiDependencyReviewHtml=aiDependencyReview.status?\`<table><tr><th>Status</th><td><code>\${esc(aiDependencyReview.status)}</code> \${esc(aiDependencyReview.mode||'advisory')}</td></tr><tr><th>Reason</th><td>\${esc(aiDependencyReview.statusReason||'No dependency review reason provided.')}</td></tr><tr><th>Security confidence</th><td><code>\${esc(aiDependencyReview.securityConfidence||'unknown')}</code></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};
@@ -473,7 +473,8 @@ const ciReadinessHtml=ciReadiness.length?'<table>'+ciReadiness.map(s=>\`<tr><th>
 const enforcementProfile=manifest.preflight?.enforcementProfile||{};
 const strictCommands=enforcementProfile.strictCommands||[];
 const gate=enforcementProfile.gate||{};
-const enforcementHtml=\`<table><tr><th>Default</th><td><code>\${esc(gate.defaultMode||enforcementProfile.defaultMode||'advisory')}</code> \${esc(gate.localDefault||'warn-only')}</td></tr><tr><th>Strict</th><td><code>\${esc(gate.strictMode||'off')}</code></td></tr><tr><th>Fail</th><td>\${esc(gate.failCondition||'never in default mode')}</td></tr><tr><th>Exit</th><td>\${esc(gate.exitCode||'0 unless the command itself errors')}</td></tr><tr><th>Recommended</th><td><code>\${esc(enforcementProfile.recommendedStrictCommand||'aienvmp doctor --strict all')}</code></td></tr></table><div class="timeline">\${strictCommands.slice(0,4).map(cmd=>\`<div class="event"><time>CI</time><div><code>\${esc(cmd)}</code></div></div>\`).join('')}</div><div class="path">\${esc(gate.rule||enforcementProfile.reason||'Warnings stay advisory unless strict mode is requested.')}</div>\`;
+const strictPlan=enforcementProfile.strictPlan||{};
+const enforcementHtml=\`<table><tr><th>Default</th><td><code>\${esc(gate.defaultMode||enforcementProfile.defaultMode||'advisory')}</code> \${esc(gate.localDefault||'warn-only')}</td></tr><tr><th>Strict</th><td><code>\${esc(gate.strictMode||'off')}</code></td></tr><tr><th>Fail</th><td>\${esc(gate.failCondition||'never in default mode')}</td></tr><tr><th>Exit</th><td>\${esc(gate.exitCode||'0 unless the command itself errors')}</td></tr><tr><th>Recommended</th><td><code>\${esc(strictPlan.recommendedStrictCommand||enforcementProfile.recommendedStrictCommand||'aienvmp doctor --strict all')}</code></td></tr><tr><th>CI</th><td><code>\${esc(strictPlan.ciCommand||'aienvmp doctor --strict all --json')}</code></td></tr></table><div class="timeline">\${strictCommands.slice(0,4).map(cmd=>\`<div class="event"><time>CI</time><div><code>\${esc(cmd)}</code></div></div>\`).join('')}</div><div class="path">\${esc(strictPlan.rule||gate.rule||enforcementProfile.reason||'Warnings stay advisory unless strict mode is requested.')}</div>\`;
 const contract=manifest.preflight?.contract||{};
 const contractHtml=contract.name?\`<table><tr><th>Name</th><td><code>\${esc(contract.name)}</code></td></tr><tr><th>Version</th><td><code>\${esc(contract.version||1)}</code></td></tr><tr><th>Stability</th><td><code>\${esc(contract.stability||'additive')}</code></td></tr><tr><th>AI fields</th><td>\${esc((contract.aiEntryFields||[]).join(', ')||'none')}</td></tr></table><div class="path">\${esc(contract.rule||'Ignore unknown fields.')}</div>\`:'<div class="okline">Run <code>aienvmp status --write</code> to include AI contract metadata.</div>';
 const intentTargets=manifest.preflight?.intentTargets||[];