aienvmp 0.1.50 → 0.1.52

package/.agents/skills/aienvmp/SKILL.md

@@ -11,20 +11,26 @@ The goal is to help multiple AI agents avoid silently installing or using differ
 
 ## Preflight
 
-Before environment-impacting work, run:
+Before environment-impacting work, run the light preflight first:
 
 ```bash
-npx aienvmp context
+npx aienvmp status --write
 ```
 
-If the output says `review-required`, do not change global runtimes, package managers, Docker settings, or global packages without asking the user.
+Then read the short handoff:
 
-For machine-readable context, use:
+```bash
+cat .aienvmp/summary.md
+```
+
+For deeper machine-readable context, use:
 
 ```bash
 npx aienvmp context --json
 ```
 
+If the output says `review-required`, do not change global runtimes, package managers, Docker settings, dependencies, lockfiles, or global packages without asking the user.
+
 ## Before Environment Changes
 
 Record intent before changing shared environment state:
@@ -38,26 +44,25 @@ Use this for changes such as:
 - installing or upgrading Node, Python, Docker, package managers, or global CLIs
 - changing `.nvmrc`, `.python-version`, `mise.toml`, `.tool-versions`, or `.aienvmp/policy.yml`
 - switching package managers
+- changing dependencies or lockfiles
 - changing Docker daemon/context assumptions
 
 ## After Environment Changes
 
-Refresh the environment map:
+Use the one-command checkpoint after an accepted environment change:
 
 ```bash
-npx aienvmp sync
+npx aienvmp checkpoint --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>"
 ```
 
-Record what changed:
+This records the change, refreshes the env map, writes status/summary/SBOM artifacts, and records a handoff.
 
-```bash
-npx aienvmp record --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>" --evidence "<command or file>"
-```
-
-Resolve the original intent if complete:
+If checkpoint is not available, use the explicit fallback:
 
 ```bash
-npx aienvmp resolve --actor agent:codex --id "<intent-id>"
+npx aienvmp sync
+npx aienvmp record --actor agent:codex --summary "<what changed>" --target "<tool-or-runtime>" --evidence "<command or file>"
+npx aienvmp handoff --record --actor agent:codex
 ```
 
 ## Safety Rules
@@ -66,6 +71,7 @@ npx aienvmp resolve --actor agent:codex --id "<intent-id>"
 - Treat policy mismatches as review-required.
 - Do not install, upgrade, downgrade, or remove global software unless the user explicitly asks.
 - Prefer project-local version files and local environments.
+- Do not switch package managers or rewrite lockfiles only to satisfy a tool preference.
 - Do not use warnings as permission to interrupt production or shared workspace operations.
 - Use `npx aienvmp doctor --ci` only in CI or explicit strict-mode automation.
 

package/BUGFIXES.md

@@ -94,6 +94,18 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `readJson` now strips a leading UTF-8 BOM before parsing.
 - Verification: regression tests cover BOM JSON parsing and Windows smoke testing confirmed dependency counts in `summary.md`.
 
+### Agent instructions lagged behind the current protocol
+
+- Issue: packaged skill and pointer snippets still emphasized older context/record flows and did not direct agents to `summary.md`.
+- Fix: snippets and the Codex skill now use the current status, summary, context, intent, and checkpoint flow with agent-specific actor examples.
+- Verification: regression tests cover snippet output for AGENTS.md, Claude, and Gemini, and summary/status tests cover the read order and dependency protocol.
+
+### AI pointer files were only detected as booleans
+
+- Issue: AI and humans could see that an instruction file existed, but not whether it actually contained the aienvmp pointer.
+- 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.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.52
+
+- Expanded `manifest.agentFiles` from booleans to lightweight agent instruction metadata.
+- Detected whether AGENTS.md, CLAUDE.md, and GEMINI.md contain the aienvmp pointer marker.
+- Added install commands and roles to agent instruction metadata.
+- Added a low-priority recommended action when no AI instruction pointer is installed.
+- Updated the dashboard Agent Pointers card to distinguish installed pointers, missing pointers, and missing files.
+- Updated README guidance to mention pointer detection and non-blocking doctor recommendations.
+- Added regression tests for pointer scanning, pointer recommendations, dashboard rendering, and sync output.
+
+## 0.1.51
+
+- Updated Codex/Claude/Gemini pointer snippets to use the current `status -> summary.md -> context` read order.
+- Added agent-specific actor examples for Codex, Claude, and Gemini snippet output.
+- Added dependency and lockfile changes to the snippet environment-change scope.
+- Updated the packaged Codex skill to prefer `status --write`, `summary.md`, and `checkpoint`.
+- Added `.aienvmp/summary.md` to the shared preflight read order and next-agent hint.
+- Added a Dependency changes section to `summary.md` with read files, intent command, checkpoint command, and package-manager policy.
+- Updated README agent-file guidance and added regression coverage for the AI snippet and summary protocol.
+
 ## 0.1.50
 
 - Added `aienvmp summary` for a compact Markdown AI/CI handoff view.

