claude-dev-env 2.8.0 → 2.10.0

package/scripts/codex_compat_materializer.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import ast
 import hashlib
 import json
 import os
@@ -15,6 +14,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable, Iterable
 
+import yaml
+
 
 ManagedContent = str | bytes
 
@@ -24,7 +25,6 @@ reparse_point_attribute_name = "FILE_ATTRIBUTE_REPARSE_POINT"
 manifest_indentation_width = 2
 publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
-frontmatter_required_fields = ("name", "description")
 frontmatter_unsupported_fields = ("tools", "model", "color")
 full_prune_opt_in_flag = "--allow-prune-all"
 unreadable_source_root_message = (
@@ -259,73 +259,67 @@ def validate_target_path(target_root: Path, relative_path: str) -> Path:
     return _validate_containment(root, candidate)
 
 
-def _parse_frontmatter_scalar(serialized_field_text: str) -> str | tuple[str, ...] | None:
-    normalized_field_text = serialized_field_text.strip()
-    if not normalized_field_text:
-        return ""
-    if normalized_field_text.startswith("["):
-        return _parse_frontmatter_list(normalized_field_text)
-    try:
-        parsed = ast.literal_eval(normalized_field_text)
-    except (SyntaxError, ValueError):
-        if normalized_field_text[:1] in {'"', "'"} or normalized_field_text[:1] == "[":
-            raise MaterializerError("malformed frontmatter value")
-        return normalized_field_text
-    if isinstance(parsed, str):
-        return parsed
-    if isinstance(parsed, list) and all(isinstance(each_entry, str) for each_entry in parsed):
-        return tuple(parsed)
-    raise MaterializerError("frontmatter value must be a string or string list")
-
-
-def _parse_frontmatter_list(serialized_list: str) -> tuple[str, ...]:
-    if not serialized_list.endswith("]"):
-        raise MaterializerError("malformed frontmatter value")
-    all_entries: list[str] = []
-    entry_start = 1
-    quote: str | None = None
-    has_escape_pending = False
-    for each_index, each_character in enumerate(serialized_list[1:-1], 1):
-        if has_escape_pending:
-            has_escape_pending = False
-            continue
-        if quote == '"' and each_character == "\\":
-            has_escape_pending = True
-            continue
-        if each_character in {'"', "'"}:
-            if quote is None:
-                quote = each_character
-            elif quote == each_character:
-                quote = None
-            continue
-        if each_character == "," and quote is None:
-            all_entries.append(_parse_frontmatter_list_entry(serialized_list[entry_start:each_index]))
-            entry_start = each_index + 1
-    if quote is not None or has_escape_pending:
-        raise MaterializerError("malformed frontmatter value")
-    all_entries.append(_parse_frontmatter_list_entry(serialized_list[entry_start:-1]))
-    return tuple(all_entries) if all_entries != [""] else ()
-
-
-def _parse_frontmatter_list_entry(raw_entry: str) -> str:
-    entry = raw_entry.strip()
-    if not entry:
-        raise MaterializerError("malformed frontmatter value")
-    try:
-        parsed = ast.literal_eval(entry)
-    except (SyntaxError, ValueError):
-        if entry[0] in {'"', "'"}:
-            raise MaterializerError("malformed frontmatter value")
-        if any(character in entry for character in "[]{}:"):
-            raise MaterializerError("malformed frontmatter value")
-        return entry
-    if not isinstance(parsed, str):
-        raise MaterializerError("frontmatter list entries must be strings")
-    return parsed
+class _UniqueKeySafeLoader(yaml.SafeLoader):
+    """SafeLoader that rejects duplicate mapping keys (safe_load keeps last)."""
+
+
+def _construct_mapping_rejecting_duplicates(
+    loader: yaml.SafeLoader,
+    node: yaml.nodes.MappingNode,
+    is_deep: bool = False,
+) -> dict:
+    mapping: dict = {}
+    for each_key_node, each_field_node in node.value:
+        key = loader.construct_object(each_key_node, deep=is_deep)
+        if key in mapping:
+            raise yaml.constructor.ConstructorError(
+                None,
+                None,
+                f"duplicate key {key!r}",
+                each_key_node.start_mark,
+            )
+        mapping[key] = loader.construct_object(each_field_node, deep=is_deep)
+    return mapping
+
+
+_UniqueKeySafeLoader.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+    _construct_mapping_rejecting_duplicates,
+)
+
+
+def _require_nonempty_string(field_content: object, source_path: Path) -> str:
+    if not isinstance(field_content, str):
+        raise MaterializerError(f"name and description are required: {source_path}")
+    if not field_content.strip():
+        raise MaterializerError(f"name and description are required: {source_path}")
+    return field_content
+
+
+def _require_optional_string(
+    field_content: object, field_name: str, source_path: Path
+) -> str | None:
+    if field_content is None:
+        return None
+    if not isinstance(field_content, str):
+        raise MaterializerError(f"{field_name} must be a string: {source_path}")
+    return field_content
+
+
+def _require_tools_list(tools_content: object, source_path: Path) -> tuple[str, ...]:
+    if tools_content is None:
+        return ()
+    if isinstance(tools_content, str):
+        return (tools_content,)
+    if not isinstance(tools_content, list):
+        raise MaterializerError(f"tools must be a list: {source_path}")
+    if not all(isinstance(each_entry, str) for each_entry in tools_content):
+        raise MaterializerError(f"tools must be a list: {source_path}")
+    return tuple(tools_content)
 
 
 def parse_frontmatter(source_path: Path, source_text: str, relative_source: str) -> ClaudeAgent:
