opencode-swarm 7.52.1 → 7.52.3

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-OpenCode Swarm is a plugin for [OpenCode](https://opencode.ai) that turns a single AI coding session into an **architect-led team of specialized core, optional, and conditional agents** — see `/swarm agents` for the live roster. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another checks security. **Nothing ships until every required gate passes.**
+OpenCode Swarm is a plugin for [OpenCode](https://opencode.ai) that turns a single AI coding session into an **architect-led team of specialized core, optional, and conditional agents**. Run `/swarm agents` for the live roster; it is generated from the current plugin configuration. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another checks security. **Nothing ships until every required gate passes.**
 
 ```bash
 bunx opencode-swarm install
@@ -24,7 +24,7 @@ bunx opencode-swarm install
 
 > This single command installs the package, registers it as an OpenCode plugin, disables conflicting default agents, and creates a ready-to-edit config at `~/.config/opencode/opencode-swarm.json`. Requires [Bun](https://bun.sh) (`bun --version` to check). If you must use npm: `npm install -g opencode-swarm && opencode-swarm install`.
 
-> ⚠️ **On first run, Swarm auto-selects the architect and shows a welcome message.** The default OpenCode `Build` and `Plan` modes **bypass this plugin entirely** — none of the gates, reviewers, or test agents below run. If you ever need to switch architect manually, open the OpenCode mode/agent picker and choose the Swarm architect; it then coordinates every other agent automatically. If you ever see Swarm "do nothing," this is almost always the cause.
+> **First-run note:** the installer registers the plugin, writes the global plugin config, creates a project override when missing, and disables the native `explore` and `general` agents in `opencode.json`. If you are not using a Swarm architect, the Swarm gates, reviewers, and test agents are bypassed. Open the OpenCode agent or mode picker and choose the Swarm architect when needed.
 
 ### Why Swarm?
 
@@ -44,7 +44,7 @@ Most AI coding tools let one model write code and ask that same model whether th
 - 🆓 **Free tier** — works with OpenCode Zen's free model roster
 - ⚙️ **Fully configurable** — override any agent's model, disable agents, tune guardrails
 
-> **The Swarm architect is auto-selected on first run and coordinates all other agents automatically.** You never manually switch between internal roles. If you use the default OpenCode `Build` / `Plan` modes, the plugin is bypassed entirely (see the install warning above).
+> **The Swarm architect coordinates all internal agents automatically.** You never manually switch between internal roles. If the active OpenCode agent is not a Swarm architect, the plugin workflow is bypassed.
 
 ---
 
@@ -157,10 +157,10 @@ The 15-minute guide covers:
 - Running your first task
 - Troubleshooting common issues
 
-On first run, Swarm automatically:
-- Creates project config at `.opencode/opencode-swarm.json` with all agents enabled
-- Selects the Swarm architect as the default
-- Shows a welcome message with next steps
+The installer automatically:
+- Creates a project config at `.opencode/opencode-swarm.json` when missing so project-level overrides have a place to live
+- Adds `opencode-swarm` to the OpenCode plugin list
+- Disables the native `explore` and `general` agents to reduce routing conflicts
 
 ---
 
@@ -174,8 +174,7 @@ No animated GIF is shipped in the repo — instead, here is the exact terminal s
 # 1. Install the plugin (5s)
 bunx opencode-swarm install
 
-# 2. Open opencode — Swarm auto-selects architect on first run
-#    (the architect is auto-selected; manual selection is only needed to override)
+# 2. Open opencode and select a Swarm architect if it is not already active
 opencode
 
 # 3. Inside the OpenCode session, verify Swarm is live (5s)
@@ -225,12 +224,18 @@ Each row corresponds to a real gate documented further down this README — none
 **OpenCode caches plugins indefinitely.** A normal OpenCode restart does **not**
 pull newer versions from npm — once a plugin is cached, OpenCode keeps using
 that exact copy on every subsequent launch (issue #675). The cache lives in
-one of two places depending on your platform:
+several places depending on your platform and OpenCode version:
 
-- Linux / devcontainers / GitHub Codespaces:
+- Current OpenCode cache layout:
+  `~/.cache/opencode/node_modules/opencode-swarm/`
+- Legacy Linux / devcontainers / GitHub Codespaces:
   `~/.config/opencode/node_modules/opencode-swarm/`
-- Some macOS / Windows installs:
+- Package cache layout:
   `~/.cache/opencode/packages/opencode-swarm@latest/`
+- Platform-specific macOS / Windows cache roots:
+  `~/Library/Caches/opencode/...`, `%LOCALAPPDATA%\opencode\...`, or `%APPDATA%\opencode\...`
+
+The updater also clears known OpenCode lock files (`bun.lock`, `bun.lockb`, and `package-lock.json`) so the next start resolves the latest package.
 
 To upgrade to the latest published version (clears both layouts automatically):
 
@@ -250,7 +255,7 @@ in your `opencode-swarm.json`.
 
 ## Commands
 
-All 43 subcommands at a glance:
+Common subcommands at a glance:
 
 ```bash
 /swarm help [command]      # List all commands or get detailed help for a specific command
@@ -266,7 +271,7 @@ Use `/swarm help` to see all available commands categorized by function. Use `/s
 
 Nine commands display a ⚠️ warning in help output because they share names with Claude Code built-in slash commands (e.g., `/plan`, `/reset`, `/status`). The warning reminds you to always use `/swarm <command>` — the bare CC command does something different and sometimes destructive. See [docs/commands.md#claude-code-command-conflicts](docs/commands.md#claude-code-command-conflicts) for the full conflict registry.
 
-See [docs/commands.md](docs/commands.md) for the full reference (43 commands).
+See [docs/commands.md](docs/commands.md) for the full reference. The live source of truth is `src/commands/registry.ts`, which includes canonical commands, compound commands, and deprecated aliases.
 
 ## Command Aliases
 
@@ -529,13 +534,13 @@ Override via `authority.rules` in config.
 
 Built-in tools verify every task before it ships:
 
-- **syntax_check** — Tree-sitter validation (12 languages)
+- **syntax_check** — Tree-sitter validation across the configured language grammar map
 - **placeholder_scan** — Catches TODOs, stubs, incomplete code
 - **sast_scan** — 63+ security rules, 9 languages (offline)
 - **sbom_generate** — Dependency tracking (CycloneDX)
 - **quality_budget** — Complexity, duplication, test ratio limits
 
-All tools run locally. No Docker, no network calls.
+These quality gates run locally. No Docker is required. Config-gated features such as General Council web search can make external API calls only when you enable them and provide a Tavily or Brave Search key.
 
 ### Context Budget Guard
 
@@ -719,16 +724,16 @@ Swarm provides tools for managing generated skill lifecycles:
 <details>
 <summary><strong>Quality Gates (Technical Detail)</strong></summary>
 
-### Built-in Tools
+### Built-in Tools and Hooks
 
-| Tool | What It Does |
+| Surface | What It Does |
 |------|-------------|
-| syntax_check | Tree-sitter validation across 12 languages |
+| syntax_check | Tree-sitter validation across the configured language grammar map |
 | placeholder_scan | Catches TODOs, FIXMEs, stubs, placeholder text |
 | sast_scan | Offline security analysis, 63+ rules, 9 languages |
 | sbom_generate | CycloneDX dependency tracking, 8 ecosystems |
 | build_check | Runs your project's native build/typecheck |
-| incremental_verify | Post-coder typecheck for TS/JS, Go, Rust, C# (v6.29.2) |
+| incremental_verify | Post-coder hook for TS/JS, Go, Rust, Python, and C#; configured by `incremental_verify.*`, not invoked as a registered tool |
 | quality_budget | Enforces complexity, duplication, and test ratio limits |
 | pre_check_batch | Runs lint, secretscan, SAST, and quality budget in parallel (~15s vs ~60s sequential) |
 | phase_complete | Enforces phase completion, verifies required agents, requires a valid retrospective evidence bundle, logs events, and resets state; appends to `events.jsonl` with file locking |
@@ -742,7 +747,7 @@ Swarm provides tools for managing generated skill lifecycles:
 | symbols | Extract exported symbols from source files; supports `workspace` (boolean) and `name` (string) parameters for multi-file symbol search |
 
 
-All tools run locally. No Docker, no network calls, no external APIs.
+Quality-gate surfaces run locally and require no Docker. Optional search-backed council features use external APIs only when explicitly enabled and configured.
 
 Optional enhancement: Semgrep (if on PATH).
 
@@ -873,19 +878,21 @@ Config file location: `~/.config/opencode/opencode-swarm.json` (global) or `.ope
   "knowledge": {
     "enabled": true,
     "swarm_max_entries": 100,
-    "hive_max_entries": 1000,
-    "auto_promote_days": 30,
+    "hive_max_entries": 200,
+    "auto_promote_days": 90,
     "max_inject_count": 5,
+    "inject_char_budget": 2000,
+    "max_lesson_display_chars": 120,
     "dedup_threshold": 0.6,
     "scope_filter": ["global"],
     "hive_enabled": true,
-    "rejected_max_entries": 200,
+    "rejected_max_entries": 20,
     "validation_enabled": true,
-    "evergreen_confidence": 0.8,
-    "evergreen_utility": 0.5,
-    "low_utility_threshold": 0.2,
+    "evergreen_confidence": 0.9,
+    "evergreen_utility": 0.8,
+    "low_utility_threshold": 0.3,
     "min_retrievals_for_utility": 3,
-    "schema_version": "v6.17"
+    "schema_version": 1
   }
 }
 ```
@@ -1024,7 +1031,7 @@ Control how tool outputs are summarized for LLM context.
 | `/swarm preflight` | Run phase preflight checks |
 | `/swarm config doctor [--fix]` | Config validation with optional auto-fix |
 | `/swarm doctor tools` | Tool registration coherence and binary readiness check |
-| `/swarm sync-plan` | Force plan.md regeneration from plan.json |
+| `/swarm sync-plan` | Force `plan.md` regeneration from the canonical plan ledger |
 | `/swarm specify [description]` | Generate or import a feature specification |
 | `/swarm clarify [topic]` | Clarify and refine an existing feature specification |
 | `/swarm analyze` | Analyze spec.md vs plan.md for requirement coverage gaps |
@@ -1040,9 +1047,15 @@ Control how tool outputs are summarized for LLM context.
 | `/swarm knowledge quarantine [id]` | Move a knowledge entry to quarantine |
 | `/swarm knowledge restore [id]` | Restore a quarantined knowledge entry |
 | `/swarm memory status` | Show memory provider and JSONL migration status |
+| `/swarm memory pending` | Show pending memory proposals and recent rejection reasons |
+| `/swarm memory recall-log` | Summarize memory recall usage |
+| `/swarm memory stale` | List expired, superseded, deleted, and low-utility memory records |
+| `/swarm memory compact` | Dry-run memory cleanup; pass `--confirm` to apply |
 | `/swarm memory export` | Export memory records and proposals to JSONL |
+| `/swarm memory evaluate` | Run memory recall evaluation fixtures |
 | `/swarm memory import` | Import legacy JSONL memory into SQLite |
 | `/swarm memory migrate` | Run the one-time JSONL to SQLite migration |
+| `/swarm concurrency <set|status|reset>` | Manage session-scoped runtime concurrency override |
 | `/swarm turbo` | Enable turbo mode for the current session (bypasses QA gates) |
 | `/swarm full-auto` | Toggle Full-Auto Mode for the current session [on|off] |
 | `/swarm checkpoint` | Save a git checkpoint for the current state |
@@ -1053,8 +1066,8 @@ Control how tool outputs are summarized for LLM context.
 
 ## Supported Languages
 
-Full Tier-1 support: TypeScript, JavaScript, Python, Go, Rust  
-Tier-2 support: Java, Kotlin, C#, C/C++, Swift  
+Full Tier-1 support: TypeScript, JavaScript, Python, Go, Rust
+Tier-2 support: Java, Kotlin, C#, C/C++, Swift
 Tier-3 support: Dart, Ruby, PHP/Laravel
 
 All binaries optional. Missing tools produce soft warnings, never hard-fail.

package/dist/cli/index.js

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.52.1",
+    version: "7.52.3",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -17275,7 +17275,7 @@ function getCanonicalAgentRole(agentName, generatedAgentNames) {
 function stripKnownSwarmPrefix(agentName) {
   return getCanonicalAgentRole(agentName);
 }
-var SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, ContextMapConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
+var SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, ContextMapConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillPropagationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_constants();
@@ -17832,6 +17832,10 @@ var init_schema = __esm(() => {
       "Task"
     ])
   });
+  SkillPropagationConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true),
+    enforce: exports_external.boolean().default(false)
+  });
   SkillImproverConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(false),
     model: exports_external.string().nullable().default(null),
@@ -18023,6 +18027,7 @@ var init_schema = __esm(() => {
     curator: CuratorConfigSchema.optional(),
     architectural_supervision: ArchitecturalSupervisionConfigSchema.optional(),
     knowledge_application: KnowledgeApplicationConfigSchema.optional(),
+    skillPropagation: SkillPropagationConfigSchema.optional(),
     skill_improver: SkillImproverConfigSchema.optional(),
     spec_writer: SpecWriterConfigSchema.optional(),
     tool_output: exports_external.object({
@@ -37092,6 +37097,57 @@ function readSkillUsageEntries(directory, options) {
     return true;
   });
 }
+function pruneSkillUsageLog(directory, maxEntriesPerSkill = 500) {
+  const resolved = resolveLogPath(directory);
+  if (!_internals10.existsSync(resolved)) {
+    return { pruned: 0, remaining: 0 };
+  }
+  const allEntries = readSkillUsageEntries(directory);
+  if (allEntries.length === 0) {
+    return { pruned: 0, remaining: 0 };
+  }
+  const groups = new Map;
+  for (const entry of allEntries) {
+    const list = groups.get(entry.skillPath);
+    if (list)
+      list.push(entry);
+    else
+      groups.set(entry.skillPath, [entry]);
+  }
+  let pruned = 0;
+  const surviving = [];
+  groups.forEach((entries) => {
+    if (entries.length <= maxEntriesPerSkill) {
+      surviving.push(...entries);
+      return;
+    }
+    entries.sort((a, b) => b.timestamp > a.timestamp ? 1 : b.timestamp < a.timestamp ? -1 : 0);
+    const kept = entries.slice(0, maxEntriesPerSkill);
+    pruned += entries.length - kept.length;
+    surviving.push(...kept);
+  });
+  if (pruned === 0) {
+    return { pruned: 0, remaining: allEntries.length };
+  }
+  const dir = path14.dirname(resolved);
+  const tmpPath = path14.join(dir, `skill-usage-${Date.now()}.tmp`);
+  const content = surviving.map((e) => JSON.stringify(e)).join(`
+`).concat(`
+`);
+  try {
+    _internals10.writeFileSync(tmpPath, content, "utf-8");
+    _internals10.renameSync(tmpPath, resolved);
+  } catch (writeErr) {
+    const msg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+    try {
+      if (_internals10.existsSync(tmpPath)) {
+        _internals10.writeFileSync(tmpPath, "", "utf-8");
+      }
+    } catch {}
+    return { pruned: 0, remaining: allEntries.length, error: msg };
+  }
+  return { pruned, remaining: surviving.length };
+}
 async function resolveSourceKnowledgeIds(directory, skillPath) {
   try {
     let cleanPath = skillPath;
@@ -37203,7 +37259,7 @@ async function applySkillUsageFeedback(directory, options) {
   }
   return { processed, bumps };
 }
-var _internals10, TAIL_BYTES_DEFAULT, COMPLIANCE_BOOST = 0.05, VIOLATION_DECAY = 0.1;
+var _internals10, TAIL_BYTES_DEFAULT, SKILL_USAGE_LOG_ROTATE_BYTES, COMPLIANCE_BOOST = 0.05, VIOLATION_DECAY = 0.1;
 var init_skill_usage_log = __esm(() => {
   init_knowledge_store();
   init_utils2();
@@ -37219,11 +37275,13 @@ var init_skill_usage_log = __esm(() => {
     openSync: fs7.openSync.bind(fs7),
     readSync: fs7.readSync.bind(fs7),
     closeSync: fs7.closeSync.bind(fs7),
+    pruneSkillUsageLog,
     resolveSourceKnowledgeIds,
     applySkillUsageFeedback,
     parseGeneratedFromKnowledge
   };
   TAIL_BYTES_DEFAULT = 64 * 1024;
+  SKILL_USAGE_LOG_ROTATE_BYTES = 1024 * 1024;
 });
 
 // src/hooks/curator.ts

package/dist/config/index.d.ts

@@ -18,7 +18,7 @@ export declare const _internals: {
 };
 export type { MigrationStatus, Phase, PhaseStatus, Plan, Task, TaskSize, TaskStatus, } from './plan-schema';
 export { MigrationStatusSchema, PhaseSchema, PhaseStatusSchema, PlanSchema, TaskSchema, TaskSizeSchema, TaskStatusSchema, } from './plan-schema';
-export type { AgentOverrideConfig, AutomationCapabilities, AutomationConfig, AutomationMode, LeanTurboConfig, MemoryConfig, PhaseCompleteConfig, PipelineConfig, PluginConfig, SwarmConfig, TurboConfig, } from './schema';
-export { AgentOverrideConfigSchema, AutomationCapabilitiesSchema, AutomationConfigSchema, AutomationModeSchema, LeanTurboConfigSchema, MemoryConfigSchema, PhaseCompleteConfigSchema, PipelineConfigSchema, PluginConfigSchema, SwarmConfigSchema, TurboConfigSchema, } from './schema';
+export type { AgentOverrideConfig, AutomationCapabilities, AutomationConfig, AutomationMode, LeanTurboConfig, MemoryConfig, PhaseCompleteConfig, PipelineConfig, PluginConfig, SkillPropagationConfig, SwarmConfig, TurboConfig, } from './schema';
+export { AgentOverrideConfigSchema, AutomationCapabilitiesSchema, AutomationConfigSchema, AutomationModeSchema, LeanTurboConfigSchema, MemoryConfigSchema, PhaseCompleteConfigSchema, PipelineConfigSchema, PluginConfigSchema, SkillPropagationConfigSchema, SwarmConfigSchema, TurboConfigSchema, } from './schema';
 export type { DeltaSpec, Obligation, SpecDelta, SpecRequirement, SpecScenario, SpecSection, SwarmSpec, } from './spec-schema';
 export { DeltaSpecSchema, ObligationSchema, SpecDeltaSchema, SpecRequirementSchema, SpecScenarioSchema, SpecSectionSchema, SwarmSpecSchema, validateSpecContent, } from './spec-schema';

package/dist/config/schema.d.ts

@@ -611,6 +611,11 @@ export declare const KnowledgeApplicationConfigSchema: z.ZodObject<{
     high_risk_tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type KnowledgeApplicationConfig = z.infer<typeof KnowledgeApplicationConfigSchema>;
+export declare const SkillPropagationConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    enforce: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SkillPropagationConfig = z.infer<typeof SkillPropagationConfigSchema>;
 export declare const SkillImproverConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -1309,6 +1314,10 @@ export declare const PluginConfigSchema: z.ZodObject<{
         require_skill_refs: z.ZodDefault<z.ZodBoolean>;
         high_risk_tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    skillPropagation: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        enforce: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     skill_improver: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         model: z.ZodDefault<z.ZodNullable<z.ZodString>>;

package/dist/hooks/skill-propagation-gate.d.ts

@@ -29,10 +29,8 @@ export declare function loadRoutingSkills(directory: string, targetAgent: string
 /** Agents that should receive skill context in delegations. */
 export declare const SKILL_CAPABLE_AGENTS: Set<string>;
 /**
- * Maximum number of session-scoped skill-usage entries to process for
- * skill scoring. When a session accumulates more entries than this
- * limit, scoring is skipped to prevent unbounded file reads from
- * stalling every delegated Task call.
+ * Maximum number of session-scoped skill-usage tail entries to process for
+ * skill scoring. This applies to the bounded tail-read window only.
  */
 export declare const MAX_SCORING_SESSION_ENTRIES = 500;
 export interface SkillGateInput {

package/dist/hooks/skill-usage-log.d.ts

@@ -66,6 +66,7 @@ export declare const _internals: {
     openSync: typeof fs.openSync;
     readSync: typeof fs.readSync;
     closeSync: typeof fs.closeSync;
+    pruneSkillUsageLog: typeof pruneSkillUsageLog;
     resolveSourceKnowledgeIds: typeof resolveSourceKnowledgeIds;
     applySkillUsageFeedback: typeof applySkillUsageFeedback;
     parseGeneratedFromKnowledge: typeof parseGeneratedFromKnowledge;
@@ -86,6 +87,7 @@ export declare function appendSkillUsageEntry(directory: string, entry: Omit<Ski
 export declare function readSkillUsageEntries(directory: string, options?: SkillUsageFilterOptions): SkillUsageEntry[];
 /** Default maximum bytes to read from the end of the log file. */
 export declare const TAIL_BYTES_DEFAULT: number;
+export declare const MAX_TAIL_BYTES: number;
 /**
  * Read the last `maxBytes` of the skill-usage JSONL log and parse matching
  * entries. Much faster than `readSkillUsageEntries` for large logs because

package/dist/index.js

@@ -69,7 +69,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.52.1",
+    version: "7.52.3",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -15207,7 +15207,7 @@ function resolveGuardrailsConfig(config2, agentName) {
   };
   return resolved;
 }
-var _internals, SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, ContextMapConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
+var _internals, SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, ContextMapConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillPropagationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_constants();
@@ -15769,6 +15769,10 @@ var init_schema = __esm(() => {
       "Task"
     ])
   });
+  SkillPropagationConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true),
+    enforce: exports_external.boolean().default(false)
+  });
   SkillImproverConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(false),
     model: exports_external.string().nullable().default(null),
@@ -15960,6 +15964,7 @@ var init_schema = __esm(() => {
     curator: CuratorConfigSchema.optional(),
     architectural_supervision: ArchitecturalSupervisionConfigSchema.optional(),
     knowledge_application: KnowledgeApplicationConfigSchema.optional(),
+    skillPropagation: SkillPropagationConfigSchema.optional(),
     skill_improver: SkillImproverConfigSchema.optional(),
     spec_writer: SpecWriterConfigSchema.optional(),
     tool_output: exports_external.object({
@@ -16520,6 +16525,7 @@ __export(exports_config, {
   SpecScenarioSchema: () => SpecScenarioSchema,
   SpecRequirementSchema: () => SpecRequirementSchema,
   SpecDeltaSchema: () => SpecDeltaSchema,
+  SkillPropagationConfigSchema: () => SkillPropagationConfigSchema,
   ReviewEvidenceSchema: () => ReviewEvidenceSchema,
   QA_AGENTS: () => QA_AGENTS,
   PluginConfigSchema: () => PluginConfigSchema,
@@ -41522,6 +41528,7 @@ __export(exports_state, {
   endAgentSession: () => endAgentSession,
   defaultRunContext: () => defaultRunContext,
   clearCriticalShownIds: () => clearCriticalShownIds,
+  canAdvanceTaskState: () => canAdvanceTaskState,
   buildRehydrationCache: () => buildRehydrationCache,
   beginInvocation: () => beginInvocation,
   applyRehydrationCache: () => applyRehydrationCache,
@@ -41900,14 +41907,6 @@ function advanceTaskState(session, taskId, newState, options, councilConfig) {
   if (!session || !(session.taskWorkflowStates instanceof Map)) {
     throw new Error("INVALID_SESSION: session.taskWorkflowStates must be a Map instance");
   }
-  const STATE_ORDER = [
-    "idle",
-    "coder_delegated",
-    "pre_check_passed",
-    "reviewer_run",
-    "tests_run",
-    "complete"
-  ];
   const current = session.taskWorkflowStates.get(taskId) ?? "idle";
   const currentIndex = STATE_ORDER.indexOf(current);
   const newIndex = STATE_ORDER.indexOf(newState);
@@ -41924,10 +41923,33 @@ function advanceTaskState(session, taskId, newState, options, councilConfig) {
     }
   }
   session.taskWorkflowStates.set(taskId, newState);
+  if (newState === "complete") {
+    session.stageBCompletion?.delete(taskId);
+  }
   if (options?.emitTelemetry !== false) {
     telemetry.taskStateChanged(options?.telemetrySessionId ?? session.agentName, taskId, newState, current);
   }
 }
+function canAdvanceTaskState(session, taskId, newState, councilConfig) {
+  if (!isValidTaskId2(taskId))
+    return false;
+  if (!session || !(session.taskWorkflowStates instanceof Map))
+    return false;
+  const current = session.taskWorkflowStates.get(taskId) ?? "idle";
+  const currentIndex = STATE_ORDER.indexOf(current);
+  const newIndex = STATE_ORDER.indexOf(newState);
+  if (newIndex <= currentIndex)
+    return false;
+  if (newState === "complete" && current !== "tests_run") {
+    const councilEntry = session.taskCouncilApproved?.get(taskId);
+    const effectiveMinimum = councilConfig?.requireAllMembers ? 5 : councilConfig?.minimumMembers ?? 3;
+    const councilApproved = councilEntry?.verdict === "APPROVE" && (councilEntry.quorumSize ?? 0) >= effectiveMinimum;
+    const pastPreCheck = currentIndex >= STATE_ORDER.indexOf("pre_check_passed");
+    if (!councilApproved || !pastPreCheck)
+      return false;
+  }
+  return true;
+}
 async function advanceTaskStateAndPersist(session, taskId, newState, directory, options, councilConfig) {
   advanceTaskState(session, taskId, newState, options, councilConfig);
   if (newState !== "coder_delegated" && newState !== "complete") {
@@ -42098,14 +42120,6 @@ function applyRehydrationCache(session) {
     session.taskCouncilApproved = new Map;
   }
   const { planTaskStates, evidenceMap } = _rehydrationCache;
-  const STATE_ORDER = [
-    "idle",
-    "coder_delegated",
-    "pre_check_passed",
-    "reviewer_run",
-    "tests_run",
-    "complete"
-  ];
   for (const [taskId, planState] of planTaskStates) {
     const existingState = session.taskWorkflowStates.get(taskId);
     const evidence = evidenceMap.get(taskId);
@@ -42241,7 +42255,7 @@ function addKnowledgeAckDedup(key) {
       set2.delete(oldest);
   }
 }
-var _rehydrationCache = null, _councilDisagreementWarned, _toolAggregates, defaultRunContext, _runContexts, swarmState, MAX_TRACKED_CRITICAL_SHOWN = 500, MAX_TRACKED_KNOWLEDGE_ACKS = 5000, _internals16;
+var _rehydrationCache = null, _councilDisagreementWarned, STATE_ORDER, _toolAggregates, defaultRunContext, _runContexts, swarmState, MAX_TRACKED_CRITICAL_SHOWN = 500, MAX_TRACKED_KNOWLEDGE_ACKS = 5000, _internals16;
 var init_state = __esm(() => {
   init_constants();
   init_plan_schema();
@@ -42252,6 +42266,14 @@ var init_state = __esm(() => {
   init_telemetry();
   init_logger();
   _councilDisagreementWarned = new Set;
+  STATE_ORDER = [
+    "idle",
+    "coder_delegated",
+    "pre_check_passed",
+    "reviewer_run",
+    "tests_run",
+    "complete"
+  ];
   _toolAggregates = new Map;
   defaultRunContext = new AgentRunContext("default", _toolAggregates);
   _runContexts = new Map;
@@ -58222,6 +58244,12 @@ function appendSkillUsageEntry(directory, entry) {
   };
   _internals19.appendFileSync(resolved, `${JSON.stringify(fullEntry)}
 `, "utf-8");
+  try {
+    const stat3 = _internals19.statSync(resolved);
+    if (stat3.size > SKILL_USAGE_LOG_ROTATE_BYTES) {
+      _internals19.pruneSkillUsageLog(directory, SKILL_USAGE_LOG_MAX_ENTRIES_PER_SKILL);
+    }
+  } catch {}
 }
 function readSkillUsageEntries(directory, options) {
   const resolved = resolveLogPath(directory);
@@ -58268,8 +58296,10 @@ function readSkillUsageEntriesTail(directory, filters, maxBytes = TAIL_BYTES_DEF
   if (!_internals19.existsSync(logPath))
     return [];
   try {
+    const normalizedMaxBytes = Number.isFinite(maxBytes) ? maxBytes : TAIL_BYTES_DEFAULT;
+    const boundedMaxBytes = Math.min(Math.max(1, normalizedMaxBytes), MAX_TAIL_BYTES);
     const stat3 = _internals19.statSync(logPath);
-    const start2 = Math.max(0, stat3.size - maxBytes);
+    const start2 = Math.max(0, stat3.size - boundedMaxBytes);
     const fd = _internals19.openSync(logPath, "r");
     try {
       const readLen = stat3.size - start2;
@@ -58469,7 +58499,7 @@ async function applySkillUsageFeedback(directory, options) {
   }
   return { processed, bumps };
 }
-var _internals19, TAIL_BYTES_DEFAULT, COMPLIANCE_BOOST = 0.05, VIOLATION_DECAY = 0.1;
+var _internals19, TAIL_BYTES_DEFAULT, MAX_TAIL_BYTES, SKILL_USAGE_LOG_ROTATE_BYTES, SKILL_USAGE_LOG_MAX_ENTRIES_PER_SKILL = 500, COMPLIANCE_BOOST = 0.05, VIOLATION_DECAY = 0.1;
 var init_skill_usage_log = __esm(() => {
   init_knowledge_store();
   init_utils2();
@@ -58485,11 +58515,14 @@ var init_skill_usage_log = __esm(() => {
     openSync: fs15.openSync.bind(fs15),
     readSync: fs15.readSync.bind(fs15),
     closeSync: fs15.closeSync.bind(fs15),
+    pruneSkillUsageLog,
     resolveSourceKnowledgeIds,
     applySkillUsageFeedback,
     parseGeneratedFromKnowledge
   };
   TAIL_BYTES_DEFAULT = 64 * 1024;
+  MAX_TAIL_BYTES = TAIL_BYTES_DEFAULT;
+  SKILL_USAGE_LOG_ROTATE_BYTES = 1024 * 1024;
 });
 
 // src/hooks/curator.ts
@@ -105511,7 +105544,7 @@ async function skillPropagationGateBefore(directory, input, config3) {
       });
       if (sessionEntries.length > _internals58.MAX_SCORING_SESSION_ENTRIES) {
         scoringSkipped = true;
-        warn(`[skill-propagation-gate] skipping scoring — session has ${sessionEntries.length} entries (limit: ${_internals58.MAX_SCORING_SESSION_ENTRIES})`);
+        warn(`[skill-propagation-gate] skipping scoring — tail window has ${sessionEntries.length} session entries (limit: ${_internals58.MAX_SCORING_SESSION_ENTRIES})`);
       } else {
         const prompt = typeof input.args?.prompt === "string" ? String(input.args.prompt) : "";
         scored = availableSkills.map((skillPath) => {
@@ -128556,6 +128589,12 @@ function recoverTaskStateFromDelegations(taskId, directory) {
         advanceTaskState(session, taskId, "coder_delegated");
       } catch {}
     }
+    if (hasReviewer) {
+      recordStageBCompletion(session, taskId, "reviewer");
+    }
+    if (hasTestEngineer) {
+      recordStageBCompletion(session, taskId, "test_engineer");
+    }
     if (hasReviewer) {
       const stateNow = getTaskState(session, taskId);
       if (stateNow === "coder_delegated" || stateNow === "pre_check_passed") {
@@ -130120,6 +130159,7 @@ async function initializeOpenCodeSwarm(ctx) {
   const summaryConfig = SummaryConfigSchema.parse(config3.summaries ?? {});
   const toolSummarizerHook = createToolSummarizerHook(summaryConfig, ctx.directory);
   const knowledgeConfig = KnowledgeConfigSchema.parse(config3.knowledge ?? {});
+  const skillPropagationConfig = SkillPropagationConfigSchema.parse(config3.skillPropagation ?? {});
   const knowledgeCuratorHook = knowledgeConfig.enabled ? createKnowledgeCuratorHook(ctx.directory, knowledgeConfig) : undefined;
   const hivePromoterHook = knowledgeConfig.enabled && knowledgeConfig.hive_enabled ? createHivePromoterHook(ctx.directory, knowledgeConfig) : undefined;
   const knowledgeInjectorHook = knowledgeConfig.enabled ? createKnowledgeInjectorHook(ctx.directory, knowledgeConfig) : undefined;
@@ -130576,6 +130616,9 @@ async function initializeOpenCodeSwarm(ctx) {
       },
       (input, output) => {
         try {
+          if (!skillPropagationConfig.enabled) {
+            return Promise.resolve();
+          }
           const p = input;
           return skillPropagationTransformScan(ctx.directory, output, p.sessionID);
         } catch {
@@ -130656,12 +130699,12 @@ async function initializeOpenCodeSwarm(ctx) {
         agent: input.agent,
         sessionID: input.sessionID
       }, KnowledgeApplicationConfigSchema.parse(config3.knowledge_application ?? {}));
-      const skillResult = await skillPropagationGateBefore(ctx.directory, {
+      const skillResult = skillPropagationConfig.enabled ? await skillPropagationGateBefore(ctx.directory, {
         tool: input.tool,
         agent: input.agent,
         sessionID: input.sessionID,
         args: input.args
-      }, { enabled: true });
+      }, skillPropagationConfig) : { blocked: false, reason: null, recommendedSkills: undefined };
       if (skillResult.blocked) {
         throw new Error(skillResult.reason ?? "Blocked by skill propagation gate");
       }

package/dist/state.d.ts

@@ -425,6 +425,22 @@ export declare function advanceTaskState(session: AgentSessionState, taskId: str
     minimumMembers?: number;
     requireAllMembers?: boolean;
 }): void;
+/**
+ * Returns true iff calling `advanceTaskState(session, taskId, newState)` would
+ * succeed without throwing. Use this predicate to guard call sites that cannot
+ * catch `INVALID_TASK_STATE_TRANSITION` as a control-flow mechanism.
+ *
+ * Does NOT perform side effects or emit telemetry.
+ *
+ * @param session - The agent session state
+ * @param taskId - The task identifier
+ * @param newState - The requested new state
+ * @param councilConfig - Optional council quorum config (required when newState='complete')
+ */
+export declare function canAdvanceTaskState(session: AgentSessionState, taskId: string, newState: TaskWorkflowState, councilConfig?: {
+    minimumMembers?: number;
+    requireAllMembers?: boolean;
+}): boolean;
 /**
  * Advance the per-task workflow state machine AND persist the corresponding
  * plan.json status at meaningful workflow boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.52.1",
+	"version": "7.52.3",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",