arkgate 4.5.7 → 4.6.1

package/bin/lib/product-copy.mjs

@@ -0,0 +1,32 @@
+/**
+ * Human-facing product copy (4.6). JSON field names stay stable; this module
+ * owns labels people read in doctor, HTML, and compact router.
+ *
+ * Brands kept: ArkGate, ArkRules. Dialect (design-weak, hard write, …) maps to
+ * common software words. See docs/product-voice.md.
+ */
+
+/** Status-light leftover-design qualifier (was “design-weak”). */
+export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
+
+/**
+ * Operating-mode title for humans (and doctor JSON `designFitness.label` prefix).
+ * @param {string|null|undefined} mode suggest|adapt|enforce
+ * @param {boolean} leftoverDesign
+ */
+export function operatingModeTitle(mode, leftoverDesign) {
+  const light = String(mode || 'enforce').toUpperCase();
+  return leftoverDesign ? `${light} · ${LEFTOVER_DESIGN_LABEL}` : light;
+}
+
+/** Short HTML/doctor badge text. */
+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. 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.';
+
+export const HARD_WRITE_HUMAN = 'pre-write block';
+export const ADVISORY_WRITE_HUMAN = 'warning only (not blocked)';

package/bin/lib/skill-write.mjs

@@ -16,7 +16,7 @@ export const HOME_SKILL_PENDING_CATALOG = '.arkgate-catalog.pending.json';
 const HOME_SKILL_LOCK = '.arkgate-install.lock';
 const HOME_SKILL_CATALOG_SCHEMA = '1.0';
 const HOME_SKILL_LOCK_STALE_MS = 5 * 60 * 1000;
-const HOME_SKILL_LOCK_ATTEMPTS = 100;
+const HOME_SKILL_LOCK_ATTEMPTS = 200;
 const HOME_SKILL_LOCK_RETRY_MS = 25;
 const UUID_PATTERN =
   /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;

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');
@@ -382,6 +383,17 @@ export function collectStatusFacts(options = {}) {
             ? 0
             : null,
     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 +435,7 @@ export function runStatusCommand(args = {}) {
       expectedProjectId: args.expectedProjectId,
       host: args.host,
       arkgateVersion: args.arkgateVersion,
+      vs: args.vs,
     });
 
     if (asJson || args.json) {
@@ -471,6 +484,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

@@ -311,6 +311,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 +579,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' },
+            },
+        },
     },
 };

package/bin/lib/team-parliament-io.mjs

