create-byan-agent 2.35.0 → 2.38.0

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

@@ -1,6 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { getStatus, MIN_PASSES } from './strict-mode.js';
 import { fetchSession, syncEnabled } from './strict-sync.js';
 
+// F2 (additive): the completeness-evidence gate at commit time. Reads the
+// completeness ledger written by strict complete(). It only ever BLOCKS when
+// delivery-default.json completenessGate.armed === true (default false). With
+// the gate disarmed this is a no-op and the gate decision is exactly as before.
+const DELIVERY_CONFIG_REL = path.join('_byan', '_config', 'delivery-default.json');
+const COMPLETENESS_LEDGER_REL = path.join('_byan-output', 'completeness-ledger.jsonl');
+
+function completenessGateArmed(projectRoot) {
+  try {
+    const p = path.join(projectRoot || process.cwd(), DELIVERY_CONFIG_REL);
+    if (!fs.existsSync(p)) return false;
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return !!(cfg && cfg.completenessGate && cfg.completenessGate.armed === true);
+  } catch {
+    return false; // A broken/absent config never arms the gate.
+  }
+}
+
+// Last completeness-ledger entry for the given scope_hash, or null. Best-effort.
+function lastCompletenessEntry(projectRoot, scopeHash) {
+  try {
+    const p = path.join(projectRoot || process.cwd(), COMPLETENESS_LEDGER_REL);
+    if (!fs.existsSync(p)) return null;
+    const lines = fs
+      .readFileSync(p, 'utf8')
+      .split('\n')
+      .filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const e = JSON.parse(lines[i]);
+        if (!scopeHash || e.scope_hash === scopeHash) return e;
+      } catch {
+        // skip a malformed line
+      }
+    }
+  } catch {
+    // unreadable ledger -> treat as no evidence record
+  }
+  return null;
+}
+
+// Pure overlay: given a base decision (PASS), apply the armed completeness gate.
+// Returns the base decision untouched when disarmed or when the base already
+// blocks; otherwise blocks when the completeness ledger shows missing criteria.
+export function applyCompletenessGate(base, { armed, entry }) {
+  if (!base.pass || !armed) return base;
+  if (entry && Array.isArray(entry.missing) && entry.missing.length) {
+    return {
+      pass: false,
+      reason:
+        `Completeness gate ARMED: the completed strict session left ` +
+        `${entry.missing.length} code-shaped criteria without evidence ` +
+        `(${entry.missing.join('; ')}). Provide the artifacts before committing.`,
+    };
+  }
+  return base;
+}
+
 // BYAN Strict Mode pre-commit gate.
 //
 // The final, platform-agnostic net. Claude Code has in-session hooks; Codex
