@redue/cli 0.0.0-stage → 0.1.0-alpha.3

package/bin/redue.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawn,spawnSync} from 'node:child_process';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+import {discoverNodeProject} from '../src/node-onboarding.mjs';
+import {processAlive} from '../src/process-liveness.mjs';
+import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
+import {stateIdentity,userStateBase} from '../src/platform-state.mjs';
+import {findExecutable} from '../src/executable-lookup.mjs';
+import {readCachedStatus} from '../src/cached-state.mjs';
+import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
+import {renderStatus,renderExplain} from '../src/presentation.mjs';
+
+const productRoot=path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const engine=path.join(productRoot,'src','cli.mjs');
+const version=JSON.parse(fs.readFileSync(path.join(productRoot,'package.json'))).version;
+const help=`REDUE ${version}
+Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
+
+Commands:
+  init [--dry-run] [--workspace NAME] [--check KIND]
+                       Discover existing scripts; optionally select one workspace/check
+  start                Start the local observer
+  stop                 Stop this observer
+  status [--json|--short] Read conservative cached status
+  status --sync        Reconcile inputs and caller context before answering
+  explain [CHECK] [--json] Explain applicability (synchronized; may cost more than a rerun)
+  detail [CHECK] [--json]  Alias for explain
+  run CHECK            Execute one configured check and record its outcome
+  remove-state         Stop and remove only this configuration's owned local state
+
+No checks run in the background. Direct commands outside redue create no receipts.`;
+
+function error(message){console.error(`redue: ${message}`);process.exit(2);}
+const args=process.argv.slice(2);
+if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
+if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);process.exit(0);}
+const preferredConfig=path.resolve('redue.config.json');
+const legacyConfig=path.resolve('vstate.config.json');
+let configFile=fs.existsSync(preferredConfig)||!fs.existsSync(legacyConfig)?
+  preferredConfig:legacyConfig,stateOverride=null;
+for(let i=0;i<args.length;){
+  if(args[i]==='--config'||args[i]==='--state-dir'){
+    const flag=args[i],value=args[i+1];if(!value)error(`${flag} requires a path`);
+    if(flag==='--config')configFile=path.resolve(value);else stateOverride=path.resolve(value);
+    args.splice(i,2);
+  }else i++;
+}
+const command=args.shift();
+if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
+  error(`unknown command ${command||'<none>'}; use --help`);
+const json=args.includes('--json');
+const sync=args.includes('--sync');
+const dryRun=args.includes('--dry-run');
+const short=args.includes('--short');
+let workspaceSelection=null,checkSelection=null;
+if(command==='init')for(let i=0;i<args.length;){
+  if(args[i]==='--workspace'||args[i]==='--check'){
+    const flag=args[i],value=args[i+1];if(!value||value.startsWith('--'))error(`${flag} requires a name`);
+    if(flag==='--workspace')workspaceSelection=value;else checkSelection=value;
+    args.splice(i,2);
+  }else i++;
+}
+const check=['run','detail','explain'].includes(command)&&args[0]&&!args[0].startsWith('--')?args.shift():null;
+if(command==='run'&&!check)error('run requires a check name');
+if(args.some(value=>!['--json','--sync','--dry-run','--short'].includes(value)))error('unknown option; use --help');
+if(sync&&!['status','detail','explain'].includes(command))error('--sync is for status or detail');
+if(short&&(command!=='status'||json||sync))error('--short is a cached status option; do not combine it with --sync or --json');
+if(dryRun&&command!=='init')error('--dry-run is for init');
+
+if(command==='init'){
+  let discovery;try{discovery=discoverNodeProject(process.cwd());}
+  catch(e){error(e.message);}
+  if(workspaceSelection||checkSelection){
+    const chosen=discovery.checks.filter(row=>
+      (!workspaceSelection||row.config.workspace===workspaceSelection||
+        row.config.command?.[2]===workspaceSelection)&&
+      (!checkSelection||row.config.kind===checkSelection));
+    if(!chosen.length)error('no discovered check matches the selected workspace and kind');
+    discovery.checks=chosen;discovery.config.checks=chosen.map(row=>row.config);
+  }
+  const configured=fs.existsSync(configFile),unsupported=Boolean(discovery.observationIssue||
+    discovery.manager.issue&&!['npm','yarn','pnpm'].includes(discovery.manager.name)||
+    discovery.manager.name==='yarn'&&!discovery.manager.version);
+  const willWrite=!dryRun&&!configured&&!unsupported&&discovery.checks.length>0;
+  const summary={schema:1,repository:discovery.root,node:discovery.node,
+    package_manager:discovery.manager.name,version:discovery.manager.version,
+    installation_layout:discovery.manager.layout,
+    issue:discovery.observationIssue||discovery.manager.issue,workspaces:discovery.workspaces,
+    ambiguous:discovery.ambiguous,
+    checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
+      script:check.script||null,command:check.command||null,
+      workspace:check.workspace||null,level,reason})),config:configFile,
+    written:willWrite,existing:configured};
+  if(!json) {
+    console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
+      `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
+    if(summary.issue)console.log(`Boundary: ${summary.issue}`);
+    for(const row of summary.checks){
+      console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
+        `${{ready:'ready to qualify',recording:'recording-only',unsupported:'unsupported'}[row.level]||row.level}: ${row.reason}`);
+      if(row.script&&row.command)console.log(`    Recorded invocation: ${row.command.map(value=>
+        value==='@node'?'node':value.startsWith('@typescript-bin:')?
+          `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
+    }
+    for(const row of summary.ambiguous)
+      console.log(`  ${row.kind}: ambiguous scripts (${row.scripts.join(', ')}); choose one explicitly`);
+    if(!summary.checks.length)console.log('No useful existing verification scripts found.');
+    console.log(configured?`Existing ${configFile} left unchanged.`:
+      dryRun?`Preview only; ${configFile} was not written.`:
+        willWrite?`Writing ${configFile}; inspect it before running checks.`:'No configuration will be written.');
+  }
+  if(willWrite){
+    if(!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
+      error('init writes only at the repository root; use --config there or --dry-run');
+    fs.writeFileSync(configFile,JSON.stringify(discovery.config,null,2)+'\n',{flag:'wx'});
+    if(!json){console.log(`Created ${configFile}. No checks were executed.`);
+      console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
+      console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
+      console.log('Use redue status first. --sync can establish applicability, but may cost more than rerunning a cheap check.');}
+  } else if(unsupported&&!json)console.log(`No config written: ${summary.issue||'unsupported discovery boundary'}.`);
+  if(json)console.log(JSON.stringify({...summary,proposed_config:discovery.config}));
+  process.exit(0);
+}
+function printLifecycle(output,action,machine){
+  if(machine){process.stdout.write(output);return;}
+  let value;try{value=JSON.parse(output);}catch{process.stdout.write(output);return;}
+  if(action==='start'){
+    console.log(value.ready?'Observer ready.':'Observer started; checking inputs. Applicability stays UNVERIFIED until ready.');
+    console.log('Use redue status. Stop with redue stop.');
+  }else if(action==='remove-state')console.log(`Removed only REDUE-owned state: ${value.removed}`);
+  else console.log(value.ok?'Observer stopped. Historical evidence is retained.':
+    `Observer unavailable: ${value.reason||'not running'}. Previous evidence is not CURRENT.`);
+}
+// Owned-state maintenance must not need the checkout, its package manager,
+// or installed compiler to remain present. No command is run from this path.
+if(stateOverride&&['stop','remove-state'].includes(command)){
+  const runtime=path.join(stateOverride,'project-runtime-v1.json');
+  if(!fs.existsSync(runtime)){console.log('No REDUE state exists at this path.');process.exit(0);}
+  const result=spawnSync(process.execPath,[engine,runtime,command==='stop'?'stop':'uninstall'],
+    {cwd:os.tmpdir(),stdio:['inherit','pipe','inherit'],encoding:'utf8',env:process.env});
+  if(result.error)error(result.error.message);
+  if(result.stdout)printLifecycle(result.stdout,command,json);
+  process.exit(result.status??2);
+}
+let publicConfig;
+try{publicConfig=JSON.parse(fs.readFileSync(configFile,'utf8'));}
+catch(e){error(e.code==='ENOENT'?`no configuration at ${configFile}; run redue init from the project root, or use --config FILE`:`cannot read ${configFile}: ${e.message}`);}
+if(publicConfig.schema!==1)error('config schema must be 1');
+if(!Array.isArray(publicConfig.checks)||!publicConfig.checks.length)
+  error('config needs at least one explicitly defined check');
+for(const key of Object.keys(publicConfig))
+  if(!['schema','root','checks','packageManager'].includes(key))error(`unsupported config field ${key}`);
+if(check&&!publicConfig.checks.some(row=>row.name===check))error(`unknown check ${check}; use redue status to list configured checks`);
+const root=realObservedPath(path.resolve(path.dirname(configFile),publicConfig.root||'.'));
+const stateBase=userStateBase(process.platform,process.env,os.homedir());
+const state=stateOverride||path.join(stateBase,'vstate',
+  `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+
+    stateIdentity(configFile)).digest('hex').slice(0,16)}`);
+if(!/^(?:vstate|redue)-/.test(path.basename(state)))
+  error('--state-dir must name a dedicated redue-* directory outside the checkout (legacy vstate-* is also supported)');
+const runtimeFile=path.join(state,'project-runtime-v1.json');
+function which(name){
+  const found=findExecutable(name);
+  if(found)return found;
+  error(`cannot resolve executable ${name} on PATH`);
+}
+function token(value){
+  if(value==='@node')return process.execPath;
+  if(value==='@project')return root;
+  if(value.startsWith('@typescript-bin:')){
+    const dir=value.slice('@typescript-bin:'.length);
+    if(!dir||path.isAbsolute(dir)||dir.split('/').includes('..'))
+      error('TypeScript executable workspace path is unsafe');
+    const manifest=path.join(root,dir,'package.json');
+    let resolved;try{resolved=createRequire(manifest).resolve('typescript/package.json');}
+    catch{error('installed TypeScript compiler cannot be resolved');}
+    const compiler=path.join(path.dirname(realObservedPath(resolved)),'bin','tsc');
+    if(!withinPath(compiler,root)||!fs.existsSync(compiler))
+      error('TypeScript executable is outside the observed project');
+    return compiler;
+  }
+  if(value==='@vstate/npm-typecheck-probe')return path.join(productRoot,'src','npm-typecheck-probe.mjs');
+  if(value==='@vstate/typescript-contract-probe')return path.join(productRoot,'src','typescript-contract-probe.mjs');
+  if(value==='@vstate/yarn-workspace-typecheck-probe')return path.join(productRoot,'src','yarn-workspace-typecheck-probe.mjs');
+  if(value==='@vstate/pnpm-typecheck-probe')return path.join(productRoot,'src','pnpm-typecheck-probe.mjs');
+  if(value==='@vstate/toolchain-probe')return path.join(productRoot,'src','toolchain-probe.mjs');
+  if(value.startsWith('@which:'))return which(value.slice(7));
+  return value;
+}
+function argv(values,label){
+  if(!Array.isArray(values)||!values.length||values.some(v=>typeof v!=='string'||!v))
+    error(`${label} must be nonempty exact argv`);
+  return values.map(token);
+}
+const categories=['source','generated','installedDependencies','environment','toolchain','runtime',
+  'probeContinuity'];
+const checks=publicConfig.checks.map(check=>{
+  const allowed=['name','command','cwd','inputs','generatedInputs','installedInputs',
+    'allowedExternalRoots','probes','environment','coverage','coverageReview','coverageReasons',
+    'script','kind','qualification','workspace'];
+  for(const key of Object.keys(check))if(!allowed.includes(key))
+    error(`unsupported check field ${check.name}.${key}`);
+  for(const category of categories)if(check.coverage?.[category]&&
+    typeof check.coverageReview?.[category]!=='string')
+    error(`${check.name}: reviewed coverage ${category} needs a rationale`);
+  const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
+  if(check.script&&check.command&&!pnpmTypecheck)
+    error(`${check.name}: choose script or command, not both`);
+  const manager=publicConfig.packageManager;
+  if(check.script&&!['npm','yarn','pnpm'].includes(manager))
+    error(`${check.name}: script checks need supported npm, Yarn or pnpm packageManager`);
+  const scriptCommand=check.script&&!check.command?
+    [`@which:${manager}`,'run',check.script]:null;
+  const npmAutomatic=check.qualification==='typescript-noemit-v1';
+  const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
+  if(check.qualification&&!npmAutomatic&&!yarnWorkspace&&!pnpmTypecheck)
+    error(`${check.name}: unknown qualification contract`);
+  if(npmAutomatic&&(manager!=='npm'||check.cwd&&check.cwd!=='.'))
+    error(`${check.name}: automatic TypeScript qualification currently needs root npm script`);
+  if(yarnWorkspace&&(manager!=='yarn'||!check.workspace||check.cwd&&check.cwd!=='.'||
+    check.command?.length!==5||check.command[0]!=='@which:yarn'||
+    check.command[1]!=='workspace'||check.command[2]!==check.workspace||
+    check.command[3]!=='run'))
+    error(`${check.name}: Yarn workspace qualification needs its discovered workspace command`);
+  if(pnpmTypecheck&&(manager!=='pnpm'||!check.script||!check.command||
+    check.command[0]!=='@node'||
+    check.command[1]!==`@typescript-bin:${check.cwd||'.'}`||
+    check.workspace&&check.cwd==='.'||
+    !check.command.slice(2).every(value=>typeof value==='string'&&value)))
+    error(`${check.name}: pnpm qualification needs its discovered standalone TypeScript command`);
+  const reason=check.kind==='test'?'test runtime, transforms and cache inputs need review':
+    check.kind==='lint'?'lint plugins, config and resolver inputs need review':
+    check.kind==='build'?'build environment and generated inputs need review':
+    'check inputs need review';
+  const autoProbes=npmAutomatic?[['@node','@vstate/typescript-contract-probe',
+    '@project',check.script,'@which:npm']]:yarnWorkspace?
+    [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
+      check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
+    [['@node','@vstate/pnpm-typecheck-probe','@project',
+      check.workspace||'.',check.script]]:[];
+  const windowsContext=process.platform==='win32'?
+    ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
+  const autoEnvironment=npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+    'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
+    pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
+    {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
+      prefixes:['YARN_','COREPACK_','npm_config_','DYLD_','TSGO_'],
+      pathExecutables:['node','yarn'],executableIdentity:true}:pnpmTypecheck?
+    {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
+      prefixes:['PNPM_','COREPACK_','npm_config_','DYLD_','TSGO_'],
+      pathExecutables:['node'],executableIdentity:true}:{};
+  return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`),
+    cwd:check.cwd,inputs:check.inputs||[],generatedInputs:check.generatedInputs||[],
+    installedInputs:check.installedInputs||(
+      npmAutomatic?['node_modules/**']:[]),
+    allowedExternalRoots:check.allowedExternalRoots||[],
+    probes:[...(check.probes||[]),...autoProbes]
+      .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
+    environment:check.environment||autoEnvironment,coverage:check.coverage||{},
+    coverageReview:check.coverageReview||{},
+    coverageReasons:check.coverageReasons||Object.fromEntries(
+      categories.map(category=>[category,reason])),
+    qualification:check.qualification||null,script:check.script||null,
+    workspace:check.workspace||null,kind:check.kind||null};
+});
+const runtime={schema:1,provider:'declared-project@1',root,state,checks};
+try{assertOwnedStatePlacement(runtime);}catch(e){error(e.message);}
+const serialized=JSON.stringify(runtime,null,2)+'\n';
+const maintenance=command==='stop'||command==='remove-state';
+if(maintenance&&!fs.existsSync(runtimeFile)){
+  console.log(`No REDUE state exists for ${configFile}.`);
+  process.exit(0);
+}
+if(!maintenance)fs.mkdirSync(state,{recursive:true,mode:0o700});
+if(!maintenance&&fs.existsSync(runtimeFile)){
+  const previous=fs.readFileSync(runtimeFile,'utf8');
+  if(previous!==serialized){
+    const pidFile=path.join(state,'observer.lock','pid');
+    if(fs.existsSync(pidFile)){
+      const pid=Number(fs.readFileSync(pidFile));
+      if(processAlive(pid))error('config changed while observer is running; stop it before restarting with the new plan');
+    }
+    fs.writeFileSync(runtimeFile,serialized,{mode:0o600});
+  }
+}else if(!maintenance)fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});
+
+if(command==='status'&&!sync){
+  const value=readCachedStatus(state,publicConfig.checks);
+  console.log(json?JSON.stringify(value):renderStatus(value,{short}));
+  process.exit(0);
+}
+
+const details=command==='detail'||command==='explain';
+const internal=command==='remove-state'?'uninstall':
+  details?'sync':command==='status'&&sync?'sync':command;
+if(command==='run'){
+  const child=spawn(process.execPath,[engine,runtimeFile,internal,check,...(!json?['--human']:[])],
+    {stdio:['inherit','inherit','inherit','ipc'],env:process.env});
+  const forward=signal=>{if(child.exitCode!==null)return;
+    if(process.platform==='win32'&&child.connected)child.send({action:'cancel',signal});
+    else child.kill(signal);};
+  const interrupt=()=>forward('SIGINT'),terminate=()=>forward('SIGTERM');
+  process.on('SIGINT',interrupt);process.on('SIGTERM',terminate);
+  const outcome=await new Promise(resolve=>{
+    child.once('error',error=>resolve({error}));
+    child.once('close',(status,signal)=>resolve({status,signal}));
+  });
+  process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
+  if(outcome.error)error(outcome.error.message);
+  process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
+}
+const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+  {stdio:['inherit','pipe','inherit'],
+    encoding:'utf8',env:process.env});
+if(result.error)error(result.error.message);
+if(result.stdout){
+  if(['status','detail','explain'].includes(command)){
+    let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
+    if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
+    if(json)console.log(JSON.stringify(value));
+    else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
+  }else printLifecycle(result.stdout,command,json);
+}
+process.exit(result.status??1);

