codexspec 0.7.17__tar.gz → 0.7.18__tar.gz

{codexspec-0.7.17 → codexspec-0.7.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.17
+Version: 0.7.18
 Summary: CodexSpec - A Requirements-First SDD toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -565,6 +565,7 @@ Implementation follows **conditional TDD workflow**:
 | `--list-langs`            | List all supported languages |
 | `--auto-next`            | Toggle/set `workflow.auto_next` (bare toggles; or on/off) |
 | `--auto-distill`         | Toggle/set `workflow.auto_distill` (default on; bare toggles; or on/off) |
+| `--worktrees`            | Toggle/set checkout-local worktree isolation (default on; bare toggles; or on/off) |
 
 </details>
 
@@ -837,3 +838,10 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 - Inspired by [GitHub spec-kit](https://github.com/github/spec-kit)
 - Built for [Claude Code](https://claude.ai/code)
+
+Ordinary features develop in separate worktrees under the main checkout's sibling
+`<repository-name>-codexspec-worktrees/`, starting before the first requirements write.
+Blueprint and auto-dev retain their fixed shared worktree. Standalone project edits
+use a maintenance worktree; settings take effect per checkout and reach other checkouts
+through Git integration. See [worktree development](docs/en/user-guide/workflow.md#worktree-development)
+and [configuration](docs/en/reference/configuration.md#workflowworktrees).

{codexspec-0.7.17 → codexspec-0.7.18}/README.md

@@ -520,6 +520,7 @@ Implementation follows **conditional TDD workflow**:
 | `--list-langs`            | List all supported languages |
 | `--auto-next`            | Toggle/set `workflow.auto_next` (bare toggles; or on/off) |
 | `--auto-distill`         | Toggle/set `workflow.auto_distill` (default on; bare toggles; or on/off) |
+| `--worktrees`            | Toggle/set checkout-local worktree isolation (default on; bare toggles; or on/off) |
 
 </details>
 
@@ -792,3 +793,10 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 - Inspired by [GitHub spec-kit](https://github.com/github/spec-kit)
 - Built for [Claude Code](https://claude.ai/code)
+
+Ordinary features develop in separate worktrees under the main checkout's sibling
+`<repository-name>-codexspec-worktrees/`, starting before the first requirements write.
+Blueprint and auto-dev retain their fixed shared worktree. Standalone project edits
+use a maintenance worktree; settings take effect per checkout and reach other checkouts
+through Git integration. See [worktree development](docs/en/user-guide/workflow.md#worktree-development)
+and [configuration](docs/en/reference/configuration.md#workflowworktrees).

{codexspec-0.7.17 → codexspec-0.7.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.7.17"
+version = "0.7.18"
 description = "CodexSpec - A Requirements-First SDD toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

{codexspec-0.7.17 → codexspec-0.7.18}/scripts/bash/create-new-feature.sh

@@ -50,6 +50,17 @@ if [ -z "$FEATURE_SUFFIX" ]; then
     exit 1
 fi
 
+# Resolve the switch before creating directories or changing Git state.
+if ! command_exists codexspec; then
+    log_error "CodexSpec runtime is unavailable. Install codexspec before creating a feature."
+    exit 1
+fi
+WORKTREE_SETTING=$(codexspec _worktree-helper setting) || exit $?
+case "$WORKTREE_SETTING" in
+    *'"enabled": false'*) ;; # Explicit opt-out retains the original in-place flow below.
+    *) exec codexspec _worktree-helper create --name "$FEATURE_SUFFIX" ;;
+esac
+
 TIMESTAMP=$(date +"%Y-%m%d-%H%M")
 RANDOM_SUFFIX=$(LC_ALL=C tr -dc 'a-z0-9' </dev/urandom | head -c 2)
 FEATURE_ID="${TIMESTAMP}${RANDOM_SUFFIX}"

{codexspec-0.7.17 → codexspec-0.7.18}/scripts/powershell/create-new-feature.ps1

@@ -132,6 +132,34 @@ if (-not $branchSuffix) {
     exit 1
 }
 
+# Resolve isolation before any feature directory or branch mutation.
+if (-not (Get-Command codexspec -ErrorAction SilentlyContinue)) {
+    Write-Error "CodexSpec runtime is unavailable. Install codexspec before creating a feature."
+    exit 1
+}
+$settingOutput = & codexspec _worktree-helper setting
+if ($LASTEXITCODE -ne 0) { Write-Output $settingOutput; exit $LASTEXITCODE }
+$setting = $settingOutput | ConvertFrom-Json
+if ($setting.enabled) {
+    $workspaceOutput = & codexspec _worktree-helper create --name $branchSuffix
+    $workspaceExit = $LASTEXITCODE
+    if ($workspaceExit -ne 0) { Write-Output $workspaceOutput; exit $workspaceExit }
+    $workspace = $workspaceOutput | ConvertFrom-Json
+    $env:CODEXSPEC_FEATURE = $workspace.branch
+    $result = [PSCustomObject]@{
+        BRANCH_NAME = $workspace.branch
+        REQUIREMENTS_FILE = $workspace.requirements_file
+        FEATURE_ID = $workspace.feature_id
+        WORKTREE_PATH = $workspace.workspace
+        HAS_GIT = $true
+        STATUS = $workspace.status
+        WARNINGS = $workspace.warnings
+    }
+    if ($Json) { $result | ConvertTo-Json -Compress }
+    else { $result | Format-List | Out-String | Write-Output }
+    exit 0
+}
+
 $specsDir = Join-Path $repoRoot '.codexspec/specs'
 New-Item -ItemType Directory -Path $specsDir -Force | Out-Null
 

{codexspec-0.7.17 → codexspec-0.7.18}/src/codexspec/__init__.py

@@ -14,7 +14,7 @@ import sys
 import webbrowser
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 import typer
 from rich.console import Console
@@ -64,9 +64,18 @@ from .i18n import (
 from .integrations import get_integrations
 from .profile import ensure_profile_scaffold, inject_profile_block
 from .translator import SUPPORTED_LANGUAGES, translate
+from .worktrees import (
+    MAINTENANCE_NAME,
+    WorkspaceManager,
+    feature_name,
+    read_worktrees,
+    validate_write_path,
+    write_destination,
+    write_worktrees,
+)
 
 # Version info
-__version__ = "0.7.17"
+__version__ = "0.7.18"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -82,6 +91,51 @@ app = typer.Typer(
 console = Console()
 
 
+@app.command("_worktree-helper", hidden=True)
+def worktree_helper(
+    action: str = typer.Argument(...),
+    name: Optional[str] = typer.Option(None, "--name"),
+    feature: Optional[str] = typer.Option(None, "--feature"),
+    verification: Optional[Path] = typer.Option(None, "--verification"),
+) -> None:
+    """Return structured workspace facts; never emit shell code for callers to evaluate."""
+    recovery: dict[str, Any] = {}
+    result: dict[str, Any]
+    try:
+        from .worktrees import checkout_root
+
+        root = checkout_root(Path.cwd())
+        if action == "setting":
+            result = {"enabled": read_worktrees(root / ".codexspec/config.yml")}
+        elif action == "route":
+            result = {"status": "ready", "workspace": str(write_destination(root))}
+        elif action == "create" and not read_worktrees(root / ".codexspec/config.yml"):
+            result = {"status": "disabled", "workspace": str(root.resolve())}
+        else:
+            manager = WorkspaceManager(root)
+            if action == "create":
+                if bool(name) == bool(feature):
+                    raise AutomationError("expected_name_or_feature")
+                identity = feature if feature else feature_name(name or "")
+                branch, path, _ = manager._identity(identity)
+                recovery = {"branch": branch, "workspace": str(path)}
+                result = manager.create(identity, reuse=feature is not None)
+            elif action == "resolve" and feature:
+                result = manager.resolve(feature)
+            elif action == "maintenance":
+                result = manager.create(MAINTENANCE_NAME)
+            elif action == "finish" and feature and verification:
+                result = manager.finish(feature, json.loads(verification.read_text(encoding="utf-8")))
+            else:
+                raise AutomationError("invalid_workspace_action", action)
+        print(json.dumps(result, ensure_ascii=False))
+        if result.get("status") in {"creating", "merge_requires_resolution", "merge_requires_verification"}:
+            raise typer.Exit(3)
+    except (AutomationError, OSError, ValueError) as exc:
+        print(json.dumps({**recovery, "status": "blocked", "error": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(1) from exc
+
+
 @app.command("_distill-review-helper", hidden=True)
 def distill_review_helper(
     project_root: Path = typer.Option(Path("."), "--project-root"),
@@ -99,6 +153,17 @@ def distill_review_helper(
     if not root.is_dir() or not (root / ".codexspec" / "profile").is_dir():
         _review_result(language, {"status": "invalid_input", "error": "invalid_project_root"})
         raise typer.Exit(2)
+    try:
+        root = write_destination(root)
+    except (AutomationError, OSError) as exc:
+        _review_result(language, {"status": "invalid_input", "error": str(exc)})
+        raise typer.Exit(2) from exc
+    language = get_interaction_language(root / ".codexspec" / "config.yml")
+    if not (root / ".codexspec" / "profile").is_dir():
+        _review_result(
+            language, {"status": "invalid_input", "error": "missing_destination_profile", "project_root": str(root)}
+        )
+        raise typer.Exit(2)
     store = SessionStore(root)
     lease = ReviewLease(root)
     try:
@@ -526,6 +591,9 @@ def config(
         "--auto-distill",
         help="Toggle workflow.auto_distill (bare), or set it (on/off|true/false|1/0|yes/no).",
     ),
+    worktrees: Optional[str] = typer.Option(
+        None, "--worktrees", help="Toggle checkout-local worktree isolation (default on), or set on/off."
+    ),
 ) -> None:
     """
     View or modify CodexSpec project configuration.
@@ -561,6 +629,58 @@ def config(
         console.print("Run [cyan]codexspec init[/cyan] to create a new project.")
         raise typer.Exit(1)
 
+    # Validate values before creating any destination workspace.
+    for value, sentinel, option in (
+        (auto_next, _AUTO_NEXT_SENTINEL, "--auto-next"),
+        (auto_distill, _AUTO_DISTILL_SENTINEL, "--auto-distill"),
+        (worktrees, "__toggle_worktrees__", "--worktrees"),
+    ):
+        if value is not None and value != sentinel:
+            try:
+                parse_auto_next_value(value)
+            except ValueError:
+                console.print(f"[red]Invalid {option} value:[/red] {value!r}")
+                raise typer.Exit(1)
+    modifying = any(
+        value is not None
+        for value in (
+            auto_next,
+            auto_distill,
+            worktrees,
+            set_lang,
+            set_commit_lang,
+            set_interaction_lang,
+            set_document_lang,
+        )
+    )
+    if modifying:
+        try:
+            isolated = read_worktrees(config_file)
+            destination = write_destination(config_file.parent.parent)
+            config_file = destination / ".codexspec" / "config.yml"
+            if isolated:
+                validate_write_path(destination, config_file)
+                if set_lang is not None or set_interaction_lang is not None:
+                    _validate_command_frontmatter(destination)
+            if not config_file.is_file():
+                raise AutomationError("missing_destination_config", str(config_file))
+            console.print(f"Configuration destination: {config_file}", markup=False, soft_wrap=True)
+            console.print("Changes apply to this checkout; other checkouts receive them through Git integration.")
+        except (AutomationError, OSError) as exc:
+            console.print(str(exc), markup=False)
+            raise typer.Exit(1) from exc
+    if worktrees is not None:
+        target = (
+            not read_worktrees(config_file) if worktrees == "__toggle_worktrees__" else parse_auto_next_value(worktrees)
+        )
+        try:
+            write_worktrees(config_file, target)
+        except (AutomationError, OSError) as exc:
+            console.print(str(exc), markup=False)
+            raise typer.Exit(1) from exc
+        console.print(f"workflow.worktrees = {str(target).lower()}")
+        return
+
     # Handle auto-next toggle/set
     if auto_next is not None:
         if auto_next == _AUTO_NEXT_SENTINEL:
@@ -740,6 +860,7 @@ def config(
         return
 
     # Display current configuration
+    console.print(f"Effective workflow.worktrees: {str(read_worktrees(config_file)).lower()}")
     console.print(
         Panel(
             config_file.read_text(encoding="utf-8"),
@@ -1228,6 +1349,15 @@ def init(
     console.print(f"[yellow]{_important_action(integrations, normalized_lang)}[/yellow]")
 
 
+def _validate_command_frontmatter(root: Path) -> None:
+    commands = root / ".claude" / "commands" / COMMANDS_SUBDIR
+    validate_write_path(root, commands)
+    if commands.exists() and not commands.is_dir():
+        raise AutomationError("unsafe_write_path", str(commands))
+    for command in commands.glob("*.md"):
+        validate_write_path(root, command)
+
+
 def _rerender_command_frontmatter(config_file: Path) -> None:
     """Re-render installed command frontmatter in the current interaction language.
 
@@ -1237,7 +1367,7 @@ def _rerender_command_frontmatter(config_file: Path) -> None:
     pre-translated cache are not re-rendered here (that path would invoke the
     ``claude`` CLI once per command); the user is advised to run ``codexspec init``.
     """
-    commands_subdir = Path.cwd() / ".claude" / "commands" / COMMANDS_SUBDIR
+    commands_subdir = config_file.parent.parent / ".claude" / "commands" / COMMANDS_SUBDIR
     if not commands_subdir.exists():
         return
     language = get_interaction_language(config_file)  # re-read AFTER the config write
@@ -1919,6 +2049,8 @@ def main() -> None:
         sys.argv = _normalize_auto_next_argv(sys.argv)
     if "--auto-distill" in sys.argv:
         sys.argv = _normalize_auto_distill_argv(sys.argv)
+    if "--worktrees" in sys.argv:
+        sys.argv = _normalize_optional_value_argv(sys.argv, "--worktrees", "__toggle_worktrees__")
     app()
 
 

{codexspec-0.7.17 → codexspec-0.7.18}/src/codexspec/automation.py

@@ -173,8 +173,12 @@ def locate_repository(cwd: Path | str, *, runner: GitRunner | None = None) -> Re
     current = Path(cwd).resolve()
     top = git.run(current, "rev-parse", "--show-toplevel", check=False)
     if top.returncode != 0:
-        raise AutomationError("not_git_repository")
-    invoking_root = Path(top.stdout.strip()).resolve()
+        bare = git.run(current, "rev-parse", "--is-bare-repository", check=False)
+        if bare.returncode != 0 or bare.stdout.strip() != "true":
+            raise AutomationError("not_git_repository")
+        invoking_root = Path(git.run(current, "rev-parse", "--absolute-git-dir").stdout.strip()).resolve()
+    else:
+        invoking_root = Path(top.stdout.strip()).resolve()
     worktrees = _parse_worktrees(git.run(invoking_root, "worktree", "list", "--porcelain").stdout)
     if not worktrees:
         raise AutomationError("worktree_registry_empty")
@@ -188,7 +192,7 @@ def locate_repository(cwd: Path | str, *, runner: GitRunner | None = None) -> Re
     default_branch = remote_branch or _local_default_branch(git, primary_root, worktrees[0].get("branch"))
     if remote_name and remote_ref is None:
         remote_ref = f"refs/remotes/{remote_name}/{default_branch}"
-    worktree_path = Path(f"{primary_root}-worktrees") / WORKTREE_BASENAME
+    worktree_path = Path(f"{primary_root}-codexspec-worktrees") / WORKTREE_BASENAME
     return RepositoryContext(
         repository_root=primary_root,
         common_git_dir=common_git_dir,
@@ -303,16 +307,22 @@ def _remote_default(git: GitRunner, root: Path) -> tuple[str | None, str | None,
     if symbolic.returncode != 0:
         return remote, None, None
     ref = symbolic.stdout.strip()
-    return remote, ref, ref.rsplit("/", 1)[-1]
+    return remote, ref, ref.removeprefix(f"refs/remotes/{remote}/")
 
 
 def _local_default_branch(git: GitRunner, root: Path, primary_branch_ref: str | None) -> str:
     for candidate in ("main", "master"):
         if git.run(root, "show-ref", "--verify", "--quiet", f"refs/heads/{candidate}", check=False).returncode == 0:
             return candidate
-    if primary_branch_ref and primary_branch_ref.startswith("refs/heads/"):
-        return primary_branch_ref.removeprefix("refs/heads/")
-    raise AutomationError("default_branch_not_found")
+    configured = git.run(root, "config", "--get", "init.defaultBranch", check=False).stdout.strip()
+    if (
+        configured
+        and git.run(root, "show-ref", "--verify", "--quiet", f"refs/heads/{configured}", check=False).returncode == 0
+    ):
+        return configured
+    raise AutomationError(
+        "default_branch_not_found", "Configure the remote default branch or a valid init.defaultBranch."
+    )
 
 
 def _parse_worktrees(output: str) -> list[dict[str, Any]]: