@xgent-ai/skills 0.7.4 → 0.7.6

package/docs/codex-context-goal-guard.md

@@ -1,109 +0,0 @@
-# Codex goal 上下文收尾提醒
-
-当本地估算上下文使用率**严格超过阈值**（默认 65%，可配置）且当前根线程的 goal 为 `active` 时，本 hook 提醒 agent 收尾：更新已有任务记录、交接未完成项、按用户明确的暂停策略调用原生 goal 工具，再提醒用户自行新开对话。恰好等于阈值不触发。hook 只读取本地数据，不写进度、修改 goal 或创建对话。
-
-## 兼容范围与限制
-
-首期格式限定为 Codex CLI / App Server **0.160.0**。已验证环境为 macOS arm64、Python 3.13.7；运行服务标识及完整验收见 [M1 记录](plan/codex-context-goal-guard.records/M1.md)与 [M3 记录](plan/codex-context-goal-guard.records/M3.md)。Python 至少需要 3.9。后续 Codex 版本不自动视为兼容，未知格式会报告检测不可用。
-
-估算值来自当前会话最新完整 `token_count` 的 `last_token_usage.total_tokens / model_context_window`，可能滞后于 UI。累计 tokens、cached tokens 和 reasoning tokens 不重复加入。压缩或模型/窗口改变后，没有新统计时不沿用旧值。子 agent 跳过；fork 只读取自己的 goal。读取位置由真实 hook 输入和 `CODEX_HOME` 决定，未设置时使用 `~/.codex`。
-
-检查发生在同步 `PreToolUse` 和 `Stop` 边界；已经调度的调用可能完成，部分工具路径没有 tool hook。提醒依赖 agent 执行，不能强制暂停。首次 Stop 可以请求补做收尾，第二次仍未暂停时只告警；此告警不能阻止 goal 自动续跑。上述事件、信任及输出语义见 [官方 Hooks 文档](https://learn.chatgpt.com/docs/hooks)。
-
-## 获取与部署
-
-### 使用 install
-
-功能已接入 `install` 源码和 npm 打包清单，尚未发布到 npm。当前从本仓库根目录运行：
-
-```sh
-# 默认不安装 guard；需要时显式选择安装
-node bin/xgent-skills.js install /absolute/path/to/project --context-goal-guard
-```
-
-发布包含此功能的新版本后，可用 `npx @xgent-ai/skills install --context-goal-guard`。交互和非交互安装均默认跳过 guard，不再询问。仅在显式传入 `--context-goal-guard` 或 `--context-goal-guard-threshold=N` 时安装；`--no-context-goal-guard` 显式跳过并保留已有 guard，不能与安装参数同时使用。此选择独立于 `--providers`、`--no-phoenix-ui`（旧 `--no-impeccable` 为弃用别名）和 `--xgent-init`。
-
-请安装到目标 Git 仓库根目录。安装器检查 `python3` 为 3.9+ 且包含 SQLite 标准库，然后复制脚本到目标项目 `.codex/hooks/context-goal-guard.py`，将两个同步 handler 合并到 `.codex/hooks.json`，使用 `$(git rev-parse --show-toplevel)` 在运行时定位脚本，超时设为 3 秒，配置不包含本机项目绝对路径。其他事件、handler、matcher 和顶层字段保留；重复安装更新 guard，不重复添加，也会替换旧版 guard 的绝对路径命令。非法 JSON 默认报错，`--force` 可先备份为 `.bak` 再覆盖；合法 JSON 的未知结构需手动修复。
-
-Python 缺失或版本不足时，按安装器提示先安装 Python 并运行 `python3 --version` 核对，再重试；也可用 `--no-context-goal-guard` 完成其他安装。Codex 运行环境必须能解析 `git` 和 `python3`；后者无法解析时，按下方手动配置说明改为解释器绝对路径。
-
-安装结束会打印下方「信任与生效确认」的操作步骤及可复制的当前 goal 暂停策略。**脚本已部署不等于已生效**：用户仍需在 Codex 内信任项目、审阅并信任启用两个 handler、明确当前 goal 的暂停策略，并用测试 goal 验证真实暂停。安装器不代替用户完成这些步骤。
-
-### 阈值配置
-
-阈值写在 handler 命令末尾：`--threshold N`，N 为 1–99 的整数百分比；不带参数时为 65。与 Claude Code 版（默认 70）各自独立。
-
-```sh
-node bin/xgent-skills.js install /absolute/path/to/project --context-goal-guard-threshold=60
-```
-
-`--context-goal-guard-threshold=N` 同时表示安装，不再询问；与 `--no-context-goal-guard` 不能同时使用。安装器总是把阈值写进两个 handler 的 command，重装时不给这个 flag 就沿用已装的值；安装输出里可复制的暂停策略也使用实际阈值。改动 command 后需要在 `/hooks` 中重新审阅、信任。参数无效时 guard 报告检测不可用，不猜测数值。
-
-### 手动部署
-
-也可单独复制仓库文件。首期手动部署的精确本地验证 revision 记在 [M3 记录](plan/codex-context-goal-guard.records/M3.md)：在可访问该本地仓库的机器 clone 并 checkout 该 revision（该 revision 不含后续 install 集成）。远程发布后，才可从 `https://github.com/XGENT-ai/skills.git` checkout 对应已发布 revision；不要将尚未发布的 SHA 当作远程可获取版本。
-
-```sh
-git clone /absolute/path/to/skills /tmp/skills-guard-source
-git -C /tmp/skills-guard-source checkout <M3记录中的本地验证revision>
-```
-
-先核对 `codex --version`、`python3 --version` 和 `git --version`。以下复制命令中的目标目录替换为实际 Git 仓库根目录；可在目标项目运行 `git rev-parse --show-toplevel` 确认。
-
-```sh
-mkdir -p "/absolute/path/to/My Project/.codex/hooks"
-cp "/tmp/skills-guard-source/hooks/codex/context-goal-guard.py" "/absolute/path/to/My Project/.codex/hooks/context-goal-guard.py"
-```
-
-打开目标项目 `.codex/hooks.json`，将 [配置示例](../hooks/codex/hooks.example.json)中的两组 handler **追加**到已有 `PreToolUse` 和 `Stop` 数组；没有文件或事件时才新建对应对象。保留其他事件、handler、matcher 和顶层字段。不要用整个示例覆盖已有 manifest。
-
-两个 command 保留以下写法及 JSON 内转义的双引号，无需填入本机目录；运行时按 Git 根目录解析，可从仓库子目录启动，也可随仓库迁移：[官方 Hooks 路径约定](https://learn.chatgpt.com/docs/hooks)。
-
-```json
-{"type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65", "timeout": 3}
-```
-
-若 Codex 环境无法解析 `python3`，将其换为已核对的 Python 3 可执行文件绝对路径，也保留必要引号。Git 根目录的命令替换结果置于双引号内，含空格或 shell 元字符的项目路径仍作为单个参数传入。同步超时为 3 秒。非 Git 目录不适用此写法，需手动配置脚本绝对路径。
-
-## 信任与生效确认
-
-1. 从目标项目启动 Codex，审阅并信任项目 `.codex/` 层。
-2. 打开 `/hooks`，找到来源为本项目 `.codex/hooks.json` 的两个 guard handler；审阅命令、路径、事件与超时，分别信任并启用。
-3. 再次确认两个 handler 的来源、启用和信任状态；确认其他 hooks 仍在列表中。未信任时会被跳过，安静无告警不能证明已生效。
-4. 修改 hook 定义或 command 路径后，重新在 `/hooks` 审阅信任。信任绑定定义 hash，不伪造 hash。替换脚本内容也需自行重新审阅；不要假定定义 hash 会检测脚本内容变化。
-5. 在隔离项目、测试 goal 中验证提示和真实暂停后，再用于日常任务。可从仓库子目录启动，command 仍从 Git 根目录定位脚本。
-
-安装、信任和阅读说明都不构成暂停授权。在**当前 goal** 的用户指令里明确，例如：
-
-> 对当前 goal，如果本地估算上下文使用率严格超过 65%（按实际阈值替换），请先安全收尾，按已有任务约定保存进度和交接说明，再使用原生 goal 工具将其设为 paused 并核对，无需二次确认。未完成工作不要标为 complete。请提醒我自己新开对话继续。
-
-后续 `/goal resume` 撤销先前暂停请求，需重新明确策略。普通命令测试可使用 `features.code_mode.enabled=true` 和 `features.code_mode.direct_only_tool_namespaces=["functions"]`；code mode 使用默认路径。M1 验证了两者；仅关闭 code mode 不保证普通命令回退。配置字段见 [官方配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)。
-
-## 收尾与人工接续
-
-成功回复应说明真实 `paused` 状态、已有记录位置、剩余任务和下一步。无既有记录时，agent 在回复中给出交接摘要（完成/未完成、验证/未验证、下一步、仍运行的进程），不强制创建新文件。进度写入失败时，也先在回复保留最小摘要并明确失败。
-
-在同一项目目录自行新开对话，提供已有计划路径，或粘贴交接摘要并说明继续。新对话没有继承的 goal；需要用户手动设置 goal、重新明确按阈值暂停的策略后，guard 才对它生效。旧 goal 保持 paused；可保留，或回旧对话主动 `/goal clear`。恢复旧 goal 不清空上下文，不作为腾出上下文的办法。线程生命周期命令见 [官方 Goals 文档](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)。
-
-如果 agent 请求确认、拒绝暂停或暂停失败，仍算尚未暂停；在原对话执行 `/goal pause` 后再接续。不要依据“已提醒”判断暂停成功。
-
-## 排查与停用
-
-| 表现 | 检查与处理 |
-| --- | --- |
-| `/hooks` 没有 guard 或显示待审/禁用 | 核对项目层信任、来源、manifest JSON，以及 `git rev-parse --show-toplevel` 下的脚本路径；重新审阅信任并启用 |
-| “检测不可用” | 核对 Codex 版本、进程实际 `CODEX_HOME`、会话和 `goals_1.sqlite` 的存在与读权限；不手工补库或改状态。格式/schema/锁异常持续时在 `/hooks` 停用 guard |
-| hook 超时/失败提示 | 本次检测失效，工具可能继续。检查 Python、文件读取与存储延迟，在隔离环境重验后再调整 3 秒上限 |
-| 超过阈值但没有提示 | 核对当前根线程是否有 active goal、新统计是否已记录及工具事件覆盖；不能用 UI 百分比直接代替本地统计 |
-| Stop 后仍 active 或持续续跑 | 在原对话 `/goal pause`；检查暂停授权和其他 Stop hooks。其他 hooks 的继续/停止要求须组合实测，不能宣称所有组合兼容 |
-
-临时停用：在 `/hooks` 中仅禁用本 guard 的两个 handler。永久移除：从两个事件数组中只删除 command 指向 `context-goal-guard.py` 的 handler，保留其他 hooks；确认不再引用后可删除该脚本副本。任务记录保留，paused goal 不自动恢复，不需要数据库迁移或回填。
-
-## 本地验证
-
-```sh
-python3 -m unittest discover -s test/codex -p 'test_*.py'
-python3 -m py_compile hooks/codex/context-goal-guard.py
-```
-
-行为测试通过真实脚本入口、临时 JSONL 和只读 SQLite 验证阈值、身份、无写入与异常降级；真实 Codex 部署和接续证据位于上述里程碑记录。fixture 不能替代真实阈值与调度验收。

package/hooks/claude/context-goal-guard.js

@@ -1,139 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-// Read-only context reminder for an active /goal, verified against the Claude Code 2.1.288 transcript format.
-// Never writes files and never exits with code 2: anything unexpected degrades to "detection unavailable".
-
-const fs = require('node:fs');
-
-// Percent of the window; the handler command may override it with `--threshold N`.
-const DEFAULT_THRESHOLD = 70;
-// Hook input and transcript carry no window size; only windows checked against statusLine are trusted.
-const WINDOWS = {
-  'claude-opus-5-5': 1000000,
-  'claude-sonnet-5-5': 1000000,
-  'claude-haiku-4-5-20251001': 200000,
-};
-const WINDOW_ENV = ['CLAUDE_CODE_DISABLE_1M_CONTEXT', 'DISABLE_COMPACT', 'CLAUDE_CODE_MAX_CONTEXT_TOKENS'];
-
-class Unavailable extends Error {}
-
-function readTranscript(file) {
-  if (typeof file !== 'string' || !file) throw new Unavailable('hook 输入缺少会话记录路径');
-  let text;
-  try {
-    text = fs.readFileSync(file, 'utf8');
-  } catch {
-    throw new Unavailable('无法读取会话记录');
-  }
-  let goal = null;
-  let usage = null;
-  for (const line of text.split('\n')) {
-    let record;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      continue; // blank lines and the line still being written
-    }
-    if (!record || record.isSidechain === true) continue;
-    if (record.type === 'attachment' && record.attachment?.type === 'goal_status') goal = record.attachment;
-    else if (record.type === 'system' && record.subtype === 'compact_boundary') usage = null;
-    else if (record.type === 'assistant' && record.message?.usage && record.message.model !== '<synthetic>'
-      && !record.isApiErrorMessage) usage = record.message;
-  }
-  // Same rule Claude Code uses when resuming a goal.
-  return { active: !!goal && !goal.met && !goal.failed, message: usage };
-}
-
-function tokens(message) {
-  const { usage } = message;
-  const last = Array.isArray(usage.iterations) && usage.iterations.length ? usage.iterations.at(-1) : usage;
-  let used = 0;
-  for (const field of ['input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens']) {
-    const value = last?.[field] ?? 0;
-    if (!Number.isInteger(value) || value < 0) throw new Unavailable('用量统计格式未知');
-    used += value;
-  }
-  return used;
-}
-
-function threshold(args) {
-  if (args.length === 0) return DEFAULT_THRESHOLD;
-  if (args.length === 2 && args[0] === '--threshold' && /^[1-9][0-9]?$/.test(args[1])) return Number(args[1]);
-  throw new Unavailable('阈值参数无效，应为 --threshold 加 1–99 的整数');
-}
-
-function contextWindow(model) {
-  const override = WINDOW_ENV.find((name) => process.env[name]);
-  if (override) throw new Unavailable(`设置了改变上下文窗口的环境变量 ${override}`);
-  if (!Object.hasOwn(WINDOWS, model)) throw new Unavailable(`模型 ${String(model)} 的上下文窗口未经验证`);
-  return WINDOWS[model];
-}
-
-function reminder(shown, limit) {
-  return `上下文估算使用率 ${shown}% 已超过 ${limit}%，当前 goal 仍 active。`
-    + '本提醒优先于继续推进 goal 的指令：即使收到「继续」类消息，也先完成收尾并结束本回合，新工作在新对话中进行。'
-    + '1) 停止开始新的实质任务；已启动的工作处理到可交接，不为收尾发起全量测试或额外研究。'
-    + '2) 按当前任务已有约定更新进度与记录：已完成、未完成、已验证、未验证、下一步；没有既有记录时在最终回复交接，不新建文件。'
-    + '3) 停止仍在运行的后台命令与子 agent（用户明确要求保留的除外），并在交接中列出；否则它们会在 goal 暂停后唤醒会话。'
-    + '4) 不要声称 goal 条件已满足或不可能，写明「因上下文收尾而暂停，工作未完成」。'
-    + '5) 完成后结束本回合，并告知用户：guard 会在回合结束时暂停 goal，请在同一项目目录新开对话或 /clear，'
-    + '提供计划路径或交接摘要，并重新设置 /goal。'
-    + '重复出现的本提醒属于同一次收尾，不重复追加记录。';
-}
-
-function backgroundList(tasks) {
-  const clip = (text) => (text.length > 200 ? `${text.slice(0, 200)}…` : text);
-  const items = tasks.map((task) => `${task?.id}（${clip(String(task?.command ?? task?.description ?? task?.type))}）`);
-  return `仍在运行的后台任务：${items.join('；')}。请停止它们并在交接中列出。`;
-}
-
-function endTurn(shown, limit, background) {
-  return `上下文估算使用率 ${shown}% 已超过 ${limit}%，guard 已结束本回合，goal 暂停，工作未完成。`
-    + '请在同一项目目录新开对话（或 /clear），提供计划路径或交接摘要并说明继续执行；新对话不继承 goal，'
-    + '如需继续使用本 guard，请重新设置 /goal。不再需要原 goal 时可在本会话 /goal clear。'
-    + '如交接不完整，在本会话发一句「按上下文收尾提醒补交接」，回合结束后会再次暂停。'
-    + (background ? `仍有 ${background} 个后台任务在运行，它们结束或 check-in 时会短暂唤醒会话，guard 会再次结束回合。` : '');
-}
-
-function unavailable(reason) {
-  return {
-    systemMessage: `context goal guard 检测不可用：${reason}；参见 docs/claude-context-goal-guard.md 排查，`
-      + '或从 .claude/settings.local.json 移除本 guard',
-  };
-}
-
-function decide(input) {
-  const event = input?.hook_event_name;
-  if ((event !== 'PostToolBatch' && event !== 'Stop') || input.agent_id) return null;
-  try {
-    const { active, message } = readTranscript(input.transcript_path);
-    if (!active || !message) return null;
-    const limit = threshold(process.argv.slice(2));
-    const used = tokens(message);
-    const window = contextWindow(message.model);
-    if (used * 100 <= window * limit) return null;
-    const shown = Math.round((used / window) * 100);
-    if (event === 'PostToolBatch') {
-      return { hookSpecificOutput: { hookEventName: event, additionalContext: reminder(shown, limit) } };
-    }
-    const background = Array.isArray(input.background_tasks) ? input.background_tasks : [];
-    if (input.stop_hook_active !== true) {
-      const reason = reminder(shown, limit) + (background.length ? backgroundList(background) : '')
-        + '若已完成收尾，只需一句确认后结束。';
-      return { decision: 'block', reason };
-    }
-    return { continue: false, stopReason: endTurn(shown, limit, background.length) };
-  } catch (error) {
-    // Warn once per stop instead of on every tool batch; never block or end the turn on uncertainty.
-    if (event !== 'Stop') return null;
-    return unavailable(error instanceof Unavailable ? error.message : '内部错误');
-  }
-}
-
-let output = null;
-try {
-  output = decide(JSON.parse(fs.readFileSync(0, 'utf8')));
-} catch {
-  output = null;
-}
-if (output) process.stdout.write(JSON.stringify(output));

package/hooks/claude/settings.example.json

@@ -1,26 +0,0 @@
-{
-  "hooks": {
-    "PostToolBatch": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-goal-guard.js\" --threshold 70",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-goal-guard.js\" --threshold 70",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
-}

package/hooks/codex/context-goal-guard.py

@@ -1,189 +0,0 @@
-#!/usr/bin/env python3
-"""Read-only context reminder for the verified Codex 0.160.0 transcript format."""
-
-import json
-import os
-from pathlib import Path
-import re
-import sqlite3
-import sys
-import uuid
-
-
-# Percent of the window; the handler command may override it with `--threshold N`.
-DEFAULT_THRESHOLD = 65
-
-UNAVAILABLE = {
-    "systemMessage": "上下文 goal guard 检测不可用；请核对 CODEX_HOME、会话格式及随附的启用说明。"
-                     "持续异常时请在 /hooks 中停用本 guard 并按说明排查。"
-}
-
-
-def root_transcript(data, home):
-    if data.get("agent_id"):
-        return None
-    session_id = data["session_id"]
-    if not isinstance(session_id, str):
-        raise ValueError("invalid session identity")
-    uuid.UUID(session_id)
-    path = Path(data["transcript_path"])
-    if not path.is_absolute() or not path.resolve().is_relative_to((home / "sessions").resolve()):
-        raise ValueError("transcript outside current home")
-    with path.open("rb") as stream:
-        header = stream.readline(1024 * 1024)
-    if not header.endswith(b"\n"):
-        raise ValueError("incomplete session metadata")
-    record = json.loads(header)
-    if record["type"] != "session_meta":
-        raise ValueError("missing session metadata")
-    meta = record["payload"]
-    if not isinstance(meta, dict):
-        raise ValueError("unknown session metadata")
-    source = meta.get("source")
-    if meta.get("parent_thread_id") or isinstance(source, dict) and "subagent" in source:
-        return None
-    if (meta["id"] != session_id or meta["session_id"] != session_id
-            or source not in ("cli", "exec", "vscode") or meta["cli_version"] != "0.160.0"):
-        raise ValueError("unverified identity or format")
-    return path
-
-
-def goal_active(home, thread):
-    database = home / "goals_1.sqlite"
-    con = sqlite3.connect(database.resolve().as_uri() + "?mode=ro", uri=True, timeout=0.2)
-    try:
-        found = con.execute("SELECT status FROM thread_goals WHERE thread_id = ?", (thread,)).fetchone()
-    finally:
-        con.close()
-    if found is not None and not isinstance(found[0], str):
-        raise ValueError("unknown goal status format")
-    return found is not None and found[0] == "active"
-
-
-def reverse_records(stream):
-    stream.seek(0, os.SEEK_END)
-    remaining = stream.tell()
-    pending = b""
-    discard_tail = True
-    while remaining:
-        size = min(65536, remaining)
-        remaining -= size
-        stream.seek(remaining)
-        parts = (stream.read(size) + pending).split(b"\n")
-        pending = parts.pop(0)
-        for line in reversed(parts):
-            # Drop the trailing fragment, or the empty line after a final newline.
-            if discard_tail:
-                discard_tail = False
-            elif line.strip():
-                yield json.loads(line)
-    if pending.strip() and not discard_tail:
-        yield json.loads(pending)
-
-
-def context_usage(path, model):
-    if not isinstance(model, str) or not model:
-        raise ValueError("missing current model")
-    candidate = None
-    newer_context = False
-    windows = []
-    window_ids = []
-    with path.open("rb") as stream:
-        for record in reverse_records(stream):
-            kind = record["type"]
-            payload = record["payload"]
-            if not isinstance(payload, dict):
-                raise ValueError("unknown record payload")
-            if kind == "compacted" or (kind == "event_msg" and payload.get("type") in
-                                      ("context_compacted", "model_context_changed", "model_changed")):
-                if candidate is None or newer_context:
-                    raise ValueError("statistics invalidated")
-                return candidate
-            if kind == "turn_context":
-                if payload["model"] != model:
-                    raise ValueError("statistics belong to another model")
-                context = payload.get("context_window")
-                if context is not None:
-                    identity = context["window_id"]
-                    if not isinstance(identity, str) or not identity:
-                        raise ValueError("unknown context identity")
-                    window_ids.append(identity)
-                if "model_context_window" in payload:
-                    windows.append(payload["model_context_window"])
-                if candidate is not None:
-                    if any(type(w) is not int or w != candidate[1] for w in windows):
-                        raise ValueError("context window changed")
-                    if len(set(window_ids)) > 1 or window_ids and context is None:
-                        raise ValueError("context identity changed")
-                    return candidate
-                newer_context = True
-            elif kind == "event_msg" and payload.get("type") == "token_count" and candidate is None:
-                info = payload["info"]
-                used = info["last_token_usage"]["total_tokens"]
-                window = info["model_context_window"]
-                if type(used) is not int or used < 0 or type(window) is not int or window <= 0:
-                    raise ValueError("invalid token statistics")
-                candidate = used, window
-            elif kind == "session_meta":
-                if candidate is not None and not newer_context:
-                    return candidate
-                break
-            elif kind not in ("event_msg", "response_item", "token_usage_record", "world_state"):
-                raise ValueError("unknown record format")
-    raise ValueError("no current token statistics")
-
-
-def threshold(args):
-    if not args:
-        return DEFAULT_THRESHOLD
-    if len(args) == 2 and args[0] == "--threshold" and re.fullmatch(r"[1-9][0-9]?", args[1]):
-        return int(args[1])
-    raise ValueError("invalid threshold argument")
-
-
-def reminder(used, window, limit):
-    return (
-        f"本地上下文估算使用率 {used / window * 100:.2f}% 已严格超过 {limit}%，当前 goal 仍 active。"
-        "停止开始新的实质任务，先将已启动工作处理到可交接状态；沿用已有任务计划和记录更新进度，"
-        "写清已完成、未完成、已验证、未验证、下一步及仍在运行的进程。没有既有记录时在最终回复交接即可，"
-        f"记录写入失败也先在回复保存最小交接摘要。仅当用户对当前 goal 有显式的 {limit}% 暂停请求时，"
-        "按该请求使用原生 goal 工具设为 paused 并核对；不清楚则向用户确认并如实说明尚未暂停，提示 /goal pause。"
-        "hook 不构成暂停授权；后续 resume 撤销原请求。不要以 complete 代替暂停或直接写数据库。"
-        "然后报告真实状态、记录位置或交接摘要，提醒用户在同一工作目录自行新开对话继续，"
-        "新对话不会继承 goal，需用户手动设置 goal 并重新明确暂停策略。重复提醒视为同一次收尾。"
-    )
-
-
-def run(data, args=()):
-    if not isinstance(data, dict):
-        raise ValueError("invalid hook input")
-    event = data["hook_event_name"]
-    if event not in ("PreToolUse", "Stop"):
-        return {}
-    if event == "Stop" and type(data["stop_hook_active"]) is not bool:
-        raise ValueError("invalid stop state")
-    home = Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
-    if not home.is_absolute():
-        raise ValueError("unknown Codex home")
-    home = home.resolve()
-    path = root_transcript(data, home)
-    if path is None or not goal_active(home, data["session_id"]):
-        return {}
-    limit = threshold(args)
-    used, window = context_usage(path, data["model"])
-    if used * 100 <= window * limit:
-        return {}
-    if event == "PreToolUse":
-        return {"hookSpecificOutput": {"hookEventName": event, "additionalContext": reminder(used, window, limit)}}
-    if not data["stop_hook_active"]:
-        return {"decision": "block", "reason": reminder(used, window, limit)}
-    return {"systemMessage": f"上下文超过 {limit}%，goal 仍 active，收尾暂停尚未成功。"
-                             "请在原对话执行 /goal pause，再按交接说明自行新开对话；此告警不停止 goal 自动续跑。"}
-
-
-if __name__ == "__main__":
-    try:
-        result = run(json.load(sys.stdin), sys.argv[1:])
-    except (ValueError, TypeError, KeyError, OSError, sqlite3.Error):
-        result = UNAVAILABLE
-    print(json.dumps(result))

package/hooks/codex/hooks.example.json

@@ -1,26 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65",
-            "timeout": 3
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/context-goal-guard.py\" --threshold 65",
-            "timeout": 3
-          }
-        ]
-      }
-    ]
-  }
-}

