Auto-declare plan and spec documents from a Claude Code PostToolUse hook (blocked on AI-2774 measurement)

[alexeyzimarev]

Follow-up to kurrent-io/kcap-server Linear issue AI-2774 (Plan ledger). Blocked on the adoption measurement in AI-2774: build only if agents are not declaring documents through kcap-plans on their own.

Idea

Declaration without model cooperation, for Claude Code only: a PostToolUse hook on Write / Edit whose target path is under a configured set of plan and spec folders (default: the Superpowers docs/superpowers/plans/ and docs/superpowers/specs/) calls declare_plan_document through the CLI with the kind inferred from the folder. kcap registers no PostToolUse hook today, so this is a new hook command (kcap post-tool-use) with its own settings entry in kcap setup.

Constraints

• Idempotent: repeated writes to the same file re-declare the same key; unchanged content hash writes nothing new server-side.
• Fail open: a server error never blocks the agent's write.
• Folder set is configuration, not code, so other conventions can be added without a release.
• Other harnesses stay on the model-driven path; there is no equivalent hook surface for them.

[linear-code]

AI-2779