@josfox/jos 4.0.8 → 5.0.0

package/README.md

@@ -1,186 +1,334 @@
-<div align="center">
+# @josfox/jos
+
+A `.jos` is an intention you declare: **what** to do, **when it is done** (success criteria) and **what to avoid**
+(guardrails). It is **validated without running anything**, and **run with guarantees**: limits enforced while it
+runs, every criterion checked, a receipt per step and a hash-chained ledger per run. It has a **content identity**
+(`art_`, the hash of the document; JOSID names such as `ent_`). It is **fractal**: an atom, a flow of atoms and a
+folder with a `.jos/` directory have the same shape. And it is **reusable**: `use` another document by id,
+instantiate templates, pin what you depend on by digest. Two reference kernels, JavaScript and Python, give
+identical results on every conformance vector.
+
+`jos` is the command line for this. It hands every document to the reference kernel `jos-core` and shows what the
+kernel decided; it has no execution logic of its own.
+
+Version 5.0.0 · kernel `@josfox/jos-core` 2.0.0 (its only dependency) · Node.js 18 or later ·
+`jos` and `jos-core` open no network connection (a step you write can; see [Security](#security)) ·
+Apache-2.0.
+
+## Install
 
 ```
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⡀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⠙⠻⢶⣄⡀⠀⠀⠀⢀⣤⠶⠛⠛⡇⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⣇⠀⠀⣙⣿⣦⣤⣴⣿⣁⠀⠀⣸⠇⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⣡⣾⣿⣿⣿⣿⣿⣿⣿⣷⣌⠋⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣴⣿⣷⣄⡈⢻⣿⡟⢁⣠⣾⣿⣦⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⣿⣿⣿⣿⠘⣿⠃⣿⣿⣿⣿⡏⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠀⠈⠛⣰⠿⣆⠛⠁⠀⡀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣼⣿⣦⠀⠘⠛⠋⠀⣴⣿⠁⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣶⣾⣿⣿⣿⣿⡇⠀⠀⠀⢸⣿⣏⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⣠⣶⣿⣿⣿⣿⣿⣿⣿⣿⠿⠿⠀⠀⠀⠾⢿⣿⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⣠⣿⣿⣿⣿⣿⣿⡿⠟⠋⣁⣠⣤⣤⡶⠶⠶⣤⣄⠈⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⢰⣿⣿⣮⣉⣉⣉⣤⣴⣶⣿⣿⣋⡥⠄⠀⠀⠀⠀⠉⢻⣄⠀⠀⠀⠀⠀
-⠀⠀⠀⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣟⣋⣁⣤⣀⣀⣤⣤⣤⣤⣄⣿⡄⠀⠀⠀⠀
-⠀⠀⠀⠀⠙⠿⣿⣿⣿⣿⣿⣿⣿⡿⠿⠛⠋⠉⠁⠀⠀⠀⠀⠈⠛⠃⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+npm install -g @josfox/jos
+jos --version          # jos 5.0.0 and the jos-core it found
 ```
 
-# @josfox/jos
-
-**Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)**
+`@josfox/jos` needs `@josfox/jos-core` from the registry: both packages have to be published for this to install.
+`jos` finds the kernel as the installed `@josfox/jos-core`, else as `kernel/js/jos-core.js` of a checkout of the
+repository; without one, `run`, `validate` and the other kernel commands exit 5 and say so.
 
-**Stoic Kernel for AI Agent Orchestration**
+## Start
 
-[![npm](https://img.shields.io/badge/npm-@josfox/jos-00ffff?style=for-the-badge)](https://www.npmjs.com/package/@josfox/jos)
-[![Version](https://img.shields.io/badge/version-4.0.4-success?style=for-the-badge)](#)
-[![Dependencies](https://img.shields.io/badge/dependencies-0-blue?style=for-the-badge)](#zero-dependencies)
-[![License](https://img.shields.io/badge/license-MIT-purple?style=for-the-badge)](LICENSE)
+```
+jos                    # what jos does, and the .jos documents in this folder (read only)
+jos start              # writes ./jos-start: four examples that need no keys and no network
+cd jos-start && jos run hello.jos
+```
 
-*Zero Dependencies • Offline First • Open Standard*
+`jos` alone lists the `.jos` / `.jos.json` documents of the current folder and one folder down, and the folders
+with a `.jos/manifest.jos`, each with its `jos validate` and `jos run` command. It runs nothing, writes nothing, and
+never scans your home folder. `jos start [dir]` writes `hello.jos` (an atom), `flow.jos` (a flow with a human gate),
+`sealed/` (a folder sealed by its hash) and `limits.jos` (guardrails stopping two steps), plus a README with the
+commands in order and what each prints; it never overwrites a file.
 
-</div>
+`jos run` shows the intention first, then the verdict of each criterion, then the outcome:
 
----
+```
+$ jos run hello.jos
 
-## Overview
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JOS RUN // jos-core 2.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**@josfox/jos** is the reference implementation of the **.jos Open Standard** — a portable artifact format for AI agent orchestration.
+  File: hello.jos
 
-| Feature | Description |
-|---------|-------------|
-| **Stoic Kernel** | 77-line minimal kernel with zero dependencies |
-| **Plugin Architecture** | Commands live in `~/.jos/commands/` or bundled |
-| **Offline First** | Works without network, like Git |
-| **A2A Compatible** | Designed for Agent-to-Agent interoperability |
+Intention: Print a greeting and exit cleanly
+Done when:
+  • exit 0
+  • stdout contains "hello"
+Avoid: "rm -rf", "curl", "wget"
+Limit: 10 s, 65536 output bytes per stream, 0 retries
 
----
+  ID: art_803576e37d948d3036d1c84febcfc229f6fabc78ffebdbd1a427e9ca7d342575
+  Input version: 2.0.0
+  Capability: cap_… (local-trusted)
+  Ledger: ~/.jos/runs/run_…/ledger.jsonl
 
-## Quick Start
+hello, .jos
 
-```bash
-# Run with npx (no install required)
-npx josfox serve
+Verdict:
+  [1] hello ✓ code 0
+    ✓ exit: exit 0 (want 0)
+    ✓ stdout_contains: found
 
-# Or install globally
-npm install -g @josfox/jos
-jos serve
+✓ Intention met (code 0, run_…)
 ```
 
----
+When it is not met, the last line says why: `✖ Intention NOT met (code 1: not done)`, with the reason below it.
+`--json` prints the kernel's result object instead, unchanged.
+
+## What it can do
+
+Each capability, the command, and the example of the tour (`examples/`, see [its README](examples/README.md)) that
+shows it.
+
+| Capability | Command | Tour |
+|---|---|---|
+| Declare an intention: objective, success criteria, `avoid`, `limit` | `jos init <name>`, `jos start`, `jos validate <file> --strict` | `01-hello.jos` |
+| Check it without running anything: JSON, schema, normalization, `art_` | `jos validate <file>` | any |
+| Every criterion evaluated and reported (`exit`, `stdout_contains`, `stdout_matches`, `stderr_empty`, files, hashes, `all` / `any` / `not`; text criteria are recorded, not evaluated) | `jos run <file>` | `02-criteria.jos` |
+| Guardrails before and during the run: an `avoid` match never starts (3), time (124) and output (137) limits stop the process | `jos run limits.jos` (from `jos start`) | `limits.jos` |
+| Flows: sequences and DAGs (`needs`), automatic and human gates, data between steps | `jos run <flow> --approve <step>`, `--flow <name>`, `--input <json>` | `03-flow-gate.jos` |
+| Reuse: `use` by id and version range, templates with typed slots, a dependency pinned by digest | `jos run <flow> --library <dir>`, `jos run <template> --with <json>` | `04-use-template/` |
+| A folder is a document; sealed by its directory hash, refused when anything in `.jos/` changes (3) | `jos run <folder>` | `05-sealed/` |
+| Refuse what it cannot honor, before the first step (5): unmet `requires[]`, `security.tier: sandbox` | `jos run <file>` | `06-requires.jos`, `07-sandbox.jos` |
+| Identity: `art_` of the content, `ent_` of the name, the hash of a folder | `jos ids <file>…` | `08-ids-ledger-meter.md` |
+| Receipts and a hash-chained ledger of every run; verify it; meter it (tokens and cost when an engine reports them) | `jos runs`, `jos ledger verify <run>`, `jos meter <run>` | `08-ids-ledger-meter.md` |
+| Credentials for a step without putting them in the document, the command line or the output | `jos secrets exec --only NAME -- jos run <file>` | `11-openai.jos`, `12-gemini.jos`, `13-anthropic.jos` |
+| A local model as a shell step | `jos run 10-ollama.jos` | `10-ollama.jos` |
+| A read-only page of your runs, on 127.0.0.1 only | `jos run 14-serve.jos` | `14-serve.jos` |
+| Give an MCP client (Claude Code, Claude Desktop, Cursor) read-only access to a project folder | `jos serve --mcp` | see below |
+| Reseal a 4.1.0 document (0.0.7 with `security.integrity_ref`) as 2.0, only if it verifies | `jos migrate <file>` | see Changes since 4.1.0 |
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `jos serve` | Start development server with dashboard |
-| `jos run <file>` | Execute .jos artifacts |
-| `jos get <package>` | Fetch packages from repositories |
-| `jos secrets` | Manage encrypted credentials (AES-256) |
-| `jos repo` | Manage package repositories |
-
-```bash
-# Examples
-jos serve --port 8080
-jos run artifact.jos --dry-run
-jos get myrepo:package-name
-jos secrets set API_KEY sk-abc123
-```
-
----
+| Command | What it does |
+|---|---|
+| `jos` | Overview and read-only discovery of this folder (see Start). Exit 0. |
+| `jos start [dir]` | Writes the four start examples and their README into `dir` (default `jos-start`), each validated by jos-core first; refuses (1) if any of them exists. |
+| `jos run <file \| folder> [--json] [--dry-run] [--flow <name>] [--library <dir>] [--approve <step>]… [--input <json>] [--with <json>]` | Runs the document with jos-core, in the document's own folder (never the shell's current directory). A folder `D` (or `D/.jos`) with `D/.jos/manifest.jos` runs that manifest in `D` when it is of kind `directory` (a 1.0.0 flow with `meta.labels.dotjos` too); any other manifest is 2 before any step, as `jos validate D` says; a sealed folder is verified by its hash first. The options are passed to jos-core as they are: `--flow` picks a flow (default `main`, or the only one), `--library` is one more place for `use`, `--approve` approves a human gate (repeatable; `outer/step` for a nested one, `step#2` for a second occurrence), `--input` is the run's input, `--with` the slots of a template run directly. `--dry-run` checks everything and prints the plan without launching. `--` ends the options. |
+| `jos validate <file> [--json] [--strict]` | Validates and normalizes; prints the `art_`, the input version, the intention and `Inferred:`, what jos-core applies that the document does not write (each JSON Pointer with its value and source: a SPEC section or a jos-core default), with `⚠ … not declared` for a missing objective, success criteria or guardrails. `--json` carries the same `inferred` section as `jos-core validate --json`. `--strict` also exits 2 when the objective, the success criteria or the guardrails are not written in the document. A folder `D` (or `D/.jos`) is validated as a directory by jos-core: a manifest that is not of kind `directory` is 2, the answer of `jos run D`; `--strict` applies to the manifest. Never runs anything. |
+| `jos migrate <file> [--out <file> \| --in-place] [--force]` | For a 0.0.7 document sealed by `security.integrity_ref` (what `jos init` of 4.1.0 wrote): verifies the manifest exactly as `run` does (a mismatch is 3 and nothing is written), then writes `<name>.v2.jos` (or `--out`): jos-core's 2.0 normalization with `integrity_ref` removed, `security.permissions` moved to `security.x-legacy-permissions` (4.1.0 never applied it; 2.0 would apply an empty list as "no shell") and `integrity.hash` of the result. The result must validate and plan the same steps as the original before it is written; it prints what changed. Never overwrites the input without `--in-place`, nor an existing output without `--force`. A 2.0 document: "already 2.0" (0); a 1.1.0 or 1.0.0 document, or a 0.0.7 one without `integrity_ref`: 64 (they run as they are). |
+| `jos ids <file \| folder>… [--json]` | `art_`, `ent_` (`uuid5("<kind>:<id>")`) and, for a folder, its directory hash and whether it matches its seal. Exit 2 if one is invalid. |
+| `jos runs [--limit <n>] [--json]` | The runs in `~/.jos/runs/`, newest first: id, start, code, document, `art_`, metered cost. Each ledger is verified; one that does not verify is flagged. Never creates `~/.jos`. |
+| `jos ledger verify <run_id \| ledger.jsonl \| run folder> [--json]` | Recomputes every entry hash of a run's ledger and checks the chain and the end entry. Exit 0 verifies, 1 does not, 2 not found. |
+| `jos meter <run_id \| ledger.jsonl \| run folder> [--json]` | Steps, engines, attempts, time, tokens, cost, approvals, from the ledger, only when it verifies; a meter no engine reported is "not reported", never 0. |
+| `jos init <name> [--force]` | Writes `<name>.jos`, a 2.0 atom validated by jos-core. A name ending in `.jos` / `.jos.json` gets no second extension; a directory part is kept (it must exist). |
+| `jos verify` | Self-check: runs the embedded `examples/hello.jos` in a new temporary folder (also its HOME) and removes it. |
+| `jos version`, `jos --version` | Host version; kernel version and where it was found. |
+| `jos secrets set\|get\|list\|delete\|exec\|migrate\|fix-perms` | Local credentials in `~/.jos/secrets/`. Values never go on a command line or to stdout: `set NAME --stdin`, `get NAME` shows a keyed fingerprint, `exec --only A,B -- <cmd>` adds only those values to the child's environment. Details: [SECURITY-SECRETS.md](SECURITY-SECRETS.md). |
+| `jos serve --mcp [--root <dir>] [--allow-write] [--allow-shell]` | MCP server over stdio, read-only by default. Details below and in [SECURITY-MCP.md](SECURITY-MCP.md). |
+
+Every command has `--help`. `jos <file>` with a `.jos` file or a `.jos/` folder is not a command: it exits 1 and
+names `jos run <file>` and `jos validate <file>`; nothing runs by itself. Every message for a person has one format
+(`✓` / `✖` / `⚠`, color only on a terminal and without `NO_COLOR`, errors on stderr; rules and their test:
+[STYLE.md](STYLE.md)); `--json` output is plain JSON.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done |
+| 1 | not done (a criterion failed, a human gate is waiting) |
+| 2 | invalid document |
+| 3 | blocked (`avoid` matched, the Capability denied it, or an integrity hash or a 0.0.7 `integrity_ref` manifest does not match) |
+| 4 | budget exceeded before start |
+| 5 | unexecutable (no kernel, unresolved `use`, unmet `requires[]`, no engine for it, `sandbox` or `privileged` that this kernel cannot honor) |
+| 124 | time limit |
+| 137 | output limit or killed |
+| 64 | usage error |
+| 70 | internal error of the host (never a document outcome); the stack trace only with `JOS_DEBUG=1` |
+
+### Files written
+
+`jos` writes only what a command is for: `init` its file, `start` its folder, `migrate` its output file, `secrets` `~/.jos/secrets/`,
+`serve --mcp --allow-write` what the client asks inside its root. jos-core writes a ledger for every `run` (not
+`--dry-run`): `<run_id>/ledger.jsonl` in `.jos/replays/` of the nearest folder above the document that has a
+`.jos/manifest.jos`, otherwise in `~/.jos/runs/`. The ledger holds the Capability, the receipts and hashes; a step's
+output appears in it only as a hash. `jos`, `validate`, `ids`, `runs`, `ledger`, `meter`, `verify`, `version` and
+`run --dry-run` leave nothing on disk.
+
+## Security
+
+What `jos` and jos-core guarantee, exactly:
+
+- **Validating never executes.** `validate`, `ids`, `jos` alone and `run --dry-run` read and check; no step starts.
+- **`avoid` is checked before launch.** A pattern that matches the engine input (the argv or command line) blocks
+  the step before its process exists: code 3. **`limit` is enforced while it runs**: past `seconds` the process
+  group is killed (124); past `output_bytes` on a stream it is killed (137); `retries` bounds the correction loop.
+- **Hashes before running.** `integrity.hash` of a document, of a document reached by `use`, of a pinned
+  `requires[].digest` and of a sealed folder is recomputed (SHA-256 over the canonical JSON, RFC 8785) before
+  anything starts; a mismatch is code 3 (5 for an unmet digest). Signatures are not verified yet:
+  `security.tier: privileged` is refused (5).
+- **A 0.0.7 document sealed by `security.integrity_ref`** (4.1.0's separate manifest) is verified against the octets
+  `jos run` read, before anything starts, `--dry-run` included: the manifest path must be relative and stay inside the
+  document's folder (no absolute path, URL or symbolic link), and its `artifact_sha256` must match the file (as it
+  is, or with LF / CRLF line endings); otherwise code 3 with a reason that begins `integrity_ref:`. A `type: jos` child
+  sealed this way is verified before the parent's first step. Like `integrity.hash`, it detects change; it does not
+  authenticate anyone (whoever can edit the folder can rewrite both files). `jos validate` does not read the manifest.
+- **It refuses what it cannot honor**, before the first step: an unmet `requires[]` entry, `security.tier: sandbox`
+  (this kernel cannot confine a process), an engine it does not have, a criterion it cannot evaluate: code 5.
+- **A step sees only the environment it declares**: the names in `execution.env` (default `PATH`).
+- **Every run is recorded**: a receipt per step and a hash-chained ledger that `jos ledger verify` recomputes.
+- **`jos secrets`**: AES-256-GCM per entry with the name as associated data, a master key at mode 0600 in a 0700
+  folder, values never on a command line or stdout, `exec --only` for the one run that needs them.
+- **`jos serve --mcp` is read-only by default**; `~/.jos/secrets` is denied to its file tools; writing and running
+  programs are separate opt-ins (`--allow-shell` is local code execution as you).
+- **No network from `jos` or jos-core**, no telemetry. A step is a program you chose: it can use the network (the
+  provider examples call `curl`; `14-serve.jos` listens on 127.0.0.1) and it runs with your user's privileges; the
+  `shell` engine is not a sandbox, and its receipts say `isolation: "none"`.
+
+`jos secrets` is a local, best-effort vault for a single user, not a hardened secrets manager. Provided "AS IS"
+without warranty (Apache-2.0 §7–8); use at your own risk.
+
+### Disclaimer
+
+Figures jos prints (cost, tokens, time) are estimates; vendor invoices are authoritative. Any AI output it relays can
+be wrong: use the receipts and the ledger as evidence for your own decision. Provided "AS IS", without warranty
+(Apache-2.0). The same text is the last line of `jos --help`.
+
+## Not yet
+
+| What | Today | Planned |
+|---|---|---|
+| `engine: llm` and `judge` / `json_schema` criteria | valid documents, refused at run: code 5 | 2.1 |
+| Signatures (`integrity.signature`, `security.tier: privileged`) | code 5 | 2.1 |
+| Cache, crystals (`kind: crystal`), store | crystals validate; running one is code 5 | 2.1 |
+| `jos get` (fetch a document from a registry) | frozen: exit 1 | 2.1, with signatures |
+| Learning (`adaptive_ai` of 0.0.7 is kept as `x-legacy-adaptive_ai` and not read) | none | 2.1 |
+| `jos serve` as an HTTP explorer | off: exit 2 (`jos serve --mcp` works) | F3 |
+| `jos llm`, `jos prompts`, `jos repo`, `jos add` | frozen: exit 1, `jos <name>` says why | not scheduled |
+| `josctl`, `@josfox/jos-cli` | separate older packages, not part of 5.0 | future |
+
+## Compatibility
+
+| Input | What happens |
+|---|---|
+| `.jos` 2.0.0 | the format of this release |
+| 1.1.0 short form (`{ "use": … }`) | normalized to a 2.0 atom with a `main` flow |
+| 1.0.0 | normalized in memory to 2.0 (the file is not rewritten). Since jos-core 2.0.0-rc.8: `execution.flow` (`[{ invoke }]`) runs as the `main` flow, `execution.budget` bounds flows too, a gate keyed `after-<step>` is the gate of that step, and a 1.0.x document without `integrity.signature` may carry the 1.0.0 seal (hash computed with only the hash field empty) |
+| 0.0.7 with text steps | normalized to a 2.0 flow and runs; `success_criteria` text is recorded, not evaluated |
+| 0.0.7 sealed by `security.integrity_ref` | runs only if its manifest verifies (3 otherwise, also with `--dry-run`); `jos migrate` reseals it as a 2.0 document with `integrity.hash` |
+| 0.0.7 written by `jos init` of 4.1.0 (with `orchestration.state`) | valid and runs since jos-core 2.0.0-rc.8: `orchestration.state` is kept as `orchestration.x-legacy-state` (never dropped), the `integrity_ref` manifest is verified first, `jos migrate` writes the 2.0 document (`read-0.0.7-init` in [PROMISES.md](PROMISES.md)) |
+| 0.0.7 with object steps | invalid (2) |
+| 0.0.7 with `type: prompt` steps (or any `type` other than `shell`, `jos`, `http`) | invalid (2) since jos-core 2.0.0-rc.8 (rc.3 to rc.7: valid and unexecutable, 5) |
+| A step definition with a member the schema does not give it (`on_error` or `env` beside `run`, a `with` that is not an object) | invalid (2) since jos-core 2.0.0-rc.8: write `on_error` and `env` in the definition's `execution` |
+| Integer values outside ±2^53 and below 10^21 however written (`9007199254740993`, `1e20`), decimals an IEEE 754 double does not keep exactly (`1.00000000000000001`, `1e-400`) | invalid (2) since jos-core 2.0.0-rc.8 (they were rounded, so two documents could share an `art_`, and `1e20` has no valid canonical form) |
+
+`jos` reads 4.1.0's 13-key Minimal Valid Artifact unchanged: `jos validate` passes and `jos run` prints `Hello!`.
+
+Every promise in one table, with what 4.1.0 did, what 5.0 does, what is planned and the command that proves it, known
+gaps included: [PROMISES.md](PROMISES.md) (generated from `promises.json`; `npm test` runs every gate).
+
+## Changes since 4.1.0
+
+- `run` and `validate` hand the document to jos-core. 4.1.0's own runner is gone: `execSync` of each step, the
+  13-key presence check (only `jos` and `meta` are required now), `--insecure` and `--verbose` (both exit 64).
+- `--flow <name>` exists again, with jos-core's meaning: it picks a flow of the document. A document with several
+  flows and none named `main` needs it.
+- 0.0.7 flows with text steps run; object steps are invalid (2); `type: prompt` steps are invalid (2).
+- Documents are validated with the published `schema/jos.schema.json` (jos-core 2.0.0-rc.8): integer values outside ±2^53
+  and below 10^21, and numbers not exactly representable, are invalid (2), as are members a definition does not have.
+- `validate` shows what jos-core infers and what the document does not declare; `--strict` refuses (2) a document
+  without its own objective, success criteria and guardrails.
+- `security.integrity_ref` is verified again (as in 4.1.0, stricter on paths), and `jos migrate` reseals it as
+  `integrity.hash`. A mismatch is code 3 (4.1.0: 1), `--dry-run` included; there is no bypass (`--insecure` is 64).
+- Exit codes 0–5, 64, 70, 124, 137 (4.1.0 used 0 and 1).
+- No more `~/.jos/runs/*/events.jsonl`: receipts in the result and jos-core's ledger replace it. `~/.jos/commands/`
+  overrides are not loaded; the command table is fixed.
+- `init` writes a 2.0 atom (no `.sig.json`); `add`, `llm`, `prompts`, `get` and `repo` are frozen; `jos serve`
+  without `--mcp` is off.
+- License Apache-2.0 (4.x: MIT). The `josfox` alias binary is no longer installed.
+
+Full list: [CHANGELOG.md](CHANGELOG.md).
+
+## Use with an MCP client
+
+`jos serve --mcp` is an MCP server over stdio: the client starts the command and talks JSON-RPC 2.0 on its stdin and
+stdout. Started by hand in a terminal, it prints on stderr what it is, the root, the mode, its tools and how to
+connect it, then waits (Ctrl-C to exit). `jos serve --help` prints the connection commands with the real paths
+filled in; run it in the project folder you want to serve:
 
-## The .jos Standard
+```
+claude mcp add jos -- node /absolute/path/to/@josfox/jos/bin/jos serve --mcp --root /path/to/project
+claude mcp remove jos
+```
 
-A `.jos` file binds **Intention** and **Execution** into one portable artifact:
+For Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
 
 ```json
 {
-  "meta": { "name": "example", "version": "1.0.0" },
-  "intention": {
-    "objective": "What this artifact does",
-    "success_criteria": "How to know it worked"
-  },
-  "guardrails": { "avoid": [], "max_retries": 3 },
-  "orchestration": {
-    "flows": { "main": { "steps": ["task1", "task2"] } }
+  "mcpServers": {
+    "jos": {
+      "command": "node",
+      "args": ["/absolute/path/to/@josfox/jos/bin/jos", "serve", "--mcp", "--root", "/path/to/project"]
+    }
   }
 }
 ```
 
-> Full specification: [jos.md](./jos.md)
-
----
-
-## Architecture
+| Tool | What it is for |
+|---|---|
+| `list_files` | list the files and folders of a directory under the root (recursive to depth 3) |
+| `read_file` | read a regular file under the root (at most 10 MB) |
+| `search_files` | find files under the root by a glob on the name (`*` and `?`; 100 matches, depth 5) |
+| `read_markdown` | read a Markdown file under the root, with its line count |
+| `list_modules` | list the modules in `~/.jos/modules` and whether `~/.jos/modules.json` enables them |
+| `list_processes` | list the runs recorded in `~/.jos/runs/*/report.json` |
+| `hot_reload` | read `~/.jos/modules.json` again and report the enabled and disabled modules |
+| `write_file` | only with `--allow-write`: create or overwrite a file under the root, never under `~/.jos` |
+| `run_command` | only with `--allow-shell`: run a program with an argv (no shell) in a folder under the root; each one shown on stderr |
+
+The server refuses to serve `/`, `$HOME` or a folder containing it unless `--root` names it. A client cannot reach a
+file outside the root, cannot read, list, search or write `~/.jos/secrets` (nor any `.master` or `vault.json` under
+`~/.jos`), cannot write without `--allow-write` and cannot run a program without `--allow-shell`.
+**`--allow-shell` grants local code execution with your user privileges**: a program it starts can read your
+secrets (`~/.jos/secrets`, `~/.ssh`, cloud keys) outside the MCP tools. Do not give it to an untrusted agent
+without an external sandbox (a container or a virtual machine).
+
+## Frozen
+
+Their code stays in `src/commands/_frozen/` and is neither published nor dispatched; each has a one-line
+`*.README.md` with the reason, which is published (`jos <command>` prints its path).
+
+| Frozen | Reason |
+|---|---|
+| `llm` | Overwrote the `.jos` with model output without validating it; sent the artifact with the encrypted vault file as the Bearer token. |
+| `prompts` | `optimize` overwrote the `.jos` without validating it; the adapters fabricated quality scores. |
+| `get` | Wrote to a path built from `meta.name` (path traversal); downloaded without verifying. |
+| `repo` | Managed the repository list that only `get` used. |
+| `serve` (HTTP file explorer) | Served files by working directory without a sandbox and exposed `~/.jos/secrets` when run from the home directory. Exit 2. |
+| `add` | Edited 0.0.7 flows and regenerated their `.sig.json` manifest (which `jos run` verifies again; `jos migrate` replaces it with `integrity.hash`). Flows are written in the document now (`flow.jos` of `jos start`, `examples/03-flow-gate.jos`). |
+
+## Tests
 
 ```
-~/.jos/
-├── commands/       # Plugin architecture
-├── artifacts/      # Package cache
-├── secrets/        # Encrypted vault (AES-256)
-├── runs/           # Execution epochs
-├── repos.json      # Repository configuration
-└── lock.json       # Package integrity
+npm test                  # the gate, in order; no network (Node 22 or later):
+                          #   jos verify; every test/*.test.js once with a per-file coverage gate (each published
+                          #   file of src/ and bin/jos >= 90 % lines, branches, functions; secrets.js and mcp.js 100 %);
+                          #   secrets and mcp alone at 100 %; nothing new left in HOME or in the repository
+npm run test:host         # host tests alone, without coverage (Node 18 or later)
+npm run test:promises     # the promise gate alone: every gate of promises.json (Node 18 or later)
+npm run promises:md       # regenerate PROMISES.md after editing promises.json
+python3 -I bench/bench.py # host overhead over jos-core, appends to BENCHMARKS.md
 ```
 
----
-
-## A2A Protocol Compatibility
-
-This implementation is designed to be compatible with agent interoperability protocols, including the A2A (Agent-to-Agent) Protocol.
-
-- **.jos artifacts** can serve as A2A task payloads
-- **Agents** can declare .jos compatibility in capability cards
-- **Integrity verification** ensures secure artifact exchange
+`test/tour.test.js` runs the tour: every example validates in both kernels with the same `art_`; the ones without
+keys run; the provider and Ollama examples run against a fake `curl` (and a fake `ollama`) on `PATH`, with and without
+a key, and the key is checked absent from the output, the result, the receipts and the ledgers. The tests write only
+to temporary folders; run them as `HOME=$(mktemp -d) npm test` on a machine where other `jos` processes write to
+`~/.jos`.
 
----
+`test/promises.test.js` runs every gate of `promises.json` in a temporary folder with a temporary HOME, no provider
+key and a fake `curl` and `ollama` on `PATH`. A known gap asserts today's behaviour and prints `⚠ known gap: <id>`;
+it fails the day the gap is fixed, and then the entry is updated. It also fails when a row of "What it can do" or
+"Not yet" has no entry, or when `PROMISES.md` is stale.
 
-## Disclaimer & Legal
+## Links
 
-### AS-IS Software
-
-This software is provided **"AS IS"**, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.
-
-### Liability
-
-In no event shall the authors, contributors, or the JOS Open Standards Foundation be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.
-
-### Your Responsibility
-
-- You use this software **at your own risk**
-- You are responsible for validating its suitability for your use case
-- You are responsible for compliance with applicable laws and regulations
-
-### Trademark Notice
-
-- **JOS**, **JOSFOX**, and the Kitsune fox logo are trademarks of the JOS Open Standards Foundation
-- **A2A Protocol** and related terminology are property of their respective owners
-- **Google** and related trademarks are property of Google LLC
-- All other trademarks are property of their respective owners
-
-This project is an independent open-source implementation and is **not affiliated with, endorsed by, or sponsored by** any third-party trademark holders mentioned in this documentation.
-
-### Citation Requirement
-
-If you implement or distribute the .jos standard, you must include attribution to:
-- The **JOS Open Standards Foundation**
-- The official specification repository
-
----
+Specification, schemas and conformance vectors: <https://github.com/josfox-jos/jos-spec>. Source:
+<https://github.com/josfox-jos/jos>.
 
 ## License
 
-**MIT License** — See [LICENSE](./LICENSE) for details.
-
-Free to use for personal, educational, and commercial purposes.
-
----
-
-<div align="center">
-
-**Made with ❤️ & AI**
-
-*JOS Open Standards Foundation*
-
-```
-██╗  ██╗██╗████████╗███████╗██╗   ██╗███╗   ██╗███████╗
-██║ ██╔╝██║╚══██╔══╝██╔════╝██║   ██║████╗  ██║██╔════╝
-█████╔╝ ██║   ██║   ███████╗██║   ██║██╔██╗ ██║█████╗  
-██╔═██╗ ██║   ██║   ╚════██║██║   ██║██║╚██╗██║██╔══╝  
-██║  ██╗██║   ██║   ███████║╚██████╔╝██║ ╚████║███████╗
-╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝
-```
-
-</div>
+Apache License 2.0 ([LICENSE](LICENSE)), from version 5.0.0; versions up to 4.x were published under the MIT
+license. Copyright JOSFOX LLC.

package/SECURITY-MCP.md

@@ -0,0 +1,117 @@
+# `jos serve --mcp` — what an MCP client can and cannot do
+
+Applies to `@josfox/jos` 5.0.0-rc.3 and later (verified again under 5.0.0) (closes H-01). Code: `src/mcp.js`, flag parsing in `src/serve.js`. Tests: `test/mcp.test.js` (gate: `npm run test:mcp`, 100 % lines, branches and functions of `src/mcp.js`).
+
+`jos serve --mcp` speaks JSON-RPC 2.0 over stdio to one MCP client, usually an AI agent. Treat that client as untrusted: it acts on whatever text it has read, and a hostile web page, issue or file can steer it. The server is what stands between that client and the files of the user who started it.
+
+## The problem this fixes (H-01)
+
+Up to 5.0.0-rc.2 the file tools accepted any path under the working directory **and under all of `~/.jos`**, compared lexically (no symlink resolution), `write_file` and `toggle_module` were always on, and `run_command` ran any command line through a shell (`execSync`) behind a list of five forbidden substrings. A client could read `~/.jos/secrets/.master` and `vault.json` directly, or through a symlink in the working directory, and decrypt every stored secret; or `cat` them through `run_command`.
+
+## Usage
+
+```
+jos serve --mcp [--root <dir>] [--allow-write] [--allow-shell]
+```
+
+| Flag | Default | Effect |
+|---|---|---|
+| (none) | read-only, root = working directory | `list_files`, `read_file`, `read_markdown`, `search_files`, `list_modules`, `hot_reload`, `list_processes` |
+| `--root <dir>` | the working directory | the one directory the file tools may reach. Must exist (exit 64 otherwise, or when the value is missing) |
+| `--allow-write` | off | adds `write_file` (inside the root, never under `~/.jos`) |
+| `--allow-shell` | off | adds `run_command` (a program and an argv, no shell): **local code execution with your user privileges**, see [`--allow-shell`](#--allow-shell) |
+
+**The server refuses to start (exit 2)** when the root would be `/`, your home directory, or any directory that contains your home directory, unless you named it yourself with `--root`. The home directory is the parent of the `~/.jos` the host uses.
+
+A tool that is off is not in `tools/list`, and calling it is `-32601 Unknown tool`.
+
+**Started by hand.** When stdin is a terminal (a person, not a client), the server writes a notice on **stderr**: that it is an MCP server waiting for a client, the root, the mode (read-only, or which of `--allow-write` / `--allow-shell` is on), that `~/.jos/secrets` and any `.master` or `vault.json` under `~/.jos` are denied, with `--allow-shell` the warning that the flag is local code execution with the user's privileges, the tools it offers with one line each, and how to connect it (`claude mcp add jos -- node <absolute path of this bin/jos> serve --mcp --root <root>`, `claude mcp remove jos`, and the JSON block for Claude Desktop / Cursor), then `Ctrl-C to exit.` Nothing of it goes to stdout, the JSON-RPC channel. When stdin is not a terminal, which is how a client starts the server, there is no notice. The examples it prints are read-only; `jos serve --help` prints the same, for the current directory or the `--root` given with `--help`, and warns when that root is `/`, `$HOME` or contains it.
+
+## Roots
+
+| Tool | Reaches | Notes |
+|---|---|---|
+| `list_files`, `read_file`, `read_markdown`, `search_files` | the root, nothing else | `~/.jos` is **no longer a root**. If the root contains `~/.jos` (only possible with an explicit `--root`), the server says so on stderr at start; `~/.jos/secrets` stays denied |
+| `write_file` (`--allow-write`) | the root, minus everything under `~/.jos` | |
+| `list_modules`, `hot_reload` | read `~/.jos/modules.json`, `~/.jos/modules/*/package.json` | fixed names; the client chooses no path |
+| `list_processes` | reads `~/.jos/runs/*/report.json` | fixed names; reports liveness with `kill(pid, 0)` |
+| `toggle_module` | **removed** | it wrote `~/.jos/modules.json`; nothing writes under `~/.jos` any more |
+| `run_command` (`--allow-shell`) | anything the user can do | see below |
+
+## How a path is checked
+
+1. The client's string must be a string without NUL; it is resolved against the root (`..`, `.`, repeated slashes collapse here).
+2. The result is turned into its **real path** with `fs.realpathSync.native` (which also returns the on-disk case on APFS). For a path that does not exist yet, the real path of its deepest existing ancestor is taken and the missing components are appended. A dangling symlink, a symlink loop, a component that is not a directory, or an unreadable component on the way makes the path **denied**.
+3. The real path must be the root or lie under it. A symlink inside the root that points outside it (for example to `~/.ssh`) is therefore denied.
+4. Neither the lexical nor the real path may be protected by name (next section); for a write, neither may lie under `~/.jos`.
+5. The **device and inode** of the path and of each of its existing ancestors are compared with those of `~/.jos/secrets` and of every entry in it (and, for a write, of `~/.jos`). This catches hard links, case or Unicode folding the name checks missed, and any other alias of the same directory.
+6. The file is opened **by that real path** with `O_NOFOLLOW` (and `O_NONBLOCK`, so a FIFO in the tree cannot hang the server); after opening, its inode is compared again. Writes open without `O_TRUNC`, check the inode, and only then truncate through the same descriptor, so a hard link to a secret is never emptied.
+
+Listing and searching apply the same rules to every entry they meet: protected entries, hard links to a secret, and symlinks that leave the root, dangle or end in a protected place are left out (not reported as errors).
+
+## What is protected
+
+- `~/.jos/secrets` and everything below it, in its lexical form, its real form and by inode (so a `~/.jos` that is itself a symlink, or a secrets directory reached by its real location inside the root, is still denied);
+- any file named `.master` or `vault.json` anywhere under `~/.jos` (for example a stray copy);
+- for writes, everything under `~/.jos`.
+
+The comparison of names ignores case and Unicode normalization (APFS and NTFS are case-insensitive; on APFS even `ſ`, U+017F, is the same letter as `s`, which the real-path and inode steps catch). On a case-sensitive file system this also denies, for instance, `~/.jos/SECRETS`, which is a different directory there: over-denial, never under-denial.
+
+The protected set is recomputed on every call, so a vault created while the server runs is protected from its first byte; a path under `~/.jos/secrets` is denied by name even before the directory exists, so a client cannot learn whether it does.
+
+## Errors
+
+Out of the root and protected give the same message, `Access denied: path is outside the working directory or protected`, whether the file exists or not. Other errors name only the path the client wrote and an error code (`File not found: x`, `Cannot open x: EACCES`, `Not a regular file: x`). No error and no response carries the content of a denied file or a key; the tests check every response and stderr for the synthetic master key, ciphertext and secret value.
+
+## `--allow-shell`
+
+**Warning: `--allow-shell` grants local code execution with the privileges of the user who runs `jos`.** A program started by `run_command` can read the secrets (`~/.jos/secrets`, `.master`, `~/.ssh`, cloud credentials) outside the MCP tools: the root, the path checks and the denials of this document bind the file tools, not that program. Do not give `--allow-shell` to an untrusted agent, or to a client that relays one, without an external sandbox (a container or a virtual machine that holds neither your home directory nor your keys). `jos serve --help` and the notice at start (stdin a terminal) print this warning, and the stderr warning at start of a server with the flag repeats it.
+
+`jos serve --mcp --allow-shell` adds `run_command { command, args?, cwd?, timeout? }`:
+
+- `command` is a program (looked up in `PATH`, or a path) and `args` an array of strings. It is started with `spawnSync(command, args, { shell: false })`: no command line, no expansion, no `;`, `|`, `$(...)` or globbing. `"echo hi; touch x"` as `command` is a program name that does not exist (`ENOENT`). A client that wants a shell has to ask for one explicitly (`command: "sh", args: ["-c", ...]`) — the flag allows that too; see below.
+- `cwd` (default: the root) is checked like any path: inside the root, not protected; the root of the file system (`/`) is refused even when it is the root.
+- At start the server writes a warning on stderr; **every command** is written to stderr before it runs (`▶ jos serve: run_command ["prog","arg"] in "<dir>"`, JSON-quoted so no terminal escape gets through).
+- The child's environment is the server's minus every variable whose name (compared without case) is a secret name in `~/.jos/secrets/vault.json` or `~/.jos/secrets/keychain.json`. That also removes whatever `jos secrets exec --only A,B -- jos serve ...` put there. If either file exists but cannot be read or has another shape, the command is refused (better no command than one with a secret in its environment).
+- stdin is `/dev/null` (never the protocol stream); timeout defaults to 30 s and is capped at 10 min; output is capped at 1 MiB.
+- The old list of forbidden substrings (`rm -rf /`, `mkfs`, ...) is **gone**: it never was a defence (`rm -rf "/"` or `rm -fr /` passed it) and keeping it would suggest one.
+
+**What `--allow-shell` does not protect: anything.** It runs any program as you. `cat ~/.jos/secrets/.master`, `sh -c ...`, reading `~/.ssh`, `~/.aws` or browser profiles, and `jos secrets exec` all work. No shell parsing only removes injection through a command line; stripping secret names from the environment only stops the secrets already in the server's environment from being handed over for free. Use the flag only with a client you would let type in your terminal.
+
+## What this does not protect
+
+- **The root itself.** The client reads every file in it, dot files included when named (`read_file('.env')`; listings and searches skip dot files). With `--allow-write` it can overwrite any of them, including files that run code later: `.git/hooks/*`, `package.json` scripts, `Makefile`. Serve a project directory.
+- **Races.** Steps 2–6 are not atomic. `O_NOFOLLOW` covers the last component and the inode is compared after opening; a process of the same user that swaps an intermediate directory for a symlink between the check and the open can still redirect the access. Such a process can read the secrets directly anyway.
+- **Other users of the same uid**, root, and anything with a copy of `.master` (see SECURITY-SECRETS.md).
+- **Secrets that are not in the vault**: environment variables with other names (`AWS_SECRET_ACCESS_KEY` set by your shell), credential files inside the root.
+- **Copies** (not hard links) of a secret file outside `~/.jos`, or under `~/.jos` with a name other than `.master` or `vault.json`, for example a backup someone left in the root. A hard link to the original is denied by inode wherever it is.
+- **Windows**: the code has no platform branch and drops the flags Windows lacks, but it has not been run there.
+
+## Tests and coverage
+
+`test/mcp.test.js`, 40 tests, in-process (calling `handleMessage` and `startMCPServer` with streams) and over the real stdio protocol (`bin/jos serve --mcp`), each in its own temporary `HOME` with a synthetic vault (one of them written by the real `jos secrets set --stdin`). `JOS_SECRETS_BACKEND` and `JOS_TEST_KEYCHAIN` are removed from the test process and from every child.
+
+- M1 every spelling of a path into the secrets (relative, absolute, `..`, `./`, case, `ſ` on macOS, repeated slashes, the directory itself, missing files under it, before the directory exists, a symlinked `~/.jos`, a root inside the secrets) is denied for all five file tools; out-of-root paths get the same message whether they exist or not;
+- M2 a symlink and a hard link in the root to `.master` are denied and hidden; symlinks out of the root, dangling, looping or through a file are denied, a symlink inside the root works;
+- M3 `run_command` is absent and unknown without `--allow-shell`; with it, it runs an argv without a shell (metacharacters stay bytes), is announced on stderr, and `env` in the child shows none of the vault and keychain names (also in other case); `cwd` outside the root or `/` is refused; refusal when the names cannot be read; failure, signal, timeout and bad `cwd` are reported;
+- M4 reads, overwrites, listings, recursive listings and glob searches inside the root keep working; FIFO, `EACCES`, size limit and invalid parameters give clean errors;
+- M6 read-only by default (`write_file` and the removed `toggle_module` are unknown tools); with `--allow-write` nothing is written under `~/.jos`, from a root that contains it or from a root inside it;
+- M7 `/`, `$HOME` and an ancestor of it are refused without `--root` (exit 2), accepted with it; `--root` without a value or to a missing directory exits 64;
+- the notice: with stdin a terminal it is on stderr and stdout stays empty, it lists only the tools that are on and carries an existing absolute path of `bin/jos` and the root in its examples; without a terminal there is none; `--help` lists every tool with its flag, has no `undefined`, and its examples carry real paths (and the short `jos` form only when `jos` on `PATH` is this `bin/jos`); `--help`, and the notice when `--allow-shell` is on (only then), carry the warning that the flag is local code execution and needs an external sandbox for an untrusted agent;
+- module tools: `modules.json` as a symlink or a hard link into the secrets reads as missing; `~/.jos/runs` or `~/.jos/modules` as a link to `~/.jos/secrets` lists nothing and reads nothing from it, with a file planted one level inside the secrets that only the `homePath` check (real path, then name denial) stops, since the inode comparison after opening covers only the direct entries of the secrets directory (R-18);
+- a symlink swapped in for the last component between the path check and the open (the test wraps `fs.openSync`, the call that opens the file) is refused for `read_file` and for `write_file`, with a decoy inside the root that is not a secret, so only `O_NOFOLLOW` can stop it (R-17).
+
+Coverage of `src/mcp.js`: 100 % lines, branches and functions, without exclusions. Two tests are skipped when run as root (`EACCES` cannot be produced) and three on Windows (FIFO, and the two `O_NOFOLLOW` tests, which say so: the flag does not exist there); in those environments the gate cannot reach 100 % branches.
+
+Sensitivity, checked by mutation on a scratch copy (each mutant must make `npm run test:mcp` fail): removing the path jail, the realpath step, the root check, the name denial, the ancestor inode check, the inode check at open, the `~/.jos` write block, the write flag, the `--allow-write` or `--allow-shell` gate, `shell: false`, the environment filter, `O_NONBLOCK` (the FIFO test then hangs and is killed), `O_NOFOLLOW` (the two swap tests then read or write through the symlink and fail), the realpath or the protection in `homePath` (the two `~/.jos/runs`/`~/.jos/modules` link tests then list the planted entry), the listing filter, the refusal to serve `$HOME` or the `cwd: "/"` check — every one fails the gate.
+
+## Incompatible changes
+
+- Read-only by default: `write_file` exists only with `--allow-write`, and never writes under `~/.jos`. `toggle_module` is removed.
+- `run_command` exists only with `--allow-shell`, and takes a program plus an `args` array; a command line in `command` is no longer run through a shell.
+- `jos serve --mcp` refuses to start in `/`, in `$HOME` or in a directory containing it, unless `--root` names the directory.
+- The file tools no longer reach `~/.jos` from a root outside it.
+- A symlink in the root that points outside it is no longer followed (denied, and hidden from listings).
+- `search_files` takes a glob on the file name (`*`, `?`, anchored at both ends), no longer a regular expression made from the pattern; `hello` no longer matches `hello.txt`. The 100-match limit now holds within one directory too.
+- `read_file` refuses unknown encodings and non-regular files; `write_file` refuses non-string content.
+- Error texts for denied paths changed to the single message above.