aienvmp 0.1.52 → 0.1.54

package/BUGFIXES.md

@@ -106,6 +106,18 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `agentFiles` now records path, existence, pointer marker state, role, and install command; recommended actions suggest installing a pointer without failing local work.
 - Verification: tests cover sync pointer scanning, recommended action output, and dashboard status labels.
 
+### AI consumers had to inspect the full manifest for pointer state
+
+- Issue: `status`, `context`, and `doctor` did not expose a compact pointer summary even after manifest scanning detected it.
+- Fix: `agentPointers` now appears in status/preflight, context JSON, doctor JSON, and summary markdown.
+- Verification: regression tests cover status, context, doctor, schema, and summary outputs.
+
+### AI continuation readiness was spread across several fields
+
+- Issue: AI consumers had to infer readiness from status, intents, activity, follow-ups, pointer state, and SBOM risk separately.
+- 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.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.54
+
+- Added `aiReadiness` to the shared preflight/status contract.
+- Added root `aiReadiness` to `context --json`.
+- Added `aiReadiness` to `doctor --json` as advisory metadata.
+- Printed `ai-readiness` in plain `aienvmp status` output.
+- Added `AI readiness` to `.aienvmp/summary.md`.
+- Added an AI readiness item to the dashboard audit band.
+- Updated README, schema metadata, and regression tests for the ready/review signal.
+
+## 0.1.53
+
+- Added `agentPointers` to the shared AI preflight/status contract.
+- Added `agentPointers` to `context --json` at the root for quick AI access.
+- Added `agentPointers` to `doctor --json` without making missing pointers a blocking warning.
+- Added agent pointer status to `.aienvmp/summary.md`.
+- Added `agentPointers` to the stable schema contract metadata.
+- Preserved legacy boolean `agentFiles` compatibility in preflight summaries.
+- Added regression tests for status, context, doctor, schema, and summary pointer outputs.
+
 ## 0.1.52
 
 - Expanded `manifest.agentFiles` from booleans to lightweight agent instruction metadata.

package/README.md

@@ -50,6 +50,7 @@ AIENV.md                 # Markdown env map for AI agents
 - `schema --json` prints the stable AI-readable output contract without scanning.
 - `summary.md` is the short CI/AI handoff view.
 - `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.
 - `sbomRisk` gives AI a compact light-SBOM risk level, signals, and next command.
 - `coordination.conflictTargets` shows where multiple agents are planning changes.
@@ -73,6 +74,7 @@ npx aienvmp snippet gemini
 
 Snippets point each AI to `status`, `summary.md`, `context --json`, intent, and checkpoint without taking over the instruction file.
 `sync` records whether those pointers are installed, and `doctor` can recommend installing one without blocking local work.
+`status`, `context --json`, and `doctor --json` expose the same `agentPointers` summary for AI consumers.
 
 ## Commands
 

package/package.json

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

package/src/commands/context.js

@@ -26,7 +26,9 @@ export async function contextWorkspace(args) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
       preflight,
+      aiReadiness: preflight.aiReadiness,
       coordination: preflight.coordination,
+      agentPointers: preflight.agentPointers,
       sbomRisk: preflight.sbomRisk,
       followUps: preflight.followUps,
       decision,

package/src/commands/doctor.js

@@ -5,6 +5,7 @@ import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { recommendedActions } from "../actions.js";
 import { enforcementAdvice, strictResult } from "../enforcement.js";
+import { buildPreflight } from "../preflight.js";
 
 export { strictResult } from "../enforcement.js";
 
@@ -17,6 +18,7 @@ export async function doctorWorkspace(args) {
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const actions = recommendedActions(manifest, { warnings, intents });
+  const preflight = buildPreflight(manifest, warnings, intents, timeline);
   const strict = strictResult(warnings, args);
   const exitBehavior = {
     mode: strict.enabled ? "strict" : "advisory",
@@ -32,6 +34,8 @@ export async function doctorWorkspace(args) {
       exitBehavior,
       trust: manifest.trust || {},
       policy,
+      aiReadiness: preflight.aiReadiness,
+      agentPointers: preflight.agentPointers,
       openIntentCount: intents.length,
       warnings,
       recommendedActions: actions,

package/src/commands/status.js

@@ -22,6 +22,7 @@ export async function statusWorkspace(args) {
     console.log(JSON.stringify(output, null, 2));
   } 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(`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

