feat(framework): measurement that works on five tools, each proven by a session that ran

.claude-plugin/marketplace.json

@@ -55,6 +55,13 @@
       "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.",
       "strict": true,
       "recommended": false
+    },
+    {
+      "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.",
+      "strict": true,
+      "recommended": false
     }
   ]
 }

.claude/settings.json

@@ -1,18 +1,5 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "extraKnownMarketplaces": {
-    "aidd-framework": {
-      "source": { "source": "directory", "path": "." }
-    }
-  },
-  "enabledPlugins": {
-    "aidd-context@aidd-framework": true,
-    "aidd-dev@aidd-framework": true,
-    "aidd-vcs@aidd-framework": true,
-    "aidd-pm@aidd-framework": true,
-    "aidd-orchestrator@aidd-framework": true,
-    "aidd-refine@aidd-framework": true
-  },
   "hooks": {
     "WorktreeCreate": [
       {
@@ -24,5 +11,21 @@
         ]
       }
     ]
+  },
+  "enabledPlugins": {
+    "aidd-context@aidd-framework": true,
+    "aidd-dev@aidd-framework": true,
+    "aidd-vcs@aidd-framework": true,
+    "aidd-pm@aidd-framework": true,
+    "aidd-orchestrator@aidd-framework": true,
+    "aidd-refine@aidd-framework": true
+  },
+  "extraKnownMarketplaces": {
+    "aidd-framework": {
+      "source": {
+        "source": "directory",
+        "path": "."
+      }
+    }
   }
 }

.github/workflows/cli-ci.yml

@@ -13,10 +13,48 @@ on:
     paths:
       - "cli/**"
       - "kanban/**"
+      # The plugin ships the hooks and skills these jobs exercise, and the Windows job
+      # exists for them in particular - without this, changing any of it runs nothing.
+      - "plugins/aidd-telemetry/**"
+      - "scripts/__tests__/**"
+      # Except its prose. The plugin's markdown is asserted - the README's coverage
+      # table, where its scripts say they live - but only by `scripts/__tests__`,
+      # which `validate.yml` already runs over the whole tree on every push and
+      # pull request, unfiltered and required. Re-running it here costs a Windows
+      # runner for a paragraph, and proves nothing that job did not.
+      #
+      # `**.md`, not `**/*.md`: GitHub's `**` matches any character including a
+      # slash, so the second form needs a slash after it and would miss the
+      # top-level README.md that this exists for.
+      #
+      # Bounded on purpose: on `pull_request` GitHub matches the whole diff, not
+      # the last push, so a branch that also touches cli/ runs everything however
+      # small its newest commit is. This saves the run on a push to next or main,
+      # and on a pull request whose diff is prose and nothing else.
+      - "!plugins/aidd-telemetry/**.md"
   pull_request:
     paths:
       - "cli/**"
       - "kanban/**"
+      # The plugin ships the hooks and skills these jobs exercise, and the Windows job
+      # exists for them in particular - without this, changing any of it runs nothing.
+      - "plugins/aidd-telemetry/**"
+      - "scripts/__tests__/**"
+      # Except its prose. The plugin's markdown is asserted - the README's coverage
+      # table, where its scripts say they live - but only by `scripts/__tests__`,
+      # which `validate.yml` already runs over the whole tree on every push and
+      # pull request, unfiltered and required. Re-running it here costs a Windows
+      # runner for a paragraph, and proves nothing that job did not.
+      #
+      # `**.md`, not `**/*.md`: GitHub's `**` matches any character including a
+      # slash, so the second form needs a slash after it and would miss the
+      # top-level README.md that this exists for.
+      #
+      # Bounded on purpose: on `pull_request` GitHub matches the whole diff, not
+      # the last push, so a branch that also touches cli/ runs everything however
+      # small its newest commit is. This saves the run on a push to next or main,
+      # and on a pull request whose diff is prose and nothing else.
+      - "!plugins/aidd-telemetry/**.md"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -108,6 +146,32 @@ jobs:
       - run: cd cli && pnpm install --frozen-lockfile
       - run: cd cli && pnpm knip:production
 
