Merge pull request #85 from dmoliveira/my_opencode-e15-enforcement-engine

Complete E15 todo enforcer and plan compliance

Author: dmoliveira

CHANGELOG.md

@@ -49,6 +49,9 @@ All notable changes to this project are documented in this file.
 - 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.
+- Added `scripts/todo_enforcement.py` with deterministic todo transition/completion validation and remediation hint helpers for Epic 15 Task 15.2.
+- Added `scripts/todo_command.py` with `/todo status` and `/todo enforce` diagnostics for runtime compliance visibility.
+- Added `/todo`, `/todo-status`, and `/todo-enforce` aliases in `opencode.json`.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.
@@ -93,6 +96,9 @@ All notable changes to this project are documented in this file.
 - Expanded install/selftest coverage for `/start-work` plan validation, execution state persistence, and deviation diagnostics.
 - Expanded `/start-work` integrations with background queue handoff, digest recap payloads, and unified `/doctor` visibility.
 - Expanded `/start-work` validation coverage for missing frontmatter, out-of-order ordinals, and recovery from invalid runtime state.
+- Updated `/start-work` execution to enforce todo compliance transitions, emit audit events, and block completion when required items remain unchecked.
+- Integrated todo compliance checks into `/doctor` summary, installer self-checks, and install-test smoke coverage.
+- Expanded selftest coverage for todo transition gating, completion blocking, and bypass audit-event payload validation.
 
 ## v0.2.0 - 2026-02-12
 

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 | in_progress | High | E14 | bd-l9c | Keep execution aligned with approved checklists |
+| E15 | Todo Enforcer and Plan Compliance | done | 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,7 +595,7 @@ Every command-oriented epic must ship all of the following:
 
 ## Epic 15 - Todo Enforcer and Plan Compliance
 
-**Status:** `in_progress`
+**Status:** `done`
 **Priority:** High
 **Goal:** Enforce explicit checklist progress during execution so outcomes stay aligned with approved plans.
 **Depends on:** Epic 14
@@ -605,20 +605,23 @@ Every command-oriented epic must ship all of the following:
   - [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
-  - [ ] Subtask 15.2.3: Emit actionable remediation prompts on violations
-- [ ] Task 15.3: Integrate command workflows
-  - [ ] Subtask 15.3.1: Integrate with plan execution command and background runs
-  - [ ] Subtask 15.3.2: Add `/todo status` and `/todo enforce` diagnostics
-  - [ ] Subtask 15.3.3: Add docs for compliant workflow patterns
-- [ ] Task 15.4: Verification
-  - [ ] Subtask 15.4.1: Add tests for transition validity and blocking behavior
-  - [ ] Subtask 15.4.2: Add tests for bypass annotations and logs
-  - [ ] Subtask 15.4.3: Add install-test smoke scenarios
-- [ ] Exit criteria: plan completion cannot be marked done with unchecked required items
-- [ ] Exit criteria: bypass behavior is explicit, logged, and reviewable
+- [x] Task 15.2: Implement enforcement engine
+  - [x] Subtask 15.2.1: Validate state transitions before major actions
+  - [x] Subtask 15.2.2: Block completion when required tasks remain unchecked
+  - [x] Subtask 15.2.3: Emit actionable remediation prompts on violations
+  - [x] Notes: Added `scripts/todo_enforcement.py` and wired `/start-work` to enforce deterministic todo transitions, completion gating, and remediation/audit outputs in runtime state.
+- [x] Task 15.3: Integrate command workflows
+  - [x] Subtask 15.3.1: Integrate with plan execution command and background runs
+  - [x] Subtask 15.3.2: Add `/todo status` and `/todo enforce` diagnostics
+  - [x] Subtask 15.3.3: Add docs for compliant workflow patterns
+  - [x] Notes: Added `scripts/todo_command.py`, command aliases, doctor integration, and README/install workflow guidance for explicit todo compliance checks.
+- [x] Task 15.4: Verification
+  - [x] Subtask 15.4.1: Add tests for transition validity and blocking behavior
+  - [x] Subtask 15.4.2: Add tests for bypass annotations and logs
+  - [x] Subtask 15.4.3: Add install-test smoke scenarios
+  - [x] Notes: Expanded `scripts/selftest.py` and install smoke checks for transition gating, completion blocking, bypass metadata validation, and deterministic bypass audit payloads.
+- [x] Exit criteria: plan completion cannot be marked done with unchecked required items
+- [x] Exit criteria: bypass behavior is explicit, logged, and reviewable
 
 ---
 

Makefile

@@ -49,6 +49,7 @@ install-test: ## Run installer smoke test in temp HOME
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/stack_profile_command.py" status; \
 	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" profile agent-browser; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" doctor --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" profile playwright; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" doctor --json; fi; \
 	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" ]; then PLAN_FILE="$$TMP_HOME/.config/opencode/my_opencode/.install-test-plan.md"; python3 -c "from pathlib import Path; Path('$$PLAN_FILE').write_text('---\nid: install-test-plan\ntitle: Install Test Plan\nowner: install-test\ncreated_at: 2026-02-13T00:00:00Z\nversion: 1\n---\n\n# Plan\n\n- [ ] 1. Validate command availability\n- [ ] 2. Validate status persistence\n', encoding='utf-8')"; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" "$$PLAN_FILE" --deviation "install smoke" --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" "$$PLAN_FILE" --background --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/background_task_manager.py" run --max-jobs 1; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" deviations --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" doctor --json; fi; \
+	if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/todo_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/todo_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/todo_command.py" enforce --json; fi; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py" install minimal --link-init; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py" status; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/devtools_command.py" status; \