-    """Parse one Claude agent's frontmatter.
+    """Parse one Claude agent's frontmatter through validated YAML.
 
     Args:
         source_path: Path used in validation errors.
@@ -342,30 +336,56 @@ def parse_frontmatter(source_path: Path, source_text: str, relative_source: str)
     lines = source_text.splitlines()
     if len(lines) < 3 or lines[0].strip() != "---":
         raise MaterializerError(f"malformed frontmatter: {source_path}")
-    delimiters = [each_index for each_index, line in enumerate(lines[1:], 1) if line.strip() == "---"]
+    delimiters = [
+        each_index for each_index, line in enumerate(lines[1:], 1) if line.strip() == "---"
+    ]
     if len(delimiters) != 1:
         raise MaterializerError(f"malformed frontmatter delimiters: {source_path}")
-    all_fields: dict[str, str | tuple[str, ...] | None] = {}
-    for each_line in lines[1 : delimiters[0]]:
-        if not each_line.strip() or ":" not in each_line:
-            raise MaterializerError(f"malformed frontmatter: {source_path}")
-        key, serialized_field_text = each_line.split(":", 1)
-        key = key.strip()
-        if key in all_fields or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]*", key):
+    frontmatter_text = line_separator.join(lines[1 : delimiters[0]]) + line_separator
+    try:
+        parsed_fields = yaml.load(frontmatter_text, Loader=_UniqueKeySafeLoader)
+    except yaml.YAMLError as yaml_error:
+        raise MaterializerError(f"malformed frontmatter: {source_path}") from yaml_error
+    if not isinstance(parsed_fields, dict):
+        raise MaterializerError(f"malformed frontmatter: {source_path}")
+    for each_key in parsed_fields:
+        if not isinstance(each_key, str) or not re.fullmatch(
+            r"[A-Za-z][A-Za-z0-9_-]*", each_key
+        ):
             raise MaterializerError(f"malformed frontmatter key: {source_path}")
-        all_fields[key] = _parse_frontmatter_scalar(serialized_field_text)
-    unknown = tuple(sorted(each_key for each_key in all_fields if each_key not in frontmatter_allowed_fields))
+    unknown = tuple(
+        sorted(
+            each_key
+            for each_key in parsed_fields
+            if each_key not in frontmatter_allowed_fields
+        )
+    )
     if unknown:
         raise MaterializerError(f"unknown frontmatter keys: {source_path}")
