@geraldmaron/construct 1.0.14 → 1.0.15

package/lib/sync/skill-frontmatter.mjs

@@ -2,38 +2,130 @@
  * lib/sync/skill-frontmatter.mjs — Build Anthropic Agent Skills frontmatter
  * for SKILL.md files emitted by sync-specialists.
  *
- * Anthropic Skills require YAML frontmatter with at minimum `name` and
- * `description`. The description gates skill selection — without it, the
- * loader silently skips the file (the user-reported bug: 141 files dropped).
- * Source Construct skills carry an HTML comment header with the description;
- * extractSkillDescription pulls it out.
+ * Source skills carry YAML frontmatter with at minimum `name` + `description`
+ * (Anthropic spec). For role files, extra construct-internal keys (role,
+ * applies_to, inherits, version, profiles, cap) live in the same block; sync
+ * drops those at emit time so only spec-compliant keys ship in SKILL.md.
  *
- * Also exports a conservative stripLeadingFrontmatter helper so we never
- * emit double-frontmatter when the source body already has its own block.
+ * Backwards-compat path: source files missing YAML frontmatter fall through
+ * to HTML-comment preamble extraction, then first body paragraph. Keeps
+ * unmigrated files working during transition; the validator warns until
+ * they migrate.
+ *
+ * Zero-dep posture: runs from isolated environments (cpSync'd tmpdirs
+ * without node_modules), so the YAML reader/emitter stays in-tree. Surface
+ * is small — read flat top-level keys + simple inline arrays; write 2 keys
+ * (name, description). For richer YAML, the migration script and validator
+ * use js-yaml.
  */
 
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 const HTML_COMMENT_RE = /^<!--([\s\S]*?)-->/;
-// Matches the source skill comment header shape: `skills/path/foo.md (Title)
-// Use when X.\n...rest of comment...`. Group 1 captures the optional title,
-// group 2 captures all subsequent prose inside the comment. No /m flag — `$`
-// matches end of input, not end of line, so multi-line "Use when..." prose
-// is captured in full and firstSentence() picks the first terminator.
-
 const SOURCE_HEADER_RE = /^skills\/[\w./-]+\s*(?:\(([^)]+)\))?\s*([\s\S]*?)$/;
 
