oh-my-opencode 5.1.54 → 5.1.56

package/packages/shared-skills/skills/programming/scripts/typescript/mutation-proof.test.ts

@@ -0,0 +1,43 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { MutationError, runMutation } from "./mutation-proof"
+
+let root = ""
+const OWNER = "export const add = (a: number, b: number): number => a + b\n"
+
+describe("#given a production owner and a test that exercises it", () => {
+  beforeAll(() => {
+    root = mkdtempSync(join(process.env.RUN_TMP ?? tmpdir(), "mutation-proof-"))
+    writeFileSync(join(root, "owner.ts"), OWNER)
+    writeFileSync(
+      join(root, "owner.test.ts"),
+      'import { expect, test } from "bun:test"\nimport { add } from "./owner"\ntest("adds", () => { expect(add(1, 2)).toBe(3) })\n',
+    )
+  })
+
+  afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+  test("#when the owner is broken #then the test goes red and the owner is restored byte for byte", async () => {
+    const result = await runMutation({
+      cwd: root,
+      file: "owner.ts",
+      find: "a + b",
+      replace: "a - b",
+      tests: [{ label: "candidate", command: [process.execPath, "test", "owner.test.ts"] }],
+    })
+    expect(result.outcomes.map((outcome) => [outcome.label, outcome.verdict])).toEqual([["candidate", "red"]])
+    expect(result.restoredSha256).toBe(result.originalSha256)
+    expect(readFileSync(join(root, "owner.ts"), "utf8")).toBe(OWNER)
+  })
+
+  test("#when the find text is not unique or empty #then it refuses before touching the file", async () => {
+    for (const [find, kind] of [["a", "FIND_NOT_UNIQUE"], ["", "FIND_EMPTY"]] as const) {
+      const attempt = runMutation({ cwd: root, file: "owner.ts", find, replace: "x", tests: [] })
+      await expect(attempt).rejects.toMatchObject({ kind })
+    }
+    expect(readFileSync(join(root, "owner.ts"), "utf8")).toBe(OWNER)
+  })
+})

