opencode-swarm 7.108.0 → 7.109.1

package/.opencode/skills/clarify-spec/SKILL.md

@@ -9,11 +9,13 @@ description: >
 This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
 
 ### MODE: CLARIFY-SPEC
-Activates when: `.swarm/spec.md` exists AND contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY with open markers.
+Activates when: `/swarm sdd status` reports a **single resolved EFFECTIVE spec** (non-null) AND it contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY with open markers.
 
-CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. If `.swarm/spec.md` does not exist, tell the user: "No spec found. Use `/swarm specify` to generate one first." and stop.
+`/swarm sdd status` reflects `readEffectiveSpecSync`, which returns **null** (NO effective spec) for: no sources at all, multiple competing sources (e.g. `openspec/` AND `.specify/`), multi-feature Spec-Kit without a selected feature, or any other unresolvable state. CLARIFY-SPEC does NOT activate in these null cases — tell the user: "No resolved effective spec exists. Disambiguate with `/swarm sdd project --source <source>` or `--feature <feature>`, or run `/swarm specify` to generate one first." and stop.
 
-1. Read `.swarm/spec.md` (read current spec FIRST before making any changes).
+CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. Always consult `/swarm sdd status` to determine the effective spec source before proceeding.
+
+1. Read the **effective spec** resolved by `/swarm sdd status` (native `.swarm/spec.md` OR OpenSpec `openspec/` OR Spec-Kit `.specify/` — read the resolved spec FIRST before making any changes).
 2. Scan for ambiguities beyond explicit `[NEEDS CLARIFICATION]` markers:
    - Vague adjectives ("fast", "secure", "user-friendly") without measurable targets
    - Requirements that overlap or potentially conflict with each other
@@ -28,10 +30,14 @@ CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. If `.swarm/spec.md` does not
    - Offer 2–4 multiple-choice options for each question
    - Mark the recommended option with reasoning (e.g., "Recommended: Option 2 because…")
    - Allow free-form input as an alternative to the options
-5. After each accepted answer:
-   - Immediately update `.swarm/spec.md` with the resolution
-   - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer
-   - If the answer invalidates an earlier requirement, update it to remove the contradiction
+5. After each accepted answer, write the resolution to the **resolved effective source** (source-aware write-back):
+    - **NATIVE effective spec** (`.swarm/spec.md` exists): update `.swarm/spec.md` with the resolution directly.
+    - **NON-NATIVE effective spec** (openspec/specify-only, NO native `.swarm/spec.md`): do NOT write `.swarm/spec.md` — this would silently shadow the non-native source. Instead:
+      - (a) If the resolved source supports in-place edits (e.g., OpenSpec sections), update the source artifacts directly.
+      - (b) If no in-place edit path exists, ask the user: "The effective spec lives in `<source>`. To persist this resolution as a native spec, run `/swarm sdd project` first to materialize one, or I can stop here. Proceed?" — if the user consents to project, materialize via `/swarm sdd project` then write `.swarm/spec.md`; otherwise stop.
+      - (c) If neither (a) nor (b) applies, stop and tell the user the clarification cannot be auto-written to a non-native source without a projection step.
+    - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer.
+    - If the answer invalidates an earlier requirement, update it to remove the contradiction.
 6. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
 7. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).
 
@@ -39,9 +45,9 @@ CLARIFY-SPEC RULES:
 - FR-ID increment rule: When adding new requirements, find the highest existing FR-ID and increment from there (FR-001 → FR-002). Never reuse or skip FR-IDs.
 - One question at a time — never ask multiple questions in the same message.
 - Do not modify any part of the spec that was not affected by the accepted answer.
-- Always write the accepted answer back to spec.md before presenting the next question.
+- Always write the accepted answer back to the resolved effective source before presenting the next question. Never write `.swarm/spec.md` in a non-native (openspec/specify-only) repo — see step 5 source-aware write-back rule.
 - Max 8 questions per session — if limit reached, report remaining ambiguities and stop.
-- Do not create or overwrite the spec file — only refine what exists.
+- Do not create, overwrite, or shadow the spec file — only refine what exists. In non-native (openspec/specify-only) repos, never silently materialize a `.swarm/spec.md` that would shadow the effective source.
 
 ### Scoped Funnel Protocol (CLARIFY-SPEC only)
 

package/.opencode/skills/critic-gate/SKILL.md

@@ -11,6 +11,7 @@ This protocol is loaded on demand by the architect stub in src/agents/architect.
 ### MODE: CRITIC-GATE
 Delegate plan to the active swarm's critic agent for review BEFORE any implementation begins.
 - Send the full plan.md content and codebase context summary
+- Explicitly reference "plan.md" or "critic-gate" in the dispatch prompt text. This lets the mechanical approval-recording gate reliably detect the review and record the critic's APPROVED verdict, which the EXECUTE-phase coder gate then requires.
 - **APPROVED** → Proceed to MODE: EXECUTE
 - **NEEDS_REVISION** → Revise the plan based on critic feedback, then resubmit (max 2 cycles)
 - **REJECTED** → Inform the user of fundamental issues and ask for guidance before proceeding
