aienvmp 0.1.65 → 0.1.67

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.67
+
+- Added a dashboard `First read` strip with status, first file, review targets, and local operation mode.
+- Kept the detailed dashboard cards below the top decision area so humans get a faster scan without losing AI context.
+- Added `maintenanceLoop` to the AI preflight contract so agents can repeat refresh, decide, inspect, plan, intent, checkpoint, and handoff steps.
+- Surfaced the maintenance loop in `context --json`, `summary.md`, `AIENV.md`, schema metadata, and regression tests.
+- Added `maintenanceLoop.sbomReview` so AI agents can connect SBOM risk, scanner confidence, review targets, and dependency-change commands.
+- Added medium light-SBOM risk planning guidance to recommended actions.
+- Added `strictDecision` so AI agents and CI can distinguish local warn-only checks from optional strict gates.
+- Surfaced local `doctor --json` and scoped CI strict commands in summary, dashboard, status/context JSON, and tests.
+- Added `handoff.continuation` so the next AI receives maintenance-loop, SBOM-review, and strict-decision guidance without parsing the full preflight.
+- Added the continuation summary to plain Markdown handoff output and schema metadata.
+- Reworked the README first-read flow around shared AI workspaces, the 10-second command path, and the AI maintenance loop.
+- Added `aiLoop` to `schema --json` and plain schema output so AI consumers see the same loop described in the README.
+
+## 0.1.66
+
+- Added `aienvmp resolve --target <target>` to resolve all open intents for one environment target.
+- Added `aienvmp resolve --all` to close all open intents after coordination.
+- Added `resolve --json` output so AI agents can read resolved refs and counts directly.
+- Kept single-intent `resolve --id` behavior for precise manual cleanup.
+- Updated coordination recommended actions to point at target-based resolve.
+- Updated CLI help and README command guidance for the simplified resolve flow.
+- Added regression tests for target resolve, all resolve, JSON output, and coordination action commands.
+
 ## 0.1.65
 
 - Added a dashboard `Next command` bar directly below the AI control strip.

package/README.md

@@ -6,28 +6,54 @@
 
 **AI Environment Map.**
 
-`aienvmp` is a lightweight env map and light SBOM for shared AI coding machines.
+`aienvmp` is a lightweight env map and light SBOM for AI coding workspaces.
 
-It helps Codex, Claude, Gemini, and humans avoid silent runtime, package manager, dependency, Docker, and security drift.
+It helps Codex, Claude, Gemini, and humans avoid silent runtime, package manager, dependency, Docker, and security drift on shared machines.
+
+**Use it when multiple AI agents or people touch the same server, repo, laptop, or CI workspace.**
+
+## Why
+
+- one AI-readable environment map
+- one lightweight SBOM view
+- one append-only intent and change timeline
+- one human dashboard
+- advisory by default, strict only when requested
 
 ## 10-Second Use
 
 ```bash
 npx aienvmp sync
 npx aienvmp status
+npx aienvmp handoff
+```
+
+For AI details:
+
+```bash
 npx aienvmp context --json
 npx aienvmp schema --json
 ```
 
-Before environment changes:
+Before an environment-affecting change:
 
 ```bash
-npx aienvmp intent --actor agent:codex --action "change dependency" --target dependency
-npx aienvmp checkpoint --actor agent:codex --summary "dependency-change" --target dependency
+npx aienvmp intent --actor agent:id --action "planned-change" --target dependency
+npx aienvmp checkpoint --actor agent:id --summary "dependency-change" --target dependency
 ```
 
-Use `--dir <workspace>` when AI or CI runs outside the target project.
-Warnings are advisory by default. Use `doctor --strict <scope>` only when you want CI-style failure.
+Use `--dir <workspace>` when AI or CI runs outside the target project. Warnings do not block local work by default.
+
+## AI Loop
+
+1. `sync` refreshes `AIENV.md`, status, summary, SBOM, ledger, and dashboard.
+2. `status` gives the 5-line clear/review decision.
+3. `context --json` gives AI the full preflight contract.
+4. `intent` records planned env changes before touching dependencies, runtimes, package managers, Docker, or global tools.
+5. `checkpoint` records the accepted change, refreshes outputs, and writes a handoff.
+6. `handoff` tells the next AI what to read, what to avoid, and whether SBOM/strict review is needed.
+
+Local mode is warn-only. Use `doctor --strict security|policy|coordination|all` only for CI or explicit human-requested gates.
 
 ## What It Creates
 
@@ -46,23 +72,12 @@ AIENV.md                 # Markdown env map for AI agents
 
 ## AI Contract
 
