chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/evidence-authority-enrollment.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonicalSerialize } from '@chati/core';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { verifyRailEvidenceAuthorityCertificate } from './rail-evidence-authority.js';
+import { verifyClickUpMcpAuthorityCertificate } from './clickup-runtime.js';
+import {
+  persistImmutableInstallationFile, readSafeInstallationStorageFile, replaceInstallationStorageFile,
+} from '../installer-v2/catalog-client.js';
+
+const MAX_CERTIFICATE_BYTES = 32 * 1024;
+const CERTIFICATE_TYPES = Object.freeze({
+  'chati-rail-evidence-authority': Object.freeze({
+    path: '.chati/v2/rail/evidence-authority.json', verify: verifyRailEvidenceAuthorityCertificate,
+  }),
+  'chati-clickup-mcp-authority': Object.freeze({
+    path: '.chati/v2/tracking/clickup-mcp-authority.json', verify: verifyClickUpMcpAuthorityCertificate,
+  }),
+});
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+
+/** Public-certificate enrollment only. Never generates or trusts an issuer key. */
+export function enrollProjectEvidenceAuthority({ projectDir, certificate, replace = false, clock = () => new Date() } = {}) {
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'evidence authority enrollment requires a verified v2 installation');
+  if (typeof replace !== 'boolean') fail('INVALID_AUTHORITY_ENROLLMENT', 'replace must be an explicit boolean');
+  const definition = Object.hasOwn(CERTIFICATE_TYPES, certificate?.certificate_type ?? '')
+    ? CERTIFICATE_TYPES[certificate.certificate_type] : null;
+  if (!definition) fail('INVALID_AUTHORITY_CERTIFICATE_TYPE', 'expected a CHATI RAIL evidence or ClickUp MCP authority certificate');
+  const rootPublicKey = readFileSync(new URL('../installer/signing-public-key.pem', import.meta.url), 'utf8');
+  // Verify the original closed-schema object before serializing or mutating storage.
+  definition.verify({ certificate, expected_project_id: artifact.project_id, root_public_key: rootPublicKey, clock });
+  // createPublicKey also accepts private PEM and ignores trailing PEM blocks.
+  // Do not persist such input or normalize a signed certificate into new bytes.
+  if (typeof certificate.public_key !== 'string'
+    || !/^-----BEGIN PUBLIC KEY-----\r?\n(?:[A-Za-z0-9+/=]+\r?\n)+-----END PUBLIC KEY-----$/.test(certificate.public_key.trim())) {
+    fail('AUTHORITY_PUBLIC_KEY_REQUIRED', 'certificate public_key must contain exactly one public SPKI PEM block');
+  }
+  const content = `${canonicalSerialize(certificate)}\n`;
+  if (Buffer.byteLength(content) > MAX_CERTIFICATE_BYTES) fail('AUTHORITY_CERTIFICATE_SIZE_LIMIT', 'authority certificate exceeds 32 KiB');
+  const path = join(projectDir, definition.path);
+  const previous = readSafeInstallationStorageFile(path, {
+    allowMissing: true, label: 'evidence authority certificate', maxBytes: MAX_CERTIFICATE_BYTES,
+    unsafeCode: 'UNSAFE_AUTHORITY_CERTIFICATE_STORAGE', sizeCode: 'AUTHORITY_CERTIFICATE_SIZE_LIMIT',
+  });
+  let written = false;
+  if (previous === null) {
+    written = persistImmutableInstallationFile(path, content, {
+      label: 'evidence authority certificate', maxBytes: MAX_CERTIFICATE_BYTES,
+      conflictCode: 'AUTHORITY_CERTIFICATE_CONFLICT',
+    });
+  } else if (previous.content !== content) {
+    if (!replace) fail('AUTHORITY_CERTIFICATE_CONFLICT', 'another certificate is enrolled; use --replace explicitly to rotate it');
+    replaceInstallationStorageFile(path, content, previous);
+    written = true;
+  }
+  return Object.freeze({
+    ok: true, action: 'rail_authority_enrolled', written,
+    project_id: artifact.project_id, issuer_id: certificate.issuer_id,
+    certificate_type: certificate.certificate_type, certificate_ref: definition.path,
+    expires_at: certificate.expires_at,
+  });
+}
+
+export function enrollProjectEvidenceAuthorityFile({ projectDir, certificatePath, replace = false } = {}) {
+  const source = readSafeInstallationStorageFile(certificatePath, {
+    label: 'enrollment certificate input', maxBytes: MAX_CERTIFICATE_BYTES,
+    unsafeCode: 'UNSAFE_AUTHORITY_CERTIFICATE_INPUT', sizeCode: 'AUTHORITY_CERTIFICATE_SIZE_LIMIT',
+  });
+  let certificate;
+  try { certificate = JSON.parse(source.content); }
+  catch { fail('INVALID_AUTHORITY_CERTIFICATE_JSON', 'enrollment certificate must be valid JSON'); }
+  return enrollProjectEvidenceAuthority({ projectDir, certificate, replace });
+}

