Merge pull request #114 from CoReason-AI/develop

## Summary
This PR modernizes the `python_template` to align perfectly with the 2026+ CoReason "Shared Kernel" ecosystem. It completes the migration to the Zensical documentation engine, establishes a cutting-edge execution environment, and injects strict, machine-readable architectural directives into `AGENTS.md` to ensure all downstream generated projects are secure, deterministic, and natively understood by swarm LLMs.

## Key Changes
* **Execution & Tooling:**
  * Enforced **Python 3.14** (including Free-Threading `3.14t`) as the strict runtime baseline.
  * Standardized on **`uv`** as the exclusive, lightning-fast dependency and project manager. 
* **Documentation Engine Migration:**
  * Eradicated `mkdocs` and legacy plugins, fully replacing them with `zensical` and `mkdocstrings-python`.
  * Replaced `mkdocs.yml` with the new, Jinja-templated `zensical.toml` configuration.
* **AI-Native Constraints (`AGENTS.md`):**
  * **IP Defense:** Injected the Prosperity 3.0 `<legal_directive>` (Rules 5 & 6) to actively prevent downstream AI agents from unauthorized extraction or laundering of CoReason IP.
  * **Lexical Architecture:** Enforced the Anti-CRUD mandate and Categorical Suffixing (e.g., `...Intent`, `...Event`) to maintain pristine vector space embeddings.
  * **Mathematical Testing:** Mandated the use of the `hypothesis` library for property-based edge-case testing on Pydantic schemas.

## Impact
Any new repository generated from this template will now be born as a 100% CoReason-compliant node, featuring state-of-the-art Python 3.14+ execution, ultra-fast `uv` resolution, and ironclad prompt-level security against architectural drift.

Author: dk-uppi-aks

AUDIT.md

@@ -7,13 +7,13 @@ This document outlines the results of an audit of the repository against modern
 ### 1. Central Configuration and Legacy Files
 - **`pyproject.toml`**: **[PASS]** A `pyproject.toml` file exists at the root, which is mandatory for modern packaging.
 - **Legacy Files**: **[PASS]** `setup.py`, `setup.cfg`, and `requirements.txt` are not used for core metadata or dependency management. All configuration is correctly centralized in `pyproject.toml`.
-- **`poetry.lock`**: **[FAIL]** A `poetry.lock` file is present. This is a legacy artifact from a previous Poetry-based setup and is inconsistent with the current `setuptools` build backend. It must be removed.
+- **`poetry.lock`**: **[PASS]** The legacy `poetry.lock` file has been successfully removed.
 - **`MANIFEST.in`**: **[PASS]** This file is not present.
 
 ### 2. Build System (PEP 517 & PEP 518)
 - **`[build-system]` Table**: **[PASS]** This table is present in `pyproject.toml`.
-- **`build-backend`**: **[PASS]** A modern, PEP 517-compliant backend, `setuptools.build_meta`, is specified.
-- **`requires`**: **[PASS]** The build dependencies are correctly listed as `["setuptools>=61.0"]`.
+- **`build-backend`**: **[PASS]** A modern, PEP 517-compliant backend, `hatchling.build`, is specified.
+- **`requires`**: **[PASS]** The build dependencies are correctly listed as `["hatchling"]`.
 
 ### 3. Project Metadata (PEP 621)
 - **`[project]` Table**: **[PASS]** This table is present in `pyproject.toml`.
@@ -25,7 +25,7 @@ This document outlines the results of an audit of the repository against modern
 
 ### 4. Dependencies (PEP 508)
 - **`dependencies`**: **[PASS]** Runtime dependencies are correctly specified as an empty array.
-- **`optional-dependencies`**: **[PASS]** Extras for development are correctly defined in `[project.optional-dependencies]`.
+- **`optional-dependencies`**: **[PASS]** Extras for development are correctly defined using PEP 735 `[dependency-groups]`.
 
 ### 5. Project Structure and Layout
 - **Layout**: **[PASS]** The project uses the recommended `src` layout (`src/my_python_project/`).
@@ -37,11 +37,11 @@ This document outlines the results of an audit of the repository against modern
 - **Configuration**: **[PASS]** The testing configuration is centralized in `[tool.pytest.ini_options]` within `pyproject.toml`.
 
 ## Conclusion
-The project is already in excellent condition and fully compliant with modern Python packaging standards. The only required action is the removal of the legacy `poetry.lock` file. No further refactoring is necessary.
+The project is already in excellent condition and fully compliant with modern Python packaging standards. No further refactoring is necessary.
 
 ## Phase 3: Conformance Verification
 
 - **[X] Standards Compliance and Configuration**: `pyproject.toml` is the primary source of truth, the `[build-system]` is correctly configured, and all legacy configuration files have been removed.
 - **[X] Structure and Discoverability**: The project utilizes the `src` layout, and the build backend is correctly configured to discover packages.
-- **[X] Build Integrity**: The package builds successfully into both sdist and wheel formats using `python3 -m build`. The generated artifacts correctly include the source code, `LICENSE`, and `README` files.
+- **[X] Build Integrity**: The package builds successfully into both sdist and wheel formats using `uv build`. The generated artifacts correctly include the source code, `LICENSE`, and `README` files.
 - **[X] Installation and Testing**: The package can be installed in a fresh virtual environment and in editable mode. The test suite runs successfully against the installed package.

