pactkit 4.4.0__tar.gz → 4.4.1__tar.gz

{pactkit-4.4.0 → pactkit-4.4.1}/.secrets.baseline

@@ -213,14 +213,22 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "8e796005c96e92c749dcf97c59e13696fd054e00",
+        "hashed_secret": "6a372f78ae760b38ce439c7cedd67a2fc1fda7f7",
         "is_verified": false,
         "line_number": 7
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "b5c0472ae7ea18a660c41a27b8b67d2e5ae16ea3",
+        "hashed_secret": "86c73e09643e122fee6f5f7723b46bd6f236170f",
+        "is_verified": false,
+        "line_number": 8
+      },
+
+      {
+        "type": "Hex High Entropy String",
+        "filename": "tests/fixtures/host_artifact_paths.json",
+        "hashed_secret": "d46f0536967f523a1033adc6b2bf14b61e7b33f7",
         "is_verified": false,
         "line_number": 9
       },
@@ -759,7 +767,7 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "229137663ca7a52a4354bf2f2eb3726cb8953cc9",
+        "hashed_secret": "e811dccd70a0a16780cfc1ec4917ea21f72ad7e2",
         "is_verified": false,
         "line_number": 386
       },
@@ -969,7 +977,7 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
-        "hashed_secret": "91a0aa711b49a52809fea5824ceaa0f1ea4a40b5",
+        "hashed_secret": "3d49aa7c5ad73d0ac55dc6a907899cf3fa23b796",
         "is_verified": false,
         "line_number": 562
       },
@@ -1099,7 +1107,14 @@
         "is_verified": false,
         "line_number": 593
       },
-      {
+            {
+        "type": "Hex High Entropy String",
+        "filename": "tests/fixtures/host_artifact_paths.json",
+        "hashed_secret": "336de6b749ee5ec69dc9358c32d8ba15b86eaefa",
+        "is_verified": false,
+        "line_number": 649
+      },
+{
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_artifact_paths.json",
         "hashed_secret": "b1949130fb35124304c0f240b13f11e0ae63f390",
@@ -1272,14 +1287,14 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/classic.json",
-        "hashed_secret": "8371de7fa126a6f62d33ff47fdaa97a6c3bfcc0f",
+        "hashed_secret": "abcffe98a3588f59549e53483200cc96554c69fc",
         "is_verified": false,
         "line_number": 92
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/classic.json",
-        "hashed_secret": "4dcffac995fb027b5455a26d17ab04362018be7d",
+        "hashed_secret": "35980425ab94e5bcb95b8fadf4c45996fdd37ce6",
         "is_verified": false,
         "line_number": 93
       },
@@ -1876,14 +1891,14 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/codex.json",
-        "hashed_secret": "d648b031f1fb581d282fe80da2a9419d5f69db21",
+        "hashed_secret": "802459e44393d5a0d4cdf39cdd5d979a6cda210e",
         "is_verified": false,
         "line_number": 78
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/codex.json",
-        "hashed_secret": "01be8019c35651b6bc2a56961485ed6cf98219a9",
+        "hashed_secret": "e702416aa196b7467e61f1e9da2e4f27c881f100",
         "is_verified": false,
         "line_number": 79
       },
@@ -2326,14 +2341,14 @@
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/opencode.json",
-        "hashed_secret": "b5e1bd1f91ff93ef610a68b5e25fae2cf4cbd17c",
+        "hashed_secret": "1249a0f63296de9ea419044a8e598f37c72266a9",
         "is_verified": false,
         "line_number": 90
       },
       {
         "type": "Hex High Entropy String",
         "filename": "tests/fixtures/host_prompt_snapshots/opencode.json",
-        "hashed_secret": "3b2893c3c9616424c920a035c1b0b085c7ec9707",
+        "hashed_secret": "948711067721f75761bdede8ad96a4f3d56064f3",
         "is_verified": false,
         "line_number": 91
       },
@@ -3040,4 +3055,4 @@
     ]
   },
   "generated_at": "2026-11-06T06:48:50Z"
-}
+}