-// Anthropic Skills cap descriptions at 1024 chars; this cap is tighter so
-// the YAML stays readable in `construct skills list` output too.
-const DESCRIPTION_MAX = 240;
+const DESCRIPTION_MAX = 1024;
+
+// In-tree minimal YAML parser. Handles the subset Construct skill frontmatter
+// uses: flat scalar keys, double/single-quoted or unquoted strings, simple
+// inline arrays ([a, b, c]), and block-style arrays (- item per line).
+// Unparseable input returns null; callers fall back to extraction.
+
+function parseFlatYaml(text) {
+  if (!text || typeof text !== 'string') return null;
+  const lines = text.split('\n');
+  const out = {};
+  let pendingArrayKey = null;
+  try {
+    for (const raw of lines) {
+      const line = raw.replace(/\r$/, '');
+      if (!line.trim() || line.trim().startsWith('#')) continue;
+      if (pendingArrayKey && /^\s+-\s+/.test(line)) {
+        out[pendingArrayKey].push(parseScalar(line.replace(/^\s+-\s+/, '')));
+        continue;
+      }
+      pendingArrayKey = null;
+      const m = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+      if (!m) continue;
+      const key = m[1];
+      const rawValue = m[2];
+      if (rawValue === '' || rawValue === undefined) {
+        out[key] = [];
+        pendingArrayKey = key;
+        continue;
+      }
+      if (rawValue.startsWith('[') && rawValue.endsWith(']')) {
+        const inner = rawValue.slice(1, -1).trim();
+        out[key] = inner === '' ? [] : inner.split(',').map((s) => parseScalar(s.trim()));
+        continue;
+      }
+      out[key] = parseScalar(rawValue);
+    }
+  } catch (err) {
+    if (err instanceof YamlError) return null;
+    throw err;
+  }
+  return out;
+}
+
+class YamlError extends Error {}
+
+function parseScalar(s) {
+  const trimmed = s.trim();
+  if (trimmed === '' || trimmed === 'null' || trimmed === '~') return null;
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (/^-?\d+$/.test(trimmed)) return Number(trimmed);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return Number(trimmed);
+  if (trimmed.startsWith('"')) {
+    if (!trimmed.endsWith('"') || trimmed.length < 2) throw new YamlError('unclosed double quote');
+    return trimmed.slice(1, -1).replace(/\\"/g, '"');
+  }
+  if (trimmed.startsWith("'")) {
+    if (!trimmed.endsWith("'") || trimmed.length < 2) throw new YamlError('unclosed single quote');
+    return trimmed.slice(1, -1).replace(/\\'/g, "'");
+  }
+  return trimmed;
+}
+
+function emitScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  const s = String(value);
+  if (/[:"'\n#&*!|>%@`]|^[-?]/.test(s) || s.length === 0) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+export function readSkillFrontmatter(content) {
+  if (!content) return null;
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  return parseFlatYaml(match[1]);
+}
 
 export function buildSkillFrontmatter(name, sourceContent) {
-  const skillName = String(name).replace(/\//g, '.');
-  const description = extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`;
-  const safeDescription = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'");
-  return `---\nname: ${skillName}\ndescription: "${safeDescription}"\n---\n`;
+  const fromSource = readSkillFrontmatter(sourceContent);
+  const skillName = (fromSource?.name && typeof fromSource.name === 'string')
+    ? fromSource.name
+    : kebabFromPath(name);
+  const description = (fromSource?.description && typeof fromSource.description === 'string')
+    ? fromSource.description
+    : (extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`);
+  const safe = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'").trim();
+  return `---\nname: ${emitScalar(skillName)}\ndescription: ${emitScalar(safe)}\n---\n`;
+}
+
+function kebabFromPath(name) {
+  return String(name).replace(/[/.]/g, '-').toLowerCase();
 }
 
 export function extractSkillDescription(content) {
   if (!content) return null;
+  const fromYaml = readSkillFrontmatter(content);
+  if (fromYaml?.description && typeof fromYaml.description === 'string') {
+    return fromYaml.description;
+  }
   const commentMatch = content.match(HTML_COMMENT_RE);
   if (commentMatch) {
     const inner = commentMatch[1].trim();
@@ -45,7 +137,7 @@ export function extractSkillDescription(content) {
     const lines = inner.split('\n').map((l) => l.trim()).filter(Boolean);
     if (lines.length >= 2) return firstSentence(lines.slice(1).join(' '));
   }
-  const body = content.replace(HTML_COMMENT_RE, '').trim();
+  const body = content.replace(FRONTMATTER_RE, '').replace(HTML_COMMENT_RE, '').trim();
   const paragraphs = body.split(/\n\s*\n/);
   for (const p of paragraphs) {
     const trimmed = p.trim();

package/lib/tracking-surfaces.mjs

@@ -26,6 +26,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { join } from 'node:path';
 
 import { extractBeadsFromPlan, syncPlanWithBeads } from './beads-automation.mjs';
+import { assertBeadId } from './beads-client.mjs';
 import { buildPlanTemplate } from './project-init-shared.mjs';
 
 const CONTEXT_RECENT_DAYS = 30;
@@ -191,6 +192,7 @@ export async function closeBeadsFromPrRefs({ prNumber, mergeCommitSha = '', cwd
     : `Merged via PR #${prNumber}`;
 
   for (const id of beadIds) {
+    try { assertBeadId(id); } catch (err) { errors.push({ id, reason: 'invalid-bead-id', detail: err.message }); continue; }
     const status = readBeadStatus(cwd, id);
     if (status === 'closed') { skipped.push(id); continue; }
     if (status === null) { errors.push({ id, reason: 'bd-show-failed' }); continue; }

package/lib/validators/skills.mjs

@@ -1,62 +1,71 @@
 /**
  * lib/validators/skills.mjs — Validate the structure of skill files.
  *
- * Skills are markdown files under `skills/` (and any merged plugin or project
- * skill paths) that follow this convention:
+ * After the YAML-frontmatter migration, every skill file under `skills/` has:
  *
- *   <!--
- *   skills/<domain>/<name>.md — <Title> — <one-line description>
- *   ...
- *   -->
+ *   ---
+ *   name: <kebab-case>
+ *   description: "<≤1024 chars, includes a 'use when' trigger>"
+ *   [role/applies_to/inherits/version/profiles/cap for role files]
+ *   ---
  *   # <Title>
- *
- *   Use this skill when <triggering condition>.
- *   ...
+ *   Use when: <trigger condition>
+ *   <body>
  *
  * The validator splits findings into hard errors (block the build) and soft
  * warnings (surfaced by `construct doctor` without failing it):
  *
  *   Hard errors:
- *     - missing H1 title
+ *     - frontmatter missing or not parseable as YAML
+ *     - name missing, > 64 chars, fails ^[a-z0-9][a-z0-9-]*$, or contains
+ *       reserved tokens (anthropic, claude)
+ *     - description missing, empty, > 1024 chars, contains XML/HTML tags,
+ *       or missing a "use when" trigger clause
+ *     - missing H1 title (in body)
  *     - title over 80 chars
  *     - duplicate relative paths across roots
  *     - unreadable file
  *
  *   Soft warnings:
- *     - opener is missing or doesn't match a recognised "Use this skill
- *       when/to/for ..." form (skills with non-trigger openers still load,
- *       but they're harder for routing to surface)
- *     - opener over 240 chars
- *
- * Hard checks prevent broken file structure; soft checks surface drift from
- * authoring conventions without blocking authors who legitimately diverge.
+ *     - body opener missing or doesn't match a "Use this skill when/to/for ..."
+ *       form (YAML description is now primary; body opener is a behavioral hint)
+ *     - body opener over 240 chars
  */
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import yaml from 'js-yaml';
 
-const DESCRIPTION_MAX_CHARS = 240;
+const DESCRIPTION_MAX = 1024;
+const NAME_MAX = 64;
 const TITLE_MAX_CHARS = 80;
+const BODY_OPENER_MAX = 240;
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 
-// Accept any of the conventional skill-trigger openers actually in use across
-// the corpus: "Use this skill when/to/for", "Use when:", "Use this when",
-// "Trigger:", or a leading "When ..." that signals a triggering condition.
 const TRIGGER_PATTERN = /^(?:use\s+(?:this\s+(?:skill\s+)?)?(?:when|to|for|if)\b|when\s+to\s+use\b|trigger\s*:|use\s+when\s*:)/i;
 
 function* walk(root) {
-  const entries = readdirSync(root, { withFileTypes: true });
-  for (const entry of entries) {
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
     const full = path.join(root, entry.name);
-    if (entry.isDirectory()) {
-      yield* walk(full);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      yield full;
-    }
+    if (entry.isDirectory()) yield* walk(full);
+    else if (entry.isFile() && entry.name.endsWith('.md')) yield full;
+  }
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { frontmatter: null, body: content };
+  try {
+    const parsed = yaml.load(match[1]) || {};
+    return { frontmatter: parsed, body: content.slice(match[0].length) };
+  } catch (err) {
+    return { frontmatter: null, body: content.slice(match[0].length), yamlError: err.message };
   }
 }
 
-function extractTitleAndOpener(text) {
-  const lines = text.split(/\r?\n/);
+function extractTitleAndOpener(body) {
+  const lines = body.split(/\r?\n/);
   let title = null;
   let opener = null;
   let inBody = false;
@@ -64,11 +73,7 @@ function extractTitleAndOpener(text) {
     const line = lines[i].trim();
     if (!title) {
       const m = line.match(/^#\s+(.+?)\s*$/);
-      if (m) {
-        title = m[1];
-        inBody = true;
-        continue;
-      }
+      if (m) { title = m[1]; inBody = true; continue; }
     } else if (inBody && line && !line.startsWith('#') && !line.startsWith('<!--')) {
       opener = line;
       break;
@@ -77,23 +82,31 @@ function extractTitleAndOpener(text) {
   return { title, opener };
 }
 
-/**
- * Validate every skill file under one or more directories.
- *
- * @param {string[]|string} roots — directories to walk recursively
- * @returns {{
- *   valid: boolean,
- *   errors: string[],
- *   warnings: string[],
- *   skills: Array<{ path: string, title: string|null, opener: string|null }>,
- * }}
- */
+function validateName(name) {
+  if (!name) return 'frontmatter.name is missing';
+  if (typeof name !== 'string') return `frontmatter.name must be a string (got ${typeof name})`;
+  if (!NAME_RE.test(name)) return `frontmatter.name "${name}" must match ${NAME_RE}`;
+  if (name.length > NAME_MAX) return `frontmatter.name "${name}" exceeds ${NAME_MAX} chars`;
+  if (/\banthropic\b|\bclaude\b/.test(name)) return `frontmatter.name "${name}" contains reserved token`;
+  return null;
+}
+
+function validateDescription(description) {
+  if (!description) return 'frontmatter.description is missing or empty';
+  if (typeof description !== 'string') return `frontmatter.description must be a string (got ${typeof description})`;
+  if (description.length > DESCRIPTION_MAX) return `frontmatter.description ${description.length} > ${DESCRIPTION_MAX} chars`;
+  if (/<[A-Za-z][^>]*>/.test(description)) return 'frontmatter.description contains XML/HTML tags';
+  if (!/use\s+when|use\s+this/i.test(description)) return 'frontmatter.description missing "use when" trigger clause';
+  return null;
+}
+
 export function validateSkills(roots) {
   const dirs = Array.isArray(roots) ? roots : [roots];
   const errors = [];
   const warnings = [];
   const skills = [];
   const seenRelative = new Map();
+  const seenNames = new Map();
 
   for (const dir of dirs) {
     let exists = false;
@@ -113,12 +126,31 @@ export function validateSkills(roots) {
 
       let raw;
       try { raw = readFileSync(filePath, 'utf8'); }
-      catch (err) {
-        errors.push(`${rel}: cannot read (${err.message})`);
+      catch (err) { errors.push(`${rel}: cannot read (${err.message})`); continue; }
+
+      const { frontmatter, body, yamlError } = parseFrontmatter(raw);
+
+      if (yamlError) {
+        errors.push(`${rel}: frontmatter YAML parse error — ${yamlError}`);
         continue;
       }
+      if (!frontmatter) {
+        errors.push(`${rel}: missing YAML frontmatter block (---name/description---)`);
+        continue;
+      }
+
+      const nameErr = validateName(frontmatter.name);
+      if (nameErr) errors.push(`${rel}: ${nameErr}`);
+      else {
+        const dupName = seenNames.get(frontmatter.name);
+        if (dupName) errors.push(`${rel}: duplicate frontmatter.name "${frontmatter.name}" (also in ${dupName})`);
+        else seenNames.set(frontmatter.name, rel);
+      }
+
+      const descErr = validateDescription(frontmatter.description);
+      if (descErr) errors.push(`${rel}: ${descErr}`);
 
-      const { title, opener } = extractTitleAndOpener(raw);
+      const { title, opener } = extractTitleAndOpener(body);
 
       if (!title) {
         errors.push(`${rel}: missing H1 title (e.g. "# Skill Name")`);
@@ -127,14 +159,14 @@ export function validateSkills(roots) {
       }
 
       if (!opener) {
-        warnings.push(`${rel}: no trigger opener after the H1 title — routing will have nothing to match`);
+        warnings.push(`${rel}: no trigger opener in body after the H1 — YAML description still primary, but body opener helps in-task behavior`);
       } else if (!TRIGGER_PATTERN.test(opener)) {
-        warnings.push(`${rel}: opener should start with "Use this skill when/to/for ..." (got "${opener.slice(0, 60)}…")`);
-      } else if (opener.length > DESCRIPTION_MAX_CHARS) {
-        warnings.push(`${rel}: opener exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${opener.length})`);
+        warnings.push(`${rel}: body opener should start with "Use this skill when/to/for ..." (got "${opener.slice(0, 60)}…")`);
+      } else if (opener.length > BODY_OPENER_MAX) {
+        warnings.push(`${rel}: body opener exceeds ${BODY_OPENER_MAX} chars (got ${opener.length})`);
       }
 
-      skills.push({ path: rel, title, opener });
+      skills.push({ path: rel, name: frontmatter.name, description: frontmatter.description, title, opener });
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -57,7 +57,6 @@
     "lint:contracts": "node ./bin/construct lint:contracts",
     "lint:agents": "node ./bin/construct lint:agents",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
-    "lint:prose": "node scripts/lint-prose.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
@@ -73,16 +72,17 @@
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@xenova/transformers": "^2.0.1",
+    "js-yaml": "^4.2.0",
     "node-webvtt": "^1.9.3",
     "postgres": "^3.4.9"
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/core": "^1.25.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
     "@opentelemetry/resources": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0",
-    "@opentelemetry/core": "^1.25.0"
+    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0"
   },
   "overrides": {
     "express-rate-limit": "8.5.1",

package/personas/construct.md

@@ -1,10 +1,7 @@
-<!--
-personas/construct.md. Construct persona prompt.
-
-Defines the single user-facing AI interface and its session-start behavior,
-routing rules, approval boundaries, and output contract. Loaded by sync-specialists
-and emitted to every supported platform.
--->
+---
+name: construct
+description: Construct persona prompt.
+---
 You are Construct. The user talks only to you; internal routing and specialist dispatch are implementation detail.
 
 **Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.

package/platforms/claude/settings.template.json

@@ -151,7 +151,7 @@
           }
         ],
         "id": "post:edit:comment-lint",
-        "description": "Block edits that violate comment policy (banned patterns, missing required header). Bypass: CONSTRUCT_SKIP_COMMENT_LINT=1"
+        "description": "Block edits that violate comment policy (banned patterns, missing required header). No bypass — repair the policy if it fires wrong."
       },
       {
         "matcher": "Write|Edit|MultiEdit",

package/rules/common/beads-hygiene.md

@@ -1,12 +1,6 @@
-<!--
-rules/common/beads-hygiene.md: Beads issue tracker hygiene contract.
-
-Beads is the system of record for durable work in this project. Status drifts
-when issues are not updated alongside the code, so every agent and persona
-operating in Construct treats hygiene as part of the work, not as cleanup.
-Loaded by AGENTS.md, CLAUDE.md, the construct persona, and the engineer /
-operator / planner role overlays.
--->
+---
+description: Beads issue tracker hygiene contract.
+---
 # Beads Hygiene: Project Contract
 
 Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent (human or AI, on any platform) is responsible for keeping the tracker honest.

package/rules/common/code-review.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/code-review.md: when and how to conduct code reviews.
-
-Defines mandatory review triggers, severity levels, approval criteria,
-and references coding-style.md and security.md for checklists.
--->
+---
+description: when and how to conduct code reviews.
+---
 # Code Review Standards
 
 ## When to Review

package/rules/common/coding-style.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/coding-style.md: language-agnostic coding standards.
-
-Covers immutability, core principles (KISS/DRY/YAGNI), file organization,
-error handling, input validation, naming conventions, and quality checklist.
--->
+---
+description: language-agnostic coding standards.
+---
 # Coding Style
 
 ## Immutability (CRITICAL)

package/rules/common/comments.md

@@ -1,10 +1,6 @@
-<!--
-rules/common/comments.md: Construct comment convention for JS/TS/MJS source files.
-
-Defines the two allowed comment forms (file header, section context block) and
-what is never allowed (inline narration, trailing comments, mid-function notes).
-Enforced by lib/hooks/comment-lint.mjs and tests/hooks-budget.test.mjs.
--->
+---
+description: Construct comment convention for JS/TS/MJS source files.
+---
 # Comment Convention
 
 Two forms are allowed. Everything else is deleted.

package/rules/common/commit-approval.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/commit-approval.md: conversational approval rule for mutating git operations.
-
-Behavioral rule, not a hook. The agent asks and waits for a yes; the user
-replies in chat. Infrastructure stays out of the way.
--->
+---
+description: conversational approval rule for mutating git operations.
+---
 # Commit Approval
 
 Construct does not commit, push, or merge without the user explicitly saying yes in the current conversation.

package/rules/common/cx-agent-routing.md

@@ -1,10 +1,6 @@
-<!--
-rules/common/cx-agent-routing.md: auto-trigger routing rules for cx-* specialist agents.
-
-Defines when to route directly to a cx-* specialist vs through Construct orchestration.
-Covers intent-based routing table, complexity gate, and routing rules.
-Loaded by rule-loading systems that look for cx-agent-routing in the rules hierarchy.
--->
+---
+description: auto-trigger routing rules for cx-* specialist agents.
+---
 # cx-* Agent Routing: Auto-trigger Rules
 
 When a request matches the trigger patterns below, automatically route to the corresponding cx-* specialist or persona before responding.

package/rules/common/cx-skill-routing.md

@@ -1,6 +1,6 @@
-<!--
-rules/common/cx-skill-routing.md: Redirect to canonical skill routing table.
--->
+---
+description: Redirect to canonical skill routing table.
+---
 # cx-* Skill Routing
 
 > **Canonical file:** [`skills/routing.md`](../../skills/routing.md)

package/rules/common/doc-ownership.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/doc-ownership.md: which specialist owns which document type.
-
-Prevents the orchestrator (or any general persona) from authoring specialist
-documents directly. Routing authorship to the owning role is how research,
-framing, and domain scrutiny actually fire: writing a PRD without the
-product manager bypasses those checks entirely.
--->
+---
+description: which specialist owns which document type.
+---
 # Document Ownership
 
 A document type names a body of work. That body of work has an owner. The orchestrator routes; it does not author.

package/rules/common/efficiency.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/efficiency.md: session context and tool-use efficiency standards.
-
-Applies to all agents operating in a Construct session. Violations compound context
-cost and reduce throughput. These rules are enforced by read-tracker.mjs and surfaced
-in the session-start efficiency digest.
--->
-
+---
+description: session context and tool-use efficiency standards.
+---
 # Session Efficiency
 
 ## Read discipline

package/rules/common/framing.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/framing.md: how to frame a problem before acting on it.
-
-Establishes the hard separation between execution artifacts (tickets, chat
-transcripts, existing docs) and sources of truth (the underlying problem).
-Applies to every specialist working on architecture, documentation, research,
-product, or strategy work. Read before scaffolding anything.
--->
+---
+description: how to frame a problem before acting on it.
+---
 # Framing Policy
 
 Most agent failures on ambiguous work trace to a single mistake: anchoring on the most concrete input available (usually a ticket or a prior doc) and building the output around its structure instead of around the actual problem.

package/rules/common/git-workflow.md

@@ -1,8 +1,6 @@
-<!--
-rules/common/git-workflow.md: commit message format and PR workflow.
-
-Defines conventional commit types and pull request creation steps.
--->
+---
+description: commit message format and PR workflow.
+---
 # Git Workflow
 
 ## Commit Message Format

package/rules/common/no-fabrication.md

@@ -1,14 +1,6 @@
-<!--
-rules/common/no-fabrication.md: canonical anti-fabrication policy for Construct.
-
-Defines the trust contract between operators and the system: outputs stick to
-source, gaps stay visible, and confidence reflects evidence. Applies to every
-specialist, every artifact, and every summary — intake processing, document
-evaluation, knowledge writing, plan drafting, review verdicts, handoffs.
-
-Sibling rules: research.md (evidence hierarchy), framing.md (execution
-artifacts are not sources), comments.md (banned voice patterns).
--->
+---
+description: canonical anti-fabrication policy for Construct.
+---
 # No-Fabrication Policy
 
 Fabrication is the single largest threat to trust in an agent system. A persona that invents a customer quote, sharpens a vague signal into a confident assertion, or papers over a gap with plausible-sounding prose corrupts every artifact downstream. This rule applies to **every output** Construct produces: intake summaries, classification rationales, PRDs, ADRs, RFCs, knowledge notes, handoffs, review verdicts, plan entries, beads issues, MCP tool responses, dashboard text.
@@ -61,7 +53,7 @@ Fabrication is the single largest threat to trust in an agent system. A persona
 ## Enforcement
 
 - `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
-- `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation when `CONSTRUCT_CONTRACT_ENFORCEMENT=block`.
+- `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation; binary postconditions in `lib/specialists/postconditions.mjs` block rubber-stamp reviews, post-hoc threat models, symptom-only fixes, stale-doc PRs, and post-hoc accessibility. Enforcement is hard-default `block`.
 - `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
 
 ## Bypass