bmad-module-skill-forge 0.10.0 → 1.0.0-rc.3

package/src/shared/references/feasibility-report-schema.md

@@ -0,0 +1,86 @@
+# Feasibility Report Schema
+
+**Purpose:** Canonical contract shared between `skf-create-stack-skill` (consumer) and `skf-verify-stack` (producer). Any change here must be applied to both skills in lockstep.
+
+## Filename
+
+```
+{forge_data_folder}/feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md
+```
+
+`{project_slug}` is the slugified `project_name` (lowercase, hyphens only, no unicode). A stable `feasibility-report-{project_slug}-latest.md` copy (not symlink) is written next to the timestamped file for pipeline consumers.
+
+## Frontmatter (required)
+
+```yaml
+---
+schemaVersion: "1.0"
+reportType: feasibility
+projectName: "{project_name}"
+projectSlug: "{project_slug}"
+generatedAt: "{ISO-8601 UTC}"
+generatedBy: skf-verify-stack
+overallVerdict: "FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE"
+coveragePercentage: <0..100 integer>
+pairsVerified: <non-negative integer>
+pairsPlausible: <non-negative integer>
+pairsRisky: <non-negative integer>
+pairsBlocked: <non-negative integer>
+recommendationCount: <non-negative integer>
+prdAvailable: <true|false>
+---
+```
+
+**Unknown `schemaVersion` MUST fail loudly in consumers — never silently proceed.** Consumers check `schemaVersion == "1.0"` and emit an explicit error if mismatched.
+
+## Per-pair verdict tokens (case-sensitive)
+
+Exactly one of:
+
+| Token | Meaning | Required evidence |
+|---|---|---|
+| `Verified` | All compatibility checks pass with declared evidence in both skills | Documentation cross-reference (Check 4) MUST pass with literal substring/name citation; language + protocol + type checks all pass |
+| `Plausible` | Checks pass but at least one relies on inferred rather than declared evidence | Language + protocol + type checks pass; Check 4 weak or missing |
+| `Risky` | At least one check produced incompatibility that a workaround may resolve | Any single check fails; workaround cited in recommendation |
+| `Blocked` | Fundamental incompatibility that cannot be worked around | Language mismatch, protocol mismatch with no bridge, or type mismatch with no adapter |
+
+## Overall verdict tokens (case-sensitive)
+
+Exactly one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE`.
+
+- `FEASIBLE` — 100% coverage AND zero Blocked pairs AND zero pairs with Check 4 missing.
+- `NOT_FEASIBLE` — Any Blocked pair OR zero coverage.
+- `CONDITIONALLY_FEASIBLE` — Everything else.
+
+## Body section headings (required, in order)
+
+```markdown
+## Executive Summary
+## Coverage Analysis
+## Integration Verdicts
+## Recommendations
+## Evidence Sources
+```
+
+Consumers grep for `## Integration Verdicts` to locate the pair table. The table header is fixed:
+
+```markdown
+| lib_a | lib_b | verdict | rationale |
+```
+
+## Producer obligations (skf-verify-stack)
+
+- Set `schemaVersion: "1.0"` in frontmatter.
+- Never emit a verdict token outside the defined set.
+- When Check 4 (documentation cross-reference) produces weak/missing evidence, cap the per-pair verdict at `Plausible`.
+- When `coveragePercentage == 0`, force `overallVerdict: NOT_FEASIBLE` regardless of pair results.
+
+## Consumer obligations (skf-create-stack-skill)
+
+- Verify `schemaVersion == "1.0"`; halt with explicit error on mismatch.
+- Treat any unknown verdict token as a hard error (do not silently drop or map).
+- Use filename pattern above when referencing prior reports.
+
+## Versioning policy
+
+Any change to the verdict token set, frontmatter keys, or section headers is a schema-breaking change and MUST bump `schemaVersion`. Additive changes (new optional frontmatter keys) bump the minor version; breaking changes bump the major version.

package/src/shared/references/headless-gate-convention.md

