@ccoalm/ccl-skills 0.18.7 → 0.18.9

package/README.md

@@ -60,7 +60,7 @@ ccl-skills uninstall         # preview
 ccl-skills uninstall --yes   # remove host assets
 ```
 
-Limit any operation to one host with `--host claude`, `--host codex`, or `--host opencode`. Add `--json` for machine-readable output.
+Limit these operations to one host with `--host claude`, `--host codex`, or `--host opencode`. Add `--json` for machine-readable output.
 
 For `--host codex`, unreadable public plugin state returns exit `3` with `host-state-unknown`; a missing CLI or failed capability probe returns `4`. If that host failure occurs with a pending journal, recovery is deferred: exit `5` with `partial-journal` retains the journal and records `details.hostFailure`. Restore the CLI or readable public plugin state, then rerun the command. Other outcomes can share these exit codes, so inspect the JSON status as well.
 
@@ -70,9 +70,76 @@ Codex `doctor` also reads the native hook inventory. When every expected package
 
 After `ccl-skills uninstall --yes`, remove the CLI package itself with `npm uninstall --global @ccoalm/ccl-skills` if it is no longer needed.
 
+## Automatic CCL updates
+
+On macOS, explicitly enable daily CCL updates for one host:
+
+```bash
+# Existing Codex Git plugin; Codex is the default host
+npx --yes @ccoalm/ccl-skills@latest auto-update enable
+npx --yes @ccoalm/ccl-skills@latest auto-update status --json
+npx --yes @ccoalm/ccl-skills@latest auto-update disable
+
+# Existing npm-managed OpenCode skills, plugin and hooks
+npx --yes @ccoalm/ccl-skills@latest auto-update enable --host opencode
+npx --yes @ccoalm/ccl-skills@latest auto-update status --host opencode --json
+npx --yes @ccoalm/ccl-skills@latest auto-update disable --host opencode
+```
+
+With the CLI installed globally, replace `npx --yes @ccoalm/ccl-skills@latest` with `ccl-skills`. Each command acts on one host and executes directly; `--yes` and `--host all` are unsupported. Installation never enables scheduling. Separate launchd jobs run every 24 hours while logged in and when loaded at login. A non-root macOS user is required; other platforms return exit `4` with `unsupported-platform`.
+
+### Codex
+
+The target is `ccl-skills@ccl-skills` in the current `CODEX_HOME`, or `~/.codex` when unset. Its marketplace and plugin must use the canonical `ccoalm/ccl-skills` Git repository over HTTPS or SSH, and the plugin must be enabled. Codex must support `--no-daemon` and plugin JSON output.
+
+Each run checks public plugin state before and between these steps:
+
+```bash
+codex --no-daemon plugin marketplace upgrade ccl-skills
+codex --no-daemon plugin add ccl-skills@ccl-skills
+```
+
+An unsuccessful upgrade prevents the add step. Each update command has a two-minute limit; timeout terminates its child process group. Source changes are checked at those boundaries; Codex does not provide an atomic compare-and-update operation. Restart Codex to load changes. Hook trust follows Codex's normal policy.
+
+Codex npm installations use a local snapshot under `ccl-skills-npm`, which this scheduler refuses. Keep those current with `ccl-skills update --yes`. To migrate, preview removal with `ccl-skills uninstall --host codex`, then repeat with `--yes`. Register the Git installation explicitly:
+
+```bash
+codex --no-daemon plugin marketplace add https://github.com/ccoalm/ccl-skills.git
+codex --no-daemon plugin add ccl-skills@ccl-skills
+npx --yes @ccoalm/ccl-skills@latest auto-update enable
+```
+
+### OpenCode
+
+OpenCode requires an existing healthy npm-managed CCL installation with bundled assets. The scheduler updates only its CCL skills, native plugin and hook runtime under `~/.config/opencode`. It preserves OpenCode itself, application configuration, authentication, unrelated files and `~/.agents`. Restart OpenCode to load changes.
+
+Each run downloads `@ccoalm/ccl-skills@latest` from the public npm registry into a fresh private directory. It disables lifecycle scripts and package self-update, validates package identity, then invokes the fetched CLI's OpenCode doctor and update commands. It refuses missing installations, source overrides and locally changed managed files. A newer installed version is retained. Success requires a healthy receipt matching the fetched package version and bundled source.
+
+Source-checkout installs are unsupported. To migrate, first back up their CCL files and receipt, move only those verified CCL-owned files out of OpenCode's shared directories, then explicitly run the npm installer:
+
+```bash
+npx --yes @ccoalm/ccl-skills@latest install --host opencode
+npx --yes @ccoalm/ccl-skills@latest doctor --host opencode
+npx --yes @ccoalm/ccl-skills@latest auto-update enable --host opencode
+```
+
+The scheduler never adopts or deletes a source-copy installation. Resolve any collision or drift reported by the installer before enabling it.
+
+Package download has a three-minute limit; asset update has a two-minute limit. Cancellation sends SIGINT and allows ten seconds for rollback before forcing termination. A forced termination reports unknown finality; inspect `doctor --host opencode` before retrying. Fetch and preflight failures leave installed assets intact.
+
+### Status and recovery
+
+State lives in `$CODEX_HOME/ccl-skills-auto-update` for Codex and `~/.config/opencode/ccl-skills-auto-update` for OpenCode. Each profile has its own file in `~/Library/LaunchAgents`. The saved runner survives removal of an npx download and keeps the executable paths and profile selected at enable time. Those executables must remain installed. Re-enabling retains the saved runner; upgrading the npm CLI does not replace it.
+
+Commands receive fixed HOME/PATH plus CODEX_HOME and `GIT_TERMINAL_PROMPT=0` for Codex, or the self-update/notifier opt-outs for OpenCode. npm uses private empty config files and cache. Credentials and source/registry overrides from the enabling shell are not persisted; macOS may add runtime variables.
+
+`status` checks live registration and the latest bounded `last-run.json` record, which excludes raw command output. Failed or interrupted runs, registration errors and ownership errors return exit `5`. Restore the reported dependency and retry `enable` or `disable`. Overlapping runs are skipped. `disable` removes only that host's owned schedule and retains its runner, state and log. Disable first if removing the CLI should also stop updates.
+
+SIGINT and SIGTERM release owned locks, including between commands. A crash or forced kill can leave a `run.lock` or `manage.lock`. A lock at least 15 minutes old, or dated at least 15 minutes into the future, reports failure even if its PID is alive. The scheduler never removes these locks automatically. Inspect the recorded PID and launchd job; remove only that lock after confirming no updater owns it. Never remove a running updater's lock.
+
 ## Update notice
 
-Nothing here updates itself. An interactive run prints a one-line notice on **stderr** when a newer version exists, at most once a day per version:
+The npm package does not update itself automatically. An interactive run prints a one-line notice on **stderr** when a newer version exists, at most once a day per version:
 
 ```
 Update available: 0.2.0 -> 0.3.0

