docs+feat: the line between a hook and the CLI, and the last plugin script crossing it

[blafourcade]

Why

The telemetry pivot moved 4,355 lines of skill-owned scripts into the CLI. What is left outside is one skill script and the bundled hooks — and the argument that decides which is which was never written down. Nothing stops the next change from moving a hook into the CLI because "everything is in the CLI now".

The measurement that decides it

One machine, 12 runs each, median:

	Start
plugins/aidd-telemetry/hooks/journal.cjs	27 ms
cli/dist/cli.js --version	180 ms

6.7×, on an event (PostToolUse) that fires on every tool call a session makes. A thousand tool calls is 153 seconds a person waits through. The hooks are not a leftover; they are where they are for a reason with a number attached.

The line

Not "plugin or CLI" — what the code answers to:

	Triggered by	Latency	Runs as
Observing	a tool event, thousands of times a session	must not be felt	plain Node in hooks/, no install, no dependency
Answering	a person or a skill, once	irrelevant	the aidd CLI

Two consequences, both already paid for, both stated in the new section: a capability that answers belongs in the CLI even when a plugin is what asks for it; and a skill that needs an absent CLI must say so out loud, which scripts/__tests__/telemetry-cli-required.test.js already pins word for word across every such skill.

The cost is stated rather than argued away: a plugin that promised "no npm install, no CLI, no account" now needs node to measure and aidd to answer.

The bug the guard could not see

docs/ARCHITECTURE.md named hooks/update_memory.cjs. That file has always been .js — in the tree and in the plugin's own hooks.json — so a reader following the architecture doc to the context plugin's session hook found nothing.

comments-name-files-that-exist.test.js exists to catch exactly this. It scanned cli/src, cli/tests, plugins and scripts for .ts, .cjs and .js, and no markdown at all. It now scans docs/ markdown too — the existing guard extended, not a second test beside it, because a durable doc naming a file makes the same promise a comment does.

Markdown anywhere else stays out, and that is measured rather than assumed:

Scope scanned	Findings	Real faults
every .md in the tree	17	0
docs/**/*.md	3	1

The 17 are a skill's own assets and cli/tests/fixtures templates naming illustrative paths on purpose. Of the 3, one is this bug; the other two name INSTALL.md, a seam artefact one plugin writes into a reader's own project for another to read back, now listed in NOT_A_REPOSITORY_FILE for what it is.

Verification

Red before the fix, on the one line it names:

docs/ARCHITECTURE.md names `hooks/update_memory.cjs`, which no tracked file matches

Green after. 371 repository script tests pass — the same count as before, because the guard was extended rather than duplicated. check-markdown-links.js: 0 broken in 798 files.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp

---

Second commit: aidd ai rules, and the drift it uncovered

plugins/aidd-context/skills/11-explore/scripts/list-rules.mjs was the only script left inside a skill — 198 lines — and its own header read:

// NOTE: synced from plugins/aidd-dev/scripts/list-rules.mjs. Keep in sync when the source changes.

plugins/aidd-dev/scripts/ no longer exists. A hand-maintained copy whose source is gone, and whose header is false.

It had drifted where it mattered

The script carried its own table of four tool directories and stated "Codex CLI: rules not supported, skipped". plugin-content-translator.ts:237 routes a plugin's rules/ into every tool whose capability accepts them, and all five accept them. A Codex project asking what rules it had was answered none — silently, and wrongly.

plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md said the same of Codex and OpenCode, and told a generator to put the convention in AGENTS.md instead. Both rows are corrected here.

What removes the table instead of moving it

RulesCapability.installedLocation() asks buildInstallPath with a sentinel name and reads the answer back, so the directory and extension come from the installer:

Tool	Directory	Extension
claude	.claude/rules/	.md
codex	.codex/rules/	.md
copilot	.github/instructions/	.instructions.md
cursor	.cursor/rules/	.mdc
opencode	.opencode/rules/	.md

Three of those are a path template, Cursor's goes through toMdc, Copilot's is a delegated handler — so a caller parsing a path string back apart would have been a second copy, free to disagree the day a tool moves. registry-conformance pins all five, so a sixth tool or a moved directory is read by whoever changes it.

The hand-rolled frontmatter parser goes too: domain/formats/markdown.ts already exported parseFrontmatter. hasRules was private to plugin-content-translator.ts and is now exported from contracts.ts beside the type it guards, generic so that translator keeps the narrowing it had.

Contract kept

--json prints the array the script printed, field for field, so the skill reading it did not change what it reads. The default output is for a person, and a project with no rule says so rather than printing nothing — an empty answer and a command that never ran look identical on a terminal, and only one of them is a fact about the project.

The skill runs aidd ai rules --json and, finding no command, stops and says the CLI is required. Never an empty inventory — which is the rule the first commit writes down.

Tests

Fourteen new cases, each written before the code. Mutations run, three killed:

Mutation	Red
installedLocation answers the source path, not the installed one	4
the scan drops its extension filter	1
a name trimmed at the last dot, not by the whole extension	1

An e2e case runs the built binary against a temp project holding a Claude rule, a Codex rule and a README.md sitting beside a Cursor rule — because the skill invokes the binary, and a use case passing in isolation says nothing about whether the subcommand is reachable.

vitest 3,488 passed / 312 files. 371 repository script tests. Typecheck, biome ci (2 pre-existing warnings), knip, jscpd, layering clean, 0 broken links in 798 files. Bundle 596.6 → 599.0 KB, budget 598 → 601, measured and recorded beside the three raises before it.