hermes-task-framework 1.0.0__py3-none-any.whl

task-framework/skills/task-framework/references/generating-output-documents.md

@@ -0,0 +1,166 @@
+# Generating Output Documents (Merged Markdown + PDF)
+
+When a project task involves converting multiple source documents (DOCX, old-format DOC, XLSX) and merging them into a consolidated output, follow this pattern.
+
+## Typical Use Cases
+
+- Policy document collection from multiple government sources
+- Competitor analysis report from multiple vendor documents
+- Research paper compilation from multiple papers/drafts
+- Any batch of Chinese-language office documents needing a unified markdown output
+
+## Tools
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| `pandoc` | .docx → markdown | System package |
+| `olefile` | Extract text from old .doc (OLE2) | `uv pip install olefile` |
+| `openpyxl` | .xlsx → markdown tables | `uv pip install openpyxl` |
+| `weasyprint` | markdown → PDF | `uv pip install weasyprint` |
+
+**Note:** pandoc does NOT support old-format .doc — only .docx. libreoffice is usually not available on servers. olefile extracts readable text directly from the OLE2 binary stream.
+
+## Pipeline
+
+### Phase 1 — Convert Source Files to Markdown
+
+Write a Python script (not inline heredocs — quoting issues guaranteed) that:
+
+1. **.docx → markdown** via pandoc subprocess:
+   ```python
+   subprocess.run(["pandoc", str(src), "-f", "docx", "-t", "markdown",
+                    "--wrap=none"], capture_output=True, text=True, timeout=120)
+   ```
+
+2. **.doc → text** via olefile:
+   ```python
+   ole = olefile.OleFileIO(src_path)
+   data = ole.openstream('WordDocument').read()
+   # Scan binary data for readable text sequences
+   # Filter: ASCII printable 0x20-0x7e, newlines, UTF-8 sequences
+   ole.close()
+   ```
+
+3. **.xlsx → markdown table** via openpyxl:
+   ```python
+   wb = openpyxl.load_workbook(src_path, data_only=True)
+   for sheet_name in wb.sheetnames:
+       ws = wb[sheet_name]
+       # Find header row, build markdown table (header + align + rows)
+   ```
+
+**Output:** Each source file → `docs/policy-<sanitized-name>.md` with H1 = original filename, quote block indicating source file, and body text.
+
+**Logging:** Each conversion writes to `logs/convert-<name>.log` with pandoc stdout/stderr and exit code.
+
+### Phase 2 — Merge Into Comprehensive Document
+
+Organize by region/theme with the structure:
+```
+## [[Region]]
+### [Document Name]
+[full text body]
+```
+
+1. Define document groups with descriptions
+2. For each group, read the markdown from docs/
+3. Strip auto-generated duplicate headers (h1 + source line)
+4. Insert under the appropriate h2 section header
+5. Generate table of contents
+
+### Phase 3 — Generate Summary + Time Annotations
+
+When the source documents are policies or regulatory filings, extract and annotate time metadata:
+
+- **Policy validity periods** — title-embedded ranges (e.g. "2025—2027年")
+- **Milestone targets** — "到2027年" goals (bed counts, coverage rates, etc.)
+- **Effective/enforcement dates** — "自...起施行" or "印发之日起"
+- **Application deadlines** — "于...前报送" or "申报截止"
+- **Funding/subsidy cutoffs** — per-item expiration dates
+- **Project execution periods** — "实施周期不超过3年" clauses
+
+Add a `> **发文：** ... ｜ **文号：** ... ｜ **目标节点：** ...` line after each h3 policy heading in the merged document. See `references/policy-time-metadata.md` for the full category breakdown.
+
+### Phase 4 — Generate Summary + PDF
+
+1. Write `summary.md` with: overview, per-group summary tables, cross-cutting theme analysis, key data points, and the time metadata section.
+
+2. Convert to PDF via markdown → HTML → weasyprint. **CRITICAL: Pandoc's default HTML5 output does NOT produce a full HTML document.** Without `--standalone` / `-s`, pandoc outputs only body content — no `<html>`, `<head>`, or `<style>` tags. CSS injection via `</head>` replacement **fails silently**, and weasyprint falls back to a font without CJK glyphs → garbled PDF.
+
+   **The Fix — Always wrap pandoc output in a complete HTML document:**
+
+   ```python
+   import subprocess
+   from pathlib import Path
+
+   md_path = Path("summary.md")
+   pdf_path = Path("summary.pdf")
+
+   # Step 1: Get body HTML from pandoc (capture stdout, no -o flag)
+   result = subprocess.run(
+       ["pandoc", str(md_path), "-f", "markdown", "-t", "html5",
+        "--wrap=none", "--quiet"],
+       capture_output=True, text=True, timeout=30
+   )
+   body_html = result.stdout
+
+   # Step 2: Wrap in full HTML document with CSS
+   full_html = f"""<!DOCTYPE html>
+   <html lang="zh-CN">
+   <head>
+   <meta charset="utf-8">
+   <title>{title}</title>
+   <style>
+     @page {{ size: A4; margin: 2cm; }}
+     body {{ font-family: 'WenQuanYi Zen Hei', 'Noto Sans CJK SC', sans-serif;
+            font-size: 11pt; line-height: 1.7; }}
+     h1 {{ font-size: 20pt; color: #1a3a5c; border-bottom: 2px solid #1a3a5c; }}
+     h2 {{ font-size: 16pt; color: #2a5a8c; margin-top: 24px; }}
+     table {{ border-collapse: collapse; width: 100%; }}
+     th, td {{ border: 1px solid #aaa; padding: 6px 10px; }}
+     th {{ background-color: #e8f0f8; }}
+   </style>
+   </head>
+   <body>
+   {body_html}
+   </body>
+   </html>"""
+
+   # Step 3: Write temp HTML and convert
+   html_path = pdf_path.with_suffix('.html')
+   html_path.write_text(full_html, encoding='utf-8')
+   subprocess.run(["weasyprint", str(html_path), str(pdf_path)], timeout=60)
+   html_path.unlink()
+   ```
+
+   **Alternative — Python markdown renderer (for large files):** When the merged markdown exceeds 500KB / 4000+ lines, pandoc may timeout. Use `scripts/convert_md_to_pdf.py` instead:
+   ```bash
+   uv run scripts/convert_md_to_pdf.py <input.md> <output.pdf>
+   ```
+   This script has its own markdown→HTML renderer that handles Chinese headings, pipe tables, blockquotes, lists, code blocks, and `---` horizontal rules without pandoc's YAML issue.
+
+3. **Font Requirements:** This system has `WenQuanYi Zen Hei` at `/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc`. The CSS font-family MUST list this font first. Do NOT use:
+   - `Noto Sans CJK SC` (not installed)
+   - `Source Han Sans SC` (not installed)
+   - `SimSun` (not installed)
+   - `Microsoft YaHei` (not installed)
+   These fail silently and produce garbled output.
+
+4. **Keep both .md and .pdf.** Delete the intermediate .html.
+
+### Phase 5 — Verify PDF Output
+
+```bash
+pdftotext output.pdf - | head -20
+# Expected: clean Chinese like "政策文件汇编 — 摘要"
+# Bad: garbled like "政ç–文件汇编" (font or CSS wrapping issue)
+```
+
+## Pitfalls
+
+- **Chinese vs English `政策`/`policy` prefix mismatch** — the conversion script saves files as `policy-<name>.md` but the merge script may look for `政策-<name>.md`. The `policy-` prefix (English) is correct — align all keys with actual filenames.
+- **.doc binary extraction is lossy** — olefile extracts raw text from the WordDocument stream, which may include metadata, lose formatting, or produce fragments. Always note in the merged doc: "从旧格式 .doc 提取，格式可能不完整".
+- **Pandoc timeout** — large files (>500KB) can take >30s via stdin. Set timeout to at least 120s or use `scripts/convert_md_to_pdf.py`.
+- **Markdown anchor links** — Chinese characters in TOC anchors may not work in all renderers. For pandoc compatibility, ASCII-only anchors are safer.
+- **Memory pressure** — 16+ documents merged can exceed 500K chars. Keep the summary small; the full merged file is for reference.
+- **`---` horizontal rule = YAML parse exception** — pandoc interprets `---` lines as YAML metadata block delimiters, even with `-f markdown`. Replace with `<hr>` or use the Python renderer script.