README.md

@@ -588,7 +588,7 @@ Epic 14 Task 14.1 defines the baseline plan format and execution-state rules for
 - backend command: `scripts/start_work_command.py`
 - format scope: markdown checklist + YAML metadata frontmatter
 - validation scope: deterministic preflight failures with line-level remediation hints
-- state model scope: `pending/in_progress/completed/failed/skipped` with strict transition semantics
+- state model scope: `pending/in_progress/done/skipped` with strict transition semantics
 
 Use:
 ```text
@@ -614,6 +614,23 @@ Epic 15 Task 15.1 defines the baseline compliance contract for enforced todo exe
 - enforcement: one active item at a time with deterministic transition validation
 - bypass path: explicit metadata + audit event requirements for controlled exceptions
 
+Epic 15 Task 15.2 implements the enforcement backend:
+
+- engine module: `scripts/todo_enforcement.py`
+- `/start-work` now validates todo transitions before state mutation and blocks completion when required items remain unchecked
+- compliance violations now emit deterministic remediation prompts and persisted audit events
+
+Use:
+```text
+/todo status --json
+/todo enforce --json
+```
+
+Compliant workflow pattern:
+- run `/start-work path/to/plan.md --json`
+- inspect `/todo status --json` for current state counts
+- gate handoff/closure with `/todo enforce --json`
+
 ## Context resilience policy
 
 Epic 11 Task 11.1 defines the baseline policy schema for context-window resilience:
@@ -961,6 +978,8 @@ For your LangGraph setup, default endpoint target is `http://localhost:3000/open
 - `scripts/stack_profile_command.py` - backend script for `/stack`
 - `scripts/browser_command.py` - backend script for `/browser`
 - `scripts/start_work_command.py` - backend script for `/start-work`
+- `scripts/todo_command.py` - backend script for `/todo`
+- `scripts/todo_enforcement.py` - shared todo compliance enforcement helpers
 - `scripts/install_wizard.py` - interactive install/reconfigure wizard
 - `scripts/nvim_integration_command.py` - backend script for `/nvim`
 - `scripts/devtools_command.py` - backend script for `/devtools`

install.sh

@@ -75,6 +75,9 @@ fi
 if [ -f "$INSTALL_DIR/scripts/start_work_command.py" ]; then
   chmod +x "$INSTALL_DIR/scripts/start_work_command.py"
 fi
+if [ -f "$INSTALL_DIR/scripts/todo_command.py" ]; then
+  chmod +x "$INSTALL_DIR/scripts/todo_command.py"
+fi
 ln -sfn "$INSTALL_DIR/opencode.json" "$CONFIG_PATH"
 
 if [ "$RUN_WIZARD" = true ]; then
@@ -120,6 +123,10 @@ if [ "$SKIP_SELF_CHECK" = false ]; then
     python3 "$INSTALL_DIR/scripts/start_work_command.py" deviations --json
     python3 "$INSTALL_DIR/scripts/start_work_command.py" doctor --json
   fi
+  if [ -f "$INSTALL_DIR/scripts/todo_command.py" ]; then
+    python3 "$INSTALL_DIR/scripts/todo_command.py" status --json
+    python3 "$INSTALL_DIR/scripts/todo_command.py" enforce --json
+  fi
   python3 "$INSTALL_DIR/scripts/nvim_integration_command.py" status
   python3 "$INSTALL_DIR/scripts/devtools_command.py" status
   python3 "$INSTALL_DIR/scripts/doctor_command.py" run || true
@@ -183,6 +190,8 @@ printf "  /start-work-bg ~/.config/opencode/my_opencode/plan.md\n"
 printf "  /start-work status --json\n"
 printf "  /start-work deviations --json\n"
 printf "  /start-work-doctor-json\n"
+printf "  /todo status --json\n"
+printf "  /todo enforce --json\n"
 printf "  /nvim status\n"
 printf "  /devtools status\n"
 printf "  /devtools install all\n"

opencode.json

@@ -290,6 +290,18 @@
       "description": "Run plan execution health diagnostics in JSON",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/start_work_command.py\" doctor --json`\nShow only the command output."
     },
+    "todo": {
+      "description": "Inspect todo compliance state (status|enforce)",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/todo_command.py\" $ARGUMENTS`\nShow only the command output."
+    },
+    "todo-status": {
+      "description": "Show latest todo compliance status",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/todo_command.py\" status --json`\nShow only the command output."
+    },
+    "todo-enforce": {
+      "description": "Run todo compliance enforcement checks in JSON",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/todo_command.py\" enforce --json`\nShow only the command output."
+    },
     "nvim": {
       "description": "Manage Neovim OpenCode integration (status|doctor|snippet|install|uninstall)",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py\" $ARGUMENTS`\nShow only the command output."

scripts/doctor_command.py

@@ -192,6 +192,18 @@ def script_path(name: str) -> Path:
             "--json",
         ],
     },
+    {
+        "name": "todo",
+        "kind": "doctor-json",
+        "optional": True,
+        "required_path": str(script_path("todo_command.py")),
+        "command": [
+            sys.executable,
+            str(script_path("todo_command.py")),
+            "enforce",
+            "--json",
+        ],
+    },
 ]