create-byan-agent 2.16.1 → 2.17.1

package/install/templates/_byan/mcp/byan-mcp-server/lib/fd-state.js

@@ -70,7 +70,7 @@ function stampId(now = new Date(), slug) {
   return `${s}-${slugify(slug)}`;
 }
 
-export function start({ featureName, projectRoot, now = new Date(), force = false } = {}) {
+export function start({ featureName, projectRoot, now = new Date(), force = false, strict = false } = {}) {
   const existing = readState(projectRoot);
   if (existing && !['COMPLETED', 'ABORTED'].includes(existing.phase) && !force) {
     throw new Error(
@@ -82,6 +82,7 @@ export function start({ featureName, projectRoot, now = new Date(), force = fals
     fd_id: stampId(now, featureName),
     feature_name: featureName || 'unnamed',
     phase: 'DISCOVERY',
+    strict_mode: Boolean(strict),
     started_at: now.toISOString(),
     updated_at: now.toISOString(),
     phase_history: [{ phase: 'DISCOVERY', entered_at: now.toISOString() }],

package/install/templates/_byan/mcp/byan-mcp-server/lib/precommit-gate.js

@@ -0,0 +1,120 @@
+import { getStatus, MIN_PASSES } from './strict-mode.js';
+import { fetchSession, syncEnabled } from './strict-sync.js';
+
+// BYAN Strict Mode pre-commit gate.
+//
+// The final, platform-agnostic net. Claude Code has in-session hooks; Codex
+// and Copilot do not. This gate runs at commit time on every platform, so an
+// agent that engaged strict mode but bailed on verification cannot land the
+// commit.
+//
+// The byan_web API is the authority. At commit time the gate asks the API for
+// the session record and judges that; the local .byan-strict/ mirror is the
+// fallback only when the API is genuinely unreachable (so an offline machine
+// is not hard-blocked, but online the server's word is final).
+//
+// Decision (same on either source) :
+//   - No strict session                    -> PASS (strict was not engaged).
+//   - Session aborted                       -> PASS (deliberate, audited exit).
+//   - Session engaged but not completed     -> BLOCK.
+//   - Completed but < min passes
+//     or last verdict not "ok"              -> BLOCK (completion was not earned).
+//   - Completed correctly                   -> PASS.
+
+// Pure decision over a normalized status shape:
+//   { hasSession, active, scopeLocked, completed, passCount, minPasses, passes:[{verdict}], auditToken, sessionId }
+export function decide(status) {
+  if (!status || !status.hasSession) {
+    return { pass: true, reason: 'no strict session — strict mode not engaged' };
+  }
+  if (status.active === false && !status.completed) {
+    return { pass: true, reason: 'strict session aborted (audited) — allowed' };
+  }
+  if (!status.scopeLocked) {
+    return { pass: true, reason: 'no scope locked — strict mode not engaged' };
+  }
+  if (!status.completed) {
+    return {
+      pass: false,
+      reason:
+        `Strict session ${status.sessionId} is engaged but not completed ` +
+        `(${status.passCount}/${status.minPasses} self-verify passes). ` +
+        `Run byan_strict_self_verify until satisfied, then byan_strict_complete. ` +
+        `To exit strict mode deliberately, call byan_strict_abort.`,
+    };
+  }
+  if (status.passCount < status.minPasses) {
+    return {
+      pass: false,
+      reason:
+        `Strict session completed with only ${status.passCount}/${status.minPasses} ` +
+        `self-verify passes. This should not happen — investigate the audit trail.`,
+    };
+  }
+  const passes = status.passes || [];
+  const last = passes[passes.length - 1];
+  if (!last || last.verdict !== 'ok') {
+    return {
+      pass: false,
+      reason:
+        `Strict session completed but the last self-verify verdict was ` +
+        `"${last ? last.verdict : 'none'}" (must be "ok").`,
+    };
+  }
+  return {
+    pass: true,
+    reason: `strict session completed (${status.source}): ${status.passCount} passes, audit token ${status.auditToken}`,
+  };
+}
+
+function normalizeLocal(local) {
+  const noState =
+    local.active === false && !local.scope_locked && !local.completed;
+  return {
+    source: 'local',
+    hasSession: !noState,
+    active: local.active,
+    scopeLocked: Boolean(local.scope_locked),
+    completed: Boolean(local.completed),
+    passCount: local.pass_count || 0,
+    minPasses: local.min_passes || MIN_PASSES,
+    passes: local.passes || [],
+    auditToken: local.audit_token || null,
+    sessionId: local.strict_session_id || null,
+  };
+}
+
+function normalizeApi(api) {
+  const passes = (api.passes || []).map((p) => ({ verdict: p.verdict }));
+  return {
+    source: 'api',
+    hasSession: true,
+    active: api.active !== false && !api.aborted && !api.completed,
+    scopeLocked: true,
+    completed: Boolean(api.completed),
+    passCount: passes.length,
+    minPasses: MIN_PASSES,
+    passes,
+    auditToken: api.audit_token || null,
+    sessionId: api.id || null,
+  };
+}
+
+export async function evaluateGate({ projectRoot, fetchImpl } = {}) {
+  const local = getStatus({ projectRoot });
+  const normalizedLocal = normalizeLocal(local);
+
+  // Consult the authority when there is a session to check and a token is set.
+  if (normalizedLocal.sessionId && syncEnabled()) {
+    const remote = await fetchSession(
+      { sessionId: normalizedLocal.sessionId },
+      fetchImpl ? { fetchImpl } : {}
+    );
+    if (remote.ok && remote.data) {
+      return decide(normalizeApi(remote.data));
+    }
+    // API unreachable / not found -> fall back to local mirror.
+  }
+
+  return decide(normalizedLocal);
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/strict-activation.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+// Strict-mode activation detector.
+//
+// Reads the activation keywords from the single source of truth
+// (_byan/_config/strict-mode.yaml) and reports whether a piece of text
+// (a user request, a feature name) signals a production-grade deliverable
+// that should be built under strict mode.
+//
+// This is the platform-agnostic counterpart to the strict-context-inject
+// hook : Codex and Copilot have no in-session hook, so they call
+// byan_strict_suggest to get the same signal.
+
+const DEFAULT_CONFIG_REL = path.join('_byan', '_config', 'strict-mode.yaml');
+const FALLBACK_KEYWORDS = [
+  'prod',
+  'production',
+  'client',
+  'contrat',
+  'template officiel',
+  'livrable',
+  'deliverable',
+  'release',
+];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function loadKeywords({ projectRoot, configPath } = {}) {
+  const file = configPath || path.join(resolveRoot(projectRoot), DEFAULT_CONFIG_REL);
+  try {
+    if (fs.existsSync(file)) {
+      const cfg = yaml.load(fs.readFileSync(file, 'utf8'));
+      const kw = cfg && cfg.activation && cfg.activation.auto_keywords;
+      if (Array.isArray(kw) && kw.length > 0) return kw;
+    }
+  } catch {
+    // fall through to fallback list
+  }
+  return FALLBACK_KEYWORDS;
+}
+
+function matchKeyword(text, keyword) {
+  const kw = String(keyword).toLowerCase();
+  const lower = text.toLowerCase();
+  // Single alphabetic words match on word boundary to avoid false hits
+  // (e.g. "prod" should not match "reproduction").
+  if (/^[a-z]+$/.test(kw)) {
+    return new RegExp(`\\b${kw}\\b`).test(lower);
+  }
+  return lower.includes(kw);
+}
+
+export function detectActivation({ text, projectRoot, configPath } = {}) {
+  if (!text || typeof text !== 'string') {
+    return { suggested: false, matched: [], message: '' };
+  }
+  const keywords = loadKeywords({ projectRoot, configPath });
+  const matched = keywords.filter((k) => matchKeyword(text, k));
+
+  if (matched.length === 0) {
+    return { suggested: false, matched: [], message: '' };
+  }
+
+  const message =
+    `The request mentions ${matched.map((m) => `"${m}"`).join(', ')}, ` +
+    `which signals a production-grade deliverable. Lock strict mode with ` +
+    `byan_strict_lock_scope (verbatim scope + testable acceptance criteria) ` +
+    `before building. Strict mode enforces self-verification and a 95% ` +
+    `confidence floor on hard claims.`;
+
+  return { suggested: true, matched, message };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/strict-mode.js

@@ -0,0 +1,391 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const STRICT_DIR = '.byan-strict';
+const STATE_FILE = 'state.json';
+const AUDIT_FILE = 'audit.log';
+const MIN_SELF_VERIFY_PASSES = 3;
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function strictDir(projectRoot) {
+  return path.join(resolveRoot(projectRoot), STRICT_DIR);
+}
+
+function statePath(projectRoot) {
+  return path.join(strictDir(projectRoot), STATE_FILE);
+}
+
+function auditPath(projectRoot) {
+  return path.join(strictDir(projectRoot), AUDIT_FILE);
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state, projectRoot) {
+  const p = statePath(projectRoot);
+  ensureDir(p);
+  fs.writeFileSync(p, JSON.stringify(state, null, 2));
+  return p;
+}
+
+function appendAudit(entry, projectRoot) {
+  const p = auditPath(projectRoot);
+  ensureDir(p);
+  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  return p;
+}
+
+function readAuditLog(projectRoot) {
+  const p = auditPath(projectRoot);
+  if (!fs.existsSync(p)) return [];
+  const raw = fs.readFileSync(p, 'utf8');
+  return raw
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function hashScope(scopeText, acceptanceCriteria, allowedPaths) {
+  const payload = JSON.stringify({
+    scope: String(scopeText || '').trim(),
+    criteria: Array.isArray(acceptanceCriteria) ? acceptanceCriteria : [],
+    paths: Array.isArray(allowedPaths) ? allowedPaths : [],
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+
+function stampId(now, slug) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const s =
+    now.getFullYear().toString() +
+    pad(now.getMonth() + 1) +
+    pad(now.getDate()) +
+    '-' +
+    pad(now.getHours()) +
+    pad(now.getMinutes()) +
+    pad(now.getSeconds());
+  return `${s}-${slug || 'strict'}`;
+}
+
+function emptyState(now) {
+  return {
+    strict_session_id: stampId(now, 'session'),
+    active: true,
+    started_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    scope_lock: null,
+    self_verify_passes: [],
+    completed: false,
+    completed_at: null,
+    audit_token: null,
+  };
+}
+
+export function lockScope({
+  scopeText,
+  acceptanceCriteria = [],
+  allowedPaths = [],
+  projectRoot,
+  now = new Date(),
+  force = false,
+} = {}) {
+  if (!scopeText || typeof scopeText !== 'string' || scopeText.trim().length < 10) {
+    throw new Error(
+      'scopeText must be a non-empty string of at least 10 chars describing the locked scope.'
+    );
+  }
+  if (!Array.isArray(acceptanceCriteria) || acceptanceCriteria.length === 0) {
+    throw new Error(
+      'acceptanceCriteria must be a non-empty array of strings (explicit deliverables).'
+    );
+  }
+
+  const scopeHash = hashScope(scopeText, acceptanceCriteria, allowedPaths);
+
+  let state = readState(projectRoot);
+  if (state && state.active && state.scope_lock && !state.completed && !force) {
+    if (state.scope_lock.scope_hash === scopeHash) {
+      return state.scope_lock;
+    }
+    throw new Error(
+      `Scope already locked with hash ${state.scope_lock.scope_hash}. Pass force=true to relock, or call abort() first.`
+    );
+  }
+
+  if (!state || state.completed || force) {
+    state = emptyState(now);
+  }
+
+  state.scope_lock = {
+    scope_hash: scopeHash,
+    scope_text: scopeText.trim(),
+    acceptance_criteria: acceptanceCriteria,
+    allowed_paths: allowedPaths,
+    locked_at: now.toISOString(),
+  };
+  state.updated_at = now.toISOString();
+  state.self_verify_passes = [];
+  state.completed = false;
+  state.completed_at = null;
+  state.audit_token = null;
+
+  writeState(state, projectRoot);
+  appendAudit(
+    {
+      ts: now.toISOString(),
+      event: 'lock_scope',
+      strict_session_id: state.strict_session_id,
+      scope_hash: scopeHash,
+      scope_text: state.scope_lock.scope_text,
+      acceptance_criteria: acceptanceCriteria,
+      allowed_paths: allowedPaths,
+    },
+    projectRoot
+  );
+
+  return state.scope_lock;
+}
+
+export function selfVerify({
+  findings = [],
+  verdict,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  const state = readState(projectRoot);
+  if (!state || !state.active) {
+    throw new Error('No active strict session. Call lockScope() first.');
+  }
+  if (!state.scope_lock) {
+    throw new Error('Scope is not locked. Call lockScope() first.');
+  }
+  if (state.completed) {
+    throw new Error(
+      'Strict session already completed. Call abort() or lockScope({force:true}) to restart.'
+    );
+  }
+  if (!['ok', 'gap'].includes(verdict)) {
+    throw new Error('verdict must be "ok" (no gap) or "gap" (gap detected).');
+  }
+  if (verdict === 'gap' && (!Array.isArray(findings) || findings.length === 0)) {
+    throw new Error('When verdict is "gap", findings must be a non-empty array of strings.');
+  }
+  if (!Array.isArray(findings)) {
+    throw new Error('findings must be an array of strings (can be empty when verdict is "ok").');
+  }
+
+  const passNumber = state.self_verify_passes.length + 1;
+  const passEntry = {
+    pass: passNumber,
+    completed_at: now.toISOString(),
+    findings: findings.map((f) => String(f)),
+    verdict,
+  };
+  state.self_verify_passes.push(passEntry);
+  state.updated_at = now.toISOString();
+
+  writeState(state, projectRoot);
+  appendAudit(
+    {
+      ts: now.toISOString(),
+      event: 'self_verify',
+      strict_session_id: state.strict_session_id,
+      scope_hash: state.scope_lock.scope_hash,
+      pass: passNumber,
+      verdict,
+      findings: passEntry.findings,
+    },
+    projectRoot
+  );
+
+  return {
+    pass_count: state.self_verify_passes.length,
+    pass: passNumber,
+    verdict,
+    remaining_passes: Math.max(0, MIN_SELF_VERIFY_PASSES - state.self_verify_passes.length),
+  };
+}
+
+export function complete({ projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state || !state.active) {
+    throw new Error('No active strict session.');
+  }
+  if (!state.scope_lock) {
+    throw new Error('Scope is not locked.');
+  }
+  if (state.completed) {
+    throw new Error('Strict session already completed.');
+  }
+  const passCount = state.self_verify_passes.length;
+  if (passCount < MIN_SELF_VERIFY_PASSES) {
+    throw new Error(
+      `Cannot complete: ${passCount}/${MIN_SELF_VERIFY_PASSES} self-verify passes done. Run selfVerify() at least ${MIN_SELF_VERIFY_PASSES - passCount} more times.`
+    );
+  }
+  const lastPass = state.self_verify_passes[state.self_verify_passes.length - 1];
+  if (lastPass.verdict !== 'ok') {
+    throw new Error(
+      `Cannot complete: last self-verify pass returned verdict="${lastPass.verdict}". Final pass must be "ok" (zero gaps).`
+    );
+  }
+
+  const auditEntries = readAuditLog(projectRoot);
+  const auditPayload = JSON.stringify({
+    scope_hash: state.scope_lock.scope_hash,
+    audit: auditEntries,
+    ts: now.toISOString(),
+  });
+  const auditToken = crypto
+    .createHash('sha256')
+    .update(auditPayload)
+    .digest('hex')
+    .slice(0, 24);
+
+  state.completed = true;
+  state.completed_at = now.toISOString();
+  state.audit_token = auditToken;
+  state.updated_at = now.toISOString();
+
+  writeState(state, projectRoot);
+  appendAudit(
+    {
+      ts: now.toISOString(),
+      event: 'complete',
+      strict_session_id: state.strict_session_id,
+      scope_hash: state.scope_lock.scope_hash,
+      pass_count: passCount,
+      audit_token: auditToken,
+    },
+    projectRoot
+  );
+
+  return {
+    audit_token: auditToken,
+    scope_hash: state.scope_lock.scope_hash,
+    pass_count: passCount,
+    completed_at: state.completed_at,
+  };
+}
+
+export function getStatus({ projectRoot } = {}) {
+  const state = readState(projectRoot);
+  if (!state) {
+    return {
+      active: false,
+      scope_locked: false,
+      pass_count: 0,
+      completed: false,
+      min_passes: MIN_SELF_VERIFY_PASSES,
+    };
+  }
+  return {
+    active: state.active,
+    strict_session_id: state.strict_session_id,
+    scope_locked: Boolean(state.scope_lock),
+    scope_hash: state.scope_lock ? state.scope_lock.scope_hash : null,
+    scope_text: state.scope_lock ? state.scope_lock.scope_text : null,
+    acceptance_criteria: state.scope_lock ? state.scope_lock.acceptance_criteria : [],
+    allowed_paths: state.scope_lock ? state.scope_lock.allowed_paths : [],
+    pass_count: state.self_verify_passes.length,
+    passes: state.self_verify_passes,
+    min_passes: MIN_SELF_VERIFY_PASSES,
+    completed: state.completed,
+    completed_at: state.completed_at,
+    audit_token: state.audit_token,
+    updated_at: state.updated_at,
+  };
+}
+
+export function abort({ reason, projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state) {
+    throw new Error('No strict session to abort.');
+  }
+  state.active = false;
+  state.updated_at = now.toISOString();
+  writeState(state, projectRoot);
+  appendAudit(
+    {
+      ts: now.toISOString(),
+      event: 'abort',
+      strict_session_id: state.strict_session_id,
+      scope_hash: state.scope_lock ? state.scope_lock.scope_hash : null,
+      reason: reason || null,
+    },
+    projectRoot
+  );
+  return { aborted: true, strict_session_id: state.strict_session_id };
+}
+
+export function checkAuditTrail({
+  scopeHash,
+  windowSeconds = 600,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  const state = readState(projectRoot);
+  if (!state || !state.completed) {
+    return {
+      ok: false,
+      reason: 'no_completed_session',
+      detail: 'No completed strict session found in state.json.',
+    };
+  }
+  if (scopeHash && state.scope_lock && state.scope_lock.scope_hash !== scopeHash) {
+    return {
+      ok: false,
+      reason: 'scope_mismatch',
+      detail: `Expected scope_hash=${scopeHash}, found ${state.scope_lock.scope_hash}.`,
+    };
+  }
+  if (state.self_verify_passes.length < MIN_SELF_VERIFY_PASSES) {
+    return {
+      ok: false,
+      reason: 'insufficient_passes',
+      detail: `Only ${state.self_verify_passes.length}/${MIN_SELF_VERIFY_PASSES} self-verify passes.`,
+    };
+  }
+  const completedAt = new Date(state.completed_at).getTime();
+  const ageSeconds = (now.getTime() - completedAt) / 1000;
+  if (ageSeconds > windowSeconds) {
+    return {
+      ok: false,
+      reason: 'audit_expired',
+      detail: `Completion is ${Math.round(ageSeconds)}s old, max allowed is ${windowSeconds}s.`,
+    };
+  }
+  return {
+    ok: true,
+    audit_token: state.audit_token,
+    scope_hash: state.scope_lock.scope_hash,
+    pass_count: state.self_verify_passes.length,
+    completed_at: state.completed_at,
+    age_seconds: Math.round(ageSeconds),
+  };
+}
+
+export const MIN_PASSES = MIN_SELF_VERIFY_PASSES;