Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ Open the part relevant to your current question. Use the resource links above fo
<details id="hooks">
<summary>Optional hooks: installation, coverage, and limits</summary>

<p class="status">OPTIONAL CONTINUITY + CHECKPOINTS · NO MERGE GUARD</p><p>Choose continuity for compact recovery, checkpoints for commit/review reminders, or both. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.</p><h4>Choose your optional presets</h4><pre><code>./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
<p class="status">OPTIONAL CONTINUITY + CHECKPOINTS + STANDARDS · NO MERGE GUARD</p><p>Choose continuity for compact recovery, checkpoints for commit/review reminders, standards to run your declared checks after a commit, or any combination. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.</p><h4>Choose your optional presets</h4><pre><code>./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints
./structured-coding/scripts/install codex --project /path/to/project --hooks continuity checkpoints
./structured-coding/scripts/install codex --project /path/to/project --check-hooks
Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ scope 按工具分别设置,因为正确答案本来就因工具而异:只
<details id="hooks">
<summary>可选 hook:安装、覆盖范围和限制</summary>

<p class="status">可选 CONTINUITY + CHECKPOINTS · 尚无 MERGE GUARD</p><p>需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,也可同时安装。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。</p><h4>选择需要的 preset</h4><pre><code>./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
<p class="status">可选 CONTINUITY + CHECKPOINTS + STANDARDS · 无 MERGE GUARD</p><p>需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,需要在 commit 后跑你声明的检查可选 standards,也可任意组合。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。</p><h4>选择需要的 preset</h4><pre><code>./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints
./structured-coding/scripts/install codex --project /path/to/project --hooks continuity checkpoints
./structured-coding/scripts/install codex --project /path/to/project --check-hooks
Expand Down
2 changes: 1 addition & 1 deletion dist/claude-code/structured-coding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ On resume, reload the current design, filled contract, and full execution rules;

## Optional hooks: installation, coverage, and limits

Choose continuity for compact recovery, checkpoints for commit/review reminders, or both. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.
Choose continuity for compact recovery, checkpoints for commit/review reminders, standards to run your declared checks after a commit, or any combination. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.

```sh
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
Expand Down
2 changes: 1 addition & 1 deletion dist/claude-code/structured-coding/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ Compact 是 host 为腾出 context 而压缩聊天历史的过程,不是新建

## 可选 hook:安装、覆盖范围和限制

需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,也可同时安装。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。
需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,需要在 commit 后跑你声明的检查可选 standards,也可任意组合。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。

```sh
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
Expand Down
1 change: 1 addition & 0 deletions dist/claude-code/structured-coding/VERSION
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0.1.0
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Hook behavior contract

Status: **BEHAVIOR SPECIFICATION — optional [continuity preset](continuity.md) implements mechanical H4 checks, H5 snapshot attempts, and the H6 recovery-instruction subset.** It is not registered by default. The optional [checkpoints preset](checkpoints.md) adds H2 commit-preparation advice and an H7 review-intent notice, with zero automatic continuations. Full H1/H2/H3/H7 enforcement and H6 mutation enforcement remain unimplemented. The requirements below remain the complete target, not a claim of full adapter coverage.
Status: **BEHAVIOR SPECIFICATION — optional [continuity preset](continuity.md) implements mechanical H4 checks, H5 snapshot attempts, and the H6 recovery-instruction subset.** It is not registered by default. The optional [checkpoints preset](checkpoints.md) adds H2 commit-preparation advice and an H7 review-intent notice, with zero automatic continuations. Full H1/H2/H3/H7 enforcement and H6 mutation enforcement remain unimplemented. The optional [standards preset](standards.md) is **not** an adapter for anything specified here: it reports a project's own declared checks and review conventions after a direct `git commit`, which is a different axis from the freeze, merge and continuity behaviour this contract describes, and it blocks nothing. The requirements below remain the complete target, not a claim of full adapter coverage.

This contract translates the workflow's freeze, merge, and context-continuity requirements into observable behavior. Event names below describe the workflow; actual host adapters are separate work. Supported host events and their sources are listed in [platforms.md](platforms.md).