@@ -0,0 +1,62 @@
+# Headless Gate Convention
+
+## Overview
+
+Gates are user interaction points where a workflow pauses for confirmation or input. In headless mode, gates auto-resolve with their default action. This convention ensures one code path with two behaviors — interactive and headless use the same gates, the same output, and the same progression logic.
+
+## How It Works
+
+Every gate in a step file follows this pattern:
+
+```
+**GATE: [default action]** — Present [options] to user.
+If `{headless_mode}`: auto-proceed with [default action], log: "headless: auto-[action]".
+```
+
+The gate always:
+1. Prepares the same output (summary, preview, menu) regardless of mode
+2. In interactive mode: displays the output and waits for user input
+3. In headless mode: displays the output, logs the auto-action, and proceeds with the default
+
+## Resolving `{headless_mode}`
+
+`{headless_mode}` is resolved during activation from:
+1. **Args:** `--headless` or `-H` passed to the skill invocation
+2. **Preferences:** `headless_mode: true` in `{sidecar_path}/preferences.yaml`
+3. **Default:** `false`
+
+Each workflow's On Activation section resolves this variable alongside other config. The forger passes it through when dispatching to workflows.
+
+## Gate Types
+
+### Confirm Gate (default: Continue)
+The most common gate. Presents a summary and asks to continue.
+- Default action: `[C] Continue`
+- Headless behavior: auto-continue after displaying summary
+
+### Review Gate (default: Approve)
+Presents compiled output for review before writing.
+- Default action: `[C] Continue` (approve)
+- Headless behavior: auto-approve after displaying preview
+
+### Input Gate (default: use provided args)
+Requires user-supplied data (skill name, path, etc.).
+- Default action: use `{headless_args}` if provided
+- Headless behavior: consume pre-supplied arguments; halt if missing required input
+
+### Choice Gate (default: first safe option)
+Presents a menu with multiple options (P/I/A, etc.).
+- Default action: varies per gate (documented in step file)
+- Headless behavior: auto-select the default, log the choice
+
+## Headless Args
+
+For skills that require user input (skill name, target path, etc.), headless mode accepts arguments via the invocation. Each skill's Invocation Contract documents its required headless args.
+
+Example: `@Ferris QS cocoindex --headless` passes `cocoindex` as the target and skips all gates.
+
+## What Headless Does NOT Skip
+
+- Error halts (hard halts on missing files, invalid state)
+- Progress output (summaries, status updates still display)
+- Quality thresholds (if a step produces output below spec, it still reports the issue)

package/src/shared/references/output-contract-schema.md

@@ -0,0 +1,35 @@
+# Output Contract Schema
+
+Every pipeline-capable skill writes a result JSON file at its final step. This enables reliable CI integration and pipeline chaining.
+
+## Schema
+
+```json
+{
+  "skill": "skf-skill-name",
+  "status": "success" | "failed" | "partial",
+  "timestamp": "ISO-8601",
+  "outputs": [
+    {"type": "report|skill|manifest|config", "path": "relative/path/to/file"}
+  ],
+  "summary": {
+    // skill-specific summary fields
+  }
+}
+```
+
+## Filenames
+
+Each run writes **two files** to `{output_dir}`:
+
+1. **Per-run record** (audit trail): `{skill-name}-result-{YYYYMMDD-HHmmss}.json`
+   - Timestamp is UTC, resolution to seconds — e.g., `update-skill-result-20260413-145230.json`
+   - Never overwritten by subsequent runs — preserves a durable audit trail across retries, aborts, and re-runs
+2. **Stable latest pointer** (pipeline consumption): `{skill-name}-result-latest.json`
+   - A **copy** (not a symlink) of the per-run record just written
+   - Always present at a deterministic path so CI / pipelines / the forger can read `summary.*` without enumerating timestamps
+   - Overwritten on every successful write
+
+Write the per-run record first, then copy it to the `-latest.json` path. If the copy fails, the per-run record still exists — the run is not lost.
+
+**Consumers (forger, CI, chained workflows):** read from `{skill-name}-result-latest.json`. Do not enumerate timestamped files unless inspecting prior-run history.

package/src/shared/references/pipeline-contracts.md

@@ -0,0 +1,102 @@
+# Pipeline Contracts
+
+## Overview
+
+Pipelines chain multiple SKF workflows in sequence. The forger orchestrates the chain, passing data between workflows via filesystem artifacts and validating output contracts at each transition.
+
+## Syntax
+
+The forger recognizes pipeline invocations when the user provides multiple workflow codes:
+
+```
+AN CS TS EX              — space-separated codes
+AN -> CS -> TS -> EX     — arrow-separated (equivalent)
+BS CS[cocoindex] TS EX   — with target argument in brackets
+CS TS[min:80] EX         — with circuit breaker threshold
+```
+
+The forger also accepts common pipeline aliases:
+
+| Alias | Expands To | Description |
+|-------|-----------|-------------|
+| `forge` | `BS CS TS EX` | Full skill creation pipeline (brief through export) |
+| `forge-quick` | `QS TS EX` | Quick skill pipeline |
+| `onboard` | `AN CS TS EX` | Full brownfield onboarding (AN generates briefs, CS consumes them directly) |
+| `maintain` | `AS US TS EX` | Maintenance cycle (audit → update → test → export) |
+
+## Pipeline Rules
+
+1. **Left to right execution** — each workflow completes before the next begins
+2. **Headless implied** — pipelines activate `{headless_mode}` automatically for all workflows in the chain (the user already committed to the sequence)
+3. **Data forwarding** — the forger resolves output-to-input mapping between adjacent workflows (see Data Flow table)
+4. **Circuit breakers** — if a workflow's output fails its quality check, the pipeline halts with a summary of what completed and what remains
+5. **Error halts propagate** — if any workflow hard-halts, the pipeline stops immediately
+6. **Progress reporting** — the forger reports completion of each workflow before starting the next
+
+## Data Flow
+
+How outputs from one workflow become inputs to the next:
+
+| From | To | Data Passed | How |
+|------|-----|------------|-----|
+| AN | CS | `skill-brief.yaml` paths from generated briefs | Forger passes each `brief_path` written by AN to CS; in batch mode, CS processes all sequentially |
+| BS | CS | `skill-brief.yaml` path | Forger passes the brief path written by BS as `brief_path` to CS |
+| CS | TS | skill name (derived from brief) | Forger passes the `skill_name` from the completed CS to TS |
+| CS | EX | skill name | Same — forger resolves the created skill's name |
+| TS | EX | skill name + test result | Forger checks `result` field in test report; if FAIL and circuit breaker active, halts |
+| QS | TS | skill name (from `repo_name`) | Forger passes the quick-skill's output name to TS |
+| QS | EX | skill name | Same |
+| AS | US | skill name + drift severity | Forger checks `summary.severity` in `audit-skill-result-latest.json`; if CLEAN, skips US |
+| VS | RA | architecture doc path | Already known from VS invocation |
+
+## Circuit Breakers
+
+Circuit breakers halt the pipeline when a workflow's output doesn't meet a quality threshold:
+
+| Workflow | Check | Default Threshold | Halt Condition |
+|----------|-------|-------------------|----------------|
+| AN | recommended units count | min: 1 | Zero skillable units found |
+| CS | compilation success | must complete | Hard error during compilation |
+| TS | completeness score | min: 60 | Score below threshold |
+| AS | drift score | not CRITICAL | Critical drift found |
+| VS | feasibility verdict | not BLOCKED | All integrations blocked |
+
+Override syntax: `TS[min:80]` sets the test-skill threshold to 80 for this pipeline run.
+
+### Bracket Syntax
+
+Brackets after a workflow code (`CODE[value]`) are parsed as follows:
+
+- **Circuit breaker override**: `min:N` where N is a number — e.g., `TS[min:80]` sets the threshold for that workflow
+- **Target argument**: any other value — e.g., `CS[cocoindex]` passes "cocoindex" as the target to CS
+
+Only workflows with a circuit breaker entry (AN, CS, TS, AS, VS) accept `min:N` overrides. All other workflows ignore `min:N` brackets. Target arguments are valid for any workflow that accepts a named input (CS, QS, BS, US, etc.).
+
+## Pipeline State
+
+The forger tracks pipeline state in memory during execution:
+
+```yaml
+pipeline:
+  workflows: [AN, CS, TS, EX]
+  current_index: 1
+  completed:
+    - {code: AN, status: ok, output: {units: 3, briefs: [...]}}
+  pending: [CS, TS, EX]
+  data:
+    skill_name: "cocoindex"
+    brief_path: "/path/to/skill-brief.yaml"
+    target: "cocoindex"
+```
+
+## Anti-Patterns
+
+The forger validates the pipeline sequence and warns about:
+
+| Pattern | Issue | Suggestion |
+|---------|-------|------------|
+| EX before TS | Exporting untested skill | Add TS before EX |
+| US without AS | Updating without audit | Run AS first to detect what changed |
+| CS without BS or AN | Compiling without brief | Need a brief — use QS for quick path, or AN for brownfield |
+| TS after EX | Testing after export | Move TS before EX |
+| Duplicate codes | Same workflow twice | Remove duplicate |

