@thebackstoryis/engineering-with-ai 0.3.0 → 0.3.1

package/src/config-document.mjs

@@ -0,0 +1,49 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync,existsSync} 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';
+
+function fail(message,statusCode=409){const error=new Error(message);error.statusCode=statusCode;error.configurationError=true;throw error;}
+function safePath(paths){
+  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
+  if(rel.startsWith('..')||isAbsolute(rel))fail('Settings require a safe project configuration path.',403);
+  let cursor=parent;
+  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Settings cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Settings require a safe project configuration path.',403);cursor=next;}
+  const stat=lstatSync(paths.configPath);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Settings require a regular, non-symbolic configuration file.',403);
+  if(stat.size>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+  return stat;
+}
+export function readProjectDocument(projectRoot){
+  const paths=projectPaths(projectRoot);let fd;
+  try{
+    const stat=safePath(paths);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.');
+    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+    const document=YAML.parseDocument(bytes.toString('utf8'));
+    if(document.errors.length)fail('Project configuration contains invalid YAML. Fix it before editing settings.',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('Project configuration and SPECS locator must agree before editing settings.',422);
+    return {paths,document,config,digest:'sha256:'+createHash('sha256').update(bytes).digest('hex'),mode:stat.mode&0o777};
+  }catch(error){if(error.configurationError)throw error;fail('Project settings could not be read. Check configuration and file permissions.');}
+  finally{if(fd!==undefined)closeSync(fd);}
+}
+export function editProjectDocument(projectRoot,expectedDigest,apply){
+  if(!/^sha256:[a-f0-9]{64}$/.test(String(expectedDigest??'')))fail('Reload settings before saving.',400);
+  const paths=projectPaths(projectRoot),lock=paths.configPath+'.configuration.lock';let lockFd,tempFd,temporary;
+  try{
+    safePath(paths);
+    if(existsSync(paths.configPath+'.dashboard-preferences.lock'))fail('Settings are being edited. Retry after that save finishes.');
+    try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Settings are being edited. Retry after that save finishes.');}
+    const before=readProjectDocument(projectRoot);if(before.digest!==expectedDigest)fail('Project configuration changed. Reload the settings and try again.');
+    apply(before.document,before.config);
+    const content=before.document.toString();
+    temporary=paths.configPath+'.settings-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
+    writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
+    if(readProjectDocument(projectRoot).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.');
+    safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
+    return readProjectDocument(projectRoot);
+  }catch(error){if(error.configurationError||error.codingProviderError||error.dashboardPreferenceError)throw error;fail('Project settings could not be saved. Check configuration and file permissions.');}
+  finally{if(tempFd!==undefined)closeSync(tempFd);if(temporary)unlinkSync(temporary);if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}}
+}

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';
@@ -90,6 +91,20 @@ const checkinInstructionFiles = ['AGENTS.md', 'CLAUDE.md'];
 const checkinInstruction = `<!-- EWAI-CHECKIN:START -->
 ## EWAI conversation check-in
 
+### Concise, useful output
+
+Prioritise correctness, fidelity and usefulness, then brevity. Resist verbosity: remove repetition, filler, restated requests and routine tool narration. Lead with the result or recommendation, using plain language and enough action detail to make it usable.
+
+Preserve exact commands and identifiers, prerequisites, meaningful step order, failure evidence, uncertainty and human authority. Report only verification actually performed. Follow mandatory check-in, status, consent and phase protocols. Expand when a shorter answer would hide a consequential fact or when detail is requested; do not impose arbitrary word limits.
+
+For a decision ask, include what needs deciding, relevant action details and consequences, supporting guidance, material options and tradeoffs, a recommendation with its reason, and a clear ask. Provide a suggested response when it helps the person act. If evidence is insufficient, recommend the next evidence-gathering step. Recommendations, defaults and suggested replies never constitute approval.
+
+### Query refinement
+
+Lead with the recommended interpretation or refined request, explaining consequential assumptions. Ask one focused question only when missing information materially changes the scope, outcome or next action; include supporting guidance and a recommended response with its reason. Keep uncertainty visible, preserve the user's intent and continue independent authorised work. After clarification, confirm the refined request briefly and act within its authority boundaries.
+
+### Check-in and workflow
+
 Keep the complete workflow, but present it cleanly: four routine status lines plus the returned menu at a decision point. Preserve warnings, blockers and unknown checks with short reasons; detailed diagnostics are on request. Progress is one sentence of at most 24 words per meaningful checkpoint. Do not narrate commands, file reads, JSON parsing or internal reasoning, and do not repeat the menu during a selected action. Never shorten briefing, purpose alignment, consent, standards or approval gates to meet an output limit. Use the guarded dashboard password form by default for licence setup; a private terminal prompt is an alternative only when a genuine interactive terminal is available. Never emulate hidden terminal entry through chat.
 
 When \`.ewai-pipeline/project.json\` exists, perform one EWAI check-in at the start of each new agent conversation before substantive project work. That locator identifies the configured SPECS root; do not assume it is \`./SPECS\`. Claude may receive its check-in JSON from the managed SessionStart hook; interpret that result instead of running it twice. Otherwise run \`ewai checkin --project . --json\`. This starts or reuses the project-local pipeline dashboard and refreshes its SQLite projection. Always interpret and report the EWAI version/update status, premium entitlement and installed-library status, dashboard URL, state-integrity result, mandatory standards status, configured external validators, and any configured-versus-installed CLI mismatch. Show unknown checks with their reason rather than omitting them.
@@ -346,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,
@@ -360,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);
 }
 
@@ -392,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 };
 }