aienvmp 0.1.67 → 0.1.68

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.68
+
+- Added an `aienvmp AI loop` block to the GitHub Action Step Summary using `schema.aiLoop`.
+- Kept the Action summary advisory by default while showing the same loop documented in README and `schema --json`.
+- Updated the GitHub Action example and README CI notes to mention Step Summary strict-plan and AI-loop blocks.
+- Added `doctor --json` `nextSafeCommand` so AI agents can pick one advisory next command without parsing every warning.
+- Aligned the dashboard next-command fallback with `maintenanceLoop.nextCommand` so the visual surface follows the same advisory next-step chain.
+- Added `context --json` `nextSafeCommand` so AI agents get the same one-step advisory next command in the preflight payload.
+- Added `handoff --json` `nextSafeCommand` so the next AI can resume from one root-level advisory command.
+- Added `status --json` and `.aienvmp/status.json` `nextSafeCommand` as a stable alias for the preflight next command.
+
 ## 0.1.67
 
 - Added a dashboard `First read` strip with status, first file, review targets, and local operation mode.

package/README.md

@@ -77,6 +77,7 @@ AIENV.md                 # Markdown env map for AI agents
 - `sbomRisk` and `sbomReview` connect light SBOM risk to safe dependency-change steps.
 - `collaboration`, `coordination`, and `agentActivity` show multi-agent conflicts and shared targets.
 - `strictDecision` separates local warn-only checks from optional CI strict gates.
+- `status --json`, `context --json`, `handoff --json`, and `doctor --json` include `nextSafeCommand` for one advisory next step.
 - `schema --json` prints the stable machine-readable contract without scanning.
 
 ## Agent Files
@@ -118,7 +119,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.
-The Step Summary includes an `aienvmp strict plan` block so humans and AI agents can pick the narrowest CI strict scope without parsing the full artifacts.
+The Step Summary includes `aienvmp strict plan` and `aienvmp AI loop` blocks so humans and AI agents can choose CI gates and continue the same workflow without parsing full artifacts.
 
 ```yaml
 - uses: soovwv/aienvmp@main

package/action.yml

@@ -123,6 +123,36 @@ runs:
         NODE
         fi
 
+    - name: Append AI loop summary
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-summary }}" = "true" ] && [ -n "$GITHUB_STEP_SUMMARY" ]; then
+          mkdir -p "${{ inputs.directory }}/.aienvmp"
+          schema_source="${{ inputs.directory }}/.aienvmp/schema.json"
+          if [ ! -f "$schema_source" ]; then
+            schema_source="$(mktemp)"
+            node "$GITHUB_ACTION_PATH/bin/aienvmp.js" schema --json > "$schema_source"
+          fi
+          node - "$schema_source" "$GITHUB_STEP_SUMMARY" <<'NODE'
+        const fs = require("node:fs");
+
+        const [schemaPath, summaryPath] = process.argv.slice(2);
+        const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+        const loop = schema.aiLoop || {};
+        const steps = (loop.steps || []).slice(0, 6).map((item) => item.command).join(" -> ");
+
+        fs.appendFileSync(summaryPath, [
+          "",
+          "## aienvmp AI loop",
+          "",
+          `- mode: ${loop.localMode || "warn-only"}`,
+          `- steps: \`${steps || "aienvmp sync -> aienvmp status -> aienvmp handoff"}\``,
+          `- rule: ${loop.strictRule || "Local checks are warn-only; strict gates are explicit."}`,
+          ""
+        ].join("\n"));
+        NODE
+        fi
+
     - name: Doctor
       shell: bash
       run: |

package/examples/github-action.yml

@@ -17,7 +17,7 @@ jobs:
           write-schema: "true"
           write-doctor-json: "true"
           write-sbom: "true"
-          write-summary: "true"
+          write-summary: "true" # appends summary, strict plan, and AI loop to GitHub Step Summary
           strict: "off" # security, policy, coordination, all, or off
 
       - uses: actions/upload-artifact@v4

package/package.json

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

package/src/commands/context.js

