@fro.bot/systematic 2.9.2 → 2.11.0

package/README.md

@@ -326,11 +326,54 @@ Configuration is loaded from multiple locations and merged (later sources overri
 | `bootstrap.enabled` | `boolean` | `true` | Inject the `using-systematic` guide into system prompts |
 | `bootstrap.file` | `string` | — | Custom bootstrap file path (overrides default) |
 
-Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `color` accepts `#RGB`, `#RRGGBB`, or OpenCode named color tokens matching `[a-zA-Z][a-zA-Z0-9-]*`; whitespace/freeform numeric strings are rejected. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `model` controls provider routing/cost/privacy and `permission`/`skills` control tool access, those fields are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`. Project config may tune non-sensitive presentation and runtime fields such as `variant`, `temperature`, `top_p`, `mode`, `color`, `steps`, `hidden`, or exact-agent `disable`, but it cannot choose model/provider routing or loosen permission/capability policy.
-
-Systematic separates config-source precedence from overlay precedence. Config files merge in this order: user config, project config, then `$OPENCODE_CONFIG_DIR/systematic.json` if set. Higher-priority `agents.<key>` and `categories.<id>` entries replace lower-priority entries wholesale, while unrelated keys survive. Project overlays are the exception for trust-sensitive fields: same-key project overlays preserve user-level `model`, `permission`, and `skills` fields instead of erasing them. After the effective config is built, exact `agents` overlays beat category overlays, which beat built-in policy defaults, bundled markdown defaults, and OpenCode inherited defaults.
-
-Bundled agents omit `model` by default so OpenCode model inheritance keeps working. Systematic emits a `model` only when you configure one explicitly in user or custom config; provider-specific zero-config model defaults are intentionally deferred.
+Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `color` accepts `#RGB`, `#RRGGBB`, or OpenCode named color tokens matching `[a-zA-Z][a-zA-Z0-9-]*`; whitespace/freeform numeric strings are rejected. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `model` and `variant` control provider routing/cost/privacy and `permission`/`skills` control tool access, those fields are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`. Project config may tune non-sensitive presentation and runtime fields such as `temperature`, `top_p`, `mode`, `color`, `steps`, `hidden`, or exact-agent `disable`, but it cannot choose model/provider routing, tune `variant`, or loosen permission/capability policy.
+
+Systematic separates config-source precedence from overlay precedence. Config files merge in this order: user config, project config, then `$OPENCODE_CONFIG_DIR/systematic.json` if set. Higher-priority `agents.<key>` and `categories.<id>` entries replace lower-priority entries wholesale, while unrelated keys survive. Project overlays are the exception for trust-sensitive fields: same-key project overlays preserve user-level `model`, `variant`, `permission`, and `skills` fields instead of erasing them. After the effective config is built, Systematic applies agent overlay precedence for bundled agents:
+
+1. Exact `agents.<key>` overlay (high-trust `model` wins)
+2. `categories.<category-id>` overlay (high-trust `model` wins)
+3. Source category model default (built-in, code-owned)
+4. Bundled markdown/frontmatter defaults
+5. OpenCode inherited defaults
+
+Source category model defaults are primary model choices only — they are not fallback chains. Systematic does not support `fallback_models`, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.
+
+Source category model defaults are now ordered preference arrays per category rather than single strings. At plugin load, Systematic reads OpenCode's authentication state from `auth.json` and selects the first array entry whose provider is authenticated. For example, the `review` category defaults to `['anthropic/claude-opus-4.7', 'openai/gpt-5.5']` — a user authenticated only to OpenAI receives `openai/gpt-5.5` (first match), while a user authenticated to Anthropic (or both) receives the more preferred `anthropic/claude-opus-4.7`. If no array entry's provider is authenticated, the first entry is used as the default. The arrays are an ordered preference list, not a runtime fallback chain — `fallback_models` is still not supported.
+
+If you want to restore OpenCode parent-model inheritance for a bundled agent or category (opting out of the source default), set `"model": null` in high-trust user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot use `model: null` — project config cannot set, erase, or shadow `model` at any value.
+
+The source defaults are:
+
+| Category | Default `model` | Rationale |
+|----------|-----------------|-----------|
+| `design` | `openai/gpt-5.5` | High-judgment UX/product/design work benefits from a strong general reasoning model. |
+| `docs` | `openai/gpt-5.4-mini` | Documentation and summarization should start cheaper/faster. |
+| `document-review` | `anthropic/claude-opus-4.7` | Requirements and plan critique benefit from strongest nuanced reasoning. |
+| `research` | `openai/gpt-5.5` | Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model. |
+| `review` | `anthropic/claude-opus-4.7` | Code/security/adversarial review benefits from strongest reasoning. |
+| `workflow` | `openai/gpt-5.4-mini` | Orchestration and bounded implementation should default cheaper/faster. |
+
+These defaults are owned by Systematic code and emitted for bundled agents in each category when no stronger high-trust exact or category `model` override exists. Uncategorized bundled agents receive no source default and continue inheriting the parent OpenCode model. Native OpenCode agents with the same emitted key are full replacements and receive no Systematic source model default.
+
+Bundled agent markdown still intentionally omits `model` — the field belongs in source code defaults, not portable markdown files. Authors must not add `model:` frontmatter to bundled agent files.
+
+Systematic emits a source model as the default; you can override it per-agent or per-category in user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot set, erase, or shadow `model` policy.
+
+> **Migration: Restoring parent-model inheritance.** If you previously relied on bundled agents inheriting the parent OpenCode model (no source defaults), set `"model": null` in your high-trust config to opt out of the source default per agent or per category. For example:
+>
+> ```jsonc
+> // ~/.config/opencode/systematic.json or $OPENCODE_CONFIG_DIR/systematic.json
+> {
+>   "categories": {
+>     "review": { "model": null }     // All review agents inherit parent model
+>   },
+>   "agents": {
+>     "security-sentinel": { "model": null }  // Single agent inherits parent model
+>   }
+> }
+> ```
+>
+> This only works from high-trust config (user or `$OPENCODE_CONFIG_DIR/systematic.json`). Project `.opencode/systematic.json` cannot set `model: null` or any `model` value.
 
 Native OpenCode agents with the same emitted key are full replacements. An exact Systematic overlay for that key conflicts, while category overlays skip native replacements and continue applying to other bundled agents. Use one canonical agent key form across config sources (`security-sentinel` or `review/security-sentinel`) because alias collisions fail duplicate-target validation.
 

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-d5ewqz8w.js";
+} from "./index-mfy9dbdx.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-d5ewqz8w.js → index-mfy9dbdx.js}

