arkgate 4.8.20 → 4.8.21

package/bin/lib/config-contract.mjs

@@ -214,6 +214,11 @@ export const ARK_CONFIG_SCHEMA = {
                 message: { type: 'string', minLength: 1 },
                 peerIsolation: { type: 'boolean' },
                 sliceFolders: { ...stringArraySchema, minItems: 1 },
+                sliceIdentity: {
+                    type: 'string',
+                    enum: ['path', 'stars'],
+                    description: 'How a starred sliceFolders prefix is named. Absent and path keep today\'s ids (every literal and star binding). stars keeps the last literal plus the star bindings, so parallel trees share one feature id. Bare names are unchanged.',
+                },
                 sharedRoots: { ...stringArraySchema, minItems: 1 },
                 allowedCrossSlice: {
                     type: 'array',

package/bin/lib/diagnostic-catalog.mjs

@@ -120,6 +120,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('CONFIG_AMBIGUOUS_LAYERS', 'config', 'Ambiguous layer classification', 'Some files match multiple layers at equal specificity; classification falls back to declaration order.', 'Disambiguate overlapping patterns so each file has one clear layer owner.', { oftenAdvisory: true }),
     entry('CONFIG_UNCLASSIFIED_FILES', 'config', 'Unclassified included files', 'Included source files match no layer pattern; import rules will not enforce on them.', 'Extend layer patterns or narrow include so every governed file is classified.', { oftenAdvisory: true }),
     entry('CONFIG_LAYER_MISSING_OWNER', 'config', 'Layer missing owner', 'requireLayerOwners is on and this layer has no owners. Writes to that house fail closed, like a folder with no name on the door.', 'Add a GitHub handle or email to that layer’s owners in ark.config.json (/ark-adopt), then re-run. Reserved/allowEmpty houses may stay unnamed. Turn the flag off only if you no longer want owners required.'),
+    entry('CONFIG_SLICE_IDENTITY_COLLISION', 'config', 'Starred slice prefixes share one id', 'sliceIdentity is stars and two different sliceFolders prefixes bind as the same slice id. Parallel trees of one feature do that on purpose; unrelated trees that share the last folder name merge by accident.', 'Keep stars when those prefixes are one feature. Otherwise use path, or rename the last literal so the prefixes do not bind as the same id. Doctor names both paths.', { oftenAdvisory: true }),
     // ── literal path drift ───────────────────────────────────────────────────
     entry('LITERAL_PATH_DRIFT', 'drift', 'Literal path moved by a rename', 'A repo path written inside a string, a comment or a docstring no longer resolves, and the rename set says where it went. Nothing in the gate sees this class: `tsc` resolves imports, not strings, and ESLint does not either, so the rename compiles green and the reference lies afterwards. It appears in four forms — the tsconfig alias, a relative literal, a path written without the include-root prefix, and prose — and a hand sweep reliably covers one of them.', 'Apply the suggested replacement, or re-run `npx arkgate-check --path-drift --base-ref <ref> --write` to apply every writable anchored replacement at once. The rewrite is mechanical and one-directional: the destination comes from the rename, it must itself resolve and be path-shaped, and the token is rewritten in the form the author wrote it in. A destination that leaves the alias root of the literal is reported with the target only and must be rewritten by hand.'),
     entry('LITERAL_PATH_UNRESOLVED', 'drift', 'Literal path does not resolve', 'A literal that looks like a repo path does not resolve under this root, and no rename explains where it went. Unlike LITERAL_PATH_DRIFT this is a candidate, not a verdict: with nothing to anchor it, ArkGate cannot tell a dead reference from an illustrative path in a comment, an example in documentation, or a path belonging to another tree.', 'Read the candidate and decide: fix the path, or leave it. Advisory only — it never fails a run and is never rewritten by --write, because there is no destination to propose. Run `--path-drift --all` to list the sweep.', { oftenAdvisory: true }),

package/bin/lib/doctor-advisories.mjs

@@ -37,6 +37,7 @@ import {
 } from './ark-order-doctor.mjs';
 import { composeMergePlanesHonesty } from './extra-merge-teeth.mjs';
 import { collectPrototypeShortcutsResidual } from './prototype-shortcuts.mjs';
+import { sliceIdentityCollisions } from '../ark-layer-match.mjs';
 
 export function attachExtraDoctorSections(rulesUnderContract, config, classification, findings) {
   const arkRulesMerge = {
@@ -122,6 +123,13 @@ export function printCompactExtraDoctorLines(advisories, io) {
       if (states.nextAction) io.line(' ', `Next: ${states.nextAction}`);
     }
   }
+  const sliceIdentity = advisories?.sliceIdentity;
+  if (Array.isArray(sliceIdentity?.collisions) && sliceIdentity.collisions.length > 0) {
+    console.log('');
+    for (const collision of sliceIdentity.collisions) {
+      io.line(io.warn, collision.message);
+    }
+  }
   const noDomain = advisories?.noDomainFrontend;
   if (noDomain?.ask) {
     console.log('');
@@ -247,8 +255,12 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     coverage: cov,
     files,
   });
+  const sliceIdentityHits = sliceIdentityCollisions(rules ?? config?.rules);
   return {
     ...(prototypeShortcuts ? { prototypeShortcuts } : {}),
+    ...(sliceIdentityHits.length > 0
+      ? { sliceIdentity: { notAScore: true, collisions: sliceIdentityHits } }
+      : {}),
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
     physicalCohesion,
@@ -265,6 +277,14 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
 }
 
 export function printDoctorAdvisories(advisories, io) {
+  const sliceIdentity = advisories?.sliceIdentity;
+  if (Array.isArray(sliceIdentity?.collisions) && sliceIdentity.collisions.length > 0) {
+    console.log('');
+    console.log(io.color.bold('Slice identity'));
+    for (const collision of sliceIdentity.collisions) {
+      io.line(io.warn, collision.message);
+    }
+  }
   printContractHealthSection(advisories.contractHealth, io);
   printAmbientStateSection(advisories.ambientState, io);
   printPhysicalCohesionSection(

package/bin/lib/doctor-human.mjs

@@ -14,6 +14,7 @@ import { analysisIncompleteStatement } from './analysis-completeness.mjs';
 import { skillGapsForActiveHost, detectCodexHomeGap, codexConcernIsActive, skillGapToolLabel } from './agent-gates.mjs';
 import { agentHomeConcernIsActive } from './agent-homes.mjs';
 import { layerGuidanceLine } from './layer-description.mjs';
+import { printSharedImportsSliceBridgeList } from './violations.mjs';
 import {
   citedGreen,
   ciMergeGreenCites,
@@ -187,6 +188,7 @@ export function printDoctorCompactHuman(view) {
     }
   }
 
+  printSharedImportsSliceBridgeList(view.warnings);
   console.log('');
   console.log(color.dim('More: --doctor --all'));
 }
@@ -298,15 +300,15 @@ export function printDoctorDetailsHuman(view) {
         line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
       }
     }
-    if (pilotLoop?.active && pilotLoop.nextPilot) {
-      const np = pilotLoop.nextPilot;
-      line(
-        warn,
-        `Next pilot (one at a time): ${np.pilotTarget || np.pilot} [${np.smellId}] → re-doctor after change`
-      );
-      line(' ', color.dim(`success: ${np.successSignal}`));
-      line(' ', color.dim('never multi-pilot batch; pattern bets are never auto-applied'));
-    }
+  }
+  if (pilotLoop?.active && pilotLoop.nextPilot) {
+    const np = pilotLoop.nextPilot;
+    line(
+      warn,
+      `Next pilot (one at a time): ${np.pilotTarget || np.pilot} [${np.smellId}] → re-doctor after change`
+    );
+    line(' ', color.dim(`success: ${np.successSignal}`));
+    line(' ', color.dim('never multi-pilot batch; pattern bets are never auto-applied'));
   }
 
   if (options.designDelta) {

package/bin/lib/doctor-plan.mjs

@@ -66,7 +66,7 @@ import {
   loadGoldenPattern,
   summarizeGoldenPattern,
 } from './golden-pattern.mjs';
-import { summarizePilotLoop } from './pilot-loop.mjs';
+import { collectPilotCandidates, summarizePilotLoop } from './pilot-loop.mjs';
 import { computeDoctorAdvisories } from './doctor-advisories.mjs';
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
@@ -325,12 +325,8 @@ export function buildRemediationPlan(
     governedPercent,
     totalFiles,
   });
-  // Q04 — single next pilot extraction card (one at a time → re-doctor).
-  const pilotLoop = summarizePilotLoop({
-    designWeak,
-    patternBets,
-    designSmells,
-  });
+  // Q04 — one candidate at a time. Plan has no cohesion advisory.
+  const pilotLoop = summarizePilotLoop(collectPilotCandidates({ designWeak, patternBets, designSmells }));
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
     totalFiles,
@@ -604,13 +600,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const goldenPattern = summarizeGoldenPattern(goldenLoad);
   // Y06 — pure-layer opt-in when golden names pure modules but no pure:true layer.
   const pureLayerOptIn = computePureLayerOptInNudge(config, goldenLoad);
-  // Q04 — one next pilot (extraction card) when design-weak.
-  const patternBetsForLoop = buildPatternBetsFromSmells(designSmells);
-  const pilotLoop = summarizePilotLoop({
-    designWeak: designFitness.designWeak,
-    patternBets: patternBetsForLoop,
-    designSmells,
-  });
   const activeViolations = baseline.exists
     ? violations.filter((_, index) => !baseline.keys.has(occurrenceKeys[index]))
     : violations;
@@ -625,6 +614,17 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     options.facts ?? options.architectureFacts,
     activeViolations
   );
