bigpowers 2.90.1 → 2.91.0

package/.windsurf/rules/release-branch.md

@@ -56,13 +56,12 @@ git log main...HEAD --format="%B" | grep -qiE 'co[- ]authored[- ]by' && echo "
 ### 2a. Security gate
 
 - [ ] `specs/security/REVIEW.md` exists and is fresh (matches current branch diff)
-- [ ] No unresolved HIGH findings with confidence ≥ 8 (or all documented in `specs/security/EXCEPTIONS.md` with sign-off rationale)
 
-If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
+### 2b. Audit-code & Traceability gates (HARD GATES — Issue #182)
 
-### 2b. Traceability gate
-
-Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
+- [ ] Run `bash scripts/lib/assert-epic-gate.sh release` (asserts `specs/AUDIT_LATEST.md` passed; blocks release on failure).
+- [ ] No unresolved HIGH security findings with confidence ≥ 8 (or documented in `specs/security/EXCEPTIONS.md`).
+- [ ] Run `gate-trace`. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml`. WAIVED if no matrix available.
 
 > **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails.
 

package/.windsurf/rules/run-planning.md

@@ -62,7 +62,12 @@ if written:
    - `plan-release` — sequence epics by WSJF
    - `slice-tasks` — cut vertical slices
 
-4. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
+4. **Mechanical artifact assertion before status update (HARD GATE — Issue #183):**
+   Before marking any workflow key `status: done`, run:
+   ```bash
+   bash scripts/lib/assert-planning-artifacts.sh <workflow-key>
+   ```
+   If the artifact assertion fails, do NOT advance status. Remediate missing output files before continuing. On success, set `status: done` for that workflow key in `planning-status.yaml`.
 
 5. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
 

package/.windsurf/rules/verify-work.md

@@ -62,7 +62,8 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
 5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only.
 
-5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate.
+5b. **NFR Evidence Gate** (P0 only) — Go/no-go on Performance, Reliability, Operability against `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`. Evidence written to `specs/verifications/NFR-eNNsYY.json`. FAIL blocks gate.
+5c. **Adversarial Defect Mutation Gate (HARD GATE — e86 / ab-20)** — `bash scripts/verify-adversarial.sh`. Boundary fuzzing & parameter injection against modified interfaces. Crashes or failures block PASS gate; evidence in `specs/verifications/ADVERSARIAL_LATEST.yaml`.
 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 

package/.zcode/skills/build-epic/SKILL.md

@@ -66,7 +66,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
 
 1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
-2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+2. **Pass (exit 0):** All checklist sections pass → run `bash scripts/lib/assert-epic-gate.sh advance` to mechanically confirm the audit pass, then advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
 3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
 4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
 5. **Enforce F.I.R.S.T:** After audit-code passes, run `enforce-first --quick` on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.

package/.zcode/skills/commit-message/SKILL.md

@@ -36,6 +36,7 @@ description: "Reviews working-tree changes, then drafts a Conventional Commits t
 
 ## Checklist before finalizing
 
+- [ ] **Audit pass confirmed (HARD GATE — Issue #182):** In active epic flow, `bash scripts/lib/assert-epic-gate.sh commit` passes.
 - [ ] Type matches the **dominant** user-visible outcome (`feat` vs `fix` vs `perf`, etc.).
 - [ ] **Scope** is a short noun in parentheses if it helps (e.g. `fix(api): …`).
 - [ ] Breaking changes are explicit (`!` and/or `BREAKING CHANGE:` in the body/footer).

package/.zcode/skills/release-branch/SKILL.md

@@ -56,13 +56,12 @@ git log main...HEAD --format="%B" | grep -qiE 'co[- ]authored[- ]by' && echo "
 ### 2a. Security gate
 
 - [ ] `specs/security/REVIEW.md` exists and is fresh (matches current branch diff)
-- [ ] No unresolved HIGH findings with confidence ≥ 8 (or all documented in `specs/security/EXCEPTIONS.md` with sign-off rationale)
 
-If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
+### 2b. Audit-code & Traceability gates (HARD GATES — Issue #182)
 
-### 2b. Traceability gate
-
-Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
+- [ ] Run `bash scripts/lib/assert-epic-gate.sh release` (asserts `specs/AUDIT_LATEST.md` passed; blocks release on failure).
+- [ ] No unresolved HIGH security findings with confidence ≥ 8 (or documented in `specs/security/EXCEPTIONS.md`).
+- [ ] Run `gate-trace`. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml`. WAIVED if no matrix available.
 
 > **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails.
 

