@warren-dean/code-kit 0.20.0 → 0.21.0

package/hooks/lib/checks.mjs

@@ -16,13 +16,14 @@ function directories(check, files, root) {
 }
 
 /**
- * The first failure as { title, output }, or null. `actor` decides `owners`; the lead always may. A
+ * The first failure as { check, title, output }, or null. `actor` decides `owners`; the lead always may. A
  * command that isn't installed skips the rest of the check, unless `ifMissing` is "fail", and is
  * added to `skipped` as { check, command, where }, so a pass never hides a check that didn't run.
  */
 function runCheck(check, files, root, actor, skipped) {
   if (check.owners && !(actor.kind === 'lead' || check.owners.includes(actor.lane))) {
     return {
+      check: check.name,
       title: `The ${actor.label} changed ${check.name} files it does not own:`,
       output: files.join('\n'),
     };
@@ -39,6 +40,7 @@ function runCheck(check, files, root, actor, skipped) {
       if (res.status === 127) {
         if (check.ifMissing === 'fail')
           return {
+            check: check.name,
             title: `${check.name}: \`${command}\` is not installed${where}. Install it so the check can run.`,
           };
         skipped.push({ check: check.name, command, where: where.replace(/^ in /, '') || null });
@@ -46,10 +48,12 @@ function runCheck(check, files, root, actor, skipped) {
       }
       if (res.error || res.status === null)
         return {
+          check: check.name,
           title: `${check.name}: \`${command}\` did not finish${where} (${res.error?.code ?? res.signal}).`,
         };
       if (res.status !== 0)
         return {
+          check: check.name,
           title: `${check.name}: \`${command}\` fails${where}. Fix it:`,
           output: res.stdout + res.stderr,
         };

package/hooks/lib/config.mjs

@@ -174,7 +174,7 @@ export function validate(c) {
   );
   // A brownfield project may have no specs yet: then there is no spec-check gate.
   need(c.docs === undefined || isObj(c.docs), '"docs" must be an object');
-  for (const k of ['specs', 'principles', 'plan', 'decisions'])
+  for (const k of ['specs', 'principles', 'plan', 'decisions', 'standards'])
     need(c.docs?.[k] === undefined || isStr(c.docs[k]), `"docs.${k}" must be a path`);
   need(isObj(c.lead) && isList(c.lead?.paths), '"lead.paths" must be a list of globs');
   need(

package/hooks/lib/instructions.mjs

@@ -5,9 +5,16 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  appliesTo,
+  laneLayers,
+  projectStandards,
+  standardLine,
+  standardsFile,
+} from './standards.mjs';
 
 /** The version of code-kit's instructions: raised whenever the templates' rules change. */
-export const INSTRUCTIONS_VERSION = 5;
+export const INSTRUCTIONS_VERSION = 6;
 
 const TEMPLATES = fileURLToPath(new URL('../../templates/', import.meta.url));
 const BEGIN = (v) => `<!-- code-kit:begin v${v} -->`;
@@ -25,8 +32,20 @@ function fill(text, facts) {
     .replace(/\n{3,}/g, '\n\n');
 }
 
-/** What the templates need from the project: everything the config and the repository say. */
-function factsOf(root, config) {
+/** The standards that apply (spec 22), or none when the file can't be read. */
+function standardsOf(root, config) {
+  try {
+    return projectStandards(root, config).standards;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * What the templates need from the project: everything the config and the repository say. With `lane`,
+ * the standards are the ones for that lane's layers (STD-3).
+ */
+function factsOf(root, config, lane = null) {
   const delegated = new Set(config.approvals?.delegate?.protected ?? []);
   const kept = [];
   for (const p of config.protected ?? []) {
@@ -45,9 +64,24 @@ function factsOf(root, config) {
     'docs.specs': config.docs?.specs ?? 'the specs',
     'docs.plan': config.docs?.plan ?? 'the plan',
     'docs.principles': config.docs?.principles ?? "the project's principles",
+    'docs.standards': standardsFile(config),
+    standards: laneStandards(root, config, lane),
+    'standards.all': standardsOf(root, config)
+      .map((s) => `${s.id} ${s.title}`)
+      .join('; '),
   };
 }
 
+/** A lane's standards as the lines of a nested list, or '' when none apply. */
+function laneStandards(root, config, lane) {
+  if (!lane) return '';
+  const layers = (config.layers ?? []).length ? laneLayers(config.lanes?.[lane], config) : null;
+  const lines = standardsOf(root, config)
+    .filter((s) => appliesTo(s, layers))
+    .map((s) => `\n  - ${standardLine(s)}`);
+  return lines.join('');
+}
+
 const marked = (body) => `${BEGIN(INSTRUCTIONS_VERSION)}\n${body.trim()}\n${END}`;
 
 /** The lead's section of CLAUDE.md, between its markers. */
@@ -55,10 +89,10 @@ export function leadSection(root, config) {
   return marked(fill(readFileSync(join(TEMPLATES, 'claude-md.md'), 'utf8'), factsOf(root, config)));
 }
 
-/** A lane agent's "Always:" rules, between their markers. */
-export function agentRules(root, config) {
+/** A lane agent's "Always:" rules, between their markers: with `lane`, its layers' standards too. */
+export function agentRules(root, config, lane = null) {
   const template = readFileSync(join(TEMPLATES, 'agent.md'), 'utf8');
-  return marked(fill(template.slice(template.indexOf('Always:')), factsOf(root, config)));
+  return marked(fill(template.slice(template.indexOf('Always:')), factsOf(root, config, lane)));
 }
 
 /** Whether two renderings say the same, whatever their whitespace and list indentation. */
@@ -87,17 +121,16 @@ function stateOf(text, block, legacy) {
  */
 export function instructionsState(root, config) {
   const lead = leadSection(root, config);
-  const rules = agentRules(root, config);
   const files = [
     { file: 'CLAUDE.md', kind: 'lead', block: lead, legacy: LEAD_LEGACY },
-    ...[...new Set(Object.values(config.lanes ?? {}).map((l) => l.agent))]
-      .map((agent) => ({
-        file: `.claude/agents/${agent}.md`,
+    ...Object.entries(config.lanes ?? {})
+      .filter(([, l]) => existsSync(join(root, `.claude/agents/${l.agent}.md`)))
+      .map(([name, l]) => ({
+        file: `.claude/agents/${l.agent}.md`,
         kind: 'lane',
-        block: rules,
+        block: agentRules(root, config, name),
         legacy: AGENT_LEGACY,
-      }))
-      .filter((f) => existsSync(join(root, f.file))),
+      })),
   ];
   return files.map(({ file, kind, block, legacy }) => {
     const path = join(root, file);

package/hooks/lib/layers.mjs

@@ -55,3 +55,14 @@ export function layerProblems(rel, source, config) {
   }
   return problems;
 }
+
+/**
+ * The rule a layer problem broke, read back from its sentence (as layerProblems words it):
+ * { kind: 'layers', from, to } or { kind: 'layers', from, package }. Null for any other text.
+ */
+export function brokenLayerRule(problem) {
+  const pkg = String(problem).match(/ \(([^()]+)\) may not import the package (\S+)\.$/);
+  if (pkg) return { kind: 'layers', from: pkg[1], package: pkg[2] };
+  const layer = String(problem).match(/ \(([^()]+)\) imports \S+ \(([^()]+)\); /);
+  return layer ? { kind: 'layers', from: layer[1], to: layer[2] } : null;
+}

package/hooks/lib/rules.mjs

@@ -31,6 +31,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
 import { globToRegExp, matchesAny } from './glob.mjs';
+import { noteFor } from './standards.mjs';
 
 export const APPROVAL_LOG = '.claude/approval-log.jsonl';
 export const APPROVALS_DIR = '.claude/approvals';
@@ -763,7 +764,7 @@ export function writeProblem(actor, rel, root, config) {
       decidedBy(guarded.approval, config) === 'lead'
         ? "the lead's approval"
         : "a person's approval";
-    return `${rel} is ${guarded.why} and needs ${who}. ${askHowTo(guarded.approval, actor, root, config)}`;
+    return `${rel} is ${guarded.why} and needs ${who}.${noteFor(root, config, { kind: 'protected', name: guarded.approval, glob: guarded.glob })} ${askHowTo(guarded.approval, actor, root, config)}`;
   }
   if (matchesAny(rel, config.anyActor)) return null;
   if (actor.kind === 'readonly') return readonlyProblem(actor, rel);

package/hooks/lib/snapshot.mjs

@@ -14,8 +14,18 @@ import { sendBacks } from './reviews.mjs';
 import { readMilestones, specCheckRows } from './plan.mjs';
 import { storyTimes } from './timeline.mjs';
 import { trail } from './storymap.mjs';
+import {
+  APPLIED,
+  CATEGORIES,
+  LEVELS,
+  ORIGINS,
+  SOURCES,
+  projectStandards,
+  sourceOf,
+} from './standards.mjs';
 
-export const SNAPSHOT_VERSION = 1;
+/** 2 adds the project's standards (code-kit spec 22). */
+export const SNAPSHOT_VERSION = 2;
 
 /** A story's stage, as a report names it. */
 export const STAGES = [
@@ -87,8 +97,28 @@ export const SNAPSHOT_SCHEMA = {
     delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
     designGate: 'bool',
   },
+  // Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
+  // its why in one line at most, and its evidence only as counts.
+  standards: [
+    {
+      id: 'id',
+      title: 'title',
+      category: `enum:${Object.values(CATEGORIES).join('|')}`,
+      level: `enum:${LEVELS.join('|')}`,
+      applied: `enum:${APPLIED.join('|')}`,
+      layers: ['name'],
+      source: `enum:${SOURCES.join('|')}`,
+      evidenceCount: 'count?',
+      evidenceOf: 'count?',
+      origin: `enum:${ORIGINS.join('|')}`,
+      why: 'line?',
+    },
+  ],
 };
 
+/** Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. */
+export const LATER_PARTS = ['standards'];
+
 const ONE_LINE = (max) => (v) => typeof v === 'string' && v.length <= max && !/[\r\n]/.test(v);
 const KINDS = {
   id: (v) => typeof v === 'string' && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(v),
@@ -122,7 +152,9 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
   const extra = Object.keys(value).filter((k) => !(k in shape));
   return [
     ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
-    ...Object.entries(shape).flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
+    ...Object.entries(shape)
+      .filter(([k]) => !(shape === SNAPSHOT_SCHEMA && LATER_PARTS.includes(k) && !(k in value)))
+      .flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
   ];
 }
 
@@ -143,6 +175,7 @@ export const EVENT_PARTS = [
   'requirements',
   'approvals',
   'rules',
+  'standards',
 ];
 
 const git = (root, ...args) => {
@@ -347,6 +380,45 @@ export function buildSnapshot({
       },
       designGate: Boolean(config.designGate),
     },
+    standards: reportedStandards(root, config, line),
   };
   return snapshot;
 }
+
+/**
+ * Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
+ * unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.
+ */
+function reportedStandards(root, config, line) {
+  let all = [];
+  try {
+    all = projectStandards(root, config).standards;
+  } catch {
+    return [];
+  }
+  return all
+    .filter(
+      (s) =>
+        KINDS.id(s.id) &&
+        CATEGORIES[s.id.split('-')[0]] &&
+        LEVELS.includes(s.level) &&
+        APPLIED.includes(s.applied) &&
+        KINDS.title(line(s.title) ?? ''),
+    )
+    .map((s) => {
+      const source = s.origin === 'inherited' ? { kind: 'organisation' } : sourceOf(s.source);
+      return {
+        id: s.id,
+        title: line(s.title),
+        category: CATEGORIES[s.id.split('-')[0]],
+        level: s.level,
+        applied: s.applied,
+        layers: (s.layers ?? []).filter((l) => KINDS.name(l)),
+        source: source.kind,
+        evidenceCount: source.count ?? null,
+        evidenceOf: source.of ?? null,
+        origin: ORIGINS.includes(s.origin) ? s.origin : 'own',
+        why: line(s.why),
+      };
+    });
+}