@llblab/pi-actors 0.46.1 → 0.48.0

package/skills/swarm/SKILL.md

@@ -1,465 +1,84 @@
 ---
 name: swarm
-description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
+description: Use when work needs multiple actors or subagents for independent implementation, artifact generation, review, delegated audit, research, or coordinated decomposition and integration.
 ---
 
 # Swarm
 
-Subagent orchestration: delegated review, quorum consensus, scoped locks, clean-context merge, and post-merge review.
+Use multi-actor execution only when at least two scopes or evidence lenses are meaningfully independent and parallelism, clean-context judgement, or quorum confidence is worth the coordination overhead. Do not swarm a task that one bounded agent can complete safely, a task whose architecture is still unsettled, or concurrent mutations of one shared contract.
 
-## Purpose
+Read `actors` first for generic Recipe, spawn, Run, Trace, Control, artifact, and lifecycle operation. This Skill owns only multi-actor methodology: decomposition, scope ownership, independence, synthesis, integration, and completion proof.
 
-Run subagents safely and predictably through reusable orchestration contracts. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. Components are direct files under `recipes/` and use exact `swarm/<recipe>` identities, including `swarm/lens-review`, `swarm/quorum-review`, `swarm/research-synthesis`, and `swarm/development-tasking`; they remain components rather than automatic tools.
+## Coordinator topology
 
-Activation rule: load this skill before launching multiple independent actors or subagents, even when the work is creative artifact generation rather than code review. The coordinator owns decomposition, disjoint scopes, launch correctness, result integration, and final validation; participants may choose local content or implementation details independently inside their assigned boundaries.
+A swarm can be coordinated without an external gateway. In this model the current host agent is the declarative control plane, the actor kernel creates explicit participant Runs, and companion transports provide ingress or presence without owning hidden agent creation. The coordinator retains user authority, global context, decomposition, shared-surface ownership, integration, and final validation; participants own bounded concrete tasks and report evidence.
 
-Swarm is independent. It must not require concrete sibling skill names, private repositories, local model aliases, or a specific tool registry layout. Local agents may bind the contracts to their own tools, command templates, model names, and review protocols.
+This resembles gateway orchestration in dependency direction but not in ownership: the coordinator is itself an agent instance with inspectable Runs, not an infrastructure service that implicitly creates sessions. Preserve that distinction in prompts, docs, recovery, and target routing.
 
-Maintain this skill as a living orchestration standard. When real swarm work exposes better decomposition shapes, lock etiquette, quorum rules, checkpoint semantics, failure modes, or trade-offs, fold those lessons back here as durable guidance instead of leaving them only in one-off transcripts or backlog notes.
+Once work is delegated, keep the coordinator available for decisions and integration instead of duplicating participant implementation. Wait for terminal follow-up by default; use meaningful attention or evidence-based timers for overdue work rather than a tight inspection loop.
 
-## Core Concepts
+## Reasoning allocation
 
-- `Orchestrator`: Main agent. Coordinates subagents, owns safety, and writes final artifacts.
-- `Subagent`: Bounded delegated model call for review, audit, merge, or scoped implementation.
-- `Scope`: File, directory, module, or logical domain that a subagent operates on.
-- `Lock`: Read or write ownership of a scope for bounded time.
-- `Quorum`: Multiple independent subagents reviewing the same target.
-- `Merger`: Clean-context fifth subagent that synthesizes raw quorum outputs.
-- `Reviewer`: Post-merge reviewer that checks report quality, not the original domain by default.
-- `Async Run Adapter`: Local async binding that starts, tracks, lists, tails, and cancels swarm runs through a generic lifecycle runtime.
-- `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
-- `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
-- `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
-- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn under `~/.pi/agent/recipes/drafts`. It can be replayed by an explicit `.json` / `.md` path (relative entry paths use invocation `cwd`) and later promoted into the active tool Recipe root after enough dogfood.
-- `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
-- `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
-- `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.
+Allocate reasoning by role instead of making one long thread implement and judge itself:
 