+  // After physical cohesion so a reshape pilot is a candidate (#309).
+  const pilotLoop = summarizePilotLoop(
+    collectPilotCandidates(
+      {
+        ...designFitness,
+        patternBets: buildPatternBetsFromSmells(designSmells),
+        designSmells,
+      },
+      doctorAdvisories
+    )
+  );
   const layerOwners = collectLayerOwnerResidual(config);
   const rulesUnderContract = doctorAdvisories.rulesUnderContract;
   const arkRun = doctorAdvisories.arkRun;
@@ -965,6 +965,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     activeCount,
     skillGaps,
     agentHomeGaps,
+    warnings: options.warnings,
     baseline,
     baselineHonesty,
     staleBaseline,

package/bin/lib/first-run-help.mjs

@@ -27,6 +27,9 @@ export function upgradeUsage() {
   arkgate upgrade --apply    apply the previewed bytes (needs --plan-digest when applying managed files)
 
 Customized files stay unless you pass --accept-conflicts or --refresh-skills.
+A gitignored missing file (absent-local) is recreated without that flag.
+Exit: 0 applied and green; 3 applied but red; 2 blocked (consent); 1 error.
+Scripts comparing against 1 must switch to non-zero.
 Then: arkgate-check --doctor
 
 Every flag: arkgate --help --all
@@ -77,8 +80,11 @@ Options:
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
   --apply       Apply a start plan; for upgrade, update/repreview or apply managed bytes.
   --accept-conflicts
-                Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
+                Allow upgrade to recreate a deleted managed asset that is not gitignored, or replace a recorded conflict.
+                A missing gitignored file (absent-local, for example per-machine .mcp.json) is recreated without this flag.
   --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
+                upgrade --apply exits 0 when applied and the architecture check is green, 3 when applied but red,
+                2 when blocked for consent, and 1 on error. Scripts comparing against 1 must switch to non-zero.
   --json        Emit the start/upgrade/status/agents-md preview as deterministic machine-readable JSON.
   --write       For agents-md: merge the version-matched projection into AGENTS.md.
   --check       For agents-md: exit 1 when projection stamp drifts from package version.

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

@@ -88,6 +88,13 @@ function ackLifecycleHtml(lc) {
   return rows.join('\n');
 }
 
+function sliceIdentityHtml(section) {
+  const collisions = Array.isArray(section?.collisions) ? section.collisions : [];
+  if (collisions.length === 0) return '';
+  const items = collisions.map((collision) => `<li>${esc(collision.message ?? '')}</li>`).join('');
+  return `<section class="section card" data-advisory="sliceIdentity"><h2>Slice identity <span class="muted">(advisory — not a verdict, not a score)</span></h2><ul>${items}</ul><p class="muted">Two prefixes bind as one slice id under <code>sliceIdentity: "stars"</code>. That is the point when the trees are one feature, and a mistake when they are not.</p></section>`;
+}
+
 function contractHealthHtml(health) {
   if (!health) return '';
   const smells = Array.isArray(health.smells) ? health.smells : [];
@@ -347,6 +354,7 @@ export function renderAdvisorySections(advisories, escape) {
     improvementCompassHtml(advisories.improvementCompass),
     deepModuleCoachHtml(advisories.deepModuleCoach),
     stewardNudgeHtml(advisories.stewardNudge),
+    sliceIdentityHtml(advisories.sliceIdentity),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

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

@@ -8,7 +8,7 @@ import {
   summarizeDesignFitness,
   buildPatternBetsFromSmells,
 } from './design-smells.mjs';
-import { summarizePilotLoop } from './pilot-loop.mjs';
+import { collectPilotCandidates, summarizePilotLoop } from './pilot-loop.mjs';
 import { buildPostGreenNextAction } from './post-green-path.mjs';
 import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
 import { collectAdoptionGaps } from './mcp-adoption.mjs';
@@ -76,11 +76,14 @@ export function buildReportDepthPayload(
   });
   const postGreenPath = buildPostGreenNextAction(designFitness);
   const patternBets = buildPatternBetsFromSmells(designSmells);
-  const pilotLoop = summarizePilotLoop({
-    designWeak: designFitness.designWeak,
-    patternBets,
-    designSmells,
-  });
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  physicalCohesion.reshapeDecisions = computeReshapeDecisionMemory(root, files).summary;
+  const pilotLoop = summarizePilotLoop(
+    collectPilotCandidates(
+      { ...designFitness, patternBets, designSmells },
+      { physicalCohesion }
+    )
+  );
   const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
   const adoption = collectAdoptionGaps(root, config, coverage);
   const baseline = readBaseline(root, '.ark-baseline.json');
@@ -155,8 +158,6 @@ export function buildReportDepthPayload(
       : packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT'
         ? 'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
         : null;
-  const physicalCohesion = computePhysicalCohesion(root, files);
-  physicalCohesion.reshapeDecisions = computeReshapeDecisionMemory(root, files).summary;
   const productHonesty = buildProductHonesty({
     coverageHonesty,
     baselineHonesty,