cherry-works 0.4.0 → 0.6.0

package/README.md

@@ -114,20 +114,26 @@ Each kind comes up at a different time:
 |---|---|
 | `guide` | a touched file matches one of its `globs`, or on every turn when it has no globs |
 | `sensor` | the `signal` it names is raised, and the harness runs its `run` command |
-| `skill` | one of its `triggers` matches the request, or it is called by name as `/skill-<id>` |
-| `playbook` | one of its `triggers` matches; its body is a sequence of skills |
-| `agent` | it is spawned by identity, with only the `tools` it lists |
+| `skill` | one of its `triggers` matches the request, or it is called by name as `/<id>` |
+| `playbook` | one of its `triggers` matches, or it is called as `/<id>`; its body is a sequence of skills |
+| `agent` | it is spawned by its id, with only the `tools` it lists |
 | `posture` | always, wherever the host can be told what to `allow` and `deny` |
 | `corpus` | a primitive's `rationale` cites it, to give the reasoning behind a rule |
 | `mixin` | never on its own; its body is lent to the primitives that pull it in |
-| `mcp` | a primitive's body names it as `mcp:<id>`: a place outside the repository, reached through `cw mcp serve` |
+| `mcp` | a primitive's body names it as `[[<id>]]`: an mcp origin outside the repository, reached through `cw mcp serve` |
 
-`cw kinds <kind>` gives the exact fields each kind takes. An identity is
-`kind:id`, and it names exactly one primitive across the whole charter. If two
-files claim the same identity, the build is refused and both files are named.
+A skill or a playbook that is only a step of another can say
+`disable-user-invocation: true`: it is then not offered as a `/` command, and
+the agent still opens it when its triggers match or a playbook sends it there.
+
+`cw kinds <kind>` gives the exact fields each kind takes. An id names exactly
+one primitive across the whole charter, whatever its kind. If two files claim
+the same id, the build is refused and both files are named. A primitive is
+named by its id alone: bare in a header (`rationale: type-safety`), a test or a
+command, and as `[[<id>]]` in a body, which the build turns into a link.
 Every primitive is a folder holding its `index.md`, and any other file in that
 folder is one of its assets, reached from the body as `./<file>`. An id is at
-most 40 characters, and may be grouped with `/`: `mcp:mfbs/billing` is kept at
+most 40 characters, and may be grouped with `/`: the mcp `mfbs/billing` is kept at
 `.cw/charter/mcp/mfbs/billing/index.md`.
 
 `cw build` compiles every primitive to `.cw/out/<kind>/<id>/index.md`, with its
@@ -145,16 +151,19 @@ agent reads it.
 | `cw list [--kind] [--min]` | List what the charter holds |
 | `cw kinds [kind]` | List the kinds, or the fields one of them requires |
 | `cw add <kind> <id> [--header k=v …]` | Write a new primitive |
-| `cw edit <identity>` | Open a primitive's file in your editor |
-| `cw remove <identity> [--yes]` | Delete a primitive this repository authored |
-| `cw explain <identity>` | Show which file declares an identity, what it pulls in and which tests name it |
+| `cw edit <id>` | Open a primitive's file in your editor |
+| `cw remove <id> [--yes]` | Delete a primitive this repository authored |
+| `cw explain <id>` | Show which file declares an id, what it pulls in and which tests name it |
 | `cw doctor` | Check the agents, the charter, the vendor sources and the compiled output |
+| `cw context [--exact]` | Say how many tokens the charter puts into the agent's context when a session opens |
+| `cw sessions [--since] [--until] [--json]` | Sum up the tokens of the sessions kept on this machine, by day and by session |
 | `cw test` | Run every case in `.cw/test/` against the charter |
+| `cw eval` | Put every case in `.cw/eval/` to the real agent under promptfoo |
 | `cw suite add \| edit \| remove` | Manage test files |
 | `cw vendor add <source> [--ref] \| remove \| list` | Install, update, remove or list vendor sources |
 | `cw portal [--port]` | Open the charter in a browser on this machine |
