@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/comment-lint.mjs

@@ -18,7 +18,7 @@ const JS_HEADER_GLOBS = [
   /^lib\/server\//,
   /^lib\/mcp\//,
   /^lib\/metrics\//,
-  /^sync-agents\.mjs$/,
+  /^sync-specialists\.mjs$/,
   /^tests\//,
 ];
 
@@ -29,10 +29,29 @@ const MD_HEADER_GLOBS = [
   /^commands\//,
 ];
 
+// Artifact paths receive an additional prose-lint pass for fabrication patterns
+// (manufactured confidence, hand-wave percentages, mind-reading, speculation).
+// Scope is deliberately narrow — READMEs, cookbook, concepts, and reference are
+// unaffected. The patterns live in BANNED_ARTIFACT below; the severity (block
+// vs warn) is controlled by CONSTRUCT_ARTIFACT_LINT_MODE.
+const ARTIFACT_PATH_GLOBS = [
+  /^docs\/prd\//,
+  /^docs\/adr\//,
+  /^docs\/rfc\//,
+  /^docs\/research\//,
+  /^\.cx\/knowledge\//,
+  /^\.cx\/handoffs\//,
+  /^\.cx\/research\//,
+];
+
 function relPath(rootDir, absPath) {
   return path.relative(rootDir, absPath).replace(/\\/g, '/');
 }
 