{pactkit-4.4.0 → pactkit-4.4.1}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [4.4.1] - 2026-11-13
+
+**写入可信边界补丁：配置同步不再静默、文件权限保留、查询截断可机器识别、`-C` 上下文统一、死代码索引状态显式。**
+
+### Migration
+
+行为变化，无需修改调用方：
+
+- `atomic_write` 覆盖既有文件时保留原 mode；新建文件仍遵循 umask。依赖固定 `0644` 重建的脚本需显式 `chmod`。
+- `sync_project_config` 新增 `source-tree`、`locked` 状态；命令前的配置自动同步失败现在会向 stderr 告警。
+- `garden --dead-code --write` 在 CodeGraph 索引非 `ok` 时拒绝写入并以非零退出。
+- `query --explore/--context/--node` 文本结果新增 `text_length` / `text_truncated`；超过预算时 `ProviderDecision.truncated` 为 true。
+- `-C` 下的 `generate-id` / `marker` / `query` 统一读取目标项目根与配置。
+
+### Fixed
+
+- 配置自动同步不再把 `0600` 的 `pactkit.yaml` 改成 `0644`：`atomic_write` 在覆盖既有文件时保留原 mode，并在替换前 `fsync`。
+- 源码树即使已带落后版本戳也不会被自动同步写入；`stamp_config()` 显式路径行为不变。
+- quoted `pactkit_version` 原位替换，不再追加第二个 YAML key；重复键与 flow mapping 返回 `refused` 且文件逐字节不变。
+- 配置同步的读-改-写过程加排他锁，超时返回 `locked`，并发更新不再被旧快照覆盖。
+- `query` 的文本结果超过 4000 字符时标记 `truncated`，人类输出报告字符数而非包装行数。
+- `-C` 指定项目时 `generate-id` / `marker` / `query` 使用目标项目根与配置，不再读取当前目录。
+- `garden --dead-code` 区分索引 `ok` / `unavailable` / `invalid` / `stale` / `unknown`；非 `ok` 不写 triage，未完成外部验证的 internal candidate 显式标注。
+
 ## [4.4.0] - 2026-11-06
 
 **项目内默认工作流、配置随版本自动同步、CLI 分发表重构与死代码 triage。**

{pactkit-4.4.0 → pactkit-4.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 4.4.0
+Version: 4.4.1
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit-public

pactkit-4.4.1/docs/architecture/governance/lessons/LESSON-20261113064541-4c36d97592.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20261113064541-4c36d97592
+date: '2026-11-13'
+story_id: STORY-slim-202611138701d652f238
+context: src/pactkit/config_sync.py:sync_project_config
+tags: []
+---
+
+src/pactkit/utils.py:atomic_write 必须先保留既有目标 mode 再 os.replace；src/pactkit/config_sync.py:sync_project_config 的源码树守卫必须放在入口，而不是只放在 _stamp_legacy 分支。

{pactkit-4.4.0 → pactkit-4.4.1}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 7968+ tests must pass before any commit to `main`.
+1. All 8067+ tests must pass before any commit to `main`.
 2. Specs (`docs/specs/`) are the source of truth — code conforms to specs, not the reverse.
 3. CLI entry point is `pactkit` via `src/pactkit/cli.py:main`.
 4. No runtime dependencies beyond `pyyaml`.

{pactkit-4.4.0 → pactkit-4.4.1}/docs/architecture/governance/ut-inventory.md

@@ -194,7 +194,7 @@
     },
     {
       "module": "src/pactkit/cli.py",
-      "test_files": 19,
+      "test_files": 20,
       "contracts": [
         "cli-root-help-surface",
         "cli-subcommand-help-surface"
@@ -221,7 +221,7 @@
     },
     {
       "module": "src/pactkit/commands/handlers.py",
-      "test_files": 1,
+      "test_files": 2,
       "contracts": [],
       "is_gate": false
     },
@@ -247,7 +247,7 @@
     },
     {
       "module": "src/pactkit/config_sync.py",
-      "test_files": 1,
+      "test_files": 2,
       "contracts": [],
       "is_gate": false
     },
@@ -307,7 +307,7 @@
     },
     {
       "module": "src/pactkit/dead_code.py",
-      "test_files": 1,
+      "test_files": 2,
       "contracts": [],
       "is_gate": false
     },
@@ -455,7 +455,7 @@
     },
     {
       "module": "src/pactkit/graph_query.py",
-      "test_files": 11,
+      "test_files": 12,
       "contracts": [],
       "is_gate": false
     },
@@ -897,7 +897,7 @@
     },
     {
       "module": "src/pactkit/utils.py",
-      "test_files": 13,
+      "test_files": 14,
       "contracts": [],
       "is_gate": false
     },

{pactkit-4.4.0 → pactkit-4.4.1}/docs/product/sprint_board.md

