fix: unify PLAN↔EXECUTE stage record format (Codex #6)

Add canonical `Files:` field to todo.md stage records:
- docs/state-files.md: schema updated with Files field + backward compat note
- docs/10plan.md: Phase 4 now writes Files field in stage records
- docs/10exec.md: stage loop parses Files field, flags drift, handles legacy
- SKILL.md: plan output template includes Files field

Also adds lessons #8 (enforce schemas) and #9 (trace across boundaries)
discovered during v2.3 integration testing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

SKILL.md

@@ -141,7 +141,7 @@ MEDIUM: [pattern] — [defense]
 1. [foundation] -> 2. [consumer] -> 3. [integration]
 
 ## Stages (R4)
-- [ ] Stage 1: [name] | Entry: [cond] | Exit: [cond]
+- [ ] Stage 1: [name] | Entry: [cond] | Exit: [cond] | Files: [path1, path2]
 - [ ] Stage 2: ...
 
 ## Failure Paths (R7)

docs/10exec.md

@@ -31,7 +31,19 @@ C) Defer — mark as tech debt for later
 - Run `git diff` to see what changed.
 - Self-review the diff against the stage's exit conditions.
 - If tests exist, run them.
-- If the diff touches files NOT in the stage's predicted file list, flag it.
+- Parse the current stage's `Files:` field from `todo.md` (comma-separated paths after `Files:`).
+- If `Files:` field exists: compare the diff's changed files against the predicted list. Flag any file NOT in the list:
+
+```
+File drift detected: {path} was modified but not in the stage's predicted file list.
+Rule 5: is this an intentional scope expansion or accidental coupling?
+
+A) Expected — update the stage's Files field
+B) Refactor — move this change to a separate stage
+C) Revert — this was accidental
+```
+
+- If no `Files:` field (legacy format): skip the file drift check for this stage.
 
 ### 4. Verify (Rule 9)
 

docs/10plan.md

@@ -97,8 +97,14 @@ C) Show me the existing code for these interfaces
    - **Name**
    - **Entry condition** (what must be true before starting)
    - **Exit condition** (what must be true to call it done)
-   - **Files to touch** (predicted)
-2. Write stages as checkboxes to `todo.md` under `## Stages`.
+   - **Files to touch** (predicted, comma-separated)
+2. Write stages as checkboxes to `todo.md` under `## Stages`, using the canonical format:
+
+```
+- [ ] Stage N: {name} | Entry: {cond} | Exit: {cond} | Files: {path1, path2}
+```
+
+The `Files:` field is required. EXECUTE uses it to detect file drift (edits outside predicted files).
 
 ## Phase 5: Failure Path Audit (Rule 7)
 

docs/state-files.md

@@ -12,11 +12,13 @@ Canonical formats for all state files used by 10devrules. Every reader/writer mu
 # Task Plan
 
 ## Stages
-- [ ] Stage 1: {name} | Entry: {condition} | Exit: {condition}
-- [ ] Stage 2: {name} | Entry: {condition} | Exit: {condition}
-- [x] Stage 3: {name} | Entry: {condition} | Exit: {condition}
+- [ ] Stage 1: {name} | Entry: {condition} | Exit: {condition} | Files: {path1, path2}
+- [ ] Stage 2: {name} | Entry: {condition} | Exit: {condition} | Files: {path3}
+- [x] Stage 3: {name} | Entry: {condition} | Exit: {condition} | Files: {path4, path5}
 ```
 
+The `Files:` field lists predicted files to touch (comma-separated). EXECUTE uses this to flag drift when the diff touches unexpected files. If a stage has no `Files:` field (legacy format), EXECUTE skips the file drift check for that stage.
+
 Created by: PLAN Phase 4. Updated by: EXECUTE (checkbox toggling).
 
 ### .10dev/boundary.txt

lessons.md

@@ -26,6 +26,12 @@ The router table, output templates, and anti-pattern table exist because an LLM
 ### 7. Version semantics signal intent
 v1.0 (passive doc) → v2.0 (active agent) → v2.1 (router + DOCS mode). The jump from 1→2 signaled a breaking paradigm shift. 2.0→2.1 signaled additive capability. Naming versions correctly set expectations for consumers.
 
+### 8. Schema must be enforced, not just documented
+State file schemas (docs/state-files.md) defined canonical formats, but another project's agent created developer-profile.md with a completely different format. Documentation alone doesn't prevent drift — the reading agent must validate or normalize on read.
+
+### 9. Contract gaps surface at integration, not in isolation
+PLAN wrote "Files to touch" but todo.md had no field for it. EXECUTE needed it but couldn't find it. The gap was invisible until both modes ran in sequence. Always trace data across mode boundaries, not just within a single mode.
+
 ---
 
-**Formula:** split the monolith, match the platform, symlink the truth, stage the surface, enforce don't suggest, design for your consumer, version your intent.
+**Formula:** split the monolith, match the platform, symlink the truth, stage the surface, enforce don't suggest, design for your consumer, version your intent, enforce the schema, trace across boundaries.

todo.md

@@ -0,0 +1,7 @@
+# Task Plan: Unify PLAN↔EXECUTE Stage Record Format
+
+## Stages
+- [x] Stage 1: Update state-files.md schema | Entry: current schema read | Exit: Files field in format | Files: docs/state-files.md
+- [x] Stage 2: Update 10plan.md Phase 4 | Entry: schema defined | Exit: Phase 4 writes Files field | Files: docs/10plan.md
+- [x] Stage 3: Update 10exec.md stage loop | Entry: format defined | Exit: exec reads Files field | Files: docs/10exec.md
+- [x] Stage 4: Update SKILL.md template | Entry: format defined | Exit: template includes Files | Files: SKILL.md