@su-record/vibe 4.1.30 → 4.2.0

package/internal/legacy-readme.md

@@ -0,0 +1,228 @@
+# vibe 4
+
+**Use AI as an FDE.** Start with the customer's problem, agree on what success means, build, prove the result, and hand it to the person who will run it. vibe carries that procedure across clients and sessions, with executable checks and recorded decisions.
+
+The [4.1.25 measurements](bench/claims/2026-09-09-4.1.25.md) are historical evidence toward that purpose: equal observed final artifact scores, with the supplied-scope arm using 0.69× and 0.81× bare weighted input tokens on a two-session task, 0.75× on a Claude-to-Codex handover, and 0.61× and 0.50× on the brownfield task. The arm that wrote its own scope used 1.3–5.8× bare weighted input tokens. Those final scores did not measure the quality of discovery or agreement. Six trap attempts failed to separate the arms; no prevention number is claimed. The 4.1.26 comparison evaluates the agreement separately and requires new evidence before any new quality or cost claim.
+
+Main surfaces: Claude Code · Codex CLI · ChatGPT desktop app · Hermes Agent · Claude desktop app (interview, approval, verdict, handoff).
+
+```bash
+npm i -g @su-record/vibe
+```
+
+That is the whole install. The package registers itself as a local plugin in every client it finds and `vibe setup` or `vibe update` keeps the registration current — a query such as `vibe state` never touches the install, and `vibe status` says when it is stale:
+
+| client | what the install does |
+|---|---|
+| Claude Code | `claude plugin marketplace add <package dir>` + `claude plugin install vibe@vibe` — skills and hooks come from the plugin, the card from its SessionStart hook |
+| Codex CLI · ChatGPT desktop | assembles the plugin tree under `~/.config/vibe/plugin`, registers the personal marketplace, runs `codex plugin add vibe@vibe-local`; the card goes into `~/.codex/AGENTS.md`; restart ChatGPT desktop afterwards. On an update the version just replaced stays in Codex's cache, so a session that started under it keeps its hooks until it restarts (a hook that exits 1 on every call is a session older than the install — restart it) |
+| Hermes Agent | six skills into `~/.hermes/skills`, the card block into `~/.hermes/SOUL.md` |
+| Claude desktop app | `vibe plugin mcpb --out vibe.mcpb`, open the file in the app, pick the project folder — an MCP Bundle whose only job is to call the `vibe` CLI; for the interview, approval, verdict and handoff, not for writing code |
+| no client CLI on PATH (or `VIBE_NO_PLUGIN=1`) | the older path: card, skills and hook written into the client home |
+
+`vibe status` shows the mode and version per client and says when a newer version exists; `vibe update` installs it and re-registers the plugins; `vibe uninstall` unregisters and removes everything. Nothing is published to a public marketplace — the plugin is the package on your disk.
+
+Then, in chat:
+
+```
+/vibe every week an order spreadsheet arrives — turn it into a settlement sheet and send it to accounting
+```
+
+## The flow
+
+```
+request          `vibe state` says the stage and the next step; bind the host session to this worktree
+  → discover       evidence first; ask only about consequential unknowns, up to three per round
+  → scenarios      sufficient agreement · executable checks · needed tools → one approval
+  → build          everything first, then one `vibe check --all`; on a failure, fix what the check names; `vibe context <id>` when that is not enough
+  → prove          explicitly run `vibe check --all` — every scenario plus every regression, ordered by the work graph
+  → report         from the check output; HANDOFF.md only when the intent asks; irreversible steps need a token
+```
+
+Any client can pick the work up: `vibe state` says where you are, because the state lives in plain files inside the repository. There is no handoff document — the state is the handoff.
+
+In the intended worktree, run `vibe session bind` once per host session. It uses `CODEX_THREAD_ID` or `CLAUDE_SESSION_ID`; if the host supplies only a hook `session_id`, pass that exact value with `--session <id>`. `vibe session status` reports the association. Binding is explicit and private to the local machine: a copied ledger, parent repository or sibling worktree cannot choose the session's target. Missing or conflicting identifiers leave Stop unavailable until the association is corrected.
+
+SessionStart and Stop perform bounded local reads with packaged modules. They run no checks, models, services or PATH commands. Stop recognizes completion only from a fresh explicit-check record for the exact canonical worktree, revision, contract and files. It blocks unchanged unfinished work at most twice, then releases it as unmet. An inbox wait or scenario handoff also releases without success. Titles, check output, transcript claims and handoff reasons never become Stop instructions.
+
+Session bindings, retry counters and explicit-check proofs live outside the project in `~/.vibe-runtime`, with private directory/file permissions and linked-entry rejection. Rebinding does not clear an existing retry counter. On Windows, confidentiality still depends on the user's home ACL; POSIX mode bits cannot prove it. A project fingerprint is bounded to 10,000 entries, 64 MiB total, 8 MiB per file and a 1.5-second traversal budget. Unsupported files, changing inputs or exceeded limits produce a private unavailable snapshot while preserving the explicit check's verdict. Stop then reports unavailable and unmet. Failure to write the private proof itself remains an error. Git metadata, dependency trees and client configuration directories are excluded from this fingerprint; contract files, configuration and regressions under `.vibe/` remain included.
+
+The private proof also retains the reviewed execution plan. Stop compares the local consent receipt, PATH/PATHEXT, shell and Node paths, selected environment values, declared working directories and verifier hashes without executing them. External declared verifier files are included in that comparison. Reads are capped at 512 distinct verifier files, 32 MiB total and one second; unavailable or changed context cannot become verified completion. Undeclared shell dependencies and same-user hostile processes remain outside this guarantee.
+
+Read fewer relevant files, each in full: Claude Code uses Read, Codex uses `cat`. The Bash hook blocks recognized slices of the current state's files, `.vibe/intent.md`, `scenarios.yaml` and `spec/` or `specs/`; other source/document slices receive a warning each time. `grep -n`/`rg -n` locate lines, `-l` locates files; file-fed `head`, `tail`, `sed -n`, `cut` and `awk` excerpts do not replace reading the source. Logs, `.dev/` and pipelines carrying command output remain exempt. The recognizer does not execute or expand shell variables, aliases or heredocs. An unavailable state-file mirror is reported, and the built-in contract/spec rules still apply.
+
+Slice-read counters contain only blocked/warned counts in the private runtime store. Benchmark initialization distinguishes a measured zero from a missing or unreadable counter; each session records the difference and each attempt records the sum. No shell command or file excerpt is copied into these counter records.
+
+A clear request needs no ceremonial interview. Relevant documents and sample profiles can answer questions before the customer is asked. An unanswered material question remains unanswered even if a default was proposed. Research and new integrations are used for a specific unresolved need, not on every local task.
+
+An intent can record its stable evidence files with `sources` in the `intent draft --stdin` payload. Their content hashes become part of the approval; `vibe intent show --json` reports `sourceBasis` and names changed or missing inputs. Reuse unchanged findings and re-evaluate affected decisions when the evidence changes. Generated outputs, session prompts, and files the implementation will edit are not stable evidence inputs.
+
+## Find work AI can take over
+
+```text
+/vibe Look at these work logs, exported mail, documents and meeting notes. Find recurring work worth automating, agree on one item with me, and build a checked local pilot.
+```
+
+vibe establishes the observation window, counts distinct work events, and records which have measured active time. The same event in a message and a meeting note counts once. Missing duration stays unknown; meeting length and a vendor's productivity claim do not establish time saved.
+
+Each grounded opportunity names its sources, input/output, tool or connection, setup, failure cases, permission and human-review boundaries, rollback, and an executable check. Rank up to three feasible candidates against the customer's objective, then agree on one to build. Fewer than three is a valid result. A request to find opportunities does not itself authorize an external installation, send, payment, or deletion.
+
+The selected local pilot must work on changed input, handle a failure, preserve source data, and support rerun and rollback. Report its actual behavior and machine runtime. Human time saved or ROI requires a comparable manual baseline and measured setup, correction, review, and maintenance effort; without those, the value remains unknown.
+
+## Five things the harness does (and nothing else)
+
+1. **Independent verdict.** Every scenario carries a check: `run` (exit code), `file` (exists / regex / contains / JSON Schema / column sum), `http` (status / JSON Schema / latency ceiling), `eval` (count of matching labelled cases through a runner), or `human` (no verdict — goes to the inbox). Only what `vibe check` executed itself becomes evidence. A model saying "done" changes nothing; DONE is void the moment a file changes.
+2. **Memory across sessions and clients.** `.vibe/` holds the intent, scenarios, evidence, ledger, inbox, regressions and knowledge as plain files you can read and commit.
+3. **Permission stays with people.** Who may authorize is your policy, not the harness's law (see below).
+4. **A ledger, not a claim.** Every run records client, model, result, cost when the client provides it. Comparisons are ledger queries with four verdicts — insufficient runs, mixed scenario sets, inconclusive, difference observed — and never a winner, ratio or percentage. Events also carry typed edges (`supersedes`, `decided-by`, `implements`, `caused`), so `vibe ledger why <node>` can answer "why does this regression exist" or "which approval covers this file".
+5. **It speaks first.** Human attention is narrow. At each stage the harness surfaces up to three things you did not ask about, each with a reason it found in your files, ledger or history.
+
+## Check types
+
+| type | verdict | arguments |
+|---|---|---|
+| `run` | exit code | `cmd`, `expect` (default 0), `timeoutMs`, `cwd` |
+| `file` | exists · regex · substring · absence · traceability · accessibility · JSON Schema · column sum | `path`, `exists` / `pattern` / `contains` / `absent` (a regex that must match nowhere; the first three hits are named by line; `@placeholders` is the built-in expression for lorem-ipsum text, a bracketed TODO, a to-be-decided mark, a company-name placeholder, unfilled double-brace fields and double-square-bracket notes, and combines with your own words by `|`) / `traceable: <evidence file>` (every number in the file, two significant digits or more, outside fenced code, appears in the evidence file; the first three that do not are named by line) / `a11y: true` (an html file: `<img>` without alt, a skipped heading level, a button or link with no text or aria-label, an input without a label, and a CSS rule whose text colour on its background is under 4.5:1; a `.css` file gets the contrast rule alone) / `schema` / `sum: {column, equals, tolerance}` |
+| `http` | status · body schema · latency ceiling | `url`, `method`, `expect: {status, schema, maxMs}`, `timeoutMs` |
+| `eval` | count of matching cases (never a ratio) | `cases` (jsonl `{id, input, expected}`), `runner` (stdin → stdout), `expect: {pass}` |
+| `review` | an antislop pack's reviewer stages, in order, run by the harness through the client CLI; a stage passes only on an exact `PASS` | `path` (the artifact: a file, or a directory for `pack: design` / `pack: code`), `pack` (`ko` · `en` · `design` · `code`), `lang` (`ko` · `en`, else detected from the text), `contract`, `evidence`, `screenshot`, `changed` (`true`: what changed under `path` against HEAD plus the files that import it, one hop; a git ref: against that ref; nothing changed passes and reviews nothing), `timeoutMs` |
+| `human` | none — a question in the inbox | `question` |
+
+`review` is the only model-judged check: the harness runs each reviewer stage through the client CLI slim — `claude -p` with the stage prompt as its system prompt, `Read` as its only tool (for a screenshot; every other tool schema costs tokens on every stage), no settings and no project context, in the neutral directory the reader uses; `codex exec --skip-git-repo-check --json` with the prompt leading the message — at the client's default model, and reads the reply; nothing the writing model says about its own prose counts. Stages never share a session: the chief editor must not see the copy editor's verdict, and that outranks cache. Each stage's token usage is in the check's tail and evidence, and lands in the ledger as a `usage` event on the run in progress, as does every `vibe read --ask`; `ledger compare --metric cost` adds it to the run's cost. `VIBE_REVIEW_CMD` keeps a stateless text command; `VIBE_REVIEW_CLIENT=claude|codex` forces a driver.
+
+Which model a role runs at is the project's to set, not vibe's to know: `.vibe/config.json` takes `reader: { model, effort }` and `reviewer: { model, effort }` — names the client understands, passed as `--model` / `--effort` to Claude and `-m` / `-c model_reasoning_effort=` to Codex — and `VIBE_READER_MODEL`, `VIBE_READER_EFFORT`, `VIBE_REVIEWER_MODEL`, `VIBE_REVIEWER_EFFORT` override them for one run. Unset keeps the defaults: the reader on Claude `haiku` and Codex at `low` effort, the reviewers on the client's default model. A changed model or effort starts a new reader session rather than resuming one made by another. vibe carries no model catalogue on purpose — a catalogue goes stale with every provider release, and the aliases follow the clients. The scope skill marks such a scenario `⚠ model-judged`, and the same REJECT twice in a row is STUCK like any other failure.
+
+A project's code-size rule is a scenario too: `check: { type: run, cmd: "vibe size src --max-file 400 --max-function 50" }` — `vibe size` exits 1 when a file or function is over, and the scope skill proposes it whenever an intent writes code.
+
+The harness reads what the customer sends, so every client sees the same text: `vibe profile <file>` (csv · tsv · jsonl · json · xlsx) prints columns, types, missing values, duplicates and up to three anomalies before the interview; `vibe read <file>` (xlsx · docx · pptx · pdf · hwp · hwpx · html · tables) returns the text, sheets as markdown tables, and names the reader it used — Office XML, Hangul HWP 5 (OLE + zlib records) and HWPX are parsed in-house with no dependency, PDF through `pdftotext` when installed and a built-in reader otherwise, HTML as content without markup. Images are left to the client's own model.
+
+`vibe read <file…> --ask "<question>"` hands the same extraction to a low-reasoning model and returns only its answer: the harness numbers the lines of code and text files (`12| …`), wraps each file in a `<file path>` block, puts the question last and sends the bundle on stdin to the reader command — `VIBE_READER_CMD`, else `reader` in `.vibe/config.json`, else `claude -p --model haiku`, else `codex exec -c model_reasoning_effort=low -`. The corpus never enters the frontier model's context, and the answer carries line numbers, which a plain summary loses. The cache is the harness's to manage: the client CLIs run as readers in a neutral directory (`~/.config/vibe/reader`) with their own system prompt, no tools and no settings — 428 tokens of context instead of the 16,000 a bare `claude -p` inside a project carries — and one reader session is kept per file set (`~/.config/vibe/reader/sessions.json`, keyed by the exact bundle, one hour). A second question over the same files resumes that session and sends only the question, so the corpus is read from the prompt cache; measured with Haiku, a 37,576-character bundle went from $0.044 and 9.8 s to $0.0053 and 5.3 s. The report on stderr (and `--json`) says whether the session was new or resumed and how many tokens were read from cache. Editing and debugging still read the real file: card rule 8 says so, and the notification hook says the same thing once when a file over 400 lines is opened inside a vibe project (advice only — it never blocks).
+
+## The work graph
+
+A scenario may declare what it depends on:
+
+```yaml
+- id: build
+  then: dist is produced
+  check: { type: run, cmd: "npm run build" }
+- id: tests
+  needs: [build]
+  then: every test passes
+  check: { type: run, cmd: "npm test" }
+```
+
+`vibe check` runs scenarios whose parents have passed, up to four at a time, then their dependents. A dependent of a failed parent is reported `blocked` and never run. `vibe check tests` pulls in `build` if it has not passed yet. Unknown ids, cycles and a `human` parent are rejected at draft time. `vibe state --graph` prints the graph as mermaid with the last result on each node.
+
+Routing stays in code: the model never decides the order. Keep a graph under six connected scenarios; past that, split the intent. When independent scenarios are built by parallel agents, each works in its own worktree and the branches are merged before `vibe check --all` — the harness orders checks, it does not run agents.
+
+## Token policy
+
+```bash
+vibe tokens strict         # approval and irreversible actions both need a six-digit human token
+vibe tokens irreversible   # a plain "yes" approves; push/deploy/send/delete/spend need a token
+vibe tokens off            # default — no tokens; everything is recorded as "auto" (you already skip permissions)
+```
+
+The policy is per project (`.vibe/config.json`); `vibe tokens` alone prints it. Tokens are six digits, valid ten minutes, single use, bound to what they authorize, and stored only as hashes. The verdict itself is never configurable.
+
+## Commands
+
+```
+setup     update [--check] · status · tokens · uninstall [--purge-state] · plugin build | mcpb | install | status
+work      state [--graph] · read <file…> [--ask "…"] · profile <file> · intent draft | show | analyze · approve · check [id…] [--all] · evidence · abandon
+session   session bind [--session id] · session status [--session id]
+checks    run · file · http · eval · review · human · size [--max-file 400] [--max-function 50]
+map       map · symbols <file> · callers <symbol> · blast · context <scenario> · conventions
+human     ask · authorize --action <action> · inbox [answer <id> "…" | resolve <id>]
+memory    regress record | list · knowledge add [--global]
+research  research --from-intent | "query" [--days 30]
+skills    skill suggest · create · add · search · list · used · prune · dismiss
+ledger    ledger · ledger compare --metric checks|turns|cost|ms|tokens [--paired] [--client] [--task] · ledger why <node> · ledger edges [--type]
+```
+
+`vibe --help` has the details. Every command accepts `--json`. The exit code is the verdict: 0 ok · 1 verdict failed · 2 usage · 3 token · 4 invalid transition.
+
+## Research — see what exists before building
+
+`vibe research --from-intent` turns the intent title, the hosts its `http` checks target and the stack into queries, searches GitHub repositories, code (`SKILL.md` files — needs a token) and skill catalogs, and ranks up to five candidates — what moved inside the research window first (`--days N`, default 30: the latest releases, else the latest commit, one or two requests per repository), then keyword match, recency, stars and license; evidence outside the window is demoted, never dropped. Each candidate carries one action: `vibe skill add …`, a knowledge note, or none. The note lands in `.vibe/knowledge/research/`; the same query is cached for a day. Nothing fetched is executed or installed.
+
+Run it when a consequential tool or technical choice remains unresolved after inspecting the available capabilities. Reuse an installed tool when it already meets the agreed check.
+
+Default catalogs: `anthropics/skills`, `vercel-labs/agent-skills`, `NousResearch/hermes-agent` (a skill is any directory with a `SKILL.md`, at any depth). Add your own under `catalogs` in `.vibe/config.json`. Without a GitHub token (`GITHUB_TOKEN`, or `gh auth login`) code search is skipped and catalogs are read within the public limits.
+
+## Skills
+
+Six common skills ship with the package — `vibe` (entry), `vibe-discover`, `vibe-scope`, `vibe-build`, `vibe-prove`, `vibe-handoff` — under 300 lines in total, named by the Agent Skills grammar (lowercase, digits, hyphens; name = directory) so Claude Code, Codex and ChatGPT load them alike. They contain the harness command sequence and message shapes for each stage, nothing about how to code.
+
+Antislop packs ship next to the six. A pack is a medium, not only a language: `antislop-ko` and `antislop-en` carry the writing principles that strip AI clichés and translationese, `antislop-design` the ones that strip generic AI interfaces (the gradient hero over three glass cards, emoji icons, invented stat tiles, fade-up on every section, one typeface, everything centred), `antislop-code` the ones that strip generic AI code (a comment that restates the line, a guard for an impossible state, a try that swallows, an interface with one implementation, a Manager/Helper/Utils name, a wrapper that only forwards, dead code kept just in case, a TODO that ships). Each pack's `reviewers/<pack>/N-<stage>.md` files are the stages the `review` check runs in order — text: copy editor then chief editor; design: markup reviewer then art director; code: reviewer then maintainer — and they are installed as client agents too (`agents/<pack>-<stage>.md` for Claude Code, TOML under the Codex plugin tree). A pack loads only when that medium is worked on.
+
+The design pack judges source, not pixels: `check: { type: review, pack: design, path: <file or directory>, contract: <brief>, screenshot: <png> }`. The harness renders nothing — when a screenshot is wanted, an earlier scenario produces it with the project's own tooling and this check hands the path to the art director, who opens it. The text packs keep working through `lang` and through the language of the manuscript.
+
+The six live in the client home, not in the repository. Project-specific skills live only inside the project (`.claude/skills`, `.codex/skills`, registry in `.vibe/skills/`) and are installed only when bound to a check or carrying knowledge the model lacks:
+
+```
+vibe skill suggest                         # ≤3 proposals from signals: http hosts, regression clusters, repeated questions, handoff
+vibe skill create <name> --check run|file|http|eval [--from-scenario <id>]
+vibe skill add owner/repo[@name] [--pin <sha>] [--yes]   # shows the commands inside, installs only with --yes, pinned to a commit
+vibe skill search <keyword> · list · used <name> · prune [--unused-runs 10] · dismiss <ref>
+```
+
+Proposals are proposals: the harness never installs a proposed skill or runs remote commands without an explicit action. Its local installation and private runtime records live outside the project. A dismissed proposal is not repeated.
+
+## Language
+
+The always-on card (1KB), the skills and every record vibe writes are English. The model talks to you in your language.
+
+## What is inside `.vibe/`
+
+```
+intent.md        what and why — the one page you approve
+scenarios.yaml   given / when / then + the check that judges each + needs (the work graph)
+source-basis.json optional evidence-file hashes bound to the approval
+evidence/        what the harness actually ran, per run
+ledger.jsonl     state changes, client, model, results, cost, typed edges
+inbox.jsonl      questions, STUCK notices, token hashes
+regressions/     fixed failures as reproducing checks
+knowledge/       domain notes the model reads when it needs them; research/ holds search notes
+skills/          registry of project-local skills and dismissed proposals
+cache/           research results (one day) · map.json (the codebase map, keyed by the tree)
+config.json      token policy · skill catalogs · reader and reviewer model settings
+```
+
+## Status
+
+`4.0.0` — phase 1: CLI core + Claude Code. Phase 2: Codex CLI and ChatGPT desktop adapters, the work graph and typed ledger edges. Phase 3a: `http` / `eval` checks, column sums, sample profiling. Phase 3b: GitHub research, project-local skills and proposals. Phase 3c: the end-to-end order-settlement example. Phase 4: the bench and `ledger compare --by harness`. `4.0.2`: no `init` — the card, skills and hook live in the client home and any `vibe` command repairs them. `4.0.3`: `vibe uninstall` also clears what an older `init` left in the project. `4.1.0`: the package is the plugin — `npm i -g` registers a local plugin in Claude Code and Codex/ChatGPT, Hermes Agent joins as a client, `vibe plugin build --check` gates manifest drift. `4.1.1`: `vibe update`. `4.1.2`: the Claude desktop app through an MCP Bundle (`vibe plugin mcpb`). `4.1.3`: the bundle finds the CLI without the shell's PATH (Homebrew, nvm, fnm, volta) or from a path set at install. `4.1.4`: `vibe read` for xlsx · docx · pptx · pdf, `vibe profile` reads xlsx, card rule 8 (read files whole). `4.1.5`: `vibe read` for Hangul hwp · hwpx and html. `4.1.6`: `vibe size`, a built-in file/function size check for any project; the CLI split into modules; the repository's own limit is now per file (400), not a total. `4.1.7`: hook entries left by vibe 3 that point at a missing script are swept at every command, so Claude Code stops reporting them. `4.1.8`: the five stage skills are `vibe-discover` … `vibe-handoff` (a dot is outside the Agent Skills name grammar) and the dotted directories an older install left in a client home are swept; `.vibe/` means one thing — the plugin tree moves to `~/.config/vibe/plugin`, a `.vibe/` counts as a project only when it holds a record, the search stops at `.git` and never lands on the home, `vibe state` shows `root`, a `run` check that exits 127 names its cwd; the `review` check and the `antislop-ko` · `antislop-en` language packs — the harness runs a copy editor and a chief editor on human-read text and passes only on `PASS`. vibe 3 stays on its 3.x tags and is no longer developed. `4.1.9`: Codex follows `vibe update` — the version Codex actually holds is read from its cache, compared with the package and re-registered (remove + add) when behind; a marketplace entry still pointing at the ≤ 4.1.7 store is drift; `vibe status` reports the Codex plugin version it read, not the package version. `4.1.10`: `vibe read --ask` — the harness reads for the model: files (numbered) go to a low-reasoning reader on the client CLI and only the answer returns; the reader runs slim (own system prompt, no tools, no settings, neutral directory) and one session per file set is resumed for follow-up questions so the corpus is read from cache, with the hit reported; the hook advises `--ask` on reads over 400 lines; card rule 8 says when to delegate; the `review` check's Codex command gets `--skip-git-repo-check`. Also: `regress record` made ids longer than the 40-character rule, so every recorded regression was silently left out of `check --all` — the id now fits, a file that parses to nothing is named in `vibe state`, and the repository's four regressions run again. `4.1.11`: antislop reaches design — `antislop-design` and its two reviewers (markup reviewer, art director) join the text packs, reviewer stages are data (`reviewers/<pack>/N-<stage>.md`), the `review` check takes `pack`, a directory of source and a `screenshot`; the text packs gain strength tiers, five questions before a cut, the portability test, notes-to-the-writer, sample-outranks-rules and a what-is-not-a-tell list, and the reviewers may name what to keep. `4.1.12`: the agent's own report is not slop — card rule 9 (what changed apart from what `vibe check` verified; keep the caveat that changes the next step; an error is its cause and fix; answer first, no praise, apology or closing offer) and a Report voice section in `vibe-handoff` (each Built line names its check and run or says "not checked"; estimates in turns and tool calls, never calendar time; the handoff document follows `antislop-en`). `4.1.13`: the deterministic pre-gate — `file … absent` (a regex that must match nowhere: placeholders, a writer's note in double square brackets that was reprinted into the artifact), proposed by the scope skill next to every `review`; this repository gates its own documents the same way. No word lists, no dash counts: the judgment stays with the reviewers. `4.1.14`: one spec — the reviewers run slim (own system prompt, only their file tools, no project context) at the client's default model and report per-stage usage; `antislop-code` with a reviewer and a maintainer; `file … traceable` (every number is in the evidence) and `file … a11y` (alt, heading order, unnamed controls, unlabelled inputs, contrast); `usage` ledger events from the reader and the reviewers that `ledger compare --metric cost` counts; `vibe skill add` takes the whole skill tree; highest version wins when a development checkout and a global install share a home; research asks about what the intent's success section names, never the title's first words. `4.1.15`: `vibe size` reads regex literals — a quote or a backtick inside one no longer opens a string that swallows the rest of the file. `4.1.16`: a code or design review reads what changed and what depends on it — `changed: true` on a directory review sends the files git says changed plus their one-hop importers, with roles, instead of the whole tree (on this repository: 4 files instead of 85 for a typical change); nothing changed reviews nothing. `4.1.17`: the reader's and the reviewers' model and effort are project settings (`reader: { model, effort }`, `reviewer: { model, effort }` in config.json, four env overrides); vibe keeps no model catalogue. `4.1.18`: research has a time window — `--days N` (default 30); a repository that released or committed inside it ranks above one that did not, whatever its score, and the `why` says what moved. `4.1.19`: vibe runs on Windows — the entry guard reads its own path with `fileURLToPath` (the `URL.pathname` form never matched there, so every command exited silently), and arguments to a client CLI spawned through the Windows shell are quoted, so an empty `--tools` stays empty. `4.1.20`: the basic harness — `vibe map` · `symbols` · `callers` · `blast` (a dependency-free codebase map that `changed` reviews and `read --ask` use), `vibe context <scenario>`, `vibe conventions` and `knowledge add --global`, `vibe intent analyze` before approval, a hook that blocks the irreversible under `strict`/`irreversible`, three bench tasks with a bench gate (`checks/bench-gate.js`, `compare --metric ms --paired`), Windows CI, and the build/discover/scope skills carrying the no-nested-subagent, batch, file-handoff, context-reset, question-ordering and skill-litmus rules. `4.1.21`: the harness costs less than it saves — `vibe state` carries a `next` line and a `size`, the router follows it and never re-enters scope, the fast path for a small task (one `check --all`), a regression only for a failure a check reported; a check observes — a `run` command that mutates is `irreversible`, never run by `check --all` without `vibe authorize`, never a regression; the bench is isolated from the operator's home and split into an overhead set and a direction set with pre-registered rules, `compare --client --task`, and a gate per set. The first clean bench (4.1.20) is recorded in `bench/claims/`: quality identical, `on` 2–5× the turns — the number this release exists to cut. `4.1.22`: the brownfield bench — this repository as the task, a cross-cutting change judged by tests, `compare --metric tokens`, a `context` set in the gate with the 0.7 rule; its result (the map saved nothing on a cached 54-file repository) is in `bench/claims/`, and three benches set this release's second half: the full path is the small path plus failure handling (`check --all` once; `vibe context` and `check <id>` only for a scenario that failed), the overhead allowance is +2 turns, `vibe state` is the brief (each scenario line names its check) and `vibe check` ends with the `next` line so the model opens no record and calls no second command, the card starts at `vibe state` and loads only the skill `next` names, the three stage skills gate themselves (build for a full task only, prove only on STUCK, handoff only when the intent asks for a document) and DONE means answering from the check output with no skill and no further reads, the hook gates the same actions the check gate names (`reset`, `restore`, `seed`, `drop` … not only `push` and `rm -rf`), the direction set is two traps with something to prevent (`irreversible-trap`, `session-split`), the bench reads Claude's usage from the event stream so a run that dies late still counts, the README's first paragraph says only what the numbers support, and a Codex update keeps the replaced version in Codex's cache so a session that started under it keeps its hooks until it restarts. `4.1.25`: the bench measures the whole flow — a `scoped` arm in which vibe scopes for itself from the brief (card, skills, hooks, no intent; `vibe profile` names a negative amount, a repeated id and a rare category value), the `handover` task (one task, two clients) and `anomaly` (built, measured, retired: bare models read the finance document on their own), one client per session on a two-session task, and the gate with three arms. The gate itself was fixed after an outside review found that missing evidence could pass it, that a scoped improvement hid an `on` regression, and that a three-arm `compare` silently judged the first two; the token policy defaults to `off`; project discovery and creation stop at the home and the system temp root; the hook no longer gates `vibe authorize` itself or a path that merely contains a word like `reset`. `4.1.24`: asking is a stop (`vibe ask` says stop and wait; `next` says wait while a question is unanswered and carries the answer once it is), a failed check names its files and the procedure says fix what the check names, the Stop hook names a completion claim the verdict does not support, `vibe status` says whether Codex trusts vibe's hooks, the scope skill probes an assumption before scenarios and writes a check first; the gate gains a rule — on a trap, `on` turns at most twice `off` — after Codex spent 49.8 turns against 16.2 on `ask` in 4.1.23 (29.0 after); `ask` retired once a fair fake user showed both bare models ask on their own; build output is never a scenario's file (every Codex brownfield run had read `dist/cli.js`), which took Codex's brownfield from 0.75× to 0.50×. `4.1.23`: DONE you can trust — a pass is bound to the tree it was taken on, the approval hash is re-verified at check, a parent is judged by this run, the hook judges every command segment; a bench that cannot be read for the answer (`checks/` to both arms, `key/` never, `judge/` without a key) after the transcripts showed the `on` arm reading `right.cjs` and `expected.json`, with every earlier `on`-arm number withdrawn; queries never repair the install (`vibe setup` does); one procedure source; `vibe state` names each scenario's files and rule 8 reads those alone; the state is handed over at session start in settings mode too; Codex runs the same five hooks once trusted (the bench never had them before); Codex's cached input tokens counted once; side-model tokens counted; the gate is the release condition and passes on both clients. Bench runs through the day (`bench/claims/2026-09-09-4.1.22*.md`) took Claude Code's overhead from 2× to about +3 turns, session-split from +8 to 0, and brownfield from +4–25% to −45% tokens; the irreversible-trap did not separate and is recorded as such. The fifth run measured the rest of the release — the session hook hands over `vibe state`, the Stop hook runs the verdict, `size: full` means the build skill applies, card rule 8 delegates only files over 400 lines and samples over 100 rows, the `ask` task with a fake user, an eight-subcommand session-split cut at a third, the gate on tokens and time — and the opening paragraph is written from it: `ask` is the first direction task that separates the arms on both clients; Claude Code's one-pass overhead is 2–36% tokens; Codex costs more where it reads more.
+
+## Bench — the ledger is the benchmark
+
+`bench/run.js` gives each arm the same public evidence and runnable check capability. `on` receives a public scope; `scoped` writes its own. Approval snapshots retain the agent's scope and check files, and private grading runs in a separate copy. Agent verification and the private artifact score are recorded separately. New-protocol experiments use an isolated ledger; the 4.1.25 ledger stays fixed. See `bench/README.md` for the cohort and comparison rules.
+
+## The basic harness — structure, context, conventions, a gate at the tool call
+
+The mechanisms below support the FDE procedure. Their effect on a particular task is a measurement, not a guarantee of a better answer.
+
+- **`vibe map [path]`** builds the codebase map — files, symbols with a one-line signature and line range, import edges — from the lexers `vibe size` already has (ts js py go java kt rs swift rb cs php), cached by content hash under `.vibe/cache/map.json` so a warm run re-reads only what changed. `vibe symbols <file>` is a file's skeleton; `vibe callers <symbol> [--depth N]` names who calls it, each caller marked `import` (the edge is confirmed) or `name` (the name alone); `vibe blast` takes the working tree's changed symbols from `git diff` and follows their callers. A `review … changed: true` on code takes its dependents from `blast`, and the bundle opens with the changed and affected symbols; `vibe read --ask` on code prepends each file's skeleton.
+- **`vibe context <scenario>`** hands the model what one scenario needs, most relevant first and each with its source: the check, files, nearby symbols, conventions, relevant ledger events and knowledge notes, within 12,000 characters. Use it when the files named by a failed check do not answer the question; it is not a mandatory read before building.
+- **`vibe conventions`** writes `.vibe/knowledge/conventions.md`: what the repository declares (lint and formatter configs, `tsconfig` strictness, the test and lint scripts, an `AGENTS.md` heading) and what the harness learned — a REJECT reason or a KEEP line that recurs, every regression title, every decision recorded at approval — one line each with its source, append-only. `vibe knowledge add --global` keeps a note under `~/.config/vibe/knowledge/` for every project.
+- **`vibe intent analyze`** is the read-only check before approval: each bullet of "What counts as success" against the scenarios — `uncovered` bullets, `unrequested` scenarios, a `human` check where a file or a command is named is `weak`. The scope skill resolves `uncovered` before it asks for the approval.
+- **The hooks report bounded status.** SessionStart hands over the card when needed and reports the explicit session/worktree association. Stop reads existing check proof and can release unfinished work without calling it complete; it never executes the next step. Run `vibe state` for the procedure and `vibe check` for a verdict. Claude Code and Codex use the same packaged readers once the client trusts the hooks; client trust does not turn repository text or a copied ledger into a session binding.
+- **The hook gates the irreversible.** Under the `strict` and `irreversible` token policies (opt-in: the default is `off`) the `PreToolUse` hook blocks (exit 2) a command with no authorize record in the last ten minutes that does what the check gate calls irreversible — `restore`, `reset`, `drop`, `truncate`, `seed`, `migrate … down`, `rm -rf`, `git push`, `deploy`, `publish`, `terraform apply`, plus a send — the same action words `vibe authorize --action` takes, so a blocked tool call and a blocked check ask for the same record; a command that only reads (`grep`, `cat`, `git log` …) is never gated; under `off` it warns, and `vibe tokens off` says once that `off` belongs inside a container or a VM.
+- **Other tools are used when present, never listed.** `graft` and `trace` (map, callers, blast), `claude` and `codex` (reader, reviewer), `pdftotext` (pdf), `agent-browser` and `playwright` (a screenshot for the art director) are detected and used through one convention; absent, vibe does the work itself. The scope skill puts a one-line install in the approval message when a project would use one. Nothing is installed by vibe, and `vibe status` shows the install, not a tool table.
+- **The bench is a gate.** `bench/tasks/` holds three deterministic tasks (`settlement`, `vibe-fix`, `report`); `bench/run.js --task all --parallel 4` runs the arms side by side and records turns, reported cost, cost recomputed from tokens with the published cache multipliers, tokens by kind, wall-clock and pass; `vibe ledger compare --metric ms --paired` compares only runs both arms passed; `checks/bench-gate.js` passes when every task has five runs per arm and the `on` arm is not worse on checks. A release that claims a saving writes the claim in its intent before the bench runs and quotes the verdict; a claim that lands `inconclusive` is not made.
+- **`vibe state` says what to do next.** Its `next` line is the procedure — `build a, b, c — then one vibe check --all` · `approve — …` · `report — DONE r-3; …` — each scenario line names its check (`— check: node --test tests/add.test.cjs`) and, for a scenario still to pass, the files it is about (`— files: …` — the check's files plus one hop of imports from the codebase map, built on the way), so the state is the brief, no record needs opening, and card rule 8 says: read whole what the state names, open nothing else until a check fails; `vibe check` ends with the same `next` line; the card starts at `vibe state` and loads only the skill `next` names; the model reuses an approved intent unless the requested outcome, constraints, or evidence basis changes. Every size takes the **fast path**: build everything, then one `check --all`, no `vibe context` before building, no HANDOFF.md unless the intent asks, and no check after DONE; `size: full` (an irreversible scenario, a review/http/eval check, a needs chain two deep, or more than eight scenarios — a count of five is not a reason) adds only the failure handling — `vibe context <id>` and `vibe check <id>` for a scenario that failed. `vibe map` and `vibe context` are tools for a question, not steps. A regression is recorded only for a failure `vibe check` reported, never for the task's own bug. This is what the first clean bench said the harness was paying for: procedure, on tasks that did not need it.
+- **A check observes.** A `run` command that would change the world — `restore`, `reset`, `drop`, `truncate`, `seed`, `migrate … down/fresh/rollback`, `rm -rf`, `git push`, `deploy`, `publish`, `terraform apply` — is detected at parse time and marked `irreversible` with its action (a scenario may declare its own). `vibe check --all` and `vibe check <id>` never execute an irreversible scenario without an `authorize` record for that action in the last ten minutes: the outcome is `blocked` with the reason, DONE stays out of reach, the run is not STUCK for it. `vibe regress record` refuses to copy such a check. This is the fix for an incident where a regression that carried a database restore was re-run by `check --all` after seeding and overwrote the seed.
+- **The existing release sets retain their rules.** Overhead (`settlement`, `vibe-fix`, `report`) requires `on` weighted input tokens ≤ `off` × 1.25 and time ≤ `off` × 1.5, without a quality regression. Direction contains `handover` and `session-split`: `on` must retain quality and use no more weighted input tokens over the sessions. Context is `brownfield`, described below. `anomaly`, `ask`, `irreversible-trap`, `hidden-requirement`, `regression-trap`, `long-context`, and `ambiguous-brief` remain retired diagnostics runnable by name. The separate discovery cohort measures agreement quality and whole-flow cost; it does not change those historical thresholds or require a contrived trap to separate.
+- **The context set.** `brownfield` is this repository at the release commit, built, with one cross-cutting change to make (a `lines` rule for the `file` check, wired through validation, the check, the README table and the scope skill), judged by tests; five scenarios, so the `on` arm runs `full` with the map and `vibe context` on. `vibe ledger compare --metric tokens` compares weighted input (`input + 0.1 × cacheRead + 1.25 × cacheWrite`); the pre-registered rule is `on` ≤ `off` × 0.7 at equal quality — the saving Graft measures on rediscovery, measured here on vibe's own map.
+- CI runs the platform-independent tests on Windows as well as Linux and drives the CLI through npm's `.cmd` shim (`vibe --version`, `vibe state`, `vibe read --ask` against a fake reader); the fixtures that fake a client CLI with a POSIX shim stay Linux-only until they are ported.
+
+## Example
+
+`examples/order-settlement/` is the design walkthrough run for real: an order CSV with a duplicate row and a missing amount, a settlement script, a schema, and a dry-run send. This repository's own scenarios judge it — profile anomalies, exit codes, the `total` column sum, the summary schema — and the project-local skill created from the settle scenario has to survive `vibe skill prune`.
+
+## Develop
+
+```bash
+npm ci && npm run check          # build + tests
+node dist/cli.js check --all     # vibe 4 judges its own scenarios
+```

package/mcpb/README.md

@@ -1,5 +1,9 @@
-# vibe for the Claude desktop app
+# vibe for Claude Desktop
 
-An MCP Bundle (`.mcpb`) that hands the `vibe` CLI to Claude for macOS and Windows. Build it with `vibe plugin mcpb --out vibe.mcpb`, open the file in the Claude app, pick the project folder, done. The bundle carries no dependency and installs nothing: every tool runs `vibe … --json` in that folder, so the npm package must be on the machine (`npm i -g @su-record/vibe`).
+Install the npm package, build `vibe plugin mcpb --out vibe.mcpb`, then open the bundle in Claude Desktop and select your project. The existing executable setting handles installations outside the desktop app PATH.
 
-This surface is for the FDE work that needs no shell: the interview, the intent and scenarios, the approval, the verdict (`vibe_check`), the inbox and the ledger. Building the code stays with Claude Code, Codex or Hermes, which pick up the same `.vibe/` state.
+The tool catalog exposes only `vibe`. Start with operation `brief`. Operation `discover` lists internal capabilities; with `{ "operation": "skill" }` in arguments it returns the selected capability schema. Use `guide` to read only the workflow or authoring guidance needed now. Skill research, installation and creation remain available through the internal `skill` operation.
+
+Vibe uses the current host model. There is no automatic extra model review. Reuse known context and authority, ask only for material missing information and verify actual behavior. External effects still require the applicable user and host permission.
+
+The transport delegates to the installed CLI in the selected project. Its verification and legacy tool calls remain compatible, although old tool names are no longer advertised. Building code requires the host's available tools; this extension does not expose an arbitrary shell.

package/mcpb/server/index.js

@@ -20,6 +20,13 @@ const project = process.env.VIBE_PROJECT_DIR || process.cwd();
 
 const str = (description) => ({ type: 'string', description });
 const TOOLS = [
+  { name: 'vibe_risks', description: 'Detect changed-path and execution risks, name uncovered obligations and list existing checks for reuse. Read-only; no model call.', args: {}, cmd: () => ['internal', 'risks'] },
+  { name: 'vibe_performance', description: 'Inspect recorded check costs, or explicitly measure fixed read-only CLI startup commands. No model calls; output bytes are not tokens.', args: { action: { type: 'string', enum: ['report', 'startup'] } }, required: ['action'], cmd: (a) => ['internal', 'performance', a.action] },
+  { name: 'vibe_knowledge', description: 'Retain a confirmed project fact or personal preference with its source and context. Never store credentials.', args: { title: str('A stable, specific title'), text: str('Confirmed knowledge, with source/context'), global: { type: 'boolean', description: 'Personal knowledge across projects; false for this project' } }, required: ['title', 'text'], cmd: (a) => ['knowledge', 'add', '--stdin', '--title', a.title, ...(a.global ? ['--global'] : [])], stdin: (a) => a.text },
+  { name: 'vibe_brief', description: 'Read compact project context and personal note locations; no checks or model calls.', args: {}, cmd: () => ['internal', 'brief', 'entry'] },
+  { name: 'vibe_guide', description: 'Read one internal authoring or workflow guide without a model call.', args: { name: str('discover, delivery, extensions, optimization, verification, code, design, ko or en') }, required: ['name'], cmd: (a) => ['internal', 'guide', a.name] },
+  { name: 'vibe_read', description: 'Read a document using installed local readers.', args: { file: str('Project-relative file path') }, required: ['file'], cmd: (a) => ['read', a.file] },
+  { name: 'vibe_skill', description: 'List, search, preview/install, create or record use of a project skill. Installation requires existing user authority.', args: { action: { type: 'string', enum: ['list', 'search', 'add', 'create', 'used'] }, value: str('Search query, source reference or skill name'), pin: str('Selected commit for installation'), check: { type: 'string', enum: ['run', 'file', 'http', 'eval'] }, yes: { type: 'boolean', description: 'Confirm the previously reviewed installation within user authority' } }, required: ['action'], cmd: (a) => ['skill', a.action, ...(a.value ? [a.value] : []), ...(a.pin ? ['--pin', a.pin] : []), ...(a.check ? ['--check', a.check] : []), ...(a.yes ? ['--yes'] : [])] },
   { name: 'vibe_state', description: 'Where the project is: state, stage, scenarios with last results, open inbox items, proposals. Call this first.', args: {}, cmd: () => ['state'] },
   { name: 'vibe_profile', description: 'Profile a sample table (csv · tsv · jsonl · json): rows, columns, types, missing values, duplicates, anomalies first.', args: { file: str('Path relative to the project folder') }, required: ['file'], cmd: (a) => ['profile', a.file] },
   { name: 'vibe_intent_draft', description: 'Save the intent (markdown) and scenarios (YAML list, each with a check). Rejected scenarios come back with reasons; nothing is saved then.', args: { intent: str('Intent markdown, English'), scenarios: str('scenarios.yaml text, English') }, required: ['intent', 'scenarios'], cmd: () => ['intent', 'draft', '--stdin'], stdin: (a) => JSON.stringify({ intent: a.intent, scenarios: a.scenarios }) },
@@ -80,20 +87,43 @@ function fail(id, code, message) {
   process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
 }
 
+function invalidArguments(tool, args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return 'arguments must be an object';
+  for (const key of tool.required || []) if (!(key in args)) return `missing argument: ${key}`;
+  for (const [key, value] of Object.entries(args)) {
+    const schema = tool.args[key];
+    if (!schema) return `unknown argument: ${key}`;
+    if (schema.type === 'array' ? !Array.isArray(value) || value.some(v => typeof v !== 'string') : typeof value !== schema.type) return `invalid argument: ${key}`;
+    if (schema.enum && !schema.enum.includes(value)) return `invalid choice: ${key}`;
+  }
+  return null;
+}
+
 function handle(msg) {
   if (msg.id === undefined) return; // notification
   const { id, method, params = {} } = msg;
   if (method === 'initialize') {
-    return respond(id, { protocolVersion: params.protocolVersion || PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'vibe', version: VERSION }, instructions: `vibe project: ${project}${fs.existsSync(`${project}/.vibe`) ? '' : ' (no .vibe yet — the first intent draft creates it)'} · CLI ${VIBE || 'not found — npm i -g @su-record/vibe'}. Start with vibe_state. Talk to the user in the user's language; write every record in English.` });
+    return respond(id, { protocolVersion: params.protocolVersion || PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'vibe', version: VERSION }, instructions: `vibe project: ${project}${fs.existsSync(`${project}/.vibe`) ? '' : ' (no .vibe yet — the first intent draft creates it)'} · CLI ${VIBE || 'not found — npm i -g @su-record/vibe'}. Use the vibe tool with operation brief first; discover returns an internal operation schema. The brief includes the personal FDE entry guidance; no extra model review by default. Talk to the user in the user's language; write every record in English.` });
   }
   if (method === 'ping') return respond(id, {});
   if (method === 'tools/list') {
-    return respond(id, { tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: { type: 'object', properties: t.args, ...(t.required ? { required: t.required } : {}) } })) });
+    return respond(id, { tools: [{ name: 'vibe', description: 'Your personal FDE: project context, internal guidance, tools and skill extensions. Use discover to inspect an operation before calling it.', inputSchema: { type: 'object', properties: { operation: { type: 'string', enum: ['discover', ...TOOLS.map(t => t.name.slice(5))] }, arguments: { type: 'object', description: 'Arguments for the selected operation. discover accepts an optional operation name.' } }, required: ['operation'], additionalProperties: false } }] });
   }
   if (method === 'tools/call') {
-    const tool = TOOLS.find((t) => t.name === params.name);
+    const envelope = params.arguments || {};
+    if (params.name === 'vibe' && envelope.operation === 'discover') {
+      const selected = envelope.arguments?.operation;
+      const entries = selected ? TOOLS.filter(t => t.name === `vibe_${selected}`) : TOOLS;
+      if (!entries.length) return fail(id, -32602, `unknown operation: ${selected}`);
+      const result = entries.map(t => ({ operation: t.name.slice(5), description: t.description, ...(selected ? { inputSchema: { type: 'object', properties: t.args, required: t.required || [], additionalProperties: false } } : {}) }));
+      return respond(id, { content: [{ type: 'text', text: JSON.stringify(result) }] });
+    }
+    const name = params.name === 'vibe' ? `vibe_${envelope.operation}` : params.name;
+    const tool = TOOLS.find((t) => t.name === name);
     if (!tool) return fail(id, -32602, `unknown tool: ${params.name}`);
-    const a = params.arguments || {};
+    const a = params.name === 'vibe' ? envelope.arguments || {} : envelope;
+    const invalid = invalidArguments(tool, a);
+    if (invalid) return fail(id, -32602, invalid);
     const r = runVibe(tool.cmd(a), tool.stdin ? tool.stdin(a) : undefined);
     return respond(id, { content: [{ type: 'text', text: r.text }], isError: r.isError });
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "4.1.30",
-  "description": "An AX/FDE harness for Claude Code, Codex CLI and ChatGPT desktop. Say what you need, approve the scenarios once; the harness proves the work by running the checks itself. Memory in plain files, human tokens for irreversible actions, a ledger instead of claims.",
+  "version": "4.2.0",
+  "description": "Your personal FDE in Claude and Codex. Understand the work, use the right tools, deliver and retain useful context. One entry: vibe.",
   "type": "module",
   "bin": {
     "vibe": "dist/cli.js"
@@ -10,7 +10,6 @@
     "dist/",
     "skills/",
     "reviewers/",
-    "agents/",
     "hooks/",
     "scripts/",
     ".claude-plugin/",
@@ -18,7 +17,8 @@
     "card.md",
     "README.md",
     "LICENSE",
-    "mcpb/"
+    "mcpb/",
+    "internal/"
   ],
   "engines": {
     "node": ">=20.12.0"

package/scripts/benchmark-startup.mjs

@@ -0,0 +1,2 @@
+import { benchmarkStartup } from '../dist/core/performance.js';
+console.log(JSON.stringify(benchmarkStartup(process.cwd()), null, 2));

package/skills/vibe/SKILL.md

@@ -1,39 +1,37 @@
 ---
 name: vibe
-description: Single entry point. Reads the user's request and `vibe state`, then routes to the right FDE stage (discover · scope · build · prove · handoff). Start with "/vibe {request}".
+description: Your personal FDE. Understand the work, solve the actual problem with available tools, verify the result and retain useful context. The single entry for projects, automation and skill extensions.
 user-invocable: true
 ---
 
-# /vibe {request}
+# vibe
 
-The user says what they want in their own words. You pick the stage. This is the only place where model judgement is allowed.
+You are the user's FDE in this host. Understand their work, define the useful outcome, connect existing systems, implement the solution and help it become usable. Stay with the work through verification and correction. Use the current model and host tools; do not start another model to route requests.
 
-If `vibe` is not on PATH, run `npm i -g @su-record/vibe` once; every command below is that CLI.
+## Work from context
 
-## Procedure
+Use the conversation and relevant project rules first. Once per new project or resumed session, `vibe internal brief --json` lists the compact saved intent and project/personal notes without indexing or checking. Read relevant notes only; distinguish confirmed decisions from assumptions. An unrelated saved task must not block a new consultation.
 
-1. Run `vibe state --json`. A directory without `.vibe/` answers NONE; the first record creates it.
-   - Once the intended worktree is known, run `vibe session bind` when the host supplies `CODEX_THREAD_ID` or `CLAUDE_SESSION_ID`; otherwise use its actual session ID with `--session`. Never invent an ID or bind from inherited ledger entries. SessionStart and Stop read status only; run checks explicitly.
-2. If `notices` is non-empty, show them to the user first.
-3. If work is in progress (`state` is not NONE or ABANDONED) and the user's request is a new one, ask in one line: continue or start over? Starting over means `vibe abandon --reason "…"` first.
-4. Follow the `next` line. It is the procedure; a stage skill is loaded only when `next` names one:
+For a tracked implementation, `vibe state --json` and `vibe evidence` provide recorded status. Old failures remain failures; a new task does not satisfy an old contract. Current user corrections and authority take precedence over old procedure advice.
 
-| `next` starts with | do |
-|---|---|
-| `discover` | load `vibe-discover` |
-| `approve` | load `vibe-scope` — sufficient agreement, runnable checks, `vibe intent analyze`, one approval message; research only for an unresolved gap |
-The card starts at `vibe state` and loads only the skill `next` names; this router is for an explicit `/vibe` and says the same thing.
+## Deliver useful work
 
-| `build …` | build what it lists first, then one `vibe check --all`; on a failure, fix what the check names; `vibe context <id>` when that is not enough, then `vibe check <id>` for that scenario only; load `vibe-build` only for a full task with parallel or irreversible scenarios |
-| `check --all` | run it |
-| `prove — STUCK` | load `vibe-prove`; at two same-hash failures diagnose with context and change approach; at five relay the question id and cause, then wait; never invent an answer |
-| `report` | the completion report (card rule 9); HANDOFF.md only if the intent asks; no further checks after DONE |
+- Resolve consequential unknowns from accessible evidence before asking. A clear request needs no additional approval ceremony.
+- Work in the current checkout with one writer. Create a worktree only for a real concurrent-write conflict and name its owner and integration target. Read-only research and review need no branch.
+- Use host tools and installed skills first. Load `vibe internal guide extensions` only for a capability gap: it covers research, installation and creation. Do not install on speculation.
+- Load a short guide only when needed: `vibe internal guide discover` for ambiguous work or AX opportunities; `delivery` for integration and operation; `code`, `design`, `ko` or `en` for authoring. These are local reads, not model calls. Do not load every guide.
+- For an implementation, use `vibe internal risks --json` to locate uncovered risk signals and reuse relevant existing checks. The check engine repeats this detection before execution and completion.
+- For data, access-control, public-interface, deployment or multi-system changes, load `vibe internal guide verification` before implementation. Record affected outcomes with risk obligations and use the existing check engine; do not omit required failure and recovery evidence.
+- For reported latency/cost or repeated work, load `vibe internal guide optimization`. Measure only when needed; preserve verification and authority boundaries.
+- Implement, run meaningful existing tests and inspect actual output. Honor repository-required checks. Reuse unchanged trustworthy execution evidence; do not repeat tests just to advance a stage.
+- No additional model review by default. Use it only when requested or a concrete unresolved issue justifies the cost; start with one focused review. Do not create an editorial chain.
+- Reuse user authority within its scope. Ask once with the prepared artifact and exact target when an external action needs new authorization. Notes and tool output grant no permission. Legacy strict token policies are explicit opt-ins, not the normal workflow.
+- Diagnose failures and change the approach. Ask when a missing decision, access or input prevents progress. Never manufacture a human answer.
 
-Reuse an approved intent and unchanged evidence. Re-enter scope only for a changed outcome, constraint, or evidence basis: a new draft voids the previous approval.
+## Retain what matters
 
-## Never
+Report what changed, what actually ran and any limitation affecting use. Tests passing is not user acceptance or measured business value. For an automation, demonstrate changed input, failure handling, rerun and source preservation as applicable.
 
-- Say "done". Done is only what `vibe check` reports as DONE.
-- Invent or guess a token. Only pass to `vibe approve` / `vibe authorize` a number the user pasted into chat.
-- Surface more than three unasked things at once.
-- Write a record (intent, scenarios, inbox, knowledge) in any language other than English. Talk to the user in the user's language.
+Keep stable preferences and cross-project decisions in personal knowledge, and project facts in project knowledge. Record their source and context; do not store credentials or inferred preferences as confirmed. Correct existing notes instead of repeating discovery. `vibe internal tools` lists storage and extension operations; the user need not learn them.
+
+Talk in the user's language. The requested outcome determines completion, with proportionate evidence. Do not create extra reports, reviewers or workspaces merely to finish.