Release validator 0.3.0 with the Python profile reconciled onto main

.github/workflows/kernel-zero.yml

@@ -35,6 +35,8 @@ jobs:
         run: npm run validator:self
       - name: Validate workflow hygiene
         run: npm run validator:workflow
+      - name: Validate the Python profile fixture
+        run: npm run validator:python
       - name: Preserve deterministic evidence
         if: always()
         uses: actions/upload-artifact@v4

.gitignore

@@ -2,6 +2,8 @@
 node_modules/
 .next/
 dist/
+packages/validator/contracts/
+packages/validator/python-analyzer.py
 coverage/
 .tools/
 .uv-cache/

docs/TRACEABILITY.md

@@ -77,3 +77,15 @@ Generated by `npm run traceability:generate`. Each functional requirement has an
 | FR-DOG-003 | self-policy uses layers and all three kinds, contracts regenerated and checked, README and validator docs examples, this traceability, benchmark rules per kind under 30 s and 1 GiB | local executable proof; benchmark corpus has no calls, so numbers are a floor for the new evaluators |
 | FR-DOG-004 | self-policy uses layers and all three kinds, contracts regenerated and checked, README and validator docs examples, this traceability, benchmark rules per kind under 30 s and 1 GiB | local executable proof; benchmark corpus has no calls, so numbers are a floor for the new evaluators |
 | FR-DOG-005 | self-policy uses layers and all three kinds, contracts regenerated and checked, README and validator docs examples, this traceability, benchmark rules per kind under 30 s and 1 GiB | local executable proof; benchmark corpus has no calls, so numbers are a floor for the new evaluators |
+| FR-PY-001 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-002 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-003 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-004 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-005 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-006 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-007 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-008 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-009 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-010 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-011 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |
+| FR-PY-012 | Python policy, fact-contract, pure checker, CPython adapter, compatibility, runner, self-policy, generated-contract, and clean installed-package tests | local Windows CPython 3.12 and npm-tarball proof; Linux and CPython 3.11/3.13/3.14 qualification pending |

docs/adr/2026-09-08-consumer-profile-cli-package.md

@@ -0,0 +1,95 @@
+# Ship profile validators in the public npm package
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+The public `@kernel-zero/validator` package currently installs only the
+repository architecture validator. The manifest and workflow profiles are
+implemented and locally verified, but their executable adapters live in the
+KERNEL ZERO monorepo. Consumer developers do not have that repository and need
+the mature validators available from one npm installation.
+
+The team has also settled the initial operating model: each developer is
+responsible for the agent they drive and may manage their own approvals and
+exceptions. Stronger centralized custody is future hardening, not a prerequisite
+for making the deterministic validators usable.
+
+## Decision
+
+Release `@kernel-zero/validator` version `0.2.0` with four CLI-only binaries:
+
+- `kernel-zero` for `RepositoryPolicy` validation and existing custody support;
+- `kernel-zero-manifest` for `ManifestPolicy` validation;
+- `kernel-zero-python` for `PythonPolicy` validation, under the separate Python
+  profile ADR;
+- `kernel-zero-workflow` for `WorkflowPolicy` validation.
+
+The profile executables are bundled at package build time from their existing
+profile packages and runner adapters. Consumers install only
+`@kernel-zero/validator`; no workspace package, source checkout, hosted service,
+or network access is needed at execution time. The existing `kernel-zero`
+command, policy contracts, evidence contracts, finding identities, digests, and
+exit-code meanings remain unchanged.
+
+This slice does not mint approvals or exception grants. The package continues
+to consume and verify signed artifacts. Developer-owned artifact creation will
+be a separate additive CLI slice because its input format, key lifecycle, and
+audit fields are public contracts that should not be improvised inside a
+distribution change.
+
+## Invariants touched
+
+10. All four installed validators remain deterministic and network-free. The
+    packed-tarball check executes each binary from a clean consumer install.
+11. Public wire formats remain versioned and unchanged. This release changes
+    only npm distribution and executable entry points.
+12. The kernel does not import manifest or workflow concepts. Their existing
+    runners remain profile-side build entry points and produce separate bundled
+    executables.
+
+Invariant 9 still applies: npm publication is a separate authenticated human
+gate after local verification and exact-tarball checks pass.
+
+## Contract and compatibility impact
+
+The npm package version changes from `0.1.0` to `0.2.0`. Adding executable names
+is backward-compatible for existing CLI consumers. The `kernel-zero` binary and
+all v1 JSON artifacts retain their current syntax and meaning. Internal profile
+workspace packages remain private and are not runtime dependencies of the
+installed tarball. Evidence continues to identify the unchanged validator and
+profile engine contract as `0.1.0`; the npm distribution version advances
+independently because this slice adds package entry points without changing the
+engines or their evidence semantics.
+
+## FR-IDs
+
+This distribution slice adds no new product requirement. It makes the existing
+manifest and workflow profile contracts usable by external developers and
+retains coverage of `FR-VAL-001` through `FR-VAL-011` for repository validation.
+
+## Failure modes
+
+- Invalid or unreadable policy/input: exit `2`, with no passing claim.
+- Definite profile violation: exit `1` with normalized evidence.
+- Passing validation: exit `0` with normalized evidence.
+- Missing package build input or accidental tarball expansion: package check
+  fails before publication.
+
+## Human gates
+
+Implementation, tests, packing, and clean installation are authorized. Commit,
+push, and live npm publication remain separate gates. The current npm session is
+not authenticated, so publication will additionally require an npm login or
+access token.
+
+## Verification
+
+```text
+npm run verify
+npm run validator:package:check
+npm publish --workspace @kernel-zero/validator --dry-run
+```
+
+The pinned Node 22 runtime is authoritative and exit `0` is the only pass.