@@ -26,11 +27,12 @@ You MUST NOT proceed to MODE: EXECUTE without printing this checklist with fille
 CRITIC-GATE TRIGGER: Run ONCE when you first write the complete .swarm/plan.md.
 Do NOT re-run CRITIC-GATE before every project phase.
 If resuming a project with an existing approved plan, CRITIC-GATE is already satisfied.
+Caveat: this assumption breaks if the plan lacks a `plan_critic_gate`-tagged approval snapshot (e.g. a plan approved before this mechanical gate existed, or one where the recording heuristic didn't fire) — in that case the first coder dispatch will fail with `PLAN_CRITIC_GATE_VIOLATION`. If that happens, do not assume CRITIC-GATE is satisfied; re-run it and get a fresh APPROVED verdict.
 
 6j. SPEC-GATE (Execute BEFORE any save_plan call):
-- The save_plan tool will REJECT if .swarm/spec.md does not exist (enforced at the tool level via SWARM_SKIP_SPEC_GATE env var bypass).
-- Before calling save_plan, verify spec.md is present using lint_spec.
-- If spec.md is absent: do NOT call save_plan. Use /swarm specify to create a spec first, or inform the user.
+- An effective spec exists iff `/swarm sdd status` reports a resolved spec (it reflects `readEffectiveSpecSync`, which returns null — NO effective spec — for no sources, multiple competing sources (openspec+specify), multi-feature Spec-Kit without a selected feature, or any unresolvable state). `save_plan` rejects (SPEC_REQUIRED) when `/swarm sdd status` reports no resolved spec. The gate is overridable via `SWARM_SKIP_SPEC_GATE=1`.
+- Before calling save_plan, verify an effective spec exists (via `/swarm sdd status` or `lint_spec`).
+- If no effective spec exists: do NOT call save_plan. Generate one first — native via `/swarm specify`, or via the agent-invocable `/swarm sdd project` (from SDD sources, after consent).
 - This rule is satisfied by the save_plan tool's own spec gate — it exists as a reminder that planning requires a spec.
 
 6k. SPEC-STALENESS GUARD:
@@ -60,7 +62,13 @@ If resuming a project with an existing approved plan, CRITIC-GATE is already sat
 
 6l. OBLIGATION TRACEABILITY CHECK (FR-003):
 - Before the critic's substantive rubric, the critic MUST cross-reference every
-  MUST/SHALL SC-### obligation in .swarm/spec.md against the plan tasks.
+  MUST/SHALL SC-### obligation in the EFFECTIVE spec against the plan tasks.
+  An effective spec exists iff `/swarm sdd status` reports a resolved spec (it
+  reflects `readEffectiveSpecSync`, which returns null — NO effective spec — for
+  no sources, multiple competing sources (openspec+specify), multi-feature
+  Spec-Kit without a selected feature, or any unresolvable state). Obligations
+  are traced only against the resolved effective spec; in a null/unresolved
+  state there is nothing to trace (this check is not applicable).
 - If ANY MUST/SHALL SC-### has zero corresponding plan tasks, the critic MUST
   return VERDICT: REJECTED enumerating each unmapped obligation.
 - The critic MUST evaluate coverage against the FULL plan — each task's

package/.opencode/skills/execute/SKILL.md

@@ -55,6 +55,7 @@ All other gates: failure → return to coder. No self-fixes. No workarounds.
     → Subsequent `pre_check_batch` calls with `phase: <N>` will automatically diff against this baseline — only NEW findings (not in baseline) drive the fail verdict.
     -> PREFLIGHT CHECKLIST: Before first coder delegation, answer "SAST baseline captured before first coder delegation? yes/no/disabled/error". If the answer is no, do not delegate to coder; run 5b-BASE first. If disabled or error, record the exact tool result.
 5b. the active swarm's coder agent - Implement (if designer scaffold produced, include it as INPUT).
+    → If this dispatch fails with `PLAN_CRITIC_GATE_VIOLATION`: the plan has no current critic-approved snapshot (commonly a plan approved before this mechanical gate existed). Do NOT retry the coder dispatch as-is — re-run MODE: CRITIC-GATE to get a fresh critic `APPROVED` verdict, then retry this step.
 5b-bis. **CODER OUTPUT VERIFICATION**: After the coder reports completion, do NOT accept the self-report alone. Run `diff` (step 5c) and inspect at least one of the modified files yourself to confirm the change exists. The coder may report DONE without having produced any diff. A 30-second read of the changed file(s) catches this failure mode. This is NOT a separate explorer dispatch — the existing `diff` tool at step 5c is the verification mechanism; the key discipline is checking that `diff` returns actual changes before proceeding, rather than forwarding the coder's self-report to the next gate.
 5c. Run `diff` tool. If `hasContractChanges` → the active swarm's explorer agent integration analysis. If COMPATIBILITY SIGNALS=INCOMPATIBLE or MIGRATION_SURFACE=yes → coder retry. If COMPATIBILITY SIGNALS=COMPATIBLE and MIGRATION_SURFACE=no → proceed.
     → REQUIRED: Print "diff: [PASS | CONTRACT CHANGE — details]"

package/.opencode/skills/phase-wrap/SKILL.md

@@ -62,7 +62,7 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
 4. Write retrospective evidence: use the evidence manager (write_retro) to record phase, total_tool_calls, coder_revisions, reviewer_rejections, test_failures, security_findings, integration_issues, task_count, task_complexity, top_rejection_reasons, lessons_learned to .swarm/evidence/. Reset Phase Metrics in context.md to 0.
 4.5. Run `evidence_check` to verify all completed tasks have required evidence (review + test). If gaps found, note in retrospective lessons_learned. Optionally run `pkg_audit` if dependencies were modified during this phase. Optionally run `schema_drift` if API routes were modified during this phase.
 5. Run `sbom_generate` with scope='changed' to capture post-implementation dependency snapshot (saved to `.swarm/evidence/sbom/`). This is a non-blocking step - always proceeds to summary.
-5.5. **Drift verification**: Conditional on .swarm/spec.md existence — if spec.md does not exist, skip silently and proceed to step 5.55. If spec.md exists, delegate to the active swarm's critic_drift_verifier agent with DRIFT-CHECK context:
+5.5. **Drift verification**: Conditional on an EFFECTIVE spec existing (determined via `/swarm sdd status` or `readEffectiveSpecSync` — native `.swarm/spec.md`, OpenSpec `openspec/`, or Spec-Kit `.specify/`). If NO effective spec exists at all, skip silently. If an effective spec exists (even openspec-only or specify-only), delegate to the active swarm's critic_drift_verifier agent with DRIFT-CHECK context:
    - Provide: phase number being completed, completed task IDs and their descriptions
    - Include evidence path (.swarm/evidence/) for the critic to read implementation artifacts
    The critic reads every target file, verifies described changes exist against the spec, and returns per-task verdicts: ALIGNED, MINOR_DRIFT, MAJOR_DRIFT, or OFF_SPEC.
@@ -92,7 +92,7 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
 5.58. **Design-doc sync (conditional on `design_docs.enabled` — issue #1080)**: If `design_docs.enabled` is not true, skip silently. Otherwise: `phase_complete` runs a deterministic, non-blocking design-doc drift check and writes `.swarm/doc-drift-phase-{phase}.json`. If its verdict is `DOC_STALE`, enter MODE: DESIGN_DOCS in sync mode for the stale sections only — delegate to the active swarm's `docs_design` agent (NOT the standard `docs` agent) with the changed files + the stale section IDs, and have it update the affected docs and append a `design-changelog.md` entry. This is advisory and NON-BLOCKING — never hold up phase_complete on design-doc lag, and never write `.swarm/spec.md`, `CHANGELOG.md`, or `docs/releases/pending/*` here.
 5.6. **Mandatory gate evidence**: Before calling phase_complete, ensure:
    - `.swarm/evidence/{phase}/completion-verify.json` exists (written automatically by the completion-verify gate)
-   - `.swarm/evidence/{phase}/drift-verifier.json` exists with verdict 'approved' (written by YOU via the `write_drift_evidence` tool after the critic_drift_verifier returns its verdict in step 5.5) — required when .swarm/spec.md exists
+    - `.swarm/evidence/{phase}/drift-verifier.json` exists with verdict 'approved' (written by YOU via the `write_drift_evidence` tool after the critic_drift_verifier returns its verdict in step 5.5) — required when an effective spec exists
    - `.swarm/evidence/{phase}/hallucination-guard.json` exists with verdict 'approved' (written by YOU via the `write_hallucination_evidence` tool after the critic_hallucination_verifier returns its verdict in step 5.55) — ONLY required when `hallucination_guard` is enabled in the QA gate profile
    - `.swarm/evidence/{phase}/mutation-gate.json` exists with verdict 'pass' or 'warn' (written by YOU via the `write_mutation_evidence` tool after step 5.56) — ONLY required when `mutation_test` is enabled in the QA gate profile
     - regression-test falsification evidence exists for at least one regression

package/.opencode/skills/plan/SKILL.md

@@ -11,22 +11,25 @@ This protocol is loaded on demand by the architect stub in src/agents/architect.
 ### MODE: PLAN
 
 SPEC GATE (soft — check before planning):
-- If `.swarm/spec.md` does NOT exist:
+
+An effective spec exists iff `/swarm sdd status` reports a resolved spec (it reflects `readEffectiveSpecSync`, which returns null for no sources, multiple competing sources, multi-feature Spec-Kit without a selected feature, or any unresolvable state). Do NOT enumerate these cases — defer to `/swarm sdd status`.
+
+- If NO effective spec exists (confirmed via `/swarm sdd status`):
   - PLAN INGESTION DETECTION: Check if the user is providing an external plan (indicators: markdown content with Phase/Task structure, or phrases like "ingest this plan", "implement this plan", "prepare for implementation", "here is a plan", "here's the plan"):
-    - If plan ingestion is detected AND no spec.md exists: offer this choice FIRST before any planning:
+    - If plan ingestion is detected AND no effective spec exists: offer this choice FIRST before any planning:
       1. "Generate spec from this plan first" → enter EXTERNAL PLAN IMPORT PATH in MODE: SPECIFY to reverse-engineer a spec.md from the provided plan, then return to planning
       2. "Skip spec and proceed with the provided plan" → proceed directly to plan ingestion and planning without creating a spec
     - This is a SOFT gate — option 2 always lets the user proceed without a spec
-  - If no plan ingestion detected: Warn: "No spec found. A spec helps ensure the plan covers all requirements and gives the critic something to verify against. Would you like to create one first?"
+  - If no plan ingestion detected: Warn: "No effective spec found. A spec helps ensure the plan covers all requirements and gives the critic something to verify against. Would you like to create one first?"
     - Offer two options:
       1. "Create a spec first" → transition to MODE: SPECIFY
       2. "Skip and plan directly" → continue with the steps below unchanged
-- If `.swarm/spec.md` EXISTS:
+- If an effective spec EXISTS:
   - NOTE: Stale detection is intentionally heuristic (compare headings) — false positives are acceptable because this is a SOFT gate. When in doubt, ask the user.
-  - Read the spec and compare its first heading (or feature description) against the current planning context (the user's request and any existing plan.md title/phase names)
+  - Read the spec (using the effective spec path reported by `/swarm sdd status`) and compare its first heading (or feature description) against the current planning context (the user's request and any existing plan.md title/phase names)
   - STALE SPEC DETECTION: If the spec heading or feature description does NOT match the current work being planned (e.g., spec describes "user authentication" but user is asking to plan "payment integration"), treat the spec as potentially stale and offer three options:
     1. **Archive and create new spec** → attempt to rename .swarm/spec.md to .swarm/spec-archive/spec-{YYYY-MM-DD}.md (create the directory if needed); if archival succeeds: enter MODE: SPECIFY and skip the "spec already exists" prompt; if archival fails: inform user of the failure and offer: retry archival, or proceed with option 2, or proceed with option 3
-    2. **Keep existing spec** → use spec.md as-is and proceed with planning below
+    2. **Keep existing spec** → use the effective spec as-is and proceed with planning below
     3. **Skip spec entirely** → proceed to planning below ignoring the existing spec
   - If the spec appears current (heading matches the work being planned) OR user chose option 2 above, proceed with spec:
     - Read it and use it as the primary input for planning
@@ -37,7 +40,16 @@ SPEC GATE (soft — check before planning):
 
 This is a SOFT gate. When the user chooses "Skip and plan directly", proceed to the steps below exactly as before — do NOT modify any planning behavior.
 
-Run CODEBASE REALITY CHECK scoped to codebase elements referenced in spec.md or user constraints. Discrepancies must be reflected in the generated plan.
+**SAVE_PLAN SPEC_REQUIRED RECOVERY:**
+When `save_plan` returns a SPEC_REQUIRED rejection (no effective spec found), the architect MUST:
+1. DIAGNOSE: run `/swarm sdd status` to determine why no effective spec resolved.
+   - (a) If `/swarm sdd status` shows NO sources → transition to MODE: SPECIFY.
+   - (b) If `/swarm sdd status` shows multiple competing sources (e.g., openspec AND specify with no native) → ask the user which provider to use (`openspec` or `speckit`), then run `/swarm sdd project --source <user_choice>` (obtain explicit consent first; add `--overwrite` only if a native `.swarm/spec.md` already exists). Then re-attempt `save_plan`.
+   - (c) If `/swarm sdd status` shows Spec-Kit with multiple features → ask the user which feature, then run `/swarm sdd project --source speckit --feature <id>` (obtain explicit consent first; add `--overwrite` only if a native `.swarm/spec.md` already exists). Then re-attempt `save_plan`.
+2. If `/swarm sdd status` shows a single resolvable source but it was not yet materialized: run `/swarm sdd project` (obtain explicit consent first; add `--overwrite` only if a native `.swarm/spec.md` already exists). Then re-attempt `save_plan`.
+3. If the user does NOT consent to materializing an effective spec: surface the blockage and stop — do not silently skip or retry without a spec.
+
+Run CODEBASE REALITY CHECK scoped to codebase elements referenced in the effective spec or user constraints. Discrepancies must be reflected in the generated plan.
 
 ### GENERAL COUNCIL ADVISORY OPTION (pre-save_plan)
 
@@ -305,17 +317,17 @@ PHASE COUNT GUIDANCE:
 
 Also create .swarm/context.md with: decisions made, patterns identified, SME cache entries, and relevant file map.
 
-TRACEABILITY CHECK (run after plan is written, when spec.md exists):
+TRACEABILITY CHECK (run after plan is written, when an effective spec exists):
 
 OBLIGATION TRACEABILITY — STRUCTURAL COMPLETENESS PRECONDITION
 The obligation-traceability mapping is a STRUCTURAL COMPLETENESS precondition. It MUST be evaluated BEFORE the critic begins its substantive 5-axis/7-dimension rubric. An unmapped MUST/SHALL obligation makes the plan structurally incomplete — it is not an afterthought.
 
 1. FR-### MAPPING (existing requirement):
-   - Every FR-### in spec.md MUST map to at least one task → unmapped FRs = coverage gap, flag to user
+   - Every FR-### in the effective spec (resolved via `/swarm sdd status`) MUST map to at least one task → unmapped FRs = coverage gap, flag to user
    - Every task MUST reference its source FR-### in the description or acceptance field → tasks with no FR = potential gold-plating, flag to critic
 
 2. SC-### MAPPING (MUST/SHALL obligations):
-   - Parse spec.md for every SC-### line whose obligation text contains MUST or SHALL/SHALL NOT
+   - Parse the effective spec (resolved via `/swarm sdd status`) for every SC-### line whose obligation text contains MUST or SHALL/SHALL NOT
    - Each such MUST/SHALL SC-### MUST be referenced by ≥1 task's description or acceptance field
    - Unmapped MUST/SHALL SC-### are structural coverage gaps that must be resolved — surface them prominently, not buried
    - A plan where every MUST/SHALL SC-### is referenced by ≥1 task passes this check and is not blocked by it
@@ -324,7 +336,7 @@ The obligation-traceability mapping is a STRUCTURAL COMPLETENESS precondition. I
 REPORT FORMAT:
 "TRACEABILITY: <N> FRs mapped, <M> unmapped FRs (gap), <K> tasks with no FR mapping (gold-plating risk), <P> MUST/SHALL SCs mapped, <Q> unmapped MUST/SHALL SCs (structural gap)"
 
-- If no spec.md: skip this check silently.
+- If no effective spec: skip this check silently.
 
 ### Transition to CRITIC-GATE
 

package/.opencode/skills/specify/SKILL.md

@@ -9,15 +9,33 @@ description: >
 This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
 
 ### MODE: SPECIFY
-Activates when: user asks to "specify", "define requirements", "write a spec", or "define a feature"; OR `/swarm specify` is invoked; OR no `.swarm/spec.md` exists and no `.swarm/plan.md` exists.
-
-1. Check if `.swarm/spec.md` already exists.
-   - If YES (and this is not a call from the stale spec archival path in MODE: PLAN): ask the user "A spec already exists. Do you want to overwrite it or refine it?"
-     - Overwrite → ARCHIVE FIRST: read the existing spec, extract version (priority order): (1) from spec heading, look for patterns like "v{semver}" or "Version {semver}" in the first H1/H2; (2) from package.json version field in project root; create `.swarm/spec-archive/` directory if it does not exist; copy existing spec.md to `.swarm/spec-archive/spec-v{version}.md`; if version cannot be determined, use date-based fallback: `.swarm/spec-archive/spec-{YYYY-MM-DD}.md`; log the archive location to the user ("Archived existing spec to .swarm/spec-archive/spec-v{version}.md"); then proceed to generation (step 2)
-     - Refine → delegate to MODE: CLARIFY-SPEC
-   - If NO: proceed to generation (step 2)
-   - If this is called from the stale spec archival path (MODE: PLAN option 1) — archival was already completed; skip this check and proceed directly to generation (step 2)
-1b. Run CODEBASE REALITY CHECK for any codebase references mentioned by the user or implied by the feature. Skip if work is purely greenfield (no existing codebase to check). Report discrepancies before proceeding to explorer.
+Activates when: user asks to "specify", "define requirements", "write a spec", or "define a feature"; OR `/swarm specify` is invoked; OR no EFFECTIVE spec exists and no `.swarm/plan.md` exists (use `/swarm sdd status` to determine effective-spec existence — native `.swarm/spec.md`, OpenSpec `openspec/`, or Spec-Kit `.specify/`).
+
+   1. Run `/swarm sdd status` to determine whether an effective spec exists and, if so, how it should be handled. An effective spec exists iff `/swarm sdd status` reports a resolved spec. `/swarm sdd status` reflects `readEffectiveSpecSync`, which returns null (NO effective spec) for: no sources, multiple competing sources (openspec+speckit), multi-feature Spec-Kit without a selected feature, or any unresolvable state. When `/swarm sdd status` reports a resolved spec, classify it as NATIVE (native `.swarm/spec.md`) vs NON-NATIVE (projected). When it reports NO resolved spec, do NOT treat any source as an effective spec. Based on this classification, branch to the appropriate sub-step:
+     - **NATIVE**: proceed to step 1a (overwrite/refine/archive).
+     - **NON-NATIVE**: proceed to step 1b (non-shadowing choice).
+     - **NO effective spec** (ambiguous or no sources): if multiple SDD sources are present, proceed to step 1c (disambiguation); otherwise proceed to step 1d (native authoring).
+     - If this is called from the stale spec archival path (MODE: PLAN option 1) — archival was already completed; skip all branches and proceed directly to generation (step 2).
+1a. **NATIVE SPEC — overwrite/refine/archive.** Ask the user "A spec already exists. Do you want to overwrite it or refine it?"
+      - Overwrite → ARCHIVE FIRST: read the existing spec, extract version (priority order): (1) from spec heading, look for patterns like "v{semver}" or "Version {semver}" in the first H1/H2; (2) from package.json version field in project root; create `.swarm/spec-archive/` directory if it does not exist; copy existing spec.md to `.swarm/spec-archive/spec-v{version}.md`; if version cannot be determined, use date-based fallback: `.swarm/spec-archive/spec-{YYYY-MM-DD}.md`; log the archive location to the user ("Archived existing spec to .swarm/spec-archive/spec-v{version}.md"); then proceed to generation (step 2)
+      - Refine → delegate to MODE: CLARIFY-SPEC
+1b. **NON-NATIVE SPEC — non-shadowing check (FR-002).** The effective spec comes from `openspec/` or `.specify/` sources with no native `.swarm/spec.md`. Do NOT silently author a competing native spec. Instead OFFER the user a choice:
+      - **(a) Project/ingest** the existing SDD sources into `.swarm/spec.md` via the agent-invocable `/swarm sdd project` command. Obtain EXPLICIT user consent before proceeding. (Do not pass `--overwrite` in this branch — no native spec exists yet.)
+      - **(b) Proceed with native authoring** (`/swarm specify`) if the user explicitly chooses to ignore the SDD sources and write a new spec from scratch.
+      - **(c) Cancel** — abort SPECIFY; the existing SDD sources remain the effective spec.
+     - If the user chooses option (a) and `/swarm sdd project` completes successfully: the projected spec is now materialized as `.swarm/spec.md` (NATIVE). Do NOT proceed to generation (step 2) — that would overwrite the just-projected spec. Instead route to step 1a (overwrite/refine/archive) so the user can refine, overwrite, or archive the projected spec.
+     - If the user chooses option (b): proceed directly to generation (step 2) with a note that existing SDD sources were bypassed per user decision.
+     - If the user chooses option (a) and `/swarm sdd project` fails: report the failure and re-offer the choices.
+1c. **AMBIGUOUS — multiple SDD sources detected.** Both `openspec/` AND `.specify/` exist with no native `.swarm/spec.md`. Per `readEffectiveSpecSync` semantics this is NOT an effective spec (the function returns null). Do NOT treat this as a single-source NON-NATIVE choice. Instead:
+        - Inform the user: "Multiple SDD sources detected (openspec AND speckit) but no native spec exists. This is ambiguous — there is no single effective spec. You must choose which source to project, or disambiguate via `/swarm sdd status --source`."
+       - Offer the user a choice:
+         - **(a) Project from openspec** — run `/swarm sdd project --source openspec` (after consent) to project the openspec source into `.swarm/spec.md`.
+          - **(b) Project from speckit** — run `/swarm sdd project --source speckit` (after consent) to project the speckit source into `.swarm/spec.md`.
+         - **(c) Cancel** — abort SPECIFY; the ambiguous sources remain as-is.
+       - After a successful projection (a or b): the spec is now NATIVE → route to step 1a (overwrite/refine/archive).
+       - After a failed projection: report the failure and re-offer the choices.
+1d. **NO EFFECTIVE SPEC.** Proceed directly to generation (step 2).
+1e. Run CODEBASE REALITY CHECK for any codebase references mentioned by the user or implied by the feature. Skip if work is purely greenfield (no existing codebase to check). Report discrepancies before proceeding to explorer.
 2. Delegate to `the active swarm's explorer agent` to scan the codebase for relevant context (existing patterns, related code, affected areas).
 3. Delegate to `the active swarm's sme agent` for domain research on the feature area to surface known constraints, best practices, and integration concerns.
 4. Generate `.swarm/spec.md` capturing:

package/dist/cli/{core-vev13ej2.js → core-mbd2g302.js}

@@ -6,13 +6,15 @@ import {
   checkPathBudget,
   cleanUntrackedFiles,
   isCleanWorktree,
+  isPathUnderSwarmWorktreeBase,
   makeWorktreeBranchName,
   provisionWorktree,
   removeLaneProfileFromDiskReal,
   removeWorktree,
+  resolveWorktreeBaseDir,
   shortenWorktreePath,
   writeLaneProfileToDiskReal
-} from "./index-f1qyj61w.js";
+} from "./index-3yk9196e.js";
 import"./index-5e4e2hvv.js";
 import"./index-p0arc26j.js";
 import"./index-zgwm4ryv.js";
@@ -21,10 +23,12 @@ import"./index-a76rekgs.js";
 export {
   writeLaneProfileToDiskReal,
   shortenWorktreePath,
+  resolveWorktreeBaseDir,
   removeWorktree,
   removeLaneProfileFromDiskReal,
   provisionWorktree,
   makeWorktreeBranchName,
+  isPathUnderSwarmWorktreeBase,
   isCleanWorktree,
   cleanUntrackedFiles,
   checkPathBudget,

package/dist/cli/{curator-drift-fdfgj9qf.js → curator-drift-169wgaxn.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-c8s9a3zh.js";
 import {
   readEffectiveSpecSync
-} from "./index-91j1sqzm.js";
+} from "./index-scww5b77.js";
 import {
   readSwarmFileAsync,
   validateSwarmPath

package/dist/cli/{curator-llm-factory-n70bxf40.js → curator-llm-factory-gtfhwnbr.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   createCuratorLLMDelegate
-} from "./index-1emhz3zb.js";
+} from "./index-nq9h2t3x.js";
 import"./index-wj4jeavn.js";
 import"./index-5gnp8fyw.js";
 import"./index-c8s9a3zh.js";
 import"./index-fm7xz1ne.js";
-import"./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+import"./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-yw8qpf51.js";
 import"./index-85bacexr.js";
 import"./index-09xpycan.js";
@@ -21,7 +21,7 @@ import"./index-bfwt3abw.js";
 import"./index-wvrj16f0.js";
 import"./index-q1exe2b3.js";
 import"./index-x2q0gnt8.js";
-import"./index-f1qyj61w.js";
+import"./index-3yk9196e.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";
 import"./index-5e4e2hvv.js";

package/dist/cli/{curator-js92gc8a.js → curator-q4febs18.js}

@@ -11,13 +11,13 @@ import {
   runCuratorInit,
   runCuratorPhase,
   writeCuratorSummary
-} from "./index-1emhz3zb.js";
+} from "./index-nq9h2t3x.js";
 import"./index-wj4jeavn.js";
 import"./index-5gnp8fyw.js";
 import"./index-c8s9a3zh.js";
 import"./index-fm7xz1ne.js";
-import"./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+import"./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-yw8qpf51.js";
 import"./index-85bacexr.js";
 import"./index-09xpycan.js";
@@ -31,7 +31,7 @@ import"./index-bfwt3abw.js";
 import"./index-wvrj16f0.js";
 import"./index-q1exe2b3.js";
 import"./index-x2q0gnt8.js";
-import"./index-f1qyj61w.js";
+import"./index-3yk9196e.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";
 import"./index-5e4e2hvv.js";

package/dist/cli/{evidence-summary-service-bjhr75v0.js → evidence-summary-service-8tasw2tt.js}

@@ -6,8 +6,8 @@ import {
   loadPlanJsonOnly,
   mergeDurableGateEntriesFromEvidence,
   readDurableGateEvidence
-} from "./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+} from "./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-q1exe2b3.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";

package/dist/cli/{guardrail-explain-sn2a4pb7.js → guardrail-explain-r2d8ftkv.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-7jyndvsy.js";
-import"./index-1emhz3zb.js";
+} from "./index-wsg3vkss.js";
+import"./index-nq9h2t3x.js";
 import"./index-wj4jeavn.js";
 import"./index-5gnp8fyw.js";
 import"./index-c8s9a3zh.js";
 import"./index-fm7xz1ne.js";
-import"./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+import"./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-yw8qpf51.js";
 import"./index-85bacexr.js";
 import"./index-09xpycan.js";
@@ -22,7 +22,7 @@ import"./index-bfwt3abw.js";
 import"./index-wvrj16f0.js";
 import"./index-q1exe2b3.js";
 import"./index-x2q0gnt8.js";
-import"./index-f1qyj61w.js";
+import"./index-3yk9196e.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";
 import"./index-5e4e2hvv.js";

package/dist/cli/{hive-promoter-3hh8ph4a.js → hive-promoter-mfd5p9f5.js}

@@ -5,13 +5,13 @@ import {
   isHiveEligible,
   promoteFromSwarm,
   promoteToHive
-} from "./index-1emhz3zb.js";
+} from "./index-nq9h2t3x.js";
 import"./index-wj4jeavn.js";
 import"./index-5gnp8fyw.js";
 import"./index-c8s9a3zh.js";
 import"./index-fm7xz1ne.js";
-import"./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+import"./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-yw8qpf51.js";
 import"./index-85bacexr.js";
 import"./index-09xpycan.js";
@@ -25,7 +25,7 @@ import"./index-bfwt3abw.js";
 import"./index-wvrj16f0.js";
 import"./index-q1exe2b3.js";
 import"./index-x2q0gnt8.js";
-import"./index-f1qyj61w.js";
+import"./index-3yk9196e.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";
 import"./index-5e4e2hvv.js";

package/dist/cli/{index-x06d2qqm.js → index-1capawwy.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-7jyndvsy.js";
+} from "./index-wsg3vkss.js";
 import {
   handleGuardrailLog
 } from "./index-vx76tcxe.js";
@@ -80,13 +80,13 @@ import {
   handleWriteRetroCommand,
   normalizeSwarmCommandInput,
   resolveCommand
-} from "./index-1emhz3zb.js";
+} from "./index-nq9h2t3x.js";
 import"./index-wj4jeavn.js";
 import"./index-5gnp8fyw.js";
 import"./index-c8s9a3zh.js";
 import"./index-fm7xz1ne.js";
-import"./index-48mc4d48.js";
-import"./index-91j1sqzm.js";
+import"./index-j2v3w1ds.js";
+import"./index-scww5b77.js";
 import"./index-yw8qpf51.js";
 import"./index-85bacexr.js";
 import"./index-09xpycan.js";
@@ -104,7 +104,7 @@ import"./index-bfwt3abw.js";
 import"./index-wvrj16f0.js";
 import"./index-q1exe2b3.js";
 import"./index-x2q0gnt8.js";
-import"./index-f1qyj61w.js";
+import"./index-3yk9196e.js";
 import"./index-r3j3458j.js";
 import"./index-jtqkh8jf.js";
 import"./index-5e4e2hvv.js";

package/dist/cli/{index-f1qyj61w.js → index-3yk9196e.js}

@@ -162,9 +162,39 @@ function makeWorktreeBranchName(sessionId, id, options) {
   }
   return `swarm/${options.purpose}/${sessionId}/${id}`;
 }
