claude-dev-env 1.29.2 → 1.30.0

package/scripts/config/groq_bugteam_config.py

@@ -111,8 +111,112 @@ If ``applied_finding_indexes`` is empty, ``updated_content`` MUST equal the
 input exactly.
 """
 
+SPEC_IMPLEMENTER_SYSTEM_PROMPT = """<groq_spec_implementer>
+
+<role>
+    Apply a Claude-authored fix-spec to a single file. Treat each spec as an executable patch instruction authored by a higher-reasoning agent that already validated the bug and decided the fix. Perform mechanical edits only. Never re-evaluate whether the finding is real, relevant, or well-scoped — Claude already decided that. Produce the patched file contents and a self-assessment of every acceptance criterion stated in the spec.
+</role>
+
+<inputs>
+    Every invocation provides exactly two inputs:
+
+    1. The current contents of one file, as a single UTF-8 string.
+
+    2. A fix-spec array targeting that file. Each spec entry has these fields:
+
+       - finding_index (int, stable across audit and fix)
+       - severity (P0 | P1 | P2)
+       - category (single letter A–J)
+       - file (relative path, must match the file being patched)
+       - target_line_start (int, 1-based, inclusive)
+       - target_line_end (int, 1-based, inclusive; equals target_line_start for single-line edits)
+       - intended_change (natural-language description of the edit)
+       - replacement_code (optional literal text to splice in; absent when Claude wanted Groq to derive the edit from intended_change + acceptance_criteria)
+       - acceptance_criteria (array of observable post-fix assertions; each is a standalone sentence a reader can check against the patched file)
+
+    Treat every field as authoritative. Accept the finding_index exactly as provided and echo it in the output.
+</inputs>
+
+<rules>
+
+<rule_1_mechanical_only>
+    Apply the spec verbatim. Skip every form of re-analysis. Only edit lines covered by target_line_start..target_line_end, plus any new lines explicitly required by intended_change (for example, adding a new import when intended_change requires the fix to import a module).
+</rule_1_mechanical_only>
+
+<rule_2_replacement_code_when_present>
+    When replacement_code is present, splice it in so the resulting file replaces lines target_line_start..target_line_end with the exact text of replacement_code. Preserve the newline character at the end of the replaced span so the file's line structure remains consistent.
+</rule_2_replacement_code_when_present>
+
+<rule_3_derive_minimally_when_replacement_absent>
+    When replacement_code is absent, implement the smallest edit that satisfies intended_change AND every acceptance_criterion. Choose the minimum number of lines within the target range required to pass the acceptance checks.
+</rule_3_derive_minimally_when_replacement_absent>
+
+<rule_4_byte_for_byte_outside_edit>
+    Preserve every byte outside the edited region: leading whitespace, trailing whitespace, trailing newline presence or absence, indent style (tabs versus spaces), blank-line placement, import order, existing comment placement, and line-ending style. Read the input file's trailing-newline state and reproduce it exactly in the output.
+</rule_4_byte_for_byte_outside_edit>
+
+<rule_5_no_stylistic_additions>
+    Add zero new comments, docstrings, type hints, or defensive code unless the spec explicitly requires one. Reject every impulse to refactor, rename, reorder, or "clean up" nearby code. Keep the diff as narrow as the spec allows.
+</rule_5_no_stylistic_additions>
+
+<rule_6_never_invent_authorization>
+    Only apply edits covered by a spec entry. When a spec says "replace line 42" and line 42 does not exist or is empty, skip the finding with a one-line reason. Never fabricate lines Claude did not authorize. Never generalize the spec to adjacent lines.
+</rule_6_never_invent_authorization>
+
+<rule_7_acceptance_self_check>
+    For every finding marked applied, evaluate each acceptance_criterion against the patched file contents. Record the result in acceptance_checks with met=true or met=false. When any acceptance_criterion evaluates to met=false for a given finding_index, move that finding_index out of applied_finding_indexes and into skipped with a reason naming the failing criterion.
+</rule_7_acceptance_self_check>
+
+</rules>
+
+<output_schema>
+    Respond with JSON only. Emit zero prose outside the JSON object. The object has exactly these top-level keys:
+
+        {
+          "updated_content": "full patched file contents as a single string",
+          "applied_finding_indexes": [0, 2],
+          "skipped": [
+            {"finding_index": 1, "reason": "one-line reason"}
+          ],
+          "acceptance_checks": [
+            {"finding_index": 0, "criterion": "verbatim text from the spec", "met": true}
+          ]
+        }
+
+    Ensure updated_content contains the full patched file — never a diff, never a fragment, never a summary. When applied_finding_indexes is empty, ensure updated_content equals the input byte-for-byte. Copy each acceptance_criterion string verbatim from the spec into the corresponding acceptance_checks entry.
+</output_schema>
+
+<failure_mode>
+    Skip the finding and preserve the file unchanged when any of these hold:
+
+    - target_line_start or target_line_end points outside the file.
+    - target_line_start > target_line_end.
+    - replacement_code contains a syntax error detectable on inspection.
+    - acceptance_criteria contradict the current file state in a way no valid patch can satisfy.
+    - intended_change and acceptance_criteria disagree with each other.
+    - Applying the spec would require editing lines outside target_line_start..target_line_end AND intended_change does not explicitly authorize that wider scope.
+
+    In every skip case, set the corresponding entry in skipped with a one-line reason naming the exact condition that failed. Return updated_content equal to the input when every finding is skipped. Never guess. Never partially apply. Never emit prose explanations outside the JSON object.
+</failure_mode>
+
+</groq_spec_implementer>
+"""
+
 JSON_INDENT_SPACES = 2
 PIPELINE_FAILURE_EXIT_CODE = 2
 
 TEXT_CLAMP_HEAD_PARTS = 1
 TEXT_CLAMP_TOTAL_PARTS = 2
+
+SPEC_MODE_FLAG = "--mode"
+SPEC_MODE_VALUE = "spec"
+MISSING_API_KEY_ERROR = (
+    "GROQ_API_KEY not set in environment; create packages/claude-dev-env/.env "
+    "from packages/claude-dev-env/.env.example (gitignored) or export GROQ_API_KEY"
+)
+
+REQUIRED_GROQ_BUGTEAM_ATTRIBUTES: tuple[str, ...] = (
+    "call_groq_with_fallback",
+    "parse_json_object",
+    "preserve_trailing_newline",
+)

package/scripts/config/test_groq_bugteam_config.py

@@ -70,3 +70,14 @@ def test_fix_budget_exceeds_audit_budget():
         groq_bugteam_config.GROQ_FIX_MAX_COMPLETION_TOKENS
         > groq_bugteam_config.GROQ_AUDIT_MAX_COMPLETION_TOKENS
     )
+
+
+def test_spec_implementer_prompt_is_distinct_from_fix_prompt():
+    assert (
+        groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
+        != groq_bugteam_config.FIX_SYSTEM_PROMPT
+    )
+
+
+def test_spec_implementer_prompt_contains_mechanical_discipline_marker():
+    assert "mechanical edits only" in groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT

package/scripts/config/test_spec_implementer_prompt.py

@@ -0,0 +1,36 @@
+"""Existence and coherence check for SPEC_IMPLEMENTER_SYSTEM_PROMPT."""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+
+def _load_config_module():
+    module_path = pathlib.Path(__file__).parent / "groq_bugteam_config.py"
+    module_spec = importlib.util.spec_from_file_location(
+        "groq_bugteam_config_spec", module_path
+    )
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    sys.modules["groq_bugteam_config_spec"] = loaded_module
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+groq_bugteam_config = _load_config_module()
+
+
+def test_spec_implementer_prompt_exists():
+    assert hasattr(groq_bugteam_config, "SPEC_IMPLEMENTER_SYSTEM_PROMPT")
+
+
+def test_spec_implementer_prompt_is_non_empty_string():
+    prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
+    assert isinstance(prompt_text, str)
+    assert len(prompt_text.strip()) > 0
+
+
+def test_spec_implementer_prompt_declares_mechanical_only_discipline():
+    prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
+    assert "mechanical edits only" in prompt_text

package/scripts/groq_bugteam.README.md

@@ -58,6 +58,7 @@ The caller posts the review to GitHub. This script does not touch the GitHub API
 ## Required environment
 
 - `GROQ_API_KEY` — from https://console.groq.com/keys. Free tier is enough for a single PR.
+- **Local file (preferred):** copy `packages/claude-dev-env/.env.example` to `packages/claude-dev-env/.env`, set `GROQ_API_KEY=...` inside the copy. That path is gitignored; `groq_bugteam.py` loads it on startup when the file exists (without overriding variables already exported in your shell).
 - `git` on PATH, configured to push to the target remote.
 - Python 3.10+. No external deps (stdlib `urllib.request` only).
 
@@ -65,6 +66,7 @@ The caller posts the review to GitHub. This script does not touch the GitHub API
 
 ```bash
 # Assumes you already have a git worktree checked out to the PR head branch.
+# Either use packages/claude-dev-env/.env (see Required environment) or:
 export GROQ_API_KEY=gsk_...
 
 python3 - <<'EOF' | python3 packages/claude-dev-env/scripts/groq_bugteam.py

package/scripts/groq_bugteam.py

@@ -7,7 +7,9 @@ team, no 10-loop convergence: one audit call, one fix call, one commit and
 push per PR.
 
 Stateless and PII-free. All GitHub identifiers arrive on stdin as JSON;
-``GROQ_API_KEY`` is read from the environment. Output is JSON on stdout.
+``GROQ_API_KEY`` is read from the environment after loading
+``packages/claude-dev-env/.env`` when that file exists (gitignored; see
+``.env.example``). Output is JSON on stdout.
 
 Pipeline (per invocation):
   1. Read PR metadata, unified diff, file contents from stdin.
@@ -74,6 +76,7 @@ from config.groq_bugteam_config import (
     MAXIMUM_DIFF_CHARACTERS,
     MAXIMUM_FILE_CONTENT_CHARACTERS,
     MAXIMUM_FINDINGS_PER_PR,
+    MISSING_API_KEY_ERROR,
     NO_FINDINGS_REVIEW_BODY,
     PIPELINE_FAILURE_EXIT_CODE,
     REVIEW_BODY_HEADER_TEMPLATE,
@@ -81,6 +84,9 @@ from config.groq_bugteam_config import (
     TEXT_CLAMP_TOTAL_PARTS,
 )
 
+from groq_bugteam_dotenv import load_claude_dev_env_dotenv_file
+
+
 @dataclass(frozen=True)
 class GroqCallResult:
     content: str
@@ -98,12 +104,21 @@ def should_skip_to_next_model(error: urllib.error.HTTPError) -> bool:
 def clamp_text(text: str, max_characters: int) -> str:
     if len(text) <= max_characters:
         return text
-    head_length = max_characters * TEXT_CLAMP_HEAD_PARTS // TEXT_CLAMP_TOTAL_PARTS
-    tail_length = max_characters - head_length
+    truncated_count = len(text)
+    while True:
+        truncation_marker = f"\n\n... [truncated {truncated_count} chars] ...\n\n"
+        if len(truncation_marker) >= max_characters:
+            return text[:max_characters]
+        content_budget = max_characters - len(truncation_marker)
+        refined_truncated_count = len(text) - content_budget
+        if refined_truncated_count == truncated_count:
+            break
+        truncated_count = refined_truncated_count
+    head_length = content_budget * TEXT_CLAMP_HEAD_PARTS // TEXT_CLAMP_TOTAL_PARTS
+    tail_length = content_budget - head_length
     head = text[:head_length]
-    tail = text[-tail_length:]
-    truncated_count = len(text) - max_characters
-    return f"{head}\n\n... [truncated {truncated_count} chars] ...\n\n{tail}"
+    tail = text[-tail_length:] if tail_length else ""
+    return f"{head}{truncation_marker}{tail}"
 
 
 def post_to_groq(
@@ -160,7 +175,9 @@ def call_groq_with_fallback(
                 if should_skip_to_next_model(http_error):
                     break
                 if not is_recoverable_http_error(http_error):
-                    break
+                    raise RuntimeError(
+                        f"Groq request failed with non-recoverable HTTP error: {http_error}"
+                    ) from http_error
             except (
                 urllib.error.URLError,
                 TimeoutError,
@@ -181,6 +198,30 @@ def parse_json_object(raw_text: str) -> dict:
     return json.loads(match.group(0))
 
 
+def coerce_indexes_to_int_set(raw_indexes: list | None) -> set[int]:
+    coerced: set[int] = set()
+    for each_raw_index in raw_indexes or []:
+        try:
+            coerced.add(int(each_raw_index))
+        except (TypeError, ValueError):
+            continue
+    return coerced
+
+
+def coerce_skipped_entries(raw_skipped: list | None) -> dict[int, str]:
+    coerced: dict[int, str] = {}
+    for each_entry in raw_skipped or []:
+        if not isinstance(each_entry, dict):
+            continue
+        try:
+            finding_index = int(each_entry.get("finding_index"))
+        except (TypeError, ValueError):
+            continue
+        raw_reason = each_entry.get("reason", "")
+        coerced[finding_index] = "" if raw_reason is None else str(raw_reason)
+    return coerced
+
+
 def normalize_findings(raw_findings: list, files_content: dict) -> list:
     normalized = []
     for each_raw in raw_findings:
@@ -248,7 +289,10 @@ def should_write_fixed_file(
 def is_safe_relative_path(each_path: str) -> bool:
     if os.path.isabs(each_path):
         return False
-    if each_path.startswith(("/", "\\")):
+    posix_style_each_path = each_path.replace("\\", "/")
+    if posix_style_each_path.startswith("/"):
+        return False
+    if each_path.startswith("\\"):
         return False
     normalized = os.path.normpath(each_path)
     if normalized.startswith(".." + os.sep) or normalized == "..":
@@ -436,9 +480,10 @@ def build_review_body(
 
 
 def run_pipeline(input_data: dict) -> dict:
+    load_claude_dev_env_dotenv_file()
     api_key = os.environ.get("GROQ_API_KEY", "").strip()
     if not api_key:
-        return {"error": "GROQ_API_KEY not set in environment"}
+        return {"error": MISSING_API_KEY_ERROR}
 
     diff_text = input_data.get("diff", "")
     files_content = input_data.get("files_content", {})
@@ -477,11 +522,10 @@ def run_pipeline(input_data: dict) -> dict:
                     )
                 continue
             raw_updated_content = fix_result.get("updated_content", current_content)
-            applied_indexes = set(fix_result.get("applied_finding_indexes", []))
-            skipped_entries = {
-                each_skipped["finding_index"]: each_skipped.get("reason", "")
-                for each_skipped in fix_result.get("skipped", [])
-            }
+            applied_indexes = coerce_indexes_to_int_set(
+                fix_result.get("applied_finding_indexes", [])
+            )
+            skipped_entries = coerce_skipped_entries(fix_result.get("skipped", []))
             updated_content = preserve_trailing_newline(current_content, raw_updated_content)
             content_changed = updated_content != current_content
             if should_write_fixed_file(applied_indexes, updated_content, current_content):
@@ -565,7 +609,7 @@ def run_pipeline(input_data: dict) -> dict:
     }
 
 
-def main() -> None:
+def run_default_pipeline_main() -> None:
     try:
         stdin_text = sys.stdin.read()
         input_data = json.loads(stdin_text)
@@ -584,5 +628,20 @@ def main() -> None:
         sys.exit(PIPELINE_FAILURE_EXIT_CODE)
 
 
+from groq_bugteam_spec import (
+    apply_fix_from_spec,
+    is_spec_mode_invocation,
+    run_spec_mode_main,
+)
+
+
+def main() -> None:
+    load_claude_dev_env_dotenv_file()
+    if is_spec_mode_invocation(sys.argv[1:]):
+        run_spec_mode_main()
+        return
+    run_default_pipeline_main()
+
+
 if __name__ == "__main__":
     main()

package/scripts/groq_bugteam_dotenv.py

@@ -0,0 +1,40 @@
+"""Load ``packages/claude-dev-env/.env`` into ``os.environ`` for local Groq use.
+
+Does not override variables already set in the process environment. Uses a
+minimal KEY=value parser (stdlib only) so ``groq_bugteam.py`` stays dependency
+free.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def claude_dev_env_dotenv_path() -> Path:
+    """Absolute path to the gitignored ``.env`` beside ``groq_bugteam.py``'s package."""
+    return Path(__file__).resolve().parent.parent / ".env"
+
+
+def load_claude_dev_env_dotenv_file(dotenv_path: Path | None = None) -> None:
+    """Apply KEY=value lines from the dotenv file when the file exists."""
+    resolved_path = dotenv_path if dotenv_path is not None else claude_dev_env_dotenv_path()
+    if not resolved_path.is_file():
+        return
+    raw_text = resolved_path.read_text(encoding="utf-8")
+    for each_line in raw_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line or stripped_line.startswith("#"):
+            continue
+        if stripped_line.startswith("export "):
+            stripped_line = stripped_line.removeprefix("export ").strip()
+        if "=" not in stripped_line:
+            continue
+        key_part, _, value_part = stripped_line.partition("=")
+        key_name = key_part.strip()
+        value_text = value_part.strip()
+        if len(value_text) >= 2 and value_text[0] == value_text[-1] and value_text[0] in "\"'":
+            value_text = value_text[1:-1]
+        if not key_name or key_name in os.environ:
+            continue
+        os.environ[key_name] = value_text