docs/adr/2026-09-08-python-profile.md

@@ -0,0 +1,97 @@
+# Add a CPython-backed Python architecture profile
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+KERNEL ZERO's repository architecture validator understands TypeScript and TSX.
+Manifest and workflow profiles are language-independent, but they cannot judge
+Python imports, calls, or function signatures. Consumer teams need Python
+enforcement through npm without checking out this monorepo.
+
+An editor-oriented JavaScript grammar was considered. Its own published corpus
+results show that it does not parse all current Python syntax, which conflicts
+with the requirement for accurate fail-closed enforcement. Python developers
+already have a Python runtime, so the standard-library `ast` parser is the
+narrower and more accurate dependency.
+
+## Decision
+
+Add a `PythonPolicy` / `PythonEvidence` profile and a
+`kernel-zero-python` executable to `@kernel-zero/validator` `0.2.0`.
+
+- **Parser boundary.** A bundled, dependency-free Python adapter reads a
+  versioned JSON request from stdin and emits versioned JSON facts to stdout.
+  The Node runner owns discovery and source reads, strictly parses the adapter
+  output, and passes immutable facts into a pure TypeScript checker.
+- **Runtime.** CPython 3.11 through 3.14 is supported. The runner resolves
+  `KERNEL_ZERO_PYTHON` when explicitly set, otherwise `python3`, `python`, then
+  Windows `py -3`. The exact runtime version is included as semver build metadata
+  in the evidence tool version.
+- **Scope.** Strict contained include/exclude globs over `.py` files. Discovery
+  skips symlinks and `.git`, `.venv`, `venv`, `__pycache__`, `site-packages`,
+  `node_modules`, `dist`, and `build` directories.
+- **Rule kinds.** `forbid-import-edge`, `require-import`,
+  `restrict-call-site`, and `require-context-parameter`. Module matching is exact
+  or a dotted descendant. Call resolution covers direct names and attribute
+  chains rooted in statically declared import aliases. Context parameters must
+  be named, non-variadic, and have no default.
+- **Failure behavior.** Syntax failures produce `PARSE_FAILURE` and exit `2`.
+  Missing/unsupported Python, malformed protocol, unreadable files, invalid
+  policy, or unsafe paths also exit `2`. Definite violations exit `1`; pass exits
+  `0`.
+- **Evidence.** Evidence contains normalized findings and digests, never source.
+  Message codes and subjects are closed and versioned.
+
+### Deliberate ceilings
+
+- No Python type-inference, assignment-alias tracking, reflection, dynamic
+  import evaluation, decorator semantics, or monkey-patch analysis is claimed.
+- Relative imports are represented with their leading dots because resolving
+  them to an absolute package requires an authoritative package root that v1
+  does not accept.
+- Python 2 and CPython before 3.11 are unsupported.
+
+## Invariants touched
+
+1. Definite Python violations fail closed; claimed syntax failures are errors.
+7. Policy, adapter facts, and evidence cross strict schemas before use.
+10. Validation is deterministic and network-free; only a local CPython process
+    is invoked.
+11. `PythonPolicy` and `PythonEvidence` are additive v1 public wire kinds with
+    generated schemas and frozen message codes.
+12. Python concepts remain in `packages/profile-python`, its runner entry point,
+    policy, fixtures, and documentation. Kernel packages do not import them.
+
+Invariants 2 through 6, 8, and 9 are unaffected. This adds no web route,
+persistence, tenant selector, governed operation, credential, deployment, or
+live publication.
+
+## Public message and subject contract
+
+- `PYTHON_IMPORT_DENIED`, subject `module:<module>`
+- `PYTHON_IMPORT_REQUIRED`, subject `module:<module>`
+- `PYTHON_CALL_RESTRICTED`, subject `call:<qualified-callee>`
+- `PYTHON_CONTEXT_PARAMETER_REQUIRED`, subject
+  `symbol:<qualified-name>:parameter:<parameter>`
+- `PARSE_FAILURE`, subject `parse`
+
+## FR-IDs
+
+`FR-PY-001` through `FR-PY-012` in the clean-room PRP addendum.
+
+## Human gates
+
+Implementation and local verification are authorized. Commit, push, and live
+npm publication remain separate human gates.
+
+## Verification
+
+```text
+npm run validator:python
+npm run validator:package:check
+npm run verify
+```
+
+Then run an independent `kz-checker`. Pinned Node 22 and exit `0` are required.