package/README.md

@@ -65,11 +65,15 @@ AIENV.md                 # Markdown env map for AI agents
 `aienvmp` does not replace AGENTS.md, CLAUDE.md, or GEMINI.md. It gives them a live environment source of truth.
 
 ```bash
+npx aienvmp snippet codex
 npx aienvmp snippet agents
 npx aienvmp snippet claude
 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.
+
 ## Commands
 
 ```bash

package/package.json

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

package/src/actions.js

@@ -21,6 +21,7 @@ export function recommendedActions(manifest = {}, context = {}) {
 
   actions.push(...securityActions(manifest.security));
   actions.push(...sbomRiskActions(manifest.lightSbom?.riskSummary));
+  actions.push(...agentPointerActions(manifest.agentFiles));
 
   if (hasRuntimePolicyWarning(warnings)) {
     actions.push(action("review-version-policy", "medium", "runtime", "Detected runtime or package manager policy drift. Prefer project-local version files and ask before global changes."));
@@ -74,6 +75,25 @@ function securityActions(security = {}) {
   )];
 }
 
+function agentPointerActions(agentFiles = {}) {
+  const known = Object.entries(agentFiles || {}).filter(([name]) => ["agents", "claude", "gemini"].includes(name));
+  if (!known.length) return [];
+  if (known.some(([, item]) => hasPointer(item))) return [];
+  const first = known.find(([, item]) => item?.installCommand) || known[0];
+  return [action(
+    "install-agent-pointer",
+    "low",
+    "agent-instructions",
+    "Install an aienvmp pointer in an agent instruction file so future AI agents discover the env map before changing runtimes or dependencies.",
+    first?.[1]?.installCommand || "aienvmp snippet codex --write"
+  )];
+}
+
+function hasPointer(item) {
+  if (typeof item === "boolean") return item;
+  return item?.hasAienvmpPointer === true;
+}
+
 function action(id, priority, category, summary, command = "") {
   return { id, priority, category, summary, command };
 }

package/src/cli.js

@@ -140,7 +140,7 @@ Advanced:
   aienvmp resolve [--dir .] --actor human:you --id <intent-id> [--status resolved|cancelled]
   aienvmp record [--dir .] --actor agent:codex --summary "updated .nvmrc" [--target node] [--before 20] [--after 24]
   aienvmp checkpoint [--dir .] --actor agent:codex --summary "updated dependency" [--target dependency]
-  aienvmp snippet [agents|claude|gemini] [--write AGENTS.md]
+  aienvmp snippet [agents|codex|claude|gemini] [--write AGENTS.md]
   aienvmp compile [--dir .]
   aienvmp diff [--dir .]
   aienvmp doctor [--dir .] [--json] [--ci] [--strict security|policy|coordination|all]

package/src/commands/summary.js