-    unsupported = tuple(sorted(each_key for each_key in all_fields if each_key in frontmatter_unsupported_fields))
-    if any(not isinstance(all_fields.get(each_key), str) or not all_fields[each_key] for each_key in frontmatter_required_fields):
-        raise MaterializerError(f"name and description are required: {source_path}")
-    tools = all_fields.get("tools", ())
-    if isinstance(tools, str):
-        tools = (tools,)
-    if not isinstance(tools, tuple):
-        raise MaterializerError(f"tools must be a list: {source_path}")
-    return ClaudeAgent(source_path, source_identity, all_fields["name"], all_fields["description"], tools, all_fields.get("model"), all_fields.get("color"), unsupported)
+    unsupported = tuple(
+        sorted(
+            each_key
+            for each_key in parsed_fields
+            if each_key in frontmatter_unsupported_fields
+        )
+    )
+    name = _require_nonempty_string(parsed_fields.get("name"), source_path)
+    description = _require_nonempty_string(
+        parsed_fields.get("description"), source_path
+    )
+    tools = _require_tools_list(parsed_fields.get("tools"), source_path)
+    model = _require_optional_string(parsed_fields.get("model"), "model", source_path)
+    color = _require_optional_string(parsed_fields.get("color"), "color", source_path)
+    return ClaudeAgent(
+        source_path,
+        source_identity,
+        name,
+        description,
+        tools,
+        model,
+        color,
+        unsupported,
+    )
 
 
 def convert_agent(agent: ClaudeAgent) -> str:

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -10,8 +10,10 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
 | `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
 | `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
 | `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
+| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
+| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
 | `__init__.py` | Empty package marker |
 
 ## Convention

package/scripts/dev_env_scripts_constants/active_capability_constants.py

@@ -0,0 +1,46 @@
+"""Constants for the active_capability_references script.
+
+Script-level scalar constants live in dev_env_scripts_constants alongside
+timing.py and the other per-script constant modules.
+"""
+
+from __future__ import annotations
+
+PACKAGE_SKILLS_DIRECTORY: str = "skills"
+PACKAGE_AGENTS_DIRECTORY: str = "agents"
+PACKAGE_COMMANDS_DIRECTORY: str = "commands"
+SKILL_MANIFEST_FILENAME: str = "SKILL.md"
+
+# Slash-command and skill names that must never appear as active instructions.
+ALL_BANNED_ACTIVE_CAPABILITY_NAMES: frozenset[str] = frozenset(
+    {
+        "stub-detector",
+        "superpowers",
+        "qbug",
+        "findbugs",
+        "fixbugs",
+        "monitor-open-prs",
+    }
+)
+
+# Fence languages treated as inert historical/example content.
+ALL_INERT_FENCE_LANGUAGES: frozenset[str] = frozenset(
+    {
+        "example",
+        "history",
+        "historical",
+        "quote",
+        "diff",
+    }
+)
+
+SLASH_CAPABILITY_PATTERN: str = r"(?<![`\w])/([a-z][a-z0-9-]{2,})"
+BACKTICK_CAPABILITY_PATTERN: str = (
+    r"`(?:skills/)?([a-z][a-z0-9-]{2,})(?:/SKILL\.md)?`"
+)
+FENCE_OPEN_PATTERN: str = r"^```([A-Za-z0-9_-]*)\s*$"
+FENCE_CLOSE_PATTERN: str = r"^```\s*$"
+BANNED_REASON_PREFIX: str = "banned_active_capability:"
+
+UTF8_ENCODING: str = "utf-8"
+NEWLINE_JOIN_SEPARATOR: str = "\n"

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -227,3 +227,77 @@ ATTEMPT_SUMMARY_ENTRY_TEMPLATE: str = "{command}={status}"
 
 ATTEMPT_SUMMARY_JOIN_SEPARATOR: str = ", "
 """Separator joining per-attempt fragments in the exhausted-chain summary."""