-- `status`, `context`, `plan`, and `handoff` share one preflight contract.
-- `schema --json` prints the stable AI-readable output contract without scanning.
-- `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.
-- `dashboard.html` starts with a 3-card AI control strip plus one 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.
-- `coordination.conflictTargets` shows where multiple agents are planning changes.
-- `agentActivity.multiActorTargets` shows where multiple agents actually recorded env changes.
-- `followUps` shows records that still need `sync`, `status`, or `handoff`.
-- `handoff` carries dependency read-set and protocol guidance for the next AI.
-- Light SBOM includes source/confidence hints; verify security claims with dedicated scanners.
-- `enforcementProfile.gate` explains when checks warn, fail, and set exit codes.
-- Everything is advisory by default; strict failure is opt-in with `doctor --strict` or `--ci`.
+- `status`, `context`, `plan`, and `handoff` share one additive preflight contract.
+- `maintenanceLoop` gives AI the recurring env-management loop.
+- `sbomRisk` and `sbomReview` connect light SBOM risk to safe dependency-change steps.
+- `collaboration`, `coordination`, and `agentActivity` show multi-agent conflicts and shared targets.
+- `strictDecision` separates local warn-only checks from optional CI strict gates.
+- `schema --json` prints the stable machine-readable contract without scanning.
 
 ## Agent Files
 
@@ -94,6 +109,7 @@ aienvmp schema --json           # stable output contract for AI/CI consumers
 aienvmp plan --write            # read-only action plan
 aienvmp handoff --record        # next-agent summary
 aienvmp intent                  # record planned env change
+aienvmp resolve --target dependency --actor agent:id
 aienvmp record                  # record what changed
 aienvmp checkpoint              # record + sync + status + handoff after env change
 aienvmp doctor --strict security|policy|coordination|all

package/package.json

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

package/src/actions.js

@@ -12,7 +12,7 @@ export function recommendedActions(manifest = {}, context = {}) {
   }
 
   if (warnings.some((warning) => warning.code === "conflicting-open-intents")) {
-    actions.push(action("coordinate-agents", "high", "coordination", "Multiple agents are planning changes to the same environment target. Coordinate with the user before proceeding."));
+    actions.push(action("coordinate-agents", "high", "coordination", "Multiple agents are planning changes to the same environment target. Coordinate with the user before proceeding.", "aienvmp resolve --actor agent:id --target <target> --status resolved"));
   }
 
   if (warnings.some((warning) => warning.code === "multi-agent-records")) {
@@ -44,8 +44,14 @@ function sbomRiskActions(risk = {}) {
   if (risk.scanner === "off" && risk.vulnerabilityCount === 0) {
     actions.push(action("scan-sbom-risk", "medium", "security", "Run a read-only security scan before dependency or release decisions.", "aienvmp sync --security"));
   }
-  if (["urgent", "high"].includes(risk.level)) {
-    actions.push(action("review-sbom-risk", "high", "security", `Review light SBOM risk summary before dependency changes: ${(risk.signals || []).slice(0, 2).join("; ") || risk.level}.`, "aienvmp plan --write"));
+  if (["urgent", "high", "medium"].includes(risk.level)) {
+    actions.push(action(
+      "review-sbom-risk",
+      ["urgent", "high"].includes(risk.level) ? "high" : "medium",
+      "security",
+      `Review light SBOM risk summary before dependency changes: ${(risk.signals || []).slice(0, 2).join("; ") || risk.level}.`,
+      "aienvmp plan --write"
+    ));
   }
   return actions;
 }

package/src/cli.js

@@ -137,7 +137,7 @@ Advanced:
   aienvmp init [--dir .]
   aienvmp scan [--dir .] [--deep] [--security]
   aienvmp intent [--dir .] --actor agent:codex --action "install pnpm"
-  aienvmp resolve [--dir .] --actor human:you --id <intent-id> [--status resolved|cancelled]
+  aienvmp resolve [--dir .] --actor human:you (--id <intent-id>|--target dependency|--all) [--status resolved|cancelled] [--json]
   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|codex|claude|gemini] [--write AGENTS.md]

package/src/commands/context.js

@@ -28,6 +28,7 @@ export async function contextWorkspace(args) {
       preflight,
       aiReadiness: preflight.aiReadiness,
       collaboration: preflight.collaboration,
+      maintenanceLoop: preflight.maintenanceLoop,
       coordination: preflight.coordination,
       agentPointers: preflight.agentPointers,
       sbomRisk: preflight.sbomRisk,

package/src/commands/handoff.js

@@ -62,6 +62,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
     inventory: inventorySummary(manifest.inventory),
     security: securitySummary(manifest.security),
     dependencyHandoff: dependencyHandoffSummary(preflight),
+    continuation: continuationSummary(preflight),
     coordination: preflight.coordination,
     agentActivity: preflight.agentActivity,
     policy: {
@@ -86,6 +87,37 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
   };
 }
 
+function continuationSummary(preflight = {}) {
+  const maintenanceLoop = preflight.maintenanceLoop || {};
+  const strictDecision = preflight.enforcementProfile?.strictDecision || preflight.enforcement?.strictDecision || {};
+  const sbomReview = maintenanceLoop.sbomReview || {};
+  return {
+    status: preflight.state || "unknown",
+    nextCommand: maintenanceLoop.nextCommand || preflight.nextCommand || "aienvmp status --json",
+    readOrder: (maintenanceLoop.readOrder || preflight.readOrder || []).slice(0, 4),
+    maintenance: {
+      mode: maintenanceLoop.mode || "advisory",
+      localImpact: maintenanceLoop.localImpact || "read-only until an AI or human records a change",
+      sbomCommand: maintenanceLoop.sbomCommand || "aienvmp sbom --json",
+      rule: maintenanceLoop.rule || "Keep local operation advisory and lightweight."
+    },
+    sbomReview: {
+      status: sbomReview.status || "unknown",
+      riskLevel: sbomReview.riskLevel || "unknown",
+      securityConfidence: sbomReview.securityConfidence || "unknown",
+      nextCommand: sbomReview.nextCommand || maintenanceLoop.sbomCommand || "aienvmp sbom --json",
+      reviewTargets: (sbomReview.reviewTargets || []).slice(0, 5)
+    },
+    strict: {
+      localCommand: strictDecision.localCommand || "aienvmp doctor --json",
+      local: strictDecision.local || "warn-only",
+      shouldFailLocal: strictDecision.shouldFailLocal === true,
+      ciCommand: strictDecision.ciCommand || "aienvmp doctor --strict all --json",
+      rule: strictDecision.rule || "Local checks stay advisory; strict failure is opt-in."
+    }
+  };
+}
+
 function dependencyHandoffSummary(preflight = {}) {
   const protocol = preflight.dependencyChangeProtocol || {};
   return {

package/src/commands/resolve.js

@@ -5,18 +5,32 @@ import { intentsPath, workspaceDir } from "../paths.js";
 export async function resolveWorkspace(args) {
   const dir = workspaceDir(args);
   const actor = required(args.actor, "actor");
-  const requested = required(args.id || args.ref, "id");
-  const ref = await resolveIntentRef(dir, requested);
-  const entry = {
-    at: new Date().toISOString(),
+  const refs = await resolveIntentRefs(dir, args);
+  const now = new Date().toISOString();
+  const entries = refs.map((ref) => ({
+    at: now,
     type: "intent-resolved",
     actor,
     ref,
     status: args.status || "resolved",
     reason: args.reason || ""
+  }));
+  for (const entry of entries) {
+    await appendJsonLine(intentsPath(dir), entry);
+  }
+  const output = {
+    status: args.status || "resolved",
+    count: entries.length,
+    refs,
+    actor,
+    reason: args.reason || ""
   };
-  await appendJsonLine(intentsPath(dir), entry);
-  console.log(`intent ${entry.status}: ${ref}`);
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else if (!args.quiet) {
+    console.log(`intents ${output.status}: ${output.count}${refs.length ? ` (${refs.join(", ")})` : ""}`);
+  }
+  return output;
 }
 
 function required(value, name) {
@@ -24,8 +38,22 @@ function required(value, name) {
   return String(value);
 }
 
-async function resolveIntentRef(dir, requested) {
+async function resolveIntentRefs(dir, args) {
   const open = openIntents(await readJsonl(intentsPath(dir)));
+  if (args.all) return open.map((intent) => intent.id);
+  if (args.target) {
+    const target = String(args.target).trim().toLowerCase();
+    const refs = open
+      .filter((intent) => String(intent.target || "").trim().toLowerCase() === target)
+      .map((intent) => intent.id);
+    if (!refs.length) throw new Error(`resolve: no open intents for target "${target}"`);
+    return refs;
+  }
+  const requested = required(args.id || args.ref, "id");
+  return [await resolveIntentRef(open, requested)];
+}
+
+async function resolveIntentRef(open, requested) {
   const matches = open.filter((intent) => intent.id === requested || intent.id.startsWith(requested));
   if (matches.length === 1) return matches[0].id;
   if (matches.length > 1) {

package/src/commands/schema.js

@@ -10,6 +10,7 @@ export async function schemaWorkspace(args = {}) {
     console.log(`status: ${schema.outputs.status.command}`);
     console.log(`context: ${schema.outputs.context.command}`);
     console.log(`handoff: ${schema.outputs.handoff.command}`);
+    console.log(`loop: ${schema.aiLoop.steps.map((item) => item.command).join(" -> ")}`);
     console.log(`rule: ${schema.compatibility.consumerRule}`);
   }
   return schema;

package/src/commands/summary.js

@@ -38,6 +38,8 @@ export function renderSummary(status = {}, manifest = {}) {
   const coordination = status.coordination || {};
   const activity = status.agentActivity || {};
   const collaboration = status.collaboration || {};
+  const maintenanceLoop = status.maintenanceLoop || {};
+  const sbomReview = maintenanceLoop.sbomReview || {};
   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";
@@ -58,6 +60,7 @@ export function renderSummary(status = {}, manifest = {}) {
   const aiNext = aiReadiness.next || "Run aienvmp context --json for details.";
   const aiDependencyReview = manifest.lightSbom?.aiDependencyReview || {};
   const strictPlan = status.enforcementProfile?.strictPlan || status.enforcement?.strictPlan || {};
+  const strictDecision = status.enforcementProfile?.strictDecision || status.enforcement?.strictDecision || {};
 
   return [
     "# aienvmp summary",
@@ -66,9 +69,11 @@ export function renderSummary(status = {}, manifest = {}) {
     `- 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 maintenance loop: ${maintenanceLoop.nextCommand || next}`,
     `- 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}`,
+    `- local check: ${strictDecision.localCommand || "aienvmp doctor --json"} (${strictDecision.local || "warn-only"})`,
     `- CI strict: ${strictPlan.ciCommand || `${strict} --json`}`,
     "",
     `- state: ${status.state || "unknown"}`,
@@ -84,6 +89,7 @@ export function renderSummary(status = {}, manifest = {}) {
     `- 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."}`,
