recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026
@@ -237,11 +237,13 @@ Use `openspec/plan/README.md` as the operational runbook and `openspec/plan/PLAN
 
 Default quick flow:
 1. Create/maintain `openspec/plan/<plan-slug>/`.
-2. Keep role `tasks.md` files current (`planner`, `architect`, `critic`, `executor`, `writer`, `verifier`).
-3. Keep checklist headings visible: `## 1. Spec`, `## 2. Tests`, `## 3. Implementation`, `## 4. Checkpoints`, plus a final cleanup section (`## 5. Cleanup` or `## 6. Cleanup`).
-4. Update checkboxes continuously while work progresses.
-5. Execute from approved `planner/plan.md` with role ownership.
-6. Verify with evidence before archive/finish.
+2. Create/maintain `openspec/plan/<plan-slug>/open-questions.md`.
+3. Keep `open-questions.md` current; when Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it there as an unchecked `- [ ]` item.
+4. Keep role `tasks.md` files current (`planner`, `architect`, `critic`, `executor`, `writer`, `verifier`).
+5. Keep checklist headings visible: `## 1. Spec`, `## 2. Tests`, `## 3. Implementation`, `## 4. Checkpoints`, plus a final cleanup section (`## 5. Cleanup` or `## 6. Cleanup`).
+6. Update checkboxes continuously while work progresses.
+7. Execute from approved `planner/plan.md` with role ownership.
+8. Verify with evidence before archive/finish.
 
 Helper sub-branch exception:
 - When a helper branch targets another `agent/*` owner branch, implementation is allowed in helper lanes, but OpenSpec change/spec/tasks artifacts stay owned by the owner branch.
@@ -279,6 +281,8 @@ OMX completion policy: when a task is done, the agent must commit the task chang
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
+**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+
 **OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.

