arkgate 3.6.1 → 3.8.0

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

@@ -152,6 +152,46 @@ function ambientStateHtml(state) {
   </section>`;
 }
 
+function reshapeDecisionsHtml(memory) {
+  if (!memory) return '';
+  const lifecycle = memory.lifecycle ?? {};
+  const rows = [];
+  if (memory.decisionFile?.invalid) {
+    rows.push(
+      `<p><span class="tag warn">invalid</span> ${esc(memory.decisionFile.path)} is ignored; no reshape decision suppresses a pilot.</p>`
+    );
+  }
+  for (const decision of memory.current ?? []) {
+    const tag = decision.verdict === 'accepted' ? 'ok' : 'warn';
+    const review = decision.reviewBy ? ` · review-by ${esc(decision.reviewBy)}` : '';
+    rows.push(
+      `<p><span class="tag ${tag}">${esc(decision.verdict)}</span> <b>${esc(decision.concept)}</b>${review} — ${esc(decision.reason)}${decision.suppressesPilot ? ' Pilot pressure suppressed; mirror facts remain visible.' : ' Pilot remains available.'}</p>`
+    );
+  }
+  if ((memory.currentCount ?? 0) > (memory.current?.length ?? 0)) {
+    rows.push(`<p class="muted">…(+${memory.currentCount - memory.current.length} more current decision(s))</p>`);
+  }
+  if ((lifecycle.expiredCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">expired</span> ${lifecycle.expiredCount} decision(s) no longer apply; pilot pressure is active again.</p>`);
+  }
+  if ((lifecycle.malformedCount ?? 0) > 0) {
+    rows.push(`<p><span class="tag warn">malformed</span> ${lifecycle.malformedCount} review-by date(s) are invalid; those decisions are ignored.</p>`);
+  }
+  if ((lifecycle.staleCount ?? 0) > 0) {
+    const stale = (lifecycle.stale ?? [])
+      .slice(0, 4)
+      .map((decision) => `<code>${esc(decision.concept)}</code>`)
+      .join(' · ');
+    const more = lifecycle.staleCount > 4 ? ` …(+${lifecycle.staleCount - 4} more)` : '';
+    rows.push(`<p><span class="tag warn">stale</span> ${lifecycle.staleCount} decision(s) have a changed anchor set and no longer apply: ${stale}${more}</p>`);
+  }
+  if ((lifecycle.undated ?? 0) > 0) {
+    rows.push(`<p class="muted">${lifecycle.undated} current decision(s) have no review-by date.</p>`);
+  }
+  if (rows.length === 0) return '';
+  return `<div data-advisory="reshapeDecisions"><h3>Reshape decisions <span class="muted">(explicit; pilot pressure only)</span></h3>${rows.join('\n')}</div>`;
+}
+
 function physicalCohesionHtml(pc) {
   if (!pc) return '';
   const findings = Array.isArray(pc.findings) ? pc.findings : [];
@@ -173,10 +213,28 @@ function physicalCohesionHtml(pc) {
   <section data-advisory="physicalCohesion">
     <h2>Physical cohesion <span class="muted">(advisory — facts, not a score; the verdict is unchanged)</span></h2>
     ${body}
+    ${reshapeDecisionsHtml(pc.reshapeDecisions)}
     ${pilot}
   </section>`;
 }
 
+function parseHealthHtml(health) {
+  if (!health) return '';
+  const files = Array.isArray(health.files) ? health.files : [];
+  const body = health.available === false
+    ? '<p class="muted">Parse health was not available for this rendering — no clean claim is made.</p>'
+    : health.affectedFiles === 0
+    ? `<p class="muted">No parse diagnostics found across ${health.scannedFiles ?? 0} governed file(s) scanned.</p>`
+    : `<p><span class="tag warn">${health.affectedFiles} affected</span> ${health.diagnosticCount} parse diagnostic(s) across ${health.scannedFiles} governed file(s).</p>` +
+      `<ul>${files.map((f) => `<li><code>${esc(f.file)}</code> — ${f.diagnosticCount} parse diagnostic(s)</li>`).join('')}</ul>` +
+      (health.truncated > 0 ? `<p class="muted">…(+${health.truncated} more affected file(s); doctor list capped)</p>` : '');
+  return `
+  <section data-advisory="parseHealth">
+    <h2>Parse health <span class="muted">(completeness evidence — affected syntax makes analysis partial)</span></h2>
+    ${body}
+  </section>`;
+}
+
 /**
  * Render every doctor advisory as report sections. Keys must cover everything
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
@@ -189,6 +247,7 @@ export function renderAdvisorySections(advisories, escape) {
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),
+    parseHealthHtml(advisories.parseHealth),
   ]
     .filter(Boolean)
     .join('\n');

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

@@ -106,6 +106,14 @@ export function renderWritePathAdoptionBlock(writePath) {
   const gapNote = writePath.gap
     ? ` Gap: <b>${esc(writePath.gap.id)}</b> — ${esc(writePath.gap.message || '')}`
     : '';
+  const state = writePath.enforcementState;
+  const value = (entry) => entry === true ? 'yes' : entry === false ? 'no' : String(entry);
+  const boundary = (label, entry) => entry
+    ? `<li><b>${esc(label)}</b> — supported ${esc(value(entry.supported))}; analyzed ${esc(value(entry.analyzed))}; configured ${esc(value(entry.configured))}; installed ${esc(value(entry.installed))}; runtime observed ${esc(value(entry.runtimeObserved))}; operation ${esc(entry.operation ?? 'none')}; operation covered ${esc(value(entry.operationCoverage))}; active ${esc(value(entry.active))}; bypassable ${esc(value(entry.bypassable))}; required ${esc(value(entry.required))}; hard ${esc(value(entry.hard))}</li>`
+    : '';
+  const stateHtml = state
+    ? `<ul class="senior-list" style="margin:.45rem 0 0">${boundary('Local write', state.localWrite)}${boundary('Advisory MCP', state.advisoryMcp)}${boundary('CI merge', state.ciMerge)}</ul>`
+    : '';
   // invLine / gapNote already include escaped user content; only plain strings go through esc().
   return `<div class="write-path-block" title="${esc(writePathModeHint(mode))}">
       <p class="dim" style="margin:.65rem 0 .2rem;font-size:.84rem">
@@ -117,6 +125,7 @@ export function renderWritePathAdoptionBlock(writePath) {
       <p class="kpi-hint" style="max-width:none;margin:0">
         ${esc(writePathModeHint(mode))} ${invLine}${esc(unknownNote)}${gapNote}
       </p>
+      ${stateHtml}
     </div>`;
 }
 

package/bin/lib/html-report.mjs

@@ -51,9 +51,9 @@ export function detectEnforcement(root) {
       '.grok/hooks/ark-write-gate.json') ||
     null;
   return [
-    { name: 'Write gate', where: writeGateFile, what: 'blocks a bad edit as you type (PreToolUse hook / MCP)' },
+    { name: 'Write gate', where: writeGateFile, what: 'configured local gate; active blocking depends on observed host/runtime evidence' },
     { name: 'ESLint', where: eslintFile || null, what: 'flags violations in your editor' },
-    { name: 'CI check', where: workflowsMentionArk(), what: 'blocks the merge if the architecture breaks' },
+    { name: 'CI check', where: workflowsMentionArk(), what: 'runs Ark; merge blocking requires provider-confirmed required status' },
     { name: 'Baseline', where: has('.ark-baseline.json') ? '.ark-baseline.json' : null, what: 'old violations frozen; new ones fail' },
   ].map((e) => ({ ...e, on: !!e.where }));
 }
@@ -1061,8 +1061,8 @@ export function renderHtmlReport({
         )}
         ${metricKpi(
           `${gatesOn}/${enforcement.length}`,
-          'Gates live',
-          'Write hook, CI workflow, ESLint plugin, and baseline file — how many enforcement points are actually present.'
+          'Gates configured',
+          'Write hook, CI workflow, ESLint plugin, and baseline file — how many enforcement surfaces are present, not proof that each is active or required.'
         )}
         ${metricKpi(
           `${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}`,
@@ -1222,7 +1222,7 @@ export function renderHtmlReport({
       ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, ''],
       ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, ''],
       ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, ''],
-      ['Gates live', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
+      ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
     ];
     const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
     const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';

package/bin/lib/install-migrate.mjs

@@ -125,6 +125,81 @@ export function warnLockfileConflict(root) {
   );
 }
 
+/**
+ * Canonical, side-effect-free catalog of project assets emitted by the gate installer.
+ * Upgrade consumes this same allowlist; a manifest can record identities but can never
+ * introduce a new write path.
+ */
+export function buildManagedAssetCatalog({ root, tools, compact = false, skillsOnly = false }) {
+  const selectedTools = tools instanceof Set ? tools : new Set(tools ?? []);
+  const assets = [];
+  const add = (relativePath, content, kind = 'gate', scope = 'whole-file') => {
+    assets.push({
+      relativePath,
+      content,
+      kind,
+      scope,
+      templateId: `${kind}:${relativePath}`,
+    });
+  };
+
+  if (!skillsOnly) {
+    const compactHost = compact ? [...selectedTools][0] ?? null : null;
+    add(
+      'AGENTS.md',
+      compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root)
+    );
+    if (!compact || !compactHost || compactHost === 'claude') add('.mcp.json', mcpJson(root));
+    const deploy = detectDeployPathQuality(root);
+    add(
+      '.github/workflows/ark-check.yml',
+      githubWorkflow(packageManager(root), detectCiNode(root), {
+        hasLintScript: deploy.hasLintScript,
+        hasTypecheckScript: deploy.hasTypecheckScript,
+      })
+    );
+    if (selectedTools.has('cursor')) {
+      add('.cursor/mcp.json', mcpJson(root));
+      if (!compact) add('.cursor/rules/ark.mdc', cursorRule(root));
+    }
+    if (selectedTools.has('claude')) add('.claude/settings.json', claudeSettings(root));
+    if (selectedTools.has('codex')) {
+      add('.codex/hooks.json', codexHooks(root));
+      add('.codex/config.toml', codexProjectConfig(root), 'gate', 'toml-section');
+      if (!compact) add('docs/ark-codex-config.toml', codexTomlSnippet(root));
+    }
+    if (selectedTools.has('grok')) {
+      add('.grok/config.toml', grokProjectConfig(root));
+      add('.grok/hooks/ark-write-gate.json', grokHooks(root));
+    }
+    if (selectedTools.has('windsurf')) add('.windsurf/rules/ark.md', instructionRule(root));
+    if (selectedTools.has('cline')) add('.clinerules/ark.md', instructionRule(root));
+    if (selectedTools.has('copilot')) {
+      add('.github/copilot-instructions.md', instructionRule(root));
+    }
+    if (selectedTools.has('kiro')) add('.kiro/steering/ark.md', instructionRule(root));
+    if (selectedTools.has('roo')) add('.roo/rules/ark.md', instructionRule(root));
+    if (selectedTools.has('continue')) add('.continue/rules/ark.md', instructionRule(root));
+    if (selectedTools.has('gemini')) add('GEMINI.md', instructionRule(root));
+  }
+
+  const version = arkPackageVersion();
+  const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
+  const skillPaths = new Set();
+  if (!compact) {
+    for (const tool of selectedTools) {
+      const target = SKILL_TOOL_TARGETS[tool];
+      if (!target) continue;
+      for (const [name, content] of skills) {
+        const relativePath = target(name);
+        skillPaths.add(relativePath);
+        add(relativePath, content, 'skill');
+      }
+    }
+  }
+  return { assets, skills, skillPaths, version };
+}
+
 // --migrate-commands: rewrite ONLY the Ark command runner in existing gate files to the
 // project's package manager (no --force clobber). Closes the upgrade gap where a repo that
 // adopted before the package-manager-aware templates keeps a stale `npx`.
@@ -220,7 +295,6 @@ export function runInstallAgentGates(args) {
     process.exitCode = 2;
     return;
   }
-  const pm = packageManager(root);
   const hasCheckScript = hasCheckArchitectureScript(root);
   const { tools, source } = args.compact && args.tools == null
     ? { tools: new Set(), source: 'compact-none' }
@@ -239,7 +313,6 @@ export function runInstallAgentGates(args) {
           ? 'no active host detected'
         : 'default set — no agent config dirs found';
   console.log(`Agent gates for: ${[...tools].sort().join(', ')} (${toolSource})`);
-  const templates = [];
   // --skills-only refreshes just the canonical /ark-* skills, which are safe to
   // overwrite (they track the package). The gate/instruction files (AGENTS.md,
   // settings.json, CI workflow, rules) are the ones users customize, so a plain
@@ -253,84 +326,15 @@ export function runInstallAgentGates(args) {
         `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
       );
     }
-    // Base gates: tool-agnostic contract + CI backstop, always written.
-    const compactHost = args.compact ? [...tools][0] ?? null : null;
-    templates.push([
-      'AGENTS.md',
-      args.compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root),
-    ]);
-    if (!args.compact || !compactHost || compactHost === 'claude') {
-      templates.push(['.mcp.json', mcpJson(root)]);
-    }
-    templates.push([
-      '.github/workflows/ark-check.yml',
-      (() => {
-        const deploy = detectDeployPathQuality(root);
-        return githubWorkflow(pm, detectCiNode(root), {
-          hasLintScript: deploy.hasLintScript,
-          hasTypecheckScript: deploy.hasTypecheckScript,
-        });
-      })(),
-    ]);
-    if (tools.has('cursor')) {
-      templates.push(['.cursor/mcp.json', mcpJson(root)]);
-      if (!args.compact) templates.push(['.cursor/rules/ark.mdc', cursorRule(root)]);
-    }
-    if (tools.has('claude')) {
-      templates.push(['.claude/settings.json', claudeSettings(root)]);
-    }
-    if (tools.has('codex')) {
-      templates.push(['.codex/hooks.json', codexHooks(root)]);
-      templates.push(['.codex/config.toml', codexProjectConfig(root)]);
-      if (!args.compact) templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
-    }
-    if (tools.has('grok')) {
-      templates.push(['.grok/config.toml', grokProjectConfig(root)]);
-      templates.push(['.grok/hooks/ark-write-gate.json', grokHooks(root)]);
-    }
-    // Instruction-tier hosts: one shared rule text, host-specific path.
-    if (tools.has('windsurf')) {
-      templates.push(['.windsurf/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('cline')) {
-      templates.push(['.clinerules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('copilot')) {
-      templates.push(['.github/copilot-instructions.md', instructionRule(root)]);
-    }
-    if (tools.has('kiro')) {
-      templates.push(['.kiro/steering/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('roo')) {
-      templates.push(['.roo/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('continue')) {
-      templates.push(['.continue/rules/ark.md', instructionRule(root)]);
-    }
-    // Gemini CLI reads GEMINI.md as its primary project context (it also reads
-    // AGENTS.md, but GEMINI.md wins when both are present), so the rule lives there.
-    if (tools.has('gemini')) {
-      templates.push(['GEMINI.md', instructionRule(root)]);
-    }
-  }
-  // /ark-* skills for every detected tool that supports project-level commands.
-  // Stamp each with the shipping version so a later ark-check can flag skills
-  // left behind by an older Ark (see detectSkillGaps) without nagging about
-  // user edits to the body.
-  const version = arkPackageVersion();
-  const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
-  const skillPaths = new Set();
-  if (!args.compact) {
-    for (const tool of tools) {
-      const target = SKILL_TOOL_TARGETS[tool];
-      if (!target) continue;
-      for (const [name, content] of skills) {
-        const relativePath = target(name);
-        skillPaths.add(relativePath);
-        templates.push([relativePath, content]);
-      }
-    }
   }
+  const catalog = buildManagedAssetCatalog({
+    root,
+    tools,
+    compact: args.compact,
+    skillsOnly: args.skillsOnly,
+  });
+  const { skills, skillPaths, version } = catalog;
+  const templates = catalog.assets.map(({ relativePath, content }) => [relativePath, content]);
 
   // A compact router can be moved back from an explicit host removal. Delete the
   // generic MCP file only when it exactly matches Ark's generated artifact.