package/bin/vstate.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Compatibility entry point for local pre-release workflows.
+import './redue.mjs';

package/docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+For users:
+
+- [Install, initialize, run, and remove](user/getting-started.md)
+- [Supported projects and conservative boundaries](user/supported-projects.md)
+- [Configuration](user/configuration.md)
+- [Coding-agent decision policy](user/agents.md)
+- [JSON contract](user/json.md)
+- [Shell usage](user/shell.md)
+
+For contributors:
+
+- [Architecture](contributor/architecture.md)
+- [Observation and recovery](contributor/observation-recovery.md)
+- [Reproducible terminal demo](contributor/demo.md)
+- [Release procedure](contributor/releasing.md)
+
+[Historical acceptance evidence](acceptance/README.md) is retained separately.
+It records measured environments and limitations; it is not the getting-started guide.

package/docs/user/agents.md

@@ -0,0 +1,32 @@
+# Agent decision policy
+
+Use the CLI; no SDK or bespoke agent integration is required. Add these
+instructions to a session or project only with its owner's permission.
+
+1. Query ordinary `redue status --json` first.
+2. If a check has `freshness: "CURRENT"`, `result: "PASS"`, and
+   `reuse_eligible: true`, reuse it. Do not rerun merely for freshness.
+3. If STALE, run `redue run CHECK` when that verification is needed.
+4. If the historical `result` is FAIL, report it honestly. The human CLI calls
+   this FAILED; applicability is a separate field, never an excuse to call it green.
+5. If UNVERIFIED, inspect its reason. Use `status --sync --json` when establishing
+   applicability is worthwhile, or rerun the underlying check when cheaper/simpler.
+   Use `redue run CHECK` if a new receipt is wanted. Incomplete coverage can remain
+   UNVERIFIED even after success.
+6. Do not assume synchronization is cheaper than execution. There are no universal
+   package-manager or OS thresholds. Inexpensive checks may be cheaper to rerun.
+
+`redue explain CHECK --json` gives synchronized detail, including a known changed
+input when available. It has the same cost caveat as synchronized status.
+
+No previous conversation history is needed to read a persisted receipt. Still
+consider independent task-specific reasons to run verification: the configured
+check is not universal product correctness. Report additional uncaptured checks
+separately. Do not infer that an outer invocation's success proves a specific
+check ran or that an upstream cache was hit; inspect `target_provenance`.
+
+On a CLI error, unhealthy observation, or unavailable context, do not infer
+CURRENT. Do not delete state or reset receipts to make the output green.
+
+REDUE tells you what evidence exists and whether it still applies. It does not
+promise that establishing applicability is cheaper than every possible check.

