geneseed 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +2 -2
  4. package/adapters/opencode/README.md +7 -4
  5. package/docs/concepts/agents.md +8 -0
  6. package/docs/concepts/enforcement-table.md +1 -1
  7. package/docs/concepts/exclusions.md +1 -1
  8. package/docs/concepts/foreman-mode.md +5 -3
  9. package/docs/concepts/hooks.md +1 -1
  10. package/docs/concepts/kits.md +20 -2
  11. package/docs/concepts/loops.md +5 -0
  12. package/docs/concepts/skills.md +1 -1
  13. package/docs/concepts/superpowers-kit.md +79 -0
  14. package/docs/extending.md +11 -4
  15. package/docs/guides/install-scripted.md +1 -1
  16. package/docs/reference/cli.md +2 -0
  17. package/docs/reference/profiles.md +10 -5
  18. package/harness.config.json +1 -1
  19. package/js/README.md +2 -0
  20. package/js/build/args.mjs +4 -2
  21. package/js/build/driver.mjs +8 -8
  22. package/js/build/emit-claude.mjs +5 -3
  23. package/js/build/emit-opencode.mjs +2 -2
  24. package/js/build/generate.mjs +1 -1
  25. package/js/build/profile.mjs +15 -7
  26. package/js/build/render.mjs +81 -10
  27. package/js/build/source.mjs +75 -1
  28. package/js/cli-table.json +17 -2
  29. package/js/hosts/hooks.mjs +16 -5
  30. package/js/hosts/installs.mjs +50 -4
  31. package/js/hosts/native.mjs +104 -3
  32. package/js/hosts/opencode.mjs +13 -15
  33. package/js/inspect/checks-authoring.mjs +24 -1
  34. package/js/inspect/checks-build.mjs +43 -2
  35. package/js/inspect/checks-counts.mjs +72 -1
  36. package/js/inspect/diff.mjs +17 -3
  37. package/js/inspect/doctor.mjs +23 -2
  38. package/js/inspect/status.mjs +5 -1
  39. package/js/inspect/validate.mjs +1 -1
  40. package/js/loop/catalog.mjs +10 -0
  41. package/js/maintain/kit-migration.mjs +109 -0
  42. package/js/maintain/plugin-detect.mjs +150 -0
  43. package/js/maintain/profiles.mjs +46 -5
  44. package/js/maintain/setup.mjs +45 -11
  45. package/js/maintain/update.mjs +1 -1
  46. package/js/web/actions.mjs +28 -7
  47. package/js/web/api.mjs +3 -1
  48. package/js/web/profiles-api.mjs +11 -7
  49. package/package.json +1 -1
  50. package/profiles/autonomous.json +1 -0
  51. package/profiles/corporate.json +1 -1
  52. package/profiles/mentor.json +1 -0
  53. package/profiles/minimal.json +2 -1
  54. package/profiles/starter.json +1 -1
  55. package/src/AGENT.md.tmpl +1 -6
  56. package/src/agents/_template.md +4 -0
  57. package/src/agents/advocate.md +1 -0
  58. package/src/agents/architect.md +1 -0
  59. package/src/agents/developer.md +12 -4
  60. package/src/agents/empiricist.md +1 -0
  61. package/src/agents/explorer.md +1 -0
  62. package/src/agents/framer.md +1 -0
  63. package/src/agents/historian.md +1 -0
  64. package/src/agents/operator.md +1 -0
  65. package/src/agents/performance.md +2 -1
  66. package/src/agents/pragmatist.md +1 -0
  67. package/src/agents/react-reviewer.md +1 -0
  68. package/src/agents/researcher.md +1 -0
  69. package/src/agents/reviewer.md +1 -0
  70. package/src/agents/security.md +1 -0
  71. package/src/agents/skeptic.md +1 -0
  72. package/src/agents/spring-reviewer.md +1 -0
  73. package/src/agents/spring-security.md +1 -0
  74. package/src/agents/steward.md +1 -0
  75. package/src/agents/user-advocate.md +1 -0
  76. package/src/agents/visionary.md +1 -0
  77. package/src/bricks/ci-fix.md +12 -2
  78. package/src/kits/superpowers/missing.md +3 -0
  79. package/src/kits/superpowers/provider.md +7 -0
  80. package/src/kits/superpowers/rules.md +6 -0
  81. package/src/kits/superpowers.json +45 -0
  82. package/src/modes/foreman.md +18 -12
  83. package/src/skills/commit.md +4 -0
  84. package/src/skills/parallel-agents.md +2 -2
  85. package/src/skills/spring-boot/cloud.md +8 -2
  86. package/src/skills/spring-boot.md +3 -1
  87. package/src/skills/spring-testing.md +3 -3
  88. package/src/upstreams.json +1 -1
@@ -35,8 +35,8 @@ import { existsSync, readdirSync } from 'node:fs';
35
35
  import path from 'node:path';
36
36
 
37
37
  import {
38
- CONFIG, CONTEXT_WINDOWS, CONTEXT_WINDOW_MARKER, DEFAULT_CONTEXT_WINDOW, GATE_SWITCHES, PACK_ORDER,
39
- RETIRED_KIT_IDS, THEMES, discoverNames, loadKits, resolveSkillNames,
38
+ CONFIG, CONTEXT_WINDOWS, CONTEXT_WINDOW_MARKER, DEFAULT_CONTEXT_WINDOW, DEFAULT_TIERS, GATE_SWITCHES, PACK_ORDER,
39
+ RETIRED_KIT_IDS, TIERS_CHOICES, TIERS_MARKER, THEMES, WORKFLOW_PROVIDER_HEADING, discoverNames, linkedSkillIds, loadKits, resolveSkillNames,
40
40
  } from '../build/source.mjs';
