Enforce rulespec creation with plan_write for new plans

Solves the tautology problem where the LLM would write invariants after
implementation, making them match what was done rather than constrain it.

Changes:
- plan_write now accepts 'rulespec' parameter
- New plans REQUIRE rulespec (fails with helpful error if missing)
- Plan updates don't require rulespec (backward compatible)
- Rulespec is parsed, validated, and written atomically with plan
- Updated system prompt with clear examples for new vs update
- Updated tool definition schema
- Updated all affected tests

New flow: task → plan+rulespec → user reviews BOTH → approve → implement

crates/g3-core/src/prompts.rs

@@ -58,8 +58,10 @@ Short description for providers without native calling specs:
   - Example: {\"tool\": \"plan_read\", \"args\": {}}
 
 - **plan_write**: Create or update the Plan with YAML content
-  - Format: {\"tool\": \"plan_write\", \"args\": {\"plan\": \"plan_id: my-plan\\nitems: [...]\"}}
-  - Example: {\"tool\": \"plan_write\", \"args\": {\"plan\": \"plan_id: feature-x\\nitems:\\n  - id: I1\\n    description: Add feature\\n    state: todo\\n    touches: [src/lib.rs]\\n    checks:\\n      happy: {desc: Works, target: lib}\\n      negative:\\n        - {desc: Errors, target: lib}\\n      boundary:\\n        - {desc: Edge, target: lib}\"}}
+  - Format: {\"tool\": \"plan_write\", \"args\": {\"plan\": \"plan_id: my-plan\\nitems: [...]\", \"rulespec\": \"claims: [...]\\npredicates: [...]\"}}
+  - For NEW plans, rulespec is REQUIRED. For updates, it's optional.
+  - Example (new plan): {\"tool\": \"plan_write\", \"args\": {\"plan\": \"plan_id: feature-x\\nitems:\\n  - id: I1\\n    description: Add feature\\n    state: todo\\n    touches: [src/lib.rs]\\n    checks:\\n      happy: {desc: Works, target: lib}\\n      negative:\\n        - {desc: Errors, target: lib}\\n      boundary:\\n        - {desc: Edge, target: lib}\", \"rulespec\": \"claims:\\n  - name: feature\\n    selector: feature.done\\npredicates:\\n  - claim: feature\\n    rule: exists\\n    source: task_prompt\"}}
+  - Example (update): {\"tool\": \"plan_write\", \"args\": {\"plan\": \"plan_id: feature-x\\nitems:\\n  - id: I1\\n    state: done\\n    evidence: [src/lib.rs:42]\\n    notes: Implemented\"}}
 
 - **plan_approve**: Approve the current plan revision (called by user)
   - Format: {\"tool\": \"plan_approve\", \"args\": {}}

crates/g3-core/src/tool_definitions.rs

@@ -199,13 +199,17 @@ fn create_core_tools() -> Vec<Tool> {
 
     tools.push(Tool {
         name: "plan_write".to_string(),
-        description: "Create or update the Plan for this session. Provide plan as YAML with plan_id and items array. See system prompt for full schema (items need: id, description, state, touches, checks with happy/negative/boundary). Evidence and notes required when marking done.".to_string(),
+        description: "Create or update the Plan for this session. For NEW plans, you MUST provide both 'plan' and 'rulespec' arguments. The rulespec defines invariants (constraints that must/must not hold) extracted from the task and memory. For plan UPDATES, rulespec is optional.".to_string(),
         input_schema: json!({
             "type": "object",
             "properties": {
                 "plan": {
                     "type": "string",
                     "description": "The plan as YAML. Must include plan_id and items array."
+                },
+                "rulespec": {
+                    "type": "string",
+                    "description": "The rulespec as YAML with claims and predicates. REQUIRED for new plans, optional for updates. Defines invariants from task_prompt and memory."
                 }
             },
             "required": ["plan"]

crates/g3-core/src/tools/plan.rs

@@ -20,7 +20,7 @@ use crate::ToolCall;
 
 use super::executor::ToolContext;
 
-use super::invariants::{format_envelope_markdown, format_rulespec_markdown, get_envelope_path, get_rulespec_path, read_envelope, read_rulespec};
+use super::invariants::{format_envelope_markdown, format_rulespec_markdown, get_envelope_path, get_rulespec_path, read_envelope, read_rulespec, write_rulespec, Rulespec};
 
 // ============================================================================
 // Plan Schema
@@ -845,14 +845,57 @@ pub async fn execute_plan_write<W: UiWriter>(
         None => return Ok("❌ Missing 'plan' argument. Provide the plan as YAML.".to_string()),
     };
 
+    // Get optional rulespec content from args
+    let rulespec_yaml = tool_call.args.get("rulespec").and_then(|v| v.as_str());
+
     // Parse the YAML
     let mut plan: Plan = match serde_yaml::from_str(plan_yaml) {
         Ok(p) => p,
         Err(e) => return Ok(format!("❌ Invalid plan YAML: {}", e)),
     };
 
-    // Load existing plan to preserve approved_revision and increment revision
-    if let Some(existing) = read_plan(session_id)? {
+    // Load existing plan to check if this is a new plan or an update
+    let existing_plan = read_plan(session_id)?;
+    let is_new_plan = existing_plan.is_none();
+
+    // For NEW plans, rulespec is REQUIRED
+    // This prevents the tautology problem where invariants are written after implementation
+    if is_new_plan && rulespec_yaml.is_none() {
+        return Ok("❌ Missing 'rulespec' argument. New plans MUST include a rulespec with invariants.\n\n\
+            The rulespec defines constraints that MUST or MUST NOT hold, extracted from:\n\
+            - task_prompt: What the user explicitly requires\n\
+            - memory: Persistent rules from workspace memory\n\n\
+            Example rulespec:\n\
+            ```yaml\n\
+            claims:\n\
+              - name: feature_capabilities\n\
+                selector: \"feature.capabilities\"\n\
+            predicates:\n\
+              - claim: feature_capabilities\n\
+                rule: contains\n\
+                value: \"required_feature\"\n\
+                source: task_prompt\n\
+                notes: \"User explicitly requested this\"\n\
+            ```".to_string());
+    }
+
+    // Parse and validate rulespec if provided
+    let rulespec: Option<Rulespec> = if let Some(yaml) = rulespec_yaml {
+        match serde_yaml::from_str(yaml) {
+            Ok(r) => {
+                let rs: Rulespec = r;
+                if let Err(e) = rs.validate() {
+                    return Ok(format!("❌ Invalid rulespec: {}", e));
+                }
+                Some(rs)
+            }
+            Err(e) => return Ok(format!("❌ Invalid rulespec YAML: {}", e)),
+        }
+    } else {
+        None
+    };
+
+    if let Some(existing) = existing_plan {
         // Preserve approved_revision from existing plan
         plan.approved_revision = existing.approved_revision;
         // Increment revision
@@ -888,17 +931,23 @@ pub async fn execute_plan_write<W: UiWriter>(
         return Ok(format!("❌ Failed to write plan: {}", e));
     }
 
+    // Write the rulespec if provided (atomically with plan)
+    if let Some(ref rs) = rulespec {
+        if let Err(e) = write_rulespec(session_id, rs) {
+            return Ok(format!("❌ Failed to write rulespec: {}", e));
+        }
+    }
+
     // Display the plan in compact format
     let plan_path = get_plan_path(session_id);
     let plan_path_str = plan_path.to_string_lossy().to_string();
     let yaml = serde_yaml::to_string(&plan)?;
     ctx.ui_writer.print_plan_compact(Some(&yaml), Some(&plan_path_str), true);
 
-    // Read and format rulespec if it exists
-    let rulespec_section = match read_rulespec(session_id) {
-        Ok(Some(rulespec)) => format_rulespec_markdown(&rulespec),
-        Ok(None) => "\n_No rulespec generated._\n".to_string(),
-        Err(_) => "\n_No rulespec generated._\n".to_string(),
+    // Format rulespec section - use provided rulespec or read from disk
+    let rulespec_section = match rulespec.as_ref().or(read_rulespec(session_id).ok().flatten().as_ref()) {
+        Some(rs) => format_rulespec_markdown(rs),
+        None => "\n_No rulespec defined._\n".to_string(),
     };
 
     // Read and format envelope if it exists

crates/g3-core/tests/stream_completion_characterization_test.rs

@@ -621,6 +621,15 @@ items:
       boundary:
         - desc: Edge cases
           target: test::module"#
+                ,
+                "rulespec": r#"claims:
+  - name: test_feature
+    selector: test.done
+predicates:
+  - claim: test_feature
+    rule: exists
+    source: task_prompt
+    notes: Test invariant"#
             }),
         };
         let write_result = agent.execute_tool(&write_call).await.unwrap();

crates/g3-core/tests/tool_execution_roundtrip_test.rs

@@ -425,6 +425,14 @@ items:
       boundary:
         - desc: Edge
           target: test"#
+                ,
+                "rulespec": r#"claims:
+  - name: test_feature
+    selector: test.done
+predicates:
+  - claim: test_feature
+    rule: exists
+    source: task_prompt"#
             }),
         );
         
@@ -479,6 +487,14 @@ items:
       happy: {desc: Works, target: test}
       negative: [{desc: Errors, target: test}]
       boundary: [{desc: Edge, target: test}]"#
+                ,
+                "rulespec": r#"claims:
+  - name: approval_test
+    selector: test.approved
+predicates:
+  - claim: approval_test
+    rule: exists
+    source: task_prompt"#
             }),
         );
         agent.execute_tool(&write_call).await.unwrap();