nold-ai · djm81 · Feb 18, 2026 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,29 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.33.0] - 2026-02-17
+
+### Added
+
+- New `policy-engine` module package with lazy-loaded `specfact policy` command group.
+- `specfact policy validate` for deterministic policy evaluation with hard failures and dual output (`json`, `markdown`, or `both`).
+- `specfact policy suggest` for confidence-scored, patch-ready suggestions with explicit no-auto-write behavior.
+- Policy configuration loader for `.specfact/policy.yaml` supporting Scrum DoR/DoD fields, Kanban column entry/exit requirements, and SAFe PI readiness fields.
+- Integration tests for policy commands in `tests/integration/commands/test_policy_engine_commands.py` with recorded TDD evidence.
+
+### Changed
+
+- Updated Agile/Scrum and DevOps adapter integration guides with policy engine command usage and workflow guidance.
+- `specfact policy validate` and `specfact policy suggest` now apply `--limit` to backlog item group count when `--group-by-item` is enabled (instead of truncating sub-item findings/suggestions).
+- Grouped-mode policy output now avoids duplicate top-level flat arrays and emits grouped payloads with summary metadata for cleaner consumption.
+- Policy command docs and OpenSpec change artifacts were updated to document grouped-limit semantics and grouped output behavior.
+
+### Fixed
+
+- Resolved type-check errors in `policy_engine/main.py` by introducing typed grouped payload structures and explicit payload typing.
+
+---
+
 ## [0.32.1] - 2026-02-17
 
 ### Added

diff --git a/README.md b/README.md
@@ -113,6 +113,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
+- `specfact policy validate ...`
+- `specfact policy suggest ...`
+
+What the Policy Engine does in practice:
+- Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data.
+- Shows exactly what is missing per item (for example missing acceptance criteria or definition of done).
+- Generates patch-ready suggestions so teams can fix policy gaps quickly without guessing.
+
+Start with:
+- `specfact policy init --template scrum`
+- `specfact policy validate --group-by-item`
+- `specfact policy suggest --group-by-item --limit 5`
 
 **Try it now**
 
@@ -221,6 +233,7 @@ SpecFact complements your stack rather than replacing it.
 - **[Backlog Refinement](docs/guides/backlog-refinement.md)**
 - **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)**
 - **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)**
+- **[Policy Engine Commands](docs/guides/policy-engine-commands.md)**
 - **[Project DevOps Flow](docs/guides/project-devops-flow.md)**
 - **[Sidecar Validation](docs/guides/sidecar-validation.md)**
 - **[OpenSpec Journey](docs/guides/openspec-journey.md)**

diff --git a/docs/README.md b/docs/README.md
@@ -22,6 +22,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
+- `specfact policy validate ...`
+- `specfact policy suggest ...`
+
+What the Policy Engine does in practice:
+- Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks.
+- Flags exact policy gaps per backlog item with actionable evidence pointers.
+- Produces patch-ready suggestions so teams can remediate quickly.
+
+Start with:
+- `specfact policy init --template scrum`
+- `specfact policy validate --group-by-item`
+- `specfact policy suggest --group-by-item --limit 5`
 
 **Try it now**
 
@@ -109,6 +121,7 @@ For implementation details, see:
 - [Backlog Refinement](guides/backlog-refinement.md)
 - [Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)
 - [Backlog Delta Commands](guides/backlog-delta-commands.md)
+- [Policy Engine Commands](guides/policy-engine-commands.md)
 - [Project DevOps Flow](guides/project-devops-flow.md)
 - [DevOps Adapter Integration](guides/devops-adapter-integration.md)
 - [AI IDE Workflow](guides/ai-ide-workflow.md)

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -141,6 +141,7 @@ <h2 class="docs-sidebar-title">
               <ul>
                 <li><a href="{{ '/guides/command-chains/' | relative_url }}">Command Chains</a></li>
                 <li><a href="{{ '/guides/agile-scrum-workflows/' | relative_url }}">Agile/Scrum Workflows</a></li>
+                <li><a href="{{ '/guides/policy-engine-commands/' | relative_url }}">Policy Engine Commands</a></li>
                 <li><a href="{{ '/guides/creating-custom-bridges/' | relative_url }}">Creating Custom Bridges</a></li>
                 <li><a href="{{ '/guides/extending-projectbundle/' | relative_url }}">Extending ProjectBundle</a></li>
                 <li><a href="{{ '/guides/using-module-security-and-extensions/' | relative_url }}">Using Module Security and Extensions</a></li>

diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md
@@ -50,6 +50,21 @@ SpecFact CLI supports real-world agile/scrum practices through:
 - **Business Value Focus**: User-focused value statements and measurable outcomes
 - **Conflict Resolution**: Persona-aware three-way merge with automatic conflict resolution based on section ownership
 