@@ -1657,3 +1657,16 @@
 - [x] DSH 部署文本与插件上下文对齐
 - [x] 冻结基线重录与回归测试
 - [x] 跨仓提交与部署验证
+
+### [STORY-slim-202611138701d652f238] 配置写入与查询/死代码输出的可信边界
+> Spec: docs/specs/STORY-slim-202611138701d652f238.md
+
+- [x] atomic_write 保留目标 mode
+- [x] config_sync 源码树守卫/锁/结构化 stamp
+- [x] graph_query 文本预算与 truncated
+- [x] handlers -C 项目上下文统一
+- [x] dead_code index_status 与 external_verified
+- [x] garden --dead-code 写入守卫
+- [x] AC1–AC13 回归测试
+- [x] Check 修复：R7 provider health 与索引状态
+- [x] Check 修复：CLI 同步告警与 board 投影

pactkit-4.4.1/docs/product/stories/STORY-slim-202611138701d652f238.yaml

@@ -0,0 +1,36 @@
+schema_version: 1
+id: STORY-slim-202611138701d652f238
+title: 配置写入与查询/死代码输出的可信边界
+spec_path: docs/specs/STORY-slim-202611138701d652f238.md
+status: archived
+tasks:
+- id: task-eba323fcd8
+  title: atomic_write 保留目标 mode
+  completed: true
+- id: task-db2eb71449
+  title: config_sync 源码树守卫/锁/结构化 stamp
+  completed: true
+- id: task-1923212874
+  title: graph_query 文本预算与 truncated
+  completed: true
+- id: task-12196e662b
+  title: handlers -C 项目上下文统一
+  completed: true
+- id: task-2bdd5fa88e
+  title: dead_code index_status 与 external_verified
+  completed: true
+- id: task-936b6ef60d
+  title: garden --dead-code 写入守卫
+  completed: true
+- id: task-b857254c04
+  title: AC1–AC13 回归测试
+  completed: true
+- id: task-eb8f31fde7
+  title: Check 修复：R7 provider health 与索引状态
+  completed: true
+- id: task-57b4a8011d
+  title: Check 修复：CLI 同步告警与 board 投影
+  completed: true
+created_at: '2026-11-13T03:16:14+00:00'
+updated_at: '2026-11-13T06:46:40+00:00'
+archived_at: '2026-11-13T06:46:40+00:00'

pactkit-4.4.1/docs/specs/STORY-slim-202611138701d652f238.md

