claude-dev-env 4.3.0 → 7.0.0

package/_shared/pr-loop/scripts/tests/test_post_audit_thread_constants.py

@@ -1,129 +0,0 @@
-"""Tests for post_audit_thread_constants.py extracted constant set."""
-
-import importlib.util
-from pathlib import Path
-from types import ModuleType
-
-
-def _load_constants_module() -> ModuleType:
-    module_path = (
-        Path(__file__).parent.parent
-        / "pr_loop_shared_constants"
-        / "post_audit_thread_constants.py"
-    )
-    specification = importlib.util.spec_from_file_location(
-        "pr_loop_shared_constants.post_audit_thread_constants", module_path
-    )
-    assert specification is not None
-    assert specification.loader is not None
-    module = importlib.util.module_from_spec(specification)
-    specification.loader.exec_module(module)
-    return module
-
-
-constants_module = _load_constants_module()
-
-
-def test_http_request_content_type_is_application_json() -> None:
-    assert constants_module.HTTP_REQUEST_CONTENT_TYPE == "application/json"
-
-
-def test_http_method_post_constant_is_post() -> None:
-    assert constants_module.HTTP_METHOD_POST == "POST"
-
-
-def test_http_header_authorization_constant_is_authorization() -> None:
-    assert constants_module.HTTP_HEADER_AUTHORIZATION == "Authorization"
-
-
-def test_http_header_accept_constant_is_accept() -> None:
-    assert constants_module.HTTP_HEADER_ACCEPT == "Accept"
-
-
-def test_http_header_content_type_constant_is_content_type() -> None:
-    assert constants_module.HTTP_HEADER_CONTENT_TYPE == "Content-Type"
-
-
-def test_http_header_github_api_version_constant_is_x_github_api_version() -> None:
-    assert constants_module.HTTP_HEADER_GITHUB_API_VERSION == "X-GitHub-Api-Version"
-
-
-def test_http_header_user_agent_constant_is_user_agent() -> None:
-    assert constants_module.HTTP_HEADER_USER_AGENT == "User-Agent"
-
-
-def test_http_authorization_bearer_prefix_is_bearer_with_trailing_space() -> None:
-    prefix = constants_module.HTTP_AUTHORIZATION_BEARER_PREFIX
-    assert prefix == "Bearer "
-    assert prefix.endswith(" ")
-
-
-def test_http_request_timeout_seconds_is_positive_int() -> None:
-    timeout_seconds = constants_module.HTTP_REQUEST_TIMEOUT_SECONDS
-    assert isinstance(timeout_seconds, int)
-    assert timeout_seconds > 0
-
-
-def test_error_response_preview_chars_is_positive_int() -> None:
-    preview_chars = constants_module.ERROR_RESPONSE_PREVIEW_CHARS
-    assert isinstance(preview_chars, int)
-    assert preview_chars > 0
-
-
-def test_single_review_api_path_template_uses_pr_number_placeholder() -> None:
-    template_text = constants_module.SINGLE_REVIEW_API_PATH_TEMPLATE
-    assert "{owner}" in template_text
-    assert "{repo}" in template_text
-    assert "{pr_number}" in template_text
-    assert "{review_id}" in template_text
-
-
-def test_single_review_comments_api_path_template_uses_pr_number_placeholder() -> None:
-    template_text = constants_module.SINGLE_REVIEW_COMMENTS_API_PATH_TEMPLATE
-    assert "{owner}" in template_text
-    assert "{repo}" in template_text
-    assert "{pr_number}" in template_text
-    assert "{review_id}" in template_text
-    assert template_text.endswith("/comments")
-
-
-def test_audit_body_skeleton_marker_tokens_present() -> None:
-    open_marker = constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER
-    close_marker = constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER
-    assert open_marker.startswith("<!--") and open_marker.endswith("-->")
-    assert close_marker.startswith("<!--") and close_marker.endswith("-->")
-    assert open_marker != close_marker
-
-
-def test_template_path_resolves_to_existing_markdown_file() -> None:
-    resolved_path = constants_module.template_path()
-    assert resolved_path.is_file(), f"missing: {resolved_path}"
-    assert resolved_path.suffix == ".md"
-
-
-def test_template_contains_skeleton_markers() -> None:
-    resolved_path = constants_module.template_path()
-    template_text = resolved_path.read_text(encoding="utf-8")
-    assert constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER in template_text
-    assert constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER in template_text
-
-
-def test_live_test_fixture_names_are_not_exposed_from_production_config_module() -> None:
-    forbidden_attribute_names = [
-        "LIVE_TEST_OWNER",
-        "LIVE_TEST_REPO",
-        "LIVE_TEST_BRANCH_PREFIX",
-        "LIVE_TEST_PR_TITLE",
-        "LIVE_TEST_PR_BODY",
-        "LIVE_TEST_BASE_BRANCH",
-        "LIVE_TEST_FIXTURE_FILENAME",
-        "LIVE_TEST_FIXTURE_CONTENT",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_ONE",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_TWO",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_THREE",
-    ]
-    for each_attribute_name in forbidden_attribute_names:
-        assert not hasattr(constants_module, each_attribute_name), (
-            f"production config module exposes test-only fixture "
-            f"{each_attribute_name!r}; move it to test_post_audit_thread.py"
-        )

