diff --git a/README.md b/README.md index e8e8168..76a7fec 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ +## Optional diagnostic log + +TaskFlow diagnostics are off by default. From the affected repository, ask the TaskFlow agent to enable diagnostics, or run `bash /hooks/diagnostic-log enable` to enable them and `bash /hooks/diagnostic-log disable` to stop recording. Export to a new local file with `bash /hooks/diagnostic-log export /path/to/new-file.jsonl`; the export is never uploaded. Export requires a filesystem supporting hard links. Only fixed event categories, result categories and UTC timestamps are stored; no prompts, commands, paths, code, personal data, tool output or arbitrary capability names are recorded. Recording stops when the log reaches approximately 1 MiB; asynchronous events can be lost. For a few fixed skill names, a shell command is classified as a mention without retaining the command; a mention does not prove a read succeeded. Hosts expose different events; missing records do not establish that a capability was not used or why the model chose it. + + > [!IMPORTANT] > **TaskFlow is a workflow convention, not an Agent.** It does not select tools or take decisions itself. It may coordinate with host/harness hooks (Claude Code, Codex CLI, CodeBuddy, dsh, and Trae) for bounded bookkeeping and context summaries; hooks never write core documents and never approve. It gives humans and Agents a shared, inspectable place to record what a task means and how it changed. diff --git a/README.zh-CN.md b/README.zh-CN.md index 5be2d32..9a0c0ae 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -16,6 +16,11 @@ +## 可选诊断日志 + +TaskFlow 诊断日志默认关闭。在相关仓库中请 TaskFlow Agent 启用诊断日志,或运行 `bash <已安装的 TaskFlow 路径>/hooks/diagnostic-log enable` 启用,运行 `bash <已安装的 TaskFlow 路径>/hooks/diagnostic-log disable` 停止记录;使用 `bash <已安装的 TaskFlow 路径>/hooks/diagnostic-log export /path/to/new-file.jsonl` 导出到新的本地文件,导出不会自动上传;导出目标所在文件系统须支持硬链接。日志只保存固定事件类别、结果类别和 UTC 时间,不记录提示词、命令、路径、代码、个人信息、工具输出或任意能力名称。日志达到约 1 MiB 后停止写入;记录异步执行,事件可能丢失。对于少数固定技能名,只从 shell 命令中提取“被提及”的固定类别,不保存命令;被提及不代表读取成功。各宿主可提供的事件不同;缺少记录不能证明未使用能力,也不能解释模型选择原因。 + + > [!IMPORTANT] > **TaskFlow 是流程约定,不是 Agent。** 它不选择工具、也不替 Agent 决策。它可与宿主/工具链 hook(Claude Code、Codex CLI、CodeBuddy、dsh 与 Trae)协作做有边界的记账和上下文摘要;hook 绝不写核心文档、绝不代为批准。它为人和 Agent 提供一个共同的、可检查的地方,记录任务是什么以及它如何变化。 diff --git a/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/plan.md b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/plan.md new file mode 100644 index 0000000..c4105dc --- /dev/null +++ b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/plan.md @@ -0,0 +1,123 @@ +# Plan — TaskFlow 脱敏诊断日志与导出 +> Task version: v1 +> Status: completed + +## Spec Pointers + +- `spec.md` + +## Reference Pointers + +- [Reinforce] `CODE_STYLE.md` — 代码风格、隐私及兼容约束。 + +## Related Tasks + +- 关联 `fix/taskflow-capability-outcomes` 分支的 `TaskFlowDocs/2026-11-12-capability-outcomes/` v1(尚未合入 main):日志为后续正式安装排查提供独立交付;不宣称完成原任务的行为验收。 + +## Skills / Tools Used + +- [PRD] Declared `agent-skills:spec-driven-development` — purpose: 形成可验收的需求和隐私边界;outcome: 区分可观测事件、未知原因和导出;incorporated: PRD 要求及验收。 +- [Spec] Declared `agent-skills:spec-driven-development` — purpose: 设计事件和数据边界;outcome: 允许列表、重新校验、失败语义;incorporated: Spec。 +- [Plan] Declared `agent-skills:planning-and-task-breakdown` — purpose: 设计依赖顺序及可验证步骤;outcome: 拆分事件核实、实现和独立验收;incorporated: Steps。 +- [Test] Declared `agent-skills:security-and-hardening` — purpose: 考虑敏感输入和信任边界;outcome: 密钥、代码、恶意记录及失败场景;incorporated: 测试要求。 +- `agent-skills:observability-and-instrumentation` — purpose: 设计可回答的问题;outcome: 事件、结果与宿主可见性分开;incorporated: Spec。 + +## Preconditions + +- 使用项目内工作树 `D:/WorkSpace/Agent/TaskFlow/.worktrees/capability-outcomes`,分支 `fix/taskflow-capability-outcomes`。 +- 已确认默认关闭、指定本地导出和允许列表;不记录用户内容,不阻塞运行。 +- 项目规则 `CONTRIBUTING.md`、`CODE_STYLE.md`;任务事实以当前文档为准。 + +## Plan Review + +- Verdict: sound — 方案覆盖已确认需求;具体宿主支持必须先验证。 +- Coverage: Step 1 核实事件及隐私契约;Step 2 实现启停、异步记录与导出;Step 3 覆盖安全、非阻塞和宿主结果;Step 4 审查、提交和交付。 +- Verifiability: 每项行为均由导出内容、可控阻塞测试和宿主事件检查;无法观察的原因不宣称已知。 +- Layer ownership: 宿主决定可见事件,TaskFlow 负责允许列表、非阻塞采集与安全导出,用户负责正式安装后的实际场景测试。 + +## Approval + +- Status: approved +- Approved by: user +- Approved at: 2026-11-13 13:29 +0800 +- Approved version: v1 +- Approved scope: PRD / Spec / Plan + +## Steps + +### Step 1 — 核实宿主事件与数据边界 + +- Goal: 确认可记录事件、异步机制和具体隐私边界。 +- Dependencies: v1 方案获批。 +- Files: 宿主 hook 配置与运行时说明。 +- Implementation checklist: + - [x] 核对宿主事件、异步语义及覆盖限制,确定固定事件与能力分类。 +- Acceptance: 每个字段均有来源和允许范围,不能推断的事实明确标未知。 +- Verification: 接线与受控事件对照。 +- Rollback: 只更正任务记录。 +- Status: done + +### Step 2 — 实现诊断与导出 + +- Goal: 实现默认关闭、非阻塞记录和安全的本地导出。 +- Dependencies: Step 1。 +- Files: `hooks/`、宿主配置、TaskFlow skill、README。 +- Implementation checklist: + - [x] 实现用户启停、异步固定枚举记录和安全导出;更新用户说明。 +- Acceptance: 不写用户内容;导出仅写指定新文件;不自动上传。 +- Verification: 功能与格式测试。 +- Rollback: 回退本步骤提交,不删除用户日志。 +- Status: done + +### Step 3 — 安全、非阻塞与真实宿主验证 + +- Goal: 验证泄露防护、日志故障和实际事件路径。 +- Dependencies: Step 2。 +- Files: 现有测试与项目内临时夹具。 +- Implementation checklist: + - [x] 测试敏感输入、恶意记录、默认关闭、导出失败、并发和受控阻塞。 + - [x] 运行适用 smoke、离线评估和至少一个受授权真实宿主场景,记录覆盖边界。 +- Acceptance: 隐私和非阻塞测试通过,测试材料及宿主限制可审计。 +- Verification: 命令、结果及脱敏证据。 +- Rollback: 按授权清理本次测试夹具,保留用户数据。 +- Status: done + +### Step 4 — 审查与交付 + +- Goal: 审查差异,提交版本回退点,为用户 PR 与发布准备结果。 +- Dependencies: Step 3。 +- Files: 变更及任务记录。 +- Implementation checklist: + - [x] 完成审查、Git 提交、记录验证与限制。 +- Acceptance: 代码、说明和测试一致;不擅自推送、合并或发布。 +- Verification: `git diff --check`、Git 状态与提交检查。 +- Rollback: 按提交回退。 +- Status: done + +## Checkpoints + +## Verification / Review + +- Windows 与 WSL 的 `hooks/test-diagnostic-log` 通过:默认关闭、后台入口、合成密钥和代码不落盘、恶意记录过滤、并发格式、固定技能及命令中提及的分类、禁覆盖和人为延迟的 Git/存储检查。事件记录采用异步旁路;合成阻塞测试验证入口在等待上限前返回,不证明所有文件系统和宿主都无延迟。 +- 在 WSL 的 Windows 挂载目录复现并发追加丢失少量事件;保留记录格式完整,日志为尽力记录而非完整审计。达到约 1 MiB 停止追加,文档已说明。 +- 独立 PR 分支的 Windows 完整 smoke(包括诊断测试入口、双 shell 配置和开放 stdin)通过;分支上的 WSL 诊断测试通过。`python evals/runner.py` PASS (6);WSL Python 运行技能校验通过。Windows 默认 Python 缺 PyYAML,未安装依赖。 +- 创建并临时安装本地测试插件,随后通过正式 CLI 移除插件和市场,核实缓存副本及市场均不存在,官方更新保留;第二轮真实宿主测试后再次移除插件与市场,精确删除其 11 个 hook 状态并以 TOML 结构对比确认其他配置不变。当前 computer-use 技能禁止操作 Codex CLI 和安全权限界面,无法自动信任测试 hook;用户手动信任指定诊断 hook 后,在受监控合成仓库运行 `codex exec --json --sandbox read-only`,会话和答复完成、退出 0,未观察到工具调用;项目日志出现 session 和 prompt 两条事件,用户指定本地路径的 JSONL 导出仅含五个允许字段。此次未覆盖真实宿主的工具调用事件或其他宿主,不能推断其行为。Linux 全量 smoke 的首次夹具准备因 Windows Git 工作树路径不适用于 WSL 失败;第二次复制时误排除诊断脚本而失败。修正后暴露旧的固定命令数量断言和两个脚本清单未更新;补充逐宿主逐事件接线断言及清单后,在私有 tmpfs 中重跑得到 `ALL SMOKE PASSED`。 +- 自审:日志仅输出固定枚举与生成的时间,导出重新校验、通过硬链接发布而不覆盖现有目标;不支持硬链接的目标文件系统将返回失败。提及分类仅表示工具输入含固定技能名,不证明成功读取或采用;不记录原命令。 + +- 原关联分支代码提交 `7218bfa`、检查记录提交 `67617a5`;日志独立 PR 分支分别移植为 `cdac9fc`、`29915f9`,并保留真实宿主验收与归档提交。 + +- PR 模板 `.github/pull_request_template.md`:Summary 说明默认关闭、脱敏导出及宿主限制;TaskFlow traceability 指向本归档、日志范围和 `hkwuks/TaskFlow` 的 `main`;Verification 填入独立分支复测、技能校验、diff 检查和 Hooks 工作流;Review boundaries 核对敏感信息、无关变更、目标及限制。Hooks 只由 PR 或 main push 触发,须先创建 PR 才能取得该 PR 的 CI 结果,结果未到时保持待完成并回填。 + +- PR 首次 Windows CI 因测试使用 PowerShell 字符串管道,环境编码在 JSON 前插入 BOM,导致 SessionStart 的输入解析失败;改用 `cmd` 的空 stdin,继续检查两种 shell 中的实际 hook 命令。Linux 和 macOS CI 已通过;修复后的 CI 须重新通过。 + +## Change Log + +- 2026-11-13:用户确定默认关闭、本地指定路径导出、仅允许列表元数据;日志不阻塞被观察代码。 +- 2026-11-13:实现固定类别的命令提及识别,只保存枚举,不保存命令;与已批准范围一致,属于工作修订。 +- 2026-11-13:为单独交付已验收日志,从已核实的 main 分出 PR 分支,移植必要的 Windows hook 启动修复与日志提交;另一任务和其待办继续留在原分支。 + +## Follow-ups + +## Version History + +- v1 — planning。 diff --git a/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/prd.md b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/prd.md new file mode 100644 index 0000000..1a652a7 --- /dev/null +++ b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/prd.md @@ -0,0 +1,52 @@ +# TaskFlow 脱敏诊断日志与导出 +> Task version: v1 +> Status: completed + +## Goal + +为正式安装后的能力引导调查提供用户可控的诊断日志和本地导出。 + +## Task Kind + +- Kind: capability + +## Background / Confirmed Facts + +能力引导任务发现,Codex 的事件接线只能观察宿主提供的部分事件;通过 shell 读取技能不一定有可识别的技能调用事件。事件、模型决策和产物贡献不能互相等同。 + +## Requirements + +- 日志默认关闭,由用户主动开启和关闭;不自动上传。 +- 严格允许列表:仅可记录预定义的事件类型、结果、时间和经过允许列表筛选的能力标识;不记录提示词、命令、路径、代码、个人信息、密钥、工具输入输出或自由文本。 +- 日志写入或其故障不得阻塞被观察代码;明确丢失或不可观察的边界。 +- 用户可导出至指定本地文件;导出时再次校验允许的格式和字段,不读取或打包其他文件。 +- 区分 hook 到达、宿主可观察的调用事件及失败,不臆测模型内部原因或技能实际贡献。 + +## Acceptance Criteria + +- 默认关闭不产生诊断记录;启用、停用、导出在正式安装的使用方式中可操作且有说明。 +- 合成输入中嵌入代码、路径、令牌、个人信息及恶意字段后,本地日志和导出均不包含这些内容;未知字段、标识或记录不会原样落盘或导出。 +- 日志存储不可用、写入阻塞或后台进程失败时,受观察工作仍能完成;使用真实可控阻塞场景验证。 +- 真实或受控宿主事件验证 hook 到达和可观察调用;未被宿主暴露的行为明确标记为未知,而非未调用。 +- 导出只写用户指定目标,不自动发送网络;覆盖、失败和敏感数据边界有测试。 + +## External Facts + +- Depends on external facts: no +- Why not: 已有接线与能力范围见 `hooks/hooks-codex.json`、`hooks/capability-evidence`;实现不依赖其他宿主未验证的承诺。 + +## In Scope + +日志配置、脱敏事件记录、本地导出、测试和使用说明。 + +## Out of Scope + +记录用户代码或完整会话;推断模型内部意图;自动上传;替代现有能力门禁或假定覆盖所有宿主事件。 + +## Risks / Deferred Items + +异步记录可能丢失事件;默认关闭的时间段不可追溯;宿主未暴露的调用无法被日志证明。 + +## Open Questions + +具体宿主可见事件及其失败语义以实现前逐项核实为准,不得虚构。 diff --git a/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/spec.md b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/spec.md new file mode 100644 index 0000000..bcc4a98 --- /dev/null +++ b/TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/spec.md @@ -0,0 +1,40 @@ +# Spec — TaskFlow 脱敏诊断日志与导出 +> Task version: v1 + +## Objective and Success Criteria + +以最小可观测元数据诊断真实宿主事件,并提供明确、可测试的隐私和非阻塞边界。 + +## Architecture Boundaries and Responsibilities + +宿主负责实际投递事件,TaskFlow 仅记录接收到的已知事件;记录器不读取会话或其他日志,不推断模型思维。导出只处理本模块的结构化数据并重新校验。 + +## Project Structure / Affected Files + +复用 `hooks/` 及各宿主现有事件接线;按实际需要补充日志命令、自动测试、TaskFlow skill 和中英文 README。不得修改用户 Agent 配置目录。 + +## Interfaces, Data Flow, and Contracts + +提供用户可发现的启用、停用和导出命令。默认无配置视为关闭;启用状态与日志存放于任务工作区的本地 Git 元数据,不进入 Git 提交。事件进入记录器前必须降为固定枚举;未知值统一归为 unknown 或丢弃,绝不保存原值。能力标识只有硬编码允许值可写,其余使用类别或 unknown,不将任意宿主名字、路径或哈希作为安全替代。 + +记录采用结构化单行格式,字段和可取值均严格白名单;时间仅由记录器生成。绝不将原始输入、错误消息或命令参数写入。导出重新解析并重建允许字段,拒绝或跳过异常记录;目标已存在时不覆盖,失败不留下看似成功的导出。 + +## Invariants and Compatibility + +日志记录是可选、异步且可丢失的旁路;日志输出的任何磁盘 IO 或等待不得发生在受观察执行路径。不得依赖新增的兼容代码或外部依赖。仅对实际宿主提供且验证的事件声称覆盖。 + +## Validation and Error Semantics + +测试包含默认关闭、启停、导出与已有目标、结构化允许列表、带令牌和私人信息的输入、篡改的本地记录、并发、不可写存储和可控长时间阻塞的写入;验证被观察流程及时完成且输出未变。测量和记录受控真实宿主投递,明确无法证明 skill 内容已采纳或解释未观察到的调用。 + +## Code and Test Constraints + +复用既有测试框架;不接触用户个人文件或凭据。运行适用 smoke、离线评估及 `git diff --check`,如宿主或环境不可用则保留未验证状态。 + +## Design Decisions and Alternatives + +选择默认关闭、固定枚举、用户指定本地导出;较宽泛的正则脱敏不能保证未知密钥和代码安全,因此不将原始内容交给日志存储。诊断所需的细节与严格隐私冲突时保留隐私边界并公开可观察性限制。 + +## Open Questions + +不同宿主的异步投递和事件字段需先以现有运行时实现及验证结果确定;不以静态配置代替真实宿主验证。 diff --git a/TaskFlowDocs/todo.md b/TaskFlowDocs/todo.md index 95bb998..d37a583 100644 --- a/TaskFlowDocs/todo.md +++ b/TaskFlowDocs/todo.md @@ -1257,3 +1257,10 @@ has an issue number or URL. - Task: `TaskFlowDocs/achieved/2026-10-31-external-facts/` - Next action: None — completed and archived. +## 增加脱敏且不阻塞运行的 TaskFlow 诊断日志和用户导出能力, + +- ID: TF-20261113-5681c7 +- Status: done +- Goal: 增加脱敏且不阻塞运行的 TaskFlow 诊断日志和用户导出能力,用于正式安装后调查能力引导与调用问题 +- Task: `TaskFlowDocs/achieved/2026-11-13-diagnostic-logs/` +- Next action: None — completed and archived. diff --git a/hooks/README.md b/hooks/README.md index 5205812..b02abef 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -19,6 +19,9 @@ taskflow/hooks/ ├── merge-todo # the driver: merges TaskFlowDocs/todo.md by entry ├── summarize-state # derives the state summary (shared logic) ├── repository-docs-context # syncs index metadata and derives routes +├── diagnostic-event # launches the best-effort redacted event worker +├── diagnostic-log # enables, disables and exports diagnostic records +├── test-diagnostic-log # privacy, export and nonblocking fixture ├── capability-evidence # records observable capability invocations ├── external-evidence # records outside URLs from tool events ├── capability-gate # refuses a stage document's first body write diff --git a/hooks/diagnostic-event b/hooks/diagnostic-event new file mode 100644 index 0000000..e2e6da9 --- /dev/null +++ b/hooks/diagnostic-event @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# Diagnostic writes run in a detached worker; the hook itself does no log I/O. +set -u +HERE="$(cd "$(dirname "$0")" && pwd)" +if [ "${1:-}" != worker ]; then + bash "$HERE/diagnostic-event" worker <&0 >/dev/null 2>&1 & + exit 0 +fi +umask 077 +payload="$(cat)" || exit 0 +field() { printf '%s' "$payload" | bash "$HERE/json-field" "$1" 2>/dev/null; } +root="$(field cwd)" || exit 0 +[ -n "$root" ] || root="$PWD" +gitdir="$(git -C "$root" rev-parse --absolute-git-dir 2>/dev/null)" || exit 0 +store="$gitdir/taskflow/diagnostics" +[ ! -L "$gitdir/taskflow" ] && [ ! -L "$store" ] || exit 0 +[ -f "$store/enabled" ] && [ ! -L "$store/enabled" ] || exit 0 +[ "$(cat "$store/enabled" 2>/dev/null)" = on ] || exit 0 +[ ! -L "$store/events" ] || exit 0 +[ ! -e "$store/events" ] || [ -f "$store/events" ] || exit 0 +name="$(field hook_event_name)" || exit 0 +tool="$(field tool_name)" || exit 0 +case "$name" in + SessionStart) event=session; result=observed; kind=none ;; + UserPromptSubmit) event=prompt; result=observed; kind=none ;; + SubagentStart) event=agent; result=observed; kind=agent ;; + PostToolUse|PostToolUseFailure) + event=tool + case "$name" in PostToolUse) result=observed ;; *) result=failed ;; esac + case "$tool" in Skill|skill) kind=skill ;; Agent|Task) kind=agent ;; mcp__*) kind=mcp ;; Bash|PowerShell|shell|shell_command|exec_command) kind=shell ;; *) kind=other ;; esac ;; + *) exit 0 ;; +esac +capability=unknown +if [ "$kind" = skill ]; then + skill="$(field tool_input.skill)" || exit 0 + [ -n "$skill" ] || skill="$(field tool_input.name)" || exit 0 + case "$skill" in + agent-skills:spec-driven-development) capability=spec ;; + agent-skills:idea-refine) capability=brainstorm ;; + agent-skills:planning-and-task-breakdown) capability=planning ;; + agent-skills:code-review-and-quality) capability=review ;; + esac +elif [ "$kind" = shell ]; then + command="$(field tool_input.command)" || exit 0 + [ -n "$command" ] || command="$(field tool_input.cmd)" || exit 0 + case "$command" in + *spec-driven-development*) capability=spec_mention ;; + *idea-refine*) capability=brainstorm_mention ;; + *planning-and-task-breakdown*) capability=planning_mention ;; + *code-review-and-quality*) capability=review_mention ;; + esac +fi +# Bounded growth: drop new events after the limit rather than delete logs. +if [ -f "$store/events" ]; then + bytes="$(wc -c < "$store/events" 2>/dev/null)" || exit 0 + [ "$bytes" -lt 1048576 ] || exit 0 +fi +stamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)" || exit 0 +printf '%s|%s|%s|%s|%s\n' "$stamp" "$event" "$result" "$kind" "$capability" >> "$store/events" 2>/dev/null || : +exit 0 diff --git a/hooks/diagnostic-log b/hooks/diagnostic-log new file mode 100644 index 0000000..29e00fd --- /dev/null +++ b/hooks/diagnostic-log @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# User-controlled, worktree-local diagnostic logging and export. +set -euo pipefail +umask 077 +usage() { echo 'Usage: bash hooks/diagnostic-log enable|disable|export ' >&2; exit 2; } +[ "$#" -ge 1 ] || usage +command="$1"; shift +case "$command" in enable|disable) [ "$#" -eq 0 ] || usage ;; export) [ "$#" -eq 1 ] || usage ;; *) usage ;; esac +gitdir="$(git rev-parse --absolute-git-dir)" +store="$gitdir/taskflow/diagnostics" +[ ! -L "$gitdir/taskflow" ] && [ ! -L "$store" ] || { echo 'Invalid diagnostic directory' >&2; exit 1; } +case "$command" in + enable) + mkdir -p "$store" + [ ! -L "$store/enabled" ] && { [ ! -e "$store/enabled" ] || [ -f "$store/enabled" ]; } || { echo 'Invalid diagnostic control file' >&2; exit 1; } + printf 'on\n' > "$store/enabled" + echo 'TaskFlow diagnostics enabled.' ;; + disable) + [ -d "$store" ] || { echo 'TaskFlow diagnostics already disabled.'; exit 0; } + [ ! -L "$store/enabled" ] && { [ ! -e "$store/enabled" ] || [ -f "$store/enabled" ]; } || { echo 'Invalid diagnostic control file' >&2; exit 1; } + printf 'off\n' > "$store/enabled" + echo 'TaskFlow diagnostics disabled.' ;; + export) + [ -f "$store/events" ] && [ ! -L "$store/events" ] || { echo 'No diagnostic events available.' >&2; exit 1; } + target="$1" + [ ! -e "$target" ] && [ ! -L "$target" ] || { echo 'Cannot create export; choose a new file.' >&2; exit 1; } + tmp="$(mktemp "${target}.taskflow.XXXXXXXX")" || { echo 'Cannot create export.' >&2; exit 1; } + trap 'rm -f -- "$tmp"' EXIT + awk -F'|' ' + NF == 5 && $1 ~ /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[0-9][0-9]:[0-9][0-9]:[0-9][0-9]Z$/ && + ($2 == "session" || $2 == "prompt" || $2 == "agent" || $2 == "tool") && + ($3 == "observed" || $3 == "completed" || $3 == "failed") && + ($4 == "none" || $4 == "agent" || $4 == "skill" || $4 == "mcp" || $4 == "shell" || $4 == "other") && + ($5 == "unknown" || $5 == "spec" || $5 == "brainstorm" || $5 == "planning" || $5 == "review" || $5 == "spec_mention" || $5 == "brainstorm_mention" || $5 == "planning_mention" || $5 == "review_mention") { + printf "{\"time\":\"%s\",\"event\":\"%s\",\"result\":\"%s\",\"kind\":\"%s\",\"capability\":\"%s\"}\n", $1,$2,$3,$4,$5 + } + ' "$store/events" > "$tmp" || { echo 'Cannot prepare export.' >&2; exit 1; } + # A hard link publishes the complete file without replacing an existing target. + ln "$tmp" "$target" 2>/dev/null || { echo 'Cannot create export; choose a new file.' >&2; exit 1; } + echo 'TaskFlow diagnostics exported.' ;; +esac diff --git a/hooks/hooks-codebuddy.json b/hooks/hooks-codebuddy.json index 935c3e6..4f6fe98 100644 --- a/hooks/hooks-codebuddy.json +++ b/hooks/hooks-codebuddy.json @@ -11,6 +11,15 @@ "timeout": 15 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CODEBUDDY_PLUGIN_ROOT}/hooks/diagnostic-event\"", + "timeout": 15 + } + ] } ], "UserPromptSubmit": [ @@ -22,6 +31,15 @@ "timeout": 15 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CODEBUDDY_PLUGIN_ROOT}/hooks/diagnostic-event\"", + "timeout": 15 + } + ] } ], "PreToolUse": [ @@ -65,6 +83,15 @@ "timeout": 15 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${CODEBUDDY_PLUGIN_ROOT}/hooks/diagnostic-event\"", + "timeout": 15 + } + ] } ] } diff --git a/hooks/hooks-codex.json b/hooks/hooks-codex.json index 20ae0b6..90dad1f 100644 --- a/hooks/hooks-codex.json +++ b/hooks/hooks-codex.json @@ -8,7 +8,16 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/session-start\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" session-start" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" session-start" + } + ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${PLUGIN_ROOT}/hooks/diagnostic-event\"", + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" diagnostic-event" } ] } @@ -19,7 +28,16 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/capability-evidence\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-evidence" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-evidence" + } + ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${PLUGIN_ROOT}/hooks/diagnostic-event\"", + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" diagnostic-event" } ] } @@ -30,7 +48,16 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/prompt-reminder\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" prompt-reminder" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" prompt-reminder" + } + ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${PLUGIN_ROOT}/hooks/diagnostic-event\"", + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" diagnostic-event" } ] } @@ -42,7 +69,7 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/capability-gate\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-gate" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-gate" } ] } @@ -54,7 +81,7 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/capability-evidence\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-evidence" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" capability-evidence" } ] }, @@ -64,7 +91,7 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/base-status-reminder\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" base-status-reminder", + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" base-status-reminder", "async": true } ] @@ -74,7 +101,16 @@ { "type": "command", "command": "bash \"${PLUGIN_ROOT}/hooks/external-evidence\"", - "commandWindows": "\"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" external-evidence" + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" external-evidence" + } + ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash \"${PLUGIN_ROOT}/hooks/diagnostic-event\"", + "commandWindows": "cmd.exe /d /c call \"${PLUGIN_ROOT}\\hooks\\run-hook.cmd\" diagnostic-event" } ] } diff --git a/hooks/hooks-dsh.json b/hooks/hooks-dsh.json index 6f95009..6fdcec9 100644 --- a/hooks/hooks-dsh.json +++ b/hooks/hooks-dsh.json @@ -10,6 +10,14 @@ "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' diagnostic-event" + } + ] } ], "UserPromptSubmit": [ @@ -20,6 +28,14 @@ "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' prompt-reminder" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' diagnostic-event" + } + ] } ], "PreToolUse": [ @@ -50,6 +66,14 @@ "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' external-evidence" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}' bash '${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' diagnostic-event" + } + ] } ] } diff --git a/hooks/hooks-trae.json b/hooks/hooks-trae.json index 0f8aae3..807ca4a 100644 --- a/hooks/hooks-trae.json +++ b/hooks/hooks-trae.json @@ -12,6 +12,15 @@ "timeout": 30 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash '/hooks/run-hook.cmd' diagnostic-event", + "timeout": 30 + } + ] } ], "UserPromptSubmit": [ @@ -23,6 +32,15 @@ "timeout": 30 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash '/hooks/run-hook.cmd' diagnostic-event", + "timeout": 30 + } + ] } ], "PreToolUse": [ @@ -66,6 +84,15 @@ "timeout": 30 } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash '/hooks/run-hook.cmd' diagnostic-event", + "timeout": 30 + } + ] } ] } diff --git a/hooks/hooks.json b/hooks/hooks.json index 9d94a0f..fb0c738 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -11,6 +11,15 @@ "shell": "bash" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" diagnostic-event", + "shell": "bash" + } + ] } ], "UserPromptSubmit": [ @@ -22,6 +31,15 @@ "shell": "bash" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" diagnostic-event", + "shell": "bash" + } + ] } ], "PreToolUse": [ @@ -58,6 +76,15 @@ "async": true } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" diagnostic-event", + "shell": "bash" + } + ] } ], "PostToolUse": [ @@ -91,6 +118,15 @@ "shell": "bash" } ] + }, + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" diagnostic-event", + "shell": "bash" + } + ] } ] } diff --git a/hooks/smoke-test b/hooks/smoke-test index 7b9f320..c147410 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -30,6 +30,7 @@ if [ $# -eq 0 ]; then fi bash "$HERE/test-version-baseline" "$tmp/version-baseline-fixture" +bash "$HERE/test-diagnostic-log" "$tmp/diagnostic-fixture" echo "== completion-gate decides the one shared answer ==" # `archive`, `task complete`, `task state in_progress` and `task progress` all @@ -6948,6 +6949,20 @@ grep -q -F -- 'lowercase' "$HERE/../skills/taskflow/references/runtime.md" \ || { echo "FAIL runtime.md no longer states the dsh tool-name reason"; exit 1; } echo ok +echo "== diagnostic events are wired to the intended host events ==" +for diagnostic_config in hooks.json hooks-codex.json hooks-codebuddy.json hooks-dsh.json hooks-trae.json; do + diagnostic_events='SessionStart UserPromptSubmit PostToolUse' + case "$diagnostic_config" in hooks.json) diagnostic_events="$diagnostic_events PostToolUseFailure" ;; hooks-codex.json) diagnostic_events="$diagnostic_events SubagentStart" ;; esac + for diagnostic_event in $diagnostic_events; do + awk -v wanted="$diagnostic_event" ' + /^ "[[:alnum:]]+": \[/ { active = ($0 ~ "^ \"" wanted "\": \\[") } + active && /"command":.*diagnostic-event/ { found = 1 } + END { exit !found } + ' "$HERE/$diagnostic_config" || { echo "FAIL $diagnostic_config lacks diagnostic hook for $diagnostic_event"; exit 1; } + done +done +echo ok + echo "== every host whose contract matches the gate actually wires it ==" # Measured 2026-10-11: `task approve` requires a release record, and the gate was # its only writer. A host wiring no tool-call event therefore had no gate, no @@ -6971,7 +6986,7 @@ for cb_pat in '"PreToolUse"' '"matcher": "Write|Edit"' '"PostToolUse"' '"matcher || { echo "FAIL hooks/hooks-codebuddy.json is missing $cb_pat"; exit 1; } done cb_cmds="$(sed -n 's/.*"command": *"\(.*\)".*/\1/p' "$cb_json" | sed 's/\\"/"/g')" -[ "$(printf '%s\n' "$cb_cmds" | grep -c .)" -eq 6 ] \ +[ "$(printf '%s\n' "$cb_cmds" | grep -v -F diagnostic-event | grep -c .)" -eq 6 ] \ || { echo "FAIL hooks/hooks-codebuddy.json should wire six hook commands (SessionStart, UserPromptSubmit, PreToolUse, Skill, MCP, external-evidence):"; printf '%s\n' "$cb_cmds"; exit 1; } cb_root="$(cd "$HERE/.." && pwd)" cb_run() { # cb_run @@ -7101,7 +7116,7 @@ trae_root="$(cd "$HERE/.." && pwd)" # them: left in, `\"path\"` reaches the shell as a word whose characters include # two quote marks, and sh reports "not found" for a path that exists. trae_cmds="$(sed -n 's/.*"command": *"\(.*\)".*/\1/p' "$trae_json" | sed 's/\\"/"/g')" -[ "$(printf '%s\n' "$trae_cmds" | grep -c .)" -eq 6 ] \ +[ "$(printf '%s\n' "$trae_cmds" | grep -v -F diagnostic-event | grep -c .)" -eq 6 ] \ || { echo "FAIL hooks/hooks-trae.json should wire six hook commands (SessionStart, UserPromptSubmit, PreToolUse, Skill, MCP, external-evidence):"; printf '%s\n' "$trae_cmds"; exit 1; } printf '%s\n' "$trae_cmds" | grep -q "CLAUDE_PLUGIN_ROOT=''" \ || { echo "FAIL hooks/hooks-trae.json does not set CLAUDE_PLUGIN_ROOT: Trae would discard the SessionStart context silently"; exit 1; } diff --git a/hooks/smoke-test-windows.ps1 b/hooks/smoke-test-windows.ps1 index 93220f7..3d01f23 100755 --- a/hooks/smoke-test-windows.ps1 +++ b/hooks/smoke-test-windows.ps1 @@ -75,6 +75,24 @@ try { } 'WINDOWS SCRIPT IS ASCII' + if ($env:TASKFLOW_STDIN_SELFCHECK -ne '1') { + # Exercise the configured commands, not only the launcher invoked directly. + $codexHooks = [IO.File]::ReadAllText((Join-Path $here 'hooks-codex.json')) | ConvertFrom-Json + foreach ($event in $codexHooks.hooks.PSObject.Properties) { + foreach ($group in $event.Value) { + foreach ($handler in $group.hooks) { + $configured = $handler.commandWindows.Replace('${PLUGIN_ROOT}', (Split-Path -Parent $here)) + $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($configured)) + $shellOutput = & cmd.exe /d /c "powershell.exe -NoProfile -NonInteractive -EncodedCommand $encoded < nul" 2>&1 + if ($LASTEXITCODE -ne 0) { throw "Codex Windows hook $($event.Name) failed to launch: $shellOutput" } + $shellOutput = & cmd.exe /d /s /c "$configured < nul" 2>&1 + if ($LASTEXITCODE -ne 0) { throw "Codex cmd hook $($event.Name) failed to launch: $shellOutput" } + } + } + } + 'CODEX WINDOWS HOOK COMMANDS PASSED' + } + $launcherArgs = @('space value', ([string]([char]0x4E2D) + [char]0x6587), 'quoted value', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten') $launcherOutput = @(& "$here\run-hook.cmd" smoke-test --echo-args @launcherArgs 2>&1) if ($LASTEXITCODE -ne 0) { throw "Launcher argument check failed: $launcherOutput" } @@ -319,6 +337,9 @@ try { # if ($env:TASKFLOW_STDIN_SELFCHECK -ne '1') { $parityRoot = Join-Path $Root 'host-parity' + $diagnosticRoot = Join-Path $Root 'diagnostic-fixture' + & "$here\run-hook.cmd" test-diagnostic-log $diagnosticRoot + if ($LASTEXITCODE -ne 0) { throw 'Diagnostic log test failed' } & "$here\run-hook.cmd" test-host-parity $parityRoot if ($LASTEXITCODE -ne 0) { throw 'host parity fixture failed' } } @@ -328,7 +349,8 @@ try { $self = $MyInvocation.MyCommand.Path $psi = New-Object Diagnostics.ProcessStartInfo $psi.FileName = (Get-Command powershell.exe).Source - $psi.Arguments = '-NoProfile -ExecutionPolicy Bypass -File "' + $self + '"' + $childRoot = Join-Path $Root 'stdin-selfcheck' + $psi.Arguments = '-NoProfile -ExecutionPolicy Bypass -File "' + $self + '" -Root "' + $childRoot + '"' $psi.RedirectStandardInput = $true # a pipe nobody writes or closes $psi.RedirectStandardOutput = $true $psi.RedirectStandardError = $true diff --git a/hooks/test-diagnostic-log b/hooks/test-diagnostic-log new file mode 100644 index 0000000..0f077df --- /dev/null +++ b/hooks/test-diagnostic-log @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +root="${1:?pass an empty project-local fixture directory}" +mkdir -p "$root" +root="$(cd "$root" && pwd)" +git -C "$root" init -q +mkdir -p "$root/TaskFlowDocs" +cd "$root" +secret='sk_test_SUPERSECRET_user@example.com_PRIVATE_CODE' +event='{"hook_event_name":"PostToolUse","tool_name":"mcp__secret_'"$secret"'","cwd":"'"$root"'","tool_input":{"command":"'"$secret"'"}}' +# An event while disabled must not create diagnostic storage. +printf '%s' "$event" | bash "$HERE/diagnostic-event" worker +[ ! -e "$root/.git/taskflow/diagnostics/events" ] +bash "$HERE/diagnostic-log" enable +printf '%s' "$event" | bash "$HERE/diagnostic-event" worker +# Exercise the real detached entry point and wait only in this test. +printf '%s' "$event" | bash "$HERE/diagnostic-event" +for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do + [ "$(wc -l < "$root/.git/taskflow/diagnostics/events")" -ge 2 ] && break + sleep 0.2 +done +[ "$(wc -l < "$root/.git/taskflow/diagnostics/events")" -ge 2 ] +# A fixed skill can be identified, while arbitrary identifiers are never stored. +skill_event='{"hook_event_name":"PostToolUse","tool_name":"Skill","cwd":"'"$root"'","tool_input":{"skill":"agent-skills:spec-driven-development"}}' +printf '%s' "$skill_event" | bash "$HERE/diagnostic-event" worker +mention_event='{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"'"$root"'","tool_input":{"command":"read spec-driven-development '"$secret"'"}}' +printf '%s' "$mention_event" | bash "$HERE/diagnostic-event" worker +for i in 1 2 3 4; do printf '%s' "$event" | bash "$HERE/diagnostic-event" worker & done +wait +[ "$(wc -l < "$root/.git/taskflow/diagnostics/events")" -ge 4 ] +# Concurrent best-effort writers may lose records, but may not produce partial records. +awk -F'|' 'NF != 5 { exit 1 }' "$root/.git/taskflow/diagnostics/events" +! grep -F "$secret" "$root/.git/taskflow/diagnostics/events" +# Tampered records and arbitrary event values must never be exported. +printf '%s\n' "2026-11-13T00:00:00Z|tool|observed|skill|$secret" "$secret" >> "$root/.git/taskflow/diagnostics/events" +bash "$HERE/diagnostic-log" export "$root/export.jsonl" +[ -s "$root/export.jsonl" ] +! grep -F "$secret" "$root/export.jsonl" +grep -F '"event":"tool"' "$root/export.jsonl" >/dev/null +grep -F '"capability":"spec"' "$root/export.jsonl" >/dev/null +grep -F '"capability":"spec_mention"' "$root/export.jsonl" >/dev/null +! bash "$HERE/diagnostic-log" export "$root/export.jsonl" >/dev/null 2>&1 +bash "$HERE/diagnostic-log" disable +before="$(wc -c < "$root/export.jsonl")" +printf '%s' "$event" | bash "$HERE/diagnostic-event" worker +bash "$HERE/diagnostic-log" export "$root/export2.jsonl" +[ "$(wc -c < "$root/export2.jsonl")" = "$before" ] +# A deliberately slow Git process runs only in the worker, not the hook. +mkdir "$root/slow-bin" +printf '#!/usr/bin/env bash\nsleep 5\nexit 1\n' > "$root/slow-bin/git" +chmod +x "$root/slow-bin/git" +probe_nonblocking() { + local bin="$1" probe i + printf '%s' "$event" | PATH="$bin:$PATH" bash "$HERE/diagnostic-event" & + probe=$! + for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do + if ! kill -0 "$probe" 2>/dev/null; then wait "$probe"; return; fi + sleep 0.1 + done + kill "$probe" 2>/dev/null || : + wait "$probe" 2>/dev/null || : + echo 'FAIL diagnostic hook blocked' >&2; return 1 +} +probe_nonblocking "$root/slow-bin" +mkdir "$root/slow-write-bin" +printf '#!/usr/bin/env bash\nsleep 5\nexit 1\n' > "$root/slow-write-bin/wc" +chmod +x "$root/slow-write-bin/wc" +bash "$HERE/diagnostic-log" enable +probe_nonblocking "$root/slow-write-bin" +bash "$HERE/diagnostic-log" disable +echo 'DIAGNOSTIC TEST PASSED' diff --git a/skills/taskflow/SKILL.md b/skills/taskflow/SKILL.md index 7a26636..cd5d96d 100644 --- a/skills/taskflow/SKILL.md +++ b/skills/taskflow/SKILL.md @@ -429,3 +429,7 @@ Before declaring a task complete, confirm: - [ ] Validation results and failure classification are in `plan.md`. - [ ] Scope, sensitive-data, and concurrent-write checks passed. - [ ] Completion gates passed before moving to `TaskFlowDocs/achieved/`. + +## Optional diagnostics + +When a user asks to enable, disable, or export TaskFlow diagnostic logs, run the installed plugin's `hooks/diagnostic-log` from the affected repository. Derive the plugin root from this skill's installed `SKILL.md` location, not from the user's repository. Use `enable`, `disable`, or `export ` respectively. Logging is off by default and does not upload. Logs contain only allowlisted event categories, results, timestamps and fixed capability categories; they exclude prompts, commands, paths, code, personal information and tool outputs. Recording is asynchronous and can lose events. Fixed skill-name mentions in shell commands are classified without retaining commands; mentions do not prove a successful read. An absent event does not prove that a capability was not used or explain the model's decision. diff --git a/skills/taskflow/references/runtime.md b/skills/taskflow/references/runtime.md index 8e1ce94..5bb5a91 100644 --- a/skills/taskflow/references/runtime.md +++ b/skills/taskflow/references/runtime.md @@ -382,6 +382,9 @@ repo-root/ ├── install-git-hygiene # per-clone Git config: Todo merge driver + local-file excludes ├── merge-todo # the driver: merges todo.md by entry ├── repository-docs-context # syncs index metadata + derives routes + ├── diagnostic-event # asynchronous allowlisted event recording + ├── diagnostic-log # user-controlled enable, disable, export + ├── test-diagnostic-log # privacy and nonblocking fixture ├── capability-evidence # records real invocations in the worktree store ├── external-evidence # records outside URLs from any tool event, in a separate store ├── capability-gate # refuses a stage document's first body write