opencode-swarm 6.60.0 → 6.61.0

package/README.md

@@ -759,14 +759,17 @@ Use glob patterns for complex path matching:
 - `?` — Match single character: `test?.js` matches `test1.js`, `testa.js`
 - Uses [picomatch](https://github.com/micromatch/picomatch) for cross-platform compatibility
 
+**Path Normalization and Symlinks:**
+Paths are resolved via `realpathSync` before matching, which resolves symlinks and prevents path-traversal escapes. However, if a symlink's target does not exist, `realpathSync` throws and the fallback returns the symlink's own path (unresolved). A dangling symlink inside an `allowedPrefix` directory will therefore pass prefix-based checks even if its intended target is outside the project. Use `blockedExact` or `blockedGlobs` to deny known dangling-symlink paths explicitly.
+
 **Evaluation Order:**
 1. `readOnly` check (if true, deny all writes)
 2. `blockedExact` (exact path matches, highest priority)
 3. `blockedGlobs` (glob pattern matches)
 4. `allowedExact` (exact path matches, overrides prefix/glob restrictions)
 5. `allowedGlobs` (glob pattern matches)
-6. `allowedPrefix` (prefix matches)
-7. `blockedPrefix` (prefix matches)
+6. `blockedPrefix` (prefix matches)
+7. `allowedPrefix` (prefix matches)
 8. `blockedZones` (zone classification)
 
 </details>

package/dist/agents/architect.commands-list.adversarial.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/architect.commands-list.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/index.js

@@ -18296,7 +18296,7 @@ ${warnings.map((w) => `  - ${w}`).join(`
 `)}` : "";
   const cautionMessage = `
 
-\u26A0\uFE0F  Caution: Spec drift was acknowledged \u2014 verify that the implementation still matches the spec before proceeding.`;
+\u26A0\uFE0F  Warning: Spec drift was acknowledged \u2014 verify that the implementation still matches the spec before proceeding.`;
   return baseMessage + warningMessage + cautionMessage;
 }
 
@@ -18564,7 +18564,8 @@ var AGENT_TOOL_MAP = {
     "imports",
     "retrieve_summary",
     "symbols",
-    "knowledge_recall"
+    "knowledge_recall",
+    "req_coverage"
   ],
   critic_drift_verifier: [
     "complexity_hotspots",
@@ -18968,7 +18969,8 @@ var GuardrailsConfigSchema = exports_external.object({
     ]),
     require_reviewer_test_engineer: exports_external.boolean().default(true)
   }).optional(),
