Add Hook Daemon SPEC.md with acceptance criteria#1277
Draft
agentydragon wants to merge 3 commits intodevelfrom
Draft
Add Hook Daemon SPEC.md with acceptance criteria#1277agentydragon wants to merge 3 commits intodevelfrom
agentydragon wants to merge 3 commits intodevelfrom
Conversation
Introduce devinfra/claude/hook_daemon/SPEC.md describing what the hook daemon guarantees to every Claude Code session (common / CLI-only / web-only), with observable acceptance criteria that /web_selfcheck runs against a live session. Add a repo-level SPEC.md convention in AGENTS.md, point the claude README and web_selfcheck skill at the SPEC as the source of truth for a healthy session, and leave a TODO on the BES interceptor noting its --remote_executor nudge is experimental and deliberately not in SPEC yet. BAZEL_TEST_INVOCATIONS=none: documentation-only change (new SPEC.md plus markdown edits to AGENTS.md, README.md, SKILL.md, and a docstring TODO in bes_interceptor.py); no source code behavior changes to test. https://claude.ai/code/session_01MV6VtGgEB5HF5Ws1zS8mgL
Frame web_selfcheck as the runnable acceptance test for the hook daemon SPEC: read SPEC.md, then run one concrete check per numbered criterion (C1-C8 common, CLI1-4, W1-5). Drop prose that restated the SPEC, drop verbose "Fix" recipes (the fix is always "tell the user, daemon broken"), and collapse the old SOPS decryption narrative into the live API tests that already verify the credentials end-to-end. Keep the out-of-SPEC diagnostics that catch real-world failure modes the SPEC does not codify (web_setup.sh freshness, claude-hooks pin staleness, bbr runner recycling, origin URL reachability for bbr) under a clearly-marked Diagnostics section so they can not be confused with SPEC violations. Net: 657 -> 372 lines (-43%). BAZEL_TEST_INVOCATIONS=none: documentation-only change to a single skill markdown file; no source code changes. https://claude.ai/code/session_01MV6VtGgEB5HF5Ws1zS8mgL
Move the bbr runner-recycling / analysis-cache check from web_selfcheck out-of-SPEC diagnostics into SPEC.md as a best-effort guarantee: a second bbr invocation with identical inputs should usually land on a warm runner with the Bazel analysis cache already populated, so the second build is substantially faster than a cold one. Explicitly scope this as best-effort (runners are shared across concurrent sessions today, so transient cold hits are acceptable) rather than a hard guarantee, since we do not yet tag snapshots per session. Add Common acceptance criterion C9 to SPEC.md and the matching check to web_selfcheck SKILL.md; drop the old D3 and renumber the D-check table. BAZEL_TEST_INVOCATIONS=none: documentation-only change to SPEC.md and web_selfcheck SKILL.md; no source code changes. https://claude.ai/code/session_01MV6VtGgEB5HF5Ws1zS8mgL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduce a high-level, user-facing specification for the Claude Code hook daemon that documents what behaviors and guarantees are provided to every session, along with observable acceptance criteria for validation.
Key Changes
New
devinfra/claude/hook_daemon/SPEC.md: Comprehensive specification covering:Updated
AGENTS.md: Added new "SPEC.md — High-level component specifications" section documenting:Updated
skills/web_selfcheck/SKILL.md: Added "What 'Healthy' Means — the Hook Daemon SPEC" section clarifying:Updated
devinfra/claude/README.md: Added "Specification" section directing readers to SPEC.md for high-level behavior documentation before diving into implementation detailsUpdated
devinfra/claude/hook_daemon/bes_interceptor.py: Added TODO comment noting that the BES interceptor nudge behavior is experimental and not yet committed in SPEC.mdNotable Details
The SPEC establishes a clear contract between the hook daemon and the agent, with explicit acceptance criteria that can be validated by the
/web_selfcheckskill. This creates a single source of truth for what behaviors are guaranteed vs. implementation details.https://claude.ai/code/session_01MV6VtGgEB5HF5Ws1zS8mgL