Merge pull request #84 from dmoliveira/my_opencode-e15-compliance-model

Define E15-T1 todo compliance model

Author: dmoliveira

CHANGELOG.md

@@ -48,6 +48,7 @@ All notable changes to this project are documented in this file.
 - Added `/start-work`, `/start-work-status`, and `/start-work-deviations` aliases in `opencode.json`.
 - Added `/start-work-bg` and `/start-work-doctor-json` aliases for background-safe queueing and execution health diagnostics.
 - Added `instructions/plan_execution_workflows.md` with sample plans and direct/background/recovery workflows for `/start-work`.
+- Added `instructions/todo_compliance_model.md` defining todo states, transition enforcement, bypass metadata, and compliance audit event format for Epic 15 Task 15.1.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.

IMPLEMENTATION_ROADMAP.md

@@ -51,7 +51,7 @@ Use this map to avoid overlapping implementations.
 | E12 | Provider/Model Fallback Visibility | done | Medium | E5 | bd-1jq, bd-298, bd-194, bd-2gq | Explain why model routing decisions happen |
 | E13 | Browser Automation Profile Switching | done | Medium | E1 | bd-3rs, bd-2qy, bd-f6g, bd-393 | Toggle Playwright/agent-browser with checks |
 | E14 | Plan-to-Execution Bridge Command | done | Medium | E2, E3 | bd-1z6, bd-2te, bd-3sg, bd-2bv | Execute validated plans with progress tracking |
-| E15 | Todo Enforcer and Plan Compliance | planned | High | E14 | TBD | Keep execution aligned with approved checklists |
+| E15 | Todo Enforcer and Plan Compliance | in_progress | High | E14 | bd-l9c | Keep execution aligned with approved checklists |
 | E16 | Comment and Output Quality Checker Loop | merged | Medium | E23 | TBD | Merged into E23 (PR Review Copilot) |
 | E17 | Auto-Resume and Recovery Loop | planned | High | E11, E14 | TBD | Resume interrupted work from checkpoints safely |
 | E18 | LSP/AST-Assisted Safe Edit Mode | planned | High | E3 | TBD | Prefer semantic edits over plain text replacements |
@@ -595,15 +595,16 @@ Every command-oriented epic must ship all of the following:
 
 ## Epic 15 - Todo Enforcer and Plan Compliance
 
-**Status:** `planned`
+**Status:** `in_progress`
 **Priority:** High
 **Goal:** Enforce explicit checklist progress during execution so outcomes stay aligned with approved plans.
 **Depends on:** Epic 14
 
-- [ ] Task 15.1: Define compliance model
-  - [ ] Subtask 15.1.1: Define required todo states (`pending`, `in_progress`, `done`, `skipped`)
-  - [ ] Subtask 15.1.2: Define rules for one-active-item-at-a-time enforcement
-  - [ ] Subtask 15.1.3: Define acceptable bypass annotations and audit format
+- [x] Task 15.1: Define compliance model
+  - [x] Subtask 15.1.1: Define required todo states (`pending`, `in_progress`, `done`, `skipped`)
+  - [x] Subtask 15.1.2: Define rules for one-active-item-at-a-time enforcement
+  - [x] Subtask 15.1.3: Define acceptable bypass annotations and audit format
+  - [x] Notes: Added `instructions/todo_compliance_model.md` with state model, transition constraints, bypass metadata requirements, and audit event contract.
 - [ ] Task 15.2: Implement enforcement engine
   - [ ] Subtask 15.2.1: Validate state transitions before major actions
   - [ ] Subtask 15.2.2: Block completion when required tasks remain unchecked

README.md

@@ -605,6 +605,15 @@ Integration notes:
 - `/digest run` now includes a `plan_execution` recap block (status, plan id, step counts, deviation count)
 - `/doctor run` includes `start-work` health diagnostics for execution-state visibility
 
+## Todo compliance model
+
+Epic 15 Task 15.1 defines the baseline compliance contract for enforced todo execution:
+
+- compliance spec: `instructions/todo_compliance_model.md`
+- required states: `pending`, `in_progress`, `done`, `skipped`
+- enforcement: one active item at a time with deterministic transition validation
+- bypass path: explicit metadata + audit event requirements for controlled exceptions
+
 ## Context resilience policy
 
 Epic 11 Task 11.1 defines the baseline policy schema for context-window resilience:

instructions/todo_compliance_model.md

@@ -0,0 +1,96 @@
+# Todo Compliance Model
+
+Epic 15 Task 15.1 defines the compliance contract that keeps execution aligned with approved plans.
+
+## Goals
+
+- enforce explicit, auditable todo state progression during plan execution
+- prevent silent task skipping by allowing only explicit, reasoned bypass paths
+- keep compliance checks deterministic and machine-readable for automation
+
+## Required todo state model
+
+Every tracked todo item must be in exactly one state:
+
+- `pending`: planned but not started
+- `in_progress`: actively being executed
+- `done`: completed and verified
+- `skipped`: intentionally not executed with explicit rationale
+
+Unknown states must fail compliance checks.
+
+## Core enforcement rules
+
+1. Exactly one item may be `in_progress` at a time.
+2. Transition order must follow:
+   - `pending -> in_progress`
+   - `in_progress -> done`
+   - `in_progress -> skipped`
+3. Direct transitions like `pending -> done` are invalid unless a bypass annotation exists.
+4. Plan completion is valid only when all items are `done` or `skipped`.
+
+## Bypass annotations
+
+Bypass is allowed only through explicit metadata attached to the affected item:
+
+- `bypass_reason`: concise justification
+- `bypass_actor`: who authorized it
+- `bypass_at`: RFC3339 timestamp
+- `bypass_type`: one of `risk_acceptance`, `scope_change`, `emergency_hotfix`
+
+Missing any required bypass field must invalidate the bypass.
+
+## Audit event format
+
+Compliance-relevant state transitions should emit append-only events:
+
+```json
+{
+  "event": "todo_transition",
+  "todo_id": "todo-3",
+  "from": "pending",
+  "to": "in_progress",
+  "at": "2026-02-13T12:00:00Z",
+  "actor": "diego",
+  "compliance": "enforced"
+}
+```
+
+Bypass usage should emit:
+
+```json
+{
+  "event": "todo_bypass",
+  "todo_id": "todo-5",
+  "from": "pending",
+  "to": "done",
+  "at": "2026-02-13T12:05:00Z",
+  "actor": "diego",
+  "bypass": {
+    "type": "scope_change",
+    "reason": "task absorbed into prior step",
+    "authorized_by": "owner"
+  }
+}
+```
+
+## Validation outcomes
+
+Compliance checks should return deterministic results:
+
+- `PASS`: all todo states and transitions satisfy rules
+- `FAIL`: violations detected; include violation code(s), affected todo id(s), and remediation hints
+
+Reference violation codes:
+
+- `unknown_todo_state`
+- `multiple_in_progress_items`
+- `invalid_transition`
+- `missing_bypass_metadata`
+- `incomplete_todo_set`
+
+## Integration targets
+
+- Task 15.2 should implement enforcement engine checks for this model
+- Task 15.3 should expose `/todo status` and `/todo enforce` diagnostics with machine-readable outputs
+- Task 15.4 should validate normal, bypass, and failure paths with docs/examples