-  profiles: exports_external.record(exports_external.string(), GuardrailsProfileSchema).optional()
+  profiles: exports_external.record(exports_external.string(), GuardrailsProfileSchema).optional(),
+  block_destructive_commands: exports_external.boolean().default(true)
 });
 var WatchdogConfigSchema = exports_external.object({
   scope_guard: exports_external.boolean().default(true),
@@ -32067,7 +32069,7 @@ var DeltaSpecSchema = exports_external.union([
 ]);
 // src/tools/create-tool.ts
 function classifyToolError(error93) {
-  const msg = (error93 instanceof Error ? error93.message : String(error93)).toLowerCase();
+  const msg = (error93 instanceof Error ? error93.message ?? "" : String(error93)).toLowerCase();
   if (msg.includes("not registered") || msg.includes("unknown tool"))
     return "not_registered";
   if (msg.includes("not whitelisted") || msg.includes("not allowed"))
@@ -36802,6 +36804,10 @@ async function discoverBuildCommands(workingDir, options) {
   const skipped = [...profileSkipped];
   for (const ecosystem of ECOSYSTEMS) {
     if (coveredEcosystems.has(ecosystem.ecosystem)) {
+      skipped.push({
+        ecosystem: ecosystem.ecosystem,
+        reason: `Covered by profile detection`
+      });
       continue;
     }
     if (!checkToolchain(ecosystem.toolchainCommands)) {
@@ -42649,7 +42655,8 @@ Run \`/swarm evidence ${result.task_id ?? "unknown"}\` to view it, or \`/swarm s
 var COMMAND_REGISTRY = {
   "acknowledge-spec-drift": {
     handler: (ctx) => handleAcknowledgeSpecDriftCommand(ctx.directory, ctx.args),
-    description: "Acknowledge that the spec has drifted from the plan and suppress further warnings"
+    description: "Acknowledge that the spec has drifted from the plan and suppress further warnings",
+    args: ""
   },
   status: {
     handler: (ctx) => handleStatusCommand(ctx.directory, ctx.agents),
@@ -42695,112 +42702,156 @@ var COMMAND_REGISTRY = {
   },
   "sync-plan": {
     handler: (ctx) => handleSyncPlanCommand(ctx.directory, ctx.args),
-    description: "Ensure plan.json and plan.md are synced"
+    description: "Ensure plan.json and plan.md are synced",
+    args: ""
   },
   benchmark: {
     handler: (ctx) => handleBenchmarkCommand(ctx.directory, ctx.args),
-    description: "Show performance metrics [--cumulative] [--ci-gate]"
+    description: "Show performance metrics [--cumulative] [--ci-gate]",
+    args: "--cumulative, --ci-gate"
   },
   export: {
     handler: (ctx) => handleExportCommand(ctx.directory, ctx.args),
-    description: "Export plan and context as JSON"
+    description: "Export plan and context as JSON",
+    args: "",
+    details: "Exports the current plan and context as JSON to stdout. Useful for piping to external tools or debugging swarm state."
   },
   evidence: {
     handler: (ctx) => handleEvidenceCommand(ctx.directory, ctx.args),
-    description: "Show evidence bundles [taskId]"
+    description: "Show evidence bundles [taskId]",
+    args: "<taskId>",
+    details: 'Displays review results, test verdicts, and other evidence bundles for the given task ID (e.g., "2.1").'
   },
   "evidence summary": {
     handler: (ctx) => handleEvidenceSummaryCommand(ctx.directory),
     description: "Generate evidence summary with completion ratio and blockers",
-    subcommandOf: "evidence"
+    subcommandOf: "evidence",
+    args: "",
+    details: "Generates a summary showing completion ratio across all tasks, lists blockers, and identifies missing evidence."
   },
   "evidence-summary": {
     handler: (ctx) => handleEvidenceSummaryCommand(ctx.directory),
     description: "Generate evidence summary with completion ratio and blockers",
-    subcommandOf: "evidence"
+    subcommandOf: "evidence",
+    args: "",
+    details: "Generates a summary showing completion ratio across all tasks, lists blockers, and identifies missing evidence."
   },
   archive: {
     handler: (ctx) => handleArchiveCommand(ctx.directory, ctx.args),
-    description: "Archive old evidence bundles [--dry-run]"
+    description: "Archive old evidence bundles [--dry-run]",
+    details: "Archives evidence bundles older than max_age_days (config, default 90) or beyond max_bundles cap (config, default 1000). --dry-run previews which bundles would be archived without deleting them. Applies two-tier retention: age-based first, then count-based on oldest remaining.",
+    args: "--dry-run"
   },
   curate: {
     handler: (ctx) => handleCurateCommand(ctx.directory, ctx.args),
-    description: "Run knowledge curation and hive promotion review"
+    description: "Run knowledge curation and hive promotion review",
+    args: ""
   },
   "dark-matter": {
     handler: (ctx) => handleDarkMatterCommand(ctx.directory, ctx.args),
-    description: "Detect hidden file couplings via co-change NPMI analysis"
+    description: "Detect hidden file couplings via co-change NPMI analysis",
+    args: "--threshold <number>, --min-commits <number>"
   },
   close: {
     handler: (ctx) => handleCloseCommand(ctx.directory, ctx.args),
-    description: "Use /swarm close to close the swarm project and archive evidence"
+    description: "Use /swarm close to close the swarm project and archive evidence",
+    details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs safe git ff-only to main. Resets agent sessions and delegation chains. Reads .swarm/close-lessons.md for explicit lessons and runs curation.",
+    args: "--prune-branches"
   },
   simulate: {
     handler: (ctx) => handleSimulateCommand(ctx.directory, ctx.args),
-    description: "Dry-run impact analysis of proposed changes [--target <glob>]"
+    description: "Dry-run hidden coupling analysis with configurable thresholds",
+    args: "--threshold <number>, --min-commits <number>"
   },
   analyze: {
     handler: (ctx) => handleAnalyzeCommand(ctx.directory, ctx.args),
-    description: "Analyze spec.md vs plan.md for requirement coverage gaps"
+    description: "Analyze spec.md vs plan.md for requirement coverage gaps",
+    args: ""
   },
   clarify: {
     handler: (ctx) => handleClarifyCommand(ctx.directory, ctx.args),
-    description: "Clarify and refine an existing feature specification"
+    description: "Clarify and refine an existing feature specification",
+    args: "[description-text]"
   },
   specify: {
     handler: (ctx) => handleSpecifyCommand(ctx.directory, ctx.args),
-    description: "Generate or import a feature specification [description]"
+    description: "Generate or import a feature specification [description]",
+    args: "[description-text]"
   },
   promote: {
     handler: (ctx) => handlePromoteCommand(ctx.directory, ctx.args),
-    description: "Manually promote lesson to hive knowledge"
+    description: "Manually promote lesson to hive knowledge",
+    details: "Promotes a lesson directly to hive knowledge (--category flag sets category) or references an existing swarm lesson by ID (--from-swarm). Validates lesson text before promotion. Either direct text or --from-swarm ID is required.",
+    args: "--category <category>, --from-swarm <lesson-id>, <lesson-text>"
   },
   reset: {
     handler: (ctx) => handleResetCommand(ctx.directory, ctx.args),
-    description: "Clear swarm state files [--confirm]"
+    description: "Clear swarm state files [--confirm]",
+    details: "DELETES plan.md, context.md, and summaries/ directory from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag \u2014 without it, displays a warning and tips to export first.",
+    args: "--confirm (required)"
   },
   "reset-session": {
     handler: (ctx) => handleResetSessionCommand(ctx.directory, ctx.args),
-    description: "Clear session state while preserving plan, evidence, and knowledge"
+    description: "Clear session state while preserving plan, evidence, and knowledge",
+    details: "Deletes only .swarm/session/state.json and any other session files. Clears in-memory agent sessions and delegation chains. Preserves plan, evidence, and knowledge for cross-session continuity.",
+    args: ""
   },
   rollback: {
     handler: (ctx) => handleRollbackCommand(ctx.directory, ctx.args),
-    description: "Restore swarm state to a checkpoint <phase>"
+    description: "Restore swarm state to a checkpoint <phase>",
+    details: "Restores .swarm/ state by directly overwriting files from a checkpoint directory (checkpoints/phase-<N>). Writes rollback event to events.jsonl. Without phase argument, lists available checkpoints. Partial failures are reported but processing continues.",
+    args: "<phase-number>"
   },
   retrieve: {
     handler: (ctx) => handleRetrieveCommand(ctx.directory, ctx.args),
-    description: "Retrieve full output from a summary <id>"
+    description: "Retrieve full output from a summary <id>",
+    args: "<summary-id>",
+    details: "Loads the full tool output that was previously summarized (referenced by IDs like S1, S2). Use when you need the complete output instead of the truncated summary."
   },
   handoff: {
     handler: (ctx) => handleHandoffCommand(ctx.directory, ctx.args),
-    description: "Prepare state for clean model switch (new session)"
+    description: "Prepare state for clean model switch (new session)",
+    args: "",
+    details: "Generates handoff.md with full session state snapshot, including plan progress, recent decisions, and agent delegation history. Prepended to the next session prompt for seamless model switches."
   },
   turbo: {
     handler: (ctx) => handleTurboCommand(ctx.directory, ctx.args, ctx.sessionID),
-    description: "Toggle Turbo Mode for the active session [on|off]"
+    description: "Toggle Turbo Mode for the active session [on|off]",
+    args: "on, off",
+    details: 'Toggles Turbo Mode which skips non-critical QA gates for faster iteration. When enabled, the architect can proceed without waiting for all automated checks. Session-scoped \u2014 resets on new session. Use "on" or "off" to set explicitly, or toggle with no argument.'
   },
   "full-auto": {
     handler: (ctx) => handleFullAutoCommand(ctx.directory, ctx.args, ctx.sessionID),
-    description: "Toggle Full-Auto Mode for the active session [on|off]"
+    description: "Toggle Full-Auto Mode for the active session [on|off]",
+    args: "on, off",
+    details: 'Toggles Full-Auto Mode which enables autonomous execution without confirmation prompts. When enabled, the architect proceeds through implementation steps automatically. Session-scoped \u2014 resets on new session. Use "on" or "off" to set explicitly, or toggle with no argument.'
   },
   "write-retro": {
     handler: (ctx) => handleWriteRetroCommand(ctx.directory, ctx.args),
-    description: "Write a retrospective evidence bundle for a completed phase <json>"
+    description: "Write a retrospective evidence bundle for a completed phase <json>",
+    details: "Writes retrospective evidence bundle to .swarm/evidence/retro-{phase}/evidence.json. Required JSON: phase, summary, task_count, task_complexity, total_tool_calls, coder_revisions, reviewer_rejections, test_failures, security_findings, integration_issues. Optional: lessons_learned (max 5), top_rejection_reasons, task_id, metadata.",
+    args: "<json: {phase, summary, task_count, task_complexity, ...}>"
   },
   "knowledge migrate": {
     handler: (ctx) => handleKnowledgeMigrateCommand(ctx.directory, ctx.args),
     description: "Migrate knowledge entries to the current format",
-    subcommandOf: "knowledge"
+    subcommandOf: "knowledge",
+    details: "One-time migration from .swarm/context.md SME cache to .swarm/knowledge.jsonl. Skips if sentinel file .swarm/.knowledge-migrated exists, if context.md is absent, or if context.md is empty. Reports entries migrated, dropped (validation/dedup), and total processed.",
+    args: "<directory>"
   },
   "knowledge quarantine": {
     handler: (ctx) => handleKnowledgeQuarantineCommand(ctx.directory, ctx.args),
     description: "Move a knowledge entry to quarantine <id> [reason]",
-    subcommandOf: "knowledge"
+    subcommandOf: "knowledge",
+    details: 'Moves a knowledge entry to quarantine with optional reason string (defaults to "Quarantined via /swarm knowledge quarantine command"). Validates entry ID format (1-64 alphanumeric/hyphen/underscore). Quarantined entries are excluded from knowledge queries.',
+    args: "<entry-id> [reason]"
   },
   "knowledge restore": {
     handler: (ctx) => handleKnowledgeRestoreCommand(ctx.directory, ctx.args),
     description: "Restore a quarantined knowledge entry <id>",
-    subcommandOf: "knowledge"
+    subcommandOf: "knowledge",
+    details: "Restores a quarantined knowledge entry back to the active knowledge store by ID. Validates entry ID format (1-64 alphanumeric/hyphen/underscore). Entry must currently be in quarantine state.",
+    args: "<entry-id>"
   },
   knowledge: {
     handler: (ctx) => handleKnowledgeListCommand(ctx.directory, ctx.args),
@@ -42808,7 +42859,9 @@ var COMMAND_REGISTRY = {
   },
   checkpoint: {
     handler: (ctx) => handleCheckpointCommand(ctx.directory, ctx.args),
-    description: "Manage project checkpoints [save|restore|delete|list] <label>"
+    description: "Manage project checkpoints [save|restore|delete|list] <label>",
+    details: "save: creates named snapshot of current .swarm/ state. restore: soft-resets to checkpoint by overwriting current .swarm/ files. delete: removes named checkpoint. list: shows all checkpoints with timestamps. All subcommands require a label except list.",
+    args: "<save|restore|delete|list> <label>"
   }
 };
 var VALID_COMMANDS = Object.keys(COMMAND_REGISTRY);

package/dist/commands/index.d.ts

@@ -33,6 +33,7 @@ export { handleStatusCommand } from './status';
 export { handleSyncPlanCommand } from './sync-plan';
 export { handleTurboCommand } from './turbo';
 export { handleWriteRetroCommand } from './write-retro';
+export declare function buildHelpText(): string;
 /**
  * Creates a command.execute.before handler for /swarm commands.
  * Uses factory pattern to close over directory and agents.

package/dist/commands/index.help-text.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/registry-documentation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/registry-type.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/registry.d.ts

@@ -12,11 +12,23 @@ export type CommandEntry = {
     description: string;
     /** If true, this command is only accessible as a sub-key of a parent command */
     subcommandOf?: string;
+    /**
+     * 2-3 line behavioral summary: what the command does step-by-step,
+     * side effects, and safety guarantees.
+     */
+    details?: string;
+    /**
+     * Documents flags and positional arguments. Format: flags comma-separated with
+     * double-dash prefix, positional args in angle brackets.
+     * Example: args: '--dry-run, --confirm, <phase-number>'
+     */
+    args?: string;
 };
 export declare const COMMAND_REGISTRY: {
     readonly 'acknowledge-spec-drift': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Acknowledge that the spec has drifted from the plan and suppress further warnings";
+        readonly args: "";
     };
     readonly status: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
@@ -63,111 +75,155 @@ export declare const COMMAND_REGISTRY: {
     readonly 'sync-plan': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Ensure plan.json and plan.md are synced";
+        readonly args: "";
     };
     readonly benchmark: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show performance metrics [--cumulative] [--ci-gate]";
+        readonly args: "--cumulative, --ci-gate";
     };
     readonly export: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Export plan and context as JSON";
+        readonly args: "";
+        readonly details: "Exports the current plan and context as JSON to stdout. Useful for piping to external tools or debugging swarm state.";
     };
     readonly evidence: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Show evidence bundles [taskId]";
+        readonly args: "<taskId>";
+        readonly details: "Displays review results, test verdicts, and other evidence bundles for the given task ID (e.g., \"2.1\").";
     };
     readonly 'evidence summary': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Generate evidence summary with completion ratio and blockers";
         readonly subcommandOf: "evidence";
+        readonly args: "";
+        readonly details: "Generates a summary showing completion ratio across all tasks, lists blockers, and identifies missing evidence.";
     };
     readonly 'evidence-summary': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Generate evidence summary with completion ratio and blockers";
         readonly subcommandOf: "evidence";
+        readonly args: "";
+        readonly details: "Generates a summary showing completion ratio across all tasks, lists blockers, and identifies missing evidence.";
     };
     readonly archive: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Archive old evidence bundles [--dry-run]";
+        readonly details: "Archives evidence bundles older than max_age_days (config, default 90) or beyond max_bundles cap (config, default 1000). --dry-run previews which bundles would be archived without deleting them. Applies two-tier retention: age-based first, then count-based on oldest remaining.";
+        readonly args: "--dry-run";
     };
     readonly curate: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Run knowledge curation and hive promotion review";
+        readonly args: "";
     };
     readonly 'dark-matter': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Detect hidden file couplings via co-change NPMI analysis";
+        readonly args: "--threshold <number>, --min-commits <number>";
     };
     readonly close: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Use /swarm close to close the swarm project and archive evidence";
+        readonly details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs safe git ff-only to main. Resets agent sessions and delegation chains. Reads .swarm/close-lessons.md for explicit lessons and runs curation.";
+        readonly args: "--prune-branches";
     };
     readonly simulate: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
-        readonly description: "Dry-run impact analysis of proposed changes [--target <glob>]";
+        readonly description: "Dry-run hidden coupling analysis with configurable thresholds";
+        readonly args: "--threshold <number>, --min-commits <number>";
     };
     readonly analyze: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Analyze spec.md vs plan.md for requirement coverage gaps";
+        readonly args: "";
     };
     readonly clarify: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clarify and refine an existing feature specification";
+        readonly args: "[description-text]";
     };
     readonly specify: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Generate or import a feature specification [description]";
+        readonly args: "[description-text]";
     };
     readonly promote: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Manually promote lesson to hive knowledge";
+        readonly details: "Promotes a lesson directly to hive knowledge (--category flag sets category) or references an existing swarm lesson by ID (--from-swarm). Validates lesson text before promotion. Either direct text or --from-swarm ID is required.";
+        readonly args: "--category <category>, --from-swarm <lesson-id>, <lesson-text>";
     };
     readonly reset: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear swarm state files [--confirm]";
+        readonly details: "DELETES plan.md, context.md, and summaries/ directory from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag — without it, displays a warning and tips to export first.";
+        readonly args: "--confirm (required)";
     };
     readonly 'reset-session': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear session state while preserving plan, evidence, and knowledge";
+        readonly details: "Deletes only .swarm/session/state.json and any other session files. Clears in-memory agent sessions and delegation chains. Preserves plan, evidence, and knowledge for cross-session continuity.";
+        readonly args: "";
     };
     readonly rollback: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Restore swarm state to a checkpoint <phase>";
+        readonly details: "Restores .swarm/ state by directly overwriting files from a checkpoint directory (checkpoints/phase-<N>). Writes rollback event to events.jsonl. Without phase argument, lists available checkpoints. Partial failures are reported but processing continues.";
+        readonly args: "<phase-number>";
     };
     readonly retrieve: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Retrieve full output from a summary <id>";
+        readonly args: "<summary-id>";
+        readonly details: "Loads the full tool output that was previously summarized (referenced by IDs like S1, S2). Use when you need the complete output instead of the truncated summary.";
     };
     readonly handoff: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Prepare state for clean model switch (new session)";
+        readonly args: "";
+        readonly details: "Generates handoff.md with full session state snapshot, including plan progress, recent decisions, and agent delegation history. Prepended to the next session prompt for seamless model switches.";
     };
     readonly turbo: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Toggle Turbo Mode for the active session [on|off]";
+        readonly args: "on, off";
+        readonly details: "Toggles Turbo Mode which skips non-critical QA gates for faster iteration. When enabled, the architect can proceed without waiting for all automated checks. Session-scoped — resets on new session. Use \"on\" or \"off\" to set explicitly, or toggle with no argument.";
     };
     readonly 'full-auto': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Toggle Full-Auto Mode for the active session [on|off]";
+        readonly args: "on, off";
+        readonly details: "Toggles Full-Auto Mode which enables autonomous execution without confirmation prompts. When enabled, the architect proceeds through implementation steps automatically. Session-scoped — resets on new session. Use \"on\" or \"off\" to set explicitly, or toggle with no argument.";
     };
     readonly 'write-retro': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Write a retrospective evidence bundle for a completed phase <json>";
+        readonly details: "Writes retrospective evidence bundle to .swarm/evidence/retro-{phase}/evidence.json. Required JSON: phase, summary, task_count, task_complexity, total_tool_calls, coder_revisions, reviewer_rejections, test_failures, security_findings, integration_issues. Optional: lessons_learned (max 5), top_rejection_reasons, task_id, metadata.";
+        readonly args: "<json: {phase, summary, task_count, task_complexity, ...}>";
     };
     readonly 'knowledge migrate': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Migrate knowledge entries to the current format";
         readonly subcommandOf: "knowledge";
+        readonly details: "One-time migration from .swarm/context.md SME cache to .swarm/knowledge.jsonl. Skips if sentinel file .swarm/.knowledge-migrated exists, if context.md is absent, or if context.md is empty. Reports entries migrated, dropped (validation/dedup), and total processed.";
+        readonly args: "<directory>";
     };
     readonly 'knowledge quarantine': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Move a knowledge entry to quarantine <id> [reason]";
         readonly subcommandOf: "knowledge";
+        readonly details: "Moves a knowledge entry to quarantine with optional reason string (defaults to \"Quarantined via /swarm knowledge quarantine command\"). Validates entry ID format (1-64 alphanumeric/hyphen/underscore). Quarantined entries are excluded from knowledge queries.";
+        readonly args: "<entry-id> [reason]";
     };
     readonly 'knowledge restore': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Restore a quarantined knowledge entry <id>";
         readonly subcommandOf: "knowledge";
+        readonly details: "Restores a quarantined knowledge entry back to the active knowledge store by ID. Validates entry ID format (1-64 alphanumeric/hyphen/underscore). Entry must currently be in quarantine state.";
+        readonly args: "<entry-id>";
     };
     readonly knowledge: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
@@ -176,6 +232,8 @@ export declare const COMMAND_REGISTRY: {
     readonly checkpoint: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Manage project checkpoints [save|restore|delete|list] <label>";
+        readonly details: "save: creates named snapshot of current .swarm/ state. restore: soft-resets to checkpoint by overwriting current .swarm/ files. delete: removes named checkpoint. list: shows all checkpoints with timestamps. All subcommands require a label except list.";
+        readonly args: "<save|restore|delete|list> <label>";
     };
 };
 export type RegisteredCommand = keyof typeof COMMAND_REGISTRY;

package/dist/config/schema.d.ts

@@ -330,6 +330,7 @@ export declare const GuardrailsConfigSchema: z.ZodObject<{
         warning_threshold: z.ZodOptional<z.ZodNumber>;
         idle_timeout_minutes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    block_destructive_commands: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
 export declare const WatchdogConfigSchema: z.ZodObject<{
@@ -655,6 +656,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
             warning_threshold: z.ZodOptional<z.ZodNumber>;
             idle_timeout_minutes: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
+        block_destructive_commands: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     watchdog: z.ZodOptional<z.ZodObject<{
         scope_guard: z.ZodDefault<z.ZodBoolean>;

package/dist/hooks/guardrails.d.ts

@@ -103,6 +103,11 @@ export declare function validateAndRecordAttestation(dir: string, findingId: str
     valid: false;
     reason: string;
 }>;
+/**
+ * Clears all guardrails caches.
+ * Use this for test isolation or when guardrails config reloads at runtime.
+ */
+export declare function clearGuardrailsCaches(): void;
 type AgentRule = {
     readOnly?: boolean;
     blockedExact?: string[];