zrwangems/dsh-zrwang-plugin / ars/skills/academic-pipeline
academic-pipeline
Flagged学术研究总编排:研究→写作→诚信检查→评审→返修→复审→终检→定稿的十阶段流水线,每阶段停在用户确认点,含材料护照与 7 类 AI 研究失败模式检查。Triggers: academic pipeline, research to paper, full paper workflow, end-to-end paper | 完整论文流程, 从研究到论文, 端到端写论文, 论文流水线。
scripts/ars_apply_revision_patch.py
View on GitHub#!/usr/bin/env python3
"""Apply a revision patch to an anchored draft — two-phase, fail-closed.
#89 Item 7 Slice A. Normative source:
`docs/design/2026-06-10-390-diff-patch-revision-mode-spec.md` §3.3
(deterministic apply), §3.2 (patch document constraints).
**Phase 1 — validate everything, touch nothing.** Schema-validate the
patch; verify `base_draft_hash` against the base file's raw bytes; parse
the base with the shared parser; check every op (target exists,
`old_hash` matches the current normalized block text, each block ID in
at most one op in any role — the `DOC-BODY-START` sentinel included,
no `<!--block:` in `new_text`, `new_text` segments cleanly). ANY failure
rejects the whole patch with a structured report and no output artifact:
a stale-base or hallucinated-target patch cannot half-land.
**Phase 2 — apply all, by byte-span splicing.** The original byte stream
is spliced at the validated spans; every byte outside them — untouched
blocks' marker lines and inter-block separator bytes included — is
copied verbatim from the base. Hash normalization is read-side only and
never appears in the output. Fresh IDs are assigned by this script alone
(`max(existing) + 1`, base-document encounter order). Output is written
to a temp file and atomically renamed; a post-write self-check re-parses
the result and asserts marker uniqueness + grammar.
**Structural-shape triggers** (§3.3, deterministic): heading-block ops,
net section-count change, and `blocks_touched / blocks_total` strictly
above `--touched-ratio-threshold` (default 0.6 — the #424 Slice B ship
decision; pass 1.0 to disable, since the ratio never exceeds 1.0 and the
comparator is strict per the spec's "above a threshold"). The ratio is
computed and recorded in every report regardless. Any raised flag
refuses the apply unless `--acknowledge-structural` is set (the §3.6
escalation checkpoint owns that decision; this script only enforces it).
`blocks_touched` counts replace/delete targets; an `insert_after`
anchor's content is not touched, so it does not count. Heading-anchor
exemption (#424): an `insert_after` whose anchor is a heading raises NO
heading flag when its segmented `new_text` contains no heading blocks —
inserting body text after a section heading leaves every heading byte
untouched; heading-bearing `new_text` still flags via its segments.
**Pure-move check** (§3.3): an inserted segment whose normalized-text
hash equals a same-patch deleted block's `old_hash` is recorded as a
machine-verified `pure_move` pair. No similarity heuristics for
moved-and-reworded text — that lands as ordinary touched-block exposure.
Exit codes: 0 = applied; 2 = Phase 1 rejection (structured report on
stdout); 3 = structural-shape refusal (unacknowledged); 4 = post-write
self-check failure (bug, not user error).
Current-write usage (patch 1.1 only):
python scripts/ars_apply_revision_patch.py base.md patch.json \
--block-manifest base.md.block-manifest.json \
--output base.rev2.md [--report-out R.json] \
[--roadmap roadmap.json --author-adjudication author.json \
--claim-surface-manifest claims.json --artifact-root BUNDLE_ROOT] \
[--integrity-issue-list issue-list.json] \
[--acknowledge-structural] [--touched-ratio-threshold 0.6]
"""
from __future__ import annotations
import argparse
import hashlib
import json
import sys
from pathlib import Path
import jsonschema
if __package__ in (None, ""): # pragma: no cover - direct CLI invocation
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from scripts._block_parser import (
BLOCK_ID_FORMAT,
MARKER_PREFIX,
Block,
BlockParseError,
ParsedDocument,
atomic_write_bytes,
base_draft_hash,
parse_document,
segment_fragment,
)
from scripts.revision_roadmap import (
ArtifactStore,
ContractError,
_read_path_once,
load_json_path,
validate_block_manifest,
validate_claim_surface_manifest,
validate_integrity_patch_authorization,
validate_review_patch_authorization,
validate_roadmap,
)
REPO_ROOT = Path(__file__).resolve().parent.parent
PATCH_SCHEMA_PATH = REPO_ROOT / "shared" / "contracts" / "patch" / "revision_patch.schema.json"
DOC_BODY_START = "DOC-BODY-START"
# 1.3 is the first current-write report under #670. It adds the replayed
# authorization_witness and explicit per-op claim/collateral declarations.
# Historical patch/report replay is isolated in scripts/legacy; this CLI does
# not write an authorization PASS for patch 1.0.
REPORT_FORMAT_VERSION = "1.3"
# #424 Slice B ship decision (spec §3.3 required it; recorded in the spec's
# amendment log). Strict `>` comparator per the spec's "above a threshold":
# 1.0 disables the trigger because touched/total never exceeds 1.0.
DEFAULT_TOUCHED_RATIO_THRESHOLD = 0.6
def _ratio_threshold(raw: str) -> float:
"""argparse type for --touched-ratio-threshold: a finite value in
[0.0, 1.0]. Rejects NaN (which makes `touched_ratio > NaN` silently
False, disabling the trigger off the documented 1.0 path), inf, and
out-of-range values."""
try:
value = float(raw)
except ValueError:
raise argparse.ArgumentTypeError(f"{raw!r} is not a number")
import math
if not math.isfinite(value) or not (0.0 <= value <= 1.0):
raise argparse.ArgumentTypeError(
f"{raw!r} must be a finite ratio in [0.0, 1.0] "
"(1.0 disables the trigger; NaN/inf/negative are rejected)"
)
return value
class ApplyRejection(Exception):
"""Phase 1 rejection carrying the structured failure list."""
def __init__(self, failures: list[dict]):
self.failures = failures
super().__init__(f"{len(failures)} validation failure(s)")
class StructuralRefusal(Exception):
"""Unacknowledged structural-shape flags (§3.3 / §3.6)."""
def __init__(self, flags: dict):
self.flags = flags
super().__init__("structural-shape flags raised without acknowledgement")
def _fail(failures: list[dict], op_index: int | None, kind: str, message: str, **extra) -> None:
entry = {"op_index": op_index, "kind": kind, "message": message}
entry.update(extra)
failures.append(entry)
def _load_patch_schema() -> dict:
return json.loads(PATCH_SCHEMA_PATH.read_text(encoding="utf-8"))
def validate_patch(
patch: dict,
base_raw: bytes,
base: ParsedDocument,
*,
touched_ratio_threshold: float | None,
) -> dict:
"""Phase 1. Returns the analysis dict Phase 2 consumes, or raises."""
failures: list[dict] = []
validator = jsonschema.Draft202012Validator(_load_patch_schema())
schema_errors = sorted(validator.iter_errors(patch), key=lambda e: list(e.absolute_path))
for err in schema_errors:
path = "/".join(str(p) for p in err.absolute_path) or "(root)"
_fail(failures, None, "schema_invalid", f"{path}: {err.message}")
if schema_errors:
raise ApplyRejection(failures)
actual_base_hash = base_draft_hash(base_raw)
if patch["base_draft_hash"] != actual_base_hash:
_fail(
failures,
None,
"base_hash_mismatch",
"patch was generated against a different base (stale-base rejection)",
expected=patch["base_draft_hash"],
actual=actual_base_hash,
)
by_id = base.block_by_id()
seen_targets: dict[str, int] = {}
analyses: list[dict] = []
for idx, op in enumerate(patch["ops"]):
block_id = op["block_id"]
analysis: dict = {"op": op, "op_index": idx, "segments": None, "target": None}
if block_id in seen_targets:
_fail(
failures,
idx,
"duplicate_target",
f"block {block_id} already named by op {seen_targets[block_id]} "
"(each block ID appears in at most one op, in any role)",
)
else:
seen_targets[block_id] = idx
if block_id == DOC_BODY_START:
pass # position sentinel, no anchor block to precondition on
elif block_id not in by_id:
_fail(failures, idx, "unknown_block_id", f"block {block_id} does not exist in the base")
else:
target = by_id[block_id]
analysis["target"] = target
if op["old_hash"] != target.norm_hash:
_fail(
failures,
idx,
"hash_mismatch",
f"block {block_id} content is not what the patch preconditions on",
expected=op["old_hash"],
actual=target.norm_hash,
)
new_text = op.get("new_text")
if new_text is not None:
if MARKER_PREFIX in new_text:
_fail(
failures,
idx,
"marker_in_new_text",
"new_text must not contain <!--block: markers "
"(ID assignment is the apply script's exclusive authority)",
)
else:
try:
analysis["segments"] = segment_fragment(new_text)
except BlockParseError as exc:
_fail(failures, idx, f"new_text_invalid:{exc.kind}", str(exc))
analyses.append(analysis)
if failures:
raise ApplyRejection(failures)
# Structural-shape flags (§3.3) — deterministic, computed on the
# validated patch only.
heading_op_indexes: list[int] = []
headings_delta = 0
touched = 0
for analysis in analyses:
op = analysis["op"]
target: Block | None = analysis["target"]
segments: list[Block] | None = analysis["segments"]
seg_headings = sum(1 for s in (segments or []) if s.kind == "heading")
target_is_heading = target is not None and target.kind == "heading"
# §3.3 heading rule with the #424 heading-anchor exemption: an op
# that REWRITES or DELETES a heading block, or whose segmented
# new_text CONTAINS a heading, flags. An insert_after merely
# ANCHORED on a heading does not — the heading's bytes are
# untouched, and "insert body text after a section heading" is the
# most common legitimate insertion; flagging it daily would erode
# the checkpoint (alarm fatigue). Heading-bearing new_text still
# flags via seg_headings whatever the anchor is.
if op["op"] == "replace_block":
touched += 1
headings_delta += seg_headings - (1 if target_is_heading else 0)
flags_heading = target_is_heading or bool(seg_headings)
elif op["op"] == "delete_block":
touched += 1
headings_delta -= 1 if target_is_heading else 0
flags_heading = target_is_heading
else: # insert_after
headings_delta += seg_headings
flags_heading = bool(seg_headings)
if flags_heading:
heading_op_indexes.append(analysis["op_index"])
blocks_total = len(base.blocks)
touched_ratio = (touched / blocks_total) if blocks_total else 0.0
ratio_exceeded = (
touched_ratio_threshold is not None and touched_ratio > touched_ratio_threshold
)
structural_flags = {
"heading_op_indexes": heading_op_indexes,
"section_count_delta": headings_delta,
"touched_ratio": round(touched_ratio, 4),
"touched_ratio_threshold": touched_ratio_threshold,
"touched_ratio_exceeded": ratio_exceeded,
"any": bool(heading_op_indexes) or headings_delta != 0 or ratio_exceeded,
}
# Pure-move pairs (§3.3): inserted segment hash == deleted block hash.
deleted_hashes = {
a["op"]["old_hash"]: a["op"]["block_id"]
for a in analyses
if a["op"]["op"] == "delete_block"
}
pure_move_seeds = []
for analysis in analyses:
if analysis["op"]["op"] not in ("replace_block", "insert_after"):
continue
for seg_idx, seg in enumerate(analysis["segments"] or []):
if seg.norm_hash in deleted_hashes:
pure_move_seeds.append(
{
"from_block_id": deleted_hashes[seg.norm_hash],
"op_index": analysis["op_index"],
"segment_index": seg_idx,
}
)
return {
"analyses": analyses,
"structural_flags": structural_flags,
"pure_move_seeds": pure_move_seeds,
"counters_base": {"blocks_total": blocks_total, "blocks_touched": touched},
}
def _render_segments(
new_text: str,
segments: list[Block],
*,
first_keeps_marker: bool,
fresh_ids: list[str],
) -> str:
"""Render fragment segments with marker lines, joined by blank lines.
``fresh_ids`` supplies the IDs for every segment that needs one
(all of them, except the first when ``first_keeps_marker``). Each
rendered segment ends with exactly one newline.
"""
rendered: list[str] = []
fresh_iter = iter(fresh_ids)
for seg_idx, seg in enumerate(segments):
seg_text = new_text[seg.span[0] : seg.span[1]]
if not seg_text.endswith("\n"):
seg_text += "\n"
if seg_idx == 0 and first_keeps_marker:
rendered.append(seg_text)
else:
rendered.append(f"<!--block:{next(fresh_iter)}-->\n{seg_text}")
return "\n".join(rendered)
def apply_patch(base_text: str, base: ParsedDocument, analysis: dict) -> tuple[str, dict]:
"""Phase 2: splice. Returns (output_text, phase2_report_fields)."""
blocks = base.blocks
n = len(blocks)
text = base_text
ops_by_target: dict[str, dict] = {}
doc_body_start_op: dict | None = None
for a in analysis["analyses"]:
if a["op"]["block_id"] == DOC_BODY_START:
doc_body_start_op = a
else:
ops_by_target[a["op"]["block_id"]] = a
next_num = base.next_fresh_id_num()
fresh_assigned: list[str] = []
seg_id_map: dict[tuple[int, int], str] = {} # (op_index, seg_index) -> fresh id
ops_applied: list[dict] = []
def _take_fresh(op_index: int, seg_indexes: list[int]) -> list[str]:
nonlocal next_num
ids = []
for seg_idx in seg_indexes:
fid = BLOCK_ID_FORMAT.format(next_num)
next_num += 1
ids.append(fid)
fresh_assigned.append(fid)
seg_id_map[(op_index, seg_idx)] = fid
return ids
# Splicing model: a block's unit is [full_start, next.full_start); the
# "gap" is the separator bytes between its content end and the next
# block's full_start, copied verbatim (§3.3 byte-span splicing). The
# gap must be RECOMPUTED instead of copied only where its boundary
# disappears (everything after it deleted) or never existed (an
# insertion lands where the base had zero inter-block bytes).
deleted = {
a["op"]["block_id"]
for a in analysis["analyses"]
if a["op"]["op"] == "delete_block"
}
# Highest index that survives the patch; `i >= last_kept` ⇔ every
# block after i is deleted (O(1) per block instead of a tail scan).
last_kept = max(
(j for j in range(n) if blocks[j].block_id not in deleted),
default=-1,
)
out: list[str] = []
head_end = blocks[0].full_start if n else len(text)
out.append(text[0:head_end])
if doc_body_start_op is not None:
a = doc_body_start_op
segments = a["segments"]
ids = _take_fresh(a["op_index"], list(range(len(segments))))
rendered = _render_segments(
a["op"]["new_text"], segments, first_keeps_marker=False, fresh_ids=ids
)
out.append(rendered)
if n:
out.append("\n")
ops_applied.append(
{
"op_index": a["op_index"],
"op": "insert_after",
"block_id": DOC_BODY_START,
"roadmap_item_ids": a["op"]["roadmap_item_ids"],
"claim_strength_changes": a["op"]["claim_strength_changes"],
"collateral_authorization_ids": a["op"]["collateral_authorization_ids"],
"new_block_ids": ids,
}
)
for i, block in enumerate(blocks):
unit_end = blocks[i + 1].full_start if i + 1 < n else len(text)
content_end = block.span[1]
gap = text[content_end:unit_end]
a = ops_by_target.get(block.block_id) if block.block_id else None
if a is not None and a["op"]["op"] == "delete_block":
ops_applied.append(
{
"op_index": a["op_index"],
"op": "delete_block",
"block_id": block.block_id,
"roadmap_item_ids": a["op"]["roadmap_item_ids"],
"claim_strength_changes": a["op"]["claim_strength_changes"],
"collateral_authorization_ids": a["op"]["collateral_authorization_ids"],
"new_block_ids": [],
}
)
continue # marker, content, and following separator all dropped
# Suppress the separator when everything after this block is
# deleted (a last-block delete must not leave trailing blanks).
rest_all_deleted = i + 1 < n and i >= last_kept
if a is None:
out.append(text[block.full_start : content_end])
out.append("" if rest_all_deleted else gap)
continue
op = a["op"]
if op["op"] == "replace_block":
segments = a["segments"]
ids = _take_fresh(a["op_index"], list(range(1, len(segments))))
if block.marker_span is not None:
out.append(text[block.marker_span[0] : block.marker_span[1]])
rendered = _render_segments(
op["new_text"], segments, first_keeps_marker=True, fresh_ids=ids
)
content = text[block.span[0] : block.span[1]]
if not content.endswith("\n") and rendered.endswith("\n"):
rendered = rendered[:-1] # final block without EOL stays EOL-less
out.append(rendered)
out.append("" if rest_all_deleted else gap)
ops_applied.append(
{
"op_index": a["op_index"],
"op": "replace_block",
"block_id": block.block_id,
"roadmap_item_ids": op["roadmap_item_ids"],
"claim_strength_changes": op["claim_strength_changes"],
"collateral_authorization_ids": op["collateral_authorization_ids"],
"new_block_ids": ids,
}
)
else: # insert_after
segments = a["segments"]
ids = _take_fresh(a["op_index"], list(range(len(segments))))
out.append(text[block.full_start : content_end])
content = text[block.span[0] : block.span[1]]
prefix = "\n" if content.endswith("\n") else "\n\n"
rendered = _render_segments(
op["new_text"], segments, first_keeps_marker=False, fresh_ids=ids
)
out.append(prefix + rendered)
if gap == "" and i + 1 < n and not rest_all_deleted:
out.append("\n") # keep a blank line before an adjacent next block
out.append("" if rest_all_deleted else gap)
ops_applied.append(
{
"op_index": a["op_index"],
"op": "insert_after",
"block_id": block.block_id,
"roadmap_item_ids": op["roadmap_item_ids"],
"claim_strength_changes": op["claim_strength_changes"],
"collateral_authorization_ids": op["collateral_authorization_ids"],
"new_block_ids": ids,
}
)
output_text = "".join(out)
target_id_by_op_index = {
a["op_index"]: a["op"]["block_id"]
for a in analysis["analyses"]
if a["op"]["op"] == "replace_block"
}
pure_move_pairs = []
for seed in analysis["pure_move_seeds"]:
to_id = seg_id_map.get((seed["op_index"], seed["segment_index"]))
if to_id is None and seed["segment_index"] == 0:
# replace_block keeps the target's ID on the head segment.
to_id = target_id_by_op_index.get(seed["op_index"])
pure_move_pairs.append(
{
"from_block_id": seed["from_block_id"],
"to_block_id": to_id,
"op_index": seed["op_index"],
}
)
ops_applied.sort(key=lambda entry: entry["op_index"])
return output_text, {
"ops_applied": ops_applied,
"fresh_block_ids": fresh_assigned,
"pure_move_pairs": pure_move_pairs,
}
def run(
base_path: Path,
patch_path: Path,
output_path: Path,
report_path: Path,
*,
acknowledge_structural: bool,
touched_ratio_threshold: float | None,
block_manifest_path: Path | None = None,
roadmap_path: Path | None = None,
author_adjudication_path: Path | None = None,
claim_surface_manifest_path: Path | None = None,
artifact_root: Path | None = None,
integrity_issue_list_path: Path | None = None,
integrity_authorization_path: Path | None = None,
) -> dict:
"""Full two-phase apply. Raises ApplyRejection / StructuralRefusal /
BlockParseError; returns the success report dict.
`touched_ratio_threshold`: the CLI defaults this to
DEFAULT_TOUCHED_RATIO_THRESHOLD (0.6, the #424 ship decision); a
programmatic caller may pass `None` for record-only mode — the ratio is
still computed and recorded in the report, but never triggers a
structural refusal (for callers that own their own escalation policy).
"""
resolved = {
"base": base_path.resolve(),
"output": output_path.resolve(),
"report": report_path.resolve(),
}
collisions = []
if resolved["output"] == resolved["base"]:
collisions.append("--output must not name the base draft (the base is never modified)")
if resolved["report"] in (resolved["base"], resolved["output"]):
collisions.append("--report-out must not name the base draft or the output draft")
if collisions:
raise ApplyRejection(
[
{"op_index": None, "kind": "artifact_path_collision", "message": msg}
for msg in collisions
]
)
# The output is a NEW versioned artifact (§3.3 supersession): refusing
# to overwrite an existing file is what makes the report-failure
# cleanup below safe — any file at output_path is one this run created.
exists = [
{"op_index": None, "kind": "artifact_already_exists", "message": msg}
for p, msg in (
(output_path, "--output already exists; the revised draft must be a new versioned artifact"),
(report_path, "--report-out already exists; each apply emits its own report"),
)
if p.exists()
]
if exists:
raise ApplyRejection(exists)
try:
base_raw = _read_path_once(base_path, "base draft")
base_text = base_raw.decode("utf-8")
except (ContractError, UnicodeDecodeError) as exc:
message = "; ".join(exc.failures) if isinstance(exc, ContractError) else str(exc)
raise ApplyRejection(
[{"op_index": None, "kind": "base_read_invalid", "message": message}]
) from exc
try:
patch, patch_raw = load_json_path(patch_path, "revision patch")
except ContractError as exc:
raise ApplyRejection(
[
{"op_index": None, "kind": "patch_read_invalid", "message": failure}
for failure in exc.failures
]
) from exc
try:
base = parse_document(base_text)
except BlockParseError as exc:
raise ApplyRejection(
[{"op_index": None, "kind": f"base_parse_rejected:{exc.kind}", "message": str(exc)}]
) from exc
analysis = validate_patch(
patch, base_raw, base, touched_ratio_threshold=touched_ratio_threshold
)
# Authority replay is a Phase-1 gate. All named inputs are read once,
# exact-byte/hash checked, and validated before any output is written.
try:
if block_manifest_path is None:
raise ContractError(["current patch apply requires --block-manifest"])
block_manifest, block_manifest_raw = load_json_path(
block_manifest_path, "block manifest"
)
validate_block_manifest(block_manifest, block_manifest_raw, base_raw)
context = patch["authorization_context"]
if context == "review_roadmap":
missing = [
name
for name, value in (
("--roadmap", roadmap_path),
("--author-adjudication", author_adjudication_path),
("--claim-surface-manifest", claim_surface_manifest_path),
("--artifact-root", artifact_root),
)
if value is None
]
forbidden_integrity = [
name
for name, value in (
("--integrity-issue-list", integrity_issue_list_path),
("--integrity-authorization", integrity_authorization_path),
)
if value is not None
]
if forbidden_integrity:
raise ContractError(
[
"review-roadmap patch must not receive "
+ ", ".join(forbidden_integrity)
]
)
if missing:
raise ContractError(
["review-roadmap patch is missing " + ", ".join(missing)]
)
assert roadmap_path is not None
assert author_adjudication_path is not None
assert claim_surface_manifest_path is not None
assert artifact_root is not None
roadmap, roadmap_raw = load_json_path(roadmap_path, "revision roadmap")
validate_roadmap(
roadmap,
roadmap_raw=roadmap_raw,
base_raw=base_raw,
block_manifest=block_manifest,
block_manifest_raw=block_manifest_raw,
)
claim_surface, claim_surface_raw = load_json_path(
claim_surface_manifest_path, "claim surface manifest"
)
surfaces = validate_claim_surface_manifest(
claim_surface,
claim_surface_raw=claim_surface_raw,
roadmap=roadmap,
roadmap_raw=roadmap_raw,
base_raw=base_raw,
artifact_store=ArtifactStore(artifact_root),
)
adjudication, adjudication_raw = load_json_path(
author_adjudication_path, "author adjudication"
)
authorization_witness = validate_review_patch_authorization(
patch,
base_raw=base_raw,
roadmap=roadmap,
roadmap_raw=roadmap_raw,
adjudication=adjudication,
adjudication_raw=adjudication_raw,
claim_surface=claim_surface,
claim_surface_raw=claim_surface_raw,
surfaces_by_id=surfaces,
)
elif context == "integrity_correction":
forbidden = [
name
for name, value in (
("--roadmap", roadmap_path),
("--author-adjudication", author_adjudication_path),
("--claim-surface-manifest", claim_surface_manifest_path),
("--artifact-root", artifact_root),
)
if value is not None
]
if forbidden:
raise ContractError(
["integrity-correction patch must not receive " + ", ".join(forbidden)]
)
missing = [
name
for name, value in (
("--integrity-issue-list", integrity_issue_list_path),
("--integrity-authorization", integrity_authorization_path),
)
if value is None
]
if missing:
raise ContractError(
["integrity-correction patch requires " + ", ".join(missing)]
)
assert integrity_issue_list_path is not None
assert integrity_authorization_path is not None
issue_list, issue_list_raw = load_json_path(
integrity_issue_list_path, "integrity correction list"
)
integrity_authorization, integrity_authorization_raw = load_json_path(
integrity_authorization_path,
"integrity correction authorization",
)
authorization_witness = validate_integrity_patch_authorization(
patch,
patch_raw=patch_raw,
base_raw=base_raw,
issue_list=issue_list,
issue_list_raw=issue_list_raw,
integrity_authorization=integrity_authorization,
integrity_authorization_raw=integrity_authorization_raw,
)
else: # schema validation makes this unreachable; keep fail-closed.
raise ContractError([f"unsupported authorization_context {context!r}"])
except ContractError as exc:
raise ApplyRejection(
[
{"op_index": None, "kind": "authorization_invalid", "message": failure}
for failure in exc.failures
]
) from exc
flags = analysis["structural_flags"]
flags["acknowledged"] = acknowledge_structural
if flags["any"] and not acknowledge_structural:
raise StructuralRefusal(flags)
output_text, phase2 = apply_patch(base_text, base, analysis)
# Post-write self-check (marker uniqueness + grammar): a failure here
# is a splicer bug — no artifact may land.
reparsed = parse_document(output_text)
ids = [b.block_id for b in reparsed.blocks if b.block_id is not None]
if len(ids) != len(set(ids)): # pragma: no cover - parser already rejects
raise AssertionError("self-check: duplicate markers in apply output")
output_bytes = output_text.encode("utf-8")
atomic_write_bytes(output_path, output_bytes)
counters_base = analysis["counters_base"]
blocks_total = counters_base["blocks_total"]
touched = counters_base["blocks_touched"]
preserved = blocks_total - touched
report = {
"report_format_version": REPORT_FORMAT_VERSION,
"mode": "patch",
"base_path": str(base_path),
"output_path": str(output_path),
"base_draft_hash": patch["base_draft_hash"],
"output_draft_hash": base_draft_hash(output_bytes),
# Full 64-hex (not the 12-hex draft-hash form): it pairs with the
# §11 manifest's `revision_patches[i].sha256`, which is full-width.
"patch_digest": hashlib.sha256(patch_raw).hexdigest(),
"revision_round": patch["revision_round"],
"authorization_context": patch["authorization_context"],
"authorization_witness": authorization_witness,
"ops_applied": phase2["ops_applied"],
"fresh_block_ids": phase2["fresh_block_ids"],
"pure_move_pairs": phase2["pure_move_pairs"],
"structural_flags": flags,
"counters": {
"blocks_total": blocks_total,
"blocks_touched": touched,
"blocks_preserved_byte_identical": preserved,
"preserved_ratio": round(preserved / blocks_total, 4) if blocks_total else 0.0,
},
}
try:
# allow_nan=False: a non-finite counter would serialize as bare
# `NaN`/`Infinity` (invalid JSON for strict readers). The threshold
# is range-validated upstream, so this is belt-and-suspenders.
atomic_write_bytes(
report_path,
(json.dumps(report, ensure_ascii=False, indent=2, allow_nan=False)
+ "\n").encode("utf-8"),
)
except BaseException:
# The output and its apply report land as a pair: a report-write
# failure must not leave a revised draft with no provenance record.
output_path.unlink(missing_ok=True)
raise
return report
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("base", type=Path, help="anchored base draft (never modified)")
parser.add_argument("patch", type=Path, help="revision patch JSON")
parser.add_argument(
"--block-manifest",
type=Path,
required=True,
help="exact script-generated block manifest for the base draft",
)
parser.add_argument("--roadmap", type=Path, help="immutable reviewer roadmap (review context)")
parser.add_argument(
"--author-adjudication",
type=Path,
help="hash-bound explicit author-choice sidecar (review context)",
)
parser.add_argument(
"--claim-surface-manifest",
type=Path,
help="registered exact claim surfaces (review context)",
)
parser.add_argument(
"--artifact-root",
type=Path,
help="root for claim-intent artifacts named by the claim-surface manifest",
)
parser.add_argument(
"--integrity-issue-list",
type=Path,
help="hash-bound correction proposal list (integrity context only)",
)
parser.add_argument(
"--integrity-authorization",
type=Path,
help="explicit-author exact-patch authorization (integrity context only)",
)
parser.add_argument("--output", type=Path, required=True, help="revised draft output path")
parser.add_argument(
"--report-out",
type=Path,
default=None,
help="apply report path (default: <output>.apply-report.json)",
)
parser.add_argument(
"--acknowledge-structural",
action="store_true",
help="proceed despite structural-shape flags (set only after the §3.6 escalation checkpoint)",
)
parser.add_argument(
"--touched-ratio-threshold",
type=_ratio_threshold,
default=DEFAULT_TOUCHED_RATIO_THRESHOLD,
help="touched-ratio trigger threshold, a finite ratio in [0.0, 1.0] "
"(default %(default)s, the #424 ship decision; fires when "
"blocks_touched/blocks_total is strictly above it; pass 1.0 to disable)",
)
args = parser.parse_args(argv)
report_path = args.report_out or Path(str(args.output) + ".apply-report.json")
try:
report = run(
args.base,
args.patch,
args.output,
report_path,
acknowledge_structural=args.acknowledge_structural,
touched_ratio_threshold=args.touched_ratio_threshold,
block_manifest_path=args.block_manifest,
roadmap_path=args.roadmap,
author_adjudication_path=args.author_adjudication,
claim_surface_manifest_path=args.claim_surface_manifest,
artifact_root=args.artifact_root,
integrity_issue_list_path=args.integrity_issue_list,
integrity_authorization_path=args.integrity_authorization,
)
except ApplyRejection as exc:
print(json.dumps({"result": "rejected", "phase": 1, "failures": exc.failures}, indent=2))
return 2
except StructuralRefusal as exc:
print(
json.dumps(
{
"result": "refused_structural",
"structural_flags": exc.flags,
"hint": "re-run with --acknowledge-structural only after the "
"escalation checkpoint (spec §3.6)",
},
indent=2,
)
)
return 3
except AssertionError as exc: # pragma: no cover - self-check path
print(f"SELF-CHECK FAILED (bug, no artifact written): {exc}", file=sys.stderr)
return 4
counters = report["counters"]
print(
"apply ok: {applied} op(s); {preserved}/{total} blocks preserved byte-identical "
"(ratio {ratio}); report {rpath}".format(
applied=len(report["ops_applied"]),
preserved=counters["blocks_preserved_byte_identical"],
total=counters["blocks_total"],
ratio=counters["preserved_ratio"],
rpath=report_path,
)
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |