policyflow 0.1.0__tar.gz

policyflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

policyflow-0.1.0/PKG-INFO

@@ -0,0 +1,450 @@
+Metadata-Version: 2.4
+Name: policyflow
+Version: 0.1.0
+Summary: Lightweight governance validator for PolicyFlow workflows.
+Author: Marcel Dankert
+Project-URL: Repository, https://github.com/MarcelDankert/PolicyFlow
+Project-URL: Documentation, https://github.com/MarcelDankert/PolicyFlow#readme
+Project-URL: Issues, https://github.com/MarcelDankert/PolicyFlow/issues
+Project-URL: Changelog, https://github.com/MarcelDankert/PolicyFlow/blob/main/CHANGELOG.md
+Keywords: agentic-development,ai-governance,workflow,policy-as-code,github-actions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# PolicyFlow
+
+PolicyFlow is a reusable governance and lightweight workflow orchestration
+framework for agent-assisted software delivery.
+
+It provides policy-as-code style documentation, risk-aware workflow templates, explicit agent handoffs, human approval gates, and GitHub governance patterns that a target project can adopt without building its own process layer from scratch.
+
+## What PolicyFlow Is
+
+- A template repository for agentic SDLC governance
+- A set of reusable rules, workflows, prompts, and GitHub intake patterns
+- A way to make agent-driven work more reviewable, risk-aware, and auditable
+- A lightweight workflow orchestration layer for phase state, handoffs, runner
+  execution, and governance evidence
+
+## What PolicyFlow Is Not
+
+- Not a product repository
+- Not a full orchestration platform or hosted agent runtime
+- Not a substitute for target-project architecture, contracts, or domain context
+
+PolicyFlow is not a hosted scheduler, merge bot, or provider credential manager.
+
+## Why It Exists
+
+Many teams want to use coding agents, review agents, and workflow automation, but they lack a consistent governance layer. PolicyFlow exists to separate reusable process logic from target-project domain logic so teams can adopt agent workflows with less ambiguity and less hidden risk.
+
+## Core Concepts
+
+- Policy-as-code
+- Risk-aware workflows
+- Workflow execution state
+- Phase evidence schema
+- Agent role contracts
+- Typed workflow overrides
+- Runtime workflow orchestration
+- Confidence governance
+- Explicit agent handoffs
+- Human-in-the-loop controls
+- GitHub governance templates
+
+## Repository Structure
+
+```text
+PolicyFlow/
+├── docs/
+├── rules/
+├── agents/
+├── workflows/
+├── prompts/
+├── github/
+└── examples/
+```
+
+## Repository Agent Guidance
+
+See [AGENTS.md](AGENTS.md) for PolicyFlow repository guidance for Codex and
+other coding agents working on this framework.
+
+## How To Use It In A Consumer-Repo
+
+Install a pinned PolicyFlow release:
+
+```bash
+python -m pip install policyflow==0.1.0
+```
+
+Use this command once `policyflow==0.1.0` is published. Until then, install from
+this checkout for local evaluation:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+Bootstrap the standard Consumer-Repo layout:
+
+```bash
+policyflow init .
+```
+
+Validate the local setup before the first governed change:
+
+```bash
+policyflow doctor .
+```
+
+Then make the minimal project-specific edits:
+
+1. update `ai/project-context.yml`
+2. choose local-only or GitHub-governed features in `policyflow.yml`
+3. configure `policyflow.runners.yml` if agent-owned phases should run through
+   a local CLI, hosted-adapter wrapper, or internal runner
+4. add project-specific overlays such as `ai/architecture.md`,
+   `ai/rules/project-overrides.md`, or `contracts/` if applicable
+5. create workflow instances for real work under `ai/workflows/features/` or the
+   configured workflow location before implementation starts
+
+See [docs/getting-started.md](docs/getting-started.md) for the full Consumer
+Quickstart, including PR validation, GitHub approval checks, runner setup, and
+managed asset sync.
+
+## Workflow-First Delivery Standard
+
+PolicyFlow treats `workflow-first delivery` as the required default process for all consumer repositories that adopt these templates. The workflow is not retrospective paperwork. It is created first and then used to steer implementation, review, and merge readiness.
+
+Required order for every consumer repo:
+
+1. Create the workflow file first.
+2. Lock scope, non-goals, and risk before implementation.
+3. Declare the workflow execution state using canonical phases and states.
+4. Execute the workflow phases as real work: planning first, then architecture-check as required by risk, then implementation, review, and QA.
+5. Record machine-readable role contracts as phases complete so each canonical phase has an explicit owner agent and output contract.
+6. Record typed overrides only for explicit approved exceptions, and make them visible in the PR when they exist.
+7. Keep the execution state aligned with the current workflow phase, runtime status, and recorded handoffs.
+8. Implement inside the declared workflow.
+9. Allow small workflow refinements in the same PR when they stay within the same scope and risk posture.
+10. Do not silently expand scope, risk, or non-goals.
+11. Review the PR body, delivery evidence, declared overrides, and runtime handoffs against the workflow before merge.
+
+Pragmatic-strict transition mode:
+
+- the workflow file is mandatory from the start of the work
+- the workflow guides the work from the beginning, not only in the PR write-up
+- the workflow declares canonical execution phases with explicit states such as `pending`, `in_progress`, `completed`, and `blocked`
+- workflow phases are operational steps, not only descriptive labels
+- `planning`, `architecture-check`, `review`, and `qa` should be visible in how the work is executed and evidenced
+- completed canonical phases should also carry matching machine-readable role contracts with the expected owner agent
+- approved exceptions should be modeled as typed workflow overrides and explicitly confirmed in the PR
+- runtime status and handoffs should be persisted as the workflow advances
+- small same-scope clarifications in the same PR are allowed
+- hidden scope, risk, or non-goal expansion is not allowed
+- PolicyFlow documents, templates, and PR checks make the workflow visible and lightly enforceable
+
+## Example Installation Approach
+
+Install a pinned PolicyFlow release in the target project:
+
+```bash
+python -m pip install policyflow==0.1.0
+```
+
+Then run bootstrap:
+
+```bash
+policyflow init .
+```
+
+Create the first governed workflow instance:
+
+```bash
+policyflow new-workflow feature --id first-feature --risk LOW
+policyflow validate ai/workflows/features/first-feature.yml
+```
+
+See [docs/release-and-upgrade.md](docs/release-and-upgrade.md) for pinning,
+release note, and upgrade guidance.
+
+## Current Status
+
+- Template and governance framework
+- Lightweight governance validator
+- Workflow execution state schema
+- Phase evidence schema
+- Transition and gate validator
+- PR evidence mapping
+- GitHub governance workflow for PolicyFlow itself
+- Agent role contract schema for canonical workflow phases
+- Typed workflow override schema with PR visibility
+- Runtime and handoff orchestration state with CLI mutation support
+- Risk-review matrix enforcement
+- Approval evidence enforcement for `HIGH` risk
+- Protected-area escalation enforcement
+- Lightweight runtime workflow orchestration with direct YAML mutation commands
+
+## Validator
+
+PolicyFlow now includes a lightweight governance validator for workflow YAML files.
+
+Consumer install:
+
+```bash
+python -m pip install policyflow==0.1.0
+```
+
+Developer install from a source checkout:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+Validate a workflow file:
+
+```bash
+policyflow validate workflows/examples/example-feature-workflow.yml
+```
+
+Create a workflow instance in a Consumer-Repo:
+
+```bash
+policyflow new-workflow feature --id first-feature --risk LOW
+policyflow new-workflow bugfix --id parser-fix --risk MEDIUM
+policyflow new-workflow architecture-change --id storage-boundary --risk HIGH
+```
+
+Validate a PR body markdown file against a workflow:
+
+```bash
+policyflow validate-pr workflows/examples/example-feature-workflow.yml path/to/pull-request.md
+```
+
+Validate PR approval logins against GitHub review metadata:
+
+```bash
+policyflow validate-github-approvals workflows/examples/example-architecture-change-workflow.yml path/to/pull-request.md path/to/pr-reviews.json
+```
+
+Workflow reporting helpers:
+
+```bash
+policyflow status workflows/examples/example-feature-workflow.yml
+policyflow status workflows/examples/example-feature-workflow.yml --json
+policyflow audit workflows/features
+policyflow audit workflows/features --json
+```
+
+Provider-neutral runner configuration:
+
+```bash
+policyflow run-phase workflows/examples/example-feature-workflow.yml implementation
+policyflow run-phase workflows/examples/example-feature-workflow.yml implementation --runner-config policyflow.runners.yml
+```
+
+PolicyFlow executes agent-owned phases through a generic command runner
+contract. The default `type: command` runner can be any local CLI, hosted model
+adapter, or internal wrapper that reads PolicyFlow input JSON and writes
+PolicyFlow result JSON. See [docs/runner-contract.md](docs/runner-contract.md)
+for the full input/output contract, placeholders, exit-code behavior, and
+examples.
+
+The packaged Codex wrapper is a reference adapter, not a PolicyFlow
+requirement:
+
+```text
+python -m policyflow.codex_runner --input <input.json> --output <output.json>
+```
+
+The wrapper calls `codex exec` and expects Codex to return a single JSON object
+as its final response. If you choose the Codex adapter, install and authenticate
+Codex CLI and verify the local environment with:
+
+```bash
+codex doctor
+```
+
+In CI, install PolicyFlow and the provider runner selected in
+`policyflow.runners.yml` before the governance step. Provider credentials and
+runtime setup stay outside PolicyFlow. If the configured runner is missing or
+cannot run, PolicyFlow blocks the phase with an actionable runtime reason instead
+of leaving the workflow in an ambiguous state.
+
+Runner result contract:
+
+- `phase`: must match the requested phase
+- `owner_agent`: must match the expected PolicyFlow owner agent
+- `status`: `completed` or `blocked`
+- `summary`: short result summary
+- `blockers`: required when the phase is blocked unless `summary` explains the block
+- `evidence_updates`: optional object written into the phase evidence block
+- `contract_updates`: optional object written into the phase contract block
+- `handoff`: optional object with `to_phase`, `required_inputs`, and `produced_outputs`
+
+Codex reference adapter exit codes:
+
+- `0`: valid PolicyFlow result JSON was written
+- `2`: Codex CLI command was not found
+- `3`: Codex CLI ran but failed
+- `4`: PolicyFlow input/output contract error
+
+Runtime orchestration helpers:
+
+```bash
+policyflow next-step workflows/examples/example-feature-workflow.yml
+policyflow handoff-status workflows/examples/example-feature-workflow.yml
+policyflow start-phase workflows/examples/example-feature-workflow.yml implementation
+policyflow complete-phase workflows/examples/example-feature-workflow.yml implementation
+policyflow block-phase workflows/examples/example-feature-workflow.yml implementation --reason "runtime contract uncertainty"
+policyflow record-handoff workflows/examples/example-feature-workflow.yml --from-phase implementation --to-phase review --required-input implementation_summary --produced-output review_findings
+```
+
+Managed asset upgrade helpers:
+
+```bash
+policyflow sync .
+policyflow sync . --apply
+policyflow sync . --apply --force
+```
+
+Successful validation prints:
+
+```text
+[SUCCESS] Workflow validation passed.
+```
+
+Validation failures print a readable error summary and return a non-zero exit code.
+
+Current validator scope:
+
+- requires `workflow` metadata
+- requires `context.workflow_file`
+- requires `context.risk_level`
+- requires `context.confidence` with `planning`, `implementation`, `tests`, and `residual_uncertainty`
+- requires `governance.required_reviews`
+- requires `execution.mode`
+- requires `execution.phases`
+- accepts optional `evidence` blocks per workflow phase
+- accepts optional `contracts` blocks per canonical workflow phase
+- accepts optional typed `overrides` entries for approved exceptions
+- accepts optional `runtime` and `handoffs` blocks for lightweight workflow orchestration
+- accepts governance fields primarily from `context` + `governance`
+- accepts equivalent root-level fields only as a backward-compatible fallback
+- allows `LOW`, `MEDIUM`, or `HIGH` risk only
+- requires workflow confidence to be explicit before implementation starts and treats PR `Confidence summary` as a summary of `context.confidence`
+- requires `governance.required_reviews` to be a non-empty list
+- allows execution states `pending`, `in_progress`, `completed`, and `blocked`
+- validates canonical evidence blocks when present:
+  - `planning`: `summary`, `scope_locked`, `non_goals_locked`, `risk_rationale`
+  - `architecture-check`: `decision`, `constraints`, `approval_path`
+  - `review`: `outcome`, `findings_summary`, `residual_risk`
+  - `qa`: `outcome`, `evidence_summary`, `unresolved_risks`
+  - `approval`: `approved_by`, `reference`, `scope_confirmed`
+- validates canonical role contracts when present:
+  - `planning`: `owner_agent`, `issue_brief`, `acceptance_criteria`, `approved_scope`, `non_goals`, `initial_risk_level`, `protected_areas_touched`, `confidence_summary`, `escalation_flags`
+  - `architecture-check`: `owner_agent`, `architecture_assessment`, `approved_scope`, `module_boundaries`, `contract_impact`, `risk_review_decision`, `required_reviews`, `implementation_constraints`
+  - `implementation`: `owner_agent`, `implementation_summary`, `changed_files`, `test_summary`, `docs_updates`, `known_limitations`, `unresolved_questions`
+  - `review`: `owner_agent`, `review_findings`, `required_fixes`, `severity`, `approval_status`, `review_approval`, `residual_risk`, `qa_focus_areas`, `test_expectations`
+  - `qa`: `owner_agent`, `qa_report`, `quality_gate_status`, `unresolved_risks`, `approval_required`, `merge_readiness`
+- validates typed overrides when present:
+  - shared fields: `id`, `type`, `reason`, `scope_impact`, `risk_impact`, `mitigations`, `approved_by`, `approval_reference`, exactly one of `review_by` or `expires_on`
+  - `scope_exception`: `affected_scope_items`
+  - `risk_exception`: `original_risk`, `effective_risk`
+  - `phase_bypass`: `bypassed_phase`, `compensating_controls`
+  - `approval_bypass`: `approval_target`, `compensating_controls`
+  - `non_goal_exception`: `affected_non_goals`
+  - override lifecycle: `active` until the declared review/expiry window closes, `expiring` during the last 7 days before it closes, `revalidation_required` after it has passed
+- validates runtime orchestration when present:
+  - `runtime.status`: `idle`, `in_progress`, `handoff_pending`, `blocked`, `completed`
+  - `runtime.current_phase`, `runtime.active_agent`, `runtime.last_transition`, `runtime.block_reason`
+  - `handoffs`: `from_phase`, `to_phase`, `status`, `required_inputs`, `produced_outputs`, `blockers`, `override_refs`
+- enforces the first execution transition gates:
+  - `implementation` cannot start before `planning` is completed
+  - `MEDIUM`/`HIGH` implementation cannot start before `architecture-check` is completed
+  - `review` cannot start before `implementation` is completed
+  - `qa` cannot start before `review` is completed
+  - `approval` cannot start before `qa` is completed
+- requires matching evidence blocks for completed evidence-bearing phases
+- requires matching role contract blocks for completed canonical agent-owned phases
+- requires approval metadata for `risk_exception` and `approval_bypass`
+- emits non-blocking warnings for `expiring` overrides and blocks workflows that reach `revalidation_required`
+- requires PR-visible override references for declared workflow overrides
+- requires runtime `handoff_pending` states to point to an open pending handoff
+- blocks handoffs that still reference overrides requiring revalidation
+- requires concrete handoff input and output artifact lists
+- requires canonical execution phases by risk:
+  - `LOW`: `planning`, `implementation`, `review`
+  - `MEDIUM`: `planning`, `architecture-check`, `implementation`, `review`, `qa`
+  - `HIGH`: `planning`, `architecture-check`, `implementation`, `review`, `qa`, `approval`
+- enforces minimum `required_reviews` from `rules/risk-review-matrix.md`
+- requires `governance.human_approval_required: true` for `HIGH` risk workflows
+- requires non-empty `governance.approval_evidence` for `HIGH` risk workflows
+- requires workflows that touch protected areas to:
+  - use `HIGH` risk
+  - set `governance.escalation_required: true`
+- treats `governance.protected_areas_touched: [none]` as an explicit no-protected-area case
+- validates PR body markdown files against the existing PR template with:
+  - a non-empty `Linked Issue` section
+  - a `Workflow File` entry matching `context.workflow_file`
+  - a `Declared risk level` entry matching `context.risk_level`
+  - a `Human approval login if required` entry matching `evidence.approval.approved_by` for approval-gated workflows
+  - override `Approved by login` entries matching workflow `approved_by` logins when present
+  - evidence references that point to existing workflow evidence blocks
+  - override references that point to existing typed workflow overrides
+  - a checked confirmation that the linked workflow governed the change
+  - a checked confirmation that the workflow governed the work from the start, not only as a retrospective reference
+  - a checked confirmation that scope, non-goals, and risk were fixed in the workflow before implementation started
+  - a checked confirmation that required workflow phases were executed as visible working steps, not only documented after the fact
+- validates GitHub PR review metadata against workflow approval claims by requiring `APPROVED` reviews from the declared `approved_by` logins
+- exposes workflow reporting views for a single workflow (`status`) and a directory tree (`audit`) with optional JSON output
+- supports synchronous external agent execution for canonical agent-owned phases through a central runner config and JSON result contract
+- supports dry-run and explicit-apply sync for PolicyFlow-managed Consumer-Repo assets
+
+This runtime layer is intentionally small. It mutates only controlled workflow fields and does not execute agents, schedule work, or orchestrate GitHub runs directly.
+
+PolicyFlow now acts as a lightweight workflow orchestration layer as well as a governance validator, but it is still not a full orchestration platform, scheduler, or agent runtime.
+
+## Compatibility
+
+Follow the canonical workflow schema and migration guidance in
+[docs/schema-compatibility.md](docs/schema-compatibility.md). Stable public
+imports are documented in [docs/public-api.md](docs/public-api.md).
+
+## Project Status
+
+PolicyFlow is release-ready for `0.1.0` packaging and publication once the PyPI
+package and matching GitHub Release are created. Until that release exists,
+install from this repository for evaluation and use the pinned
+`policyflow==0.1.0` commands as the intended published Consumer-Repo path.
+
+## Future Roadmap
+
+- release publishing automation after packaged release checks are proven
+- additional consumer validation beyond AurumEdge once more repos adopt the workflow
+
+## License
+
+See [LICENSE](LICENSE).