Sync installed jobs with source after deepwork install

Running `deepwork install` synced several updates from source:
- Added browser automation capability guidance to job definition steps
- Added supplemental_file_references.md documentation
- Updated generated commands in .claude/ and .gemini/

Author: claude

.claude/commands/deepwork_policy.define.md

@@ -88,6 +88,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -118,6 +134,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -127,6 +144,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -198,7 +216,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies

.deepwork/jobs/deepwork_policy/steps/define.md

@@ -56,6 +56,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -86,6 +102,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -95,6 +112,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -166,7 +184,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies

.gemini/commands/deepwork_jobs/learn.toml

@@ -174,7 +174,42 @@ The AGENTS.md file captures project-specific knowledge that helps future agent r
    - This keeps AGENTS.md in sync as the codebase evolves
    - Pattern: "See `path/to/file.ext` for [description]"
 
-3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format.
+3. **AGENTS.md structure**:
+
+```markdown
+# Project Context for [Job Name]
+
+## Codebase Structure
+
+<!-- Reference files rather than duplicating content -->
+- Project structure: See `README.md` for overview
+- API documentation: See `docs/api.md`
+- Configuration: See `config/README.md`
+
+## Conventions
+
+### Naming Conventions
+- [Convention]: See example in `path/to/example.ext:LINE`
+
+### File Organization
+- [Pattern]: Reference `path/to/pattern/`
+
+## Job-Specific Context
+
+### [Job Name]
+
+#### [Step Name]
+- [Learning]: Reference `relevant/file.ext`
+- [Context]: [Brief explanation with file reference]
+
+## Known Issues and Workarounds
+
+- [Issue]: [Workaround with file reference if applicable]
+
+## Last Updated
+- Date: [YYYY-MM-DD]
+- From conversation about: [Brief description]
+```
 
 4. **Writing entries**
    - Be concise but specific
@@ -196,14 +231,36 @@ If instruction files were modified:
      changes: "Improved [step] instructions based on execution learnings: [brief description]"
    ```
 
-### Step 7: Sync and Relay Instructions
+### Step 7: Sync and Summarize
 
 1. **Run deepwork sync** (if instructions were modified)
    ```bash
    deepwork sync
    ```
 
-2. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
+2. **Create learning_summary.md** in the working folder:
+   ```markdown
+   # Learning Summary
+
+   ## Job Analyzed
+   - Job: [job_name]
+   - Steps executed: [list of steps]
+
+   ## Generalizable Improvements Made
+   - [Step]: [What was improved]
+
+   ## Bespoke Learnings Captured
+   - Location: [path to AGENTS.md]
+   - Entries added: [list of entries]
+
+   ## Files Modified
+   - [List of files changed]
+
+   ## Recommendations
+   - [Any additional suggestions]
+   ```
+
+3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
 
 ## File Reference Patterns
 
@@ -234,6 +291,7 @@ When adding entries to AGENTS.md, prefer these patterns:
 - AGENTS.md created/updated with bespoke learnings
 - File references used instead of duplicating content
 - AGENTS.md is in the correct working folder
+- learning_summary.md documents all changes
 - When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>`
 
 ## Example Dialog
@@ -293,7 +351,7 @@ I found the following job executions:
 
 **Summary**
 
-Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated commands, type 'exit' then run 'claude --resume'.
+Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'.
 ```
 
 ## Handling Edge Cases
@@ -345,7 +403,7 @@ All work for this job should be done on a dedicated work branch:
 ## Output Requirements
 
 Create the following output(s):
-- `AGENTS.md`
+- `learning_summary.md`
 
 Ensure all outputs are:
 - Well-formatted and complete
@@ -359,7 +417,7 @@ After completing this step:
 
 2. **Inform the user**:
    - The learn command is complete
-   - Outputs created: AGENTS.md
+   - Outputs created: learning_summary.md
    - This command can be run again anytime to make further changes
 
 ## Command Complete

.gemini/commands/deepwork_policy/define.toml

@@ -93,6 +93,22 @@ If there are files that, when also changed, mean the policy shouldn't fire:
   - Trigger: `src/auth/**/*`
   - Safety: `SECURITY.md`, `docs/security_review.md`
 
+### Step 3b: Choose the Comparison Mode (Optional)
+
+The `compare_to` field controls what baseline is used when detecting "changed files":
+
+**Options:**
+- `base` (default) - Compares to the base of the current branch (merge-base with main/master). This is the most common choice for feature branches, as it shows all changes made on the branch.
+- `default_tip` - Compares to the current tip of the default branch (main/master). Useful when you want to see the difference from what's currently in production.
+- `prompt` - Compares to the state at the start of each prompt. Useful for policies that should only fire based on changes made during a single agent response.
+
+**When to use each:**
+- **base**: Best for most policies. "Did this branch change config files?" → trigger docs review
+- **default_tip**: For policies about what's different from production/main
+- **prompt**: For policies that should only consider very recent changes within the current session
+
+Most policies should use the default (`base`) and don't need to specify `compare_to`.
+
 ### Step 4: Write the Instructions
 
 Create clear, actionable instructions for what the agent should do when the policy fires.
@@ -123,6 +139,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
   safety: "[glob pattern]"   # optional, or array
+  compare_to: "base"         # optional: "base" (default), "default_tip", or "prompt"
   instructions: |
     [Multi-line instructions for the agent...]
 ```
@@ -132,6 +149,7 @@ Create or update `.deepwork.policy.yml` in the project root.
 - name: "[Friendly name for the policy]"
   trigger: "[glob pattern]"
   safety: "[glob pattern]"
+  compare_to: "base"         # optional
   instructions_file: "path/to/instructions.md"
 ```
 
@@ -203,7 +221,10 @@ Create or update this file at the project root with the new policy entry.
 ## Context
 
 Policies are evaluated automatically when you finish working on a task. The system:
-1. Tracks which files you changed during the session
+1. Determines which files have changed based on each policy's `compare_to` setting:
+   - `base` (default): Files changed since the branch diverged from main/master
+   - `default_tip`: Files different from the current main/master branch
+   - `prompt`: Files changed since the last prompt submission
 2. Checks if any changes match policy trigger patterns
 3. Skips policies where safety patterns also matched
 4. Prompts you with instructions for any triggered policies