feat(telemetry): deterministic claude code token measurement, release 1

.claude-plugin/marketplace.json

@@ -73,7 +73,7 @@
     {
       "name": "aidd-telemetry",
       "source": "./plugins/aidd-telemetry",
-      "description": "Measurement: journals every session so a unit of work can be tied to what it cost. The hooks record on plain node; its three skills reach the `aidd` CLI to turn it on, answer and check.",
+      "description": "Measurement: counts the tokens of Claude Code sessions per task, ticket, model and day, locally. The hooks ask for a task on plain node; its two skills reach the `aidd` CLI to turn it on and answer.",
       "strict": true,
       "metadata": {
         "recommended": false

.github/workflows/cli-ci.yml

@@ -46,8 +46,7 @@ jobs:
         id: filter
         run: |
           set -euo pipefail
-          # The scope the jobs below actually exercise. The telemetry plugin's own prose is
-          # excluded because validate.yml already asserts it on every push and pull request.
+          # The scope the jobs below actually exercise.
           if [[ "${{ github.event_name }}" == "pull_request" ]]; then
             BASE="${{ github.event.pull_request.base.sha }}"
             HEAD="${{ github.event.pull_request.head.sha }}"
@@ -71,17 +70,15 @@ jobs:
               cli/*|kanban/*|scripts/__tests__/*|README.md)
                 relevant=true
                 ;;
+              # The identifier-join probe, and the hook predicates it judges the real tool by.
+              scripts/probe-identifier-join.cjs|plugins/aidd-telemetry/hooks/*)
+                relevant=true
+                ;;
               # This file: a change to how the suite runs matches nothing else here, so the
               # workflow deciding whether the suite passes would land unverified.
               .github/workflows/cli-ci.yml)
                 relevant=true
                 ;;
-              plugins/aidd-telemetry/*)
-                case "$f" in
-                  *.md) ;; # prose only, covered by validate.yml instead
-                  *) relevant=true ;;
-                esac
-                ;;
             esac
             [[ "$relevant" == "true" ]] && break
           done < <(git diff --name-only "$BASE" "$HEAD")
@@ -412,19 +409,17 @@ jobs:
           restore-keys: pnpm-${{ runner.os }}-
       - run: cd cli && pnpm install --frozen-lockfile
       - run: cd cli && pnpm build
-      # The probe drives the real tool, so the real tool has to be here. No credentials are
-      # needed: it points Claude Code at a dead address, and the session id is minted first.
+      # The check drives the real tool, so the real tool has to be here. No credentials are needed.
       - name: Install Claude Code
         run: npm install -g @anthropic-ai/claude-code # floats on purpose, declared in scripts/__tests__/workflows-pin-global-installs.test.js
-      # Everything in this layer joins on the identifier a hook receives being the one the
-      # export carries, and a tool update can break it with nothing else turning red. Exit 2
-      # means the probe could not form an opinion, rather than blaming the tool.
-      - name: Probe the identifier join
-        run: node scripts/probe-identifier-join.cjs
       # The golden snapshots pin what a claude build contains; only the host can say it loads.
       # Its `plugin validate` exits 0 either way, so the script reads the verdict from its text.
       - name: Claude Code accepts the translated marketplace
         run: node scripts/check-claude-accepts-build.cjs
+      # One session id in the hook's payload, its environment and the transcript: what the
+      # telemetry joins on. Against a dead API, so it spends nothing.
+      - name: Claude Code keeps the session id join
+        run: node scripts/probe-identifier-join.cjs
 
   cli-jscpd:
     name: cli / JSCPD (duplication)
@@ -489,38 +484,9 @@ jobs:
         with:
           node-version: "22"
 
-      # The WRITE path, on the platform where a home directory, a line ending and an absolute
-      # path all resolve differently. It runs before the CLI is built on purpose: recording is
-      # supposed to need nothing installed, and this is where that claim is exercised.
-      - name: Chain - allow measurement, with nothing installed
-        run: |
-          # Written directly rather than through a command: the switch is a file the hooks
-          # read fresh at every write, so no binary has to exist for it to work.
-          mkdir -p .aidd
-          node -e "require('fs').writeFileSync('.aidd/config.json', JSON.stringify({ telemetry: { enabled: true } }, null, 2) + '\n');"
-      - name: Chain - journal a captured payload
-        run: |
-          # The fixture's cwd came off whatever machine captured it: rewritten so getRepoRoot
-          # resolves a repository that exists here.
-          node -e "const p=require('./scripts/__tests__/fixtures/claude-code-session-start.json'); p.cwd=process.cwd(); require('fs').writeFileSync('payload.json', JSON.stringify(p));"
-          node plugins/aidd-telemetry/hooks/journal.cjs session-start < payload.json
-          node plugins/aidd-telemetry/hooks/journal.cjs turn-end < payload.json
-      # `telemetry check` fails on `sessionFound: false`, and nothing in this chain places a
-      # transcript for the session just journalled. Copied from a local-cost fixture with its
-      # session id rewritten, under `$HOME` — which is what the read path itself resolves
-      # first, and which Git Bash sets on this runner.
-      - name: Chain - place the transcript where claude keeps it
-        run: |
-          node -e "const fs=require('fs'),os=require('os'),path=require('path');const homeDir=process.env.HOME||os.homedir();const sessionId='ffde6fda-14a8-4b32-8110-be1f1d13eebf';const src='cli/tests/fixtures/local-cost/.claude/projects/fake-project/22222222-2222-4222-8222-222222222222.jsonl';const dir=path.join(homeDir,'.claude','projects','fake-project');fs.mkdirSync(dir,{recursive:true});const content=fs.readFileSync(src,'utf8').split('22222222-2222-4222-8222-222222222222').join(sessionId);fs.writeFileSync(path.join(dir,sessionId+'.jsonl'),content);"
-      - name: Chain - the journal stays private and git add -A still works
-        run: |
-          git add -A
-          git status --porcelain >/dev/null
-
       # Wrapped: a suite writing into this repository's own .git/hooks passes every assertion
       # and destroys an install nothing can restore. The suite reads YAML through the root
-      # devDependencies, so the install has to precede it — and the chain steps above stay
-      # ahead of any install on purpose.
+      # devDependencies, so the install has to precede it.
       - run: pnpm install --frozen-lockfile
       - run: cd cli && pnpm install --frozen-lockfile
       - name: Plugin suite
@@ -554,21 +520,13 @@ jobs:
           pnpm build
           pnpm pack --pack-destination ./dist
           npm install -g ./dist/ai-driven-dev-cli-*.tgz --force
-      # The exact command `02-check`'s own markdown names, not a script beside it. Failing
-      # `aidd --version` means the CLI could not be resolved on the PATH.
-      - name: Chain - diagnose, through the command every skill's own markdown names
-        run: |
-          aidd --version
-          # A gated run judges nothing and exits 0, so the one row the chain exists to make
-          # true is asserted separately: the transcript placed for the session was read.
-          aidd telemetry check | tee telemetry-check.out
-          grep -E "tool files readable +ok" telemetry-check.out
+      # Failing `aidd --version` means the CLI could not be resolved on the PATH.
+      - name: Chain - the installed CLI resolves
+        run: aidd --version
       - run: cd cli && pnpm test:unit
       - run: cd cli && pnpm test:integration
       - run: cd cli && pnpm test:arch
-      # Every e2e but the two named below. `telemetry-commit-trailer.e2e.test.ts` is why the
-      # step matters most: it is the only thing proving the `prepare-commit-msg` hook is
-      # reachable by the shell Git for Windows ships, which a backslash path is not.
+      # Every e2e but the one named below.
       - name: cli e2e
         # `--max-workers=2`, and only here. Vitest transforms modules on its own main thread
         # while every worker calls back into it, and that call has a fixed 60 s timeout no
@@ -578,11 +536,8 @@ jobs:
         run: |
           cd cli
           pnpm exec vitest run --project=e2e --max-workers=2 \
-            --exclude "tests/e2e/persona.e2e.test.ts" \
-            --exclude "tests/e2e/telemetry-multi-tool.e2e.test.ts"
-        # persona.e2e.test.ts needs /usr/bin/expect, which windows-latest does not carry;
-        # telemetry-multi-tool.e2e.test.ts relies on a shebang, and Windows resolves an
-        # executable by PATHEXT.
+            --exclude "tests/e2e/persona.e2e.test.ts"
+        # persona.e2e.test.ts needs /usr/bin/expect, which windows-latest does not carry.
 
   # Fan-in: every job above either ran and passed, or was skipped because `changes` found
   # nothing relevant. The one check the branch rulesets require — without it a pull request

.github/workflows/validate.yml

@@ -52,11 +52,11 @@ jobs:
         run: pnpm exec lefthook run pre-commit --all-files --force
 
       # The generator hooks `git add` their output and never fail on drift, so a stale
-      # CATALOG.md, prompts doc or README count passes the step above in silence. Against
+      # CATALOG.md or README count passes the step above in silence. Against
       # HEAD, not the index: the generators already staged, so a plain `git diff` is empty.
       - name: Fail if a generated file drifted from what pre-commit regenerated
         run: |
-          if ! git diff --exit-code HEAD -- 'plugins/*/CATALOG.md' docs/prompts-documentation.md README.md; then
+          if ! git diff --exit-code HEAD -- 'plugins/*/CATALOG.md' README.md; then
             echo "::error::A generated file is stale. Run 'pnpm exec lefthook run pre-commit --all-files --force' locally and commit the result."
             exit 1
           fi

.gitignore

@@ -34,20 +34,11 @@ coverage/
 
 # AIDD CLI's own local state (install manifest, auth): machine-local, never
 # part of the project's own tracked content. config.json is the exception:
-# it is the committed telemetry switch (see .aidd/config.json and
-# aidd_docs/tasks/2026_08/2026_08_20_telemetry-export-enable/phase-1.md),
-# tracked so a fresh clone inherits the project's decision.
+# it is the committed project switch (see .aidd/config.json), tracked so a
+# fresh clone inherits the project's decision.
 .aidd/*
 !.aidd/config.json
 
-# AIDD run-journal records: where they land once .aidd/config.json turns
-# telemetry on (see plugins/aidd-telemetry/hooks/journal.js) - this
-# directory being committed is a location, not a permission. The records it
-# holds never are.
-aidd_docs/runs/*
-!aidd_docs/runs/.gitkeep
-!aidd_docs/runs/README.md
-
 # SpecStory captures (may contain transcripts / secrets)
 .specstory/
 

README.md

@@ -11,7 +11,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best
 🧱 **IDE agnostic** · 🏗️ **Legacy systems** · 🌱 **Token-optimized** · 🇫🇷 **Made in France**
 
 <p>
-  <!--counts:start--><kbd>9 plugins</kbd> · <kbd>52 skills</kbd> · <kbd>2 agents</kbd><!--counts:end-->
+  <!--counts:start--><kbd>9 plugins</kbd> · <kbd>51 skills</kbd> · <kbd>2 agents</kbd><!--counts:end-->
 </p>
 
 [![Open Source](https://img.shields.io/badge/Open_Source-Yes-yellow?logo=open-source-initiative&logoColor=white)](https://opensource.org/)
@@ -315,9 +315,9 @@ UI / UX design — smoke-test only, not ready for use.
 
 ### 📈 [aidd-telemetry](plugins/aidd-telemetry/README.md) 🧪
 
-`3 skills` · **beta**
+`2 skills` · **beta**
 
-Answers what a piece of work cost — tokens, models, and which skill spent them. The switch is git-tracked, so it applies to everyone who clones; opt out per person with `AIDD_TELEMETRY=0`. Nothing leaves your machine.
+Counts the tokens of Claude Code sessions per task, ticket, model and day. Opt-in, and local to your machine.
 
 </td>
 <td width="33%" valign="top">

aidd_docs/memory/architecture.md

@@ -33,7 +33,7 @@ flowchart LR
 | Concern decides placement, not existence | a missing capability goes to the plugin whose concern owns it; the caller delegates |
 | A skill is a router | `SKILL.md` dispatches to actions or protocols; the only place a capability is addressed by name |
 | Recipe skills discover providers at runtime | by description matching. Only agent permission lists and orchestration references name a provider |
-| Observation is its own layer | `aidd-telemetry` journals what a session did; it never reads or writes application source |
+| Observation is its own layer | `aidd-telemetry` counts what a session consumed, from the task a person declared; it never reads or writes application source |
 | A launcher runs an external binary, never embeds it | `kanban` broke that and was unwired. Detail in the CLI bank |
 
 The concern-to-plugin taxonomy is canonical in [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md).
@@ -42,4 +42,4 @@ The concern-to-plugin taxonomy is canonical in [`docs/ARCHITECTURE.md`](../../do
 
 - 9 plugins ship, 3 off the curated install path: `aidd-ui` is alpha, `aidd-telemetry` beta and opt-in, `aidd-qa` new and unproven outside this repository.
 - A skill never links outside itself: the tree ships both flat and as a marketplace, so no relative path survives both.
-- Bundled hooks run Node. No `node` on `PATH`, no memory refresh and no run journal.
+- Bundled hooks run Node. No `node` on `PATH`, no memory refresh and no question about the task.

aidd_docs/memory/cli.md

@@ -7,8 +7,8 @@ The `aidd` binary, built from `cli/` and published to npm as `@ai-driven-dev/cli
 ## Commands
 
 - Eleven groups: `setup`, `framework`, `translate`, `plugin`, `marketplace`, `auth`, `sync`, `update`, `doctor`, `clean`, `telemetry`.
+- `telemetry` counts the tokens of Claude Code sessions locally: [usage contract](../product/usage-contract.md).
 - No list here. The surface moves; `aidd --help` is the only reading that stays true.
-- `telemetry`'s sink, run journal, record shapes, report axes and per-tool declarations: [`cli/aidd_docs/memory/telemetry.md`](../../cli/aidd_docs/memory/telemetry.md).
 
 ## Interface
 

aidd_docs/memory/codebase-map.md

@@ -38,7 +38,6 @@ flowchart TD
 | Binary | `cli/src/cli.ts` → `dist/cli.js`, bin name `aidd` |
 | Workflow | `plugins/<plugin>/skills/<NN>-<name>/SKILL.md` |
 | Memory refresh | `plugins/aidd-context/hooks/update_memory.js`, on `SessionStart` |
-| Run journal | `plugins/aidd-telemetry/hooks/journal.cjs`, on `SessionStart`, `Stop`, `PostToolUse` |
 
 ## Packages
 

aidd_docs/memory/coding-assertions.md

@@ -29,7 +29,7 @@ Never state in a commit message or a report anything not just observed in output
 | 1 | `pnpm exec lefthook run pre-commit` | JSON and YAML validity, `scripts/` tests, skill frontmatter and argument hints, cross-plugin orthogonality and router coherence (`scripts/check-architecture-rules.js`), context imports and reference form, markdown links, the paths the prose names and a sentence written in two documents (`scripts/check-doc-duplication.js`); `cli` lint, architecture, typecheck and type honesty when `cli/` changed. `cli` knip and the full `cli` suite are pre-push, not pre-commit — see below |
 | 2 | `pnpm exec commitlint --edit` | the message against `commitlint.config.cjs` |
 
-Same hook regenerates each plugin's `CATALOG.md`, the README counts and `docs/prompts-documentation.md`, and stages them.
+Same hook regenerates each plugin's `CATALOG.md`, and the README counts, and stages them.
 
 Every `cli` job is globbed on `cli/**`. A change under `kanban/` alone fires no local job; run `cd kanban && pnpm test` by hand. CI does cover it — `cli-ci.yml`'s `kanban-checks`, see `deployment.md`.
 

aidd_docs/memory/deployment.md

@@ -9,7 +9,7 @@ Where the project runs and how it ships: CI/CD, environments, and release.
 | Workflow | Runs |
 | --- | --- |
 | `ci.yml` | commitlint on pull requests and on `main`'s tip, plus the PR title itself — the subject a squash merge uses — then release-please on `main` and the release jobs |
-| `cli-ci.yml` | the `cli` and `kanban` gates — job list in the CLI bank. No `paths:` filter, deliberately: it runs on every push and pull request, and a `changes` job decides in bash whether the rest has anything to do — `cli/**`, `kanban/**`, `scripts/__tests__/**`, `README.md`, the workflow file itself, and `plugins/aidd-telemetry/**` except its `*.md` prose. Mutations skip only for a same-repository numeric `promote/next-to-main-*` snapshot whose `cli / gate` passed in a successful `next` push and whose PR merge tree equals that snapshot with `main` already its ancestor; the resulting `main` push reuses it only for that exact two-parent promotion merge when its tree, associated merged PR, and source snapshot all match. Missing, failed, unreadable, or mismatched Git/API proof keeps normal mutation scopes. All non-mutation checks still run on the current PR merge ref or `main` commit. |
+| `cli-ci.yml` | the `cli` and `kanban` gates — job list in the CLI bank. No `paths:` filter, deliberately: it runs on every push and pull request, and a `changes` job decides in bash whether the rest has anything to do — `cli/**`, `kanban/**`, `scripts/__tests__/**`, `README.md`, the workflow file itself. Mutations skip only for a same-repository numeric `promote/next-to-main-*` snapshot whose `cli / gate` passed in a successful `next` push and whose PR merge tree equals that snapshot with `main` already its ancestor; the resulting `main` push reuses it only for that exact two-parent promotion merge when its tree, associated merged PR, and source snapshot all match. Missing, failed, unreadable, or mismatched Git/API proof keeps normal mutation scopes. All non-mutation checks still run on the current PR merge ref or `main` commit. |
 | `validate.yml` | plugin and marketplace manifests against their schemas, plus the whole pre-commit over the whole tree |
 | `codeql.yml` | code scanning |
 | `promote.yml` | opens the `next` to `main` promote PR, merge auto-merge |