faf-python-sdk 1.2.0__tar.gz → 1.3.0__tar.gz

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to faf-python-sdk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [1.3.0] - 2026-09-06 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+### Added
+- `faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`,
+  Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, kept in
+  parity with the canonical TypeScript. Deterministic BETTER-shaped projection:
+  `## Setup & build` (install→build→dev ordered) · `## Run the tests` ·
+  `## Where things live` · `## Conventions` · three-tier `## Guardrails` ·
+  `## Definition of Done` · `## When stuck` · `## Security & secrets` ·
+  `## Commit & PR` · `## Stack`. Human Context (who/why marketing) is
+  intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA.
+- `faf_meta_tag(faf)`, `title_label(key)`, `slot_label(path)` — the shared
+  label + metastamp helpers, also from `src/interop`.
+- Both generators take the **raw parsed dict** (`FafFile.data.raw`) — the .faf
+  format carries top-level `commands` / `key_files` / `security` that the typed
+  model doesn't surface.
+- 17 tests, including deterministic-output and human-context-omission guards.
+
+### Fixed
+- `[tool.mypy] python_version` was `"3.9"` — rejected by modern mypy
+  (`must be 3.10 or higher`). Set to `"3.10"`.
+
 ## [1.2.0] - 2026-06-16 — The Dart Edition
 
 Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/CLAUDE.md

@@ -1,21 +1,22 @@
-<!-- faf: faf-python-sdk | Python |  | Python SDK for parsing, validating, and scoring .faf files with Mk4 Championship Engine -->
+<!-- faf:start -->
+<!-- faf: faf-python-sdk | Python |  | Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on -->
 <!-- faf: claim=project.faf | family=FAF -->
 
 # CLAUDE.md — faf-python-sdk
 
 ## What This Is
 
-Python SDK for parsing, validating, and scoring .faf files with Mk4 Championship Engine
+Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on
 
 ## Stack
 
 - **Language:** Python
 - **Backend:** Python
-- **Api Type:** SDK (library)
+- **API:** SDK (library)
 - **Runtime:** Python 3.8+
 - **Hosting:** PyPI
 - **Build:** hatchling
-- **Cicd:** GitHub Actions
+- **CI/CD:** GitHub Actions
 
 ## Context
 
@@ -28,4 +29,5 @@ Python SDK for parsing, validating, and scoring .faf files with Mk4 Championship
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-06-16T20:16:30.936Z*
+*STATUS: BI-SYNC ACTIVE — 2026-09-06T18:19:41.228Z*
+<!-- faf:end -->

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.2.0
+Version: 1.3.0
 Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
 Project-URL: Homepage, https://faf.one
 Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
@@ -41,17 +41,30 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-196%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.3.0 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+`faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.
+
+```python
+from faf_sdk import parse_file, generate_agents_md
+
+faf = parse_file("project.faf")
+print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+```
+
+Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+
 ## What's New in v1.2.0 — The Dart Edition
 
 Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
 
-The SDK's first detection capability — it now reads a `pubspec.yaml` and tells you *what kind* of Dart project it is, not just parse/validate/score. The detection KNOWLEDGE is vendored byte-identical from faf-cli (the single source) and ships in the wheel:
-
 ```python
 from faf_sdk import detect_dart_project
 

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/README.md

@@ -9,17 +9,30 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-196%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.3.0 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+`faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.
+
+```python
+from faf_sdk import parse_file, generate_agents_md
+
+faf = parse_file("project.faf")
+print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+```
+
+Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+
 ## What's New in v1.2.0 — The Dart Edition
 
 Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
 
-The SDK's first detection capability — it now reads a `pubspec.yaml` and tells you *what kind* of Dart project it is, not just parse/validate/score. The detection KNOWLEDGE is vendored byte-identical from faf-cli (the single source) and ships in the wheel:
-
 ```python
 from faf_sdk import detect_dart_project
 

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/faf_sdk/__init__.py

