aienvmp 0.1.54 → 0.1.56

package/BUGFIXES.md

@@ -118,6 +118,18 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `aiReadiness` now provides one advisory ready/review signal across status, context, doctor, summary, and dashboard.
 - Verification: regression tests cover ready/review summaries, text status output, schema metadata, and dashboard rendering.
 
+### AI readiness was visible but not first in human review surfaces
+
+- Issue: CI Step Summary and the dashboard showed readiness, but agents and humans still had to scan past broader status fields to find the main AI continuation signal.
+- Fix: `.aienvmp/summary.md` now starts with `AI readiness`, `AI signals`, and `AI next`; the dashboard audit band includes readiness signals in its hint.
+- Verification: regression tests assert the summary top block and dashboard readiness signals; Windows and macOS package smoke checks cover generated artifacts.
+
+### AI review state could sound more blocking than intended
+
+- Issue: `aiReadiness.level: review` made risk visible, but did not explicitly tell AI agents which local actions remain safe and which environment changes need intent/review first.
+- 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.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.56
+
+- Added `aiReadiness.requiresHumanReview` so agents can distinguish review-needed signals from hard blocking.
+- Added `aiReadiness.safeProjectLocalActions` to clarify what AI agents may still do in review state.
+- Added `aiReadiness.reviewOnlyEnvironmentChanges` to keep environment changes advisory, intentional, and non-disruptive.
+- Added the safe-local-work hint to `.aienvmp/summary.md`.
+- Documented the summary top block and `aiReadiness` consumption rule in `schema --json`.
+- Added regression tests for status, context, summary, and schema outputs.
+
+## 0.1.55
+
+- Moved `AI readiness`, readiness signals, and next action to the top of `.aienvmp/summary.md`.
+- Added `aiReadiness.signals` to the dashboard audit-band hint.
+- Kept the CI Step Summary lightweight while making the first AI review signal easier to scan.
+- Updated README and regression tests for the new summary/dashboard readiness surface.
+
 ## 0.1.54
 
 - Added `aiReadiness` to the shared preflight/status contract.

package/README.md

