specsmith 0.21.0.dev787__tar.gz → 0.22.0__tar.gz

{specsmith-0.21.0.dev787/src/specsmith.egg-info → specsmith-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.21.0.dev787
+Version: 0.22.0
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -102,6 +102,8 @@ AI Agents / IDE Clients
 ## When to use / when not to use
 
 - Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage.
+- Use especially for larger projects where governance reduces token costs by 2-6x compared to ungoverned approaches (as demonstrated in our efficiency benchmarks)
+- Use with local LLMs like LMStudio, vLLM, or llama.cpp for maximum cost control and privacy
 - Avoid when rapid local prototyping is the only goal and formal governance is unnecessary.
 
 ## Comparison summary
@@ -124,8 +126,34 @@ We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/
 
 **Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179).
 
+## Current Stats
+
+- **52+ model profiles** in registry (including Qwen3.6-35B-A3B)
+- **127 canonical skills** available across all domains
+- **10 governance skills** (including improvement-reporter, agent-flow-controller, model-runtime-optimizer)
+- **Development mode** with improvement tracking and session analysis
+
+See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
+
+### Development Mode Features
+
+When enabled in project configuration, development mode provides:
+
+- **Enhanced logging** for all agent interactions and decision-making processes
+- **Session analysis** that tracks what worked, what didn't, and improvement suggestions
+- **Cost-per-correct-solution metrics** to measure efficiency
+- **Automated improvement tracking** to identify patterns and areas for optimization
+- **Session reports** that can be generated for review and analysis
+
+To enable development mode, set `enable_development_mode: true` in your project's `.specsmith/config.yml` file.
+
 See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
 
+**v0.22.0** - Epistemic chat handoffs preserve source provenance for Zoo-Code and
+other agents, while a mergeable JSONL session-event log keeps collaboration state
+reviewable. This release also adds CPU-safe local-model fallback (REQ-445) and
+stable-release validation before PyPI publishing.
+
 **v0.20.0** — Native Warp integration: `specsmith integrate warp` scaffolds `.warp/` MCP + launch configs and a Warp-aware `specsmith run` banner (REQ-444). Plus VRAM-aware local model recommendations: `specsmith local-model recommend` prints a per-role lineup (default / fast / harder pass / general) with a `fits`/`tight`/`spills` fit assessment (REQ-445).
 
 **v0.19.x** — `specsmith wi link-test`, the governance-YAML content auditor and sync markdown-reconcile warnings, and a HuggingFace provider + 15-model multi-provider benchmark matrix for GovernanceBench.
@@ -148,6 +176,7 @@ specsmith ollama gpu                        # detect GPU VRAM, recommend context
 specsmith local-model recommend            # VRAM-aware model lineup (fits/tight/spills)
 specsmith integrate warp                    # scaffold Warp-native governance (MCP + launch config)
 specsmith export                            # generate full compliance report
+specsmith endpoints add lmstudio            # add LMStudio endpoint for BYOE support
 
 # Update channels
 specsmith channel set stable               # pin to stable releases
@@ -215,17 +244,6 @@ specsmith phase list     # list all phases
 The current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist
 of file/command criteria, recommended commands, and a readiness percentage.
 
-## 1.0 release criteria status
-
-| Criterion | Status | Source |
-|---|---|---|
-| Stable CLI core contract documented | In progress | `docs/stability.md` |
-| Stable generated file schemas documented | In progress | `docs/stability.md` |
-| Stable MCP tool schemas documented | In progress | `docs/stability.md` |
-| Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` |
-| Security threat model documented | In progress | `docs/security-threat-model.md` |
-| Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` |
-| Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` |
 
 ---
 
@@ -353,6 +371,14 @@ specsmith phase                          # current phase + readiness %
 specsmith audit                          # full governance health check
 ```
 
+> **Session Bootstrap**: For a more streamlined session start, you can also use:
+> ```bash
+> specsmith load                           # run migrate, audit, sync, and checkpoint in sequence
+> ```
+> This command combines the essential bootstrap steps for a clean session start.
+>
+> **Note**: The `specsmith load` command is particularly useful for quickly setting up a new session with all governance checks in place.
+
 > **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.
 > Every utterance is preflighted automatically. Use `/why` to see the governance trace.
 > For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
@@ -1130,6 +1156,16 @@ specsmith skill install specsmith-audit
 
 Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
 