41
41
  import {
42
42
  CARRIERS, CLAUDE_STYLE, DISABLED_STASH, GLOBAL_MANIFEST, HOSTS, SHARED_TIER_RE, carriersFor, gateCarrierText, isHostGlobalDir,
@@ -448,7 +448,13 @@ export function excludedSkillsOfDir(d, host = null, notify = null) {
448
448
  const { ids, notices, unknown } = resolveSkillNames(m[1].split(',').map((s) => s.trim()).filter(Boolean));
449
449
  if (unknown.length) return [];
450
450
  if (notify) for (const n of notices) notify(n);
451
- return ids;
451
+ // A skill some spec LINKS to became protected after the install was made (F1: relative links
452
+ // count): the flag would refuse the name and break every replay, and re-admitting a skill is
453
+ // the safe direction, so the exclusion is dropped with a notice, as an alias to a linked skill is.
454
+ const linked = ids.length ? linkedSkillIds() : [];
455
+ const kept = ids.filter((n) => !linked.includes(n));
456
+ if (notify) for (const n of ids.filter((x) => linked.includes(x))) notify(`'${n}' is linked to by another skill and cannot be excluded — exclusion dropped`);
457
+ return kept;
452
458
  }, [], host);
453
459
  }
454
460
 
@@ -480,6 +486,26 @@ export function kitsOfDir(d, host = null, notify = null) {
480
486
  }
481
487
 
482
488
 
