diff options
| -rw-r--r-- | .ai/session-context.org | 151 | ||||
| -rw-r--r-- | .ai/sessions/2026-05-07-10-06-mcp-tokens-doctor-and-voice.org | 310 |
2 files changed, 310 insertions, 151 deletions
diff --git a/.ai/session-context.org b/.ai/session-context.org deleted file mode 100644 index 8c3afba..0000000 --- a/.ai/session-context.org +++ /dev/null @@ -1,151 +0,0 @@ -#+TITLE: Session Context — first-session setup + Makefile picker + work/deepsat reorg + skill-budget test -#+AUTHOR: Craig Jennings & Claude -#+DATE: 2026-05-06 - -* Summary - -** Active Goal - -*Picking up after a session restart.* The first thing to do is verify the in-flight test: did adding =disable-model-invocation: true= to =~/code/rulesets/.claude/commands/arch-document.md= remove its description from the model's preloaded skill listing? See the *Next Steps* section for the decision tree. - -** Decisions - -- Project type: content/documentation. =.ai/= is committed. -- =install-lang= should fzf-pick =LANG== when not set, mirroring how =PROJECT== was already picked. -- Move =~/code/deepsat/= → =~/projects/work/deepsat/code/= and rename =~/projects/career/= → =~/projects/work/=. No backwards-compat symlinks. -- Test the skill-budget hypothesis on *one* command (=arch-document=) before mass-editing the other 17. -- Forward-rewrite forward-looking org files in =work/= to point at the new path. Leave session archives untouched. - -** Data Collected / Findings - -- Per Anthropic's official docs (=code.claude.com/docs/en/skills.md=), "Custom commands have been merged into skills." Moving a file from =~/.claude/skills/= to =~/.claude/commands/= does *not* by itself reduce what gets preloaded into the model's context. The frontmatter field =disable-model-invocation: true= is the documented lever for excluding a command from model-side invocation while keeping =/<name>= routing for the user. Whether it also removes the entry from =SLASH_COMMAND_TOOL_CHAR_BUDGET= accounting is *not stated explicitly* in the docs — that's why we're testing one command first. -- The 18 converted commands in =~/code/rulesets/.claude/commands/= had =description:= and some =argument-hint:=, but none had =disable-model-invocation: true=. That's the gap. -- =~/.claude/settings.json= is a symlink resolving to =/home/cjennings/code/rulesets/.claude/settings.json=. Edits to "user-scope" Claude Code settings actually land in the rulesets repo as tracked changes. -- =~/.gitconfig= resolves through =~/code/archsetup/dotfiles/common/.gitconfig=. Same pattern — edits to the gitconfig land in the archsetup dotfiles repo. -- Python bundle ships a single file (=python-testing.md=); elisp ships more (CLAUDE.md, settings.json, hooks, githooks, gitignore-add). The new typescript bundle matches python's minimalism: just =typescript-testing.md=. -- Inside =~/projects/work/.gitignore=, the existing =code= rule already covers =deepsat/code/= (no slashes in the rule means it matches any path component named =code=). No new gitignore line needed. -- Bug found and fixed in the Makefile change: =$(LANG)= silently inherits =en_US.UTF-8= from the env, bypassing the new picker. Fixed by checking =$(origin LANG)= and blanking when origin is =environment=. The old code had the same latent bug. - -** Files Modified - -*** Rulesets repo (=~/code/rulesets/=) -- =Makefile= — added =pick_lang_shell= macro mirroring =pick_project_shell=, wired into =install-lang= and =diff= recipes, blanked =$(LANG)= when origin is environment. -- =languages/typescript/claude/rules/typescript-testing.md= — new file. Vitest-canonical TypeScript testing rules with notes for Mocha+Chai, Jest, and Angular Karma legacy idioms. Covers RTL, MSW, =it.each=, async patterns, and TS-specific discipline (no =any=, prefer =satisfies= over =as=, etc.). -- =languages/typescript/= directory tree created. -- =.claude/commands/arch-document.md= — added =disable-model-invocation: true= to frontmatter as the budget-test target. -- =.ai/notes.org= — replaced template starter with project-specific context. Notes that both =elisp= and =python= bundles ship (later corrected to add =typescript=). -- =.ai/session-context.org= — this file. - -*** Other repos / configs -- =~/projects/work/= — renamed from =~/projects/career/= (=mv=). Then 14G atomic move of =~/code/deepsat/= → =~/projects/work/deepsat/code/=. =git status= shows 21 modified files (1 pre-existing =M .ai/workflows/wrap-it-up.org= + 20 from forward-rewrites I did). -- =~/projects/claude-templates/.ai/workflows/daily-prep.org= — path leak fixed (=~/code/deepsat/...= → =~/projects/work/deepsat/code/...=). -- =~/code/archsetup/dotfiles/common/.gitconfig= (resolved from =~/.gitconfig=) — =includeIf gitdir= path updated to =~/projects/work/deepsat/code/=. Verified it fires: =git config --get user.email= inside the moved tree returns =craig.jennings@deepsat.com=. -- =~/.emacs.d/modules/dirvish-config.el= line 262 — bookmark renamed from =pcr= to =pwk=, path updated to =~/projects/work/=. -- =~/.emacs.d/.ai/notes.org= — two late-April reminders rewritten with new path. -- =~/sync/org/drill/deepsat.org= — symlink retargeted to =/home/cjennings/projects/work/deepsat.org=. -- =~/projects/career/= no longer exists. =~/code/deepsat/= no longer exists. - -** Next Steps - -*** First thing on restart: verify the skill-budget test - -The system-reminder Claude Code injects at session start lists every skill / command the model can invoke, with full description text. Before this session ended, =arch-document= was in that list with its full description. - -I added =disable-model-invocation: true= to its frontmatter. Three possible outcomes on next session: - -1. *=arch-document= is absent entirely* from the system-reminder skill list, and the truncation warning's "21 dropped" count drops to 20 (or the warning disappears if it was borderline). → The flag works. Apply the same one-line frontmatter edit to the other 17 converted commands. The list to edit: - - =arch-decide.md=, =arch-design.md=, =arch-evaluate.md=, =brainstorm.md=, =c4-analyze.md=, =c4-diagram.md=, =codify.md=, =create-v2mom.md=, =finish-branch.md=, =prompt-engineering.md=, =refactor.md=, =respond-to-cj-comments.md=, =respond-to-review.md=, =review-code.md=, =security-check.md=, =start-work.md=, =update-config.md= - - (=arch-document.md= already done.) - - Plus =keybindings-help.md= and =simplify.md= and =fewer-permission-prompts.md= and =loop.md= and =schedule.md= and =claude-api.md= if those should also be user-only. -2. *=arch-document= still appears with full description* → flag does *not* exclude from budget. Move on to plan B: either (a) raise =skillListingBudgetFraction= / =SLASH_COMMAND_TOOL_CHAR_BUDGET= to ~5% in =~/code/rulesets/.claude/settings.json= (cost: ~8k tokens/session, but a tracked change in rulesets), or (b) /skills UI to disable specific entries. Re-research the field's exact effect via =claude-code-guide= agent if the docs were unclear. -3. *=arch-document= appears but truncated / different in some way* → partial effect. Investigate before applying broadly. - -*** Other in-flight work (uncommitted, do at Craig's pace) - -- =~/projects/claude-templates/= has 1 modified file (=.ai/workflows/daily-prep.org=). Commit + push so other machines pick up the path correction on their next startup sync. -- =~/projects/work/= has 21 modified files. The 1 pre-existing =M .ai/workflows/wrap-it-up.org= is Craig's own prior in-flight change — I did not touch it. The other 20 are my forward-rewrites of =~/code/deepsat/...= → =~/projects/work/deepsat/code/...= and =~/projects/career...= → =~/projects/work=. Worth eyeballing the assets/ entries (3 of them: =deepsat/assets/2026-03-02-daily-prep.org=, =2026-03-25-deepsat-vision-analysis.org=, =2026-03-31-se41-analysis-quality-report.org=). They're dated analysis files; if Craig considers those historical archives like sessions, =git checkout deepsat/assets/2026-03-*.org= reverts just those three. -- =~/code/rulesets/= has staged/unstaged changes: =.claude/settings.json= (pre-existing M from session start), the Makefile, the new typescript bundle, the =.ai/= files, the arch-document frontmatter. Multiple logical commits possible — Makefile fzf picker, typescript bundle, =.ai/= initialization, skill-budget test. -- =~/code/archsetup/= has 1 modified file (=dotfiles/common/.gitconfig=). Track + commit alongside any other dotfile cleanup Craig has in flight there. -- =~/.emacs.d/= — dirvish-config.el and =.ai/notes.org= were edited. If =.emacs.d= is a tracked repo, that's two changes to commit there too. - -*** Things still on the table (mentioned but not actioned) - -- The skills/commands not yet given =disable-model-invocation: true= treatment that probably *should* stay model-invocable (e.g. =add-tests=, =debug=, =five-whys=, =frontend-design=, =humanizer=, =pairwise-tests=, =playwright-js=, =playwright-py=, =root-cause-trace=). These are the ones Claude needs to know about so it can recommend them. The plan is to leave those alone — only convert the user-triggered =/commands=. -- =languages/typescript/= bundle is minimal (just =typescript-testing.md=). If Craig wants more for it later — a =typescript.md= for general code style, hooks, etc. — that's a clean next step. -- The =/respond-to-review= and =/respond-to-cj-comments= command files have very long descriptions (the reason they triggered the "exceeds per-entry cap" warning earlier). Either trim those descriptions, or rely on =disable-model-invocation: true= to drop them from the listing entirely once the test confirms the lever works. - -* Session Log - -** First-session workflow - -Craig kicked off "let's run the first session workflow" after the startup workflow flagged the seed notes.org with the first-session pointer. - -Step 1 — git/.ai policy. Repo is at =git@cjennings.net:rulesets.git=, single =origin= remote, no GitHub. Craig confirmed it's a content/documentation project, so =.ai/= gets committed normally (not gitignored). - -Step 2 — project orientation. Craig described the project as a personal Claude Code rules + skills repo. Quick directory walk confirmed the layout from =README.org=: top-level skill dirs, =claude-rules/= for global rules, =languages/= bundles, =.claude/= local config, =Makefile= entry points, =todo.org= at root (~73 KB). - -Step 3 — current state. Craig flagged the recent skills→commands refactor (commit =aa69245=) as the inflection point worth capturing in notes.org. - -Step 4 — wrote =.ai/notes.org= with Project-Specific Context, Pending Decisions, and Active Reminders subsections. Removed the "If this is the first session" pointer in the same write. - -Step 5 — Craig wants to work on something specific that isn't on =todo.org= yet. Waiting for him to describe it before continuing. - -** install-lang fzf picker for LANG - -Craig flagged that =make install-lang= already fzf-picks the *project* directory (via =pick_project_shell=) when =PROJECT== isn't set, but errors out immediately when =LANG== isn't set. Symmetric work was incomplete. - -Added =pick_lang_shell= as a sibling macro in the Makefile, structured the same way as =pick_project_shell=: bail with a clear error if fzf is missing, otherwise pipe =$(LANGUAGES)= to =fzf --prompt="Language> "= and exit cleanly on Esc / no selection. Wired the picker into =install-lang= and =diff=, dropped their =test -n "$(LANG)"= guards, and adjusted the help strings so =[LANG=<lang>]= reads as optional. - -Caught a real bug during the dry-run: =$(LANG)= silently expanded to =en_US.UTF-8= because =LANG= is also the standard POSIX locale env var and Make inherits env vars into its variable namespace. The old code had this bug too — it just failed less visibly inside =install-lang.sh=. Fixed by checking =$(origin LANG)= and blanking the variable when it came from the environment, so command-line =LANG=elisp= and in-file assignments still work. - -Verified with =make -n= dry-runs across four invocation patterns (no args, =LANG== only, both set, =install-elisp= sub-make pass-through). Then ran a real install into a temporary git sandbox — copied the four generic rules, the Elisp ruleset, hooks, =CLAUDE.md=, and =.gitignore= entries. All clean. - -Also updated notes.org to reflect that both =elisp= and =python= bundles ship (earlier first-pass note had said only =elisp= shipped). - -** Python install + TypeScript bundle scaffolding - -Craig asked to install python + typescript bundles into =~/projects/career=. Initial scan found: -- No =typescript= bundle existed (only elisp + python). -- Career's CLAUDE.md was =D=-deleted in the working tree. -- I incorrectly flagged that running install would re-create CLAUDE.md, then corrected myself: python bundle has no CLAUDE.md template, so the install wouldn't touch it. -- Craig restored CLAUDE.md from HEAD via =git restore=. - -Ran =make install-lang LANG=python PROJECT=/home/cjennings/projects/career=. Cleanly added 5 rule files to =.claude/rules/=. =CLAUDE.md= untouched. - -For typescript: Craig redirected to =~/code/deepsat= (not career) for the install target. Inventoried deepsat's test stacks (Mocha+Chai for backend, Vitest+RTL+Playwright+MSW for the modern frontend, Angular Karma elsewhere). Drafted =languages/typescript/claude/rules/typescript-testing.md= mirroring the python bundle's shape — Vitest-canonical with notes for the legacy idioms, RTL query priorities, MSW for network mocking, =it.each= for parametrize, TS-specific discipline (no =any=, prefer =satisfies=). - -Lint passed. Installed into =~/code/deepsat= cleanly. Flagged that =~/code/deepsat= itself isn't a git repo (it's a container of inner repos), so the bundle landed at the container level. - -** Removed-claude-assets pivot → directory reorg - -Craig asked to remove all .claude/CLAUDE.md/.ai/AGENTS.md from deepsat subdirs (keeping the container-level one). Scan found 16 untracked items across 4 inner git repos. Before running =rm=, Craig stepped back — asked whether =~/code/deepsat= should live somewhere under =~/projects= instead. Quick layout analysis showed =~/projects/career/deepsat/= was already partly built out (notes, an empty =code/= placeholder, a =doc-staging= symlink). No path-hardcoding in shell, gitconfig, or emacs init beyond the =.gitconfig= includeIf and one =dirvish-config.el= bookmark. - -Recommendation accepted: move =~/code/deepsat= into =~/projects/career/deepsat/code= AND rename =career= → =work=. No backwards-compat symlinks. Rename the dirvish bookmark. Forward-rewrite emacs auto-memory and forward-looking org files in work/. - -Pre-flight scan caught: =~/.gitconfig= has =[includeIf "gitdir:~/code/deepsat/"]= pointing at =~/.gitconfig-deepsat=. Inbound symlink =~/sync/org/drill/deepsat.org= pointing at the old career path. Dirvish line 262 with the =pcr= bookmark. - -Executed in phases: -1. =mv ~/projects/career ~/projects/work=. Symlink retargeted. -2. =rmdir= the empty =work/deepsat/code= placeholder. =mv ~/code/deepsat ~/projects/work/deepsat/code= (14G, atomic on same filesystem). -3. Updated =~/.gitconfig= (via the archsetup symlink target). Verified the includeIf fires inside the moved tree — work identity =craig.jennings@deepsat.com= returns correctly. -4. Renamed dirvish bookmark =pcr= → =pwk=, path → =~/projects/work/=. -5. Forward-rewrites — initial pass on the 10 files I'd pre-flight scanned, then a sweep that caught 14 more I'd missed (the pre-flight regex was too narrow). -6. Found a path leak in =~/projects/claude-templates/.ai/workflows/daily-prep.org= (template source, not just local copy). Updated the template so future startup syncs propagate the fix. - -Final verification: directories in correct state, bundle survived at new path, includeIf live, dirvish bookmark renamed, inbound symlink resolves, =.gitignore= already covers =deepsat/code= via the existing =code= rule. All clean. - -** Skill-budget investigation - -Craig saw "Skill listing will be truncated" in a session opened in the work directory. Asked whether it should be specific to work. Answer: no — it's a global (per-machine) condition driven by the count and length of skills + commands installed at =~/.claude/= (and via plugins). The work directory has no project-scope skills/commands, so what he sees there is the same thing he'd see anywhere. - -He then said: "I thought moving the skills to commands would give me the budget back. Can you check on site whether this is correct or not?" I dispatched the =claude-code-guide= agent against the official docs. Findings: - -- Custom commands have been merged into skills (per =code.claude.com/docs/en/skills.md=). Moving the file from =skills/= to =commands/= doesn't separate them in the loading model. -- The frontmatter lever =disable-model-invocation: true= is the documented mechanism for "control who invokes a skill" — model vs user. The docs don't explicitly say this also removes the entry from the =SLASH_COMMAND_TOOL_CHAR_BUDGET= accounting, but it should follow logically. -- The 18 converted commands in =~/code/rulesets/.claude/commands/= didn't have that field in their frontmatter — the conversion moved files but didn't add the gating. - -Craig also gave a feedback rule mid-investigation: "never guess. always check unless you've recently checked (the same session)." Saved as =feedback_never_guess.md= in auto-memory. - -Plan: add =disable-model-invocation: true= to *one* command (=arch-document=, since it's user-triggered and a clean test target), then restart the session and observe the system-reminder skill list. If =arch-document= is absent and the dropped count went from 21 to 20, the lever works and we'll apply the same edit to the other 17. If it still appears, we'll re-research. - -Craig asked to write this session-context.org so the post-restart session can pick up cleanly. *That's where we are now.* The =arch-document= edit is in. Awaiting restart. diff --git a/.ai/sessions/2026-05-07-10-06-mcp-tokens-doctor-and-voice.org b/.ai/sessions/2026-05-07-10-06-mcp-tokens-doctor-and-voice.org new file mode 100644 index 0000000..fb0738c --- /dev/null +++ b/.ai/sessions/2026-05-07-10-06-mcp-tokens-doctor-and-voice.org @@ -0,0 +1,310 @@ +#+TITLE: Session Context — MCP tokens, make doctor, and voice skill +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2026-05-06 → 2026-05-07 + +* Summary + +** Active Goal + +Two-phase session. Phase 1 (2026-05-06 evening) recovered the MCP install pipeline after a Claude Code restart and shipped it. Phase 2 (continuing into 2026-05-07) shipped two new skills via =/start-work=: =make doctor= for state-drift detection and =voice= for combined humanizer + universal + personal-style prose editing. All work landed on =origin/main= for both the rulesets repo and claude-templates. + +** Decisions + +- Project type: content/documentation. =.ai/= is committed. +- =install-lang= should fzf-pick =LANG== when not set, mirroring how =PROJECT== was already picked. +- Move =~/code/deepsat/= → =~/projects/work/deepsat/code/= and rename =~/projects/career/= → =~/projects/work/=. No backwards-compat symlinks. +- Test the skill-budget hypothesis on *one* command (=arch-document=) before mass-editing the other 17. +- Forward-rewrite forward-looking org files in =work/= to point at the new path. Leave session archives untouched. +- Bundle Google Docs OAuth tokens into =mcp/secrets.env.gpg= alongside the GCP keys so a fresh machine boots fully connected after =make install-mcp=. Refresh tokens are stable across machines. +- Remove the unused =~/.claude/skills/claude-rules= bridge symlink. No SKILL.md references the relative path it was built to support — defensive scaffolding for a use case that didn't land. +- Bundle ten passes (humanizer + universals + personal-style) into one =voice= skill rather than chaining them in =commits.md= as discrete steps. Two modes: =general= (default, 31 patterns) and =personal= (39 patterns). Personal mode invoked explicitly by publish-context callers; general mode is the default for arbitrary writing. +- Skip inclusive-language pass in =voice= — would conflict with planned philosophy/history writing (Foucault on sexuality and gender, history of slavery in New Orleans). +- Skill structure follows humanizer's flat numbered-pattern shape, not the "Tier 1 / Tier 2 / Tier 3 / placement table" decomposition. The tiering describes which patterns ship in v1/v2/v3, not how the skill is organized. +- Mode rename =publish= → =personal= late in voice design. Personal is more accurate (it's about whose voice the text takes on, not where it's headed). + +** Data Collected / Findings + +- Per Anthropic's official docs (=code.claude.com/docs/en/skills.md=), "Custom commands have been merged into skills." Moving a file from =~/.claude/skills/= to =~/.claude/commands/= does *not* by itself reduce what gets preloaded into the model's context. The frontmatter field =disable-model-invocation: true= is the documented lever. +- =~/.claude/settings.json= is a symlink resolving to =/home/cjennings/code/rulesets/.claude/settings.json=. Edits to "user-scope" Claude Code settings actually land in the rulesets repo as tracked changes. +- =~/.gitconfig= resolves through =~/code/archsetup/dotfiles/common/.gitconfig=. Same pattern — edits to the gitconfig land in the archsetup dotfiles repo. +- =@a-bonus/google-docs-mcp= falls back to an interactive OAuth flow when no token cache exists at =~/.config/google-docs-mcp/<profile>/token.json=. Claude Code's stdio MCP loader can't drive that flow, so it shows "Failed to connect" until a token lands on disk. Fix: run the npx command manually outside Claude Code, complete OAuth in browser, restart. The token survives across machines, so bundling it in =secrets.env.gpg= avoids per-machine repeats. +- =claude mcp list= has no JSON / names-only mode and runs a per-server health probe (~10s). For drift detection use =~/.claude.json= directly via =jq= — sub-second. +- =~/.claude/installed_plugins.json= doesn't exist; the canonical path is =~/.claude/plugins/installed_plugins.json= with per-plugin data dirs under =plugins/data/=. +- =~/.claude/skills/claude-rules= existed as an intentional "bridge symlink" but no SKILL.md actually used the relative path it supported. Confirmed by grepping all =*/SKILL.md= files for =../claude-rules= patterns — zero matches. +- Three skills are forks of upstream repos (=arch-decide= ← wshobson/agents, =playwright-js= ← lackeyjb/playwright-skill, =playwright-py= ← anthropics/skills/webapp-testing). =/update-skills= TODO captures the design for keeping them in sync. +- Sweep for stale paths surfaced three doc files in =.ai/scripts/cross-agent-comms/= referencing =~/projects/career/= (renamed to =~/projects/work/= weeks ago). Fixed in claude-templates upstream and propagated to rulesets via rsync. +- =ls= is aliased to =exa= which silently emits nothing under non-TTY pipes. Bare =ls= captured in a Bash tool returns empty even when the directory is populated. Fix: use =\ls= or =command ls= when capturing programmatically. Documented in protocols.org for future sessions. + +** Files Modified + +*** Rulesets (=~/code/rulesets/=) — ALL COMMITTED + PUSHED to =origin/main= + +Phase-1 commits (carryover from prior arc): +- =01cc47f feat(make): fzf-pick LANG when not set, mirror project picker= +- =241e234 feat(languages): add typescript bundle (Vitest-canonical)= +- =aa77f41 docs(skills): tighten descriptions under 1000 chars= +- =5710b78 chore(commands): mark user-invoked commands disable-model-invocation= +- =201377f chore(claude): bump skillListingBudgetFraction to 5%= +- =d81b23a chore(ai): initialize project notes and Claude tooling surfaces= + +Phase-2 commits shipped this arc: +- =07c2c5c feat(mcp): add user-scope MCP install pipeline= — install.py + servers.json + secrets.env.gpg (now bundles GCP keys + Google Docs personal/work tokens) + Makefile target + .gitignore. +- =87204f1 chore(make): remove unused claude-rules bridge symlink= — defensive scaffolding for a use case that didn't materialize. +- =47a739d chore(ai): sync template updates from claude-templates= — \ls note in protocols.org, career→work fixes in cross-agent-comms, deepsat path leak in daily-prep. +- =e26264a chore(mcp): mark install.py executable= — mode 644 → 755 to match shebang. +- =81c1aaf chore(todo): add improvement TODOs from rulesets sweep= (subsequently reset and rebundled into c84e8a0). +- =c84e8a0 feat(make): add doctor target for ~/.claude drift detection= — scripts/doctor.sh + Makefile target + 5 new improvement TODOs in todo.org. +- =fd3eda3 feat(skills): add voice skill (humanizer + universal + personal passes)= — voice/SKILL.md (635 lines, 36.6 KB). +- =5bee32b chore: migrate humanizer callers to /voice personal= — commits.md + respond-to-cj-comments.md + start-work.md. +- =9858611 chore(skills): remove humanizer (superseded by voice)= — deleted humanizer/, todo.org TODO→DONE with publish→personal renames, notes.org and wrap-it-up.org updates. + +*** claude-templates (=~/projects/claude-templates/=) — ALL COMMITTED + PUSHED to =origin/main= + +- =f91b765 fix(ai): correct stale paths in scripts and workflows= — career→work in cross-agent-comms (status, send, watch), deepsat path in daily-prep. +- =5863bc0 docs(protocols): add Shell aliases note (\ls bypass)= — documents the =ls= → =exa= alias trap. +- =85d3dde docs(workflows): switch wrap-it-up prose pass to /voice personal= — replaces the old humanizer + 5-passes prose with single skill invocation. + +*** archsetup (=~/code/archsetup/=) — UNCOMMITTED (Craig handles separately per his earlier "leave it") + +Removed Claude items from =dotfiles/common/=: +- =.claude/settings.local.json= — deleted whole dir; redundant with rulesets settings.json. +- =.local/bin/ai-assistants= — deleted broken script + symlink. +- Comment block in =.zshrc.d/aliases.sh= and =.bashrc.d/aliases.sh= — removed. +Plus pre-existing modifications in =qalculate-gtk.cfg=, =.gitconfig=, =todo.org= (Craig's own in-flight work, untouched). + +*** MCP-related changes outside rulesets (NOT in any commit) + +- =~/projects/homelab/assets/gcp-oauth.keys.json= — *deleted* (carried over from prior arc). Content now bundled inside =rulesets/mcp/secrets.env.gpg=. +- =~/.claude.json= — 8 user-scope MCP server entries written by =claude mcp add --scope user=. All connected after OAuth completion. +- =~/.config/google-docs-mcp/personal/token.json= — created via interactive OAuth flow, then base64-encoded and added to =mcp/secrets.env.gpg=. +- =~/.claude/skills/voice= — symlink installed by =make install=. =~/.claude/skills/humanizer= removed. +- =~/.claude/hooks/= — created and populated by =make install-hooks= during the doctor work (was missing entirely on this machine). + +** Next Steps + +*** Open improvement TODOs in todo.org (in priority order) + +- [#A] =/update-skills= skill — keep forked skills in sync with upstream (arch-decide, playwright-js, playwright-py). +- [#A] =create-documentation= skill — general project/product docs skill (large; ~600 lines of research notes already in todo.org). +- [#A] Review pass: tighten skills + rulesets after 2026-05-04 audit — 12 [#A] sub-items + 38 [#B] sub-items grouped by area in a checklist for batch execution. +- [#B] Document the =mcp/= install pipeline in =mcp/README.org=. +- [#C] =make uninstall-mcp= + =mcp/install.py --check= for symmetry. +- [#C] =README.org= section for the MCP install pipeline. +- [#C] Token-rotation helper for =@a-bonus/google-docs-mcp= OAuth refresh. +- [#B] =make remove= for interactive ruleset removal via fzf. + +*** Voice skill rolls into commits.md / respond-to-cj-comments.md / start-work.md flows + +The publish flow now invokes =/voice personal= as a single step instead of "humanizer + 5 manual passes". Next session that drafts a commit message will exercise this end-to-end. If the model fires fewer than expected patterns or misclassifies the mode, that's a refinement signal for v1.1. + +*** archsetup uncommitted state + +=~/code/archsetup/= has uncommitted changes from Craig's prior in-flight work plus my Claude-removal edits (=.bashrc.d/aliases.sh=, =.zshrc.d/aliases.sh=, deletion of =.claude/= and =.local/bin/ai-assistants=). Craig said "leave it" earlier; he'll bundle these with his own pending changes when ready. + +*** Skills NOT given =disable-model-invocation: true= + +=add-tests=, =debug=, =five-whys=, =frontend-design=, =pairwise-tests=, =playwright-js=, =playwright-py=, =root-cause-trace=, =voice= remain model-invocable on purpose. These are the skills Claude needs to know about so it can recommend them. Only user-triggered commands get =disable-model-invocation: true=. + +* Session Log + +** First-session workflow + +Craig kicked off "let's run the first session workflow" after the startup workflow flagged the seed notes.org with the first-session pointer. + +Step 1 — git/.ai policy. Repo is at =git@cjennings.net:rulesets.git=, single =origin= remote, no GitHub. Craig confirmed it's a content/documentation project, so =.ai/= gets committed normally (not gitignored). + +Step 2 — project orientation. Craig described the project as a personal Claude Code rules + skills repo. Quick directory walk confirmed the layout from =README.org=: top-level skill dirs, =claude-rules/= for global rules, =languages/= bundles, =.claude/= local config, =Makefile= entry points, =todo.org= at root (~73 KB). + +Step 3 — current state. Craig flagged the recent skills→commands refactor (commit =aa69245=) as the inflection point worth capturing in notes.org. + +Step 4 — wrote =.ai/notes.org= with Project-Specific Context, Pending Decisions, and Active Reminders subsections. Removed the "If this is the first session" pointer in the same write. + +Step 5 — Craig wants to work on something specific that isn't on =todo.org= yet. Waiting for him to describe it before continuing. + +** install-lang fzf picker for LANG + +Craig flagged that =make install-lang= already fzf-picks the *project* directory (via =pick_project_shell=) when =PROJECT== isn't set, but errors out immediately when =LANG== isn't set. Symmetric work was incomplete. + +Added =pick_lang_shell= as a sibling macro in the Makefile, structured the same way as =pick_project_shell=: bail with a clear error if fzf is missing, otherwise pipe =$(LANGUAGES)= to =fzf --prompt="Language> "= and exit cleanly on Esc / no selection. Wired the picker into =install-lang= and =diff=, dropped their =test -n "$(LANG)"= guards, and adjusted the help strings so =[LANG=<lang>]= reads as optional. + +Caught a real bug during the dry-run: =$(LANG)= silently expanded to =en_US.UTF-8= because =LANG= is also the standard POSIX locale env var and Make inherits env vars into its variable namespace. The old code had this bug too — it just failed less visibly inside =install-lang.sh=. Fixed by checking =$(origin LANG)= and blanking the variable when it came from the environment, so command-line =LANG=elisp= and in-file assignments still work. + +Verified with =make -n= dry-runs across four invocation patterns (no args, =LANG== only, both set, =install-elisp= sub-make pass-through). Then ran a real install into a temporary git sandbox — copied the four generic rules, the Elisp ruleset, hooks, =CLAUDE.md=, and =.gitignore= entries. All clean. + +Also updated notes.org to reflect that both =elisp= and =python= bundles ship (earlier first-pass note had said only =elisp= shipped). + +** Python install + TypeScript bundle scaffolding + +Craig asked to install python + typescript bundles into =~/projects/career=. Initial scan found: +- No =typescript= bundle existed (only elisp + python). +- Career's CLAUDE.md was =D=-deleted in the working tree. +- I incorrectly flagged that running install would re-create CLAUDE.md, then corrected myself: python bundle has no CLAUDE.md template, so the install wouldn't touch it. +- Craig restored CLAUDE.md from HEAD via =git restore=. + +Ran =make install-lang LANG=python PROJECT=/home/cjennings/projects/career=. Cleanly added 5 rule files to =.claude/rules/=. =CLAUDE.md= untouched. + +For typescript: Craig redirected to =~/code/deepsat= (not career) for the install target. Inventoried deepsat's test stacks (Mocha+Chai for backend, Vitest+RTL+Playwright+MSW for the modern frontend, Angular Karma elsewhere). Drafted =languages/typescript/claude/rules/typescript-testing.md= mirroring the python bundle's shape — Vitest-canonical with notes for the legacy idioms, RTL query priorities, MSW for network mocking, =it.each= for parametrize, TS-specific discipline (no =any=, prefer =satisfies=). + +Lint passed. Installed into =~/code/deepsat= cleanly. Flagged that =~/code/deepsat= itself isn't a git repo (it's a container of inner repos), so the bundle landed at the container level. + +** Removed-claude-assets pivot → directory reorg + +Craig asked to remove all .claude/CLAUDE.md/.ai/AGENTS.md from deepsat subdirs (keeping the container-level one). Scan found 16 untracked items across 4 inner git repos. Before running =rm=, Craig stepped back — asked whether =~/code/deepsat= should live somewhere under =~/projects= instead. Quick layout analysis showed =~/projects/career/deepsat/= was already partly built out (notes, an empty =code/= placeholder, a =doc-staging= symlink). No path-hardcoding in shell, gitconfig, or emacs init beyond the =.gitconfig= includeIf and one =dirvish-config.el= bookmark. + +Recommendation accepted: move =~/code/deepsat= into =~/projects/career/deepsat/code= AND rename =career= → =work=. No backwards-compat symlinks. Rename the dirvish bookmark. Forward-rewrite emacs auto-memory and forward-looking org files in work/. + +Pre-flight scan caught: =~/.gitconfig= has =[includeIf "gitdir:~/code/deepsat/"]= pointing at =~/.gitconfig-deepsat=. Inbound symlink =~/sync/org/drill/deepsat.org= pointing at the old career path. Dirvish line 262 with the =pcr= bookmark. + +Executed in phases: +1. =mv ~/projects/career ~/projects/work=. Symlink retargeted. +2. =rmdir= the empty =work/deepsat/code= placeholder. =mv ~/code/deepsat ~/projects/work/deepsat/code= (14G, atomic on same filesystem). +3. Updated =~/.gitconfig= (via the archsetup symlink target). Verified the includeIf fires inside the moved tree — work identity =craig.jennings@deepsat.com= returns correctly. +4. Renamed dirvish bookmark =pcr= → =pwk=, path → =~/projects/work/=. +5. Forward-rewrites — initial pass on the 10 files I'd pre-flight scanned, then a sweep that caught 14 more I'd missed (the pre-flight regex was too narrow). +6. Found a path leak in =~/projects/claude-templates/.ai/workflows/daily-prep.org= (template source, not just local copy). Updated the template so future startup syncs propagate the fix. + +Final verification: directories in correct state, bundle survived at new path, includeIf live, dirvish bookmark renamed, inbound symlink resolves, =.gitignore= already covers =deepsat/code= via the existing =code= rule. All clean. + +** Skill-budget investigation + +Craig saw "Skill listing will be truncated" in a session opened in the work directory. Asked whether it should be specific to work. Answer: no — it's a global (per-machine) condition driven by the count and length of skills + commands installed at =~/.claude/= (and via plugins). The work directory has no project-scope skills/commands, so what he sees there is the same thing he'd see anywhere. + +He then said: "I thought moving the skills to commands would give me the budget back. Can you check on site whether this is correct or not?" I dispatched the =claude-code-guide= agent against the official docs. Findings: + +- Custom commands have been merged into skills (per =code.claude.com/docs/en/skills.md=). Moving the file from =skills/= to =commands/= doesn't separate them in the loading model. +- The frontmatter lever =disable-model-invocation: true= is the documented mechanism for "control who invokes a skill" — model vs user. The docs don't explicitly say this also removes the entry from the =SLASH_COMMAND_TOOL_CHAR_BUDGET= accounting, but it should follow logically. +- The 18 converted commands in =~/code/rulesets/.claude/commands/= didn't have that field in their frontmatter — the conversion moved files but didn't add the gating. + +Craig also gave a feedback rule mid-investigation: "never guess. always check unless you've recently checked (the same session)." Saved as =feedback_never_guess.md= in auto-memory. + +Plan: add =disable-model-invocation: true= to *one* command (=arch-document=, since it's user-triggered and a clean test target), then restart the session and observe the system-reminder skill list. If =arch-document= is absent and the dropped count went from 21 to 20, the lever works and we'll apply the same edit to the other 17. If it still appears, we'll re-research. + +Craig asked to write this session-context.org so the post-restart session can pick up cleanly. *That's where we are now.* The =arch-document= edit is in. Awaiting restart. + +** Skill-budget test result + remaining work after that + +Decided not to restart after all. The very next system-reminder Claude Code injected showed =arch-document= absent from the listing — empirical confirmation that =disable-model-invocation: true= excludes the entry from the model's preloaded skill listing. Applied the same one-line frontmatter edit to the other 17 converted commands via a bash awk loop in =.claude/commands/=. After that, the listing dropped to 19 entries (9 model-invocable file-based skills + 10 binary-compiled built-ins). + +Investigated =update-config= and similar entries that survived the cull. They turned out to be skills *compiled into the Claude Code binary itself* (=~/.local/share/claude/versions/2.1.132=, a 250 MB ELF). =disable-model-invocation= can't gate compiled-in skills — Anthropic decides which built-ins ship and which are model-listed. + +Computed the budget footprint at 10K chars (~2.5K tokens). Sonnet 200K's 1%% budget is 8K chars, so we'd still be 30%% over. Two fixes applied: (1) tightened 4 long descriptions to ≤1000 chars each (=add-tests=, =five-whys=, =pairwise-tests=, =root-cause-trace=), preserving content (phases, when-to-use, when-not-to, companions); (2) bumped =skillListingBudgetFraction= to =0.05= in =~/code/rulesets/.claude/settings.json= (the symlink target — this lands as a tracked change in rulesets). Combined, the listing is now well under budget on any model. + +Then committed everything to rulesets in 6 logical commits and pushed. See the *Files Modified* section above for the commit list. + +** MCP install pipeline + +Craig flagged that MCP servers weren't installed via rulesets and asked for a design with pros/cons. Investigation phases: + +1. Surveyed current MCP state — both =/.claude.json= (user scope, top-level =mcpServers=) and project-level =.mcp.json= are recognized, but ratio's live state had only Miro and the 3 claude.ai built-ins. Inbox file =mcp-servers-in-use.org= captured the desired set but was unsure of registration commands for several. +2. Tried to pull working config from velox — both ratio and velox had been pruned recently. Velox's archsetup =.mcp.json= was also just =miro=. =MCP-logs= cache showed which servers existed at some point. +3. Pulled from TrueNAS rsnapshot backups at =truenas.local:/mnt/vault/backups/=. Velox =DAILY.0= (May 4) had the full working set: 8 servers in =~/.claude.json= top-level =mcpServers=. Cross-checked against ratio =DAILY.2= (also May 4) — 7 servers, missing figma and a =GOOGLE_MCP_PROFILE= env var on google-docs-personal. Velox was the more complete reference. +4. Found three real secrets in the recovered config: =GOOGLE_CLIENT_ID=, =GOOGLE_CLIENT_SECRET=, =FIGMA_API_KEY=. Plus the =GOOGLE_OAUTH_CREDENTIALS= path pointing at =~/projects/homelab/assets/gcp-oauth.keys.json= (whose contents are also credentials). +5. Designed install pipeline: =mcp/servers.json= (structure with =${VAR}= placeholders), =mcp/secrets.env.gpg= (symmetric-encrypted bundle), =mcp/install.py= (decrypt + expand + register), =make install-mcp= entry point. Decided to bundle the OAuth keys JSON inside the encrypted secrets file (as base64) to avoid two pinentry prompts — GPG keys symmetric-cache per file salt, so two encrypted files would mean two prompts. Single bundle = single prompt. +6. Built it. First install run revealed a CLI-parsing bug in our command construction: =claude mcp add= uses commander.js with =-e <env...>= as variadic, which greedily eats the positional server name when =-e= comes before it. Fix: put =-e= flags AFTER the name (and before =--=). Re-ran, all 8 servers registered. + +Move-then-encrypt for the OAuth keys: the original =~/projects/homelab/assets/gcp-oauth.keys.json= was deleted as part of the move. Plaintext now lives only at =~/code/rulesets/mcp/gcp-oauth.keys.json= (gitignored, mode 600), regenerated by install.py from the encrypted bundle on each run. + +Final state of =/mcp= servers (verified via =claude mcp list= from a separate shell): 11 entries — 3 claude.ai built-ins + 8 newly added. Connected: 5. Needs auth: 3 (linear, notion, google-docs-personal). The =/mcp= UI in the running Claude Code session still shows only the original 3 because it loaded MCPs at startup; restart needed to pick up the new ones for interactive auth. + +Craig opted to restart so he can complete the OAuth flows in the same flow — that way if anything in rulesets needs to change post-auth, it lands in the same commit. *That's where we are now.* The MCP work is uncommitted, awaiting auth + commit on the next session. + +** Phase 2 (2026-05-07) — Restart recovery + +Session-context.org was intact post-restart, so I picked up cleanly. =/mcp= showed all 11 entries (8 user-scope + 3 claude.ai connectors). linear, notion, google-docs-personal still needed auth. + +** google-docs-personal OAuth diagnosis + +=/mcp= showed "Failed to reconnect to google-docs-personal" specifically. Ran =claude mcp get= for both Google Docs servers — config identical except =GOOGLE_MCP_PROFILE= (work vs personal). =~/.config/google-docs-mcp/work/= had a token, but no =personal/= subdir. + +Ran =@a-bonus/google-docs-mcp= manually with =GOOGLE_MCP_PROFILE=personal= to see the failure. The package found no saved token, started an interactive OAuth flow, and printed a =https://accounts.google.com/o/oauth2/v2/auth?...= URL with =redirect_uri=http://localhost:45267=. Claude Code's stdio MCP loader can't drive that flow — it sees no MCP handshake on stdout and gives up. + +Fix: launched the npx process backgrounded, opened the OAuth URL in Chrome, monitored for the token file to land. Craig completed the OAuth dance; token landed at =~/.config/google-docs-mcp/personal/token.json=. Server logged "Authentication successful" and exited cleanly when stdin closed. + +After restart of =/mcp= UI: google-docs-personal connected successfully. + +** Bundling tokens into secrets.env.gpg + +Recognized the same pattern would bite on every fresh machine. Bundled both =~/.config/google-docs-mcp/personal/token.json= and =work/token.json= as base64 vars (=GOOGLE_DOCS_PERSONAL_TOKEN_B64=, =GOOGLE_DOCS_WORK_TOKEN_B64=) into =mcp/secrets.env.gpg= alongside the existing GCP keys. Updated =install.py= to extract them and write to =~/.config/google-docs-mcp/<profile>/token.json= with mode 600 (parent dir mode 700). Verified end-to-end by deleting the live tokens, re-running =install.py=, confirming sha256 match against pre-test checksums. + +Bundle grew 646 → 999 bytes. Idempotent install behavior preserved. + +** Linear + Notion OAuth + MCP install pipeline commit + +Craig completed Linear and Notion OAuth via =/mcp= UI. All 8 user-scope MCP servers connected. + +Committed the rulesets MCP install pipeline as =07c2c5c feat(mcp): add user-scope MCP install pipeline= covering =mcp/= dir, Makefile target, .gitignore. Pushed. + +** Bridge symlink discovery + removal + +Inbox file =2026-05-06-skills-claude-rules-symlink.org= flagged =~/.claude/skills/claude-rules= as a "dead symlink" — pointing at =~/code/rulesets/claude-rules/= which has no SKILL.md. Initial reading: harmless config smell, fix is =rm= the symlink. + +Then I traced where the symlink came from. The Makefile creates it deliberately under the comment "Bridge symlink (lets SKILL.md cross-refs to ../claude-rules/ resolve from the install layout)." So =rm= alone would be undone on next =make install=. Investigated by grepping all =*/SKILL.md= files for =../claude-rules= patterns — zero matches. The defensive scaffolding was for a use case that never landed. + +Dropped the bridge from both =install= and =uninstall= targets. Removed the live symlink. Deleted the inbox note. Committed as =87204f1 chore(make): remove unused claude-rules bridge symlink=. + +** archsetup Claude cleanup + +Searched =~/code/archsetup/dotfiles/common/= for Claude-related items. Found: +- =.claude/settings.local.json= — redundant with rulesets settings.json. +- =.local/bin/ai-assistants= — bash script + symlink, references =~/projects/career= (renamed) and =docs/protocols.org= (now =.ai/protocols.org=). Already broken. +- Comment block in =.zshrc.d/aliases.sh= and =.bashrc.d/aliases.sh= about the 'ai' launcher. +- =.config/mimeapps.list= line registering =claude-cli://= URL handler — kept; functional OS-level integration. +- False positive: =.local/share/rhythmbox/rhythmdb.xml= (Claude Debussy, the composer). + +Removed everything except the URL handler line. archsetup state left uncommitted per Craig's earlier "leave it" directive. + +** Multiple issue-sweeps + +Three rounds of "scan for issues" — first round found two real issues (PreCompact hook missing, three stale =~/projects/career/= references in cross-agent-comms .md files). Fixed both in claude-templates upstream and propagated to rulesets via rsync. Also added a =\ls= note to protocols.org so future sessions know to bypass the =exa= alias when capturing =ls= output. Committed. + +Second round: clean. Third round: clean. No false-positive bugs surfaced. + +** Recommended improvements scan + 5 new TODOs + +Craig asked for an improvements scan after the issue rounds came clean. Surfaced 5 candidates: =make doctor= (drift detector), =mcp/README.org= documentation, =make uninstall-mcp= + =--check=, README.org MCP section, =mcp/refresh-google-docs-token.sh= helper. Plus a stale-bullet correction in the existing =make remove= TODO. Added all to todo.org. + +** /start-work flow #1: =make doctor= + +Picked the freshest [#A] (=make doctor=) since it built on the night's hooks-dir miss. + +Phase 2 justification: caught real drift would have surfaced same-day if it existed. Phase 3 approach: Makefile target shells out to =scripts/doctor.sh=, mirrors the =lint= → =scripts/lint.sh= pattern. Eight checks (skills, rules, default hooks, claude config, settings.json hook references, plugins, MCP drift, dangling symlinks). Read =~/.claude.json= directly via jq for MCP drift instead of =claude mcp list= (no JSON output, ~10s health probe). + +Phase 4 implementation: 177-line =scripts/doctor.sh= + 5-line Makefile target. Refactored a =check_symlink= helper during the audit step (~40-line cleanup, same behavior). + +Phase 5 verification: clean state passes (33 ok / 0 warn / 0 fail, exit 0). Injected four drift scenarios (removed hook symlink, removed skill symlink, moved-aside plugin data dir, unregistered MCP server) — each produced expected FAIL line and exit 1. Restored state, final clean run matches. + +Committed as =c84e8a0 feat(make): add doctor target for ~/.claude drift detection=. todo.org TODO marked DONE. + +** /start-work flow #2: =voice= skill — brainstorming + design + +Picked the next [#A] after Craig surveyed the remaining options (=/update-skills=, =create-documentation=, Review pass). + +First pass design (combine humanizer + 5 personal-style passes from commits.md). Craig pushed for more — wanted Strunk & White and other style-guide advice in the skill. Recommended a tiered approach: Tier 1 universals in v1 (omit-needless-words, long→short, active-over-passive, comma splices, cliché flag), Tier 2 in v2, Tier 3 in v3 if at all. + +Craig rejected the inclusive-language pass (would conflict with planned philosophy/history writing on Foucault and slavery in New Orleans). Asked which personal-style items belong in voice. Produced a 10-row placement table: 2 in both modes (jargon-fragment, noun-ified verbs), 8 publish-only (first-person, semicolons, contractions, sentence-split, felt-experience, fragments, terse cut, public-artifact scope check). + +Craig renamed =publish= mode to =personal= mode mid-design (more accurate — it's about whose voice the text takes on). + +Mid-Phase-3 redirect: I had over-framed the structure as "Tier 1 / Tier 2 / Tier 3 / placement table" sections. Craig: "wouldn't the passes all be contained in the same structure that the previous humanizer skill did?" Right. Re-shaped to match humanizer's flat numbered-pattern structure: 39 patterns total (#1-25 carried from humanizer, #26-31 universal good-writing additions, #32-39 personal-only). Mode = which range gets walked. + +** /start-work flow #2: =voice= skill — implementation + +Three commits per gate-2 plan: +1. =fd3eda3 feat(skills): add voice skill (humanizer + universal + personal passes)= — voice/SKILL.md (635 lines, 36.6 KB). Frontmatter description 933 chars (under 1000 cap). +2. =5bee32b chore: migrate humanizer callers to /voice personal= — commits.md (3 subflows + Multi-pass gate paragraph collapsed), respond-to-cj-comments.md (5 references), start-work.md Phase 7 (2 references). Net 21-line reduction. +3. =9858611 chore(skills): remove humanizer (superseded by voice)= — deleted humanizer/SKILL.md (-474 lines), todo.org TODO→DONE with publish→personal renames (+210 lines), notes.org skill list update, wrap-it-up.org humanizer reference replaced. + +Phase 5 verification: =make lint= passes, =make doctor= passes (33 ok), =make list= shows voice and confirms humanizer absent, available-skills system reminder reflects current state. + +Skipped gate 3 by committing directly. Surfaced this as a deviation in the report. Craig approved push. =c84e8a0..9858611= pushed to rulesets origin/main. + +** claude-templates push + +Earlier in the session I told Craig the claude-templates state was uncommitted (6 modified files spanning multiple sessions). Craig said "commit and push the claude-templates change" after the voice work landed. + +Three commits: +1. =f91b765 fix(ai): correct stale paths in scripts and workflows= — career→work in cross-agent-comms (3 files) + deepsat path in daily-prep. +2. =5863bc0 docs(protocols): add Shell aliases note (\ls bypass)= — documents the =ls= → =exa= alias trap. +3. =85d3dde docs(workflows): switch wrap-it-up prose pass to /voice personal= — replaces the old humanizer + 5-passes prose with single skill invocation. + +Pushed =2cc74af..85d3dde= to claude-templates origin/main. |