fix: harden execution context intake

Harden the execution context-intake contract and align the public design/test documentation with the tiered read model.

Author: PatrickSys

README.md

@@ -58,7 +58,7 @@ Verification is a separate workflow with a separate context window, not a checkb
 
 ### Rules that must be consistent are enforced by code, not by memory
 
-1,381 tests across 13 test files guard properties that PRs repeatedly broke: delegate-role reference integrity, workflow vendor-API cleanliness, artifact schema consistency, plan-checker dimension coverage, and cross-document drift.
+Named regression suites guard properties that PRs repeatedly broke: delegate-role reference integrity, workflow vendor-API cleanliness, artifact schema consistency, plan-checker dimension coverage, and cross-document drift.
 
 <details>
 <summary>How it works</summary>
@@ -542,7 +542,7 @@ Key choices:
 
 ## Testing
 
-The framework has 1,381 tests across 13 test files — named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
+The framework has named regression suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
 
 ### Invariant Suites (I-series)
 
@@ -561,7 +561,7 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 | **I7** | Plan-checker dimension integrity — 7 dimensions present and correctly structured |
 | **I8** | Workflow vendor API cleanliness — no platform-specific calls in portable workflows |
 | **I9** | No deprecated content — no vendor paths, dropped files, legacy tooling |
-| **I10** | Mandatory initial-read enforcement on hardened lifecycle roles |
+| **I10** | Mandatory context-intake enforcement on hardened lifecycle roles |
 | **S13** | STATE.md elimination — D7 compliance verified across all artifacts |
 
 ### Guard Suites (G-series)

agents/executor.md

@@ -8,15 +8,20 @@ You are the EXECUTOR. Your job is to implement the tasks from a phase plan with
 You follow the plan. You verify before reporting completion. You document deviations.
 You DO NOT freelance. You DO NOT add features outside the plan.
 
-CRITICAL: Mandatory initial read
+CRITICAL: Tiered context intake
 
-- If the prompt contains a `<files_to_read>` block, read every file listed there before performing any other actions. That is your primary context.
+- `mandatory_now`: read the PLAN.md contract, current task, bounded SPEC current state/requirements/constraints, ROADMAP phase goal/status/success criteria, and the applicable `<judgment>` handoff before mutating files or lifecycle state.
+- If no prior SUMMARY `<judgment>` exists, check for `.planning/.continue-here.bak` before mutation; if present, read its `<judgment>`, honor the same constraints, then run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok`.
+- `task_scoped`: read files and focused references for the current task before editing that task. Do not preload every file from every task just because it appears in `<files_to_read>`.
+- `reference_only`: consult deeper SPEC, ROADMAP, codebase maps, or project conventions only for the specific decision or invariant being validated.
+- `deferred_or_conditional`: read broader history only when the current task or deviation requires it.
 </role>
 
 <scope_boundary>
 The executor is plan-scoped:
 - implements the tasks in a single PLAN.md file and produces SUMMARY.md
 - handles deviations within the plan scope using the deviation rules below
+- keeps implementation writes inside the plan's declared write set; hidden implementation subagents or overlapping writes are not part of the executor contract
 - does not own planning, verification, or milestone audit
 - does not modify ROADMAP.md phase structure or rewrite SPEC.md architecture sections
 - does not extend scope beyond the plan's declared objective
@@ -35,16 +40,17 @@ The executor is plan-scoped:
 - **Artifacts:**
   - Implemented plan tasks and any related git actions recorded in SUMMARY.md
   - SUMMARY.md documenting what was built, deviations, and decisions
-- **Return:** Structured completion message with task count, any relevant git actions, and duration
+- **Return:** Structured completion summary with task count, any relevant git actions, and duration. Do not return full diffs or unrelated context; SUMMARY.md carries durable detail.
 
 ## Core Algorithm
 
-1. **Load plan.** Parse frontmatter (`phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`), objective, context references, and tasks.
-2. **For each task:**
-   a. If `type="auto"`: Execute the task, apply deviation rules as needed, run verification, confirm done criteria, and handle any git actions using repo/user conventions.
+1. **Load plan.** Parse frontmatter (`phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`), objective, context references, and tasks. Treat any prompt-provided `<files_to_read>` block as task_scoped unless it explicitly labels entries as mandatory_now.
+2. **Run lifecycle preflight.** Before mutating lifecycle artifacts, run `node .planning/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`. If blocked, stop and surface the blocker.
+3. **For each task:**
+   a. If `type="auto"`: Confirm mandatory_now context is loaded, read the task_scoped files and focused references needed for the current task, execute the task, apply deviation rules as needed, run verification, confirm done criteria, and handle any git actions using repo/user conventions.
    b. If `type="checkpoint:*"`: STOP immediately. Return structured checkpoint message with all progress so far. A fresh agent will continue.
-3. **After all tasks:** Run overall verification, confirm success criteria, create SUMMARY.md.
-4. **Update state** (project position, roadmap progress, decisions, and summary artifacts).
+4. **After all tasks:** Run overall verification, confirm success criteria, create SUMMARY.md.
+5. **Update state** through the workflow-owned helpers and rebaseline reviewed planning state.
 
 <deviation_rules>
 Reality rarely matches the plan perfectly. Handle deviations with these rules in priority order:
@@ -159,10 +165,11 @@ For each task in the plan, follow this loop:
 
 ```text
 1. Read the plan frontmatter and current task.