489
+ /**
490
+ * Was this install built by a Geneseed that knows the `superpowers` kit? Read off the carrier: such
491
+ * a build writes either `Active kits: ... superpowers` or, with the kit off, the Workflow provider
492
+ * block (`WORKFLOW_PROVIDER_HEADING`). An older build writes neither. The migration of an install made
493
+ * before the kit (`js/maintain/kit-migration.mjs`) reads this beside the release the marker records,
494
+ * because a build made after the kit but before its release carries the old release number.
495
+ * `null` when there is no Geneseed carrier to read: nothing is installed there to migrate.
496
+ */
497
+ export function kitAwareOfDir(d, host = null) {
498
+ return firstCarrier(d, (carrierPath) => {
499
+ const text = readMaybe(carrierPath);
500
+ if (text === null) return undefined;
501
+ // A carrier with no `Active packs:` line is not one Geneseed rendered (a file the user wrote
502
+ // and the emit kept): there is nothing in it to migrate, so it reads like no carrier at all.
503
+ if (!/^Active packs:/m.test(text)) return undefined;
504
+ const line = KITS_RE.exec(text);
505
+ return new RegExp(`^${WORKFLOW_PROVIDER_HEADING}\\r?$`, 'm').test(text) || (line !== null && /(^|[ ,])superpowers\b/.test(line[1]));
506
+ }, null, host);
507
+ }
508
+
483
509
  /**
484
510
  * Whether a DEPLOYED install reads the shared tier (`--shared-tier on`), read back so `rebuild-all`,
485
511
  * `upgrade`, `diff`, the wizard and the console re-render it. A missing line is `false`: the default
@@ -512,6 +538,25 @@ export function contextWindowOfDir(d, host = null) {
512
538
  }, DEFAULT_CONTEXT_WINDOW, host);
513
539
  }
514
540
 
541
+ const TIERS_RE = new RegExp(`^${TIERS_MARKER}:[ \\t]*(\\S+?)[ \\t]*\\r?$`, 'm');
542
+
543
+ /**
544
+ * The sub-agent tier routing a DEPLOYED install was built with (`--tiers`), read back so
545
+ * `rebuild-all`, `upgrade`, `diff` and the guard re-render it. A missing line is the default
546
+ * (`off`): the marker is only ever written off it, so an install older than the option is a
547
+ * default install. A value this checkout does not know reads as the default too, so a
548
+ * hand-edited line can never reach `--tiers` and refuse a rebuild.
549
+ */
550
+ export function tiersOfDir(d, host = null) {
551
+ return firstCarrier(d, (carrierPath) => {
552
+ const text = readMaybe(carrierPath);
553
+ if (text === null) return undefined;
554
+ const m = TIERS_RE.exec(text);
555
+ if (!m) return undefined;
556
+ return TIERS_CHOICES.includes(m[1]) ? m[1] : DEFAULT_TIERS;
557
+ }, DEFAULT_TIERS, host);
558
+ }
559
+
515
560
  /**
516
561
  * Whether a DEPLOYED install keeps one law's hook gate armed — `true` (armed) or `false` (its
517
562
  * `<marker>: off` line, written by a build with that gate's `--no-*-gate` flag; `GATE_SWITCHES`).
@@ -853,7 +898,7 @@ export function installedDefaults() {
853
898
  const found = {
854
899
  theme: null, posture: null, mode: null, emit: null, footprint: null, doctrines: null,
855
900
  excludeRules: null, excludeSkills: null, kits: null, sharedTier: false,
856
- contextWindow: DEFAULT_CONTEXT_WINDOW,
901
+ contextWindow: DEFAULT_CONTEXT_WINDOW, tiers: DEFAULT_TIERS,
857
902
  };
858
903
  const candidates = [];
859
904
  for (const { host, configDir } of HOSTS) {
@@ -906,6 +951,7 @@ export function installedDefaults() {
906
951
  // Two states too: the default and no line read the same, so the first install that says
907
952
  // otherwise speaks.
908
953
  if (found.contextWindow === DEFAULT_CONTEXT_WINDOW) found.contextWindow = contextWindowOfDir(base);
954
+ if (found.tiers === DEFAULT_TIERS) found.tiers = tiersOfDir(base);
909
955
  }
910
956
  return found;
911
957
  }
@@ -302,6 +302,15 @@ export function stripSkillBodyLinks(body) {
302
302
  return body.replace(SKILL_BODY_LINK_RE, '$1');
303
303
  }
304
304
 
305
+ /**
306
+ * An agent's link to a SKILL (`../skills/debug.md`) resolves in the flat bundle and nowhere
307
+ * natively, where a skill is `skills/<name>/SKILL.md`. The link text stays; a skill body is
308
+ * de-linked the same way (`stripSkillBodyLinks`). Links to other agents stay: agents are flat.
309
+ */
310
+ export function stripAgentSkillLinks(body) {
311
+ return body.replace(/\[([^\]]+)\]\(\.\.\/skills\/[^)\s]*\.md(?:#[^)\s]*)?\)/g, '$1');
312
+ }
313
+
305
314
  /**
306
315
  * A first-party skill's SIDE FILES (`src/skills/<stem>/<file>`, beside the flat spec) are
307
316
  * linked from the spec as `[…](<stem>/<file>)` — the path that resolves in `src/` and in the
@@ -408,10 +417,12 @@ const WEBFETCH_MARKER = '<!-- webfetch: allow -->';
408
417
  * cannot name tools it has never seen, so a read-only agent in a session with such a server can
409
418
  * still write through it, until this becomes an allowlist (`tools:`).
410
419
  */
411
- function claudeAgentFrontmatter(stem, text, overrides) {
420
+ function claudeAgentFrontmatter(stem, text, overrides, tierModel = null) {
412
421
  const fm = [`name: ${stem}`, `description: ${jsonDumps(agentDescription(text))}`];
413
422
  const ov = agentOverride(overrides, stem);
423
+ // Precedence, highest first (spec D5): the user's pin, then the tier's model, then inherit.
414
424
  if (isTruthy(ov.model)) fm.push(`model: ${formatValue(ov.model)}`);
425
+ else if (tierModel) fm.push(`model: ${formatValue(tierModel)}`);
415
426
  if (isReadonly(text)) {
416
427
  const list = ['Write', 'Edit', 'NotebookEdit', 'Agent', 'Task'];
417
428
  if (!text.includes(WEBFETCH_MARKER)) list.push('WebFetch');
@@ -518,6 +529,90 @@ export function loadAgentOverrides(base) {
518
529
  return agents;
519
530
  }
520
531
 
532
+ /**
533
+ * What Claude Code's own aliases are called on a cloud provider: `sonnet` is only a model there
534
+ * once `ANTHROPIC_DEFAULT_SONNET_MODEL` says which one (Bedrock and Vertex have no default).
535
+ */
536
+ const CLAUDE_ALIAS_ENV = Object.freeze({
537
+ opus: 'ANTHROPIC_DEFAULT_OPUS_MODEL', sonnet: 'ANTHROPIC_DEFAULT_SONNET_MODEL',
538
+ haiku: 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
539
+ });
540
+ /** The model each non-strong tier gets on Claude Code when `tiers.<tier>` names none (spec D2). */
541
+ export const CLAUDE_TIER_DEFAULTS = Object.freeze({ standard: 'sonnet', light: 'haiku' });
542
+ /** The tier-map keys that take a model; `strong` is the parent's model and takes none (D9). */
543
+ const TIER_MAP_KEYS = ['standard', 'light'];
544
+
545
+ /** An env switch the way Claude Code reads it: set, and not spelled off. */
546
+ function envOn(env, name) {
547
+ const v = String(env[name] ?? '').trim().toLowerCase();
548
+ return v !== '' && v !== '0' && v !== 'false';
549
+ }
550
+
551
+ /**
552
+ * The model a tier gets on Claude Code, or null (inherit) — pure, so the table in
553
+ * `tests/unit/tiers.test.mjs` states every row. `map` is the user's `tiers` map
554
+ * (`loadTierMap`), `env` the environment.
555
+ *
556
+ * - `strong` never gets a line: it IS the parent's model.
557
+ * - A tier the map does not name gets the alias default (`CLAUDE_TIER_DEFAULTS`); a tier the map
558
+ * names with an empty value is the user choosing inherit.
559
+ * - D11 (revised 2026-11-17): the alias is ALWAYS written. On Bedrock or Vertex without
560
+ * `ANTHROPIC_DEFAULT_<ALIAS>_MODEL`, Claude Code resolves it to its built-in model id (seen on
561
+ * 2.1.326, Vertex: `haiku` -> claude-haiku-4-5@20251001, and the sub-agent runs), which may not
562
+ * exist in the user's cloud project. So `model` is unchanged and `warning` carries the advice to
563
+ * pin it; the doctor prints it (`tierEnvNotes`), the build says nothing. Only the three aliases
564
+ * are checked: any other value is a model id the user wrote and owns.
565
+ */
566
+ export function claudeTierModel(tier, map = {}, env = {}) {
567
+ if (!TIER_MAP_KEYS.includes(tier)) return { model: null, warning: null };
568
+ const named = Object.hasOwn(map, tier);
569
+ const value = named ? map[tier] : CLAUDE_TIER_DEFAULTS[tier];
570
+ if (!isTruthy(value)) return { model: null, warning: null };
571
+ const alias = String(value).trim().toLowerCase();
572
+ const cloud = ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX'].find((n) => envOn(env, n));
573
+ const need = Object.hasOwn(CLAUDE_ALIAS_ENV, alias) ? CLAUDE_ALIAS_ENV[alias] : null;
574
+ const warning = cloud && need && !String(env[need] ?? '').trim()
575
+ ? `--tiers auto: ${cloud} is set but ${need} is not, so the ${tier} tier's '${alias}' alias `
576
+ + `resolves to Claude Code's built-in model id, which may not exist in your cloud project — `
577
+ + `pin it: set ${need}`
578
+ : null;
579
+ return { model: String(value), warning };
580
+ }
581
+
582
+ /**
583
+ * The user's `tiers` map from `agent-overrides.json` (spec D9): `{ "standard": "<model>",
584
+ * "light": "<model>" }`. `strong` takes no value and is dropped with a notice, as is any other
585
+ * key; a value that would break the frontmatter is dropped like an `agents.*` one
586
+ * (`overrideProblem`). Missing or malformed file: `{}`, every tier on its default.
587
+ */
588
+ export function loadTierMap(base, report = warn) {
589
+ const file = path.join(base, 'agent-overrides.json');
590
+ let data;
591
+ try {
592
+ data = parseJson(readText(file));
593
+ } catch {
594
+ return {};
595
+ }
596
+ const tiers = isDict(data) ? data.tiers : null;
597
+ if (!isDict(tiers)) return {};
598
+ const out = {};
599
+ for (const [key, value] of Object.entries(tiers)) {
600
+ if (!TIER_MAP_KEYS.includes(key)) {
601
+ report(`[geneseed] WARN: ${file}: tiers.${key} is not a tier that takes a model `
602
+ + `(${TIER_MAP_KEYS.join(', ')}; strong is the parent's model) — skipped`);
603
+ continue;
604
+ }
605
+ if (value === null || value === undefined) continue;
606
+ const why = overrideProblem(value);
607
+ if (why) {
608
+ report(`[geneseed] WARN: ${file}: tiers.${key} ${why} — skipped`);
609
+ continue;
610
+ }
611
+ out[key] = value;
612
+ }
613
+ return out;
614
+ }
615
+
521
616
  /**
522
617
  * Warn once per override key the Claude dialect drops. The seeded `agent-overrides.json`
523
618
  * advertises all four keys on every host, and Claude Code's agent frontmatter takes `model`
@@ -690,10 +785,15 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
690
785
  // choice. The caller (`emit-claude.mjs`) routes the suppressed names through
691
786
  // `writeAliasCommands(..., alsoUserOnly: true)` into `.bob/commands/*.md` instead (O2).
692
787
  bobDialect = false,
788
+ // `--tiers auto` on Claude Code: `{ map, env }` (`loadTierMap`, the build env), else null — no tier line.
789
+ tiers = null,
693
790
  } = {}) {
694
791
  const ov = overrides || {};
695
792
  if (bobDialect) warnBobIgnored(ov);
696
793
  else if (host === 'claude') warnClaudeIgnored(ov);
794
+ // D11: the build never withholds the alias; the doctor warns about a cloud provider (`tierEnvNotes`).
795
+ const tierModelOf = (tier) => (!tiers || host !== 'claude' || bobDialect ? null
796
+ : claudeTierModel(tier, tiers.map, tiers.env).model);
697
797
  let nAgents = 0;
698
798
  let nSkills = 0;
699
799
  const written = [];
@@ -707,7 +807,7 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
707
807
  written.push(dest);
708
808
  };
709
809
 
710
- for (const { text, src: source, rel, licenceOf } of items) {
810
+ for (const { text, src: source, rel, licenceOf, tier = 'standard' } of items) {
711
811
  // A credited skill's upstream licence: copied verbatim beside its SKILL.md, held like a side
712
812
  // file until that claim holds. Routed by `licenceOf`, since `source` is the upstream's file.
713
813
  if (licenceOf) {
@@ -772,9 +872,10 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
772
872
  let userOnly = false;
773
873
  if (folder === 'agents') {
774
874
  if (bobDialect) fm = bobAgentFrontmatter(stem, text);
775
- else if (host === 'claude') fm = claudeAgentFrontmatter(stem, text, ov);
875
+ else if (host === 'claude') fm = claudeAgentFrontmatter(stem, text, ov, tierModelOf(tier));
776
876
  else fm = opencodeAgentFrontmatter(stem, text, ov, theme);
777
877
  dest = path.join(agentsDir, `${stem}.md`);
878
+ body = stripAgentSkillLinks(body);
778
879
  kind = 'agent';
779
880
  } else {
780
881
  // Skills are BYTE-IDENTICAL across hosts: name + description, body link-stripped.
@@ -27,7 +27,7 @@ import { writeText, readText, copyFile } from '../lib/fs.mjs';
27
27
  import { jsonDumps, jsonDumpsIndent, parseJson } from '../lib/json.mjs';
28
28
  import { comparePaths } from '../lib/paths.mjs';
29
29
  import { sourceReleaseVersion } from '../build/version.mjs';
30
- import { aliasesOf } from '../build/source.mjs';
30
+ import { aliasesOf, kitMembers, loadKits } from '../build/source.mjs';
31
31
  import { lstripNewlines } from './settings.mjs';
32
32
  import {
33
33
  firstBlockquote, isUserInvokedOnly, skillDescription, stripSkillBodyLinks, pointSideFiles,
@@ -83,23 +83,13 @@ const AGENT_OVERRIDES_STUB = {
83
83
  + 'steps (max tool-iterations — a runaway-loop cap). e.g. '
84
84
  + '"reviewer": {"model": "anthropic/claude-haiku-4-5", "temperature": 0.1, '
85
85
  + '"variant": "high", "steps": 20}. '
86
+ + 'Tiers (build with --tiers auto): "tiers": {"standard": "<model>", "light": "<model>"} '
87
+ + 'names the model each tier runs on; a tier you leave out gets its host default (Claude Code: '
88
+ + 'sonnet and haiku; other hosts inherit), an empty value means inherit, strong is always the session model. A '
89
+ + 'per-agent entry in "agents" wins over its tier. '
86
90
  + 'Host-specific; git-ignored. A future TUI screen edits this — rebuild to apply.'
87
91
  ),
88
92
  agents: {},
89
- // Inert: `loadAgentOverrides` reads `agents` only. This is the starting point the README
90
- // used to describe in prose — the seats whose work is read-and-summarise, where a smaller
91
- // model loses little and a council convenes 3–6 of them at once.
92
- _recommended: {
93
- _comment: (
94
- 'Cheap-tier seats: copy the ones you want into "agents" with your host\'s cheap '
95
- + 'model id (OpenCode: "anthropic/claude-haiku-4-5"; Claude Code: "haiku"). '
96
- + 'Read-and-summarise work — a council convenes several at once, so this is where '
97
- + 'the savings compound. Nothing applies until you copy it.'
98
- ),
99
- 'cheap-tier': ['explorer', 'researcher', 'tester', 'advocate', 'skeptic', 'pragmatist',
100
- 'steward', 'visionary', 'user-advocate', 'framer', 'empiricist', 'operator',
101
- 'historian'],
102
- },
103
93
  };
104
94
 
105
95
  /**
@@ -342,6 +332,12 @@ function writeCommandFile(dest, desc, body) {
342
332
  writeText(dest, `---\ndescription: ${jsonDumps(desc)}\n---\n\n${body}`);
343
333
  }
344
334
 
335
+ /** Every skill of a kit this build left OFF: not in `items`, and no error. */
336
+ function offKitSkills(cfg) {
337
+ const kits = loadKits(cfg.src);
338
+ return kitMembers(new Map([...kits].filter(([k]) => !(cfg.kits ?? []).includes(k)))).skills;
339
+ }
340
+
345
341
  /** `_build_emit._write_command_layer` — the opt-in /slash commands. */
346
342
  export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => true,
347
343
  skillDirOf = siblingSkillDir(commandDir)) {
@@ -352,6 +348,8 @@ export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => tru
352
348
  // A command runs a skill; `--exclude-skills` took that skill out, so the command goes too.
353
349
  if ((cfg.excludeSkills ?? []).includes(skill)) continue;
354
350
  const text = byName.get(skill);
351
+ // A skill of a kit that is off is not in `items`: its command goes with it, as for an exclusion.
352
+ if (text === undefined && offKitSkills(cfg).has(skill)) continue;
355
353
  if (text === undefined) {
356
354
  throw new Error(`COMMAND_SET: /${name} runs skill '${skill}', which src/skills/ does not have`);
357
355
  }
@@ -13,7 +13,7 @@
13
13
  * `node --check` over every OpenCode plugin. See `doctor.mjs` for what that allow-list costs.
14
14
  */
15
15
  import path from 'node:path';
16
- import { PLUGIN_SRC, SRC } from '../build/source.mjs';
16
+ import { PLUGIN_SRC, SRC, TIER_MARKER_RE } from '../build/source.mjs';
17
17
  import { HOSTS } from '../hosts/hosts.mjs';
18
18
  import { descBlockProblem, firstBlockquote } from '../hosts/native.mjs';
19
19
  import { readText } from '../lib/fs.mjs';
@@ -56,6 +56,7 @@ const ALLOWED_COMMENT_RES = [
56
56
  // js/web/docs.mjs HARNESS_OPEN_RE: `harness:` then one or more of its four ids, comma-separated.
57
57
  new RegExp(`^harness:\\s*(?:${HARNESS_IDS})(?:\\s*,\\s*(?:${HARNESS_IDS}))*$`),
58
58
  /^bash:\s*allow$/, // js/hosts/native.mjs BASH_MARKER
59
+ /^tier:\s*(strong|light)$/, // js/build/source.mjs TIER_MARKER_RE
59
60
  /^banned: ok$/, // checks-counts.mjs kitProblems: a kit line that names a banned string
60
61
  ];
61
62
 
@@ -146,6 +147,26 @@ export function factoryProblems(opts = {}) {
146
147
  * registry describes exactly what `src/` provides, no credential ships, and every vendored
147
148
  * folder carries an immutable upstream pin.
148
149
  */
150
+ /**
151
+ * The tier marker's shape in one agent spec, or '' when it holds. The build strips the whole line
152
+ * (`splitTier`), and that leaves the pre-marker text byte for byte only because the marker sits on
153
+ * a line of its own DIRECTLY ABOVE `## When to dispatch`; one anywhere else, twice, or naming a
154
+ * tier that does not exist would ship as live text or move a heading.
155
+ */
156
+ export function tierMarkerProblem(text) {
157
+ const lines = text.split(/\r?\n/);
158
+ const at = lines.map((l, i) => (/^\s*<!--\s*tier:/.test(l) ? i : -1)).filter((i) => i >= 0);
159
+ if (!at.length) return '';
160
+ if (at.length > 1) return 'has more than one tier marker';
161
+ if (!TIER_MARKER_RE.test(`${lines[at[0]]}\n`)) {
162
+ return `the tier marker '${lines[at[0]].trim()}' is not '<!-- tier: strong|light -->' on a line of its own`;
163
+ }
164
+ if (lines[at[0] + 1] !== '## When to dispatch') {
165
+ return "the tier marker is not directly above '## When to dispatch' (the line the build strips must leave the text unchanged)";
166
+ }
167
+ return '';
168
+ }
169
+
149
170
  export function authoringProblems() {
150
171
  const problems = [];
151
172
  for (const folder of ['agents', 'skills']) {
@@ -157,6 +178,8 @@ export function authoringProblems() {
157
178
  problems.push(`[authoring] ${folder}/${path.basename(spec)} unreadable: ${e.message}`);
158
179
  continue;
159
180
  }
181
+ const tierWhy = folder === 'agents' ? tierMarkerProblem(text) : '';
182
+ if (tierWhy) problems.push(`[authoring] agents/${path.basename(spec)}: ${tierWhy}`);
160
183
  if (!firstBlockquote(text)) {
161
184
  problems.push(`[authoring] ${folder}/${path.basename(spec)} has no '>' purpose line `
162
185
  + '(its OpenCode description would render empty)');
@@ -11,8 +11,10 @@ import { stripCapabilityLinks } from '../build/emit-common.mjs';
11
11
  import { STRUCTURE, renderAll } from '../build/render.mjs';
12
12
  import { CONFIG, CREDIT_RE, DESCRIPTION_LIMIT, makeCfg } from '../build/source.mjs';
13
13
  import { CLAUDE_STYLE, HOSTS, hostCatalogsNatively, resolvePath } from '../hosts/hosts.mjs';
14
- import { EMIT_HOST_SCOPE, footprintOfDir, readMaybe, renderedTier, themeFiles } from '../hosts/installs.mjs';
15
- import { isVendoredPath } from '../hosts/native.mjs';
14
+ import {
15
+ EMIT_HOST_SCOPE, footprintOfDir, installState, installTargets, readMaybe, renderedTier, themeFiles, tiersOfDir,
16
+ } from '../hosts/installs.mjs';
17
+ import { claudeTierModel, isVendoredPath, loadAgentOverrides, loadTierMap } from '../hosts/native.mjs';
16
18
  import { PALETTE_ROLES, colorThemeFiles } from '../hosts/opencode.mjs';
17
19
  import { readText, withDiscardableStderr } from '../lib/fs.mjs';
18
20
  import { parseJson, formatRepr } from '../lib/json.mjs';
@@ -229,6 +231,45 @@ export function renderedPathNotes() {
229
231
  return notes;
230
232
  }
231
233
 
234
+ /**
235
+ * Each Claude Code install, global or project, built `--tiers auto` whose tier alias cannot
236
+ * resolve in this process's environment (spec D11, revised): a Bedrock or Vertex provider with no
237
+ * `ANTHROPIC_DEFAULT_<ALIAS>_MODEL`. The build wrote the alias anyway, and Claude Code resolves it
238
+ * to its built-in model id, which may not exist in the user's cloud project; this names the
239
+ * variable to pin. A tier is skipped when every agent of it carries its own `agents.<name>.model`
240
+ * pin, since no alias is then in play. A NOTE, not a problem: nothing is known to be broken.
241
+ * `env` is a parameter so a test plants the provider without touching the real one.
242
+ *
243
+ * Which installs: `installTargets()` (the cwd, the registered project roots and every host's
244
+ * global dir), each read at its own overrides dir: the config dir itself for a global install,
245
+ * `<root>/.claude` for a project one (where the emit read the map from).
246
+ */
247
+ export function tierEnvNotes(env = process.env) {
248
+ const notes = [];
249
+ let agents = null; // the agent stems of each tier, rendered once, only when an install needs it
250
+ for (const [host, scope, root] of installTargets()) {
251
+ if (host !== 'claude' || installState(root, host, scope) !== 'active') continue;
252
+ if (tiersOfDir(root, host) !== 'auto') continue;
253
+ const dir = scope === 'global' ? root : path.join(root, '.claude');
254
+ const map = loadTierMap(dir, () => {});
255
+ const pins = loadAgentOverrides(dir);
256
+ if (agents === null) {
257
+ agents = { standard: [], light: [] };
258
+ for (const { rel, tier = 'standard' } of renderAll(makeCfg(), 'neutral').items) {
259
+ const m = /^agents\/([^_/][^/]*)\.md$/.exec(rel);
260
+ if (m && agents[tier]) agents[tier].push(m[1]);
261
+ }
262
+ }
263
+ for (const tier of ['standard', 'light']) {
264
+ if (agents[tier].every((stem) => Object.hasOwn(pins, stem) && pins[stem]?.model)) continue;
265
+ const { warning } = claudeTierModel(tier, map, env);
266
+ const where = scope === 'global' ? host : `${host} (project ${root})`;
267
+ if (warning) notes.push(`${NOTE}[tiers] ${where}: ${warning}`);
268
+ }
269
+ }
270
+ return notes;
271
+ }
272
+
232
273
  /**
233
274
  * A committed bundle must match a fresh render of
234
275
  * `src/` for its OWN recorded theme, emit and footprint.
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import path from 'node:path';
10
10
  import {
11
- DOCS, DOC_FOLDERS, PLUGIN_SRC, RETIRED_KIT_IDS, ROOT, SRC, kitMembers, loadKits, makeCfg, ruleCanon, specLinks, upstreams,
11
+ DOCS, DOC_FOLDERS, PLUGIN_SRC, RETIRED_KIT_IDS, ROOT, SRC, kitMembers, linkTargetOf, loadKits, makeCfg, ruleCanon, specLinks, upstreams,
12
12
  } from '../build/source.mjs';
13
13
  import { effectiveTheme, renderFile } from '../build/render.mjs';
14
14
  import { themeFiles } from '../hosts/installs.mjs';
@@ -375,6 +375,7 @@ export function kitProblems(src = SRC) {
375
375
  if (words > budget) {
376
376
  problems.push(`[authoring] src/${m.rules} renders to ${words} words, over kit '${kit}' rulesWordBudget of ${budget}`);
377
377
  }
378
+ if (m.replacedBy) problems.push(...replacedByProblems(src, kit, m, cfg, theme, budget));
378
379
  }
379
380
  // R4. A core member (R3, named above) is left out: every core file linking it would repeat that.
380
381
  const r4 = new Set();
@@ -382,10 +383,80 @@ export function kitProblems(src = SRC) {
382
383
  // Links run kit -> core only: a core file, or ANOTHER kit's file, linking a member dangles
383
384
  // whenever that member's kit is off.
384
385
  if (!l.owner || l.kit === l.owner || core[l.kind].has(l.name)) continue;
386
+ // `replacedBy` is the one exception: the render rewrites a link to such a member when its kit is off.
387
+ // ...and only where the rewrite resolves the link (`linkTargetOf`), the same function it runs.
388
+ if (l.kind === 'skills' && kits.get(l.owner)?.replacedBy && !l.kit && linkTargetOf(l.rel, `{{DIR_SKILLS}}/${l.name}.md`)) continue;
385
389
  r4.add(l.kit
386
390
  ? `[authoring] src/${l.rel} (kit '${l.kit}') links ${l.kind}/${l.name}, a member of kit '${l.owner}' — links run kit → core only`
387
391
  : `[authoring] src/${l.rel} links ${l.kind}/${l.name}, a kit member — the link dangles when the kit is off`);
388
392
  }
389
393
  problems.push(...r4);
394
+ problems.push(...bareMentionProblems(src, kits));
390
395
  return problems;
391
396
  }
397
+
398
+ /**
399
+ * A kit's `replacedBy` (spec 2): a plugin skill for EVERY member and for nothing else, an upstream
400
+ * key `src/upstreams.json` holds, a spelling per host that carries `{name}`, and the two blocks
401
+ * the render leaves behind with the kit off (`provider`, `missing`), each inside the word budget.
402
+ */
403
+ function replacedByProblems(src, kit, m, cfg, theme, budget) {
404
+ const at = `src/kits/${kit}.json`;
405
+ const r = m.replacedBy;
406
+ const out = [];
407
+ let keys = [];
408
+ try { keys = Object.keys(upstreams()); } catch { /* creditProblems names a bad upstreams.json */ }
409
+ if (!keys.includes(r.upstream)) out.push(`[authoring] ${at}: replacedBy.upstream '${r.upstream}' is not a key of src/upstreams.json`);
410
+ for (const s of m.skills) {
411
+ if (typeof r.skills[s] !== 'string' || !r.skills[s]) out.push(`[authoring] ${at}: replacedBy.skills has no plugin skill for member '${s}'`);
412
+ }
413
+ if (r.plain !== undefined) {
414
+ for (const s of m.skills) {
415
+ if (typeof r.plain[s] !== 'string' || !r.plain[s]) out.push(`[authoring] ${at}: replacedBy.plain has no wording for member '${s}'`);
416
+ }
417
+ }
418
+ for (const s of Object.keys(r.skills)) {
419
+ if (!m.skills.includes(s)) out.push(`[authoring] ${at}: replacedBy.skills names '${s}', which is not a skill of kit '${kit}'`);
420
+ }
421
+ for (const [host, tpl] of Object.entries(r.hosts)) {
422
+ if (typeof tpl !== 'string' || !tpl.includes('{name}')) out.push(`[authoring] ${at}: replacedBy.hosts.${host} must be a spelling with {name}`);
423
+ }
424
+ for (const field of ['provider', 'missing']) {
425
+ const f = r[field];
426
+ if (typeof f !== 'string' || !isFile(path.join(src, f))) {
427
+ out.push(`[authoring] ${at}: replacedBy.${field} must name a file under src/`);
428
+ continue;
429
+ }
430
+ const words = renderFile(cfg, path.join(src, f), theme).split(/\s+/).filter(Boolean).length;
431
+ if (words > budget) out.push(`[authoring] src/${f} renders to ${words} words, over kit '${kit}' rulesWordBudget of ${budget}`);
432
+ }
433
+ return out;
434
+ }
435
+
436
+ /**
437
+ * A member of a kit with `replacedBy` named in prose, with no link: the kit-off rewrite only sees
438
+ * links, so the name would ship as a Rite the install does not have. Refused in core specs:
439
+ * `<member> {{SKILL}}` or a backticked `member` outside a link label. Turn the mention into a link.
440
+ */
441
+ function bareMentionProblems(src, kits) {
442
+ const names = [...kits.values()].filter((k) => k.replacedBy).flatMap((k) => k.skills);
443
+ if (!names.length) return [];
444
+ const owned = new Set([...kits.values()].flatMap((k) => [...k.skills, ...k.agents]));
445
+ const alt = names.join('|');
446
+ const re = new RegExp(`(?<![\\[\\x60/-])(?:\\b(?:${alt}) \\{\\{SKILL\\}\\}|\\x60(?:${alt})\\x60 (?:skill|\\{\\{SKILL\\}\\}))`);
447
+ const out = [];
448
+ // Every folder that renders into an install, not only skills/ and agents/ (the rewrite reads them all).
449
+ for (const dir of ['skills', 'agents', 'laws', 'doctrines', 'modes', 'postures', 'ontology', '.']) {
450
+ for (const f of mdIn(path.join(src, dir)).concat(dir === '.' ? ['AGENT.md.tmpl'] : [])) {
451
+ if (dir !== '.' && (owned.has(f.slice(0, -3)) || f.startsWith('_'))) continue;
452
+ const rel = dir === '.' ? f : `${dir}/${f}`;
453
+ if (!isFile(path.join(src, rel))) continue;
454
+ readText(path.join(src, rel)).split('\n').forEach((line, i) => {
455
+ if (re.test(line.replace(/\[[^\]]*\]\([^)]*\)/g, ''))) {
456
+ out.push(`[authoring] src/${rel}:${i + 1} names a superpowers-kit skill without a link, so the kit-off rewrite cannot see it`);
457
+ }
458
+ });
459
+ }
460
+ }
461
+ return out;
462
+ }
@@ -40,7 +40,7 @@ import {
40
40
  } from '../hosts/hosts.mjs';
41
41
  import {
42
42
  EMIT_HOST_SCOPE, defaultTheme, doctrinesForBuild, excludedRulesOfDir,
43
- contextWindowOfDir, excludedSkillsOfDir, gatesOfDir, kitsOfDir, sharedTierOfDir,
43
+ contextWindowOfDir, excludedSkillsOfDir, gatesOfDir, sharedTierOfDir, tiersOfDir,
44
44
  footprintOfDir, modeOfDir, postureOfDir,
45
45
  trustOfDir,
46
46
  readJsonMaybe, readMaybe, renderedTier, themeOfDir,
@@ -53,6 +53,7 @@ import { NOTES_DIRS, sharedPaths } from '../lib/machine-dir.mjs';
53
53
  import { normcase, toPlatformPath } from '../lib/paths.mjs';
54
54
  import { projectNotesDir } from '../hosts/spec-feedback.mjs';
55
55
  import { relPosix } from '../lib/text.mjs';
56
+ import { migratedKitsOfDir } from '../maintain/kit-migration.mjs';
56
57
 
57
58
  /**
58
59
  * This process's start, in epoch seconds.
@@ -129,11 +130,19 @@ const posixRel = (rel) => rel.split('\\').join('/');
129
130
  * is its name, which the texts still spell (`locatedAt`).
130
131
  */
131
132
  function renderExpected(host, axes) {
133
+ const { overridesText = null, ...renderAxes } = axes;
132
134
  const tmp = mkdtempSync(path.join(os.tmpdir(), 'geneseed-diff-'));
133
135
  try {
134
136
  const expected = path.join(tmp, 'expected');
137
+ // The deployed `agent-overrides.json`, seeded BEFORE the emit: the emit reads the user's per-agent
138
+ // pins and `tiers` map out of the config dir it writes, so a render without it states every
139
+ // map- or pin-driven `model:` line as drift, and a restore would write the default over it.
140
+ if (overridesText !== null) {
141
+ mkdirSync(expected, { recursive: true });
142
+ writeText(path.join(expected, 'agent-overrides.json'), overridesText);
143
+ }
135
144
  withStdoutSwallowed(() => emitGlobalInto(host, {
136
- ...axes, out: path.join(tmp, 'bundle'), cfgDir: expected,
145
+ ...renderAxes, out: path.join(tmp, 'bundle'), cfgDir: expected,
137
146
  }));
138
147
  const texts = new Map();
139
148
  for (const p of rglobFiles(expected)) texts.set(relPosix(expected, p), readText(p));
@@ -264,11 +273,16 @@ export function diffCollect({
264
273
  // The excluded skills, or every skill the install left out reads as deleted.
265
274
  excludeSkills: excludedSkillsOfDir(dir, host),
266
275
  // The kits on, or every kit file reads as added and the Kits block as drift.
267
- kits: kitsOfDir(dir, host),
276
+ kits: migratedKitsOfDir(dir, host),
268
277
  // The shared-tier marker, or an install built `--shared-tier on` reads its `Shared tier: on` line as drift.
269
278
  sharedTier: sharedTierOfDir(dir, host),
270
279
  // The context window, or a `1m` install reads its `Context window: 1m` line as drift.
271
280
  contextWindow: contextWindowOfDir(dir, host),
281
+ // The tier routing, or an install built `--tiers auto` reads its `Model tiers: auto` line and every tiered agent as drift.
282
+ tiers: tiersOfDir(dir, host),
283
+ // The user's own overrides file (pins and the tiers map): a render input like every axis above, so it is
284
+ // part of the memo key, and `null` (no file) leaves the emit to seed its stub as before.
285
+ overridesText: readMaybe(path.join(dir, 'agent-overrides.json')),
272
286
  // The gate switches, or a disarmed install reads its `<gate>: off` line as drift.
273
287
  ...gatesOfDir(dir, host),
274
288
  // The tier root it rendered, or an install left relative reads every file as behind source.
@@ -35,14 +35,16 @@ import { emitGlobalInto, emitProjectInto, main as driverMain } from '../build/dr
35
35
  import { ROOT } from '../build/source.mjs';
36
36
  import { CLAUDE_STYLE, opencodeShadowedInstall, resolvePath } from '../hosts/hosts.mjs';
37
37
  import {
38
- hookShellProblems, installedDefaults, openclaudeDualHarnessRoots, themeFiles,
38
+ hookShellProblems, installTargets, installedDefaults, openclaudeDualHarnessRoots, themeFiles,
39
39
  } from '../hosts/installs.mjs';
40
+ import { installProfile } from '../build/profile.mjs';
41
+ import { providerWarning } from '../maintain/kit-migration.mjs';
40
42
  import { validateIsVendored } from '../hosts/native.mjs';
41
43
  import { printErr, printOut } from '../lib/fs.mjs';
42
44
  import { authoringProblems, factoryProblems, loopProblems } from './checks-authoring.mjs';
43
45
  import { gateProbe, guardProbe } from './checks-probe.mjs';
44
46
  import {
45
- checkBuild, colorThemeProblems, renderedPathNotes, renderedProblems, themeParityProblems,
47
+ checkBuild, colorThemeProblems, renderedPathNotes, renderedProblems, themeParityProblems, tierEnvNotes,
46
48
  } from './checks-build.mjs';
47
49
  import {
48
50
  bobBlockProblems, hostMatrixProblems, localNoteProblems, moduleMapProblems, scorecardProblems,
@@ -78,6 +80,23 @@ export function openclaudeDualHarnessNotes() {
78
80
  + 'longer use if this was not intended');
79
81
  }
80
82
 
83
+ /**
84
+ * The workflow-provider WARN per install (`providerWarning`): the superpowers kit and the official
85
+ * plugin both on, or neither. A NOTE, never a problem: either is a legal configuration its owner
86
+ * may have chosen, and doctor must not fail on it. Read from files only, and never on the hook path.
87
+ */
88
+ export function providerNotes() {
89
+ const out = [];
90
+ for (const [host, scope, root] of installTargets()) {
91
+ let p;
92
+ try { p = installProfile(host, scope, root); } catch { continue; }
93
+ if (p.state === 'absent') continue;
94
+ const w = providerWarning({ host, scope, root, kits: p.kits });
95
+ if (w) out.push(`${NOTE}[superpowers] ${host}:${scope} — ${w}`);
96
+ }
97
+ return out;
98
+ }
99
+
81
100
  /**
82
101
  * `swallowStdout` and `captureBoth` below are the same operation over a different stream
83
102
  * list: replace each stream's `write` with a no-op for the duration of `fn`, then restore
@@ -269,6 +288,8 @@ export function doctorCollect({
269
288
  problems = problems.concat(ran('openclaude_dual', 'OpenClaude dual harness',
270
289
  openclaudeDualHarnessNotes()));
271
290
  problems = problems.concat(ran('shared_paths', 'Rendered shared paths', renderedPathNotes()));
291
+ problems = problems.concat(ran('providers', 'Workflow provider', providerNotes()));
292
+ problems = problems.concat(ran('tier_env', 'Model tier aliases', tierEnvNotes()));
272
293
  problems = problems.concat(ran('map', 'Module map', moduleMapProblems()));
273
294
  problems = problems.concat(ran('host_matrix', 'Host tables', hostMatrixProblems()));
274
295
  problems = problems.concat(ran('host_claims', 'Host claims',