@@ -0,0 +1,20 @@
+# Proposal: record codex open questions in plan workspace
+
+## Why
+
+- The repo contract keeps planning artifacts in-repo, but unresolved questions can still disappear into chat-only notes.
+- The user wants a durable `plans/open-questions` rule that behaves the same way across repos.
+- The current plan scaffold does not create an `open-questions.md` file, so the contract has no concrete landing zone.
+
+## What Changes
+
+- [ ] Add an `open-questions.md` requirement to the live repo contract and reusable multiagent template.
+- [ ] Add committed `openspec/plan` guidance describing how open questions should be recorded.
+- [ ] Update the plan-workspace scaffold to create `open-questions.md` and point roles/coordinators at it.
+- [ ] Seed this task's plan workspace with the exact three joined-session questions from the user.
+
+## Impact
+
+- Scope: AGENTS contract, reusable template, OpenSpec plan docs, plan scaffold.
+- Risks: Low; wording drift between live and templated docs if one surface is missed.
+- Dependencies: `scripts/openspec/init-plan-workspace.sh` and `templates/scripts/openspec/init-plan-workspace.sh` must stay in sync.
@@ -0,0 +1,23 @@
+# Capability Spec: plan-open-questions
+
+## ADDED Requirements
+
+### Requirement: Plan workspaces capture unresolved questions
+
+Plan workspaces SHALL provide `open-questions.md` for unresolved questions that must survive chat history.
+
+#### Scenario: Agent hits a branching question during planning
+
+- **WHEN** Codex or Claude reaches an unresolved question, branching decision, or blocker during plan-driven work
+- **THEN** it records that question in `openspec/plan/<plan-slug>/open-questions.md`
+- **AND** the question appears as an unchecked checklist item until resolved
+
+### Requirement: Guardex contract points to the same question log
+
+The repo contract SHALL route unresolved questions into the active plan workspace instead of chat-only notes.
+
+#### Scenario: Multi-agent or plan-driven work needs durable questions
+
+- **WHEN** the repo contract describes collaboration, planning, or handoff rules
+- **THEN** it points agents to `openspec/plan/<plan-slug>/open-questions.md`
+- **AND** the plan scaffold creates that file by default
@@ -0,0 +1,29 @@
+# Tasks
+
+## 1. Contract
+
+- [x] 1.1 Update `AGENTS.md` to require `openspec/plan/<plan-slug>/open-questions.md` for unresolved questions.
+- [x] 1.2 Update `templates/AGENTS.multiagent-safety.md` with the same open-questions rule.
+
+## 2. OpenSpec Plan Docs
+
+- [x] 2.1 Add `openspec/plan/README.md` with the shared open-questions workflow.
+- [x] 2.2 Add `openspec/plan/PLANS.md` with planner-specific question discipline.
+
+## 3. Scaffold
+
+- [x] 3.1 Update `scripts/openspec/init-plan-workspace.sh` to create and reference `open-questions.md`.
+- [x] 3.2 Update `templates/scripts/openspec/init-plan-workspace.sh` to stay in template parity.
+- [x] 3.3 Regenerate this task's plan workspace and seed the user-provided questions.
+
+## 4. Verification
+
+- [x] 4.1 Read the final diff to confirm the live contract, template contract, and scaffold all mention `open-questions.md`.
+- [x] 4.2 Run the plan-workspace scaffold for this task and confirm `open-questions.md` is created.
+- [x] 4.3 Run focused shell verification for modified docs/scripts and record results.
+
+## 5. Cleanup
+
+- [ ] 5.1 Finish the branch with `gx branch finish --branch agent/codex/record-codex-open-questions-in-plan-work-2026-04-22-18-25 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 5.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 5.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
@@ -0,0 +1,23 @@
+# Planner Contract
+
+`planner/plan.md` is the durable narrative for the active `openspec/plan/<plan-slug>/` workspace.
+
+## Keep these in sync
+
+- `summary.md` for scope and current status
+- `phases.md` for session-sized execution slices
+- `checkpoints.md` for timestamped planning handoffs
+- `open-questions.md` for unresolved decisions that must survive chat
+
+## Question discipline
+
+Do not bury unresolved planning questions in chat transcripts or one-off handoff notes.
+When a question affects scope, sequencing, safety, or implementation shape, add it to `open-questions.md` as an unchecked `- [ ]` item.
+
+Questions should be:
+
+- concrete
+- decision-shaped
+- easy to verify once answered
+
+When a question is resolved, either check it off with the answer inline or move the final decision into `planner/plan.md` and leave a short resolution note in `open-questions.md`.
@@ -0,0 +1,32 @@
+# OpenSpec Plan Workspaces
+
+Use `openspec/plan/<plan-slug>/` for durable planning artifacts that must survive chat history.
+
+## Required shared files
+
+- `summary.md`
+- `checkpoints.md`
+- `phases.md`
+- `open-questions.md`
+- `coordinator-prompt.md`
+- `kickoff-prompts.md` when wave splitting is needed
+
+## Open questions rule
+
+When Codex or Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item.
+
+Example checklist:
+
+- [ ] Should finish override be allowed when joined sessions are active, and if yes what exact flag/guard text should be used?
+- [ ] Do we want join-mode sessions to be persisted only by PID or by a stable explicit session id generated at join time?
+- [ ] Should lock registry entries carry joined session identity in this first iteration, or deferred to a follow-up change?
+
+Avoid vague notes like `- [ ] Figure out join mode somehow`.
+
+Close questions in place with the answer, linked evidence, or a checked item once the decision is made.
+
+## Minimum role hygiene
+
+- Keep role `tasks.md` checklists current.
+- Record joined-agent handoffs in the relevant role workspace.
+- Push unresolved plan questions into `open-questions.md` instead of chat-only notes.
@@ -50,17 +50,38 @@ Chronological checkpoint log for all roles.
 CPTEOF
 fi
 
+if [[ ! -f "$PLAN_DIR/open-questions.md" ]]; then
+  cat > "$PLAN_DIR/open-questions.md" <<OPENQUESTIONSEOF
+# Open Questions: ${PLAN_SLUG}
+
+Capture unresolved plan questions here as unchecked checklist items.
+Keep each item concrete, decision-shaped, and easy to close with evidence.
+
+- [ ] Add the next unresolved question here.
+OPENQUESTIONSEOF
+fi
+
 if [[ ! -f "$PLAN_DIR/README.md" ]]; then
   {
     echo "# Plan Workspace: ${PLAN_SLUG}"
     echo
     echo "This folder stores durable planning artifacts before implementation changes."
     echo
+    echo "## Shared files"
+    echo "- \`summary.md\`"
+    echo "- \`checkpoints.md\`"
+    echo "- \`phases.md\`"
+    echo "- \`open-questions.md\`"
+    echo "- \`coordinator-prompt.md\`"
+    echo "- \`kickoff-prompts.md\`"
+    echo
     echo "## Role folders"
     for role in "${ROLES[@]}"; do
       echo "- \`${role}/\`"
     done
     echo
+    echo "When Codex or Claude hits an unresolved question that should survive chat, add it to \`open-questions.md\` as an unchecked \`- [ ]\` item."
+    echo
     echo "Each role folder contains OpenSpec-style artifacts:"
     echo "- \`.openspec.yaml\`"
     echo "- \`proposal.md\`"
@@ -85,15 +106,17 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc
 
 - \`openspec/plan/${PLAN_SLUG}/summary.md\`
 - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\`
+- \`openspec/plan/${PLAN_SLUG}/open-questions.md\`
 - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\`
 - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier
 
 ## Coordinator responsibilities
 
 1. Keep checkpoints current in each role \`tasks.md\` and root \`checkpoints.md\`.
-2. Ensure each role has explicit acceptance criteria and verification evidence.
-3. Prevent implementation from starting before planning gates are complete.
-4. Keep handoffs concise: files changed, behavior touched, verification output, risks.
+2. Route unresolved questions and branching decisions into \`open-questions.md\`.
+3. Ensure each role has explicit acceptance criteria and verification evidence.
+4. Prevent implementation from starting before planning gates are complete.
+5. Keep handoffs concise: files changed, behavior touched, verification output, risks.
 
 ## Wave-splitting decision (optional)
 
@@ -109,6 +132,7 @@ If wave splitting is not needed, keep execution under a single owner with normal
 
 - All role checkpoints required for planning are done.
 - Execution lanes (if any) have clear ownership boundaries.
+- \`open-questions.md\` captures unresolved decisions that still need answers.
 - Verification plan and rollback expectations are explicit and testable.
 COORDPROMPTEOF
 fi
@@ -431,6 +455,7 @@ EXCCPTEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -467,6 +492,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -503,6 +529,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -539,6 +566,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -575,6 +603,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -611,6 +640,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 
@@ -647,6 +677,7 @@ TASKEOF
 
 - [ ] 5.1 Owner recorded this lane before edits.
 - [ ] 5.2 Record joined agents / handoffs, or mark \`N/A\` when solo.
+- [ ] 5.3 Record unresolved plan questions in \`../open-questions.md\`, or mark \`N/A\` when none.
 
 ## 6. Cleanup
 

@@ -25,6 +25,8 @@ OMX completion policy: when a task is done, the agent must commit the task chang
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
+**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+
 **OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.