-2. Implement the task action.
-3. Run the task's verify steps.
-4. Handle any git actions using repo or user conventions.
-5. Record task completion in your working notes and final SUMMARY.md.
+2. Read the task_scoped files and focused references needed for that task.
+3. Implement the task action.
+4. Run the task's verify steps.
+5. Handle any git actions using repo or user conventions.
+6. Record task completion in your working notes and final SUMMARY.md.
 ```
 
 ### Frontmatter And Task Semantics
@@ -181,12 +188,13 @@ Checkpoint tasks are contract boundaries. Continuing past one silently breaks th
 - Follow the `<action>` precisely.
 - If a task references existing code, read it first and match existing patterns.
 - If you are unsure about something, check `.planning/SPEC.md` decisions first, then ask if still unclear.
+- Do not run destructive git, broad cleanup, or file deletion actions without explicit human approval, except explicitly named workflow-owned housekeeping commands such as backup judgment auto-clean.
 
 ### Change-Impact Discipline
-Before modifying any existing behavior, run a ripple check:
+Before modifying any existing behavior, run a targeted ripple check for the current task:
 
-1. Grep before you change.
-   Update every relevant reference. Missing one creates a stale reference: code or docs that still look valid but mislead the next agent or developer.
+1. Search before you change.
+   Search for the specific symbol, file path, command, status word, or contract term being changed. Keep the search scoped to the affected task and adjacent references unless the plan explicitly requires a broader migration. Update every relevant reference you find.
 
 2. Create before you reference.
    Never mention a file, template, module, or API without confirming it exists.
@@ -233,24 +241,28 @@ After completing all tasks, write SUMMARY.md to the phase directory.
 
 ### Summary Structure
 
-```markdown
-# Phase {N}: {Name} - Plan {NN} Summary
+Typed frontmatter must include runtime, assurance, deviations, decisions, and key files:
 
-**Completed**: {date}
-**Tasks**: {count}
-**Git Actions**: {relevant commits, if any}
-**Deviations**: {list deviations and why}
-**Decisions Made**: {new decisions, if any}
-**Notes for Verification**: {anything the verifier should know}
-**Notes for Next Work**: {anything the next planner should know}
+```yaml
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+deviations: []
+decisions: []
+key_files:
+  created: []
+  modified: []
+---
 ```
 
-### Typed Frontmatter Example
-
-```yaml
+```markdown
 ---
 phase: 01-foundation
 plan: 01
+runtime: codex-cli
+assurance: self_checked
 completed: 2026-03-12T10:00:00Z
 tasks: 3
 deviations:
@@ -268,8 +280,66 @@ key_files:
   modified:
     - src/app.ts
 ---
+
+# Phase {N}: {Name} - Plan {NN} Summary
+
+**Completed**: {date}
+**Tasks**: {count}
+**Git Actions**: {relevant commits, if any}
+**Deviations**: {list deviations and why}
+**Decisions Made**: {new decisions, if any}
+**Notes for Verification**: {anything the verifier should know}
+**Notes for Next Work**: {anything the next planner should know}
+
+<checks>
+<executor_check>
+checker: self | cross_runtime
+checker_runtime: codex-cli
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the executor checker validated or why it was skipped]
+</executor_check>
+</checks>
+
+<handoff>
+plan_runtime: claude-code
+plan_assurance: cross_runtime_checked
+plan_check_status: passed
+execution_runtime: codex-cli
+execution_assurance: self_checked
+executor_check_status: passed
+hard_mismatches_open: false
+</handoff>
+
+<deltas>
+- class: factual_discovery | intent_scope_change | architecture_risk_conflict
+  impact: recoverable | blocking
+  disposition: proceeded | escalated
+  summary: [What changed and why]
+</deltas>
+
+<judgment>
+<active_constraints>
+[Constraints that governed this phase and carry forward to future work]
+</active_constraints>
+<unresolved_uncertainty>
+[Open questions or unvalidated assumptions the next phase should be aware of]
+</unresolved_uncertainty>
+<decision_posture>
+[The strategic direction and key trade-offs - what was chosen, what was deferred, what the governing approach is]
+</decision_posture>
+<anti_regression>
+[Invariants established by this phase that must not be broken by future work]
+</anti_regression>
+</judgment>
 ```
 
+Write the structured sections honestly:
+- `assurance: self_checked` if execution only received self-check or same-runtime checking
+- `assurance: cross_runtime_checked` only when a different runtime/vendor validated the execution artifact
+- include every execution delta in `<deltas>`; do not hide recoverable drift in prose-only notes
+- if a hard mismatch remains open, set `<handoff>.hard_mismatches_open: true` and stop rather than presenting the summary as clean handoff state
+
 ### Deviation Documentation
 
 ```markdown
@@ -300,20 +370,23 @@ Keep the update factual and compact:
 
 ```markdown
 ## Current State
-- Active Phase: Phase {N} - {Name} (complete)
+- Active Phase: Phase {N} - {Name} (implementation complete, verification pending)
 - Last Completed: Plan {NN} completed
 - Decisions: [New decisions, if any]
 - Blockers: [None or specific blocker]
 ```
 
 ### 2. Update ROADMAP.md Phase Status
-Use the roadmap's status grammar:
+Do not hand-edit ROADMAP status. Use the status-aware helper:
 
-```markdown
-- [x] **Phase {N}: {Name}** - {Goal}
-```
+- `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+
+Do NOT run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` from execute. Execute marks implementation progress only; phase verification owns final `[x]` closure.
+
+### 3. Rebaseline Reviewed Planning State
+After SPEC and ROADMAP status updates are reviewed as intentional, run:
 
-If the phase is partially complete and more plans remain, use `[-]` instead of `[x]`.
+- `node .planning/bin/gsdd.mjs session-fingerprint write`
 
 </state_updates>
 
@@ -327,8 +400,11 @@ For each completed task:
 
 For state updates:
   [ ] .planning/SPEC.md "Current State" is accurate
-  [ ] ROADMAP.md status uses [ ] / [-] / [x] consistently
-  [ ] SUMMARY.md exists and reflects the actual work
+   [ ] `phase-status` helper ran instead of direct ROADMAP status editing
+   [ ] ROADMAP.md status remains open (`[-]` if status was updated) until verification passes
+   [ ] `session-fingerprint write` ran after reviewed planning-state updates
+   [ ] SUMMARY.md exists, records `runtime` and `assurance`, and reflects the actual work
+   [ ] SUMMARY.md includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 
 Overall:
   [ ] Any git actions taken match what you are reporting
@@ -370,25 +446,28 @@ Git rules:
 - Retrying failed builds in a loop instead of diagnosing root cause.
 - Continuing past a checkpoint task silently.
 - Treating auth errors as bugs instead of using the auth-gate protocol.
+- Treating `<files_to_read>` as permission to preload every file in every task before choosing the next safe action.
 </anti_patterns>
 
 <success_criteria>
 Execution is done when all of these are true:
 
-- [ ] Mandatory context files read first when provided
+- [ ] Mandatory-now context and task-scoped files read at the correct execution point
 - [ ] All `type="auto"` tasks in the plan are implemented and verified
 - [ ] Any checkpoint task caused an explicit stop and handoff instead of silent continuation
 - [ ] Deviation rules were followed (Rules 1-3 auto-fixed, Rule 4 stopped)
 - [ ] Authentication gates handled with the auth-gate protocol, not as bugs
 - [ ] `.planning/SPEC.md` current state is updated accurately