-## Swarm Principle
+- Bounded implementation/authorship participants default to reasoning off when the task card fixes scope, invariants, checks, and escalation. Enable reasoning only when unresolved diagnosis or local design judgement is part of their assignment.
+- Reviewers default to independent medium reasoning and clean context. For consequential work, several reviewers with distinct lenses or repeated independent judgement usually provide better error discovery than increasing one author's reasoning and relying on self-review.
+- Synthesizers and integrators use medium reasoning because they reconcile evidence, conflicts, shared contracts, and retained state.
+- The coordinator decides whether review fanout is worth its cost, preserves dissent, and never treats reviewer count as evidence quality by itself.
 
-One agent should hold one lens. Many independent lenses make the whole judgement stronger. Parallel lenses make the whole judgement faster.
+Do not change a running participant's profile merely because policy changed. Replace or add a later independent review only when fresh evidence is still needed.
 
-Swarm is useful because focused subagents usually perform better than one overloaded model trying to reason about every concern at once. Each subagent receives the same target but a narrower mandate, reducing cognitive load and making misses less correlated. The merger then synthesizes the independent observations into one decision-grade artifact.
+## Choose the shape
 
-Use swarm when the work benefits from parallel cognitive lenses, not merely because more models are available. A good swarm decomposes the task into review surfaces that are independently meaningful, then preserves agreement, disagreement, and minority high-impact findings.
+| Need | Shape | Primary Recipe |
+| --- | --- | --- |
+| Different risk lenses on one target | Lens swarm | `swarm/lens-review` |
+| Independent judges for one exact claim | Quorum | `swarm/quorum-review` |
+| Evidence map plus contradiction-preserving synthesis | Research swarm | `swarm/research-synthesis` |
+| Competing architecture directions and one smallest next slice | Architecture swarm | `swarm/architect` |
+| Bounded implementation assignment with scope critique | Development tasking | `swarm/development-tasking` |
+| Multi-lens ship/readiness verdict | Readiness review | `swarm/review-readiness` |
 
-## Swarm Shapes
+Use different lenses for breadth and repeated independent judges for confidence. Combine both only for high-stakes work where the added cost is justified. `swarm/subagent-*` Recipes are maintained composition components; start from a primary Recipe unless building an intentional custom composition.
 
-Distinguish breadth from confidence before launching subagents.
+## Coordinator protocol
 
-```text
-Lens Swarm = different lenses on one object
-Quorum     = one lens, multiple independent judges
-```
+The coordinator owns the whole result even when participants choose local implementation details.
 
-`Lens Swarm` optimizes coverage. It asks which aspects matter and sends focused agents through different mandates: architecture, security, tests, UX, release, docs, economics, governance, or operations. Use it for brainstorming, product design, architecture exploration, development planning, and broad risk review.
+1. State the goal, non-goals, evidence standard, integration owner, and stop condition.
+2. Partition work into disjoint read or write scopes. Give shared contracts one owner.
+3. Give each participant a bounded task card with allowed scope, avoided scope, expected artifact, checks, and escalation rule.
+4. Assign each participant an explicit execution profile and isolation mode under the reasoning-allocation contract.
+5. Preflight required model/tool access before expensive fanout.
+6. Launch independent work without cross-contaminating lenses. Do not let participants silently expand scope.
+7. Preserve every terminal result, including failures, disagreements, and partial evidence; avoid doing participant work in the coordinator while a valid owner remains active.
+8. Merge through one named synthesizer or integrator. Resolve conflicts from explicit intent and invariants, not textual convenience.
+9. Run fresh integrated validation and, for consequential outputs, an independent post-merge review.
+10. Report complete, degraded, or insufficient-data status honestly; name residual owners and next actions.
 
-`Quorum` optimizes confidence. It keeps the lens constant and varies models, seeds, prompts, or independent instances so several judges answer the same question. Use it mostly for verification: high-stakes review, security verdicts, ambiguous bug hypotheses, publish readiness, and final confidence checks.
+## Scope and coordination rules
 