-| `cw mcp auth [identity] [--status]` | Sign in, as yourself, to every place the charter reaches, or to one again |
-| `cw mcp serve` | Serve every place the charter reaches to your agent, over stdio |
+| `cw mcp auth [id] [--status]` | Sign in, as yourself, to every mcp origin the charter reaches, or to one again |
+| `cw mcp serve` | Serve every mcp origin the charter reaches to your agent, over stdio |
 
 `cw doctor` exits with a failure status when the charter has an error, when a
 vendored file was edited in this repository, or when the compiled output no
@@ -214,15 +223,95 @@ one:
 {
   "description": "The TypeScript guide comes up on source files.",
   "cases": [
-    { "do": { "touchFile": "src/one.ts" }, "expect": { "activate": "guide:no-any" } },
-    { "when": "Stop", "expect": { "run": "sensor:lint" } },
+    { "do": { "touchFile": "src/one.ts" }, "expect": { "activate": "no-any" } },
+    { "when": "Stop", "expect": { "run": "lint" } },
     { "do": { "touchFile": ".env" }, "expect": { "allow": false } }
   ]
 }
 ```
 
 `cw test` resolves each case against the charter and reports the ones that no
-longer hold.
+longer hold. It runs no agent and costs nothing, so it fits in CI.
+
+## Evaluating against the real agent
+
+`cw test` proves what the charter says; `cw eval` proves what the agent does
+with it. A file in `.cw/eval/` holds prompts and what is expected of each:
+
+```json
+{
+  "description": "Planning goes through the planning skill.",
+  "cases": [
+    { "prompt": "plan this feature: export a report as PDF", "expect": { "invoke": "sdd-plan", "maxTokens": 200000 } },
+    { "prompt": "add a function that totals an invoice", "expect": { "follow": "no-single-word-naming" } }
+  ]
+}
+```
+
+Each case expects at least one of:
+
+| Expectation | Passes when |
+|---|---|
+| `invoke: <id>` | the agent invoked that skill or playbook |
+| `follow: <id>` | a model judge finds the agent followed that guide |
+| `maxTokens: <n>` | the case used no more than that many tokens |
+
+```bash
+cw eval
+```
+
+Every case is handed to [promptfoo](https://www.promptfoo.dev), which puts its
+prompt to Claude Code run headless, in a worktree of your last commit with the
+charter built, so your working tree is never touched. You never write a
+promptfoo configuration. The first run installs promptfoo and the Claude Agent
+SDK under `~/.cherry-works/promptfoo/`, and later runs reuse them.
+
+The report gives each case's outcome and tokens, and the run's total. A case
+that misses what it expects fails the run, with what the agent did instead.
+It runs on whatever Claude Code is signed in with, or on `ANTHROPIC_API_KEY`
+when set, and spends real tokens: commit before you run it, and keep the cases
+few.
+
+## What the charter costs
+
+Everything the charter loads when a session opens — always-on guides, every
+skill's description, every subagent's — is paid for on every turn.
+
+```bash
+cw context           # each primitive's tokens, the largest first, estimated
+cw context --exact   # counted through the agent's own command line
+```
+
+A guide with `globs` is listed apart: it is loaded only when a file it names is
+touched. `cw build` prints the total in one line, the portal shows the same
+list, and `cw doctor` warns once the total passes `mainContextCeiling` in
+`.cw/settings.json` (20,000 tokens unless you set it).
+
+Once a session runs, the engine's own Stop hook counts what it has used, its
+subagents included, each time the agent stops. It keeps one line per stop
+under `~/.cherry-works/` (or the folder `sessionAnalysisFolder` names), never in
+the repository, and tells you in one line each time a session crosses another
+`sessionContextMark` tokens (100,000 unless you set it). The model is never
+sent that line.
+
+```bash
+cw sessions                          # the last 31 days, by day and by session
+cw sessions --since 2026-10-01       # 31 days from that day at most
+cw sessions --since 2026-10-01 --until 2026-10-05 --json
+```
+
+To put a price on it, ask your agent what last week cost: the built-in
+`cw-session-cost` skill reads the same summary, asks whether to use prices you
+type or the provider's published ones, and answers per session and per day,
+naming the prices it used.
+
+```json
+{
+  "agents": ["claude"],
+  "mainContextCeiling": 20000,
+  "sessionContextMark": 100000
+}
+```
 
 ## Vendor sources
 
@@ -235,7 +324,7 @@ there, test it, and push. Only its `.cw/charter/` folder is installed, under
 `.cw/vendor/<name>/`, pinned to the ref you chose and committed. A repository
 without that folder is refused, and so is one that has vendors of its own:
 vendoring is one level deep. Vendored primitives are read-only. To differ from
-one, write your own primitive under a new identity.
+one, write your own primitive under a new id.
 
 Run `cw vendor add` again with a new `--ref` to update a source, and
 `cw vendor remove <name>` to take it away. Run `cw build` after either.
@@ -244,12 +333,13 @@ Run `cw vendor add` again with a new `--ref` to update a source, and
 
 | Charter | What it gives your agent | Install |
 | --- | --- | --- |
+| [sdd-charter](https://github.com/tamnguyenvt/sdd-charter) | Spec-driven development: a spec set with a status per story and a roadmap of their dependencies, and six commands (`/sdd-init`, `/sdd-plan`, `/sdd-implement`, `/sdd-bug-fix`, `/sdd-status`, `/sdd-report`) that take each story from request to merge, stopping for your yes at each step. | `cw vendor add git@github.com:tamnguyenvt/sdd-charter.git --ref v0.1.7` |
 | [hexagonal-architecture-charter](https://github.com/tamnguyenvt/hexagonal-architecture-charter) | Sets up a hexagonal (ports and adapters) architecture in a folder you choose, then keeps the agent following it. | `cw vendor add git@github.com:tamnguyenvt/hexagonal-architecture-charter.git --ref v0.1.0` |
 
-## Places outside the repository
+## MCP origins outside the repository
 
 Much of what an agent needs to know is kept elsewhere: another service's code,
-an issue tracker, a wiki. An `mcp` primitive declares one such place, an MCP
+an issue tracker, a wiki. An `mcp` primitive declares one such mcp origin, an MCP
 server, and the tools of it your agent may use:
 
 ```markdown
