chore(governance): add missing governance files

.github/workflows/governance.yml

@@ -0,0 +1,79 @@
+name: Governance
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions: read-all
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  required-files:
+    name: Required governance files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+      - name: Verify required files
+        run: |
+          set -e
+          required=(
+            "SECURITY.md"
+            ".github/dependabot.yml"
+            ".github/workflows/scorecard.yml"
+            ".editorconfig"
+            "cliff.toml"
+            "SSOT.md"
+          )
+          missing=0
+          for f in "${required[@]}"; do
+            if [ ! -e "$f" ]; then
+              echo "::error file=$f::Missing required governance file: $f"
+              missing=1
+            else
+              echo "OK: $f"
+            fi
+          done
+          if [ "$missing" -eq 1 ]; then
+            echo "::error::One or more required governance files are missing."
+            exit 1
+          fi
+
+  commit-policy:
+    name: Conventional commit lint
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout (shallow)
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4
+        with:
+          fetch-depth: 50
+      - name: Conventional commit check
+        if: hashFiles('.commitlintrc.json') != ''
+        uses: wagoid/commitlint-github-action@5a18711fb4551c356c12597d399a82599b8e2a39 # v5
+        with:
+          configFile: .commitlintrc.json
+      - name: Skip notice
+        if: hashFiles('.commitlintrc.json') == ''
+        run: echo "No .commitlintrc.json present; skipping conventional commit lint."
+
+  branch-policy:
+    name: Branch policy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify default branch naming
+        run: |
+          default=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main")
+          case "$default" in
+            main|master) echo "OK: default branch '$default' is governance-approved" ;;
+            *) echo "::error::Default branch '$default' is not in the approved set (main, master)"; exit 1 ;;
+          esac
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

ARCHITECTURE.md

@@ -0,0 +1,44 @@
+# Architecture
+
+## Overview
+- phenoAI is a Rust workspace in the Phenotype ecosystem focused on AI-agent capabilities.
+- Stack: Rust (Cargo workspace), Python bindings, with shared Phenotype crates.
+- This document is a skeleton; expand with crate-level ownership and boundaries as the workspace evolves.
+
+## Components
+## crates/*
+- Rust crates implementing the AI agent domain logic, model integrations, and shared utilities.
+
+## python/
+- Python bindings and helper modules that wrap the Rust crates for ecosystem consumers.
+
+## ports/
+- External port surfaces (CLI, MCP, library) that expose the workspace to other Phenotype projects.
+
+## docs/
+- Project documentation: guides, reports, research, reference, checklists (per `AGENTS.md` layout).
+
+## Data flow
+```text
+external caller (CLI / MCP / Python)
+  -> ports/ entrypoint
+  -> crates/* domain logic
+  -> python/ bindings (optional)
+  -> external model / storage providers
+```
+
+## Key invariants
+- Treat crate boundaries as explicit contracts; respect `deny.toml` and `lefthook.yml` quality gates.
+- Mirror the Phenotype org scripting policy (Rust default; no new shell scripts).
+- Functional requirements in `FUNCTIONAL_REQUIREMENTS.md` MUST be traceable to at least one test.
+- Cross-project reuse: prefer extraction into existing shared modules (see `AGENTS.md`).
+
+## Cross-cutting concerns (config, telemetry, errors)
+- Config: load via Phenotype shared config patterns.
+- Telemetry: propagate structured logs and traces across the workspace.
+- Errors: normalize failure handling so port surfaces can report actionable messages.
+
+## Future considerations
+- Replace this skeleton with per-crate ownership and a concrete call-graph diagram.
+- Capture release and integration assumptions as the workspace evolves (see `PLAN.md`).
+- Add startup diagrams for CLI, MCP, and Python-binding paths.

SSOT.md

@@ -0,0 +1,33 @@
+# SSOT — Single Source of Truth (phenoAI)
+
+This document records the canonical authority for cross-cutting facts in the
+phenoAI repository. When a fact conflicts across docs, the source listed
+here wins.
+
+## Scope
+
+| Domain | Authoritative source |
+| --- | --- |
+| Build & test commands | `justfile` (root) and per-crate `Cargo.toml` |
+| Release & versioning | `cliff.toml` + `CHANGELOG.md` (git-cliff generated) |
+| Security disclosure process | `SECURITY.md` |
+| Dependency updates | `.github/dependabot.yml` |
+| Branch & commit policy | `.github/workflows/governance.yml` |
+| Repository health score | `.github/workflows/scorecard.yml` (OpenSSF) |
+| Editor / formatting baseline | `.editorconfig` |
+| Workspace architecture | `PLAN.md` + per-crate `Cargo.toml` |
+| Agent operating model | `AGENTS.md` |
+| Functional requirements | `FUNCTIONAL_REQUIREMENTS.md` |
+
+## Precedence order
+
+1. Executable config (workflows, `justfile`, `Cargo.toml`, `deny.toml`, `lefthook.yml`) — observed behavior.
+2. `*.md` governance files in this SSOT table.
+3. `PLAN.md` milestone-level contracts.
+4. Anything else.
+
+## Updating this file
+
+- Keep the table narrow and unambiguous.
+- Cite the canonical file by path; do not duplicate content.
+- Update via a `chore(governance):` commit referencing the change.