opencode-swarm 6.57.0 → 6.59.0

package/dist/plan/ledger.d.ts

@@ -123,17 +123,67 @@ export declare function appendLedgerEvent(directory: string, eventInput: LedgerE
     expectedHash?: string;
     planHashAfter?: string;
 }): Promise<LedgerEvent>;
+/**
+ * Append a ledger event with optimistic retry on stale-writer conflicts.
+ *
+ * When another writer advances the ledger between the caller's read and
+ * their append, `appendLedgerEvent` throws `LedgerStaleWriterError`. This
+ * helper wraps that call in a bounded retry loop, refreshing the
+ * `expectedHash` concurrency token against the current plan.json before
+ * each retry.
+ *
+ * IMPORTANT: refreshing the hash is only safe when the event input is
+ * *still semantically valid* after the intervening write. For audit
+ * events computed from an in-memory plan the caller is about to persist,
+ * it is always valid. For `task_status_changed` events, pass a
+ * `verifyValid` callback that returns false when the transition no
+ * longer applies (e.g. the task's on-disk status already matches the
+ * `to_status`, or has moved past it). When `verifyValid` returns false,
+ * the retry loop exits and the helper returns `null` to signal that the
+ * event was skipped — it is not an error.
+ *
+ * @param directory - Working directory containing `.swarm/plan-ledger.jsonl`
+ * @param eventInput - Event to append (required fields minus auto-generated)
+ * @param options - Concurrency and retry configuration:
+ *   - expectedHash: the hash of plan.json the caller observed (REQUIRED)
+ *   - planHashAfter: precomputed hash of the mutated plan
+ *   - maxRetries: max stale-writer retries (default: 3)
+ *   - backoffMs: base delay in milliseconds (default: 10; exponential)
+ *   - verifyValid: callback invoked before each retry to confirm the
+ *     event input is still meaningful. Returning false aborts and
+ *     resolves the helper to `null`.
+ * @returns The written LedgerEvent, or `null` if verifyValid aborted.
+ * @throws LedgerStaleWriterError if retries are exhausted.
+ */
+export declare function appendLedgerEventWithRetry(directory: string, eventInput: LedgerEventInput, options: {
+    expectedHash: string;
+    planHashAfter?: string;
+    maxRetries?: number;
+    backoffMs?: number;
+    verifyValid?: () => Promise<boolean> | boolean;
+}): Promise<LedgerEvent | null>;
 /**
  * Take a snapshot event and append it to the ledger.
  * The snapshot embeds the full Plan payload for ledger-only rebuild.
  *
  * @param directory - The working directory
  * @param plan - The current plan state to snapshot
- * @param options - Optional configuration
+ * @param options - Optional configuration:
+ *   - planHashAfter: precomputed hash of the mutated plan (bypasses the
+ *     on-disk plan.json read when available)
+ *   - source: attribution string stored on the ledger event. Defaults to
+ *     `'takeSnapshotEvent'`. Use `'critic_approved'` to mark a snapshot as
+ *     the immutable phase-approved checkpoint readable by
+ *     `loadLastApprovedPlan`.
+ *   - approvalMetadata: optional free-form metadata embedded into the
+ *     snapshot payload (e.g. phase number, verdict, summary) so that
+ *     downstream readers can filter without decoding prompts.
  * @returns The LedgerEvent that was written
  */
 export declare function takeSnapshotEvent(directory: string, plan: Plan, options?: {
     planHashAfter?: string;
+    source?: string;
+    approvalMetadata?: Record<string, unknown>;
 }): Promise<LedgerEvent>;
 /**
  * Options for replayFromLedger
@@ -193,4 +243,44 @@ export declare function quarantineLedgerSuffix(directory: string, badSuffix: str
  * @returns Reconstructed Plan from ledger events, or null if replay fails
  */
 export declare function replayWithIntegrity(directory: string): Promise<Plan | null>;