package/src/orchestrator/evidence-authority-request.js

@@ -0,0 +1,46 @@
+import { canonicalSerialize, sha256 } from '@chati/core';
+import { createPublicKey, verify } from 'node:crypto';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { delegatedAuthorityPublicIdentity, signDelegatedAuthorityStatement } from '../installer-v2/installation-authority.js';
+
+const REQUEST_DOMAIN = 'chati.evidence-authority-certification-request.v1';
+const CERTIFICATE_TYPES = Object.freeze({
+  'rail-evidence': 'chati-rail-evidence-authority', 'clickup-mcp': 'chati-clickup-mcp-authority',
+});
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+
+/** Creates a public request, never an enrolled certificate or a trusted verdict. */
+export function createEvidenceAuthorityRequest({ projectDir, kind, validForDays = 30, clock = () => new Date(), authorityDirectory } = {}) {
+  if (!Object.hasOwn(CERTIFICATE_TYPES, kind ?? '')) fail('INVALID_AUTHORITY_REQUEST_KIND', 'kind must be rail-evidence or clickup-mcp');
+  if (!Number.isInteger(validForDays) || validForDays < 1 || validForDays > 90) fail('INVALID_AUTHORITY_REQUEST_LIFETIME', 'requested validity must be 1 to 90 days');
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'a certification request requires a verified v2 installation');
+  const observed = clock();
+  const now = (observed instanceof Date ? observed : new Date(observed)).getTime();
+  if (!Number.isFinite(now)) fail('INVALID_AUTHORITY_REQUEST_TIME', 'certification request requires a valid time');
+  const identityOptions = { projectDir, projectId: artifact.project_id, kind, authorityDirectory };
+  const identity = delegatedAuthorityPublicIdentity({ ...identityOptions, create: true });
+  const request = {
+    schema_version: 1, request_type: REQUEST_DOMAIN,
+    requested_issuer_implementation: 'chati-local-evidence-observer-v1',
+    project_binding_digest: identity.project_binding_digest,
+    certificate_payload: {
+      schema_version: 1, certificate_type: CERTIFICATE_TYPES[kind], project_id: artifact.project_id,
+      issuer_id: identity.issuer_id, public_key: identity.public_key,
+      not_before: new Date(now).toISOString(), expires_at: new Date(now + validForDays * 86400000).toISOString(),
+    },
+  };
+  const proof = signDelegatedAuthorityStatement(request, identityOptions);
+  // A concurrent key replacement must not produce a request with mismatched proof.
+  if (proof.issuer_id !== identity.issuer_id
+    || !verify(null, Buffer.from(canonicalSerialize(request)), createPublicKey(identity.public_key), Buffer.from(proof.signature, 'base64'))) {
+    fail('AUTHORITY_REQUEST_IDENTITY_CHANGED', 'delegated identity changed while creating its public request');
+  }
+  return Object.freeze({
+    ok: true, action: 'rail_authority_certification_requested', certified: false,
+    request_id: `authority-request-${sha256(request)}`, request,
+    proof_of_possession: proof.signature,
+    next_required_action: 'authorized_root_reviews_issuer_and_signs_certificate_then_enroll',
+  });
+}

package/src/orchestrator/handoff-engine.js

@@ -10,9 +10,10 @@ import { readAgentMemory } from '../memory/agent-memory.js';
 import { getRelevantGotchas } from '../memory/gotchas.js';
 import { updateProjectContext } from '../memory/magic-docs.js';
 import { generateContextFiles } from '../config/context-file-generator.js';