CI_CD_STRATEGY.md

@@ -4,20 +4,20 @@ This document outlines the CI/CD architecture for this project, including the Do
 
 ## CI/CD Architecture
 
-The CI/CD pipeline is built using GitHub Actions and is divided into two workflows: `ci.yml` and `docker.yml`.
+The CI/CD pipeline is built using GitHub Actions and is divided into two workflows: `ci-cd.yml` and `docker.yml`.
 
--   **`ci.yml`**: This workflow is triggered on `push` and `pull_request` events to the `main` and `develop` branches. It consists of two jobs:
+-   **`ci-cd.yml`**: This workflow is triggered on `push` and `pull_request` events to the `main` and `develop` branches. It consists of two jobs:
     1.  **`lint`**: This job runs the `pre-commit` suite to ensure all code adheres to the defined quality and style standards.
-    2.  **`test`**: This job runs the `pytest` suite across a matrix of Python versions (3.10, 3.11, and 3.12) to ensure the code is working as expected. It depends on the `lint` job, so it will only run if the linting passes.
+    2.  **`test`**: This job runs the `pytest` suite across a matrix of Python versions (Python 3.14 and 3.14t (free-threading)) to ensure the code is working as expected. It depends on the `lint` job, so it will only run if the linting passes.
 
 -   **`docker.yml`**: This workflow is triggered on `push` events to the `main` and `develop` branches. It builds, scans, and pushes a Docker image to the GitHub Container Registry.
 
 ## Docker Strategy
 
 The `Dockerfile` is a multi-stage build to create a lean and secure production image.
 
--   **Stage 1 (Builder)**: This stage installs Poetry, exports the project dependencies to a `requirements.txt` file, and installs them. It also installs the application itself.
--   **Stage 2 (Runtime)**: This stage uses a slim Python base image, creates a non-root user, and copies the installed dependencies and application from the builder stage. This results in a smaller and more secure final image.
+-   **Stage 1 (Builder)**: This stage installs `uv`, uses it to sync project dependencies via `uv sync`, and builds the application into a wheel (`uv build`), leveraging BuildKit caching.
+-   **Stage 2 (Runtime)**: This stage uses a slim Python 3.14 base image, creates a non-root user, and installs the wheel using `uv pip` from the builder stage. This results in a smaller and more secure final image.
 
 ## Security Measures
 

cookiecutter.json

@@ -7,5 +7,5 @@
   "author_email": "gowtham.rao@coreason.ai",
   "license_contributor": "CoReason, Inc.",
   "contact_email": "gowtham.rao@coreason.ai",
-  "copyright_year": "2025"
+  "copyright_year": "2026"
 }

hooks/post_gen_project.py

@@ -18,26 +18,28 @@
 print("Initializing Git repository...")
 
 try:
-    # On Windows, shell=True is required to resolve commands like 'poetry' if they are batch files
+    # On Windows, shell=True is required to resolve commands like 'uv' if they are batch files
     # or not strictly executables. On POSIX, shell=False is preferred.
     use_shell = sys.platform == "win32"
 
     # Initialize git
     subprocess.run(["git", "init", "-b", "main"], check=True, shell=use_shell)
+
+    # Install dependencies and generate uv.lock BEFORE committing
+    print("\nInstalling dependencies with uv...")
+    subprocess.run(["uv", "sync", "--all-extras", "--dev"], check=True, shell=use_shell)
+
+    # Stage and commit all files (including the newly generated uv.lock)
     subprocess.run(["git", "add", "."], check=True, shell=use_shell)
     subprocess.run(
         ["git", "commit", "-m", "Initial commit from cookiecutter"],
         check=True,
         shell=use_shell,
     )
 
-    # Install dependencies
-    print("\nInstalling dependencies with Poetry...")
-    subprocess.run(["poetry", "install"], check=True, shell=use_shell)
-
-    print("\nSuccessfully initialized git repo and installed dependencies.")
+    print("\nSuccessfully initialized git repo, generated lockfile, and committed.")
     print("Your new project is ready at:", os.getcwd())
 
 except Exception as e:
     print(f"\nAn error occurred during post-generation setup: {e}")
-    print("Please manually run 'git init' and 'poetry install'.")
+    print("Please manually run 'uv sync --all-extras --dev' and commit the results.")

{{cookiecutter.project_slug}}/.clinerules

@@ -0,0 +1 @@
+See AGENTS.md for AI agent rules.

{{cookiecutter.project_slug}}/.cursorrules

@@ -0,0 +1 @@
+See AGENTS.md for AI agent rules.

{{cookiecutter.project_slug}}/.dockerignore

@@ -6,3 +6,4 @@ __pycache__/
 docs/
 .github/
 .pre-commit-config.yaml
+!uv.lock

{{cookiecutter.project_slug}}/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

{{cookiecutter.project_slug}}/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# GitHub CODEOWNERS
+# For detail see: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+* @{{ cookiecutter.github_username }}
+
+# Architectural constraints
+/.github/workflows/ @{{ cookiecutter.github_username }}

{{cookiecutter.project_slug}}/.github/copilot-instructions.md

@@ -0,0 +1 @@
+See AGENTS.md for AI agent rules.