@@ -0,0 +1,338 @@
+/**
+ * Team parliament I/O — git base refs, changed paths, pin/contract/baseline compare.
+ * Pure classification lives in team-parliament.mjs (Domain).
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import {
+  baselineKeysFromDocument,
+  classifyBaselineKeyDelta,
+  classifyChangeSet,
+  evaluateTeamGate,
+  formatVsBaseLine,
+  isTeamPersona,
+  mapPolicyClassToKind,
+  parseCodeownersHandles,
+  personaCheckBudget,
+  resolveStewardHandle,
+  suggestStewards,
+} from './team-parliament.mjs';
+
+export {
+  baselineKeysFromDocument,
+  classifyBaselineKeyDelta,
+  classifyChangeSet,
+  evaluateTeamGate,
+  formatVsBaseLine,
+  isTeamPersona,
+  mapPolicyClassToKind,
+  parseCodeownersHandles,
+  personaCheckBudget,
+  resolveStewardHandle,
+  suggestStewards,
+};
+
+function runGit(cwd, args) {
+  return spawnSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+export function safeGitRef(value) {
+  return (
+    typeof value === 'string' &&
+    /^[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/.test(value) &&
+    !value.includes('..')
+  );
+}
+
+export function contractSessionFrom(args, env = process.env) {
+  if (args?.contractSession === true) return true;
+  const raw = env.ARK_CONTRACT_SESSION;
+  return raw === '1' || raw === 'true';
+}
+
+export function resolveTeamAuthor(args, env = process.env) {
+  return resolveStewardHandle({
+    explicit: typeof args?.author === 'string' ? args.author : null,
+    githubActor: env.GITHUB_ACTOR,
+    arkSteward: env.ARK_STEWARD,
+    authorEmail: env.GIT_AUTHOR_EMAIL,
+    gitName: env.GIT_AUTHOR_NAME,
+  });
+}
+
+export function discoverTeamBaseRef(root, preferred) {
+  if (safeGitRef(preferred)) return preferred;
+  const candidates = ['origin/dev', 'origin/main', 'origin/master', 'dev', 'main'];
+  for (const candidate of candidates) {
+    const exists = runGit(root, ['rev-parse', '--verify', `${candidate}^{commit}`]);
+    if (exists.status === 0) return candidate;
+  }
+  return null;
+}
+
+export function listChangedPaths(root, baseRef) {
+  if (!safeGitRef(baseRef)) {
+    return { ok: false, paths: [], error: 'Invalid or missing git base ref.' };
+  }
+  const verify = runGit(root, ['rev-parse', '--verify', `${baseRef}^{commit}`]);
+  if (verify.status !== 0) {
+    return { ok: false, paths: [], error: `Cannot resolve git ref ${baseRef}.` };
+  }
+  const diff = runGit(root, ['diff', '--name-only', `${baseRef}...HEAD`]);
+  const unstaged = runGit(root, ['diff', '--name-only']);
+  const staged = runGit(root, ['diff', '--name-only', '--cached']);
+  const untracked = runGit(root, ['ls-files', '--others', '--exclude-standard']);
+  if (diff.status !== 0) {
+    return { ok: false, paths: [], error: diff.stderr.trim() || `git diff ${baseRef} failed.` };
+  }
+  const paths = [
+    ...diff.stdout.split('\n'),
+    ...unstaged.stdout.split('\n'),
+    ...staged.stdout.split('\n'),
+    ...untracked.stdout.split('\n'),
+  ]
+    .map((line) => line.trim().replace(/\\/g, '/'))
+    .filter(Boolean);
+  return { ok: true, paths: [...new Set(paths)].sort(), error: null };
+}
+
+export function gitShowText(root, baseRef, relPath) {
+  if (!safeGitRef(baseRef) || !relPath) return null;
+  const shown = runGit(root, ['show', `${baseRef}:${relPath}`]);
+  if (shown.status !== 0) return null;
+  return shown.stdout;
+}
+
+export function readJsonMaybe(text) {
+  if (typeof text !== 'string' || !text.trim()) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function arkgatePinFromPackageJson(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const bags = [raw.dependencies, raw.devDependencies, raw.optionalDependencies];
+  for (const bag of bags) {
+    if (bag && typeof bag.arkgate === 'string' && bag.arkgate.trim()) return bag.arkgate.trim();
+  }
+  if (raw.name === 'arkgate' && typeof raw.version === 'string') return raw.version;
+  return null;
+}
+
+function sha256Text(text) {
+  return `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}
+
+export function collectVsBaseFacts({ root, baseRef, configRel = 'ark.config.json' }) {
+  const localConfigPath = path.join(root, configRel);
+  const localPkgPath = path.join(root, 'package.json');
+  const localBaselinePath = path.join(root, '.ark-baseline.json');
+  const localConfig = fs.existsSync(localConfigPath) ? fs.readFileSync(localConfigPath, 'utf8') : '';
+  const localPkg = fs.existsSync(localPkgPath)
+    ? readJsonMaybe(fs.readFileSync(localPkgPath, 'utf8'))
+    : null;
+  const localBaseline = fs.existsSync(localBaselinePath)
+    ? readJsonMaybe(fs.readFileSync(localBaselinePath, 'utf8'))
+    : null;
+  const baseConfig = gitShowText(root, baseRef, configRel) ?? '';
+  const basePkg = readJsonMaybe(gitShowText(root, baseRef, 'package.json'));
+  const baseBaseline = readJsonMaybe(gitShowText(root, baseRef, '.ark-baseline.json'));
+  const localKeys = baselineKeysFromDocument(localBaseline);
+  const baseKeys = baselineKeysFromDocument(baseBaseline);
+  const grew = classifyBaselineKeyDelta(baseKeys, localKeys).grow.length > 0;
+  const facts = {
+    baseRef,
+    pinLocal: arkgatePinFromPackageJson(localPkg),
+    pinBase: arkgatePinFromPackageJson(basePkg),
+    contractEqual: Boolean(localConfig) && localConfig === baseConfig,
+    baselineGrew: grew,
+  };
+  if (localConfig && baseConfig && !facts.contractEqual) {
+    facts.contractEqual = sha256Text(localConfig) === sha256Text(baseConfig);
+  }
+  return { ...facts, line: formatVsBaseLine(facts) };
+}
+
+export function teamStewardsFromConfig(config) {
+  return Array.isArray(config?.stewards) ? config.stewards.filter((s) => typeof s === 'string') : [];
+}
+
+export function applyPersonaDefaults(args) {
+  const next = { ...args };
+  if (!isTeamPersona(next.persona)) return next;
+  const budget = personaCheckBudget(next.persona);
+  if (budget.scan === 'none' || budget.scan === 'changed' || budget.scan === 'changed+ungoverned') {
+    next.changed = true;
+  }
+  if (budget.scan === 'changed+ungoverned') next.failUngoverned = true;
+  if (budget.contractDiff) next.contractDiff = true;
+  if (next.persona === 'steward') next.contractSession = true;
+  return next;
+}
+
+export function bindTeamBaseRefs(args, root) {
+  const next = applyPersonaDefaults(args);
+  const teamBase = discoverTeamBaseRef(
+    root,
+    next.base || next.against || next.policyBaseRef || next.baseRef
+  );
+  if (teamBase) {
+    if (!next.against && (next.changed || next.contractDiff || next.persona)) {
+      next.against = teamBase;
+    }
+    if (!next.policyBaseRef && (next.contractDiff || next.changed || next.against)) {
+      next.policyBaseRef = teamBase;
+    }
+    if (!next.baseRef && next.failOnNewSmells) next.baseRef = teamBase;
+  }
+  return { args: next, teamBase };
+}
+
+export function teamCheckRequested(args, config) {
+  return Boolean(
+    args.changed ||
+      args.contractDiff ||
+      args.against ||
+      args.persona ||
+      args.contractSession ||
+      (args.strictMerge && teamStewardsFromConfig(config).length > 0)
+  );
+}
+
+export function runTeamPreflight({ root, args, config, policyDelta, teamBase }) {
+  if (!teamCheckRequested(args, config)) {
+    return { halt: null, teamParliament: null, changedPaths: [] };
+  }
+  const againstRef = args.against || teamBase;
+  const listed = againstRef ? listChangedPaths(root, againstRef) : { ok: true, paths: [], error: null };
+  const changedPaths = listed.ok ? listed.paths : [];
+  const changeSet = classifyChangeSet(changedPaths);
+  const baseBaselineRaw = againstRef
+    ? readJsonMaybe(gitShowText(root, againstRef, '.ark-baseline.json'))
+    : null;
+  const localBaselinePath = path.join(root, args.baseline || '.ark-baseline.json');
+  const localBaselineRaw = fs.existsSync(localBaselinePath)
+    ? readJsonMaybe(fs.readFileSync(localBaselinePath, 'utf8'))
+    : null;
+  const baselineDelta = classifyBaselineKeyDelta(
+    baselineKeysFromDocument(baseBaselineRaw),
+    baselineKeysFromDocument(localBaselineRaw)
+  );
+  const policyKind = mapPolicyClassToKind(policyDelta?.classification ?? null);
+  const verdict = evaluateTeamGate({
+    changeSet,
+    contractSession: contractSessionFrom(args),
+    policyKind,
+    baselineGrowCount: baselineDelta.grow.length,
+    stewards: teamStewardsFromConfig(config),
+    author: resolveTeamAuthor(args),
+  });
+  const teamParliament = {
+    baseRef: againstRef,
+    changeSet,
+    policyKind,
+    baselineGrow: baselineDelta.grow.length,
+    baselineShrink: baselineDelta.shrink.length,
+    ...verdict,
+    changedPathError: listed.ok ? null : listed.error,
+  };
+  if (!listed.ok && (args.changed || args.against || args.contractDiff)) {
+    return {
+      halt: { exitCode: 2, message: listed.error || 'Cannot resolve team base ref.', teamParliament },
+      teamParliament,
+      changedPaths,
+    };
+  }
+  if (verdict.deny) {
+    return {
+      halt: { exitCode: 1, message: verdict.message, teamParliament, fail: true },
+      teamParliament,
+      changedPaths,
+    };
+  }
+  if (args.changed && changeSet.productPaths.length === 0 && !changeSet.hasLaw) {
+    return {
+      halt: { exitCode: 0, cheap: true, teamParliament },
+      teamParliament,
+      changedPaths,
+    };
+  }
+  return { halt: null, teamParliament, changedPaths };
+}
+
+export function ungovernedDumpMessage(dumped) {
+  return `New ungoverned source in this diff: ${dumped.slice(0, 8).join(', ')}${dumped.length > 8 ? '…' : ''}. Classify via /ark-adopt (contract session) or move into a governed layer.`;
+}
+
+export function filterChangedGovernedFiles(allGovernedFiles, root, changedPaths, normalizeRel) {
+  if (!changedPaths?.length) return allGovernedFiles;
+  const changedSet = new Set(changedPaths);
+  return allGovernedFiles.filter((abs) => changedSet.has(normalizeRel(path.relative(root, abs))));
+}
+
+export function applyAgainstRatchet({
+  violations,
+  againstRef,
+  root,
+  changed,
+  changedPaths,
+  occurrenceKeys,
+}) {
+  const baseRaw = readJsonMaybe(gitShowText(root, againstRef, '.ark-baseline.json'));
+  const baseKeys = new Set(baselineKeysFromDocument(baseRaw));
+  const vsBaseActive = violations.filter((_, index) => !baseKeys.has(occurrenceKeys[index]));
+  const changedSet = new Set(changedPaths ?? []);
+  const activeViolations = changed
+    ? vsBaseActive.filter((violation) =>
+        changedSet.has(String(violation.file || '').replace(/\\/g, '/'))
+      )
+    : vsBaseActive;
+  return {
+    activeViolations,
+    suppressed: violations.filter((violation) => !activeViolations.includes(violation)),
+  };
+}
+
+function gitAuthors(root) {
+  const log = runGit(root, ['log', '--format=%aN<%aE>', '--max-count=300']);
+  if (log.status !== 0) return [];
+  const ids = [];
+  for (const line of log.stdout.split('\n')) {
+    const match = line.trim().match(/^(.*)<([^>]+)>$/);
+    if (!match) continue;
+    const name = match[1].trim();
+    const email = match[2].trim();
+    ids.push(email || name);
+  }
+  return ids;
+}
+
+function readCodeowners(root) {
+  for (const rel of ['CODEOWNERS', '.github/CODEOWNERS', 'docs/CODEOWNERS']) {
+    const full = path.join(root, rel);
+    if (!fs.existsSync(full)) continue;
+    try {
+      return parseCodeownersHandles(fs.readFileSync(full, 'utf8'));
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+/** Advisory only. Never flips a gate. Missing git is honest empty, not green. */
+export function collectStewardNudge(root, config) {
+  return suggestStewards({
+    existingStewards: teamStewardsFromConfig(config),
+    gitAuthors: gitAuthors(root),
+    codeowners: readCodeowners(root),
+  });
+}