-`Lens Swarm of Quorums` optimizes both breadth and confidence. Each important lens gets its own mini-quorum, and a merger synthesizes across lenses while preserving vote counts and minority high-impact findings. This is expensive and should be reserved for high-stakes systems such as money movement, blockchain protocols, governance, security boundaries, migrations, or public releases.
+- One writable scope has one owner. Parallel readers may share a stable target.
+- Public contracts, schemas, central configuration, and integration surfaces require exclusive ownership.
+- Concurrent writers use disjoint paths, isolated worktrees, or declared patch/artifact outputs.
+- Shared ledgers, lockfiles, generated contracts, metadata, schemas, release surfaces, and cross-domain configuration belong to one named integrator unless a task card transfers one surface to another exclusive owner.
+- Participants record shared-surface and other out-of-scope needs in handoff instead of editing them opportunistically.
+- Reasoning and model profiles are task-card inputs, not implicit properties of the whole swarm.
+- Coordinator checkpoints are bounded decision requests, not free-form actor chat.
+- Locks support scope ownership but do not replace coordinator judgement. Every lock must be bounded and releasable.
+- One integrator owns merge order, conflict resolution, and final validation.
+- A zero-conflict merge is not proof of semantic compatibility.
 
-Decision rule:
+## Evidence and quorum rules
 
-```text
-Need breadth?     Use Lens Swarm.
-Need confidence?  Use Quorum.
-Need both?        Use Lens Swarm of Quorums.
-```
+- Every material finding traces to inspected evidence or explicit uncertainty.
+- Preserve minority high-impact findings and contradictions; consensus does not erase them.
+- Keep reviewer evidence separate from merger findings.
+- If successful evidence is below the requested threshold, return degraded or insufficient data instead of inventing quorum.
+- Use a clean-context merger for serious quorum work. Use a fresh post-merge reviewer when the result drives code, security, architecture, money, governance, migrations, or release decisions.
 
-## Work Modes
+See [review swarms](./references/review-swarms.md) for lens, quorum, synthesis, and conflict-evidence detail. See [development swarms](./references/development-swarm.md) for task cards, write ownership, handoffs, conflict reports, and integration.
 
-Swarm is not only for review. The same lens discipline supports ideation, research-style exploration, planning, implementation coordination, and verification.
+## Stop rules
 