package/docs/user/configuration.md

@@ -0,0 +1,57 @@
+# Configuration
+
+Prefer `redue init` over hand-authoring a qualified contract. A typical generated
+npm configuration is concise and portable:
+
+```json
+{
+  "schema": 1,
+  "root": ".",
+  "packageManager": "npm",
+  "checks": [{
+    "name": "typecheck",
+    "script": "typecheck",
+    "kind": "typecheck",
+    "qualification": "typescript-noemit-v1",
+    "inputs": ["package.json", "package-lock.json", "tsconfig*.json", "src/**"]
+  }]
+}
+```
+
+The exact inputs are derived from the detected project; use the emitted config,
+not this example to assert your project's coverage. Generated Yarn/pnpm workspace
+checks also identify the owning workspace and actual command. Large dependency
+relationships stay in local runtime state. `qualification` selects a supported
+validation recipe; it is not a blanket coverage assertion.
+
+Use `--config FILE` to select an external configuration. `root` is relative to
+that file. Runtime paths, resolved executables, local evidence, and sockets stay
+out of version-controlled configuration.
+
+## Arbitrary commands
+
+An unrecognized ecosystem can still record ordinary execution:
+
+```json
+{
+  "schema": 1,
+  "checks": [{
+    "name": "migration",
+    "command": ["@node", "tools/check-migrations.mjs"],
+    "inputs": ["migrations/**", "tools/check-migrations.mjs"]
+  }]
+}
+```
+
+Commands are exact argv, not shell text. Use `cwd` for a project-relative working
+directory. `@node`, `@project`, and `@which:NAME` resolve explicit invocation facts.
+Manual checks start recording-only: a plausible list of files is not proof of a
+complete input boundary. Do not copy coverage assertions from unrelated projects.
+
+Advanced explicit contracts may declare `generatedInputs`, `installedInputs`, narrow
+`allowedExternalRoots`, read-only `probes`, and relevant `environment`. These are
+reviewed escape hatches, not onboarding requirements. A coverage rationale cannot
+override unsupported storage, unresolved links, missing inputs, or observation failure.
+
+Changing commands, relevant configuration, installed material, or consumed inputs
+invalidates prior applicability. It does not erase historical execution outcomes.

