@josfox/jos 4.1.0 → 5.0.0

package/src/commands/start.js

@@ -0,0 +1,210 @@
+/**
+ * JOS START - quick start: writes a folder (jos-start/ or the one given) with four examples that run without keys and
+ * without network, and a README with the commands in order and what each prints:
+ *   hello.jos    an atom: intention, success criteria, guardrails, one shell step
+ *   flow.jos     a flow with a human gate (stops with code 1 until `--approve build`)
+ *   sealed/      a folder whose .jos/manifest.jos is sealed with the directory hash jos-core computes (SPEC-2.0 §9.3)
+ *   limits.jos   guardrails that stop steps: an avoid pattern (code 3) and a time limit (code 124)
+ * Every document is validated by jos-core before anything is written. Nothing is overwritten: if one of the files
+ * exists, nothing is written. Exit codes: 0 written, 1 exists or cannot be written, 5 no kernel, 64 usage.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const kernel = require('../kernel');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+
+const DEFAULT_DIR = 'jos-start';
+const USAGE = 'usage: jos start [dir]';
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS START${C.reset} // Four examples to run first
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos start [dir]          (default: ./${DEFAULT_DIR})
+
+${C.bold}Writes:${C.reset}
+  hello.jos    an atom: intention, success criteria, guardrails, one shell step
+  flow.jos     a flow with a human gate: code 1 until you run it with --approve build
+  sealed/      a folder sealed by its directory hash: edit .jos/manifest.jos and it is code 3
+  limits.jos   guardrails at work: an avoid pattern blocks a step (code 3), a time limit
+               stops another (code 124)
+  README.md    the commands in order and what each one prints
+
+  They run without keys and without network. Every document is validated by jos-core
+  before writing; nothing is overwritten (if one of the files exists, nothing is written).
+`;
+
+const LIMIT = { seconds: 10, output_bytes: 65536, retries: 0 };
+const head = (kind, id, objective, criteria) => ({
+    jos: { version: '2.0.0', kind }, id, meta: { name: id, version: '1.0.0' },
+    intention: { objective, success_criteria: criteria },
+});
+
+function documents() {
+    const hello = Object.assign(head('atom', 'hello', 'Print a greeting and exit cleanly', [{ exit: 0 }, { stdout_contains: 'hello' }]), {
+        guardrails: { avoid: ['rm -rf', 'curl', 'wget'], limit: LIMIT },
+        execution: { engine: 'shell', run: ['echo', 'hello, .jos'], env: ['PATH'] },
+    });
+    const step = (word, objective) => ({ engine: 'shell', run: ['echo', word], intention: { objective, success_criteria: [{ stdout_contains: word }] } });
+    const flow = Object.assign(head('flow', 'flow', 'Build, wait for a person to approve the build, then publish', [{ exit: 0 }]), {
+        guardrails: { avoid: ['rm -rf'], limit: LIMIT },
+        orchestration: {
+            definitions: { build: step('built', 'Make the artifact'), publish: step('published', 'Publish the approved build') },
+            flows: { main: { steps: ['build', 'publish'], gates: { build: { kind: 'human' } } } },
+        },
+    });
+    const sealed = Object.assign(head('directory', 'sealed', 'Run only while the folder is exactly as it was sealed', [{ exit: 0 }, { stdout_contains: 'sealed folder ran' }]), {
+        guardrails: { limit: LIMIT },
+        orchestration: {
+            definitions: { say: { engine: 'shell', run: ['echo', 'the sealed folder ran'] } },
+            flows: { main: { steps: ['say'] } },
+        },
+    });
+    const limits = Object.assign(head('flow', 'limits', 'Show guardrails stopping steps: an avoid pattern before launch, a time limit during the run', [{ exit: 0 }]), {
+        guardrails: { avoid: ['rm -rf'], limit: LIMIT },
+        orchestration: {
+            definitions: {
+                cleanup: { engine: 'shell', run: ['echo', 'rm -rf ./build'], execution: { on_error: 'continue' }, description: 'Matches avoid: never starts (code 3)' },
+                slow: { engine: 'shell', run: ['sleep', '5'], guardrails: { limit: { seconds: 1 } }, description: 'Needs 5 s, may take 1: stopped (code 124)' },
+            },
+            flows: { main: { steps: ['cleanup', 'slow'] } },
+        },
+    });
+    return { hello, flow, sealed, limits };
+}
+
+const README = (dir, version, artifact) => `# jos start
+
+Four \`.jos\` examples written by \`jos start\`. They run without keys and without network.
+Run the commands in this order from \`${dir}\`; each \`jos run\` prints the intention first,
+then the verdict of every criterion, then \`Intention met\` or \`Intention NOT met\`.
+
+| Command | What you see | Exit |
+|---|---|---|
+| \`jos validate hello.jos\` | the intention, \`✓ VALIDATION PASSED\`; nothing runs | 0 |
+| \`jos run hello.jos\` | \`hello, .jos\`, then \`✓ exit\`, \`✓ stdout_contains\`, \`✓ Intention met\` | 0 |
+| \`jos run flow.jos\` | \`build\` runs, then the human gate stops the flow: \`Intention NOT met (code 1: not done)\` and the command to approve | 1 |
+| \`jos run flow.jos --approve build\` | \`build\` and \`publish\` run: \`published\`, \`✓ Intention met\` | 0 |
+| \`jos ids hello.jos flow.jos sealed\` | the \`art_\` (content), \`ent_\` (name) and, for \`sealed\`, the directory hash | 0 |
+| \`jos run sealed\` | \`the sealed folder ran\`: the folder's hash matches \`integrity.hash\` | 0 |
+| \`jos run limits.jos\` | \`cleanup\` blocked by \`avoid\` before it starts (code 3), \`slow\` stopped after 1 s (code 124) | 124 |
+| \`jos runs\` | the runs above, newest first, with their codes | 0 |
+| \`jos ledger verify <run_id>\` | \`✓ LEDGER VERIFIED\`: every hash of the run's ledger recomputed | 0 |
+| \`jos meter <run_id>\` | steps, attempts, time; tokens and cost "not reported" (the shell engine reports none) | 0 |
+
+To see the seal work, change the text \`the sealed folder ran\` in \`sealed/.jos/manifest.jos\`
+and run \`jos run sealed\` again: \`Intention NOT met (code 3: blocked)\`, because the declared hash
+no longer matches. Undo the change and it runs again.
+
+The ledgers of these runs are in \`~/.jos/runs/\` (for \`sealed\`, in \`sealed/.jos/replays/\`).
+
+## What \`jos run hello.jos\` prints (NO_COLOR)
+
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JOS RUN // jos-core ${version}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  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: ${artifact}
+  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_…)
+\`\`\`
+
+The \`art_\` is the hash of the document's content: the same on every machine, in both reference kernels.
+`;
+
+exports.execute = async (args) => {
+    const err = ui.printer(process.stderr);
+    const { files, help, error } = parse(args, {});
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    if (error || files.length > 1) {
+        err.fail('jos start: ' + (error ? problem(error) : 'takes at most one folder'));
+        err.hint(USAGE);
+        return 64;
+    }
+    const given = files.length ? files[0] : DEFAULT_DIR;
+    const dir = path.resolve(given);
+
+    let k;
+    let core;
+    try { k = kernel.locate(); core = kernel.need(k, ['validate', 'dirHash']); } catch (e) { return kernel.fail(e); }
+    const docs = documents();
+    for (const [name, doc] of Object.entries(docs)) {
+        const v = core.validate(doc);
+        if (!v.valid) throw new Error('jos start: the ' + name + ' example is not valid for jos-core ' + k.version + ': ' + v.errors.join('; '));
+    }
+    if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
+        err.fail('jos start: ' + given + ' exists and is not a folder');
+        return 1;
+    }
+    const taken = ['hello.jos', 'flow.jos', 'limits.jos', 'sealed', 'README.md'].filter((n) => fs.existsSync(path.join(dir, n)));
+    if (taken.length) {
+        err.fail('jos start: ' + given + ' already has ' + taken.join(', '), '(nothing was written; nothing is overwritten)');
+        err.hint('choose another folder: jos start <dir>');
+        return 1;
+    }
+
+    const shown = ui.shellArg(given);
+    try {
+        fs.mkdirSync(path.join(dir, 'sealed', '.jos'), { recursive: true });
+        const write = (name, text) => fs.writeFileSync(path.join(dir, name), text, { flag: 'wx' });
+        for (const name of ['hello', 'flow', 'limits']) write(name + '.jos', JSON.stringify(docs[name], null, 2) + '\n');
+        // seal: write the manifest, hash the folder with the kernel (integrity.hash itself is not hashed), write it again
+        const manifest = path.join(dir, 'sealed', '.jos', 'manifest.jos');
+        write('sealed/.jos/manifest.jos', JSON.stringify(docs.sealed, null, 2) + '\n');
+        docs.sealed.integrity = { hash: core.dirHash(path.dirname(manifest)).hash };
+        fs.writeFileSync(manifest, JSON.stringify(docs.sealed, null, 2) + '\n');
+        write('README.md', README(given, k.version, core.validate(docs.hello).artifact));
+    } catch (e) {
+        err.fail('jos start: cannot write in ' + given + ': ' + (e && e.code ? e.code : e.message));
+        return 1;
+    }
+
+    err.header('JOS START', 'jos-core ' + k.version);
+    err.ok('Created ' + given + '/', '(four examples; no keys, no network)');
+    err.item('hello.jos     an atom: intention, criteria, guardrails');
+    err.item('flow.jos      a flow with a human gate');
+    err.item('sealed/       a folder sealed by its hash: ' + docs.sealed.integrity.hash.slice(0, 19) + '…');
+    err.item('limits.jos    guardrails at work: avoid (code 3) and limit (code 124)');
+    err.item('README.md     the commands in order and what each prints');
+    err.line();
+    err.line(`${err.C.bold}Next:${err.C.reset}`);
+    err.cmd('cd ' + shown);
+    err.cmd('jos validate hello.jos');
+    err.cmd('jos run hello.jos');
+    err.cmd('jos run flow.jos                  # stops at the gate: code 1');
+    err.cmd('jos run flow.jos --approve build');
+    err.cmd('jos run sealed');
+    err.cmd('jos run limits.jos                # code 124: the receipts show 3 and 124');
+    err.cmd('jos runs');
+    err.line();
+    return 0;
+};

package/src/commands/validate.js

@@ -1,194 +1,178 @@
-/**
- * JOS VALIDATE Command - Validate .jos artifacts
- * Checks schema, required keys, and integrity
- * Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const C = {
-    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-    purple: '\x1b[38;5;135m', cyan: '\x1b[38;5;51m',
-    green: '\x1b[38;5;78m', red: '\x1b[38;5;196m',
-    yellow: '\x1b[38;5;220m', gray: '\x1b[38;5;245m'
-};
-
-// Witness Logging
-function logWitness(home, eventType, data) {
-    const runId = global.JOS_VALIDATE_ID || new Date().toISOString().replace(/[:.]/g, '-');
-    global.JOS_VALIDATE_ID = runId;
-
-    const runDir = path.join(home, 'runs', runId);
-    if (!fs.existsSync(runDir)) fs.mkdirSync(runDir, { recursive: true });
-
-    const event = {
-        timestamp: new Date().toISOString(),
-        type: `validate:${eventType}`,
-        ...data
-    };
-
-    fs.appendFileSync(path.join(runDir, 'events.jsonl'), JSON.stringify(event) + '\n');
-}
-
-// Required keys for JOSFOXAI + MAGIC compliance (ALL REQUIRED - NO EXCEPTIONS)
-const JOSFOXAI_KEYS = ['jos', 'orchestration_contract', 'security', 'files', 'orchestration', 'x_run_params', 'adaptive_ai', 'id_jos'];
-const MAGIC_KEYS = ['meta', 'artifacts', 'guardrails', 'intention', 'capabilities'];
-const ALL_REQUIRED_KEYS = [...JOSFOXAI_KEYS, ...MAGIC_KEYS];
-
-exports.execute = async (args, home) => {
-    const target = args[0];
-    const insecure = args.includes('--insecure');
-    const verbose = args.includes('--verbose') || args.includes('-v');
-
-    if (!target || args.includes('--help')) {
-        console.log(`
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
-${C.bold}JOS VALIDATE${C.reset} // Validate .jos artifacts (STRICT)
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
-
-${C.bold}Usage:${C.reset}
-  jos validate <file.jos> [options]
-
-${C.bold}Options:${C.reset}
-  --insecure    Skip integrity verification
-  --verbose     Show detailed validation information
-
-${C.bold}ALL REQUIRED Keys:${C.reset}
-  JOSFOXAI: ${JOSFOXAI_KEYS.join(', ')}
-  MAGIC: ${MAGIC_KEYS.join(', ')}
-
-${C.bold}Validates:${C.reset}
-  1. JSON syntax
-  2. ALL JOSFOXAI keys (8 required)
-  3. ALL MAGIC keys (5 required)
-  4. Integrity manifest (unless --insecure)
-`);
-        return;
-    }
-
-    console.log(`\n${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`${C.bold}JOS VALIDATE${C.reset} // ${C.gray}Format v0.0.7 — STRICT MODE${C.reset}`);
-    console.log(`${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`\n${C.cyan}📋 Artifact:${C.reset} ${target}`);
-
-    logWitness(home, 'start', { artifact: target });
-
-    let allPassed = true;
-    const results = [];
-
-    // 1. JSON Syntax Check
-    let content, artifact;
-    try {
-        content = fs.readFileSync(target, 'utf8');
-        artifact = JSON.parse(content);
-        console.log(`${C.green}  ✓ JSON Syntax Valid${C.reset}`);
-        results.push({ check: 'json_syntax', passed: true });
-        logWitness(home, 'check_passed', { check: 'json_syntax' });
-    } catch (e) {
-        console.log(`${C.red}  ✖ JSON Error: ${e.message}${C.reset}`);
-        results.push({ check: 'json_syntax', passed: false, error: e.message });
-        logWitness(home, 'check_failed', { check: 'json_syntax', error: e.message });
-        process.exit(1);
-    }
-
-    // 2. JOSFOXAI Keys Check (ALL 8 REQUIRED)
-    const missingJosfoxai = JOSFOXAI_KEYS.filter(k => !artifact[k]);
-    if (missingJosfoxai.length > 0) {
-        console.log(`${C.red}  ✖ Missing JOSFOXAI Keys: ${missingJosfoxai.join(', ')}${C.reset}`);
-        results.push({ check: 'josfoxai_keys', passed: false, missing: missingJosfoxai });
-        logWitness(home, 'check_failed', { check: 'josfoxai_keys', missing: missingJosfoxai });
-        allPassed = false;
-    } else {
-        console.log(`${C.green}  ✓ JOSFOXAI Keys Present (${JOSFOXAI_KEYS.length}/${JOSFOXAI_KEYS.length})${C.reset}`);
-        results.push({ check: 'josfoxai_keys', passed: true });
-        logWitness(home, 'check_passed', { check: 'josfoxai_keys' });
-    }
-
-    // 3. MAGIC Keys Check (ALL 5 REQUIRED)
-    const missingMagic = MAGIC_KEYS.filter(k => !artifact[k]);
-    if (missingMagic.length > 0) {
-        console.log(`${C.red}  ✖ Missing MAGIC Keys: ${missingMagic.join(', ')}${C.reset}`);
-        results.push({ check: 'magic_keys', passed: false, missing: missingMagic });
-        logWitness(home, 'check_failed', { check: 'magic_keys', missing: missingMagic });
-        allPassed = false;
-    } else {
-        console.log(`${C.green}  ✓ MAGIC Keys Present (${MAGIC_KEYS.length}/${MAGIC_KEYS.length})${C.reset}`);
-        results.push({ check: 'magic_keys', passed: true });
-        logWitness(home, 'check_passed', { check: 'magic_keys' });
-    }
-
-    // 4. Orchestration Structure Check
-    if (artifact.orchestration) {
-        const hasDefinitions = artifact.orchestration.definitions && Object.keys(artifact.orchestration.definitions).length > 0;
-        const hasFlows = artifact.orchestration.flows && Object.keys(artifact.orchestration.flows).length > 0;
-
-        if (hasDefinitions && hasFlows) {
-            const defCount = Object.keys(artifact.orchestration.definitions).length;
-            const flowCount = Object.keys(artifact.orchestration.flows).length;
-            console.log(`${C.green}  ✓ Orchestration Structure (${defCount} definitions, ${flowCount} flows)${C.reset}`);
-            results.push({ check: 'orchestration_structure', passed: true, definitions: defCount, flows: flowCount });
-        } else {
-            console.log(`${C.yellow}  ⚠ Orchestration may be incomplete${C.reset}`);
-            results.push({ check: 'orchestration_structure', passed: true, warning: 'may be incomplete' });
-        }
-    }
-
-    // 5. Integrity Check
-    if (!insecure) {
-        if (artifact.security?.integrity_ref) {
-            const manifestPath = path.resolve(path.dirname(target), artifact.security.integrity_ref);
-            if (fs.existsSync(manifestPath)) {
-                try {
-                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-                    const hash = crypto.createHash('sha256').update(content).digest('hex');
-                    if (hash === manifest.artifact_sha256) {
-                        console.log(`${C.green}  ✓ Integrity Verified (SHA-256 match)${C.reset}`);
-                        if (verbose) {
-                            console.log(`${C.gray}    Hash: ${hash}${C.reset}`);
-                        }
-                        results.push({ check: 'integrity', passed: true, hash: hash });
-                        logWitness(home, 'integrity_verified', { hash: hash, manifest: artifact.security.integrity_ref });
-                    } else {
-                        console.log(`${C.red}  ✖ Integrity Mismatch!${C.reset}`);
-                        if (verbose) {
-                            console.log(`${C.gray}    Expected: ${manifest.artifact_sha256}${C.reset}`);
-                            console.log(`${C.gray}    Actual:   ${hash}${C.reset}`);
-                        }
-                        results.push({ check: 'integrity', passed: false, expected: manifest.artifact_sha256, actual: hash });
-                        logWitness(home, 'integrity_failed', { expected: manifest.artifact_sha256, actual: hash });
-                        allPassed = false;
-                    }
-                } catch (e) {
-                    console.log(`${C.red}  ✖ Invalid Manifest: ${e.message}${C.reset}`);
-                    results.push({ check: 'integrity', passed: false, error: e.message });
-                    allPassed = false;
-                }
-            } else {
-                console.log(`${C.red}  ✖ Manifest Not Found: ${artifact.security.integrity_ref}${C.reset}`);
-                results.push({ check: 'integrity', passed: false, error: 'manifest not found' });
-                logWitness(home, 'integrity_failed', { error: 'manifest not found' });
-                allPassed = false;
-            }
-        } else {
-            console.log(`${C.yellow}  ⚠ No Integrity Reference (security.integrity_ref)${C.reset}`);
-            results.push({ check: 'integrity', passed: true, warning: 'no integrity_ref' });
-        }
-    } else {
-        console.log(`${C.yellow}  ⚠ Integrity Check Skipped (--insecure)${C.reset}`);
-        results.push({ check: 'integrity', skipped: true });
-    }
-
-    // Summary
-    console.log('');
-    if (allPassed) {
-        console.log(`${C.green}${C.bold}✓ VALIDATION PASSED${C.reset}`);
-        logWitness(home, 'success', { results: results });
-    } else {
-        console.log(`${C.red}${C.bold}✖ VALIDATION FAILED${C.reset}`);
-        logWitness(home, 'failed', { results: results });
-        process.exit(1);
-    }
-    console.log('');
-};
+/**
+ * JOS VALIDATE - Validate a .jos document with the jos-core kernel
+ * Accepts 2.0.0, 1.1.0, 1.0.0 and 0.0.7 documents. Exit 0 valid, 2 invalid (also a valid document that --strict
+ * refuses: no objective, success criteria or guardrails written); 5 no kernel; 64 usage.
+ * Shows what jos-core infers (its `inferred` section, jos-core 2.0.0-rc.8): members the document does not write and
+ * the kernel applies, with their source, and what the document does not declare.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const kernel = require('../kernel');
+const ui = require('../ui');
+const { RULE } = ui;
+const { split } = require('../args');
+const intention = require('../intention');
+
+// What --strict requires the document itself to write: an entry of `inferred` at one of these pointers means it does not.
+const STRICT = ['/intention/objective', '/intention/success_criteria', '/guardrails'];
+const OPTIONS = ['--json', '--strict'];
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS VALIDATE${C.reset} // Validate .jos documents with jos-core
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos validate <file.jos> [--json] [--strict]
+  jos validate <folder> [--json] [--strict]           (D or D/.jos: the directory D)
+  jos validate [--json] [--strict] -- <file.jos>     (-- ends the options)
+
+${C.bold}Options:${C.reset}
+  --json    Print the validation result as JSON, with jos-core's "inferred" section
+  --strict  Also fail (exit 2) when the document does not write intention.objective,
+            intention.success_criteria and guardrails itself
+
+${C.bold}Checks:${C.reset}
+  UTF-8 and JSON syntax, forbidden keys, form detection (2.0.0, 1.1.0, 1.0.0, 0.0.7),
+  normalization to 2.0, schema, artifact id (art_<sha256>). Nothing runs.
+  A valid document's intention is shown as written: objective, success criteria
+  ("Done when"), avoid patterns and limits. "Inferred" lists what jos-core applies
+  that the document does not write (pointer, value, source: SPEC section or jos-core
+  default) and flags what it does not declare. The document alone is read: the
+  .jos/ chain of its folder is applied by jos run, not shown here.
+  A folder D (or D/.jos) is validated as a directory by jos-core (SPEC-2.0 9.1):
+  D/.jos/manifest.jos MUST be of kind directory (a 1.0.0 flow with
+  meta.labels.dotjos is accepted with a warning), every .jos under .jos/ is
+  validated, and the .jos/ chain above D may only restrict. jos run D refuses
+  the same manifests; --strict applies to the manifest.
+`;
+
+function isDirectory(p) {
+    try { return fs.statSync(p).isDirectory(); } catch (e) { return false; }
+}
+
+// A folder D (or D/.jos) is validated as the directory D by the kernel's validateDir, as `jos-core validate D` does:
+// its four layers, and a manifest that is not of kind directory is code 2 at /jos/kind, the answer of `jos run D`
+// (SPEC-2.0 §9.1, the 1.0.0 flow with meta.labels.dotjos accepted with a warning; readiness rc.7 pass 5 F-19).
+// --strict applies to the manifest, the document of the folder.
+function folder(out, err, k, given, dir, flags) {
+    let core;
+    try { core = kernel.need(k, ['validateDir', 'documentPath']); } catch (e) { return kernel.fail(e); }
+    const v = core.validateDir(dir, {});
+    const missing = flags.includes('--strict') && v.valid
+        ? STRICT.filter((p) => Object.prototype.hasOwnProperty.call(core.inferred(core.loadFile(core.documentPath(dir))), p)) : [];
+    const strictFail = () => {
+        err.fail('jos validate: --strict: the manifest of ' + given + ' does not declare ' + missing.map((p) => p.slice(1).replace('/', '.')).join(', '));
+        err.hint('write intention.objective, intention.success_criteria and guardrails in .jos/manifest.jos');
+        return 2;
+    };
+    if (flags.includes('--json')) {
+        ui.json(process.stdout, v);
+        if (missing.length) return strictFail();
+        return v.valid ? 0 : 2;
+    }
+    const { C } = out;
+    out.header('JOS VALIDATE', 'jos-core ' + k.version);
+    out.field('Folder', given);
+    for (const w of v.warnings) out.warn(w);
+    if (v.valid) {
+        out.ok('Valid directory', `(${v.files} documents, integrity ${v.integrity})`);
+        out.line();
+        if (missing.length) return strictFail();
+        out.ok(`${C.bold}VALIDATION PASSED`);
+        out.line();
+        return 0;
+    }
+    for (const e of v.errors) out.fail(e);
+    out.line();
+    out.fail(`${C.bold}VALIDATION FAILED`);
+    out.line();
+    return 2;
+}
+
+exports.execute = async (args) => {
+    const out = ui.printer(process.stdout);
+    const err = ui.printer(process.stderr);
+    const { C } = out;
+    const { flags, files, help } = split(args);
+    if (help) {
+        out.text(HELP(C));
+        return 0;
+    }
+    for (const f of flags) {
+        if (!OPTIONS.includes(f)) {
+            err.fail('jos validate: unknown option ' + f);
+            if (f === '--insecure' || f === '--verbose') err.hint('(removed in 5.0.0)');
+            return 64;
+        }
+    }
+    if (files.length !== 1) {
+        err.fail('jos validate: takes exactly one file');
+        err.hint('usage: jos validate <file.jos> [--json] [--strict]');
+        return 64;
+    }
+
+    let k;
+    let core;
+    try { k = kernel.locate(); core = kernel.need(k, ['inferred']); } catch (e) { return kernel.fail(e); }
+    const file = path.resolve(files[0]);
+    if (isDirectory(file)) return folder(out, err, k, files[0], file, flags);
+
+    let v;
+    let raw = null;
+    try {
+        raw = core.loadFile(file);
+        v = core.validate(raw);
+    } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        v = { valid: false, form: null, input_version: null, artifact: null, errors: e.errors, document: null };
+    }
+    // as `jos-core validate --json`: the section of the document alone, null when it is invalid
+    const inferred = v.valid ? core.inferred(raw) : null;
+    const missing = flags.includes('--strict') && inferred ? STRICT.filter((p) => Object.prototype.hasOwnProperty.call(inferred, p)) : [];
+    const strictFail = () => {
+        err.fail('jos validate: --strict: ' + files[0] + ' does not declare ' + missing.map((p) => p.slice(1).replace('/', '.')).join(', '));
+        err.hint('write intention.objective, intention.success_criteria and guardrails in the document');
+        return 2;
+    };
+
+    if (flags.includes('--json')) {
+        ui.json(process.stdout, Object.assign({}, v, { inferred }));
+        if (missing.length) return strictFail();
+        return v.valid ? 0 : 2;
+    }
+
+    out.header('JOS VALIDATE', 'jos-core ' + k.version);
+    out.field('Artifact', files[0]);
+    if (v.valid) {
+        out.ok('Valid', `(input ${v.form} ${v.input_version})`);
+        out.field('ID', v.artifact);
+        if (v.form === '0.0.7') {
+            out.warn('0.0.7 document, normalized to 2.0 in memory; the file is not rewritten');
+            // jos-core validate does not read the manifest (SPEC-2.0 §2.4, decision D4); jos run verifies it, --dry-run too
+            const ref = Object(raw.security).integrity_ref;
+            if (![undefined, null, ''].includes(ref)) {
+                out.warn('integrity_ref present: verified on run');
+                out.hint('validate does not read the manifest ' + JSON.stringify(ref) + '; jos run checks it before anything starts (also --dry-run), a mismatch is code 3');
+                out.hint('jos migrate ' + ui.shellArg(files[0]) + ' reseals it as a 2.0 document (integrity.hash)');
+            }
+        }
+        intention.intention(out, v.document);
+        intention.inferred(out, inferred);
+        out.line();
+        if (missing.length) {
+            out.fail(`${C.bold}VALIDATION FAILED`, '(--strict)');
+            out.line();
+            return strictFail();
+        }
+        out.ok(`${C.bold}VALIDATION PASSED`);
+        out.line();
+        return 0;
+    }
+    for (const e of v.errors) out.fail(e);
+    out.line();
+    out.fail(`${C.bold}VALIDATION FAILED`);
+    out.line();
+    return 2;
+};