@fro.bot/systematic 2.9.1 → 2.10.0

package/README.md

@@ -326,11 +326,52 @@ 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.
+
+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/agents/design/design-iterator.md

@@ -1,7 +1,7 @@
 ---
 name: design-iterator
 description: "Iteratively refines UI design through N screenshot-analyze-improve cycles. Use PROACTIVELY when design changes aren't coming together after 1-2 attempts, or when user requests iterative refinement."
-color: violet
+color: accent
 ---
 
 You are an expert UI/UX design iterator specializing in systematic, progressive refinement of web components. Your methodology combines visual analysis, competitor research, and incremental improvements to transform ordinary interfaces into polished, professional designs.

package/agents/design/figma-design-sync.md

@@ -1,7 +1,7 @@
 ---
 name: figma-design-sync
 description: "Detects and fixes visual differences between a web implementation and its Figma design. Use iteratively when syncing implementation to match Figma specs."
-color: purple
+color: accent
 ---
 
 You are an expert design-to-code synchronization specialist with deep expertise in visual design systems, web development, CSS/Tailwind styling, and automated quality assurance. Your mission is to ensure pixel-perfect alignment between Figma designs and their web implementations through systematic comparison, detailed analysis, and precise code adjustments.

package/agents/docs/ankane-readme-writer.md

@@ -1,7 +1,7 @@
 ---
 name: ankane-readme-writer
 description: "Creates or updates README files following Ankane-style template for Ruby gems. Use when writing gem documentation with imperative voice, concise prose, and standard section ordering."
-color: cyan
+color: info
 ---
 
 You are an expert Ruby gem documentation writer specializing in the Ankane-style README format. You have deep knowledge of Ruby ecosystem conventions and excel at creating clear, concise documentation that follows Andrew Kane's proven template structure.

package/agents/review/adversarial-reviewer.md

@@ -2,7 +2,7 @@
 name: adversarial-reviewer
 description: Conditional code-review persona, selected when the diff is large (>=50 changed lines) or touches high-risk domains like auth, payments, data mutations, or external APIs. Actively constructs failure scenarios to break the implementation rather than checking against known patterns.
 tools: Read, Grep, Glob, Bash
-color: red
+color: error
 
 ---
 

package/agents/review/agent-native-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: agent-native-reviewer
 description: "Reviews code to ensure agent-native parity -- any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
-color: cyan
+color: info
 tools: Read, Grep, Glob, Bash
 ---
 

package/agents/review/api-contract-reviewer.md

@@ -2,7 +2,7 @@
 name: api-contract-reviewer
 description: Conditional code-review persona, selected when the diff touches API routes, request/response types, serialization, versioning, or exported type signatures. Reviews code for breaking contract changes.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/cli-agent-readiness-reviewer.md

@@ -2,7 +2,7 @@
 name: cli-agent-readiness-reviewer
 description: "Reviews CLI source code, plans, or specs for AI agent readiness using a severity-based rubric focused on whether a CLI is merely usable by agents or genuinely optimized for them."
 tools: Read, Grep, Glob, Bash
-color: yellow
+color: warning
 ---
 
 # CLI Agent-Readiness Reviewer

package/agents/review/cli-readiness-reviewer.md

@@ -2,7 +2,7 @@
 name: cli-readiness-reviewer
 description: "Conditional code-review persona, selected when the diff touches CLI command definitions, argument parsing, or command handler implementations. Reviews CLI code for agent readiness -- how well the CLI serves autonomous agents, not just human users."
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 ---
 
 # CLI Agent-Readiness Reviewer

package/agents/review/correctness-reviewer.md

@@ -2,7 +2,7 @@
 name: correctness-reviewer
 description: Always-on code-review persona. Reviews code for logic errors, edge cases, state management bugs, error propagation failures, and intent-vs-implementation mismatches.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/data-migrations-reviewer.md

@@ -2,7 +2,7 @@
 name: data-migrations-reviewer
 description: Conditional code-review persona, selected when the diff touches migration files, schema changes, data transformations, or backfill scripts. Reviews code for data integrity and migration safety.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/dhh-rails-reviewer.md

