govkit 0.5.0__tar.gz

govkit-0.5.0/.claude/settings.local.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:openai.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:developers.openai.com)",
+      "WebFetch(domain:platform.openai.com)",
+      "WebFetch(domain:docs.qodo.ai)",
+      "WebFetch(domain:www.qodo.ai)",
+      "WebFetch(domain:qodo-merge-docs.qodo.ai)",
+      "WebFetch(domain:marketplace.visualstudio.com)",
+      "Bash(for agent:*)",
+      "Bash(do)",
+      "Bash(sed -i 's|\"\"features/\"\"|\"\"features/starter_backend/\"\", \"\"features/schema_contract_example/\"\"|g' agents/$agent/manifest.json)",
+      "Bash(sed -i 's|\"\"ci/\"\"|\"\"ci/quality-gate-example.yml\"\", \"\"ci/eval-gate-example.yml\"\"|g' agents/$agent/manifest.json)",
+      "Bash(done)",
+      "Bash(echo \"=== $agent ===\")",
+      "Read(//c/Users/marty/source/repos/governed-ai-delivery/agents/$agent/**)",
+      "Bash(grep -r docs/architecture /c/Users/marty/source/repos/governed-ai-delivery --include=*.md --include=*.json --include=*.yaml --include=*.yml)",
+      "Bash(grep -r governance/schemas /c/Users/marty/source/repos/governed-ai-delivery --include=*.md)",
+      "Bash(grep -rn docs/architecture/ /c/Users/marty/source/repos/governed-ai-delivery --include=*.md)"
+    ]
+  }
+}

govkit-0.5.0/.github/CODEOWNDERS

@@ -0,0 +1,7 @@
+* @marty916
+
+/docs/ @marty916
+/agents/ @marty916
+/governance/ @marty916
+/ci/ @marty916
+/tests/ @marty916

govkit-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,89 @@
+name: Bug report
+description: Report a defect or unexpected behavior in GovKit
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug. Please provide enough detail for us to reproduce and triage the issue.
+
+  - type: input
+    id: summary
+    attributes:
+      label: Summary
+      description: Briefly describe the issue
+      placeholder: govkit validate fails when eval_criteria.yaml uses mode none
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: List the exact steps needed to reproduce the problem
+      placeholder: |
+        1. Run ...
+        2. Apply ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - CLI
+        - Agents
+        - Docs
+        - Governance Schemas
+        - CI Templates
+        - Worked Examples
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: GovKit version, tag, or commit SHA
+      placeholder: v0.1.0 or commit SHA
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, shell, and any other relevant environment details
+      placeholder: Windows 11, Python 3.11, PowerShell
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output or logs
+      description: Paste error output, tracebacks, or validation messages
+      render: shell
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other context, screenshots, or related links

govkit-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability report
+    url: https://github.com/Accelerated-Innovation/governed-ai-delivery/security/advisories/new
+    about: Report security issues privately. Do not open a public issue.

govkit-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,73 @@
+name: Feature request
+description: Suggest an improvement or new capability for GovKit
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting an improvement. Please describe the problem, the proposed change, and why it matters.
+
+  - type: input
+    id: summary
+    attributes:
+      label: Summary
+      description: Briefly describe the requested feature or improvement
+      placeholder: Add stack reference docs for Node.js projects
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or opportunity
+      description: What problem does this solve, or what opportunity does it address?
+      placeholder: Contributors need a clear way to apply GovKit outside Python-specific projects.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the change you would like to see
+      placeholder: Add stack-specific reference docs and update generic agent guidance to point to them.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe any alternatives you considered
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - CLI
+        - Agents
+        - Docs
+        - Governance Schemas
+        - CI Templates
+        - Worked Examples
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Expected impact
+      description: Who benefits and how?
+      placeholder: Makes GovKit easier to use across multiple stacks and reduces stack-specific assumptions in the core kit.
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any related links, examples, mockups, or notes

govkit-0.5.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

govkit-0.5.0/.github/pull_request_template.md

