agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/rule_snapshot.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+
+from agentic_project_kit.rule_source_validator import (
+    RuleSourceValidationResult,
+    validate_rule_sources,
+)
+
+
+@dataclass(frozen=True)
+class RuleSourceDigest:
+    path: str
+    sha256: str
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class DerivedRuleSnapshot:
+    schema_version: int
+    snapshot_id: str
+    sources_total: int
+    source_digests: tuple[RuleSourceDigest, ...]
+    validation: RuleSourceValidationResult
+
+    @property
+    def is_valid(self) -> bool:
+        return self.validation.is_valid
+
+    @property
+    def fail_closed(self) -> bool:
+        return self.validation.fail_closed
+
+    def as_json_data(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "snapshot_id": self.snapshot_id,
+            "sources_total": self.sources_total,
+            "is_valid": self.is_valid,
+            "fail_closed": self.fail_closed,
+            "source_digests": [
+                {
+                    "path": digest.path,
+                    "sha256": digest.sha256,
+                    "size_bytes": digest.size_bytes,
+                }
+                for digest in self.source_digests
+            ],
+            "validation": self.validation.as_json_data(),
+        }
+
+
+def _file_digest(path: Path) -> tuple[str, int]:
+    data = path.read_bytes()
+    return hashlib.sha256(data).hexdigest(), len(data)
+
+
+def _snapshot_id(
+    source_digests: tuple[RuleSourceDigest, ...], validation: RuleSourceValidationResult
+) -> str:
+    payload = {
+        "schema_version": 1,
+        "source_digests": [
+            {
+                "path": digest.path,
+                "sha256": digest.sha256,
+                "size_bytes": digest.size_bytes,
+            }
+            for digest in source_digests
+        ],
+        "blocking_reasons": list(validation.blocking_reasons),
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def build_derived_rule_snapshot(root: str | Path = ".") -> DerivedRuleSnapshot:
+    root_path = Path(root)
+    validation = validate_rule_sources(root_path)
+
+    digests: list[RuleSourceDigest] = []
+    for source in validation.source_paths:
+        path = root_path / source
+        if path.exists() and path.is_file():
+            digest, size_bytes = _file_digest(path)
+            digests.append(RuleSourceDigest(path=source, sha256=digest, size_bytes=size_bytes))
+
+    source_digests = tuple(digests)
+    return DerivedRuleSnapshot(
+        schema_version=1,
+        snapshot_id=_snapshot_id(source_digests, validation),
+        sources_total=validation.sources_total,
+        source_digests=source_digests,
+        validation=validation,
+    )

agentic_project_kit/rule_source_validator.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from agentic_project_kit.chat_bootloader import MANDATORY_BOOT_SOURCES
+from agentic_project_kit.handoff_prompt import MANDATORY_SUCCESSOR_CHAT_SOURCES
+from agentic_project_kit.handoff_state import load_handoff_state, validate_handoff_state
+from agentic_project_kit.rule_refresh import COMMUNICATION_RULE_SOURCES, HANDOFF_RULE_SOURCES
+
+
+CANONICAL_YAML_RULE_SOURCES = (
+    ".agentic/compiled_agent_context.yaml",
+    ".agentic/handoff_state.yaml",
+    ".agentic/rule_mechanism_inventory.yaml",
+    ".agentic/rule_migrations.yaml",
+    ".agentic/rule_preservation.yaml",
+)
+
+
+@dataclass(frozen=True)
+class RuleSourceValidationResult:
+    source_paths: tuple[str, ...]
+    missing_required_paths: tuple[str, ...]
+    yaml_parse_error_paths: tuple[str, ...]
+    handoff_state_errors: tuple[str, ...]
+    blocking_reasons: tuple[str, ...]
+
+    @property
+    def sources_total(self) -> int:
+        return len(self.source_paths)
+
+    @property
+    def is_valid(self) -> bool:
+        return not self.blocking_reasons
+
+    @property
+    def fail_closed(self) -> bool:
+        return bool(self.blocking_reasons)
+
+    def as_json_data(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "sources_total": self.sources_total,
+            "is_valid": self.is_valid,
+            "fail_closed": self.fail_closed,
+            "source_paths": list(self.source_paths),
+            "missing_required_paths": list(self.missing_required_paths),
+            "yaml_parse_error_paths": list(self.yaml_parse_error_paths),
+            "handoff_state_errors": list(self.handoff_state_errors),
+            "blocking_reasons": list(self.blocking_reasons),
+        }
+
+
+def canonical_rule_source_paths() -> tuple[str, ...]:
+    """Return the de-duplicated canonical rule-source set used for read-only validation."""
+
+    ordered: list[str] = []
+    for collection in (
+        MANDATORY_BOOT_SOURCES,
+        tuple(MANDATORY_SUCCESSOR_CHAT_SOURCES),
+        COMMUNICATION_RULE_SOURCES,
+        HANDOFF_RULE_SOURCES,
+        CANONICAL_YAML_RULE_SOURCES,
+    ):
+        for source in collection:
+            if source == "relevant source files and tests for the requested slice":
+                continue
+            if source not in ordered:
+                ordered.append(source)
+    return tuple(ordered)
+
+
+def validate_rule_sources(root: str | Path = ".") -> RuleSourceValidationResult:
+    """Validate canonical rule sources without writing files or generating snapshots."""
+
+    root_path = Path(root)
+    source_paths = canonical_rule_source_paths()
+    missing_required_paths: list[str] = []
+    yaml_parse_error_paths: list[str] = []
+    handoff_state_errors: list[str] = []
+    blocking_reasons: list[str] = []
+
+    for source in source_paths:
+        path = root_path / source
+        if not path.exists() or not path.is_file():
+            missing_required_paths.append(source)
+            blocking_reasons.append(f"missing required rule source: {source}")
+            continue
+
+        if path.suffix in {".yaml", ".yml"}:
+            try:
+                yaml.safe_load(path.read_text(encoding="utf-8"))
+            except yaml.YAMLError as exc:
+                yaml_parse_error_paths.append(source)
+                blocking_reasons.append(f"yaml parse error in rule source: {source}: {exc}")
+
+    handoff_path = root_path / ".agentic/handoff_state.yaml"
+    if handoff_path.exists() and handoff_path.is_file():
+        try:
+            handoff_state_errors.extend(validate_handoff_state(load_handoff_state(handoff_path)))
+        except (OSError, ValueError, yaml.YAMLError) as exc:
+            handoff_state_errors.append(str(exc))
+    for error in handoff_state_errors:
+        blocking_reasons.append(f"handoff_state invalid: {error}")
+
+    return RuleSourceValidationResult(
+        source_paths=source_paths,
+        missing_required_paths=tuple(missing_required_paths),
+        yaml_parse_error_paths=tuple(yaml_parse_error_paths),
+        handoff_state_errors=tuple(handoff_state_errors),
+        blocking_reasons=tuple(blocking_reasons),
+    )
+
+
+def render_rule_source_validation(result: RuleSourceValidationResult) -> str:
+    lines = [
+        "RULE_SOURCE_VALIDATION",
+        f"sources_total={result.sources_total}",
+        f"is_valid={result.is_valid}",
+        f"fail_closed={result.fail_closed}",
+    ]
+    for path in result.missing_required_paths:
+        lines.append(f"missing_required_path={path}")
+    for path in result.yaml_parse_error_paths:
+        lines.append(f"yaml_parse_error_path={path}")
+    for error in result.handoff_state_errors:
+        lines.append(f"handoff_state_error={error}")
+    for reason in result.blocking_reasons:
+        lines.append(f"blocking_reason={reason}")
+    return "\n".join(lines)

agentic_project_kit/run_summary.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class WorkResult(StrEnum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    PENDING = "PENDING"
+    HARD_FAIL = "HARD-FAIL"
+
+
+class EvidenceResult(StrEnum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    PARTIAL = "PARTIAL"
+    CHAT_ONLY = "CHAT_ONLY"
+    NOT_REQUIRED = "NOT_REQUIRED"
+
+
+class RemoteEvidence(StrEnum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    PARTIAL = "PARTIAL"
+    NOT_REQUIRED = "NOT_REQUIRED"
+
+
+class NextChatReply(StrEnum):
+    D = "d"
+    F = "f"
+    PASTE_OUTPUT = "paste-output"
+    CONTINUE = "continue"
+    STOP = "stop"
+
+
+@dataclass(frozen=True)
+class RunSummary:
+    work_result: WorkResult
+    evidence_result: EvidenceResult
+    overall_result: WorkResult
+    remote_evidence: RemoteEvidence
+    terminal_log: str = "NONE"
+    command_report: str = "NONE"
+    next_chat_reply: NextChatReply = NextChatReply.D
+
+
+def render_run_summary(summary: RunSummary) -> str:
+    lines = [
+        "================================================================",
+        "SUMMARY",
+        f"WORK RESULT: {summary.work_result.value}",
+        f"EVIDENCE RESULT: {summary.evidence_result.value}",
+        f"OVERALL RESULT: {summary.overall_result.value}",
+        f"REMOTE_EVIDENCE: {summary.remote_evidence.value}",
+        f"terminal_log={summary.terminal_log}",
+        f"command_report={summary.command_report}",
+        f"NEXT_CHAT_REPLY: {summary.next_chat_reply.value}",
+        f"### RESULT: {summary.overall_result.value} ###",
+        "================================================================",
+    ]
+    return "\n".join(lines)
+
+
+def summary_for_status(status: int, terminal_log: str = "NONE", command_report: str = "NONE", remote_evidence: RemoteEvidence = RemoteEvidence.PARTIAL) -> RunSummary:
+    if status == 0:
+        return RunSummary(WorkResult.PASS, EvidenceResult.PASS, WorkResult.PASS, remote_evidence, terminal_log, command_report, NextChatReply.D)
+    return RunSummary(WorkResult.FAIL, EvidenceResult.PARTIAL, WorkResult.FAIL, remote_evidence, terminal_log, command_report, NextChatReply.F)

agentic_project_kit/run_summary_renderer.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+VALID_RESULTS = {"PASS", "FAIL", "PENDING", "HARD-FAIL", "NO-COMMAND"}
+VALID_EVIDENCE_RESULTS = {"PASS", "FAIL", "PARTIAL", "CHAT_ONLY", "NOT_REQUIRED"}
+VALID_REMOTE_EVIDENCE_RESULTS = {"PASS", "FAIL", "PARTIAL", "NOT_REQUIRED"}
+VALID_CHAT_REPLIES = {"d", "f", "w", "paste-output", "stop"}
+LEGACY_SUMMARY_TOKENS = ("WORK RESULT:", "EVIDENCE RESULT:", "OVERALL RESULT:", "NEXT_CHAT_REPLY:")
+REQUIRED_RENDERED_TOKENS = (
+    "SUMMARY COMM-",
+    "SLICE\n",
+    "EXECUTION\n",
+    "RESULT\n",
+    "REMOTE\n",
+    "EVIDENCE FILES\n",
+    "INTERPRETATION\n",
+    "NEXT\n",
+    "  WORK: ",
+    "  EVIDENCE: ",
+    "  OVERALL: ",
+    "  REMOTE_EVIDENCE: ",
+    "  terminal_log: ",
+    "  command_report: ",
+    "  CHAT_REPLY: ",
+    "### RESULT: ",
+)
+
+
+@dataclass(frozen=True)
+class SummaryPayload:
+    comm_id: str = "COMM-PENDING"
+    comm_header: str = ""
+    slice: str = ""
+    slice_name: str = ""
+    scope: str = ""
+    branch: str = "current"
+    origin: str = "local"
+    state_mode: str = "local"
+    mode_check: str = "not_recorded"
+    work: str = "PENDING"
+    evidence: str = "CHAT_ONLY"
+    overall: str = "PENDING"
+    remote_evidence: str = "NOT_REQUIRED"
+    pr: str = "NONE"
+    head_sha: str = "NONE"
+    ci: str = "NONE"
+    merge: str = "NONE"
+    terminal_log: str = "NONE"
+    terminal_log_remote: str = "NONE"
+    terminal_log_local: str = "NONE"
+    command_report: str = "NONE"
+    interpretation: str = "No interpretation recorded."
+    safe_step: str = "not_recorded"
+    next: str = ""
+    chat_reply: str = ""
+    timestamp: str = ""
+
+
+RunSummaryPayload = SummaryPayload
+
+
+def _payload_from_mapping(data: dict[str, Any]) -> SummaryPayload:
+    normalized = {str(key).replace("-", "_"): value for key, value in data.items()}
+    if "next_safe_step" in normalized and "safe_step" not in normalized:
+        normalized["safe_step"] = normalized["next_safe_step"]
+    allowed = SummaryPayload.__dataclass_fields__.keys()
+    return SummaryPayload(**{key: str(normalized[key]) for key in allowed if key in normalized and normalized[key] is not None})
+
+
+def _selected_chat_reply(payload: SummaryPayload) -> str:
+    return payload.chat_reply or payload.next or ""
+
+
+def validate_summary_data(data: SummaryPayload | dict[str, Any]) -> list[str]:
+    payload = data if isinstance(data, SummaryPayload) else _payload_from_mapping(data)
+    findings: list[str] = []
+    terminal_log = payload.terminal_log.strip()
+    if not terminal_log or terminal_log == "NONE":
+        findings.append("missing field: terminal_log")
+    if payload.work not in VALID_RESULTS:
+        findings.append("invalid field: work")
+    if payload.overall not in VALID_RESULTS:
+        findings.append("invalid field: overall")
+    if payload.evidence not in VALID_EVIDENCE_RESULTS:
+        findings.append("invalid field: evidence")
+    if payload.remote_evidence not in VALID_REMOTE_EVIDENCE_RESULTS:
+        findings.append("invalid field: remote_evidence")
+    next_reply = _selected_chat_reply(payload)
+    if next_reply not in VALID_CHAT_REPLIES:
+        findings.append("invalid field: chat_reply")
+    if payload.overall == "PASS" and payload.work != "PASS":
+        findings.append("invalid pass: work is not PASS")
+    if payload.overall == "PASS" and payload.evidence in {"FAIL", "PARTIAL", "CHAT_ONLY"}:
+        findings.append("invalid pass: evidence is not complete")
+    if payload.overall == "PASS" and payload.remote_evidence not in {"PASS", "NOT_REQUIRED"}:
+        findings.append("invalid pass: remote evidence is not complete")
+    if payload.overall == "PASS" and next_reply != "d":
+        findings.append("invalid pass: chat_reply must be d")
+    if payload.overall in {"FAIL", "HARD-FAIL"} and next_reply == "d":
+        findings.append("invalid failure: chat_reply must not be d")
+    if payload.overall == "PENDING" and next_reply in {"d", "f"}:
+        findings.append("invalid pending: chat_reply must be w, paste-output, or stop")
+    if payload.remote_evidence == "PASS" and not payload.terminal_log_remote.startswith("docs/reports/terminal/"):
+        findings.append("invalid remote evidence: missing remote terminal log")
+    return findings
+
+
+def validate_rendered_summary_text(text: str) -> list[str]:
+    findings: list[str] = []
+    for token in LEGACY_SUMMARY_TOKENS:
+        if token in text:
+            findings.append(f"legacy summary token: {token}")
+    for token in REQUIRED_RENDERED_TOKENS:
+        if token not in text:
+            findings.append(f"missing summary token: {token.strip()}")
+    summary_headers = [line for line in text.splitlines() if line.startswith("SUMMARY COMM-")]
+    if len(summary_headers) != 1:
+        findings.append(f"invalid summary count: {len(summary_headers)}")
+    result_values = [line.split(":", 1)[1].strip() for line in text.splitlines() if line.strip().startswith("OVERALL:")]
+    marker_values = [line.replace("### RESULT:", "").replace("###", "").strip() for line in text.splitlines() if line.startswith("### RESULT:")]
+    if len(marker_values) != 1:
+        findings.append(f"invalid result marker count: {len(marker_values)}")
+    if result_values and marker_values and result_values[-1] != marker_values[-1]:
+        findings.append("contradictory summary marker")
+    for bad in ("  REMOTE_EVIDENCE: NONE", "  REMOTE_EVIDENCE: CHAT_ONLY", "  REMOTE_EVIDENCE: PENDING"):
+        if bad in text:
+            findings.append("invalid rendered remote evidence value")
+    return findings
+
+
+def _header(payload: SummaryPayload) -> str:
+    if payload.comm_header.strip():
+        return payload.comm_header
+    timestamp = payload.timestamp or datetime.now().astimezone().strftime("%Y-%m-%d %H:%M:%S %z")
+    return f"SUMMARY {payload.comm_id} | {timestamp}"
+
+
+def render_summary(payload: SummaryPayload | dict[str, Any]) -> str:
+    if isinstance(payload, dict):
+        payload = _payload_from_mapping(payload)
+    findings = validate_summary_data(payload)
+    if findings:
+        raise ValueError("; ".join(findings))
+    slice_name = payload.slice or payload.slice_name or "UNKNOWN"
+    next_reply = _selected_chat_reply(payload)
+    lines = [
+        "================================================================",
+        _header(payload),
+        "",
+        "SLICE",
+        f"  NAME: {slice_name}",
+        f"  SCOPE: {payload.scope}",
+        f"  BRANCH: {payload.branch}",
+        "",
+        "EXECUTION",
+        f"  ORIGIN: {payload.origin}",
+        f"  STATE_MODE: {payload.state_mode}",
+        f"  MODE_CHECK: {payload.mode_check}",
+        "  SWITCH_HINT: ./ns mode-write local|remote && ./ns mode-check local|remote",
+        "",
+        "RESULT",
+        f"  WORK: {payload.work}",
+        f"  EVIDENCE: {payload.evidence}",
+        f"  OVERALL: {payload.overall}",
+        "",
+        "REMOTE",
+        f"  REMOTE_EVIDENCE: {payload.remote_evidence}",
+        f"  PR: {payload.pr}",
+        f"  HEAD_SHA: {payload.head_sha}",
+        f"  CI: {payload.ci}",
+        f"  MERGE: {payload.merge}",
+        "",
+        "EVIDENCE FILES",
+        f"  terminal_log: {payload.terminal_log}",
+        f"  terminal_log_remote: {payload.terminal_log_remote}",
+        f"  terminal_log_local: {payload.terminal_log_local}",
+        f"  command_report: {payload.command_report}",
+        "",
+        "INTERPRETATION",
+        f"  {payload.interpretation}",
+        "",
+        "NEXT",
+        f"  SAFE_STEP: {payload.safe_step}",
+        f"  CHAT_REPLY: {next_reply}",
+        "",
+        f"### RESULT: {payload.overall} ###",
+        "================================================================",
+    ]
+    rendered = "\n".join(lines)
+    rendered_findings = validate_rendered_summary_text(rendered)
+    if rendered_findings:
+        raise ValueError("; ".join(rendered_findings))
+    return rendered
+
+
+render = render_summary
+
+
+def _load_json_argument(value: str) -> dict[str, Any]:
+    candidate = Path(value)
+    if candidate.exists():
+        return json.loads(candidate.read_text(encoding="utf-8"))
+    return json.loads(value)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="run-summary-renderer")
+    parser.add_argument("--json", default=None)
+    for field in SummaryPayload.__dataclass_fields__:
+        parser.add_argument("--" + field.replace("_", "-"), dest=field, default=None)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.json:
+        data = _load_json_argument(args.json)
+    else:
+        data = {field: getattr(args, field) for field in SummaryPayload.__dataclass_fields__ if getattr(args, field) is not None}
+        if data.get("terminal_log", "NONE") == "NONE":
+            data["terminal_log"] = data.get("terminal_log_remote") or data.get("terminal_log_local") or "NONE"
+    try:
+        print(render_summary(_payload_from_mapping(data)))
+    except ValueError as exc:
+        parser.error(str(exc))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/runtime_validator.py

@@ -0,0 +1,68 @@
+"""Runtime validation primitives for generated governance artifacts.
+
+This module intentionally starts small: it provides deterministic, auditable
+validation results without performing repair or invoking any model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class ValidationSeverity(str, Enum):
+    """Severity for runtime validation findings."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass(frozen=True)
+class ValidationFinding:
+    """Single validation finding with stable machine-readable fields."""
+
+    code: str
+    message: str
+    severity: ValidationSeverity = ValidationSeverity.ERROR
+
+
+@dataclass(frozen=True)
+class ValidationReport:
+    findings: tuple[ValidationFinding, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return not any(finding.severity is ValidationSeverity.ERROR for finding in self.findings)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a deterministic JSON-safe representation."""
+        return {
+            "ok": self.ok,
+            "findings": [
+                {
+                    "severity": finding.severity.value,
+                    "code": finding.code,
+                    "message": finding.message,
+                }
+                for finding in self.findings
+            ],
+        }
+
+def validate_required_sections(text: str, required_sections: tuple[str, ...]) -> ValidationReport:
+    """Validate that required section markers are present in text.
+
+    The check is intentionally literal and deterministic. This makes it suitable
+    as a first runtime skeleton for generated output contracts and governance
+    wrapper artifacts.
+    """
+    findings: list[ValidationFinding] = []
+    for section in required_sections:
+        if section not in text:
+            findings.append(
+                ValidationFinding(
+                    code="missing_required_section",
+                    message=f"Missing required section: {section}",
+                )
+            )
+    return ValidationReport(findings=tuple(findings))

agentic_project_kit/safe_file_replace.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+import py_compile
+from pathlib import Path
+
+
+class SafeReplaceError(RuntimeError):
+    pass
+
+
+def validate_replacement(target: Path, replacement: Path) -> None:
+    if not replacement.exists():
+        raise SafeReplaceError(f"replacement does not exist: {replacement}")
+    if not replacement.is_file():
+        raise SafeReplaceError(f"replacement is not a file: {replacement}")
+    if replacement.is_symlink():
+        raise SafeReplaceError(f"replacement must not be a symlink: {replacement}")
+    if target.suffix == ".py":
+        try:
+            py_compile.compile(str(replacement), doraise=True)
+        except py_compile.PyCompileError as exc:
+            raise SafeReplaceError(f"replacement failed py_compile: {replacement}") from exc
+
+
+def safe_replace(target: Path | str, replacement: Path | str) -> Path:
+    target_path = Path(target)
+    replacement_path = Path(replacement)
+    if target_path.is_symlink():
+        raise SafeReplaceError(f"target must not be a symlink: {target_path}")
+    if not target_path.parent.exists():
+        raise SafeReplaceError(f"target parent does not exist: {target_path.parent}")
+    validate_replacement(target_path, replacement_path)
+    os.replace(replacement_path, target_path)
+    return target_path

agentic_project_kit/safe_patch.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import shlex
+
+
+FORBIDDEN_FRAGMENTS = (
+    "<<",
+    "python -c",
+    "python3 -c",
+    "${",
+)
+
+
+@dataclass(frozen=True)
+class SafePatchScript:
+    """A small shell script that writes a file line by line with printf."""
+
+    target: Path
+    content: str
+
+    def render(self) -> str:
+        target = shlex.quote(str(self.target))
+        lines = ["#!/usr/bin/env sh", "set -eu", f": > {target}"]
+        for line in self.content.splitlines():
+            quoted = shlex.quote(line)
+            lines.append(f"printf '%s\\n' {quoted} >> {target}")
+        return "\n".join(lines) + "\n"
+
+
+def render_safe_file_writer(target: str | Path, content: str) -> str:
+    """Render a quoting-safe shell script for deterministic file replacement."""
+
+    script = SafePatchScript(Path(target), content).render()
+    validate_safe_patch_script(script)
+    return script
+
+
+def validate_safe_patch_script(script: str) -> None:
+    """Reject recurring unsafe patch-script patterns before they reach the terminal."""
+
+    for fragment in FORBIDDEN_FRAGMENTS:
+        if fragment in script:
+            raise ValueError(f"unsafe patch script fragment detected: {fragment}")
+    if "cat >" in script or "cat << " in script:
+        raise ValueError("unsafe cat-based patch script detected")