geneseed 3.17.0 → 3.19.0

package/js/inspect/checks-repo.mjs

@@ -7,15 +7,20 @@
  * itself and compares it against what is on disk.
  */
 import path from 'node:path';
-import { PLUGIN_SRC, ROOT, SRC, THEMES, WORKFLOW_SRC } from '../build/source.mjs';
+import {
+  ALIASES_RE, PLUGIN_SRC, RETIRED_SKILL_IDS, ROOT, SRC, THEMES, WORKFLOW_SRC, aliasesOf, knownSkillIds,
+} from '../build/source.mjs';
 import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
+import { COMMAND_SET } from '../hosts/opencode.mjs';
 import { hookShimPath, shimDeadPaths } from '../hosts/shim.mjs';
 import { readText } from '../lib/fs.mjs';
 import { formatRepr, formatValue } from '../lib/json.mjs';
 import { splitLines } from '../lib/udiff.mjs';
 import { ENTITY_STATUSES } from './inventory.mjs';
+import { assessRepo } from './scorecard.mjs';
+import { badgeUrl, renderSvg } from './scorecard-svg.mjs';
 import { isDir, isFile, rglob, srcStems } from './scan.mjs';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 
 /**
  * `_harness_build._registry_keys` — every entity the registry must describe.
@@ -106,6 +111,7 @@ export function registryProblems() {
  *
  * `(?i)` becomes the `i` flag on the last one only, which is where the Python puts it.
  */
