aienvmp 0.1.66 → 0.1.68

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.68
+
+- Added an `aienvmp AI loop` block to the GitHub Action Step Summary using `schema.aiLoop`.
+- Kept the Action summary advisory by default while showing the same loop documented in README and `schema --json`.
+- Updated the GitHub Action example and README CI notes to mention Step Summary strict-plan and AI-loop blocks.
+- Added `doctor --json` `nextSafeCommand` so AI agents can pick one advisory next command without parsing every warning.
+- Aligned the dashboard next-command fallback with `maintenanceLoop.nextCommand` so the visual surface follows the same advisory next-step chain.
+- Added `context --json` `nextSafeCommand` so AI agents get the same one-step advisory next command in the preflight payload.
+- Added `handoff --json` `nextSafeCommand` so the next AI can resume from one root-level advisory command.
+- Added `status --json` and `.aienvmp/status.json` `nextSafeCommand` as a stable alias for the preflight next command.
+
+## 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.

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,13 @@ 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.
+- `status --json`, `context --json`, `handoff --json`, and `doctor --json` include `nextSafeCommand` for one advisory next step.
+- `schema --json` prints the stable machine-readable contract without scanning.
 
 ## Agent Files
 
@@ -103,7 +119,7 @@ aienvmp doctor --strict security|policy|coordination|all
 ## CI
 
 The GitHub Action writes status, summary, schema, doctor, plan, SBOM, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
-The Step Summary includes an `aienvmp strict plan` block so humans and AI agents can pick the narrowest CI strict scope without parsing the full artifacts.
+The Step Summary includes `aienvmp strict plan` and `aienvmp AI loop` blocks so humans and AI agents can choose CI gates and continue the same workflow without parsing full artifacts.
 
 ```yaml
 - uses: soovwv/aienvmp@main

package/action.yml

@@ -123,6 +123,36 @@ runs:
         NODE
         fi
 
+    - name: Append AI loop summary
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-summary }}" = "true" ] && [ -n "$GITHUB_STEP_SUMMARY" ]; then
+          mkdir -p "${{ inputs.directory }}/.aienvmp"
+          schema_source="${{ inputs.directory }}/.aienvmp/schema.json"
+          if [ ! -f "$schema_source" ]; then
+            schema_source="$(mktemp)"
+            node "$GITHUB_ACTION_PATH/bin/aienvmp.js" schema --json > "$schema_source"
+          fi
+          node - "$schema_source" "$GITHUB_STEP_SUMMARY" <<'NODE'
+        const fs = require("node:fs");
+
+        const [schemaPath, summaryPath] = process.argv.slice(2);
+        const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+        const loop = schema.aiLoop || {};
+        const steps = (loop.steps || []).slice(0, 6).map((item) => item.command).join(" -> ");
+
+        fs.appendFileSync(summaryPath, [
+          "",
+          "## aienvmp AI loop",
+          "",
+          `- mode: ${loop.localMode || "warn-only"}`,
+          `- steps: \`${steps || "aienvmp sync -> aienvmp status -> aienvmp handoff"}\``,
+          `- rule: ${loop.strictRule || "Local checks are warn-only; strict gates are explicit."}`,
+          ""
+        ].join("\n"));
+        NODE
+        fi
+
     - name: Doctor
       shell: bash
       run: |

package/examples/github-action.yml

@@ -17,7 +17,7 @@ jobs:
           write-schema: "true"
           write-doctor-json: "true"
           write-sbom: "true"
-          write-summary: "true"
+          write-summary: "true" # appends summary, strict plan, and AI loop to GitHub Step Summary
           strict: "off" # security, policy, coordination, all, or off
 
       - uses: actions/upload-artifact@v4

package/package.json

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

package/src/actions.js

@@ -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/commands/context.js

@@ -22,12 +22,15 @@ export async function contextWorkspace(args) {
   const actions = recommendedActions(manifest, { warnings, intents });
   const stepSummary = compactStepSummary(buildPlan(manifest, warnings, intents, policy));
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
+  const nextSafeCommand = contextNextSafeCommand(actions, warnings, preflight);
   if (args.json) {
     console.log(JSON.stringify({
       status: warnings.length ? "review-required" : "clear",
+      nextSafeCommand,
       preflight,
       aiReadiness: preflight.aiReadiness,
       collaboration: preflight.collaboration,
+      maintenanceLoop: preflight.maintenanceLoop,
       coordination: preflight.coordination,
       agentPointers: preflight.agentPointers,
       sbomRisk: preflight.sbomRisk,
@@ -58,6 +61,14 @@ export async function contextWorkspace(args) {
   console.log(renderContext({ ...manifest, preflight }, timeline, warnings, intents, policy, actions));
 }
 
+function contextNextSafeCommand(actions = [], warnings = [], preflight = {}) {
+  const actionCommand = actions.find((item) => item.command)?.command;
+  return preflight.nextCommand
+    || preflight.maintenanceLoop?.nextCommand
+    || actionCommand
+    || (warnings.length ? "aienvmp plan --write" : "aienvmp status --json");
+}
+
 function lightSbomSummary(lightSbom = {}) {
   return {
     mode: lightSbom.mode || "light-sbom",

package/src/commands/doctor.js

@@ -20,6 +20,7 @@ export async function doctorWorkspace(args) {
   const actions = recommendedActions(manifest, { warnings, intents });
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
   const strict = strictResult(warnings, args);
+  const nextSafeCommand = doctorNextSafeCommand(actions, warnings);
   const exitBehavior = {
     mode: strict.enabled ? "strict" : "advisory",
     willSetFailureExitCode: strict.fail,
@@ -37,6 +38,7 @@ export async function doctorWorkspace(args) {
       aiReadiness: preflight.aiReadiness,
       agentPointers: preflight.agentPointers,
       openIntentCount: intents.length,
+      nextSafeCommand,
       warnings,
       recommendedActions: actions,
       enforcement: enforcementAdvice(warnings),
@@ -63,3 +65,10 @@ export async function doctorWorkspace(args) {
     process.exitCode = 1;
   }
 }
+
+function doctorNextSafeCommand(actions = [], warnings = []) {
+  const command = actions.find((item) => item.command)?.command;
+  if (command) return command;
+  if (warnings.length) return "aienvmp plan --write";
+  return "aienvmp status --json";
+}

package/src/commands/handoff.js

@@ -49,6 +49,7 @@ export function buildHandoff(manifest, timeline = [], warnings = [], intents = [
   const preflight = buildPreflight(manifest, warnings, intents, timeline);
   return {
     status: reviewRequired ? "review-required" : "clear",
+    nextSafeCommand: preflight.nextCommand || preflight.maintenanceLoop?.nextCommand || "aienvmp status --json",
     trust: manifest.trust || {},
     schemaVersion: manifest.schemaVersion || 1,
     preflight,
@@ -62,6 +63,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 +88,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/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", "nextSafeCommand", "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,10 +14,25 @@ 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",
         command: "aienvmp status --json",
+        rootFields: ["state", "nextCommand", "nextSafeCommand", "decision", "counts", "aiReadiness", "collaboration", "maintenanceLoop", "coordination", "agentPointers", "sbomRisk"],
         contract: preflightContract()
       },
       summary: {
@@ -29,11 +44,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", "nextSafeCommand", "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", "nextSafeCommand", "decision", "preflight", "continuation", "coordination", "dependencyHandoff", "openIntents", "warnings", "recommendedActions", "recentChanges"]
       },
       manifest: {
         file: ".aienvmp/manifest.json",
@@ -57,6 +72,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,17 @@ 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
+  });
+  const nextCommand = maintenanceLoop.nextCommand || topAction?.command || decision.nextCommand;
   return {
     schemaVersion: 1,
     contract: preflightContract(),
@@ -38,6 +49,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 +75,7 @@ export function buildPreflight(manifest = {}, warnings = [], intents = [], timel
     coordination,
     agentActivity,
     collaboration,
+    maintenanceLoop,
     agentPointers,
     aiReadiness,
     sbomRisk,
@@ -90,7 +103,82 @@ 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,
+    nextSafeCommand: 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||[];
@@ -500,6 +528,7 @@ const activityTargets=agentActivity.targets||[];
 const activityHtml=activityTargets.length?'<div class="timeline">'+activityTargets.slice(0,5).map(a=>\`<div class="event"><time>\${esc(a.target||'env')}</time><div><b>\${esc((a.actors||[]).join(', ')||'unknown')}</b> \${esc(a.count||0)} record(s) \${a.multiActor?'<code>multi-agent</code>':'<code>single-agent</code>'}\${a.latestSummary?\`<div class="path">\${esc(a.latestSummary)}</div>\`:''}</div></div>\`).join('')+'</div><div class="path">'+esc(agentActivity.next||'Review activity before environment changes.')+'</div>':'<div class="okline">No recorded environment activity needs coordination.</div>';
 const collaboration=manifest.preflight?.collaboration||{};
 const collaborationHtml=\`<table><tr><th>Status</th><td><code>\${esc(collaboration.status||'unknown')}</code> \${esc(collaboration.mode||'advisory')}</td></tr><tr><th>Targets</th><td>\${esc((collaboration.activeTargets||[]).join(', ')||'none')}</td></tr><tr><th>Project work</th><td><code>\${esc(collaboration.projectLocalWork||'allowed')}</code></td></tr><tr><th>Env changes</th><td><code>\${esc(collaboration.environmentChanges||'intent-first')}</code></td></tr><tr><th>Next</th><td><code>\${esc(collaboration.nextCommand||'aienvmp status --json')}</code></td></tr></table><div class="timeline">\${(collaboration.reviewSignals||[]).slice(0,4).map(signal=>\`<div class="event"><time>review</time><div>\${esc(signal)}</div></div>\`).join('')}</div><div class="path">\${esc(collaboration.rule||'Record intent before shared environment changes.')}</div>\`;
+const maintenanceLoop=manifest.preflight?.maintenanceLoop||{};
 const dependencyReadSet=manifest.preflight?.dependencyReadSet||[];
 const dependencyReadSetHtml=dependencyReadSet.length?'<div class="timeline">'+dependencyReadSet.slice(0,5).map(d=>\`<div class="event"><time>\${esc(d.ecosystem||'deps')}</time><div><b>\${esc(d.manifest||'dependency files')}</b> <code>\${esc(d.manager||'unknown')}</code><div class="path">\${esc([d.manifest,...(d.lockfiles||[])].filter(Boolean).join(', '))}</div>\${d.riskPackages?.length?\`<div class="path">risk: \${esc(d.riskPackages.join(', '))}</div>\`:''}</div></div>\`).join('')+'</div>':'<div class="okline">No dependency files detected.</div>';
 const dependencyProtocol=manifest.preflight?.dependencyChangeProtocol||{};
@@ -524,12 +553,16 @@ const sbomRiskValue=riskSummary.level||'unknown';
 const sbomRiskClass=['urgent','high','medium'].includes(sbomRiskValue)?'review':'ready';
 const sbomRiskScore=riskSummary.score!==undefined?' ('+riskSummary.score+')':'';
 const sbomRiskNext=riskSummary.next||aiDependencyReview.beforeDependencyChange?.[0]||'Run aienvmp sbom --json for dependency context.';
-const nextCommand=manifest.preflight?.nextCommand||topAction.command||collaboration.nextCommand||'aienvmp status --json';
-const nextReason=topAction.summary||collaboration.rule||riskSummary.next||'Read status/context before changing shared environment state.';
+const nextCommand=manifest.preflight?.nextCommand||maintenanceLoop.nextCommand||topAction.command||collaboration.nextCommand||'aienvmp status --json';
+const nextReason=topAction.summary||maintenanceLoop.rule||collaboration.rule||riskSummary.next||'Read status/context before changing shared environment state.';
 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 +583,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')}