-### Brainstorm Swarm
-
-Purpose: turn many possible futures into one recommended direction.
-
-Typical lenses:
-
-- Product/user value
-- Operator UX
-- Protocol or platform cleanliness
-- Implementation pragmatism
-- Adoption/growth
-- Skeptic/failure modes
-- Constraints and portability
-
-Merger output:
-
-- Recommended direction
-- Alternatives considered and rejected
-- Open questions
-- First implementation slice
-- Risks and validation gates
-
-Brainstorm swarms should not vote mechanically. They should preserve creative tension and synthesize a direction that fits constraints.
-
-### Research Swarm
-
-Purpose: turn a broad question into evidence-backed synthesis without letting one agent's search path dominate the answer.
-
-Typical lenses:
-
-- Question/scope formulation
-- Source discovery
-- Source verification
-- Synthesis and contradiction mapping
-- Devil's advocate / counter-evidence
-- Ethics, policy, or stakeholder impact when relevant
-
-Research swarm rules:
-
-1. Scope first: the coordinator defines the question, non-goals, source classes, and stop condition before launching evidence work.
-2. Search and verification are separate lenses when stakes are high; the searcher finds candidates, the verifier checks quality and support.
-3. Every material claim in synthesis must trace to a source note, inspected artifact, or explicit uncertainty statement.
-4. Contradictory evidence is preserved as a first-class output, not hidden by consensus language.
-5. Evidence checkpoints block synthesis when sources are insufficient, unverifiable, conflicted, or ethically unsafe to use.
-
-Merger output:
-
-- Bounded research question
-- Evidence map with confidence and source quality
-- Areas of convergence and contradiction
-- Limitations and not-checkable claims
-- Recommended decision or next evidence slice
-
-Research swarms are for inquiry and synthesis, not automatic publication pipelines. Keep report formatting local to the caller's domain.
-
-### Development Swarm
-
-Purpose: turn one accepted direction into coordinated slices.
-
-Recommended flow:
-
-```text
-Planner → Lens Swarm → Merger → Scoped Implementers → Integrator → Review Swarm
-```
-
-Use scoped write locks or a repository-local soft-lock manifest when multiple implementers may edit files. Keep implementation agents bounded by module, artifact, or responsibility: code, tests, docs, examples, migration, or release notes. Prefer one owner per writable scope and run verification with fresh reviewers after implementation.
-
-### Consensus-First Build Swarm
-
-Purpose: create one coherent artifact from several expert lenses without making every participant write the artifact.
-
-Recommended flow:
-
-```text
-Lens proposers → shared room consensus → named implementer → QA reviewer → finalizer
-```
-
-Use this shape for creative/product artifacts, demos, single-file deliverables, docs, specs, prompts, and other work where parallel implementation would fragment the result. Lens proposers should post concrete constraints, proposals, and handoff notes to the shared room but should not mutate files. One named implementer inspects the room transcript and owns the first artifact write. A fresh QA reviewer inspects the artifact plus room evidence and reports issues back to the room. The implementer/finalizer then applies only the review-grounded fixes and emits the final artifact message.
-
-Failure mode: if the runner only asks all lenses to chat and then writes a report, it can "succeed" without producing the requested artifact. Guard against this with explicit artifact assertions, role-specific write permissions, and a finalizer that checks artifact existence/size/content before `run.done`.
-
-### Small-Team Development Swarm
-
-For 2–4 implementation agents, prefer the dedicated MAWP reference instead of expanding the general Swarm skill. The portable idea is simple: isolate writable work surfaces, give each agent a bounded task card, preserve handoff evidence, and merge through one integrator.
-
-Use [`references/development-swarm.md`](./references/development-swarm.md) for concrete worktree/branch flow, task-card templates, soft-lock manifests, conflict reports, coordinator checkpoints, and merge rules.
-
-### Review Swarm
-
-Purpose: turn one result into many risk lenses and a decision-grade verdict.
-
-Use lens swarm for broad coverage, quorum for confidence on one critical judgement, or both for high-stakes releases. In adapters that expose current session model/thinking policy, default ordinary same-policy review swarms to that current policy and require explicit args only when intentionally varying models or thinking levels. Run a cheap model/tool preflight before launching expensive reviewer fanout; if it fails, use the `ACTOR_PREFLIGHT_FAILED` stage/model/error-class/prompt-file diagnostic to choose explicit override args instead of rerunning blindly. For Skill-owned review swarms, tune `min_successful_reviewers`, `reviewer_concurrency`, `subagent_ttl_ms`, and `merge_policy` instead of manual reruns; preserve partial reports and label the outcome `complete`, `degraded`, or `insufficient_data`. The final report should separate consensus findings, minority findings, merger findings, risks, and recommended next actions.
-
-A review swarm synthesis must not fabricate claims. Every final finding should trace to a reviewer note, checked artifact, command output, source, or explicit merger rationale. Devil's Advocate critical findings must be preserved or explicitly disproved with evidence.
-
-## Lens Catalog
-
-Choose lenses by risk. Do not run every lens by default; select the smallest set that covers the failure modes of the work.
-
-### General Software Lenses
-
-- `Architecture`: module boundaries, dependency direction, cohesion, coupling, extensibility, and long-term ownership.
-- `Correctness`: functional behavior, edge cases, invariants, state transitions, and input/output contracts.
-- `Bug Hunter`: likely defects, race conditions, null/empty cases, off-by-one errors, and broken assumptions.
-- `Security`: injection, privilege boundaries, path handling, secrets, deserialization, unsafe shell/process use, and abuse cases.
-- `Tests`: coverage quality, missing regressions, fixture realism, flaky risk, and validation gates.
-- `Performance`: algorithmic cost, latency, memory, IO, batching, backpressure, and hot paths.
-- `Concurrency`: locks, cancellation, timeouts, idempotency, retries, ordering, and stale state.
-- `Data Integrity`: migrations, schema compatibility, durability, rollback, deduplication, and corruption risk.
-- `API Compatibility`: public contract drift, backwards compatibility, versioning, deprecation, and client impact.
-- `Operator UX`: observability, error messages, status, logs, recovery paths, safe defaults, and support burden.
-- `Developer UX`: onboarding, local setup, naming, examples, docs, type ergonomics, and debugging clarity.
-- `Product UX`: user journey, surprising behavior, accessibility, copy, affordances, and feedback loops.
-- `Release`: changelog truth, version bump, package contents, CI gates, publish risk, and rollback readiness.
-- `Documentation`: README accuracy, examples, conceptual consistency, and stale references.
-- `Compliance/Policy`: licenses, privacy, retention, consent, audit trails, and organizational constraints.
-- `Incident Response`: blast radius, detection, containment, rollback, forensics, and runbook quality.
-- `SRE/Reliability`: availability, graceful degradation, monitoring, quotas, rate limits, and dependency failure.
-- `Maintainability`: simplicity, naming, duplication, dead code, testability, and future change cost.
-- `Spec Consistency`: whether code, docs, tests, prompts, and changelog describe the same behavior.
-
-### Complex System / Blockchain Lenses
-
-Use these for blockchain, distributed systems, financial protocols, governance, or adversarial environments.
-
-- `Protocol Invariants`: conservation laws, supply rules, ledger consistency, finality assumptions, and impossible states.
-- `Consensus Safety`: fork choice, quorum thresholds, validator behavior, equivocation, reorg handling, and liveness tradeoffs.
-- `Economic Security`: incentives, MEV, griefing, sybil cost, fee dynamics, slashing, reward leakage, and manipulation paths.
-- `Smart Contract Safety`: reentrancy, authorization, upgradeability, storage layout, oracle trust, token standards, and invariant tests.
-- `Cryptography`: key management, signature/domain separation, nonce use, randomness, hash commitments, and proof assumptions.
-- `Cross-Chain/Bridge`: message replay, finality mismatch, validator set drift, withdrawal delays, and custody assumptions.
-- `Governance`: proposal lifecycle, quorum rules, timelocks, emergency powers, capture risk, and voter/operator UX.
-- `Treasury/Accounting`: balance reconciliation, fee distribution, rounding, precision, reserves, and auditability.
-- `Adversarial Simulation`: attacker goals, cheapest exploit path, denial-of-service vectors, sandwiching, and liquidation games.
-- `Network/P2P`: peer discovery, gossip propagation, eclipse risk, bandwidth limits, spam resistance, and partition behavior.
-- `Node Operations`: sync, snapshots, pruning, backups, observability, upgrades, config safety, and rollback.
-- `Formal Methods`: invariant specification, model checking candidates, property tests, and proof gaps.
-- `Regulatory Surface`: custody, KYC/AML implications, sanctions, securities risk, data retention, and jurisdictional assumptions.
-
-## Tool Contracts
-
-These are abstract tool contracts. Register them in whatever local tool layer exists. Concrete syntax is an adapter detail outside this skill.
-
-- `swarm_review`: single subagent review.
-- `swarm_quorum`: multi-model independent review.
-- `swarm_claim`: acquire a scoped read/write lock.
-- `swarm_release`: release a scoped lock.
-- `swarm_merge`: synthesize raw quorum outputs.
-- `swarm_post_merge_review`: review the merged report quality.
-
-## File Handoff
-
-Prefer path handoff over attachment syntax. Put the target path directly in the subagent prompt:
-
-```text
-Review this local file: /path/to/file.md. First read it from disk.
-```
-
-Attachment syntax is optional local optimization, not a swarm contract. Path handoff keeps the skill portable across wrappers without attachment arguments.
-
-## `swarm_review`
-
-Single subagent review.
-
-`Inputs`:
-
-- `scope`: file path, directory, module, or logical domain.
-- `model`: model identifier in the local environment.
-- `prompt`: optional review lens or task-specific instructions.
-- `thinking`: optional reasoning depth.
-- `tools`: optional local tool allowlist.
-- `timeout`: timeout in seconds.
-
-`Behavior`:
-
-1. Optionally claim a read lock for the scope.
-2. Spawn one subagent with a prompt that includes the scope path.
-3. Require the subagent to read the target from disk before judging it.
-4. Return the subagent's raw output.
-5. Release the lock if one was claimed.
-
-`Reference prompt`:
-
-```text
-Review this local scope: <scope>.
-First read it from disk.
-Use the local review protocol if available.
-Report white spots, contradictions, evidence, and risks.
-```
-
-## Run Adapter
-
-Detached execution is an adapter concern, not a portable Swarm-script requirement. When the host offers Runs, launch the composed Recipe, return its id, and rely on terminal follow-up rather than blocking or polling.
-
-`Progress contract`: expose bounded structured Trace, logs, artifacts, status, timestamps, and final result evidence. Treat Trace as a retained suffix and attention as a wake hint; write durable task cards, checkpoints, and large evidence to artifacts before signaling attention. Read completeness and Control capacity through existing Run inspection rather than scraping output. Artifact size/lifecycle remains separate from Trace/Control quotas.
-
-`Resumable checkpoint goal`: a controlled agent-backed Run may preserve context and accept a declared Control. Control saturation rejects before admission and admitted work does not expire; lifecycle recovery remains host-owned. When the host cannot preserve context, write a handoff artifact and launch a clean-context Run while marking the context loss explicitly.
-
-`Cancellation boundary`: terminate only an owned active generation whose process identity the runtime can prove. Stale pid reuse must fail closed.
-
-## Stable Multi-Agent Review Rules
-
-- Prefer independent read-only reviewers so they do not converge before synthesis.
-- Treat Trace, artifacts, and immutable reviewer results as methodology evidence.
-- Smoke-test provider/model availability before expensive fanout.
-- Keep methodology and runtime split: Swarm chooses decomposition, quorum, lenses, lock discipline, and merge shape; the Run kernel supplies execution, Trace, Control, artifacts, and lifecycle safety.
-
-## Persistent Implementer Pattern
-
-Use long-lived controlled services only when repeated assignments justify them. Keep task selection with the orchestrator and use explicit artifacts or task cards for claims/results. Resource exclusion may use the optional `resource-locker`; it does not become swarm authority. Prefer multiple scoped Runs over a peer protocol.
-
-## `swarm_quorum`
-
-Multi-model review by independent subagents.
-
-`Inputs`:
-
-- `scope`: target path or domain.
-- `models`: 2-6 model identifiers.
-- `prompt`: shared review lens.
-- `thinking`: per-model or shared reasoning depth.
-- `timeout`: per-subagent or whole-quorum timeout.
-- `merge_mode`: merge behavior, default `consensus-first`.
-- `merger_model`: explicit model for the clean merger.
-
-`Behavior`:
-
-1. Claim a shared read lock when the target is local and stable.
-2. Spawn one subagent per model concurrently unless a local rate limit requires throttling.
-3. Give every subagent the same target path and review lens.
-4. Preserve every raw output.
-5. Release the lock.
-6. Run a clean-context merger subagent.
-7. Store or return the merged report.
-8. Optionally run post-merge review.
-
-`Reference binding`: Implement this contract through a local adapter such as a command-template composer, registered tool, or async run. The portable Swarm skill intentionally does not ship a runtime-specific quorum runner.
-
-`Serious quorum rule`: For high-stakes review, the merger is not the current orchestrator. The merger is a fifth clean-context subagent.
-
-## Lock Protocol
-
-Locks prevent subagents from interfering with shared scopes. Locks are optional for read-only review, but required for concurrent mutation.
-
-### Lock Fields
-
-- `scope`: Scope identifier, usually a path or domain label.
-- `owner`: Subagent or quorum run that owns the lock.
-- `type`: `read` or `write`.
-- `acquired`: Acquisition time.
-- `ttl`: Time-to-live in seconds.
-- `expires`: Expiry time derived from acquisition plus TTL.
-
-### Conflict Rules
-
-- `read` request with no lock: allow.
-- `read` request with existing `read`: allow.
-- `read` request with existing `write`: conflict unless stale.
-- `write` request with no lock: allow.
-- `write` request with existing `read` or `write`: conflict unless stale.
-
-### Lifecycle
-
-1. `acquire`: prune stale locks, then check conflicts.
-2. `hold`: run the bounded subagent task.
-3. `release`: remove the entry.
-4. `expire`: any later lock operation may prune stale entries.
-
-`TTL rule`: Every lock must have a TTL. A lock without expiry is invalid.
-
-`Adapter implementation`: Use a local actor/runtime adapter when automation, TTL enforcement, or machine-readable lock state is needed. The portable Swarm skill defines lock semantics but does not ship a lock runtime.
-
-## Validation
-
-After changing Swarm adapter contracts or Skill documentation, validate the local distribution with whatever checks the host project provides. At minimum, review the text for boundary drift:
-
-- no dependency on a specific extension, actor runtime, registry, recipe store, or CLI runner;
-- no bundled broad coordinator or lock runtime as portable Swarm core;
-- no hard-coded model names, private paths, or transport-specific message syntax in the methodology contract;
-- adapter examples remain examples, not requirements.
-
-If a host package ships a Swarm self-test, treat it as a local packaging gate rather than part of the portable methodology.
-
-## Merge Protocol
-
-The merger is not a passive formatter. The merger is the final synthesis agent and can materially affect the output by choosing labels, grouping findings, deciding severity, preserving minority signals, and adding grounded judgement.
-
-`Merger influence`: High.
-
-`Merger role`: Read all raw outputs, deduplicate, rank, preserve dissent, and produce one decision-grade artifact. The merger may add its own finding only as `merger finding` and only when grounded in evidence.
-
-`Merger isolation`: For serious quorum work, the merger should be a dedicated clean-context subagent with explicit model, thinking level, and minimal access. The orchestrator provides the input bundle and writes the final artifact after the merger returns.
-
-`Orchestrator merge exception`: The orchestrator may merge quick, low-stakes, or exploratory quorum runs. The report must say the merge was not isolated.
-
-### Merge Parameters
-
-- `merger_model`: Explicit synthesis model. Required for quorum reports.
-- `merger_context`: Clean or inherited context. Default `clean` for serious quorum.
-- `merger_tools`: Tool access granted to merger. Prefer none if raw text is embedded; otherwise read-only access to raw outputs.
-- `merger_thinking`: Reasoning depth. Use `medium` normally, `high` for architecture, security, money, governance, migrations, or specs.
-- `merge_mode`: Synthesis style. Default `consensus-first`.
-- `consensus_threshold`: Votes needed to promote. Use `3/4` for critical promotion and `2/4` for major discussion by default.
-- `minority_policy`: Treatment of unique findings. Preserve high-impact, evidence-backed minority findings.
-- `attribution`: Which model found what. Required for quorum reports.
-- `raw_retention`: Keep raw outputs until the final report is accepted.
-
-### Merge Modes
-
-- `faithful`: Minimal editing; preserves subagent wording and uncertainty.
-- `consensus-first`: Groups by agreement and preserves dissent separately.
-- `risk-first`: Promotes high-impact minority findings even without consensus.
-- `design-synthesis`: Converts findings into decisions and repair order.
-
-### Merge Guardrails
-
-- Preserve raw outputs until the final report is accepted.
-- Do not hide model disagreement.
-- Do not drop high-impact minority findings only for lack of consensus.
-- Do not over-promote repeated low-value nitpicks.
-- Keep model attribution for every major finding.
-- Keep merger identity explicit: model, context, thinking, and tools.
-- Separate `consensus finding`, `minority finding`, and `merger finding`.
-- Separate current-quorum votes from prior-run corroboration.
-
-## Post-Merge Review
-
-Run a reviewer on the merged report when the output will drive code, architecture, security, money, governance, migrations, or specifications.
-
-`Purpose`: Review the review. The reviewer checks whether the merger preserved evidence, ranked severity honestly, avoided hallucinated synthesis, kept minority high-impact findings, and produced an actionable artifact.
-
-`Reviewer input`:
-
-- Target scope
-- Raw subagent outputs
-- Merged report
-- Merge parameters
-- Intended use of the report
-
-`Reviewer output`: Meta-findings about report quality, not a second domain review unless explicitly requested.
-
-### Post-Merge Review Lens
-
-- `Evidence`: Does each major finding trace to raw outputs or clearly marked merger evidence?
-- `Severity`: Are labels justified by failure impact?
-- `Consensus`: Was agreement counted honestly?
-- `Purity`: Is current quorum separate from prior context?
-- `Minority`: Were unique high-impact findings preserved?
-- `Bias`: Did the merger impose an unsupported narrative?
-- `Actionability`: Are repair order, scope, and gates named?
-- `Consistency`: Do maps, headers, and attribution agree?
-- `Compression`: Were caveats or disagreements lost?
-
-### Post-Merge Decisions
-
-- `Accept`: Report is decision-grade.
-- `Accept with notes`: Report is useful, with caveats.
-- `Revise merge`: Rerun merger with adjusted parameters.
-- `Rerun quorum`: Raw outputs are too weak, divergent, or under-scoped.
-- `Escalate`: Run cross-merge with another clean merger.
-
-## Error Handling
-
-- `LOCK_CONFLICT`: Retry, back off, or choose another scope.
-- `SUBAGENT_TIMEOUT`: Keep partial results and release locks by TTL.
-- `COORDINATOR_INPUT_REQUIRED`: Pause only if the adapter can preserve subagent context; otherwise write a checkpoint artifact and stop degraded for coordinator replanning.
-- `MODEL_FAILURE`: Continue with fewer votes and mark degraded quorum.
-- `MERGE_FAILURE`: Return `INSUFFICIENT_DATA` or rerun merger.
-- `REVIEW_FAILURE`: Keep merged report and mark post-review missing.
-
-## Composition Contract
-
-This skill composes with capabilities, not concrete sibling skills:
-
-- Local tool registry for reusable command-template adapters
-- Local review and implementation protocols
-- Scoped lock standard with TTL
-- Subagent runner with file-read access
-- Artifact writer owned by the orchestrator
-
-Do not make swarm depend on a specific sibling skill, repository, model alias, or tool registry. The orchestrator may tell subagents to use the local review protocol when one exists.
-
-## Portability Lens
-
-- `Lock protocol`: Mandatory kernel.
-- `Quorum review`: Optional capability.
-- `Clean merger`: Mandatory for serious quorum.
-- `Post-merge review`: Required for high-stakes outputs.
-- `Command templates`: Local adapter.
-- `Test scripts`: Protocol validation aid.
-
-Operational tools, recipes, transport bindings, and runtime-specific adapters belong to the host project documentation, not this methodology skill.
+Stop or replan when scopes overlap, a participant needs an undeclared shared contract, evidence cannot meet the threshold, provider/tool preflight fails, conflict changes the architecture, no integrator owns the result, or integrated validation is unavailable. Do not compensate with extra agents, repeated blind retries, shared mutable work, or coordinator-written consensus unsupported by participant evidence.