vault: session notes 2026-07-10

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

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)

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.

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).