create-forge 0.4.0__tar.gz → 0.5.0__tar.gz

{create_forge-0.4.0 → create_forge-0.5.0}/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
 Generated by git-cliff from Conventional Commits.
+## [0.5.0] - 2026-09-21
+
+### Bug Fixes
+
+- Contain every engine-update filesystem target (CF-22.01) (#207)
+- Recover failed updates from the actual Git state (CF-22.02) (#208)
+- Capture subprocess output as bytes and decode by explicit rule (CF-23.01) (#215)
+
+### Documentation
+
+- Record create-forge 0.4.0 publication evidence (CF-18.07) (#185)
+
+### Testing
+
+- Validate installed Streamlit generation and document usage (CF-21.02) (#187)
+- Verify update safety through the installed console (CF-22.03) (#210)
 ## [0.4.0] - 2026-09-14
 
 ### Documentation

{create_forge-0.4.0 → create_forge-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: create-forge
-Version: 0.4.0
+Version: 0.5.0
 Summary: Scaffold modern Python projects from maintained templates.
 Project-URL: Homepage, https://github.com/Sandsy09/create-forge
 Project-URL: Repository, https://github.com/Sandsy09/create-forge
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: forge-template<0.6,>=0.5
+Requires-Dist: forge-template<0.7,>=0.6
 Requires-Dist: pydantic>=2.10
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0
@@ -170,9 +170,10 @@ uv run poe check
 `update` runs the engine-native Git-backed three-way merge against the
 project's committed `.forge/generation.json`. Review the resulting diff and
 resolve any conflict markers before committing. `--dry-run` prints the
-per-target classification without writing anything; a failed or interrupted
-update always leaves a recoverable working tree, printed on request:
-`git restore . && git clean -fd`.
+per-target classification without writing anything. A failed or interrupted
+update leaves a working tree you can restore to your last commit — the
+[updates guide](https://sandsy09.github.io/create-forge/updates/) has the
+recovery procedure, including for an update that is already staged.
 
 ## The `--legacy` Copier route
 

{create_forge-0.4.0 → create_forge-0.5.0}/README.md

@@ -136,9 +136,10 @@ uv run poe check
 `update` runs the engine-native Git-backed three-way merge against the
 project's committed `.forge/generation.json`. Review the resulting diff and
 resolve any conflict markers before committing. `--dry-run` prints the
-per-target classification without writing anything; a failed or interrupted
-update always leaves a recoverable working tree, printed on request:
-`git restore . && git clean -fd`.
+per-target classification without writing anything. A failed or interrupted
+update leaves a working tree you can restore to your last commit — the
+[updates guide](https://sandsy09.github.io/create-forge/updates/) has the
+recovery procedure, including for an update that is already staged.
 
 ## The `--legacy` Copier route
 

{create_forge-0.4.0 → create_forge-0.5.0}/docs/README.md

@@ -40,7 +40,7 @@ still usually cites the ADR that authorised it.
 
 | Contract | Governs |
 | --- | --- |
-| [filesystem-generation.md](filesystem-generation.md) | Destination-conflict, staging, finalisation, and cleanup rules in `staging.py` (ADR 0015). |
+| [filesystem-generation.md](filesystem-generation.md) | Destination-conflict, staging, finalisation, and cleanup rules in `staging.py` (ADR 0015), and the shared target-safety boundary in `paths.py` that both generation and engine-native `update` resolve every engine-supplied path through (ADR 0052). |
 | [end-to-end-tests.md](end-to-end-tests.md) | The fast/`network`/`e2e` test-tier split and what the real console script is proven to do (ADR 0016). |
 
 ## Validation records
@@ -55,6 +55,9 @@ Acceptance-checklist-to-named-test maps, each closing an epic or a release.
 | [release-0-3-0-validation.md](release-0-3-0-validation.md) | The published `create-forge 0.3.0` / `forge-template 0.4.1` pair verified against its own artefacts (ADR 0034). |
 | [engine-cutover-validation.md](engine-cutover-validation.md) | The installed-console cutover acceptance matrix's remaining rows, and the rewritten user guide (ADR 0048). |
 | [release-0-4-0-validation.md](release-0-4-0-validation.md) | The published `create-forge 0.4.0` / `forge-template 0.5.0` pair verified against its own artefacts, and the Engine-Default Cutover roadmap close-out (ADR 0049). |
+| [installed-streamlit-validation.md](installed-streamlit-validation.md) | The four accepted Streamlit compositions, the previous-line provider, and the Streamlit failure cases through the installed candidate wheel (ADR 0051). |
+| [subprocess-output.md](subprocess-output.md) | How every process the client starts is captured as bytes and decoded by an explicit rule (diagnostic, protocol, path/binary), the site inventory, the worker's UTF-8 wire format, and the test-harness rule (ADR 0055). |
+| [update-safety-validation.md](update-safety-validation.md) | Update containment and recovery proven through the installed candidate wheel, the candidate's hashes and safety-relevant source digest, and CF-21.03's release prerequisite (ADR 0054). |
 
 ## Process and security
 

{create_forge-0.4.0 → create_forge-0.5.0}/docs/adr/README.md

@@ -52,6 +52,13 @@ format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
 - [0047 — Reject a pre-cutover `--engine-preview` project with one diagnostic, add no migration helper, and keep the Copier route reachable without a usable engine](0047-legacy-copier-retention-and-preview-transition.md)
 - [0048 — Complete the installed cutover acceptance evidence and the user guide's post-cutover voice](0048-installed-cutover-acceptance-evidence.md)
 - [0049 — Publish create-forge 0.4.0 and close the Engine-Default Cutover roadmap](0049-publish-0-4-0-and-close-roadmap-v3.md)
+- [0050 — Adopt the forge-template 0.6 Streamlit provider line](0050-adopt-the-0-6-streamlit-provider-line.md)
+- [0051 — Validate Streamlit through the installed create-forge candidate](0051-validate-installed-streamlit-generation.md)
+- [0052 — Contain every client filesystem target behind one shared boundary](0052-contain-every-client-filesystem-target.md)
+- [0053 — Recover a failed update from the repository's actual Git state](0053-recover-updates-from-the-actual-git-state.md)
+- [0054 — Verify update safety through the installed console, and bind it to the release candidate](0054-verify-installed-update-safety-on-the-release-candidate.md)
+- [0055 — Capture subprocess output as bytes, and decode it by an explicit rule](0055-capture-subprocess-output-as-bytes-and-decode-by-rule.md)
+- [0056 — Publish create-forge 0.5.0 and close the Streamlit roadmap's client work](0056-publish-create-forge-0-5-0.md)
 
 Add a new record by copying the most recent one and incrementing the number.
 Records are immutable: supersede them rather than editing.

{create_forge-0.4.0 → create_forge-0.5.0}/docs/roadmap-v3/README.md

@@ -2,22 +2,24 @@
 
 ## Status
 
-Filed and open. This pack records 5 repository-owned epics and
+Filed and delivered. This pack recorded 5 repository-owned epics and
 21 children for Stages 15–18, with verified issue numbers, labels,
-milestones, native parents and direct dependencies. No release or runtime
-implementation is claimed by these planning documents.
+milestones, native parents and direct dependencies. The filed manifest, the
+issue bodies, and `scripts/check_roadmaps.py`'s expected output stay
+unchanged (`filed-open`) by design — completion is recorded in prose here
+and in the evidence record below, not in the pack's own filing status; see
+ADR 0049 decision 5.
 
-The `create-forge`-side implementation this pack planned is complete on
-`main`: CF-18.01 through CF-18.06 shipped the engine-default cutover, and
-CF-18.07 ([#164](https://github.com/Sandsy09/create-forge/issues/164), ADR
-0049) is publishing it as `create-forge 0.4.0`, gated on
-[FT-18.01](https://github.com/Sandsy09/forge-template/issues/156)'s
-provider-side integrated validation. See `docs/release-0-4-0-validation.md`
-for the publication evidence once it lands.
+The engine-default cutover this pack planned has shipped:
+[FT-18.01](https://github.com/Sandsy09/forge-template/issues/156) closed the
+provider-side integrated validation, and CF-18.07
+([#164](https://github.com/Sandsy09/create-forge/issues/164), ADR 0049)
+published it as **`create-forge 0.4.0`**. See
+`docs/release-0-4-0-validation.md` for the full publication evidence and
+roadmap reconciliation.
 
 Working engine-native updates and continued support for existing Copier
-projects gate the engine-default release. Detailed architecture remains
-subject to the explicit decision children.
+projects gated the engine-default release; both shipped.
 
 ## Read this pack
 

{create_forge-0.4.0 → create_forge-0.5.0}/docs/roadmap-v3/roadmap/18-engine-default-client-delivery-and-validation/README.md

@@ -2,15 +2,16 @@
 
 ## Status and epics
 
-Filed and open.
-[CF-EPIC-18](https://github.com/Sandsy09/create-forge/issues/153),
-[FT-EPIC-18](https://github.com/Sandsy09/forge-template/issues/143).
-
-`CF-EPIC-18`'s six implementation children (CF-18.01–CF-18.06) have merged;
-CF-18.07 (ADR 0049) is publishing `create-forge 0.4.0`, gated on
-[FT-18.01](https://github.com/Sandsy09/forge-template/issues/156). See
-`docs/release-0-4-0-validation.md` for the publication evidence once it
-lands.
+Filed and delivered on the `create-forge` side.
+[CF-EPIC-18](https://github.com/Sandsy09/create-forge/issues/153) is closed:
+all seven children merged, and CF-18.07 (ADR 0049) published
+`create-forge 0.4.0` after
+[FT-18.01](https://github.com/Sandsy09/forge-template/issues/156) closed the
+provider-side integrated validation. See `docs/release-0-4-0-validation.md`
+for the full publication evidence.
+[FT-EPIC-18](https://github.com/Sandsy09/forge-template/issues/143) is
+`forge-template`'s own epic; see that repository's roadmap record for its
+status.
 
 ## Entry criteria
 

{create_forge-0.4.0 → create_forge-0.5.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "create-forge"
-version = "0.4.0"
+version = "0.5.0"
 description = "Scaffold modern Python projects from maintained templates."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,11 +32,12 @@ dependencies = [
     # moves from the optional `engine` extra into a required dependency. ADR
     # 0018 assigned the first released range; ADR 0026 moved it to the
     # `forge-template` 0.4 line; ADR 0031 raised the floor to the reviewed
-    # 0.4.1 release; this adopts the reviewed 0.5.0 cutover release (ADR 0042
-    # / docs/engine-cutover-acceptance.md). src/create_forge/engine.py stays
-    # the only module that imports it; src/create_forge/compat.py holds the
-    # range itself so `doctor` can report it without importing the engine.
-    "forge-template>=0.5,<0.6",
+    # 0.4.1 release; ADR 0042 adopted the reviewed 0.5.0 cutover release
+    # (docs/engine-cutover-acceptance.md); ADR 0050 (CF-21.01) adopts the
+    # reviewed 0.6.0 Streamlit provider release. src/create_forge/engine.py
+    # stays the only module that imports it; src/create_forge/compat.py holds
+    # the range itself so `doctor` can report it without importing the engine.
+    "forge-template>=0.6,<0.7",
     # ADR 0021 adds bounded uv to finalise the engine render's dynamic
     # lockfile; ADR 0038 reviewed that floor against the advisory record and
     # held it -- the whole `>=0.12,<0.13` range is already advisory-free. Now
@@ -223,6 +224,13 @@ docs = "mkdocs serve"
 # entry point -- see scripts/check_workflows.py.
 "check:workflows" = "python scripts/check_workflows.py"
 
+# Prints the table that binds the installed update-safety evidence to one
+# candidate: commit, wheel/sdist hashes, forge-template artefact hashes, tool
+# versions, and the safety-relevant source digest a fast-suite test checks
+# (ADR 0054, CF-22.03). Re-run on the release commit to refresh it; `--no-build`
+# skips the build. See scripts/candidate_evidence.py.
+"evidence:candidate" = "python scripts/candidate_evidence.py"
+
 # Reconciles a repo's GitHub labels against .github/labels.toml. Idempotent:
 # `gh label create --force` creates or updates. Pass extra args after `--`,
 # e.g. `uv run poe labels:sync --dry-run` or `--repo OWNER/NAME --prune`

{create_forge-0.4.0 → create_forge-0.5.0}/src/create_forge/_engine_worker.py

@@ -148,6 +148,29 @@ def _dispatch(op: str, request: dict[str, object]) -> dict[str, object]:
     raise ValueError(msg)
 
 
+def _read_request() -> str:
+    """The request, as strict UTF-8 from the binary stdin.
+
+    The protocol is UTF-8 in both directions whatever this interpreter's locale
+    is (CF-23.01, docs/subprocess-output.md), so the text layer -- which would
+    decode with the locale -- is bypassed. A byte that is not valid UTF-8 raises
+    here and is reported as a structured error by `main`, like any other bad
+    request. This file cannot import `create_forge.capture`: it runs where
+    `create_forge` is not installed.
+    """
+    return sys.stdin.buffer.read().decode("utf-8")
+
+
+def _emit(response: dict[str, object]) -> None:
+    """Write exactly one JSON object and a newline, as UTF-8, to the binary stdout.
+
+    `json.dumps` keeps its default `ensure_ascii=True`, so the bytes are ASCII --
+    valid UTF-8 -- and there is no newline translation to differ by platform.
+    """
+    sys.stdout.buffer.write((json.dumps(response) + "\n").encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
 def main(argv: list[str]) -> int:
     """Read one JSON request from stdin, write one JSON response to stdout.
 
@@ -167,19 +190,19 @@ def main(argv: list[str]) -> int:
                 "details": [],
             },
         }
-        print(json.dumps(response))
+        _emit(response)
         return 0
 
     op = argv[1]
     try:
-        raw = sys.stdin.read()
+        raw = _read_request()
         request = json.loads(raw) if raw.strip() else {}
         result = _dispatch(op, request)
     except Exception as exc:
-        print(json.dumps({"ok": False, "error": _error_payload(exc)}))
+        _emit({"ok": False, "error": _error_payload(exc)})
         return 0
 
-    print(json.dumps({"ok": True, "result": result}))
+    _emit({"ok": True, "result": result})
     return 0
 
 

create_forge-0.5.0/src/create_forge/capture.py

@@ -0,0 +1,156 @@
+"""The one place subprocess output is captured, and the rules for decoding it.
+
+CF-23.01 (ADR 0055; canonical `docs/subprocess-output.md`). `subprocess.run(...,
+text=True)` decodes with the *host locale* -- `cp1252` on a default Windows
+install -- so what a child writes and how this process reads it were only ever
+lined up by accident. `git` and `uv` write UTF-8; a Python child writes the
+locale encoding when piped. On a non-UTF-8 host a single undecodable byte in a
+child's stderr raised inside `subprocess.run` and left `stdout` as `None`.
+`PYTHONUTF8=1` hides that; it does not define what the bytes are.
+
+So nothing in this package captures text. `run_captured` returns **bytes**, and a
+caller decodes only what it genuinely reads, with one of three explicit rules:
+
+- **Diagnostic** (`decode_diagnostic`): UTF-8, `errors="replace"`. For a fact
+  extracted from human-oriented output (a version token, whether a value is
+  set). It never raises, and its result is never shown raw: raw argv, stdout and
+  stderr are never echoed (ADR 0044/0045/0046), because they can carry a
+  credential.
+- **Protocol** (`decode_protocol`, `parse_protocol_json`): UTF-8, **strict**.
+  Machine-readable output either parses or is rejected. Malformed bytes, a byte
+  order mark, or a body that is not JSON raise `ProtocolDecodeError`; they can
+  never quietly become valid protocol data.
+- **Path or binary data**: bytes are left alone (`git merge-file`'s content), or
+  are turned into a path with `decode_path`, which is `os.fsdecode`: exactly the
+  filesystem's own round trip, with **no replacement character**. Replacing
+  bytes in a path would name a different file.
+
+Most call sites read only the return code and so decode nothing at all.
+
+Deliberately engine-free, like `staging.py`, `lifecycle.py`, `update.py` and
+`engine_source.py`: nothing here imports `forge_template`
+(`tests/test_engine_contract.py`'s `_SHIPPED_MODULES` guard covers it), and
+`tests/test_subprocess_policy.py` fails if any other module in this package calls
+`subprocess.run`/`Popen`/`check_output`, or asks `subprocess` to decode.
+
+`OSError` (a missing or unlaunchable executable) and `subprocess.TimeoutExpired`
+propagate unchanged, so each caller keeps translating them into its own safe
+error, and return codes -- including the negative "killed by signal" codes on
+POSIX -- reach the caller exactly as `subprocess.run` reports them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+
+class ProtocolDecodeError(ValueError):
+    """Protocol output that is not valid UTF-8 JSON.
+
+    Carries no output bytes: what a misbehaving child wrote is never forwarded.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class Captured:
+    """One finished child process: its status and its raw, undecoded streams."""
+
+    returncode: int
+    stdout: bytes
+    stderr: bytes
+
+
+def run_captured(
+    argv: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    stdin: bytes | None = None,
+    timeout: float | None = None,
+) -> Captured:
+    """Run `argv` without a shell and return its status and raw bytes.
+
+    Never passes `text=`, `encoding=` or `universal_newlines`, so nothing is
+    decoded and no newline is translated. `stdin`, when given, must already be
+    bytes: the caller states the encoding it sends. Never raises for a non-zero
+    exit (`check=False`); `OSError` and `subprocess.TimeoutExpired` propagate.
+    """
+    result = subprocess.run(  # noqa: S603 - callers pass reviewed argv, never a shell
+        list(argv),
+        cwd=cwd,
+        env=dict(env) if env is not None else None,
+        input=stdin,
+        capture_output=True,
+        check=False,
+        timeout=timeout,
+    )
+    return Captured(result.returncode, result.stdout, result.stderr)
+
+
+def decode_diagnostic(data: bytes) -> str:
+    """Decode human-oriented output as UTF-8, replacing what is not.
+
+    For extracting a fact, never for showing the output: see the module
+    docstring's rule on echoing raw process output.
+    """
+    return data.decode("utf-8", errors="replace")
+
+
+def decode_protocol(data: bytes) -> str:
+    """Decode machine-readable output as strict UTF-8.
+
+    Raises:
+        ProtocolDecodeError: `data` is not valid UTF-8.
+    """
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        msg = "protocol output is not valid UTF-8"
+        raise ProtocolDecodeError(msg) from exc
+
+
+def parse_protocol_json(data: bytes) -> object:
+    """Parse machine-readable output: strict UTF-8, then strict JSON.
+
+    A byte order mark is left in place by the decode and refused by the parser,
+    so it is rejected rather than skipped.
+
+    Raises:
+        ProtocolDecodeError: `data` is not valid UTF-8, or is not JSON.
+    """
+    text = decode_protocol(data)
+    try:
+        return json.loads(text)
+    except (ValueError, RecursionError) as exc:
+        msg = "protocol output is not valid JSON"
+        raise ProtocolDecodeError(msg) from exc
+
+
+def decode_path(data: bytes) -> str:
+    """Turn path bytes a child printed into a path, with no replacement.
+
+    `os.fsdecode` is the filesystem's own encoding on every host (UTF-8 on
+    Windows since Python 3.6, the locale with `surrogateescape` on POSIX), so the
+    result names the file the child meant and round-trips through
+    `os.fsencode`.
+    """
+    return os.fsdecode(data)
+
+
+def display_safe(text: str) -> str:
+    r"""Make `text` printable without raising, without changing what it names.
+
+    A path decoded with `decode_path` can hold lone surrogates (bytes the
+    filesystem encoding could not decode); printing one raises. They are shown as
+    a visible `\udcXX` instead. The original string is untouched: use this only
+    at the point of display.
+    """
+    return text.encode("utf-8", errors="backslashreplace").decode("utf-8")

{create_forge-0.4.0 → create_forge-0.5.0}/src/create_forge/cli.py

@@ -18,7 +18,7 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
-from create_forge import compat
+from create_forge import capture, compat
 from create_forge.compat import (
     ENGINE_DISTRIBUTION,
     INTEGRATION_LINE,
@@ -1442,15 +1442,27 @@ def _run_engine_update(  # noqa: PLR0915 - one branch per prepare/apply/degraded
     """The engine-native `update` route (ADR 0041 rules 9-23, ADR 0046)."""
     from create_forge import engine, pipeline, update  # noqa: PLC0415
 
+    # ADR 0053: recovery guidance is only ever printed once the clean-tree
+    # precondition has passed. Before it, whatever is dirty is the user's own
+    # work, and telling them to restore it away would destroy it.
+    started = False
     try:
         update.require_clean_tree(project)
+        started = True
         degraded_reason: str | None = None
 
         if degraded:
             recorded, new = pipeline.prepare_degraded_update(project)
+            new_files = {file.target: file.content for file in new.files}
+            update.preflight_update(
+                project,
+                metadata_filename=engine.generation_metadata_target(),
+                targets=new_files,
+                recorded_targets=recorded.digests,
+            )
             outcome = update.degraded_plan(
                 project,
-                {file.target: file.content for file in new.files},
+                new_files,
                 recorded_digests=recorded.digests,
                 dry_run=dry_run,
             )
@@ -1463,15 +1475,31 @@ def _run_engine_update(  # noqa: PLR0915 - one branch per prepare/apply/degraded
                     err.print(f"[red]{exc}[/red]")
                     raise typer.Exit(3) from exc
                 recorded, new = pipeline.prepare_degraded_update(project)
+                new_files = {file.target: file.content for file in new.files}
+                update.preflight_update(
+                    project,
+                    metadata_filename=engine.generation_metadata_target(),
+                    targets=new_files,
+                    recorded_targets=recorded.digests,
+                )
                 outcome = update.degraded_plan(
                     project,
-                    {file.target: file.content for file in new.files},
+                    new_files,
                     recorded_digests=recorded.digests,
                     dry_run=dry_run,
                 )
                 degraded_reason = str(exc)
             else:
                 new = preparation.new
+                # ADR 0052: refuse the whole update before its first mutation.
+                # Plan targets already cover every recorded target the plan
+                # acts on, so the recorded document itself is not re-read here.
+                update.preflight_update(
+                    project,
+                    metadata_filename=engine.generation_metadata_target(),
+                    targets=[item.target for item in preparation.plan.targets],
+                    renames=preparation.plan.renames,
+                )
                 update.apply_renames(project, preparation.plan.renames)
                 outcome = update.apply_plan(
                     project,
@@ -1492,8 +1520,10 @@ def _run_engine_update(  # noqa: PLR0915 - one branch per prepare/apply/degraded
             msg = "the engine returned no generation metadata for this render"
             raise StagingError(msg)
         refreshed = engine.metadata_json(new.metadata, degraded_reason=degraded_reason)
-        (project / engine.generation_metadata_target()).write_text(
-            refreshed, encoding="utf-8"
+        update.write_recorded(
+            project,
+            metadata_filename=engine.generation_metadata_target(),
+            content=refreshed,
         )
         update.stage_result(project)
 
@@ -1502,21 +1532,37 @@ def _run_engine_update(  # noqa: PLR0915 - one branch per prepare/apply/degraded
         _report_update_result(outcome)
     except KeyboardInterrupt:
         err.print("\n[dim]Cancelled.[/dim]")
-        err.print(f"[dim]Recover with: {update.ROLLBACK_HINT}[/dim]")
+        _print_recovery(project, started=started)
         raise typer.Exit(130) from None
     except (update.UpdateError, StagingError) as exc:
         err.print(f"[red]{exc}[/red]")
-        err.print(f"[dim]Recover with: {update.ROLLBACK_HINT}[/dim]")
+        _print_recovery(project, started=started)
         raise typer.Exit(1) from exc
     except engine.EngineCompatibilityError as exc:
         err.print(f"[red]{exc}[/red]")
         raise typer.Exit(3) from exc
     except engine.ForgeEngineError as exc:
         err.print(f"[red]{engine.explain(exc)}[/red]")
-        err.print(f"[dim]Recover with: {update.ROLLBACK_HINT}[/dim]")
+        _print_recovery(project, started=started)
         raise typer.Exit(1) from exc
 
 
+def _print_recovery(project: Path, *, started: bool) -> None:
+    """Rule 18 (ADR 0053): guidance for the repository's *actual* Git state.
+
+    Read from Git at failure time, so a failure that changed nothing says so
+    rather than printing a command, and a staged or half-renamed tree gets one
+    that actually restores it. Printed, never run. `soft_wrap` and no markup or
+    highlighting keep a command on one line, unmangled, ready to paste.
+    """
+    if not started:
+        return
+    from create_forge import update  # noqa: PLC0415
+
+    for line in update.recovery_guidance(project).lines():
+        err.print(line, style="dim", markup=False, highlight=False, soft_wrap=True)
+
+
 def _markers(target: Console) -> tuple[str, str]:
     """Return (pass, fail) markers the console's encoding can actually render.
 
@@ -1889,16 +1935,11 @@ def _uv_version(uv_path: str | None) -> str | None:
     if not uv_path:
         return None
     try:
-        result = subprocess.run(  # noqa: S603
-            [uv_path, "--version"],
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=5,
-        )
+        result = capture.run_captured([uv_path, "--version"], timeout=5)
     except (OSError, subprocess.TimeoutExpired):  # pragma: no cover
         return None
-    match result.stdout.split():
+    # A diagnostic read (CF-23.01): lenient, and only a validated token escapes.
+    match capture.decode_diagnostic(result.stdout).split():
         case [_, token, *_] if re.fullmatch(r"[0-9][0-9A-Za-z.+-]*", token):
             return token
         case _:
@@ -2048,13 +2089,9 @@ def config_show() -> None:
 
 def _git_config(key: str) -> str | None:
     try:
-        result = subprocess.run(  # noqa: S603
-            ["git", "config", "--get", key],  # noqa: S607
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=5,
-        )
+        result = capture.run_captured(["git", "config", "--get", key], timeout=5)
     except (OSError, subprocess.TimeoutExpired):  # pragma: no cover
         return None
-    return result.stdout.strip() or None
+    # A diagnostic read (CF-23.01): a name may be non-ASCII, and doctor only asks
+    # whether one is set, so a lenient decode is enough and cannot raise.
+    return capture.decode_diagnostic(result.stdout).strip() or None

{create_forge-0.4.0 → create_forge-0.5.0}/src/create_forge/compat.py

@@ -27,21 +27,24 @@ from packaging.version import Version
 ENGINE_DISTRIBUTION = "forge-template"
 """The PyPI distribution name the engine dependency declares."""
 
-INTEGRATION_LINE = "v0.4.x-engine"
+INTEGRATION_LINE = "v0.5.x-engine"
 """The create-forge release line and its default generation architecture.
 
 This is explicit rather than derived from installed metadata so a new release
 line requires a deliberate compatibility review. ADR 0040 (CF-18.01) makes the
 engine the default `new` architecture; `new` is Copier-backed only under the
 explicit `--legacy` flag. ADR 0049 (CF-18.07) moved this from `v0.3.x-engine`
-to `v0.4.x-engine` for the published cutover release -- a shipped diagnostic
-surface (`doctor --json`'s `integration.line`) reviewed by hand, not derived.
+to `v0.4.x-engine` for the published cutover release, and ADR 0056 (CF-21.03)
+moves it to `v0.5.x-engine` for the release that crosses to the `forge-template`
+`0.6` provider line (client `0.N.x` pairs with provider `0.(N+1)`) -- a shipped
+diagnostic surface (`doctor --json`'s `integration.line`) reviewed by hand, not
+derived.
 `tests/test_engine_contract.py`'s
 `test_diagnostic_integration_line_matches_package_release_line` checks this
 literal against `pyproject.toml`'s own `major.minor`.
 """
 
-SUPPORTED_ENGINE_RANGE = ">=0.5,<0.6"
+SUPPORTED_ENGINE_RANGE = ">=0.6,<0.7"
 """The supported `forge-template` compatibility range.
 
 Pre-1.0, a supported range stays within one minor line -- see the
@@ -52,14 +55,17 @@ human-authored line crossing (ADR 0012), never a Dependabot proposal. ADR
 `forge-template` 0.4 line; ADR 0031 raised the lower bound to the reviewed
 `0.4.1` release. ADR 0040/0042 (CF-18.01) adopt the reviewed `0.5.0`
 engine-default cutover release, the first to publish `metadata_version` and
-component-manifest protocol `3`. `engine.py` checks an installed package
-against this range with `packaging.specifiers.SpecifierSet`.
+component-manifest protocol `3`. ADR 0050 (CF-21.01) adopts the reviewed
+`0.6.0` Streamlit provider release, which moves only the package version and
+the discovered catalogue (a fifteenth component) and no protocol tuple.
+`engine.py` checks an installed package against this range with
+`packaging.specifiers.SpecifierSet`.
 """
 
 SUPPORTED_PROJECTSPEC_PROTOCOLS: tuple[int, ...] = (1,)
 """ProjectSpec wire protocols this create-forge release has implemented
-against. Unchanged across the `0.3.x` through `0.5.x` engine lines
-(ADR 0026, ADR 0042).
+against. Unchanged across the `0.3.x` through `0.6.x` engine lines
+(ADR 0026, ADR 0042, ADR 0050).
 
 Deliberately not read from the installed engine's own advertised protocols
 -- negotiation in `engine.py` compares the two sides rather than assuming