aienvmp 0.1.61 → 0.1.62

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.62
+
+- Added a compact `collaboration` block to the shared preflight/status contract for multi-agent environment coordination.
+- Exposed `collaboration` at the root of `context --json` so AI agents can read status, active targets, and the next command without digging through multiple sections.
+- Added the collaboration status and rule to `.aienvmp/summary.md`.
+- Added a short collaboration line to plain `aienvmp status` output.
+- Added an `AI Collaboration` dashboard card with status, active targets, env-change rule, and next command.
+- Documented the collaboration block in the stable schema contract and README.
+- Added regression tests for status, context, summary, dashboard, and schema surfaces.
+
 ## 0.1.61
 
 - Added an `aienvmp strict plan` block to the GitHub Action Step Summary.

package/README.md

@@ -51,6 +51,7 @@ AIENV.md                 # Markdown env map for AI agents
 - `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.
+- `collaboration` gives the shortest multi-agent env-change status, targets, and next command.
 - `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, scanner confidence, and safe dependency-change steps.

package/package.json

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

package/src/commands/context.js

@@ -27,6 +27,7 @@ export async function contextWorkspace(args) {
       status: warnings.length ? "review-required" : "clear",
       preflight,
       aiReadiness: preflight.aiReadiness,
+      collaboration: preflight.collaboration,
       coordination: preflight.coordination,
       agentPointers: preflight.agentPointers,
       sbomRisk: preflight.sbomRisk,

package/src/commands/status.js

@@ -23,6 +23,7 @@ export async function statusWorkspace(args) {
   } else if (!args.quiet) {
     console.log(`${output.state}: ${output.summary}`);
     console.log(`ai-readiness: ${output.aiReadiness?.level || "unknown"} - ${output.aiReadiness?.next || "Run aienvmp context --json for details."}`);
+    console.log(`collaboration: ${output.collaboration?.status || "unknown"} - ${output.collaboration?.nextCommand || "aienvmp status --json"}`);
     console.log(`next: ${output.nextCommand}`);
     console.log(`ai: ${output.quickstart.readFirst} -> ${output.quickstart.detailCommand}`);
     console.log(`intent: ${output.intentTargets[0]?.command || output.commands.recordIntent}`);

package/src/commands/summary.js

@@ -37,6 +37,7 @@ export function renderSummary(status = {}, manifest = {}) {
   const sbomRisk = status.sbomRisk || manifest.lightSbom?.riskSummary || {};
   const coordination = status.coordination || {};
   const activity = status.agentActivity || {};
+  const collaboration = status.collaboration || {};
   const workspace = manifest.workspace?.root || manifest.workspace?.name || ".";
   const next = status.nextCommand || status.decision?.nextCommand || "aienvmp status";
   const readFirst = status.nextAgent?.readFirst || ".aienvmp/status.json";
@@ -64,6 +65,7 @@ export function renderSummary(status = {}, manifest = {}) {
     `- AI readiness: ${aiReadiness.level || "unknown"}`,
     `- AI signals: ${aiSignals.length ? aiSignals.join("; ") : "none"}`,
     `- AI next: ${aiNext}`,
+    `- AI collaboration: ${collaboration.status || "unknown"} / ${toList(collaboration.activeTargets).join(", ") || "none"} / ${collaboration.nextCommand || "aienvmp status --json"}`,
     `- 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}`,
@@ -79,6 +81,7 @@ export function renderSummary(status = {}, manifest = {}) {
     "## AI handoff",
     "",
     `- environment changes: ${status.agentUse?.environmentChanges || "intent-and-review-first"}`,
+    `- collaboration rule: ${collaboration.rule || "Record intent before shared environment changes."}`,
     `- coordination: ${coordination.next || "No open environment intents."}`,
     `- recent agent activity: ${activity.next || "No environment records need coordination."}`,
     `- conflict targets: ${conflictTargets.length ? conflictTargets.join(", ") : "none"}`,

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", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "aiReadiness", "collaboration", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }
@@ -29,7 +29,7 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "aiReadiness", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "preflight", "aiReadiness", "collaboration", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",
@@ -56,6 +56,7 @@ export function schemaContract() {
       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.",
+      collaborationRule: "Use collaboration.status, activeTargets, and nextCommand as the shortest multi-agent environment coordination hint.",
       strictPlanRule: "Use enforcement.strictPlan or preflight.enforcementProfile.strictPlan to choose the narrowest explicit strict scope for CI."
     }
   };

package/src/preflight.js

@@ -19,6 +19,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   const sbomRisk = manifest.lightSbom?.riskSummary || {};
   const agentPointers = agentPointerSummary(manifest.agentFiles);
   const aiReadiness = aiReadinessSummary({ state, decision, coordination, agentActivity, agentPointers, sbomRisk, followUps });
+  const collaboration = collaborationSummary({ state, decision, coordination, agentActivity, followUps, aiReadiness });
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -61,6 +62,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     nextAgent: nextAgentHint(state, dependencyReadSet, dependencyChangeProtocol),
     coordination,
     agentActivity,
+    collaboration,
     agentPointers,
     aiReadiness,
     sbomRisk,
@@ -92,6 +94,45 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   };
 }
 
+function collaborationSummary({ state, decision, coordination, agentActivity, followUps, aiReadiness }) {
+  const conflictTargets = coordination?.conflictTargets || [];
+  const multiActorTargets = agentActivity?.multiActorTargets || [];
+  const followUpTargets = (followUps || []).map((item) => item.target || "environment");
+  const activeTargets = unique([...conflictTargets, ...multiActorTargets, ...followUpTargets]);
+  const reviewSignals = [];
+  if (conflictTargets.length) reviewSignals.push("open intent conflict");
+  if (multiActorTargets.length) reviewSignals.push("multi-agent environment record");
+  if ((followUps || []).length) reviewSignals.push("pending post-change follow-up");
+  if (state !== "clear") reviewSignals.push("preflight review required");
+
+  const nextCommand = firstFollowUpCommand(followUps)
+    || (multiActorTargets.length ? "aienvmp handoff --record --actor agent:id" : "")
+    || (conflictTargets.length ? "aienvmp plan --write" : "")
+    || (decision?.canChangeEnvironmentWithoutReview
+      ? "aienvmp intent --actor agent:id --action planned-change --target environment"
+      : "aienvmp context --json");
+
+  const status = reviewSignals.length ? "review-before-env-change" : "clear";
+  return {
+    status,
+    mode: "advisory",
+    activeTargets,
+    reviewSignals,
+    projectLocalWork: aiReadiness?.projectLocalWork || (decision?.canContinueProjectLocalWork ? "allowed" : "review-first"),
+    environmentChanges: reviewSignals.length ? "intent-review-handoff-first" : "intent-first",
+    nextCommand,
+    rule: reviewSignals.length
+      ? "Do not install, remove, upgrade, downgrade, or switch shared environment tools until the listed collaboration signals are reviewed."
+      : "Multiple AI agents may continue project-local work; record intent before shared environment changes.",
+    commands: {
+      read: "aienvmp status --json",
+      plan: "aienvmp plan --write",
+      handoff: "aienvmp handoff --record --actor agent:id",
+      checkpoint: "aienvmp checkpoint --actor agent:id --summary what-changed --target environment"
+    }
+  };
+}
+
 function aiReadinessSummary({ state, decision, coordination, agentActivity, agentPointers, sbomRisk, followUps }) {
   const blockers = [];
   const review = [];
@@ -429,6 +470,18 @@ function normalizeTarget(target = "") {
   return normalized;
 }
 
+function unique(items = []) {
+  return [...new Set(items.map((item) => normalizeTarget(item)).filter(Boolean))];
+}
+
+function firstFollowUpCommand(followUps = []) {
+  for (const item of followUps || []) {
+    const command = item.commands?.find(Boolean);
+    if (command) return command;
+  }
+  return "";
+}
+
 function agentQuickstart(reviewRequired) {
   return {
     label: "10-second AI flow",

package/src/render.js

@@ -484,6 +484,8 @@ const followUpsHtml=followUps.length?'<div class="timeline">'+followUps.slice(0,
 const agentActivity=manifest.preflight?.agentActivity||{};
 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 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||{};
@@ -546,6 +548,8 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('Agent Activity',agentActivity.multiActorTargets?.length?'<span class="pill warn">'+agentActivity.multiActorTargets.length+' shared</span>':'<span class="pill">clear</span>',activityHtml)}
     <div style="height:14px"></div>
+    \${card('AI Collaboration',collaboration.status==='clear'?'<span class="pill">clear</span>':'<span class="pill warn">review</span>',collaborationHtml)}
+    <div style="height:14px"></div>
     \${card('AI Contract','<span class="pill">'+(contract.stability||'additive')+'</span>',contractHtml)}
     <div style="height:14px"></div>
     \${card('Dependency Read Set','<span class="pill">'+dependencyReadSet.length+' files</span>',dependencyReadSetHtml)}