+
+AFFINITY_STATE_SCHEMA_VERSION: int = 1
+"""Version field written into the session-to-binary affinity state document."""
+
+AFFINITY_STATE_FILENAME: str = "claude-chain-affinity.json"
+"""Default affinity state file name under the Claude home directory."""
+
+AFFINITY_MAXIMUM_ENTRIES: int = 64
+"""Hard cap on retained session-to-binary affinity rows (oldest drop first)."""
+
+AFFINITY_KEY_SCHEMA_VERSION: str = "schema_version"
+"""JSON key for the affinity document schema version."""
+
+AFFINITY_KEY_ALL_BINDINGS: str = "all_bindings"
+"""JSON key for the ordered list of session-to-command bindings."""
+
+AFFINITY_KEY_SESSION_ID: str = "session_id"
+"""JSON key for a bound Claude session id."""
+
+AFFINITY_KEY_COMMAND: str = "command"
+"""JSON key for the chain binary command bound to a session id."""
+
+AFFINITY_TEMP_SUFFIX: str = ".tmp"
+"""Suffix for the temporary file used during atomic affinity replacement."""
+
+AFFINITY_BINDING_NOT_OBJECT_REASON: str = "a binding entry is not an object"
+"""Reason when an affinity binding entry is not a JSON object."""
+
+AFFINITY_BINDING_SESSION_ID_MISSING_REASON: str = (
+    "binding missing non-empty session_id"
+)
+"""Reason when an affinity binding lacks a usable session_id."""
+
+AFFINITY_BINDING_COMMAND_MISSING_REASON: str = "binding missing non-empty command"
+"""Reason when an affinity binding lacks a usable command."""
+
+AFFINITY_UNSUPPORTED_SCHEMA_VERSION_REASON_TEMPLATE: str = (
+    "unsupported schema_version {schema_version!r}"
+)
+"""Reason when the affinity document schema version is not supported."""
+
+AFFINITY_BINDINGS_MISSING_OR_NOT_LIST_REASON: str = (
+    "all_bindings is missing or not a list"
+)
+"""Reason when all_bindings is absent or the wrong type."""
+
+AFFINITY_TOP_LEVEL_NOT_OBJECT_REASON: str = "top-level value is not a JSON object"
+"""Reason when the affinity document root is not an object."""
+
+AFFINITY_SESSION_ID_AND_COMMAND_REQUIRED_MESSAGE: str = (
+    "session_id and command must be non-empty"
+)
+"""ValueError message when record_affinity_binding receives empty ids."""
+
+AFFINITY_MAXIMUM_ENTRIES_MINIMUM_MESSAGE: str = "maximum_entries must be at least 1"
+"""ValueError message when maximum_entries is below one."""
+
+AFFINITY_CORRUPT_MESSAGE_TEMPLATE: str = (
+    "Affinity state at {state_path} is corrupt or unreadable: {error}. "
+    "Delete or repair the file before retrying."
+)
+"""Actionable diagnostic when affinity state cannot be loaded."""
+
+AFFINITY_WRITE_FAILED_MESSAGE_TEMPLATE: str = (
+    "Failed to write affinity state at {state_path}: {error}. "
+    "Check directory permissions and free space."
+)
+"""Actionable diagnostic when atomic affinity replacement fails."""
+
+AFFINITY_JSON_INDENT_SPACES: int = 2
+"""Indent width for the written affinity state JSON document."""
+
+RESUME_SESSION_FLAG: str = "--resume"
+"""Claude CLI flag that continues a prior session by id."""

package/scripts/dev_env_scripts_constants/grok_run_ledger_constants.py