@@ -34,7 +34,7 @@ Warnings are advisory by default. Use `doctor --strict <scope>` only when you wa
 ```text
 AIENV.md                 # Markdown env map for AI agents
 .aienvmp/status.json     # first AI read: clear/review, next command, nextAgent hint
-.aienvmp/summary.md      # compact AI/CI summary
+.aienvmp/summary.md      # compact AI/CI summary; starts with AI readiness
 .aienvmp/manifest.json   # runtime map + light SBOM
 .aienvmp/sbom.json       # standalone AI-readable light SBOM
 .aienvmp/sbom.cdx.json   # CycloneDX-lite export from project manifests
@@ -48,7 +48,7 @@ AIENV.md                 # Markdown env map for AI agents
 
 - `status`, `context`, `plan`, and `handoff` share one preflight contract.
 - `schema --json` prints the stable AI-readable output contract without scanning.
-- `summary.md` is the short CI/AI handoff view.
+- `summary.md` is the short CI/AI handoff view, with `AI readiness`, signals, and next action first.
 - `status.json.nextAgent` tells the next AI what to read and whether to review first.
 - `aiReadiness` gives a one-field ready/review signal for AI continuation.
 - `dependencyReadSet` lists manifests and lockfiles before package or security changes.

package/package.json

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

package/src/commands/summary.js

@@ -53,19 +53,25 @@ export function renderSummary(status = {}, manifest = {}) {
   const dependencyFiles = dependencyFilesFor(status.dependencyReadSet);
   const agentPointers = status.agentPointers || {};
   const aiReadiness = status.aiReadiness || {};
+  const aiSignals = toList(aiReadiness.signals).slice(0, 5);
+  const aiNext = aiReadiness.next || "Run aienvmp context --json for details.";
 
   return [
     "# aienvmp summary",
     "",
+    `- AI readiness: ${aiReadiness.level || "unknown"}`,
+    `- AI signals: ${aiSignals.length ? aiSignals.join("; ") : "none"}`,
+    `- AI next: ${aiNext}`,
+    `- 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}`,
+    "",
     `- state: ${status.state || "unknown"}`,
     `- workspace: ${workspace}`,
     `- warnings: ${valueOrZero(counts.warnings)} / open intents: ${valueOrZero(counts.openIntents)}`,
     `- runtimes: ${valueOrZero(counts.runtimes)} / dependencies: ${valueOrZero(counts.dependencies)} / vulnerabilities: ${valueOrZero(counts.vulnerabilities)}`,
     `- light SBOM risk: ${riskLevel} (${riskScore}) / scanner: ${scanner}`,
     `- next: ${next}`,
-    `- AI readiness: ${aiReadiness.level || "unknown"} / ${aiReadiness.next || "Run aienvmp context --json for details."}`,
-    `- AI read first: ${readFirst}, then ${detail}`,
-    `- mode: advisory by default; strict is opt-in with ${strict}`,
     "",
     "## AI handoff",
     "",

package/src/contract.js

@@ -24,7 +24,8 @@ export function schemaContract() {
         file: ".aienvmp/summary.md",
         command: "aienvmp summary --write",
         format: "markdown",
-        purpose: "Compact AI and CI step summary for quick review."
+        purpose: "Compact AI and CI step summary for quick review.",
+        startsWith: ["AI readiness", "AI signals", "AI next"]
       },
       context: {
         command: "aienvmp context --json",
@@ -52,7 +53,8 @@ export function schemaContract() {
     compatibility: {
       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."
+      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."
     }
   };
 }

package/src/preflight.js

@@ -105,10 +105,21 @@ function aiReadinessSummary({ state, decision, coordination, agentActivity, agen
   const next = level === "ready"
     ? "AI agents can continue project-local work; record intent before environment changes."
     : "Review listed signals before another AI changes runtimes, dependencies, package managers, Docker, or global tools.";
+  const safeProjectLocalActions = [
+    "read status, summary, context, env map, SBOM, and timeline artifacts",
+    "continue code-only work that does not install, remove, upgrade, downgrade, or switch tools",
+    "write a plan or intent before changing runtimes, dependencies, package managers, Docker, or global tools"
+  ];
+  const reviewOnlyEnvironmentChanges = review.length
+    ? "Record intent and review signals before environment changes; strict failure remains opt-in."
+    : "Record intent before environment changes; strict failure remains opt-in.";
   return {
     level,
+    requiresHumanReview: review.length > 0,
     projectLocalWork: decision?.canContinueProjectLocalWork ? "allowed" : "review-first",
     environmentChanges: decision?.canChangeEnvironmentWithoutReview ? "allowed" : "intent-and-review-first",
+    safeProjectLocalActions,
+    reviewOnlyEnvironmentChanges,
     signals: review,
     blockers,
     next,

package/src/render.js

@@ -494,6 +494,8 @@ const auditItem=(key,value,hint,klass='')=>\`<div class="audit-item \${klass}"><
 const driftLabel=warnings.length?'detected':'none';
 const nextAgent=manifest.preflight?.nextAgent||{};
 const aiReadiness=manifest.preflight?.aiReadiness||{};
+const aiReadinessSignals=(aiReadiness.signals||[]).slice(0,3);
+const aiReadinessHint=(aiReadiness.next||'Run aienvmp context --json for details.')+(aiReadinessSignals.length?' Signals: '+aiReadinessSignals.join('; '):'');
 const coordination=manifest.preflight?.coordination||{};
 const conflictTargets=coordination.conflictTargets||[];
 const handoffFiles=nextAgent.dependencyFiles?.length?nextAgent.dependencyFiles:(dependencyReadSet[0]?[dependencyReadSet[0].manifest,...(dependencyReadSet[0].lockfiles||[])].filter(Boolean):[]);
@@ -510,7 +512,7 @@ document.getElementById('app').innerHTML=\`
 </header>
 <section class="audit" aria-label="Audit summary">
   \${auditItem('AI decision',reviewRequired?'review required':'can proceed',nextAction,reviewRequired?'review':'primary')}
-  \${auditItem('AI readiness',aiReadiness.level||'unknown',aiReadiness.next||'Run aienvmp context --json for details.',aiReadiness.level==='ready'?'primary':'review')}
+  \${auditItem('AI readiness',aiReadiness.level||'unknown',aiReadinessHint,aiReadiness.level==='ready'?'primary':'review')}
   \${auditItem('Runtime drift',driftLabel,warnings.length?'Policy, runtime, or coordination warning detected':'No drift warnings detected',warnings.length?'review':'')}
   \${auditItem('Open env changes',String(intents.length),intents.length?'Resolve or coordinate before changes':'No pending env changes')}
   \${auditItem('Trust',trustState,trustState==='verified'?'Human or CI verified':'Machine observed; not AI-verified')}