+    `- maintenance rule: ${maintenanceLoop.rule || "Refresh, inspect, record intent, checkpoint, and hand off without blocking local operation."}`,
     `- conflict targets: ${conflictTargets.length ? conflictTargets.join(", ") : "none"}`,
     `- multi-actor targets: ${multiActorTargets.length ? multiActorTargets.join(", ") : "none"}`,
     "",
@@ -91,6 +97,7 @@ export function renderSummary(status = {}, manifest = {}) {
     "",
     `- source: ${manifest.lightSbom?.source?.dependencies || "project manifests"}`,
     `- confidence: transitive ${manifest.lightSbom?.confidence?.transitiveDependencies || "not-resolved"}`,
+    `- maintenance SBOM review: ${sbomReview.status || "unknown"} / ${sbomReview.securityConfidence || "unknown"} / ${sbomReview.nextCommand || maintenanceLoop.sbomCommand || "aienvmp sbom --json"}`,
     `- AI dependency review: ${aiDependencyReview.status || "unknown"} / ${aiDependencyReview.securityConfidence || "unknown"} / ${aiDependencyReview.beforeDependencyChange?.[0] || "aienvmp sbom --json"}`,
     `- signals: ${riskSignals.length ? riskSignals.join("; ") : "none"}`,
     `- verify: ${sbomRisk.next || "Use a dedicated scanner for security decisions."}`,

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", "collaboration", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
+    aiEntryFields: ["state", "summary", "aiReadiness", "collaboration", "maintenanceLoop", "nextAgent", "coordination", "agentActivity", "agentPointers", "sbomRisk", "followUps", "dependencyReadSet", "dependencyChangeProtocol"],
     rule: "Consumers should ignore unknown fields and treat missing optional fields as unavailable."
   };
 }