+/** @type {Array<[string, RegExp]>} */
 const SECRET_PATTERNS = [
   ['Anthropic API key', /sk-ant-[A-Za-z0-9_-]{20,}/],
   ['OpenAI-style API key', /\bsk-[A-Za-z0-9]{32,}/],
@@ -240,6 +246,83 @@ export function vendorPinProblems() {
   return problems;
 }
 
+/**
+ * Every `<!-- aliases: … -->` name is a clean, unclaimed, single-owner path segment.
+ *
+ * An alias becomes a folder (`skills/<alias>/`) and a command file (`command/<alias>.md`) on
+ * every install, so a name that collides overwrites something: another skill, another
+ * skill's alias, or an OpenCode command (`COMMAND_SET`, `/ponytail`). A retired skill id is
+ * refused as an alias AND as a live skill — `RETIRED_SKILL_IDS` is the list of names that
+ * already meant something on someone's machine. The emit trusts all of this; this is where
+ * it is checked.
+ */
+export function aliasProblems(src = SRC) {
+  const problems = [];
+  const known = knownSkillIds(src);
+  const reserved = new Set([...Object.keys(COMMAND_SET), 'ponytail']);
+  for (const id of known) {
+    if (Object.hasOwn(RETIRED_SKILL_IDS, id)) {
+      problems.push(`[authoring] skill '${id}' reuses a retired skill id (RETIRED_SKILL_IDS)`);
+    }
+  }
+  const owner = new Map();
+  for (const id of known) {
+    let text;
+    try { text = readText(path.join(src, 'skills', `${id}.md`)); } catch { continue; }  // a folder skill
+    // `aliasesOf` reads the FIRST marker line only, so a second one would be dropped in silence.
+    if ((text.match(new RegExp(ALIASES_RE.source, 'gm')) || []).length > 1) {
+      problems.push(`[authoring] skills/${id}.md declares aliases on more than one line — merge them`);
+    }
+    for (const alias of aliasesOf(text)) {
+      const where = `skills/${id}.md alias '${alias}'`;
+      if (!/^[a-z0-9-]+$/.test(alias)) problems.push(`[authoring] ${where} is not [a-z0-9-]+`);
+      else if (known.includes(alias)) problems.push(`[authoring] ${where} is already a skill`);
+      else if (Object.hasOwn(RETIRED_SKILL_IDS, alias)) {
+        problems.push(`[authoring] ${where} is a retired skill id (RETIRED_SKILL_IDS)`);
+      } else if (reserved.has(alias)) problems.push(`[authoring] ${where} is an OpenCode command name`);
+      else if (owner.has(alias)) {
+        problems.push(`[authoring] ${where} is already declared by skills/${owner.get(alias)}.md`);
+      } else owner.set(alias, id);
+    }
+  }
+  return problems;
+}
+
+/**
+ * A first-party skill's side files (`src/skills/<name>/<file>.md`, emitted beside its SKILL.md
+ * and read only when the body points at them) keep the one layout every writer assumes: a flat
+ * `<name>.md` owns the folder, files sit one level down, each is `.md` (rendered and themed),
+ * none is `SKILL.md` (the emit writes that one), and the spec links every one as
+ * `[…](<name>/<file>)` — an unlinked side file ships to every install and is never read.
+ * Vendored folders are exempt: they carry their own SKILL.md and their own layout.
+ */
+export function sideFileProblems(src = SRC) {
+  const problems = [];
+  const dir = path.join(src, 'skills');
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory() || e.name.startsWith('_') || VENDORED_SKILL_DIRS.has(e.name)) continue;
+    const name = e.name;
+    let spec;
+    try { spec = readText(path.join(dir, `${name}.md`)); } catch {
+      problems.push(`[authoring] skills/${name}/ has no skills/${name}.md — a side-file folder `
+        + 'belongs to a flat spec (or list a folder skill in VENDORED_SKILL_DIRS)');
+      continue;
+    }
+    for (const f of readdirSync(path.join(dir, name), { withFileTypes: true })) {
+      const where = `skills/${name}/${f.name}`;
+      if (!f.isFile() || !f.name.endsWith('.md')) {
+        problems.push(`[authoring] ${where} — a side file is a .md one level down`);
+      } else if (f.name === 'SKILL.md') {
+        problems.push(`[authoring] ${where} collides with the SKILL.md the emit writes`);
+      } else if (!spec.includes(`](${name}/${f.name})`) && !spec.includes(`](${name}/${f.name}#`)) {
+        problems.push(`[authoring] ${where} is not linked from skills/${name}.md — `
+          + `link it as [${name}/${f.name}](${name}/${f.name}) or delete it`);
+      }
+    }
+  }
+  return problems.sort();
+}
+
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 
 /**
@@ -359,3 +442,84 @@ export function moduleMapProblems() {
   }
   return problems;
 }
+
+/**
+ * The AI Harness Scorecard checks this repo passes, written out — the ratchet's floor.
+ *
+ * Taken from `geneseed scorecard` on main after #209-#213 (security policy, PR template, ARCHITECTURE
+ * and ADRs, the audit and commitlint jobs, Dependabot, coverage, property tests, fuzzing): 26 of 31,
+ * 81.2/100, matching upstream's Python tool check for check. Then the weekly Stryker run and the
+ * offline link check added mutation_testing and stale_doc_detection: 28 of 31, 88.7 (A); the checkJs
+ * pass added type_safety (partial: `strict` is off): 29 of 31, 90.4; calling the web job's prettier and vitest
+ * directly (the scorecard reads only the root package.json's scripts) added formatter_enforcement
+ * and lifted test_suite_exists to 3 of 3: 30 of 31, 95.3. Grouped by pillar, in upstream order.
+ * The ratchet is on `passed`, which upstream sets for any score above zero: `type_safety`
+ * passes at 1.5 of 3, and a full check sliding to a partial one is
+ * invisible here. A check this repo starts to pass is added by hand; one it stops passing is a
+ * doctor problem until fixed or deliberately removed from this list, in the same commit.
+ */
+export const SCORECARD_FLOOR = [
+  'architecture_doc',
+  'agent_instructions',
+  'adr_presence',
+  'module_boundary_docs',
+  'ci_pipeline_exists',
+  'linter_enforcement',
+  'formatter_enforcement',
+  'type_safety',
+  'dependency_auditing',
+  'conventional_commits',
+  'unsafe_code_policy',
+  'test_suite_exists',
+  'feature_matrix_testing',
+  'coverage_measurement',
+  'mutation_testing',
+  'property_based_testing',
+  'fuzz_testing',
+  'contract_tests',
+  'tests_blocking_ci',
+  'code_review_required',
+  'scheduled_ci',
+  'stale_doc_detection',
+  'mr_template',
+  'automated_review',
+  'doc_sync_check',
+  'ai_usage_norms',
+  'small_batch_enforcement',
+  'multiple_approach_culture',
+  'error_handling_policy',
+  'security_critical_marking',
+];
+
+/**
+ * The scorecard ratchet — one problem per `SCORECARD_FLOOR` check that no longer passes.
+ *
+ * DEVELOPMENT CHECKOUT ONLY: it scores `.github/` (CI, CODEOWNERS, the PR template), and
+ * `.github/` is WITHHELD from the npm package (`tests/unit/package_manifest.test.mjs`), so an npm
+ * install would fail half the floor for files it was never meant to carry. A `.git` entry (a
+ * directory in a clone, a FILE in a worktree — hence `existsSync`, not `isDir`) plus
+ * `.github/workflows` is what only a checkout of this repository has. Anything else skips: [].
+ */
+export function scorecardProblems(root = ROOT) {
+  if (!existsSync(path.join(root, '.git')) || !isDir(path.join(root, '.github', 'workflows'))) return [];
+  const a = assessRepo(root);
+  const checks = new Map(a.categories.flatMap((c) => c.checks).map((k) => [k.id, k]));
+  // THE README CARD IS A RENDER OF THIS SAME ASSESSMENT, compared byte for byte: a card that no
+  // longer matches the score is the stale-number problem the badges have, caught the same way.
+  const card = path.join(root, ...SCORECARD_CARD.split('/'));
+  const stale = isFile(card) && readText(card) === renderSvg(a) ? [] : [
+    `[scorecard] ${SCORECARD_CARD} does not match the current score — run: geneseed scorecard --svg ${SCORECARD_CARD}`,
+  ];
+  const readme = path.join(root, 'README.md');
+  if (isFile(readme) && !readText(readme).includes(`(${badgeUrl(a)})`)) {
+    stale.push(`[scorecard] README.md's scorecard badge does not show the current score — set it to ${badgeUrl(a)}`);
+  }
+  return stale.concat(SCORECARD_FLOOR.filter((id) => !checks.get(id)?.passed).map((id) => {
+    const k = checks.get(id);
+    return `[scorecard] ${id} no longer passes — it is in SCORECARD_FLOOR (js/inspect/checks-repo.mjs)`
+      + (k ? `: ${k.evidence}. Fix: ${k.remediation}` : ', and the scorecard has no such check');
+  }));
+}
+
+/** Where the README's scorecard card lives, and what doctor compares against a fresh render. */
+export const SCORECARD_CARD = 'docs/assets/scorecard.svg';

