feat: export core Hermes skills

.gitignore

@@ -0,0 +1,7 @@
+skills/.curator_backups/
+skills/.hub/
+skills/.archive/
+skills/.usage.json
+skills/.usage.json.lock
+skills/.bundled_manifest
+skills/.curator_state

README.md

@@ -1,3 +1,10 @@
 # hermes-skills
 
-Public export of Hermes skills used by 小Maggie
+Public export of Hermes skills used by 小Maggie.
+
+## Structure
+- `skills/` — exported skill directories and linked reference/template/script files.
+
+## Notes
+- Exported from local Hermes profile.
+- Skills may contain workflow-specific conventions and environment assumptions.

skills/autonomous-ai-agents/DESCRIPTION.md

@@ -0,0 +1,3 @@
+---
+description: Skills for spawning and orchestrating autonomous AI coding agents and multi-agent workflows — running independent agent processes, delegating tasks, and coordinating parallel workstreams.
+---

skills/autonomous-ai-agents/ai-coding-agents/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ai-coding-agents
+description: "Delegate coding to external AI CLI agents (Claude Code, Codex, OpenCode). Shared orchestration patterns, tool selection, PTY handling."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Coding-Agent, Claude, Codex, OpenAI, OpenCode, Autonomous, PTY, Delegation]
+    related_skills: [hermes-agent]
+---
+
+# AI Coding Agents — Orchestration Guide
+
+Delegate coding tasks to external autonomous coding agent CLIs via the Hermes terminal. All three tools follow the same orchestration patterns; pick based on what's installed and the user's preference.
+
+## Tool Selection
+
+| Tool | Provider | Install | Best For |
+|------|----------|---------|----------|
+| **Claude Code** | Anthropic | `npm install -g @anthropic-ai/claude-code` | Complex multi-file refactoring, deep reasoning, MCP integration |
+| **Codex** | OpenAI | `npm install -g @openai/codex` | Fast feature implementation, batch issue fixing |
+| **OpenCode** | Multi-provider | `npm i -g opencode-ai@latest` | Provider-agnostic work, cost optimization |
+
+## Shared Orchestration Patterns
+
+### One-Shot (Preferred for most tasks)
+
+All three tools support non-interactive one-shot execution — the cleanest integration:
+
+```bash
+# Claude Code
+claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10
+
+# Codex
+codex exec 'Add dark mode toggle to settings'
+
+# OpenCode
+opencode run 'Add retry logic to API calls and update tests'
+```
+
+### Interactive / Background (Multi-turn sessions)
+
+For iterative work, run in background with PTY:
+
+```bash
+# All tools require pty=true for interactive mode
+terminal(command="<tool> ...", workdir="~/project", background=true, pty=true)
+# Monitor with process(action="poll"|"log")
+# Send input with process(action="submit", data="...")
+```
+
+### PR Review
+
+```bash
+# Claude Code
+claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10
+
+# Codex
+codex exec 'Review PR #42. git diff origin/main...origin/pr/42'
+
+# OpenCode
+opencode pr 42
+```
+
+### Parallel Tasks
+
+All three support running multiple instances in separate workdirs/worktrees:
+
+```bash
+terminal(command="<tool> 'Fix issue #78'", workdir="/tmp/issue-78", background=true, pty=true)
+terminal(command="<tool> 'Fix issue #99'", workdir="/tmp/issue-99", background=true, pty=true)
+```
+
+## Critical Rules
+
+1. **Always use `workdir`** — scope the agent to the right project
+2. **Set turn limits** for one-shot mode (prevents runaway loops)
+3. **Use `pty=true`** for interactive sessions — all three are TUI apps
+4. **Monitor progress** with `process(action="poll"|"log")` — don't kill slow sessions
+5. **Git repo required** — all three need a git directory. Use `mktemp -d && git init` for scratch work
+6. **Clean up** background sessions when done
+
+## Tool-Specific References
+
+Detailed CLI flags, session management, and advanced features for each tool:
+
+- `references/claude-code.md` — Claude Code: print mode deep dive, tmux orchestration, hooks, MCP, subagents, settings hierarchy
+- `references/codex.md` — Codex: exec flags, full-auto vs yolo, worktree patterns, auth (OAuth vs API key)
+- `references/opencode.md` — OpenCode: run vs interactive TUI, session resumption, provider selection, PR review

skills/autonomous-ai-agents/ai-coding-agents/references/claude-code.md

@@ -0,0 +1,745 @@
+---
+name: claude-code
+description: "Delegate coding to Claude Code CLI (features, PRs)."
+version: 2.2.0
+author: Hermes Agent + Teknium
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Coding-Agent, Claude, Anthropic, Code-Review, Refactoring, PTY, Automation]
+    related_skills: [codex, hermes-agent, opencode]
+---
+
+# Claude Code — Hermes Orchestration Guide
+
+Delegate coding tasks to [Claude Code](https://code.claude.com/docs/en/cli-reference) (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.
+
+## Prerequisites
+
+- **Install:** `npm install -g @anthropic-ai/claude-code`
+- **Auth:** run `claude` once to log in (browser OAuth for Pro/Max, or set `ANTHROPIC_API_KEY`)
+- **Console auth:** `claude auth login --console` for API key billing
+- **SSO auth:** `claude auth login --sso` for Enterprise
+- **Check status:** `claude auth status` (JSON) or `claude auth status --text` (human-readable)
+- **Health check:** `claude doctor` — checks auto-updater and installation health
+- **Version check:** `claude --version` (requires v2.x+)
+- **Update:** `claude update` or `claude upgrade`
+
+## Two Orchestration Modes
+
+Hermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.
+
+### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)
+
+Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
+
+```
+terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)
+```
+
+**When to use print mode:**
+- One-shot coding tasks (fix a bug, add a feature, refactor)
+- CI/CD automation and scripting
+- Structured data extraction with `--json-schema`
+- Piped input processing (`cat file | claude -p "analyze this"`)
+- Any task where you don't need multi-turn conversation
+
+**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.
+
+### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions
+
+Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. **Requires tmux orchestration.**
+
+```
+# Start a tmux session
+terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")
+
+# Launch Claude Code inside it
+terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")
+
+# Wait for startup, then send your task
+# (after ~3-5 seconds for the welcome screen)
+terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")
+
+# Monitor progress by capturing the pane
+terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")
+
+# Send follow-up tasks
+terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")
+
+# Exit when done
+terminal(command="tmux send-keys -t claude-work '/exit' Enter")
+```
+
+**When to use interactive mode:**
+- Multi-turn iterative work (refactor → review → fix → test cycle)
+- Tasks requiring human-in-the-loop decisions
+- Exploratory coding sessions
+- When you need to use Claude's slash commands (`/compact`, `/review`, `/model`)
+
+## PTY Dialog Handling (CRITICAL for Interactive Mode)
+
+Claude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:
+
+### Dialog 1: Workspace Trust (first visit to a directory)
+```
+❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
+  2. No, exit
+```
+**Handling:** `tmux send-keys -t <session> Enter` — default selection is correct.
+
+### Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
+```
+❯ 1. No, exit                    ← DEFAULT (WRONG choice!)
+  2. Yes, I accept
+```
+**Handling:** Must navigate DOWN first, then Enter:
+```
+tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
+```
+
+### Robust Dialog Handling Pattern
+```
+# Launch with permissions bypass
+terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions \"your task\"' Enter")
+
+# Handle trust dialog (Enter for default "Yes")
+terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")
+
+# Handle permissions dialog (Down then Enter for "Yes, I accept")
+terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")
+
+# Now wait for Claude to work
+terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")
+```
+
+**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use `--dangerously-skip-permissions`.
+
+## CLI Subcommands
+
+| Subcommand | Purpose |
+|------------|---------|
+| `claude` | Start interactive REPL |
+| `claude "query"` | Start REPL with initial prompt |
+| `claude -p "query"` | Print mode (non-interactive, exits when done) |
+| `cat file \| claude -p "query"` | Pipe content as stdin context |
+| `claude -c` | Continue the most recent conversation in this directory |
+| `claude -r "id"` | Resume a specific session by ID or name |
+| `claude auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |
+| `claude auth status` | Check login status (returns JSON; `--text` for human-readable) |
+| `claude mcp add <name> -- <cmd>` | Add an MCP server |
+| `claude mcp list` | List configured MCP servers |
+| `claude mcp remove <name>` | Remove an MCP server |
+| `claude agents` | List configured agents |
+| `claude doctor` | Run health checks on installation and auto-updater |
+| `claude update` / `claude upgrade` | Update Claude Code to latest version |
+| `claude remote-control` | Start server to control Claude from claude.ai or mobile app |
+| `claude install [target]` | Install native build (stable, latest, or specific version) |
+| `claude setup-token` | Set up long-lived auth token (requires subscription) |
+| `claude plugin` / `claude plugins` | Manage Claude Code plugins |
+| `claude auto-mode` | Inspect auto mode classifier configuration |
+
+## Print Mode Deep Dive
+
+### Structured JSON Output
+```
+terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)
+```
+
+Returns a JSON object with:
+```json
+{
+  "type": "result",
+  "subtype": "success",
+  "result": "The analysis text...",
+  "session_id": "75e2167f-...",
+  "num_turns": 3,
+  "total_cost_usd": 0.0787,
+  "duration_ms": 10276,
+  "stop_reason": "end_turn",
+  "terminal_reason": "completed",
+  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
+  "modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
+}
+```
+
+**Key fields:** `session_id` for resumption, `num_turns` for agentic loop count, `total_cost_usd` for spend tracking, `subtype` for success/error detection (`success`, `error_max_turns`, `error_budget`).
+
+### Streaming JSON Output
+For real-time token streaming, use `stream-json` with `--verbose`:
+```
+terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)
+```
+
+Returns newline-delimited JSON events. Filter with jq for live text:
+```
+claude -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
+  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
+```
+
+Stream events include `system/api_retry` with `attempt`, `max_retries`, and `error` fields (e.g., `rate_limit`, `billing_error`).
+
+### Bidirectional Streaming
+For real-time input AND output streaming:
+```
+claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages
+```
+`--replay-user-messages` re-emits user messages on stdout for acknowledgment.
+
+### Piped Input
+```
+# Pipe a file for analysis
+terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)
+
+# Pipe multiple files
+terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)
+
+# Pipe command output
+terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)
+```
+
+### JSON Schema for Structured Extraction
+```
+terminal(command="claude -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)
+```
+
+Parse `structured_output` from the JSON result. Claude validates output against the schema before returning.
+
+### Session Continuation
+```
+# Start a task
+terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)
+
+# Resume with session ID
+terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)
+
+# Or resume the most recent session in the same directory
+terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)
+
+# Fork a session (new ID, keeps history)
+terminal(command="claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)
+```
+
+### Bare Mode for CI/Scripting
+```
+terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)
+```
+
+`--bare` skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires `ANTHROPIC_API_KEY` (skips OAuth).
+
+To selectively load context in bare mode:
+| To load | Flag |
+|---------|------|
+| System prompt additions | `--append-system-prompt "text"` or `--append-system-prompt-file path` |
+| Settings | `--settings <file-or-json>` |
+| MCP servers | `--mcp-config <file-or-json>` |
+| Custom agents | `--agents '<json>'` |
+
+### Fallback Model for Overload
+```
+terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)
+```
+Automatically falls back to the specified model when the default is overloaded (print mode only).
+
+## Complete CLI Flags Reference
+
+### Session & Environment
+| Flag | Effect |
+|------|--------|
+| `-p, --print` | Non-interactive one-shot mode (exits when done) |
+| `-c, --continue` | Resume most recent conversation in current directory |
+| `-r, --resume <id>` | Resume specific session by ID or name (interactive picker if no ID) |
+| `--fork-session` | When resuming, create new session ID instead of reusing original |
+| `--session-id <uuid>` | Use a specific UUID for the conversation |
+| `--no-session-persistence` | Don't save session to disk (print mode only) |
+| `--add-dir <paths...>` | Grant Claude access to additional working directories |
+| `-w, --worktree [name]` | Run in an isolated git worktree at `.claude/worktrees/<name>` |
+| `--tmux` | Create a tmux session for the worktree (requires `--worktree`) |
+| `--ide` | Auto-connect to a valid IDE on startup |
+| `--chrome` / `--no-chrome` | Enable/disable Chrome browser integration for web testing |
+| `--from-pr [number]` | Resume session linked to a specific GitHub PR |
+| `--file <specs...>` | File resources to download at startup (format: `file_id:relative_path`) |
+
+### Model & Performance
+| Flag | Effect |
+|------|--------|
+| `--model <alias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |
+| `--effort <level>` | Reasoning depth: `low`, `medium`, `high`, `max`, `auto` | Both |
+| `--max-turns <n>` | Limit agentic loops (print mode only; prevents runaway) |
+| `--max-budget-usd <n>` | Cap API spend in dollars (print mode only) |
+| `--fallback-model <model>` | Auto-fallback when default model is overloaded (print mode only) |
+| `--betas <betas...>` | Beta headers to include in API requests (API key users only) |
+
+### Permission & Safety
+| Flag | Effect |
+|------|--------|
+| `--dangerously-skip-permissions` | Auto-approve ALL tool use (file writes, bash, network, etc.) |
+| `--allow-dangerously-skip-permissions` | Enable bypass as an *option* without enabling it by default |
+| `--permission-mode <mode>` | `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` |
+| `--allowedTools <tools...>` | Whitelist specific tools (comma or space-separated) |
+| `--disallowedTools <tools...>` | Blacklist specific tools |
+| `--tools <tools...>` | Override built-in tool set (`""` = none, `"default"` = all, or tool names) |
+
+### Output & Input Format
+| Flag | Effect |
+|------|--------|
+| `--output-format <fmt>` | `text` (default), `json` (single result object), `stream-json` (newline-delimited) |
+| `--input-format <fmt>` | `text` (default) or `stream-json` (real-time streaming input) |
+| `--json-schema <schema>` | Force structured JSON output matching a schema |
+| `--verbose` | Full turn-by-turn output |
+| `--include-partial-messages` | Include partial message chunks as they arrive (stream-json + print) |
+| `--replay-user-messages` | Re-emit user messages on stdout (stream-json bidirectional) |
+
+### System Prompt & Context
+| Flag | Effect |
+|------|--------|
+| `--append-system-prompt <text>` | **Add** to the default system prompt (preserves built-in capabilities) |
+| `--append-system-prompt-file <path>` | **Add** file contents to the default system prompt |
+| `--system-prompt <text>` | **Replace** the entire system prompt (use --append instead usually) |
+| `--system-prompt-file <path>` | **Replace** the system prompt with file contents |
+| `--bare` | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |
+| `--agents '<json>'` | Define custom subagents dynamically as JSON |
+| `--mcp-config <path>` | Load MCP servers from JSON file (repeatable) |
+| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configs |
+| `--settings <file-or-json>` | Load additional settings from a JSON file or inline JSON |
+| `--setting-sources <sources>` | Comma-separated sources to load: `user`, `project`, `local` |
+| `--plugin-dir <paths...>` | Load plugins from directories for this session only |
+| `--disable-slash-commands` | Disable all skills/slash commands |
+
+### Debugging
+| Flag | Effect |
+|------|--------|
+| `-d, --debug [filter]` | Enable debug logging with optional category filter (e.g., `"api,hooks"`, `"!1p,!file"`) |
+| `--debug-file <path>` | Write debug logs to file (implicitly enables debug mode) |
+
+### Agent Teams
+| Flag | Effect |
+|------|--------|
+| `--teammate-mode <mode>` | How agent teams display: `auto`, `in-process`, or `tmux` |
+| `--brief` | Enable `SendUserMessage` tool for agent-to-user communication |
+
+### Tool Name Syntax for --allowedTools / --disallowedTools
+```
+Read                    # All file reading
+Edit                    # File editing (existing files)
+Write                   # File creation (new files)
+Bash                    # All shell commands
+Bash(git *)             # Only git commands
+Bash(git commit *)      # Only git commit commands
+Bash(npm run lint:*)    # Pattern matching with wildcards
+WebSearch               # Web search capability
+WebFetch                # Web page fetching
+mcp__<server>__<tool>   # Specific MCP tool
+```
+
+## Settings & Configuration
+
+### Settings Hierarchy (highest to lowest priority)
+1. **CLI flags** — override everything
+2. **Local project:** `.claude/settings.local.json` (personal, gitignored)
+3. **Project:** `.claude/settings.json` (shared, git-tracked)
+4. **User:** `~/.claude/settings.json` (global)
+
+### Permissions in Settings
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
+    "ask": ["Write(*.ts)", "Bash(git push*)"],
+    "deny": ["Read(.env)", "Bash(rm -rf *)"]
+  }
+}
+```
+
+### Memory Files (CLAUDE.md) Hierarchy
+1. **Global:** `~/.claude/CLAUDE.md` — applies to all projects
+2. **Project:** `./CLAUDE.md` — project-specific context (git-tracked)
+3. **Local:** `.claude/CLAUDE.local.md` — personal project overrides (gitignored)
+
+Use the `#` prefix in interactive mode to quickly add to memory: `# Always use 2-space indentation`.
+
+## Interactive Session: Slash Commands
+
+### Session & Context
+| Command | Purpose |
+|---------|---------|
+| `/help` | Show all commands (including custom and MCP commands) |
+| `/compact [focus]` | Compress context to save tokens; CLAUDE.md survives compaction. E.g., `/compact focus on auth logic` |
+| `/clear` | Wipe conversation history for a fresh start |
+| `/context` | Visualize context usage as a colored grid with optimization tips |
+| `/cost` | View token usage with per-model and cache-hit breakdowns |
+| `/resume` | Switch to or resume a different session |
+| `/rewind` | Revert to a previous checkpoint in conversation or code |
+| `/btw <question>` | Ask a side question without adding to context cost |
+| `/status` | Show version, connectivity, and session info |
+| `/todos` | List tracked action items from the conversation |
+| `/exit` or `Ctrl+D` | End session |
+
+### Development & Review
+| Command | Purpose |
+|---------|---------|
+| `/review` | Request code review of current changes |
+| `/security-review` | Perform security analysis of current changes |
+| `/plan [description]` | Enter Plan mode with auto-start for task planning |
+| `/loop [interval]` | Schedule recurring tasks within the session |
+| `/batch` | Auto-create worktrees for large parallel changes (5-30 worktrees) |
+
+### Configuration & Tools
+| Command | Purpose |
+|---------|---------|
+| `/model [model]` | Switch models mid-session (use arrow keys to adjust effort) |
+| `/effort [level]` | Set reasoning effort: `low`, `medium`, `high`, `max`, or `auto` |
+| `/init` | Create a CLAUDE.md file for project memory |
+| `/memory` | Open CLAUDE.md for editing |
+| `/config` | Open interactive settings configuration |
+| `/permissions` | View/update tool permissions |
+| `/agents` | Manage specialized subagents |
+| `/mcp` | Interactive UI to manage MCP servers |
+| `/add-dir` | Add additional working directories (useful for monorepos) |
+| `/usage` | Show plan limits and rate limit status |
+| `/voice` | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |
+| `/release-notes` | Interactive picker for version release notes |
+
+### Custom Slash Commands
+Create `.claude/commands/<name>.md` (project-shared) or `~/.claude/commands/<name>.md` (personal):
+
+```markdown
+# .claude/commands/deploy.md
+Run the deploy pipeline:
+1. Run all tests
+2. Build the Docker image
+3. Push to registry
+4. Update the $ARGUMENTS environment (default: staging)
+```
+
+Usage: `/deploy production` — `$ARGUMENTS` is replaced with the user's input.
+
+### Skills (Natural Language Invocation)
+Unlike slash commands (manually invoked), skills in `.claude/skills/` are markdown guides that Claude invokes automatically via natural language when the task matches:
+
+```markdown
+# .claude/skills/database-migration.md
+When asked to create or modify database migrations:
+1. Use Alembic for migration generation
+2. Always create a rollback function
+3. Test migrations against a local database copy
+```
+
+## Interactive Session: Keyboard Shortcuts
+
+### General Controls
+| Key | Action |
+|-----|--------|
+| `Ctrl+C` | Cancel current input or generation |
+| `Ctrl+D` | Exit session |
+| `Ctrl+R` | Reverse search command history |
+| `Ctrl+B` | Background a running task |
+| `Ctrl+V` | Paste image into conversation |
+| `Ctrl+O` | Transcript mode — see Claude's thinking process |
+| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open prompt in external editor |
+| `Esc Esc` | Rewind conversation or code state / summarize |
+
+### Mode Toggles
+| Key | Action |
+|-----|--------|
+| `Shift+Tab` | Cycle permission modes (Normal → Auto-Accept → Plan) |
+| `Alt+P` | Switch model |
+| `Alt+T` | Toggle thinking mode |
+| `Alt+O` | Toggle Fast Mode |
+
+### Multiline Input
+| Key | Action |
+|-----|--------|
+| `\` + `Enter` | Quick newline |
+| `Shift+Enter` | Newline (alternative) |
+| `Ctrl+J` | Newline (alternative) |
+
+### Input Prefixes
+| Prefix | Action |
+|--------|--------|
+| `!` | Execute bash directly, bypassing AI (e.g., `!npm test`). Use `!` alone to toggle shell mode. |
+| `@` | Reference files/directories with autocomplete (e.g., `@./src/api/`) |
+| `#` | Quick add to CLAUDE.md memory (e.g., `# Use 2-space indentation`) |
+| `/` | Slash commands |
+
+### Pro Tip: "ultrathink"
+Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current `/effort` setting.
+
+## PR Review Pattern
+
+### Quick Review (Print Mode)
+```
+terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)
+```
+
+### Deep Review (Interactive + Worktree)
+```
+terminal(command="tmux new-session -d -s review -x 140 -y 40")
+terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
+terminal(command="sleep 5 && tmux send-keys -t review Enter")  # Trust dialog
+terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
+terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")
+```
+
+### PR Review from Number
+```
+terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)
+```
+
+### Claude Worktree with tmux
+```
+terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")
+```
+Creates an isolated git worktree at `.claude/worktrees/feature-x` AND a tmux session for it. Uses iTerm2 native panes when available; add `--tmux=classic` for traditional tmux.
+
+## Parallel Claude Instances
+
+Run multiple independent Claude tasks simultaneously:
+
+```
+# Task 1: Fix backend
+terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")
+
+# Task 2: Write tests
+terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")
+
+# Task 3: Update docs
+terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")
+
+# Monitor all
+terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")
+```
+
+## CLAUDE.md — Project Context File
+
+Claude Code auto-loads `CLAUDE.md` from the project root. Use it to persist project context:
+
+```markdown
+# Project: My API
+
+## Architecture
+- FastAPI backend with SQLAlchemy ORM
+- PostgreSQL database, Redis cache
+- pytest for testing with 90% coverage target
+
+## Key Commands
+- `make test` — run full test suite
+- `make lint` — ruff + mypy
+- `make dev` — start dev server on :8000
+
+## Code Standards
+- Type hints on all public functions
+- Docstrings in Google style
+- 2-space indentation for YAML, 4-space for Python
+- No wildcard imports
+```
+
+**Be specific.** Instead of "Write good code", use "Use 2-space indentation for JS" or "Name test files with `.test.ts` suffix." Specific instructions save correction cycles.
+
+### Rules Directory (Modular CLAUDE.md)
+For projects with many rules, use the rules directory instead of one massive CLAUDE.md:
+- **Project rules:** `.claude/rules/*.md` — team-shared, git-tracked
+- **User rules:** `~/.claude/rules/*.md` — personal, global
+
+Each `.md` file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.
+
+### Auto-Memory
+Claude automatically stores learned project context in `~/.claude/projects/<project>/memory/`.
+- **Limit:** 25KB or 200 lines per project
+- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions
+
+## Custom Subagents
+
+Define specialized agents in `.claude/agents/` (project), `~/.claude/agents/` (personal), or via `--agents` CLI flag (session):
+
+### Agent Location Priority
+1. `.claude/agents/` — project-level, team-shared
+2. `--agents` CLI flag — session-specific, dynamic
+3. `~/.claude/agents/` — user-level, personal
+
+### Creating an Agent
+```markdown
+# .claude/agents/security-reviewer.md
+---
+name: security-reviewer
+description: Security-focused code review
+model: opus
+tools: [Read, Bash]
+---
+You are a senior security engineer. Review code for:
+- Injection vulnerabilities (SQL, XSS, command injection)
+- Authentication/authorization flaws
+- Secrets in code
+- Unsafe deserialization
+```
+
+Invoke via: `@security-reviewer review the auth module`
+
+### Dynamic Agents via CLI
+```
+terminal(command="claude --agents '{\"reviewer\": {\"description\": \"Reviews code\", \"prompt\": \"You are a code reviewer focused on performance\"}}' -p 'Use @reviewer to check auth.py'", timeout=120)
+```
+
+Claude can orchestrate multiple agents: "Use @db-expert to optimize queries, then @security to audit the changes."
+
+## Hooks — Automation on Events
+
+Configure in `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write(*.py)",
+      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
+    }],
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
+    }],
+    "Stop": [{
+      "hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> /tmp/claude-activity.log"}]
+    }]
+  }
+}
+```
+
+### All 8 Hook Types
+| Hook | When it fires | Common use |
+|------|--------------|------------|
+| `UserPromptSubmit` | Before Claude processes a user prompt | Input validation, logging |
+| `PreToolUse` | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |
+| `PostToolUse` | After a tool finishes | Auto-format code, run linters |
+| `Notification` | On permission requests or input waits | Desktop notifications, alerts |
+| `Stop` | When Claude finishes a response | Completion logging, status updates |
+| `SubagentStop` | When a subagent completes | Agent orchestration |
+| `PreCompact` | Before context memory is cleared | Backup session transcripts |
+| `SessionStart` | When a session begins | Load dev context (e.g., `git status`) |
+
+### Hook Environment Variables
+| Variable | Content |
+|----------|---------|
+| `CLAUDE_PROJECT_DIR` | Current project path |
+| `CLAUDE_FILE_PATHS` | Files being modified |
+| `CLAUDE_TOOL_INPUT` | Tool parameters as JSON |
+
+### Security Hook Examples
+```json
+{
+  "PreToolUse": [{
+    "matcher": "Bash",
+    "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
+  }]
+}
+```
+
+## MCP Integration
+
+Add external tool servers for databases, APIs, and services:
+
+```
+# GitHub integration
+terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)
+
+# PostgreSQL queries
+terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)
+
+# Puppeteer for web testing
+terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)
+```
+
+### MCP Scopes
+| Flag | Scope | Storage |
+|------|-------|---------|
+| `-s user` | Global (all projects) | `~/.claude.json` |
+| `-s local` | This project (personal) | `.claude/settings.local.json` (gitignored) |
+| `-s project` | This project (team-shared) | `.claude/settings.json` (git-tracked) |
+
+### MCP in Print/CI Mode
+```
+terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)
+```
+`--strict-mcp-config` ignores all MCP servers except those from `--mcp-config`.
+
+Reference MCP resources in chat: `@github:issue://123`
+
+### MCP Limits & Tuning
+- **Tool descriptions:** 2KB cap per server for tool descriptions and server instructions
+- **Result size:** Default capped; use `maxResultSizeChars` annotation to allow up to **500K** characters for large outputs
+- **Output tokens:** `export MAX_MCP_OUTPUT_TOKENS=50000` — cap output from MCP servers to prevent context flooding
+- **Transports:** `stdio` (local process), `http` (remote), `sse` (server-sent events)
+
+## Monitoring Interactive Sessions
+
+### Reading the TUI Status
+```
+# Periodic capture to check if Claude is still working or waiting for input
+terminal(command="tmux capture-pane -t dev -p -S -10")
+```
+
+Look for these indicators:
+- `❯` at bottom = waiting for your input (Claude is done or asking a question)
+- `●` lines = Claude is actively using tools (reading, writing, running commands)
+- `⏵⏵ bypass permissions on` = status bar showing permissions mode
+- `◐ medium · /effort` = current effort level in status bar
+- `ctrl+o to expand` = tool output was truncated (can be expanded interactively)
+
+### Context Window Health
+Use `/context` in interactive mode to see a colored grid of context usage. Key thresholds:
+- **< 70%** — Normal operation, full precision
+- **70-85%** — Precision starts dropping, consider `/compact`
+- **> 85%** — Hallucination risk spikes significantly, use `/compact` or `/clear`
+
+## Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `ANTHROPIC_API_KEY` | API key for authentication (alternative to OAuth) |
+| `CLAUDE_CODE_EFFORT_LEVEL` | Default effort: `low`, `medium`, `high`, `max`, or `auto` |
+| `MAX_THINKING_TOKENS` | Cap thinking tokens (set to `0` to disable thinking entirely) |
+| `MAX_MCP_OUTPUT_TOKENS` | Cap output from MCP servers (default varies; set e.g., `50000`) |
+| `CLAUDE_CODE_NO_FLICKER=1` | Enable alt-screen rendering to eliminate terminal flicker |
+| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from sub-processes for security |
+
+## Cost & Performance Tips
+
+1. **Use `--max-turns`** in print mode to prevent runaway loops. Start with 5-10 for most tasks.
+2. **Use `--max-budget-usd`** for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
+3. **Use `--effort low`** for simple tasks (faster, cheaper). `high` or `max` for complex reasoning.
+4. **Use `--bare`** for CI/scripting to skip plugin/hook discovery overhead.
+5. **Use `--allowedTools`** to restrict to only what's needed (e.g., `Read` only for reviews).
+6. **Use `/compact`** in interactive sessions when context gets large.
+7. **Pipe input** instead of having Claude read files when you just need analysis of known content.
+8. **Use `--model haiku`** for simple tasks (cheaper) and `--model opus` for complex multi-step work.
+9. **Use `--fallback-model haiku`** in print mode to gracefully handle model overload.
+10. **Start new sessions for distinct tasks** — sessions last 5 hours; fresh context is more efficient.
+11. **Use `--no-session-persistence`** in CI to avoid accumulating saved sessions on disk.
+
+## Pitfalls & Gotchas
+
+1. **Interactive mode REQUIRES tmux** — Claude Code is a full TUI app. Using `pty=true` alone in Hermes terminal works but tmux gives you `capture-pane` for monitoring and `send-keys` for input, which is essential for orchestration.
+2. **`--dangerously-skip-permissions` dialog defaults to "No, exit"** — you must send Down then Enter to accept. Print mode (`-p`) skips this entirely.
+3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately.
+4. **`--max-turns` is print-mode only** — ignored in interactive sessions.
+5. **Claude may use `python` instead of `python3`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects.
+6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory.
+7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns.
+8. **Trust dialog only appears once per directory** — first-time only, then cached.
+9. **Background tmux sessions persist** — always clean up with `tmux kill-session -t <name>` when done.
+10. **Slash commands (like `/commit`) only work in interactive mode** — in `-p` mode, describe the task in natural language instead.
+11. **`--bare` skips OAuth** — requires `ANTHROPIC_API_KEY` env var or an `apiKeyHelper` in settings.
+12. **Context degradation is real** — AI output quality measurably degrades above 70% context window usage. Monitor with `/context` and proactively `/compact`.
+
+## Rules for Hermes Agents
+
+1. **Prefer print mode (`-p`) for single tasks** — cleaner, no dialog handling, structured output
+2. **Use tmux for multi-turn interactive work** — the only reliable way to orchestrate the TUI
+3. **Always set `workdir`** — keep Claude focused on the right project directory
+4. **Set `--max-turns` in print mode** — prevents infinite loops and runaway costs
+5. **Monitor tmux sessions** — use `tmux capture-pane -t <session> -p -S -50` to check progress
+6. **Look for the `❯` prompt** — indicates Claude is waiting for input (done or asking a question)
+7. **Clean up tmux sessions** — kill them when done to avoid resource leaks
+8. **Report results to user** — after completion, summarize what Claude did and what changed
+9. **Don't kill slow sessions** — Claude may be doing multi-step work; check progress instead
+10. **Use `--allowedTools`** — restrict capabilities to what the task actually needs

skills/autonomous-ai-agents/ai-coding-agents/references/codex.md

@@ -0,0 +1,130 @@
+---
+name: codex
+description: "Delegate coding to OpenAI Codex CLI (features, PRs)."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Coding-Agent, Codex, OpenAI, Code-Review, Refactoring]
+    related_skills: [claude-code, hermes-agent]
+---
+
+# Codex CLI
+
+Delegate coding tasks to [Codex](https://github.com/openai/codex) via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.
+
+## When to use
+
+- Building features
+- Refactoring
+- PR reviews
+- Batch issue fixing
+
+Requires the codex CLI and a git repository.
+
+## Prerequisites
+
+- Codex installed: `npm install -g @openai/codex`
+- OpenAI auth configured: either `OPENAI_API_KEY` or Codex OAuth credentials
+  from the Codex CLI login flow
+- **Must run inside a git repository** — Codex refuses to run outside one
+- Use `pty=true` in terminal calls — Codex is an interactive terminal app
+
+For Hermes itself, `model.provider: openai-codex` uses Hermes-managed Codex
+OAuth from `~/.hermes/auth.json` after `hermes auth add openai-codex`. For the
+standalone Codex CLI, a valid CLI OAuth session may live under
+`~/.codex/auth.json`; do not treat a missing `OPENAI_API_KEY` alone as proof
+that Codex auth is missing.
+
+## One-Shot Tasks
+
+```
+terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
+```
+
+For scratch work (Codex needs a git repo):
+```
+terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)
+```
+
+## Background Mode (Long Tasks)
+
+```
+# Start in background with PTY
+terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
+# Returns session_id
+
+# Monitor progress
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+
+# Send input if Codex asks a question
+process(action="submit", session_id="<id>", data="yes")
+
+# Kill if needed
+process(action="kill", session_id="<id>")
+```
+
+## Key Flags
+
+| Flag | Effect |
+|------|--------|
+| `exec "prompt"` | One-shot execution, exits when done |
+| `--full-auto` | Sandboxed but auto-approves file changes in workspace |
+| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
+
+## PR Reviews
+
+Clone to a temp directory for safe review:
+
+```
+terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)
+```
+
+## Parallel Issue Fixing with Worktrees
+
+```
+# Create worktrees
+terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
+terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
+
+# Launch Codex in each
+terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
+terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)
+
+# Monitor
+process(action="list")
+
+# After completion, push and create PRs
+terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
+terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
+
+# Cleanup
+terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
+```
+
+## Batch PR Reviews
+
+```
+# Fetch all PR refs
+terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")
+
+# Review multiple PRs in parallel
+terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
+terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)
+
+# Post results
+terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
+```
+
+## Rules
+
+1. **Always use `pty=true`** — Codex is an interactive terminal app and hangs without a PTY
+2. **Git repo required** — Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch
+3. **Use `exec` for one-shots** — `codex exec "prompt"` runs and exits cleanly
+4. **`--full-auto` for building** — auto-approves changes within the sandbox
+5. **Background for long tasks** — use `background=true` and monitor with `process` tool
+6. **Don't interfere** — monitor with `poll`/`log`, be patient with long-running tasks
+7. **Parallel is fine** — run multiple Codex processes at once for batch work

skills/autonomous-ai-agents/ai-coding-agents/references/opencode.md

@@ -0,0 +1,219 @@
+---
+name: opencode
+description: "Delegate coding to OpenCode CLI (features, PR review)."
+version: 1.2.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Coding-Agent, OpenCode, Autonomous, Refactoring, Code-Review]
+    related_skills: [claude-code, codex, hermes-agent]
+---
+
+# OpenCode CLI
+
+Use [OpenCode](https://opencode.ai) as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.
+
+## When to Use
+
+- User explicitly asks to use OpenCode
+- You want an external coding agent to implement/refactor/review code
+- You need long-running coding sessions with progress checks
+- You want parallel task execution in isolated workdirs/worktrees
+
+## Prerequisites
+
+- OpenCode installed: `npm i -g opencode-ai@latest` or `brew install anomalyco/tap/opencode`
+- Auth configured: `opencode auth login` or set provider env vars (OPENROUTER_API_KEY, etc.)
+- Verify: `opencode auth list` should show at least one provider
+- Git repository for code tasks (recommended)
+- `pty=true` for interactive TUI sessions
+
+## Binary Resolution (Important)
+
+Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check:
+
+```
+terminal(command="which -a opencode")
+terminal(command="opencode --version")
+```
+
+If needed, pin an explicit binary path:
+
+```
+terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)
+```
+
+## One-Shot Tasks
+
+Use `opencode run` for bounded, non-interactive tasks:
+
+```
+terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")
+```
+
+Attach context files with `-f`:
+
+```
+terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")
+```
+
+Show model thinking with `--thinking`:
+
+```
+terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")
+```
+
+Force a specific model:
+
+```
+terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")
+```
+
+## Interactive Sessions (Background)
+
+For iterative work requiring multiple exchanges, start the TUI in background:
+
+```
+terminal(command="opencode", workdir="~/project", background=true, pty=true)
+# Returns session_id
+
+# Send a prompt
+process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")
+
+# Monitor progress
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+
+# Send follow-up input
+process(action="submit", session_id="<id>", data="Now add error handling for token expiry")
+
+# Exit cleanly — Ctrl+C
+process(action="write", session_id="<id>", data="\x03")
+# Or just kill the process
+process(action="kill", session_id="<id>")
+```
+
+**Important:** Do NOT use `/exit` — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (`\x03`) or `process(action="kill")` to exit.
+
+### TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit message (press twice if needed) |
+| `Tab` | Switch between agents (build/plan) |
+| `Ctrl+P` | Open command palette |
+| `Ctrl+X L` | Switch session |
+| `Ctrl+X M` | Switch model |
+| `Ctrl+X N` | New session |
+| `Ctrl+X E` | Open editor |
+| `Ctrl+C` | Exit OpenCode |
+
+### Resuming Sessions
+
+After exiting, OpenCode prints a session ID. Resume with:
+
+```
+terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # Continue last session
+terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # Specific session
+```
+
+## Common Flags
+
+| Flag | Use |
+|------|-----|
+| `run 'prompt'` | One-shot execution and exit |
+| `--continue` / `-c` | Continue the last OpenCode session |
+| `--session <id>` / `-s` | Continue a specific session |
+| `--agent <name>` | Choose OpenCode agent (build or plan) |
+| `--model provider/model` | Force specific model |
+| `--format json` | Machine-readable output/events |
+| `--file <path>` / `-f` | Attach file(s) to the message |
+| `--thinking` | Show model thinking blocks |
+| `--variant <level>` | Reasoning effort (high, max, minimal) |
+| `--title <name>` | Name the session |
+| `--attach <url>` | Connect to a running opencode server |
+
+## Procedure
+
+1. Verify tool readiness:
+   - `terminal(command="opencode --version")`
+   - `terminal(command="opencode auth list")`
+2. For bounded tasks, use `opencode run '...'` (no pty needed).
+3. For iterative tasks, start `opencode` with `background=true, pty=true`.
+4. Monitor long tasks with `process(action="poll"|"log")`.
+5. If OpenCode asks for input, respond via `process(action="submit", ...)`.
+6. Exit with `process(action="write", data="\x03")` or `process(action="kill")`.
+7. Summarize file changes, test results, and next steps back to user.
+
+## PR Review Workflow
+
+OpenCode has a built-in PR command:
+
+```
+terminal(command="opencode pr 42", workdir="~/project", pty=true)
+```
+
+Or review in a temporary clone for isolation:
+
+```
+terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)
+```
+
+## Parallel Work Pattern
+
+Use separate workdirs/worktrees to avoid collisions:
+
+```
+terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
+terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
+process(action="list")
+```
+
+## Session & Cost Management
+
+List past sessions:
+
+```
+terminal(command="opencode session list")
+```
+
+Check token usage and costs:
+
+```
+terminal(command="opencode stats")
+terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")
+```
+
+## Pitfalls
+
+- Interactive `opencode` (TUI) sessions require `pty=true`. The `opencode run` command does NOT need pty.
+- `/exit` is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
+- PATH mismatch can select the wrong OpenCode binary/model config.
+- If OpenCode appears stuck, inspect logs before killing:
+  - `process(action="log", session_id="<id>")`
+- Avoid sharing one working directory across parallel OpenCode sessions.
+- Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).
+
+## Verification
+
+Smoke test:
+
+```
+terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")
+```
+
+Success criteria:
+- Output includes `OPENCODE_SMOKE_OK`
+- Command exits without provider/model errors
+- For code tasks: expected files changed and tests pass
+
+## Rules
+
+1. Prefer `opencode run` for one-shot automation — it's simpler and doesn't need pty.
+2. Use interactive background mode only when iteration is needed.
+3. Always scope OpenCode sessions to a single repo/workdir.
+4. For long tasks, provide progress updates from `process` logs.
+5. Report concrete outcomes (files changed, tests, remaining risks).
+6. Exit interactive sessions with Ctrl+C or kill, never `/exit`.

skills/autonomous-ai-agents/hermes-agent/references/native-mcp.md

@@ -0,0 +1,344 @@
+# Native MCP Client
+
+Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.
+
+## When to Use
+
+Use this whenever you want to:
+- Connect to MCP servers and use their tools from within Hermes Agent
+- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
+- Run local stdio-based MCP servers (npx, uvx, or any command)
+- Connect to remote HTTP/StreamableHTTP MCP servers
+- Have MCP tools auto-discovered and available in every conversation
+
+For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.
+
+## Prerequisites
+
+- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
+- **Node.js** -- required for `npx`-based MCP servers (most community servers)
+- **uv** -- required for `uvx`-based MCP servers (Python-based servers)
+
+Install the MCP SDK:
+
+```bash
+pip install mcp
+# or, if using uv:
+uv pip install mcp
+```
+
+## Quick Start
+
+Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+Restart Hermes Agent. On startup it will:
+1. Connect to the server
+2. Discover available tools
+3. Register them with the prefix `mcp_time_*`
+4. Inject them into all platform toolsets
+
+You can then use the tools naturally -- just ask the agent to get the current time.
+
+## Configuration Reference
+
+Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).
+
+### Stdio Transport (command + args)
+
+```yaml
+mcp_servers:
+  server_name:
+    command: "npx"             # (required) executable to run
+    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
+    env:                       # (optional) environment variables for the subprocess
+      SOME_API_KEY: "value"
+    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### HTTP Transport (url)
+
+```yaml
+mcp_servers:
+  server_name:
+    url: "https://my-server.example.com/mcp"   # (required) server URL
+    headers:                                     # (optional) HTTP headers
+      Authorization: "Bearer sk-..."
+    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### All Config Options
+
+| Option            | Type   | Default | Description                                       |
+|-------------------|--------|---------|---------------------------------------------------|
+| `command`         | string | --      | Executable to run (stdio transport, required)     |
+| `args`            | list   | `[]`    | Arguments passed to the command                   |
+| `env`             | dict   | `{}`    | Extra environment variables for the subprocess    |
+| `url`             | string | --      | Server URL (HTTP transport, required)             |
+| `headers`         | dict   | `{}`    | HTTP headers sent with every request              |
+| `timeout`         | int    | `120`   | Per-tool-call timeout in seconds                  |
+| `connect_timeout` | int    | `60`    | Timeout for initial connection and discovery      |
+
+Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.
+
+## How It Works
+
+### Startup Discovery
+
+When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:
+
+1. Reads `mcp_servers` from `~/.hermes/config.yaml`
+2. For each server, spawns a connection in a dedicated background event loop
+3. Initializes the MCP session and calls `list_tools()` to discover available tools
+4. Registers each tool in the Hermes tool registry
+
+### Tool Naming Convention
+
+MCP tools are registered with the naming pattern:
+
+```
+mcp_{server_name}_{tool_name}
+```
+
+Hyphens and dots in names are replaced with underscores for LLM API compatibility.
+
+Examples:
+- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
+- Server `github`, tool `list-issues` → `mcp_github_list_issues`
+- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
+
+### Auto-Injection
+
+After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
+
+### Connection Lifecycle
+
+- Each server runs as a long-lived asyncio Task in a background daemon thread
+- Connections persist for the lifetime of the agent process
+- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
+- On agent shutdown, all connections are gracefully closed
+
+### Idempotency
+
+`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
+
+## Transport Types
+
+### Stdio Transport
+
+The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
+```
+
+The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.
+
+### HTTP / StreamableHTTP Transport
+
+For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
+
+```yaml
+mcp_servers:
+  remote_api:
+    url: "https://mcp.example.com/mcp"
+    headers:
+      Authorization: "Bearer sk-..."
+```
+
+If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
+
+## Security
+
+### Environment Variable Filtering
+
+For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
+
+- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
+- Any `XDG_*` variables
+
+All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      # Only this token is passed to the subprocess
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
+```
+
+### Credential Stripping in Error Messages
+
+If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
+
+- GitHub PATs (`ghp_...`)
+- OpenAI-style keys (`sk-...`)
+- Bearer tokens
+- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
+
+## Troubleshooting
+
+### "MCP SDK not available -- skipping MCP tool discovery"
+
+The `mcp` Python package is not installed. Install it:
+
+```bash
+pip install mcp
+```
+
+### "No MCP servers configured"
+
+No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
+
+### "Failed to connect to MCP server 'X'"
+
+Common causes:
+- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
+- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
+- **Timeout**: The server took too long to start. Increase `connect_timeout`.
+- **Port conflict**: For HTTP servers, the URL may be unreachable.
+
+### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
+
+Your `mcp` package version doesn't include HTTP client support. Upgrade:
+
+```bash
+pip install --upgrade mcp
+```
+
+### Tools not appearing
+
+- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
+- Ensure the YAML indentation is correct
+- Look at Hermes Agent startup logs for connection messages
+- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
+
+### Connection keeps dropping
+
+The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
+
+## Examples
+
+### Time Server (uvx)
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+Registers tools like `mcp_time_get_current_time`.
+
+### Filesystem Server (npx)
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
+    timeout: 30
+```
+
+Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
+
+### GitHub Server with Authentication
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+    timeout: 60
+```
+
+Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
+
+### Remote HTTP Server
+
+```yaml
+mcp_servers:
+  company_api:
+    url: "https://mcp.mycompany.com/v1/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+      X-Team-Id: "engineering"
+    timeout: 180
+    connect_timeout: 30
+```
+
+### Multiple Servers
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+
+  company_api:
+    url: "https://mcp.internal.company.com/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+    timeout: 300
+```
+
+All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
+
+## Sampling (Server-Initiated LLM Requests)
+
+Hermes supports MCP's `sampling/createMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).
+
+Sampling is **enabled by default**. Configure per server:
+
+```yaml
+mcp_servers:
+  my_server:
+    command: "npx"
+    args: ["-y", "my-mcp-server"]
+    sampling:
+      enabled: true           # default: true
+      model: "gemini-3-flash" # model override (optional)
+      max_tokens_cap: 4096    # max tokens per request
+      timeout: 30             # LLM call timeout (seconds)
+      max_rpm: 10             # max requests per minute
+      allowed_models: []      # model whitelist (empty = all)
+      max_tool_rounds: 5      # tool loop limit (0 = disable)
+      log_level: "info"       # audit verbosity
+```
+
+Servers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.
+
+Disable sampling for untrusted servers with `sampling: { enabled: false }`.
+
+## Notes
+
+- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
+- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
+- The native MCP client is independent of `mcporter` -- you can use both simultaneously
+- Server connections are persistent and shared across all conversations in the same agent process
+- Adding or removing servers requires restarting the agent (no hot-reload currently)

skills/autonomous-ai-agents/hermes-agent/references/skill-authoring-in-repo.md

@@ -0,0 +1,165 @@
+---
+name: hermes-agent-skill-authoring
+description: "Author in-repo SKILL.md: frontmatter, validator, structure."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [skills, authoring, hermes-agent, conventions, skill-md]
+    related_skills: [plan, requesting-code-review]
+---
+
+# Authoring Hermes-Agent Skills (in-repo)
+
+## Overview
+
+There are two places a SKILL.md can live:
+
+1. **User-local:** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — personal, not shared. Created via `skill_manage(action='create')`.
+2. **In-repo (this skill is about this case):** `/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md` — committed, shipped with the package. Use `write_file` + `git add`. `skill_manage(action='create')` does NOT target this tree.
+
+## When to Use
+
+- User asks you to add a skill "in this branch / repo / commit"
+- You're committing a reusable workflow that should ship with hermes-agent
+- You're editing an existing skill under `/home/bb/hermes-agent/skills/` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)
+
+## Required Frontmatter
+
+Source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Hard requirements:
+
+- Starts with `---` as the first bytes (no leading blank line).
+- Closes with `\n---\n` before the body.
+- Parses as a YAML mapping.
+- `name` field present.
+- `description` field present, ≤ **1024 chars** (`MAX_DESCRIPTION_LENGTH`).
+- Non-empty body after the closing `---`.
+
+Peer-matched shape used by every skill under `skills/software-development/`:
+
+```yaml
+---
+name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
+description: Use when <trigger>. <one-line behavior>.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [short, descriptive, tags]
+    related_skills: [other-skill, another-skill]
+---
+```
+
+`version` / `author` / `license` / `metadata` are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.
+
+## Size Limits
+
+- Description: ≤ 1024 chars (enforced).
+- Full SKILL.md: ≤ 100,000 chars (enforced as `MAX_SKILL_CONTENT_CHARS`, ~36k tokens).
+- Peer skills in `software-development/` sit at **8-14k chars**. Aim for that range. If you're pushing past 20k, split into `references/*.md` and reference them from SKILL.md.
+
+## Peer-Matched Structure
+
+Every in-repo skill follows roughly:
+
+```
+# <Title>
+
+## Overview
+One or two paragraphs: what and why.
+
+## When to Use
+- Bulleted triggers
+- "Don't use for:" counter-triggers
+
+## <Topic sections specific to the skill>
+- Quick-reference tables are common
+- Code blocks with exact commands
+- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)
+
+## Common Pitfalls
+Numbered list of mistakes and their fixes.
+
+## Verification Checklist
+- [ ] Checkbox list of post-action verifications
+
+## One-Shot Recipes (optional)
+Named scenarios → concrete command sequences.
+```
+
+Not every section is mandatory, but `Overview` + `When to Use` + actionable body + pitfalls are the minimum for the skill to feel like a peer.
+
+## Directory Placement
+
+```
+skills/<category>/<skill-name>/SKILL.md
+```
+
+Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `dogfood`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
+
+Pick the closest existing category. Don't invent new top-level categories casually.
+
+## Workflow
+
+1. **Survey peers** in the target category:
+   ```
+   ls skills/<category>/
+   ```
+   Read 2-3 peer SKILL.md files to match tone and structure.
+2. **Check validator constraints** in `tools/skill_manager_tool.py` if unsure.
+3. **Draft** with `write_file` to `skills/<category>/<name>/SKILL.md`.
+4. **Validate locally**:
+   ```python
+   import yaml, re, pathlib
+   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
+   assert content.startswith("---")
+   m = re.search(r'\n---\s*\n', content[3:])
+   fm = yaml.safe_load(content[3:m.start()+3])
+   assert "name" in fm and "description" in fm
+   assert len(fm["description"]) <= 1024
+   assert len(content) <= 100_000
+   ```
+5. **Git add + commit** on the active branch.
+6. **Note:** the CURRENT session's skill loader is cached — `skill_view` / `skills_list` will not see the new skill until a new session. This is expected, not a bug.
+
+## Cross-Referencing Other Skills
+
+`metadata.hermes.related_skills` unions both trees (`skills/` in-repo and `~/.hermes/skills/`) at load time. You CAN reference a user-local skill from an in-repo skill, but it won't resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in `~/.hermes/skills/`, consider promoting it to the repo.
+
+## Editing Existing In-Repo Skills
+
+- **Small fix (typo, added pitfall, tightened trigger):** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` works fine on in-repo skills.
+- **Major rewrite:** `write_file` the whole SKILL.md. `skill_manage(action='edit')` also works but requires supplying the full new content.
+- **Adding supporting files:** `write_file` to `skills/<category>/<name>/references/<file>.md`, `templates/<file>`, or `scripts/<file>`. `skill_manage(action='write_file')` also works and enforces the references/templates/scripts/assets subdir allowlist.
+- **Always commit** the edit — in-repo skills are source, not runtime state.
+
+## Common Pitfalls
+
+1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~/.hermes/skills/`, not the repo tree. Use `write_file` for in-repo creation.
+
+2. **Leading whitespace before `---`.** The validator checks `content.startswith("---")`; any leading blank line or BOM fails validation.
+
+3. **Description too generic.** Peer descriptions start with "Use when ..." and describe the *trigger class*, not the one task. "Use when debugging X" > "Debug X".
+
+4. **Forgetting the author/license/metadata block.** Not validator-enforced, but every peer has it; omitting makes the skill look half-finished.
+
+5. **Writing a skill that duplicates a peer.** Before creating, `ls skills/<category>/` and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling.
+
+6. **Expecting the current session to see the new skill.** It won't. The skill loader is initialized at session start. Verify in a fresh session or via `skill_view` using the exact path.
+
+7. **Linking to skills that don't exist in-repo.** `related_skills: [some-user-local-skill]` works for you but breaks for other clones. Prefer only in-repo links.
+
+## Verification Checklist
+
+- [ ] File is at `skills/<category>/<name>/SKILL.md` (not in `~/.hermes/skills/`)
+- [ ] Frontmatter starts at byte 0 with `---`, closes with `\n---\n`
+- [ ] `name`, `description`, `version`, `author`, `license`, `metadata.hermes.{tags, related_skills}` all present
+- [ ] Name ≤ 64 chars, lowercase + hyphens
+- [ ] Description ≤ 1024 chars and starts with "Use when ..."
+- [ ] Total file ≤ 100,000 chars (aim for 8-15k)
+- [ ] Structure: `# Title` → `## Overview` → `## When to Use` → body → `## Common Pitfalls` → `## Verification Checklist`
+- [ ] `related_skills` references resolve in-repo (or are explicitly OK to be user-local)
+- [ ] `git add skills/<category>/<name>/ && git commit` completed on the intended branch

skills/autonomous-ai-agents/hermes-agent/references/webhooks.md

@@ -0,0 +1,194 @@
+# Webhook Subscriptions
+
+Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Hermes agent runs by POSTing events to a URL.
+
+## Setup (Required First)
+
+The webhook platform must be enabled before subscriptions can be created. Check with:
+```bash
+hermes webhook list
+```
+
+If it says "Webhook platform is not enabled", set it up:
+
+### Option 1: Setup wizard
+```bash
+hermes gateway setup
+```
+Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.
+
+### Option 2: Manual config
+Add to `~/.hermes/config.yaml`:
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      host: "0.0.0.0"
+      port: 8644
+      secret: "generate-a-strong-secret-here"
+```
+
+### Option 3: Environment variables
+Add to `~/.hermes/.env`:
+```bash
+WEBHOOK_ENABLED=true
+WEBHOOK_PORT=8644
+WEBHOOK_SECRET=generate-a-strong-secret-here
+```
+
+After configuration, start (or restart) the gateway:
+```bash
+hermes gateway run
+# Or if using systemd:
+systemctl --user restart hermes-gateway
+```
+
+Verify it's running:
+```bash
+curl http://localhost:8644/health
+```
+
+## Commands
+
+All management is via the `hermes webhook` CLI command:
+
+### Create a subscription
+```bash
+hermes webhook subscribe <name> \
+  --prompt "Prompt template with {payload.fields}" \
+  --events "event1,event2" \
+  --description "What this does" \
+  --skills "skill1,skill2" \
+  --deliver telegram \
+  --deliver-chat-id "12345" \
+  --secret "optional-custom-secret"
+```
+
+Returns the webhook URL and HMAC secret. The user configures their service to POST to that URL.
+
+### List subscriptions
+```bash
+hermes webhook list
+```
+
+### Remove a subscription
+```bash
+hermes webhook remove <name>
+```
+
+### Test a subscription
+```bash
+hermes webhook test <name>
+hermes webhook test <name> --payload '{"key": "value"}'
+```
+
+## Prompt Templates
+
+Prompts support `{dot.notation}` for accessing nested payload fields:
+
+- `{issue.title}` — GitHub issue title
+- `{pull_request.user.login}` — PR author
+- `{data.object.amount}` — Stripe payment amount
+- `{sensor.temperature}` — IoT sensor reading
+
+If no prompt is specified, the full JSON payload is dumped into the agent prompt.
+
+## Common Patterns
+
+### GitHub: new issues
+```bash
+hermes webhook subscribe github-issues \
+  --events "issues" \
+  --prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+Then in GitHub repo Settings → Webhooks → Add webhook:
+- Payload URL: the returned webhook_url
+- Content type: application/json
+- Secret: the returned secret
+- Events: "Issues"
+
+### GitHub: PR reviews
+```bash
+hermes webhook subscribe github-prs \
+  --events "pull_request" \
+  --prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
+  --skills "github-code-review" \
+  --deliver github_comment
+```
+
+### Stripe: payment events
+```bash
+hermes webhook subscribe stripe-payments \
+  --events "payment_intent.succeeded,payment_intent.payment_failed" \
+  --prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+### CI/CD: build notifications
+```bash
+hermes webhook subscribe ci-builds \
+  --events "pipeline" \
+  --prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
+  --deliver discord \
+  --deliver-chat-id "1234567890"
+```
+
+### Generic monitoring alert
+```bash
+hermes webhook subscribe alerts \
+  --prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
+  --deliver origin
+```
+
+### Direct delivery (no agent, zero LLM cost)
+
+For use cases where you just want to push a notification through to a user's chat — no reasoning, no agent loop — add `--deliver-only`. The rendered `--prompt` template becomes the literal message body and is dispatched directly to the target adapter.
+
+Use this for:
+- External service push notifications (Supabase/Firebase webhooks → Telegram)
+- Monitoring alerts that should forward verbatim
+- Inter-agent pings where one agent is telling another agent's user something
+- Any webhook where an LLM round trip would be wasted effort
+
+```bash
+hermes webhook subscribe antenna-matches \
+  --deliver telegram \
+  --deliver-chat-id "123456789" \
+  --deliver-only \
+  --prompt "🎉 New match: {match.user_name} matched with you!" \
+  --description "Antenna match notifications"
+```
+
+The POST returns `200 OK` on successful delivery, `502` on target failure — so upstream services can retry intelligently. HMAC auth, rate limits, and idempotency still apply.
+
+Requires `--deliver` to be a real target (telegram, discord, slack, github_comment, etc.) — `--deliver log` is rejected because log-only direct delivery is pointless.
+
+## Security
+
+- Each subscription gets an auto-generated HMAC-SHA256 secret (or provide your own with `--secret`)
+- The webhook adapter validates signatures on every incoming POST
+- Static routes from config.yaml cannot be overwritten by dynamic subscriptions
+- Subscriptions persist to `~/.hermes/webhook_subscriptions.json`
+
+## How It Works
+
+1. `hermes webhook subscribe` writes to `~/.hermes/webhook_subscriptions.json`
+2. The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
+3. When a POST arrives matching a route, the adapter formats the prompt and triggers an agent run
+4. The agent's response is delivered to the configured target (Telegram, Discord, GitHub comment, etc.)
+
+## Troubleshooting
+
+If webhooks aren't working:
+
+1. **Is the gateway running?** Check with `systemctl --user status hermes-gateway` or `ps aux | grep gateway`
+2. **Is the webhook server listening?** `curl http://localhost:8644/health` should return `{"status": "ok"}`
+3. **Check gateway logs:** `grep webhook ~/.hermes/logs/gateway.log | tail -20`
+4. **Signature mismatch?** Verify the secret in your service matches the one from `hermes webhook list`. GitHub sends `X-Hub-Signature-256`, GitLab sends `X-Gitlab-Token`.
+5. **Firewall/NAT?** The webhook URL must be reachable from the service. For local development, use a tunnel (ngrok, cloudflared).
+6. **Wrong event type?** Check `--events` filter matches what the service sends. Use `hermes webhook test <name>` to verify the route works.

skills/communication/multichannel-messaging-discipline/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: multichannel-messaging-discipline
+description: 跨渠道、多人环境下的通讯纪律——回复路由（在哪个渠道被找就回哪个渠道）、发送者身份核实、信息隔离、发送前核对。在向任何人或群发消息/回复、不确定对方是谁、或决定通知发往何处之前加载。覆盖企微 + 飞书的群聊与私聊。Load before sending any WeCom/Feishu message (group or DM), when unsure who the sender is, or when deciding where a reply/notification should go.
+---
+
+# 多渠道通讯纪律 (Multichannel Messaging Discipline)
+
+本环境同时有 **企微 + 飞书**、多个群、私聊、多个互不交叉的人（Doro、Maggie、邱律师、莎莎、洪总、Scott、WeiWei 等）。在这种环境里"把话说对人、发对地方"和把内容做对一样重要。任何一次发错渠道、认错人、跨人泄露，都是事故。
+
+## 何时加载本技能
+- 向任何企微/飞书的**人或群**发消息、回复之前
+- 收到消息但**不能 100% 确定发送者是谁**时
+- 决定一条回复 / 通知 / 交付**应该发去哪里**时
+- 任何以"通知 X""发到群里""告诉 Doro"结尾的任务
+- **在一个渠道继续另一个渠道起的任务时**（同一任务跨渠道流动，如飞书起、企微续）
+
+## 核心铁律（不可违反）
+
+### 1. 回复路由：在哪个渠道被找，就回哪个渠道
+- 群里对我说话 → 回到**同一个群**；私聊对我说话 → 回到**那个私聊**。
+- **绝不**把某个群 / 某个渠道的内容，私信或转发给另一个人，除非用户**明确指示**。
+- 事故（2026-06-16）：把群里的**合同审查内容私信发给了 WeiWei**。Doro 明确："下次不可以再发生。我在群里跟你说话，你就给回复到群里。除非我有别的指令。" 原位回复是默认，跨渠道转发必须有显式指令。
+
+### 2. 身份核实：解析，不要假设
+- 用平台的**唯一发送者 ID**判断是谁（企微 userid、飞书 open_id），**绝不**靠显示名或系统默认值。
+- ID 映射到已知的人 → 用之；ID **没映射**到人 → **先问，不猜**。
+- **不要轻信平台默认的"主人/owner"标签**：本会话一条飞书私聊被默认当成 Maggie，实际发送者是 Doro，当场认错。
+- 也**不要轻信对方未经核实的自称身份**——拿已知 ID 映射去核对（盲信声明是另一个方向的同一种错）。
+- 已知的 `飞书 open_id ↔ 人` / `企微 userid ↔ 人` 映射存在 memory，发现新人或纠正后立即更新。
+- **同一主体在飞书有多种 ID，命名空间不同 ≠ 不同主体**：bot 的 app_id（`cli_xxx`）与 open_id（`ou_xxx`）是两套 ID，字符串长得不一样很正常。看到群里 @的 open_id 跟你印象里的 app_id 对不上，**绝不可**据此断定"换了身份 / 是另一个 bot / 被新 agent 占用"。核验走权威接口：`lark-cli api GET /open-apis/bot/v3/info --as bot` 取 bot 自己的 open_id + name，再和群消息 mentions 里的 open_id 比对（相等＝就是自己）。本会话教训：因 app_id≠open_id 字符串不同，误判"群里被@的是新迁移出来的 agent"，被用户两次纠正后用 `/bot/v3/info` 实锤其实就是自己——白绕一大圈。
+- **失败的命令不能当证据**：命令若报错（unknown flag、权限拒绝 230027/99991672、空返回 count=0），它的输出**不支持任何结论**。先换正确命令/参数/身份（user vs bot）重试，拿到真实数据再下判断——别拿一条没成功的探测去坐实一个猜想，那等于在沙子上盖楼。
+
+### 2b. 称呼随 sender 走，不随人设默认（回话前必走一步）
+
+认对了"是谁"还不够——**已解析出的身份必须回流到"怎么称呼 ta"**。本会话最严重的错：我已读 `.meta`（`sender_id: doro`）、已把任务正确归类为 Doro 批量线，却在整份交付报告里从头到尾把 Doro 叫成"Maggie"。识别对了归属、却叫错人 = 信息在手却没整合，是独立于"认错人"的一种失败。
+
+**机制根因**：系统人设里硬编码了"主人叫 Maggie、称呼主人为 Maggie"。这条规则有个**隐含前提——当前对话者确实是主人本人**。把它当成无条件默认，就会用人设里的高频人名锚点覆盖掉会话事实。
+
+**回话前的强制自检（每次生成称呼前走一遍）**：
+1. 当前这条消息的 **sender 是谁**？取 `.meta` 的 `sender_id`，或会话 `Source / User`，**不取人设默认名**。
+2. sender **是主人本人吗**？是 → 才用主人称呼（Maggie）；**否** → 用该 sender 的真实身份（`doro → Doro`、`qiuting → 邱律师` 等）。
+3. 已核实的任务归属身份与称呼**必须一致**——不能归属判对了、抬头却写错。
+
+口诀：**人设默认名是"当对方是主人时"的条件值，不是无条件抬头。回话前先认 sender，再决定称呼。**
+
+### 3. 信息隔离
+- 每个人 / 每个团队的文件和任务，只留在该人 / 该团队的上下文里。绝不把一方的内容带进另一方的渠道，也不在 A 的群里提 B 的任务。
+- Maggie 团队 与 Doro/邱律师 团队、各客户之间，严格不交叉。
+
+### 3b. 跨渠道任务连续性（同一任务在两个渠道间流动时）
+同一个项目/任务可能在多个渠道接力推进——典型：飞书上确认了方法、更新了交付物，然后转到企微继续。**记忆是跨渠道通的（用户偏好、规则、文件位置都在），但每个渠道的对话上下文是隔离的**：飞书刚说的话不会自动进企微会话。所以\"接力续做\"前必须主动对齐，否则会拿旧认知在新渠道做事、重复已完成的工作、或漏掉刚确认的结论。
+
+**续做铁律：先对齐，再动手。**
+1. **用 `session_search` 把另一渠道的最新成果拉回来**——搜项目名/关键结论（如\"世茂 千分号 汇总表\"），读出对方渠道刚确认了什么、交付物更新到哪一版。不要凭这边的旧记忆假设进度。
+2. **从权威源核实交付物现状**，不信任\"我记得\"——交付物（Nextcloud xlsx/docx）以实际文件为准，拉最新版打开看，确认版本/时间戳/内容与对方渠道的结论一致。
+3. **回应用户关心的具体修改/结论时，先复述对齐结果**（\"飞书那边刚确认的 X、更新的 Y 我已接收\"），让用户确认我们站在同一起点，再往下做。
+4. **渠道中断会留缺口**：若某渠道掉线过（如企微群订阅失效两小时），那段时间该渠道里别人发的内容这边是空白。续做前主动提示用户\"X 时段后若有人在该渠道发过东西，我没收到，请补给我\"，避免任务断档——尤其客户对接渠道（隔离铁律下漏收=对接出窟窿）。
+
+> 实证（2026-06-18 南通新东方/世茂）：用户在飞书确认了 OCR 千分号/百分号识别法 + 更新了世茂汇总表，然后转企微说\"继续过世茂合同\"。正确做法是先 session_search 把飞书成果对齐、从 Nextcloud 拉最新版 xlsx 读出 4 份合同结构，再请用户给逐条指令——而不是在企微凭旧上下文直接开干。同期企微群因订阅失效（errcode 846609）静默两小时，须提示用户补回漏收的群消息。
+
+### 4. 发送前三项核对（任何别人能看到的消息）
+发出去前确认：
+1. **收件人**——确切的人或群，解析出 chat_id / user_id（不要凭印象挑一个）
+2. **内容**——要发的正文
+3. **以谁的身份发**——bot 还是 user
+工具支持时**先 dry-run**，确认 payload 无误再正式发；发完把回执（message_id + 北京时间）报给用户便于核对。
+
+### 5. 平台内账号/身份管理请求：把它当成“账号操作”，不是“消息回复”
+当用户让你**登录某个平台上的账号、修改密码、完成首次登录、维护个人账号资料**时，默认这是一个**账号操作任务**，不是跨人沟通任务。此时重点从“回哪个群/私聊”切换为：
+
+1. **先区分是否是“当前 agent 自己要持有的账号”**
+   - 用户明确说“这是你的账号”“你自己管理好密码” → 可由 agent 自行设置并保管该账号密码。
+   - 如果是代表某个真人同事/用户持有的账号，且对方未授权 agent 自定密码 → 不能擅自决定长期密码。
+2. **执行后要给结果，不要停在征求式废话**
+   - 用户已明确授权 agent 自主管理密码时，直接完成修改并回报“已完成”。
+   - 不要在已获授权的情况下继续追问“你想设什么密码”。
+3. **账号管理与消息路由隔离**
+   - 账号是平台内身份，不等于消息发送对象；不要因为会话对方是谁，就把账号密码策略误当成需要对方逐项确认的沟通动作。
+4. **汇报风格要结果导向**
+   - 这类任务完成后，优先回：是否登录成功、是否已改密、页面确认信息。
+   - 不展开无关解释，避免把简单账号操作说成审批流程。
+
+### 5. 用户要求“重新查 / 不要用记忆 / 用文件夹里的问题件”时，立即切换到证据模式
+这类指令不是语气提醒，而是**明确纠偏**：之前的回答被认为混入了记忆、推断或口径漂移。后续必须把“回复别人”切回“基于当前文件/当前目录/当前记录的实查结果”。
+
+执行要求：
+1. **停止沿用上一条摘要口径**——哪怕上一条是自己刚写的，也不能继续复述；
+2. **以用户指定的载体为准重新取证**：
+   - 说“用文件夹里的问题件” → 先看该文件夹实际有哪些文件；
+   - 说“打开文件查” → 必须打开文件或其内部结构（如 docx XML）再说；
+   - 说“不要用记忆” → 禁止用 memory / 旧会话印象补缀事实；
+3. **结论按证据强弱分层表达**：
+   - 能被当前文件直接坐实的，就说“可确认”；
+   - 只能证明“文件存在”但不能证明“属于该批问题件/pass件”的，就明确写“目前只能确认存在，不能据此归类”；
+4. **不要把“在任务交付目录里存在”偷换成“就是问题件 / 已 pass / 属于同一批”**；
+5. **汇报时先交代证据来源**（查了哪个目录、哪份问题汇总、是否打开了文件），再给结论。
+6. **用户说“我就要一个结果”时，停止过程化解释**：这类话表示对方当前只接受最终答案，不要再补背景、过程、严谨性铺垫。先给一句结论；如对方追问，再展开证据链。
+
+一句话：**用户说“重新查”时，先把脑子里的版本清空，回到文件本身；用户说“只要结果”时，先把话收成结论。**
+
+## 实操配方
+- **飞书群里接收文件/图片**：飞书不允许文件和文字（@mention）在同一条消息里。解决方案：用户先发文件/图片，再对那条消息点「回复」并在回复里@小 Maggie。Gateway 的 `_fetch_parent_media` 方法会自动从被引用的 parent 消息中下载附件（2026-07-11 补丁）。文件缓存路径：`~/.hermes/cache/documents/`。图片同理——用户发图后回复+@即可。
+- 飞书群发消息 + @人（找群、@格式、dry-run、核对回执）：见 `references/feishu-group-send-and-mention.md`
+- **飞书 bot 在群里不回、私聊却正常**的诊断配方（gateway inbound vs 群真实历史对照、查 `mentions[].id` 的 open_id 识别同名 bot 撞名、`--as user` 读群历史）：见 `references/feishu-bot-silent-in-group-diagnosis.md`
+- 企微发文件 / 私信机制：见 `wecom-file-send-receive` 技能（MEDIA: 标签发文件；私信走独立 WS aibot_send_msg，chatid=userid+chat_type=1）
+- **企微私信非 home 的人（Doro/邱律师/WeiWei 等）→ 用 `~/.hermes/scripts/wecom_dm.py`，不要用 `send_message` 工具**：
+  - `send_message(target='wecom:WeiWei')` 对非 home 的 wecom 用户会**静默回退到 home channel**（实测返回 `chat_id: JiaQian` + note `Sent to wecom home channel`），**不报错**——一条发给 WeiWei 的技术讨论就这样落到了 Maggie 渠道，同时违反信息隔离。
+  - 正确做法（agent 可直接 terminal 调用，自开 WS、永不退化成回复、目标唯一）：
+    ```bash
+    python3 ~/.hermes/scripts/wecom_dm.py --list                       # 先看白名单别名↔userid
+    python3 ~/.hermes/scripts/wecom_dm.py --to WeiWei --text "…" --dry-run   # 演练
+    python3 ~/.hermes/scripts/wecom_dm.py --to WeiWei --text "…"        # 真发，回执含 message_id
+    ```
+  - 别名：`doro / jiaqian / qiuting / weiwei / shasha / yangayi / xiaonan`（`--list` 为准）。这是 `references/wecom-proactive-notify-misrouting.md` 修复方向 A 在脚本层的现成实现，**比 `_send_wecom(extra,…)` 更可用**（后者需 gateway 内部 `extra`，agent 会话里拿不到）。
+- 企微主动通知**错投到错误的人**（"给 Doro 的消息发给了 Maggie"）的根因 + 只读诊断配方 + 修复方向：见 `references/wecom-proactive-notify-misrouting.md`
+
+## Pitfalls
+- **把群任务的处理结果私信给"相关的人"**——即使你觉得对方该知道，也不行。原位回群，要不要另外通知由用户决定。
+- **靠会话默认值认人**——私聊默认 owner 不等于当前发送者，必须看 sender ID。
+- **拿\"两个长得不一样的 ID 字符串\"推断成\"两个身份/新迁移出的 agent\"**——同一个实体在不同命名空间有多种 ID，长相不同是常态：飞书机器人的 `app_id`（`cli_xxx`）与它的 `open_id`（`ou_xxx`）本就不一样，**两者是同一个 bot**。事故（2026-06-22 与 WeiWei 排障）：我把群里被 @ 的 `ou_20bd8…`（open_id）和 gateway 配置里的 `cli_aaa4e77d27789bed`（app_id）当成两个 bot，进而臆断\"有个新迁移出来的 agent 占用了身份\"，被纠正\"迁移还没开始\"。下结论前用**权威身份接口**核对：`LARK_CLI_NO_PROXY=1 lark-cli api GET /open-apis/bot/v3/info --as bot` 返回的 `open_id`/`app_name` 才是 bot 真身——拿它去比对，再判断是不是同一个。
+- **从一条 errored 的命令里读出\"结论\"**——同一次排障里，我那条查 bot open_id 的命令其实用错了 flag、根本没返回结果，我却继续往\"新身份\"上跳。**命令报错 = 没有证据，不是证据**；拿到真实返回再推理，别把工具失败当成支持自己假设的信号。
+- **同名 bot 撞名 = @ 显示名 ≠ @ 到你这个 app**：群里可能存在两个同名「小Maggie」（典型触发：做过新 Agent 迁移 / provisioning，新身份被拉进群）。用户 @ 显示名时飞书解析到的是某个 open_id，若那不是当前 gateway 跑的 app_id，事件流根本收不到，bot"静默不回"，但 DM 仍正常（DM 按会话路由、不按 @ 身份）。诊断时必须查群消息 `mentions[].id` 的 open_id 和当前 bot app_id 是否一致，别一看不回就报"掉线"。完整配方见 `references/feishu-bot-silent-in-group-diagnosis.md`。
+- **认对了人却叫错称呼**——已解析出 sender 是 Doro，抬头却写"Maggie"。人设里"主人叫 Maggie"是"当对方是主人时"的条件值，不是无条件抬头；归属身份必须回流到称呼（见 2b）。
+- **session 无 .meta / sender 信息时，从文件内容或"印象"推断发件人**——事故(2026-07-13)：session JSON 的 user message 里无 sender_id metadata，我从合同内容（青浦区卫生机构）推断是"刘婷律师"，实际 gateway 日志明确显示 `user=QiuTing`（邱律师）。**当 session 记录不含 sender 信息时，必须查 gateway 日志（`~/.hermes/logs/gateway.log`）确认 `inbound message: platform=wecom user=XXX` 才能定身份**，绝不可从文件内容、以往经验、或"谁经常发这类合同"去猜。`grep "时间段" ~/.hermes/logs/gateway.log | grep "inbound"` 是唯一权威来源。
+- **猜 chat_id / group**——发前用 `lark-cli im +chat-list --as bot` 把 bot 实际所在的群列出来，挑出你和目标人共处的那个，别凭记忆。
+- **企微 @通知**：aibot_send_msg 只支持 markdown，不支持 text+mentioned_list，无法真正 @人；需要提醒时另发一条私信利用其消息提醒（仅在用户允许、且不违反路由铁律的前提下）。
+- **自动化脚本会替你发消息**：`auto_notify_new_file.sh` 等脚本会自动私信。处理任务前留意有没有自动化机制正在按旧规则推送，避免它替你违反路由 / 隔离铁律。
+- **`wecom_group_notify.py` 和 `wecom_dm.py` 是两个完全不同的脚本，不可混用（2026-07-01教训）**：Doro说"私信邱律师"，用了 `wecom_group_notify.py`（默认发到批量合同审查群 `wrbAFkXAAAiWC3styKqNj0bZyH6BbJ_Q`），消息发到了群里而不是邱律师私信。**发前看清脚本名**：`wecom_dm.py` = 私信；`wecom_group_notify.py` = 群通知。workflow YAML 中通知邱律师的脚本也必须用 `wecom_dm.py --to qiuting`，不是 `wecom_group_notify.py`。
+- **`send_message` 工具私信企微人会静默投错**：`send_message(target='wecom:<user>')` 对非 home channel 的 wecom 用户**不报错、直接回退到 home channel**（实测发给 WeiWei 却落到 JiaQian/Maggie）。这是单点事故——既没到目标人、又跨团队泄露。私信非 home 的企微人一律走 `~/.hermes/scripts/wecom_dm.py --to <alias>`（见上"实操配方"），别用 `send_message`。发完核回执里的 userid 是不是目标人，发现是 home channel 立即用脚本补发。
+- **"给 X 的消息错投给 Y"先查 adapter 回复兜底，别先怪 userid**：企微 `WeComAdapter.send()` 在主动 `aibot_send_msg` 前有一段 `_last_chat_req_ids[chat_id]` 回复兜底——主动私信可能**退化成"回复某条历史消息"**，在多人并发的长跑 gateway 里串到别人头上。userid 往往是对的（`doro/JiaQian/QiuTing` 都是独立真实 ID），错在路径。诊断配方 + 根因 + 三个修复方向见 `references/wecom-proactive-notify-misrouting.md`。注意 `workflow-watchdog.sh` 仍硬编码 `_send_wecom(extra,'doro',msg)`，是未拆的隐患。

skills/communication/multichannel-messaging-discipline/references/feishu-bot-silent-in-group-diagnosis.md

@@ -0,0 +1,56 @@
+# 飞书 bot 在群里静默、私聊却正常 —— 诊断配方
+
+实证：2026-06-22 群「小Maggie工作群」(`oc_a927f86118216c36cb9394b0e95f2a11`)。WeiWei/颜伽艺在群里 @小Maggie 无反应，私聊正常。
+
+## 症状
+- 用户在飞书**群**里 @小Maggie，bot 不回。
+- 但**私聊**（DM）发消息 bot 正常回复。
+- gateway 进程活着，飞书连接日志显示 `[Feishu] Connected in websocket mode`。
+
+## 根因类别（按概率排序）
+1. **身份不匹配（display-name 撞名）** — 群里被 @ 的「小Maggie」其实是**另一个 bot 身份**（不同 open_id），不是当前 gateway 跑的那个 app。常见触发：做过「新 Agent 迁移 / provisioning」，新身份被拉进群并占用了群里「小Maggie」的 @ 目标。群 @ 解析到新身份的 open_id，旧 gateway（旧 app_id）的事件流里根本收不到这条，所以"不回"。**DM 仍正常，因为 DM 按会话路由、不按 @ 身份。** ← 本会话确诊就是这一类。
+2. 订阅/连接在空窗后失效（同类：企微 errcode 846609 静默两小时）。
+3. 发送侧失败：历史上见过 `[99992402] field validation failed`（连 plain-text 兜底也失败）——这是**发**不出去，不是**收**不到，必须区分。
+
+## 诊断步骤（命令均已实测可用）
+所有 lark-cli 命令加 `LARK_CLI_NO_PROXY=1` 前缀，避免凭据走 HTTPS_PROXY。
+
+**1. 确认 bot 在哪些群、拿群 chat_id：**
+```bash
+LARK_CLI_NO_PROXY=1 lark-cli im +chat-list --as bot
+```
+
+**2. 查 gateway 实际收到了这个群的哪些 inbound：**
+```bash
+grep "oc_<群id>" ~/.hermes/logs/gateway.log | grep -iE "Inbound|inbound message"
+```
+若最后一条 inbound 停在很久以前、之后空白 → gateway 根本没收到新群消息（排除"收到但没回"）。
+
+**3. 拉群的真实消息历史，和第 2 步对照：**
+> bot 身份读群历史会因缺 scope 失败：`+chat-messages-list --as bot` → 230027 / 99991672，缺 `im:chat:readonly` `im:chat.members:read`。**改用 `--as user`**。
+```bash
+LARK_CLI_NO_PROXY=1 lark-cli im +chat-messages-list \
+  --chat-id oc_<群id> --as user --order desc --page-size 30 --no-reactions --format json
+```
+返回 JSON 字段：`data.messages[]`，每条含 `content`(直接是文本)、`create_time`、`sender.{id,sender_type,name}`、`mentions[].{id,name}`。**注意不是 `items`/`body`** —— 用错字段会得到 `count=0` 的假空，误判成"群里没人发"。
+
+**4. 关键判定 —— 看 @ 到的是谁的 open_id：**
+群消息的 `mentions[].id` 就是被 @ 对象的 open_id。和当前 gateway 的 bot 身份对比：
+```bash
+# 当前 gateway 用的飞书 app_id
+python3 -c "import yaml;c=yaml.safe_load(open('/home/maggie/.hermes/config.yaml'));print(c['gateway']['platforms']['feishu'].get('extra',{}).get('app_id'))"
+```
+- 对照法：第 2 步里 gateway 正常工作时段，bot 在群里发言的 sender 是 `app cli_<app_id>`。拿这个和第 4 步 mentions 里「小Maggie」的 open_id 比。
+- 若群历史里「小Maggie」被 @ 的 open_id ≠ 当前 gateway bot 的身份 → **确诊身份不匹配**：群里有两个同名「小Maggie」，大家 @ 错了。
+
+**5. 旁证：DM 是否正常。** 私聊 inbound 在 gateway.log 里照常出现 → 证明连接/订阅活着，问题收敛到"群 @ 身份"这一层。
+
+## 结论怎么报
+- 这是技术/配置问题，按铁律修复决策交给技术负责人（WeiWei/Scott），不自作主张改。
+- 给三个方向：①新 Agent 接管群（@ 目标对到新身份 / 把新身份订阅配通）；②仍由旧 bot 管群（移除或换回群里的新「小Maggie」）；③过渡期走私聊。
+
+## Pitfalls
+- **别一看 bot 没回就说"掉线了"** —— 先分清"没收到（群 @ 身份不对 / 订阅失效）" vs "收到但没发出去（send 失败 99992402）"。
+- **lark-cli 读群历史/群成员要用 `--as user`**，bot 身份缺 scope。要让 bot 自己能读，得在开放平台给 `cli_xxx` 补 `im:chat:readonly` `im:chat.group_info:readonly` `im:chat.members:read`。
+- **JSON 字段名**：`+chat-messages-list` 返回 `data.messages[].content`，不是 `items[].body`。用错字段会得到误导性的 `count=0`。
+- **重启时 DNS 抽风是环境问题，不是代码问题** —— 重启日志里若有 `Temporary failure in name resolution`（open.feishu.cn / openws.work.weixin.qq.com），那是当时网络/DNS 短暂故障；飞书多半自己重连上了，企微可能没重连成功，单独核实企微在线状态即可，别当成代码 bug 去改。

skills/communication/multichannel-messaging-discipline/references/feishu-group-send-and-mention.md

@@ -0,0 +1,88 @@
+# 飞书群发消息 + @人（已验证配方 2026-06-16）
+
+目标：把消息发到**正确的飞书群**并 **@ 正确的人**，一次做对。依赖 `lark-cli`（lark-im 技能）。
+
+## 步骤
+
+### 1. 找出 bot 实际所在的群（不要猜 chat_id）
+```bash
+cd ~ && lark-cli im +chat-list --as bot
+```
+返回每个群的 `chat_id`、`name`、`description`、`owner_id`。挑出你和目标人**共处**的那个群。
+- 本环境已知群："Doro, Maggie, 魏玮"（描述"小Maggie工作群"）= `oc_a927f86118216c36cb9394b0e95f2a11`。
+- 若有多个候选群，按成员和描述确认，仍不确定就问用户，别赌。
+
+### 2. @人的格式（两种已验证写法，均触发真实可点击 @ + 通知）
+- **text 模式**：`--msg-type text`，content 形如 `{"text":"<at>…</at> 正文"}`，@ 标签 `<at user_id="ou_xxx">显示名</at>`（用 **open_id**；嵌进 JSON 字符串时内层引号按 JSON 规则转义）。@所有人 `<at user_id="all"></at>`。
+- **post 模式**（多行/结构化汇报推荐，2026-06-16 已验证）：post JSON 里 @ 用 at 元素 `{"tag":"at","user_id":"ou_xxx"}`，与文本元素 `{"tag":"text","text":"…"}` **同行**拼接，配 `--msg-type post`。结构：
+  `{"zh_cn":{"content":[[{"tag":"at","user_id":"ou_757f053c9d7aff6c73b18aa60c337756"},{"tag":"text","text":" 进展汇报…"}],[{"tag":"text","text":"第二行"}]]}}`
+- **不要用 `--markdown`** 发 @：会强制转 post 且 @ 处理不可靠，用显式 post JSON 自己控制。
+
+### 3. 先 dry-run 验证 payload
+```bash
+lark-cli im +messages-send --chat-id oc_xxx --as bot \
+  --content '{"text":"<at user_id=\"ou_757f053c9d7aff6c73b18aa60c337756\">Doro</at> 正文…"}' \
+  --msg-type text --dry-run
+```
+检查 body 里 chat_id、msg_type、@标签是否正确。
+
+### 4. 去掉 --dry-run 正式发送
+成功返回 `message_id` + `create_time`。把 message_id 和**北京时间**报给用户便于核对。
+
+## 发送前如何核实「这个 open_id 确实是目标本人」
+@错人是红线。理想是查通讯录，但本 bot **常缺 contact / chat 读权限**，按可靠性从高到低：
+
+1. **gateway.log 取地面真值（最可靠，无需任何 scope）**——平台事件原始数据，比 API、比记忆都硬：
+   ```bash
+   grep "oc_<群id>" ~/.hermes/logs/gateway.log | grep -oE "ou_[a-z0-9]{20,}" | sort | uniq -c | sort -rn
+   ```
+   再看「当前这条消息」的入站行确认发送者：
+   ```bash
+   grep "inbound message: platform=feishu" ~/.hermes/logs/gateway.log | tail
+   # → user=ou_xxx chat=oc_xxx msg='…' 即是谁在这个群说了这句话
+   ```
+   把刚收到那句话的 `user=ou_xxx` 与已知映射比对，一致才发。
+2. **已知 open_id 映射**（下方表 + memory），ID 没映射到人 → 先问不猜。
+3. **通讯录 API（常被 scope 挡）**：`lark-cli contact +get-user --user-id ou_xxx --user-id-type open_id --as user`。本环境 2026-06-16 报缺 `contact:user.basic_profile:readonly`；`im chat.members get` 也缺 `im:chat.members:read` 等。缺权限是**正常状态**，别卡在这里——退回方法 1。
+
+## 已知 open_id（核对身份用，新增/纠正后同步到 memory）
+- Doro = `ou_757f053c9d7aff6c73b18aa60c337756`（与 bot 私聊 chat=`oc_9292e11bd98ddb5a69ea2c2da10d4f12`）
+- Scott(魏玮) = `ou_04fade9a9335c09ad09846da2051b3c0`
+
+## 注意
+- `--as bot`：消息以应用 bot 名义发出，bot 必须已在目标群里。
+- lark-cli 是 API 工具，不是消息网关；bot 身份不代理用户（Scott 已纠正）。
+- 终端里 lark-cli 输出常带 HTTPS_PROXY 的 WARN 和版本更新 notice，是噪音，不影响结果；可 `grep -v "WARN\|proxy"` 过滤。
+
+## 发文件附件到群里（md/pdf/docx 报告，已验证）
+
+要把一份**文件**（错误分析 md、合同 docx、报告 pdf）发到群里，用 `--file`。常见组合：**先发文件附件，再发一条 @某人 的 post 说明**（文件本身不能 @ 人，说明消息负责 @）。
+
+```bash
+# 先发文件（--file 接 cwd 相对路径），成功返回 message_id 并打印 "uploading file: xxx"
+cd ~/lark_send_tmp && lark-cli im +messages-send \
+  --chat-id oc_a927f86118216c36cb9394b0e95f2a11 \
+  --as bot --file "./报告.md" \
+  --dry-run 2>&1 | grep -v "WARN\|proxy"   # 先 dry-run，确认后去掉 --dry-run
+# 再发 @某人 的 post 说明（见上「@人的格式」post 模式），把文件背景+要点写清楚
+```
+
+### ⚠️ 关键坑：`--file` 只接 cwd 相对路径，绝对路径被拒
+lark-cli 安全限制：`--file`（及 `--image`/`--video`/`--audio`）**拒绝绝对路径**（如 `/tmp/x.md`），路径解析 `..`/symlink 后必须仍在 cwd 内。
+**解法**：把文件复制到干净工作目录，`cd` 进去用 `./文件名` 发：
+```bash
+mkdir -p ~/lark_send_tmp && cp "/tmp/报告.md" ~/lark_send_tmp/
+cd ~/lark_send_tmp && lark-cli im +messages-send --chat-id oc_xxx --as bot --file "./报告.md"
+rm -rf ~/lark_send_tmp   # 发完清理
+```
+- 本地文件 lark-cli 会**先自动上传**再发 file 消息，无需手动 `images.create`/拿 file_key。
+- dry-run 时 file_key 显示占位符 `file_dryrun_upload` 是正常的，正式发送才真上传。
+- 同理发图片用 `--image ./x.png`，视频 `--video ./x.mp4 --video-cover ./cover.png`。
+
+## 已知群与人 ID（核对身份用）
+| 对象 | ID |
+|------|-----|
+| 飞书工作群"Doro, Maggie, 魏玮"（小Maggie工作群） | `oc_a927f86118216c36cb9394b0e95f2a11` |
+| Doro | `ou_757f053c9d7aff6c73b18aa60c337756`（私聊 chat `oc_9292e11bd98ddb5a69ea2c2da10d4f12`，别和群混） |
+| Scott / 魏玮 | `ou_04fade9a9335c09ad09846da2051b3c0` |
+| @所有人 | `all` |

skills/communication/multichannel-messaging-discipline/references/wecom-proactive-notify-misrouting.md

@@ -0,0 +1,74 @@
+# 企微主动通知错投到错误的人 — 根因与诊断
+
+**症状**：一条本应私信给 A（如 Doro）的**主动通知**，落到了 B（如 JiaQian/Maggie）的企微私信里。
+实证（2026-06-17，Maggie 飞书原话）：私信收到"收到 JiaQian 发来的文件…请问如何处理？"——这条内容本应发给 Doro，却投到了 JiaQian 本人。
+
+**关键澄清：不是 userid 传错。** 会话 DB 里 `doro / JiaQian / WeiWei / ShaSha / QiuTing` 都是**各自独立的真实企微 userid**，`chat_id="doro"` 本身指向的就是 Doro。错投来自下面两个机制叠加，而非地址写错。
+
+## 根因 1：发送者归属靠"猜"（旧 `auto_notify_new_file.sh`）
+旧版 `get_sender()` 查 session DB 取"最近 5 分钟最后一个会话"：
+```sql
+SELECT user_id FROM sessions
+WHERE source='wecom' AND started_at > (now-300)
+ORDER BY started_at DESC LIMIT 1
+```
+多人**并发**时，这个"最近活跃会话"经常不是真正发文件的人 → 发件人张冠李戴。
+
+**已修复**：企微 adapter 落盘缓存文件时写 `.meta` 边车文件（`~/.hermes/cache/documents/<file>.meta`，字段 `sender_id / chat_id / chat_type`）。脚本改读 `${filepath}.meta`，不再靠"最近会话"猜。验证：`.meta` 内容形如 `sender_id=doro chat_id=doro type=dm`。
+
+## 根因 2：主动私信会"退化成回复"导致串号（adapter 层）
+`gateway/platforms/wecom.py` `WeComAdapter.send(chat_id, content)` 在做主动 `aibot_send_msg` 前有一段**回复优先兜底**（约 1430–1445 行）：
+```python
+reply_req_id = self._reply_req_id_for_message(reply_to)
+if not reply_req_id and chat_id in self._last_chat_req_ids:
+    reply_req_id = self._last_chat_req_ids[chat_id]   # ← 退化点
+if reply_req_id:
+    response = await self._send_reply_markdown(reply_req_id, content)  # 回复某条历史消息，而非主动私信
+else:
+    payload = {"chatid": chat_id, "msgtype": "markdown", ...}
+    if not chat_id.startswith("wr"):      # 群 ID 以 "wr" 开头；非 "wr" 当私聊
+        payload["chat_type"] = 1          # 主动单聊
+    response = await self._send_request(APP_CMD_SEND, payload)
+```
+`_last_chat_req_ids[chat_id]` 由**入站流量**填充（`_remember_chat_req_id`，约 533 行）。在长跑的 gateway 常驻进程里、多人并发时，某个 `chat_id` key 上记住的 `req_id` 可能绑定到**归属于另一个人的会话上下文**——于是"发给 doro"退化成"回复那条 req_id"，落到错误的人头上。
+
+> 注意两个独立的 dict：`_reply_req_ids`（按 **message_id** 存，给显式 `reply_to` 用）和 `_last_chat_req_ids`（按 **chat_id** 存，作群聊无 `reply_to` 时的兜底）。错投走的是后者这条 chat_id 兜底路径。
+
+## 谁还在踩这条路径（主动私信脚本）
+任何脚本调用 `_send_wecom(extra, 'doro', msg)` → `adapter.send()` 都会经过上面的回复兜底，存在同样的串号风险。已知：
+- `auto_notify_new_file.sh`：**主循环已不再调用** `notify_doro()`（非 QiuTing 文件只记日志、不通知任何人，符合信息隔离铁律；QiuTing 走静默 workflow 不发中间通知）。`notify_doro()` 函数仍**定义着**但无调用点 → 主路径安全。
+- `workflow-watchdog.sh`：其 `notify()` **仍在用** `_send_wecom(extra, 'doro', msg)`，workflow 崩溃重启时会触发，**未拆除的隐患**（低频但路径有风险）。
+
+## 修复方向（动手前须经用户确认，勿擅改代码/脚本）
+- **A（最稳）**：给 adapter 加"强制主动私信"参数，让脚本类通知**绕过 `_last_chat_req_ids` 回复兜底**，永远走 `chat_type=1` proactive 直发。一次修复，所有脚本受益。涉及代码库，宜拉熟代码的人（WeiWei）评审。
+- **B（最快）**：把 `workflow-watchdog.sh` 的通知目标改到本机日志/Scott，彻底不碰串号路径。改动小。
+- **C（最保守）**：先出一页纸根因+修复评审文档，定了再动。
+
+### ✅ 方向 A 已有现成实现：`~/.hermes/scripts/wecom_dm.py`（agent 可直接用）
+不必等改 adapter——这个独立脚本已经实现了"强制主动私信、绕过回复兜底"：自开 WebSocket，`aibot_subscribe` 认证后直接 `aibot_send_msg + chat_type=1`，**永不退化成回复**，一条消息=一次干净 proactive send、目标唯一。带 `--list` 白名单（别名↔userid 三方交叉验证）、`--dry-run`、回执 message_id。
+```bash
+python3 ~/.hermes/scripts/wecom_dm.py --list
+python3 ~/.hermes/scripts/wecom_dm.py --to doro --text "…" --dry-run
+python3 ~/.hermes/scripts/wecom_dm.py --to doro --text "…"
+```
+凡是 agent 会话里要私信某个企微人（绕开 home channel）的场景，**首选这个脚本**，而不是 `send_message(target='wecom:…')`（会静默落 home channel）或 `_send_wecom(extra,…)`（需 gateway 内部 `extra`，会话里拿不到）。`workflow-watchdog.sh` 等仍硬编码 `_send_wecom(extra,'doro',…)` 的脚本，理想改法就是切到这个干净发送器。
+
+## 诊断配方（只读，安全）
+```bash
+# 1. 脚本实际发了什么、发给谁（看 chat_id 与回执）
+tail -n 80 /tmp/auto_notify_new_file.log
+grep -aiE "Sending response .* to|aibot_send|chat_type|私信" ~/.hermes/logs/agent.log | tail -30
+
+# 2. 真实 userid ↔ 人 映射（确认不是地址写错）
+cd ~/.hermes/hermes-agent && source venv/bin/activate
+python3 -c "import sqlite3;d=sqlite3.connect('$HOME/.hermes/state.db');[print(r) for r in d.execute(\"SELECT user_id,COUNT(*),MAX(started_at) FROM sessions WHERE source='wecom' GROUP BY user_id ORDER BY 2 DESC\")]"
+
+# 3. .meta 边车归属是否正确
+find ~/.hermes/cache/documents -name '*.meta' -exec cat {} \;
+
+# 4. 谁还在用 doro 硬编码主动发送
+# search_files pattern: _send_wecom|DORO_ID="doro"  在 ~/.hermes/scripts
+```
+
+## 一句话结论
+"给 X 的消息错投给 Y"在企微里**首查 adapter 的 `_last_chat_req_ids` 回复兜底**与**脚本的发件人归属逻辑**，不要一上来就怀疑 userid 写错——userid 往往是对的，错在"主动私信退化成回复历史消息"。

skills/github/DESCRIPTION.md

@@ -0,0 +1,3 @@
+---
+description: GitHub workflow skills for managing repositories, pull requests, code reviews, issues, and CI/CD pipelines using the gh CLI and git via terminal.
+---

skills/github/github/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: github
+description: "GitHub workflow: auth setup, PR lifecycle, code review, issue management, repo operations. Covers gh CLI and curl fallbacks."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Git, Pull-Requests, Code-Review, Issues, Repositories, gh-cli]
+---
+
+# GitHub Workflow — Complete Guide
+
+End-to-end GitHub operations: authentication, repository management, PR lifecycle, code review, and issue tracking. Every section shows `gh` CLI first, then `git` + `curl` fallback for machines without `gh`.
+
+## Quick Auth Check
+
+Run this at the start of any GitHub workflow:
+
+```bash
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  echo "AUTH_METHOD=gh"
+elif [ -n "$GITHUB_TOKEN" ]; then
+  echo "AUTH_METHOD=curl"
+elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+  export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+  echo "AUTH_METHOD=curl"
+else
+  echo "AUTH_METHOD=none — need to set up auth first"
+fi
+```
+
+See `references/auth.md` for complete auth setup (HTTPS tokens, SSH keys, gh CLI login, troubleshooting).
+
+## Operations Overview
+
+| Task | Reference | Key Commands |
+|------|-----------|-------------|
+| **Auth setup** | `references/auth.md` | `gh auth login`, SSH keys, credential helpers |
+| **Repo management** | `references/repo-management.md` | clone, create, fork, releases, secrets, Actions |
+| **PR lifecycle** | `references/pr-workflow.md` | branch, commit, open, CI monitoring, merge |
+| **Code review** | `references/code-review.md` | local diff review, PR comments, inline review, submit review |
+| **Issue management** | `references/issues.md` | create, triage, label, assign, bulk operations |
+| **Codebase inspection** | `references/codebase-inspection.md` | LOC counts, language breakdown, code-vs-comment ratios via pygount |
+
+## Common Patterns
+
+### Creating a Feature PR (end-to-end)
+1. Branch: `git checkout -b feat/description`
+2. Commit with conventional format: `feat(scope): description`
+3. Push: `git push -u origin HEAD`
+4. Open PR: `gh pr create --title "..." --body "..."`
+5. Monitor CI: `gh pr checks --watch`
+6. Merge: `gh pr merge --squash --delete-branch`
+
+See `references/pr-workflow.md` for the complete lifecycle with CI auto-fix loops.
+
+### Reviewing a PR
+1. Get PR context: `gh pr view N` + `gh pr diff N --name-only`
+2. Check out locally: `git fetch origin pull/N/head:pr-N && git checkout pr-N`
+3. Read diff + full files with `read_file`
+4. Apply review checklist (correctness, security, quality, testing, performance)
+5. Submit: `gh pr review N --approve|--request-changes|--comment`
+
+See `references/code-review.md` for inline comments, formal reviews, and the review checklist.
+
+### Triaging Issues
+1. List untriaged: `gh issue list --label "needs-triage"`
+2. Categorize and apply labels
+3. Assign if owner is clear
+4. Comment with triage notes
+
+See `references/issues.md` for templates, bulk operations, and linking issues to PRs.
+
+## Support Files
+
+### References
+- `references/auth.md` — Full authentication setup and troubleshooting
+- `references/repo-management.md` — Clone, create, fork, settings, releases, secrets, Actions, gists
+- `references/pr-workflow.md` — Branch creation, commits, CI monitoring, auto-fix, merging
+- `references/code-review.md` — Local review, PR review, inline comments, formal review submission
+- `references/issues.md` — Create, manage, triage, bulk operations
+- `references/conventional-commits.md` — Commit message format conventions
+- `references/ci-troubleshooting.md` — Diagnosing and fixing CI failures
+- `references/review-output-template.md` — Structured review output format
+- `references/github-api-cheatsheet.md` — GitHub REST API endpoint quick reference
+
+### Templates
+- `templates/bug-report.md` — Bug report issue template
+- `templates/feature-request.md` — Feature request issue template
+- `templates/pr-body-bugfix.md` — PR body template for bug fixes
+- `templates/pr-body-feature.md` — PR body template for features
+
+### Scripts
+- `scripts/gh-env.sh` — Source this to set up GitHub auth env vars in shell

skills/github/github/references/auth.md

@@ -0,0 +1,247 @@
+---
+name: github-auth
+description: "GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Authentication, Git, gh-cli, SSH, Setup]
+    related_skills: [github-pr-workflow, github-code-review, github-issues, github-repo-management]
+---
+
+# GitHub Authentication Setup
+
+This skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths:
+
+- **`git` (always available)** — uses HTTPS personal access tokens or SSH keys
+- **`gh` CLI (if installed)** — richer GitHub API access with a simpler auth flow
+
+## Detection Flow
+
+When a user asks you to work with GitHub, run this check first:
+
+```bash
+# Check what's available
+git --version
+gh --version 2>/dev/null || echo "gh not installed"
+
+# Check if already authenticated
+gh auth status 2>/dev/null || echo "gh not authenticated"
+git config --global credential.helper 2>/dev/null || echo "no git credential helper"
+```
+
+**Decision tree:**
+1. If `gh auth status` shows authenticated → you're good, use `gh` for everything
+2. If `gh` is installed but not authenticated → use "gh auth" method below
+3. If `gh` is not installed → use "git-only" method below (no sudo needed)
+
+---
+
+## Method 1: Git-Only Authentication (No gh, No sudo)
+
+This works on any machine with `git` installed. No root access needed.
+
+### Option A: HTTPS with Personal Access Token (Recommended)
+
+This is the most portable method — works everywhere, no SSH config needed.
+
+**Step 1: Create a personal access token**
+
+Tell the user to go to: **https://github.com/settings/tokens**
+
+- Click "Generate new token (classic)"
+- Give it a name like "hermes-agent"
+- Select scopes:
+  - `repo` (full repository access — read, write, push, PRs)
+  - `workflow` (trigger and manage GitHub Actions)
+  - `read:org` (if working with organization repos)
+- Set expiration (90 days is a good default)
+- Copy the token — it won't be shown again
+
+**Step 2: Configure git to store the token**
+
+```bash
+# Set up the credential helper to cache credentials
+# "store" saves to ~/.git-credentials in plaintext (simple, persistent)
+git config --global credential.helper store
+
+# Now do a test operation that triggers auth — git will prompt for credentials
+# Username: <their-github-username>
+# Password: <paste the personal access token, NOT their GitHub password>
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+```
+
+After entering credentials once, they're saved and reused for all future operations.
+
+**Alternative: cache helper (credentials expire from memory)**
+
+```bash
+# Cache in memory for 8 hours (28800 seconds) instead of saving to disk
+git config --global credential.helper 'cache --timeout=28800'
+```
+
+**Alternative: set the token directly in the remote URL (per-repo)**
+
+```bash
+# Embed token in the remote URL (avoids credential prompts entirely)
+git remote set-url origin https://<username>:<token>@github.com/<owner>/<repo>.git
+```
+
+**Step 3: Configure git identity**
+
+```bash
+# Required for commits — set name and email
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+**Step 4: Verify**
+
+```bash
+# Test push access (this should work without any prompts now)
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+
+# Verify identity
+git config --global user.name
+git config --global user.email
+```
+
+### Option B: SSH Key Authentication
+
+Good for users who prefer SSH or already have keys set up.
+
+**Step 1: Check for existing SSH keys**
+
+```bash
+ls -la ~/.ssh/id_*.pub 2>/dev/null || echo "No SSH keys found"
+```
+
+**Step 2: Generate a key if needed**
+
+```bash
+# Generate an ed25519 key (modern, secure, fast)
+ssh-keygen -t ed25519 -C "their-email@example.com" -f ~/.ssh/id_ed25519 -N ""
+
+# Display the public key for them to add to GitHub
+cat ~/.ssh/id_ed25519.pub
+```
+
+Tell the user to add the public key at: **https://github.com/settings/keys**
+- Click "New SSH key"
+- Paste the public key content
+- Give it a title like "hermes-agent-<machine-name>"
+
+**Step 3: Test the connection**
+
+```bash
+ssh -T git@github.com
+# Expected: "Hi <username>! You've successfully authenticated..."
+```
+
+**Step 4: Configure git to use SSH for GitHub**
+
+```bash
+# Rewrite HTTPS GitHub URLs to SSH automatically
+git config --global url."git@github.com:".insteadOf "https://github.com/"
+```
+
+**Step 5: Configure git identity**
+
+```bash
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+---
+
+## Method 2: gh CLI Authentication
+
+If `gh` is installed, it handles both API access and git credentials in one step.
+
+### Interactive Browser Login (Desktop)
+
+```bash
+gh auth login
+# Select: GitHub.com
+# Select: HTTPS
+# Authenticate via browser
+```
+
+### Token-Based Login (Headless / SSH Servers)
+
+```bash
+echo "<THEIR_TOKEN>" | gh auth login --with-token
+
+# Set up git credentials through gh
+gh auth setup-git
+```
+
+### Verify
+
+```bash
+gh auth status
+```
+
+---
+
+## Using the GitHub API Without gh
+
+When `gh` is not available, you can still access the full GitHub API using `curl` with a personal access token. This is how the other GitHub skills implement their fallbacks.
+
+### Setting the Token for API Calls
+
+```bash
+# Option 1: Export as env var (preferred — keeps it out of commands)
+export GITHUB_TOKEN="<token>"
+
+# Then use in curl calls:
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user
+```
+
+### Extracting the Token from Git Credentials
+
+If git credentials are already configured (via credential.helper store), the token can be extracted:
+
+```bash
+# Read from git credential store
+grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|'
+```
+
+### Helper: Detect Auth Method
+
+Use this pattern at the start of any GitHub workflow:
+
+```bash
+# Try gh first, fall back to git + curl
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  echo "AUTH_METHOD=gh"
+elif [ -n "$GITHUB_TOKEN" ]; then
+  echo "AUTH_METHOD=curl"
+elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+  echo "AUTH_METHOD=curl"
+elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+  export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+  echo "AUTH_METHOD=curl"
+else
+  echo "AUTH_METHOD=none"
+  echo "Need to set up authentication first"
+fi
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `git push` asks for password | GitHub disabled password auth. Use a personal access token as the password, or switch to SSH |
+| `remote: Permission to X denied` | Token may lack `repo` scope — regenerate with correct scopes |
+| `fatal: Authentication failed` | Cached credentials may be stale — run `git credential reject` then re-authenticate |
+| `ssh: connect to host github.com port 22: Connection refused` | Try SSH over HTTPS port: add `Host github.com` with `Port 443` and `Hostname ssh.github.com` to `~/.ssh/config` |
+| Credentials not persisting | Check `git config --global credential.helper` — must be `store` or `cache` |
+| Multiple GitHub accounts | Use SSH with different keys per host alias in `~/.ssh/config`, or per-repo credential URLs |
+| `gh: command not found` + no sudo | Use git-only Method 1 above — no installation needed |

skills/github/github/references/ci-troubleshooting.md

@@ -0,0 +1,183 @@
+# CI Troubleshooting Quick Reference
+
+Common CI failure patterns and how to diagnose them from the logs.
+
+## Reading CI Logs
+
+```bash
+# With gh
+gh run view <RUN_ID> --log-failed
+
+# With curl — download and extract
+curl -sL -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/actions/runs/<RUN_ID>/logs \
+  -o /tmp/ci-logs.zip && unzip -o /tmp/ci-logs.zip -d /tmp/ci-logs
+```
+
+## Common Failure Patterns
+
+### Test Failures
+
+**Signatures in logs:**
+```
+FAILED tests/test_foo.py::test_bar - AssertionError
+E       assert 42 == 43
+ERROR tests/test_foo.py - ModuleNotFoundError
+```
+
+**Diagnosis:**
+1. Find the test file and line number from the traceback
+2. Use `read_file` to read the failing test
+3. Check if it's a logic error in the code or a stale test assertion
+4. Look for `ModuleNotFoundError` — usually a missing dependency in CI
+
+**Common fixes:**
+- Update assertion to match new expected behavior
+- Add missing dependency to requirements.txt / pyproject.toml
+- Fix flaky test (add retry, mock external service, fix race condition)
+
+---
+
+### Lint / Formatting Failures
+
+**Signatures in logs:**
+```
+src/auth.py:45:1: E302 expected 2 blank lines, got 1
+src/models.py:12:80: E501 line too long (95 > 88 characters)
+error: would reformat src/utils.py
+```
+
+**Diagnosis:**
+1. Read the specific file:line numbers mentioned
+2. Check which linter is complaining (flake8, ruff, black, isort, mypy)
+
+**Common fixes:**
+- Run the formatter locally: `black .`, `isort .`, `ruff check --fix .`
+- Fix the specific style violation by editing the file
+- If using `patch`, make sure to match existing indentation style
+
+---
+
+### Type Check Failures (mypy / pyright)
+
+**Signatures in logs:**
+```
+src/api.py:23: error: Argument 1 to "process" has incompatible type "str"; expected "int"
+src/models.py:45: error: Missing return statement
+```
+
+**Diagnosis:**
+1. Read the file at the mentioned line
+2. Check the function signature and what's being passed
+
+**Common fixes:**
+- Add type cast or conversion
+- Fix the function signature
+- Add `# type: ignore` comment as last resort (with explanation)
+
+---
+
+### Build / Compilation Failures
+
+**Signatures in logs:**
+```
+ModuleNotFoundError: No module named 'some_package'
+ERROR: Could not find a version that satisfies the requirement foo==1.2.3
+npm ERR! Could not resolve dependency
+```
+
+**Diagnosis:**
+1. Check requirements.txt / package.json for the missing or incompatible dependency
+2. Compare local vs CI Python/Node version
+
+**Common fixes:**
+- Add missing dependency to requirements file
+- Pin compatible version
+- Update lockfile (`pip freeze`, `npm install`)
+
+---
+
+### Permission / Auth Failures
+
+**Signatures in logs:**
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+Error: Resource not accessible by integration
+403 Forbidden
+```
+
+**Diagnosis:**
+1. Check if the workflow needs special permissions (token scopes)
+2. Check if secrets are configured (missing `GITHUB_TOKEN` or custom secrets)
+
+**Common fixes:**
+- Add `permissions:` block to workflow YAML
+- Verify secrets exist: `gh secret list` or check repo settings
+- For fork PRs: some secrets aren't available by design
+
+---
+
+### Timeout Failures
+
+**Signatures in logs:**
+```
+Error: The operation was canceled.
+The job running on runner ... has exceeded the maximum execution time
+```
+
+**Diagnosis:**
+1. Check which step timed out
+2. Look for infinite loops, hung processes, or slow network calls
+
+**Common fixes:**
+- Add timeout to the specific step: `timeout-minutes: 10`
+- Fix the underlying performance issue
+- Split into parallel jobs
+
+---
+
+### Docker / Container Failures
+
+**Signatures in logs:**
+```
+docker: Error response from daemon
+failed to solve: ... not found
+COPY failed: file not found in build context
+```
+
+**Diagnosis:**
+1. Check Dockerfile for the failing step
+2. Verify the referenced files exist in the repo
+
+**Common fixes:**
+- Fix path in COPY/ADD command
+- Update base image tag
+- Add missing file to `.dockerignore` exclusion or remove from it
+
+---
+
+## Auto-Fix Decision Tree
+
+```
+CI Failed
+├── Test failure
+│   ├── Assertion mismatch → update test or fix logic
+│   └── Import/module error → add dependency
+├── Lint failure → run formatter, fix style
+├── Type error → fix types
+├── Build failure
+│   ├── Missing dep → add to requirements
+│   └── Version conflict → update pins
+├── Permission error → update workflow permissions (needs user)
+└── Timeout → investigate perf (may need user input)
+```
+
+## Re-running After Fix
+
+```bash
+git add <fixed_files> && git commit -m "fix: resolve CI failure" && git push
+
+# Then monitor
+gh pr checks --watch 2>/dev/null || \
+  echo "Poll with: curl -s -H 'Authorization: token ...' https://api.github.com/repos/.../commits/$(git rev-parse HEAD)/status"
+```

skills/github/github/references/code-review.md

@@ -0,0 +1,481 @@
+---
+name: github-code-review
+description: "Review PRs: diffs, inline comments via gh or REST."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Code-Review, Pull-Requests, Git, Quality]
+    related_skills: [github-auth, github-pr-workflow]
+---
+
+# GitHub Code Review
+
+Perform code reviews on local changes before pushing, or review open PRs on GitHub. Most of this skill uses plain `git` — the `gh`/`curl` split only matters for PR-level interactions.
+
+## Prerequisites
+
+- Authenticated with GitHub (see `github-auth` skill)
+- Inside a git repository
+
+### Setup (for PR interactions)
+
+```bash
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+```
+
+---
+
+## 1. Reviewing Local Changes (Pre-Push)
+
+This is pure `git` — works everywhere, no API needed.
+
+### Get the Diff
+
+```bash
+# Staged changes (what would be committed)
+git diff --staged
+
+# All changes vs main (what a PR would contain)
+git diff main...HEAD
+
+# File names only
+git diff main...HEAD --name-only
+
+# Stat summary (insertions/deletions per file)
+git diff main...HEAD --stat
+```
+
+### Review Strategy
+
+1. **Get the big picture first:**
+
+```bash
+git diff main...HEAD --stat
+git log main..HEAD --oneline
+```
+
+2. **Review file by file** — use `read_file` on changed files for full context, and the diff to see what changed:
+
+```bash
+git diff main...HEAD -- src/auth/login.py
+```
+
+3. **Check for common issues:**
+
+```bash
+# Debug statements, TODOs, console.logs left behind
+git diff main...HEAD | grep -n "print(\|console\.log\|TODO\|FIXME\|HACK\|XXX\|debugger"
+
+# Large files accidentally staged
+git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10
+
+# Secrets or credential patterns
+git diff main...HEAD | grep -in "password\|secret\|api_key\|token.*=\|private_key"
+
+# Merge conflict markers
+git diff main...HEAD | grep -n "<<<<<<\|>>>>>>\|======="
+```
+
+4. **Present structured feedback** to the user.
+
+### Review Output Format
+
+When reviewing local changes, present findings in this structure:
+
+```
+## Code Review Summary
+
+### Critical
+- **src/auth.py:45** — SQL injection: user input passed directly to query.
+  Suggestion: Use parameterized queries.
+
+### Warnings
+- **src/models/user.py:23** — Password stored in plaintext. Use bcrypt or argon2.
+- **src/api/routes.py:112** — No rate limiting on login endpoint.
+
+### Suggestions
+- **src/utils/helpers.py:8** — Duplicates logic in `src/core/utils.py:34`. Consolidate.
+- **tests/test_auth.py** — Missing edge case: expired token test.
+
+### Looks Good
+- Clean separation of concerns in the middleware layer
+- Good test coverage for the happy path
+```
+
+---
+
+## 2. Reviewing a Pull Request on GitHub
+
+### View PR Details
+
+**With gh:**
+
+```bash
+gh pr view 123
+gh pr diff 123
+gh pr diff 123 --name-only
+```
+
+**With git + curl:**
+
+```bash
+PR_NUMBER=123
+
+# Get PR details
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "
+import sys, json
+pr = json.load(sys.stdin)
+print(f\"Title: {pr['title']}\")
+print(f\"Author: {pr['user']['login']}\")
+print(f\"Branch: {pr['head']['ref']} -> {pr['base']['ref']}\")
+print(f\"State: {pr['state']}\")
+print(f\"Body:\n{pr['body']}\")"
+
+# List changed files
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/files \
+  | python3 -c "
+import sys, json
+for f in json.load(sys.stdin):
+    print(f\"{f['status']:10} +{f['additions']:-4} -{f['deletions']:-4}  {f['filename']}\")"
+```
+
+### Check Out PR Locally for Full Review
+
+This works with plain `git` — no `gh` needed:
+
+```bash
+# Fetch the PR branch and check it out
+git fetch origin pull/123/head:pr-123
+git checkout pr-123
+
+# Now you can use read_file, search_files, run tests, etc.
+
+# View diff against the base branch
+git diff main...pr-123
+```
+
+**With gh (shortcut):**
+
+```bash
+gh pr checkout 123
+```
+
+### Leave Comments on a PR
+
+**General PR comment — with gh:**
+
+```bash
+gh pr comment 123 --body "Overall looks good, a few suggestions below."
+```
+
+**General PR comment — with curl:**
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
+  -d '{"body": "Overall looks good, a few suggestions below."}'
+```
+
+### Leave Inline Review Comments
+
+**Single inline comment — with gh (via API):**
+
+```bash
+HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')
+
+gh api repos/$OWNER/$REPO/pulls/123/comments \
+  --method POST \
+  -f body="This could be simplified with a list comprehension." \
+  -f path="src/auth/login.py" \
+  -f commit_id="$HEAD_SHA" \
+  -f line=45 \
+  -f side="RIGHT"
+```
+
+**Single inline comment — with curl:**
+
+```bash
+# Get the head commit SHA
+HEAD_SHA=$(curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments \
+  -d "{
+    \"body\": \"This could be simplified with a list comprehension.\",
+    \"path\": \"src/auth/login.py\",
+    \"commit_id\": \"$HEAD_SHA\",
+    \"line\": 45,
+    \"side\": \"RIGHT\"
+  }"
+```
+
+### Submit a Formal Review (Approve / Request Changes)
+
+**With gh:**
+
+```bash
+gh pr review 123 --approve --body "LGTM!"
+gh pr review 123 --request-changes --body "See inline comments."
+gh pr review 123 --comment --body "Some suggestions, nothing blocking."
+```
+
+**With curl — multi-comment review submitted atomically:**
+
+```bash
+HEAD_SHA=$(curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews \
+  -d "{
+    \"commit_id\": \"$HEAD_SHA\",
+    \"event\": \"COMMENT\",
+    \"body\": \"Code review from Hermes Agent\",
+    \"comments\": [
+      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"Use parameterized queries to prevent SQL injection.\"},
+      {\"path\": \"src/models/user.py\", \"line\": 23, \"body\": \"Hash passwords with bcrypt before storing.\"},
+      {\"path\": \"tests/test_auth.py\", \"line\": 1, \"body\": \"Add test for expired token edge case.\"}
+    ]
+  }"
+```
+
+Event values: `"APPROVE"`, `"REQUEST_CHANGES"`, `"COMMENT"`
+
+The `line` field refers to the line number in the *new* version of the file. For deleted lines, use `"side": "LEFT"`.
+
+---
+
+## 3. Review Checklist
+
+When performing a code review (local or PR), systematically check:
+
+### Correctness
+- Does the code do what it claims?
+- Edge cases handled (empty inputs, nulls, large data, concurrent access)?
+- Error paths handled gracefully?
+
+### Security
+- No hardcoded secrets, credentials, or API keys
+- Input validation on user-facing inputs
+- No SQL injection, XSS, or path traversal
+- Auth/authz checks where needed
+
+### Code Quality
+- Clear naming (variables, functions, classes)
+- No unnecessary complexity or premature abstraction
+- DRY — no duplicated logic that should be extracted
+- Functions are focused (single responsibility)
+
+### Testing
+- New code paths tested?
+- Happy path and error cases covered?
+- Tests readable and maintainable?
+
+### Performance
+- No N+1 queries or unnecessary loops
+- Appropriate caching where beneficial
+- No blocking operations in async code paths
+
+### Documentation
+- Public APIs documented
+- Non-obvious logic has comments explaining "why"
+- README updated if behavior changed
+
+---
+
+## 4. Pre-Push Review Workflow
+
+When the user asks you to "review the code" or "check before pushing":
+
+1. `git diff main...HEAD --stat` — see scope of changes
+2. `git diff main...HEAD` — read the full diff
+3. For each changed file, use `read_file` if you need more context
+4. Apply the checklist above
+5. Present findings in the structured format (Critical / Warnings / Suggestions / Looks Good)
+6. If critical issues found, offer to fix them before the user pushes
+
+---
+
+## 5. PR Review Workflow (End-to-End)
+
+When the user asks you to "review PR #N", "look at this PR", or gives you a PR URL, follow this recipe:
+
+### Step 1: Set up environment
+
+```bash
+source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
+# Or run the inline setup block from the top of this skill
+```
+
+### Step 2: Gather PR context
+
+Get the PR metadata, description, and list of changed files to understand scope before diving into code.
+
+**With gh:**
+```bash
+gh pr view 123
+gh pr diff 123 --name-only
+gh pr checks 123
+```
+
+**With curl:**
+```bash
+PR_NUMBER=123
+
+# PR details (title, author, description, branch)
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER
+
+# Changed files with line counts
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/files
+```
+
+### Step 3: Check out the PR locally
+
+This gives you full access to `read_file`, `search_files`, and the ability to run tests.
+
+```bash
+git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
+git checkout pr-$PR_NUMBER
+```
+
+### Step 4: Read the diff and understand changes
+
+```bash
+# Full diff against the base branch
+git diff main...HEAD
+
+# Or file-by-file for large PRs
+git diff main...HEAD --name-only
+# Then for each file:
+git diff main...HEAD -- path/to/file.py
+```
+
+For each changed file, use `read_file` to see full context around the changes — diffs alone can miss issues visible only with surrounding code.
+
+### Step 5: Run automated checks locally (if applicable)
+
+```bash
+# Run tests if there's a test suite
+python -m pytest 2>&1 | tail -20
+# or: npm test, cargo test, go test ./..., etc.
+
+# Run linter if configured
+ruff check . 2>&1 | head -30
+# or: eslint, clippy, etc.
+```
+
+### Step 6: Apply the review checklist (Section 3)
+
+Go through each category: Correctness, Security, Code Quality, Testing, Performance, Documentation.
+
+### Step 7: Post the review to GitHub
+
+Collect your findings and submit them as a formal review with inline comments.
+
+**With gh:**
+```bash
+# If no issues — approve
+gh pr review $PR_NUMBER --approve --body "Reviewed by Hermes Agent. Code looks clean — good test coverage, no security concerns."
+
+# If issues found — request changes with inline comments
+gh pr review $PR_NUMBER --request-changes --body "Found a few issues — see inline comments."
+```
+
+**With curl — atomic review with multiple inline comments:**
+```bash
+HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")
+
+# Build the review JSON — event is APPROVE, REQUEST_CHANGES, or COMMENT
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/reviews \
+  -d "{
+    \"commit_id\": \"$HEAD_SHA\",
+    \"event\": \"REQUEST_CHANGES\",
+    \"body\": \"## Hermes Agent Review\n\nFound 2 issues, 1 suggestion. See inline comments.\",
+    \"comments\": [
+      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"🔴 **Critical:** User input passed directly to SQL query — use parameterized queries.\"},
+      {\"path\": \"src/models.py\", \"line\": 23, \"body\": \"⚠️ **Warning:** Password stored without hashing.\"},
+      {\"path\": \"src/utils.py\", \"line\": 8, \"body\": \"💡 **Suggestion:** This duplicates logic in core/utils.py:34.\"}
+    ]
+  }"
+```
+
+### Step 8: Also post a summary comment
+
+In addition to inline comments, leave a top-level summary so the PR author gets the full picture at a glance. Use the review output format from `references/review-output-template.md`.
+
+**With gh:**
+```bash
+gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
+## Code Review Summary
+
+**Verdict: Changes Requested** (2 issues, 1 suggestion)
+
+### 🔴 Critical
+- **src/auth.py:45** — SQL injection vulnerability
+
+### ⚠️ Warnings
+- **src/models.py:23** — Plaintext password storage
+
+### 💡 Suggestions
+- **src/utils.py:8** — Duplicated logic, consider consolidating
+
+### ✅ Looks Good
+- Clean API design
+- Good error handling in the middleware layer
+
+---
+*Reviewed by Hermes Agent*
+EOF
+)"
+```
+
+### Step 9: Clean up
+
+```bash
+git checkout main
+git branch -D pr-$PR_NUMBER
+```
+
+### Decision: Approve vs Request Changes vs Comment
+
+- **Approve** — no critical or warning-level issues, only minor suggestions or all clear
+- **Request Changes** — any critical or warning-level issue that should be fixed before merge
+- **Comment** — observations and suggestions, but nothing blocking (use when you're unsure or the PR is a draft)

skills/github/github/references/codebase-inspection.md

@@ -0,0 +1,116 @@
+---
+name: codebase-inspection
+description: "Inspect codebases w/ pygount: LOC, languages, ratios."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [LOC, Code Analysis, pygount, Codebase, Metrics, Repository]
+    related_skills: [github-repo-management]
+prerequisites:
+  commands: [pygount]
+---
+
+# Codebase Inspection with pygount
+
+Analyze repositories for lines of code, language breakdown, file counts, and code-vs-comment ratios using `pygount`.
+
+## When to Use
+
+- User asks for LOC (lines of code) count
+- User wants a language breakdown of a repo
+- User asks about codebase size or composition
+- User wants code-vs-comment ratios
+- General "how big is this repo" questions
+
+## Prerequisites
+
+```bash
+pip install --break-system-packages pygount 2>/dev/null || pip install pygount
+```
+
+## 1. Basic Summary (Most Common)
+
+Get a full language breakdown with file counts, code lines, and comment lines:
+
+```bash
+cd /path/to/repo
+pygount --format=summary \
+  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
+  .
+```
+
+**IMPORTANT:** Always use `--folders-to-skip` to exclude dependency/build directories, otherwise pygount will crawl them and take a very long time or hang.
+
+## 2. Common Folder Exclusions
+
+Adjust based on the project type:
+
+```bash
+# Python projects
+--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"
+
+# JavaScript/TypeScript projects
+--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"
+
+# General catch-all
+--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"
+```
+
+## 3. Filter by Specific Language
+
+```bash
+# Only count Python files
+pygount --suffix=py --format=summary .
+
+# Only count Python and YAML
+pygount --suffix=py,yaml,yml --format=summary .
+```
+
+## 4. Detailed File-by-File Output
+
+```bash
+# Default format shows per-file breakdown
+pygount --folders-to-skip=".git,node_modules,venv" .
+
+# Sort by code lines (pipe through sort)
+pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20
+```
+
+## 5. Output Formats
+
+```bash
+# Summary table (default recommendation)
+pygount --format=summary .
+
+# JSON output for programmatic use
+pygount --format=json .
+
+# Pipe-friendly: Language, file count, code, docs, empty, string
+pygount --format=summary . 2>/dev/null
+```
+
+## 6. Interpreting Results
+
+The summary table columns:
+- **Language** — detected programming language
+- **Files** — number of files of that language
+- **Code** — lines of actual code (executable/declarative)
+- **Comment** — lines that are comments or documentation
+- **%** — percentage of total
+
+Special pseudo-languages:
+- `__empty__` — empty files
+- `__binary__` — binary files (images, compiled, etc.)
+- `__generated__` — auto-generated files (detected heuristically)
+- `__duplicate__` — files with identical content
+- `__unknown__` — unrecognized file types
+
+## Pitfalls
+
+1. **Always exclude .git, node_modules, venv** — without `--folders-to-skip`, pygount will crawl everything and may take minutes or hang on large dependency trees.
+2. **Markdown shows 0 code lines** — pygount classifies all Markdown content as comments, not code. This is expected behavior.
+3. **JSON files show low code counts** — pygount may count JSON lines conservatively. For accurate JSON line counts, use `wc -l` directly.
+4. **Large monorepos** — for very large repos, consider using `--suffix` to target specific languages rather than scanning everything.

skills/github/github/references/conventional-commits.md

@@ -0,0 +1,71 @@
+# Conventional Commits Quick Reference
+
+Format: `type(scope): description`
+
+## Types
+
+| Type | When to use | Example |
+|------|------------|---------|
+| `feat` | New feature or capability | `feat(auth): add OAuth2 login flow` |
+| `fix` | Bug fix | `fix(api): handle null response from /users endpoint` |
+| `refactor` | Code restructuring, no behavior change | `refactor(db): extract query builder into separate module` |
+| `docs` | Documentation only | `docs: update API usage examples in README` |
+| `test` | Adding or updating tests | `test(auth): add integration tests for token refresh` |
+| `ci` | CI/CD configuration | `ci: add Python 3.12 to test matrix` |
+| `chore` | Maintenance, dependencies, tooling | `chore: upgrade pytest to 8.x` |
+| `perf` | Performance improvement | `perf(search): add index on users.email column` |
+| `style` | Formatting, whitespace, semicolons | `style: run black formatter on src/` |
+| `build` | Build system or external deps | `build: switch from setuptools to hatch` |
+| `revert` | Reverts a previous commit | `revert: revert "feat(auth): add OAuth2 login flow"` |
+
+## Scope (optional)
+
+Short identifier for the area of the codebase: `auth`, `api`, `db`, `ui`, `cli`, etc.
+
+## Breaking Changes
+
+Add `!` after type or `BREAKING CHANGE:` in footer:
+
+```
+feat(api)!: change authentication to use bearer tokens
+
+BREAKING CHANGE: API endpoints now require Bearer token instead of API key header.
+Migration guide: https://docs.example.com/migrate-auth
+```
+
+## Multi-line Body
+
+Wrap at 72 characters. Use bullet points for multiple changes:
+
+```
+feat(auth): add JWT-based user authentication
+
+- Add login/register endpoints with input validation
+- Add User model with argon2 password hashing
+- Add auth middleware for protected routes
+- Add token refresh endpoint with rotation
+
+Closes #42
+```
+
+## Linking Issues
+
+In the commit body or footer:
+
+```
+Closes #42          ← closes the issue when merged
+Fixes #42           ← same effect
+Refs #42            ← references without closing
+Co-authored-by: Name <email>
+```
+
+## Quick Decision Guide
+
+- Added something new? → `feat`
+- Something was broken and you fixed it? → `fix`
+- Changed how code is organized but not what it does? → `refactor`
+- Only touched tests? → `test`
+- Only touched docs? → `docs`
+- Updated CI/CD pipelines? → `ci`
+- Updated dependencies or tooling? → `chore`
+- Made something faster? → `perf`

skills/github/github/references/github-api-cheatsheet.md

@@ -0,0 +1,161 @@
+# GitHub REST API Cheatsheet
+
+Base URL: `https://api.github.com`
+
+All requests need: `-H "Authorization: token $GITHUB_TOKEN"`
+
+Use the `gh-env.sh` helper to set `$GITHUB_TOKEN`, `$GH_OWNER`, `$GH_REPO` automatically:
+```bash
+source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
+```
+
+## Repositories
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| Get repo info | GET | `/repos/{owner}/{repo}` |
+| Create repo (user) | POST | `/user/repos` |
+| Create repo (org) | POST | `/orgs/{org}/repos` |
+| Update repo | PATCH | `/repos/{owner}/{repo}` |
+| Delete repo | DELETE | `/repos/{owner}/{repo}` |
+| List your repos | GET | `/user/repos?per_page=30&sort=updated` |
+| List org repos | GET | `/orgs/{org}/repos` |
+| Fork repo | POST | `/repos/{owner}/{repo}/forks` |
+| Create from template | POST | `/repos/{owner}/{template}/generate` |
+| Get topics | GET | `/repos/{owner}/{repo}/topics` |
+| Set topics | PUT | `/repos/{owner}/{repo}/topics` |
+
+## Pull Requests
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List PRs | GET | `/repos/{owner}/{repo}/pulls?state=open` |
+| Create PR | POST | `/repos/{owner}/{repo}/pulls` |
+| Get PR | GET | `/repos/{owner}/{repo}/pulls/{number}` |
+| Update PR | PATCH | `/repos/{owner}/{repo}/pulls/{number}` |
+| List PR files | GET | `/repos/{owner}/{repo}/pulls/{number}/files` |
+| Merge PR | PUT | `/repos/{owner}/{repo}/pulls/{number}/merge` |
+| Request reviewers | POST | `/repos/{owner}/{repo}/pulls/{number}/requested_reviewers` |
+| Create review | POST | `/repos/{owner}/{repo}/pulls/{number}/reviews` |
+| Inline comment | POST | `/repos/{owner}/{repo}/pulls/{number}/comments` |
+
+### PR Merge Body
+
+```json
+{"merge_method": "squash", "commit_title": "feat: description (#N)"}
+```
+
+Merge methods: `"merge"`, `"squash"`, `"rebase"`
+
+### PR Review Events
+
+`"APPROVE"`, `"REQUEST_CHANGES"`, `"COMMENT"`
+
+## Issues
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List issues | GET | `/repos/{owner}/{repo}/issues?state=open` |
+| Create issue | POST | `/repos/{owner}/{repo}/issues` |
+| Get issue | GET | `/repos/{owner}/{repo}/issues/{number}` |
+| Update issue | PATCH | `/repos/{owner}/{repo}/issues/{number}` |
+| Add comment | POST | `/repos/{owner}/{repo}/issues/{number}/comments` |
+| Add labels | POST | `/repos/{owner}/{repo}/issues/{number}/labels` |
+| Remove label | DELETE | `/repos/{owner}/{repo}/issues/{number}/labels/{name}` |
+| Add assignees | POST | `/repos/{owner}/{repo}/issues/{number}/assignees` |
+| List labels | GET | `/repos/{owner}/{repo}/labels` |
+| Search issues | GET | `/search/issues?q={query}+repo:{owner}/{repo}` |
+
+Note: The Issues API also returns PRs. Filter with `"pull_request" not in item` when parsing.
+
+## CI / GitHub Actions
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List workflows | GET | `/repos/{owner}/{repo}/actions/workflows` |
+| List runs | GET | `/repos/{owner}/{repo}/actions/runs?per_page=10` |
+| List runs (branch) | GET | `/repos/{owner}/{repo}/actions/runs?branch={branch}` |
+| Get run | GET | `/repos/{owner}/{repo}/actions/runs/{run_id}` |
+| Download logs | GET | `/repos/{owner}/{repo}/actions/runs/{run_id}/logs` |
+| Re-run | POST | `/repos/{owner}/{repo}/actions/runs/{run_id}/rerun` |
+| Re-run failed | POST | `/repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs` |
+| Trigger dispatch | POST | `/repos/{owner}/{repo}/actions/workflows/{id}/dispatches` |
+| Commit status | GET | `/repos/{owner}/{repo}/commits/{sha}/status` |
+| Check runs | GET | `/repos/{owner}/{repo}/commits/{sha}/check-runs` |
+
+## Releases
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List releases | GET | `/repos/{owner}/{repo}/releases` |
+| Create release | POST | `/repos/{owner}/{repo}/releases` |
+| Get release | GET | `/repos/{owner}/{repo}/releases/{id}` |
+| Delete release | DELETE | `/repos/{owner}/{repo}/releases/{id}` |
+| Upload asset | POST | `https://uploads.github.com/repos/{owner}/{repo}/releases/{id}/assets?name={filename}` |
+
+## Secrets
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| List secrets | GET | `/repos/{owner}/{repo}/actions/secrets` |
+| Get public key | GET | `/repos/{owner}/{repo}/actions/secrets/public-key` |
+| Set secret | PUT | `/repos/{owner}/{repo}/actions/secrets/{name}` |
+| Delete secret | DELETE | `/repos/{owner}/{repo}/actions/secrets/{name}` |
+
+## Branch Protection
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| Get protection | GET | `/repos/{owner}/{repo}/branches/{branch}/protection` |
+| Set protection | PUT | `/repos/{owner}/{repo}/branches/{branch}/protection` |
+| Delete protection | DELETE | `/repos/{owner}/{repo}/branches/{branch}/protection` |
+
+## User / Auth
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| Get current user | GET | `/user` |
+| List user repos | GET | `/user/repos` |
+| List user gists | GET | `/gists` |
+| Create gist | POST | `/gists` |
+| Search repos | GET | `/search/repositories?q={query}` |
+
+## Pagination
+
+Most list endpoints support:
+- `?per_page=100` (max 100)
+- `?page=2` for next page
+- Check `Link` header for `rel="next"` URL
+
+## Rate Limits
+
+- Authenticated: 5,000 requests/hour
+- Check remaining: `curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit`
+
+## Common curl Patterns
+
+```bash
+# GET
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO
+
+# POST with JSON body
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/issues \
+  -d '{"title": "...", "body": "..."}'
+
+# PATCH (update)
+curl -s -X PATCH \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/issues/42 \
+  -d '{"state": "closed"}'
+
+# DELETE
+curl -s -X DELETE \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$GH_OWNER/$GH_REPO/issues/42/labels/bug
+
+# Parse JSON response with python3
+curl -s ... | python3 -c "import sys,json; data=json.load(sys.stdin); print(data['field'])"
+```

skills/github/github/references/issues.md

@@ -0,0 +1,370 @@
+---
+name: github-issues
+description: "Create, triage, label, assign GitHub issues via gh or REST."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Issues, Project-Management, Bug-Tracking, Triage]
+    related_skills: [github-auth, github-pr-workflow]
+---
+
+# GitHub Issues Management
+
+Create, search, triage, and manage GitHub issues. Each section shows `gh` first, then the `curl` fallback.
+
+## Prerequisites
+
+- Authenticated with GitHub (see `github-auth` skill)
+- Inside a git repo with a GitHub remote, or specify the repo explicitly
+
+### Setup
+
+```bash
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+```
+
+---
+
+## 1. Viewing Issues
+
+**With gh:**
+
+```bash
+gh issue list
+gh issue list --state open --label "bug"
+gh issue list --assignee @me
+gh issue list --search "authentication error" --state all
+gh issue view 42
+```
+
+**With curl:**
+
+```bash
+# List open issues
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/issues?state=open&per_page=20" \
+  | python3 -c "
+import sys, json
+for i in json.load(sys.stdin):
+    if 'pull_request' not in i:  # GitHub API returns PRs in /issues too
+        labels = ', '.join(l['name'] for l in i['labels'])
+        print(f\"#{i['number']:5}  {i['state']:6}  {labels:30}  {i['title']}\")"
+
+# Filter by label
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/issues?state=open&labels=bug&per_page=20" \
+  | python3 -c "
+import sys, json
+for i in json.load(sys.stdin):
+    if 'pull_request' not in i:
+        print(f\"#{i['number']}  {i['title']}\")"
+
+# View a specific issue
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42 \
+  | python3 -c "
+import sys, json
+i = json.load(sys.stdin)
+labels = ', '.join(l['name'] for l in i['labels'])
+assignees = ', '.join(a['login'] for a in i['assignees'])
+print(f\"#{i['number']}: {i['title']}\")
+print(f\"State: {i['state']}  Labels: {labels}  Assignees: {assignees}\")
+print(f\"Author: {i['user']['login']}  Created: {i['created_at']}\")
+print(f\"\n{i['body']}\")"
+
+# Search issues
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/search/issues?q=authentication+error+repo:$OWNER/$REPO" \
+  | python3 -c "
+import sys, json
+for i in json.load(sys.stdin)['items']:
+    print(f\"#{i['number']}  {i['state']:6}  {i['title']}\")"
+```
+
+## 2. Creating Issues
+
+**With gh:**
+
+```bash
+gh issue create \
+  --title "Login redirect ignores ?next= parameter" \
+  --body "## Description
+After logging in, users always land on /dashboard.
+
+## Steps to Reproduce
+1. Navigate to /settings while logged out
+2. Get redirected to /login?next=/settings
+3. Log in
+4. Actual: redirected to /dashboard (should go to /settings)
+
+## Expected Behavior
+Respect the ?next= query parameter." \
+  --label "bug,backend" \
+  --assignee "username"
+```
+
+**With curl:**
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues \
+  -d '{
+    "title": "Login redirect ignores ?next= parameter",
+    "body": "## Description\nAfter logging in, users always land on /dashboard.\n\n## Steps to Reproduce\n1. Navigate to /settings while logged out\n2. Get redirected to /login?next=/settings\n3. Log in\n4. Actual: redirected to /dashboard\n\n## Expected Behavior\nRespect the ?next= query parameter.",
+    "labels": ["bug", "backend"],
+    "assignees": ["username"]
+  }'
+```
+
+### Bug Report Template
+
+```
+## Bug Description
+<What's happening>
+
+## Steps to Reproduce
+1. <step>
+2. <step>
+
+## Expected Behavior
+<What should happen>
+
+## Actual Behavior
+<What actually happens>
+
+## Environment
+- OS: <os>
+- Version: <version>
+```
+
+### Feature Request Template
+
+```
+## Feature Description
+<What you want>
+
+## Motivation
+<Why this would be useful>
+
+## Proposed Solution
+<How it could work>
+
+## Alternatives Considered
+<Other approaches>
+```
+
+## 3. Managing Issues
+
+### Add/Remove Labels
+
+**With gh:**
+
+```bash
+gh issue edit 42 --add-label "priority:high,bug"
+gh issue edit 42 --remove-label "needs-triage"
+```
+
+**With curl:**
+
+```bash
+# Add labels
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42/labels \
+  -d '{"labels": ["priority:high", "bug"]}'
+
+# Remove a label
+curl -s -X DELETE \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42/labels/needs-triage
+
+# List available labels in the repo
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/labels \
+  | python3 -c "
+import sys, json
+for l in json.load(sys.stdin):
+    print(f\"  {l['name']:30}  {l.get('description', '')}\")"
+```
+
+### Assignment
+
+**With gh:**
+
+```bash
+gh issue edit 42 --add-assignee username
+gh issue edit 42 --add-assignee @me
+```
+
+**With curl:**
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42/assignees \
+  -d '{"assignees": ["username"]}'
+```
+
+### Commenting
+
+**With gh:**
+
+```bash
+gh issue comment 42 --body "Investigated — root cause is in auth middleware. Working on a fix."
+```
+
+**With curl:**
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42/comments \
+  -d '{"body": "Investigated — root cause is in auth middleware. Working on a fix."}'
+```
+
+### Closing and Reopening
+
+**With gh:**
+
+```bash
+gh issue close 42
+gh issue close 42 --reason "not planned"
+gh issue reopen 42
+```
+
+**With curl:**
+
+```bash
+# Close
+curl -s -X PATCH \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42 \
+  -d '{"state": "closed", "state_reason": "completed"}'
+
+# Reopen
+curl -s -X PATCH \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/issues/42 \
+  -d '{"state": "open"}'
+```
+
+### Linking Issues to PRs
+
+Issues are automatically closed when a PR merges with the right keywords in the body:
+
+```
+Closes #42
+Fixes #42
+Resolves #42
+```
+
+To create a branch from an issue:
+
+**With gh:**
+
+```bash
+gh issue develop 42 --checkout
+```
+
+**With git (manual equivalent):**
+
+```bash
+git checkout main && git pull origin main
+git checkout -b fix/issue-42-login-redirect
+```
+
+## 4. Issue Triage Workflow
+
+When asked to triage issues:
+
+1. **List untriaged issues:**
+
+```bash
+# With gh
+gh issue list --label "needs-triage" --state open
+
+# With curl
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/issues?labels=needs-triage&state=open" \
+  | python3 -c "
+import sys, json
+for i in json.load(sys.stdin):
+    if 'pull_request' not in i:
+        print(f\"#{i['number']}  {i['title']}\")"
+```
+
+2. **Read and categorize** each issue (view details, understand the bug/feature)
+
+3. **Apply labels and priority** (see Managing Issues above)
+
+4. **Assign** if the owner is clear
+
+5. **Comment with triage notes** if needed
+
+## 5. Bulk Operations
+
+For batch operations, combine API calls with shell scripting:
+
+**With gh:**
+
+```bash
+# Close all issues with a specific label
+gh issue list --label "wontfix" --json number --jq '.[].number' | \
+  xargs -I {} gh issue close {} --reason "not planned"
+```
+
+**With curl:**
+
+```bash
+# List issue numbers with a label, then close each
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/issues?labels=wontfix&state=open" \
+  | python3 -c "import sys,json; [print(i['number']) for i in json.load(sys.stdin)]" \
+  | while read num; do
+    curl -s -X PATCH \
+      -H "Authorization: token $GITHUB_TOKEN" \
+      https://api.github.com/repos/$OWNER/$REPO/issues/$num \
+      -d '{"state": "closed", "state_reason": "not_planned"}'
+    echo "Closed #$num"
+  done
+```
+
+## Quick Reference Table
+
+| Action | gh | curl endpoint |
+|--------|-----|--------------|
+| List issues | `gh issue list` | `GET /repos/{o}/{r}/issues` |
+| View issue | `gh issue view N` | `GET /repos/{o}/{r}/issues/N` |
+| Create issue | `gh issue create ...` | `POST /repos/{o}/{r}/issues` |
+| Add labels | `gh issue edit N --add-label ...` | `POST /repos/{o}/{r}/issues/N/labels` |
+| Assign | `gh issue edit N --add-assignee ...` | `POST /repos/{o}/{r}/issues/N/assignees` |
+| Comment | `gh issue comment N --body ...` | `POST /repos/{o}/{r}/issues/N/comments` |
+| Close | `gh issue close N` | `PATCH /repos/{o}/{r}/issues/N` |
+| Search | `gh issue list --search "..."` | `GET /search/issues?q=...` |

skills/github/github/references/pr-workflow.md

@@ -0,0 +1,367 @@
+---
+name: github-pr-workflow
+description: "GitHub PR lifecycle: branch, commit, open, CI, merge."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Pull-Requests, CI/CD, Git, Automation, Merge]
+    related_skills: [github-auth, github-code-review]
+---
+
+# GitHub Pull Request Workflow
+
+Complete guide for managing the PR lifecycle. Each section shows the `gh` way first, then the `git` + `curl` fallback for machines without `gh`.
+
+## Prerequisites
+
+- Authenticated with GitHub (see `github-auth` skill)
+- Inside a git repository with a GitHub remote
+
+### Quick Auth Detection
+
+```bash
+# Determine which method to use throughout this workflow
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  # Ensure we have a token for API calls
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+echo "Using: $AUTH"
+```
+
+### Extracting Owner/Repo from the Git Remote
+
+Many `curl` commands need `owner/repo`. Extract it from the git remote:
+
+```bash
+# Works for both HTTPS and SSH remote URLs
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+echo "Owner: $OWNER, Repo: $REPO"
+```
+
+---
+
+## 1. Branch Creation
+
+This part is pure `git` — identical either way:
+
+```bash
+# Make sure you're up to date
+git fetch origin
+git checkout main && git pull origin main
+
+# Create and switch to a new branch
+git checkout -b feat/add-user-authentication
+```
+
+Branch naming conventions:
+- `feat/description` — new features
+- `fix/description` — bug fixes
+- `refactor/description` — code restructuring
+- `docs/description` — documentation
+- `ci/description` — CI/CD changes
+
+## 2. Making Commits
+
+Use the agent's file tools (`write_file`, `patch`) to make changes, then commit:
+
+```bash
+# Stage specific files
+git add src/auth.py src/models/user.py tests/test_auth.py
+
+# Commit with a conventional commit message
+git commit -m "feat: add JWT-based user authentication
+
+- Add login/register endpoints
+- Add User model with password hashing
+- Add auth middleware for protected routes
+- Add unit tests for auth flow"
+```
+
+Commit message format (Conventional Commits):
+```
+type(scope): short description
+
+Longer explanation if needed. Wrap at 72 characters.
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`, `perf`
+
+## 3. Pushing and Creating a PR
+
+### Push the Branch (same either way)
+
+```bash
+git push -u origin HEAD
+```
+
+### Create the PR
+
+**With gh:**
+
+```bash
+gh pr create \
+  --title "feat: add JWT-based user authentication" \
+  --body "## Summary
+- Adds login and register API endpoints
+- JWT token generation and validation
+
+## Test Plan
+- [ ] Unit tests pass
+
+Closes #42"
+```
+
+Options: `--draft`, `--reviewer user1,user2`, `--label "enhancement"`, `--base develop`
+
+**With git + curl:**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.v3+json" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls \
+  -d "{
+    \"title\": \"feat: add JWT-based user authentication\",
+    \"body\": \"## Summary\nAdds login and register API endpoints.\n\nCloses #42\",
+    \"head\": \"$BRANCH\",
+    \"base\": \"main\"
+  }"
+```
+
+The response JSON includes the PR `number` — save it for later commands.
+
+To create as a draft, add `"draft": true` to the JSON body.
+
+## 4. Monitoring CI Status
+
+### Check CI Status
+
+**With gh:**
+
+```bash
+# One-shot check
+gh pr checks
+
+# Watch until all checks finish (polls every 10s)
+gh pr checks --watch
+```
+
+**With git + curl:**
+
+```bash
+# Get the latest commit SHA on the current branch
+SHA=$(git rev-parse HEAD)
+
+# Query the combined status
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(f\"Overall: {data['state']}\")
+for s in data.get('statuses', []):
+    print(f\"  {s['context']}: {s['state']} - {s.get('description', '')}\")"
+
+# Also check GitHub Actions check runs (separate endpoint)
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/check-runs \
+  | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for cr in data.get('check_runs', []):
+    print(f\"  {cr['name']}: {cr['status']} / {cr['conclusion'] or 'pending'}\")"
+```
+
+### Poll Until Complete (git + curl)
+
+```bash
+# Simple polling loop — check every 30 seconds, up to 10 minutes
+SHA=$(git rev-parse HEAD)
+for i in $(seq 1 20); do
+  STATUS=$(curl -s \
+    -H "Authorization: token $GITHUB_TOKEN" \
+    https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
+    | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])")
+  echo "Check $i: $STATUS"
+  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failure" ] || [ "$STATUS" = "error" ]; then
+    break
+  fi
+  sleep 30
+done
+```
+
+## 5. Auto-Fixing CI Failures
+
+When CI fails, diagnose and fix. This loop works with either auth method.
+
+### Step 1: Get Failure Details
+
+**With gh:**
+
+```bash
+# List recent workflow runs on this branch
+gh run list --branch $(git branch --show-current) --limit 5
+
+# View failed logs
+gh run view <RUN_ID> --log-failed
+```
+
+**With git + curl:**
+
+```bash
+BRANCH=$(git branch --show-current)
+
+# List workflow runs on this branch
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?branch=$BRANCH&per_page=5" \
+  | python3 -c "
+import sys, json
+runs = json.load(sys.stdin)['workflow_runs']
+for r in runs:
+    print(f\"Run {r['id']}: {r['name']} - {r['conclusion'] or r['status']}\")"
+
+# Get failed job logs (download as zip, extract, read)
+RUN_ID=<run_id>
+curl -s -L \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
+  -o /tmp/ci-logs.zip
+cd /tmp && unzip -o ci-logs.zip -d ci-logs && cat ci-logs/*.txt
+```
+
+### Step 2: Fix and Push
+
+After identifying the issue, use file tools (`patch`, `write_file`) to fix it:
+
+```bash
+git add <fixed_files>
+git commit -m "fix: resolve CI failure in <check_name>"
+git push
+```
+
+### Step 3: Verify
+
+Re-check CI status using the commands from Section 4 above.
+
+### Auto-Fix Loop Pattern
+
+When asked to auto-fix CI, follow this loop:
+
+1. Check CI status → identify failures
+2. Read failure logs → understand the error
+3. Use `read_file` + `patch`/`write_file` → fix the code
+4. `git add . && git commit -m "fix: ..." && git push`
+5. Wait for CI → re-check status
+6. Repeat if still failing (up to 3 attempts, then ask the user)
+
+## 6. Merging
+
+**With gh:**
+
+```bash
+# Squash merge + delete branch (cleanest for feature branches)
+gh pr merge --squash --delete-branch
+
+# Enable auto-merge (merges when all checks pass)
+gh pr merge --auto --squash --delete-branch
+```
+
+**With git + curl:**
+
+```bash
+PR_NUMBER=<number>
+
+# Merge the PR via API (squash)
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge \
+  -d "{
+    \"merge_method\": \"squash\",
+    \"commit_title\": \"feat: add user authentication (#$PR_NUMBER)\"
+  }"
+
+# Delete the remote branch after merge
+BRANCH=$(git branch --show-current)
+git push origin --delete $BRANCH
+
+# Switch back to main locally
+git checkout main && git pull origin main
+git branch -d $BRANCH
+```
+
+Merge methods: `"merge"` (merge commit), `"squash"`, `"rebase"`
+
+### Enable Auto-Merge (curl)
+
+```bash
+# Auto-merge requires the repo to have it enabled in settings.
+# This uses the GraphQL API since REST doesn't support auto-merge.
+PR_NODE_ID=$(curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['node_id'])")
+
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/graphql \
+  -d "{\"query\": \"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \\\"$PR_NODE_ID\\\", mergeMethod: SQUASH}) { clientMutationId } }\"}"
+```
+
+## 7. Complete Workflow Example
+
+```bash
+# 1. Start from clean main
+git checkout main && git pull origin main
+
+# 2. Branch
+git checkout -b fix/login-redirect-bug
+
+# 3. (Agent makes code changes with file tools)
+
+# 4. Commit
+git add src/auth/login.py tests/test_login.py
+git commit -m "fix: correct redirect URL after login
+
+Preserves the ?next= parameter instead of always redirecting to /dashboard."
+
+# 5. Push
+git push -u origin HEAD
+
+# 6. Create PR (picks gh or curl based on what's available)
+# ... (see Section 3)
+
+# 7. Monitor CI (see Section 4)
+
+# 8. Merge when green (see Section 6)
+```
+
+## Useful PR Commands Reference
+
+| Action | gh | git + curl |
+|--------|-----|-----------|
+| List my PRs | `gh pr list --author @me` | `curl -s -H "Authorization: token $GITHUB_TOKEN" "https://api.github.com/repos/$OWNER/$REPO/pulls?state=open"` |
+| View PR diff | `gh pr diff` | `git diff main...HEAD` (local) or `curl -H "Accept: application/vnd.github.diff" ...` |
+| Add comment | `gh pr comment N --body "..."` | `curl -X POST .../issues/N/comments -d '{"body":"..."}'` |
+| Request review | `gh pr edit N --add-reviewer user` | `curl -X POST .../pulls/N/requested_reviewers -d '{"reviewers":["user"]}'` |
+| Close PR | `gh pr close N` | `curl -X PATCH .../pulls/N -d '{"state":"closed"}'` |
+| Check out someone's PR | `gh pr checkout N` | `git fetch origin pull/N/head:pr-N && git checkout pr-N` |

skills/github/github/references/repo-management.md

@@ -0,0 +1,516 @@
+---
+name: github-repo-management
+description: "Clone/create/fork repos; manage remotes, releases."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Repositories, Git, Releases, Secrets, Configuration]
+    related_skills: [github-auth, github-pr-workflow, github-issues]
+---
+
+# GitHub Repository Management
+
+Create, clone, fork, configure, and manage GitHub repositories. Each section shows `gh` first, then the `git` + `curl` fallback.
+
+## Prerequisites
+
+- Authenticated with GitHub (see `github-auth` skill)
+
+### Setup
+
+```bash
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  AUTH="gh"
+else
+  AUTH="git"
+  if [ -z "$GITHUB_TOKEN" ]; then
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
+  fi
+fi
+
+# Get your GitHub username (needed for several operations)
+if [ "$AUTH" = "gh" ]; then
+  GH_USER=$(gh api user --jq '.login')
+else
+  GH_USER=$(curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user | python3 -c "import sys,json; print(json.load(sys.stdin)['login'])")
+fi
+```
+
+If you're inside a repo already:
+
+```bash
+REMOTE_URL=$(git remote get-url origin)
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+```
+
+---
+
+## 1. Cloning Repositories
+
+Cloning is pure `git` — works identically either way:
+
+```bash
+# Clone via HTTPS (works with credential helper or token-embedded URL)
+git clone https://github.com/owner/repo-name.git
+
+# Clone into a specific directory
+git clone https://github.com/owner/repo-name.git ./my-local-dir
+
+# Shallow clone (faster for large repos)
+git clone --depth 1 https://github.com/owner/repo-name.git
+
+# Clone a specific branch
+git clone --branch develop https://github.com/owner/repo-name.git
+
+# Clone via SSH (if SSH is configured)
+git clone git@github.com:owner/repo-name.git
+```
+
+**With gh (shorthand):**
+
+```bash
+gh repo clone owner/repo-name
+gh repo clone owner/repo-name -- --depth 1
+```
+
+## 2. Creating Repositories
+
+**With gh:**
+
+```bash
+# Create a public repo and clone it
+gh repo create my-new-project --public --clone
+
+# Private, with description and license
+gh repo create my-new-project --private --description "A useful tool" --license MIT --clone
+
+# Under an organization
+gh repo create my-org/my-new-project --public --clone
+
+# From existing local directory
+cd /path/to/existing/project
+gh repo create my-project --source . --public --push
+```
+
+**With git + curl:**
+
+```bash
+# Create the remote repo via API
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user/repos \
+  -d '{
+    "name": "my-new-project",
+    "description": "A useful tool",
+    "private": false,
+    "auto_init": true,
+    "license_template": "mit"
+  }'
+
+# Clone it
+git clone https://github.com/$GH_USER/my-new-project.git
+cd my-new-project
+
+# -- OR -- push an existing local directory to the new repo
+cd /path/to/existing/project
+git init
+git add .
+git commit -m "Initial commit"
+git remote add origin https://github.com/$GH_USER/my-new-project.git
+git push -u origin main
+```
+
+To create under an organization:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/orgs/my-org/repos \
+  -d '{"name": "my-new-project", "private": false}'
+```
+
+### From a Template
+
+**With gh:**
+
+```bash
+gh repo create my-new-app --template owner/template-repo --public --clone
+```
+
+**With curl:**
+
+```bash
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/owner/template-repo/generate \
+  -d '{"owner": "'"$GH_USER"'", "name": "my-new-app", "private": false}'
+```
+
+## 3. Forking Repositories
+
+**With gh:**
+
+```bash
+gh repo fork owner/repo-name --clone
+```
+
+**With git + curl:**
+
+```bash
+# Create the fork via API
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/owner/repo-name/forks
+
+# Wait a moment for GitHub to create it, then clone
+sleep 3
+git clone https://github.com/$GH_USER/repo-name.git
+cd repo-name
+
+# Add the original repo as "upstream" remote
+git remote add upstream https://github.com/owner/repo-name.git
+```
+
+### Keeping a Fork in Sync
+
+```bash
+# Pure git — works everywhere
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+**With gh (shortcut):**
+
+```bash
+gh repo sync $GH_USER/repo-name
+```
+
+## 4. Repository Information
+
+**With gh:**
+
+```bash
+gh repo view owner/repo-name
+gh repo list --limit 20
+gh search repos "machine learning" --language python --sort stars
+```
+
+**With curl:**
+
+```bash
+# View repo details
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO \
+  | python3 -c "
+import sys, json
+r = json.load(sys.stdin)
+print(f\"Name: {r['full_name']}\")
+print(f\"Description: {r['description']}\")
+print(f\"Stars: {r['stargazers_count']}  Forks: {r['forks_count']}\")
+print(f\"Default branch: {r['default_branch']}\")
+print(f\"Language: {r['language']}\")"
+
+# List your repos
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/user/repos?per_page=20&sort=updated" \
+  | python3 -c "
+import sys, json
+for r in json.load(sys.stdin):
+    vis = 'private' if r['private'] else 'public'
+    print(f\"  {r['full_name']:40}  {vis:8}  {r.get('language', ''):10}  ★{r['stargazers_count']}\")"
+
+# Search repos
+curl -s \
+  "https://api.github.com/search/repositories?q=machine+learning+language:python&sort=stars&per_page=10" \
+  | python3 -c "
+import sys, json
+for r in json.load(sys.stdin)['items']:
+    print(f\"  {r['full_name']:40}  ★{r['stargazers_count']:6}  {r['description'][:60] if r['description'] else ''}\")"
+```
+
+## 5. Repository Settings
+
+**With gh:**
+
+```bash
+gh repo edit --description "Updated description" --visibility public
+gh repo edit --enable-wiki=false --enable-issues=true
+gh repo edit --default-branch main
+gh repo edit --add-topic "machine-learning,python"
+gh repo edit --enable-auto-merge
+```
+
+**With curl:**
+
+```bash
+curl -s -X PATCH \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO \
+  -d '{
+    "description": "Updated description",
+    "has_wiki": false,
+    "has_issues": true,
+    "allow_auto_merge": true
+  }'
+
+# Update topics
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.mercy-preview+json" \
+  https://api.github.com/repos/$OWNER/$REPO/topics \
+  -d '{"names": ["machine-learning", "python", "automation"]}'
+```
+
+## 6. Branch Protection
+
+```bash
+# View current protection
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/branches/main/protection
+
+# Set up branch protection
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/branches/main/protection \
+  -d '{
+    "required_status_checks": {
+      "strict": true,
+      "contexts": ["ci/test", "ci/lint"]
+    },
+    "enforce_admins": false,
+    "required_pull_request_reviews": {
+      "required_approving_review_count": 1
+    },
+    "restrictions": null
+  }'
+```
+
+## 7. Secrets Management (GitHub Actions)
+
+**With gh:**
+
+```bash
+gh secret set API_KEY --body "your-secret-value"
+gh secret set SSH_KEY < ~/.ssh/id_rsa
+gh secret list
+gh secret delete API_KEY
+```
+
+**With curl:**
+
+Secrets require encryption with the repo's public key — more involved via API:
+
+```bash
+# Get the repo's public key for encrypting secrets
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/secrets/public-key
+
+# Encrypt and set (requires Python with PyNaCl)
+python3 -c "
+from base64 import b64encode
+from nacl import encoding, public
+import json, sys
+
+# Get the public key
+key_id = '<key_id_from_above>'
+public_key = '<base64_key_from_above>'
+
+# Encrypt
+sealed = public.SealedBox(
+    public.PublicKey(public_key.encode('utf-8'), encoding.Base64Encoder)
+).encrypt('your-secret-value'.encode('utf-8'))
+print(json.dumps({
+    'encrypted_value': b64encode(sealed).decode('utf-8'),
+    'key_id': key_id
+}))"
+
+# Then PUT the encrypted secret
+curl -s -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/secrets/API_KEY \
+  -d '<output from python script above>'
+
+# List secrets (names only, values hidden)
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/secrets \
+  | python3 -c "
+import sys, json
+for s in json.load(sys.stdin)['secrets']:
+    print(f\"  {s['name']:30}  updated: {s['updated_at']}\")"
+```
+
+Note: For secrets, `gh secret set` is dramatically simpler. If setting secrets is needed and `gh` isn't available, recommend installing it for just that operation.
+
+## 8. Releases
+
+**With gh:**
+
+```bash
+gh release create v1.0.0 --title "v1.0.0" --generate-notes
+gh release create v2.0.0-rc1 --draft --prerelease --generate-notes
+gh release create v1.0.0 ./dist/binary --title "v1.0.0" --notes "Release notes"
+gh release list
+gh release download v1.0.0 --dir ./downloads
+```
+
+**With curl:**
+
+```bash
+# Create a release
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/releases \
+  -d '{
+    "tag_name": "v1.0.0",
+    "name": "v1.0.0",
+    "body": "## Changelog\n- Feature A\n- Bug fix B",
+    "draft": false,
+    "prerelease": false,
+    "generate_release_notes": true
+  }'
+
+# List releases
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/releases \
+  | python3 -c "
+import sys, json
+for r in json.load(sys.stdin):
+    tag = r.get('tag_name', 'no tag')
+    print(f\"  {tag:15}  {r['name']:30}  {'draft' if r['draft'] else 'published'}\")"
+
+# Upload a release asset (binary file)
+RELEASE_ID=<id_from_create_response>
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Content-Type: application/octet-stream" \
+  "https://uploads.github.com/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets?name=binary-amd64" \
+  --data-binary @./dist/binary-amd64
+```
+
+## 9. GitHub Actions Workflows
+
+**With gh:**
+
+```bash
+gh workflow list
+gh run list --limit 10
+gh run view <RUN_ID>
+gh run view <RUN_ID> --log-failed
+gh run rerun <RUN_ID>
+gh run rerun <RUN_ID> --failed
+gh workflow run ci.yml --ref main
+gh workflow run deploy.yml -f environment=staging
+```
+
+**With curl:**
+
+```bash
+# List workflows
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/workflows \
+  | python3 -c "
+import sys, json
+for w in json.load(sys.stdin)['workflows']:
+    print(f\"  {w['id']:10}  {w['name']:30}  {w['state']}\")"
+
+# List recent runs
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?per_page=10" \
+  | python3 -c "
+import sys, json
+for r in json.load(sys.stdin)['workflow_runs']:
+    print(f\"  Run {r['id']}  {r['name']:30}  {r['conclusion'] or r['status']}\")"
+
+# Download failed run logs
+RUN_ID=<run_id>
+curl -s -L \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
+  -o /tmp/ci-logs.zip
+cd /tmp && unzip -o ci-logs.zip -d ci-logs
+
+# Re-run a failed workflow
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun
+
+# Re-run only failed jobs
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun-failed-jobs
+
+# Trigger a workflow manually (workflow_dispatch)
+WORKFLOW_ID=<workflow_id_or_filename>
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/workflows/$WORKFLOW_ID/dispatches \
+  -d '{"ref": "main", "inputs": {"environment": "staging"}}'
+```
+
+## 10. Gists
+
+**With gh:**
+
+```bash
+gh gist create script.py --public --desc "Useful script"
+gh gist list
+```
+
+**With curl:**
+
+```bash
+# Create a gist
+curl -s -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/gists \
+  -d '{
+    "description": "Useful script",
+    "public": true,
+    "files": {
+      "script.py": {"content": "print(\"hello\")"}
+    }
+  }'
+
+# List your gists
+curl -s \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/gists \
+  | python3 -c "
+import sys, json
+for g in json.load(sys.stdin):
+    files = ', '.join(g['files'].keys())
+    print(f\"  {g['id']}  {g['description'] or '(no desc)':40}  {files}\")"
+```
+
+## Quick Reference Table
+
+| Action | gh | git + curl |
+|--------|-----|-----------|
+| Clone | `gh repo clone o/r` | `git clone https://github.com/o/r.git` |
+| Create repo | `gh repo create name --public` | `curl POST /user/repos` |
+| Fork | `gh repo fork o/r --clone` | `curl POST /repos/o/r/forks` + `git clone` |
+| Repo info | `gh repo view o/r` | `curl GET /repos/o/r` |
+| Edit settings | `gh repo edit --...` | `curl PATCH /repos/o/r` |
+| Create release | `gh release create v1.0` | `curl POST /repos/o/r/releases` |
+| List workflows | `gh workflow list` | `curl GET /repos/o/r/actions/workflows` |
+| Rerun CI | `gh run rerun ID` | `curl POST /repos/o/r/actions/runs/ID/rerun` |
+| Set secret | `gh secret set KEY` | `curl PUT /repos/o/r/actions/secrets/KEY` (+ encryption) |

skills/github/github/references/review-output-template.md

@@ -0,0 +1,74 @@
+# Review Output Template
+
+Use this as the structure for PR review summary comments. Copy and fill in the sections.
+
+## For PR Summary Comment
+
+```markdown
+## Code Review Summary
+
+**Verdict: [Approved ✅ | Changes Requested 🔴 | Reviewed 💬]** ([N] issues, [N] suggestions)
+
+**PR:** #[number] — [title]
+**Author:** @[username]
+**Files changed:** [N] (+[additions] -[deletions])
+
+### 🔴 Critical
+<!-- Issues that MUST be fixed before merge -->
+- **file.py:line** — [description]. Suggestion: [fix].
+
+### ⚠️ Warnings
+<!-- Issues that SHOULD be fixed, but not strictly blocking -->
+- **file.py:line** — [description].
+
+### 💡 Suggestions
+<!-- Non-blocking improvements, style preferences, future considerations -->
+- **file.py:line** — [description].
+
+### ✅ Looks Good
+<!-- Call out things done well — positive reinforcement -->
+- [aspect that was done well]
+
+---
+*Reviewed by Hermes Agent*
+```
+
+## Severity Guide
+
+| Level | Icon | When to use | Blocks merge? |
+|-------|------|-------------|---------------|
+| Critical | 🔴 | Security vulnerabilities, data loss risk, crashes, broken core functionality | Yes |
+| Warning | ⚠️ | Bugs in non-critical paths, missing error handling, missing tests for new code | Usually yes |
+| Suggestion | 💡 | Style improvements, refactoring ideas, performance hints, documentation gaps | No |
+| Looks Good | ✅ | Clean patterns, good test coverage, clear naming, smart design decisions | N/A |
+
+## Verdict Decision
+
+- **Approved ✅** — Zero critical/warning items. Only suggestions or all clear.
+- **Changes Requested 🔴** — Any critical or warning item exists.
+- **Reviewed 💬** — Observations only (draft PRs, uncertain findings, informational).
+
+## For Inline Comments
+
+Prefix inline comments with the severity icon so they're scannable:
+
+```
+🔴 **Critical:** User input passed directly to SQL query — use parameterized queries to prevent injection.
+```
+
+```
+⚠️ **Warning:** This error is silently swallowed. At minimum, log it.
+```
+
+```
+💡 **Suggestion:** This could be simplified with a dict comprehension:
+`{k: v for k, v in items if v is not None}`
+```
+
+```
+✅ **Nice:** Good use of context manager here — ensures cleanup on exceptions.
+```
+
+## For Local (Pre-Push) Review
+
+When reviewing locally before push, use the same structure but present it as a message to the user instead of a PR comment. Skip the PR metadata header and just start with the severity sections.

skills/github/github/scripts/gh-env.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# GitHub environment detection helper for Hermes Agent skills.
+#
+# Usage (via terminal tool):
+#   source skills/github/github-auth/scripts/gh-env.sh
+#
+# After sourcing, these variables are set:
+#   GH_AUTH_METHOD  - "gh", "curl", or "none"
+#   GITHUB_TOKEN    - personal access token (set if method is "curl")
+#   GH_USER         - GitHub username
+#   GH_OWNER        - repo owner  (only if inside a git repo with a github remote)
+#   GH_REPO         - repo name   (only if inside a git repo with a github remote)
+#   GH_OWNER_REPO   - owner/repo  (only if inside a git repo with a github remote)
+
+# --- Auth detection ---
+
+GH_AUTH_METHOD="none"
+GITHUB_TOKEN="${GITHUB_TOKEN:-}"
+GH_USER=""
+
+if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
+    GH_AUTH_METHOD="gh"
+    GH_USER=$(gh api user --jq '.login' 2>/dev/null)
+elif [ -n "$GITHUB_TOKEN" ]; then
+    GH_AUTH_METHOD="curl"
+elif [ -f "$HOME/.hermes/.env" ] && grep -q "^GITHUB_TOKEN=" "$HOME/.hermes/.env" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$HOME/.hermes/.env" | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if [ -n "$GITHUB_TOKEN" ]; then
+        GH_AUTH_METHOD="curl"
+    fi
+elif [ -f "$HOME/.git-credentials" ] && grep -q "github.com" "$HOME/.git-credentials" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "github.com" "$HOME/.git-credentials" | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -n "$GITHUB_TOKEN" ]; then
+        GH_AUTH_METHOD="curl"
+    fi
+fi
+
+# Resolve username for curl method
+if [ "$GH_AUTH_METHOD" = "curl" ] && [ -z "$GH_USER" ]; then
+    GH_USER=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+        https://api.github.com/user 2>/dev/null \
+        | python3 -c "import sys,json; print(json.load(sys.stdin).get('login',''))" 2>/dev/null)
+fi
+
+# --- Repo detection (if inside a git repo with a GitHub remote) ---
+
+GH_OWNER=""
+GH_REPO=""
+GH_OWNER_REPO=""
+
+_remote_url=$(git remote get-url origin 2>/dev/null)
+if [ -n "$_remote_url" ] && echo "$_remote_url" | grep -q "github.com"; then
+    GH_OWNER_REPO=$(echo "$_remote_url" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+    GH_OWNER=$(echo "$GH_OWNER_REPO" | cut -d/ -f1)
+    GH_REPO=$(echo "$GH_OWNER_REPO" | cut -d/ -f2)
+fi
+unset _remote_url
+
+# --- Summary ---
+
+echo "GitHub Auth: $GH_AUTH_METHOD"
+[ -n "$GH_USER" ]       && echo "User: $GH_USER"
+[ -n "$GH_OWNER_REPO" ] && echo "Repo: $GH_OWNER_REPO"
+[ "$GH_AUTH_METHOD" = "none" ] && echo "⚠ Not authenticated — see github-auth skill"
+
+export GH_AUTH_METHOD GITHUB_TOKEN GH_USER GH_OWNER GH_REPO GH_OWNER_REPO

skills/github/github/templates/bug-report.md

@@ -0,0 +1,35 @@
+## Bug Description
+
+<!-- Clear, concise description of the bug -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen -->
+
+## Actual Behavior
+
+<!-- What actually happens -->
+
+## Environment
+
+- OS:
+- Version/Commit:
+- Python version:
+- Browser (if applicable):
+
+## Error Output
+
+<!-- Paste relevant error messages, stack traces, or logs -->
+
+```
+```
+
+## Additional Context
+
+<!-- Screenshots, related issues, workarounds discovered, etc. -->

skills/github/github/templates/feature-request.md

@@ -0,0 +1,31 @@
+## Feature Description
+
+<!-- What do you want? -->
+
+## Motivation
+
+<!-- Why would this be useful? What problem does it solve? -->
+
+## Proposed Solution
+
+<!-- How could it work? Include API sketches, CLI examples, or mockups if helpful -->
+
+```
+# Example usage
+```
+
+## Alternatives Considered
+
+<!-- Other approaches and why they're less ideal -->
+
+-
+
+## Scope / Effort Estimate
+
+<!-- How big is this? What areas of the codebase would it touch? -->
+
+Small / Medium / Large — <!-- explanation -->
+
+## Additional Context
+
+<!-- Links to similar features in other tools, relevant discussions, etc. -->

skills/github/github/templates/pr-body-bugfix.md

@@ -0,0 +1,35 @@
+## Bug Description
+
+<!-- What was happening? -->
+
+Fixes #
+
+## Root Cause
+
+<!-- What was causing the bug? -->
+
+## Fix
+
+<!-- What does this PR change to fix it? -->
+
+-
+
+## How to Verify
+
+<!-- Steps a reviewer can follow to confirm the fix -->
+
+1.
+2.
+3.
+
+## Test Plan
+
+- [ ] Added regression test for this bug
+- [ ] Existing tests still pass
+- [ ] Manual verification of the fix
+
+## Risk Assessment
+
+<!-- Could this fix break anything else? What's the blast radius? -->
+
+Low / Medium / High — <!-- explanation -->

skills/github/github/templates/pr-body-feature.md

@@ -0,0 +1,33 @@
+## Summary
+
+<!-- 1-3 bullet points describing what this PR does -->
+
+-
+
+## Motivation
+
+<!-- Why is this change needed? Link to issue if applicable -->
+
+Closes #
+
+## Changes
+
+<!-- Detailed list of changes made -->
+
+-
+
+## Test Plan
+
+<!-- How was this tested? Checklist of verification steps -->
+
+- [ ] Unit tests pass (`pytest`)
+- [ ] Manual testing of new functionality
+- [ ] No regressions in existing behavior
+
+## Screenshots / Examples
+
+<!-- If UI changes or new output, show before/after -->
+
+## Notes for Reviewers
+
+<!-- Anything reviewers should pay special attention to -->

skills/legal/case-analysis-nine-steps/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: case-analysis-nine-steps
+description: 要件审判九步法——邹碧华法官提出的民事案件分析方法论。以请求权思维为基础，将案件分析分解为九个环环相扣的步骤。适用于案件分析、诉讼策略制定、庭审准备、裁判文书分析。
+version: 1
+tags: [legal, litigation, case-analysis, methodology]
+triggers:
+  - 分析案件
+  - 案件分析
+  - 九步法
+  - 诉讼策略
+  - 请求权分析
+  - 争点整理
+---
+
+# 要件审判九步法 — 案件分析方法论
+
+> 来源：邹碧华法官《要件审判九步法》
+> 核心思维：先找法（大前提）→ 再认定事实（小前提）→ 归入裁判（结论）
+
+## 案卷材料分析流程（九步法前置）
+
+拿到案卷材料后，必须先完成以下步骤，再进入九步法分析：
+
+### 一、精读全部材料
+
+- **所有文件逐页阅读**，页眉、页脚、注释、手写内容、印章、批注一律不放过
+- 标记关键信息：日期、金额、签名、盖章、手写备注
+- 注意文件之间的交叉引用和矛盾之处
+
+### 二、梳理相关方与时间线
+
+- **找出所有相关方**：当事人、关联公司、代理人、第三方等
+- **按时间顺序梳理全部事件**：合同签订、履行、违约、通知、催告、诉讼等
+- 制作时间线表格，每个事件标注：时间、相关方、事件内容、对应文件
+
+### 三、法律行为分析与法律关系提炼
+
+- 对**每个相关方**逐一进行"法律行为"分析——做了什么、基于什么身份、产生什么法律效果
+- 提炼**两两相对方之间的法律关系**（合同关系、侵权关系、担保关系、代理关系等）
+- 总结每组法律关系中各方的**权利义务**
+
+### 四、推理还原与缺失材料识别
+
+- 基于已有材料**推理还原事件经过**
+- **推测可能存在但未提供的文件和事实**（如：有催告函但没有送达凭证、有合同但没有付款凭证）
+- 标注推测依据
+
+### 五、制作补充材料清单
+
+- 列出**需要客户补充的材料和文件**，说明每份材料的用途和重要性
+- 要求客户提供，必要时说明不提供的风险
+
+### 六、事实还原定稿
+
+- 确认收集到所有能够搜集到的资料后，**尽可能还原案件事实全貌**
+- 形成完整的事实陈述，区分"已证实事实"和"待确认事实"
+
+完成以上步骤后，进入要件审判九步法进行法律分析。
+
+---
+
+## 适用场景
+
+- 民事案件全面分析
+- 诉讼策略制定（原告视角/被告视角）
+- 庭审准备与争点预判
+- 裁判文书逻辑审查
+- 合同纠纷、侵权纠纷、物权纠纷等各类民商事案件
+
+## 九步分析流程
+
+### 第一步：固定权利请求
+
+**任务**：明确当事人的诉讼请求是什么。
+
+- 原告请求什么？（给付金钱、返还财产、确认权利、变更/解除合同等）
+- 有无反诉？反诉请求是什么？
+- 诉讼请求是否明确、具体、可执行？
+- 注意区分：确认之诉、给付之诉、形成之诉
+
+**输出**：列出全部诉讼请求（含反诉），逐条编号。
+
+### 第二步：识别权利请求基础规范（法官找法）
+
+**任务**：为每项诉讼请求找到对应的法律依据（请求权基础）。
+
+- 该请求权属于什么性质？（合同请求权、侵权请求权、不当得利请求权、物权请求权等）
+- 对应的具体法律条文是什么？（民法典哪一条、哪部特别法）
+- 是否存在请求权竞合？如有，分析各请求权基础的利弊
+- **必须查原文**：引用具体条文，不凭印象
+
+**输出**：每项请求对应的法律条文及请求权性质。
+
+### 第三步：识别抗辩权基础规范（对立规范）
+
+**任务**：预判或识别对方可能/已经提出的抗辩。
+
+- 权利障碍抗辩（合同无效、未成立等）
+- 权利消灭抗辩（已清偿、已抵销、已免除等）
+- 权利阻止抗辩（诉讼时效、同时履行抗辩权、不安抗辩权等）
+- 每项抗辩对应的法律规范是什么？
+- 抗辩的举证责任归谁？
+
+**输出**：抗辩清单及对应法律依据，标注举证责任分配。
+
+### 第四步：基础规范构成要件分析
+
+**任务**：将请求权基础规范和抗辩规范的构成要件逐一拆解。
+
+- 把法律条文分解为若干事实要件（要件事实）
+- 对不完全法条，通过法律解释、司法解释、指导案例补充隐含要件
+- 每个要件需要什么事实来满足？
+
+**输出**：要件分解表——每项请求权/抗辩的构成要件列表。
+
+**示例格式**：
+```
+请求权基础：《民法典》第577条（违约责任）
+构成要件：
+  1. 合同有效成立
+  2. 被告存在违约行为
+  3. 原告遭受损失
+  4. 违约行为与损失之间有因果关系
+```
+
+### 第五步：审查诉讼主张是否完备
+
+**任务**：检查当事人的主张是否覆盖了全部构成要件。
+
+- 有无遗漏的主张？（对照第四步的要件清单逐一检查）
+- 有无矛盾的主张？
+- 如代表一方，提示需要补充的主张
+- 如分析裁判，检查法院是否进行了释明
+
+**输出**：主张完备性检查表，标注缺漏项。
+
+### 第六步：争点整理
+
+**任务**：归纳案件的争议焦点。
+
+- 哪些要件事实双方无争议？（可直接认定）
+- 哪些要件事实双方有争议？（这就是争点）
+- 是否存在法律适用争点？（法条理解分歧）
+- 按重要性和逻辑顺序排列争点
+
+**输出**：争议焦点清单，按优先级排序。
+
+### 第七步：要件事实的证明
+
+**任务**：围绕争点分析证据情况。
+
+- 每个争点需要什么证据来证明？
+- 现有证据是否充分？
+- 举证责任如何分配？（谁主张谁举证，举证责任倒置情形）
+- 有无证据缺口？如何补强？
+- 对方证据的薄弱点在哪里？
+
+**输出**：证据与争点对照表，标注证据充分性和风险点。
+
+### 第八步：要件事实的认定
+
+**任务**：基于证据认定事实。
+
+- 依据构成要件"过滤"证据，排除无关联性证据
+- 判断证据的真实性、合法性、关联性
+- 对证据证明力大小作出判断
+- 确认哪些要件事实可以认定、哪些不能
+
+**输出**：事实认定结论，逐要件标注"已证明/未证明/证据不足"。
+
+### 第九步：要件归入并得出结论
+
+**任务**：将认定的事实归入法律要件，得出最终结论。
+
+- 逐一比对：每个构成要件是否有事实支撑？
+- 全部要件满足 → 请求权成立
+- 任一要件不满足 → 请求权不成立
+- 抗辩要件是否满足？
+- 综合得出裁判/分析结论
+
+**输出**：归入分析表 + 最终结论。
+
+## 使用原则
+
+1. **严格按顺序**：九步环环相扣，不跳步
+2. **法条必须查原文**：涉及具体法律条文必须检索验证，不凭印象
+3. **区分视角**：明确是站在原告、被告还是中立分析视角
+4. **要件拆解是核心**：第四步做得越细，后续分析越精准
+5. **争点是指挥棒**：第六步决定了后续证据分析的方向
+6. **结论要有证据支撑**：每个判断都要指向具体证据
+
+## 输出格式建议
+
+分析报告按九步结构组织，每步包含：
+- 分析过程
+- 关键发现
+- 风险提示（如有）
+
+最后附总结：案件整体评估、胜诉概率判断（如适用）、策略建议。

skills/legal/contract-editor/references/add-clause-after-tracked-replace-failure.md

@@ -0,0 +1,67 @@
+# add_clause after_search Fails After tracked_replace — Use Direct lxml Insertion
+
+## Problem (2026-07-01 凤雅幼儿园劳务派遣协议)
+
+After calling `ed.tracked_replace(old, new)` on multiple paragraphs, subsequent `ed.add_clause(text, after_search="...")` calls silently fail — the new paragraph doesn't appear in the output. The function returns without error but the clause is not inserted.
+
+## Root Cause
+
+`add_clause`'s `after_search` parameter searches paragraph text by concatenating all `<w:t>` elements. After `tracked_replace`, the paragraph's XML contains interleaved `<w:del>` and `<w:ins>` elements. The `after_search` text-matching logic may:
+
+1. Include both old (del) and new (ins) text in the concatenation, so neither the old NOR new text matches cleanly
+2. Match the wrong paragraph if the search string appears in unexpected combinations of del+ins text
+
+## Solution: Direct lxml `addnext` Insertion
+
+After all `tracked_replace` calls, insert new clauses directly using lxml:
+
+```python
+# Find reference paragraph by index or by scanning accepted-view text
+paras = ed.body.findall(f'{WNS}p')
+ref_para = paras[target_index]  # e.g., P68
+
+# Build INS paragraph
+new_p = etree.Element(f'{WNS}p')
+new_p.append(copy.deepcopy(ref_ppr))  # Clone paragraph formatting
+
+ins = etree.SubElement(new_p, f'{WNS}ins')
+ins.set(f'{WNS}id', next_rev_id())
+ins.set(f'{WNS}author', 'WB')
+ins.set(f'{WNS}date', rev_date)
+
+r = etree.SubElement(ins, f'{WNS}r')
+r.set(f'{WNS}rsidR', rsid)
+r.insert(0, copy.deepcopy(ref_rpr))
+
+t = etree.SubElement(r, f'{WNS}t')
+t.set(XML_SPACE, 'preserve')
+t.text = clause_text
+
+# Mark paragraph itself as inserted (pPr/rPr/ins)
+ppr = new_p.find(f'{WNS}pPr')
+ppr_rpr = etree.SubElement(ppr, f'{WNS}rPr')
+ppr_ins = etree.SubElement(ppr_rpr, f'{WNS}ins')
+ppr_ins.set(f'{WNS}id', next_rev_id())
+ppr_ins.set(f'{WNS}author', 'WB')
+ppr_ins.set(f'{WNS}date', rev_date)
+
+# Insert after reference
+ref_para.addnext(new_p)
+ref_para = new_p  # Chain subsequent inserts
+```
+
+## When This Applies
+
+- You need to both modify existing clauses (tracked_replace) AND add new clauses in the same editing session
+- The `after_search` text has been altered by prior tracked_replace calls
+
+## Correct Operation Order
+
+1. All `ed.tracked_replace(...)` calls first
+2. Then find target paragraphs by scanning the body with accepted-view text extraction
+3. Insert new paragraphs directly via `addnext`
+4. `ed.validate()` + `ed.save()`
+
+## Verification
+
+After save, scan paragraphs and confirm new clauses appear in accepted-view text at the expected positions.

skills/legal/contract-editor/references/auto-notify-queue-routing.md

@@ -0,0 +1,55 @@
+# auto_notify_new_file.sh 架构：入队模式 vs 直接执行模式
+
+## 根因（2026-06-30）
+
+`auto_notify_new_file.sh` 原本自己启动 `uwf thread exec -c 5`（前台模式）来执行合同审查 workflow。
+但 hermes ACP 适配器在前台模式下有 asyncio stdin 注册 bug（`KeyError: '0 is not registered'`），
+导致每次 spawn `hermes acp` 子进程都立即失败，日志中全是 `agent command failed (uwf-hermes)`。
+
+**对比**：`contract-queue-runner.sh` 使用 `uwf thread exec --background` 模式，正常工作。
+
+## 当前架构（2026-06-30 修复后）
+
+```
+企微收到文件
+  → auto_notify_new_file.sh (inotifywait 监控)
+    → 识别 sender (邱律师=QiuTing)
+    → 上传 Nextcloud 待审查/
+    → 入队 /tmp/contract-queue/manifest.txt
+    → 检查 contract-queue-runner.sh 是否在运行，不在则启动
+      → contract-queue-runner.sh 串行执行（--background 模式）
+        → uwf thread start + thread exec --background
+        → uwf-hermes → hermes acp（正常）
+```
+
+## 关键文件
+
+| 文件 | 路径 | 职责 |
+|------|------|------|
+| auto_notify | `~/.hermes/scripts/auto_notify_new_file.sh` | 监控文件到达、上传、入队 |
+| queue runner | `~/.hermes/skills/devops/uwf/scripts/contract-queue-runner.sh` | 串行执行 workflow |
+| watchdog | `~/.hermes/scripts/contract-queue-watchdog.sh` | 每20分钟检查卡住的 thread |
+| auto_notify watchdog | `~/.hermes/scripts/auto_notify_watchdog.sh` | 每5分钟检查 auto_notify 进程 |
+
+## 禁止回退
+
+**绝不可把 auto_notify 改回自己启动 `uwf thread exec` 的模式**。前台模式有 ACP stdin bug，
+只有 `--background` 模式能正常工作。如果未来需要修改 auto_notify 的 workflow 启动逻辑，
+必须通过 contract-queue-runner 间接执行。
+
+## 入队逻辑
+
+```bash
+# 入队到 contract-queue
+cp "$filepath" "$QUEUE_DIR/${orig_name}"
+
+# 追加到 manifest（去重）
+if ! grep -qFx "$orig_name" "$QUEUE_DIR/manifest.txt" 2>/dev/null; then
+    echo "$orig_name" >> "$QUEUE_DIR/manifest.txt"
+fi
+
+# 检查 queue runner 是否在运行，不在则启动
+if ! ps aux | grep -q "[c]ontract-queue-runner"; then
+    nohup bash "$HOME/.hermes/skills/devops/uwf/scripts/contract-queue-runner.sh" >> "$QUEUE_DIR/queue.log" 2>&1 &
+fi
+```

skills/legal/contract-editor/references/auto-number-to-manual-fix.md

@@ -0,0 +1,98 @@
+# 自动编号 → 手动固定编号修复（删段重排根治）
+
+## 适用场景
+他人（如屠佳青）用修订模式整段删除了一个**自动编号列表项**（段落 pPr 含 `<w:numPr>`，且段落标记 del=True），导致 OnlyOffice **markup 修订视图**把后续列表项渲染成"旧号新号"双编号：
+
+```
+（1）报名服务          ← 正常
+（2）笔试服务[删除线]   ← 被删，仍占编号位
+（3）（2）面试服务      ← 双号！自动引擎按"接受后会变(2)"提前显示
+（4）（3）项目管理      ← 双号！
+```
+
+Maggie/Doro 平时看 markup 视图，要求"修订视图下编号稳定显示 (1)(2)(3)(4)"。
+根治办法：把这一组列表项从自动编号转成**手动文本编号**——文本是字面量，渲染器原样输出，不再经过自动编号引擎重排。
+
+## 关键认知（动手前必须确认）
+1. **被删项的删除是他人修订 → 绝不动其正文**（只在段首加编号 run，不碰 del 内容）。
+2. **全文先确认没有对这些子项编号的交叉引用**（如"按上述第3项""见（4）"）。本例"具体服务内容详见 附件一：服务报价单"是文字列举，非编号引用 → 安全。若存在引用，转手动编号后引用文字需同步核对。
+3. 用 `docker exec <nc容器> find ... ` 从 Nextcloud **拉当前交付版**作修复源，`md5sum` 比对确认本地副本没过时。
+
+## 可复用代码（2026-06-16 验证通过）
+```python
+import zipfile, shutil, os
+from lxml import etree
+NS='http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+def q(t): return f'{{{NS}}}{t}'
+def ln(el): return etree.QName(el).localname
+
+src='交付版.docx'; out='FIXED.docx'
+work='work.docx'; shutil.copy(src, work)
+root=etree.fromstring(zipfile.ZipFile(work).read('word/document.xml'))
+
+# 1. 按正文开头定位目标段（按你的合同改这些前缀）
+segs={}
+for p in root.iter(q('p')):
+    t=''.join((x.text or '') for x in p.iter() if ln(x) in ('t','delText'))
+    if   t.startswith('报名服务：'):       segs['报名']=p
+    elif t.startswith('笔试服务：提供'):   segs['笔试']=p   # 被删的那项
+    elif t.startswith('面试服务：'):       segs['面试']=p
+    elif t.startswith('项目管理：整个项目'): segs['项目管理']=p
+
+def make_rpr():  # 字体/字号照搬本段原文（本例宋体sz=24）。务必与目标段一致
+    rpr=etree.SubElement(etree.Element(q('tmp')), q('rPr'))
+    rf=etree.SubElement(rpr, q('rFonts'))
+    for a in ('ascii','hAnsi','cs'): rf.set(q(a),'宋体;SimSun')
+    etree.SubElement(rpr, q('sz')).set(q('val'),'24')
+    etree.SubElement(rpr, q('szCs')).set(q('val'),'24')
+    return rpr
+
+def make_run(text):
+    r=etree.Element(q('r')); r.append(make_rpr())
+    t=etree.SubElement(r, q('t')); t.text=text
+    t.set('{http://www.w3.org/XML/1998/namespace}space','preserve')
+    return r
+
+def remove_numpr(p):
+    ppr=p.find(q('pPr'))
+    if ppr is not None:
+        np=ppr.find(q('numPr'))
+        if np is not None: ppr.remove(np)
+
+def insert_first(p, node):  # 插到 pPr 之后、第一个内容元素之前
+    idx=len(p)
+    for i,c in enumerate(p):
+        if ln(c) in ('r','ins','del','hyperlink'): idx=i; break
+    p.insert(idx, node)
+
+# 2. 普通项：明文编号 run
+for key,label in [('报名','（1）'),('面试','（3）'),('项目管理','（4）')]:
+    remove_numpr(segs[key]); insert_first(segs[key], make_run(label))
+
+# 3. 被删项：编号 run 必须包进【他人的】<w:del>（复制其 author/date）
+p=segs['笔试']; remove_numpr(p)
+ex=p.find(q('del'))                       # 已有的他人 del（屠佳青）
+nd=etree.Element(q('del'))
+nd.set(q('author'), ex.get(q('author')))  # 照抄他人 author
+nd.set(q('date'),   ex.get(q('date')))
+nd.set(q('id'),'99001')                   # 不冲突的大 id
+r=etree.SubElement(nd, q('r')); r.append(make_rpr())
+dt=etree.SubElement(r, q('delText')); dt.text='（2）'
+dt.set('{http://www.w3.org/XML/1998/namespace}space','preserve')
+insert_first(p, nd)
+
+# 4. 写回（只换 document.xml，其余条目原样复制）
+new_doc=etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True)
+with zipfile.ZipFile(work) as zin, zipfile.ZipFile(out,'w',zipfile.ZIP_DEFLATED) as zout:
+    for it in zin.namelist():
+        zout.writestr(it, new_doc if it=='word/document.xml' else zin.read(it))
+```
+
+## 交付前必验（vision 不可用时降级四查，缺一不可）
+1. **逐段 markup diff vs 交付源** → 只有目标 N 段不同，其余零改动（本例 346 段只动 4 段）。
+2. **pdftotext 渲染层数编号链** → `onlyoffice-render.sh out.docx && pdftotext -f1 -l1 out.pdf -` 确认 1.2 下严格 (1)(2)(3)(4) 无双号。
+3. **编号 run rPr == 本段正文 run rPr**（字体宋体、sz=24 一致）。
+4. **接受修订后视图编号链连续** + `python-docx Document(out)` 可打开（XML 合法）。验证被删项的编号确实在 `<del author=他人>` 里、他人原 del 内容（id 不变）一字未动。
+
+## 上传
+`docker cp` 覆盖 `任务交付/` 同名文件 → `chown www-data` → `occ files:scan --path` → 清 OnlyOffice 缓存（`rm -rf .../App_Data/cache/files/*`）让 Maggie 打开看到新版。`md5sum` 比对容器内==本地确认上传成功。

skills/legal/contract-editor/references/auto-numbered-list-clause-insert.md

@@ -0,0 +1,113 @@
+# 在「自动编号的顶层列表」中新增条款（保留numPr）
+
+2026-06-18 华新慢病运维合同实战。一次返工换来的教训。
+
+## 适用判定（动手前先分清两类合同）
+
+合同的「条款」分两种承载方式，新增条款的手法完全不同：
+
+| 类型 | 特征 | 新增条款手法 |
+|------|------|-------------|
+| **A. 第X条 文本标题** | 条款标题是 run 里的文字「第七条 …」/「7. …」，段落**无** numPr | `add_clause()`（库会剥 numPr，正确）|
+| **B. 自动编号列表项** | 条款本身是自动编号列表项：段落 pPr 带 `<w:numPr>`，编号由 numbering.xml 的 `start`+`lvlText`（如 `一、`/`1.`/`（1）`）自动渲染，run 里**没有**编号文字 | ❌ 不能用 `add_clause()`；按下方「numbered-insert」手法 |
+
+**判定脚本**：对要插入位置附近的条款段落跑 `numbering-diagnose.py`，或直接看锚点段 `pPr/numPr` 是否存在且其 numId 的 lvlText 是序号格式。本案锚点「五、违约责任」段 `pPr` = `pStyle=12 + numPr(numId=1,ilvl=0) + ind`，numId=1→abstractNum start=1 lvlText=`%1、`（japaneseCounting 一、二、三）。
+
+## 为什么 add_clause 在 B 类会坏
+
+`add_clause()`（contract_docx_lib.py 第408-411行）**无条件**剥离新段的 numPr：
+```python
+numpr = new_ppr.find(qn('numPr'))
+if numpr is not None:
+    new_ppr.remove(numpr)   # ← B类灾难
+```
+后果（本案实测）：5 个新增条款全部**丢失自动编号**，且因 pPr 缺 numPr/缩进与列表项不一致，渲染时**堆到了文档最末尾**（签署页之前），既无编号又错位——违反「新增条款插在逻辑对应位置、不堆到最后」+「自动编号保留numPr」两条规则。
+
+`add_clause` 第二个缺陷：它只把**文本** run 包进 w:ins，**没有把段落标记（¶）标记为插入**。B 类里 ¶ 承载着自动编号，¶ 不是 tracked-insert，则接受/拒绝修订时这一项的编号增减不随修订走。
+
+## 正确手法：numbered tracked-insert 段落
+
+克隆锚点段的 pPr（**保留** numPr，让新段成为同一自动编号序列的一员），并把**段落标记本身**也标成 w:ins：
+
+```python
+import sys, copy
+sys.path.insert(0, '/home/maggie/contract-work')
+from contract_docx_lib import ContractEditor, qn
+from lxml import etree
+
+ed = ContractEditor(src)
+
+# 1) 定位锚点段（要插在它之后的那条原文条款）
+anchor = None
+for p in ed.body.findall(qn('p')):
+    if '违约责任：按照中华人民共和国民法典' in ed.get_para_text(p):
+        anchor = p; break
+anchor_ppr = anchor.find(qn('pPr'))
+assert anchor_ppr.find(qn('numPr')) is not None, "锚点不是自动编号项，确认是否B类"
+
+def make_numbered_ins_para(text):
+    new_p = etree.Element(qn('p'))
+    new_ppr = copy.deepcopy(anchor_ppr)          # 含 pStyle + numPr(同numId/ilvl) + ind → 入同一自动编号序列
+    # 关键：把段落标记(¶)标成插入，整段(含自动编号)作为 tracked insertion
+    rpr_mark = new_ppr.find(qn('rPr'))
+    if rpr_mark is None:
+        rpr_mark = etree.SubElement(new_ppr, qn('rPr'))
+    ins_mark = etree.SubElement(rpr_mark, qn('ins'))
+    ins_mark.set(qn('id'), ed._next_id())
+    ins_mark.set(qn('author'), 'WB')
+    ins_mark.set(qn('date'), ed._revision_date)
+    new_p.append(new_ppr)
+    # 文本作为 tracked-ins run，用规范化 _body_rpr（完整rFonts四属性+hint=eastAsia+显式sz）
+    new_p.append(ed._mk_ins(text, ed._body_rpr))
+    return new_p
+
+clauses = [  # 期望的最终正序 六~十
+    "保密与数据：……",
+    "知识产权与系统交接：……",
+    "转包与分包：……",
+    "第三方侵权：……",
+    "违约赔偿：……",
+]
+
+# 2) 全部插在 anchor 之后；倒序 insert 使最终正序
+parent = ed.body
+anchor_idx = list(parent).index(anchor)
+for txt in reversed(clauses):
+    parent.insert(anchor_idx + 1, make_numbered_ins_para(txt))
+
+assert ed.validate() == []
+ed.save(out)
+```
+
+要点：
+- **倒序插入**：每条都插在 `anchor_idx+1`，倒序遍历 → 最终正序。
+- **同一 numId/ilvl**：克隆锚点 pPr 即自动继承，新条款自动续编（本案锚点是五 → 新条款渲染为六、七、八、九、十，后续原文自动顺延为十一、十二…，**无需手动改任何原文编号**）。
+- **¶ 标插入** + **文本 run 标插入**，两者都要，缺一不可。
+- 文本 run 用 `ed._body_rpr`（库已规整：四属性 rFonts + hint=eastAsia + 显式 sz），不要手搓 rPr。
+
+## 交付前验证（B 类专项）
+
+1. **接受所有修订后**渲染（删 w:del + 删带 `pPr/rPr/del` 的整段 + 解包 w:ins）→ 确认新条款编号与锚点连续、原文顺延正确、无错位到末尾。
+2. **字体核对走「同段原文」标准**：本案原文正文 run = `<w:rFonts hint="eastAsia"/><w:szCs val="21"/>`（**无**显式 eastAsia 名，继承 docDefaults 宋体）。新 INS run 与之等效即合格——`ea=None hint=eastAsia` 是**正确**的，`wb-ins-font-verify.py` 若按绝对属性报 `ea=None` 是假阳性（见 contract-reviewer 的 2026-06-17 培训合同条）。唯一差异是 INS 多了显式 `<w:sz val="21">`（w:ins 必需），渲染一致。
+3. **LibreOffice 渲染假象**：用 `libreoffice→pdftotext` 自查时，被顺延的自动编号项会显示 `十二、[七、]` 这种**方括号叠加**（recomputed 新号 + cached 旧号），这是 LibreOffice markup 渲染产物，**不是错误**，XML 里没有字面方括号。判真实编号一律以「接受所有修订后」或 OnlyOffice 渲染为准（OnlyOffice 是 Maggie/Doro 实际所用引擎）。
+
+## 锚点选择铁律：插在 body text 之后，不是 heading 之后
+
+**这是一个极易犯的错误**（2026-06-26 朱家角环保袋合同实证）：
+
+当Reviewer要求"在违约责任条款之后、争议解决条款之前新增XX条款"时，合同结构通常是：
+```
+P74: 八．违约责任        ← heading（numId=1）
+P75: 若乙方未按本合同... ← body text（无 numPr）
+P76: 九．合同金额        ← 下一个 heading（numId=1）
+```
+
+**错误做法**：锚点 = P74（heading），插入后 → 新条款夹在 heading 和它的 body text 之间，结构错乱。
+
+**正确做法**：锚点 = P75（body text），插入后 → 新条款在 body text 之后、下一个 heading 之前，结构正确。
+
+**判据**：`numbering-diagnose.py` 确认锚点段的 `numPr` 状态——heading 有 numPr，body text 无 numPr。新条款应克隆**下一个 heading**（如 P76 合同金额）的 pPr（含 numPr），插入在**前一个 body text**（如 P75）之后。
+
+## 一句话
+
+锚点是自动编号列表项（pPr 有 numPr）→ 别用 add_clause，克隆锚点 pPr（留 numPr）+ ¶ 标 w:ins + 文本标 w:ins，倒序插入，新条款自动续编、原文自动顺延。**插在 body text 之后，不是 heading 之后。**

skills/legal/contract-editor/references/clause-clone-sibling-format.md

@@ -0,0 +1,95 @@
+# A类（手动文本编号）新增条款：克隆"真实邻居段落"而非信任库的 _title_rpr / _body_rpr
+
+2026-06-18 赵巷镇 X线设备采购合同实战。终审字体核验抓出"新标题不加粗"，根因是库提取的标题格式丢了 bold。
+
+## 何时用这套手法
+
+- 合同是 **A 类**：条款标题是 run 里的**手动文本编号**（如 `8.争端的解决`、`第七条 索赔`），段落**无** numPr。
+- 要新增一个带标题的条款（标题段 + 正文段），并希望格式与兄弟条款 100% 一致。
+- （B 类自动编号列表项见 `auto-numbered-list-clause-insert.md`，手法不同。）
+
+## 为什么不直接用库的 `_title_rpr` / `_body_rpr`
+
+`ContractEditor._extract_formats()`（contract_docx_lib.py ~第86-175行）用启发式认"条款标题"：
+```python
+is_clause_title = (re.match(r'^\d+[．.、]\s*\S', p_text) or
+                   re.match(r'^第[一二三四五六七八九十百千\d]+条\s*\S', p_text)) and len(p_text) < 30
+# 且 _is_title_style() 要 <w:b/> 或标题字体(黑体/SimHei…) 才算 title
+```
+**坑**：当标题就是"8.争端的解决"（宋体 + `<w:b/>`，无特殊标题字体），若该段在扫描中**没被 `_is_title_style` 命中**（例如 b 标记在 bCs 旁、或正则边界），`clause_title_rpr` / `first_bold_rpr` 取空 → `_title_rpr` **回退到 `_body_rpr`（不含 bold）**。
+
+实测后果：新标题 `8.转包与分包` 的 INS run `bold=False`，而原文兄弟标题 `9.争端的解决` `bold=True`。`validate()` 查不出（它不比 bold），只有逐段 WB INS 与"同段/同级原文"对比才抓得到。
+
+## 稳健手法：克隆紧邻同级原文段落
+
+不取库的 `_title_rpr`/`_body_rpr`，改为**直接深拷贝隔壁真实条款段**的 pPr 和首个 run 的 rPr：
+
+```python
+import sys, copy
+sys.path.insert(0, '/home/maggie/contract-work')
+from contract_docx_lib import ContractEditor, qn
+from lxml import etree
+
+ed = ContractEditor(src)   # 已先做完所有 tracked_replace
+
+def find(kw):
+    for p in ed.body.findall(qn('p')):
+        if kw in ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}')):
+            return p
+    return None
+
+# 克隆来源：插入点后面那条原文条款的【标题段】和它的【正文段】
+title_src = find('8.争端的解决')          # 兄弟条款标题（自带 <w:b/> + 宋体四属性 + 标题pPr缩进）
+body_src  = find('双方如在履行合同中发生纠纷')  # 兄弟条款正文（无bold + firstLine=420 缩进）
+
+def clone_as_ins(src_para, new_text):
+    """深拷贝 src_para 的 pPr + 首run rPr，替换文本，整段(含¶)标 w:ins(author=WB)"""
+    np = etree.Element(qn('p'))
+    ppr = copy.deepcopy(src_para.find(qn('pPr')))
+    # ¶ 段落标记标插入
+    rprm = ppr.find(qn('rPr'))
+    if rprm is None:
+        rprm = etree.SubElement(ppr, qn('rPr'))
+    insm = etree.SubElement(rprm, qn('ins'))
+    insm.set(qn('id'), ed._next_id()); insm.set(qn('author'), 'WB'); insm.set(qn('date'), ed._revision_date)
+    np.append(ppr)
+    # run rPr 直接克隆兄弟段首 run（bold/字体/字号全继承，不碰库的默认值）
+    src_r = src_para.find(qn('r'))
+    src_rpr = copy.deepcopy(src_r.find(qn('rPr'))) if (src_r is not None and src_r.find(qn('rPr')) is not None) else None
+    np.append(ed._mk_ins(new_text, src_rpr))
+    return np
+
+title_p = clone_as_ins(title_src, "8.转包与分包")
+body_p  = clone_as_ins(body_src,  "未经甲方书面同意，乙方不得将本合同项下的…连带责任。")
+
+idx = list(ed.body).index(title_src)
+ed.body.insert(idx,     title_p)   # 标题插在兄弟条款标题之前 → 成为新的"8."，兄弟顺延为"9."
+ed.body.insert(idx + 1, body_p)
+```
+
+## A类手动编号的顺延（与 B 类自动顺延不同！）
+
+A 类编号是 run 里的字面文字，**不会自动顺延**。插入新"8."后，必须手动把后续所有手动编号 DEL 旧号+INS 新号（用 tracked_replace）：
+```python
+for old, new in [("8.争端的解决","9.争端的解决"), ("9.合同生效","10.合同生效"),
+                 ("9.1 本合同在…","10.1 本合同在…"), ("10.合同附件","11.合同附件"),
+                 ("10.1 配置清单","11.1 配置清单"), ...,  ("12.特别约定","13.特别约定")]:
+    ed.tracked_replace(old, new)
+```
+- **子编号一并顺延**（9.1/9.2→10.1/10.2，11.1-11.7→12.1-12.7）。
+- 匹配串要够长以避免短串误命中（见 SKILL.md「tracked_replace 短字符串误命中」）。
+
+## 交付前验证（必做）
+
+1. **bold 对照**：新标题 INS run `bold==True` 且 ==兄弟标题；新正文 INS run `bold==False` 且有正确 `firstLine` 缩进。
+   ```python
+   r = p.find('.//w:ins/w:r', ns); b = r.find('w:rPr/w:b', ns)
+   # 标题段 b is not None == 兄弟标题段 b is not None
+   ```
+2. **WB INS 字体逐段核验（相对同段/同级原文）**：异常应为 0。原文 run 有显式宋体四属性时，克隆来的 INS 也带四属性——与原文一致即合格。
+3. **接受所有修订后渲染**，确认手动编号链连续（…7、**8.转包**、9、10、10.1、10.2、11…13），无重号/跳号。
+4. python-docx 能打开（XML 合法）。
+
+## 一句话
+
+A 类手动编号合同新增带标题条款：**别用库的 `_title_rpr`/`_body_rpr`（启发式可能丢 bold）**，直接 `copy.deepcopy` 紧邻兄弟条款的【标题段】和【正文段】的 pPr+首run rPr，文本替换+整段标 w:ins；编号不会自动顺延，手动 tracked_replace 把后续主/子编号全部 +1。

skills/legal/contract-editor/references/comment-restoration-from-original.md

@@ -0,0 +1,146 @@
+# Comment Restoration from Original File
+
+When comments are lost during docx editing (e.g., paragraph clear operations that remove commentRangeStart/End/Reference elements), restore them from the original file.
+
+## Scenario
+- Original file has N comments (e.g., Alice×2, 法务, 杜律 = 4 comments, ids 0-3)
+- Edited file lost some/all original comments and may have added new ones (e.g., 华诚-Z comment id=0, Alice id=2)
+- Goal: merge all comments — original ones preserved + new ones added, with non-conflicting IDs
+
+## Recovery Technique
+
+### Step 1: Extract original comments
+```python
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+z_orig = zipfile.ZipFile('original.docx')
+with z_orig.open('word/comments.xml') as f:
+    ctree_orig = etree.parse(f)
+orig_comments = []
+for c in ctree_orig.getroot().findall(f'{WNS}comment'):
+    orig_comments.append({
+        'id': c.get(f'{WNS}id'),
+        'author': c.get(f'{WNS}author'),
+        'date': c.get(f'{WNS}date'),
+        'text': ''.join(t.text for t in c.iter(f'{WNS}t') if t.text),
+        'element': copy.deepcopy(c)
+    })
+z_orig.close()
+```
+
+### Step 2: Identify which comments survived in the edited file
+```python
+z_edit = zipfile.ZipFile('edited.docx')
+with z_edit.open('word/comments.xml') as f:
+    ctree_edit = etree.parse(f)
+edit_comment_ids = set()
+for c in ctree_edit.getroot().findall(f'{WNS}comment'):
+    edit_comment_ids.add(c.get(f'{WNS}id'))
+```
+
+### Step 3: Find new comments (non-original authors)
+```python
+new_comments = []
+for c in ctree_edit.getroot().findall(f'{WNS}comment'):
+    if c.get(f'{WNS}author') not in [oc['author'] for oc in orig_comments]:
+        new_comments.append({
+            'old_id': c.get(f'{WNS}id'),
+            'author': c.get(f'{WNS}author'),
+            'element': copy.deepcopy(c)
+        })
+```
+
+### Step 4: Rebuild comments.xml with all comments
+Assign non-conflicting IDs:
+- Original comments keep their original IDs (0, 1, 2, 3)
+- New comments get IDs starting from max(original_ids) + 1
+
+```python
+new_comments_xml = etree.Element(f'{WNS}comments')
+new_comments_xml.set('xmlns:w', 'http://schemas.openxmlformats.org/wordprocessingml/2006/main')
+# ... add other namespaces as needed
+
+max_id = max(int(oc['id']) for oc in orig_comments)
+
+# Add original comments
+for oc in orig_comments:
+    new_comments_xml.append(oc['element'])
+
+# Add new comments with renumbered IDs
+for nc in new_comments:
+    max_id += 1
+    nc['new_id'] = str(max_id)
+    nc['element'].set(f'{WNS}id', nc['new_id'])
+    new_comments_xml.append(nc['element'])
+```
+
+### Step 5: Update document.xml comment references
+For each new comment, find its commentRangeStart, commentRangeEnd, and commentReference in document.xml and update the ID from old to new:
+
+```python
+for nc in new_comments:
+    old_id = nc['old_id']
+    new_id = nc['new_id']
+    
+    # Update commentRangeStart
+    for elem in root.iter(f'{WNS}commentRangeStart'):
+        if elem.get(f'{WNS}id') == old_id:
+            elem.set(f'{WNS}id', new_id)
+    
+    # Update commentRangeEnd
+    for elem in root.iter(f'{WNS}commentRangeEnd'):
+        if elem.get(f'{WNS}id') == old_id:
+            elem.set(f'{WNS}id', new_id)
+    
+    # Update commentReference (inside w:r)
+    for elem in root.iter(f'{WNS}commentReference'):
+        if elem.get(f'{WNS}id') == old_id:
+            elem.set(f'{WNS}id', new_id)
+```
+
+### Step 6: Write back to docx
+```python
+z_out = zipfile.ZipFile('output.docx', 'w')
+# Copy all files from edited.docx except comments.xml and document.xml
+for item in z_edit.namelist():
+    if item not in ('word/comments.xml', 'word/document.xml'):
+        z_out.writestr(item, z_edit.read(item))
+
+# Write updated comments.xml
+z_out.writestr('word/comments.xml', 
+    etree.tostring(new_comments_xml, encoding='UTF-8', xml_declaration=True, standalone=True))
+
+# Write updated document.xml
+z_out.writestr('word/document.xml',
+    etree.tostring(tree, encoding='UTF-8', xml_declaration=True, standalone=True))
+
+z_edit.close()
+z_out.close()
+```
+
+## Verification
+```python
+z = zipfile.ZipFile('output.docx')
+with z.open('word/comments.xml') as f:
+    ctree = etree.parse(f)
+for c in ctree.getroot().findall(f'{WNS}comment'):
+    print(f"  id={c.get(f'{WNS}id')} author={c.get(f'{WNS}author')}: {text[:80]}")
+
+# Check all IDs referenced in document.xml exist in comments.xml
+content = z.read('word/document.xml').decode('utf-8')
+doc_ids = set(re.findall(r'commentRangeStart[^>]*w:id="(\d+)"', content))
+doc_ids |= set(re.findall(r'commentRangeEnd[^>]*w:id="(\d+)"', content))
+doc_ids |= set(re.findall(r'commentReference[^>]*w:id="(\d+)"', content))
+comment_ids = set(c.get(f'{WNS}id') for c in ctree.getroot().findall(f'{WNS}comment'))
+assert doc_ids == comment_ids, f"ID mismatch: doc={doc_ids} comments={comment_ids}"
+```
+
+## Key Pitfall: Comment Text Extraction
+When extracting comment text for comparison, comments may have nested `<w:p>` elements (multi-paragraph comments). Use `.iter()` not `.findall()` to get all text nodes.
+
+## Empirical Case (2026-07-01 反委托代发工资协议)
+- Original: 4 comments (Alice id=0, Alice id=1, 法务 id=2, 杜律 id=3)
+- v1_doro_updated: 2 comments (华诚-Z id=0, Alice id=2) — lost Alice id=0/1, 法务, 杜律
+- Final: 5 comments (Alice id=0, Alice id=1, 法务 id=2, 杜律 id=3, 华诚-Z id=4)
+- 华诚-Z's comment was id=0 in v1_doro_updated, renumbered to id=4 in final
+- All commentRangeStart/End/Reference IDs updated in document.xml accordingly

skills/legal/contract-editor/references/contract-template-revision.md

@@ -0,0 +1,94 @@
+# 合同模板修订工作流（非workflow场景）
+
+## 触发条件
+用户要求参考一份新合同模板（保护甲方），将有利内容用修订模式改进原合同（乙方模板）。
+
+## 与标准 review-contract workflow 的区别
+- 不涉及 classifier/reviewer/editor/deliverer 角色链
+- 不使用 review-rules.md
+- 不需要 pass 流程（不写 tracker/xlsx）
+- 直接用 ContractEditor 库手动修订
+
+## 操作步骤
+
+### 1. 读取两份合同
+```python
+from contract_docx_lib import ContractEditor
+editor = ContractEditor('原合同.docx')  # 乙方模板，作为修订基底
+```
+同时用 python-docx 或 zipfile+lxml 读取新合同全文，逐条对比差异。
+
+### 2. 识别差异并分类
+- **可直接移植**：新合同中明确有利于甲方的条款（如违约金降低、管辖权、解除权限制）
+- **需要调整**：新合同有利但需适配原合同结构/编号的条款
+- **需要补充**：新合同仍未覆盖的保护甲方的内容（根据法律法规判断）
+
+### 3. 执行修订（最小化修改原则）
+- 整体格式、编号逻辑按**原合同**来
+- 用 `tracked_replace` 修改既有条款
+- 用 `add_clause` 新增条款（插在合同逻辑对应位置）
+- author=WB
+
+### 4. 法律研究（严禁凭记忆）
+每次修订前必须查证：
+- 最新法律法规（民法典、劳动合同法、劳务派遣暂行规定等）
+- 上海地区地方规定和司法实践
+- 行业惯例
+
+常见需要查证的点：
+- 违约金比例上限（司法实践中过高会被调整）
+- 管辖权约定（甲方所在地法院 vs 仲裁）
+- 劳务派遣的法定退回情形（劳动合同法第65条）
+- 雇主责任险要求（上海地区实务惯例）
+- 经济补偿金的法定标准
+
+### 5. 修订说明
+完成后向用户汇报：
+- 修订数量（insertions/deletions）
+- 每项修订的法律依据
+- 标注哪些是根据新合同移植、哪些是独立判断补充
+
+## 违约后果公式（核心原则，2026-06-29 Doro纠正）
+
+**"权利是法律给的，关键在违约后果"**——当法律已赋予甲方某项权利时，合同中简单写入"甲方有权XX"只是重复法律，没有实质保护价值。审查/修订的重点是**违约后果条款**：
+
+### 标准违约后果公式
+```
+甲方因此支付的一切费用、承担的赔偿或补偿金、损失等由乙方全额赔偿，
+乙方另向甲方支付违约金人民币      元。
+如对甲方造成其他不良影响的，乙方还应当消除一切影响。
+```
+
+### 三要素
+1. **赔偿范围**：一切费用、承担的赔偿或补偿金、损失等（括注具体类型如重新招聘费用、行政罚款、律师费、诉讼费等）
+2. **违约金**：金额留空（6个空格），由甲方根据实际用工规模和风险自行填写
+3. **消除影响**：兜底，覆盖名誉损害、商誉损失等非经济损失
+
+### 适用场景
+所有"乙方违反法定义务→甲方有权XX"类条款：
+- 资质丧失 → 不止"甲方有权解除"，要追加完整后果公式
+- 克扣工资/欠缴社保 → 不止"暂停付款"，要追加连带后果公式
+- 一般违约追偿 → 不止"有权追偿"，要写清赔偿范围+违约金+消除影响
+
+### 劳务派遣协议实证（2026-06-29）
+| 条款 | 原写法（弱） | 改后（含后果公式） |
+|------|------------|-------------------|
+| 资质丧失 | "甲方有权解除，乙方赔偿全部损失" | "乙方赔偿一切费用/赔偿或补偿金/损失（含重新招聘费、劳动者赔偿金、行政罚款、律师费等）+违约金___元+消除一切影响" |
+| 审核权 | "暂停支付相关费用直至整改完成" | 追加：因乙方违法行为导致甲方承担连带责任的，一切费用由乙方赔偿+违约金+消除影响 |
+| 一般追偿 | "甲方有权依法向乙方追偿" | "一切费用由乙方赔偿+违约金+消除一切影响" |
+
+## 2026-06-29 劳务派遣协议案修订清单
+
+| 修订 | 类型 | 法律依据 |
+|------|------|----------|
+| 乙方资质持续保证 | 新增 | 《劳务派遣暂行规定》第17条 |
+| 甲方监督检查权扩展 | 修改 | 《劳动合同法》第62条 |
+| 甲方调整岗位权 | 新增 | 《劳动合同法》第62条 |
+| 甲方随时退回权 | 新增 | 《劳动合同法》第65条、《劳务派遣暂行规定》第12条 |
+| 雇主责任险要求 | 新增 | 上海司法实践惯例 |
+| 乙方解除权限制 | 修改 | 《民法典》第563条（催告程序） |
+| 付款期限延长 | 修改 | 商业条款（甲方资金调度） |
+| 甲方违约金降低 | 修改 | 上海法院对过高违约金的司法调整 |
+| 乙方根本违约情形 | 新增 | 《民法典》第563条 |
+| 争议解决管辖 | 新增 | 《民事诉讼法》第35条（协议管辖） |
+| 附件和补充协议 | 新增 | 标准合同条款 |

skills/legal/contract-editor/references/cross-border-ma-fee-reference.md

@@ -0,0 +1,33 @@
+# 跨境并购费用参考（5000万人民币交易规模）
+
+> 来源：行业公开数据与市场实践，2026年6月。具体费用因交易复杂度、目标法域、各方谈判能力而异。
+
+## 各角色费用区间
+
+| 角色 | 费用（人民币） | 收费模式 |
+|---|---|---|
+| 财务顾问（FA） | 150万–250万 | 成功费，交易对价3%–5%；分期收取（签约10–20%，签约后40%，交割后40–50%） |
+| 法律顾问（中国律所） | 50万–100万 | 固定费，含法律尽调15–30万、交易文件20–40万、监管审批10–20万、境外律师协调5–10万 |
+| 境外律师 | 30万–80万 | 按小时（300–800美元/小时），目标法域决定 |
+| 会计师（财务尽调） | 20万–40万 | 固定费 |
+| 税务师 | 15万–35万 | 固定费，含税务尽调10–20万、结构优化5–15万 |
+| **合计** | **265万–505万** | 占交易额约5%–10% |
+
+## FA 费率惯例
+
+- 中国市场：中端交易3%–5%，大型交易费率递减
+- 海外莱曼公式（Lehman Formula）：累退费率，5000万人民币≈680万欧元→约15万欧元（约118万人民币），但中国市场费率通常高于莱曼
+- 中国FA实操中常用"一口价"或协商费率，少见纯莱曼公式
+
+## 交易协调人（律师兼任）收费参考
+
+- 固定项目管理费：5万–10万/月，或每项目15万–30万
+- 从FA成功费分成：10%–15%
+- 最优组合：固定费（保底）+ FA分成（激励）+ 法律费独立收取（不混）
+
+## 第三方机构管理原则
+
+- FA负责整体协调，但不代替第三方出具报告
+- 第三方费用由客户直接支付
+- 各机构独立承担专业责任
+- 律师（作为交易协调人）可帮FA管理第三方机构，但不能替第三方机构的工作成果背书

skills/legal/contract-editor/references/docx-comments-insertion.md

@@ -0,0 +1,102 @@
+# DOCX 批注（Word 原生 comment）插入 — 纯 zipfile+lxml
+
+实战来源：南通新东方校外培训服务合同独立审查（2026-06-17）。Maggie 要求"用修订**和批注**的形式"。`ContractEditor` 没有批注方法（`dir()` 确认无 comment/annot/note），批注必须手写 OOXML。已验证可在 OnlyOffice 正常显示。
+
+## 何时用 DOCX 批注 vs PDF 批注
+- **docx 合同** → 用本文方法（Word 原生 comment，OnlyOffice 显示为右侧批注气泡）。
+- **PDF 合同** → 用 pymupdf(fitz) 高亮+comment annotation（见 SKILL.md「PDF合同直接批注」）。两者不通用。
+
+## 批注内容铁律（与 SKILL.md 一致，复述强调）
+- 只写"建议……"，给方案；**不写理由/原因/因为**；**不加【新增】【建议】等标签**。
+- 批注仅限两类：①需客户确认（名称空白、标准未定义需明示）；②建议增加条款且内容较长。**选择题/勾选项不处理（2026-07-08废止）。**
+- 能直接修订的一律修订，批注是最后手段。
+
+## 五个改动点（缺一不可，否则 Word 报"无法打开/需修复"）
+1. **新增 `word/comments.xml`**：定义每条批注的 id/author/date/initials + 内容。
+2. **`word/document.xml`**：在锚点文本范围**前**插 `w:commentRangeStart`、**后**插 `w:commentRangeEnd` + 一个带 `w:commentReference` 的 run。
+3. **`[Content_Types].xml`**：加 `Override` 声明 comments.xml 的 content-type。
+4. **`word/_rels/document.xml.rels`**：加 `Relationship` 指向 comments.xml。
+5. 三处 id（rangeStart/rangeEnd/commentReference）与 comments.xml 的 `w:comment/@w:id` **必须全部一致**。
+
+## 锚点定位（关键陷阱）
+- 锚点文本要按**接受修订后**的文本匹配（遍历 w:t 时**跳过 w:del 内的**），否则被删字符会让匹配错位。
+- commentRangeStart 必须插在段落第一个 `w:r` **或 `w:ins`** 之前（不能只找 w:r——修订后段首可能是 ins）。
+- 先验证每个锚点在全文**唯一命中**（命中数==1）再插，多处命中会挂错段落。
+
+## 可复用代码
+```python
+import zipfile, io
+from lxml import etree
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+Wq = '{' + W + '}'
+DATE = "2026-06-17T10:00:00Z"
+
+comments = [  # 站顾问单位立场，需确认/建议增加内容
+    {"id":"201","anchor":"甲方扣除相应服务费后","text":"建议在合同或退费管理制度中明确“服务费”的扣费比例或计算方式，并在签约时向乙方明示。"},
+    {"id":"202","anchor":"向甲方住所地人民法院提起诉讼","text":"本条约定甲方住所地法院管辖，建议签约时以加粗或单独提示方式向乙方说明，尽到格式条款提示义务。"},
+]
+
+def build_comments_xml(comments):
+    p = ['<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
+         f'<w:comments xmlns:w="{W}" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">']
+    for c in comments:
+        p.append(f'<w:comment w:id="{c["id"]}" w:author="WB" w:date="{DATE}" w:initials="WB">')
+        # 批注文字字体随原文（本例宋体sz=18小一号），hint=eastAsia 必带
+        p.append('<w:p><w:r><w:rPr><w:rFonts w:ascii="宋体" w:hAnsi="宋体" w:eastAsia="宋体" w:cs="宋体" w:hint="eastAsia"/><w:sz w:val="18"/><w:szCs w:val="18"/></w:rPr>')
+        p.append(f'<w:t xml:space="preserve">{c["text"]}</w:t></w:r></w:p></w:comment>')
+    p.append('</w:comments>')
+    return ''.join(p)
+
+comments_xml = build_comments_xml(comments)
+with open('IN.docx','rb') as f: data=f.read()
+bi, bo = io.BytesIO(data), io.BytesIO()
+inserted = {c["id"]: False for c in comments}
+with zipfile.ZipFile(bi) as zin, zipfile.ZipFile(bo,'w',zipfile.ZIP_DEFLATED) as zout:
+    for it in zin.infolist():
+        raw = zin.read(it.filename)
+        if it.filename == 'word/document.xml':
+            tree = etree.fromstring(raw); body = tree.find(f'{Wq}body')
+            for para in body.findall(f'.//{Wq}p'):
+                ptext = ''  # 接受修订后文本：跳过 del
+                for t in para.findall(f'.//{Wq}t'):
+                    if not any(a.tag==f'{Wq}del' for a in t.iterancestors()):
+                        ptext += (t.text or '')
+                for c in comments:
+                    if not inserted[c["id"]] and c["anchor"] in ptext:
+                        cid = c["id"]
+                        first = next((ch for ch in para if ch.tag in (f'{Wq}r',f'{Wq}ins')), None)
+                        if first is None: continue
+                        crs = etree.Element(f'{Wq}commentRangeStart'); crs.set(f'{Wq}id',cid); first.addprevious(crs)
+                        cre = etree.Element(f'{Wq}commentRangeEnd');   cre.set(f'{Wq}id',cid); para.append(cre)
+                        rr = etree.SubElement(para,f'{Wq}r'); rp=etree.SubElement(rr,f'{Wq}rPr')
+                        rs = etree.SubElement(rp,f'{Wq}rStyle'); rs.set(f'{Wq}val','CommentReference')
+                        cref = etree.SubElement(rr,f'{Wq}commentReference'); cref.set(f'{Wq}id',cid)
+                        inserted[cid] = True
+            raw = etree.tostring(tree, xml_declaration=True, encoding='UTF-8', standalone=True)
+        elif it.filename == '[Content_Types].xml':
+            ct = etree.fromstring(raw); NS='http://schemas.openxmlformats.org/package/2006/content-types'
+            ov = etree.SubElement(ct,f'{{{NS}}}Override')
+            ov.set('PartName','/word/comments.xml')
+            ov.set('ContentType','application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml')
+            raw = etree.tostring(ct, xml_declaration=True, encoding='UTF-8', standalone=True)
+        elif it.filename == 'word/_rels/document.xml.rels':
+            rt = etree.fromstring(raw); RNS='http://schemas.openxmlformats.org/package/2006/relationships'
+            r = etree.SubElement(rt,f'{{{RNS}}}Relationship')
+            r.set('Id','rIdComments1')
+            r.set('Type','http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments')
+            r.set('Target','comments.xml')
+            raw = etree.tostring(rt, xml_declaration=True, encoding='UTF-8', standalone=True)
+        zout.writestr(it, raw)
+    zout.writestr('word/comments.xml', comments_xml.encode('utf-8'))
+with open('OUT.docx','wb') as f: f.write(bo.getvalue())
+assert all(inserted.values()), f"未全部挂靠: {inserted}"
+```
+
+## 交付前验证（缺一不可）
+1. **id 四向一致**：`commentRangeStart` / `commentRangeEnd` / `commentReference` 三组 id 集合 == comments.xml 的 `w:comment/@w:id` 集合。
+2. **python-docx 能打开**（XML 合法）。
+3. **接受修订后锚点存在**：批注挂靠的文本在去 del 后仍在。
+4. **OnlyOffice 渲染**（onlyoffice-render.sh）确认批注气泡正常显示，不破坏修订标记。
+
+## 修订与批注可共存
+同一份 docx 先用 ContractEditor 做完 tracked_replace/add_clause 并 save，再在产物上跑本脚本加批注。批注的 commentRangeStart 会落在修订后的段落结构里（段首可能是 w:ins），代码已用 `(w:r, w:ins)` 兼容。

skills/legal/contract-editor/references/duplicate-workflow-detection.md

@@ -0,0 +1,42 @@
+# 检测已审查文件重复处理（Workflow产出双版本问题）
+
+## 2026-07-13 消防设施检测合同教训
+
+### 现象
+同一份合同在任务交付目录出现两个文件：
+- v1: 有WB tracked changes（正确交付物）
+- v2: 无tracked changes + 有WB批注（纯批注版）
+
+### 诊断方法
+```python
+# 快速判断文件性质
+with zipfile.ZipFile(filepath, 'r') as z:
+    doc_xml = z.read('word/document.xml')
+    # 检查tracked changes
+    ins_count = doc_xml.count(b'w:ins')
+    del_count = doc_xml.count(b'w:del')
+    # 检查批注
+    has_comments = 'word/comments.xml' in z.namelist()
+    if has_comments:
+        comments = z.read('word/comments.xml')
+        comment_count = comments.count(b'w:comment ')
+
+print(f"INS: {ins_count}, DEL: {del_count}, Comments: {comment_count}")
+```
+
+### 判断标准
+| 文件状态 | 性质 | 应否保留 |
+|----------|------|----------|
+| 有INS/DEL + 无comments | 标准修订版 | ✅ 正确交付物 |
+| 有INS/DEL + 有comments | 修订+批注版 | ✅ 正确 |
+| 无INS/DEL + 有comments | 纯批注版 | ⚠️ 需审查批注合规性 |
+| 无INS/DEL + 无comments | 原文副本 | ❌ 不应在交付目录 |
+
+### 纯批注版的审查要点
+- 是否违反"能改就不批注"原则
+- 批注立场是否正确（站甲方）
+- 是否属于"提醒性批注"（禁止）
+- **严重错误示例**：Comment 203建议"违约金偏高，建议设上限"——这是在帮乙方限制甲方的违约金权利，立场完全反了
+
+### python-docx的.text陷阱
+`paragraph.text`不反映批注内容。两份文件的`.text`可能100%相同但实际一份有6条批注。**判断文件是否相同必须检查comments.xml**。

skills/legal/contract-editor/references/file-versioning-discipline.md

@@ -0,0 +1,42 @@
+# 文件版本管理纪律（2026-07-01 总结多次返工教训）
+
+## 铁律：操作前备份，操作后验证，不覆盖不重做
+
+### 1. 操作前必须备份
+任何对 docx 文件的修改操作前，先 `cp` 一份到 `/tmp/contract-backup/` 并带时间戳：
+```bash
+cp /tmp/反委托_版本1.docx /tmp/contract-backup/反委托_版本1_$(date +%H%M).docx
+```
+
+2026-07-01教训：反委托代发工资协议做了7-8个版本，每次覆盖前一版，最终华诚-Z的修订痕迹差点不可恢复（在v1_doro_updated.docx中找到最后一份）。
+
+### 2. 增量修复，不从头重做
+出问题时修补当前版本，不从原文件重新做一遍。重做=覆盖=丢失中间状态。
+
+### 3. 操作后验证完整性
+每次修改 docx 后必须验证：
+- comments.xml：批注数量、作者、ID 是否完整（与修改前对比）
+- document.xml：tracked changes 的 author 集合是否正确
+- 文件大小：是否合理（不应比修改前小太多）
+
+### 4. 中间版本命名规范
+```
+反委托_版本1_v1.docx  → 第一版
+反委托_版本1_v2.docx  → 第二版（不覆盖v1）
+反委托_版本1_v3.docx  → 第三版
+反委托_版本1_final.docx → 确认后的最终版（覆盖上传到Nextcloud）
+```
+
+### 5. Subagent 输出必须验证
+delegate_task 返回后：
+- 检查 result.status 是否 "completed"
+- 对文件类结果：用 zipfile 打开验证 comments/tracked changes 完整性
+- 不能假设 subagent 正确——它可能丢批注、改错 author、漏条款
+
+## 常见覆盖事故
+
+| 事故 | 根因 | 预防 |
+|------|------|------|
+| 华诚-Z修订被全部改成WB | 多次重做时每次都"统一author=WB" | 备份原始含华诚-Z的版本 |
+| 批注丢失（4条变2条） | 从头重建时没对比原文件的comments.xml | 修改后立即验证批注数量 |
+| 字体覆盖（仿宋_GB2312→仿宋） | 重做时用了错误的字体名 | 从原文件克隆rPr，不手写 |

skills/legal/contract-editor/references/high-density-tracked-changes-layering.md

@@ -0,0 +1,144 @@
+# Layering WB Revisions on High-Density Tracked Changes Documents
+
+## Problem
+When a document already has extensive tracked changes from another author (e.g., 华诚-Z with 170+ INS and 90+ DEL), ContractEditor's `tracked_replace` frequently fails with `ValueError: Element is not a child of this node` because the paragraph structure is heavily fragmented with interleaved `w:ins`/`w:del`/`w:r` elements.
+
+## Solution: Direct lxml Operations
+
+### Strategy
+Use zipfile + lxml to directly manipulate the XML instead of ContractEditor library. Three operation types:
+
+### 1. Append text to existing paragraph end
+Find the paragraph, locate the last content element, and append a `w:ins` after it.
+
+```python
+# Find the last non-pPr child element in the paragraph
+last_content = None
+for child in p:
+    if child.tag != f'{WNS}pPr':
+        last_content = child
+
+# Create INS element
+ins = etree.SubElement(p, f'{WNS}ins')
+ins.set(f'{WNS}id', str(next_id))
+ins.set(f'{WNS}author', 'WB')
+ins.set(f'{WNS}date', '2026-07-02T00:00:00Z')
+
+r = etree.SubElement(ins, f'{WNS}r')
+# Clone rPr from nearby run
+rpr = get_reference_rpr(p)  # see below
+if rpr is not None:
+    r.insert(0, copy.deepcopy(rpr))
+
+t = etree.SubElement(r, f'{WNS}t')
+t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+t.text = "追加的文字内容"
+```
+
+### 2. Insert new paragraph (全段INS)
+Clone neighboring paragraph's pPr, create a new `w:p` with all content inside `w:ins`.
+
+```python
+# Clone pPr from reference paragraph
+ref_p = paras[target_idx]  # the paragraph after which to insert
+new_p = etree.Element(f'{WNS}p')
+
+# Clone pPr
+ref_ppr = ref_p.find(f'{WNS}pPr')
+if ref_ppr is not None:
+    new_p.append(copy.deepcopy(ref_ppr))
+
+# Create INS wrapping all content
+ins = etree.SubElement(new_p, f'{WNS}ins')
+ins.set(f'{WNS}id', str(next_id))
+ins.set(f'{WNS}author', 'WB')
+ins.set(f'{WNS}date', '2026-07-02T00:00:00Z')
+
+r = etree.SubElement(ins, f'{WNS}r')
+rpr = get_reference_rpr(ref_p)
+if rpr is not None:
+    r.insert(0, copy.deepcopy(rpr))
+t = etree.SubElement(r, f'{WNS}t')
+t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+t.text = "新增条款全文"
+
+# Insert after reference paragraph
+ref_p.addnext(new_p)
+```
+
+### 3. Character-level replacement within high-density paragraph
+When text to replace is inside an existing `w:ins` from another author (e.g., 华诚-Z), you need to split that ins element.
+
+```python
+# Find the ins element containing target text
+for ins_elem in p.findall(f'{WNS}ins'):
+    for r in ins_elem.findall(f'{WNS}r'):
+        t = r.find(f'{WNS}t')
+        if t is not None and t.text and old_text in t.text:
+            # Split: keep text before, add WB del+ins for changed part, keep text after
+            pos = t.text.index(old_text)
+            before = t.text[:pos]
+            after = t.text[pos + len(old_text):]
+            
+            # Modify existing t to keep only 'before'
+            t.text = before + after.replace(old_text, new_text)  # simplified
+            # Or split into multiple elements...
+```
+
+### Getting reference rPr
+```python
+def get_reference_rpr(p):
+    """Get rPr from first non-del run in paragraph, or from 华诚-Z ins"""
+    # Try plain runs first
+    for r in p.findall(f'{WNS}r'):
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is not None:
+            return rpr
+    # Try non-WB ins elements
+    for ins in p.findall(f'{WNS}ins'):
+        if ins.get(f'{WNS}author') != 'WB':
+            for r in ins.findall(f'{WNS}r'):
+                rpr = r.find(f'{WNS}rPr')
+                if rpr is not None:
+                    return rpr
+    # Try previous paragraph
+    prev = p.getprevious()
+    if prev is not None:
+        return get_reference_rpr(prev)
+    return None
+```
+
+## Critical: Post-save sz fix
+
+When INS runs clone rPr from paragraphs that lack explicit `w:sz` (relying on style inheritance), the INS will render at wrong size. **Always run a post-save sweep:**
+
+```python
+# Determine dominant body sz from neighboring paragraphs
+# Then fix all WB INS runs missing sz
+for ins in body.iter(f'{WNS}ins'):
+    if ins.get(f'{WNS}author') != 'WB':
+        continue
+    for r in ins.findall(f'{WNS}r'):
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is not None:
+            sz = rpr.find(f'{WNS}sz')
+            if sz is None:
+                sz = etree.SubElement(rpr, f'{WNS}sz')
+                sz.set(f'{WNS}val', dominant_sz)  # e.g., '24' for 12pt
+                szCs = etree.SubElement(rpr, f'{WNS}szCs')
+                szCs.set(f'{WNS}val', dominant_sz)
+```
+
+## Author Unification
+
+After Doro reviews and confirms, unify all authors to WB:
+```bash
+python scripts/unify-author-wb.py input.docx [output.docx]
+```
+
+## Lesson Learned (2026-07-02)
+- Doro will edit the files in OnlyOffice after upload. Always download Doro's version before doing further work.
+- "你自己要满意再给我" = self-verify before delivery, don't ask user to check.
+- "认真做" = thoroughness signal. Read full contract text, verify each modification landed correctly.
+- When Doro says "看看是否还有需要调整的" = compare your version vs Doro's, identify what Doro changed, assess if further work needed.
+- Unifying author is a standard final step — use the script, don't hand-code each time.

skills/legal/contract-editor/references/lawyer-letter-formatting.md

@@ -0,0 +1,27 @@
+---
+name: lawyer-letter-formatting
+description: 律师函制作格式要点。基于Watson&Band模板，logo在正文段落anchor中而非header XML。
+tags: [legal, lawyer-letter, docx, formatting]
+---
+
+# 律师函制作
+
+## 关键格式（参考_律师函模板）
+- **字体**：仿宋 12pt，西文Times New Roman
+- **首行缩进**：304800 EMU
+- **行距**：1.25倍
+- **对齐**：两端对齐(JUSTIFY)
+- **列表编号**：numbering.xml中japaneseCounting格式（第一、第二、第三、）
+- **送达信息**：9pt
+
+## 关键陷阱
+- **Logo不在header XML中**！是作为浮动锚点(anchor drawing)嵌在正文第一段落的run中
+- 用python-docx重建段落会丢失drawing元素，必须从模板段落提取保留
+- 复制模板时要保留原始段落的XML结构，不能只复制文字
+
+## 参考文件位置
+- 模板：Doro诉讼案件任务/参考文件/_律师函
+
+## 交付位置
+- 放到 Doro其他任务/交付文件/（不是待处理任务）
+- 交付后@doro通知

skills/legal/contract-editor/references/layer-revisions-on-user-revised-doc.md

@@ -0,0 +1,68 @@
+# 在「用户已自行修订过」的合同上叠加我方修订
+
+实战来源：金信大厦5层东部租赁合同（2026-06-25）。Maggie 本人已用修订模式改了 6 处（author="maggie jia"），要求小Maggie 在此基础上**再补几处**（模版比对后补不可抗力对等、装修残值公式、抵押救济），**保留她的全部修订一字不动**。
+
+## 何时用本配方
+- 收到的 docx **已带 track changes**（settings.xml 有 `<w:trackRevisions/>`，文中有 author≠WB/小Maggie 的 w:ins/w:del）。
+- 任务是**在用户既有修订之上追加几处**，不是重审、不是从干净稿做。
+- **不重跑 workflow，也不用 ContractEditor 库**——库的字符级 diff 引擎会把用户既有 w:ins/w:del 卷进来重算，破坏其修订。一律 zipfile+lxml 直接追加节点。
+
+## 五步配方
+
+### 1. 新修订 id 从 `maxid+1000` 起，防撞 + 便于事后过滤
+```python
+maxid = 0
+for el in root.iter():
+    if el.tag in (Wq+"ins", Wq+"del"):
+        v = el.get(Wq+"id")
+        if v and v.isdigit(): maxid = max(maxid, int(v))
+nextid = [maxid + 1000]            # 1000 间隔：本次新增 id 全 >1000，过滤/核验时一眼区分
+def newid(): nextid[0]+=1; return str(nextid[0])
+```
+为什么 +1000 不是 +1：核验「我的修订」与「用户的修订」时，`int(id)>1000` 直接切分两批，不必记具体数字。
+
+### 2. 作者：沿用文档既有修订线，不强行套 WB
+金信大厦案文档既有修订 author="maggie jia"，本次追加**沿用同一 author**（保持修订线一致、Maggie 看就是「她那条线的延续」）。
+> 注意与「author 铁律=WB」的边界：WB 是 Doro 体系合同审查的署名；当**文档已有用户自己的修订线**、任务是「在她的修订上接着改」时，沿用她的 author 让修订归并到同一作者更自然。归属按文档既有线定，不是无脑套 WB。拿不准就问。
+
+### 3. rPr：克隆「用户已渲染正确的 INS」当样板，预防中文字体回退坑
+不要自己造 rPr。找一个用户已有的、**中文显示正常的** w:ins run，读它的 rPr 当模板：
+```python
+# 金信大厦案模板：<w:rFonts w:ascii="Times New Roman" w:eastAsiaTheme="minorEastAsia"
+#                  w:hAnsi="Times New Roman" w:cs="Times New Roman" w:hint="eastAsia"/>
+#                 <w:sz w:val="21"/><w:szCs w:val="21"/>
+def make_rpr():
+    rpr = etree.Element(Wq+"rPr")
+    rf = etree.SubElement(rpr, Wq+"rFonts")
+    rf.set(Wq+"ascii","Times New Roman"); rf.set(Wq+"eastAsiaTheme","minorEastAsia")
+    rf.set(Wq+"hAnsi","Times New Roman"); rf.set(Wq+"cs","Times New Roman"); rf.set(Wq+"hint","eastAsia")
+    sz = etree.SubElement(rpr, Wq+"sz"); sz.set(Wq+"val","21")
+    etree.SubElement(rpr, Wq+"szCs").set(Wq+"val","21")
+    return rpr
+```
+`eastAsiaTheme="minorEastAsia"+hint="eastAsia"` 让中文走主题回退（金信大厦回退到宋体），西文 Times New Roman——这是这类合同 INS 中文正常显示的关键，详见 SKILL.md「INS 中文字体」节。
+
+### 4. 三种插入机制（按改动类型选）
+- **纯追加**（句末补一句救济/公式）：定位段落最后一个 normal run / 最后一个 ins，`last.addnext(make_ins(text, rpr))`。
+- **删一段换对等表述**（单向条款改双向）：split 原 run → 原 run 文本保留前半、`addnext(make_del(后半, 原rpr))` → 再 `del.addnext(make_ins(对等表述, rpr))`。
+- **替换数值/词**（6→12 个月、percent→百分之）：字符级定位，DEL 旧 + INS 新。
+
+`make_del` 用 `<w:del><w:r><w:delText>`、克隆原 run 的 rPr 加 `rsidDel`；`make_ins` 用 `<w:ins><w:r><w:t xml:space="preserve">`。
+
+### 5. 只换 document.xml（settings 已开 trackRevisions 就不动它）
+```python
+with zipfile.ZipFile(SRC) as zin, zipfile.ZipFile(tmp,"w",zipfile.ZIP_DEFLATED) as zout:
+    for it in zin.namelist():
+        zout.writestr(it, new_doc if it=="word/document.xml" else zin.read(it))
+```
+
+## 四查验证（缺一不可）
+1. **python-docx 能打开**（`Document(out)`）——XML 合法。
+2. **接受所有修订后文本正确**——抽出「保留 ins 内容、丢弃 del 内容」的纯文本，逐处核我改的几段语句通顺、内容对。
+3. **本次新增 INS（id>1000）含中文 run 字体非 Times New Roman**——`eastAsiaTheme=="minorEastAsia" or (ea and ea!="Times New Roman")` 应全真。
+4. **🔴 用户原有修订逐 id 比对一字未动**——把源文件与产物里 `id<=maxid` 的所有 ins/del 提成 `(id, tag, author, 文本)` 排序比对，必须**完全相等**。这是本配方的核心安全验证：证明我只追加、没碰用户的任何一处。
+
+## 收口（与库路径相同）
+`scripts/accept-revisions-preview.py` 生成干净版 → OnlyOffice 渲染 → vision 视觉验收。
+- **vision 报「页底某句截断」先分清 PDF 分页 vs 真丢数据**：金信大厦案 vision 报抵押救济句在 P7 底部截断，实为该句跨页接到 P8 开头——①数据层读该 INS 完整内容在；②P7+P8 拍平后 grep 完整句存在 → 确认是 PDF 分页跨页，OnlyOffice 滚动查看正常，**不返工**。判据同 contract-portfolio-analysis Pitfall：数据层完整+跨页搜得到=分页现象。
+- vision 对字体/‰%/小符号的误判同样适用——回数据层核，别据像素返工（见 SKILL.md「交付前视觉验收的两个已知误判」）。

skills/legal/contract-editor/references/legal-doc-footnotes-and-templating.md

@@ -0,0 +1,62 @@
+# 法律文书：脚注、同源模板成稿、Doro 编辑后字体修复
+
+contract-editor 库（zipfile+lxml）在**新成稿文书**（非修订态）上的复用。2026-06-23-24 邹家《情况反映》制作中验证。配套 `litigation-doc-tracked-changes.md`（那篇讲修订态；本篇讲脚注+新建文书+字体规范化，都不是 tracked-changes）。
+
+## 1. 法条原文脚注——从同案"姊妹文书"克隆脚注样式（铁律：脚注样式不要凭空造）
+
+需求场景：Doro 把正文里的法条引用（"《民事诉讼法》第七十一条之规定"）要求改成**脚注呈现法条全文**，且"脚注格式和申请书一样"。
+
+正确做法是从**同案已有带脚注的文书**（如同目录的《民事诉讼监督申请书》v9）克隆脚注体例，而不是自己拼 footnotes.xml：
+
+**脚注的两个组成**（先从姊妹文书读出样式模板）：
+- 正文里的**引用标**：一个 `<w:r>`，rPr 带 `<w:rStyle w:val="affb"/>` + Times New Roman + 与正文同字号（sz24），内含 `<w:footnoteReference w:id="N"/>`。`affb` 是 Word 默认的 FootnoteReference 字符样式 id（不同文档可能不同，**从姊妹文书正文的 footnoteReference 承载 run 实测，别硬编码**）。
+- footnotes.xml 里的**脚注正文**：separator/continuationSeparator 两个特殊脚注（id=-1/0，原样复制）+ 内容脚注（id≥1）。内容脚注段落 spacing line=240，run 字号是**脚注体例 sz18（9pt，小于正文）**，法名加粗（`<w:b/>`）、条号与原文不加粗。
+
+```python
+# 从姊妹文书 sqs_v9.docx 取模板
+fn_sqs = etree.fromstring(z_sqs.read('word/footnotes.xml'))
+special = {ft: deepcopy(f) for f in fn_sqs.iter(qn('footnote'))
+           for ft in [f.get(qn('type'))] if ft in ('separator','continuationSeparator')}
+content_tmpl_p = deepcopy([f.find(qn('p')) for f in fn_sqs.iter(qn('footnote'))
+                           if f.get(qn('id'))=='1'][0])
+# 从模板段落抽三种 rPr：mark(带rStyle affb)、bold(法名)、plain(原文)
+# 正文引用标 rPr 则从姊妹文书 document.xml 里 footnoteReference 承载 run 抓
+```
+
+**目标 docx 必须已支持脚注**：`word/_rels/document.xml.rels` 有 footnotes 关系、`[Content_Types].xml` 有 `footnotes+xml`、styles.xml 有 `affb` 样式。若目标是从同源文书演化来的（本例情况反映以申请书为母版），这三样天然齐全；若从零新建则要补。
+
+## 2. 脚注标定位的坑：锚点跨 run 时 footnoteReference 会插错位置（本会话实犯）
+
+把脚注标插在"第五十一条第二款"之后时，第一版用"找锚点子串→定位锚点所在 run→run 后插标"，结果 ³ 插到了下游的"承办部门"后面——因为锚点文字**跨多个 run**，按 run 粒度定位会落到错误的 run。
+
+**正解：字符流定位 + 必要时拆 run**。把全段所有 `w:t` 拼成字符流，建立 `每个字符→(t元素, 字符在t内的索引)` 映射，找到锚点**结束字符**的精确位置；若结束字符在某 run 中间，**split 该 run**（head 留原 run，tail 进新 run），脚注引用 run 插在 head 和 tail 之间。这样标精确落在"…第二款【标】所定…"。
+
+验证只能靠 OnlyOffice x2t 渲染后看页脚——vision 一眼就抓出"³ 标在承办部门后"，肉眼读 XML 容易漏。体例统一：四个脚注一律"法条号正后方"挂注（不要有的挂句末有的挂条号后）。
+
+## 3. 用同案文书做"母版"新建文书——保证两份同源同体例
+
+新建《情况反映》时，以同案《民事诉讼监督申请书》v9 为母版克隆，确保字体/字号/页边距/样式完全一致（Doro/Maggie 两份并排看不会有体例差）：
+- 从母版抽各类段落模板：title(居中bold sz30)、body(首行缩进480 sz24)、recip(顶格bold 机关名)、sign(右对齐)、date、attachment-title、attachment-item。`mk(tmpl_key, text, bold=, no_indent=)` 克隆模板段→清空 run/numPr/ins/del→重设仿宋+Times→填文字。
+- 用母版的整个 docx 做容器（保留 sectPr 页面设置、styles、numbering），只重写 body 的段落序列 + 清掉 `<w:trackRevisions/>`。
+- **清掉母版页眉**：母版页眉可能是另一种文书的抬头（本例申请书页眉"申请监督案号/受理法院"套在情况反映上不对）。清页眉要两步：①删页眉段所有 run 文字；②**删页眉段 pPr 的 `<w:pBdr>`**（页眉那条横线来自段落下边框，只删文字会留一条孤线）。OnlyOffice 渲染确认顶部纯白到标题。
+
+## 4. ⚠️Doro 用编辑器改过的 docx 会丢显式 eastAsia 字体属性——每轮都要补（本会话两轮各犯一次）
+
+**现象**：Doro 在他本机编辑器改过 docx 后回传，正文中文 run 的 `rFonts` **没有显式 eastAsia 字体名**（本会话两轮分别 1283、1243 个中文字符 `eastAsia=None`，docDefaults 也空）。OnlyOffice 靠底层回退仍渲染成仿宋、肉眼看正常，但**显式字体属性缺失不符合交付标准**（我们要求中文显式仿宋）。
+
+**判别**：交付前扫一遍——
+```python
+for r in root.iter(qn('r')):
+    rf = r.find(qn('rPr/rFonts'))
+    ea = rf.get(qn('eastAsia')) if rf is not None else None
+    # 统计含中文 run 里 ea is None 的数量；>0 就要补
+```
+
+**修复（格式规范化，不改字形/文字/Doro 内容）**：每个含文字的 run，rFonts 显式设 `eastAsia=仿宋`，缺 ascii/hAnsi 的补 `Times New Roman`；再给 `docDefaults/rPrDefault/rPr/rFonts` 补 `eastAsia=仿宋` 兜底。改完目标：CJK 全仿宋、英数全 Times。**这是和合同字体规范化同类的操作，但要点在"每次 Doro 回传都要重做一遍"**——他的编辑器每改一次就再剥一次，不是一次性问题。改完必须 OnlyOffice 重渲染确认无字形回退（字体属性动过就要重验）。
+
+## 5. 附件/正文 Doro 自己加的内容：修错别字但不擅改实质
+
+Doro 自己在附件加了"检查监督申请书"——①错别字"检**查**"→"检**察**"院的监督，规范名应是与正式文件名一致的《民事诉讼监督申请书》（改）；②但若附件项之间有实质区分缺失（如两份《质证通知书》一份标了"3日期限版"另一份没标"15日期限版"），那是 Doro 定的内容，**只提示不擅改**。附件清单常是自动编号（numId），Doro 删手敲序号是对的，自动会续 1-6。
+
+## 一句话
+脚注从同案姊妹文书克隆样式（rStyle affb + sz18 脚注体、法名加粗）、标位置用字符流+拆run精确落在条号后；新建文书拿同案文书做母版保同源（清页眉含删 pBdr）；**Doro 编辑器回传的 docx 每轮都丢显式 eastAsia，每次交付前都要全局补仿宋再渲染**。

skills/legal/contract-editor/references/litigation-doc-footnotes-and-templates.md

@@ -0,0 +1,73 @@
+# 诉讼文书：法条原文脚注 + 母版克隆建新文书 + 字体规范化
+
+contract-editor 库在诉讼文书上的三组技法，2026-06-23/24 邹家「情况反映」（给法院监督部门的程序违法反映材料）制作中验证，全部 OnlyOffice x2t 渲染逐页核对过。与 `litigation-doc-tracked-changes.md`（修订态技法）互补——本文是**脚注 + 新建文书 + 字体**层面。
+
+---
+
+## 一、法条原文脚注（Doro 偏好：引用法律规定一律用脚注呈现原文，不删改不概括）
+
+Doro 对引用法条的文书要求：**法条原文（一字不改、不归纳）用脚注方式写进去**。监督申请书 v9 已是这个体例，情况反映照搬。这是可复用的整套做法。
+
+### 1. 脚注格式从同族已有文书克隆，不自造
+申请书 v9 的 `word/footnotes.xml` 是现成模板。提取三样：
+- **两个特殊脚注** `type=separator` / `type=continuationSeparator`（id=-1/0）——分隔线，照搬。
+- **一个内容脚注的段落骨架**（id=1 的 `<w:p>`）——拿它的 `pPr`（脚注段 `spacing line=240`）和三种 run 的 `rPr` 模板：
+  - **mark rPr**：带 `<w:rStyle w:val="affb"/>` + Times New Roman + **sz18**（9pt 脚注体，不是正文 sz24）——脚注区那个序号。
+  - **bold rPr**：`<w:b/>` + sz18——法名加粗用。
+  - **plain rPr**：sz18 无 rStyle 无 b——条号+原文用。
+- 正文里的脚注引用标（`footnoteReference` 承载 run）的 rPr 另取：从 v9 **正文** 里找 `r/footnoteReference` 那个 run 的 rPr（`rStyle=affb` + Times + **sz24**，跟正文同号，上标由 affb 样式控制）。
+
+每条脚注 `<w:footnote id=N>` 段落结构：`[footnoteRef(mark rPr)][空格(plain)][法名(bold rPr)][条号+原文(plain rPr)]`。条号与原文之间用**全角空格**（如「第七十一条　证据应当…」）。
+
+### 2. 目标 docx 已支持脚注则零配置
+情况反映是从 v9 编辑来的，本就带 `word/footnotes.xml`、rels 里有 footnotes 关系、`[Content_Types].xml` 有 `footnotes+xml`、styles.xml 有 `affb` 样式——直接覆盖 footnotes.xml + 在 document.xml 插引用标即可，**不用补 rels/CT/style**。动手前先 grep 确认这四样齐全；若是从无脚注的 docx 起步，才需要补全四处。
+
+### 3. 插入引用标的位置铁律 + 多 run 锚点陷阱（本次踩坑）
+脚注上标要紧贴**法条号正后方**（如「第七十一条¹之规定」「第五十一条第二款³所定」），不要落在句末或下游词上。统一体例：四个脚注全部「条号后挂注」最整齐。
+
+**陷阱**：`第五十一条第二款` 这种锚点在 docx XML 里常**跨多个 w:r**（编号、款号被拆在不同 run）。若按"找到 anchor 所在 run、在该 run 后插引用"的粗定位，会把上标插到 anchor **下游某个 run 后**——本次 ³ 错插到了「承办部门」后（隔了好几个词）。OnlyOffice 渲染出来才发现，vision 核对抓到的。
+
+**正解：字符流 + split run 精确定位**：
+```python
+# 1) 拼接段落所有 w:t 成 full，建 map: full每个字符 -> (t_element, idx_in_t)
+# 2) end = full.find(anchor) + len(anchor) - 1   # 锚点最后一个字符
+# 3) t_end, k_end = map[end]；把 t_end 文本 split：head=s[:k_end+1], tail=s[k_end+1:]
+# 4) t_end.text=head；在 t_end 所在 run 之后 addnext 一个新 run(脚注引用)；
+#    若 tail 非空，再 addnext 一个同 rPr 的 run 承载 tail
+```
+这样上标精确落在锚点最后一字之后，不受 run 边界影响。容错：`第五十一条第二款` 找不到时退化找 `第五十一条`。
+
+### 4. 款数存疑时，脚注放全条原文
+Doro 引「第五十一条**第二款**」，但权威原文里"普通程序不少于十五日"实际在**第一款**。**不擅改他的款数**——脚注内容放该条**全文（含两款）**，无论款数对错，原文都完整覆盖、不断章；款数是否要改回原文里报给 Doro 定，不自己动。
+
+---
+
+## 二、母版克隆建新诉讼文书（保证与同案既有文书同源）
+
+新建一份配套文书（情况反映 vs 已有的监督申请书），要让字体/字号/页边距/样式与同案既有文书**完全同源**——直接拿那份已交付的 docx 当母版。
+
+- **段落模板克隆**：从母版 body 抓代表性段落各一份 deepcopy 当模板——title（居中 bold sz30）、body（首行缩进 fl480 sz24）、recip（机关名顶格 bold sz24）、sign（右对齐 sz24）、date（右对齐）、attt（附件标题顶格 bold）、att（附件项 fl480）。`mk(模板, 文本, bold, no_indent)`：克隆模板→清空其 run/ins/del→（按需删 numPr/ind）→`force_font`(eastAsia=仿宋, ascii/hAnsi=Times)→写新 run。
+- **清空原 body 段落**，把新段落 insert 到 `sectPr` 之前（保页边距/分节设置不变）。
+- **关 trackRevisions**：新建文书是全新成稿、非修订态，settings.xml 删 `<w:trackRevisions/>`。
+- **页眉错配必须清**（本次踩坑）：母版（监督申请书）的 `header1.xml` 带"申请监督民事诉讼案号/受理法院"这种**本文书类型专属抬头**，套到情况反映上不对路。处理：清空 header 所有 run 的文字。
+- **页眉横线 = pBdr，单清文字不够**：清了页眉文字后 OnlyOffice 仍渲出一条横线——来自页眉段落的 `<w:pBdr>`（段落下边框）。遍历 header 所有 `pPr` 删 `pBdr`（本例 2 段），并去掉可能带边框的 `pStyle` 引用。styles.xml 里的 Header 样式若也挂 pBdr 一并清。重渲确认顶部纯白到标题。
+
+---
+
+## 三、字体规范化：源文档丢了显式 eastAsia 字体
+
+**症状**：用户编辑过的 docx，正文中文 run 的 `rFonts` **没有 eastAsia 属性**（eastAsia=None），docDefaults 也没设。OnlyOffice 靠底层回退仍渲成仿宋，但**显式字体属性缺失**不符合"中文必须显式仿宋"的交付标准。本次 Doro 改的情况反映 1283 个中文字符全是 eastAsia=None。
+
+**判断边界（重要）**：先比对**用户原版**——若原版本就是 eastAsia=None（不是你的编辑引入的），补齐属于**格式规范化（不改字形、不改一个文字、不动他的内容编辑）**，与历史上的字体规范化同类，可做。若是你的操作把字体搞丢的，那是 bug 要修源头。
+
+**修法**：遍历所有含文字的 run，`rFonts` 设 `eastAsia=仿宋`，缺 ascii/hAnsi 则补 Times New Roman；再给 `docDefaults/rPrDefault/rPr/rFonts` 补 eastAsia=仿宋 兜底。改完 OnlyOffice **重渲**确认无字形回退（字体改动必重渲，vision 核"全文仿宋、无方框、无回退乱码"）。核验：zipfile 统计 CJK→仿宋、LATIN→Times New Roman 计数全覆盖。
+
+---
+
+## 验收三件套（脚注版）
+1. **正文脚注引用数** == 预期（`sum(r.find(footnoteReference) for r in runs)`）。
+2. **footnotes.xml 内容数** == 引用数，逐条 print 前 50 字核法名+条号+原文。
+3. **OnlyOffice x2t 渲染逐页 vision 核**：每个上标在**正确法条号正后方**（重点查多 run 锚点那条没错位）、页脚脚注区原文完整无截断、脚注字号 < 正文、法名加粗、无乱码。脚注主要落在前两页，逐页都要看。
+
+## 一句话
+法条脚注：格式克隆同族文书的 footnotes.xml（separator+内容模板，mark/bold/plain 三 rPr），引用标用 split-run 精确插在条号后（多 run 锚点必踩坑），款数存疑放全条原文不擅改。建新文书：克隆母版段落模板保同源，清错配页眉+pBdr 横线。字体：源档丢 eastAsia 时补齐属于规范化（先确认是原档状态不是自己搞丢的），改完必重渲。

skills/legal/contract-editor/references/litigation-doc-tracked-changes.md

@@ -0,0 +1,74 @@
+# 诉讼文书的修订态技法（contract-editor 库在合同以外文书上的复用）
+
+ContractEditor 库不止用于合同——审/改诉讼文书（监督申请书、起诉状、答辩状等）同样适用。本文记录 2026-06-23 邹家民事诉讼监督申请书审改中验证过的几招，都用 OnlyOffice x2t（Doro/Maggie 实际引擎）渲染核对过。
+
+## 1. 大段改写用「整块 del+ins」，不用字符级 diff（markup 可读性铁律）
+`tracked_replace` 是字符级 diff（CJK 每字一 token + difflib）——**补字/小改**（错别字、补一个"在"字、称谓换词）用它，markup 干净。
+但**大段改写**（整句重写、换论证）若用字符级 diff，新旧文本大量字符重合，markup 会交错成一团（"未经~~及~~法庭审理""一百二十八条~~切~~国家机关"），Doro 在 OnlyOffice 看修订态根本读不下去。**接受修订后的最终文本虽正确，但修订态不可读 = 不合格交付**（Doro 有格式洁癖，看的就是 markup）。
+- **正解**：对整句/整段改写，做「整块删 + 整块插」——`[<w:del>旧整句</w:del>][<w:ins>新整句</w:ins>]`，markup 显示为一条删除线旧句紧跟一条下划线新句，清清楚楚。
+- 实现：复制 `tracked_replace` 的定位逻辑，但不跑 difflib，直接 `_mk_del(old_text)` + `_mk_ins(new_text)` 整块插。判据：**新旧文本相似度高、改动跨度大 → 整块；纯增删几个字 → 字符级**。
+
+## 2. 称谓/词替换也要整词块替换，别让共享字符碎裂
+把"法**庭**"改"莲都法**院**"时，"法"字共享，字符级 diff 会渲染成"莲都法~~庭~~院"（接受后对，markup 脏）。
+- **正解**：整词 `tracked_block_replace("本案法庭向申请人送达", "莲都法院向申请人送达")` → markup 是干净的[删旧短语][插新短语]。
+- 同理坑：替换前先分类全文每处目标词——actor 指代（要改）vs 法条/术语原文（如"法庭审理""在法庭上出示"=不能动）。grep 出所有命中，逐个判，别一刀切 replace_all。
+
+## 3. 整段删除（让自动编号重排）——库没有，需自加 `tracked_delete_paragraph`
+合并两个自动编号请求项（删一项、后项自动续号）时，要的是**段落级修订删除**：段内每个 run 包进 `<w:del>`，**且段落标记也要标删**——在 `pPr/rPr` 里插一个 `<w:del>`。这样接受修订后整段连段落标记一起消失，自动编号从 一二三四 重排成 一二三。
+```python
+def tracked_delete_paragraph(self, search_text):
+    p = self.find_para(search_text)
+    for r in list(p.findall(qn('r'))):
+        # 每个run的w:t搬进新建<w:del><w:r><w:delText>
+        ...
+    ppr = p.find(qn('pPr')) or 新建
+    rpr = ppr.find(qn('rPr')) or 新建
+    rpr.insert(0, <w:del author=... date=...>)   # 段落标记删除标记
+```
+缺了"段落标记删除"那一步，接受后会残留一个空的编号项。
+
+## 4. 半角括号→全角：改 numbering.xml 的 lvlText，一次性根治
+子标题 `(一)(二)…` 是自动编号时，半角括号来自 `word/numbering.xml` 里 `<w:lvlText w:val="(%1)">`。逐段改文档没用（那是渲染出来的）。
+- **正解**：遍历 numbering.xml 所有 `<w:lvlText>`，`val` 里的 `(`→`（`、`)`→`）`，一次改全文所有同源编号。本例 37 处 lvlText 一次改完。
+- 注意只动含 `()` 的 lvlText，`、`分隔的（如请求"一、二、三"用 `%1、`）不受影响。
+
+## 5. 引号"统一为仿宋全角"——根因是引号 run 的字体不是中文字体
+现象：正文中文是仿宋（继承样式），但弯引号 `“”`(U+201C/U+201D) 的 run `ascii=Times New Roman, eastAsia=None`。因为弯引号是**中西文模糊字符**，OnlyOffice 对没有 eastAsia 设定的字符按 ascii 字体渲染 → 引号显示成西文 Times 的粗重样式，和仿宋正文不协调。
+- **正解（彻底版）**：对**纯引号/中文 run**，把 rFonts 的 `ascii/eastAsia/hAnsi/cs` 全设为「仿宋」+ `hint="eastAsia"`，消除歧义。对**引号+数字混排 run**（如 `“2026…`），按字符**拆 run**：引号段走仿宋、数字段保留 Times New Roman。
+- 只设 eastAsia 不够稳——某些渲染下仍可能按 ascii 走 Times。纯引号 run 连 ascii 一起设仿宋最保险（数字 run 才需要保留 Times）。
+- 核对：OnlyOffice x2t 渲染后裁剪含引号区域，确认引号纤细、与仿宋协调（不是又粗又重的衬线引号）。
+
+## 6. 验证三件套（同合同终审，文书一样适用）
+- `ed.validate()` 返回空。**注意**：诉讼文书的「请求项」原文常是加粗的（与合同正文不加粗体例不同），validate 的"不应加粗"规则会**误报**——先读原文该段普通 run 的 `<w:b>` 状态，若原文请求项本就加粗、INS 继承同样加粗=格式一致=误报，可放行。
+- 逐个 `w:ins` 核 author 正确（诉讼文书署当前文书归属人，如本例 Doro 文书上署"小Maggie"修订；合同历史署"WB"——按文书归属定）、eastAsia 字体不缺。
+- OnlyOffice x2t 渲两版：**修订态**（看 markup 干净）+ **接受态**（删 w:del、解包 w:ins、删段落标记被删的空段后重渲，看编号连续、全角括号生效、无乱码）。接受态自己生成：解包所有 ins、删所有 del、删 numPr 空段。
+
+## 一句话
+合同库的修订能力对所有 docx 文书通用；诉讼文书审改的差异点是：①大改写要整块 del+ins 保 markup 可读 ②引号/括号这类「字体/编号源」问题改 styles/numbering 层不改文档层 ③validate 加粗规则对加粗请求项会误报。
+
+## 7. 接受所有修订 → 干净版 docx（反向操作，2026-06-24 徐函任务验证）
+用户给一份**带修订痕迹+批注**的 docx，要「先接受现有修订、让我看干净版本」时——不是用 Word 手点"接受全部"，用 zipfile+lxml 一次处理：
+```python
+W='http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+def w(t): return f'{{{W}}}'+t
+# 1) w:del → 整个元素删掉（连 delText 一起没）
+for d in root.findall('.//'+w('del')): d.getparent().remove(d)
+# 2) w:ins → 解包：用其子元素替换它本身（保留插入内容，去掉ins包裹）
+for ins in root.findall('.//'+w('ins')):
+    parent=ins.getparent(); idx=list(parent).index(ins)
+    for child in reversed(list(ins)): parent.insert(idx, child)
+    parent.remove(ins)
+# 3) 属性变更追踪一并清：pPrChange/rPrChange/sectPrChange/tblPrChange/tcPrChange/trPrChange
+for tag in ('pPrChange','rPrChange','sectPrChange','tblPrChange','tcPrChange','trPrChange'):
+    for el in root.findall('.//'+w(tag)): el.getparent().remove(el)
+# 4) 批注三处一起拆（用户要"干净版"= 连批注也清）：
+#    document.xml: 删 commentRangeStart/End，删含 commentReference 的整个 run
+#    settings.xml: 删 <w:trackRevisions/>（让文件退出跟踪模式）
+#    打包时跳过 word/comments*.xml，并从 [Content_Types].xml 和 document.xml.rels 删 comments 的 Override/Relationship
+```
+要点：
+- **w:del 删整块、w:ins 解包**——方向别搞反（del 是要丢弃的，ins 是要保留的）。
+- **务必清 settings.xml 的 trackRevisions**，否则文件仍处于"跟踪修订"模式，用户继续编辑会又开始记修订。
+- **批注要三处协同删**（comments.xml 本体 + document.xml 的 range/reference 锚点 + Content_Types/rels 注册），漏一处 OnlyOffice/Word 打开可能报损坏。
+- 验证：解包后 `root.findall('.//w:ins')`/`w:del`/`w:commentReference` 全为 0；`'word/comments.xml' in zip.namelist()` 为 False；python-docx 能打开；OnlyOffice x2t 渲染核对无修订痕迹无批注无错位。
+- vision 核干净版时顺带抓**残留内部标记**：黄色高亮（内部校对标记）、留白占位（编号"第　号"、日期"　日"）、标题英文双连字符`--`应为中文破折号`——`——这些不是修订痕迹但属"未清的内部审核稿"特征，正式交付前要清。

skills/legal/contract-editor/references/lxml-xml-declaration-fix.md

@@ -0,0 +1,126 @@
+# lxml XML Declaration Fix for docx Files
+
+## Problem (2026-07-01, 劳务派遣协议案)
+
+When lxml serializes XML (via `etree.tostring()` or python-docx's `Document.save()`), it outputs:
+- **Single-quote** XML declaration: `<?xml version='1.0' encoding='UTF-8' standalone='yes'?>`
+- **LF** line endings (`\n`)
+
+Original docx files (created by Word/WPS/OnlyOffice) use:
+- **Double-quote** XML declaration: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`
+- **CRLF** line endings (`\r\n`)
+
+**OnlyOffice cannot open docx files with single-quote XML declarations.** The file appears structurally valid (ZIP ok, XML parses fine, python-docx loads it, even x2t can convert it to PDF), but the OnlyOffice web editor refuses to open it.
+
+## Affected Files
+
+Only XML files that were **re-serialized by lxml** are affected. In a typical ContractEditor workflow:
+- `word/document.xml` — always re-serialized (main editing target)
+- `word/settings.xml` — re-serialized if trackRevisions was added/modified
+
+Other XML files (styles.xml, fontTable.xml, theme1.xml, etc.) that were read and written back unchanged via `zipfile` retain their original format.
+
+## Diagnosis
+
+```python
+import zipfile
+
+def check_docx_xml_format(docx_path):
+    """Check if any XML files have problematic single-quote declarations."""
+    issues = []
+    with zipfile.ZipFile(docx_path) as z:
+        for name in z.namelist():
+            if name.endswith('.xml') or name.endswith('.rels'):
+                data = z.read(name).decode('utf-8')
+                first_line = data.split('\n')[0]
+                has_single_quotes = "version='1.0'" in first_line
+                has_lf_only = '\r\n' not in data[:200]
+                if has_single_quotes or has_lf_only:
+                    issues.append((name, has_single_quotes, has_lf_only))
+    return issues
+```
+
+## Fix Script
+
+```python
+import zipfile
+import re
+import os
+import tempfile
+
+def fix_xml_declarations(docx_path, output_path=None):
+    """
+    Fix lxml-serialized XML files inside a docx:
+    1. Single quotes -> double quotes in XML declaration
+    2. LF -> CRLF line endings (only if file has no CRLF)
+    
+    If output_path is None, fixes in-place (via temp file + rename).
+    """
+    if output_path is None:
+        output_path = docx_path
+    
+    tmp_fd, tmp_path = tempfile.mkstemp(suffix='.docx')
+    os.close(tmp_fd)
+    
+    try:
+        with zipfile.ZipFile(docx_path, 'r') as zin:
+            with zipfile.ZipFile(tmp_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    data = zin.read(item.filename)
+                    
+                    if item.filename.endswith('.xml') or item.filename.endswith('.rels'):
+                        text = data.decode('utf-8')
+                        
+                        # Fix 1: Single quotes -> double quotes in XML declaration
+                        text = re.sub(
+                            r"<\?xml version='1\.0' encoding='UTF-8' standalone='yes'\?>",
+                            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
+                            text
+                        )
+                        
+                        # Fix 2: LF -> CRLF (only if no CRLF present)
+                        if '\r\n' not in text and '\n' in text:
+                            text = text.replace('\n', '\r\n')
+                        
+                        data = text.encode('utf-8')
+                    
+                    zout.writestr(item, data)
+        
+        os.replace(tmp_path, output_path)
+    except:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+# Usage after ContractEditor.save() or manual zipfile write:
+# fix_xml_declarations('/tmp/【修】contract.docx')
+```
+
+## Integration Points
+
+### After ContractEditor.save()
+```python
+ed = ContractEditor(src)
+# ... edits ...
+ed.save(output_path)
+fix_xml_declarations(output_path)  # Must run after every save
+```
+
+### After manual zipfile+lxml write
+```python
+with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+    for item in zin.infolist():
+        # ... write files ...
+        pass
+
+fix_xml_declarations(output_path)  # Must run after ZIP is closed
+```
+
+## Key Insight
+
+- `x2t` (OnlyOffice converter CLI) tolerates single-quote declarations — it can convert the "broken" file to PDF successfully
+- The **OnlyOffice web editor** (WOPI-based document editing) does NOT tolerate single-quote declarations
+- `python-docx Document()` opens the file fine (lxml parses both formats)
+- Standard validation tools (zipfile.testzip(), etree.fromstring()) all pass
+
+This makes the issue hard to diagnose — everything looks valid except OnlyOffice refuses to open it. The **only reliable test** is checking the raw bytes of the XML declaration in the ZIP.

skills/legal/contract-editor/references/manual-clause-renumbering.md

@@ -0,0 +1,66 @@
+# A类手动编号顺延 — 段落级 DEL/INS 模式
+
+实战来源：CT维保合同-香花桥（2026-06-26）。新增"9. 第三方侵权"条款后，需将原9→10、10→11、11→12、12→13、13→14 顺延。所有条款编号均为手动文本（A类，run内w:t文字，无numPr）。
+
+## 核心模式
+
+对每个需顺延的段落，找到包含旧编号的 run，用**段落级** DEL/INS 替换：
+
+```python
+for old_num, new_num in renumber_map.items():
+    for r in p.findall(f'{{{W}}}r'):
+        t = r.find(f'{{{W}}}t')
+        if t is None or t.text is None: continue
+        if t.text.strip().startswith(str(old_num)):
+            # 1. DEL run: 旧编号
+            del_run = deepcopy(r)
+            del_run.set(f'{{{W}}}rsidDel', rsid)
+            del_t = del_run.find(f'{{{W}}}t')
+            del_t.tag = f'{{{W}}}delText'
+            del_t.text = str(old_num)
+            
+            del_w = etree.Element(f'{{{W}}}del')
+            del_w.set(f'{{{W}}}id', str(nid)); nid += 1
+            del_w.set(f'{{{W}}}author', 'WB')
+            del_w.set(f'{{{W}}}date', rev_date)
+            del_w.append(del_run)
+            
+            # 2. INS run: 新编号
+            ins_run = deepcopy(r)
+            ins_run.set(f'{{{W}}}rsidR', rsid)
+            ins_t = ins_run.find(f'{{{W}}}t')
+            ins_t.text = str(new_num)
+            
+            ins_w = etree.Element(f'{{{W}}}ins')
+            ins_w.set(f'{{{W}}}id', str(nid)); nid += 1
+            ins_w.set(f'{{{W}}}author', 'WB')
+            ins_w.set(f'{{{W}}}date', rev_date)
+            ins_w.append(ins_run)
+            
+            # 3. 原 run 去掉编号前缀
+            t.text = t.text[len(str(old_num)):]
+            
+            # 4. DEL + INS 插入在原 run 之前
+            r.addprevious(ins_w)
+            r.addprevious(del_w)
+            break
+    break  # 每个段落只改一个编号
+```
+
+## 关键点
+
+1. **DEL/INS 在段落级**（`w:p` 的直接子元素），不是 run 内
+2. **从后往前处理**：如果用索引遍历，从后往前避免 offset 漂移
+3. **只匹配run开头**：`t.text.strip().startswith(str(old_num))` 确保只匹配编号前缀
+4. **原 run 保留剩余文本**：`t.text = t.text[len(str(old_num)):]` 去掉编号后保留标题文字
+5. **ID 递增**：每个 DEL/INS 用独立 id，从 `max_id + 1` 起
+
+## 与 add_clause 的区别
+
+- `add_clause` / `add_clause_before`：创建**全新段落**（整段 w:ins）
+- 本模式：修改**已有段落**的第一个 run 的编号，其余内容不动
+
+## 适用场景
+
+- 新增条款后，后续**手动编号**（A类）的条款需要顺延
+- 不适用于自动编号（B类）——自动编号由 number.xml 引擎处理，修改 run 内文字无效

skills/legal/contract-editor/references/manual-review-rules.md

@@ -0,0 +1,60 @@
+# 手动合同审查：具体修改规则（非角色约束）
+
+> Doro 2026-07-02 明确："我需要你遵守的是具体修改规则，不是角色。"
+> 这些规则不因"手动操作"还是"workflow执行"而有任何区别。
+
+## 十条硬规则
+
+1. **修订精准到字，不整段 del+ins**
+   - 改一个字只标记一个字的 del+ins
+   - 不允许为了方便把整句/整段删掉重写
+
+2. **INS run 字体/字号与原文同段落一致**
+   - 每个 INS run 的 rPr（sz/bold/rFonts）必须与同段落其他非INS run一致
+   - 签署页特别注意："甲方：""乙方："标签和名称可能原文字号不同，INS必须匹配标签字号
+
+3. **格式、大小与原文保持一致**
+   - 段落缩进（firstLine）、行距（spacing）、段落样式（pStyle）全部与原文同级段落一致
+   - 新增条款标题必须继承原文条款标题的样式
+
+4. **编号顺延要通读全文确认**
+   - 插入新条款后，后续条款编号必须顺延
+   - 必须通读全文确认编号链连续无跳号
+
+5. **不擅自填写合同空白内容**
+   - 空白的商业条款（金额、期限、数量、质量标准等）不动
+   - 空白 = 留给签约双方自行填写，不是让审查人补充
+
+6. **不做独立法律判断**
+   - 不在审查中做"这个条款合不合法"的独立判断
+   - 只按reviewer的issue清单执行修改
+
+7. **不站自己的立场改客户的商业安排**
+   - 客户已经做出的商业决策不否定
+   - 例：客户选择"反委托代发工资"，不能改成"乙方直接发"
+   - 只能在客户选择的框架内加保护条款
+
+8. **批注只写修改方案，不写理由**
+   - ❌ "建议修改为……，因为……"
+   - ✅ "建议修改为……"
+   - 不加【新增】【修改】等标签前缀
+
+9. **金额是商业条款不动**
+   - 无论金额看起来是否"合理"，绝对不改
+   - 金额矛盾也只批注提示，不做修改
+
+10. **原文批注/修订不动**
+    - 其他人（华诚-Z、法务、屠佳青等）的修订和批注保留原样
+    - 不删除、不修改、不合并他人的批注
+    - 除非Doro明确指示合并（如"华诚-Z的修订人改为WB"）
+
+## 核心原则
+
+**遵守的是规则本身，不是"我现在扮演什么角色"。** 不管是workflow的editor角色执行、还是Doro直接让我手动改合同，这十条规则完全一样，不打折扣。
+
+## 反面教材（2026-07-01）
+
+- 反委托代发工资协议：站自己立场否定客户的反委托安排（版本1直接取消反委托）→ 违反第7条
+- 填写空白的"质量保证期___个月" → 违反第5条
+- 批注写理由 → 违反第8条
+- 劳务派遣协议整段del+ins → 违反第1条

skills/legal/contract-editor/references/merge-layered-revisions-with-priority.md

@@ -0,0 +1,125 @@
+# Merge Layered Revisions with Priority (Accept Inner Author's Edits)
+
+## Scenario (2026-07-03 模特合作协议案)
+
+File has two layers of tracked changes:
+- **Layer 1 (WB)**: Original review modifications
+- **Layer 2 (华诚-Z)**: User edited on top of WB's tracked changes
+
+Result: 华诚-Z's `w:del` elements are **nested inside** WB's `w:ins` elements — meaning 华诚-Z deleted portions of what WB had inserted.
+
+User instruction: "以华诚-Z为准" (prioritize 华诚-Z), then unify all author names to WB.
+
+## Three-Step Algorithm
+
+### Step 1: Accept nested deletions (inner author wins)
+
+Find all `w:del[author=华诚-Z]` nested inside `w:ins[author=WB]` and remove them (= accept the deletion):
+
+```python
+def accept_nested_deletions(body, inner_author='华诚-Z', outer_author='WB'):
+    for ins_elem in body.findall(f'.//{W}ins'):
+        if ins_elem.get(f'{W}author') != outer_author:
+            continue
+        for del_elem in ins_elem.findall(f'.//{W}del'):
+            if del_elem.get(f'{W}author') == inner_author:
+                parent = del_elem.getparent()
+                parent.remove(del_elem)
+```
+
+### Step 2: Remove empty outer elements
+
+After accepting nested deletions, some WB ins elements may be empty (all their content was deleted by 华诚-Z):
+
+```python
+def remove_empty_ins(body):
+    for ins_elem in body.findall(f'.//{W}ins'):
+        has_text = False
+        for t in ins_elem.findall(f'.//{W}t'):
+            if t.text and t.text.strip():
+                has_text = True
+                break
+        if not has_text:
+            parent = ins_elem.getparent()
+            if parent is not None:
+                parent.remove(ins_elem)
+```
+
+### Step 3: Unify author names
+
+```python
+def rename_author(body, old_author, new_author):
+    count = 0
+    for elem in body.iter():
+        author = elem.get(f'{W}author')
+        if author == old_author:
+            elem.set(f'{W}author', new_author)
+            count += 1
+    return count
+```
+
+## Complete Flow
+
+```python
+from docx import Document
+from lxml import etree
+
+doc = Document('input.docx')
+body = doc.element.body
+
+# Step 1: Accept 华诚-Z deletions of WB content
+accept_nested_deletions(body, inner_author='华诚-Z', outer_author='WB')
+
+# Step 2: Clean up empty WB ins elements
+remove_empty_ins(body)
+
+# Step 3: Rename 华诚-Z → WB
+rename_author(body, '华诚-Z', 'WB')
+
+doc.save('output.docx')
+```
+
+## After Merge: Additional Modifications
+
+After merging, you can continue adding new WB tracked changes on the unified file (e.g., reverting specific clauses to template wording). Use standard tracked change creation:
+
+```python
+def make_del(text, rPr=None, author='WB', date='2026-07-03T06:00:00Z'):
+    d = etree.Element(f'{W}del')
+    d.set(f'{W}id', str(abs(hash(text)) % 100000))
+    d.set(f'{W}author', author)
+    d.set(f'{W}date', date)
+    r = etree.SubElement(d, f'{W}r')
+    if rPr is not None:
+        r.append(deepcopy(rPr))
+    dt = etree.SubElement(r, f'{W}delText')
+    dt.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+    dt.text = text
+    return d
+
+def make_ins(text, rPr=None, author='WB', date='2026-07-03T06:00:00Z'):
+    ins = etree.Element(f'{W}ins')
+    ins.set(f'{W}id', str(abs(hash(text + 'ins')) % 100000))
+    ins.set(f'{W}author', author)
+    ins.set(f'{W}date', date)
+    r = etree.SubElement(ins, f'{W}r')
+    if rPr is not None:
+        r.append(deepcopy(rPr))
+    t = etree.SubElement(r, f'{W}t')
+    t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+    t.text = text
+    return ins
+```
+
+## Verification
+
+After merge:
+- `set(elem.get(W+'author') for elem in body.iter() if elem.get(W+'author'))` should return `{'WB'}` only
+- Count ins/del elements to confirm reasonable numbers
+- Verify key clauses read correctly in "accepted" view
+
+## Key Distinction from `unify-author-wb.py`
+
+The `scripts/unify-author-wb.py` script **only renames authors** — it does NOT handle nested deletions. If 华诚-Z has `w:del` inside WB's `w:ins`, just running unify will rename the del to WB but **leave the deleted content still marked as deleted inside the insertion** — creating a confusing state where WB appears to both insert and delete the same text.
+
+**Always run the three-step algorithm** when inner author has modified outer author's tracked changes.

skills/legal/contract-editor/references/mixed-inherited-sz-fix.md

@@ -0,0 +1,118 @@
+# Mixed Inherited/Explicit Font Size Fix (Document-Wide)
+
+## Problem (2026-07-01 生育友好宣传阵地建设协议)
+
+Source document has **mixed font sizing** in body text:
+- Some runs have explicit `sz=24` (12pt) — e.g., section headings, specific clauses
+- Other runs have **no explicit sz** — inherit from Normal style (`sz=21` / 10.5pt)
+- WB INS runs mostly got `sz=24` correctly, but the mix of explicit + inherited in **original** runs creates visual inconsistency
+
+Doro complaint: "文字大小不一致，修改" — the rendered result shows mixed sizes.
+
+## Root Cause
+
+- `docDefaults` / Normal style = 10.5pt (sz=21)
+- Many body runs (P12+) have explicit sz=24 (from original author or conversion)
+- ~72 original runs have NO explicit sz → inherit 10.5pt → render smaller
+- OnlyOffice renders the mix faithfully → visible inconsistency
+
+## Diagnosis
+
+```python
+from docx import Document
+from collections import Counter
+
+doc = Document('file.docx')
+print(f'Normal style sz: {doc.styles["Normal"].font.size}')  # If 133350 EMU = 10.5pt
+
+sizes = Counter()
+for p in doc.paragraphs[BODY_START:BODY_END]:
+    for run in p.runs:
+        if run.text.strip():
+            sizes[run.font.size.pt if run.font.size else 'inherited'] += 1
+
+# If both 'inherited' and explicit size (e.g. 12.0) appear → mixed problem
+print(sizes.most_common())
+```
+
+## Fix Pattern (Full Body Range)
+
+Unlike the INS-only sweep, this fix targets ALL runs in the body text range:
+
+```python
+import zipfile, re
+from lxml import etree
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+# 1. Identify body range (skip title/preamble and signature)
+BODY_START = 12   # First body content paragraph index
+BODY_END = 56     # Last body paragraph (exclusive)
+TARGET_SZ = '24'  # From explicit runs in body (majority value)
+
+# 2. Fix ALL runs in body range
+for pidx in range(BODY_START, min(BODY_END, len(paras))):
+    p = paras[pidx]
+    
+    # Plain runs
+    for r in p.findall(f'{WNS}r'):
+        t_elem = r.find(f'{WNS}t')
+        if t_elem is None or not (t_elem.text or '').strip():
+            continue
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is None:
+            rpr = etree.SubElement(r, f'{WNS}rPr')
+            r.insert(0, rpr)
+        sz = rpr.find(f'{WNS}sz')
+        if sz is None:
+            sz = etree.SubElement(rpr, f'{WNS}sz')
+        sz.set(f'{WNS}val', TARGET_SZ)
+        szCs = rpr.find(f'{WNS}szCs')
+        if szCs is None:
+            szCs = etree.SubElement(rpr, f'{WNS}szCs')
+        szCs.set(f'{WNS}val', TARGET_SZ)
+    
+    # INS runs
+    for ins in p.findall(f'{WNS}ins'):
+        for r in ins.findall(f'{WNS}r'):
+            # same logic as above
+            ...
+    
+    # DEL runs (for visual consistency in markup view)
+    for d in p.findall(f'{WNS}del'):
+        for r in d.findall(f'{WNS}r'):
+            # same logic
+            ...
+```
+
+## Key Distinctions from INS-Only Fix
+
+| Aspect | INS-only sweep | Full body range fix |
+|--------|---------------|---------------------|
+| Scope | Only WB INS runs | ALL runs (plain + INS + DEL) |
+| Trigger | INS runs missing sz | Doro reports "文字大小不一致" |
+| Root cause | add_clause/tracked_replace gaps | Source document mixed inheritance |
+| Target sz | From neighboring runs | From majority explicit sz in body |
+
+## When to Apply
+
+- Doro says "文字大小不一致" on a delivered file
+- `wb-ins-font-verify.py` passes (INS runs OK) but rendered output still shows mixed sizes
+- Diagnostic shows body runs split between `inherited` and explicit sz
+
+## Important: Don't Change Preamble/Signature
+
+- Title/header (e.g., P0-P2): larger sz by design (22pt/sz=44) — don't touch
+- Party info (P3-P10): may use different sz — don't touch unless in body range
+- Signature area (P56+): often sz=21 (10.5pt) — don't touch
+- Only fix the **body text range** where sz should be uniform
+
+## Relationship to 格式保留铁律
+
+This fix does NOT violate "格式保留铁律" (don't change original formatting) because:
+- The original document's **intent** is uniform 12pt body text (evidenced by majority explicit sz=24)
+- The missing sz is a **formatting omission** (author forgot to set explicit sz on some runs)
+- The fix makes the document render as the original author intended
+- This is different from "changing 仿宋_GB2312 to 仿宋" (that changes the actual format choice)
+
+BUT: if the original document intentionally uses different sizes in body (e.g., smaller text for notes, larger for headings), don't blindly unify. Check the pattern first.

skills/legal/contract-editor/references/modify-tracked-change-author-text.md

@@ -0,0 +1,204 @@
+# 修改已有tracked changes的作者和文本内容
+
+## 场景
+- 合并用户在OnlyOffice中的修订（author如"华诚-Z"改为"WB"）
+- 修改INS元素中的文本内容（如更新法律措辞）
+- 修改批注作者（comments.xml中的w:comment author属性）
+
+## 技术实现
+
+### 修改tracked change作者
+```python
+from lxml import etree
+import zipfile
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+# 打开docx，修改document.xml
+z_in = zipfile.ZipFile('input.docx', 'r')
+z_out = zipfile.ZipFile('output.docx', 'w')
+
+# 复制非document.xml的文件
+for item in z_in.namelist():
+    if item != 'word/document.xml':
+        z_out.writestr(item, z_in.read(item))
+
+# 修改tracked change作者
+with z_in.open('word/document.xml') as f:
+    tree = etree.parse(f)
+root = tree.getroot()
+
+for elem in root.iter():
+    tag = etree.QName(elem.tag).localname
+    if tag in ('ins', 'del'):
+        old_author = elem.get(f'{WNS}author', '')
+        if old_author == '旧作者名':
+            elem.set(f'{WNS}author', 'WB')
+
+z_out.writestr('word/document.xml', etree.tostring(tree, encoding='UTF-8', xml_declaration=True, standalone=True))
+z_in.close()
+z_out.close()
+```
+
+### 修改INS文本内容
+```python
+from copy import deepcopy
+from datetime import datetime
+
+now = datetime.now().isoformat()
+
+# 定位特定段落中的INS元素
+body = root.find(f'{WNS}body')
+paras = body.findall(f'{WNS}p')
+target_para = paras[12]  # 按索引定位
+
+# 删除旧的INS元素（按作者筛选）
+for ins in list(target_para.findall(f'{WNS}ins')):
+    author = ins.get(f'{WNS}author', '')
+    if author == '目标作者':
+        target_para.remove(ins)
+
+# 添加新的INS元素
+new_ins = etree.SubElement(target_para, f'{WNS}ins')
+new_ins.set(f'{WNS}author', 'WB')
+new_ins.set(f'{WNS}date', now)
+new_r = etree.SubElement(new_ins, f'{WNS}r')
+
+# 从同段落的原文run复制格式
+orig_runs = target_para.findall(f'{WNS}r')
+if orig_runs:
+    orig_rpr = orig_runs[0].find(f'{WNS}rPr')
+    if orig_rpr is not None:
+        new_r.append(deepcopy(orig_rpr))
+
+new_t = etree.SubElement(new_r, f'{WNS}t')
+new_t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+new_t.text = '新的插入文本'
+```
+
+### 修改批注作者
+```python
+# 修改comments.xml中的作者
+if 'word/comments.xml' in z_in.namelist():
+    with z_in.open('word/comments.xml') as f:
+        ctree = etree.parse(f)
+    croot = ctree.getroot()
+    for c in croot.findall(f'{WNS}comment'):
+        if c.get(f'{WNS}author', '') == '旧作者名':
+            c.set(f'{WNS}author', 'WB')
+    z_out.writestr('word/comments.xml', etree.tostring(ctree, encoding='UTF-8', xml_declaration=True, standalone=True))
+```
+
+### 在已有WB INS元素内修改部分文本（2026-07-01 反委托代发工资协议）
+
+当段落文本全部是WB INS（无普通w:r），需要替换其中某一句时，**不能删除整个INS重建**（会丢失该INS中其他文本的修订标记）。正确手法：**trim原INS的w:t + addnext插入DEL/INS**。
+
+```python
+old_sentence = "退回派遣员工由乙方依法自行安置处理，与甲方无涉。"
+new_sentence = "派遣员工退回后由乙方依法负责安置处理。因乙方安置不当导致甲方被追究责任的，乙方应赔偿甲方因此遭受的全部损失。"
+
+for child in list(p):
+    tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+    if tag == 'ins' and child.get(f'{WNS}author') == 'WB':
+        for r in child.findall(f'{WNS}r'):
+            for t in r.findall(f'{WNS}t'):
+                if t.text and old_sentence in t.text:
+                    rpr_copy = copy.deepcopy(r.find(f'{WNS}rPr')) if r.find(f'{WNS}rPr') is not None else None
+                    
+                    # 1. Trim原INS文本（去掉被替换的句子）
+                    t.text = t.text.replace(old_sentence, "")
+                    
+                    # 2. 创建DEL
+                    del_elem = etree.Element(f'{WNS}del')
+                    del_elem.set(f'{WNS}id', next_id())
+                    del_elem.set(f'{WNS}author', 'WB')
+                    del_elem.set(f'{WNS}date', rev_date)
+                    del_r = etree.SubElement(del_elem, f'{WNS}r')
+                    if rpr_copy: del_r.insert(0, copy.deepcopy(rpr_copy))
+                    del_r.set(f'{WNS}rsidDel', rsid)
+                    del_t = etree.SubElement(del_r, f'{WNS}delText')
+                    del_t.set(XML_SPACE, 'preserve')
+                    del_t.text = old_sentence
+                    
+                    # 3. 创建INS
+                    ins_elem = etree.Element(f'{WNS}ins')
+                    ins_elem.set(f'{WNS}id', next_id())
+                    ins_elem.set(f'{WNS}author', 'WB')
+                    ins_elem.set(f'{WNS}date', rev_date)
+                    ins_r = etree.SubElement(ins_elem, f'{WNS}r')
+                    if rpr_copy: ins_r.insert(0, copy.deepcopy(rpr_copy))
+                    ins_r.set(f'{WNS}rsidR', rsid)
+                    ins_t = etree.SubElement(ins_r, f'{WNS}t')
+                    ins_t.set(XML_SPACE, 'preserve')
+                    ins_t.text = new_sentence
+                    
+                    # 4. 插入到原INS之后（addnext保证顺序）
+                    child.addnext(ins_elem)   # 后插的在后面
+                    child.addnext(del_elem)   # 后插的在前面 → 最终: [原INS] [DEL] [INS]
+```
+
+**关键点**：
+- `addnext` 两次：先插INS再插DEL，后插的排前面，最终顺序：`[原INS(trimmed)] [DEL旧句] [INS新句]`
+- 绝不能 `p.remove(child)` 再重建——会丢失INS中其他未改动的文本
+- rPr必须从原INS的run深拷贝，不要从全文body_rpr取（字号可能不同）
+
+### 给全INS段落补充条款编号（2026-07-01）
+
+段落所有文本都是WB INS时，编号INS插到pPr之后：
+
+```python
+ins_num = etree.Element(f'{WNS}ins')
+ins_num.set(f'{WNS}id', next_id()); ins_num.set(f'{WNS}author', 'WB'); ins_num.set(f'{WNS}date', rev_date)
+ins_r = etree.SubElement(ins_num, f'{WNS}r')
+ins_r.insert(0, copy.deepcopy(existing_rpr))  # 从同段落INS run深拷贝
+ins_r.set(f'{WNS}rsidR', rsid)
+ins_t = etree.SubElement(ins_r, f'{WNS}t')
+ins_t.set(XML_SPACE, 'preserve'); ins_t.text = "第X条  "
+
+ppr = p.find(f'{WNS}pPr')
+if ppr is not None: ppr.addnext(ins_num)
+else: p.insert(0, ins_num)
+```
+
+### 新INS元素eastAsia字体显式补齐
+
+原文WB INS run可能**没有显式eastAsia属性**（靠docDefaults回退），但新INS run**必须显式设置eastAsia=宋体**，否则修订上下文中可能丢失回退。post-save sweep：
+
+```python
+for p in body.findall(f'{WNS}p'):
+    for ins in p.findall(f'{WNS}ins'):
+        for r in ins.findall(f'{WNS}r'):
+            text = ''.join(t.text for t in r.findall(f'{WNS}t') if t.text)
+            if not any('\u4e00' <= c <= '\u9fff' for c in text): continue
+            rpr = r.find(f'{WNS}rPr')
+            if rpr is None:
+                rpr = etree.Element(f'{WNS}rPr'); r.insert(0, rpr)
+            rf = rpr.find(f'{WNS}rFonts')
+            if rf is None: rf = etree.SubElement(rpr, f'{WNS}rFonts')
+            if not rf.get(f'{WNS}eastAsia'): rf.set(f'{WNS}eastAsia', '宋体')
+            if not rf.get(f'{WNS}ascii'): rf.set(f'{WNS}ascii', '宋体')
+```
+
+## 验证方法
+```python
+# 验证所有作者已更改
+content = z_out.read('word/document.xml').decode('utf-8', 'ignore')
+authors = set(re.findall(r'w:author="([^"]+)"', content))
+assert '旧作者名' not in authors, f"仍有旧作者: {authors}"
+
+# 验证批注作者
+if 'word/comments.xml' in z_out.namelist():
+    with z_out.open('word/comments.xml') as f:
+        ctree = etree.parse(f)
+    for c in ctree.getroot().findall(f'{WNS}comment'):
+        assert c.get(f'{WNS}author') != '旧作者名'
+```
+
+## ⚠️ 铁律
+1. **修改前必须备份原文件**：覆盖含第三方修订的文件 = 不可逆丢失
+2. **只改作者名，不改文本**：除非明确要求修改INS内容
+3. **zipfile不能原地读写**：必须先读后写临时文件，再用os.replace
+4. **保留comments.xml中的批注锚点**：只改author属性，不改id/content/anchor
+
+## 实证（2026-07-01 反委托代发工资协议）
+华诚-Z在OnlyOffice中做了3处修订（第六条去法条引用、第七条简化纠正流程、第八条加退回员工安置）。后续制作版本时覆盖了所有中间文件，导致华诚-Z修订痕迹丢失。最终通过系统化文件扫描在/tmp/v1_doro_updated.docx中找到仍含华诚-Z作者的文件，提取修订内容后在最终版本中恢复。

skills/legal/contract-editor/references/multi-version-comparison-table.md

@@ -0,0 +1,93 @@
+# Multi-Version Contract Comparison Table (三版对比表)
+
+## When to Use
+When Maggie/Doro asks to compare multiple versions of a contract (typically: template / counterparty revision / our revision), produce a structured docx comparison table.
+
+## Pattern (2026-07-03 模特合作协议 session)
+
+### Document Setup
+- **Landscape orientation** for 4-5 columns: `section.orientation = 1; page_width=Cm(29.7); page_height=Cm(21.0)`
+- Narrow margins: 1.2-1.5cm all sides
+- Font size 8.5-9pt for table cells (fits more content)
+
+### Table Structure
+| 条款 | 【模版】 | 版本A（对方修订） | 版本B（我方修订） | 双方协商一致 |
+|------|---------|------------------|-----------------|-------------|
+
+### Red Font for Differences
+- Column N is red when its content differs from other versions
+- Use `RGBColor(0xFF, 0x00, 0x00)` on the run
+- "协商一致" column: red = current text doesn't match consensus → needs modification
+
+### Yellow Background for Consensus Column
+```python
+def set_cell_shading(cell, color):
+    tc = cell._element
+    tcPr = tc.find(qn('w:tcPr'))
+    if tcPr is None:
+        tcPr = OxmlElement('w:tcPr')
+        tc.insert(0, tcPr)
+    shading = OxmlElement('w:shd')
+    shading.set(qn('w:fill'), color)  # e.g. 'FFF8E1' for light yellow
+    shading.set(qn('w:val'), 'clear')
+    tcPr.append(shading)
+```
+
+### Header Row Styling
+- Blue background (`D9E2F3`)
+- Bold, centered, font size 8.5pt
+
+### Data Structure in Code
+```python
+# Each row: (clause_name, col1_text, col2_text, col3_text, col4_text, col2_red, col3_red, col4_red)
+rows = [
+    ('条款名',
+     '模版内容',
+     '对方修订内容',
+     '我方修订内容', 
+     '协商一致内容',
+     True,   # col2 red? (differs from others)
+     False,  # col3 red?
+     True),  # col4 red? (doesn't match consensus)
+]
+```
+
+### Legend at Bottom
+Include a legend explaining what red means in each column:
+- 版本A列红色 = 与模版/我方版不一致（对方的修改）
+- 版本B列红色 = 与模版不一致（我方的修改）
+- 协商一致列红色 = 当前文本与协商一致不符，需要修改
+
+## Key Lessons
+1. **Read all three files from Nextcloud** using `sudo find ~/nextcloud/data/data/...` path
+2. **Extract paragraph text** using python-docx: `[(i, p.text.strip()) for i, p in enumerate(doc.paragraphs) if p.text.strip()]`
+3. **Check tables** separately: `doc.tables` — contracts often have signature blocks and SNS account tables
+4. **Align comparison by clause semantics**, not paragraph index — different versions may have different paragraph counts
+5. Also upload to Nextcloud for viewing in OnlyOffice
+
+## Per-Run Precision for Tracked Changes (Maggie's correction)
+
+When applying tracked changes based on comparison results, **never replace entire paragraphs**. Instead:
+
+1. Identify the specific runs containing text to change
+2. For each run: create w:del wrapping a deepcopy (converting w:t → w:delText), create w:ins with new text and cloned rPr, swap in place
+3. All surrounding runs remain untouched
+
+```python
+# Find specific run by text content
+for r in para_element.findall(qn('w:r')):
+    text = ''.join(t.text or '' for t in r.findall(qn('w:t')))
+    if text == '¥700,000':  # exact match on this run
+        r_parent = r.getparent()
+        r_idx = list(r_parent).index(r)
+        # Create del wrapping copy of this run
+        del_elem = make_del_run_from_existing(r)
+        # Create ins with new value, same rPr
+        ins_elem = make_ins_run('¥600,000', r.find(qn('w:rPr')))
+        r_parent.remove(r)
+        r_parent.insert(r_idx, ins_elem)
+        r_parent.insert(r_idx, del_elem)
+        break
+```
+
+This produces clean tracked changes where Word/OnlyOffice shows exactly which characters changed (e.g., ~~700,000~~ → 600,000) rather than entire-paragraph replacements.

skills/legal/contract-editor/references/multi-version-creation-pattern.md

@@ -0,0 +1,232 @@
+# Multi-Version Creation Pattern
+
+## When to Use
+When creating multiple versions of the same contract (e.g., 版本1法定安排 vs 版本2反委托保护) or when needing to redo a version from scratch.
+
+## Critical Rule
+**ALWAYS start from the original source file for each version. Never modify a previously modified version.**
+
+## Step-by-Step Pattern
+
+### 1. Preserve Original Source
+```python
+# First time: copy original to safe location
+shutil.copy('/path/to/original.docx', '/tmp/original_backup.docx')
+```
+
+### 2. For Each Version, Start Fresh
+```python
+# Always reload from original
+with zipfile.ZipFile('/tmp/original_backup.docx', 'r') as zin:
+    all_data = {n: zin.read(n) for n in zin.namelist()}
+
+doc_xml = all_data['word/document.xml']
+root = etree.fromstring(doc_xml)
+body = root.find(f'{W}body')
+paras = body.findall(f'{W}p')
+
+# Get font template from original
+rpr_template = None
+for p in paras:
+    for r in p.findall(f'{W}r'):
+        t = r.find(f'{W}t')
+        if t is not None and t.text and t.text.strip():
+            rpr_elem = r.find(f'{W}rPr')
+            if rpr_elem is not None:
+                rpr_template = copy.deepcopy(rpr_elem)
+                break
+    if rpr_template:
+        break
+```
+
+### 3. Apply All Modifications in One Pass
+```python
+rev_id = 1000  # Start fresh revision ID counter
+
+# Batch all replacements
+replacements = [
+    (0, "old text", "new text"),
+    (5, "old text", "new text"),
+    # ... more replacements
+]
+
+for idx, old_text, new_text in replacements:
+    p = paras[idx]
+    # Clear runs (but NOT comment anchors!)
+    for child in list(p):
+        tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+        if tag == 'r':  # Only remove regular runs
+            p.remove(child)
+    d, i = make_tracked_replace(old_text, new_text, rpr_template, rev_id)
+    rev_id += 2
+    p.append(d)
+    p.append(i)
+
+# Insert new clauses
+insert_after = paras[10]
+for clause_text in new_clauses:
+    new_p = make_ins_paragraph(clause_text, rpr_template, rev_id)
+    rev_id += 1
+    insert_after.addnext(new_p)
+    insert_after = new_p
+
+# Mark deletions (e.g., 承诺书)
+for idx in range(21, 30):
+    p = paras[idx]
+    text_parts = []
+    for r in p.findall(f'{W}r'):
+        t = r.find(f'{W}t')
+        if t is not None and t.text:
+            text_parts.append(t.text)
+    full_text = ''.join(text_parts)
+    if not full_text.strip():
+        continue
+    for child in list(p):
+        tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+        if tag == 'r':
+            p.remove(child)
+    del_elem = make_tracked_delete(full_text, rpr_template, rev_id)
+    rev_id += 1
+    p.append(del_elem)
+
+# Add comments LAST (after all structural changes)
+# Comment anchors are fragile - add them at the end
+```
+
+### 4. Add Comments Carefully
+```python
+# Check if paragraph already has comment anchors
+existing = p.find(f'{W}commentRangeStart')
+if existing is None:
+    # Add new comment anchors
+    comment_start = etree.Element(f'{W}commentRangeStart')
+    comment_start.set(f'{W}id', str(comment_id))
+    p.insert(0, comment_start)
+    
+    comment_end = etree.Element(f'{W}commentRangeEnd')
+    comment_end.set(f'{W}id', str(comment_id))
+    p.append(comment_end)
+    
+    comment_ref_run = etree.SubElement(p, f'{W}r')
+    comment_ref = etree.SubElement(comment_ref_run, f'{W}commentReference')
+    comment_ref.set(f'{W}id', str(comment_id))
+
+# Update comments.xml
+if 'word/comments.xml' in all_data:
+    croot = etree.fromstring(all_data['word/comments.xml'])
+else:
+    croot = etree.Element(f'{W}comments', nsmap={'w': W_NS})
+
+# Add or update comment
+new_comment = etree.SubElement(croot, f'{W}comment')
+new_comment.set(f'{W}id', str(comment_id))
+new_comment.set(f'{W}author', author)
+new_comment.set(f'{W}date', datetime.now().isoformat())
+
+p = etree.SubElement(new_comment, f'{W}p')
+r = etree.SubElement(p, f'{W}r')
+t = etree.SubElement(r, f'{W}t')
+t.set(XML_SPACE, 'preserve')
+t.text = comment_text
+```
+
+### 5. Save and Verify
+```python
+all_data['word/document.xml'] = etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True)
+all_data['word/comments.xml'] = etree.tostring(croot, xml_declaration=True, encoding='UTF-8', standalone=True)
+
+with zipfile.ZipFile('/tmp/version1.docx', 'w', zipfile.ZIP_DEFLATED) as zout:
+    for name, data in all_data.items():
+        zout.writestr(name, data)
+
+# Verify immediately
+doc = Document('/tmp/version1.docx')
+print(f"OK: {len(doc.paragraphs)} paragraphs")
+```
+
+## Common Pitfalls
+
+### ❌ Don't Do This
+```python
+# WRONG: Modifying v1 to create v2
+shutil.copy('/tmp/v1.docx', '/tmp/v2.docx')
+with zipfile.ZipFile('/tmp/v2.docx', 'r') as zin:
+    # ... load v1's modified structure
+    # This will have v1's tracked changes, comments, etc.
+```
+
+### ❌ Don't Clear Everything When Modifying
+```python
+# WRONG: Clears comment anchors too!
+for child in list(p):
+    if child.tag not in (f'{W}pPr',):
+        p.remove(child)  # Removes commentRangeStart/End!
+```
+
+### ✅ Do This Instead
+```python
+# RIGHT: Only clear regular runs, preserve comment anchors
+for child in list(p):
+    tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+    if tag == 'r':  # Only regular runs
+        p.remove(child)
+    # commentRangeStart, commentRangeEnd are preserved
+```
+
+## Preserving Original Comments
+When the original document has comments (e.g., Alice, 法务, 杜律), the workflow must:
+1. Read original comments.xml to get all comment IDs and content
+2. Check which paragraphs have comment anchors (commentRangeStart/End)
+3. When clearing runs, preserve comment anchors (they're not `w:r` elements)
+4. Add new comments with NEW IDs (don't reuse original IDs)
+5. Original comments remain unchanged in comments.xml
+
+## Preserving Third-Party Tracked Changes (2026-07-01 华诚-Z案)
+
+When a contract file contains tracked changes from someone other than WB (e.g., 华诚-Z, Crystall, or any third-party reviewer), **those files must never be overwritten**. The tracked changes represent real editorial work that cannot be reconstructed from session notes alone.
+
+### Backup Protocol
+```python
+import shutil
+from datetime import datetime
+
+# BEFORE any modification to a file with third-party tracked changes:
+ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+backup_path = f'/tmp/{filename}.bak_{ts}'
+shutil.copy(source_path, backup_path)
+print(f"Backed up to {backup_path}")
+```
+
+### Detection: Does This File Have Third-Party Changes?
+```python
+import zipfile, re
+with zipfile.ZipFile(filepath) as z:
+    content = z.read('word/document.xml').decode('utf-8', errors='ignore')
+    authors = set(re.findall(r'w:author="([^"]+)"', content))
+    third_party = authors - {'WB'}
+    if third_party:
+        print(f"⚠️ Third-party authors found: {third_party} — BACKUP REQUIRED")
+```
+
+### Multi-Version with Third-Party Edits
+When creating v1 and v2 from a file that has both original content AND third-party edits:
+
+1. **Backup the file with third-party edits** (e.g., `华诚-Z版.bak_20260701`)
+2. **Backup the pristine original** (no tracked changes at all)
+3. **For each version**: start from the pristine original, then layer on:
+   - WB's own tracked changes
+   - Third-party's tracked changes (with author renamed to WB)
+4. **Never modify the backup files** — they are your insurance
+
+### What Was Lost (华诚-Z案)
+- 华诚-Z made 3 tracked changes in OnlyOffice: 第六条 (removed specific legal citations), 第七条 (simplified correction process), 第八条 (added employee return placement clause)
+- These intermediate files in /tmp/ were overwritten during v1/v2 creation
+- Only session notes preserved the *content* of changes, not the actual tracked change markup (ids, timestamps, exact XML positions)
+- **Recovery was impossible** — Doro had to accept reconstructed versions
+
+## Real Example from This Session
+- Original: 4 comments (Alice×2, 法务, 杜律)
+- Version 1: 5 comments (original 4 + WB legal risk)
+- Version 2: 5 comments (original 4 + WB legal risk)
+
+Both versions created independently from original, each with their own WB comment (different content for each version).

skills/legal/contract-editor/references/new-clause-ppr-complete-clone.md

@@ -0,0 +1,34 @@
+# 新增条款pPr完整克隆铁律（2026-07-13 盈浦健康科普合同教训）
+
+## 问题
+
+新增条款（如"八、转包与分包"的正文P75）插入后，只考虑了numPr是否正确，但遗漏了其他pPr子元素（如`ind`首行缩进）。导致新增段落与原文同类段落格式不一致。
+
+## 教训链（同一份合同被Doro纠正3次）
+
+1. **第一次**：P75挂了错误的numId=11（不可抗力的序列）→ 渲染为"3."
+2. **第二次**：去掉numId后，加了新的numId=14 → 单段正文不该有编号（"有2才有1"规则延伸到numPr）
+3. **第三次**：去掉numId后仍缺首行缩进ind=420 → 与原文"一、合作背景"（同为单段无编号正文）格式不一致
+
+## 铁律：新增段落pPr必须完整比对原文参照段
+
+动手前必须：
+1. **找到原文中的参照段落**——格式相同的段落（同层级、同类型）
+2. **逐子元素列出参照段的pPr**：spacing、ind、numPr、jc、每一个子元素
+3. **逐一对比新增段落的pPr**：缺什么补什么，多什么删什么
+4. 不能只看一个属性（如numPr）就认为"格式正确了"
+
+## "有2才有1"规则在numPr上的延伸
+
+原规则：新增条款如果下一级只有一条内容，不加子编号。
+
+延伸到numPr：如果某章节下只有一个正文段落，且原文中同类单段正文没有numPr（如"一、合作背景"的P12无numPr），则新增的单段正文也不加numPr。
+
+判断方法：看原文中有没有"章节标题+单段正文+无numPr"的先例。有→新增单段也不加。
+
+## 检查清单（操作后必过）
+
+- [ ] 新增段落的spacing与参照段一致
+- [ ] 新增段落的ind与参照段一致（特别是firstLine/firstLineChars）
+- [ ] 新增段落的numPr：单段→不加（参照原文同类）；多段→加入对应序列
+- [ ] 新增段落INS run的rPr与参照段原文run的rPr一致（无多余sz、无缺失属性）

skills/legal/contract-editor/references/numpr-strip-when-adding-manual-numbering.md

@@ -0,0 +1,147 @@
+# Strip numPr When Adding Manual Numbering to Auto-Numbered Paragraphs
+
+## Problem (2026-07-01 反委托代发工资协议)
+
+Original contract paragraphs have `<w:numPr>` with actual auto-numbering (e.g., `numId=3 → abstractNum decimal "%1." start=1`). When you insert manual "第X条" numbering as `w:ins` at paragraph start, OnlyOffice renders BOTH:
+
+```
+1. 第一条  乙方应严格按照...   ← "1." is auto-numbering, "第一条" is your INS
+```
+
+This looks broken — two different numbering systems stacked.
+
+## Root Cause
+
+The paragraph's `pPr/numPr` tells the rendering engine to prepend an automatic decimal number. Your INS adds a second, manual number. They coexist independently.
+
+Additionally, if the paragraph has `pPr/pPrChange` (tracking the old paragraph formatting), the old `numPr` inside `pPrChange` can ALSO render in markup view.
+
+## Fix (two-step)
+
+After inserting manual numbering INS elements, strip auto-numbering from ALL affected paragraphs:
+
+```python
+for idx in target_paragraph_indices:
+    p = paras[idx]
+    ppr = p.find(f'{WNS}pPr')
+    if ppr is not None:
+        # Step 1: Remove direct numPr
+        num_pr = ppr.find(f'{WNS}numPr')
+        if num_pr is not None:
+            ppr.remove(num_pr)
+        
+        # Step 2: Remove numPr inside pPrChange (old formatting record)
+        ppr_change = ppr.find(f'{WNS}pPrChange')
+        if ppr_change is not None:
+            inner_ppr = ppr_change.find(f'{WNS}pPr')
+            if inner_ppr is not None:
+                inner_num = inner_ppr.find(f'{WNS}numPr')
+                if inner_num is not None:
+                    inner_ppr.remove(inner_num)
+```
+
+## When This Applies
+
+- You're converting a contract from auto-numbered clauses to manual "第X条" heading-style numbering
+- The original .doc/.docx used Word's list numbering for clause structure
+- You're adding "第一条  " etc. as INS at paragraph start
+
+## Verification
+
+After fix:
+1. `pdftotext -layout` of OnlyOffice render should show NO stray "1." / "2." / "3." before your "第X条"
+2. Accept-revisions preview should also be clean (no residual auto-numbers)
+
+## Scenario B: Auto-Numbering Resets Across Tracked-Deleted Paragraphs (2026-07-01 反委托代发工资协议)
+
+### Problem
+
+When paragraphs with `numPr` auto-numbering are interspersed with **entirely deleted paragraphs** (all content in `w:del`), OnlyOffice's auto-number counter **resets to 1** after the deleted block. This makes continuous numbering impossible with `numPr` alone.
+
+Example structure:
+```
+P6:  numPr=1  INS content (clause 1) → renders "1."
+P7:  numPr=1  continuation            → renders "2." (wrong if P7 shouldn't be numbered)
+P8:  numPr=1  ALL w:del               → renders "3." with strikethrough
+P9:  numPr=1  ALL w:del               → renders "4." with strikethrough
+P10: numPr=1  INS content (clause 2)  → renders "1." ← RESETS! Should be "2."
+```
+
+The auto-numbering engine counts visible (non-deleted) items in the `numId` sequence, but deleted paragraphs **break the continuity** in OnlyOffice's rendering.
+
+### Solution: Convert to Manual Text Numbering
+
+Strip `numPr` from ALL paragraphs and insert "N. " as `w:ins` text at paragraph start. This gives identical visual output ("1. 2. 3. ...") without depending on the broken auto-number counter.
+
+```python
+# Step 1: Strip ALL numPr (including inside pPrChange)
+for i, p in enumerate(paragraphs):
+    pPr = p.find(f'{{{W}}}pPr')
+    if pPr is not None:
+        numPr = pPr.find(f'{{{W}}}numPr')
+        if numPr is not None:
+            pPr.remove(numPr)
+        for pPrChange in pPr.findall(f'{{{W}}}pPrChange'):
+            old_pPr = pPrChange.find(f'{{{W}}}pPr')
+            if old_pPr is not None:
+                old_numPr = old_pPr.find(f'{{{W}}}numPr')
+                if old_numPr is not None:
+                    old_pPr.remove(old_numPr)
+
+# Step 2: Insert "N. " as w:ins text for each clause paragraph
+# Only number paragraphs that have VISIBLE content (not entirely w:del)
+clause_map = {6: 1, 10: 2, 11: 3, ...}  # para_index: clause_number
+
+for para_idx, clause_num in clause_map.items():
+    p = paragraphs[para_idx]
+    # Build INS element with "N. " text
+    ins_elem = ET.Element(f'{{{W}}}ins')
+    ins_elem.set(f'{{{W}}}id', str(next_rev_id()))
+    ins_elem.set(f'{{{W}}}author', rev_author)  # from existing INS in doc
+    ins_elem.set(f'{{{W}}}date', rev_date)
+    
+    r_elem = ET.SubElement(ins_elem, f'{{{W}}}r')
+    # Clone rPr from existing runs for font consistency
+    rPr = get_run_rPr_from_paragraph(p)
+    if rPr is not None:
+        r_elem.append(copy.deepcopy(rPr))
+    
+    t_elem = ET.SubElement(r_elem, f'{{{W}}}t')
+    t_elem.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+    t_elem.text = f"{clause_num}. "
+    
+    # Insert after pPr
+    pPr = p.find(f'{{{W}}}pPr')
+    if pPr is not None:
+        p.insert(list(p).index(pPr) + 1, ins_elem)
+    else:
+        p.insert(0, ins_elem)
+```
+
+### When to Use This (vs Scenario A)
+
+- **Scenario A** (above): You're CHANGING the numbering scheme (auto "1." → manual "第一条")
+- **Scenario B** (this): You're KEEPING the same format ("1. 2. 3.") but converting from auto to manual because auto-numbering resets across w:del paragraphs
+- **Trigger**: Original uses numPr auto-numbering + your edits create entirely-deleted paragraphs between numbered items → auto counter resets → switch to manual text
+
+### Key Decision: Which Paragraphs to Number
+
+Only number paragraphs that will be visible after accepting revisions:
+- Paragraphs with ONLY `w:del` content → skip (they're deleted)
+- Paragraphs that are continuations of the previous clause (no independent number) → skip
+- New INS-only paragraphs (new clauses) → number them
+- Rewritten paragraphs (mixed INS+DEL, first clause in sequence) → number them
+
+### Verification
+
+After conversion:
+1. OnlyOffice render (x2t → PDF) should show continuous "1. 2. 3. ... 11." without resets
+2. No stray auto-numbers from numPr remnants
+3. Deleted paragraphs (entirely w:del) should NOT show any number
+
+## Distinction from Existing Rules
+
+- Rule 5 (A類 vs B類) talks about NEW clauses inheriting/stripping numPr
+- Scenario A is EXISTING paragraphs where you're REPLACING their numbering scheme with a different format via INS
+- Scenario B is EXISTING paragraphs where auto-numbering BREAKS due to tracked-deleted paragraphs, requiring conversion to same-format manual text
+- numId=0 trap (Rule 5 sub-note) is about fake auto-numbering; BOTH scenarios here are about REAL auto-numbering that renders visible numbers

skills/legal/contract-editor/references/one-page-docx-compression.md

@@ -0,0 +1,54 @@
+# 一页纸 docx 排版压缩配方
+
+适用场景：创建必须严格一页的 Word 文档（合作框架、报价单、一页摘要等），通过 OnlyOffice x2t 渲染验证。
+
+## 迭代压缩流程
+
+x2t 渲染的行高/间距比 python-docx 估算的略宽松，不能靠"调好参数直接交付"。必须走渲染验证循环。
+
+### 第一轮：合理起点
+| 参数 | 值 |
+|---|---|
+| 上下边距 | 1.5–2.0 cm |
+| 左右边距 | 1.8–2.0 cm |
+| 正文字号 | 9–10 pt |
+| 表格字号 | 8–9 pt |
+| 行距 | 1.05–1.15 |
+
+### 验证循环
+```bash
+bash ~/.hermes/skills/legal/contract-editor/scripts/onlyoffice-render.sh <docx> <pdf>
+python3 -c "
+import subprocess
+r=subprocess.run(['pdftotext','<pdf>','-'],capture_output=True,text=True)
+pages=r.stdout.split('\f')
+print(f'页数: {len(pages)}')
+"
+```
+- 页数=1 → 交付
+- 页数=2 且末页空白 → 内容刚好溢出，微调即可
+- 页数=2 且有内容 → 需要大幅压缩或精简文字
+
+### 逐级压缩（按优先级）
+1. 底部边距：1.5→1.0→0.8→0.5 cm（先砍底部，顶部保阅读感）
+2. 表格字号：8→7.5→7 pt
+3. 行距：1.05→1.0
+4. 左右边距：1.8→1.5 cm
+5. 段落间距：Pt(2)→Pt(1)→Pt(0)
+6. 精简文字（最后手段）
+
+### 已实证的可用参数（5000字内一页A4）
+| 参数 | 值 |
+|---|---|
+| 上下边距 | 1.2 / 0.5 cm |
+| 左右边距 | 1.5 cm |
+| 正文字号 | 8 pt |
+| 表格字号 | 7 pt |
+| 行距 | 1.0 |
+| 段落间距 | 0 |
+
+## 陷阱
+- x2t 对表格行高估算偏大，表内文字多时尤其明显
+- 分隔线（`—`*N）占用空间，一页紧张时去掉
+- 表格 `Table Grid` 样式自带内边距，无法通过 python-docx 参数完全消除
+- 第二页空白但无文字 = 内容刚好溢出几像素，再砍 0.2cm 底部边距或减 0.5pt 字号即可

skills/legal/contract-editor/references/operation-ordering-renumber.md

@@ -0,0 +1,40 @@
+# ContractEditor Operation Ordering: Add Clauses Before Renumbering
+
+## 2026-07-13 练塘硬件购销合同教训
+
+### Problem
+When interleaving `add_clause_before()` and `tracked_replace()` for renumbering, lxml throws:
+```
+ValueError: Element is not a child of this node.
+```
+in `tracked_replace()` → `parent.remove(runs[idx])`.
+
+### Root Cause
+`add_clause_before()` / `add_clause()` mutate the XML tree (insert new `<w:p>` elements). After insertion, previously-found element references held by later `tracked_replace()` calls may point to nodes whose parent relationship has shifted. The `parent.remove()` call inside `tracked_replace` fails because the run's parent `<w:p>` is no longer the same object the code expects.
+
+### Fix: Two-Phase Approach (铁律)
+
+**Phase 1 — All structural additions:**
+- `add_clause()` / `add_clause_before()` for new clauses
+- Content-level `tracked_replace()` that don't touch clause titles being renumbered
+
+**Phase 2 — Renumbering (after all additions are done):**
+- `tracked_replace('第七条不可抗力', '第九条不可抗力')` etc.
+
+### Example (correct order)
+```python
+# Phase 1: add new clauses
+editor.add_clause_before('第七条 转包与分包\n...', before_search='第七条不可抗力')
+editor.add_clause_before('第八条 第三方侵权\n...', before_search='第七条不可抗力')
+
+# Phase 2: renumber old clauses (all additions done)
+editor.tracked_replace('第七条不可抗力', '第九条不可抗力')
+editor.tracked_replace('第八条争议解决', '第十条争议解决')
+```
+
+### WPS/DOC File Handling
+WPS `.wps` and `.doc` files must be converted to `.docx` before ContractEditor can process them:
+```bash
+libreoffice --headless --convert-to docx input.wps --outdir /tmp/contract-review/
+```
+Then copy to a simple ASCII filename to avoid python-docx path issues with Chinese characters.

skills/legal/contract-editor/references/paragraph-deletion.md

@@ -0,0 +1,60 @@
+# Paragraph Deletion via Tracked Changes (WB)
+
+When a reviewer instructs you to delete an entire clause/paragraph, use **paragraph-level deletion** — not just deleting the text but marking the entire paragraph as removed in tracked changes.
+
+## Two-Part Deletion
+
+### Part 1: Paragraph Mark Deletion
+
+Add a `w:del` element inside the paragraph's `w:pPr/w:rPr`:
+
+```xml
+<w:pPr>
+  <w:rPr>
+    <w:del w:id="7777" w:author="WB" w:date="2026-06-26T00:00:00Z"/>
+  </w:rPr>
+</w:pPr>
+```
+
+This marks the paragraph marker (¶) as deleted, so the paragraph doesn't leave an empty line.
+
+### Part 2: Content Deletion
+
+Wrap every text run in the paragraph inside `w:del` elements, converting `w:t` to `w:delText`:
+
+```python
+for child in list(paragraph):
+    tag = child.tag.split('}')[-1]
+    if tag in ('r', 'ins'):
+        paragraph.remove(child)
+        del_elem = etree.SubElement(paragraph, f'{{{W}}}del')
+        del_elem.set(f'{{{W}}}id', '7777')
+        del_elem.set(f'{{{W}}}author', 'WB')
+        del_elem.set(f'{{{W}}}date', '2026-06-26T00:00:00Z')
+        
+        target_runs = child.findall(f'{{{W}}}r') if tag == 'ins' else [child]
+        for r in target_runs:
+            t = r.find(f'{{{W}}}t')
+            if t is not None:
+                r.remove(t)
+                dt = etree.SubElement(r, f'{{{W}}}delText')
+                dt.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+                dt.text = t.text
+            r.set(f'{{{W}}}rsidDel', new_rsid())
+            del_elem.append(r)
+```
+
+### Key Points
+
+- **Same del id** for both the paragraph mark and content dels (e.g., `7777`) — they're part of the same deletion operation
+- **Handle existing INS runs**: If the paragraph has runs inside `w:ins` (from previous revisions), extract them and wrap in `w:del` too
+- **Leave existing DEL runs untouched** — they're already deleted
+- **Copy rPr**: If the original run had `rPr`, copy it into the del run so the strikethrough text renders with correct font/size
+- **Use unique ids**: Pick an id that doesn't collide with existing del/ins ids in the document. Check `max(del_ids) + 1000` if unsure
+
+### Verification
+
+After deletion, render with OnlyOffice and check:
+1. The deleted paragraph appears with strikethrough in markup view
+2. Accepting all revisions removes the paragraph entirely (no empty line)
+3. The paragraph mark (¶) is also deleted — no gap between surrounding paragraphs

skills/legal/contract-editor/references/per-paragraph-font-matching.md

@@ -0,0 +1,50 @@
+# Per-Paragraph Font Matching（2026-07-13 消防设施检测合同教训）
+
+## 问题
+同一份合同中，不同段落的原文runs可能有完全不同的字体属性方案：
+- P20 runs: `ascii=宋体, hAnsi=宋体, cs=宋体, sz=24, eastAsia=None, hint=None`
+- P36/P41 runs: `rPr=None`（完全无字体属性，靠docDefaults/style继承）
+
+如果对所有WB INS runs统一设置一种字体属性，必然导致某些段落mismatch。
+
+## 错误做法
+```python
+# ❌ 全局统一设置
+for ins in all_wb_ins:
+    rf.set('ascii', '宋体')
+    rf.set('sz', '24')
+```
+
+## 正确做法
+```python
+# ✅ 按段落匹配原文第一个非INS/非DEL run的rPr
+for p in paras:
+    # 找到同段落的第一个orig run
+    orig_run = None
+    for child in p:
+        if child.tag == f'{WNS}r':
+            orig_run = child
+            break
+    
+    if orig_run is None:
+        continue  # 整段INS，无参照
+    
+    orig_rpr = orig_run.find(f'{WNS}rPr')
+    orig_rf = orig_rpr.find(f'{WNS}rFonts') if orig_rpr is not None else None
+    
+    # INS的rPr应该与orig_run的rPr完全匹配
+    # 如果orig没有rFonts → INS也不该有
+    # 如果orig有ascii=宋体但没有eastAsia → INS也是这样
+```
+
+## 整段INS段落（无同段原文可比）
+- wb-ins-font-verify.py会报"MISSING HINT (无同段原文可比)"
+- 这是**已知假阳性**，不算真问题
+- 整段INS段落的字体应参照**相邻段落**（前后各2段）的原文run格式
+- 如果相邻原文runs有explicit属性(ascii=宋体 sz=24)，INS也设
+- 如果相邻原文runs无rPr，INS也不设
+
+## 2026-07-13 消防设施检测合同实证
+- 第一次修复：全局strip eastAsia/hint → P20报ASCII MISMATCH（原文有ascii=宋体）
+- 第二次修复：全局设ascii=宋体 → P36/P41报ASCII MISMATCH（原文无rFonts）
+- 正确修复：per-paragraph检查orig_run是否有ascii → 有则INS也设，无则INS也不设

skills/legal/contract-editor/references/reverse-wage-delegation-risk.md

@@ -0,0 +1,46 @@
+# 反委托代发工资法律风险
+
+## 核心法律规定
+
+| 法律依据 | 条文 | 效力 |
+|----------|------|------|
+| 《劳务派遣暂行规定》第8条第(三)项 | 派遣单位应当依法支付被派遣劳动者的劳动报酬 | 强制性规定 |
+| 《劳动合同法》第58条 | 派遣单位是用人单位，应履行用人单位义务 | 法律 |
+| 《劳动合同法》第92条第2款 | 用工单位给被派遣劳动者造成损害的，派遣单位与用工单位承担连带赔偿责任 | 法律 |
+| 《劳务派遣暂行规定》第24条 | 用工单位违法退回的，按劳动合同法第92条第2款执行 | 部门规章 |
+| 劳社部发〔2005〕12号第2条 | 工资支付凭证是认定事实劳动关系的首要证据 | 规范性文件 |
+
+## 核心结论
+
+1. **代发工资 = 事实劳动关系首要证据**：用工单位直接向派遣员工发工资，违反《劳务派遣暂行规定》第8条强制性规定
+2. **协议不能免除法定责任**：甲乙之间的内部追偿条款不能对抗劳动者和行政机关
+3. **退回条款限制**：用工单位只能在法定三种情形下退回（客观情况重大变化/经济性裁员、破产/解散、协议期满）
+4. **"与甲方无涉"条款有法律风险**：可能因违反《劳动合同法》第26条第2款（免除法定责任）被认定无效
+
+## 关键判例
+
+- **广东高院(2022)粤民再30号**：汽车公司以咨询公司名义签劳动合同，工资由汽车公司直接发放。认定汽车公司与劳动者存在事实劳动关系。
+- **(2019)沪0109民初12453号**：用工单位违法退回导致派遣公司违法解除的，用工单位承担连带赔偿责任。
+- **(2022)鲁0322民初834号**：甲公司将工资计算后交乙公司发放，法院认定甲公司存在经济依附性，构成事实劳动关系。
+
+## 审查建议
+
+### 推荐方案（版本1：回归法定安排）
+- 删除代发工资条款，由乙方（派遣公司）直接支付工资
+- 添加甲方监督权、扣款权、违约金条款
+- 添加乙方资质维持、用工管理义务、退回权、保密条款
+
+### 替代方案（版本2：反委托保护）
+如甲方坚持代发，最大化保护措施：
+1. 鉴于条款定性为"委托代发"，明确甲方仅为代理人
+2. 三方签署要求（甲方、乙方、派遣员工）
+3. 事实劳动关系兜底：乙方十日内赔偿甲方全部损失
+4. 履约保证金（金额留空）或银行保函
+5. 税务责任限定：甲方仅承担自身原因导致的差额
+6. 社保义务对等
+7. 劳动关系确认条款
+8. 乙方资质维持 + 用工管理义务
+
+### 退回条款措辞
+❌ "退回派遣员工由乙方依法自行安置处理，与甲方无涉"（有法律风险）
+✅ "派遣员工退回后由乙方依法负责安置处理。因乙方安置不当导致甲方被追究责任的，乙方应赔偿甲方因此遭受的全部损失。"

skills/legal/contract-editor/references/review-opinion-font-enforcement.md

@@ -0,0 +1,120 @@
+# 审查意见文档字体强制设置
+
+## 背景（2026-07-02 肃言+恭兴合同返工）
+
+review-rules.md 规定审查意见文档：中文统一仿宋体，英文Times New Roman。
+
+**问题**：模板文件（`朱家角 审查意见【模板】.docx`）的表头行有显式eastAsia=仿宋，但新建的数据行字体设置不一致：
+- 恭兴审查意见：editor给数据行设了 ascii=仿宋 hAnsi=仿宋（错：英文也变仿宋了）
+- 肃言审查意见：editor压根没给数据行设ascii/hAnsi（只有eastAsia=仿宋）
+
+**根因**：LLM每次独立session生成代码，字体设置逻辑不稳定。
+
+## 强制修复代码（生成审查意见后必跑）
+
+```python
+from docx import Document
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+
+def enforce_review_opinion_fonts(doc_path, save=True):
+    """审查意见文档生成后强制设置所有run的字体。
+    中文=仿宋, 英文=Times New Roman
+    """
+    doc = Document(doc_path)
+    fixed = 0
+    
+    # Fix all table cells
+    for table in doc.tables:
+        for row in table.rows:
+            for cell in row.cells:
+                for p in cell.paragraphs:
+                    for run in p.runs:
+                        fixed += _fix_run_font(run._element)
+    
+    # Fix all paragraphs outside tables
+    for p in doc.paragraphs:
+        for run in p.runs:
+            fixed += _fix_run_font(run._element)
+    
+    if save:
+        doc.save(doc_path)
+    return fixed
+
+def _fix_run_font(run_element):
+    """Ensure run has eastAsia=仿宋, ascii/hAnsi=Times New Roman"""
+    rPr = run_element.find(qn('w:rPr'))
+    if rPr is None:
+        rPr = OxmlElement('w:rPr')
+        run_element.insert(0, rPr)
+    
+    rFonts = rPr.find(qn('w:rFonts'))
+    if rFonts is None:
+        rFonts = OxmlElement('w:rFonts')
+        rPr.insert(0, rFonts)
+    
+    changed = False
+    
+    # eastAsia must be 仿宋
+    if rFonts.get(qn('w:eastAsia')) != '仿宋':
+        rFonts.set(qn('w:eastAsia'), '仿宋')
+        changed = True
+    
+    # ascii must be Times New Roman (NOT 仿宋)
+    if rFonts.get(qn('w:ascii')) != 'Times New Roman':
+        rFonts.set(qn('w:ascii'), 'Times New Roman')
+        changed = True
+    
+    # hAnsi must be Times New Roman (NOT 仿宋)
+    if rFonts.get(qn('w:hAnsi')) != 'Times New Roman':
+        rFonts.set(qn('w:hAnsi'), 'Times New Roman')
+        changed = True
+    
+    return 1 if changed else 0
+```
+
+## 验证方法
+
+```python
+def verify_review_opinion_fonts(doc_path):
+    """验证审查意见文档字体全部正确"""
+    from docx import Document
+    from docx.oxml.ns import qn
+    doc = Document(doc_path)
+    errors = []
+    for table in doc.tables:
+        for i, row in enumerate(table.rows):
+            for j, cell in enumerate(row.cells):
+                for p in cell.paragraphs:
+                    for run in p.runs:
+                        rpr = run._element.find(qn('w:rPr'))
+                        if rpr is None:
+                            errors.append(f'Row{i}Col{j}: no rPr')
+                            continue
+                        rf = rpr.find(qn('w:rFonts'))
+                        if rf is None:
+                            errors.append(f'Row{i}Col{j}: no rFonts')
+                            continue
+                        ea = rf.get(qn('w:eastAsia'))
+                        ascii_f = rf.get(qn('w:ascii'))
+                        hAnsi = rf.get(qn('w:hAnsi'))
+                        if ea != '仿宋':
+                            errors.append(f'Row{i}Col{j}: eastAsia={ea} (should be 仿宋)')
+                        if ascii_f != 'Times New Roman':
+                            errors.append(f'Row{i}Col{j}: ascii={ascii_f} (should be TNR)')
+                        if hAnsi != 'Times New Roman':
+                            errors.append(f'Row{i}Col{j}: hAnsi={hAnsi} (should be TNR)')
+    return errors
+```
+
+## 常见错误
+
+| 错误 | 后果 | 根因 |
+|------|------|------|
+| ascii/hAnsi=仿宋 | 英文/数字渲染用仿宋（无西文字形，显示异常） | LLM把"统一仿宋"理解为所有属性都设仿宋 |
+| 数据行无ascii/hAnsi | 英文回退系统默认字体（可能是宋体/黑体） | 只设了eastAsia，忘设西文字体 |
+| 只有表头有字体 | 数据行全部回退默认 | 模板限制：只有表头行有显式字体 |
+
+## 预防方案
+
+最佳方案：修改模板文件的**Normal样式或Table Grid样式**定义，预设完整字体。但模板可能被多场景共用，最稳妥还是生成后强制设置。

skills/legal/contract-editor/references/review-opinion-format-checklist.md

@@ -0,0 +1,40 @@
+# 审查意见文档格式检查清单 (2026-07-13 Doro纠正)
+
+## 生成后必做三项格式修复
+
+### 1. 删除表格中的空白行
+- "空白行"指**表格中**三列全为空的row（模板占位行）
+- 不是文档段落的空行
+- 代码：遍历table rows，检查所有cells文本为空的row，删除
+
+### 2. 页眉日期改为修订当日
+- 读取 header*.xml，找到日期文本（如"2019/3"）
+- ⚠️ 日期经常被拆成多个run（如"201"+"9"+"/"+"3"）
+- 需逐run处理：拼出完整日期字符串 → 替换为当日（如"2026/7"）
+- 格式：YYYY/M（不补零）
+
+### 3. 标题必须用合同正文全称
+- 读合同docx正文P0（或前几段）获取合同标题全称
+- 填入审查意见文档的《》内
+- ❌ 不能用文件名（文件名可能是简称、带前缀、有(1)后缀）
+- ✅ 必须是合同正文中出现的完整合同名称
+
+## 内容规则（不变）
+- 只写原文和修订后内容，不做理由说明
+- 不写(注：...)
+- 行顺序按条款号排列
+- 有修改意见时删除"无法律修改意见。"段落
+- 批注内容也要体现在表格中
+
+## 字体硬规则
+| 位置 | eastAsia | ascii | hAnsi | sz | bold | hint |
+|------|----------|-------|-------|-----|------|------|
+| 标题 | 仿宋 | - | - | 32(16pt) | True | eastAsia |
+| 表头 | 仿宋 | TNR | TNR | 24(12pt) | True | eastAsia |
+| 数据行 | 仿宋 | TNR | TNR | 24(12pt) | False | eastAsia |
+| 签名 | 仿宋 | TNR | TNR | 24(12pt) | False | eastAsia |
+
+## 同模板合同审查意见一致性
+- 共有修订行内容完全一致
+- 行顺序统一（按条款号）
+- 个案差异行按各合同实际情况（如金额批注）

skills/legal/contract-editor/references/review-opinion-format-rules-0713.md

@@ -0,0 +1,44 @@
+# 审查意见文档格式规则 (2026-07-13 Doro纠正)
+
+## 规则来源
+朱家角 review-rules.md "审查意见格式要求" 章节 (2026-07-13 更新)
+
+## 规则内容
+
+### 1. 删除表格中的空白行
+- "空白行"指的是审查意见表格中**三列全空**的行（条文/原文/修订后都没有内容）
+- 不是正文段落的空白行——正文段落空行是排版问题，表格空行才是Doro说的"删除空白行"
+- 2026-07-13教训：Doro说"删除空白行"，小Maggie误解为删正文段落空行，被纠正后才看到是表格Row1-Row4全空
+
+### 2. 页眉日期改为修订当日
+- 审查意见模板页眉中有日期（如 header2.xml 中 "2019/3"）
+- 生成审查意见时必须更新为**修订当日**的年/月（如"2026/7"）
+- 注意：页眉中的日期可能拆分在多个run中（如"201"+"9"+"/"+"3"），需逐run定位修改
+
+### 3. 标题必须用合同正文全称
+- 规则："标题《》内填写所审查的合同名称"
+- "合同名称" = 合同正文第一段的标题（如"医疗设备器械购销合同"），**不是文件名**
+- 文件名可能是简写（如"医疗合同(2).doc"），但审查意见标题必须写全称
+- 2026-07-13教训：文件名"医疗合同(2)"，合同正文标题是"医疗设备器械购销合同"，审查意见标题应为"关于《医疗设备器械购销合同》的审查意见"
+
+## Workflow重复处理检测（2026-07-13 香花桥安全生产合同教训）
+
+### 问题
+待审查目录的文件可能**已含WB tracked changes**（上一轮workflow产出被放回了待审查）。workflow不做去重检测，会在已有修订上再跑一遍，导致：
+- 文字重复（如"全部损失全部损失"）
+- 相同内容被双重标记为INS（冗余修订痕迹）
+
+### 检测方法
+修复/审查前**第一步**：检查待审查文件是否已有author=WB的tracked changes
+```python
+for ins in body.iter(f'{WNS}ins'):
+    if ins.get(f'{WNS}author') == 'WB':
+        # 文件已被处理过！
+```
+
+### 正确做法
+如果待审查文件已有WB修订：
+1. **以待审查版为基底**（它的第一轮修订是正确的）
+2. 只在此基础上补充缺失的修订（如名称统一）
+3. **不使用任务交付目录的二次处理版本**（它有重复）
+4. 排查是否是auto_notify重复触发或手动误操作导致

skills/legal/contract-editor/references/review-opinion-generation-pattern.md

@@ -0,0 +1,83 @@
+# 审查意见文档生成模式（2026-07-02 确立）
+
+## 核心原则
+
+1. **只体现差异，不做理由说明** — 表格三列（条文｜原文｜修订后）只写文字差异
+2. **字体必须显式设置** — 不依赖模板继承，每个run四属性齐全
+3. **同模板合同内容必须一致** — 行顺序按条款号，模板级修订表述相同
+
+## 字体规则
+
+```python
+def set_cell_font(cell, text, east_asia='仿宋', ascii_font='Times New Roman', h_ansi='Times New Roman', bold=False):
+    """Set cell text with proper font - every run must have explicit rFonts"""
+    from docx.oxml.ns import qn
+    from docx.oxml import OxmlElement
+    
+    # Clear existing content
+    for p in cell.paragraphs[1:]:
+        cell._element.remove(p._element)
+    p = cell.paragraphs[0]
+    for r in p._element.findall(qn('w:r')):
+        p._element.remove(r)
+    
+    # Set paragraph alignment to justify
+    pPr = p._element.find(qn('w:pPr'))
+    if pPr is None:
+        pPr = OxmlElement('w:pPr')
+        p._element.insert(0, pPr)
+    jc = pPr.find(qn('w:jc'))
+    if jc is None:
+        jc = OxmlElement('w:jc')
+        pPr.append(jc)
+    jc.set(qn('w:val'), 'both')
+    
+    # Add run with explicit font settings
+    run = p.add_run(text)
+    rPr = run._element.find(qn('w:rPr'))
+    if rPr is None:
+        rPr = OxmlElement('w:rPr')
+        run._element.insert(0, rPr)
+    
+    rFonts = OxmlElement('w:rFonts')
+    rFonts.set(qn('w:eastAsia'), east_asia)
+    rFonts.set(qn('w:ascii'), ascii_font)
+    rFonts.set(qn('w:hAnsi'), h_ansi)
+    rPr.insert(0, rFonts)
+    
+    if bold:
+        b = OxmlElement('w:b')
+        rPr.append(b)
+```
+
+## 内容格式
+
+### ✅ 正确（只体现差异）
+| 条文 | 原文 | 修订后 |
+|------|------|--------|
+| 第1条 | 买方同意向卖方购买，同时卖方同意授予买方以下器械 | 甲方同意向乙方购买，同时乙方同意向甲方出售以下器械 |
+| 第7.1.2条 | 按照器械的疵劣程度 | 按照器械的瑕疵程度 |
+
+### ❌ 错误（带理由说明）
+| 条文 | 原文 | 修订后 |
+|------|------|--------|
+| 第1条 | ... | 甲方同意向乙方购买……（注：统一称谓为甲方/乙方，"授予"修改为"出售"以准确反映买卖关系） |
+
+## 同模板合同一致性保证
+
+当同一顾问单位有多份同模板合同时：
+
+1. 先确定模板级修订点列表（所有同模板合同共享的问题）
+2. 每份合同的审查意见必须包含**全部**模板级修订点
+3. 行顺序统一按条款号排列
+4. 个案差异（如金额问题）在统一行之外单独加行
+5. 修订后列的文字必须完全一致（逐字对比）
+
+## 验证清单
+
+生成完成后必须验证：
+- [ ] 所有数据行的每个run都有eastAsia=仿宋 + ascii/hAnsi=Times New Roman
+- [ ] 修订后列无(注：...)、无理由解释
+- [ ] 行顺序按条款号排列
+- [ ] 同模板合同的审查意见行数一致（除个案差异行外）
+- [ ] 标题包含合同全称

skills/legal/contract-editor/references/review-opinion-generation.md

@@ -0,0 +1,64 @@
+# 审查意见文档生成规则（朱家角模板）
+
+## 2026-07-02 Doro多次纠正后确立
+
+### 模板结构
+路径：`~/.hermes/shared/模版库/朱家角 审查意见【模板】.docx`
+（新模板参考：`Doro合同审查任务/参考文件/朱家角 审查意见【新模板】.docx`）
+
+1. 空行（P0, 居中）
+2. 标题：`关于《XX》的审查意见`（居中、仿宋 **16pt**(sz=32) **加粗**）
+3. `无法律修改意见。`（有审查意见时**删除此行**）
+4. `审查意见：`（仿宋 12pt）
+5. 表格（条文｜原文｜修订后）
+6. 空行
+7. 签名：`邱庭 律师`（右对齐、仿宋 12pt）
+
+### 字体规格（从模板XML实际读取，非推测）
+- 标题：eastAsia=仿宋, sz=32(16pt), bold=True, **ascii=None**（模板未设）
+- 表头行：eastAsia=仿宋, sz=24(12pt), bold=True
+- 数据行：eastAsia=仿宋, ascii=Times New Roman, hAnsi=Times New Roman, sz=24(12pt), bold=False, hint=eastAsia
+- 正文段：eastAsia=仿宋, sz=24(12pt)
+
+⚠️ 模板本身只设了`eastAsia=仿宋`没有设`ascii`。按review-rules.md要求英文用TNR，生成时应显式设ascii/hAnsi=Times New Roman。
+
+### 文档格式处理（2026-07-12 Doro要求）
+- **删除空白行**：文档中所有无内容的空段落必须删除（模板自带的空行也删）
+- **页眉日期改为修订当日**：header*.xml中如有日期（如"2019/3"），改为当日日期（如"2026/7"）。注意日期可能被拆分为多个run（如"201"+"9"+"/"+"3"），需逐run处理
+- **标题用合同正文中的实际标题**：从合同docx正文提取合同全称（如"医疗设备器械购销合同"），填入《》内。绝不用文件名代替（文件名可能是简称如"医疗合同(2)"）
+- **标题格式**：`关于《XX合同全称》的审查意见`，确保无多余占位符残留
+
+### 内容规则（2026-07-02 Doro明确）
+- **只写原文和修订后的内容（包括批注内容），不做理由说明**
+- ❌ 不写 (注：统一称谓…)
+- ❌ 不写 (注：原引用法规…)
+- ✅ 条文列：第X条 / 第X.X条 / 新增X.X条（主题）
+- ✅ 原文列：合同原文
+- ✅ 修订后列：修订后文字 / 批注内容（如"请注意确认金额"）
+- 行顺序按条款号排列
+- 新增条款：条文栏写"新增X.X条（主题）"，修订后栏直接写条文内容
+
+### 同模板合同的审查意见统一规则
+- 格式、字体、行顺序统一
+- 共有修订行内容完全相同
+- 个案差异行（如金额批注）按各合同实际情况处理
+- 没有问题的合同不要强加批注行
+
+### 生成代码要点
+```python
+# 字体设置（数据行）
+def set_run_font(run_elem, east_asia='仿宋', ascii_font='Times New Roman', h_ansi='Times New Roman', sz_val=24):
+    rFonts.set(qn('w:eastAsia'), east_asia)
+    rFonts.set(qn('w:ascii'), ascii_font)
+    rFonts.set(qn('w:hAnsi'), h_ansi)
+    rFonts.set(qn('w:hint'), 'eastAsia')
+    sz.set(qn('w:val'), str(sz_val))  # 24 = 12pt
+    szCs.set(qn('w:val'), str(sz_val))
+```
+
+### 常见错误（本session犯过的）
+1. 未设sz_val → 回退到默认字号
+2. ascii设成仿宋 → 英文也变仿宋
+3. 用bytes literal写中文 → unicode转义不解析显示乱码
+4. 忘删"无法律修改意见。" → 矛盾
+5. 写(注：...)理由 → 规则禁止

skills/legal/contract-editor/references/same-template-consistency.md

@@ -0,0 +1,32 @@
+# 同模板合同审查一致性规则
+
+## 2026-07-02 朱家角恭兴+肃言合同教训
+
+### 问题
+两份同模板购销合同（结构完全一致，仅乙方名称和设备清单不同），workflow串行审查后修订不一致：
+- 恭兴发现了6.4条（药监局法规过时）但遗漏7.3条（侵权兜底）
+- 肃言发现了7.3条但遗漏6.4条
+
+### 根因
+workflow是逐份串行处理（relay-runner），每份合同完全独立走reviewer→editor→deliverer，各session之间零状态共享。LLM每次独立推理，对同一段文字的优先级判断有随机性。
+
+### 解决办法（已实施）
+
+1. **review-rules.md增加同模板一致性规则**（已做）
+2. **reviewer skill增加前置检查**：审查前检查同目录是否有同模板已审查的合同，对齐修订点
+3. **手动审查时的铁律**：同批同模板合同必须先审完一份→确认修订点→后续合同按同样标准执行
+
+### 判断"同模板"的方法
+- 合同标题完全相同
+- 正文条款结构一致（前20行匹配度>80%）
+- 甲方相同，乙方不同
+- 区别仅在商业条款（金额、设备清单、乙方信息等）
+
+### 审查意见的统一要求
+- 共有修订行：内容必须完全一致
+- 行顺序：按条款号排列
+- 个案差异：只有真实存在的问题才加行（如恭兴金额有误加批注行，肃言金额正确则不加）
+- 格式：字体/字号/对齐统一
+
+### 批注的统一原则
+"统一"是审查逻辑统一，不是机械复制。金额有问题的合同加批注，没问题的不加——逻辑一致即可。不能给正确的合同强加问题批注。

skills/legal/contract-editor/references/same-template-revision-transfer.md

@@ -0,0 +1,189 @@
+# Same-Template Revision Transfer (同模板修订参照)
+
+When Doro says "参照X合同的修订进行修订" — apply the same WB revisions from a reference contract to another contract using the same template.
+
+## ⚠️ Doro 强制验证纪律（2026-07-08 明确要求）
+
+Doro 明确要求做同模板修订参照时必须走完以下步骤，缺一不可：
+
+1. **先确认模板一致性**：逐段对比两份合同原文（去掉修订后的文本），确认段落数一致、差异仅限业务内容（项目名称、单价等），其余结构完全相同。打印差异段数/总段数（如"9/62段有差异"）。
+2. **参照修订**：提取参照合同的WB修订→适配目标合同业务语境→应用
+3. **格式/字体/编号全检**：所有INS的rPr必须与前后邻居run一致（逐个检查sz/rFonts/bold）。遵守workflow规则（author=WB、精准到字、不整段del+ins）
+4. **全文阅读审查合理性**：渲染accept后全文，逐段通读确认修订逻辑合理、不破坏上下文语义
+5. **交付前检查**：python-docx可打开、无异常字符、修订数与参照合同一致、他人修订保持不动
+
+**不能跳步直接做修订然后上传。** Doro原话："你先确认：两个合同是不是模板一样，内容一样；如果一样，参照修改；你修改的格式、字体、编号等，都要遵守workflow的规则；全文阅读，修订是否合理。最后检查交付。"
+
+## Workflow
+
+### Step 1: Extract revisions from reference contract
+
+```python
+import zipfile
+from lxml import etree
+
+ns = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+
+def extract_wb_revisions(filepath):
+    """Extract all WB-authored INS and DEL from a contract."""
+    with zipfile.ZipFile(filepath, 'r') as z:
+        content = z.read('word/document.xml')
+    tree = etree.fromstring(content)
+    
+    revisions = []
+    for ins in tree.iter(f'{{{ns}}}ins'):
+        if ins.get(f'{{{ns}}}author') != 'WB':
+            continue
+        texts = [t.text for t in ins.iter(f'{{{ns}}}t') if t.text]
+        # Get parent paragraph for context
+        parent_p = ins
+        while parent_p is not None and parent_p.tag != f'{{{ns}}}p':
+            parent_p = parent_p.getparent()
+        p_texts = [t.text for t in parent_p.iter(f'{{{ns}}}t') if t.text] if parent_p is not None else []
+        revisions.append({
+            'type': 'INS', 'text': ''.join(texts),
+            'para_context': ''.join(p_texts)[:120]
+        })
+    
+    for d in tree.iter(f'{{{ns}}}del'):
+        if d.get(f'{{{ns}}}author') != 'WB':
+            continue
+        texts = [t.text for t in d.iter(f'{{{ns}}}delText') if t.text]
+        parent_p = d
+        while parent_p is not None and parent_p.tag != f'{{{ns}}}p':
+            parent_p = parent_p.getparent()
+        p_texts = [t.text for t in parent_p.iter(f'{{{ns}}}t') if t.text] if parent_p is not None else []
+        revisions.append({
+            'type': 'DEL', 'text': ''.join(texts),
+            'para_context': ''.join(p_texts)[:120]
+        })
+    return revisions
+```
+
+### Step 2: Identify modification patterns
+
+Group INS/DEL pairs by paragraph context to understand what was changed:
+- Simple text replacement: DEL "协议" + INS "合同" in same paragraph
+- Text insertion: INS without corresponding DEL (e.g., data ownership sentence)
+- Prefix insertion: INS "上海市" before existing text
+
+### Step 3: Context adaptation
+
+When the template is shared but service content differs, adapt context-specific terms:
+- "体检服务" → "口腔检查服务"
+- "学生个人信息、健康检查结果" → "个人信息、检查结果"
+- Keep legal boilerplate identical (e.g., "归甲方所有", "合同期满")
+
+### Step 4: Apply to target contract (zipfile+lxml)
+
+Use three operations:
+
+#### A. Tracked replace (DEL old + INS new)
+```python
+def do_tracked_replace(para, find_text, replace_text):
+    """Find text in paragraph runs, create DEL + INS."""
+    # Build character map from runs (skip ins/del elements)
+    char_map = []
+    for elem in para:
+        if elem.tag == f'{{{ns}}}r':
+            t = elem.find(f'{{{ns}}}t')
+            if t is not None and t.text:
+                for ci in range(len(t.text)):
+                    char_map.append((elem, t, ci))
+    
+    full_text = ''.join(cm[1].text[cm[2]] for cm in char_map)
+    pos = full_text.find(find_text)
+    if pos == -1:
+        return False
+    
+    # Verify single-run containment, then split into before/DEL/INS/after
+    # ... (see session code for full implementation)
+```
+
+#### B. Insert before text
+```python
+def do_tracked_insert_before(para, anchor_text, insert_text):
+    """Insert INS element right before anchor_text."""
+    for elem in para:
+        if elem.tag == f'{{{ns}}}r':
+            t = elem.find(f'{{{ns}}}t')
+            if t is not None and t.text and anchor_text in t.text:
+                # Split run, insert INS before anchor portion
+                ...
+```
+
+#### C. Insert after text
+```python
+def do_tracked_insert_after(para, anchor_text, insert_text):
+    """Insert INS element right after anchor_text."""
+    for elem in para:
+        if elem.tag == f'{{{ns}}}r':
+            t = elem.find(f'{{{ns}}}t')
+            if t is not None and t.text and anchor_text in t.text:
+                # Split run, insert INS after anchor portion
+                ...
+```
+
+## Data Attribution Rule (2026-07-08 Doro clarification)
+
+When writing data ownership/attribution clauses across same-template contracts:
+
+**LOCKED (identical across all contracts)**: 归属表述 = "归甲方或相关权利方所有"
+- NOT "归甲方所有" (excludes data subjects' rights under PIPL)
+- The phrase "甲方或相关权利方" covers both: data甲方 owns (aggregated stats, service outputs) AND personal info that belongs to data subjects
+
+**NOT LOCKED (varies by contract)**: The descriptive content before the attribution phrase
+- 体检合同: "乙方在提供体检服务过程中获取和产生的全部数据（包括但不限于学生个人信息、健康检查结果等）"
+- 口腔检查合同: "乙方在提供口腔检查服务过程中获取和产生的全部数据（包括但不限于个人信息、检查结果等）"
+- Other contracts: adapt to the specific service/data context
+
+**Doro原话**: "我只需要涉及到数据权利的归属时，把归属谁改成'归甲方或相关权利方所有'，其他的内容不同合同会不同，所以你不能写死。"
+
+**Rule source**: `review-rules.md` §4 保密/数据 (updated 2026-07-08)
+
+## Pitfalls
+
+### 1. `<w:proofErr>` splits runs
+Text like "青浦区练塘镇" may be split into multiple runs separated by `<w:proofErr>` elements:
+```xml
+<w:r><w:t>青浦区练塘</w:t></w:r>
+<w:proofErr w:type="gramStart"/>
+<w:r><w:t>镇社区卫生服务中心</w:t></w:r>
+```
+
+**Fix**: Search at individual run level (`for elem in para: if elem.tag == w:r`), not at full paragraph text level. Insert INS before the run containing the anchor, not at a text position within full paragraph text.
+
+### 2. "达成如下协议" — not all "协议" should be replaced
+In the reference contract, "达成如下协议：" was NOT changed (it's a formulaic expression meaning "reached the following agreement"). Only contextual uses of "协议" meaning "this agreement/contract" were changed to "合同"/"本合同".
+
+**Rule**: Compare reference contract's accepted text to determine which instances were changed and which were left alone.
+
+### 3. INS rPr must clone from target run (not reference)
+The target contract's runs may have different formatting than the reference. Always clone rPr from the **target paragraph's existing run**, not from the reference contract.
+
+### 4. Order of operations matters
+Do replacements BEFORE insertions. Insertions change paragraph structure and character positions, which can break subsequent text searches.
+
+Recommended order:
+1. All `do_tracked_replace` calls (these only split existing runs)
+2. All `do_tracked_insert_after` / `do_tracked_insert_before` calls (these add new elements)
+
+### 5. Verify with accept-all view
+After applying all revisions, verify by building accepted text (skip DEL, include INS) for key paragraphs and comparing against the reference contract's accepted text.
+
+## 2026-07-08 实证：练塘口腔检查合同
+
+Reference: 【修】2026年学生体检外包合同--练塘(1).docx
+Target: 2026年口腔检查外包合同--练塘.docx
+
+Modifications applied:
+| # | Type | Content | Adaptation |
+|---|------|---------|------------|
+| 1 | INS before "青浦区" | "上海市" | None (identical) |
+| 2a | INS after "保密义务。" | Data ownership sentence | "体检服务"→"口腔检查服务", "学生个人信息、健康检查结果"→"个人信息、检查结果" |
+| 2b | DEL "协议" + INS "合同" | "协议期满"→"合同期满" | None |
+| 2c | DEL "服务协议" + INS "本合同" | "服务协议解除"→"本合同解除" | None |
+| 2d | DEL "本协议" + INS "本合同" | "本协议的履行"→"本合同的履行" | None |
+| 3 | DEL "本协议" + INS "本合同" | "本协议一式"→"本合同一式" | None |
+
+proofErr pitfall encountered: "青浦区练塘" split by `<w:proofErr>` — had to insert at run level rather than text-position level.

skills/legal/contract-editor/references/single-paragraph-section-no-numpr.md

@@ -0,0 +1,32 @@
+# 单段正文章节不加numPr（2026-07-12 盈浦健康科普合同）
+
+## 规则
+当新增的章节（如"八、转包与分包"）下只有**一段**正文时，该段落**不设numPr**。
+
+## 判断方法
+1. 看原文中同样只有一段正文的章节是否有numPr
+2. 如果原文单段章节无numPr（如"一、合作背景"P12无numPr），新增也不加
+3. 多段正文章节有numPr（如"七、不可抗力"两段都有numId=11）
+4. 这是"有2才有1"规则在numPr层面的体现
+
+## 实证
+盈浦健康科普服务合同：
+- 原文"一、合作背景": 1段正文 → 无numPr
+- 原文"七、不可抗力": 2段正文 → numId=11
+- 新增"八、转包与分包": 1段正文 → 不应有numPr
+
+错误地加了numId=14（新建abstractNum），导致OnlyOffice渲染出孤零零的"1."
+
+## 同时要检查的段落格式
+新增段落的pPr必须与原文同类型段落**完整匹配**：
+- `w:ind`（firstLine/firstLineChars）—— 首行缩进
+- `w:spacing`（line/lineRule）
+- 不能只有spacing没有ind
+
+实证：原文正文段有 `ind firstLine=420 firstLineChars=200`，workflow新增P75只有spacing缺ind → 渲染无首行缩进。
+
+## heading run的sz继承陷阱
+原文Heading 1样式定义sz=48（24pt），heading段落的plain run**没有显式sz**（靠样式继承）。
+workflow/ContractEditor操作后可能给某个run添加spurious `sz=20`（从szCs误取），导致该run从24pt变成10pt。
+
+检查：修订后Heading段落的所有plain run不应有新增的显式sz。

skills/legal/contract-editor/references/split-merged-title-body-paragraph.md

@@ -0,0 +1,175 @@
+# 拆分合并的标题+正文段落为两个独立INS段落
+
+## 场景
+
+Reviewer发现新增条款的标题和正文被合并在一个`<w:p>`段落中（通过`<w:t>`内的换行符分隔），要求拆分为两个独立段落——标题段和正文段，各有独立的格式。
+
+## 判别
+
+- 目标段落是一个`<w:p>`，内含一个`<w:ins author="WB">`，`<w:ins>`内只有一个`<w:r>`，`<w:t>`文本包含换行符（`\n`）分隔标题和正文
+- 标题格式要求：参照原文同级标题段落（如"第四条"或"第六条"）
+- 正文格式要求：参照原文同层级正文段落（如"一、施工期限"）
+
+## 操作步骤
+
+### 1. 读取原文并定位目标段落
+
+```python
+import zipfile
+from lxml import etree
+import copy
+
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+
+with zipfile.ZipFile(docx_path, 'r') as zf:
+    doc_xml = etree.parse(zf.open('word/document.xml'))
+    all_files = {name: zf.read(name) for name in zf.namelist()}
+
+body = doc_xml.getroot().find(f'{{{W}}}body')
+paragraphs = list(body.findall(f'{{{W}}}p'))
+
+# 找到目标段落
+for i, p in enumerate(paragraphs):
+    texts = []
+    for elem in p.iter(f'{{{W}}}t'):
+        texts.append(elem.text or '')
+    full_text = ''.join(texts)
+    if '第五条' in full_text and '转包' in full_text:
+        target_idx = i
+        break
+```
+
+### 2. 提取标题和正文文本
+
+```python
+full_text = ''
+for elem in target_p.iter(f'{{{W}}}t'):
+    full_text += elem.text or ''
+
+lines = full_text.split('\n')
+title_text = lines[0].strip()   # "第五条 转包与分包"
+body_text = '\n'.join(lines[1:]).strip()  # 正文内容
+```
+
+### 3. 找到参照段落并克隆pPr
+
+标题段pPr从紧邻的同级标题段落克隆（如"第六条"），正文段pPr从同层级正文段落克隆（如"一、施工期限"）。
+
+```python
+# 标题参照段落（如"第六条"）
+ref_title_p = paragraphs[24]  # 原文"第六条"的索引
+ref_title_pPr = ref_title_p.find(f'{{{W}}}pPr')
+title_pPr = copy.deepcopy(ref_title_pPr)
+
+# 正文参照段落（如"一、施工期限"）
+ref_body_p = paragraphs[13]  # 原文"一、施工期限"的索引
+ref_body_pPr = ref_body_p.find(f'{{{W}}}pPr')
+body_pPr = copy.deepcopy(ref_body_pPr)
+```
+
+### 4. 构建标题段落
+
+```python
+title_p = etree.Element(f'{{{W}}}p', nsmap=target_p.nsmap)
+title_p.append(title_pPr)
+
+# 标题rPr：黑体四属性 + hint=eastAsia + sz=24 + bold
+title_rPr = etree.Element(f'{{{W}}}rPr')
+rFonts = etree.SubElement(title_rPr, f'{{{W}}}rFonts')
+for attr in ['ascii', 'hAnsi', 'eastAsia', 'cs']:
+    rFonts.set(f'{{{W}}}{attr}', '黑体')
+rFonts.set(f'{{{W}}}hint', 'eastAsia')
+etree.SubElement(title_rPr, f'{{{W}}}spacing').set(f'{{{W}}}val', '-6')
+etree.SubElement(title_rPr, f'{{{W}}}sz').set(f'{{{W}}}val', '24')
+etree.SubElement(title_rPr, f'{{{W}}}szCs').set(f'{{{W}}}val', '24')
+etree.SubElement(title_rPr, f'{{{W}}}b')  # 加粗
+
+title_ins = etree.SubElement(title_p, f'{{{W}}}ins')
+title_ins.set(f'{{{W}}}id', str(new_ins_id))
+title_ins.set(f'{{{W}}}author', 'WB')
+title_ins.set(f'{{{W}}}date', '2026-06-26T14:00:00Z')
+
+title_r = etree.SubElement(title_ins, f'{{{W}}}r')
+title_r.set(f'{{{W}}}rsidR', '00AA0001')
+title_r.append(copy.deepcopy(title_rPr))
+title_t = etree.SubElement(title_r, f'{{{W}}}t')
+title_t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+title_t.text = title_text
+```
+
+### 5. 构建正文段落
+
+```python
+body_p = etree.Element(f'{{{W}}}p', nsmap=target_p.nsmap)
+body_p.append(body_pPr)
+
+# 正文rPr：宋体四属性 + hint=eastAsia + sz=21
+body_rPr = etree.Element(f'{{{W}}}rPr')
+body_rFonts = etree.SubElement(body_rPr, f'{{{W}}}rFonts')
+for attr in ['ascii', 'hAnsi', 'eastAsia', 'cs']:
+    body_rFonts.set(f'{{{W}}}{attr}', '宋体')
+body_rFonts.set(f'{{{W}}}hint', 'eastAsia')
+etree.SubElement(body_rPr, f'{{{W}}}spacing').set(f'{{{W}}}val', '-4')
+etree.SubElement(body_rPr, f'{{{W}}}sz').set(f'{{{W}}}val', '21')
+
+body_ins = etree.SubElement(body_p, f'{{{W}}}ins')
+body_ins.set(f'{{{W}}}id', str(new_ins_id + 1))
+body_ins.set(f'{{{W}}}author', 'WB')
+body_ins.set(f'{{{W}}}date', '2026-06-26T14:00:00Z')
+
+body_r = etree.SubElement(body_ins, f'{{{W}}}r')
+body_r.set(f'{{{W}}}rsidR', '00AA0001')
+body_r.append(copy.deepcopy(body_rPr))
+body_t = etree.SubElement(body_r, f'{{{W}}}t')
+body_t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+body_t.text = body_text
+```
+
+### 6. 插入并删除原段落（⚠️ addprevious顺序陷阱）
+
+**关键**：`addprevious`将元素插入到目标元素的**紧邻前一个**位置。要得到 [title, body, old_p] 的顺序，必须：
+
+```python
+old_p = paragraphs[target_idx]
+old_p.addprevious(body_p)   # 先插入body → 顺序: body, old_p
+body_p.addprevious(title_p)  # 再在body前插入title → 顺序: title, body, old_p
+body.remove(old_p)           # 删除原段落 → 顺序: title, body, ...
+```
+
+**错误做法**（会导致顺序反转）：
+```python
+# ❌ 错误：title在body之后
+old_p.addprevious(title_p)  # title, old_p
+old_p.addprevious(body_p)   # title, body, old_p  ← 看起来对但实际是 body, title, old_p
+```
+
+原理：`addprevious`始终插入到目标元素的紧邻前一个位置。`old_p.addprevious(body_p)` 后 body_p 是 old_p 的前一个兄弟；`old_p.addprevious(title_p)` 后 title_p 成为 old_p 的前一个兄弟，body_p 被推到 title_p 之前。
+
+### 7. 保存
+
+```python
+new_doc_xml = etree.tostring(doc_xml.getroot(), xml_declaration=True, encoding='UTF-8', standalone=True)
+
+with zipfile.ZipFile(docx_path, 'w', zipfile.ZIP_DEFLATED) as zf_out:
+    for name, data in all_files.items():
+        if name == 'word/document.xml':
+            zf_out.writestr(name, new_doc_xml)
+        else:
+            zf_out.writestr(name, data)
+```
+
+## 验证
+
+1. **段落顺序**：确认 [title_idx] 是标题文本，[title_idx+1] 是正文文本
+2. **字体属性**：标题 rPr 含 rFonts四属性(黑体) + hint=eastAsia + sz=24 + bold；正文 rPr 含 rFonts四属性(宋体) + hint=eastAsia + sz=21
+3. **INS属性**：author=WB, 有 rsidR, 有唯一id
+4. **OnlyOffice渲染**：x2t渲染为PDF，pdftotext确认标题和正文各占一行，正文有缩进
+5. **validate()**：运行ContractEditor的validate()，区分预存误报和本轮新增问题
+
+## 注意事项
+
+- 标题和正文的pPr应从**紧邻的原文同级段落**克隆，而非从目标段落自身克隆
+- rFonts必须设置四属性（ascii, hAnsi, eastAsia, cs），仅设hint=eastAsia是不够的
+- 标题的bold属性按照reviewer的指令设置（注意：原文标题可能不加粗，但reviewer可能要求加粗）
+- 两个INS段落使用不同的id（从文档中max_ins_id+1开始递增）
+- 操作前先备份原文件

skills/legal/contract-editor/references/split-run-renumber.md

@@ -0,0 +1,60 @@
+# Split-Run Numbering in docx XML
+
+## Problem
+Contract numbering like `（5）` is often split across multiple `<w:r>` runs in the XML:
+```xml
+<w:r><w:t>（</w:t></w:r>
+<w:r><w:t>5</w:t></w:r>
+<w:r><w:t>）委托方</w:t></w:r>
+```
+
+A naive `tracked_replace("（5）", "（6）")` searching for the complete string in a single `<w:t>` will **silently fail** — no match, no error, no renumbering.
+
+## Solution: Multi-run concatenation + split
+
+### Algorithm
+```python
+def tracked_replace_split_number(p, old_num, new_num):
+    """Handle （old_num） spread across multiple runs."""
+    target = f'（{old_num}）'
+    new_target = f'（{new_num}）'
+    
+    # 1. Collect all plain runs (not inside w:ins or w:del)
+    plain_runs = [(index, run, text) for each child of p]
+    
+    # 2. Slide a window: concatenate adjacent run texts until target is found
+    for start in range(len(plain_runs)):
+        concat = ""
+        for end in range(start, start+4):  # max 4 runs for a number
+            concat += plain_runs[end].text
+            if target in concat:
+                # Found! Extract before/after text around the number
+                runs_to_wrap = plain_runs[start:end+1]
+                # ...proceed to replace
+    
+    # 3. Remove original runs, insert:
+    #    - [before_run if text before number]
+    #    - DEL element with delText=target
+    #    - INS element with t=new_target  
+    #    - [after_run if text after number, e.g. "委托方"]
+    
+    # 4. Set rsid attributes: rsidDel on DEL runs, rsidR on INS runs
+```
+
+### Critical: Process order
+**Always renumber from bottom to top** (last paragraph first) to avoid index shifting:
+```python
+# CORRECT
+renumber = [(P113, '10', '11'), (P112, '9', '10'), (P111, '7', '8')]
+
+# WRONG - P112 was already renumbered when we get to it
+renumber = [(P111, '7', '8'), (P112, '9', '10'), (P113, '10', '11')]
+```
+
+### Edge cases encountered (2026-06-08)
+- `（` + `10）` (two runs, not three) — the closing `）` merged with the digit
+- `（` + `5` + `）委托方` — closing `）` merged with following text, must split run to preserve "委托方"
+- Copy `w:rPr` from original runs to all new DEL/INS runs to preserve font/size
+
+## Lesson
+This was the root cause of a terminal review failure where 3 new clauses were inserted without numbering, and subsequent numbering was not renumbered. The `tracked_replace` function matched nothing because it expected `（5）` as a single text node.

skills/legal/contract-editor/references/standalone-charlevel-tracked-changes.md

@@ -0,0 +1,87 @@
+# Standalone Char-Level Tracked Changes + Comments (non-workflow)
+
+When modifying contracts **outside** the Doro/邱律师 workflow (e.g. Maggie directly asks to revise a client's agreement), the full `ContractEditor` library + review-rules machinery is overkill. Use this lightweight pattern instead.
+
+## When to use
+- Maggie sends a contract and says "帮我改一下" / "修改这份协议"
+- No workflow, no reviewer, no deliverer — just direct revision
+- Still must produce Word-native tracked changes (del/ins) + comments
+
+## Core technique: `difflib.SequenceMatcher` char-level diff
+
+```python
+import difflib
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+
+def char_level_replace(para, new_text, author="WB", date="2026-07-07T10:00:00Z"):
+    """Replace paragraph text with char-level tracked changes.
+    Unchanged chars → normal w:r (preserved).
+    Deleted chars → w:del + w:delText.
+    Inserted chars → w:ins + w:t.
+    """
+    p = para._element
+    old_text = para.text
+    if old_text == new_text:
+        return
+    
+    # Remove existing runs (preserve pPr)
+    for child in list(p):
+        tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+        if tag in ('r', 'ins', 'del', 'hyperlink'):
+            p.remove(child)
+    
+    sm = difflib.SequenceMatcher(None, old_text, new_text)
+    for op, i1, i2, j1, j2 in sm.get_opcodes():
+        if op == 'equal':
+            p.append(make_run(old_text[i1:i2]))
+        elif op == 'delete':
+            p.append(make_del_run(old_text[i1:i2], author, date))
+        elif op == 'insert':
+            p.append(make_ins_run(new_text[j1:j2], author, date))
+        elif op == 'replace':
+            p.append(make_del_run(old_text[i1:i2], author, date))
+            p.append(make_ins_run(new_text[j1:j2], author, date))
+```
+
+## Comments injection (bypassing python-docx limitations)
+
+python-docx has no native comment support. Inject manually:
+
+1. Add `commentRangeStart` + `commentRangeEnd` + `commentReference` run to target paragraph
+2. Build `word/comments.xml` as a plain string (proper namespace, no lxml serialization quirks)
+3. Inject into the docx ZIP: update `[Content_Types].xml` + `word/_rels/document.xml.rels`
+
+### Critical: comments.xml namespace
+
+**Wrong** (causes "reuse of xmlns" error):
+```python
+comments_xml = etree.Element(qn('w:comments'))
+comments_xml.set(qn('xmlns:w'), WNS)  # ❌ double declaration
+```
+
+**Right** (build as plain string):
+```python
+def build_comments_xml(comments_list):
+    lines = ['<?xml version="1.0" encoding="UTF-8" standalone="yes"?>']
+    lines.append('<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"'
+                 ' xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">')
+    for cid, text in comments_list:
+        safe = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        lines.append(f'  <w:comment w:id="{cid}" w:author="WB" w:date="..." w:initials="WB">')
+        lines.append(f'    <w:p><w:r><w:t>{safe}</w:t></w:r></w:p>')
+        lines.append(f'  </w:comment>')
+    lines.append('</w:comments>')
+    return "\n".join(lines)
+```
+
+## Pitfalls learned (2026-07-07 退休返聘案)
+
+1. **lxml etree serialization breaks Word**: `etree.tostring()` produces `xmlns:ns0=...` prefix notation that Word/OnlyOffice cannot parse. Always build comments.xml as a plain string.
+2. **Entire-paragraph del+ins is unacceptable**: Maggie and Doro both require char-level precision. "原文相同的部分保留，不一样的用修订" — this is non-negotiable.
+3. **New paragraphs (fully inserted)**: Use `pPr/rPr/ins` mark to flag the ¶ itself as inserted, plus `w:ins` wrapping the text run. Both are needed for Word to show the full paragraph as tracked insertion.
+4. **Verify files open correctly**: After save, always `Document(path)` to confirm no XML parse errors.
+
+## Template (full working script structure)
+
+See `/tmp/modify_v3_charlevel.py` from the 2026-07-07 session — processes two contracts (full-time + part-time) with char-level diff + comments injection. Pattern: `process_contract(input, output, is_fulltime=bool)`.

skills/legal/contract-editor/references/strip-numpr-before-manual-numbering.md

@@ -0,0 +1,93 @@
+# Strip numPr Before Inserting Manual Numbering (2026-07-01)
+
+## Problem
+
+When adding manual numbering (e.g. "第一条  ") as `w:ins` at the beginning of a paragraph that already has `<w:numPr>` (automatic numbering like "%1." decimal format), OnlyOffice renders BOTH:
+- The automatic number: "1."
+- The manual INS text: "第一条"
+
+Result: "1. 第一条  乙方应严格按照..."
+
+## Root Cause
+
+`<w:numPr>` in pPr tells the rendering engine to prepend an auto-generated number. The `w:ins` text is just another run in the paragraph — it doesn't suppress the auto-numbering.
+
+Additionally, `<w:pPrChange>` records the pre-revision pPr state. If pPrChange still contains `<w:numPr>`, some renderers will show the old numbering in markup view.
+
+## Affected Scenarios
+
+1. **反委托代发工资协议 (2026-07-01)**: Original paragraphs P6-P12, P19 had `numId=1` or `numId=3` (decimal "%1." format). After adding "第一条" through "第十一条" as INS, OnlyOffice showed "1. 第一条", "2. 第二条", etc.
+
+2. **Any contract where the original used auto-numbering**: Check `numbering.xml` for active numId references with `numFmt=decimal` or `numFmt=chineseCounting`.
+
+## Fix Pattern
+
+```python
+import zipfile
+from lxml import etree
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+with zipfile.ZipFile(docx_path, 'r') as z:
+    all_files = {name: z.read(name) for name in z.namelist()}
+
+doc = etree.fromstring(all_files['word/document.xml'])
+body = doc.find(f'{WNS}body')
+paras = body.findall(f'{WNS}p')
+
+# Identify paragraphs where we added manual numbering INS
+# These are paragraphs that have both:
+# 1. A w:ins with author=WB containing "第X条" text
+# 2. A pPr with numPr
+
+for i, p in enumerate(paras):
+    ppr = p.find(f'{WNS}pPr')
+    if ppr is None:
+        continue
+    
+    # Check if this paragraph has our manual numbering INS
+    has_manual_numbering = False
+    for child in p:
+        tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+        if tag == 'ins' and child.get(f'{WNS}author') == 'WB':
+            text = ''.join(t.text for t in child.iter(f'{WNS}t') if t.text)
+            if '第' in text and '条' in text:
+                has_manual_numbering = True
+                break
+    
+    if not has_manual_numbering:
+        continue
+    
+    # Strip numPr from pPr
+    num_pr = ppr.find(f'{WNS}numPr')
+    if num_pr is not None:
+        ppr.remove(num_pr)
+        print(f"P{i}: Stripped numPr from pPr")
+    
+    # Strip numPr from pPrChange
+    ppc = ppr.find(f'{WNS}pPrChange')
+    if ppc is not None:
+        inner_ppr = ppc.find(f'{WNS}pPr')
+        if inner_ppr is not None:
+            inner_num = inner_ppr.find(f'{WNS}numPr')
+            if inner_num is not None:
+                inner_ppr.remove(inner_num)
+                print(f"P{i}: Stripped numPr from pPrChange")
+
+# Save back
+all_files['word/document.xml'] = etree.tostring(doc, xml_declaration=True, encoding='UTF-8', standalone=True)
+# Write to temp file then replace (never write to same zip you're reading)
+```
+
+## Verification
+
+After stripping, render with OnlyOffice and confirm:
+1. Markup view shows only the manual numbering (no "1." prefix)
+2. Accepted-revisions view shows clean "第一条" through "第十一条"
+3. python-docx can still open the file without errors
+
+## Edge Cases
+
+- **DEL-only empty paragraphs** (e.g. P8, P9 where all content is w:del): These may still have numPr. If they render a visible "3." or "4." in the gap, strip those too.
+- **Cross-paragraph clauses** (P6+P7 = one clause): P7 may have its own independent numPr even though it's a continuation paragraph. Strip it.
+- **numId=0 (disabled numbering)**: `numId=0` in OOXML means "numbering OFF" — it doesn't render anything. Only strip numPr where `numId > 0` and the corresponding abstractNum has a visible numFmt (decimal, chineseCounting, etc.).

skills/legal/contract-editor/references/systematic-file-recovery-lost-authors.md

@@ -0,0 +1,121 @@
+# Systematic File Recovery for Lost Author Markers
+
+When intermediate files have been overwritten during iterative editing (e.g., multiple versions of a contract revision), and you need to find a specific version that contains tracked changes by a particular author (e.g., "华诚-Z"), use this systematic scan approach.
+
+## Scenario
+- You made multiple intermediate files (v1, v2, v3...) in `/tmp/` during contract editing
+- You overwrote files, losing the version with a specific author's tracked changes
+- You need to find ANY surviving file that still has that author's `w:author` attribute
+
+## Recovery Technique
+
+### Step 1: List all candidate files
+Find all `.docx` files in the working directory that are newer than the original source file:
+```bash
+find /tmp -name '*.docx' -newer /tmp/original_file.docx 2>/dev/null | sort
+```
+
+### Step 2: Check each file for the target author
+```python
+import zipfile, re, os
+from datetime import datetime
+
+target_author = '华诚-Z'  # or whatever author you're looking for
+
+files = [
+    "/tmp/v1_clean.docx",
+    "/tmp/v1_final.docx",
+    # ... list all candidate files from Step 1
+]
+
+for f in files:
+    if not os.path.exists(f):
+        continue
+    try:
+        z = zipfile.ZipFile(f)
+        content = z.read('word/document.xml').decode('utf-8', 'ignore')
+        authors = set(re.findall(r'w:author="([^"]+)"', content))
+        mt = datetime.fromtimestamp(os.path.getmtime(f)).strftime('%m-%d %H:%M')
+        has_target = target_author in authors
+        marker = '★' if has_target else ' '
+        print(f"{marker} {os.path.basename(f):35s} {mt}  authors={sorted(authors)}")
+        z.close()
+    except Exception as e:
+        print(f"  ERROR {f}: {e}")
+```
+
+### Step 3: Extract the target author's changes
+Once you find the file with the target author, extract their specific tracked changes:
+```python
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+z = zipfile.ZipFile('/tmp/file_with_target_author.docx')
+with z.open('word/document.xml') as f:
+    tree = etree.parse(f)
+root = tree.getroot()
+body = root.find(f'{WNS}body')
+paras = body.findall(f'{WNS}p')
+
+for i, p in enumerate(paras):
+    has_target = False
+    parts = []
+    for child in p:
+        tag = etree.QName(child.tag).localname
+        if tag == 'r':
+            t = child.find(f'{WNS}t')
+            if t is not None and t.text:
+                parts.append(('RUN', t.text, None))
+        elif tag == 'ins':
+            author = child.get(f'{WNS}author', '?')
+            if target_author in author:
+                has_target = True
+            ins_texts = []
+            for r in child.findall(f'{WNS}r'):
+                t = r.find(f'{WNS}t')
+                if t is not None and t.text:
+                    ins_texts.append(t.text)
+            if ins_texts:
+                parts.append(('INS', ''.join(ins_texts), author))
+        elif tag == 'del':
+            author = child.get(f'{WNS}author', '?')
+            if target_author in author:
+                has_target = True
+            del_texts = []
+            for r in child.findall(f'{WNS}r'):
+                t = r.find(f'{WNS}delText')
+                if t is not None and t.text:
+                    del_texts.append(t.text)
+            if del_texts:
+                parts.append(('DEL', ''.join(del_texts), author))
+    
+    if has_target:
+        print(f"\n★ P{i}:")
+        for kind, text, author in parts:
+            if kind == 'RUN':
+                print(f"  [原文] {repr(text)}")
+            else:
+                print(f"  [{kind} by {author}] {repr(text)}")
+
+z.close()
+```
+
+## Empirical Case (2026-07-01 反委托代发工资协议)
+- Made ~15 intermediate files in `/tmp/` during iterative editing
+- Overwrote all files, changing all `w:author` attributes to "WB"
+- User (Doro) demanded recovery of 华诚-Z's tracked changes
+- Systematic scan found `/tmp/v1_doro_updated.docx` with `authors=['WB', '华诚-Z']`
+- Extracted 华诚-Z's 3 specific changes:
+  - P6: INS "等" (between WB's "《劳务派遣暂行规定》" and "规定，")
+  - P12: INS "退回派遣员工" + INS "由乙方依法自行安置处理，与甲方无涉。"
+
+## Key Pitfalls
+1. **Don't assume the file is gone** — check ALL intermediate files, not just the ones you expect
+2. **Check timestamps** — the file you need might be an early intermediate, not the latest
+3. **Use `w:author` attribute** — this is the definitive marker, not file content or naming
+4. **Comments may also be lost** — the recovered file might have lost some original comments (see `references/comment-restoration-from-original.md`)
+
+## Prevention (Better Than Recovery)
+The existing skill already covers this, but worth repeating: **改前必备份** — before modifying any file with third-party tracked changes, save a timestamped backup:
+```bash
+cp file_with_third_party.docx file_with_third_party.bak_$(date +%Y%m%d_%H%M%S).docx
+```

skills/legal/contract-editor/references/table-cell-format-preservation.md

@@ -0,0 +1,69 @@
+# 表格单元格编辑：保持格式不被破坏
+
+## 问题
+
+编辑 docx 表格单元格中的文字时，两种常见错误做法都会破坏格式：
+
+1. **`cell.paragraphs[0].clear()` + `add_run()`**：把多段结构压成一段，丢失加粗、字号、字体
+2. **XML 层全 cell 文字重分片**：把修改后的文字均匀分配到所有 `w:t` 元素，破坏段落边界和编号
+
+## 正确做法：段落级精确定位 + 只改目标段
+
+```python
+from docx import Document
+from docx.shared import Pt
+
+doc = Document('file.docx')
+table = doc.tables[0]
+cell = table.rows[7].cells[1]
+
+# 1. 定位目标段落（按索引）
+paras = cell.paragraphs
+target_p = paras[4]  # 例如 P4 是你要改的段落
+
+# 2. 保存首 run 格式
+first_run = target_p.runs[0]
+saved = {
+    'name': first_run.font.name,
+    'size': first_run.font.size,
+    'bold': first_run.font.bold,
+    'italic': first_run.font.italic,
+}
+
+# 3. 文字替换
+old_text = target_p.text
+new_text = old_text.replace('要被替换的文字', '新文字')
+
+# 4. 清空该段 → 重写（保留格式）
+target_p.clear()
+run = target_p.add_run(new_text)
+run.font.name = saved['name']
+run.font.size = saved['size']
+run.font.bold = saved['bold']
+run.font.italic = saved['italic']
+
+# 5. 合并单元格：同步更新同行其他 cell
+for col_idx in [2, 3]:
+    cell2 = table.rows[7].cells[col_idx]
+    p = cell2.paragraphs[4]
+    p.clear()
+    run = p.add_run(new_text)
+    run.font.name = saved['name']
+    run.font.size = saved['size']
+
+doc.save('output.docx')
+```
+
+## 关键原则
+
+- **不碰其他段落**：只改目标索引的段落，其余段落原封不动
+- **不压多段为一段**：每个段落独立处理，保持 `P0/P1/P2/P3/P4` 结构不变
+- **合并单元格全同步**：`row[7].cells[1]` 改了什么，`cells[2]`、`cells[3]` 也要同步
+- **先读后改**：改前用 `cell.paragraphs[i].text` 确认内容，用 `cell.paragraphs[i].runs[0].font` 确认格式
+
+## 本次教训
+
+2026-06-26 预算绩效分析表：两轮都搞坏格式。
+- 第一轮：`clear()` + `add_run()` 把 Row 7 的 P0-P10 多段结构压成一段
+- 第二轮：XML 全 cell 文字重分片把 "2.成本核算分析" 变成 ".成本核算分析"（编号丢失）
+- 第三轮（正确）：定位到 P4（成本优化段），只改它，保留 P0-P3 不动

skills/legal/contract-editor/references/tracked-replace-del-element-break.md

@@ -0,0 +1,65 @@
+# tracked_replace 被 DEL 元素打断（2026-06-26 CT维保合同-香花桥实证）
+
+## 症状
+
+`tracked_replace(old, new)` 对跨 DEL 元素的文本静默失败（不报错但也不修改）。
+
+## 根因
+
+当匹配文本被拆成多个 run，且中间夹着 `<w:del>` 元素时，`tracked_replace` 无法跨元素边界匹配完整字符串。
+
+## 实证
+
+**场景**：原文"一 年"（中间有空格），需改为"一年"。
+
+实际 XML 结构：
+```xml
+<w:r><w:t>一</w:t></w:r>
+<w:del><w:r><w:delText> </w:delText></w:r></w:del>
+<w:r><w:t>年</w:t></w:r>
+```
+
+`tracked_replace("一 年", "一年")` 无法匹配（"一 年" 不连续存在于任何单一 run 中）。
+
+## 修法
+
+直接 zipfile+lxml 操作，移除 DEL 元素：
+
+```python
+for elem in list(paragraph):
+    if elem.tag.split('}')[-1] == 'del':
+        for t in elem.iter():
+            if t.tag == f'{{{W}}}delText' and t.text == ' ':
+                paragraph.remove(elem)
+                break
+```
+
+## 同类变体：INS 需插入在 DEL 之后
+
+**场景**：原文"与济损失"（"与"为错字），上一轮已将"与"包进 DEL，但未补 INS "经"。
+
+实际 XML 结构：
+```xml
+<w:del><w:r><w:delText>与</w:delText></w:r></w:del>
+<w:r><w:t>济损失的...</w:t></w:r>
+```
+
+`tracked_replace("与济损失", "经济损失")` 静默失败（"与"在 DEL 内）。
+
+**修法**：zipfile+lxml 在 DEL 元素后插入 INS：
+```python
+ins = etree.SubElement(paragraph, f'{{{W}}}ins')
+ins.set(f'{{{W}}}id', str(new_id))
+ins.set(f'{{{W}}}author', 'WB')
+ins.set(f'{{{W}}}date', date_str)
+del_elem.addnext(ins)  # INS 紧跟在 DEL 之后
+
+r = etree.SubElement(ins, f'{{{W}}}r')
+r.append(copy.deepcopy(ref_rPr))  # 从同级 run 克隆 rPr
+t = etree.SubElement(r, f'{{{W}}}t')
+t.text = '经'
+```
+
+## 判别
+
+改前先遍历目标段落子元素，看是否有 `w:del` 或 `w:ins` 元素分割了匹配文本。有则不用 `tracked_replace`，改用 zipfile+lxml 直接操作。

skills/legal/contract-editor/references/tracked-replace-spanning-wins.md

@@ -0,0 +1,127 @@
+# tracked_replace 跨 w:ins 元素失败的处理
+
+## 症状
+
+`tracked_replace(old, new)` 抛出 `ValueError: Element is not a child of this node`，
+发生在 `contract_docx_lib.py` 第368行 `parent.remove(runs[idx])`。
+
+## 根因
+
+合同已经过上一轮 workflow 修订，原文段落中插入了 `w:ins(author="WB")` 元素。
+目标匹配文本跨越了 `w:r` 和 `w:ins` 边界：
+
+```
+w:r:  "...若甲方在双"
+w:ins(author="WB"): "方"
+w:r:  "核对消费金额时未提出异议的..."
+```
+
+`tracked_replace` 把 `w:r` 和 `w:ins` 下的 `w:r` 都收集到 `runs` 列表，
+但 `parent.remove(runs[idx])` 时，`w:ins` 内的 `w:r` 的 parent 是 `w:ins`，不是 `w:p` → 报错。
+
+## 判别
+
+修改前先遍历目标段落的子元素，看是否有 `w:ins` 分割了匹配文本：
+
+```python
+for elem in paragraph:
+    tag = elem.tag.split('}')[-1]
+    if tag in ('r', 'ins', 'del'):
+        print(f"  {tag}: '{''.join(t.text or '' for t in elem.findall('.//{W}t'))}'")
+```
+
+## 修法：zipfile+lxml 直接操作
+
+不用 `tracked_replace`，改用 zipfile+lxml 四步操作：
+
+### 步骤1：裁掉第一段 run 中跨越的部分
+
+```python
+# 如：w:r 末尾是 "...核对确认，若甲方在双" → 裁掉 "若甲方在双"
+assert r1_t.text.endswith('若甲方在双')
+r1_t.text = r1_t.text[:-6]  # 移除6个字符
+```
+
+### 步骤2：创建 DEL 包裹被裁掉的文字
+
+```python
+del_elem = etree.Element(qn('del'))
+del_elem.set(qn('id'), str(next_del_id))
+del_elem.set(qn('author'), 'WB')
+del_elem.set(qn('date'), revision_date)
+
+del_run = etree.SubElement(del_elem, qn('r'))
+del_rpr = etree.SubElement(del_run, qn('rPr'))
+# 从被裁 run 复制 rPr
+for child in r1_elem.find(qn('rPr')):
+    del_rpr.append(copy.deepcopy(child))
+del_text = etree.SubElement(del_run, qn('delText'))
+del_text.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+del_text.text = '若甲方在双方'  # 被裁文字 + w:ins 内容
+```
+
+### 步骤3：移除原来的 w:ins 元素
+
+```python
+p.remove(ins_elem)
+```
+
+### 步骤4：DEL旧文字 + INS新文字
+
+```python
+# DEL 旧文字（第三段 run 的完整内容）
+del_elem2 = ...  # 同上模式，delText = r3_t.text
+# INS 新文字
+ins_elem = etree.Element(qn('ins'))
+ins_elem.set(qn('id'), str(next_ins_id))
+ins_elem.set(qn('author'), 'WB')
+ins_elem.set(qn('date'), revision_date)
+ins_run = etree.SubElement(ins_elem, qn('r'))
+# 从原 run 复制 rPr
+ins_rpr = etree.SubElement(ins_run, qn('rPr'))
+for child in r3_elem.find(qn('rPr')):
+    ins_rpr.append(copy.deepcopy(child))
+ins_t = etree.SubElement(ins_run, qn('t'))
+ins_t.set('{http://www.w3.org/XML/1998/namespace}space', 'preserve')
+ins_t.text = new_text
+
+# 替换：在 r3 位置前插入 DEL 和 INS，再删除 r3
+r3_pos = list(p).index(r3_elem)
+p.insert(r3_pos, del_elem2)
+p.insert(r3_pos + 1, ins_elem)
+p.remove(r3_elem)
+```
+
+### 步骤5：写回
+
+```python
+doc_xml_modified = etree.tostring(tree, encoding='UTF-8', xml_declaration=True)
+with zipfile.ZipFile(src, 'r') as zf:
+    file_data = {f: zf.read(f) for f in zf.namelist()}
+with zipfile.ZipFile(src, 'w', zipfile.ZIP_DEFLATED) as zf:
+    for f, data in file_data.items():
+        zf.writestr(f, doc_xml_modified if f == 'word/document.xml' else data)
+```
+
+## 易错点
+
+### 1. 中文切片长度
+`[:-3]` 移除3个**字符**（不是字节）。"但本" = 2个中文字符 → 用 `[:-2]`。
+用 `[:-3]` 会多切一个字（如把"；"也切掉）。
+
+**⚠️ 全角标点也是1个字符（2026-06-26 健康积分兑换协议教训）**：`（四）` 是3个字符——`（`（U+FF08全角左括号=1字）、`四`（1字）、`）`（U+FF09全角右括号=1字）。用 `[4:]` 切片会多切掉1个中文字符，导致 DEL 文本缺字（"甲方"→"方"）。**判别**：数切片偏移时，全角括号/标点（（）、【】、《》、。，！？等）每符1字，不因"看起来宽"就计为多个。切片前 `print(repr(text[:10]))` 确认边界。
+
+### 2. 旧文末尾与新文开头重复
+原文 run 裁掉部分后，末尾可能与 INS 新文字开头重复。
+如：原文末尾是"核对确认"，新文字开头也是"核对确认" → 出现"核对确认核对确认"。
+**修法**：从 INS 新文字中去掉重复前缀。
+
+### 3. 标点符号归属
+裁掉 run 末尾文字时，确保标点符号（；。等）留在正确位置。
+如原文"费用；但本"裁掉"但本"后应为"费用；"（保留分号）。
+
+## 验证
+
+1. `python-docx` 能打开（`Document(out)` 不抛异常）
+2. `wb-ins-font-verify.py` 所有 WB INS 字体一致
+3. 用 `ContractEditor.get_para_text()` 读段落文本，确认无重复/缺字

skills/legal/contract-editor/references/transplant-revisions-to-variant-contract.md

@@ -0,0 +1,67 @@
+# 移植workflow修订到同名不同版本合同 (2026-07-08)
+
+## 场景
+邱律师同日发了两份同名文件（如"2026年华新镇公立中小学生健康体检服务合同.docx"），内容有实质差异（不同版本/条款）。第一份被workflow正常审查交付，第二份因queue-runner同名跳过逻辑被遗漏。Doro要求"把workflow第1份的修订内容直接修订到第2份里，但要注意相关修订在第2份里是否合理"。
+
+## 操作步骤
+
+### 1. 提取第1份的WB修订清单
+从已交付文件提取所有 `author=WB` 的 `w:ins` 和 `w:del`：
+```python
+from zipfile import ZipFile
+from lxml import etree
+
+with ZipFile(delivered_path, 'r') as z:
+    content = z.read('word/document.xml').decode('utf-8')
+root = etree.fromstring(content.encode('utf-8'))
+# 遍历所有 WB INS/DEL，记录：段落索引、INS文本、DEL文本、上下文
+```
+
+### 2. 对比两份合同差异
+用 `difflib` 对比两版全文，定位哪些段落内容不同。特别关注：
+- 修订涉及的段落在第2份中是否存在
+- 如果存在，文本是否与第1份中的"修订前"文本一致
+
+### 3. 逐条判断修订是否适用于第2份
+| 修订类型 | 判断方法 |
+|---------|---------|
+| 术语统一（如"协议"→"合同"） | 在第2份中搜索同一术语，存在则同样修改 |
+| 新增保护条款（如数据归属、转包连带责任） | 检查第2份对应位置是否缺同样的保护，缺则加 |
+| 金额/支付相关修订 | 第2份的支付条款可能完全不同（如本案），需独立判断是否需要新的修订 |
+| 合同期限相关修订 | 第2份期限可能不同，独立判断 |
+
+### 4. 对第2份执行修订
+使用ContractEditor库，与正常审查相同流程：
+```python
+ed = ContractEditor(second_file)
+ed.tracked_replace(old, new)  # 逐条适用的修订
+errors = ed.validate()
+ed.save(output)
+```
+
+### 5. 字体验证 + 上传
+- `wb-ins-font-verify.py` 必须PASS
+- 上传替换NC任务交付目录中的同名文件
+- 同时确保第2份原始文件在待审查目录
+
+## 2026-07-08 华新镇体检合同实证
+
+**两版差异：**
+| 条款 | 第1份 (11:05) | 第2份 (16:04) |
+|------|--------------|--------------|
+| 项目内容 | "公立中小学生健康检查工作" | "华新镇公立中小学生健康体检工作" |
+| 支付方式 | 按实际人数结算，无金额上限 | 按实际完成人数+考核表结算，费用上限17万 |
+| 合同期限 | 9月10日起 | 9月1日起 |
+
+**移植的修订（全部适用）：**
+1. 保密条款：数据归属+合同期满扩大+协议→合同统一 ✅ 第2份保密条款内容相同
+2. 转包限制：增加甲方书面同意+连带责任 ✅ 第2份P44文本相同
+3. 效力条款：本协议→本合同 ✅ 第2份P51文本相同
+
+**不需要额外修订的原因：**
+- 第2份的支付条款已更完善（有上限、有考核、有一次性付清约定）
+- 违约责任、争议解决条款相同且已足够
+
+## 注意事项
+- 第2份被上传后会**替换**第1份的交付文件（同名），tracker中seq=262的记录对应的实际内容变了
+- hint mismatch 在 tracked_replace 生成的长INS文本中常见（库不自动加hint到多段INS），需post-fix

skills/legal/contract-editor/references/version-management-antipatterns.md

@@ -0,0 +1,59 @@
+# 版本管理反模式（2026-07-01 反委托代发工资协议惨痛教训）
+
+## 事件回顾
+
+反委托代发工资协议需要制作两个版本（法定安排 vs 反委托保护），同时保留华诚-Z的修订痕迹。
+
+### 灾难链条
+
+1. 原始文件有华诚-Z的修订（author="华诚-Z"）+ 批注
+2. 我制作WB版本时，把所有author改成了WB
+3. 又做了一版合并版本，再次覆盖
+4. 之后Doro说"你把华诚-Z修订痕迹的版本放进去"
+5. 发现/tmp里所有文件都只有WB作为author
+6. Nextcloud版本历史也没有（只保留了一个.v文件，也是WB）
+7. 最终在 `/tmp/v1_doro_updated.docx` 找到——这是一个中间版本，纯属侥幸
+
+### 反模式清单
+
+| 反模式 | 后果 |
+|--------|------|
+| 修改author前不备份 | 原始修订痕迹不可逆丢失 |
+| 覆盖式保存（同文件名） | 中间版本消失 |
+| 从头重做而非增量修补 | 每次重做都覆盖上一版 |
+| 不验证就交付 | 批注丢了3条没发现 |
+| 多轮操作共用/tmp目录 | 后续操作的文件名与前面冲突 |
+
+### 正确做法
+
+```python
+import shutil
+from datetime import datetime
+
+# 操作前备份
+timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+shutil.copy(source, f"{source}.bak_{timestamp}")
+
+# 操作后验证
+import zipfile, re
+z = zipfile.ZipFile(output)
+content = z.read('word/document.xml').decode('utf-8')
+authors = set(re.findall(r'w:author="([^"]+)"', content))
+assert '华诚-Z' in authors, "华诚-Z author LOST!"
+
+# 批注验证
+if 'word/comments.xml' in z.namelist():
+    comments_xml = z.read('word/comments.xml').decode('utf-8')
+    comment_count = len(re.findall(r'<w:comment ', comments_xml))
+    assert comment_count >= expected_count, f"Comments lost: {comment_count} < {expected_count}"
+```
+
+### 文件命名规范（防覆盖）
+
+不要用 `_v2.docx` `_v3.docx` 这种递增命名——容易忘记当前版本是几。用语义+时间戳：
+
+```
+反委托_华诚Z原版_20260701_0320.docx    # 带华诚-Z修订的版本
+反委托_WB合并版_20260701_0341.docx     # WB+华诚-Z合并后
+反委托_V1法定安排_FINAL_20260701.docx   # 最终交付
+```

skills/legal/contract-editor/references/wb-ins-renumber-collision.md

@@ -0,0 +1,56 @@
+# WB自加手动编号与前序自动编号撞号 — 诊断与修复
+
+实战来源：端午节福利品采购合同（2026-06-16）。Maggie："转包责任应该是7，上一个编号是6。手动修复上传。"
+
+## 场景识别
+- 我们(WB)用 `w:ins` 新增了若干尾部条款（转包/违约/争议…），编号是**手动文字**写在 run 文本开头（"6、转包限制…"）。
+- 紧邻的前一条是**原文自带的自动编号**条款（pPr 有 `<w:numPr>`，编号由 numbering.xml 的 `<w:start>` 生成，文字里**没有**编号）。
+- 二者渲染数字撞号：自动编号末值=6，我方手动也从6起 → 接受修订后出现两个6。
+
+## 诊断步骤（顺序不可颠倒，OnlyOffice为准）
+1. 取交付版(任务交付/【修】…docx)+原文(待审查/…doc)，各用 `scripts/onlyoffice-render.sh` 渲染 PDF。
+2. `pdftotext -layout x.pdf - | grep -E "^\s*\f?[0-9]+、"` 数出**完整可见编号链**（注意"5、结算"可能挤在第4条段内、自动编号条款文字里无编号——肉眼易漏）。
+3. 读 numbering.xml 确认前序自动条款的 numId→abstractNumId→lvl0 的 `start` 值，得知它渲染成几（端午节：numId=3, start=6 →"6"）。
+4. 读 document.xml，确认我方各条是 `w:ins author=WB`，编号"6、""7、""8、"在 ins 首个 w:r 的 w:t 开头。
+
+## 判定
+前序自动编号末值 = N → 我方手动编号应从 **N+1** 起顺延。端午节：售后=6 → 转包=7、违约=8、争议=9。
+**有Maggie明确指示 + 完整核对 → 执行。** 不要因"擅改编号"的旧教训而拒绝正确修复（区别在：当初错在没核对没确认，不在方向）。
+
+## 修复（纯 zipfile+lxml，最干净）
+只改 ins 首个 w:t 的编号前缀，不拆 run、不碰 rPr、不转 numbering：
+
+```python
+import zipfile, os
+from lxml import etree
+W = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+src='deliver.docx'; out='deliver_FIXED.docx'
+root = etree.fromstring(zipfile.ZipFile(src).read('word/document.xml'))
+paras = root.find(f'{W}body').findall(f'{W}p')
+changes = {19:('6、','7、','转包'), 20:('7、','8、','违约'), 21:('8、','9、','争议')}  # 段索引→(旧号,新号,关键词)
+for idx,(old,new,kw) in changes.items():
+    ins = paras[idx].find(f'{W}ins')
+    assert ins is not None and ins.get(f'{W}author')=='WB', f"段{idx}非WB的ins!"   # 铁律：绝不改他人ins
+    t = ins.find(f'{W}r').find(f'{W}t')
+    assert t.text.startswith(old) and kw in t.text[:6]
+    t.text = new + t.text[len(old):]
+new_doc = etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True)
+tmp=out+'.tmp'
+with zipfile.ZipFile(src) as zin, zipfile.ZipFile(tmp,'w',zipfile.ZIP_DEFLATED) as zout:
+    for it in zin.infolist():
+        zout.writestr(it, new_doc if it.filename=='word/document.xml' else zin.read(it.filename))
+os.replace(tmp,out)
+```
+
+## 交付前四查（vision不可用时的强制验证，缺一不可）
+1. **逐段markup diff vs交付源**：提取两版每个 w:p 的 markup 文本（含 delText），断言**只有目标N段不同**、其余全部零改动（端午节33段只动3段）。
+2. **OnlyOffice渲染PDF编号链**：pdftotext 数出 1,2,3,4,(5),6,7,8,9 连续无双号。
+3. **INS run rPr 改前==改后**：`etree.tostring(rpr)` 逐段比对，确认字体/字号一字未动。
+4. **python-docx 能打开** + 接受修订后（去 del、解包 ins）编号链连续，证明 XML 合法、WB 修订标记完整保留。
+
+## 交付（Editor到此为止则交deliverer；本例Maggie直接要"上传"故一并做）
+- 文件名**一字不动**：覆盖 `Doro合同审查任务/任务交付/【修】<原名>.docx`。
+- `docker cp` 进 nextcloud-nextcloud-1 → `chown www-data` → `occ files:scan --path=...`。
+- 落盘 md5 == 修复版 md5 才算成功。
+- 清 OnlyOffice 缓存：`docker exec nextcloud-onlyoffice-1 rm -rf .../App_Data/cache/files/*`。
+- 已 pass 登记过的合同仅编号订正：tracker/xlsx 记录不变动。

skills/legal/contract-editor/references/workflow-font-contamination-repair.md

@@ -0,0 +1,127 @@
+# ContractEditor 原文Run属性污染诊断与修复
+
+## 2026-07-13 洋励合同实证
+
+### 问题描述
+
+ContractEditor（contract_docx_lib.py）在处理文档时，不仅给WB INS runs添加多余属性，还会**修改原文runs**的rPr——给本来靠docDefaults/style继承的orig runs添加显式eastAsia/cs/sz。
+
+### 典型污染模式
+
+| 属性 | 原文（待审查） | 被污染后（交付物中的orig run） | WB INS run |
+|------|--------------|-------------------------------|-----------|
+| eastAsia | None (继承minorEastAsia) | **宋体** (被加) | None |
+| cs | None | **宋体** (被加) | None |
+| sz | None (继承docDefaults=22) | **21** (被加且值错) | None |
+| ascii | 宋体 | 宋体 | None |
+| hint | eastAsia (部分有) | eastAsia | None |
+
+### 后果
+
+1. 原文所有文字从11pt(docDefaults sz=22)变成10.5pt(显式sz=21) — 整体缩小0.5pt
+2. INS文字没有任何属性 → 走docDefaults 11pt → 与被改小的原文不一致
+3. 字体验证脚本(wb-ins-font-verify.py)报INS缺属性，但实际问题是orig被污染
+
+### 诊断步骤
+
+```bash
+# 1. 读原文代表性段落run rPr
+python3 -c "
+import zipfile
+from lxml import etree
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+with zipfile.ZipFile('原文.docx', 'r') as z:
+    ...
+# 检查: eastAsia=None? sz=None? 
+# 如果是 → 原文靠继承
+
+# 2. 读交付物同段落orig run rPr
+# 检查: 是否多了eastAsia/cs/sz?
+# 如果是 → 被污染
+```
+
+### 修复代码模板
+
+```python
+import zipfile, tempfile, shutil
+from lxml import etree
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+with zipfile.ZipFile(filepath, 'r') as z:
+    all_files = {n: z.read(n) for n in z.namelist()}
+
+tree = etree.fromstring(all_files['word/document.xml'])
+body = tree.find(f'{WNS}body')
+
+# Step 1: Strip contaminated attributes from ALL orig runs
+for p in body.findall(f'{WNS}p'):
+    for r in p.findall(f'{WNS}r'):  # Only direct child runs (not inside ins/del)
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is None:
+            continue
+        rf = rpr.find(f'{WNS}rFonts')
+        if rf is not None:
+            # Strip eastAsia (original didn't have it)
+            if f'{WNS}eastAsia' in rf.attrib:
+                del rf.attrib[f'{WNS}eastAsia']
+            # Strip cs (original didn't have it)
+            if f'{WNS}cs' in rf.attrib:
+                del rf.attrib[f'{WNS}cs']
+        # Strip sz (original relies on docDefaults)
+        sz = rpr.find(f'{WNS}sz')
+        if sz is not None:
+            rpr.remove(sz)
+
+# Step 2: Fix INS runs to match REAL original format
+for ins in body.findall(f'.//{WNS}ins'):
+    if ins.get(f'{WNS}author') != 'WB':
+        continue
+    for r in ins.findall(f'{WNS}r'):
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is None:
+            continue
+        rf = rpr.find(f'{WNS}rFonts')
+        if rf is None:
+            rf = etree.SubElement(rpr, f'{WNS}rFonts')
+        # Match real original: ascii=宋体, hAnsi=宋体, NO eastAsia
+        rf.set(f'{WNS}ascii', '宋体')
+        rf.set(f'{WNS}hAnsi', '宋体')
+        if f'{WNS}eastAsia' in rf.attrib:
+            del rf.attrib[f'{WNS}eastAsia']
+        # Remove sz (let it inherit)
+        sz = rpr.find(f'{WNS}sz')
+        if sz is not None:
+            rpr.remove(sz)
+
+# Step 3: Per-paragraph hint matching
+for p in body.findall(f'{WNS}p'):
+    # Get orig run's hint
+    orig_hint = None
+    for r in p.findall(f'{WNS}r'):
+        rpr = r.find(f'{WNS}rPr')
+        if rpr is not None:
+            rf = rpr.find(f'{WNS}rFonts')
+            orig_hint = rf.get(f'{WNS}hint') if rf is not None else None
+        break
+    # Apply to INS runs in same paragraph
+    for ins in p.findall(f'.//{WNS}ins'):
+        if ins.get(f'{WNS}author') != 'WB':
+            continue
+        for r in ins.findall(f'{WNS}r'):
+            rpr = r.find(f'{WNS}rPr')
+            if rpr is None: continue
+            rf = rpr.find(f'{WNS}rFonts')
+            if rf is None: continue
+            if orig_hint:
+                rf.set(f'{WNS}hint', orig_hint)
+            elif f'{WNS}hint' in rf.attrib:
+                del rf.attrib[f'{WNS}hint']
+```
+
+### 注意事项
+
+1. **必须对比原文确定被污染了哪些属性** — 不同合同模板的原文属性不同
+2. **不是所有合同都有此问题** — 取决于原文是否靠继承（有显式属性的不会被"污染"，因为值相同）
+3. **Step 1必须在Step 2之前** — 否则wb-ins-font-verify仍会报INS与(被污染的)orig不一致
+4. **hint要逐段处理** — 同一文档不同段落的orig runs可能有的有hint有的没有

skills/legal/contract-editor/references/workflow-ins-format-repair.md

@@ -0,0 +1,70 @@
+# Workflow INS Format Repair — ContractEditor Font Contamination Pattern
+
+## 2026-07-13 洋励/安全生产/消防设施检测 连续验证
+
+### 问题根因
+
+ContractEditor库在处理文档时会**污染原文runs**——给原本没有显式属性的runs添加`eastAsia`、`cs`、`sz`。
+
+典型对比：
+```
+原文(待审查):  rFonts={ascii=宋体, hAnsi=宋体, hint=eastAsia}, szCs=21, NO sz, NO eastAsia
+v1中orig runs: rFonts={ascii=宋体, hAnsi=宋体, hint=eastAsia, cs=宋体, eastAsia=宋体}, szCs=21, sz=21
+v1中WB INS:    rPr=空 (什么属性都没有)
+```
+
+**后果**：
+1. 原文字号从继承docDefaults(如sz=22=11pt)变为显式sz=21(10.5pt)——整体缩小0.5pt
+2. INS runs无属性→走docDefaults继承→11pt，与被改小的orig runs(10.5pt)不一致
+3. wb-ins-font-verify报"orig=宋体/21 wb=None"——但这个"orig"已被污染，不是真实原文
+
+### 诊断铁律
+
+**永远对比待审查目录的原文，不信v1中的orig runs**：
+
+```python
+# 对比同一段落的run属性
+for label, path in [('待审查原文', orig_path), ('交付v1', v1_path)]:
+    # 读P4 first run rPr的所有子元素
+    # 如果v1比原文多了eastAsia/cs/sz → 被污染
+```
+
+### 修复方法（三步）
+
+**Step 1：清除orig runs的污染属性**
+```python
+for r in p.findall(f'{WNS}r'):  # 只处理原文runs（不在ins/del内的）
+    rpr = r.find(f'{WNS}rPr')
+    rf = rpr.find(f'{WNS}rFonts')
+    if rf is not None:
+        # 如果原文没有eastAsia，strip之
+        if f'{WNS}eastAsia' in rf.attrib:
+            del rf.attrib[f'{WNS}eastAsia']
+        if f'{WNS}cs' in rf.attrib:
+            del rf.attrib[f'{WNS}cs']
+    # 如果原文没有sz（靠继承），strip之
+    sz = rpr.find(f'{WNS}sz')
+    if sz is not None:
+        rpr.remove(sz)
+```
+
+**Step 2：设INS runs匹配真实原文**
+```python
+for ins in p.findall(f'.//{WNS}ins'):
+    if ins.get(f'{WNS}author') != 'WB': continue
+    for r in ins.findall(f'{WNS}r'):
+        rf = rpr.find(f'{WNS}rFonts')
+        # 设置为原文实际有的属性（如ascii=宋体, hAnsi=宋体）
+        # 不设原文没有的（如eastAsia, cs）
+        # hint按同段orig run的值设
+```
+
+**Step 3：逐段匹配hint**
+不同段落的orig runs hint状态不同（有的有hint=eastAsia，有的没有）。必须逐段检查并匹配。
+
+### 注意事项
+
+- **不能一刀切**：同一文档不同段落的orig run属性可能不同（P4有hint, P19没hint; P20有完整rFonts, P36完全没rFonts）
+- **docDefaults是真正的参考基准**：检查`word/styles.xml`的`docDefaults/rPrDefault`了解继承值
+- **"MISSING HINT (无同段原文可比)"是已知限制**：整段WB INS的新增段落没有orig run对比，脚本报MISSING不是真实错误
+- **洋励案实证**：120处orig runs被污染，修复后INS只剩14个MISSING HINT（全是新增段落）

skills/legal/contract-editor/references/workflow-output-audit-checklist.md

@@ -0,0 +1,92 @@
+# Workflow交付件逐份审查检查清单 (2026-07-13 Doro要求)
+
+## 触发条件
+Doro说"逐一审查已交付合同的修订有哪些问题"或类似指令。
+
+## 操作流程
+1. 全文阅读通用review-rules.md + 对应顾问单位特殊规则
+2. 列出今天交付的全部文件（`sudo find ... -newermt`）
+3. 一份一份审查，报告问题，等Doro说pass再做下一份
+
+## 每份检查项
+
+### A0. 文件完整性（先于内容）
+- `zipfile`读`word/comments.xml`看有无批注
+- 统计`w:ins`/`w:del`数量确认有修订痕迹
+- 如果有多版本（v1/v2），每个都要独立检查性质
+
+### A. 格式验证
+- `wb-ins-font-verify.py` — 必须PASS
+- 原文同段run属性 vs INS run属性逐一比对
+- 新增段落pPr（ind/spacing/numPr）vs原文邻近段落
+
+### B. 审查清单覆盖（10条逐条）
+1. 主体条款
+2. 违约责任（含赔偿上限删除、维权费用）
+3. 争议解决/管辖（甲方所在地法院）
+4. 保密/数据（归属+存续+泄露赔偿 三要素）
+5. 知识产权/系统
+6. 第三方侵权（全责+赔偿甲方损失）
+7. 转包/分包（限制+连带）
+8. 价款条款
+9. 服务成果持续使用权（仅持续性服务适用）
+10. 条款逻辑
+
+### C. 同模板一致性
+- 同批同模板合同的修订是否完全统一
+- 特别检查：编号顺延方式、章节结构、措辞、天数
+
+### D. 特殊交付物
+- 读该顾问单位review-rules.md确认是否要求审查意见文档
+- 缺失则标记
+
+### E. 批注审查
+- 每条WB批注逐一比对规则
+- 立场是否正确（站甲方）
+- 是否违反"能改就不批注"
+- 是否属于提醒性批注（禁止）
+
+## 报告格式
+```
+## 【修】合同名称
+
+**字体验证：** PASS/FAIL
+**修订内容：** 逐条列出WB INS/DEL
+**问题：**
+1. [严重/一般] 具体问题描述
+2. ...
+**结论：** pass建议/需修复
+```
+
+### F. 编号顺延完整性（2026-07-13 璞石合同教训）
+- 章节标题编号顺延后（如七→八），**子编号也必须顺延**（7.1→8.1, 7.2→8.2...）
+- Workflow常见遗漏：只改了章节标题的汉字编号（第七条→第八条），但内部子条款的阿拉伯数字编号（7.1/7.2/7.3/7.4）原封不动
+- **检查方法**：accepted text中搜索所有"X.Y"格式编号，确认X与所属章节标题的序号一致
+- 修复方法：子编号通常拆为两个run（如"7" + ".1  "），只需DEL第一个run("7")+INS新数字("8")
+
+### G. 内容去重（2026-07-13 璞石合同教训）
+- 新增的保密存续条款是否与原文已有的类似表述重复
+- 典型：原文已有"乙方的保密义务不因合同解除或终止而免除"，WB又插入"本条保密义务不因本合同的终止或解除而终止"——语义完全重复
+
+### H. 赔偿上限全面检查（2026-07-13 璞石合同教训）
+- 规则"赔偿上限能删就删"不仅适用于乙方赔偿甲方的上限
+- **双向条款中的上限也要删**：如"任何一方违约，违约金额为合同总金额的20%"——此上限同时限制了甲方可获赔偿
+- P43甲方自身违约金上限保留是正确的（保护甲方），但P49双向上限应删除
+- **判断方法**：上限是否限制了对方向甲方赔偿？是→删；上限是否限制了甲方向对方赔偿？是→保留
+
+### I. 新增标题段落样式（2026-07-13 璞石合同教训）
+- WB新增的章节标题段（如"第七条 转包与分包"）的pStyle必须与原文标题段一致
+- 原文标题用Heading4→新增也用Heading4，不能用Style15（正文首行缩进）
+- 标题文字中"第X条"与名称之间是否有空格？原文无空格（"第六条违约责任"）则新增也不加空格
+
+### J. 原文已有修订保持不动
+- 对照原文确认：WB-1/86187/杨丽/富强等原文修订人的INS/DEL/批注是否全部原样保留
+- WB的修改不能意外覆盖或嵌套进原文修订
+- P29金额"27900"的sz=22是原文86187的修订→不是workflow问题
+
+## 铁律
+- 先tool call读文件再下结论（验证指令铁律）
+- 不凭上一份的印象判断下一份
+- comments.xml必须检查（2026-07-13教训）
+- **原文自带【修】前缀的文件**：按命名规则应为【修】【修】...，workflow通常不做双重前缀——记录为已知缺陷
+- **Doro说"看清楚前后文再回复"**：意思是你漏了问题或误判了严重性，必须重新逐属性检查

skills/legal/contract-editor/scripts/accept-revisions-preview.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""生成"接受所有修订后"的干净 docx，用于 OnlyOffice 渲染做字体/排版的决定性视觉验证。
+
+为什么需要：OnlyOffice 渲染修订态文字（w:ins，紫色+下划线）时视觉上常显示为类无衬线、
+看起来字体/粗细与正文不同——这是 track-changes 的渲染特性，不是真实字体差异。vision 工具
+会据此误报"字体不一致"，导致无谓返工。把所有修订接受、批注去掉后再渲染，才能在无修订
+颜色干扰下看到插入文字与正文的真实字体一致性。
+
+用法: python accept-revisions-preview.py <in.docx> <out.docx>
+处理: 解包所有 w:ins（保留内容）+ 删除所有 w:del（连内容）+ 移除批注锚点标记。
+注意: 产物仅供"渲染核对"，不是正式交付物（交付的是带修订痕迹的版本）。
+"""
+import sys, zipfile, io
+from lxml import etree
+
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+Wq = '{' + W + '}'
+
+
+def accept_revisions(in_path, out_path):
+    with open(in_path, 'rb') as f:
+        data = f.read()
+    bin_, bout = io.BytesIO(data), io.BytesIO()
+    with zipfile.ZipFile(bin_) as zin, zipfile.ZipFile(bout, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.infolist():
+            raw = zin.read(item.filename)
+            if item.filename == 'word/document.xml':
+                root = etree.fromstring(raw)
+                # 删除所有 w:del（含内容）
+                for d in [e for e in root.iter(Wq + 'del')]:
+                    d.getparent().remove(d)
+                # 解包所有 w:ins：把子元素提到 ins 的位置后删除 ins 壳
+                for ins in [e for e in root.iter(Wq + 'ins')]:
+                    parent = ins.getparent()
+                    idx = list(parent).index(ins)
+                    for child in reversed(list(ins)):
+                        parent.insert(idx, child)
+                    parent.remove(ins)
+                # 移除批注锚点标记
+                for tag in ('commentRangeStart', 'commentRangeEnd'):
+                    for e in [x for x in root.iter(Wq + tag)]:
+                        e.getparent().remove(e)
+                for r in [x for x in root.iter(Wq + 'r')]:
+                    if r.find(Wq + 'commentReference') is not None:
+                        r.getparent().remove(r)
+                raw = etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True)
+            zout.writestr(item, raw)
+    with open(out_path, 'wb') as f:
+        f.write(bout.getvalue())
+    print(f'接受修订版已生成: {out_path}')
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 3:
+        print('用法: python accept-revisions-preview.py <in.docx> <out.docx>')
+        sys.exit(1)
+    accept_revisions(sys.argv[1], sys.argv[2])

skills/legal/contract-editor/scripts/contract_docx_lib.py

@@ -0,0 +1,684 @@
+#!/usr/bin/env python3
+"""
+contract_docx_lib.py — 合同修订核心库
+固化验证通过的docx XML操作，不再每次重写。
+
+用法：
+    from contract_docx_lib import ContractEditor
+    
+    editor = ContractEditor("原文件.docx")
+    editor.tracked_replace("原文片段", "新文片段")
+    editor.add_clause("19．服务成果持续使用权", "条款内容...", after_clause=18)
+    editor.renumber(19, 20)  # 原19→20
+    errors = editor.validate()
+    if not errors:
+        editor.save("【修】原文件.docx")
+
+关键操作顺序（renumber和新增条款）：
+    1. 先做所有 tracked_replace（文本修改）
+    2. 再做 add_clause（新增子条款，如15.4）
+    3. 再做 renumber_range（先腾出编号空间）
+    4. 最后做 add_clause_before（插入新主条款，用已腾出的编号）
+    5. validate() 验证
+    6. save() 保存
+"""
+
+import zipfile, io, copy, re, difflib
+from lxml import etree
+from datetime import datetime
+from pathlib import Path
+
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+WP = 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing'
+XML_SPACE = '{http://www.w3.org/XML/1998/namespace}space'
+WNS = '{' + W + '}'
+
+def qn(tag):
+    return f'{WNS}{tag}'
+
+
+def cjk_tokenize(text):
+    """CJK每字一token，ASCII连续一token，标点单独token。
+    经验证的分词策略，不要改。"""
+    tokens = []
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if '\u4e00' <= ch <= '\u9fff' or '\u3000' <= ch <= '\u303f' or ch in '，。、；：！？""''（）【】《》—…·[]％%':
+            tokens.append(ch)
+            i += 1
+        elif ch.isascii() and ch.isalnum():
+            j = i
+            while j < len(text) and text[j].isascii() and text[j].isalnum():
+                j += 1
+            tokens.append(text[i:j])
+            i = j
+        else:
+            tokens.append(ch)
+            i += 1
+    return tokens
+
+
+class ContractEditor:
+    """合同修订编辑器。一个实例对应一份合同文件。"""
+    
+    def __init__(self, filepath):
+        self.filepath = Path(filepath)
+        with open(filepath, 'rb') as f:
+            self.original_bytes = f.read()
+        
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as z:
+            self.doc_xml = z.read('word/document.xml')
+        
+        self.tree = etree.fromstring(self.doc_xml)
+        self.body = self.tree.find(qn('body'))
+        self._rev_id = 100
+        self._revision_date = datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ')
+        self._author = 'WB'
+        self._rsid = '00AA0001'
+        
+        # 提取原文格式（核心：避免每次猜错格式）
+        self._body_rpr = None   # 正文格式（最常见的非加粗rPr）
+        self._title_rpr = None  # 条款标题格式（加粗的rPr）
+        self._body_ppr = None
+        self._extract_formats()
+    
+    def _extract_formats(self):
+        """从原文提取正文和标题的rPr。
+        策略：
+        - 正文格式：统计所有run的rPr，取出现最多的非加粗rPr
+        - 标题格式：优先从条款编号标题段落（如"7.索赔条款"）提取rPr，
+          而非简单取第一个加粗run（可能是合同大标题，字号不同）
+        - 如果条款标题不加粗，标题格式回退到正文格式"""
+        import re
+        rpr_map = {}  # serialized_rpr -> (count, rpr_element)
+        clause_title_rpr = None  # 从条款编号标题提取的格式
+        first_bold_rpr = None    # 第一个加粗run的格式（fallback）
+        
+        for p in self.body.findall(qn('p')):
+            # 获取段落全文，判断是否是条款编号标题（如 "7.索赔条款" "5.伴随服务"）
+            p_text = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}')).strip()
+            is_clause_title = bool(re.match(r'^\d+[．.、]\s*\S', p_text)) and len(p_text) < 30
+            
+            for r in p.findall(qn('r')):
+                rpr = r.find(qn('rPr'))
+                txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if not txt.strip() or len(txt) < 3:
+                    continue
+                
+                if rpr is not None:
+                    is_bold = rpr.find(qn('b')) is not None
+                    key = etree.tostring(rpr, encoding='unicode')
+                    
+                    if is_bold and first_bold_rpr is None:
+                        first_bold_rpr = rpr
+                    
+                    # 优先从条款标题段落提取标题格式
+                    if is_clause_title and clause_title_rpr is None:
+                        clause_title_rpr = rpr
+                    
+                    if not is_bold:
+                        if key not in rpr_map:
+                            rpr_map[key] = [0, rpr]
+                        rpr_map[key][0] += 1
+            
+            if self._body_ppr is None:
+                ppr = p.find(qn('pPr'))
+                txt = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+                if ppr is not None and len(txt) > 20:
+                    self._body_ppr = ppr
+        
+        if rpr_map:
+            best = max(rpr_map.values(), key=lambda x: x[0])
+            self._body_rpr = best[1]
+        
+        # 标题格式优先级：条款编号标题 > 第一个加粗run > 正文格式
+        self._title_rpr = clause_title_rpr or first_bold_rpr or self._body_rpr
+        
+        if self._title_rpr is None and self._body_rpr is not None:
+            self._title_rpr = copy.deepcopy(self._body_rpr)
+            etree.SubElement(self._title_rpr, qn('b'))
+    
+    def _next_id(self):
+        self._rev_id += 1
+        return str(self._rev_id)
+    
+    def _mk_del(self, text, rpr=None):
+        d = etree.Element(qn('del'))
+        d.set(qn('id'), self._next_id())
+        d.set(qn('author'), self._author)
+        d.set(qn('date'), self._revision_date)
+        r = etree.SubElement(d, qn('r'))
+        r.set(qn('rsidDel'), self._rsid)
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('delText'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return d
+    
+    def _mk_ins(self, text, rpr=None):
+        i = etree.Element(qn('ins'))
+        i.set(qn('id'), self._next_id())
+        i.set(qn('author'), self._author)
+        i.set(qn('date'), self._revision_date)
+        r = etree.SubElement(i, qn('r'))
+        r.set(qn('rsidR'), self._rsid)
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('t'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return i
+    
+    def _mk_run(self, text, rpr=None):
+        r = etree.Element(qn('r'))
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('t'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return r
+    
+    def get_para_text(self, p):
+        """获取段落的原始文本（不含删除标记中的文本）"""
+        return ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+    
+    def find_para(self, search_text):
+        """查找包含指定文本的段落"""
+        for p in self.body.findall(qn('p')):
+            if search_text in self.get_para_text(p):
+                return p
+        return None
+    
+    def tracked_replace(self, old_text, new_text):
+        """在整个文档中查找old_text并用修订模式替换为new_text。
+        使用字符级tokenizer+difflib实现精准修订。
+        返回True如果成功。"""
+        for p in self.body.findall(qn('p')):
+            runs = p.findall(f'.//{qn("r")}')
+            if not runs:
+                continue
+            full = ''.join(
+                ''.join(t.text or '' for t in r.findall(qn('t')))
+                for r in runs
+            )
+            if old_text not in full:
+                continue
+            
+            start = full.index(old_text)
+            end = start + len(old_text)
+            
+            # 获取匹配位置的rPr
+            rpr = None
+            pos = 0
+            for r in runs:
+                rt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if pos + len(rt) > start:
+                    rpr = r.find(qn('rPr'))
+                    break
+                pos += len(rt)
+            
+            # 生成diff元素
+            if new_text == '':
+                elems = [self._mk_del(old_text, rpr)]
+            else:
+                ot = cjk_tokenize(old_text)
+                nt = cjk_tokenize(new_text)
+                matcher = difflib.SequenceMatcher(None, ot, nt)
+                elems = []
+                for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+                    if tag == 'equal':
+                        elems.append(self._mk_run(''.join(ot[i1:i2]), rpr))
+                    elif tag == 'delete':
+                        elems.append(self._mk_del(''.join(ot[i1:i2]), rpr))
+                    elif tag == 'insert':
+                        elems.append(self._mk_ins(''.join(nt[j1:j2]), rpr))
+                    elif tag == 'replace':
+                        elems.append(self._mk_del(''.join(ot[i1:i2]), rpr))
+                        elems.append(self._mk_ins(''.join(nt[j1:j2]), rpr))
+            
+            # 定位受影响的runs并替换
+            pos = 0
+            first = last = None
+            prefix_text = suffix_text = ""
+            for idx, r in enumerate(runs):
+                rt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                run_end = pos + len(rt)
+                if run_end > start and pos < end:
+                    if first is None:
+                        first = idx
+                        prefix_text = full[pos:start]
+                    last = idx
+                    suffix_text = full[end:run_end] if run_end > end else ""
+                pos = run_end
+            
+            if first is None:
+                continue
+            
+            ref = runs[first]
+            # Find the actual paragraph (w:p) element to insert into
+            para_elem = p
+            # Determine insert position: find ref or its ancestor that is a direct child of p
+            ref_ancestor = ref
+            while ref_ancestor.getparent() is not para_elem and ref_ancestor.getparent() is not None:
+                ref_ancestor = ref_ancestor.getparent()
+            insert_pos = list(para_elem).index(ref_ancestor)
+            
+            # Remove runs (each from its own parent)
+            for idx in range(last, first - 1, -1):
+                r = runs[idx]
+                r_parent = r.getparent()
+                r_parent.remove(r)
+                # If parent (e.g. w:ins) is now empty, remove it too
+                if r_parent is not para_elem and len(r_parent) == 0:
+                    gp = r_parent.getparent()
+                    if gp is not None:
+                        gp.remove(r_parent)
+            
+            ip = insert_pos
+            if prefix_text:
+                para_elem.insert(ip, self._mk_run(prefix_text, rpr))
+                ip += 1
+            for e in elems:
+                para_elem.insert(ip, e)
+                ip += 1
+            if suffix_text:
+                para_elem.insert(ip, self._mk_run(suffix_text, rpr))
+            
+            return True
+        
+        return False
+    
+    def _get_leading_whitespace(self, para):
+        """从段落中提取前导空格/tab模式。
+        很多中文文档的缩进不是通过w:ind实现的，而是通过文本中的空格字符。"""
+        for r in para.findall(qn('r')):
+            # Skip deleted runs
+            if r.getparent().tag == qn('del'):
+                continue
+            for t in r.findall(qn('t')):
+                if t.text:
+                    # Extract leading whitespace
+                    stripped = t.text.lstrip()
+                    if stripped:  # Has actual content after whitespace
+                        return t.text[:len(t.text) - len(stripped)]
+                    elif t.text.isspace():  # Entire run is whitespace
+                        return t.text
+        return ''
+    
+    def add_clause(self, full_text, after_search, use_title_format=False):
+        """在包含after_search的段落之后插入新条款段落。
+        
+        full_text: 新条款全文
+        after_search: 在包含此文本的段落之后插入
+        use_title_format: True=标题格式（加粗），False=正文格式
+        """
+        ref_para = self.find_para(after_search)
+        if ref_para is None:
+            return False
+        
+        rpr = self._title_rpr if use_title_format else self._body_rpr
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws and not full_text.startswith(leading_ws):
+            full_text = leading_ws + full_text
+        
+        new_p = etree.Element(qn('p'))
+        if ppr is not None:
+            new_p.append(copy.deepcopy(ppr))
+        new_p.append(self._mk_ins(full_text, rpr))
+        
+        idx = list(self.body).index(ref_para)
+        self.body.insert(idx + 1, new_p)
+        return True
+    
+    def add_clause_before(self, full_text, before_search, use_title_format=False):
+        """在包含before_search的段落之前插入新条款段落。"""
+        ref_para = self.find_para(before_search)
+        if ref_para is None:
+            return False
+        
+        rpr = self._title_rpr if use_title_format else self._body_rpr
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws and not full_text.startswith(leading_ws):
+            full_text = leading_ws + full_text
+        
+        new_p = etree.Element(qn('p'))
+        if ppr is not None:
+            new_p.append(copy.deepcopy(ppr))
+        new_p.append(self._mk_ins(full_text, rpr))
+        
+        idx = list(self.body).index(ref_para)
+        self.body.insert(idx, new_p)
+        return True
+    
+    def add_mixed_clause(self, title_text, content_text, after_search):
+        """插入标题加粗+内容不加粗的新条款（两个段落）。
+        用于原文标题和内容分行的合同格式。"""
+        ref_para = self.find_para(after_search)
+        if ref_para is None:
+            return False
+        
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        idx = list(self.body).index(ref_para)
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws:
+            if not title_text.startswith(leading_ws):
+                title_text = leading_ws + title_text
+            if not content_text.startswith(leading_ws):
+                content_text = leading_ws + content_text
+        
+        p_title = etree.Element(qn('p'))
+        if ppr: p_title.append(copy.deepcopy(ppr))
+        p_title.append(self._mk_ins(title_text, self._title_rpr))
+        self.body.insert(idx + 1, p_title)
+        
+        p_content = etree.Element(qn('p'))
+        if ppr: p_content.append(copy.deepcopy(ppr))
+        p_content.append(self._mk_ins(content_text, self._body_rpr))
+        self.body.insert(idx + 2, p_content)
+        
+        return True
+    
+    def renumber_clause(self, old_num, new_num):
+        """把条款编号从old_num改为new_num（修订模式）。
+        从后往前扫描，避免重复修改。"""
+        changed = 0
+        for p in reversed(self.body.findall(qn('p'))):
+            runs = p.findall(f'.//{qn("r")}')
+            for r in runs:
+                for t in r.findall(qn('t')):
+                    if t.text and old_num in t.text:
+                        rpr_e = r.find(qn('rPr'))
+                        parent = r.getparent()
+                        idx_r = list(parent).index(r)
+                        
+                        pos = t.text.index(old_num)
+                        prefix = t.text[:pos]
+                        suffix = t.text[pos + len(old_num):]
+                        
+                        parent.remove(r)
+                        ip = idx_r
+                        if prefix:
+                            parent.insert(ip, self._mk_run(prefix, rpr_e))
+                            ip += 1
+                        parent.insert(ip, self._mk_del(old_num, rpr_e))
+                        ip += 1
+                        parent.insert(ip, self._mk_ins(new_num, rpr_e))
+                        ip += 1
+                        if suffix:
+                            parent.insert(ip, self._mk_run(suffix, rpr_e))
+                        
+                        changed += 1
+                        break
+        return changed
+    
+    def renumber_range(self, start, shift=1):
+        """从start开始，所有现有条款编号+shift。从后往前处理。
+        
+        注意：先调用此方法腾出编号空间，再插入新条款。
+        例：要在18后插入新19条：
+            editor.renumber_range(19, 1)  # 19→20, 20→21, 21→22
+            editor.add_clause_before("19．新条款内容", before_search="20．合同生效")
+        """
+        max_num = 0
+        for p in self.body.findall(qn('p')):
+            txt = self.get_para_text(p)
+            for m in re.finditer(r'(\d+)[．.]', txt):
+                n = int(m.group(1))
+                if n > max_num:
+                    max_num = n
+        
+        for n in range(max_num, start - 1, -1):
+            self.renumber_clause(f'{n}．', f'{n + shift}．')
+            self.renumber_clause(f'{n}.', f'{n + shift}.')
+    
+    def renumber_chinese(self, old_cn, new_cn):
+        """中文编号顺延，如 "第十三条" → "第十四条"。"""
+        return self.renumber_clause(old_cn, new_cn)
+    
+    def validate(self):
+        """交付前验证。返回错误列表，空列表=通过。"""
+        errors = []
+        
+        # 1. 编号连续性
+        clause_nums = []
+        for p in self.body.findall(qn('p')):
+            accepted = ''
+            for child in p:
+                tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+                if tag == 'r':
+                    accepted += ''.join(t.text or '' for t in child.findall(qn('t')))
+                elif tag == 'ins':
+                    accepted += ''.join(t.text or '' for t in child.findall(f'.//{qn("t")}'))
+            m = re.match(r'^(\d+)[．.]', accepted.strip())
+            if m:
+                clause_nums.append(int(m.group(1)))
+        
+        main_clauses = sorted(set(clause_nums))
+        for i in range(1, len(main_clauses)):
+            if main_clauses[i] - main_clauses[i-1] > 1:
+                errors.append(f"编号跳跃: {main_clauses[i-1]}→{main_clauses[i]}，缺少{main_clauses[i-1]+1}")
+        
+        # 2. 字号一致性（WB的ins内容 vs 原文正文）
+        if self._body_rpr is not None:
+            body_sz = None
+            sz_elem = self._body_rpr.find(qn('sz'))
+            if sz_elem is not None:
+                body_sz = sz_elem.get(qn('val'))
+            
+            if body_sz:
+                for ins in self.tree.findall(f'.//{qn("ins")}'):
+                    if ins.get(qn('author')) != self._author:
+                        continue
+                    for r in ins.findall(qn('r')):
+                        rpr = r.find(qn('rPr'))
+                        txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                        if not txt.strip():
+                            continue
+                        if rpr is not None:
+                            ins_sz = rpr.find(qn('sz'))
+                            if ins_sz is not None:
+                                val = ins_sz.get(qn('val'))
+                                is_bold = rpr.find(qn('b')) is not None
+                                if val != body_sz and not is_bold:
+                                    errors.append(f"字号不一致: ins sz={val} vs 原文sz={body_sz}，'{txt[:30]}'")
+        
+        # 3. 加粗规则（内容不应加粗）
+        for ins in self.tree.findall(f'.//{qn("ins")}'):
+            if ins.get(qn('author')) != self._author:
+                continue
+            for r in ins.findall(qn('r')):
+                rpr = r.find(qn('rPr'))
+                txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if not txt.strip() or len(txt.strip()) < 5:
+                    continue
+                is_bold = rpr is not None and rpr.find(qn('b')) is not None
+                is_clause_title = bool(re.match(r'^\d+[．.]\S', txt.strip())) or bool(re.match(r'^第.{1,3}条', txt.strip())) or bool(re.match(r'^[一二三四五六七八九十]{1,3}、', txt.strip()))
+                if is_bold and not is_clause_title:
+                    errors.append(f"不应加粗: '{txt[:40]}'")
+        
+        return errors
+    
+    def dump_numbering(self):
+        """输出accepted view的编号序列，用于人工确认"""
+        result = []
+        for p in self.body.findall(qn('p')):
+            accepted = ''
+            for child in p:
+                tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+                if tag == 'r':
+                    accepted += ''.join(t.text or '' for t in child.findall(qn('t')))
+                elif tag == 'ins':
+                    accepted += ''.join(t.text or '' for t in child.findall(f'.//{qn("t")}'))
+            m = re.match(r'^(\d+)[．.]', accepted.strip())
+            if m:
+                result.append(f"{m.group(1)}. {accepted.strip()[:60]}")
+        return result
+    
+    def save(self, output_path):
+        """保存修订后的文件"""
+        new_doc_xml = etree.tostring(self.tree, xml_declaration=True,
+                                      encoding='UTF-8', standalone=True)
+        
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as z:
+            settings = z.read('word/settings.xml')
+        stree = etree.fromstring(settings)
+        if stree.find(f'.//{qn("trackRevisions")}') is None:
+            stree.append(etree.Element(qn('trackRevisions')))
+        new_settings = etree.tostring(stree, xml_declaration=True,
+                                       encoding='UTF-8', standalone=True)
+        
+        buf = io.BytesIO()
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as zin:
+            with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    if item.filename == 'word/document.xml':
+                        zout.writestr(item, new_doc_xml)
+                    elif item.filename == 'word/settings.xml':
+                        zout.writestr(item, new_settings)
+                    else:
+                        zout.writestr(item, zin.read(item.filename))
+        
+        with open(output_path, 'wb') as f:
+            f.write(buf.getvalue())
+        
+        return output_path
+
+
+class ZhujiajaoOpinion:
+    """朱家角审查意见表格填写器。严格使用模板结构，不自创格式。"""
+    
+    TEMPLATE_PATH = Path.home() / ".hermes/shared/模版库/朱家角 审查意见【模板】.docx"
+    
+    def __init__(self, template_path=None):
+        tpath = Path(template_path) if template_path else self.TEMPLATE_PATH
+        with open(tpath, 'rb') as f:
+            self.tmpl_bytes = f.read()
+        
+        with zipfile.ZipFile(io.BytesIO(self.tmpl_bytes)) as z:
+            self.doc_xml = z.read('word/document.xml')
+        
+        self.tree = etree.fromstring(self.doc_xml)
+        self.body = self.tree.find(qn('body'))
+    
+    def fill(self, contract_name, items, has_modifications=True):
+        """填写审查意见。
+        
+        contract_name: 合同名称（填入标题《》中间）
+        items: [(条文位置, 原文, 修订后), ...]
+        has_modifications: False则保留"无法律修改意见"
+        """
+        # 1. 填标题——找到空格run替换
+        for p in self.body.findall(qn('p')):
+            runs = p.findall(f'.//{qn("r")}')
+            for r in runs:
+                for t in r.findall(qn('t')):
+                    if t.text and t.text.strip() == '' and len(t.text) >= 2:
+                        parent_txt = ''.join(
+                            tt.text or '' for rr in runs for tt in rr.findall(qn('t'))
+                        )
+                        if '关于《' in parent_txt:
+                            t.text = contract_name
+        
+        # 2. 处理"无法律修改意见"
+        if has_modifications:
+            for p in self.body.findall(qn('p')):
+                txt = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+                if '无法律修改意见' in txt:
+                    for r in p.findall(f'.//{qn("r")}'):
+                        for t in r.findall(qn('t')):
+                            if '无法律修改意见' in (t.text or ''):
+                                t.text = ''
+        
+        # 3. 填表格
+        if not items:
+            return
+        
+        tbl = self.body.find(qn('tbl'))
+        if tbl is None:
+            return
+        
+        rows = tbl.findall(qn('tr'))
+        # Row 0 = header, Row 1+ = data rows
+        
+        # 获取表头rPr
+        header_rpr = None
+        for hc in rows[0].findall(qn('tc')):
+            for hr in hc.findall(f'.//{qn("r")}'):
+                rr = hr.find(qn('rPr'))
+                if rr:
+                    header_rpr = rr
+                    break
+            if header_rpr:
+                break
+        
+        # 确保有足够数据行
+        template_row = rows[1] if len(rows) > 1 else None
+        while len(tbl.findall(qn('tr'))) - 1 < len(items):
+            if template_row is not None:
+                tbl.append(copy.deepcopy(template_row))
+        
+        rows = tbl.findall(qn('tr'))
+        
+        # 填写数据
+        for i, (clause, orig_text, modified_text) in enumerate(items):
+            if i + 1 >= len(rows):
+                break
+            row = rows[i + 1]
+            cells = row.findall(qn('tc'))
+            if len(cells) < 3:
+                continue
+            
+            for ci, text in enumerate([clause, orig_text, modified_text]):
+                cell = cells[ci]
+                p = cell.find(qn('p'))
+                if p is None:
+                    p = etree.SubElement(cell, qn('p'))
+                for r in p.findall(qn('r')):
+                    p.remove(r)
+                
+                r = etree.SubElement(p, qn('r'))
+                if header_rpr:
+                    new_rpr = copy.deepcopy(header_rpr)
+                    b = new_rpr.find(qn('b'))
+                    if b is not None:
+                        new_rpr.remove(b)
+                    if '注：' in text:
+                        color = new_rpr.find(qn('color'))
+                        if color is None:
+                            color = etree.SubElement(new_rpr, qn('color'))
+                        color.set(qn('val'), 'FF0000')
+                    r.append(new_rpr)
+                
+                t = etree.SubElement(r, qn('t'))
+                t.set(XML_SPACE, 'preserve')
+                t.text = text
+        
+        # 删除多余空行
+        rows = tbl.findall(qn('tr'))
+        for i in range(len(rows) - 1, len(items), -1):
+            tbl.remove(rows[i])
+    
+    def save(self, output_path):
+        new_doc = etree.tostring(self.tree, xml_declaration=True,
+                                  encoding='UTF-8', standalone=True)
+        buf = io.BytesIO()
+        with zipfile.ZipFile(io.BytesIO(self.tmpl_bytes)) as zin:
+            with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    if item.filename == 'word/document.xml':
+                        zout.writestr(item, new_doc)
+                    else:
+                        zout.writestr(item, zin.read(item.filename))
+        with open(output_path, 'wb') as f:
+            f.write(buf.getvalue())
+        return output_path

skills/legal/contract-editor/scripts/contract_docx_lib.py.bak

@@ -0,0 +1,684 @@
+#!/usr/bin/env python3
+"""
+contract_docx_lib.py — 合同修订核心库
+固化验证通过的docx XML操作，不再每次重写。
+
+用法：
+    from contract_docx_lib import ContractEditor
+    
+    editor = ContractEditor("原文件.docx")
+    editor.tracked_replace("原文片段", "新文片段")
+    editor.add_clause("19．服务成果持续使用权", "条款内容...", after_clause=18)
+    editor.renumber(19, 20)  # 原19→20
+    errors = editor.validate()
+    if not errors:
+        editor.save("【修】原文件.docx")
+
+关键操作顺序（renumber和新增条款）：
+    1. 先做所有 tracked_replace（文本修改）
+    2. 再做 add_clause（新增子条款，如15.4）
+    3. 再做 renumber_range（先腾出编号空间）
+    4. 最后做 add_clause_before（插入新主条款，用已腾出的编号）
+    5. validate() 验证
+    6. save() 保存
+"""
+
+import zipfile, io, copy, re, difflib
+from lxml import etree
+from datetime import datetime
+from pathlib import Path
+
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+WP = 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing'
+XML_SPACE = '{http://www.w3.org/XML/1998/namespace}space'
+WNS = '{' + W + '}'
+
+def qn(tag):
+    return f'{WNS}{tag}'
+
+
+def cjk_tokenize(text):
+    """CJK每字一token，ASCII连续一token，标点单独token。
+    经验证的分词策略，不要改。"""
+    tokens = []
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if '\u4e00' <= ch <= '\u9fff' or '\u3000' <= ch <= '\u303f' or ch in '，。、；：！？""''（）【】《》—…·[]％%':
+            tokens.append(ch)
+            i += 1
+        elif ch.isascii() and ch.isalnum():
+            j = i
+            while j < len(text) and text[j].isascii() and text[j].isalnum():
+                j += 1
+            tokens.append(text[i:j])
+            i = j
+        else:
+            tokens.append(ch)
+            i += 1
+    return tokens
+
+
+class ContractEditor:
+    """合同修订编辑器。一个实例对应一份合同文件。"""
+    
+    def __init__(self, filepath):
+        self.filepath = Path(filepath)
+        with open(filepath, 'rb') as f:
+            self.original_bytes = f.read()
+        
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as z:
+            self.doc_xml = z.read('word/document.xml')
+        
+        self.tree = etree.fromstring(self.doc_xml)
+        self.body = self.tree.find(qn('body'))
+        self._rev_id = 100
+        self._revision_date = datetime.now().strftime('%Y-%m-%dT%H:%M:%SZ')
+        self._author = 'WB'
+        self._rsid = '00AA0001'
+        
+        # 提取原文格式（核心：避免每次猜错格式）
+        self._body_rpr = None   # 正文格式（最常见的非加粗rPr）
+        self._title_rpr = None  # 条款标题格式（加粗的rPr）
+        self._body_ppr = None
+        self._extract_formats()
+    
+    def _extract_formats(self):
+        """从原文提取正文和标题的rPr。
+        策略：
+        - 正文格式：统计所有run的rPr，取出现最多的非加粗rPr
+        - 标题格式：优先从条款编号标题段落（如"7.索赔条款"）提取rPr，
+          而非简单取第一个加粗run（可能是合同大标题，字号不同）
+        - 如果条款标题不加粗，标题格式回退到正文格式"""
+        import re
+        rpr_map = {}  # serialized_rpr -> (count, rpr_element)
+        clause_title_rpr = None  # 从条款编号标题提取的格式
+        first_bold_rpr = None    # 第一个加粗run的格式（fallback）
+        
+        for p in self.body.findall(qn('p')):
+            # 获取段落全文，判断是否是条款编号标题（如 "7.索赔条款" "5.伴随服务"）
+            p_text = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}')).strip()
+            is_clause_title = bool(re.match(r'^\d+[．.、]\s*\S', p_text)) and len(p_text) < 30
+            
+            for r in p.findall(qn('r')):
+                rpr = r.find(qn('rPr'))
+                txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if not txt.strip() or len(txt) < 3:
+                    continue
+                
+                if rpr is not None:
+                    is_bold = rpr.find(qn('b')) is not None
+                    key = etree.tostring(rpr, encoding='unicode')
+                    
+                    if is_bold and first_bold_rpr is None:
+                        first_bold_rpr = rpr
+                    
+                    # 优先从条款标题段落提取标题格式
+                    if is_clause_title and clause_title_rpr is None:
+                        clause_title_rpr = rpr
+                    
+                    if not is_bold:
+                        if key not in rpr_map:
+                            rpr_map[key] = [0, rpr]
+                        rpr_map[key][0] += 1
+            
+            if self._body_ppr is None:
+                ppr = p.find(qn('pPr'))
+                txt = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+                if ppr is not None and len(txt) > 20:
+                    self._body_ppr = ppr
+        
+        if rpr_map:
+            best = max(rpr_map.values(), key=lambda x: x[0])
+            self._body_rpr = best[1]
+        
+        # 标题格式优先级：条款编号标题 > 第一个加粗run > 正文格式
+        self._title_rpr = clause_title_rpr or first_bold_rpr or self._body_rpr
+        
+        if self._title_rpr is None and self._body_rpr is not None:
+            self._title_rpr = copy.deepcopy(self._body_rpr)
+            etree.SubElement(self._title_rpr, qn('b'))
+    
+    def _next_id(self):
+        self._rev_id += 1
+        return str(self._rev_id)
+    
+    def _mk_del(self, text, rpr=None):
+        d = etree.Element(qn('del'))
+        d.set(qn('id'), self._next_id())
+        d.set(qn('author'), self._author)
+        d.set(qn('date'), self._revision_date)
+        r = etree.SubElement(d, qn('r'))
+        r.set(qn('rsidDel'), self._rsid)
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('delText'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return d
+    
+    def _mk_ins(self, text, rpr=None):
+        i = etree.Element(qn('ins'))
+        i.set(qn('id'), self._next_id())
+        i.set(qn('author'), self._author)
+        i.set(qn('date'), self._revision_date)
+        r = etree.SubElement(i, qn('r'))
+        r.set(qn('rsidR'), self._rsid)
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('t'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return i
+    
+    def _mk_run(self, text, rpr=None):
+        r = etree.Element(qn('r'))
+        if rpr is not None:
+            r.append(copy.deepcopy(rpr))
+        t = etree.SubElement(r, qn('t'))
+        t.set(XML_SPACE, 'preserve')
+        t.text = text
+        return r
+    
+    def get_para_text(self, p):
+        """获取段落的原始文本（不含删除标记中的文本）"""
+        return ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+    
+    def find_para(self, search_text):
+        """查找包含指定文本的段落"""
+        for p in self.body.findall(qn('p')):
+            if search_text in self.get_para_text(p):
+                return p
+        return None
+    
+    def tracked_replace(self, old_text, new_text):
+        """在整个文档中查找old_text并用修订模式替换为new_text。
+        使用字符级tokenizer+difflib实现精准修订。
+        返回True如果成功。"""
+        for p in self.body.findall(qn('p')):
+            runs = p.findall(f'.//{qn("r")}')
+            if not runs:
+                continue
+            full = ''.join(
+                ''.join(t.text or '' for t in r.findall(qn('t')))
+                for r in runs
+            )
+            if old_text not in full:
+                continue
+            
+            start = full.index(old_text)
+            end = start + len(old_text)
+            
+            # 获取匹配位置的rPr
+            rpr = None
+            pos = 0
+            for r in runs:
+                rt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if pos + len(rt) > start:
+                    rpr = r.find(qn('rPr'))
+                    break
+                pos += len(rt)
+            
+            # 生成diff元素
+            if new_text == '':
+                elems = [self._mk_del(old_text, rpr)]
+            else:
+                ot = cjk_tokenize(old_text)
+                nt = cjk_tokenize(new_text)
+                matcher = difflib.SequenceMatcher(None, ot, nt)
+                elems = []
+                for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+                    if tag == 'equal':
+                        elems.append(self._mk_run(''.join(ot[i1:i2]), rpr))
+                    elif tag == 'delete':
+                        elems.append(self._mk_del(''.join(ot[i1:i2]), rpr))
+                    elif tag == 'insert':
+                        elems.append(self._mk_ins(''.join(nt[j1:j2]), rpr))
+                    elif tag == 'replace':
+                        elems.append(self._mk_del(''.join(ot[i1:i2]), rpr))
+                        elems.append(self._mk_ins(''.join(nt[j1:j2]), rpr))
+            
+            # 定位受影响的runs并替换
+            pos = 0
+            first = last = None
+            prefix_text = suffix_text = ""
+            for idx, r in enumerate(runs):
+                rt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                run_end = pos + len(rt)
+                if run_end > start and pos < end:
+                    if first is None:
+                        first = idx
+                        prefix_text = full[pos:start]
+                    last = idx
+                    suffix_text = full[end:run_end] if run_end > end else ""
+                pos = run_end
+            
+            if first is None:
+                continue
+            
+            ref = runs[first]
+            # Find the actual paragraph (w:p) element to insert into
+            para_elem = p
+            # Determine insert position: find ref or its ancestor that is a direct child of p
+            ref_ancestor = ref
+            while ref_ancestor.getparent() is not para_elem and ref_ancestor.getparent() is not None:
+                ref_ancestor = ref_ancestor.getparent()
+            insert_pos = list(para_elem).index(ref_ancestor)
+            
+            # Remove runs (each from its own parent)
+            for idx in range(last, first - 1, -1):
+                r = runs[idx]
+                r_parent = r.getparent()
+                r_parent.remove(r)
+                # If parent (e.g. w:ins) is now empty, remove it too
+                if r_parent is not para_elem and len(r_parent) == 0:
+                    gp = r_parent.getparent()
+                    if gp is not None:
+                        gp.remove(r_parent)
+            
+            ip = insert_pos
+            if prefix_text:
+                para_elem.insert(ip, self._mk_run(prefix_text, rpr))
+                ip += 1
+            for e in elems:
+                para_elem.insert(ip, e)
+                ip += 1
+            if suffix_text:
+                para_elem.insert(ip, self._mk_run(suffix_text, rpr))
+            
+            return True
+        
+        return False
+    
+    def _get_leading_whitespace(self, para):
+        """从段落中提取前导空格/tab模式。
+        很多中文文档的缩进不是通过w:ind实现的，而是通过文本中的空格字符。"""
+        for r in para.findall(qn('r')):
+            # Skip deleted runs
+            if r.getparent().tag == qn('del'):
+                continue
+            for t in r.findall(qn('t')):
+                if t.text:
+                    # Extract leading whitespace
+                    stripped = t.text.lstrip()
+                    if stripped:  # Has actual content after whitespace
+                        return t.text[:len(t.text) - len(stripped)]
+                    elif t.text.isspace():  # Entire run is whitespace
+                        return t.text
+        return ''
+    
+    def add_clause(self, full_text, after_search, use_title_format=False):
+        """在包含after_search的段落之后插入新条款段落。
+        
+        full_text: 新条款全文
+        after_search: 在包含此文本的段落之后插入
+        use_title_format: True=标题格式（加粗），False=正文格式
+        """
+        ref_para = self.find_para(after_search)
+        if ref_para is None:
+            return False
+        
+        rpr = self._title_rpr if use_title_format else self._body_rpr
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws and not full_text.startswith(leading_ws):
+            full_text = leading_ws + full_text
+        
+        new_p = etree.Element(qn('p'))
+        if ppr is not None:
+            new_p.append(copy.deepcopy(ppr))
+        new_p.append(self._mk_ins(full_text, rpr))
+        
+        idx = list(self.body).index(ref_para)
+        self.body.insert(idx + 1, new_p)
+        return True
+    
+    def add_clause_before(self, full_text, before_search, use_title_format=False):
+        """在包含before_search的段落之前插入新条款段落。"""
+        ref_para = self.find_para(before_search)
+        if ref_para is None:
+            return False
+        
+        rpr = self._title_rpr if use_title_format else self._body_rpr
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws and not full_text.startswith(leading_ws):
+            full_text = leading_ws + full_text
+        
+        new_p = etree.Element(qn('p'))
+        if ppr is not None:
+            new_p.append(copy.deepcopy(ppr))
+        new_p.append(self._mk_ins(full_text, rpr))
+        
+        idx = list(self.body).index(ref_para)
+        self.body.insert(idx, new_p)
+        return True
+    
+    def add_mixed_clause(self, title_text, content_text, after_search):
+        """插入标题加粗+内容不加粗的新条款（两个段落）。
+        用于原文标题和内容分行的合同格式。"""
+        ref_para = self.find_para(after_search)
+        if ref_para is None:
+            return False
+        
+        ppr = ref_para.find(qn('pPr')) or self._body_ppr
+        idx = list(self.body).index(ref_para)
+        
+        # 复制相邻段落的前导空格模式
+        leading_ws = self._get_leading_whitespace(ref_para)
+        if leading_ws:
+            if not title_text.startswith(leading_ws):
+                title_text = leading_ws + title_text
+            if not content_text.startswith(leading_ws):
+                content_text = leading_ws + content_text
+        
+        p_title = etree.Element(qn('p'))
+        if ppr: p_title.append(copy.deepcopy(ppr))
+        p_title.append(self._mk_ins(title_text, self._title_rpr))
+        self.body.insert(idx + 1, p_title)
+        
+        p_content = etree.Element(qn('p'))
+        if ppr: p_content.append(copy.deepcopy(ppr))
+        p_content.append(self._mk_ins(content_text, self._body_rpr))
+        self.body.insert(idx + 2, p_content)
+        
+        return True
+    
+    def renumber_clause(self, old_num, new_num):
+        """把条款编号从old_num改为new_num（修订模式）。
+        从后往前扫描，避免重复修改。"""
+        changed = 0
+        for p in reversed(self.body.findall(qn('p'))):
+            runs = p.findall(f'.//{qn("r")}')
+            for r in runs:
+                for t in r.findall(qn('t')):
+                    if t.text and old_num in t.text:
+                        rpr_e = r.find(qn('rPr'))
+                        parent = r.getparent()
+                        idx_r = list(parent).index(r)
+                        
+                        pos = t.text.index(old_num)
+                        prefix = t.text[:pos]
+                        suffix = t.text[pos + len(old_num):]
+                        
+                        parent.remove(r)
+                        ip = idx_r
+                        if prefix:
+                            parent.insert(ip, self._mk_run(prefix, rpr_e))
+                            ip += 1
+                        parent.insert(ip, self._mk_del(old_num, rpr_e))
+                        ip += 1
+                        parent.insert(ip, self._mk_ins(new_num, rpr_e))
+                        ip += 1
+                        if suffix:
+                            parent.insert(ip, self._mk_run(suffix, rpr_e))
+                        
+                        changed += 1
+                        break
+        return changed
+    
+    def renumber_range(self, start, shift=1):
+        """从start开始，所有现有条款编号+shift。从后往前处理。
+        
+        注意：先调用此方法腾出编号空间，再插入新条款。
+        例：要在18后插入新19条：
+            editor.renumber_range(19, 1)  # 19→20, 20→21, 21→22
+            editor.add_clause_before("19．新条款内容", before_search="20．合同生效")
+        """
+        max_num = 0
+        for p in self.body.findall(qn('p')):
+            txt = self.get_para_text(p)
+            for m in re.finditer(r'(\d+)[．.]', txt):
+                n = int(m.group(1))
+                if n > max_num:
+                    max_num = n
+        
+        for n in range(max_num, start - 1, -1):
+            self.renumber_clause(f'{n}．', f'{n + shift}．')
+            self.renumber_clause(f'{n}.', f'{n + shift}.')
+    
+    def renumber_chinese(self, old_cn, new_cn):
+        """中文编号顺延，如 "第十三条" → "第十四条"。"""
+        return self.renumber_clause(old_cn, new_cn)
+    
+    def validate(self):
+        """交付前验证。返回错误列表，空列表=通过。"""
+        errors = []
+        
+        # 1. 编号连续性
+        clause_nums = []
+        for p in self.body.findall(qn('p')):
+            accepted = ''
+            for child in p:
+                tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+                if tag == 'r':
+                    accepted += ''.join(t.text or '' for t in child.findall(qn('t')))
+                elif tag == 'ins':
+                    accepted += ''.join(t.text or '' for t in child.findall(f'.//{qn("t")}'))
+            m = re.match(r'^(\d+)[．.]', accepted.strip())
+            if m:
+                clause_nums.append(int(m.group(1)))
+        
+        main_clauses = sorted(set(clause_nums))
+        for i in range(1, len(main_clauses)):
+            if main_clauses[i] - main_clauses[i-1] > 1:
+                errors.append(f"编号跳跃: {main_clauses[i-1]}→{main_clauses[i]}，缺少{main_clauses[i-1]+1}")
+        
+        # 2. 字号一致性（WB的ins内容 vs 原文正文）
+        if self._body_rpr is not None:
+            body_sz = None
+            sz_elem = self._body_rpr.find(qn('sz'))
+            if sz_elem is not None:
+                body_sz = sz_elem.get(qn('val'))
+            
+            if body_sz:
+                for ins in self.tree.findall(f'.//{qn("ins")}'):
+                    if ins.get(qn('author')) != self._author:
+                        continue
+                    for r in ins.findall(qn('r')):
+                        rpr = r.find(qn('rPr'))
+                        txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                        if not txt.strip():
+                            continue
+                        if rpr is not None:
+                            ins_sz = rpr.find(qn('sz'))
+                            if ins_sz is not None:
+                                val = ins_sz.get(qn('val'))
+                                is_bold = rpr.find(qn('b')) is not None
+                                if val != body_sz and not is_bold:
+                                    errors.append(f"字号不一致: ins sz={val} vs 原文sz={body_sz}，'{txt[:30]}'")
+        
+        # 3. 加粗规则（内容不应加粗）
+        for ins in self.tree.findall(f'.//{qn("ins")}'):
+            if ins.get(qn('author')) != self._author:
+                continue
+            for r in ins.findall(qn('r')):
+                rpr = r.find(qn('rPr'))
+                txt = ''.join(t.text or '' for t in r.findall(qn('t')))
+                if not txt.strip() or len(txt.strip()) < 5:
+                    continue
+                is_bold = rpr is not None and rpr.find(qn('b')) is not None
+                is_clause_title = bool(re.match(r'^\d+[．.]\S', txt.strip())) or bool(re.match(r'^第.{1,3}条', txt.strip()))
+                if is_bold and not is_clause_title:
+                    errors.append(f"不应加粗: '{txt[:40]}'")
+        
+        return errors
+    
+    def dump_numbering(self):
+        """输出accepted view的编号序列，用于人工确认"""
+        result = []
+        for p in self.body.findall(qn('p')):
+            accepted = ''
+            for child in p:
+                tag = child.tag.split('}')[-1] if '}' in child.tag else child.tag
+                if tag == 'r':
+                    accepted += ''.join(t.text or '' for t in child.findall(qn('t')))
+                elif tag == 'ins':
+                    accepted += ''.join(t.text or '' for t in child.findall(f'.//{qn("t")}'))
+            m = re.match(r'^(\d+)[．.]', accepted.strip())
+            if m:
+                result.append(f"{m.group(1)}. {accepted.strip()[:60]}")
+        return result
+    
+    def save(self, output_path):
+        """保存修订后的文件"""
+        new_doc_xml = etree.tostring(self.tree, xml_declaration=True,
+                                      encoding='UTF-8', standalone=True)
+        
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as z:
+            settings = z.read('word/settings.xml')
+        stree = etree.fromstring(settings)
+        if stree.find(f'.//{qn("trackRevisions")}') is None:
+            stree.append(etree.Element(qn('trackRevisions')))
+        new_settings = etree.tostring(stree, xml_declaration=True,
+                                       encoding='UTF-8', standalone=True)
+        
+        buf = io.BytesIO()
+        with zipfile.ZipFile(io.BytesIO(self.original_bytes)) as zin:
+            with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    if item.filename == 'word/document.xml':
+                        zout.writestr(item, new_doc_xml)
+                    elif item.filename == 'word/settings.xml':
+                        zout.writestr(item, new_settings)
+                    else:
+                        zout.writestr(item, zin.read(item.filename))
+        
+        with open(output_path, 'wb') as f:
+            f.write(buf.getvalue())
+        
+        return output_path
+
+
+class ZhujiajaoOpinion:
+    """朱家角审查意见表格填写器。严格使用模板结构，不自创格式。"""
+    
+    TEMPLATE_PATH = Path.home() / ".hermes/shared/模版库/朱家角 审查意见【模板】.docx"
+    
+    def __init__(self, template_path=None):
+        tpath = Path(template_path) if template_path else self.TEMPLATE_PATH
+        with open(tpath, 'rb') as f:
+            self.tmpl_bytes = f.read()
+        
+        with zipfile.ZipFile(io.BytesIO(self.tmpl_bytes)) as z:
+            self.doc_xml = z.read('word/document.xml')
+        
+        self.tree = etree.fromstring(self.doc_xml)
+        self.body = self.tree.find(qn('body'))
+    
+    def fill(self, contract_name, items, has_modifications=True):
+        """填写审查意见。
+        
+        contract_name: 合同名称（填入标题《》中间）
+        items: [(条文位置, 原文, 修订后), ...]
+        has_modifications: False则保留"无法律修改意见"
+        """
+        # 1. 填标题——找到空格run替换
+        for p in self.body.findall(qn('p')):
+            runs = p.findall(f'.//{qn("r")}')
+            for r in runs:
+                for t in r.findall(qn('t')):
+                    if t.text and t.text.strip() == '' and len(t.text) >= 2:
+                        parent_txt = ''.join(
+                            tt.text or '' for rr in runs for tt in rr.findall(qn('t'))
+                        )
+                        if '关于《' in parent_txt:
+                            t.text = contract_name
+        
+        # 2. 处理"无法律修改意见"
+        if has_modifications:
+            for p in self.body.findall(qn('p')):
+                txt = ''.join(t.text or '' for t in p.findall(f'.//{qn("t")}'))
+                if '无法律修改意见' in txt:
+                    for r in p.findall(f'.//{qn("r")}'):
+                        for t in r.findall(qn('t')):
+                            if '无法律修改意见' in (t.text or ''):
+                                t.text = ''
+        
+        # 3. 填表格
+        if not items:
+            return
+        
+        tbl = self.body.find(qn('tbl'))
+        if tbl is None:
+            return
+        
+        rows = tbl.findall(qn('tr'))
+        # Row 0 = header, Row 1+ = data rows
+        
+        # 获取表头rPr
+        header_rpr = None
+        for hc in rows[0].findall(qn('tc')):
+            for hr in hc.findall(f'.//{qn("r")}'):
+                rr = hr.find(qn('rPr'))
+                if rr:
+                    header_rpr = rr
+                    break
+            if header_rpr:
+                break
+        
+        # 确保有足够数据行
+        template_row = rows[1] if len(rows) > 1 else None
+        while len(tbl.findall(qn('tr'))) - 1 < len(items):
+            if template_row is not None:
+                tbl.append(copy.deepcopy(template_row))
+        
+        rows = tbl.findall(qn('tr'))
+        
+        # 填写数据
+        for i, (clause, orig_text, modified_text) in enumerate(items):
+            if i + 1 >= len(rows):
+                break
+            row = rows[i + 1]
+            cells = row.findall(qn('tc'))
+            if len(cells) < 3:
+                continue
+            
+            for ci, text in enumerate([clause, orig_text, modified_text]):
+                cell = cells[ci]
+                p = cell.find(qn('p'))
+                if p is None:
+                    p = etree.SubElement(cell, qn('p'))
+                for r in p.findall(qn('r')):
+                    p.remove(r)
+                
+                r = etree.SubElement(p, qn('r'))
+                if header_rpr:
+                    new_rpr = copy.deepcopy(header_rpr)
+                    b = new_rpr.find(qn('b'))
+                    if b is not None:
+                        new_rpr.remove(b)
+                    if '注：' in text:
+                        color = new_rpr.find(qn('color'))
+                        if color is None:
+                            color = etree.SubElement(new_rpr, qn('color'))
+                        color.set(qn('val'), 'FF0000')
+                    r.append(new_rpr)
+                
+                t = etree.SubElement(r, qn('t'))
+                t.set(XML_SPACE, 'preserve')
+                t.text = text
+        
+        # 删除多余空行
+        rows = tbl.findall(qn('tr'))
+        for i in range(len(rows) - 1, len(items), -1):
+            tbl.remove(rows[i])
+    
+    def save(self, output_path):
+        new_doc = etree.tostring(self.tree, xml_declaration=True,
+                                  encoding='UTF-8', standalone=True)
+        buf = io.BytesIO()
+        with zipfile.ZipFile(io.BytesIO(self.tmpl_bytes)) as zin:
+            with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    if item.filename == 'word/document.xml':
+                        zout.writestr(item, new_doc)
+                    else:
+                        zout.writestr(item, zin.read(item.filename))
+        with open(output_path, 'wb') as f:
+            f.write(buf.getvalue())
+        return output_path

skills/legal/contract-editor/scripts/contract_preprocess.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+contract_preprocess.py — 合同预处理：检测并切割非审查图片内容
+
+用途：在workflow审查前，检测合同末尾的纯图片附件（如招标公告截图、中标通知书等），
+     切割出来保存，审查完后再还原。
+
+判断逻辑：
+1. 扫描文件结构：文字段落数 vs 图片段落数
+2. 全文/大部分是图片（扫描件合同）→ 不切割，标记需OCR
+3. 正文文字+末尾图片附件 → 切割末尾图片区域
+4. 切割点：从最后一个"纯文字附件"结束后，到第一个"纯图片附件"开始
+
+输出：
+- {basename}_stripped.docx — 去掉图片附件的版本（供workflow处理）
+- {basename}_cutdata.json — 切割信息（供还原用）
+"""
+
+import zipfile, json, os, sys, re
+from lxml import etree
+
+W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+A_NS = 'http://schemas.openxmlformats.org/drawingml/2006/main'
+
+
+def analyze_contract(docx_path):
+    """Analyze contract structure, return analysis dict"""
+    with zipfile.ZipFile(docx_path) as z:
+        doc = etree.fromstring(z.read('word/document.xml'))
+        media_files = {n: z.getinfo(n).file_size for n in z.namelist() if n.startswith('word/media/')}
+
+    body = doc.find(f'{{{W}}}body')
+    paras = body.findall(f'{{{W}}}p')
+
+    paragraphs = []
+    total_text_chars = 0
+    total_img_paras = 0
+
+    for i, p in enumerate(paras):
+        texts = p.findall(f'.//{{{W}}}t')
+        text = ''.join(t.text or '' for t in texts).strip()
+
+        has_img = any('drawing' in (e.tag if isinstance(e.tag, str) else '') for e in p.iter())
+
+        blips = list(p.iter(f'{{{A_NS}}}blip'))
+        img_rids = [b.get(f'{{{R_NS}}}embed', '') for b in blips]
+
+        total_text_chars += len(text)
+        if has_img:
+            total_img_paras += 1
+
+        paragraphs.append({
+            'idx': i,
+            'text': text,
+            'text_len': len(text),
+            'has_img': has_img,
+            'img_rids': img_rids,
+            'is_appendix_heading': bool(re.match(r'^附件[一二三四五六七八九十\d]+[：:、]', text)),
+        })
+
+    return {
+        'total_paras': len(paras),
+        'total_text_chars': total_text_chars,
+        'total_img_paras': total_img_paras,
+        'media_files': media_files,
+        'total_media_bytes': sum(media_files.values()),
+        'paragraphs': paragraphs,
+    }
+
+
+def detect_cut_zone(analysis):
+    """Detect if there's a tail image zone to cut."""
+    paras = analysis['paragraphs']
+    total = analysis['total_paras']
+
+    text_paras = sum(1 for p in paras if p['text_len'] > 0 and not p['has_img'])
+    img_paras = analysis['total_img_paras']
+
+    if text_paras == 0 and img_paras > 0:
+        return {'action': 'ocr', 'reason': '全文无文字段落，疑似扫描件合同'}
+
+    if img_paras == 0:
+        return None
+
+    img_ratio = img_paras / max(1, text_paras + img_paras)
+    if img_ratio > 0.5:
+        return {'action': 'ocr', 'reason': f'图片段落占比{img_ratio:.0%}，疑似扫描件合同'}
+
+    # Find tail image zones
+    image_zones = []
+    i = 0
+    while i < total:
+        p = paras[i]
+        if p['is_appendix_heading']:
+            zone_start = i
+            zone_has_images = False
+            zone_has_text_content = False
+            j = i + 1
+
+            while j < total:
+                next_p = paras[j]
+                if next_p['is_appendix_heading']:
+                    break
+                if next_p['has_img']:
+                    zone_has_images = True
+                if next_p['text_len'] > 20 and not next_p['has_img']:
+                    zone_has_text_content = True
+                j += 1
+
+            image_zones.append({
+                'start_idx': zone_start,
+                'end_idx': j - 1,
+                'heading': p['text'],
+                'has_images': zone_has_images,
+                'has_text': zone_has_text_content,
+                'is_image_only': zone_has_images and not zone_has_text_content,
+            })
+            i = j
+        else:
+            i += 1
+
+    # Find consecutive image-only appendices at the tail
+    tail_cut_zones = []
+    for zone in reversed(image_zones):
+        if zone['is_image_only']:
+            tail_cut_zones.insert(0, zone)
+        else:
+            break
+
+    if not tail_cut_zones:
+        return None
+
+    cut_start = tail_cut_zones[0]['start_idx']
+    cut_headings = [z['heading'] for z in tail_cut_zones]
+
+    return {
+        'action': 'cut',
+        'cut_start_idx': cut_start,
+        'cut_end_idx': total - 1,
+        'cut_headings': cut_headings,
+        'reason': f'末尾{len(tail_cut_zones)}个附件为纯图片：{", ".join(cut_headings)}',
+    }
+
+
+def preprocess_contract(docx_path, output_dir=None):
+    """Main entry: analyze and optionally strip tail images."""
+    if output_dir is None:
+        output_dir = os.path.dirname(docx_path) or '.'
+
+    basename = os.path.splitext(os.path.basename(docx_path))[0]
+
+    analysis = analyze_contract(docx_path)
+    cut_info = detect_cut_zone(analysis)
+
+    print(f"\n=== 合同预处理分析 ===")
+    print(f"文件: {os.path.basename(docx_path)}")
+    print(f"段落数: {analysis['total_paras']}")
+    print(f"文字字符: {analysis['total_text_chars']}")
+    print(f"图片段落: {analysis['total_img_paras']}")
+    print(f"媒体文件: {len(analysis['media_files'])} ({analysis['total_media_bytes']:,} bytes)")
+
+    if cut_info is None:
+        print(f"结论: 无需切割")
+        return {'action': 'none', 'analysis': analysis}
+
+    if cut_info['action'] == 'ocr':
+        print(f"结论: {cut_info['reason']}，需OCR处理")
+        return {'action': 'ocr', 'reason': cut_info['reason'], 'analysis': analysis}
+
+    cut_start = cut_info['cut_start_idx']
+    print(f"结论: 需切割 — {cut_info['reason']}")
+    print(f"切割点: 段落 #{cut_start}")
+
+    with zipfile.ZipFile(docx_path) as z:
+        doc = etree.fromstring(z.read('word/document.xml'))
+        all_files = {}
+        for name in z.namelist():
+            all_files[name] = z.read(name)
+
+    body = doc.find(f'{{{W}}}body')
+    paras = body.findall(f'{{{W}}}p')
+
+    cut_paras_xml = []
+    for i in range(cut_start, len(paras)):
+        cut_paras_xml.append(etree.tostring(paras[i], encoding='unicode'))
+
+    for i in range(len(paras) - 1, cut_start - 1, -1):
+        body.remove(paras[i])
+
+    cut_rids = set()
+    for p_info in analysis['paragraphs'][cut_start:]:
+        cut_rids.update(p_info['img_rids'])
+
+    rels_xml = all_files.get('word/_rels/document.xml.rels', b'')
+    if isinstance(rels_xml, bytes):
+        rels_xml = rels_xml.decode()
+    rid_to_media = {}
+    for m in re.finditer(r'Id="(rId\d+)"[^/]*Target="(media/[^"]+)"', rels_xml):
+        rid_to_media[m.group(1)] = f'word/{m.group(2)}'
+
+    cut_media = {}
+    for rid in cut_rids:
+        media_path = rid_to_media.get(rid)
+        if media_path and media_path in all_files:
+            cut_media[media_path] = len(all_files[media_path])
+
+    stripped_path = os.path.join(output_dir, f'{basename}_stripped.docx')
+    all_files['word/document.xml'] = etree.tostring(doc, xml_declaration=True, encoding='UTF-8', standalone=True)
+
+    with zipfile.ZipFile(stripped_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for name, data in all_files.items():
+            zout.writestr(name, data)
+
+    cutdata = {
+        'original_file': os.path.basename(docx_path),
+        'cut_start_idx': cut_start,
+        'total_paras_original': len(paras) + len(cut_paras_xml),
+        'cut_paragraphs_xml': cut_paras_xml,
+        'cut_headings': cut_info['cut_headings'],
+        'cut_media_files': list(cut_media.keys()),
+        'reason': cut_info['reason'],
+    }
+
+    cutdata_path = os.path.join(output_dir, f'{basename}_cutdata.json')
+    with open(cutdata_path, 'w', encoding='utf-8') as f:
+        json.dump(cutdata, f, ensure_ascii=False, indent=2)
+
+    stripped_size = os.path.getsize(stripped_path)
+    original_size = os.path.getsize(docx_path)
+
+    print(f"\n输出:")
+    print(f"  stripped: {stripped_path} ({stripped_size:,} bytes)")
+    print(f"  cutdata:  {cutdata_path}")
+    print(f"  大小变化: {original_size:,} → {stripped_size:,} bytes ({stripped_size/original_size:.0%})")
+
+    return {
+        'action': 'cut',
+        'stripped_path': stripped_path,
+        'cutdata_path': cutdata_path,
+        'cut_info': cut_info,
+        'analysis': analysis,
+    }
+
+
+def restore_contract(reviewed_path, cutdata_path, output_path):
+    """Restore cut content back into the reviewed file."""
+    with open(cutdata_path, 'r', encoding='utf-8') as f:
+        cutdata = json.load(f)
+
+    with zipfile.ZipFile(reviewed_path) as z:
+        doc = etree.fromstring(z.read('word/document.xml'))
+        all_files = {}
+        for name in z.namelist():
+            all_files[name] = z.read(name)
+
+    body = doc.find(f'{{{W}}}body')
+    sect_pr = body.find(f'{{{W}}}sectPr')
+
+    for para_xml in cutdata['cut_paragraphs_xml']:
+        para_elem = etree.fromstring(para_xml)
+        if sect_pr is not None:
+            sect_pr.addprevious(para_elem)
+        else:
+            body.append(para_elem)
+
+    original_dir = os.path.dirname(cutdata_path)
+    original_name = cutdata['original_file']
+    original_path = os.path.join(original_dir, original_name)
+
+    if os.path.exists(original_path):
+        with zipfile.ZipFile(original_path) as z_orig:
+            for media_file in cutdata.get('cut_media_files', []):
+                if media_file not in all_files and media_file in z_orig.namelist():
+                    all_files[media_file] = z_orig.read(media_file)
+                    print(f"  还原媒体文件: {media_file}")
+
+    all_files['word/document.xml'] = etree.tostring(doc, xml_declaration=True, encoding='UTF-8', standalone=True)
+
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for name, data in all_files.items():
+            zout.writestr(name, data)
+
+    restored_size = os.path.getsize(output_path)
+    print(f"\n=== 合同还原完成 ===")
+    print(f"还原文件: {output_path} ({restored_size:,} bytes)")
+    print(f"还原段落: {len(cutdata['cut_paragraphs_xml'])} 个")
+    print(f"还原附件: {', '.join(cutdata['cut_headings'])}")
+
+    return output_path
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage:")
+        print("  预处理: python contract_preprocess.py preprocess <input.docx> [output_dir]")
+        print("  还原:   python contract_preprocess.py restore <reviewed.docx> <cutdata.json> <output.docx>")
+        sys.exit(1)
+
+    action = sys.argv[1]
+
+    if action == 'preprocess':
+        docx_path = sys.argv[2]
+        output_dir = sys.argv[3] if len(sys.argv) > 3 else None
+        result = preprocess_contract(docx_path, output_dir)
+        print(f"\nResult: {json.dumps({k: v for k, v in result.items() if k != 'analysis'}, ensure_ascii=False, indent=2)}")
+
+    elif action == 'restore':
+        reviewed_path = sys.argv[2]
+        cutdata_path = sys.argv[3]
+        output_path = sys.argv[4]
+        restore_contract(reviewed_path, cutdata_path, output_path)
+
+    else:
+        print(f"Unknown action: {action}")
+        sys.exit(1)

skills/legal/contract-editor/scripts/numbering-diagnose.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""编号链诊断探针 — 一次性看清 docx 的自动编号/手动编号全貌。
+
+用途：合同编号疑似错乱（重复/跳号/双号）时，动手改之前必跑此脚本。
+它把三件事一次性摊开，让你判断「是我们WB改错的 / 他人修订重排的 / 还是源文件自带的潜伏自动编号」：
+  1. 每个段落：是否带 <w:numPr>(自动编号)、numId、ilvl、是否整段ins/del
+  2. numbering.xml 解析：numId→abstractNum→(numFmt, lvlText, start) —— 
+     ⚠️ start≠1 的 decimal 列表会渲染出「6、」之类的可见编号，但 run 里没有这个字！
+     这是最隐蔽的坑：源文件起草人给某段挂了 numId(start=6)，OnlyOffice 自动显示「6、售后服务」，
+     而你在末尾新增条款时只数了手打的「1 2 3 4 5」，顺手编成「6」→ 与潜伏的自动6撞号。
+  3. 每段「接受所有修订后」的可见文本（去w:del、保w:ins），近似 OnlyOffice 接受后视图
+
+用法:  python numbering-diagnose.py <contract.docx>
+.doc 先转换:  soffice --headless --convert-to docx <file>.doc
+"""
+import sys, zipfile
+from lxml import etree
+
+W = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+def text_mode(p, mode):
+    """mode='final': 接受所有修订后(去del,保ins).  mode='orig': 修订前(去ins,保del)."""
+    parts = []
+    for node in p.iter():
+        if node.tag == W + 't':
+            anc, skip = node, False
+            while anc is not None:
+                if mode == 'final' and anc.tag == W + 'del':
+                    skip = True; break
+                if mode == 'orig' and anc.tag == W + 'ins':
+                    skip = True; break
+                anc = anc.getparent()
+            if not skip:
+                parts.append(node.text or '')
+        elif node.tag == W + 'delText' and mode == 'orig':
+            parts.append(node.text or '')
+    return ''.join(parts).strip()
+
+def parse_numbering(z):
+    """返回 numId -> (numFmt, lvlText, start)  仅 lvl0(够用于条款标题层)."""
+    out = {}
+    if 'word/numbering.xml' not in z.namelist():
+        return out
+    num = etree.fromstring(z.read('word/numbering.xml'))
+    n2a = {}
+    for n in num.findall(W + 'num'):
+        ab = n.find(W + 'abstractNumId')
+        if ab is not None:
+            n2a[n.get(W + 'numId')] = ab.get(W + 'val')
+    a2fmt = {}
+    for ab in num.findall(W + 'abstractNum'):
+        l0 = ab.find(W + 'lvl')
+        if l0 is not None:
+            fmt = l0.find(W + 'numFmt')
+            txt = l0.find(W + 'lvlText')
+            st = l0.find(W + 'start')
+            a2fmt[ab.get(W + 'abstractNumId')] = (
+                fmt.get(W + 'val') if fmt is not None else '?',
+                txt.get(W + 'val') if txt is not None else '',
+                st.get(W + 'val') if st is not None else '1',
+            )
+    for nid, aid in n2a.items():
+        out[nid] = a2fmt.get(aid, ('?', '', '1'))
+    return out
+
+def main(path):
+    z = zipfile.ZipFile(path)
+    root = etree.fromstring(z.read('word/document.xml'))
+    numinfo = parse_numbering(z)
+
+    print(f"### {path}\n")
+    print("=== numbering.xml: numId -> (numFmt, lvlText, start) ===")
+    if not numinfo:
+        print("  (无 numbering.xml — 全文应为手动文本编号)")
+    for nid, (fmt, txt, st) in sorted(numinfo.items()):
+        warn = '   ⚠️start≠1 会渲染潜伏编号!' if (fmt == 'decimal' and st != '1') else ''
+        print(f"  numId={nid}: fmt={fmt}, lvlText='{txt}', start={st}{warn}")
+    print()
+    print("idx | numPr(自动)        | rendered | ins/del | 文本(接受修订后)")
+    print("-" * 92)
+    for i, p in enumerate(root.findall('.//' + W + 'p')):
+        tf = text_mode(p, 'final')
+        if not tf:
+            continue
+        npr = p.find('.//' + W + 'numPr')
+        npinfo, rendered = '—', ''
+        if npr is not None:
+            nid_el = npr.find(W + 'numId')
+            il_el = npr.find(W + 'ilvl')
+            nid = nid_el.get(W + 'val') if nid_el is not None else '?'
+            il = il_el.get(W + 'val') if il_el is not None else '0'
+            npinfo = f"numId={nid},lvl={il}"
+            fmt, txt, st = numinfo.get(nid, ('?', '', '1'))
+            if fmt == 'decimal':
+                rendered = (txt or '%1、').replace('%1', st)  # 该项首个渲染值(近似)
+            elif fmt == 'bullet':
+                rendered = '•'
+            elif fmt == 'none':
+                rendered = '(无)'
+        has_ins = p.find('.//' + W + 'ins') is not None
+        has_del = p.find('.//' + W + 'del') is not None
+        mk = ('INS' if has_ins else '') + ('/' if has_ins and has_del else '') + ('DEL' if has_del else '')
+        print(f"{i:3d} | {npinfo:18s} | {rendered:8s} | {mk:7s} | {tf[:46]}")
+    print()
+    print("判读要点:")
+    print(" - rendered 列非空 = OnlyOffice 会自动加这个编号(run里没有这串字)")
+    print(" - 手动编号: rendered='—' 且文本以「N、」开头 = 编号是写死的文字")
+    print(" - 若末尾新增条款(INS)的手打编号 与 上方某段 rendered 自动编号 相同 → 撞号")
+    print("   正确做法: 新增手打编号应接续【rendered 自动值】往下编, 不是接续最后一个手打数字")
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print(__doc__); sys.exit(1)
+    main(sys.argv[1])

skills/legal/contract-editor/scripts/onlyoffice-render.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# OnlyOffice x2t 渲染 docx → PDF
+# 用途：用Maggie/Doro实际使用的渲染引擎(OnlyOffice)把合同docx渲染成PDF，
+#       核对编号/格式的真实显示效果（与LibreOffice/python模拟可能不同，核对一律以此为准）。
+# 用法: ./onlyoffice-render.sh /path/to/合同.docx [输出PDF路径]
+#   不给输出路径时，默认输出到 同目录/同名.pdf
+# 依赖: OnlyOffice容器 nextcloud-onlyoffice-1 在运行；x2t在容器内
+#       /var/www/onlyoffice/documentserver/server/FileConverter/bin/x2t
+# 之后用: pdftotext -layout out.pdf - | grep -nE "^\s*[0-9]+、"  逐条数编号链
+#        pdftoppm -png -r 140 -f 1 -l 1 out.pdf prefix          转图发给Maggie确认
+
+set -e
+SRC="$1"
+[ -z "$SRC" ] && { echo "用法: $0 <docx路径> [输出PDF]"; exit 1; }
+OUT="${2:-${SRC%.docx}.pdf}"
+CONTAINER=nextcloud-onlyoffice-1
+TS=$(date +%s%N)
+INNAME="/tmp/render_${TS}.docx"
+OUTNAME="/tmp/render_${TS}.pdf"
+CONVXML="/tmp/conv_${TS}.xml"
+
+docker cp "$SRC" "${CONTAINER}:${INNAME}"
+docker exec "$CONTAINER" bash -c "cat > ${CONVXML} << 'EOF'
+<?xml version=\"1.0\" encoding=\"utf-8\"?>
+<TaskQueueDataConvert xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">
+<m_sFileFrom>${INNAME}</m_sFileFrom>
+<m_sFileTo>${OUTNAME}</m_sFileTo>
+<m_bIsNoBase64>true</m_bIsNoBase64>
+</TaskQueueDataConvert>
+EOF
+cd /var/www/onlyoffice/documentserver/server/FileConverter/bin && ./x2t ${CONVXML} > /dev/null 2>&1 && echo x2t_done"
+docker cp "${CONTAINER}:${OUTNAME}" "$OUT"
+docker exec "$CONTAINER" rm -f "$INNAME" "$OUTNAME" "$CONVXML" 2>/dev/null || true
+echo "渲染完成: $OUT"

skills/legal/contract-editor/scripts/strip-inherited-ins-attrs.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Post-save sweep: strip explicit attributes from WB INS runs when
+the same-paragraph original runs rely on inheritance (ea=None, hint=None, sz=None).
+
+Usage: python3 strip-inherited-ins-attrs.py <docx_path>
+
+Modifies the file in place. Run AFTER ContractEditor.save() and BEFORE
+wb-ins-font-verify.py to fix the known "ContractEditor默认sz=21与docDefaults继承冲突".
+
+The pattern: for each paragraph containing WB INS, find the first plain w:r
+(non-INS, non-DEL) as reference. If that reference run has no explicit
+eastAsia/hint/sz, strip those from all WB INS runs in the same paragraph.
+"""
+import sys
+import zipfile
+import tempfile
+import shutil
+from lxml import etree
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+
+def strip_inherited_attrs(filepath):
+    with zipfile.ZipFile(filepath, 'r') as z:
+        doc_xml = z.read('word/document.xml')
+        all_files = {n: z.read(n) for n in z.namelist()}
+
+    tree = etree.fromstring(doc_xml)
+    body = tree.find(f'{WNS}body')
+    paras = body.findall(f'{WNS}p')
+
+    fixed = 0
+    for p in paras:
+        # Find first plain run as reference
+        orig_run = None
+        for child in p:
+            if child.tag == f'{WNS}r':
+                orig_run = child
+                break
+        if orig_run is None:
+            continue
+
+        orig_rpr = orig_run.find(f'{WNS}rPr')
+        orig_rf = orig_rpr.find(f'{WNS}rFonts') if orig_rpr is not None else None
+        orig_sz = orig_rpr.find(f'{WNS}sz') if orig_rpr is not None else None
+        orig_ea = orig_rf.get(f'{WNS}eastAsia') if orig_rf is not None else None
+        orig_hint = orig_rf.get(f'{WNS}hint') if orig_rf is not None else None
+        orig_sz_val = orig_sz.get(f'{WNS}val') if orig_sz is not None else None
+
+        for ins in p.findall(f'.//{WNS}ins'):
+            if ins.get(f'{WNS}author') != 'WB':
+                continue
+            for r in ins.findall(f'{WNS}r'):
+                rpr = r.find(f'{WNS}rPr')
+                if rpr is None:
+                    continue
+                rf = rpr.find(f'{WNS}rFonts')
+                sz = rpr.find(f'{WNS}sz')
+
+                if orig_ea is None and rf is not None:
+                    for attr in ['eastAsia', 'ascii', 'hAnsi']:
+                        key = f'{WNS}{attr}'
+                        if key in rf.attrib:
+                            if orig_rf is None or orig_rf.get(key) is None:
+                                del rf.attrib[key]
+                                fixed += 1
+
+                if orig_hint is None and rf is not None and f'{WNS}hint' in rf.attrib:
+                    del rf.attrib[f'{WNS}hint']
+                    fixed += 1
+
+                if orig_sz_val is None and sz is not None:
+                    rpr.remove(sz)
+                    fixed += 1
+
+    # Save
+    tmp = tempfile.mktemp(suffix='.docx')
+    with zipfile.ZipFile(tmp, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for name in all_files:
+            if name == 'word/document.xml':
+                new_xml = etree.tostring(tree, xml_declaration=True, encoding='UTF-8', standalone=True)
+                new_str = new_xml.decode('utf-8')
+                new_str = new_str.replace(
+                    "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>",
+                    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>')
+                new_str = new_str.replace('\n', '\r\n')
+                zout.writestr(name, new_str.encode('utf-8'))
+            else:
+                zout.writestr(name, all_files[name])
+    shutil.move(tmp, filepath)
+    return fixed
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <docx_path>")
+        sys.exit(1)
+    n = strip_inherited_attrs(sys.argv[1])
+    print(f"Fixed {n} inherited attribute issues in {sys.argv[1]}")

skills/legal/contract-editor/scripts/unify-author-wb.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Unify all tracked change authors in a docx to 'WB'.
+
+Usage: python unify-author-wb.py <input.docx> [output.docx]
+If output is omitted, overwrites input.
+
+Covers: w:ins, w:del, rPrChange, pPrChange, sectPrChange,
+        tblPrChange, trPrChange, tcPrChange.
+Also fixes XML declaration (single→double quotes) for OnlyOffice compatibility.
+"""
+import sys, os, zipfile, re
+from lxml import etree
+
+WNS = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}'
+
+CHANGE_TAGS = ('ins', 'del', 'rPrChange', 'pPrChange',
+               'sectPrChange', 'tblPrChange', 'trPrChange', 'tcPrChange')
+
+def unify_author(src_path, out_path=None):
+    if out_path is None:
+        out_path = src_path
+    tmp_path = out_path + '.tmp'
+
+    zin = zipfile.ZipFile(src_path, 'r')
+    doc_xml = zin.read('word/document.xml')
+    tree = etree.fromstring(doc_xml)
+    body = tree.find(f'{WNS}body')
+
+    changed = 0
+    for tag_suffix in CHANGE_TAGS:
+        for elem in body.iter(f'{WNS}{tag_suffix}'):
+            author = elem.get(f'{WNS}author')
+            if author and author != 'WB':
+                elem.set(f'{WNS}author', 'WB')
+                changed += 1
+
+    # Serialize + fix XML declaration
+    doc_bytes = etree.tostring(tree, xml_declaration=True, encoding='UTF-8', standalone=True)
+    doc_str = doc_bytes.decode('utf-8')
+    doc_str = doc_str.replace(
+        "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>",
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>')
+
+    with zipfile.ZipFile(tmp_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.namelist():
+            if item == 'word/document.xml':
+                zout.writestr(item, doc_str.encode('utf-8'))
+            else:
+                zout.writestr(item, zin.read(item))
+    zin.close()
+    os.replace(tmp_path, out_path)
+
+    # Verify
+    z = zipfile.ZipFile(out_path)
+    vdoc = z.read('word/document.xml')
+    vtree = etree.fromstring(vdoc)
+    vbody = vtree.find(f'{WNS}body')
+    remaining = set()
+    for tag_suffix in CHANGE_TAGS:
+        for elem in vbody.iter(f'{WNS}{tag_suffix}'):
+            a = elem.get(f'{WNS}author', '')
+            if a != 'WB':
+                remaining.add(a)
+    z.close()
+
+    print(f"✅ {changed} author attributes → WB")
+    if remaining:
+        print(f"⚠️ Remaining non-WB authors: {remaining}")
+    else:
+        print(f"   All authors = WB")
+    print(f"   Output: {out_path} ({os.path.getsize(out_path):,} bytes)")
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+    src = sys.argv[1]
+    out = sys.argv[2] if len(sys.argv) > 2 else None
+    unify_author(src, out)

skills/legal/contract-pass-workflow/SKILL.md

@@ -0,0 +1,698 @@
+---
+name: contract-pass-workflow
+description: 合同审查pass后的标准操作——更新tracker、更新xlsx清单、上传Nextcloud、清缓存。Doro说pass后照此执行。
+version: 1.0.0
+tags: [合同审查, pass, tracker, xlsx]
+---
+
+# 合同审查 Pass 后标准操作
+
+## 交付文件位置（铁律，2026-06-29 Doro纠正）
+
+所有交付文件统一放在 **`Doro合同审查任务/任务交付/`（根目录）**，不放顾问单位子文件夹。
+
+- ✅ `Doro合同审查任务/任务交付/【修】合同_朱家角.docx`
+- ❌ `Doro合同审查任务/朱家角镇社区卫生服务中心/任务交付/【修】合同_朱家角.docx`
+
+workflow YAML deliverer 步骤（第210行）明确写的上传路径是根目录 `任务交付/`。如果 deliverer 或 final_review 把文件放到了子文件夹，pass 步骤0核对时必须发现并移到根目录。
+
+## 步骤0核对要点
+
+pass 步骤0的核对流程：
+1. 取原始文件名（去掉【修】/【审】前缀）
+2. 去 `Doro合同审查任务/待审查/` 确认源文件存在
+3. **确认交付文件在根目录 `任务交付/`**（不是子文件夹）
+4. 顾问单位核对（从合同正文读甲方名称）
+5. tracker 查重
+
+## 红线：验证指令 ≠ 回忆指令（2026-07-02 信任危机后确立）
+
+### 根因排查铁律：抛弃旧判断，先查“发生了什么变化”，再谈原因（2026-07-14 Doro纠正）
+
+当 Doro 明确说“去查原因”“不是让你猜测、推断”“完全抛弃此前的判断，重新核查情况”时，后续动作必须切换为**变化核查模式**，而不是继续打磨措辞、修补上一版归因。
+
+**强制步骤：**
+1. **旧判断全部作废**：停止沿用“状态漂移”“异常”“习惯变差”“元控制失效”等任何解释性语言，除非已经有直接证据支持。
+2. **先限定时间窗**：如果用户已给出时间边界（如“发生在 7 月 10 日前”），所有核查必须围绕该边界展开；边界外的改动先排除，不得混入结论。
+3. **优先查“可观察变化”而不是“解释”**：
+   - 配置文件修改时间与具体改动；
+   - workflow/queue/watchdog/notify 脚本的修改时间与新增逻辑；
+   - skill 规则文本的修改时间；
+   - gateway / auto-notify / watchdog 的退出、重启、恢复日志；
+   - tracker / queue / done / manifest 等状态文件是否出现结构变化。
+4. **汇报格式必须是“已查到的变化 / 没查到的变化”**，不能把“更可能”“像是”“说明了”写成原因结论。
+5. **只有在“变化事实”查清后，才允许进入第二步根因分析**；若变化事实尚未闭环，明确说“目前只查到这些变化，原因尚未下结论”。
+
+**禁止事项：**
+- 不断修改上一版判断的措辞，假装自己在继续调查；
+- 用“异常”“偶发”“状态不好”“坏习惯”去解释持续两天、批量失效的问题；
+- 把证据和推断混写成同一层结论；
+- 用户要求查原因时，实际只做语言收缩而不做新核查。
+
+**本会话教训：** Doro连续纠正“不是让你猜测、推断”“不是让你不断修改措辞”“要你完全抛弃此前判断，重新核查 7 月 10 日前发生了什么变化”。以后凡是原因排查任务，第一步不是解释，而是建立时间窗并枚举已发生变化。
+
+### 先查清时间窗，再查数据（2026-07-13 本会话再犯后补丁）
+
+当 Doro/Maggie 说“上周五”“今天”“昨天”“本周一”这类**相对日期**时，**第一步不是直接查数据，而是先把自然语言时间词锚定成明确的北京时间起止窗口**。没先锚时间窗，就会出现：
+- 把“上周五”理解成错误日期；
+- UTC/BJT 边界算错；
+- 用错窗口后得出“0 份”之类错误结论；
+- 之后再补查 gateway.log 才发现用户是对的，严重伤信任。
+
+**强制步骤：**
+1. 先用北京时间确认当前日期和星期；
+2. 把“上周五/今天”等词转换成**北京时间明确起止时间**；
+3. 再换算成 UTC 时间戳/窗口；
+4. 把这个时间窗写出来后，才开始查 `.meta` / gateway.log / tracker / xlsx。
+
+**执行纪律：**
+- 如果 `meta` 查不到，但 `gateway.log` 里已经出现该日文件消息证据，**不得继续说“0 份”或“没发”**；必须当场降级结论为“已证明确实发了，但文件清单仍在继续反查”。
+- 对周五这类历史批次，**至少要交叉两源**：`gateway.log` 文件消息 + tracker / xlsx / queue 痕迹，不能只信一侧。
+- 没闭环前，结论只能说“已查实部分”“尚未查实部分”，不能提前给“全部无遗漏”的总判断。
+
+**本会话教训**：周五邱律师明明发了文件，但因先把时间窗算错、又只依赖 `.meta`，错误说成“0 份”；之后从 `gateway.log` 查到 `msg=''` 文件消息才纠正。以后凡是相对日期统计任务，**先定北京时间窗口，再查数据**。
+
+## 红线：验证指令 ≠ 回忆指令（2026-07-02 信任危机后确立）
+
+### 当前交付目录全量 pass 指令（2026-07-13 Doro明确授权）
+
+当 Doro 明确下达类似指令：
+- "任务交付文件夹里所有的合同及companion，都做pass"
+- "现在这一刻，Nextcloud-任务交付里，所有的合同和companion，都做pass流程"
+
+这属于**对当前任务交付目录的全量授权**，不再局限于单份合同或单个 companion。此时必须：
+
+1. **先列出任务交付目录当前全部文件**，不要凭上一条对话里提到的那一份合同推断。
+2. **合同与 companion 都要纳入核查范围**——先查清目录里到底有哪些主合同、有哪些 companion，不能只扫主合同关键词就下结论。
+3. **主合同与 companion 的 pass 处理规则不同**：
+   - **主合同**：做完整 pass——tracker 标记 `completed`，并登记到 excel。
+   - **companion**：属于主合同的附属交付物，**不单独登记到 excel，不单独占 seq**。只在核查结果中确认其存在与关联关系，必要时体现在主合同的 pass 备注/关联记录中。
+4. **先查 tracker / xlsx 再写入**，但用户已经授权时，不要卡在"没有 tracker 记录所以我先不做"的保守口径上；对主合同应直接补建记录并完成 completed + excel 登记。
+5. **汇报时先给出全量清单，再区分主合同与 companion 的处理结果**，不能把“全部做pass”误写成“所有文件都单独登记 excel”。
+
+### 本次会话教训
+- 错误做法：只围绕白鹤这一份合同回答"已pass"，没有先把任务交付目录全量列出，遗漏了香花桥和朱家角积分项目的一整组合同及 companion。
+- 第二层错误：把 companion 当成主合同一样单独写入 tracker/xlsx，导致 seq 冲突和错误登记。
+- 正确做法：当 Doro 说"任务交付文件夹里所有的合同及companion，都做pass"时，必须把**当前任务交付目录的全部文件**作为审计范围，但**excel 只登记主合同，companion 不单独登记**。
+**凡Doro说"查""核实""核对""是不是都""有没有遗漏"→ 回复中必须先有工具调用再有结论。context记忆/session summary ≠ 查证，不可直接输出。**
+
+违反后果：Doro已明确说"到了无法信任你的程度"。这不是规则问题，是行为问题——规则早就写了（见已知坑），照样违反。
+
+四个具体失败模式（2026-07-02 同一轮对话全犯）：
+1. **拿记忆当查证**：session context有信息→直接组织成答案→包装成"查实结果"→其实没跑工具
+2. **渠道遗漏**：只查了QiuTing私信，漏了Doro私信、Doro直接Nextcloud上传、飞书等渠道
+3. **不认识自己的输出**：之前汇报过的数据（seq 216-222含重固），被追问时说"找不到"——数据一直在，没看自己历史输出
+4. **推责给用户**：找不到时直接问Doro"你记得叫什么名字吗"——把验证责任转嫁给用户。正确做法：穷尽搜索策略（换关键词、按时间批次找、按相邻seq推断、直接读xlsx逐行扫、session_search换多个query）。数据就在tracker里，是自己没认真遍历。
+
+**第4条补充（2026-07-02追加）**：被追问"你真的查了吗"→ 如果上一条回复里没有tool call，直接承认"没查，现在查"。不辩解、不包装。
+
+**唯一可接受的行为**：
+- 跑工具 → 看输出 → 写结论
+- 不确定的说不确定
+- 被追问时不防御不绕，直接承认没查到
+- 对比自己之前输出过的表格/数据，确认是否已经有答案
+
+## 恢复到workflow交付状态（2026-07-13 教训）
+
+Doro可能要求"恢复到workflow完成的状态"——意思是撤销你的手动修改，让NC上的交付文件回到workflow原始交付版本。
+
+**恢复方法（按优先级）**：
+1. **NC版本历史**：`docker exec nextcloud-nextcloud-1 ls /var/www/html/data/doro/files_versions/Doro合同审查任务/任务交付/` 找 `.v<timestamp>` 文件，最早的版本 = workflow原始交付版
+2. **`/tmp/pass_check_*` 副本**：pass流程核对时从NC拉取的副本，如果时间早于你的手动修改，就是workflow原版
+3. **练塘镇子目录副本**：部分合同在 `练塘镇社区卫生服务中心/任务交付/` 也有一份
+
+**操作**：docker cp 覆盖 → chown www-data → occ files:scan。
+
+**场景**：你手动修复了workflow交付的合同（补编号、修字体等），但Doro认为应该重新走workflow而非手动修补。恢复后等Doro进一步指示。
+
+## 前置审查（Doro要求"审查workflow修改"时触发）
+
+Doro可能在pass之前要求逐份审查workflow交付物的质量。这不是pass流程，而是**前置质量审计**，只有审计通过+手动修复后Doro才会说pass。
+
+### 审计方法论
+
+1. **区分原文修订 vs workflow修订**：用zipfile读XML，按`w:ins/@author`和`w:del/@author`区分。`author=WB`是workflow的，其余（WB-1/86187/杨丽等）是原文自带的→保持不动。
+2. **对照原文确认**：必须docker cp原文件（从NC待审查目录），转换后逐段对比，确认哪些修订是原文自带。
+3. **逐项检查清单**：
+   - INS rFonts：WB INS的rFonts属性必须与同段原文run一致（不多不少）。常见问题：多了hAnsi/cs/hint
+   - pStyle：新增条款标题的段落样式必须与原文条款标题一致（如Heading4），不能用Style15等其他样式
+   - 标题空格：原文"第六条违约责任"无空格→新增也不能有空格"第七条转包与分包"
+   - 子编号顺延：章节编号改了（七→八），内部子编号（7.1→8.1）也必须改
+   - 赔偿上限：双向条款的赔偿上限（限制甲方获赔）按规则"能删就删"
+   - 内容去重：新增保密存续等条款前，检查原文是否已有同义表述
+   - 脚注"法律顾问修订版"：**必须用修订格式**（w:ins, author=WB），不能是普通文本
+   - 文件命名：【修】+原文件名一字不动（含扩展名变化.doc→.docx）
+4. **通读全文**：接受修订后的全文必须通读，检查WB插入的内容是否与上下文语句通顺、有无重复编号（原文问题不改，但要识别）
+5. **Doro的期望**：
+   - "打开文件查清楚再回答我"→ 必须用工具完整检查后才能下结论，不能凭印象
+   - "看清楚前后文再回答我"→ 报告问题前必须理解修改点的上下文语境
+   - "有没有该加粗没加粗的"→ 格式检查要全面（bold/style/indent/spacing都要对比）
+   - "按照workflow的规则，手动修改"→ 发现问题后直接修复，不只是报告
+
+### 修复操作要点
+
+- 用zipfile+lxml直接操作XML（不用python-docx修改tracked changes）
+- 修复后的INS rFonts只保留原文有的属性（通常eastAsia+ascii）
+- 子编号顺延：原文数字可能分散在多个run中（如"7"+".1  "两个run），只需DEL+INS第一个数字run
+- P49类大段文本需精确split run（保留前后文，只DEL中间要删的部分）
+- 修复后必须python-docx打开验证
+
+## 触发条件
+Doro对已交付的合同**明确说"pass"**（可以是单份或批量）。
+
+⚠️ **绝对前提：Doro必须亲口说"pass"才能启动此流程。** 合同交付后、workflow完成后、端午节合同end后——这些都**不是**pass。不要因为合同已交付就主动查xlsx/tracker或准备pass操作。Doro没说pass之前，对交付物的一切后续操作（更新tracker、更新xlsx、查重等）都不做。
+
+⚠️ **"我满意了"≠Doro说pass（2026-07-13教训）**：即使你作为审查负责人完成了质检、修复了所有问题、对文件满意，也**绝不能自行执行pass流程**。必须等Doro明确说"pass"。2026-07-13实证：白鹤劳务派遣协议修复完毕后自行做了pass，被Doro纠正"我没说pass你做什么pass"，紧急撤销（tracker回退delivered+xlsx删行）。自主质检和pass是两个完全独立的步骤——前者是你的职责，后者是Doro的权力。
+
+2026-06-15教训：两次被Doro纠正（"我都还没说pass呢"、"今天的合同我都没说pass呢"）——agent在合同交付后主动查xlsx是否已更新、准备补写tracker，被视为越权操作。
+2026-07-13教训：白鹤劳务派遣协议自行质检完后直接执行pass，被纠正"我没说pass你做什么pass"，紧急撤销。
+
+**手动审查交付物的完整检查清单**见 `references/manual-review-checklist-0713.md`——当Doro要求"审查workflow修改的情况"时按此执行。核心：自主质检→发现问题直接修→报告→等Doro说pass。不问"需要修复吗"，不自行pass。
+
+## 特殊判定："终身不通过"
+
+Doro可能对某些合同说"终身不通过"——这意味着合同审查质量太差，**永远不会pass**。
+- **不是返工**：不是让你修了再交，而是直接否决
+- **处理方式**：在tracker中标记`status: "permanently_rejected"`，不进入pass流程
+- **反思**：必须分析为什么质量差到这个程度，是workflow哪个角色出了问题，把教训记入historical-failures
+- **不要追问Doro**：已经定性了就不要再烦，自己复盘
+
+## 操作步骤（严格按顺序）
+
+### 0. 交付物核对（写入前必做）
+
+⚠️ **PDF 批注交付件的独立核验** → 用 `scripts/verify_pdf_annotation_deliverable.py <原件> <NC交付件> [本地核验件]`：一键查 SHA256 字节一致、页数、原文未改动、批注数/author=WB、批注格式（"建议"开头无【】）、高亮几何锚定。扫描件/PDF 合同走批注模式（非 docx 修订），docx 专项检查不适用，用此脚本替代。
+
+Doro说pass后，在写tracker/xlsx之前，**必须先核对交付物与源文件的匹配关系**：
+
+1. **取原始文件名**：从交付文件名去掉`【修】`或`【无修改意见】`前缀 → 得到原始文件名
+2. **待审查目录核实**：去Nextcloud `Doro合同审查任务/待审查/` 确认该原始文件名存在。不存在则停下来排查，不继续写入
+3. **顾问单位核对**：确认要写入xlsx的顾问单位名称正确。⚠️ 不能盲信classifier的`our_party_name`——已有多次classifier误判案例（如智慧医院云项目合同classifier设为"朱家角"实际甲方是"卫健事业发展中心"）。**必须用python-docx打开合同原文，直接读取甲方名称**
+   - **⚠️ python-docx 的 `paragraph.text` 会吞掉 `w:ins`（修订插入）内容 → 读出的甲方可能是"补全前"的残缺名（2026-06-25 实证）**：当本次审查的改动之一就是"给甲方补全行政区前缀"（如 WB 修订插入「上海市青浦区」），交付件里甲方全称是「原稿可见文字 + w:ins 插入文字」拼起来的。`python-docx` 遍历 `doc.paragraphs[i].text` 时**未必包含 ins 的文字**，会让你误以为甲方还是缺前缀的简称。**核甲方全称必须把 `w:ins` 算进去**：用 zipfile 读 `word/document.xml`、对甲方那一段 `''.join(t.text for t in p.iter('{...}t'))`（`w:t` 不分 ins/非 ins，全收），或干脆遍历所有 `w:ins` 看 author=WB 插了什么。2026-06-25 项目终止协议书：`paragraph.text` 显示甲方「华新镇社区卫生服务中心」，实际交付件 w:ins 补了「上海市青浦区」，全称应是「上海市青浦区华新镇社区卫生服务中心」——只看 `.text` 就会把残缺简称写进 tracker/xlsx。**写 party 前先确认你读的是"接受修订后"的完整甲方名。**
+   - **顾问单位名称空白的特殊情况（按合同来源分两路，2026-06-25 补全）**：合同正文里顾问单位名称是空白下划线（待签时填）时，无法从正文确定。**先分清这份合同是谁的任务线**，再决定问谁——别默认是邱律师：
+     - **邱律师批量线**（health-centers）：私信邱律师询问归属。私信用 `python3 ~/.hermes/scripts/wecom_dm.py --to qiuting --text "…"`（或 `_send_wecom(extra,'QiuTing',msg)`），**不用** `send_message(target='wecom:X')`（静默回退 home channel）。暂停 pass（不写 tracker/xlsx），邱律师回复后从步骤1继续；Doro 说过"邱律师回复了就直接补上 我不管了"——回复后自主补登记，不再找 Doro。
+     - **Doro 直接指派 / 非批量线**（如幼儿园保密协议、劳动合同等非卫生中心合同）：**问发起 pass 的人本人**（通常就是正在对话的 Doro），不要问邱律师，也不要自己瞎填占位符。
+     - ⚠️ **绝不用泛指占位符当 party 写进 tracker/xlsx**（如"幼儿园（园方，名称空白待填）"）——2026-06-25 教训：园名空白我写了这种占位符，Doro 直接纠正"顾问单位是平和学校"。空白就停下来问准确**法律主体全称**，确认后再写。
+   - **同名/近名主体消歧（2026-06-25 教训，写 party 前必做）**：拿到顾问单位名后，先 `openpyxl` 扫 xlsx 第 C 列看清单里**是否已有多个相似名**的主体——它们往往是**不同法律实体**，不能混用。本会话清单里同时有「上海青浦平和**幼儿园有限公司**」(seq13/15) 和「上海青浦平和**双语学校**」(seq44/210/211)，一个园、一个校，是两个主体。判别靠**合同内容性质**：这份通篇"幼儿园/幼儿就读/保教费"→幼儿园主体；但既然清单里并存多个近名实体，**最终仍用 `clarify` 让发起人拍板一个准确全称**，并复用清单里既有的写法（保持前后一致，别造新写法）。
+   - **更正已写错的 party（两处同步）**：若 tracker/xlsx 已写入后才被纠正，两处都要改：tracker 用原子写回（tempfile+rename）改对应 seq 的 `party`；xlsx 改第 C 列后重新 `docker cp` 上传 + `occ files:scan` + 清 OnlyOffice 缓存重启；最后从线上重新拉 xlsx + 读 tracker **核对两处一致**才算完成。
+4. **查重**：在tracker中检查是否已有相同 `original_filename` + `party` 的completed记录。有则为重复交付，不再写入
+
+以上4步全部通过，才进入步骤1写tracker。任何一步不通过，停下来排查原因。
+
+**注意**：Doro批量pass时可能列出审查意见文件（如"朱家角审查意见-xxx"、"采购协议-审查意见"）。这些是主合同的附属交付物，**默认不单独写tracker/xlsx条目**。只需为主合同文件（【修】前缀的）写tracker和xlsx。审查意见文件如果不在交付目录中（可能已被清理或因classifier误判未生成），不影响主合同的pass流程——跳过即可，不需要报错或追问Doro。
+
+### 例外：用户明确说“任务交付文件夹里所有的合同及companion，都做pass流程”时（2026-07-13 Doro明确）
+当 Doro 用**当前任务交付目录全量授权**的口径下指示：
+- “任务交付文件夹里所有的合同及companion，都做pass”
+- “现在这一刻，Nextcloud-任务交付里，所有的合同和companion，都做pass流程”
+
+此时必须把 companion **纳入 pass 核查范围**，但仍要遵守：
+- **companion 不是独立合同，不单独登记 excel，不单独占 seq**；
+- tracker/xlsx 的登记主体仍然是**主合同**；
+- companion 的处理应当体现在“该主合同已连同 companion 一并核查/补做pass”的结果里，而不是把每个 companion 当主合同单独建台账。
+
+**执行顺序**：
+1. 先把当前 `任务交付/` 目录全部文件列出来，不能只围绕当前对话那一份合同；
+2. 再识别哪些是主合同、哪些是 companion；
+3. 主合同逐份做 pass / tracker / xlsx；
+4. companion 只做挂靠核查，不单独占 excel 行；
+5. 回复时明确区分“主合同已登记几份、companion 已核查几份”，不要混成一类。
+
+**2026-06-11教训**：安全测试合同因跳过核对，第一次把原始文件名写进xlsx文件名列（没有【修】前缀），发现后补写但未清理错误记录，导致tracker和xlsx各多一条重复数据。
+**2026-06-12教训**：手动写xlsx时列顺序写反（日期和序号对调、文件名列写成原始文件名而非delivered_filename、顾问单位列写成"已完成"状态文字）。**写xlsx前必须先读上一行确认列顺序**，不要凭记忆。正确列顺序：A=序号, B=日期, C=顾问单位, D=合同名称, E=文件名(delivered_filename)。
+
+### 1. 更新 Tracker JSON
+
+路径：`~/.hermes/data/contract-tracker.json`
+
+#### 状态流转（新增 `delivered` 中间态，2026-07-02 确立）
+
+```
+文件到达 → workflow审查 → deliverer交付成功 → queue-runner写入 status=delivered
+                                                       ↓
+                                          Doro说pass → status=completed
+                                                       ↓
+                                              24h后 → cleanup清理
+```
+
+**三道防线防重复：**
+| 检查点 | 逻辑 |
+|--------|------|
+| queue-runner 启动前 | 查 tracker，`delivered` 或 `completed` → 直接 SKIP 并移入 done/ |
+| watchdog resume 前 | 查 tracker，已交付的 thread 不恢复 |
+| deliverer 写入时 | exists 检查，同文件不重复写入 |
+
+#### Pass 时的写入逻辑
+
+**如果 tracker 中已有该 `original_filename` 且 `status=delivered`** → 更新该记录为 `completed`，补全 `seq`/`party`/`contract_name`/`delivered_filename`/`converted_filename`/`xlsx_updated_at`/`cleaned=false`。
+
+**如果 tracker 中没有记录**（旧合同、手动审查等情况）→ 新建完整记录，直接 `status=completed`。
+
+完整记录示例：
+```json
+{
+  "original_filename": "消防设施检测服务合同（练塘卫生院）.doc",
+  "delivered_filename": "【修】消防设施检测服务合同（练塘卫生院）.docx",
+  "converted_filename": "消防设施检测服务合同（练塘卫生院）.docx",
+  "party": "上海市青浦区练塘镇社区卫生服务中心",
+  "contract_name": "消防设施2026年度检测服务合同",
+  "seq": 175,
+  "status": "completed",
+  "delivered_at": "2026-06-09T18:30:00+08:00",
+  "xlsx_updated_at": "2026-06-09T20:09:00+08:00",
+  "cleaned": false
+}
+```
+
+字段说明：
+- `original_filename`：邱律师发来的原始文件名（可能是.doc）
+- `delivered_filename`：交付到任务交付目录的文件名（【修】前缀）
+- `converted_filename`：workflow转换后的.docx文件名（原始是.doc时有值，否则空字符串）。**来源**：workflow的`converted_filename`字段会从classifier一路传递到deliverer/final_review输出。pass流程必须从workflow输出中提取并写入tracker。如果workflow输出中没有此字段（旧workflow跑的合同），则根据original_filename判断：以`.doc`结尾的，converted_filename = 同名`.docx`；以`.docx`结尾的，converted_filename = 空字符串
+- `seq`：合同审查清单中的序号
+- `delivered_at`：workflow 交付完成时间（queue-runner 写入）
+- `xlsx_updated_at`：pass 时写入，北京时间ISO格式，清理脚本据此计算24h
+- `cleaned`：清理脚本执行后改为true
+
+**写入方式**：先写临时文件再rename（原子操作），防止进程中断导致JSON损坏。
+
+```python
+import json, os, tempfile
+from datetime import datetime, timezone, timedelta
+
+BJT = timezone(timedelta(hours=8))
+tracker_path = os.path.expanduser('~/.hermes/data/contract-tracker.json')
+
+# 读取现有tracker
+if os.path.exists(tracker_path):
+    with open(tracker_path, 'r') as f:
+        tracker = json.load(f)
+else:
+    tracker = {"contracts": []}
+
+now = datetime.now(BJT).isoformat()
+
+# 查找是否已有 delivered 记录
+existing = None
+for c in tracker["contracts"]:
+    if c.get("original_filename") == original_filename:
+        existing = c
+        break
+
+if existing and existing.get("status") == "delivered":
+    # 已有 delivered → 更新为 completed（补全字段）
+    existing["status"] = "completed"
+    existing["delivered_filename"] = delivered_filename
+    existing["converted_filename"] = converted_filename
+    existing["party"] = party
+    existing["contract_name"] = contract_name
+    existing["seq"] = seq
+    existing["xlsx_updated_at"] = now
+    existing["cleaned"] = False
+elif existing and existing.get("status") == "completed":
+    # 已经 completed → 查重命中，不重复写入
+    pass
+else:
+    # 无记录 → 新建（旧合同/手动审查走这条路）
+    tracker["contracts"].append({
+        "original_filename": original_filename,
+        "delivered_filename": delivered_filename,
+        "converted_filename": converted_filename,
+        "party": party,
+        "contract_name": contract_name,
+        "seq": seq,
+        "status": "completed",
+        "xlsx_updated_at": now,
+        "cleaned": False
+    })
+
+# 原子写入
+fd, tmp = tempfile.mkstemp(dir=os.path.dirname(tracker_path), suffix='.json')
+with os.fdopen(fd, 'w') as f:
+    json.dump(tracker, f, ensure_ascii=False, indent=2)
+os.replace(tmp, tracker_path)
+```
+
+### 2. 更新合同审查清单 xlsx
+
+路径（Nextcloud）：`Doro合同审查任务/合同审查清单.xlsx`
+
+⚠️ **铁律（2026-07-03覆盖事故后确立）：写xlsx前必须从Nextcloud实时拉取最新版本，禁止使用/tmp或本地任何已有的xlsx文件。** 违反此规则会用旧版覆盖新版，导致其他session已登记的记录丢失（2026-07-03实证：用240行旧文件覆盖了252行最新版，丢失12条记录）。
+
+**强制检查流程**：
+1. `docker cp` 从NC拉取 → 保存到 `/tmp/合同审查清单_LIVE.xlsx`（带LIVE后缀避免与残留文件混淆）
+2. 打开后先读 `ws.max_row` 和最后一行的seq → 打印确认
+3. 如果发现本地已有同名文件，**必须删除后重新拉取**，不得复用
+4. 追加新行后上传
+
+步骤：
+1. **从Nextcloud下载最新xlsx（必须实时拉取，禁止复用本地文件）**
+2. 用openpyxl追加行（序号、日期、顾问单位全称、合同名称、文件名）
+3. 从上一行复制字体和对齐样式（用copy()）
+4. border用Side对象重建（不用ref_cell.border直接赋值，会报unhashable错误）
+5. 保存后上传回Nextcloud
+6. 执行files:scan + 清OnlyOffice缓存
+
+```bash
+# 下载（铁律：必须每次实时拉取，rm掉旧文件防止复用）
+rm -f /tmp/合同审查清单_LIVE.xlsx
+docker cp nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx /tmp/合同审查清单_LIVE.xlsx
+sudo chown maggie:maggie /tmp/合同审查清单_LIVE.xlsx
+
+# 上传
+docker cp /tmp/合同审查清单_LIVE.xlsx nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx
+# 上传
+docker cp /tmp/合同审查清单_LIVE.xlsx nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx
+python3 -c "import openpyxl; ws=openpyxl.load_workbook('/tmp/合同审查清单_LIVE.xlsx').active; print(f'NC当前版本: {ws.max_row}行, 最后seq={ws.cell(ws.max_row,1).value}')"
+
+# 上传
+docker cp /tmp/合同审查清单_LIVE.xlsx nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx
+docker exec nextcloud-nextcloud-1 chown www-data:www-data /var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx
+docker exec -u www-data nextcloud-nextcloud-1 php occ files:scan --path="doro/files/Doro合同审查任务/合同审查清单.xlsx"
+
+# 上传后验证（write-read-verify，防止覆盖事故）
+rm -f /tmp/合同审查清单_VERIFY.xlsx
+docker cp nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx /tmp/合同审查清单_VERIFY.xlsx
+python3 -c "import openpyxl; ws=openpyxl.load_workbook('/tmp/合同审查清单_VERIFY.xlsx').active; print(f'上传后验证: {ws.max_row}行, 最后seq={ws.cell(ws.max_row,1).value}')"
+
+# 清OnlyOffice缓存
+docker exec nextcloud-onlyoffice-1 bash -c 'rm -rf /var/lib/onlyoffice/documentserver/App_Data/cache/files/data/*'
+docker restart nextcloud-onlyoffice-1
+```
+
+### 3. 确认并汇报
+
+向Doro确认已标记completed，告知清单已更新到第几条。
+
+### 批量pass后的登记完整性审计（2026-06-15教训）
+
+⚠️ **Doro说\"都pass了\"或\"看下是否都走了pass流程\"时，必须把每一份pass的合同逐一对照 tracker JSON 和 xlsx 两个存储，找出缺漏——不能假设\"workflow跑完了/交付了\"就等于\"登记完整\"。**
+
+2026-06-15教训：6份合同队列全部跑完并交付，Doro说6份都pass。实际核对发现只有2份（端午节、医疗急救招聘）走了完整pass流程，另外4份（金泽蛋糕、赵巷消防、练塘健康积分、徐泾维保）tracker和xlsx**全都没登记**。Doro主动提醒\"excel登记是不够的\"。原因：交付由workflow的final_review完成，但pass流程（写tracker+xlsx）是独立的人工步骤，前面几份漏做了。
+
+**审计脚本逻辑**（用openpyxl+json对照）：
+1. 列出本批次所有pass合同的 `delivered_filename`（从任务交付目录或Doro的pass消息提取）
+2. 读 xlsx 第E列（文件名列）建一个 set
+3. 读 tracker.json 的 `contracts[].delivered_filename` 建一个 set
+4. 逐份合同检查：`in xlsx?` + `in tracker?`，打印缺失矩阵
+5. 对缺失的合同，**完整补走步骤0（待审查核实+正文读甲方+查重）→ 步骤1（tracker）→ 步骤2（xlsx）**，不能只补一个存储
+6. 补完后重新跑一遍审计脚本，确认6份全部 ✅ xlsx + ✅ tracker
+
+**xlsx与tracker必须成对存在**：xlsx是给人看的登记，tracker是给cleanup cron用的。只有xlsx没tracker→文件永远不被自动清理；只有tracker没xlsx→Doro的清单缺条目。审计时两个都要查。
+
+**openpyxl写xlsx的权限陷阱**：从Nextcloud用`sudo cp`下载的xlsx属主是root，openpyxl保存时报`PermissionError`。先`sudo chown maggie:maggie`改属主到当前用户的可写副本再操作。
+
+## 触发模式
+
+Doro会**回复引用**某条交付通知消息并说"pass"。可能是单份也可能批量（"四份都pass"）。
+- 引用的消息中包含交付文件名，从中提取合同信息
+- 批量pass时逐份处理，每份都写tracker+xlsx
+
+### 审查意见文件的处理
+Doro可能把审查意见文件（如"朱家角审查意见-XXX.docx"、"采购协议-审查意见.docx"）也列入pass清单。这些是合同的伴随交付物，**不需要单独的tracker条目和xlsx行**——它们跟随主合同的tracker记录：
+- 主合同"【修】XXX.docx" → 写tracker + 写xlsx
+- 伴随审查意见文件 → 不写tracker，不写xlsx
+- 清理时：审查意见文件跟随主合同一起清理
+
+### Classifier甲方误判的pass处理（2026-06-12教训）
+当workflow classifier误判了顾问单位（如把"卫健事业发展中心"误判为"朱家角"），pass流程写tracker/xlsx时必须用**合同正文中的真实甲方名称**，不能用classifier的`our_party_name`。
+- 步骤0核对时用python-docx读取合同正文前30段，找甲方全称
+- tracker的`party`字段和xlsx的"顾问单位"列写真实甲方
+
+## 清理cron配套信息
+- Cron job name: `contract-cleanup`，job_id: `4636467b715d`
+- 脚本路径: `~/.hermes/scripts/contract-cleanup.py`
+- 调度: 每小时，no_agent静默模式
+- 逻辑: 读tracker → 找completed + xlsx_updated_at超24h + cleaned=false → docker exec删Nextcloud待审查/和任务交付/中的文件 → 标记cleaned=true → files:scan
+- 安全: 只删tracker中精确记录的文件名，不通配。xlsx在上一级目录碰不到。JSON损坏时静默不操作。原子写入(tempfile+rename)
+- **.doc→.docx转换残留（2026-06-11发现+修复）**：原始文件为`.doc`时，workflow会用libreoffice转换为`.docx`副本放在待审查目录。cleanup脚本已有`converted_filename`字段的读取逻辑（第113-116行），但旧workflow跑的合同tracker中缺少此字段导致转换文件残留。**治本修复**（2026-06-11已实施）：在review-contract.yaml的classifier procedure中添加`converted_filename`记录步骤，从classifier→reviewer→editor→deliverer→final_review全链路传递该字段。pass流程写tracker时从workflow输出中提取。cleanup脚本自动生效。
+- **手动批量清理（Doro授权模式）**：Doro可能要求按日期批量清除旧文件（不走tracker逻辑），此时按修改时间（stat %Y）过滤，在Nextcloud容器内执行rm，完成后files:scan+清OO缓存。2026-06-11执行过一次：保留6月10日及之后的文件，删除之前的全部（待审查11个+任务交付179个）。
+
+## 已知坑
+
+- **时间窗不能先拍脑袋，必须先用工具确认当天与"上周五"的北京时间边界（2026-07-13 再犯后补强）**：用户要求"查看北京时间上周五及今天，邱律师（查sender id）发了多少合同"时，不能直接按自己理解硬算时间窗，更不能在没交叉验证前就下"周五=0份"结论。必须至少两步核对：①先用 `TZ='Asia/Shanghai' date` 确认当前北京时间与星期；②把北京时间窗口换算成 UTC 后，再同时查 `.meta` 和 `gateway.log`。**只要 gateway.log 已出现 QiuTing 的空消息（msg=''）文件记录，就不能再说该时段 0 份。**
+
+- **查"邱律师发了多少合同"必须双源交叉，不可只靠 cache meta（2026-07-13 教训）**：仅查 `~/.hermes/cache/documents/*.meta` 可能漏掉周五文件或误判为 0。标准做法：
+  1. `.meta`：按 `sender_id == QiuTing` + 北京时间窗口换算后的 UTC 区间统计
+  2. `gateway.log`：按同一时间窗 grep `platform=wecom user=QiuTing chat=QiuTing msg=''`，这是文件消息的一手证据
+  3. tracker + xlsx：核对这些文件是否都 workflow 完成、是否都 pass、是否都登记 excel
+  4. **没有把两源对齐前，不得下"都完成了/没有遗漏"结论**
+
+- **被 Doro 说"胡说八道，重新查，查明情况再说"时，表示你刚才的结论缺乏证据链**：此时必须回退到原始数据源重查，不得只改措辞继续硬答。正确做法：先承认上一条没查明，再用不同数据源（如从 meta 转到 gateway.log）交叉验证。
+- **审查workflow交付物时必须区分原文自带修订 vs WB修订（2026-07-13 Doro指示）**：Doro要求"对照原文件，WB-1如果是原文自带修订，保持不动。你只需要看workflow是不是准确遵守了workflow的规则，包括命名规则"。具体方法：①用zipfile读原文件（待审查目录）的revision authors，确认哪些author是原文已有的 ②读交付件，按author过滤只看WB的修订 ③逐条核对WB修订是否符合审查规则 ④原文自带的修订（其他author）不评价、不报告为问题。**常见误判**：把原文WB-1的修订当成workflow的WB修订来审查——必须先确认author再下结论。
+
+- **核查汇报必须先用工具验证再说（2026-07-01+07-02 升级为顶部红线）**：详见本skill顶部「红线：验证指令 ≠ 回忆指令」章节 + `references/audit-methodology.md`。2026-07-02 同一轮对话中此规则被违反4次，导致Doro信任破裂（"到了无法信任你的程度"）。不再重复列举——执行时加载顶部红线即可。
+
+- **"确定吗？再仔细查实"（2026-07-02 追加）**：Doro说"确定吗""再仔细认真查实"时，意思是**上一条回复的结论不够可信/不够深入**。正确做法：不要只是重复上一轮的输出，而是用不同角度/更深层的工具去交叉验证。具体：①查session_search看是否有其他session做过相同操作 ②查uwf step list确认每个thread走到了哪一步 ③确认通知确实被发出（session中有_send_wecom的tool call记录）而非假设。核心原则：**每一条"确认X发生了"的结论，都必须有对应的工具调用输出作为证据。**
+
+- **文件"消失"的排查思路（2026-07-01 教训）**：Doro发现待审查/交付目录文件不在时，不要急着说"被误删"。先排查：①tracker 的 `cleaned` 字段是否已为true（cron清理了）→ 不可能不到24h；②auto_notify 是否正常工作（文件可能从来没上传到待审查目录，workflow直接从cache路径读文件完成审查，但Doro在Nextcloud看不到）；③是否是手动操作中 `docker exec rm` 删了。根因很可能是"从来没上传到待审查"而不是"上传后被删了"。
+
+- **交付件被 Doro 手动编辑后大小/内容会变 —— pass 时不覆盖、只登记（2026-06-23 实证）**：Doro 收到交付件后可能自己在 OnlyOffice 里编辑（删掉部分批注内容、改条款等），导致 Nextcloud 上的交付文件大小/字节/md5 与 workflow 原始交付件不同；且 OnlyOffice 后台处理期间文件**大小会持续变化**，docker cp 出来用 pymupdf/python-docx 读可能是 0 页/0 批注的中间态。**看到交付件与你核验时不一致，先确认是不是 Doro 自己改的，绝不要当成文件损坏去"修复"或用本地完整版覆盖。** Doro 说 pass 后：以 Doro 改后的版本为准，只写 tracker+xlsx 登记，**不触碰交付目录里的文件**。2026-06-23 教训：交付 PDF 从 20MB 变 3.5MB 且持续变化，我误判损坏、准备用本地版覆盖，Doro 说"是我删除了一些内容，你直接做 pass 就可以"。
+
+- **PDF 扫描件合同走批注模式，不 OCR 转 docx（2026-06-23 Doro 明确）**：收到扫描件 PDF 合同（无文字层）时，**不要纠结"OCR 转 docx 才能修订"**——workflow 对 PDF 用**批注模式**审查（高亮 Highlight + 批注气泡 Text 配对，author=WB），原文零污染，这是正常流程（seq=201 朱家角.pdf、seq=207 阳澄湖团建.pdf 都是 PDF 批注交付）。Doro 原话"PDF 的修改使用批注，这是 workflow 的正常流程"。PDF 交付件**核验/pass 时**：核批注数/author/高亮锚定位置/原文页数不变，**不套用** INS/DEL/字号/numPr 那套 docx 专项检查（final_review 对 PDF 会自动判定这些不适用）。
+
+- **交付文件位置：根目录 `任务交付/` 是正确的（2026-06-29 确认）**：workflow deliverer 明确写着上传到 `Doro合同审查任务/任务交付/`（根目录）。不要把文件移到顾问单位子文件夹——那里不是交付目的地。pass 流程步骤0核对时，交付文件应该在根目录 `任务交付/` 中。如果 deliverer 同时上传到了子文件夹（如 final_review 越权重复上传），子文件夹里的是多余的，应清理。
+
+- **final_review 越权重复上传（2026-06-29 教训）**：workflow 中上传是 deliverer 的职责，final_review 只负责质量检查和通知 Doro。但 LLM 执行 final_review 时可能越权上传文件（到子文件夹而非根目录 `任务交付/`），且使用完全不同的命名格式。**判别**：`stat` 比较文件大小，同内容两份不同名=重复。**处理**：保留 deliverer 上传的（【修】/【审】+ 原始文件名），删除 final_review 额外上传的。**根因**：review-contract.yaml 的 final_review procedure 需修改，明确禁止上传动作（待 WeiWei 实施）。
+
+- **审查意见标题空壳（2026-06-29 教训）**：workflow editor 生成的审查意见文档标题是"关于《合同》的审查意见"——"《合同》"是占位符，没有替换为实际合同名称。classifier 已正确提取了 `contract_title`，但 editor 生成审查意见时没有填入。**pass 流程必须检查审查意见标题**：如果标题是"关于《合同》的审查意见"，需要手动修正为"关于《{合同实际名称}》的审查意见"。修正方法：用 zipfile + lxml 读 document.xml，找到标题段落的所有 `w:t` 节点，第一个设为完整标题，其余清空。
+
+- **【审】审查意见文件缺失（2026-06-30 发现）**：deliverer 有时只上传【修】修订版而没有上传【审】审查意见文件。**排查**：`sudo find .../任务交付/ -name "【审】*"` 检查是否有对应的审查意见。**处理**：如果缺失，需要手动生成或报告Doro确认是否需要补做。审查意见是companion文件，不影响主合同的pass流程（不需要tracker/xlsx条目），但Doro可能期望看到。
+- **Workflow常见格式缺陷清单（2026-07-13 审计总结，详见 `references/pre-pass-audit-checklist-20260713.md`）**：
+  1. WB INS rFonts多余属性（hAnsi/cs/hint）——每份都有，每次审计必查必清
+  2. 新增条款标题pStyle错误（用了Style15而非Heading4等）
+  3. 新增标题带空格（"第七条 转包"应为"第七条转包"）
+  4. 子编号未顺延（只改了章编号，没改内部X.Y编号）
+  5. 赔偿上限遗漏（双向条款的20%上限未删）
+  6. 保密存续重复插入（原文已有同义表述）
+  7. 脚注未用修订格式
+
+- **同模板合同修订一致性（2026-07-03 Doro确认：手动调整）**：不同顾问单位提交审查的合同若为相同模板，修订需保持一致（规则9已有）。但不改workflow自动化逻辑——Doro指出不一致时手动调整即可，避免矫枉过正。不需要template_type标签或修订库。
+
+- **非合同文件进入workflow审查（2026-07-01 香花桥招标需求实证）**：classifier识别出"招标需求文件"但仍走了完整review+edit流程并交付了修订版。Doro判定此类文件无需审查，直接通知邱律师。**已修auto_notify加L1文件名预筛**（关键词：招标需求/技术方案/报价单等）。但classifier兜底层未修——仍然会把非合同当合同审。根因：workflow的routing graph没有从classifier直接到$END的non-contract路径。**pass前排查**：如果交付物对应的原始文件明显不是合同（招标需求/投标文件/会议纪要等），直接删除交付物并通知邱律师，不做pass。
+
+- **审查意见文件是错误交付物（2026-07-01 发现）**：workflow 有时会生成不该有的审查意见文件（如合同已被其他thread审查过、或classifier误判导致多生成）。**pass前排查**：检查任务交付目录中是否有不属于本次审查的【审】文件。如果是错误交付物（如旧版残留、重复审查产物），直接删除不pass。判断标准：审查意见的标题和内容是否对应本次审查的合同，标题是否是"关于《合同》的审查意见"（占位符）。
+- **cleanup脚本不处理tracker顶层"ready"条目 + 不清理本地目录（2026-07-03 查明根因）**：`contract-cleanup.py` 只遍历 `tracker["contracts"]` 数组中 `status=completed` + `cleaned=False` 的条目。但以下两类文件不会被清理：
+  1. **Tracker顶层字典键**（status=ready的条目）：这些是workflow跑完但尚未被Doro pass的合同，存储在tracker的顶层键而非contracts数组里。cleanup脚本看不到它们。Doro pass后，pass流程会把它们从顶层搬到contracts数组并标记completed——此时cleanup才能处理。**如果pass流程有bug没搬进contracts数组，文件永远不会被清理。**
+  2. **本地 `~/.hermes/shared/Doro合同审查任务/待审查/` 目录**：cleanup脚本只删Nextcloud容器内的文件（`docker exec rm`），本地shared目录的副本无人管理。这些是auto_notify上传NC后留下的本地副本——NC侧被cleanup清了，本地的永远残留。
+  - **诊断方法**：`ls ~/.hermes/shared/Doro合同审查任务/待审查/` 如果有文件，且对应的tracker条目已经completed/ready，就是此bug。
+  - **临时清理**：确认文件在tracker中已completed后，手动 `rm` 本地副本即可。
+  - **根治**：cleanup脚本需要增加两段逻辑：①遍历tracker顶层ready条目（Doro已pass但pass流程漏搬的）②清理本地shared/待审查/中已completed的文件。
+
+- **沟通时间统一使用北京时间（2026-07-03 Doro多次纠正）**：所有对外沟通（包括向Doro汇报workflow状态、文件接收时间等）一律使用北京时间。服务器UTC时间仅在内部日志/脚本中使用，不对用户展示。
+
+- **Doro说"查清楚"/"你去查原因"——必须用工具验证后再给结论**：Doro要求查证时，不能凭记忆或context summary回答。必须实际调用工具（session_search、terminal读文件/目录、tracker等）取得证据后再汇报。2026-07-13教训：被要求"查清楚我哪些说了pass"时，需要在本session对话记录中找到Doro的原话，不能凭印象列清单。
+
+- **脚注"法律顾问修订版"必须用修订格式（2026-07-13 Doro纠正）**：添加页脚文字时，必须包裹在`w:ins`元素中（author=WB），不能作为普通文本直接写入。OnlyOffice/Word中显示为带修订标记的新增内容。实现方式：用python-docx添加footer文本后，再用zipfile+lxml找到footer XML中的对应run，包裹进`w:ins`元素。
+
+- **交付件字体大小不一致（2026-07-01 Doro纠正，根因细化）**：有两种常见成因：
+  1. **段内混用**：同一段落内不同run使用不同字号（如sz=21和sz=24混用）。修复：找dominant size统一。
+  2. **INS-only新段落缺sz**（更隐蔽）：`add_clause`插入的全新段落，原文docDefaults无sz定义或sz≠邻居段落的显式sz。新段落INS run不写sz→继承docDefaults→与显式sz=24的邻居段落不一致。**诊断**：找所有INS-only段落（整段只有w:ins），检查其run的rPr是否有sz，再对比前后段落的sz。缺sz且邻居有显式sz=补上。
+  3. **numPr叠加**：加了手动编号但没去掉原自动编号→显示"1. 第一条"。修法见contract-editor skill的"strip numPr"规则。
+
+- **deliverer 重复上传（同内容两份不同名）（2026-06-29 教训）**：deliverer 可能对同一合同上传两次，文件大小完全一致说明内容相同。**判别**：`stat` 比较文件大小。**处理**：保留命名规范的那份（【修】/【审】+ 原始文件名），删除另一份。
+
+- **原文件自带【修】前缀时命名错误（2026-07-13 璞石合同实证）**：邱律师发来的文件本身已有【修】前缀（如`【修】练塘-硬件购销合同-璞石医疗2026.7.13.wps`），workflow按规则应生成`【修】【修】练塘-...docx`（原文件名一字不动，前面再加【修】），但实际只生成了`【修】练塘-...docx`（吞掉了原文的【修】前缀）。**审查时判别**：原文件名含【修】时，交付文件名应出现两个【修】。只有一个=workflow命名错误。**根因**：workflow的命名逻辑strip了原文件名中已有的【修】前缀后再加自己的。
+
+- **Cache hash前缀混入交付文件名（2026-06-30 实证）**：deliverer 有时把 cache 文件名直接当交付文件名上传，产生类似 `【修】doc_0ad4ee63bff5_印刷品制作合同2026.6(1).docx` 的文件名。**判别**：文件名含 `doc_[a-f0-9]{12}_` 模式。**处理**：删除带 hash 前缀的那份，保留正确命名的（`【修】印刷品制作合同2026.6(1).docx`）。**根因**：deliverer 从 cache 复制文件时没有去掉 cache hash 前缀重命名。
+
+- **companion 文件（审查意见/流程单）不会被 cleanup 自动清理 → 永久残留孤儿（2026-06-21/29 实证）**：`contract-cleanup.py` 只删 tracker 里 `original_filename`/`converted_filename`/`delivered_filename` 三个字段精确匹配的文件。companion 从不进 tracker → 主合同被清理后 companion 永远残留。**排查**：运行 `references/cleanup-audit.py` 审计脚本，列出所有 not-in-tracker 的文件。**应急清理（Doro 授权后）**：
+  ```bash
+  # 必须搜索所有任务交付路径（根目录+顾问单位子目录都可能有）
+  sudo docker exec nextcloud-nextcloud-1 find /var/www/html/data/doro/files/Doro合同审查任务/ -path "*任务交付*" -name "*审*意见*"
+  # 确认后逐个删除
+  sudo docker exec nextcloud-nextcloud-1 rm -f "<path1>" "<path2>" ...
+  # 扫描+清缓存
+  sudo docker exec -u www-data nextcloud-nextcloud-1 php occ files:scan doro --path="/doro/files/Doro合同审查任务/"
+  docker exec nextcloud-onlyoffice-1 bash -c 'rm -rf /var/lib/onlyoffice/documentserver/App_Data/cache/files/data/*'
+  docker restart nextcloud-onlyoffice-1
+  ```
+  ⚠️ Companion 可能同时存在于根目录 `任务交付/` 和顾问单位子目录（如 `朱家角镇社区卫生服务中心/任务交付/`）——find 命令用 `-path "*任务交付*"` 通配搜索确保不遗漏（2026-07-06 实证：肃言/恭兴审查意见各在两个位置共4份）。
+  **治本方案见 `references/companion-cleanup-proposal.md`**，需 WeiWei 决策后实施。
+  
+  - **Companion 判定不能靠想当然命名（2026-07-13 白鹤劳务派遣协议教训）**：Doro说“交付文件夹里的合同及companion全部做pass”时，**先查清交付文件夹里到底有哪些相关文件，再决定有没有 companion**。不要因为很多合同通常会带审查意见，就默认本案也有；也不要只看主文件名一次就下结论。正确顺序：①先在 `任务交付/` 中做**宽匹配扫描**（合同名关键词、当事人名关键词、业务关键词都要扫）②再把整个 `Doro合同审查任务/` 目录补扫一遍，确认没有藏在别的子目录里的 companion ③最后再对 tracker+xlsx 核对是否已有 completed 记录。**如果实扫结果只有主合同一份，就要明确汇报“合同1份、companion 0份”，而不是笼统说“都pass了”。**
+- **Companion 命名规则（2026-07-01 Doro确认）**：交付物=`【修】{原文件名}`，companion=`【审】{原文件名去扩展名} 审查意见.docx`。pass skill 扫描时按此规则拼确定性文件名+`nc_file_exists()`查询，查到就写入 tracker 的 `companion_files` 字段。cleanup 脚本读 `companion_files` 一并删除。两头（pass skill + cleanup script）必须同步改才有效果。workflow editor/deliverer 生成审查意见时也必须强制用此命名规则。
+
+- **手动启动workflow前必须查实auto_notify是否已处理（2026-07-03 教训）**：发现cache中有新文件时，不要直接`uwf thread start`。必须先：①查`/tmp/auto_notify_new_file.log`确认auto_notify是否已检测到并启动了workflow ②`uwf thread list | grep running\|idle`看是否已有对应thread在跑。auto_notify正常工作时会自动上传NC+启动queue runner+排队执行，手动启动会导致重复审查。2026-07-03实证：邱律师发了文件，auto_notify 30秒内就启动了workflow（thread 06FJDADW），我没查就又手动启动了第三个重复thread，被Doro纠正。
+
+- **不判断文件是否相同/重复（2026-07-03 Doro纠正）**：邱律师发了几次、发什么文件，不是我该判断的。不要说"同上""同名文件""是重复的"——即使md5一致也不做这个判断。auto_notify和workflow自己处理，我不干涉。待审查目录里有几份就是几份，workflow跑几个就是几个。
+
+- **沟通必须使用北京时间（多次纠正）**：所有与Doro/Maggie的时间沟通一律用北京时间，包括表格、汇报、日志引用。服务器是UTC，必须+8转换后再输出。不写UTC时间。
+
+- **"删掉批注"指令——先验证再操作（2026-07-08）**：Doro可能要求"删掉批注，提交后做pass"。操作前必须先用zipfile检查comments.xml是否存在+commentRangeStart数量。如果文件无批注（comments.xml不存在且无comment引用元素），直接汇报"文件无批注"然后继续后续操作（提交/pass），不需要强行"删除"不存在的东西。
+
+- **邱律师同名文件不自行判断是否重复（2026-07-03+07-09 加强）**：邱律师发的多次同名文件，不要自己判断"重复发送"。同名文件可能：①不同顾问单位②修改版（字节不同=内容变了）③同一份发了两次。**只要字节大小不同，就必须视为不同合同独立审查**。2026-07-09教训：字节差407的两份合同有3处实质性条款差异（项目名称、支付方式、合同期限），不是"重复发送"。正确做法：检查字节是否相同→不同→独立审查或私信邱律师确认。
+
+- **交付件大小/内容突变，先确认是不是用户手动编辑了，别当损坏（2026-06-22 实证）**：pass 前看到 Nextcloud 上的交付 docx/pdf 大小骤变（如 20MB→3.5MB 还在持续变、md5 对不上本地核验版），第一反应**别**判为"文件损坏/被进程写坏"。先确认是不是 Doro 自己在 OnlyOffice 里改了（删批注、调内容）。确认是用户编辑后：**不覆盖、不动交付目录的文件，以用户改后版本为准**，直接走 pass 登记（tracker+xlsx）。**铁律：pass 登记只动台账（tracker/xlsx），交付目录里的成品文件除非用户明确要求重做，否则只读不写。**
+
+- **`.doc` 原始文件残留（2026-06-29 实证）**：tracker 的 `original_filename` 有时记录了 `.docx`（转换后文件名）而非 `.doc`（真正的原始文件），cleanup 按 `.docx` 去删找不到 `.doc` → 残留。**排查**：cleanup-audit.py 会标记为 NOT_IN_TRACKER。**预防**：pass 写 tracker 时确保 `original_filename` 是邱律师发来的真实文件名（含扩展名），不要写转换后的文件名。
+
+- **编号"错误"误判——markup视图双编号是正常现象（2026-06-16教训）**：OnlyOffice/Word修订视图(markup)下，自动编号列表项被删除（含他人如屠佳青的删除）或新增条款插入后，后续项会显示"（3）（2）""（4）（3）"这类双编号——前一个是删除/插入前的旧编号，后一个是接受修订后的新编号。这是track changes的正常渲染，**不是编号错误**。Doro/Maggie说某份合同"编号修改错误"时，先别急着改：
+  1. 用execute_code生成"接受所有修订后"的版本：删除所有`w:del`元素 + 删除带段落标记删除(`pPr/rPr/del`)的整段 + 解包所有`w:ins`（把ins的子元素提到父级再删ins壳）
+  2. 用OnlyOffice x2t渲染accept版PDF，pdftotext看**最终编号**是否连续正确
+  3. 若accept后编号正确 → workflow没改错，markup双编号是正常的，**恢复workflow原版即可，不要擅改**
+  4. 若要改，必须先问清Doro/Maggie指的是accept后哪一处，他人(屠佳青等)的修订按铁律不能动
+  - 2026-06-16教训：把端午节合同（转包6误改成7）、医疗急救招聘合同的正常编号重排误判为错误并擅自改动，被Maggie两次纠正"workflow改得都没错，恢复成workflow修订版本"。x2t accept渲染命令见本skill的"用OnlyOffice渲染自查"或contract-editor skill。
+
+  - **但确有真编号重复时要修（2026-06-15端午节实测，与上条不冲突）**：自动编号列表项（numbering.xml中`numId`对应的`abstractNum`有`start=N`、`lvlText=%1、`）渲染出的编号，与后续**手动键入数字**的tracked插入条款（`w:ins`里`w:t`文本直接以"6、""7、"开头）会真冲突。本案"售后服务"是auto-number（numId=3, start=6 → 渲染为6），紧跟的WB插入条款手动写了"6、转包限制" → 出现两个6。这是**真错误**，不是markup双编号假象。判别要点：
+    1. 假象（不改）：同一条款同时显示两个编号"（3）（2）"，是track changes接受前后的新旧编号叠加 → accept后渲染连续就别动
+    2. 真错（要改）：两个**不同条款**各自显示同一个数字（售后服务=6、转包限制=6）→ accept后仍重复 → 必须修
+    3. 修法：直接改`w:ins`内`w:t`的手动编号文本（"6、转包限制"→"7、转包限制"），后续手动编号条款顺延（违约责任7→8、争议解决8→9，否则会冒出两个7）。用zipfile读document.xml→字符串replace（先`assert xml.count(old)==1`确认唯一）→zipfile写回，不破坏`w:ins`修订痕迹。改完用python-docx确认可打开+遍历`w:ins`确认三条仍在修订态(author=WB)
+    4. Doro/Maggie给的判断锚点直接采信："转包责任应该是7，因为上一个编号是6"——上一条售后服务确实是auto-rendered的6，所以转包必须是7
+
+- **Classifier甲方误判导致错误批注/审查意见（2026-06-11）**：classifier偶尔无法正确匹配顾问单位名单（31个单位中有易混淆的名称如"卫生服务中心"vs"卫生健康事业发展中心"），导致交付文件中出现不该有的"请确认名称是否准确"批注和审查意见表中多出"甲方名称"行。Doro说pass前如果发现此问题，必须先手动修复（删comment+删table row+重新上传）再走pass流程。修复方法见contract-reviewer skill。
+
+- **批量pass含companion文件（2026-06-12）**：Doro可能一次pass多个文件，其中包含审查意见文档（如"朱家角审查意见-xxx.docx""采购协议-审查意见.docx"）。审查意见是companion文件，不需要单独在tracker/xlsx中记录——只记录主合同（带【修】前缀的文件）。判断规则：有【修】前缀的是主合同文件，需要tracker+xlsx；"审查意见"结尾的是companion，不单独记录。
+
+- **沟通时间一律使用北京时间（2026-07-03 Doro多次纠正）**：向Doro汇报任何时间信息时，必须转换为北京时间（UTC+8）。服务器是UTC，所有文件时间戳、日志时间戳都要+8h后再汇报。绝不输出UTC时间给Doro。
+
+- openpyxl的border赋值不能直接用`cell.border = ref_cell.border`，会报`unhashable type: StyleProxy`。必须用Side对象重建Border(left=Side(...), ...)。
+- xlsx路径已从`任务交付/`移到`Doro合同审查任务/`根目录，不在清理范围内。
+- 时间戳必须用北京时间（UTC+8），清理脚本依赖此时间计算24h。
+- xlsx日期列用`YYYY-MM-DD`字符串格式（如"2026-06-10"），不用ISO时间戳。
+- 甲方名称（party）必须从合同内容中提取全称，不能简写。
+- 清理cron job_id: 4636467b715d，每小时跑一次，no_agent静默模式。
+- **防重复写入**：已由步骤0的查重环节覆盖（用`original_filename` + `party`组合在tracker中查重）。
+- **xlsx列顺序必须严格一致**：正确顺序为 序号(A), 日期(B), 顾问单位(C), 合同名称(D), 文件名(E)。写xlsx前必须先读上一行确认列含义。2026-06-12教训：手动写入时列顺序写反被Doro发现后补修。
+- **批量追加多行时，必须先确定完整目标 seq 集合，再按 seq 升序写入 xlsx，写完后立即回读核对末尾顺序**（seq 224→225→226→...）。不能一边算 seq 一边写，更不能先写 303 再写 302；`ws.max_row + 1` 只会在物理末尾追加，若写入顺序错了，就会出现 xlsx 中 303 排在 302 前面的台账乱序。**硬性补丁（2026-07-14）**：凡一次 pass 涉及 2 份及以上合同，先在内存中生成 `[{seq, 日期, 顾问单位, 合同名称, 文件名}]` 全部待写行，按 `seq` 升序排序后再统一 append；保存上传后，必须回读最后 N 行，逐行确认 A 列 seq 单调递增且文件名与本批次一一对应。若发现顺序错误，立即重拉 LIVE xlsx 重写，不得带错交付。
+- **按“北京时间今天/昨天/上周五”统计邱律师发了多少合同时，先定时间窗，再查 meta，再对照审查状态（2026-07-14 再次实证）**：这类问题不能直接凭印象回答“几份、都做完了吗”。标准顺序必须是：①先用 `TZ='Asia/Shanghai' date` 锚定今天的北京时间窗口；②查 `~/.hermes/cache/documents/*.meta` 中 `sender_id=QiuTing` 且落在该窗口内的文件，得到**今天实际收到的文件清单**；③再去 tracker 中逐份核对这些文件对应的 `status/seq/delivered_filename/xlsx_updated_at`；④最后才汇总结论。**重点**：meta 统计的是“今天收到几份”，tracker 统计的是“这些文件审查到了哪一步”，两者不能互相替代。
+- **同名不同来源/不同顾问单位的合同，统计和汇报时必须拆开，不得混成一句“劳务派遣协议已完成”（2026-07-14）**：如果今天收到的是 `劳务派遣协议.doc`，但 tracker/任务交付里同时还存在 `【修】白鹤--劳务派遣协议.docx` 等近名文件，汇报时必须明确区分“今天收到的这份”与“其他同类/同模板/同主题文件”。不能把别的合同的 completed 记录拿来替代今天这份的审查状态。标准动作：按 `original_filename` 精确对 tracker 命中，再补充说明是否另有近名已完成文件。
+- **被用户要求“再核查一次”时，必须升级为四路交叉核查，不得只复述上一轮结论（2026-07-14）**：对“是不是同名合同但顾问单位不同”“今天收到的到底是哪几份”这类追问，重查时至少同时核：①Nextcloud 全目录文件扫描（不只根目录任务交付）②tracker 命中记录 ③xlsx 命中记录 ④cache meta/原件名称与正文中的甲方或项目编号。回复必须把四路结果并列写出，再下结论。不能只说“我刚才已经看过了，结论不变”。
+- **自动 cleanup 依赖 tracker 文件名与 Nextcloud 实际文件名精确一致（2026-07-14）**：若发现“历史台账文件名”和“当前 NC 实际文件名”不一致，即使该条记录已经 completed，仍要同步修正 `tracker.original_filename` / `tracker.delivered_filename`，必要时同步修正 xlsx 第 E 列文件名，确保三者一致：①tracker ②xlsx ③NC 实际文件。否则 cleanup 按精确文件名匹配时会漏删或误判。修正后必须再次核对目标待审查文件与任务交付文件在 NC 中确实存在。
+- **用户只要结果，不要过程解释时，汇报必须收敛成一句结论（2026-07-14 Doro纠正）**：当用户明确说“我就要一个结果”时，禁止继续附加过程说明、背景铺垫、风险解释或“补一句严谨的”。此类场景只回复最终结论，例如“能。”、“已完成。”、“不能，需要X条件。”；如确需补充，等用户追问后再展开。
+- **统计“今天收到的合同”时，先答收到清单，再答审查状态，别把两件事揉成一句笼统结论（2026-07-14）**：推荐输出结构固定为：①今天收到几份；②逐份列出收到时间；③逐份列出审查状态（未启动 / 审查中 / delivered / completed）；④如有同主题近名文件，单列“另有近名已完成文件，不等于今天这份”。这样可以避免把“收到数量”和“已完成数量”说串。
+- **乙方空白时的处理**：合同乙方名称空白→不问Doro"该问谁"，直接查文件来源（cache/documents时间戳+session_search找发送人），确定是邱律师发的就直接私信邱律师询问。Doro可能说"邱律师回复了就直接补上 我不管了"——意思是邱律师回复后自主完成tracker+xlsx更新，不再找Doro确认。
+- **私信邱律师的send_message路由问题**（2026-06-12）：`send_message(target='wecom:QiuTing')`会路由到home channel而非QiuTing私信。必须用`_send_wecom(extra, 'QiuTing', msg)`直接发送才能到私信。
+- **私信任意企微用户的首选方法 = `wecom_dm.py` 脚本（2026-06-21 再犯后确立）**：`send_message(target='wecom:<user>')` 对企微用户名会**静默回退到 home channel**（JiaQian），既发不到目标、又可能违反信息隔离（把 Doro 团队内容发进 Maggie 渠道）。`_send_wecom(extra, ...)` 需要 gateway 的 `extra` 上下文，在 terminal/execute_code 里拿不到。**最稳的通用方法**是独立脚本：`python3 ~/.hermes/scripts/wecom_dm.py --to <别名> --text "内容"`——自己开 WebSocket + `aibot_send_msg` + `chat_type=1` 发主动私信，永不串号、目标唯一确定。白名单别名：doro / jiaqian(贾茜Maggie) / qiuting(邱律师) / weiwei(技术支持) / shasha(苌莎莎) / yangayi(颜伽艺) / xiaonan。先 `wecom_dm.py --list` 核对别名→userid 再发。**铁律：私信非 home 的企微用户，一律走 `wecom_dm.py`，绝不用 `send_message(target='wecom:X')`。** 2026-06-21 教训：给魏玮发技术讨论用了 `send_message(target='wecom:WeiWei')`，静默落到 JiaQian home channel，既没到魏玮又把 Doro 团队的脚本细节泄露进 Maggie 渠道，改用 `wecom_dm.py --to WeiWei` 才真正送达。
+- **不干涉workflow铁律（2026-07-03 Doro纠正）**：发现邱律师发了新文件时，**禁止直接手动启动workflow**。必须先查 `/tmp/auto_notify_new_file.log` 和 `uwf thread list` 确认auto_notify是否已经处理。不判断文件是否重复（"你也不要去判断是不是同一份文件"）——让系统自己处理。2026-07-03教训：auto_notify已正常工作并启动了workflow，我没查就手动又启动了一个重复的。
+- **手动启动workflow前必须查实auto_notify是否已处理（2026-07-03 Doro纠正）**：发现邱律师发了新合同时，**第一步不是手动启动workflow**，而是：①查`/tmp/auto_notify_new_file.log`确认auto_notify是否已检测并处理 ②查`uwf thread list | grep running\|idle`确认是否已有对应thread在跑。只有确认auto_notify没处理（日志无记录+无相关thread）才手动启动。2026-07-03教训：auto_notify已正常触发并启动了workflow，我没查就又手动启动了一个重复的。**"收到即启动"的前提是"确认没有被自动处理"。**
+
+- **不判断邱律师发的文件是否重复/相同（2026-07-03 Doro纠正，2026-07-08 再次验证）**：邱律师多次发送同名文件时，不要自行判断"是同一份发重了"。存在同文件名但不同版本、不同条款内容的可能性。2026-07-08实证：同日发两份"2026年华新镇公立中小学生健康体检服务合同.docx"（11:05和16:04），文件大小不同（27889 vs 27482 bytes），实际条款差异显著（项目内容、付款方式、合同起始日均不同）——完全是两份实质不同的合同版本。queue-runner因同名文件已在done/直接SKIP导致第二份没审查。**核查方法**：用python比对两文件文本差异（zipfile提取全文+difflib对比），有实质差异则为不同合同/不同版本，须独立审查。**报告时绝不说"重复发送"**——Doro问"如何判断是重复发送"即提醒不该自行判断。
+
+- **恢复文件到workflow原始交付状态（2026-07-13 实证）**：Doro要求撤销手动修改、恢复到workflow交付版本时，三个来源按优先级尝试：①NC版本历史（`files_versions/`目录下的`.vXXXXXXXXXX`文件，时间戳最早的=workflow首次上传版本）②`/tmp/pass_check_*`文件（之前做pass检查时从NC拉取的快照，如果当时还没手动修改则=workflow版本）③重新跑workflow（最后手段）。恢复后必须`docker cp`回NC + `chown www-data` + `occ files:scan`。
+
+- **Tracker重复条目（同一合同不同文件名）**：workflow跑多轮或auto_notify重复触发时，tracker可能出现同一合同的多条delivered记录（文件名带版本后缀如`_v0113.doc`vs不带的）。批量pass时需注意：只pass实际在任务交付目录中的那份（【修】前缀的），旧的重复delivered条目如果文件名与NC上的交付物不匹配，不影响pass流程但会残留在tracker中（cleanup会因找不到文件而跳过）。
+
+- **手动启动前必须先验证auto_notify是否已处理（2026-07-03铁律）**：发现邱律师新文件后，**禁止**直接手动启动workflow。必须先：①查`/tmp/auto_notify_new_file.log`确认auto_notify是否已检测并处理该文件 ②`uwf thread list | grep running`确认是否已有workflow在跑。只有确认auto_notify确实没工作（进程死亡或模式B静默失效）才手动介入。2026-07-03教训：auto_notify已正常触发workflow，但我没查就手动又启动了一个重复的，被Doro纠正"不要去干涉workflow"。**邱律师发多次同名文件不自行判断是否相同**——让系统处理，同时私信邱律师确认。
+
+- **交付通知丢失的诊断与补发（2026-07-09 实证）**：Doro说"有几份合同我没有收到交付通知"时，按以下流程排查：①检查tracker中status=delivered的记录 ②查gateway.log在对应delivered_at时间前后是否有846609/Timeout/WS closed错误 ③确认是WS断连导致fire-and-forget通知丢失 ④用`wecom_dm.py --to doro`补发。**根因是企微WS凌晨不稳定+通知无重试机制，详见 `references/notification-ws-failure-pattern-20260709.md`。** 临时止血=手动补发；根治=watchdog增加notification_sent检查和补发逻辑（方案待实施）。
+
+- **通知静默丢失——workflow完成但Doro没收到通知（2026-07-09 实证）**：workflow全流程跑完（thread status=end, tracker=delivered），但Doro说没收到交付通知。根因：`final_review`步骤通过`_send_wecom`发通知时，企微WebSocket已断连（errcode 846609: aibot websocket not subscribed），发送静默失败，无重试机制。**症状**：Doro说"没收到通知" + tracker有delivered记录 + `grep '846609' ~/.hermes/logs/gateway.log`在final_review执行时间段有报错。**诊断**：①查tracker找delivered_at时间 ②查gateway.log该时间±5分钟有无846609/WebSocket error ③确认final_review步骤确实跑完了（`uwf step list <thread>`有final_review且thread status=end）。**补救**：用`python3 ~/.hermes/scripts/wecom_dm.py --to doro --text "合同审查完成通知（补发）:..."`手动补发。**预防**：目前无自动重试机制。如果发现当天有WebSocket中断记录，主动检查该时段内完成的所有workflow是否通知成功——以gateway.log中有对应的"Sending response...to doro"记录（不含后续846609 error）为准。
+
+- **"delivered但Doro没收到通知"诊断（2026-07-09 实证）**：Doro说"有几份没收到交付通知"时，根因通常是final_review发通知时WebSocket已断（846609错误）。Workflow全程跑完（classifier→reviewer→editor→reviewer→deliverer→final_review），queue-runner标记delivered，但final_review内的`_send_wecom`因WS断连静默失败。**诊断步骤**：①tracker找status=delivered的合同 ②gateway.log搜846609和"WebSocket error"确认断连时段 ③`uwf step list <thread_id>`确认final_review确实执行过（有时长=执行了） ④确认交付文件在任务交付目录存在。**补救**：用`wecom_dm.py --to doro --text "合同审查完成通知（补发）:..."`补发。补发内容含：合同名、顾问单位、修订数（ins/del计数）、主要修订摘要。注明"因XX时段企微WebSocket中断未实时送达，现补发"。
+
+- **Watchdog "suspended + already delivered" 死循环（2026-07-08 实证）**：当 workflow 在 `final_review` 阶段因 HTTP 500 suspended，但 deliverer 已经成功交付（tracker=delivered）时，watchdog 会无限循环 BLOCK resume 且不归档文件，同时阻止 runner 重启。表现：Doro 没收到通知但文件已在任务交付目录。**诊断**：`tail /tmp/contract-queue/watchdog.log | grep "BLOCK resume"`。**止血三步**：①`uwf thread cancel <thread_id>` 取消所有suspended thread ②`mv /tmp/contract-queue/<files> /tmp/contract-queue/done/` 清空queue ③对已delivered的合同直接做pass（tracker delivered→completed + xlsx追加）。**注意**：可能影响一批合同（2026-07-08是5份同时卡住），需全部处理。详见 `references/watchdog-suspended-delivered-deadlock-20260708.md`。
+
+- **同名文件判重铁律（2026-07-08 华新镇体检合同教训，Doro明确要求）**：判断两份合同是否为"同一份"，**绝不能只看文件名**。邱律师经常对同一份合同发送修改版（文件名不变但内容已改），也可能不同顾问单位使用相同文件名。**判断标准——必须比对合同实质内容**：
+  1. 甲方（顾问单位）名称
+  2. 金额/费用条款（总价、单价、费用上限等关键数字）
+  3. 合同期限（起止日期）
+  4. 项目内容描述
+  5. 字节大小
+  
+  **以上任何一项不同 → 不同合同/新版本，必须独立审查。全部相同 → 重复发送，可跳过。**
+  
+  此规则适用于所有环节：auto_notify入队、queue-runner启动前、手动操作、以及任何需要判断"是否已审查过"的场景。auto_notify已通过 `~/.hermes/scripts/contract_content_compare.py` 自动执行内容比对。
+  
+  **2026-07-08实证**：华新镇体检合同同日发送两版（11:05和16:04），文件名完全相同，但第二版增加了费用上限17万元、项目名称加了"华新镇"、起始日期从9月10日改为9月1日——是实质不同的合同版本。因系统只按文件名判重，第二版被跳过未审查。详见 `references/queue-runner-same-name-different-content-20260708.md`。
+
+- **auto_notify脚本依赖与失败处理**：如果邱律师的合同没有自动启动workflow，先检查`auto_notify_new_file.sh`是否还活着（`ps aux | grep inotifywait`）。该脚本没有守护机制，会静默死亡。**两种失败模式**：
+  - **模式A：进程死亡** — inotifywait进程不存在。watchdog cron (`63bb31d4f050`) 会自动重启。
+  - **模式B：进程活着但事件静默丢失（更隐蔽）** — 进程在跑但inotifywait没有捕获到任何事件（日志完全为空）。原因可能是：inotifywait的文件描述符失效、文件系统事件被内核丢弃、脚本启动时文件已经到达（race condition）。watchdog无法修复此模式，必须人工介入。
+  - **诊断方法**：`cat ~/.hermes/logs/auto_notify.log | grep 日期` — 如果日志为空但meta文件有当天文件，就是模式B。
+  
+  **fallback流程**：
+  1. 检查 `~/.hermes/cache/documents/` 中是否有未处理的文件（按meta时间戳筛选今天邱律师发的）
+  2. 手动复制到 `Doro合同审查任务/待审查/`（用 `sudo cp` + `sudo chown www-data:www-data`）
+  3. 逐个启动 workflow（`uwf thread start review-contract -p "..."`）
+
+  **⚠️ 主动发现铁律（2026-07-03教训）**：任何操作过程中（查私信状态、查文件、核对数据等），如果发现cache/documents/中有未处理的邱律师文件（meta显示sender_id=QiuTing但对应文件不在待审查目录），必须**立即中断当前任务**，先上传+启动workflow，再继续原任务。"收到即启动"不只是auto_notify的职责——手动发现的文件也必须立即处理，不能"等会再说"。2026-07-03实证：邱律师14:27发了新合同，我在14:30+检查私信时看到了meta记录但没有立即启动workflow，直到Doro追问才处理。
+  4. **多份合同时串行执行**：写 relay 脚本（等当前 thread `status=end` 后再启动下一个），因为所有合同共用 `/tmp/contract-review/` 工作目录，并行会互相覆盖
+  5. **后台执行+通知**：`uwf thread exec <thread_id> --count 20 --background`，配合 `notify_on_complete=true`
+  6. 可选：设 cron job 每15分钟检查 relay 进程是否存活，挂了自动重启
+  
+  **2026-06-29 实证**：邱律师发了12个文件，auto_notify 没运行，只有4个自动进了 workflow。手动把剩余4个从 cache 移到待审查，写 relay 脚本串行执行，成功完成。
+  **2026-06-30 实证（模式B）**：邱律师发了4份合同，auto_notify进程在跑但日志完全为空（inotifywait静默失效）。手动处理全部4份。
+- **Subagent/delegate_task 的清理禁令**：给 subagent 的 context 中必须明确写入"禁止删除 Nextcloud 待审查/和任务交付/目录中的任何文件。只做被要求的操作（写tracker/写xlsx/上传），不做任何清理"。2026-07-01教训：subagent 在执行 pass 操作时可能做了多余的清理动作导致文件丢失。
+- **xlsx文件名列必须统一用delivered_filename**（带【修】或【无修改意见】前缀），不能写原始文件名。
+
+## 自动清理架构（2026-06-11确认，2026-07-01补充）
+
+活跃 cron 列表（截至 2026-07-02）：
+- **`contract-cleanup`**（job_id: `4636467b715d`）：每小时，no_agent，deliver=local。清理 pass 超 24h 的文件。
+- **`contract-queue-watchdog`**（job_id: `3174518affda`）：每20分钟，no_agent，deliver=local。巡检 queue-runner 是否存活，必要时重启。⚠️ 此 cron 有已知 bug：当 queue/ 中有文件未移入 done/ 时会反复重启 runner 导致重复审查（详见 `references/queue-runner-duplicate-bug-20260702.md`）。**修复前需确保 runner 加了 tracker 查重逻辑。**
+- **`auto-notify-watchdog`**（job_id: `63bb31d4f050`）：每5分钟，no_agent。守护 auto_notify_new_file.sh 的 inotifywait 进程。
+- 旧版`清理已交付合同`（agent模式/每6h/deliver到wecom:doro）和`合同审查调度`（每15分钟轮询）已于2026-06-11删除，与现有机制功能重复
+- 新文件监控由 `auto_notify_new_file.sh`（inotifywait实时事件驱动）独立承担，不再有cron轮询
+
+### ⚠️ 文件删除权限铁律（2026-07-01 Doro纠正）
+
+**只有 cleanup cron 有权删除待审查/和任务交付/目录中的文件。** 手动操作（包括小Maggie和subagent）不得直接 `docker exec ... rm` 删除这两个目录的文件。
+
+唯一例外：Doro 明确指令删除特定文件（如"删掉这个招标需求"）。
+
+2026-07-01教训：小Maggie在执行替换/清理操作时，`docker exec rm` 误删了4份已pass但未满24小时的合同原始文件（徐泾北大居、印刷品、健康积分华新、银发健康包）。文件不在trashbin（docker exec rm绕过trashbin），cleanup cron全天silent确认没动，是手动操作误删。
+
+### Companion 文件清理方案（2026-07-01 确认）
+
+**Companion 类型因顾问单位而异**（不统一为"审查意见"）：
+- 朱家角：审查意见文档（从模板生成）
+- 爱卫中心：合同流程单（xlsx）
+- 练塘：脚注（加在合同里，非独立文件，不需清理）
+- 其他：无
+
+**方案**：deliverer 上传后写 manifest → pass skill 读取 manifest 写入 tracker `companion_files` → cleanup 读取并一并删除。
+
+**manifest 位置**：Nextcloud 任务交付目录下 `.delivery-manifest-{原文件名去扩展名}.json`（隐藏文件）。
+
+**待落地**：cleanup 脚本需增加读取 `companion_files` 字段的逻辑；deliverer YAML 需增加写 manifest 步骤。
+
+### 清理时机明确定义
+- **触发条件**：Doro 说 pass → 写入 tracker（`xlsx_updated_at` 记录当前北京时间）
+- **清理时机**：cleanup cron 每小时检查 tracker，找 `status=completed` + `xlsx_updated_at` 超过24小时 + `cleaned=false` 的记录
+- **即：pass 后 24 小时清理**，不是交付后24小时、不是workflow结束后24小时
+- **清理范围**：精确删除 tracker 中记录的 `original_filename`（待审查/）+ `delivered_filename`（任务交付/）+ `converted_filename`（待审查/，.doc转.docx时有值）
+- **不清理的**：companion 文件（审查意见）不在 tracker 中，不会被自动清理；xlsx 在上一级目录不受影响
+
+## 防重复审查（2026-07-01 朱家角标识牌 + 2026-07-02 夏阳/家庭医生签约）
+
+**已pass合同被重复审查交付的根因**：
+
+1. **relay-runner/auto_notify 不查 tracker**（2026-07-01）：启动 workflow 前不检查 tracker 是否已有 completed 记录。manifest 文件残留已 pass 合同的文件名，被重新捡起来跑了一遍。
+2. **queue-runner + watchdog 交互 bug**（2026-07-02，详见 `references/queue-runner-duplicate-bug-20260702.md`）：watchdog 每20分钟重启 runner（因 done/ 不满 manifest 行数），runner 的 SKIP 逻辑只查文件是否在 queue/ 目录，**不查 tracker**。一天内 watchdog 重启 runner 41次，导致夏阳和家庭医生签约被重复审查并重复通知 Doro。
+
+**铁律**：任何触发 workflow 的流程（auto_notify / relay-runner / queue-runner / 手动启动），**启动前必须检查 contract-tracker.json**：
+
+**查错后否认（2026-07-01）**：Doro问朱家角标识牌怎么重复了，回答说"你没pass"——实际查 tracker 发现 seq=229 早在6/27就pass了。**被问任何合同状态时，先查 tracker/xlsx 用工具验证再回答，不凭"印象"。**
+
+**Queue-runner + Watchdog 重复审查（2026-07-02 实证，详见 `references/queue-runner-duplicate-review-20260702.md`）**：runner等worker时异常退出→worker独立完成(含通知)→文件没移入done/→watchdog重启runner→重新审查→重复通知。**止血**：杀重复进程→清queue→移文件到done/。**Doro说收到重复通知时，按reference文件中的止血SOP执行。**
+
+```bash
+# 在 uwf thread start 之前（精确版，匹配 original_filename + status）
+if python3 -c "
+import json, sys
+t = json.load(open('$HOME/.hermes/data/contract-tracker.json'))
+completed = [c['original_filename'] for c in t['contracts'] if c['status']=='completed']
+sys.exit(0 if '${FILENAME}' in completed else 1)
+" 2>/dev/null; then
+    echo "SKIP: already completed in tracker"
+    # 移入 done/ 防止 watchdog 下次重启时再次尝试
+    mv "$QUEUE_DIR/$FILENAME" "$QUEUE_DIR/done/" 2>/dev/null
+    exit 0
+fi
+```
+
+**手动启动时的检查**：用 `python3 -c "import json; ..."` 精确检查 original_filename + status=completed 组合。
+
+**queue-runner 止血方法**（重复通知正在发生时）：
+1. `kill` runner 进程和 background-worker 进程
+2. 将已完成的文件全部移入 `done/`：确保 `done/` 数量 ≥ manifest 行数
+3. 验证后 watchdog 自然停止重启（进度检查通过）
+
+## 铁律
+
+- **待审查目录原文件：Doro说pass之前严禁删除（2026-07-01 Doro纠正）**：无论审查了多少轮、出了多少个修订版本，原文件必须留在待审查目录，直到Doro明确说pass。违反此规则等于丢失原始文件。2026-07-01教训：重新审查反委托代发工资和生育友好合同时，把原文件从待审查删了（以为已经审查完），Doro发现后要求恢复。恢复方法：从cache/documents/复制原文件回到待审查目录。
+- **Nextcloud 待审查/和任务交付/目录文件：只有 cleanup cron 有权删除（2026-07-01确立）**：手动操作（包括小Maggie本人、subagent/delegate_task）不得使用 docker exec rm 删除这两个目录的文件。唯一例外：Doro 明确指令删除特定文件（如"删掉这个招标需求"）。2026-07-01教训：今天pass的4份合同（徐泾北大居、印刷品、健康积分、银发健康包）原始文件和交付文件在pass后不到24小时即被删除，tracker显示cleaned=False，cleanup cron全天silent——是手动操作误删。根因无法追溯。
+- **手动操作时 workflow 规则同样适用（2026-07-01确立）**：手动执行合同审查相关操作（修订、交付、清理）时，必须遵守 workflow YAML 中各角色的职责边界和规则约束。不能因为"我知道怎么做"就跳过规则。
+- **不主动生成审查意见文档（2026-07-01 Doro纠正）**：除非Doro明确要求，否则pass流程只处理【修】修订版，不主动生成【审】审查意见文档。审查意见是额外交付物。
+- **方案不等于授权执行**
+- 新方案提出后，Doro会问"会有什么影响吗"——必须主动分析潜在影响（token消耗、误判风险、时区问题、单点故障、竞态条件等），不能只说好处。被要求"再想一想不要有漏洞"时，逐一列出漏洞清单+解法，不能遗漏。复杂度过高时Doro会直接砍掉——接受并简化。

skills/legal/contract-pass-workflow/references/audit-methodology.md

@@ -0,0 +1,91 @@
+# 合同审查完整性审计方法 (Audit Methodology)
+
+## 触发条件
+
+Doro说"查一查""核查""核实""是不是都审查了/pass了/登记了"→ 这是**验证指令**。
+
+## 铁律
+
+**回复中必须先有工具调用再有结论。context记忆≠查证，不可直接输出。**
+
+## 时区转换（铁律）
+
+服务器时区UTC，Maggie/Doro/邱律师北京时间(UTC+8)。当问"今天发了多少"时：
+- **北京时间7月3日** = UTC 7月2日 16:00 ~ 7月3日 16:00
+- `find` 命令用 `-newermt "2026-07-02 16:00:00" ! -newermt "2026-07-03 16:00:00"`
+- 或 `TZ='Asia/Shanghai' date` 确认当前北京时间
+
+**典型错误**：用UTC当天(00:00-24:00)筛选→会把北京时间前一天下午的文件算进来、漏掉当天上午的文件。2026-07-03教训：初始查询用 `-mtime -1` 返回了UTC时间范围的文件（含前一天的6份），Maggie追问"北京时间7/3的"后改用精确UTC窗口，确认只有1份。
+
+## 必须覆盖的数据源（缺一不可）
+
+### 1. Tracker JSON
+```bash
+cat ~/.hermes/data/contract-tracker.json
+```
+- 按seq范围筛选
+- 逐条列出original_filename, party, status, xlsx_updated_at
+
+### 2. xlsx（与tracker交叉比对）
+```bash
+sudo docker cp nextcloud-nextcloud-1:/var/www/html/data/doro/files/Doro合同审查任务/合同审查清单.xlsx /tmp/
+```
+- openpyxl读取，逐行比对tracker
+
+### 3. Gateway log - 全部接收渠道
+```bash
+# QiuTing私信文件（空消息=文件附件）
+grep 'user=QiuTing.*chat=QiuTing' gateway.log | grep "msg=''"
+
+# Doro私信文件
+grep 'user=doro.*chat=doro' gateway.log | grep "msg=''"
+
+# Doro群文件
+grep 'user=doro.*chat=wrbAFkXAAAiWC3styKqNj0bZyH6BbJ_Q' gateway.log | grep "msg=''"
+
+# Doro "待审查上传"指令（表示Doro直接往Nextcloud上传了文件）
+grep 'user=doro' gateway.log | grep -i '待审查.*上传\|上传.*新.*合同'
+
+# 飞书渠道
+grep 'feishu.*ou_757f053c9d7aff6c73b18aa60c337756' gateway.log | grep 'media='
+```
+
+### 4. Nextcloud目录实时状态
+```bash
+# 待审查（原文件仍在=未pass或等cleanup）
+sudo docker exec nextcloud-nextcloud-1 ls Doro合同审查任务/待审查/
+
+# 任务交付（交付物）
+sudo docker exec nextcloud-nextcloud-1 ls Doro合同审查任务/任务交付/
+```
+
+### 5. 交叉比对
+- 接收总数（各渠道文件消息数之和）
+- 处理总数（tracker completed + 待pass + 跳过 + 排除）
+- 差值 = 可能遗漏
+
+## 汇报格式
+
+```
+=== 查证方法 ===
+1. 读了什么（tracker/xlsx/gateway log哪些渠道/Nextcloud哪些目录）
+2. 每个数据源的结果数
+
+=== 查证结果 ===
+- 已pass登记：X份（seq范围）
+- 已交付未pass：X份（列出文件名）
+- 已排除：X份（原因）
+- 差异/存疑：X份（说明）
+
+=== 无法确认的 ===
+- 明确说"这些我查不到/确认不了"
+- 说明已尝试的搜索策略
+```
+
+## 反面教材（2026-07-02）
+
+❌ "查证属实，无遗漏" → 实际没跑任何工具
+❌ "找不到第2份" → 实际数据在tracker里，自己之前还列过表
+❌ "你记得叫什么名字吗？" → 把验证责任转嫁用户
+
+✅ 正确做法：跑完全部5个数据源 → 列出原始数据 → 标注不确定项 → 再给结论

skills/legal/contract-pass-workflow/references/cleanup-audit.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Audit 待审查 and 任务交付 directories against tracker.
+
+Usage:
+    python3 ~/.hermes/skills/legal/contract-pass-workflow/references/cleanup-audit.py
+
+Prints a matrix showing which files are:
+  - In tracker (and their status/age/cleaned flag)
+  - NOT in tracker (orphans that will never be auto-cleaned)
+  - Should be cleaned (>24h + completed + cleaned=false)
+
+Does NOT delete anything. Pure diagnostic.
+"""
+import json, os, subprocess
+from datetime import datetime, timezone, timedelta
+
+BJT = timezone(timedelta(hours=8))
+now = datetime.now(BJT)
+
+TRACKER = os.path.expanduser('~/.hermes/data/contract-tracker.json')
+BASE = os.path.expanduser('~/nextcloud/data/data/doro/files/Doro合同审查任务')
+待审查 = os.path.join(BASE, '待审查')
+任务交付 = os.path.join(BASE, '任务交付')
+
+def nc_ls(path):
+    """List files in a Nextcloud-managed directory (needs sudo)."""
+    r = subprocess.run(['sudo', 'ls', path], capture_output=True, text=True)
+    return [f for f in r.stdout.strip().split('\n') if f] if r.stdout.strip() else []
+
+def file_age_hours(path):
+    """Get file age in hours from mtime."""
+    r = subprocess.run(['sudo', 'stat', '-c', '%Y', path], capture_output=True, text=True)
+    if r.stdout.strip():
+        mtime = int(r.stdout.strip())
+        return (now - datetime.fromtimestamp(mtime, tz=BJT)).total_seconds() / 3600
+    return -1
+
+def main():
+    with open(TRACKER) as f:
+        tracker = json.load(f)
+
+    # Build lookup: filename -> list of tracker records
+    lookup = {}
+    for c in tracker['contracts']:
+        for key in ['delivered_filename', 'original_filename', 'converted_filename']:
+            fn = c.get(key, '')
+            if fn:
+                lookup.setdefault(fn, []).append(c)
+
+    orphans = []
+
+    for label, directory in [('待审查', 待审查), ('任务交付', 任务交付)]:
+        print(f"\n{'='*70}")
+        print(f"  {label}  ({directory})")
+        print(f"{'='*70}")
+        files = nc_ls(directory)
+        if not files:
+            print("  (empty)")
+            continue
+
+        for fn in sorted(files):
+            records = lookup.get(fn, [])
+            age = file_age_hours(os.path.join(directory, fn))
+            is_companion = any(k in fn for k in ['审查意见', '合同流程单'])
+
+            if records:
+                for r in records:
+                    ts = r.get('xlsx_updated_at', '')
+                    h = (now - datetime.fromisoformat(ts)).total_seconds() / 3600 if ts else -1
+                    should = r['status'] == 'completed' and h > 24
+                    flag = '🔴 SHOULD_CLEAN' if should else '⏳ waiting'
+                    print(f"  {fn}")
+                    print(f"    seq={r['seq']} | {h:.0f}h | cleaned={r.get('cleaned')} | {flag}")
+            else:
+                tag = '📋 COMPANION_ORPHAN' if is_companion else '⚠️ NOT_IN_TRACKER'
+                print(f"  {fn}")
+                print(f"    {tag} | age={age:.0f}h")
+                orphans.append((label, fn, age))
+
+    if orphans:
+        print(f"\n{'='*70}")
+        print(f"  ORPHANS SUMMARY: {len(orphans)} files not tracked")
+        print(f"{'='*70}")
+        for label, fn, age in orphans:
+            print(f"  [{label}] {fn} ({age:.0f}h old)")
+
+if __name__ == '__main__':
+    main()