+/**
+ * Metadata describing an approved snapshot recovered from the ledger.
+ */
+export interface ApprovedSnapshotInfo {
+    /** The immutable plan payload captured at critic approval time */
+    plan: Plan;
+    /** The ledger sequence number of the snapshot event */
+    seq: number;
+    /** ISO 8601 timestamp of the snapshot event */
+    timestamp: string;
+    /** Arbitrary metadata the caller attached (phase, verdict, summary, ...) */
+    approval?: Record<string, unknown>;
+    /** Hash of the plan payload at snapshot time */
+    payloadHash: string;
+}
+/**
+ * Find the most recent critic-approved immutable plan snapshot in the ledger.
+ *
+ * Snapshots are tagged at write time with a distinguishing `source` string
+ * (see `takeSnapshotEvent`). The `critic_approved` marker identifies snapshots
+ * persisted by the orchestrator after a phase Critic returns APPROVED. This
+ * function scans the ledger in reverse order and returns the first matching
+ * snapshot, including its embedded plan payload and approval metadata.
+ *
+ * Intended for use as a fallback when plan.json is lost, overwritten, or
+ * suspected of drift: the Architect can fall back to the last approved plan
+ * and the Critic can drift-check against it.
+ *
+ * SAFETY: when `expectedPlanId` is supplied, only snapshots whose event
+ * `plan_id` matches are considered. Callers MUST pass an expected identity
+ * whenever they have one (e.g. from the ledger's first `plan_created` anchor)
+ * to prevent cross-identity contamination: a stale `critic_approved` snapshot
+ * left in a reused directory could otherwise be resurrected as the active plan.
+ *
+ * @param directory - Working directory containing `.swarm/plan-ledger.jsonl`
+ * @param expectedPlanId - Optional plan identity filter. When provided, only
+ *   snapshots whose ledger event `plan_id` matches are considered.
+ * @returns The most recent approved snapshot info, or null if none exists
+ */
+export declare function loadLastApprovedPlan(directory: string, expectedPlanId?: string): Promise<ApprovedSnapshotInfo | null>;
 export {};

package/dist/plan/manager.d.ts

@@ -1,4 +1,4 @@
-import { type Plan, type TaskStatus } from '../config/plan-schema';
+import { type Plan, type RuntimePlan, type TaskStatus } from '../config/plan-schema';
 /** Reset the startup ledger check flag. For testing only. */
 export declare function resetStartupLedgerCheck(): void;
 /**
@@ -24,7 +24,7 @@ export declare function regeneratePlanMarkdown(directory: string, plan: Plan): P
  * 3. .swarm/plan.md exists only -> migrate from plan.md, save both files, return Plan
  * 4. Neither exists -> return null
  */
-export declare function loadPlan(directory: string): Promise<Plan | null>;
+export declare function loadPlan(directory: string): Promise<RuntimePlan | null>;
 /**
  * Validate against PlanSchema (throw on invalid), write to .swarm/plan.json via atomic temp+rename pattern,
  * then derive and write .swarm/plan.md

package/dist/services/preflight-service.d.ts

@@ -12,7 +12,7 @@
  * Callable by background flow (from preflight.requested events).
  */
 /** Preflight check types */
