Problem Statement
Pull Request #60 added approximately 5,000 lines of documentation and a verification tool. While the intent was to provide comprehensive extensibility guidance, the current documentation contains significant "hallucinations"—referencing API commands, event types, and JSON schemas that do not exist in the actual Go implementation.
As a fast-moving project, we must ensure that our "LLM guidance" (the docs LLMs use to understand the repo) is 100% accurate, or we risk a "hallucination loop" where the AI continues to build on non-existent foundations.
Objectives
Audit & Reconcile: Align all new documentation with the current code implementation.
Harden Tooling: Upgrade the verify-docs tool to use AST parsing/reflection instead of hardcoded checks.
CI Integration: Block PRs that introduce documented features not present in the code.
LLM Guardrails: Update repository instructions to prioritize "code-first" truth.
Technical Tasks
- Documentation Reconciliation (Truth-Checking)
The following files must be audited against the source code. Delete any section referencing a feature that is not yet implemented.
Socket API: Reconcile docs/extending/SOCKET_API.md against internal/daemon/daemon.go. Ensure the "20+ commands" claimed are actually supported in the switch statement of the daemon.
Event Hooks: Reconcile docs/extending/EVENT_HOOKS.md against internal/events/events.go. Verify that every event type (e.g., session.created) is actually defined as a constant and emitted in the code.
State Schema: Reconcile docs/extending/STATE_FILE_INTEGRATION.md against internal/state/state.go. Ensure field names match (check for snake_case vs camelCase discrepancies).
Code Examples: Validate all 50+ code examples in the docs/ folder.
Requirement: Every Go example must compile.
Requirement: Every Python/Node example must use existing API endpoints.
- Harden cmd/verify-docs Tool
The current verification tool is likely checking for file existence or matching against hardcoded strings. It must be upgraded to:
Scan Constants: Use Go's go/ast or go/parser to extract valid Socket commands and Event types directly from the source code.
Doc-Sync Check: Parse the Markdown files and flag any command/event mentioned in the docs that is not found in the extracted code constants.
Schema Validation: Compare the JSON examples in the docs against the Go struct definitions using reflection or a schema generator.
- Implement CI Gates
Add a GitHub Action (.github/workflows/verify-docs.yml) that:
Runs go run cmd/verify-docs/main.go.
Fails if there is a mismatch between the implementation and the documentation.
(Optional) Runs a "Doc Lint" to ensure all links and code blocks are valid.
- Update LLM Guardrails (CLAUDE.md)
Add the following rules to the "Development Patterns" or "Extensibility" section of CLAUDE.md:
Rule: "Never document an API, command, or event that does not exist in the current main branch."
Rule: "If a feature is 'planned' but not implemented, it must be explicitly labeled as [PLANNED] or [PROPOSED] to prevent LLMs from attempting to use it as an active integration point."
Rule: "Always run verify-docs before submitting PRs containing documentation changes."
Acceptance Criteria
[ ] cmd/verify-docs/main.go correctly identifies a missing command when one is deleted from the code but remains in the docs.
[ ] CI is green for this repo, confirming all current docs match the code.
[ ] All 50+ code examples have been verified as functional or removed.
[ ] CLAUDE.md contains the updated guardrails.
Resources
Reference PR: #60
Primary Source of Truth: internal/daemon/, internal/events/, internal/state/
Problem Statement
Pull Request #60 added approximately 5,000 lines of documentation and a verification tool. While the intent was to provide comprehensive extensibility guidance, the current documentation contains significant "hallucinations"—referencing API commands, event types, and JSON schemas that do not exist in the actual Go implementation.
As a fast-moving project, we must ensure that our "LLM guidance" (the docs LLMs use to understand the repo) is 100% accurate, or we risk a "hallucination loop" where the AI continues to build on non-existent foundations.
Objectives
Audit & Reconcile: Align all new documentation with the current code implementation.
Harden Tooling: Upgrade the verify-docs tool to use AST parsing/reflection instead of hardcoded checks.
CI Integration: Block PRs that introduce documented features not present in the code.
LLM Guardrails: Update repository instructions to prioritize "code-first" truth.
Technical Tasks
The following files must be audited against the source code. Delete any section referencing a feature that is not yet implemented.
Socket API: Reconcile docs/extending/SOCKET_API.md against internal/daemon/daemon.go. Ensure the "20+ commands" claimed are actually supported in the switch statement of the daemon.
Event Hooks: Reconcile docs/extending/EVENT_HOOKS.md against internal/events/events.go. Verify that every event type (e.g., session.created) is actually defined as a constant and emitted in the code.
State Schema: Reconcile docs/extending/STATE_FILE_INTEGRATION.md against internal/state/state.go. Ensure field names match (check for snake_case vs camelCase discrepancies).
Code Examples: Validate all 50+ code examples in the docs/ folder.
Requirement: Every Go example must compile.
Requirement: Every Python/Node example must use existing API endpoints.
The current verification tool is likely checking for file existence or matching against hardcoded strings. It must be upgraded to:
Scan Constants: Use Go's go/ast or go/parser to extract valid Socket commands and Event types directly from the source code.
Doc-Sync Check: Parse the Markdown files and flag any command/event mentioned in the docs that is not found in the extracted code constants.
Schema Validation: Compare the JSON examples in the docs against the Go struct definitions using reflection or a schema generator.
Add a GitHub Action (.github/workflows/verify-docs.yml) that:
Runs go run cmd/verify-docs/main.go.
Fails if there is a mismatch between the implementation and the documentation.
(Optional) Runs a "Doc Lint" to ensure all links and code blocks are valid.
Add the following rules to the "Development Patterns" or "Extensibility" section of CLAUDE.md:
Rule: "Never document an API, command, or event that does not exist in the current main branch."
Rule: "If a feature is 'planned' but not implemented, it must be explicitly labeled as [PLANNED] or [PROPOSED] to prevent LLMs from attempting to use it as an active integration point."
Rule: "Always run verify-docs before submitting PRs containing documentation changes."
Acceptance Criteria
[ ] cmd/verify-docs/main.go correctly identifies a missing command when one is deleted from the code but remains in the docs.
[ ] CI is green for this repo, confirming all current docs match the code.
[ ] All 50+ code examples have been verified as functional or removed.
[ ] CLAUDE.md contains the updated guardrails.
Resources
Reference PR: #60
Primary Source of Truth: internal/daemon/, internal/events/, internal/state/