faf-python-sdk 1.3.1__tar.gz → 2.0.0__tar.gz

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/.github/workflows/pypi.yml

@@ -10,5 +10,13 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      # Gate: the full suite, with the live faf-kernel oracle required, passes
+      # before anything is built or published.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install --prefix scripts
+      - run: pip install -e ".[dev]"
+      - run: FAF_REQUIRE_KERNEL=1 python -m pytest tests/ -q
       - run: pip install build && python -m build
       - uses: pypa/gh-action-pypi-publish@release/v1

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/.github/workflows/testpypi.yml

@@ -1,13 +1,13 @@
 name: Publish to TestPyPI
 
-# Fires on every version tag push (e.g. `git push origin v0.1.5`).
-# Stage 1 of the publish flow: stage to TestPyPI for verification BEFORE
-# creating a GitHub Release (which then fires pypi.yml for production).
+# Fires on every version tag push. Stage with a pre-release tag (e.g.
+# `v2.1.0rc1` on a version-only commit), so the real version is never burned on
+# TestPyPI before review.
 #
-# Flow:
-#   1. git tag v0.1.5 && git push origin v0.1.5     → this workflow runs
-#   2. verify install from TestPyPI                  → manual / via verify_install.py
-#   3. gh release create v0.1.5                     → triggers pypi.yml (production)
+# Flow (/pubpypi):
+#   1. tag vX.Y.ZrcN + push                          → this workflow (TestPyPI)
+#   2. verify install from TestPyPI, independent review
+#   3. on GO: tag vX.Y.Z on main, then run pypi.yml (workflow_dispatch) from that tag
 
 on:
   push:

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/.gitignore

@@ -42,3 +42,6 @@ htmlcov/
 # OS
 .DS_Store
 Thumbs.db
+
+# Node (kernel oracle for the parity harness)
+node_modules/

faf_python_sdk-2.0.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+All notable changes to faf-python-sdk are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [2.0.0] - 2026-09-28 — The Always33 Edition
+
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
+
+`score_faf(yaml)` returns what faf-kernel (Wolfe-Jam/faf-rust `crates/faf-kernel`,
+npm `faf-scoring-kernel@3.0.0`) returns, on every file. A parity harness
+(`tests/test_always33_parity.py`) checks score, tier, populated, empty, ignored,
+active, total and every slot state against the kernel's recorded answers: 845/845
+fixtures (58 real `project.faf` files from public Wolfe-Jam repos, 55 rule
+fixtures, 272 YAML-layer cases, 460 seeded fuzz documents).
+
+### Changed (breaking — scores move)
+- **Always 33 slots.** The 12 enterprise slots count unless the file marks them
+  `slotignored`; `slotignored` slots drop out of the denominator
+  (`active = 33 − ignored`). A file with the 21 base slots filled and no markers
+  scores 64% (21/33); the same file plus the 12 markers scores 100% (21/21).
+- `score_faf(yaml, tier=...)` still accepts `tier`, but it no longer changes the
+  slot count: `LicenseTier.BASE` and `LicenseTier.ENTERPRISE` give the same result.
+- `Mk4Result.slots` (and `to_dict()["slots"]`) always lists 33 slots, in kernel
+  order, under the kernel's canonical names: `stack.framework`, `stack.css`,
+  `stack.state`, `stack.api`, `stack.db`, `stack.pkg_manager` (were
+  `stack.frontend`, `stack.css_framework`, `stack.state_management`,
+  `stack.api_type`, `stack.database`, `stack.package_manager`). `Mk4Result` keeps
+  its fields.
+- `tbd` and `todo` (case-insensitive) are placeholders and score as empty, with
+  the existing list (`none`, `null`, `n/a`, `unknown`, `not applicable`, …).
+- Short keys are read: `stack.framework`, `css`, `state`, `api`, `db`,
+  `pkg_manager`. The legacy key is read only when the short key is empty.
+- Rounding is half away from zero, as the kernel does (1/8 = 12.5% → 13, where
+  Python's `round()` gave 12).
+- YAML is read the way the kernel reads it (serde_yaml_ng on libyaml), not with
+  `yaml.safe_load`: flow-style YAML, a leading BOM and tabs inside values parse
+  as they do in the kernel; `<<` is an ordinary key (no YAML 1.1 merge); a
+  redefined anchor name resolves the way the kernel resolves it (an alias
+  follows the kernel's anchor ids, so it can land on a later anchor); duplicate
+  keys, a second document, an empty `?` key inside `[...]` (`[?, a]`, `[?]`),
+  alias expansion past the kernel's repetition limit and nesting deeper than
+  128 are unreadable, and nesting past that limit (`[`/`{` or block) is rejected
+  in linear time; a local tag (`!x value`) scores the slot empty.
+- Unreadable YAML scores 0 with every slot empty. `score_faf` does not raise for
+  any `str` or `bytes` input.
+
+### Added
+- `faf_sdk.mk4.SLOTS` (the 33 slot paths, kernel order), `TOTAL_SLOTS`,
+  `LEGACY_ALIASES`.
+- Parity harness and fixtures under `tests/fixtures/`; the kernel oracle
+  (`scripts/kernel_oracle.js`, pinned in `scripts/package.json`) and
+  `scripts/record_kernel_expected.py`, which records the kernel's answers.
+
+### Upgrading
+- Files without the 12 enterprise markers score lower. `faf auto` (faf-cli)
+  writes the 12 markers; with them, a complete 21-slot file scores 100%.
+- Code that reads `result.slots` by name: use the canonical short names above.
+- YAML the kernel can't read now scores 0: a duplicate key (1.4.0 kept the last
+  value), a second document (`---`), an empty `?` key inside `[...]`, nesting
+  deeper than 128. `tbd` and `todo` now count as empty.
+- Rounding is half away from zero (12.5% → 13), as the kernel rounds.
+
+### Notes
+- `generate_agents_md` / `generate_gemini_md` remain deprecated aliases in 2.0.0.
+- `validate()`'s completeness score is unchanged; it is not the Mk4 score.
+
+## [1.4.0] - 2026-09-08 — The Interop Edition
+
+The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).
+
+1.3.1 kept `generate_*` as "internal identifiers" — but a name that surfaces
+reflexively when reasoning about the tool lands in `tools/list` descriptions,
+host UIs, and docs. "Internal-only" holds only until someone documents it, so
+the public name has to be right now.
+
+### Added
+- `author_agents_md(faf)` / `author_gemini_md(faf)` — the public API names, in
+  the "faf authors" voice used on every documented surface. This is what
+  `faf_sdk.interop.__all__` advertises.
+- `render_agents_md(faf)` / `render_gemini_md(faf)` — the impl names: pure
+  `dict -> str` projection, pairs with the `write_*` helpers, greps clean. Same
+  split the canonical faf-cli TS uses.
+
+### Deprecated
+- `generate_agents_md` / `generate_gemini_md` — still work, now emit
+  `DeprecationWarning`, removed in 2.0. Point at `author_*`.
+
+### Notes
+- Additive + back-compatible: existing `from faf_sdk import generate_agents_md`
+  keeps working. No output change — the authored Markdown is byte-identical.
+
+## [1.3.1] - 2026-09-07 — The Interop Edition
+
+Docs / copy patch — no API change.
+
+### Fixed
+- "generate" removed from external copy: the `interop.py` module docstring, the
+  `## Setup & build` blockquote written into every AGENTS.md ("regenerated each
+  time" → "do not edit the managed block"), README, and CHANGELOG. FAF authors
+  and delivers facts. The `generate_agents_md` / `generate_gemini_md` function
+  names are unchanged (internal identifiers, TS↔Python parity).
+
+## [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 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.
+
+### Added
+- `detect_dart_project(dir)` → `DartProject` — the SDK's first detection capability. Reads `pubspec.yaml` and classifies: Flutter app vs reusable package, Dart MCP server, Dart backend (Serverpod / Dart Frog / Shelf / …), Dart CLI, or library. Exported from `faf_sdk`.
+- `faf_sdk/dart_detection.json` — the detection KNOWLEDGE spec, vendored byte-identical from faf-cli (the single source); ships in the wheel, loaded at runtime.
+- `tests/test_dart_parity.py` — 20 shared fixtures run identically by faf-cli and this SDK; parity proven by test, not by eye.
+- `scripts/sync-dart-spec.sh` — vendor + `--check` (byte-identity) the spec & fixtures from faf-cli.
+
+### Notes
+- Mirrors faf-cli `src/detect/dart.ts` exactly (A+B hybrid). To bolster Dart support, edit the spec in faf-cli (the Truth) and re-sync. No new runtime dependencies.
+
+## [1.1.2] - 2026-04-26
+
+### Changed
+- Package description aligned with the canonical "Persistent project context for Python" framing on PyPI catalog and GitHub repo metadata.
+- README lede sharpened — leads with the value proposition and the audience (MCP server / CI validator / tool authors), no longer feature-list framing.
+
+### Added
+- `CHANGELOG.md` (this file) — versioned release history, separate from the README's "What's New" section.
+- Brand mantra `FAF defines. MD instructs. AI codes.` anchored in the README and `__init__.py` module docstring.
+
+### Notes
+No runtime code changes. Patch release to surface description alignment in the PyPI catalog and tighten positioning copy. The catalog only updates on a new publish.
+
+## [1.1.1] - 2026-04-18
+
+### Fixed
+- Tier alignment to match faf-cli v6 — clean geometric symbols, no emoji. v1.1.0 mistakenly returned emoji tiers; this patch normalizes them to plain uppercase strings (`TROPHY`, `GOLD`, `SILVER`, `BRONZE`, `GREEN`, `YELLOW`, `RED`).
+
+## [1.1.0] - 2026-03-29
+
+### Added
+- **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores.
+- `score_faf()` — Mk4 scoring with 21-slot Base or 33-slot Enterprise tiers.
+- 100% parity with `faf-wasm-sdk` (Rust) and `faf-cli` (TypeScript).
+- 88 new WJTTC championship-grade tests (concurrency, adversarial input, security).
+- Total test count: 175 (was 87).
+
+### Fixed
+- 3 crash bugs in malformed YAML and null project field handling.
+
+## [1.0.2] - earlier
+
+### Added
+- Initial public release with `parse`, `parse_file`, `stringify`, `validate`, `find_faf_file`, `find_project_root`, and the typed `FafData` model.

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- 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: faf-python-sdk | Python | library | 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
@@ -29,5 +29,5 @@ Python SDK for parsing, validating, scoring, and authoring .faf project context
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-09-07T02:08:39.970Z*
+*STATUS: SYNC ACTIVE — 2026-09-28T17:59:27.771Z*
 <!-- faf:end -->

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/CONTRIBUTING.md

@@ -26,7 +26,8 @@ That's it. You're ready to run tests and ship a fix.
 Run the full check pass:
 
 ```bash
-pytest tests/ -v          # all tests must pass
+npm install --prefix scripts                   # the faf-kernel oracle (once)
+FAF_REQUIRE_KERNEL=1 pytest tests/ -v          # all tests must pass, incl. the live-kernel check
 mypy faf_sdk/             # strict typing — no untyped defs
 ```
 

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.3.1
+Version: 2.0.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,29 +41,42 @@ 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-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-1070%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.1 — The Interop Edition
+## What's New in v2.0.0 — The Always33 Edition
 
-The SDK can now author AI-context files, not just parse and score them.
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
 
-> **v1.3.1** is a copy patch — "generate" removed from external text (module docstring, the blockquote written into every AGENTS.md, README, CHANGELOG). No API change; the `faf_sdk.interop` functions below are unchanged.
+- **Always 33 slots.** The 12 enterprise slots count unless marked `slotignored`. 21 base slots filled with no markers: 64% (21/33). The same file plus the 12 markers: 100% (21/21). `faf auto` (faf-cli) writes the markers.
+- `tbd` / `todo` are placeholders; short keys (`framework`, `css`, `state`, `api`, `db`, `pkg_manager`) are read.
+- YAML is read the way the kernel reads it; unreadable YAML scores 0 without raising.
+- `score_faf(yaml, tier=...)` still accepts `tier`; it no longer changes the slot count.
+- **Upgrading:** `result.slots` lists all 33 slots under the kernel's names (`stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager`; were `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager`). Code that reads slots by name needs the new names. YAML the kernel can't read now scores 0 (a duplicate key, a second document, nesting deeper than 128), and rounding is half away from zero (12.5% → 13), as the kernel does.
+- Parity harness: 845/845 fixtures match faf-kernel (`faf-scoring-kernel@3.0.0`), including the `project.faf` of 58 public repos.
 
-`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.
+See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+## v1.4.0 — The Interop Edition
+
+The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).
+
+Output is byte-identical — a naming change, not a behaviour change. Existing `from faf_sdk import generate_agents_md` keeps working, now with a `DeprecationWarning`.
+
+`faf_sdk.interop` — `author_agents_md(faf)` and `author_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
+from faf_sdk import parse_file, author_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
+print(author_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 one. `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
+## 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.
 
@@ -74,7 +87,7 @@ d = detect_dart_project(".")
 print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
 ```
 
-## What's New in v1.1.0
+## v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
 
@@ -114,26 +127,24 @@ print(f"Slots: {result.populated}/{result.total} populated")
 
 ## Mk4 Scoring
 
-The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+The Mk4 engine scores `.faf` files against 33 slots (project metadata, human context, tech stack, and 12 enterprise slots), exactly as faf-kernel does. Each slot is **Populated**, **Empty**, or **Slotignored**. The score is populated ÷ active, where active = 33 − slotignored.
 
 ```python
-from faf_sdk import score_faf, LicenseTier
+from faf_sdk import score_faf
 
-# Base scoring (21 slots)
 result = score_faf(yaml_content)
 print(result.score)      # 0-100
-print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.tier)       # TROPHY / GOLD / SILVER / BRONZE / GREEN / YELLOW / RED / WHITE
 print(result.populated)  # slots with real data
-print(result.active)     # total minus slotignored
-print(result.slots)      # per-slot breakdown
-
-# Enterprise scoring (33 slots — adds monorepo/infra)
-result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+print(result.active)     # 33 minus slotignored
+print(result.slots)      # per-slot breakdown, 33 entries in kernel order
 ```
 
-**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+**Placeholder rejection:** Values like `"null"`, `"none"`, `"unknown"`, `"n/a"`, `"tbd"`, `"todo"`, `"Describe your project goal"` (case-insensitive) are scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A project that does not use the 12 enterprise slots marks them `slotignored` (`faf auto` writes them) and can still reach 100%.
 
-**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+**Short keys:** `stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager` are the canonical names; the legacy `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager` are read when the short key is empty.
 
 ## Parsing
 
@@ -188,7 +199,7 @@ root = find_project_root()
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| `score_faf(yaml, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `score_faf(yaml)` | `Mk4Result` | Mk4 score, always 33 slots (faf-kernel parity) |
 | `parse(content)` | `FafFile` | Parse YAML string |
 | `parse_file(path)` | `FafFile` | Parse from file path |
 | `validate(faf)` | `ValidationResult` | Structure validation + warnings |

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/README.md

@@ -9,29 +9,42 @@ 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-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-1070%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.1 — The Interop Edition
+## What's New in v2.0.0 — The Always33 Edition
 
-The SDK can now author AI-context files, not just parse and score them.
+One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.
 
-> **v1.3.1** is a copy patch — "generate" removed from external text (module docstring, the blockquote written into every AGENTS.md, README, CHANGELOG). No API change; the `faf_sdk.interop` functions below are unchanged.
+- **Always 33 slots.** The 12 enterprise slots count unless marked `slotignored`. 21 base slots filled with no markers: 64% (21/33). The same file plus the 12 markers: 100% (21/21). `faf auto` (faf-cli) writes the markers.
+- `tbd` / `todo` are placeholders; short keys (`framework`, `css`, `state`, `api`, `db`, `pkg_manager`) are read.
+- YAML is read the way the kernel reads it; unreadable YAML scores 0 without raising.
+- `score_faf(yaml, tier=...)` still accepts `tier`; it no longer changes the slot count.
+- **Upgrading:** `result.slots` lists all 33 slots under the kernel's names (`stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager`; were `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager`). Code that reads slots by name needs the new names. YAML the kernel can't read now scores 0 (a duplicate key, a second document, nesting deeper than 128), and rounding is half away from zero (12.5% → 13), as the kernel does.
+- Parity harness: 845/845 fixtures match faf-kernel (`faf-scoring-kernel@3.0.0`), including the `project.faf` of 58 public repos.
 
-`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.
+See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+## v1.4.0 — The Interop Edition
+
+The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).
+
+Output is byte-identical — a naming change, not a behaviour change. Existing `from faf_sdk import generate_agents_md` keeps working, now with a `DeprecationWarning`.
+
+`faf_sdk.interop` — `author_agents_md(faf)` and `author_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
+from faf_sdk import parse_file, author_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
+print(author_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 one. `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
+## 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.
 
@@ -42,7 +55,7 @@ d = detect_dart_project(".")
 print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
 ```
 
-## What's New in v1.1.0
+## v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
 
@@ -82,26 +95,24 @@ print(f"Slots: {result.populated}/{result.total} populated")
 
 ## Mk4 Scoring
 
-The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+The Mk4 engine scores `.faf` files against 33 slots (project metadata, human context, tech stack, and 12 enterprise slots), exactly as faf-kernel does. Each slot is **Populated**, **Empty**, or **Slotignored**. The score is populated ÷ active, where active = 33 − slotignored.
 
 ```python
-from faf_sdk import score_faf, LicenseTier
+from faf_sdk import score_faf
 
-# Base scoring (21 slots)
 result = score_faf(yaml_content)
 print(result.score)      # 0-100
-print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.tier)       # TROPHY / GOLD / SILVER / BRONZE / GREEN / YELLOW / RED / WHITE
 print(result.populated)  # slots with real data