+  identifier-join:
+    name: cli / Identifier join (Claude Code)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@latest --activate
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+      - 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
+      # configured and none are needed: it points Claude Code at a dead address with a fake
+      # key, and the session id is minted before any of that matters.
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+      # Re-checks what #632 measured once, by running a session: that the identifier a hook
+      # receives is the one the export carries. Everything in this layer joins on that, and a
+      # tool update can break it with nothing else turning red. Exit 2 means the probe could
+      # not form an opinion and says so rather than blaming the tool.
+      - name: Probe the identifier join
+        run: node scripts/probe-identifier-join.cjs
+
   cli-jscpd:
     name: cli / JSCPD (duplication)
     runs-on: ubuntu-latest
@@ -140,3 +204,96 @@ jobs:
       - run: cd kanban && pnpm typecheck
       - run: cd kanban && pnpm lint
       - run: cd kanban && pnpm test
+
+  windows:
+    # Runs under bash (Git Bash, bundled on windows-latest) so every command is the one the
+    # Linux jobs run, not a PowerShell rewrite of it.
+    name: cli / Windows
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@latest --activate
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+
+      # The WRITE path, on the platform where a home directory, a line ending and an absolute
+      # path all resolve differently than they do on the Linux jobs above. It runs before the
+      # CLI is built, on purpose: recording is supposed to need nothing installed, and this is
+      # where that claim is exercised. Reading is the CLI's now, and the e2e project below
+      # covers it on this same runner.
+      - name: Chain - allow measurement, with nothing installed
+        run: |
+          # Written directly rather than through a command: the switch is a file, the hooks
+          # read it fresh at every write, and no binary has to exist for that 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 own cwd is a path from whatever machine captured it - rewritten to
+          # this checkout's real path 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
+      - name: Chain - the journal stays private and git add -A still works
+        run: |
+          git add -A
+          git status --porcelain >/dev/null
+
+      - name: Plugin suite
+        run: node --test "scripts/__tests__/*.test.js"
+
+      - run: cd kanban && pnpm install --frozen-lockfile
+      - run: cd cli && pnpm install --frozen-lockfile
+      # A real global install, not `node dist/cli.js` by path: build, pack, and
+      # `npm install -g` the tarball — the same shim generation a person's own
+      # `npm install -g @ai-driven-dev/cli` produces. Every suite below invokes the built
+      # file directly and proves nothing about whether `aidd` actually resolves on this
+      # platform's PATH — Windows is where that kind of assumption has broken silently
+      # before (`os.homedir()` never reading `$HOME` here). Built here, ahead of the
+      # unit/integration/e2e suites below, so this is the only build this job needs.
+      #
+      # Inlined rather than `pnpm run install:local` (the equivalent script this package
+      # already ships): a package.json script runs through pnpm's own configured shell,
+      # `cmd.exe` on Windows unless `script-shell` says otherwise, which this repository
+      # never sets — its `$(node -p ...)` command substitution is bash syntax and would
+      # not survive that. This step's own `run:` block is guaranteed bash by the job's
+      # `defaults.run.shell` above, so the same two commands run here directly instead,
+      # with a glob standing in for the version substitution.
+      - name: Install the built CLI globally, the way a person actually would
+        run: |
+          cd cli
+          pnpm build
+          pnpm pack --pack-destination ./dist
+          npm install -g ./dist/ai-driven-dev-cli-*.tgz --force
+      # `02-check` diagnoses the chain above through this exact command, lifted from its
+      # own markdown — not a script beside it, the same move `00-init`'s own chain step
+      # made for the switch. `aidd --version` is the same command every skill's own locate
+      # step runs first; failing here 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
+          aidd telemetry check
+      - run: cd cli && pnpm test:unit
+      - run: cd cli && pnpm test:integration
+      # Every e2e but the two named below — and one of them is why this step matters most:
+      # `telemetry-commit-trailer.e2e.test.ts` makes real commits and reads their messages
+      # back, which is the only thing that proves the `prepare-commit-msg` hook this build
+      # installs is reachable by the shell Git for Windows ships. A path written with
+      # backslashes is not, and nothing but this catches it. Exclude it only for a reason as
+      # concrete as the two below.
+      - name: cli e2e
+        run: |
+          cd cli
+          pnpm exec vitest run --project=e2e \
+            --exclude "tests/e2e/persona.e2e.test.ts" \
+            --exclude "tests/e2e/telemetry-multi-tool.e2e.test.ts"
+        # persona.e2e.test.ts hardcodes /usr/bin/expect for TTY emulation, which windows-latest
+        # does not carry. telemetry-multi-tool.e2e.test.ts puts a `#!/bin/sh` stand-in binary
+        # with no extension on PATH; Windows resolves an executable by PATHEXT, never a shebang.