@@ -0,0 +1,50 @@
+"""Named constants for the host-neutral Grok run ledger and patch artifacts."""
+
+from __future__ import annotations
+
+LEDGER_SCHEMA_VERSION: str = "1.0.0"
+"""Schema version stamped on every ledger document and task record."""
+
+LEDGER_FILENAME: str = "grok-run-ledger.json"
+"""Default ledger filename under a run-state directory."""
+
+PATCH_MANIFEST_FILENAME: str = "patch-manifest.json"
+"""Default patch-manifest filename under a run-state directory."""
+
+TASK_STATUS_PENDING: str = "pending"
+"""Task is recorded and waiting for dispatch."""
+
+TASK_STATUS_IN_PROGRESS: str = "in_progress"
+"""Task has exactly one live owner and is being worked."""
+
+TASK_STATUS_COMPLETED: str = "completed"
+"""Task reached a successful terminal state."""
+
+TASK_STATUS_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Task stopped because the advisor bind or verdict failed closed."""
+
+TASK_STATUS_PENDING_REVIEW: str = "pending_review"
+"""Task was invalidated by snapshot drift and needs re-review."""
+
+ALL_LEGAL_TASK_STATUSES: frozenset[str] = frozenset(
+    {
+        TASK_STATUS_PENDING,
+        TASK_STATUS_IN_PROGRESS,
+        TASK_STATUS_COMPLETED,
+        TASK_STATUS_ADVISOR_BLOCKED,
+        TASK_STATUS_PENDING_REVIEW,
+    }
+)
+"""Every legal task status the ledger accepts."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for ledger and patch-manifest files."""
+
+JSON_INDENT: int = 2
+"""Indent width for pretty-printed ledger and patch-manifest JSON."""
+
+TEMPORARY_LEDGER_PREFIX: str = ".ledger-"
+"""Prefix for atomic ledger temp files before replace."""
+
+TEMPORARY_LEDGER_SUFFIX: str = ".tmp"
+"""Suffix for atomic ledger temp files before replace."""

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -503,3 +503,107 @@ CLI_ENABLE_CLAUDE_TIER_FLAG: str = "--enable-claude-tier"
 
 EMPTY_OUTPUT: str = ""
 """Empty captured output when no tier produced stdout."""