@@ -0,0 +1,270 @@
+# STORY-slim-202611138701d652f238: 配置写入与查询/死代码输出的可信边界
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-202611138701d652f238 |
+| Type | Story |
+| Status | Done |
+| Priority | P1 |
+| Release | 4.4.1 |
+
+## Background
+
+4.4.0 引入了两条新的执行路径：命令入口的**项目配置自动同步**
+（STORY-slim-202611063f2bf6369619）与 CodeGraph 的 **explore/context/node 文本查询**。
+对 4.4.0 主线（`eade0d4`）做风险导向审查后，确认了 7 个边界缺陷，其中两个已独立复现：
+
+- `atomic_write()` 用默认 mode 创建临时文件后 `os.replace`，在 `umask 022` 下把
+  `0600` 的 `pactkit.yaml` 变成 `0644`（复现：0600 → 0644）。
+- `sync_project_config()` 的版本戳替换只匹配行首无引号的 `pactkit_version:`；
+  写成合法 YAML `"pactkit_version": "4.3.0"` 时会**追加第二个键**，PyYAML 取后者，
+  现有校验看不出来（复现：同一文件出现 4.3.0 与 4.4.0 两个键）。
+- CodeGraph 文本查询的结果在 `_clean()` 里被 `[:4000]` 静默截断，
+  但 `ProviderDecision.truncated` 只对行式 kind 置位，文本 kind 仍报 `False`。
+- `sync_project_config()` 的源码树守卫只在 legacy 分支 `_stamp_legacy()` 内；
+  配置一旦带上 stamp，正常同步路径会再次写 PactKit 自己的 checkout。
+  规划时工作区的 `pactkit.yaml` 恰好带有未提交的 4.4.0 stamp，这使
+  `tests/unit/test_config_auto_sync.py::test_pactkit_source_tree_is_never_auto_written`
+  断言 `current == source-tree` 失败——失败的是守卫位置，不是测试。
+- 自动同步是跨进程的读-改-写，只有 `os.replace` 的原子性，没有事务隔离。
+- `-C` 指定项目时，`h_query` / `h_generate_id` / `h_marker` 仍从当前目录取配置、
+  developer 或源文件根。
+- `garden --dead-code` 在数据库缺失或 SQLite 读取失败时把 `_zero_inbound()` 折叠成
+  `[]`，上层照常生成全零报告；外部适配器不可用时，未识别符号仍落成
+  `internal-candidate`，没有体现外部引用验证不完整。
+
+这些缺陷共享同一个语义错误：**验证失败、证据不完整、结果确实为空，被折叠成了
+同一个成功值**。ADR-0009 要求“测量到的证据”与“声明的证据”可区分；本 Story 把
+同一原则落到配置写入、查询输出与死代码分类三处，不新增功能。
+
+权限策略采用**保留既有目标 mode**：同步路径上的配置文件必然已存在，保留原 mode
+即可恢复 0600 的保密性；新建文件维持当前行为，避免改变 69 处 `atomic_write`
+调用方的语义。
+
+## Requirements
+
+### R1: `atomic_write` 保留既有目标权限 (MUST)
+
+目标文件已存在时，替换完成后的权限位 MUST 与替换前一致（包括 `0600`）。目标
+不存在时，创建行为 MUST 与当前实现一致，不因本 Story 收紧其他调用方。实现 MUST
+继续是唯一共享的 `atomic_write()`，不得在 `config_sync` 内复制写入逻辑；写入失败
+时 MUST 清理本次创建的临时文件（保持现有行为）。
+
+### R2: 源码树守卫覆盖所有自动同步路径 (MUST)
+
+`sync_project_config(root)` MUST 在读取版本、比较版本之前检查 `_is_source_tree(root)`；
+命中时 MUST 返回 `source-tree`，且 MUST NOT 读取或写入 `pactkit.yaml`。该行为 MUST
+与配置是否带 `pactkit_version` 无关：带 stamp 的源码树同样不得进入 `current` 或
+`synced` 路径。显式写入路径（`stamp_config()`，由 `init`/`update` 调用）不在本禁令
+内，但其 docstring MUST 说明这条边界。
+
+### R3: 版本戳替换基于 YAML 结构，禁止重复键 (MUST)
+
+定位顶层 `pactkit_version` MUST 使用 YAML 解析（`yaml.compose()` 的节点位置或等价
+的结构化定位），MUST NOT 只依赖“行首无引号”的正则。修改 MUST 只替换该键自身的
+行/片段，保留其余字节（键顺序、注释、空行）。以下情况 MUST 返回 `refused` 且文件
+逐字节不变，MUST NOT 追加第二个 `pactkit_version`：解析后存在该键但无法唯一定位
+（如 flow mapping）；顶层已存在重复的 `pactkit_version`。写入前 MUST 重新解析并
+断言顶层该键恰好一个、值等于安装版本。
+
+### R4: 同步读-改-写串行化 (MUST)
+
+`sync_project_config()` MUST 在读取文件前获取排他 advisory lock，并持有到
+`os.replace` 完成。锁实现 MUST 同时覆盖 POSIX（`fcntl.flock`）与 Windows
+（`msvcrt.locking`），锁文件放在 `.pactkit/locks/`。在限定时间内拿不到锁时 MUST
+返回 `locked` 且不写文件，MUST NOT 静默继续。两个并发的同步 MUST 不丢失任何一方
+的补齐键：后到者必须读到先到者写入后的内容。
+
+### R5: 文本查询截断必须机器可辨 (MUST)
+
+`_clean()` 的职责 MUST 拆成“清洗”（ANSI、home 路径）与“预算”两部分。`explore` /
+`context` / `node` 的文本结果超过 4000 字符时：结果 MUST 携带原始长度（或等价
+字段）；`ProviderDecision.truncated` MUST 为 `true`；`warnings` MUST 含
+`result_budget_hit:text:<原始长度>`。`--json`、`--explain` 与人类输出 MUST 都能看出
+截断；人类输出 MUST 说明是字符预算，MUST NOT 写成 “showing N rows”。未超预算时
+文本 MUST 完整返回，`truncated` MUST 保持 `false`。文本 kind 的 `result_count` 语义
+（包装行数）不在本 Story 改动，机器区分由 `truncated` 承担。
+
+### R6: `-C` 项目上下文在三个 handler 一致 (MUST)
+
+`h_query` MUST 用 `load_effective_config(ctx.project_root)` 取 `graph_provider`，
+MUST NOT 用无参 `load_config()` 从当前目录发现配置。`h_generate_id` MUST 从
+`load_effective_config(ctx.project_root)` 取 `developer`，`specs_dir` 继续取
+`ctx.project_root`。`h_marker` MUST 用 `ctx.project_root` 作为 `source_for()` 的根。
+三个命令在 `cd A && pactkit -C B ...` 下 MUST 以 B 为准，即使 A 也有
+`pactkit.yaml`。
+
+### R7: 死代码索引状态与外部验证标志 (MUST)
+
+`Report` MUST 暴露 `index_status`，取值 `ok` / `unavailable` / `invalid` / `stale` /
+`unknown`，并可带 `index_detail`。数据库不存在 → `unavailable`；SQLite 打开或查询
+失败 → `invalid`；可读且 provider health 报 fresh → `ok`；provider 可用但 health
+报不新鲜 → `stale`；可读但无法获得 health 结论 → `unknown`。`render()` MUST 在
+非 `ok` 时明确写出“这不是零候选结果”及原因，MUST NOT 把它渲染成普通全零报告。
+`--write` 仅在 `index_status == ok` 时允许写；其余状态 MUST 以非零退出码拒绝，
+且既有 `dead-code-triage.md` MUST 逐字节不变。
+
+`Candidate` MUST 增加 `external_verified: bool`。当任意外部适配器状态为
+`unavailable` 且 verdict 为 `internal-candidate` 时，该字段 MUST 为 `false`；
+`deletable()` MUST 排除这些候选；`render()` MUST 标出“外部引用验证不完整”。
+
+## Acceptance Criteria
+
+### AC1: 已有文件权限保持 (R1)
+
+- **Given** 一个权限为 `0600` 的 `pactkit.yaml`
+- **When** 调用 `atomic_write()` 写入新内容
+- **Then** 文件权限仍为 `0600`
+- **And** 在 `umask 022` 下新建目标文件时，权限与本次改动前一致（`0644`）
+
+### AC2: 源码树永不被自动写 (R2)
+
+- **Given** PactKit 源码树，其 `pactkit.yaml` 已带 `pactkit_version: "4.4.0"`
+- **When** 调用 `sync_project_config(repo_root)`
+- **Then** 返回 `source-tree`，文件内容与 mtime 均不变
+- **And** 无 stamp 的 legacy 源码树同样返回 `source-tree`
+
+### AC3: 带引号的版本戳被原位替换 (R3)
+
+- **Given** 配置含 `"pactkit_version": "4.3.0"`、`stack: python` 与行尾注释
+- **When** 自动同步到 4.4.0
+- **Then** 文件中顶层 `pactkit_version` 恰好一个，值为 `"4.4.0"`
+- **And** `stack` 与注释逐字节保留
+
+### AC4: 无法唯一定位时拒绝写入 (R3)
+
+- **Given** 配置使用 flow mapping，或顶层已存在两个 `pactkit_version`
+- **When** 自动同步
+- **Then** 返回 `refused`，文件逐字节不变，且不新增第三个键
+
+### AC5: 并发同步不丢更新 (R4)
+
+- **Given** 进程 A 持有同步锁并暂停在写前
+- **When** 进程 B 在超时内调用 `sync_project_config()`
+- **Then** B 返回 `locked`，文件不变
+- **And** 串行执行两次补齐不同缺失键的同步后，两个键都存在于最终文件
+
+### AC6: 文本查询超预算时可见 (R5)
+
+- **Given** CodeGraph 对 `explore` 返回 5000 字符
+- **When** 执行查询
+- **Then** 返回文本为 4000 字符，`decision.truncated` 为 `true`
+- **And** `warnings` 含 `result_budget_hit:text:5000`；人类输出说明字符预算
+- **And** `--json` 中同样可见 `truncated: true`
+
+### AC7: 文本查询未超预算时不变 (R5)
+
+- **Given** 返回 1000 字符
+- **When** 执行查询
+- **Then** 文本完整、`truncated` 为 `false`，且无 `result_budget_hit` 警告
+
+### AC8: `-C` 目标项目优先于当前目录 (R6)
+
+- **Given** 当前目录 A 与目标目录 B 各有不同的 `graph_provider`、`developer` 与源文件
+- **When** 在 A 中执行 `pactkit -C B query --explore ...`、`generate-id`、`marker`
+- **Then** 查询使用 B 的 provider，ID 使用 B 的 developer，marker 摘要来自 B 的源文件
+
+### AC9: 数据库缺失不产生零候选报告 (R7)
+
+- **Given** `.codegraph/codegraph.db` 不存在，且既有 triage 文件存在
+- **When** `garden --dead-code --write`
+- **Then** `index_status == unavailable`，命令以非零码退出，既有文件逐字节不变
+- **And** 非 `--write` 输出明确说明“未完成扫描”，而不是全零分类
+
+### AC10: 数据库损坏记为 invalid (R7)
+
+- **Given** `codegraph.db` 存在但不是可查询的 SQLite 数据库
+- **When** 运行 `garden --dead-code`
+- **Then** `index_status == invalid`，`--write` 被拒绝且不覆盖既有文件
+
+### AC11: 过期索引记为 stale (R7)
+
+- **Given** provider health 返回可读但 `fresh == false`
+- **When** 运行 `garden --dead-code --write`
+- **Then** `index_status == stale`，写入被拒绝，既有文件不变
+
+### AC12: 无法确认新鲜度记为 unknown (R7)
+
+- **Given** 索引可读，但 provider 不可用或 health 无法给出结论
+- **When** 运行 `garden --dead-code --write`
+- **Then** `index_status == unknown`，写入被拒绝，报告说明新鲜度未验证
+
+### AC13: 外部验证不完整不进入删除建议 (R7)
+
+- **Given** 至少一个外部适配器为 `unavailable`，某符号仅被分类为 `internal-candidate`
+- **When** 生成报告
+- **Then** 该候选 `external_verified == false`
+- **And** `deletable()` 不包含它，`render()` 标出“外部引用验证不完整”
+
+## Target Call Chain
+
+配置写入：`_main` → `_sync_config_before_dispatch` →
+`config_sync.sync_project_config(root)` → `_is_source_tree(root)` → 获取
+`.pactkit/locks/config-sync.lock` → `yaml.compose` / `yaml.safe_load` →
+`_missing_keys` → `atomic_write` → `os.replace`。
+
+查询：`h_query` → `load_effective_config(ctx.project_root)` →
+`resolve_graph_provider` → `project_router(...).query` → `CodegraphProvider.query` →
+文本清洗/预算 → `ProviderDecision(truncated=...)` → `to_dict()` / 人类渲染。
+
+ID 与 marker：`h_generate_id` → `load_effective_config(ctx.project_root)` →
+`generate_item_id`；`h_marker` → `source_for(ctx.project_root, ...)` → `render`。
+
+死代码：`h_garden` → `dead_code.candidates` → `_zero_inbound`（返回行 + 状态）→
+`CodegraphProvider.health()`（仅当可执行文件可用）→ `Report.render()` /
+写入守卫。
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/utils.py` | `atomic_write` 在替换前保留目标 mode；临时文件 `fsync` 后 `os.replace` | None | Medium |
+| 2 | `src/pactkit/config_sync.py` | 守卫前移；锁；YAML 结构定位 stamp；重复/不可定位时 `refused` | 1 | High |
+| 3 | `src/pactkit/graph_query.py` | 拆分清洗与预算；文本 kind 携带原始长度与截断标记；`decision.truncated` 与 warning | None | Medium |
+| 4 | `src/pactkit/commands/handlers.py` | `h_query` / `h_generate_id` / `h_marker` 统一 `ctx.project_root`；文本截断的人类提示 | 3 | Low |
+| 5 | `src/pactkit/dead_code.py` | `index_status`/`index_detail`；`external_verified`；`deletable`；render 状态行 | None | Medium |
+| 6 | `src/pactkit/commands/handlers.py` | `h_garden --dead-code` 读取/传递索引状态；`--write` 仅在 `ok` 时写，否则非零退出 | 5 | Medium |
+| 7 | `tests/unit/` | AC1–AC13 回归；含源码树 stamped 用例、并发锁、quoted stamp、文本预算、`-C` 跨项目、索引状态 | 1–6 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | 配置文件权限与原子替换是权限面；本 Story 修正 mode 丢失并保持 0600 |
+| SEC-2 | Yes | 输入面包括 `-C` 项目路径与 YAML 结构（quoted key、重复键、flow mapping）；写入前重新解析校验 |
+| SEC-3 | Yes | `dead_code` 以只读 URI 打开 SQLite；失败状态必须与空结果区分 |
+| SEC-4 | No | 不修改前端文件 |
+| SEC-5 | Yes | 配置可能含凭据类字段；本 Story 只改权限保持与写入事务，不新增读取/输出路径 |
+| SEC-6 | No | 不新增 API/路由 |
+| SEC-7 | Yes | `locked` / `refused` / `unavailable` / `invalid` / `stale` 都是显式错误路径，必须非零退出或明确告警 |
+| SEC-8 | No | 不新增依赖或依赖清单 |
+
+## Permission Matrix
+
+| Actor | Action | Resource | Decision |
+|-------|--------|----------|----------|
+| 文件所有者 | 读取 `pactkit.yaml` | 项目配置 | Allow |
+| 其他本地用户 | 读取 mode `0600` 的 `pactkit.yaml` | 项目配置 | Deny |
+| 并发 `pactkit` 进程 | 未持锁时读-改-写配置 | `pactkit.yaml` | Deny（返回 `locked`） |
+| 同步进程 | 自动写 PactKit 源码树配置 | 源码树 `pactkit.yaml` | Deny（返回 `source-tree`） |
+| `garden --dead-code --write` | 索引非 `ok` 时覆盖既有 triage | `dead-code-triage.md` | Deny |
+| `-C B` 调用者 | 读取当前目录 A 的配置/developer 来服务 B | A 的项目配置 | Deny（以 B 为准） |
+
+## Dependency Surface
+
+| Field | Value |
+|-------|-------|
+| Depends on | `pactkit.utils.atomic_write`、`pactkit.config.load_effective_config`、`pactkit.graph_query.CodegraphProvider.health`、`ProviderDecision`、`pactkit.dead_code.Report` |
+| Provides | 保留 mode 的 `atomic_write`；`SyncResult` 的 `source-tree`/`locked`/`refused`；文本查询截断标记；`Report.index_status`；`Candidate.external_verified` |
+| Touches | `src/pactkit/utils.py`、`src/pactkit/config_sync.py`、`src/pactkit/graph_query.py`、`src/pactkit/commands/handlers.py`、`src/pactkit/dead_code.py`、对应单测 |
+| Conflict risk | MEDIUM：配置同步几乎每个命令都跑；`atomic_write` 有 69 处调用点；查询 JSON 有下游消费者 |
+
+## Out of Scope
+
+- 死代码数据库的 mtime 启发式新鲜度：只认 provider health，不做时间戳猜测。
+- 文本查询 `result_count` 的语义调整（仍表示包装行数）；本 Story 只补 `truncated`。
+- 引入 `ruamel.yaml` 或全量 YAML round-trip 重写；不新增依赖。
+- 自动删除死代码、自动运行 `codegraph sync`、修改 provider 选择策略。
+- 迁移或提交当前工作区中带 stamp 的 `pactkit.yaml`：这是独立决策。
+- 全仓其余 handler 的 `Path.cwd()` / 无参 `load_config()` 审计；本 Story 只修三个已证实的点，其余可另开 BUG。
+- 跨网络文件系统或非 POSIX 语义下的锁保证；锁只覆盖本机常规文件系统。

pactkit-4.4.1/docs/test_cases/STORY-slim-202611138701d652f238_case.md

@@ -0,0 +1,115 @@
+pactkit marker PACTKIT_MEASUREMENT docs/specs/STORY-slim-202611138701d652f238.md
+
+# Test Cases: STORY-slim-202611138701d652f238 — 配置写入与查询/死代码输出的可信边界
+
+## TC-1: 已有文件权限保持 (AC1, R1)
+
+**Given** 一个权限为 `0600` 的 `pactkit.yaml`
+**When** 调用 `atomic_write()` 写入新内容
+**Then** 文件权限仍为 `0600`
+**And** 在 `umask 022` 下新建目标文件时，权限与本 Story 改动前一致（`0644`）
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_atomic_write_preserves_existing_mode`、`::test_atomic_write_new_target_still_honours_umask`
+
+## TC-2: 源码树永不被自动写 (AC2, R2)
+
+**Given** PactKit 源码树，其 `pactkit.yaml` 已带 `pactkit_version: "4.4.0"`
+**When** 调用 `sync_project_config(repo_root)`
+**Then** 返回 `source-tree`，文件内容与 mtime 均不变
+**And** 无 stamp 的 legacy 源码树同样返回 `source-tree`
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_stamped_source_tree_is_never_auto_written`
+
+## TC-3: 带引号的版本戳被原位替换 (AC3, R3)
+
+**Given** 配置含 `"pactkit_version": "4.3.0"`、`stack: python` 与行尾注释
+**When** 自动同步到 4.4.0
+**Then** 文件中顶层 `pactkit_version` 恰好一个，值为 `"4.4.0"`
+**And** `stack` 与注释逐字节保留
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_quoted_stamp_is_replaced_in_place`
+
+## TC-4: 无法唯一定位时拒绝写入 (AC4, R3)
+
+**Given** 配置使用 flow mapping，或顶层已存在两个 `pactkit_version`
+**When** 自动同步
+**Then** 返回 `refused`，文件逐字节不变，且不新增第三个键
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_duplicate_stamp_is_refused_and_file_is_unchanged`、`::test_flow_mapping_stamp_is_refused_and_file_is_unchanged`
+
+## TC-5: 并发同步不丢更新 (AC5, R4)
+
+**Given** 进程 A 持有同步锁并暂停在写前
+**When** 进程 B 在超时内调用 `sync_project_config()`
+**Then** B 返回 `locked`，文件不变
+**And** 串行执行两次补齐不同缺失键的同步后，两个键都存在于最终文件
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_concurrent_sync_reports_locked`、`::test_two_serial_additions_do_not_drop_each_other`
+
+## TC-6: 文本查询超预算时可见 (AC6, R5)
+
+**Given** CodeGraph 对 `explore` 返回 5000 字符
+**When** 执行查询
+**Then** 返回文本为 4000 字符，`decision.truncated` 为 `true`
+**And** `warnings` 含 `result_budget_hit:text:5000`；人类输出说明字符预算
+**And** `--json` 中同样可见 `truncated: true`
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_text_result_over_budget_is_truncated_and_labelled`、`::test_text_truncation_human_message_names_characters`
+
+## TC-7: 文本查询未超预算时不变 (AC7, R5)
+
+**Given** 返回 1000 字符
+**When** 执行查询
+**Then** 文本完整、`truncated` 为 `false`，且无 `result_budget_hit` 警告
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_text_result_under_budget_is_untouched`
+
+## TC-8: `-C` 目标项目优先于当前目录 (AC8, R6)
+
+**Given** 当前目录 A 与目标目录 B 各有不同的 `graph_provider`、`developer` 与源文件
+**When** 在 A 中执行 `pactkit -C B query --explore ...`、`generate-id`、`marker`
+**Then** 查询使用 B 的 provider，ID 使用 B 的 developer，marker 摘要来自 B 的源文件
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_generate_id_uses_target_project_config`、`::test_query_uses_target_project_config`、`::test_marker_uses_target_project_root`
+
+## TC-9: 数据库缺失不产生零候选报告 (AC9, R7)
+
+**Given** `.codegraph/codegraph.db` 不存在，且既有 triage 文件存在
+**When** `garden --dead-code --write`
+**Then** `index_status == unavailable`，命令以非零码退出，既有文件逐字节不变
+**And** 非 `--write` 输出明确说明“未完成扫描”，而不是全零分类
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_missing_index_is_unavailable_not_zero_candidates`、`::test_dead_code_write_refuses_non_ok_index`
+
+## TC-10: 数据库损坏记为 invalid (AC10, R7)
+
+**Given** `codegraph.db` 存在但不是可查询的 SQLite 数据库
+**When** 运行 `garden --dead-code`
+**Then** `index_status == invalid`，`--write` 被拒绝且不覆盖既有文件
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_corrupt_index_is_invalid`
+
+## TC-11: 过期索引记为 stale (AC11, R7)
+
+**Given** 索引可读但 provider health 报 `fresh == false`
+**When** 运行 `garden --dead-code --write`
+**Then** `index_status == stale`，写入被拒绝，既有文件不变
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_stale_index_is_reported`
+
+## TC-12: 无法确认新鲜度记为 unknown (AC12, R7)
+
+**Given** 索引可读，但 provider 不可用或 health 无法给出结论
+**When** 运行 `garden --dead-code --write`
+**Then** `index_status == unknown`，写入被拒绝，报告说明新鲜度未验证
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_unknown_freshness_is_unknown`
+
+## TC-13: 外部验证不完整不进入删除建议 (AC13, R7)
+
+**Given** 至少一个外部适配器为 `unavailable`，某符号仅被分类为 `internal-candidate`
+**When** 生成报告
+**Then** 该候选 `external_verified == false`
+**And** `deletable()` 不包含它，`render()` 标出“外部引用验证不完整”
+
+对应测试：`tests/unit/test_story_slim202611138701d652f238.py::test_external_verification_incomplete_excludes_deletion`