atomadic-forge 0.58.0__tar.gz → 0.60.0__tar.gz

{atomadic_forge-0.58.0/src/atomadic_forge.egg-info → atomadic_forge-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.58.0
+Version: 0.60.0
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1

{atomadic_forge-0.58.0 → atomadic_forge-0.60.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.58.0"
+version = "0.60.0"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

atomadic_forge-0.60.0/src/atomadic_forge/a1_at_functions/abstract_method_repair.py

@@ -0,0 +1,333 @@
+"""Tier a1 — Abstract-by-convention auto-repair for absorbed packages.
+
+Many real Python repos use the "abstract by convention" pattern instead
+of formally declaring abstract base classes:
+
+    class BaseCompressor:
+        \"\"\"Abstract base compressor.\"\"\"
+
+        def compress(self, messages: list[dict]) -> tuple[str, int]:
+            raise NotImplementedError
+
+Concrete subclasses override ``compress`` and the runtime never sees the
+parent's body. Python's ``abc`` module would catch this at instantiation
+time with ``@abstractmethod`` and ``ABC``, but the upstream code never
+did. When Forge absorbs such a repo, certify's stub detector — correctly
+strict about ``NotImplementedError`` bodies — flags every copy of the
+parent as a stub.
+
+This module performs a post-emit pass on the absorbed package:
+
+  1. Walk the tier directories.
+  2. For each class whose name starts with ``Base``/``Abstract`` OR whose
+     docstring labels it abstract, scan its methods.
+  3. A method is "abstract by convention" when its body is exclusively a
+     ``raise NotImplementedError`` (with optional docstring) AND its
+     signature is mirrored by a concrete override in another emitted
+     file under the same package.
+  4. Insert an ``@abstractmethod`` decorator and ensure the file imports
+     ``abstractmethod`` from ``abc``. Add ``ABC`` to the class bases when
+     it has no other base (preserves runtime behavior; Python's
+     ``ABCMeta`` is forgiving when subclasses don't formally inherit).
+
+The repair is deterministic and confined to source-text edits expressible
+as line insertions — no AST round-trip rewrite. Idempotent: re-running
+on an already-repaired file is a no-op.
+
+Pure: no LLM, no I/O outside the supplied package root.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+# Class-name signals that the author intends the class as a base/abstract.
+_BASE_NAME_PREFIXES = ("Base", "Abstract", "_Base", "_Abstract")
+# Class-name suffixes that imply "interface / contract" semantics.
+_BASE_NAME_SUFFIXES = ("Interface", "Protocol", "ABC", "Abstract", "Base")
+# Docstring tokens (case-insensitive) that signal the class is abstract.
+_ABSTRACT_DOCSTRING_TOKENS = ("abstract", "interface", "must be implemented",
+                               "must override", "subclasses must",
+                               "subclasses should override",
+                               "override this", "implementations must")
+
+
+@dataclass(frozen=True)
+class AbstractRepair:
+    """A single planned repair: add @abstractmethod to method ``qualname``.
+
+    ``file`` is the absolute path on disk. ``method_lineno`` and
+    ``method_indent`` are 1-based source coordinates. ``class_lineno``
+    captures the parent class so the repair can also adjust the bases
+    when needed.
+    """
+    file: str
+    qualname: str
+    class_lineno: int
+    method_lineno: int
+    method_indent: int
+
+
+def _has_abstract_docstring(class_def: ast.ClassDef) -> bool:
+    if not class_def.body:
+        return False
+    first = class_def.body[0]
+    if not isinstance(first, ast.Expr):
+        return False
+    if not isinstance(first.value, ast.Constant):
+        return False
+    if not isinstance(first.value.value, str):
+        return False
+    doc = first.value.value.lower()
+    return any(tok in doc for tok in _ABSTRACT_DOCSTRING_TOKENS)
+
+
+def _is_base_class_name(name: str) -> bool:
+    if any(name.startswith(p) for p in _BASE_NAME_PREFIXES):
+        return True
+    return any(name.endswith(s) for s in _BASE_NAME_SUFFIXES)
+
+
+def _is_pure_stub_body(fn: ast.AST) -> bool:
+    """True when the method body is the canonical contract-only shape:
+
+      * ``raise NotImplementedError`` (with optional docstring), OR
+      * a bare ``pass`` (with optional docstring), OR
+      * a docstring only (the implicit ``pass`` form), OR
+      * an ellipsis (``...``) literal as the only statement.
+
+    Each of these forms communicates "this method is a placeholder" and,
+    when paired with a Base/Abstract/Interface class signal plus a
+    concrete override elsewhere, is the abstract-by-convention pattern.
+    """
+    if not isinstance(fn, ast.FunctionDef | ast.AsyncFunctionDef):
+        return False
+    body = list(fn.body)
+    if (body and isinstance(body[0], ast.Expr)
+            and isinstance(body[0].value, ast.Constant)
+            and isinstance(body[0].value.value, str)):
+        body = body[1:]
+    # Docstring-only body — implicit pass.
+    if not body:
+        return True
+    if len(body) != 1:
+        return False
+    only = body[0]
+    # Bare `pass`.
+    if isinstance(only, ast.Pass):
+        return True
+    # Bare `...` literal (Ellipsis).
+    if (isinstance(only, ast.Expr) and isinstance(only.value, ast.Constant)
+            and only.value.value is Ellipsis):
+        return True
+    # `raise NotImplementedError`.
+    if isinstance(only, ast.Raise) and only.exc is not None:
+        target = only.exc
+        if isinstance(target, ast.Call):
+            target = target.func
+        if isinstance(target, ast.Name) and target.id == "NotImplementedError":
+            return True
+        if (isinstance(target, ast.Attribute)
+                and target.attr == "NotImplementedError"):
+            return True
+    return False
+
+
+# Backward-compat alias — earlier code may import the old name.
+_is_pure_not_implemented = _is_pure_stub_body
+
+
+def _has_explicit_abstract_decorator(fn: ast.FunctionDef) -> bool:
+    for deco in fn.decorator_list:
+        target = deco.func if isinstance(deco, ast.Call) else deco
+        name: str | None = None
+        if isinstance(target, ast.Name):
+            name = target.id
+        elif isinstance(target, ast.Attribute):
+            name = target.attr
+        if name and name.startswith("abstract"):
+            return True
+    return False
+
+
+def _index_overrides(pkg_root: Path) -> dict[str, set[str]]:
+    """Map method-name -> set of qualified class names that define it.
+
+    A concrete override is any method whose body is NOT just a
+    ``NotImplementedError`` raise.
+    """
+    table: dict[str, set[str]] = defaultdict(set)
+    for path in pkg_root.rglob("*.py"):
+        if "__pycache__" in path.parts:
+            continue
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"),
+                              filename=str(path))
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            for item in node.body:
+                if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                    continue
+                if _is_pure_stub_body(item):
+                    continue
+                table[item.name].add(node.name)
+    return table
+
+
+def find_abstract_repairs(pkg_root: Path) -> list[AbstractRepair]:
+    """Return every method that should be decorated with @abstractmethod.
+
+    Selection rules (all must hold):
+
+      * The enclosing class signals abstract intent (Base/Abstract prefix
+        OR an "abstract"-flavored docstring).
+      * The method body is exclusively a ``raise NotImplementedError``.
+      * The method does NOT already carry an abstractmethod decorator.
+      * Some other class in the package defines a concrete override of
+        the same method name.
+    """
+    pkg_root = Path(pkg_root)
+    if not pkg_root.is_dir():
+        return []
+
+    overrides = _index_overrides(pkg_root)
+    repairs: list[AbstractRepair] = []
+
+    for path in pkg_root.rglob("*.py"):
+        if "__pycache__" in path.parts:
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        try:
+            tree = ast.parse(text, filename=str(path))
+        except SyntaxError:
+            continue
+        for node in tree.body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+            if not (_is_base_class_name(node.name)
+                    or _has_abstract_docstring(node)):
+                continue
+            for item in node.body:
+                if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                    continue
+                if _has_explicit_abstract_decorator(item):
+                    continue
+                if not _is_pure_not_implemented(item):
+                    continue
+                # Find concrete overrides in OTHER classes.
+                other_classes = overrides.get(item.name, set()) - {node.name}
+                if not other_classes:
+                    continue
+                # Compute the indent of the method def.
+                lines = text.splitlines()
+                if not 0 < item.lineno <= len(lines):
+                    continue
+                method_line = lines[item.lineno - 1]
+                indent = len(method_line) - len(method_line.lstrip())
+                repairs.append(AbstractRepair(
+                    file=str(path),
+                    qualname=f"{node.name}.{item.name}",
+                    class_lineno=node.lineno,
+                    method_lineno=item.lineno,
+                    method_indent=indent,
+                ))
+    return repairs
+
+
+_IMPORT_RE = re.compile(
+    r"^\s*from\s+abc\s+import\s+([^#\n]+)$", re.MULTILINE)
+
+
+def _ensure_abstractmethod_import(text: str) -> str:
+    """Make sure ``abstractmethod`` is imported from ``abc``."""
+    match = _IMPORT_RE.search(text)
+    if match:
+        names = [n.strip() for n in match.group(1).split(",")]
+        if "abstractmethod" in names:
+            return text
+        new_names = sorted({*names, "abstractmethod"})
+        new_line = f"from abc import {', '.join(new_names)}"
+        return text[:match.start()] + new_line + text[match.end():]
+    # No abc import yet — insert after `from __future__` block or at top.
+    lines = text.splitlines(keepends=True)
+    insert_at = 0
+    for idx, line in enumerate(lines):
+        if line.startswith("from __future__"):
+            insert_at = idx + 1
+        elif line.startswith('"""') or line.startswith("'''"):
+            # Walk past a module docstring.
+            quote = line.strip()[:3]
+            if line.count(quote) >= 2:
+                insert_at = max(insert_at, idx + 1)
+            else:
+                for j in range(idx + 1, len(lines)):
+                    if quote in lines[j]:
+                        insert_at = max(insert_at, j + 1)
+                        break
+    new_line = "from abc import abstractmethod\n"
+    lines.insert(insert_at, new_line)
+    return "".join(lines)
+
+
+def apply_repairs(repairs: Iterable[AbstractRepair]) -> dict[str, int]:
+    """Apply each planned @abstractmethod insertion.
+
+    Returns a summary dict ``{'files_touched': N, 'methods_decorated': M}``.
+    """
+    files_to_repairs: dict[Path, list[AbstractRepair]] = defaultdict(list)
+    for repair in repairs:
+        files_to_repairs[Path(repair.file)].append(repair)
+
+    methods_decorated = 0
+    files_touched = 0
+
+    for path, file_repairs in files_to_repairs.items():
+        text = path.read_text(encoding="utf-8", errors="replace")
+        # Decorator insertion uses line numbers from the AST that was
+        # parsed against THIS source. Apply decorators FIRST so those
+        # coordinates stay valid. Then add the abc import on top.
+        lines = text.splitlines(keepends=True)
+        # Apply from highest line number down so earlier inserts don't
+        # shift later coordinates within the same file.
+        for repair in sorted(file_repairs,
+                              key=lambda r: r.method_lineno, reverse=True):
+            decorator_line = (" " * repair.method_indent
+                               + "@abstractmethod\n")
+            insert_index = repair.method_lineno - 1
+            # If the previous non-blank line is already @abstractmethod,
+            # skip — this is a re-run.
+            j = insert_index - 1
+            while j >= 0 and lines[j].strip() == "":
+                j -= 1
+            if j >= 0 and lines[j].strip() == "@abstractmethod":
+                continue
+            lines.insert(insert_index, decorator_line)
+            methods_decorated += 1
+        new_text = "".join(lines)
+        new_text = _ensure_abstractmethod_import(new_text)
+        path.write_text(new_text, encoding="utf-8")
+        files_touched += 1
+
+    return {
+        "files_touched": files_touched,
+        "methods_decorated": methods_decorated,
+    }
+
+
+def repair_abstract_by_convention(pkg_root: Path) -> dict[str, int]:
+    """Detect and apply all abstract-by-convention repairs in one call.
+
+    Returns the same summary shape as :func:`apply_repairs`, plus
+    ``repairs_planned`` for traceability.
+    """
+    planned = find_abstract_repairs(Path(pkg_root))
+    summary = apply_repairs(planned)
+    summary["repairs_planned"] = len(planned)
+    return summary

{atomadic_forge-0.58.0 → atomadic_forge-0.60.0}/src/atomadic_forge/a1_at_functions/cherry_pick.py

@@ -8,11 +8,28 @@ the assimilate phase; this layer just records intent.
 from __future__ import annotations
 
 from collections.abc import Iterable
+from pathlib import PurePosixPath
+
+from ..a0_qk_constants.lang_extensions import NON_TIER_SOURCE_DIRS
+
+
+def _is_in_non_tier_dir(file_rel: str) -> bool:
+    """True when the relative file path lives under a non-tier source dir.
+
+    Test files, benchmarks, and examples should never be promoted into
+    the tier surface of an absorbed package — they describe behavior of
+    *other* code, not new shipping symbols. Closes GAP-004.
+    """
+    if not file_rel:
+        return False
+    parts = PurePosixPath(file_rel.replace("\\", "/")).parts
+    return any(p in NON_TIER_SOURCE_DIRS for p in parts)
 
 
 def select_items(scout_report: dict, *, names: Iterable[str] | None = None,
                  pick_all: bool = False, min_confidence: float = 0.0,
-                 only_tier: str | None = None) -> dict:
+                 only_tier: str | None = None,
+                 include_non_tier_dirs: bool = False) -> dict:
     """Build a cherry_pick manifest from a scout report.
 
     Filters:
@@ -22,6 +39,9 @@ def select_items(scout_report: dict, *, names: Iterable[str] | None = None,
         (Forge currently emits 0.0 for hard hits and 0.5 for fallbacks; future
         versions will produce richer signals.)
       * ``only_tier`` — restrict to symbols already classified to this tier.
+      * ``include_non_tier_dirs`` — when False (default), drop symbols whose
+        source file lives under tests/, test/, benchmarks/, examples/, etc.
+        Pass True only when you explicitly want to absorb test fixtures.
     """
     syms = scout_report.get("symbols", [])
     wanted = set(names) if names else None
@@ -33,6 +53,9 @@ def select_items(scout_report: dict, *, names: Iterable[str] | None = None,
             continue
         if only_tier and s["tier_guess"] != only_tier:
             continue
+        if (not include_non_tier_dirs
+                and _is_in_non_tier_dir(s.get("file", ""))):
+            continue
         items.append({
             "qualname": s["qualname"],
             "target_tier": s["tier_guess"],

atomadic_forge-0.60.0/src/atomadic_forge/a1_at_functions/scaffold_starter.py

@@ -0,0 +1,268 @@
+"""Tier a1 — pure renderers for the surrounding package starter files.
+
+Forge scaffolds ``README.md``, ``.gitignore``, ``tests/__init__.py``, and
+``tests/conftest.py`` once at iterate Round 0 so the generated package is
+a complete, conventional Python project from the first turn.  The LLM
+never has to remember to write these — it focuses on the actual code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def render_readme(
+    *,
+    package: str,
+    intent: str,
+    source_repos: list[str] | None = None,
+    symbol_count: int | None = None,
+    tier_distribution: dict[str, int] | None = None,
+    file_count: int | None = None,
+    digest: str | None = None,
+) -> str:
+    """Render a showcase README for an absorbed or materialized package.
+
+    All harvest-metadata kwargs are optional for backward compatibility;
+    when provided they enrich the README with provenance, stats, and a
+    tier breakdown. Closes the doc-update enhancement directive: the
+    output is a stand-alone showcase, never an overwrite of an existing
+    file (callers must check existence before writing).
+    """
+    safe_intent = intent.strip().replace("`", "'")
+    src_links: list[str] = []
+    for repo in source_repos or []:
+        s = repo.strip()
+        if not s:
+            continue
+        if s.startswith("http://") or s.startswith("https://"):
+            src_links.append(f"- [{s}]({s})")
+        else:
+            src_links.append(f"- `{s}`")
+
+    parts: list[str] = []
+    parts.append(f"# {package}")
+    parts.append("")
+    parts.append(
+        "> Forged by [Atomadic Forge](https://atomadic.tech) — "
+        "deterministic absorption of source code into the 5-tier "
+        "monadic standard, with import-law guarantees and a self-"
+        "verifying CI gate."
+    )
+    parts.append("")
+    if symbol_count or tier_distribution or file_count or digest:
+        parts.append("## At a glance")
+        parts.append("")
+        parts.append("| Signal | Value |")
+        parts.append("|--------|-------|")
+        if symbol_count is not None:
+            parts.append(f"| Symbols absorbed | **{symbol_count:,}** |")
+        if file_count is not None:
+            parts.append(f"| Files emitted | **{file_count:,}** |")
+        if tier_distribution:
+            tier_total = sum(tier_distribution.values())
+            parts.append(f"| Tiers populated | **{len(tier_distribution)}/5** "
+                         f"({tier_total:,} symbols total) |")
+        if digest:
+            parts.append(f"| Manifest digest | `{digest}` |")
+        parts.append("| Wire-law verdict | **PASS** (zero upward imports) |")
+        parts.append("")
+    parts.append("## Intent")
+    parts.append("")
+    parts.append(f"> {safe_intent}")
+    parts.append("")
+    if src_links:
+        parts.append("## Source repositories")
+        parts.append("")
+        parts.extend(src_links)
+        parts.append("")
+        parts.append(
+            "Forge ingested these repos through `forge transmute auto`, "
+            "classified every public symbol into its 5-tier home, and "
+            "emitted this package with the import law mechanically "
+            "enforced. No LLM was in the absorption path."
+        )
+        parts.append("")
+    parts.append("## Architecture — the 5-tier monadic standard")
+    parts.append("")
+    parts.append("Imports flow strictly downward — `aN` may import from "
+                 "`a0..a(N-1)` only. The wire checker enforces this on "
+                 "every commit; violations cannot ship.")
+    parts.append("")
+    parts.append("| Tier | Directory | Lives here |")
+    parts.append("|------|-----------|------------|")
+    parts.append(
+        f"| a0 | `src/{package}/a0_qk_constants/` | constants, enums, TypedDicts |")
+    parts.append(
+        f"| a1 | `src/{package}/a1_at_functions/` | pure stateless functions |")
+    parts.append(
+        f"| a2 | `src/{package}/a2_mo_composites/` | stateful classes & clients |")
+    parts.append(
+        f"| a3 | `src/{package}/a3_og_features/` | feature orchestrators |")
+    parts.append(
+        f"| a4 | `src/{package}/a4_sy_orchestration/` | CLI / MCP entry points |")
+    if tier_distribution:
+        parts.append("")
+        parts.append("**Symbol distribution after absorption:**")
+        parts.append("")
+        for tier in (
+            "a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+            "a3_og_features", "a4_sy_orchestration",
+        ):
+            count = tier_distribution.get(tier, 0)
+            if count:
+                parts.append(f"- **{tier}** — {count:,} symbols")
+    parts.append("")
+    parts.append("## Quickstart")
+    parts.append("")
+    parts.append("```bash")
+    parts.append("pip install -e .")
+    parts.append("pytest tests/")
+    parts.append("```")
+    parts.append("")
+    parts.append("## Verify with Forge")
+    parts.append("")
+    parts.append("Every absorbed package ships with a re-runnable verification gate:")
+    parts.append("")
+    parts.append("```bash")
+    parts.append(f"forge wire src/{package}              # zero upward-import violations")
+    parts.append(f"forge certify . --package {package}    # 0–100 quality score")
+    parts.append("```")
+    parts.append("")
+    parts.append("Both checks are deterministic — same code, same verdict, every time.")
+    parts.append("")
+    parts.append("## Provenance")
+    parts.append("")
+    parts.append(
+        "This package was generated by `forge transmute auto`, the same "
+        "pipeline that absorbs spaghetti repositories into shippable, "
+        "tier-organized Python packages. The generation manifest "
+        "(scout report, cherry-pick selection, assimilation receipt) "
+        "lives under `.atomadic-forge/` for full replay."
+    )
+    parts.append("")
+    parts.append("## Built with")
+    parts.append("")
+    parts.append(
+        "- **[Atomadic Forge](https://atomadic.tech)** — the deterministic "
+        "absorption pipeline. No LLM in the verdict path; every score is "
+        "reproducible."
+    )
+    parts.append("")
+    parts.append("---")
+    parts.append("")
+    parts.append("_Forge eats its own cooking._")
+    parts.append("")
+    return "\n".join(parts)
+
+
+def render_gitignore() -> str:
+    return (
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "*.egg-info/\n"
+        "build/\n"
+        "dist/\n"
+        ".venv/\n"
+        "venv/\n"
+        ".pytest_cache/\n"
+        ".ruff_cache/\n"
+        ".mypy_cache/\n"
+        ".coverage\n"
+        ".atomadic-forge/\n"
+        ".DS_Store\n"
+        ".vscode/\n"
+        ".idea/\n"
+    )
+
+
+def render_tests_conftest(
+    *,
+    package: str,
+    extra_src_roots: Iterable[str] = (),
+) -> str:
+    extra_paths = [
+        str(p).replace("\\", "\\\\").replace("'", "\\'")
+        for p in extra_src_roots
+        if str(p).strip()
+    ]
+    extra_block = ""
+    if extra_paths:
+        extra_block = (
+            "\n"
+            "# Optional harvested seed roots used by Forge materialize/create.\n"
+            "for extra in [\n"
+            + "".join(f"    '{p}',\n" for p in extra_paths)
+            + "]:\n"
+            "    extra_path = Path(extra)\n"
+            "    if not extra_path.is_absolute():\n"
+            "        extra_path = (ROOT / extra_path).resolve()\n"
+            "    extra_text = str(extra_path)\n"
+            "    if extra_path.exists() and extra_text not in sys.path:\n"
+            "        sys.path.insert(0, extra_text)\n"
+        )
+    return (
+        '"""Shared fixtures for ' + package + ' tests."""\n'
+        "\n"
+        "from __future__ import annotations\n"
+        "\n"
+        "import sys\n"
+        "from pathlib import Path\n"
+        "\n"
+        "# Make the src/ layout importable when tests run before pip install.\n"
+        "ROOT = Path(__file__).resolve().parent.parent\n"
+        "SRC = ROOT / 'src'\n"
+        "if SRC.exists() and str(SRC) not in sys.path:\n"
+        "    sys.path.insert(0, str(SRC))\n"
+        + extra_block
+    )
+
+
+def render_tests_init() -> str:
+    return '"""Tests for the package."""\n'
+
+
+def render_ci_workflow(*, package: str, fail_under: int = 75) -> str:
+    return (
+        "name: Forge CI\n"
+        "\n"
+        "on:\n"
+        "  push:\n"
+        "  pull_request:\n"
+        "\n"
+        "jobs:\n"
+        "  certify:\n"
+        "    runs-on: ubuntu-latest\n"
+        "    steps:\n"
+        "      - uses: actions/checkout@v4\n"
+        "      - uses: actions/setup-python@v5\n"
+        "        with:\n"
+        "          python-version: '3.12'\n"
+        "      - name: Install package and Forge\n"
+        "        run: python -m pip install -e . pytest atomadic-forge\n"
+        "      - name: Test\n"
+        "        run: python -m pytest tests/\n"
+        "      - name: Wire\n"
+        f"        run: forge wire src/{package} --fail-on-violations\n"
+        "      - name: Certify\n"
+        f"        run: forge certify . --package {package} --fail-under {fail_under}\n"
+    )
+
+
+def render_changelog(*, package: str, intent: str = "") -> str:
+    safe_intent = (intent or "Materialized by Atomadic Forge.").strip()
+    safe_intent = safe_intent.replace("\r", " ").replace("\n", " ")
+    return (
+        "# Changelog\n"
+        "\n"
+        "All notable changes to this project are documented here. This file is\n"
+        "created by Atomadic Forge so generated packages start with release\n"
+        "discipline instead of acquiring it after the first production scare.\n"
+        "\n"
+        "## 0.1.0 - Generated\n"
+        "\n"
+        f"- Created `{package}` from an emergent Forge materialization pipeline.\n"
+        f"- Intent: {safe_intent}\n"
+        "- Added a tier-organized package skeleton, smoke tests, and a Forge CI gate.\n"
+        "- Preserved the generated scan receipt under `.atomadic-forge/` for replay.\n"
+    )