package/_shared/pr-loop/state-schema.md

@@ -1,45 +0,0 @@
-# State schema
-
-State each PR-loop workflow tracks across iterations. Workflows differ on persistence (in-memory vs files) and which fields they use; shapes overlap.
-
-## Common fields
-
-| Field | Type | Purpose |
-|---|---|---|
-| `loop_count` | int | Iterations completed; bumps on each AUDIT or tick |
-| `last_action` | enum | `fresh`, `audited`, `fixed` — drives next-step dispatch |
-| `last_findings` | object | `{p0, p1, p2, total}` count of findings from most recent AUDIT |
-| `audit_log` | list[str] | Per-iteration one-line summaries for the final report |
-| `starting_sha` | str | `git rev-parse HEAD` at workflow start |
-| `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, thread_node_id, fix_status, ...}}` (`thread_node_id` is the PR review thread node id — `PRRT_kwDOxxx` — captured at audit time when calling `get_review_comments`, used by `resolve_thread` at FIX time) |
-
-## autoconverge (workflow and portable pacer)
-
-Workflow runs hold round state in the workflow journal. On `pacer=portable`, the
-continuous driver seeds `pr-converge-state.json` under the job directory and
-advances phases through `portable_converge_driver.py`. Portable state carries
-`current_head`, `phase`, `codex_clean_at`, `codex_down`, `codex_required`, and
-pending `next` / `wait_seconds` stamps. Round shape and terminal gates are
-documented in
-[`../../.agents/skills/autoconverge/reference/convergence.md`](../../.agents/skills/autoconverge/reference/convergence.md).
-The machine readiness checklist is
-[`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md).
-
-## Archived workflow extensions
-
-Historical field lists for retired entry skills live under
-`packages/claude-dev-env/.agents/skills-archived/`:
-
-- **bugteam** — inline orchestrator state, `team_name`, `gate_round_count`, exit payload fields. See [`../../.agents/skills-archived/bugteam/SKILL.md`](../../.agents/skills-archived/bugteam/SKILL.md).
-- **pr-converge** — file-backed multi-PR state, phase enum, dual persistence. See [`../../.agents/skills-archived/pr-converge/reference/state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md) and [`../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md`](../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md).
-
-## Reset semantics
-
-- **autoconverge** — portable state resets on a fresh `open-run`; workflow journal is per run id.
-- **Archived bugteam** — cleared on each new invocation; see archived skill body.
-- **Archived pr-converge** — see archived [`state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md); multi-PR file state persists across orchestrator runs and only `last_seen_comment_id` advances monotonically.
-
-## Convergence checks
-
-- **autoconverge** — `packages/claude-dev-env/_shared/pr-loop/scripts/check_convergence.py` is the single readiness source; gate labels are listed in [`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md). On pass, mark the PR ready (`gh pr ready`).
-- **Archived pr-converge** — same script and archived [`convergence-gates.md`](../../.agents/skills-archived/pr-converge/reference/convergence-gates.md) reference.

package/_shared/pr-loop/worker-spawn.md