-print(result.active)     # total minus slotignored
-print(result.slots)      # per-slot breakdown
-
-# Enterprise scoring (33 slots — adds monorepo/infra)
-result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+print(result.active)     # 33 minus slotignored
+print(result.slots)      # per-slot breakdown, 33 entries in kernel order
 ```
 
-**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+**Placeholder rejection:** Values like `"null"`, `"none"`, `"unknown"`, `"n/a"`, `"tbd"`, `"todo"`, `"Describe your project goal"` (case-insensitive) are scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A project that does not use the 12 enterprise slots marks them `slotignored` (`faf auto` writes them) and can still reach 100%.
 
-**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+**Short keys:** `stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager` are the canonical names; the legacy `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager` are read when the short key is empty.
 
 ## Parsing
 
@@ -156,7 +167,7 @@ root = find_project_root()
 
 | Function | Returns | Description |
 |----------|---------|-------------|
-| `score_faf(yaml, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `score_faf(yaml)` | `Mk4Result` | Mk4 score, always 33 slots (faf-kernel parity) |
 | `parse(content)` | `FafFile` | Parse YAML string |
 | `parse_file(path)` | `FafFile` | Parse from file path |
 | `validate(faf)` | `ValidationResult` | Structure validation + warnings |

{faf_python_sdk-1.3.1 → faf_python_sdk-2.0.0}/faf_sdk/__init__.py

@@ -25,7 +25,15 @@ 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 .interop import (
+    author_agents_md,
+    author_gemini_md,
+    render_agents_md,
+    render_gemini_md,
+    generate_agents_md,  # deprecated alias — kept in 2.0, removal planned
+    generate_gemini_md,  # deprecated alias — kept in 2.0, removal planned
+    faf_meta_tag,
+)
 from .types import (
     FafData,
     ProjectInfo,
@@ -36,7 +44,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.3.1"
+__version__ = "2.0.0"
 __all__ = [
     # Parser
     "parse",
@@ -58,9 +66,9 @@ __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",
+    # Interop — AGENTS.md / GEMINI.md authoring (parity with faf-cli src/interop)
+    "author_agents_md",
+    "author_gemini_md",
     "faf_meta_tag",
     # Types
     "FafData",