task-framework/skills/task-framework/references/operations/code-write.md

@@ -0,0 +1,30 @@
+# Operation: code-write
+
+Implement a feature or fix in code, with tests.
+
+## Workflow
+
+1. **Understand the requirement** — read TASK.md, PRD/TRD, existing code patterns
+2. **Plan** — what files need changing, in what order (data → logic → UI)
+3. **Write tests first** (TDD) — red phase
+4. **Implement** — make tests pass (green)
+5. **Refactor** — clean up duplication, naming, structure
+6. **Verify** — run test suite, manual smoke test if applicable
+
+## Input
+
+- Task description or PRD section
+- Existing codebase to integrate with
+
+## Output
+
+- Changed source files
+- Passing test suite
+- Updated TASK.md checklist
+
+## Pitfalls
+
+- Skipping test design — TDD exists because it works. Don't skip red phase.
+- Over-engineering — implement the simplest thing that works first, then refactor.
+- Missing edge cases — nulls, empties, boundaries, error states.
+- Commit message convention — use `feat:` / `fix:` based on file functional role (skills/rules → feat, even if .md).

task-framework/skills/task-framework/references/operations/document-write.md

@@ -0,0 +1,185 @@
+# document-write — 编写结构化文档
+
+## When to Use
+
+编写产品/技术类文档，包括但不限于：
+- 产品需求文档 (PRD) — 做什么、为什么
+- 产品设计文档 — 用户看到什么、怎么交互
+- 技术需求文档 (TRD) — 技术约束、架构模式
+- 技术设计文档 — 代码怎么实现
+
+## Four-Document Pattern
+
+For feature-level work, the user prefers a **four-document split** (an evolution of the original PRD+TRD pair):
+
+| Doc | Content | Audience |
+|-----|---------|----------|
+| **产品需求** (PRD) | 功能描述、用户故事、优先级、需求来源 | 产品/业务 |
+| **产品设计** | 布局图（ASCII）、交互流程、视觉规范、颜色方案、组件状态 | 设计师/前端 |
+| **技术需求** (TRD) | 架构模式、数据模型、状态管理、API 定义、技术约束 | 后端/架构 |
+| **技术设计** | 组件结构、代码实现细节、CSS 模式、已知问题清单 | 开发实施 |
+
+### Relationships
+
+```
+产品需求  ──说明→  产品设计
+   │                    │
+   解释"为什么"       解释"怎么用"
+   │                    │
+   ▼                    ▼
+技术需求  ──约束→  技术设计
+                    （具体实现）
+```
+
+### File Naming
+
+Project-level naming convention:
+```
+docs/
+├── product-requirements.md              ← 产品需求 (PRD)
+├── sales-product-design.md              ← 产品设计
+├── technical-requirements.md            ← 技术需求 (TRD)
+└── sales-technical-design.md            ← 技术设计
+```
+
+For domain-specific modules, prefix with module name: `sales-*`, `product-*`, etc.
+
+### Versioning
+
+Each doc should have a header block:
+```markdown
+> **版本:** v0.1
+> **状态:** 前端已实现（Mock 数据）
+> **最后修改:** 2026-06-04
+```
+
+## Layout Visualization
+
+For UI/UX documents, use ASCII-art tree diagrams to show layout structure. Use Unicode box-drawing characters for column layouts:
+
+```
+┌─────────────────────┬──────────────────────────┐
+│  Left (2/3)         │  Right (1/3)             │
+│                     │  ┌─ Panel A (2/3) ─────┐ │
+│  Content here       │  │  ...                │ │
+│                     │  └─────────────────────┘ │
+│                     │  ┌─ Panel B (1/3) ─────┐ │
+│                     │  │  ...                │ │
+│                     │  └─────────────────────┘ │
+└─────────────────────┴──────────────────────────┘
+```
+
+For tighter representations, use ASCII tree diagrams:
+
+```
+└─ order-left (flex column)
+   ├─ order-top-half (flex:1)
+   │  ├─ section-title
+   │  ├─ search input
+   │  └─ product-list (flex:1, scroll)
+   └─ order-bottom-half (flex:1, border-top)
+      ├─ section-title
+      └─ selected-list (flex:1, scroll)
+```
+
+## Standard Tables
+
+Use pipe tables in the following standardized formats:
+
+### Component/Property Specs
+```markdown
+| 元素 | 字号 | 粗细 | 圆角 |
+|------|------|------|------|
+| 面板头部 | 13px | 600 | — |
+| 建议标签 | 10px | 600 | 4px |
+```
+
+### Color/Variable Specs
+```markdown
+| 用途 | CSS 变量 / 值 | 说明 |
+|------|--------------|------|
+| 背景（画布） | `var(--chakra-colors-bg-canvas, #fff)` | 纯白底 |
+| 文字（默认） | `var(--chakra-colors-fg-default, #1a202c)` | 正文 |
+```
+
+### API Endpoints
+```markdown
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/sales/leads` | 潜客列表 |
+```
+
+### Data Models
+```markdown
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | string | 主键 |
+```
+
+## Integration with software-dev Composite
+
+The `document-write` operation appears in the `software-dev` composite pattern at step 2:
+
+```
+0. [git] Pre-Change Sync
+1. info-search    → 调研现有方案
+2. document-write → 写 PRD/TRD + 产品设计/技术设计
+3. code-write     → 实现（TDD）
+4. code-review    → 审查
+5. [git] Post-Change Workflow
+```
+
+For feature work that's already implemented (docs-as-built, not docs-as-spec), write all four docs together to capture the complete design intent for future maintenance.
+
+## Functional Semantics Requirement
+
+**Every element described in a document must include its functional semantics** — the purpose, intent, and behavior, not just a label or position. This ensures the doc is usable for future reference and verification, not just a build checklist.
+
+### What to include per element type
+
+| Element type | Must include | Good example | Poor example |
+|-------------|-------------|-------------|-------------|
+| **Button** | What happens on click, what triggers it, what outcome for user | "🔍预览 — 根据当前已选产品动态生成订单详情+收款码组合图片并在浮层展示。用于让销售在发送前确认内容排版和金额正确。" | "预览按钮，弹出浮层" |
+| **Tab / Sub-tab** | What content, when visible, what user goal | "AI对话 — 三栏布局：左侧聊天界面（销售↔AI交流），右侧历史记录（按渠道分组）+ AI分析建议。用于快速记录客户跟进、查看历史对话。" | "AI对话 tab" |
+| **Display area / panel** | What data, what user can do, why it exists | "收款码下方独立操作卡片：包含4个操作按钮，用于对已生成的订单图片进行预览确认、发送给客户、复制到剪贴板或下载保存。" | "收款码下方有操作按钮" |
+| **Interaction** | Full cause-effect chain: user action → system action → user sees | "点击待办事项 → 系统通过openLead将该潜客加入已打开列表，setActiveView切换到潜客管理或客户管理，右侧详情面板同步打开。" | "点击待办跳转到详情" |
+| **Permission / visibility rule** | Who can see it, when it appears, when hidden | "数据显示子tab — 仅role===admin的销售员可见。非管理员看不到该tab按钮，也不影响其他视图。" | "管理员可见" |
+
+### Why it matters
+1. **Future verification**: A new developer (or the same agent in a future session) should understand what a feature is supposed to DO, not just where it RENDERS.
+2. **Cross-reference with implementation**: Detailed semantics make it possible to detect drift between spec and code. "预览弹出浮层" vs "预览动态生成图片并弹窗展示" — the latter is testable, the former is vague.
+3. **Design iteration**: When the user says "the meaning of this button should be clearer", the doc should already contain the semantic description so the conversation starts from a shared understanding.
+
+### Integration into the workflow
+
+When writing or updating any of the four docs:
+1. For every new button, tab, panel, or interaction being described, write its functional semantics in the same pass
+2. When reading an existing doc, note where semantic descriptions are missing — these become qualified items for the "待完善事项" table
+3. Do NOT defer semantics to a later cleanup step — the doc is not complete until every user-facing element has a "why" or "what happens" description
+
+## Cross-Referencing with Session History
+
+When writing "as-built" docs for work already implemented, use the `conversation-message-list` skill to review the actual conversation and extract the precise set of changes:
+
+```bash
+# Get the session ID for the relevant conversation
+hermes sessions list
+
+# Show compact Q&A history (no tool calls)
+python3 ~/.hermes/skills/hermes/conversation-message-list/scripts/list-messages.py <session_id>
+```
+
+This gives a tool-call-free list of every user question and final answer, which maps directly to feature requirements and design decisions.
+
+## Pitfalls
+
+| Pitfall | Correction |
+|---------|------------|
+| Writing only PRD without design/tech docs | Split into all four to cover product + implementation perspectives |
+| ASCII diagrams with ambiguous proportion | Mark flex ratios explicitly (`flex: 2` / `flex: 1`) in the diagram caption |
+| Ignoring user feedback-coupling | Use feedback-station skill to cross-reference doc sections with user feedback IDs |
+| Doc status unchanged after implementation | Update status from "需求讨论中" to actual development phase |
+| No known-issues section in tech design | Always include a backlog/Known Issues table to track gaps |
+| Overwriting existing PRD structure | Read existing doc first, then append/update sections — don't rewrite from scratch |
+| Writing docs from memory instead of session replay | Use `conversation-message-list` skill to re-read the actual conversation for accurate change scope |
+| Forgetting to update sibling docs | When any one doc changes, check and update all four — they form a coherent set |

task-framework/skills/task-framework/references/operations/info-search.md

@@ -0,0 +1,27 @@
+# Operation: info-search
+
+Multi-source information search and capture — competitor analysis, policy research, tech stack evaluation.
+
+## Workflow
+
+1. **Identify search targets** — competitors, products, papers, policies
+2. **Collect from each source** — web_search, arXiv, policy databases
+3. **Write findings** — one markdown file per source in `tasks/<ts>.<name>/docs/`
+4. **Tag sources** — note date, source URL, confidence level
+5. **Update README.md** — add summary table of collected docs
+
+## Input
+
+- List of search queries or targets
+- Domain context (industry, technology area)
+
+## Output
+
+- `docs/*.md` — one file per source
+- Updated `README.md` with collected-docs summary table
+
+## Pitfalls
+
+- Blind trust in one source — cross-validate with multiple searches
+- Missing search freshness — note date of retrieval
+- Scope creep — agree on search scope before starting

task-framework/skills/task-framework/references/operations/web-research.md

@@ -0,0 +1,57 @@
+# Operation: web-research
+
+单站或多站网页调研 — 读取 URL 内容、提取关键信息、生成结构化摘要。
+
+## 适用场景
+
+- 竞品官网分析
+- 产品/服务调研
+- 技术文档速读
+- 含截图附件的综合调研
+
+## Workflow
+
+1. **解析调研目标** — 从 TASK.md 或对话中获取 URL 列表和调研目的
+2. **读取网页内容** — 对每个 URL：
+   - 首选 curl（纯文本/API 端点，如 .md/.json/.yaml）
+   - 次选 browser_navigate（富交互页面）
+3. **处理附件** — 扫描 `input/` 目录，对截图/图片执行 OCR（tesseract）
+4. **整理摘要** — 统一写入 `output/summary.md`
+5. **内容讨论** — 讨论纪要写入 `output/discuss.md`
+
+## 典型 Checklist
+
+```
+- [x] Phase 1 — 读取 <url1> 内容
+- [x] Phase 2 — 读取 <url2> 内容
+- [x] Phase 3 — 处理 input/ 附件（OCR）
+- [x] Phase 4 — 保存 summary 到 output/summary.md
+- [x] Phase 5 — 保存内容讨论到 output/discuss.md
+- [ ] BREAK: 确认产出物是否符合要求
+```
+
+## Input
+
+- URL 列表（由 TASK.md 或用户指定）
+- `input/` 中的截图/图片（可选）
+
+## Output
+
+- `output/summary.md` — 结构化调研摘要（含来源标注）
+- `output/discuss.md` — 仅限调研内容本身的后续讨论
+
+## 工具链
+
+| 步骤 | 工具 |
+|------|------|
+| 网页读取 | `curl`（纯文本）、`browser_navigate` + `browser_console`（富页面） |
+| 图片 OCR | `tesseract`（`-l eng+chi_sim`）|
+| 文件保存 | `write_file` 到 `output/` |
+
+## Pitfalls
+
+- **不保存网页原始内容** — 除非用户明确要求，summary 已提炼关键信息，避免冗余存档
+- **discuss.md 只放内容讨论** — 任务元讨论（skill/pipeline 设计）是对话内容，不放任务产出物
+- **OCR 可能不准** — 中文截图建议用 `chi_sim` 语言包；多语言混排用 `eng+chi_sim`
+- **内容重复** — 多个页面可能有重叠信息，summary 中应去重合并
+- **区分 summary 和 discuss** — summary 是调研结论（客观），discuss 是后续分析和疑问（主观）

task-framework/skills/task-framework/references/policy-time-metadata.md

@@ -0,0 +1,137 @@
+# Policy / Regulatory Document Time Metadata Extraction
+
+When processing a batch of policy or regulatory documents, extract and categorize all time-related information. This enables chronological analysis, deadline tracking, and compliance planning.
+
+## Time Metadata Categories
+
+### 1. Title-Embedded Period (标题自带周期)
+
+Some policies declare their validity period in the title itself. These are the most visible:
+
+```
+浙江省加快推动"人工智能+医疗健康"高质量发展行动计划（2025—2027年）
+重庆市智慧医疗装备产业创新发展行动计划（2025—2027年）
+```
+
+**Extraction pattern:** grep for parenthesized year ranges in document titles. Regex: `（\d{4}—\d{4}年）`
+
+### 2. Target Milestone ("到 X 年" goals)
+
+Almost every policy includes specific quantitative targets with a deadline year. These drive execution priorities.
+
+| Pattern | Example |
+|---------|---------|
+| "到 2027 年，……" | 到 2027 年，适老化改造累计完成不少于 12 万户 |
+| "到 2026 年……；到 2027 年……" | 分阶段目标（如 AI 普及率 70% → 80%） |
+
+**Extraction:** grep for `到 \d{4} 年` and collect the subsequent metric + value.
+
+### 3. Effective / Enforcement Date (施行日期)
+
+When the policy takes legal effect:
+
+| Source | Examples |
+|--------|----------|
+| "自 XXXX 年 XX 月 XX 日起施行" | 自 2025-01-22 起施行 |
+| "自印发之日起施行" | 重庆市创新医疗器械管理办法 |
+| "自 XXXX 年 XX 月 XX 日起执行，有效期 X 年" | 深圳宝安区措施：3 年 |
+
+**Extraction:** grep for `自.*起施行|自.*起执行|有效期.*年`
+
+### 4. Filing / Application Deadline (申报截止)
+
+For competitive programs, funding applications, and pilot project solicitations:
+
+| Source | Deadline |
+|--------|----------|
+| "请于 XXXX 年 XX 月 XX 日前报送" | 海珠区 AI 场景：2026-04-18 |
+| "于 XXXX 年 XX 月 XX 日前将申报材料报送" | 养老机器人试点：2025-07-10 |
+
+**Extraction:** grep for `于.*前|截止.*时间|报送.*日期`
+
+### 5. Subsidy / Funding Expiration (补贴截止)
+
+Each subsidy program has its own end date, often in the supporting table rather than the policy body:
+
+| Expression | Meaning |
+|------------|---------|
+| "政策实施期限暂定 2026 年" | Tentative, subject to extension |
+| "政策实施截至 2027 年 12 月 31 日" | Hard deadline |
+| "试行 1 年" | 1-year trial from issuance date |
+| "至 2028-05" | Month-level precision |
+| "至 2028 年 12 月 31 日结束" | Year-end hard stop |
+
+**Extraction:** grep for `期限|截止|结束|试行.*年|有效期` in subsidy/funding sections.
+
+### 6. Project Execution Period (项目实施周期)
+
+For programs that fund specific projects, the allowable execution window:
+
+| Provision | Example |
+|-----------|---------|
+| "实施周期原则上不超过 X 年" | 重庆市创新医疗器械：≤ 3 年 |
+| "可延长，最长 1 年" | With extension mechanism |
+| "每个项目只能申请 1 次时间延长" | One-time extension limit |
+
+### 7. Document Issuance Date (发文日期)
+
+The official publish date from the document footer. Useful for recency assessment:
+
+| Source | Example |
+|--------|---------|
+| Government document footer | 2025 年 2 月 24 日 |
+| Official letter number | 粤府办〔2025〕4号（year embedded in 文号） |
+
+## Practical Workflow
+
+### Step 1 — Scan all documents for time patterns
+
+Use a broad grep across all converted markdown files:
+
+```bash
+cd tasks/<task-name>/docs
+grep -n -E '(有效期|截止|自.*起|至.*止|期限|到.*年|试行|实施.*年|年度)' *.md | grep -v '来源文件'
+```
+
+### Step 2 — Categorize into the 7 types above
+
+Group results by category. Some entries may fit multiple categories — pick the primary one.
+
+### Step 3 — Annotate the merged document
+
+For each policy heading in the merged document, add a blockquote line:
+
+```markdown
+### Policy Name
+
+> **发文：** 2025-02-24 ｜ **文号：** 粤府办〔2025〕4号 ｜ **目标节点：** 2027 年
+> **施行：** 2025-05-18 ｜ **有效期：** 3 年（至 2028-05-18）
+> **申报截止：** 2026-04-18
+```
+
+Use pipe-separated format within a single `>` line for compactness. Multiple lines only when a policy has many time attributes.
+
+### Step 4 — Add a summary table to summary.md
+
+In the summary document, add a comprehensive time table:
+
+```markdown
+## 政策有效期与关键时间节点
+
+### 目标完成期限
+| 政策 | 节点目标 | 期限 |
+|------|---------|------|
+| ... | ... | 2027年 |
+
+### 申报截止日期
+| 项目 | 截止时间 |
+|------|---------|
+| ... | 2026-04-18 |
+```
+
+## Pitfalls
+
+- **文号中的年份** — 渝府办发〔2025〕57号 tells you the year is 2025, but the actual validity may extend to 2027. The 文号 year is the issuance year, not the policy period.
+- **"试行" ≠ short-term** — 试行 policies often remain in effect indefinitely until formally replaced. The trial label means the policy is provisional, not that it has a hard expiration.
+- **Deadlines in attachments** — critical deadlines (especially for subsidies) are often in XLSX spreadsheets or appendix tables, not the main policy body. Always scan supplementary files.
+- **Cross-referencing other policies** — some policies say "有效期至 XXXX 年" but the referenced implementation rules may have a different timeline. Document both.