+function resolveWorktreeBaseDir(directory, worktreeDir) {
+  return worktreeDir ? path.resolve(directory, worktreeDir) : path.resolve(path.dirname(directory), ".swarm-worktrees");
+}
+function isPathUnderSwarmWorktreeBase(targetPath, directory, worktreeDirOverrides = []) {
+  const caseInsensitive = process.platform === "win32";
+  let realTarget;
+  try {
+    realTarget = fs.realpathSync(path.resolve(directory, targetPath));
+  } catch {
+    return false;
+  }
+  const bases = [
+    resolveWorktreeBaseDir(directory),
+    ...worktreeDirOverrides.map((d) => resolveWorktreeBaseDir(directory, d))
+  ];
+  const cmpTarget = caseInsensitive ? realTarget.toLowerCase() : realTarget;
+  return bases.some((base) => {
+    let realBase;
+    try {
+      realBase = fs.realpathSync(base);
+    } catch {
+      realBase = path.resolve(base);
+    }
+    const cmpBase = caseInsensitive ? realBase.toLowerCase() : realBase;
+    if (cmpTarget === cmpBase)
+      return true;
+    const rel = path.relative(cmpBase, cmpTarget);
+    return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
+  });
+}
 async function provisionWorktree(directory, id, sessionId, options) {
   const branchName = makeWorktreeBranchName(sessionId, id, options);
-  let worktreePath = options.worktreeDir ? path.resolve(directory, options.worktreeDir, sessionId, id) : path.resolve(path.dirname(directory), ".swarm-worktrees", sessionId, id);
+  let worktreePath = path.resolve(resolveWorktreeBaseDir(directory, options.worktreeDir), sessionId, id);
   const budgetResult = await checkPathBudget(worktreePath, directory);
   if (budgetResult.ok === false) {
     if (options.worktreeDir) {
@@ -285,7 +315,7 @@ async function provisionWorktree(directory, id, sessionId, options) {
     sessionId
   };
 }
-async function removeWorktree(worktreePath, projectRoot) {
+async function removeWorktree(worktreePath, projectRoot, options) {
   const isWindows = _internals.platform === "win32";
   const MAX_RETRIES = 4;
   const RETRY_DELAY_MS = 2000;
@@ -300,6 +330,13 @@ async function removeWorktree(worktreePath, projectRoot) {
       await _internals.sleep(RETRY_DELAY_MS);
       continue;
     }
+    if (options?.force && isPathUnderSwarmWorktreeBase(worktreePath, projectRoot, options.worktreeDir ? [options.worktreeDir] : [])) {
+      const forced = await runGit(["worktree", "remove", "--force", worktreePath], projectRoot);
+      if (forced.exitCode === 0) {
+        return { success: true };
+      }
+      return { error: forced.stderr.trim() || forced.stdout.trim() };
+    }
     return { error: lastError };
   }
   return { error: lastError };
@@ -415,4 +452,4 @@ async function assertCleanWorkingTree(directory) {
   return { clean: true };
 }
 
-export { _internals, writeLaneProfileToDiskReal, removeLaneProfileFromDiskReal, checkPathBudget, shortenWorktreePath, makeWorktreeBranchName, provisionWorktree, removeWorktree, isCleanWorktree, autoCommitDirty, cleanUntrackedFiles, assertCleanWorkingTree };
+export { _internals, writeLaneProfileToDiskReal, removeLaneProfileFromDiskReal, checkPathBudget, shortenWorktreePath, makeWorktreeBranchName, resolveWorktreeBaseDir, isPathUnderSwarmWorktreeBase, provisionWorktree, removeWorktree, isCleanWorktree, autoCommitDirty, cleanUntrackedFiles, assertCleanWorkingTree };

package/dist/cli/{index-48mc4d48.js → index-j2v3w1ds.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   readEffectiveSpecSync
-} from "./index-91j1sqzm.js";
+} from "./index-scww5b77.js";
 import {
   _internals,
   buildDefaultPolicy,
@@ -2339,7 +2339,7 @@ async function takeSnapshotWithRetry(directory, plan, options) {
   } catch {}
 }
 async function takeSnapshotEvent(directory, plan, options) {
-  const payloadHash = computePlanHash(plan);
+  const payloadHash = options?.payloadHashOverride ?? computePlanHash(plan);
   const snapshotPayload = {
     plan,
     payload_hash: payloadHash
@@ -2536,6 +2536,9 @@ async function quarantineLedgerSuffix(directory, badSuffix) {
 }
 async function loadLastApprovedPlan(directory, expectedPlanId) {
   const events = await readLedgerEvents(directory);
+  return findLastApprovedSnapshot(events, expectedPlanId);
+}
+function findLastApprovedSnapshot(events, expectedPlanId, extraFilter) {
   if (events.length === 0) {
     return null;
   }
@@ -2558,6 +2561,9 @@ async function loadLastApprovedPlan(directory, expectedPlanId) {
         continue;
       }
     }
+    if (extraFilter && !extraFilter(payload)) {
+      continue;
+    }
     return {
       plan: payload.plan,
       seq: event.seq,