.gitignore

@@ -32,6 +32,22 @@ coverage/
 .claude/settings.local.json
 .claude/worktrees/
 
+# 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.
+.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/
 

.release-please-manifest.json

@@ -7,5 +7,6 @@
   "plugins/aidd-orchestrator": "2.2.1",
   "plugins/aidd-refine": "3.0.0",
   "plugins/aidd-ui": "0.2.1-alpha.0",
+  "plugins/aidd-telemetry": "0.1.0",
   "cli": "5.2.2"
 }

AGENTS.md

@@ -51,6 +51,10 @@ Project docs, memory, specs, and plans live in `aidd_docs/`.
 [aidd_docs/memory/testing.md](aidd_docs/memory/testing.md)
 [aidd_docs/memory/vcs.md](aidd_docs/memory/vcs.md)
 
+<!-- read on demand, not auto-loaded -->
+- aidd_docs/memory/internal/decisions/a-price-table-is-the-destination-s.md
+- aidd_docs/memory/internal/decisions/measurement-may-reach-a-hosted-destination.md
+
 <!-- aidd_project_memory:end -->
 
 - If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file.

CLAUDE.md

@@ -51,6 +51,10 @@ Project docs, memory, specs, and plans live in `aidd_docs/`.
 @aidd_docs/memory/testing.md
 @aidd_docs/memory/vcs.md
 
+<!-- read on demand, not auto-loaded -->
+- aidd_docs/memory/internal/decisions/a-price-table-is-the-destination-s.md
+- aidd_docs/memory/internal/decisions/measurement-may-reach-a-hosted-destination.md
+
 <!-- aidd_project_memory:end -->
 
 - If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file.

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>7 plugins</kbd> · <kbd>47 skills</kbd> · <kbd>2 agents</kbd><!--counts:end-->
+  <!--counts:start--><kbd>8 plugins</kbd> · <kbd>50 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/)
@@ -57,7 +57,7 @@ Why not just write your own commands? → [FAQ](docs/FAQ.md#-why-aidd-instead-of
 
 ### Claude Code
 
-Installs the 6 stable plugins (`aidd-ui` is 🚧 alpha, install separately — see [Plugins](#-plugins)).
+Installs the 6 stable plugins (`aidd-ui` is 🚧 alpha and `aidd-telemetry` 🧪 beta, install separately — see [Plugins](#-plugins)).
 
 **In the session** (slash commands)
 
@@ -231,7 +231,7 @@ learning only when it is durable enough to improve the next feature.
 
 ## 🧩 Plugins
 
-Seven plugins covering the whole SDLC — **install all of them**; they work together. (`aidd-ui` is 🚧 **alpha**, off the curated path.)
+Eight plugins covering the whole SDLC — **install all of them**; they work together. (`aidd-ui` is 🚧 **alpha** and `aidd-telemetry` 🧪 **beta** — both off the curated path.)
 
 <table>
 <tr>
@@ -302,7 +302,15 @@ Synchronous feature flow, async issue-to-PR automation, and product backlog.
 UI / UX design — smoke-test only, not ready for use.
 
 </td>
-<td width="33%" valign="top"></td>
+<td width="33%" valign="top">
+
+### 📈 [aidd-telemetry](plugins/aidd-telemetry/README.md) 🧪
+
+`3 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.
+
+</td>
 <td width="33%" valign="top"></td>
 </tr>
 </table>

aidd_docs/memory/README.md

@@ -27,6 +27,11 @@ Refreshed automatically by the memory hook. Do not edit by hand.
 - [project-brief.md](project-brief.md)
 - [testing.md](testing.md)
 - [vcs.md](vcs.md)
+
+Read on demand:
+
+- [internal/decisions/a-price-table-is-the-destination-s.md](internal/decisions/a-price-table-is-the-destination-s.md)
+- [internal/decisions/measurement-may-reach-a-hosted-destination.md](internal/decisions/measurement-may-reach-a-hosted-destination.md)
 <!-- files:end -->
 
 ## Maintaining it