@@ -25,6 +25,7 @@ from .validator import validate, ValidationResult
 from .mk4 import score_faf, Mk4Result, SlotState, LicenseTier
 from .discovery import find_faf_file, find_project_root, load_fafignore
 from .detect import detect_dart_project, DartProject
+from .interop import generate_agents_md, generate_gemini_md, faf_meta_tag
 from .types import (
     FafData,
     ProjectInfo,
@@ -35,7 +36,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 __all__ = [
     # Parser
     "parse",
@@ -57,6 +58,10 @@ __all__ = [
     # Detection (Dart/Flutter — A+B hybrid, parity with faf-cli)
     "detect_dart_project",
     "DartProject",
+    # Interop — AGENTS.md / GEMINI.md generators (parity with faf-cli src/interop)
+    "generate_agents_md",
+    "generate_gemini_md",
+    "faf_meta_tag",
     # Types
     "FafData",
     "ProjectInfo",

faf_python_sdk-1.3.0/faf_sdk/interop.py

@@ -0,0 +1,403 @@
+"""
+AI-context file generators — AGENTS.md and GEMINI.md from .faf data.
+
+Python port of faf-cli's `src/interop/agents.ts` + `gemini.ts`, kept in
+parity with the canonical TypeScript. Deterministic projection from curated
+truth — facts, not freewritten prose. Human Context (who/why marketing) is
+intentionally omitted from AGENTS.md; it belongs in the README / .faf DNA,
+not agent ops.
+
+Both take the raw parsed .faf dict (`FafFile.data.raw`) — the .faf format
+carries top-level `commands` / `key_files` / `security` that the typed model
+doesn't surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["generate_agents_md", "generate_gemini_md", "faf_meta_tag", "title_label", "slot_label"]
+
+# --- shared helpers ----------------------------------------------------------
+
+_ACRONYMS = {
+    "API", "CI", "CD", "MCP", "CLI", "SDK", "UI", "UX", "AI", "ML", "DB", "ORM",
+    "OS", "HTTP", "HTTPS", "REST", "RPC", "JSON", "YAML", "XML", "SQL", "CSS",
+    "HTML", "AWS", "GCP", "CDN", "DNS", "JWT", "ID", "IP", "URL", "URI", "TS", "JS",
+}
+
+# Canonical .faf slot labels (from faf-cli src/core/slots.ts).
+_SLOT_LABELS = {
+    "stack.frontend": "Framework", "stack.css_framework": "CSS",
+    "stack.ui_library": "UI Library", "stack.state_management": "State",
+    "stack.backend": "Backend", "stack.api_type": "API", "stack.runtime": "Runtime",
+    "stack.database": "Database", "stack.connection": "Connection",
+    "stack.hosting": "Hosting", "stack.build": "Build", "stack.cicd": "CI/CD",
+    "stack.monorepo_tool": "Monorepo", "stack.package_manager": "Package Manager",
+    "stack.workspaces": "Workspaces", "stack.admin": "Admin", "stack.cache": "Cache",
+    "stack.search": "Search", "stack.storage": "Storage",
+}
+
+# Preference keys that describe human<->assistant interaction, not repo conventions.
+_HUMAN_PREF = {
+    "commit_style", "communication", "response_style", "explanation_level",
+    "explanations", "documentation", "code_first",
+}
+
+# Stack keys that are context/marketing, not actual stack.
+_NON_STACK = {"target_user", "core_problem", "mission_purpose"}
+
+
+def _present(v: Any) -> bool:
+    """Non-empty, not 'slotignored', non-empty list."""
+    if v is None or v == "" or v == "slotignored":
+        return False
+    if isinstance(v, (list, tuple)) and len(v) == 0:
+        return False
+    return True
+
+
+def _filled(v: Any) -> bool:
+    """A string slot value carrying real content."""
+    return isinstance(v, str) and v.strip() not in ("", "slotignored")
+
+
+def _fmt_val(v: Any) -> str:
+    if isinstance(v, (list, tuple)):
+        return ", ".join(str(x) for x in v)
+    return str(v)
+
+
+def title_label(key: str) -> str:
+    """snake_case -> Title Case, acronym-aware. `api_type` -> 'API Type'."""
+    out: list[str] = []
+    for w in key.split("_"):
+        if not w:
+            out.append(w)
+        elif w.upper() in _ACRONYMS:
+            out.append(w.upper())
+        else:
+            out.append(w[0].upper() + w[1:])
+    return " ".join(out)
+
+
+def slot_label(path: str) -> str:
+    """Canonical display label for a .faf slot path; falls back to title_label."""
+    if path in _SLOT_LABELS:
+        return _SLOT_LABELS[path]
+    key = path.rsplit(".", 1)[-1] if "." in path else path
+    return title_label(key)
+
+
+def faf_meta_tag(faf: dict) -> str:
+    """The two-line `<!-- faf: ... -->` metastamp every faf-generated file opens with."""
+    proj = faf.get("project") or {}
+    name = str(proj.get("name") or "").strip()
+    lang = str(proj.get("main_language") or "").strip()
+    typ = str(proj.get("type") or "").strip()
+    desc = str(proj.get("goal") or "").strip()
+    line1 = f"<!-- faf: {' | '.join([name, lang, typ, desc])} -->"
+    kv = ["claim=project.faf", "family=FAF"]
+    line2 = f"<!-- faf: {' | '.join(kv)} -->"
+    return f"{line1}\n{line2}"
+
+
+# --- command classification (shared by both generators) ---------------------
+
+def _classify_commands(faf: dict) -> dict:
+    commands = faf.get("commands") or {}
+    entries = [(k, v) for k, v in commands.items() if _present(v)]
+    test_cmds = [(k, v) for k, v in entries if "test" in k.lower()]
+    lint_cmds = [
+        (k, v) for k, v in entries
+        if ("lint" in k.lower() or "check" in k.lower()) and "test" not in k.lower()
+    ]
+    setup_raw = [
+        (k, v) for k, v in entries
+        if not any(t in k.lower() for t in ("test", "lint", "check"))
+    ]
+
+    def setup_rank(k: str) -> int:
+        n = k.lower()
+        if "install" in n or "deps" in n:
+            return 0
+        if "build" in n and "rebuild" not in n:
+            return 1
+        if n == "dev" or "develop" in n:
+            return 2
+        if n == "start" or "run" in n:
+            return 3
+        return 4
+
+    setup_cmds = sorted(setup_raw, key=lambda kv: (setup_rank(kv[0]), kv[0]))
+    verify_cmds = test_cmds + lint_cmds
+    return {
+        "test": test_cmds, "lint": lint_cmds, "setup": setup_cmds, "verify": verify_cmds,
+    }
+
+
+def _key_files(faf: dict) -> list:
+    kf = faf.get("key_files")
+    if not kf:
+        ic = faf.get("instant_context") or {}
+        kf = ic.get("key_files")
+    return kf or []
+
+
+# --- AGENTS.md -------------------------------------------------------------
+
+def generate_agents_md(faf: dict) -> str:
+    """Author a BETTER-shaped AGENTS.md from raw .faf data. Deterministic."""
+    lines: list[str] = []
+
+    def push(s: str = "") -> None:
+        lines.append(s)
+
+    proj = faf.get("project") or {}
+    ai = faf.get("ai_instructions") or {}
+    prefs = faf.get("preferences") or {}
+    security = faf.get("security") or {}
+    branch = str(proj["default_branch"]) if _present(proj.get("default_branch")) else "main"
+
+    cmds = _classify_commands(faf)
+    setup_cmds, test_cmds, lint_cmds, verify_cmds = (
+        cmds["setup"], cmds["test"], cmds["lint"], cmds["verify"],
+    )
+    test_cmd = test_cmds[0][1] if test_cmds else None
+    build_cmd = next((v for k, v in setup_cmds if "build" in k.lower()), None)
+    key_files = _key_files(faf)
+
+    push(faf_meta_tag(faf))
+    push()
+    push(f"# AGENTS.md — {proj.get('name') or 'Project'}")
+    push()
+
+    # 1 - orientation
+    bits: list[str] = []
+    if proj.get("main_language"):
+        bits.append(str(proj["main_language"]))
+    if _present(proj.get("type")):
+        bits.append(f"type: {proj['type']}")
+    if _present(proj.get("version")):
+        bits.append(f"v{proj['version']}")
+    orientation = str(proj["goal"]).strip() if proj.get("goal") else ""
+    if bits:
+        orientation += (" — " if orientation else "") + " · ".join(bits)
+    if orientation:
+        push(orientation)
+        push()
+    push(
+        "> Authored by faf — refresh with `faf export --agents` or the "
+        "`faf_agents` MCP tool. The managed block is regenerated each time; "
+        "hand-written content outside it is preserved."
+    )
+    push()
+
+    # 2 - setup & build
+    if setup_cmds:
+        push("## Setup & build")
+        push()
+        push("```bash")
+        for k, v in setup_cmds:
+            push(f"{v}    # {k}")
+        push("```")
+        push()
+
+    # 3 - run the tests
+    if verify_cmds:
+        push("## Run the tests")
+        push()
+        push("```bash")
+        for _, v in verify_cmds:
+            push(v)
+        push("```")
+        push()
+
+    # 4 - where things live
+    if key_files:
+        push("## Where things live")
+        push()
+        rows = []
+        for f in key_files:
+            s = str(f)
+            at = s.find(" — ")
+            rows.append((s[:at], s[at + 3:]) if at > 0 else (s, ""))
+        if any(role for _, role in rows):
+            push("| Path | Role |")
+            push("|------|------|")
+            for path, role in rows:
+                push(f"| `{path}` | {role} |")
+        else:
+            for path, _ in rows:
+                push(f"- `{path}`")
+        push()
+
+    # 5 - conventions
+    conventions: dict[str, str] = {}
+
+    def collect(obj: Any) -> None:
+        if not isinstance(obj, dict):
+            return
+        for k, v in obj.items():
+            if k in _HUMAN_PREF or not _present(v):
+                continue
+            label = title_label(k)
+            conventions.setdefault(label, _fmt_val(v))
+
+    collect(ai.get("working_style"))
+    collect(prefs)
+    detected_conv = faf.get("conventions") or []
+    if conventions or detected_conv:
+        push("## Conventions")
+        push()
+        for label, val in conventions.items():
+            push(f"- **{label}:** {val}")
+        for c in detected_conv:
+            if _present(c):
+                push(f"- {c}")
+        push()
+
+    # 6 - guardrails
+    warnings = [w for w in (ai.get("warnings") or []) if _present(w)]
+    always = ["read the tree"]
+    if test_cmd:
+        always.append(f"run the tests (`{test_cmd}`)")
+    if build_cmd:
+        always.append("build the project")
+    for _, v in lint_cmds[:1]:
+        always.append(f"`{v}`")
+    push("## Guardrails")
+    push()
+    for w in warnings:
+        push(f"- {w}")
+    push(f"- **Always OK:** {' · '.join(dict.fromkeys(always))}.")
+    push("- **Ask first:** dependency installs, deletions, migrations, schema changes, publish/release.")
+    push(
+        f"- **Never:** force-push · push straight to `{branch}` (branch and open a PR) · commit secrets."
+    )
+    push()
+
+    # 7 - definition of done
+    dod: list[str] = []
+    for _, v in lint_cmds:
+        dod.append(f"`{v}` exits 0")
+    for _, v in test_cmds:
+        dod.append(f"`{v}` passes")
+    dod.append("changes committed with a conventional message")
+    push("## Definition of Done")
+    push()
+    push(f"Done when: {' · '.join(dict.fromkeys(dod))}.")
+    push()
+
+    # 8 - when stuck
+    push("## When stuck")
+    push()
+    push(
+        "Ask a clarifying question, propose a short plan, or open a draft PR with "
+        f"notes — do not push large speculative changes to `{branch}`."
+    )
+    push()
+
+    # 9 - security & secrets
+    if security and (_present(security.get("secrets")) or (security.get("never") or [])):
+        push("## Security & secrets")
+        push()
+        if _present(security.get("secrets")):
+            ex = f" (see `{security['example']}`)" if _present(security.get("example")) else ""
+            push(f"- Secrets live in `{security['secrets']}`{ex}. Never read or commit them.")
+        for n in security.get("never") or []:
+            if _present(n):
+                push(f"- Never read or commit `{n}`.")
+        push()
+
+    # 10 - commit & PR
+    push("## Commit & PR")
+    push()
+    if _present(prefs.get("commit_style")):
+        push(f"- Commit style: {_fmt_val(prefs['commit_style'])}")
+    else:
+        push("- Conventional Commits preferred (`feat:`, `fix:`, `chore:`, …).")
+    push(f"- Branch off `{branch}` and open a PR — never commit to `{branch}` directly.")
+    push("- If build/test scripts or layout change, refresh this file in the **same PR**.")
+    push()
+
+    # stack (reference)
+    stack = faf.get("stack") or {}
+    if isinstance(stack, dict):
+        rendered = [
+            f"- **{slot_label(f'stack.{k}')}:** {v.strip()}"
+            for k, v in stack.items()
+            if k not in _NON_STACK and _filled(v)
+        ]
+        if rendered:
+            push("## Stack")
+            push()
+            lines.extend(rendered)
+            push()
+
+    gen = faf.get("generated")
+    if _present(gen):
+        push(f"*Context authored: {gen}*")
+
+    return "\n".join(lines)
+
+
+# --- GEMINI.md ------------------------------------------------------------
+
+def generate_gemini_md(faf: dict) -> str:
+    """GEMINI.md — Gemini CLI's own convention (hierarchical, @file-importable)."""
+    lines: list[str] = []
+    proj = faf.get("project") or {}
+    cmds = _classify_commands(faf)
+    setup_cmds, verify_cmds = cmds["setup"], cmds["verify"]
+    key_files = _key_files(faf)
+
+    lines.append(faf_meta_tag(faf))
+    lines.append("")
+    lines.append(f"# GEMINI.md — {proj.get('name') or 'Project'}")
+    lines.append("")
+    lines.append("> Authored from project.faf — refresh with the `faf_gemini` MCP tool or `faf export --gemini`.")
+    lines.append("")
+
+    if proj.get("name"):
+        lines.append(f"Project: {proj['name']}")
+    if proj.get("goal"):
+        lines.append(f"Goal: {proj['goal']}")
+    if proj.get("main_language"):
+        lines.append(f"Language: {proj['main_language']}")
+
+    if setup_cmds:
+        lines += ["", "## Setup & build", "", "```bash"]
+        for k, v in setup_cmds:
+            lines.append(f"{v}    # {k}")
+        lines.append("```")
+
+    if verify_cmds:
+        lines += ["", "## Test & verify", "", "```bash"]
+        for _, v in verify_cmds:
+            lines.append(v)
+        lines.append("```")
+
+    if key_files:
+        lines += ["", "## Where things live", ""]
+        for f in key_files:
+            lines.append(f"- `{f}`")
+
+    stack = faf.get("stack") or {}
+    if isinstance(stack, dict):
+        rendered = [
+            f"- {slot_label(f'stack.{k}')}: {v.strip()}"
+            for k, v in stack.items()
+            if k not in _NON_STACK and _filled(v)
+        ]
+        if rendered:
+            lines += ["", "## Stack"]
+            lines.extend(rendered)
+
+    lines += [
+        "", "## Before changing things", "",
+        "- Ask first: dependency installs, deletions, migrations, schema changes, publish/release.",
+        "- Never: force-push · push straight to `main` · commit secrets.",
+        "",
+    ]
+    return "\n".join(lines)

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/project.faf

@@ -1,7 +1,7 @@
-faf_version: '2.5.0'
+faf_version: "3.0"
 project:
   name: faf-python-sdk
-  goal: Python SDK for parsing, validating, and scoring .faf files with Mk4 Championship Engine
+  goal: Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on
   main_language: Python
 human_context:
   who: Python developers building AI tools, MCP servers, and CI pipelines

{faf_python_sdk-1.2.0 → faf_python_sdk-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faf-python-sdk"
-version = "1.2.0"
+version = "1.3.0"
 description = "Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml."
 readme = "README.md"
 license = {text = "MIT"}
@@ -61,7 +61,7 @@ packages = ["faf_sdk"]
 artifacts = ["faf_sdk/dart_detection.json"]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -69,3 +69,7 @@ disallow_untyped_defs = true
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = "test_*.py"
+
+# PEP 561 — mark package as typed for mypy consumers (gemini-faf-mcp, etc.)
+[tool.hatch.build.targets.wheel.force-include]
+"faf_sdk/py.typed" = "faf_sdk/py.typed"

faf_python_sdk-1.3.0/tests/test_interop.py

@@ -0,0 +1,178 @@
+"""Tests for faf_sdk.interop — AGENTS.md / GEMINI.md generators."""
+
+from faf_sdk import faf_meta_tag, generate_agents_md, generate_gemini_md
+from faf_sdk.interop import slot_label, title_label
+
+# A representative .faf as the raw parsed dict.
+SAMPLE = {
+    "faf_version": "3.0",
+    "project": {
+        "name": "widget-api",
+        "goal": "REST API for widget inventory",
+        "main_language": "TypeScript",
+        "type": "api",
+        "version": "2.1.0",
+    },
+    "commands": {
+        "install": "npm ci",
+        "build": "npm run build",
+        "dev": "npm run dev",
+        "test": "npm test",
+        "lint": "npm run lint",
+    },
+    "key_files": ["src/server.ts — the entry point", "src/routes/ — the handlers"],
+    "ai_instructions": {
+        "warnings": ["Never touch the billing module without a review"],
+        "working_style": {"testing": "required", "quality_bar": "zero_errors"},
+    },
+    "preferences": {"commit_style": "conventional", "communication": "direct"},
+    "security": {"secrets": ".env", "example": ".env.example"},
+    "stack": {
+        "backend": "fastify",
+        "database": "postgres",
+        "api_type": "rest",
+        "target_user": "developers",
+    },
+    "generated": "2026-09-06T00:00:00Z",
+}
+
+
+# --- helpers ---------------------------------------------------------------
+
+def test_title_label_acronyms():
+    assert title_label("api_type") == "API Type"
+    assert title_label("mcp_sdk") == "MCP SDK"
+    assert title_label("runtime") == "Runtime"
+    assert title_label("state_management") == "State Management"
+
+
+def test_slot_label_canonical_then_fallback():
+    assert slot_label("stack.cicd") == "CI/CD"
+    assert slot_label("stack.api_type") == "API"
+    assert slot_label("stack.made_up_key") == "Made Up Key"
+
+
+def test_faf_meta_tag_two_lines():
+    tag = faf_meta_tag(SAMPLE)
+    line1, line2 = tag.split("\n")
+    assert line1 == (
+        "<!-- faf: widget-api | TypeScript | api | REST API for widget inventory -->"
+    )
+    assert line2 == "<!-- faf: claim=project.faf | family=FAF -->"
+
+
+# --- AGENTS.md -----------------------------------------------------------
+
+def test_agents_md_sections_present():
+    md = generate_agents_md(SAMPLE)
+    for section in (
+        "# AGENTS.md — widget-api",
+        "## Setup & build",
+        "## Run the tests",
+        "## Where things live",
+        "## Conventions",
+        "## Guardrails",
+        "## Definition of Done",
+        "## When stuck",
+        "## Security & secrets",
+        "## Commit & PR",
+        "## Stack",
+    ):
+        assert section in md, f"missing {section!r}"
+
+
+def test_agents_md_omits_human_context():
+    md = generate_agents_md({**SAMPLE, "human_context": {"who": "devs", "why": "money"}})
+    assert "## Human Context" not in md
+    assert "## Context" not in md
+    assert "money" not in md
+
+
+def test_agents_md_setup_ordered_install_build_dev():
+    md = generate_agents_md(SAMPLE)
+    block = md.split("## Setup & build")[1].split("```")[1]
+    # first line is the ```bash language tag
+    lines = [ln for ln in block.strip().splitlines()][1:]
+    assert lines[0].startswith("npm ci")
+    assert lines[1].startswith("npm run build")
+    assert lines[2].startswith("npm run dev")
+
+
+def test_agents_md_guardrails_always_render_even_with_no_data():
+    md = generate_agents_md({"faf_version": "3.0", "project": {"name": "bare"}})
+    assert "## Guardrails" in md
+    assert "## Definition of Done" in md
+    assert "## Commit & PR" in md
+    assert "**Never:** force-push" in md
+
+
+def test_agents_md_key_files_table_when_roles_present():
+    md = generate_agents_md(SAMPLE)
+    assert "| Path | Role |" in md
+    assert "| `src/server.ts` | the entry point |" in md
+
+
+def test_agents_md_security_never_leaks_values():
+    md = generate_agents_md(SAMPLE)
+    assert "Secrets live in `.env`" in md
+    assert "see `.env.example`" in md
+
+
+def test_agents_md_stack_drops_non_stack_marketing_keys():
+    md = generate_agents_md(SAMPLE)
+    assert "developers" not in md.split("## Stack")[1]  # target_user filtered
+
+
+def test_agents_md_deterministic():
+    assert generate_agents_md(SAMPLE) == generate_agents_md(dict(SAMPLE))
+
+
+def test_agents_md_human_prefs_excluded_from_conventions():
+    md = generate_agents_md(SAMPLE)
+    conv = md.split("## Conventions")[1].split("##")[0]
+    assert "communication" not in conv.lower()
+    assert "Testing" in conv
+
+
+# --- GEMINI.md ----------------------------------------------------------
+
+def test_gemini_md_structure():
+    md = generate_gemini_md(SAMPLE)
+    assert md.startswith("<!-- faf:")
+    assert "# GEMINI.md — widget-api" in md
+    assert "Project: widget-api" in md
+    assert "## Setup & build" in md
+    assert "## Test & verify" in md
+    assert "## Before changing things" in md
+
+
+def test_gemini_md_no_guardrail_ladder():
+    # GEMINI.md is lighter — no Definition of Done / When stuck
+    md = generate_gemini_md(SAMPLE)
+    assert "## Definition of Done" not in md
+    assert "## Guardrails" not in md
+
+
+# --- edge cases -------------------------------------------------------
+
+def test_minimal_faf_does_not_crash():
+    minimal = {"faf_version": "3.0", "project": {"name": "x"}}
+    assert "# AGENTS.md — x" in generate_agents_md(minimal)
+    assert "# GEMINI.md — x" in generate_gemini_md(minimal)
+
+
+def test_key_files_from_instant_context_fallback():
+    faf = {
+        "faf_version": "3.0",
+        "project": {"name": "y"},
+        "instant_context": {"key_files": ["a.py", "b.py"]},
+    }
+    md = generate_agents_md(faf)
+    assert "- `a.py`" in md
+
+
+def test_commands_from_instant_context_are_not_used_at_toplevel():
+    # top-level `commands` is the source; instant_context.commands is separate
+    faf = {"faf_version": "3.0", "project": {"name": "z"}, "commands": {"test": "go test ./..."}}
+    md = generate_agents_md(faf)
+    assert "go test ./..." in md