-export type PreflightCheckType = 'lint' | 'tests' | 'secrets' | 'evidence' | 'version';
+export type PreflightCheckType = 'lint' | 'tests' | 'secrets' | 'evidence' | 'version' | 'req_coverage';
 /** Individual check status */
 export interface PreflightCheckResult {
     type: PreflightCheckType;

package/dist/tools/index.d.ts

@@ -24,6 +24,7 @@ export { pkg_audit } from './pkg-audit';
 export { type PlaceholderFinding, type PlaceholderScanInput, type PlaceholderScanResult, placeholder_scan, placeholderScan, } from './placeholder-scan';
 export { type PreCheckBatchInput, type PreCheckBatchResult, pre_check_batch, runPreCheckBatch, type ToolResult, } from './pre-check-batch';
 export { type QualityBudgetInput, type QualityBudgetResult, quality_budget, qualityBudget, } from './quality-budget';
+export { req_coverage } from './req-coverage';
 export { retrieve_summary } from './retrieve-summary';
 export { type SastScanFinding, type SastScanInput, type SastScanResult, sast_scan, sastScan, } from './sast-scan';
 export type { SavePlanArgs, SavePlanResult } from './save-plan';
@@ -36,6 +37,7 @@ import { suggestPatch } from './suggest-patch';
 export { suggestPatch };
 export type { SuggestPatchArgs } from './suggest-patch';
 export declare const suggest_patch: typeof suggestPatch;
+export { lint_spec } from './lint-spec';
 export { symbols } from './symbols';
 export { type SyntaxCheckFileResult, type SyntaxCheckInput, type SyntaxCheckResult, syntax_check, syntaxCheck, } from './syntax-check';
 export { test_runner } from './test-runner';

package/dist/tools/lint-spec.d.ts

@@ -0,0 +1,2 @@
+import { createSwarmTool } from './create-tool';
+export declare const lint_spec: ReturnType<typeof createSwarmTool>;

package/dist/tools/req-coverage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Requirement coverage tool for analyzing FR requirements against touched files.
+ * Reads .swarm/spec.md for FR-### requirements and checks coverage against
+ * files touched during a phase via evidence files.
+ */
+import { tool } from '@opencode-ai/plugin';
+declare const OBLIGATION_KEYWORDS: readonly ["MUST", "SHOULD", "SHALL"];
+type ObligationLevel = (typeof OBLIGATION_KEYWORDS)[number];
+interface Requirement {
+    id: string;
+    obligation: ObligationLevel | null;
+    text: string;
+    status: 'covered' | 'missing';
+    filesSearched: string[];
+}
+interface RequirementMatch {
+    id: string;
+    obligation: ObligationLevel | null;
+    text: string;
+}
+/**
+ * Extract all FR-### requirements from spec content.
+ * For each requirement, identifies obligation level (MUST/SHOULD/SHALL) and text.
+ */
+export declare function extractRequirements(specContent: string): RequirementMatch[];
+/**
+ * Extract obligation level (MUST/SHOULD/SHALL) and requirement text from a line.
+ */
+export declare function extractObligationAndText(id: string, lineText: string): RequirementMatch | null;
+/**
+ * Read evidence files from .swarm/evidence/{taskId}/ directory structure.
+ * Returns list of source files that were touched during the specified phase.
+ * Evidence is stored at .swarm/evidence/<taskId>/evidence.json (e.g., 1.1, 2.3.1).
+ * Only directories with numeric task IDs matching the phase prefix are processed.
+ */
+export declare function readTouchedFiles(evidenceDir: string, phase: number, cwd: string): string[];
+/**
+ * Search a file for keywords from a requirement.
+ * Returns true if any keyword is found.
+ */
+export declare function searchFileForKeywords(filePath: string, keywords: string[], cwd: string): boolean;
+/**
+ * Analyze coverage for a requirement against touched files.
+ */
+export declare function analyzeRequirementCoverage(requirement: RequirementMatch, touchedFiles: string[], cwd: string): Requirement;
+export declare const req_coverage: ReturnType<typeof tool>;
+export {};

package/dist/tools/tool-names.d.ts

@@ -3,7 +3,7 @@
  * Used for constants and agent setup references.
  */
 /** Union type of all valid tool names */
-export type ToolName = 'diff' | 'syntax_check' | 'placeholder_scan' | 'imports' | 'lint' | 'secretscan' | 'sast_scan' | 'build_check' | 'pre_check_batch' | 'quality_budget' | 'symbols' | 'complexity_hotspots' | 'schema_drift' | 'todo_extract' | 'evidence_check' | 'check_gate_status' | 'completion_verify' | 'sbom_generate' | 'checkpoint' | 'pkg_audit' | 'test_runner' | 'detect_domains' | 'gitingest' | 'retrieve_summary' | 'extract_code_blocks' | 'phase_complete' | 'save_plan' | 'update_task_status' | 'write_retro' | 'write_drift_evidence' | 'declare_scope' | 'knowledge_query' | 'doc_scan' | 'doc_extract' | 'curator_analyze' | 'knowledge_add' | 'knowledge_recall' | 'knowledge_remove' | 'co_change_analyzer' | 'search' | 'batch_symbols' | 'suggest_patch';
+export type ToolName = 'diff' | 'syntax_check' | 'placeholder_scan' | 'imports' | 'lint' | 'secretscan' | 'sast_scan' | 'build_check' | 'pre_check_batch' | 'quality_budget' | 'symbols' | 'complexity_hotspots' | 'schema_drift' | 'todo_extract' | 'evidence_check' | 'check_gate_status' | 'completion_verify' | 'sbom_generate' | 'checkpoint' | 'pkg_audit' | 'test_runner' | 'detect_domains' | 'gitingest' | 'retrieve_summary' | 'extract_code_blocks' | 'phase_complete' | 'save_plan' | 'update_task_status' | 'lint_spec' | 'write_retro' | 'write_drift_evidence' | 'declare_scope' | 'knowledge_query' | 'doc_scan' | 'doc_extract' | 'curator_analyze' | 'knowledge_add' | 'knowledge_recall' | 'knowledge_remove' | 'co_change_analyzer' | 'search' | 'batch_symbols' | 'suggest_patch' | 'req_coverage';
 /** Readonly array of all tool names */
 export declare const TOOL_NAMES: readonly ToolName[];
 /** Set for O(1) tool name validation */

package/dist/tools/write-drift-evidence.d.ts

@@ -14,6 +14,8 @@ export interface WriteDriftEvidenceArgs {
     verdict: 'APPROVED' | 'NEEDS_REVISION';
     /** Human-readable summary of the drift verification */
     summary: string;
+    /** Requirement coverage report from req_coverage tool */
+    requirementCoverage?: string;
 }
 /**
  * Execute the write_drift_evidence tool.

package/dist/types/events.d.ts

@@ -72,4 +72,22 @@ export interface AuthorityHandoffResolvedEvent {
     newAgent: string;
     reason: 'task_complete' | 'stale_delegation' | 'conflict_escalation' | 'manual_reset';
 }
-export type V619Event = SoundingBoardConsultedEvent | ArchitectLoopDetectedEvent | PrecedentManipulationDetectedEvent | CoderSelfAuditEvent | CoderRetryCircuitBreakerEvent | AgentConflictDetectedEvent | AuthorityHandoffResolvedEvent;
+export interface SpecStaleDetectedEvent {
+    type: 'spec_stale_detected';
+    timestamp: string;
+    phase: number;
+    specHash_plan: string;
+    specHash_current: string | null;
+    reason: string;
+    planTitle: string;
+}
+export interface SpecDriftAcknowledgedEvent {
+    type: 'spec_drift_acknowledged';
+    timestamp: string;
+    phase: number;
+    planTitle: string;
+    acknowledgedBy: string;
+    previousHash: string;
+    newHash: string | null;
+}
+export type V619Event = SoundingBoardConsultedEvent | ArchitectLoopDetectedEvent | PrecedentManipulationDetectedEvent | CoderSelfAuditEvent | CoderRetryCircuitBreakerEvent | AgentConflictDetectedEvent | AuthorityHandoffResolvedEvent | SpecStaleDetectedEvent | SpecDriftAcknowledgedEvent;

package/dist/utils/spec-hash.d.ts

@@ -0,0 +1,15 @@
+import type { Plan } from '../config/plan-schema';
+/**
+ * Computes SHA-256 hex hash of `.swarm/spec.md` content in the given directory.
+ * Returns null if the file does not exist (does NOT throw).
+ */
+export declare function computeSpecHash(directory: string): Promise<string | null>;
+/**
+ * Determines if the spec file has changed since the plan was saved.
+ * Plans created before this feature (no specHash) are exempt from staleness checks.
+ */
+export declare function isSpecStale(directory: string, plan: Plan): Promise<{
+    stale: boolean;
+    reason?: string;
+    currentHash?: string | null;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "6.57.0",
+	"version": "6.59.0",
 	"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",