package/dist/assets/marketplace/plugins/ccl-skills/agent-context/session-policy.md

@@ -41,7 +41,7 @@ The compact session-start entry routes to these execution details when the relev
 
 几条贯穿原则（任何任务都适用；详则在 owner 技能里）：
 - **上下文恢复是 agent 的工作**：恢复/继续/复盘/判断既有工作时，先读 SessionStart 的 `<agent-context-recovery>`（若宿主提供），再核 repo 契约、当前 Git、项目状态/任务持久件、最小相关 session/memory 片段、commit 与 CI/test 证据；读取历史片段前必须确认其 repo root / cwd / remote 属于当前仓（全局 session/db 存在不等于相关）；启动快照只用于定位，结论仍要 live refresh。能从本地证据恢复的事实不得让用户重述。只有方向/重大取舍、缺失权限或凭据、不可逆动作、以及本地证据确实不存在时才打断用户。
-- **自主决策，别把可判定的问题推给用户**：开发中只在真实阻塞时停下问人——缺失的凭据/授权；本地证据确实没有的事实；上面安全硬边界管的动作（无恢复的破坏性/不可逆、prod/客户数据、目标外的合并/发布）；推翻用户既定方向；证据无法裁决的重大产品取舍。其余都由你定：设计期安全 4 问自答写进方案、安全自检、选 owner 技能/模块/方案、测试与命名、目标内的下一步；提交/推送/合并按「硬纪律 1」目标授权判断。写明假设后继续。「owner」指技能或代码 owner，不是要用户指派的人。某一步被阻塞时先做完其余独立工作，再在结尾用 `proposed-next: blocked:` 说明具体阻塞。
+- **自主决策，别把可判定的问题推给用户**：开发中只在真实阻塞时停下问人——缺失的凭据/授权；本地证据确实没有的事实；上面安全硬边界管的动作（无恢复的破坏性/不可逆、prod/客户数据、目标外的合并/发布）；推翻用户既定方向；证据无法裁决的重大产品取舍。其余都由你定：设计期安全 4 问自答写进方案、安全自检、选 owner 技能/模块/方案、测试与命名、目标内的下一步；提交/推送/合并按「硬纪律 1」目标授权判断。写明假设后继续。判据：阻塞必须是只有用户能提供的东西（证据无法裁决的决定、凭据或访问授权、目标之外的许可、所有可读来源里都没有的事实）；你自己能执行的下一步——修复及其测试评审、推分支开 MR/PR、重跑或重试失败/超时/结果不明的检查、查资料——不论花多少时间和次数都不是阻塞。以下几种说法都过不了这个判据：「你只让我调查/研究」——查原因、线上问题、测试挂了这类失败目标，根因证实后默认包含窄修复、回归测试、评审、推送功能分支并向开发目标开/更新 MR/PR，用户的明确限制照样约束（「只查/先别改」「先别推」、费用或次数上限），仓库契约标为先确认的区域、破坏性操作、新采购、合并/部署/生产动作也照常停（交接摘要里「这一步只读」只约束那一步）；「推送/开 MR 是对外动作」——推功能分支、开 MR/PR 是常规研发动作，不是发布，自审、外部评审和必需 CI 过了就在同一轮转 ready，不以「MR 保持 Draft」收尾；「等 CI 跑完」——自己 MR 的流水线自己轮询到结果；你自己提出的次数、轮数、停止线——它们是你的估计，不是用户限制；只有用户把它采纳为上限（亲口给数字、说「最多/只」、或明确接受为上限）才算，单纯同意去做（「ok」「好」）不算；用户中途的追问——答完继续已授权的动作，不是 status-only；能自己查到或构造的事实、日志、测试数据、之前用过的账号与环境——先自己查。真要停下要合并授权时，一次请求覆盖整个交付计划，别按次追加。「owner」指技能或代码 owner，不是要用户指派的人。某一步被阻塞时先做完其余独立工作，再在结尾用 `proposed-next: blocked:` 说明具体阻塞。
 - **用户主权**：AI 推荐、用户定。要改变用户既定方向时**始终先呈现+问，别径直下结论或代为决定**。你和另一个模型（codex 等）都同意也只是强信号、不是裁决。**仅当用户有既定方向、且你与第二模型都主张推翻它**（普通选项/口味/缺信息/评审 nit 不触发此结构）：用户方向是默认、改动由模型举证，呈现时必须显式补两句——我们可能缺什么上下文、若改错代价是什么（详见 tighten-doc cross-model caveat）。
 - **无证据不声称完成**：本轮没亲手跑过验证、没读到通过输出，就不说"完成/修好/通过/没问题"，缺证据如实说缺（详见 product-rd-workflow 验证门）。
 - **完整优先**：做完必要工作，不扩范围。报告/总结/进度说明不等于交付：结束前逐项核对用户请求和工作自身带出的后续项（失败检查、评审 finding、要同步的测试/文档；提交推送按「硬纪律 1」目标授权），能做的做完再收尾。阻塞交付的检查失败含基线问题，按 defect-diagnosis 诊断、安全修复、复测；真实阻塞才交回。

package/dist/assets/marketplace/plugins/ccl-skills/hooks/guard-merge-authorization.sh