@@ -22,9 +22,11 @@ export async function contextWorkspace(args) {
   const actions = recommendedActions(manifest, { warnings, intents });
   const stepSummary = compactStepSummary(buildPlan(manifest, warnings, intents, policy));
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
+  const nextSafeCommand = contextNextSafeCommand(actions, warnings, preflight);
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
+      nextSafeCommand,
       preflight,
       aiReadiness: preflight.aiReadiness,
       collaboration: preflight.collaboration,
@@ -59,6 +61,14 @@ export async function contextWorkspace(args) {
   console.log(renderContext({ ...manifest, preflight }, timeline, warnings, intents, policy, actions));
 }
 
+function contextNextSafeCommand(actions = [], warnings = [], preflight = {}) {
+  const actionCommand = actions.find((item) => item.command)?.command;
+  return preflight.nextCommand
+    || preflight.maintenanceLoop?.nextCommand
+    || actionCommand
+    || (warnings.length ? "aienvmp plan --write" : "aienvmp status --json");
+}
+
 function lightSbomSummary(lightSbom = {}) {
   return {
     mode: lightSbom.mode || "light-sbom",

package/src/commands/doctor.js

@@ -20,6 +20,7 @@ export async function doctorWorkspace(args) {
   const actions = recommendedActions(manifest, { warnings, intents });
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
   const strict = strictResult(warnings, args);
+  const nextSafeCommand = doctorNextSafeCommand(actions, warnings);
   const exitBehavior = {
     mode: strict.enabled ? "strict" : "advisory",
     willSetFailureExitCode: strict.fail,
@@ -37,6 +38,7 @@ export async function doctorWorkspace(args) {
       aiReadiness: preflight.aiReadiness,
       agentPointers: preflight.agentPointers,
       openIntentCount: intents.length,
+      nextSafeCommand,
       warnings,
       recommendedActions: actions,
       enforcement: enforcementAdvice(warnings),
@@ -63,3 +65,10 @@ export async function doctorWorkspace(args) {
     process.exitCode = 1;
   }
 }
+
+function doctorNextSafeCommand(actions = [], warnings = []) {
+  const command = actions.find((item) => item.command)?.command;
+  if (command) return command;
+  if (warnings.length) return "aienvmp plan --write";
+  return "aienvmp status --json";
+}

package/src/commands/handoff.js

@@ -49,6 +49,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
   return {
     status: reviewRequired ? "review-required" : "clear",
+    nextSafeCommand: preflight.nextCommand || preflight.maintenanceLoop?.nextCommand || "aienvmp status --json",
     trust: manifest.trust || {},
     schemaVersion: manifest.schemaVersion || 1,
     preflight,

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", "aiReadiness", "collaboration", "maintenanceLoop", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "nextSafeCommand", "aiReadiness", "collaboration", "maintenanceLoop", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }
@@ -32,6 +32,7 @@ export function schemaContract() {
       status: {
         file: ".aienvmp/status.json",
         command: "aienvmp status --json",
+        rootFields: ["state", "nextCommand", "nextSafeCommand", "decision", "counts", "aiReadiness", "collaboration", "maintenanceLoop", "coordination", "agentPointers", "sbomRisk"],
         contract: preflightContract()
       },
       summary: {
@@ -43,11 +44,11 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "aiReadiness", "collaboration", "maintenanceLoop", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "nextSafeCommand", "preflight", "aiReadiness", "collaboration", "maintenanceLoop", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",
-        rootFields: ["status", "decision", "preflight", "continuation", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
+        rootFields: ["status", "nextSafeCommand", "decision", "preflight", "continuation", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
       },
       manifest: {
         file: ".aienvmp/manifest.json",

package/src/preflight.js

@@ -30,6 +30,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     dependencyReadSet,
     collaboration
   });
+  const nextCommand = maintenanceLoop.nextCommand || topAction?.command || decision.nextCommand;
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -102,7 +103,8 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
       recordIntent: intentTargets[0]?.command || "aienvmp intent --actor agent:id --action planned-change"
     },
     topAction,
-    nextCommand: maintenanceLoop.nextCommand || topAction?.command || decision.nextCommand
+    nextCommand,
+    nextSafeCommand: nextCommand
   };
 }
 

package/src/render.js

@@ -528,6 +528,7 @@ const activityTargets=agentActivity.targets||[];
 const activityHtml=activityTargets.length?'<div class="timeline">'+activityTargets.slice(0,5).map(a=>\`<div class="event"><time>\${esc(a.target||'env')}</time><div><b>\${esc((a.actors||[]).join(', ')||'unknown')}</b> \${esc(a.count||0)} record(s) \${a.multiActor?'<code>multi-agent</code>':'<code>single-agent</code>'}\${a.latestSummary?\`<div class="path">\${esc(a.latestSummary)}</div>\`:''}</div></div>\`).join('')+'</div><div class="path">'+esc(agentActivity.next||'Review activity before environment changes.')+'</div>':'<div class="okline">No recorded environment activity needs coordination.</div>';
 const collaboration=manifest.preflight?.collaboration||{};
 const collaborationHtml=\`<table><tr><th>Status</th><td><code>\${esc(collaboration.status||'unknown')}</code> \${esc(collaboration.mode||'advisory')}</td></tr><tr><th>Targets</th><td>\${esc((collaboration.activeTargets||[]).join(', ')||'none')}</td></tr><tr><th>Project work</th><td><code>\${esc(collaboration.projectLocalWork||'allowed')}</code></td></tr><tr><th>Env changes</th><td><code>\${esc(collaboration.environmentChanges||'intent-first')}</code></td></tr><tr><th>Next</th><td><code>\${esc(collaboration.nextCommand||'aienvmp status --json')}</code></td></tr></table><div class="timeline">\${(collaboration.reviewSignals||[]).slice(0,4).map(signal=>\`<div class="event"><time>review</time><div>\${esc(signal)}</div></div>\`).join('')}</div><div class="path">\${esc(collaboration.rule||'Record intent before shared environment changes.')}</div>\`;
+const maintenanceLoop=manifest.preflight?.maintenanceLoop||{};
 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||{};
@@ -552,8 +553,8 @@ const sbomRiskValue=riskSummary.level||'unknown';
 const sbomRiskClass=['urgent','high','medium'].includes(sbomRiskValue)?'review':'ready';
 const sbomRiskScore=riskSummary.score!==undefined?' ('+riskSummary.score+')':'';
 const sbomRiskNext=riskSummary.next||aiDependencyReview.beforeDependencyChange?.[0]||'Run aienvmp sbom --json for dependency context.';
-const nextCommand=manifest.preflight?.nextCommand||topAction.command||collaboration.nextCommand||'aienvmp status --json';
-const nextReason=topAction.summary||collaboration.rule||riskSummary.next||'Read status/context before changing shared environment state.';
+const nextCommand=manifest.preflight?.nextCommand||maintenanceLoop.nextCommand||topAction.command||collaboration.nextCommand||'aienvmp status --json';
+const nextReason=topAction.summary||maintenanceLoop.rule||collaboration.rule||riskSummary.next||'Read status/context before changing shared environment state.';
 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):[]);