syncade 0.6.2__py3-none-any.whl

syncade/persistence/checks.py

@@ -0,0 +1,249 @@
+"""Mechanical-check leg persistence.
+
+Writes ``<round_dir>/<check_name>.check.{stdout,stderr,exit-code.txt}`` for each
+configured check that ran, mirroring :func:`persist_test_run_result`'s
+file-layout convention. The orchestrator calls this once per check on rounds
+where checks ran (reviewers succeeded AND the synth produced output). The
+manifest / findings surfacing of these results lives in the round-manifest +
+findings_md + run_summary writers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from syncade.synthesis import has_active_blocker
+from syncade.test_runner import TestRunResult
+
+from ._atomic import atomic_write_text
+from ._validation import _validate_reviewer_filename_basename
+
+if TYPE_CHECKING:
+    from syncade.synthesizer import SynthesizerResult
+
+
+@dataclass(frozen=True)
+class CheckArtifactPaths:
+    """Where one mechanical check's artifacts land on disk.
+
+    All paths are absolute and rooted at ``<round_dir>``. ``name`` is the
+    check's name (a validated plain basename) so a consumer can map the files
+    back to the configured check without re-deriving the layout convention.
+    """
+
+    name: str
+    stdout: Path
+    stderr: Path
+    exit_code: Path
+
+
+def persist_check_result(
+    round_dir: Path,
+    check_result: TestRunResult,
+) -> CheckArtifactPaths:
+    """Write one check's outputs to
+    ``<round_dir>/<name>.check.{stdout,stderr,exit-code.txt}``.
+
+    Mirrors :func:`persist_test_run_result`; the ``.check.`` infix groups the
+    files and keeps them distinct from the per-reviewer and test-run artifacts.
+    The check name is a validated plain basename (rejected at config-load
+    otherwise); this re-validates defensively before using it as a filename so
+    a check name can never escape ``round_dir``.
+
+    Args:
+        round_dir: The round directory to write into (must already exist).
+        check_result: One :class:`~syncade.test_runner.TestRunResult`
+            populated with mechanical-check ``name`` and ``severity``.
+
+    Returns:
+        :class:`CheckArtifactPaths` naming all three written files.
+
+    Raises:
+        FileNotFoundError: If ``round_dir`` does not exist.
+    """
+    _require_check_metadata(check_result)
+    _validate_reviewer_filename_basename(check_result.name)
+    if not round_dir.is_dir():
+        raise FileNotFoundError(f"round_dir does not exist: {round_dir}")
+
+    base = check_result.name
+    stdout_path = round_dir / f"{base}.check.stdout"
+    stderr_path = round_dir / f"{base}.check.stderr"
+    exit_code_path = round_dir / f"{base}.check.exit-code.txt"
+
+    atomic_write_text(stdout_path, check_result.stdout)
+    atomic_write_text(stderr_path, check_result.stderr)
+    atomic_write_text(exit_code_path, f"{check_result.exit_code}\n")
+
+    return CheckArtifactPaths(
+        name=base,
+        stdout=stdout_path,
+        stderr=stderr_path,
+        exit_code=exit_code_path,
+    )
+
+
+_STATUS_LABEL = {"passed": "PASS", "failed": "FAIL", "subprocess_error": "ERROR"}
+
+
+def render_checks_section(check_results: list[TestRunResult]) -> list[str]:
+    """Render the ``## Mechanical checks`` section (findings.md / summary.md) as
+    a list of lines, or ``[]`` when there are no checks.
+
+    Advisory failures are tagged ``(advisory — non-blocking)`` and counted in a
+    trailing note; blocking failures read plainly (they drove the verdict). A
+    failing/erroring check links its captured output files.
+    """
+    if not check_results:
+        return []
+    lines = ["## Mechanical checks", ""]
+    advisory_failures = 0
+    for c in check_results:
+        status = _STATUS_LABEL.get(c.outcome, c.outcome.upper())
+        failed = c.outcome != "passed"
+        if failed and c.severity == "advisory":
+            tag = " (advisory — non-blocking)"
+            advisory_failures += 1
+        elif failed:
+            tag = " (blocking)"
+        else:
+            tag = ""
+        lines.append(f"- **{c.name}** ({c.severity}): {status} — exit {c.exit_code}{tag}  ")
+        if failed:
+            lines.append(
+                f"  Output: [{c.name}.check.stdout]({c.name}.check.stdout) | "
+                f"[{c.name}.check.stderr]({c.name}.check.stderr)"
+            )
+    if advisory_failures:
+        noun = "check" if advisory_failures == 1 else "checks"
+        lines.append("")
+        lines.append(f"Advisory: {advisory_failures} mechanical {noun} failed (non-blocking).")
+    lines.append("")
+    return lines
+
+
+def _require_check_metadata(check_result: TestRunResult) -> None:
+    if check_result.name is None or check_result.severity is None:
+        raise ValueError("check result requires name and severity")
+
+
+def _check_manifest_entry(check_result: TestRunResult) -> dict[str, object]:
+    """Build one ``checks[]`` entry for the round manifest. ``blocking`` is
+    surfaced as an explicit boolean so a consumer can filter gating vs advisory
+    checks without re-deriving it from ``severity``."""
+    _require_check_metadata(check_result)
+    return {
+        "name": check_result.name,
+        "severity": check_result.severity,
+        "blocking": check_result.severity == "blocking",
+        "outcome": check_result.outcome,
+        "exit_code": check_result.exit_code,
+        "command": check_result.command,
+        "duration_seconds": check_result.duration_seconds,
+        "stdout_path": f"{check_result.name}.check.stdout",
+        "stderr_path": f"{check_result.name}.check.stderr",
+        "exit_code_path": f"{check_result.name}.check.exit-code.txt",
+        "error_type": (
+            type(check_result.error).__name__ if check_result.error is not None else None
+        ),
+    }
+
+
+# check-aware Next-steps for the per-round summary.md.
+# When a BLOCKING mechanical check (not a reviewer / synth / test phase)
+# drove the round's exit code, the generic per-exit-code guidance points
+# the operator at the wrong artifact ("read the active synth blockers" /
+# "a reviewer subprocess failed"). These variants point at the check.
+_NEXT_STEPS_30_CHECK_FAILED = (
+    "- A blocking mechanical check FAILED (the cold synthesizer was\n"
+    "  clean — no consolidated blockers). The `## Mechanical checks`\n"
+    "  section of `findings.md` names which check failed; open that\n"
+    "  check's `<name>.check.stdout` / `<name>.check.stderr` for its\n"
+    "  output. This is a NO-SHIP from the mechanical lane, not a\n"
+    "  reviewer / synth finding — `findings.md`'s consolidated review\n"
+    "  has zero active blockers."
+)
+_NEXT_STEPS_40_CHECK_SUBPROCESS = (
+    "- A blocking mechanical check's subprocess could not run to\n"
+    "  completion (every reviewer succeeded; the synthesizer\n"
+    "  succeeded). `findings.md` renders Verdict: ABORT — the check\n"
+    "  signal is indeterminate until the environment problem is\n"
+    "  fixed. Read the failing check's `<name>.check.stderr` and the\n"
+    "  manifest's `checks[].error_type`; common shapes are a missing\n"
+    "  binary (the check `command` references a tool not on PATH in\n"
+    "  the check worktree) or a timeout."
+)
+
+
+def check_aware_next_steps(
+    exit_code: int,
+    synth_result: SynthesizerResult | None,
+    test_result: TestRunResult | None,
+    check_results: list[TestRunResult] | None,
+) -> str | None:
+    """Return a check-driven Next-steps override for the per-round
+    summary.md, or ``None`` when the round's failure was NOT driven by a
+    blocking mechanical check (the caller keeps its normal routing).
+
+    Fires only for the two check-driven exits — a failing blocking check
+    on a synth-clean round (exit 30) and a blocking-check subprocess
+    error (exit 40) — and only when no reviewer / synth / test phase is
+    the real cause. Every zero-check round passes ``check_results``
+    empty and gets ``None`` here, so the generic guidance stays
+    byte-identical everywhere else.
+    """
+    checks = check_results or []
+    blocking_failed = any(c.severity == "blocking" and c.outcome == "failed" for c in checks)
+    blocking_errored = any(
+        c.severity == "blocking" and c.outcome == "subprocess_error" for c in checks
+    )
+    if exit_code == 40 and blocking_errored:
+        synth_failed = synth_result is not None and synth_result.error is not None
+        test_errored = test_result is not None and test_result.outcome == "subprocess_error"
+        if not synth_failed and not test_errored:
+            return _NEXT_STEPS_40_CHECK_SUBPROCESS
+    if exit_code == 30 and blocking_failed:
+        test_failed = test_result is not None and test_result.outcome == "failed"
+        synth_clean = (
+            synth_result is not None
+            and synth_result.output is not None
+            and not has_active_blocker(synth_result.output)
+        )
+        if synth_clean and not test_failed:
+            return _NEXT_STEPS_30_CHECK_FAILED
+    return None
+
+
+# validation fix (codex blocker): the LOOP-summary equivalent of the
+# per-round check-aware next-steps. When the FINAL round's NO-SHIP was a
+# synth-clean blocking-check failure, loop-summary.md points at the check
+# instead of the termination_reason-keyed text (e.g. max_rounds_reached's
+# "read the remaining active blockers"), which misleads — there are none.
+_LOOP_NEXT_STEPS_CHECK_FAILURE = (
+    "- The final round was a NO-SHIP driven by a failing BLOCKING mechanical "
+    "check, not by the synthesizer's consolidated findings (which were clean). "
+    "Read the `## Mechanical checks` section of that round's `findings.md` to "
+    "see which check failed, then open its `<name>.check.stdout` / "
+    "`<name>.check.stderr` in the round directory. There are NO active synth "
+    "blockers here — the mechanical lane is the NO-SHIP signal."
+)
+
+
+def _final_round_blocking_check_failure(rounds: list) -> bool:
+    """True when the LAST round's NO-SHIP was a synth-clean BLOCKING
+    mechanical-check failure (duck-typed over ``RoundResult``). Drives the
+    loop-summary next-steps override above."""
+    if not rounds:
+        return False
+    r = rounds[-1]
+    synth = r.synth_result
+    synth_clean = (
+        synth is not None and synth.output is not None and not has_active_blocker(synth.output)
+    )
+    if not synth_clean:
+        return False
+    if r.test_result is not None and r.test_result.outcome == "failed":
+        return False
+    return any(c.severity == "blocking" and c.outcome == "failed" for c in r.check_results)

syncade/persistence/decision_needed.py

@@ -0,0 +1,289 @@
+"""Decision-needed checkpoint persistence.
+
+When a NO-SHIP round's producer escalates a finding as an operator
+decision (see :mod:`syncade.producer_escalation`) AND the loop honors
+that escalation, the loop terminator writes
+``<run_dir>/decision-needed.md`` — the operator-facing checkpoint
+carrying the producer's case (the finding, the decision to make, the
+concrete options, the reproduction-backed rationale) and the
+record-a-decision-then-resume instructions. Since the escalation
+is honored (and this file written) ONLY when its ``finding_indices``
+cover every active blocker in the round; an escalation that leaves a
+blocker uncovered is treated as a producer stall (exit 30) and this
+file is not written.
+
+The companion is ``decision.txt``: the operator writes their decision
+into ``<run_dir>/decision.txt`` and runs ``syncade --resume <run-id>``;
+the resumed round's producer receives that text. The filename constant
+and the reader live here so the writer (which tells the operator where to
+write) and the reader (resume) share one source of truth.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from syncade.producer_escalation import ProducerEscalation
+
+from ._atomic import atomic_write_text
+
+if TYPE_CHECKING:
+    from syncade.test_runner import TestRunResult
+
+DECISION_NEEDED_FILENAME = "decision-needed.md"
+"""The operator-facing escalation checkpoint, at the run root."""
+
+OPERATOR_DECISION_FILENAME = "decision.txt"
+"""Where the operator records the decision the resume reads back. Plain
+text (the producer receives it verbatim). Single source of truth shared
+by :func:`persist_decision_needed` (which instructs the operator) and
+:func:`read_operator_decision` (which the resume path calls)."""
+
+
+def persist_decision_needed(
+    run_dir: Path,
+    *,
+    round_idx: int,
+    escalation: ProducerEscalation,
+    run_id: str,
+    branch_advanced: bool = False,
+    check_results: list[TestRunResult] | None = None,
+) -> Path:
+    """Write ``<run_dir>/decision-needed.md`` for an honored escalation.
+
+    The loop terminator calls this only when the round's producer
+    escalated AND the escalation's ``finding_indices`` covered every
+    active blocker; a non-honored escalation maps to a producer
+    stall (exit 30) and never reaches this writer.
+
+    Args:
+        run_dir: Top-level run directory (``<repo>/.syncade/runs/<id>/``).
+        round_idx: The 0-indexed round whose producer escalated.
+        escalation: The structured :class:`ProducerEscalation` the
+            producer emitted.
+        run_id: The run-id, for the heading + the resume command.
+        branch_advanced: Whether an EARLIER round in this run already
+            fast-forwarded the branch. Passed in from the loop's cumulative
+            state rather than assumed: a multi-round run can reach this
+            state after a prior producer round landed commits.
+        check_results: The mechanical-check results from this round, if any.
+            Failing blocking checks are listed in the document so the operator
+            knows that resuming addresses the producer question but the checks
+            will still rerun and must also pass.
+
+    Returns:
+        Path of the written ``decision-needed.md``.
+
+    Raises:
+        FileNotFoundError: If ``run_dir`` does not exist.
+    """
+    if not run_dir.is_dir():
+        raise FileNotFoundError(f"run_dir does not exist: {run_dir}")
+
+    _branch_note = (
+        "**Your branch was already advanced** by an earlier round in this "
+        "run — producer commits from that round are on it. Nothing was "
+        "advanced for THIS round."
+        if branch_advanced
+        else "No branch was advanced."
+    )
+    lines: list[str] = [
+        f"# Decision needed — Syncade run {run_id}",
+        "",
+        f"The producer escalated a finding in round {round_idx} that it "
+        "determined is an **operator decision** — a spec/design conflict it "
+        "cannot resolve in code without a human ruling, not a defect it can "
+        f"fix. The loop checkpointed and terminated (exit 10); {_branch_note} "
+        "The mechanical verdict is unchanged (still NO-SHIP).",
+        "",
+        "## The finding",
+        "",
+        *_md_text_block_lines(escalation.finding),
+        "",
+        "## The decision you must make",
+        "",
+        *_md_text_block_lines(escalation.decision),
+        "",
+        "## Options",
+        "",
+    ]
+    for idx, option in enumerate(escalation.options, start=1):
+        lines.extend([f"### Option {idx}", "", *_md_text_block_lines(option), ""])
+    lines += [
+        "## The producer's rationale (reproduction-backed)",
+        "",
+        *_md_text_block_lines(escalation.rationale),
+        "",
+    ]
+
+    failing_blocking_checks = [
+        c for c in (check_results or []) if c.severity == "blocking" and c.outcome != "passed"
+    ]
+    if failing_blocking_checks:
+        lines += [
+            "## Co-failing blocking checks",
+            "",
+            "These blocking mechanical checks also failed this round. Resuming "
+            "addresses the producer decision above, but the checks rerun on "
+            "resume and must also pass before the round can SHIP:",
+            "",
+        ]
+        for c in failing_blocking_checks:
+            status = "FAIL" if c.outcome == "failed" else "ERROR"
+            lines.append(f"- **{c.name}**: {status} (exit {c.exit_code})")
+            if c.name:
+                lines.append(
+                    f"  Output: `{c.name}.check.stdout` / `{c.name}.check.stderr` "
+                    f"in `round-{round_idx}/`"
+                )
+        lines.append("")
+
+    lines += [
+        "## How to continue",
+        "",
+        f"1. Decide, then write your decision (the option you chose plus any "
+        f"specifics the producer needs) into `{OPERATOR_DECISION_FILENAME}` in "
+        "this run directory.",
+        f"2. Resume: `syncade --resume {run_id}`. The escalated round re-runs "
+        "with your decision fed to the producer. (Resume refuses if "
+        f"`{OPERATOR_DECISION_FILENAME}` is missing or empty.)",
+        "",
+    ]
+
+    path = run_dir / DECISION_NEEDED_FILENAME
+    atomic_write_text(path, "\n".join(lines))
+    return path
+
+
+def _md_text_block_lines(text: str) -> list[str]:
+    max_run = 0
+    current = 0
+    for ch in text:
+        if ch == "`":
+            current += 1
+            if current > max_run:
+                max_run = current
+        else:
+            current = 0
+    fence = "`" * max(4, max_run + 1)
+    return [f"{fence}text", text.rstrip("\n"), fence]
+
+
+def read_operator_decision(run_dir: Path) -> str | None:
+    """Return the operator's recorded decision from
+    ``<run_dir>/decision.txt``, or ``None`` when the file is absent or
+    blank (whitespace-only counts as absent — an empty file is not a
+    decision). Stripped of surrounding whitespace.
+    """
+    decision_path = run_dir / OPERATOR_DECISION_FILENAME
+    if not decision_path.is_file():
+        return None
+    text = decision_path.read_text(encoding="utf-8").strip()
+    return text or None
+
+
+def persist_deactivated_blockers_decision_needed(
+    run_dir: Path,
+    *,
+    round_idx: int,
+    run_id: str,
+    deactivated: list[tuple[str, str, str]],
+    branch_advanced: bool = False,
+) -> Path:
+    """Write ``decision-needed.md`` for a PR-h-01 increment-D escalation.
+
+    The other escalation in this module is the producer's: it argues a case and
+    asks the operator to choose. This one has no advocate. Two or more distinct
+    reviewers independently raised blockers, the synthesizer ruled every one of
+    them out, and nothing checked whether those rulings were right — so the
+    round is neither a defensible SHIP nor a mechanical NO-SHIP.
+
+    The document's whole job is to put the reviewers' own words in front of the
+    operator next to what the synthesizer did with them, because that
+    comparison is the decision. Quotes are verbatim: provenance text is
+    cross-checked against the source reviewer's finding
+    (``syncade.synthesizer.validation``), so what is printed here is what the
+    reviewer actually wrote.
+
+    Args:
+        run_dir: Top-level run directory (``<repo>/.syncade/runs/<id>/``).
+        round_idx: The 0-indexed round that escalated.
+        run_id: The run-id, for the heading.
+        deactivated: ``(reviewer_name, verbatim_finding_text, disposition)``
+            per deactivated source blocker, where ``disposition`` describes how
+            the synthesizer removed it (e.g. ``dismissed: <rationale>``).
+        branch_advanced: Whether an EARLIER round in this run already
+            fast-forwarded the branch. Passed in rather than assumed: a
+            multi-round run can reach this state after a producer round
+            landed commits, and telling an operator their branch is untouched
+            when it is not is exactly the kind of wrong that gets acted on.
+
+    Returns:
+        Path of the written ``decision-needed.md``.
+
+    Raises:
+        FileNotFoundError: If ``run_dir`` does not exist.
+    """
+    if not run_dir.is_dir():
+        raise FileNotFoundError(f"run_dir does not exist: {run_dir}")
+
+    reviewers = sorted({name for name, _, _ in deactivated})
+    lines: list[str] = [
+        f"# Decision needed — Syncade run {run_id}",
+        "",
+        f"In round {round_idx}, **{len(reviewers)} independent reviewers "
+        f"({', '.join(reviewers)}) each raised at least one blocker, and the "
+        "synthesizer deactivated every one of them** — by dismissal, by "
+        "downgrade, or by splitting one concern into separate single-reviewer "
+        "findings it could then rule out individually.",
+        "",
+        (
+            "That may be entirely correct. But independent corroboration is the "
+            "strongest signal this tool produces, and a machine should not "
+            "discard all of it silently. The loop terminated at exit 10 rather "
+            "than reporting a SHIP it cannot justify."
+        ),
+        "",
+        (
+            "**Your branch was already advanced** by an earlier round in this "
+            "run — producer commits from that round are on it. Nothing was "
+            "advanced for THIS round."
+            if branch_advanced
+            else "No branch was advanced."
+        ),
+        "",
+        "## What each reviewer actually said",
+        "",
+        "Quoted verbatim from the reviewers' own output — not the synthesizer's restatement of it.",
+        "",
+    ]
+    for idx, (reviewer, text, disposition) in enumerate(deactivated, start=1):
+        lines.extend(
+            [
+                f"### {idx}. {reviewer} — blocker",
+                "",
+                *_md_text_block_lines(text),
+                "",
+                f"**Synthesizer's disposition:** {disposition}",
+                "",
+            ]
+        )
+    lines += [
+        "## How to continue",
+        "",
+        "Read the quotes above and decide whether the synthesizer was right.",
+        "",
+        "- **It was right** — the concerns really are false positives. This "
+        "round is a SHIP; nothing is blocking you.",
+        "- **It was wrong about any of them** — that concern is real and "
+        "unfixed. Address it and re-run.",
+        "",
+        "The full consolidated view, including each dismissal rationale in "
+        f"context, is in `round-{round_idx}/findings.md`.",
+        "",
+    ]
+
+    path = run_dir / DECISION_NEEDED_FILENAME
+    atomic_write_text(path, "\n".join(lines))
+    return path