@@ -172,6 +172,7 @@ DENY_TEXT_AUTO="合并授权闸：该命令会开启 auto-merge / merge-when-pip
 DENY_TEXT_SPELL="合并授权闸：授权有效但命令拼写不满足一次性立即合并要求——glab 需显式 --auto-merge=false（pipeline 运行中裸 merge 会默认转 auto-merge），gh 需显式 --merge/--squash/--rebase 策略，merge REST API 需显式 -X PUT。授权未消费，按上述拼写改写命令直接重试即可（无需用户重新授权）。"
 DENY_TEXT_TARGET="合并授权闸：用户授权指向了特定 MR/PR 编号，但该命令的合并对象与之不符或无法识别。授权未消费——请显式点名该编号（如 glab mr merge <授权编号> --auto-merge=false --yes）后重试；确需合并其他 MR 请让用户重新授权。"
 DENY_TEXT_MULTI="合并授权闸：同一条命令内检测到多个平台合并调用。每条命令只放行一个合并——把命令拆开逐条执行（单个授权下每个合并由用户分别授权；批量授权下每条命令消费 1 个额度，无需用户再次回复）。"
+DENY_TEXT_HELP="合并授权闸：命令带 -h/--help，只会打印帮助、不会合并，因此拒绝且不消费授权。查看帮助请用 glab help mr merge 或 gh help pr merge；正式合并时去掉帮助参数，用户已给的授权仍然有效。"
 DENY_TEXT_AMBIGUOUS="合并授权闸：检测到原始 HTTP 客户端、变更 method 的选项和 merge endpoint，但 method、transfer 边界、目标或动作数无法可靠关联。授权未消费——请改写成单个 curl/wget、单个明确 PUT method 和单个 merge URL 后重试。"
 
 # Missing legacy epoch files are compatible with pre-upgrade grants. Once
@@ -741,7 +742,7 @@ printf '%s\n' "$masked" | tr ';|&(){}' '\n' | while IFS= read -r seg; do
       # gh explicit strategy; REST/GraphQL calls are immediate by API
       # semantics). mid: the merge target id when statically extractable
       # ("?" otherwise) — matched against a number-bound grant below.
-      hit=0; auto=0; spell=SPELLBAD; mid="?"; multi_seg=0
+      hit=0; auto=0; spell=SPELLBAD; mid="?"; multi_seg=0; help=0
       if [ "$tool" = "glab" ]; then
         # `accept` is glab's documented alias of `mr merge` (same help text).
         if [ "${1:-}" = "mr" ] && { [ "${2:-}" = "merge" ] || [ "${2:-}" = "accept" ]; }; then
@@ -755,6 +756,7 @@ printf '%s\n' "$masked" | tr ';|&(){}' '\n' | while IFS= read -r seg; do
               # value-taking flags: consume the value so it is not mistaken
               # for the MR id positional (`glab mr merge --sha abc 546`).
               --sha|-m|--message|--squash-message) [ $# -ge 2 ] && shift ;;
+              -h|--help) help=1 ;;
               -*) : ;;
               *)
                 if [ "$mid" = "?" ] && [ -z "${id_seen:-}" ]; then
@@ -826,6 +828,7 @@ printf '%s\n' "$masked" | tr ';|&(){}' '\n' | while IFS= read -r seg; do
               # value-taking flags: consume the value so it is not mistaken
               # for the PR id positional.
               -b|--body|-F|--body-file|-t|--subject|--match-head-commit|-A|--author-email) [ $# -ge 2 ] && shift ;;
+              -h|--help) help=1 ;;
               -*) : ;;
               *)
                 if [ "$mid" = "?" ] && [ -z "${id_seen:-}" ]; then
@@ -876,7 +879,11 @@ printf '%s\n' "$masked" | tr ';|&(){}' '\n' | while IFS= read -r seg; do
         # the id unresolvable so bound grants deny (unbound grants keep the
         # agent-side duty to target the discussed MR — documented residual).
         [ "$retarget" = 1 ] && mid="?"
-        if [ "$auto" = 1 ]; then echo DENY_AUTO; else
+        # A help flag in flag position means the CLI prints help and merges
+        # nothing; deny it without touching any grant. A help token taken as a
+        # known flag's value never reaches here, and an unknown value-taking
+        # flag only makes this deny a real merge, never release one.
+        if [ "$help" = 1 ]; then echo DENY_HELP; elif [ "$auto" = 1 ]; then echo DENY_AUTO; else
           echo "DENY_MR $mid $spell"
           # A single segment carrying multiple aliased merge mutations emits a
           # second DENY_MR so the >1 exactly-one-per-command guard denies it.
@@ -1066,6 +1073,9 @@ fi
 if printf '%s\n' "$verdicts" | grep -q '^DENY_GIT_UNRESOLVED$'; then
   deny "$DENY_TEXT_GIT_UNRESOLVED"
 fi
+if printf '%s\n' "$verdicts" | grep -q '^DENY_HELP$'; then
+  deny "$DENY_TEXT_HELP"
+fi
 if printf '%s\n' "$verdicts" | grep -q '^DENY_AUTO'; then
   deny "$DENY_TEXT_AUTO"
 fi

package/dist/assets/marketplace/plugins/ccl-skills/hooks/host-input.py

@@ -13,6 +13,7 @@ import re
 import shlex
 import stat
 import sys
+import tempfile
 
 # Hook assets may be installed read-only; importing the optional state helper
 # must not create bytecode beside them.
@@ -626,6 +627,23 @@ def delivery_eligible(summary):
             or summary['continuation_contract_visible'])
 
 