package/scripts/groq_bugteam_spec.py

@@ -0,0 +1,226 @@
+"""Spec-mode implementer for groq_bugteam.
+
+Splits the Claude-authored fix-spec pipeline into its own module so
+groq_bugteam.py can keep the single-shot audit+fix pipeline isolated
+from the mechanical patch applier. Both entrypoints share the same
+HTTP client (``call_groq_with_fallback``), string helpers
+(``parse_json_object``, ``preserve_trailing_newline``), and config
+constants via the parent groq_bugteam module, resolved at call time
+through resolve_groq_bugteam_module(). That resolver handles both
+contexts: tests register the parent as ``sys.modules["groq_bugteam"]``
+via spec_from_file_location, while a direct CLI invocation of
+``python groq_bugteam.py --mode spec`` runs the parent as
+``sys.modules["__main__"]``. The resolver also keeps tests able to
+monkeypatch ``groq_bugteam.call_groq_with_fallback`` and have the
+patch reach this module.
+
+This module is imported from the bottom of groq_bugteam.py so
+groq_bugteam.apply_fix_from_spec remains attribute-accessible to
+existing callers and tests. The module must not import groq_bugteam
+at its top level -- that would close the cycle during CLI startup
+and raise ImportError before groq_bugteam_spec finishes defining its
+public names.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from types import ModuleType
+
+from config.groq_bugteam_config import (
+    GROQ_FIX_MAX_COMPLETION_TOKENS,
+    GROQ_FIX_TEMPERATURE,
+    JSON_INDENT_SPACES,
+    MISSING_API_KEY_ERROR,
+    PIPELINE_FAILURE_EXIT_CODE,
+    REQUIRED_GROQ_BUGTEAM_ATTRIBUTES,
+    SPEC_IMPLEMENTER_SYSTEM_PROMPT,
+    SPEC_MODE_FLAG,
+    SPEC_MODE_VALUE,
+)
+
+from groq_bugteam_dotenv import load_claude_dev_env_dotenv_file
+
+
+def extract_failing_criteria_by_finding(
+    acceptance_checks: list[dict],
+) -> dict[int, list[str]]:
+    failing_by_finding: dict[int, list[str]] = {}
+    for each_check in acceptance_checks:
+        if each_check.get("met"):
+            continue
+        each_finding_index = each_check.get("finding_index")
+        if not isinstance(each_finding_index, int):
+            continue
+        each_criterion_text = each_check.get("criterion", "")
+        failing_by_finding.setdefault(each_finding_index, []).append(
+            each_criterion_text
+        )
+    return failing_by_finding
+
+
+def demote_findings_with_failing_criteria(
+    applied_finding_indexes: list[int],
+    skipped_entries: list[dict],
+    failing_criteria_by_finding: dict[int, list[str]],
+) -> tuple[list[int], list[dict]]:
+    demoted_applied = [
+        each_index
+        for each_index in applied_finding_indexes
+        if each_index not in failing_criteria_by_finding
+    ]
+    already_skipped_indexes = {
+        each.get("finding_index")
+        for each in skipped_entries
+        if each.get("finding_index") is not None
+    }
+    augmented_skipped = list(skipped_entries)
+    for (
+        each_finding_index,
+        each_failing_criteria,
+    ) in failing_criteria_by_finding.items():
+        if each_finding_index in already_skipped_indexes:
+            continue
+        reason_text = "; ".join(each_failing_criteria)
+        augmented_skipped.append(
+            {"finding_index": each_finding_index, "reason": reason_text}
+        )
+    return demoted_applied, augmented_skipped
+
+
+def build_spec_user_message(spec_list: list[dict], current_content: str) -> str:
+    payload = {"spec": spec_list, "current_content": current_content}
+    return json.dumps(payload, indent=JSON_INDENT_SPACES)
+
+
+def find_missing_required_attributes(candidate_module: ModuleType) -> list[str]:
+    return [
+        each_attribute_name
+        for each_attribute_name in REQUIRED_GROQ_BUGTEAM_ATTRIBUTES
+        if not hasattr(candidate_module, each_attribute_name)
+    ]
+
+
+def resolve_groq_bugteam_module() -> ModuleType:
+    registered_module = sys.modules.get("groq_bugteam")
+    if registered_module is not None and not find_missing_required_attributes(
+        registered_module
+    ):
+        return registered_module
+    main_module = sys.modules.get("__main__")
+    if main_module is not None and not find_missing_required_attributes(main_module):
+        return main_module
+    stub_module = registered_module if registered_module is not None else main_module
+    if stub_module is not None:
+        missing_attributes = find_missing_required_attributes(stub_module)
+        raise RuntimeError(
+            "groq_bugteam module found but missing required attributes: "
+            + ", ".join(missing_attributes)
+        )
+    raise RuntimeError(
+        "groq_bugteam module not found in sys.modules; "
+        "groq_bugteam_spec must be invoked from a context where "
+        "groq_bugteam is the parent module (test loader or CLI)."
+    )
+
+
+def coerce_to_list(candidate_value: object) -> list:
+    if isinstance(candidate_value, list):
+        return candidate_value
+    return []
+
+
+def coerce_to_string_or_fallback(
+    candidate_value: object, fallback_value: str
+) -> str:
+    if isinstance(candidate_value, str):
+        return candidate_value
+    return fallback_value
+
+
+def apply_fix_from_spec(spec_list: list[dict], current_content: str) -> dict:
+    load_claude_dev_env_dotenv_file()
+    api_key = os.environ.get("GROQ_API_KEY", "").strip()
+    if not api_key:
+        raise RuntimeError(MISSING_API_KEY_ERROR)
+
+    groq_bugteam_module = resolve_groq_bugteam_module()
+    user_message = build_spec_user_message(spec_list, current_content)
+    groq_result = groq_bugteam_module.call_groq_with_fallback(
+        api_key,
+        messages=[
+            {"role": "system", "content": SPEC_IMPLEMENTER_SYSTEM_PROMPT},
+            {"role": "user", "content": user_message},
+        ],
+        temperature=GROQ_FIX_TEMPERATURE,
+        max_completion_tokens=GROQ_FIX_MAX_COMPLETION_TOKENS,
+    )
+    parsed_response = groq_bugteam_module.parse_json_object(groq_result.content)
+
+    raw_updated_content = coerce_to_string_or_fallback(
+        parsed_response.get("updated_content"), current_content
+    )
+    applied_finding_indexes = coerce_to_list(
+        parsed_response.get("applied_finding_indexes")
+    )
+    skipped_entries = coerce_to_list(parsed_response.get("skipped"))
+    acceptance_checks = coerce_to_list(parsed_response.get("acceptance_checks"))
+
+    failing_criteria_by_finding = extract_failing_criteria_by_finding(acceptance_checks)
+    demoted_applied, augmented_skipped = demote_findings_with_failing_criteria(
+        applied_finding_indexes, skipped_entries, failing_criteria_by_finding
+    )
+    updated_content = groq_bugteam_module.preserve_trailing_newline(
+        current_content, raw_updated_content
+    )
+
+    return {
+        "updated_content": updated_content,
+        "applied_finding_indexes": demoted_applied,
+        "skipped": augmented_skipped,
+        "acceptance_checks": acceptance_checks,
+    }
+
+
+def read_spec_input_from_stdin() -> tuple[list[dict], str]:
+    stdin_text = sys.stdin.read()
+    parsed_input = json.loads(stdin_text)
+    spec_list = parsed_input.get("spec", [])
+    current_content = parsed_input.get("current_content", "")
+    return spec_list, current_content
+
+
+def run_spec_mode() -> dict:
+    try:
+        spec_list, current_content = read_spec_input_from_stdin()
+    except (json.JSONDecodeError, ValueError) as parse_error:
+        return {"error": f"stdin is not valid JSON: {parse_error}"}
+    try:
+        return apply_fix_from_spec(spec_list, current_content)
+    except Exception as spec_error:
+        return {"error": f"spec-mode fix failed: {spec_error}"}
+
+
+def is_spec_mode_invocation(argv: list[str]) -> bool:
+    for each_argv_index, each_argv_token in enumerate(argv):
+        if each_argv_token != SPEC_MODE_FLAG:
+            continue
+        if each_argv_index + 1 >= len(argv):
+            continue
+        if argv[each_argv_index + 1] == SPEC_MODE_VALUE:
+            return True
+    return False
+
+
+def emit_outcome(outcome: dict) -> None:
+    json.dump(outcome, sys.stdout, indent=JSON_INDENT_SPACES)
+    sys.stdout.write("\n")
+
+
+def run_spec_mode_main() -> None:
+    spec_outcome = run_spec_mode()
+    emit_outcome(spec_outcome)
+    if "error" in spec_outcome:
+        sys.exit(PIPELINE_FAILURE_EXIT_CODE)