arkgate 4.6.0 → 4.6.2

package/bin/lib/html-report-advisories.mjs

@@ -311,12 +311,32 @@ function deepModuleCoachHtml(coach) {
   </section>`;
 }
 
+function stewardNudgeHtml(nudge) {
+  if (!nudge || nudge.notAScore !== true) return '';
+  const ask =
+    (nudge.needsStewards || nudge.drift) && typeof nudge.ask === 'string' && nudge.ask
+      ? `<p>${esc(nudge.ask)}</p>`
+      : '<p class="muted">No steward list gap (advisory).</p>';
+  const next =
+    typeof nudge.nextAction === 'string' && nudge.nextAction
+      ? `<p class="muted">Next: ${esc(nudge.nextAction)}</p>`
+      : '';
+  return `
+  <section class="section card" data-advisory="stewardNudge">
+    <h2>Stewards <span class="muted">(advisory — never changes the verdict)</span></h2>
+    ${ask}
+    ${next}
+    <p class="muted">GitHub handle or email. Never invent names. Always <code>notAScore</code>.</p>
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
     improvementCompassHtml(advisories.improvementCompass),
     deepModuleCoachHtml(advisories.deepModuleCoach),
+    stewardNudgeHtml(advisories.stewardNudge),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

package/bin/lib/improvement-compass-map.mjs

@@ -118,11 +118,11 @@ function mapDesignSmells(byId, smells) {
         const shapeAction = {
             kind: 'skill',
             ref: '/ark-explore',
-            summary: 'Map Shape residual (shape-focus), then one extraction pilot with user OK.',
+            summary: 'Map Shape residual (shape-focus), then apply one extraction pilot with /ark-autopilot.',
         };
         const dipAction = {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Inject a port/adapter for I/O; keep domain pure.',
         };
         switch (id) {
@@ -147,7 +147,7 @@ function mapDesignSmells(byId, smells) {
                 attach('srp', 'God modules own too many responsibilities — split by concern (one pilot).', {
                     kind: 'skill',
                     ref: '/ark-autopilot',
-                    summary: 'One Shape pilot with user OK — never multi-pilot batch.',
+                    summary: 'One Shape pilot this turn — never multi-pilot batch.',
                 });
                 break;
             case 'mixed-pattern-cluster':
@@ -161,12 +161,12 @@ function mapDesignSmells(byId, smells) {
             case 'soft-contract':
                 attach('maintainability', 'Soft contract walls (layers without deny rules) hide maintainability debt.', {
                     kind: 'skill',
-                    ref: '/ark-contract',
+                    ref: '/ark-adopt',
                     summary: 'Add real layer rules so the AI has hard walls.',
                 });
                 attach('coupling', 'Layers with files but almost no deny rules allow free peer coupling.', {
                     kind: 'skill',
-                    ref: '/ark-contract',
+                    ref: '/ark-adopt',
                     summary: 'Tighten inter-layer allows/denies without weakening enforcement.',
                 });
                 break;
@@ -213,7 +213,7 @@ function mapViolations(byId, violations) {
         }
         const edgeAction = {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Clear the active edge residual, then re-doctor.',
         };
         if (upper === 'LAYER_IMPORT_VIOLATION' ||
@@ -229,7 +229,7 @@ function mapViolations(byId, violations) {
         if (upper.includes('PEER_ISOLATION') || upper === 'PEER_ISOLATION_VIOLATION') {
             attach('coupling', 'Peer isolation residual — slices import each other freely.', {
                 kind: 'skill',
-                ref: '/ark-loop',
+                ref: '/ark-autopilot',
                 summary: 'Peer isolation fixes are judgment-class — one cluster at a time.',
             });
             continue;
@@ -237,12 +237,12 @@ function mapViolations(byId, violations) {
         if (upper === 'FORBIDDEN_GLOBAL' || upper.startsWith('FORBIDDEN_')) {
             attach('dip', 'Forbidden globals / effect surfaces break dependency inversion.', {
                 kind: 'skill',
-                ref: '/ark-fix',
+                ref: '/ark-autopilot',
                 summary: 'Inject a port instead of the forbidden global.',
             });
             attach('testability', 'Forbidden ambient effects reduce pure-domain testability.', {
                 kind: 'skill',
-                ref: '/ark-fix',
+                ref: '/ark-autopilot',
                 summary: 'Replace ambient effects with injectable ports.',
             });
             continue;
@@ -250,12 +250,12 @@ function mapViolations(byId, violations) {
         if (upper === 'CAPABILITY_VIOLATION') {
             attach('dip', 'Denied capability use — invert through an allowed adapter/port.', {
                 kind: 'skill',
-                ref: '/ark-fix',
+                ref: '/ark-autopilot',
                 summary: 'Capability walls require port injection (judgment, not mechanical-safe).',
             });
             attach('testability', 'Capability violations couple domain code to I/O — harder to unit-test.', {
                 kind: 'skill',
-                ref: '/ark-fix',
+                ref: '/ark-autopilot',
                 summary: 'Keep pure layers free of denied capabilities.',
             });
             continue;
@@ -263,7 +263,7 @@ function mapViolations(byId, violations) {
         if (upper.startsWith('ARKRULE_') || upper === 'INVARIANT_UNCOVERED') {
             attach('encapsulation', 'ArkRules structure / invariant residual inside a layer.', {
                 kind: 'skill',
-                ref: '/ark-fix',
+                ref: '/ark-autopilot',
                 summary: 'Label [ArkRules]; structure fixes are judgment — never invent mechanical-safe.',
             });
             attach('domain', 'Intra-layer domain structure or invariant coverage residual.', {
@@ -282,7 +282,7 @@ function mapCountsAndFlags(byId, facts) {
         pushEvidence(lens, 'cycles', `count:${cycleCount}`);
         markResidual(lens, 'Import cycles couple modules tightly.', {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Break cycles with a judgment extraction — one pilot.',
         });
     }
@@ -296,7 +296,7 @@ function mapCountsAndFlags(byId, facts) {
         pushEvidence(lens, 'peerIsolation', `count:${peer}`);
         markResidual(lens, 'Peer isolation residual remains.', {
             kind: 'skill',
-            ref: '/ark-loop',
+            ref: '/ark-autopilot',
             summary: 'Peer isolation is judgment-class residual.',
         });
     }
@@ -314,7 +314,7 @@ function mapCountsAndFlags(byId, facts) {
         markResidual(srp, 'Mirrored clusters suggest split-by-concern residual (architecture SRP).', {
             kind: 'skill',
             ref: '/ark-autopilot',
-            summary: 'One reshape/extraction pilot with user OK.',
+            summary: 'One reshape/extraction pilot this turn.',
         });
     }
     const pureN = Number(facts.pureOrCapabilityResidual) || 0;
@@ -327,7 +327,7 @@ function mapCountsAndFlags(byId, facts) {
             pushEvidence(dip, 'forbiddenGlobals', `residual:${fgN}`);
         markResidual(dip, 'Pure / capability / forbidden residual weakens dependency inversion.', {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Inject ports; keep pure layers free of effects.',
         });
         const test = byId.get('testability');
@@ -337,7 +337,7 @@ function mapCountsAndFlags(byId, facts) {
             pushEvidence(test, 'forbiddenGlobals', `residual:${fgN}`);
         markResidual(test, 'Impure domain or capability residual reduces testability.', {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Prefer ports over concrete I/O in pure/domain modules.',
         });
     }
@@ -347,7 +347,7 @@ function mapCountsAndFlags(byId, facts) {
         pushEvidence(enc, 'arkRules', `structureResidual:${arkN}`);
         markResidual(enc, 'ArkRules structure residual — encapsulation inside the layer.', {
             kind: 'skill',
-            ref: '/ark-fix',
+            ref: '/ark-autopilot',
             summary: 'Fix structure sensors under [ArkRules] without inventing mechanical-safe.',
         });
         const domain = byId.get('domain');
@@ -368,7 +368,7 @@ function mapCountsAndFlags(byId, facts) {
         markResidual(m, 'Design-weak: checked edges may be clean, but design residual remains — not finished.', {
             kind: 'skill',
             ref: '/ark-explore',
-            summary: 'Shape door: explore shape-focus → dual-plan B → one pilot with OK.',
+            summary: 'Shape door: explore shape-focus → dual-plan B → one /ark-autopilot pilot.',
         });
     }
     if (facts.dirtyBaselineRisk === true || (Number(facts.baselineStale) || 0) > 0) {
@@ -409,7 +409,7 @@ function mapCountsAndFlags(byId, facts) {
             pushEvidence(mod, 'coverage', `emptyLayers:${emptyL}`);
         markResidual(mod, 'Placement / modularity residual — ungoverned dirs or empty layer globs.', {
             kind: 'skill',
-            ref: '/ark-contract',
+            ref: '/ark-adopt',
             summary: 'Classify ungoverned paths; fix empty layer patterns.',
         });
     }

package/bin/lib/pilot-loop.mjs

@@ -115,7 +115,7 @@ export function extractionCardFromBet(bet, preferredFiles) {
     reDoctor: 'ark-check --doctor --json',
     rePlan: 'ark-check --plan --json',
     next:
-      '/ark-fix (one cluster) | /ark-autopilot (user ok on B) | re-doctor after pilot',
+      '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
   };
 }
 

package/bin/lib/post-green-path.mjs

@@ -16,13 +16,13 @@ export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
 
 /**
  * Canonical human / agent next-action string (single door).
- * Chained: explore shape-focus then autopilot only to apply B with user OK.
+ * Chained: explore shape-focus then autopilot applies one B pilot.
  */
 export const POST_GREEN_PRIMARY_ACTION = POST_GREEN_HUMAN;
 
 /** Short label for tables / metrics. */
 export const POST_GREEN_PRIMARY_SHORT =
-  '/ark-explore shape-focus → /ark-autopilot (apply B with OK)  # Shape residual';
+  '/ark-explore shape-focus → /ark-autopilot (apply one B pilot)  # Shape residual';
 
 /** Placement coaching while design residual remains (new code only). */
 export const POST_GREEN_PLACEMENT_COACHING =

package/bin/lib/prepare-change.mjs

@@ -13,6 +13,7 @@ import {
 } from './resolved-candidate-facts.mjs';
 import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { classifyChangeSet, evaluateTeamGate } from './team-parliament.mjs';
 
 function candidatePath(value) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -102,6 +103,14 @@ export function prepareChangeFromRoot({
   const normalizedChanges = normalizeChangeSet(changes);
   const normalizedOverlayChanges =
     overlayChanges === undefined ? normalizedChanges : normalizeChangeSet(overlayChanges);
+  const lawGate = evaluateTeamGate({
+    changeSet: classifyChangeSet(normalizedChanges.map((change) => change.path)),
+    contractSession:
+      process.env.ARK_CONTRACT_SESSION === '1' || process.env.ARK_CONTRACT_SESSION === 'true',
+  });
+  if (lawGate.deny && lawGate.reasonId === 'mixed-law-and-product') {
+    throw new Error(lawGate.message);
+  }
   const effectiveConfig = effectiveAnalysisConfig(config, manifest);
   for (const change of normalizedChanges) {
     assertInsideProject(root, change.path);

package/bin/lib/product-copy.mjs

@@ -23,7 +23,7 @@ export function operatingModeTitle(mode, leftoverDesign) {
 export const LEFTOVER_DESIGN_BADGE = LEFTOVER_DESIGN_LABEL;
 
 export const POST_GREEN_HUMAN =
-  'Imports check out, but the design is still messy. Map leftover work with /ark-explore shape-focus, then apply one small refactor via /ark-autopilot with your OK. A clean import check is not done; pattern bets are never auto-applied.';
+  'Imports check out, but the design is still messy. Map leftover work with /ark-explore shape-focus, then apply one small refactor via /ark-autopilot. A clean import check is not done; pattern bets are never auto-applied.';
 
 export const POST_GREEN_LEDE =
   'Import rules are clean, but leftover design work remains. That does not fail the check — it only means “done” is still wrong until you tidy shape.';

package/bin/lib/start-preview.mjs

@@ -147,21 +147,16 @@ export function renderStartPreview(preview, options = {}) {
   } else {
     console.log('Ark start preview — no files were changed.');
   }
+  if (!applying) {
+    console.log('Apply this plan with: arkgate start --apply');
+  }
   if (preview.analysis) {
     console.log(`Your project looks like: ${preview.analysis.label} (${preview.analysis.archetype}, confidence ${preview.analysis.confidence}).`);
   }
-  console.log(`Projected governed coverage: ${preview.projectedCoverage.percent ?? 'unknown'}% (${preview.projectedCoverage.classifiedFiles}/${preview.projectedCoverage.totalFiles} files)`);
-  const budget = preview.setupBudget;
-  const arkrulesNote =
-    budget.arkrulesFiles > 0 ? ` (+${budget.arkrulesFiles} arkrules)` : '';
-  const gateCount = budget.gateFiles ?? budget.files;
-  console.log(
-    `Compact setup budget: ${gateCount}/${budget.maxFiles} gate files${arkrulesNote}, ${budget.bytes}/${budget.maxBytes} bytes${budget.ok ? '' : ' (exceeded)'}.`
-  );
   console.log(applying ? 'Files create/edit/delete:' : 'Files to create/edit/delete:');
   if (preview.changes.length === 0) console.log('  (none)');
   for (const change of preview.changes) {
-    console.log(`  ${change.action.padEnd(6)} ${change.path}  ${change.afterHash ?? '(deleted)'}`);
+    console.log(`  ${change.action.padEnd(6)} ${change.path}`);
   }
   if (!applying) {
     console.log('Commands in the approved setup plan:');
@@ -179,8 +174,20 @@ export function renderStartPreview(preview, options = {}) {
     console.log('Unresolved decisions:');
     for (const decision of preview.unresolvedDecisions) console.log(`  ${decision}`);
   }
+  console.log('Details (optional):');
+  console.log(`Projected governed coverage: ${preview.projectedCoverage.percent ?? 'unknown'}% (${preview.projectedCoverage.classifiedFiles}/${preview.projectedCoverage.totalFiles} files)`);
+  const budget = preview.setupBudget;
+  const arkrulesNote =
+    budget.arkrulesFiles > 0 ? ` (+${budget.arkrulesFiles} arkrules)` : '';
+  const gateCount = budget.gateFiles ?? budget.files;
+  console.log(
+    `Compact setup budget: ${gateCount}/${budget.maxFiles} gate files${arkrulesNote}, ${budget.bytes}/${budget.maxBytes} bytes${budget.ok ? '' : ' (exceeded)'}.`
+  );
+  for (const change of preview.changes) {
+    console.log(`  ${change.action.padEnd(6)} ${change.path}  ${change.afterHash ?? '(deleted)'}`);
+  }
   if (!applying) {
-    console.log('Review complete file contents with --json. Apply this plan with: ark start --apply');
+    console.log('Review complete file contents with --json.');
   }
 }
 

package/bin/lib/status-command.mjs

@@ -25,6 +25,7 @@ import { detectActiveAgentHost } from './skill-install.mjs';
 import { readBaseline } from './violations.mjs';
 import { reportsDir, readJsonSafe } from './html-report.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { collectVsBaseFacts, discoverTeamBaseRef } from './team-parliament-io.mjs';
 
 function sha256Hex(value) {
   return createHash('sha256').update(value, 'utf8').digest('hex');
@@ -381,7 +382,23 @@ export function collectStatusFacts(options = {}) {
           : arkRulesLoaded
             ? 0
             : null,
+    leftoverDesignWork:
+      options.leftoverDesignWork === true ||
+      latest?.leftoverDesignWork === true ||
+      latest?.designFitness?.designWeak === true ||
+      latest?.doctor?.designFitness?.designWeak === true,
     improvementCompass,
+    vsBase: (() => {
+      const vsRef = typeof options.vs === 'string' ? options.vs.trim() : '';
+      if (!vsRef) return null;
+      const baseRef = discoverTeamBaseRef(resolvedRoot, vsRef);
+      if (!baseRef) return null;
+      return collectVsBaseFacts({
+        root: resolvedRoot,
+        baseRef,
+        configRel: path.basename(configPath),
+      });
+    })(),
   };
 }
 
@@ -423,6 +440,7 @@ export function runStatusCommand(args = {}) {
       expectedProjectId: args.expectedProjectId,
       host: args.host,
       arkgateVersion: args.arkgateVersion,
+      vs: args.vs,
     });
 
     if (asJson || args.json) {
@@ -471,6 +489,7 @@ export function runStatusCommand(args = {}) {
             ' · not a score'
         );
       }
+      if (manifest.vsBase?.line) write(`  ${manifest.vsBase.line}`);
       write(`  next: [${manifest.nextAction.id}] ${manifest.nextAction.summary}`);
     }
 

package/bin/lib/status-manifest.mjs

@@ -230,6 +230,12 @@ export function resolveStatusNextAction(facts, binding, activation, lastCheck, r
             summary: 'Local write is advisory for this host — keep a required GitHub status on arkgate-check --strict-merge as the hard merge boundary.',
         };
     }
+    if (facts.leftoverDesignWork === true) {
+        return {
+            id: 'map-leftover-design',
+            summary: 'Leftover design work remains. Map with /ark-explore, then apply one small refactor with /ark-autopilot. Green imports are not done.',
+        };
+    }
     if (rules.arkRulesLoaded && (rules.frozenResidual ?? 0) > 0) {
         return {
             id: 'review-arkrules-residual',
@@ -311,6 +317,9 @@ export function buildStatusManifest(facts) {
     const compass = normalizeStatusImprovementCompass(facts.improvementCompass);
     if (compass)
         status.improvementCompass = compass;
+    if (facts.vsBase && typeof facts.vsBase.baseRef === 'string' && facts.vsBase.baseRef.length > 0) {
+        status.vsBase = facts.vsBase;
+    }
     return status;
 }
 const STATUS_COMPASS_MODE_SET = new Set(STATUS_COMPASS_MODES);
@@ -576,5 +585,19 @@ export const ARK_STATUS_MANIFEST_SCHEMA = {
                 contractHash: { type: 'string', minLength: 1 },
             },
         },
+        vsBase: {
+            type: 'object',
+            description: 'Checkout vs a git base ref: pin, contract identity, baseline grow. Advisory honesty only — never a gate input.',
+            additionalProperties: false,
+            required: ['baseRef', 'line', 'pinLocal', 'pinBase', 'contractEqual', 'baselineGrew'],
+            properties: {
+                baseRef: { type: 'string', minLength: 1 },
+                line: { type: 'string', minLength: 1 },
+                pinLocal: { anyOf: [{ type: 'string', minLength: 1 }, { type: 'null' }] },
+                pinBase: { anyOf: [{ type: 'string', minLength: 1 }, { type: 'null' }] },
+                contractEqual: { type: 'boolean' },
+                baselineGrew: { type: 'boolean' },
+            },
+        },
     },
 };