aienvmp 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.5
+
+- Added machine-readable trust states for observed, planned, changed, review, verified, and stale environment facts.
+- Added multi-agent intent conflict warnings for shared runtime/package manager targets.
+- Added trust and schema context to `context`, `handoff`, `doctor`, `AIENV.md`, and the dashboard.
+- Repositioned the docs around AI environment coordination instead of general AI project memory.
+
+## 0.1.4
+
+- Added `aienvmp handoff` for next-agent environment handoff summaries.
+- Added an AI Handoff card to the dashboard.
+- Added handoff test coverage.
+
 ## 0.1.3
 
 - Strengthened the dashboard audit summary with AI decision, open intents, warnings, and recent changes.

package/README.md

@@ -6,22 +6,18 @@
 
 **AI Environment Map.**
 
-`aienvmp` gives AI agents a shared view of the current dev environment:
+`aienvmp` is an AI environment coordination tool for shared coding machines.
 
-- runtime versions
-- package managers
-- Docker state
-- project version hints
-- planned env changes
-- recent env changes
+It helps Codex, Claude, Gemini, and other agents avoid silently using or installing different runtime and tool versions.
 
-So multiple AI agents do not silently use or install different software versions.
+Core loop: scan the env, give AI a preflight context, and hand off safe next steps to the next agent.
 
 ## Use
 
 ```bash
 npx aienvmp sync
 npx aienvmp context
+npx aienvmp handoff
 ```
 
 ## Output