Expand Down
4 changes: 2 additions & 2 deletions dist/claude-code/structured-coding/references/platforms.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@ From the cloned repository, use the exact project Git root (quote paths with spa
./scripts/install codex --project /path/to/project --remove-hooks
```

Use `claude-code` for Claude Code. Python 3.9+, Git and macOS/Linux/WSL are required. Current conservative host floors are Codex 0.153.4 and Claude Code 2.1.261; host delivery needs separate native verification. Restart the host and inspect `/hooks` after changes; the installer does not grant trust or enable disabled hooks.
Use `claude-code` for Claude Code. Python 3.9+, Git and macOS/Linux/WSL are required. Current conservative host floors are Codex 0.153.4 and Claude Code 2.1.261; host delivery needs separate native verification. Restart the host and inspect `/hooks` after changes; the installer does not grant trust or enable disabled hooks. The installed copy carries its release in `VERSION`, and `--check-hooks` reports it, so you can tell which one a project has.

Codex requires trust at **two** levels, and a registration is inert until both are given. First the project: until it is trusted, Codex loads no project-local hooks at all and says so on stderr, naming the file it wants the entry in. That entry must live in the `config.toml` under `CODEX_HOME`; a `-c projects."<path>".trust_level="trusted"` override on the command line does **not** satisfy it, which is the failure that looks like hooks being delivered but ignored. Second, each hook definition is trusted by its own content hash, so changing a command asks again. Both are Codex's own mechanism; neither is granted by this installer. Claude Code has no equivalent second level.

Installation is additive. Standards alone registers shared SessionStart and PostToolUse, and is the only preset that runs anything; its PostToolUse hook carries a 60-second budget rather than 12, because a check is slower than a notice. Checkpoints alone registers shared SessionStart, PreToolUse and Stop, without compact handlers. Continuity alone registers shared SessionStart and manual/automatic PreCompact. Both use five groups, with SessionStart exactly once. Removing one keeps the other usable. Bare `--remove-hooks` removes all owned presets and preserves the skill and session data. Repeating a selection is a byte-preserving no-op; duplicate/unknown names are rejected.
Installation is additive. Standards alone registers shared SessionStart and PostToolUse, and is the only preset that runs anything; its PostToolUse hook carries a 60-second budget rather than 12, because a check is slower than a notice. Checkpoints alone registers shared SessionStart, PreToolUse and Stop, without compact handlers. Continuity alone registers shared SessionStart and manual/automatic PreCompact. All three together register six groups, with SessionStart exactly once. Removing one keeps the other usable. Bare `--remove-hooks` removes all owned presets and preserves the skill and session data. Repeating a selection is a byte-preserving no-op; duplicate/unknown names are rejected.

One aggregate receipt owns the original settings backup. Legacy continuity receipts remain readable and migrate only on an explicit state change; check, preview and unchanged reinstall do not rewrite them. Existing customized runtime dependencies are never overwritten: compare/back up the installed skill and explicitly update it first. Missing, changed or duplicate owned groups, unknown receipt schemas, and redirected/unverifiable paths cause refusal. New installations register commands that contain no machine-specific path, so a registration committed to a shared settings file works on a teammate's machine; each machine still reviews and trusts the hooks itself. An installation made by an older release keeps its absolute commands, stays inspectable and removable, and is rewritten only by `--upgrade-registration`, which changes every command and therefore requires trusting the hooks again. `--check-hooks` says whether a registration is portable, and names the recorded interpreter only for an absolute one.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@ Codex 的目录和调用方式依据 [OpenAI 官方 skills 文档](https://learn
./scripts/install codex --project /path/to/project --remove-hooks
```

Claude Code 用户把 `codex` 换成 `claude-code`。需要 Python 3.9+、Git 和 macOS/Linux/WSL。目前保守的宿主版本下限是 Codex 0.153.4 和 Claude Code 2.1.261;实际事件送达还需要独立的 native 验证。修改后重启 host 并检查 `/hooks`;installer 不授予信任,也不会打开被禁用的 hook。
Claude Code 用户把 `codex` 换成 `claude-code`。需要 Python 3.9+、Git 和 macOS/Linux/WSL。目前保守的宿主版本下限是 Codex 0.153.4 和 Claude Code 2.1.261;实际事件送达还需要独立的 native 验证。修改后重启 host 并检查 `/hooks`;installer 不授予信任,也不会打开被禁用的 hook。安装后的副本在 `VERSION` 里带着自己的发布版本,`--check-hooks` 会报告它,所以你能知道某个项目装的是哪一版。

Codex 的信任分**两层**,两层都给到之前注册都是空转的。第一层是项目:在项目被信任之前,Codex 根本不加载任何 project-local hook,并会在 stderr 上说明,同时指出它要求写入的文件。那条记录必须写在 `CODEX_HOME` 下的 `config.toml` 里;命令行上的 `-c projects."<path>".trust_level="trusted"` 覆盖**不满足**这一条,而这种失败看起来像是 hook 被送达却被忽略了。第二层是每个 hook 定义按自身内容 hash 单独信任,所以改动命令会重新询问。两层都是 Codex 自己的机制,installer 都不会替你授予。Claude Code 没有对应的第二层。

安装是追加操作。单装 standards 会注册共享 SessionStart 和 PostToolUse,它是唯一会真正运行东西的 preset;它的 PostToolUse hook 预算是 60 秒而不是 12 秒,因为跑一次检查比发一条提示慢。单装 checkpoints 会注册共享 SessionStart、PreToolUse 和 Stop,不注册 compact handler。单装 continuity 会注册共享 SessionStart 和手动/自动 PreCompact。组合安装共五个 group,SessionStart 只出现一次。移除一个后另一个仍可用。裸 `--remove-hooks` 移除全部自有 preset,保留 skill 和 session 数据。重复安装同一选择不会改变文件字节;重复或未知名称会被拒绝。
安装是追加操作。单装 standards 会注册共享 SessionStart 和 PostToolUse,它是唯一会真正运行东西的 preset;它的 PostToolUse hook 预算是 60 秒而不是 12 秒,因为跑一次检查比发一条提示慢。单装 checkpoints 会注册共享 SessionStart、PreToolUse 和 Stop,不注册 compact handler。单装 continuity 会注册共享 SessionStart 和手动/自动 PreCompact。三个一起安装共六个 group,SessionStart 只出现一次。移除一个后另一个仍可用。裸 `--remove-hooks` 移除全部自有 preset,保留 skill 和 session 数据。重复安装同一选择不会改变文件字节;重复或未知名称会被拒绝。

一份 aggregate receipt 保存原始设置备份。旧 continuity receipt 仍可读取,仅在明确改变安装状态时迁移;检查、预览和未改变选择的重装都不改写它。installer 不覆盖定制过的 runtime 依赖:先比较、备份已有 skill,再明确升级。自有 group 缺失、被修改或重复,receipt schema 未知,以及路径被重定向或无法核验,都会导致拒绝。新安装注册的命令不含任何机器相关路径,因此提交到共享设置文件里的注册在同事的机器上同样有效;每台机器仍需自己审阅并信任这些 hook。旧版本装出来的注册保留其绝对路径命令,仍可检查、仍可移除,只有 `--upgrade-registration` 会重写它;重写会改变每一条命令,因此需要重新信任这些 hook。`--check-hooks` 会说明注册是否可移植,并且只对绝对路径的注册报告记录的 interpreter。

Expand Down
2 changes: 1 addition & 1 deletion dist/codex/structured-coding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ On resume, reload the current design, filled contract, and full execution rules;

## Optional hooks: installation, coverage, and limits

Choose continuity for compact recovery, checkpoints for commit/review reminders, or both. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.
Choose continuity for compact recovery, checkpoints for commit/review reminders, standards to run your declared checks after a commit, or any combination. Both are off by default. Checkpoints advises; it does not enforce commits or certify readiness. Protocol tests do not establish native event delivery or model compliance. The agent does not dynamically register its own hooks.

```sh
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
Expand Down
2 changes: 1 addition & 1 deletion dist/codex/structured-coding/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ Compact 是 host 为腾出 context 而压缩聊天历史的过程,不是新建

## 可选 hook:安装、覆盖范围和限制

需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,也可同时安装。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。
需要 compact 恢复可选 continuity,需要 commit/review 提醒可选 checkpoints,需要在 commit 后跑你声明的检查可选 standards,也可任意组合。默认都不开。Checkpoints 提供建议,不拦截 commit,也不证明已达到交付条件。Protocol 测试不能证明 native 事件送达或模型遵守了提示。agent 不会动态注册自己的 hook。

```sh
./structured-coding/scripts/install codex --project /path/to/project --hooks checkpoints --dry-run
Expand Down
1 change: 1 addition & 0 deletions dist/codex/structured-coding/VERSION
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0.1.0
2 changes: 1 addition & 1 deletion dist/codex/structured-coding/references/hook-contract.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Hook behavior contract

Status: **BEHAVIOR SPECIFICATION — optional [continuity preset](continuity.md) implements mechanical H4 checks, H5 snapshot attempts, and the H6 recovery-instruction subset.** It is not registered by default. The optional [checkpoints preset](checkpoints.md) adds H2 commit-preparation advice and an H7 review-intent notice, with zero automatic continuations. Full H1/H2/H3/H7 enforcement and H6 mutation enforcement remain unimplemented. The requirements below remain the complete target, not a claim of full adapter coverage.
Status: **BEHAVIOR SPECIFICATION — optional [continuity preset](continuity.md) implements mechanical H4 checks, H5 snapshot attempts, and the H6 recovery-instruction subset.** It is not registered by default. The optional [checkpoints preset](checkpoints.md) adds H2 commit-preparation advice and an H7 review-intent notice, with zero automatic continuations. Full H1/H2/H3/H7 enforcement and H6 mutation enforcement remain unimplemented. The optional [standards preset](standards.md) is **not** an adapter for anything specified here: it reports a project's own declared checks and review conventions after a direct `git commit`, which is a different axis from the freeze, merge and continuity behaviour this contract describes, and it blocks nothing. The requirements below remain the complete target, not a claim of full adapter coverage.

This contract translates the workflow's freeze, merge, and context-continuity requirements into observable behavior. Event names below describe the workflow; actual host adapters are separate work. Supported host events and their sources are listed in [platforms.md](platforms.md).

Expand Down
Loading
Loading