@@ -266,31 +356,38 @@ tools: ["get_file_contents", "search_code", "list_pull_requests"]
 The billing service. Look here before changing anything that charges a customer.
 ```
 
-A place is either an `endpoint` reached over HTTP, or a `command` with its
+An mcp origin is either an `endpoint` reached over HTTP, or a `command` with its
 `args` that `cw` starts as a local process; a local one takes a token only, in
 the environment variable its `tokenEnv` names. Any primitive points the agent
-at a place by naming it in its body as `mcp:mfbs/billing`.
+at an mcp origin by naming it in its body as `[[mfbs/billing]]`.
 
 ```bash
 cw build            # adds one entry, cw mcp serve, to your agent's .mcp.json
-cw mcp auth         # sign in to every place you are not signed in to yet
+cw mcp auth         # sign in to every mcp origin you are not signed in to yet
 cw mcp auth --status
 ```
 
-Every developer signs in as themselves, by browser where the place offers OAuth
+Every developer signs in as themselves, by browser where the mcp origin offers OAuth
 or with a token typed at a hidden prompt. Credentials are kept in the operating
 system's credential store, never in the repository, and renewed without asking
-where the place allows it. `cw mcp serve` is the one MCP server your agent is
-given: it serves the tools each place declares and forwards every call under
-your own credential. A place that is down or not signed in to loses only its own
+where the mcp origin allows it. `cw mcp serve` is the one MCP server your agent is
+given: it serves the tools each mcp origin declares and forwards every call under
+your own credential. An mcp origin that is down or not signed in to loses only its own
 tools.
 
-A subagent reaches only the places it lists under `tools`: `mcp:<id>` for every
-tool of a place, or `mcp:<id>:<tool>` for one of them.
+The build asks each mcp origin for its tools once and keeps them beside the
+charter, and turns your agent's own tool search on: a session opens with each
+tool's name and no schema, and the agent looks up the one it needs. `cw mcp
+serve` lists the kept tools without reaching any mcp origin, and reaches one
+only for a call. A tool an `mcp` declares that its mcp origin does not list
+stops the build.
+
+A subagent reaches only the mcp origins it lists under `tools`: `[[<id>]]` for every
+tool of an mcp origin, or `[[<id>]]:<tool>` for one of them.
 
 ## Your agent can write rules too
 
-Every governed repository gets a built-in skill, `skill:cw-author`, in the
+Every governed repository gets a built-in skill, `cw-author`, in the
 agent's hands from the moment `cw init` finishes. It teaches
 the agent to ask `cw kinds` what a kind requires and to write primitives with
 `cw add`, instead of copying fields from memory.

package/dist/cw.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "cherry-works",
-  version: "0.4.0",
+  version: "0.6.0",
   description: "The charter engine: resolves a charter and compiles it into what a coding agent reads.",
   keywords: [
     "claude-code",
@@ -42,11 +42,9 @@ var package_default = {
   scripts: {
     build: "tsup && tailwindcss -i src/driver/portal/page/styles.css -o dist/portal/styles.css --minify",
     typecheck: "tsc --noEmit && tsc --noEmit -p src/driver/portal/page",
-    test: 'pnpm run lint:deps && pnpm run build && node --import tsx --test "test/**/*.test.ts"',
-    cw: "node --import tsx main.ts",
+    test: 'pnpm run lint:deps && pnpm run build && node --import tsx --import ./scripts/moduleLoader.mjs --test "test/**/*.test.ts"',
+    cw: "node --import tsx --import ./scripts/moduleLoader.mjs main.ts",
     "lint:deps": "depcruise src main.ts",
-    "specs:link": "node --import tsx scripts/link-specs.ts",
-    "specs:check": "node --import tsx scripts/link-specs.ts --check",
     release: "node --import tsx scripts/release.ts",
     prepublishOnly: `node -e "console.error('Publish with \\"pnpm release <version>\\", which checks the package first.'); process.exit(1)"`
   },
@@ -56,6 +54,9 @@ var package_default = {
     "@codemirror/language": "^6.12.4",
     "@codemirror/state": "^6.7.4",
     "@codemirror/view": "^6.43.11",
+    "@hono/node-server": "^2.1.1",
+    "@hono/zod-openapi": "^1.6.3",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@tailwindcss/cli": "^4.3.3",
     "@tanstack/react-query": "^5.103.2",
     "@types/node": "^22.10.2",
@@ -68,9 +69,14 @@ var package_default = {
     clsx: "^2.1.1",
     cmdk: "^1.1.1",
     "dependency-cruiser": "^18.2.0",
+    hono: "^4.13.7",
+    "js-tiktoken": "^1.0.21",
     "lucide-react": "^1.47.0",
     marked: "^18.0.13",
+    picomatch: "^4.0.7",
     playwright: "^1.63.0",
+    promptfoo: "0.123.1",
+    prompts: "^2.4.2",
     "radix-ui": "^1.6.7",
     react: "^19.3.0",
     "react-dom": "^19.3.0",
@@ -80,23 +86,15 @@ var package_default = {
     tsup: "^8.3.5",
     tsx: "^4.19.2",
     "tw-animate-css": "^1.4.0",
-    typescript: "^5.7.2"
+    typescript: "^5.7.2",
+    yaml: "^2.9.0",
+    yargs: "^18.1.0",
+    zod: "^4.6.1"
   },
   pnpm: {
     onlyBuiltDependencies: [
       "esbuild"
     ]
-  },
-  dependencies: {
-    "@hono/node-server": "^2.1.1",
-    "@hono/zod-openapi": "^1.6.3",
-    "@modelcontextprotocol/sdk": "^1.31.0",
-    hono: "^4.13.7",
-    picomatch: "^4.0.7",
-    prompts: "^2.4.2",
-    yaml: "^2.9.0",
-    yargs: "^18.1.0",
-    zod: "^4.6.1"
   }
 };