+## Policy Engine Commands (DoR/DoD/Flow/PI)
+
+Use the `policy` command group to run deterministic readiness checks before sprint and refinement ceremonies:
+
+```bash
+# Validate configured policy rules against a snapshot
+specfact policy validate --repo . --format both
+
+# Generate confidence-scored, patch-ready suggestions (no automatic writes)
+specfact policy suggest --repo .
+```
+
+Policy configuration is loaded from `.specfact/policy.yaml` and supports Scrum (`dor_required_fields`,
+`dod_required_fields`), Kanban column entry/exit requirements, and SAFe PI readiness fields.
+
 **🆕 NEW: Backlog Refinement Integration** - Use `specfact backlog ceremony refinement` to standardize backlog items from GitHub Issues, Azure DevOps, and other tools into template-compliant format before importing into project bundles. See [Backlog Refinement Guide](backlog-refinement.md) for complete documentation.
 
 **Tutorial**: For an end-to-end daily standup and sprint review walkthrough (auto-detect repo, view standup, post comment, interactive, Copilot export), see **[Tutorial: Daily Standup and Sprint Review](../getting-started/tutorial-daily-standup-sprint-review.md)**.

diff --git a/docs/guides/devops-adapter-integration.md b/docs/guides/devops-adapter-integration.md
@@ -11,6 +11,22 @@ permalink: /guides/devops-adapter-integration/
 
 This guide explains how to integrate SpecFact CLI with DevOps backlog tools (GitHub Issues, Azure DevOps, Linear, Jira) to sync OpenSpec change proposals and track implementation progress through automated comment annotations.
 
+## Policy Readiness in DevOps Flows
+
+You can validate policy readiness (DoR/DoD, Kanban flow gates, SAFe PI hooks) before posting updates back to
+your backlog system:
+
+```bash
+# Deterministic policy validation with JSON + Markdown output
+specfact policy validate --repo . --format both
+
+# AI-assisted suggestions with confidence scores and patch-ready output
+specfact policy suggest --repo .
+```
+
+Both commands read `.specfact/policy.yaml`. `policy suggest` never writes changes automatically; it emits
+recommendations you can review and apply explicitly in your normal workflow.
+
 ## Overview
 
 **Why This Matters**: This feature bridges the gap between specification management (OpenSpec) and backlog management (GitHub Issues, ADO, Linear, Jira), allowing you to use SpecFact's specification-driven development approach while working within your existing agile DevOps workflows.