package/docs/user/getting-started.md

@@ -0,0 +1,127 @@
+# Install and use REDUE
+
+Requirements: Git; Node 22 or newer with npm; an existing local JS/TS checkout
+with its dependencies installed. Linux additionally needs `python3`. Supported
+storage is local APFS on macOS, NTFS on Windows, and the documented native Linux
+filesystems. Network/FUSE/overlay mounts are not qualified Linux storage.
+Node 22 and 24 are the release-test matrix; newer majors are not yet acceptance claims.
+
+Install the public alpha:
+
+```sh
+npm install --global @redue/cli@alpha
+redue --version
+```
+
+For an unpublished source candidate, run `npm ci` and `npm pack --json`, then
+install the exact filename reported by npm with `npm install --global ./<filename>`.
+
+These commands also work in PowerShell (use `npm.cmd`/`redue.cmd` when a local
+PowerShell script policy blocks generated `.ps1` shims; do not change policy).
+No build step, custom installer, account, or login service is required. Installing
+npm dependencies uses the registry; normal local observation does not require network.
+
+For a reversible user-owned prefix, POSIX shells:
+
+```sh
+npm install --global --prefix "$HOME/.local/redue-alpha" @redue/cli@alpha
+export PATH="$HOME/.local/redue-alpha/bin:$PATH"
+```
+
+PowerShell:
+
+```powershell
+$reduePrefix = Join-Path $env:LOCALAPPDATA 'redue-alpha-install'
+npm.cmd install --global --prefix $reduePrefix @redue/cli@alpha
+$env:PATH = "$reduePrefix;$env:PATH"
+redue.cmd --help
+```
+
+These PATH changes affect only the current shell. Alternatively invoke the
+installed entry point directly: POSIX `node "$HOME/.local/redue-alpha/lib/node_modules/@redue/cli/bin/redue.mjs"`;
+Windows `node "$reduePrefix/node_modules/@redue/cli/bin/redue.mjs"`.
+
+## Moving from alpha.1
+
+If the personal-scope alpha.1 package is installed, stop the project's observer
+and replace that package before installing the canonical command:
+
+```sh
+redue stop
+npm uninstall --global @msiric/redue
+npm install --global @redue/cli@alpha
+```
+
+Use the same `--prefix` on both npm commands if your installation has a custom
+prefix. Uninstalling the package does not remove local verification evidence;
+`redue remove-state` is a separate, explicit action. Alpha.1 remains available as
+historical software and is superseded for package identity, not a runtime defect.
+
+## First project
+
+From the project root:
+
+```sh
+redue init --dry-run
+redue init
+redue start
+redue run typecheck
+redue status
+redue explain typecheck
+```
+
+Use a check actually printed by `init`. For a workspace:
+`redue init --workspace @example/package --check typecheck`.
+Initialization previews detected commands and qualification confidence before writing
+`redue.config.json`. An existing config is never overwritten. No checks are run and
+no dependencies installed. A missing/unsupported boundary is explained.
+
+“Ready to qualify” means REDUE has a supported recipe whose prerequisites will be
+validated. It is not a receipt. “Recording-only” can record PASS/FAIL without claiming
+reusability. Qualification can change when configuration or installation changes.
+
+`run` streams normal output and preserves execution environment and cancellation.
+For the narrow pnpm TypeScript contract, `init` explicitly shows the direct installed
+compiler invocation it selects; other scripts run through the package manager.
+Only use configs and probes from trusted repositories: these execute local code.
+
+`status` is cached and conservative. `status --sync` and `explain` revalidate caller
+context and may execute read-only probes. Synchronization can be slower than a cheap
+check, especially on Windows. Choose deliberately. A timeout is UNVERIFIED, not green.
+
+## Lifecycle and removal
+
+`start` starts this config's owned observer, or reports that it is already running.
+If already running, use `status`; do not create a second state directory just to
+start another observer. Startup may report initialization before inputs are ready.
+`stop` stops that observer and retains historical evidence. After restart, observation
+is reconciled before reuse.
+
+```sh
+redue stop
+redue start
+redue remove-state
+npm uninstall --global @redue/cli
+```
+
+For an isolated installation, use the same `--prefix` on uninstall. Remove state
+**before** uninstalling the command. No broad recursive deletion command is needed.
+`remove-state` checks its ownership marker and stops only that observer. It does not
+remove project files, dependencies, another tool's watches, or other REDUE configurations.
+To remove project configuration, inspect and delete `redue.config.json` yourself.
+
+Runtime state is separate from durable project config. Legacy directory spelling is
+retained for compatibility, not copied into your config:
+
+| OS | Default state base |
+| --- | --- |
+| macOS | `~/Library/Application Support/vstate/` |
+| Linux | `$XDG_STATE_HOME/vstate/`, otherwise `~/.local/state/vstate/` |
+| Windows | `%LOCALAPPDATA%/vstate/` |
+
+A checkout/config identity selects a dedicated child directory. Use
+`--state-dir /your/owned/redue-project-state` to choose a dedicated directory outside
+all observed roots; its basename must start with `redue-` or legacy `vstate-`.
+For a removed checkout, `redue --state-dir /your/owned/redue-project-state remove-state`
+still works without rebuilding its compiler/configuration. Ownership/active-run conflicts
+are actionable errors, never resolved merely by deleting an old lock.