@@ -0,0 +1,46 @@
+## Summary
+
+Describe what changed and why.
+
+## Type of Change
+
+- [ ] Feature
+- [ ] Fix
+- [ ] Documentation
+- [ ] Refactor
+- [ ] Test
+- [ ] CI / Build
+- [ ] Chore
+
+## Related Issues
+
+Link any related issues here.
+
+## What Changed
+
+List the main changes in this pull request.
+
+- 
+- 
+- 
+
+## Validation
+
+Describe what you ran to validate the change.
+
+- [ ] Relevant tests passed
+- [ ] `govkit validate` was run where applicable
+- [ ] Worked examples were checked where applicable
+- [ ] Docs were updated where behavior or structure changed
+- [ ] Templates, schemas, and examples were updated together where required
+
+## Breaking Changes
+
+- [ ] No breaking changes
+- [ ] This PR includes breaking changes
+
+If there are breaking changes, describe them here.
+
+## Additional Notes
+
+Add any context reviewers should know.

govkit-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check
+        run: twine check dist/*
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

govkit-0.5.0/.gitignore

@@ -0,0 +1,102 @@
+# ----------------------------
+# OS
+# ----------------------------
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ----------------------------
+# Python
+# ----------------------------
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+.env
+.venv/
+venv/
+env/
+pip-wheel-metadata/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ----------------------------
+# Node / Frontend
+# ----------------------------
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-lock.yaml
+dist/
+build/
+.next/
+out/
+
+# ----------------------------
+# IDE
+# ----------------------------
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/launch.json
+.idea/
+
+.qodo
+
+# ----------------------------
+# Logs
+# ----------------------------
+*.log
+logs/
+
+# ----------------------------
+# CI / Artifacts
+# ----------------------------
+*.zip
+*.tar.gz
+*.tgz
+artifacts/
+reports/
+
+# ----------------------------
+# Security / Secrets
+# ----------------------------
+.env.*
+secrets/
+*.pem
+*.key
+*.crt
+*.p12
+
+# ----------------------------
+# Evaluation / Data
+# ----------------------------
+data/
+datasets/
+*.sqlite3
+*.db
+*.csv
+*.parquet
+
+# ----------------------------
+# Docker
+# ----------------------------
+docker-compose.override.yml
+
+# ----------------------------
+# Mac / Windows noise
+# ----------------------------
+*.swp
+*.swo
+*.stackdump

govkit-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.5
+    hooks:
+      - id: ruff
+      - id: ruff-format

govkit-0.5.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.4.0] — 2026-04-09
+
+### Added
+- **Level 5: GenAI Operations** — governed tooling for LLM-powered features
+- **Architecture contracts** — LLM_GATEWAY_CONTRACT.md (LiteLLM), OBSERVABILITY_LLM_CONTRACT.md (OpenLLMetry + Langfuse), GUARDRAILS_CONTRACT.md (NeMo + Guardrails AI), EVALUATION_LLM_CONTRACT.md (DeepEval + Promptfoo + RAGAS)
+- **Practical guides** — 8 usage guides in `docs/backend/guides/` (one per tool)
+- **Guardrails config schema** — `governance/backend/schemas/guardrails_config.schema.json`
+- **L5 feature starters** — `starter_backend_l5/`, `starter_cli_l5/` with LLM NFRs, deepeval criteria, L5 preflight sections
+- **L5 plan and preflight templates** — extended with LLM gateway, guardrails, and evaluation sections
+- **L5 agent rules** — `llm-gateway.md`, `guardrails.md`, `llm-evaluation.md`, `llm-observability.md` (Claude Code + Copilot)
+- **L5 agent skills** — `/genai-preflight` (validates L5 architecture decisions), `/eval-suite-planning` (plans DeepEval/Promptfoo/RAGAS suites)
+- **L5 CI templates** — `deepeval-gate.yml`, `promptfoo-gate.yml`, `guardrails-check.yml` (GitHub Actions + Azure DevOps)
+- **L5 CLAUDE.md variants** — `l5-backend-api.md`, `l5-backend-cli.md`
+- **L5 Copilot instruction variants** — `l5-backend-api.md`, `l5-backend-cli.md`
+- **L5 validation checks** — `check_llm_nfrs()`, `check_l5_eval_criteria()`, `check_l5_preflight_sections()` (9 total checks at L5)
+
+### Changed
+- **eval_criteria.schema.json** — added 11 new eval_class values (deepeval_*, promptfoo_*, ragas_*) and optional `tool` field
+- **evaluation_prediction.schema.json** — added optional `llm_evaluation` object for L5 predictions
+- **agent-manifest.schema.json** — added `level_5` to variant_config properties
+- **TECH_STACK.md** — added sections for LLM Gateway, LLM Evaluation, LLM Observability, Runtime Guardrails
+- **AGENT_ARCHITECTURE.md** — updated tool integration, observability, evaluation, added guardrails section
+- **EVAL_STACK.md** — replaced LangSmith/Arize with Langfuse, added DeepEval/Promptfoo/RAGAS
+- **check_gherkin_nfr_coverage()** — now skips non-standard NFR categories (e.g., LLM-specific)
+- **CLI** — `--level` accepts "5", `cmd_init` selects L5 starters, marker version bumped to 0.4.0
+
+---
+
+## [0.3.0] — 2026-04-08
+
+### Added
+- **Maturity model** — govkit now supports Level 3 (Spec-Driven Development) and Level 4 (Governed AI Delivery)
+- **`--level` flag** — `govkit apply`, `govkit init`, and `govkit validate` accept `--level 3` or `--level 4`
+- **`.govkit` marker file** — written after `govkit apply`, tracks level and options for auto-detection by `init` and `validate`
+- **Level 3 feature starters** — `starter_backend_l3/`, `starter_cli_l3/`, `starter_ui_l3/` with 3 artifacts (no eval_criteria.yaml, no architecture_preflight.md)
+- **Level 3 plan templates** — simplified plan.md without evaluation_prediction blocks
+- **Level 3 generic agent rules** — `test-first.md` and `spec-compliance.md` (no path-scoped rules)
+- **Level 3 CLAUDE.md variants** — `l3-backend-api.md`, `l3-backend-cli.md`, `l3-ui-react.md`, `l3-ui-angular.md`
+- **Level 3 agent skills** — simplified `/spec-planning` and `/implementation-plan` without evaluation scoring
+- **Level 3 Copilot equivalents** — L3 copilot-instructions and prompts for all project types
+- **Level 3 CI templates** — `l3-quality-gate.yml` for GitHub Actions and Azure DevOps (no eval gates, no boundary checks)
+- **Level-aware validation** — `govkit validate` checks 3 artifacts for L3, 5 for L4; skips eval checks at L3
+- **Manifest `level_3` sub-key** — variant overrides co-located with parent variants; schema updated
+
+### Changed
+- **Manifest schema** — `variant_config` now accepts optional `level_3` override with same shape
+- **`resolve_variant_files()`** — respects level selection, uses `level_3` override when level is "3"
+- **`run_validation()`** — accepts `level` parameter; auto-detects from `.govkit` marker
+- **`check_completeness()`** — parameterized to accept custom artifact list
+- **Starter skip list** — includes L3 starters (`starter_backend_l3`, etc.)
+
+---
+
+## [0.2.0] — 2026-04-02
+
+### Added
+- **FIRST Scoring Rubric** — concrete 1–5 scoring definitions for each FIRST principle (backend and UI)
+- **7 Virtues Scoring Rubric** — concrete 1–5 scoring definitions for each code virtue (backend and UI)
+- **Observability Port Contract** — port interface, adapter example, and testing guidance
+- **Error Mapping Contract** — domain exception hierarchy and HTTP status mapping
+- **Cross-Cutting Concerns** — DTOs, validation boundaries, pagination, timestamps, soft deletes, audit trails, configuration
+- **LangGraph vs LangChain decision matrix** in TECH_STACK.md
+- **Evaluation prediction schema** — JSON Schema for plan.md prediction blocks
+- **Import-linter reference config** — ready-to-merge config for hexagonal architecture enforcement
+- **CI governance artifact checks** — jobs to verify architecture preflight exists and commit message format
+- **CI README** — documents what's enforced vs predicted vs stubbed vs agent-only
+- **README expansion** — prerequisites, concepts, interactive prompt example, post-install verification, troubleshooting, FAQ, glossary, governance structure explanation
+- **CONTRIBUTING.md** and **CHANGELOG.md**
+
+### Changed
+- **Evaluation prediction format standardized** — UI now uses same `first`/`virtues`/`accessibility` structure as backend
+- **UI eval-gate** now checks Virtue scores in addition to FIRST scores (GitHub Actions + Azure DevOps)
+- **Copilot prompts enhanced** — added template locations, output paths, scoring rubric references, increment sizing
+- **Starter templates** — added mode selection instructions to backend and CLI starters
+- **Skill invocation syntax** — corrected `/project:` prefix to `/` in README and all CLAUDE.md variants
+
+### Fixed
+- **CLI error handling** — source path validation, UTF-8 encoding, JSON parse error handling, manifest structure validation
+- **`cmd_list`** — now skips non-directory entries and handles malformed manifests gracefully
+
+---
+
+## [0.1.0] — 2026-04-01
+
+### Added
+- Initial release
+- Two agents: `claude-code` and `copilot` with variant-based manifests
+- Variant options: `--type` (api/cli), `--ui` (none/react/angular), `--ci` (github/azure)
+- CLI: `govkit apply`, `govkit list`, `govkit validate`
+- Backend architecture docs: ARCH_CONTRACT, BOUNDARIES, API_CONVENTIONS, CLI_CONVENTIONS, SECURITY_AUTH_PATTERNS, TECH_STACK, TESTING, DESIGN_PRINCIPLES, GHERKIN_CONVENTIONS
+- UI architecture docs: MVVM_CONTRACT, COMPONENT_CONVENTIONS, STATE_MANAGEMENT (React + Angular)
+- Evaluation standards: eval_criteria.md (backend + UI), EVAL_STACK.md
+- Feature starters: starter_backend, starter_cli, starter_ui
+- Worked examples: schema_contract_example, ui_task_dashboard
+- CI templates: quality-gate, eval-gate, ui-quality-gate, ui-eval-gate (GitHub Actions + Azure DevOps)
+- Governance schemas: eval_criteria.schema.json (backend + UI)

govkit-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,90 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to making participation in the Governed AI Delivery community a respectful, professional, and harassment-free experience for everyone.
+
+We want this project to be a place where contributors, maintainers, and users can collaborate productively across different backgrounds, experience levels, and perspectives.
+
+## Expected Behavior
+
+Examples of behavior that contribute to a positive environment include:
+
+- Being respectful in comments, reviews, discussions, and other community interactions
+- Giving and receiving constructive feedback
+- Focusing on what is best for the project and community
+- Showing empathy toward other community members
+- Being professional in disagreement
+- Respecting different viewpoints and experiences
+
+## Unacceptable Behavior
+
+Examples of unacceptable behavior include:
+
+- Harassment, intimidation, or discrimination of any kind
+- Trolling, insulting, or derogatory comments
+- Personal or political attacks
+- Public or private harassment
+- Publishing someone else's private information without explicit permission
+- Sexualized language or imagery
+- Threatening language
+- Sustained disruptive behavior in issues, pull requests, discussions, or other project spaces
+- Any conduct that would be inappropriate in a professional setting
+
+## Scope
+
+This Code of Conduct applies within all project spaces, including:
+
+- GitHub issues
+- pull requests
+- discussions
+- code reviews
+- project documentation
+- any other official community channels related to this project
+
+It also applies when an individual is officially representing the project in public spaces.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please report it privately.
+
+Please do not open public GitHub issues for Code of Conduct reports.
+
+Report concerns to: marty@acceleratedinnovation.com
+
+If a report relates to a security issue, follow the process described in `SECURITY.md`.
+
+When making a report, please include:
+
+- a description of the incident
+- where it occurred
+- when it occurred
+- any relevant screenshots, links, or supporting details
+
+All reports will be reviewed and handled as promptly and confidentially as possible.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this Code of Conduct.
+
+Maintainers have the right to remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct.
+
+Maintainers may take any action they deem appropriate in response to unacceptable behavior, including:
+
+- warning the contributor
+- removing content
+- temporarily restricting participation
+- permanently banning an individual from project spaces
+
+## Enforcement Guidelines
+
+In deciding on an appropriate response, maintainers will consider:
+
+- the severity of the behavior
+- whether the behavior was repeated
+- the impact on the affected person or community
+- whether the contributor responds in good faith
+
+## Attribution
+
+This Code of Conduct is informed by the Contributor Covenant, a widely used open source code of conduct framework.