+### Skill Policy
+
+If a skill is reusable across projects, it belongs in `src/specsmith/skills/<domain>.py`.
+
+If a skill is project-specific, generated by the user, or experimental, it belongs in `.specsmith/skills/<skill-id>/`.
+
+If a skill needs to be read by Claude Code, Warp, Cursor, Aider, etc., it is exported/materialized into `.agents/skills/<slug>/SKILL.md`.
+
+Do not hand-edit `.agents/skills/` as a canonical source.
+
 ### Skill domains
 
 | Domain | Count | Coverage |
@@ -1388,7 +1424,6 @@ command reference, project types, tool registry, governance model, ESDB, skills
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
 - [Stability Contract](https://github.com/layer1labs/specsmith/blob/develop/docs/stability.md)
-- [1.0 Release Criteria](https://github.com/layer1labs/specsmith/blob/develop/docs/roadmap/1.0-criteria.md)
 - [Editions Matrix](https://github.com/layer1labs/specsmith/blob/develop/docs/editions.md)
 - [Changelog](https://github.com/layer1labs/specsmith/blob/develop/CHANGELOG.md)
 - [Contributing](https://github.com/layer1labs/specsmith/blob/develop/CONTRIBUTING.md)

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/README.md

@@ -24,6 +24,8 @@ AI Agents / IDE Clients
 ## When to use / when not to use
 
 - Use when you need governed AI development, auditable decision trails, and requirement-to-test linkage.
+- Use especially for larger projects where governance reduces token costs by 2-6x compared to ungoverned approaches (as demonstrated in our efficiency benchmarks)
+- Use with local LLMs like LMStudio, vLLM, or llama.cpp for maximum cost control and privacy
 - Avoid when rapid local prototyping is the only goal and formal governance is unnecessary.
 
 ## Comparison summary
@@ -46,8 +48,34 @@ We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/
 
 **Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179).
 
+## Current Stats
+
+- **52+ model profiles** in registry (including Qwen3.6-35B-A3B)
+- **127 canonical skills** available across all domains
+- **10 governance skills** (including improvement-reporter, agent-flow-controller, model-runtime-optimizer)
+- **Development mode** with improvement tracking and session analysis
+
+See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
+
+### Development Mode Features
+
+When enabled in project configuration, development mode provides:
+
+- **Enhanced logging** for all agent interactions and decision-making processes
+- **Session analysis** that tracks what worked, what didn't, and improvement suggestions
+- **Cost-per-correct-solution metrics** to measure efficiency
+- **Automated improvement tracking** to identify patterns and areas for optimization
+- **Session reports** that can be generated for review and analysis
+
+To enable development mode, set `enable_development_mode: true` in your project's `.specsmith/config.yml` file.
+
 See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
 
+**v0.22.0** - Epistemic chat handoffs preserve source provenance for Zoo-Code and
+other agents, while a mergeable JSONL session-event log keeps collaboration state
+reviewable. This release also adds CPU-safe local-model fallback (REQ-445) and
+stable-release validation before PyPI publishing.
+
 **v0.20.0** — Native Warp integration: `specsmith integrate warp` scaffolds `.warp/` MCP + launch configs and a Warp-aware `specsmith run` banner (REQ-444). Plus VRAM-aware local model recommendations: `specsmith local-model recommend` prints a per-role lineup (default / fast / harder pass / general) with a `fits`/`tight`/`spills` fit assessment (REQ-445).
 
 **v0.19.x** — `specsmith wi link-test`, the governance-YAML content auditor and sync markdown-reconcile warnings, and a HuggingFace provider + 15-model multi-provider benchmark matrix for GovernanceBench.
@@ -70,6 +98,7 @@ specsmith ollama gpu                        # detect GPU VRAM, recommend context
 specsmith local-model recommend            # VRAM-aware model lineup (fits/tight/spills)
 specsmith integrate warp                    # scaffold Warp-native governance (MCP + launch config)
 specsmith export                            # generate full compliance report
+specsmith endpoints add lmstudio            # add LMStudio endpoint for BYOE support
 
 # Update channels
 specsmith channel set stable               # pin to stable releases
@@ -137,17 +166,6 @@ specsmith phase list     # list all phases
 The current phase is persisted in `scaffold.yml` as `aee_phase`. Each phase has a checklist
 of file/command criteria, recommended commands, and a readiness percentage.
 
-## 1.0 release criteria status
-
-| Criterion | Status | Source |
-|---|---|---|
-| Stable CLI core contract documented | In progress | `docs/stability.md` |
-| Stable generated file schemas documented | In progress | `docs/stability.md` |
-| Stable MCP tool schemas documented | In progress | `docs/stability.md` |
-| Migration tests linked (#218) | In progress | `docs/roadmap/1.0-criteria.md` |
-| Security threat model documented | In progress | `docs/security-threat-model.md` |
-| Docs/tutorial/glossary baseline complete | In progress | `docs/roadmap/1.0-criteria.md` |
-| Upgrade path and changelog criteria defined | In progress | `docs/roadmap/1.0-criteria.md` |
 
 ---
 
@@ -275,6 +293,14 @@ specsmith phase                          # current phase + readiness %
 specsmith audit                          # full governance health check
 ```
 
+> **Session Bootstrap**: For a more streamlined session start, you can also use:
+> ```bash
+> specsmith load                           # run migrate, audit, sync, and checkpoint in sequence
+> ```
+> This command combines the essential bootstrap steps for a clean session start.
+>
+> **Note**: The `specsmith load` command is particularly useful for quickly setting up a new session with all governance checks in place.
+
 > **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.
 > Every utterance is preflighted automatically. Use `/why` to see the governance trace.
 > For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
@@ -1052,6 +1078,16 @@ specsmith skill install specsmith-audit
 
 Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
 
+### Skill Policy
+
+If a skill is reusable across projects, it belongs in `src/specsmith/skills/<domain>.py`.
+
+If a skill is project-specific, generated by the user, or experimental, it belongs in `.specsmith/skills/<skill-id>/`.
+
+If a skill needs to be read by Claude Code, Warp, Cursor, Aider, etc., it is exported/materialized into `.agents/skills/<slug>/SKILL.md`.
+
+Do not hand-edit `.agents/skills/` as a canonical source.
+
 ### Skill domains
 
 | Domain | Count | Coverage |
@@ -1310,7 +1346,6 @@ command reference, project types, tool registry, governance model, ESDB, skills
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
 - [Stability Contract](https://github.com/layer1labs/specsmith/blob/develop/docs/stability.md)
-- [1.0 Release Criteria](https://github.com/layer1labs/specsmith/blob/develop/docs/roadmap/1.0-criteria.md)
 - [Editions Matrix](https://github.com/layer1labs/specsmith/blob/develop/docs/editions.md)
 - [Changelog](https://github.com/layer1labs/specsmith/blob/develop/CHANGELOG.md)
 - [Contributing](https://github.com/layer1labs/specsmith/blob/develop/CONTRIBUTING.md)

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.21.0.dev787"
+version = "0.22.0"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.20.1"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.22.0"  # fallback: keep in sync with pyproject.toml

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/src/specsmith/advanced_code_analysis.py

@@ -174,7 +174,7 @@ class AdvancedCodeAnalyzer:
                                 ),
                             )
                         )
-        except Exception:
+        except Exception:  # noqa: BLE001  # intentional: fire-and-forget analysis; log is written above
             pass
 
         return reports

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/src/specsmith/agent/cleanup.py

@@ -249,7 +249,7 @@ def _consolidate_governance_files(root: Path) -> list[str]:
             reqs_yaml_dir = root / "docs" / "requirements"
             reqs_yaml_dir.mkdir(parents=True, exist_ok=True)
             consolidated.append("Consolidated requirements to YAML structure")
-        except Exception:
+        except Exception:  # noqa: BLE001  # intentional: fire-and-forget cleanup; log is written above
             pass
 
     if tests_dir.exists() and tests_dir.is_dir():
@@ -258,7 +258,7 @@ def _consolidate_governance_files(root: Path) -> list[str]:
             tests_yaml_dir = root / "docs" / "tests"
             tests_yaml_dir.mkdir(parents=True, exist_ok=True)
             consolidated.append("Consolidated tests to YAML structure")
-        except Exception:
+        except Exception:  # noqa: BLE001  # intentional: fire-and-forget cleanup; log is written above
             pass
 
     return consolidated

specsmith-0.22.0/src/specsmith/chat_handoff.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Evidence-preserving chat compaction and portable agent handoffs (REQ-446)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+SCHEMA_VERSION = 1
+_MAX_EXCERPT = 280
+
+
+def build_handoff(
+    history: list[dict[str, Any]],
+    *,
+    work_item_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build an extractive, provenance-preserving envelope from chat turns.
+
+    This deliberately does not ask an LLM to invent a prose summary.  Each
+    compacted claim remains a bounded excerpt linked to a deterministic turn ID,
+    allowing another agent to inspect the original history before relying on it.
+    """
+    turns: list[dict[str, str]] = []
+    for index, turn in enumerate(history):
+        role = turn.get("role")
+        content = turn.get("content")
+        if not isinstance(role, str) or not isinstance(content, str) or not content.strip():
+            continue
+        canonical = json.dumps(
+            {"role": role, "content": content}, sort_keys=True, ensure_ascii=False
+        )
+        source_id = f"turn:{hashlib.sha256(canonical.encode('utf-8')).hexdigest()[:16]}"
+        turns.append(
+            {
+                "source_id": source_id,
+                "role": role,
+                "excerpt": content.strip()[:_MAX_EXCERPT],
+                "position": str(index),
+            },
+        )
+
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "kind": "epistemic_chat_handoff",
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "confidence": 1.0,
+        "uncertainty": "Extractive envelope; excerpts are not inferred claims.",
+        "work_item_ids": sorted(set(work_item_ids or [])),
+        "turns": turns,
+    }
+    fingerprint = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    digest = hashlib.sha256(fingerprint.encode("utf-8")).hexdigest()[:16].upper()
+    payload["id"] = f"HANDOFF-{digest}"
+    validate_handoff(payload)
+    return payload
+
+
+def validate_handoff(payload: dict[str, Any]) -> None:
+    """Reject malformed or unsupported handoff claims before persistence/import."""
+    if (
+        payload.get("schema_version") != SCHEMA_VERSION
+        or payload.get("kind") != "epistemic_chat_handoff"
+    ):
+        raise ValueError("unsupported handoff schema")
+    if not isinstance(payload.get("id"), str) or not payload["id"].startswith("HANDOFF-"):
+        raise ValueError("handoff must have a stable ID")
+    if payload.get("confidence") != 1.0:
+        raise ValueError("extractive handoffs must retain confidence 1.0")
+    for turn in payload.get("turns", []):
+        if not isinstance(turn, dict) or not isinstance(turn.get("source_id"), str):
+            raise ValueError("handoff turn is missing provenance")
+        if not isinstance(turn.get("excerpt"), str) or len(turn["excerpt"]) > _MAX_EXCERPT:
+            raise ValueError("handoff excerpt is invalid")
+
+
+def render_handoff_context(payload: dict[str, Any]) -> str:
+    """Render a bounded context entry that tells agents how to verify it."""
+    validate_handoff(payload)
+    excerpts = "\n".join(
+        f"- [{turn['source_id']}] {turn['role']}: {turn['excerpt']}" for turn in payload["turns"]
+    )
+    return (
+        f"[Epistemic handoff {payload['id']} | {len(payload['turns'])} extractive turns | "
+        "verify source IDs before treating excerpts as decisions]\n"
+        f"{excerpts}"
+    )
+
+
+def store_handoff(root: Any, payload: dict[str, Any]) -> None:
+    """Persist a validated handoff in the active ESDB backend."""
+    validate_handoff(payload)
+    from specsmith.esdb import SqliteRecord, open_default_store
+
+    with open_default_store(root) as store:
+        store.upsert(
+            SqliteRecord(
+                id=payload["id"],
+                kind="chat_handoff",
+                label="Epistemic chat handoff",
+                confidence=1.0,
+                data=payload,
+            ),
+        )

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/src/specsmith/cli.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 import contextlib
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -189,13 +190,17 @@ def _maybe_prompt_project_update() -> None:
 
         if installed < project:
             # Backward migration (downgrade) — hard error, REQ-370.
+            from specsmith.updater import version_mismatch_remediation
+
+            remedy = version_mismatch_remediation(project_ver)
             click.echo(
                 f"\nERROR: specsmith downgrade detected.\n"
                 f"  Project spec_version : {project_ver}\n"
                 f"  Installed specsmith  : {__version__} (older)\n"
                 "\n"
                 "  Backward migration is not supported.\n"
-                "  Upgrade specsmith first: pipx upgrade specsmith\n"
+                f"  Install the required version: {remedy}\n"
+                "  Stable projects can instead use: pipx upgrade specsmith\n"
                 "  Then re-run this command.",
                 err=True,
             )
@@ -595,8 +600,19 @@ def _load_config_with_inheritance(config_path: str) -> dict[str, object]:
 VCS_PLATFORM_CHOICES = {"1": "github", "2": "gitlab", "3": "bitbucket", "4": ""}
 VCS_PLATFORM_LABELS = {"1": "GitHub", "2": "GitLab", "3": "Bitbucket", "4": "None"}
 
-BRANCH_STRATEGY_CHOICES = {"1": "gitflow", "2": "trunk-based", "3": "github-flow"}
-BRANCH_STRATEGY_LABELS = {"1": "Gitflow", "2": "Trunk-based", "3": "GitHub Flow"}
+BRANCH_STRATEGY_CHOICES = {
+    "1": "single-branch",
+    "2": "gitflow",
+    "3": "trunk-based",
+    "4": "github-flow",
+}
+BRANCH_STRATEGY_LABELS = {
+    "1": "Single branch (direct governed work on main)",
+    "2": "Gitflow",
+    "3": "Trunk-based",
+    "4": "GitHub Flow",
+}
+_BRANCH_WORKFLOWS = tuple(BRANCH_STRATEGY_CHOICES.values())
 
 
 def _interactive_config(no_git: bool) -> ProjectConfig:
@@ -631,7 +647,7 @@ def _interactive_config(no_git: bool) -> ProjectConfig:
     for k, v in BRANCH_STRATEGY_LABELS.items():
         console.print(f"  {k}. {v}")
     branch_choice = click.prompt("Select strategy", default="1")
-    branching_strategy = BRANCH_STRATEGY_CHOICES.get(branch_choice, "gitflow")
+    branching_strategy = BRANCH_STRATEGY_CHOICES.get(branch_choice, "single-branch")
 
     return ProjectConfig(
         name=name,
@@ -1881,6 +1897,17 @@ def doctor(project_dir: str, onboarding: bool, as_json: bool) -> None:
         ok, detail = _tool_version(tool)
         _add(tool, ok, detail)
 
+    if _is_windows_platform():
+        from specsmith.updater import find_windows_launchers
+
+        launchers = find_windows_launchers(__import__("os").environ.get("PATH", ""))
+        _add(
+            "specsmith launchers",
+            len(launchers) <= 1,
+            str(launchers[0]) if len(launchers) == 1 else f"{len(launchers)} found; use pipx only",
+            warn=len(launchers) > 1,
+        )
+
     overall = "pass" if all(c["status"] != "fail" for c in checks) else "fail"
 
     if as_json:
@@ -1899,6 +1926,11 @@ def doctor(project_dir: str, onboarding: bool, as_json: bool) -> None:
         console.print("One or more checks failed.")
 
 
+def _is_windows_platform() -> bool:
+    """Return whether the CLI is running on Windows."""
+    return sys.platform == "win32"
+
+
 @main.command()
 @click.option(
     "--project-dir",
@@ -3634,12 +3666,12 @@ def branch_create(name: str, project_dir: str) -> None:
     """Create a branch following the branching strategy."""
     root = Path(project_dir).resolve()
     scaffold_path = root / "scaffold.yml"
-    strategy = "gitflow"
+    strategy = "single-branch"
     main_branch = "main"
     if scaffold_path.exists():
         with open(scaffold_path) as f:
             raw = yaml.safe_load(f) or {}
-        strategy = raw.get("branching_strategy", "gitflow")
+        strategy = raw.get("branching_strategy", "single-branch")
         main_branch = raw.get("default_branch", "main")
 
     from specsmith.vcs_commands import create_branch
@@ -3648,7 +3680,34 @@ def branch_create(name: str, project_dir: str) -> None:
     if result.success:
         console.print(f"[green]\u2713[/green] {result.message}")
     else:
-        console.print(f"[red]\u2717[/red] {result.message}")
+        raise click.ClickException(result.message)
+
+
+@branch_group.command(name="workflow")
+@click.argument("strategy", required=False, type=click.Choice(_BRANCH_WORKFLOWS))
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def branch_workflow(strategy: str | None, project_dir: str) -> None:
+    """Show or explicitly select the governed branching workflow."""
+    root = Path(project_dir).resolve()
+    scaffold_path = root / "scaffold.yml"
+    if not scaffold_path.exists():
+        raise click.ClickException(
+            "No scaffold.yml found; run specsmith init before selecting a workflow."
+        )
+
+    with scaffold_path.open(encoding="utf-8") as handle:
+        raw = yaml.safe_load(handle) or {}
+    current = str(raw.get("branching_strategy", "single-branch"))
+    if strategy is None:
+        console.print(f"Branch workflow: {current}")
+        return
+
+    raw["branching_strategy"] = strategy
+    scaffold_path.write_text(
+        yaml.safe_dump(raw, default_flow_style=False, sort_keys=False),
+        encoding="utf-8",
+    )
+    console.print(f"[green]\u2713[/green] Branch workflow set to {strategy}")
 
 
 @branch_group.command(name="list")
@@ -3789,6 +3848,13 @@ def channel_set_cmd(channel: str) -> None:
     immediately for all subsequent ``specsmith self-update`` / ``update`` calls.
     """
     from specsmith.channel import set_persisted_channel
+    from specsmith.updater import is_prerelease_version, version_mismatch_remediation
+
+    if channel == "stable" and is_prerelease_version(__version__):
+        raise click.UsageError(
+            "Cannot select stable while a prerelease is installed. "
+            f"Install a stable build first: {version_mismatch_remediation('0.22.0')}"
+        )
 
     set_persisted_channel(channel)
     channel_color = "cyan" if channel == "dev" else "green"
@@ -14446,5 +14512,77 @@ def ai_analyze_cmd(project_dir: str, as_json: bool) -> None:
         raise SystemExit(1) from e
 
 
+# Development mode and improvement tracking commands
+@main.group(name="dev", invoke_without_command=True)
+def dev_group() -> None:
+    """Development mode and improvement tracking commands."""
+    pass
+
+
+@dev_group.command(name="session-report")
+@click.option(
+    "--session-id",
+    type=str,
+    default=None,
+    help="Session ID to report on (default: latest session).",
+)
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True),
+    default=".",
+    help="Project root directory.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit results as JSON.",
+)
+def dev_session_report_cmd(session_id: str | None, project_dir: str, as_json: bool) -> None:
+    """Generate a session report with improvement analysis."""
+    from pathlib import Path
+
+    from specsmith.improvement_tracker import ImprovementTracker
+
+    root = Path(project_dir).resolve()
+    tracker = ImprovementTracker(root)
+
+    if as_json:
+        # Return JSON output
+        import json as _json
+
+        if session_id:
+            analysis = tracker.get_session_analysis(session_id)
+            if analysis:
+                click.echo(_json.dumps(analysis.model_dump(), indent=2))
+            else:
+                click.echo(_json.dumps({"error": "Session not found"}, indent=2))
+        else:
+            # Get latest session
+            # For simplicity, we'll just list recent sessions
+            improvements = tracker.get_recent_improvements(10)
+            result = {"recent_improvements": [imp.model_dump() for imp in improvements]}
+            click.echo(_json.dumps(result, indent=2))
+    else:
+        # Return human-readable output
+        if session_id:
+            analysis = tracker.get_session_analysis(session_id)
+            if analysis:
+                report = tracker.generate_session_report(session_id)
+                click.echo(report)
+            else:
+                click.echo(f"Session {session_id} not found.")
+        else:
+            # Show recent improvements
+            improvements = tracker.get_recent_improvements(10)
+            if improvements:
+                click.echo("Recent Improvements:")
+                for imp in improvements:
+                    click.echo(f"  - {imp.description} ({imp.severity})")
+            else:
+                click.echo("No recent improvements recorded.")
+
+
 if __name__ == "__main__":
     main()

{specsmith-0.21.0.dev787 → specsmith-0.22.0}/src/specsmith/commands/zoo_code.py

@@ -22,6 +22,25 @@ def zoo_code_group() -> None:
     """Manage Zoo-Code integration and benchmarking for Specsmith."""
 
 
+@zoo_code_group.command("export-handoff")
+@click.option("--project-dir", default=".", help="Governed project containing session state")
+@click.option("--output", type=click.Path(), required=True, help="Portable handoff JSON path")
+def zoo_code_export_handoff(project_dir: str, output: str) -> None:
+    """Export the latest session as a validated portable agent handoff."""
+    from specsmith.chat_handoff import build_handoff
+    from specsmith.session_store import load_session
+
+    root = Path(project_dir)
+    context, history = load_session(root)
+    handoff = build_handoff(history, work_item_ids=list((context or {}).get("work_item_ids", [])))
+    output_path = Path(output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(
+        json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    click.echo(f"Exported epistemic handoff {handoff['id']} to {output_path}")
+
+
 @zoo_code_group.command("init")
 @click.option("--output-dir", default=".", help="Directory to create Zoo-Code config files")
 def zoo_code_init(output_dir: str) -> None: