atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/recipes.py

@@ -0,0 +1,186 @@
+"""Tier a1 — golden-path recipes (Codex #12).
+
+Codex's prescription:
+
+  > For common agent tasks: recipe_release_hardening,
+  > recipe_add_cli_command, recipe_fix_wire_violation,
+  > recipe_add_feature, recipe_publish_mcp. Each returns a
+  > checklist, file scope, and validation gate. Agents love rails.
+
+Pure: a recipe is a static dict. ``get_recipe(name)`` returns it,
+``list_recipes()`` returns the catalogue.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+SCHEMA_VERSION_RECIPE_V1 = "atomadic-forge.recipe/v1"
+
+
+class GoldenRecipe(TypedDict, total=False):
+    schema_version: str
+    name: str
+    description: str
+    checklist: list[str]
+    file_scope_hints: list[str]
+    validation_gate: list[str]
+    notes: list[str]
+
+
+_RECIPES: dict[str, GoldenRecipe] = {
+    "release_hardening": GoldenRecipe(
+        schema_version=SCHEMA_VERSION_RECIPE_V1,
+        name="release_hardening",
+        description=(
+            "Add CI + CHANGELOG entry + version bump + signed Receipt "
+            "before tagging a release."
+        ),
+        checklist=[
+            "Add or update .github/workflows/ci.yml",
+            "Append a CHANGELOG.md entry under the new version",
+            "Bump version in pyproject.toml (or package.json)",
+            "Run forge certify . --emit-receipt --sign",
+            "Run forge wire src --fail-on-violations",
+            "Tag the commit with the new version",
+        ],
+        file_scope_hints=[
+            ".github/workflows/ci.yml",
+            "CHANGELOG.md",
+            "pyproject.toml",
+        ],
+        validation_gate=[
+            "python -m ruff check .",
+            "python -m pytest",
+            "forge wire src --fail-on-violations",
+            "forge certify . --fail-under 90",
+        ],
+        notes=[
+            "Lane G1 ships --fail-under and --fail-on-violations natively; "
+            "use them instead of python -c JSON-parse fallbacks.",
+        ],
+    ),
+    "add_cli_command": GoldenRecipe(
+        schema_version=SCHEMA_VERSION_RECIPE_V1,
+        name="add_cli_command",
+        description=(
+            "Add a new top-level Forge verb (or sibling-tool verb) "
+            "with tier-clean wiring."
+        ),
+        checklist=[
+            "Decide whether the logic is pure (a1), stateful (a2), or "
+            "feature-orchestrating (a3); CLI wrapper goes in a4.",
+            "Implement the pure helper in the right tier.",
+            "Add the @app.command(...) handler in cli.py with --json "
+            "and (where applicable) --fail-on flags.",
+            "Add a smoke test in tests/test_cli_smoke.py + a unit test "
+            "for the pure helper.",
+            "Run forge wire src --fail-on-violations to confirm tier "
+            "discipline; bump CHANGELOG.",
+        ],
+        file_scope_hints=[
+            "src/atomadic_forge/aN_*/<your_module>.py",
+            "src/atomadic_forge/a4_sy_orchestration/cli.py",
+            "tests/test_cli_smoke.py",
+            "CHANGELOG.md",
+        ],
+        validation_gate=[
+            "python -m pytest tests/test_cli_smoke.py",
+            "forge wire src/atomadic_forge --fail-on-violations",
+        ],
+    ),
+    "fix_wire_violation": GoldenRecipe(
+        schema_version=SCHEMA_VERSION_RECIPE_V1,
+        name="fix_wire_violation",
+        description=(
+            "Resolve a tier upward-import violation surfaced by "
+            "forge wire (F0040–F0049)."
+        ),
+        checklist=[
+            "Run forge wire <pkg> --suggest-repairs to read the "
+            "F-code + suggested move.",
+            "Decide: move the file UP to the higher tier (default), "
+            "or invert the import direction by extracting the symbol "
+            "DOWN to a lower tier.",
+            "Run forge enforce <pkg> --apply for F0041..F0046 "
+            "(rollback-safe orchestrator).",
+            "Re-run forge wire to confirm zero violations.",
+            "Re-run forge certify to confirm score recovered.",
+        ],
+        file_scope_hints=[
+            "src/<pkg>/aN_*/<violating_file>.py",
+        ],
+        validation_gate=[
+            "forge wire <pkg> --fail-on-violations",
+            "python -m pytest",
+            "forge certify . --fail-under 75",
+        ],
+    ),
+    "add_feature": GoldenRecipe(
+        schema_version=SCHEMA_VERSION_RECIPE_V1,
+        name="add_feature",
+        description=(
+            "Implement a feature that combines existing a1 helpers "
+            "and a2 composites under an a3 module."
+        ),
+        checklist=[
+            "Read existing a3 features for tone + shape.",
+            "Add the feature module under a3_og_features/.",
+            "If the feature has a CLI surface, add a thin wrapper in "
+            "a4_sy_orchestration/cli.py.",
+            "Tests cover the pure parts at a1 level + the feature at a3.",
+            "Run forge wire to confirm no upward imports.",
+        ],
+        file_scope_hints=[
+            "src/atomadic_forge/a3_og_features/<feature>.py",
+            "src/atomadic_forge/a4_sy_orchestration/cli.py",
+            "tests/test_<feature>.py",
+        ],
+        validation_gate=[
+            "python -m pytest",
+            "forge wire src/atomadic_forge --fail-on-violations",
+            "forge certify . --fail-under 75",
+        ],
+    ),
+    "publish_mcp": GoldenRecipe(
+        schema_version=SCHEMA_VERSION_RECIPE_V1,
+        name="publish_mcp",
+        description=(
+            "Register Forge as an MCP server in a coding-agent client "
+            "(Cursor / Claude Code / Aider / Devin)."
+        ),
+        checklist=[
+            "Install Forge: pip install -e . (or pip install "
+            "atomadic-forge once on PyPI).",
+            "Add a 'forge' entry to the client's mcpServers map.",
+            "command = 'forge'; args = ['mcp', 'serve', '--project', "
+            "'/path/to/your/repo'].",
+            "Reconnect the client; expect tools/list to expose 11 "
+            "tools incl. context_pack, preflight_change, score_patch.",
+            "Hit forge://summary/blockers as the agent's first call "
+            "for orientation.",
+        ],
+        file_scope_hints=[
+            "<your-mcp-config>.json",
+        ],
+        validation_gate=[
+            "forge mcp serve --project . < /dev/null",
+        ],
+        notes=[
+            "On Windows, use absolute paths with forward slashes in "
+            "the MCP config to avoid escape-character issues.",
+        ],
+    ),
+}
+
+
+def list_recipes() -> list[str]:
+    return sorted(_RECIPES.keys())
+
+
+def get_recipe(name: str) -> GoldenRecipe | None:
+    return _RECIPES.get(name)
+
+
+def all_recipes() -> dict[str, GoldenRecipe]:
+    """Return the full recipe catalogue (read-only-by-convention)."""
+    return dict(_RECIPES)

atomadic_forge/a1_at_functions/repo_explainer.py

@@ -0,0 +1,124 @@
+"""Tier a1 — explain_repo: humane operational orientation (Codex #6).
+
+Codex distinguished this from context_pack:
+
+  > 'This is different from docs. It is operational orientation.
+  >  Output: This is a Python package for…  Core flow is…  Do not
+  >  break…  Most important tests are…  Release state is…'
+
+Pure: takes already-computed reports (or None) and emits a short
+operational paragraph + a few bullets the agent should treat as
+hard constraints.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+SCHEMA_VERSION_EXPLAIN_V1 = "atomadic-forge.explain_repo/v1"
+
+
+class RepoExplanation(TypedDict, total=False):
+    schema_version: str
+    project_root: str
+    one_liner: str
+    core_flow: str
+    do_not_break: list[str]
+    important_tests: list[str]
+    release_state: str
+    depth: str
+
+
+def _detect_core_flow(scout_report: dict | None) -> str:
+    if not scout_report:
+        return "(scout report unavailable; run forge recon)"
+    tiers = scout_report.get("tier_distribution") or {}
+    if not tiers:
+        return "(repo has no tier-organized symbols)"
+    primary_tier = max(tiers.items(), key=lambda kv: kv[1])[0]
+    return (
+        f"primary symbol density is in {primary_tier} "
+        f"({tiers[primary_tier]} symbols). "
+        f"a4_sy_orchestration calls into a3 features which compose "
+        f"a2 stateful classes from a1 pure functions over a0 "
+        f"constants — the upward-only law applies."
+    )
+
+
+def _detect_release_state(certify_report: dict | None,
+                           wire_report: dict | None) -> str:
+    if certify_report is None and wire_report is None:
+        return "(no certify / wire scans available)"
+    score = (certify_report or {}).get("score")
+    wire_verdict = (wire_report or {}).get("verdict", "?")
+    # Wire FAIL is blocking regardless of whether certify ran.
+    if wire_verdict == "FAIL":
+        return f"BLOCKED — wire verdict={wire_verdict}; fix violations first."
+    if score is None:
+        return f"wire={wire_verdict}; no certify score available."
+    if score >= 100 and wire_verdict == "PASS":
+        return "PASS — every gate green; ready to ship."
+    if score >= 75 and wire_verdict == "PASS":
+        return f"GREEN-ISH — score {score:.0f}/100; ship-ready by team-grade gate."
+    return f"REFINE — score {score:.0f}/100 below shipping bar."
+
+
+def _important_tests(project_root: Path) -> list[str]:
+    """Heuristic: tests at the top of tests/ are usually the smoke +
+    contract tests; tests with 'smoke' or 'contract' in the name
+    explicitly. Cap at 5."""
+    out: list[str] = []
+    for sub in ("tests", "test"):
+        d = project_root / sub
+        if not d.is_dir():
+            continue
+        # Smoke / contract first.
+        for f in sorted(d.glob("test_*.py")):
+            n = f.name.lower()
+            if "smoke" in n or "contract" in n or "import" in n:
+                out.append(str(f.relative_to(project_root).as_posix()))
+        # Then any other top-level tests/.
+        for f in sorted(d.glob("test_*.py")):
+            rel = str(f.relative_to(project_root).as_posix())
+            if rel not in out:
+                out.append(rel)
+            if len(out) >= 5:
+                break
+        break
+    return out[:5]
+
+
+def explain_repo(
+    *,
+    project_root: Path,
+    repo_purpose: str,
+    scout_report: dict | None = None,
+    wire_report: dict | None = None,
+    certify_report: dict | None = None,
+    depth: str = "agent",
+) -> RepoExplanation:
+    """Build the humane orientation paragraph + bullets.
+
+    ``depth`` is reserved for future variants ('agent' | 'reviewer' |
+    'newcomer'); v1 emits the agent-tuned version regardless.
+    """
+    project_root = Path(project_root).resolve()
+    one_liner = (repo_purpose or f"Repo at {project_root.name}")[:200]
+    do_not_break = [
+        "the upward-only tier law (a0 → a1 → a2 → a3 → a4); "
+        "any wire violation blocks merge",
+        "public re-exports in __init__.py — touching them is a "
+        "public_api_risk in score_patch",
+        "release-control files (pyproject.toml, CHANGELOG.md, "
+        "VERSION) — version bumps require a CHANGELOG entry",
+    ]
+    return RepoExplanation(
+        schema_version=SCHEMA_VERSION_EXPLAIN_V1,
+        project_root=str(project_root),
+        one_liner=one_liner,
+        core_flow=_detect_core_flow(scout_report),
+        do_not_break=do_not_break,
+        important_tests=_important_tests(project_root),
+        release_state=_detect_release_state(certify_report, wire_report),
+        depth=depth,
+    )

atomadic_forge/a1_at_functions/roi_calculator.py

@@ -0,0 +1,265 @@
+"""Tier a1 — pure ROI calculator for ForgeReceiptV1.
+
+Golden Path Lane F W3.
+
+Given a ForgeReceiptV1 dict, applies the CISQ cost model to estimate:
+  * structural defects identified by Forge (wire violations + certify axes)
+  * avoided remediation cost (finding at architecture layer vs production)
+  * annual technical-debt carry cost eliminated
+  * CIO-facing ROI summary in USD
+
+All numbers use conservative CISQ 2022 lower-bound figures so enterprise
+claims remain defensible. See ``a0_qk_constants/roi_constants.py`` for
+source citations.
+"""
+from __future__ import annotations
+
+from atomadic_forge.a0_qk_constants.roi_constants import (
+    ANNUAL_CARRY_COST_PER_KLOC_USD,
+    CISQ_CITATION,
+    CISQ_REFERENCE_YEAR,
+    COST_PER_CERTIFY_AXIS_FAIL_USD,
+    COST_PER_DEFECT_PRODUCTION_USD,
+    COST_PER_STRUCTURAL_DEFECT_USD,
+    DEFAULT_TEAM_HOURLY_RATE_USD,
+    HOURS_PER_CERTIFY_AXIS_FIX,
+    HOURS_PER_STRUCTURAL_DEFECT_FIX,
+    NIST_CITATION,
+    SCORE_THRESHOLD_GOOD,
+    SCORE_THRESHOLD_PASS,
+    SYMBOLS_PER_KLOC,
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _wire(r: dict) -> dict:
+    return r.get("wire") or {}
+
+
+def _certify(r: dict) -> dict:
+    return r.get("certify") or {}
+
+
+def _scout(r: dict) -> dict:
+    return r.get("scout") or {}
+
+
+def _axes_fail_count(r: dict) -> int:
+    axes = _certify(r).get("axes") or {}
+    return sum(1 for v in axes.values() if not v)
+
+
+def _symbol_count(r: dict) -> int:
+    return int(_scout(r).get("symbol_count") or 0)
+
+
+def _kloc_estimate(r: dict) -> float:
+    symbols = _symbol_count(r)
+    if symbols <= 0:
+        return 0.0
+    return symbols / SYMBOLS_PER_KLOC
+
+
+def _score(r: dict) -> float:
+    return float(_certify(r).get("score", 0.0))
+
+
+def _wire_violations(r: dict) -> int:
+    return int(_wire(r).get("violation_count") or 0)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def calculate_roi(
+    receipt: dict,
+    team_hourly_rate: float = DEFAULT_TEAM_HOURLY_RATE_USD,
+) -> dict:
+    """Calculate TD-principal reduction estimate from a ForgeReceiptV1.
+
+    Returns a dict with all figures in USD, ready to embed in a Receipt
+    or render as a Markdown report::
+
+        {
+            "wire_violations": int,
+            "certify_score": float,
+            "certify_axes_failing": int,
+            "estimated_structural_defects": float,
+            "avoided_remediation_cost_usd": float,   # catch-at-arch vs catch-at-prod
+            "annual_carry_reduction_usd": float,
+            "fix_effort_hours": float,
+            "fix_effort_cost_usd": float,
+            "roi_multiplier": float,                 # avoided_cost / fix_cost
+            "grade": str,                            # PASS / GOOD / FAIR / POOR
+            "cisq_reference_year": str,
+            "team_hourly_rate_usd": float,
+        }
+
+    Never raises. Returns zeros for an empty receipt.
+    """
+    if not receipt:
+        return _zero_roi()
+
+    violations = _wire_violations(receipt)
+    axes_failing = _axes_fail_count(receipt)
+    kloc = _kloc_estimate(receipt)
+    score = _score(receipt)
+
+    # Total structural defects: each wire violation is 1 defect;
+    # each failing certify axis contributes 0.5 (weaker signal).
+    estimated_defects = float(violations) + axes_failing * 0.5
+
+    # Remediation cost at architecture layer (cheap — caught now).
+    review_cost = violations * COST_PER_STRUCTURAL_DEFECT_USD
+    review_cost += axes_failing * COST_PER_CERTIFY_AXIS_FAIL_USD
+
+    # Avoided cost = what it would cost if these reached production.
+    avoided_cost = violations * COST_PER_DEFECT_PRODUCTION_USD
+    avoided_cost += axes_failing * COST_PER_CERTIFY_AXIS_FAIL_USD * 3.0
+
+    # Annual carry cost eliminated by resolving all identified issues.
+    # We credit the full KLOC carry for projects at PASS; partial for others.
+    if score >= SCORE_THRESHOLD_PASS:
+        carry_credit = 0.0  # already clean
+    else:
+        debt_fraction = max(0.0, (SCORE_THRESHOLD_PASS - score) / SCORE_THRESHOLD_PASS)
+        carry_credit = kloc * ANNUAL_CARRY_COST_PER_KLOC_USD * debt_fraction
+
+    # Fix effort — how long it would take to address everything Forge found.
+    fix_hours = violations * HOURS_PER_STRUCTURAL_DEFECT_FIX
+    fix_hours += axes_failing * HOURS_PER_CERTIFY_AXIS_FIX
+    fix_cost = fix_hours * team_hourly_rate
+
+    # ROI multiplier: how many dollars of avoided future cost per dollar of fix cost.
+    total_avoided = avoided_cost + carry_credit
+    roi_mult = (total_avoided / fix_cost) if fix_cost > 0.0 else 0.0
+
+    grade = _grade(score)
+
+    return {
+        "wire_violations": violations,
+        "certify_score": round(score, 2),
+        "certify_axes_failing": axes_failing,
+        "estimated_structural_defects": round(estimated_defects, 1),
+        "avoided_remediation_cost_usd": round(avoided_cost, 2),
+        "annual_carry_reduction_usd": round(carry_credit, 2),
+        "fix_effort_hours": round(fix_hours, 1),
+        "fix_effort_cost_usd": round(fix_cost, 2),
+        "roi_multiplier": round(roi_mult, 1),
+        "grade": grade,
+        "cisq_reference_year": CISQ_REFERENCE_YEAR,
+        "team_hourly_rate_usd": team_hourly_rate,
+    }
+
+
+def _zero_roi() -> dict:
+    return {
+        "wire_violations": 0,
+        "certify_score": 0.0,
+        "certify_axes_failing": 0,
+        "estimated_structural_defects": 0.0,
+        "avoided_remediation_cost_usd": 0.0,
+        "annual_carry_reduction_usd": 0.0,
+        "fix_effort_hours": 0.0,
+        "fix_effort_cost_usd": 0.0,
+        "roi_multiplier": 0.0,
+        "grade": "UNKNOWN",
+        "cisq_reference_year": CISQ_REFERENCE_YEAR,
+        "team_hourly_rate_usd": DEFAULT_TEAM_HOURLY_RATE_USD,
+    }
+
+
+def _grade(score: float) -> str:
+    if score >= SCORE_THRESHOLD_PASS:
+        return "PASS"
+    if score >= SCORE_THRESHOLD_GOOD:
+        return "GOOD"
+    if score >= 60.0:
+        return "FAIR"
+    return "POOR"
+
+
+def render_roi_markdown(roi: dict, project_name: str = "Project") -> str:
+    """Render an ROI dict as a CIO-ready Markdown report.
+
+    The output is a concise Markdown document suitable for:
+      * direct email attachment (rendered by most email clients)
+      * pasting into Confluence / Notion
+      * converting to PDF via ``pandoc`` or ``wkhtmltopdf``
+    """
+    violations = roi["wire_violations"]
+    axes_fail = roi["certify_axes_failing"]
+    defects = roi["estimated_structural_defects"]
+    avoided = roi["avoided_remediation_cost_usd"]
+    carry = roi["annual_carry_reduction_usd"]
+    fix_h = roi["fix_effort_hours"]
+    fix_cost = roi["fix_effort_cost_usd"]
+    mult = roi["roi_multiplier"]
+    grade = roi["grade"]
+    score = roi["certify_score"]
+    rate = roi["team_hourly_rate_usd"]
+    year = roi["cisq_reference_year"]
+
+    grade_icon = {"PASS": "✓", "GOOD": "~", "FAIR": "!", "POOR": "✗"}.get(grade, "?")
+
+    lines = [
+        f"# Forge ROI Report — {project_name}",
+        "",
+        f"**Conformity grade: {grade_icon} {grade}** | Certify score: {score:.0f}/100",
+        "",
+        "## Findings",
+        "",
+        f"| Metric | Count |",
+        f"|---|---|",
+        f"| Wire violations (structural defects) | {violations} |",
+        f"| Certify axes failing | {axes_fail} |",
+        f"| Estimated total structural defects | {defects:.1f} |",
+        "",
+        "## Financial impact (CISQ {year} cost model)".format(year=year),
+        "",
+        f"| Item | USD |",
+        f"|---|---|",
+        f"| Avoided production-defect cost | ${avoided:,.0f} |",
+        f"| Annual technical-debt carry eliminated | ${carry:,.0f} |",
+        f"| Fix effort ({fix_h:.0f} h × ${rate:,.0f}/h) | ${fix_cost:,.0f} |",
+        f"| **ROI multiplier** | **{mult:.1f}×** |",
+        "",
+    ]
+    if mult >= 1.0:
+        lines += [
+            f"Forge identified **{defects:.1f} structural defects**. "
+            f"Fixing them now costs an estimated **${fix_cost:,.0f}** "
+            f"and avoids **${avoided + carry:,.0f}** in future remediation "
+            f"and annual carry — a **{mult:.1f}× return on investment**.",
+            "",
+        ]
+    else:
+        lines += [
+            "No actionable defects detected. This project is already at "
+            "or near structural quality floor.",
+            "",
+        ]
+    lines += [
+        "## Methodology",
+        "",
+        "Cost-per-defect figures are CISQ 2022 lower-bound (conservative):",
+        "",
+        f"- Structural defect caught at architecture layer: ${COST_PER_STRUCTURAL_DEFECT_USD:,.0f}",
+        f"- Same defect reaching production: ${COST_PER_DEFECT_PRODUCTION_USD:,.0f}",
+        f"- Annual carry per KLOC of technical debt: ${ANNUAL_CARRY_COST_PER_KLOC_USD:,.0f}",
+        "",
+        "**References**",
+        "",
+        f"1. {CISQ_CITATION}",
+        f"2. {NIST_CITATION}",
+        "",
+        "_Generated by Atomadic Forge. Figures are estimates based on "
+        "industry-average defect costs; actual costs may vary._",
+    ]
+    return "\n".join(lines) + "\n"