+function isArtifactPath(rel) {
+  return ARTIFACT_PATH_GLOBS.some((r) => r.test(rel));
+}
+
 function requiresHeader(rel) {
   const ext = path.extname(rel);
   if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
@@ -42,6 +61,10 @@ function requiresHeader(rel) {
   if (rel.startsWith('lib/server/static/')) {
     return { required: false, type: null };
   }
+  // Exclude test fixture data files — these are project artifacts, not source files.
+  if (rel.startsWith('tests/fixtures/projects/')) {
+    return { required: false, type: null };
+  }
   // Markdown files always get markdown-style headers, even if the directory
   // glob (e.g. ^tests/) primarily targets JS sources. Without this, .md docs
   // co-located with .mjs tests were forced into /** */ format.
@@ -88,6 +111,13 @@ const BANNED = [
   // step markers — only flag in `//` comments. Ordered lists are
   // conventional inside JSDoc decision-tree and flow documentation.
   { pattern: /\/\/\s+\d+\.\s+\w/, label: 'step marker: use function names or block structure instead of "// 1. Step"' },
+  // deferred-implementation wording: signals incomplete work that should
+  // either ship or be removed before release.
+  { pattern: new RegExp(`${CMT}.*\\bphase\\s+[abc]\\s+follow-?up\\b`, 'i'), label: 'deferred implementation: "Phase X follow-up" — ship it or remove it' },
+  { pattern: new RegExp(`${CMT}.*\\bin a real implementation\\b`, 'i'), label: 'deferred implementation: "in a real implementation" — implement the contract honestly' },
+  { pattern: new RegExp(`${CMT}.*\\bwould go here\\b`, 'i'), label: 'deferred implementation: "would go here" — implement or delete the placeholder' },
+  { pattern: new RegExp(`${CMT}.*\\bcoming soon\\b`, 'i'), label: 'deferred implementation: "coming soon" — not a release-ready statement' },
+  { pattern: new RegExp(`${CMT}.*\\bnot yet supported\\b`, 'i'), label: 'deferred implementation: "not yet supported" — document the supported contract instead' },
   // markdown equivalents
   { pattern: /<!--.*\b(?:added for|added recently|just added|new:)\b.*-->/i, label: 'point-in-time in markdown comment' },
   { pattern: /<!--.*\b(?:used by|called from|only consumer)\b.*-->/i, label: 'caller reference in markdown comment' },
@@ -102,16 +132,111 @@ const BANNED = [
 const BANNED_CHECK_SKIP = [
   'lib/comment-lint.mjs',
   'rules/common/comments.md',
+  'rules/common/no-fabrication.md',
   'tests/comment-lint.test.mjs',
   'commands/work/clean.md',
   'skills/utility/clean-code.md',
 ];
 
+// Artifact-prose patterns. Scoped to ARTIFACT_PATH_GLOBS. Each entry can mark
+// requireCitation: true — in that case the violation is suppressed when a
+// citation (`[source: …]`, http URL, or footnote ref) appears in the same line
+// or within 2 lines of context.
+const BANNED_ARTIFACT = [
+  {
+    pattern: /\b(?:clearly|obviously|undoubtedly|definitely|certainly|surely)\b/i,
+    label: 'manufactured confidence: "clearly/obviously/undoubtedly/etc" smuggles certainty without evidence (no-fabrication §4)',
+  },
+  {
+    pattern: /\b\d{1,3}\s*%/,
+    label: 'unattributed percentage: quantitative claims require a [source: …] citation (no-fabrication §4)',
+    requireCitation: true,
+  },
+  {
+    pattern: /\b(?:users|customers|everyone)\s+(?:want|expect|prefer|agree|need)\b/i,
+    label: 'customer mind-reading: "users want / customers expect / everyone agrees" requires a [source: …] citation (no-fabrication §5)',
+    requireCitation: true,
+  },
+  {
+    pattern: /\b(?:will\s+(?:likely|probably)|should\s+improve|expected\s+to\s+(?:improve|reduce|increase|drop|rise))\b/i,
+    label: 'speculative projection: future-tense claims need a baseline + projection source (no-fabrication §3, §4)',
+    requireCitation: true,
+  },
+];
+
 function isBannedCheckSkipped(filePath) {
   if (!filePath) return false;
   return BANNED_CHECK_SKIP.some((suffix) => filePath.endsWith(suffix));
 }
 
+// Track fenced code blocks ( ``` … ``` ) and YAML frontmatter ( --- … --- )
+// so artifact-prose patterns inside code or metadata are not flagged.
+function buildSkipMap(lines) {
+  const skip = new Array(lines.length).fill(false);
+  let inFence = false;
+  let inFrontmatter = false;
+  let frontmatterClosed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (i === 0 && line.trim() === '---') {
+      inFrontmatter = true;
+      skip[i] = true;
+      continue;
+    }
+    if (inFrontmatter) {
+      skip[i] = true;
+      if (line.trim() === '---') {
+        inFrontmatter = false;
+        frontmatterClosed = true;
+      }
+      continue;
+    }
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      skip[i] = true;
+      continue;
+    }
+    if (inFence) {
+      skip[i] = true;
+      continue;
+    }
+    if (/^\s{0,3}#{1,6}\s/.test(line)) skip[i] = true;
+    // Markdown table rows (start and end with `|`) are typically targets,
+    // specs, or reference lookups, not narrative prose. Skip to keep the
+    // pattern bank focused on the prose surface where embellishment lives.
+    if (/^\s*\|.*\|\s*$/.test(line)) skip[i] = true;
+  }
+  void frontmatterClosed;
+  return skip;
+}
+
+function hasCitationNearby(lines, idx) {
+  const lo = Math.max(0, idx - 2);
+  const hi = Math.min(lines.length, idx + 3);
+  for (let i = lo; i < hi; i++) {
+    if (/\[source:|\bhttps?:\/\/|\[\^\d+\]/i.test(lines[i])) return true;
+  }
+  return false;
+}
+
+function checkArtifactBanned(content, rel) {
+  if (!isArtifactPath(rel)) return [];
+  const lines = content.split('\n');
+  const skip = buildSkipMap(lines);
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (skip[i]) continue;
+    if (lines[i].includes('construct-lint-ignore')) continue;
+    for (const entry of BANNED_ARTIFACT) {
+      if (entry.pattern.test(lines[i])) {
+        if (entry.requireCitation && hasCitationNearby(lines, i)) continue;
+        violations.push({ line: i + 1, label: entry.label, kind: 'artifact' });
+      }
+    }
+  }
+  return violations;
+}
+
 function checkBanned(content, filePath) {
   if (isBannedCheckSkipped(filePath)) return [];
 
@@ -180,6 +305,19 @@ export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}
   const banned = checkBanned(content, filePath);
   for (const w of banned) warnings.push(w);
 
+  // Artifact-prose lint applies to markdown files under intake-fed artifact
+  // paths (PRD, ADR, RFC, research, knowledge, handoffs). Severity is governed
+  // by CONSTRUCT_ARTIFACT_LINT_MODE: 'block' (CLI / release-gate) routes hits
+  // to errors[]; 'warn' (PostToolUse hook default) routes to warnings[] with
+  // kind:'artifact' so the hook can let the edit through while still surfacing
+  // the finding.
+  const artifactHits = checkArtifactBanned(content, rel);
+  if (artifactHits.length > 0) {
+    const mode = process.env.CONSTRUCT_ARTIFACT_LINT_MODE || 'warn';
+    const bucket = mode === 'block' ? errors : warnings;
+    for (const v of artifactHits) bucket.push(v);
+  }
+
   return { path: rel, errors, warnings };
 }
 

package/lib/completions.mjs

@@ -1,7 +1,7 @@
 /**
  * completions.mjs — generates bash and zsh completion scripts for construct.
  *
- * Called by scripts/sync-agents.mjs after each sync.
+ * Called by scripts/sync-specialists.mjs after each sync.
  * Outputs to a platform-appropriate per-user completions directory.
  */
 

package/lib/config/schema.mjs

@@ -6,7 +6,7 @@
  * before npm install completes in some bootstrap paths.
  *
  * Schema v1 covers: alias, deployment, providers, autoEmbed, telemetry.
- * Tier model selection lives in `agents/registry.json` only — this config
+ * Tier model selection lives in `specialists/registry.json` only — this config
  * file is intentionally not a second edit surface for model assignments.
  * Later phases (6, 7b) extend it with `resources` and `costs` blocks
  * without bumping the version — additive keys are allowed.
@@ -22,6 +22,8 @@ export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
 export const DEFAULT_PROFILE_ID = 'rnd';
 
+export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cursor'];
+
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
   alias: 'Construct',
@@ -42,6 +44,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     secondary: null,
     perConversationOverride: true,
   }),
