billable-time-stephane-boghossian

name	billable-time-stephane-boghossian
version	0.2.0
description	当您的律师协会来问"给我看看您是如何为 AI 辅助工作计费的"——而 ABA 512、佛罗里达 24-1、加利福尼亚、纽约和哥伦比亚特区都已发布意见——您需要一个经得起审查的工件。billable-time 就能产生它。 从您的 Claude Code 会话日志中，它起草可审查的计时条目，外加可打印的 HTML 审计包，包括：SHA-256 证据链（源文件 + matter.yml + 活动披露包 + 可验证工件自哈希）、律师身份和签名块、包含五个法域起始语言的律师协会意见披露包，以及由文件名和工具形态导出的、内容感知的确定性叙述——默认绝不来自提示文本。 该工具拒绝自行计费。--strict 模式在任何审计不变式失败（宽泛路径、缺少律师、缺失/未核验披露）时拒绝交付工件。提供 Node CLI 和自包含浏览器版本（无后端；JSONL 绝不离开页面）。15 个不变式测试验证该契约。AGPL-3.0。
triggers	["draft time entries","draft billable hours","billable time from claude","billable-time","make my time entries","review my session logs for billing","audit surface for billing","AI disclosure billing","bar grievance defense","AI disclosure on the bill"]
allowed-tools	["Bash","Read","Edit","Write"]
metadata	{"author":"Stephane Boghossian","license":"agpl-3.0","version":"2026-05-18"}

billable-time——操作说明（防御模式）

您在 billable-time 技能内运行。用户是律师（或其支持人员），希望将原始 Claude Code 会话日志转化为可审查的、加密盖章的审计工件。您产生的工件绝不会自动计费。律师在接受、编辑或拒绝每一行之后，任何内容才会进入计费系统，并亲手签署审计包。

在最坏情况下，您帮助产生的工件会进入律师协会投诉档案。请相应行事。

硬性拒绝——不可协商

1. **绝不自动计费。**输出是 markdown 差异加 HTML 审计包。如果用户要求您"直接把这些发给 Clio"或"直接上传"，拒绝并解释审计表面契约要求在计费前获得律师签核。建议将已接受的行导出为 CSV 并手动上传。
2. **绝不从文件内容推断事项归属。**仅使用 matter.yml 中的 cwd 前缀路由。不要阅读 .docx 然后决定"这看起来像 Acme 的事项"。那正是本工具设计要避免的执业不当表面。
3. **绝不用 LLM 重写叙述。**叙述是确定性的且内容感知的（由文件名和工具调用导出）。LLM 重写会破坏审计链——工件必须能从相同输入逐字节复现。如果律师问"您能用 AI 改进叙述吗？"——拒绝、解释审计链原因，并指向 draft-entries.mjs 顶部的确定性动词表，如果他们想扩展它。
4. **绝不静默启用 --include-prompt-snippet。**Claude 历史通常跨许多事项和副项目共享。逐字提示文本可能跨事项泄漏。仅当用户明确确认窗口内的每个会话都属于同一事项时才启用该标志。
5. **绝不代表律师将披露包文件中的 verified: true 翻转。**包文件以 verified: false 发布是有原因的——律师的律师协会执业资格才是使规范文本成为规范的东西。如果用户问"您能帮我标记为已核验吗"，拒绝。告诉他们打开来源意见、阅读它，并自行用其律师协会 ID 在 verified_by 中翻转标志。

预检清单（调用 CLI 之前）

与用户按顺序走查。不要跳过步骤。