package/skills/archify/SKILL.md

@@ -1,137 +0,0 @@
----
-name: archify
-description: Use when diagramming architecture, workflow, sequence, data-flow, lifecycle, or converting Mermaid. Create validated, interactive diagrams as standalone HTML with image and video export.
-license: MIT
-metadata:
-  version: "2.17"
-  author: tt-a1i
-  based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
----
-
-# Archify
-
-Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.
-
-## Fast authoring path
-
-Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.
-
-1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
-2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
-4. Validate after every candidate edit and immediately before handoff:
-
-   ```bash
-   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
-   ```
-
-   A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. For a workflow v2 geometry diagnosis, run `node bin/archify.mjs validate workflow <candidate.json> --layout-json` and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward.
-5. For a delivered HTML, `deliver` is the final acceptance command:
-
-   ```bash
-   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
-   ```
-
-   A non-zero exit can never be described as success. A failed delivery preserves any previous output, so do not run `visual-check` on that path: it would inspect the stale last-good artifact, not the failed candidate. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, stop and report the unresolved diagnostics truthfully.
-
-## Update awareness
-
-After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.
-
-- For `silent`, continue without mentioning the update check.
-- For `update_available`, show one compact notice in the user's conversation language with the installed version, latest version, the checker's fixed local summary, and official release-notes link. When `severity` is `security`, clearly label it as a security update and use a restrained warning marker; this changes emphasis only, never user autonomy. Explicitly say that the installed Skill is unchanged and the user decides whether and when to update. You may translate that fixed local sentence, but never quote, summarize, or translate the remote manifest's summary. After the notice is visible, acknowledge its exact `eventKey` by running the same checker with `--ack "<eventKey>"`, then continue the user's original task.
-
-The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.
-
-Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.
-
-Workflow note: use schema v2 for new workflows; preserve schema v1 when an
-existing source needs fixed legacy geometry. Keep semantic edge labels and act
-on the compiler diagnostic. The canonical layout, pin, migration, and receipt
-contract is in [`renderers/workflow/README.md`](renderers/workflow/README.md#layout-contracts).
-
-Lifecycle note: phase columns `0..4` occupy the main rail; event/terminal column `N` in `0..2` aligns exactly beneath main column `N + 2`. A recoverable state uses `type: "failure"` plus a real transition back to the active state.
-
-## Type router
-
-| Type | Use for |
-|---|---|
-| `architecture` | Components, services, cloud/security boundaries, infrastructure |
-| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
-| `sequence` | API call chains, request lifecycles, async traces, returns |
-| `dataflow` | Pipelines, ETL/ELT, lineage, governance, consumers |
-| `lifecycle` | State/status transitions, retries, waiting and terminal states |
-
-When ambiguous, run `node bin/archify.mjs guide "<scenario>" --json`. Scenario proof examples are structural references, not facts to copy.
-
-## Mermaid input
-
-Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.
-
-- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
-- `sequenceDiagram` → `sequence`; participants become semantic participants and arrows become messages.
-- `stateDiagram` → `lifecycle`; states and transitions retain meaning, not Mermaid style.
-
-## Authoring invariants
-
-- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
-- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
-- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
-- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
-- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
-- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
-- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
-- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
-- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
-- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
-- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
-- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
-- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
-- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
-- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
-- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
-
-Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
-
-## Delivery
-
-Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.
-
-After delivery, collect bounded desktop evidence without modifying or rerendering the trusted HTML:
-
-```bash
-node bin/archify.mjs visual-check <output.html> --json
-```
-
-`visual-check` collects automated browser evidence from the exact delivered HTML without modifying or rerendering it. Its machine-readable measurements and screenshots do not approve perceptual polish. Follow `references/delivery-contract.md` for the canonical receipt fields, coverage, sidecars, exit behavior, and supplementary manual-record requirements.
-
-Keep the three claims separate: `deliver` proves deterministic artifact checks, `visual-check` proves bounded behavior in a real browser, and perceptual visual review requires an actual human or image-capable reviewer. Report browser evidence and perceptual review independently. An unconstrained glance can support only perceptual review; use the canonical delivery contract when recording supplementary manual browser work or handling an environmental failure.
-
-Add `--open` only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:
-
-```bash
-node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
-```
-
-Never start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-commit opening.
-
-## Optional viewer capabilities
-
-Generated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.
-
-Read `references/viewer-runtime.md` only when the user explicitly asks for Share Cards, Route/Reach cards, motion, guided stories, deep links, presentation, search/focus, or another Viewer Runtime feature.
-
-## Setup and fallback
-
-No install is required inside the skill package. Verify with:
-
-```bash
-node bin/archify.mjs doctor
-node bin/archify.mjs demo <output-directory>
-```
-
-When shell access is unavailable, hand-place architecture SVG into `assets/template.html`, use CSS semantic classes rather than inline colors, and follow the visual review contract in `references/delivery-contract.md`.
-
-## Output
-
-Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.