@@ -34,6 +30,10 @@ AIENV.md
 .aienvmp/dashboard.html
 ```
 
+Trust states are machine-readable: `observed`, `planned`, `changed`, `review`, `verified`, `stale`.
+
+AI agents can observe, plan, and record. Only a human or CI should mark environment facts as verified.
+
 ## For AGENTS.md
 
 `aienvmp` does not replace AGENTS.md. It gives AGENTS.md a live environment source of truth.
@@ -48,6 +48,7 @@ npx aienvmp snippet agents
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
 aienvmp context --json    # machine-readable AI decision context
+aienvmp handoff           # next-agent handoff summary
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed
 aienvmp doctor --ci       # strict CI check

package/ROADMAP.md

@@ -4,11 +4,11 @@
 
 ## Near Term
 
-- Policy checks for Node, Python, and package manager drift
-- Intent lifecycle: open, resolve, cancel
-- JSON output for AI/tool integrations
-- Non-blocking by default, strict only with `--ci`
-- Dashboard improvements for policy and agent coordination
+- Strengthen trust states: observed, planned, changed, review, verified, stale
+- Detect multi-agent environment intent conflicts
+- Stabilize `.aienvmp/manifest.json` and JSON command schemas
+- Keep `sync`, `context`, and `handoff` as the simple core flow
+- Improve the dashboard for 10-second human review
 
 ## Next
 
@@ -21,8 +21,8 @@
   - `pipx list`
   - `uv tool list`
 - Conflict detection:
-  - multiple open intents for the same target
   - stale unresolved intents
+  - recent runtime changes without a fresh handoff
   - package manager policy vs lockfile mismatch
 - CI mode:
   - stable exit codes

package/package.json

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

package/src/cli.js

@@ -10,6 +10,7 @@ import { intentWorkspace } from "./commands/intent.js";
 import { resolveWorkspace } from "./commands/resolve.js";
 import { syncWorkspace } from "./commands/sync.js";
 import { snippetWorkspace } from "./commands/snippet.js";
+import { handoffWorkspace } from "./commands/handoff.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -24,7 +25,8 @@ const commands = new Map([
   ["intent", intentWorkspace],
   ["resolve", resolveWorkspace],
   ["sync", syncWorkspace],
-  ["snippet", snippetWorkspace]
+  ["snippet", snippetWorkspace],
+  ["handoff", handoffWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -74,10 +76,12 @@ function printUsage() {
 Usage:
   aienvmp sync [--dir .] [--json] [--quiet]
   aienvmp context [--dir .] [--json]
+  aienvmp handoff [--dir .] [--json]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard
   aienvmp context   print the AI preflight brief
+  aienvmp handoff   print the next-agent handoff summary
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
 

package/src/commands/compile.js

@@ -13,7 +13,7 @@ export async function compileWorkspace(args) {
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
-  const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const rendered = renderAIEnv(manifest, timeline, warnings, intents, policy);
   await fs.writeFile(aiEnvPath(dir), rendered, "utf8");
   if (!args.quiet) {

package/src/commands/context.js

@@ -12,12 +12,13 @@ export async function contextWorkspace(args) {
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
-  const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const decision = contextDecision(warnings, intents);
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
       decision,
+      trust: manifest.trust || {},
       guidance: decision,
       workspace: manifest.workspace,
       runtimes: manifest.runtimes,

package/src/commands/dash.js

@@ -15,7 +15,7 @@ export async function dashWorkspace(args) {
   const timeline = await readTimeline(timelinePath(dir));
   const intents = openIntents(await readJsonl(intentsPath(dir)));
   const policy = await loadPolicy(dir);
-  const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const html = renderDashboard(manifest, timeline, warnings, intents, policy);
   const out = dashboardPath(dir);
   await fs.mkdir(path.dirname(out), { recursive: true });

package/src/commands/doctor.js

@@ -1,6 +1,7 @@
 import { diagnose } from "../doctor.js";
 import { readJson } from "../fsutil.js";
-import { manifestPath, workspaceDir } from "../paths.js";
+import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 
 export async function doctorWorkspace(args) {
@@ -8,11 +9,15 @@ export async function doctorWorkspace(args) {
   const manifest = await readJson(manifestPath(dir));
   if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
   const policy = await loadPolicy(dir);
-  const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const timeline = await readTimeline(timelinePath(dir));
+  const intents = openIntents(await readJsonl(intentsPath(dir)));
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "warning" : "ok",
+      trust: manifest.trust || {},
       policy,
+      openIntentCount: intents.length,
       warnings
     }, null, 2));
     if (args.ci && warnings.length) {

package/src/commands/handoff.js

@@ -0,0 +1,57 @@
+import { diagnose } from "../doctor.js";
+import { readJson } from "../fsutil.js";
+import { loadPolicy, policyWarnings } from "../policy.js";
+import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
+import { renderHandoff } from "../render.js";
+import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+
+export async function handoffWorkspace(args) {
+  const dir = workspaceDir(args);
+  const manifest = await readJson(manifestPath(dir));
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
+  const timeline = await readTimeline(timelinePath(dir));
+  const intents = openIntents(await readJsonl(intentsPath(dir)));
+  const policy = await loadPolicy(dir);
+  const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
+  const handoff = buildHandoff(manifest, timeline, warnings, intents, policy);
+
+  if (args.json) {
+    console.log(JSON.stringify(handoff, null, 2));
+  } else {
+    console.log(renderHandoff(handoff));
+  }
+  return handoff;
+}
+
+export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
+  const reviewRequired = warnings.length > 0 || intents.length > 0;
+  return {
+    status: reviewRequired ? "review-required" : "clear",
+    trust: manifest.trust || {},
+    schemaVersion: manifest.schemaVersion || 1,
+    workspace: manifest.workspace,
+    safeRuntime: {
+      node: manifest.runtimes?.node || "not detected",
+      python: manifest.runtimes?.python || manifest.runtimes?.python3 || "not detected",
+      docker: manifest.containers?.docker ? "available" : "not detected"
+    },
+    policy: {
+      node: policy.node || "not set",
+      python: policy.python || "not set",
+      packageManager: policy.packageManager || "not set",
+      runtimeChanges: policy.runtimeChanges || "ask-first",
+      globalInstalls: policy.globalInstalls || "ask-first"
+    },
+    openIntents: intents.slice(-5).reverse(),
+    warnings,
+    recentChanges: timeline.slice(-5).reverse(),
+    mustNotDo: [
+      "do not change global runtimes without user approval",
+      "do not install or remove global package managers without user approval",
+      "do not change Docker daemon/context assumptions without user approval"
+    ],
+    recommendedNext: reviewRequired
+      ? "review warnings and open intents before environment changes"
+      : "continue with project-local work; record intent before environment changes"
+  };
+}

package/src/commands/intent.js

@@ -1,19 +1,22 @@
 import { appendJsonLine } from "../fsutil.js";
 import { intentsPath, workspaceDir } from "../paths.js";
 import { newIntentID } from "../timeline.js";
+import { plannedTrust } from "../trust.js";
 
 export async function intentWorkspace(args) {
   const dir = workspaceDir(args);
   const actor = required(args.actor, "actor");
   const action = required(args.action, "action");
+  const now = new Date();
   const entry = {
-    at: new Date().toISOString(),
+    at: now.toISOString(),
     type: "intent",
     actor,
     action,
     target: args.target || "",
     reason: args.reason || "",
-    status: "open"
+    status: "open",
+    trust: plannedTrust(now)
   };
   entry.id = newIntentID();
   await appendJsonLine(intentsPath(dir), entry);

package/src/commands/record.js

@@ -1,12 +1,15 @@
 import { appendJsonLine } from "../fsutil.js";
 import { timelinePath, workspaceDir } from "../paths.js";
+import { changedTrust } from "../trust.js";
 
 export async function recordWorkspace(args) {
   const dir = workspaceDir(args);
   const actor = required(args.actor, "actor");
   const summary = required(args.summary || args.change, "summary");
+  const now = new Date();
+  const requiresReview = args.review === true || args.review === "true";
   const entry = {
-    at: new Date().toISOString(),
+    at: now.toISOString(),
     actor,
     type: args.type || "agent-record",
     summary,
@@ -14,7 +17,8 @@ export async function recordWorkspace(args) {
     before: args.before || "",
     after: args.after || "",
     evidence: args.evidence || "",
-    requiresReview: args.review === true || args.review === "true"
+    requiresReview,
+    trust: changedTrust(now, requiresReview)
   };
   await appendJsonLine(timelinePath(dir), entry);
   console.log(`recorded ${entry.type} by ${actor}`);

package/src/doctor.js

@@ -1,4 +1,6 @@
-export function diagnose(manifest) {
+import { isStaleTimestamp } from "./trust.js";
+
+export function diagnose(manifest, context = {}) {
   const warnings = [];
   const hints = manifest.projectHints || {};
   const runtimes = manifest.runtimes || {};
@@ -34,5 +36,43 @@ export function diagnose(manifest) {
       message: "Dockerfile detected, but Docker CLI was not found."
     });
   }
+  if (isStaleTimestamp(manifest.generatedAt)) {
+    warnings.push({
+      code: "manifest-stale",
+      message: "Environment snapshot is older than 24 hours. Run `aienvmp sync` before changing the environment."
+    });
+  }
+  warnings.push(...coordinationWarnings(context.intents || []));
+  return warnings;
+}
+
+export function coordinationWarnings(intents = []) {
+  const warnings = [];
+  const byTarget = new Map();
+  for (const intent of intents) {
+    const target = String(intent.target || inferTarget(intent.action) || "").trim().toLowerCase();
+    if (!target) continue;
+    const list = byTarget.get(target) || [];
+    list.push(intent);
+    byTarget.set(target, list);
+  }
+  for (const [target, list] of byTarget) {
+    const actors = new Set(list.map((intent) => intent.actor).filter(Boolean));
+    if (list.length > 1 && actors.size > 1) {
+      warnings.push({
+        code: "conflicting-open-intents",
+        target,
+        message: `Multiple agents have open environment intents for ${target}. Resolve or coordinate before changing it.`
+      });
+    }
+  }
   return warnings;
 }
+
+function inferTarget(action = "") {
+  const normalized = String(action).toLowerCase();
+  for (const target of ["node", "python", "docker", "npm", "pnpm", "yarn", "uv", "pip", "pipx"]) {
+    if (normalized.includes(target)) return target;
+  }
+  return "";
+}

package/src/manifest.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { commandOutput, commandVersion } from "./shell.js";
 import { exists } from "./fsutil.js";
+import { observedTrust } from "./trust.js";
 
 export async function buildManifest(dir) {
   const now = new Date().toISOString();
@@ -14,6 +15,7 @@ export async function buildManifest(dir) {
       name: "aienvmp",
       command: "aienvmp sync"
     },
+    trust: observedTrust(new Date(now)),
     workspace: {
       path: dir,
       name: path.basename(dir)
@@ -27,9 +29,15 @@ export async function buildManifest(dir) {
     agentProtocol: {
       sourceOfTruth: "AIENV.md",
       preflightCommand: "aienvmp context",
+      handoffCommand: "aienvmp handoff",
       intentCommand: "aienvmp intent --actor <agent:id> --action <planned-change>",
       recordCommand: "aienvmp record --actor <agent:id> --summary <what-changed>",
       afterEnvironmentChange: ["aienvmp sync"],
+      trustModel: {
+        agentWritable: ["observed", "planned", "changed", "review", "stale"],
+        verifiedRequires: "human-or-ci",
+        rule: "AI agents may report observations and plans, but must not mark environment facts as verified."
+      },
       globalRuntimeChangeRequiresUserApproval: true,
       globalInstallPolicy: "ask-first",
       projectLocalChanges: "allowed-when-task-requires"

package/src/render.js

@@ -19,6 +19,9 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push(...policyLines(policy));
   lines.push("- Enforcement: non-blocking by default; warnings require review but do not lock the machine.");
   lines.push("- Project-local dependency installs: allowed when required by the user task.", "");
+  lines.push("## Trust State", "");
+  lines.push(`- State: ${manifest.trust?.state || "observed"}`);
+  lines.push("- Rule: AI agents may observe, plan, and record changes, but verified requires human or CI review.", "");
   lines.push("## AI Preflight Summary", "");
   lines.push(...contextLines(manifest, warnings, intents), "");
   lines.push("## Runtime Map", "");
@@ -83,6 +86,7 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "",
     `Status: ${status}`,
     `Next: ${next}`,
+    `Trust: ${manifest.trust?.state || "observed"} (verified requires human or CI)`,
     `Workspace: ${manifest.workspace.path}`,
     `Node: ${manifest.runtimes.node || "not detected"}`,
     `Python: ${manifest.runtimes.python || manifest.runtimes.python3 || "not detected"}`,
@@ -111,6 +115,38 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
   ].join("\n");
 }
 
+export function renderHandoff(handoff) {
+  const lines = [
+    "# AI Handoff",
+    "",
+    `Status: ${handoff.status}`,
+    `Trust: ${handoff.trust?.state || "observed"} (not AI-verified)`,
+    `Schema: ${handoff.schemaVersion}`,
+    `Workspace: ${handoff.workspace?.path || "unknown"}`,
+    "",
+    "Safe runtime:",
+    `- Node: ${handoff.safeRuntime.node}`,
+    `- Python: ${handoff.safeRuntime.python}`,
+    `- Docker: ${handoff.safeRuntime.docker}`,
+    "",
+    "Open intents:",
+    ...(handoff.openIntents.length ? handoff.openIntents.map((i) => `- ${i.actor}: ${i.action}${i.target ? ` (${i.target})` : ""}`) : ["- none"]),
+    "",
+    "Warnings:",
+    ...(handoff.warnings.length ? handoff.warnings.map((w) => `- ${w.message}`) : ["- none"]),
+    "",
+    "Recent changes:",
+    ...(handoff.recentChanges.length ? handoff.recentChanges.map((t) => `- ${formatTimeline(t)}`) : ["- none"]),
+    "",
+    "Must not do:",
+    ...handoff.mustNotDo.map((item) => `- ${item}`),
+    "",
+    `Recommended next: ${handoff.recommendedNext}`,
+    ""
+  ];
+  return lines.join("\n");
+}
+
 export function renderDashboard(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const data = JSON.stringify({ manifest, timeline, warnings, intents, policy });
   return `<!doctype html>
