aienvmp 0.1.50 → 0.1.51

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,12 @@ 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.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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,14 @@ 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.
+
 ## Commands
 
 ```bash

package/package.json

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

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/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.`;
 }