@@ -856,7 +856,12 @@ var DEFAULT_CONFIG = {
   agents: {},
   categories: {}
 };
-var SECURITY_OVERLAY_FIELDS = new Set(["model", "permission", "skills"]);
+var SECURITY_OVERLAY_FIELDS = new Set([
+  "model",
+  "variant",
+  "permission",
+  "skills"
+]);
 function isErrorWithCode(error) {
   return error instanceof Error && "code" in error;
 }

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-d5ewqz8w.js";
+} from "./index-mfy9dbdx.js";
 
 // src/index.ts
 import fs4 from "fs";
@@ -78,7 +78,16 @@ ${toolMapping}
 
 // src/lib/agent-overlays.ts
 import fs2 from "fs";
+import os2 from "os";
 import path2 from "path";
+var SOURCE_CATEGORY_MODEL_DEFAULTS = {
+  design: ["openai/gpt-5.5", "anthropic/claude-opus-4.7"],
+  docs: ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"],
+  "document-review": ["anthropic/claude-opus-4.7", "openai/gpt-5.5"],
+  research: ["openai/gpt-5.5", "anthropic/claude-opus-4.7"],
+  review: ["anthropic/claude-opus-4.7", "openai/gpt-5.5"],
+  workflow: ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
+};
 var ALLOWED_OVERLAY_FIELDS = new Set([
   "model",
   "variant",
@@ -158,6 +167,72 @@ function inferBuiltInTemperature(name, description) {
   }
   return 0.3;
 }
+function getAuthenticatedProviders(rootDirOverride) {
+  const xdgDataHome = process.env.XDG_DATA_HOME?.trim();
+  const rootDir = rootDirOverride || (xdgDataHome && path2.isAbsolute(xdgDataHome) ? xdgDataHome : path2.join(os2.homedir(), ".local/share"));
+  const authPath = path2.join(rootDir, "opencode", "auth.json");
+  let raw;
+  try {
+    raw = fs2.readFileSync(authPath, "utf8");
+  } catch (err) {
+    if (isSystemError(err) && err.code === "ENOENT") {
+      return new Set;
+    }
+    console.warn(`[systematic] auth.json unreadable at ${authPath}; ignoring`);
+    return new Set;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`);
+    return new Set;
+  }
+  if (!isRecord(parsed)) {
+    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`);
+    return new Set;
+  }
+  return new Set(Object.keys(parsed));
+}
+function getSourceCategoryModel(category, authedProviders) {
+  if (!category)
+    return;
+  const candidates = SOURCE_CATEGORY_MODEL_DEFAULTS[category];
+  if (!candidates || candidates.length === 0)
+    return;
+  if (!authedProviders || authedProviders.size === 0)
+    return candidates[0];
+  for (const entry of candidates) {
+    const slashIndex = entry.indexOf("/");
+    if (slashIndex <= 0)
+      continue;
+    const providerId = entry.slice(0, slashIndex);
+    if (authedProviders.has(providerId)) {
+      return entry;
+    }
+  }
+  return candidates[0];
+}
+function assertSourceCategoryModelCoverage(categories) {
+  validateSourceCategoryModelDefaults();
+  const missingCategories = categories.filter((category) => !Object.hasOwn(SOURCE_CATEGORY_MODEL_DEFAULTS, category));
+  if (missingCategories.length > 0) {
+    throw new Error(`Source category model defaults missing intentional coverage for: ${missingCategories.join(", ")}`);
+  }
+}
+function validateSourceCategoryModelDefaults(defaults = SOURCE_CATEGORY_MODEL_DEFAULTS) {
+  for (const [category, value] of Object.entries(defaults)) {
+    if (!Array.isArray(value)) {
+      throw new Error(`Source category model defaults: ${category} must be a non-empty array of provider/model strings`);
+    }
+    if (value.length === 0) {
+      throw new Error(`Source category model defaults: ${category} must be a non-empty array of provider/model strings`);
+    }
+    for (const [index, model] of value.entries()) {
+      validateModel("source category model defaults", `source category model defaults.${category}[${index}]`, model);
+    }
+  }
+}
 function validateExactAgentOverlays(inventory, overlays, nativeAgents, enabledSkills) {
   const result = [];
   const seenTargets = new Map;
@@ -227,6 +302,8 @@ function hasPermissionSkill(permission) {
 function validateOverlayFieldValue(sourcePath, keyPath, field, value, enabledSkills) {
   switch (field) {
     case "model":
+      if (value === null)
+        return;
       validateModel(sourcePath, keyPath, value);
       return;
     case "variant":
@@ -371,6 +448,9 @@ function validAgentKeys(inventory) {
 function throwConfigError(sourcePath, keyPath, message) {
   throw new Error(`Invalid Systematic config in ${sourcePath}: ${keyPath} ${message}`);
 }
+function isSystemError(err) {
+  return typeof err === "object" && err !== null && "code" in err && typeof err.code === "string";
+}
 
 // src/lib/skill-loader.ts
 import path3 from "path";
@@ -540,7 +620,7 @@ function loadSkillAsCommand(loaded) {
     config.subtask = loaded.subtask;
   return config;
 }
-function collectAgents(dir, disabledAgents, nativeAgents, overlays) {
+function collectAgents(dir, disabledAgents, nativeAgents, overlays, authedProviders) {
   const agents = {};
   const agentList = findAgentsInDir(dir);
   const disabledSet = new Set(disabledAgents);
@@ -555,12 +635,12 @@ function collectAgents(dir, disabledAgents, nativeAgents, overlays) {
       continue;
     const config = loadAgentAsConfig(agentInfo);
     if (config) {
-      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays);
+      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays, authedProviders);
     }
   }
   return agents;
 }
-function applyAgentOverlays(config, agentInfo, overlays) {
+function applyAgentOverlays(config, agentInfo, overlays, authedProviders) {
   const id = agentInfo.category ? `${agentInfo.category}/${agentInfo.name}` : agentInfo.name;
   const categoryOverlay = agentInfo.category ? overlays.categoriesByKey.get(agentInfo.category) : undefined;
   const exactOverlay = overlays.agentsByTargetId.get(id);
@@ -571,6 +651,12 @@ function applyAgentOverlays(config, agentInfo, overlays) {
     addPermissionRules(permissionRules, config.permission);
   }
   result.temperature = inferBuiltInTemperature(agentInfo.name, result.description);
+  if (agentInfo.category) {
+    const sourceModel = getSourceCategoryModel(agentInfo.category, authedProviders);
+    if (sourceModel) {
+      result.model = sourceModel;
+    }
+  }
   if (categoryOverlay) {
     applyOverlayObject(result, categoryOverlay.value, permissionRules);
   }
@@ -603,7 +689,11 @@ var OVERLAY_ASSIGN_FIELDS = [
 function applyOverlayObject(target, overlay, permissionRules) {
   for (const field of OVERLAY_ASSIGN_FIELDS) {
     if (Object.hasOwn(overlay, field)) {
-      target[field] = overlay[field];
+      if (field === "model" && overlay[field] === null) {
+        delete target[field];
+      } else {
+        target[field] = overlay[field];
+      }
     }
   }
   if (isRecord(overlay.permission)) {
@@ -692,6 +782,7 @@ function collectEnabledSkillNames(dir, disabledSkills) {
 }
 function createConfigHandler(deps) {
   const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } = deps;
+  const readAuthProviders = deps.getAuthenticatedProviders ?? getAuthenticatedProviders;
   return async (config) => {
     const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
     const existingAgents = { ...config.agent ?? {} };
@@ -699,6 +790,7 @@ function createConfigHandler(deps) {
     const bundledSkills = collectSkillsAsCommands(bundledSkillsDir, systematicConfig.disabled_skills);
     const enabledSkillNames = collectEnabledSkillNames(bundledSkillsDir, systematicConfig.disabled_skills);
     const inventory = buildBundledAgentInventory(bundledAgentsDir, systematicConfig.disabled_agents);
+    assertSourceCategoryModelCoverage(inventory.categories);
     const validatedOverlays = validateAgentOverlays({
       inventory,
       overlays,
@@ -706,7 +798,8 @@ function createConfigHandler(deps) {
       enabledSkills: enabledSkillNames
     });
     const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays);
-    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, existingAgents, resolvedOverlays);
+    const authedProviders = readAuthProviders();
+    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, existingAgents, resolvedOverlays, authedProviders);
     const bundledCommands = collectCommands(bundledCommandsDir, systematicConfig.disabled_commands);
     config.agent = {
       ...bundledAgents,

package/dist/lib/agent-overlays.d.ts

@@ -42,3 +42,27 @@ export declare function buildBundledAgentInventory(agentsDir: string, disabledAg
 export declare function validateAgentOverlays({ inventory, overlays, nativeAgents, enabledSkills, }: ValidateAgentOverlaysOptions): ValidatedAgentOverlays;
 export declare function resolveAgentOverlaySet(overlays: ValidatedAgentOverlays): ResolvedAgentOverlaySet;
 export declare function inferBuiltInTemperature(name: string, description?: string): number;
+/**
+ * Read which providers are authenticated from OpenCode's auth.json.
+ *
+ * Reads only top-level keys (provider IDs). Nested values are NEVER
+ * inspected, logged, persisted, or transmitted. This is a hard contract:
+ * the auth file holds API keys and OAuth tokens, and Systematic must
+ * never expose them via stderr, telemetry, or any other channel.
+ *
+ * Intended for one invocation per plugin config(cfg) cycle. Repeated
+ * calls trigger repeated file reads and, on malformed input, repeated
+ * stderr diagnostics.
+ *
+ * @param rootDirOverride - Optional path override for tests. When
+ *   non-empty, the auth file is resolved as
+ *   `path.join(rootDirOverride, 'opencode', 'auth.json')`. When
+ *   omitted, resolution follows XDG_DATA_HOME -> ~/.local/share
+ *   convention.
+ * @returns A readonly set of authenticated provider IDs (empty set on
+ *   any failure).
+ */
+export declare function getAuthenticatedProviders(rootDirOverride?: string): ReadonlySet<string>;
+export declare function getSourceCategoryModel(category: string | undefined, authedProviders?: ReadonlySet<string>): string | undefined;
+export declare function assertSourceCategoryModelCoverage(categories: string[]): void;
+export declare function validateSourceCategoryModelDefaults(defaults?: Record<string, unknown>): void;

package/dist/lib/config-handler.d.ts

@@ -4,6 +4,8 @@ export interface ConfigHandlerDeps {
     bundledSkillsDir: string;
     bundledAgentsDir: string;
     bundledCommandsDir: string;
+    /** Override for authenticated provider reader; for testing. */
+    getAuthenticatedProviders?: (rootDirOverride?: string) => ReadonlySet<string>;
 }
 export declare function toTitleCase(name: string): string;
 export declare function formatAgentDescription(name: string, description: string | undefined): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.9.2",
+  "version": "2.11.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/onboarding/scripts/inventory.mjs

@@ -339,7 +339,7 @@ async function detectLanguagesAndFrameworks() {
       if (allDeps[dep]) {
         // Check exclusion rules before adding
         const exclusions = NODE_FRAMEWORK_EXCLUSIONS[fw]
-        if (exclusions && exclusions.some((ex) => allDeps[ex])) continue
+        if (exclusions?.some((ex) => allDeps[ex])) continue
 
         const ver = allDeps[dep].replace(/[\^~>=<]/g, '').split(' ')[0]
         frameworks.push(ver ? `${fw} ${ver}` : fw)
@@ -821,7 +821,7 @@ async function findTestInfra() {
     'src/__tests__',
   ]
   for (const dir of testDirs) {
-    if (await exists(join(root, dir))) dirs.push(dir + '/')
+    if (await exists(join(root, dir))) dirs.push(`${dir}/`)
   }
 
   // Test config files
@@ -1042,13 +1042,13 @@ async function main() {
     infrastructure,
   }
 
-  process.stdout.write(JSON.stringify(inventory) + '\n')
+  process.stdout.write(`${JSON.stringify(inventory)}\n`)
 }
 
 main().catch((err) => {
   // Always exit 0 with valid JSON, even on error
   process.stdout.write(
-    JSON.stringify({
+    `${JSON.stringify({
       error: err.message,
       name: basename(root),
       languages: [],
@@ -1062,6 +1062,6 @@ main().catch((err) => {
       docs: [],
       testInfra: { dirs: [], config: [] },
       infrastructure: { envFiles: [], configFiles: [], services: [] },
-    }) + '\n',
+    })}\n`,
   )
 })

package/skills/writing-systematic-skills/SKILL.md

@@ -86,7 +86,7 @@ description: ...
 ---
 ```
 
-Per [OpenCode's agent docs](https://opencode.ai/docs/agents/), subagents with no `model` inherit the model of the primary agent that invoked them — which is the desired portable behavior. Do **not** declare `model: inherit`: that literal value is undocumented and produces `ProviderModelNotFoundError` on OpenCode older than ~v1.13.x (pre [sst/opencode#17888](https://github.com/sst/opencode/pull/17888)). Hardcoded provider model IDs (`anthropic/...`, `openai/...`, etc.) are also banned because they break users on other providers.
+Per [OpenCode's agent docs](https://opencode.ai/docs/agents/), subagents with no `model` inherit the model of the primary agent that invoked them — which is the desired portable behavior. Do **not** declare `model: inherit`: that literal value is undocumented and produces `ProviderModelNotFoundError` on OpenCode older than ~v1.13.x (pre [sst/opencode#17888](https://github.com/sst/opencode/pull/17888)). Hardcoded provider model IDs (`anthropic/...`, `openai/...`, etc.) are also banned from **bundled agent markdown/frontmatter** because they break users on other providers. Source-owned category model defaults in TypeScript code are a separate mechanism — they are audited, centrally maintained, and do not violate this markdown rule.
 
 For agent or API attribution, `ai:systematic` is the machine ID used by Systematic-owned operations, such as Proof's `by` field and `X-Agent-Id` header. It is not a skill cross-reference convention.
 

package/skills/writing-systematic-skills/references/foundation-conventions.md

@@ -120,7 +120,9 @@ Per [OpenCode's agent docs](https://opencode.ai/docs/agents/): **"If you don't s
 
 Do **not** declare `model: inherit`. That literal value is undocumented and was treated as a real provider/model string by `Provider.parseModel()` until [sst/opencode#17888](https://github.com/sst/opencode/pull/17888) landed in mid-March 2026 — producing `ProviderModelNotFoundError` on every subagent invocation for anyone on an older OpenCode. Omitting the field works on every OpenCode version and is what the docs canonically describe.
 
-Hardcoded provider IDs (`anthropic/claude-...`, `openai/gpt-...`, etc.) are also banned because they make an agent unusable for users on other providers. If a future agent truly depends on a specific provider, document the constraint in the plan and get explicit review before adding the hardcoded model.
+Hardcoded provider IDs (`anthropic/claude-...`, `openai/gpt-...`, etc.) are also banned from **bundled agent markdown/frontmatter** because they make an agent unusable for users on other providers. This ban does not apply to source-owned category model defaults in TypeScript code, which are centrally maintained, structurally validated, and emitted at the built-in/default layer during config handling. If a future agent truly depends on a specific provider in its markdown, document the constraint in the plan and get explicit review before adding the hardcoded model.
+
+Systematic provides source-owned category model defaults in TypeScript code for all six bundled agent categories (`design`, `docs`, `document-review`, `research`, `review`, `workflow`). These code-level defaults are emitted during config handling and do not change the markdown contract: bundled agent files must still omit `model` frontmatter. The content-integrity gate continues to enforce the markdown-level ban independently of what source code defaults provide.
 
 ### Machine ID