@@ -104,6 +164,7 @@ export async function evaluateGate({ projectRoot, fetchImpl } = {}) {
   const local = getStatus({ projectRoot });
   const normalizedLocal = normalizeLocal(local);
 
+  let base;
   // Consult the authority when there is a session to check and a token is set.
   if (normalizedLocal.sessionId && syncEnabled()) {
     const remote = await fetchSession(
@@ -111,10 +172,15 @@ export async function evaluateGate({ projectRoot, fetchImpl } = {}) {
       fetchImpl ? { fetchImpl } : {}
     );
     if (remote.ok && remote.data) {
-      return decide(normalizeApi(remote.data));
+      base = decide(normalizeApi(remote.data));
     }
     // API unreachable / not found -> fall back to local mirror.
   }
+  if (!base) base = decide(normalizedLocal);
 
-  return decide(normalizedLocal);
+  // F2 overlay: disarmed by default -> returns `base` unchanged.
+  const armed = completenessGateArmed(projectRoot);
+  if (!armed) return base;
+  const entry = lastCompletenessEntry(projectRoot, local.scope_hash);
+  return applyCompletenessGate(base, { armed, entry });
 }

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

@@ -1,12 +1,50 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { buildEvidence } from './completeness-evidence.js';
 
 const STRICT_DIR = '.byan-strict';
 const STATE_FILE = 'state.json';
 const AUDIT_FILE = 'audit.log';
 const MIN_SELF_VERIFY_PASSES = 3;
 
+// F2 completeness-evidence gate. complete() ATTACHES an evidence report and, when
+// the gate is ARMED (delivery-default.json completenessGate.armed === true),
+// hard-rejects a completion that leaves code-shaped criteria without evidence.
+// Default DISARMED: complete() behaves exactly as before (passCount >= 3 + last
+// verdict ok), the report is pure observation, and every completion appends one
+// line to the completeness ledger so arming later is data-informed.
+const DELIVERY_CONFIG_REL = path.join('_byan', '_config', 'delivery-default.json');
+const COMPLETENESS_LEDGER_REL = path.join('_byan-output', 'completeness-ledger.jsonl');
+
+function readDeliveryConfig(projectRoot) {
+  try {
+    const p = path.join(resolveRoot(projectRoot), DELIVERY_CONFIG_REL);
+    if (fs.existsSync(p)) {
+      const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (cfg && typeof cfg === 'object') return cfg;
+    }
+  } catch {
+    // A broken config must NOT arm the gate — fail safe toward disarmed.
+  }
+  return {};
+}
+
+function completenessGateArmed(config) {
+  const g = config && config.completenessGate;
+  return !!(g && g.armed === true);
+}
+
+function appendCompletenessLedger(entry, projectRoot) {
+  try {
+    const p = path.join(resolveRoot(projectRoot), COMPLETENESS_LEDGER_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  } catch {
+    // The observation ledger is best-effort — never break completion.
+  }
+}
+
 function resolveRoot(projectRoot) {
   return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -234,7 +272,7 @@ export function selfVerify({
   };
 }
 
-export function complete({ projectRoot, now = new Date() } = {}) {
+export function complete({ projectRoot, now = new Date(), context = {}, evidenceIo } = {}) {
   const state = readState(projectRoot);
   if (!state || !state.active) {
     throw new Error('No active strict session.');
@@ -258,6 +296,42 @@ export function complete({ projectRoot, now = new Date() } = {}) {
     );
   }
 
+  // F2 (additive): collect the completeness-evidence report over the locked
+  // criteria + allowed paths. Always observed + ledgered; only ENFORCED when the
+  // gate is armed in delivery-default.json (default false -> behaviour unchanged).
+  const deliveryConfig = readDeliveryConfig(projectRoot);
+  const gateArmed = completenessGateArmed(deliveryConfig);
+  const evidence = buildEvidence({
+    criteria: state.scope_lock.acceptance_criteria || [],
+    allowedPaths: state.scope_lock.allowed_paths || [],
+    context,
+    projectRoot: resolveRoot(projectRoot),
+    io: evidenceIo,
+  });
+  appendCompletenessLedger(
+    {
+      ts: now.toISOString(),
+      event: gateArmed ? (evidence.missing.length ? 'would-reject' : 'pass') : 'observed-disarmed',
+      strict_session_id: state.strict_session_id,
+      scope_hash: state.scope_lock.scope_hash,
+      armed: gateArmed,
+      missing: evidence.missing,
+      per_criterion: evidence.perCriterion.map((c) => ({
+        criterion: c.criterion,
+        kind: c.kind,
+        hasEvidence: c.hasEvidence,
+      })),
+    },
+    projectRoot
+  );
+  if (gateArmed && evidence.missing.length) {
+    throw new Error(
+      `Cannot complete: completeness gate is ARMED and ${evidence.missing.length} ` +
+        `code-shaped criteria have no evidence (file / green test / diff): ` +
+        `${evidence.missing.join('; ')}. Provide the missing artifacts or re-lock the scope.`
+    );
+  }
+
   const auditEntries = readAuditLog(projectRoot);
   const auditPayload = JSON.stringify({
     scope_hash: state.scope_lock.scope_hash,
@@ -296,6 +370,9 @@ export function complete({ projectRoot, now = new Date() } = {}) {
     // Surfaced for the C3 learning-loop feed: an explicit ELO domain on the
     // locked scope means a completed session is a VALIDATED outcome.
     domain: state.scope_lock.domain || '',
+    // F2 (additive): the completeness-evidence report. Attached whether or not
+    // the gate is armed; with the gate disarmed it is pure observation.
+    evidence,
   };
 }
 

package/install/templates/docs/leantime-integration.md

@@ -13,7 +13,7 @@ events:
 | FD phase / event | Effect on the board |
 |------------------|---------------------|
 | DISCOVERY (project confirmed) | create-or-fetch the Leantime project |
-| DISPATCH (per backlog feature) | one task per feature |
+| DISPATCH (per backlog feature) | one task per feature, with effort (storypoints), priority and a description |
 | BUILD (feature starts) | task -> column `doing` |
 | REVIEW needs-rework / VALIDATE KO | task -> column `blocked` |
 | VALIDATE OK | task -> column `review` |
@@ -23,6 +23,16 @@ The FD lifecycle columns (`todo|doing|blocked|review|done`) are resolved to the
 project's configured Leantime status ids at call time (statuses are per-project
 ints), with a conservative fallback when the labels cannot be read.
 
+Each created task also carries the BYAN signal, not just a bare title:
+
+- **effort** -- `storypoints` from the feature's complexity: a finite `complexity`
+  (0-100) bucketed on the Fibonacci scale (`<=15->2`, `16-39->5`, `40-69->8`,
+  `>=70->13`), else derived from priority (`P1->8`, `P2->5`, `P3->3`, default 3).
+- **priority** -- `P1`/`P2`/`P3` mapped to Leantime `3`/`2`/`1` (omitted when unknown).
+- **description** -- `BYAN FD <id> -- <headline>`, plus `[complexity:N]` when known.
+  It also carries the complexity if the Leantime effort field name differs from
+  the presumed `storypoints` (a `[UNVERIFIED]` wire detail, see Troubleshooting).
+
 ## Automatic sync (the leantime-fd-sync hook)
 
 You do not call the `byan_leantime_*` tools by hand. A Claude Code `PostToolUse`

package/node_modules/byan-platform-config/lib/mcp-config.js

@@ -27,6 +27,13 @@ const path = require('path');
 const fs = require('fs-extra');
 
 const MCP_SERVER_REL_PATH = '_byan/mcp/byan-mcp-server/server.js';
+// Channel entrypoint: a SEPARATE MCP server (research preview) spawned by Claude
+// Code via --dangerously-load-development-channels. Same relative-path discipline
+// as the main server (relative to projectRoot, never absolute) so the entry is
+// portable across machines/OSes and stays valid when the repo is moved or shipped
+// via npm. The entry is INERT by default: registering it in .mcp.json does NOT
+// enable the channel (that needs the explicit --dangerously-load flag at launch).
+const MCP_CHANNEL_REL_PATH = '_byan/mcp/byan-mcp-server/channel-entry.js';
 const TOKEN_PLACEHOLDER = '${BYAN_API_TOKEN}';
 const LEANTIME_URL_PLACEHOLDER = '${LEANTIME_API_URL}';
 const LEANTIME_TOKEN_PLACEHOLDER = '${LEANTIME_API_TOKEN}';
@@ -87,15 +94,66 @@ function mergeByanEntry(existingConfig, { apiUrl, token } = {}) {
   delete env.BYAN_API_URL;
   delete env.BYAN_API_TOKEN;
 
+  // The canonical RELATIVE path is forced on `args` AFTER ...existing so it always
+  // wins -- this REPAIRS a stale entry that carried an absolute path (a pre-2.37.x
+  // install): relative survives a moved / npm-shipped repo, absolute does not, and
+  // Claude Code spawns the server with cwd=projectRoot so the relative path resolves
+  // identically. `command` is only F1-orthogonal (the interpreter, not a path), so a
+  // user-chosen command is preserved; we default to 'node' only when absent. Other
+  // pre-existing keys are still preserved.
   const entry = {
-    command: 'node',
-    args: [MCP_SERVER_REL_PATH],
     ...existing,
+    command: existing.command || 'node',
+    args: [MCP_SERVER_REL_PATH],
   };
   if (Object.keys(env).length > 0) entry.env = env;
   else delete entry.env;
 
   cfg.mcpServers.byan = entry;
+
+  // The channel entry is written alongside byan from the SAME merge so there is
+  // a single source of truth for the byan MCP registration. It is inert.
+  return mergeChannelEntry(cfg);
+}
+
+/**
+ * Pure merge — no I/O. Adds the `byan-channel` MCP server entry alongside byan.
+ *
+ * This entry is a Claude Code research-preview channel (CC v2.1.80+). It is
+ * INERT by default: present in .mcp.json but only loaded when the user launches
+ * with `claude --dangerously-load-development-channels server:byan-channel`.
+ * Registering it does NOT auto-activate anything — this function writes NO
+ * channelsEnabled / allowedChannelPlugins / --dangerously-load flag.
+ *
+ * Same portability discipline as the byan entry: a RELATIVE path (never
+ * absolute), no secret in env (the channel resolves its own config at boot via
+ * resolve-config.js: env -> ~/.byan/credentials.json -> defaults). An existing
+ * byan-channel entry is preserved (command/args/env) so the merge is idempotent.
+ *
+ * @param {object} existingConfig — current parsed config
+ * @returns {object} new merged config
+ */
+function mergeChannelEntry(existingConfig) {
+  const cfg = existingConfig && typeof existingConfig === 'object' ? { ...existingConfig } : {};
+  cfg.mcpServers = { ...(cfg.mcpServers || {}) };
+
+  const existing = cfg.mcpServers['byan-channel'] || {};
+
+  // The canonical RELATIVE path + the empty (secret-free) env are forced AFTER
+  // ...existing so they always win, normalizing a stale entry (absolute path, or
+  // a stray env) while preserving any other pre-existing key. env stays empty: the
+  // channel resolves BYAN_API_URL/TOKEN itself via resolve-config.js -- writing a
+  // secret here would land it in tracked git, and the channel has no legitimate
+  // env contract of its own (Leantime refs live on the byan entry). `command` is
+  // F1-orthogonal so a user-chosen interpreter is preserved, 'node' only as the
+  // default. Idempotent: re-running yields the same entry.
+  cfg.mcpServers['byan-channel'] = {
+    ...existing,
+    command: existing.command || 'node',
+    args: [MCP_CHANNEL_REL_PATH],
+    env: {},
+  };
+
   return cfg;
 }
 
@@ -141,14 +199,20 @@ function mergeLeantimeRefs(existingConfig) {
   env.LEANTIME_API_URL = LEANTIME_URL_PLACEHOLDER;
   env.LEANTIME_API_TOKEN = LEANTIME_TOKEN_PLACEHOLDER;
 
+  // Same discipline as mergeByanEntry: args forced to the canonical RELATIVE path
+  // (normalizes a stale absolute one), command preserved (F1-orthogonal), env
+  // carries the merged Leantime refs.
   cfg.mcpServers.byan = {
-    command: 'node',
-    args: [MCP_SERVER_REL_PATH],
     ...existing,
+    command: existing.command || 'node',
+    args: [MCP_SERVER_REL_PATH],
     env,
   };
 
-  return cfg;
+  // Keep the channel entry coherent with the byan entry: ensureLeantimeRefs runs
+  // after ensureMcpConfig in the installer, but routing through mergeChannelEntry
+  // here makes the byan-channel registration robust to call order (idempotent).
+  return mergeChannelEntry(cfg);
 }
 
 /**
@@ -252,12 +316,14 @@ module.exports = {
   ensureMcpConfig,
   readMcpConfig,
   mergeByanEntry,
+  mergeChannelEntry,
   mergeLeantimeRefs,
   ensureLeantimeRefs,
   addMcpEntry,
   removeMcpEntry,
   looksLikeSecret,
   MCP_SERVER_REL_PATH,
+  MCP_CHANNEL_REL_PATH,
   TOKEN_PLACEHOLDER,
   LEANTIME_URL_PLACEHOLDER,
   LEANTIME_TOKEN_PLACEHOLDER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.35.0",
+  "version": "2.38.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {

package/install/templates/.mcp.json.tmpl

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "byan": {
-      "command": "node",
-      "args": ["{{PROJECT_ROOT}}/_byan/mcp/byan-mcp-server/server.js"]
-    }
-  }
-}