@@ -48,6 +48,9 @@ export function renderSummary(status = {}, manifest = {}) {
   const riskSignals = toList(sbomRisk.signals).slice(0, 3);
   const conflictTargets = toList(coordination.conflictTargets);
   const multiActorTargets = toList(activity.multiActorTargets);
+  const dependencyProtocol = status.dependencyChangeProtocol || {};
+  const dependencyCommands = dependencyProtocol.commands || {};
+  const dependencyFiles = dependencyFilesFor(status.dependencyReadSet);
 
   return [
     "# aienvmp summary",
@@ -76,6 +79,13 @@ export function renderSummary(status = {}, manifest = {}) {
     `- signals: ${riskSignals.length ? riskSignals.join("; ") : "none"}`,
     `- verify: ${sbomRisk.next || "Use a dedicated scanner for security decisions."}`,
     "",
+    "## Dependency changes",
+    "",
+    `- read files: ${dependencyFiles.length ? dependencyFiles.join(", ") : "none detected"}`,
+    `- before: ${dependencyCommands.recordIntent || "aienvmp intent --actor agent:id --action planned-change --target dependency"}`,
+    `- after: ${dependencyCommands.checkpointAfterChange || "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"}`,
+    `- package manager policy: ${dependencyProtocol.packageManagerPolicy || "not-detected"}`,
+    "",
     "## Artifacts",
     "",
     "- AIENV.md",
@@ -94,3 +104,15 @@ function valueOrZero(value) {
 function toList(value) {
   return Array.isArray(value) ? value.filter(Boolean) : [];
 }
+
+function dependencyFilesFor(readSet = []) {
+  const files = [];
+  for (const item of toList(readSet).slice(0, 3)) {
+    if (item.manifest) files.push(item.manifest);
+    for (const lockfile of toList(item.lockfiles).slice(0, 3)) {
+      const file = typeof lockfile === "string" ? lockfile : lockfile?.file;
+      if (file && !files.includes(file)) files.push(file);
+    }
+  }
+  return files.slice(0, 8);
+}

package/src/manifest.js

@@ -205,11 +205,32 @@ async function scanAgentFiles(dir) {
   };
   const out = {};
   for (const [name, rel] of Object.entries(files)) {
-    out[name] = await exists(path.join(dir, rel));
+    const full = path.join(dir, rel);
+    const fileExists = await exists(full);
+    const content = fileExists ? await fs.readFile(full, "utf8") : "";
+    out[name] = {
+      path: rel,
+      exists: fileExists,
+      hasAienvmpPointer: content.includes("<!-- aienvmp:begin -->") && content.includes("<!-- aienvmp:end -->"),
+      installCommand: snippetCommand(name),
+      role: agentRole(name)
+    };
   }
   return out;
 }
 
+function snippetCommand(name) {
+  if (name === "agents") return "aienvmp snippet codex --write";
+  if (["claude", "gemini"].includes(name)) return `aienvmp snippet ${name} --write`;
+  return "";
+}
+
+function agentRole(name) {
+  if (name === "agents") return "codex";
+  if (["claude", "gemini"].includes(name)) return name;
+  return "external";
+}
+
 function compact(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, value]) => value));
 }

package/src/preflight.js

