@josfox/jos 4.1.0 → 5.0.0

package/README.md

@@ -1,138 +1,334 @@
-# JOS Open Standard
-
-> **The minimal atomic unit for fractal, intention-native Adaptive Intelligent Agents.**
-
-JOS (JSON Object Specification) introduces a novel fractal paradigm for AI orchestration—**intention-based, efficient, portable, secure, and adaptive by design.** Every `.jos` artifact encodes both the *why* (intention) and the *how* (execution) as a single, versioned, cryptographically verifiable unit.
-
-[![npm](https://img.shields.io/npm/v/@josfox/jos?label=%40josfox%2Fjos)](https://www.npmjs.com/package/@josfox/jos)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Specification](https://img.shields.io/badge/Spec-v0.0.7-purple.svg)](https://github.com/josfox-ai/jos-format-spec)
-
----
-
-## ✨ What's New in v4.1.0
-
-### 🧠 LLM Integration & Prompt Enhancement
-- **Native LLM Support**: `jos llm <artifact>` crystallizes `.jos` intentions into chat-oriented prompts for any AI/LLM/GPT
-- **Multi-Adapter Architecture**: Ollama (local), Gemini, OpenAI, Anthropic adapters built-in
-- **Prompt Enhancement**: Automatically enriches prompts with guardrails, context, and success criteria
-
-### 🦊 Introducing ALAIA
-**Adaptive Learning AI Agent** — the nano-agent framework that bonds to `.jos` artifacts, enabling:
-- Offline-first execution with Ollama
-- Real-time guardrail enforcement
-- Adaptive learning from execution feedback
-
-### 🚀 Quick Start with Ollama
-Run locally with zero cloud dependencies:
-```bash
-# Install JOS
-npm install -g @josfox/jos
-
-# Clone starter examples
-git clone https://github.com/josfox-ai/jos-repo-starter
-cd jos-repo-starter
-
-# Run with local Ollama
-jos llm examples/hello-ai.jos --adapter ollama
-```
-
----
-
-## 🎯 The Fractal Paradigm
-
-> *"Everything is a prompt. Every prompt is an intention. Every intention is an artifact."*
-
-JOS artifacts are **self-similar at all scales**—from atomic single-step automations to orchestrated enterprise workflows. The same schema, the same validation, the same security model.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      .jos ARTIFACT                               │
-├─────────────────────────────────────────────────────────────────┤
-│   MAGIC Kernel (Why + What)    │   JOSFOXAI Kernel (How + Who)  │
-│   ─────────────────────────    │   ───────────────────────────  │
-│   • intention                  │   • orchestration              │
-│   • success_criteria           │   • security                   │
-│   • guardrails                 │   • files                      │
-│   • capabilities               │   • integrity verification     │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📦 Installation
-
-```bash
-# Core kernel (zero dependencies)
-npm install -g @josfox/jos
-
-# With orchestration controller
-npm install -g josctl
-
-# With extended CLI features
-npm install -g @josfox/jos-cli
-```
-
----
-
-## 🔧 Commands
-
-| Command | Description |
-|---------|-------------|
-| `jos run <artifact>` | Execute a .jos artifact |
-| `jos llm <artifact>` | Crystallize intention for LLM interaction |
-| `jos validate <artifact>` | Strict validation (13 required keys) |
-| `jos serve` | Launch local dashboard |
-| `jos get <foxtail>` | Install artifact from registry |
-
----
-
-## 📝 Minimal Valid Artifact
-
-Every `.jos` artifact requires **13 keys** for strict validation:
-
-```json
-{
-  "id_jos": "example-v1",
-  "jos": { "open": "jos run artifact", "supports": ["@josfox/jos"] },
-  "orchestration_contract": { "version": "0.0.7", "mode": "sync" },
-  "meta": { "name": "example", "version": "1.0.0", "type": "atom" },
-  "intention": { "objective": "Demonstrate JOS", "success_criteria": "Output greeting" },
-  "guardrails": { "avoid": [], "max_retries": 0 },
-  "capabilities": ["demo"],
-  "artifacts": { "description": "Minimal example" },
-  "orchestration": {
-    "definitions": { "greet": { "type": "shell", "command": "echo 'Hello!'" } },
-    "flows": { "main": { "steps": ["greet"] } }
-  },
-  "security": { "type": "open", "permissions": [], "integrity_ref": null },
-  "files": [],
-  "x_run_params": { "timeout": 5000, "retry_on_failure": false },
-  "adaptive_ai": { "learning_enabled": false, "feedback_collection": false }
-}
-```
-
----
-
-## 🔗 Ecosystem Links
-
-| Resource | Link |
-|----------|------|
-| 📖 **Specification** | [github.com/josfox-ai/jos-format-spec](https://github.com/josfox-ai/jos-format-spec) |
-| 🦊 **Starter Examples** | [github.com/josfox-ai/jos-repo-starter](https://github.com/josfox-ai/jos-repo-starter) |
-| 🎨 **KRMEN Design System** | [krmen.mx](https://krmen.mx) |
-| 📦 **npm: @josfox/jos** | [npmjs.com/package/@josfox/jos](https://www.npmjs.com/package/@josfox/jos) |
-| 📦 **npm: josctl** | [npmjs.com/package/josctl](https://www.npmjs.com/package/josctl) |
-
----
-
-## 🏛️ Governance
-
-**JOS Open Standards Foundation**  
-Specification v0.0.7 · Format v0.1.0 (Alpha)
-
----
-
-## 📄 License
-
-MIT © JOS Open Standards Foundation
+# @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` 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.
+
+## Start
+
+```
+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
+```
+
+`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.
+
+`jos run` shows the intention first, then the verdict of each criterion, then the outcome:
+
+```
+$ jos run hello.jos
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JOS RUN // jos-core 2.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  File: hello.jos
+
+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
+
+hello, .jos
+
+Verdict:
+  [1] hello ✓ code 0
+    ✓ exit: exit 0 (want 0)
+    ✓ stdout_contains: found
+
+✓ 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 | 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:
+
+```
+claude mcp add jos -- node /absolute/path/to/@josfox/jos/bin/jos serve --mcp --root /path/to/project
+claude mcp remove jos
+```
+
+For Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "jos": {
+      "command": "node",
+      "args": ["/absolute/path/to/@josfox/jos/bin/jos", "serve", "--mcp", "--root", "/path/to/project"]
+    }
+  }
+}
+```
+
+| 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
+
+```
+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
+```
+
+`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.
+
+## Links
+
+Specification, schemas and conformance vectors: <https://github.com/josfox-jos/jos-spec>. Source:
+<https://github.com/josfox-jos/jos>.
+
+## License
+
+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.