@@ -2,7 +2,7 @@
 name: dhh-rails-reviewer
 description: Conditional code-review persona, selected when Rails diffs introduce architectural choices, abstractions, or frontend patterns that may fight the framework. Reviews code from an opinionated DHH perspective.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/julik-frontend-races-reviewer.md

@@ -2,7 +2,7 @@
 name: julik-frontend-races-reviewer
 description: Conditional code-review persona, selected when the diff touches async UI code, Stimulus/Turbo lifecycles, or DOM-timing-sensitive frontend behavior. Reviews code for race conditions and janky UI failure modes.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/kieran-python-reviewer.md

@@ -2,7 +2,7 @@
 name: kieran-python-reviewer
 description: Conditional code-review persona, selected when the diff touches Python code. Reviews changes with Kieran's strict bar for Pythonic clarity, type hints, and maintainability.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/kieran-rails-reviewer.md

@@ -2,7 +2,7 @@
 name: kieran-rails-reviewer
 description: Conditional code-review persona, selected when the diff touches Rails application code. Reviews Rails changes with Kieran's strict bar for clarity, conventions, and maintainability.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/kieran-typescript-reviewer.md

@@ -2,7 +2,7 @@
 name: kieran-typescript-reviewer
 description: Conditional code-review persona, selected when the diff touches TypeScript code. Reviews changes with Kieran's strict bar for type safety, clarity, and maintainability.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/maintainability-reviewer.md

@@ -2,7 +2,7 @@
 name: maintainability-reviewer
 description: Always-on code-review persona. Reviews code for premature abstraction, unnecessary indirection, dead code, coupling between unrelated modules, and naming that obscures intent.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/performance-reviewer.md

@@ -2,7 +2,7 @@
 name: performance-reviewer
 description: Conditional code-review persona, selected when the diff touches database queries, loop-heavy data transforms, caching layers, or I/O-intensive paths. Reviews code for runtime performance and scalability issues.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/previous-comments-reviewer.md

@@ -2,7 +2,7 @@
 name: previous-comments-reviewer
 description: Conditional code-review persona, selected when reviewing a PR that has existing review comments or review threads. Checks whether prior feedback has been addressed in the current diff.
 tools: Read, Grep, Glob, Bash
-color: yellow
+color: warning
 
 ---
 

package/agents/review/project-standards-reviewer.md

@@ -2,7 +2,7 @@
 name: project-standards-reviewer
 description: Always-on code-review persona. Audits changes against the project's own AGENTS.md standards -- frontmatter rules, reference inclusion, naming conventions, cross-platform portability, and tool selection policies.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 
 ---
 

package/agents/review/reliability-reviewer.md

@@ -2,7 +2,7 @@
 name: reliability-reviewer
 description: Conditional code-review persona, selected when the diff touches error handling, retries, circuit breakers, timeouts, health checks, background jobs, or async handlers. Reviews code for production reliability and failure modes.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/security-reviewer.md

@@ -2,7 +2,7 @@
 name: security-reviewer
 description: Conditional code-review persona, selected when the diff touches auth middleware, public endpoints, user input handling, or permission checks. Reviews code for exploitable vulnerabilities.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 mode: subagent
 temperature: 0.1
 ---

package/agents/review/testing-reviewer.md

@@ -2,7 +2,7 @@
 name: testing-reviewer
 description: Always-on code-review persona. Reviews code for test coverage gaps, weak assertions, brittle implementation-coupled tests, and missing edge case coverage.
 tools: Read, Grep, Glob, Bash
-color: blue
+color: info
 
 ---
 

package/agents/workflow/lint.md

@@ -1,7 +1,7 @@
 ---
 name: lint
 description: Use this agent when you need to run linting and code quality checks on Ruby and ERB files. Run before pushing to origin.
-color: yellow
+color: warning
 mode: subagent
 temperature: 0.1
 ---

package/agents/workflow/pr-comment-resolver.md

@@ -1,7 +1,7 @@
 ---
 name: pr-comment-resolver
 description: "Evaluates and resolves one or more related PR review threads -- assesses validity, implements fixes, and returns structured summaries with reply text. Spawned by the resolve-pr-feedback skill."
