claude-dev-env 2.9.0 → 2.11.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

@@ -12,6 +12,8 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | `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, 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/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."""

package/scripts/profile-isolation-launchers/config/mcp-bundles.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "supportedActivationInterface": "claude-config-dir-mcp-json",
+  "mcpConfigFileName": "mcp.json",
+  "bundles": {
+    "lean": {
+      "id": "lean",
+      "allServerNames": ["filesystem-readonly"]
+    },
+    "full": {
+      "id": "full",
+      "allServerNames": ["filesystem-readonly", "github-readonly"]
+    }
+  },
+  "serverByName": {
+    "filesystem-readonly": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROFILE_ROOT}"]
+    },
+    "github-readonly": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"]
+    }
+  }
+}

package/scripts/profile-isolation-launchers/config/profile-isolation-constants.mjs

@@ -0,0 +1,60 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CONFIG_DIRECTORY_PATH = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @param {string} fileName
+ * @returns {unknown}
+ */
+function readJsonConfigFile(fileName) {
+  const absolutePath = join(CONFIG_DIRECTORY_PATH, fileName);
+  return JSON.parse(readFileSync(absolutePath, 'utf8'));
+}
+
+export const PROFILES_MANIFEST_FILE_NAME = 'profiles.manifest.json';
+export const SHARED_ALLOWLIST_FILE_NAME = 'shared-allowlist.json';
+
+/**
+ * Sole authoritative profile-root environment variable for CLI isolation.
+ * CLAUDE_HOME is never honored as a profile root by this contract.
+ */
+export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
+export const CLAUDE_HOME_ENVIRONMENT_VARIABLE = 'CLAUDE_HOME';
+export const CLAUDE_CODE_TMPDIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CODE_TMPDIR';
+export const CLAUDE_CODE_PLUGIN_SEED_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CODE_PLUGIN_SEED_DIR';
+
+export const PROFILES_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PROFILES_ROOT';
+export const SHARED_SOURCE_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_SHARED_SOURCE_ROOT';
+export const PLUGIN_SEED_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PLUGIN_SEED_ROOT';
+
+export const DEFAULT_PROFILES_ROOT_DIRECTORY_NAME = '.claude-profiles';
+export const DEFAULT_SHARED_SOURCE_DIRECTORY_NAME = 'shared-source';
+export const DEFAULT_PLUGIN_SEED_DIRECTORY_NAME = 'plugin-seed';
+
+export const MIGRATION_MODE_CLEAN_LOCAL_RUNTIME = 'clean-local-runtime';
+export const MIGRATION_MODE_MATERIALIZE_FROM_LEGACY = 'materialize-from-legacy';
+
+export const MCP_BUNDLE_LEAN = 'lean';
+export const MCP_BUNDLE_FULL = 'full';
+
+export const LAUNCHER_SCHEMA_VERSION = 1;
+export const PROFILE_ISOLATION_CONTRACT_OWNER = 'profile-isolation-contract';
+export const PACKAGE_FILES_WHITELIST_SCRIPTS_ENTRY = 'scripts/';
+export const LIVE_DEPLOYMENT_RESERVED_FOR = 'L1';
+export const INSTALL_DESTINATION_ROOT_RELATIVE_PATH = 'scripts/profile-isolation-launchers';
+
+/**
+ * @returns {Record<string, unknown>}
+ */
+export function loadProfilesManifestDocument() {
+  return /** @type {Record<string, unknown>} */ (readJsonConfigFile(PROFILES_MANIFEST_FILE_NAME));
+}
+
+/**
+ * @returns {Record<string, unknown>}
+ */
+export function loadSharedAllowlistDocument() {
+  return /** @type {Record<string, unknown>} */ (readJsonConfigFile(SHARED_ALLOWLIST_FILE_NAME));
+}

package/scripts/profile-isolation-launchers/config/profiles.manifest.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "profilesRootPlaceholder": "${PROFILES_ROOT}",
+  "sharedSourcePlaceholder": "${SHARED_SOURCE_ROOT}",
+  "pluginSeedPlaceholder": "${PLUGIN_SEED_ROOT}",
+  "migrationOrder": ["profile-c", "profile-b", "profile-a", "master", "profile-d"],
+  "profiles": {
+    "master": {
+      "id": "master",
+      "aliases": ["default"],
+      "directoryName": "master",
+      "launcherNames": ["claude"],
+      "fullLauncherNames": ["claude-full"],
+      "migrationMode": "materialize-from-legacy",
+      "mcpBundle": "lean"
+    },
+    "profile-a": {
+      "id": "profile-a",
+      "aliases": [],
+      "directoryName": "profile-a",
+      "launcherNames": ["claude-profile-a"],
+      "fullLauncherNames": ["claude-profile-a-full"],
+      "migrationMode": "materialize-from-legacy",
+      "mcpBundle": "lean"
+    },
+    "profile-c": {
+      "id": "profile-c",
+      "aliases": [],
+      "directoryName": "profile-c",
+      "launcherNames": ["claude-profile-c"],
+      "fullLauncherNames": ["claude-profile-c-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    },
+    "profile-b": {
+      "id": "profile-b",
+      "aliases": [],
+      "directoryName": "profile-b",
+      "launcherNames": ["claude-profile-b"],
+      "fullLauncherNames": ["claude-profile-b-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    },
+    "profile-d": {
+      "id": "profile-d",
+      "aliases": [],
+      "directoryName": "profile-d",
+      "launcherNames": ["claude-profile-d"],
+      "fullLauncherNames": ["claude-profile-d-full"],
+      "migrationMode": "clean-local-runtime",
+      "mcpBundle": "lean"
+    }
+  }
+}