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

package/bin/redue.mjs

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decision-profile.mjs';
+traceBase({...traceContext(),request:traceId(),work:'client'});
+mark('client.loaded');
+import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
+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,pathToFileURL} from 'node:url';
+import {processAlive} from '../src/process-liveness.mjs';
+import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
+import {discoverConfig,projectState,canonicalConfig} from '../src/project-location.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] [--recipe typescript-direct]
+                       Discover existing scripts; optionally select one workspace/check
+  agent setup codex|claude [--dry-run|--apply] [--json]
+  agent doctor [codex|claude] [--json]
+  agent remove codex|claude [--dry-run|--apply] [--json]
+                       Connect project instructions; explicit setup only
+  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===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
+  // Runs before config discovery: the hook must exit 0 on every failure,
+  // because Claude Code treats exit 2 as a block.
+  const {runClaudeHook}=await import('../src/claude-hook.mjs');
+  await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
+}
+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);}
+let configFile=null,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();
+try{configFile??=command==='init'||stateOverride&&['stop','remove-state'].includes(command)?
+  path.resolve(fs.existsSync('redue.config.json')||!fs.existsSync('vstate.config.json')?'redue.config.json':'vstate.config.json'):discoverConfig();}
+catch(e){error(e.message);}
+if(fs.existsSync(path.dirname(configFile)))configFile=canonicalConfig(configFile);
+if(command==='agent'){
+  // Loaded on demand: onboarding and agent setup are not on the run/status path.
+  const {agentCommand}=await import('../src/agent-integration.mjs');
+  try{await agentCommand(args,{configFile,stateOverride,entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  // Exiting with piped output still queued truncates it (8 KB on macOS).
+  await new Promise(resolve=>process.stdout.write('',resolve));
+  process.exit(0);
+}
+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,recipeSelection=null;
+if(command==='init')for(let i=0;i<args.length;){
+  if(args[i]==='--workspace'||args[i]==='--check'||args[i]==='--recipe'){
+    const flag=args[i],value=args[i+1];if(!value||value.startsWith('--'))error(`${flag} requires a name`);
+    if(flag==='--workspace')workspaceSelection=value;else if(flag==='--recipe')recipeSelection=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'){
+  const {discoverNodeProject}=await import('../src/node-onboarding.mjs');
+  let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
+  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==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':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('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
+      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);}
+  mark('client.engine_submit');
+  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 state=stateOverride||projectState(root,configFile);
+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==='@typescript-compiler:.'){
+    try{return directCompiler(root,{verify:false}).entry;}catch(e){error(`direct compiler unavailable: ${e.code||e.message}`);}
+  }
+  if(value==='@vstate/direct-typescript-probe')return path.join(productRoot,'src','direct-typescript-probe.mjs');
+  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 npmDirect=check.qualification===directQualification;
+  const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
+  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect)
+    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&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck)
+    error(`${check.name}: unknown qualification contract`);
+  if(npmDirect&&(manager!=='npm'||!check.script||check.cwd&&check.cwd!=='.'||
+    JSON.stringify(check.command)!==JSON.stringify(['@node','@typescript-compiler:.','--noEmit'])))
+    error(`${check.name}: direct recipe requires its explicit local compiler command`);
+  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=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',check.script]]: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=npmDirect?directEnvironment: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||npmDirect?['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,
+    ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
+    ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
+    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;
+// On macOS and Linux the engine runs in this process, which saves a Node startup
+// on every run; its own handlers receive SIGINT and SIGTERM. Windows keeps a
+// child engine because cancellation reaches it over IPC.
+if(command==='run'&&process.platform!=='win32'){
+  process.argv=[process.argv[0],engine,runtimeFile,internal,check,...(!json?['--human']:[])];
+  await import(pathToFileURL(engine).href);
+}else 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));
+}else{
+  mark('client.engine_submit');
+  const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+    {stdio:['inherit','pipe','inherit'],
+      encoding:'utf8',env:traceEnvironment()});
+  mark('client.engine_complete',{exit:result.status,signal:result.signal});
+  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,21 @@
+# Documentation
+
+For users:
+
+- [Install, initialize, run, and remove](user/getting-started.md)
+- [Fixed-build opt-in development pilot](user/pilot.md)
+- [Supported projects and conservative boundaries](user/supported-projects.md)
+- [Configuration](user/configuration.md)
+- [Connect coding agents and apply the 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,253 @@
+# Agent decision policy
+
+Use the CLI with explicit project-local activation below, or add this policy to a
+generic agent's instructions with the project owner's permission.
+
+1. If fresh execution is already required, execute it; do not synchronize merely
+   to confirm an irrelevant reuse opportunity. Use `redue run CHECK` when recording
+   the configured check. An explicit npm-script request still requires npm.
+2. For reuse of the explicitly configured direct compiler recipe
+   (`qualification: "npm-typescript-direct-v1"`, direct compiler command; receipt
+   `verification_recipe: "npm-direct-typescript@1"`), query once:
+   `redue --config CONFIG status --sync --json`. Do not infer a recipe from its name.
+   Cached status cannot establish its caller context. In mixed configurations,
+   assess each check's contract separately; this is not a global sync-first policy.
+3. For other/unknown recipes, query ordinary `status --json` first and decide whether
+   synchronization is worthwhile. Ordinary status and `--short` remain cheap inspection.
+4. Reuse only schema 1, healthy observation and the selected check's CURRENT/PASS
+   with `reuse_eligible: true`. Missing eligibility means false. A historical FAIL
+   is never green evidence. Do not rerun eligible evidence merely for freshness.
+5. STALE requires execution when verification is needed. UNVERIFIED requires an
+   honest choice of synchronization, permitted execution or reporting the limitation.
+   Recording-only success can remain UNVERIFIED. A deliberate cheap-check rerun is
+   permitted; there are no universal platform/package-manager timing thresholds.
+6. Use a successful synchronized response for the current decision without repeated
+   sync/explain calls unless edits, context changes or missing information require it.
+   Do not loop until green or use an earlier response after a later query fails.
+
+`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`.
+
+Reassess at the decision point after edits or context changes; previous CURRENT is
+not continuing authorization. A status exit code of zero is not proof of CURRENT.
+An empty changed-input list does not prove nothing changed. `run CHECK --json`
+streams check output; use a subsequent status/explain query for structured evidence.
+Explicit fresh-execution requests still require execution.
+
+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.
+
+## Connect once (experimental)
+
+Alpha.5 and later support opt-in project-local activation and direct
+TypeScript evidence, with fresh-session reuse demonstrated for Codex CLI 0.160.1
+and subsequent 0.162.0 trials on macOS under the documented owner-approved checkout/state/socket route. CLI
+mechanics are tested on macOS/Linux/Windows; model behavior is not claimed for
+every host/platform or sandbox policy. Claude setup/removal mechanics are tested,
+but Claude behavior and cross-host reuse remain untested. Reuse is not guaranteed,
+and the existing subsecond example establishes no meaningful net time saving.
+
+After installing REDUE and running `redue init` in a trusted project:
+
+```sh
+redue agent setup codex --dry-run
+redue agent setup codex --apply
+# Or: redue agent setup claude --apply
+redue agent doctor
+```
+
+Start a fresh agent session in this checkout, then give it your ordinary task.
+Interactive setup shows the changes and asks before applying; noninteractive
+setup requires `--apply`. `--dry-run` never writes. Installing REDUE or running
+`init` does not connect an agent automatically. Setup does not start an observer
+or execute verification. Use `redue start` when you want observation.
+
+## Claude Code typecheck hook
+
+`redue agent setup claude --apply` also adds a PreToolUse hook to
+`.claude/settings.local.json`. The hook needs a local REDUE install, so it is
+per-developer; keep that file out of commits. Other settings in the file are kept,
+but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
+`redue agent remove claude --apply` removes only the entry REDUE added.
+
+The hook skips an exact rerun of a configured typecheck: a check with
+`kind: "typecheck"` or named `typecheck`. It matches these commands, run from the
+project root:
+
+- `redue run CHECK`
+- `npm run SCRIPT`, when the check has an npm script
+- `npx tsc --noEmit`, for the direct-TypeScript recipe
+- the check's `command`, when it has no `@` tokens
+
+Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
+`| tail -N` or `| head -N`. Nothing else matches. Each form has its own `if`
+rule, so other Bash commands never start the hook.
+
+On a match, the hook runs `redue status --sync --json` with a 2-second timeout.
+It blocks the command only when the check is CURRENT, PASS and
+`reuse_eligible: true`. The message names the check and the receipt's run ID. Every
+other result allows the command: STALE, UNVERIFIED, FAILED, a timeout, an error, or
+a missing `redue`. A command that starts with `REDUE_FORCE=1` always runs.
+
+When the check is not CURRENT but the observer answered for it, the hook rewrites
+the command to `redue run CHECK` and allows it, keeping any `2>&1` and
+`| tail`/`| head` suffix. It adds `--config FILE` when the config is not
+`redue.config.json`. The run is recorded, so the next identical command can be
+skipped. Without a healthy answer (timeout, error, no observer) the command runs
+as typed. Claude Code still applies deny and ask rules to the rewritten command.
+
+Limits:
+
+- The hook judges its own environment, which Claude Code passes to it. The Bash
+  tool can add variables from your shell profile. The hook cannot see those.
+- Commands run from a subdirectory, or combined with `&&`, `;` or other pipes,
+  are not matched.
+- Only the Bash tool is covered, not PowerShell.
+- Run setup again after you rename a check or script.
+- The rewrite is allowed without a permission prompt, even where the original
+  command would have prompted.
+
+## Update an existing connection
+
+Installing a newer package does **not** rewrite project instructions. From the
+same project and installation, stop every observer using that installation before
+replacing it. Keep the original config and state selection; do not create a second
+config or delete receipts. Example for a default npm installation/config:
+
+```sh
+redue --config redue.config.json stop
+npm install --global @redue/cli@alpha
+redue --config redue.config.json agent setup codex --dry-run
+redue --config redue.config.json agent setup codex --apply
+redue --config redue.config.json start
+redue --config redue.config.json status --sync --json
+```
+
+Use the **same `--prefix`** as the existing npm installation when it has a custom
+prefix, and invoke its corresponding `redue` binary. Keep your actual config path
+on every command. For Claude, select `claude` in both setup commands. Preserve any
+existing `--state-dir` on lifecycle/status commands; setup does not embed custom
+state locations, so retain the documented generic instruction path if your agent
+workflow needs an explicit custom state. PowerShell may use the existing
+`npm.cmd`/`redue.cmd` shims without changing script policy.
+
+Review the preview before applying. Intact owned content updates; unrelated text
+is preserved. Edited managed content is refused, not overwritten. If refused,
+review/reconcile those edits deliberately; do not remove ownership records to force
+an update. Restart the observer with its original selection even if you postpone
+updating instructions, then start a **fresh agent session** after a successful
+update. Setup creates no verification receipt.
+
+Managed project metadata can itself be an observed input. Prior receipts remain
+historical evidence, but setup may make them STALE or UNVERIFIED. Reassess normally
+and run required checks; an upgrade is not a promise that existing receipts remain
+CURRENT. Do not suppress that invalidation or reset state.
+
+Codex gets a short managed section in project `AGENTS.md` and
+`.agents/skills/redue-verification/SKILL.md`. Claude Code gets a managed section
+in `CLAUDE.md` and `.claude/skills/redue-verification/SKILL.md`. Each uses the same
+policy source; detailed guidance is loaded when verification is relevant. Small
+ownership records in `.redue/agents/` support safe updates/removal. These are
+portable project files, not receipts; review and commit them if the team wants
+this integration. Do not ignore just the ownership records while committing the
+managed files.
+
+Existing instruction text is retained. Review it in the preview: setup cannot
+prove arbitrary natural-language policies are consistent. Conflicts such as a
+root `AGENTS.override.md` or an alternative `.claude/CLAUDE.md` are reported
+instead of silently outranked. Global/managed policies, nested instructions,
+Codex instruction-size limits, skill disabling, and host-specific exclusions
+still apply. Complete the host's ordinary trust/permission prompts yourself;
+REDUE never grants tool permission. Sandboxed hosts may need owner-approved access
+to the checkout, owned state directory and local observer socket. A healthy daemon
+does not establish that the agent can reach it; doctor reports control access
+separately. Do not disable sandbox protections to make this work. Do not use a mode that disables project
+instructions and expect automatic activation.
+
+Control access is not simply file-read permission. The observer can reconcile and
+write its owned index, run the trusted configuration's probes in its own process
+context, reload receipts, and stop. Approve only the intended checkout/state and
+endpoint, accounting for that authority. Doctor sends only a bounded metrics
+request; it does not synchronize or run these probes.
+
+`agent doctor [codex|claude] --json` is read-only. It distinguishes command lookup,
+config resolution, cached observer health, a bounded read-only control-access probe,
+managed-file integrity, detected host
+version, and loading guidance. `behavior_verified: false` is deliberate: intact
+files do not prove the agent followed them. For Claude, doctor reports whether the
+typecheck hook is installed. Doctor neither
+executes checks nor starts observers, reconciles inputs, or installs a host.
+
+Doctor separates missing/unreadable state, a missing or refused endpoint, an
+explicit EPERM/EACCES access denial, and timeout/invalid response. A denial does
+not identify whether OS permissions or host policy caused it. A live PID and
+healthy cached observation do not prove control access. An older cached response
+without receipt-selection validation gets stop/start guidance. Windows command
+shims whose target has not been established are reported as unknown, not a
+proven installation mismatch.
+
+Codex CLI 0.160.1 on macOS can use the approved exact observer-socket route while
+other sockets and direct network access remain denied. Its independent sessions
+receive different proxy values. Ordinary npm invocation is **not** equivalent
+across arbitrary notifier state: REDUE withholds automatic npm-launcher
+reuse. Do not change proxy settings or permissions to get green evidence.
+
+The separate opt-in [direct local compiler recipe](direct-typescript.md) does not
+run npm. Its reviewed compiler implementation does not consume npm/proxy settings;
+a digest preserves their observed provenance without treating them as compiler
+inputs. Other execution context remains strict, and cached status still cannot
+assert caller eligibility. An explicit user request for `npm run typecheck` still
+requires npm execution; direct compiler evidence is not a substitute.
+
+Before model trials, run `redue agent doctor --json` and
+`redue status --sync --json` inside the agent's actual command boundary. The
+contributor helper `test/acceptance/codex-preflight.mjs --config FILE --check CHECK`
+performs the same bounded, read-only decision check and exits 2 when reuse is not
+eligible. It neither executes verification nor grants access; synchronization
+may run configured probes. A successful outside-shell result is insufficient.
+
+Use the same setup command after an upgrade; it updates intact managed
+content idempotently. Changed skill text or a changed managed block causes a
+conflict instead of an overwrite. Review your edits before retrying.
+
+```sh
+redue agent remove codex --dry-run
+redue agent remove codex --apply
+redue agent remove claude --apply
+```
+
+Removal deletes only intact REDUE-owned content for that host. Unrelated text,
+other integrations, project config, receipts and installed dependencies remain.
+User edits outside the managed section survive. Modified managed content is left
+intact with a diagnostic; compare it with a preview and resolve manually. Empty
+parent directories may remain. If the selected config has been deleted, restore
+it or manually remove only the marked REDUE section, that host's skill, and its
+`.redue/agents/HOST.json` ownership record after review. Do not delete an entire
+instruction file containing user content.
+
+## Project identity and generic agents
+
+Commands from nested directories search toward the nearest Git root. If more than
+one configuration applies, select one with `--config FILE`; REDUE refuses to guess.
+The generated instruction names its project-relative configuration and applies it
+to status/run/explain. External configs or custom machine-local `--state-dir`
+setups should use a reviewed generic instruction instead of committing absolute
+paths. Other worktrees and remote containers have separate local evidence.
+
+For another agent, put a short instruction in its documented project mechanism:
+“Before deciding whether configured verification needs repeating, read REDUE's
+agent policy, identify the selected recipe and use its decision query for the intended config.
+Apply the schema/health/reuse rules.” Supply this document and the
+[JSON contract](json.md) as the detailed policy. Review the agent's actual tool
+trace before calling activation verified. A local npm installation does not install
+REDUE in a remote container; that environment needs its own CLI, checkout,
+dependencies and state. There is no cloud/team receipt synchronization.