codexspec 0.7.16__tar.gz → 0.7.18__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.16
+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.16 → 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.16 → codexspec-0.7.18}/pyproject.toml

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

{codexspec-0.7.16 → 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.16 → 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.16 → codexspec-0.7.18}/src/codexspec/__init__.py

@@ -8,11 +8,13 @@ executable specifications that guide AI-assisted implementation.
 
 import json
 import re
+import secrets
 import subprocess
 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
@@ -43,6 +45,12 @@ from .commands.installer import (
     should_update_commands,
     update_installed_command_frontmatter,
 )
+from .distill_review.domain import ReviewError, ReviewService
+from .distill_review.lease import ActiveSessionError, ReviewLease
+from .distill_review.server import create_server
+from .distill_review.session import SessionError, SessionStore, ensure_runtime_ignored
+from .distill_review.terminal import localized_error, localized_result, run_text_review, safe_terminal
+from .distill_review.transaction import ProfileTransaction, TransactionError
 from .i18n import (
     generate_config_content,
     get_explicit_language_key,
@@ -56,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.16"
+__version__ = "0.7.18"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -74,6 +91,153 @@ 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"),
+    mode: str = typer.Option("html", "--mode"),
+    manifest: Optional[Path] = typer.Option(None, "--manifest"),
+    no_open: bool = typer.Option(False, "--no-open"),
+    discard_draft: bool = typer.Option(False, "--discard-draft"),
+) -> None:
+    """Run the deterministic local carrier used by the distill command."""
+    root = project_root.resolve()
+    language = get_interaction_language(root / ".codexspec" / "config.yml")
+    if mode not in {"html", "text"}:
+        _review_result(language, {"status": "invalid_input", "error": "invalid_mode"})
+        raise typer.Exit(2)
+    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:
+        lease.acquire({"state": "starting", "mode": mode})
+    except ActiveSessionError as exc:
+        # Machine output reports the running session, but its capability token and
+        # token-bearing URL belong to the session that printed them.
+        session = {key: value for key, value in exc.metadata.items() if key not in {"capability", "url"}}
+        _review_result(language, {"status": "active_session", "session": session})
+        return
+    except (AutomationError, SessionError, OSError) as exc:
+        _review_result(language, {"status": "invalid_input", "error": str(exc)})
+        raise typer.Exit(2) from exc
+    server = None
+    try:
+        try:
+            ProfileTransaction.recover(root, store)
+        except (TransactionError, SessionError, OSError):
+            if not discard_draft:
+                raise
+            # A failed recovery must not brick the documented escape hatch: an
+            # explicit discard abandons the draft and the stuck journal together.
+        if discard_draft:
+            store.discard()
+            store.discard_transaction()
+            _review_result(language, {"status": "discarded"})
+            return
+        draft = store.load()
+        service = ReviewService.from_project(
+            root,
+            manifest_path=manifest,
+            draft=draft,
+            interaction_language=language,
+        )
+    except (ReviewError, SessionError, TransactionError, OSError) as exc:
+        _review_result(language, {"status": "invalid_input", "error": str(exc)})
+        raise typer.Exit(2) from exc
+    if not service.records and not service.clusters and not (service.draft.decisions or service.draft.deferred):
+        _review_result(language, {"status": "nothing_to_review"})
+        return
+    try:
+        if mode == "text":
+            lease.update({"mode": "text"})
+            result = run_text_review(service, store)
+            typer.echo()
+            _machine_json(result)
+            return
+        token = secrets.token_urlsafe(32)
+        server = create_server(service, store, token=token)
+        url = f"http://127.0.0.1:{server.server_port}/#token={token}"
+        lease.update({"mode": "html", "port": server.server_port, "capability": token, "url": url})
+        try:
+            opened = False if no_open else webbrowser.open(url)
+        except (OSError, webbrowser.Error):
+            opened = False
+        if not opened:
+            typer.echo(url)
+        server.timeout = 0.5
+        while not server.stop_event.is_set():
+            server.handle_request()
+        _review_result(language, server.final_result or {"status": "finished"})
+    except (ReviewError, SessionError, TransactionError, OSError) as exc:
+        failure: dict[str, object] = {"status": "invalid_input", "error": str(exc)}
+        if isinstance(exc, TransactionError):
+            failure["records"] = exc.records
+            failure["failures"] = exc.failures
+        _review_result(language, failure)
+        raise typer.Exit(2) from exc
+    finally:
+        if server is not None:
+            server.server_close()
+        lease.release()
+
+
 def get_version() -> str:
     """Return the current version of codexspec."""
     return __version__
@@ -192,6 +356,25 @@ def _machine_json(value: object) -> None:
     sys.stdout.write(json.dumps(value, sort_keys=True, separators=(",", ":")) + "\n")
 
 
+def _review_result(language: str, value: dict[str, object]) -> None:
+    status = str(value.get("status", "invalid_input"))
+    if status in {"invalid_input", "conflict"}:
+        raw_records = value.get("records")
+        raw_failures = value.get("failures")
+        records = [str(item) for item in raw_records] if isinstance(raw_records, list) else None
+        failures = [str(item) for item in raw_failures] if isinstance(raw_failures, list) else None
+        message = localized_error(
+            language,
+            str(value.get("error", status)),
+            records=records,
+            failures=failures,
+        )
+    else:
+        message = localized_result(language, status)
+    typer.echo(safe_terminal(message))
+    _machine_json(value)
+
+
 def _stdin_json() -> dict:
     try:
         value = json.loads(sys.stdin.read() or "{}")
@@ -408,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.
@@ -443,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:
@@ -622,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"),
@@ -885,6 +1124,7 @@ def init(
     # so knowledge distilled later is effective immediately with no re-init and
     # no dangling reference. Non-destructive: existing profile files are kept.
     ensure_profile_scaffold(target_dir)
+    ensure_runtime_ignored(target_dir, install_managed_file=True)
 
     # Copy helper scripts based on platform
     scripts_source_dir = get_scripts_dir()
@@ -1109,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.
 
@@ -1118,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
@@ -1800,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.16 → 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]]:

codexspec-0.7.18/src/codexspec/distill_review/__init__.py

@@ -0,0 +1,13 @@
+"""Deterministic local review runtime for distilled profile knowledge."""
+
+from .domain import ReviewError, ReviewService
+from .records import RecordDocument, RecordError, discover_records, parse_record
+
+__all__ = [
+    "RecordDocument",
+    "RecordError",
+    "ReviewError",
+    "ReviewService",
+    "discover_records",
+    "parse_record",
+]