package/src/shared/scripts/skf-atomic-write.py

@@ -0,0 +1,370 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Atomic Write — Crash-safe artifact writing for skill workflows.
+
+Provides three CLI subcommands skills can invoke via bash to avoid
+partial-write corruption and active-symlink races.
+
+Subcommands:
+  write      Stage content into <target>.skf-tmp, fsync, then rename to <target>.
+             Content comes from stdin. Creates parent dirs as needed.
+
+  stage-dir  Create <target>.skf-tmp/ as a staging directory (mkdir -p).
+             Caller writes files into it, then calls commit-dir to atomically
+             swap it into place as <target>/ (with prior target moved aside
+             to <target>.skf-rollback-<pid> and removed on success).
+
+  commit-dir Atomically swap <target>.skf-tmp/ into <target>/. If <target>/
+             exists, move it to <target>.skf-rollback-<pid> first; on failure,
+             restore. Supports rollback via --rollback to undo the most recent
+             commit by restoring the rollback dir if still present.
+
+  flip-link  Atomically update symlink <link> to point at <target> using
+             the `ln -sfn tmp && mv -Tf tmp link` pattern (or equivalent via
+             os.replace on the link path). Holds an flock on <link>.lock.
+
+Cross-platform: locking branches between fcntl (POSIX) and msvcrt
+(Windows). Symlink semantics on Windows require dev mode or admin —
+flip-link surfaces a clear error rather than silently falling back.
+Native Windows is untested in CI; the supported path is WSL2.
+
+Exit codes:
+  0 on success
+  1 on user error (bad args, missing input)
+  2 on operation failure (disk full, permission, race-detected)
+
+CLI examples:
+  cat metadata.json | python3 skf-atomic-write.py write --target /path/to/metadata.json
+  python3 skf-atomic-write.py stage-dir --target /path/to/1.0.0
+  python3 skf-atomic-write.py commit-dir --target /path/to/1.0.0
+  python3 skf-atomic-write.py flip-link --link /path/to/active --target 1.0.0
+"""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+def _create_symlink_or_junction(target: str, link_path: Path) -> str:
+    """Create a directory link from link_path to target.
+
+    On POSIX: standard symlink. On Windows: try symlink first (works under
+    Developer Mode or admin), fall back to a directory junction via `mklink /J`
+    on PRIVILEGE_NOT_HELD / ACCESS_DENIED. Junctions don't need elevation and
+    behave like directory symlinks for the resolve() / is_dir() consumers in
+    skf-skill-inventory.py.
+
+    Returns "symlink" or "junction" so callers can report which kind was made.
+    """
+    try:
+        os.symlink(target, link_path)
+        return "symlink"
+    except OSError as e:
+        if os.name != "nt" or getattr(e, "winerror", None) not in (1314, 5):
+            raise
+        # Junctions are absolute-path-only and target must be a real directory
+        # at creation time. Resolve relative `target` against link_path's parent.
+        abs_target = (link_path.parent / target).resolve()
+        if not abs_target.is_dir():
+            raise OSError(
+                errno.ENOTDIR,
+                f"junction fallback requires existing directory target: {abs_target}",
+            ) from e
+        result = subprocess.run(
+            ["cmd", "/c", "mklink", "/J", str(link_path), str(abs_target)],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            raise OSError(
+                e.errno,
+                f"junction fallback failed: {result.stderr.strip() or result.stdout.strip()}",
+            ) from e
+        return "junction"
+
+
+def _acquire_lock(fd: int) -> None:
+    """Acquire an exclusive non-blocking lock on fd (auto-released on close/exit)."""
+    if os.name == "nt":
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError as e:
+            if e.errno in (errno.EAGAIN, errno.EACCES, errno.EDEADLK):
+                raise OSError(errno.EAGAIN, "lock held") from e
+            raise
+    else:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as e:
+            if e.errno in (errno.EAGAIN, errno.EACCES):
+                raise OSError(errno.EAGAIN, "lock held") from e
+            raise
+
+
+def _release_lock(fd: int) -> None:
+    if os.name == "nt":
+        try:
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+    else:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+
+
+def _die(code: int, message: str) -> None:
+    print(json.dumps({"status": "error", "message": message}), file=sys.stderr)
+    sys.exit(code)
+
+
+def _ok(payload: dict) -> None:
+    payload.setdefault("status", "ok")
+    print(json.dumps(payload))
+
+
+def cmd_write(target: Path) -> None:
+    """Write stdin to target atomically via temp + rename."""
+    data = sys.stdin.buffer.read()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_name(target.name + ".skf-tmp")
+    try:
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+        try:
+            os.write(fd, data)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(tmp, target)
+    except OSError as e:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+        _die(2, f"atomic write failed: {e}")
+    _ok({"wrote": str(target), "bytes": len(data)})
+
+
+def cmd_stage_dir(target: Path) -> None:
+    """Create <target>.skf-tmp/ staging directory (clean if present)."""
+    staging = target.with_name(target.name + ".skf-tmp")
+    # A prior interrupted run can leave staging as a regular file or a dangling
+    # symlink; shutil.rmtree only handles real directories, so dispatch by type.
+    if staging.is_symlink() or (staging.exists() and not staging.is_dir()):
+        try:
+            staging.unlink()
+        except OSError as e:
+            _die(2, f"failed to clear stale staging entry {staging}: {e}")
+    elif staging.is_dir():
+        shutil.rmtree(staging)
+    staging.mkdir(parents=True)
+    _ok({"staging": str(staging)})
+
+
+def cmd_commit_dir(target: Path, rollback: bool = False) -> None:
+    """Swap <target>.skf-tmp/ into <target>/.
+
+    The swap is two os.replace calls (move prior aside, then move staging
+    into place); a crash between them leaves the prior snapshot at
+    <target>.skf-rollback-<pid>/ recoverable via --rollback. Concurrent
+    commits against the same target are NOT supported — callers must
+    serialize via the per-target flock provided by flip-link or external
+    coordination.
+    """
+    staging = target.with_name(target.name + ".skf-tmp")
+    rollback_dir = target.with_name(target.name + f".skf-rollback-{os.getpid()}")
+
+    if rollback:
+        # Pick the newest rollback dir by mtime, not by lexical PID sort.
+        # Concurrent commits leave one rollback per PID; sorting by PID-as-string
+        # could restore an older snapshot (PID "9999" sorts after "10001"). mtime
+        # of the rollback dir = moment os.replace moved the prior target aside,
+        # which is the correct "most recent" anchor.
+        candidates = list(target.parent.glob(target.name + ".skf-rollback-*"))
+        if not candidates:
+            _die(1, f"no rollback dir for {target}")
+        chosen = max(candidates, key=lambda p: p.stat().st_mtime)
+        if target.exists():
+            shutil.rmtree(target)
+        os.replace(chosen, target)
+        _ok({"restored": str(target), "from": str(chosen)})
+        return
+
+    if not staging.is_dir():
+        _die(1, f"staging dir missing: {staging}")
+
+    # First-install case: target's parent may not exist yet (e.g. fresh
+    # {skill_group}/{version}/ install). os.replace requires the destination
+    # parent to exist, so create it before either replace fires.
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    prior_moved = False
+    if target.exists():
+        if target.is_symlink() or target.is_file():
+            _die(2, f"target is not a directory: {target}")
+        try:
+            os.replace(target, rollback_dir)
+            prior_moved = True
+        except OSError as e:
+            _die(2, f"failed to move prior target aside: {e}")
+
+    try:
+        os.replace(staging, target)
+    except OSError as e:
+        if prior_moved:
+            try:
+                os.replace(rollback_dir, target)
+            except OSError:
+                pass
+        _die(2, f"commit swap failed: {e}")
+
+    if prior_moved:
+        try:
+            shutil.rmtree(rollback_dir)
+        except OSError:
+            pass
+
+    _ok({"committed": str(target)})
+
+
+def _is_link_or_junction(p: Path) -> bool:
+    """True for POSIX symlinks AND Windows junctions/symlinks.
+
+    `Path.is_symlink()` is False for Windows junctions; os.readlink succeeds
+    for both symlinks and junctions (since CPython 3.8 on Windows). A regular
+    directory raises OSError on readlink, which is the signal we want to
+    refuse replacement.
+    """
+    if p.is_symlink():
+        return True
+    if not p.exists() and not p.is_symlink():
+        return False
+    try:
+        os.readlink(p)
+        return True
+    except OSError:
+        return False
+
+
+def cmd_flip_link(link: Path, target: str) -> None:
+    """Atomically point <link> at <target> using rename-over-symlink pattern.
+
+    target is the value of the symlink (may be relative, as is convention
+    for `active -> 1.0.0`). Held lock on <link>.lock prevents concurrent flips.
+
+    On Windows, os.symlink requires Developer Mode or admin. When that fails
+    with PRIVILEGE_NOT_HELD/ACCESS_DENIED the helper falls back to a directory
+    junction (no elevation needed); junctions resolve identically for
+    skf-skill-inventory's resolve_active_version().
+    """
+    lock_path = link.with_name(link.name + ".skf-lock")
+    link.parent.mkdir(parents=True, exist_ok=True)
+
+    # Refuse only if <link> is a real directory/file (not a symlink or junction).
+    # Replacing a real dir would lose user data; replacing a link is the point.
+    if link.exists() and not _is_link_or_junction(link):
+        _die(2, f"refusing to replace non-link: {link}")
+
+    lock_fd = os.open(lock_path, os.O_WRONLY | os.O_CREAT, 0o644)
+    lock_held = False
+    try:
+        try:
+            _acquire_lock(lock_fd)
+            lock_held = True
+        except OSError as e:
+            if e.errno == errno.EAGAIN:
+                _die(2, f"another process holds flip lock on {link}")
+            raise
+
+        tmp_link = link.with_name(link.name + ".skf-tmp-link")
+        if tmp_link.is_symlink() or tmp_link.exists():
+            # On Windows a junction returns is_dir()=True, exists()=True but
+            # is_symlink()=False — must rmdir/unlink based on type.
+            if tmp_link.is_dir() and not tmp_link.is_symlink():
+                tmp_link.rmdir()
+            else:
+                tmp_link.unlink()
+        try:
+            link_kind = _create_symlink_or_junction(target, tmp_link)
+        except OSError as e:
+            if os.name == "nt" and getattr(e, "winerror", None) in (1314, 5):
+                _die(
+                    2,
+                    "symlink/junction creation failed on Windows. Junction fallback "
+                    "requires the target directory to exist. Either enable Developer "
+                    "Mode (Settings → Privacy & Security → For Developers) or use WSL2.",
+                )
+            raise
+        # os.replace can swap a symlink-over-symlink atomically, but Windows
+        # rejects renaming a directory (junction) over an existing directory
+        # (junction or real). Drop the existing link first when junction-based.
+        if link_kind == "junction" and (link.is_dir() or link.is_symlink() or link.exists()):
+            if link.is_symlink() or not link.is_dir():
+                link.unlink()
+            else:
+                link.rmdir()
+        os.replace(tmp_link, link)
+    finally:
+        if lock_held:
+            _release_lock(lock_fd)
+        os.close(lock_fd)
+        # Lock file is bookkeeping only — once the fd is closed the lock is
+        # gone, so leaving the file around just litters the skill_group dir.
+        # Best-effort unlink; a concurrent flipper may have already removed it.
+        try:
+            lock_path.unlink()
+        except OSError:
+            pass
+
+    _ok({"link": str(link), "points_to": target, "kind": link_kind})
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_write = sub.add_parser("write", help="Atomic file write from stdin")
+    p_write.add_argument("--target", type=Path, required=True)
+
+    p_stage = sub.add_parser("stage-dir", help="Create staging directory")
+    p_stage.add_argument("--target", type=Path, required=True)
+
+    p_commit = sub.add_parser("commit-dir", help="Commit staging directory to target")
+    p_commit.add_argument("--target", type=Path, required=True)
+    p_commit.add_argument("--rollback", action="store_true", help="Restore from rollback dir instead of committing")
+
+    p_flip = sub.add_parser("flip-link", help="Atomic symlink flip")
+    p_flip.add_argument("--link", type=Path, required=True)
+    p_flip.add_argument("--target", type=str, required=True)
+
+    args = parser.parse_args()
+
+    if args.cmd == "write":
+        cmd_write(args.target)
+    elif args.cmd == "stage-dir":
+        cmd_stage_dir(args.target)
+    elif args.cmd == "commit-dir":
+        cmd_commit_dir(args.target, rollback=args.rollback)
+    elif args.cmd == "flip-link":
+        cmd_flip_link(args.link, args.target)
+
+
+if __name__ == "__main__":
+    main()