docsif 0.2.0__tar.gz → 1.0.1__tar.gz

{docsif-0.2.0 → docsif-1.0.1}/.github/workflows/docs.yml

@@ -13,9 +13,13 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   docs-test:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
 
@@ -29,10 +33,10 @@ jobs:
           pip install -e ".[dev]"
 
       - name: Run docs tests
-        run: pytest tests/test_docs.py -v
+        run: pytest tests/test_docs.py -v --no-cov
 
       - name: Verify generation scripts work
         run: |
           python scripts/generate_cli_ref.py
           python scripts/generate_config_ref.py
-          git diff --exit-code docs/cli-reference.md docs/configuration.md || true
+          git diff --exit-code docs/cli-reference.md docs/configuration.md

docsif-1.0.1/.gsd/.gitignore

@@ -0,0 +1 @@
+*

docsif-1.0.1/.gsd/dispatch-isolation-sentinel.json

@@ -0,0 +1 @@
+{"isolation":"none","harness_flag":null,"phase":null,"plan":null,"written_at":1794012884815}

docsif-1.0.1/.planning/.continue-here.md

@@ -0,0 +1,80 @@
+---
+context: default
+phase: none
+task: 0
+total_tasks: 0
+status: milestone_shipped
+last_updated: 2026-11-06T23:17:56.807Z
+---
+
+# BLOCKING CONSTRAINTS — Read Before Anything Else
+
+> These are not suggestions. Each constraint below was discovered through failure.
+> Acknowledge each one explicitly before proceeding.
+
+- [ ] CONSTRAINT: generator-owned docs are version-sensitive by construction — any change to generator behavior or the libraries they introspect (Click majors, Python minors, pydantic) re-drifts `docs/cli-reference.md`/`configuration.md`; after touching a generator or bumping an introspected dep, ALWAYS run `make docs-generate` and commit the regenerated output before push, or CI's `git diff --exit-code` gate fails.
+
+**Do not proceed until the box is checked.**
+
+## Critical Anti-Patterns
+
+| Pattern | Description | Severity | Prevention Mechanism |
+|---------|-------------|----------|---------------------|
+| Floors-only unpinned deps | CI installs latest deps (Click 8.5 vs local 8.3) and behavior diverged, failing the drift gate; a fresh-install test env also surfaced undeclared pytest-asyncio | advisory | Generator output is now version-normalized; before releases, smoke-test a FRESH venv install (`uv pip install docsif[dev]`) — it catches undeclared/exploded deps the canonical env masks |
+| Post-verification edits re-stale fingerprints | Fixing files covered by an already-verified phase (shared surfaces: get.py, Makefile, docs) invalidates that phase's digest, cascading | advisory | Sequence wide fixes BEFORE verifiers run, or expect one extra regeneration round; check `verification.status` per phase after multi-phase fix sessions |
+
+<current_state>
+Milestone v1.0 is SHIPPED and RELEASED. All planning artifacts archived under `.planning/milestones/v1.0-*`; `.planning/phases/` and `.planning/quick/` are empty; ROADMAP collapsed to a shipped-milestone summary; tag `v1.0` pushed; PR #1 (dev→main) open with green CI; **docsif 1.0.0 live on PyPI** (verified installable). No active phase work.
+</current_state>
+
+<completed_work>
+
+- Milestone v1.0 close: verified_closeout, zero overrides (audit 3/3 resolved, not acknowledged)
+- 4 stale phase verifications regenerated (05/06/07/10.1) — 5 review criticals + 4 verification gaps fixed en route (get.py markup display ×2, generator pipes/version-drift, README command, docs CI `--no-cov`, Mermaid sync, phantom fusion, k1)
+- Version 1.0.0 (6 sites), tag v1.0, archives, MILESTONES.md, RETROSPECTIVE.md
+- Pushed dev (207 commits) + tag; PR #1 created; CI Docs Validation failure diagnosed (Click 8.5 drift) and fixed — green
+- PyPI: published as **docsif 1.0.0** (`sif` taken; user chose their own registered name)
+- numpy≥2: canonical suite (numpy 2.3.5) 1015 green; published wheel on numpy 2.5.4 → CLI smoke + 974/974
+- pytest-asyncio added to dev extras (fresh-env 56-failure root cause)
+</completed_work>
+
+<remaining_work>
+
+No open phase work. Backlog (all ledgered in archived REVIEW-DISPOSITION files):
+- 10-REVIEW WR-01..10, 10.1 IN-10..13, 07 WR-02/IN-02/03, delta WR-02 (pip constraints)/IN-02
+- Version quadruplication sync mechanism; arch-generator CI wiring; Makefile test-fast echo wording; mcp/cli.py 0% shim; `context remove/prune` confirmation guardrails
+- Human: merge PR #1; optionally `rm -rf ~/.claude/skills/docsift-{get,search}` (stale pre-rename dirs)
+</remaining_work>
+
+<decisions_made>
+
+- Distribution name `docsif` on PyPI (import/console name stays `sif`)
+- verified_closeout after resolving everything (user principle: resolve, don't acknowledge)
+- Generator outputs normalized version-insensitively rather than pinning CI deps
+- pytest-asyncio fix rides the next release (dev extras don't affect runtime users)
+</decisions_made>
+
+<blockers>
+- None
+</blockers>
+
+## Required Reading (in order)
+
+1. `.planning/MILESTONES.md` — what v1.0 shipped
+2. `.planning/RETROSPECTIVE.md` — patterns/lessons (display-integrity triple precedent, gate discipline)
+3. `.planning/STATE.md` — current position (Awaiting next milestone)
+
+## Infrastructure State
+
+- Branch `dev` @ d0682ba pushed; PR #1 open (CI green); tag `v1.0` pushed
+- PyPI: docsif 1.0.0 published (pypi.org/project/docsif/1.0.0/) — twine creds in `~/.pypirc` ([pypi] + [testpypi])
+- CI: Docs Validation green (run 42310044731) — triggers on docs/README/cli/config/scripts/test_docs paths
+- Untracked by intent: `.planning/state.json` (runtime contract state), `.planning/tmp/` (transient)
+
+<context>
+Session arc: resume → quality gates → ty debt cleared → docs verified → user directed milestone close with "resolve everything" → 4-phase verification regeneration (with real bug fixes surfaced by each round) → clean closeout → push/PR → CI fix → PyPI release (name collision resolved to docsif) → numpy≥2 verification → dev-extras fix. The release is complete; next session starts fresh at milestone planning.
+</context>
+
+<next_action>
+Start with: `/gsd-new-milestone` (or merge PR #1 first if handling the release flow manually).
+</next_action>

docsif-1.0.1/.planning/HANDOFF.json

@@ -0,0 +1,37 @@
+{
+  "version": "1.0",
+  "timestamp": "2026-11-06T23:17:56.807Z",
+  "phase": null,
+  "phase_name": null,
+  "phase_dir": null,
+  "plan": null,
+  "task": null,
+  "total_tasks": 0,
+  "status": "paused",
+  "completed_tasks": [
+    {"id": 1, "name": "Milestone v1.0 close — verified_closeout (11/11 phases fresh-verified, 31/31 requirements, zero overrides)", "status": "done", "commit": "b63eca1"},
+    {"id": 2, "name": "Four stale-verification regenerations (05/06/07/10.1) incl. 5 review criticals fixed along the way", "status": "done", "commit": "92e0150"},
+    {"id": 3, "name": "Version 1.0.0 bump + tag v1.0 + archives (milestones/v1.0-*) + RETROSPECTIVE", "status": "done", "commit": "11b8640"},
+    {"id": 4, "name": "Push dev + tag; PR #1 dev→main", "status": "done", "commit": "1115409"},
+    {"id": 5, "name": "CI Docs Validation fixed (Click 8.5 vs 8.3 generator divergence normalized) — run 42310044731 green", "status": "done", "commit": "1115409"},
+    {"id": 6, "name": "PyPI release: docsif 1.0.0 published (sif name taken; docsif is the project's own registered name)", "status": "done"},
+    {"id": 7, "name": "numpy>=2 verification: canonical suite 1015 green on numpy 2.3.5; fresh install of PUBLISHED wheel on numpy 2.5.4 → CLI smoke + 974/974 (torch-only module excluded)", "status": "done", "commit": "d0682ba"},
+    {"id": 8, "name": "pytest-asyncio declared in dev extras (fresh-install 56-failure root cause; ships next release)", "status": "done", "commit": "d0682ba"}
+  ],
+  "remaining_tasks": [],
+  "blockers": [],
+  "async_jobs": [],
+  "human_actions_pending": [
+    {"action": "Merge PR #1 (dev → main)", "context": "CI green, v1.0 tagged and published; merge completes the release flow", "blocking": false},
+    {"action": "Optionally remove stale pre-rename skill dirs: rm -rf ~/.claude/skills/docsift-get ~/.claude/skills/docsift-search", "context": "P07-T05: they teach the nonexistent docsift CLI; repo-side sif-* symlinks are correct. Agent home-dir deletion was permission-blocked by design", "blocking": false}
+  ],
+  "decisions": [
+    {"decision": "Distribution name = docsif on PyPI", "rationale": "'sif' taken by an unrelated project; docsif is this account's own registered name (0.1.x-0.2.0). Import name and sif console script unchanged", "phase": "release"},
+    {"decision": "verified_closeout with zero overrides", "rationale": "User chose 'resolve everything': UAT gap live-verified, ResourceWarnings fixed (17→0 warnings), mypy ledger resolved, then 4 stale phases regenerated to fresh fingerprints", "phase": "close"},
+    {"decision": "CLI-reference generator normalized against Click version drift", "rationale": "CI installs unpinned Click (8.5) vs local 8.3: flag defaults (None vs False) and help indentation diverged, failing the drift gate. cleandoc + flag-default canonicalization make output version-insensitive", "phase": "release"},
+    {"decision": "pytest-asyncio added to dev extras rather than republishing 1.0.0", "rationale": "dev extras do not affect runtime installs; the gap only breaks fresh contributor envs; ships with the next version", "phase": "release"}
+  ],
+  "uncommitted_files": ["?? .planning/state.json", "?? .planning/tmp/"],
+  "next_action": "/gsd-new-milestone to plan the next version (v1.1 candidates: LLM query expansion backlog item, open review ledgers WR-01..10/IN-10..13, version-sync mechanism, arch-generator CI wiring). Or merge PR #1 first.",
+  "context_notes": "Milestone v1.0 fully shipped: 11/11 phases verified-closeout, archived under .planning/milestones/v1.0-*, tag v1.0 pushed, docsif 1.0.0 live on PyPI (verified installable with numpy 2.5 + click 8.5 + latest starlette). Known follow-ups live in the phase REVIEW-DISPOSITION ledgers (now in milestones/v1.0-phases/). KNOWN QUIRKS: STATE.md frontmatter progress fields undercount by tool accounting — body is authoritative, do not hand-fix. Fresh-install dev envs now get pytest-asyncio via extras; torch is only in 'all' extras and tests/unit/inference/test_reranker.py needs it directly (skip with --ignore on minimal envs)."
+}

docsif-1.0.1/.planning/MILESTONES.md

@@ -0,0 +1,52 @@
+# Milestones
+
+## v1.0 MVP — qmd 功能对等的本地混合搜索引擎 (Shipped: 2026-11-07)
+
+**Phases completed:** 11 phases, 68 plans, 112 tasks
+
+**Key accomplishments:**
+- Added all missing runtime dependencies to pyproject.toml so `pip install -e .` succeeds and the CLI launches without ModuleNotFoundError.
+- Converted FTS5 virtual tables to external content tables with SQLite triggers, removed stale sqlite_repository.py, and fixed BM5 rowid joins.
+- Fixed inverted checksum logic in index update and removed hardcoded embedding model paths, aligning CLI and embedder defaults with Settings
+- Replaced random/placeholder embedding implementations in the factory with real `sentence-transformers` and `llama-cpp-python` loaders, and unified the `ModelType` enum across modules.
+- Made sqlite-vec a hard requirement for vector search, removed all Python brute-force fallbacks, and rewrote the vsearch CLI to fail fast with clear errors.
+- Implemented `multi-get` command with auto-detection for comma-separated IDs, glob patterns, and single docid/path fallback, plus full unit test coverage.
+- Top-level `docsift ls` command displaying indexed documents as a virtual file tree, with optional collection and subpath filtering
+- Collection update-cmd, include/exclude subcommands, and pre-index shell hook with fail-fast subprocess execution
+- Wired `--all` flag into `search`, `query`, and `vsearch` CLI commands so default searches respect `include_by_default` collection setting.
+- Implemented OpenAIEmbedder with dimension auto-detection, added MODELSCOPE to ModelType, refactored the factory to return Embedder protocol instances, and created unit tests for all backends.
+- Refactored EmbeddingManager to work with the Embedder protocol and added comprehensive unit tests.
+- OpenAIEmbedder(Embedder) with generic OpenAI-compatible endpoint support (api_base → {api_base}/embeddings), per-model dimension auto-detection cached to openai_dim_cache.json with a 7-day TTL and fail-fast SIF_EMBEDDING_DIM mismatch validation, wired through EmbeddingModelFactory — closing the single 03-VERIFICATION VEC-01 gap and delivering both missing Wave-0 test files.
+- Idempotent `sif index embed`: delete-before-insert replaces a re-chunked document's vec0 rows, and a per-document exact-set check skips complete documents unless `--force` — closing UAT gap G-03-3 where 7 runs on a 3-chunk collection left 21 searchable embedding rows returning the document 7 times.
+- Complete
+- QueryExpansion with embedding-based pseudo-relevance feedback returning list[str], and SmartSnippetExtractor scoring sentences by weighted query term frequency.
+- Snippet column in query/search CLI tables fed by transient content fetch and prefix-route snippet coverage.
+- Unified contexts table with SAVEPOINT atomic migration, ContextRepository with context_type filtering, and SearchResult.context_description field preserved through RRF fusion and cross-encoder reranking
+- Attach path context descriptions to all search results via batch query across BM25, vector, hybrid, and pipeline searchers.
+- Shared `_collapse_duplicate_path_rows` helper collapses every same-file spelling into one canonical row on ALL re-add paths (truth 21), and `context list` escapes all Rich table cells so markup-bearing content renders literally (CR-02).
+- escape() on every user-derived string crossing Rich in the search/vsearch/query tables and both explain prints — markup-bearing queries, titles, collection names, and content render literally instead of crashing with rich.errors.MarkupError
+- Bracket-named context targets are now addable — rich.markup.escape at the three confirmation prints (add create, add update, remove) stops the MarkupError that rolled back writes inside the transaction, locked by three machine-validated RED-first regression tests.
+- Auto-generated CLI reference via Click introspection, replacing stale manual documentation with accurate command/argument/option tables for all 32 commands.
+- Auto-generated configuration reference from Pydantic Settings introspection, eliminating 6 phantom fields and documenting 25 real settings with Qwen3 defaults.
+- Complete rewrite of docs/quickstart.md to match current CLI signatures, replacing all broken examples (collection create, add-path, update, search similar, mcp start) with working commands verified against installed package
+- Updated README.md and docs/index.md to reflect current v1.0 features, Qwen3 default models, and correct CLI examples while removing "planned" labels from already-implemented features.
+- Updated four technical docs and created an architecture diagram generator to reflect current implementation after Phases 1-5
+- Renamed Python package directory from `src/docsift/` to `src/sif/` and updated all `pyproject.toml` metadata, scripts, URLs, and tool configs.
+- SIF branding applied to all core constants, package metadata, and CLI entry point with automatic model cache migration from old docsift paths
+- Bulk mechanical rename of all internal imports and string references from `docsift` to `sif` across 54 source files, with zero remaining `from docsift` imports and full compile/import verification.
+- Updated Pydantic Settings env_prefix from "DOCSIFT_" to "SIF_", changed default DB path to "sif.db", and verified all filesystem paths resolve under sif/ directories.
+- All 31 test files migrated from `docsift` to `sif` imports, patch targets, and command references with pytest collecting 388 tests successfully
+- Full quality suite verification of DocSift-to-SIF rename with 377 tests passing, zero rename-related errors, and consistent SIF branding.
+- Deleted the D-01 dead-code cluster and re-baselined coverage from 78% to 81.48% (5320 statements, 985 missed), with 690 tests passing and live CLI imports intact.
+- Raised full-suite line coverage from 81.48% to 85.34% with real-SQLite CLI tests: collection 99.15%, main 86.99%, get 100%, and all D-06 order probes green.
+- Raised full-suite line coverage from 85.34% to 88.57% with deterministic reranker tests and 64 search CLI tests; rerank.py reached 98.60%, search.py 99.44%, and XML now safely escapes machine output.
+- Raised full-suite coverage from 88.57% to 90.89% with real-SQLite database/cache tests; repositories, database, schema, and cache reached 100%, migrations reached 92%, and real SQL exposed and proved fixes for stale FTS rows, lazy stats initialization, and broken migration scripts.
+- Raised full-suite coverage from 90.89% to 93.48% with 78 new behavior tests; all seven target files reached 100%, ModelScope/network/home boundaries remained isolated, and the tests exposed and proved fixes for custom logging formatter and indeterminate Rich progress defects.
+- Raised full-suite coverage from 93.48% to 96.16% with 83 new behavior tests, reached 100% parser/scanner/server/stdio coverage, and fixed chunker non-termination plus MCP session-limit defects exposed by the new edge cases.
+- Rehearsed the 90% gate at TOTAL 96.16% with zero long-tail additions and landed `[tool.coverage.report] fail_under = 90` as the single pyproject coverage config change — the canonical suite now exits 0 only when src/sif line coverage stays at or above 90%.
+- Symlink-alias paths now resolve to indexed documents across sif get/multi-get and MCP get_document via normalize_path-wrapped lookups, get.py owns its Database lifecycle, and the index-vs-disk fallback boundary is documented in the generated CLI reference.
+- Generalized legacy-FTS-trigger detector migrating direct-DELETE triggers to 'delete'-command form with a detection-gated 'rebuild' that purges stale MATCHable entries on the same open
+- W3C XML 1.0 Char-production sanitizer stripping forbidden code points from every `--xml`-bound string, plus context-manager Database ownership for search/query/vsearch with closure regression locks
+- Context-manager Database ownership at all 21 remaining CLI construction sites (6 modules) plus a TrackingDatabase closure harness asserting success- and exception-path closure
+
+---

docsif-1.0.1/.planning/PROJECT.md

@@ -0,0 +1,102 @@
+# DocSift
+
+## What This Is
+
+DocSift 是 [qmd](https://github.com/tobi/qmd) 的 Python 重构版本，一个面向个人知识库的**本地混合搜索引擎**。它索引 Markdown 笔记、文档和会议纪要，支持关键词搜索（BM25）、语义向量搜索（Vector Search），以及基于 LLM 的重排序（Rerank）和查询扩展。同时提供 CLI 工具和 MCP（Model Context Protocol）服务器两种使用方式，完全在本地运行，无需外部 API。
+
+## Core Value
+
+用户可以在自己的笔记和文档库中，用自然语言快速、准确地找到需要的信息——无论关键词是否匹配。
+
+## Requirements
+
+### Validated
+
+- ✓ 集合（Collection）的增删改查 — 现有
+- ✓ 基于文件扫描的文档索引（含 checksum 去重） — 现有
+- ✓ SQLite FTS5 全文搜索（BM25） — 现有
+- ✓ 基础混合搜索（BM25 + Vector + RRF） — 现有
+- ✓ MCP 服务器骨架（stdio + HTTP 双传输） — 现有
+- ✓ 多格式输出（rich table / JSON / CSV / Markdown / XML） — 现有
+- ✓ 文档片段（chunk）和嵌入存储 — 现有
+- ✓ 修复现有 bug 和占位实现（stub）：硬编码模型路径、随机 embedding fallback、MCP 连接安全等 — Validated in Phase 01
+- ✓ 依赖声明完整性：补全 `pyproject.toml` 中缺失的运行时依赖 — Validated in Phase 01
+- ✓ 补齐缺失的 CLI 命令：multi-get、ls、update-cmd、pull、bench — Validated in Phase 02/04
+- ✓ 嵌入模型灵活可配置：本地 GGUF（llama-cpp-python）、sentence-transformers、ModelScope，及可选 OpenAI 兼容 API（默认 Qwen3 系列） — Validated in Phase 03
+- ✓ LLM 重排序（Qwen3-Reranker）和查询扩展（SearchPipeline），`query` 搜索质量达标 — Validated in Phase 04/05
+- ✓ 统一 MCP 服务器实现（`src/sif/mcp/`，stdio + Streamable HTTP） — Validated in Phase 09
+- ✓ 上下文描述：path/collection/global 三种作用域，context CLI 全命令集，搜索结果自动附加描述 — Validated in Phase 05（2026-11-06 重新验证 24/24 通过，第五次陈旧验证再生）
+- ✓ 测试覆盖率常驻门禁：TOTAL 96.22%（1011 项测试），`[tool.coverage.report] fail_under = 90` 落地且无任何豁免行 — Validated in Phase 10（2026-11-06 重新验证 35/35 通过，fresh fingerprint）
+- ✓ 技术债收口：symlink/别名路径经 `get`/`multi-get`/MCP `get_document` 解析到已索引文档（DEBT-PN）；旧版 FTS 触发器迁移 + 检测门控 rebuild 清除陈旧索引（CR-01）；`--xml` 输出恒为良构 XML（CR-02）；全部 26 处 CLI Database 构造点上下文管理器持有、异常路径确定性关闭（WR-01） — Validated in Phase 10.1（2026-11-06 重新验证 16/16 通过，fresh fingerprint）
+
+### Active
+
+（无 — v1.0 全部需求已交付，待 milestone 归档时全面复核）
+
+### Out of Scope
+
+- 多用户/权限系统 — 本地单用户工具，不需要
+- 实时协作/同步 — 超出 qmd 原有范围
+- Web UI — qmd 也没有，仅 CLI + MCP
+- 非 Markdown 格式的复杂解析（如 PDF、Word）—— 先聚焦文本和代码文件
+
+## Context
+
+- 原始项目 qmd 使用 TypeScript / Bun 开发，依赖 `node-llama-cpp` 加载 GGUF 模型进行本地 embedding 和 rerank。
+- 当前 docsift 代码库已完成大部分核心架构（分层设计、Repository 模式、插件化 Chunker / Searcher），但存在多处 stub、bug 和未实现的 CLI 命令。
+- 目标是**功能对等**的 Python 版本，同时改进架构（更好的模块化、可测试性）。
+- 需要保持与 qmd 的 CLI 命令和 MCP 工具接口兼容，方便现有用户迁移。
+
+## Constraints
+
+- **Tech Stack**: Python 3.10+、SQLite（FTS5 + 可选 sqlite-vec）、Click CLI、Pydantic Settings
+- **Local-First**: 默认所有模型本地运行，不依赖外部 API；API 调用仅作为可选配置
+- **Compatibility**: CLI 接口和 MCP Tool Schema 尽量与 qmd 保持一致
+- **Build**: hatchling 构建后端，pytest 测试（常驻 fail_under=90 覆盖率门禁）
+- **Type checking**: ty 为唯一类型检查器（mypy 已于 2026-11-06 退役，`ty check src/sif` 0 诊断）
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 远端维度探测 probe-free，缓存键 `base_url::model_name` | 避免对远端后端产生计费探测请求 | Phase 03 Complete |
+| 上下文规范化：写入时存 `normalize_path` 规范形，读取时双侧重规范化匹配，显式 re-add 时合并旧 verbatim 行；永不批量回填迁移 | realpath 不可逆，SQL 预过滤永远无法匹配 verbatim 旧数据行（05-08/05-09，WR-01/WR-02/CR-02 根因） | Phase 05 Complete |
+| 完全复刻 qmd 功能 | 用户明确要求功能对等 | — Complete (v1.0) |
+| 本地模型 + API 切换双支持 | 提升灵活性和可访问性 | — Complete (v1.0) |
+| 优先修复 bug/stub，再补 CLI，再做 rerank/MCP | 先让现有代码可用，再扩展功能 | Phase 01 Complete |
+| 向量库幂等：re-chunk 事务内 delete-before-insert + 精确 chunk-id 集合跳过，`--force` 才全量重嵌 | G-03-3：重复 embed 不再产生孤儿向量/重复计费 | Phase 03 Complete (UAT 7/7) |
+| embed_cmd 每集合一个事务，失败报告在事务外抛出 | CR-02：单集合失败不回滚已成功集合、退出码如实非零 | Phase 03 Complete (live-verified) |
+| 覆盖率门禁 `fail_under = 90` 最后落地（D-04），禁用 exclude_lines / cov-branch / pragma 豁免 | 门禁不可绕过；覆盖率成为永久回归约束，只增不减 | Phase 10 Complete (96.22%, 1011 tests) |
+| DEBT-PN 查找顺序（OQ2）：精确路径仅规范化形查找；ID/裸文件名保持原始；glob 原始优先、规范化兜底 | realpath 不可逆前提下最小惊讶：别名路径可命中，手迁移相对模式行不破坏 | Phase 10.1 Complete |
+| FTS 迁移检测门控 `VALUES('rebuild')`（OQ1）：仅当检出旧版 direct-DELETE 触发器才重建索引，永不用 needs_rebuild_* 做门 | 修复状态而非仅机制：清除坏触发器时期的孤儿索引项；新库/已迁移库零开销 | Phase 10.1 Complete |
+| CLI Database 生命周期：`with Database(index_path) as db:` 自 init_schema 起持有命令体，嵌套事务块原样保留 | 成功与异常路径都确定性关闭连接（57→13 ResourceWarnings，余量测试侧）；main.py 作用域置于 try/except 内部保证异常先关句柄 | Phase 10.1 Complete |
+| XML 输出净化器 = XML 1.0 Char 产生式补集，先于 `xml_escape`/`quoteattr` 应用 | 转义只管 `<>&'"`，禁用码位归净化器管——两者不可互相替代；`ET.fromstring` 往返测试锁定 | Phase 10.1 Complete |
+| mypy 退役，ty 为唯一类型检查器 | 17 条 ty 诊断清零（断言收窄/Protocol/cast，零行为变化），全部 mypy 残留清除；typing-debt 四批次收官 | v1.0 Complete |
+| 文档内容永不作为 Rich markup 渲染 | get/multi-get 内容 `markup=False` 直出、表头 `escape()`——与 05-10/05-11 同类第三例；回归测试锁定（字面渲染、批次不中断、回退路径同等契约） | v1.0 Complete |
+| docs 局部套件 `--no-cov` | 全局 `addopts` 覆盖率 + `fail_under=90` 使 docs-only 运行必失败（CI 自 Phase 10 起恒红）；Makefile 与 docs.yml 双修 | v1.0 Complete |
+
+## Context（v1.0 shipped 2026-11-07）
+
+- 版本 1.0.0；692 commits（2026-04-14 → 2026-11-07）；src 12.5K 行 / tests 23.1K 行
+- 质量门禁：pytest 1015 passed @ 96.20%（fail_under=90 常驻、零豁免行）、ruff/format/ty 全绿
+- 里程碑收尾时全量文档事实核验：512 条声明 0 失败；四个陈旧验证全部再生（05/06/07/10.1）
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-11-07 after v1.0 milestone（11/11 阶段、68/68 计划全部交付并持新鲜验证；里程碑审计 tech_debt 项全部在收尾前解决：路径规范化、CR-01/02、WR-01、docs CI、ty 清零、get 显示完整性、需求追溯 31/31）*

docsif-1.0.1/.planning/RETROSPECTIVE.md

@@ -0,0 +1,41 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v1.0 — MVP（qmd 功能对等的本地混合搜索引擎）
+
+**Shipped:** 2026-11-07
+**Phases:** 11 | **Plans:** 68 | **Tasks:** 112 | **Quick tasks:** 18
+
+### What Was Built
+- 可信的本地混合搜索引擎：BM25（FTS5 外部内容表 + 触发器同步）+ 向量（sqlite-vec,fail-fast）+ RRF 融合 + Qwen3 重排序/查询扩展，Click CLI 与 MCP 服务器（stdio + Streamable HTTP）双入口
+- 可配置嵌入后端：sentence-transformers / GGUF(llama-cpp) / ModelScope / OpenAI 兼容（默认 Qwen3 系列,维度守护 + 缓存探测）
+- 上下文系统（path/collection/global 三作用域）与路径规范化(别名解析、写入规范化、读取双侧匹配)
+- 质量基线:1015 测试 @ 96.20%,`fail_under=90` 常驻门禁、零豁免行;ty 唯一类型检查器 0 诊断;docs 事实核验 512 声明 0 失败;CI 漂移门禁
+
+### What Worked
+- SDD 分层 + Repository/Protocol/Factory 模式让 11 个阶段可以在几乎无回归的情况下持续插入(05/07/08/09/10/10.1 均为后插)
+- 质量门禁前置:fail_under=90 落地后,后续所有维护(ty 清债、get 修复、文档刷新)都套件全绿通过,零回归逃逸
+- stale-verification 再生机制虽繁琐但可靠:四阶段(05/06/07/10.1)全部翻新,级联失效(06/07 被 10 的修复再度弄陈旧)也被指纹机制如实捕获
+- 代码评审在里程碑收尾抓出 5 个真实 Critical(README 坏命令、生成器管道转义、版本依赖输出、get 内容 markup、表头 markup)——全部实测复现后修复
+
+### What Was Inefficient
+- 显示层 markup 完整性修了三次(05-10/05-11 context 表格、10.1 XML、v1.0 收尾 get 内容+表头)——同类缺陷应一次性全库扫清,而非每阶段撞一次
+- docs CI 自 Phase 10 落地 fail_under 后恒红,直到里程碑收尾才被发现——门禁变更应立即跑一遍受影响的局部套件
+- 版本号散布 6 处无同步机制(评审 WR-03,仍开放)
+- 验证指纹的级联陈旧(修 A 阶段文件弄陈旧 B 阶段)在交叉覆盖集下产生两轮额外再生
+
+### Patterns Established
+- 用户内容永不经 Rich markup 渲染:内容 `markup=False`、表头 `escape()`、机器输出 XML 1.0 净化器——三例同构,已有回归测试锁定
+- 生成器拥有的文档(cli-reference/configuration)只改生成器源 + `make docs-generate`,CI 漂移门禁兜底
+- 测试侧也守资源契约:`contextlib.closing` 包裹裸 sqlite3 连接(全库 0 warning)
+- optional 导入 None 回退是刻意的测试补丁目标:类型收窄在使用点(assert),不重构导入
+
+### Key Lessons
+1. 覆盖率门禁 + 零豁免一旦落地,后续一切维护的回归成本趋近于零——值得在 v1.x 前置
+2. 跨阶段共享文件(显示层、CI、Makefile)的修复要按缺陷类全库横扫,不要按阶段纵切
+3. 里程碑收尾时"审计→resolve 全部→验证全 fresh→归档"的顺序是对的:audit-open 的三项全部真修(CR-03 实测、ResourceWarning 清零、mypy 销账),不留 acknowledge
+
+### Cost Observations
+- 692 commits / 207 天(2026-04-14 → 2026-11-07);src 12.5K 行、tests 23.1K 行(测试:源 ≈ 1.8:1)
+- 里程碑收尾日单会话完成:ty 清债 quick task、文档全量核验、版本 1.0.0、四阶段验证再生、5 个 Critical 修复、归档

docsif-1.0.1/.planning/ROADMAP.md

@@ -0,0 +1,26 @@
+# DocSift Roadmap
+
+## Milestones
+
+- ✅ **v1.0 MVP — qmd 功能对等的本地混合搜索引擎** — Phases 1-10.1 (shipped 2026-11-07)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-10.1) — SHIPPED 2026-11-07</summary>
+
+- [x] Phase 1: Foundation Fix (6/6 plans) — completed 2026-04-14
+- [x] Phase 2: CLI Core Completion (6/6 plans) — completed 2026-04-15
+- [x] Phase 3: Embedding & Vector Search (8/8 plans) — completed 2026-04-16
+- [x] Phase 4: Advanced Search Pipeline (8/8 plans) — completed 2026-04-17
+- [x] Phase 5: Agent Context Experience (12/12 plans) — completed 2026-09-07
+- [x] Phase 6: Documentation Audit & Refresh (10/10 plans) — completed 2026-04-18
+- [x] Phase 7: CLI Claude Skill (2/2 plans) — completed 2026-04-20
+- [x] Phase 8: Project rename DocSift → SIF (8/8 plans) — completed 2026-04-27
+- [x] Phase 9: MCP Server Implementation (6/6 plans) — completed 2026-05-12
+- [x] Phase 10: Raise pytest coverage to 90% (7/7 plans) — completed 2026-11-06
+- [x] Phase 10.1: Tech debt — path normalization + CR-01/CR-02/WR-01 (4/4 plans) — completed 2026-11-06
+
+Full detail: `.planning/milestones/v1.0-ROADMAP.md`
+
+</details>

docsif-1.0.1/.planning/STATE.md

@@ -0,0 +1,204 @@
+---
+gsd_state_version: "1.0"
+milestone: v1.0
+status: Awaiting next milestone
+stopped_at: Phase 10.1 complete — all phases complete
+last_updated: "2026-11-07T03:06:23.417Z"
+last_activity: 2026-11-07
+last_activity_desc: Milestone v1.0 completed and archived
+state_head: c4088cafedd12250e7309ac7eb5768d4e049e138
+progress:
+  total_phases: 11
+  completed_phases: 11
+  total_plans: 68
+  completed_plans: 68
+milestone_name: milestone
+current_phase: 10
+current_phase_name: "Address tech debt: path normalization + review findings CR-01/CR-02/WR-01 (INSERTED)"
+---
+
+# DocSift — Project State
+
+## Project Reference
+
+- **Name:** DocSift
+- **Core Value:** 用户可以在自己的笔记和文档库中，用自然语言快速、准确地找到需要的信息——无论关键词是否匹配。
+- **Current Focus:** Milestone v1.0 complete (all 11 phases; 10.1 verification regenerated 2026-11-06, 16/16, fresh fingerprint) — ready for milestone close/archive.
+- **Tech Stack:** Python 3.10+, SQLite (FTS5 + sqlite-vec), Click, Pydantic, sentence-transformers, llama-cpp-python
+
+## Current Position
+
+Phase: Milestone v1.0 complete
+Plan: —
+Status: Awaiting next milestone
+Last activity: 2026-11-07 - Completed quick task 261107-f5t: Bump version to 1.0.1 (release docsif 1.0.1: typo fixes + parser checksum fix since v1.0)
+
+## Phase History
+
+| Phase | Date Started | Date Completed | Outcome |
+|-------|--------------|----------------|---------|
+| 01–04 — Foundation / CLI / Embedding / Pipeline | 2026-04-14 | 2026-04-17 | All 23 plans passed across four phases; trustworthy core, full CLI surface, configurable embeddings, complete search pipeline. |
+| 05 — Agent Context Experience | 2026-04-18 | 2026-09-07 | 9/9 plans passed incl. 05-08 read-side + 05-09 write/prune normalization gap closures. Qwen3 models default. |
+| 06 — Documentation Audit & Refresh | 2026-04-18 | 2026-04-18 | All 7 plans passed. Auto-generated CLI/config references, docs code block validator (12 tests), Makefile target, GitHub Actions CI workflow. |
+| 07 — CLI Claude Skill | 2026-04-20 | 2026-05-30 | 2/2 plans passed. sif-search and sif-get skills created, symlinked to ~/.claude/skills/. |
+| 08 — Project rename from DocSift to SIF | 2026-04-27 | 2026-04-27 | 8/8 plans passed. Complete rename of package, CLI, env vars, docs, tests, and skills. |
+| 09 — MCP Server Implementation | 2026-05-12 | 2026-05-12 | 6/6 plans passed. Unified MCP package, SearchBackend, 4 tool handlers, stdio/HTTP transports, integration tests. 86% MCP coverage. |
+
+## Performance Metrics
+
+- **Requirements mapped:** 31/31 v1 + 7 DOC requirements
+- **Phases defined:** 10
+- **Tests passing:** 1011 passed, 0 failed (post 10.1 + phase-10 regeneration, fail_under=90 active)
+- **Known blockers:** 0
+
+**Per-Plan Metrics:**
+
+| Plan | Duration | Tasks | Files |
+|------|----------|-------|-------|
+| Phase 05 P08 | 17min | 2 tasks | 9 files |
+| Phase 05 P09 | 12min | 2 tasks | 5 files |
+| Phase 10 P01 | 6min | 2 tasks | 5 files |
+| Phase 10 P02 | 13min | 3 tasks | 3 files |
+| Phase 10 P03 | 19min | 2 tasks | 4 files |
+| Phase 10 P04 | 30min | 3 tasks | 10 files |
+| Phase 10 P05 | 11min | 3 tasks | 12 files |
+| Phase 10 P06 | 20min | 3 tasks | 9 files |
+| Phase 10 P07 | 198s | 2 tasks | 1 files |
+| Phase 10.1 P01 | 13min | 2 tasks | 6 files |
+| Phase 10.1 P02 | 9min | 2 tasks | 2 files |
+| Phase 10.1 P03 | 13min | 3 tasks | 2 files |
+| Phase 10.1 P04 | 16min | 3 tasks | 8 files |
+| Phase 05 P10 | 8min | 3 tasks | 2 files |
+| Phase 05 P11 | 12min | 2 tasks | 2 files |
+| Phase 05 P12 | 8min | 2 tasks | 2 files |
+
+## Accumulated Context
+
+### Decisions
+
+- ✓ D-01: FTS5 synchronization uses SQLite triggers on external content tables
+- ✓ D-02: `sqlite_repository.py` deleted, all access consolidated into `repositories.py`
+- ✓ D-03: Vector search fails fast with `RuntimeError` when sqlite-vec is unavailable
+- ✓ D-04: MCP server uses connection-per-request via `DatabaseConnection`
+- ✓ D-05: Heavy ML libraries remain optional extras in `pyproject.toml`
+- [Phase 03 gap closure]: Vector store idempotency = delete-before-insert in the re-chunk transaction + exact chunk-id-set skip; `--force` re-embeds all (G-03-3)
+- [Phase 03 gap closure]: embed_cmd uses one transaction per collection; failure report raised outside transactions (CR-02)
+- [Phase 03 gap closure]: Remote dimension is probe-free at load; dim cache keyed `base_url::model_name` (WR-02/03-07)
+- [Phase 03 gap closure]: Text egress strictly opt-in — OpenAIEmbedder reachable only via explicit `model_type=openai` (P-1, UAT-verified by egress audit)
+- [Phase 09]: Unified `src/sif/mcp/` package replacing dual legacy/refactored implementations
+- [Phase 09]: ToolHandler ABC pattern with async `handle(params, backend)` signature
+- [Phase 09]: SearchBackend with `asyncio.to_thread()` wrapper over sync sqlite3
+- [Phase 09]: Streamable HTTP (2025-11-25) — single `/mcp` endpoint, POST/GET, session-aware
+- [Phase 09]: CORS defaults non-wildcard: `["http://localhost:3000", "http://127.0.0.1:3000"]`
+- [Phase 02]: Mock index_path.exists on the mock object rather than patching Path.exists in ls.py, since ls.py does not import Path directly
+- [Phase 02-cli-core-completion]: D-01 priority preserved: comma-separated detection takes precedence over glob detection in multi-get
+- [Phase 02-cli-core-completion]: Refactored pull_cmd into helper functions to keep mccabe complexity under 10
+- [Phase 02-cli-core-completion]: Used module-level optional imports with None fallback so patch targets exist for tests
+- [Phase 04]: Mock optional dependencies (`llama_cpp`, `sentence_transformers`) via `sys.modules` injection before import in tests
+- [Phase 04]: Patch `llama_cpp.Llama` and `sentence_transformers.CrossEncoder` at module level, not inside `docsift.search.rerank`
+- [Phase 04]: BM25Searcher tests use MagicMock sqlite3 connections with `fetchall.return_value` for row data
+- [Phase 04]: `include_highlights=False` required in basic BM25Searcher tests to avoid extra mock DB calls
+- [Phase 05-gap-closure]: Used callable default for `--index` option (Click supports callable defaults) to allow dynamic resolution via Settings
+- [Phase 05-gap-closure]: Normalized paths with `os.path.realpath()` in all three searchers due to macOS `/tmp` → `/private/tmp` resolution
+- [Phase 05-model-update]: Default embedding model switched from `all-MiniLM-L6-v2` (384 dim) to `Qwen/Qwen3-Embedding-0.6B` (1024 dim)
+- [Phase 05-model-update]: Default reranker switched from `cross-encoder/ms-marco-MiniLM-L-6-v2` to `Qwen/Qwen3-Reranker-0.6B` (transformers backend)
+- [Phase 05-model-update]: Added `modelscope` model_type to `EmbeddingConfig.ModelType` and `_create_modelscope_model` to factory
+- [Phase 05-model-update]: Added `Qwen3Reranker` class for transformers-based reranking with yes/no logits scoring
+- [Phase 06-discuss]: CLI reference auto-generated via Python script traversing Click command tree (`scripts/generate_cli_ref.py`)
+- [Phase 06-discuss]: Code block validation: fence-tag based classification (bash → execute, json/python → syntax check, text → skip)
+- [Phase 06-discuss]: Blacklist for long-running commands (mcp start, pip install, etc.) in docs tests
+- [Phase 06-discuss]: Docs tests use pytest fixture with temp DB + minimal test data, CliRunner primary + subprocess secondary
+- [Phase 06-discuss]: Technical docs validated via AST parsing: extract public API from code, verify against documented names
+- [Phase 06-discuss]: Architecture diagram strategy: keep ASCII in README (manual), generate Mermaid in architecture.md (scripted)
+- [Phase 09]: [Phase 03-07]: OpenAI-compatible endpoints addressed via OpenAI(api_key, base_url) — SDK appends /embeddings; api_base=None uses SDK default (D-04)
+- [Phase 09]: [Phase 03-07]: Dimension source of truth is the API — one minimal probe cached per model to openai_dim_cache.json with 7-day TTL; corrupt/missing cache degrades to probe, never crashes load (D-05)
+- [Phase 09]: [Phase 03-07]: Configured embedding_dim disagreeing with API-detected dimension fails fast at load naming both values + SIF_EMBEDDING_DIM (extends D-09 fail-fast philosophy)
+- [Phase 09]: [Phase 03-07]: api_key passes only to the OpenAI client constructor — never logged, interpolated, or embedded in exceptions (threat T-03-01)
+- [Phase 09]: [Phase 03-07]: Factory honest signatures -> Embedder / **kwargs: Any completed the refactor plan 03-02 promised (03-REVIEW WR-01/WR-02)
+- [Phase 04 UAT]: Shared stem-tolerant term matcher (src/sif/search/term_match.py): word-boundary + light-stem for ASCII, substring + per-char fallback for CJK — used by both SmartSnippetExtractor and BM25 highlights
+- [Phase 04 UAT]: Snippets are line-aware: windows center on the matched line (heading/table row/code line), structural lines never anchor
+- [Phase 04 UAT]: Reranker model dirs resolve by config qualification (config.json with model_type, root before aux subdirs like Qwen3-Reranker's 1_LogitScore)
+- [Phase 04 UAT]: LlamaCppEmbedder owns generation (create_completion) + shape-aware embed (unwrap list-of-embeddings, mean-pool token-level); HyDE reachable end-to-end
+- [Phase 04 UAT deferred]: embedding cache bucket key omits model_path — switching GGUF files under one model_name cross-pollutes cache; include path identity in _cache_model_id
+- [Phase 03]: [Phase 03-08] Idempotent embed via delete-before-insert: chunk_repo.delete_by_document -> VectorSearcher.delete_embeddings_by_document -> add_embeddings_batch in one transaction; probe-free dimension from get_model_info() (isinstance-guarded probe fallback)
+- [Phase 03]: [Phase 03-08] --force honored via exact chunk-id-set equality: _needs_embedding(live, embedded, force) module-level helper; default run skips complete documents with zero embed calls, partial/orphaned states self-heal
+- [Phase 03]: [Phase 03-08] VectorSearcher construction failure in embed_cmd surfaces as click.ClickException (D-03 fail-fast extended to the embed path; never swallowed into failed_collections)
+- [Phase 04]: [Phase 04-06]: Pipeline snippet content fetch is transient — fetched text feeds extraction only, never written into SearchResult.content (CLI-07 --full contract preserved)
+- [Phase 04]: [Phase 04-06]: Snippet table cells wrapped in rich.markup.escape so document bracket sequences render literally (threat T-04-06-02 mitigated)
+- [Phase 04]: [Phase 04-06]: _display_snippet guards snippet and highlights with getattr, falling back to the first BM25 highlight when no snippet exists
+- [Phase 05]: 05-08: read-side re-normalization replaces the raw-string SQL pre-filter in context attachment — one constant-SQL batch query of all path contexts, both sides normalized in Python via normalize_path (realpath is not invertible, so no SQL path pre-filter can ever match a verbatim legacy row; D-06 batch shape preserved)
+- [Phase 05]: 05-08: legacy verbatim context rows match on read — no contexts-table backfill migration; context_description is set only on match so RRF/rerank-carried descriptions are never clobbered; ORDER BY updated_at gives deterministic newest-wins for duplicate-normalizing targets
+- [Phase 05]: 05-09: context add path stores normalize_path(target) canonical form with dual-form upsert — legacy verbatim rows are re-pointed via new ContextRepository.update_target() on explicit re-add; no bulk backfill migration ever runs (re-normalize-on-read + merge-on-re-add closes WR-02/CTX-01)
+- [Phase 05]: 05-09: delete_orphaned_paths compares normalize_path on both sides in a Python set — SQL cannot call realpath so the raw-string NOT IN comparison is gone entirely; count semantics and D-12/D-13 explicit-command contract unchanged (closes CR-02/CTX-02)
+- [Phase 10]: 10-01: Applied D-01 exactly, deleting the approved dead-code cluster while preserving live CLI imports; measured post-deletion coverage at 81.48% (5320 statements, 985 missed).
+- [Phase 10]: 10-01: Kept pyproject.toml free of fail_under and coverage exclusions under D-04; final gate remains reserved for plan 10-07.
+- [Phase 10]: 10-02: D-06 isolated, both-order, and full-suite probes were green; no speculative repair or production change was made.
+- [Phase 10]: 10-02: Real-temp-DB CLI tests raised TOTAL coverage from 81.48% to 85.34%; collection 99.15%, main 86.99%, get 100%.
+- [Phase 10]: 10-03: Used real torch tensor math with constructor/downloader mocks for deterministic Qwen3 yes/no scoring; scoped ML module injection under D-07.
+- [Phase 10]: 10-03: Escaped XML query attributes and result fields so machine output strict-parses markup-sensitive content; search command reached 99.44% coverage.
+- [Phase 10]: 10-04: Real SQLite exposed and repaired stale external-content FTS delete triggers, lazy stats initialization, and multi-statement migration execution; repositories/schema/database/cache reached 100% and migrations 92%.
+- [Phase 10]: 10-05: Used real domain entities with repository Protocol doubles and scoped ModelScope/process-state isolation; all seven target files reached 100%.
+- [Phase 10]: 10-05: Behavior tests exposed and repaired custom logging formatter and indeterminate Rich progress defects; TOTAL coverage reached 93.48%.
+- [Phase 10]: 10-06: Real-file Unicode parsing, exact code-point chunk boundaries, and isolated MCP protocol tests raised TOTAL coverage to 96.16%.
+- [Phase 10]: 10-06: Behavior tests repaired fixed-size chunker forward progress and post-insertion MCP session LRU bounds.
+- [Phase 10]: 10-07: Zero long-tail tests required; Wave-2 combined TOTAL already 96.16% (>=90%). D-05 did not trigger; no candidate test file was modified.
+- [Phase 10]: 10-07: Landed [tool.coverage.report] fail_under=90 LAST per D-04/Pattern 6; no exclude_lines/exclude_also/--cov-branch, no business-logic pragma. Canonical suite green under active gate (958 passed, 96.16%).
+- [Phase 10.1]: DEBT-PN lookup order (OQ2): normalized-only for exact-path lookups; ID-first and bare-filename stay raw; globs raw-first-then-normalized
+- [Phase 10.1]: get/multi-get own Database lifecycle via with Database(index_path) (WR-01, 2 sites); nested with db.connection kept for commit sequencing
+- [Phase 10.1]: DEBT-PN-DOC lands in docstrings + make docs-generate output + sif-get skill note; no separate prose page (OQ3/A5)
+- [Phase 10.1]: 10.1-02: CR-01 closed via generalized _fts_trigger_is_legacy detector (direct-UPDATE FND-06 + direct-DELETE forms) migrating all four FTS sync triggers on create_all()
+- [Phase 10.1]: 10.1-02 OQ1: detection-gated FTS 'rebuild' purges entries orphaned by past broken deletes; gate is legacy detection alone, never needs_rebuild_*; fresh/migrated DBs pay nothing
+- [Phase 10.1]: 10.1-02: migration logic extracted to _drop_legacy_fts_triggers returning legacy-delete booleans (ruff C901 mccabe-10 cap)
+- [Phase 10.1]: 10.1-03: CR-02 closed — sanitizer is the XML 1.0 Char production complement transliterated (strip #x00-#x08/#x0B/#x0C/#x0E-#x1F/surrogates/#xFFFE-#xFFFF; keep tab/LF/CR; never strip #x7F-#x9F), applied BEFORE xml_escape/quoteattr which keep owning <>&'"
+- [Phase 10.1]: 10.1-03: WR-01 search.py — with Database(index_path) covers each command body from init_schema onward; all nine nested with db.connection: transaction blocks preserved
+- [Phase 10.1]: 10.1-03: closure doubles patch the import SOURCE for function-local imports — vsearch_cmd binds Database at call time, so its TrackingDatabase patches sif.database.database.Database; and real-Database doubles need settings.embedding_dim as a real int (init_schema resolves get_settings lazily per call)
+- [Phase 10.1]: 10.1-04: WR-01 closed for six CLI modules (21 sites) — with Database(index_path) ownership wraps each command body from init_schema onward; nested with db.connection/transaction blocks preserved verbatim (57→13 ResourceWarnings, remainder test-side)
+- [Phase 10.1]: 10.1-04: main.py ownership scopes sit INSIDE the existing try/except — exceptions close the Database via __exit__ before the ClickException handler runs
+- [Phase 10.1]: 10.1-04: lifecycle harness asserts non-vacuous closure (every test asserts >=1 TrackingDatabase captured) and covers index update (not index status, which delegates to main's status_cmd and would not exercise index.py's scope)
+- [Phase 05]: 05-10: truth-21 duplicate collapse centralized in _collapse_duplicate_path_rows — shared by exact-match branch, normalized branch, and upsert-hit path; exact-match branch gains the same landed-guard (update_target True before any deletion) as the normalized branch (T-05-16)
+- [Phase 05]: 05-10: CR-02 closed — context list wraps all three Rich table cells in rich.markup.escape AFTER truncation so the 50-char display cap applies to raw text; display-only, stored bytes untouched (mirrors 04-06 snippet precedent)
+- [Phase 05]: 05-11: CR-01 closed — rich.markup.escape at all 12 display sites (3 titles, 3 title cells, 3 collection cells, 3 content appends, 2 explain prints); display-layer only, machine outputs byte-unchanged
+- [Phase 05]: 05-11: escape-after-truncation ordering (truncate raw text, then escape the whole displayed expression incl. ellipsis) — mirrors the 05-10 context-list precedent; tests renamed to *_renders_markup_literally so -k markup_literal selects all five
+- [Phase 05]: 05-12: CR-03 closed — rich.markup.escape wraps display_target at both context add confirmation prints and context_id at the remove print; display-layer only, print placement inside the transaction and stored bytes unchanged (mirrors 05-10/05-11 precedents; 05-10-P3 now HOLDS at all three sites) — Bracket-named targets were permanently unaddable because the MarkupError from the confirmation print rolled back the open transaction; escaping removes the raising path while both write branches stay inside with db.transaction()
+
+### Roadmap Evolution
+
+- Later-added phases: 07 Claude skills (2026-04-20), 08 rename DocSift→SIF (2026-04-27), 09 MCP server (2026-05-08)
+- Phase 10 added: Raise pytest coverage to 90% (2026-11-05; baseline 78% / 5587 stmts / 1220 missed — lowest: cli/config.py 0%, formatters 29%, collection 44%)
+- Phase 10.1 inserted after Phase 10: Address tech debt: path normalization + review findings CR-01/CR-02/WR-01 (URGENT)
+
+### TODOs
+
+- [x] Plan Phase 06 documentation audit and refresh — 7 plans created and verified
+- [x] Phase 7: CLI Claude Skill — sif-search and sif-get skills created, symlinked, and committed
+- [ ] (Backlog) Phase 8: LLM-based query expansion — model tested (Qwen3.5-2B), awaiting v1.0 ship
+- [ ] (Backlog) Phase 10 regen code review: 10 warnings open (WR-01..WR-10, 0 critical) — ledger in 10-REVIEW-DISPOSITION.md; candidates for a future debt phase (precedent: 10.1 arose from 10's original review)
+- [ ] (Backlog) Phase 10.1 regen code review: 4 info findings open (IN-10..IN-13: stale test-count claims in docs/testing.md, invalid bare `sif search` in DESIGN.md, discarded `_collapse_duplicate_path_rows` return, duplicated test helpers) — ledger in 10.1-REVIEW-DISPOSITION.md
+
+### Blockers
+
+- None
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 261107-cdh | Fix README.md install typo: docdocsif -> docsif in extras install command | 2026-11-07 | ef8edc2 | [261107-cdh-fix-readme-md-install-typo-docdocsif-doc](./quick/261107-cdh-fix-readme-md-install-typo-docdocsif-doc/) |
+| 261107-f5t | Bump version to 1.0.1 (release docsif 1.0.1: typo fixes + parser checksum fix since v1.0) | 2026-11-07 | c4088ca | [261107-f5t-bump-version-to-1-0-1-release-docsif-1-0](./quick/261107-f5t-bump-version-to-1-0-1-release-docsif-1-0/) |
+
+### Overrides
+
+- [2026-09-03] Phase 03 decision-coverage gate override (user-approved): D-06/D-07/D-08/D-10 accepted as covered-by-legacy — implemented and behaviorally verified per 03-VERIFICATION.md; legacy plans 03-01…03-06 predate D-ID citation and are read-only in gap-closure mode. Verify-phase should re-surface this.
+
+## Session Continuity
+
+**Last session:** 2026-11-07 (milestone v1.0 close)
+**Stopped at:** v1.0 shipped and archived — verified_closeout, zero overrides; 11/11 phases fresh-verified, 31/31 requirements, suite 1015 @ 96.20%
+**Resume file:** None
+
+- **Last action:** /gsd-complete-milestone v1.0 — four stale verifications regenerated (05/06/07/10.1) with 5 review criticals fixed along the way; archives at .planning/milestones/v1.0-*; tag v1.0.
+- **Next expected action:** `/gsd-new-milestone` — v1.0 已归档，规划下一版本。
+
+## Operator Next Steps
+
+- Start the next milestone with /gsd-new-milestone