package/.zcode/skills/run-planning/SKILL.md

@@ -62,7 +62,12 @@ if written:
    - `plan-release` — sequence epics by WSJF
    - `slice-tasks` — cut vertical slices
 
-4. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
+4. **Mechanical artifact assertion before status update (HARD GATE — Issue #183):**
+   Before marking any workflow key `status: done`, run:
+   ```bash
+   bash scripts/lib/assert-planning-artifacts.sh <workflow-key>
+   ```
+   If the artifact assertion fails, do NOT advance status. Remediate missing output files before continuing. On success, set `status: done` for that workflow key in `planning-status.yaml`.
 
 5. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
 

package/.zcode/skills/verify-work/SKILL.md

@@ -62,7 +62,8 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
 5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only.
 
-5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate.
+5b. **NFR Evidence Gate** (P0 only) — Go/no-go on Performance, Reliability, Operability against `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`. Evidence written to `specs/verifications/NFR-eNNsYY.json`. FAIL blocks gate.
+5c. **Adversarial Defect Mutation Gate (HARD GATE — e86 / ab-20)** — `bash scripts/verify-adversarial.sh`. Boundary fuzzing & parameter injection against modified interfaces. Crashes or failures block PASS gate; evidence in `specs/verifications/ADVERSARIAL_LATEST.yaml`.
 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.91.0](https://github.com/danielvm-git/bigpowers/compare/v2.90.2...v2.91.0) (2026-11-03)
+
+
+### Features
+
+* **hooks:** enforce mechanical gates for red-commit, artifacts, and adversarial mutation (e86) ([#191](https://github.com/danielvm-git/bigpowers/issues/191)) ([7a1b090](https://github.com/danielvm-git/bigpowers/commit/7a1b0907aa20962ee71e825c4996aa80c213be3f))
+
+## [2.90.2](https://github.com/danielvm-git/bigpowers/compare/v2.90.1...v2.90.2) (2026-11-03)
+
+
+### Bug Fixes
+
+* **scripts:** write spec state atomically instead of in place ([#192](https://github.com/danielvm-git/bigpowers/issues/192)) ([6198138](https://github.com/danielvm-git/bigpowers/commit/61981388c6ab80e493ae7582749730b41c89fa24)), closes [#181](https://github.com/danielvm-git/bigpowers/issues/181)
+
 ## [2.90.1](https://github.com/danielvm-git/bigpowers/compare/v2.90.0...v2.90.1) (2026-11-03)
 
 

package/hooks/pre-tool-use.sh

@@ -42,8 +42,30 @@ deny() {
 # Read input from stdin
 INPUT=$(cat)
 
-# Extract command using jq (standard in bigpowers)
+# Extract command and file path using jq (standard in bigpowers)
 COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .tool_input.file_path // .path // .tool_input.path // .target_file // .tool_input.target_file // empty')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool // .name // .tool_name // empty')
+
+# 0. Check file editing rules
+if [ -n "$FILE_PATH" ]; then
+  # e86s01: Generated paths are blocked at edit time
+  if [[ "$FILE_PATH" =~ ^\.cursor/rules/ ]] || [[ "$FILE_PATH" =~ ^\.gemini/extensions/ ]] || [[ "$FILE_PATH" =~ ^\.windsurf/ ]]; then
+    deny "BLOCKED: Generated file '$FILE_PATH' cannot be edited directly. Edit the source SKILL.md instead and run bash scripts/sync-skills.sh."
+  fi
+
+  # e86s02: Tests are locked during fix_bug flow after RED commit
+  if [[ "$FILE_PATH" =~ (^|/)test/ ]] || [[ "$FILE_PATH" =~ (^|/)tests/ ]] || [[ "$FILE_PATH" =~ \.test\.[^/]+$ ]] || [[ "$FILE_PATH" =~ _test\.[^/]+$ ]] || [[ "$FILE_PATH" =~ (^|/)test_[^/]+$ ]]; then
+    if [ -f specs/state.yaml ] && grep -qE "active_flow:[[:space:]]*fix_bug" specs/state.yaml 2>/dev/null; then
+      if git rev-parse --git-dir >/dev/null 2>&1; then
+        recent_log=$(git log -n 5 --format=%s 2>/dev/null || true)
+        if echo "$recent_log" | grep -qE '^test(\(.+\))?:'; then
+          deny "BLOCKED: Test files ($FILE_PATH) are locked during fix_bug after the RED commit. Write the fix in production code (src/), not in tests."
+        fi
+      fi
+    fi
+  fi
+fi
 
 if [ -z "$COMMAND" ]; then
   [ "$MODE" = "gemini" ] && echo '{"decision":"allow"}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.90.1",
+  "version": "2.91.0",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {
@@ -68,6 +68,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@ctxo/lang-typescript": "^0.11.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",

package/scripts/convert-legado.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # convert-legado.sh — RELEASE-PLAN.md + SCOPE.md → YAML layout (one-time migration helper)
+# bp-manual-utility: legacy MD spec converter (pre-e44 migration)
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 SPECS="$REPO_ROOT/specs"

package/scripts/lib/ab_report.py

@@ -7,11 +7,15 @@ from __future__ import annotations
 import json
 import random
 import subprocess
+import sys
 from datetime import date
 from pathlib import Path
 
 import yaml
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
+
 REPO_ROOT = Path(__file__).resolve().parents[2]
 BOOTSTRAP_RESAMPLES = 1000
 BOOTSTRAP_SEED = 58
@@ -96,10 +100,13 @@ def write_reports(out: Path, meta: dict, result: dict, records: list[dict]) -> P
     out.mkdir(parents=True, exist_ok=True)
     today = date.today().isoformat()
     report = out / f"AB-{today}.yaml"
-    report.write_text(yaml.safe_dump({**meta, **result}, sort_keys=False))
-    with (out / f"ab-runs-{today}.jsonl").open("w") as f:
-        for rec in records:
-            f.write(json.dumps({**rec, "bigpowers_sha": meta["bigpowers_sha"]}) + "\n")
+    # Atomic (#181): the dashboard reads these while a run is still appending.
+    atomic_write_text(report, yaml.safe_dump({**meta, **result}, sort_keys=False))
+    records_path = out / f"ab-runs-{today}.jsonl"
+    atomic_write_text(
+        records_path,
+        "".join(json.dumps({**rec, "bigpowers_sha": meta["bigpowers_sha"]}) + "\n" for rec in records),
+    )
     return report
 
 

package/scripts/lib/assert-epic-gate.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# story: e86 / GH #182
+# Mechanical audit-code pass gate before commit / release.
+set -euo pipefail
+
+STAGE="${1:-commit}"
+
+AUDIT_PASSED=false
+
+# Check specs/AUDIT_LATEST.md
+if [[ -f specs/AUDIT_LATEST.md ]]; then
+  if grep -qiE "VERDICT:[[:space:]]*PASS|RESULT:[[:space:]]*PASS" specs/AUDIT_LATEST.md; then
+    AUDIT_PASSED=true
+  fi
+fi
+
+# Check specs/execution-status.yaml
+if [[ "$AUDIT_PASSED" == "false" ]] && [[ -f specs/execution-status.yaml ]]; then
+  if grep -qE "audit_passed:[[:space:]]*true" specs/execution-status.yaml 2>/dev/null; then
+    AUDIT_PASSED=true
+  fi
+fi
+
+if [[ "$AUDIT_PASSED" == "false" ]]; then
+  echo "ERROR [$STAGE]: audit-code check is missing or did not pass (Issue #182)." >&2
+  echo "Remediation: Run audit-code and ensure all checks pass before advancing to $STAGE." >&2
+  echo "If audit fails, loop back to develop-tdd to address findings." >&2
+  exit 1
+fi
+
+echo "PASS [$STAGE]: audit-code verified."
+exit 0

package/scripts/lib/assert-planning-artifacts.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# story: e86 / GH #183
+# Mechanical artifact existence assertion for run-planning workflow steps.
+set -euo pipefail
+
+STEP="${1:-}"
+
+if [[ -z "$STEP" ]]; then
+  echo "Usage: bash scripts/lib/assert-planning-artifacts.sh <step_name>" >&2
+  exit 1
+fi
+
+case "$STEP" in
+  survey-context)
+    if [[ ! -f specs/tech-architecture/tech-stack.md ]] && [[ ! -f specs/state.yaml ]]; then
+      echo "ERROR [survey-context]: Neither specs/tech-architecture/tech-stack.md nor specs/state.yaml exists." >&2
+      exit 1
+    fi
+    ;;
+
+  scope-work)
+    if [[ ! -f specs/product/SCOPE_LATEST.yaml ]] || [[ ! -s specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [scope-work]: specs/product/SCOPE_LATEST.yaml is missing or empty." >&2
+      exit 1
+    fi
+    ;;
+
+  research-first)
+    # Research can record in specs/product/PRIOR_ART.md or directly in specs/
+    if [[ ! -f specs/product/PRIOR_ART.md ]] && [[ ! -f specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [research-first]: Neither specs/product/PRIOR_ART.md nor specs/product/SCOPE_LATEST.yaml found." >&2
+      exit 1
+    fi
+    ;;
+
+  elaborate-spec)
+    if [[ ! -f specs/planning-context.yaml ]] && [[ ! -f specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [elaborate-spec]: specs/planning-context.yaml is missing." >&2
+      exit 1
+    fi
+    ;;
+
+  plan-release)
+    if [[ ! -f specs/release-plan.yaml ]] || [[ ! -s specs/release-plan.yaml ]]; then
+      echo "ERROR [plan-release]: specs/release-plan.yaml is missing or empty." >&2
+      exit 1
+    fi
+    ;;
+
+  slice-tasks)
+    # Assert at least one task file exists in specs/epics/
+    if ! find specs/epics -name "*-tasks.yaml" 2>/dev/null | grep -q .; then
+      echo "ERROR [slice-tasks]: No tasks files (*-tasks.yaml) found in specs/epics/." >&2
+      exit 1
+    fi
+    ;;
+
+  *)
+    echo "WARNING: Unknown step '$STEP' — skipping artifact assertion" >&2
+    exit 0
+    ;;
+esac
+
+echo "PASS: Planning artifacts asserted for step '$STEP'."
+exit 0

package/scripts/lib/atomic_write.py

@@ -0,0 +1,71 @@
+"""Atomic file replacement for spec state (BUG-2026-11-03-atomic-yaml-writes, #181).
+
+`Path.write_text()` truncates the destination first and then streams the new
+bytes into it. Any concurrent reader — the dashboard snapshot loop, a subagent,
+a background gate — can observe the file after the truncate and before the last
+chunk lands, and fails with `yaml.scanner.ScannerError` on a file that a moment
+later is perfectly valid. Interrupting the agent mid-write leaves the file
+truncated for good.
+
+`atomic_write_text()` never exposes a partial file: the bytes go to a temporary
+file in the same directory, are flushed and fsynced, and only then replace the
+destination with `os.replace()` (a single atomic rename on POSIX). Readers see
+the old content or the new content, never a mix.
+
+Same-directory temp file is required: `os.replace` is atomic only within one
+filesystem, and `tempfile.mkstemp(dir=...)` guarantees that.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_bytes(path: str | Path, data: bytes, mode: int | None = None) -> None:
+    """Replace `path` with `data` atomically. Preserves the target's mode."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if mode is None and target.exists():
+        mode = stat.S_IMODE(target.stat().st_mode)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=f".{target.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if mode is not None:
+            os.chmod(tmp_name, mode)
+        os.replace(tmp_name, target)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+    _fsync_dir(target.parent)
+
+
+def atomic_write_text(path: str | Path, text: str, encoding: str = "utf-8", mode: int | None = None) -> None:
+    """Atomic replacement for `Path.write_text()`."""
+    atomic_write_bytes(path, text.encode(encoding), mode=mode)
+
+
+def _fsync_dir(directory: Path) -> None:
+    """Persist the rename itself. Best-effort: not every platform allows it."""
+    flags = getattr(os, "O_DIRECTORY", 0)
+    try:
+        dir_fd = os.open(str(directory), os.O_RDONLY | flags)
+    except OSError:
+        return
+    try:
+        os.fsync(dir_fd)
+    except OSError:
+        pass
+    finally:
+        os.close(dir_fd)

package/scripts/lib/blind-spot-checks.py

@@ -6,6 +6,8 @@
 import json, os, re, sys
 from pathlib import Path
 from datetime import datetime, timezone
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
 
 ROOT = Path(sys.argv[1])
 BLIND_SPOTS_JSON = Path(sys.argv[2])
@@ -202,7 +204,7 @@ blind_spots = {
 }
 
 BLIND_SPOTS_JSON.parent.mkdir(parents=True, exist_ok=True)
-BLIND_SPOTS_JSON.write_text(json.dumps(blind_spots, indent=2), encoding="utf-8")
+atomic_write_text(BLIND_SPOTS_JSON, json.dumps(blind_spots, indent=2), encoding="utf-8")
 
 print(f"check-blind-spots.sh: {len(findings)} findings ({high_count} HIGH, {medium_count} MEDIUM, {low_count} LOW)")
 for f in findings:

package/scripts/lib/blind-spots.py

@@ -15,6 +15,8 @@ from __future__ import annotations
 import json, os, re, sys
 from pathlib import Path
 from datetime import datetime, timezone
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
 
 ROOT = Path(sys.argv[1])
 BLIND_SPOTS_JSON = Path(sys.argv[2])
@@ -260,7 +262,7 @@ blind_spots = {
 }
 
 BLIND_SPOTS_JSON.parent.mkdir(parents=True, exist_ok=True)
-BLIND_SPOTS_JSON.write_text(json.dumps(blind_spots, indent=2), encoding="utf-8")
+atomic_write_text(BLIND_SPOTS_JSON, json.dumps(blind_spots, indent=2), encoding="utf-8")
 
 print(f"check-blind-spots.sh: {len(findings)} findings ({high_count} HIGH, {medium_count} MEDIUM, {low_count} LOW)")
 for f in findings:

package/scripts/lib/golden-suite-gates.sh

@@ -81,6 +81,8 @@ GOLDEN_GATES=(
   "golden-gate-runner:bash scripts/test-golden-gate-runner.sh:false"
   # Pipefail SIGPIPE races: fix shapes hold, git output never feeds grep -q/head.
   "pipefail-pipe-race:bash scripts/test-pipefail-pipe-race.sh:false"
+  # Atomic state writes: no reader ever sees a truncated YAML/JSON file (#181).
+  "atomic-writes:bash scripts/test-atomic-writes.sh:false"
   # One pipeline, release needs: every gate, pinned runner and actions.
   "ci-pipeline-contract-selftest:bash scripts/test-ci-pipeline-contract.sh --self-test:false"
   "ci-pipeline-contract:bash scripts/test-ci-pipeline-contract.sh:false"

package/scripts/lib/run-benchmark.py

@@ -12,6 +12,9 @@ from pathlib import Path
 
 import yaml
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
+
 REPO_ROOT = Path(__file__).resolve().parents[2]
 BENCH_DIR = REPO_ROOT / "specs" / "benchmarks"
 REPORTS_DIR = BENCH_DIR / "reports"
@@ -169,8 +172,7 @@ def run_benchmark(skill: str, baseline: bool = False) -> dict:
     REPORTS_DIR.mkdir(parents=True, exist_ok=True)
     yaml_path = REPORTS_DIR / f"BENCHMARK-{skill}-{today}.yaml"
     json_path = REPORTS_DIR / f"benchmark-{skill}.json"
-    with yaml_path.open("w") as f:
-        yaml.dump(
+    yaml_text = yaml.dump(
             {
                 "skill": skill,
                 "run_date": today,
@@ -189,9 +191,9 @@ def run_benchmark(skill: str, baseline: bool = False) -> dict:
             },
             f,
             default_flow_style=False,
-        )
-    with json_path.open("w") as f:
-        json.dump(report, f, separators=(",", ":"))
+    )
+    atomic_write_text(yaml_path, yaml_text)
+    atomic_write_text(json_path, json.dumps(report, separators=(",", ":")))
     print(f"Wrote {yaml_path}")
     print(f"Wrote {json_path}")
     if baseline:

package/scripts/lib/srp_engine_okf.py

@@ -1,7 +1,12 @@
 """OKF concept-page rendering for srp-engine (sync-skills.sh --okf)."""
 # story: e39s04
 # story: BUG-2026-10-30-compliance-akita-masked
+# story: BUG-2026-11-03-atomic-yaml-writes
 import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from atomic_write import atomic_write_text  # noqa: E402
 
 
 def render_okf_concept(skill_data, okf_wiki_skills):
@@ -61,5 +66,4 @@ def render_okf_concept(skill_data, okf_wiki_skills):
         f"> Auto-generated by sync-skills.sh --okf (e39s04) from skills/{name}/SKILL.md"
     ])
     
-    with open(okf_file, 'w', encoding='utf-8') as f:
-        f.write('\n'.join(lines) + '\n')
+    atomic_write_text(okf_file, '\n'.join(lines) + '\n')

package/scripts/lib/trace-stories.py

@@ -15,6 +15,8 @@ import json, os, re, subprocess, sys
 from pathlib import Path
 from datetime import datetime, timezone
 import yaml
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
 
 ROOT = Path(sys.argv[1])
 MATRIX_JSON = Path(sys.argv[2])
@@ -189,7 +191,7 @@ matrix = {
     }
 }
 MATRIX_JSON.parent.mkdir(parents=True, exist_ok=True)
-MATRIX_JSON.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
+atomic_write_text(MATRIX_JSON, json.dumps(matrix, indent=2), encoding="utf-8")
 
 # --- 6. Emit TRACEABILITY_LATEST.md
 lines = ["# Traceability Matrix", "",
@@ -224,7 +226,7 @@ if stale_tags:
     for st in stale_tags: lines.append(f"- `{st}`")
     lines.append("")
 TRACE_MD.parent.mkdir(parents=True, exist_ok=True)
-TRACE_MD.write_text("\n".join(lines), encoding="utf-8")
+atomic_write_text(TRACE_MD, "\n".join(lines))
 
 # --- 7. Emit OKF bundle (specs/codebase-wiki/)
 OKF_DIR.mkdir(parents=True, exist_ok=True)
@@ -240,7 +242,7 @@ for s in matrix_stories:
     mc = "high" if "high" in confs else ("medium" if "medium" in confs else ("low" if confs else "none"))
     idx_lines.append(f"| [{s['id']}](./{s['id']}.md) | {s['title'][:60]} | {mc} | {s['link_count']} |")
 idx_lines.append("")
-(OKF_DIR / "index.md").write_text("\n".join(idx_lines), encoding="utf-8")
+atomic_write_text(OKF_DIR / "index.md", "\n".join(idx_lines))
 for s in matrix_stories:
     concept = ["---", f"type: Story", f"id: {s['id']}", f"epic: {s['epic_id']}",
         f"bcps: {s['bcp']}", f"wsjf: {s['wsjf']}",
@@ -263,7 +265,7 @@ for s in matrix_stories:
     else:
         concept.append("*No code links found — this is a dark story.*")
     concept.append("")
-    (OKF_DIR / f"{s['id']}.md").write_text("\n".join(concept), encoding="utf-8")
+    atomic_write_text(OKF_DIR / f"{s['id']}.md", "\n".join(concept))
 
 # --- 8. Strict mode
 if STRICT:

package/scripts/lib/trace_renderer.py

@@ -3,6 +3,8 @@
 import json
 from pathlib import Path
 from datetime import datetime, timezone
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from atomic_write import atomic_write_text  # noqa: E402
 
 def emit_matrix_json(matrix_json_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list) -> dict:
     matrix = {
@@ -26,7 +28,7 @@ def emit_matrix_json(matrix_json_path: Path, stories: dict, tagged_sids: set, da
         }
     }
     matrix_json_path.parent.mkdir(parents=True, exist_ok=True)
-    matrix_json_path.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
+    atomic_write_text(matrix_json_path, json.dumps(matrix, indent=2), encoding="utf-8")
     return matrix
 
 def emit_trace_md(trace_md_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list, matrix: dict, dev_status: dict) -> None:
@@ -80,7 +82,7 @@ def emit_trace_md(trace_md_path: Path, stories: dict, tagged_sids: set, dark_sto
         lines.append("")
     
     trace_md_path.parent.mkdir(parents=True, exist_ok=True)
-    trace_md_path.write_text("\n".join(lines), encoding="utf-8")
+    atomic_write_text(trace_md_path, "\n".join(lines))
 
 def emit_okf_bundle(okf_dir: Path, stories: dict, matrix_stories: list) -> None:
     okf_dir.mkdir(parents=True, exist_ok=True)
@@ -104,7 +106,7 @@ def emit_okf_bundle(okf_dir: Path, stories: dict, matrix_stories: list) -> None:
         max_conf = "high" if "high" in confs else ("medium" if "medium" in confs else ("low" if confs else "none"))
         idx_lines.append(f"| [{s['id']}](./{s['id']}.md) | {s['title'][:60]} | {max_conf} | {s['link_count']} |")
     idx_lines.append("")
-    (okf_dir / "index.md").write_text("\n".join(idx_lines), encoding="utf-8")
+    atomic_write_text(okf_dir / "index.md", "\n".join(idx_lines))
     
     # Generate one concept per story
     for s in matrix_stories:
@@ -144,4 +146,4 @@ def emit_okf_bundle(okf_dir: Path, stories: dict, matrix_stories: list) -> None:
         else:
             concept.append("*No code links found — this is a dark story.*")
         concept.append("")
-        (okf_dir / f"{s['id']}.md").write_text("\n".join(concept), encoding="utf-8")
+        atomic_write_text(okf_dir / f"{s['id']}.md", "\n".join(concept))

package/scripts/okf-add-references.py

@@ -8,6 +8,9 @@ import re
 import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+from atomic_write import atomic_write_text  # noqa: E402
+
 
 def main() -> int:
     graph_json = Path(sys.argv[1])
@@ -69,7 +72,7 @@ def main() -> int:
                 content,
             )
         count_updated += 1
-        path.write_text(content, encoding="utf-8")
+        atomic_write_text(path, content)
 
     print(f"  concepts with cross-references: {count_updated}", file=sys.stderr)
     return 0

package/scripts/sync-bugs-registry.sh

@@ -12,6 +12,9 @@ import re
 import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(sys.argv[2]) / "scripts" / "lib"))
+from atomic_write import atomic_write_text
+
 bugs_dir = Path(sys.argv[1])
 repo_root = Path(sys.argv[2])
 
@@ -61,7 +64,7 @@ for e in entries:
             val = e[opt].replace('"', "'")
             lines.append(f'    {opt}: "{val}"')
 lines.append("")
-out.write_text("\n".join(lines), encoding="utf-8")
+atomic_write_text(out, "\n".join(lines))
 print(f"sync-bugs-registry: {len(entries)} bugs -> {out}")
 
 # ---- Phase 2: Emit OKF concept bundles (e45s03) ----
@@ -96,7 +99,7 @@ references:
 
 See `specs/bugs/{bug_id}.md` for full investigation and fix details.
 """
-    bundle_path.write_text(bundle, encoding="utf-8")
+    atomic_write_text(bundle_path, bundle)
     okf_count += 1
 
 print(f"sync-bugs-registry: {okf_count} OKF concept bundles -> {bugs_dir}/")