package/js/inspect/diff.mjs

@@ -189,7 +189,10 @@ export function diffCollect({ target = null, theme = null, emit = null, footprin
     // reference render names the temp tree. Mapped back to the deployed dir before comparing,
     // or every such skill reads as edited. A deployment that has since MOVED still differs,
     // and that is real drift — its skills point at a directory that is no longer theirs.
+    // A side-file pointer (and a global OpenCode command's) spells the same directory
+    // `/`-separated, so that spelling is mapped too.
     const deployedDir = resolvePath(dir);
+    const posix = (p) => p.split(path.sep).join('/');
     const rels = [...new Set([...ownedSet(dir), ...ownedSet(expected)])].sort();
     for (const rel of rels) {
       const a = path.join(dir, rel);
@@ -198,7 +201,8 @@ export function diffCollect({ target = null, theme = null, emit = null, footprin
         // `read_text(errors="replace")` — Node's utf8 decoder substitutes U+FFFD for the
         // same bytes, and `readText` folds the line endings the way `Path.read_text` does.
         const ta = readText(a);
-        const tb = readText(b).split(expected).join(deployedDir);
+        const tb = readText(b).split(expected).join(deployedDir)
+          .split(posix(expected)).join(posix(deployedDir));
         if (cmpKey(rel, ta) !== cmpKey(rel, tb)) {
           const diff = unifiedDiff(splitLines(tb), splitLines(ta), {
             fromfile: `source/${rel}`, tofile: `deployed/${rel}`, lineterm: '',

package/js/inspect/doctor.mjs

@@ -40,7 +40,7 @@ import { authoringProblems, loopProblems } from './checks-authoring.mjs';
 import {
   checkBuild, colorThemeProblems, renderedProblems, themeParityProblems,
 } from './checks-build.mjs';
-import { moduleMapProblems, shimProblems } from './checks-repo.mjs';
+import { moduleMapProblems, scorecardProblems, shimProblems } from './checks-repo.mjs';
 import { isDoctorNote, sortedProblems, sortedUnique, stemOf, withTempDir } from './scan.mjs';
 
 /**
@@ -220,6 +220,7 @@ export function doctorCollect({
   problems = problems.concat(ran('loops', 'Loop catalogue', loopProblems()));
   problems = problems.concat(ran('shim', 'Hook shim', shimProbs));
   problems = problems.concat(ran('map', 'Module map', moduleMapProblems()));
+  problems = problems.concat(ran('scorecard', 'Scorecard floor', scorecardProblems()));
   // P10c's `cli` check is GONE, and the reason is not that it stopped mattering. It hashed
   // `rituals/harness.py` and compared that against a digest baked into `cli.json`, to catch a
   // parser edited without regenerating the table. P2 made the table the OWNED document

package/js/inspect/inventory.mjs

@@ -92,23 +92,21 @@ export const SKILL_CLASS = {
   brainstorm: 'design', plan: 'design', council: 'design',
   workflow: 'design', 'parallel-agents': 'design', pipeline: 'design',
   loop: 'design', 'brick-forge': 'design',
-  'codebase-design': 'design', 'domain-modeling': 'design', wayfinder: 'design',
-  tickets: 'design',
-  develop: 'build', refactor: 'build', debug: 'build', migrate: 'build',
-  'frontend-design': 'build', 'opencode-theme': 'build', prototype: 'build',
-  'forge-mcp': 'build', 'bruno-collection-generator': 'build', 'bruno-test-writer': 'build',
-  worktree: 'build', 'ci-fix': 'build', 'deps-audit': 'build',
+  'codebase-design': 'design', wayfinder: 'design',
+  develop: 'build', refactor: 'build', debug: 'build', dependencies: 'build',
+  'frontend-design': 'build', prototype: 'build',
+  'forge-mcp': 'build', bruno: 'build', worktree: 'build',
   'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'security-audit': 'review',
   'roast-me': 'review', 'review-response': 'review', ponytail: 'review',
-  commit: 'ship', ship: 'ship', release: 'ship', handoff: 'ship', 'git-rescue': 'ship',
-  'repo-map': 'understand', 'git-archaeology': 'understand',
+  commit: 'ship', ship: 'ship', release: 'ship', handoff: 'ship',
+  'git-history': 'understand',
   research: 'understand', ingest: 'understand', 'document-project': 'understand',
   prose: 'understand',
   // `harness` — skills about the agent's own apparatus (its harness, memory, rules,
   // knowledge base, terminal) rather than about the user's code. They sat under
   // `understand` before, which made that class a grab-bag.
   wiki: 'harness', geneseed: 'harness', rule: 'harness', profile: 'harness',
-  herdr: 'harness', 'skill-forge': 'harness', 'consolidate-memory': 'harness',
+  herdr: 'harness', 'skill-forge': 'harness',
   teach: 'learn', quiz: 'learn', 'learn-mode': 'learn',
 };