dmoliveira · dmoliveira · Feb 13, 2026 · Feb 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -43,6 +43,7 @@ All notable changes to this project are documented in this file.
 - Added `scripts/browser_command.py` with `/browser status`, `/browser profile <provider>`, and `/browser doctor` for provider switching and dependency diagnostics.
 - Added `/browser`, `/browser-status`, `/browser-profile`, and `/browser-doctor-json` aliases in `opencode.json`.
 - Added browser profile selection support to `scripts/install_wizard.py` via `--browser-profile <playwright|agent-browser>`.
+- Added `instructions/plan_artifact_contract.md` defining `/start-work` plan metadata/checklist format, validation rules, step transitions, and deviation capture requirements.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.

diff --git a/IMPLEMENTATION_ROADMAP.md b/IMPLEMENTATION_ROADMAP.md
@@ -50,7 +50,7 @@ Use this map to avoid overlapping implementations.
 | E11 | Context-Window Resilience Toolkit | done | High | E4 | bd-2tj, bd-n9y, bd-2t0, bd-18e | Improve long-session stability and recovery |
 | 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 | planned | Medium | E2, E3 | TBD | Execute validated plans with progress tracking |
+| E14 | Plan-to-Execution Bridge Command | in_progress | Medium | E2, E3 | bd-1z6 | Execute validated plans with progress tracking |
 | E15 | Todo Enforcer and Plan Compliance | planned | High | E14 | TBD | 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 |
@@ -563,15 +563,16 @@ Every command-oriented epic must ship all of the following:
 
 ## Epic 14 - Plan-to-Execution Bridge Command
 
-**Status:** `planned`
+**Status:** `in_progress`
 **Priority:** Medium
 **Goal:** Add a command to execute from an approved plan artifact with progress tracking and deviation reporting.
 **Depends on:** Epic 2, Epic 3
 
-- [ ] Task 14.1: Define plan artifact contract
-  - [ ] Subtask 14.1.1: Define accepted plan format (markdown checklist + metadata)
-  - [ ] Subtask 14.1.2: Define validation rules before execution starts
-  - [ ] Subtask 14.1.3: Define step state transitions and completion semantics
+- [x] Task 14.1: Define plan artifact contract
+  - [x] Subtask 14.1.1: Define accepted plan format (markdown checklist + metadata)
+  - [x] Subtask 14.1.2: Define validation rules before execution starts
+  - [x] Subtask 14.1.3: Define step state transitions and completion semantics
+  - [x] Notes: Added `instructions/plan_artifact_contract.md` covering artifact schema, deterministic validation failures, transition rules, and deviation capture requirements for `/start-work`.
 - [ ] Task 14.2: Implement execution bridge backend
   - [ ] Subtask 14.2.1: Add `/start-work <plan>` command implementation
   - [ ] Subtask 14.2.2: Execute steps sequentially with checkpoint updates

diff --git a/README.md b/README.md
@@ -579,6 +579,15 @@ Recommended workflow:
 - run `/rules status` after edits to validate discovery
 - use `/rules explain <path> --json` to verify effective rule stack before relying on behavior
 
+## Plan execution artifact contract
+
+Epic 14 Task 14.1 defines the baseline plan format and execution-state rules for the upcoming `/start-work <plan>` command:
+
+- contract spec: `instructions/plan_artifact_contract.md`
+- 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
+
 ## Context resilience policy
 
 Epic 11 Task 11.1 defines the baseline policy schema for context-window resilience:

diff --git a/instructions/plan_artifact_contract.md b/instructions/plan_artifact_contract.md
@@ -0,0 +1,118 @@
+# Plan Artifact Contract
+
+Epic 14 Task 14.1 defines the baseline artifact contract for `/start-work <plan>` execution.
+
+## Goals
+
+- keep plan execution deterministic from a human-reviewed artifact
+- fail fast on malformed or unsafe plans with actionable errors
+- preserve step progress and deviations in a machine-readable state model
+
+## Accepted artifact format
+
+The command accepts a markdown file with two required sections in this order:
+
+1. metadata frontmatter (YAML)
+2. execution checklist body (markdown task list)
+
+Reference skeleton:
+
+```markdown
+---
+id: plan-2026-02-13-e14t1
+title: Example migration plan
+owner: diego
+created_at: 2026-02-13T10:00:00Z
+version: 1
+---
+
+# Plan
+
+- [ ] 1. Prepare baseline checks
+- [ ] 2. Apply implementation changes
+- [ ] 3. Run verification and summarize deltas
+```
+
+## Metadata contract
+
+Required keys:
+
+- `id`: stable slug-like identifier (`[a-z0-9][a-z0-9-_]{2,63}`)
+- `title`: non-empty human label
+- `owner`: actor/team responsible for execution
+- `created_at`: RFC3339 timestamp
+- `version`: positive integer
+
+Optional keys:
+
+- `depends_on`: array of external references (issue ids, PRs, doc ids)
+- `risk_level`: one of `low`, `medium`, `high`
+- `timeout_minutes`: integer guardrail for total execution budget
+
+Unknown metadata keys are preserved but ignored by v1 validation.
+
+## Checklist contract
+
+- each executable step must be a top-level markdown checkbox (`- [ ]`)
+- step text must start with a numeric ordinal (`1.`, `2.`, `3.`) to keep ordering explicit
+- ordinals must be strictly increasing without duplicates
+- nested checklist items are treated as notes and are not executable steps
+- empty checkbox lines are invalid
+
+## Pre-execution validation rules
+
+Validation must fail before execution when any of these are true:
+
+- missing frontmatter or malformed YAML
+- missing required metadata key or invalid key value type/format
+- no executable checklist steps
+- duplicate or out-of-order ordinals
+- all steps already marked complete (`- [x]`) at start
+
+Validation output must include:
+
+- deterministic machine-readable error codes
+- file path + line numbers for each violation
+- remediation hints for each failed rule
+
+## Step state model and transitions
+
+Each executable step is tracked with one of:
+
+- `pending`
+- `in_progress`
+- `completed`
+- `failed`
+- `skipped`
+
+Allowed transitions:
+
+- `pending -> in_progress`
+- `in_progress -> completed`
+- `in_progress -> failed`
+- `in_progress -> skipped`
+- `failed -> in_progress` (retry path)
+
+Disallowed transitions must fail with explicit transition error diagnostics.
+
+Completion semantics:
+
+- exactly one step can be `in_progress` at a time
+- plan is complete only when all executable steps are `completed` or `skipped`
+- any `failed` step keeps the overall plan status in failed/recovery-required state
+
+## Deviation capture requirements
+
+Execution runtime must record deviations from the original artifact, including:
+
+- inserted ad-hoc step not present in the source plan
+- skipped required step with rationale
+- reordered execution relative to declared ordinal sequence
+
+Deviation records should include step id, timestamp, reason, and actor.
+
+## Integration targets
+
+- Task 14.2 should implement parser/validator + state transition engine for this contract
+- Task 14.3 should expose contract/state health through doctor and digest outputs
+- Task 14.4 should add parser/transition/recovery tests and user-facing docs with sample plans