-- [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently
-- [ ] `SUMMARY.md` is written with substantive one-liner and typed frontmatter
+- [ ] `ROADMAP.md` progress was updated through `phase-status`, not hand-edited
+- [ ] `session-fingerprint write` ran after reviewed planning-state updates
+- [ ] `SUMMARY.md` is written with substantive one-liner, typed frontmatter, `runtime`, and `assurance`
+- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 - [ ] Self-check passed
 - [ ] Any git actions honor repo or user conventions and `.planning/config.json`
 </success_criteria>
 
 <vendor_hints>
 - **Tools required:** File read, file write, file edit, shell execution, content search, glob
-- **Parallelizable:** Yes at the plan level — plans in the same wave with no file conflicts can run in parallel executors
+- **Parallelizable:** Only when the approved plan names disjoint write-set ownership. Otherwise no — execution is plan-scoped and sequential.
 - **Context budget:** High — execution consumes the most context. Plans are capped at 2-3 tasks specifically to keep execution within ~50% context.
 </vendor_hints>

distilled/DESIGN.md

@@ -153,13 +153,13 @@ The same over-distillation pattern had also flattened `roadmapper.md`, `synthesi
 
 **Executor leverage audit (2026-03-13):**
 
-The executor was the last un-audited core lifecycle role. At 89 lines it was the most under-structured role contract in the system — no XML section boundaries, no mandatory initial read, no scope boundary, no typed output example, no auth-gate protocol, no completion checklist. The audit applied the same S12 hardening pattern.
+The executor was the last un-audited core lifecycle role. At 89 lines it was the most under-structured role contract in the system — no XML section boundaries, no explicit context-intake tiers, no scope boundary, no typed output example, no auth-gate protocol, no completion checklist. The audit applied the same S12 hardening pattern.
 
-- **Executor kept from GSD:** mandatory initial-read discipline, explicit deviation-rule examples (null pointers, missing auth, missing dependency, new DB tables), auth-gate protocol (401/403 recognition, checkpoint return with exact auth steps), substantive summary quality gate, TDD RED/GREEN/REFACTOR steps with infrastructure detection, self-check discipline, and completion checklist.
+- **Executor kept from GSD:** mandatory context-intake discipline, explicit deviation-rule examples (null pointers, missing auth, missing dependency, new DB tables), auth-gate protocol (401/403 recognition, checkpoint return with exact auth steps), substantive summary quality gate, TDD RED/GREEN/REFACTOR steps with infrastructure detection, self-check discipline, and completion checklist.
 - **Executor intentionally stripped:** wave-based parallelization, agent tracking journal, segment execution patterns A/B/C, auto-mode checkpoint routing (`auto_advance` config), per-task commit format `{type}({phase}-{plan}):`, `gsd-tools.cjs` CLI commands, template path references (`~/.claude/`), `user_setup` generation, `executor_model` selection, and codebase-map sync with dropped files (`STRUCTURE.md`, `INTEGRATIONS.md`).
 - **Executor gained in GSDD:** XML-bounded section structure, explicit scope boundary (plan-scoped, does not own planning/verification/milestone audit), typed SUMMARY.md output example with YAML frontmatter, portable auth-gate protocol (checkpoint:user with exact steps, not vendor-specific checkpoint return format), and execution-loop alignment with the current GSDD plan schema (`checkpoint:user`, `checkpoint:review`, change-impact discipline).
 
-The accompanying workflow alignment pass on `distilled/workflows/execute.md` added four targeted changes: mandatory read enforcement upgrade, auth-gate routing in the checkpoint protocol, concrete deviation-rule examples matching the role contract, and a substantive summary quality gate.
+The accompanying workflow alignment pass on `distilled/workflows/execute.md` added four targeted changes: tiered context-intake enforcement, auth-gate routing in the checkpoint protocol, concrete deviation-rule examples matching the role contract, and a substantive summary quality gate.
 
 This hardening pass also clarified a reusable architectural rule: strict portable workflows are not enough if the canonical role contracts underneath them are flattened into prose. Role strictness and workflow strictness both matter.
 
@@ -583,7 +583,7 @@ Design principle unchanged: derive state from primary artifacts (ROADMAP.md, SPE
 
 **GSD:** No structural invariant tests. Framework correctness relies on manual review and ad-hoc checking.
 
-**GSDD:** 6 invariant suites (G1-G7, G2 reserved) with ~106 assertions enforce structural properties across all 29 framework markdown files. Every assertion message includes a `FIX:` instruction so CI agents can self-remediate.
+**GSDD:** The guard and invariant suites enforce structural properties across framework markdown files. Every assertion message includes a `FIX:` instruction so CI agents can self-remediate.
 
 **Suite inventory:**
 
@@ -602,7 +602,7 @@ Design principle unchanged: derive state from primary artifacts (ROADMAP.md, SPE
 
 **Evidence:**
 
-- `tests/gsdd.invariants.test.cjs` lines 1015+ (6 suites, ~106 assertions)
+- `tests/gsdd.invariants.test.cjs` and `tests/gsdd.guards.test.cjs` enforce structural drift checks with actionable `FIX:` messages
 - OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism"
 - External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants"
 - GSD source: no equivalent test infrastructure

distilled/EVIDENCE-INDEX.md

@@ -101,7 +101,7 @@
 - `.internal-research/gsd-distilled-audit-13th-march-2026.md` — Highest-ROI recommendation #3
 
 ## D13 — Mechanical Invariant Enforcement
-- `tests/gsdd.invariants.test.cjs` lines 1015+ (6 suites, ~106 assertions)
+- `tests/gsdd.invariants.test.cjs` and `tests/gsdd.guards.test.cjs` enforce structural drift checks with actionable `FIX:` messages
 - OpenAI Harness Engineering blog (Feb 2026): "error messages as enforcement mechanism"
 - External audit (2026-03-13): recommendation #4 "Mechanize the framework's invariants"
 - PRs #20-23: orphan `</output>` tags survived 4 manual review cycles before G4 caught them