-color: blue
+color: info
 ---
 
 You resolve PR review threads. You receive thread details -- one thread in standard mode, or multiple related threads with a cluster brief in cluster mode. Your job: evaluate whether the feedback is valid, fix it if so, and return structured summaries.

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";
@@ -79,6 +79,14 @@ ${toolMapping}
 // src/lib/agent-overlays.ts
 import fs2 from "fs";
 import path2 from "path";
+var SOURCE_CATEGORY_MODEL_DEFAULTS = {
+  design: "openai/gpt-5.5",
+  docs: "openai/gpt-5.4-mini",
+  "document-review": "anthropic/claude-opus-4.7",
+  research: "openai/gpt-5.5",
+  review: "anthropic/claude-opus-4.7",
+  workflow: "openai/gpt-5.4-mini"
+};
 var ALLOWED_OVERLAY_FIELDS = new Set([
   "model",
   "variant",
@@ -158,6 +166,23 @@ function inferBuiltInTemperature(name, description) {
   }
   return 0.3;
 }
+function getSourceCategoryModel(category) {
+  if (!category)
+    return;
+  return SOURCE_CATEGORY_MODEL_DEFAULTS[category];
+}
+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, model] of Object.entries(defaults)) {
+    validateModel("source category model defaults", `source category model defaults.${category}`, model);
+  }
+}
 function validateExactAgentOverlays(inventory, overlays, nativeAgents, enabledSkills) {
   const result = [];
   const seenTargets = new Map;
@@ -227,6 +252,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":
@@ -571,6 +598,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);
+    if (sourceModel) {
+      result.model = sourceModel;
+    }
+  }
   if (categoryOverlay) {
     applyOverlayObject(result, categoryOverlay.value, permissionRules);
   }