+# Stops kept surviving the recheck by restating the blocker in a new term, so
+# the test is stated as an invariant (who can act) and the observed terms are
+# only examples of restatements that fail it.
+NOT_BLOCKERS = (
+    'A blocker names something only the user can supply: a decision the evidence cannot settle, a credential '
+    'or access grant, permission the goal does not cover, or a fact absent from every source you can read. '
+    'A next step you can perform yourself is not a blocker, whatever it costs in time or runs: a fix with its '
+    'tests and review, a branch push and MR/PR, marking that MR/PR ready once your own checks pass instead of '
+    'leaving it in Draft, waiting on a CI run you can poll, a rerun or retry of a failed, timed-out or '
+    'inconclusive check, or a lookup. Restatements observed to fail this test: "you only asked me to investigate" — a failure or '
+    'diagnosis goal includes the verified fix, tests, review, branch push and MR/PR to the development target '
+    'unless an explicit user limit says otherwise (diagnosis only, no push); "pushing or opening an MR is outward-facing" — a feature branch '
+    'and its MR/PR are routine; a count, round or stop bar you proposed yourself, unless the user adopted it as '
+    'a limit; "the check can only restart '
+    'from scratch"; and facts, logs, test data or access you can find or reuse yourself. A clarifying question '
+    'is not a status-only request: answer it, then continue. ')
+
 # One bounded recheck (host stop_hook_active) for stops that hand work back to
 # the user; it names the real blockers and grants no authority.
 DECISION_RECHECK = {'decision': 'block', 'reason': (
@@ -633,7 +651,8 @@ DECISION_RECHECK = {'decision': 'block', 'reason': (
     'Real blockers are: missing credentials or authority; a fact unavailable from local evidence; '
     'an action the safety rules gate (destructive or irreversible without recovery, production or '
     'customer data, merge or publication outside the goal); overturning an established user direction; '
-    'or a material product tradeoff the evidence cannot settle. An ordinary change needs no human review, '
+    'or a material product tradeoff the evidence cannot settle. ' + NOT_BLOCKERS +
+    'An ordinary change needs no human review, '
     'sign-off or risk owner: run the self-review and external review yourself. '
     'Small tests and routine development/test-environment operations within the authorized task '
     'run directly with configured accounts; do not ask for per-run approval or invent a cost cap. '
@@ -649,10 +668,77 @@ DECISION_RECHECK = {'decision': 'block', 'reason': (
     'This reminder supplies no new goal or authorization.')}
 
 
+# Reader-facing documents edited in a session owe the tighten-doc closeout
+# readback (the routing rule says so), yet it was skipped in 26 of 29 observed
+# sessions. Agent-facing files are excluded: skill bodies, contracts, memory
+# and scratch or temporary paths.
+READER_DOC_SUFFIXES = ('.md', '.mdx', '.rst')
+AGENT_DOC_NAMES = {'skill.md', 'agents.md', 'claude.md', 'memory.md'}
+AGENT_DOC_DIRS = {'memory', '.claude', '.codex', '.git', 'node_modules', 'skills', 'agent-context',
+                  'scratchpad'}
+
+
+def reader_docs(edit_paths, cwd):
+    base = os.path.realpath(cwd) if isinstance(cwd, str) and cwd else None
+    temp_roots = tuple(os.path.realpath(root) + os.sep
+                       for root in {tempfile.gettempdir(), '/tmp', '/private/tmp', '/var/folders'})
+    found = []
+    for path in edit_paths:
+        if not isinstance(path, str) or not path.lower().endswith(READER_DOC_SUFFIXES):
+            continue
+        real = os.path.realpath(path)
+        if base and (real == base or real.startswith(base + os.sep)):
+            parts = os.path.relpath(real, base).split(os.sep)
+        elif real.startswith(temp_roots):
+            continue
+        else:
+            parts = real.split(os.sep)
+        if parts[-1].lower() in AGENT_DOC_NAMES or any(p.lower() in AGENT_DOC_DIRS for p in parts[:-1]):
+            continue
+        found.append(real)
+    return found
+
+
+def doc_closeout_note(payload):
+    path, cwd = payload.get('transcript_path'), payload.get('cwd')
+    if not isinstance(path, str) or not path:
+        return ''
+    cwd = cwd if isinstance(cwd, str) else os.getcwd()
+    try:
+        summary = transcript(path, cwd)
+    except TranscriptTruncated:
+        summary = context_transcript(path, cwd)
+    except (OSError, ValueError):
+        return ''
+    if any(skill.split(':')[-1] == 'tighten-doc' for skill in summary['completed_skills']):
+        return ''
+    docs = reader_docs(summary['edit_paths'], cwd)
+    if not docs:
+        return ''
+    names = ', '.join(sorted({os.path.basename(doc) for doc in docs})[:5])
+    return ('Document closeout: this session edited reader-facing documents ({}) without loading '
+            'tighten-doc. Load it and run its closeout readback on those documents before finishing; '
+            'the substance stays as the owning skill decided.'.format(names))
+
+
 def proposed_next(payload):
     if (not isinstance(payload, dict) or payload.get('hook_event_name') != 'Stop'
             or payload.get('stop_hook_active') is not False):
         return None
+    result = delivery_reminder(payload)
+    try:
+        note = doc_closeout_note(payload)
+    except Exception:  # advisory: a failed document check never costs the reminder
+        note = ''
+    if not note:
+        return result
+    if not result:
+        return {'decision': 'block', 'reason': note + ' Then end with the same proposed-next: line. '
+                'This reminder supplies no new goal or authorization.'}
+    return {'decision': 'block', 'reason': note + ' ' + result['reason']}
+
+
+def delivery_reminder(payload):
     final = payload.get('last_assistant_message')
     if not isinstance(final, str) or not final.strip() or machine_artifact(final):
         return None
@@ -674,7 +760,8 @@ def proposed_next(payload):
             'authorized and runnable, execute it now instead of waiting for another continue message. '
             'For unrun, failed or inconclusive checks, continue available diagnosis, research, safe repair '
             'and retesting; a report alone does not complete implementation. Respect explicit stop, '
-            'planning-only and status-only requests. If a user decision or missing authority/resource '
+            'planning-only and status-only requests. ' + NOT_BLOCKERS +
+            'If a user decision or missing authority/resource '
             'prevents action, report the concrete blocker; do not invent work or bypass a failed gate. '
             'This reminder supplies no new goal or authorization.')}
     path = payload.get('transcript_path')

package/dist/assets/marketplace/plugins/ccl-skills/hooks/remind-post-merge-cleanup.sh

@@ -72,6 +72,11 @@ masked=$(printf '%s' "$cmd" | sed -E \
 # NON-fire — `glab mr merge` / `gh pr merge` is the near-universal agent merge
 # path, and the human-readable cleanup rule in worktree-isolation SKILL.md +
 # bootstrap covers EVERY merge path regardless of this reminder.
+# `gh help pr merge` / `glab help mr merge` print help (the merge guard's help
+# denial points there). Remove only those literal invocations, never a prefix,
+# so a real merge before or after them in the same command still matches.
+masked=$(printf '%s' "$masked" | sed -E \
+  's/(glab|gh)[[:space:]]+help[[:space:]]+(mr|pr)[[:space:]]+(merge|accept)([[:space:]]|$)/ /g')
 printf '%s' "$masked" | grep -Eq \
   'glab[[:space:]]([^&|;]*[[:space:]])?mr[[:space:]]+(merge|accept)([[:space:]]|$)|gh[[:space:]]([^&|;]*[[:space:]])?pr[[:space:]]+merge([[:space:]]|$)' \
   || exit 0

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_guard_merge_authorization.sh

@@ -1035,6 +1035,44 @@ for invalidation in '停止' '改成另一个功能'; do
 done
 unset RACE_SENT RACE_REACHED RACE_RESUME REAL_MV
 
+# A help probe merges nothing, so it must never consume a grant. Observed: an
+# agent added --auto-merge=false to `glab mr merge --help` to pass the spelling
+# check, the probe consumed the one-shot grant, and the real merge was denied.
+# Earlier cases leave epoch files for this session; clear them so each probe
+# meets a valid grant rather than an epoch mismatch (which also denies).
+rm -f "$VAUTH_DIR/$VSID.epoch" "$VAUTH_DIR/$VSID.grant-epoch"
+for help_cmd in 'glab mr merge --help --auto-merge=false' 'glab mr merge 123 -h --auto-merge=false --yes' \
+                'gh pr merge 45 --merge --help' 'gh pr merge --squash -h'; do
+  varm
+  probe_sid deny "$FEAT_CWD" "$VSID" "$help_cmd"
+  sentinel_state present "help probe kept the grant: $help_cmd"
+done
+varm
+reason_help=$(jq -nc --arg c 'glab mr merge --help --auto-merge=false' --arg w "$FEAT_CWD" --arg s "$VSID" \
+  '{tool_input:{command:$c},cwd:$w,session_id:$s}' | TMPDIR="$tmp" bash "$GUARD")
+if printf '%s' "$reason_help" | grep -q 'glab help mr merge'; then pass=$((pass+1)); else
+  fail=$((fail+1)); echo 'FAIL help denial must name the non-merge help form' >&2; fi
+rm -f "$VAUTH_DIR/$VSID"
+# A value-taking flag swallows a following --help: the command still merges.
+varm
+probe_sid allow "$FEAT_CWD" "$VSID" 'glab mr merge 123 -m --help --auto-merge=false --yes'
+sentinel_state absent 'a --help message value is a real merge and consumes the grant'
+probe allow "$FEAT_CWD" 'glab help mr merge'
+probe allow "$FEAT_CWD" 'gh help pr merge'
+# A help probe compounded with a real merge denies the whole command and keeps
+# the grant; a quoted --help message value is masked and stays a real merge.
+varm
+probe_sid deny "$FEAT_CWD" "$VSID" 'glab mr merge 123 --auto-merge=false --yes && glab mr merge --help'
+sentinel_state present 'help compounded with a merge keeps the grant'
+rm -f "$VAUTH_DIR/$VSID"
+varm
+probe_sid allow "$FEAT_CWD" "$VSID" 'glab mr merge 123 -m "--help" --auto-merge=false --yes'
+sentinel_state absent 'a quoted --help message is a real merge and consumes the grant'
+# Without any grant a help probe is denied and creates no grant.
+rm -f "$VAUTH_DIR/$VSID"
+probe_sid deny "$FEAT_CWD" "$VSID" 'gh pr merge 45 --merge --help'
+sentinel_state absent 'a help probe without a grant creates nothing'
+
 if [ "$fail" -ne 0 ]; then
   echo "test_guard_merge_authorization: FAIL pass=$pass fail=$fail" >&2
   exit 1

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_merge_authorization_prompt.sh

@@ -213,6 +213,17 @@ done
 send '批量合并 3'
 send '继续'
 if [ ! -f "$SENT" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo 'FAIL legacy batch still clears on neutral prompt' >&2; fi
+# A host task notification reaches this hook with no field that tells it apart
+# from typed text, so it is handled as a user message: it revokes single and
+# counted grants (a stop typed in its markup must still revoke) and never arms.
+note=$'<task-notification>\n<task-id>abc123</task-id>\n<status>completed</status>\n<summary>Background command "wait for CI" completed (exit code 0)</summary>\n</task-notification>'
+send '批量合并 3'
+send "$note"
+if [ ! -f "$SENT" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo 'FAIL a notification must revoke a counted grant' >&2; fi
+send '合并'
+send $'<task-notification>\n<summary>先别合并</summary>\n</task-notification>'
+if [ ! -f "$SENT" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo 'FAIL a stop inside notification markup must revoke' >&2; fi
+expect_not_armed $'<task-notification>\n<summary>合并</summary>\n</task-notification>'
 git -C "$tmp/repo" remote set-url origin 'https://user:password@example.invalid/team/project.git'
 expect_not_armed '完成并合并 PR #123'
 git -C "$tmp/repo" remote set-url origin 'git@example.invalid:team/project.git'

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_proposed_next.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 """Synthetic native Stop payloads; no real host state or conversations."""
+import importlib.util
 import json
 import os
 from pathlib import Path
@@ -7,6 +8,7 @@ import shutil
 import subprocess
 import tempfile
 import unittest
+from unittest.mock import patch
 
 ROOT = Path(__file__).resolve().parents[1]
 
@@ -341,6 +343,115 @@ class ProposedNextTests(unittest.TestCase):
                 self.assertIn('supplies no new goal or authorization', result['reason'])
                 self.assertEqual(self.run_hook(dict(payload, stop_hook_active=True)), {})
 
+    def test_diagnosis_scope_and_question_turn_are_named_in_both_reminders(self):
+        # Observed stops after a verified root cause: the agent read "missing
+        # authority" as "you only asked me to investigate", and a clarifying
+        # question as a status-only request. Both reminders must close those terms.
+        for events in ([], self.claude_load()):
+            self.events(events)
+            for text in (
+                    'Fixing it changes shared code and opens an MR, beyond the investigation you asked for.\n'
+                    'proposed-next: blocked: limit fix, consistency test and MR — waiting for you to authorize the code change',
+                    '这一轮你只问了一个问题，我只解释了现状。\n'
+                    'proposed-next: blocked: 上限修复、补测试、提 MR——改共享仓库需要你确认',
+                    'Root cause verified.\nproposed-next: open a branch, fix the limit, add the test and open the MR',
+                    'Required CI passed; the advisory review timed out and its evidence was cleared.\n'
+                    'proposed-next: blocked: complete the CI review — no resume handle; a retry restarts from scratch',
+                    'Both MRs pushed; required CI is still running, the MRs stay in Draft.\n'
+                    'proposed-next: wait for CI to finish and for your merge confirmation'):
+                with self.subTest(text=text):
+                    result = self.run_hook(dict(self.payload, last_assistant_message=text))
+                    self.assert_block(result)
+                    self.assertIn('you only asked me to investigate', result['reason'])
+                    self.assertIn('failure or diagnosis goal includes the verified fix', result['reason'])
+                    # Closing the terms must not widen past an explicit user
+                    # limit: a "fix locally, do not push" instruction still binds.
+                    self.assertIn('unless an explicit user limit says otherwise (diagnosis only, no push)',
+                                  result['reason'])
+                    self.assertIn('clarifying question is not a status-only request', result['reason'])
+                    self.assertIn('outward-facing" — a feature branch and its MR/PR are routine', result['reason'])
+                    self.assertIn('stop bar you proposed yourself', result['reason'])
+                    self.assertIn('A blocker names something only the user can supply', result['reason'])
+                    self.assertIn('a rerun or retry of a failed, timed-out or inconclusive check', result['reason'])
+                    self.assertIn('marking that MR/PR ready once your own checks pass', result['reason'])
+                    self.assertIn('waiting on a CI run you can poll', result['reason'])
+                    self.assertIn('supplies no new goal or authorization', result['reason'])
+
+    def doc_edit(self, relative, tool_id='doc', tool='Write'):
+        target = str(self.root / relative)
+        return [
+            {'type': 'assistant', 'message': {'content': [{'type': 'tool_use', 'id': tool_id,
+             'name': tool, 'input': {'file_path': target, 'content': 'x'}}]}},
+            {'type': 'user', 'message': {'content': [{'type': 'tool_result',
+             'tool_use_id': tool_id, 'is_error': False, 'content': 'written'}]}}]
+
+    def test_reader_doc_edit_without_tighten_doc_gets_one_closeout_reminder(self):
+        # Observed: 26 of 29 sessions that edited plans, specs, READMEs or
+        # handoff documents never loaded tighten-doc before finishing.
+        status = 'Plan updated.\nproposed-next: none — status only'
+        for relative in ('docs/plans/rollout.md', 'README.md', 'handoffs/state.md', 'specs/9-x/plan.md'):
+            with self.subTest(relative=relative):
+                self.events(self.doc_edit(relative))
+                result = self.run_hook(dict(self.payload, last_assistant_message=status))
+                self.assert_block(result)
+                self.assertIn('tighten-doc', result['reason'])
+                self.assertIn(Path(relative).name, result['reason'])
+                self.assertIn('supplies no new goal or authorization', result['reason'])
+                self.assertEqual(self.run_hook(dict(self.payload, last_assistant_message=status,
+                                                    stop_hook_active=True)), {})
+
+    def test_doc_reminder_is_quiet_after_tighten_doc_or_for_agent_files(self):
+        status = 'Plan updated.\nproposed-next: none — status only'
+        self.events(self.claude_load('tighten-doc') + self.doc_edit('docs/plans/rollout.md'))
+        self.assertEqual(self.run_hook(dict(self.payload, last_assistant_message=status)), {})
+        for relative in ('skills/x/SKILL.md', 'AGENTS.md', 'CLAUDE.md', 'memory/note.md',
+                         '.claude/notes.md', 'src/app.py', 'notes.txt'):
+            with self.subTest(relative=relative):
+                self.events(self.doc_edit(relative))
+                self.assertEqual(self.run_hook(dict(self.payload, last_assistant_message=status)), {})
+
+    def test_doc_reminder_joins_a_continuation_reminder(self):
+        self.events(self.doc_edit('docs/plans/rollout.md'))
+        result = self.run_hook(dict(self.payload,
+                                    last_assistant_message='proposed-next: run the remaining local checks'))
+        self.assert_block(result)
+        self.assertIn('execute it now', result['reason'])
+        self.assertIn('tighten-doc', result['reason'])
+
+    def test_doc_reminder_covers_each_file_edit_tool(self):
+        # Edits are seen through the file-edit tool calls the transcript records;
+        # shell writes are outside this check by design.
+        for tool in ('Edit', 'MultiEdit'):
+            with self.subTest(tool=tool):
+                self.events(self.doc_edit('docs/handoff.md', tool=tool))
+                result = self.run_hook()
+                self.assert_block(result)
+                self.assertIn('handoff.md', result['reason'])
+
+    def test_unreadable_doc_path_never_costs_the_delivery_reminder(self):
+        # The document check is advisory; a path it cannot resolve (an embedded
+        # NUL makes realpath raise) must not replace the continuation reminder
+        # with the "reminder unavailable" notice.
+        self.events(self.doc_edit('docs/plans/roll\x00out.md'))
+        result = self.run_hook(dict(self.payload,
+                                    last_assistant_message='proposed-next: run the remaining local checks'))
+        self.assert_block(result)
+        self.assertIn('execute it now', result['reason'])
+
+    def test_doc_check_failure_never_costs_the_delivery_reminder(self):
+        # The document check is advisory: whatever it raises, the continuation
+        # reminder it would have joined is still returned.
+        self.events(self.doc_edit('docs/plans/rollout.md'))
+        spec = importlib.util.spec_from_file_location('doc_check_probe', self.hooks / 'host-input.py')
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        payload = dict(self.payload, last_assistant_message='proposed-next: run the remaining local checks')
+        with patch.object(module, 'reader_docs', side_effect=RuntimeError('unexpected')):
+            result = module.proposed_next(payload)
+        self.assert_block(result)
+        self.assertIn('execute it now', result['reason'])
+        self.assertNotIn('tighten-doc', result['reason'])
+
     def test_quoted_actions_do_not_turn_a_status_handoff_into_work(self):
         self.events(self.claude_load())
         for suffix in ('\n> proposed-next: deploy', '\n```text\nproposed-next: deploy\n```'):

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_remind_post_merge_cleanup.sh

@@ -113,6 +113,18 @@ probe_json remind 'glab mr merge 123 --yes'  '{"stdout":"Merged !123"}'
 # --- --help / -h is not a merge → quiet ---
 probe quiet 'gh pr merge --help'
 probe quiet 'glab mr merge -h'
+# The help subcommand form, which the merge guard's help denial points to,
+# prints help and merges nothing.
+probe quiet 'gh help pr merge' 'Merge a pull request on GitHub.'
+probe quiet 'glab help mr merge' 'Merges a merge request.'
+probe quiet 'gh help pr merge 2>&1 | grep -- --match-head-commit' '--match-head-commit SHA'
+# A real merge beside a help lookup in one command still reminds, whichever
+# comes first: only the help invocation itself is set aside.
+probe remind 'gh help pr merge >/dev/null; gh pr merge 45 --merge' 'Merged'
+probe remind 'glab help mr merge && glab mr merge 123 --yes' 'Merged !123'
+probe remind 'gh pr merge 45 --merge # see gh help pr merge' 'Merged'
+probe remind 'gh pr merge 45 --merge $(gh help pr merge >/dev/null)' 'Merged'
+probe remind 'glab mr merge 123 --yes; glab help mr merge' 'Merged !123'
 # a successful-looking string response still reminds
 probe remind 'glab mr merge 123 --yes' 'Merged! https://.../merge_requests/123'
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/defect-diagnosis/SKILL.md

@@ -16,7 +16,7 @@ Diagnose and fix from evidence; route prevention to product, architecture, devel
 - Do not call a workaround the fix unless the owner explicitly accepts the tradeoff and residual risk is recorded.
 - Do not start broad refactoring while the cause is unknown. Isolate and fix first; refactor after the behavior is understood.
 - Do not stop at "this line was wrong" when the defect reveals a missing contract, guardrail, test, review check, or skill rule.
-- Do not state or act on a root-cause verdict — even as a confident aside — before you have read the failing owner's own evidence with your own eyes (assertion diff for a test, stack/exception for a crash, trace/log slice for a production symptom, source only when it is itself the failing artifact). Until then, label every cause as a hypothesis and name the evidence that would confirm or reject it. This applies to your OWN analysis, not only to LLM-proposed causes. Mitigation is exempt: you may roll back, flag-off, or shed traffic from symptoms while cause stays marked unknown — what is forbidden is choosing or applying a *fix* as though a cause is proven.
+- Do not state or act on a root-cause verdict — even as a confident aside — before you have read the failing owner's own evidence with your own eyes (assertion diff for a test, stack/exception for a crash, trace/log slice for a production symptom, source only when it is itself the failing artifact). Until then, label every cause as a hypothesis and name the evidence that would confirm or reject it. This applies to your OWN analysis, not only to LLM-proposed causes. Mitigation is exempt: you may roll back, flag-off, or shed traffic from symptoms while cause stays marked unknown — what is forbidden is choosing or applying a *fix*, or handing the user a decision or tradeoff that rests on the cause, as though a cause is proven. While a falsifying check is runnable, run it before asking anyone to choose.
 
 ## Phase A: Diagnose
 
@@ -47,7 +47,7 @@ Diagnose and fix from evidence; route prevention to product, architecture, devel
    - **A test that passes alone and fails in the suite must be bisected over the tests that run before it** — only for a failure that reproduces on every run under a fixed serial order (parallel or intermittent failures keep the failing schedule and validate each kept or dropped subset over repeated runs per the flaky rule, or route to concurrency diagnosis): halve the preceding set in order and keep a failing half; when neither half fails alone, remove one chunk at a time and keep the reduced set whenever the failure persists without that chunk, then halve the chunk size and repeat until every remaining chunk is needed (a minimal ordered polluting subsequence) or the shared fixture/state is found; the same reduction isolates a failing input, config, or dataset when no commit range exists (moves in `references/diagnosis-playbook.md`).
    - Identify whether the failure is in product logic, contract mapping, persistence, cache, async processing, dependency behavior, runtime config, release state, or test setup.
    - If the failure appears only in tests or CI, classify the test evidence before changing code: deterministic assertion, fixed external data, live infrastructure, random/log-only behavior, long sleep, allow-failure gate, generated/vendor test, or deploy/build-only pipeline.
-   - **A red CI pipeline/job is not by itself a code/dependency defect — read the failing job's own trace (not the red/green summary) and classify the cause before touching code.** Refining the classes above into why-CI-is-red-but-code-may-be-fine: (a) **trigger-variant artifact** — when the same job runs under more than one trigger-scoped config (branch/push vs merge-request vs manual/scheduled), the trigger can resolve different default variables or a different checked-out ref, so a red on a non-gating trigger may be benign — but conclude that ONLY after confirming the *same failing check* ran and is green on the gating path (a gating pipeline that is overall green yet never runs the failing check does not clear it; if that check's coverage is unique to the non-gating trigger — e.g. a scheduled/manual-only suite — treat it as genuine (d), not a variant artifact); (b) **retriable infra flake** — e.g. a shared-runner lock collision: confirm per the flaky rule below (rerun N times + record the ratio; a 100%-reproducible red is deterministic, not a flake), and still read the red run's trace for the collision signature, since one green rerun cannot separate an infra flake from a genuine intermittent code bug; (c) **deterministic non-code infra fault** — toolchain/runner-image drift, stale cache/vendored artifact, credential/quota expiry: reproduces identically (NOT a flake) AND must be shown **code-independent** before disowning — confirm the same failure reproduces on a known-good baseline (parent/last-good commit, or a build without the change) under the same runner/toolchain; if the red appears only *with* the change it is (d) however much it resembles drift → route to platform/infra only after that baseline check, then do not attribute to code; (d) **genuine code/dependency failure**. (Single-variant repos skip the (a) check; the trace-first and cause-classification still apply.)
+   - **A red CI pipeline/job is not by itself a code/dependency defect — read the failing job's own trace (not the red/green summary) and classify the cause before touching code.** Classify it as a trigger-variant artifact, a retriable infra flake, a deterministic non-code infra fault, or a genuine code/dependency failure using the checks in `references/diagnosis-playbook.md` (Red CI cause classes) before disowning or touching code.
    - **For a failing test, read the actual assertion error (Expected/Actual) and the failing test body FIRST — before diagnosing flakiness, concurrency, shared state, mock setup, or external-dependency causes.** A passing/failing count, a `REQUEST POST`-style debug log line, or "passes in isolation, fails in suite" is a symptom, not the assertion evidence; naming a cause from those alone is the exact failure this skill exists to prevent. If the test is suspected flaky, rerun N times and record the pass/fail ratio before calling it flaky (100% reproducible failure is deterministic, not flaky), and confirm the test's network/dependency boundary by reading its setup (e.g. whether it is already mocked) rather than inferring from logs.
 
 3. Hypothesize.
@@ -76,7 +76,7 @@ Diagnose and fix from evidence; route prevention to product, architecture, devel
 5. Verify cause.
    - Prove the cause with evidence.
    - **A diagnosis licenses a fix only when it explains both causality and incorrectness**: how the defect produced this failure on the failing path, and why that code, data, or config is wrong against its contract — so the fix covers related failures. A change that makes the failure disappear without the second half is a symptom patch; a genuine defect that cannot be linked to this failure is a different bug — record it, never ship it as this cause.
-   - Report query/lookup evidence by cardinality: a data query, log search, or identity resolution that returns 0, 1, or N matches reports each of those outcomes distinctly — never silently take the first row of N, and never treat 0 rows as "no evidence collected" (an empty result over a named scope IS evidence: record which scopes matched and which were empty).
+   - Report query/lookup evidence by cardinality: a data query, log search, or identity resolution that returns 0, 1, or N matches reports each of those outcomes distinctly — never silently take the first row of N, and never treat 0 rows as "no evidence collected" (an empty result over a named scope IS evidence: record which scopes matched and which were empty). A zero failure count says something only after the scope's exposure is confirmed — the path was live and exercised in that window; zero failures from a path that never ran is no data, not health.
    - When the cause is environment/toolchain state, prove it from the tool that owns that state, not only from the high-level wrapper. A wrapper failure is a symptom until the underlying compiler, generator, runtime registry, dependency resolver, or platform destination evidence explains it.
    - If disproven, return to hypotheses instead of guessing.
    - Separate symptom, immediate cause, contributing factors, and prevention.
@@ -93,6 +93,10 @@ The hypothesize → instrument → verify loop must not run forever, and escalat
 
 ## Phase B: Fix And Verify
 
+A failure or diagnosis goal carries this phase. Once the cause is verified, fix, test, review, push the branch and open or update the MR/PR to the repository's development target in the same delivery. "You only asked me to investigate" is not missing authority, and a "read-only" note on one step of a handoff binds that step only.
+
+- Every explicit user limit and existing gate must still stop the step it covers, for example diagnosis only (只查 / 先别改), no push, a cost or run cap, a repository's confirm-first areas, the shared-gate route below, destructive actions, purchases, and merge, deploy or production steps.
+
 1. Fix minimally.
    - Address the proven cause with the smallest correct change.
    - Preserve contracts unless the task explicitly requires a contract change.

package/dist/assets/marketplace/plugins/ccl-skills/skills/defect-diagnosis/references/diagnosis-playbook.md

@@ -65,6 +65,10 @@ Locating the defect is usually the most expensive phase — harder than reproduc
 | Wrong value observed downstream | upstream trace | follow the value backward to the first point where a correct input produced a wrong output; that transition is the defect and the observation point is only where it surfaced — fix there when it is owned and changeable, otherwise record the upstream cause and enforce the contract at the nearest owned boundary |
 | Production symptom that cannot be re-triggered | telemetry walk | alert → exemplar trace → span tree → logs by trace-id (SKILL.md Phase A.4); group the failing population by attribute and compare it against the baseline to find what is different about failing requests |
 
+## Red CI Cause Classes
+
+- A red CI pipeline/job is not by itself a code/dependency defect; read the failing job's own trace (not the red/green summary) and classify the cause before touching code. Refining the test-evidence classes in the entrypoint's Phase A Isolate step into why-CI-is-red-but-code-may-be-fine: (a) **trigger-variant artifact** — when the same job runs under more than one trigger-scoped config (branch/push vs merge-request vs manual/scheduled), the trigger can resolve different default variables or a different checked-out ref, so a red on a non-gating trigger may be benign — but conclude that ONLY after confirming the *same failing check* ran and is green on the gating path (a gating pipeline that is overall green yet never runs the failing check does not clear it; if that check's coverage is unique to the non-gating trigger — e.g. a scheduled/manual-only suite — treat it as genuine (d), not a variant artifact); (b) **retriable infra flake** — e.g. a shared-runner lock collision: confirm per the entrypoint's flaky-test rule (rerun N times and record the ratio) (rerun N times + record the ratio; a 100%-reproducible red is deterministic, not a flake), and still read the red run's trace for the collision signature, since one green rerun cannot separate an infra flake from a genuine intermittent code bug; (c) **deterministic non-code infra fault** — toolchain/runner-image drift, stale cache/vendored artifact, credential/quota expiry: reproduces identically (NOT a flake) AND must be shown **code-independent** before disowning — confirm the same failure reproduces on a known-good baseline (parent/last-good commit, or a build without the change) under the same runner/toolchain; if the red appears only *with* the change it is (d) however much it resembles drift → route to platform/infra only after that baseline check, then do not attribute to code; (d) **genuine code/dependency failure**. (Single-variant repos skip the (a) check; the trace-first and cause-classification still apply.)
+
 ## Probe Ordering And The Hypothesis Log
 
 Order probes; do not merely list hypotheses. For each candidate cause record the observation only it produces, the observation that cannot occur if it is true (the falsifier — collect this one first), what the probe costs, and what it risks. Then apply the entrypoint's one ordering rule: safety is a filter, not a rank — reject any probe outside the safety boundary first; rank the rest by alternatives ruled out per unit of cost; break ties by likelihood, then residual risk. Watch for confounders (a probe run from the wrong host, credential, or network position fails for its own reasons), side effects of active probes (more CPU changes race timing; verbose logging worsens latency — revert before the next probe), and probes that are only suggestive (races, deadlocks): record the evidence grade next to the result.