@mycodemap/mycodemap 2.0.0 → 2.7.0

package/docs/ideation/2026-05-04-subagent-hooks-deep-dive-ideation.md

@@ -0,0 +1,133 @@
+---
+date: 2026-05-04
+topic: subagent-hooks-deep-dive
+focus: Phase 58 hooks system deepening and security architecture
+mode: repo-grounded
+---
+
+# Ideation: Subagent Hooks 安全体系深化
+
+## Grounding Context
+
+### Codebase Context
+- **父代理 session 无防护**: settings.json hooks 为空，所有执行仅存在于 worker.md frontmatter
+- **52 个第三方代理无 hooks**: /home/stark/.claude/agents/ 下所有 hooks 被注释掉
+- **Transcript 审计脆弱**: subagent-stop-audit.js 使用正则扫描 JSONL，可被绕过
+- **Dead hooks**: rule-route-advisory.js 和 check-gstack.sh 存在但未接入
+- **Exit code 协议不一致**: process.exit(2) vs decision:'block' JSON 混用
+- **L0-L3 分级存在但 hooks 不感知**: 分类系统是建议而非控制
+
+### Past Learnings
+- SubagentStart additionalContext 不可靠（压缩时可能丢弃，Issue #23885）
+- PreToolUse updatedInput 对 Agent tool 静默丢弃（Issue #39814）
+- 注入失败，检索成功：retrieval-based pattern 是验证的路径
+- 渐进升级管道：report-only → warn → block
+- env-contract 基础设施成熟：CLI、MCP、doctor、checker、validator
+
+### External Context
+- Claude Code hooks 支持 20+ 事件、5 种 handler（command, http, mcp_tool, prompt, agent）
+- 无竞品有环境契约模式；OS 级沙箱是收敛趋势
+- Codex CLI 使用 sandbox-exec/namespaces 做沙箱
+- Langfuse 提供 session-level trace grouping 和 agent graph visualization
+- 游戏反作弊从客户端控制转向服务端权威验证
+
+## Ranked Ideas
+
+### 1. 父代理升级为执行权威 (Invert Parent Session to Enforcer)
+**Description:** 将主要执行点从子代理 frontmatter 移到父代理的 settings.json hooks。父代理成为主动防火墙，在子代理工具调用到达文件系统前进行检查、拦截和日志记录。子代理级 hooks 变为可选补充而非唯一执行机制。
+**Warrant:** `direct:` — settings.json hooks 显式为空；所有执行仅存在于 worker.md frontmatter 中。父代理是所有子交互的唯一不变量。
+**Rationale:** 每个其他 hook、审计和契约机制都是执行位置的下游。将执行移到父代理将多个 per-agent hook 配置折叠为单一策略面。这是单一最高杠杆的架构变更。
+**Downsides:** 父代理 hooks 在每次工具调用时触发，增加延迟。需要精心设计 matcher 避免对父代理自身操作的误报。可能与现有父代理工具使用模式冲突。
+**Confidence:** 85%
+**Complexity:** Medium-High
+**Status:** Unexplored
+
+### 2. 用签名执行收据替代 Transcript 审计 (Signed Execution Receipts)
+**Description:** 用结构化 JSON "执行收据" 替代 subagent-stop-audit.js 的正则扫描。收据包含：契约哈希、工具调用摘要、文件访问日志。父代理验证收据完整性而非 transcript 内容。
+**Warrant:** `direct:` — 审计脚本存在于 subagent-stop-audit.js，其正则方法被确认为脆弱。JSONL transcript 不是为机器可验证合规设计的——它们是人类可读日志被误用为验证协议。
+**Rationale:** 消除合规管道中最大单一误报/漏报源。将验证从"transcript 是否包含正确字符串"转向"执行是否产生了有效收据"。收据构造上即防篡改。
+**Downsides:** 收据需要子代理配合（必须在 Stop 前发出）。收据格式需要版本化。需要从当前审计的迁移路径。
+**Confidence:** 75%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 3. 第三方代理包装模式 (Third-Party Agent Wrapping)
+**Description:** 创建项目所有的包装代理 (.claude/agents/safe-*.md)，委托给第三方代理同时添加 PreToolUse hooks for Bash safety 和 Stop 审计。包装器成为项目的执行边界；第三方代理行为不变。
+**Warrant:** `reasoned:` — Claude Code 按名称从 .claude/agents/*.md 解析代理。如果项目定义了带 hooks 的 safe-brainstorm.md，用户调用 @safe-brainstorm 时 hooks 生效。这是装饰器模式应用于代理治理。
+**Rationale:** 当前状态是二元的：要么完全信任 52 个代理，要么不使用它们。包装给出中间地带——使用代理能力同时执行项目级规则。对会生成自己子代理的代理（嵌套信任链）尤其有价值。
+**Downsides:** 每个包装器是维护面。包装器可能与上游代理定义漂移。并非所有第三方代理都能干净地包装（复杂工具需求）。
+**Confidence:** 80%
+**Complexity:** Low-Medium
+**Status:** Unexplored
+
+### 4. 审计日志作为一等工件 (Audit Trail As First-Class Artifact)
+**Description:** 创建结构化追加日志 (.mycodemap/audit.jsonl)，每个 hook 调用追加一行 JSON（时间戳、事件、代理类型、决策、原因）。构建 `mycodemap audit` CLI 命令查询和趋势分析。
+**Warrant:** `direct:` — subagent-stop-audit.js 已经读取 transcript、解析 JSONL 并提取结构化数据。如果它将发现写入结构化日志，审计轨迹将经受 transcript 轮换、可被 mycodemap doctor 查询、并支持趋势分析。
+**Rationale:** 将合规从"我们认为代理遵循规则"转变为"我们可以证明，这是趋势"。使 mycodemap doctor 能报告合规率。创建反馈循环：如果规则产生大量违规，要么沟通不畅，要么规则过严。
+**Downsides:** 日志文件随时间增长（需要轮换）。Hook 脚本稍微复杂（必须写入日志）。共享仓库的隐私考虑。
+**Confidence:** 90%
+**Complexity:** Low
+**Status:** Unexplored
+
+### 5. 服务端权威结果验证 (Server-Authoritative Outcome Validation)
+**Description:** 不验证代理行为（调用了什么工具），而是验证代理结果（代码库状态变化）。运行确定性后置验证检查不变量——无意外文件修改、无规则违规、无能力边界突破。
+**Warrant:** `reasoned:` — 游戏反作弊从客户端控制转向服务端权威验证，因为不能信任客户端。CodeMap 当前通过 PreToolUse hooks（客户端控制）控制代理行为。52 个无 hooks 代理 = 忽略反作弊的游戏客户端。但你可以通过检查代码库 diff 验证任何代理触碰后的状态。
+**Rationale:** 直接解决"52 个代理无 hooks"盲区。即使无法拦截代理的工具调用，也可以通过检查结果代码库 diff 检测违规。从"控制代理"转向"控制后果"。
+**Downsides:** 事后检测（损害已发生）。需要清晰定义不变量。合法但异常的变更可能产生误报。
+**Confidence:** 80%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 6. 契约运行时 API — 单一编译面 (Contract Runtime API)
+**Description:** 构建 compileContract() 函数，从所有治理源（AGENTS.md, .githooks, package.json, docs/rules/, .mycodemap/rules/）产生单一 ProjectEnvironmentContract 工件。所有下游消费者——hooks、MCP、doctor、CI、transcript 审计——从这一个编译输出读取。
+**Warrant:** `reasoned:` — 当前 discovery.ts 已部分实现（5 个硬编码 builder），但每个新执行面需要自己的集成代码。单一编译步骤加稳定 API 消除每消费者集成工作。添加新契约项 = 添加一个 builder 函数；所有消费者自动获取。
+**Rationale:** 当前添加新契约规则需要分别修改 discovery、CLI、MCP tool、doctor 和可能的 hooks。运行时 API 意味着每个未来契约项以零额外接线流过所有执行路径。O(1) 集成而非 O(n)。
+**Downsides:** 需要重构现有消费者使用 API。单一编译面成为单点故障。API 设计需要关注向后兼容。
+**Confidence:** 85%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 7. 反转 Read-Before-Edit；编辑前自动读取 (Auto-Read Before Edits)
+**Description:** 不阻断未读文件的编辑，而是在 PreStep 中自动触发静默读取。Hook 拦截 Edit 调用，内部执行读取，将文件内容注入子代理上下文，然后允许编辑继续。执行是环境性的，非教育性的。
+**Warrant:** `reasoned:` Read-Before-Edit 是已知的 AI 编程助手失败模式。阻断门创建摩擦并教会子代理添加形式化读取调用。不可见预读确保上下文始终存在，无需子代理显式请求。
+**Rationale:** 消除最常见的 AI 编码错误类别（过时上下文编辑）而不增加摩擦。无论子代理是否"记得"先读都有效。执行是环境性的，非教育性的。
+**Downsides:** Hook 必须注入文件内容到上下文（大文件的 token 成本）。可能与子代理自身读取策略冲突。实现依赖 Claude Code hook 注入内容的能力。
+**Confidence:** 70%
+**Complexity:** Medium-High
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| P6 | SubagentStart Context Injection Broken Promise | 已有文档覆盖 |
+| P4 | Two-Language Exit Code Problem | 低于讨论门槛 — 清理任务 |
+| P5 | Dead Hooks on Disk | 低于讨论门槛 — 接线任务 |
+| I3 | Remove Explicit env-contract Calls via Hook Injection | Warrant 自相矛盾 |
+| I7 | Remove Inconsistent Exit Code | 与 P4 重复 |
+| A5 | The Contract Is The Hook | 与 I3 重复 |
+| A6 | Treat Hook Bugs As Config | Bug 未修复时不可操作 |
+| A7 | Agent-Type-less Contracts | 成本超过收益 |
+| A2 | Behavioral Anomaly Scoring | 过于投机，无基础设施 |
+| L6 | Contract Item Plugin Registry | 当前规模过度设计 |
+| L7 | Drift-Aware Regeneration Pipeline | 低于讨论门槛 — 工程任务 |
+| L8 | Contract Coverage Matrix | 低于讨论门槛 — doctor 扩展 |
+| I4 | Convert Advisory to Mandatory Gates | 直接工程任务 |
+| L5 | Platform-Agnostic Adapters | 非核心安全问题 |
+| A1 | The Parent Is The Threat | 被更强 I1 吸收 |
+| A3 | Transcript Audit As Prevention | 被更强 I1 吸收 |
+| C6 | Parent Session Mirror | 被更强 I1 吸收 |
+| L4 | Agent Behavior Ledger | 被更强 A8 吸收 |
+| C7 | Honeypot Contract Injection | 被更强 C3 吸收 |
+| L2 | Hook Action Bindings | 被更强 L1 吸收 |
+| I6 | Automate L0-L3 Classification | 精度不足 |
+| P7 | L0-L3 But Hooks Don't See It | 被 I6 吸收后拒绝 |
+| P8 | 52-Agent Blind Spot in Audit | 被更强 C3 吸收 |
+| L3 | Contract-as-Test Harness | 被更强 A8 吸收 |
+| I5 | Remove Per-Agent Hook Config | 被更强 I1 吸收 |
+| P3 | Retroactive Audit Theater | 被更强 I1 吸收 |
+| C2 | All 20+ Events Telemetry Ring | 与 A8 重叠但更不实用 |
+| C1 | Zero-Token Enforcement | 有趣但实现成本高 |
+| C4 | Agent Registry & Capability Negotiation | 需要平台支持 |
+| C5 | Contract-as-Runtime-Code Compiler | 高成本，增量收益有限 |
+| C8 | Custom MCP Enforcement Gateway | 过度设计 |

package/docs/ideation/2026-05-10-agent-effectiveness-validation-ideation.md

@@ -0,0 +1,219 @@
+---
+date: 2026-05-10
+topic: agent-effectiveness-validation
+focus: 验证 mycodemap 工具已完成功能是否真正为 AI agent 产生了积极效果，需要数据指标支撑
+mode: repo-grounded
+---
+
+# Ideation: CodeMap Agent 效果验证——如何证明工具真的有用
+
+## Grounding Context
+
+**Codebase:** CodeMap v2.0.0, TypeScript, CLI/MCP/HTTP API surfaces, architecture CLI→Server→Domain→Infrastructure→Interface.
+
+**Key existing evidence:**
+- Comprehensive test report (2026-03): 5-scenario comparison, 3.35/5 overall score, 60-300x slower than rg but near-zero false positives
+- Agent dogfood report (2026-04-17): 6/10 agent-friendliness, controlled A/B showing 6+→1 calls for impact analysis
+- Validation guardrails (Phase 40.1): real-world validation as hard constraint
+- Ghost command detection (Phase 46): docs accuracy validation
+
+**Critical gap:** No continuous effectiveness metrics, no automated validation pipeline, no agent feedback loop.
+
+**External benchmarks:** SWE-bench, HumanEval, GitHub Copilot (55% speed improvement), METR (AI tools may slow senior devs by 19%), Anthropic tool design evaluation, LangSmith, SPACE framework.
+
+## Topic Axes
+
+1. Agent task completion efficiency
+2. Token/call efficiency
+3. Accuracy/precision
+4. Agent behavior quality
+5. Developer experience
+
+## Ranked Ideas
+
+### 1. Agent Task Completion A/B Harness
+
+**Description:** Build a harness that runs identical agent prompts (find callers, assess impact, trace dependencies) against two conditions: CodeMap-enabled vs text-search-only. Measures task completion rate, time-to-solution, and answer correctness. Runs as CI gate on every release.
+
+**Axis:** Agent task completion efficiency
+
+**Basis:** `direct:` Dogfood report (2026-04-17) showed 6+→1 calls for impact analysis, but was one-time manual evaluation with no repeatable infrastructure. The grounding summary explicitly states "No continuous effectiveness metrics, no automated validation pipeline."
+
+**Rationale:** This is the foundational validation question. Without A/B infrastructure, every claim about CodeMap's value remains a proxy metric. The actual question — "does the agent solve the task better with CodeMap?" — is unanswered. All other metrics (speed, accuracy, tokens) are intermediate proxies of this core question.
+
+**Downsides:** Requires defining ground truth for agent tasks (non-trivial). Agent variability adds noise. Needs 2-3 weeks of dedicated effort.
+
+**Confidence:** 90%
+
+**Complexity:** High
+
+**Status:** Unexplored
+
+---
+
+### 2. Zero-Touch Benchmark from Git History
+
+**Description:** Mine the repo's git history for real impact analysis, dependency tracing, and refactoring commits. Replay those exact scenarios through CodeMap automatically. Every merged PR becomes a free test case with ground truth (the human did the work). Eliminates manual test scenario design entirely.
+
+**Axis:** Accuracy/precision
+
+**Basis:** `direct:` Phase 40.1 established real-world validation as hard constraint. `external:` SWE-bench uses this exact pattern — GitHub issues + merged PRs as ground truth for agent evaluation.
+
+**Rationale:** Currently validation requires manually constructing scenarios. This eliminates that cost — every merged PR in every participating repo becomes a growing validation dataset with zero human effort. Compounds over time: more PRs = stronger signal.
+
+**Downsides:** Git history quality varies; not all commits have clear "ground truth." Requires mapping commit types to CodeMap query types. Initial harness investment needed.
+
+**Confidence:** 85%
+
+**Complexity:** Medium
+
+**Status:** Unexplored
+
+---
+
+### 3. Token Cost Accounting
+
+**Description:** Tag each CodeMap response with estimated token cost (input + output). Compare against raw-text alternatives (rg, grep). Build per-query-type token baselines. Expose as `codemap benchmark --token-report` command. Enables agents to make informed tool-choice decisions.
+
+**Axis:** Token/call efficiency
+
+**Basis:** `direct:` Dogfood report showed 6+→1 call reduction but never measured total token consumption. A single CodeMap call returning 50KB JSON might cost 15K tokens vs 200 bytes from rg. `external:` GitHub Copilot research (55% speed improvement) and Anthropic tool design emphasize minimizing agent processing burden.
+
+**Rationale:** Agents pay for tokens, not tool calls. The 6+→1 reduction is CodeMap's strongest claim, but if each response is 50x larger, token savings may be negated. This is the cheapest metric to implement (just count) and most directly actionable (maps to real cost).
+
+**Downsides:** Token estimation is approximate. Response size varies by query and codebase. Doesn't capture downstream token savings (agent doesn't need to read files).
+
+**Confidence:** 85%
+
+**Complexity:** Low
+
+**Status:** Unexplored
+
+---
+
+### 4. Ghost Feedback — Agent Behavior Telemetry
+
+**Description:** Instrument the MCP gateway to log post-CodeMap agent behavior. Classify into: "accepted" (moved on), "re-queried" (response insufficient), "abandoned" (fell back to rg/grep). Requires no cooperation from agents — just server-side observation. Produces continuous effectiveness signal.
+
+**Axis:** Agent behavior quality
+
+**Basis:** `direct:` Grounding summary identifies "no agent feedback loop" as key gap. Phase 46 ghost command detection shows infrastructure for detecting unexpected tool usage patterns already exists. `external:` METR finding that "AI tools may slow senior devs by 19%" suggests adoption friction matters more than tool capability.
+
+**Rationale:** The agent dogfood report was one-time manual evaluation. Without continuous behavioral telemetry, we cannot detect regressions (parser change makes output harder to parse), adoption drops (agents learn to avoid CodeMap), or feature-specific problems. This is the cheapest continuous signal — captured automatically during normal operation.
+
+**Downsides:** Classification of "accepted" vs "abandoned" requires heuristics that may be noisy. Privacy considerations for logging agent behavior. Doesn't capture WHY behavior changed.
+
+**Confidence:** 80%
+
+**Complexity:** Low-Medium
+
+**Status:** Unexplored
+
+---
+
+### 5. Agent-Perceived Latency vs Raw Latency
+
+**Description:** Redefine the benchmark: instead of comparing CodeMap-WASM vs CodeMap-Native, compare CodeMap single-call total time vs equivalent multi-call raw-tool workflow total time. An agent waiting 2s for CodeMap that replaces 6 rg calls (200ms each = 1200ms total) has net latency reduction. Set thresholds based on agent-perceived delta.
+
+**Axis:** Developer experience
+
+**Basis:** `direct:` Benchmark command states "[WHY] Compare WASM vs Native performance to verify <1s startup penalty on 10K-file repos." The 2026-03 report found "CodeMap 60-300x slower than rg" — but this compares single-call latency without accounting for multi-call alternative workflow.
+
+**Rationale:** Current benchmark creates a false optimization target. If we optimize WASM from 800ms to 400ms, that's 50% improvement on benchmark — but agents don't care because the alternative (6×200ms = 1200ms) is still slower. Agent-perceived latency reframes the metric to what actually matters for agent workflows.
+
+**Downsides:** Defining "equivalent workflow" requires judgment. Different task types have different alternative workflows. May need per-query-type latency budgets.
+
+**Confidence:** 80%
+
+**Complexity:** Low
+
+**Status:** Unexplored
+
+---
+
+### 6. Adoption Decay Monitoring
+
+**Description:** Track, over time, what percentage of eligible agent queries use CodeMap vs raw-text alternatives (rg, grep). A declining adoption rate is the ultimate effectiveness signal — it means the tool is failing at its core mission. Report weekly. Compare against baseline.
+
+**Axis:** Agent behavior quality
+
+**Basis:** `external:` METR's finding that AI tools may slow senior devs by 19% implies adoption decay is a real phenomenon — tools that don't deliver value get abandoned. `direct:` Grounding summary notes "no continuous effectiveness metrics" and "no agent feedback loop."
+
+**Rationale:** All other metrics (speed, accuracy, token cost) are intermediate proxies. Adoption rate is the ground truth. If agents stop using CodeMap, nothing else matters. Tracking adoption decay is the cheapest, most informative validation we can build — it's the "vital sign" of tool effectiveness.
+
+**Downsides:** Requires instrumenting agent tool selection (may not be available in all environments). Defining "eligible queries" needs thought. Adoption may fluctuate for reasons unrelated to tool quality.
+
+**Confidence:** 75%
+
+**Complexity:** Low-Medium
+
+**Status:** Unexplored
+
+---
+
+### 7. Precision-Weighted Cost Model
+
+**Description:** Quantify the downstream cost of false positives and false negatives in CodeMap outputs. Formula: `cost = (fp_rate × wasted_action_cost) + (fn_rate × missed_issue_cost)`. Track across query types. Reveals which query types have asymmetric costs (missing a security dependency is worse than listing an unused one).
+
+**Axis:** Accuracy/precision
+
+**Basis:** `direct:` 2026-03 test report showed near-zero false positives but measured in isolation. Dogfood report's 6/10 agent-friendliness suggests accuracy alone doesn't guarantee usefulness. `external:` METR findings imply tool outputs must be high-signal to justify integration cost.
+
+**Rationale:** Transforms accuracy from binary metric ("is it correct?") to economic one ("what does correctness cost?"). Once established, lets you set precision thresholds per feature type and make trade-off decisions objective. Reveals where to invest accuracy improvements for maximum impact.
+
+**Downsides:** Requires estimating "wasted action cost" and "missed issue cost" (judgment-dependent). Needs real agent session data to calibrate. May oversimplify complex failure modes.
+
+**Confidence:** 75%
+
+**Complexity:** Medium
+
+**Status:** Unexplored
+
+---
+
+## Cross-Cutting Combinations
+
+### CC1: Behavioral Telemetry + Adoption Decay (Ideas 4 + 6)
+Micro-level (per-call behavior) + macro-level (adoption trends) = complete agent trust picture. Telemetry shows WHAT agents do; adoption shows WHETHER they keep doing it.
+
+### CC2: Zero-Touch Git History + A/B Harness (Ideas 1 + 2)
+Git mining generates test cases automatically; A/B harness runs them with/without CodeMap = continuous validation from real usage with zero manual effort.
+
+### CC3: Token Accounting + Agent-Perceived Latency (Ideas 3 + 5)
+Token cost per response + total workflow time comparison = true efficiency picture. Both reframe "CodeMap is slow" into "CodeMap is efficient when measured correctly."
+
+---
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1.2 | Dead Man's Switch | Overlaps with 1.1 (A/B harness); harder to implement, same insight |
+| 1.3 | Production Shadow Tracing | Overlaps with 4 (Ghost Feedback); same telemetry, less structured |
+| 1.4 | Agent-Native Validation Harness | Duplicate of 1.1 with different framing |
+| 1.5 | Comparative A/B in Production | Duplicate of 1.1 at workflow level |
+| 1.6 | Session Replay Infrastructure | Overlaps with 1.1; higher complexity for marginal gain |
+| 1.8 | Pharmaceutical Clinical Trials | Same concept as 1.1, academic framing |
+| 1.9 | Automated SWE-bench Pipeline | Same as 1.1, higher ambition not justified now |
+| 1.10 | Open Benchmark Community | Too expensive for current stage; internal benchmarks sufficient |
+| 2.3 | Automated Token-Per-Insight | Duplicate of 3 (Token Cost Accounting) |
+| 2.4 | Token-Efficiency First-Class | Duplicate of 3 |
+| 2.5 | Token Delta Tracking | Duplicate of 3 + 2.2 combined |
+| 2.6 | Sports Biomechanics | Too academic; actionable metric is token cost (covered by 3) |
+| 2.7 | Sharpe Ratio | Interesting reframing but overlaps with 7 (Precision-Weighted Cost) |
+| 2.8 | Token Budget Pressure Test | Duplicate of 2.2 (Call Collapse) + 3 (Token Accounting) |
+| 3.4 | "Fool the Agent" Adversarial | Overlaps with 3.5; 3.3 (Git History) more pragmatic |
+| 3.5 | Red-Team Adversarial | Overlaps with 3.3 (Git History); git history provides real adversarial cases |
+| 3.6 | Regression Canary | Overlaps with 3.3 (Git History); git mining is more comprehensive |
+| 3.8 | Cross-Codebase Generalization | Good but lower priority than 3.3; can be added later |
+| 4.3 | Behavioral Fingerprinting | Overlaps with 4 (Ghost Feedback); same signal, more complex |
+| 4.4 | Agent-as-Judge | Overlaps with 4 (Ghost Feedback); explicit feedback less reliable than behavioral |
+| 4.5 | Shadow-Mode Effect | Too complex for current stage; 4 (Ghost Feedback) captures similar signal |
+| 4.6 | Measure What Don't Ask | Duplicate of 6 (Adoption Decay) |
+| 4.7 | Override Signal | Overlaps with 4 (Ghost Feedback); override is one behavior class |
+| 4.8 | Aviation Intervention Rate | Academic reframing of 4.7; same insight |
+| 5.2 | Delete the Docs | Interesting but risky; 5 (Agent-Perceived Latency) more actionable |
+| 5.3 | Single-User Instrumentation | Overlaps with 4 (Ghost Feedback); manual vs automated |
+| 5.4 | Continuous Satisfaction Signal | Duplicate of 4 (Ghost Feedback) |
+| 5.5 | Latency Budget | Good CI gate but subset of 5 (Agent-Perceived Latency) |
+| 5.6 | Learning Curve Analysis | Too academic; adoption decay (6) captures similar signal |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "2.0.0",
+  "version": "2.7.0",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",
@@ -29,6 +29,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "postbuild": "node scripts/copy-build-assets.mjs",
     "dev": "tsc --watch",
     "docs:check": "node scripts/validate-docs.js && node scripts/validate-ai-docs.js",
     "docs:check:human": "node scripts/validate-docs.js",
@@ -67,9 +68,13 @@
     "commander": "^11.1.0",
     "dependency-cruiser": "^17.3.10",
     "globby": "^14.0.0",
+    "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
     "hono": "^4.12.8",
     "ora": "^8.0.1",
+    "smol-toml": "^1.6.1",
     "tree-sitter": "^0.21.1",
+    "tree-sitter-python": "0.23.4",
     "tree-sitter-typescript": "^0.23.2",
     "typescript": "^5.3.3",
     "typhonjs-escomplex": "^0.1.0",
@@ -85,8 +90,8 @@
     "vitest": "^1.1.0"
   },
   "optionalDependencies": {
-    "web-tree-sitter": "^0.24.0",
-    "sql.js": "^1.12.0"
+    "sql.js": "^1.12.0",
+    "web-tree-sitter": "^0.24.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/copy-build-assets.mjs

@@ -0,0 +1,23 @@
+// Post-tsc copy step: ship non-TS assets that `tsc` does not emit into `dist/`.
+// Phase 53: built-in bootstrap profile JSONs live next to the profile-loader
+// and must be present at runtime in published packages (`files` ships `dist/`,
+// not `src/`).
+
+import { cpSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+
+const copies = [
+  {
+    from: path.join(repoRoot, 'src', 'cli', 'init', 'profiles'),
+    to: path.join(repoRoot, 'dist', 'cli', 'init', 'profiles'),
+  },
+];
+
+for (const { from, to } of copies) {
+  mkdirSync(to, { recursive: true });
+  cpSync(from, to, { recursive: true });
+  console.log(`[copy-build-assets] ${path.relative(repoRoot, from)} -> ${path.relative(repoRoot, to)}`);
+}

package/scripts/hooks/templates/pre-commit

@@ -40,6 +40,35 @@ echo "Tests passed"
 # 2. repo-local 规则校验（按 hard_gate.mode 决定 report-only / enforce）
 RULE_CONFIG_PATH=".claude/rule-system.config.json"
 RULE_HARD_GATE_MODE="report-only"
+RULE_REPORT_ONLY_TIMEOUT_SECONDS="${RULE_REPORT_ONLY_TIMEOUT_SECONDS:-20}"
+
+run_rule_validation_report_only() {
+    python3 - <<'PY'
+import os
+import subprocess
+import sys
+
+timeout_value = os.environ.get("RULE_REPORT_ONLY_TIMEOUT_SECONDS", "20")
+
+try:
+    timeout_seconds = int(timeout_value)
+except ValueError:
+    timeout_seconds = 20
+
+try:
+    completed = subprocess.run(
+        ["python3", "scripts/validate-rules.py", "code", "--report-only"],
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        timeout=timeout_seconds,
+    )
+except subprocess.TimeoutExpired:
+    sys.exit(124)
+
+sys.exit(completed.returncode)
+PY
+}
 
 if [ -f "$RULE_CONFIG_PATH" ]; then
     RULE_HARD_GATE_MODE=$(python3 - <<'PY'
@@ -91,9 +120,11 @@ case "$RULE_HARD_GATE_MODE" in
         if [ "$RULE_HARD_GATE_MODE" != "report-only" ]; then
             echo "WARNING: Unknown hard gate mode '$RULE_HARD_GATE_MODE', defaulting to report-only"
         fi
-        python3 scripts/validate-rules.py code --report-only >/dev/null
+        run_rule_validation_report_only
         VALIDATE_EXIT=$?
-        if [ "$VALIDATE_EXIT" -ne 0 ]; then
+        if [ "$VALIDATE_EXIT" -eq 124 ]; then
+            echo "WARNING: Rule validation report-only timed out after ${RULE_REPORT_ONLY_TIMEOUT_SECONDS}s, continuing commit"
+        elif [ "$VALIDATE_EXIT" -ne 0 ]; then
             echo "WARNING: Rule validation report-only command exited with $VALIDATE_EXIT, continuing commit"
         else
             echo "Rule validation report-only completed"

package/scripts/tests/test_rule_control_workflow.py

@@ -35,8 +35,12 @@ class RuleControlWorkflowTests(unittest.TestCase):
             ROOT / ".codex/get-shit-done/workflows/execute-phase.md",
             ROOT / ".claude/get-shit-done/workflows/execute-phase.md",
         ]
+        existing_paths = [workflow_path for workflow_path in workflow_paths if workflow_path.exists()]
 
-        for workflow_path in workflow_paths:
+        if not existing_paths:
+            self.skipTest("execute-phase workflow paths are not vendored in this checkout")
+
+        for workflow_path in existing_paths:
             content = workflow_path.read_text(encoding="utf-8")
             self.assertIn("rule-context.mjs --files", content)
             self.assertIn("<rule_context>", content)
@@ -46,6 +50,16 @@ class RuleControlWorkflowTests(unittest.TestCase):
         self.assertIn("Rule validation backstop", content)
         self.assertIn("python3 scripts/validate-rules.py code", content)
 
+    def test_pre_commit_report_only_timeout_guard_exists(self):
+        for hook_path in [
+            ROOT / ".githooks" / "pre-commit",
+            ROOT / "scripts" / "hooks" / "templates" / "pre-commit",
+        ]:
+            content = hook_path.read_text(encoding="utf-8")
+            self.assertIn("RULE_REPORT_ONLY_TIMEOUT_SECONDS", content)
+            self.assertIn("Rule validation report-only timed out after", content)
+            self.assertIn("subprocess.TimeoutExpired", content)
+
 
 if __name__ == "__main__":
     unittest.main()