diff --git a/docs/guides/policy-engine-commands.md b/docs/guides/policy-engine-commands.md
@@ -0,0 +1,151 @@
+---
+layout: default
+title: Policy Engine Commands
+permalink: /guides/policy-engine-commands/
+---
+
+# Policy Engine Commands
+
+Use SpecFact policy commands to scaffold, validate, and improve policy configuration for common frameworks.
+
+## Overview
+
+The policy engine currently supports:
+
+- `specfact policy init` to scaffold `.specfact/policy.yaml` from a built-in template.
+- `specfact policy validate` to evaluate configured rules deterministically against policy input artifacts.
+- `specfact policy suggest` to generate confidence-scored, patch-ready recommendations (no automatic writes).
+
+## Commands
+
+### Initialize Policy Config
+
+Create a starter policy configuration file:
+
+```bash
+specfact policy init --repo . --template scrum
+```
+
+Supported templates:
+
+- `scrum`
+- `kanban`
+- `safe`
+- `mixed`
+
+Interactive mode (template prompt):
+
+```bash
+specfact policy init --repo .
+```
+
+The command writes `.specfact/policy.yaml`. Use `--force` to overwrite an existing file.
+
+### Validate Policies
+
+Run policy checks with deterministic output:
+
+```bash
+specfact policy validate --repo . --format both
+```
+
+Artifact resolution order when `--snapshot` is omitted:
+
+1. `.specfact/backlog-baseline.json`
+2. Latest `.specfact/plans/backlog-*.yaml|yml|json`
+
+You can still override with an explicit path:
+
+```bash
+specfact policy validate --repo . --snapshot ./snapshot.json --format both
+```
+
+Filter and scope output:
+
+```bash
+# only one rule family, max 20 findings
+specfact policy validate --repo . --rule scrum.dor --limit 20 --format json
+
+# item-centric grouped output
+specfact policy validate --repo . --group-by-item --format both
+
+# in grouped mode, --limit applies to item groups
+specfact policy validate --repo . --group-by-item --limit 4 --format json
+```
+
+Output formats:
+
+- `json`
+- `markdown`
+- `both`
+
+When config is missing or invalid, the command prints a docs hint pointing back to this policy format guidance.
+
+### Suggest Policy Fixes
+
+Generate suggestions from validation findings:
+
+```bash
+specfact policy suggest --repo .
+```
+
+Suggestion shaping options:
+
+```bash
+# suggestions for one rule family, limited output
+specfact policy suggest --repo . --rule scrum.dod --limit 10
+
+# grouped suggestions by backlog item index
+specfact policy suggest --repo . --group-by-item
+
+# grouped mode limits item groups, not per-item fields
+specfact policy suggest --repo . --group-by-item --limit 4
+```
+
+Suggestions include confidence scores and patch-ready structure, but no file is modified automatically.
+
+## Policy File Location and Format
+
+Expected location:
+
+- `.specfact/policy.yaml`
+
+Minimal structure:
+
+```yaml
+scrum:
+  dor_required_fields: [acceptance_criteria]
+  dod_required_fields: [definition_of_done]
+kanban:
+  columns:
+    In Progress:
+      exit_required_fields: [qa_status]
+safe:
+  pi_readiness_required_fields: [risk_owner]
+```
+
+## Template Assets
+
+Built-in templates are shipped from:
+
+- `resources/templates/policies/`
+
+These templates are intended as a starting point and should be adjusted to team/project policy needs.
+
+## Accepted Policy Input Shapes
+
+Policy commands normalize these payload structures:
+
+- `[{...}, {...}]`
+- `{ items: [{...}, {...}] }`
+- `{ items: { "ID-1": {...}, "ID-2": {...} } }`
+- `{ backlog_graph: { items: [...] } }`
+- `{ backlog_graph: { items: { "ID-1": {...} } } }`
+
+## Compatibility Mapping for Imported Artifacts
+
+Before evaluating rules, policy input normalization maps common aliases to canonical policy fields:
+
+- `acceptance_criteria` from aliases such as `acceptanceCriteria`, `System.AcceptanceCriteria`, or description section `## Acceptance Criteria`
+- `business_value` from aliases such as `businessValue` or `Microsoft.VSTS.Common.BusinessValue`
+- `definition_of_done` from aliases such as `definitionOfDone` or description section `## Definition of Done`
diff --git a/docs/index.md b/docs/index.md
@@ -90,6 +90,7 @@ Why this matters:
 
 - **[Command Chains](guides/command-chains.md)** ⭐ **NEW** - Complete workflows from start to finish
 - **[Agile/Scrum Workflows](guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams
+- **[Policy Engine Commands](guides/policy-engine-commands.md)** - Scaffold policy config templates and run `policy init|validate|suggest`
 - **[DevOps Backlog Integration](guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows with bidirectional backlog sync
 - **[Backlog Refinement](guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven backlog refinement for standardizing work items
 - **[Backlog Dependency Analysis](guides/backlog-dependency-analysis.md)** - Analyze critical path, cycles, orphans, and dependency impact from backlog graph data

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -162,6 +162,13 @@ specfact auth status
 - `validate sidecar run` - Run sidecar validation workflow (CrossHair + Specmatic)
   - **Workflow**: [Sidecar Validation Chain](../guides/command-chains.md#5-sidecar-validation-chain)
 
+**Policy Engine:**
+
+- `policy init` - Scaffold `.specfact/policy.yaml` from built-in templates (`scrum`, `kanban`, `safe`, `mixed`)
+- `policy validate` - Run deterministic policy checks; auto-discovers `.specfact/backlog-baseline.json` then latest `.specfact/plans/backlog-*` when `--snapshot` is omitted; supports `--rule`, `--limit`, `--group-by-item` (`--limit` applies to item groups when grouped)
+- `policy suggest` - Generate confidence-scored, patch-ready policy suggestions (no automatic writes); same artifact auto-discovery behavior as validate; supports `--rule`, `--limit`, `--group-by-item` (`--limit` applies to item groups when grouped)
+- **Guide**: [Policy Engine Commands](../guides/policy-engine-commands.md)
+
 **API Specification Management:**
 
 - `spec validate` - Validate OpenAPI/AsyncAPI specifications with Specmatic

diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
@@ -30,7 +30,7 @@ Changes are grouped by **module** and prefixed with **`<module>-NN-`** so implem
 
 ### Pending
 
-All entries in the table below are pending implementation.
+Entries in the tables below are pending unless explicitly marked as implemented (pending archive).
 
 ## Plan-derived addendum (2026-02-15 architecture integration plan)
 
@@ -62,7 +62,7 @@ These are derived extensions of the same 2026-02-15 plan and are required to ope
 
 | Module | Order | Change folder | GitHub # | Blocked by |
 |--------|-------|---------------|----------|------------|
-| policy-engine | 01 | policy-engine-01-unified-framework | [#176](https://github.com/nold-ai/specfact-cli/issues/176) | — |
+| policy-engine | 01 | policy-engine-01-unified-framework ✅ (implemented 2026-02-17; pending archive) | [#176](https://github.com/nold-ai/specfact-cli/issues/176) | — |
 | patch-mode | 01 | patch-mode-01-preview-apply | [#177](https://github.com/nold-ai/specfact-cli/issues/177) | — |
 | validation | 01 | validation-01-deep-validation | [#163](https://github.com/nold-ai/specfact-cli/issues/163) | — |
 | bundle-mapper | 01 | bundle-mapper-01-mapping-strategy | [#121](https://github.com/nold-ai/specfact-cli/issues/121) | — |
@@ -254,7 +254,7 @@ Dependencies flow left-to-right; a wave may start once all its hard blockers are
 
 - **Wave 1 — Platform extensions + cross-cutting foundations** (arch-06 ✅, arch-07 ✅, ci-01 ✅):
   - arch-06 ✅, arch-07 ✅, ci-01 ✅
-  - policy-engine-01, patch-mode-01
+  - policy-engine-01 ✅, patch-mode-01
   - backlog-core-01
   - validation-01, sidecar-01 ✅, bundle-mapper-01