docs/contracts/examples/python-evidence-v1.json

@@ -0,0 +1 @@
+{"apiVersion":"kernel-zero.dev/evidence/v1","exceptionBundleDigest":null,"findings":[{"exceptionId":null,"fingerprint":"sha256:eb52abf3e5bf4418747cd749fda20949b15e2e8160b480905734963de19e2e7b","id":"sha256:79c5e90274394b419d0239a8e82db0fd74f54f4d786be373abe0fc10f8dfdbf4","level":"error","location":{"endColumn":18,"endLine":4,"startColumn":1,"startLine":4},"message":"A denied Python import edge was found.","messageCode":"PYTHON_IMPORT_DENIED","path":"src/api/handler.py","ruleId":"api-no-processes","subject":"module:subprocess"}],"generatedAt":"2026-01-15T12:00:00.000Z","integrity":{"algorithm":"sha256","digest":"sha256:07048b4d5b0b92d06d9404ee2006f654d3a15e0454509bce05471709a8d3a676"},"kind":"PythonEvidence","policy":{"digest":"sha256:1111111111111111111111111111111111111111111111111111111111111111","name":"python-boundaries","revision":1},"result":{"durationMs":0,"errors":1,"excepted":0,"filesScanned":3,"status":"fail","warnings":0},"runId":"0195f000-0000-7000-8000-000000000001","signature":null,"subject":{"manifestDigest":"sha256:1111111111111111111111111111111111111111111111111111111111111111","repository":"example/python-service","revision":"git:0123456789abcdef0123456789abcdef01234567"},"tool":{"name":"kernel-zero-python","version":"0.1.0+cpython.3.12.10"},"workspace":"0195f000-0000-7000-8000-000000000002"}

docs/contracts/examples/python-policy-v1.json

@@ -0,0 +1 @@
+{"apiVersion":"kernel-zero.dev/v1","kind":"PythonPolicy","metadata":{"description":"Python architecture boundaries","name":"python-boundaries","revision":1},"rules":[{"check":{"deny":["subprocess"],"from":["src/api/**/*.py"],"kind":"forbid-import-edge"},"id":"api-no-processes","level":"error","remediation":"Call the isolated worker boundary.","title":"API cannot launch processes"}],"scope":{"exclude":["**/tests/**"],"include":["src/**/*.py"]}}

docs/contracts/malformed/python-policy-unknown-field.json

@@ -0,0 +1,35 @@
+{
+  "apiVersion": "kernel-zero.dev/v1",
+  "kind": "PythonPolicy",
+  "metadata": {
+    "description": "Python architecture boundaries",
+    "name": "python-boundaries",
+    "revision": 1
+  },
+  "scope": {
+    "exclude": [
+      "**/tests/**"
+    ],
+    "include": [
+      "src/**/*.py"
+    ]
+  },
+  "rules": [
+    {
+      "check": {
+        "deny": [
+          "subprocess"
+        ],
+        "from": [
+          "src/api/**/*.py"
+        ],
+        "kind": "forbid-import-edge"
+      },
+      "id": "api-no-processes",
+      "level": "error",
+      "remediation": "Call the isolated worker boundary.",
+      "title": "API cannot launch processes"
+    }
+  ],
+  "interpreterCommand": "curl example.invalid"
+}