@@ -178,8 +214,11 @@ const policyHtml=entries(policy).length?\`<table>\${rows(policy)}</table>\`:'<di
 const card=(title,badge,body)=>\`<section class="card"><div class="card-head"><h2>\${title}</h2>\${badge||''}</div>\${body}</section>\`;
 const reviewRequired=warnings.length>0||intents.length>0;
 const recentChanges=timeline.slice(-8).length;
+const trustState=manifest.trust?.state||'observed';
 const nextAction=reviewRequired?'Review before environment changes':'Proceed with project-local work';
 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 handoffHtml=\`<table><tr><th>Status</th><td>\${reviewRequired?'review-required':'clear'}</td></tr><tr><th>Trust</th><td><code>\${esc(trustState)}</code></td></tr><tr><th>Node</th><td><code>\${esc(manifest.runtimes.node||'not detected')}</code></td></tr><tr><th>Python</th><td><code>\${esc(manifest.runtimes.python||manifest.runtimes.python3||'not detected')}</code></td></tr><tr><th>Docker</th><td>\${manifest.containers?.docker?'available':'not detected'}</td></tr><tr><th>Next</th><td>\${reviewRequired?'Review warnings and open intents':'Continue project-local work'}</td></tr></table>\`;
 document.getElementById('app').innerHTML=\`
 <header>
   <div>
@@ -191,9 +230,9 @@ 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('Open intents',String(intents.length),intents.length?'Resolve or coordinate before changes':'No pending env changes')}
-  \${auditItem('Warnings',String(warnings.length),warnings.length?'Policy or drift needs attention':'No warnings detected')}
-  \${auditItem('Recent changes',String(recentChanges),recentChanges?'Check ledger before continuing':'No recent env ledger entries')}
+  \${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')}
 </section>
 <section class="metrics">
   <div class="metric"><div class="num">\${entries(manifest.runtimes).length}</div><div class="label">runtimes</div></div>
@@ -215,6 +254,8 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('Agent Intents','<span class="pill">'+intents.length+' open</span>',intentsHtml)}
     <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>')}
     <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>\`)}

package/src/trust.js

@@ -0,0 +1,41 @@
+export const TRUST_STATES = {
+  OBSERVED: "observed",
+  PLANNED: "planned",
+  CHANGED: "changed",
+  REVIEW: "review",
+  VERIFIED: "verified",
+  STALE: "stale"
+};
+
+export function observedTrust(now = new Date()) {
+  return {
+    state: TRUST_STATES.OBSERVED,
+    at: now.toISOString(),
+    by: "aienvmp scan",
+    verified: false,
+    note: "Machine-observed only. AI agents cannot mark environment facts as verified."
+  };
+}
+
+export function plannedTrust(now = new Date()) {
+  return {
+    state: TRUST_STATES.PLANNED,
+    at: now.toISOString(),
+    verified: false
+  };
+}
+
+export function changedTrust(now = new Date(), requiresReview = false) {
+  return {
+    state: requiresReview ? TRUST_STATES.REVIEW : TRUST_STATES.CHANGED,
+    at: now.toISOString(),
+    verified: false
+  };
+}
+
+export function isStaleTimestamp(value, now = new Date(), maxAgeHours = 24) {
+  if (!value) return false;
+  const then = new Date(value).getTime();
+  if (!Number.isFinite(then)) return false;
+  return now.getTime() - then > maxAgeHours * 60 * 60 * 1000;
+}