chati-dev 4.4.1 → 4.5.2

package/node_modules/@chati/tracking-clickup/src/index.js

@@ -0,0 +1,293 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ContractError, canonicalize, sha256 } from '@chati/core';
+
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const DELIVERY_STATES = new Set(['pending', 'sent_unconfirmed', 'confirmed', 'retryable_failure', 'permanent_failure']);
+const RECONCILIATION_STATES = new Set(['not_due', 'pending', 'reconciled', 'drift_detected', 'blocked']);
+const OPERATIONS = new Set(['create', 'update', 'close']);
+export const HOURLY_WATCHER_INTERVAL_MS = 60 * 60 * 1000;
+
+function fail(code, message, details = {}) { throw new ContractError(code, message, details); }
+function string(value, code, label) { if (typeof value !== 'string' || value.trim() === '') fail(code, `${label} must be a non-empty string`); }
+function object(value, code, label) { if (!value || typeof value !== 'object' || Array.isArray(value)) fail(code, `${label} must be an object`); }
+function timestamp(clock) {
+  if (typeof clock !== 'function') fail('MISSING_CLOCK', 'a deterministic clock function is required');
+  const result = clock();
+  const value = result instanceof Date ? result.toISOString() : result;
+  if (typeof value !== 'string' || !RFC3339.test(value) || Number.isNaN(Date.parse(value))) fail('INVALID_CLOCK', 'clock must return a valid RFC3339 timestamp or Date');
+  return value;
+}
+function writeAtomic(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(canonicalize(data), null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+function readOutbox(path) {
+  if (!existsSync(path)) return { schema_version: 1, projections: [] };
+  let data;
+  try { data = JSON.parse(readFileSync(path, 'utf8')); } catch { fail('OUTBOX_CORRUPT', 'outbox JSON is malformed'); }
+  if (data?.schema_version !== 1 || !Array.isArray(data.projections)) fail('OUTBOX_CORRUPT', 'outbox schema is invalid');
+  return data;
+}
+function closureMutation(payload) {
+  const status = typeof payload.status === 'string' ? payload.status.trim().toLowerCase() : '';
+  return ['closed', 'close', 'done', 'complete', 'completed'].includes(status)
+    || Object.hasOwn(payload, 'end_date') || Object.hasOwn(payload, 'endDate');
+}
+
+/**
+ * C-07 local projection authority. It intentionally has no ClickUp SDK,
+ * credentials, network client, timer or knowledge-store integration. A caller
+ * injects a transport only after an independently authorized boundary.
+ */
+export class TrackingClickUp {
+  #outboxPath;
+  #evolutionDir;
+  #clock;
+  #transport;
+  #verifyCompletion;
+  #verifyReference;
+  #resolveReference;
+  #preflight;
+  #watcherIntervalMs;
+  #state;
+
+  constructor({ outbox_path, project_evolution_dir, clock, transport = null, verify_completion, verify_reference, resolve_reference, preflight = null, watcher_interval_ms = HOURLY_WATCHER_INTERVAL_MS } = {}) {
+    string(outbox_path, 'INVALID_OUTBOX_PATH', 'outbox_path');
+    string(project_evolution_dir, 'INVALID_EVOLUTION_DIR', 'project_evolution_dir');
+    if (transport !== null && (!transport || typeof transport.send !== 'function')) fail('INVALID_TRANSPORT', 'transport.send must be a function');
+    if (typeof verify_completion !== 'function') fail('MISSING_COMPLETION_VERIFIER', 'verify_completion must be an injected C-06 verifier');
+    if (typeof verify_reference !== 'function') fail('MISSING_REFERENCE_VERIFIER', 'verify_reference must verify immutable handoff and journal references');
+    if (typeof resolve_reference !== 'function') fail('MISSING_REFERENCE_RESOLVER', 'resolve_reference must produce verified handoff and journal views');
+    if (preflight !== null && (typeof preflight.validate_schema !== 'function' || typeof preflight.authorize_transport !== 'function')) fail('INVALID_PREFLIGHT', 'preflight requires validate_schema and authorize_transport functions');
+    if (watcher_interval_ms !== HOURLY_WATCHER_INTERVAL_MS) fail('INVALID_WATCHER_INTERVAL', 'watcher interval must be exactly hourly');
+    this.#outboxPath = outbox_path;
+    this.#evolutionDir = project_evolution_dir;
+    this.#clock = clock;
+    this.#transport = transport;
+    this.#verifyCompletion = verify_completion;
+    this.#verifyReference = verify_reference;
+    this.#resolveReference = resolve_reference;
+    this.#preflight = preflight;
+    this.#watcherIntervalMs = watcher_interval_ms;
+    this.#state = readOutbox(outbox_path);
+    // Project Evolution is a derivative, never the only copy of evidence.
+    // Rebuild it after an interrupted outbox/evolution write sequence.
+    for (const projectId of new Set(this.#state.projections.map((item) => item.project_id))) this.#evolve(projectId);
+  }
+
+  get projections() { return Object.freeze(this.#state.projections.map((item) => Object.freeze(canonicalize(item)))); }
+  get outboxPath() { return this.#outboxPath; }
+  get watcherConfig() { return Object.freeze({ interval_ms: this.#watcherIntervalMs, mode: 'external-one-shot-scheduler' }); }
+
+  #persist() { writeAtomic(this.#outboxPath, this.#state); }
+  #find(projectionId) {
+    string(projectionId, 'INVALID_PROJECTION_ID', 'projection_id');
+    const projection = this.#state.projections.find((item) => item.projection_id === projectionId);
+    if (!projection) fail('PROJECTION_NOT_FOUND', 'projection does not exist', { projection_id: projectionId });
+    return projection;
+  }
+  #evolve(projectId) {
+    const relevant = this.#state.projections.filter((item) => item.project_id === projectId);
+    const latestByTask = new Map();
+    for (const item of relevant) latestByTask.set(item.task_id, item);
+    const sourceProjections = relevant.map(({ project_evolution_ref, ...source }) => source);
+    const snapshot = canonicalize({
+      schema_version: 1,
+      project_id: projectId,
+      current_phase: [...latestByTask.values()].at(-1)?.handoff_view.phase ?? 'unknown',
+      tasks: [...latestByTask.values()].map((item) => ({ task_id: item.task_id, attempt_id: item.attempt_id, phase: item.handoff_view.phase, canonical_state: item.journal_view.task_state, blockers: item.journal_view.blockers, delivery_state: item.delivery_state, reconciliation_state: item.reconciliation_state })),
+      decisions: [...new Map(relevant.flatMap((item) => item.decisions.map((decision) => [decision.decision_ref, decision]))).values()],
+      verified_handoff_refs: [...new Set(relevant.map((item) => item.handoff_ref))],
+      verified_journal_refs: [...new Set(relevant.map((item) => item.journal_ref))],
+      receipt_refs: [...new Set(relevant.map((item) => item.receipt_ref).filter(Boolean))],
+      blockers: relevant.filter((item) => item.delivery_state === 'permanent_failure' || item.reconciliation_state === 'blocked').map((item) => item.projection_id),
+      projection_backlog: relevant.filter((item) => !['confirmed', 'permanent_failure'].includes(item.delivery_state)).map((item) => item.projection_id),
+      source_outbox_hash: sha256({ schema_version: 1, projections: sourceProjections }),
+    });
+    const digest = sha256(snapshot);
+    const path = join(this.#evolutionDir, projectId, `${digest}.json`);
+    writeAtomic(path, snapshot);
+    return Object.freeze({ project_evolution_ref: `project-evolution://${projectId}/${digest}`, path, digest });
+  }
+  #setEvolution(projection) {
+    const evolution = this.#evolve(projection.project_id);
+    projection.project_evolution_ref = evolution.project_evolution_ref;
+    return evolution;
+  }
+  #preflightTransport(projection) {
+    validateProjection(projection);
+    if (!this.#preflight) fail('TRANSPORT_PRECONDITION_UNMET', 'schema and authorization preflight are required before any transport call');
+    if (this.#preflight.validate_schema(Object.freeze(canonicalize(projection))) !== true) fail('SCHEMA_NOT_AUTHORIZED', 'remote schema preflight rejected projection');
+    if (this.#preflight.authorize_transport(Object.freeze(canonicalize(projection))) !== true) fail('TRANSPORT_NOT_AUTHORIZED', 'transport authorization or token gate rejected projection');
+  }
+
+  enqueue(input = {}) {
+    object(input, 'INVALID_PROJECTION', 'projection');
+    const { projection_id, idempotency_key, canonical_event_id, task_id, clickup_ref, operation, payload, project_id, handoff_ref, journal_ref } = input;
+    const attempt_id = input.attempt_id ?? `project:${project_id}:no-attempt`;
+    for (const [name, value] of Object.entries({ projection_id, idempotency_key, canonical_event_id, task_id, clickup_ref, project_id })) string(value, 'INVALID_PROJECTION', name);
+    string(attempt_id, 'INVALID_PROJECTION', 'attempt_id');
+    if (!OPERATIONS.has(operation)) fail('INVALID_PROJECTION_OPERATION', 'operation must be create, update, or close');
+    object(payload, 'INVALID_PROJECTION', 'payload');
+    string(handoff_ref, 'MISSING_SOURCE_REFERENCE', 'handoff_ref');
+    string(journal_ref, 'MISSING_SOURCE_REFERENCE', 'journal_ref');
+    if (this.#verifyReference(handoff_ref, 'handoff') !== true || this.#verifyReference(journal_ref, 'journal') !== true) fail('UNVERIFIED_SOURCE_REFERENCE', 'handoff and journal references must be verified before projection');
+    const handoff_view = this.#resolveReference(handoff_ref, 'handoff');
+    const journal_view = this.#resolveReference(journal_ref, 'journal');
+    object(handoff_view, 'INVALID_HANDOFF_VIEW', 'resolved handoff view');
+    object(journal_view, 'INVALID_JOURNAL_VIEW', 'resolved journal view');
+    string(handoff_view.phase, 'INVALID_HANDOFF_VIEW', 'resolved handoff view.phase');
+    string(journal_view.task_state, 'INVALID_JOURNAL_VIEW', 'resolved journal view.task_state');
+    if (!Array.isArray(journal_view.blockers) || !journal_view.blockers.every((item) => typeof item === 'string' && item)) fail('INVALID_JOURNAL_VIEW', 'resolved journal view.blockers must be non-empty strings');
+    if (input.decisions !== undefined && (!Array.isArray(input.decisions) || !input.decisions.every((item) => item && typeof item === 'object' && typeof item.decision_ref === 'string' && item.decision_ref && this.#verifyReference(item.decision_ref, 'decision') === true))) fail('INVALID_DECISIONS', 'decisions must be verified immutable project decision references');
+    const duplicateByKey = this.#state.projections.find((item) => item.idempotency_key === idempotency_key);
+    const duplicateById = this.#state.projections.find((item) => item.projection_id === projection_id);
+    const duplicate = duplicateByKey || duplicateById;
+    if (duplicate) {
+      const sameIdentity = duplicateByKey === duplicateById
+        && duplicate.task_id === task_id
+        && duplicate.attempt_id === attempt_id
+        && duplicate.operation === operation
+        && duplicate.payload_hash === sha256(payload);
+      if (sameIdentity) return Object.freeze(canonicalize(duplicate));
+      if (duplicateByKey) fail('DUPLICATE_IDEMPOTENCY_KEY', 'idempotency_key already exists with different material');
+      fail('DUPLICATE_PROJECTION_ID', 'projection_id already exists with different material');
+    }
+    if (operation === 'close' || closureMutation(payload)) {
+      object(input.completion, 'MISSING_COMPLETION_EVIDENCE', 'completion');
+      const verdict = this.#verifyCompletion(input.completion);
+      if (verdict !== true) fail('INVALID_COMPLETION_EVIDENCE', 'close requires a valid C-06 completion');
+    }
+    const projection = canonicalize({
+      schema_version: 1, projection_id, idempotency_key, canonical_event_id, task_id, attempt_id, clickup_ref, project_id, handoff_ref, journal_ref, handoff_view: canonicalize(handoff_view), journal_view: canonicalize(journal_view), decisions: canonicalize(input.decisions ?? []), operation,
+      payload_hash: sha256(payload), payload, delivery_state: 'pending', reconciliation_state: 'not_due', created_at: timestamp(this.#clock), attempts: 0,
+    });
+    this.#state.projections.push(projection);
+    this.#persist(); // Durable before any injected transport is called.
+    this.#setEvolution(projection);
+    this.#persist();
+    return Object.freeze(canonicalize(projection));
+  }
+
+  deliver({ projection_id } = {}) {
+    const projection = this.#find(projection_id);
+    if (!this.#transport) fail('TRANSPORT_NOT_CONFIGURED', 'no authorized projection transport is configured');
+    if (projection.delivery_state === 'confirmed') return Object.freeze(canonicalize(projection));
+    if (projection.delivery_state === 'permanent_failure') fail('PERMANENT_FAILURE', 'permanently failed projection cannot be retried');
+    if (projection.delivery_state === 'sent_unconfirmed') fail('UNCONFIRMED_DELIVERY_REQUIRES_LOOKUP', 'unconfirmed delivery must be resolved by idempotency lookup before resend');
+    this.#preflightTransport(projection);
+    projection.attempts += 1;
+    projection.last_attempt_at = timestamp(this.#clock);
+    try {
+      const response = this.#transport.send(Object.freeze(canonicalize(projection)));
+      object(response, 'INVALID_TRANSPORT_RECEIPT', 'transport response');
+      if (response.receipt_ref) {
+        string(response.receipt_ref, 'INVALID_TRANSPORT_RECEIPT', 'receipt_ref');
+        if (this.#verifyReference(response.receipt_ref, 'receipt') !== true) fail('UNVERIFIED_RECEIPT', 'delivery receipt must be an immutable verified reference');
+        projection.delivery_state = 'confirmed';
+        projection.receipt_ref = response.receipt_ref;
+        projection.reconciliation_state = 'pending';
+      } else projection.delivery_state = 'sent_unconfirmed';
+    } catch (error) {
+      projection.delivery_state = error?.permanent === true ? 'permanent_failure' : 'retryable_failure';
+      projection.failure_code = typeof error?.code === 'string' ? error.code : 'TRANSPORT_FAILURE';
+    }
+    this.#setEvolution(projection);
+    this.#persist();
+    return Object.freeze(canonicalize(projection));
+  }
+
+  reconcile({ projection_id } = {}) {
+    const projection = this.#find(projection_id);
+    if (!this.#transport || typeof this.#transport.reconcile !== 'function') fail('RECONCILIATION_NOT_CONFIGURED', 'no authorized reconciliation transport is configured');
+    if (projection.delivery_state !== 'confirmed') fail('RECEIPT_REQUIRED', 'reconciliation requires confirmed delivery receipt');
+    this.#preflightTransport(projection);
+    const result = this.#transport.reconcile(Object.freeze(canonicalize(projection)));
+    object(result, 'INVALID_RECONCILIATION_RESULT', 'reconciliation result');
+    if (!['reconciled', 'drift_detected', 'blocked'].includes(result.state)) fail('INVALID_RECONCILIATION_RESULT', 'reconciliation state is invalid');
+    projection.reconciliation_state = result.state;
+    if (result.evidence_ref !== undefined) { string(result.evidence_ref, 'INVALID_RECONCILIATION_RESULT', 'evidence_ref'); projection.reconciliation_evidence_ref = result.evidence_ref; }
+    this.#setEvolution(projection);
+    this.#persist();
+    return Object.freeze(canonicalize(projection));
+  }
+
+  resolveSentUnconfirmed({ projection_id } = {}) {
+    const projection = this.#find(projection_id);
+    if (projection.delivery_state !== 'sent_unconfirmed') fail('NOT_SENT_UNCONFIRMED', 'idempotency lookup only applies to sent_unconfirmed delivery');
+    if (!this.#transport || typeof this.#transport.lookup !== 'function') fail('IDEMPOTENCY_LOOKUP_NOT_CONFIGURED', 'sent_unconfirmed requires an idempotency lookup transport');
+    this.#preflightTransport(projection);
+    const result = this.#transport.lookup(Object.freeze(canonicalize(projection)));
+    object(result, 'INVALID_LOOKUP_RESULT', 'idempotency lookup result');
+    if (result.receipt_ref !== undefined) {
+      string(result.receipt_ref, 'INVALID_LOOKUP_RESULT', 'receipt_ref');
+      if (this.#verifyReference(result.receipt_ref, 'receipt') !== true) fail('UNVERIFIED_RECEIPT', 'lookup receipt must be an immutable verified reference');
+      projection.delivery_state = 'confirmed';
+      projection.receipt_ref = result.receipt_ref;
+      projection.reconciliation_state = 'pending';
+    } else if (result.state === 'not_found') projection.delivery_state = 'pending';
+    else if (result.state !== 'unknown') fail('INVALID_LOOKUP_RESULT', 'lookup requires receipt_ref, not_found, or unknown');
+    this.#setEvolution(projection);
+    this.#persist();
+    return Object.freeze(canonicalize(projection));
+  }
+
+  watchOnce() {
+    // Intentionally one-shot: a host scheduler may invoke this hourly. No timer is created.
+    const replayed = [];
+    for (const projection of this.#state.projections) {
+      if (projection.delivery_state === 'sent_unconfirmed') {
+        const resolved = this.resolveSentUnconfirmed({ projection_id: projection.projection_id });
+        if (resolved.delivery_state === 'pending') replayed.push(this.deliver({ projection_id: projection.projection_id }));
+      } else if (['pending', 'retryable_failure'].includes(projection.delivery_state)) replayed.push(this.deliver({ projection_id: projection.projection_id }));
+    }
+    return Object.freeze(replayed);
+  }
+
+  rederiveProjectEvolution({ project_id } = {}) {
+    string(project_id, 'INVALID_PROJECT_ID', 'project_id');
+    if (!this.#state.projections.some((item) => item.project_id === project_id)) fail('PROJECT_NOT_FOUND', 'project has no durable projections', { project_id });
+    return this.#evolve(project_id);
+  }
+
+  recordMetrics({ projection_id, actual_human_effort, actual_ai_processing, rework_cycles, rework_review_refs, completion } = {}) {
+    const projection = this.#find(projection_id);
+    object(actual_human_effort, 'INVALID_HUMAN_EFFORT', 'actual_human_effort');
+    object(actual_ai_processing, 'INVALID_AI_PROCESSING', 'actual_ai_processing');
+    if (!Number.isInteger(rework_cycles) || rework_cycles < 0) fail('INVALID_REWORK_CYCLES', 'rework_cycles must be a non-negative integer');
+    object(completion, 'MISSING_COMPLETION_EVIDENCE', 'completion');
+    if (this.#verifyCompletion(completion) !== true) fail('INVALID_COMPLETION_EVIDENCE', 'metrics require a valid C-06 completion');
+    if (!Array.isArray(rework_review_refs) || rework_review_refs.length !== rework_cycles || !rework_review_refs.every((ref) => typeof ref === 'string' && ref && this.#verifyReference(ref, 'review') === true)) {
+      fail('INVALID_REWORK_PROVENANCE', 'each rework cycle requires one verified C-05 review reference');
+    }
+    string(actual_human_effort.evidence_ref, 'INVALID_HUMAN_EFFORT', 'actual_human_effort.evidence_ref');
+    string(actual_ai_processing.evidence_ref, 'INVALID_AI_PROCESSING', 'actual_ai_processing.evidence_ref');
+    if (this.#verifyReference(actual_human_effort.evidence_ref, 'human-effort') !== true || this.#verifyReference(actual_ai_processing.evidence_ref, 'attempt-instrumentation') !== true) {
+      fail('UNVERIFIED_METRIC_PROVENANCE', 'metrics require verified explicit human and attempt instrumentation evidence');
+    }
+    // No wall-clock value exists here. Provenance is durable with the metric.
+    const metricMaterial = canonicalize({ actual_human_effort, actual_ai_processing, rework_cycles, rework_review_refs, completion_id: completion.completion_id });
+    if (projection.metrics) {
+      const { recorded_at: _recordedAt, ...existingMaterial } = projection.metrics;
+      if (sha256(existingMaterial) !== sha256(metricMaterial)) fail('METRICS_ALREADY_RECORDED', 'projection metrics are immutable');
+      return Object.freeze(canonicalize(projection));
+    }
+    projection.metrics = canonicalize({ ...metricMaterial, recorded_at: timestamp(this.#clock) });
+    this.#setEvolution(projection);
+    this.#persist();
+    return Object.freeze(canonicalize(projection));
+  }
+}
+
+export function validateProjection(projection) {
+  object(projection, 'INVALID_PROJECTION', 'projection');
+  for (const field of ['projection_id', 'idempotency_key', 'canonical_event_id', 'task_id', 'clickup_ref', 'project_id', 'payload_hash']) string(projection[field], 'INVALID_PROJECTION', field);
+  if (!OPERATIONS.has(projection.operation)) fail('INVALID_PROJECTION_OPERATION', 'operation is invalid');
+  if (!DELIVERY_STATES.has(projection.delivery_state)) fail('INVALID_DELIVERY_STATE', 'delivery_state is invalid');
+  if (!RECONCILIATION_STATES.has(projection.reconciliation_state)) fail('INVALID_RECONCILIATION_STATE', 'reconciliation_state is invalid');
+  if (projection.delivery_state === 'confirmed' && typeof projection.receipt_ref !== 'string') fail('MISSING_RECEIPT', 'confirmed projection requires receipt_ref');
+  return Object.freeze(canonicalize(projection));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.4.1",
+  "version": "4.5.2",
   "description": "AI-Powered Multi-Agent Orchestration System - Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -28,7 +28,9 @@
     "sync": "node scripts/sync-framework.js",
     "scan": "node scripts/scan-stale.js",
     "install-to": "node scripts/install-to.js",
-    "prepublishOnly": "node scripts/sync-framework.js && node scripts/scan-stale.js && node scripts/sign-manifest.js && REQUIRE_SIGNED_MANIFEST=1 node scripts/validate-package.js",
+    "prepublishOnly": "node scripts/sync-framework.js && node scripts/scan-stale.js && node scripts/sign-model-catalog.js && node scripts/sign-manifest.js && REQUIRE_SIGNED_MANIFEST=1 node scripts/validate-package.js",
+    "prepack": "node scripts/prepare-bundled-dependencies.js",
+    "postpack": "node scripts/prepare-bundled-dependencies.js --clean",
     "test": "node --test test/**/*.test.js",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
@@ -62,12 +64,32 @@
     "url": "https://github.com/Chati-dev/Chati.dev/issues"
   },
   "dependencies": {
+    "@chati/browser-capability": "0.1.0",
+    "@chati/core": "0.1.0",
+    "@chati/knowledge-context": "0.1.0",
+    "@chati/planning": "0.1.0",
+    "@chati/provider-registry": "0.1.0",
+    "@chati/rail": "0.1.0",
+    "@chati/release-lane": "0.1.0",
+    "@chati/review-council": "0.1.0",
+    "@chati/tracking-clickup": "0.1.0",
     "@clack/prompts": "^0.7.0",
     "chalk": "^5.3.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^5.4.0",
     "ora": "^8.0.1",
     "semver": "^7.6.0"
   },
+  "bundleDependencies": [
+    "@chati/browser-capability",
+    "@chati/core",
+    "@chati/knowledge-context",
+    "@chati/planning",
+    "@chati/provider-registry",
+    "@chati/rail",
+    "@chati/release-lane",
+    "@chati/review-council",
+    "@chati/tracking-clickup"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },

package/src/config/ide-configs.js

@@ -37,6 +37,16 @@ export const IDE_CONFIGS = {
     rulesPath: '.codex/rules/',
     overrideFile: 'AGENTS.override.md',
   },
+  'grok-cli': {
+    name: 'Grok CLI',
+    description: 'xAI terminal agent',
+    group: 'cli',
+    recommended: false,
+    configPath: '.grok/commands/',
+    rulesFile: 'AGENTS.md',
+    mcpConfigFile: '.grok/mcp.json',
+    formatNotes: 'Native markdown command format',
+  },
   'vscode': {
     name: 'VS Code',
     description: 'Extensions: Continue, AI Chat, etc',
@@ -87,6 +97,7 @@ export const IDE_TO_PROVIDER = {
   'claude-code': 'claude',
   'gemini-cli': 'gemini',
   'codex-cli': 'codex',
+  'grok-cli': 'grok',
   'vscode': null,
   'cursor': null,
   'windsurf': null,

package/src/context/domain-loader.js

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join, basename } from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 /**
  * Load a single domain YAML file.

package/src/dashboard/data-reader.js

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**

package/src/executors/runner.js

@@ -17,7 +17,7 @@
 import { spawn } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**

package/src/installer/core.js

@@ -23,7 +23,7 @@ const FRAMEWORK_SOURCE = existsSync(BUNDLED_SOURCE) ? BUNDLED_SOURCE : MONOREPO_
  * Install Chati.dev framework into target directory
  */
 export async function installFramework(config) {
-  const { targetDir, projectType, language, selectedIDEs, selectedMCPs, projectName, llmProvider, allProviders } = config;
+  const { targetDir, projectType, language, selectedIDEs, selectedMCPs, projectName, allProviders } = config;
   // Always derive version from package.json (single source of truth)
   let { version } = config;
   if (!version) {
@@ -55,7 +55,7 @@ export async function installFramework(config) {
   if (!existsSync(sessionPath)) {
     writeFileSync(
       sessionPath,
-      generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, llmProvider, allProviders }),
+      generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, allProviders }),
       'utf-8'
     );
   }
@@ -114,12 +114,13 @@ export async function installFramework(config) {
     createDir(join(memoriesBase, dir));
   }
 
-  // Copy framework files from source (adapted for non-Claude providers)
-  copyFrameworkFiles(frameworkDir, llmProvider || 'claude');
+  // Copy the canonical framework as a provider-neutral fallback. Every enabled
+  // CLI receives its own explicit adapted overlay below.
+  copyFrameworkFiles(frameworkDir, 'claude');
 
-  // Generate provider overlays for secondary CLI providers
-  if (allProviders && allProviders.length > 1) {
-    generateProviderOverlays(targetDir, FRAMEWORK_SOURCE, llmProvider || 'claude', allProviders);
+  // Generate symmetric provider overlays. No CLI is permanently primary.
+  if (allProviders && allProviders.length > 0) {
+    generateProviderOverlays(targetDir, FRAMEWORK_SOURCE, allProviders);
   }
 
   // Bundle the CLI source into the framework dir so chati-router.js can run
@@ -159,19 +160,19 @@ export async function installFramework(config) {
   // Write config.yaml
   writeFileSync(
     join(frameworkDir, 'config.yaml'),
-    generateConfigYaml({ version, projectType, language, selectedIDEs, llmProvider, allProviders }),
+    generateConfigYaml({ version, projectType, language, selectedIDEs, allProviders }),
     'utf-8'
   );
 
-  // 3. Configure IDEs (secondary providers get overlay orchestrator path)
-  const primary = llmProvider || 'claude';
+  // 3. Configure every CLI against its own overlay. The CLI that opens a
+  // session becomes that session's orchestrator.
   for (const ideKey of selectedIDEs) {
     const ideProvider = IDE_TO_PROVIDER[ideKey];
-    const isSecondary = ideProvider && ideProvider !== primary && allProviders && allProviders.length > 1;
-    const orchestratorPath = isSecondary
+    const hasProviderOverlay = ideProvider && allProviders?.includes(ideProvider);
+    const orchestratorPath = hasProviderOverlay
       ? `.chati.dev/.adapted/${ideProvider}/orchestrator/chati.md`
       : '.chati.dev/orchestrator/chati.md';
-    await configureIDE(targetDir, ideKey, selectedMCPs, { orchestratorPath, isSecondary, providerName: ideProvider });
+    await configureIDE(targetDir, ideKey, selectedMCPs, { orchestratorPath, isSecondary: false, providerName: ideProvider });
   }
 
   const hasClaude = selectedIDEs.includes('claude-code');

package/src/installer/provider-overlay.js

@@ -2,8 +2,8 @@
  * @fileoverview Provider Overlay Generator for multi-CLI continuity.
  *
  * When multiple CLI providers are selected (e.g. Claude Code + Gemini CLI),
- * the primary provider's adapted files go in chati.dev/ (main). For each
- * secondary provider, this module generates an overlay directory at
+ * the provider-neutral framework lives in chati.dev/ (main). For each
+ * enabled provider, this module generates an overlay directory at
  * chati.dev/.adapted/<provider>/ with the ADAPTABLE_FILES adapted for
  * that provider. Each CLI reads only its own files — zero runtime translation.
  *
@@ -15,31 +15,24 @@ import { join, dirname } from 'path';
 import { adaptFrameworkFile, ADAPTABLE_FILES } from '../config/framework-adapter.js';
 
 /**
- * Generate adapted framework overlays for secondary providers.
+ * Generate adapted framework overlays for all enabled providers.
  *
- * For each non-primary CLI provider, creates chati.dev/.adapted/<provider>/
+ * For each CLI provider, creates chati.dev/.adapted/<provider>/
  * with provider-adapted copies of all ADAPTABLE_FILES.
  *
- * Reads CANONICAL (Claude) content from frameworkSource, then adapts for
- * each secondary provider. This avoids double-adaptation issues when the
- * primary provider is not Claude.
+ * Reads canonical source content from frameworkSource, then adapts it for
+ * each enabled provider. Every CLI resolves its own overlay symmetrically.
  *
  * @param {string} targetDir - Project root directory
  * @param {string} frameworkSource - Source directory with canonical framework files
- * @param {string} primaryProvider - Primary provider name ('claude', 'gemini', 'codex')
  * @param {string[]} allProviders - All CLI provider names
  * @returns {{ generated: string[], skipped: string[] }}
  */
-export function generateProviderOverlays(targetDir, frameworkSource, primaryProvider, allProviders) {
+export function generateProviderOverlays(targetDir, frameworkSource, allProviders) {
   const result = { generated: [], skipped: [] };
   const frameworkDir = join(targetDir, '.chati.dev');
 
   for (const provider of allProviders) {
-    if (provider === primaryProvider) {
-      result.skipped.push(provider);
-      continue;
-    }
-
     const overlayDir = join(frameworkDir, '.adapted', provider);
 
     for (const file of ADAPTABLE_FILES) {
@@ -64,7 +57,7 @@ export function generateProviderOverlays(targetDir, frameworkSource, primaryProv
 /**
  * Resolve the correct framework file path for a given provider.
  *
- * Returns the overlay path for secondary providers (if it exists),
+ * Returns the provider overlay path when it exists,
  * otherwise falls back to the main chati.dev/ path.
  *
  * @param {string} projectDir - Project root directory

package/src/installer/scaffold-applier.js

@@ -24,7 +24,7 @@ import {
 } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { hashContent } from './file-hasher.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/installer/templates.js

@@ -1,10 +1,10 @@
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 /**
  * Generate session.yaml content
  */
 export function generateSessionYaml(config) {
-  const { projectName, projectType, language, selectedIDEs, selectedMCPs, llmProvider, allProviders } = config;
+  const { projectName, projectType, language, selectedIDEs, selectedMCPs, allProviders } = config;
 
   // Schema MUST match session-manager.js DEFAULT_SESSION fields,
   // otherwise validateSession() rejects installer-generated sessions.
@@ -27,9 +27,7 @@ export function generateSessionYaml(config) {
     user_level_confidence: 0.0,
     ides: selectedIDEs,
     mcps: selectedMCPs,
-    providers_enabled: allProviders && allProviders.length > 0 ? allProviders : [llmProvider || 'claude'],
-    primary_provider: llmProvider || 'claude',
-    active_provider: llmProvider || 'claude',
+    providers_enabled: allProviders && allProviders.length > 0 ? allProviders : ['claude'],
     completed_agents: [],
     agent_results: {},
     mode_transitions: [],
@@ -60,7 +58,7 @@ export function generateSessionYaml(config) {
     };
   }
 
-  return yaml.dump(session, { lineWidth: -1, quotingType: '"', forceQuotes: false });
+  return yaml.dump(session, { lineWidth: -1, quoteStyle: 'double', forceQuotes: false });
 }
 
 /**
@@ -102,10 +100,9 @@ export const PROVIDER_MODEL_MAPS = {
  * Generate config.yaml content
  */
 export function generateConfigYaml(config) {
-  const { version, projectType, language, llmProvider, allProviders } = config;
+  const { version, projectType, language, allProviders } = config;
   const selectedIDEs = config.selectedIDEs || [];
-  const provider = llmProvider || 'claude';
-  const providers = allProviders && allProviders.length > 0 ? allProviders : [provider];
+  const providers = allProviders && allProviders.length > 0 ? allProviders : ['claude'];
 
   const configData = {
     version: version,
@@ -116,9 +113,10 @@ export function generateConfigYaml(config) {
     language: language,
     ides: selectedIDEs,
     providers: {
-      claude: { enabled: providers.includes('claude') || provider === 'claude', primary: provider === 'claude' },
-      gemini: { enabled: providers.includes('gemini') || selectedIDEs.includes('gemini-cli'), model_default: 'pro', primary: provider === 'gemini' },
-      codex: { enabled: providers.includes('codex') || selectedIDEs.includes('codex-cli'), model_default: 'codex', primary: provider === 'codex' },
+      claude: { enabled: providers.includes('claude') },
+      gemini: { enabled: providers.includes('gemini') || selectedIDEs.includes('gemini-cli') },
+      codex: { enabled: providers.includes('codex') || selectedIDEs.includes('codex-cli') },
+      grok: { enabled: providers.includes('grok') || selectedIDEs.includes('grok-cli') },
     },
   };
 
@@ -148,7 +146,7 @@ export function generateConfigYaml(config) {
     frustration_detection: true,
     bash_security_checks: true,
     // Agent Teams (Article XXI) — default ON in v4.2.2.
-    // Only effective when provider === 'claude' (gated in cli.js
+    // Only effective when the active session runs in Claude (gated in cli.js
     // isAgentTeamsEnabled). Gemini and Codex always fall back to sequential
     // pipeline silently. See plan: was previously false for "safe rollout"
     // but the v4.2.0 launch never actually shipped, so this is a fresh start.
@@ -165,18 +163,7 @@ export function generateConfigYaml(config) {
     anonymous_id: null,
   };
 
-  // Add agent_overrides with optimal model map for the selected provider
-  if (provider !== 'claude') {
-    const modelMap = PROVIDER_MODEL_MAPS[provider];
-    if (modelMap) {
-      configData.agent_overrides = {};
-      for (const [agent, model] of Object.entries(modelMap.agents)) {
-        configData.agent_overrides[agent] = { provider, model };
-      }
-    }
-  }
-
-  return yaml.dump(configData, { lineWidth: -1, quotingType: '"', forceQuotes: false });
+  return yaml.dump(configData, { lineWidth: -1, quoteStyle: 'double', forceQuotes: false });
 }
 
 /**