@thebackstoryis/engineering-with-ai 0.3.1-beta.0 → 0.3.1

package/src/dashboard-preferences.mjs

@@ -1,8 +1,4 @@
-import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync} from 'node:fs';
-import {dirname,relative,resolve,isAbsolute} from 'node:path';
-import {createHash,randomUUID} from 'node:crypto';
-import YAML from 'yaml';
-import {projectPaths} from './paths.mjs';
+import {readProjectDocument,editProjectDocument} from './config-document.mjs';
 
 export const DASHBOARD_VIEWS=Object.freeze([
   ['portfolio','Portfolio','Compare work and decisions across several projects.','Across projects and teams'],
@@ -27,54 +23,17 @@ export function normaliseDashboardPreferences(value={}){
   return {sidebar_collapsed:value.sidebar_collapsed??false,optional_views:Object.fromEntries(DASHBOARD_VIEWS.map(v=>[v.id,optional[v.id]??false]))};
 }
 export function premiumPersonasActive(premium){return premium?.access==='available'&&premium?.installed===true&&premium?.verified===true;}
-const digest=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
-function safePath(paths){
-  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
-  if(rel.startsWith('..')||isAbsolute(rel))fail('Dashboard preferences require a safe project configuration path.',403);
-  let cursor=parent;
-  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Dashboard preferences cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Dashboard preferences require a safe project configuration path.',403);cursor=next;}
-  const stat=lstatSync(paths.configPath);
-  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Dashboard preferences require a regular, non-symbolic configuration file.',403);
-  if(stat.size>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
-  return stat;
-}
-function snapshot(paths){
-  const stat=safePath(paths);let fd;
-  try{
-    fd=openSync(paths.configPath,constants.O_RDONLY|constants.O_NOFOLLOW);
-    const opened=fstatSync(fd);if(opened.ino!==stat.ino||opened.dev!==stat.dev)fail('Project configuration changed. Reload the settings and try again.',409);
-    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
-    const document=YAML.parseDocument(bytes.toString('utf8'));
-    if(document.errors.length)fail('The project configuration contains invalid YAML. Fix it before editing dashboard preferences.',422);
-    let config;try{config=document.toJS({maxAliasCount:100});}catch{fail('The project configuration cannot be safely read.',422);}
-    if(config?.schema!=='ewai.project/v1'||config?.specs?.root!==paths.specsRelative)fail('The project configuration and SPECS locator must agree before editing dashboard preferences.',422);
-    return {document,preferences:normaliseDashboardPreferences(config.dashboard),digest:digest(bytes),mode:stat.mode&0o777};
-  }finally{if(fd!==undefined)closeSync(fd);}
-}
-function guarded(operation){try{return operation();}catch(error){if(error.dashboardPreferenceError)throw error;fail('Dashboard preferences could not be read or saved. Check the project configuration and file permissions.',409);}}
+function snapshot(projectRoot){const state=readProjectDocument(projectRoot);return {...state,preferences:normaliseDashboardPreferences(state.config.dashboard)};}
+function guarded(operation){try{return operation();}catch(error){if(error.dashboardPreferenceError||error.configurationError)throw error;fail('Dashboard preferences could not be read or saved. Check project configuration and file permissions.',409);}}
 function projection(state){return {schema:'ewai.dashboard-preferences/v1',digest:state.digest,preferences:state.preferences,views:DASHBOARD_VIEWS};}
-export function readDashboardPreferences(projectRoot){return guarded(()=>projection(snapshot(projectPaths(projectRoot))));}
+export function readDashboardPreferences(projectRoot){return guarded(()=>projection(snapshot(projectRoot)));}
 export function saveDashboardPreferences(projectRoot,input){
   return guarded(()=>{
     keys(input,['confirmed','expectedDigest','preferences']);
     if(input.confirmed!==true)fail('Confirm the dashboard preference changes before saving.');
-    if(!/^sha256:[a-f0-9]{64}$/.test(String(input.expectedDigest??'')))fail('Reload dashboard preferences before saving.');
     if(!record(input.preferences))fail('Provide the dashboard preferences to save.');
-    const preferences=normaliseDashboardPreferences(input.preferences),paths=projectPaths(projectRoot);
-    safePath(paths);const lock=paths.configPath+'.dashboard-preferences.lock';let lockFd,tempFd,temporary;
-    try{
-      try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Dashboard preferences are being edited. Retry after that save finishes.',409);}
-      const before=snapshot(paths);if(before.digest!==input.expectedDigest)fail('Project configuration changed. Reload the settings and try again.',409);
-      before.document.set('dashboard',preferences);const content=before.document.toString();
-      temporary=paths.configPath+'.dashboard-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
-      writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
-      if(snapshot(paths).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.',409);
-      safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
-      return projection(snapshot(paths));
-    }finally{
-      if(tempFd!==undefined)closeSync(tempFd);
-      if(temporary)unlinkSync(temporary);
-      if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}
-    }
+    const preferences=normaliseDashboardPreferences(input.preferences);
+    const state=editProjectDocument(projectRoot,input.expectedDigest,document=>document.set('dashboard',preferences));
+    return projection({...state,preferences:normaliseDashboardPreferences(state.config.dashboard)});
   });
 }

package/src/delivery.mjs

@@ -10,6 +10,7 @@ import {
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
+import {codingPolicyDigest,assertCodingPolicyFresh,assertModelPolicy} from './coding-providers.mjs';
 import { updateIntentDeliveryState, validateIntentStateCopies } from './intents.mjs';
 import { loadProjectConfig } from './project.mjs';
 import { readRuntimeIntent } from './runtime/intents.mjs';
@@ -38,7 +39,7 @@ import { validatePhaseArtefacts } from './delivery-artifacts.mjs';
 import {
   canonicalValidationProvider,
   effectiveValidationConfig,
-  VALIDATION_PROVIDERS,
+  SUPPORTED_VALIDATION_PROVIDERS,
   validationCheckpointForPhase,
 } from './validation-config.mjs';
 import {
@@ -431,7 +432,7 @@ function normaliseDeliveryValidation(paths, state) {
   const legacyProviders = [...new Set(
     (Array.isArray(state.providers) ? state.providers : [])
       .map(canonicalValidationProvider)
-      .filter((provider) => VALIDATION_PROVIDERS.includes(provider)),
+      .filter((provider) => SUPPORTED_VALIDATION_PROVIDERS.includes(provider)),
   )];
 
   for (const [checkpointName, checkpoint] of Object.entries(validation.checkpoints)) {
@@ -638,6 +639,10 @@ function recordOwnedExternalValidationCycle(projectRoot, slug, phaseId, input) {
   const phase = findTrackedPhase(state, phaseId);
   if (phase.status !== 'running') throw new Error(`Phase ${phaseId} is not running.`);
   if (!phase.validation) throw new Error(`Phase ${phaseId} is not an external-validation checkpoint.`);
+  if(state.validation?.codingPolicyDigest){
+    const {config}=loadProjectConfig(projectRoot);
+    assertCodingPolicyFresh(state.validation.codingPolicyDigest,codingPolicyDigest(config.coding_providers));
+  }
 
   const provider = String(input.provider ?? '').trim().toLowerCase();
   if (!phase.validation.providers.includes(provider)) {
@@ -646,6 +651,7 @@ function recordOwnedExternalValidationCycle(projectRoot, slug, phaseId, input) {
     );
   }
   const outcome = String(input.outcome ?? '').trim().toLowerCase();
+  assertModelPolicy(provider,state.validation?.codingPolicy);
   if (!['pass', 'issues'].includes(outcome)) {
     throw new Error('Validation cycle outcome must be pass or issues.');
   }

package/src/discovery.mjs

@@ -20,6 +20,7 @@ import { loadProjectConfig } from './project.mjs';
 import {
   VALIDATION_CHECKPOINTS,
   VALIDATION_PROVIDERS,
+  SUPPORTED_VALIDATION_PROVIDERS,
   normaliseValidationConfig,
 } from './validation-config.mjs';
 import { publishLifecycleEventSafely } from './runtime/lifecycle-hooks.mjs';
@@ -218,7 +219,7 @@ function normaliseOrganisationBlueprint(value) {
 
 function discoveryValidation(raw, configured) {
   const rawProviders = raw.providers ?? Object.fromEntries(
-    VALIDATION_PROVIDERS
+    SUPPORTED_VALIDATION_PROVIDERS
       .filter((provider) => raw[provider] !== undefined)
       .map((provider) => [provider, raw[provider]]),
   );
@@ -852,7 +853,7 @@ function renderDiscoveryEvidence(answers, detected, standards, compliance, compl
     ['AI features', answers.assurance.aiFeatures],
     ['Accessibility obligations', answers.assurance.accessibility],
     ['Availability', answers.assurance.availability],
-    ...VALIDATION_PROVIDERS.map((provider) => [
+    ...Object.keys(answers.validation.external.providers).map((provider) => [
       `${provider[0].toUpperCase()}${provider.slice(1)} external validation`,
       `${answers.validation.external.providers[provider].state}; ${
         answers.validation.external.providers[provider].enabled ? 'enabled' : 'disabled'
@@ -879,7 +880,7 @@ function renderProjectConstraints(answers, completedAt) {
 }
 
 function renderApproach(answers, completedAt) {
-  const providerLines = VALIDATION_PROVIDERS.map((provider) => {
+  const providerLines = Object.keys(answers.validation.external.providers).map((provider) => {
     const setting = answers.validation.external.providers[provider];
     return `- **${provider[0].toUpperCase()}${provider.slice(1)}:** ${setting.state}; ${setting.enabled ? 'enabled' : 'disabled'}`;
   }).join('\n');
@@ -1250,7 +1251,7 @@ export async function runDiscoveryInterview(projectRoot, io = {}) {
     const availability = await askEnum(rl, 'Availability expectation', [...AVAILABILITY_LEVELS], 'standard');
     const configuredProviders = config.validation?.external?.providers ?? {};
     const validationProviders = {};
-    for (const provider of VALIDATION_PROVIDERS) {
+    for (const provider of [...VALIDATION_PROVIDERS,...(configuredProviders.grok?['grok']:[])]) {
       const label = `${provider[0].toUpperCase()}${provider.slice(1)}`;
       validationProviders[provider] = await askEnum(
         rl,

package/src/grok-credentials.mjs

@@ -0,0 +1,95 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,realpathSync,readFileSync,mkdirSync,writeFileSync,renameSync,unlinkSync,rmSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {resolve,relative,isAbsolute} from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+
+const messages={
+ 'grok-credential-invalid':'Provide a valid xAI API key using the private setup form or hidden terminal prompt.',
+ 'grok-credential-input':'Use the supported credential action and confirm the change.',
+ 'grok-credential-unsafe-storage':'Private credential storage is unsafe or unavailable. Repair its permissions or use XAI_API_KEY in the launching environment.',
+ 'grok-credential-invalid-storage':'The saved credential could not be read safely. Repair the private credential file before continuing.',
+ 'grok-credential-stale':'The saved credential changed. Refresh its status and try again.',
+ 'grok-credential-busy':'Another credential change is running. Retry after it finishes.',
+ 'grok-credential-missing':'No Grok key is configured. Use private credential setup or XAI_API_KEY in the launching environment.',
+ 'grok-key-rejected':'The key was not accepted. Check the key and its API permissions, then try again. The previous saved key was retained.',
+ 'grok-check-rate-limited':'xAI limited the authentication check. Wait before trying again. The previous saved key was retained.',
+ 'grok-check-unavailable':'The authentication check could not complete. Check your connection and try again. The previous saved key was retained.',
+};
+function fail(code,statusCode=400){const error=new Error(messages[code]??messages['grok-credential-input']);error.code=code;error.statusCode=statusCode;throw error;}
+function key(value){if(typeof value!=='string'||value.length>512||!/^xai-[A-Za-z0-9_-]{16,508}$/.test(value.trim()))fail('grok-credential-invalid');return value.trim();}
+function request(input,fields){if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(k=>!fields.includes(k))||input.confirmed!==true||typeof input.expectedRevision!=='string'||input.expectedRevision.length>80)fail('grok-credential-input');}
+function stat(path){try{return lstatSync(path);}catch(error){if(error.code==='ENOENT')return null;fail('grok-credential-unsafe-storage');}}
+function owned(s){return s&&!s.isSymbolicLink()&&(process.getuid===undefined||s.uid===process.getuid());}
+function paths(options={},create=false){
+ const declaredHome=resolve(options.home??homedir());
+ const root=stat(declaredHome);if(!owned(root)||!root.isDirectory()||(root.mode&0o022))fail('grok-credential-unsafe-storage');
+ let home,project;try{home=realpathSync(declaredHome);if(options.projectRoot)project=realpathSync(resolve(options.projectRoot));}catch{fail('grok-credential-unsafe-storage');}
+ const folder=resolve(home,'.ewai/credentials'),file=resolve(folder,'grok.json');
+ if(project){const rel=relative(project,file);if(rel===''||(!isAbsolute(rel)&&rel!=='..'&&!rel.startsWith('../')))fail('grok-credential-unsafe-storage');}
+ const canonicalRoot=stat(home);if(!owned(canonicalRoot)||canonicalRoot.ino!==root.ino||canonicalRoot.dev!==root.dev)fail('grok-credential-unsafe-storage');
+ for(const path of [resolve(home,'.ewai'),folder]){
+  let s=stat(path);if(!s&&create){try{mkdirSync(path,{mode:0o700});}catch(error){if(error.code!=='EEXIST')fail('grok-credential-unsafe-storage');}s=stat(path);}
+  if(s&&(!owned(s)||!s.isDirectory()||(s.mode&(path===folder?0o077:0o022))))fail('grok-credential-unsafe-storage');
+ }
+ return {folder,file,location:JSON.stringify([home,root.dev,root.ino])};
+}
+function stored(options={}){
+ const {file,location}=paths(options),before=stat(file);if(!before)return {value:null,signature:'missing',location};
+ if(process.platform==='win32'||!owned(before)||!before.isFile()||before.nlink!==1||(before.mode&0o077)||before.size>4096)fail('grok-credential-unsafe-storage');
+ let fd;try{
+  fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);const bytes=readFileSync(fd),after=fstatSync(fd),current=stat(file);
+  if(bytes.length>4096||!current||before.ino!==after.ino||before.dev!==after.dev||before.mtimeMs!==after.mtimeMs||after.ino!==current.ino||after.mtimeMs!==current.mtimeMs)fail('grok-credential-unsafe-storage');
+  let value;try{value=JSON.parse(bytes.toString('utf8'));}catch{fail('grok-credential-invalid-storage');}
+  if(value?.schema!=='ewai.grok-credential/v1'||typeof value.revision!=='string'||!/^[a-f0-9-]{36}$/.test(value.revision)||Object.keys(value).some(k=>!['schema','revision','apiKey'].includes(k)))fail('grok-credential-invalid-storage');
+  try{key(value.apiKey);}catch{fail('grok-credential-invalid-storage');}
+  return {value,location,signature:JSON.stringify([after.dev,after.ino,after.mtimeMs,after.ctimeMs,createHash('sha256').update(bytes).digest('hex')])};
+ }catch(error){if(error.code?.startsWith('grok-'))throw error;fail('grok-credential-unsafe-storage');}finally{if(fd!==undefined)closeSync(fd);}
+}
+function environment(options){const env=options.env??process.env;return env.XAI_API_KEY?key(env.XAI_API_KEY):null;}
+export function grokCredentialStatus(options={}){
+ const {value}=stored(options),override=environment(options);
+ return {schema:'ewai.grok-credential-status/v1',provider:'grok',configured:Boolean(override||value),saved:Boolean(value),source:override?'environment':value?'saved':'missing',revision:value?.revision??'missing',storage:'owner-only-local-file',encrypted:false,storageSupported:process.platform!=='win32',authority:'credentials-only'};
+}
+export function resolveGrokApiKey(options={}){const override=environment(options);return override??stored(options).value?.apiKey??null;}
+function predecessor(input,options,expected){const current=stored(options);if((current.value?.revision??'missing')!==input.expectedRevision||(expected&&(current.signature!==expected.signature||current.location!==expected.location)))fail('grok-credential-stale',409);return current;}
+function mutation(options,operation){
+ if(process.platform==='win32')fail('grok-credential-unsafe-storage');
+ const {folder}=paths(options,true),lock=resolve(folder,'.grok.lock');
+ try{mkdirSync(lock,{mode:0o700});}catch(error){fail(error.code==='EEXIST'?'grok-credential-busy':'grok-credential-unsafe-storage',409);}
+ const identity=lstatSync(lock);
+ try{return operation();}finally{const current=stat(lock);if(owned(current)&&current.isDirectory()&&current.ino===identity.ino)rmSync(lock,{recursive:true});}
+}
+async function authenticate(apiKey,options={}){
+ const controller=new AbortController();let timer;
+ try{
+  const timeout=Math.min(10000,Math.max(10,options.timeoutMs??10000));
+  const response=await Promise.race([(options.fetchImpl??fetch)('https://api.x.ai/v1/models',{method:'GET',headers:{authorization:'Bearer '+apiKey},redirect:'manual',signal:controller.signal}),new Promise((_,reject)=>{timer=setTimeout(()=>{controller.abort();reject(Error('deadline'));},timeout);})]);
+  // Discard provider bodies, including errors. They are not safe evidence.
+  if(response.body)void response.body.cancel().catch(()=>{});
+  if(response.status===200)return {status:'verified',code:'grok-authentication-verified',message:'xAI authentication check passed. No output was generated; credit and coding readiness remain unverified.'};
+  const code=[401,403].includes(response.status)?'grok-key-rejected':response.status===429?'grok-check-rate-limited':'grok-check-unavailable';return {status:'failed',code,message:messages[code]};
+ }catch{return {status:'failed',code:'grok-check-unavailable',message:messages['grok-check-unavailable']};}
+ finally{clearTimeout(timer);controller.abort();}
+}
+export async function checkGrokConnection(options={}){
+ const apiKey=resolveGrokApiKey(options);
+ if(!apiKey)return {...grokCredentialStatus(options),status:'failed',code:'grok-credential-missing',message:messages['grok-credential-missing']};
+ return {...grokCredentialStatus(options),...await authenticate(apiKey,options)};
+}
+export async function configureGrokCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision','apiKey']);const apiKey=key(input.apiKey);environment(options);const previous=predecessor(input,options);
+ const check=await authenticate(apiKey,options);if(check.status!=='verified')fail(check.code);
+ mutation(options,()=>{
+  predecessor(input,options,previous);const {file}=paths(options,true),temporary=file+'.'+randomUUID()+'.tmp';
+  try{writeFileSync(temporary,JSON.stringify({schema:'ewai.grok-credential/v1',revision:randomUUID(),apiKey})+'\n',{flag:'wx',mode:0o600});paths(options);predecessor(input,options,previous);renameSync(temporary,file);}
+  catch(error){if(error.code?.startsWith('grok-'))throw error;fail('grok-credential-unsafe-storage');}
+  finally{if(stat(temporary))unlinkSync(temporary);}
+ });
+ return {...grokCredentialStatus(options),check,message:'Grok key checked and saved for your account on this computer. No work started.'};
+}
+export function removeGrokCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision']);environment(options);const previous=predecessor(input,options);
+ mutation(options,()=>{const current=predecessor(input,options,previous);if(current.value)unlinkSync(paths(options).file);});
+ const status=grokCredentialStatus(options);return {...status,message:status.source==='environment'?'Saved key removed. XAI_API_KEY still supplies the active credential.':'Saved Grok key removed. No work started.'};
+}
+export function safeGrokCredentialError(error){const code=Object.hasOwn(messages,error?.code)?error.code:'grok-credential-input';return {error:messages[code],code};}

package/src/install.mjs

@@ -31,11 +31,12 @@ function availableClaudeAgents() {
     .sort();
 }
 
-function selectedHosts(host, home) {
+function selectedHosts(host, home, grokHome) {
   if (host !== 'auto') return [host];
   const hosts = [];
   if (existsSync(resolve(home, '.codex'))) hosts.push('codex');
   if (existsSync(resolve(home, '.claude'))) hosts.push('claude');
+  if (existsSync(grokHome)) hosts.push('grok');
   if (
     existsSync(resolve(home, '.gemini/antigravity-cli'))
     || existsSync(resolve(home, '.gemini/config'))
@@ -43,13 +44,15 @@ function selectedHosts(host, home) {
   return hosts.length ? hosts : ['codex'];
 }
 
-function skillDestinationRoot({ scope, host, home, projectRoot }) {
+function skillDestinationRoot({ scope, host, home, projectRoot, grokHome }) {
   if (scope === 'project') {
     if (!projectRoot) throw new Error('Project installation requires projectRoot');
+    if (host === 'grok') return resolve(projectRoot, '.grok/skills');
     return host === 'claude'
       ? resolve(projectRoot, '.claude/skills')
       : resolve(projectRoot, '.agents/skills');
   }
+  if (host === 'grok') return resolve(grokHome, 'skills');
   return host === 'claude'
     ? resolve(home, '.claude/skills')
     : host === 'antigravity'
@@ -103,9 +106,11 @@ export function install(options = {}) {
   if (!['global', 'project'].includes(scope)) throw new Error(`Unsupported install scope: ${scope}`);
   if (!['copy', 'link'].includes(mode)) throw new Error(`Unsupported install mode: ${mode}`);
 
-  const hosts = selectedHosts(options.host ?? 'auto', home);
+  // Explicit fixture homes never inherit the real machine's GROK_HOME.
+  const grokHome=resolve(options.grokHome ?? (options.home===undefined ? (options.env??process.env).GROK_HOME : undefined) ?? resolve(home,'.grok'));
+  const hosts = selectedHosts(options.host ?? 'auto', home, grokHome);
   for (const host of hosts) {
-    if (!['codex', 'claude', 'antigravity'].includes(host)) throw new Error(`Unsupported agent host: ${host}`);
+    if (!['codex', 'claude', 'antigravity', 'grok'].includes(host)) throw new Error(`Unsupported agent host: ${host}`);
   }
 
   const results = [];
@@ -115,6 +120,7 @@ export function install(options = {}) {
       scope,
       host,
       home,
+      grokHome,
       projectRoot: options.projectRoot ? resolve(options.projectRoot) : ''
     });
     mkdirSync(destinationRoot, { recursive: true });

package/src/project.mjs

@@ -4,6 +4,7 @@ import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import {normaliseDashboardPreferences} from './dashboard-preferences.mjs';
+import {normaliseCodingProviders} from './coding-providers.mjs';
 import { projectPaths } from './paths.mjs';
 import { premiumPersonaLearningAction } from './companion-opening.mjs';
 import { initializeRuntime } from './runtime/database.mjs';
@@ -360,11 +361,11 @@ export function configureValidationCheckpoint(projectRoot, checkpoint, update) {
 }
 
 export function externalValidationStatus(config, orchestrator = 'manual') {
-  const effective = effectiveValidationConfig(config, orchestrator);
+  const effective = validationStatus(config, orchestrator);
   const selected = new Set(
     Object.values(effective.checkpoints).flatMap((checkpoint) => checkpoint.validators),
   );
-  return VALIDATION_PROVIDERS.map((validator) => ({
+  return Object.keys(effective.providers).map((validator) => ({
     validator,
     state: effective.providers[validator].state,
     enabled: effective.providers[validator].enabled,
@@ -374,6 +375,12 @@ export function externalValidationStatus(config, orchestrator = 'manual') {
 }
 
 export function validationStatus(config, orchestrator = 'manual') {
+  // Settings inspection has no coding-agent identity. Resolve independent
+  // roles only for an actual delivery host; phase dispatch still uses the
+  // strict effective configuration and cannot claim independence from manual.
+  if(orchestrator==='manual'&&config.coding_providers){
+    return {...effectiveValidationConfig(config.validation,orchestrator),roleResolution:'requires-orchestrator'};
+  }
   return effectiveValidationConfig(config, orchestrator);
 }
 
@@ -406,6 +413,7 @@ export function loadProjectConfig(projectRoot) {
   }
   config.validation = normaliseValidationConfig(config.validation);
   config.dashboard = normaliseDashboardPreferences(config.dashboard);
+  if(config.coding_providers!==undefined)config.coding_providers=normaliseCodingProviders(config.coding_providers);
   return { config, paths };
 }
 

package/src/runtime/afk-conductor.mjs

@@ -18,9 +18,12 @@ import {
 } from './execution-leases.mjs';
 import { addActivityEvent } from './work.mjs';
 import {
-  AFK_PROVIDERS, buildProviderInvocation, commandAvailable, invokeProvider, providerCommand,
+  SUPPORTED_AFK_PROVIDERS, buildProviderInvocation, commandAvailable, invokeProvider, providerCommand, captureProviderIdentity, prepareGrokBuildProvider,
 } from './provider-adapters.mjs';
 import { prepareContextPack } from './context-assembly.mjs';
+import {readCodingPolicy, resolveCodingProviders, assertCodingPolicyFresh, assertModelPolicy} from '../coding-providers.mjs';
+import {readAutonomyPolicy} from '../autonomy.mjs';
+import {prepareGrokTaskEvidence,assertGrokTaskEvidenceFresh} from './grok-provider.mjs';
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const workerPath = resolve(moduleDir, '../afk-worker.mjs');
@@ -101,9 +104,10 @@ function event(projectRoot, run, summary, details = '', eventType = 'progress',
 
 function configuredProviders(config) {
   const status = validationStatus(config, 'manual');
-  return AFK_PROVIDERS.filter((provider) => {
+  return SUPPORTED_AFK_PROVIDERS.filter((provider) => {
     const setting = status.providers[provider];
-    return setting.state === 'available' && setting.enabled && commandAvailable(providerCommand(provider));
+    return setting?.state === 'available' && setting.enabled && commandAvailable(providerCommand(provider))
+      && (provider!=='grok'||prepareGrokBuildProvider('implementation').status==='requires-conformance');
   });
 }
 
@@ -283,15 +287,35 @@ export function preflightAfkRun(projectRoot, slug, options = {}) {
   if (!ready.length && !(graphCheck?.completedTasks?.length === graph?.tasks?.length)) failures.push('No AFK task is ready to execute.');
 
   const available = configuredProviders(config);
+  const coding=readCodingPolicy(root);
+  let approved=available;
+  if(options.autonomy&&coding.policy){const policy=readAutonomyPolicy(root);if(policy.status!=='current'||policy.grant.digest!==options.autonomy.grantDigest)failures.push('The approved autonomy grant changed.');
+    approved=available.filter(p=>policy.grant?.scope.providers.includes(p));}
   const requested = String(options.provider ?? 'auto');
-  const providers = requested === 'auto'
+  let providers = requested === 'auto'
     ? available
     : requested.split(',').map((value) => value.trim()).filter(Boolean);
   for (const provider of providers) {
-    if (!AFK_PROVIDERS.includes(provider)) failures.push(`Unknown AFK provider: ${provider}.`);
+    if (!SUPPORTED_AFK_PROVIDERS.includes(provider)) failures.push(`Unknown AFK provider: ${provider}.`);
     else if (!available.includes(provider)) failures.push(`${provider} is not both enabled in SPECS/pipeline.yaml and installed in this terminal.`);
   }
-  if (!providers.length) failures.push('No configured and installed Claude, Codex, or Antigravity CLI is available.');
+  let roles=null,providerIdentities=[],implementationProviders=[];
+  if(coding.policy){try{
+    if(requested!=='auto'&&coding.policy.primary!=='existing'&&coding.policy.primary!=='auto'
+      && !providers.includes(coding.policy.primary))throw new Error('The requested provider conflicts with the saved primary. Recommended: update provider settings or use --provider auto.');
+    providers=providers.filter(p=>coding.policy.pool.includes(p)&&approved.includes(p));
+    const first=resolveCodingProviders({...coding.policy,secondary:'off',tertiary:'off'},
+      {available,allowedProviders:approved,orchestrator:providers[0]});
+    roles=resolveCodingProviders(coding.policy,{available,allowedProviders:approved,orchestrator:first.primary??providers[0]});
+    implementationProviders=coding.policy.primary==='existing'?providers.filter(orchestrator=>{
+      try{resolveCodingProviders(coding.policy,{available,allowedProviders:approved,orchestrator});return true;}catch{return false;}
+    }):[roles.primary];
+    if(!implementationProviders.length)throw new Error('No eligible coding agent can satisfy the independent review roles. Recommended: choose a primary and distinct reviewers.');
+    providers=[...new Set([...implementationProviders,...roles.reviewers])];
+    if(providers.some(p=>!approved.includes(p)))throw new Error('The selected provider is outside the approved pool.');
+    for(const provider of providers){assertModelPolicy(provider,coding.policy);providerIdentities.push(captureProviderIdentity(provider));}
+  }catch(error){failures.push(error.message);}}
+  if (!providers.length) failures.push('No configured and installed coding CLI is available. Recommended: enable and install a provider, then repeat preflight.');
   const requestedParallel = Number(options.maxParallel ?? graph?.parallelism?.max_parallel_tasks ?? 1);
   if (!Number.isInteger(requestedParallel) || requestedParallel < 1) failures.push('maxParallel must be a positive integer.');
   const maxParallel = Math.max(1, Math.min(
@@ -308,6 +332,7 @@ export function preflightAfkRun(projectRoot, slug, options = {}) {
     parentBranch: graph?.parent_branch ?? '',
     topology,
     providers,
+    ...(coding.policy?{codingPolicy:coding.policy,codingPolicyDigest:coding.policyDigest,codingRoles:roles,implementationProviders,providerIdentities}:{}),
     readyTasks: ready,
     maxParallel,
     graphCheck,
@@ -365,6 +390,8 @@ export function startAfkRun(projectRoot, slug, options = {}) {
       status: 'starting',
       desiredState: 'running',
       providers: preflight.providers,
+      ...(preflight.codingPolicy?{codingPolicy:preflight.codingPolicy,codingPolicyDigest:preflight.codingPolicyDigest,
+        codingRoles:preflight.codingRoles,implementationProviders:preflight.implementationProviders,providerIdentities:preflight.providerIdentities}:{}),
       maxParallel: preflight.maxParallel,
       timeoutMs: Number(options.timeoutMs ?? 45 * 60 * 1000),
       createdAt: now(),
@@ -436,10 +463,12 @@ export function resumeAfkRun(projectRoot, runId, options = {}) {
     || options.autonomy?.runId !== run.autonomy.runId || options.autonomy?.grantDigest !== run.autonomy.grantDigest
     || typeof options.dependencies?.authority !== 'function')) throw new Error('Autonomous AFK resume requires the same bounded foreground authority context.');
   if (processAlive(run.pid)) throw new Error('AFK conductor is already running.');
+  assertRunProviderFresh(paths.projectRoot,run);
   const preflight = preflightAfkRun(paths.projectRoot, run.slug, {
     provider: run.providers.join(','),
     maxParallel: run.maxParallel,
     ignoreRunId: run.id,
+    autonomy: options.autonomy,
   });
   if (preflight.status !== 'ready') throw new Error(`AFK recovery preflight blocked: ${preflight.failures.join(' ')}`);
   if (run.autonomy) options.dependencies.authority({ stage: 'prepare', mode: 'command' });
@@ -479,9 +508,10 @@ export function prepareAfkContext(projectRoot, task, repository, options = {}) {
   const review = options.mode === 'review';
   const implementationCommit = String(options.implementationCommit ?? '').trim();
   const taskContent = JSON.stringify(task);
-  const rules = review
+  let rules = review
     ? `TESTS_FIRST Read tests before implementation. Read cited standards from ${specsRoot}. Review implementation commit ${implementationCommit}. Check the diff, exact task contract, write_set, desired outcome, stop conditions, test evidence, correctness, standards, security and scope. Do not edit files. End with exactly one line: VERDICT: PASS or VERDICT: FAIL.`
     : `You are an EWAI Build worker in an isolated Git worktree. Read standards from ${specsRoot} and tests before implementation. Repository ${repository.name} (${repository.role}). Work only inside write_set. Run only allowed_commands. Stop on every stop_condition. Make the smallest code and test change. Do not create SPECS records, commit, merge, change delivery state or update phase status. AUTHORITY_NONE. Finish with files changed and commands run.`;
+  if(options.evidenceCandidates?.length)rules += ' For this isolated Grok worker, read the complete source-standard and recorded-check sections supplied in this context. Host paths and Git history are inaccessible. Use the supplied exact commit diff for review. Do not execute commands: the conductor runs approved checks and owns commits. Read tests from the declared file snapshot before implementation.';
   const ruleMarkers = review
     ? ['TESTS_FIRST', implementationCommit, 'VERDICT: PASS or VERDICT: FAIL', 'Do not edit files']
     : ['AUTHORITY_NONE', 'Work only inside write_set', 'Do not create SPECS records', 'Do not create SPECS records, commit, merge, change delivery state or update phase status'];
@@ -513,19 +543,20 @@ export function prepareAfkContext(projectRoot, task, repository, options = {}) {
         requiredMarkers: ruleMarkers.filter(Boolean),
         selectionReason: review ? 'Tests-first review and exact verdict are mandatory.' : 'Write, command and delivery authority boundaries are mandatory.',
       },
+      ...(options.evidenceCandidates ?? []),
     ],
   });
 }
 
-function taskPrompt(projectRoot, task, repository) {
-  const pack = prepareAfkContext(projectRoot, task, repository, { mode: 'implementation' });
+function taskPrompt(projectRoot, task, repository, evidence) {
+  const pack = prepareAfkContext(projectRoot, task, repository, { mode: 'implementation',evidenceCandidates:evidence?.candidates });
   if (pack.status !== 'ready') throw new Error(`AFK Build context is not ready: ${pack.reason}.`);
   return pack.modelContext;
 }
 
-function reviewPrompt(projectRoot, task, implementationCommit) {
+function reviewPrompt(projectRoot, task, implementationCommit, evidence) {
   const pack = prepareAfkContext(projectRoot, task, { name: task.repo, role: 'review' }, {
-    mode: 'review', implementationCommit, repositoryRevision: implementationCommit,
+    mode: 'review', implementationCommit, repositoryRevision: implementationCommit,evidenceCandidates:evidence?.candidates,
   });
   if (pack.status !== 'ready') throw new Error(`AFK review context is not ready: ${pack.reason}.`);
   return pack.modelContext;
@@ -619,6 +650,15 @@ function taskState(run, task, update = {}) {
   run.tasks[task.id] = { ...(run.tasks[task.id] ?? {}), id: task.id, ...update, updatedAt: now() };
 }
 
+function assertRunProviderFresh(projectRoot,run) {
+  if(!run.codingPolicyDigest)return;
+  assertCodingPolicyFresh(run.codingPolicyDigest,readCodingPolicy(projectRoot).policyDigest);
+  for(const identity of run.providerIdentities??[]){
+    if(captureProviderIdentity(identity.provider).identityDigest!==identity.identityDigest)
+      throw new Error('Provider identity changed. Recheck capabilities before continuing.');
+  }
+}
+
 async function invokeControlled(projectRoot, run, task, invocation, invoke = invokeProvider) {
   const paths = pathsFor(projectRoot, run.id), controller = new AbortController();
   const key = controlKey(projectRoot, run.id), controls = runningControls.get(key) ?? new Set();
@@ -628,6 +668,7 @@ async function invokeControlled(projectRoot, run, task, invocation, invoke = inv
     try {
       if (requireRun(projectRoot, run.id).run.desiredState === 'cancelled') controller.abort();
       authorityChecks.get(run)?.({ stage: 'check', mode: invocation.mode ?? 'command' });
+      if(run.codingPolicyDigest)assertCodingPolicyFresh(run.codingPolicyDigest,readCodingPolicy(projectRoot).policyDigest);
     }
     catch (error) { authorityError = error; controller.abort(); }
   };
@@ -636,12 +677,18 @@ async function invokeControlled(projectRoot, run, task, invocation, invoke = inv
     guard();
     if (authorityError) throw authorityError;
     authorityChecks.get(run)?.({ stage: 'dispatch', mode: invocation.mode ?? 'command' });
+    const identity=(run.providerIdentities??[]).find(value=>value.provider===invocation.provider);
+    const evidence=invocation.grokEvidence;
+    const checkIdentity=()=>{if(identity&&captureProviderIdentity(invocation.provider).identityDigest!==identity.identityDigest)throw new Error('Provider identity changed. Recheck capabilities before continuing.');
+      if(invocation.provider==='grok')assertGrokTaskEvidenceFresh(evidence,invocation.mode);};
+    checkIdentity();
     // Persist uncertainty before the launch. A dead conductor must not leave
     // an old true flag that lets resume abandon a still-running worker's lease.
     run.executionStopped = false;
     saveRun(paths, run);
     timer = setInterval(guard, 50);
-    const result = await invoke(invocation, { signal: controller.signal, onStart(pid) {
+    const result = await invoke(invocation, { signal: controller.signal, beforeAccept(){guard();if(authorityError)throw authorityError;
+      authorityChecks.get(run)?.({stage:'accept',mode:invocation.mode??'command'});checkIdentity();}, onStart(pid) {
       taskState(run, task, { pid });
       run.activeWorkers = [...(run.activeWorkers ?? []).filter(worker => worker.taskId !== task.id), { taskId: task.id, pid }];
       saveRun(paths, run);
@@ -650,6 +697,7 @@ async function invokeControlled(projectRoot, run, task, invocation, invoke = inv
     if (result.executionStopped === true) run.activeWorkers = (run.activeWorkers ?? []).filter(worker => worker.taskId !== task.id);
     else run.unconfirmedExecution = true;
     if (authorityError) throw authorityError;
+    checkIdentity();
     if (run.unconfirmedExecution) throw new Error('AFK execution is not confirmed stopped; recovery is required.');
     run.executionStopped = (run.activeWorkers ?? []).length === 0;
     saveRun(paths, run);
@@ -791,12 +839,15 @@ async function implementTask(projectRoot, run, task, provider, dependencies = {}
     taskState(run, task, { status: 'implementing' });
     saveRun(paths, run);
     event(projectRoot, run, `Agent implementing ${task.id}.`, `${provider} · ${task.name}`);
+    const implementationEvidence=provider==='grok'?prepareGrokTaskEvidence(projectRoot,worktree,task,{mode:'implementation',commands:[red]}):null;
     const invocation = buildProviderInvocation(provider, {
       cwd: worktree,
-      prompt: taskPrompt(projectRoot, task, repository),
+      prompt: taskPrompt(projectRoot, task, repository,implementationEvidence),
+      grokEvidence:implementationEvidence,
       task,
       timeoutMs: run.timeoutMs,
       mode: 'implementation',
+      codingPolicy:run.codingPolicy,policyDigest:run.codingPolicyDigest,policyRoot:projectRoot,
     });
     invocation.logPath = resolve(logRoot, 'implementation.log');
     const result = await invokeControlled(projectRoot, run, task, invocation, invoke);
@@ -840,16 +891,25 @@ async function implementTask(projectRoot, run, task, provider, dependencies = {}
     git(worktree, ['commit', '-m', `feat(${run.slug}): implement ${task.id}`]);
     const implementationCommit = git(worktree, ['rev-parse', 'HEAD']);
 
-    const reviewer = run.providers.find((candidate) => candidate !== provider) ?? provider;
+    const resolvedReviewers=run.codingPolicy?resolveCodingProviders(run.codingPolicy,{available:run.providers,allowedProviders:run.providers,orchestrator:provider}).reviewers:null;
+    const reviewers = resolvedReviewers?.length?resolvedReviewers:[run.providers.find((candidate) => candidate !== provider) ?? provider];
+    let review,reviewer;
+    const reviewResults=[];
+    for(const selectedReviewer of reviewers){
+    reviewer=selectedReviewer;
+    const reviewEvidence=reviewer==='grok'?prepareGrokTaskEvidence(projectRoot,worktree,task,{mode:'review',implementationCommit,commands:[red,green,refactor]}):null;
     const reviewInvocation = buildProviderInvocation(reviewer, {
       cwd: worktree,
-      prompt: reviewPrompt(projectRoot, task, implementationCommit),
+      prompt: reviewPrompt(projectRoot, task, implementationCommit,reviewEvidence),
+      grokEvidence:reviewEvidence,
       task,
       timeoutMs: run.timeoutMs,
       mode: 'review',
+      codingPolicy:run.codingPolicy,policyDigest:run.codingPolicyDigest,policyRoot:projectRoot,
     });
     reviewInvocation.logPath = resolve(logRoot, 'review.log');
-    const review = await invokeControlled(projectRoot, run, task, reviewInvocation, invoke);
+    reviewInvocation.logPath = resolve(logRoot, `review-${reviewer}.log`);
+    review = await invokeControlled(projectRoot, run, task, reviewInvocation, invoke);
     if (requireRun(projectRoot, run.id).run.desiredState === 'cancelled') {
       throw new Error('AFK run was cancelled during fresh-context review.');
     }
@@ -860,12 +920,15 @@ async function implementTask(projectRoot, run, task, provider, dependencies = {}
     if (git(worktree, ['rev-parse', 'HEAD']) !== implementationCommit || gitDirty(worktree)) {
       throw new Error('Fresh-context review changed the inspected implementation.');
     }
+    reviewResults.push({reviewer,output:review.output,logPath:review.logPath});
+    }
+    if(reviewResults.length>1)review={...review,output:reviewResults.map(value=>`${value.reviewer}:\n${value.output}`).join('\n')};
     heartbeatExecutionLease(projectRoot, lease.id, {
       token: lease.token,
       durationMs: Math.min(86_400_000, run.timeoutMs + 10 * 60 * 1000),
     });
     const branchHead = git(worktree, ['rev-parse', 'HEAD']);
-    const reviewerIdentity = `${reviewer}/${reviewer === provider ? 'fresh-session' : 'independent-cli'}`;
+    const reviewerIdentity = reviewers.map(reviewer=>`${reviewer}/${reviewer === provider ? 'fresh-session' : 'independent-cli'}`).join(',');
     taskState(run, task, { status: 'ready-to-integrate', implementationCommit, branchHead, reviewer: reviewerIdentity });
     saveRun(paths, run);
     return {
@@ -890,6 +953,7 @@ async function implementTask(projectRoot, run, task, provider, dependencies = {}
 }
 
 async function integrateTask(projectRoot, run, result) {
+  assertRunProviderFresh(projectRoot,run);
   authorityChecks.get(run)?.({ stage: 'integrate', mode: 'command' });
   const { task, lease } = result;
   const repository = result.repository;
@@ -1027,6 +1091,7 @@ export async function executeAfkRun(projectRoot, runId, dependencies = {}) {
   try {
     if (run.autonomy && !authorityChecks.has(run)) throw new Error('Autonomous AFK run requires its original live authority context.');
     while (run.desiredState === 'running') {
+      assertRunProviderFresh(paths.projectRoot,run);
       const graph = readGraph(paths.projectRoot, run.slug);
       const check = validateTaskGraph(deliveryPaths(paths.projectRoot, run.slug).deliveryRoot, { slug: run.slug });
       if (check.status !== 'pass') throw new Error(`Task graph became invalid: ${check.errors.map((item) => item.message).join('; ')}`);
@@ -1043,7 +1108,8 @@ export async function executeAfkRun(projectRoot, runId, dependencies = {}) {
       const waveDefinition = graph.afk_waves.find((candidate) => Number(candidate.wave) === Number(firstReady.parallel_wave));
       const wave = executableIds.map((id) => graph.tasks.find((task) => task.id === id));
       const results = await Promise.all(wave.map((task, index) => (
-        implementTask(paths.projectRoot, run, task, run.providers[index % run.providers.length], dependencies)
+        implementTask(paths.projectRoot, run, task,
+          (run.implementationProviders??run.providers)[index % (run.implementationProviders??run.providers).length], dependencies)
       )));
       const control = requireRun(paths.projectRoot, run.id).run;
       run.desiredState = control.desiredState;