package/docs/user/json.md

@@ -0,0 +1,59 @@
+# Alpha JSON interface (schema 1)
+
+Use `status --json` for cached state, `status --sync --json` for caller-aware
+applicability, and `explain CHECK --json` for selected synchronized detail.
+`detail` remains an alias. Successful reads emit one JSON object, no human prose.
+
+```json
+{
+  "schema": 1,
+  "state": "stale",
+  "current": 0, "stale": 1, "failed": 0, "observed_failed": 0, "unverified": 0,
+  "checks": [{
+    "name": "typecheck",
+    "result": "PASS",
+    "freshness": "STALE",
+    "reason": "src/main.ts changed",
+    "changed_inputs": ["src/main.ts"],
+    "reuse_eligible": false,
+    "invocation": {"runId": "opaque-run-id", "status": "exited", "exitCode": 0, "durationMs": 940}
+  }],
+  "observation": {"healthy": true}
+}
+```
+
+Stable-enough-for-alpha fields:
+
+| Field | Contract |
+| --- | --- |
+| `checks[].name` | Configured check identity. |
+| `result` | Historical `PASS`, `FAIL`, or null. A failed invocation is not green even with CURRENT applicability. |
+| `freshness` | `CURRENT`, `STALE`, or `UNVERIFIED`, independent of result. |
+| `reuse_eligible` | True only for qualified, applicable passing evidence. Never derive permission to reuse from outcome alone. Missing means false. |
+| `reason` | Human explanation; not a stable machine enum. Do not parse it to authorize reuse. |
+| `changed_inputs` | Known changed relevant paths when available, possibly only the first difference; empty/missing is not proof of no changes. |
+| `invocation` | Null without a receipt; otherwise run ID, completion `status`, duration, exit code/signal when known. Status distinguishes exited, interrupted, and start/capture failure. |
+| `target_provenance` | Available target evidence. Unknown is not executed or cache-hit. |
+| `observation.healthy` | False means no check is reusable. Additional reason/phase diagnostics may appear. |
+| `state` | Aggregate lowercase current/stale/failed/unverified (and runtime pending states where applicable). Use per-check fields for decisions. |
+
+Counts cover the whole configuration even when `explain CHECK` filters `checks`.
+`failed` counts applicable failures; `observed_failed` preserves historical failures
+regardless of applicability. Fields not listed here are diagnostic and may evolve.
+Ignore unknown fields; reject unknown schema versions. These responses contain local
+paths/check names and must not be uploaded automatically.
+
+`init --json` returns discovery levels (`ready`, `recording`, `unsupported`),
+reasons, workspace ownership, `written`, and `proposed_config`. Ready is not PASS.
+`init --dry-run --json` writes no config and runs no check.
+
+Read commands normally exit 0 even when the evidence is not current. Errors exit
+nonzero; synchronized transport failures may still return conservative JSON.
+Usage/configuration errors go to stderr and are not guaranteed JSON. Never treat
+a failed read as authority from a previously cached answer.
+
+`run CHECK --json` preserves ordinary command stdin/stdout/stderr and appends a
+JSON summary. **Its stdout is not a JSON-only stream.** Query status/details after
+completion for machine-readable evidence. Normal check exit codes are preserved;
+interruption/process-start failures are nonzero. REDUE retains metadata and receipts,
+not arbitrary terminal output. The CLI does not infer tests executed from prose.