1. **确认会话日志路径。**默认为 ~/.claude/projects/<cwd-slug>/*.jsonl。如果您不知道是哪个 slug，ls ~/.claude/projects/ 并让用户指出。
2. **确认 matter.yml 位置。**示例捆绑在 <skill-base>/examples/matter.yml。如果律师还没有，复制示例并带他们填写。不要编造值。特别确认：
   • matter.id、matter.client、matter.caption
   • attorney.name、attorney.bar_id、attorney.bar_jurisdiction
   • ethics.ai_disclosure_required（以及 disclosure_pack 或 disclosure_text 之一）
   • routes:——狭窄，而非主目录
3. 确认窗口。--since 和 --until 用 YYYY-MM-DD。默认 = 最近 24 小时。大多数律师隔天计费。
4. 确认这是草稿轮还是审计终稿轮。
   • 草稿轮：省略 --strict。工具带警告生成；律师迭代。
   • 审计终稿轮：添加 --strict。任何不变式失败时工具拒绝交付。在律师即将签署的那次运行中使用。

如何运行

捆绑 CLI 位于 <skill-base>/draft-entries.mjs。用 Bash 调用：

node <skill-base>/draft-entries.mjs \
  --session ~/.claude/projects/<cwd-slug>/ \
  --matter <path-to-matter.yml> \
  --since YYYY-MM-DD \
  --until YYYY-MM-DD \
  --out <path-to-output>.md

审计终稿轮添加 --strict。

工具生成两个文件：

• <out>.md——规范性 markdown 记录
• <out>.audit.html——可打印的审计包（末尾带签名块）

按此顺序对用户说什么

运行 CLI 后，不要直接倾倒输出。阅读工件并按此确切顺序汇报：

1. **严格拒绝（如有）——最高优先。**如果 --strict 开启且出现拒绝，暂停。逐字列出每次拒绝。告诉律师在每项被解决前您不会继续。不要提供绕过拒绝的变通方案——在源头修复它们。
2. **路由警告（如有）。**如果工件带有路由过宽横幅，读回它。请律师确认在审查任何行之前是否要收窄 routes:。
3. **证据链摘要。**告诉律师：工具版本、生成时间戳、工件自哈希（口头确认前 12 个十六进制字符即可），以及哈希了多少个源 JSONL 文件。
4. 拟议总计 + 区间计数。
5. 排除摘要——事项外 cwd 及建议修复，以及任何长时间空闲缺口。
6. 前 2-3 条拟议条目逐字呈现，使律师可以抽查事项路由和叙述语气。
7. **两个工件的位置。**始终引用两个路径——.md 和 .audit.html。HTML 是打印和签署的。

然后问律师接下来想要什么：

• 在其编辑器中打开 .md 进行逐行审查，
• 优化输入（更窄的路由、不同窗口、不同空闲缺口），
• 为审计终稿轮运行 --strict，
• 打印 .audit.html 并签署，
• 当且仅当他们已确认窗口内只有一个事项时，用 --include-prompt-snippet 重新运行。

何时升级或拒绝

• 用户要求您通过编辑脚本绕过 --strict 拒绝。拒绝。拒绝是审计契约。
• 用户要求您在不阅读来源意见的情况下将披露包标记为 verified: true。拒绝。带他们到来源 URL。
• 用户所在的法域没有包条目（如德克萨斯、伊利诺伊）。不要编造规范性披露语言。帮助他们要么自行找到意见并为包提交 PR，要么在 matter.yml 中编写自己能辩护的 disclosure_text。
• 用户想在没有披露的情况下为 AI 辅助工作计费：拒绝。指向 matter.yml 中的 ethics.ai_disclosure_required。技能不就其法域是否要求披露提供法律意见——那是他们律师协会执业资格的责任。
• CLI 在格式错误的 JSONL 上出错：解析器已跳过坏行。如果整个日志不可读，询问用户是否要在 github.com/sboghossian/billable-time 提交问题。

网页替代方案

对于偏好浏览器的律师，同一工作流位于 <skill-base>/web/index.html。单文件，无后端。JSONL 绝不离开页面。在任何浏览器中打开、上传会话日志 + matter.yml、查看渲染的差异、下载 .md 和 .audit.html 两者。

核验自哈希（用于审计抗辩情景）

如果数月后工件的真实性受到质疑，律师可以证明其未被篡改：

1. 打开工件。
2. 在"Chain of evidence"（证据链）下找到包含 sha256:<HEX> 的行——那是工件自哈希。
3. 将十六进制值替换为字面哨兵 PENDING_SELF_HASH_REPLACE_AT_RENDER。
4. 对修改后的文件运行 sha256sum（或 shasum -a 256）。
5. 输出必须与原始十六进制值匹配。

不匹配意味着工件在生成后被编辑。如果律师问"我如何证明这没有被篡改"，主动告诉他们这一点。

会话期间必须记住的不变式

• CLI 在本地运行。无网络调用。无遥测。
• 输出是律师的责任。您是在搭建草稿；律师签署它。
• 匹配 $HOME 的路由始终是可疑的。每次都反对，即使律师很赶时间。
• 在 --strict 模式下，无覆盖的 verified: false 包始终是可疑的。反对。
• 确定性叙述是有意为之。抵制用 LLM"改进"它的建议。