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

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

@@ -1,11 +1,31 @@
 # Changelog
 
 Generated by git-cliff from Conventional Commits.
+## [0.4.0] - 2026-09-14
+
+### Documentation
+
+- Reconcile living documentation with the 0.3 release line (#148)
+- Prepare engine-default and Streamlit roadmap packs
+- Record filed cross-repository roadmaps
+- Define engine-default selection and source-resolution UX (#155) (#169)
+- Define update dispatch, migration and filesystem lifecycle (#156) (#170)
+- Approve coordinated cutover acceptance and support policy (#157) (#171)
+- Consolidate CLAUDE.md and CONTRIBUTING.md behind a docs index (#173)
+
+### Features
+
+- Make the engine the default new path (CF-18.01)
+- Implement isolated --engine-source overrides (CF-18.02) (#174)
+- Implement engine generation finalisation, Git and hooks (CF-18.03) (#175)
+- Implement engine-native project updates (CF-18.04) (#176)
+- Preserve legacy Copier workflows and reject preview projects (CF-18.05) (#177)
+- Complete installed cutover regressions and migration docs (CF-18.06) (#178)
 ## [0.3.2] - 2026-09-08
 
 ### Features
 
-- Diagnose the Copier template cache
+- Diagnose the Copier template cache (#147)
 ## [0.3.1] - 2026-09-08
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: create-forge
-Version: 0.3.2
+Version: 0.4.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,16 +20,16 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: copier<10,>=9.16
-Requires-Dist: platformdirs>=4.3.6
+Requires-Dist: forge-template<0.6,>=0.5
 Requires-Dist: pydantic>=2.10
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0
 Requires-Dist: rich>=13.9
 Requires-Dist: typer>=0.16
-Provides-Extra: engine
-Requires-Dist: forge-template<0.5,>=0.4.1; extra == 'engine'
-Requires-Dist: uv<0.13,>=0.12; extra == 'engine'
+Requires-Dist: uv<0.13,>=0.12
+Provides-Extra: legacy
+Requires-Dist: copier<10,>=9.16; extra == 'legacy'
+Requires-Dist: platformdirs>=4.3.6; extra == 'legacy'
 Description-Content-Type: text/markdown
 
 # create-forge
@@ -46,11 +46,12 @@ uvx create-forge new
 
 Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), Git,
 and Python 3.11+ (uv can install Python for you). Configure your Git author
-name and email before generating a default Library project: generation
-creates local commits.
+name and email before generating a project: generation creates local commits.
 
 **[Read the Forge user guide](https://sandsy09.github.io/create-forge/)**
-for walkthroughs, template choices, and troubleshooting.
+for walkthroughs, project types, and troubleshooting. Coming from a `0.3.x`
+install or project? Start with the
+[migration guide](https://sandsy09.github.io/create-forge/migration/).
 
 ## How the repositories fit together
 
@@ -75,8 +76,11 @@ uv, Ruff, pytest with coverage, mypy and/or pyright, pre-commit hooks, and
 GitHub Actions CI. Choose your build backend, versioning, license, and
 dependency-update tooling. MkDocs documentation is optional.
 
-The template is rendered by [Copier](https://copier.readthedocs.io/), which
-also supports bringing later template improvements into existing projects.
+`new` discovers project types and capabilities directly from the
+`forge-template` engine, constructs a ProjectSpec, and renders through its
+public facade — no template repository to clone. Generation also runs
+`git init`, an initial commit, and installs any pre-commit hooks the project
+carries.
 
 ## Install and manage the tool
 
@@ -95,8 +99,8 @@ your terminal.
 
 ```bash
 uvx create-forge@latest new
-uvx create-forge@0.3.0 new
-uv tool install "create-forge==0.3.0"
+uvx create-forge@0.4.0 new
+uv tool install "create-forge==0.4.0"
 ```
 
 Plain `uvx create-forge` can reuse a cached or persistently installed
@@ -110,8 +114,8 @@ See [installation and versions](https://sandsy09.github.io/create-forge/installa
 | Command | Purpose |
 | --- | --- |
 | `uvx create-forge new` | Create a project interactively. |
-| `uvx create-forge list` | List the bundled Copier templates. |
-| `uvx create-forge update` | Update a Copier-generated project from its directory. |
+| `uvx create-forge list` | List the discovered project types and capabilities. |
+| `uvx create-forge update` | Update a generated project from its directory. |
 | `uvx create-forge doctor` | Diagnose Python, Git, uv, and package compatibility. |
 | `uvx create-forge config init` | Create an optional configuration file. |
 | `uvx create-forge config show` | Show resolved configuration and its sources. |
@@ -122,30 +126,40 @@ For scripts and CI, provide a project name and skip questions with `--yes`:
 uvx create-forge new "My Library" --yes --data github_org=your-org --data build_backend=hatchling --data versioning=vcs
 ```
 
-Use `--path` to choose the destination and repeat `--data key=value` to
-preset answers. Run `uvx create-forge new --help` for the default workflow's
-options. Saved author details, GitHub organisation, and preferred template
-are covered in the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
+Use `--path` to choose the destination, `--archetype`/`--capability` to
+preselect a project type, and repeat `--data key=value` to preset answers.
+Run `uvx create-forge new --help` for the default workflow's options. Saved
+author details, GitHub organisation, and preferred archetype are covered in
+the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
 
-### Choose a template version or source
+### More project types and capabilities
 
 ```bash
-uvx create-forge new "My Library" --template library --ref v0.4.1
-uvx create-forge new "Custom Project" --template-url https://github.com/you/your-template
+uvx create-forge new "My Analysis" --archetype data-science --capability jupyter --yes --data license=mit
+cd my-analysis
+uv run --locked poe check
+uv run poe notebook
 ```
 
-`--ref` selects a Git revision in the **template repository**. It does not
-select the CLI version. Without it, Copier uses the latest suitable release
-tag. The bundled registry currently offers Library; upgrade the CLI to
-receive registry changes.
+Available types include Library, CLI Application, and Data Science (a Python
+package with a starter notebook and Jupyter tooling), plus optional
+**Jupyter** and **Scientific Python** capabilities (Data Science requires
+Jupyter; Scientific Python is optional and can accompany any archetype). The
+[project guide](https://sandsy09.github.io/create-forge/projects/) explains
+each type's output.
 
-Templates can execute code through generation and update tasks. Use custom
-sources only when you trust their content; `--yes` also skips the custom
-template confirmation.
+### Isolated engine overrides
 
-### Update a generated project
+```bash
+uvx create-forge new "Custom" --engine-source https://github.com/you/your-engine-fork --engine-ref v0.5.1
+```
 
-From a clean, committed Copier-generated project:
+`--engine-source`/`--engine-ref` provision an isolated environment for
+cross-repository development against a fork or unreleased engine revision,
+separate from your ordinary install. Use custom sources only when you trust
+their content; `--yes` also skips the confirmation prompt.
+
+### Update a generated project
 
 ```bash
 uvx create-forge update --dry-run
@@ -153,50 +167,35 @@ uvx create-forge update
 uv run poe check
 ```
 
-Keep `.copier-answers.yml` committed. Review the resulting diff and resolve
-conflicts before committing. A dry run validates the update without applying
-it; it does not produce a file-by-file diff. Use `update --ref v0.4.1` to
-target a particular template version.
+`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`.
 
-## Preview: more project types and capabilities
-
-The `0.3.0` CLI also provides an opt-in engine preview using
-`forge-template>=0.4.1,<0.5`. These options are currently hidden from help.
-
-| Project type | Use it for |
-| --- | --- |
-| Library | A distributable Python package with a choice of packaging modes. |
-| CLI Application | A Typer application with a console command and tests. |
-| Data Science | A Python package with a starter notebook and Jupyter tooling. |
-
-Add **Jupyter** for notebook development or **Scientific Python** for NumPy,
-pandas, Matplotlib, and scikit-learn. Data Science requires Jupyter;
-Scientific Python is optional. These capabilities can also accompany the
-other preview archetypes.
+## The `--legacy` Copier route
 
 ```bash
-uvx --from "create-forge[engine]==0.3.0" create-forge new "My Analysis" --engine-preview --archetype data-science --capability jupyter --yes --data license=mit
-cd my-analysis
-uv run --locked poe check
-uv run poe notebook
+uv tool install "create-forge[legacy]"
+uvx --from "create-forge[legacy]" create-forge new "My Library" --legacy --template library --ref v0.4.1
 ```
 
-For regular preview use, install with `uv tool install "create-forge[engine]"`.
-The [project guide](https://sandsy09.github.io/create-forge/projects/) explains
-each type's output and links to complete recipes.
-
-**Preview projects do not support `create-forge update`.** Their shared
-tooling differs from the default Copier template; the preview does not
-generate its CI workflows or install Git hooks. `--template`,
-`--template-url`, and `--ref` apply only to the Copier workflow.
+`--legacy` renders directly from the bundled Copier registry instead of the
+engine — the original `create-forge` architecture, still fully supported.
+`--template`, `--template-url`, and `--ref` select the template and version
+under this route; `create-forge update` against a `.copier-answers.yml`
+project runs `copier update`. The `legacy` extra installs `copier`; without
+it, `--legacy` exits `3` naming the remedy.
 
 ## What's next
 
-The Foundation and Data Science roadmaps are complete. Making the engine
-the default generation workflow is a planned direction with no scheduled
-release. Follow [open work](https://github.com/Sandsy09/create-forge/issues)
-and [releases](https://github.com/Sandsy09/create-forge/releases) for updates,
-or suggest a project type, capability, or guide you would find useful.
+The Foundation, Data Science, and Engine-Default Cutover roadmaps are
+complete. The filed [Streamlit Archetype](docs/roadmap-v4/README.md) roadmap
+describes the next project type. Follow
+[open work](https://github.com/Sandsy09/create-forge/issues) and
+[releases](https://github.com/Sandsy09/create-forge/releases) for updates, or
+suggest a project type, capability, or guide you would find useful.
 
 ## Feedback and contributing
 

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

@@ -12,11 +12,12 @@ uvx create-forge new
 
 Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), Git,
 and Python 3.11+ (uv can install Python for you). Configure your Git author
-name and email before generating a default Library project: generation
-creates local commits.
+name and email before generating a project: generation creates local commits.
 
 **[Read the Forge user guide](https://sandsy09.github.io/create-forge/)**
-for walkthroughs, template choices, and troubleshooting.
+for walkthroughs, project types, and troubleshooting. Coming from a `0.3.x`
+install or project? Start with the
+[migration guide](https://sandsy09.github.io/create-forge/migration/).
 
 ## How the repositories fit together
 
@@ -41,8 +42,11 @@ uv, Ruff, pytest with coverage, mypy and/or pyright, pre-commit hooks, and
 GitHub Actions CI. Choose your build backend, versioning, license, and
 dependency-update tooling. MkDocs documentation is optional.
 
-The template is rendered by [Copier](https://copier.readthedocs.io/), which
-also supports bringing later template improvements into existing projects.
+`new` discovers project types and capabilities directly from the
+`forge-template` engine, constructs a ProjectSpec, and renders through its
+public facade — no template repository to clone. Generation also runs
+`git init`, an initial commit, and installs any pre-commit hooks the project
+carries.
 
 ## Install and manage the tool
 
@@ -61,8 +65,8 @@ your terminal.
 
 ```bash
 uvx create-forge@latest new
-uvx create-forge@0.3.0 new
-uv tool install "create-forge==0.3.0"
+uvx create-forge@0.4.0 new
+uv tool install "create-forge==0.4.0"
 ```
 
 Plain `uvx create-forge` can reuse a cached or persistently installed
@@ -76,8 +80,8 @@ See [installation and versions](https://sandsy09.github.io/create-forge/installa
 | Command | Purpose |
 | --- | --- |
 | `uvx create-forge new` | Create a project interactively. |
-| `uvx create-forge list` | List the bundled Copier templates. |
-| `uvx create-forge update` | Update a Copier-generated project from its directory. |
+| `uvx create-forge list` | List the discovered project types and capabilities. |
+| `uvx create-forge update` | Update a generated project from its directory. |
 | `uvx create-forge doctor` | Diagnose Python, Git, uv, and package compatibility. |
 | `uvx create-forge config init` | Create an optional configuration file. |
 | `uvx create-forge config show` | Show resolved configuration and its sources. |
@@ -88,30 +92,40 @@ For scripts and CI, provide a project name and skip questions with `--yes`:
 uvx create-forge new "My Library" --yes --data github_org=your-org --data build_backend=hatchling --data versioning=vcs
 ```
 
-Use `--path` to choose the destination and repeat `--data key=value` to
-preset answers. Run `uvx create-forge new --help` for the default workflow's
-options. Saved author details, GitHub organisation, and preferred template
-are covered in the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
+Use `--path` to choose the destination, `--archetype`/`--capability` to
+preselect a project type, and repeat `--data key=value` to preset answers.
+Run `uvx create-forge new --help` for the default workflow's options. Saved
+author details, GitHub organisation, and preferred archetype are covered in
+the [CLI guide](https://sandsy09.github.io/create-forge/cli/).
 
-### Choose a template version or source
+### More project types and capabilities
 
 ```bash
-uvx create-forge new "My Library" --template library --ref v0.4.1
-uvx create-forge new "Custom Project" --template-url https://github.com/you/your-template
+uvx create-forge new "My Analysis" --archetype data-science --capability jupyter --yes --data license=mit
+cd my-analysis
+uv run --locked poe check
+uv run poe notebook
 ```
 
-`--ref` selects a Git revision in the **template repository**. It does not
-select the CLI version. Without it, Copier uses the latest suitable release
-tag. The bundled registry currently offers Library; upgrade the CLI to
-receive registry changes.
+Available types include Library, CLI Application, and Data Science (a Python
+package with a starter notebook and Jupyter tooling), plus optional
+**Jupyter** and **Scientific Python** capabilities (Data Science requires
+Jupyter; Scientific Python is optional and can accompany any archetype). The
+[project guide](https://sandsy09.github.io/create-forge/projects/) explains
+each type's output.
 
-Templates can execute code through generation and update tasks. Use custom
-sources only when you trust their content; `--yes` also skips the custom
-template confirmation.
+### Isolated engine overrides
 
-### Update a generated project
+```bash
+uvx create-forge new "Custom" --engine-source https://github.com/you/your-engine-fork --engine-ref v0.5.1
+```
 
-From a clean, committed Copier-generated project:
+`--engine-source`/`--engine-ref` provision an isolated environment for
+cross-repository development against a fork or unreleased engine revision,
+separate from your ordinary install. Use custom sources only when you trust
+their content; `--yes` also skips the confirmation prompt.
+
+### Update a generated project
 
 ```bash
 uvx create-forge update --dry-run
@@ -119,50 +133,35 @@ uvx create-forge update
 uv run poe check
 ```
 
-Keep `.copier-answers.yml` committed. Review the resulting diff and resolve
-conflicts before committing. A dry run validates the update without applying
-it; it does not produce a file-by-file diff. Use `update --ref v0.4.1` to
-target a particular template version.
+`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`.
 
-## Preview: more project types and capabilities
-
-The `0.3.0` CLI also provides an opt-in engine preview using
-`forge-template>=0.4.1,<0.5`. These options are currently hidden from help.
-
-| Project type | Use it for |
-| --- | --- |
-| Library | A distributable Python package with a choice of packaging modes. |
-| CLI Application | A Typer application with a console command and tests. |
-| Data Science | A Python package with a starter notebook and Jupyter tooling. |
-
-Add **Jupyter** for notebook development or **Scientific Python** for NumPy,
-pandas, Matplotlib, and scikit-learn. Data Science requires Jupyter;
-Scientific Python is optional. These capabilities can also accompany the
-other preview archetypes.
+## The `--legacy` Copier route
 
 ```bash
-uvx --from "create-forge[engine]==0.3.0" create-forge new "My Analysis" --engine-preview --archetype data-science --capability jupyter --yes --data license=mit
-cd my-analysis
-uv run --locked poe check
-uv run poe notebook
+uv tool install "create-forge[legacy]"
+uvx --from "create-forge[legacy]" create-forge new "My Library" --legacy --template library --ref v0.4.1
 ```
 
-For regular preview use, install with `uv tool install "create-forge[engine]"`.
-The [project guide](https://sandsy09.github.io/create-forge/projects/) explains
-each type's output and links to complete recipes.
-
-**Preview projects do not support `create-forge update`.** Their shared
-tooling differs from the default Copier template; the preview does not
-generate its CI workflows or install Git hooks. `--template`,
-`--template-url`, and `--ref` apply only to the Copier workflow.
+`--legacy` renders directly from the bundled Copier registry instead of the
+engine — the original `create-forge` architecture, still fully supported.
+`--template`, `--template-url`, and `--ref` select the template and version
+under this route; `create-forge update` against a `.copier-answers.yml`
+project runs `copier update`. The `legacy` extra installs `copier`; without
+it, `--legacy` exits `3` naming the remedy.
 
 ## What's next
 
-The Foundation and Data Science roadmaps are complete. Making the engine
-the default generation workflow is a planned direction with no scheduled
-release. Follow [open work](https://github.com/Sandsy09/create-forge/issues)
-and [releases](https://github.com/Sandsy09/create-forge/releases) for updates,
-or suggest a project type, capability, or guide you would find useful.
+The Foundation, Data Science, and Engine-Default Cutover roadmaps are
+complete. The filed [Streamlit Archetype](docs/roadmap-v4/README.md) roadmap
+describes the next project type. Follow
+[open work](https://github.com/Sandsy09/create-forge/issues) and
+[releases](https://github.com/Sandsy09/create-forge/releases) for updates, or
+suggest a project type, capability, or guide you would find useful.
 
 ## Feedback and contributing
 

create_forge-0.4.0/docs/README.md

@@ -0,0 +1,77 @@
+# Canonical contracts
+
+This is the index of `create-forge`'s living contract documents — the
+`docs/*.md` files that fix behaviour a test or an ADR treats as binding, as
+opposed to prose that merely describes the code. [CLAUDE.md](../CLAUDE.md) and
+[CONTRIBUTING.md](../CONTRIBUTING.md) point here rather than restating this
+list; several entries have their own link-audit test in
+[tests/test_engine_contract.py](../tests/test_engine_contract.py) or
+[tests/test_reference_client_boundary.py](../tests/test_reference_client_boundary.py)
+requiring them to stay linked from here.
+
+A contract changes in the same pull request as the behaviour it describes.
+Records are living documents, not immutable like an ADR — but a change to one
+still usually cites the ADR that authorised it.
+
+## CLI surface
+
+| Contract | Governs |
+| --- | --- |
+| [cli-conventions.md](cli-conventions.md) | Input precedence, prompt-skipping, interactive/non-interactive parity, validation ownership, exit statuses. |
+| [component-selection.md](component-selection.md) | `--capability`/`--platform`/`--component-option` flags, absent-vs-explicit-empty, precedence, prompt order (ADR 0027). |
+| [engine-default-cli.md](engine-default-cli.md) | The post-cutover command surface: engine as the default `new` path, `--legacy`, `--engine-source`/`--engine-ref` (ADR 0040). |
+| [engine-project-lifecycle.md](engine-project-lifecycle.md) | Post-generation `git init`/commit/hooks, `.forge/generation.json`, and `update` dispatch (ADR 0041). |
+| [engine-cutover-acceptance.md](engine-cutover-acceptance.md) | The cutover release, supported OS/Python/install matrix, acceptance gates, support and deprecation windows (ADR 0042). |
+
+## Engine boundary
+
+| Contract | Governs |
+| --- | --- |
+| [integration-contract.md](integration-contract.md) | The evolving package/protocol compatibility rules with `forge-template` (ADR 0010). Its compatibility table is asserted byte-exact by a test. |
+| [engine-resolution.md](engine-resolution.md) | How the engine package is sourced, overridden locally, diagnosed, and rejected when incompatible (ADR 0011). |
+| [engine-updates.md](engine-updates.md) | How a compatibility-line dependency bump is adopted, how a breaking line is crossed, and what Dependabot may never do alone (ADR 0012). |
+| [project-spec-construction.md](project-spec-construction.md) | The CLI-answer-to-ProjectSpec field mapping and validation `spec.py`/`engine.py` implement (ADR 0013). |
+| [component-discovery.md](component-discovery.md) | Protocol negotiation, descriptor ownership, and the no-fallback trust boundary in `engine.py`. |
+| [engine-contract-tests.md](engine-contract-tests.md) | The supported package/protocol range and the sibling-checkout contract-test command. |
+| [downstream-client-reference.md](downstream-client-reference.md) | `examples/downstream_cli.py` — a second, independent client proving no `create-forge` dependency is required (ADR 0023). |
+| [organisation-policy-consumption.md](organisation-policy-consumption.md) | The `SelectionRequest`/`SelectionProvenance` seam, and why `create-forge` ships no policy parser (ADR 0022). |
+
+## Filesystem and tests
+
+| Contract | Governs |
+| --- | --- |
+| [filesystem-generation.md](filesystem-generation.md) | Destination-conflict, staging, finalisation, and cleanup rules in `staging.py` (ADR 0015). |
+| [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
+
+Acceptance-checklist-to-named-test maps, each closing an epic or a release.
+
+| Contract | Governs |
+| --- | --- |
+| [data-science-preview-validation.md](data-science-preview-validation.md) | CF-EPIC-13's acceptance checklist against the Data Science preview pipeline (ADR 0030). |
+| [installed-data-science-validation.md](installed-data-science-validation.md) | Both Data Science compositions through the installed candidate wheel (ADR 0032). |
+| [rollout-regression-validation.md](rollout-regression-validation.md) | Library/CLI Application engine paths, the engine-less default, and the full selection/option/destination/lock/cleanup failure matrix (ADR 0033). |
+| [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). |
+
+## Process and security
+
+| Contract | Governs |
+| --- | --- |
+| [workflow-security.md](workflow-security.md) | SHA-pinning external Actions and per-job `permissions:` scoping (ADR 0037). |
+| [cross-repository-workflow.md](cross-repository-workflow.md) | Validating sibling `create-forge`/`forge-template` checkouts before merge or release. |
+| [ADR 0024](adr/0024-reference-client-not-framework-dependency.md) | `create-forge` is one reference client, not a framework dependency for the engine or generated projects. |
+| [ADR 0037](adr/0037-immutable-workflow-actions.md) | The SHA-pinning and permissions rule `workflow-security.md` records. |
+
+## Elsewhere
+
+- [docs/adr/README.md](adr/README.md) — the full Architecture Decision Record
+  index, in Nygard format.
+- [docs/roadmap-v1/](roadmap-v1/) through [docs/roadmap-v4/](roadmap-v4/) —
+  completed and in-flight cross-repository roadmaps.
+- [docs/user-guide/](user-guide/) — the published
+  [Forge user guide](https://sandsy09.github.io/create-forge/) (end-user
+  docs; source of `reference.md`'s own technical-reference index for engine
+  APIs hosted in `forge-template`).

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

@@ -42,6 +42,16 @@ format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
 - [0037 — Pin external Actions to reviewed commits and scope permissions per job](0037-immutable-workflow-actions.md)
 - [0038 — Raise the Copier floor past the destination-escape advisories and hold uv](0038-dependency-floor-review.md)
 - [0039 — Diagnose the Copier template cache](0039-copier-cache-diagnostics.md)
+- [0040 — Define engine-default selection and source-resolution UX](0040-engine-default-selection-and-source-resolution.md)
+- [0041 — Define engine project lifecycle and update dispatch](0041-engine-project-lifecycle-and-update-dispatch.md)
+- [0042 — Approve the engine-default cutover acceptance and support policy](0042-engine-cutover-acceptance-and-support-policy.md)
+- [0043 — Consolidate CLAUDE.md and CONTRIBUTING.md behind a docs index](0043-consolidate-contributor-documentation.md)
+- [0044 — Run `--engine-source` overrides out of process](0044-out-of-process-engine-source-overrides.md)
+- [0045 — Run the engine `new` Git/hook lifecycle in a new module, and refuse the excluded targets it makes load-bearing](0045-engine-generation-lifecycle-and-staging-exclusions.md)
+- [0046 — Apply the engine-native update client-side with `git merge-file`, and reproduce the old render with a version-match short-circuit](0046-engine-native-update-application.md)
+- [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)
 
 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/docs/roadmap-v3/README.md

@@ -0,0 +1,62 @@
+# Engine-Default Cutover roadmap
+
+## Status
+
+Filed and open. This pack records 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.
+
+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.
+
+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.
+
+## Read this pack
+
+- [Stage overview](ROADMAP.md)
+- [Architecture and decision boundaries](ARCHITECTURE.md)
+- [Repository ownership](REPOSITORY-OWNERSHIP.md)
+- [Review traceability](TRACEABILITY.md)
+- [GitHub filing record and reconciliation procedure](github-issues/GITHUB-SETUP.md)
+- [Direct dependency matrix](github-issues/CROSS-REPO-DEPENDENCIES.md)
+- [Client issue index](github-issues/create-forge/ISSUE-INDEX.md)
+- [Provider issue index](github-issues/forge-template/ISSUE-INDEX.md)
+- [Machine-readable filing manifest](github-issues/filing-manifest.json)
+
+## Coordination
+
+The two packs are mirrored in both repositories. The reviewed manifest and
+complete bodies record the filed state. GitHub bodies and native relationships
+are authoritative; update both mirrors when decisions alter scope or
+dependencies. Never invent or reuse GitHub numbers.
+
+The next [Streamlit roadmap](../roadmap-v4/README.md) shares the contract
+gates. Preserve completed roadmap-v1/v2 records and historical ADRs.
+
+## Filed-state validation
+
+From either repository root:
+
+```bash
+uv run python scripts/check_roadmaps.py
+uv run poe check
+uv run pre-commit run --all-files
+```
+
+For a normal sibling layout, compare from create-forge with
+`uv run python scripts/check_roadmaps.py --mirror ../forge-template`,
+or from forge-template with
+`uv run python scripts/check_roadmaps.py --mirror ../create-forge`.
+Use an absolute mirror path when reviewing an isolated worktree.
+The checker reads both packs, validates links/anchors and the filing graph,
+and compares mirrored bytes and shared label manifests when requested.
+It performs no GitHub writes. The create-forge shared guide also requires
+`uv run poe docs:build`; provider technical docs are not a MkDocs site.

create_forge-0.4.0/docs/roadmap-v3/roadmap/15-engine-default-provider-contracts/README.md

@@ -0,0 +1,32 @@
+# Stage 15 — Engine-Default Provider Contracts
+
+## Status and epics
+
+Filed and open.
+[FT-EPIC-15](https://github.com/Sandsy09/forge-template/issues/141).
+
+## Entry criteria
+
+Follow each child's direct blockers below. Contract approval unblocks design;
+provider publication unblocks adoption. A blocked child must not begin before
+its required decision or immutable hand-off is accepted.
+
+## Child work
+
+| Child | Outcome | Direct blockers |
+| --- | --- | --- |
+| [FT-15.01](https://github.com/Sandsy09/forge-template/issues/146) | Account for every supported behaviour, generated concern and explicit exclusion. | None |
+| [FT-15.02](https://github.com/Sandsy09/forge-template/issues/147) | Specify versioned metadata, output ownership and reproducible old/new render requirements. | [FT-15.01](https://github.com/Sandsy09/forge-template/issues/146) |
+| [FT-15.03](https://github.com/Sandsy09/forge-template/issues/148) | Assign concerns to Foundation, archetypes, capabilities and platforms; identify necessary extension points. | [FT-15.01](https://github.com/Sandsy09/forge-template/issues/146) |
+| [FT-15.04](https://github.com/Sandsy09/forge-template/issues/149) | Classify public API/protocol changes and approve the provider acceptance matrix. | [FT-15.02](https://github.com/Sandsy09/forge-template/issues/147), [FT-15.03](https://github.com/Sandsy09/forge-template/issues/148) |
+
+## Exit criteria
+
+All stage-owned children have reviewed completion evidence. Resolve acceptance
+criteria through their named owner and keep scope within the approved contracts.
+
+## Non-goals
+
+No unrelated operational work, new archetype outside this roadmap, remote
+component registry or plugin system. Contract-only stages make no runtime,
+generated-content, dependency, version or release changes.