package/packages/shared-skills/skills/programming/scripts/typescript/mutation-proof.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+/**
+ * Prove that a test can fail: apply one exact-match edit to a production file, run each test
+ * command against the mutated owner, then restore the original bytes and verify their hash.
+ *
+ * Usage:
+ *   bun run scripts/typescript/mutation-proof.ts --file <path> --find <text> --replace <text> \
+ *     --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]
+ *
+ *   --test takes "label=command words"; the command is split on spaces and quoting is not
+ *   supported, so select a test by a pattern without spaces or run the whole file.
+ *
+ * Verdicts per test: red (exit != 0, the test caught the mutation) or green (exit 0, it did not).
+ * The owner is restored on success, on a thrown error, and on SIGINT/SIGTERM.
+ * Exit codes: 0 ran and restored, 1 the find text is empty or did not match exactly once or the
+ * restore hash differed (the file was still restored), 2 usage, 130/143 interrupted and restored.
+ * Read references/testing/junk-classes.md "Proof rule" for how to read a candidate/keeper pair.
+ */
+
+import { createHash } from "node:crypto"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+import process from "node:process"
+import { parseArgs } from "node:util"
+
+export type MutationTest = { readonly label: string; readonly command: readonly string[] }
+
+export type MutationOutcome = {
+  readonly label: string
+  readonly command: readonly string[]
+  readonly exitCode: number
+  readonly verdict: "red" | "green"
+  readonly outputTail: string
+}
+
+export type MutationResult = {
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly originalSha256: string
+  readonly restoredSha256: string
+  readonly outcomes: readonly MutationOutcome[]
+}
+
+export class MutationError extends Error {
+  constructor(
+    readonly kind: "FIND_EMPTY" | "FIND_NOT_UNIQUE" | "RESTORE_MISMATCH",
+    message: string,
+  ) {
+    super(message)
+    this.name = "MutationError"
+  }
+}
+
+const sha256 = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex")
+
+async function runCaptured(command: readonly string[], cwd: string): Promise<{ readonly exitCode: number; readonly outputTail: string }> {
+  const child = Bun.spawn([...command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  const lines = `${stdout}${stderr}`.trimEnd().split("\n")
+  return { exitCode, outputTail: lines.slice(-30).join("\n") }
+}
+
+export async function runMutation(options: {
+  readonly cwd: string
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly tests: readonly MutationTest[]
+}): Promise<MutationResult> {
+  if (options.find.length === 0) throw new MutationError("FIND_EMPTY", `${options.file}: find text is empty`)
+  const full = resolve(options.cwd, options.file)
+  const original = readFileSync(full)
+  const text = original.toString("utf8")
+  const occurrences = text.split(options.find).length - 1
+  if (occurrences !== 1) {
+    throw new MutationError("FIND_NOT_UNIQUE", `${options.file}: find matched ${occurrences} times (need exactly 1)`)
+  }
+  const originalSha256 = sha256(original)
+  const outcomes: MutationOutcome[] = []
+  const restoreOnSignal = (signal: NodeJS.Signals): void => {
+    writeFileSync(full, original)
+    process.exit(signal === "SIGINT" ? 130 : 143)
+  }
+  process.on("SIGINT", restoreOnSignal)
+  process.on("SIGTERM", restoreOnSignal)
+  try {
+    writeFileSync(full, text.replace(options.find, () => options.replace))
+    for (const test of options.tests) {
+      const run = await runCaptured(test.command, options.cwd)
+      outcomes.push({
+        label: test.label,
+        command: test.command,
+        exitCode: run.exitCode,
+        verdict: run.exitCode === 0 ? "green" : "red",
+        outputTail: run.outputTail,
+      })
+    }
+  } finally {
+    writeFileSync(full, original)
+    process.off("SIGINT", restoreOnSignal)
+    process.off("SIGTERM", restoreOnSignal)
+  }
+  const restoredSha256 = sha256(readFileSync(full))
+  if (restoredSha256 !== originalSha256) {
+    throw new MutationError("RESTORE_MISMATCH", `${options.file} not restored byte for byte`)
+  }
+  return { file: options.file, find: options.find, replace: options.replace, originalSha256, restoredSha256, outcomes }
+}
+
+function parseTest(spec: string): MutationTest | undefined {
+  const separator = spec.indexOf("=")
+  if (separator <= 0) return undefined
+  const label = spec.slice(0, separator)
+  const command = spec
+    .slice(separator + 1)
+    .split(" ")
+    .filter((word) => word.length > 0)
+  return command.length === 0 ? undefined : { label, command }
+}
+
+function usage(): number {
+  console.error(
+    "usage: mutation-proof.ts --file <path> --find <text> --replace <text> --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]",
+  )
+  return 2
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      file: { type: "string" },
+      find: { type: "string" },
+      replace: { type: "string" },
+      test: { type: "string", multiple: true },
+      cwd: { type: "string", default: process.cwd() },
+      json: { type: "boolean", default: false },
+    },
+    strict: true,
+  })
+  if (values.file === undefined || values.find === undefined || values.replace === undefined || values.test === undefined) {
+    return usage()
+  }
+  const tests: MutationTest[] = []
+  for (const spec of values.test) {
+    const parsed = parseTest(spec)
+    if (parsed === undefined) return usage()
+    tests.push(parsed)
+  }
+  try {
+    const result = await runMutation({
+      cwd: values.cwd ?? process.cwd(),
+      file: values.file,
+      find: values.find,
+      replace: values.replace,
+      tests,
+    })
+    if (values.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      for (const outcome of result.outcomes) console.log(`${outcome.label}: ${outcome.verdict} (exit ${outcome.exitCode})`)
+      console.log(`restored ${result.file} (sha256 ${result.restoredSha256.slice(0, 12)})`)
+    }
+    return 0
+  } catch (error) {
+    if (error instanceof MutationError) {
+      console.error(`mutation-proof: ${error.kind}: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+if (import.meta.main) process.exit(await main(process.argv.slice(2)))

package/packages/shared-skills/skills/remove-ai-slops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remove-ai-slops
-description: "Removes AI-generated code smells from branch changes or an explicit file list behind regression tests. Use when the user asks to clean up, deslop, or remove AI-slop patterns from recent changes."
+description: "Removes AI-generated code smells from branch changes or an explicit file list behind regression tests, including junk tests (prose pins, source greps, copied inventories, mock echoes), each proven by its class's rule before a cut. Use when the user asks to clean up, deslop, remove AI-slop patterns, or prune tests from recent changes."
 argument-hint: "[file ...]"
 ---
 
@@ -21,7 +21,7 @@ The core safety invariant: **behavior is locked by green tests before a single l
 
 ## Categories (what counts as slop)
 
-The agent looks for these nine categories. The first three are stylistic, the next three are structural, the next two are about hidden cost, and the last is about behavior coverage.
+The agent looks for these ten categories. The first three are stylistic, the next three are structural, the next two are about hidden cost, the ninth is tests, and the last is size.
 
 ### Stylistic
 1. **Obvious comments** — comments restating code, trivial docstrings, section dividers, commented-out code, vague TODOs/Notes.
@@ -62,10 +62,13 @@ The agent looks for these nine categories. The first three are stylistic, the ne
 
    **Hard rule**: only apply when behavior equivalence is obvious. Do NOT change algorithms with subtle correctness implications. Do NOT micro-optimize hot paths without a benchmark. If in doubt, SKIP.
 
-### Behavior coverage
-9. **Missing tests** — behavior present in changed files that is not locked by any regression test. The fix is not to remove code but to ADD the narrowest test that pins the behavior. EXCEPTION: a PROSE file (prompt, `SKILL.md`, rule, markdown) has no behavioral seam — do NOT add a text/word-count/phrase pin for it; that guards a diff, not behavior. Cover only a machine-consumed value (parsed field, sentinel a runtime greps, a doc JSON sample through its real validator) or leave it to review.
+### Tests
+9. **Tests: missing or junk** — tests are code in scope like any other file, judged by the one table in the `programming` skill, `references/testing/junk-classes.md` (junk classes, retention bar, R/F/C/D marks, proof rule). Two directions:
+   - **Missing**: a behavior in the changed files that no test guards, where the repository keeps tests for that kind of behavior and a regression would otherwise pass unnoticed. ADD the narrowest test that passes the four-question authoring gate (`references/testing/README.md`); name its owner contract. A PROSE file (prompt, `SKILL.md`, rule, markdown) has no behavioral seam: cover only a machine-consumed value (parsed field, sentinel a runtime greps, a doc JSON sample through its real validator) or leave it to review.
+   - **Junk**: mark every in-scope test declaration `R` / `F` / `C` / `D`. A `D` or `C` needs the proof the table names for its class BEFORE the cut: for a behavior class (cannot fail, mock echo, source grep, duplicate contract, layer replay, implementation mirror, fabricated postcondition, input transcript) a mutation of the production owner run against the candidate and its named keeper on the unmodified test tree; for a prose pin the assertion line plus the repo's prose rule; for a change certificate the revert that turns it red; for a seam keeper the `knip`/grep showing no production caller; for a copied inventory the generator or consumer that owns it; for a capability restatement the delivery test that owns the promise (none: `F`, not `D`); for near-duplicate cases the one table that keeps every old assertion (typecheck after). A misnamed test is re-marked by what its assertions check, never cut for its name. A mutation proves `D` only when the keeper goes red and the candidate stays green (cannot fail) or both go red (redundant); a candidate that is the ONLY red is `R`, or `C` into the keeper and re-run. Mutations run in Phase 4b, serially, by the orchestrator, never by a batch worker. A test-only production seam (export, flag, getter, reset hook) whose last test was deleted goes with it.
+   - KEEP: everything under the retention bar (public API, protocol, config, migration, storage, security, platform, shipped-copy equality, Node-compat suites, issue regressions, machine-consumed text). A test that is red on the unchanged base is a product bug to report, never a deletion. Static or slow is never a reason to delete.
 
-### Structural
+### Size
 10. **Oversized modules** — any source file exceeding **250 pure LOC** (non-blank, non-comment lines). This is an architectural defect, not a style preference. Measure: `awk '!/^[[:space:]]*$/ && !/^[[:space:]]*(#|\/\/)/' <file> | wc -l`.
 
    **When found, do NOT just flag it. Execute a full modular refactoring:**
@@ -123,16 +126,17 @@ For each in-scope source file:
 
 1. Identify the public/observable behavior the file exposes (exported functions, HTTP handlers, CLI commands, classes used elsewhere).
 2. Check whether existing tests cover that behavior. Use `git grep` / project test conventions to find related test files.
-3. **If behavior is uncovered or weakly covered, write the narrowest regression test that pins current behavior BEFORE editing the file.** Tests should pin observable outputs, not implementation details. A PROSE file (prompt/`SKILL.md`/rule/markdown) is exempt — its wording is not behavior; skip the test and rely on review, or assert only a machine-consumed value.
-4. Run the test suite (or at minimum the relevant tests). They must be **green** before any cleanup begins.
+3. **If a behavior the cleanup could change is uncovered, write the narrowest test that passes the authoring gate (`programming/references/testing/README.md`) BEFORE editing the file**, and name the behavior it guards. It asserts observable outputs at the real boundary, never the implementation shape the cleanup is about to change, and never a value derived from the code under test. A PROSE file (prompt/`SKILL.md`/rule/markdown) is exempt: its wording is not behavior; skip the test and rely on review, or assert only a machine-consumed value.
+4. Run the test suite (or at minimum the relevant tests). A test that is red on the unchanged base is recorded as a bug (baseline-red list), excluded from every proof, and neither fixed in this pass nor deleted; everything else must be **green** before any cleanup begins.
+5. Run the `programming` skill's static detector over every in-scope test file, the ones written in step 3 included: `bun run <programming skill dir>/scripts/typescript/check-test-junk.ts <test files>` (exit 1 lists `file:line` per junk class it can see: source grep, prose pin, fixed sleep, `.only`/`.skip`, self-comparison, lower-bound cardinality). Its findings are category-9 candidates for the Tests Ledger (marked `R`/`F`/`C`/`D` by the table once its proof runs), never automatic cuts, and a test from step 3 that it flags is rewritten before the pass continues.
 
-If you cannot establish a green baseline (e.g., test runner is broken), STOP and report. Do not proceed with cleanup on unverified ground.
+Only a broken runner stops the pass: if the suite cannot run at all, STOP and report. Do not proceed with cleanup on unverified ground.
 
 ### Phase 3: Cleanup plan — existence first, then smells
 
 The largest, safest deletion is code that should not have existed. **Before categorizing smells, run the deletion ladder on each changed unit:**
 
-- **Delete entirely** — the behavior is not needed (YAGNI, speculative, dead on arrival).
+- **Delete entirely** — the behavior is not needed (YAGNI, speculative, dead on arrival); for a test, its contract is already owned by a keeper or it has none (category 9, with the proof).
 - **Reuse** — an existing helper or pattern in this repo already does it; replace the reimplementation with a call to it.
 - **Platform / stdlib / native / dependency** — the language stdlib, the runtime, or an already-installed dependency already does it (a hand-rolled date picker → `<input type="date">`, a custom query parser → `URLSearchParams`, a bespoke debounce → the util already imported).
 - **Simplify in place** — it must exist; make it smaller.
@@ -159,11 +163,11 @@ File: src/bar.py
 
 **Intentional shortcuts:** if the plan deliberately keeps a bounded simplification (a naive scan fine under N rows, a global lock, an O(n²) path), mark it in-code with a `debt:` comment naming the ceiling and the upgrade trigger (in omo, prefix with `// @allow` so the comment-checker treats it as intentional), and list it under "Remaining Risks / Deferred" in the report. That section is the debt ledger — a simplification with a known ceiling and no marker is indistinguishable from a bug.
 
-Order rule (safest → riskiest): comments → dead code → defensive → duplication → complexity → abstraction/boundary → performance → tests → oversized-modules. This minimizes blast radius of any one change.
+Order rule (safest → riskiest): comments → dead code → defensive → duplication → complexity → abstraction/boundary → performance → tests (`F` rows; `D`/`C` wait for Phase 4b) → oversized-modules. This minimizes blast radius of any one change.
 
 ### Phase 4: Parallel slop removal via `deep-low` agents in batches of 5
 
-Files are processed by `deep-low` category agents with the `$omo:remove-ai-slops` skill loaded, **batched 5 at a time in parallel**. The executable skill name is `remove-ai-slops`. The `deep-low` category gives the agent enough thoroughness to correctly evaluate the 9 categories and respect the KEEP rules without slipping into surface fixes; the 5-wide batch is the sweet spot — more than 5 creates result-merging noise and context contention, fewer wastes parallelism.
+Files are processed by `deep-low` category agents with the `$omo:remove-ai-slops` skill loaded, **batched 5 at a time in parallel**. The executable skill name is `remove-ai-slops`. The `deep-low` category gives the agent enough thoroughness to correctly evaluate the 10 categories and respect the KEEP rules without slipping into surface fixes; the 5-wide batch is the sweet spot — more than 5 creates result-merging noise and context contention, fewer wastes parallelism.
 
 **Batching protocol** (strict):
 
@@ -189,9 +193,9 @@ Remove AI slops from: {file_path}
 
 First run the deletion ladder from Phase 3 on this file (delete entirely / reuse existing repo code / platform-stdlib-native / simplify in place); only code that must exist proceeds to smell removal.
 
-Then evaluate EVERY category defined in this skill's "Categories (what counts as slop)" section, applying that section's KEEP and REFACTOR rules verbatim — the Categories section you have loaded is canonical, do not work from a restated subset.
+Then evaluate EVERY category defined in this skill's "Categories (what counts as slop)" section, applying that section's KEEP and REFACTOR rules verbatim — the Categories section you have loaded is canonical, do not work from a restated subset. For a test file, do NOT cut yet: mark every declaration R/F/C/D against `programming/references/testing/junk-classes.md` and return one ledger row per D/C/F (`| test | mark | keeper or reason | proposed proof |`), where the proposed proof names the class's proof kind and, for a mutation, the owner file, the exact find/replace, and the keeper to run. This worker applies `F` rows in the test file it owns and reports them in the ledger as applied; `D`/`C` rows are returned uncut; it never mutates any file to prove a test - the orchestrator runs the proofs in Phase 4b.
 
-Apply changes in this order (safest → riskiest): comments → dead code → defensive → duplication → complexity → abstraction/boundary → performance → oversized-modules.
+Apply changes in this order (safest → riskiest): comments → dead code → defensive → duplication → complexity → abstraction/boundary → performance → tests (`F` rows; `D`/`C` wait for Phase 4b) → oversized-modules.
 
 Hard constraints:
 - Behavior MUST be preserved. When equivalence is not obvious, SKIP.
@@ -201,11 +205,15 @@ Hard constraints:
 - Diff stays minimal and scoped to slop removal.
 
 Report changes grouped by category. For each change, give before/after, why-slop, why-safe.
-For each skipped issue, give reason.
+For each skipped issue, give reason. For a test file, end with the ledger rows.
 """
 )
 ```
 
+### Phase 4b: Prove the test cuts, serially, then cut
+
+After the last batch finishes and no worker is running, the orchestrator takes the collected ledger rows. For each row whose proof is a mutation, run the `programming` skill's `bun run <programming skill dir>/scripts/typescript/mutation-proof.ts --file <owner> --find <text> --replace <text> --test 'candidate=<argv>' --test 'keeper=<argv>'` (add `--json` for the ledger; each `--test` value is split on spaces with no quoting, so a filter that contains a space needs a wrapper script or a file-path target instead): it applies the find/replace to the production owner, runs the candidate and the keeper on the unmodified test tree, records both verdicts, and restores the owner byte for byte (sha256-checked) before the next row. One mutation at a time, never while another worker or test run is live, and never two on the same file; a mutation touches a file outside the diff only transiently and is never committed. Rows proven per the table become the cuts; a D or C whose proof fails or was not run is an R. Non-mutation proofs (prose pin, change certificate, seam keeper, copied inventory, capability restatement, near-duplicate cases) are checked here too, from the row's evidence.
+
 **Batch failure handling**: a `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived, not that a `deep-low` agent failed. For long passes, require each child to send `WORKING: <file> - <current phase>` and `BLOCKED: <reason>` only when it cannot progress. Treat a running child as alive. Mark a file for retry only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Do NOT block the remaining 4 in that batch; collect successful results and retry the failed file once later. If retry also fails, escalate that file under "Issues Found & Fixed" in the final report.
 
 ### Phase 5: Verify with quality gates + critical review
@@ -260,8 +268,8 @@ Files: [N files]
 
 Behavior Lock:
   - Existing coverage: [N files already covered]
-  - Tests added: [M new regression tests at path/to/test_X.py]
-  - Baseline status: GREEN
+  - Tests added: [M gate-passing tests at path/to/test_X.py, each naming its contract]
+  - Baseline status: GREEN apart from the baseline-red list (recorded as bugs, excluded from proofs, not deleted): [none] OR [list]
 
 Cleanup Plan:
   - path/to/file1.ts: [ladder: 1 delete (native) + simplify-in-place] → [dead code → complexity → performance]
@@ -279,6 +287,12 @@ Per-File Results (each cut shows what replaces it):
     - Obvious comments: 5 removed → nothing
     - Over-defensive: 1 simplified (redundant isinstance on typed param)
 
+Tests Ledger (category 9; one row per test declaration marked D/C/F, proofs run in Phase 4b):
+  | Test | Mark | Keeper / reason | Proof |
+  |---|---|---|---|
+  | `foo.test.ts > reads the source for "export"` | D | source grep; `foo.test.ts > exports parse()` owns the contract | mutation parse.ts `return tokens` -> `return []`: candidate green, keeper red; restored sha-equal |
+  | `skill.test.ts > mentions the gate` | D | prose pin on SKILL.md | assertion line + repo prose rule (no mutation applies) |
+
 Quality Gates:
   - Regression tests: PASS (12 tests, 0 failed)
   - Lint: PASS
@@ -331,7 +345,5 @@ Final Status: CLEAN | ISSUES FIXED | REQUIRES ATTENTION
 ## Quality Assurance
 
 - NEVER remove code that serves a functional purpose.
-- ALWAYS verify changes compile/parse and pass type-check.
-- ALWAYS preserve test coverage; add tests rather than remove them.
-- If uncertain about a change, err on the side of keeping the original code.
-- The default action when in doubt is SKIP, not GUESS.
+- Preserve every proven contract: a test leaves only with its proof receipt (category 9), and a missing contract gets a gate-passing test, never a change certificate.
+- When in doubt, SKIP and keep the original; never GUESS.

package/packages/shared-skills/skills/ulw-research/scripts/source-commands.mjs

@@ -143,7 +143,9 @@ function declareOverKeptRaw(sourcesDir, id, input) {
 	const dir = join(sourcesDir, String(id))
 	if (input.kind !== "converted-only" || !existsSync(join(dir, "raw.bin")) || !existsSync(join(dir, "meta.json"))) return
 	const before = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8"))
-	Object.assign(input, { url: before.url, raw: readFileSync(join(dir, "raw.bin")), kind: before.kind, declared: true })
+	const raw = readFileSync(join(dir, "raw.bin"))
+	if (sha256Of(raw) !== before.sha256) throw new CliError(`snapshot_hash_mismatch: ${id} raw.bin no longer matches its pinned hash`)
+	Object.assign(input, { url: before.url, raw, kind: before.kind, observed_at: before.observed_at, declared: true })
 	delete input.path
 }
 

package/packages/shared-skills/skills/ulw-research/scripts/source-integrity.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, onTestFinished, test } from "bun:test"
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs"
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
-import { sha256Of } from "./cli-support.mjs"
+import { CliError, sha256Of } from "./cli-support.mjs"
 import { addRow, readLedger, writeLedger } from "./fact-ledger.mjs"
 import { run } from "./report-tools.mjs"
+import { writeSnapshot } from "./source-snapshot.mjs"
 
 const BRIEF = readFileSync(join(import.meta.dir, "tests/fixtures/fidelity-brief-locked.md"), "utf8")
 const PAGE = '<html><body><p>The main deck spans <span title="9 m">320</span> m in total.</p><table id="sizes"><tr><th>Name</th><th>Length</th></tr><tr><td>Deck</td><td>320 m</td></tr></table></body></html>'
@@ -127,6 +128,42 @@ describe("converted text is never a raw snapshot", () => {
 	})
 })
 
+describe("replacement over retained raw bytes", () => {
+	for (const [name, tampered, recaptured] of [
+		["healthy retained bytes", false, false],
+		["tampered retained bytes", true, false],
+		["an explicit new capture after retained drift", true, true],
+	] as const) {
+		test(`#given ${name} #when text replaces the extraction #then only validated retained bytes keep their original observation`, async () => {
+			const dir = session()
+			const observedAt = "2026-01-01T00:00:00.000Z"
+			const { dir: source } = writeSnapshot(join(dir, "sources"), "S1", {
+				url: "https://example.invalid/bridge", html: PLAIN, extractor: "model", observed_at: observedAt,
+			})
+			if (tampered) writeFileSync(join(source, "raw.bin"), PLAIN.replace("320", "330"))
+			const before = Object.fromEntries(readdirSync(source).map((name) => [name, readFileSync(join(source, name))]))
+			const raw = recaptured ? "A new capture says 340 m." : PLAIN
+			const text = recaptured ? raw : "The corrected extraction says 320 m."
+			const replaced = snapshot(dir, "S1", "--text", file(dir, "corrected.txt", text), "--replace",
+				...(recaptured ? ["--raw", file(dir, "recaptured.txt", raw)] : []))
+
+			if (tampered && !recaptured) {
+				await expect(replaced).rejects.toBeInstanceOf(CliError)
+				expect(Object.fromEntries(readdirSync(source).map((name) => [name, readFileSync(join(source, name))]))).toEqual(before)
+				return
+			}
+
+			expect((await replaced).exitCode).toBe(0)
+			expect(readFileSync(join(source, "raw.bin"), "utf8")).toBe(raw)
+			expect(readFileSync(join(source, "text.txt"), "utf8")).toBe(text)
+			const meta = JSON.parse(readFileSync(join(source, "meta.json"), "utf8"))
+			expect(meta).toMatchObject({ sha256: sha256Of(raw), text_source: "declared", text_sha256: sha256Of(text) })
+			if (recaptured) expect(meta.observed_at).not.toBe(observedAt)
+			else expect(meta.observed_at).toBe(observedAt)
+		})
+	}
+})
+
 // chmod 000 does not stop the owner reading a file on Windows (no POSIX mode bits), so there the same
 // fail-closed condition is produced the way an unreadable path occurs on win32: raw.bin is replaced by
 // a directory, and reading it fails (EISDIR). Both paths must make verify exit 1 with the cause.