@@ -603,7 +636,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)) {
@@ -699,6 +736,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,
@@ -734,28 +772,20 @@ function registerSkillsPaths(config, skillsDir) {
 var SINGLETON_KEY = Symbol.for("systematic.singleton.v1");
 async function plugInOnce({
   doInit,
-  onDuplicate,
   pid
 }) {
   const currentPid = pid ?? process.pid;
   const g = globalThis;
   const existing = g[SINGLETON_KEY];
   if (existing && existing.pid === currentPid) {
-    if (!existing.warned) {
-      existing.warned = true;
-      try {
-        onDuplicate?.(currentPid);
-      } catch {}
-    }
-    await existing.hooksPromise;
-    return { isFirst: false, hooks: {} };
+    const hooks2 = await existing.hooksPromise;
+    return { isFirst: false, hooks: hooks2 };
   }
   const hooksPromise = doInit();
   g[SINGLETON_KEY] = {
     pid: currentPid,
     loadedAt: Date.now(),
-    hooksPromise,
-    warned: false
+    hooksPromise
   };
   const hooks = await hooksPromise;
   return { isFirst: true, hooks };
@@ -1004,18 +1034,7 @@ var initializePlugin = async ({ client, directory }) => {
 };
 var SystematicPlugin = async (input) => {
   const { hooks } = await plugInOnce({
-    doInit: () => initializePlugin(input),
-    onDuplicate: (pid) => {
-      const message = `[systematic] duplicate factory invocation in same process (pid=${pid}); skipping duplicate registration. Multiple opencode.json sources may list this plugin.`;
-      console.warn(message);
-      input.client.app.log({
-        body: {
-          service: "systematic",
-          level: "warn",
-          message
-        }
-      }).catch(() => {});
-    }
+    doInit: () => initializePlugin(input)
   });
   return hooks;
 };

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

@@ -42,3 +42,6 @@ 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;
+export declare function getSourceCategoryModel(category: string | undefined): string | undefined;
+export declare function assertSourceCategoryModelCoverage(categories: string[]): void;
+export declare function validateSourceCategoryModelDefaults(defaults?: Record<string, unknown>): void;

package/dist/lib/plugin-singleton.d.ts

@@ -11,25 +11,17 @@
  *
  * On the first invocation `doInit` runs and the resulting hooks promise
  * is cached on `globalThis`; the caller receives `{ isFirst: true, hooks }`.
- * On every subsequent invocation in the same PID `doInit` is skipped, the
- * cached promise is awaited (so sticky rejections still propagate),
- * `onDuplicate` fires exactly once, and the caller receives
- * `{ isFirst: false, hooks: {} as T }`. Across PIDs the guard is treated
- * as absent and init runs fresh — `globalThis` is per-process, but the
- * explicit PID check adds defensive belt-and-suspenders against any
- * state-leakage edge case.
+ * On every subsequent invocation in the same PID `doInit` is skipped and
+ * the cached resolved hooks are returned directly to every caller.
+ * Across PIDs the guard is treated as absent and init runs fresh —
+ * `globalThis` is per-process, but the explicit PID check adds defensive
+ * belt-and-suspenders against any state-leakage edge case.
  *
- * **Why empty hooks on duplicate invocations.** A whole-hooks singleton
- * that returns the same hooks reference to both invocations does not
- * deduplicate host-side tool registration: OpenCode iterates each plugin
- * source's returned hook surface and registers every tool entry it finds,
- * even when two sources return the same JS reference. Returning `{}` from
- * the duplicate path is the only shape that prevents host-side double
- * registration of `systematic_skill`, the `config` hook, and the
- * `experimental.chat.system.transform` hook. The Phase 0 follow-up probe
- * (see `docs/plans/2026-05-01-001-fix-idempotent-plugin-registration-plan.md`)
- * verified the duplicate `systematic_skill` entry in OpenCode's
- * `client.tool.list(...)` output, which is the LLM-visible tool catalog.
+ * The singleton returns the same hooks reference to every caller within a
+ * process — first and duplicate alike. OpenCode may register the same hook
+ * surface once per configured plugin source; that is preferable to suppressing
+ * duplicates with an empty object because every source keeps the full tools,
+ * commands, skills, and hooks surface.
  *
  * **Known limitation — rejected init is sticky.** If `doInit()` rejects,
  * the rejected promise is stored on `globalThis` and every subsequent
@@ -40,37 +32,27 @@
 export interface PlugInOnceOptions<T> {
     /** Heavy init work that should run at most once per process. */
     doInit: () => Promise<T>;
-    /**
-     * Called exactly once on the first duplicate invocation in the same
-     * process. Subsequent duplicates are silent. Receives the same `pid`
-     * value the guard used for its identity check (so test overrides flow
-     * through faithfully). Implementations must not throw; fire-and-forget
-     * side effects (logging, metrics) are expected. Synchronous exceptions
-     * are swallowed defensively.
-     */
-    onDuplicate?: (pid: number) => void;
     /** Test override; defaults to `process.pid`. */
     pid?: number;
 }
 /**
  * Result envelope for `plugInOnce(...)`.
  *
- * - `isFirst: true` — caller should return `hooks` to OpenCode.
- * - `isFirst: false` — caller MUST return `hooks` (which is an empty `{}`)
- *   so the host loader does not register tools or hooks twice.
+ * - `isFirst: true` — caller was the first invocation in this process.
+ * - `isFirst: false` — `doInit` was skipped; the cached result is returned.
  *
- * Callers that just `return result.hooks` do the right thing in both
- * cases without needing to inspect `isFirst`.
+ * In both cases `hooks` is the real resolved value of `doInit()`. Callers
+ * return `result.hooks` unconditionally without inspecting `isFirst`.
  */
 export interface PlugInOnceResult<T> {
     isFirst: boolean;
     hooks: T;
 }
 /**
- * Run `doInit` at most once per process; on duplicate invocations resolve to
- * empty hooks so the OpenCode host does not double-register tools and hooks.
+ * Run `doInit` at most once per process; on duplicate invocations return the
+ * cached real hook surface so every config source sees the same surface.
  */
-export declare function plugInOnce<T>({ doInit, onDuplicate, pid, }: PlugInOnceOptions<T>): Promise<PlugInOnceResult<T>>;
+export declare function plugInOnce<T>({ doInit, pid, }: PlugInOnceOptions<T>): Promise<PlugInOnceResult<T>>;
 /**
  * Test-only: clear the singleton state so the next invocation re-runs
  * init. Must not be called in production code paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.9.1",
+  "version": "2.10.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