@@ -66,6 +66,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     artifacts: preflightArtifacts(),
     readOrder: [
       ".aienvmp/status.json",
+      ".aienvmp/summary.md",
       "AIENV.md",
       ".aienvmp/manifest.json",
       ".aienvmp/plan.json",
@@ -195,6 +196,7 @@ function nextAgentHint(state, dependencyReadSet = [], dependencyChangeProtocol =
   return {
     handoffCommand: dependencyChangeProtocol.commands?.handoff || "aienvmp handoff --record --actor agent:id",
     readFirst: ".aienvmp/status.json",
+    readSummary: ".aienvmp/summary.md",
     readNext: "aienvmp context --json",
     reviewState: state,
     dependencyFiles,

package/src/render.js

@@ -114,18 +114,30 @@ function preflightLines(preflight = {}) {
 
 export function renderAgentPointer(target = "agents") {
   const label = target === "claude" ? "Claude" : target === "gemini" ? "Gemini" : "AI agents";
+  const actor = target === "claude"
+    ? "agent:claude"
+    : target === "gemini"
+      ? "agent:gemini"
+      : target === "codex"
+        ? "agent:codex"
+        : "agent:id";
   return `## aienvmp Environment Map
 
 ${label} should use \`aienvmp\` as the workspace environment source of truth.
 
-Before changing runtimes, package managers, Docker settings, global packages, or environment policy:
+Fast read order:
 
 1. Run \`aienvmp status --write\`.
-2. Run \`aienvmp context --json\` for details.
-3. Read \`AIENV.md\`.
-4. If status or context says \`review-required\`, ask the user before changing the environment.
-5. Record planned environment changes with the recommended target, for example \`aienvmp intent --actor agent:id --action planned-change --target dependency\`.
-6. After environment changes, run \`aienvmp checkpoint --actor agent:id --summary what-changed --target environment\`.
+2. Read \`.aienvmp/summary.md\` for the short handoff.
+3. Run \`aienvmp context --json\` for details.
+4. Read \`AIENV.md\` when Markdown context is easier.
+
+Before changing runtimes, package managers, Docker settings, global packages, dependencies, lockfiles, or environment policy:
+
+1. If status or context says \`review-required\`, ask the user before changing the environment.
+2. Record planned environment changes with the recommended target, for example \`aienvmp intent --actor ${actor} --action planned-change --target dependency\`.
+3. Prefer project-local version files and local environments.
+4. After accepted environment changes, run \`aienvmp checkpoint --actor ${actor} --summary what-changed --target environment\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
@@ -433,7 +445,11 @@ const securityHtml=sec.enabled?\`<table><tr><th>Total</th><td><code>\${esc(secSu
 const change=c=>c.type==='changed'?\`\${c.scope} \${c.key}: \${c.before} -> \${c.after}\`:\`\${c.scope} \${c.key}: \${c.type} \${c.after||c.before}\`;
 const timelineLabel=t=>t.change?change(t.change):(t.summary||t.action||t.type||'recorded change');
 const agentNames={agents:'Codex',claude:'Claude',gemini:'Gemini'};
-const agentCards=Object.entries(agentNames).map(([key,label])=>\`<div class="agent"><strong>\${label}</strong><span>\${manifest.agentFiles?.[key]?'instruction file detected':'not detected'}</span></div>\`).join('');
+const agentInfo=v=>typeof v==='object'&&v? v : {exists:!!v,hasAienvmpPointer:!!v,path:''};
+const agentHasPointer=v=>agentInfo(v).hasAienvmpPointer===true;
+const agentStatus=v=>agentHasPointer(v)?'aienvmp pointer installed':(agentInfo(v).exists?'file detected, pointer missing':'not detected');
+const agentCards=Object.entries(agentNames).map(([key,label])=>\`<div class="agent"><strong>\${label}</strong><span>\${esc(agentStatus(manifest.agentFiles?.[key]))}</span>\${agentInfo(manifest.agentFiles?.[key]).installCommand?\`<span class="path">\${esc(agentInfo(manifest.agentFiles?.[key]).installCommand)}</span>\`:''}</div>\`).join('');
+const agentPointerCount=entries(manifest.agentFiles).filter(([,v])=>agentHasPointer(v)).length;
 const warnHtml=warnings.length?'<div class="warnings">'+warnings.map(w=>\`<div class="warning">\${esc(w.message)}</div>\`).join('')+'</div>':'<div class="okline">No blocking environment warnings detected.</div>';
 const timelineHtml=timeline.length?'<div class="timeline">'+timeline.slice(-8).reverse().map(t=>\`<div class="event"><time>\${esc(t.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(t.actor||'system')}</b> \${esc(timelineLabel(t))}</div></div>\`).join('')+'</div>':'<div class="okline">No previous environment changes recorded.</div>';
 const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reverse().map(i=>\`<div class="event"><time>\${esc(i.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(i.actor)}</b> plans \${esc(i.action)}</div></div>\`).join('')+'</div>':'<div class="okline">No pending agent intents recorded.</div>';
@@ -549,7 +565,7 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('AI Handoff',reviewRequired?'<span class="pill warn">review</span>':'<span class="pill">ready</span>',handoffHtml)}
     <div style="height:14px"></div>
-    \${card('Agent Pointers','<span class="pill">'+entries(manifest.agentFiles).filter(([,v])=>v).length+' detected</span>','<div class="agents">'+agentCards+'</div>')}
+    \${card('Agent Pointers','<span class="pill">'+agentPointerCount+' installed</span>','<div class="agents">'+agentCards+'</div>')}
     <div style="height:14px"></div>
     \${card('Snapshot','',\`<table><tr><th>OS</th><td>\${esc(manifest.os.platform)} \${esc(manifest.os.release)} \${esc(manifest.os.arch)}</td></tr><tr><th>Shell</th><td>\${esc(manifest.os.shell||'unknown')}</td></tr><tr><th>Workspace</th><td><div class="path">\${esc(manifest.workspace.path)}</div></td></tr></table>\`)}
   </aside>