@@ -1,189 +0,0 @@
-# Worker-spawn protocol
-
-Single home for the worker-spawn dispatcher contract and for Claude-only
-slash-step host routing. Skills that need a role-bound headless worker call
-[`scripts/resolve_worker_spawn.py`](../../scripts/resolve_worker_spawn.py)
-(or import `resolve_worker_spawn`) and read this page for the tier walk, inputs,
-JSON result shape, host rules, and setup. Skills that run a Claude-only slash
-step (for example `/code-review`) read the code-review host-routing section.
-
-Composed helpers (preflight, headless runners, and the code-review invoker)
-stay documented at their own modules; this page states how callers use them.
-
-## Three tiers
-
-Walk order is fixed: soft-gate preflight for tier 1, then tier 1, then host
-branching for tiers 2 and 3.
-
-| Tier | Name | Who runs it |
-|---|---|---|
-| 1 | Grok headless | Python helper: `grok_worker_preflight` then `grok_headless_runner.run_headless_worker` |
-| 2 | `claude_agent_required` | **Not** the Python helper. A stop signal so the **calling skill / harness** runs the Claude Code Agent tool itself |
-| 3 | Claude headless | Python helper: `claude_chain_runner.run_claude` with `-p --output-format json --agent <stem>`, prompt body on stdin from the prompt file, and subprocess `cwd` set to the caller's working directory |
-
-### `claude_agent_required` boundary
-
-A Python helper cannot spawn Claude Code Agent-tool subagents. On a **Claude**
-host, when the claude headless tier is **not** enabled (`--enable-claude-tier`
-absent / `is_claude_tier_enabled=False`), a grok fallthrough records tier 2 with
-reason `claude_agent_required`, leaves `tier_used` null, and returns. The
-calling skill must then run the Agent tool in-process.
-
-On a **ThirdParty** host, or when the claude tier is enabled on a Claude host,
-the dispatcher continues to tier 3.
-
-## Tier-1 fleets via grok-spawn
-
-For a fleet of tier-1 grok workers (batch spec in, reports out), use the
-**grok-spawn** skill when that skill is installed on the host (it ships on a
-sibling stack and is not part of this dispatcher page). When present, that
-skill owns the batch playbook and flag profiles under its reference docs.
-This page stays the single-worker dispatcher contract (`resolve_worker_spawn`).
-
-The calling session owns verification and every commit, push, or GitHub post.
-Workers never commit or post.
-
-## Required inputs
-
-### CLI
-
-```
-python resolve_worker_spawn.py \
-  --role <role> \
-  --prompt-file <path> \
-  --cwd <dir> \
-  --run-temp-dir <dir> \
-  [--timeout-seconds N] \
-  [--enable-claude-tier]
-```
-
-| Flag | Required | Meaning |
-|---|---|---|
-| `--role` | no (default `bugteam`) | Role name for preflight agent-set checks; mapped to the primary agent stem for headless `--agent` (for example `bugteam` → `code-quality-agent`, `clean-coder` → `clean-coder`; unknown roles fall back to the raw role string) |
-| `--prompt-file` | yes | Prompt file path for headless workers |
-| `--cwd` | yes | Working directory for headless grok and claude workers |
-| `--run-temp-dir` | yes | Run-scoped directory for leader sockets and preflight cache (created if missing) |
-| `--timeout-seconds` | no (default `600`) | Per-tier timeout in seconds |
-| `--enable-claude-tier` | no | Allow tier 3 on a Claude host |
-
-There is no separate outcome-file flag. The result surface is **stdout JSON**
-plus the process exit code.
-
-### Import API
-
-`resolve_worker_spawn(...)` takes keyword-only arguments:
-`role`, `prompt_file`, `working_directory`, `timeout_seconds`,
-`is_claude_tier_enabled`, `run_state_directory`.
-`encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
-prints.
-
-The grok tier runs with no turn cap; `timeout_seconds` is its only bound.
-
-## JSON result shape
-
-Stdout is one JSON object:
-
-```json
-{
-  "tier_used": 1,
-  "ok": true,
-  "attempts": [
-    {"tier": 1, "ok": true, "reason": null}
-  ],
-  "output": "<serving tier stdout>",
-  "returncode": 0
-}
-```
-
-| Key | Meaning |
-|---|---|
-| `tier_used` | Serving tier number (`1` or `3`), or `null` when no tier served |
-| `ok` | Whether the serving call completed successfully |
-| `attempts` | Ordered list of tries: each `{tier, ok, reason}` |
-| `output` | Captured stdout from the serving tier (empty when none) |
-| `returncode` | Process return code from the last tier run (or config-error code) |
-
-`attempts` is in tried order. A Claude-host stop records tier `2` with
-`reason: "claude_agent_required"`. Preflight or grok fallthrough reasons use the
-preflight/runner classification strings (for example `grok_binary_missing`,
-`usage_limit`).
-
-### Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | A tier served (`tier_used` is not null) |
-| `2` | Exhausted — no tier served |
-| `3` | Config error: the `--prompt-file` path is not an existing file (`output` = `prompt_file_missing`) or claude chain configuration missing or invalid |
-
-## Host detection
-
-After a grok fallthrough the dispatcher calls `detect_host_profile()` from
-`tier_model_ids` (advisor scripts). Detection order:
-
-1. `ADVISOR_HOST_PROFILE` when set — must be `Claude`, `Codex`, or `ThirdParty` (any letter case).
-2. `THIRD_PARTY` when truthy — `1`, `true`, `yes`, or `on`.
-3. Default: `Claude`.
-
-Profiles are the real names `Claude`, `Codex`, and `ThirdParty` (not a separate Grok host
-profile). Grok is tier 1 on every host; host profile only chooses the post-grok
-branch (Agent-tool handoff vs headless claude chain). A Codex profile takes the
-non-Claude branch.
-
-## Code-review host routing
-
-Claude-only slash steps need a Claude Code harness. The built-in
-`/code-review` command is the main case. The host-routing pair is:
-
-- `detect_host_profile()` from `tier_model_ids` — same host detection as the
-  worker-spawn dispatcher above
-- `invoke_code_review` — host-aware invoker for `/code-review` (lives next to
-  `resolve_worker_spawn` under the package scripts tree)
-
-Mode decision:
-
-| Host profile | Session model | Mode | Who runs `/code-review` |
-|---|---|---|---|
-| `Claude` | `opus` | `in_session` | The calling skill runs the slash command in-process |
-| `Claude` | any other alias | `chain` | Headless spawn through `claude_chain_runner` |
-| `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
-
-The review always runs at effort **high** on model **opus**. Chain mode builds
-a single-turn prompt `/code-review ultra --fix`, pins `--model opus`, sets
-subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
-so the spawn does not wait for input.
-
-After a chain run, a non-empty `git status --porcelain` means the review
-applied fixes. The calling host commits and pushes those fixes per the fix
-protocol. The chain process never commits or posts. A clean stamp requires
-`returncode == 0` and a non-null `served_command` plus a clean tree —
-`dirty_tree` false alone is not enough when the chain failed or never served.
-
-GitHub transport (`pr-loop-cloud-transport`) is a separate axis from this
-harness branch. That skill routes `gh` vs MCP; it does not change which host
-can run Claude-only slash commands.
-
-## Leader-socket rule
-
-Every concurrent grok process gets its own `--leader-socket` path under the
-caller-supplied run temp directory. The headless runner mints a unique
-`grok-leader-<uuid>.sock` per invocation. Preflight auth and ping probes use
-their own fixed socket filenames under the same directory so they never share a
-socket with a live worker.
-
-## Cloud setup
-
-Unattended grok auth uses the `XAI_API_KEY` environment variable. Install the
-CLI via the vendor curl installer or the `@xai-official/grok` package. Keep
-agent definitions and hook config in parity with `npx claude-dev-env` so the
-preflight role-agent check and local `~/.claude` layout match what the worker
-expects.
-
-Use placeholders for account-specific values; do not hardcode personal paths or
-keys in skills or docs.
-
-## GitHub transport
-
-`pr-loop-cloud-transport` is a separate axis. This utility never posts reviews,
-opens PRs, or substitutes `gh` for MCP. GitHub reachability and cloud session
-routing stay outside the worker-spawn contract.