+  hosts: Object.freeze(Object.fromEntries(SURFACES.map((s) => [s, Object.freeze({ enabled: true })]))),
   resources: Object.freeze({
     disk: Object.freeze({
       tracesMaxDays: 30,
@@ -98,6 +101,17 @@ export const FIELD_RULES = {
     },
   },
   resources: { type: 'object', required: false },
+  hosts: {
+    type: 'object',
+    required: false,
+    fields: Object.fromEntries(SURFACES.map((s) => [s, {
+      type: 'object',
+      required: false,
+      fields: {
+        enabled: { type: 'boolean', required: false },
+      },
+    }])),
+  },
   costs: {
     type: 'object',
     required: false,

package/lib/contracts/validate.mjs

@@ -0,0 +1,371 @@
+/**
+ * lib/contracts/validate.mjs — Validate specialists/contracts.json at sync time + at handoff.
+ *
+ * Three validation tiers:
+ *   1. Schema shape: contracts.json conforms to contracts.schema.json (minimal
+ *      validator — top-level required fields, contract entry required fields).
+ *   2. Cross-file refs: every output.schema points to a real file in lib/schemas/,
+ *      every producer/consumer name resolves to an agent or persona in
+ *      specialists/registry.json, every well-known event/intake string is reachable.
+ *   3. Runtime handoff: a single artifact validated against the schema referenced
+ *      by a producer→consumer contract, with mustContain post-conditions.
+ *
+ * Surfaces:
+ *   - scripts/sync-specialists.mjs invokes validateContractsFile at sync time.
+ *   - bin/construct lint:contracts invokes the same path in CI.
+ *   - workflowContractValidate (runtime) invokes validateHandoff per handoff.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
+const CONTRACTS_SCHEMA_PATH = join(REPO_ROOT, 'specialists', 'contracts.schema.json');
+const REGISTRY_PATH = join(REPO_ROOT, 'specialists', 'registry.json');
+
+const WELL_KNOWN_PRODUCERS = new Set(['user', 'oncall', 'incident-system', '*']);
+const WELL_KNOWN_CONSUMERS = new Set(['user', 'construct']);
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Validate specialists/contracts.json shape and cross-file references.
+ * Returns { ok, errors[] } — errors is empty on success.
+ */
+export function validateContractsFile({ contractsPath, registryPath, repoRoot = REPO_ROOT } = {}) {
+  const errors = [];
+
+  // When repoRoot is supplied but explicit paths are not, derive both from it
+  // so test fixtures and the consistency watcher can validate slices in a
+  // tmpdir without pointing at the live repo.
+  const cPath = contractsPath || join(repoRoot, 'specialists', 'contracts.json');
+  const rPath = registryPath || join(repoRoot, 'specialists', 'registry.json');
+  const schemaPath = join(repoRoot, 'specialists', 'contracts.schema.json');
+
+  if (!existsSync(cPath)) {
+    return { ok: false, errors: [`contracts file not found: ${cPath}`] };
+  }
+  if (!existsSync(schemaPath)) {
+    errors.push(`contracts schema missing: ${schemaPath}`);
+  }
+
+  let contracts;
+  try { contracts = readJson(cPath); }
+  catch (err) { return { ok: false, errors: [`contracts.json parse error: ${err.message}`] }; }
+
+  for (const key of ['version', 'terminalStates', 'severities', 'contracts']) {
+    if (!(key in contracts)) errors.push(`contracts.json missing top-level field: ${key}`);
+  }
+
+  const knownNames = collectAgentNames(rPath);
+
+  if (Array.isArray(contracts.contracts)) {
+    const ids = new Set();
+    contracts.contracts.forEach((c, idx) => {
+      const where = `contracts[${idx}]${c.id ? ` (${c.id})` : ''}`;
+      if (!c.id) errors.push(`${where}: missing id`);
+      else if (!/^[a-z0-9][a-z0-9-]*$/.test(c.id)) errors.push(`${where}: id must be kebab-case`);
+      else if (ids.has(c.id)) errors.push(`${where}: duplicate id`);
+      else ids.add(c.id);
+
+      if (!c.producer) errors.push(`${where}: missing producer`);
+      if (!c.consumer) errors.push(`${where}: missing consumer`);
+      if (!c.input) errors.push(`${where}: missing input`);
+
+      if (c.producer && !nameResolves(c.producer, knownNames, 'producer')) {
+        errors.push(`${where}: producer '${c.producer}' is not an agent/persona in registry.json and is not a well-known producer`);
+      }
+      if (c.consumer && !nameResolves(c.consumer, knownNames, 'consumer')) {
+        errors.push(`${where}: consumer '${c.consumer}' is not an agent/persona in registry.json and is not a well-known consumer`);
+      }
+
+      const schemaRef = c.output?.schema;
+      if (schemaRef) {
+        const outputSchemaPath = join(repoRoot, schemaRef);
+        if (!existsSync(outputSchemaPath)) {
+          errors.push(`${where}: output.schema '${schemaRef}' does not exist on disk`);
+        } else {
+          try { readJson(outputSchemaPath); }
+          catch (err) { errors.push(`${where}: output.schema '${schemaRef}' is not valid JSON: ${err.message}`); }
+        }
+      }
+    });
+  } else {
+    errors.push('contracts.json: contracts must be an array');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function nameResolves(name, knownNames, role) {
+  if (WELL_KNOWN_PRODUCERS.has(name) && role === 'producer') return true;
+  if (WELL_KNOWN_CONSUMERS.has(name) && role === 'consumer') return true;
+  if (knownNames.has(name)) return true;
+  // Persona registry stores names without the cx- prefix; contracts.json
+  // conventionally uses the cx-prefixed form. Normalize both directions.
+  const stripped = name.startsWith('cx-') ? name.slice(3) : `cx-${name}`;
+  return knownNames.has(stripped);
+}
+
+function collectAgentNames(registryPath) {
+  const names = new Set();
+  if (!existsSync(registryPath)) return names;
+  try {
+    const registry = readJson(registryPath);
+    if (registry.orchestrator?.name) names.add(registry.orchestrator.name);
+    if (registry.orchestrator?.displayName) names.add(registry.orchestrator.displayName);
+    for (const s of registry.specialists || []) {
+      if (s?.name) names.add(s.name);
+      if (s?.displayName) names.add(s.displayName);
+    }
+  } catch { /* fall through with whatever names we collected */ }
+  return names;
+}
+
+/**
+ * Look up a contract by producer/consumer pair (and optional id).
+ */
+export function findContract({ producer, consumer, id, contractsPath = CONTRACTS_PATH }) {
+  if (!existsSync(contractsPath)) return null;
+  let contracts;
+  try { contracts = readJson(contractsPath); } catch { return null; }
+  const list = contracts.contracts || [];
+  if (id) return list.find((c) => c.id === id) || null;
+  return list.find((c) => c.producer === producer && c.consumer === consumer) || null;
+}
+
+/**
+ * Validate a single artifact against its contract at handoff time.
+ *
+ * Returns one of:
+ *   { ok: true, contract }
+ *   { ok: false, status: 'BLOCKED_CONTRACT', errors[], contract }
+ *
+ * Enforcement defaults to the value of process.env.CONSTRUCT_CONTRACT_ENFORCEMENT
+ * ('warn' or 'block'), and may be overridden by the caller. In warn mode the
+ * result includes errors but ok stays true so a session is not blocked.
+ */
+export function validateHandoff({
+  producer,
+  consumer,
+  id,
+  artifact,
+  contractsPath = CONTRACTS_PATH,
+  repoRoot = REPO_ROOT,
+  enforcement = process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+}) {
+  const contract = findContract({ producer, consumer, id, contractsPath });
+  if (!contract) {
+    return enforcement === 'block'
+      ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`], contract: null }
+      : { ok: true, warnings: [`no contract found for ${producer}→${consumer}`], contract: null };
+  }
+
+  const errors = [];
+
+  // A handoff carries a producer's output, which is the consumer's input. The
+  // input contract is what the consumer expects to receive; check mustContain
+  // against that first. Output.schema validation only applies when the artifact
+  // declares the matching `type` (e.g. the consumer is forwarding its own
+  // produced artifact downstream).
+  const inputMustContain = contract.input?.mustContain || [];
+  for (const field of inputMustContain) {
+    if (!hasField(artifact, field)) {
+      errors.push(`artifact missing required field: ${field}`);
+    }
+  }
+
+  const outputType = contract.output?.type;
+  const schemaRef = contract.output?.schema;
+  if (schemaRef && outputType && artifact && artifact.type === outputType) {
+    const schemaPath = join(repoRoot, schemaRef);
+    if (!existsSync(schemaPath)) {
+      errors.push(`contract output.schema '${schemaRef}' does not exist on disk`);
+    } else {
+      const schema = readJson(schemaPath);
+      for (const field of schema.required || []) {
+        if (!hasField(artifact, field)) errors.push(`artifact missing schema-required field: ${field}`);
+      }
+    }
+  }
+
+  // Postcondition checks run against the artifact file on disk when the
+  // handoff envelope declares `artifactPath`. Resolved relative to repoRoot.
+  const declaredArtifactPath = artifact?.artifactPath || artifact?.output?.artifactPath;
+  if (declaredArtifactPath) {
+    const absPath = isAbsolutePath(declaredArtifactPath)
+      ? declaredArtifactPath
+      : join(repoRoot, declaredArtifactPath);
+    const pcErrors = validatePostconditions({ contract, artifactPath: absPath });
+    for (const e of pcErrors) errors.push(e);
+  }
+
+  if (errors.length === 0) return { ok: true, contract };
+  if (enforcement === 'block') return { ok: false, status: 'BLOCKED_CONTRACT', errors, contract };
+  return { ok: true, warnings: errors, contract };
+}
+
+function isAbsolutePath(p) {
+  return p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+}
+
+function hasField(obj, field) {
+  if (obj == null) return false;
+  if (typeof obj !== 'object') return false;
+  return Object.prototype.hasOwnProperty.call(obj, field) && obj[field] != null && obj[field] !== '';
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseArtifactFrontmatter(text) {
+  const m = text.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: text };
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (key) fm[key] = rawValue.replace(/^["']|["']$/g, '');
+  }
+  return { frontmatter: fm, body: text.slice(m[0].length) };
+}
+
+function hasSection(body, sectionTitle) {
+  const target = sectionTitle.trim().toLowerCase();
+  const headingRe = /^#{1,6}\s+(.+)$/gm;
+  let m;
+  while ((m = headingRe.exec(body))) {
+    if (m[1].trim().toLowerCase() === target) return true;
+  }
+  return false;
+}
+
+function claimsHaveCitations(body) {
+  const lines = body.split('\n');
+  const offenders = [];
+  let inFence = false;
+  let inTable = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    inTable = /^\s*\|.*\|\s*$/.test(line);
+    if (inTable) continue;
+    if (/\b\d{1,3}\s*%/.test(line) || /\b\d{2,}x\b/i.test(line)) {
+      const window = [lines[i - 1] || '', line, lines[i + 1] || ''].join('\n');
+      if (!/\[source:|\bhttps?:\/\/|\[\^\d+\]/i.test(window)) {
+        offenders.push({ line: i + 1, snippet: line.trim().slice(0, 80) });
+      }
+    }
+  }
+  return offenders;
+}
+
+/**
+ * Run structured postcondition checks against a handoff's output artifact on
+ * disk. Postconditions can be strings (descriptive, ignored here) or objects
+ * with { id, check, field?, section? }. Returns an array of error strings.
+ */
+export function validatePostconditions({ contract, artifactPath }) {
+  if (!contract?.postconditions?.length) return [];
+  if (!artifactPath || !existsSync(artifactPath)) {
+    const structured = contract.postconditions.filter((p) => typeof p === 'object');
+    if (structured.length === 0) return [];
+    return [`postcondition checks declared but artifact not found on disk: ${artifactPath}`];
+  }
+  const text = readFileSync(artifactPath, 'utf8');
+  const { frontmatter, body } = parseArtifactFrontmatter(text);
+  const errors = [];
+  for (const pc of contract.postconditions) {
+    if (typeof pc !== 'object') continue;
+    const tag = pc.id || pc.check;
+    switch (pc.check) {
+      case 'artifact-has-frontmatter-field': {
+        if (!pc.field) {
+          errors.push(`[${tag}] postcondition missing 'field' for artifact-has-frontmatter-field`);
+          break;
+        }
+        if (!frontmatter[pc.field]) {
+          errors.push(`[${tag}] artifact missing frontmatter field: ${pc.field}`);
+        }
+        break;
+      }
+      case 'artifact-has-section': {
+        if (!pc.section) {
+          errors.push(`[${tag}] postcondition missing 'section' for artifact-has-section`);
+          break;
+        }
+        if (!hasSection(body, pc.section)) {
+          errors.push(`[${tag}] artifact missing required section: "${pc.section}"`);
+        }
+        break;
+      }
+      case 'artifact-claims-cited': {
+        const offenders = claimsHaveCitations(body);
+        for (const o of offenders) {
+          errors.push(`[${tag}] uncited numeric claim at line ${o.line}: ${o.snippet}`);
+        }
+        break;
+      }
+      default:
+        errors.push(`[${tag}] unknown postcondition check: ${pc.check}`);
+    }
+  }
+  return errors;
+}
+
+// Minimum evidence required: either a PR reference (#N or PR #N) or a file
+// reference of the form `path:<line>` or `file:<line>` where line is a number.
+const CLOSE_REASON_PR_PATTERN = /#\d+/;
+const CLOSE_REASON_FILE_PATTERN = /[\w./\\-]+(?:\.(?:mjs|ts|js|tsx|jsx|py|go|rs|java|md|json|yml|yaml)):[0-9]+/i;
+const CLOSE_REASON_MIN_LENGTH = 20;
+
+/**
+ * Validate a beads close reason for evidence quality.
+ *
+ * Returns { ok: boolean, message: string|null }. On failure, `message` describes
+ * what is missing. The caller decides whether to warn or block based on
+ * CONSTRUCT_BEADS_HYGIENE (warn | block). Default behavior is warn.
+ *
+ * A passing reason must:
+ *   - Be at least 20 characters.
+ *   - Contain a PR reference (#N) OR a file:line reference (path.mjs:42).
+ */
+export function validateBeadsCloseReason(reason) {
+  if (!reason || typeof reason !== 'string') {
+    return { ok: false, message: 'Close reason is empty. Add evidence: PR reference (#N) or file:line reference.' };
+  }
+  const trimmed = reason.trim();
+  if (trimmed.length < CLOSE_REASON_MIN_LENGTH) {
+    return { ok: false, message: `Close reason too short (${trimmed.length} chars). Minimum: ${CLOSE_REASON_MIN_LENGTH}. Add evidence.` };
+  }
+  const hasPr = CLOSE_REASON_PR_PATTERN.test(trimmed);
+  const hasFile = CLOSE_REASON_FILE_PATTERN.test(trimmed);
+  if (!hasPr && !hasFile) {
+    return {
+      ok: false,
+      message: `Close reason lacks evidence. Include a PR reference (#N) or a file:line reference (e.g. lib/foo.mjs:42). Got: "${trimmed.slice(0, 80)}"`,
+    };
+  }
+  return { ok: true, message: null };
+}
+
+/**
+ * Apply the beads close-reason policy: warn or block based on
+ * CONSTRUCT_BEADS_HYGIENE env var. Returns exit code (0 = ok, 1 = block).
+ */
+export function applyBeadsHygienePolicy(reason, { stderr = process.stderr } = {}) {
+  const { ok, message } = validateBeadsCloseReason(reason);
+  if (ok) return 0;
+
+  const mode = (process.env.CONSTRUCT_BEADS_HYGIENE || 'warn').toLowerCase();
+  const prefix = mode === 'block' ? '[beads-hygiene] BLOCK' : '[beads-hygiene] WARN';
+  stderr.write(`${prefix}: ${message}\n`);
+  return mode === 'block' ? 1 : 0;
+}