+
+BATCH_SPEC_ADVISOR_KEY: str = "advisor"
+"""JSON key for the optional batch-level worker-advisor block."""
+
+ADVISOR_SPEC_LAUNCHER_KEY: str = "launcher"
+"""JSON key for the lead-supplied advisor launcher executable name."""
+
+ADVISOR_SPEC_MODEL_KEY: str = "model"
+"""JSON key for the advisor model name."""
+
+ADVISOR_SPEC_EFFORT_KEY: str = "effort"
+"""JSON key for the advisor effort level."""
+
+DEFAULT_ADVISOR_LAUNCHER_PLACEHOLDER: str = "ADVISOR_LAUNCHER_PLACEHOLDER"
+"""Committed placeholder; real launcher arrives only from the lead's batch spec."""
+
+DEFAULT_ADVISOR_MODEL: str = "opus"
+"""Default advisor model when the batch advisor block omits model."""
+
+DEFAULT_ADVISOR_EFFORT: str = "high"
+"""Default advisor effort when the batch advisor block omits effort."""
+
+MAXIMUM_WORKER_ADVISOR_CORRECTIONS: int = 3
+"""Maximum CORRECTION/PLAN re-consults per worker before advisor_blocked."""
+
+MAXIMUM_ADVISOR_TIMEOUT_SECONDS: int = 600
+"""Timeout for one advisor launcher subprocess call, in seconds."""
+
+ADVISOR_SIGNAL_ENDORSE: str = "ENDORSE"
+"""Opening signal that accepts a worker report."""
+
+ADVISOR_SIGNAL_CORRECTION: str = "CORRECTION"
+"""Opening signal that requires a re-consult up to the correction cap."""
+
+ADVISOR_SIGNAL_PLAN: str = "PLAN"
+"""Opening signal treated like CORRECTION for re-consult counting."""
+
+ADVISOR_SIGNAL_STOP: str = "STOP"
+"""Opening signal that ends the worker as advisor_blocked immediately."""
+
+ALL_KNOWN_ADVISOR_SIGNALS: frozenset[str] = frozenset(
+    {
+        ADVISOR_SIGNAL_ENDORSE,
+        ADVISOR_SIGNAL_CORRECTION,
+        ADVISOR_SIGNAL_PLAN,
+        ADVISOR_SIGNAL_STOP,
+    }
+)
+"""The four allowed first tokens of an advisor reply."""
+
+CLASSIFICATION_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Worker classification when advisor bind, resume, or verdict fails closed."""
+
+PENDING_BIND_SENTINEL: str = "PENDING_BIND"
+"""Unbound advisor session or signal sentinel; must fail closed before launch."""
+
+ADVISOR_PROMPT_HEADER_TEMPLATE: str = (
+    "Worker advisor session: {session_id}\n"
+    "Advisor model: {model}\n"
+    "Advisor effort: {effort}\n"
+    "Report only after the same session endorses or corrections are applied.\n\n"
+)
+"""Prefix injected into each worker prompt after a successful pre-dispatch bind."""
+
+SUMMARY_ADVISOR_SESSION_ID_KEY: str = "advisor_session_id"
+"""Per-worker report JSON key for the unique advisor session id."""
+
+SUMMARY_ADVISOR_SIGNAL_KEY: str = "advisor_completion_signal"
+"""Per-worker report JSON key for the final advisor opening signal."""
+
+SUMMARY_ADVISOR_LAUNCHER_KEY: str = "advisor_launcher"
+"""Per-worker report JSON key for the spec-supplied launcher (runtime only)."""
+
+ADVISOR_CLI_PRINT_FLAG: str = "-p"
+"""Print/non-interactive flag passed to the advisor launcher."""
+
+ADVISOR_CLI_MODEL_FLAG: str = "--model"
+"""Model flag passed to the advisor launcher."""
+
+ADVISOR_CLI_EFFORT_FLAG: str = "--effort"
+"""Effort flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_FLAG: str = "--output-format"
+"""Output-format flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_JSON: str = "json"
+"""JSON output format value for advisor launcher calls."""
+
+ADVISOR_CLI_RESUME_FLAG: str = "--resume"
+"""Resume flag for post-report advisor consults."""
+
+ADVISOR_BIND_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Pre-dispatch: ENDORSE this worker assignment if safe, else CORRECTION."
+)
+"""Prompt body used for the pre-dispatch advisor bind."""
+
+ADVISOR_VERDICT_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}, session {session_id}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Post-report review of the worker report follows.\n\n{report_text}"
+)
+"""Prompt body used for the post-report advisor verdict."""

package/scripts/dev_env_scripts_constants/verify_installable_package_constants.py

@@ -0,0 +1,116 @@
+"""Constants for verify_installable_package — npm pack surface checks.
+
+Holds manifest keys, pack/tarball path tokens, hook-command path markers,
+git and smoke-tool argv pieces, and CLI status messages.
+"""
+
+MANIFEST_FILENAME: str = "installable-surfaces.manifest.json"
+"""Basename of the committed installable-surfaces manifest under the package root."""
+
+PACKAGE_JSON_FILENAME: str = "package.json"
+"""Basename of the npm package manifest that lists the files field."""
+
+PACKAGE_JSON_FILES_KEY: str = "files"
+"""JSON key on package.json that lists packaged path entries."""
+
+PACKAGE_JSON_EXCLUDE_PREFIX: str = "!"
+"""Prefix on package.json files entries that exclude a path pattern."""
+
+MANIFEST_DIRECTORIES_KEY: str = "directories"
+"""JSON key listing required top-level package directories."""
+
+MANIFEST_ROOT_FILES_KEY: str = "root_files"
+"""JSON key listing required package-root files."""
+
+TARBALL_PACKAGE_PREFIX: str = "package/"
+"""Path prefix npm pack applies to every member inside the generated tarball."""
+
+PLUGIN_ROOT_TOKEN: str = "${CLAUDE_PLUGIN_ROOT}/"
+"""Placeholder prefix hooks.json uses for package-relative hook script paths."""
+
+PYTHON_FILE_SUFFIX: str = ".py"
+"""Suffix that marks a hook command token as a Python script path."""
+
+HOOKS_DIRECTORY_NAME: str = "hooks"
+"""Top-level package directory that holds hook scripts and hooks.json."""
+
+HOOKS_DIRECTORY_PREFIX: str = "hooks/"
+"""Package-relative prefix that marks a hook script path under hooks/."""
+
+HOOKS_JSON_RELATIVE_PATH: str = "hooks/hooks.json"
+"""Package-relative path of the hook registration map."""
+
+JSON_COMMAND_KEY: str = "command"
+"""JSON object key whose string value is a hook command line."""
+
+INSTALL_ENTRYPOINT_RELATIVE_PATH: str = "bin/install.mjs"
+"""Package-relative path of the primary install CLI entrypoint."""
+
+PACKAGE_PATH_FROM_REPOSITORY: str = "packages/claude-dev-env"
+"""Repository-relative path of the published package directory."""
+
+NPM_BINARY_NAME: str = "npm"
+"""npm CLI binary name used to build the pack tarball on POSIX hosts."""
+
+NPM_CMD_BINARY_NAME: str = "npm.cmd"
+"""Windows npm launcher resolved before the extensionless npm name."""
+
+NEWLINE_JOIN_SEPARATOR: str = "\n"
+"""Separator used when joining multi-line verification failure reports."""
+
+NPM_PACK_SUBCOMMAND: str = "pack"
+"""npm subcommand that writes the installable tarball."""
+
+NPM_PACK_JSON_FLAG: str = "--json"
+"""Flag that makes npm pack emit machine-readable filename metadata."""
+
+NPM_PACK_DESTINATION_FLAG: str = "--pack-destination"
+"""Flag that directs npm pack to write the tarball into a chosen directory."""
+
+NPM_PACK_FILENAME_KEY: str = "filename"
+"""JSON field on an npm pack --json record that holds the tarball basename."""
+
+GIT_BINARY_NAME: str = "git"
+"""git CLI binary name used to confirm hook scripts are committed."""
+
+GIT_LS_FILES_SUBCOMMAND: str = "ls-files"
+"""git subcommand that lists tracked paths in the index."""
+
+NODE_BINARY_NAME: str = "node"
+"""Node.js binary name used for install-entrypoint syntax smoke checks."""
+
+NODE_CHECK_FLAG: str = "--check"
+"""Flag that makes node parse a script without executing it."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for manifest, hooks.json, and subprocess text mode."""
+
+CLASS_PACKAGED: str = "packaged"
+"""Surface classification when a directory is on disk and listed for packaging."""
+
+CLASS_SOURCE_ONLY: str = "source_only"
+"""Surface classification when a directory is on disk but not listed for packaging."""
+
+CLASS_CONTRADICTORY: str = "contradictory"
+"""Surface classification when package.json lists a directory that is missing on disk."""
+
+EXIT_CODE_SUCCESS: int = 0
+"""Process exit code when every installable-surface check passes."""
+
+EXIT_CODE_FAILURE: int = 1
+"""Process exit code when one or more installable-surface checks fail."""
+
+MISSING_MANIFEST_SURFACES_HEADER: str = "Missing surfaces in npm pack tarball:"
+"""Header printed when required manifest paths are absent from the packed tarball."""
+
+UNTRACKED_HOOK_SCRIPTS_HEADER: str = "Hook scripts missing from git index:"
+"""Header printed when a hooks.json command resolves to an untracked or missing file."""
+
+SMOKE_COMPILE_FAILURES_HEADER: str = "Hook scripts failed py_compile:"
+"""Header printed when a resolved hook script fails Python syntax compilation."""
+
+INSTALL_ENTRYPOINT_SMOKE_FAILURE_HEADER: str = "Install entrypoint failed node --check:"
+"""Header printed when bin/install.mjs fails the Node syntax smoke check."""
+
+VERIFICATION_PASSED_MESSAGE: str = "installable package verification passed"
+"""Status line printed when every check succeeds."""