-import { existsSync, readdirSync } from 'fs';
+import { existsSync } from 'fs';
 import { join } from 'path';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { listHandoffAgents } from '../utils/handoff-paths.js';
 
 /**
  * Execute a full agent-to-agent handoff.
@@ -228,17 +229,9 @@ export function loadHandoffContext(projectDir, fromAgent) {
  * @returns {object[]} Array of handoff summaries
  */
 export function getHandoffHistory(projectDir) {
-  const handoffsDir = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs');
-
-  if (!existsSync(handoffsDir)) {
-    return [];
-  }
-
   try {
-    const files = readdirSync(handoffsDir)
-      .filter(f => f.endsWith('-handoff.md'))
-      .map(f => {
-        const agentName = f.replace('-handoff.md', '');
+    const files = listHandoffAgents(projectDir)
+      .map(agentName => {
         const result = loadHandoff(projectDir, agentName);
 
         if (!result.loaded) {

package/src/orchestrator/pipeline-manager.js

@@ -138,6 +138,24 @@ function loadQaThresholds(projectDir) {
   return out;
 }
 
+export function getQaThreshold(agent, projectDir) {
+  return loadQaThresholds(projectDir)[agent] ?? null;
+}
+
+/** A controller may explicitly reopen completed Planning dependencies, never advance. */
+export function assertQaCorrectionTarget(state, agent, results) {
+  if (!results.correctionTarget) return;
+  const rejected = results.qaVerdict === 'needs_correction'
+    || (Number.isFinite(results.score) && results.score < getQaThreshold(agent, state.targetDir));
+  if (agent !== 'qa-planning' || !rejected
+    || !['detail', 'architect', 'ux'].includes(results.correctionTarget)
+    || !state.completedAgents.includes(results.correctionTarget)
+    || !results.handoffData?.decision_trail_entries?.some(entry => entry.resolved === false)) {
+    throw Object.assign(new Error('An explicit QA correction target requires a completed negative review, unresolved findings, and a completed upstream Planning agent.'),
+      { code: 'INVALID_QA_CORRECTION_TARGET' });
+  }
+}
+
 /**
  * Route a failing QA to the correct rework target via Fault Vector Protocol.
  *
@@ -396,6 +414,7 @@ export function initStandardFlowPipeline(options = {}) {
  * @returns {{ state: object, nextAction: string, nextAgent: string|null, needsModeSwitch: boolean, contextBracket: object }}
  */
 export function advancePipeline(pipelineState, completedAgent, results = {}) {
+  assertQaCorrectionTarget(pipelineState, completedAgent, results);
   const newState = { ...pipelineState };
 
   // Update completed agent status
@@ -406,7 +425,7 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
   newState.agents[completedAgent] = {
     ...newState.agents[completedAgent],
     status: AGENT_STATUS.COMPLETED,
-    score: results.score || null,
+    score: results.score ?? null,
     completedAt: new Date().toISOString(),
   };
 
@@ -426,15 +445,30 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
     agent: completedAgent,
     action: 'completed',
     timestamp: new Date().toISOString(),
-    score: results.score || null,
+    score: results.score ?? null,
   });
 
   // Special handling for QA agents - check if they meet thresholds
   const isQAAgent = completedAgent === 'qa-planning' || completedAgent === 'qa-implementation' || completedAgent === 'qa-visual';
   if (isQAAgent) {
     const transitionCheck = checkPhaseTransition(newState);
+    const rejected = results.qaVerdict === 'needs_correction'
+      || !Number.isFinite(results.score)
+      || results.score < getQaThreshold(completedAgent, newState.targetDir);
+
+    // QA completion precedes Phases/Tasks in Team Mode. Missing later agents
+    // prevent a phase transition, not an otherwise approved QA result.
+    if (completedAgent === 'qa-planning' && newState.phase === 'plan'
+      && !rejected && !transitionCheck.canAdvance
+      && ['phases', 'tasks'].some(agent => newState.agents[agent]?.status !== AGENT_STATUS.COMPLETED)) {
+      return {
+        state: newState, nextAction: 'continue',
+        nextAgent: getNextAgent(completedAgent, newState.completedAgents).next,
+        needsModeSwitch: false, contextBracket,
+      };
+    }
 
-    if (transitionCheck.canAdvance) {
+    if (!rejected && transitionCheck.canAdvance) {
       // User Preview gate: when the final QA gate (qa-visual) passes in build phase,
       // don't advance to deploy yet — let user preview first. (4.3.0+: qa-visual is
       // the final build gate; previously this was qa-implementation.)
@@ -491,11 +525,15 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
       // QA failed — trigger backward transition via Fault Vector Protocol.
       // We re-open the rework target, NOT wait for manual intervention.
       const faultOrigin = (results.faultOrigin || extractPrimaryFaultOrigin(results.handoffData)).toUpperCase();
-      const { nextAgent: correctionTarget, reason: routingReason } = routeByFaultVector(
+      const routed = routeByFaultVector(
         completedAgent,
         faultOrigin,
         newState,
       );
+      const correctionTarget = results.correctionTarget || routed.nextAgent;
+      const routingReason = results.correctionTarget
+        ? `${completedAgent} requires correction; the controller selected upstream ${correctionTarget} from the preserved findings.`
+        : routed.reason;
 
       // DEFER or unroutable — log and stay in wait (legacy behavior)
       if (!correctionTarget) {