bmad-module-skill-forge 3.0.0 → 4.0.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "3.0.0",
+      "version": "4.0.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -32,7 +32,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "3.0.0"
+skf_version: "4.0.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/examples.md

@@ -325,7 +325,7 @@ Generated skills automatically follow authoring best practices: third-person des
 
 ### Scripts & Assets
 
-If your source repo includes executable scripts (such as `scripts/`, `bin/` or `tools/`) or static assets (such as `assets/`, `templates/` or `schemas/`), SKF detects and packages them automatically with provenance tracking. Scripts and assets you add yourself under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are preserved during updates, just like `<!-- [MANUAL] -->` markers in SKILL.md.
+If your source repo includes executable scripts (such as `scripts/`, `bin/`, `tools/` or `cli/`; when one of these folders is a Python package, holding `__init__.py`, only its `__main__.py` and the modules with a shebang or an `if __name__ == "__main__":` block count as scripts) or static assets (such as `assets/`, `templates/` or `schemas/`), SKF detects and packages them automatically with provenance tracking. Only the files the brief's `scope.include` takes and its `scope.exclude` leaves are packaged, and Audit Skill reports a new one the same way. Scripts and assets you add yourself under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are preserved during updates, just like `<!-- [MANUAL] -->` markers in SKILL.md.
 
 ### Let the Health Check Run
 

package/docs/troubleshooting.md

@@ -49,6 +49,12 @@ Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) (the `c
 
 When ccc is available (Forge+, or Deep with ccc), create-skill indexes the skill's source with it. A local source folder inside your project or inside another git checkout (a subfolder such as `./packages/lib`, a linked worktree or a submodule) becomes a ccc project of its own, and ccc does not gitignore an index there. create-skill keeps it out of git by writing a `.gitignore` holding `*` inside that `.cocoindex_code/` folder, and says so in one line; it never edits your own `.gitignore`. For a folder an earlier SKF release left untracked, run create-skill for that source again, or create `<source>/.cocoindex_code/.gitignore` holding the single line `*`. If you already committed the index, `git rm -r --cached <source>/.cocoindex_code` stops tracking it.
 
+### Setup says the CCC index failed
+
+Surfaced by `@Ferris SF` when ccc is available and `ccc index` exits with an error: the forge status shows `indexing failed, semantic discovery unavailable this session` with ccc's own message. Setup still finishes at your tier; only semantic discovery is off until the index builds. One cause is an index that an older ccc wrote and the installed ccc cannot read, with a message such as `Failed to deserialize pickle payload`.
+
+**Fix:** from the project root, run `ccc reset`, then `ccc daemon restart`, then re-run `@Ferris SF`. `ccc reset` deletes only the index databases and keeps `.cocoindex_code/settings.yml` with SKF's exclusions. Restart the daemon before indexing again: it still holds the databases `ccc reset` deleted, so an index built right after the reset can fail with `environment already open in this program`.
+
 ### `@Ferris deepwiki` shows a deprecation notice
 
 The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](/docs/forge-auto.md). It was renamed to avoid confusion with the DeepWiki MCP server, since the pipeline compiles a verified skill from source and does **not** call that server. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
@@ -145,6 +151,8 @@ Surfaced by `@Ferris US` when another update of the same skill holds its run loc
 
 **`run-lock-lost`:** the same status with this reason means the update waited at a question past the stale time, so another update may have changed the skill (`error.phase` is `merge:run-lock` or `write:run-lock`). It stops before it writes `metadata.json`, and the halt undoes anything the update already wrote: it removes the new version folders, or, for a repair from a test report, restores the files it edited in place from the copy it took first, and the message says which. Re-run the update once no other update of that skill runs; if a version folder the message names is still on disk, delete it first.
 
+**`busy`:** the same status with this reason means another run's flip of the skill's `active` link (Create Skill, Quick Skill or Drop Skill) held the link's lock for 5 seconds while the update was pointing the link at its version (`error.phase` is `write:active-symlink`). The update did not change the link, and the halt undid what the update wrote. Re-run the update once that run ends.
+
 ### A report says `Tessl Review: off`, `not run`, `no result` or `failed`
 
 Create Skill and Test Skill record one `Tessl Review:` line in the evidence report and the test report. Tessl Review is optional and never stops a run, so the line says why it produced no score:

package/docs/verifying-a-skill.md

@@ -42,7 +42,7 @@ Provenance maps live in `forge-data/{skill}/{version}/provenance-map.json` in th
 }
 ```
 
-This is the entry SKF 3.0.0 writes for cognee's `search` when ast-grep matches it, shortened to its first two parameters (`search` takes 20). It points at line 27, where `search` is defined at cognee v1.0.0's commit (`3c048aa4`), and its labels follow the tool that read it: an ast-grep match gives `T1`, `ast-grep`, the node kind its rule matched and an `[AST:]` citation. An export read by eye instead, because ast-grep could not parse its file or no rule matched it, gets `T1-low`, `source-read`, no node kind and an `[SRC:]` citation, at every forge tier.
+This is the entry SKF 3.0.0 writes for cognee's `search` when ast-grep matches it, shortened to its first two parameters (`search` takes 20). It points at line 27, where `search` is defined at cognee v1.0.0's commit (`3c048aa4`), and its labels follow the tool that read it: an ast-grep match gives `T1`, `ast-grep`, the node kind its rule matched and an `[AST:]` citation. An export read by eye instead, because ast-grep could not parse its file, an ast-grep call that failed or timed out left its file unread, or no rule matched it, gets `T1-low`, `source-read`, no node kind and an `[SRC:]` citation, at every forge tier.
 
 The published entry in oh-my-skills' [`forge-data/oms-cognee/1.0.0/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/provenance-map.json) is a good one to check by hand, because it was compiled before labels followed the tool. It records `search` as `source-read` but labels it `T1`, and it points at line 26, the blank line above the definition, while the skill's `SKILL.md` cites `[AST:cognee/api/v1/search/search.py:L27]`. SKF 3.0.0's [line, label and citation checks](#workflow-time-enforcement) flag all three when Create Skill or Update Skill writes such a map: a source read is `T1-low` with an `[SRC:]` citation, and its line is 27, the `def` line.
 
@@ -205,9 +205,13 @@ Each step rates every gap it records against the Gap Severity table in Test Skil
 |---|---|
 | **Critical** | A wrong signature, or a fabricated one (a documented export that the source does not define at the line the skill cites); a broken reference in a stack skill (a file, skill, type, or `scripts/` or `assets/` file that does not exist) |
 | **High** | An inaccurate reference in a stack skill (the target exists but does not match), or a reference whose real path leads outside the skill and its sources; a split-body mismatch (`SKILL.md` and a `references/` file document one export differently); `metadata.json` stats that count every export as documented while some are missing from the skill; in an individual skill, a missing required section, an unbalanced code fence, or an example that awaits a sync function or skips the `await` of an async one |
-| **Medium** | A missing export or type (a missing export lowers Export Coverage); stale documentation (a documented export the source no longer exports); an incomplete integration pattern in a stack skill; in an individual skill, a code fence with no language tag, a function no example names, or a table row whose column count differs from its header |
+| **Medium** | A missing export or type (a missing export lowers Export Coverage); stale documentation (a documented export outside the coverage surface that the run did not match to one declaration in the source, or that a brief scopes out); an incomplete integration pattern in a stack skill; in an individual skill, a code fence with no language tag, a function no example names, or a table row whose column count differs from its header |
 | **Low** | Gaps in metadata, the description or provenance lines, such as missing optional metadata or a provenance line that is not the definition line |
-| **Info** | Observations such as style suggestions; discovery testing not performed |
+| **Info** | Observations such as style suggestions or a documented extra (a documented name outside the coverage surface that the source still declares); discovery testing not performed |
+
+Only some runs can find a documented extra: the source must be Python or TypeScript/JavaScript, and the run needs the Forge, Forge+ or Deep tier, `analysis_confidence` `full`, `workspaceDrift` not `overridden`, a provenance map and a coverage surface that a complete extraction built. On any other run, every documented export outside the coverage surface is stale documentation.
+
+A declaration the run finds only in an `example`, `demo`, `demos`, `sample`, `samples`, `scripts`, `playground`, `bench`, `benchmark` or `migrations` folder right below a package's root, or in an `e2e` or `__fixtures__` folder anywhere, does not count, so a name declared only in `scripts/foo.py` stays stale documentation unless the provenance map cites a file in that folder. Nor does a module named after the name count (such as `client.py` for a documented `client()`) when the skill documents the name as a function, hook, class, interface, enum or type, unless the provenance map records the name as a module or package, or the module is a TypeScript or JavaScript file that is itself the export (`export default`, `module.exports =`).
 
 Discovery testing runs after the hard gate, so a discovery gap (Info, Medium or High) is counted in the Gap Report and blocks nothing.
 

package/docs/workflows.md

@@ -208,7 +208,7 @@ Each workflow is also a skill you can run directly, without Ferris: `/skf-setup`
 
 **Baseline:** An audit compares the skill with the baseline it recorded when it was built. An interactive audit shows its baseline summary and analysis plan and goes straight on. It stops to ask only when this run's forge tier is below the tier the skill was compiled at (so the diff can report as drift what only the tools changed; a compose-mode stack or a docs-only skill re-reads no source and never stops for this), or when the provenance map is more than 90 days old. At that stop, `[C]` continues, and `[X]` stops the run with exit `6` (`user-cancelled`) and keeps the drift report, which then holds the baseline only. A headless run continues. A skill with no provenance map, such as a Quick Skill, stops with `no-baseline` (exit `3`) in every mode, and the message points to `@Ferris TS` (test it against its source) or `@Ferris CS` (create it again so it can be audited). A docs-only skill is audited by its documents: each tracked document's hash is compared with the one recorded at compile time, and a changed document is graded HIGH, so the score is SIGNIFICANT, with `next_workflow` `update-skill`, or CLEAN when nothing changed. A docs-only skill that records no hash stops with `no-baseline`, one with no document that could be compared stops with `source-unreadable` (exit `3`), and a partial comparison adds a `doc_fetch_failed` or `doc_not_hashed` warning. The audit checks `uv` and its helpers before its first question and stops with `helper-missing` (exit `3`) when one is missing. The `degraded` input and the `severity_rules_path` setting are gone.
 
-**Provenance labels:** An export's labels, its confidence tier and its extraction method, follow the tool that read it, so a later read can change them, such as T1 to T1-low when ast-grep could not parse the file this time, or back. The drift report lists such changes in a **Provenance label differences (not drift)** table: they are not drift, are not counted in Total Drift Items and move no score.
+**Provenance labels:** An export's labels, its confidence tier and its extraction method, follow the tool that read it, so a later read can change them, such as T1 to T1-low when ast-grep could not parse the file this time, or back. The drift report lists such changes in a **Provenance label differences (not drift)** table: they are not drift, are not counted in Total Drift Items and move no score. For a `public-api` skill, the new exports off the public surface Create Skill and Update Skill keep the provenance map to are listed apart, named in an **Off the public surface** note, and not counted in Total Drift Items; when the audit cannot read the surface (at Quick tier, for example), every new export is reported as added and the run warns `public_surface_not_applied`.
 
 **Doc drift:** A skill compiled before SKF 3.0.0 recorded its README as a `blob/main` page, or as a URL with no scheme, so doc drift keeps flagging its README until Create Skill compiles it again and records the raw README at the ref the skill was built from.
 
@@ -368,7 +368,7 @@ Default pass threshold: **80%**. Inside a pipeline the default follows the alias
 
 **Key Steps:** Select skill → Select version(s) + mode → Update manifest → Rebuild context files → Delete files (if purge)
 
-**Safety:** Active version guard: you cannot drop the currently active version while other non-deprecated versions exist. To drop it and keep another version, make the version you keep active first: point the skill's `active` link at it (`ln -sfn <version to keep> <skills_output_folder>/<name>/active`), run `@Ferris EX` on the skill, which exports that version and archives the old one, then drop the old one. To drop the whole skill instead, choose the All versions option. Soft drop is reversible by editing the manifest. Drop offers a skill folder SKF did not generate only when the manifest lists it, and then only for deprecate. A purge deletes only SKF output: a whole-skill purge of a folder that also holds other files is refused, and so is a purge through a link. The same goes for the skill's folder in `forge_data_folder`, except that a folder there SKF did not generate (another tool's folder of the same name, or a link) is left in place and named in the report. A headless drop of a skill with no manifest entry needs `--mode purge`. A headless drop of a skill in the export manifest needs `version=all` or the one version to drop: without it, the run stops with exit `2` (`input-missing`) before it changes anything. A specific version for a draft skill (one with no manifest entry) stops with exit `2` (`input-invalid`) in every mode, since a draft is dropped whole.
+**Safety:** Active version guard: you cannot drop the currently active version while other non-deprecated versions exist. To drop it and keep another version, make the version you keep active first: point the skill's `active` link at it (`uv run _bmad/skf/shared/scripts/skf-atomic-write.py flip-link --link <skills_output_folder>/<name>/active --target <version to keep>`, which works in Git Bash, PowerShell and WSL2), run `@Ferris EX` on the skill, which exports that version and archives the old one, then drop the old one. To drop the whole skill instead, choose the All versions option. Soft drop is reversible by editing the manifest. Drop offers a skill folder SKF did not generate only when the manifest lists it, and then only for deprecate. A purge deletes only SKF output: a whole-skill purge of a folder that also holds other files is refused, and so is a purge through a link. The same goes for the skill's folder in `forge_data_folder`, except that a folder there SKF did not generate (another tool's folder of the same name, or a link) is left in place and named in the report. A headless drop of a skill with no manifest entry needs `--mode purge`. A headless drop of a skill in the export manifest needs `version=all` or the one version to drop: without it, the run stops with exit `2` (`input-missing`) before it changes anything. A specific version for a draft skill (one with no manifest entry) stops with exit `2` (`input-invalid`) in every mode, since a draft is dropped whole.
 
 **Preview first:** Add `--dry-run` to `@Ferris RS` or `@Ferris DS` to see which folders, manifest entries and context files would change. Nothing is written or deleted.
 
@@ -517,7 +517,7 @@ SKF_SETUP_RESULT_JSON: {"skf_setup":{"status":"success","tier":"Deep","previous_
 
 Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome, with no ASCII-art parsing and no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/references/write-config.md) writer. Branch on the top-level `status` field (`success`, `tier_failure`, or `blocked`) rather than composing the outcome from `require_tier_satisfied` + `error`. A write failure arrives as `blocked`, with an `error.phase` of `step 2:write-tools` or `step 2:forge-data-dir`. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
 
-Setup is not the only workflow whose result line is the run's final message: a headless Test Skill, Quick Skill (one target, not `--batch`), Brief Skill (also under `[auto]`), Update Skill, Export Skill (a `--dry-run` too) or campaign run hands its `SKF_TEST_RESULT_JSON`, `SKF_QUICK_SKILL_RESULT_JSON`, `SKF_BRIEF_RESULT_JSON`, `SKF_UPDATE_RESULT_JSON`, `SKF_EXPORT_RESULT_JSON` or `SKF_CAMPAIGN_RESULT_JSON` line to the shared health check, which displays it last, after everything else it shows (under `--no-health-check`, Test Skill displays it itself as its last line).
+Setup is not the only workflow whose result line is the run's final message: a headless Test Skill, Quick Skill (one target, not `--batch`), Brief Skill (also under `[auto]`), Update Skill, Audit Skill, Drop Skill, Export Skill (a `--dry-run` too) or campaign run hands its `SKF_TEST_RESULT_JSON`, `SKF_QUICK_SKILL_RESULT_JSON`, `SKF_BRIEF_RESULT_JSON`, `SKF_UPDATE_RESULT_JSON`, `SKF_AUDIT_RESULT_JSON`, `SKF_DROP_SKILL_RESULT_JSON`, `SKF_EXPORT_RESULT_JSON` or `SKF_CAMPAIGN_RESULT_JSON` line to the shared health check, which displays it last, after everything else it shows (under `--no-health-check`, Test Skill displays it itself as its last line). A Drop Skill `--dry-run` stops at its confirmation gate and displays its line itself, last.
 
 **Exception: `/skf-quick-skill` headless emits structured progress and result envelopes.** Headless `/skf-quick-skill` runs are first-class building blocks for batch automators. Four operational contracts go beyond per-gate auto-proceed:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/knowledge/qmd-registry.md

@@ -137,7 +137,7 @@ Then append/replace the registry entry in forge-tier.yaml. Failures never block
 
 **Context:** Audit-skill's Deep-tier semantic diff retrieves what the skill documents about each export, then checks each claim against the current source.
 
-**Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log and continue without T2 enrichment — not an error.
+**Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log it and read the skill's own files instead (the direct-content fallback, labeled T1-low-fallback): not an error.
 
 ### Example 3: Janitor Hygiene (setup)
 

package/src/knowledge/version-paths.md

@@ -266,7 +266,7 @@ Drops a specific version or the entire skill with two modes:
 
 **Hard drop (`--purge`):** Same as soft drop, plus deletes the version directory (`{skill_package}`) and forge data directory (`{forge_version}`, only when SKF generated it). Irreversible.
 
-**Active version guard:** Cannot drop the active version while other non-deprecated versions exist. The user must either make the version they keep active first (point the `active` link at it with `ln -sfn <version to keep> {skill_group}/active`, then run export-skill: the Manifest-lag guard makes it export that version, and its manifest update archives the old one), or drop all versions at once.
+**Active version guard:** Cannot drop the active version while other non-deprecated versions exist. The user must either make the version they keep active first (point the `active` link at it with `uv run _bmad/skf/shared/scripts/skf-atomic-write.py flip-link --link {skill_group}/active --target <version to keep>`, then run export-skill: the Manifest-lag guard makes it export that version, and its manifest update archives the old one), or drop all versions at once.
 
 **Skill-level drop:** Removes the entire `{skill_group}` from the manifest. If purge, also deletes `{skill_group}` and `{forge_group}` directories (the forge one only when SKF generated it).
 

package/src/shared/health-check.md

@@ -24,17 +24,8 @@ Reflect on the workflow that just completed. If real friction, bugs, or gaps wer
 - Read the complete step file before taking any action
 - Speak in `{communication_language}`
 
-### Role Reinforcement:
-- You are a **self-improvement auditor** — honest, precise, evidence-based
-- You report ONLY what you actually experienced during THIS session
-- You are NOT a creative writer looking for things to say
-
-### Anti-Hallucination Rules:
-- **DO NOT FABRICATE ISSUES.** If the workflow ran smoothly, say so and exit. Inventing issues to appear thorough is a SYSTEM FAILURE.
-- Only report issues you **ACTUALLY encountered** during THIS workflow execution
-- Every finding MUST cite the **specific step file path and section** where the issue occurred
-- If you are unsure whether something was a real issue or your own confusion, DO NOT report it
-- Reporting zero issues is the EXPECTED outcome for a well-designed workflow
+### Findings Rule:
+Zero findings is the expected outcome of a good run. Report only a bug, friction or gap you hit in this session, each with the step file and section where it happened, and leave out anything you cannot tell apart from your own confusion: a finding you invent can become a real GitHub issue filed against the module.
 
 ---
 
@@ -264,7 +255,6 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 - **Respect the length budgets.** Finding, Expected, Actual, Impact are each ONE sentence. Evidence is 2-5 bullets, not prose. Suggested Fix is 1-3 sentences with ONE recommendation — multiple options go in the `Alternatives considered` collapsible or (better) not at all.
 - **Quote, don't paraphrase.** In Evidence, cite the exact `file:line` and put the quoted text in quotes. Link the convention to the instruction that caused it.
 - **Never narrate the session.** The reader wants the defect, not the story. If a sentence starts with "During my run..." or "I was trying to...", delete it.
-- **If unsure whether it's a real issue, do not submit it.** Reporting zero findings is a healthy outcome.
 
 **Issue body format:**
 ```markdown
@@ -389,41 +379,3 @@ Or open them manually at: <https://github.com/{healthCheckRepo}/issues/new/choos
 Workflow complete."
 
 When `{result_envelope_line}` is bound (§0), display it verbatim after that block, as the last line.
-
----
-
-## CRITICAL STEP COMPLETION NOTE
-
-This is the TERMINAL step — shared across all SKF workflows. After the health check completes (clean run, or findings submitted, queued or discarded), the workflow is fully done. No further steps to load.
-
----
-
-## SYSTEM SUCCESS/FAILURE METRICS
-
-### SUCCESS:
-
-- Clean runs exit immediately with no findings (most common outcome)
-- Findings cite specific step files and sections with real evidence
-- User review gate presented before any submission
-- Severity gate respected: only `bug` submits live by default; `friction`/`gap` require explicit opt-in
-- Fingerprint computed deterministically and applied to both title prefix and `fp-*` label
-- `fp-*` label is ensured idempotently (`gh label create ... || true`) before `gh issue create`, so a first reporter of a defect never hard-fails
-- Remote dedup search performed before every live submission; existing issues get reactions/delta-comments rather than duplicates
-- Seen-cache at `{seenCachePath}` updated after every submission/reaction and consulted before every search
-- Local fallback files written with clear manual submission instructions (when `gh` unavailable)
-- Workflow ends cleanly
-
-### SYSTEM FAILURE:
-
-- Fabricating issues that were not actually encountered during the session
-- Reporting vague issues without step file citations ("the workflow was confusing")
-- Skipping the user review gate (resolving it to its listed headless default **\[Q]** is not skipping it: nothing is submitted)
-- Creating issues without user confirmation
-- Creating a new issue when a matching `fp-*` open issue already exists (without explicit user \[N] override)
-- Submitting `friction` or `gap` findings live without the explicit severity-gate opt-in
-- Using LLM-judged "similarity" in place of the deterministic fingerprint
-- Not updating the seen-cache, causing the same user to re-report identical fingerprints
-- Not providing the local fallback when `gh` is unavailable
-- Continuing to load steps after this one (this is terminal)
-
-**Master Rule:** Honesty is the only policy. Zero findings is the expected, healthy outcome. Fabricating issues to appear thorough undermines the entire self-improvement system and constitutes SYSTEM FAILURE.

package/src/shared/scripts/schemas/skf-audit-result-envelope.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-audit-result-envelope.v1.json",
   "title": "SKF_AUDIT_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document skf-audit-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_AUDIT_RESULT_JSON: ': once on stdout when step 6 (report) finishes, before it chains to the health check, and once on stderr at every HARD HALT (status error). The shared emitter, skf-emit-result-envelope.py, builds every line from the payload a stage stages in the run folder, folds in the auto-decisions and warnings the run recorded there, derives exit_code from halt_reason, stamps run_id and result_path, writes the result files on success, and checks the line against this schema, so the model never types it. The skill's references/headless-contract.md holds the exit-code table and its stage files show the halt command.",
+  "description": "Single-line JSON document skf-audit-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_AUDIT_RESULT_JSON: ': once on stdout when step 6 (report) finishes, which the health check displays as the run's last line, and once on stderr at every HARD HALT (status error). The shared emitter, skf-emit-result-envelope.py, builds every line from the payload a stage stages in the run folder, folds in the auto-decisions and warnings the run recorded there, derives exit_code from halt_reason, stamps run_id and result_path, writes the result files on success, and checks the line against this schema, so the model never types it. The skill's references/headless-contract.md holds the exit-code table and its stage files show the halt command.",
   "$defs": {
     "skf-envelope": {
       "description": "The shared emitter's settings for this workflow, read by skf-emit-result-envelope.py: the workflow, the line's prefix, the wrapper, the status a halt carries, the exit code of each halt_reason and the result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
@@ -164,7 +164,7 @@
     "warnings": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 },
-      "description": "Optional. Non-fatal anomalies the run recorded in its sink or the emitter raised, one string each, starting with its code: upstream_tree_unavailable when [C] could not read the upstream ref into a private tree and the audit stayed on the baseline, source_tree_not_removed when the private tree could not be removed, doc_fetch_failed and doc_not_hashed (each with its count) when a docs-only skill's score leaves out documents that could not be fetched or have no recorded hash, customization_resolver_unavailable when the customization resolver failed and only the bundled customize.toml applied, and result_file_write_failed when a result file could not be written. Present only when there is at least one."
+      "description": "Optional. Non-fatal anomalies the run recorded in its sink or the emitter raised, one string each, starting with its code: upstream_tree_unavailable when [C] could not read the upstream ref into a private tree and the audit stayed on the baseline, source_tree_not_removed when the private tree could not be removed, recipe_runner_failed (with the recipe runner's error line) when the runner left no JSON and named an error on stderr, so re-index extracted without it, public_surface_not_applied (with the rule's problem) when re-index could read no public surface for a public-api skill (Quick tier, a runner that could not run, an incomplete run, one with errors, or an entry point it could not trace), so structural diff reported every export the provenance map does not hold as added, doc_fetch_failed and doc_not_hashed (each with its count) when a docs-only skill's score leaves out documents that could not be fetched or have no recorded hash, new_files_not_checked (with the reason) when the Script/Asset Drift check looked for no new script, asset or document because the skill has no brief it could read or a helper it needs could not be loaded, customization_resolver_unavailable when the customization resolver failed and only the bundled customize.toml applied, and result_file_write_failed when a result file could not be written. Present only when there is at least one."
     },
     "error": {
       "type": "object",

package/src/shared/scripts/schemas/skf-update-result-envelope.v1.json

@@ -50,7 +50,7 @@
             "halted-for-concurrent-run",
             "blocked"
           ],
-          "description": "Single-field outcome for pipeline branching. 'success' when the run completed and wrote the updated artifacts. 'no-changes' when detect-changes found nothing to update. 'detect-only' when the workflow was invoked with --detect-only and exited after step 2 without modifying any artifact. 'dry-run' when the workflow was invoked with --dry-run and exited after step 3 (re-extract) without merging or writing: the envelope describes what merge+write WOULD have done. Each 'halted-for-*' value corresponds to a documented halt in the stage prose (workspace-drift from gap-driven.md §3, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from gap-driven.md §4a, manual-mismatch from write.md §1, after write.md §6's provenance fixes and after write.md §7's skill-check edits (all error.phase 'write:verify-manual-integrity'), from merge.md §6b's check of the merged SKILL.md before it is published (error.phase 'merge:verify-manual-integrity') and from a headless merge that meets a [MANUAL] conflict (error.phase 'merge:conflict-resolution'), write-failure for a merge.md §6b version-folder or SKILL.md write failure (among them error.phase 'merge:new-version-folder' when the version folder already exists or the next version cannot be computed), a failed write in write.md §2 to §5 (error.phase 'write:artifact-write') and a write.md §8/§8a active-link failure, concurrent-run when init.md §1b's acquire finds another run's fresh run lock (error.phase 'init:concurrency-guard'), or when this run no longer holds its lock at the renewal before merge.md §6b or write.md §2 writes (error.phase 'merge:run-lock' or 'write:run-lock'; error.reason 'run-lock-lost: ...' when the lock lapsed while the run waited). error.reason names the run that holds a lock, never a PID). 'blocked' is the catch-all for halts that don't map to a documented status code, among them a headless run given no skill name (error.phase 'init:skill-name', error.reason starting 'input-missing'), a stack skill (error.phase 'init:stack-skill-guard'), init.md §6b (error.phase 'init:source-tree') when no commit to read could be obtained, a helper that failed (each its own '<step>:<section>' phase), and a private source tree that disappeared mid-run (error.phase '<step>:source-tree-missing'). A halt after merge.md §6b's first write, until write.md §10 closes the rollback window, first undoes it: a gap-driven repair's package is restored from the snapshot it took, and a new version's folders are removed, unless the active link already names the new version, which the halt keeps. write.md §8 points the active link at the new version only after §6 and §7, the last checks that can halt, so a [MANUAL] halt never leaves a live version behind. NOTE: detect-only and dry-run are successful exits: pipelines treating non-success as failure must include them in the success set."
+          "description": "Single-field outcome for pipeline branching. 'success' when the run completed and wrote the updated artifacts. 'no-changes' when detect-changes found nothing to update. 'detect-only' when the workflow was invoked with --detect-only and exited after step 2 without modifying any artifact. 'dry-run' when the workflow was invoked with --dry-run and exited after step 3 (re-extract) without merging or writing: the envelope describes what merge+write WOULD have done. Each 'halted-for-*' value corresponds to a documented halt in the stage prose (workspace-drift from gap-driven.md §3, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from gap-driven.md §4a, manual-mismatch from write.md §1, after write.md §6's provenance fixes and after write.md §7's skill-check edits (all error.phase 'write:verify-manual-integrity'), from merge.md §6b's check of the merged SKILL.md before it is published (error.phase 'merge:verify-manual-integrity') and from a headless merge that meets a [MANUAL] conflict (error.phase 'merge:conflict-resolution'), write-failure for a merge.md §6b version-folder or SKILL.md write failure (among them error.phase 'merge:new-version-folder' when the version folder already exists or the next version cannot be computed), a failed write in write.md §2 to §5 (error.phase 'write:artifact-write') and a write.md §8/§8a active-link failure, concurrent-run when init.md §1b's acquire finds another run's fresh run lock (error.phase 'init:concurrency-guard'), or when this run no longer holds its lock at the renewal before merge.md §6b or write.md §2 writes (error.phase 'merge:run-lock' or 'write:run-lock'; error.reason 'run-lock-lost: ...' when the lock lapsed while the run waited), or when write.md §8 finds another flip of the active link holding its lock for 5 s (error.phase 'write:active-symlink', error.reason 'busy: ...'). error.reason names the run that holds a run lock, never a PID). 'blocked' is the catch-all for halts that don't map to a documented status code, among them a headless run given no skill name (error.phase 'init:skill-name', error.reason starting 'input-missing'), a stack skill (error.phase 'init:stack-skill-guard'), init.md §6b (error.phase 'init:source-tree') when no commit to read could be obtained, a helper that failed (each its own '<step>:<section>' phase), and a private source tree that disappeared mid-run (error.phase '<step>:source-tree-missing'). A halt after merge.md §6b's first write, until write.md §10 closes the rollback window, first undoes it: a gap-driven repair's package is restored from the snapshot it took, and a new version's folders are removed, unless the active link already names the new version, which the halt keeps. write.md §8 points the active link at the new version only after §6 and §7, the last checks that can halt, so a [MANUAL] halt never leaves a live version behind. NOTE: detect-only and dry-run are successful exits: pipelines treating non-success as failure must include them in the success set."
         },
         "skill_name": {
           "type": "string",
@@ -128,7 +128,7 @@
         "warnings": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Non-fatal anomalies surfaced during the run. May include workspace_drift_overridden, scope_reconciliation_post entries, qmd indexing failures, source-tree:, source-not-fetched, source-version-lower, file-diff-unavailable, no-baseline-time, moved-check-skipped and unknown-language (detect-changes.md §2.1 Category A), workspace-clone-not-updated, target-ref-not-recorded, source-tree-not-removed, run-lock-replaced (init.md §1b took over a stale run lock) and run-lock-not-released entries, unconsumed-test-report (init.md §4b: a failing test report newer than the skill that this normal run did not apply), interrupted-run-cleaned and interrupted-run-not-cleaned (init.md §1b undid what an update whose stale lock it replaced had written), proposed-amendment: entries (a --detect-only or --dry-run run's skill brief decisions, not written), doc-fetch-failed, doc-not-hashed and doc-drift-not-checked (a docs-only skill's documents), rollback-incomplete (a halt could not undo all of this run's writes), run-state-not-finished, customization_resolver_unavailable, test-report: entries (what the test report helpers could not read, and test-report: not routed: for each gap a gap-driven run does not repair), etc. Empty when none."
+          "description": "Non-fatal anomalies surfaced during the run. May include workspace_drift_overridden, scope_reconciliation_post entries, qmd indexing failures, source-tree:, source-not-fetched, source-version-lower, file-diff-unavailable, no-baseline-time, moved-check-skipped and unknown-language (detect-changes.md §2.1 Category A), new-files-not-checked (Category D: a skill with no brief, so no new script or asset was looked for), workspace-clone-not-updated, target-ref-not-recorded, source-tree-not-removed, run-lock-replaced (init.md §1b took over a stale run lock) and run-lock-not-released entries, unconsumed-test-report (init.md §4b: a failing test report newer than the skill that this normal run did not apply), interrupted-run-cleaned and interrupted-run-not-cleaned (init.md §1b undid what an update whose stale lock it replaced had written), proposed-amendment: entries (a --detect-only or --dry-run run's skill brief decisions, not written), doc-fetch-failed, doc-not-hashed and doc-drift-not-checked (a docs-only skill's documents), rollback-incomplete (a halt could not undo all of this run's writes), run-state-not-finished, public-api-counted-by-hand: entries (write.md §2: the recipe runner exited 2, so the public names were found without it; each quotes the runner's error line), customization_resolver_unavailable, test-report: entries (what the test report helpers could not read, and test-report: not routed: for each gap a gap-driven run does not repair), etc. Empty when none."
         },
         "error": {
           "oneOf": [

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

@@ -23,17 +23,22 @@ Subcommands:
 
   flip-link  Point the link <link> at <target>: create the new link as
              <link>.skf-tmp-link, then os.replace it over <link>, holding an
-             exclusive lock on <link>.skf-lock (removed afterwards). Refuses
-             to replace a <link> that is a real directory or file.
+             exclusive lock on <link>.skf-lock, which only the flip holding
+             it removes. skf-update-active-symlink.py update takes the same
+             lock (take_flip_lock), so one flip of a link runs at a time.
+             Refuses to replace a <link> that is a real directory or file.
 
 Cross-platform: locking branches between fcntl (POSIX) and msvcrt
 (Windows). On Windows os.symlink needs Developer Mode or admin; when it
 fails for lack of privilege, flip-link creates a directory junction
 (mklink /J) instead, which needs neither but requires <target> to be an
-existing directory. A junction cannot be renamed over an existing link,
-so on that path flip-link removes the old link first and the flip is not
-atomic. No test exercises the junction path: CI's Windows runner holds
-symlink privilege.
+existing directory. Windows renames nothing over an existing directory
+link, so on the junction path, and on Windows whenever the rename over the
+old link is refused, replace_link removes the old link first (a junction
+whose folder is gone included) and the flip is not atomic. The Windows
+tests in test-skf-atomic-write.py and test-skf-update-active-symlink.py
+make os.symlink fail as it does without the privilege, so CI's Windows
+runner, which holds it, runs the junction path too.
 
 Exit codes:
   0 on success (JSON on stdout)
@@ -44,8 +49,11 @@ Exit codes:
   2 on a refused or failed operation, with {"status": "error", "message":
     ...} on stderr: write failed, stage-dir could not clear a stale entry,
     commit-dir found a non-directory target or could not swap, flip-link
-    found a non-link at <link> or another process holding its lock; and
-    on bad arguments (argparse usage on stderr, no JSON)
+    found a non-link at <link>, another process holding its lock, a
+    lock file Windows kept refusing to open for its short wait while the
+    file was being removed, or (on POSIX) a locked lock file that kept
+    leaving the path for that same wait; and on bad arguments (argparse
+    usage on stderr, no JSON)
 
 CLI examples:
   cat metadata.json | python3 skf-atomic-write.py write --target /path/to/metadata.json
@@ -63,6 +71,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 if os.name == "nt":
@@ -70,6 +79,18 @@ if os.name == "nt":
 else:
     import fcntl
 
+# While the flip that held <link>.skf-lock is removing it, Windows refuses a
+# new open of the file with PermissionError. flip-link takes that for a held
+# lock and tries again for up to this long (a flip fails fast on contention
+# by design, so the wait is short), then exits 2 as it does for a held lock.
+# The same wait bounds a POSIX flip that keeps finding the file it locked
+# gone from the path: it opens the path again until then, then exits 2.
+# A caller that gives take_flip_lock a longer `wait` (skf-update-active-symlink.py
+# update) keeps both retries going until that wait ends.
+_IS_WINDOWS = os.name == "nt"
+_LOCK_OPEN_WAIT_SECONDS = 1.0
+_LOCK_OPEN_POLL_SECONDS = 0.02
+
 
 def _create_symlink_or_junction(target: str, link_path: Path) -> str:
     """Create a directory link from link_path to target.
@@ -141,6 +162,16 @@ def _release_lock(fd: int) -> None:
             pass
 
 
+# Keep identical to _names_open_file in gap-ledger.py
+# (test/test-skf-atomic-write.py pins the copy).
+def _names_open_file(fd: int, path: Path) -> bool:
+    """True when `path` still names the file open as `fd`."""
+    try:
+        return os.path.samestat(os.fstat(fd), os.stat(path))
+    except OSError:
+        return False
+
+
 def _die(code: int, message: str) -> None:
     print(json.dumps({"status": "error", "message": message}), file=sys.stderr)
     sys.exit(code)
@@ -282,18 +313,182 @@ def _is_link_or_junction(p: Path) -> bool:
         return False
 
 
+def _remove_link(p: Path) -> None:
+    """Remove the symlink or junction at p, whether or not the folder it names exists.
+
+    os.readlink raises for a real folder or file (OSError) and for another
+    Windows reparse point (ValueError), so neither is ever removed. os.unlink
+    removes a symlink, and on Windows a directory symlink or a junction too;
+    os.rmdir is the fallback for a directory link unlink refuses.
+    """
+    if not p.is_symlink():
+        os.readlink(p)
+    try:
+        os.unlink(p)
+    except OSError:
+        os.rmdir(p)
+
+
+def replace_link(link: Path, target: str, tmp_link: Path | None = None) -> str:
+    """Point the link <link> at <target> through <tmp_link>; return "symlink" or "junction".
+
+    The caller holds take_flip_lock(link) and has refused a real folder or
+    file at <link>. A stale <tmp_link> from a crashed flip is removed first.
+    The new link is made at <tmp_link> and renamed over <link>, which is
+    atomic for a symlink on POSIX. Windows renames nothing over an existing
+    directory link, so the old link is removed first on the junction path,
+    and on Windows when the rename is refused: a reader can then find no
+    <link> for a moment. A failure removes <tmp_link> and raises.
+    """
+    if tmp_link is None:
+        tmp_link = link.with_name(link.name + ".skf-tmp-link")
+    if os.path.lexists(tmp_link):
+        _remove_link(tmp_link)
+    link_kind = _create_symlink_or_junction(target, tmp_link)
+    try:
+        if link_kind == "junction" and os.path.lexists(link):
+            _remove_link(link)
+        try:
+            os.replace(tmp_link, link)
+        except OSError:
+            if not _IS_WINDOWS or not os.path.lexists(link):
+                raise
+            _remove_link(link)
+            os.replace(tmp_link, link)
+    except BaseException:
+        try:
+            if os.path.lexists(tmp_link):
+                _remove_link(tmp_link)
+        except (OSError, ValueError):
+            pass
+        raise
+    return link_kind
+
+
+class FlipLockHeld(Exception):
+    """Another flip holds <link>.skf-lock; the message names <link>."""
+
+
+def take_flip_lock(link: Path, wait: float = 0.0) -> int:
+    """Take <link>.skf-lock, the lock every flip of <link> holds, and return its fd.
+
+    flip-link and skf-update-active-symlink.py update both take it, so one
+    flip of a link runs at a time. `wait` is how long to keep trying a lock
+    another flip holds: the call closes the file, sleeps
+    _LOCK_OPEN_POLL_SECONDS and opens the path again. flip-link passes 0
+    and is refused at once. Raises FlipLockHeld when the lock stays held
+    past `wait`, and when the retries cmd_flip_link's docstring describes
+    (Windows refusing the open, a locked file that left the path) run out:
+    they run until max(_LOCK_OPEN_WAIT_SECONDS, wait). release_flip_lock
+    gives the lock back.
+    """
+    lock_path = link.with_name(link.name + ".skf-lock")
+    held_deadline = time.monotonic() + wait
+    deadline = time.monotonic() + max(_LOCK_OPEN_WAIT_SECONDS, wait)
+    vanished = False
+    while True:
+        try:
+            lock_fd = os.open(lock_path, os.O_WRONLY | os.O_CREAT, 0o644)
+        except PermissionError as exc:
+            # Windows refuses to open a file whose removal is pending. A folder
+            # at the path, or nothing there twice running (once can be the
+            # removal ending just now), is a lasting denial: raise it.
+            if not _IS_WINDOWS or os.path.isdir(lock_path):
+                raise
+            if not os.path.lexists(lock_path):
+                if vanished:
+                    raise
+                vanished = True
+                continue
+            vanished = False
+            if time.monotonic() >= deadline:
+                raise FlipLockHeld(f"another process holds flip lock on {link} (last open refused: {exc})")
+            time.sleep(_LOCK_OPEN_POLL_SECONDS)
+            continue
+        held = False
+        try:
+            try:
+                _acquire_lock(lock_fd)
+            except OSError as e:
+                if e.errno != errno.EAGAIN:
+                    raise
+                if time.monotonic() >= held_deadline:
+                    raise FlipLockHeld(f"another process holds flip lock on {link}")
+                held = True
+            else:
+                # os.name here and in release_flip_lock follows the real OS; _IS_WINDOWS is the test seam of the
+                # open retry and of replace_link's remove-first retry.
+                if os.name == "nt" or _names_open_file(lock_fd, lock_path):
+                    return lock_fd
+                _release_lock(lock_fd)
+        except BaseException:
+            os.close(lock_fd)
+            raise
+        os.close(lock_fd)
+        if held:
+            time.sleep(_LOCK_OPEN_POLL_SECONDS)
+            continue
+        if time.monotonic() >= deadline:
+            raise FlipLockHeld(f"another process holds flip lock on {link}")
+
+
+def release_flip_lock(link: Path, lock_fd: int) -> None:
+    """Give back the lock take_flip_lock returned, removing <link>.skf-lock."""
+    lock_path = link.with_name(link.name + ".skf-lock")
+    # Only the flip holding the lock gets here, so it alone removes the
+    # lock file: on POSIX while the lock is still held, so that a flip on
+    # the old file sees the path no longer names it; on Windows, which
+    # removes no open file, after the release and the close. Best effort:
+    # a leftover file is locked and removed by the next flip.
+    if os.name != "nt":
+        try:
+            lock_path.unlink()
+        except OSError:
+            pass
+    _release_lock(lock_fd)
+    os.close(lock_fd)
+    if os.name == "nt":
+        try:
+            lock_path.unlink()
+        except OSError:
+            pass
+
+
 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`). A lock on <link>.skf-lock prevents concurrent flips.
+    for `active -> 1.0.0`). A lock on <link>.skf-lock, which
+    skf-update-active-symlink.py update takes too, 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().
+    skf-skill-inventory's resolve_active_version(). replace_link makes the
+    new link and renames it over <link>; skf-update-active-symlink.py update
+    flips through it too.
+
+    The lock follows ledger_lock in gap-ledger.py (the same identity check
+    and removal order): a fix to one belongs in both. The lock file is
+    removed on release, by the flip that held the lock: a flip refused by a
+    held lock exits 2 and leaves the file to its holder. On POSIX the
+    removal happens while the lock is still held, and a flip checks that
+    the file it locked is still the one at the path: otherwise a flip on
+    the removed file and a newcomer on a new one would both get a lock. A
+    flip whose file is no longer at the path lets it go and opens the path
+    again: it goes on as soon as it locks the file that is at the path, and
+    exits 2 at once when another flip holds that file. Only when the files
+    it locks keep leaving the path until _LOCK_OPEN_WAIT_SECONDS runs out
+    does it exit 2 with the "another process holds flip lock" message a
+    held lock gives. Windows removes no file that is open, so there the file goes after the
+    release, unless another flip has it open. While the removal is under
+    way (the remover's own delete handle is open, or a virus scanner's or
+    the search indexer's), Windows refuses a new open of the file with
+    PermissionError: the flip retries for up to _LOCK_OPEN_WAIT_SECONDS,
+    then exits 2 with the held-lock message, naming the last refusal. A
+    refusal with a folder at the path, or with nothing there on an
+    immediate second try, is a lasting denial and is raised as before.
     """
-    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).
@@ -301,56 +496,14 @@ def cmd_flip_link(link: Path, target: str) -> None:
     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)
+        lock_fd = take_flip_lock(link)
+    except FlipLockHeld as exc:
+        _die(2, str(exc))
+    try:
+        link_kind = replace_link(link, target)
     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
+        release_flip_lock(link, lock_fd)
 
     _ok({"link": str(link), "points_to": target, "kind": link_kind})