diff --git a/claude-md-budget-linter-plugin-concept.md b/claude-md-budget-linter-plugin-concept.md index 658e431..a79df02 100644 --- a/claude-md-budget-linter-plugin-concept.md +++ b/claude-md-budget-linter-plugin-concept.md @@ -8,14 +8,20 @@ tags: - domain/context-engineering - project/cc-os scope: global -last_updated: 2026-07-08 +last_updated: 2026-07-10 date: 2026-07-08 related: - "[[claude-code-system-prompt-customization-surface]]" + - "[[planka-backlog-routing-discoverability-gap]]" --- # CLAUDE.md budget linter plugin — concept +**Routing decided 2026-07-10:** this belongs inside the **os-doc-hygiene plugin**, not a +standalone plugin — managing CLAUDE.md is doc-hygiene's responsibility. Injected +session-context prompts (os-context) count toward the effective CLAUDE.md instruction +budget and should be noted when doc-hygiene runs. + Status: idea only, deliberately out of scope as of 2026-07-08. Revisit after the system-prompt-profiles work (`cc-os/docs/plans/system-prompt-profiles-assessment.md`). Source discussion: cc-os session 2026-07-08; maintenance philosophy drawn from diff --git a/journal/2026-07-10.md b/journal/2026-07-10.md index ec674d6..7d568f8 100644 --- a/journal/2026-07-10.md +++ b/journal/2026-07-10.md @@ -375,3 +375,10 @@ tags: [scope/global, type/log] **Reason:** other **Vault notes touched:** (none) + +## Session — 2026-07-10T16:25:56Z + +**Project:** /home/jared/servers +**Reason:** prompt_input_exit +**Vault notes touched:** +(none) diff --git a/reference/claude-code-hook-lifecycle-injection-capability.md b/reference/claude-code-hook-lifecycle-injection-capability.md new file mode 100644 index 0000000..2006b7a --- /dev/null +++ b/reference/claude-code-hook-lifecycle-injection-capability.md @@ -0,0 +1,45 @@ +--- +type: reference +title: "Claude Code hook lifecycle — which events can inject model-visible context" +summary: "Which Claude Code hook events can emit additionalContext the model acts on (SessionStart, UserPromptSubmit, PreCompact) versus events that can only run deterministic scripts (SessionEnd) or fire per-turn (Stop), and why session-close rituals must be user-invoked skills rather than hook injections." +tags: + - type/reference + - tool/claude-code + - domain/context-engineering +scope: global +date: 2026-07-10 +last_updated: 2026-07-10 +related: + - "[[claude-code-system-prompt-customization-surface]]" + - "[[memsearch-sessionstart-injection-hardcoded]]" +--- + +# Claude Code hook lifecycle — which events can inject model-visible context + +Not all hook events can put instructions in front of the model. Grouped by capability: + +## Can inject `additionalContext` the model acts on + +- **SessionStart** — fires on `startup|resume|clear|compact` (matcher-selectable). Including + `compact` in the matcher makes injected rules survive context compaction, not just the + first turn. +- **UserPromptSubmit** — per-prompt injection; the mid-session injection point. +- **PreCompact** — can shape what survives compaction. + +## Cannot instruct the model + +- **SessionEnd** — fires *after* the model's last turn. There are no more turns, so emitted + content is never seen by the model. Only useful for deterministic scripts: sync, cleanup, + journaling. +- **Stop** — fires when Claude finishes *every* turn and can block/redirect, but it is + per-turn (noisy) — wrong for once-per-session rituals. + +## Consequence + +A "session-close ritual" (commit + update docs + write handoff) **cannot be a hook +injection** — there is no injection point at session end. It must be a user-invoked +skill/command (e.g. a `/wrap` skill) whose file holds the ritual instructions. + +Corollary design pattern: a SessionStart composer hook (script reads prompt files from a +directory, concatenates, emits as `additionalContext`) is the right home for always-true +session rules; session-*end* model behavior always routes through a command the user types. diff --git a/reference/planka-backlog-routing-discoverability-gap.md b/reference/planka-backlog-routing-discoverability-gap.md new file mode 100644 index 0000000..1ce1716 --- /dev/null +++ b/reference/planka-backlog-routing-discoverability-gap.md @@ -0,0 +1,68 @@ +--- +type: reference +title: "Planka backlog routing is not discoverable by agents — needs project-level pointers and evals" +summary: "Observed failure (2026-07-10): an agent asked to file cc-os work items defaulted to Forgejo/tea because cc-os's own docs still name Forgejo as the tracker and nothing in any project routes agents to the Planka board — the Planka-vs-Forgejo routing rule, doc-hygiene ownership of CLAUDE.md budgets, and the eval work needed to close the gap." +tags: + - type/reference + - tool/planka + - project/cc-os + - domain/task-management +scope: global +date: 2026-07-10 +last_updated: 2026-07-10 +related: + - "[[vault-backlog-pilot-plan]]" + - "[[planka-v2-api-gotchas]]" + - "[[claude-md-budget-linter-plugin-concept]]" + - "[[claude-code-hook-lifecycle-injection-capability]]" +--- + +# Planka backlog routing is not discoverable by agents + +## The observed failure (2026-07-10) + +Asked to file four cc-os work items as "issues," the agent proposed **Forgejo via `tea`** — +not the Planka board. The user had to redirect. Root causes, all verified: + +1. **cc-os's own `docs/issue-workflow.md` still says** "Issues live on Forgejo … use `tea`" + — it predates the Planka pilot and was never updated. +2. **No project-level pointer exists anywhere** (cc-os CLAUDE.md, umbrella CLAUDE.md, + injected context) telling agents the Planka board is the work tracker. The routing rule + lives only in [[vault-backlog-pilot-plan]] — vault knowledge an agent only finds if it + thinks to query the vault about task management. +3. **The documented routing rule itself is ambiguous in practice:** the pilot plan says + "Forgejo = code/arch/deployment work inside a repo; Planka = everything else," yet the + user routed repo code work (plugin refactors) to the cc-os Planka board. The de facto + rule appears to be *Planka = the work tracker; Forgejo issues = execution artifacts when + a coding session wants them* — but this has never been stated crisply anywhere. + +## What filing on Planka actually takes (verified working) + +- Creds: `ssh ovh-vps "cat ~/services/planka/bot-credentials.env"` → `PLANKA_BASE_URL`, + `PLANKA_USERNAME`, `PLANKA_PASSWORD`. +- CLI: `cd ~/dev/ruby-gems/planka && bundle exec ruby exe/backlog add --quick "title" + --board cc-os --list Backlog --priority p1` (`backlog` is not on PATH; gem not installed). +- `add --quick` takes no description — patch it in afterward via + `client.cards.update(id, description: md)`. + +## Action needed (user-stated, 2026-07-10) + +**Run evals on the Planka board integration to ensure all projects know how and when to use +it.** Concretely: given a session in any project where the user asks to "file issues" / +"track this work," does the agent (a) route to the correct Planka board, (b) apply the +Planka-vs-Forgejo rule correctly, (c) find credentials and the CLI without user help? Until +project-level pointers (likely the planned `os-backlog` plugin + per-project CLAUDE.md +lines) exist and evals pass, agents will keep defaulting to whatever tracker a repo's stale +docs name. + +Also stale and needing update once the rule is settled: `~/dev/cc-os/docs/issue-workflow.md`. + +## Related routing decisions made the same session + +- **CLAUDE.md budget management belongs to os-doc-hygiene**, not to the context-injection + plugin: the [[claude-md-budget-linter-plugin-concept]] should be built as part of the + os-doc-hygiene plugin. Managing CLAUDE.md is that plugin's responsibility. +- **Injected session-context prompts count toward the effective CLAUDE.md instruction + budget** — doc-hygiene runs should at minimum note the injected-prompt total alongside + CLAUDE.md length (the os-context composer enforces its own injection cap; doc-hygiene + owns the whole-budget view).