@@ -51,6 +51,8 @@ export function renderSummary(status = {}, manifest = {}) {
   const dependencyProtocol = status.dependencyChangeProtocol || {};
   const dependencyCommands = dependencyProtocol.commands || {};
   const dependencyFiles = dependencyFilesFor(status.dependencyReadSet);
+  const agentPointers = status.agentPointers || {};
+  const aiReadiness = status.aiReadiness || {};
 
   return [
     "# aienvmp summary",
@@ -61,6 +63,7 @@ export function renderSummary(status = {}, manifest = {}) {
     `- 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}`,
     "",
@@ -86,6 +89,12 @@ export function renderSummary(status = {}, manifest = {}) {
     `- after: ${dependencyCommands.checkpointAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"}`,
     `- package manager policy: ${dependencyProtocol.packageManagerPolicy || "not-detected"}`,
     "",
+    "## Agent pointers",
+    "",
+    `- installed: ${toList(agentPointers.installed).join(", ") || "none"}`,
+    `- missing: ${toList(agentPointers.missing).join(", ") || "none"}`,
+    `- next: ${agentPointers.next || "Run aienvmp snippet codex --write if AI agents need instruction-file discovery."}`,
+    "",
     "## Artifacts",
     "",
     "- AIENV.md",

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", "nextAgent", "coordination", "agentActivity", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "aiReadiness", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }
@@ -28,7 +28,7 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "coordination", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "preflight", "aiReadiness", "coordination", "agentPointers", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",

package/src/preflight.js

@@ -17,6 +17,8 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   const followUps = pendingFollowUps(timeline);
   const agentActivity = agentActivitySummary(timeline);
   const sbomRisk = manifest.lightSbom?.riskSummary || {};
+  const agentPointers = agentPointerSummary(manifest.agentFiles);
+  const aiReadiness = aiReadinessSummary({ state, decision, coordination, agentActivity, agentPointers, sbomRisk, followUps });
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -58,6 +60,8 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     nextAgent: nextAgentHint(state, dependencyReadSet, dependencyChangeProtocol),
     coordination,
     agentActivity,
+    agentPointers,
+    aiReadiness,
     sbomRisk,
     followUps,
     intentTargets,
@@ -87,6 +91,31 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   };
 }
 
+function aiReadinessSummary({ state, decision, coordination, agentActivity, agentPointers, sbomRisk, followUps }) {
+  const blockers = [];
+  const review = [];
+  if (state !== "clear") review.push("status review required");
+  if ((coordination?.conflictTargets || []).length) review.push("open intent conflicts");
+  if ((agentActivity?.multiActorTargets || []).length) review.push("multi-agent environment activity");
+  if ((followUps || []).length) review.push("pending environment follow-ups");
+  if (["urgent", "high"].includes(sbomRisk?.level)) review.push("high light SBOM risk");
+  if ((agentPointers?.targets || []).length && (agentPointers?.installedCount || 0) === 0) review.push("no agent instruction pointer installed");
+
+  const level = review.length ? "review" : "ready";
+  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.";
+  return {
+    level,
+    projectLocalWork: decision?.canContinueProjectLocalWork ? "allowed" : "review-first",
+    environmentChanges: decision?.canChangeEnvironmentWithoutReview ? "allowed" : "intent-and-review-first",
+    signals: review,
+    blockers,
+    next,
+    mode: "advisory"
+  };
+}
+
 function agentActivitySummary(timeline = []) {
   const lastHandoffAt = lastTime(timeline, (item) => item.type === "agent-handoff");
   const envRecords = timeline
@@ -123,6 +152,59 @@ function agentActivitySummary(timeline = []) {
   };
 }
 
+export function agentPointerSummary(agentFiles = {}) {
+  const entries = Object.entries(agentFiles || {}).filter(([name]) => ["agents", "claude", "gemini"].includes(name));
+  const targets = entries.map(([name, item]) => {
+    const normalized = normalizeAgentFile(item);
+    return {
+      name,
+      role: normalized.role || (name === "agents" ? "codex" : name),
+      file: normalized.path || defaultAgentFile(name),
+      exists: normalized.exists,
+      hasPointer: normalized.hasAienvmpPointer,
+      installCommand: normalized.installCommand || defaultInstallCommand(name)
+    };
+  });
+  const installed = targets.filter((item) => item.hasPointer);
+  const missing = targets.filter((item) => !item.hasPointer);
+  return {
+    installedCount: installed.length,
+    missingCount: missing.length,
+    installed: installed.map((item) => item.role),
+    missing: missing.map((item) => item.role),
+    targets,
+    next: missing.length
+      ? `Install a pointer with ${missing[0].installCommand} if this workspace uses that AI.`
+      : "Agent instruction pointers are installed for detected AI instruction files.",
+    mode: "advisory"
+  };
+}
+
+function normalizeAgentFile(item) {
+  if (typeof item === "boolean") {
+    return { exists: item, hasAienvmpPointer: item };
+  }
+  return {
+    path: item?.path || "",
+    exists: item?.exists === true,
+    hasAienvmpPointer: item?.hasAienvmpPointer === true,
+    installCommand: item?.installCommand || "",
+    role: item?.role || ""
+  };
+}
+
+function defaultAgentFile(name) {
+  if (name === "claude") return "CLAUDE.md";
+  if (name === "gemini") return "GEMINI.md";
+  return "AGENTS.md";
+}
+
+function defaultInstallCommand(name) {
+  if (name === "claude") return "aienvmp snippet claude --write";
+  if (name === "gemini") return "aienvmp snippet gemini --write";
+  return "aienvmp snippet codex --write";
+}
+
 function coordinationSummary(intents = []) {
   const byTarget = new Map();
   for (const intent of intents) {

package/src/render.js

@@ -493,6 +493,7 @@ const nextAction=reviewRequired?'Review before environment changes':'Proceed wit
 const auditItem=(key,value,hint,klass='')=>\`<div class="audit-item \${klass}"><div class="audit-k">\${key}</div><div class="audit-v">\${value}</div><div class="audit-hint">\${hint}</div></div>\`;
 const driftLabel=warnings.length?'detected':'none';
 const nextAgent=manifest.preflight?.nextAgent||{};
+const aiReadiness=manifest.preflight?.aiReadiness||{};
 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):[]);
@@ -509,6 +510,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('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')}