@@ -14,6 +14,20 @@ export function schemaContract() {
     schemaVersion: 1,
     name: "aienvmp-contract",
     purpose: "Stable AI-readable contract for aienvmp outputs.",
+    aiLoop: {
+      name: "AI maintenance loop",
+      purpose: "Shared lightweight workflow for AI agents that maintain one workspace environment.",
+      localMode: "warn-only",
+      steps: [
+        { step: "sync", command: "aienvmp sync", purpose: "refresh AIENV.md, status, summary, SBOM, ledger, and dashboard" },
+        { step: "status", command: "aienvmp status", purpose: "read the 5-line clear/review decision" },
+        { step: "context", command: "aienvmp context --json", purpose: "read the full AI preflight contract when details are needed" },
+        { step: "intent", command: "aienvmp intent --actor agent:id --action planned-change --target dependency", purpose: "record planned environment-affecting changes before touching shared state" },
+        { step: "checkpoint", command: "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency", purpose: "record accepted changes, refresh outputs, and write handoff context" },
+        { step: "handoff", command: "aienvmp handoff", purpose: "tell the next AI what to read, avoid, and review" }
+      ],
+      strictRule: "Local checks are warn-only; use doctor --strict only for CI or explicit human-requested gates."
+    },
     outputs: {
       status: {
         file: ".aienvmp/status.json",
@@ -29,11 +43,11 @@ export function schemaContract() {
       },
       context: {
         command: "aienvmp context --json",
-        rootFields: ["status", "preflight", "aiReadiness", "collaboration", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
+        rootFields: ["status", "preflight", "aiReadiness", "collaboration", "maintenanceLoop", "coordination", "agentPointers", "decision", "enforcement", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]
       },
       handoff: {
         command: "aienvmp handoff --json",
-        rootFields: ["status", "decision", "preflight", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
+        rootFields: ["status", "decision", "preflight", "continuation", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
       },
       manifest: {
         file: ".aienvmp/manifest.json",
@@ -57,6 +71,8 @@ export function schemaContract() {
       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.",
+      maintenanceLoopRule: "Use maintenanceLoop as the short recurring AI workflow: refresh, decide, inspect, plan, intent, checkpoint, and handoff without blocking local operation.",
+      strictDecisionRule: "Use enforcement.strictDecision or preflight.enforcementProfile.strictDecision for the shortest local warn-only vs CI strict decision.",
       strictPlanRule: "Use enforcement.strictPlan or preflight.enforcementProfile.strictPlan to choose the narrowest explicit strict scope for CI."
     }
   };

package/src/enforcement.js

@@ -34,6 +34,7 @@ export function enforcementAdvice(warnings = []) {
     suggestedStrictScopes,
     scopes: scopeResults,
     strictPlan: strictScopePlan(suggestedStrictScopes, scopeResults),
+    strictDecision: strictDecision(suggestedStrictScopes, scopeResults),
     recommendedCommand: suggestedStrictScopes.length
       ? `aienvmp doctor --strict ${suggestedStrictScopes[0]}`
       : "aienvmp doctor --strict all",
@@ -41,6 +42,29 @@ export function enforcementAdvice(warnings = []) {
   };
 }
 
+export function strictDecision(suggestedStrictScopes = [], scopeResults = []) {
+  const recommendedScope = suggestedStrictScopes[0] || "all";
+  const failingScopes = suggestedStrictScopes.slice();
+  const passingScopes = scopeResults
+    .filter((item) => item.scope !== "all" && item.status === "pass")
+    .map((item) => item.scope);
+  return {
+    local: "warn-only",
+    localCommand: "aienvmp doctor --json",
+    shouldFailLocal: false,
+    ci: failingScopes.length ? "fail-on-recommended-scope" : "optional-health-check",
+    recommendedScope,
+    recommendedCommand: `aienvmp doctor --strict ${recommendedScope}`,
+    ciCommand: `aienvmp doctor --strict ${recommendedScope} --json`,
+    failingScopes,
+    passingScopes,
+    rule: failingScopes.length
+      ? "Keep local operation advisory; use the first failing scope only when CI or the user wants a gate."
+      : "Keep local operation advisory; use --strict all only for explicit CI health checks.",
+    whenToUseStrict: "CI, release checks, or explicit human-requested verification."
+  };
+}
+
 export function strictScopePlan(suggestedStrictScopes = [], scopeResults = []) {
   const firstScope = suggestedStrictScopes[0] || "all";
   return {

package/src/preflight.js

@@ -20,6 +20,16 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
   const agentPointers = agentPointerSummary(manifest.agentFiles);
   const aiReadiness = aiReadinessSummary({ state, decision, coordination, agentActivity, agentPointers, sbomRisk, followUps });
   const collaboration = collaborationSummary({ state, decision, coordination, agentActivity, followUps, aiReadiness });
+  const maintenanceLoop = maintenanceLoopSummary({
+    state,
+    decision,
+    topAction,
+    followUps,
+    sbomRisk,
+    aiDependencyReview: manifest.lightSbom?.aiDependencyReview,
+    dependencyReadSet,
+    collaboration
+  });
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -38,6 +48,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
       reason: "Avoid disrupting shared servers or developer machines while still making drift visible.",
       recommendedStrictCommand: enforcement.recommendedCommand,
       strictPlan: enforcement.strictPlan,
+      strictDecision: enforcement.strictDecision,
       strictCommands: [
         "aienvmp doctor --strict security",
         "aienvmp doctor --strict policy",
@@ -63,6 +74,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     coordination,
     agentActivity,
     collaboration,
+    maintenanceLoop,
     agentPointers,
     aiReadiness,
     sbomRisk,
@@ -90,7 +102,81 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
       recordIntent: intentTargets[0]?.command || "aienvmp intent --actor agent:id --action planned-change"
     },
     topAction,
-    nextCommand: topAction?.command || decision.nextCommand
+    nextCommand: maintenanceLoop.nextCommand || topAction?.command || decision.nextCommand
+  };
+}
+
+function maintenanceLoopSummary({ state, decision, topAction, followUps, sbomRisk, aiDependencyReview = {}, dependencyReadSet, collaboration }) {
+  const followUpCommand = firstFollowUpCommand(followUps);
+  const dependencyAware = dependencyReadSet.length > 0;
+  const securityReview = ["urgent", "high", "medium"].includes(sbomRisk?.level || "");
+  const scannerOff = sbomRisk?.scanner === "off" || aiDependencyReview.securityConfidence === "scanner-off";
+  const nextCommand = followUpCommand
+    || collaboration?.nextCommand
+    || topAction?.command
+    || decision?.nextCommand
+    || "aienvmp status --json";
+  const triggers = [
+    "start of an AI coding session",
+    "before runtime, dependency, package manager, Docker, or global tool changes",
+    "after accepted environment changes",
+    "before handing work to another AI or human"
+  ];
+  if (securityReview) triggers.push("before dependency or release decisions when SBOM risk is not clear");
+  return {
+    mode: "advisory",
+    localImpact: "read-only until an AI or human intentionally records intent, checkpoint, or handoff",
+    state,
+    nextCommand,
+    triggers,
+    readOrder: [
+      ".aienvmp/status.json",
+      ".aienvmp/summary.md",
+      "aienvmp context --json",
+      "AIENV.md"
+    ],
+    cycle: [
+      { step: "refresh", command: "aienvmp sync", when: "workspace env map may be stale" },
+      { step: "decide", command: "aienvmp status --json", when: "first AI read or quick gate" },
+      { step: "inspect", command: "aienvmp context --json", when: "status is review-required or details are needed" },
+      { step: "plan", command: "aienvmp plan --write", when: "warnings, SBOM risk, or multi-agent activity need a read-only plan" },
+      { step: "intent", command: dependencyAware ? "aienvmp intent --actor agent:id --action planned-change --target dependency" : "aienvmp intent --actor agent:id --action planned-change --target environment", when: "before environment-affecting changes" },
+      { step: "checkpoint", command: dependencyAware ? "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency" : "aienvmp checkpoint --actor agent:id --summary what-changed --target environment", when: "after accepted environment-affecting changes" },
+      { step: "handoff", command: "aienvmp handoff --record --actor agent:id", when: "before another AI continues environment work" }
+    ],
+    sbomCommand: securityReview || scannerOff ? "aienvmp sync --security" : "aienvmp sbom --json",
+    sbomReview: sbomReviewSummary({ sbomRisk, aiDependencyReview, securityReview, scannerOff }),
+    rule: "Keep local operation advisory and lightweight; use strict checks only when CI or the user explicitly asks."
+  };
+}
+
+function sbomReviewSummary({ sbomRisk = {}, aiDependencyReview = {}, securityReview = false, scannerOff = false }) {
+  const status = securityReview || aiDependencyReview.status === "review" ? "review" : "ready";
+  const before = aiDependencyReview.beforeDependencyChange?.length
+    ? aiDependencyReview.beforeDependencyChange
+    : [
+        scannerOff ? "aienvmp sync --security" : "aienvmp sbom --json",
+        "aienvmp intent --actor agent:id --action dependency-review --target dependency",
+        "aienvmp plan --write"
+      ];
+  const after = aiDependencyReview.afterDependencyChange?.length
+    ? aiDependencyReview.afterDependencyChange
+    : [
+        "run the narrowest relevant project validation",
+        "aienvmp checkpoint --actor agent:id --summary dependency-change --target dependency"
+      ];
+  return {
+    status,
+    riskLevel: sbomRisk.level || "unknown",
+    score: Number(sbomRisk.score || 0),
+    securityConfidence: aiDependencyReview.securityConfidence || (scannerOff ? "scanner-off" : "unknown"),
+    reviewTargets: aiDependencyReview.reviewTargets || sbomRisk.reviewTargets || [],
+    nextCommand: before[0] || "aienvmp sbom --json",
+    beforeDependencyChange: before,
+    afterDependencyChange: after,
+    rule: status === "review"
+      ? "Review SBOM risk, package manager policy, and dependency read set before dependency changes."
+      : "Keep SBOM review lightweight; run security scan before dependency or release decisions when scanner confidence is low."
   };
 }
 

package/src/render.js

@@ -71,6 +71,7 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
 function preflightLines(preflight = {}) {
   const quickstart = preflight.quickstart;
   const targets = preflight.intentTargets || [];
+  const maintenanceLoop = preflight.maintenanceLoop || {};
   const lines = ["## 10-Second AI Flow", ""];
   if (quickstart) {
     lines.push(`- Read first: \`${quickstart.readFirst}\``);
@@ -82,6 +83,9 @@ function preflightLines(preflight = {}) {
   } else {
     lines.push("- Run `aienvmp status --write`, then `aienvmp context --json` before environment changes.");
   }
+  if (maintenanceLoop.nextCommand) {
+    lines.push(`- Maintenance loop: \`${maintenanceLoop.nextCommand}\` - ${maintenanceLoop.rule || "refresh, inspect, record intent, checkpoint, and hand off"}`);
+  }
   lines.push("", "## Recommended Intent Targets", "");
   if (targets.length) {
     for (const target of targets.slice(0, 5)) {
@@ -212,6 +216,9 @@ export function renderHandoff(handoff) {
     `- Inventory: ${handoff.inventory?.mode || "basic"}${handoff.inventory?.enabled ? " enabled" : " disabled"}`,
     `- Security: ${handoff.security?.mode || "basic"}${handoff.security?.enabled ? ` enabled (${handoff.security.summary?.total || 0} vulnerabilities)` : " disabled"}`,
     "",
+    "AI continuation:",
+    ...continuationHandoffLines(handoff.continuation),
+    "",
     "Open intents:",
     ...(handoff.openIntents.length ? handoff.openIntents.map((i) => `- ${i.actor}: ${i.action}${i.target ? ` (${i.target})` : ""}`) : ["- none"]),
     "",
@@ -242,6 +249,20 @@ export function renderHandoff(handoff) {
   return lines.join("\n");
 }
 
+function continuationHandoffLines(continuation = {}) {
+  const strict = continuation.strict || {};
+  const sbomReview = continuation.sbomReview || {};
+  const maintenance = continuation.maintenance || {};
+  return [
+    `- Next: ${continuation.nextCommand || "aienvmp status --json"}`,
+    `- Read: ${(continuation.readOrder || []).join(", ") || ".aienvmp/status.json"}`,
+    `- Local check: ${strict.localCommand || "aienvmp doctor --json"} (${strict.local || "warn-only"})`,
+    `- CI strict: ${strict.ciCommand || "aienvmp doctor --strict all --json"}`,
+    `- SBOM review: ${sbomReview.status || "unknown"} / ${sbomReview.riskLevel || "unknown"} / ${sbomReview.nextCommand || maintenance.sbomCommand || "aienvmp sbom --json"}`,
+    `- Rule: ${maintenance.rule || strict.rule || "Keep local operation advisory and lightweight."}`
+  ];
+}
+
 function coordinationHandoffLines(coordination = {}) {
   const conflicts = coordination.conflictTargets || [];
   if (conflicts.length) return [`- Conflicts: ${conflicts.join(", ")}`, `- Next: ${coordination.next || "review open intents"}`];
@@ -392,6 +413,10 @@ h1,h2,h3,p{margin:0}h1{font-size:clamp(28px,4vw,46px);line-height:1.02;margin-to
 .nextbar b{color:var(--green);font-size:12px;text-transform:uppercase;letter-spacing:.08em}
 .nextbar code{display:inline-block;max-width:100%;white-space:normal;overflow-wrap:anywhere}
 .nextbar span{color:var(--muted);font-size:12px;overflow-wrap:anywhere}
+.brief{display:grid;grid-template-columns:1fr 1fr 1fr 1fr;gap:8px;margin:0 0 14px}
+.brief-item{border:1px solid var(--line2);background:rgba(9,19,16,.9);border-radius:8px;padding:10px;min-width:0}
+.brief-k{color:var(--muted);font-size:11px;font-weight:800;text-transform:uppercase;letter-spacing:.08em}
+.brief-v{margin-top:5px;font-size:13px;font-weight:700;color:var(--text);overflow-wrap:anywhere}
 .audit{display:grid;grid-template-columns:1.2fr repeat(3,minmax(0,.8fr));gap:12px;margin:14px 0}
 .audit-item{border:1px solid var(--line);background:rgba(13,24,21,.92);border-radius:8px;padding:14px;min-width:0}
 .audit-item.primary{background:linear-gradient(135deg,rgba(19,61,42,.88),rgba(9,19,16,.95))}
@@ -417,8 +442,10 @@ code{color:var(--code);background:#0a2017;border:1px solid #17462f;padding:2px 6
 @media (max-width:860px){header,.layout{grid-template-columns:1fr}.metrics{grid-template-columns:repeat(2,1fr)}.grid{grid-template-columns:1fr}.agents{grid-template-columns:1fr}}
 @media (max-width:860px){.control{grid-template-columns:1fr}}
 @media (max-width:860px){.nextbar{grid-template-columns:1fr}}
+@media (max-width:860px){.brief{grid-template-columns:1fr 1fr}}
 @media (max-width:860px){.audit{grid-template-columns:1fr 1fr}}
 @media (max-width:520px){.shell{padding:14px}.metrics{grid-template-columns:1fr}.event{grid-template-columns:1fr}h1{font-size:32px}}
+@media (max-width:520px){.brief{grid-template-columns:1fr}}
 @media (max-width:520px){.audit{grid-template-columns:1fr}}
 </style>
 </head>
@@ -488,7 +515,8 @@ const enforcementProfile=manifest.preflight?.enforcementProfile||{};
 const strictCommands=enforcementProfile.strictCommands||[];
 const gate=enforcementProfile.gate||{};
 const strictPlan=enforcementProfile.strictPlan||{};
-const enforcementHtml=\`<table><tr><th>Default</th><td><code>\${esc(gate.defaultMode||enforcementProfile.defaultMode||'advisory')}</code> \${esc(gate.localDefault||'warn-only')}</td></tr><tr><th>Strict</th><td><code>\${esc(gate.strictMode||'off')}</code></td></tr><tr><th>Fail</th><td>\${esc(gate.failCondition||'never in default mode')}</td></tr><tr><th>Exit</th><td>\${esc(gate.exitCode||'0 unless the command itself errors')}</td></tr><tr><th>Recommended</th><td><code>\${esc(strictPlan.recommendedStrictCommand||enforcementProfile.recommendedStrictCommand||'aienvmp doctor --strict all')}</code></td></tr><tr><th>CI</th><td><code>\${esc(strictPlan.ciCommand||'aienvmp doctor --strict all --json')}</code></td></tr></table><div class="timeline">\${strictCommands.slice(0,4).map(cmd=>\`<div class="event"><time>CI</time><div><code>\${esc(cmd)}</code></div></div>\`).join('')}</div><div class="path">\${esc(strictPlan.rule||gate.rule||enforcementProfile.reason||'Warnings stay advisory unless strict mode is requested.')}</div>\`;
+const strictDecision=enforcementProfile.strictDecision||{};
+const enforcementHtml=\`<table><tr><th>Default</th><td><code>\${esc(gate.defaultMode||enforcementProfile.defaultMode||'advisory')}</code> \${esc(gate.localDefault||'warn-only')}</td></tr><tr><th>Local</th><td><code>\${esc(strictDecision.localCommand||'aienvmp doctor --json')}</code> \${esc(strictDecision.local||'warn-only')}</td></tr><tr><th>Strict</th><td><code>\${esc(gate.strictMode||'off')}</code></td></tr><tr><th>Fail</th><td>\${esc(gate.failCondition||'never in default mode')}</td></tr><tr><th>Exit</th><td>\${esc(gate.exitCode||'0 unless the command itself errors')}</td></tr><tr><th>Recommended</th><td><code>\${esc(strictDecision.recommendedCommand||strictPlan.recommendedStrictCommand||enforcementProfile.recommendedStrictCommand||'aienvmp doctor --strict all')}</code></td></tr><tr><th>CI</th><td><code>\${esc(strictDecision.ciCommand||strictPlan.ciCommand||'aienvmp doctor --strict all --json')}</code></td></tr></table><div class="timeline">\${strictCommands.slice(0,4).map(cmd=>\`<div class="event"><time>CI</time><div><code>\${esc(cmd)}</code></div></div>\`).join('')}</div><div class="path">\${esc(strictDecision.rule||strictPlan.rule||gate.rule||enforcementProfile.reason||'Warnings stay advisory unless strict mode is requested.')}</div>\`;
 const contract=manifest.preflight?.contract||{};
 const contractHtml=contract.name?\`<table><tr><th>Name</th><td><code>\${esc(contract.name)}</code></td></tr><tr><th>Version</th><td><code>\${esc(contract.version||1)}</code></td></tr><tr><th>Stability</th><td><code>\${esc(contract.stability||'additive')}</code></td></tr><tr><th>AI fields</th><td>\${esc((contract.aiEntryFields||[]).join(', ')||'none')}</td></tr></table><div class="path">\${esc(contract.rule||'Ignore unknown fields.')}</div>\`:'<div class="okline">Run <code>aienvmp status --write</code> to include AI contract metadata.</div>';
 const intentTargets=manifest.preflight?.intentTargets||[];
@@ -530,6 +558,10 @@ 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):[]);
 const handoffNext=nextAgent.rule||(reviewRequired?'Review warnings and open intents':'Continue project-local work');
+const firstRead=nextAgent.readFirst||'.aienvmp/status.json';
+const reviewTargets=[...new Set([...(conflictTargets||[]),...(collaboration.activeTargets||[]),...(riskSummary.reviewTargets||[])].filter(Boolean))];
+const safeMode=enforcementProfile.gate?.localDefault||enforcementProfile.localOperation||'warn-only';
+const briefItem=(key,value)=>\`<div class="brief-item"><div class="brief-k">\${key}</div><div class="brief-v">\${esc(value)}</div></div>\`;
 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>Read first</th><td><code>\${esc(nextAgent.readFirst||'.aienvmp/status.json')}</code></td></tr><tr><th>Dependency files</th><td>\${handoffFiles.length?'<code>'+esc(handoffFiles.join(', '))+'</code>':'none'}</td></tr><tr><th>Conflicts</th><td>\${conflictTargets.length?'<code>'+esc(conflictTargets.join(', '))+'</code>':'none'}</td></tr><tr><th>Next</th><td>\${esc(handoffNext)}</td></tr></table>\`;
 document.getElementById('app').innerHTML=\`
 <header>
@@ -550,6 +582,12 @@ document.getElementById('app').innerHTML=\`
   <code>\${esc(nextCommand)}</code>
   <span>\${esc(nextReason)}</span>
 </section>
+<section class="brief" aria-label="First read">
+  \${briefItem('Status',reviewRequired?'review required':'clear')}
+  \${briefItem('Read first',firstRead)}
+  \${briefItem('Review targets',reviewTargets.length?reviewTargets.slice(0,4).join(', '):'none')}
+  \${briefItem('Local mode',safeMode)}
+</section>
 <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',aiReadinessHint,aiReadiness.level==='ready'?'primary':'review')}